xoonya 3.1.17 → 3.2.1

package/README.md

@@ -1,111 +1,134 @@
 # xoonya
 
-**Deterministic proof & review engine with post-quantum verification** — for receipts, handoffs,
-governance, and the native **XNYA** machine-evidence format. xoonya is the proof-side half of the
-naxytra machine stack; the runtime/payments half is [xytara](https://naxytra.com/xytara).
+**Verifier for xoonya proofs and naxytra delivery evidence.**
 
-It makes machine evidence **deterministic, portable, minimal, verifiable, and replayable**, and
-verifies it with both classical and **post-quantum** signatures.
+xoonya is the proof side of the naxytra machine stack: a hosted proof engine that emits
+deterministic, portable machine evidence for paid agent work, plus this public verifier that lets
+anyone check that evidence offline with classical and **post-quantum** signatures.
 
-## Proven live on Base mainnet
+> The proof engine and server are a hosted service; this package is the verifier. The engine is
+> not distributed.
 
-Post-quantum proof verification is real and demonstrated: a paid x402 call (gasless USDC on Base)
-routes to xoonya's `/execute`, which verifies a native **XNYA** proof bundle signed with a hybrid
-**Ed25519 + ML-DSA-65 (FIPS-204)** suite and returns a `verified_native_hybrid_signature` verdict.
-Adversarially, downgrade-to-classical and the unsigned `none` algorithm are both rejected.
+- Hosted service: https://xoonya.onrender.com
+- Product page: https://www.naxytra.com/xoonya
+- Agent entry points: https://www.naxytra.com/agents
 
-> Scope: XNYA is **machine-evidence verification** — a portable, deterministic check that a proof is
-> well-formed and cryptographically signed. It is **not** an identity, custody, settlement,
-> transport-security, or chain-finality claim.
+## What this package verifies
 
-## What it does
+- **Native proof bundles** (`proof-bundle/v1`) carrying a canonical event bundle and a receipt:
+  - `xoonya-native-sha256-v1` — replayable digest (integrity, not authorship)
+  - `xoonya-native-signed-v1` — Ed25519 / secp256k1 / P-256 signature bound to the carried public key
+  - `xoonya-native-hybrid-v1` — classical + post-quantum dual signature (Ed25519 + ML-DSA-65, FIPS 204)
+  - `xoonya-native-anchored-v1` — digest binding to declared chain / batch / finality anchor refs
+  - structural acceptance of external envelopes (`detached-assertion`, `jwt-assertion`, `did-vc`,
+    `sd-jwt-vc`, `signed-envelope`, `partner-proof-envelope`) and the compatibility `legacy-opreturn` receipt
+- **Detached signatures and compact JWS** — EdDSA, ES256/384/512, ES256K, RS*/PS*, and
+  ML-DSA-44/65/87 — with an explicit trusted-key fingerprint model
+- **XNYA machine-evidence atoms**, XNYP payload profiles and line-rate frames
 
-The public proof loop is deliberately narrow:
-
-1. **receive** a handoff or canonical event bundle
-2. **review** it
-3. **verify** it
-4. **emit** a durable proof bundle
-
-xoonya owns proof, review, and continuity. It does not own pricing, catalogs, workflow
-orchestration, payment rails, or settlement — those live in [xytara](https://naxytra.com/xytara).
+Everything runs on Node built-ins (`node:crypto`); there are no dependencies.
 
 ## Install
 
 ```bash
-npm install xoonya
+npm install xoonya          # Node 24 or newer
 ```
 
-## Quickstart — CLI
-
-```bash
-xoonya start-here                        # the shortest first-run path
-xoonya first-run --verify-native --pretty
-xoonya conformance --json                # run proof + adversarial vectors
-xoonya review --help
-```
+## Verify a native proof bundle
 
-## Quickstart — SDK
+A proof bundle is what the hosted service (or a counterparty running it) hands back after a paid
+execution. Verification is deterministic and offline:
 
 ```js
 const xoonya = require("xoonya");
-
-// 1. emit a signed receipt for a canonical event
-const receipt = xoonya.emitReceipt(event, { /* receipt options */ });
-
-// 2. build a portable proof bundle
-const bundle = xoonya.buildProofBundle({ ceb: event, receipt });
-
-// 3. verify it anywhere, deterministically
-const result = xoonya.verifyProofBundle(bundle);
-// => { valid: true, verification_method: "xoonya-native-hybrid-v1",
-//      verification_state: "verified_native_hybrid_signature", ... }
+const bundle = JSON.parse(require("fs").readFileSync("proof-bundle.json", "utf8"));
+
+const result = xoonya.verifyNativeBundle(bundle);
+// {
+//   valid: true,
+//   verification_method: "xoonya-native-hybrid-v1",
+//   verification_state: "verified_native_hybrid_signature",
+//   verification_class: "cryptographic",
+//   cryptographically_verified: true,
+//   public_key_ref: "ed25519+ml-dsa-65-hybrid-spki-sha256:...",
+//   classical_public_key_ref: "ed25519-spki-sha256:...",
+//   pq_public_key_ref: "ml-dsa-65-spki-sha256:...",
+//   ...
+// }
 ```
 
-## Verification methods
+A valid result says the bundle is well-formed, bound to the canonical event, and (for signed /
+hybrid methods) really signed by the carried public key. It does not say who controls that key.
+Bind the key to an identity you already trust, and refuse digest-only and structural results, with
+options:
 
-xoonya verifies the **native XNYA** family and common **external** formats for interop:
+```js
+xoonya.verifyNativeBundle(bundle, {
+  strict: true, // only cryptographically verified methods pass
+  trusted_public_key_refs: {
+    "did:xoonya:agent-1": {
+      classical: "ed25519-spki-sha256:...",
+      pq: "ml-dsa-65-spki-sha256:..."
+    }
+  }
+});
+// a bundle signed by any other key => { valid: false, reason: "native_hybrid_public_key_not_trusted" }
+```
 
-- **Native (XNYA):** `xoonya-native-sha256-v1`, `xoonya-native-signed-v1` (Ed25519 / secp256k1 /
-  P-256), `xoonya-native-hybrid-v1` (**classical + post-quantum**: ML-DSA-65 / FIPS-204,
-  SLH-DSA / FIPS-205), `xoonya-native-anchored-v1`.
-- **External:** `signed-envelope`, `detached-assertion`, `jwt-assertion`, `sd-jwt-vc`, `did-vc`,
-  `partner-proof-envelope`, `legacy-opreturn`.
+`verifyNativeProof({ event, receipt, anchors })` does the same for a receipt that is not yet wrapped in
+a bundle. `XOONYA_STRICT_VERIFY=1` turns strict mode on for every call.
 
-Conformance and adversarial vectors ship in `vectors/`; the `XNYA-compatible` mark is defined in
-[`XNYA_CONFORMANCE_MARK.md`](./XNYA_CONFORMANCE_MARK.md).
+## Verify a detached ML-DSA signature
 
-## As a paid service (x402)
+```js
+const result = xoonya.verifyDetachedSignature({
+  material: deliverableBytes,        // Buffer or string that was signed
+  signature: signatureBase64,        // base64 (default), "hex" or "base64url" via signature_encoding
+  public_key: signerSpkiPem,         // SPKI PEM, base64 DER or public JWK; private material is refused
+  algorithm: "ML-DSA-65",            // or "EdDSA", "ES256", "ES256K", "RS256", "PS256", ...
+  expected_key_ref: "ml-dsa-65-spki-sha256:..." // the fingerprint you already trust (optional)
+});
+// result.signature_valid   => the signature verifies under the supplied key
+// result.signing_key_ref   => "ml-dsa-65-spki-sha256:..." fingerprint of that key
+// result.trust_anchored    => signature_valid AND the key matches expected_key_ref
+```
 
-xoonya runs as a verification service you can pay per call. An agent pays
-[xytara](https://naxytra.com/xytara) with x402 for `adapter.xoonya.invoke` (tool
-`proof.verify-signature` / `proof.verify-bundle` / `proof.verify-envelope` / `proof.verify-receipt`);
-xytara routes to xoonya's bearer-authed `/execute`, which runs real verification and returns the
-verdict. It is billed only on a successful verification.
+`verifyJws(compactJws, { trusted_public_key, expected_key_ref })` verifies a compact JWS the same
+way; `alg: "none"`, `crit` extensions and unencoded payloads are rejected.
 
-Run the server yourself:
+## CLI
 
 ```bash
-XOONYA_EXECUTOR_BEARER_TOKEN=... npm start   # exposes the paid /execute lane
+xoonya start-here                          # the shortest verification path
+xoonya first-run --verify-native --pretty  # run the shipped vectors, print a JSON verdict
+xoonya conformance --json                  # conformance + adversarial vectors, full summary
+xoonya verify ./proof-bundle.json --pretty # verify one bundle; add --strict; exit 1 if invalid
 ```
 
-## Configuration
+`xoonya release` and `xoonya review` are operator tooling of the hosted service and are not part
+of this package.
 
-- `XOONYA_STRICT_VERIFY=1` — only cryptographically verified (native signed / hybrid) results pass;
-  digest and structural results are rejected.
-- `XOONYA_ACCEPT_PRIVATE_KEY_MATERIAL=false` — refuse private-key material on shared deployments;
-  sign locally with the SDK/CLI instead.
+## Conformance
 
-See [`.env.example`](./.env.example) for the full list.
+`vectors/` ships the conformance and adversarial vectors the hosted engine is tested against
+(eleven verification methods, fifteen rejection cases, XNYA atom and payload-profile vectors).
+`xoonya.verifyVectors()` runs them in-process and returns the summary. The same vectors are run by
+both the hosted engine and this verifier before every release, and every result must be identical.
 
-## Learn more
+## Honest claims
 
-- Why two packages: [`WHY_XYTARA_XOONYA.md`](./WHY_XYTARA_XOONYA.md)
-- Native proof format: [`XOONYA_NATIVE_PROOF_FORMAT.md`](./XOONYA_NATIVE_PROOF_FORMAT.md) ·
-  atom spec: [`XOONYA_NATIVE_ATOM_SPEC.md`](./XOONYA_NATIVE_ATOM_SPEC.md)
-- Start here: [`START_HERE.md`](./START_HERE.md) · terminology: [`TERMINOLOGY.md`](./TERMINOLOGY.md)
-- Live: https://naxytra.com/xoonya
+- **Post-quantum means machine-evidence verification.** A `verified_native_hybrid_signature`
+  verdict says the proof was signed by the carried Ed25519 and ML-DSA-65 keys. It is not an
+  identity, custody, settlement, transport-security or chain-finality claim.
+- **Proven suites:** Ed25519 and Ed25519 + ML-DSA-65 are exercised by the shipped vectors and by a
+  live paid verification on Base mainnet through the naxytra runtime. secp256k1, P-256 and
+  SLH-DSA are implemented suites but are not covered by shipped vectors.
+- **Digest and anchored methods prove integrity, not authorship.** Anyone can produce a valid
+  digest; anchor refs are bound, not checked against the external chain or provider.
+- **Trust in a signing key is yours to declare.** A key carried inside a proof, or supplied in the
+  same request, is never treated as trusted by itself.
 
 ## License
 
-Apache-2.0. See [`LICENSE`](./LICENSE) and [`NOTICE`](./NOTICE).
+The verifier SDK is Apache-2.0 (see `LICENSE` and `NOTICE`). The hosted xoonya proof engine and
+server are proprietary.

package/RELEASE_NOTES.md

@@ -1 +1 @@
-`xoonya` 3.1.17 is a synchronized-line release with no change to the proof engine, verification behavior, vectors, routes, or package contents. It is published through npm trusted publishing (GitHub OIDC), with no npm token involved.
+`xoonya` 3.2.1 is a synchronized-line release with no change to the verifier package contents, vectors or verification behavior. It is published through npm trusted publishing (GitHub OIDC), with no npm token involved.

package/START_HERE.md

@@ -1,159 +1,63 @@
 # xoonya Start Here
 
-This is the shortest reliable path for understanding and using the public `xoonya` package in production-facing order.
+`xoonya` on npm is the **verifier** for xoonya proofs and naxytra delivery evidence. The proof
+engine and server are a hosted service (https://xoonya.onrender.com); this package is the
+verifier. The engine is not distributed.
 
-The phase program is now complete, so this file is the right starting point for a closed and release-shaped proof system rather than an in-flight milestone build.
-
-The product-side implementation, proof posture, and bounded hybrid verification work for the widened `3.0.0` finish line are now complete. The remaining step is the synchronized public `3.0.0` release cut, publish, deploy, and verification sequence documented in NAXYTRA_3_0_0_RELEASE_CONTRACT.md and PUBLISH_PLAN.md.
-
-If you are arriving from the broader public discovery layer, the canonical entry points are:
+If you are arriving from the public discovery layer, the canonical entry points are:
 
+- https://www.naxytra.com/xoonya
 - https://www.naxytra.com/agents
-- https://www.naxytra.com/v1/agent-discovery-index
-- https://www.naxytra.com/.well-known/agent.json
-
-## 1. Understand The Role
-
-`xoonya` is the proof-side half of the public stack.
-
-Its job is to let a caller:
+- https://www.naxytra.com/v1/first-run-kit
 
-1. receive the transaction-side handoff from `xytara`
-2. inspect review and run posture
-3. emit proof-native completion artifacts
-4. verify the final proof bundle
+## 1. The role
 
-For the full public quote -> execute -> prove path, start from:
+The public spine is `quote -> pay/credits -> execute -> prove -> verify`. The naxytra runtime
+(`xytara`) owns quotes, payment and execution; the hosted xoonya engine emits the proof; this
+package lets you verify that proof anywhere, offline, deterministically.
 
-```text
-https://www.naxytra.com/v1/first-run-kit
-```
-
-Then run the local proof followthrough:
+## 2. Install and run the shipped vectors
 
 ```bash
+npm install xoonya
+xoonya start-here
 xoonya first-run --verify-native --pretty
+xoonya conformance --json
 ```
 
-If you want the frozen machine-readable proof-truth contract behind that flow, inspect:
-
-```text
-GET /v1/proof-truth
-GET /v1/proof-truth/summary
-```
-
-If you want the frozen machine-readable proof default-path contract behind that flow, inspect:
+`first-run --verify-native` must print `"ok": true` and `"required_native_methods_present": true`.
+The verification methods include `xoonya-native-sha256-v1`, `xoonya-native-signed-v1`,
+`xoonya-native-hybrid-v1` (Ed25519 + ML-DSA-65) and `xoonya-native-anchored-v1`.
 
-```text
-GET /v1/default-path
-GET /v1/default-path/summary
-```
-
-If you want the frozen machine-readable followthrough claim boundary behind that flow, inspect:
-
-```text
-GET /v1/followthrough-truth
-GET /v1/followthrough-truth/summary
-```
-
-## 2. Run The Fastest Real Example
-
-Run:
+## 3. Verify a real bundle
 
 ```bash
-node examples/package_quickstart.js
+xoonya verify ./proof-bundle.json --pretty            # exit 0 if valid, 1 otherwise
+xoonya verify ./proof-bundle.json --strict --pretty   # only cryptographically verified methods pass
 ```
 
-This is the fastest way to see the intended proof-side package story end-to-end.
-
-If you want the clearest cross-repo adoption path instead of the broad package tour, continue with:
+Or in code:
 
-- CARRIED_HANDOFF_DEMO.md
+```js
+const xoonya = require("xoonya");
+const result = xoonya.verifyNativeBundle(bundle, { strict: true, trusted_public_key_refs: { ... } });
+```
 
-If you want the shortest neutral external-adoption bundle, continue with:
+For detached signatures (including ML-DSA) use `xoonya.verifyDetachedSignature(...)`; for compact
+JWS use `xoonya.verifyJws(...)`. See `README.md` for the option model.
 
-- PARTNER_READY_PATH.md
-- PUBLIC_DEMO_SCRIPT.md
-- EXAMPLE_PATHS.md
-- `node examples/partner_proof_walkthrough.js`
+## 4. Read the boundary
 
-## 3. Verify The Whole Package
+- A valid result proves binding and signature validity under the carried key, not identity,
+  custody, settlement or external chain truth.
+- Digest and anchored methods prove integrity and replayability, not authorship.
+- Trust in a signing key is declared by you (`expected_key_ref`, `trusted_public_key_refs`).
 
-Run:
+## 5. Hosted surfaces
 
-```bash
-npm run verify:all
-```
+- https://xoonya.onrender.com/v1/proof-center/native-standard/summary
+- https://xoonya.onrender.com/v1/proof-center/native-conformance-mark/summary
+- https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary
 
-This is the production-confidence check for the published proof package surface.
-
-## 4. 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/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/major-rails`
-- `GET /v1/treasury`
-- `GET /v1/erc8004`
-- `GET /v1/proof-bridge`
-- `GET /v1/external-proof-import`
-- `GET /v1/result-package-trust`
-- `GET /v1/event-systems`
-- `GET /v1/integrations`
-- 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
-- TERMINOLOGY.md
-
-## 5. If You Are Integrating From Outside
-
-Continue with:
-
-- CROSS_RUNTIME_POSTURE.md
-- integrations/PROOF_INTEGRATION_PROCESS.md
-- PARTNER_READY_PATH.md
-- COMPATIBILITY_NOTE.md
-
-## 6. Production Reading Rule
-
-If you only remember one thing, remember this:
-
-The main public path is no longer "understand every proof helper first."
-
-It is:
-
-receive handoff -> inspect review posture -> confirm run posture -> emit and verify proof
-
-If you want the shortest CLI-first read of the package after install, use:
-
-- `xoonya start-here`
-- `xoonya release --summary`
-- `xoonya review --help`
-
-## 7. If You Are Operating The Closed Program
-
-Use:
-
-- PROGRAM_STATUS.md
-- OPERATOR_START_HERE.md
+`xoonya release` and `xoonya review` belong to the hosted service's operator tooling and are not
+part of this package.

package/bin/xoonya-first-run.js

@@ -29,8 +29,9 @@ function buildLocalGuide() {
     product: "xoonya",
     category: "xoonya-first-run-proof-guide",
     guide_version: "xoonya-first-run-proof-guide-v1",
+    package_role: "verifier",
     public_command_kit_url: DEFAULT_KIT_URL,
-    role: "proof_followthrough_after_xytara_runtime_execution",
+    role: "proof_verification_after_xytara_runtime_execution",
     safe_local_verification_command: "xoonya first-run --verify-native --pretty",
     proof_modes: [
       {
@@ -39,7 +40,11 @@ function buildLocalGuide() {
       },
       {
         method: "xoonya-native-signed-v1",
-        verification: "ed25519_signature"
+        verification: "native_signature_ed25519_secp256k1_p256"
+      },
+      {
+        method: "xoonya-native-hybrid-v1",
+        verification: "classical_plus_pq_signature_ed25519_ml_dsa_65"
       },
       {
         method: "xoonya-native-anchored-v1",
@@ -58,7 +63,8 @@ function buildLocalGuide() {
     boundaries: [
       "xoonya_verifies_proof_bundles_and_native_method_binding",
       "xoonya_anchor_binding_does_not_claim_external_provider_or_chain_truth",
-      "xytara_owns_runtime_payment_and_execution_state"
+      "xytara_owns_runtime_payment_and_execution_state",
+      "the_proof_engine_is_a_hosted_service_and_is_not_distributed"
     ]
   };
 }
@@ -80,12 +86,12 @@ function printUsage() {
     "Usage: xoonya first-run [options]",
     "",
     "Options:",
-    "  --json             Print the guided proof followthrough object",
+    "  --json             Print the guided proof verification object",
     "  --offline          Do not fetch the public command kit",
     "  --verify-native    Run local native/conformance verification",
     "  --pretty           Pretty-print JSON output",
     "  --help             Show this help message"
-  ].join("\n"));
+  ].join("\n") + "\n");
 }
 
 function runNativeVerification(args) {
@@ -107,6 +113,7 @@ function runNativeVerification(args) {
     product: "xoonya",
     category: "xoonya-first-run-native-verification",
     verification_version: "xoonya-first-run-native-verification-v1",
+    package_role: "verifier",
     proof_bundle_conformance_passed: summary.ok === true,
     conformance_count: summary.conformance_count,
     adversarial_count: summary.adversarial_count,
@@ -114,6 +121,8 @@ function runNativeVerification(args) {
     native_atom_adversarial_count: summary.native_atom_adversarial_count,
     verification_methods: summary.verification_methods,
     native_atom_error_codes: summary.native_atom_error_codes,
+    external_signature_checks: summary.external_signature_checks,
+    engine_parity: summary.engine_parity,
     required_native_methods_present: [
       "xoonya-native-sha256-v1",
       "xoonya-native-signed-v1",
@@ -158,24 +167,27 @@ async function main() {
   process.stdout.write([
     "xoonya first-run",
     "",
-    "Proof followthrough after xytara execution:",
+    "Local proof verification after xytara execution:",
     "  xoonya first-run --verify-native --pretty",
+    "  xoonya verify ./proof-bundle.json --pretty",
     "",
     "Inspect the public command kit:",
     `  ${DEFAULT_KIT_URL}`,
     "",
-    "Native proof modes checked locally:",
+    "Native proof methods checked locally:",
     "  xoonya-native-sha256-v1",
     "  xoonya-native-signed-v1",
+    "  xoonya-native-hybrid-v1",
     "  xoonya-native-anchored-v1",
     "",
-    "Public proof surfaces:",
+    "Hosted proof surfaces:",
     "  https://xoonya.onrender.com/v1/proof-center/native-standard/summary",
     "  https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary",
     "",
     "Boundary:",
-    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external."
-  ].join("\n"));
+    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external.",
+    "  The proof engine is a hosted service; this package is the verifier."
+  ].join("\n") + "\n");
 }
 
 main().catch((error) => {

package/bin/xoonya.js

@@ -1,81 +1,113 @@
 #!/usr/bin/env node
 "use strict";
 
+const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
+const OPERATOR_TOOLING_MESSAGE = "Operator tooling is not part of the xoonya verifier package. See https://www.naxytra.com/xoonya";
+
 function printUsage() {
   process.stdout.write([
     "Usage: xoonya <command> [options]",
     "",
+    "xoonya verifier: checks xoonya proof bundles, native receipts, XNYA atoms and",
+    "detached signatures (Ed25519, ECDSA, RSA, ML-DSA). The proof engine is a hosted",
+    "service and is not part of this package.",
+    "",
     "Commands:",
-    "  release [args]    Open the release/adoption/reporting surface",
-    "  review [args]     Review a carried handoff or proof input",
-    "  conformance       Run proof conformance and adversarial vectors",
-    "  first-run [args]  Guide or run proof followthrough checks",
-    "  start-here        Print the shortest first-run path",
-    "  help              Show this help message",
+    "  start-here                 Print the shortest verification path",
+    "  first-run [args]           Guide or run local native verification",
+    "  conformance [--json]       Run proof conformance and adversarial vectors",
+    "  verify <bundle.json>       Verify a proof bundle file (--strict, --pretty)",
+    "  help                       Show this help message",
     "",
     "Fastest first run:",
     "  xoonya start-here",
-    "  xoonya first-run",
     "  xoonya first-run --verify-native --pretty",
-    "  xoonya release --summary",
     "  xoonya conformance --json",
-    "  xoonya review --help"
-  ].join("\n"));
+    "  xoonya verify ./proof-bundle.json --pretty"
+  ].join("\n") + "\n");
 }
 
 function printStartHere() {
   process.stdout.write([
     "xoonya start-here",
     "",
-    "Public first-run spine:",
-    "  quote -> pay/credits -> execute -> prove",
+    "Role:",
+    "  xoonya verifies proofs and naxytra delivery evidence. The proof engine and",
+    "  server are a hosted service; this package is the verifier.",
+    "",
+    "Public spine:",
+    "  quote -> pay/credits -> execute -> prove -> verify",
     "",
     "1. Open https://www.naxytra.com/v1/first-run-kit",
     "2. Run the xytara quote-only command first; it needs no wallet secret.",
-    "3. After funded execution, verify the proof side:",
+    "3. After funded execution, verify the proof side locally:",
     "   xoonya first-run --verify-native --pretty",
-    "   node examples/package_quickstart.js",
     "   xoonya conformance --json",
-    "4. Inspect native proof surfaces:",
+    "   xoonya verify ./proof-bundle.json --pretty",
+    "4. Inspect hosted proof surfaces:",
     "   https://xoonya.onrender.com/v1/proof-center/native-standard/summary",
     "   https://xoonya.onrender.com/v1/proof-center/native-conformance-mark/summary",
     "   https://xoonya.onrender.com/v1/proof-center/native-anchor-profile/summary",
     "",
-    "Native proof modes:",
+    "Native proof methods verified locally:",
     "  xoonya-native-sha256-v1     replayable digest proof",
-    "  xoonya-native-signed-v1     key-bound authorship proof",
+    "  xoonya-native-signed-v1     key-bound signature proof (ed25519 / secp256k1 / p256)",
+    "  xoonya-native-hybrid-v1     classical + post-quantum proof (ed25519 + ml-dsa-65)",
     "  xoonya-native-anchored-v1   anchor-binding proof",
     "",
     "Boundary:",
-    "  xoonya verifies proof and anchor binding; external chain/provider truth stays external"
-  ].join("\n"));
+    "  xoonya verifies proof binding and signatures; identity, custody, settlement",
+    "  and external chain/provider truth stay external.",
+    "",
+    "More: https://www.naxytra.com/xoonya"
+  ].join("\n") + "\n");
 }
 
-function delegate(scriptName, args) {
-  const scriptPath = path.join(__dirname, scriptName);
+function delegate(scriptPath, args) {
   const result = spawnSync(process.execPath, [scriptPath, ...args], { stdio: "inherit" });
   process.exitCode = typeof result.status === "number" ? result.status : 1;
 }
 
+function readBundleArg(args) {
+  const file = args.find((token) => !token.startsWith("--"));
+  if (!file) {
+    throw new Error("usage: xoonya verify <bundle.json> [--strict] [--pretty]");
+  }
+  const raw = file === "-" ? fs.readFileSync(0, "utf8") : fs.readFileSync(path.resolve(process.cwd(), file), "utf8");
+  return JSON.parse(raw);
+}
+
+function verifyBundleCommand(args) {
+  const verifier = require("../verify");
+  let result;
+  try {
+    const bundle = readBundleArg(args);
+    result = verifier.verifyProofBundle(bundle, { strict: args.includes("--strict") });
+  } catch (error) {
+    result = { valid: false, reason: error.message };
+  }
+  process.stdout.write(`${JSON.stringify(result, null, args.includes("--pretty") ? 2 : 0)}\n`);
+  process.exitCode = result.valid === true ? 0 : 1;
+}
+
 const [command, ...rest] = process.argv.slice(2);
 
 if (!command || command === "help" || command === "--help" || command === "-h") {
   printUsage();
 } else if (command === "start-here" || command === "--start-here") {
   printStartHere();
-} else if (command === "release") {
-  delegate("xoonya-release.js", rest);
-} else if (command === "review") {
-  delegate("xoonya-review.js", rest);
+} else if (command === "release" || command === "review") {
+  process.stderr.write(`${OPERATOR_TOOLING_MESSAGE}\n`);
+  process.exitCode = 2;
 } else if (command === "first-run" || command === "firstrun") {
-  delegate("xoonya-first-run.js", rest);
+  delegate(path.join(__dirname, "xoonya-first-run.js"), rest);
 } else if (command === "conformance" || command === "verify-vectors") {
-  const scriptPath = path.join(__dirname, "..", "scripts", "verify_vectors.js");
-  const result = spawnSync(process.execPath, [scriptPath, ...rest], { stdio: "inherit" });
-  process.exitCode = typeof result.status === "number" ? result.status : 1;
+  delegate(path.join(__dirname, "..", "scripts", "verify_vectors.js"), rest);
+} else if (command === "verify" || command === "verify-bundle") {
+  verifyBundleCommand(rest);
 } else {
   printUsage();
   process.exitCode = 1;