@venlyfinance/settlement-mcp 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.8.0 – 2026-08-22
+
+- The runtime `@venlyfinance/sdk` dependency moves to `^0.7.0`, so the server's own
+  data plane matches the world its blueprints describe (0.7.1 and earlier installed a
+  0.5.x sdk at runtime).
+- The `send` journey blueprint is rewritten for the one-door send surface: recipient-object
+  fork (platform directory · saved payout recipients · own bank account), step-up
+  confirmation on every money confirm, and the forbidden-to-invent list (fee row, "No fee"
+  claim, ETA, pre-create rate, named stages beyond the status enum, any external-wallet
+  surface).
+- New `console-webhooks` journey blueprint; the operator-console blueprints
+  (`console-review-queue`, `console-decision-detail`, `console-pricing-config`,
+  `console-simulator`) now name their shipped registry blocks instead of empty arrays.
+
+## 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

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 /** 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.7.0";
+export declare const SERVER_VERSION = "0.8.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";

package/dist/constants.js

@@ -1,7 +1,7 @@
 /** 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.7.0";
+export const SERVER_VERSION = "0.8.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) {

package/dist/frontend.d.ts

@@ -14,17 +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. 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.";
+    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

@@ -37,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.
@@ -83,8 +116,10 @@ Rules that must hold: the optimistic-locking version travels with every decision
 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.
+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,
@@ -109,7 +144,8 @@ 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.
+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,
@@ -132,8 +168,12 @@ 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.
+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
@@ -158,7 +198,10 @@ 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.
+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
@@ -176,68 +219,135 @@ 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.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@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.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
         "@tanstack/react-query": "^5.0.0",
     },
     "bank-accounts": {
-        "@venlyfinance/react": "^0.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@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.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
         "@tanstack/react-query": "^5.0.0",
     },
     receive: {
-        "@venlyfinance/react": "^0.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@venlyfinance/react": "^0.6.0",
+        "@venlyfinance/sdk": "^0.7.0",
         "@tanstack/react-query": "^5.0.0",
     },
     reconciliation: {
-        "@venlyfinance/react": "^0.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@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.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@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.4.0",
-        "@venlyfinance/sdk": "^0.5.0",
+        "@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 - the console screens are built from primitives
+ * 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 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.
+ * 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.4.0",
-    "@venlyfinance/sdk": "^0.6.0",
+    "@venlyfinance/react": "^0.6.0",
+    "@venlyfinance/sdk": "^0.7.0",
     "@tanstack/react-query": "^5.0.0",
 };
 const JOURNEY_RUNTIME = {
@@ -253,7 +363,37 @@ const JOURNEY_RUNTIME = {
     },
     "home-balances": { blocks: ["balances"], hooks: ["useAccounts", "useWallets"] },
     receive: { blocks: ["receive"], hooks: ["useVirtualBankAccounts"] },
-    send: { blocks: ["send"], hooks: ["useStagedTransfer", "useFeeQuote"] },
+    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"],
@@ -286,8 +426,7 @@ const JOURNEY_RUNTIME = {
         hooks: ["useRampRequests", "useFourEyesApproval", "useRampLifecycle"],
     },
     "console-review-queue": {
-        blocks: [],
-        registryItems: ["venly-tokens", "data-table", "status-pill", "money", "list-error"],
+        blocks: ["console-queue"],
         dataPlane: true,
         hooks: ["useAccounts", "useParties"],
         extraForbidden: [
@@ -297,16 +436,7 @@ const JOURNEY_RUNTIME = {
         ],
     },
     "console-decision-detail": {
-        blocks: [],
-        registryItems: [
-            "venly-tokens",
-            "side-panel",
-            "timeline",
-            "field-list",
-            "status-pill",
-            "money",
-            "data-table",
-        ],
+        blocks: ["console-decision"],
         dataPlane: true,
         hooks: [
             "useAccount",
@@ -324,18 +454,17 @@ const JOURNEY_RUNTIME = {
         ],
     },
     "console-pricing-config": {
-        blocks: [],
-        registryItems: ["venly-tokens", "data-table", "arithmetic-ladder", "field-list"],
+        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: [],
-        registryItems: ["venly-tokens", "field-list", "status-pill", "money"],
+        blocks: ["console-simulator"],
         dataPlane: true,
         hooks: ["useVenlyMock"],
         extraForbidden: [
@@ -345,6 +474,24 @@ const JOURNEY_RUNTIME = {
             "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"]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.7.0",
+  "version": "0.8.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.5.0",
+    "@venlyfinance/sdk": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },