@venlyfinance/settlement-mcp 0.6.0 → 0.7.0

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,26 @@
 # Changelog
 
+## 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.0";
+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.0";
+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

@@ -21,6 +21,10 @@ declare const JOURNEYS: {
     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. The\nregistry has no console block yet: compose these primitives.\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.\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.\nRegistry items: venly-tokens, data-table, arithmetic-ladder, field-list.\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.\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.";
 };
 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)
@@ -78,8 +79,331 @@ 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. The
+registry has no console block yet: compose these primitives.
+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.
+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.
+Registry items: venly-tokens, data-table, arithmetic-ladder, field-list.
+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.
+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.`,
 };
 const JOURNEY_KEYS = Object.keys(JOURNEYS);
+const RUNTIME_PACKAGES_BY_BLOCK = {
+    activity: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    auth: { "@radix-ui/react-one-time-password-field": "^0.1.16" },
+    balances: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    "bank-accounts": {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    onboarding: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    receive: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    reconciliation: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    send: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+    team: { "@radix-ui/react-dialog": "^1.1.23" },
+    withdraw: {
+        "@venlyfinance/react": "^0.4.0",
+        "@venlyfinance/sdk": "^0.5.0",
+        "@tanstack/react-query": "^5.0.0",
+    },
+};
+/**
+ * The package set any hook-using screen needs, for journeys the registry has no
+ * composite block for yet - the console 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 sdk range is the one the console screens themselves need: they render the
+ * mock's channel state and balances that move on a transfer, and both arrived in
+ * 0.6.0. Composite block registry items stamp their own range from
+ * ui/package.json, which is older; a console screen built against that range
+ * would describe states it cannot reach.
+ */
+const DATA_PLANE_PACKAGES = {
+    "@venlyfinance/react": "^0.4.0",
+    "@venlyfinance/sdk": "^0.6.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"], hooks: ["useStagedTransfer", "useFeeQuote"] },
+    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: [],
+        registryItems: ["venly-tokens", "data-table", "status-pill", "money", "list-error"],
+        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: [],
+        registryItems: [
+            "venly-tokens",
+            "side-panel",
+            "timeline",
+            "field-list",
+            "status-pill",
+            "money",
+            "data-table",
+        ],
+        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: [],
+        registryItems: ["venly-tokens", "data-table", "arithmetic-ladder", "field-list"],
+        dataPlane: true,
+        hooks: ["useCompanyFees"],
+        extraForbidden: [
+            "an arithmetic ladder over figures the API does not serve",
+            "a single-member enum rendered as a select",
+        ],
+    },
+    "console-simulator": {
+        blocks: [],
+        registryItems: ["venly-tokens", "field-list", "status-pill", "money"],
+        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",
+        ],
+    },
+};
+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 +766,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.0",
   "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"
   },