@stelis/say-ur-intent 0.0.1 → 0.0.2

package/README.md

@@ -30,8 +30,8 @@ choices remain with the user, and what claims are unsupported.
 
 Say Ur Intent is one product, but it must be read at three distinct layers. Do not collapse them:
 
-- **Implemented today:** Sui mainnet evidence, local review, and the first signable review adapter for the DeepBook swap route. The account-bound DeepBook swap review builds unsigned transaction material into a local in-process material store, internally binds a Sui transaction digest to that stored material, derives object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts, emits a schema-validated wallet review contract with a PTB visualization on a `ready_for_wallet_review` state, and serves a digest-gated byte handoff to the same-machine review page for user-controlled wallet signing with execution receipts recorded on the session. MCP responses do not contain transaction bytes, signing data, or signing readiness.
-- **Deliberately sequenced next (planned order, ships only after verified review):** server-side receipt verification against chain state, additional protocol adapters registered through the descriptor contract (protocol names appear only after a concrete support decision), and richer local analysis views. Each step ships only from independently built or verified transaction material with a human-readable local review.
+- **Implemented today:** Sui mainnet evidence, local review, and signable review adapters for the DeepBook and FlowX swap routes. The account-bound DeepBook swap review builds unsigned transaction material into a local in-process material store, internally binds a Sui transaction digest to that stored material, derives object ownership, quote/policy provenance, human-readable review facts, and review-time simulation evidence from the same private review artifacts, emits a schema-validated wallet review contract with a PTB visualization on a `ready_for_wallet_review` state, and serves a digest-gated byte handoff to the same-machine review page for user-controlled wallet signing with execution receipts recorded on the session. MCP responses do not contain transaction bytes, signing data, or signing readiness.
+- **Deliberately sequenced next (planned order, ships only after verified review):** server-side receipt verification against chain state, further protocol adapters beyond DeepBook and FlowX registered through the descriptor contract (protocol names appear only after a concrete support decision), and richer local analysis views. Each step ships only from independently built or verified transaction material with a human-readable local review.
 - **Never (permanently unsupported at every layer):** no private-key custody, no MCP or AI autonomous execution, no forwarding of opaque external transaction bytes to a wallet, no silent settlement-token or route choice, no fiat cash-out, no P&L, no peg guarantee.
 
 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.
@@ -91,42 +91,6 @@ For manual maintainer and developer utilities, see [docs/UTILITY_INDEX.md](docs/
 
 User-question flows for USD-denominated coverage, balance totals, and shortfall answers live in [docs/AGENT_BEHAVIOR.md](docs/AGENT_BEHAVIOR.md). The response fields for those answers live in [docs/MCP_TOOLS.md](docs/MCP_TOOLS.md).
 
-## How Product Quality Improves: Three Axes
-
-Future quality work moves along three axes. They multiply rather than add,
-so neglecting any one of them caps the value of the other two:
-
-- **Axis 1 - intent, evidence, answer quality.** Understanding what the user
-  asked, routing it to the right tool (prompt surfaces, `userAnswerUse`
-  response guidance), and answering only from verified mainnet evidence -
-  including saying plainly when a question cannot be answered from the
-  returned evidence. This axis is never finished; it is sharpened
-  continuously.
-- **Axis 2 - protocol breadth.** Additional protocol adapters registered
-  through the descriptor contract (protocol names appear only after a
-  concrete support decision). Breadth is a multiplier, not a list: with a
-  second protocol, action routing starts doing real work (the bare action
-  prompt asks the user to choose a venue instead of routing silently), and
-  the execution-trust foundation proves it is not single-protocol.
-- **Axis 3 - execution-trust foundation.** The guarantee that what the user
-  reviewed is exactly what gets signed, held under any wallet and any signing
-  speed: the review-session state machine, the one-transaction-per-session
-  handoff lock, sign-only wallets and slow hardware signers, review-page
-  security headers, and runtime lifecycle stability. Packaging and runtime
-  operability belong here too. This axis is the product differentiator, so
-  it is tracked as its own axis rather than as a side effect of feature work.
-
-```text
-axis 1 (intent-evidence quality) --+
-                                   +--x axis 2 (protocol breadth) = product value
-axis 3 (execution-trust base)   --+
-```
-
-Work that advances several axes at once - for example, a new adapter that
-forces the intent entry point to generalize and re-proves the trust pipeline
-on a second protocol - is preferred over work that advances one axis in
-isolation.
-
 ## What Works Today
 
 The current release can run as a local stdio MCP server and expose mainnet Sui DeFi evidence:
@@ -136,10 +100,11 @@ The current release can run as a local stdio MCP server and expose mainnet Sui D
 - USD-denominated settlement asset groups derived from pinned DeepBook SDK registry metadata;
 - intent evidence with response summaries for natural-language USD-denominated payment coverage, balance-total, and shortfall questions;
 - DeepBook pools, tokens, mid price, orderbook context, raw quotes, display-amount quotes, and account inventory;
+- FlowX CLMM pools and indicative single-hop swap route quotes from the chain-verified pinned registry;
 - 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 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. The MCP layer and review API never sign, execute, or return transaction bytes.
 
 It also includes:
 

package/docs/AGENT_BEHAVIOR.md

@@ -11,7 +11,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. |
-| DeepBook 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 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. |
+| 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. |
 | PTB visualization | Rendered with emitted wallet review contracts | `reviewState.ptbVisualization` can accompany an emitted wallet review contract as a Mermaid flowchart of the stored local transaction shape. Treat it as visualization evidence only, not transaction-building input, wallet authorization, signing data, signing readiness, payment execution readiness, or route recommendation. |

package/docs/AGENT_DEVELOPMENT_POLICY.md

@@ -738,3 +738,23 @@ Work is complete only when:
 - final repository status is checked, including untracked files;
 - unexpected files are classified or cleaned up before final response;
 - if previous progress was overstated, the final response corrects the record.
+
+## Quality direction
+
+Quality work continues along three areas; progress in all three matters, and
+work that advances more than one at once is preferred over work that advances
+only one in isolation:
+
+- Intent, evidence, and answer quality: understand the request, route it to the
+  right tool (prompt surfaces, `userAnswerUse` response guidance), and answer
+  only from verified mainnet evidence, including saying plainly when a question
+  cannot be answered from the returned evidence.
+- Protocol breadth: additional protocol adapters registered through the
+  descriptor contract; protocol names appear in public docs only after a
+  concrete support decision. A second protocol is why the bare action prompt
+  asks the user to choose a venue instead of routing silently.
+- Execution-trust foundation: what the user reviewed is exactly what gets
+  signed, under any wallet and any signing speed — the review-session state
+  machine, the one-transaction-per-session handoff lock, sign-only wallets and
+  slow hardware signers, review-page security headers, runtime lifecycle
+  stability, and packaging and runtime operability.

package/docs/FRONTEND_POLICY.md

@@ -136,9 +136,10 @@ out-of-state buttons are removed, not disabled.
 
 The sign action appears only on `ready_for_wallet_review` with an emitted
 wallet review contract, a connected wallet whose account equals the reviewed
-account, and a successful digest-gated handoff. The signing wallet list offers
-only the wallet recorded for the active account; other detected wallets are
-not offered. While a handoff is outstanding the server locks the session
+account, and a successful digest-gated handoff. The signing step shows no wallet picker:
+dapp-kit autoconnect restores the wallet recorded for the active account on the
+fixed-port origin, and the sign action stays gated on the connected account
+matching the reviewed account. While a handoff is outstanding the server locks the session
 (state recomputes are refused) and the page shows a signing-in-progress state
 whose only action is cancel. Other states render:
 

package/docs/MCP_SETUP.md

@@ -64,6 +64,58 @@ On native Windows clients that need `cmd`, use the same command through `cmd /c`
 }
 ```
 
+## Published Package Setup
+
+Once `@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.
+
+### Download on demand (npx, tracks the latest release)
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@stelis/say-ur-intent"]
+}
+```
+
+No install step, and each launch resolves the latest published version. The
+trade-off: the first launch (or the first after the npx cache is cleared)
+downloads the package and its native dependencies. On a cold cache this can take
+long enough to exceed a client's MCP startup timeout, so the client may stop the
+server before it connects. If that happens, warm the cache once in a terminal and
+then restart the client:
+
+```bash
+npx -y @stelis/say-ur-intent
+# wait until it logs "review server started", then stop it with Ctrl-C
+```
+
+### Install once (global, fastest startup, pinned version)
+
+```bash
+npm install -g @stelis/say-ur-intent
+```
+
+```json
+{
+  "command": "say-ur-intent"
+}
+```
+
+The global `say-ur-intent` command starts with no per-launch download, so it
+avoids the cold-start timeout, and it stays on the installed version until you
+update it explicitly:
+
+```bash
+npm install -g @stelis/say-ur-intent@latest
+```
+
+The per-client sections below use the `npx` form. To use a global install
+instead, replace the published-package command with `"command": "say-ur-intent"`
+and drop the `args`. On native Windows clients that need `cmd`, wrap either
+command, for example `"command": "cmd", "args": ["/c", "npx", "-y", "@stelis/say-ur-intent"]`.
+
 ## Claude Code
 
 Claude Code supports local stdio MCP servers through `claude mcp add`. Put Claude CLI options such as `--transport` and `--scope` before the server name; the `--` separator starts the command that runs Say Ur Intent.
@@ -81,7 +133,7 @@ Published npm package:
 ```bash
 claude mcp add --transport stdio \
   say-ur-intent \
-  -- npx -y @stelis/say-ur-intent@next
+  -- npx -y @stelis/say-ur-intent
 ```
 
 Claude Code scopes:
@@ -144,7 +196,7 @@ Published npm package:
   "mcpServers": {
     "say-ur-intent": {
       "command": "npx",
-      "args": ["-y", "@stelis/say-ur-intent@next"]
+      "args": ["-y", "@stelis/say-ur-intent"]
     }
   }
 }
@@ -157,7 +209,7 @@ On native Windows, use `cmd /c` if direct `npx` or `node` resolution fails:
   "mcpServers": {
     "say-ur-intent": {
       "command": "cmd",
-      "args": ["/c", "npx", "-y", "@stelis/say-ur-intent@next"]
+      "args": ["/c", "npx", "-y", "@stelis/say-ur-intent"]
     }
   }
 }
@@ -185,7 +237,7 @@ Published npm package:
 
 ```bash
 codex mcp add say-ur-intent \
-  -- npx -y @stelis/say-ur-intent@next
+  -- npx -y @stelis/say-ur-intent
 ```
 
 Verify with:
@@ -211,7 +263,7 @@ Equivalent `~/.codex/config.toml` entry after npm publication:
 ```toml
 [mcp_servers.say-ur-intent]
 command = "npx"
-args = ["-y", "@stelis/say-ur-intent@next"]
+args = ["-y", "@stelis/say-ur-intent"]
 startup_timeout_sec = 10
 tool_timeout_sec = 60
 ```
@@ -247,7 +299,7 @@ Published npm package:
   "mcpServers": {
     "say-ur-intent": {
       "command": "npx",
-      "args": ["-y", "@stelis/say-ur-intent@next"]
+      "args": ["-y", "@stelis/say-ur-intent"]
     }
   }
 }
@@ -358,7 +410,7 @@ To reset local product data files, stop the MCP server and delete `say-ur-intent
 ### Fixed review server port
 
 `SAY_UR_INTENT_REVIEW_PORT` pins the local review server to a fixed loopback
-port (1-65535; default is a random free port). A fixed port keeps the review
+port (1-65535; default `8765`). A fixed port keeps the review
 page origin stable across server restarts, so the browser wallet's
 authorization and the signing auto-reconnect persist instead of being asked
 again on every restart. If the port is taken, the server fails to start

package/docs/MCP_TOOLS.md

@@ -156,7 +156,7 @@ Every quote fails closed unless all of the following hold:
 - the echoed input amount equals the requested raw amount;
 - the protocol config carried by the quoter response matches the pinned package and object ids (`protocolConfigPinMatch: true`).
 
-`source.chainVerified: false` and `quantitySemantics.chainVerified: false` state that this quote comes from the FlowX quoter API over HTTPS, not from a chain read. `amountOut.indicative: true` marks the output as an indicative estimate. Signable FlowX review, when it ships, re-verifies any quote through review-time simulation before a transaction can be reviewed.
+`source.chainVerified: false` and `quantitySemantics.chainVerified: false` state that this quote comes from the FlowX quoter API over HTTPS, not from a chain read. `amountOut.indicative: true` marks the output as an indicative estimate. Signable FlowX review re-verifies the quote through review-time simulation before the account-bound review reaches `ready_for_wallet_review`.
 
 The same payment-answer blocks as the DeepBook quotes apply: `canUseForPaymentAnswer: false`, `doNotCombineWithPaymentAnswer: true`, and `read.preview_intent_evidence` `responseSummary` stays the only payment-coverage answer source.
 

package/docs/SDK_API.md

@@ -4,9 +4,13 @@ This document records the pinned SDK APIs used by the current runtime. The sourc
 
 ## Package Versions
 
-- `@mysten/sui`: `2.16.2`
+- `@mysten/sui`: `2.17.0`
 - `@mysten/deepbook-v3`: `1.3.6`
 - `@mysten/dapp-kit-core`: `1.3.2`
+- `@flowx-finance/sdk`: `2.1.0`
+- `@stelis/agent-q-provider-sui`: `0.0.5`
+- `@zktx.io/ptb-model`: `0.5.0`
+- `mermaid`: `11.12.0`
 
 ## Sui gRPC Client
 

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@stelis/say-ur-intent",
-  "version": "0.0.1",
+  "version": "0.0.2",
+  "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",
   "type": "module",
@@ -33,7 +34,7 @@
   "homepage": "https://github.com/stelis-dev/say-ur-intent#readme",
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   },
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",