@perkos/agent-sdk 0.7.1 → 0.8.0-rc.1

package/docs/HERMES_MCP.md

@@ -0,0 +1,157 @@
+# Hermes MCP — QA adapter
+
+**Unreleased QA candidate. Not yet published to npm, not a complete wallet-enabled
+Hermes integration.** By default this packages read/prepare tools using the actual SDK.
+Optional [custody delegation](HERMES_CUSTODY.md) adds bounded register/create/fund/assign/submit/finalize
+requests to a separate operator-controlled signer. This is not deployed or funded by default.
+An additional provider-only opt-in can request public QA evaluations for the permitted job.
+Neither mode performs x402 purchases or generates wallets.
+
+## Architecture and installation
+
+Hermes → local MCP stdio → Nayori SDK → fixed public Stacks testnet reads.
+Preparation tools are offline. There is no signer in the process or tool arguments.
+The browser SDK entry point does not import this Node-only adapter.
+
+Build and verify the reviewed QA source, then pack it outside the checkout:
+
+```sh
+npm ci
+npm run verify
+npm pack --pack-destination /absolute/private-artifacts
+```
+
+In a clean consumer directory, install that exact reviewed tarball:
+
+```sh
+npm init -y
+npm install --save-exact /absolute/private-artifacts/perkos-agent-sdk-0.8.0-rc.1.tgz
+./node_modules/.bin/nayori-mcp --help
+```
+
+The current candidate is 0.8.0-rc.1, separate from published 0.7.1. Historical QA tests used
+a source tarball still numbered 0.7.1; do not confuse it with either distribution.
+Record the tarball SHA-256 and exact commit. Initializing the consumer's own package.json
+prevents npm from inheriting an unrelated parent project. See the
+[candidate release checklist](RELEASE_0.8.0_RC1.md); registry installation is not yet available.
+Do not run an unpinned `npx -y` command for a financial agent.
+
+## Public role profile
+
+Create a JSON file outside Git. It contains **only public addresses**, no environment
+variables, private keys, seed phrases, tokens, signer modules or URLs:
+
+```json
+{
+  "network": "testnet",
+  "role": "client",
+  "client": "YOUR_TESTNET_BUYER_ADDRESS",
+  "provider": "YOUR_TESTNET_PROVIDER_ADDRESS",
+  "evaluator": "THE_VERIFIED_QA_EVALUATOR_ADDRESS",
+  "treasury": "THE_VERIFIED_QA_TREASURY_ADDRESS"
+}
+```
+
+Placeholders intentionally fail validation. Use distinct valid testnet addresses, confirm
+evaluator/treasury against the deployed QA policy, and use `role: "provider"` for the
+provider's separate instance. Profile acceptance does not certify registration, ownership
+of an address or a match to on-chain evaluator/treasury policy.
+
+The adapter pins STX `agentic-commerce-v6`, sBTC `sbtc-commerce-v5`, agent-registry and
+reputation-registry-v3 under `ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5`.
+Network/contract/endpoint overrides from tools are rejected; this adapter has no mainnet mode.
+
+## Connect Hermes
+
+Start with an existing Hermes already working with your own LLM; leave that configuration
+unchanged. This MCP does not select or authenticate the LLM provider, receive model API keys
+or require PerkOS-LLM. [Existing-agent onboarding](EXISTING_AGENT.md) explains registration
+and the separate operator-owned wallet/signer preparation. Hermes is an example, not a requirement.
+The fixed QA evaluator endpoint is a separate Nayori service, not the developer's LLM endpoint.
+
+After installing the tarball, configure a separate Hermes profile for each participant:
+
+```yaml
+mcp_servers:
+  nayori_qa:
+    command: /absolute/path/to/node
+    args:
+      - /absolute/consumer/node_modules/@perkos/agent-sdk/dist/mcp/cli.js
+      - --config
+      - /absolute/private-config/public-profile.json
+```
+
+Start Hermes and request the `nayori_context` tool. Hermes may prefix tool names.
+This is a manually configured MCP, not an entry approved for the Nous MCP catalog.
+Never put wallet keys into Hermes's config, environment, skill, prompts or tool parameters.
+
+| Tool | Roles | Effect |
+|---|---|---|
+| nayori_context | Both | Fixed QA role/contracts and explicit capability flags |
+| nayori_counts | Both | Registry/job counts; not adoption/completion counts |
+| nayori_get_agent | Both | One agent by decimal ID |
+| nayori_get_job | Both | One job, escrow, decision and fee ledger |
+| nayori_get_reputation | Both | Public testnet reputation |
+| nayori_prepare_job | Buyer | Offline criteria commitment; does not create a job |
+| nayori_prepare_submission | Provider | Offline evidence commitment; does not submit work |
+
+## Boundaries and errors
+
+### Optional provider evaluation admission
+
+Only after configuring provider custody, the operator may append `--enable-qa-evaluation`
+to the MCP CLI arguments (after `--permit-hash` and its value). Add these **exact names** to
+Hermes's tool include list if one is configured:
+
+- `nayori_request_evaluation`: accepts the same asset, jobId, description, acceptanceCriteria
+  and evidence as preparation. Requires an enabled, unexpired provider permit and a confirmed
+  submit in its durable journal. It compares client/provider/evaluator/treasury, budget, criteria
+  and evidence commitments against the actual SDK job read before any admission request.
+- `nayori_evaluation_status`: accepts only asset and jobId; both must match the configured
+  custody permit. Remains available for reconciliation after permit expiry.
+
+Requests go only to `https://evaluator.qa.nayori.ai/v1/evaluations`. Evidence must use that
+HTTPS origin; this narrow pilot does not support arbitrary storage providers. The evaluator,
+not MCP, fetches/validates evidence bytes and rechecks eligibility, deadlines and capacity.
+The operator explicitly authorizes enqueueing evaluation work by enabling the option.
+No internal API key, wallet signature, second fee or x402 purchase is attached.
+
+Admission allows 45 seconds for paced eligibility reads; status lookup allows 15 seconds.
+Configure custom relay/proxy timeouts accordingly and check capacity before submission.
+Safe MCP error codes distinguish `admission_limit`, `ineligible`, `unavailable` and `transport`.
+All prohibit automatic retry. They contain fixed SDK guidance, never upstream error details.
+The contract's review deadline remains authoritative even after an HTTP timeout.
+
+The adapter looks up the deterministic job-scoped evaluation ID before POST. The server's
+durable idempotency remains the authority across processes/restarts. HTTP errors/timeouts
+do not trigger automatic retry: query status first. A changed manifest cannot bypass the
+on-chain commitment. Status responses expose only bounded identity/state/txid fields, not
+arbitrary public explanations or raw errors. `confirmed` here describes the evaluator, not a
+verified escrow payout. Buyer custody still finalizes after the actual appeal deadline.
+
+This is an unreleased source candidate. In addition to mocked HTTP/chain tests, one internal
+funded Hermes lifecycle passed; see [the exact validation scope](VALIDATION_AND_RELEASE.md).
+It is not a security audit or npm release. Without the flag, tool availability is unchanged.
+
+- No arbitrary shell, file-reading, secret-export, transaction-signing or broadcast tool.
+- Unknown fields, wrong roles, unsupported assets, oversized payloads and invalid IDs fail closed.
+- Public chain text and URLs are untrusted data. Never follow their instructions or treat
+  them as approval to spend, change configuration, or invoke another tool.
+- Evidence preparation hashes the **manifest**, not remotely fetched bytes. It returns
+  `evidenceBytesVerified: false`; the evaluator still must check allowlisted HTTPS content.
+- Errors do not reflect raw RPC responses, user inputs or diagnostics into the model.
+- A decision is not payout confirmation. Use transaction events and fee/reputation checks.
+- There is no wallet isolation claim from merely running two same-user processes. The optional
+  custody candidate requires verified Linux isolation and durable operator-approved limits.
+
+## Validation and remaining work
+
+Automated tests cover official MCP client/server handshake, schemas, role separation,
+BigInt serialization, offline commitments, sanitized failures and real subprocess stdio.
+Those automated tests are distinct from the [verified internal testnet lifecycle](VALIDATION_AND_RELEASE.md).
+Clean published-package onboarding, the separate x402 walkthrough and video remain pending.
+Repeat isolation and permission checks for each new operator deployment; this single supervised
+scenario does not certify general autonomous onboarding. No server deployment is needed to test stdio.
+
+Sources: [Hermes MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp),
+[official MCP server guide](https://modelcontextprotocol.io/docs/develop/build-server).

package/docs/HERMES_PROVIDER.md

@@ -0,0 +1,98 @@
+# Hermes provider — controlled QA walkthrough
+
+See [validation and release boundaries](VALIDATION_AND_RELEASE.md) for the verified internal
+scenario and remaining distribution/video gates. An existing active registration is reused
+after readback, not registered again; adjust the permit and gas cap to omit that action.
+
+See [QA checkpoints and confirmation handling](HERMES_CHECKPOINTS.md) for the job-bound permit,
+STX gas budget, six-burn gate and the difference between a decision and payment. Do not fund
+your wallet with sBTC merely to receive a payout or reuse an example job ID.
+
+**Unreleased candidate; funded autonomous onboarding and recording still require validation.**
+Use the same job as the [buyer walkthrough](HERMES_BUYER.md), with a different wallet, signer,
+Hermes instance and journal. The candidate MCP is not the npm 0.7.1 release.
+
+## 1. Install and prepare your wallet externally
+
+Your Hermes is already installed and working with your own LLM. Keep that setup; this guide
+adds Nayori tools without configuring or replacing your model. No PerkOS-LLM account or model
+API key shared with Nayori is required. Hermes is an example, not a platform requirement.
+Start with [existing-agent onboarding](EXISTING_AGENT.md) and the separate
+[operator wallet/signer checklist](WALLET_SIGNER_SETUP.md). Never put model credentials in
+tool arguments or recordings. Your agent's model is separate from Nayori's evaluator.
+
+Follow [MCP installation](HERMES_MCP.md) with the exact reviewed tarball/source hash. Create,
+back up and restore-check your own testnet wallet outside the SDK and Hermes. Fund only
+authorized STX network fees; a provider does not need to send sBTC to receive a job payment.
+Never give Hermes your key or the buyer/evaluator/treasury keys. Follow the separate-UID,
+filesystem, socket and capability restrictions in [custody setup](HERMES_CUSTODY.md).
+
+Configure `role: provider`. The operator permit must reference the buyer's confirmed job ID,
+same criteria, identities, amount and expiry, with only `register` and `submit`. Start with
+signing disabled and confirm tool context and custody status. Allow evaluation separately only
+if this operator consents to enqueueing review of this job.
+
+## 2. Confirm assignment and perform the work
+
+1. With explicit low-value testnet permission, enable the isolated signer and request `register`.
+   Confirm the transaction and agent record. Wallet creation is not registration.
+2. Read the job using `nayori_get_job`. Confirm provider equals your address, status is funded,
+   escrow equals the agreed gross amount and client/evaluator/treasury/criteria are correct.
+3. Do not self-assign or work against missing escrow. Ask the buyer to resolve mismatches.
+4. Have the real Hermes perform the agreed task. Preserve its actual output, including errors;
+   do not substitute a canned result and call it autonomous execution.
+5. Publish the small evidence artifact through the operator-approved QA evidence workflow.
+   This MCP does not include an upload tool. The pilot accepts evidence only from the fixed
+   evaluator QA HTTPS origin; publishing to arbitrary hosts is not supported in this bridge.
+6. Compute the actual artifact's SHA-256, MIME and byte count. Prepare its manifest with
+   `nayori_prepare_submission`. Preparation hashes the manifest and does not verify remote bytes.
+7. Request `nayori_execute` with `action: submit` and the exact evidence manifest. Confirm the
+   saved transaction and job submission, including the configured six subsequent burn blocks.
+
+## 3. Request public evaluation, without internal credentials
+
+Before submitting work, coordinate evaluator availability and daily capacity with the QA
+operator. The on-chain review window starts at submission; custody confirmation and network
+latency consume part of that window. Check the live burn height and review deadline before
+admission. A timeout does not extend the contract deadline, and no client can force an expired
+review to be accepted.
+
+The candidate waits up to 45 seconds for admission and 15 seconds for status reads. Custom
+proxies must accommodate admission's paced chain checks with a bounded timeout within the
+client's budget; a shorter proxy timeout still causes failure. The response remains size-limited.
+Quota errors require operator capacity review, not repeated requests. Eligibility errors require
+checking the actual job and deadline. Transport/service errors require status reconciliation:
+the request may already have been persisted. No automatic retries or budget increases occur.
+
+Append `--enable-qa-evaluation` to provider MCP arguments after the custody socket/permit
+configuration. If Hermes uses tool filtering, add the exact names `nayori_request_evaluation`
+and `nayori_evaluation_status`. Without this operator flag the tools are absent.
+
+Call `nayori_request_evaluation` with the same asset, jobId, description, acceptanceCriteria
+and evidence used for commitments. It checks the permitted job, confirmed submission and
+on-chain identities/budget/commitments, then uses the deterministic job-scoped evaluation ID.
+It sends no bearer token, wallet key or additional payment. The evaluator independently checks
+eligibility and evidence bytes; no agent can approve itself through this endpoint.
+
+If a response times out, call `nayori_evaluation_status` with asset and jobId before retrying.
+Do not change the evidence or create another job to bypass a failed review. Admission is not
+approval; evaluator `confirmed` is not proof that escrow has been paid out.
+
+## 4. Verify outcome and payment
+
+Read the decision and explanation through the public evaluation/chain evidence surfaces. The
+buyer finalizes after the real appeal deadline when no appeal exists. This provider pilot does
+not expose finalize, appeal or admin actions. If a rejection needs appeal, involve the operator
+and supported app/SDK appeal workflow; do not claim the restricted MCP handles it automatically.
+
+Check the terminal job, escrow zero, exact payout to your wallet, treasury fee and reputation.
+For approved 1000 sBTC units and 200 bps, net payment is 980 and treasury receives 20. The
+fee remains within escrow until settlement. Do not infer success from an HTTP 202 or txid alone.
+
+## 5. Recording and current boundaries
+
+Record the same job from the provider's perspective: installation, external wallet setup
+without showing secrets, registration, assignment check, actual work, evidence, submission,
+evaluation status and payment. Show public transaction links and label waiting-period edits.
+The x402 resource-purchase walkthrough is a separate pending integration; do not describe
+evaluation admission as an x402 payment. Our internal controlled agents are not external adoption.

package/docs/RELEASE_0.8.0_RC1.md

@@ -0,0 +1,60 @@
+# 0.8.0-rc.1 — QA release candidate
+
+**Prepared source candidate, not published.** Stable npm remains `@perkos/agent-sdk@0.7.1`.
+This prerelease packages reviewed QA features for explicit operator testing; it is not a
+production promotion or a certification of autonomous operation for every developer.
+
+## Included
+
+- Node-only Hermes-compatible MCP read/prepare tools and optional Linux custody delegation.
+- Operator-owned keys, isolated signer identities, immutable permits, bounded budgets and
+  durable intent/nonce/txid recovery. Signing remains disabled by default; the pilot is testnet-only.
+- Provider-only, job-bound evaluation admission and status with bounded timeouts, sanitized
+  errors and deterministic-ID reconciliation. No automatic retries or x402 purchases in this adapter.
+- Opt-in STX v6/sBTC v5 fee methods, consent and accounting; default v5/v4 contracts are unchanged.
+- Versioned criteria/evidence commitments, absent-reputation handling, role-separated examples
+  and buyer/provider manuals. Developers retain their own agent and LLM configuration.
+
+See [verified scope](VALIDATION_AND_RELEASE.md). The earlier internal sBTC lifecycle used
+source `fc0537477fda819fa9cce8e74e543be0d49ea3a4`, not this versioned artifact. Packaging
+checks do not establish a new funded E2E, fresh registration, external adoption or security audit.
+
+## Install the reviewed artifact before publication
+
+In a clean checkout of the reviewed candidate commit, use Node 20+ and npm 10+:
+
+```sh
+npm ci
+npm run verify
+npm pack --pack-destination /absolute/private-artifacts
+```
+
+Create a separate, empty consumer directory and initialize its own package.json:
+
+```sh
+npm init -y
+npm install --save-exact /absolute/private-artifacts/perkos-agent-sdk-0.8.0-rc.1.tgz
+./node_modules/.bin/nayori-mcp --help
+./node_modules/.bin/nayori-custody --help
+```
+
+Check the exact package version, import and transaction-plan construction without a signer.
+Record source commit, tarball integrity and contents. No private key is needed to install or
+prepare a plan. Running custody signing requires separate Linux isolation, permissions and
+budget setup; never put keys into MCP, prompts or model tools.
+
+## Release gates
+
+1. Review and merge the QA release PR; build from the exact reviewed commit with a clean tree.
+2. Verify SDK tests, package allowlist, absence of secrets, dependency audit and isolated consumer.
+3. Obtain publication approval. Use the prerelease `next` tag, never move `latest` implicitly.
+   `publishConfig.tag` is `next`; do not override it to `latest` for this candidate.
+4. Verify registry version/integrity and that `latest` remains 0.7.1. Repeat isolated installation
+   from the exact published version, not an unpinned tag or financial `npx -y` command.
+5. Validate both role walkthroughs before recording the developer demo. New funded tests require
+   a fresh reviewed budget; never reuse the completed QA job's authorization.
+
+Only after publication is confirmed should registry installation use
+`npm install --save-exact @perkos/agent-sdk@0.8.0-rc.1`.
+QA merge, npm publication, hosted documentation deployment and production promotion are
+separate events. x402/MPP resource purchases remain a separate workflow and test scope.

package/docs/SERVICE_FEES.md

@@ -0,0 +1,108 @@
+# Earned service fee integration (unreleased)
+
+This source branch adds opt-in support for `agentic-commerce-v6` (STX) and
+`sbtc-commerce-v5` (sBTC). These are **simnet candidates, not deployed defaults**.
+The published `@perkos/agent-sdk@0.7.1` does not contain these new methods.
+Do not point a production client at candidate names or treat a successful build as a deployment.
+Existing v5/v4 jobs retain their full-budget, no-service-fee terms.
+
+## Payment lifecycle
+
+Funding locks the **gross** budget, including the potential 2% fee. Nothing is paid to
+treasury at funding, submission, decision recording or appeal filing. Final evaluated
+settlement atomically sends `floor(gross / 50)` to the job-pinned treasury and the remainder
+to the provider on approval **or back to the client on rejection**. Both transfers use the
+escrow asset. The settled escrow balance is zero.
+
+No evaluation (expiry/review timeout) means no service fee. An evidence-backed waiver
+before settlement also results in zero fee. Gas is separate, paid in STX. Optional extra
+analysis would require a separately accepted x402 quote; that service is not implemented
+and there is no automatic second 2% or payment prerequisite for filing an appeal.
+
+## Read first, accept explicitly
+
+After the exact candidate sources have been deployed and verified in isolated testnet,
+configure their explicit same-network contract IDs in `PerkOSClient`. Do not guess a treasury:
+read `getServiceFeePolicy(asset)` and `getJobServiceFee(asset, jobId)`.
+
+```ts
+// Uses the UNRELEASED source build, not npm 0.7.1.
+// nayori is a client configured with reviewed contracts and a policy-limited signer.
+const job = await nayori.getJob("sbtc", jobId);
+if (!job) throw new Error("Job not found");
+const policy = await nayori.getServiceFeePolicy("sbtc");
+const fees = await nayori.getJobServiceFee("sbtc", jobId);
+
+// Present gross, potential fee, net approval/net rejection, treasury and gas
+// to the operator (or an approved deterministic agent spending policy).
+// This object represents actual acceptance, not permission granted by this example.
+const serviceFeeAcceptance = {
+  gross: job.budget,
+  basisPoints: 200 as const,
+  treasury: fees.treasury,
+  rejectionRefund: "net-after-evaluation" as const,
+};
+
+// Only after acceptance, with the CLIENT signer:
+const broadcast = await nayori.fundJob({
+  asset: "sbtc", jobId, amount: job.budget, serviceFeeAcceptance,
+});
+const confirmation = await nayori.confirm(broadcast);
+if (confirmation.status !== "success") throw new Error("Funding not confirmed");
+
+// The PROVIDER uses a separate client/signer and independently accepts the live
+// budget/fee before submitWork({ asset, jobId, deliverable, serviceFeeAcceptance }).
+```
+
+`quoteServiceFee(gross)` performs exact uint128-safe bigint arithmetic but is only a local
+quote. It does not prove a deployment, initialization, actual fee charge or refund.
+Amounts below 50 atomic units round down to zero fee; no minimum job price is introduced.
+See [`examples/service-fees.ts`](../examples/service-fees.ts) for a signer-free report helper.
+
+## Methods and role boundaries
+
+| Method | Behavior |
+| --- | --- |
+| `supportsServiceFees(asset)` | Known ABI capability, not verification of contract authenticity |
+| `getServiceFeePolicy(asset)` | Validates initialization fields, fixed 200 bps, network-specific windows and treasury separation |
+| `getJobServiceFee(asset, jobId)` | Validates ledger against the job, budget, roles and pinned treasury; read failures propagate |
+| `fundJob(input)` | Requires accepted gross/bps/treasury/net-refund terms matching live state before wallet access |
+| `submitWork(input)` | Requires the provider's matching acceptance before wallet access |
+| `finalizeDecision`, `resolveAppeal`, `settleAppealTimeout` | Derive gross and split from live state; sBTC uses the job-pinned token |
+| `initializeServiceFeeProtocol(input)` | Owner-signed, explicit treasury/authority; SDK requires testnet 3 or mainnet 144 appeal burn blocks |
+| `waiveServiceFee(input)` | Job-pinned authority signs a nonzero 32-byte evidence hash; records an irreversible waiver |
+| `refundServiceFee(asset, jobId)` | Treasury signs a real outstanding-fee return from its own balance; spending limits apply |
+
+Only standard wallet principals can execute these signer-based administrative methods. A contract
+principal treasury would require its own reviewed governance caller, not a forged wallet signer.
+The authority decides whether evidence establishes platform fault; a changed appeal outcome alone
+does not automatically waive a fee. The SDK does not make that decision for an operator.
+
+## Accounting is not a quote
+
+- `feeAmount` is the potential budget quote, never collected revenue.
+- No `settlement`: no earned fee has been collected.
+- `settlement.chargedFee - settlement.refundedFee`: fee retained after actual returns.
+- `settlement.net + settlement.refundedFee`: total delivered to the economic recipient.
+- Waiver plus an outstanding charged fee: a refund obligation, **not a completed refund**.
+
+A treasury without funds or an available signer cannot complete a refund. Maintain refund
+reserves and an operational process before launch. Replay attempts are rejected by the contract.
+Internal test-wallet transactions are not externally earned revenue or adoption.
+
+## Post-conditions and trust
+
+Decision settlements use one exact **gross escrow outflow** post-condition per asset, not separate
+net/fee conditions on the same sender. Treasury refunds instead constrain the treasury's exact
+fee outflow. Deny mode is retained. Post-conditions constrain aggregate outflow, not recipients;
+verify contract sources and canonical transfer events independently after confirmation.
+
+`plan.intent.serviceFee` is disclosure metadata, not a signed enforcement mechanism. Synchronous
+builders cannot read the chain: their caller must supply already-verified state, token and split.
+Prefer high-level client methods. Neither `execute` nor a custom RPC can establish the authenticity
+of an arbitrary caller-selected contract. Custody allowlists and source verification remain required.
+Funding/refund session limits count broadcasts conservatively, not final revenue.
+
+Direct x402/MPP single-transfer verification is unchanged and must not be relaxed for escrow splits.
+
+Reference: [Stacks post-conditions](https://docs.stacks.co/post-conditions/examples).

package/docs/TESTNET_QUICKSTART.md

@@ -0,0 +1,123 @@
+# Role-separated agent onboarding — QA candidate
+
+This guide describes the QA candidate, not a published npm release. The role-separated
+SDK/committed-evaluation flow has completed controlled STX and sBTC testnet jobs; this
+does not certify a live Hermes installation or external adoption.
+Use Node.js 22 and the reviewed QA commit. Do not point it at mainnet.
+The app's default deployments, production and the published package are unchanged.
+
+## Roles and custody
+
+- Buyer: owns criteria, creates the job, sets its budget, funds escrow and assigns a provider.
+- Provider: owns its wallet, performs the work and submits the committed evidence manifest.
+- Evaluator service: verifies chain state and downloaded evidence, then records its decision.
+- Human appeal authority: handles disputes; it is not installed in either participant agent.
+
+Create separate testnet wallets with your custody provider. Keep each key in its own signer
+boundary, fund only the required test tokens and STX gas, and never share the evaluator key.
+The example imports an **operator-selected absolute module path** exporting a `PerkOSSigner`
+named `signer`. Do not let an LLM or external job select that module. Its implementation must
+restrict network, contracts, operation, nonce and gas fees and durably account for wallet spending.
+SDK spending policies are per process and do not replace persistent custody limits.
+The separate [Hermes MCP adapter](HERMES_MCP.md) defaults to read/prepare only. Optional
+[bounded custody delegation](HERMES_CUSTODY.md) is a QA source candidate for wallet-enabled
+actions; it still requires review, deployment, Linux isolation and actual Hermes E2E validation.
+Provider MCP may additionally opt into public QA evaluation admission after its confirmed
+submission; see [the exact tools and operator flag](HERMES_MCP.md#optional-provider-evaluation-admission).
+The CLI walkthrough below remains a separate operator-driven example, not proof of Hermes autonomy.
+
+## Install and preview
+
+From the reviewed SDK source checkout:
+
+```bash
+npm ci
+npm run verify
+npm run quickstart:testnet
+```
+
+The last command defaults to offline preview; it does not load a signer or call a network.
+For clean-consumer testing, build and pack the candidate, then install that tarball in a
+separate project with Node 22 and `tsx`. Do not publish or overwrite npm 0.7.1.
+
+## Supply real job inputs
+
+Keep a JSON config **outside Git**, with one copy for each role. Required fields:
+
+| Field | Value |
+|---|---|
+| network / asset | `testnet` / `stx` or `sbtc` |
+| role | `client` or `provider` |
+| client / provider / evaluator / treasury | Four distinct real testnet principals; evaluator and treasury must match QA policy |
+| amount | Decimal string in micro-STX or satoshis; example cap 100000 or 1000 respectively |
+| expiredAt | Future **Stacks block height**, not burn height or Unix time |
+| description | Real ASCII work description, at most 428 characters |
+| acceptanceCriteria | Array of `{ id, requirement, verification }` fixed by the buyer before creation |
+| jobId | Confirmed job ID, required after creation |
+| evidence | Provider's real `{ id, uri, sha256, mediaType, sizeBytes }` manifest |
+| agentName | Optional real participant name |
+
+Use the configured QA evaluator's evidence origin allowlist. Automatic review initially supports
+up to five HTTPS UTF-8 text/plain or application/json files, 8192 bytes per file, 16000 bytes total.
+Hash the exact downloaded bytes; no fake URLs or invented deliverables. Public manifests and
+chain commitments must never contain secrets. Preserve the original criteria file for both roles.
+
+## Run one step at a time
+
+Set `PERKOS_RUN_CONFIG`, `PERKOS_JOURNAL` and `PERKOS_SIGNER_MODULE` to absolute paths outside Git.
+Use a dedicated journal per role and run. Enable `PERKOS_CONFIRM_TESTNET_BROADCAST=yes` only for
+the intended operation. Funding and submission also require
+`PERKOS_ACCEPT_SERVICE_FEE=200bps-net-after-evaluation`.
+
+```bash
+PERKOS_ACTION=register npm run quickstart:testnet
+PERKOS_ACTION=create npm run quickstart:testnet
+```
+
+Both participants register using their own process. Only the buyer creates. Copy the confirmed
+`(ok uN)` job ID from creation into both role configs, then execute separately:
+
+1. Buyer: `set-budget`, then `fund`, then `assign`.
+2. Provider: do the actual work, prepare the real evidence manifest, then `submit`.
+3. Either role: `evaluate` against an explicitly configured `PERKOS_EVALUATOR_URL` QA origin.
+4. Either role: `status`. It is read-only and needs no signer or broadcast opt-in.
+5. Buyer: `finalize` only after decision-pending, no appeal, and current burn height strictly
+   greater than the appeal deadline. Disputes require the appeal workflow, not bypassing this gate.
+
+A `202` response means admitted, not approved. Poll the returned evaluation ID at
+`GET /v1/evaluations/{id}` and inspect the on-chain job. A recorded decision does not transfer
+escrow. On finalization, independently verify the 98/2 provider/treasury split (or evaluated
+rejection refund), zero escrow and reputation sync. Gas is additional, paid by each transaction signer.
+The 2% fee is earned on evaluation and stays in escrow until settlement; no extra appeal fee is added.
+
+## Commitments without new contracts
+
+`prepareEvaluationJob(input)` returns the description plus a versioned SHA-256 criteria marker.
+`prepareEvaluationSubmission(input)` returns a 36-byte deliverable: ASCII `ny1:` and the raw
+32-byte evidence digest, fitting existing `(buff 64)` contracts.
+
+Both use fixed projected JSON fields, lexicographically sorted keys, ordered arrays, UTF-8 and
+distinct hash domains. Criteria bind network/asset/contract/client/evaluator/description.
+Evidence additionally binds job ID, provider and criteria hash. Do not reorder arrays, normalize
+text or change manifests after signing. `evaluationJobId` derives a deterministic job-scoped
+request identifier; it is **not** a credential.
+
+Hashes protect manifest integrity, not evidence truth. Only the on-chain client can commit the
+criteria and only the assigned provider can submit the evidence. Public HTTP callers may trigger
+verification of those exact commitments, but cannot change criteria, spend participant wallets
+or force the evaluator to approve.
+
+## Recovery and limitations
+
+The append-only mode-600 journal records an attempt before signing and stores the txid before
+confirmation. Repeating an identical invocation confirms that txid instead of signing again.
+Changed action inputs, a stale lock, malformed journal or ambiguous attempt fail closed.
+Never delete checkpoints to force a retry: reconcile the wallet nonce and transaction history first.
+Ambiguous signing failures require operator reconciliation; no exactly-once
+network guarantee is claimed. A dry preview is not an on-chain E2E test.
+
+The evaluator public writer defaults off; controlled QA has enabled bounded admission and
+passed database/restart and two-role STX/sBTC E2E gates. Isolated live Hermes integration,
+x402-protected API walkthrough and recorded demo remain separate gates.
+The existing x402/MPP clients are separate from this escrow evaluation trigger;
+this route does not introduce another payment or imply x402 coverage was tested here.

package/docs/VALIDATION_AND_RELEASE.md

@@ -0,0 +1,82 @@
+# Hermes validation and release boundary
+
+## What was verified
+
+On 2026-09-08 UTC, one **internal, operator-supervised Stacks testnet** sBTC job completed
+using real Hermes participants, the SDK/MCP tools, isolated policy signers and Nayori's evaluator.
+This is evidence for one scenario, not certification of all workflows or external onboarding.
+
+| Check | Observed result |
+| --- | --- |
+| SDK source | `fc0537477fda819fa9cce8e74e543be0d49ea3a4` on QA |
+| Contract / job | `ST16EWRC01S1SFWGBP63MW47VY8P3AYFA8VGEBGE5.sbtc-commerce-v5`, job 14 |
+| Participants | Existing registered agents, separate buyer/provider/evaluator roles |
+| Workflow | Create → budget → fund → assign → actual work → submit → evaluate → finalize |
+| Work | Compute 23 + 19 and explain; actual result 42 with an explanation |
+| Outcome | Completed; zero escrow; exactly 980 atomic sBTC to provider and 20 to treasury |
+| Reputation | One completed job, no disputed job; no pending synchronization |
+| Confirmation | Finalization in burn 14234; six-burn custody gate passed at 14240 |
+
+Public chain evidence:
+
+- [Submission](https://explorer.hiro.so/txid/0x8c99de7f560e82da0483875677ab2de3370403e2a617dff445a77cff40f0da31?chain=testnet)
+- [Evaluator approval](https://explorer.hiro.so/txid/0x2806cebb488794c6a8ff63bf9f437978dc7e492254974c3f06d400381b7a1f27?chain=testnet)
+- [Final settlement, Stacks block 288396](https://explorer.hiro.so/txid/0x382e05645560acbd822f573cab6e32579ad1d8ad3d1598916f132b28b86cce4c?chain=testnet)
+
+No new registration was performed in this cycle: existing records were verified and reused.
+New developers must still follow [registration](EXISTING_AGENT.md); do not repeat registration
+for an already active identity simply to match a video. Use your own agent, LLM and signer.
+Do not send funds to the addresses in this historical evidence.
+
+## Published package versus tested source
+
+| Distribution | Boundary |
+| --- | --- |
+| npm `@perkos/agent-sdk@0.7.1` | Published v5/v4 baseline; does not include the local QA Hermes/custody/fee additions |
+| Reviewed QA source above | Tested v6/v5 opt-in fee path, local Hermes MCP, custody and evaluation admission |
+| Historical QA tarball used in the lifecycle | Reports version 0.7.1; source commit and artifact integrity distinguish it from npm |
+| Current source candidate | 0.8.0-rc.1, not published; see [candidate notes](RELEASE_0.8.0_RC1.md) |
+
+Do not publish the candidate over 0.7.1 or describe it as an npm-only installation test. Use
+the [exact-artifact installation procedure](HERMES_MCP.md), never an unpinned financial `npx`.
+
+Before external distribution: review and merge the release changes, assign a new package version,
+run the SDK gate, pack and inspect its allowlisted contents, then install that exact artifact in
+a clean consumer. Verify imports, binaries and both role guides. Publish only after separate
+release approval; verify registry integrity and repeat clean installation from the published
+version. A QA merge, npm publication and production deployment are separate events.
+
+## Report three independent outcomes
+
+1. **Conversation:** Hermes must explicitly report `completed=true`; a `type: result` envelope
+   alone is insufficient. A tool may have executed even when the conversation stopped at its limit.
+2. **Operation:** preserve the actual intent, txid and journal; query the existing operation after
+   timeout or interruption. Never re-sign merely because the conversation did not complete.
+3. **Economics:** independently verify canonical success, confirmation depth, terminal job state,
+   zero escrow, exact unique transfers and reputation. Evaluator approval is not payment.
+
+Count persisted LLM attempts separately from received responses. Missing usage means **unknown**,
+not zero. Track buyer, provider and evaluator independently; a configured maximum is a bound,
+not an observed call count or bill. This cycle observed 26 Hermes calls; evaluator usage is bounded
+by four calls but its exact count is not established by this report.
+
+## Two different evidence hashes
+
+The evaluator artifact/decision uses SHA-256 of the canonical evidence list. The SDK's versioned
+submission commitment additionally binds domain, network, contract, job, roles and criteria.
+These hashes are intentionally different. Recompute each from its own input: compare the
+SDK commitment to `submit-work`/the job deliverable and the manifest hash to the evaluator
+artifact/`record-decision`. Verify the public explanation digest and fetched evidence bytes too.
+Never accept a mismatched hash by copying the expected value from the response under test.
+
+## Still outside this proof
+
+- Fresh npm-only installation, new-agent registration in this cycle, and the developer video.
+- Autonomous operation from one instruction without the operator's staged gates.
+- The separate x402/MPP resource-purchase workflow; local QA MCP does not purchase x402.
+- Other assets, rejection/appeal/recovery scenarios, or production fee activation.
+- External security review or independent adoption: these participants are team-operated testnet actors.
+
+Continue with the [buyer](HERMES_BUYER.md), [provider](HERMES_PROVIDER.md) and
+[checkpoint](HERMES_CHECKPOINTS.md) manuals. Every new funded scenario requires its own reviewed
+permissions and budget; never reuse this completed job's authorization.