@venlyfinance/settlement-mcp 0.6.0 → 0.7.1

package/AGENTS.md

@@ -9,7 +9,7 @@ You are building a financial product UI on `@venlyfinance/react`. These rules ex
 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.
+6. **Gate both the screen and its runtime contract, and wire both into CI.** Run `npx @venlyfinance/settlement-mcp review "src/**/*.tsx"` for the design contract and `npx @venlyfinance/settlement-mcp verify "src/**/*.{ts,tsx}"` for package/provider/hook/proxy composition. Each fails (exit 1) on any error-severity finding. A deliberate, justified exception carries `venly-allow:<rule-id>` on the offending line or the line above.
 
 ## Rendering money states
 
@@ -32,4 +32,4 @@ The UI kit's auth and team blocks therefore render against two adapter interface
 ## 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.
+create party → `advanceVerification(id)` → create account → virtual bank account (note its `referenceCode`) → **fund it: `simulations.inbound.credit(vbaId, 500)`** (a new account holds nothing, as in production; an unfunded transfer is refused with `402 insufficient-funds`) → stage + confirm a transfer → `advanceTransfer(id)` → show the ledger, and `simulations.ledger.verify()` to prove it balances. Inject failures with `failNext("CONFLICT")` to show the stale-version approval path – error states are part of the product.

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.7.1 – 2026-08-21
+
+- Republish so the packaged blueprints carry the corrected npm ranges for
+  `@venlyfinance/react` (`^0.5.0`) and `@venlyfinance/sdk` (`^0.6.0`). The
+  0.7.0 tarball was cut before that fix landed, so its blueprints told agents
+  to install ranges that never reach the versions the registry blocks import.
+  No behaviour change beyond the stamped ranges.
+
+## 0.7.0 – 2026-08-19
+
+The MCP now pushes a machine-checkable runtime contract instead of relying on
+agents to discover composition guidance through optional pull surfaces.
+
+- The initialize response carries server instructions that establish
+  `@venlyfinance/react` hooks and flow machines as the browser data plane,
+  `@venlyfinance/sdk` as the server data plane, and the shadcn registry as the
+  UI installation path.
+- Every `get_journey_blueprint` response keeps its prose blueprint and adds the
+  same `runtime_contract` as fenced JSON and `structuredContent`: exact registry
+  dependencies, qualified hook imports, provider configuration, forbidden
+  hand-rolled patterns, install commands, and completion gates.
+- New deterministic `verify` CLI and `verify_runtime_contract` MCP tool with
+  auto-detected `direct-sdk` and `backend-proxy` profiles. Exit codes match the
+  `review` CLI (0 clean, 1 on errors, 2 on usage/no-match), and
+  `venly-allow:<rule-id>` suppressions work on verifier findings.
+- Money-route-without-SDK, in-memory-money-store, and direct-profile missing
+  React checks remain warning-only pending a false-positive-boundary ruling.
+- Requires `@venlyfinance/sdk` ^0.5.0.
+
 ## 0.3.0 – 2026-08-04
 
 Wording-is-the-safety-surface release. An outside integrator audit (2026-08-04) found the server's words disagreeing with its behavior in three

package/README.md

@@ -13,9 +13,9 @@ Start in explicit mock mode with no credentials or network. Move the same SDK
 business logic to staging only after reviewing capabilities, compliance state and
 the normalized write requests. Staging and production writes fail closed.
 
-The Venly Finance builder surface documented here is the v0.2.0 release line.
+The Venly Finance builder surface documented here is the v0.7.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.
+Building with a coding agent? Start from [AGENTS.md](AGENTS.md) - the MCP also serves it as the `venly://frontend/agents` resource and pushes the core runtime doctrine in its initialize response.
 
 ## What it is
 
@@ -124,8 +124,12 @@ Delivery of UI source rides the shadcn registry standard – add
 to `components.json`, then `npx shadcn@latest add @venlyfinance/receive`. The MCP carries
 what a registry cannot:
 
-- `get_journey_blueprint` – screen inventory, required states, registry items and binding
-  hooks for eight money-product journeys.
+- `get_journey_blueprint` – screen inventory and required states for eleven
+  money-product journeys, plus a machine-readable `runtime_contract` containing
+  exact package versions, qualified hooks, provider setup, forbidden patterns,
+  install commands and completion checks.
+- `verify_runtime_contract` – deterministic runtime-contract checks over supplied
+  source and package metadata, using the same profiles and rules as the CLI.
 - `review_screen` – deterministic design audit of a screen's source (raw colours,
   hyphen-minus amounts, success styling on cancelled steps, masked review values,
   invented timing/custody copy, crypto codes inside `Intl.NumberFormat` currency
@@ -157,6 +161,22 @@ Scope the glob to component source, never to token or theme files: the
 css file is the one legitimate home of raw colour values (theming stays a
 one-file edit). `"src/**/*.tsx"` is the right default.
 
+### Runtime-contract CLI
+
+Gate the data-plane composition alongside the screen audit:
+
+```bash
+npx @venlyfinance/settlement-mcp verify "src/**/*.{ts,tsx}"
+```
+
+The verifier auto-detects `direct-sdk` (browser provider + hooks) or
+`backend-proxy` (browser proxy options + SDK-backed server routes). Override
+with `--profile direct-sdk` or `--profile backend-proxy`. Exit codes are `0`
+when no error findings exist, `1` when any error exists, and `2` for usage or
+no-match failures; warnings print but do not fail. The same
+`venly-allow:<rule-id>` token suppresses a deliberate finding on its line or
+the line above.
+
 ## Safety model (fail closed)
 
 Outside explicit mock mode, read-only/dry-run is the default posture. A staging
@@ -323,6 +343,7 @@ settlement-mcp/
     resources.ts          capability, safety and workflow resources
     prompts.ts            build_international_account prompt
     results.ts            text + structured output and error redaction
+    verify-cli.ts         runtime-contract profiles, checks and CLI
     staging-smoke.ts      safe discovery/read/dry-run staging verification
     client/
       sdk-client.ts       Adapter over @venlyfinance/sdk

package/dist/constants.d.ts

@@ -1,7 +1,8 @@
 /** 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.6.0";
+export declare const SERVER_VERSION = "0.7.1";
+export declare const INSTRUCTIONS = "Venly Finance build advisor. This server is a build-time advisor, not your app's data plane. The data plane is the published packages: every read is a hook and every regulated lifecycle a flow machine from `@venlyfinance/react`, inside `<VenlyProvider environment=\"mock\">` \u2013 zero credentials, zero network; server-side code uses `@venlyfinance/sdk`. Hand-rolled fetch layers, in-memory money stores, or route handlers that re-implement transfers, balances, or approvals are off-contract and fail review. UI installs from the @venlyfinance shadcn registry: `npx shadcn@latest add @venlyfinance/balances @venlyfinance/send \u2026` (auto-installs the npm packages). Before scaffolding, read `venly://frontend/agents` \u2013 it is the composition doctrine (AGENTS.md). Consult `get_journey_blueprint` per screen; gate finished screens with `review_screen` and `npx @venlyfinance/settlement-mcp review \"src/**/*.tsx\"`.";
 export declare const ENVIRONMENT_FLAG = "VENLY_ENV";
 export type VenlyEnvironment = "mock" | "qa" | "staging" | "production";
 export declare function resolveVenlyEnvironment(env: Record<string, string | undefined>): VenlyEnvironment;

package/dist/constants.js

@@ -1,7 +1,8 @@
 /** 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.6.0";
+export const SERVER_VERSION = "0.7.1";
+export const INSTRUCTIONS = `Venly Finance build advisor. This server is a build-time advisor, not your app's data plane. The data plane is the published packages: every read is a hook and every regulated lifecycle a flow machine from \`@venlyfinance/react\`, inside \`<VenlyProvider environment="mock">\` – zero credentials, zero network; server-side code uses \`@venlyfinance/sdk\`. Hand-rolled fetch layers, in-memory money stores, or route handlers that re-implement transfers, balances, or approvals are off-contract and fail review. UI installs from the @venlyfinance shadcn registry: \`npx shadcn@latest add @venlyfinance/balances @venlyfinance/send …\` (auto-installs the npm packages). Before scaffolding, read \`venly://frontend/agents\` – it is the composition doctrine (AGENTS.md). Consult \`get_journey_blueprint\` per screen; gate finished screens with \`review_screen\` and \`npx @venlyfinance/settlement-mcp review "src/**/*.tsx"\`.`;
 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

package/dist/frontend.d.ts

@@ -14,13 +14,18 @@ declare const JOURNEYS: {
     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 send: "# Send (one door)\nShell: full page; the door is the recipient picker; forms clamp ~600px; the\nreview and the step-up ceremony replace the form in place.\nRegistry items: venly-tokens, status-pill, field-list, data-table, list-error;\nblocks: send (SendDoor, RecipientPicker, DirectoryPick, PlatformTransferFlow,\nPayoutSendFlow, SendReview, StepUpConfirm, TransferDetail, PayoutDetail) and\nrecipients (RecipientsView, AddRecipientForm, BeneficiaryAccountForm,\nRouteCeremony) - the prerequisite surface saved recipients are managed on.\nHooks: useCreateFiatTransfer and useCreateCryptoTransfer (the staged-transfer\nmachine typed per rail), useRequestPayout, usePartyRoles, useAddPartyRole,\nuseCreateParty, useRegisterPayoutBankAccount, useCreatePayoutRoute,\nusePreparePayoutOwnershipProof, useCompletePayoutOwnershipProof, useParties,\nuseAccounts, useWallets, useAccountSupportedAssets, useTransfers, useTransfer,\nusePayouts, usePayout, usePayoutRoutes.\nBinding: ONE door - the first screen is the recipient picker and the fork is\nthe recipient's OBJECT TYPE, never a rail choice. A person or business on the\nplatform (a directory YOUR user table serves; render name + handle, never a\nUUID - ids stay request-side) starts an on-platform transfer. A saved\nrecipient - a party holding the payout-recipient role, owning reviewed bank\naccounts (details masked server-side) and an ACTIVE payout route - starts a\nthird-party payout referencing the ROUTE, never raw bank details. Your own\nbank account is a link row into the withdraw flow. Send-to-external-wallet\nhas NO surface: no teaser, no disabled row, no rendered trace.\nStates that must exist: recipient picker (three classes, populated and empty), disabled with the reason (unverified directory rows, non-active routes and non-active accounts), over-balance, review (known figures only), step-up (wrong code blocks, the deterministic demo code proceeds), pending, completed, failed (the record's own error verbatim, terminal), requested, sending, provider processing, rejected, returned (money came back - a neutral terminal), no active route (blocked start with the unblocking CTA), load failure (explicit error plus retry - never an empty detail).\nRules that must hold: every money confirm passes the step-up ceremony against\nYOUR auth adapter and the commit fires only after the code verifies - this is\napp-side ceremony and must never be presented as an API security guarantee;\nexecution is single-shot on an idempotency key minted ONCE per staged draft,\nso a retry replays the same record instead of moving money twice; reviews\nrender ONLY figures the API has produced, and the payout review states the\nabsence in words beside the two-sided units sentence. Forbidden to invent\n(render the labelled omission or nothing at all): a fee row - and equally a\n\"No fee\" claim, since no source confirms zero; an ETA or delivery date - no\ntiming field exists on transfers or payouts; a pre-create rate or\nrecipient-gets figure - exchangeRate and settledFiatAmount exist on CREATED\nand COMPLETED records only; named in-flight stages beyond the status enums -\nrender the app-side observation log instead. Beneficiary details come back\nmasked: render the mask, never re-ask. Route states render verbatim and a\nREJECTED route is terminal-negative with a way forward, never a dead end.";
     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.";
+    readonly "console-review-queue": "# Console review queue (the operator worklist)\nShell: left nav rail + thin top bar, full-width content, and a page-edge\nenvironment banner naming mock mode. Not a consumer surface - density rules\napply.\nRegistry items: venly-tokens, data-table, status-pill, money, list-error;\nblocks: console-queue (ConsoleQueue, WhoseMove, AgeCell, deriveKycActor,\nderivePayoutActor - the derivation functions are exported so a consumer can\nunit-test the join).\nHooks: useAccounts, useParties. The queue's own state is DERIVED on every\nrender - never stored, never cached as a status.\nBinding: sections are ACTORS, not statuses - your move, waiting on the customer,\nwaiting on a provider, then a collapsed closed section, so the reviewer's own\nworklist is the top band by construction.\nStates that must exist: loading, your move, waiting on the customer, waiting on a provider, closed, empty queue, filtered to nothing, list error.\nRules that must hold: the whose-move value is a pure function of enum values on\nthe row - no clock reading, no threshold, no configuration and no default, and a\ncombination the mapping does not cover renders NO value plus an explicit\nnot-recognised line, which is a bug report rather than a guess; never a target\ntime, a breach colour or an overdue state, because the API publishes no targets\nand an invented one is the same defect as an invented fee; an age column is\nlabelled for what it actually measures - a created-at delta is \"Age\", and only a\nduration the API itself computes may be called time in state; empty sections are\nstill drawn as a zero header row, because nothing-to-do is information; loading\nis a skeleton that preserves column geometry exactly, never prose; a row click\nopens a side panel and never navigates; one status pill per row - the whose-move\nvalue is plain text, since two pills read as two states.";
+    readonly "console-decision-detail": "# Console decision detail (evidence, ceremony, audit trail)\nShell: side panel about 30% wide over the queue - no scrim, the table stays\nvisible clipped at the panel edge and the source row stays tinted. Escalate to a\n35/65 split only when the evidence outgrows the panel. Evidence goes on the\nLEFT: this is a judging task, not an authoring one.\nRegistry items: venly-tokens, side-panel, timeline, field-list, status-pill,\nmoney, data-table; blocks: console-decision (ConsoleDecisionPanel,\nEvidenceStack, DecisionForm, DualTimeline).\nHooks: useAccount, useParty, useWallets, useTransfers,\nuseVirtualBankAccounts, useVenlyMock (the trail reads the mock's event log).\nTwo timeline columns, not one feed: the decision chain (who decided what, when,\nin which seat) beside money movement on the same subject. Different actors,\ndifferent audiences; merging them is what makes an audit trail unreadable.\nStates that must exist: loading, evidence present, evidence unavailable, decision owed, decision applied, stale decision, terminal decision, frozen, empty trail.\nRules that must hold: every evidence row is either a real field path or a\nlabelled omission, and an omission is a FIRST-CLASS type in the component's\nprops, so a placeholder cannot be rendered where a gap belongs;\nomission copy states only what is verified and never implies a result, a\npending state, or a clean one - and never mentions the API contract, which is\ndeveloper diagnostics rather than operator language; a field the API cannot\ncarry is captured anyway when the work needs it, and rendered with a visible\nbadge saying it is a console note rather than API state; every decision carries the\noptimistic-locking version, and a conflict means refetch and re-decide against\nfresh state, never auto-retry; every transition the console causes leaves a\ntimeline node with actor, role and a timezone-qualified absolute timestamp, so a\nstatus change with no node is a bug; a store resync is a system line, not a\ndecision node; the panel footer carries row-stepping key chips so the reviewer\nmoves row to row without closing.";
+    readonly "console-pricing-config": "# Console pricing configuration\nShell: in-shell content column. A config screen, not a queue: no whose-move\nvalue and no aging. The whole screen sits inside a platform-view section\nboundary - fee configuration is the platform's seat.\nRegistry items: venly-tokens, data-table, arithmetic-ladder, field-list,\nlist-error; blocks: console-pricing (ConsolePricingTable, FeeLadder, FeePanel\n- read-only, because the fees operation is GET-only; the panel renders\nfields, never an editable form).\nHooks: useCompanyFees.\nBinding: the fee data the packages actually serve is a VOLUME-TIER model - tier\nname, ramp direction, minimum and maximum volume, percentage, version - and it\nis the same model the shipped withdrawal quote consumes, so this screen shows\nwhere a real quote comes from. A second, richer per-rail configuration model\nexists on an internal plane and is NOT served here; it renders as a labelled\nomission, never as an empty form.\nStates that must exist: loading, tiers present, no tiers, configuration unavailable, worked example, save failed.\nRules that must hold: a worked arithmetic ladder is mandatory on the tier\nsection - a sample amount times the tier percentage, with the operator glyphs in\na left gutter - because a pricing screen that shows only stored numbers teaches\nnothing; the ladder renders ONLY over data that exists, never over the omitted\nsection; the tier\na sample amount falls into is highlighted in the table so the row and the ladder\nare visibly the same fact; a single-member enum renders as a disabled\nsingle-value field that says so, not a select pretending at choice; a date\nwindow that has not opened reads scheduled, never active; forms are single\ncolumn with the field width capped, label above input, helper text between them\nand the error below.";
+    readonly "console-simulator": "# Sandbox simulator (play the counterparty)\nShell: its own chrome - a scrimmed right-hand drawer on a distinct surface with\na persistent sandbox label, reachable from ONE fixed affordance in the top bar.\nIt is the only scrimmed drawer in the console, so the surface change alone\nsignals the register change.\nRegistry items: venly-tokens, field-list, status-pill, money; blocks:\nconsole-simulator (SimulatorDrawer, SimulatorControl, LedgerVerifyPanel,\nChannelFooter - SimulatorControl refuses an imperative operator-decision\nlabel with a thrown developer error).\nHooks: useVenlyMock. Every control maps to exactly one call on the mock's\nsimulations namespace - no control without a call, and no call renamed.\nBinding: inbound credits, provider progression and screening verdicts are things\nOTHER parties do, so they live here rather than in the operator's workflow.\nStates that must exist: drawer closed, drawer open, sharing, not sharing, credit landed, verdict returned, payout advanced, books balanced, books do not balance, reset.\nRules that must hold: controls are phrased as events that happen to you, in the\nthird person, while operator controls elsewhere are imperative decisions - a\ncontrol phrased in the wrong voice is in the wrong surface; a simulated\ntransition emits the SAME event the real path emits, and the trail attributes it\nto the simulator plainly rather than to an operator; the drawer is reachable\nonly from the top bar, never from a queue row or a decision panel, because those\npaths make another party's action look like the operator's; the ledger check gets\na visible surface: it is the one control here that asserts something true, namely\nthat the simulated books balance; the channel footer states the adapter, session\nand peer count, and says IN WORDS when the surface is not actually sharing - the\ndefault channel shares nothing and cross-context sharing is same-origin only, so\nwithout that line a two-context demo can prove nothing while looking correct.";
+    readonly "console-webhooks": "# Console webhooks (endpoint registration, honestly bounded)\nShell: in-shell content column - a table with a panel form beside it. This\none IS a form: the public plane carries the full lifecycle (list, create,\nread, replace, delete, ping).\nRegistry items: venly-tokens, data-table, status-pill, list-error; blocks:\nconsole-webhooks (WebhooksTable, WebhookForm, WebhookDeliveryLog - the\ndelivery log renders inside SIMULATOR chrome only, never on this screen).\nHooks: useWebhooks, useWebhook, useCreateWebhook, useUpdateWebhook,\nuseDeleteWebhook, usePingWebhook.\nBinding: webhook rows render the contract fields verbatim - url, name, and\na status enum that has exactly one member in this release, rendered as a\ndisabled single value that says so rather than a select pretending at\nchoice. The authentication method is a two-variant choice (API key or\nbasic); its secret fields are write-only on the contract, so the platform\nnever returns a stored secret and this screen never displays one - editing\nmeans re-entering the credential, and the form says why.\nStates that must exist: loading, webhooks listed, no webhooks yet, registration form, secret masked, ping result, delete confirmation, list error.\nRules that must hold: Ping is the promoted per-row affordance - it is the\none real signal the API offers about an endpoint - and its result renders\nverbatim; delivery history is NOT available from the API in this release\nand the screen says so on the screen itself, with the next step (use Ping),\nnever as a silent gap; the create operation carries no idempotency\nenvelope, so a replayed create registers a second webhook - any\nretry-safety a surface adds is a client-side convention badged as such,\nnever presented as contract behaviour; delete is confirm-and-explain: the\nconfirmation names the consequence before anything is removed; the\nsimulated delivery log is a sandbox surface phrased in the third person\nand badged as simulation, rendered only inside the simulator's own chrome.";
 };
 type JourneyKey = keyof typeof JOURNEYS;
 interface Finding {

package/dist/frontend.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { verifyRuntimeContract } from "./verify-cli.js";
 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)
@@ -36,12 +37,45 @@ Registry items: venly-tokens, field-list; block: receive.
 Hooks: useVirtualBankAccounts (first active EUR account).
 States that must exist: no virtual bank account yet (offer creation), details present, reference not yet assigned ("Not assigned yet" + Required pill - never "(not required)").
 Rules 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.`,
-    send: `# Send
-Shell: full page; form clamped ~600px; review step replaces the form.
-Registry items: venly-tokens, arithmetic-ladder, timeline; block: send.
-Hooks: useStagedTransfer (the machine IS the flow), useFeeQuote when fees apply.
-States that must exist: draft (validation issues listed), staged review, submitting, pending (polling), completed, failed (reason shown, terminal).
-Rules 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.`,
+    send: `# Send (one door)
+Shell: full page; the door is the recipient picker; forms clamp ~600px; the
+review and the step-up ceremony replace the form in place.
+Registry items: venly-tokens, status-pill, field-list, data-table, list-error;
+blocks: send (SendDoor, RecipientPicker, DirectoryPick, PlatformTransferFlow,
+PayoutSendFlow, SendReview, StepUpConfirm, TransferDetail, PayoutDetail) and
+recipients (RecipientsView, AddRecipientForm, BeneficiaryAccountForm,
+RouteCeremony) - the prerequisite surface saved recipients are managed on.
+Hooks: useCreateFiatTransfer and useCreateCryptoTransfer (the staged-transfer
+machine typed per rail), useRequestPayout, usePartyRoles, useAddPartyRole,
+useCreateParty, useRegisterPayoutBankAccount, useCreatePayoutRoute,
+usePreparePayoutOwnershipProof, useCompletePayoutOwnershipProof, useParties,
+useAccounts, useWallets, useAccountSupportedAssets, useTransfers, useTransfer,
+usePayouts, usePayout, usePayoutRoutes.
+Binding: ONE door - the first screen is the recipient picker and the fork is
+the recipient's OBJECT TYPE, never a rail choice. A person or business on the
+platform (a directory YOUR user table serves; render name + handle, never a
+UUID - ids stay request-side) starts an on-platform transfer. A saved
+recipient - a party holding the payout-recipient role, owning reviewed bank
+accounts (details masked server-side) and an ACTIVE payout route - starts a
+third-party payout referencing the ROUTE, never raw bank details. Your own
+bank account is a link row into the withdraw flow. Send-to-external-wallet
+has NO surface: no teaser, no disabled row, no rendered trace.
+States that must exist: recipient picker (three classes, populated and empty), disabled with the reason (unverified directory rows, non-active routes and non-active accounts), over-balance, review (known figures only), step-up (wrong code blocks, the deterministic demo code proceeds), pending, completed, failed (the record's own error verbatim, terminal), requested, sending, provider processing, rejected, returned (money came back - a neutral terminal), no active route (blocked start with the unblocking CTA), load failure (explicit error plus retry - never an empty detail).
+Rules that must hold: every money confirm passes the step-up ceremony against
+YOUR auth adapter and the commit fires only after the code verifies - this is
+app-side ceremony and must never be presented as an API security guarantee;
+execution is single-shot on an idempotency key minted ONCE per staged draft,
+so a retry replays the same record instead of moving money twice; reviews
+render ONLY figures the API has produced, and the payout review states the
+absence in words beside the two-sided units sentence. Forbidden to invent
+(render the labelled omission or nothing at all): a fee row - and equally a
+"No fee" claim, since no source confirms zero; an ETA or delivery date - no
+timing field exists on transfers or payouts; a pre-create rate or
+recipient-gets figure - exchangeRate and settledFiatAmount exist on CREATED
+and COMPLETED records only; named in-flight stages beyond the status enums -
+render the app-side observation log instead. Beneficiary details come back
+masked: render the mask, never re-ask. Route states render verbatim and a
+REJECTED route is terminal-negative with a way forward, never a dead end.`,
     activity: `# Activity
 Shell: full-width table + side panel.
 Registry items: venly-tokens, data-table, status-pill, side-panel, timeline; block: activity.
@@ -78,8 +112,445 @@ Registry items: venly-tokens, data-table, status-pill, side-panel, timeline.
 Hooks: useRampRequests, useFourEyesApproval (capability decides what renders), useRampLifecycle.
 States 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).
 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.`,
+    "console-review-queue": `# Console review queue (the operator worklist)
+Shell: left nav rail + thin top bar, full-width content, and a page-edge
+environment banner naming mock mode. Not a consumer surface - density rules
+apply.
+Registry items: venly-tokens, data-table, status-pill, money, list-error;
+blocks: console-queue (ConsoleQueue, WhoseMove, AgeCell, deriveKycActor,
+derivePayoutActor - the derivation functions are exported so a consumer can
+unit-test the join).
+Hooks: useAccounts, useParties. The queue's own state is DERIVED on every
+render - never stored, never cached as a status.
+Binding: sections are ACTORS, not statuses - your move, waiting on the customer,
+waiting on a provider, then a collapsed closed section, so the reviewer's own
+worklist is the top band by construction.
+States that must exist: loading, your move, waiting on the customer, waiting on a provider, closed, empty queue, filtered to nothing, list error.
+Rules that must hold: the whose-move value is a pure function of enum values on
+the row - no clock reading, no threshold, no configuration and no default, and a
+combination the mapping does not cover renders NO value plus an explicit
+not-recognised line, which is a bug report rather than a guess; never a target
+time, a breach colour or an overdue state, because the API publishes no targets
+and an invented one is the same defect as an invented fee; an age column is
+labelled for what it actually measures - a created-at delta is "Age", and only a
+duration the API itself computes may be called time in state; empty sections are
+still drawn as a zero header row, because nothing-to-do is information; loading
+is a skeleton that preserves column geometry exactly, never prose; a row click
+opens a side panel and never navigates; one status pill per row - the whose-move
+value is plain text, since two pills read as two states.`,
+    "console-decision-detail": `# Console decision detail (evidence, ceremony, audit trail)
+Shell: side panel about 30% wide over the queue - no scrim, the table stays
+visible clipped at the panel edge and the source row stays tinted. Escalate to a
+35/65 split only when the evidence outgrows the panel. Evidence goes on the
+LEFT: this is a judging task, not an authoring one.
+Registry items: venly-tokens, side-panel, timeline, field-list, status-pill,
+money, data-table; blocks: console-decision (ConsoleDecisionPanel,
+EvidenceStack, DecisionForm, DualTimeline).
+Hooks: useAccount, useParty, useWallets, useTransfers,
+useVirtualBankAccounts, useVenlyMock (the trail reads the mock's event log).
+Two timeline columns, not one feed: the decision chain (who decided what, when,
+in which seat) beside money movement on the same subject. Different actors,
+different audiences; merging them is what makes an audit trail unreadable.
+States that must exist: loading, evidence present, evidence unavailable, decision owed, decision applied, stale decision, terminal decision, frozen, empty trail.
+Rules that must hold: every evidence row is either a real field path or a
+labelled omission, and an omission is a FIRST-CLASS type in the component's
+props, so a placeholder cannot be rendered where a gap belongs;
+omission copy states only what is verified and never implies a result, a
+pending state, or a clean one - and never mentions the API contract, which is
+developer diagnostics rather than operator language; a field the API cannot
+carry is captured anyway when the work needs it, and rendered with a visible
+badge saying it is a console note rather than API state; every decision carries the
+optimistic-locking version, and a conflict means refetch and re-decide against
+fresh state, never auto-retry; every transition the console causes leaves a
+timeline node with actor, role and a timezone-qualified absolute timestamp, so a
+status change with no node is a bug; a store resync is a system line, not a
+decision node; the panel footer carries row-stepping key chips so the reviewer
+moves row to row without closing.`,
+    "console-pricing-config": `# Console pricing configuration
+Shell: in-shell content column. A config screen, not a queue: no whose-move
+value and no aging. The whole screen sits inside a platform-view section
+boundary - fee configuration is the platform's seat.
+Registry items: venly-tokens, data-table, arithmetic-ladder, field-list,
+list-error; blocks: console-pricing (ConsolePricingTable, FeeLadder, FeePanel
+- read-only, because the fees operation is GET-only; the panel renders
+fields, never an editable form).
+Hooks: useCompanyFees.
+Binding: the fee data the packages actually serve is a VOLUME-TIER model - tier
+name, ramp direction, minimum and maximum volume, percentage, version - and it
+is the same model the shipped withdrawal quote consumes, so this screen shows
+where a real quote comes from. A second, richer per-rail configuration model
+exists on an internal plane and is NOT served here; it renders as a labelled
+omission, never as an empty form.
+States that must exist: loading, tiers present, no tiers, configuration unavailable, worked example, save failed.
+Rules that must hold: a worked arithmetic ladder is mandatory on the tier
+section - a sample amount times the tier percentage, with the operator glyphs in
+a left gutter - because a pricing screen that shows only stored numbers teaches
+nothing; the ladder renders ONLY over data that exists, never over the omitted
+section; the tier
+a sample amount falls into is highlighted in the table so the row and the ladder
+are visibly the same fact; a single-member enum renders as a disabled
+single-value field that says so, not a select pretending at choice; a date
+window that has not opened reads scheduled, never active; forms are single
+column with the field width capped, label above input, helper text between them
+and the error below.`,
+    "console-simulator": `# Sandbox simulator (play the counterparty)
+Shell: its own chrome - a scrimmed right-hand drawer on a distinct surface with
+a persistent sandbox label, reachable from ONE fixed affordance in the top bar.
+It is the only scrimmed drawer in the console, so the surface change alone
+signals the register change.
+Registry items: venly-tokens, field-list, status-pill, money; blocks:
+console-simulator (SimulatorDrawer, SimulatorControl, LedgerVerifyPanel,
+ChannelFooter - SimulatorControl refuses an imperative operator-decision
+label with a thrown developer error).
+Hooks: useVenlyMock. Every control maps to exactly one call on the mock's
+simulations namespace - no control without a call, and no call renamed.
+Binding: inbound credits, provider progression and screening verdicts are things
+OTHER parties do, so they live here rather than in the operator's workflow.
+States that must exist: drawer closed, drawer open, sharing, not sharing, credit landed, verdict returned, payout advanced, books balanced, books do not balance, reset.
+Rules that must hold: controls are phrased as events that happen to you, in the
+third person, while operator controls elsewhere are imperative decisions - a
+control phrased in the wrong voice is in the wrong surface; a simulated
+transition emits the SAME event the real path emits, and the trail attributes it
+to the simulator plainly rather than to an operator; the drawer is reachable
+only from the top bar, never from a queue row or a decision panel, because those
+paths make another party's action look like the operator's; the ledger check gets
+a visible surface: it is the one control here that asserts something true, namely
+that the simulated books balance; the channel footer states the adapter, session
+and peer count, and says IN WORDS when the surface is not actually sharing - the
+default channel shares nothing and cross-context sharing is same-origin only, so
+without that line a two-context demo can prove nothing while looking correct.`,
+    "console-webhooks": `# Console webhooks (endpoint registration, honestly bounded)
+Shell: in-shell content column - a table with a panel form beside it. This
+one IS a form: the public plane carries the full lifecycle (list, create,
+read, replace, delete, ping).
+Registry items: venly-tokens, data-table, status-pill, list-error; blocks:
+console-webhooks (WebhooksTable, WebhookForm, WebhookDeliveryLog - the
+delivery log renders inside SIMULATOR chrome only, never on this screen).
+Hooks: useWebhooks, useWebhook, useCreateWebhook, useUpdateWebhook,
+useDeleteWebhook, usePingWebhook.
+Binding: webhook rows render the contract fields verbatim - url, name, and
+a status enum that has exactly one member in this release, rendered as a
+disabled single value that says so rather than a select pretending at
+choice. The authentication method is a two-variant choice (API key or
+basic); its secret fields are write-only on the contract, so the platform
+never returns a stored secret and this screen never displays one - editing
+means re-entering the credential, and the form says why.
+States that must exist: loading, webhooks listed, no webhooks yet, registration form, secret masked, ping result, delete confirmation, list error.
+Rules that must hold: Ping is the promoted per-row affordance - it is the
+one real signal the API offers about an endpoint - and its result renders
+verbatim; delivery history is NOT available from the API in this release
+and the screen says so on the screen itself, with the next step (use Ping),
+never as a silent gap; the create operation carries no idempotency
+envelope, so a replayed create registers a second webhook - any
+retry-safety a surface adds is a client-side convention badged as such,
+never presented as contract behaviour; delete is confirm-and-explain: the
+confirmation names the consequence before anything is removed; the
+simulated delivery log is a sandbox surface phrased in the third person
+and badged as simulation, rendered only inside the simulator's own chrome.`,
 };
 const JOURNEY_KEYS = Object.keys(JOURNEYS);
+const RUNTIME_PACKAGES_BY_BLOCK = {
+    activity: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    auth: { "@radix-ui/react-one-time-password-field": "^0.1.16" },
+    balances: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "bank-accounts": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-decision": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-queue": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-pricing": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-simulator": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-tenant": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "console-webhooks": {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    onboarding: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    receive: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    reconciliation: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    recipients: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    send: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+        "@radix-ui/react-one-time-password-field": "^0.1.16",
+    },
+    team: { "@radix-ui/react-dialog": "^1.1.23" },
+    withdraw: {
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+};
+/**
+ * Kept in step with the ranges the registry generator stamps into ui/r/*.json
+ * (`RUNTIME_DEPENDENCIES` in ui/scripts/build-registry.mjs): the runtime-contract
+ * test asserts the two agree, so a blueprint can never advertise a range the
+ * registry will not install.
+ *
+ * The package set any hook-using screen needs, for journeys the registry has no
+ * composite block for yet - those screens are built from primitives
+ * (data-table, side-panel, timeline …), and a primitive registry item declares
+ * no npm dependencies, so deriving `requiredPackages` from blocks alone would
+ * tell an agent that a surface living entirely on hooks needs no packages.
+ *
+ * The ranges name the versions the console surfaces actually consume: the
+ * party IV read and the payout hooks arrived in sdk 0.7.0 / react 0.6.0, on
+ * top of the 0.6.0 mock behaviours (channel state, balances that move).
+ */
+const DATA_PLANE_PACKAGES = {
+    "@venlyfinance/react": "^0.6.0",
+    "@venlyfinance/sdk": "^0.7.0",
+    "@tanstack/react-query": "^5.0.0",
+};
+const JOURNEY_RUNTIME = {
+    auth: {
+        blocks: ["auth"],
+        hooks: [],
+        demoBindings: [{ import: "createMockAuthAdapter", from: "registry:block/auth" }],
+    },
+    team: {
+        blocks: ["team"],
+        hooks: [],
+        demoBindings: [{ import: "createMockTeamAdapter", from: "registry:block/team" }],
+    },
+    "home-balances": { blocks: ["balances"], hooks: ["useAccounts", "useWallets"] },
+    receive: { blocks: ["receive"], hooks: ["useVirtualBankAccounts"] },
+    send: {
+        blocks: ["send", "recipients"],
+        hooks: [
+            "useCreateFiatTransfer",
+            "useCreateCryptoTransfer",
+            "useRequestPayout",
+            "usePartyRoles",
+            "useAddPartyRole",
+            "useCreateParty",
+            "useRegisterPayoutBankAccount",
+            "useCreatePayoutRoute",
+            "usePreparePayoutOwnershipProof",
+            "useCompletePayoutOwnershipProof",
+            "useParties",
+            "useAccounts",
+            "useWallets",
+            "useAccountSupportedAssets",
+            "useTransfers",
+            "useTransfer",
+            "usePayouts",
+            "usePayout",
+            "usePayoutRoutes",
+        ],
+        extraForbidden: [
+            "a fee row or a \"No fee\" claim (no source confirms zero)",
+            "an ETA or delivery-date row (no timing field exists on transfers or payouts)",
+            "a pre-create rate or recipient-gets figure (exchangeRate/settledFiatAmount are post-create fields)",
+            "named in-flight stages beyond the status enums (render the observation log instead)",
+            "a send-to-external-wallet surface (no teaser, no disabled row, no rendered trace)",
+        ],
+    },
+    activity: { blocks: ["activity"], hooks: ["useTransfers", "useRampRequests"] },
+    "onboarding-status": {
+        blocks: ["onboarding"],
+        hooks: ["useCreateParty", "useCreateAccount", "useParty", "useAccount"],
+    },
+    "withdraw-bank-accounts": {
+        blocks: ["bank-accounts", "withdraw"],
+        hooks: [
+            "useCompanyBankAccounts",
+            "useBankAccountConfig",
+            "useCreateCompanyBankAccount",
+            "useRampRequests",
+            "useRampRequest",
+            "useCreateRampRequest",
+            "useFeeQuote",
+            "useRampPairs",
+            "useReferenceData",
+            "useFourEyesApproval",
+            "useInitiateRamp",
+            "describeRampStatus",
+        ],
+    },
+    reconciliation: {
+        blocks: ["reconciliation"],
+        hooks: ["useVirtualBankAccounts", "useTransfers"],
+    },
+    "proof-of-segregation": { blocks: ["balances"], hooks: ["useWallets", "useAccount"] },
+    approvals: {
+        blocks: ["withdraw"],
+        hooks: ["useRampRequests", "useFourEyesApproval", "useRampLifecycle"],
+    },
+    "console-review-queue": {
+        blocks: ["console-queue"],
+        dataPlane: true,
+        hooks: ["useAccounts", "useParties"],
+        extraForbidden: [
+            "a whose-move or needs-attention value computed from anything other than enum values on the row",
+            "a target time, breach threshold or overdue state (the API publishes no targets)",
+            "labelling a created-at delta \"time in state\" rather than \"Age\" (only an API-computed duration may use that phrase)",
+        ],
+    },
+    "console-decision-detail": {
+        blocks: ["console-decision"],
+        dataPlane: true,
+        hooks: [
+            "useAccount",
+            "useParty",
+            "useWallets",
+            "useTransfers",
+            "useVirtualBankAccounts",
+            "useVenlyMock",
+        ],
+        extraForbidden: [
+            "a rendered placeholder where an unavailable field belongs (omission is a prop type, not a string)",
+            "a captured field the API cannot carry, rendered without the console-note badge",
+            "a status change that leaves no timeline node with actor, role and timezone-qualified stamp",
+            "auto-retry on a version conflict (refetch and let the operator re-decide)",
+        ],
+    },
+    "console-pricing-config": {
+        blocks: ["console-pricing"],
+        dataPlane: true,
+        hooks: ["useCompanyFees"],
+        extraForbidden: [
+            "an arithmetic ladder over figures the API does not serve",
+            "a single-member enum rendered as a select",
+            "an editable control on the tier section (the fees operation is GET-only)",
+        ],
+    },
+    "console-simulator": {
+        blocks: ["console-simulator"],
+        dataPlane: true,
+        hooks: ["useVenlyMock"],
+        extraForbidden: [
+            "counterparty or provider simulation rendered inside operator chrome",
+            "a simulator control reachable from a queue row or a decision panel",
+            "a simulator control phrased as an imperative operator decision",
+            "a cross-context demo that does not state its channel adapter and peer count",
+        ],
+    },
+    "console-webhooks": {
+        blocks: ["console-webhooks"],
+        dataPlane: true,
+        hooks: [
+            "useWebhooks",
+            "useWebhook",
+            "useCreateWebhook",
+            "useUpdateWebhook",
+            "useDeleteWebhook",
+            "usePingWebhook",
+        ],
+        extraForbidden: [
+            "a delivery-history surface presented as API-served (no delivery-log operation exists on any plane)",
+            "a stored secret displayed anywhere (the authentication secret fields are write-only)",
+            "retry-safety presented as contract behaviour (a replayed create registers a second webhook)",
+            "the single-member status enum rendered as a select",
+        ],
+    },
+};
+const RUNTIME_CONTRACT_SCHEMA = z.object({
+    runtimeMode: z.enum(["mock", "staging", "production"]),
+    requiredPackages: z.record(z.string()),
+    requiredHooks: z.array(z.object({ import: z.string(), from: z.string() })),
+    demoBindings: z.array(z.object({ import: z.string(), from: z.string() })).optional(),
+    provider: z.object({
+        import: z.string(),
+        from: z.string(),
+        props: z.object({ environment: z.literal("mock") }),
+    }),
+    forbiddenPatterns: z.array(z.string()),
+    install: z.array(z.string()),
+    completionChecks: z.array(z.string()),
+});
+function runtimeContractForJourney(journey) {
+    const definition = JOURNEY_RUNTIME[journey];
+    // Base first, blocks last: a composite block's own stamped dependencies are
+    // what the registry will actually install, so they win where the two differ.
+    const requiredPackages = definition.dataPlane
+        ? { ...DATA_PLANE_PACKAGES }
+        : {};
+    for (const block of definition.blocks) {
+        Object.assign(requiredPackages, RUNTIME_PACKAGES_BY_BLOCK[block]);
+    }
+    const installItems = definition.blocks.length
+        ? definition.blocks.map((block) => `@venlyfinance/${block}`)
+        : (definition.registryItems ?? []).map((item) => `@venlyfinance/${item}`);
+    return {
+        runtimeMode: "mock",
+        requiredPackages,
+        requiredHooks: definition.hooks.map((name) => ({
+            import: name,
+            from: "@venlyfinance/react",
+        })),
+        ...(definition.demoBindings ? { demoBindings: definition.demoBindings } : {}),
+        provider: {
+            import: "VenlyProvider",
+            from: "@venlyfinance/react",
+            props: { environment: "mock" },
+        },
+        forbiddenPatterns: [
+            "in-memory store of transfer/balance/approval state",
+            "fetch()/axios to self-owned money routes that do not wrap @venlyfinance/sdk",
+            "useEffect polling loops for transfer status (useStagedTransfer/useRampLifecycle exist)",
+            "clientSecret in browser code (provider throws; use proxyClientOptions())",
+            ...(definition.extraForbidden ?? []),
+        ],
+        install: [
+            "npx shadcn@latest init -y -b radix -p nova",
+            'add { "registries": { "@venlyfinance": "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json" } } to components.json',
+            `npx shadcn@latest add ${installItems.join(" ")} -y -o`,
+        ],
+        completionChecks: [
+            'npx @venlyfinance/settlement-mcp review "src/**/*.tsx" exits 0',
+            'npx @venlyfinance/settlement-mcp verify "src/**/*.{ts,tsx}" exits 0',
+        ],
+    };
+}
 // ---------------------------------------------------------------------------
 // Shared mechanics. Three cross-cutting behaviours every rule participates in:
 //
@@ -442,9 +913,58 @@ export function registerFrontendTools(server) {
         inputSchema: {
             journey: z.enum(JOURNEY_KEYS).describe("Which journey to blueprint"),
         },
-    }, async ({ journey }) => ({
-        content: [{ type: "text", text: JOURNEYS[journey] }],
-    }));
+        outputSchema: {
+            runtime_contract: RUNTIME_CONTRACT_SCHEMA,
+        },
+    }, async ({ journey }) => {
+        const structuredContent = {
+            runtime_contract: runtimeContractForJourney(journey),
+        };
+        return {
+            content: [
+                { type: "text", text: JOURNEYS[journey] },
+                {
+                    type: "text",
+                    text: `\`\`\`json\n${JSON.stringify(structuredContent, null, 2)}\n\`\`\``,
+                },
+            ],
+            structuredContent,
+        };
+    });
+    server.registerTool("verify_runtime_contract", {
+        title: "Verify an app's Venly runtime contract",
+        description: "Deterministically checks supplied app source and package.json against the direct-sdk or backend-proxy runtime contract. The same rules power the verify CLI.",
+        inputSchema: {
+            files: z
+                .array(z.object({ path: z.string().min(1), source: z.string() }))
+                .min(1),
+            packageJson: z.string().describe("The app's package.json contents"),
+            profile: z.enum(["direct-sdk", "backend-proxy"]).optional(),
+        },
+    }, async ({ files, packageJson, profile }) => {
+        let parsedPackageJson;
+        try {
+            parsedPackageJson = JSON.parse(packageJson);
+        }
+        catch (error) {
+            const message = `Invalid packageJson: ${error.message}`;
+            return {
+                content: [{ type: "text", text: message }],
+                structuredContent: { error: message },
+                isError: true,
+            };
+        }
+        const result = verifyRuntimeContract({ files, packageJson: parsedPackageJson, profile });
+        const structuredContent = {
+            profile: result.profile,
+            findings: result.findings,
+            summary: result.summary,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            structuredContent,
+        };
+    });
     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, 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.",

package/dist/index.js

@@ -42,6 +42,17 @@ if (argv[0] === "review") {
         process.exit(2);
     });
 }
+else if (argv[0] === "verify") {
+    import("./verify-cli.js")
+        .then(({ runVerifyCli }) => runVerifyCli(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`);

package/dist/server.js

@@ -4,7 +4,7 @@
  * mock client and no network.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { ENVIRONMENT_FLAG, SERVER_NAME, SERVER_VERSION, resolveVenlyEnvironment, } from "./constants.js";
+import { ENVIRONMENT_FLAG, INSTRUCTIONS, SERVER_NAME, SERVER_VERSION, resolveVenlyEnvironment, } from "./constants.js";
 import { registerReadTools } from "./tools/read-tools.js";
 import { registerWriteTools } from "./tools/write-tools.js";
 import { registerX402Tools } from "./tools/x402-tools.js";
@@ -26,6 +26,8 @@ export function createServer(options) {
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
+    }, {
+        instructions: INSTRUCTIONS,
     });
     registerReadTools(server, options.client);
     registerWriteTools(server, options.client, env);

package/dist/staging-smoke.d.ts

@@ -1,4 +1,4 @@
-export declare const EXPECTED_TOOLS: readonly ["list_ramp_requests", "get_ramp_request", "list_accounts", "get_account", "list_wallets", "list_virtual_bank_accounts", "get_virtual_bank_account", "reconcile_by_reference_code", "list_transfers", "get_transfer", "list_parties", "get_party", "get_reference_data", "create_party", "create_account", "create_virtual_bank_account", "create_fiat_transfer", "create_crypto_transfer", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "list_payouts", "get_payout", "list_payout_routes", "list_payout_bank_accounts", "register_payout_bank_account", "create_payout_route", "prepare_payout_ownership_proof", "complete_payout_ownership_proof", "request_payout", "quote_x402_payment", "get_journey_blueprint", "review_screen"];
+export declare const EXPECTED_TOOLS: readonly ["list_ramp_requests", "get_ramp_request", "list_accounts", "get_account", "list_wallets", "list_virtual_bank_accounts", "get_virtual_bank_account", "reconcile_by_reference_code", "list_transfers", "get_transfer", "list_parties", "get_party", "get_reference_data", "create_party", "create_account", "create_virtual_bank_account", "create_fiat_transfer", "create_crypto_transfer", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "list_payouts", "get_payout", "list_payout_routes", "list_payout_bank_accounts", "register_payout_bank_account", "create_payout_route", "prepare_payout_ownership_proof", "complete_payout_ownership_proof", "request_payout", "quote_x402_payment", "get_journey_blueprint", "verify_runtime_contract", "review_screen"];
 export declare const EXPECTED_RESOURCE_URIS: readonly ["venly://capabilities", "venly://safety", "venly://workflows/international-account", "venly://workflows/mock-to-staging", "venly://frontend/agents"];
 export declare const EXPECTED_PROMPTS: readonly ["build_international_account"];
 export interface DiscoveryNames {

package/dist/staging-smoke.js

@@ -36,6 +36,7 @@ export const EXPECTED_TOOLS = [
     "request_payout",
     "quote_x402_payment",
     "get_journey_blueprint",
+    "verify_runtime_contract",
     "review_screen",
 ];
 export const EXPECTED_RESOURCE_URIS = [

package/dist/verify-cli.d.ts

@@ -0,0 +1,24 @@
+export type VerifyProfile = "direct-sdk" | "backend-proxy";
+export interface VerifySourceFile {
+    path: string;
+    source: string;
+}
+export interface VerifyFinding {
+    rule: string;
+    severity: "error" | "warn";
+    path: string;
+    evidence: string;
+    fix: string;
+    line?: number;
+}
+export interface VerifyResult {
+    profile: VerifyProfile;
+    findings: VerifyFinding[];
+    summary: string;
+}
+export declare function verifyRuntimeContract(options: {
+    files: VerifySourceFile[];
+    packageJson: Record<string, unknown>;
+    profile?: VerifyProfile;
+}): VerifyResult;
+export declare function runVerifyCli(args: string[], out?: NodeJS.WritableStream, err?: NodeJS.WritableStream): Promise<0 | 1 | 2>;

package/dist/verify-cli.js

@@ -0,0 +1,371 @@
+// `verify` subcommand: deterministic runtime-contract checks for generated apps.
+//
+// Exit codes: 0 clean (warnings allowed) · 1 at least one error · 2 usage or
+// no-match. The three unresolved false-positive boundaries intentionally warn:
+// missing React in direct-sdk, app-owned money routes, and in-memory stores.
+import { existsSync, readFileSync, readdirSync, statSync, } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+const BLUEPRINT_HOOKS = new Set([
+    "useAccount",
+    "useAccounts",
+    "useBankAccountConfig",
+    "useCompanyBankAccounts",
+    "useCreateAccount",
+    "useCreateCompanyBankAccount",
+    "useCreateParty",
+    "useCreateRampRequest",
+    "useFeeQuote",
+    "useFourEyesApproval",
+    "useInitiateRamp",
+    "useParty",
+    "useRampLifecycle",
+    "useRampPairs",
+    "useRampRequest",
+    "useRampRequests",
+    "useReferenceData",
+    "useStagedTransfer",
+    "useTransfers",
+    "useVirtualBankAccounts",
+    "useWallets",
+]);
+function lineFor(source, index) {
+    return source.slice(0, index).split("\n").length;
+}
+function suppressed(source, rule, line) {
+    const token = `venly-allow:${rule}`;
+    if (line === undefined)
+        return source.includes(token);
+    const lines = source.split("\n");
+    return Boolean(lines[line - 1]?.includes(token) || lines[line - 2]?.includes(token));
+}
+function dependencies(packageJson) {
+    return Object.assign({}, packageJson.dependencies ?? {}, packageJson.devDependencies ?? {}, packageJson.peerDependencies ?? {});
+}
+function importsFrom(source, packageName) {
+    const names = [];
+    const expression = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*["']${packageName.replaceAll("/", "\\/")}["']`, "g");
+    for (const match of source.matchAll(expression)) {
+        for (const item of (match[1] ?? "").split(",")) {
+            const name = item.trim().split(/\s+as\s+/)[0]?.trim();
+            if (name)
+                names.push(name);
+        }
+    }
+    return names;
+}
+function isServerFile(file) {
+    return (/(?:^|\/)(?:server|backend|api)(?:\/|\.)/i.test(file.path) ||
+        /(?:^|\/)route\.[cm]?[jt]sx?$/i.test(file.path) ||
+        /[.]server\.[cm]?[jt]sx?$/i.test(file.path) ||
+        /^\s*["']use server["'];?/m.test(file.source));
+}
+function isMoneyRoute(file) {
+    const routeHandler = /(?:^|\/)route\.[cm]?[jt]sx?$/i.test(file.path) ||
+        /export\s+(?:async\s+)?function\s+(?:GET|POST|PUT|PATCH|DELETE)\b/.test(file.source);
+    const moneySignal = /(?:transfers?|payouts?|balances?|ramps?|rampRequests|virtual[-_/ ]bank)/i.test(`${file.path}\n${file.source}`);
+    return routeHandler && moneySignal;
+}
+function autoDetectProfile(files) {
+    return files.some((file) => file.source.includes("proxyClientOptions") || isMoneyRoute(file))
+        ? "backend-proxy"
+        : "direct-sdk";
+}
+export function verifyRuntimeContract(options) {
+    const { files, packageJson } = options;
+    const profile = options.profile ?? autoDetectProfile(files);
+    const deps = dependencies(packageJson);
+    const findings = [];
+    function addProjectFinding(finding) {
+        const source = files.map((file) => file.source).join("\n");
+        if (!suppressed(source, finding.rule)) {
+            findings.push({ ...finding, path: "package.json" });
+        }
+    }
+    function addSourceFinding(file, finding) {
+        if (!suppressed(file.source, finding.rule, finding.line)) {
+            findings.push({ ...finding, path: file.path });
+        }
+    }
+    if (!("@venlyfinance/react" in deps) && !("@venlyfinance/sdk" in deps)) {
+        addProjectFinding({
+            rule: "venly-package-missing",
+            severity: "error",
+            evidence: "package.json declares zero @venlyfinance runtime packages",
+            fix: "Install the registry block for the journey or add the required @venlyfinance package.",
+        });
+    }
+    if (profile === "direct-sdk") {
+        if (!("@venlyfinance/react" in deps)) {
+            addProjectFinding({
+                rule: "react-package-missing",
+                severity: "warn",
+                evidence: "direct-sdk profile has no @venlyfinance/react dependency",
+                fix: "Install the journey's registry block, or suppress this warning for an intentionally headless integration.",
+            });
+        }
+        const providerImported = files.some((file) => importsFrom(file.source, "@venlyfinance/react").includes("VenlyProvider"));
+        const mockProviderRendered = files.some((file) => /<VenlyProvider\b[^>]*\benvironment\s*=\s*(?:["']mock["']|\{[^}]+\})/s.test(file.source));
+        if (!providerImported || !mockProviderRendered) {
+            addProjectFinding({
+                rule: "provider-missing",
+                severity: "error",
+                evidence: "no VenlyProvider import and mock/environment expression wrapper were found",
+                fix: 'Import VenlyProvider from @venlyfinance/react and wrap the tree with environment="mock".',
+            });
+        }
+        const importedHooks = files.flatMap((file) => importsFrom(file.source, "@venlyfinance/react").filter((name) => BLUEPRINT_HOOKS.has(name)));
+        if (importedHooks.length === 0) {
+            addProjectFinding({
+                rule: "blueprint-hook-missing",
+                severity: "error",
+                evidence: "no journey-blueprint hook is imported from @venlyfinance/react",
+                fix: "Use the qualified hooks named by get_journey_blueprint instead of rebuilding the data layer.",
+            });
+        }
+        for (const file of files) {
+            if (!/(?:@venlyfinance\/react|["']react["']|["']use client["'])/.test(file.source))
+                continue;
+            for (const match of file.source.matchAll(/\bclientSecret\b/g)) {
+                addSourceFinding(file, {
+                    rule: "browser-client-secret",
+                    severity: "error",
+                    line: lineFor(file.source, match.index ?? 0),
+                    evidence: "clientSecret appears in browser/React source",
+                    fix: "Keep secrets server-side; use proxyClientOptions() for browser traffic.",
+                });
+            }
+        }
+    }
+    else {
+        if (!("@venlyfinance/sdk" in deps)) {
+            addProjectFinding({
+                rule: "sdk-package-missing",
+                severity: "error",
+                evidence: "backend-proxy profile has no @venlyfinance/sdk dependency",
+                fix: "Add @venlyfinance/sdk and make money routes wrap the official client.",
+            });
+        }
+        for (const file of files) {
+            if (isMoneyRoute(file) && !/from\s*["']@venlyfinance\/sdk["']/.test(file.source)) {
+                addSourceFinding(file, {
+                    rule: "money-route-without-sdk",
+                    severity: "warn",
+                    line: 1,
+                    evidence: "money-route heuristic matched but no @venlyfinance/sdk import was found",
+                    fix: "Wrap this route with @venlyfinance/sdk, or suppress if it is an unrelated consumer-owned ledger.",
+                });
+            }
+            if (!isServerFile(file)) {
+                for (const match of file.source.matchAll(/\bclientSecret\b/g)) {
+                    addSourceFinding(file, {
+                        rule: "client-secret-outside-server",
+                        severity: "error",
+                        line: lineFor(file.source, match.index ?? 0),
+                        evidence: "clientSecret appears outside a server-only file",
+                        fix: "Move the secret into a server route or server-only module.",
+                    });
+                }
+            }
+        }
+        const proxyImported = files.some((file) => importsFrom(file.source, "@venlyfinance/react").includes("proxyClientOptions"));
+        if (!proxyImported) {
+            addProjectFinding({
+                rule: "proxy-client-options-missing",
+                severity: "warn",
+                evidence: "backend-proxy profile has no browser-side proxyClientOptions import",
+                fix: "Use proxyClientOptions() in the browser provider, or suppress for a server-only consumer.",
+            });
+        }
+    }
+    for (const file of files) {
+        if (/\buseEffect\b/.test(file.source) &&
+            /\bset(?:Interval|Timeout)\b/.test(file.source) &&
+            /(?:status|state)/i.test(file.source) &&
+            /\b(?:transfer|ramp)/i.test(file.source)) {
+            const match = /\buseEffect\b/.exec(file.source);
+            addSourceFinding(file, {
+                rule: "status-polling",
+                severity: "warn",
+                line: lineFor(file.source, match?.index ?? 0),
+                evidence: "useEffect timer polling appears beside transfer/ramp state",
+                fix: "Use useStagedTransfer or useRampLifecycle for lifecycle polling.",
+            });
+        }
+        const store = /(?:^|\n)\s*export\s+(?:const|let)\s+(transfers|balances|payouts|rampRequests)\s*=\s*(?:\[|new\s+(?:Map|Set)\b)/g;
+        for (const match of file.source.matchAll(store)) {
+            addSourceFinding(file, {
+                rule: "in-memory-money-store",
+                severity: "warn",
+                line: lineFor(file.source, match.index ?? 0),
+                evidence: `module exports mutable in-memory money state named ${match[1]}`,
+                fix: "Use @venlyfinance/react hooks/flows or the SDK; suppress only for a deliberate fixture.",
+            });
+        }
+    }
+    findings.sort((a, b) => a.path.localeCompare(b.path) ||
+        (a.line ?? 0) - (b.line ?? 0) ||
+        a.rule.localeCompare(b.rule));
+    const errors = findings.filter((finding) => finding.severity === "error").length;
+    const warnings = findings.length - errors;
+    return {
+        profile,
+        findings,
+        summary: `${errors} error(s), ${warnings} warning(s) across ${files.length} file(s)`,
+    };
+}
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist"]);
+function braceExpand(pattern) {
+    const match = /\{([^{}]*)\}/.exec(pattern);
+    if (!match)
+        return [pattern];
+    const before = pattern.slice(0, match.index);
+    const after = pattern.slice(match.index + match[0].length);
+    return (match[1] ?? "").split(",").flatMap((option) => braceExpand(before + option + after));
+}
+function patternToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^$()|[\]\\?]/g, "\\$&");
+    const translated = escaped
+        .replace(/\*\*\//g, "\u0000")
+        .replace(/\*\*/g, "\u0001")
+        .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));
+        }
+    }
+}
+function expandPattern(pattern, cwd) {
+    const results = [];
+    for (const variant of braceExpand(pattern)) {
+        const segments = variant.split("/");
+        const firstWild = segments.findIndex((segment) => segment.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) {
+            const rel = relative(cwd, file).split("\\").join("/");
+            if (matcher.test(rel))
+                results.push(rel);
+        }
+    }
+    return [...new Set(results)].sort();
+}
+function expandPatterns(patterns, cwd) {
+    return [...new Set(patterns.flatMap((pattern) => expandPattern(pattern, cwd)))];
+}
+function findPackageJson(file, cwd) {
+    let dir = dirname(resolve(cwd, file));
+    while (true) {
+        const candidate = join(dir, "package.json");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function parseArgs(args) {
+    const patterns = [];
+    let profile;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index] ?? "";
+        if (arg === "--profile") {
+            const value = args[++index];
+            if (value !== "direct-sdk" && value !== "backend-proxy") {
+                return { patterns, error: "--profile must be direct-sdk or backend-proxy" };
+            }
+            profile = value;
+        }
+        else if (arg.startsWith("--profile=")) {
+            const value = arg.slice("--profile=".length);
+            if (value !== "direct-sdk" && value !== "backend-proxy") {
+                return { patterns, error: "--profile must be direct-sdk or backend-proxy" };
+            }
+            profile = value;
+        }
+        else if (arg.startsWith("-")) {
+            return { patterns, error: `Unknown option: ${arg}` };
+        }
+        else {
+            patterns.push(arg);
+        }
+    }
+    return { patterns, profile };
+}
+export async function runVerifyCli(args, out = process.stdout, err = process.stderr) {
+    const parsed = parseArgs(args);
+    if (parsed.error || parsed.patterns.length === 0) {
+        if (parsed.error)
+            err.write(`${parsed.error}\n`);
+        err.write('Usage: verify [--profile direct-sdk|backend-proxy] "<glob>" [more globs or files]\n' +
+            '  e.g. verify "src/**/*.{ts,tsx}"\n' +
+            "Exits 1 on any error-severity finding, 2 when nothing matched.\n");
+        return 2;
+    }
+    const cwd = process.cwd();
+    const files = expandPatterns(parsed.patterns, cwd);
+    if (files.length === 0) {
+        err.write(`Nothing matched: ${parsed.patterns.join(" ")}\n`);
+        return 2;
+    }
+    const groups = new Map();
+    for (const file of files) {
+        const packagePath = findPackageJson(file, cwd) ?? join(cwd, "package.json");
+        groups.set(packagePath, [...(groups.get(packagePath) ?? []), file]);
+    }
+    let errors = 0;
+    let warnings = 0;
+    for (const [packagePath, groupFiles] of [...groups.entries()].sort()) {
+        let packageJson = {};
+        if (existsSync(packagePath)) {
+            try {
+                packageJson = JSON.parse(readFileSync(packagePath, "utf8"));
+            }
+            catch (error) {
+                err.write(`Invalid package.json at ${relative(cwd, packagePath)}: ${error.message}\n`);
+                return 2;
+            }
+        }
+        const result = verifyRuntimeContract({
+            files: groupFiles.map((path) => ({ path, source: readFileSync(path, "utf8") })),
+            packageJson,
+            profile: parsed.profile,
+        });
+        out.write(`profile: ${result.profile}\n`);
+        for (const finding of result.findings) {
+            if (finding.severity === "error")
+                errors++;
+            else
+                warnings++;
+            const line = finding.line === undefined ? "" : `:${finding.line}`;
+            out.write(`${finding.path}${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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@venlyfinance/sdk": "^0.4.0",
+    "@venlyfinance/sdk": "^0.5.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },