@c4roa0/agentpay-user 0.0.0-stage → 0.3.1

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.

package/doc/runbooks/market-connection.md

@@ -0,0 +1,73 @@
+# Connect a local Wallet to Market
+
+Run from User after Wallet setup:
+
+```sh
+./run market connect
+```
+
+Enter your Market HTTPS address, sign in with your Market account, and choose a
+Wallet nickname. Private rehearsals may use an arranged loopback HTTP address.
+If preparation is needed, the command asks once, verifies the installed Wallet package,
+restarts local services and continues. Unlock when prompted; input is hidden.
+Keys, spending permission and Order records are preserved.
+
+Review the account and nickname, then type `confirm`. Use `details` to inspect the
+Safe, network and Policy. Open Market → Account to view your Wallets and Orders.
+A separate browser login may be needed; terminal sign-in does not create browser cookies.
+
+## Wallet identity and Policy access
+
+A Wallet is identified by network + Module + Safe + execution address. Its nickname
+belongs to that identity. Each attached Policy is verified separately and grants
+access only to its own Orders. Connecting another Policy with the same identity
+adds it to the existing Wallet group; it does not create a new machine identity or
+inherit unverified Policies. Activity reflects the connected, authorized scopes,
+not every transaction made by the Safe.
+
+Two machines using the same key and identity share a Wallet group. Different keys
+are different Wallets even on the same Safe. Choose a nickname distinct from other
+Wallets in your Market account. Names are compared with Unicode normalization and
+without case distinctions. The guide checks availability before confirmation; a
+pending challenge can reserve the name for up to ten minutes. Reconnecting the same
+Wallet can retain its name. Names are labels, not permission to access Orders.
+
+Connection adds website Order access/support, not payment permission, receipt
+confirmation, Policy management or platform adjudication. See the
+[identity reference](../reference/wallet-identity-policy-history.md).
+
+## Recovery and disconnect
+
+- **Locked:** enter the Wallet password when prompted.
+- **Old or stopped Wallet:** confirm preparation. If it fails, check the displayed
+  log and retry. Obtain current source if requested; preparation builds local code.
+- **Interrupted connection:** repeat `./run market connect`. Challenge verification
+  is idempotent; an expired challenge needs a fresh proof. No purchase is created.
+- **Expired Policy or disabled Module:** these stop new payments, but do not alone
+  prevent connecting the original Policy for its Order history/support. Ownership,
+  signatures, Policy existence and Order deadlines are still checked.
+- **Revoked Policy:** new support requests through that Policy are denied. Another
+  Policy does not inherit its Orders. Local original-Order reads/recovery have their
+  own authorization checks; a denied connection is not a reason to buy again.
+- **Renewal:** successful renewal can continue this connection flow to verify the
+  new Policy under the same Wallet. A cancelled connection does not undo renewal;
+  retry only `./run market connect`.
+- **Disconnect:** removes the Market association and its pending challenges, not
+  on-chain spending permission or a submitted dispute. Separately authorized access
+  may still exist. For a compromised key, use the [emergency stop](emergency-payment-stop.md).
+
+## Local administrative boundary
+
+Wallet's admin capability signs only a fixed `market.connect` proof. The Agent/Skill
+capability cannot call it. The proof binds Market origin, account, challenge,
+nickname and expiry; it cannot make a payment. Same-user filesystem/code access is
+not isolated by these capabilities. Market does not receive keys, unlock passwords
+or private service results.
+
+Normal completion and handled cancellation attempt to revoke the temporary terminal
+login session. A forcibly killed process cannot guarantee logout; unused sessions
+follow platform expiry. Passwords, login tokens and signatures are not saved locally.
+`market-connection.json` in the selected User data directory contains public receipt
+metadata and the saved Market address, protected with private file permissions.
+It is not authority for website access. Local status does not detect a later website
+disconnect or establish current server availability.

package/doc/runbooks/npm-publication.md

@@ -0,0 +1,56 @@
+# Publish User to npm
+
+This publishes the User CLI and Runtime, with its exact reviewed Wallet dependency.
+It does not deploy platform services or alter participant keys, Policies or Orders.
+
+## Verify a release
+
+From a clean reviewed source checkout, using Node 22.22.3 or newer:
+
+```sh
+npm ci --ignore-scripts
+npm test
+node scripts/test-package.mjs artifacts/npm
+```
+
+Review the package inventory and README. The archive check installs the package in
+an isolated directory, checks the public command and starts disposable Wallet/Runtime
+processes. It never uses a participant's private data. Keep the exact verified archive
+for publication; do not rebuild it between verification and upload.
+
+## First publication
+
+Authenticate as the package maintainer, then publish the verified archive:
+
+```sh
+npm publish artifacts/npm/c4roa0-agentpay-user-0.3.0.tgz --access public --ignore-scripts --registry=https://registry.npmjs.org/
+node scripts/verify-npm-release.mjs artifacts/npm/c4roa0-agentpay-user-0.3.0.tgz 0.3.0
+```
+
+Never commit or share a publishing Token. If npm stages the first release, approve
+it on npm before verifying. A timeout is not proof of failure: check the registry
+before retrying publication. Published version numbers cannot be reused.
+
+## GitHub Trusted Publisher
+
+Create the GitHub environment `npm-publish` and restrict its deployment branch to
+`main`. Add maintainer approval if desired. In the npm package's Trusted Publisher
+settings, select GitHub Actions and enter:
+
+| Field | Value |
+| --- | --- |
+| Organization/user | `c4rO-0` |
+| Repository | `agentpay-user` |
+| Workflow filename | `publish.yml` |
+| Environment name | `npm-publish` |
+| Allowed action | Direct publishing |
+
+Run **Publish User to npm** on `main` with a new reviewed package version matching
+`package.json` and `update-pair.json`. It tests, packs, verifies, publishes that exact
+archive through OIDC, and compares registry integrity. No stored npm Token is needed.
+The first successful OIDC release validates the connection; the initial Token upload
+does not. Afterwards, disable bypass-2FA tokens and retire unused publishing tokens.
+See [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/).
+
+Publication is not real-network or participant upgrade acceptance. Record the exact
+source revision and verification outcome; test the published installation separately.

package/doc/runbooks/official-test-package.md

@@ -0,0 +1,62 @@
+# Official connectivity-test package
+
+The User onboarding installer trusts the ZIP SHA-256 embedded in
+`src/official-test-package.mjs`. Market supplies the download location and metadata;
+neither its response nor a command-line hash can override the official pin. The
+installer hashes downloaded bytes before parsing or saving package contents.
+A mismatched release stops installation. Never bypass this check by accepting the
+hash reported by the same server that supplies the ZIP.
+
+This pin applies only to the maintained onboarding test. Generic Runtime calls and
+ordinary Skill installation do not require the random service or this package.
+The current pin is the reviewed random Skill 1.2.0 private rehearsal package;
+it includes its service reference. It is not a production-network release.
+
+## Before publishing a User update
+
+1. Check whether the maintained official Skill has a new published version.
+2. Review its source and actual ZIP: instructions, scripts, manifest, service
+   identity, endpoints and absence of secrets. Do not automatically trust a new
+   Market version or copy its reported hash into the code.
+3. If accepting that release, update the name, version and SHA-256 in
+   `src/official-test-package.mjs` as a reviewed code change.
+4. From the User repository, verify the actual file:
+
+   ```sh
+   node scripts/check-official-test-package.mjs /path/to/reviewed-skill.zip
+   ```
+
+   This checks the hardcoded hash, archive validity and package name/version.
+   It does not execute scripts or prove service availability.
+5. Run the official pin/download and onboarding regression tests, then publish
+   the matching User release. Actual paid acceptance remains a separate step.
+
+## Existing installations
+
+Market's legacy deployment `bundleSha256` field no longer decides which ZIP may be
+installed for a new official test. User supplies its embedded hash to the installer.
+A changed Market hash alone is not a chain deployment change and never rewrites
+saved configuration, Policy or test history.
+
+An installed package used for a new test must match the current User pin and must
+not have local edits. A saved prior test can continue with its original locally
+verified package and saved hash only after its checkpoint is checked against local
+invocation history. This exception cannot select a new package or start a replacement
+purchase. Unknown/conflicting material stops for review. Old files are not deleted.
+Updating User does not restart a completed paid test or renew an expired Policy.
+
+For a new private rehearsal after updating User/Wallet and checking the new Policy,
+run `./run payment test`. This uses the installed pinned package directly, without changing
+the old selected package or its completed checkpoint. The first call shows the
+current quote and requires explicit confirmation; after consent it saves a new
+request identifier before invoking the Skill. A retry uses the saved identifier.
+This release's official test is private-Anvil-only and does not install a third-party
+Skill. Once a test has completed, the same command offers a new paid test with a new
+quote and explicit confirmation. The old completed record is archived before a new
+test. Cached replay alone is not a fresh payment-path check. Success confirms delivery
+and receipt acknowledgement; final Provider payout follows the Order schedule.
+
+The pin protects against replacement of the test ZIP by Market; it does not protect
+against a compromised User installation, bad code accepted during release review,
+or all risks of a compromised platform. Wallet's independent spending checks and
+explicit confirmation before the paid test remain necessary.

package/doc/runbooks/order-cancellation.md

@@ -0,0 +1,56 @@
+# Cancel an unaccepted Order
+
+The cancellation client is implemented. Remaining participant and financial
+acceptance is tracked in current TODO. Keep User and Wallet side by side and use
+their declared dependency lockfiles.
+
+## Before you start
+
+Wallet must be running, unlocked and bound to the original Buyer Safe/Policy.
+Use the same User data directory and Settlement base URL as the original request.
+Use HTTPS in public deployments; loopback HTTP is permitted for private testing.
+A public reverse-proxy prefix belongs in the base URL, for example
+`https://market.example/settlement`, not the final `/agentpay/wallet` route.
+No access to platform files, databases or Provider credentials is needed.
+
+From the User repository, cancel by the original Runtime request ID:
+
+```sh
+node scripts/cancel-order.mjs "$HOME/.local/share/agentpay/user" 'https://market.example/settlement' --request 'YOUR_ORIGINAL_REQUEST_ID'
+```
+
+Replace the example URL and request ID. This reads the existing default
+`runtime/invocations.json` ledger. If Runtime uses a custom state-file path,
+use the original Order ID instead; the command does not search other ledgers:
+
+```sh
+node scripts/cancel-order.mjs "$HOME/.local/share/agentpay/user" 'https://market.example/settlement' '0xYOUR_ORIGINAL_64_HEX_ORDER_ID'
+```
+
+No saved Order means nothing is cancelled. Do not start a replacement payment
+to work around a missing or interrupted request.
+
+## Check or retry
+
+Add `--status` to either command to read the original Order without requesting
+cancellation. A request timeout is not a confirmed cancellation: check status,
+then rerun the same cancellation command if needed. The client saves one private
+cancellation identity before sending it and reuses it after response loss or
+process restart. Keep `runtime/order-cancellations/` and invocation history.
+
+| Result | Meaning / next action |
+| --- | --- |
+| `requested`, `cancelling`, `refunding` | Still pending. Query the same Order later. |
+| `cancelled` | Unpaid Order closed; no payment was refunded. |
+| `refunded` | Funded principal returned to the original Buyer Safe. Policy cumulative spend is not restored. |
+| `ORDER_ALREADY_ACCEPTED` | Provider acceptance won; existing delivery and timeout rules apply. |
+| `ORDER_CANCEL_FORBIDDEN` | Current Safe/Policy does not own that Order. Restore the original configuration. |
+| `CANCELLATION_STATE_CONFLICT` | Local intent belongs to another Policy/endpoint. Preserve it for recovery review. |
+| `ORDER_CANCELLATION_UNAVAILABLE` | Deployment or original Order does not support this closure flow. Contact the operator. |
+
+Settlement decides acceptance/cancellation atomically. A local intent alone does
+not cancel an Order. Runtime reads authoritative closure before further payment
+or service calls and stops on closing/cancelled/refunded Orders; saved, verified
+output can still be recovered. In-flight operations remain subject to Settlement
+and contract race checks. There is no new owner signature, generic signing,
+replacement Order or automatic reuse of refunded budget in this command.

package/doc/runbooks/order-support.md

@@ -0,0 +1,41 @@
+# Original results and delivery cases
+
+From the User repository, unlock Wallet and use the saved installation:
+
+```bash
+./run orders list
+./run orders status ORDER_ID
+./run orders retrieve ORDER_ID
+./run orders case ORDER_ID
+```
+
+Use a complete original Order ID from `orders`. Status never initiates a purchase.
+Retrieval uses a short-lived, Order-bound permission, directly contacts the original
+Provider and checks original delivery metadata. It never sends another payment,
+executes service work or confirms receipt. Current-format valid results are saved
+through the existing private result store and reused by the original Skill request.
+Unsupported historical formats need review; they are not silently reinterpreted.
+
+Run `./run market connect` once for this Wallet, sign in and choose a nickname.
+Then open Market → Account → Order support and choose the Order. `case` shows this
+guidance; it no longer prints a code for a Buyer page that does not accept one.
+The independent Wallet Case API remains available for API clients.
+See [Market connection](market-connection.md) for scope, privacy and disconnect.
+
+Open the case before the displayed filing deadline even if result retrieval is
+still pending. Opening a case does not automatically request or retrieve the
+result; successful retrieval does not withdraw your case or approve early payout.
+Explain the missing delivery and submit relevant evidence. Evidence
+is deliberately shared with the case participants and review service; do not include
+keys, passwords, private payment signatures or unrelated personal information.
+
+Receipt confirmation ends the right to open a non-receipt case. Withdrawal does not
+confirm receipt; reopening is allowed before the original cutoff with unchanged
+deadlines. No repeated query, evidence or model retry extends a deadline.
+
+New-policy time windows: accepted delivery +7d filing, +10d evidence, +11d latest
+human handoff, +14d decision and +15d ordinary unconfirmed payout. Chain public
+refund opens no earlier than the latest permitted delivery +16d, fixed at creation.
+All days are 24 hours. Existing Orders keep their original policy. Provider-winning
+rulings retain the planned payout; Buyer-winning rulings schedule prompt refunds.
+A completed decision is not proof that a financial transaction has confirmed.

package/doc/runbooks/policy-renewal.md

@@ -0,0 +1,80 @@
+# Change or revoke spending permission
+
+To stop all payments through an AgentPay Module after a suspected key leak, see [Emergency payment stop](emergency-payment-stop.md). Revoking the current Policy alone may leave other Policies usable.
+
+From User, inspect the current permission:
+
+```sh
+./run policy info
+```
+
+## Renew or change limits
+
+```sh
+./run policy renew
+```
+
+New renewal drafts read budget, per-payment limit and validity duration from the
+previous on-chain Policy. Press Enter to keep each displayed value; existing draft
+answers take precedence. Duration starts again from now, not the old expiry date.
+If the previous duration is not a whole number of days, enter days explicitly.
+A previous per-payment limit above a newly reduced budget is not reused.
+Navigation hints appear on a separate line.
+
+This works both before and after expiry. Keep the same Safe and Session Key, choose
+new budget/per-purchase limits/validity, then confirm. `back` revisits the draft;
+`q` pauses with answers saved. There is no `-f` bypass for owner approval.
+
+Replacement revokes the old Policy before creating the new one. It then asks Wallet
+to independently verify the chain and switch. If creation fails after revocation,
+new payments remain stopped; rerun the same command to continue the saved new Policy.
+Submitted authorization terms cannot be edited as a draft. The new budget is a new
+permission, not an automatic carry-over of old unused allowance.
+
+Owner signing follows your explicit local signer selection, independently of the
+network. The default external signer provides a temporary local browser page for
+your Safe owner wallet, including on Anvil. Return to the terminal and enter `check`
+after execution. The guarded Anvil test adapter is available only when explicitly
+selected for the arranged test Safe; chain ID alone never selects it. See
+[browser approval](safe-owner-web.md). No owner private key is requested by AgentPay.
+Implemented signing support does not establish real-network or multisig acceptance.
+
+Wallet verifies its existing trusted network/RPC, Safe, Module, key, token, Factory,
+Registry and the new authorization's activation/expiry and unused state. Replacing
+an unexpired Policy requires independent proof that the old one is revoked. The old
+scope is archived before the durable pending/completed binding switch. Retry resumes
+that exact switch and keeps signing blocked while incomplete; unlocking for recovery
+remains possible. No service purchase occurs in this guide.
+
+## Revoke
+
+```sh
+./run policy revoke
+```
+
+Review the Safe/Policy and type `confirm`. This revokes the current Policy on-chain;
+it keeps the local key and binding for Order history/support. It is different from
+`wallet lock` or `service stop`, which only affect local processes. The command verifies
+revocation after owner approval; repeats detect an already-revoked Policy.
+
+`status` and `policy info` show a revocation last verified by these commands. External
+owner revocation is still independently enforced by payment checks; these local
+summaries are not continuous chain monitoring.
+
+## Existing Orders and next step
+
+Expiry/revocation stop new spending without cancelling funded Orders. Queries and
+support keep signature, original scope, ownership, replay and business-deadline checks.
+Session Key, local Orders, files and Market connection are retained. After successful
+renewal/binding, a saved Market connection automatically continues into the existing
+connection guide using its saved address. Sign in and confirm to add the new Policy;
+the stable Wallet group and nickname are reused. Without a saved connection, this
+step is skipped. Cancelling or a Market failure does not undo renewal. Retry only
+`./run market connect` to finish website access; do not renew again for this purpose.
+Renewal does not silently broaden Market's authorization scopes.
+
+Finish with `./run status`. Its Market section checks the local connection receipt
+against the current Wallet/Policy without contacting Market. A mismatch prompts
+`./run market connect`; a matching receipt does not prove current server availability
+or detect a later website disconnect. Neither renewal nor revocation reruns a completed official
+test or initiates another payment.

package/doc/runbooks/private-anvil-terminal-setup.md

@@ -0,0 +1,58 @@
+# Private Anvil terminal onboarding
+
+Use this guide with the existing private chain (31337), an operator-reviewed public deployment config, an existing single-owner test Safe and the published official random Skill. User installs Wallet as a reviewed npm dependency; their processes remain separate. User/Wallet access their own files and public or role-authorized APIs.
+
+## Start
+
+Build Wallet and install dependencies as described in [User installation](user-onboarding.md). The operator supplies current deployment and package facts using [the config example](../reference/private-anvil-onboarding-config.example.json). Optional `safe` displays the rehearsal Safe as a default. URLs must be loopback addresses; no second Anvil or database is created.
+
+Run in an interactive terminal from the User repository:
+
+```bash
+node scripts/user-setup.mjs --anvil /ABSOLUTE/PRIVATE/agentpay-data /ABSOLUTE/PATH/anvil-onboarding.json
+```
+
+The private data directory must be owner-held and outside the User/Wallet repositories. Missing directories are created during initialization. An operator's debug launcher may record terminal output, but must invoke this original command and preserve the terminal needed for hidden password input. It must not automate the participant's answers or replace the User/Wallet operations.
+
+## Four stages
+
+| Stage | What you enter | What the guide does |
+| --- | --- | --- |
+| 1. Create local Wallet | Set an unlock secret twice using hidden input | Creates or reuses the encrypted Session Key and local caller credential |
+| 2. Set spending permission | Choose Safe, total budget, per-payment limit and whole days; confirm the final authorization summary once | Saves the exact draft, executes through the selected owner signer, reads back the chain and binds Wallet |
+| 3. Prepare the official test Skill | Unlock Wallet if requested; official package preparation is automatic | Verifies/downloads the package, installs and selects it, starts local processes and checks readiness |
+| 4. Run the paid test | Confirm the displayed maximum cost; verified official-test receipt is acknowledged automatically | Invokes the official service with a durable request identity, verifies delivery and completes the guide |
+
+The guide asks for spending authorization and paid-test consent; external owner
+approval also requires the corresponding wallet transactions. Official package preparation and verified test receipt acknowledgement run automatically. Data entry and password prompts remain. At entry or after a pause, choose `continue`, `details` or `q`; successful internal operations advance automatically. Technical substeps remain independently checked and recoverable.
+
+Press Enter to use the displayed rehearsal Safe, or enter another Safe account address. Without a Safe, enter `create` for the appropriate guidance. Private Anvil is not available in the official Safe app. Amounts use displayed token units, not atomic integers. Expiry is computed from the selected number of days and displayed in the local timezone.
+
+Review the budget carefully: eligible purchases may use the full budget without another owner signature. Qualification verifies identity/control, not service quality. Signer selection is explicit: the default external signer opens the local owner
+approval page, also on Anvil. Only an explicitly selected Anvil adapter uses the
+arranged test owner’s RPC signing operation, with chain and Safe guards. No owner
+private key is entered into AgentPay. See [browser approval](safe-owner-web.md).
+
+Deployment and selected-package details are available through `details`. The official-test preparation mode refuses to automatically select local edits; inspect them using the standalone selection command before continuing. `--preview` still provides JSON for technical inspection. New selection cannot abandon existing invocation history.
+
+## Recovery and saved state
+
+Reopen the same command with the same directory. The guide reads actual local and chain state, skips completed operations and continues the incomplete stage. A binding failure after successful chain authorization resumes binding; it does not ask you to authorize again. A stopped Wallet must be unlocked after restarting.
+
+- `runtime/authorization-fields.json`: validated Safe/budget/per-payment/days, saved by semantic field names with deployment/delegate context. Wording changes do not invalidate saved inputs. No password is stored here.
+- `runtime/authorization-draft.json`: the exact Policy ID and reviewed terms, saved before chain submission. Its presence does not mean authorization succeeded; final consent precedes submission.
+- `runtime/active-skill.json`: selected bundle and file hashes.
+- `runtime/model-ack-smoke.json` and `runtime/invocations.json`: retain both to resume the same test. Conflicting or missing history stops recovery instead of creating a replacement purchase.
+
+An older unfinished `authorization-inputs.json` is retained. If no complete draft exists, the guide explains that its old prompt-based answers must be re-entered once; there is no silent migration. Existing complete drafts, Wallet bindings and Order checkpoints continue to be used.
+
+Newly started Wallet/Runtime processes remain running after exit. PID/log files are `runtime/wallet-guide.pid`, `runtime/wallet-guide.log`, `runtime/user-runtime-guide.pid` and `runtime/user-runtime-guide.log`. Existing processes are reused only when their checks pass. Stop them through your process manager or verified PID ownership. Binding can start a locked Wallet and does not itself unlock it.
+
+A saved confirmed test is revalidated before reporting completion. Automatic receipt acknowledgement for this official test can bring payout forward; connectivity success does not establish terminal financial reconciliation. On completion the guide explicitly ends and directs you to Market to choose other Skills.
+
+## Evidence boundary
+
+Focused tests cover orchestration, temporary local IPC/CLI operations and recovery.
+The recorded participant single-owner browser-signing and payment journey passed on
+private Anvil. Neither establishes public-network, multisig or real-funds readiness.
+Current acceptance gaps are tracked in [TODO](../TODO.md).