xytara 3.1.17 → 3.2.0

package/README.md

@@ -1,135 +1,163 @@
 # xytara
 
+**Client for the hosted naxytra runtime.** naxytra is a pay-per-call runtime for AI agents: an
+agent discovers a capability, pays once with x402 (gasless USDC on Base) or spends credits, gets a
+real deliverable, and receives a signed delivery receipt it can verify offline. The same runtime is
+exposed as a pay-per-call MCP server. The proof-side half of the stack is
+[xoonya](https://naxytra.com/xoonya).
+
+> The runtime is a hosted service; this package is the client. The server is not distributed.
+
 Listed on [Smithery](https://smithery.ai/server/naxytra/xytara-mcp-executor) · [Glama](https://glama.ai/mcp/servers/naxytra/xytara-mcp-executor) · the official MCP registry (`com.naxytra/xytara-mcp-executor`).
 
-**x402 pay-per-call agent-commerce runtime** — the payment and execution layer of the naxytra
-machine stack. An agent discovers a capability, pays once with x402 (gasless USDC on Base), and gets
-a real deliverable, settled on-chain, with the revenue split reconciled in the ledger and paid out
-on-chain, plus a signed delivery receipt. The proof-side half is
-[xoonya](https://naxytra.com/xoonya).
+## What you get
 
-## Proven live on Base mainnet
+| Hosted surface | URL |
+| --- | --- |
+| Runtime (paid command path, credits, catalog, receipts) | `https://xytara.onrender.com` |
+| Pay-per-call MCP server (Streamable HTTP) | `https://xytara-mcp-executor.onrender.com/mcp` |
+| Website, agent guide, quickstart | `https://www.naxytra.com` · [/agents](https://www.naxytra.com/agents) · [/quickstart](https://www.naxytra.com/quickstart) |
 
-All demonstrated end to end on Base mainnet (provider-payout transactions are publicly verifiable —
-see **Proof** below):
+This package ships:
 
-- **Open settling provider network** — a paid x402 call routes to an independently-registered
-  execution provider, returns a real deliverable, and splits revenue — reconciled in the ledger and
-  paid out on-chain (platform keeps the remainder).
-- **Automated on-chain provider payouts** — a key-less runtime dispatches to an external signer that
-  sends USDC on Base; reconciled, idempotent, double-pay-safe.
-- **Cryptographic bounded delegated spend** — a stolen bearer token cannot spend; each spend requires
-  a fresh ed25519 signature bound to the exact account, amount, and task.
-- **Pay-per-call MCP** — 17 deterministic tools at a public endpoint, no API keys, no account.
+- `CommerceClient` — discover the catalog, quote, run the paid command path, read results
+- the delivery-receipt verifier — `verifyDeliveryReceipt`, `canonicalize`, `hashCanonical`, `keyRef`
+- x402 header helpers — `encodeX402PaymentHeader`, `decodeX402Header`
+- the `xytara` / `xytara-run` CLIs (quote-only first, then funded execution)
+- `endpoints` (runtime, mcp, website) and `version`
 
-## Pay-per-call MCP (the easy on-ramp)
+Nothing in this package runs a runtime: no server, no payment or settlement engine, no routing,
+no state store, no operator tooling.
 
-The public MCP executor is a genuine pay-per-call endpoint:
+## Install
 
-```
-endpoint:   https://xytara-mcp-executor.onrender.com/mcp
-tools/list  -> free (17 deterministic tools)
-tools/call  -> 402 Payment Required with a price
-            -> sign ONE gasless USDC authorization (x402 / EIP-3009)
-            -> the Coinbase CDP facilitator verifies it; the tool runs
-            -> only if the tool succeeds is the payment settled on Base (a failed call is not charged)
-            -> the response carries the result, the on-chain settlement receipt, and a signed
-               delivery receipt in result._meta["naxytra.com/delivery-receipt"]
+```bash
+npm install xytara
 ```
 
-## Signed delivery receipts
+Node >= 18 (built-in `fetch` and `node:crypto`), no dependencies.
 
-Every paid call returns a `naxytra-delivery-receipt/1`: the payment leg (for x402, the network,
-asset, amount, payer, pay_to, and settlement transaction), the provider that delivered, and the
-SHA-256 of the canonical request and of the delivered output — signed over its JCS (RFC 8785)
-canonical form with Ed25519, plus ML-DSA-65 (FIPS-204) where the issuer has a post-quantum key. The
-signed suite is part of the signed bytes, so stripping a signature fails verification.
+## Quickstart (CLI)
 
+```bash
+xytara start-here        # the shortest first-run path
+xytara first-run         # guided quote -> pay/credits -> execute -> prove
+xytara run --help
 ```
-GET  /.well-known/delivery-receipt-keys   # the issuer's public keys (pin them)
-GET  /v1/delivery-receipts/:receipt_id    # fetch a receipt the runtime issued
-POST /v1/delivery-receipts/verify         # free signature check
+
+Quote first, with no wallet material at all:
+
+```bash
+xytara-run --url https://xytara.onrender.com --account ACCOUNT_REF \
+  --task adapter.mcp.invoke --command mcp.invoke:summarize \
+  --body-json "{\"tool_name\":\"summarize\",\"arguments\":{\"text\":\"Summarize the naxytra first-run path in one sentence.\"}}" \
+  --quote-only --pretty
 ```
 
-Verify independently: recompute `sha256(JCS(output you received))`, check the settlement
-transaction on-chain, and verify each signature over the canonical bytes with `node:crypto` or
-xoonya's `verifyExternalProofSignature` (the receipt's `kid` is the key ref xoonya reports).
-A receipt proves who delivered what for which paid call, unaltered since signing — **not** whether
-the output was correct or good.
+## Quickstart (CommerceClient)
 
-Tools: `summarize`, `text.extract`, `html.to-text`, `text.chunk`, `json.validate`, `zones.lookup`,
-`keccak256`, `address.validate`, `abi.encode`, `abi.decode`, `merkle.verify`, `eip712.hash`,
-`x402.decode`, `x402.verify-receipt`, `tx.status`, `reply.draft`, `catalog`.
+Discover, get the 402 challenge, pay with one x402 authorization, receive the result and the receipt.
 
-## Install
+```js
+const { CommerceClient, encodeX402PaymentHeader, verifyDeliveryReceipt, hashCanonical, endpoints } = require("xytara");
 
-```bash
-npm install xytara
-```
+const client = new CommerceClient({ baseUrl: endpoints.runtime, accountId: "acct_your_agent" });
+const task = await client.getTask("adapter.mcp.invoke");                     // 1. discover
+const payload = { command: "mcp.invoke:summarize", task_ref: task.task_ref,
+  body: { tool_name: "summarize", arguments: { text: "Summarize this." } } };
 
-## Quickstart
+const challenge = await client.previewExecutionQuote(payload, { instant: true }); // 2. 402 challenge
+const accepted = challenge.accepts[0];            // { scheme, network, asset, amount, payTo, extra }
 
-```bash
-xytara start-here        # the shortest first-run path
-xytara first-run         # guided discover -> quote -> pay -> execute -> prove
-xytara run --help
-npm start                # run the xytara runtime yourself (see .env.example)
+// 3. Sign ONE EIP-3009 TransferWithAuthorization for `accepted` with your wallet (viem, ethers,
+//    or a hosted signer): domain { name: accepted.extra.name, version: accepted.extra.version,
+//    chainId, verifyingContract: accepted.asset }, message { from, to: accepted.payTo,
+//    value: accepted.amount, validAfter, validBefore, nonce }. Then send it as the payment header.
+const paymentHeader = encodeX402PaymentHeader({ accepted, authorization, signature });
+const paid = await client.postJson("/x402/commands/execute", { "payment-signature": paymentHeader },
+  { account_id: client.accountId, ...payload, quote_id: challenge.quote.quote_id });
+
+const output = paid.data.command.deliverables[0].output_payload;             // 4. result
+const receipt = paid.data.delivery_receipt;                                   //    + signed receipt
+const keys = (await client.getJson("/.well-known/delivery-receipt-keys")).data.keys;
+console.log(verifyDeliveryReceipt(receipt, keys).valid, hashCanonical(output) === receipt.delivery.output_sha256);
 ```
 
-## What it does
+The payment is settled on Base only if the call succeeds; a failed call is not charged. The
+settled transaction comes back in the `PAYMENT-RESPONSE` header (`decodeX402Header`) and inside
+`receipt.payment.settlement_tx`.
 
-- discover tasks and workflows, and quote work before execution
-- pay via x402 (gasless USDC on Base) or spend from reusable credits
-- route to an execution provider and receive the deliverable
-- meter usage, reconcile settlement, and handle refunds/disputes
-- integrate third-party adapters; emit proof-compatible facts for xoonya verification
+Credits instead of a signature per call: `POST /x402/credits/topup` returns the same kind of 402
+challenge; pay it once and the response carries a spend credential. Then call
+`/x402/commands/execute` with `payment_preference: "credits_first"` and
+`Authorization: Bearer <spend_credential.bearer_token>`.
 
-xytara owns execution, quoting, payment, delivery, lifecycle, and integration. It emits
-proof-compatible facts; canonical proof lives in [xoonya](https://naxytra.com/xoonya).
+## Pricing
 
-## The open provider network
+- **$0.01 USDC per call** on Base mainnet (`eip155:8453`); **$0.001** on Base Sepolia (`eip155:84532`).
+- **Credits:** $1.00 buys 400 credits (mainnet only); one credit per call unit as quoted.
+- Executable task refs today: `adapter.mcp.invoke` and `adapter.xoonya.invoke`. Everything else in
+  the catalog is discoverable and quotable but not executable.
+- Settlement runs through the x402 facilitator lane (gasless for the payer, USDC on Base). Other
+  assets and networks (for example USD₮ or Celo) are not live.
 
-Any execution provider can plug in. Register an endpoint that serves one or more capabilities; once
-the operator activates it, the runtime routes paid (x402-settled) agent calls to your `/execute`,
-surfaces your output as the buyer's deliverable, splits the revenue, and reconciles a payout ledger.
-The machine-readable integration contract is public:
+## Pay-per-call MCP
 
 ```
-GET  /v1/provider-network/contract      # how to integrate (fields, routing, economics, lifecycle)
-GET  /v1/provider-network/providers     # public discovery
-POST /v1/provider-network/register      # register your provider
+endpoint:   https://xytara-mcp-executor.onrender.com/mcp
+tools/list  -> free
+tools/call  -> 402 Payment Required with a price
+            -> sign ONE gasless USDC authorization (x402 / EIP-3009)
+            -> the facilitator verifies it; the tool runs
+            -> only if the tool succeeds is the payment settled on Base
+            -> the response carries the result, the settlement receipt, and a signed
+               delivery receipt in result._meta["naxytra.com/delivery-receipt"]
 ```
 
-Routing is health-aware with reputation-weighted ordering and in-request failover on
-provably-not-processed failures only (no double-execution).
+Point any MCP client at the endpoint; the public integration guide is
+[github.com/naxytra/naxytra-mcp](https://github.com/naxytra/naxytra-mcp).
 
-## Payment rails
+## Signed delivery receipts
 
-x402 (gasless USDC on Base, via the Coinbase CDP facilitator) is the proven pay-per-call rail; A2A,
-A2C, and BOLT (BSV) are also supported. Treasury settlement destinations are configured privately by
-the operator — real treasury and custody details are never in public surfaces.
+Every paid call returns a `naxytra-delivery-receipt/1`: the payment leg (network, asset, amount,
+payer, pay_to, settlement transaction), the provider that delivered, and the SHA-256 of the
+canonical request and of the delivered output — signed over its JCS (RFC 8785) canonical form with
+Ed25519, plus ML-DSA-65 (FIPS-204) where the issuer holds a post-quantum key. The signed suite is
+part of the signed bytes, so stripping a signature fails verification. Ed25519 and ML-DSA-65 are
+the only algorithms in use.
 
-## Honesty & boundaries
+```js
+const { verifyDeliveryReceipt, hashCanonical, verificationRecipe } = require("xytara");
 
-The runtime is **key-less**: payout auto-execution is a deliberate custody decision handled by an
-external signer that holds the treasury key, never a key in the runtime. xytara emits
-proof-compatible facts but does not define proof semantics — that is [xoonya](https://naxytra.com/xoonya).
+const keys = (await fetch("https://xytara.onrender.com/.well-known/delivery-receipt-keys").then((r) => r.json())).keys;
+const result = verifyDeliveryReceipt(receipt, keys);      // { valid, signatures: [{ alg, kid, valid }], ... }
+const outputMatches = hashCanonical(outputYouReceived) === receipt.delivery.output_sha256;
+console.log(verificationRecipe("/.well-known/delivery-receipt-keys").steps);
+```
 
-## Proof
+```
+GET  /.well-known/delivery-receipt-keys   # the issuer's public keys (pin them)
+GET  /v1/delivery-receipts/:receipt_id    # fetch a receipt the runtime issued
+POST /v1/delivery-receipts/verify         # free signature check
+```
 
-Automated provider payouts, verifiable on Base mainnet (Basescan):
-`0x264be245f6d58c0251bc1d9cbd124fdc46ad73ed746d7a07e750c522c37cac5b`,
-`0x6aff9701556fe00cfb076f36a0cc27296619f1539d0c39242e98123abc288caa`,
-`0xdba7cfef18e46da2cbb9a87a087df9fa1c790793bd9ab1034febe244d4565f36`.
+A receipt proves who delivered what for which paid call, unaltered since signing — **not** whether
+the output was correct or good. Check the settlement transaction on-chain yourself.
+
+## Verify the package
+
+```bash
+npm run verify:release-candidate   # offline: package surface, receipts, the paid path against a local stub, the CLIs
+npm run verify:client
+```
 
-## Learn more
+## Links
 
-- Why two packages: [`WHY_XYTARA_XOONYA.md`](./WHY_XYTARA_XOONYA.md)
-- Payment rail model: [`XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md`](./XYTARA_PAYMENT_RAIL_TRUTH_MODEL.md)
-- Real payment setup: [`REAL_PAYMENT_SETUP.md`](./REAL_PAYMENT_SETUP.md)
-- Start here: [`START_HERE.md`](./START_HERE.md) · terminology: [`TERMINOLOGY.md`](./TERMINOLOGY.md)
-- Live: https://naxytra.com/xytara · MCP endpoint: https://xytara-mcp-executor.onrender.com/mcp
+- Agent guide: https://www.naxytra.com/agents · quickstart: https://www.naxytra.com/quickstart
+- MCP integration guide: https://github.com/naxytra/naxytra-mcp
+- Proof side: [xoonya](https://naxytra.com/xoonya) · start here: [`START_HERE.md`](./START_HERE.md)
 
 ## License
 
-Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
+Apache-2.0 for this client package. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE). The hosted
+runtime is a proprietary service.

package/RELEASE_NOTES.md

@@ -1,4 +1,9 @@
-`xytara` 3.1.17 makes the pay-per-call MCP server more tolerant of real-world MCP clients.
+`xytara` 3.2.0 turns the npm package into a thin client for the hosted naxytra runtime. The runtime is a hosted service; this package is the client. The server is not distributed.
 
-- **Optional methods answered** — `logging/setLevel` is accepted (the server emits no log notifications) and `completion/complete` returns an empty completion, both declared in the server's capabilities, so clients that call them unconditionally no longer get "method not found". Paid tool calls are unchanged.
+- **What the package now contains** — `client.js` (the entry), the buyer-side `CommerceClient`, the delivery-receipt verifier, the `xytara` / `xytara-run` CLIs, two offline verification scripts, and the docs. Nothing else: no server, no payment or settlement engine, no routing, no state store, no fixtures, adapters, integrations or operator tooling.
+- **`require("xytara")` is now the client surface** — `CommerceClient` and the commerce helpers as before, plus `verifyDeliveryReceipt`, `canonicalize`, `hashCanonical`, `keyRef`, `verificationRecipe`, `RECEIPT_VERSION`, the x402 header helpers `encodeX402PaymentHeader` / `decodeX402Header`, an `endpoints` constant (runtime, mcp, website) and `version`. An `exports` map keeps `xytara`, `xytara/client`, `xytara/lib/commerce_client`, `xytara/lib/delivery_receipt_verify`, `xytara/bin/*` and `xytara/package.json` resolvable.
+- **Delivery-receipt verification stands alone** — the verification side of `naxytra-delivery-receipt/1` (JCS canonical form, hashes, key refs, verifier, recipe) ships as `lib/delivery_receipt_verify.js`; issuing and signing stay in the hosted runtime and MCP executor.
+- **CLI** — `xytara release` is no longer part of the package (it prints a notice and exits 2); `xytara-release` is gone from `bin`. `xytara start-here`, `xytara first-run` and `xytara-run` are unchanged.
+- **Release gate** — `npm run verify:release-candidate` now runs with Node built-ins only, asserts the published tarball contains exactly the thin client file list, and runs `scripts/verify_client.js`: an offline check of the package surface, receipt verification (genuine, tampered, stripped, unsigned, untrusted key), the paid command path against a local stub of the runtime (discover, 402 challenge with x402 accepts, paid 200 with a signed receipt), and the CLIs. It also runs inside an installed `node_modules/xytara`.
+- **Docs** — README and START_HERE rewritten for the client: hosted endpoints, pricing ($0.01 USDC per call on Base mainnet, $0.001 on Base Sepolia, credits $1.00 = 400), a `CommerceClient` walk-through from discover to a verified receipt, and the public MCP integration guide. Self-hosting text, `npm start` and `.env.example` are gone.
 - Published through npm trusted publishing (GitHub OIDC) — no npm token involved.

package/START_HERE.md

@@ -1,272 +1,104 @@
 # xytara Start Here
 
-This is the shortest reliable path for understanding and using the public `xytara` package in production-facing order.
+The shortest reliable path to a first paid call on the hosted naxytra runtime with the `xytara`
+client package.
 
-The phase program is now complete, so this file is the right starting point for a closed and release-shaped runtime rather than an in-flight milestone build.
+The runtime is a hosted service; this package is the client. The server is not distributed.
 
-The synchronized `3.0.0` launch line shipped and is live. The current public line is the synchronized security and stability release described in RELEASE_NOTES.md; operator write surfaces fail closed and payment acceptance defaults to signed verification, so configure the operator tokens and a wallet registry before expecting paid or operator flows to work.
+## 1. The role
 
-## 1. Understand The Role
+`xytara` is the transaction-side client of the public stack. It lets an agent:
 
-`xytara` is the transaction-side half of the public stack.
+1. discover a machine capability from the hosted catalog
+2. quote the call before paying anything
+3. pay once with x402 (gasless USDC on Base) or spend credits
+4. receive the deliverable and a signed delivery receipt
+5. hand the result into `xoonya` for proof review
 
-Its job is to let a caller:
-
-1. discover a machine capability
-2. quote or preview the path
-3. execute through the default transaction flow
-4. inspect result and lifecycle state
-5. hand the result into `xoonya` for proof-native completion
-
-## 2. Run The Fastest Real Example
-
-For an outside builder, the shortest public spine is:
+Public first-run spine:
 
 ```text
 quote -> pay/credits -> execute -> prove
 ```
 
-Open:
+## 2. Hosted endpoints
 
 ```text
-https://www.naxytra.com/v1/first-run-path
-https://www.naxytra.com/v1/first-run-kit
+runtime:  https://xytara.onrender.com
+          POST /x402/commands/execute      paid command path (402 challenge -> paid 200)
+          POST /x402/credits/topup         buy credits once, spend them per call
+          GET  /v1/catalog                 discover tasks
+          GET  /.well-known/delivery-receipt-keys
+          POST /v1/delivery-receipts/verify
+mcp:      https://xytara-mcp-executor.onrender.com/mcp
+website:  https://www.naxytra.com  (/agents, /quickstart, /v1/first-run-path, /v1/first-run-kit)
 ```
 
-The first safe runtime command is quote-only:
-
-```bash
-xytara first-run --run-quote --account ACCOUNT_REF --pretty
-```
+Price: $0.01 USDC per call on Base mainnet, $0.001 on Base Sepolia. Credits: $1.00 = 400.
+Executable task refs: `adapter.mcp.invoke`, `adapter.xoonya.invoke`.
 
-The underlying command is:
+## 3. First run
 
 ```bash
-xytara-run --url https://xytara.onrender.com --account ACCOUNT_REF --task adapter.mcp.invoke --command mcp.invoke:summarize --body-json "{\"tool_name\":\"summarize\",\"arguments\":{\"text\":\"Summarize the naxytra first-run path in one sentence.\"}}" --quote-only --pretty
+npm install xytara
+xytara start-here
+xytara first-run
 ```
 
-If you want the frozen machine-readable default-path contract behind those starter commands, inspect:
-
-```text
-GET /v1/default-path
-GET /v1/default-path/summary
-```
+Quote safely first (no wallet material needed):
 
-If you want the frozen machine-readable payment and rail claim boundary behind those execution paths, inspect:
-
-```text
-GET /v1/payment-rail-truth
-GET /v1/payment-rail-truth/summary
-```
-
-If you want the frozen machine-readable adapter and protocol front claim boundary behind those execution paths, inspect:
-
-```text
-GET /v1/adapter-protocol-truth
-GET /v1/adapter-protocol-truth/summary
+```bash
+xytara first-run --run-quote --account ACCOUNT_REF --pretty
 ```
 
-If you want one compressed public surface that exposes the real outside-agent entry, payment breadth, treasury claim boundary, and full-catalog reach in one place, inspect:
+which runs:
 
-```text
-GET /v1/autonomous-entry
-GET /v1/autonomous-entry/summary
+```bash
+xytara-run --url https://xytara.onrender.com --account ACCOUNT_REF --task adapter.mcp.invoke --command mcp.invoke:summarize --body-json "{\"tool_name\":\"summarize\",\"arguments\":{\"text\":\"Summarize the naxytra first-run path in one sentence.\"}}" --quote-only --pretty
 ```
 
-Then execute with direct signed payment or a credits-first funded account:
+Then execute with a signed x402 payment (see the `CommerceClient` example in README.md) or
+credits-first on a funded account:
 
 ```bash
 xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty
 ```
 
-Then hand the result into `xoonya` for proof review and verification:
+Then prove with `xoonya`:
 
 ```bash
 xoonya first-run --verify-native --pretty
 ```
 
-## 3. Run The Fastest Local Package Example
-
-Run:
-
-```bash
-node examples/quickstart.js
-```
-
-This is the fastest way to see the intended package story end-to-end.
+## 4. Programmatic use
 
-If you want the clearest cross-repo adoption path instead of the broad package tour, continue with:
-
-- CARRIED_HANDOFF_DEMO.md
-
-If you want the shortest neutral external-adoption bundle, continue with:
-
-- PARTNER_READY_PATH.md
-- PUBLIC_DEMO_SCRIPT.md
-- EXAMPLE_PATHS.md
-- `node examples/partner_launch_walkthrough.js`
-
-## 4. Verify The Whole Package
-
-Run:
-
-```bash
-npm run verify:all
+```js
+const { CommerceClient, verifyDeliveryReceipt, endpoints } = require("xytara");
+const client = new CommerceClient({ baseUrl: endpoints.runtime, accountId: "acct_your_agent" });
 ```
 
-This is the production-confidence check for the published package surface.
+README.md walks through discover -> 402 -> pay with an x402 authorization -> result + receipt, and
+through verifying a receipt offline against the runtime's published keys.
 
-If you are evaluating a real deployment that will use grants, credits, entitlements, or usage meters, also run:
+## 5. Check the package locally
 
 ```bash
-npm run verify:production-readiness
+xytara first-run --offline --json
+xytara-run --help
+npm run verify:release-candidate   # offline, built-ins only
 ```
 
-That gate is stricter than local verification and expects:
-
-- runtime persistence through `XYTARA_STATE_FILE` on persistent disk or `XYTARA_SUPABASE_*`
-- signed payment verification with a real wallet registry
-- real operator bearer tokens
-- treasury destinations configured through `XYTARA_TREASURY_DESTINATIONS_PATH`
-- callback signing configured through `XYTARA_CALLBACK_SIGNING_SECRET`
-- hosted checkout event verification configured through `XYTARA_CHECKOUT_WEBHOOK_SECRET`
-- `L402` ingress verification configured through `XYTARA_L402_SHARED_SECRET` when `XYTARA_L402_ENABLED=true`
-- `BOLT` ingress verification configured through `XYTARA_BOLT_SHARED_SECRET` when `XYTARA_BOLT_ENABLED=true`
-- `MPP` ingress verification configured through `XYTARA_MPP_SHARED_SECRET` when `XYTARA_MPP_ENABLED=true`
-- write-path rate limiting configured and enabled
-- execution targets configured through `XYTARA_EXECUTION_TARGETS_JSON` whenever you require provider-backed execution for live sold capabilities
-- non-mock native settlement runtime mode
-
-## 5. Read The Durable Contract
-
-For long-term product understanding, read:
-
-- FINAL_CONTRACT.md
-- SERVICE_CONTRACT.md
-- `GET /openapi.json`
-- `GET /asyncapi.json`
-- `GET /cloudevents.json`
-- `GET /v1/auth-profiles`
-- `GET /v1/identity-interop`
-- `GET /v1/providers`
-- `GET /v1/frameworks`
-- `GET /v1/protocols`
-- `GET /v1/integration-matrix`
-- `GET /v1/telemetry`
-- `GET /v1/provenance`
-- `GET /v1/artifact-distribution`
-- `GET /v1/shared-signals`
-- `GET /v1/feature-control`
-- `GET /v1/adapter-certification`
-- `GET /v1/trust-portability-boundary`
-- `GET /v1/signed-audit-provenance`
-- `GET /v1/mcp`
-- `GET /v1/a2a`
-- `GET /v1/a2c`
-- `GET /v1/x402`
-- `GET /v1/l402`
-- `GET /v1/l402/security`
-- `GET /v1/bolt`
-- `GET /v1/bolt/security`
-- `GET /v1/stripe-mpp`
-- `GET /v1/stripe-mpp/security`
-- `GET /v1/network-transport`
-- `GET /v1/payment-protocols`
-- `GET /v1/payment-protocols/strategy`
-- `GET /v1/payment-fronts`
-- `GET /v1/checkout/events/security`
-- `GET /v1/settlement`
-- `GET /v1/stripe-mpp`
-- `GET /v1/stablecoins`
-- `GET /v1/major-rails`
-- `GET /v1/treasury`
-- `GET /v1/pricing-optimization`
-- `GET /v1/pricing-optimization/quote-cohorts`
-- `GET /v1/pricing-optimization/recommendations`
-- `GET /v1/activity-ledger`
-- `GET /v1/treasury-destinations`
-- `GET /v1/treasury-destinations/operator-pack`
-- `POST /v1/treasury-destinations/validate-preview`
-- `GET /v1/treasury-egress-policy`
-- `GET /v1/erc8004`
-- `GET /v1/event-systems`
-- `GET /v1/integrations`
-- `GET /v1/capability-registry/execution-truth`
-- `GET /v1/capability-registry/execution-truth/summary`
-- `GET /v1/xt1`
-- `GET /v1/xt1/summary`
-- `GET /v1/capability-registry/commercialization-summary`
-- `GET /v1/go-live`
-- `GET /v1/go-live/summary`
-- PROGRAM_STATUS.md
-- OPERATOR_START_HERE.md
-- OPERATIONS_RUNBOOK.md
-- PROGRAM_COMPLETE_RELEASE.md
-- WHY_XYTARA_XOONYA.md
-- CARRIED_HANDOFF_DEMO.md
-- PARTNER_READY_PATH.md
-- BSV_TERANODE_PLATFORM_DISCONTINUITY_RUNBOOK.md
-- REAL_PAYMENT_SETUP.md
-- private treasury source of truth: `your private treasury source-of-truth file outside the repos`
-- TERMINOLOGY.md
-
-## 6. If You Are Building Adapters
-
-Continue with:
-
-- ADAPTER_START_HERE.md
-- adapters/AUTHORING_GUIDE.md
-- adapters/ONBOARDING_POSTURE.md
-- adapters/THIRD_PARTY_SUBMISSION_PROCESS.md
-
-## 7. Production Reading Rule
-
-If you only remember one thing, remember this:
-
-The main public path is no longer "read every milestone layer."
-
-It is:
-
-discover -> preview/quote -> execute -> inspect -> hand off to `xoonya`
-
-If you want the shortest CLI-first read of the package after install, use:
-
-- `xytara start-here`
-- `xytara release --summary`
-- `xytara run --help`
-
-If you are operationalizing monetization and multi-rail treasury custody, use:
-
-- `GET /v1/go-live`
-- `GET /v1/go-live/summary`
-- `GET /v1/pricing-optimization/quote-abandonment-summary`
-- `GET /v1/pricing-optimization/quote-cohorts`
-- `GET /v1/pricing-optimization/recommendations`
-- `GET /v1/treasury-destinations`
-- `GET /v1/treasury-destinations/operator-pack`
-- `POST /v1/treasury-destinations/validate-preview`
-- `GET /v1/treasury-egress-policy`
-- `GET /v1/activity-ledger`
-- `GET /v1/capability-registry/execution-truth`
-- `GET /v1/capability-registry/execution-truth/summary`
-- `GET /v1/xt1`
-- `GET /v1/xt1/summary`
-- `GET /v1/capability-registry/commercialization-summary`
-
-Public/private rule:
-
-- `GET /v1/treasury-destinations` is safe for public-readiness visibility
-- `GET /v1/treasury-destinations/operator-pack` is where real custody landing refs belong
-- public website and public catalog surfaces should never expose treasury landing refs or custody-provider refs
-- when `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, operator-only routes like `activity-ledger`, `treasury-destinations/operator-pack`, `treasury-destinations/validate-preview`, and `treasury-egress-policy` require that bearer token
-
-## 8. If You Are Operating The Closed Program
-
-Use:
+## 6. Boundaries
 
-- PROGRAM_STATUS.md
-- OPERATOR_START_HERE.md
+- quote-only mode needs no wallet secret; funded execution needs payment material or credits
+- a failed call is not charged; settlement happens only after a successful execution
+- a delivery receipt proves who delivered what for which paid call — not that the output is good
+- proof lives in `xoonya`; runtime payment state lives in the hosted runtime
+- this package contains no server, payment engine, routing, state store or operator tooling
 
-If you depend on hidden-account grants, credits, or usage meters in production, set `XYTARA_STATE_FILE` to a path on persistent disk before you trust restart durability.
+## 7. Learn more
 
-If your host does not provide persistent disk, use SUPABASE_RUNTIME_STATE_SETUP.md instead.
+- Agent guide: https://www.naxytra.com/agents
+- Quickstart: https://www.naxytra.com/quickstart
+- MCP integration guide: https://github.com/naxytra/naxytra-mcp
+- Proof side: https://naxytra.com/xoonya