@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

package/doc/runbooks/commands.md

@@ -0,0 +1,89 @@
+# User command reference
+
+Use `agentpay` after installing the package or linking a source checkout with
+`npm link`. From a source folder, `./run` is the same entry; it uses Node on PATH
+or `AGENTPAY_NODE`.
+
+```sh
+agentpay help
+agentpay status
+```
+
+Top-level operations are `install --market URL`, `setup`, `repair [-f]`,
+`update [-f]`, `uninstall [--delete-data]` and `status`.
+Update checks npm and installs User with its pinned Wallet, then checks the official
+test Skill. It asks before changes unless `-f` is given. Source/npm-link installations
+use manual source updates followed by repair. Repair checks installed packages and
+confirms service interruption; `-f` skips that prompt only. Uninstall removes
+services and keeps data unless `--delete-data` is explicitly confirmed. Neither
+operation revokes on-chain permission.
+
+| Group | Operations |
+| --- | --- |
+| `wallet` | `info`, `unlock`, `lock`, `restore` |
+| `policy` | `info`, `renew`, `revoke` |
+| `service` | `start`, `stop`, `restart`, `autostart on/off`, `logs wallet/runtime` |
+| `market` | `connect [--market URL]` |
+| `orders` | `list`, `details ID`, `status ID`, `retrieve ID`, `case ID`, `archive ID`, `unarchive ID`, `files ID [remove KEY]` |
+| `cache` | `info`, `list`, `details ID`, `export ID PATH`, `clean`, `settings [KEY VALUE]` |
+| `payment` | `test` |
+
+A group without an action shows help; it never unlocks, revokes or changes files.
+Use `<group> help`, or `service autostart help`, to see focused instructions. Old
+flat commands such as `unlock`, `renew`, `connect-market`, `order ID details` are
+no longer accepted; use the grouped forms shown here.
+
+## Common tasks
+
+```sh
+agentpay service start
+agentpay wallet unlock
+agentpay status
+agentpay payment test
+
+agentpay policy renew
+agentpay policy revoke
+
+agentpay orders list
+agentpay orders details ORDER_ID
+agentpay orders retrieve ORDER_ID
+
+agentpay service autostart off
+agentpay service stop
+agentpay service logs runtime
+```
+
+`policy renew` covers expired renewal and active replacement. Revoking permission
+requires owner confirmation, and existing Orders retain their support rules.
+Service stop/Wallet lock do not revoke permission. Archive hides a local warning;
+it does not cancel or settle an Order. Retrieve requests the original result and
+never buys a replacement. Cache removal only removes local copies.
+
+Online Order operations require an unlocked Wallet. Start/unlock instructions and
+`status` guide you to the next action; setup renews expired authorization first.
+
+`status` includes a Policy section and expiry. “Within saved validity period” describes
+local saved validity, not a new chain/payment-readiness check. Revocation records
+are the last verification by this command suite. Unknown or conflicting scope is
+shown as unconfirmed; use `policy info` for saved details.
+
+`payment test` is the maintained end-to-end purchase check. In this release it uses
+the reviewed private-Anvil official Skill. It shows the current price and service
+time and asks before every new paid Order. If a test is unfinished, the same command
+resumes its saved request instead of starting another purchase. Completed test records
+are archived before a new one; the original onboarding test and Skill selection stay
+untouched. After verified delivery, Wallet acknowledges receipt, which can bring
+forward Provider payout.
+
+The command checks payment, delivery and receipt acknowledgement. Provider payout
+follows the Order’s settlement schedule; success does not claim final payout.
+
+
+### Order status sources
+
+`agentpay orders status ID` reads the current Settlement record through Wallet.
+It displays retrieval time and the record update time when available; it does not
+independently query the chain. If querying fails, the command labels the last
+local record and its saved check time. A successful query does not rewrite local
+history; Runtime maintains its own recovery observations. Use
+`agentpay orders details ID` for the saved local record.

package/doc/runbooks/deployment-authorization-update.md

@@ -0,0 +1,42 @@
+# Update spending permission after contract changes
+
+Run `./run setup` or `./run policy renew`. Both check the published deployment and
+explain a mismatch before owner transactions. An existing Market connection supplies
+the HTTPS (or private loopback) configuration source. Without one, the guide can
+use the public deployment file downloaded by installation. `status` labels this
+as downloaded evidence rather than a current platform check.
+
+Review updated permission, using `details` to inspect old/new contracts. Factory and
+Module changes are supported within the same network, Safe, execution key, token,
+Registry and RPC. Network/token/Registry moves require separate review. Removing a
+Module as an emergency stop is not silently undone by an ordinary renewal.
+
+An update defaults to unspent allowance. Exhausted allowance has no automatic new
+budget default. Remaining validity supplies the duration default; retaining that
+default preserves the original expiry. Editing budget or duration deliberately
+requests new limits, which the owner reviews before signing. Ordinary renewal
+continues to offer a new budget and duration. No service-specific logic is involved.
+
+Owner approval revokes the original Policy before creating its replacement, enabling
+the destination Module if required. Wallet independently checks original revocation,
+matching identity, destination chain data and zero destination spend before binding.
+Original Policy scope and Orders remain in history. Temporary failure or leaving the
+webpage resumes the saved plan; do not delete records or create replacement purchases.
+A completed chain/binding operation with unfinished local synchronization retries
+that synchronization before a subsequent fresh renewal.
+
+After successful binding, setup settings/public Policy/draft projections are updated.
+Previous setup/draft files are retained privately. Existing Market connection flow
+continues; failure there does not undo authorization. No automatic login or new
+spending authority is granted by merely downloading deployment settings.
+
+`./run status` shares a 60-second success/error cache for deployment checks. A changed
+deployment takes priority over local missing-result warnings; Orders retain their
+warnings below. A failed check is unavailable, never healthy or proof of revocation.
+Matching deployment does not guarantee a particular service or Order can be bought.
+
+Development checks use controlled RPC/IPC fixtures. The recorded private participant
+MetaMask renewal, payment journey and historical Order viewing passed within their
+recorded scope. Full interruption/multisig and public-network acceptance remain
+separate tasks in [TODO](../TODO.md); viewing history does not prove every support
+mutation. No real-network compatibility is claimed by Anvil tests.

package/doc/runbooks/emergency-payment-stop.md

@@ -0,0 +1,80 @@
+# Emergency stop: disable AgentPay payments from your Safe
+
+Use this procedure if your computer or Wallet Session Key may be compromised.
+Use another trusted device and your Safe owner wallet. Do not enter owner keys,
+Session Keys or unlock passwords into Market or send them to support.
+
+This procedure assumes the Safe owner signers remain under your control.
+A compromised owner signer requires a separate Safe account recovery response;
+disabling a Module alone is not sufficient if an attacker can enable it again.
+
+## What disabling the Module means
+
+Your Safe permits the AgentPay Spending Module to execute bounded payments.
+Removing that Module from this Safe stops all new payments through that Module,
+across all its Policies and Wallet execution addresses. It does not disable the
+Module for other users' Safes or shut down AgentPay.
+
+A copied Session Key cannot bypass this stop: AgentPay funding calls the Safe's
+module execution function, which requires the Module to remain enabled.
+The stop takes effect only when the disabling transaction executes successfully
+on-chain. A pending proposal or owner signature is not a completed stop; payments
+may still execute before it.
+
+## Stop payments from a trusted device
+
+1. Open [Safe Wallet](https://app.safe.global/), select the correct network and Safe.
+2. Open Settings and find Modules (under advanced settings in some versions).
+   Identify the AgentPay Spending Module by its exact address, not only its label.
+   Your saved setup and `./run wallet info` expose that address, but information
+   displayed on the compromised computer must be independently checked.
+3. Select removal for that Module. Review the Safe, network and target Module.
+   Obtain the Safe's required owner approvals and execute the transaction.
+4. Confirm a successful chain receipt and verify
+   `isModuleEnabled(moduleAddress) == false` on the correct Safe.
+5. Check for other enabled AgentPay Module versions on this Safe, and repeat if
+   necessary. Each network and Safe must be handled separately.
+
+Safe exposes this through `disableModule(prevModule, module)`, called by a Safe
+transaction targeting the Safe itself. `prevModule` is the predecessor in its
+enabled-module linked list, not a previous AgentPay release. Do not guess this
+address or submit a direct owner-account call as a substitute for a Safe transaction.
+
+Official references:
+[Managing Modules](https://help.safe.global/articles/7039805766-add-a-module),
+[disableModule](https://docs.safe.global/reference-smart-account/modules/disableModule).
+
+## What remains unchanged
+
+- Safe owner operations remain available. Other unrelated enabled modules are not removed.
+- Already-funded Order Vaults retain their delivery, cancellation, dispute, payout
+  and refund rules. This operation does not refund them.
+- Policy records remain on-chain. Disabling does not revoke or delete them.
+- Market Disconnect, sign-out, stopping Runtime or locking Wallet do not replace
+  this chain operation. An attacker may hold a copied key elsewhere.
+- This is a payment stop, not revocation of every history/support credential.
+  Do not assume copied credentials lose all non-payment access.
+
+## Before restoring payments
+
+Keep the Module disabled while investigating. Replace the compromised execution
+key and revoke its still-valid Policies through the Safe owner before re-enabling
+the Module. Review all relevant Policies, including ones absent from Market's
+connected list. Re-enabling without this cleanup can restore an attacker's
+remaining spending permission.
+
+Use a trusted installation for the replacement Wallet. Do not restore a suspected
+leaked key as a security remedy. Keep Order history and incident evidence; do not
+repeat paid requests to recover missing results.
+
+## Current product and rehearsal limits
+
+Market currently provides connection management and revocation documentation;
+it does not execute this emergency Safe transaction. `./run policy revoke`
+addresses the locally selected Policy, not every Policy or the entire Module.
+See [Policy renewal and revocation](policy-renewal.md).
+
+The private Anvil rehearsal is not available through the hosted Safe Wallet.
+It needs a separately prepared owner-authorized Safe transaction and independent
+chain checks. No emergency Module-disable rehearsal has been completed by writing
+this guide. Do not send private rehearsal transactions to a real network.

package/doc/runbooks/local-autostart.md

@@ -0,0 +1,212 @@
+# Local automatic startup (Linux)
+
+Wallet and Runtime can start as systemd user services when you log in. Wallet starts
+locked. Your Session Key and existing Safe Policy are reused; no password is saved.
+This does not enable startup before login or require administrator access/linger.
+
+## Enable during setup
+
+After the official connectivity test succeeds, the Linux terminal guide asks once
+whether Wallet and Runtime should start automatically when you log in. Choosing yes
+installs/enables the services and reminder without restarting current processes.
+Choosing no keeps manual startup. Your choice is remembered; q leaves it undecided.
+A saved yes is retried after partial installation failure without repeating consent
+or creating another payment. Manual enable/disable updates the same preference.
+
+The installer verifies that existing listeners belong to its matching guide processes
+or existing user services. Missing/stale PID records, mismatched arguments/data paths,
+and system-managed processes block automatic adoption. It never kills a PID from a
+saved file. On the private shared host, operator services remain operator-managed.
+
+## Manage after setup
+
+The terminal setup start step saves your public Runtime/Settlement addresses in
+`runtime/local-services.json` under your remembered User data directory. From User:
+
+```bash
+./run service autostart on
+```
+
+This installs and enables the services for the next login. It does not replace or
+stop current terminal-started or operator-managed processes. Current guide processes are left running; the handoff is deferred until they exit
+or the computer restarts. Do not run two managers for the same Wallet.
+If a login happens while old processes still run, managed startup refuses the occupied
+socket/port; inspect status and explicitly stop the old processes before using start.
+After a clean login, use `./run wallet unlock` to resume signing.
+
+If you completed setup before this feature, an operator can save the matching public
+addresses once with `node scripts/autostart.mjs configure RUNTIME_URL SETTLEMENT_URL`.
+Use your existing deployment, not arbitrary endpoints. This saves settings only.
+Do not change endpoints to work around an incomplete request or Policy migration.
+
+## Manage
+
+From User, `./run status` shows the services. Use `start` or
+`stop` for these managed processes. Before manually starting them, stop any existing
+terminal/operator-managed instance explicitly. A live Wallet socket or Runtime port
+is rejected; it is never removed to take over an existing process.
+
+`./run service autostart off` disables login startup without stopping current processes.
+`./run service stop` stops them now without changing the login preference.
+`./run service start` starts them manually; `./run service restart` restarts them locked.
+`./run service logs runtime` shows recent Runtime service errors. Wallet data and history remain.
+This is not on-chain revocation, deletion of the installation, or Order cancellation.
+
+Files are installed under `~/.config/systemd/user/`: agentpay-local-wallet.service,
+agentpay-local-runtime.service and agentpay-wallet-reminder.service. The installer
+does not use or change `~/.config/autostart`, including its permissions or contents.
+A conflicting existing file is preserved and reported. Services use absolute Node
+and source paths; do not move/delete those paths before disabling/reconfiguring.
+The current implementation uses the standard ~/.config location.
+
+## Login reminder
+
+A systemd user oneshot, enabled for graphical-session.target, checks Wallet status
+and sends one best-effort notification
+if it is locked. It does not unlock, prompt for a password, open a terminal or make
+a payment. The notification tells you to open User and run `./run wallet unlock`.
+There is no click-to-unlock action in this first version.
+
+Linux needs a desktop environment that starts systemd graphical-session.target and
+imports its display/session environment, a notification service, and `notify-send`.
+The reminder stays active until graphical logout (PartOf + RemainAfterExit) so normal
+Wallet restarts do not repeat it. Manual service start starts only Wallet/Runtime. With SSH/headless
+sessions, missing notification support or an already unlocked Wallet, no popup is
+sent. Runtime/Skill locked errors still show the unlock command. A missed notification
+does not grant authority or block service startup. If Wallet does not become available
+during bounded checking, inspect service status; notification is not a health monitor.
+
+## Acceptance scope
+
+Isolated process tests verify locked Wallet/Runtime startup, duplicate Wallet refusal,
+stop/restart with unchanged test key and no invocation. Unit/CLI tests and systemd
+file validation passed. The terminal installer now offers deferred automatic startup after its successful
+connectivity test; it does not immediately replace guide processes. The participant reported successful Wallet restart/lock/unlock and a manually triggered
+desktop reminder. Runtime exited with status 1; its journal is still required. Actual
+login/reboot and complete Runtime recovery acceptance remain pending. macOS launchd support is pending.
+Do not manually enable these user services on the shared rehearsal host while its operator
+services use the same data/socket/port. No existing rehearsal service was changed.
+
+The `startupChoice` field in local-services.json records the requested preference,
+not proof that systemd enable/start succeeded. Use status to inspect actual services.
+If setup reports automatic startup pending, current processes remain in place and
+local keys/Policy/history remain unchanged; retry enable after correcting the problem.
+
+Desktop environments without that systemd session integration may not show a reminder;
+Wallet/Runtime still start through the user default target and locked-call guidance
+remains available. No password is collected through the notification. The former
+prototype desktop entry is not generated or automatically deleted by this version.
+
+## Uninstall
+
+Run `./run uninstall` in an interactive terminal. It lists the selected local
+installation and requires the exact phrase `DELETE LOCAL AGENTPAY DATA`.
+Confirmation stops/removes its managed services and permanently deletes its local
+Session Key, credentials, installed Skills, recovery history and installer settings.
+It preserves the source repositories and tells you to delete User and Wallet folders
+once cleanup succeeds. Other installations and unrelated startup files are preserved.
+Unknown service definitions, active external listeners or unsafe paths block cleanup.
+
+Uninstall does **not** revoke Safe authorization or cancel Orders. Resolve pending
+Orders and revoke permission separately before retiring an installation. Reinstalling
+cannot recover deleted keys or request history. Neither `stop` nor `autostart-off`
+deletes data. Graphical password input is deferred; unlock remains a terminal command.
+
+## Private rehearsal networking
+
+Current Anvil settings contain loopback RPC, Settlement and package URLs, and the
+published reference package still uses a loopback Provider URL. A desktop using those
+settings needs the arranged SSH tunnels. Existing nginx routes do not rewrite saved
+configuration or package identities. Keep Anvil and local Wallet/Runtime private.
+A production installation must use public HTTPS Market/Settlement/Provider URLs and
+an appropriate chain RPC; SSH forwarding is not a normal user installation step.
+Public settings/package handoff and production owner signing remain release work.
+
+## Startup self-check and historical Orders
+
+Runtime starts its authenticated local listener before checking business history.
+`./run status` shows process state, local inventory, Wallet availability and Order
+check counts separately. A running process is not proof that a purchase is eligible.
+The local `/status` endpoint requires the existing caller credential; `/health`
+remains a minimal liveness endpoint.
+
+The background task only reads Wallet status and original Settlement Orders. Locked
+Wallets wait for unlock; unavailable services are retried with bounded backoff.
+It does not create Orders, send payments, execute Provider work, confirm receipt or
+cancel Orders. Existing Settlement workers retain their automatic refund duties.
+
+Old invocation records stay unchanged. Known legacy requests cannot be replayed as
+new purchases. Valid inventory permits unrelated requests through ordinary checks;
+unreadable/missing/conflicting history or failed recovery-state writes pause new
+paid calls without stopping the status listener. Missing caller authentication or
+an occupied port still prevents unsafe startup.
+
+Financial state and verified result availability are separate. A settled Order with
+no verified local output is reported explicitly; Runtime will not re-execute that
+settled service request to replace missing output. Unknown IDs, mismatched identities,
+legacy output formats and unavailable original deployment access require review.
+Do not delete history or add routing-version fields to bypass those protections.
+
+Observations are saved privately beside `runtime/invocations.json` in
+`runtime/invocations.json.recovery.json`; the original history, signed payloads and
+result files are not migrated or erased. The observation file contains identifiers,
+check times and conclusions, not private inputs, outputs or signatures. It is part
+of the selected local data removed only by confirmed uninstall. Cached observations
+are not a substitute for the Wallet/Settlement checks on each actual invocation.
+
+The queue handles at most 4 records per pass, one read at a time. The IPC timeout allows Wallet's
+30-second HTTP deadline to finish before the next read. Passes wait about
+10–11 seconds after the previous pass; pending Orders are rechecked after 30 seconds, failed reads use
+backoff up to five minutes, and terminal observations at most hourly. `./run status`
+wakes a pass without bypassing per-Order backoff. Large inventories can take several
+passes. All observed times are Unix milliseconds internally.
+
+### Reading status
+
+`./run status` groups services, Orders and one suggested next command. A live Wallet
+read takes precedence over an older background observation when describing lock state.
+Green `[OK]`, yellow `[WAIT]` and red `[!]` distinguish normal, waiting and blocked
+conditions in interactive terminals. Redirected output is plain text; `NO_COLOR` or
+`TERM=dumb` also disables color. Labels remain readable without color.
+
+Status layout wraps explanations for terminals of at least 40 columns, keeps service
+columns aligned with or without color, and does not show zero Orders when inventory
+is unavailable. A successful summary says local checks passed, not payment approved.
+
+Login startup reports Enabled/Disabled only when systemd confirms that setting.
+Not configured for this user means the corresponding user unit is absent; it does
+not describe administrator-managed services. Could not check means the query did
+not establish the setting. Temporary enablement and masking are shown separately.
+Start/restart output confirms that systemd accepted a request, not that Runtime
+finished self-check; use status next. Stop/off remain separate operations.
+
+### What to do next
+
+| Status | Action |
+| --- | --- |
+| Runtime/Wallet stopped | Use the displayed start command, then check status. |
+| Status unavailable | Inspect the indicated service log; do not reset history. |
+| Locked | Run `./run wallet unlock`; background Order checks resume. |
+| Permission missing | Run `./run setup`. An existing migration must follow its original update instructions instead. |
+| Initial checks in progress | Leave services running; check after about 15 seconds. Large histories take longer. |
+| Order check temporarily unavailable | Automatic backoff continues. If persistent, check network and Runtime logs. |
+| Orders in progress | Keep services running and use the original Agent conversation. Only resume supported original requests with their original identifiers. |
+| Identity/state/result conflict, unknown Order or missing Order ID | Preserve history; ask AgentPay support to review the Order/status. Do not share secrets or signed payloads. |
+| Payment complete; local result unavailable | Check the original conversation, then ask the Provider using the Order ID. Repeated status checks cannot reconstruct the result; do not pay again to recover it. |
+| Local checks passed | This check is finished. Normal checks still apply to each purchase. |
+
+Mixed histories retain per-Order explanations; pending Orders continue automatic
+checks even when another Order needs review. Background terminal-state rechecks
+remain enabled; the guidance does not change recovery scheduling.
+
+## Missing startup settings
+
+`./run service start` prepares missing user-service configuration for an initialized Wallet.
+It reuses private User settings and asks for any missing endpoint in the terminal.
+It never reads platform secret configuration or changes your Policy.
+`./run market connect` uses the same preparation before rebuilding/restarting when
+needed. Preparing services does not turn on login startup. Conflicting saved
+addresses stop the flow for review; no new identity is generated.
+
+An old system-level installation requires an operator handoff first; User does not
+stop root services. Do not initialize another Wallet to fix process management.

package/doc/runbooks/local-cache.md

@@ -0,0 +1,115 @@
+# Manage local cache
+
+Current source includes the 2026-11-04 text/file view and generic Provider source.
+Existing file-management APIs are unchanged; this display update alone needs no
+Runtime restart. Machines on older Runtime code still need the coordinated update.
+Wallet unlock is not required. These operations never buy a service or cancel an Order.
+
+```bash
+./run cache
+./run cache list
+./run cache list 1 input
+./run cache list 1 output --state available
+./run cache list 1 --order ORDER_ID
+./run cache list 1 --request REQUEST_ID
+./run cache details FILE_ID
+./run cache export FILE_ID /your/folder/report.pdf
+./run cache clean
+./run cache settings
+./run cache settings totalBytes 1073741824
+```
+
+Use the full file ID shown by `list`. Listings have 20 entries per page; `list 2`
+shows the second page. Export verifies the saved bytes and creates a private copy;
+it never opens/executes the file or overwrites an existing destination. Choose a
+path outside the managed cache. Rename the exported copy as needed for your application.
+
+`clean` previews up to 100 eligible file copies and their sizes before asking for `confirm`.
+Original links might have expired: deleted files are not guaranteed downloadable
+again. Request/Order history, structured results and protected inputs remain. If
+records changed after preview, review cleanup again. No age-based auto eviction
+exists. Known interrupted temporary writes/deletions are repaired on first use.
+
+Inputs stay protected until the shared client and Runtime verify a durable delivered
+result for the original request. Then confirmed cleanup may remove them. Failed release
+checks retain protection and retry with the original call. Do not manually delete
+input records to work around protection.
+
+## Runtime stopped
+
+```bash
+./run cache --offline
+./run cache list --offline
+./run cache clean --offline
+```
+
+Offline mode is explicit; a failed online request does not silently switch to local
+writes. It uses the same OS file lock as Runtime. If Runtime owns the cache, use the
+online command or stop Runtime first. Never delete `owner.lock` to bypass contention.
+Offline settings changes are read at the next Runtime cache initialization; use the
+online settings command for a Runtime that is already managing files.
+
+## Space and limits
+
+The view shows text results and files. Text results include both shared-client
+copies and direct Runtime results. Matching Order/service/request/output identities
+are displayed once; storage usage includes all physical result records. Display
+source comes from the saved Provider reference, not installed package guessing.
+A missing historical source is shown as unrecorded. Source labels never authorize
+payments or alter request identity. JSON result cleanup remains disabled.
+
+The summary separates text-record storage from attachment storage and reservations.
+Unknown files occupy capacity but are not automatically deleted. Request records,
+pending delivery evidence and other local state are separate; this is not total
+User disk usage.
+
+Defaults: 100 MiB per file, 512 MiB managed file bytes, 20 active files per request or
+Order, 2 transfers, 10,000 metadata records and a 15-minute transfer timeout. Supported
+configuration names remain `singleBytes`, `totalBytes`, `filesPerResult`, `concurrent`,
+`records`, `timeoutMs`. Byte/time values use bytes/milliseconds; all are positive
+integers. `filesPerResult` applies separately to each input request or output Order.
+The total counts binary/staging/unknown files; index overhead is separately bounded
+at 8 MiB. These are local resource limits, not business or file-format restrictions.
+
+Settings commands validate and apply limits without restarting or locking Wallet.
+Lowering limits never deletes existing files; over-limit storage blocks new allocation
+while keeping inspection, export and cleanup available. Retained removed records
+still count toward metadata limits. Raising `records` cannot bypass the 8 MiB index
+bound. Cache errors do not stop Runtime's independent Order recovery.
+
+## Storage and upgrade
+
+Managed files remain under `runtime/invocations.json.files/` in the selected User
+data directory. `./run wallet info` shows that data directory. No file format is executed,
+extracted or converted; extensions and names are descriptive. Original private paths
+and signed URLs are excluded from routine lists but can exist in private metadata.
+Back up the complete User data directory privately to preserve recovery and files.
+
+First access upgrades the old version-1 output index atomically to version 2 under
+the store lock. Existing output IDs and binary paths are preserved, with no redownload.
+Old Runtime versions cannot read the new index; stop old writers and coordinate User
+updates before rollout. Do not downgrade/delete the index to fix startup. This is a
+local file metadata upgrade, not an Order, Policy or chain migration.
+
+Existing `./run orders files ORDER_ID` and `/files/*` operations remain supported through
+the same store. The new manager adds authenticated `/cache/manage` on the existing
+loopback Runtime; it has no arbitrary file-import/download or financial action.
+The shared Skill client uses the separate authenticated `/files/input` operation
+for explicit input declarations. `/files/input-release` independently verifies durable
+delivery before allowing input cleanup; it does not create, pay or acknowledge Orders.
+
+### Displayed types and sizes
+
+Text (JSON) entries show `content` (UTF-8 bytes of the business output serialized as
+JSON) and `cached` (complete saved result records, including internal copies and
+Order/verification metadata). Summary text storage counts those complete records. Attachment entries show
+input/output, the filename extension and cached bytes. Extensions are descriptive,
+not content validation. Zero attachments is expected for JSON-only services. These
+sizes are file lengths, not filesystem allocated blocks or total User disk usage.
+
+The standard Runtime result location is `runtime/invocations.json.results/`;
+shared-client results remain in `runtime/client-requests/`. If using a custom
+Runtime state file, set the same `AGENTPAY_USER_STATE_FILE` for cache commands.
+No installed ZIP is scanned for display. Attachment pagination reads only the
+prefix needed for the merged page; text inventory still scans retained result
+metadata and is not a persistent index.

package/doc/runbooks/local-update.md

@@ -0,0 +1,84 @@
+# Update User and Wallet
+
+Keep your private data when updating program files. Do not uninstall to upgrade.
+
+For a global npm installation:
+
+```sh
+agentpay update
+```
+
+It checks the published User version and shows its exact Wallet dependency. Confirm
+to continue, or cancel without changing services. `agentpay update -f` skips only
+this confirmation. The updater checks requirements, stops configured services,
+installs the confirmed version and invokes the new version's repair to refresh
+services and verify its pinned official test Skill. No paid test runs automatically.
+Other installed Skills and original requests are kept. Wallet needs unlocking after
+restart. A current User version still checks the official test Skill.
+
+Only genuine global npm installations are updated. A source checkout or `npm link`
+is refused rather than overwritten: update User's files, run `npm ci`, then
+`agentpay repair`. The first User 0.3.0 release establishes the package baseline; a later real
+registry upgrade still needs participant acceptance. The updater uses npm's configured registry, checks
+Node engine requirements and disables package installation hooks; releases must
+ship usable runtime artifacts. It never independently selects the newest Wallet.
+
+If npm fails after services stop, keep your private data. Review the shown log;
+reinstall the intended User version with npm if program files are incomplete, then
+run `agentpay repair`. Interrupted installers may leave a lock to inspect. Repair
+failure is not reported as update success. A newer update cannot silently downgrade
+a version changed while you were reviewing the confirmation.
+
+For an old custom data location, first note `wallet info` in the old installation.
+Set `AGENTPAY_USER_DATA_DIR` to that same directory when moving to npm; do not
+initialize another Wallet. Source repair can read the old adjacent checkpoint, but
+an unrelated npm installation cannot discover arbitrary old source folders.
+
+User supplies its exact reviewed Wallet dependency; do not independently replace it.
+For a source/ZIP
+installation, stop services, update the User files, run `npm ci`, then `agentpay repair`.
+If using the source wrapper instead of `npm link`, replace `agentpay` with `./run`.
+
+Repair checks installed versions and asks before restarting changed services.
+`agentpay repair -f` skips that confirmation only. It refreshes the managed systemd
+user units and local client-module path; it preserves the Runtime address, caller
+credential, login startup preference, keys, Policies and original requests.
+Wallet starts locked after restart. No Wallet compilation is required.
+
+If preparation fails after stopping services, they remain stopped. Resolve the
+reported cause and repeat repair; the log path is shown. An interrupted run may
+leave an installation lock: inspect it before removing it. There is no automatic
+code rollback. Running-package negotiation is not implemented; complete the managed
+restart before relying on a newly installed version.
+
+## Uninstall
+
+`agentpay uninstall` asks before removing background services and keeps private data.
+`agentpay uninstall --delete-data` asks for explicit confirmation before permanently
+removing the selected local keys, configuration, history and cache. A matching old source checkpoint and its saved setup files are also retired during
+explicit data deletion, so later setup cannot import them again. Unrelated source
+installations are preserved. Neither command revokes on-chain permission. Afterwards, remove the program with
+`npm uninstall --global @c4roa0/agentpay-user`, or delete your source folder.
+If you removed npm's program first, reinstall the same reviewed version to run
+cleanup against your existing data. Never erase keys to repair an installation.
+
+## Official test Skill check
+
+After a successful software update, the command downloads the published official
+test ZIP using the saved Market source, verifies its bytes against User's built-in
+SHA-256 and saves the new package alongside existing ones. It does not replace the
+selected original test, edit checkpoints, execute package scripts or purchase.
+The same check also runs when local software has no changes. Cancelling an update
+skips it. Missing settings, network errors or a hash mismatch are reported separately;
+they do not turn a successful software update into a failed preparation. Retry `agentpay repair`
+without restarting unchanged software. Local edits in an existing installed copy
+are retained and reported rather than overwritten.
+
+## Missing local Skill connection
+
+If a Skill reports a missing Runtime connection while services are running, run
+`agentpay repair`. Preparation restores a missing `runtime/connection.json` from your
+saved service settings, including when local code is unchanged. It keeps caller
+credentials, keys, Policies and request history. A conflicting, malformed or unsafe
+existing connection file is retained and reported for review; do not delete your
+User data or repeat setup to work around it.