feat(frontend): add test coverage and correct setup documentation

Frontend/README.md

@@ -112,11 +112,24 @@ npm install
 cp .env.example .env.local
 
 # Run the dev server
-npm dev
+npm run dev
 ```
 
 The app will be available at `http://localhost:3000`.
 
+### Available Scripts
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start the local development server on `http://localhost:3000` |
+| `npm run build` | Build the production bundle |
+| `npm run start` | Start the production server (requires a prior `build`) |
+| `npm run lint` | Run Next.js ESLint rules |
+| `npm run type-check` | Run TypeScript compiler check without emitting files |
+| `npm test` | Run the Jest unit test suite |
+| `npm run test:watch` | Run Jest in interactive watch mode |
+| `npm run test:coverage` | Run Jest and generate a coverage report |
+
 ### Environment Variables
 
 See `.env.example` for required variables, which typically include:
@@ -128,6 +141,34 @@ See `.env.example` for required variables, which typically include:
 
 ---
 
+## Implementation Status
+
+This table distinguishes what is currently implemented in the codebase from what is planned on the roadmap. Features listed as "Roadmap" exist as scaffolded modules or type stubs only — they are **not functional** and are gated by feature flags.
+
+| Feature | Status | Notes |
+|---|---|---|
+| Next.js app scaffold & routing | ✅ Implemented | App Router, Tailwind, TypeScript |
+| Zustand state store | ✅ Implemented | Wallet, vault, streak, discipline score state |
+| `useWallet` hook | ✅ Implemented | Connect/disconnect flow wired to `walletManager` |
+| `useVault` hook | ✅ Implemented | Create, deposit, withdraw — local state only |
+| API client (`src/lib/api.ts`) | ✅ Implemented | HTTP wrapper for backend fiat deposit/withdrawal endpoints |
+| Stellar wallet connection | 🚧 Placeholder | `connectWallet()` throws "not yet implemented" — requires wallet SDK integration |
+| Soroban contract calls | 🚧 Placeholder | Vault/streak/yield reads and signed transactions not yet implemented |
+| Savings vault UI | 🚧 Roadmap | Feature module scaffolded, UI not built |
+| Saving streaks UI | 🚧 Roadmap | Feature module scaffolded, UI not built |
+| Vault pulse / animations | 🚧 Roadmap | Planned for Phase 1–2 |
+| Achievements & milestones | 🚧 Roadmap | Planned for Phase 2 |
+| Savings calendar | 🚧 Roadmap | Planned for Phase 2 |
+| Smart notifications | 🚧 Roadmap | Planned for Phase 2 |
+| Yield display | 🚧 Roadmap | Planned for Phase 2; on-chain data source required |
+| Lending marketplace UI | 🔒 Gated | Phase 3; requires post-audit & legal review. `NEXT_PUBLIC_ENABLE_LENDING=false` |
+| Borrow against savings UI | 🔒 Gated | Phase 3; requires post-audit & legal review. `NEXT_PUBLIC_ENABLE_BORROWING=false` |
+| Investment portfolios UI | 🔒 Gated | Phase 3; requires post-audit & legal review. `NEXT_PUBLIC_ENABLE_INVESTMENTS=false` |
+| Nigerian bank deposit/withdrawal | 🔒 Gated | Depends on anchor partner backend integration |
+| Discipline Score display | 🚧 Roadmap | Type defined; UI and scoring engine not built |
+
+---
+
 ## Development Notes
 
 * This app currently targets **Phase 1–2** of the product roadmap (savings vaults, streaks, deposits, yield display, achievements, notifications). Lending, borrowing, and investment UIs exist as feature modules but should remain **gated/hidden** in production builds until Phase 3 (post-audit, post-legal-review) per the root README's roadmap.

Frontend/jest.config.ts

@@ -0,0 +1,37 @@
+import type { Config } from 'jest'
+import nextJest from 'next/jest.js'
+
+const createJestConfig = nextJest({
+  // Points to the Next.js app root so next.config.js and .env files are loaded
+  dir: './',
+})
+
+const config: Config = {
+  displayName: 'vaulty-frontend',
+  testEnvironment: 'jest-environment-jsdom',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  moduleNameMapper: {
+    // Handle @/ path alias as configured in tsconfig.json
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
+  testMatch: [
+    '**/__tests__/**/*.{ts,tsx}',
+    '**/*.{test,spec}.{ts,tsx}',
+  ],
+  collectCoverageFrom: [
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.d.ts',
+    '!src/app/**',     // Next.js pages/layouts — covered by e2e tests
+    '!src/types/**',
+  ],
+  coverageThreshold: {
+    global: {
+      branches: 60,
+      functions: 60,
+      lines: 60,
+      statements: 60,
+    },
+  },
+}
+
+export default createJestConfig(config)

Frontend/jest.setup.ts

@@ -0,0 +1,2 @@
+// jest.setup.ts — runs after the test framework is installed in the environment
+import '@testing-library/jest-dom'