xytara 1.27.0 → 2.1.0

package/.env.example

@@ -1,3 +1,25 @@
 XYTARA_HOST=127.0.0.1
 XYTARA_PORT=4320
 XYTARA_BASE_URL=http://127.0.0.1:4320
+XYTARA_PAYMENT_VERIFICATION_MODE=presence
+XYTARA_PAYMENT_MAX_AGE_SECONDS=300
+XYTARA_WALLET_REGISTRY_JSON=[]
+XYTARA_TREASURY_DESTINATION_ID=
+XYTARA_TREASURY_DESTINATION_KIND=
+XYTARA_TREASURY_ACCOUNT_ID=
+XYTARA_TREASURY_EXTERNAL_REF=
+XYTARA_TREASURY_DESTINATIONS_JSON={}
+XYTARA_BSV_TERANODE_NETWORK=mainnet
+XYTARA_BSV_TERANODE_RPC_URL=
+XYTARA_BSV_TERANODE_MODE=opreturn
+XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS=1
+XYTARA_BSV_TERANODE_MERCHANT_ADDRESS=
+XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL=
+XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
+XYTARA_BSV_TERANODE_USE_METANET=false
+XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
+XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
+XYTARA_CREDIT_BRIDGE_BEARER_TOKEN=
+XYTARA_ACCOUNT_AUTH_BEARER_TOKEN=
+XYTARA_STATE_FILE=
+XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000

package/BSV_TERANODE_SETUP.md

@@ -0,0 +1,105 @@
+# BSV Teranode Setup
+
+`xytara` now treats `bsv_teranode` as the native first-party settlement base for the default machine payment path.
+
+Use this guide when you want the public package to emit BSV/Teranode-aware payment and settlement posture instead of only generic treasury bookkeeping.
+
+## What This Gives You
+
+- quotes expose native `bsv_teranode` settlement hints
+- signed payment payloads can carry BSV/Teranode merchant details and settlement reference data
+- accepted payments and resulting receipts preserve BSV/Teranode settlement metadata
+- treasury routing can point directly at a BSV/Teranode merchant address or paymail
+
+This is still a runtime-side settlement contract, not a bundled bank or broadcaster. Real external custody still depends on the BSV/Teranode infrastructure you configure behind it.
+
+## Recommended Environment
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
+XYTARA_BSV_TERANODE_NETWORK=mainnet
+XYTARA_BSV_TERANODE_MODE=opreturn
+XYTARA_BSV_TERANODE_REQUIRED_CONFIRMATIONS=1
+XYTARA_BSV_TERANODE_MERCHANT_ADDRESS=
+XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL=
+XYTARA_BSV_TERANODE_MERCHANT_LABEL=naxytra-runtime
+XYTARA_BSV_TERANODE_USE_METANET=false
+XYTARA_BSV_TERANODE_SATS_PER_USD_CENT=100
+XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE=mock
+XYTARA_BSV_TERANODE_RPC_URL=
+XYTARA_BSV_TERANODE_RPC_API_KEY=
+XYTARA_BSV_TERANODE_RPC_AUTH_HEADER=authorization
+XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME=
+XYTARA_BSV_TERANODE_OBSERVER_URL=
+```
+
+Optional:
+
+- `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE`
+  - `mock` keeps the old simulated submit/refresh loop
+  - `observe` accepts a payment-provided `txid` and performs real live confirmation refresh
+  - `arc` submits `raw_tx` through ARC and then performs real live confirmation refresh
+- `XYTARA_BSV_TERANODE_RPC_URL`
+  - use your ARC submit endpoint, for example `https://arc.taal.com/v1/tx`
+- `XYTARA_BSV_TERANODE_RPC_API_KEY`
+  - required when your ARC provider expects authenticated submission
+- `XYTARA_BSV_TERANODE_RPC_AUTH_HEADER`
+  - defaults to `authorization`
+- `XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME`
+  - leave blank for TAAL-style raw API-key auth, or set `Bearer` if your provider expects it
+- `XYTARA_BSV_TERANODE_OBSERVER_URL`
+  - optional transaction observer base; defaults to `https://api.whatsonchain.com/v1/bsv/<network>`
+
+## Merchant Destination Routing
+
+If you set:
+
+- `XYTARA_BSV_TERANODE_MERCHANT_ADDRESS`
+or
+- `XYTARA_BSV_TERANODE_MERCHANT_PAYMAIL`
+
+then `xytara` can derive a BSV/Teranode treasury destination automatically for `bsv_teranode` settlement quotes.
+
+If you need more explicit destination control, use:
+
+- `XYTARA_TREASURY_DESTINATIONS_JSON`
+
+with a `bsv_teranode` entry.
+
+## Runtime Behavior
+
+For a native `bsv_teranode` quote:
+
+- settlement mode defaults to `bsv_teranode`
+- quote settlement hints include:
+  - rail
+  - network
+  - merchant address or paymail
+  - amount in satoshis
+  - settlement reference
+- signed client payment payloads can carry the same BSV/Teranode hints back to the runtime
+- resulting transactions/receipts preserve BSV/Teranode settlement metadata for later reconciliation and proof follow-through
+
+For live settlement follow-through after payment acceptance, use:
+
+- `GET /v1/settlement/bsv-teranode`
+- `GET /v1/settlement/bsv-teranode/:settlement_id`
+- `POST /v1/settlement/bsv-teranode/:settlement_id/submit`
+- `POST /v1/settlement/bsv-teranode/:settlement_id/refresh`
+
+If the signed payment payload already carries:
+
+- `bsv_teranode.txid`
+
+then `observe` mode is enough to turn `xytara` into a live confirmation tracker.
+
+If the signed payment payload also carries:
+
+- `bsv_teranode.raw_tx`
+
+then `arc` mode can submit the raw transaction through ARC before refresh.
+
+## Notes
+
+- `bsv_teranode` is the canonical public settlement name
+- Metanet remains optional support infrastructure, not a required dependency

package/FINAL_CONTRACT.md

@@ -20,13 +20,13 @@ It consumes and emits proof-compatible facts, but its primary job is machine com
 
 ## Public Release Stance
 
-This product is being prepared as a first public release from private lineage.
+This product is being prepared as a first public release.
 
 That means:
 
-- prior internal SDK and service shapes are design history, not public obligations
+- prior SDK and service experiments are design history, not public obligations
 - useful capability should be preserved where it strengthens the final product
-- historical private helper sprawl does not automatically define the public contract
+- older helper sprawl does not automatically define the public contract
 
 The public baseline should therefore be chosen for product quality, clarity, extensibility, and end-to-end usefulness, not for backward compatibility with prior private repos.
 
@@ -464,9 +464,9 @@ The final commerce product must maintain conformance across:
 - proof integration
 - adapter certification
 
-## What Must Survive From Internal Lineages
+## What Must Survive Across Earlier Product Iterations
 
-From the internal stack, the following semantic wins should survive:
+From earlier product iterations, the following semantic wins should survive:
 
 - clean separation of execution and proof
 - clean separation of execution and settlement
@@ -476,7 +476,7 @@ From the internal stack, the following semantic wins should survive:
 - proof-backed lifecycle state
 - operator-grade visibility
 
-Historical internal labels and names should not survive publicly.
+Historical implementation labels and temporary names should not survive publicly.
 
 ## Final Product Position
 

package/PUBLISH_PLAN.md

@@ -0,0 +1,12 @@
+# xytara Publish Plan
+
+1. Run `npm run verify:release-candidate`.
+2. Run `npm pack --dry-run --json` and confirm the package contents.
+3. Publish with `npm publish --access public`.
+4. Redeploy the live service surfaces.
+5. Verify:
+   - `/v1/release-candidate/summary`
+   - `/v1/release-center/summary`
+   - `/v1/announcement-pack/summary`
+   - `/v1/outreach-proof/summary`
+6. Run the first public machine proof path.

package/README.md

@@ -31,19 +31,177 @@ If you are building adapters, continue with:
 - [adapters/ONBOARDING_POSTURE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/ONBOARDING_POSTURE.md)
 - [adapters/THIRD_PARTY_SUBMISSION_PROCESS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/adapters/THIRD_PARTY_SUBMISSION_PROCESS.md)
 
+If you are wiring the native BSV settlement base, continue with:
+
+- [BSV_TERANODE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/BSV_TERANODE_SETUP.md)
+- [REAL_PAYMENT_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/REAL_PAYMENT_SETUP.md)
+
+If you are wiring external checkout or hosted funding paths, continue with:
+
+- [HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/HUMAN_CHECKOUT_AND_RUNTIME_BRIDGE_PATTERN.md)
+- [RUNTIME_BRIDGE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/RUNTIME_BRIDGE_CONTRACT.md)
+- [HOSTED_CHECKOUT_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/HOSTED_CHECKOUT_CONTRACT.md)
+- [CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/CHECKOUT_TO_CREDITS_AND_DISPATCH_PLAN.md)
+
 ## Production Path
 
 The intended production-facing default path is now:
 
 1. discover a capability
 2. preview or quote the transaction path
-3. execute through the default machine path
-4. inspect the transaction-side result and lifecycle state
-5. hand the result into `xoonya`
-6. review and run the proof-side completion path
+3. spend existing credits first when the caller prefers the reusable account path
+4. fall back to direct machine payment when credits are not available or not preferred
+5. execute through the default machine path
+6. inspect the transaction-side result and lifecycle state
+7. hand the result into `xoonya`
+8. review and run the proof-side completion path
+
+The machine-facing execution surface now also supports a first-class reusable balance posture:
+
+- set `payment_preference: "credits_first"` on `POST /v1/commands/execute` when the caller wants to spend existing account credits before requesting a fresh payment
+- default spend posture is `open_spend`: if the funded caller can pay, `xytara` should spend and execute without extra runtime ceremony
+- bounded spend posture is optional and only applies when the caller intentionally uses an `agent_id` and/or `budget_id`
+- inspect account credit state with `GET /v1/economics/accounts/:account_id/credit-balance`
+- inspect deterministic usage metering state with `GET /v1/economics/accounts/:account_id/metering-summary`, `GET /v1/economics/accounts/:account_id/usage-meters`, and `GET /v1/economics/accounts/:account_id/usage-meters/:usage_meter_id`
+- expect reconciliation and operator-export surfaces to carry the same metering trail for audit visibility
+- export a canonical cross-repo economic handoff bundle with `POST /v1/economics/handoff-bundles/economic-consequence`
+- expect `POST /v1/transaction-center/result-packages/export` and result-package continuation export/prepare surfaces to auto-carry that same canonical economic bundle whenever the execution path spent credits and produced a deterministic usage meter
+- inspect pack-backed entitlement pools with `GET /v1/economics/accounts/:account_id/entitlements` and `GET /v1/economics/accounts/:account_id/entitlements/summary`
+- inspect low-balance and replenishment posture with `GET /v1/economics/accounts/:account_id/entitlements/replenishment-summary`
+- inspect one pool’s replenishment view with `GET /v1/economics/accounts/:account_id/entitlements/:entitlement_id/replenishment-view`
+- inspect effective account spend posture with `GET /v1/economics/accounts/:account_id/policy-pack`
+- inspect effective agent spend posture with `GET /v1/economics/accounts/:account_id/agents/:agent_id/policy-view`
+- preflight a proposed credit spend with `POST /v1/economics/rails/credits/preview-spend`
+- record explicit bounded credit consumption with `POST /v1/economics/rails/credits/consume`
+- issue externally verified top-up grants with `POST /v1/credit-bridge/grants`
+- inspect externally issued grants with `GET /v1/credit-bridge/grants` and `GET /v1/credit-bridge/grants/:grant_id`
+- discover reusable funding posture through `GET /v1/credit-packs`, `GET /v1/credit-packs/summary`, and `GET /v1/credit-pack?ref=<pack_id>`
+- external grant callers can now fund a named public pack such as `credits.agent`, and `xytara` will validate and record that pack identity directly
+
+The SDK now exposes the same posture directly for agent callers:
+
+- `client.getCreditPackSummary()`
+- `client.getCreditBalance(accountId)`
+- `client.previewUsageMetering({ account_id, task_ref?, workflow_ref?, units? })`
+- `client.getUsageMeteringSummary(accountId)`
+- `client.listUsageMeters(accountId)`
+- `client.getUsageMeter(usageMeterId, accountId?)`
+- `client.exportEconomicConsequenceHandoffBundle({ account_id, usage_meter_id, credit_spend_id, meter_profile_ref? })`
+- `client.listEntitlements(accountId)`
+- `client.getEntitlementSummary(accountId)`
+- `client.getEntitlement(entitlementId, accountId?)`
+- `client.getEntitlementReplenishmentSummary(accountId)`
+- `client.getEntitlementReplenishmentView(entitlementId, accountId?)`
+- `client.updateEntitlementReplenishmentPreference(entitlementId, payload, accountId?)`
+- `client.previewCreditSpend({ account_id, task_ref, units, agent_id?, budget_id? })`
+- `client.getCreditSpendPolicyPack(accountId)`
+- `client.getAgentCreditSpendPolicyView(agentId, accountId?)`
+- `client.executeWithCreditsFirst(payload, options?)`
+
+The runtime now also supports a bounded delegated spend path for repeat-use automation:
+
+- issue a spend credential through `POST /v1/account-auth/spend-credentials`
+- use that credential as `authorization: Bearer <spend_credential>`
+- optionally bind the credential to a `pack_id` or `entitlement_id` when spend should stay inside one value pool
+- execute through the same `credits_first` path without sharing broad operator secrets
+- revoke it through `POST /v1/account-auth/spend-credentials/:credential_id/revoke`
+
+SDK helpers now include:
+
+- `client.createSpendCredential(payload, { bearerToken })`
+- `client.listSpendCredentials(filters?, { bearerToken? })`
+- `client.getSpendCredential(credentialId, { bearerToken? })`
+- `client.revokeSpendCredential(credentialId, payload, { bearerToken })`
+- `client.executeWithSpendCredential(payload, { spendToken })`
+
+This keeps one-off usage and repeat usage on the same public spine:
+
+- direct pay when the caller is using the stack once
+- credit balance when the caller is already funded and wants low-friction repeat execution
+- optional agent and budget controls can still bound that spend without changing the execution surface
+
+It also keeps the external funding boundary clean:
+
+- an external merchant-facing system can verify a purchase and issue a bounded credit grant into `xytara`
+- `xytara` records the granted value and consumes it during later runtime operations
+- the runtime does not need to absorb provider-specific checkout semantics to support repeat usage
+- in production, `POST /v1/credit-bridge/grants` should normally be protected with `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN`
+
+The first external checkout convenience path now follows a parallel narrow route:
+
+1. create hosted purchase intent
+2. create checkout session
+3. normalize payment success
+4. issue credits or entitlement
+5. dispatch through the runtime path when needed
+6. converge back into the same `xytara` and `xoonya` spine
+
+The first direct hosted execution path now also has a public runtime dispatch surface:
+
+- `POST /v1/runtime-bridge/dispatch`
+- `GET /v1/runtime-bridge/dispatches`
+- `GET /v1/runtime-bridge/dispatches/:request_id`
+
+The hosted payment side is intentionally asymmetric:
+
+- pay-in should be simple and fast
+- execution and delivery should follow immediately after valid payment
+- refund or reversal requests should enter review first
+- no autonomous payout path should exist outside explicit operator review and completion
+
+The operator shell now also carries hosted checkout visibility so purchase, dispatch, and refund-review load can be monitored from the same public control surface.
 
 The rest of this README explains the full surface area and milestone trail, but the public starting posture should now be understandable from that one default path.
 
+For release-grade adoption posture, inspect:
+
+- `GET /v1/release-pack`
+- `GET /v1/release-pack/summary`
+- `GET /v1/release-pack/comparison`
+- `GET /v1/release-pack/comparison/summary`
+- `GET /v1/release-pack/adoption`
+- `GET /v1/release-pack/adoption/summary`
+- `GET /v1/release-pack/scenarios`
+- `GET /v1/release-pack/scenarios/summary`
+- `GET /v1/release-pack/launch`
+- `GET /v1/release-pack/launch/summary`
+- `GET /v1/release-manifest`
+- `GET /v1/release-manifest/summary`
+- `GET /v1/release-notes`
+- `GET /v1/release-notes/summary`
+- `GET /v1/release-center`
+- `GET /v1/release-center/summary`
+- `GET /v1/release-history`
+- `GET /v1/release-history/summary`
+- `GET /v1/publish-plan`
+- `GET /v1/publish-plan/summary`
+- `GET /v1/ecosystem-entry`
+- `GET /v1/ecosystem-entry/summary`
+- `GET /v1/launch-narrative`
+- `GET /v1/launch-narrative/summary`
+- `GET /v1/outreach-proof`
+- `GET /v1/outreach-proof/summary`
+- `GET /v1/announcement-pack`
+- `GET /v1/announcement-pack/summary`
+- `GET /v1/release-candidate`
+- `GET /v1/release-candidate/summary`
+- `xytara-release --summary`
+- `xytara-release --comparison --summary`
+- `xytara-release --adoption --summary`
+- `xytara-release --scenarios --summary`
+- `xytara-release --launch --summary`
+- `xytara-release --manifest --summary`
+- `xytara-release --notes --summary`
+- `xytara-release --center --summary`
+- `xytara-release --history --summary`
+- `xytara-release --ecosystem --summary`
+- `xytara-release --narrative --summary`
+- `xytara-release --outreach-proof --summary`
+- `xytara-release --announcement --summary`
+- `xytara-release --candidate --summary`
+
+These surfaces package the current machine-commerce value story, first-contact CLI path, default transaction posture, catalog/task-pack coverage, credit-pack posture, and integration/settlement breadth into one machine-readable launch boundary.
+
 ## Commerce Loop
 
 The public product loop is:
@@ -98,7 +256,7 @@ The package and service also expose a default transaction center surface so the
 
 - default protocol lane: `mcp`
 - default payment protocol: `x402`
-- default settlement center: built-in chain settlement across the canonical bundled settlement modes
+- default settlement center: built-in chain settlement with `bsv_teranode` as the native default across the canonical bundled settlement modes
 - default treasury landing posture: account treasury destination by settlement mode
 
 That same default center is also reflected in direct helper paths for default MCP usage, so the default path can be previewed or quoted without repeating the full integration-selection story each time.
@@ -480,6 +638,12 @@ Run:
 node examples/quickstart.js
 ```
 
+For a direct one-line machine run against a live service, use the bundled CLI:
+
+```bash
+xytara-run --url https://xytara.onrender.com --account acct_demo --command "cli-run" --task trust.verify --body-json '{"subject_id":"subject-1"}' --wallet-id merchant_wallet_main --wallet-secret YOUR_LOCAL_SIGNED_SECRET --txid YOUR_BSV_TXID
+```
+
 The quickstart exercises:
 
 - health and catalog
@@ -560,6 +724,16 @@ Environment example:
 
 - [`.env.example`](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/.env.example)
 
+Production payment note:
+
+- set `XYTARA_PAYMENT_VERIFICATION_MODE=local_signed` to enforce verifiable signed payment acceptance instead of plain header presence
+- provide buyer wallet verification material through `XYTARA_WALLET_REGISTRY_JSON` or `XYTARA_WALLET_REGISTRY_PATH`
+- set `XYTARA_TREASURY_DESTINATION_ID` and related treasury env vars so accepted payments land in your merchant treasury posture instead of the default local account placeholder
+- built-in `x402` is the admission lane; real external payout/custody still depends on the payment rail and treasury destination you configure behind that lane
+- for native BSV/Teranode live follow-through, set `XYTARA_BSV_TERANODE_SETTLEMENT_RUNTIME_MODE` to `observe` or `arc`
+- use `XYTARA_BSV_TERANODE_RPC_URL` plus optional ARC auth envs when the live runtime needs ARC submission
+- use `XYTARA_BSV_TERANODE_OBSERVER_URL` if you want to override the default live observer base
+
 Primary service routes:
 
 - `GET /health`
@@ -636,6 +810,7 @@ Primary service routes:
 - `GET /v1/receipts/:receipt_id`
 - `GET /v1/payment-ledger`
 - `GET /v1/payment-ledger/:payment_id`
+- `GET /v1/payment-ledger/:payment_id/operator-pack`
 - `GET /v1/deliveries`
 - `GET /v1/deliveries/:delivery_id`
 - `GET /v1/disputes`
@@ -654,6 +829,7 @@ Primary service routes:
 - `GET /v1/operator-export-pack`
 - `GET /v1/operations/dashboard`
 - `GET /v1/operations/attention-records`
+- `GET /v1/runtime/durability`
 - `GET /v1/operator-shell`
 - `GET /v1/operator-shell/summary`
 - `POST /v1/operator-shell/summary`
@@ -699,6 +875,8 @@ Primary service routes:
 - `GET /v1/economics/evidence/receipts/:receipt_ref`
 - `GET /v1/economics/evidence/jobs/:job_id`
 - `GET /v1/economics/integration/jobs/:job_id`
+- `GET /v1/settlement/bsv-teranode/readiness`
+- `GET /v1/settlement/bsv-teranode/:settlement_id/operator-pack`
 
 The Wave C coordination carry-over line adds a bounded coordination center on top of the public transaction spine:
 
@@ -718,9 +896,17 @@ The Wave F shell carry-over line adds a bounded operator shell inside public `xy
 
 - self-serve agent account issuance for the public runtime path
 - a unified operator shell summary across operations, economics, and coordination
+- explicit runtime durability visibility for snapshot-backed recovery posture
+- explicit native BSV/Teranode readiness visibility for merchant identity, transport, and verification posture
 - compact workflow/admin shell exports that point cleanly into proof-side follow-through when needed
 
-This keeps the public product centered on `naxytra` while recovering the useful operator-shell lineage as a built-in `xytara` capability instead of a separate branded surface.
+This keeps the public product centered on `naxytra` while preserving the useful operator-shell capability directly inside `xytara` instead of splitting it into a separate surface.
+
+The durability and native-settlement readiness surfaces are also intended to make the remaining production boundary explicit:
+
+- `/v1/runtime/durability` exposes whether runtime snapshots are enabled, whether a recoverable snapshot exists yet, and any current durability blockers
+- `/v1/settlement/bsv-teranode/readiness` exposes whether merchant identity, transport, verification mode, and runtime mode are production-ready, plus the next manual inputs still required
+- `/v1/payment-ledger/:payment_id/operator-pack` and `/v1/settlement/bsv-teranode/:settlement_id/operator-pack` collapse payment, settlement, treasury, proof, and economic-consequence carry into one operator-facing pack so direct-pay and funded-runtime paths are easier to inspect without stitching raw records together
 
 ## Verification
 

package/REAL_PAYMENT_SETUP.md

@@ -0,0 +1,101 @@
+# Real Payment Setup
+
+This guide explains how to move `xytara` from local placeholder payment acceptance into a production-usable payment posture.
+
+## What Changed
+
+`xytara` now supports two payment-acceptance modes:
+
+- `presence`
+  - development/demo mode
+  - payment headers are required, but not cryptographically verified
+
+- `local_signed`
+  - production-oriented built-in mode
+  - signed payment payloads are cryptographically verified against a configured wallet registry
+  - quote replay and nonce replay are blocked
+  - accepted payments are routed into your configured merchant treasury destination posture
+
+## Minimum Production-Oriented Configuration
+
+Set these environment variables:
+
+```env
+XYTARA_PAYMENT_VERIFICATION_MODE=local_signed
+XYTARA_PAYMENT_MAX_AGE_SECONDS=300
+XYTARA_WALLET_REGISTRY_JSON=[{"wallet_id":"<wallet-id>","secret":"<shared-secret>","account_id":"<account-id>"}]
+XYTARA_TREASURY_DESTINATION_ID=merchant_treasury_primary
+XYTARA_TREASURY_DESTINATION_KIND=merchant_treasury
+XYTARA_TREASURY_ACCOUNT_ID=merchant-main
+XYTARA_TREASURY_EXTERNAL_REF=merchant-usd-main
+```
+
+You can also load the wallet registry and treasury map from files through:
+
+- `XYTARA_WALLET_REGISTRY_PATH`
+- `XYTARA_TREASURY_DESTINATIONS_PATH`
+
+## What This Gives You
+
+With `local_signed` enabled:
+
+- `POST /x402/commands/execute` challenges for payment
+- the client signs the exact payment payload
+- if the quote is using native `bsv_teranode`, the payment payload can also carry BSV/Teranode merchant and settlement-reference hints
+- the server verifies:
+  - wallet registration
+  - HMAC signature validity
+  - quote id
+  - amount
+  - currency
+  - settlement binding
+  - timestamp freshness
+  - nonce uniqueness
+- accepted payments are recorded into:
+  - `payment-ledger`
+  - `treasury-summary`
+  - `rail-summary`
+  - `reconciliation-report`
+
+## What It Does Not Do By Itself
+
+The built-in path gives you verifiable payment acceptance and merchant treasury routing posture inside `xytara`.
+
+It does not by itself:
+
+- move fiat into a bank account
+- broadcast on-chain settlement
+- replace an external processor or custodian
+
+For actual external custody, connect `xytara` to the real rail you want behind the payment and settlement boundary.
+
+That is where:
+
+- your payment rail integration
+- your settlement integration
+- your merchant treasury destination
+
+become the actual real-world landing point for accepted funds.
+
+## Best Current Public Model
+
+Use the stack like this:
+
+- `x402` route = payment admission lane
+- `local_signed` = real verifiable acceptance posture in the public package
+- `bsv_teranode` = native first-party settlement base when you want the public stack to expose BSV/Teranode-aware payout posture
+- configured treasury destination = merchant-facing landing posture in the runtime
+- external rail / settlement integration = actual custody and payout layer
+
+If you want the native BSV path specifically, continue with [BSV_TERANODE_SETUP.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/BSV_TERANODE_SETUP.md).
+
+## Operator Visibility
+
+After acceptance, inspect:
+
+- `GET /v1/payment-ledger`
+- `GET /v1/economics/accounts/:account_id/treasury-summary`
+- `GET /v1/economics/accounts/:account_id/rail-summary`
+- `GET /v1/reconciliation-report`
+
+These tell you what was accepted, where it was routed in the runtime model, and what still needs reconciliation against the underlying real-world rail.

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,10 @@
+# xytara Release Checklist
+
+1. Run `npm run verify:release-candidate`.
+2. Confirm `npm pack --dry-run --json` includes the public docs and both CLI entrypoints.
+3. Redeploy the service and verify:
+   - `/v1/release-center/summary`
+   - `/v1/announcement-pack/summary`
+   - `/v1/outreach-proof/summary`
+4. Run the first public proof path.
+5. Only then publish the npm package.

package/RELEASE_NOTES.md

@@ -0,0 +1,19 @@
+# xytara 2.1.0 Release Notes
+
+`xytara` 2.1.0 is the public machine-commerce release-candidate line.
+
+Highlights:
+
+- direct one-line machine execution with `xytara-run`
+- release, comparison, adoption, scenario, and launch packs over HTTP and CLI
+- release-center, announcement-pack, and release-candidate surfaces for public launch readiness
+- credits-first reusable spend posture
+- native settlement-aware runtime inspection
+- proof-compatible handoff into `xoonya`
+
+Recommended first checks:
+
+1. `npm install xytara`
+2. `xytara-release --candidate --summary`
+3. `npm run verify:release-candidate`
+4. inspect `/v1/release-candidate/summary` on the deployed service