@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

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.

package/doc/security/public-source-review-2026-11-06.md

@@ -0,0 +1,71 @@
+# Public-source preparation review — 2026-11-06
+
+## Completed cleanup
+
+- Original User code and documentation use owner-approved MPL 2.0. LICENSE,
+  NOTICE, SECURITY and CONTRIBUTING explain licensing, reporting and contributions.
+  The public Protocol artifact and attributed Agent test fixtures retain MIT.
+- Removed eleven historical Protocol archives from the publication tree. The one
+  required 0.14.1 archive is rebuilt from public Protocol commit `1c6ffab`, with
+  provenance, SHA-256, license and matching package-lock integrity.
+- Privately archived platform/MySQL harnesses, old operational records and previous
+  document snapshots. Removed the unused MySQL dependency. Product onboarding
+  scripts remain; script names alone were not grounds for removal.
+- Tests use the pinned package's Protocol fixtures and attributed local Skill
+  fixtures instead of sibling Agent/Protocol source. User imports its own declared
+  ethers dependency; built sibling Wallet remains required.
+- Reorganized current documentation by reader and function, rewrote source maps,
+  and separated implemented references from the future distribution plan.
+- Formatted maintained code and added comments explaining trust, persistence and
+  recovery boundaries. No payment, authorization or wire-format redesign was made.
+
+## Verification
+
+Independent verification uses only a temporary User checkout and the built public
+Wallet, without private Settlement, Agent or Protocol source checkouts. Offline
+`npm ci --ignore-scripts` installed the pinned dependencies successfully.
+
+The complete behavioral suite passed all 364 tests, with zero failures or skips.
+Tests exercise controlled local processes, sockets, HTTP boundaries and fixtures;
+these are not evidence of real-network payment, desktop login or participant browser
+acceptance. The portable approval-page test starts the exported server and checks
+actual responses and access restrictions instead of checking source text.
+
+Existing timeout tests were corrected to serve the current pre-purchase offer and
+separate status probes from preparation attempts. They still assert bounded timeout,
+lock release, the same request after restart and no Wallet call on invalid history.
+Grouped-command tests now use the current command surface.
+
+Syntax-tree comparison of 112 production source/script/browser files before and
+after formatting found no structural changes (comments and redundant parentheses
+excluded). Local Markdown links resolve, and `git diff --check` passes.
+
+## Follow-up documentation review
+
+A second pass found stale per-Policy Market grouping and expired-Policy connection
+instructions, along with pre-browser-signing descriptions in several runbooks.
+Those guides now use the implemented Wallet tuple and independently verified Policy
+scopes, explicit signer selection and the current browser approval flow. Implemented
+support remains distinct from uncompleted public-network/multisig acceptance.
+README/onboarding/developer prerequisites explicitly include npm and Corepack.
+The legacy preview's module comment now points to the public guided setup entry.
+
+This correction changed documentation and comments only. Local links, obsolete-claim
+search, JavaScript syntax and `git diff --check` passed; the prior behavioral suite
+was not repeated for prose-only edits.
+
+## Security scope and remaining decisions
+
+The bounded current-tree inventory found no literal private key, PEM private key
+or GitHub token; credential-bearing URL matches were negative-test fixtures.
+This is not a security audit or a guarantee against every secret format. Historical
+Git objects are outside this review and must not be assumed clean.
+
+User still imports Wallet compiled internals and enforces an exact update pair.
+The supported compatibility boundary and combined release archive remain separate
+work in the [distribution plan](../plans/user-wallet-distribution.md).
+The source review itself performed no automatic source download, service change
+or payment. Subsequently, the owner approved a single-commit history baseline
+(`2a80f4a`), force push and removal of old tags, then confirmed public visibility.
+Anonymous remote refs were verified; full fresh-clone/ZIP installation remains
+open in [TODO](../TODO.md).

package/doc/usage.md

@@ -0,0 +1,54 @@
+# Use AgentPay User
+
+The normal entry is `agentpay`; source checkouts also provide `./run`. Start with
+[installation](runbooks/user-onboarding.md); there is no need to run individual
+internal scripts for ordinary setup.
+
+| Task | Command / guide |
+| --- | --- |
+| Install or continue setup | `agentpay install --market URL`, then `agentpay setup` when returning |
+| Check local state | `agentpay status` |
+| Unlock / lock | `agentpay wallet unlock`, `agentpay wallet lock` |
+| Start / stop / restart | `agentpay service start`, `stop`, `restart` |
+| Login startup | `agentpay service autostart on` / `off` |
+| Inspect identity / restore | `agentpay wallet info`, `agentpay wallet restore` |
+| Change / revoke permission | `agentpay policy renew`, `agentpay policy revoke` |
+| Connect website support | `agentpay market connect` |
+| Review an Order | `agentpay orders list`, `details ID`, `status ID` |
+| Recover original result | `agentpay orders retrieve ID` |
+| Local files | `agentpay cache help`, `agentpay orders files ID` |
+| Update npm installation | `agentpay update` (confirm, or `-f`) |
+| Repair installed services | `agentpay repair` |
+| Remove services / erase data | `agentpay uninstall` / `agentpay uninstall --delete-data` (confirmation required) |
+
+See [full command reference](runbooks/commands.md) for arguments and examples.
+Status distinguishes saved local facts from refreshed observations. It is not a
+promise that a new purchase will be accepted. Online Order status queries go through
+Wallet; a failed query or missing local result does not prove non-payment.
+
+## Authorization and recovery
+
+[Browser owner approval](runbooks/safe-owner-web.md) is available for setup,
+renewal and revocation. [Deployment updates](runbooks/deployment-authorization-update.md)
+require deliberate owner approval; neither repair nor Runtime startup may silently
+replace Policy, key or Order identity.
+
+Back up the encrypted key and password securely, with the identity displayed by
+`agentpay wallet info`. Preserve the full private User data directory for local request
+and result recovery. A Policy ID alone cannot recover a lost key.
+
+## Local services and Skills
+
+The default data directory is `$HOME/.local/share/agentpay/user`, outside the source
+checkout. Runtime listens on loopback and requires a separate caller credential.
+A Skill uses local connection discovery; it must not bundle credentials or bypass
+Wallet. [Skill integration](runbooks/runtime-skill-client.md) explains per-call
+service references and recovery. No global Provider selection is required.
+
+`agentpay payment test` is a separate, explicitly paid connectivity check using the
+maintained, digest-pinned official package. Normal Runtime operation is not tied
+to that business example. An interrupted test retains its original request.
+
+[Background service guide](runbooks/local-autostart.md) explains Linux user services,
+login reminders and manual startup. A local lock or process stop does not revoke
+permission; follow [emergency stop](runbooks/emergency-payment-stop.md) when needed.

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@c4roa0/agentpay-user",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "type": "module",
+  "dependencies": {
+    "ethers": "^6.17.0",
+    "fs-native-extensions": "1.5.3",
+    "@c4roa0/agentpay-protocol": "0.14.3",
+    "@c4roa0/agentpay-wallet": "0.3.0"
+  },
+  "scripts": {
+    "start": "node src/index.mjs",
+    "check": "node --check src/index.mjs",
+    "test:unit": "node --test test/*.test.mjs",
+    "test:invocation-store": "node --test test/invocation-store.test.mjs",
+    "test:prepare-onboarding": "node --test test/prepare-onboarding.test.mjs",
+    "test:installation-guide": "node --test test/install-user.test.mjs test/install-and-setup.test.mjs test/guided-setup.test.mjs test/prepare-onboarding.test.mjs",
+    "test:market-connection": "node --test test/connect-market.test.mjs test/local-wallet-ipc.test.mjs",
+    "test": "node --test --test-concurrency=1 test/*.test.mjs"
+  },
+  "license": "MPL-2.0",
+  "bin": {
+    "agentpay": "scripts/agentpay-cli.mjs"
+  },
+  "engines": {
+    "node": ">=22.22.3"
+  },
+  "files": [
+    "src/",
+    "scripts/",
+    "run",
+    "update-pair.json",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "progress.md",
+    "AGENTS.md",
+    "doc/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/c4rO-0/agentpay-user.git"
+  },
+  "description": "Local AgentPay Runtime and guided Wallet setup for AI Agents",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}