xytara 2.5.0 → 2.7.0

package/.env.example

@@ -21,6 +21,35 @@ 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_CALLBACK_DELIVERY_ENABLED=true
+XYTARA_CALLBACK_SIGNING_SECRET=
+XYTARA_CALLBACK_TIMEOUT_MS=5000
+XYTARA_CALLBACK_MAX_ATTEMPTS=5
+XYTARA_CALLBACK_RETRY_BASE_MS=2000
+XYTARA_RUNTIME_WORKER_INTERVAL_MS=500
+XYTARA_SETTLEMENT_REFRESH_INTERVAL_MS=1500
+XYTARA_RATE_LIMIT_ENABLED=true
+XYTARA_RATE_LIMIT_WINDOW_MS=60000
+XYTARA_RATE_LIMIT_MAX_REQUESTS=600
+XYTARA_EXTERNAL_EXECUTION_REQUIRED=false
+XYTARA_EXECUTION_TARGETS_JSON=[]
+XYTARA_L402_ENABLED=false
+XYTARA_L402_SHARED_SECRET=
+XYTARA_BOLT_ENABLED=false
+XYTARA_BOLT_SHARED_SECRET=
+XYTARA_BOLT_NETWORK=mainnet
+XYTARA_BOLT_PROOF_MODE=spv_or_block_header_verifiable
+XYTARA_BOLT_MAX_AGE_SECONDS=300
+XYTARA_MPP_ENABLED=false
+XYTARA_MPP_SHARED_SECRET=
+XYTARA_MPP_PROVIDER=stripe_tempo_compatible
+XYTARA_MPP_SETTLEMENT_FAMILY=cards_or_stablecoin_or_lightning
+XYTARA_MPP_MAX_AGE_SECONDS=300
+XYTARA_NETWORK_DNS_RESULT_ORDER=verbatim
+XYTARA_NETWORK_PREFERRED_IP_FAMILY=auto
+XYTARA_EXTERNAL_EXECUTION_IP_FAMILY=auto
+XYTARA_CALLBACK_IP_FAMILY=auto
+XYTARA_SETTLEMENT_IP_FAMILY=auto
 XYTARA_STATE_FILE=./var/xytara/runtime-state.json
 XYTARA_STATE_SNAPSHOT_INTERVAL_MS=5000
 XYTARA_SUPABASE_URL=

package/BSV_TERANODE_SETUP.md

@@ -13,6 +13,8 @@ Use this guide when you want the public package to emit BSV/Teranode-aware payme
 
 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.
 
+The runtime worker now also auto-submits and auto-refreshes settlement records after payment acceptance, so a configured live rail can progress without manual operator calls.
+
 ## Recommended Environment
 
 ```env
@@ -31,6 +33,7 @@ XYTARA_BSV_TERANODE_RPC_API_KEY=
 XYTARA_BSV_TERANODE_RPC_AUTH_HEADER=authorization
 XYTARA_BSV_TERANODE_RPC_AUTH_SCHEME=
 XYTARA_BSV_TERANODE_OBSERVER_URL=
+XYTARA_SETTLEMENT_REFRESH_INTERVAL_MS=1500
 ```
 
 Optional:
@@ -63,9 +66,20 @@ then `xytara` can derive a BSV/Teranode treasury destination automatically for `
 If you need more explicit destination control, use:
 
 - `XYTARA_TREASURY_DESTINATIONS_JSON`
+- `XYTARA_TREASURY_DESTINATIONS_PATH`
+
+For a file-driven example, use:
+
+- [TREASURY_DESTINATIONS.example.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TREASURY_DESTINATIONS.example.json)
 
 with a `bsv_teranode` entry.
 
+For `bsv_teranode`, the key real landing field is:
+
+- `external_ref`
+
+That should hold the actual BSV address or paymail you want accepted funds to land on.
+
 ## Runtime Behavior
 
 For a native `bsv_teranode` quote:
@@ -84,9 +98,16 @@ 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/submission-material`
 - `POST /v1/settlement/bsv-teranode/:settlement_id/submit`
 - `POST /v1/settlement/bsv-teranode/:settlement_id/refresh`
 
+In current runtime posture:
+
+- the background runtime worker auto-submits newly created settlement records
+- the same worker auto-refreshes pending live settlements on the configured interval
+- the manual `submit` and `refresh` routes still exist for operator override and debugging
+
 If the signed payment payload already carries:
 
 - `bsv_teranode.txid`
@@ -99,6 +120,28 @@ If the signed payment payload also carries:
 
 then `arc` mode can submit the raw transaction through ARC before refresh.
 
+If a settlement record already exists but was created before the payment payload carried finality material, attach the material through the operator route before calling `submit`:
+
+```powershell
+$headers = @{
+  Authorization = "Bearer $env:XYTARA_ACCOUNT_AUTH_BEARER_TOKEN"
+  "Content-Type" = "application/json"
+}
+
+$body = @{
+  txid = "64_HEX_CHARACTER_BSV_TXID"
+  # or raw_tx = "RAW_TRANSACTION_HEX_FOR_ARC_SUBMISSION"
+  provider_ref = "operator-finality-material"
+} | ConvertTo-Json
+
+Invoke-RestMethod "https://xytara.onrender.com/v1/settlement/bsv-teranode/SETTLEMENT_ID/submission-material" `
+  -Method Post `
+  -Headers $headers `
+  -Body $body
+```
+
+The route only accepts a 64-character hex `txid` or raw transaction hex, preserves the existing settlement status, clears prior submission-material errors, and leaves finality to the normal `submit` and `refresh` path.
+
 ## Notes
 
 - `bsv_teranode` is the canonical public settlement name

package/README.md

@@ -1,28 +1,84 @@
 # xytara
 
-`xytara` is the machine transaction and execution layer for the final two-repo public stack.
+`xytara` is the runtime and payment layer for the public two-repo stack.
 
 It exists to let agents, developers, and systems:
 
 - discover tasks and workflows
 - quote work before execution
 - pay through supported payment paths
+- fund reusable balances and credits
 - execute tasks and workflows
+- dispatch runtime work
 - receive deliverables
+- inspect usage, metering, and lifecycle state
+- reconcile payment and settlement outcomes
 - inspect lifecycle state
 - operate through summaries and dashboards
+- review disputes, refunds, and remediation flows
 - integrate third-party adapters
 - emit proof-compatible facts for `xoonya` verification
 
-This repo is the hot-state commerce layer. It does not define base proof semantics. It references and emits proof-compatible facts, while `xoonya` owns canonical proof.
+This repo is the runtime layer. It does not define base proof semantics. It references and emits proof-compatible facts, while `xoonya` owns canonical proof.
 
 The 10-phase public program is now complete. `xytara` is in terminal closeout posture rather than active milestone build posture.
 
+## Public Boundary
+
+The public adoption story is intentionally simple:
+
+- install
+- discover
+- quote
+- pay or spend credits
+- execute
+- receive deliverables
+- hand off to `xoonya` when proof or review is needed
+
+Public docs and package surfaces should help builders integrate and pay for useful work. Real treasury destinations, custody details, and operator-only controls belong in private runtime configuration and operator handling, not in public marketing surfaces.
+
+## Universal Runtime Shape
+
+`xytara` is intended to be usable from:
+
+- CLI and terminal
+- direct API calls
+- chat and agent environments that can issue HTTP calls
+- browsers and hosted checkout flows
+- operating-system or service wrappers
+- partner systems that need to add adapters or registry integrations
+
+The shortest public runtime loop is:
+
+- discover
+- quote
+- pay or spend credits
+- execute
+- receive deliverables
+- inspect results and economic state
+- hand off into `xoonya` when proof or review is required
+
+The current runtime breadth already includes:
+
+- discovery and workflow lookup
+- pricing and quote generation
+- direct machine payment
+- credits, grants, entitlements, and delegated spend
+- execution, result packages, and delivery
+- usage metering and account economics
+- hosted checkout and runtime-bridge dispatch surfaces
+- disputes, refunds, and remediation
+- activity ledger, reconciliation, and treasury-control visibility
+- adapter registration, review, and promotion surfaces
+
 ## One-Line After Install
 
 If you only run two commands after install, use:
 
 - `xytara start-here`
+- `xytara first-run`
+- `xytara first-run --run-quote --account ACCOUNT_REF --pretty`
+- `xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty`
 - `xytara release --summary`
 
 If you want the shortest machine-readable discovery path, inspect:
@@ -43,13 +99,10 @@ If you are new to the public stack, use this order:
 3. run `npm run verify:all`
 4. use [FINAL_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/FINAL_CONTRACT.md) and [SERVICE_CONTRACT.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/SERVICE_CONTRACT.md) as the durable public contract
 
-If you are evaluating the post-program operating posture, read:
+If you are reading the GitHub repo and want deeper product context beyond the npm starter path, continue with:
 
-- [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
-- [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATOR_START_HERE.md)
-- [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATIONS_RUNBOOK.md)
-- [PROGRAM_COMPLETE_RELEASE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_COMPLETE_RELEASE.md)
 - [WHY_XYTARA_XOONYA.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/WHY_XYTARA_XOONYA.md)
+- [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PARTNER_READY_PATH.md)
 
 If you want one concrete cross-repo adoption story, start with:
 
@@ -81,6 +134,10 @@ The fastest copy-and-adapt third-party starter now lives under:
 - `adapters/examples/minimal-third-party-execution-registration.record.json`
 - `adapters/examples/minimal-third-party-execution.certification-pack.json`
 - `adapters/examples/minimal-third-party-execution.submission-bundle.json`
+- `adapters/examples/langgraph-reference-execution-adapter.manifest.json`
+- `adapters/examples/langgraph-reference-execution-adapter.js`
+- `adapters/examples/langchain-reference-execution-adapter.manifest.json`
+- `adapters/examples/langchain-reference-execution-adapter.js`
 
 If you are wiring the native BSV settlement base, continue with:
 
@@ -583,6 +640,8 @@ Initial certification starts with:
 npm run verify:adapters
 ```
 
+The LangGraph and LangChain reference adapters are local contract adapters. They normalize framework-style graph, chain, checkpoint, trace, and context payloads and emit proof-compatible execution facts. They do not claim live external framework-provider execution.
+
 The current seed freezes the starter contract for:
 
 - adapter identity

package/REAL_PAYMENT_SETUP.md

@@ -35,6 +35,36 @@ You can also load the wallet registry and treasury map from files through:
 - `XYTARA_WALLET_REGISTRY_PATH`
 - `XYTARA_TREASURY_DESTINATIONS_PATH`
 
+For multi-rail treasury landings, use:
+
+- [TREASURY_DESTINATIONS.example.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TREASURY_DESTINATIONS.example.json)
+- [TREASURY_DESTINATIONS.production.template.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TREASURY_DESTINATIONS.production.template.json)
+
+Important:
+
+- yes, for rails you actually want to receive and store value on, you should enter real receiving destinations
+- in `xytara`, that is the `external_ref` field for each rail
+- for practical purposes, `external_ref` is where the real landing address / paymail / custody account / external receiving reference goes
+
+Examples:
+
+- `bsv_teranode`
+  - BSV address or paymail
+- `evm` / `base`
+  - EVM address
+- `usdc` / `dai`
+  - the stablecoin receiving address on the intended chain
+- `monero`
+  - Monero address, only if you are explicitly enabling the internal optional privacy reserve
+
+Recommended file-driven setup:
+
+```env
+XYTARA_TREASURY_DESTINATIONS_PATH=./TREASURY_DESTINATIONS.production.json
+```
+
+Then create `TREASURY_DESTINATIONS.production.json` from the production template and replace every placeholder `external_ref` with the real destination you control.
+
 ## What This Gives You
 
 With `local_signed` enabled:
@@ -53,8 +83,10 @@ With `local_signed` enabled:
   - nonce uniqueness
 - accepted payments are recorded into:
   - `payment-ledger`
+  - `activity-ledger`
   - `treasury-summary`
   - `rail-summary`
+  - `treasury-egress-policy`
   - `reconciliation-report`
 
 ## What It Does Not Do By Itself
@@ -77,6 +109,23 @@ That is where:
 
 become the actual real-world landing point for accepted funds.
 
+For native `bsv_teranode`, the runtime can now:
+
+- create settlement records automatically when payment is accepted
+- auto-submit them when settlement runtime material is available
+- auto-refresh them toward observed or confirmed state through the background runtime worker
+
+That still does not remove the need for real merchant identity, real transport, and real operator-controlled destinations.
+
+So the short operational rule is:
+
+- no, you should not leave treasury rails as abstract names only
+- yes, you should configure real landing destinations for each rail you claim is operational
+- if a rail does not yet have a real destination, keep it visible as supported architecture, but do not claim it as an active treasury landing path
+- public treasury surfaces now expose `public_claim_status`, `public_claim_allowed`, and `public_claim_boundary`; only rails with `public_claim_allowed: true` should be described as live landing paths
+- rails with `readiness_template_only`, `partial_configuration_not_public_claim`, or `fallback_not_public_multi-rail_claim` are architecture/readiness surfaces until real per-rail destinations exist
+- `internal_policy_gated_not_public` rails must stay out of public live-landing claims
+
 ## Best Current Public Model
 
 Use the stack like this:
@@ -94,8 +143,20 @@ If you want the native BSV path specifically, continue with [BSV_TERANODE_SETUP.
 After acceptance, inspect:
 
 - `GET /v1/payment-ledger`
+- `GET /v1/activity-ledger`
 - `GET /v1/economics/accounts/:account_id/treasury-summary`
 - `GET /v1/economics/accounts/:account_id/rail-summary`
+- `GET /v1/treasury-destinations`
+- `GET /v1/treasury-destinations/operator-pack`
+- `GET /v1/treasury-egress-policy`
 - `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.
+
+If `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, the operator-only routes above require that bearer token.
+
+Public/private boundary:
+
+- `GET /v1/treasury-destinations` is the safe readiness surface
+- `GET /v1/treasury-destinations/operator-pack` is where real landing refs belong
+- public website and public catalog surfaces should never expose actual treasury destination refs or custody-provider refs

package/RELEASE_NOTES.md

@@ -1,10 +1,26 @@
-# xytara 2.5.0 Release Notes
+# xytara 2.7.0 Release Notes
 
-`xytara` 2.5.0 is the adoption-surface line for contracts, providers, frameworks, protocols, payment lanes, settlement lanes, observability, provenance, artifact distribution, and rollout portability.
+`xytara` 2.7.0 is the expansion-closeout release line for package-hardening, clean-consumer release smoke testing, and disciplined adapter/product claim boundaries.
+
+Highlights:
+
+- ships `scripts/` in the npm artifact so packaged verification commands are available to consumers
+- adds release-candidate guards that fail if required verifier scripts are missing from `npm pack`
+- participates in the Naxytra release-smoke harness that installs packed tarballs into a clean consumer project before synchronized release
+- keeps the 2.6.0 expansion capabilities and adapter surfaces intact while closing the packaging reliability gap
+
+# xytara 2.6.0 Release Notes
+
+`xytara` 2.6.0 is the expansion release line for first-run execution polish, provider-backed adapter depth, and framework reference adapters while preserving the existing machine-commerce, settlement, observability, and release surfaces.
 
 Highlights:
 
 - umbrella CLI entrypoint with `xytara start-here`, plus `xytara run` and `xytara release`
+- public first-run quote and credits-first execution posture for outside builders
+- provider-backed `adapter.mcp.invoke` depth with concrete MCP tool binding
+- executable LangGraph and LangChain reference framework adapters with manifests and proof-compatible execution facts
+- adapter verifier coverage for provider and framework execution posture
+- read-only operator observability across activity, payment, delivery, settlement, external credit grants, adapter failures, and pricing telemetry
 - first-class public contract lanes for `OpenAPI`, `AsyncAPI`, and `CloudEvents`
 - first-class provider, framework, protocol, and integration-matrix discovery surfaces
 - surfaced runtime breadth across `MCP`, `A2A`, `A2C`, `x402`, `Stripe MPP`, stablecoins, major rails, treasury, and registry-backed integrations
@@ -21,10 +37,11 @@ Recommended first checks:
 3. `npm run verify:release-candidate`
 4. `node examples/partner_launch_walkthrough.js`
 5. inspect `/v1/providers`, `/v1/frameworks`, `/v1/protocols`, and `/v1/integration-matrix`
-6. inspect `/v1/mcp`, `/v1/a2a`, `/v1/a2c`, `/v1/x402`, and `/v1/settlement`
-7. inspect `/v1/telemetry`, `/v1/provenance`, `/v1/artifact-distribution`, `/v1/shared-signals`, and `/v1/feature-control`
-8. inspect `/v1/economics/accounts/:account_id/wallet-ledger-bundle`
-9. inspect `/v1/economics/accounts/:account_id/network-participation-package`
+6. inspect `/v1/adapter-depth/summary` and `/v1/operator-observability/summary`
+7. inspect `/v1/mcp`, `/v1/a2a`, `/v1/a2c`, `/v1/x402`, and `/v1/settlement`
+8. inspect `/v1/telemetry`, `/v1/provenance`, `/v1/artifact-distribution`, `/v1/shared-signals`, and `/v1/feature-control`
+9. inspect `/v1/economics/accounts/:account_id/wallet-ledger-bundle`
+10. inspect `/v1/economics/accounts/:account_id/network-participation-package`
 
 Recommended first docs:
 

package/SERVICE_CONTRACT.md

@@ -37,6 +37,8 @@ Core routes:
 - `GET /v1/a2c/summary`
 - `GET /v1/x402`
 - `GET /v1/x402/summary`
+- `GET /v1/payment-protocols`
+- `GET /v1/payment-protocols/summary`
 - `GET /v1/settlement`
 - `GET /v1/settlement/summary`
 - `GET /v1/stripe-mpp`
@@ -47,6 +49,22 @@ Core routes:
 - `GET /v1/major-rails/summary`
 - `GET /v1/treasury`
 - `GET /v1/treasury/summary`
+- `GET /v1/pricing-optimization`
+- `GET /v1/pricing-optimization/summary`
+- `GET /v1/pricing-optimization/quote-abandonment-summary`
+- `GET /v1/pricing-optimization/quote-cohorts`
+- `GET /v1/pricing-optimization/recommendations`
+- `GET /v1/activity-ledger`
+- `GET /v1/activity-ledger/summary`
+- `GET /v1/operator-observability`
+- `GET /v1/operator-observability/summary`
+- `GET /v1/treasury-destinations`
+- `GET /v1/treasury-destinations/summary`
+- `GET /v1/treasury-destinations/operator-pack`
+- `GET /v1/treasury-destinations/operator-pack/summary`
+- `POST /v1/treasury-destinations/validate-preview`
+- `GET /v1/treasury-egress-policy`
+- `GET /v1/treasury-egress-policy/summary`
 - `GET /v1/erc8004`
 - `GET /v1/erc8004/summary`
 - `GET /v1/event-systems`
@@ -87,11 +105,21 @@ Operational note:
 - for production acceptance, `POST /x402/commands/execute` and `POST /x402/mcp/tools/invoke` should normally run with `XYTARA_PAYMENT_VERIFICATION_MODE=local_signed` or a stronger verifier mode
 - `GET /v1/identity-interop` exposes how native authority and machine identity map to `JWT`, `DID/VC`, and `SD-JWT VC` interop lanes without replacing the native runtime authority model
 - `GET /v1/x402` exposes the first-class quote -> challenge -> pay -> execute lane for paid machine execution
+- `GET /v1/payment-protocols` makes the charging boundary explicit: keep auth, discovery, docs, catalog, and lightweight preview free while keeping execution, credit consumption, and consequence-bearing runtime work paid
 - `GET /v1/settlement` exposes the settlement family map across native BSV/Teranode, EVM/Base/USDC, and the major-rails family
 - `GET /v1/stripe-mpp` exposes the hosted-checkout and external-funding entry lane without making provider-specific checkout semantics the center of the stack
 - `GET /v1/stablecoins` exposes the current USDC/Base runtime family and marks Circle Nanopayments/CCTP as adapter-ready extensions instead of pretending they are already core first-party rails
 - `GET /v1/major-rails` exposes Solana plus the Antelope/Proton XPR/Metal family as one practical non-default settlement lane
 - `GET /v1/treasury` exposes the treasury-connectivity posture and the internal reserve doctrine of BSV/Teranode plus DAI/USDC, with Monero retained only as an optional hidden privacy reserve
+- `GET /v1/pricing-optimization` exposes minimum charge floors, starter pricing posture, credit-pack breakpoints, high-consequence premium multipliers, and quote abandonment visibility so revenue posture is reviewable instead of implicit
+- `GET /v1/pricing-optimization/quote-cohorts` and `GET /v1/pricing-optimization/recommendations` expose how quote conversion and abandonment behave by pricing band, payment protocol, and settlement mode so monetization tuning can be data-shaped rather than guessed
+- `GET /v1/activity-ledger` exposes one operator-grade ledger across quote, payment, settlement, delivery, dispute, refund, credit-grant, bridge, and integration-admission activity so operators can answer who did what, paid what, received what, and through which route
+- `GET /v1/operator-observability` exposes a protected read-only pack across activity, payment, delivery, settlement, adapter failure, credit-grant, and pricing telemetry posture without moving funds or submitting settlements
+- `GET /v1/treasury-destinations` is public-readiness only: it shows which rails are operationally configured without exposing actual landing references
+- `GET /v1/treasury-destinations/operator-pack` is the operator-only custody surface and is where real destination references belong
+- `POST /v1/treasury-destinations/validate-preview` lets operators preview per-rail custody readiness before they claim a rail as operational
+- `GET /v1/treasury-egress-policy` makes the treasury black-hole posture explicit: funds can come in easily through configured rails, but treasury release remains blocked until manual operator review with explicit reason and signoff
+- when `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN` is configured, `GET /v1/activity-ledger`, `GET /v1/operator-observability`, `GET /v1/treasury-destinations/operator-pack`, `POST /v1/treasury-destinations/validate-preview`, and `GET /v1/treasury-egress-policy` require that bearer token
 - `GET /v1/providers` exposes the OpenAI Codex and Claude/MCP family as first-class provider entry lanes
 - `GET /v1/frameworks` exposes LangGraph, LangChain, AutoGen, and Semantic Kernel as the primary runtime framework lanes, with CrewAI and LlamaIndex surfaced as registry-backed framework breadth
 - `GET /v1/protocols` exposes the canonical protocol and transport family across MCP, A2A, A2C, ACP, gRPC, Kafka, NATS, MQTT, ROS2, and webhook-event-bus posture
@@ -103,6 +131,9 @@ Operational note:
 - `GET /v1/feature-control` exposes OpenFeature/OFREP-aligned rollout and policy portability posture across pricing, authority, identity, trust, and release gates
 - accepted payments then flow into payment-ledger, treasury-summary, rail-summary, and reconciliation surfaces
 - the default first-party settlement posture is now `bsv_teranode`, and `x402` challenge quotes carry native BSV/Teranode settlement hints when that default path is in use
+- the default machine-payment lane remains `x402`, while credits and `stripe_mpp` provide repeat-use and human-funding paths, and future protocol expansion should normally enter through the payment front rather than replacing the default machine lane
+- quote-based pricing is intentionally preferred over flat pricing because it protects margin on high-consequence work without overpricing small utility flows, but quote abandonment and conversion should still be monitored through the pricing-optimization layer
+- production acceptance on `bsv_teranode`, `evm`, `base`, `usdc`, `dai`, or `monero` should only be claimed once the corresponding treasury destination is explicitly configured and visible through `GET /v1/treasury-destinations`, with real custody details limited to `GET /v1/treasury-destinations/operator-pack`
 - in production, `POST /v1/credit-bridge/grants` should normally require `authorization: Bearer <token>` backed by `XYTARA_CREDIT_BRIDGE_BEARER_TOKEN`
 - in production, spend-credential issuance/revoke should normally require `authorization: Bearer <token>` backed by `XYTARA_ACCOUNT_AUTH_BEARER_TOKEN`
 

package/START_HERE.md

@@ -18,6 +18,45 @@ Its job is to let a caller:
 
 ## 2. Run The Fastest Real Example
 
+For an outside builder, the shortest public spine is:
+
+```text
+quote -> pay/credits -> execute -> prove
+```
+
+Open:
+
+```text
+https://www.naxytra.com/v1/first-run-path
+https://www.naxytra.com/v1/first-run-kit
+```
+
+The first safe runtime command is quote-only:
+
+```bash
+xytara first-run --run-quote --account ACCOUNT_REF --pretty
+```
+
+The underlying command is:
+
+```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:
+
+```bash
+xytara first-run --execute-with-credits --account ACCOUNT_REF --pretty
+```
+
+Then hand the result into `xoonya` for proof review and verification:
+
+```bash
+xoonya first-run --verify-native --pretty
+```
+
+## 3. Run The Fastest Local Package Example
+
 Run:
 
 ```bash
@@ -37,7 +76,7 @@ If you want the shortest neutral external-adoption bundle, continue with:
 - [EXAMPLE_PATHS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/EXAMPLE_PATHS.md)
 - `node examples/partner_launch_walkthrough.js`
 
-## 3. Verify The Whole Package
+## 4. Verify The Whole Package
 
 Run:
 
@@ -53,9 +92,22 @@ If you are evaluating a real deployment that will use grants, credits, entitleme
 npm run verify:production-readiness
 ```
 
-That gate is stricter than local verification and expects runtime persistence to be configured through `XYTARA_STATE_FILE` on persistent disk or `XYTARA_SUPABASE_*`.
+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
 
-## 4. Read The Durable Contract
+## 5. Read The Durable Contract
 
 For long-term product understanding, read:
 
@@ -79,14 +131,38 @@ For long-term product understanding, read:
 - `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/capability-registry/commercialization-summary`
+- `GET /v1/go-live`
+- `GET /v1/go-live/summary`
 - [PROGRAM_STATUS.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PROGRAM_STATUS.md)
 - [OPERATOR_START_HERE.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATOR_START_HERE.md)
 - [OPERATIONS_RUNBOOK.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/OPERATIONS_RUNBOOK.md)
@@ -96,9 +172,11 @@ For long-term product understanding, read:
 - [PARTNER_READY_PATH.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/PARTNER_READY_PATH.md)
 - [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)
+- [TREASURY_DESTINATIONS.example.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TREASURY_DESTINATIONS.example.json)
+- [TREASURY_DESTINATIONS.production.template.json](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TREASURY_DESTINATIONS.production.template.json)
 - [TERMINOLOGY.md](C:/Users/Yoga/Desktop/workspace/vscode_workspace_public/naxytra/xytara/TERMINOLOGY.md)
 
-## 5. If You Are Building Adapters
+## 6. If You Are Building Adapters
 
 Continue with:
 
@@ -107,7 +185,7 @@ 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)
 
-## 6. Production Reading Rule
+## 7. Production Reading Rule
 
 If you only remember one thing, remember this:
 
@@ -123,7 +201,30 @@ If you want the shortest CLI-first read of the package after install, use:
 - `xytara release --summary`
 - `xytara run --help`
 
-## 7. If You Are Operating The Closed Program
+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/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: