@c4roa0/agentpay-user 0.0.0-stage → 0.3.0

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).

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

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