@venlyfinance/settlement-mcp 0.4.1 → 0.6.0

package/AGENTS.md

@@ -0,0 +1,35 @@
+# Composition rules for coding agents
+
+You are building a financial product UI on `@venlyfinance/react`. These rules exist because the failure modes of money UIs are specific; follow them over generic dashboard instincts.
+
+## Non-negotiable
+
+1. **Never hand-roll API calls, auth, retries, or transfer state.** Every read is a hook (`useAccounts`, `useTransfers`, `useRampRequests`, …); every regulated lifecycle is a flow machine (`useStagedTransfer`, `useFourEyesApproval`, `useRampLifecycle`). If you are writing `fetch` or a `useEffect` polling loop, stop – the hook exists.
+2. **Wrap the tree once** in `<VenlyProvider environment="mock">`. Mock mode needs zero credentials and zero network; it is the correct default for any demo, test, or first build. Going live is a constructor change, not a rewrite.
+3. **Never place `clientSecret` in browser code.** The provider throws if you try. For browser apps use `proxyClientOptions()` against your own backend route.
+4. **Money movement is stage-then-confirm.** Render a review step showing `state.staged` (the exact request) before calling `confirm()`. Never wire a form submit directly to execution.
+5. **Approval UIs render the rule, not the error.** Use `capability` from `useFourEyesApproval`: when `reason` is `"actor-is-creator"`, say that a second person must approve – do not show buttons that will be refused. On failure `"stale-version"`, refetch and let the operator re-decide; never auto-retry an approval.
+6. **Gate every finished screen with the design audit, and wire it into CI.** `npx @venlyfinance/settlement-mcp review "src/**/*.tsx"` fails (exit 1) on any error-severity finding – raw colours, invented timing or custody copy, crypto codes inside `Intl.NumberFormat` currency formatting, a required field labelled optional, parity fixtures, and more. Add it as a CI step in the app you build. A deliberate, justified exception carries `venly-allow:<rule-id>` on the offending line or the line above.
+
+## Rendering money states
+
+- Use `descriptor` from `useRampLifecycle` for status pills and timelines: `intent` gives the semantic colour, but always pair colour with a glyph or label – state is never carried by colour alone.
+- A waiting state must answer: must I act, who is it waiting on, what still works. `descriptor.waitingOn` and `descriptor.explanation` carry this; render them instead of a bare "Pending".
+- Amounts: tabular figures, currency code after the amount, and never render a debit in red as the only signal. Empty numeric cells are an em dash, not 0.
+- Terminal failure states show the reason from the record; the status field is the explanation field.
+
+## Bring your own auth
+
+The Venly APIs authenticate machines (OAuth2 client credentials), not people: there is no end-user login, sign-up, session, password, or MFA endpoint in either API, by design. **The Venly APIs never see end-user credentials.** End-user auth is your identity layer's job; the sanctioned browser shape is a backend proxy that inherits YOUR app's session (`proxyClientOptions()`), never Venly's.
+
+The UI kit's auth and team blocks therefore render against two adapter interfaces, `AuthAdapter` and `TeamAdapter`, instead of an SDK client:
+
+- **Real implementations** wrap what you already run: OAuth/OIDC, Better Auth, Auth0, Clerk, Keycloak, or a plain session cookie. Implement `signIn`/`verifyTotp`/`signUp`/`session`/`signOut` (and the team CRUD) over your provider's SDK.
+- **Session-expiry contract:** `session()` returns `null` once the session has expired for any reason. The shell treats null as signed-out and redirects to sign-in; no other expiry signal exists in the interface.
+- **Mock adapters ship with the blocks** (`createMockAuthAdapter`, `createMockTeamAdapter`): zero credentials, deterministic 2FA code `000000`, an `expireSession()` driver, and invites that mint a display-only link – the mock never claims an email was sent.
+- Password reset, SSO buttons, and passkeys are provider features: point users at your provider's flow rather than rebuilding it behind the adapter.
+
+## Demo choreography (mock mode)
+
+`useVenlyMock()` exposes the store controls. A credible end-to-end demo:
+create party → `advanceVerification(id)` → create account → virtual bank account (note its `referenceCode`) → stage + confirm a transfer → `advanceTransfer(id)` → show the ledger. Inject failures with `failNext("CONFLICT")` to show the stale-version approval path – error states are part of the product.

package/CHANGELOG.md

@@ -2,8 +2,7 @@
 
 ## 0.3.0 – 2026-08-04
 
-Wording-is-the-safety-surface release. An outside integrator audit (Report 1,
-2026-08-04) found the server's words disagreeing with its behavior in three
+Wording-is-the-safety-surface release. An outside integrator audit (2026-08-04) found the server's words disagreeing with its behavior in three
 places; all fixed, plus the SDK under the mock now teaches the documented
 lifecycle (see @venlyfinance/sdk 0.2.0).
 
@@ -104,3 +103,34 @@ Frontend toolset: the judgment layer for interface assembly.
 ## 0.4.1 – 2026-08-07
 
 - `venly://frontend/agents` now carries the full cold-start recipe, learned from a fresh-agent build run: Tailwind + path-alias prerequisites before `shadcn init`, the non-interactive `-y -b radix -p nova` flags, that blocks land under `components/venly/` at the project root (relative imports, not the `@/` alias), that `shadcn add` auto-installs the npm dependencies, and the `.js`-extension bundler note.
+
+## 0.5.0 – 2026-08-14 (backfill; published 2026-08-15)
+
+Entry added retroactively in 0.6.0 – the publish predates it.
+
+- Nine payout tools over the re-vendored finance contract (payouts, payout routes +
+  ownership proof, party payout bank accounts), fail-closed writes.
+- Corrected capabilities text; react/ui alignment with the 0.4.0 SDK line.
+
+## 0.6.0 – 2026-08-18
+
+`review_screen` grows teeth: five new rule classes, a suppression hatch, and a CI-runnable command.
+
+- New error rules: `invented-timing-claim` (copy promising durations, settlement windows
+  or custody behaviour no API in this stack returns), `intl-currency-crypto`
+  (`Intl.NumberFormat` + `style:"currency"` + a crypto code throws `RangeError` at render;
+  a variable-fed `currency:` in the same call is a warn), `required-rendered-optional`
+  (the payment reference labelled "(not required)"), `parity-fixture` (seeded 1:1
+  exchange rates).
+- New warn rules: `blueprint-state-missing` (pass the new optional `journey` argument to
+  `review_screen` and the audit lists blueprint-named states not found in the source) and
+  `round-number-coincidence` (three or more `x.00` amounts seeded in one source).
+- Suppression hatch on every rule, old and new: `venly-allow:<rule-id>` on the offending
+  line or the line above drops the finding silently.
+- Copy-judging rules skip comment lines – a comment documenting a rule must not trip it.
+- Findings now carry a 1-based `line`.
+- New `review` CLI over the same audit: `npx @venlyfinance/settlement-mcp review "src/**/*.tsx"`
+  exits 1 on any error-severity finding (0 otherwise, 2 on usage errors/no matches), with
+  self-expanded globs and zero dependencies. Added a `settlement-mcp` bin alias so the
+  npx form resolves under npm's unscoped-name rule. This repo's CI now runs the command
+  over its own registry and example sources.

package/README.md

@@ -15,6 +15,8 @@ the normalized write requests. Staging and production writes fail closed.
 
 The Venly Finance builder surface documented here is the v0.2.0 release line.
 
+Building with a coding agent? Start from [AGENTS.md](AGENTS.md) - the MCP also serves it as the \venly://frontend/agents resource.
+
 ## What it is
 
 - Built on the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), Node
@@ -98,6 +100,15 @@ Operator writes: `approve_ramp_request`, `reject_ramp_request`. The legacy
 Each is dry-run by default and returns the exact request it would send. See the
 safety model below.
 
+### Payout tools (since 0.5.0)
+
+The payout surface of the finance contract, same tiering as above. Reads:
+`list_payouts`, `get_payout`, `list_payout_routes`, `list_payout_bank_accounts`.
+Writes (dry-run by default, fail-closed like every write): 
+`register_payout_bank_account`, `create_payout_route`,
+`prepare_payout_ownership_proof`, `complete_payout_ownership_proof`,
+`request_payout`.
+
 ### 3. x402 tool (position + stub)
 
 `quote_x402_payment` returns an HTTP-402-shaped quote (price, asset, payTo,
@@ -116,13 +127,36 @@ what a registry cannot:
 - `get_journey_blueprint` – screen inventory, required states, registry items and binding
   hooks for eight money-product journeys.
 - `review_screen` – deterministic design audit of a screen's source (raw colours,
-  hyphen-minus amounts, success styling on cancelled steps, masked review values, zebra
-  striping, off-token shadows, colour-only state). Findings, not a score.
+  hyphen-minus amounts, success styling on cancelled steps, masked review values,
+  invented timing/custody copy, crypto codes inside `Intl.NumberFormat` currency
+  formatting, required fields rendered optional, parity and round-number fixtures,
+  zebra striping, off-token shadows, colour-only state). Pass the optional `journey`
+  key to also check that every state the journey blueprint names appears in the
+  source. Findings, not a score.
 - `venly://frontend/agents` – the composition rules an agent should read before building.
 
 The `build_international_account` prompt assembles the interface from the registry and
 gates every finished screen on `review_screen`. See [`ui/`](../ui/README.md) for the kit itself.
 
+### Design-audit CLI
+
+The same audit runs as a command, so a generated app can gate itself in CI:
+
+```bash
+npx @venlyfinance/settlement-mcp review "src/**/*.tsx"
+```
+
+Exit `1` on any error-severity finding, `0` otherwise (warnings print either way),
+`2` on usage errors or a pattern that matches nothing. Suppress a deliberate,
+justified exception with `venly-allow:<rule-id>` on the offending line or the line
+above – the finding is dropped silently. This repo runs the same command over its
+own registry sources in CI.
+
+Scope the glob to component source, never to token or theme files: the
+`raw-colour` rule fires on any hex/rgba literal by design, and a tokens/theme
+css file is the one legitimate home of raw colour values (theming stays a
+one-file edit). `"src/**/*.tsx"` is the right default.
+
 ## Safety model (fail closed)
 
 Outside explicit mock mode, read-only/dry-run is the default posture. A staging
@@ -228,8 +262,9 @@ reads, and fail-closed write gate without mutating staging:
 VENLY_CLIENT_ID=... VENLY_CLIENT_SECRET=... npm run smoke:staging
 ```
 
-The command starts the MCP with `VENLY_ENV=staging`, lists the expected 24 tools,
-five resources, and builder prompt, then reads parties, accounts, and reference data.
+The command starts the MCP with `VENLY_ENV=staging`, verifies the discovery
+surface against the exact tool/resource/prompt inventory pinned in the smoke
+script itself, then reads parties, accounts, and reference data.
 It deliberately removes `VENLY_MCP_LIVE` and `VENLY_MCP_PRODUCTION` from the child
 process before submitting one confirmed `create_party` request. Passing requires that
 request to return `mode: dry-run`, `environment: staging`, and an unarmed gate. Output

package/dist/client/sdk-client.d.ts

@@ -1,6 +1,6 @@
 import { FundflowClient, VenlyFinanceClient, type MockCall } from "@venlyfinance/sdk";
 import { type VenlyEnvironment } from "../constants.js";
-import type { Account, CryptoCurrency, CreateAccountInput, CreateCryptoTransferInput, CreateFiatTransferInput, CreatePartyInput, CreatePayInSessionRequest, CreateVirtualBankAccountInput, CurrentCreateFiatTransferInput, FiatCurrency, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, RampRequestDto, RampRequestListItem, SupportedChains, Transfer, VenlyClient, VirtualBankAccount, VenlyFee, Wallet } from "../types.js";
+import type { Account, CryptoCurrency, CreateAccountInput, CreateCryptoTransferInput, CreateFiatTransferInput, CreatePartyInput, CreatePayInSessionRequest, CreateVirtualBankAccountInput, CurrentCreateFiatTransferInput, FiatCurrency, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, Payout, PayoutBankAccount, PayoutRoute, CreatePayoutInput, CreatePayoutRouteInput, RegisterPayoutBankAccountInput, PayoutOwnershipProof, CompleteOwnershipProofInput, RampRequestDto, RampRequestListItem, SupportedChains, Transfer, VenlyClient, VirtualBankAccount, VenlyFee, Wallet } from "../types.js";
 /**
  * Normalize the legacy stage_transfer input to the current Finance
  * CreateFiatTransferInput wire shape. Exported so the write tool can show the
@@ -64,4 +64,17 @@ export declare class SdkVenlyClient implements VenlyClient {
     approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
     createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
+    listPayouts(accountId: string, params?: {
+        page?: number;
+        size?: number;
+        status?: string;
+    }): Promise<Payout[]>;
+    getPayout(accountId: string, payoutId: string): Promise<Payout>;
+    requestPayout(accountId: string, body: CreatePayoutInput): Promise<Payout>;
+    listPayoutRoutes(accountId: string): Promise<PayoutRoute[]>;
+    createPayoutRoute(accountId: string, body: CreatePayoutRouteInput): Promise<PayoutRoute>;
+    preparePayoutOwnershipProof(accountId: string, routeId: string): Promise<PayoutOwnershipProof>;
+    completePayoutOwnershipProof(accountId: string, routeId: string, body: CompleteOwnershipProofInput): Promise<PayoutRoute>;
+    listPayoutBankAccounts(partyId: string): Promise<PayoutBankAccount[]>;
+    registerPayoutBankAccount(partyId: string, body: RegisterPayoutBankAccountInput): Promise<PayoutBankAccount>;
 }

package/dist/client/sdk-client.js

@@ -180,4 +180,43 @@ export class SdkVenlyClient {
         this.assertReady();
         return this.finance.paymentSessions.create(accountId, body);
     }
+    // ----- Payout surface (contract 1.3.0) -----
+    async listPayouts(accountId, params) {
+        this.assertReady();
+        const page = await this.finance.payouts.list(accountId, params);
+        return page.items;
+    }
+    async getPayout(accountId, payoutId) {
+        this.assertReady();
+        return this.finance.payouts.get(accountId, payoutId);
+    }
+    async requestPayout(accountId, body) {
+        this.assertReady();
+        return this.finance.payouts.request(accountId, body);
+    }
+    async listPayoutRoutes(accountId) {
+        this.assertReady();
+        return this.finance.payoutRoutes.list(accountId);
+    }
+    async createPayoutRoute(accountId, body) {
+        this.assertReady();
+        return this.finance.payoutRoutes.create(accountId, body);
+    }
+    async preparePayoutOwnershipProof(accountId, routeId) {
+        this.assertReady();
+        return this.finance.payoutRoutes.prepareOwnershipProof(accountId, routeId);
+    }
+    async completePayoutOwnershipProof(accountId, routeId, body) {
+        this.assertReady();
+        return this.finance.payoutRoutes.completeOwnershipProof(accountId, routeId, body);
+    }
+    async listPayoutBankAccounts(partyId) {
+        this.assertReady();
+        const page = await this.finance.payoutBankAccounts.list(partyId);
+        return page.items;
+    }
+    async registerPayoutBankAccount(partyId, body) {
+        this.assertReady();
+        return this.finance.payoutBankAccounts.register(partyId, body);
+    }
 }

package/dist/constants.d.ts

@@ -1,9 +1,9 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export declare const SERVER_NAME = "venly-finance-mcp-server";
-export declare const SERVER_VERSION = "0.4.1";
+export declare const SERVER_VERSION = "0.6.0";
 export declare const ENVIRONMENT_FLAG = "VENLY_ENV";
-export type VenlyEnvironment = "mock" | "staging" | "production";
+export type VenlyEnvironment = "mock" | "qa" | "staging" | "production";
 export declare function resolveVenlyEnvironment(env: Record<string, string | undefined>): VenlyEnvironment;
 /** The env flag that must equal "1" for any write tool to execute live. */
 export declare const LIVE_FLAG = "VENLY_MCP_LIVE";

package/dist/constants.js

@@ -1,17 +1,17 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export const SERVER_NAME = "venly-finance-mcp-server";
-export const SERVER_VERSION = "0.4.1";
+export const SERVER_VERSION = "0.6.0";
 export const ENVIRONMENT_FLAG = "VENLY_ENV";
 export function resolveVenlyEnvironment(env) {
     // Default is MOCK (since 0.3.0): the mock-first product must not point at
     // real infrastructure when unconfigured. Set VENLY_ENV explicitly for
     // staging or production.
     const value = env[ENVIRONMENT_FLAG] ?? "mock";
-    if (value === "mock" || value === "staging" || value === "production") {
+    if (value === "mock" || value === "qa" || value === "staging" || value === "production") {
         return value;
     }
-    throw new Error(`${ENVIRONMENT_FLAG} must be one of mock, staging, production; received ${JSON.stringify(value)}`);
+    throw new Error(`${ENVIRONMENT_FLAG} must be one of mock, qa, staging, production; received ${JSON.stringify(value)}`);
 }
 /** The env flag that must equal "1" for any write tool to execute live. */
 export const LIVE_FLAG = "VENLY_MCP_LIVE";

package/dist/frontend.d.ts

@@ -9,13 +9,29 @@
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare const REGISTRY_URL_TEMPLATE = "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json";
+declare const JOURNEYS: {
+    readonly auth: "# Auth (sign-in, 2FA, sign-up)\nShell: outside the app shell - a centred card column.\nRegistry items: venly-tokens; block: auth (SignInForm, TwoFactorForm, SignUpForm).\nBinding: an AuthAdapter YOU implement - the Venly APIs authenticate machines\n(client credentials), never people, so end-user auth is your identity layer\n(OAuth/OIDC, Better Auth, Auth0, Clerk, Keycloak). createMockAuthAdapter ships\nfor demos: deterministic 2FA code 000000, expireSession() driver.\nStates that must exist: signed out, bad credentials (ONE combined message -\nno user enumeration), 2FA challenge with wrong-code path, session expired\n(session() returns null - redirect, no other signal), duplicate sign-up email.\nRules that must hold: credential errors never confirm which half was wrong;\nthe code field is six slots with paste distribution and full keyboard support;\nthe mock never claims an email was sent.";
+    readonly team: "# Team\nShell: in-shell content column.\nRegistry items: venly-tokens, data-table, status-pill; block: team (TeamTable, InviteDialog).\nBinding: a TeamAdapter over your auth provider (createMockTeamAdapter for demos).\nStates that must exist: ACTIVE/INVITED/DISABLED members on first paint, invite\ncreated (display-only link in mock - never a fake sent-email claim), role\nchange persisting, self-actions blocked with the reason.\nRules that must hold: member status is word + glyph; role controls live in the\nrow; you cannot change your own role or disable yourself - the control is\ndisabled AND explains why.";
+    readonly "home-balances": "# Home / balances\nShell: left nav rail + thin top bar; full-width content.\nRegistry items: venly-tokens, balance-card, data-table, status-pill; block: balances (BalancesBlock, BalanceMiniature).\nHooks: useAccounts, useWallets; balances rendered per asset across the account's wallets.\nStates that must exist: loading, zero balances (first-run guidance), reserved buckets, entirely reserved (available 0 rendered honestly - the acct-escrow seed exercises it), balance load error degrading locally with a retry.\nRules that must hold: available is the emphasised figure and the only one above the rule; reserved is demoted by position and scale, never colour, and carries the still-yours qualifier; unspendable buckets carry the padlock; masking covers every figure including the chrome miniature; arithmetic mismatches are surfaced, never corrected; never assume stablecoin parity - render the quoted rate.";
+    readonly receive: "# Receive\nShell: content column - a warning callout, the field card, an advisory below.\nRegistry items: venly-tokens, field-list; block: receive.\nHooks: useVirtualBankAccounts (first active EUR account).\nStates that must exist: no virtual bank account yet (offer creation), details present, reference not yet assigned (\"Not assigned yet\" + Required pill - never \"(not required)\").\nRules that must hold: the payment reference is enforced as mandatory (amber Required pill, warning above the fields); per-field copy names the field it copied and only confirms on a successful write; rows never vanish - render the \"(not required)\" variant.";
+    readonly send: "# Send\nShell: full page; form clamped ~600px; review step replaces the form.\nRegistry items: venly-tokens, arithmetic-ladder, timeline; block: send.\nHooks: useStagedTransfer (the machine IS the flow), useFeeQuote when fees apply.\nStates that must exist: draft (validation issues listed), staged review, submitting, pending (polling), completed, failed (reason shown, terminal).\nRules that must hold: money movement is stage-then-confirm - the review renders the exact staged request as an arithmetic ladder (working before the answer, uncertainty attached to the number); the commit button restates the amount and never carries a countdown; values are never masked on review; execution is single-shot on an idempotency key pinned at staging.";
+    readonly activity: "# Activity\nShell: full-width table + side panel.\nRegistry items: venly-tokens, data-table, status-pill, side-panel, timeline; block: activity.\nHooks: useTransfers (and useRampRequests where ramps are in scope).\nStates that must exist: loading, empty ledger, rows with pending/failed pills, open detail panel that stays in sync with refetches.\nRules that must hold: a row click opens the panel, never navigates; no scrim - the source row stays tinted; settled rows stay quiet (colour is a budget; pills only where action or failure lives); the panel's hero is the amount; the failure reason rides the terminal timeline node.";
+    readonly "onboarding-status": "# Onboarding / verification status\nShell: full page, form clamped ~600px; a status home once submitted.\nRegistry items: venly-tokens, timeline, status-pill, field-list; block: onboarding (CompanyForm, VerificationStatusHome, RestrictedBanner).\nHooks: useCreateParty, useCreateAccount, useParty, useAccount; verification status from the party/account records verbatim.\nStates that must exist: collecting (review before submit), submitted/waiting (say who acts next, on which channel, what still works meanwhile), approved, declined (humane copy, review-request as the primary action), re-verification on a live account (banner naming what pauses and what keeps working).\nRules that must hold: never render a fake progress percentage - use real status; a waiting state answers how long / who acts / what still works, and where no review window is published the copy says so instead of inventing one; a decline explains and offers a next step, not a dead end; creating a party is NOT completed verification - show the honest state.";
+    readonly "withdraw-bank-accounts": "# Withdraw + bank accounts (off-ramp)\nShell: settings page for the whitelist; full page for the flow, form clamped ~600px.\nRegistry items: venly-tokens, data-table, status-pill, timeline, field-list, arithmetic-ladder; blocks: bank-accounts (BankAccountsBlock, AddBankAccountForm), withdraw (WithdrawFlow, WithdrawalsTable, ConnectedWithdrawDetail).\nHooks: useCompanyBankAccounts, useBankAccountConfig, useCreateCompanyBankAccount, useRampRequests, useRampRequest, useCreateRampRequest, useFeeQuote, useRampPairs, useReferenceData, useFourEyesApproval, useInitiateRamp, describeRampStatus.\nStates that must exist: empty whitelist (one CTA), account in review / verified / declined, no-verified-destination block, amount over balance (two-place signal), fee quote with its unit, awaiting approval (creator sees why they can't approve), stale decision (409 - refetch and re-decide, never auto-retry), awaiting funds (deposit instructions + mandatory reference + tx-hash report), processing, paid out, failed, rejected, cancelled, on hold.\nRules that must hold: destinations are the company's OWN verified accounts - unverified rows are disabled with the reason, never hidden; the pre-create review renders only known figures (no invented rate, no bank-receives placeholder - the created record carries the fiat arithmetic and the detail opens on it); a refusal never reads as a wait; the event timeline renders actor, role and absolute timestamps.";
+    readonly reconciliation: "# Reconciliation\nShell: split pane (roughly one-third list, two-thirds evidence) - not a drawer.\nRegistry items: venly-tokens, data-table, side-panel, status-pill, field-list.\nHooks: reconcile_by_reference_code (MCP composite) or useVirtualBankAccounts + useTransfers joined on referenceCode.\nStates that must exist: matched, unmatched with candidate expectations, partial/many-to-one with a live shortfall figure, resolved.\nRules that must hold: show per-signal match rationale (which fields agree), never a bare score; keep zero-counts visible - an empty exception queue is information; keyboard row-stepping for review throughput.";
+    readonly "proof-of-segregation": "# Proof of segregation\nShell: content column, single card.\nRegistry items: venly-tokens, field-list, balance-card.\nHooks: useWallets, useAccount; on-chain balance beside the ledger figure.\nStates that must exist: reconciled (figures agree, timestamped), reconciling, source unavailable (say so - never render a stale figure as current).\nRules that must hold: the wallet address renders monospace with copy; the on-chain figure and ledger figure sit side by side with their as-of times; discrepancies are stated, not smoothed.";
+    readonly approvals: "# Approvals\nShell: full-width queue + side panel tailored to the approver.\nRegistry items: venly-tokens, data-table, status-pill, side-panel, timeline.\nHooks: useRampRequests, useFourEyesApproval (capability decides what renders), useRampLifecycle.\nStates that must exist: queue with awaiting-approval items, detail with the decision context beside the figures, applied, stale-version (someone acted first - refetch and re-decide), creator-view (cannot approve own request - render the rule, not a disabled mystery button).\nRules that must hold: the optimistic-locking version travels with every decision; a 409 means re-decide against fresh state, never auto-retry; reject requires a reason; the creator sees why they cannot approve.";
+};
+type JourneyKey = keyof typeof JOURNEYS;
 interface Finding {
     rule: string;
     severity: "error" | "warn";
     evidence: string;
     fix: string;
+    /** 1-based line the finding fired on - lets a CLI print path:line. */
+    line?: number;
 }
 /** Deterministic design audit. Text in, findings out - no model, no taste. */
-export declare function reviewScreenSource(source: string): Finding[];
+export declare function reviewScreenSource(source: string, journey?: JourneyKey): Finding[];
 export declare function registerFrontendTools(server: McpServer): void;
 export {};