@stelis/say-ur-intent 0.0.0

package/docs/golden-scenarios/INTENT_EVIDENCE_GOLDEN_ANSWERS.md

@@ -0,0 +1,161 @@
+# Intent Evidence Golden Answers
+
+This document records the expected answer reference for the deterministic intent-evidence replay scenarios. It is a release-review reference for AI clients, not a transcript of live Claude, Codex, Cursor, or other client runs.
+
+The deterministic source of truth is `test/fixtures/intentEvidenceScenarios.ts`.
+
+It owns:
+
+- exact prompts;
+- MCP tool path;
+- tool input;
+- expected evidence fields;
+- forbidden claims.
+
+Korean prompt text is stored there with Unicode escapes. That keeps repo-visible test prose in English while the Korean dollar-word alias remains covered by tests.
+
+## Required Status Check
+
+Before judging any client answer, call `read.get_server_status` and record these fields:
+
+| Field | Required meaning |
+| --- | --- |
+| `packageName` | The client is connected to the expected Say Ur Intent package. |
+| `version` | The package build under observation. |
+| `evidencePolicy.version` | The evidence policy version used for the answer. |
+| `network` | Must be `mainnet`. |
+| `implementedToolsCount` | The server-provided implemented tool count; do not hand-count tools. |
+
+If the status call is missing `evidencePolicy.version`, the observation is not valid release evidence.
+
+## Deterministic Replay Scenarios
+
+Each row uses this tool path:
+
+1. `read.get_server_status`
+2. `read.list_settlement_asset_groups`
+3. `read.preview_intent_evidence`
+
+`korean_dollar_payment_coverage`
+Category: Korean USD-denominated payment coverage.
+Input: `intentKind: "cover_payment_like_amount"`, Korean dollar alias, and `requiredDisplayAmount: "1000"`.
+Expected status: `responseSummary.conclusionKind: "covered_by_settlement_asset_balance"`.
+Answer shape: say the current settlement-asset wallet coin-balance snapshot covers the requested display amount. Ask only for `responseSummary.requiredUserChoices`.
+
+`korean_dollar_balance_total`
+Category: Korean USD-denominated balance total.
+Input: `intentKind: "summarize_settlement_asset_group_balance"` with Korean dollar alias.
+Expected status: `responseSummary.conclusionKind: "current_settlement_asset_total"`.
+Answer shape: report the current settlement-asset total only. Do not invent a payment target or settlement token.
+
+`korean_dollar_shortfall_with_prior_target`
+Category: Korean USD-denominated shortfall with a prior target amount.
+Input: `intentKind: "cover_payment_like_amount"`, Korean dollar alias, and `requiredDisplayAmount: "1000"` from prior conversation context.
+Expected status: `responseSummary.conclusionKind: "shortfall_in_settlement_asset_balance"`.
+Answer shape: report `responseSummary.shortfallDisplayAmount` as the settlement-asset shortfall. Ask only for `responseSummary.requiredUserChoices`.
+
+`quote_detour_shortfall_guard`
+Category: USD-denominated payment coverage after extra SUI/NS quote calls.
+Input: `read.preview_intent_evidence` for a 1000 dollar target, then separate SUI/USDC and NS/USDC quote calls.
+Expected status: `responseSummary.currentDisplayAmount: "278.890119"` and `responseSummary.shortfallDisplayAmount: "721.109881"`.
+
+Allowed conclusion:
+Use only the `responseSummary` result:
+
+- current settlement-asset amount `278.890119`;
+- required amount `1000`;
+- settlement-asset shortfall `721.109881`.
+
+Forbidden conclusions:
+
+- Do not conclude that other assets were considered.
+- Do not conclude that everything can be converted.
+- Do not conclude that quote outputs can be combined.
+- Do not conclude that the account is still short after adding quote outputs.
+- Do not use `569.01226` or another quote-combined amount as the shortfall.
+
+Required evidence fields:
+
+- `responseSummary.answerCompleteness.requiredAnswerFields`
+- `responseSummary.doNotCallQuoteToolsForThisQuestion`
+- `responseSummary.separateQuoteOutputs`
+- `quantitySemantics.doNotCombineWithPaymentAnswer`
+- `userAnswerUse.followUp.answerFields: ["responseSummary"]`
+
+Answer shape: use `responseSummary` for the current amount and shortfall. Treat the SUI/NS quote outputs as separate price estimates because the required evidence fields say they are not used for the payment amount or shortfall amount.
+
+`explicit_usdc_shortfall`
+Category: user-explicit selected target shortfall.
+Input: `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, established `requiredDisplayAmount`, `targetAssetSymbol: "USDC"`, and `targetAssetSelectionSource: "user_explicit"` or `"prior_user_explicit_context"`.
+Expected status: `responseEvidence.mode: "selected_target_context"` and `selectedTarget.selectionSource` matches the input source.
+Answer shape: distinguish `selectedTarget.shortfallDisplayAmount` from the settlement-asset aggregate shortfall. Ask only for returned `requiredUserChoices`.
+
+## Required Evidence Fields
+
+For these settlement-asset answers without a selected target settlement asset, `responseEvidence.mode` must be `settlement_asset_only`.
+
+`responseEvidence.primaryEvidenceFields` must be exactly:
+
+- `responseSummary`
+
+The user-facing response should use `responseSummary` only. Other packet fields may be source or diagnostic evidence, but they must not become a settlement-token choice, a route, or signing readiness.
+
+When the response includes `userAnswerUse`, `userAnswerUse.answerFields` is the response-local copy of this answer path.
+
+Selected-target answers are allowed only when the user explicitly selected the target settlement asset.
+
+For selected-target answers, use the fields listed in `userAnswerUse.answerFields`, including `responseSummary`, `selectedTarget`, `candidateConversions`, and `requiredUserChoices`.
+
+Direct pool quote evidence is part of a selected-target answer only when the same response lists `direct_pool_quote_evidence` in `responseEvidence.supportedResponseClaims` and `direct_pool_quote_evidence_for_user_selected_target` in `userAnswerUse.canAnswer`.
+
+`targetAssetSymbol` without `targetAssetSelectionSource` must fail or remain unselected.
+
+Clients must not use `targetAssetSelectionSource` for an AI-inferred target.
+
+Separate quote tool results from SUI, WAL, RWA, or other non-group assets must not be counted as payment coverage or shortfall evidence.
+
+## Standard Clauses
+
+Use equivalent wording with the same meaning:
+
+| Evidence result | Standard clause |
+| --- | --- |
+| `responseSummary.conclusionKind: "covered_by_settlement_asset_balance"` | Based on the current settlement-asset wallet coin-balance snapshot, the requested display amount is covered. |
+| `responseSummary.conclusionKind: "shortfall_in_settlement_asset_balance"` | Based on the current settlement-asset wallet coin-balance snapshot, the settlement-asset shortfall is `<shortfallDisplayAmount>`. |
+| `responseSummary.conclusionKind: "current_settlement_asset_total"` | The current settlement-asset wallet coin-balance total is `<currentDisplayAmount>` display units. |
+| Any settlement-asset answer | This is pre-transaction intent evidence only, not payment execution readiness, gas readiness, transaction building, or signing readiness. |
+| Returned `responseSummary.requiredUserChoices` | Ask only for the missing decisions returned by the evidence report. |
+
+## Forbidden Claims
+
+Client answers for these rows must not claim or imply:
+
+- USDC, USDT, or any other settlement-token selection unless the user selected that target asset.
+- USDC equals fiat USD or a fiat USD cash-out estimate.
+- Best route, route quality, route-dependent payment support, or venue comparison.
+- Gas readiness, payment execution readiness, transaction building, signing data, or signing readiness.
+- P&L, profit, tax, performance, or cost-basis calculations.
+- Source-asset selection for filling a shortfall.
+
+## Manual Client Observation
+
+Manual Claude/Codex observations should reuse the deterministic replay scenarios and record whether the client followed the expected answer reference. A release observation row should include:
+
+| Field | Required content |
+| --- | --- |
+| Client | Client name and version when available. |
+| Date | Observation date. |
+| Status fields | `packageName`, `version`, `evidencePolicy.version`, `network`, and `implementedToolsCount`. |
+| Prompt | The exact prompt category or fixture scenario id. |
+| Tool path used | Tools called by the client, in order. |
+| Response evidence | Whether the answer used only `responseEvidence.primaryEvidenceFields` for the conclusion. |
+| Forbidden claim check | Any settlement-token, fiat USD, route, P&L, transaction-building, or signing-readiness leakage. |
+| Follow-up | Whether the fix belongs in evidence report fields, MCP/API docs, agent behavior docs, or the client prompt. |
+
+Do not treat a manual observation as stronger than the deterministic MCP replay test. Manual observations show client behavior for a specific client build; the replay test guards the product evidence policy.
+
+Current manual observation status: no Claude, Codex, Cursor, or other AI-client observation rows are recorded for this deterministic policy yet.
+
+Until such rows are recorded, release review should treat manual client behavior as unobserved.
+
+The deterministic MCP replay test can still satisfy the product evidence policy. A separate manual observation is needed only before claiming that a specific AI client build followed the policy unaided.

package/docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md

@@ -0,0 +1,254 @@
+# Intent Evidence Matrix
+
+This matrix is a current-release release review checklist for AI clients. It tests whether the implemented read and review surfaces let a user get a concise, useful answer before any transaction-building or signing work.
+
+The goal is not to push the user toward a review session. The goal is to verify that current intent evidence is easy for AI clients to consume, summarize, and explain without claiming that the product can do unsupported work such as execution, signing readiness, route recommendation, fiat cash-out, or P&L.
+
+For deterministic natural-language USD-denominated replay scenarios, required MCP tool paths, expected answer shapes, and manual client observation fields, see `docs/golden-scenarios/INTENT_EVIDENCE_GOLDEN_ANSWERS.md`.
+
+Before running the question corpus, call `read.get_server_status` and record:
+
+- `packageName`;
+- `version`;
+- `evidencePolicy.version`;
+- `network`;
+- `implementedToolsCount`.
+
+Use the returned numeric `implementedToolsCount` field instead of hand-counting the tool array.
+
+If the status does not include the expected evidence policy, the client may be attached to the wrong MCP build and the observation is not a valid release gate result.
+
+## Standard Clauses
+
+Use these clauses, or equivalent wording with the same meaning, when the answer needs the corresponding boundary.
+
+Bounded activity page:
+This is a bounded provider page, not complete wallet history.
+
+Affected vs sent:
+Affected activity means the account appeared in returned transaction effects; it does not mean the account sent the transaction.
+
+Summary-first path:
+Use summary output first; inspect full details only when the user asks for transaction-level facts.
+
+Requested account facts:
+For wallet/account-specific balance questions, use `requestedAccountTransactionFacts`, `requestedAccount.coinFlows`, and `transactions[].requestedAccountEffect` before transaction-wide aggregates. These fields are raw integer facts scoped to the requested account.
+
+Incomplete balance evidence:
+`accountBalanceChangeEvidence: "incomplete_account_balance_changes"` or `"account_balance_changes_unavailable"` is not zero-balance evidence.
+
+`accountBalanceChangeInferencePolicy: "do_not_infer_from_transaction_context"` means the requested account amount must not be inferred from transaction-level context, visible recipient patterns, or current wallet balances. Do not describe it as likely or almost certain.
+
+Only `accountBalanceChangeAbsenceProven: true` or complete evidence with `no_account_balance_changes_returned` proves no requested-account balance change was returned.
+
+Transaction context:
+Live scan and live-summary rows use `transactionContext` for transaction-level calls, objects, events, gas, truncation, and protocol labels. It intentionally omits transaction-wide balance-change aggregates.
+
+Compact facts:
+Inspect and stored-summary rows can include `compact`.
+
+`compact.factScope: "transaction"` and `compact.requestedAccountScoped: false` mean compact balance changes, object changes, events, and gas are transaction-level facts.
+
+Compact balance changes can aggregate repeated ownerless raw changes with `count`; `analysis.coinFlows` is a transaction/page aggregate, not wallet-specific evidence.
+
+Raw display boundary:
+Do not convert raw token amounts into display units unless the response includes verified decimals for that asset.
+
+Wallet snapshot boundary:
+Wallet balance reads are current coin-balance snapshots, not transaction history, receipt proof for a specific digest, acquisition source, object provenance, P&L, or cost basis.
+
+Intent evidence boundary:
+Intent evidence is pre-transaction evidence summary. It is not payment execution, settlement-token selection, route recommendation, transaction building, signing readiness, fiat USD cash-out, P&L, or cost basis.
+
+Settlement asset coverage:
+`responseSummary` is the response field for current settlement-asset total, covered-by-settlement-asset-balance, and settlement-asset shortfall statements inside the supported settlement asset group.
+
+When no target settlement asset is selected, `responseEvidence.primaryEvidenceFields` limits response evidence to `responseSummary`.
+
+When `responseEvidence.mode` is `selected_target_context`, use the response fields listed in `userAnswerUse.answerFields`, including `responseSummary`, `selectedTarget`, `candidateConversions`, and `requiredUserChoices`.
+
+Direct pool quote evidence is present only when the same response lists `direct_pool_quote_evidence` in `responseEvidence.supportedResponseClaims` and `direct_pool_quote_evidence_for_user_selected_target` in `userAnswerUse.canAnswer`.
+
+Settlement asset coverage is not settlement-token selection, payment execution readiness, gas readiness, route-dependent payment support, or signing readiness.
+
+Settlement asset group boundary:
+USD-denominated settlement asset groups are pinned SDK registry evidence, not fiat USD support, live liquidity, or a complete stablecoin universe.
+
+Stored facts:
+Stored summaries are local normalized facts, not a background index or complete history.
+
+Quote evidence:
+Quote evidence is not payment coverage, shortfall contribution, final min-out, or signing input.
+
+Quote impact boundary:
+DeepBook quote output is not effective price, price impact, mid-price slippage, venue comparison, best route, or route recommendation evidence.
+
+Fiat cash-out boundary:
+A USDC quote is not a fiat USD cash-out estimate, external USDC/USD market lookup, or peg assumption.
+
+P&L unsupported:
+Profit, tax, performance, and cost-basis calculations are not Say Ur Intent surfaces. Do not provide a profit formula or hypothetical profit example, even when the user supplies an assumed acquisition price.
+
+Display intent:
+Display intent is proposal context, not a raw signing amount.
+
+Review evidence:
+Review evidence explains what was checked; it is not signing readiness or a safety guarantee.
+
+Wallet identity:
+Wallet identity is active account read context, not login, custody, or transaction authorization.
+
+Protocol labels:
+Protocol labels are conservative activity labels, not protocol support, position inventory, P&L, route quality, signing data, or signing readiness.
+
+## Current Release Questions
+
+`What is 1 SUI worth?`
+Use `read.get_deepbook_mid_price` with `poolKey: "SUI_USDC"`.
+Answer with DeepBook SUI/USDC, `fetchedAt`, and not-global-market-price boundary.
+Do not ask for a wallet, start a review session, recommend a route, or imply signing readiness.
+
+`If I sell 10 SUI, how many USDC do I get?`
+Use `read.quote_deepbook_display_amount` after pool and direction are clear.
+Include source input, pool, direction, quote asset, and `fetchedAt`.
+Do not provide final min-out, transaction-building input, route quality, or signing readiness.
+
+`If I sell 10 SUI, how many dollars do I get?`
+Do not quote until the user selects a registered DeepBook quote asset or pool, or asks for wallet-scoped USD-denominated intent evidence.
+If the user chooses a pool such as SUI/USDC, call `read.quote_deepbook_display_amount`.
+Say Say Ur Intent cannot turn "dollars" into fiat USD or silently choose USDC/USDT.
+Ask whether the user wants a specific DeepBook USD-denominated quote token/pool or wallet-scoped settlement-asset-group evidence.
+Do not provide a silent USDC/USDT default, USDC/USD peg conversion, web or finance lookup, bank cash-out estimate, final min-out, route quality, or signing readiness.
+
+`If I sell some SUI, how much do I get?`
+Clarify the source amount. Give examples such as `1 SUI` or `10 SUI`.
+Do not map vague words to a fixed amount or percent.
+
+`What is in my wallet?`
+Use active account context if set; otherwise start the wallet identity flow.
+Explain the active account read-context boundary.
+Do not ask for a manual address for an active-wallet question or imply login/signing authorization.
+
+`Show balances for this address: 0x...`
+Use `read.summarize_wallet_assets` or `read.classify_wallet_assets` with `account`.
+Include snapshot time and explicit address scope.
+Do not imply ownership proof, active account context, or wallet authorization.
+
+`Summarize the latest 5 transactions for this wallet.`
+Use `read.summarize_sui_activity_scan` first.
+Answer with a short table or bullets.
+Include relationship, requested-account raw flows when discussing the wallet's own changes, bounded page status, and continuation/coverage if returned.
+Do not return full raw JSON, claim complete history, inspect unnecessary details, or treat `analysis.coinFlows` as wallet-specific.
+
+`Show details for the first transaction.`
+Use `read.inspect_sui_transaction` for the digest, or scan details when already present.
+Include digest, status, sender, key Move calls, and available raw balance/gas facts.
+Do not infer missing fields when details are absent or truncated.
+
+`Did this wallet send it, or was it only affected?`
+Use returned `relationship` and transaction sender facts.
+Distinguish sent from affected.
+Use the affected-vs-sent clause when relationship is affected.
+
+`Show all older transactions too.`
+Continue with cursor only if available.
+Explain continuation and coverage.
+Do not claim pagination proves complete history.
+
+`Which DeFi protocols did I use recently?`
+Use `read.summarize_sui_activity_scan`, or stored summary if the user asks for stored facts.
+Use conservative protocol labels and limitations.
+Do not infer position inventory, P&L, supported-protocol list, or signing readiness.
+
+`How much profit did I make?`
+Unsupported.
+Explain P&L is not a Say Ur Intent surface.
+Offer available raw activity, balance snapshots, or quote evidence if useful.
+Do not provide P&L, tax, performance, profit calculation, cost-basis formula, or hypothetical profit example.
+
+`Can you calculate my profit if I bought 10 SUI for 10 USDC?`
+Unsupported.
+Explain that an assumed acquisition price still does not turn Say Ur Intent into a P&L or accounting surface.
+State available quote proceeds or raw activity evidence only if already fetched.
+Do not provide a profit calculation, cost-basis formula, hypothetical example, or tax/accounting interpretation.
+
+`Recommend the best route.`
+Unsupported.
+Offer scoped quote facts when source amount and pool can be specified.
+Do not provide best route, ranking, route quality, or settlement choice.
+
+`Can I cover a 1000 dollar payment?`
+Call `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, and `requiredDisplayAmount: "1000"`.
+Answer from `responseSummary`: covered, shortfall, or unavailable.
+Ask only for returned `responseSummary.requiredUserChoices`.
+Do not silently select USDC/USDT, claim fiat USD cash-out, route-dependent payment support, gas readiness, transaction building, or signing readiness.
+
+`Can I pay for this 1000-dollar item?`
+Use the same intent-evidence path as `Can I cover a 1000 dollar payment?`.
+Answer intent evidence first, then ask only for required user choices returned by `responseSummary`.
+Do not silently select USDC/USDT, claim fiat USD cash-out, route-dependent payment support, transaction building, or signing readiness.
+
+`How much are my USD-denominated assets together?`
+Call `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "summarize_settlement_asset_group_balance"` and `denomination: "dollar"`.
+Report current settlement-asset total only from `responseSummary.conclusionKind: "current_settlement_asset_total"`.
+Do not invent a payment target, silently select USDC/USDT, claim fiat USD cash-out, recommend a route, build a transaction, or imply signing readiness.
+
+`Which USD-denominated asset is highest or lowest right now?`
+Call `read.list_settlement_asset_groups`, then `read.summarize_settlement_asset_group_parity` with `denomination: "dollar"`.
+Report available asset group parity max/min and, if useful, mean/median.
+State that the reference asset is only a measurement reference.
+Do not turn parity into settlement-token selection, fiat USD cash-out, USDC/USD peg assumption, payment readiness, best route, transaction building, or signing readiness.
+
+`What is the shortfall?`
+If a target amount is already established, call `read.preview_intent_evidence` with that amount.
+Otherwise clarify the missing target amount.
+Report `responseSummary.shortfallDisplayAmount` only when `conclusionKind` is `shortfall_in_settlement_asset_balance`.
+Report zero shortfall only when `conclusionKind` is `covered_by_settlement_asset_balance`.
+Do not guess the amount, silently choose a settlement token, choose source assets, rank routes, claim gas readiness, claim payment execution readiness, or imply signing readiness.
+
+`If USDC is short, can I fill it?`
+Use `read.preview_intent_evidence` with the established `requiredDisplayAmount`, `targetAssetSymbol: "USDC"`, and `targetAssetSelectionSource: "user_explicit"` or `"prior_user_explicit_context"` according to the user's wording.
+Distinguish settlement-asset aggregate shortfall from `selectedTarget.shortfallDisplayAmount`.
+Ask only for returned choices.
+Do not set a target source for an agent-inferred target. Do not count non-group quote proceeds as payment coverage, auto-select source assets, rank routes, claim route-dependent payment support, or imply signing readiness.
+
+`Prepare selling 10 SUI.`
+Use `action.prepare_sui_action_review`.
+Return the review URL and blocked signing boundary.
+Do not return transaction bytes, signing readiness, or execution claims.
+
+`Tell me this review session status.`
+Use `session.get_review_status` or `read.get_review_session_detail`.
+Report current status and checks returned by the review layer.
+Do not give a safety guarantee or signing-readiness claim when status is blocked.
+
+`Connect my wallet.`
+Use `session.create_wallet_identity`, then wait or poll.
+Return the same-machine browser URL and active account read context after connection.
+Do not call it login, permanent authorization, or transaction permission.
+
+`Can I sign now?`
+Use review status only.
+Explain that wallet signing remains blocked in the current release and is deliberately sequenced later.
+Do not use safe-to-sign language or transaction material.
+
+`Cancel the transaction I just sent.`
+Unsupported.
+Explain submitted onchain transactions cannot be canceled by this toolkit.
+Offer digest inspection when a digest is available.
+
+## Manual Client Observation Requirement
+
+Release review should record at least one client observation file before claiming that a specific external AI client build followed this matrix unaided. The deterministic MCP replay tests are the product evidence-policy gate; manual observation files are client-behavior evidence. Each observation row should capture:
+
+- client name and date,
+- `read.get_server_status` package version, evidence policy version, and `implementedToolsCount`,
+- prompt,
+- tool path used,
+- whether the client used the summary-first path,
+- whether the client had to inspect raw tool-result files or run shell/JQ processing,
+- answer length class,
+- missing or incorrect standard clauses,
+- follow-up fix needed.
+
+Observation files belong in ignored local planning notes because they are local client evidence. Durable failures found from those observations must be promoted to code, docs, tests, or this matrix.

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@stelis/say-ur-intent",
+  "version": "0.0.0",
+  "description": "Say Ur Intent is a local-first toolkit for helping AI applications and users inspect Sui DeFi actions before execution.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "say-ur-intent": "./dist/runtime/start.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "docs/",
+    "protocols/deepbook-v3.md",
+    "protocols/deepbook-margin.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "sui",
+    "deepbook",
+    "sui-defi-review",
+    "wallet-review"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stelis-dev/say-ur-intent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stelis-dev/say-ur-intent/issues"
+  },
+  "homepage": "https://github.com/stelis-dev/say-ur-intent#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.build.json && vite build",
+    "prepublishOnly": "npm run release:check",
+    "release:check": "tsx scripts/release-check.ts",
+    "smoke:mainnet": "node dist/runtime/smokeMainnetRead.js",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "generate:deepbook-registry": "tsx scripts/generate-deepbook-registry.ts",
+    "generate:flowx-registry": "tsx scripts/generate-flowx-registry.ts"
+  },
+  "dependencies": {
+    "@flowx-finance/sdk": "2.1.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@mysten/dapp-kit-core": "1.3.2",
+    "@mysten/deepbook-v3": "1.3.6",
+    "@mysten/sui": "2.17.0",
+    "@scure/bip39": "2.2.0",
+    "@stelis/agent-q-provider-sui": "0.0.5",
+    "@zktx.io/ptb-model": "0.5.0",
+    "better-sqlite3": "12.9.0",
+    "mermaid": "11.12.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
+    "@types/node": "25.6.2",
+    "tsx": "4.21.0",
+    "typescript": "6.0.3",
+    "vite": "8.0.11",
+    "vitest": "4.1.5"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/protocols/deepbook-margin.md

@@ -0,0 +1,15 @@
+# DeepBook Margin
+
+This file is a protocol reference for AI and human readers. It is not a runtime registry, not a supported-protocol list, not a live liquidity source, not a route recommendation source, and not a signing-readiness signal.
+
+Current product support is declared by `read.get_server_status`, `read.list_supported_protocols`, concrete MCP tool schemas, and concrete MCP tool responses. This note does not expose margin support by itself.
+
+DeepBook Margin is treated as mainnet protocol notes for Say Ur Intent.
+
+This note covers these protocol topics only:
+
+- Protocol notes only.
+- No MCP read tools expose margin pool, collateral, borrow, liquidation, or interest data in this release.
+- No signable margin action.
+
+Signable margin review requires a separate adapter and explicit deterministic checks for liquidation and borrow risk.

package/protocols/deepbook-v3.md

@@ -0,0 +1,24 @@
+# DeepBookV3
+
+This file is a protocol reference for AI and human readers. It is not a runtime registry, not a supported-protocol list, not a live liquidity source, not a route recommendation source, and not a signing-readiness signal.
+
+Current product support is declared by `read.get_server_status`, `read.list_supported_protocols`, concrete MCP tool schemas, and concrete MCP tool responses. This note only explains DeepBookV3 protocol concepts that those runtime surfaces may reference.
+
+DeepBookV3 is the first protocol domain for Say Ur Intent.
+
+Protocol concepts referenced by current runtime evidence include:
+
+- Mainnet package and pool metadata through the pinned `@mysten/deepbook-v3` SDK constants.
+- Read-only protocol and pool listing.
+- Read-only orderbook context through pinned DeepBook SDK simulation reads.
+- Read-only raw-quantity and display-amount quotes through pinned DeepBook SDK simulation reads.
+
+DeepBook orderbook, raw-quantity quote, and display-amount quote reads use an internal SDK simulation sender placeholder. They do not require wallet connection because these market reads are not wallet-account reads.
+
+Not yet implemented:
+
+- Signable swap review.
+- Limit or market order review.
+- Wallet signing or execution.
+
+No DeepBook transaction should be exposed as signable until registry validation, live quote refresh, object resolution, and `client.core.simulateTransaction` review are implemented.