@venlyfinance/settlement-mcp 0.4.1 → 0.6.0

package/dist/frontend.js

@@ -1,12 +1,35 @@
 import { z } from "zod";
 export const REGISTRY_URL_TEMPLATE = "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json";
 const JOURNEYS = {
+    auth: `# Auth (sign-in, 2FA, sign-up)
+Shell: outside the app shell - a centred card column.
+Registry items: venly-tokens; block: auth (SignInForm, TwoFactorForm, SignUpForm).
+Binding: an AuthAdapter YOU implement - the Venly APIs authenticate machines
+(client credentials), never people, so end-user auth is your identity layer
+(OAuth/OIDC, Better Auth, Auth0, Clerk, Keycloak). createMockAuthAdapter ships
+for demos: deterministic 2FA code 000000, expireSession() driver.
+States that must exist: signed out, bad credentials (ONE combined message -
+no user enumeration), 2FA challenge with wrong-code path, session expired
+(session() returns null - redirect, no other signal), duplicate sign-up email.
+Rules that must hold: credential errors never confirm which half was wrong;
+the code field is six slots with paste distribution and full keyboard support;
+the mock never claims an email was sent.`,
+    team: `# Team
+Shell: in-shell content column.
+Registry items: venly-tokens, data-table, status-pill; block: team (TeamTable, InviteDialog).
+Binding: a TeamAdapter over your auth provider (createMockTeamAdapter for demos).
+States that must exist: ACTIVE/INVITED/DISABLED members on first paint, invite
+created (display-only link in mock - never a fake sent-email claim), role
+change persisting, self-actions blocked with the reason.
+Rules that must hold: member status is word + glyph; role controls live in the
+row; you cannot change your own role or disable yourself - the control is
+disabled AND explains why.`,
     "home-balances": `# Home / balances
 Shell: left nav rail + thin top bar; full-width content.
-Registry items: venly-tokens, balance-card, data-table, status-pill.
-Hooks: useAccounts, useVirtualBankAccounts; balances rendered per account/currency.
-States that must exist: loading, zero accounts (first-run guidance), balances with reserved buckets.
-Rules that must hold: available is the emphasised figure and the only one above the rule; reserved is demoted by position and scale, never colour; unspendable buckets carry the padlock; never assume stablecoin parity - render the quoted rate.`,
+Registry items: venly-tokens, balance-card, data-table, status-pill; block: balances (BalancesBlock, BalanceMiniature).
+Hooks: useAccounts, useWallets; balances rendered per asset across the account's wallets.
+States 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.
+Rules 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.`,
     receive: `# Receive
 Shell: content column - a warning callout, the field card, an advisory below.
 Registry items: venly-tokens, field-list; block: receive.
@@ -27,10 +50,16 @@ States that must exist: loading, empty ledger, rows with pending/failed pills, o
 Rules 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.`,
     "onboarding-status": `# Onboarding / verification status
 Shell: full page, form clamped ~600px; a status home once submitted.
-Registry items: venly-tokens, timeline, status-pill, field-list.
-Hooks: useParties, useCreateParty; verification status from the party/account records.
-States that must exist: collecting (per-section progress), submitted/waiting (say who acts next, on which channel, what still works meanwhile), approved, declined (humane copy + what to do next), re-verification on a live account.
-Rules that must hold: never render a fake progress percentage - use real per-item status; a waiting state answers how long / who acts / what still works; a decline explains and offers a next step, not a dead end; creating a party is NOT completed verification - show the honest state.`,
+Registry items: venly-tokens, timeline, status-pill, field-list; block: onboarding (CompanyForm, VerificationStatusHome, RestrictedBanner).
+Hooks: useCreateParty, useCreateAccount, useParty, useAccount; verification status from the party/account records verbatim.
+States 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).
+Rules 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.`,
+    "withdraw-bank-accounts": `# Withdraw + bank accounts (off-ramp)
+Shell: settings page for the whitelist; full page for the flow, form clamped ~600px.
+Registry items: venly-tokens, data-table, status-pill, timeline, field-list, arithmetic-ladder; blocks: bank-accounts (BankAccountsBlock, AddBankAccountForm), withdraw (WithdrawFlow, WithdrawalsTable, ConnectedWithdrawDetail).
+Hooks: useCompanyBankAccounts, useBankAccountConfig, useCreateCompanyBankAccount, useRampRequests, useRampRequest, useCreateRampRequest, useFeeQuote, useRampPairs, useReferenceData, useFourEyesApproval, useInitiateRamp, describeRampStatus.
+States 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.
+Rules 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.`,
     reconciliation: `# Reconciliation
 Shell: split pane (roughly one-third list, two-thirds evidence) - not a drawer.
 Registry items: venly-tokens, data-table, side-panel, status-pill, field-list.
@@ -51,15 +80,75 @@ States that must exist: queue with awaiting-approval items, detail with the deci
 Rules 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.`,
 };
 const JOURNEY_KEYS = Object.keys(JOURNEYS);
+// ---------------------------------------------------------------------------
+// Shared mechanics. Three cross-cutting behaviours every rule participates in:
+//
+// 1. Suppression: `venly-allow:<rule-id>` on the offending line or the line
+//    immediately above drops the finding silently - no counter, no second
+//    severity tier. A consumer's own API may legitimately return what ours
+//    does not; without this hatch the audit is uninstallable for them.
+// 2. Comment lines are not copy: rules that judge words skip lines whose
+//    trimmed form starts with `*`, `//`, `/*` or `{/*` - otherwise the rule
+//    fires on the comment that documents the rule itself.
+// 3. Findings carry the character index they fired at, so suppression can be
+//    resolved against the exact offending line.
+// ---------------------------------------------------------------------------
+const COMMENT_LINE = /^\s*(?:\*|\/\/|\/\*|\{\/\*)/;
+function lineBoundsAt(source, idx) {
+    const at = Math.min(Math.max(idx, 0), source.length);
+    const start = source.lastIndexOf("\n", Math.max(0, at - 1)) + 1;
+    const nl = source.indexOf("\n", at);
+    return { start, end: nl === -1 ? source.length : nl };
+}
+function lineAt(source, idx) {
+    const { start, end } = lineBoundsAt(source, idx);
+    return source.slice(start, end);
+}
+function lineAboveAt(source, idx) {
+    const { start } = lineBoundsAt(source, idx);
+    if (start === 0)
+        return "";
+    const prevEnd = start - 1; // the \n terminating the previous line
+    const prevStart = source.lastIndexOf("\n", prevEnd - 1) + 1;
+    return source.slice(prevStart, prevEnd);
+}
+function isCommentLineAt(source, idx) {
+    return COMMENT_LINE.test(lineAt(source, idx));
+}
+function isSuppressedAt(source, idx, ruleId) {
+    const token = `venly-allow:${ruleId}`;
+    return lineAt(source, idx).includes(token) || lineAboveAt(source, idx).includes(token);
+}
+function lineNumberAt(source, idx) {
+    let line = 1;
+    for (let i = 0; i < idx && i < source.length; i++)
+        if (source[i] === "\n")
+            line++;
+    return line;
+}
 /** Deterministic design audit. Text in, findings out - no model, no taste. */
-export function reviewScreenSource(source) {
+export function reviewScreenSource(source, journey) {
     const findings = [];
-    const push = (rule, severity, evidence, fix) => findings.push({ rule, severity, evidence: evidence.slice(0, 120), fix });
+    // Returns whether the finding was recorded, so rules that stop after the
+    // first hit can keep scanning past a suppressed occurrence instead of
+    // letting one venly-allow blind them to a later real violation.
+    const push = (rule, severity, evidence, fix, atIndex) => {
+        if (isSuppressedAt(source, atIndex, rule))
+            return false;
+        findings.push({
+            rule,
+            severity,
+            evidence: evidence.slice(0, 120),
+            fix,
+            line: lineNumberAt(source, atIndex),
+        });
+        return true;
+    };
     for (const match of source.matchAll(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)/g)) {
-        push("raw-colour", "error", match[0], "Read colours from the venly-tokens custom properties; a reskin must be tokens.css and nothing else.");
+        push("raw-colour", "error", match[0], "Read colours from the venly-tokens custom properties; a reskin must be tokens.css and nothing else.", match.index ?? 0);
     }
     for (const match of source.matchAll(/-\d[\d,]*\.\d{2}\s*(?:[A-Z]{3}|€|\$|£)/g)) {
-        push("hyphen-minus-amount", "error", match[0], "Use the true minus sign − before negative amounts (the Money primitive does this).");
+        push("hyphen-minus-amount", "error", match[0], "Use the true minus sign − before negative amounts (the Money primitive does this).", match.index ?? 0);
     }
     // Only a RENDERED cancelled state counts (a quoted/JSX label or a state
     // value), never the verb "cancel" in prose or a token file's comment; and
@@ -69,29 +158,238 @@ export function reviewScreenSource(source) {
         const idx = match.index ?? 0;
         const around = source.slice(Math.max(0, idx - 150), idx + 150);
         if (/✓/.test(around)) {
-            push("success-on-cancelled", "error", around.trim().slice(0, 80), "A cancelled or failed terminal step must never carry a success check - grey ↺ or red ✕.");
-            break;
+            if (push("success-on-cancelled", "error", around.trim().slice(0, 80), "A cancelled or failed terminal step must never carry a success check - grey ↺ or red ✕.", idx))
+                break;
         }
     }
-    if (/review|confirm/i.test(source) && /[•*]{3,}/.test(source)) {
-        push("masked-review-value", "error", source.match(/[•*]{3,}/)[0], "Never mask values on a review screen; its only job is legibility of what is about to happen.");
+    // The once-per-source rules below scan every occurrence and stop at the
+    // first RECORDED finding, so a venly-allow on one occurrence never hides a
+    // later unsuppressed one.
+    if (/review|confirm/i.test(source)) {
+        for (const masked of source.matchAll(/[•*]{3,}/g)) {
+            if (push("masked-review-value", "error", masked[0], "Never mask values on a review screen; its only job is legibility of what is about to happen.", masked.index ?? 0))
+                break;
+        }
     }
-    if (/nth-child\(\s*(?:even|odd|2n)/.test(source)) {
-        push("zebra-striping", "warn", "nth-child(even/odd) background", "No finance reference uses zebra striping - separate rows with hairlines and spacing.");
+    for (const zebra of source.matchAll(/nth-child\(\s*(?:even|odd|2n)/g)) {
+        if (push("zebra-striping", "warn", "nth-child(even/odd) background", "No finance reference uses zebra striping - separate rows with hairlines and spacing.", zebra.index ?? 0))
+            break;
     }
-    if (/box-shadow/.test(source) && !/var\(--shadow-overlay\)/.test(source)) {
-        push("shadow-outside-overlay", "warn", source.match(/box-shadow[^;"}]*/)?.[0] ?? "box-shadow", "Elevation is only for overlays, and only via the --shadow-overlay token; the base layer is flat.");
+    if (!/var\(--shadow-overlay\)/.test(source)) {
+        for (const shadow of source.matchAll(/box-shadow[^;"}]*/g)) {
+            if (push("shadow-outside-overlay", "warn", shadow[0], "Elevation is only for overlays, and only via the --shadow-overlay token; the base layer is flat.", shadow.index ?? 0))
+                break;
+        }
     }
-    if (/linear-gradient|radial-gradient/.test(source)) {
-        push("gradient-surface", "warn", source.match(/\w+-gradient\([^)]*\)/)?.[0] ?? "gradient", "Gradient balance heroes read as template, not product; surfaces are flat neutrals with one accent.");
+    for (const gradient of source.matchAll(/(?:linear|radial)-gradient(?:\([^)]*\))?/g)) {
+        if (push("gradient-surface", "warn", gradient[0], "Gradient balance heroes read as template, not product; surfaces are flat neutrals with one accent.", gradient.index ?? 0))
+            break;
     }
-    if (/(?:status|state)/i.test(source) && /var\(--state-/.test(source)) {
-        if (!/[✓✕↺⚠●○]|aria-hidden/.test(source)) {
-            push("colour-only-state", "warn", "state colours present without any glyph", "Pair every state hue with a glyph or word so status survives greyscale.");
+    if (/(?:status|state)/i.test(source) && !/[✓✕↺⚠●○]|aria-hidden/.test(source)) {
+        for (const stateVar of source.matchAll(/var\(--state-/g)) {
+            if (push("colour-only-state", "warn", "state colours present without any glyph", "Pair every state hue with a glyph or word so status survives greyscale.", stateVar.index ?? 0))
+                break;
         }
     }
+    // --- New rule classes (invented timing copy, crypto currency formatting,
+    // required-rendered-optional, blueprint state coverage, fixture honesty)
+    // are registered below. Each judges text only, honours the suppression
+    // hatch, and skips comment lines wherever it judges copy.
+    checkInventedTimingClaim(source, push);
+    checkIntlCurrencyCrypto(source, push);
+    checkRequiredRenderedOptional(source, push);
+    checkBlueprintStateCoverage(source, journey, push);
+    checkFixtureHonesty(source, push);
     return findings;
 }
+/**
+ * invented-timing-claim - copy that promises a duration, a settlement window
+ * or custody behaviour ("1-2 business days", "held until claimed",
+ * "estimated arrival") that no API in this stack returns. Rendering such a
+ * promise invents a guarantee the backend cannot honour; the journey
+ * contracts require a labelled omission instead. Copy rule: comment lines
+ * are not copy, so matches on them are skipped.
+ */
+function checkInventedTimingClaim(source, push) {
+    const pattern = /\b(?:typically|usually|normally|generally)\s+(?:arrives?|takes?|clears?|settles?)\b|\b\d+\s*(?:-|–|to)\s*\d+\s+business\s+days?\b|\bwithin\s+\d+\s+(?:seconds?|minutes?|hours?|days?|business\s+days?)\b|\bheld\s+until\s+claimed\b|\bestimated\s+(?:arrival|delivery|completion)\b/gi;
+    for (const match of source.matchAll(pattern)) {
+        const at = match.index ?? 0;
+        if (isCommentLineAt(source, at))
+            continue;
+        push("invented-timing-claim", "error", match[0], "No API in this stack returns a duration, settlement window or custody guarantee. Render the labelled omission the contract specifies, or - if your own API does return it - name the field path on the line and add venly-allow:invented-timing-claim.", at);
+    }
+}
+// --- intl-currency-crypto -------------------------------------------------
+// Intl.NumberFormat validates `currency` against ISO 4217, so a crypto asset
+// code ("USDC", "DAI", ...) throws RangeError the moment the formatter is
+// constructed - a screen that compiles fine crashes on first render. Each
+// Intl.NumberFormat call site is judged by the 200 characters that follow it:
+// a literal crypto code next to style:"currency" is a certain crash (error);
+// a variable-fed `currency:` is a latent one (warn) - it only survives until
+// a crypto asset reaches it. Not a copy rule, so comment lines are not
+// skipped; suppression still applies via the shared venly-allow hatch.
+function checkIntlCurrencyCrypto(source, push) {
+    const currencyStyle = /style\s*:\s*["']currency["']/;
+    const cryptoCode = /["'](?:USDC|EURC|USDT|USDS|DAI|PYUSD|USDG|RLUSD)["']/;
+    // `\s*` lives inside the lookahead: with `currency\s*:\s*(?!["'])` the
+    // greedy whitespace backtracks to zero and the lookahead inspects the
+    // space instead of the quote, flagging `currency: "USD"` as a variable.
+    const variableCurrency = /currency\s*:(?!\s*["'])/;
+    for (const match of source.matchAll(/Intl\.NumberFormat/g)) {
+        const at = match.index ?? 0;
+        const window = source.slice(at, at + 200);
+        const style = currencyStyle.exec(window);
+        if (!style)
+            continue; // plain decimal formatting (the kit's own formatAmount) is safe
+        const styleAt = style.index ?? 0;
+        const crypto = cryptoCode.exec(window);
+        if (crypto) {
+            const cryptoAt = crypto.index ?? 0;
+            const from = Math.min(styleAt, cryptoAt);
+            const to = Math.max(styleAt + style[0].length, cryptoAt + crypto[0].length);
+            push("intl-currency-crypto", "error", window.slice(from, to), "Intl.NumberFormat with style:\"currency\" throws RangeError on a non-ISO-4217 code. Render crypto amounts with the Money primitive, which places the code beside the digits instead of inside the formatter.", at);
+            continue; // one finding per call site; the certain crash outranks the latent one
+        }
+        const variable = variableCurrency.exec(window);
+        if (variable) {
+            const variableAt = variable.index ?? 0;
+            const from = Math.min(styleAt, variableAt);
+            const to = Math.min(window.length, Math.max(styleAt + style[0].length, variableAt) + 40);
+            push("intl-currency-crypto", "warn", window.slice(from, to), "This formatter takes its currency from a variable. If a crypto asset can reach it, it throws at runtime. Use the Money primitive, or narrow the variable to ISO-4217 codes.", at);
+        }
+    }
+}
+/**
+ * A required field labelled as optional. The kit deliberately ships a
+ * "(not required)" variant for genuinely optional rows, so the net is scoped
+ * tightly: only the payment reference is required-by-contract, and a payer
+ * who omits it produces an unmatched credit that someone has to reconcile by
+ * hand. The rule therefore fires only when "(not required)" appears on a real
+ * code line AND the surrounding code (comments removed) mentions the
+ * reference - a comment that merely documents this contract must not trip it.
+ */
+function checkRequiredRenderedOptional(source, push) {
+    for (const match of source.matchAll(/\(not required\)/gi)) {
+        const idx = match.index ?? 0;
+        // Copy rule: only judge rendered copy, never commentary about it.
+        if (isCommentLineAt(source, idx))
+            continue;
+        const winStart = Math.max(0, idx - 200);
+        const winEnd = Math.min(source.length, idx + match[0].length + 200);
+        // Rebuild the window with every comment line removed. Each line is
+        // classified on its FULL text (a fragment cut by the window edge could
+        // hide its comment marker), but only the in-window portion of surviving
+        // code lines feeds the reference test.
+        let pos = source.lastIndexOf("\n", Math.max(0, winStart - 1)) + 1;
+        let window = "";
+        while (pos < winEnd) {
+            let lineEnd = source.indexOf("\n", pos);
+            if (lineEnd === -1)
+                lineEnd = source.length;
+            const line = source.slice(pos, lineEnd);
+            if (!COMMENT_LINE.test(line)) {
+                const from = Math.max(pos, winStart);
+                const to = Math.min(lineEnd, winEnd);
+                if (to > from)
+                    window += source.slice(from, to) + "\n";
+            }
+            pos = lineEnd + 1;
+        }
+        if (!/reference/i.test(window))
+            continue;
+        push("required-rendered-optional", "error", lineAt(source, idx).trim(), 'The payment reference is required - a payer who omits it produces an unmatched credit. Render the amber Required pill; never label it "(not required)".', idx);
+    }
+}
+function checkBlueprintStateCoverage(source, journey, push) {
+    // Only meaningful when the caller declared which journey this screen serves.
+    if (journey === undefined)
+        return;
+    // Whole-source suppression: this finding has no single offending line (it
+    // reports blueprint states absent from the entire file), so the escape
+    // hatch is whole-source too - the venly-allow token anywhere drops it.
+    if (source.includes("venly-allow:blueprint-state-missing"))
+        return;
+    const blueprint = JOURNEYS[journey];
+    const startMarker = "States that must exist:";
+    const startIdx = blueprint.indexOf(startMarker);
+    if (startIdx === -1)
+        return;
+    let statesText = blueprint.slice(startIdx + startMarker.length);
+    const end = /^Rules that must hold/m.exec(statesText);
+    if (end)
+        statesText = statesText.slice(0, end.index);
+    // Blueprint prose wraps across lines mid-sentence; collapse before parsing.
+    statesText = statesText.replace(/\n/g, " ");
+    // One state per " · " or "," separator - but only at parenthesis depth 0:
+    // a comma inside a parenthetical is part of that state's description, not
+    // a state boundary. Naive splitting yields fragments like "terminal)" that
+    // no source can contain, making a journey structurally unable to pass.
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of statesText) {
+        if (ch === "(")
+            depth++;
+        else if (ch === ")")
+            depth = Math.max(0, depth - 1);
+        if (depth === 0 && (ch === "," || ch === "·")) {
+            parts.push(current);
+            current = "";
+            continue;
+        }
+        current += ch;
+    }
+    parts.push(current);
+    // Each state's keyword is the text before the first parenthetical,
+    // normalised for a case-insensitive substring probe.
+    const keywords = [];
+    for (const part of parts) {
+        const keyword = part
+            .split("(")[0]
+            .trim()
+            .toLowerCase()
+            .replace(/\s+/g, " ")
+            .replace(/\.$/, "");
+        if (keyword)
+            keywords.push(keyword);
+    }
+    const lowered = source.toLowerCase();
+    const missing = keywords.filter((keyword) => !lowered.includes(keyword));
+    if (missing.length === 0)
+        return;
+    // One aggregate warn, never per-keyword findings and never an empty-list
+    // finding. Warn (not error) because blueprint phrases are prose - a state
+    // can be fully implemented under different wording.
+    const list = missing.join(", ");
+    push("blueprint-state-missing", "warn", list, `The ${journey} blueprint names ${keywords.length} states. These were not found by name in this source: ${list}. Either they are missing or they render under different wording - check each by hand.`, 0);
+}
+function checkFixtureHonesty(source, push) {
+    // Fixture honesty. A demo that seeds parity rates or round-number amounts
+    // teaches false patterns: parity hides the crypto/fiat unit distinction,
+    // and round numbers let a total look derivable when it is coincidence.
+    // ERROR - an explicit parity rate seeded on a rate-named field. Anchored to
+    // the three rate names so counters like `rateLimit: 1` never trip it.
+    for (const match of source.matchAll(/\b(?:exchangeRate|rate|fxRate)\s*[:=]\s*1(?:\.0+)?\b/g)) {
+        push("parity-fixture", "error", match[0], "A parity exchange rate makes the crypto/fiat unit distinction numerically invisible, which is the falsehood a real quoted rate exists to prevent. Seed a real non-parity rate.", match.index ?? 0);
+    }
+    // WARN - three or more round-number amounts (x.00) in one source. Comment
+    // lines are skipped: this sibling judges seeded copy/fixtures, and prose
+    // like "may display as 0.00" is documentation, not a seeded amount. One
+    // finding per source, anchored at the first counted match.
+    let roundCount = 0;
+    let firstRoundIdx = -1;
+    for (const match of source.matchAll(/\b\d+\.00\b/g)) {
+        const idx = match.index ?? 0;
+        if (isCommentLineAt(source, idx))
+            continue;
+        if (firstRoundIdx === -1)
+            firstRoundIdx = idx;
+        roundCount++;
+    }
+    if (roundCount >= 3) {
+        push("round-number-coincidence", "warn", `${roundCount} round-number (.00) amounts seeded in one source`, "Round-number fixtures hide arithmetic. If a total is coincidentally equal to a part, the screen teaches a false pattern - use amounts that do not divide evenly.", firstRoundIdx);
+    }
+}
 const AGENTS_TEXT = `# Composition rules for coding agents building on the Venly UI registry
 
 Delivery: the shadcn CLI expects a working shadcn environment BEFORE any
@@ -104,7 +402,7 @@ registry install. On a fresh Vite/React app that means, in order:
    works - it never imports base-library components itself).
 3. Add the registry once to components.json -
   { "registries": { "@venlyfinance": "${REGISTRY_URL_TEMPLATE}" } }
-4. \`npx shadcn@latest add @venlyfinance/receive @venlyfinance/send @venlyfinance/activity -y -o\`.
+4. \`npx shadcn@latest add @venlyfinance/balances @venlyfinance/activity @venlyfinance/receive @venlyfinance/send @venlyfinance/auth @venlyfinance/team @venlyfinance/onboarding -y -o\`.
    Each block auto-installs its components, the venly-tokens file AND its
    npm dependencies (@venlyfinance/react, @venlyfinance/sdk, TanStack
    Query) - no separate npm install step is needed.
@@ -128,8 +426,14 @@ installed venly-tokens css once at the app root.
    on "stale-version" refetch and let the operator re-decide.
 5. Theme by editing the installed venly-tokens css file and nothing else.
 6. Before declaring a screen done, run the review_screen tool on its source
-   and fix every error-severity finding. Consult get_journey_blueprint
-   before designing a screen the registry has no block for.
+   (pass the journey key so blueprint state coverage is checked too) and fix
+   every error-severity finding. Consult get_journey_blueprint before
+   designing a screen the registry has no block for.
+7. Wire the same audit into the app you generate as a CI step - it is what
+   turns the design contract into a gate:
+   \`npx @venlyfinance/settlement-mcp review "src/**/*.tsx"\`
+   (exit 1 on any error-severity finding). A deliberate, justified exception
+   carries venly-allow:<rule-id> on the offending line or the line above.
 `;
 export function registerFrontendTools(server) {
     server.registerTool("get_journey_blueprint", {
@@ -143,12 +447,16 @@ export function registerFrontendTools(server) {
     }));
     server.registerTool("review_screen", {
         title: "Design-audit a screen",
-        description: "Deterministic audit of component/markup source against the kit's design contract: raw colours, hyphen-minus amounts, success styling on cancelled steps, masked review values, zebra striping, off-token shadows, gradients, colour-only state. Returns findings, not a score.",
+        description: "Deterministic audit of component/markup source against the kit's design contract: raw colours, hyphen-minus amounts, success styling on cancelled steps, masked review values, invented timing/custody copy, crypto codes inside Intl currency formatting, required fields rendered optional, parity and round-number fixtures, zebra striping, off-token shadows, gradients, colour-only state. Pass the journey key to also check the source against that journey's required blueprint states. Suppress a deliberate exception with venly-allow:<rule-id> on the offending line or the line above. Returns findings, not a score.",
         inputSchema: {
             source: z.string().min(1).describe("The component/markup/CSS source to audit"),
+            journey: z
+                .enum(JOURNEY_KEYS)
+                .optional()
+                .describe("Optional: which journey this screen implements - enables the blueprint state-coverage check"),
         },
-    }, async ({ source }) => {
-        const findings = reviewScreenSource(source);
+    }, async ({ source, journey }) => {
+        const findings = reviewScreenSource(source, journey);
         return {
             content: [
                 {

package/dist/index.js

@@ -27,7 +27,24 @@ async function main() {
             : "writes DISARMED: mutations return dry-run previews (arming needs confirm:true + VENLY_MCP_LIVE=1 + credentials)";
     process.stderr.write(`venly-finance-mcp started in ${client.environment}. ${writeState}.\n`);
 }
-main().catch((err) => {
-    process.stderr.write(`Fatal: ${err.message}\n`);
-    process.exit(1);
-});
+const argv = process.argv.slice(2);
+if (argv[0] === "review") {
+    // Design-audit CLI mode: `... review "src/**/*.tsx"`. Dynamic import so the
+    // MCP/SDK path is never touched; MCP hosts launch with zero args, so plain
+    // startup is unchanged.
+    import("./review-cli.js")
+        .then(({ runReviewCli }) => runReviewCli(argv.slice(1)))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((err) => {
+        process.stderr.write(`Fatal: ${err.message}\n`);
+        process.exit(2);
+    });
+}
+else {
+    main().catch((err) => {
+        process.stderr.write(`Fatal: ${err.message}\n`);
+        process.exit(1);
+    });
+}

package/dist/resources.js

@@ -15,14 +15,16 @@ Venly Finance provides financial infrastructure through several regulated partne
 - fiat-to-crypto payment sessions;
 - account-to-account fiat-denominated and crypto-denominated transfers;
 - payment-request authorization, settlement and reversal primitives;
+- third-party payouts (contract 1.3.0): beneficiary bank accounts registered per party (SEPA and US ACH, masked details), payout routes activated by wallet-ownership proof, and payouts with a full lifecycle (REQUESTED through COMPLETED, REJECTED, FAILED or RETURNED, failures carrying a reason);
 - Fundflow on/off-ramp workflows with four-eyes approval.
 
 Current boundaries:
 
-- EUR is the currently documented virtual-bank-account currency. Do not infer global bank-account coverage.
+- EUR SEPA and USD ACH are the documented virtual-bank-account types. Do not infer global bank-account coverage.
 - Creating a party does not complete KYC/KYB. Live virtual-bank-account provisioning requires a VERIFIED account.
+- The payout surface is on the QA contract (Finance API 1.3.0); production may trail it. Verify against the environment you target.
 - Card issuing is not exposed by the current Finance OpenAPI contract.
-- A bank charter, deposit insurance and external-bank payout coverage are not supplied or implied by this MCP.
+- A bank charter and deposit insurance are not supplied or implied by this MCP.
 - Production x402 settlement is not implemented; the x402 tool is a quote-only stub.
 `,
     },
@@ -33,7 +35,7 @@ Current boundaries:
         description: "Environment, write, compliance and secret-handling rules.",
         text: `# Venly Finance MCP safety
 
-- Set VENLY_ENV explicitly to mock, staging or production. An absent value defaults to mock (since 0.3.0), so an unconfigured server never points at real infrastructure.
+- Set VENLY_ENV explicitly to mock, qa, staging or production. An absent value defaults to mock (since 0.3.0), so an unconfigured server never points at real infrastructure.
 - Mock mode uses synthetic SDK fixtures, no credentials and no network. Every mutation result is labelled mode=mock.
 - Staging writes require confirm=true, VENLY_MCP_LIVE=1 and VENLY_CLIENT_ID/VENLY_CLIENT_SECRET.
 - Production requires every staging gate plus VENLY_MCP_PRODUCTION=1.

package/dist/review-cli.d.ts

@@ -0,0 +1,4 @@
+/** Expand one glob pattern (posix-style separators) relative to cwd. */
+export declare function expandPattern(pattern: string, cwd: string): string[];
+export declare function expandPatterns(patterns: string[], cwd: string): string[];
+export declare function runReviewCli(args: string[], out?: NodeJS.WritableStream, err?: NodeJS.WritableStream): Promise<0 | 1 | 2>;

package/dist/review-cli.js

@@ -0,0 +1,131 @@
+// `review` subcommand: the review_screen design audit as a CI gate.
+//
+//   npx @venlyfinance/settlement-mcp review "src/**/*.tsx"
+//
+// Exit codes: 0 clean (warnings allowed, printed either way) · 1 at least one
+// error-severity finding · 2 usage error or a pattern that matched nothing
+// (a typo'd path must never pass CI silently).
+//
+// Patterns are self-expanded (**, *, {a,b}) so the quoted form works on any
+// shell; unquoted shell-expanded literal paths work too. No dependencies.
+// (Line comments on purpose: a glob's **/ would terminate a block comment.)
+import { readdirSync, readFileSync, statSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+import { reviewScreenSource } from "./frontend.js";
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist"]);
+function braceExpand(pattern) {
+    const m = /\{([^{}]*)\}/.exec(pattern);
+    if (!m)
+        return [pattern];
+    const before = pattern.slice(0, m.index);
+    const after = pattern.slice(m.index + m[0].length);
+    const out = [];
+    for (const option of m[1].split(",")) {
+        out.push(...braceExpand(before + option + after));
+    }
+    return out;
+}
+function patternToRegExp(pattern) {
+    // Escape everything regex-special except the glob characters we translate.
+    const escaped = pattern.replace(/[.+^$()|[\]\\?]/g, "\\$&");
+    const translated = escaped
+        .replace(/\*\*\//g, "\u0000") // **/ may match zero segments
+        .replace(/\*\*/g, "\u0001") // a bare ** matches anything
+        .replace(/\*/g, "[^/]*")
+        .replace(/\u0000/g, "(?:.*/)?")
+        .replace(/\u0001/g, ".*");
+    return new RegExp(`^${translated}$`);
+}
+function walk(dir, into) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name))
+                walk(join(dir, entry.name), into);
+        }
+        else if (entry.isFile()) {
+            into.push(join(dir, entry.name));
+        }
+    }
+}
+/** Expand one glob pattern (posix-style separators) relative to cwd. */
+export function expandPattern(pattern, cwd) {
+    const results = [];
+    for (const variant of braceExpand(pattern)) {
+        const segments = variant.split("/");
+        const firstWild = segments.findIndex((s) => s.includes("*"));
+        if (firstWild === -1) {
+            if (existsSync(join(cwd, variant)) && statSync(join(cwd, variant)).isFile()) {
+                results.push(variant);
+            }
+            continue;
+        }
+        const staticPrefix = segments.slice(0, firstWild).join("/");
+        const root = staticPrefix ? join(cwd, staticPrefix) : cwd;
+        const files = [];
+        walk(root, files);
+        const matcher = patternToRegExp(variant);
+        for (const file of files) {
+            // relative(), not string slicing: a pattern like "../ui/**/*.tsx"
+            // walks outside cwd, where prefix slicing produces garbage.
+            const rel = relative(cwd, file).split("\\").join("/");
+            if (matcher.test(rel))
+                results.push(rel);
+        }
+    }
+    return [...new Set(results)].sort();
+}
+export function expandPatterns(patterns, cwd) {
+    const out = [];
+    for (const pattern of patterns) {
+        if (/[*{]/.test(pattern)) {
+            out.push(...expandPattern(pattern.split("\\").join("/"), cwd));
+        }
+        else {
+            out.push(pattern); // shell-expanded or literal; existence checked by caller
+        }
+    }
+    return [...new Set(out)];
+}
+export async function runReviewCli(args, out = process.stdout, err = process.stderr) {
+    const patterns = args.filter((a) => !a.startsWith("-"));
+    if (patterns.length === 0) {
+        err.write('Usage: review "<glob>" [more globs or files]\n' +
+            '  e.g. review "src/**/*.tsx"\n' +
+            "Exits 1 on any error-severity finding, 2 when nothing matched.\n");
+        return 2;
+    }
+    const cwd = process.cwd();
+    const files = expandPatterns(patterns, cwd);
+    const missing = files.filter((f) => !existsSync(f));
+    if (missing.length > 0) {
+        err.write(`No such file: ${missing.join(", ")}\n`);
+        return 2;
+    }
+    if (files.length === 0) {
+        err.write(`Nothing matched: ${patterns.join(" ")}\n`);
+        return 2;
+    }
+    let errors = 0;
+    let warnings = 0;
+    for (const file of files) {
+        const findings = reviewScreenSource(readFileSync(file, "utf8"));
+        for (const finding of findings) {
+            if (finding.severity === "error")
+                errors++;
+            else
+                warnings++;
+            const line = finding.line === undefined ? "" : `:${finding.line}`;
+            out.write(`${file}${line}  ${finding.severity}  ${finding.rule}  ${finding.evidence}\n`);
+            out.write(`  fix: ${finding.fix}\n`);
+        }
+    }
+    out.write(`${errors} error(s), ${warnings} warning(s) across ${files.length} file(s)\n`);
+    return errors > 0 ? 1 : 0;
+}