Commit

.gitignore

@@ -39,3 +39,4 @@ scripts/*.js
 
 # macOS
 .DS_Store
+desktop.ini 

DEMO_CHECKLIST.md

@@ -0,0 +1,204 @@
+# Remlo — 60-Second Demo Checklist
+
+> **Setup**: `pnpm dev` running on `http://localhost:3000`. Open in Chrome. Use a second terminal for the agent script.
+
+---
+
+## Pre-Demo (30s before)
+
+- [ ] `pnpm dev` running, no console errors
+- [ ] Chrome open at `http://localhost:3000` — landing page visible (dark, animated mesh gradient)
+- [ ] Terminal ready: `npx ts-node scripts/demo-agent.ts`
+- [ ] Second browser tab open at `http://localhost:3000/dashboard/demo`
+
+---
+
+## Demo Flow
+
+### 1. Landing Page — `http://localhost:3000`
+**Expected state:**
+- Dark background (`#0A0F1E`) with animated emerald/indigo mesh gradient orbs
+- Hero: "Pay anyone, anywhere. Settle in half a second." — "half a second" in accent green
+- 3 stat chips: `< 0.5s settlement`, `$0 wire fees`, `150+ countries`
+- "Start free" and "View API docs" CTAs visible
+
+**Scroll to:**
+- Problem section: red `$47 wire cost`, `4 days`, `6.2% FX fees` with animated counters
+- How It Works: 4-step flow (01 Employer Deposits → 02 AI Runs Payroll → 03 Smart Contract Batch → 04 Employee Receives)
+- Pricing: 3-tier cards, Growth "Most Popular" highlighted with accent border
+
+---
+
+### 2. Auth / Login — `http://localhost:3000/login`
+**Expected state:**
+- Centered card with Remlo logo
+- "Continue with email" / wallet connect options (Privy)
+- Clean dark surface with border-default
+
+---
+
+### 3. Employer Dashboard Home — `http://localhost:3000/dashboard`
+**Expected state:**
+- Left sidebar: Remlo logo, nav links (Overview, Team, Payroll, Treasury, Compliance, API Access, Demo)
+- 4 MetricTiles: Treasury Balance / Total Paid / Team Size / Avg Settlement
+- Last 5 payroll runs list (mock data: 2–3 "Completed" runs)
+- Recharts bar chart (30-day payment volume)
+- Compliance donut (green/neutral)
+
+---
+
+### 4. Team Page — `http://localhost:3000/dashboard/team`
+**Expected state:**
+- Table: 3 mock employees (Sofia Mendez, James Okonkwo, Priya Sharma)
+- Status badges: 2× "Approved" (green), 1× "Pending" (yellow)
+- "Add Employee" + "Upload CSV" buttons in header
+- Table scrolls horizontally on narrow viewport
+
+**Actions to show:**
+- Click "Upload CSV" → 4-step modal (drag-drop → column map → preview → done)
+- Click employee row → navigates to `/dashboard/team/emp-1`
+
+---
+
+### 5. Employee Detail — `http://localhost:3000/dashboard/team/emp-1`
+**Expected state:**
+- 3-tab layout: Overview / Payment History / Compliance
+- **Overview tab**: wallet address (truncated, font-mono), $95,000/yr salary, VisaCard display (front face), bridge bank account section
+- **Payment History tab**: TxStatus chip + MemoDecoder with ISO 20022 fields decoded
+- **Compliance tab**: TIP-403 status "CLEAR", policy ID, authorized wallet badge, audit log
+
+---
+
+### 6. Run Payroll Wizard — `http://localhost:3000/dashboard/payroll/new`
+**Expected state:**
+- 4-step wizard with animated `StepBar`
+- Step 1 "Select Employees": 3 checkboxes (Sofia, Priya, Carlos)
+- Step 2 "Edit Amounts": editable salary amounts with running total
+- Step 3 "Review": read-only summary, total amount, recipient count
+- Step 4 "Execute": BatchProgress component — 4 steps animate through signing → submitting → confirming → ✓ success
+
+**Actions to show:**
+- Select all → Next → Next → "Run Payroll" → watch BatchProgress animate to success
+- Success state: confetti, tx hash link to Tempo Explorer, "Settled in 0.4s"
+
+---
+
+### 7. Treasury Page — `http://localhost:3000/dashboard/treasury`
+**Expected state:**
+- TreasuryCard: available balance + locked balance
+- DepositPanel: wire instructions (IBAN, routing, SWIFT)
+- YieldCard: current APY% (from YieldRouter), accrued yield counter
+- TxHistoryTable: paginated history with type badges (Deposit/Payroll/Yield)
+
+---
+
+### 8. API Access + Agent Terminal — `http://localhost:3000/dashboard/api-access`
+**Expected state:**
+- 3-tier MPP pricing table (Micro-reads at $0.01, Operations at $0.50–$1.00, Premium at $0.50)
+- AgentKeyPanel: "Generate API Key" button (800ms fake delay), copy-to-clipboard
+- AgentTerminal: macOS-style terminal with "Run Demo" button
+- Click "Run Demo" → terminal animates through 8 DEMO_LINES with type-colored output
+
+---
+
+### 9. Split-Screen Demo Page — `http://localhost:3000/dashboard/demo`
+**Expected state:**
+- Split view: terminal left, live state right
+- **Right panel**: treasury $847,234.50 · StreamingBalanceTicker ticking · compliance ALL CLEAR · MPP cost table
+- Click **"Run Demo Agent"** button:
+  - Terminal streams 15 lines over ~7 seconds
+  - Lines color-coded: system (muted) / request (cyan) / response (green) / payment (yellow)
+  - Payment total counter increments: $0.01 → $0.03 → $0.28 → $1.28 → $1.29
+  - Session complete line: "Session closed · $1.29 spent · $3.71 unspent returned"
+
+---
+
+### 10. Employee Portal — `http://localhost:3000/portal`
+**Expected state:**
+- Centered max-640px layout, "Good morning, Sofia." greeting
+- Balance card with StreamingBalanceTicker (green pulsing dot = connected)
+- Last payment card: amount, TxStatus chip, decoded memo label
+- 4 quick-action tiles: View Payments / Manage Card / Off-ramp / Settings
+
+---
+
+### 11. Portal Payment History — `http://localhost:3000/portal/payments`
+**Expected state:**
+- Expandable payment cards grouped by month
+- Expanded card: TxStatus, tx hash link, MemoDecoder (ISO 20022 fields), "Download payslip PDF" button
+- Search input filters by label/amount/hash
+
+---
+
+### 12. CLI Demo Agent (Terminal)
+```bash
+npx ts-node scripts/demo-agent.ts
+```
+
+**Expected output:**
+```
+════════════════════════════════════════════════════════════
+  REMLO — Autonomous AI Treasury Agent
+  Machine-to-Machine Payroll via MPP (x402)
+════════════════════════════════════════════════════════════
+
+[STEP 1] Opening MPP session...
+  ✓ Session initialized.
+
+[STEP 2] Querying yield rates (MPP-1, $0.01)...
+  ✓ $0.01 charged.
+
+[STEP 3] Querying treasury balance (MPP-6, $0.02)...
+  ✓ $0.02 charged.
+
+[STEP 4] Running compliance checks on 5 employees...
+  ✓ $0.25 charged. All 5 wallets verified.
+
+[STEP 5] Executing payroll batch (MPP-3, $1.00)...
+  ✓ $1.00 charged.
+
+[STEP 6] Connecting to salary stream (MPP-5)...
+  [demo mode or live ticks if server running]
+
+[STEP 7] Session Closed
+  deposited_usd: "5.00"
+  total_spent_usd: "1.29"
+  unspent_returned_usd: "3.71"
+────────────────────────────────────────────────────────────
+  DEMO COMPLETE — Autonomous AI Treasury Agent ran in ~60s
+  Total MPP payments: $1.29
+  Chain: Tempo Moderato (ID: 42431)
+  Token: pathUSD (TIP-20)
+────────────────────────────────────────────────────────────
+```
+
+**Exit code must be 0.** If server offline, all steps return demo stubs — still exits 0.
+
+---
+
+## Key Technical Talking Points
+
+| Feature | Detail |
+|---------|--------|
+| Chain | Tempo Moderato (EVM, ID: 42431) |
+| Token | pathUSD (TIP-20, 6 decimals) |
+| Settlement | < 0.5s on-chain finality |
+| Payment protocol | MPP (x402) — machine-to-machine micropayments |
+| Compliance | TIP-403 registry — on-chain wallet authorization |
+| Payroll memo | ISO 20022 encoded in 32-byte on-chain memo field |
+| Salary streaming | `StreamVesting` contract — per-second accrual |
+| Auth | Privy embedded wallets — no MetaMask needed |
+| Yield | `YieldRouter` contract — treasury earns APY while idle |
+| AI agent | Autonomous payroll run in ~60s, $1.29 total cost |
+
+---
+
+## Troubleshooting
+
+| Issue | Fix |
+|-------|-----|
+| `pnpm dev` port in use | `lsof -ti:3000 \| xargs kill -9` |
+| Demo agent crashes | Server offline is OK — stubs are returned, script still exits 0 |
+| Build fails | Check `.env.local` has all placeholder values (see `.env.local`) |
+| SSE not streaming | Check browser DevTools → Network → `run-agent` response is `text/event-stream` |
+| Dark mode not enforced on landing | `useForceDark()` runs client-side — brief flash on first load is expected |

GAPS.md

@@ -0,0 +1,125 @@
+# GAPS
+
+Reconciliation closure updated on March 23, 2026 against:
+
+- `REMLO_MASTER.md`
+- `remlo_architecture_spec.md` (Doc A)
+- `remlo_build_guide.md` (Doc B)
+- `remlo_mpp_blueprint.md` (Doc C)
+
+Naming note: where older source material says `PayStream`, read it as `Remlo`.
+
+## Resolved In This Closure Pass
+
+### Doc A — Component props
+
+All Doc A Section 5 prop drift recorded in the first reconciliation pass is now closed.
+
+| Component | Closure status |
+| --- | --- |
+| `AddressDisplay` | Resolved with `label?: string` compatibility support. |
+| `TxStatus` | Resolved with `hash` compatibility alias. |
+| `ChainBadge` | Resolved with `chain?: string` support. |
+| `TreasuryCard` | Resolved with doc-compatible balance and yield aliases. |
+| `BalanceTicker` | Resolved with default-safe `ratePerSecond` and `currency` support. |
+| `DepositPanel` | Resolved with `onClose` support. |
+| `EmployeeTable` | Resolved with doc-compatible `employees` and `onSelect` while keeping richer action callbacks. |
+| `CSVUpload` | Resolved with `onUpload(count)` compatibility callback. |
+| `WalletStatus` | Resolved with `linked` compatibility alias. |
+| `VisaCardDisplay` | Resolved with `card` object compatibility alias. |
+| `CardActivation` | Resolved with `card` object compatibility alias. |
+| `OffRampPanel` | Resolved with `onComplete` callback. |
+| `MemoDecoder` | Resolved with `memo` compatibility alias. |
+| `PayrollRunCard`, `PayrollWizard`, `BatchProgress` | Kept as implementation-supersedes-doc cases from the first pass; no regression introduced. |
+
+### Doc A — Landing copy and footer shell
+
+The copy drift recorded in the first reconciliation pass is now closed.
+
+- Navbar labels and CTA are aligned.
+- Landing hero, problem, solution, how-it-works, pricing, and FAQ copy are aligned.
+- Footer tagline is aligned.
+- Footer `Status` and `Press` destinations now exist as real public routes.
+- LinkedIn remains intentionally hidden because no verified company URL has been provided. This is now an implementation-supersedes-doc safety choice, not an unresolved missing placeholder.
+
+### Doc A — Screen wireframe gaps
+
+The previously deferred wireframe items that were part of the approved gap-closure plan are now implemented.
+
+| Surface | Closure status |
+| --- | --- |
+| `/dashboard/team` | Search, filter dropdowns, column visibility, and row actions including `Pause payments` are implemented. |
+| `/dashboard/team/[id]` | Actions dropdown, payment pagination, issue-card CTA, and platform-admin manual review action are implemented. |
+| `/portal/card` | Freeze, lost-card, and PIN controls are present as honest-disabled controls tied to current Bridge support limits. |
+| `/portal/settings` | Editable profile, passkey linking, session/security copy, and bank-management entry path are implemented. |
+| Public footer shell | `Status` and `Press` now resolve; LinkedIn remains intentionally hidden until verified. |
+
+## Technical Patterns Closed
+
+### Doc B — Bridge, security, and tests
+
+The following Doc B gaps are now closed:
+
+- Bridge webhook route now accepts canonical `x-webhook-signature` and canonical event families:
+  - `transfer.payment_processed`
+  - `card_transaction.created`
+  - `customer.updated`
+- Legacy Bridge webhook names remain accepted for compatibility.
+- `PayrollBatcher.sol` now uses `ReentrancyGuard`.
+- Foundry coverage now includes payroll batching, vesting arithmetic, and yield-router math paths.
+- The docs set now records that Mintlify content lives under `docs/` while `docs.json` remains at repo root.
+
+### Doc C — MPP endpoint drift
+
+The previously logged MPP response-contract drift is now closed for the external endpoint surface.
+
+| Endpoint | Closure status |
+| --- | --- |
+| `GET /api/mpp/employee/balance/stream` | Canonical `employeeId` query supported and documented; legacy `address` remains accepted for compatibility. |
+| `POST /api/mpp/treasury/optimize` | `question?: string` supported; richer response shape returned and documented. |
+| `GET /api/mpp/marketplace/compliance-list/[employerId]` | Returns marketplace allowlist shape with `providerId`, `clearedWallets`, `list`, and `lastUpdated`. |
+| `POST /api/mpp/agent/session/treasury` | Returns canonical `{ action, result, timestamp }` envelope. |
+
+## Remaining Verified Gaps
+
+These are the items still intentionally open after the closure pass because changing them safely requires a verified protocol decision rather than another surface-level patch.
+
+| Area | Remaining gap | Why it is still open |
+| --- | --- | --- |
+| Tempo payroll execution transport | `components/payroll/PayrollWizard.tsx` still does not use the exact sponsored TempoTransaction `type: 'tempo'` flow with `calls`, `feeToken`, `feePayer`, and `feePayerSignature`. | The current Privy `useSendTransaction` hook only exposes a standard `UnsignedTransactionRequest` surface. Implementing the exact Tempo flow safely requires a verified EIP-1193 / Viem Tempo client path rather than another approximation. |
+| Treasury identity mapping | `PayrollTreasury` keys employer balances by `keccak256(abi.encodePacked(employerAdminAddress))`, but several app routes still derive treasury and yield reads from the off-chain employer id string. | The current schema does not persist the canonical on-chain employer admin wallet address on the employer record. This needs a verified treasury identity design instead of another silent hash workaround. |
+
+### Routes still affected by the treasury identity mismatch
+
+The following routes still need that canonical on-chain employer treasury key before they can be called fully reconciled:
+
+- `GET /api/employers/[id]/treasury`
+- `GET /api/yield`
+- `POST /api/employers/[id]/payroll`
+- `POST /api/mpp/treasury/optimize`
+- `POST /api/mpp/agent/session/treasury`
+
+## Implementation Additions Not In The Original Specs
+
+These remain in the codebase and are not being removed in reconciliation. They should stay unless you explicitly want a cleanup pass.
+
+| Addition | Status |
+| --- | --- |
+| Mintlify docs bundle and `docs/` content tree | Kept and documented. You explicitly asked for the docs and for the folder reorganization. |
+| Social preview routes (`app/opengraph-image.tsx`, `app/twitter-image.tsx`) | Kept unless you want a marketing cleanup pass. |
+| Shared footer background wordmark treatment | Kept unless you want a design cleanup pass. |
+| `usePrivyAuthedFetch` | Kept; this is part of the live auth implementation, not fluff. |
+| `FundingReadinessCard` | Kept; useful product UX addition. |
+| `Developers` footer column | Kept; useful navigation addition, though it was not in the earliest source docs. |
+
+## Current Reconciliation Status
+
+- Reconciliation audit: complete
+- Gap report: updated to current codebase state
+- High-priority spec drift: closed
+- Public/footer route gaps: closed
+- MPP response-contract drift: closed
+- Bridge webhook drift: closed
+- Contract reentrancy/test hardening: closed
+- Mintlify docs move to `docs/`: closed
+- Remaining open work: exact sponsored Tempo payroll transport and canonical on-chain employer treasury identity mapping