@stelis/say-ur-intent 0.0.7 → 0.1.0

package/README.md

@@ -1,14 +1,27 @@
 # Say Ur Intent
 
-Say Ur Intent is a local-first, evidence-first Sui intent toolkit for AI clients.
+Say Ur Intent is a local-first Sui review and evidence layer for AI clients.
 
-For natural-language Sui DeFi questions, the current release returns verified,
-AI-readable evidence before transaction creation. That answer path remains
-separate from account-bound DeepBook review, where the review server builds
+It turns a supported AI-requested Sui action into a local review page where the
+user reads the transaction summary, inspects the transaction (PTB) as a graph,
+and signs in their own wallet. The AI client never receives signing authority or
+executable transaction bytes.
+
+![Say Ur Intent local review page](https://raw.githubusercontent.com/stelis-dev/say-ur-intent/main/assets/review-page.png)
+
+*The local review page: deterministic review checks, review-time simulation
+evidence, and the transaction shown as a labeled PTB graph — what the user
+reviews before signing in their own wallet.*
+
+For natural-language Sui DeFi questions, the current release also returns
+verified, AI-readable evidence before any transaction is built. That answer path
+stays separate from account-bound swap review, where the review server builds
 local unsigned transaction material internally and, once every review evidence
-stage completes, the local review page offers a digest-gated handoff,
-user-controlled wallet signing, and execution-receipt recording. The MCP layer
-and review API never sign, execute, or return transaction bytes.
+stage completes, the local review page offers a digest-gated byte handoff,
+user-controlled wallet signing, and execution-receipt recording. MCP responses
+never sign, execute, or return transaction bytes; the only transaction-byte path
+is the same-machine, digest-gated wallet handoff initiated from the local review
+page.
 
 Users can ask ordinary questions:
 
@@ -36,17 +49,19 @@ Say Ur Intent is one product, but it must be read at three distinct layers. Do n
 
 In one sentence: Say Ur Intent is a local-first Sui intent evidence and review layer that progresses from verified evidence to user-controlled wallet signing only after Say Ur Intent independently builds or verifies the transaction material and shows a human-readable local review.
 
-DeepBook is the current Sui source for liquidity and price facts in this release.
-Wallet and Sui balance reads describe held assets. DeepBook provides scoped
-conversion and price evidence. DeepBook does not define the whole product.
+DeepBook and FlowX are the current Sui liquidity and price sources in this
+release: DeepBook provides scoped conversion, price, and orderbook evidence, and
+FlowX provides indicative CLMM route quotes. Wallet and Sui balance reads
+describe held assets. They do not define the whole product.
 
 Say Ur Intent does not custody funds, hold private keys, or autonomously trade
 on behalf of users.
 By current design, it does not rank venues, choose routes, make best-price
 recommendations, or silently choose settlement tokens for users.
 
-The current release can build local unsigned transaction material only inside the
-account-bound DeepBook swap review path. It does not expose transaction bytes.
+The current release can build local unsigned transaction material inside the
+account-bound DeepBook and FlowX swap review paths. It does not expose
+transaction bytes.
 Wallet signing is user-controlled on the local review page after a
 digest-gated handoff; MCP responses never request signatures, provide signing
 readiness, or execute payments.
@@ -64,8 +79,8 @@ The current release flow is:
 The user states an intent in natural language.
 Say Ur Intent resolves the supported Sui mainnet evidence surface.
 The AI answers only from returned evidence and boundaries.
-DeepBook transaction material build is an account-bound review step, not part of
-the natural-language intent evidence answer.
+Supported swap transaction material build is an account-bound review step, not
+part of the natural-language intent evidence answer.
 ```
 
 The current release implements intent evidence for supported Sui mainnet reads.
@@ -73,17 +88,6 @@ It can also create a read-only, non-signable local review session from a
 structured external payment or Sui action proposal. External proposal ingestion
 does not trust external transaction material or send anything for wallet signing.
 
-Key terms used below:
-
-- Sui: the mainnet blockchain whose DeFi state this project reads.
-- MCP: Model Context Protocol, the tool-calling interface used by AI clients.
-- DeepBook: Sui's onchain order book protocol.
-- SDK: Software Development Kit, a version-pinned library dependency used by this repository.
-- gRPC and GraphQL: Sui SDK transports used by this runtime for mainnet reads.
-- dApp Kit: Sui's wallet connection library for web apps.
-- stdio: standard input/output, the local transport used by MCP clients to talk to this server.
-- Stelis: the GitHub and npm namespace for this package. Say Ur Intent is the product and runtime name.
-
 For setup, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
 For the MCP API reference, see [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
 For the AI-client answer playbook, see [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md).
@@ -104,7 +108,7 @@ The current release can run as a local stdio MCP server and expose mainnet Sui D
 - user-requested bounded Sui transaction digest lookup, account activity scans, sent-function activity scans with known-wallet-only persistence, and stored normalized activity summaries;
 - read-only external proposal review sessions that display proposed action, asset flow, recipient or target, freshness, missing evidence, user choices, unsupported claims, and non-signable reason;
 - local Say Ur Intent review evidence and review-session status reads;
-- account-bound DeepBook and FlowX swap review progress through local unsigned transaction material build, internal Sui transaction digest binding, object ownership evidence, quote/policy provenance binding, human-readable review facts, and review-time simulation evidence; when every stage completes the review reaches `ready_for_wallet_review` and the local review page offers a digest-gated byte handoff, user-controlled wallet signing, and execution-receipt recording. The MCP layer and review API never sign, execute, or return transaction bytes.
+- account-bound DeepBook and FlowX swap review progress through local unsigned transaction material build, internal Sui transaction digest binding, object ownership evidence, quote/policy provenance binding, human-readable review facts, and review-time simulation evidence; when every stage completes the review reaches `ready_for_wallet_review` and the local review page offers a digest-gated byte handoff, user-controlled wallet signing, and execution-receipt recording. MCP responses never sign, execute, or return transaction bytes; transaction bytes flow only through the same-machine, digest-gated wallet handoff initiated from the local review page.
 
 It also includes:
 
@@ -131,7 +135,7 @@ payloads before storage, and records why the review is non-signable.
 
 Blocked signing is session-scoped: a review session stays blocked while
 required review evidence is missing for that session (for example
-`wallet_review_contract_emit_missing`). When account-bound DeepBook swap
+`wallet_review_contract_emit_missing`). When an account-bound supported swap
 review completes local transaction material, digest binding, object ownership,
 quote/policy provenance, human-readable review evidence, and review-time
 simulation evidence, the review layer emits a schema-validated
@@ -148,11 +152,11 @@ The signable adapter and PTB visualization boundary is documented in
 `WalletReviewAdapterContract` as pre-signing review evidence when every
 required evidence stage is complete; the contract carries the transaction
 commitment hash only.
-The runtime path does not make wallet signing available.
-It does not make wallet handoff available.
-It does not make payment execution available.
-It does not make executable transaction material available.
-It does not make signing readiness available.
+
+Wallet signing and the digest-gated byte handoff happen only on the local
+review page through the user's own wallet, never through MCP responses. MCP
+responses do not return executable transaction material or signing data, and
+do not provide signing readiness.
 
 Fiat cash-out, P&L, tax, and cost-basis support are not part of the current release.
 
@@ -200,38 +204,9 @@ For quote responses alone, these conclusions are unsupported:
 - cost basis is not available;
 - actionable signing data is not available.
 
-## Developer Checkout Quickstart
-
-This package targets Node.js 22+. Node 22 or 24 LTS is recommended.
-
-Use this path when you download the repository from GitHub and want to test the local build in an MCP client:
-
-```bash
-git clone https://github.com/stelis-dev/say-ur-intent.git
-cd say-ur-intent
-npm install
-npm run build
-```
-
-No Sui endpoint setup is required for the default path. For MCP stdio configuration from a local checkout, point the client at the built runtime:
-
-```json
-{
-  "command": "node",
-  "args": ["/absolute/path/to/say-ur-intent/dist/runtime/start.js"]
-}
-```
-
-Do not wrap the stdio server in a shell command that writes ordinary text to stdout. Stdout is reserved for MCP JSON-RPC messages; logs go to stderr.
-
-Client-specific setup for Claude Code, Claude Desktop, Codex, and Cursor lives in [docs/MCP_SETUP.md](docs/MCP_SETUP.md). That file is the canonical setup guide; this README keeps only the short path.
+## Install
 
-To delegate local setup to an AI coding agent, tell it:
-
-```text
-Register this repository as a local stdio MCP server using the built /absolute/path/to/say-ur-intent/dist/runtime/start.js file.
-Use the default Sui mainnet endpoint unless I explicitly ask for a custom provider.
-```
+Install from the MCP registry (server `io.github.stelis-dev/say-ur-intent`) or with `npx -y @stelis/say-ur-intent`. For per-client configuration (Claude Code, Claude Desktop, Codex, Cursor) and running from a local checkout, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md).
 
 After the MCP server is connected, use [docs/MCP_SETUP.md](docs/MCP_SETUP.md#first-use-flow) for first-use setup, [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md) for API fields and statuses, and [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md) for user-question flow and response wording.
 
@@ -241,20 +216,6 @@ Product docs, registry, AI responses, UX copy, and signable actions are mainnet-
 
 Unsupported protocol experiments are not product functionality and are not included in the package docs, MCP resources, registry support lists, UX copy, or signable-action lists.
 
-## Commands
-
-```bash
-npm install
-npm run typecheck
-npm run build
-npm test
-npm run release:check
-npm run generate:deepbook-registry
-npm run smoke:mainnet
-```
-
-`npm run generate:deepbook-registry` writes `registry/generated/deepbook-mainnet.json`, which is ignored by Git because generated registry data must include provenance and should be regenerated from the pinned SDK.
-
 ## MCP Tools
 
 The canonical MCP API reference lives in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
@@ -299,105 +260,30 @@ AI client answer behavior must be mirrored in runtime-facing instructions, resou
 - `docs/LOCAL_DB_ARCHITECTURE.md`: local SQLite storage boundaries for maintainers.
 - `docs/SDK_API.md`: pinned SDK API notes and source-verification boundaries.
 - `docs/FRONTEND_POLICY.md`: review-app frontend implementation policy for coding agents.
-- `docs/SIGNABLE_ADAPTER_CONTRACT.md`: wallet-review adapter and PTB visualization contract. The review layer emits the contract and a PTB visualization as pre-signing review evidence; not signing support.
+- `docs/SIGNABLE_ADAPTER_CONTRACT.md`: wallet-review adapter and PTB visualization contract. It defines the pre-signing review evidence and commitment boundary; wallet signing still happens only through the local review page, not through MCP.
 - `AGENTS.md`: root repository development contract and non-negotiable product boundaries for coding agents working on this codebase.
 - `docs/AGENT_DEVELOPMENT_POLICY.md`: detailed binding development, review, documentation, source-of-truth, and completion policies for coding agents.
 
 ## Contract Name Registry
 
-The PTB visualization on the review page can show a registered Move Registry
-(MVR) package name in place of a raw package address (for example
-`@deepbook/core`), with a toggle back to the raw address and a copyable Mermaid
-source that keeps raw addresses. The name is a package identity label only, not a
-safety, trust, route-quality, or signing-readiness signal.
+The PTB visualization on the review page can show human-readable labels in place
+of raw addresses, with a toggle back to raw addresses and a copyable Mermaid
+source that always keeps raw addresses. A label is identity display only, not a
+safety, trust, route-quality, or signing-readiness signal, and only registered
+addresses are relabeled.
 
-If you maintain a Sui DeFi protocol that has a registered MVR name and want its
-package to display that name in the review graph, open a pull request adding your
-mainnet package address and MVR name to
-[`src/core/action/contractNameRegistry.ts`](src/core/action/contractNameRegistry.ts).
-Only packages listed in this registry are relabeled; every other package keeps
-its raw address.
-
-## For Maintainers
-
-This section is for people operating releases, running smoke checks, changing runtime storage, or debugging startup. Normal users and MCP client users can stop at the documentation map above.
+Two pinned, context-aware registries in
+[`src/core/action/contractNameRegistry.ts`](src/core/action/contractNameRegistry.ts)
+drive this:
 
-### Mainnet Read Smoke
-
-Normal quickstart use does not require Sui endpoint setup. The smoke script is a manual maintainer check for a specific mainnet provider:
-
-```bash
-export SUI_GRPC_URL="https://fullnode.mainnet.sui.io:443"
-export SUI_GRAPHQL_URL="https://graphql.mainnet.sui.io/graphql" # optional override; default is the built-in mainnet GraphQL endpoint
-export SMOKE_SUI_ADDRESS="0x..."
-export SMOKE_DEEPBOOK_POOL_KEY="DEEP_SUI"
-export SMOKE_QUOTE_AMOUNT="1000000000" # raw integer units; for SUI, 1000000000 = 1 SUI
-# Optional: export SMOKE_INSPECT_DIGEST="..."
-# Optional: export SMOKE_INSPECT_RANDOM_LATEST="true"
-npm run build
-npm run smoke:mainnet
-```
+- packages, relabeled only in `<address>::` path position — the DeepBook swap
+  package by its Move Registry (MVR) name `@deepbook/core`, and the Sui framework
+  packages by their Move aliases (`std`, `sui`, `sui_system`);
+- well-known Sui system objects, relabeled only as a bare object id — `Clock`,
+  `SuiSystemState`, `Random`, `DenyList`, `CoinRegistry`, and the address-based
+  balance `AccumulatorRoot`.
 
-`SUI_GRPC_URL` must be only scheme, host, and explicit port. Do not include credentials, a path, query string, or fragment.
-`SMOKE_SUI_ADDRESS` must be a 32-byte hex Sui address, for example `0x` followed by 64 hex characters.
-`SMOKE_INSPECT_DIGEST` is optional. Use a digest whose sender or returned balance-change owner is `SMOKE_SUI_ADDRESS` to exercise the stored digest-lookup path; otherwise the lookup can still return `ok` with `persistence.stored: false`.
-`SMOKE_INSPECT_RANDOM_LATEST=true` is optional and only used when `SMOKE_INSPECT_DIGEST` is unset.
-
-It samples one digest from the latest GraphQL transaction page and calls `read.inspect_sui_transaction` without passing the smoke address.
-
-This checks current transaction-read shape without pinning a specific user address or exercising the stored relation path.
-
-The smoke script currently calls:
-
-- wallet assets;
-- DeepBook orderbook;
-- raw-quantity 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.
-
-If `SMOKE_FUNCTION_TARGET` is set to a full `package::module::function`, it also calls `read.scan_sui_function_activity` and `read.summarize_sui_function_activity_scan` with limit 5.
-
-If unset, function activity smoke is recorded as not run with `notRunReason: "missing_env"`.
-
-Empty activity pages are valid smoke outcomes. They are recorded with `rowCount: 0` and `emptyAccepted: true`.
-
-If `SMOKE_INSPECT_DIGEST` is set, the script also calls `read.inspect_sui_transaction` for that digest and the smoke address.
-
-DeepBook orderbook and raw-quantity quote reads use an internal mainnet SDK simulation sender placeholder, not a user's wallet. The display-amount quote path is covered by automated tests, not by this smoke script. This smoke script does not exercise account-bound DeepBook transaction-material build or digest binding; that path needs a separate funded-account material-build smoke before smoke results are treated as product-grade proof for that review stage.
-
-Wallet asset summaries and active-account activity summaries use the smoke address through a wallet identity session created by the smoke script. Browser wallet behavior is checked separately.
-
-Smoke result files record activity status, row count, source, window/order flags, persistence, and evidence summary only. They do not record raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
-
-### Runtime Boundary
-
-The runtime starts these local components:
-
-- a local SQLite store;
-- a mainnet guard for the configured Sui gRPC endpoint;
-- the local review HTTP server on `127.0.0.1`;
-- the stdio MCP transport.
-
-The GraphQL endpoint is also mainnet-guarded when it is saved through settings, imported from a local-data backup, or first used by Sui activity tools.
-
-Stdout is reserved for MCP JSON-RPC messages. Logs go to stderr.
-
-### Local Data
-
-The runtime creates a local SQLite file for account read context and Say Ur Intent review activity evidence. Users do not install a database server separately.
-
-Override the app data directory only when needed:
-
-```bash
-export SAY_UR_INTENT_DATA_DIR="/path/to/local/app-data"
-```
-
-The stored active account is for reading wallet state only. It does not let the toolkit sign transactions on your behalf.
-
-User-requested bounded transaction scans can store normalized facts only when a transaction is related to a known local wallet. This product does not run a background or complete wallet history indexer.
-
-The default Sui mainnet gRPC and GraphQL endpoints are stored in the local SQLite settings table on first run.
-
-To inspect settings or change local data, ask your AI client to create a Say Ur Intent local settings session and open the returned settings URL in the same machine's system browser.
-
-Endpoint changes apply after the MCP server restarts.
+If you maintain a Sui DeFi protocol that has a registered MVR name and want its
+package to display that name in the review graph, open a pull request adding your
+mainnet package address and MVR name to the package registry. Every unregistered
+address keeps its raw form.

package/docs/AGENT_BEHAVIOR.md

@@ -10,7 +10,7 @@ It is not the contributor rulebook and it is not enforcement. Development rules
 
 | Surface | Status | Behavior |
 | --- | --- | --- |
-| Sui mainnet state reads | Current | Use read tools for supported balances, DeepBook pools, token registry metadata, mid-price snapshots, orderbook context, raw-quantity quotes, and DeepBook account inventory. |
+| Sui mainnet state reads | Current | Use read tools for supported balances, DeepBook pools, FlowX pools, token registry metadata, mid-price snapshots, orderbook context, raw-quantity quotes, and DeepBook account inventory. |
 | DeepBook and FlowX swap review sessions | Digest-gated handoff; user-controlled signing on the review page | A review URL can be created. The review URL displays the proposal and local review evidence. The account-bound review can build local unsigned DeepBook or FlowX swap transaction material inside the review server, internally bind a Sui transaction digest to that stored material, and derive object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts. This release does not provide a sign action, signing data, MCP-visible transaction bytes, or signing readiness. The local review page requests a digest-gated byte handoff for a `ready_for_wallet_review` state, then the user signs in their own wallet and the page records the execution receipt. |
 | External proposal review sessions | Non-signable review in the current release | `action.prepare_external_proposal_review` can create a review URL from a structured external payment or Sui action proposal. Treat the proposal as untrusted display and review context only. It does not build, verify, simulate, sign, or execute transaction material. |
 | Wallet signing | User-controlled on the local review page | MCP tools do not return signing readiness, signing data, or executable transaction bytes. Signing and execution happen only in the user's wallet from the local review page after the digest-gated handoff; results are recorded as execution receipts keyed by the review session. |
@@ -154,13 +154,13 @@ transaction material. Do not treat it as route selection. Do not treat it as
 settlement-token selection. Do not treat it as payment execution readiness. Do
 not treat it as signing data or signing readiness.
 
-After a DeepBook review session is wallet-account bound, `session.get_review_status` can include review-state checks, `reviewState.adapterLifecycle`, `reviewState.humanReadableReview`, and `reviewState.simulation`. The review page renders those fields as local review evidence.
+After a DeepBook or FlowX review session is wallet-account bound, `session.get_review_status` can include review-state checks, `reviewState.adapterLifecycle`, `reviewState.humanReadableReview`, and `reviewState.simulation`. The review page renders those fields as local review evidence.
 
-Use `reviewState.adapterLifecycle.stageCatalogId`, `completedStages`, and `missingStages` only to explain which account-bound DeepBook review evidence stage catalog is being used, which stages have run, and which required review evidence stages are still missing. If `transaction_material_build_or_verify` is completed, say only that the review server built local unsigned transaction material and kept bytes internal. If `digest_commitment` is completed, say only that the review server internally bound a Sui transaction digest to that stored local material. If `object_ownership` is completed, say only that the review server derived object ownership evidence from the stored local material and Sui owner/type reads. If `review_time_simulation` is completed, say only that the review server simulated the stored local unsigned material with checks enabled and exposed a redacted simulation summary. `reviewState.humanReadableReview` is valid only after `human_readable_review` is completed and not missing; `reviewState.simulation` is valid only after `review_time_simulation` is completed and not missing. Do not provide or infer transaction bytes, signing data, signing readiness, or execution readiness from those stages. This lifecycle stops at review-time simulation; the digest-gated byte handoff follows an emitted contract, while wallet signing and execution receipt happen on the local review page under the user's control. Use those checks to explain what the local review layer verified before signing. Do not describe them as wallet readiness, signing readiness, route quality, execution safety, or public transaction bytes. The MCP layer never signs, executes, or returns transaction bytes.
+Use `reviewState.adapterLifecycle.stageCatalogId`, `completedStages`, and `missingStages` only to explain which account-bound DeepBook or FlowX review evidence stage catalog is being used, which stages have run, and which required review evidence stages are still missing. If `transaction_material_build_or_verify` is completed, say only that the review server built local unsigned transaction material and kept bytes internal. If `digest_commitment` is completed, say only that the review server internally bound a Sui transaction digest to that stored local material. If `object_ownership` is completed, say only that the review server derived object ownership evidence from the stored local material and Sui owner/type reads. If `review_time_simulation` is completed, say only that the review server simulated the stored local unsigned material with checks enabled and exposed a redacted simulation summary. `reviewState.humanReadableReview` is valid only after `human_readable_review` is completed and not missing; `reviewState.simulation` is valid only after `review_time_simulation` is completed and not missing. Do not provide or infer transaction bytes, signing data, signing readiness, or execution readiness from those stages. This lifecycle stops at review-time simulation; the digest-gated byte handoff follows an emitted contract, while wallet signing and execution receipt happen on the local review page under the user's control. Use those checks to explain what the local review layer verified before signing. Do not describe them as wallet readiness, signing readiness, route quality, execution safety, or public transaction bytes. The MCP layer never signs, executes, or returns transaction bytes.
 
 Use `reviewState.humanReadableReview` only as displayable review facts projected
-from verified local review evidence. Its `kind` currently identifies the first
-swap review projection. Its `assetFlow` raw amounts, coin types, decimals,
+from verified local review evidence. Its `kind` currently identifies the shared
+DeepBook and FlowX swap review projection. Its `assetFlow` raw amounts, coin types, decimals,
 minimum output, fee facts, target pool, and direction are derived from the
 material-bound quote policy evidence, while object ownership is cited only as
 review evidence from stored transaction material and Sui owner/type reads.
@@ -185,9 +185,10 @@ review-time simulation to one transaction commitment hash. It is not
 transaction bytes, not signing data, not signing readiness, not wallet
 handoff, not execution readiness, and not a route recommendation. If the
 review is blocked on `wallet_review_contract_emit_missing`, say that contract
-assembly declined and use the failed
-`deepbook_wallet_review_contract_emit_missing` check message for the concrete
-reason.
+assembly declined and use the failed adapter-prefixed emit-missing check message
+for the concrete reason: `deepbook_wallet_review_contract_emit_missing` for a
+DeepBook review and `flowx_wallet_review_contract_emit_missing` for a FlowX
+review.
 
 If a response includes a `PtbVisualizationArtifact`, answer from its Mermaid
 text, diagnostics, `generatedAt`, `source`, and `unsupportedUse` fields only

package/docs/LOCAL_DB_ARCHITECTURE.md

@@ -4,6 +4,39 @@ Say Ur Intent uses a local SQLite database for durable product state that must s
 
 This document is for maintainers and contributors who change local state, import/export behavior, activity queries, or review evidence storage. Product users normally need only the README and `docs/MCP_SETUP.md`.
 
+## Runtime Boundary
+
+The runtime starts these local components:
+
+- a local SQLite store;
+- a mainnet guard for the configured Sui gRPC endpoint;
+- the local review HTTP server on `127.0.0.1`;
+- the stdio MCP transport.
+
+The GraphQL endpoint is also mainnet-guarded when it is saved through settings, imported from a local-data backup, or first used by Sui activity tools.
+
+Stdout is reserved for MCP JSON-RPC messages. Logs go to stderr.
+
+## Local Data
+
+The runtime creates a local SQLite file for account read context and Say Ur Intent review activity evidence. Users do not install a database server separately.
+
+Override the app data directory only when needed:
+
+```bash
+export SAY_UR_INTENT_DATA_DIR="/path/to/local/app-data"
+```
+
+The stored active account is for reading wallet state only. It does not let the toolkit sign transactions on your behalf.
+
+User-requested bounded transaction scans can store normalized facts only when a transaction is related to a known local wallet. This product does not run a background or complete wallet history indexer.
+
+The default Sui mainnet gRPC and GraphQL endpoints are stored in the local SQLite settings table on first run.
+
+To inspect settings or change local data, ask your AI client to create a Say Ur Intent local settings session and open the returned settings URL in the same machine's system browser.
+
+Endpoint changes apply after the MCP server restarts.
+
 ## Engine
 
 The runtime uses the `better-sqlite3` npm package for normal SQLite file semantics and incremental writes. Users do not install a separate database server.

package/docs/MCP_SETUP.md

@@ -8,6 +8,17 @@ The README keeps only the short entry path; client-specific setup, restart behav
 
 Say Ur Intent is tested from a local checkout in this repository state.
 
+## Key terms
+
+- Sui: the mainnet blockchain whose DeFi state this project reads.
+- MCP: Model Context Protocol, the tool-calling interface used by AI clients.
+- DeepBook: Sui's onchain order book protocol.
+- SDK: Software Development Kit, a version-pinned library dependency used by this repository.
+- gRPC and GraphQL: Sui SDK transports used by this runtime for mainnet reads.
+- dApp Kit: Sui's wallet connection library for web apps.
+- stdio: standard input/output, the local transport used by MCP clients to talk to this server.
+- Stelis: the GitHub and npm namespace for this package. Say Ur Intent is the product and runtime name.
+
 ## Requirements
 
 - Node.js 22+. Node 22 or 24 LTS is recommended.
@@ -64,9 +75,46 @@ On native Windows clients that need `cmd`, use the same command through `cmd /c`
 }
 ```
 
+To delegate local setup to an AI coding agent, tell it:
+
+```text
+Register this repository as a local stdio MCP server using the built /absolute/path/to/say-ur-intent/dist/runtime/start.js file.
+Use the default Sui mainnet endpoint unless I explicitly ask for a custom provider.
+```
+
+## Commands
+
+These `npm run` scripts run from a local checkout. They are developer and maintainer scripts, not MCP tools or packaged product commands:
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+npm run release:check
+npm run generate:deepbook-registry
+npm run smoke:mainnet
+```
+
+`npm run generate:deepbook-registry` writes `registry/generated/deepbook-mainnet.json`, which is ignored by Git because generated registry data must include provenance and should be regenerated from the pinned SDK.
+
+## Install from the MCP Registry
+
+If your MCP client can install servers from the
+[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=say-ur-intent),
+find the `io.github.stelis-dev/say-ur-intent` entry and install it through your
+client. The resulting stdio server command is equivalent to:
+
+```sh
+npx -y @stelis/say-ur-intent
+```
+
+Clients that do not install from the registry use the published-package and
+per-client configuration below, which give the exact `command` and `args`.
+
 ## Published Package Setup
 
-Once `@stelis/say-ur-intent` is on npm there are two ways to run it. Both start
+`@stelis/say-ur-intent` is on npm; there are two ways to run it. Both start
 the same `say-ur-intent` stdio MCP server; pick based on whether you want
 automatic updates or the fastest, most reliable startup.
 
@@ -542,7 +590,13 @@ If the user supplied a specific Sui address for `read.summarize_wallet_assets` o
 
 ### NPM command returns 404
 
-The package is not published yet in this repository state. Use Developer Checkout Setup or `npm run release:check` for packed-package testing until publication.
+`@stelis/say-ur-intent` is published to npm, so a 404 is not a "package does not
+exist" state. Treat it as a transient registry/network reachability issue, a
+mistyped package name, or a request for a version that does not exist: confirm
+the spelling, check `npm view @stelis/say-ur-intent version`, retry after any
+registry/proxy outage clears, and ensure no private/alternate npm registry is
+configured. Developer Checkout Setup or `npm run release:check` remains an
+option for testing local changes, not a substitute for an unpublished package.
 
 ## Client Snippets
 

package/docs/SIGNABLE_ADAPTER_CONTRACT.md

@@ -4,10 +4,10 @@ This document defines the contract boundary for wallet-review adapters.
 It is a product and implementation contract, not a current feature announcement.
 
 The current release can build local unsigned transaction material for the
-account-bound DeepBook swap review stage and internally bind a Sui transaction
-digest to that stored material. The byte handoff to the same-machine browser
-is gated on recomputed-digest equality, and the review page offers
-user-controlled wallet signing with execution receipts recorded on the
+account-bound DeepBook swap and FlowX swap review stages and internally bind a
+Sui transaction digest to that stored material. The byte handoff to the
+same-machine browser is gated on recomputed-digest equality, and the review page
+offers user-controlled wallet signing with execution receipts recorded on the
 session. No MCP tool returns
 transaction bytes, signing data, signing readiness, executable transaction
 material, or payment execution readiness.
@@ -18,7 +18,7 @@ The source-level schema for this contract lives in
 ## Current Status
 
 The contract schema is implemented in TypeScript and Zod, and the runtime
-DeepBook account-bound swap review emits it. When the account-bound review
+DeepBook and FlowX account-bound swap reviews emit it. When an account-bound review
 completes every evidence stage (local unsigned transaction material, internal
 digest commitment, object ownership, quote/policy provenance, human-readable
 review facts, and review-time simulation), the review layer assembles those
@@ -118,11 +118,12 @@ and it serves the same-machine browser only. After the gate passes, the
 review page requests the wallet signature; the signature, execution, and
 receipt stay user-controlled and never flow through the MCP layer.
 
-The current release builds local unsigned DeepBook swap transaction material
-inside account-bound review, binds a Sui transaction digest to the stored
-material, hands the digest-verified bytes to the same-machine browser, and
-lets the user sign and execute in their wallet with the receipt recorded on
-the review session. The MCP layer never requests signatures or executes.
+The current release builds local unsigned DeepBook swap and FlowX swap
+transaction material inside account-bound review, binds a Sui transaction digest
+to the stored material, hands the digest-verified bytes to the same-machine
+browser, and lets the user sign and execute in their wallet with the receipt
+recorded on the review session. The MCP layer never requests signatures or
+executes.
 
 ## Adapter Contract
 
@@ -275,6 +276,17 @@ emitted wallet review contract as `reviewState.ptbVisualization`. PTB
 visualization stays visualization-only evidence: it is not a runtime
 transaction builder, not wallet handoff, and not a signing-readiness surface.
 
+The producer emits the Mermaid flowchart as two parallel streams. `mermaid.text`
+keeps raw package addresses for audit and copy. `mermaid.namedText` is a second
+relabeled stream produced by `applyContractNamesToMermaid`
+(`src/core/action/ptbVisualizationProducer.ts`,
+`src/core/action/contractNameRegistry.ts`): it labels registered packages
+(`@deepbook/core`; the Sui framework `std`/`sui`/`sui_system`) and well-known
+objects (`SuiSystemState`, `Clock`, `Random`, `DenyList`, `CoinRegistry`,
+`AccumulatorRoot`) while keeping the raw addresses available. These names are a
+display label, not a safety, ownership, or trust signal, and the on-chain Move
+Registry name is not yet verified on chain.
+
 ## Adapter Registration And Stage Vocabulary
 
 Review adapters register through `ReviewAdapterDescriptor` entries in

package/docs/UTILITY_INDEX.md

@@ -44,6 +44,31 @@ Source-checkout scripts are not packaged product commands, MCP tools, review-tim
 | 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
+
+This is a manual maintainer check for a specific mainnet provider. Normal quickstart use does not require Sui endpoint setup. Run it for people operating releases or debugging mainnet read shape.
+
+```bash
+export SUI_GRPC_URL="https://fullnode.mainnet.sui.io:443"
+export SUI_GRAPHQL_URL="https://graphql.mainnet.sui.io/graphql" # optional override; default is the built-in mainnet GraphQL endpoint
+export SMOKE_SUI_ADDRESS="0x..."
+export SMOKE_DEEPBOOK_POOL_KEY="DEEP_SUI"
+export SMOKE_QUOTE_AMOUNT="1000000000" # raw integer units; for SUI, 1000000000 = 1 SUI
+# Optional: export SMOKE_INSPECT_DIGEST="..."
+# Optional: export SMOKE_INSPECT_RANDOM_LATEST="true"
+npm run build
+npm run smoke:mainnet
+```
+
+`SUI_GRPC_URL` must be only scheme, host, and explicit port. Do not include credentials, a path, query string, or fragment.
+`SMOKE_SUI_ADDRESS` must be a 32-byte hex Sui address, for example `0x` followed by 64 hex characters.
+`SMOKE_INSPECT_DIGEST` is optional. Use a digest whose sender or returned balance-change owner is `SMOKE_SUI_ADDRESS` to exercise the stored digest-lookup path; otherwise the lookup can still return `ok` with `persistence.stored: false`.
+`SMOKE_INSPECT_RANDOM_LATEST=true` is optional and only used when `SMOKE_INSPECT_DIGEST` is unset. It samples one digest from the latest GraphQL transaction page and calls `read.inspect_sui_transaction` without passing the smoke address. This checks current transaction-read shape without pinning a specific user address or exercising the stored relation path.
+
+DeepBook orderbook and raw-quantity quote reads use an internal mainnet SDK simulation sender placeholder, not a user's wallet. The display-amount quote path is covered by automated tests, not by this smoke script. This smoke script does not exercise account-bound DeepBook transaction-material build or digest binding; that path needs a separate funded-account material-build smoke before smoke results are treated as product-grade proof for that review stage.
+
+Wallet asset summaries and active-account activity summaries use the smoke address through a wallet identity session created by the smoke script. Browser wallet behavior is checked separately. This smoke script does not record raw GraphQL payloads, transaction bytes, signatures, raw transaction details, or compact transaction aggregates.
+
 ## Mainnet Read Smoke Notes
 
 Run `npm run build` first because `npm run smoke:mainnet` executes `dist/runtime/smokeMainnetRead.js`.

package/docs/WALLET_IDENTITY.md

@@ -50,10 +50,11 @@ 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
+SAY_UR_INTENT_REVIEW_PORT): when a second Say Ur Intent instance finds the port
+already held by a healthy Say Ur Intent review peer, it does not stop that peer
+and does not start a port war; it defers to the peer on the shared origin and
+takes the origin over only when that owner exits. A port held by any other
+(non-Say-Ur-Intent) process is never taken over. The record is
 read context and wallet preference only; it is not signing authorization.
 
 ## Status Model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stelis/say-ur-intent",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "mcpName": "io.github.stelis-dev/say-ur-intent",
   "description": "Say Ur Intent is a local-first toolkit for helping AI applications and users inspect Sui DeFi actions before execution.",
   "license": "MIT",