@zktx.io/sui-mcp 0.5.0 → 0.6.0

package/docs/MCP_SETUP.md

@@ -6,7 +6,7 @@ It does not define tool field contracts or response wording. Use `docs/MCP_TOOLS
 
 The README keeps only the short entry path; client-specific setup, restart behavior, and troubleshooting live here.
 
-These instructions target `@zktx.io/sui-mcp@0.5.0`. Package installation requires
+These instructions target `@zktx.io/sui-mcp@0.6.0`. Package installation requires
 that exact version to be published; use the developer checkout instructions when
 it is not available. A repository rename or local build does not publish the
 package. Changing client settings or rebuilding files does not replace an
@@ -24,6 +24,11 @@ the package identity when switching installations.
 - stdio: standard input/output, the local transport used by MCP clients to talk to this server.
 - `@zktx.io`: the npm package scope. `zktx-mcp` is the GitHub organization. Sui MCP is the product; `sui-mcp` is the MCP server name and executable command.
 
+Each MCP request, including its envelope and metadata, must fit within the
+internal transport's 4 MiB request-body limit. Card messages have a separate
+64 KiB budget; Restore uploads keep their 16 MiB file limit by sending smaller
+messages. See [MCP Tools](MCP_TOOLS.md) for request and error semantics.
+
 ## Requirements
 
 - Node.js 22+. Node 22 or 24 LTS is recommended.
@@ -34,12 +39,12 @@ the package identity when switching installations.
 
 No Sui endpoint setup is required for the default path. The runtime creates a local SQLite database automatically, stores default Sui mainnet gRPC and GraphQL endpoints there on first start, and uses those endpoints for read-only mainnet tools.
 
-If you want a custom Sui gRPC or GraphQL provider, or local data controls, configure them after the MCP server is connected by asking your AI client to create a local settings session:
+If you want a custom Sui gRPC or GraphQL provider, or local data controls, configure them after the MCP server is connected by asking your AI client to create a Settings card:
 
 - "Show my Sui MCP local settings."
-- "Open my Sui MCP local settings page."
+- "Open my Sui MCP Settings card."
 
-Open the returned settings URL in the same machine's system browser. Custom endpoint changes apply after the MCP server restarts. Advanced temporary environment overrides are documented in [Advanced Runtime Settings](#advanced-runtime-settings).
+The tool opens an internal card; use its scoped controls in the chat app. No external URL is returned. Custom endpoint changes apply after the MCP server restarts. Advanced temporary environment overrides are documented in [Advanced Runtime Settings](#advanced-runtime-settings).
 
 DeepBook orderbook, raw-quantity quote, and display-amount quote reads use an internal mainnet SDK simulation sender placeholder.
 
@@ -51,6 +56,10 @@ Reads that require a connected default account use `session.create_wallet_connec
 
 ## Developer Checkout Setup
 
+Use Node.js 22.12 or newer within 22.x, or Node.js 24 or newer, for source builds
+and tests. These ranges satisfy Vite, Rolldown and Vitest together. The installed
+package's runtime requirement remains Node.js 22 or newer.
+
 Use this path when you download the repository from GitHub and want to test the local build:
 
 ```bash
@@ -121,7 +130,7 @@ per-client configuration below, which give the exact `command` and `args`.
 
 The npm package for this release is `@zktx.io/sui-mcp`. The commands below
 require the requested version to be published; confirm it with
-`npm view @zktx.io/sui-mcp@0.5.0 version` before switching. Both installation
+`npm view @zktx.io/sui-mcp@0.6.0 version` before switching. Both installation
 methods start the same `sui-mcp` stdio MCP server. Use a local checkout when
 working on a version that has not been published.
 
@@ -143,9 +152,12 @@ then restart the client:
 
 ```bash
 npx -y @zktx.io/sui-mcp
-# wait until it logs "review server started", then stop it with Ctrl-C
+# after the server binds or a healthy peer is confirmed, stop it with Ctrl-C
 ```
 
+The startup log reports either an owned shared server or an authenticated healthy
+peer. A bootstrap failure instead reports its stage and reason on stderr.
+
 ### Install once (global, fastest startup, pinned version)
 
 ```bash
@@ -178,8 +190,30 @@ command, for example `"command": "cmd", "args": ["/c", "npx", "-y", "@zktx.io/su
 
 ## Switching the Installed Package
 
-Use these steps when selecting a different package installation. Confirm the
-requested version is available before changing your client configuration.
+### Updating an Existing Sui MCP Installation
+
+Confirm that the requested package version is available before changing every
+participating client's configuration. This release requires a new empty data
+directory when replacing a 0.5.x installation. Preserve the previous data,
+backups and private WalletConnect store; they are not converted or imported.
+Configure endpoints and read context as needed and connect through a new card.
+Use the same new data directory and review port in every participating client.
+Fully quit the participating apps, update
+the installed package or configured version, then reopen them and check
+`read.get_server_status` in each client. The package name, version and server
+name must match the intended installation. Updating the package does not
+replace a backend that is already running.
+
+A compatible update that retains the current database structure can use existing
+data. Incompatible databases and backups are rejected without migration;
+see [Local Database Architecture](LOCAL_DB_ARCHITECTURE.md#current-format-and-backups).
+Do not reset data or resend a transaction as an update step. Coordinate a safe
+restart if a transaction request is still in progress.
+
+### Switching from a Different Package
+
+Use these steps when selecting Sui MCP instead of a different package.
+Confirm the requested version is available before changing your client configuration.
 Sui MCP starts with a new database and private WalletConnect store in its own
 data directory. It does not discover, read, import or convert a previous
 package's database or backup. Existing connections, saved cards, transaction
@@ -189,13 +223,13 @@ are unaffected and must never be resubmitted as an installation step.
 
 Fully quit every app using the service and wait for its shared backend to exit
 before starting the new package. A client using a different service identity,
-API version or data directory is refused while that backend owns the port.
+package version or data directory is refused while that backend owns the port.
 If a transaction request is in progress, inspect its state and coordinate a safe
 restart first. A previous wallet pairing can remain in the wallet app; remove
 an unwanted pairing there rather than assuming new local storage disconnected it.
 
 Replace the old registration instead of adding a second one. Use exactly
-`sui-mcp` for the registration name and select `@zktx.io/sui-mcp@0.5.0` in its
+`sui-mcp` for the registration name and select `@zktx.io/sui-mcp@0.6.0` in its
 command arguments. Do not append an environment label, version or numeric
 suffix. Remove obsolete runtime environment overrides. If you set
 `SUI_MCP_DATA_DIR`, choose a new empty directory; never point it at another
@@ -435,7 +469,7 @@ After the MCP server is connected:
    - `read.summarize_sui_function_activity_scan` for sent transactions that called one full function target.
    If the selected tool accepts `account` and the user supplied a Sui address, pass it instead of starting wallet connection. DeepBook account inventory has no explicit address input.
 8. For local review evidence, use `read.list_review_activity`, `read.summarize_review_funnel`, or `read.get_review_session_detail`.
-9. For local endpoint settings or local data controls, ask your AI client to call `settings.create_local_settings_session`, then open the returned settings URL in the same machine's system browser. Setting changes apply after restart.
+9. For local endpoint settings or local data controls, ask your AI client to call `settings.create_local_settings_session`, then use the internal card controls. Setting changes apply after restart.
 
 ## Wallet Connection Boundary
 
@@ -459,14 +493,20 @@ connections are saved, the Connect card lists them for target-specific
 Disconnect confirmation. Account use and signing remain blocked until the
 conflict is resolved. No connection is silently chosen or remotely removed.
 
-There is no Restart wallet service button in Connect or Settings. If the
-connection service is unavailable or a disconnection remains unresponsive,
-fully quit all apps using Sui MCP and reopen them. Closing only a window
-or a client that does not own the shared backend is insufficient. Another open
-client may take ownership. Verify that the old backend and SDK child exited
-and that the new service becomes available; editing a config file is not a
-runtime restart. A process that survives app exit needs separate diagnosis,
-not a claim that recovery succeeded.
+Connection service restart belongs to Settings, not Connect. If an operation
+is unresponsive or the service is unavailable, ask to open Settings and use
+Troubleshooting. Inspect the affected run/requests and confirm Restart
+connection service. The backend waits for its old SDK child to exit and a new
+run to become ready; it does not restart the parent or another app. If startup
+itself remains pending, open a new Settings card for another explicit restart;
+the prior pending startup is recorded as superseded. A known failure stays a
+failure. No read, timeout or reopened frame initiates another restart.
+
+If Settings or the parent service cannot be reached, fully quit all apps using
+Sui MCP, then reopen them. Closing a peer or window can leave the owner alive.
+Use this full app restart also for stored endpoint/configuration changes or an
+installation update. A process surviving app exit needs diagnosis; editing a
+config file is not evidence of a runtime restart.
 
 Restarting does not cancel a transaction on Sui or confirm remote disconnection.
 Check retained connections in your wallet app. Saved results and the known
@@ -474,10 +514,11 @@ digests of submitted transactions remain available after restart. An
 unsubmitted approval needs a fresh review and explicit wallet approval; nothing
 is resent automatically. Normal initialization is not a failure warning.
 
-The shared backend uses internal API version 7. All clients sharing a data
-folder must use a compatible installation. Fully quit the old clients before
+All clients sharing a data folder must use the same package release. Private
+parent/child and peer authentication bind that package identity; there is no
+separate internal API or database version counter. Fully quit the old clients before
 starting the same updated installation; an incompatible owner is refused.
-Product schema 9 and private SDK format 1 are retained.
+The runtime checks the current product and private SDK storage structures directly; neither has a separate numeric version.
 
 Review requires an explicit card action and individual wallet approval. The
 backend uses Sui sign-only requests, verifies returned bytes/digest/signer and
@@ -493,7 +534,7 @@ A card accepts one read selection. Moving between chats or recreating its frame
 
 ## Local data format
 
-Start this runtime with an empty `SUI_MCP_DATA_DIR` or a database already in its current format. A mismatched existing database is refused before writes. There is no older DB or backup migration. The current database and public backup use schema 9; a development checkout replacing schema 8 needs a new empty data folder, preserving the previous folder. Older local records, known/active accounts and stored endpoints are not inherited; set the needed account context and endpoints again. Existing files are left in place, and environment overrides keep their existing precedence. See [Local DB Architecture](LOCAL_DB_ARCHITECTURE.md) for the current format, backup scope and card-result retention. Card results do not expire with the input period and can increase DB size. Reset/import removes them along with the affected local data; it is not a card-only space cleanup operation.
+Start this runtime with an empty `SUI_MCP_DATA_DIR` or a database already in its current format. A mismatched existing database is refused before writes. There is no older DB or backup migration. A checkout with different table, constraint or field definitions needs a new empty data folder, preserving the previous folder. Databases and backups do not carry a separate numeric schema version. Older local records, known/active accounts and stored endpoints are not inherited; set the needed account context and endpoints again. Existing files are left in place, and environment overrides keep their existing precedence. See [Local DB Architecture](LOCAL_DB_ARCHITECTURE.md) for the current format, backup scope and card-result retention. Card results do not expire with the input period and can increase DB size. Reset/import removes them along with the affected local data; it is not a card-only space cleanup operation.
 
 ## Local Settings
 
@@ -502,21 +543,40 @@ Beginner setup uses the built-in Sui mainnet gRPC and GraphQL endpoints. You do
 To inspect settings or change stored endpoints, ask your AI client:
 
 - "Show my Sui MCP local settings."
-- "Open my Sui MCP local settings page."
-
-The settings page lets the user:
-
-- save custom Sui gRPC and GraphQL endpoints;
-- restore the default Sui gRPC and GraphQL URLs;
-- clear active account read context;
-- reset logical local data;
-- export local data;
-- import replace-only local data.
+- "Open my Sui MCP Settings card."
+
+Settings groups Address for viewing assets, Local records, Troubleshooting and
+Advanced settings. Each card lets you make one change and keeps its result:
+
+- view or clear the default address used when checking assets;
+- back up records saved on this computer;
+- restore a Sui MCP backup, replacing the current local records and settings;
+- delete local records and saved settings;
+- check or restart the wallet connection service;
+- select a custom Sui network address or return to a built-in default.
+
+Local records include saved addresses, reviews, transaction and activity records,
+and Sui network settings. Restoring them does not reconnect your wallet or restore
+wallet approvals. Transactions on Sui are not cancelled by a restore or reset.
+Internal request IDs and file hashes appear in Details. Advanced settings names
+the Sui node connection as gRPC and the activity-data connection as GraphQL.
+Network addresses set in the app launch configuration take priority over values
+saved in Settings; remove the relevant launch setting before restarting to use
+the saved value.
 
 Settings validation rules:
 
-- Import preview validates the backup shape without contacting the imported endpoint.
-- Import accepts only the current backup format and schema identifier. Required settings and activity fields must be present; missing fields are not filled from defaults.
+- Choose a backup file no larger than 16 MiB. The card shows file transfer and Checking backup while Sui MCP checks it automatically, then shows Restore available or Cannot restore with the reason. A file still being received is not a failed backup. These initial checks do not contact network addresses from the backup.
+- Restore local records is your final confirmation. Sui MCP then checks the backup's network addresses before changing any data. Back from the confirmation clears that preparation and keeps a valid complete file. Returning from an input page to a section and using Resume preserves the selection and file. A change to local records requires a fresh check. Check backup again checks that same file when needed; Change backup file lets you choose another. Choosing or checking a file never restores it automatically.
+- If Sui MCP rejects the backup's format or mainnet network settings, use Change backup file. Back and Check backup again cannot clear that rejection. If a network service is temporarily unreachable, you can check the backup again and make a new restore confirmation; network access is still checked before any records change.
+- If another Settings operation or an unsettled wallet request temporarily blocks the change, Check status reads the same card again without repeating its action.
+- Restoring or resetting can delete records whose transaction results were not confirmed and cannot cancel a transaction on Sui. It remains blocked while a wallet/transaction response is pending or the initial transaction-result waiting period has not ended, including after automatic result checks are stopped.
+- Choose Download backup in Local records once. Sui MCP prepares and checks the backup internally, then asks the app to save it. There is no separate Create backup step. For supported downloads, the app controls the destination and Sui MCP keeps no permanent extra copy; Suggested file name is not a confirmed save path.
+- If the download function explicitly reports that it is unsupported, the same backup is saved in `<SUI_MCP_DATA_DIR>/backups/` instead. Backup saved shows its actual Folder and File name. This file remains after restarting or replacing local data; temporary cleanup does not delete it. This choice depends on the function response, not the app name. Other errors do not silently change the destination.
+- If an earlier attempt may already have saved a copy, Save a local copy asks for that decision explicitly. Retry save is available only after a confirmed local save failure with no published file. While saving or checking an uncertain result, Check status checks the same request without creating another file.
+- An accepted download request does not prove that the file was saved. If delivery fails or cannot be confirmed, Retry download sends the same snapshot while its thirty-minute transfer period remains open. An unconfirmed earlier request may already have saved a copy. Cancel download stops further transfer and cleans the temporary snapshot; it does not close a save dialog or delete a saved file. Reopening a card never starts another download automatically.
+- The thirty-minute transfer period starts when the snapshot is ready and is not extended by reads or retries. App acknowledgment, cancellation, expiry, server restart or local-data replacement ends private retention. A local save admitted before the deadline finishes its file work and records the result before cleanup; a restart can verify an already published file but never create a missing one. If temporary cleanup cannot be confirmed, Check status checks that same request without creating or downloading another backup. Existing saved local backup files are left intact. A backup larger than the 16 MiB restore limit is identified as such and is not silently truncated.
+- Import accepts only the current backup format and required field structure. Required settings and activity fields must be present; missing fields are not filled from defaults.
 - Current-format backups can contain `function_scan` provenance. Unsupported formats and scan-kind values are rejected rather than partially imported.
 - Endpoint chain-identifier verification runs only when the user confirms the replace-only import.
 - A custom gRPC endpoint must be an `http` or `https` URL with an explicit port and no credentials, path, query string, or fragment.
@@ -540,7 +600,7 @@ Use this only when you need a one-run override or need to recover from a stored
 
 After the MCP server starts with the override:
 
-1. Open the local settings page.
+1. Open the Settings card.
 2. Restore the default endpoint or save a new endpoint.
 3. Remove the environment override.
 4. Restart the client.
@@ -577,7 +637,7 @@ The port is not a browser-wallet authorization origin.
 `npm run release:check` checks synchronized release metadata, typechecks, tests,
 builds, and verifies the actual npm tarball and bundled licenses. It installs the
 tarball in a temporary directory and runs that installed binary to check MCP
-initialization, tools, document/card resources, the local Settings page and
+initialization, tools, document/card resources, the internal Settings card and
 assets, and the isolated SDK child. It confirms that Connect rejects restart
 input, manage does not pair merely by opening, and the SDK keeps its exclusive
 storage lease until shutdown. Runtime startup requires reachable Sui mainnet endpoints; a startup
@@ -696,7 +756,7 @@ cannot erase an earlier fatal or signal exit. SDK service unavailability is a
 separate condition and does not by itself shut down the parent read service.
 
 - Do not set `SUI_RPC_URL`; this runtime intentionally uses Sui gRPC and rejects Sui JSON-RPC config.
-- If a stored custom endpoint fails, temporarily start with `SUI_GRPC_URL`, open the local settings page, restore the default Sui gRPC URL or save a new endpoint, remove the override, and restart.
+- If a stored custom endpoint fails, temporarily start with `SUI_GRPC_URL`, open the Settings card, restore the default Sui gRPC URL or save a new endpoint, remove the override, and restart.
 - If an environment override is present, confirm it has scheme, host, and explicit port only.
 - If the startup chain identifier guard fails, use a Sui mainnet gRPC endpoint. If a Sui activity tool fails its GraphQL chain identifier guard, use a Sui mainnet GraphQL endpoint.
 
@@ -716,7 +776,7 @@ If the user supplied a specific Sui address for `read.summarize_wallet_assets` o
 
 A 404 means the requested package or version could not be retrieved from the
 selected registry. Confirm the exact name and version, for example with
-`npm view @zktx.io/sui-mcp@0.5.0 version --registry=https://registry.npmjs.org`.
+`npm view @zktx.io/sui-mcp@0.6.0 version --registry=https://registry.npmjs.org`.
 A new version may not have been published or become visible yet; a mistyped name
 or an alternate/private registry can also explain the response. Check the
 publication result and registry configuration before retrying. Do not assume

package/docs/MCP_TOOLS.md

@@ -8,6 +8,16 @@ 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.
+
 ## Read-Only Tools
 
 | Tool | Status | Purpose |
@@ -155,7 +165,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 +1081,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 +1104,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 +1140,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 +1236,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.