@stelis/say-ur-intent 0.0.0

package/docs/UTILITY_INDEX.md

@@ -0,0 +1,180 @@
+# Utility Index
+
+Utilities are reusable state inspection or reporting surfaces for AI agents, maintainers, and local development.
+
+This document owns manual utility and script boundaries. It distinguishes source-checkout utilities from MCP tools and packaged product commands.
+
+Tool behavior references live in `docs/MCP_TOOLS.md`. Installation and client setup live in `docs/MCP_SETUP.md`.
+
+Rows that name MCP tools describe existing product tools.
+
+Rows that name `npm` commands or `scripts/` files describe manual utility surfaces only.
+
+Source-checkout scripts are not packaged product commands, MCP tools, review-time simulation, transaction builders, signing readiness signals, or wallet authorization evidence.
+
+## Implemented
+
+| Utility | Command / Tool | Status | Notes |
+| --- | --- | --- | --- |
+| DeepBook registry generation | `npm run generate:deepbook-registry` | Implemented | Generates ignored mainnet metadata from `@mysten/deepbook-v3@1.3.6` constants. |
+| MCP server status | `read.get_server_status` | Implemented | Reports package version, evidence policy version, runtime, `implementedToolsCount`, resources, prompts, and implementation limits. |
+| Supported protocol list | `read.list_supported_protocols` | Implemented | Reports product support levels. |
+| DeepBook pool list | `read.list_deepbook_pools` | Implemented | Reads pinned SDK mainnet pool metadata. |
+| DeepBook token list | `read.list_deepbook_tokens` | Implemented | Reads pinned SDK mainnet token metadata, registry pool references, and decimals derived from pinned scalar values. |
+| Orderbook inspection | `read.inspect_deepbook_orderbook` | Implemented | Uses pinned DeepBook SDK simulation read methods over Sui gRPC with an internal sender placeholder; `ticks` is capped at 50. |
+| DeepBook mid price | `read.get_deepbook_mid_price` | Implemented | Returns pinned SDK pool mid price snapshots. Not a global market price. |
+| Quote calculation | `read.quote_deepbook_action` | Implemented | Quotes raw integer DeepBook quantities with pinned SDK transaction builders and raw `u64` simulation return values. |
+| Display amount quote | `read.quote_deepbook_display_amount` | Implemented | Converts explicit source display amounts through pinned DeepBook token units before quoting; returns exact decimal display quote strings plus raw quote evidence. Quote semantics mark payment coverage and shortfall contribution unavailable. |
+| DeepBook account inventory | `read.summarize_deepbook_account_inventory` | Implemented | Reports display-like BalanceManager inventory. Not raw balance or signing readiness. |
+| Wallet asset summary | `read.summarize_wallet_assets` | Implemented | Reads Sui coin balances for an explicit address or the active account with Sui gRPC `client.core.listBalances`; adds verified unit/display data when available; use `cursor` when `hasNextPage` is true. |
+| Wallet asset classification | `read.classify_wallet_assets` | Implemented | Classifies returned coin balances by spendability and roles. Other asset classes are explicit non-inspected boundaries. |
+| Settlement asset group list | `read.list_settlement_asset_groups` | Implemented | Lists supported natural-language settlement asset groups derived from pinned DeepBook mainnet SDK registries. Not live liquidity, route recommendation, fiat cash-out, payment execution, or signing readiness. |
+| Intent evidence preview | `read.preview_intent_evidence` | Implemented | Builds `responseSummary` for USD-denominated coverage, shortfall, or settlement-asset balance total. |
+| Review activity list | `read.list_review_activity` | Implemented | Lists local Say Ur Intent review evidence for one account; not complete wallet transaction history. |
+| Review funnel summary | `read.summarize_review_funnel` | Implemented | Summarizes local review lifecycle counts, current statuses, sparse-sample warnings, and review timing. |
+| Review session detail | `read.get_review_session_detail` | Implemented | Returns a capped detail view of one stored review session with plan, state snapshots, transitions, and execution evidence. |
+| Sui transaction digest lookup | `read.inspect_sui_transaction` | Implemented | Looks up one Sui transaction digest and stores normalized facts only when the transaction sender or a returned balance-change owner matches a known local wallet. |
+| Sui account activity scan | `read.scan_sui_account_activity` | Implemented | Runs a bounded recent-to-older GraphQL scan with requested-account facts. Not complete history. |
+| Live Sui activity scan summary | `read.summarize_sui_activity_scan` | Implemented | Summarizes a live bounded scan without full details. Not P&L, position inventory, or complete history. |
+| Sui sent-function activity scan | `read.scan_sui_function_activity` | Implemented | Scans bounded sent transactions for one full `package::module::function`. Not global function history. |
+| Live Sui sent-function activity summary | `read.summarize_sui_function_activity_scan` | Implemented | Summarizes bounded sent-function rows. Not P&L, route recommendation, or signing readiness. |
+| Stored Sui activity summary | `read.summarize_sui_account_activity` | Implemented | Summarizes stored normalized Sui activity facts, including stored Move call, balance change, object/event, gas, execution error details, and optional protocol activity labels when evidence is available. |
+| Local settings | `settings.create_local_settings_session`, `settings.get_local_settings` | Implemented | MCP creates or reads local settings sessions. Settings mutations happen in the local settings page after token validation and apply after MCP server restart when they affect the endpoint. |
+| Mainnet read smoke | `npm run smoke:mainnet` | Manual | Runs selected mainnet read paths from built `dist/`. Build first. Not part of CI or `release:check`; see notes below. |
+| Sui GraphQL function filter probe | `npm exec -- tsx scripts/sui-graphql-function-filter-probe.ts [--endpoint <mainnet-graphql-url>] [--sample-size <1-50>] [--timeout-ms <ms>]` | Manual, source evidence only | Runs a read-only Sui mainnet GraphQL source-shape probe for function-filter diagnostics; see notes below. |
+| Sui CLI transaction diagnostics | `npm exec -- tsx scripts/sui-cli-transaction-diagnostics.ts -- --help` | Manual, source checkout only | Allowlisted local `sui` CLI debug evidence. See notes below. |
+
+## Mainnet Read Smoke Notes
+
+Run `npm run build` first because `npm run smoke:mainnet` executes `dist/runtime/smokeMainnetRead.js`.
+
+The smoke command calls:
+
+- wallet assets;
+- DeepBook orderbook;
+- raw-quantity DeepBook quote;
+- `read.scan_sui_account_activity` for `SMOKE_SUI_ADDRESS` with limit 5;
+- `read.summarize_sui_activity_scan` through active account context with limit 5;
+- `read.inspect_sui_transaction` when `SMOKE_INSPECT_DIGEST` is set;
+- sent-function activity tools when `SMOKE_FUNCTION_TARGET` is set to a full `package::module::function`.
+
+Empty activity pages are valid smoke outcomes. They are recorded with `rowCount: 0` and `emptyAccepted: true`.
+
+The result file records tool names, environment-variable presence, activity status, row counts, source method, window/order flags, persistence status, function-target presence, and evidence-boundary metrics.
+
+It does not store raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
+
+Activity scan and summary smoke paths fail if full transaction details or compact transaction aggregates are returned. The optional digest verifies storage only when its sender or returned balance-change owner is `SMOKE_SUI_ADDRESS`.
+
+If `SMOKE_INSPECT_RANDOM_LATEST=true` is set and no digest is provided, the script samples one latest GraphQL transaction digest and inspects it without an account argument.
+
+This smoke path does not call display-amount quote, DeepBook account inventory,
+account-bound DeepBook transaction-material build, or internal digest binding. A
+funded-account material-build smoke is a separate operator check before this
+read smoke can be used as product-grade proof for the DeepBook review material
+stage.
+
+## Sui GraphQL Function Filter Probe Notes
+
+The GraphQL function filter probe is read-only source-shape evidence for function-filter diagnostics.
+
+It verifies the endpoint chain identifier, samples recent public mainnet transaction details to obtain redacted filter values, and probes `TransactionFilter.function` combinations with account, object, kind, and checkpoint axes using `last: 1`.
+
+It writes an ignored local source-probe note with:
+
+- endpoint host;
+- chain identifier;
+- repository revision;
+- git worktree state;
+- Node version;
+- pinned `@mysten/sui` version;
+- schema hash;
+- probe script hash;
+- filter-key matrix;
+- result classifications;
+- capped row counts.
+
+The output redacts sampled digests, addresses, objects, and functions.
+
+It does not store raw GraphQL payloads, transaction bytes, signatures, raw transaction details, wallet position inventory, route quality, P&L, transaction-building inputs, signing data, or signing readiness.
+
+Network failures and mainnet guard failures are inconclusive evidence, not unsupported filter-combination findings.
+
+It is not an MCP tool, not packaged product functionality, not CI, and not a function diagnostics implementation.
+
+## Sui CLI Transaction Diagnostics Notes
+
+The Sui CLI diagnostics utility can inspect a digest with allowlisted read/debug commands:
+
+- `tx-block`;
+- optional object inspection;
+- optional local replay traces;
+- optional gas profiles.
+
+Run `npm exec -- tsx scripts/sui-cli-transaction-diagnostics.ts -- --help` for the full flag list.
+
+Common flags include:
+
+- `--object <objectId>`;
+- `--gas-profile`;
+- `--read-timeout-ms <ms>`;
+- `--replay-timeout-ms <ms>`;
+- `--analyze-timeout-ms <ms>`.
+
+`--mainnet` selects exactly one existing Sui CLI env alias whose recorded chain id matches mainnet.
+
+`--client-env` can select an explicit existing alias.
+
+Both modes are read-only and do not switch or mutate CLI config.
+
+CLI env aliases must not contain redaction marker word forms for private key, mnemonic, signature, signed transaction, transaction bytes, or `suiprivkey`-style markers using `-`, `_`, a space, or no separator.
+
+Artifact paths must not contain `suiprivkey`-style markers; other redaction markers in paths are accepted and redacted in output.
+
+The utility records source-versioned summaries, bounded redacted CLI-derived strings, artifact paths, and limitation provenance. It does not record raw CLI payloads.
+
+It reports a limitation when the installed CLI version differs from the source-checked parser baseline.
+
+It is not an MCP tool, not a CI check, not packaged product functionality, not review-time simulation, not wallet authorization, not signing readiness, not onchain transaction submission/execution, not route analysis, not P&L, and not complete-history evidence.
+
+## Rules
+
+- Utility output should be JSON-first.
+- Read-only utilities come before write/signable actions.
+- Generated registry files are local policy/metadata, not live liquidity or execution truth.
+- DeepBook token lists are pinned SDK registry metadata, not live token discovery or a complete Sui token list.
+- Live read outputs include `fetchedAt` as ISO 8601 UTC.
+- DeepBook mid-price outputs are pool snapshots. For `SUI_USDC`, the price is USDC per SUI.
+- DeepBook mid prices are not fiat USD cash-out estimates, external market lookups, USDC/USD peg assumptions, effective quote prices, quote-vs-mid slippage, price-impact calculations, venue comparisons, best-route claims, P&L, cost basis, or route recommendations.
+- `read.quote_deepbook_action` amounts are raw integer quantities that fit the SDK `u64` quote input, not decimal display amounts. Quote responses include `rawQuote.kind: "deepbook_quote_raw_u64"` from simulated raw `u64` return values.
+- `rawQuote.sourceMoveFunction` names the simulated public entrypoint. `rawQuote.returnValueSourceMoveFunction: "pool::get_quantity_out"` names the official Move function that defines the return-value order.
+- `read.quote_deepbook_display_amount` accepts only source-side display input amounts that convert to SDK `u64` quote inputs.
+- Display quote public `quote` fields are exact decimal display strings derived from raw evidence. `rawQuote.directionalOutput.raw` is the direction-specific quote output before slippage policy.
+- Quote `quantitySemantics` marks payment coverage, shortfall contribution, and route-dependent payment support unavailable and points coverage questions back to intent evidence.
+- DeepBook account inventory quantities are display-like SDK `number` values and must not be used as raw amounts, funding sources, route liquidity, withdrawal readiness, transaction-building inputs, signing data, or signing readiness.
+- Wallet balance display amounts are presentation-only and must come from returned `display` fields. Do not infer token decimals from symbols.
+- Wallet balance reads are current coin-balance snapshots only. They are not transaction history, receipt proof for a specific digest, acquisition source, object provenance, P&L, cost basis, or signing data.
+- `uninspectedAssetClasses` entries are explicit classifier-uninspected boundaries.
+- They are not zero-balance claims, spendable asset facts, funding sources, route liquidity, payment readiness, portfolio completeness, transaction-building inputs, signing data, or signing readiness.
+- Intent evidence previews map natural-language USD-denominated targets to pinned SDK settlement asset groups and current wallet balance snapshots.
+- Use `userAnswerUse.answerFields` for intent evidence answers. Settlement-asset-only coverage, shortfall, or current-total answers use `responseSummary`; selected-target answers also use the selected-target fields listed in the response. Direct pool quote evidence is supported only when the same intent-evidence response lists `direct_pool_quote_evidence` in `responseEvidence.supportedResponseClaims` and `direct_pool_quote_evidence_for_user_selected_target` in `userAnswerUse.canAnswer`. Intent evidence previews do not choose settlement assets, quote best routes, evaluate gas reserve, execute payments, or create signing material.
+- DeepBook read outputs identify SDK simulation reads through `source.simulation`.
+- Review activity tools analyze local Say Ur Intent review evidence only. The optional `account` input is a read filter and does not change active account context.
+- Sui activity scan tools are user-requested bounded reads. They store only normalized facts tied to known local wallets.
+- Sui activity scans do not store raw provider payloads or non-known party account addresses. They do not claim complete wallet history, complete dApp history, P&L, signing readiness, transaction building, or route recommendations.
+- Activity `quantitySemantics` marks balance `amountRaw` and `*Raw` fields as raw integer facts requiring verified decimals or returned display amounts before display conversion.
+- Account effect rows include `accountBalanceChangeInferencePolicy` so truncated or unavailable requested-account evidence cannot be filled from transaction-level context, visible recipient patterns, or current wallet balances.
+- Gas display facts, when returned, use `@mysten/sui MIST_PER_SUI`.
+- Optional protocol activity labels are derived from normalized detail facts and are not a supported-protocol list or wallet position inventory.
+- Sent-function activity tools are sender-scoped only: they report transactions the selected account sent that called one full `package::module::function`, not recipient-only activity, affected-object history, or global function history.
+- `read.summarize_sui_activity_scan` and `read.summarize_sui_function_activity_scan` summarize live bounded scan results. `read.summarize_sui_account_activity` summarizes stored local SQLite facts only.
+- Sui GraphQL function filter probe output is source-shape evidence for function-filter diagnostics only.
+- Do not treat the probe as a supported function diagnostics surface, complete dApp history, route quality evidence, wallet position inventory, transaction-building input, signing data, or signing readiness.
+- Sui CLI transaction diagnostics can be compared with `read.inspect_sui_transaction` only at the fact category level.
+- Comparable categories include digest/status/checkpoint/timestamp, Move call targets, object ids/types, event type strings, raw gas summary, and optional replay/trace-derived debug artifacts.
+- Sui CLI transaction diagnostics are debug cross-check sources, not replacements for MCP normalized transaction facts and not review-time simulation.
+- Sui CLI transaction diagnostics are source-checkout debug utilities only. They must stay allowlisted and read/debug-only.
+- Local replay output is debug evidence only. The utility is not an MCP tool, review-time simulation, wallet authorization, signing readiness, or onchain transaction submission/execution.
+- When a review activity output has `lowSampleWarning: true`, report raw counts and avoid inferring behavior patterns.
+- For review activity list output, `dataScope.recordCount` is the full matching local review count. The returned `activities` array can be shorter when `truncated.activities: true`.
+- Local settings page actions mutate local settings or logical local data only. They do not execute transactions, sign, or create custody. MCP settings tools create a settings page session or read current settings.

package/docs/WALLET_IDENTITY.md

@@ -0,0 +1,194 @@
+# Wallet Identity
+
+This document is the wallet identity capture specification for Say Ur Intent. It is product-facing design guidance and must not be treated as transaction authorization.
+
+This document owns the wallet identity boundary: what active-account read context is, how same-machine capture works, which state transitions exist, and what wallet identity is not.
+
+It does not own general setup steps, MCP tool contracts, or user-question playbooks. Product users should follow the README and `docs/MCP_SETUP.md`. MCP response fields are documented in `docs/MCP_TOOLS.md`.
+
+This document is for agents, frontend contributors, backend contributors, and reviewers who implement or verify wallet identity capture.
+
+Frontend display and action policy is defined in `docs/FRONTEND_POLICY.md`.
+
+## Purpose
+
+Wallet identity capture provides one account source for wallet-account reads and account-bound review.
+
+MCP clients create and poll a local capture session.
+
+The local review server serves the wallet page and validates Host, Origin, and the fragment token.
+
+The browser frontend connects a Sui wallet and sends only the selected account address and mainnet chain identifier back to the local server.
+
+The session store owns all state transitions.
+
+Wallet identity capture is not transaction review, wallet creation, login, signing authorization, custody, or persistent permission.
+
+It does not request authorization, does not construct executable transaction material, and does not imply that an action is safe.
+
+A capture session ends when the user closes the wallet page or it expires.
+
+The captured address remains as a read context until the user clears it.
+
+The `walletUrl` field is the wallet URL returned by the MCP tool.
+
+It must be opened in the same machine's system browser because the review server is bound to loopback.
+
+MCP client sidebars and embedded webviews are not supported wallet identity surfaces.
+
+The URL includes a short-lived fragment token; do not copy, sync, share, or move it to another device.
+
+## Active Account Persistence
+
+The active account is persisted in the local SQLite store and survives server
+restarts. It remains the read-context account until the user clears it through
+`account.clear_active_account` or the settings page. A connected identity
+result also records which wallet held the account (wallet name and wallet
+standard id). Wallet connection happens only on the connection page; the
+review page reads the recorded account from the server as its single source of
+truth, shows it in the header, and never connects a wallet itself. For the
+signing step it relies on dapp-kit autoconnect restoring the signer on the
+same fixed-port origin where the wallet was connected. That review origin is a
+single per-machine port (default 8765, overridable per registration with
+SAY_UR_INTENT_REVIEW_PORT): when a newer server instance finds the port already
+held by a previous Say Ur Intent review server, it stops that previous instance
+and takes the port over so the most recently started client owns the one
+origin, and a port held by any other process is never taken over. The record is
+read context and wallet preference only; it is not signing authorization.
+
+## Status Model
+
+Product statuses are:
+
+```ts
+pending | opened | connecting | connected | rejected | failed | expired
+```
+
+`pending`, `opened`, and `connecting` are non-terminal.
+
+`connected`, `rejected`, `failed`, and `expired` are terminal.
+
+Terminal sessions are immutable. Replacing or clearing the active account context does not rewrite earlier wallet identity sessions.
+
+The pinned `@mysten/dapp-kit-core` frontend connection store has `disconnected`, `connecting`, `reconnecting`, and `connected`.
+
+Those raw statuses are frontend internals and must be mapped into the product status model.
+
+`reconnecting` occurs when dapp-kit autoconnect restores a previously selected wallet on the same fixed-port origin; the frontend maps it to the `connecting` product status while the signer settles. dapp-kit storage holds the wallet autoconnect preference only, never keys.
+
+## Failure Reasons
+
+Wallet identity failure reasons are:
+
+```ts
+user_rejected
+no_compatible_wallet
+no_accounts_authorized
+unsupported_chain
+wallet_provider_error
+```
+
+`user_rejected` is used only when the wallet error is positively identified as a Wallet Standard user rejection.
+
+`no_compatible_wallet`, `no_accounts_authorized`, and `unsupported_chain` are used only when deterministically observed.
+
+All other wallet provider failures use `wallet_provider_error` with an optional sanitized `failureDetail`.
+
+## State Contracts
+
+`connected` requires `account` and `chain: "sui:mainnet"`. `rejected` requires `failureReason: "user_rejected"`. `failed` requires a non-user failure reason. `pending`, `opened`, and `connecting` must not include an account. `expired` is terminal and does not contain an account.
+
+Active-account reads require active account context when no explicit public account is supplied.
+
+`read.preview_intent_evidence` can use either an explicit public Sui address supplied as `account` or the active account when `account` is omitted.
+
+`read.summarize_deepbook_account_inventory` uses active account context.
+
+`read.summarize_wallet_assets` and `read.classify_wallet_assets` can read either an explicit public Sui address supplied as `account` or the active account when `account` is omitted.
+
+Explicit-address coin balance and intent-evidence reads do not prove ownership, store the address as a known wallet, or create active account context.
+
+Sender-independent DeepBook orderbook, raw-quantity quote, display-amount quote, and settlement-asset-group reads stay wallet-free.
+
+The pinned SDK requires a transaction simulation sender for some market reads, but Say Ur Intent supplies an internal mainnet placeholder when the result does not depend on a user's wallet.
+
+After a wallet identity connection succeeds, Say Ur Intent stores that normalized account as the active read context in the local SQLite database.
+
+This is unconditional. There is no opt-out short of clearing it through `account.clear_active_account`.
+
+The active account can be reused for wallet-account reads until the user clears or replaces it.
+
+This is not login, signing authorization, custody, or permission for transactions.
+
+Use `account.get_active_account` when the current active account context matters. A historical wallet identity session can remain `connected` even after the active account is cleared or replaced by another session.
+
+Account-bound review sessions must bind to the active wallet identity account before review state is accepted.
+
+A review account that does not match the active account context is rejected.
+
+Once the signable adapter's review evidence completes, the account-bound review reaches `ready_for_wallet_review` and the local review page offers a digest-gated handoff and user-controlled wallet signing.
+
+The active account context stays read context and wallet preference only; it is not signing authorization, and the MCP layer does not sign, execute, or return transaction bytes on its own.
+
+## Frontend Boundary
+
+The wallet frontend uses pinned dapp-kit core APIs and renders a minimal wallet list in the local review app.
+
+The pinned `@mysten/dapp-kit-core/web` package version is recorded in `docs/SDK_API.md` and pinned in `package.json`.
+
+Its button and modal do not expose wallet provider errors as public events. The frontend calls `connectWallet()` directly to classify deterministic wallet outcomes without inspecting private DOM state or overfitting error strings.
+
+The wallet page must say address capture only. It must not show transaction review language, authorization buttons, private-key handling, executable transaction material, or safety guarantees.
+
+## HTTP Boundary
+
+The wallet identity capture UI is hosted on the analysis page served at
+`/analysis/:id`. After a wallet connects, the same page can show a wallet asset
+snapshot and stored local review records through token-gated read endpoints
+(`GET /api/analysis/:id/assets`, `GET /api/analysis/:id/review-activity`).
+State-changing wallet APIs are unchanged:
+
+- `POST /api/wallet/:id/opened`
+- `POST /api/wallet/:id/connecting`
+- `POST /api/wallet/:id/result`
+
+All state-changing endpoints require Host and Origin validation plus the wallet session token. The token is supplied with `x-say-ur-intent-token`; query-string tokens are not accepted.
+
+## MCP Boundary
+
+MCP exposes:
+
+- `session.create_wallet_identity`
+- `session.get_wallet_identity`
+- `session.wait_wallet_identity`
+- `session.get_interaction_status`
+
+These tools create, poll, wait on, and summarize local wallet identity interactions. They do not expose private keys, executable transaction material, or arbitrary wallet operations.
+
+`session.create_wallet_identity` returns `openTarget: "system_browser"` and `accessScope: "same_machine_loopback"`.
+
+These fields let clients distinguish the wallet URL opening target from the session status.
+
+`accessScope` combines the same-machine requirement with the loopback-bound review server.
+
+`session.get_wallet_identity` returns the wallet identity session status only.
+
+`session.wait_wallet_identity` is a bounded wait over the same in-memory session state. `timed_out` means the user has not finished yet.
+
+After an AI client gives the wallet URL to the user, it should immediately call `session.wait_wallet_identity` in the same turn or poll `session.get_wallet_identity`.
+
+It should not wait for the user to return and say they connected before checking the session.
+
+AI clients should then call `account.get_active_account` before telling the user which address is currently active.
+
+Pending wallet identity sessions are process-local. If the local MCP server restarts, pending wallet identity sessions are not recovered. The durable state is the active account context stored after a successful connection.
+
+## Testing Boundary
+
+Server-path smoke tests may create a wallet identity session, post a public smoke address to the result endpoint, and then call wallet-account read tools.
+
+That verifies server routing and read-tool integration only.
+
+Browser wallet verification is a separate manual release checklist and is the only check that verifies a real wallet popup.
+
+Local event logs must not write captured wallet addresses in plaintext. NDJSON event logs hash wallet addresses before writing them.

package/docs/golden-scenarios/BEHAVIOR_MATRIX.md

@@ -0,0 +1,169 @@
+# Behavior Golden Scenarios
+
+These scenarios document expected response classes for manual release review. They are not Claude, Codex, or Cursor execution results.
+
+For current-release intent evidence checks that compare user prompts, preferred tool paths, standard answer clauses, and manual client observations, see `docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md`.
+
+For the deterministic MCP replay contract behind Korean USD-denominated coverage, total, and shortfall questions, see `docs/golden-scenarios/INTENT_EVIDENCE_GOLDEN_ANSWERS.md`.
+
+Manual client runs should call `read.get_server_status` first and record the package version, `evidencePolicy.version`, and `implementedToolsCount` before running the question rows.
+
+## Current Release Intent Evidence Corpus
+
+These scenarios translate the internal intent corpus into English release-review prompts.
+
+Current-release intent evidence answers can answer evidence questions without creating route recommendations, payment support, portfolio plans, P&L, transaction material, or signing readiness. Account-bound DeepBook review has a separate local transaction-material build path that is not part of these intent evidence answer rows.
+
+Partial wallet context is allowed only when an active account is already set or the user provides an explicit Sui address.
+
+`What is 10 SUI worth?`
+Class: `answer_only`.
+Use `read.get_deepbook_mid_price` with a disclosed DeepBook SUI quote pool such as `SUI_USDC`.
+Use `read.list_deepbook_pools` only when the pool is ambiguous.
+Expose DeepBook pool, mid price, quote asset, and `fetchedAt`.
+Do not present this as a global market price, route recommendation, settlement choice, or signing readiness.
+
+`If I sell 10 SUI, how many dollars do I get?`
+Class: `clarify_or_intent_evidence`.
+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`.
+Expose source input, missing quote-token or pool choice, fiat cash-out boundary, and available intent-evidence path when account context exists.
+Do not silently choose USDC or USDT, infer inverse output-target quotes, use web/finance lookup for USDC/USD, assume the USDC/USD peg, or present fiat cash-out, final min-out, route quality, funding readiness, or signing readiness.
+
+`What can I sell?`
+Class: `wallet_asset_read`.
+Use active account context or explicit address, then call `read.classify_wallet_assets`.
+Expose returned spendable coin-balance classes, gas asset context, DeepBook token registry matches, and `uninspectedAssetClasses`.
+Do not treat staked, locked, DeepBook manager, LP, vault, NFT, object, unsupported, or unknown classes as zero balances or sellable candidates.
+
+`Sell DEEP for USDC.`
+Class: `clarify_or_quote_context`.
+Ask for a source amount before quoting.
+After source amount and pool are explicit, call `read.quote_deepbook_display_amount`.
+Use `read.classify_wallet_assets` only for scoped wallet context.
+Do not assume amount, choose a route, run inverse quotes, create a review session, or treat DeepBook manager inventory as spendable.
+
+`Make $1000.`
+Class: `intent_evidence_with_choices`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` when active account or explicit address context is available.
+Ask only for choices returned by `responseSummary`.
+Do not silently choose USDC or USDT, treat USDC as fiat USD, choose source assets, rank routes, or prepare signing.
+
+`Can I cover a 1000 dollar payment?`
+Class: `intent_evidence_with_choices`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "cover_payment_like_amount"`, `denomination: "dollar"`, and `requiredDisplayAmount: "1000"`.
+Expose `responseSummary`, settlement-asset coverage basis, settlement-asset shortfall when available, required user choices, and unsupported payment/signing boundaries.
+Do not silently choose USDC or USDT, claim fiat USD cash-out, route-dependent payment support, gas readiness, transaction building, or signing readiness.
+
+`Can I pay for this $1000 item?`
+Use the same `intent_evidence_with_choices` path as `Can I cover a 1000 dollar payment?`.
+Do not claim fiat USD cash-out, route-dependent payment support, gas completeness, transaction building, or signing readiness.
+
+`How much are my USD-denominated assets together?`
+Class: `intent_evidence_total_only`.
+Use `read.list_settlement_asset_groups`, then `read.preview_intent_evidence` with `intentKind: "summarize_settlement_asset_group_balance"` and `denomination: "dollar"`.
+Expose `responseSummary.conclusionKind: "current_settlement_asset_total"` and current display total when available.
+Do not invent a target amount, silently choose USDC or USDT, treat the total as fiat USD cash-out, recommend a route, claim payment readiness, produce transaction material, or imply signing readiness.
+
+`Which stablecoin-like asset is highest or lowest?`
+Class: `settlement_asset_group_parity`.
+Use `read.list_settlement_asset_groups`, then `read.summarize_settlement_asset_group_parity` with `denomination: "dollar"`.
+Expose `responseSummary.referenceAssetRole`, min/max/mean/median statistics, and unsupported boundaries.
+Do not treat the reference asset as settlement selection, fiat USD value, peg assumption, payment readiness, route recommendation, transaction material, or signing readiness.
+
+`What is the shortfall?`
+Class: `intent_evidence_with_context_or_clarify`.
+If a target amount was already established, use `read.preview_intent_evidence` with that amount and answer from `responseSummary`.
+If not, ask for the missing target amount.
+Do not guess the missing amount, silently choose a settlement token, choose source assets, rank routes, claim gas readiness, prepare signing, or produce transaction material.
+
+`Make it 100 SUI.`
+Class: `blocked_with_context`.
+Use `read.classify_wallet_assets` only for current coin context when active account or explicit address is available.
+Do not create a portfolio target, rebalance plan, source selection, route recommendation, or review session.
+
+`Keep 100 SUI and convert the rest.`
+Class: `blocked_with_context`.
+Use `read.classify_wallet_assets` only for current coin context when active account or explicit address is available.
+Do not infer gas reserve, sell source, route, reserve policy, transaction material, or signing readiness.
+
+`If USDC is short, sell another token to fill it.`
+Class: `intent_evidence_with_choices`.
+Use `read.preview_intent_evidence` with `targetAssetSymbol: "USDC"` and `targetAssetSelectionSource: "user_explicit"` when active account or explicit address context is available.
+Expose selected target shortfall, `selectedTarget.selectionSource`, settlement-asset candidate conversion evidence or quote-unavailable reasons, and required user choices.
+Do not set target provenance for an AI-inferred target. Do not auto-pick assets to sell, rank routes, merge non-group quote proceeds into coverage, treat uninspected assets as funding sources, or prepare signing.
+
+## General Behavior Scenarios
+
+`What is 1 SUI worth?`
+Class: `answer_only`.
+Call `read.get_deepbook_mid_price` with `poolKey: "SUI_USDC"` for Say Ur Intent verified context.
+Answer as DeepBook SUI/USDC mid price at `fetchedAt`, not as the global market price.
+Do not use external web data unless the user explicitly asks for non-product market context.
+Do not ask for a wallet or push a review session.
+
+`If I sell 10 SUI, how many dollars do I get?`
+Class: `clarify_or_intent_evidence`.
+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.
+If the user chooses SUI/USDC, answer as a DeepBook SUI/USDC quote at `fetchedAt`.
+Do not convert USDC to fiat USD cash-out, assume the USDC/USD peg, or use web/finance lookup unless the user explicitly asks for outside product market context.
+Do not present it as a global USD price, route recommendation, price-impact calculation, final min-out, funding readiness, or signing readiness.
+
+`How much do I have?`
+Class: `clarify`.
+Explain that active account context is needed before wallet assets can be read.
+If none is set, ask for wallet identity connection.
+Do not ask for manual address entry.
+
+`Connect my wallet.`
+Class: `tool_wait`.
+Call `session.create_wallet_identity`, give the user the `walletUrl`, then immediately call `session.wait_wallet_identity` in the same turn or poll `session.get_wallet_identity`.
+On `connected`, call `account.get_active_account` before announcing the active account.
+On `timed_out`, say the wallet connection is still pending, not failed.
+
+`I want to buy $10 worth of SUI.`
+Class: `present_options`.
+Do not claim a supported buy flow or provide investment advice.
+Explain that dollar-denominated intent needs a supported stablecoin and amount unit.
+Offer read-only DeepBook quote options and disclose that signing remains blocked.
+
+`Sell a little.`
+Class: `clarify`.
+Ask for a concrete amount and provide examples.
+Do not map vague quantity words to a fixed percent.
+
+`Sell half.`
+Class: `clarify`.
+Explain that balance is needed before calculating half.
+Use active account context if set; otherwise ask the user to connect wallet identity before wallet-account calculation.
+
+`5`
+Class: `clarify`.
+Ask which unit the user means: SUI, another asset, or a USD-denominated amount.
+If they mean dollars or stablecoins, use settlement-asset-group evidence before asking for a specific token.
+
+`Keep it from getting expensive.`
+Class: `clarify`.
+Ask for a price/slippage limit or explain the default only when a supported action flow applies.
+
+`Is this transaction safe?`
+Class: `redirect_unsupported`.
+Do not guarantee safety.
+Summarize concrete review facts or say a review is blocked/unavailable.
+
+`Tell me when the price drops.`
+Class: `redirect_unsupported`.
+Say alerts are unsupported and offer a one-time read.
+
+`Let's buy Bitcoin too.`
+Class: `redirect_unsupported`.
+Say only Sui mainnet surfaces are exposed.
+
+`What happened to the thing from before?`
+Class: `clarify`.
+Ask for the `reviewSessionId` unless a recent-session feature exists.
+
+## Manual Client Results
+
+No client observations are recorded in this matrix. Release checks can record Claude, Codex, or Cursor observations in an ignored local result file and promote durable failures to `docs/golden-scenarios/INTENT_EVIDENCE_MATRIX.md`, product docs, tests, or code.