@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

package/doc/runbooks/runtime-skill-client.md

@@ -0,0 +1,155 @@
+# Call paid services from a Skill
+
+Audience: Skill authors and local Agent integrators. Use the common per-call
+Runtime contract; no process-wide Skill selection or business adapter is needed.
+See [service contract](../reference/multi-service-runtime.md). Actual DeepSeek
+Harness/Claude Code discovery and execution remain separate acceptance.
+
+## Local setup
+
+Complete User/Wallet setup. The guide saves runtime/connection.json in the private
+User data directory: loopback Runtime URL, caller token file path and installed
+User module location. The token itself never enters a package or model message.
+The default is $HOME/.local/share/agentpay/user; set AGENTPAY_USER_DATA_DIR for a
+custom directory. Keep User installed at its recorded location.
+
+Existing developer installations can save discovery from the User repository:
+
+```bash
+node scripts/configure-runtime-client.mjs "$HOME/.local/share/agentpay/user" http://127.0.0.1:6490
+```
+
+This writes local connection metadata only; it does not authorize spending.
+
+## Author package
+
+Download Market's Skill template. Fill package identity, copy registered service
+references into services.main and additional aliases, and implement business input
+validation and result interpretation in the wrapper. Keep payment/credentials in
+the installed shared User client. The template text parameter is only an example.
+
+```bash
+node scripts/call-runtime.mjs --check
+node scripts/call-runtime.mjs --invoke '{"text":"hello"}' --units 1
+node scripts/call-runtime.mjs --service second --invoke '{"text":"hello"}'
+```
+
+--check verifies local interface/reference matching; it does not reserve a Quote or
+establish purchase readiness. --units is a maximum, not a price or actual usage.
+Provider business output is application-owned. Verify delivery using the agreed
+evidence contract; do not invent a new output shape or hashing requirement.
+
+## Recovery and explicit new purchase
+
+Retry the same input normally. Matching calls recover the same request or reuse
+saved verified output. Use --force only for an explicitly intended additional
+purchase. It never bypasses Policy. Diagnostic --resume <request-id> selects an
+existing request when several unfinished forced calls make automatic selection
+ambiguous. Preserve private checkpoints and invocation history. A lock left during
+local request selection fails closed for inspection; do not delete purchase state
+or automatically force a new request to work around it.
+
+## Release and acceptance
+
+The installed User and Wallet dependencies must match their shipped lockfiles.
+Preserve older request identities during upgrades; never reinterpret their routing
+or create replacement purchases. The official paid connectivity suite remains the
+installation acceptance test. Other business payloads are tested with maintained
+controlled fixtures, not third-party Skills.
+
+Runtime starts with retained older requests and performs read-only self-checks.
+Unsupported or unknown original scopes remain visible for review; they do not
+become eligible for replacement purchases. Use `./run orders list` and the suggested
+`details`, `status` or `archive` actions. Archiving preserves the request and does
+not establish its financial state. See [original Order recovery](../reference/original-order-recovery.md).
+
+## Optional result files
+
+Runtime preserves received structured results; a URL in a result is not a saved
+file. Skills can explicitly cache selected files through the installed client.
+Use the [file-cache interface](../reference/result-file-cache.md) for API examples,
+limits and digest semantics. Users inspect copies with `./run orders files ORDER_ID`.
+File operations never start a new purchase or confirm receipt.
+
+## Transport failures
+
+`RUNTIME_TIMEOUT` means the response deadline elapsed; an Order may still be running.
+`RUNTIME_RESPONSE_TOO_LARGE` means the bounded JSON response was exceeded.
+`RUNTIME_RESPONSE_INVALID` means unreadable JSON or failed delivery verification.
+`RUNTIME_UNAVAILABLE` means communication could not finish. Check local status/logs
+as directed and resume the original request. None of these proves non-payment or
+allows replacing a purchase. Binary files use the separate explicit file interface.
+
+Provider profiles may use HTTP or HTTPS. Existing requests retain their exact
+registered endpoint/profile. HTTP provides no transport confidentiality; use HTTPS
+when the service requires it. This does not change local Runtime loopback or
+Market/Settlement credential requirements, or package-download validation.
+
+## File inputs and outputs
+
+The current installed client provides `skillClientCapabilities` including
+`input-snapshots-v1`. The official Agent template distributed by Market checks it before running. Upgrade User
+and restart Runtime together; older Runtime versions lack original-request recovery.
+
+The optional hooks are:
+
+```js
+await runSkill({
+  service,
+  validateRequest: validateYourBusinessInput,
+  inputFiles(input) {
+    return [{fileKey: 'document', sourcePath: input.absoluteFilePath,
+             filename: 'document.pdf'}];
+  },
+  async prepareRequest({request, files, requestId}) {
+    // Implement YOUR Provider's upload/reference contract using files[].localPath.
+    // Use requestId/fileKey to make preparatory uploads idempotent where supported.
+    // Return bounded business JSON, not an embedded large binary or a local path
+    // that the remote Provider cannot access. Never create/pay Orders here.
+    return prepareYourProviderInput(request, files, requestId);
+  },
+  outputFiles(output) {
+    return [{fileKey: 'report', url: output.reportUrl, filename: 'report.pdf'}];
+  }
+});
+```
+
+These illustrative business functions are author code, not built-in APIs. JSON-only
+Skills omit the hooks. Input declarations accept either an absolute `sourcePath` or
+an HTTP/HTTPS `url`, plus unique `fileKey`, optional `filename` and SHA-256 `sha256`.
+At most 20 declarations are allowed; local resource limits also apply. No automatic
+path/URL discovery, archive extraction or format restriction is added.
+
+The common client saves declarations, snapshots and the final adapted request before
+paid invocation. Retrying after source changes uses original copies. `--resume` never
+reinterprets a submitted request through newly edited business preparation code.
+Use `--force` only for an intentional additional purchase/new input snapshot.
+
+Output download failure preserves the verified result and request ID. The command
+returns nonzero with `ok: true` delivery and `fileCache.state: incomplete`; retry the
+same call to finish downloading, not `--force`. Saved files are optional local copies,
+not a new delivery-proof format. View/manage copies with `./run cache`.
+
+Once Runtime verifies durable delivery, original inputs become eligible for confirmed
+cleanup. If release cannot be checked, they remain protected; retry the original call.
+A saved Runtime result can restore missing client results even after input cleanup.
+
+Runtime port changes do not change the request. A possibly submitted request requires
+matching Runtime history and atomic existing-only continuation. Missing history stops
+with `ORIGINAL_REQUEST_NOT_FOUND`: preserve local files and review with support; do
+not delete checkpoints, change IDs or force another purchase to recover it.
+
+## Service and package addresses
+
+Service references must conform to the existing Protocol v1 profile: the challenged
+MCP endpoint and payment endpoint have the canonical service-specific suffixes.
+An allowed deployment prefix is supported. Do not derive or change these identities
+inside a Skill to bypass validation. These rules apply to all service businesses.
+
+The ZIP download URL is independent: use the publisher's explicit full URL plus a
+trusted expected SHA-256, or Market's metadata/download link. The direct installer
+does not derive the ZIP path from `/invoke` and does not require a `main` service
+alias. Multiple service aliases may point to independently registered services.
+Generic `--preview`/`--execute` install without global selection; official test
+selection remains scoped to the maintained connectivity suite. Transport safety,
+archive structure, digest and service-profile validation still apply.

package/doc/runbooks/safe-owner-web.md

@@ -0,0 +1,104 @@
+# Approve Safe operations in your browser
+
+The external owner signer now opens a temporary local authorization website during
+setup, Policy renewal and Policy revocation. It requires an injected browser owner
+wallet (window.ethereum) and a validated Safe version: currently 1.3.0 or 1.4.1.
+Other Safe versions stop explicitly. WalletConnect/QR is not implemented.
+
+## Local computer
+
+The terminal prints a loopback address and attempts to open the system browser
+when a desktop environment is detected. Open that address manually if needed.
+Review the network, Safe, operation and limits. Connect a Safe owner wallet on the
+matching network. The page cannot access your local Wallet IPC or Session Key.
+
+For a single-owner Safe, choose the named operation button and confirm in the owner wallet.
+For a multisig Safe, other owners can open the same plan and use Approve operation.
+Approvals use Safe approveHash transactions and require network fees; approvals
+remain valid for that transaction hash. Once enough owners are available, execute.
+The connected executing owner can count toward the threshold without a separate
+approveHash transaction. Other owners' approvals are read from the chain, so no
+hosted transaction service or shared signature clipboard is required.
+
+Operations are sequential. For example, enable the Module, check approvals again,
+then create the Policy. The page checks completed effects before offering execution.
+A changed Safe nonce pauses the saved operation for reconciliation. Approval alone
+does not mean execution; a successful Safe ExecutionSuccess and chain state are
+required. Expired or conflicting Policy drafts stop.
+
+Return to the terminal and enter check. The local process independently verifies
+chain effects, then continues binding. Enter q to pause; the original draft remains.
+
+## Server without a desktop
+
+The local service still listens only on 127.0.0.1. The terminal prints its actual
+port and an SSH command such as:
+
+```sh
+ssh -N -L PORT:127.0.0.1:PORT USER@SERVER
+```
+
+Run that on your own computer, replacing the placeholders with the printed port and
+your server login. Open the terminal's printed URL in your local browser with the
+owner wallet extension. Forward the same port; Host validation deliberately rejects
+other origins. Do not expose this temporary service publicly.
+
+## Portable fallback
+
+Enter export in the terminal. Copy the entire printed directory to a trusted computer.
+It contains only the public fixed plan, HTML, bundled ethers/browser code and a
+minimal Node server. It does not include RPC credentials, local session tokens or
+Wallet keys. From that directory run:
+
+```sh
+node serve.mjs
+```
+
+Open the address it prints. Alternatively:
+
+```sh
+python3 -m http.server 8765 --bind 127.0.0.1
+```
+
+Then open http://127.0.0.1:8765. Direct file:// opening is not a supported wallet
+connection method. Keep the files while approval is pending, then remove that
+exported directory. Each export is separate and preserved until you remove it.
+The static page uses the browser wallet's network provider, not the original
+computer's local API. That wallet must have access to the correct network RPC.
+For Anvil, configure your browser wallet with the arranged RPC forwarding.
+
+Return to the original terminal and enter check (or resume the original command).
+A copied page cannot bind the original computer's Wallet by itself.
+
+## Evidence limits
+
+Controlled HTTP, export and mocked browser/contract tests pass. Actual browser
+extension signatures, desktop launch, SSH forwarding, multi-owner chain execution
+and transaction fees remain participant acceptance. No real-network authorization
+has been performed by implementing this page.
+
+## Recovery after interruption
+
+The local guide saves pending public transaction references and checks their receipts
+before another submission. Reopen the original guide and connect the owner wallet.
+If another Safe transaction used the nonce, check approvals again and review the new
+nonce. Prior approvals do not carry over. Keep exported pages in the same trusted
+browser; portable mode uses browser storage rather than the original machine's journal.
+Do not clear storage or switch browsers while a transaction is pending. Verify its
+original transaction and effects first. Expiry checks use chain time.
+
+## Renewal interaction
+
+Renewal reuses the bound Safe. Deployment updates label the default budget as remaining
+allowance and preserve the original expiry when its default is retained. One webpage
+runs the fixed revoke/optional Module enable/create plan. Connect once, then confirm
+each named operation in the owner wallet. The page verifies each effect before showing
+the next action. Return to the terminal and enter `check` once after all operations.
+The independent terminal/Wallet checks still gate binding. Type `help` in the terminal
+for SSH forwarding instructions; `export` provides the portable fallback.
+
+The complete renewal plan stays fixed when you pause and reopen it; completed
+operations are skipped after chain checks. Revoking the old permission alone does
+not prevent returning to edit the new draft. Once creation approval/execution has
+been prepared for the wallet, the draft is protected against changes; verify the
+original operation instead. Exporting the portable page also protects its draft.

package/doc/runbooks/safe-policy-migration.md

@@ -0,0 +1,36 @@
+# Deployment migration and advanced Policy tools
+
+For normal deployment changes, use `./run setup` or `./run policy renew`.
+The guide explains the mismatch, preserves your Safe and Session Key, and prepares
+owner-approved replacement permission. Follow
+[deployment authorization update](deployment-authorization-update.md) for supported
+changes, defaults, signing and recovery. Ordinary software repair or a newly
+qualified service does not by itself require a new Policy.
+
+The external signer serves the [browser approval page](safe-owner-web.md), including
+on Anvil. Signing support is implemented; public-network, multisig and complete
+interruption acceptance remain separate gates. Never use an unlocked test account
+as a substitute for a real owner's approval.
+
+## Advanced migration script
+
+`scripts/migrate-safe-policy.mjs` exposes `preview`, `prepare`, `status`, `export`,
+`complete`, `refresh` and `cancel` for an explicitly managed migration. It is a
+low-level tool, not the normal installation or renewal entry. Inspect its usage
+before supplying paths or arguments.
+
+Review the target Safe, network, token, delegate, Registry, budget, expiry and
+Module/Factory. `prepare` saves recoverable migration state and blocks new signing.
+The owner revokes the old Policy before creating its replacement; `export` provides
+the next operation. `complete` switches the local binding only after Wallet checks
+actual chain state. `authorize-test` is restricted to private Anvil test use.
+
+If interrupted, inspect `status` and resume the original migration. Do not remove
+local files, generate a new key or create a replacement payment. Confirmed on-chain
+revocation cannot be reversed by restoring an old local file. Cancel only while
+its state and chain checks permit it.
+
+After completion, verify the binding, restart/unlock services and check readiness.
+Migration does not purchase a service, and the platform need not wait for every
+user to migrate before resuming new Orders. Original Orders retain their original
+rules and independently verified authorization scopes.

package/doc/runbooks/safe-policy-setup.md

@@ -0,0 +1,52 @@
+# First spending authorization
+
+Start with `./run install --market YOUR_MARKET_ORIGIN`, or return with `./run setup`.
+Follow [installation](user-onboarding.md) for prerequisites. Wallet holds an encrypted
+Session Key locally; the Safe enforces the approved spending limits. Market login or
+Wallet connection does not create spending permission.
+
+## What you review
+
+1. Initialize Wallet and keep its encrypted Session Key and password securely.
+   Neither is your Safe owner's private key. Never give keys to a Skill or platform.
+2. Use a Safe on the configured network. Check the Safe address, owners, signature
+   threshold, token and balance. An ordinary owner address is not a Safe address.
+3. Choose a total budget, per-purchase limit and expiry. Eligible purchases can use
+   the full budget without another owner signature. Registry qualification verifies
+   identity/control, not service quality. New qualified services satisfying the rule
+   do not require a new Policy.
+4. Review the exact draft and operation list. `details` shows deployment and identity;
+   `back` edits unsubmitted terms. Editing a draft does not grant permission.
+5. Approve the operations with the selected owner signer. First setup may require
+   enabling the Module before creating the Policy. With the default external signer,
+   use the [local browser page](safe-owner-web.md), then return and enter `check`.
+6. Wallet independently verifies chain state before binding. Start/unlock local
+   services and, if desired, confirm the cost of the official payment test.
+
+If restoring an existing authorization, use [Wallet restoration](wallet-identity.md)
+with the original key and Policy. Do not create a replacement purchase to recover
+an interrupted Order.
+
+## Signer and evidence boundaries
+
+Signer selection is explicit. The external signer also works on Anvil; a private
+chain ID does not automatically select a test account. The guarded Anvil adapter is
+only for an explicitly selected, arranged single-owner test Safe. The advanced
+`authorize-existing-safe.mjs` test script is not the normal user entry.
+
+An owner approval or submitted transaction is not proof of successful execution.
+The guide checks chain effects and retains unfinished plans. Resume the same flow
+rather than deleting state. Multi-owner approval requires the Safe's actual threshold.
+The recorded private single-owner journey does not establish public-network,
+multisig or real-funds readiness. Safe creation is not performed by this guide.
+
+## Daily use and recovery
+
+Wallet starts locked after restart; `./run wallet unlock` unlocks it locally.
+Locking it does not revoke on-chain permission. Use [renewal/revocation](policy-renewal.md)
+or [emergency payment stop](emergency-payment-stop.md) for owner-authorized changes.
+
+Insufficient funds, exhausted budgets, expiry and unavailable services do not allow
+silent increases in authority. Interrupted requests keep their original identity.
+For a changed deployment, use [authorization update](deployment-authorization-update.md)
+without reinitializing the Session Key.

package/doc/runbooks/terminal-authorization-preview.md

@@ -0,0 +1,38 @@
+# Terminal authorization preview
+
+Use Linux with compatible Node installed. Prompts are English. This page covers
+the demo/preview entries only; ordinary setup supports external owner signing.
+macOS startup and public-network acceptance remain separate release gates.
+
+## Choose an entry
+
+For the complete four-stage UI simulation, run from User:
+
+```bash
+node scripts/user-setup.mjs --demo
+```
+
+Choose `continue` once. The demo advances through Wallet initialization, spending permission, official Skill preparation and paid test. It asks for two confirmations: spending permission and test payment. Official Skill preparation and acknowledgement of verified test receipt are simulated automatically. Hidden practice-secret entry and spending-limit fields remain. It never creates keys, connects to a chain, installs files or pays. Simulation progress survives a pause in the same process, not process exit. It ends after the test and points to Market.
+
+To preview only the spending parameters:
+
+```bash
+node scripts/guide-policy.mjs --demo
+```
+
+Enter the Safe (or press Enter for the fictional example), total budget, per-payment limit and duration in whole days. `details` shows deployment information; `create` at the Safe prompt explains where to obtain the correct Safe. One final confirmation completes this read-only preview, without granting permission. Expiry is displayed in the local timezone. No inputs are persisted by this standalone preview.
+
+For actual read-only deployment checks:
+
+```bash
+node scripts/guide-policy.mjs PUBLIC_DEPLOYMENT_JSON WALLET_DELEGATE
+```
+
+The public config supplies `chainId`, `rpcUrl`, `module`, `token`, `factory`, `registry`, `tokenDecimals` and `source`; optional `tokenSymbol` labels amounts. Use trusted deployment data and the public Wallet execution address. The command checks chain identity, contract presence, Safe owners/threshold, Module and Policy state. It cannot sign or bind. Contract presence alone is not proof of trusted semantics. Never enter an owner private key, Session Key or unlock secret into these fields.
+
+## Actual setup and owner signing
+
+This guide describes the explicit demo/preview path only. Ordinary setup supports external-owner approval; see [browser signing](safe-owner-web.md). Private Anvil can use an explicitly selected guarded test signer.
+
+On a supported real network the owner must execute the reviewed Safe operations: enable the trusted AgentPay Module if absent, then create the bounded Policy. The application must verify actual chain results and the Safe's signature threshold; a user clicking confirm is not chain evidence. Reducing guide confirmations does not merge contract operations or imply a real-wallet batch-signing implementation. [Safe authorization](safe-policy-setup.md) explains the authority and release boundaries. The demo does not open an owner-signing browser page. Actual setup attempts to
+open its local approval page on a desktop and always prints the address.

package/doc/runbooks/unlock-wallet.md

@@ -0,0 +1,68 @@
+# Lock and unlock Wallet from User
+
+From the User repository, run:
+
+```bash
+./run wallet unlock
+```
+
+Enter the Wallet unlock secret in the terminal. Input is hidden. The Wallet service
+must already be running; this command does not start services, create a key or change
+spending permission. Runtime itself does not need unlocking.
+
+Install and successful local initialization remember your User data directory in
+`.agentpay-install/state.json` beside the User and Wallet repositories. Lock/unlock
+use that location automatically. If no installation location exists, they use
+`$HOME/.local/share/agentpay/user`. To temporarily select another:
+
+```bash
+./run wallet unlock '/your/User data directory'
+```
+
+Selection order: explicit argument, `AGENTPAY_USER_DATA_DIR`, remembered installation,
+standard default. A one-off lock/unlock argument does not change the saved location.
+Install also reuses the saved location, so retrying Install does not silently switch
+back to the standard directory. The record contains only the path and existing
+installer checkpoints, never a password. Do not delete this file to recover a Wallet.
+Pass the User data directory, not its `wallet` subdirectory. Keep the User and Wallet
+repositories side by side and complete installation/build first.
+
+After successful unlock, resume the original Skill request. Do not create a replacement
+payment to work around an interrupted request. Existing Policy limits, expiry and
+revocation still apply. Unlock success alone does not prove purchase readiness.
+
+Passwords must not appear in command arguments, environment variables or files.
+The command inherits your interactive terminal; Wallet owns hidden input and its
+existing authenticated local administration call. Runtime does not receive the secret.
+
+## Restart support status
+
+Linux automatic startup and best-effort desktop reminders now have a separate
+[management command](local-autostart.md). The terminal installer now offers to enable them after the connectivity test;
+real desktop/login/reboot acceptance remains pending. No saved auto-unlock material.
+
+## Lock Wallet
+
+From the User repository:
+
+```bash
+./run wallet lock
+```
+
+Use the same optional User directory or `AGENTPAY_USER_DATA_DIR` as unlock. Lock
+clears the decrypted signing key from Wallet memory. It does not revoke the on-chain
+Policy, cancel Orders or reverse already signed/submitted payments.
+
+Both commands check local setup, ownership/permissions and socket presence first.
+A leftover socket still may not have a running process; a failed connection remains
+an error, not proof that the password is wrong. Wallet public results are rendered
+as short messages rather than raw JSON. Unknown failures retain a safe error code.
+
+## Check before unlocking
+
+Run `node scripts/status.mjs` to inspect the running local Wallet without a password.
+The same remembered directory and optional override apply. Lock/unlock/status now
+probe the socket connection, not only the socket file. A stale file reports that
+Wallet is not running before asking for a secret; no socket or data is deleted.
+A successful connection does not by itself prove authenticated IPC works; later
+Wallet errors remain visible as concise results with a safe error code.

package/doc/runbooks/user-onboarding.md

@@ -0,0 +1,87 @@
+# Install and use AgentPay User
+
+Use Linux with Node.js 22.22.3 or newer and npm. Have your platform's Market
+address and a Safe on its supported network, controlled by your owner wallet.
+AgentPay does not need your owner private key. macOS startup remains unverified.
+
+## 1. Install program files
+
+Install User with `npm install --global @c4roa0/agentpay-user@0.3.0`.
+Its reviewed Wallet dependency is included. Source/ZIP alternatives are in
+[README](../../README.md). No separate Wallet checkout or build is needed.
+Keep private data outside the program folder.
+
+## 2. Configure
+
+```sh
+agentpay install --market https://YOUR_MARKET_ORIGIN
+```
+
+Use your platform's actual HTTPS origin; private rehearsals may use loopback HTTP.
+Without `npm link`, run `./run install --market ...` from User instead. For a ZIP
+without executable permissions use `sh run`; `AGENTPAY_NODE` can select Node.
+
+Install verifies installed dependencies and downloads public deployment
+settings, then continues into local setup. Read each prompt: setup prepares an
+encrypted Session Key, spending limits, owner approval and local services. Existing
+keys, histories and saved drafts are retained on retry. Approve only the intended
+network, Safe, amounts and expiry in your owner wallet. See
+[browser approval](safe-owner-web.md).
+
+The official connectivity test asks for its maximum price before making a paid
+Order. It uses a reviewed package digest pinned in User. Download/install alone
+must not be mistaken for spending permission or payment.
+
+## Resume and operate
+
+Run the same Install command if preparation failed, or `agentpay setup` to return to
+a prepared installation. Read its saved log when dependency preparation fails;
+do not delete Wallet state to bypass an error. Deployment changes are handled by
+[authorization update](deployment-authorization-update.md).
+
+```sh
+agentpay status
+agentpay wallet unlock
+agentpay market connect
+agentpay payment test
+```
+
+Runtime and Wallet run locally. On Linux, the guide can configure systemd user
+services. Wallet starts locked after a restart; [service commands](local-autostart.md)
+control startup and background operation. Keep the Node installation used by those
+service files available.
+
+The default data location is `$HOME/.local/share/agentpay/user`. Install also stores
+private preparation checkpoints/logs under `.agentpay-install/` beside the repositories.
+`agentpay wallet info` shows resolved identity and paths. Follow
+[backup and restore](wallet-identity.md) before replacing a computer or deleting data.
+
+## Private Anvil and other deployment settings
+
+Anvil uses the same authorization/payment code with explicit configuration. Select
+external-owner signing for browser-wallet testing; the guarded test signer is only
+for the arranged private rehearsal. Network ID alone does not authorize a test signer.
+
+If a rehearsal configuration publishes server loopback URLs, they refer to that
+server and need arranged SSH forwarding from another computer. Ask the operator
+for the endpoints in that configuration; there is no universal public port list.
+Supported public deployment configuration should expose reachable public APIs and
+RPC, while your Runtime remains local. See [deployment settings](../reference/public-deployment-settings.md).
+
+The [advanced private test guide](private-anvil-terminal-setup.md) is not a requirement
+for an ordinary public-network user. Source support is not real-network acceptance.
+
+## Edit an authorization draft
+
+Type `back` to revisit the previous editable question. Earlier answers are retained;
+dependent later choices may need review. `q` pauses with saved progress. An operation
+already submitted on-chain cannot be changed by editing a local draft: resume its
+original verification first.
+
+## Update or uninstall
+
+Download compatible User and Wallet code, then run `agentpay repair`. It applies local
+code and preserves keys and requests. See [updates](local-update.md).
+`agentpay uninstall` requires confirmation before removing local data. It does not
+revoke on-chain permission; use the appropriate owner-authorized revocation or
+[emergency stop](emergency-payment-stop.md) when needed.

package/doc/runbooks/wallet-identity.md

@@ -0,0 +1,59 @@
+# Find your Wallet identity and keep a backup
+
+From the User repository, run:
+
+```bash
+./run wallet info
+```
+
+This reads saved local information without starting/unlocking Wallet or contacting
+Market or the chain. It shows your Safe, network, Module, Policy ID, Wallet execution
+address, file locations and any saved Market connection. It does not confirm that
+an authorization is still valid or a saved website connection is still active.
+Missing or unsafe files are reported rather than replaced.
+
+Keep the encrypted Session Key file shown by the command in a secure backup, and
+keep its unlock password. A password alone cannot recover a lost Session Key.
+Also keep the Safe/network/Module/Policy ID. Back up the full User data directory
+to retain private results and transaction recovery records; protect it as sensitive
+data. Do not upload key files, passwords or data-directory backups to Market or
+send them to support. The command never displays their contents.
+
+On Market, your Wallet cards in Account and Settings provide a Policy ID row.
+Use the eye button to show the full value or the copy button to copy it. If browser
+clipboard access fails, the value is shown for manual copying. A Policy ID is a
+public identifier, not proof of control or spending authority.
+
+## Restore the original identity
+
+After installing compatible User and Wallet code, run from User:
+
+```bash
+./run wallet restore
+```
+
+If no key is present, choose your original encrypted Session Key backup and enter
+its password in Wallet's hidden prompt. For a raw original Session Key, type `key`
+and enter it only in the subsequent hidden Wallet prompt; choose a new local unlock
+password. Never paste a key into a file-path, website, command argument or support
+message. Encrypted backups must be private files owned by you (mode 0600); only the
+Wallet's bounded scrypt backup format is supported, not arbitrary wallet exports.
+
+Enter the original network, RPC, Module, Safe and Policy ID from your saved settings.
+Wallet checks the chain and original key. Review the identity and confirm to save
+its local binding. Existing limits, spent amount and expiry are unchanged. No
+owner signature, chain transaction or payment is made. An exhausted Policy may be
+restored for identity but cannot fund new purchases.
+
+Existing keys are preserved; another local Policy is never overwritten. A failed
+or interrupted bind can be retried with the same command and ID. Missing, revoked,
+expired or not-yet-active Policies do not become a fresh authorization automatically.
+Use `./run status` afterward, then `./run market connect` if you need website access.
+Restoration does not recover lost private results or missing transaction records.
+
+During initial setup, choose `restore` before creating a key. Before budget entry,
+press Enter for new spending permission or enter your original Policy ID. A saved
+restore draft stays a restore draft; failures cannot submit a new authorization.
+The official connectivity purchase is a separate, explicitly confirmed step.
+
+Source verification is complete; participant restoration acceptance is pending.