@zktx.io/sui-mcp 0.5.0 → 0.6.1

package/docs/MCP_TOOLS.md

@@ -8,6 +8,31 @@ It does not own installation steps or user-question playbooks. Installation and
 
 Tool names use dot prefixes and avoid arbitrary shell, arbitrary Move calls, and private-key handling.
 
+The local stdio gateway forwards each request through authenticated internal
+HTTP. A request body must fit within 4 MiB, including the entire MCP JSON-RPC
+envelope and metadata. An oversized request is rejected before tool or card
+dispatch; this is an input-size error, not an unsupported function, wallet
+rejection or unconfirmed file delivery. Reduce the request before calling again.
+Card calls also have a 64 KiB envelope budget. Ordinary MCP calls do not inherit
+that smaller card limit. Restore files may contain up to 16 MiB and are sent in
+separate messages within the card budget; the 4 MiB request limit is not a
+backup-file limit.
+
+Internal cards require the current MCP connection to advertise
+`extensions["io.modelcontextprotocol/ui"].mimeTypes` as a string array containing
+`text/html;profile=mcp-app`. Client names and versions do not select card
+support. An absent, malformed or nonstandard advertisement returns
+`ui_unavailable` without creating a card or issuing its source query; ordinary
+evidence tools remain available. An advertisement enables card delivery, not
+transaction or Settings authorization. Scoped UI permission, stored target and
+revision checks still apply to each input action.
+
+Card responses use structured content or the corresponding JSON text payload.
+A single serialized MCP tool-result carrier and exact saved-card resource links
+are normalized by format. Conflicting payloads, private metadata or card
+identities are rejected. JSON inside ordinary product data and saved links do
+not grant input permission; a saved card is read through its bound resource.
+
 ## Read-Only Tools
 
 | Tool | Status | Purpose |
@@ -155,7 +180,7 @@ When Chart pool choices cannot be prepared, the backend creates a `closed`/`fail
 
 Receipt model results retain input kinds/indices/object references and identify input values and PTB as UI-only details. Receipt and completed Review show the executed transaction graph above their result summary when bound private metadata is available. Technical records are in one Details slide. Missing metadata leaves the saved result available without inventing a graph. The typed `sui-mcp/receipt-display` metadata binds display data to the same card ID, transaction digest and revision. It carries individual on-chain Pure input values and the graph derived from those inputs; never a serialized transaction, signature or wallet credential. Public saved resources contain only the model projection. A missing UI detail payload means unavailable display data, not that a transaction had no inputs.
 
-Backend expiry ends unsubmitted input. A server restart invalidates unfinished cards; stored completed results remain readable. Reset/import removes cards and their permissions with the data change. Completed input does not reopen, while still-valid unsubmitted input is unaffected by chat navigation. A lost submit response is resolved by reading the same card, without another source request.
+Backend expiry ends unsubmitted input. A server restart invalidates unfinished cards; stored completed results remain readable. Reset/import atomically removes other cards/permissions with the data change and preserves the applying Settings card/result as read-only. Completed input does not reopen, while still-valid unsubmitted input is unaffected by chat navigation. A lost submit response is resolved by reading the same card, without another source request.
 
 When a Host replays a historical card without its private input permission, the
 View reads `suimcp://cards/{cardId}` to restore the same card's current saved
@@ -1071,7 +1096,8 @@ Each disconnection uses the same scoped UI permission, current run and revision,
 atomic admission and saved result as an ordinary single-connection disconnect.
 No first/newest/default wallet is silently selected. When one valid connection
 remains and no connection operation is pending, normal account use can resume;
-with none, pairing is available. A failed disconnect does not prove remote removal.
+with no recorded or SDK-present connection and no pending operation, pairing is
+available. A failed disconnect does not prove remote removal.
 A failed or stopped product connection is not restored merely because its SDK
 session remains saved.
 
@@ -1093,6 +1119,19 @@ the stored default's source connection ID to match this connection and its
 address to remain approved. Matching the address in a different connection is
 insufficient. A source-less stored selection requires explicit Use address.
 
+`manageableConnectionIds` identifies exact recorded targets for a new scoped
+Disconnect, separately from account use. It includes nonpending connected records
+(including expired ones) and known terminal records whose current SDK session
+remains present. `connectionReconciliationRequired: true` identifies a present SDK
+session without a journal target after normal registration/cleanup ends. It
+blocks pairing, account use, preparation and signing while preserving SDK
+availability and saved outcomes. Remove the retained connection in the wallet
+app, then confirm absence through a complete current service observation.
+Settings/Troubleshooting can explicitly restart the service to inspect it again;
+restart alone does not remove or approve that connection. No private topic or synthetic target ID
+is exposed. Both fields also appear in interaction status; review status includes
+the reconciliation flag when current eligibility is needed.
+
 These fields are emitted together for current wallet eligibility. Independent
 historical or completed-result reads may omit them; omission does not establish
 current eligibility. Recorded `connections` and `activeAccount` remain facts,
@@ -1116,7 +1155,10 @@ errors still fail the read without deleting the stored execution result.
 
 Connect does not accept `restart_wallet_service`; that input returns
 `invalid_card_input` without consuming the card or changing the SDK run.
-There is no model-facing or Settings replacement command. Operational app
+Ordinary MCP tools cannot replace the connection service. A user may prepare
+and confirm its restart in the internal Settings card's Troubleshooting controls.
+This restores service availability, not an interrupted wallet approval or
+disconnect result. Operational app
 restart is described in [MCP Setup](MCP_SETUP.md#wallet-connection-boundary).
 
 A historical `runtimeRecovery` result retains its prior/next run IDs,
@@ -1209,38 +1251,260 @@ facts actually exist.
 | Tool | Status | Purpose |
 | --- | --- | --- |
 | `account.get_active_account` | Implemented | Reads the active wallet-account read context. |
-| `account.clear_active_account` | Implemented | Clears the active wallet-account read context. |
+
+The user clears the default read address through a confirmed Settings card action. Ordinary MCP calls do not clear it.
 
 ## Settings Tools
 
 | Tool | Status | Purpose |
 | --- | --- | --- |
-| `settings.create_local_settings_session` | Implemented | Creates a same-machine local settings page session. |
-| `settings.get_local_settings` | Implemented | Reads local Sui MCP settings, including effective Sui gRPC and GraphQL endpoint sources. |
-
-Settings MCP tools are session-gateway/read tools, not direct mutators.
-
-The settings page can change local settings after settings-token validation:
-
-- stored Sui gRPC or GraphQL endpoint;
-- default endpoint restoration;
-- active account read context clearing;
-- logical local data reset;
-- local data export;
-- replace-only local data import.
-
-These actions do not sign, execute, create custody, or produce signing material.
-
-Endpoint changes apply after MCP server restart.
-
-Custom providers can affect read data quality, so use trusted mainnet providers.
+| `settings.create_local_settings_session` | Implemented | Opens one internal Settings card with an unsubmitted draft. |
+| `settings.get_local_settings` | Implemented | Reads stored/effective Sui gRPC and GraphQL endpoints, sources and pending restart information. |
+
+The gateway name is preserved. Its result is a `kind: "settings"` card snapshot
+and a public saved-result link. Card permission is only in `sui-mcp/card` UI
+metadata. There is no `settingsUrl`, `openTarget`, external page, HTTP mutation
+API or compatibility alias. A client without internal cards receives
+`ui_unavailable`; ordinary model calls never apply a Settings change.
+
+Settings groups Address for viewing assets, Local records, Troubleshooting and Advanced
+settings. Confirmed changes are `clear_read_address`, `set_endpoint`,
+`restore_endpoint` (gRPC or GraphQL), `import_local_data`, `reset_local_data`
+and `restart_wallet_service`. Their preparation and confirmation use app-only
+`ui.act_card` with card permission, revision, operation identity and the exact
+preparation identity. Choosing or checking data does not apply it, contact a
+wallet or restart the SDK. Duplicate confirmation returns the same admitted
+result; MCP JSON-RPC request IDs do not authorize another operation.
+
+Download backup uses one `settings_download_backup` action with `operationId`
+and an `attemptId` UUID, admitted atomically through the same scoped card input.
+It creates a `download_backup` operation and one immutable snapshot. It requires
+no separate selection, preparation or confirmation action. The same admitted
+start returns the same request; a different start cannot replace it. New
+`export_local_data` selection/preparation/confirmation is not accepted.
+
+The card uses plain-language display labels without changing wire fields or
+enums. Wallet-service `available`, `initializing`, `recovering` and `unavailable`
+display as Ready, Starting, Restarting and Unavailable; Ready describes the
+service, not a connected or approved wallet. Endpoint sources display as App
+launch settings, Saved in Sui MCP and Built-in default. Internal connection and
+transaction-request IDs remain in Details; wallet identity and restart impact
+remain beside the confirmation. Known validation errors explain the cause and
+next action without requiring knowledge of upload chunks or backend admission.
+
+Completing an import upload automatically checks its integrity, current-format
+contents and local replacement conditions. `data.restoreCheck.status` is
+`no_file`, `receiving`, `checking`, `check_required`, `can_restore` or
+`cannot_restore`. Receiving describes an unsealed transfer; a complete sealed
+file needing a new local check is `check_required`, not a validation failure.
+A blocked check carries
+its `reason` and user-readable `message`; it does not end the operation or
+misclassify a storage/service failure as an invalid file. `can_restore` describes
+the current preparation, not authority, completed replacement or guaranteed
+success. The exact UI permission, preparation identity and final admission are
+still required. Imported endpoint verification runs after final confirmation,
+before any data replacement. Reads never start a new check or application.
+
+Known invalid backup contents or a definite imported URL/mainnet rejection remain
+bound to the selected file ID, hash, length and operation epoch. `settings_back` or a
+local-data revision change discards current confirmation without clearing that
+file rejection. `settings_prepare` cannot erase it or make the same file ready;
+the user must explicitly change the file selection. A new selection can use the
+same original bytes and receives a new file identity. Timeout or unreachable
+endpoint failures permit an explicit local recheck and a new final confirmation;
+that recheck does not call imported endpoints. The server derives recheck actions
+from the same decision used by the handler; the View does not choose its own
+failure-recovery policy.
+
+`file.sealed` records complete, integrity-checked transfer; it does not by itself
+establish a supported backup or permission to restore it. `settings_back` and user-data
+changes invalidate preparation while preserving a reusable complete file.
+The explicit `settings_prepare` action rechecks such a file; normal file
+selection requires no separate Preview action. A failed check preserves its
+current file/operation identity and correction path. Owner replacement ends old
+input; a new card must receive a new explicit file selection.
+
+A download's `result.completionScope: "backup_snapshot"` identifies the immutable
+preparation result, not a saved user file. `data.download` separately carries
+`availability` (`preparing`, `available`, `ended`), `currentAttemptId`, an optional
+`hostReport` (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`), `previousUnconfirmed`,
+`expiresAt`, `remainingMs`, `endReason` and `allowedFileActions`. End reasons are
+`acknowledged`, `cancelled`, `expired`, `server_restarted`, `data_replaced`,
+`source_unavailable`, `stored_locally` or `local_save_failed`. Replacement revokes the old card rather than preserving
+its input. The transfer period is thirty minutes from physical readiness;
+reads/retries never extend it or reopen the original business-input deadline.
+Raw per-attempt preparation is not copied into public `preparation`.
+
+`data.download.localSave`, when present, separates `needs_consent`, `saving`,
+`saved` and `failed`. It may include `currentSaveAttemptId`, `savedAt` and a
+failure reason (`not_published`, `target_conflict`, `source_unavailable` or
+`interrupted`). Uncertain physical results remain `saving`; they do not grant
+another save. `previousUnconfirmed` includes an earlier attempt whose delivery
+absence was not established, including an unreported or not-completed request.
+
+A verified local `saved` result provides `data.backupLocation.directory` and
+`filename` for `<SUI_MCP_DATA_DIR>/backups/<operationId>.json`. Snapshot preparation
+and Host acknowledgment do not provide that local success. A recorded
+`export_local_data` result can also identify its existing file. These fields
+never identify the destination chosen by a Host download dialog. Existing user
+files are never deleted by private snapshot cleanup. Private publication
+identities and source inode/device facts are not public projection fields.
+
+Current `data.facts` uses the same connection selection and qualification rules
+as interaction status, through a fact reader that does not settle another
+request's deadlines or callback writes. General counts describe stored records;
+reset/import preparation and confirmation independently settle deadlines and
+check the current deletion impact. Creating a Settings card or checking its own
+permission, expiry, result or cleanup retains that operation's required writes.
+`connectionReconciliationRequired: true` is separate from SDK availability and
+requires a published available run with confirmed unrecorded presence:
+remove the unrecorded connection in the wallet app, then confirm absence.
+Settings overview and Troubleshooting show that action; a service restart only
+re-inspects retained sessions and does not approve or remove them.
+An initializing/state_sync memory snapshot does not establish that diagnosis.
+The ordinary interaction response exposes its removal-and-confirmed-absence
+meaning in `userAnswerUse.canAnswer` only when the diagnostic flag is present;
+the corresponding precondition and answer fields reference the same flag.
+Neither service availability nor an absent flag establishes account authority
+or proves that no SDK session exists.
+
+`data.phase` is `draft`, `uploading`, `sealed`, `prepared`, `executing`,
+`stopping`, `starting` or `terminal`. `allowedActions` lists permitted business input;
+`observe` permits reading the existing operation only. Known file-I/O and final-slot
+conditions affect the offered actions; final admission rechecks them atomically.
+Local section navigation and Resume do not call `settings_back` or change stored
+preparation. Check status reads the same card when a change is temporarily
+unavailable and never repeats a business action or Host download. After a
+successful read, an already received but unrecorded download report can be
+recorded idempotently without resending bytes. Public fields include
+`operationId`, `draft`, preparation identity/impact, file ID/name/length/hash,
+`priorRunId`, `nextRunId`, supersession links and a recorded result. Results use
+`completed`, `failed`, `interrupted` or `superseded`. Completion describes that
+local operation, not a transaction's chain outcome. Optional
+`temporaryFileCleanup` separately reports `pending`, `failed` or `complete`;
+reading/checking it never repeats data replacement, backup creation, Host delivery or SDK
+replacement. Terminal business input remains closed; only the separate scoped
+file continuations in `data.download.allowedFileActions` may remain available. Public fields contain no raw file, transaction bytes, signatures,
+SDK credentials or card permission.
+
+A user-data writer invalidates its affected prepared confirmation atomically.
+A still-valid sealed import file remains available for a new backup check after
+`settings_back` or invalidation; an old revision/preparation cannot apply it. Explicitly
+choosing a different file invalidates the old upload. Upload, preparation and
+input permission have separate lifetimes. Known validation rejection returns
+safe input-error text and the actual current snapshot. Wrong permission returns
+no snapshot or domain explanation; storage/I/O failures are not input errors
+or success.
+
+Backup uploads accept at most 16 MiB before Base64/JSON wrapping. Chunk offsets,
+reservations, canonical Base64, full length and SHA-256 are verified. The entire
+internal MCP JSON-RPC message remains within 65,536 UTF-8 bytes; oversized upload
+rejection can report a smaller raw chunk limit before any write. The backup check validates
+strict current backup shape/references without endpoint contact. Confirmation
+verifies imported endpoints report Sui mainnet and rechecks current data and
+unsettled wallet/transaction work before atomic replacement.
+The prepared import includes `currentReadAddress` and `incomingReadAddress`
+(`null` when unset), the corresponding change and current/incoming record counts.
+Both preparation and final admission settle request deadlines before capturing
+or comparing that decision basis. A newly unknown outcome requires a new backup check.
+Reset/import revoke other live permissions and preserve only their own read-only card/result.
+Their confirmation warns that replacement can remove unconfirmed transaction
+records even when the checked count is zero; actual nonzero deletion counts stay
+visible. Outstanding wallet/transaction responses and an unfinished initial
+result-checking window block replacement, including after the user stops
+automatic result checks. Stopping those checks does not shorten that window.
+They cannot cancel a transaction on Sui or disconnect a remote wallet session.
+The private connection-service journal is preserved; it is not imported from
+the public backup and cannot restore old permissions or signing authority.
+Reset clears the default address. A restored default requires its exact current
+connection ID and approved address. Outstanding connection SDK callbacks block
+replacement along with unsettled transaction work.
+
+Endpoint preparation records the gRPC/GraphQL kind, current stored/effective
+value and source, and exact proposed stored value. Only final confirmation checks
+mainnet and stores that target. Its result captures `effectiveValueAtSave` and
+`effectiveSourceAtSave`, rather than claiming to describe a later server run.
+An environment override continues to take precedence after restart while it
+remains set; storing an endpoint does not modify that environment.
+
+Download creates and verifies one private snapshot with an exclusive generated
+file identity. Supported Host delivery does not publish a second permanent backup. Response or result
+storage failure never regenerates that snapshot. `ui.read_settings_file` is
+app-only and binds card/permission, operation, file, offset, verified hash/length
+and the current `attemptId` for a private download. Its ordinary content carries
+range metadata; Base64 bytes appear only in `sui-mcp/settings-file` UI metadata.
+The View checks the complete hash before standard Host delivery.
+
+File continuations also use app-only `ui.act_card`:
+
+- `settings_retry_download`: `operationId`, `fileId`, `previousAttemptId` and a
+  new `attemptId`; atomically advances one attempt on the same live snapshot.
+- `settings_report_download`: `operationId`, `fileId`, `attemptId` and `status`
+  (`acknowledged`, `not_completed`, `unconfirmed`, `unsupported`); the same report is idempotent,
+  and conflicting reports for one attempt are rejected. A late older report
+  cannot change the current attempt or end its retention. `unsupported` requires
+  exactly `failure: {method: "ui/download-file", code: -32601}`; other statuses
+  must omit `failure`. Only the actual download call's method-not-found result
+  supplies that report. It is atomically admitted with the same snapshot's local
+  publication intent when no earlier delivery is possible. A busy shared slot
+  rejects that admission atomically; the View can record the same received
+  report again without another Host call. An older or ended attempt report
+  never admits publication.
+- `settings_cancel_download`: `operationId`, `fileId` and `attemptId`; ends
+  further delivery of that snapshot, not a Host dialog or a user-saved file.
+  Cancellation is refused while a local save is in progress or its outcome is
+  uncertain. After a failure recorded as `not_published`, cancellation remains
+  available within the transfer period for the current authorized request.
+- `settings_store_backup`: `operationId`, `fileId`, current `attemptId`, a new
+  `saveAttemptId`, required boolean `allowPossibleCopy`, and optional
+  `previousSaveAttemptId`. It is available only for that snapshot's recorded
+  unsupported result. Possible earlier delivery requires explicit true consent;
+  otherwise false is required. Initial consent has no previous save ID. A retry
+  of a confirmed no-publication failure must name the current failed save ID.
+  IDs and consent are immutable per admission; duplicates do not repeat effects.
+  It accepts no arbitrary path, name or bytes.
+
+These actions validate current owner, epoch, credential and exact file/attempt
+identity independently of terminal business input. Retry/read requires a live
+transfer period. A late report can record a fact after that period ends but
+cannot restore the file or authority. Host acknowledgment ends retention and
+requests cleanup; it does not prove a save location or completed disk storage.
+`isError` does not distinguish cancellation, denial or failure. A lost response
+is unconfirmed and never triggers automatic retransmission. Cleanup failure is
+reported separately and is retried through Check status or owner recovery.
+Local publication closes further Host reads/retries for that snapshot. Its
+final/file-I/O reservations survive the immutable terminal snapshot result.
+New save admissions and retries require the original live period; admitted
+file work settles even if it outlives that period. A process restart verifies
+only an existing target bound to its recorded source identity/content. It never
+publishes a missing target or restores the departed card's action authority.
+A missing or changed source ends that private transfer; a new explicit request
+is required. An existing public backup is verified on the same descriptor used
+for each range and is never truncated or removed by temporary cleanup.
+
+Troubleshooting recovery confirms a precise SDK run and affected unsubmitted
+requests. Admission revokes their submission authority before stopping the old
+child. The result waits for the owned child's exit, new run reservation,
+startup and complete observation. A new explicit Settings confirmation can
+supersede a startup still pending; it cannot replace stopping or erase a known
+failure. Already admitted submissions keep observing the same digest. Restart
+does not confirm an interrupted disconnect or sign/submit a new transaction.
+The confirmation identifies wallet connection records with their recorded status
+and addresses. Historical disconnected/failed records do not prove a current
+connection or approval. The complete recorded impact remains bound to admission;
+the display does not filter it into a new wallet-eligibility rule.
+
+Endpoint changes require fully quitting/reopening every participating app to
+apply parent configuration. Restart connection service only replaces the SDK
+child. Installation environment overrides continue to take precedence. Custom
+providers affect read data quality; use trusted Sui mainnet providers.
 
 ## Resources
 
 Sui MCP serves the URI prefixes `suimcp://` and `ui://sui-mcp/`.
 The
 `sui-mcp/card`, `sui-mcp/receipt-display` and
-`sui-mcp/wallet-display` metadata keys bind stored cards to their
+`sui-mcp/wallet-display` and `sui-mcp/settings-file` metadata keys bind stored cards to their
 permissions and display facts. Clients must use the returned URI/key values.
 
 

package/docs/SDK_API.md

@@ -1,23 +1,74 @@
 # SDK API Verification
 
-This document records the pinned SDK APIs used by the current runtime. The source of truth is the installed package source in `node_modules`, not memory or external summaries.
+This document records the pinned SDK APIs used by the current runtime. Backend
+API facts come from the installed SDK source in `node_modules`. Browser
+libraries are embedded during the build; their packaged versions are recorded
+in the card dependency notices described below.
 
 ## Package Versions
 
 - `@modelcontextprotocol/ext-apps`: `1.7.5`
-- `@modelcontextprotocol/sdk`: `1.29.0`
+- `@modelcontextprotocol/sdk`: `1.31.0`
 - `@mysten/sui`: `2.17.0`
 - `@mysten/deepbook-v3`: `1.3.6`
 - `@walletconnect/sign-client`, `@walletconnect/types`, `@walletconnect/utils`: `2.23.10`
 - `qrcode`: `1.5.4`
 - `@zktx.io/ptb-model`: `0.5.0`
-- `mermaid`: `11.12.0`
+- `mermaid`: `11.16.1`
+- `katex`: `0.18.2`, pinned by an override scoped to `mermaid@11.16.1`
+
+Mermaid and its KaTeX dependency are build dependencies for the embedded card
+resources, not Node server runtime dependencies. Their versions are fixed by
+the source-checkout lockfile and included in the generated HTML. Installed npm
+dependencies do not apply a dependency package's own overrides.
+
+## Bundled Transaction Diagrams
+
+The backend uses `@zktx.io/ptb-model` to generate a flowchart from verified
+review material or a transaction read from Sui. The shared browser renderer
+uses Mermaid to display that flowchart in the Review and Receipt cards.
+The diagram is display evidence; it does not authorize signing or execution.
+
+`scripts/build-mcp-ui.ts` embeds each card's script and styles in one HTML
+resource and records the modules included in that resource. Check
+`dist/mcp-app/review.notices.txt` and `receipt.notices.txt`, or the dependency
+notices embedded in their HTML, for the actual browser-library versions.
+The dependency versions in a new source-checkout build come from
+`package-lock.json`. Reinstalling a published package's runtime dependencies
+does not replace the libraries already embedded in its card HTML. A browser
+dependency update requires rebuilding and distributing the card resources.
 
 ## MCP Apps
 
-`@modelcontextprotocol/ext-apps` is pinned to `1.7.5`, with MCP SDK `1.29.0`. The server uses `registerAppTool`, `registerAppResource` and `getUiCapability`; the view uses `App` for host-mediated calls and teardown. Account, Receipt, Chart, Connect and Review are separate self-contained resources, so an account card does not load the PTB or chart renderer. The server keeps app-only permissions out of model content.
+Card support uses the current MCP connection's
+`extensions["io.modelcontextprotocol/ui"].mimeTypes` advertisement. The pinned
+`getUiCapability` and `RESOURCE_MIME_TYPE` exports own extraction and the
+standard MIME identifier. The UI object and its string array are validated;
+client names, versions and unrelated MIME types do not enable cards.
+Capability negotiation does not grant scoped card or transaction authority.
 
-The shared server uses the pinned MCP SDK Streamable HTTP transport behind authenticated loopback access. Stdio clients forward tool, resource and prompt requests with their original client identity and capabilities. Ordinary MCP input schemas remain unchanged by the transport; the 64 KiB card/HTTP input limit includes the card call envelope.
+The common View normalizes structured results, their JSON text fallback and a
+single serialized `CallToolResult` carrier validated with the pinned SDK
+schema. Conflicting payloads or private metadata are rejected. Ordinary data
+does not supply input permission, and saved resource links remain read-only.
+
+`@modelcontextprotocol/ext-apps` is pinned to `1.7.5`, with MCP SDK `1.31.0`. The server uses `registerAppTool`, `registerAppResource` and `getUiCapability`; the view uses `App` for host-mediated calls and teardown. Account, Receipt, Chart, Connect, Review and Settings are separate self-contained resources, so an account card does not load the PTB or chart renderer. Settings uses scoped app-only inputs for local actions and file transfer. The server keeps app-only permissions out of model content.
+
+Settings completes a selected upload's verification and restore preparation on
+the backend. The card renders the stored `restoreCheck` result and collects one
+final restore confirmation; it does not parse backup contents, decide backend
+eligibility or apply data automatically. The complete file, preparation and
+final input remain bound to their card/operation identity and current revision.
+The backend distinguishes unsealed receiving, active checking, a sealed file
+needing a new check, a current confirmation and actual rejection. Definite
+file/mainnet rejection is independent of local-data confirmation revision and
+survives Back until explicit file selection changes. The View's current file-job
+progress describes communication only; it cannot grant restoration authority.
+
+Recorded backup locations use backend-native folder and file-name fields;
+optional `App.downloadFile` delivery remains separate from local publication.
+
+The shared server uses the pinned MCP SDK Streamable HTTP transport behind authenticated loopback access. Stdio clients forward tool, resource and prompt requests with their original client identity and capabilities. SDK 1.31.0 limits each internal HTTP request body to 4 MiB, including its complete MCP JSON-RPC envelope and metadata. Oversized bodies are refused before tool or card dispatch. Card calls additionally have a 64 KiB envelope budget; ordinary MCP calls do not inherit that smaller limit. Restore uploads retain their 16 MiB file limit and are split into messages within the card budget. The SDK's internal HTTP batch guard does not expose a stdio batch feature.
 
 ## WalletConnect Runtime
 
@@ -167,13 +218,15 @@ facts; its absence/timeout does not prove execution failure.
 SDK session storage persists only the pinned connection namespaces. History,
 requests and unknown queue keys are volatile. The SDK has no supported complete
 in-process disposal; its owner process lifetime bounds callbacks and storage.
-The parent uses a fixed packaged Node child entrypoint and private versioned IPC.
+The parent uses a fixed packaged Node child entrypoint and private package-bound IPC.
 Only the SDK child owns SDK storage. The supervisor fences a terminating run,
 sends SIGKILL to its owned child and waits for actual exit. Its explicit
-replacement primitive remains private infrastructure; Connect and Settings do
-not expose a restart command. Closing relay transport or receiving an IPC disconnection is not
-evidence that the SDK operation ended. No SDK private teardown, source patch,
-automatic financial retry or overlapping storage writer is used.
+replacement primitive is private infrastructure. Settings/Troubleshooting
+owns explicit run/impact preparation, atomic input revocation/admission,
+old-child exit, next-run reservation and ready/failure recording. Connect does
+not own restart. A new explicit Settings operation can supersede a startup
+still pending; known failure and its first timestamp remain immutable.
+Late callbacks cannot reopen old authority or submit another transaction.
 
 Snapshots and per-session versions distinguish present, absent and unusable
 sessions. Source inspection failure disables the service instead of becoming an

package/docs/UTILITY_INDEX.md

@@ -43,7 +43,7 @@ Source-checkout scripts are not packaged product commands, MCP tools, review-tim
 | 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. |
 | Stored account asset timeline | `read.get_account_asset_timeline` | Implemented | Builds stored local account asset net-flow bars and optional DeepBook USDC token-denominated candle references. Not held balances, complete wallet history, USD value, P&L, cost basis, route advice, transaction building, or signing readiness. |
-| 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. |
+| Local settings | `settings.create_local_settings_session`, `settings.get_local_settings` | Implemented | MCP opens an internal Settings card or reads settings. App-only preparation/confirmation owns changes, files and explicit connection-service recovery. Stored endpoints apply after all participating apps restart. |
 | Release package check | `npm run release:check` | Maintainer, source checkout | Verifies metadata, tests/build, tarball assets/licenses and installed MCP/Settings startup. Requires network and loopback access; no wallet pairing, signing or publishing. |
 | 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. |
@@ -51,19 +51,22 @@ Source-checkout scripts are not packaged product commands, MCP tools, review-tim
 
 ## Release Package Check
 
-`npm run release:check` is a source-checkout maintainer command. Node 22 or newer,
+`npm run release:check` is a source-checkout maintainer command. Node 22.12+ within
+22.x, or Node 24+,
 installed development dependencies, npm registry access for a temporary tarball
 installation, local loopback sockets, and reachable Sui mainnet endpoints are
 required. Native SQLite must work both in the checkout and the installed package.
+The source build and tests use Vite, Rolldown and Vitest's common Node ranges; the
+installed package's Node runtime requirement is documented in MCP Setup.
 The runtime uses its built-in endpoints unless `SUI_GRPC_URL` or `SUI_GRAPHQL_URL`
 is supplied; the actual mainnet checks remain enabled.
 
 The command checks metadata, types, tests, builds, package contents and licenses,
 then launches the installed package through stdio MCP with a new data directory
 and an independent port. It reads the registered tools and resources, creates a
-Settings session only in that temporary database, and checks the Settings HTML,
-assets and authenticated status. A scoped test card verifies
-that restart input is rejected and opening manage does not pair. The check
+Settings card only in that temporary database, and checks the six internal
+HTML resources, app-only tools, scoped status and retired-route rejection. A scoped test card verifies
+that Connect rejects retired restart input and opening manage does not pair. The check
 verifies the isolated SDK retains exclusive storage ownership until shutdown. It waits
 for process termination before removing its installation. A termination failure preserves the temporary files for cleanup
 after the process stops. It does not pair, sign, submit, publish, or mutate the
@@ -259,7 +262,7 @@ It is not an MCP tool, not a CI check, not packaged product functionality, not r
 - 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.
+- Settings card actions require scoped permission and explicit confirmation. They change local settings/data or recover the connection service without authorizing a new transaction, signing or custody. Ordinary MCP opens the card or reads settings; app-only file transfer never exposes raw backup bytes to the model.
 
 ### Optional account-bound review smoke
 

package/docs/WALLET_CONNECTION.md

@@ -2,7 +2,8 @@
 
 WalletConnect provides approved Sui mainnet account context and a transport for
 individual wallet requests. It is not login, proof of address ownership, custody, or standing permission to transact. Frontend behavior is defined in
-[Frontend Policy](FRONTEND_POLICY.md); tools are in [MCP Tools](MCP_TOOLS.md).
+[Frontend Policy](https://github.com/zktx-mcp/sui-mcp/blob/main/docs/FRONTEND_POLICY.md)
+in the source repository; tools are in [MCP Tools](MCP_TOOLS.md).
 
 ## Connection and read account
 
@@ -19,9 +20,23 @@ an explicit retry even if the other connection later ends. If multiple valid con
 review preparation or signing. The Connect card shows each exact target for
 user-confirmed disconnection. After recorded disconnections leave one valid
 connection and no pending connection operation, that connection becomes usable;
-with none remaining, a new pairing is allowed. Terminal history alone does not
+with no recorded or SDK-present connection and no pending operation, a new pairing is allowed. Terminal history alone does not
 block it. A failed disconnect remains unconfirmed in the wallet app; its SDK
 session cannot revive the failed product record.
+The current SDK snapshot also gates pairing and account use. A known failed or
+disconnected record whose SDK session remains present is a disconnect target
+on a new card, not a usable wallet. `manageableConnectionIds` identifies those
+exact targets and ordinary connected targets, including expired records.
+An unmapped SDK session in a published available run sets
+`connectionReconciliationRequired: true` after pending registration/cleanup
+ends. An initializing or state_sync memory snapshot does not establish this
+diagnosis, and an absent flag does not prove session absence. Pairing, account use, preparation and signing
+remain blocked. Remove the retained connection in the wallet app, then confirm
+its absence through the current connection service. Settings/Troubleshooting
+can explicitly restart the service to inspect it again, but restarting never
+promotes an unrecorded or failed session into a usable connection. The card does
+not invent a connection ID or report physical SDK failure.
+The SDK's availability and a recorded terminal outcome alone do not prove absence.
 
 The backend validates accounts, Sui mainnet namespace, methods and expiry before
 recording a connection. A single wallet-approved account can become read context
@@ -80,14 +95,21 @@ stored results. Normal startup is shown as initialization, not as a wallet
 rejection. No implicit asset account is offered until the current service run
 confirms a usable connection.
 
-There is no card or Settings control for restarting the connection service.
-If the service stops or a disconnection remains unresponsive, fully quit all
-apps using Sui MCP, then reopen them. Closing a non-owning app or only a
-window does not stop the shared backend; another open client may take over.
-Confirm the new service is available before starting a new wallet operation.
-This does not guarantee that a relay responds or that a connection is removed
-in your wallet app. Multiple saved connections are resolved through their
-individual Disconnect controls, not by assuming an app restart clears them.
+Settings owns explicit connection-service restart. Open its Troubleshooting
+section, inspect the current run and affected requests, then confirm the
+restart. Connect manages connections/approved addresses and retains individual
+Disconnect controls for conflicting saved sessions; it does not own global
+service controls. A restart waits for old child exit, new run reservation and
+complete ready observation. Unsubmitted signing authority is revoked at
+admission; late signatures cannot submit. Already submitted transactions keep
+their original digest and observation. A new explicit Settings operation may
+supersede a still-pending startup without erasing a known failure.
+
+Restart completion does not confirm an interrupted disconnect or remove a
+remote session. Check retained connections in the wallet app. If Settings or
+the parent is unavailable, fully quit all apps using Sui MCP and reopen them;
+closing a peer/window can leave the owner running. Full app restart, rather
+than child restart, applies stored endpoints and installation changes.
 
 A new owner records interrupted connection approval as stopped and unconfirmed
 disconnection as failed. It does not repeat either request or restore their