@stelis/say-ur-intent 0.0.7 → 0.0.8

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.
@@ -104,7 +119,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 +146,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 +163,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.
 
@@ -299,24 +314,33 @@ 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.
+
+Two pinned, context-aware registries in
+[`src/core/action/contractNameRegistry.ts`](src/core/action/contractNameRegistry.ts)
+drive this:
+
+- 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`.
 
 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.
+mainnet package address and MVR name to the package registry. Every unregistered
+address keeps its raw form.
 
 ## For Maintainers
 

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/MCP_SETUP.md

@@ -542,7 +542,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/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.0.8",
   "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",