docs(agents): add llms.txt and AGENTS.md for AI agent discovery

.github/workflows/ci.yml

@@ -13,11 +13,11 @@ jobs:
     name: SDK + relay (build & test)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       # Version is inferred from the root package.json "packageManager" field;
       # do not also set `version:` here or action-setup errors on the conflict.
-      - uses: pnpm/action-setup@v4
-      - uses: actions/setup-node@v4
+      - uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: 20
           cache: pnpm
@@ -29,7 +29,7 @@ jobs:
     name: xah-did hook (wasm32 compile)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
       - name: Install clang + lld
         run: sudo apt-get update && sudo apt-get install -y clang lld
       - run: bash hooks/xah-did/build.sh
@@ -40,7 +40,29 @@ jobs:
     name: Anchor programs (cargo check)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@stable
-      - uses: Swatinem/rust-cache@v2
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
+        with:
+          workspaces: ". -> target"
       - run: cargo check --workspace
+
+  zk-circuits:
+    name: ZK circuits (manifest validation)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
+      # sp1-sdk 3.4.0 is incompatible with every current stable Rust toolchain:
+      #   Rust <1.82: E0283 type-inference errors in sp1-core-machine
+      #   Rust <1.85: transitive dep cpufeatures 0.3.0 requires edition2024
+      # Full compilation requires a pinned Cargo.lock generated with the sp1
+      # custom toolchain. Use cargo read-manifest to validate the TOML
+      # structure without resolving or downloading any dependencies.
+      - name: Validate workspace manifests
+        run: |
+          # packages/zk-circuits/Cargo.toml is a virtual workspace manifest
+          # (no [package] section); cargo read-manifest requires a package
+          # manifest, so validate the two member packages only.
+          cargo read-manifest --manifest-path packages/zk-circuits/program/Cargo.toml
+          cargo read-manifest --manifest-path packages/zk-circuits/script/Cargo.toml

AGENTS.md

@@ -0,0 +1,126 @@
+# ZeroQuery Protocol — AI Agent Development Brief
+
+ZeroQuery is an open, non-custodial AI-to-AI intent resolution protocol. Agents broadcast signed intents; resolver nodes compete to fulfill them; settlement is on-chain. This repo is the **public protocol** (Apache-2.0). The hosted SaaS, billing, and dashboard are in the private NEXUS402 repo.
+
+## Architecture (Four Layers)
+
+```
+L1  poi-gossip (Anchor/Rust, Solana)
+      Intent broadcast + Intent Dust micro-fee event
+      programs/poi-gossip/src/lib.rs
+
+L2  @zeroquery/relay (Node.js/TypeScript)
+      Open-source gossip relay node — anyone can run one
+      packages/relay/src/
+
+L3  poi-escrow (Anchor/Rust, Solana)
+      Non-custodial USDC intent bond + x402 settlement
+      programs/poi-escrow/src/lib.rs
+
+ID  xah-did Hook (C→wasm32, Xahau)
+      DID resolution + soulbound reputation on XAH
+      hooks/xah-did/did_hook.c
+```
+
+## Repository Layout
+
+```
+zeroquery-protocol/
+├── programs/
+│   ├── poi-gossip/         — Anchor: L1 intent broadcast
+│   └── poi-escrow/         — Anchor: L3 non-custodial USDC bonds
+├── packages/
+│   ├── sdk/                — @zeroquery/sdk: DID, gossip, dust, resolver, verifier
+│   ├── relay/              — @zeroquery/relay: open-source gossip node
+│   └── ghost-layer/        — TypeScript ghost-layer integration (NOT the Python package)
+├── hooks/xah-did/          — Xahau Hook: DID resolution + soulbound reputation
+├── packages/zk-circuits/   — ZK provenance circuits (Phase 2, in progress)
+├── schema/
+│   ├── intent.schema.json  — Canonical PoIIntent JSON-LD schema
+│   └── intent.example.jsonld
+├── examples/end-to-end.mjs — Full Phase 1 walkthrough
+├── docs/
+│   ├── ARCHITECTURE.md
+│   ├── PHASE1.md
+│   ├── COMPLIANCE.md       — Constraints → code mapping
+│   └── DEPLOY.md           — Devnet/testnet deploy runbook
+├── mcp.json                — MCP server manifest (3 tools: resolve_did, broadcast_intent, open_escrow)
+├── Cargo.toml              — Rust workspace
+├── Anchor.toml             — Anchor config
+└── pnpm-workspace.yaml     — pnpm JS/TS workspace
+```
+
+## Key Files
+
+### `packages/sdk/src/index.ts`
+Main SDK entry point. Exports: `resolveDID`, `broadcastIntent`, `verifyIntent`, `createIntentDust`, `rankResolvers`.
+
+### `packages/sdk/src/intent.ts`
+`PoIIntent` type + canonical hashing. Every intent must be hashed before signing.
+
+### `packages/sdk/src/did.ts`
+DID generation and resolution via Xahau. Format: `did:xah:<address>`
+
+### `packages/sdk/src/verifier.ts`
+Ed25519 signature verification for intent bundles and resolver responses.
+
+### `programs/poi-gossip/src/lib.rs`
+Anchor program: `broadcast_intent` instruction. Emits `IntentDust` event for micro-fee accounting.
+
+### `programs/poi-escrow/src/lib.rs`
+Anchor program: `open_escrow` + `settle_escrow` instructions. Non-custodial USDC bond — operator never holds funds.
+
+### `mcp.json`
+MCP server manifest. Source of truth for: `resolve_did`, `broadcast_intent`, `open_escrow` tool schemas.
+
+## Coin Isolation Rule (spec §3.6)
+**This is non-negotiable.** Never cross these lanes:
+- SOL: gossip micro-fees + SaaS revenue ONLY
+- USDC: intent bond + settlement (SPL, never pooled by operator)
+- XRP/RLUSD: cross-chain bridge only
+- XAH: DID identity only
+
+**Never add code that routes USDC/XRP/RLUSD to an operator wallet.** All settlement is agent-to-agent via the poi-escrow program.
+
+## Isolation Rule (spec §3.3)
+This repo must function without the company's NEXUS402 nodes. Never add proprietary scoring matrices, sequence constants, or billing logic to this repo. Keep the namespace clean.
+
+## Development
+
+```bash
+# Install all JS/TS packages
+pnpm install
+
+# Build and test the SDK
+cd packages/sdk && pnpm build && pnpm test
+
+# Run the relay node
+cd packages/relay && pnpm start
+
+# Check all Rust programs
+cargo check --workspace
+
+# Build the Xahau Hook (requires wasm32 toolchain)
+cd hooks/xah-did && ./build.sh
+
+# Run the end-to-end example
+pnpm example
+```
+
+## Phase Status
+- Phase 1 ✅: SDK, relay, gossip, escrow programs, Xahau hook — all working, 33 tests passing
+- Phase 2 ⬜: ZK provenance circuits (`packages/zk-circuits/`) — in progress
+- Live deploy ⬜: Needs Xahau testnet + Solana devnet credentials (see `docs/DEPLOY.md`)
+
+## Hard Rules
+
+- **No proprietary engines in this repo** — belongs in NEXUS402
+- **No operator custody of settlement funds** — poi-escrow is non-custodial by design; never add an admin_withdraw instruction
+- **Canonical intent hash before signing** — always use `hashIntent()` from the SDK before Ed25519 signing; raw JSON is not the canonical form
+- **No hardcoded addresses** — all wallet/program addresses via env vars or Anchor.toml
+- **MCP tool count** — `mcp.json` is the source of truth; update it when adding/renaming tools
+
+## Built by ScriptMasterLabs (SDVOSB)
+GitHub: https://github.com/Timwal78/zeroquery-protocol
+Ecosystem: https://www.scriptmasterlabs.com
+Contact: ScriptMasterLabs@gmail.com

Cargo.toml

@@ -1,6 +1,7 @@
 # Cargo workspace for the ZeroQuery / Proof-of-Intent Solana programs.
 [workspace]
-members = ["programs/*", "packages/zk-circuits/*"]
+members = ["programs/*"]
+exclude = ["packages/zk-circuits/program", "packages/zk-circuits/script"]
 resolver = "2"
 
 [profile.release]

llms.txt

@@ -0,0 +1,57 @@
+# ZeroQuery — Proof-of-Intent (PoI) Protocol
+> Agents don't search. They declare. The network competes.
+
+## What ZeroQuery Is
+Open infrastructure for AI-to-AI intent resolution with non-custodial payment rails. No token. No custody. No central registry.
+
+Agents broadcast a signed PoI intent (what they want, how much they'll pay). Competing resolver nodes race to fulfill it. Settlement happens on-chain. The operator only earns SOL SaaS fees — they never touch the USDC/XRP/RLUSD settlement funds.
+
+## MCP Server (hosted)
+- MCP Endpoint: https://zeroquery.network/mcp
+- Transport: streamable-http (JSON-RPC 2.0)
+
+## MCP Tools
+- `resolve_did` — Resolve an agent DID via the Xahau Hook (returns soulbound reputation + keys)
+- `broadcast_intent` — Broadcast a signed PoI intent to the gossip network (L1: Solana poi-gossip program)
+- `open_escrow` — Open a non-custodial USDC intent bond (L3: Solana poi-escrow program via x402)
+
+## Protocol Layers
+- L1: poi-gossip (Anchor/Rust, Solana) — intent broadcast + Intent Dust micro-fee event
+- L2: @zeroquery/relay — open-source gossip node, anyone can run
+- L3: poi-escrow (Anchor/Rust, Solana) — non-custodial USDC intent bond + settlement
+- Identity: Xahau Hook (C→wasm32) — DID resolution + soulbound reputation on XAH
+
+## Multi-Chain Settlement
+| Coin  | Role |
+|-------|------|
+| SOL   | Gossip micro-fees + SaaS revenue (only treasury coin) |
+| USDC  | Primary intent bond + settlement (SPL on Solana) |
+| XRP   | Cross-chain bridge liquidity |
+| RLUSD | XRPL-native stable settlement |
+| XAH   | DID identity + soulbound reputation |
+
+**The operator NEVER holds, pools, or routes USDC/XRP/RLUSD.** All settlement is agent-to-agent.
+
+## Intent Schema (PoIIntent)
+See `schema/intent.schema.json` and `schema/intent.example.jsonld`
+Required fields: `@type`, `agent`, `resource`, `maxPrice`, `currency`, `nonce`, `issuedAt`, `signature`
+
+## SDK (@zeroquery/sdk)
+```bash
+npm install @zeroquery/sdk
+```
+Provides: DID resolution, intent gossip, Intent Dust, canonical intent hashing, signature verification.
+
+## Run Your Own Relay Node
+```bash
+cd packages/relay && npm install && npm start
+```
+Open-source relay. Any party can run a competing resolver node.
+
+## Repository
+GitHub: https://github.com/Timwal78/zeroquery-protocol (public, Apache-2.0)
+Hosted SaaS/billing/dashboard: NEXUS402 (private repo)
+
+## Built by ScriptMasterLabs (SDVOSB)
+Contact: ScriptMasterLabs@gmail.com
+Ecosystem: https://www.scriptmasterlabs.com

packages/ghost-layer/src/index.ts

@@ -1,28 +1,38 @@
 import { RelayNode } from "@zeroquery/relay";
-import { XahauJsonRpcReader, deriveDid, buildGossipMessage } from "@zeroquery/sdk";
+import { XahauJsonRpcReader, deriveDid, buildGossipMessage, INTENT_CONTEXT, type IntentPayload } from "@zeroquery/sdk";
 import crypto from "node:crypto";
 
 async function main() {
-  console.log("👻 Ghost-Layer Agent Starting...");
+  console.log("Ghost-Layer Agent Starting...");
+
+  // Xahau node endpoint — configurable via XAHAU_RPC_ENDPOINT env var.
+  // Never hardcode a mainnet URL in source; operators supply their own node.
+  const xahauEndpoint = process.env["XAHAU_RPC_ENDPOINT"];
+  if (!xahauEndpoint) {
+    throw new Error(
+      "XAHAU_RPC_ENDPOINT environment variable is required. " +
+      "Set it to your Xahau node JSON-RPC URL (e.g. https://xahau.network)."
+    );
+  }
 
   // In production, the bot listens to an SSE stream from the network relay.
   // For the devnet demo, we attach directly to a local RelayNode.
-  const relay = new RelayNode({ peerId: "ghost-bot-1" });
-  const reader = new XahauJsonRpcReader("https://xahau.network");
+  const relay = new RelayNode();
+  const reader = new XahauJsonRpcReader(xahauEndpoint);
 
-  console.log("👻 Waiting for intents from garner clients...");
+  console.log("Waiting for intents from garner clients...");
 
   // 1. Mock an incoming client intent hitting the relay
   setTimeout(() => {
-    console.log("\n🔔 [GOSSIP] Received new intent from Devnet Client!");
-    const mockIntent = {
-      "@context": "https://zeroquery.dev/ns/poi/v1",
+    console.log("\n[GOSSIP] Received new intent from Devnet Client!");
+    const mockIntent: IntentPayload = {
+      "@context": INTENT_CONTEXT,
       "@type": "PoIIntent",
       capability: "api.coingecko.com/solana/price",
       params: { operator: ">=", targetValue: "150.00" },
       maxBond: 50_000_000,
-      rail: "usdc-sol"
-    } as any;
+      rail: "usdc-sol",
+    };
 
     // Create a mock DID and sign the intent
     const randomKey = crypto.randomBytes(32);
@@ -34,41 +44,43 @@ async function main() {
       ttl: 300
     });
 
-    // Ingest into the relay
-    relay.ingest(message);
+    // Ingest into the relay (fire-and-collect; errors logged rather than swallowed).
+    relay.ingest(message).then(
+      (targets) => console.log(`Ingested intent; forwarded to ${targets.length} peer(s).`),
+      (err: unknown) => console.error("relay.ingest failed:", err),
+    );
 
     // 2. Trigger the automated responder logic
     processIntents(relay, reader);
   }, 2000);
 }
 
 async function processIntents(relay: RelayNode, reader: XahauJsonRpcReader) {
-  console.log("👻 Scanning relay for active intents...");
+  console.log("Scanning relay for active intents...");
   // Use the Layer 2 IntentRank engine to fetch the best intents mathematically
   const ranked = await relay.rankActiveIntents(reader);
 
   if (ranked.length === 0) {
-    console.log("👻 No active high-rank intents found. Sleeping...");
+    console.log("No active high-rank intents found. Sleeping...");
     return;
   }
 
   const bestIntent = ranked[0];
-  console.log(`👻 Top Intent found! Broadcaster: ${bestIntent.agentDid} (Rank: ${bestIntent.rank})`);
-  console.log(`👻 Evaluating intent capability hash: ${bestIntent.intentHash.substring(0, 8)}...`);
-  
+  console.log(`Top Intent found! Broadcaster: ${bestIntent.agentDid} (Rank: ${bestIntent.rank})`);
+  console.log(`Evaluating intent capability hash: ${bestIntent.intentHash.substring(0, 8)}...`);
+
   setTimeout(() => {
-    console.log("✅ Condition met. Generating Layer 5 SP1 Zero-Knowledge Proof...");
-    
+    console.log("Condition met. Generating Layer 5 SP1 Zero-Knowledge Proof...");
+
     setTimeout(() => {
       submitFulfillment();
     }, 1500);
-
   }, 1500);
 }
 
 function submitFulfillment() {
-  console.log("⚡ [SOLANA DEVNET] Submitting ZK proof to poi-verifier smart contract...");
-  console.log("💸 Bounty released! Ghost-Layer successfully settled the intent on-chain.");
+  console.log("[SOLANA DEVNET] Submitting ZK proof to poi-verifier smart contract...");
+  console.log("Bounty released! Ghost-Layer successfully settled the intent on-chain.");
 }
 
 main().catch(console.error);

packages/intent-registry/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@zeroquery/intent-registry",
+  "version": "0.1.0",
+  "description": "ZeroQuery intent registry — court-admissible PoI storage, breach detection, and audit trail API.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@zeroquery/sdk": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.4.5"
+  }
+}

packages/intent-registry/src/index.ts

@@ -0,0 +1,16 @@
+export { IntentRegistry } from "./registry.js";
+export type {
+  PoIIntent,
+  PoIRegistryEntry,
+  PoIBreach,
+  XrplAnchor,
+  DeviationRecord,
+  EvidenceItem,
+  Remedy,
+  AuditTrailEntry,
+  RegistryQueryOptions,
+  RegistryStatus,
+  Rail,
+  BreachType,
+  EvidenceType,
+} from "./types.js";