Feat/solovo

.github/workflows/frontend-ci.yml

@@ -58,6 +58,10 @@ jobs:
         if: steps.pkg.outputs.has_test == 'true'
         run: npm test
 
+      - name: Run accessibility (axe-core) tests
+        if: steps.pkg.outputs.has_test == 'true'
+        run: npm run test:a11y:ci
+
       - name: Run unit tests with coverage
         if: steps.pkg.outputs.has_test == 'true'
         run: npm run test:coverage
@@ -124,4 +128,4 @@ jobs:
         with:
           name: playwright-report
           path: frontend/playwright-report/
-          retention-days: 7
+          retention-days: 7

bridgelet-product-audit/checklists/README.md

@@ -0,0 +1,14 @@
+# Checklists Index
+
+This directory contains structured checklists for product audits, security reviews, and maintenance tasks. All checklists follow the literal-checkbox format (`- [ ] Item`) to maintain consistency across the repository.
+
+## One-time (Onboarding/Readiness) Checklists
+Use these during initial setup, before major releases, or when onboarding new infrastructure:
+
+- **[LocalStorage Data Exposure Review Checklist](localstorage-data-exposure-checklist.md)** — Use this when implementing or modifying wallet persistence to ensure no sensitive data is stored in localStorage, and all client-side storage usage is accounted for and secure.
+- **[Wallet Connection Review Checklist](wallet-connection-review-checklist.md)** — Use this before a major release to verify all three wallet connection types (Freighter, LOBSTR, generated) work as documented, with proper error handling and cross-consistency across the codebase.
+
+## Recurring (Periodic Review) Checklists
+Use these on a regular cadence to maintain product health and documentation accuracy:
+
+- **[Documentation Freshness Checklist](docs-freshness-checklist.md)** — Use this bi-annually (June and December) to audit all documentation in the `docs/` directory, verify MDX/PDF file pairs are in sync, and ensure all content remains accurate and up-to-date.

bridgelet-product-audit/glossary/README.md

@@ -0,0 +1,34 @@
+# Glossary Index
+
+**Important:** The canonical short-definition reference for all Bridgelet terms remains `docs/GLOSSARY.md`. This subfolder contains expanded, detailed entries that elaborate on those core definitions with implementation specifics, context, and technical deep dives.
+
+Entries are grouped thematically for easier navigation:
+
+## Wallet Connection Terms
+Deep dives on wallet types, persistence, and connection logic:
+
+- **[Wallet Connection Types](wallet-connection-types.md)** — Expands on the three `WalletType` values (freighter, lobstr, generated) in `frontend/lib/wallet.ts`, explaining their actual implementation differences and limitations.
+- **[Connected Wallet Persistence](connected-wallet-persistence.md)** — Details how wallet data is stored in localStorage, what fields are persisted (only publicKey and type, no secret material), and how corrupted values are handled.
+- **[Freighter vs LOBSTR vs Generated Tradeoffs](freighter-vs-lobstr-vs-generated-tradeoffs.md)** — Compares the security, UX, and implementation tradeoffs between the three supported wallet connection approaches.
+- **[Ephemeral Account in the Product Narrative](ephemeral-account-in-the-product-narrative.md)** — Explains the role of client-side generated wallets in the product's overall account model and user journey.
+- **[Custodial Model in Practice](custodial-model-in-practice.md)** — Details how Bridgelet's custody model works for each wallet type, including key responsibility and recovery implications.
+- **[Sender vs Recipient Auth Models](sender-vs-recipient-auth-models.md)** — Distinguishes between the authentication requirements for senders (who connect wallets to create claims) and recipients (who claim funds).
+
+## Claim Flow Terms
+Detailed explanations of the claim lifecycle and related concepts:
+
+- **[Claim Token and Claim URL](claim-token-and-claim-url.md)** — Expands on the core glossary definitions with implementation details: how the token is used as a route segment in Next.js, and the structure of the claim UI route.
+
+## Repository Structure Terms
+Clarifications on repository organization, tooling, and documentation standards:
+
+- **[Docs MDX vs PDF Pairs](docs-mdx-vs-pdf-pairs.md)** — Lists which documentation files exist as editable MDX sources with PDF exports vs. PDF-only files, and explains the maintenance implications of each.
+- **[Branch Protection Reference](branch-protection-reference.md)** — Summarizes the main branch protection rules from `.github/BRANCH_PROTECTION.md` for quick reference during PR reviews.
+- **[Test Result Directories](test-result-directories.md)** — Clarifies the difference between the singular `frontend/test-result/` (committed test source files) and plural `frontend/test-results/` (generated Playwright output) directories.
+- **[Lighthouse CI Config](lighthouse-ci-config.md)** — Explains the repository's Lighthouse CI setup and what metrics it tracks for frontend performance and accessibility.
+- **[Mobile App Services Logger](mobile-app-services-logger.md)** — Details the only populated service module in the mobile app's `mobile/services/` directory, including its log level filtering and exported interface.
+- **[Analytics Spec Overview](analytics-spec-overview.md)** — Expands on the analytics event specification, including how events are categorized and what each event is intended to track.
+- **[FRD UI/UX Overview](frd-ui-ux-overview.md)** — References the Functional Requirements Document that outlines the original UI/UX specifications for the product.
+- **[Multi-Chain Evaluation Summary](multi-chain-evaluation-summary.md)** — Summarizes past evaluations of adding support for blockchains beyond Stellar, including the findings and decisions made.
+- **[Org Integration API Key Model](org-integration-api-key-model.md)** — Explains the API key authentication model for organizational integrations with the Bridgelet platform.
+- **[Governance and Roadmap Cross-Reference](governance-and-roadmap-cross-reference.md)** — Details how the project's governance process interacts with product roadmap planning and prioritization.

bridgelet-product-audit/postmortems/mobile-services-logger-only-populated-directory.md

@@ -0,0 +1,22 @@
+# Postmortem: Mobile App `services/` Directory Only Contains Logger Implementation
+
+## Factual Finding
+
+During a repository structure audit, it was discovered that the mobile application's `mobile/services/` directory — which is architected to contain modular service modules for core application functionality — only has one populated subdirectory: **logger**. All other anticipated service modules (wallet integration, API client, blockchain interaction, authentication, etc.) are either missing entirely or exist only as empty placeholder directories.
+
+## Context & Maturity Assessment
+
+This observation has significant implications for the mobile app's current development maturity relative to the web frontend:
+
+1. **Frontend has comprehensive service modularity**: The web frontend (`frontend/`) maintains a robust set of modular libaries and services for wallet connections, API interactions, state management, and blockchain operations — all properly factored into maintainable, single-responsibility modules.
+
+2. **Mobile lacks equivalent service layer abstractions**: The absence of wallet, API-client, and other service modules in `mobile/services/` indicates the mobile app has not yet undergone the same architectural refactoring and modularization as the web frontend. Features that are properly separated in the web codebase may still be monolithically implemented in the mobile codebase, or have not been implemented at all.
+
+3. **Logger as a starting point**: The existence of only the logger service suggests the mobile team prioritized foundational observability tooling first, but has not yet extended that modular architectural pattern to other critical domains like wallet connectivity, which would be necessary to achieve feature parity with the web app.
+
+## Recommendation for Future Review
+
+This structural gap should be revisited as part of the broader parity review outlined in `mobile-app-parity-checklist.md`. The review should specifically:
+- Inventory which service modules are still missing from the mobile app's `services/` directory
+- Create implementation milestones for bringing the mobile app's service architecture in line with the web frontend's modular pattern
+- Track progress on this architectural debt as part of the mobile app's development roadmap to ensure it does not impede future feature development or maintainability.

bridgelet-product-audit/runbooks/README.md

@@ -0,0 +1,29 @@
+# Runbooks Index
+
+This directory contains operational runbooks for incident response, diagnostics, and maintenance procedures. Runbooks describe current behavior and workarounds, not proposed code changes. They are designed to be quickly scannable during live support escalations.
+
+## User Support Triage
+Use these to diagnose and resolve user-reported issues:
+
+- **[Diagnose Wallet Connection Failure](diagnose-wallet-connection-failure.md)** — Use when a user reports they cannot connect their Freighter wallet; walks through checking extension installation, popup blockers, and cross-browser issues.
+- **[Diagnose LOBSTR Connection Confusion](diagnose-lobstr-connection-confusion.md)** — Use when a user reports the LOBSTR connection "doesn't work"; explains the expected unimplemented state and provides the manual paste workflow workaround.
+- **[Diagnose Generated Wallet Support Request](diagnose-generated-wallet-support-request.md)** — Use if support requests arise about the client-side generated wallet feature (currently unused in the UI).
+- **[Clear Stale Persisted Wallet](clear-stale-persisted-wallet.md)** — Use when a user reports seeing the wrong wallet address or being unexpectedly connected; walks through clearing stale localStorage wallet data.
+- **[Verify Claim URL Before Support Escalation](verify-claim-url-before-onchain-state.md)** — Use to validate a user's claim link before escalating issues with claim processing.
+- **[Cross-Check Claim Error Against Onchain State](cross-check-claim-error-against-onchain-state.md)** — Use to reconcile frontend claim errors with actual blockchain state when debugging failed claims.
+
+## Engineering Diagnostics
+Use these to investigate technical issues and gaps in implementation:
+
+- **[Investigate Analytics Event Gap](investigate-analytics-event-gap.md)** — Use when analytics events are reported as missing; verifies the event's expected trigger condition and distinguishes between chain-waiting vs. immediate events.
+- **[Audit Lighthouse Scores](audit-lighthouse-scores.md)** — Use to review performance, accessibility, and best practices metrics from Lighthouse CI runs.
+- **[PDF Artifact Freshness Spot Check](pdf-artifact-freshness-spot-check.md)** — Use to verify that PDF exports in the docs directory match their source MDX files and haven't drifted apart.
+
+## Repository Maintenance
+Use these for ongoing repository health and compliance tasks:
+
+- **[Rebuild Docs PDF from MDX](rebuild-docs-pdf-from-mdx.md)** — Use after updating MDX documentation sources to regenerate their corresponding PDF exports.
+- **[Review Analytics Spec Before New Event](review-analytics-spec-before-new-event.md)** — Use before adding a new analytics event to ensure it aligns with the existing specification and event naming conventions.
+- **[Onboard Mobile App to CI](onboard-mobile-app-to-ci.md)** — Use to set up continuous integration for the mobile application, including test runs and deployment pipelines.
+- **[Verify Branch Protection Compliance](verify-branch-protection-compliance.md)** — Use to confirm repository branch protection rules match the documented requirements in `.github/BRANCH_PROTECTION.md`.
+- **[Security Disclosure Triage (Product)](security-disclosure-triage-product.md)** — Use to triage incoming security vulnerability reports, verify they came through approved channels, and route them to the correct team for remediation.