@oracle-agent/oracle 0.3.2 → 0.3.3

package/README.md

@@ -199,10 +199,14 @@ Oracle's default pack is deliberately broad but disarmed:
 
 - **Trader** — best-execution route comparison, quote/prepare, simulation, and
   receipt checks; no set-and-forget custody.
-- **Builder** — protocol, NFT, gacha, DEX, and launchpad scaffolds with unsigned
-  deploy/admin transactions.
+- **Builder** - chain-family fungible-token and NFT-collection launch plans,
+  protocol, gacha, DEX, and launchpad scaffolds with unsigned deploy/admin actions.
+  Unsupported chain adapters fail closed instead of pretending one deploy fits all.
 - **Analyzer** — token, contract, venue, portfolio, market, and risk research with
-  evidence labels.
+  evidence labels. `/balance` or plain `balance` runs one deterministic snapshot
+  across every configured EVM chain plus Solana, Bitcoin, Hyperliquid, and
+  discoverable NFTs. Profile-local observations power history and SVG value graphs;
+  unavailable values stay null instead of becoming fake zeroes.
 - **On-chain scanner** — chain-config scanners for tokens, pools, launches,
   risk, exits, and smart-wallet boards.
 - **Meme-token sniper** — fast launch/liquidity monitoring across configured
@@ -273,7 +277,8 @@ Oracle is a library. Drive it with Claude, GPT, Gemini, Grok, a local model, or
 a plain script — the tools are ordinary functions plus an MCP server:
 
 ```bash
-npx oracle-data-mcp     # works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server (any MCP client); needs oracle-data up
 ```
 
 It is better under [Hermes](https://claude-code.nousresearch.com/docs), because
@@ -294,7 +299,9 @@ Oracle ships an installable 8-lane mesh for Hermes:
 
 ```bash
 oracle-init            # dry run -- shows exactly what it would do
-oracle-init --apply    # create profiles, install SOULs + skills, wire MCP
+oracle-init --apply    # create profiles, install SOULs + skills, wire MCP config
+npx oracle-data        # keep running — MCP tools call the local read plane on :8787
+hermes -p oracle chat  # router lane; inherits whatever model Hermes already uses
 ```
 
 Lanes: `oracle` (router), `polymarket-agent`, `hyperliquid-agent`,

package/SETUP.md

@@ -103,6 +103,39 @@ export BASE_RPC_URL=https://...
 export SOLANA_RPC_URL=https://...
 ```
 
+`/balance` and plain `balance` need only public addresses. Set any families the
+wallet uses, then start `oracle-data` from the same environment:
+
+```bash
+export ORACLE_EVM_ADDRESS=0x...
+export ORACLE_SOLANA_ADDRESS=...
+export ORACLE_BITCOIN_ADDRESS=bc1...
+export ORACLE_HYPERLIQUID_ADDRESS=0x...  # optional, defaults to EVM address
+npx oracle-data
+```
+
+Missing address families are reported as `not-configured`, failed providers as
+`unavailable`, and unsupported chain families as `unsupported`. They are never
+reported as zero. EVM native balances cover every configured EVM chain. Solana
+adds SPL and Token-2022 accounts, Bitcoin adds Runes and inscriptions when an
+address indexer is configured, Hyperliquid adds spot and perp account state, and
+NFT inventory adds OpenSea-supported EVM/Solana collections plus Bitcoin
+inscriptions where owner indexers are available.
+
+Every `portfolio_snapshot` call appends one compact observation to
+`$HERMES_HOME/state/oracle/portfolio-history.jsonl` with mode `0600`. It stores a
+public-address fingerprint, coverage, value breakdown, and warnings, not keys,
+prepared transactions, or raw NFT metadata. Override the internal location only
+when needed:
+
+```bash
+export ORACLE_PORTFOLIO_HISTORY_FILE="$HOME/.local/state/oracle/portfolio-history.jsonl"
+```
+
+`portfolio_history` reads those observations. `portfolio_value_graph` returns an
+SVG chart of known priced value and omits unavailable observations instead of
+plotting them as zero.
+
 ---
 
 ## Where keys are stored
@@ -202,7 +235,8 @@ Gemini, Grok, a local Llama, or your own script at it. The tools are plain
 functions and an MCP server.
 
 ```bash
-npx oracle-data-mcp     # MCP stdio server, works with any MCP client
+npx oracle-data         # local read plane on 127.0.0.1:8787
+npx oracle-data-mcp     # MCP stdio server, works with any MCP client (needs oracle-data up)
 ```
 
 **Why [Hermes](https://claude-code.nousresearch.com/docs) is the better host: per-profile routing.**

package/artifacts/specialist-packs/oracle-full-crypto.json

@@ -1,9 +1,9 @@
 {
   "id": "oracle-full-crypto",
   "name": "Oracle Full Crypto Pack",
-  "version": 1,
+  "version": 4,
   "audience": "public-users",
-  "description": "Default capability set for public Oracle: trader, builder, analyzer, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, NFT/gacha/DEX launches, and protocol build under bound grants. User signs everything.",
+  "description": "Default capability set for public Oracle: trader, builder, analyzer, deterministic /balance aggregation, multichain scanner, meme-token sniping, RFQ routing, tokenized-asset buys, NFT mint gas-war limits, Solana, Bitcoin inscriptions, chain-family token/NFT collections, gacha/DEX launches, and protocol build under bound grants. User signs everything.",
   "posture": {
     "default": "DISARMED",
     "custody": "self-custodial",
@@ -62,6 +62,8 @@
       "oracle-protocol-builder",
       "oracle-contract-research",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "protocol-api-key-integration",
@@ -80,6 +82,8 @@
       "oracle-nft-gacha-launch",
       "oracle-dex-launch",
       "oracle-protocol-security",
+      "oracle-multichain-token-launch",
+      "oracle-multichain-nft-launch",
       "oracle-nft-mint-gas-war"
     ],
     "analysis": [
@@ -88,6 +92,7 @@
       "oracle-smart-wallet-scanner",
       "oracle-meme-token-sniper",
       "oracle-best-execution",
+      "balance",
       "oracle-chain-graphs-telegram-cards",
       "oracle-rfq-tokenized-assets"
     ]
@@ -109,7 +114,9 @@
       "write-deploy-scripts",
       "prepare-unsigned-deploy-txs",
       "security-checklist",
-      "launchpad-public-surface"
+      "launchpad-public-surface",
+      "multichain-token-launch",
+      "multichain-nft-collection-launch"
     ],
     "user_signs": true,
     "grant_actions_example": [
@@ -119,7 +126,7 @@
       "prepare:verify"
     ],
     "targets": "user-provided factory/router/implementations only unless added to destination allowlist",
-    "copy": "Oracle can design and prepare protocol, NFT/gacha, and DEX launches. You still sign. Grants bind chain, spend, and destinations."
+    "copy": "Oracle can classify and prepare chain-family token, NFT collection, protocol, gacha, and DEX launches. Unsupported adapters fail closed. You still sign every side effect."
   },
   "profiles": [
     {
@@ -201,10 +208,12 @@
         "oracle-protocol-security",
         "oracle-nft-gacha-launch",
         "oracle-dex-launch",
-        "oracle-receipts"
+        "oracle-receipts",
+        "oracle-multichain-token-launch",
+        "oracle-multichain-nft-launch"
       ],
       "label": "protocol builder",
-      "description": "Scaffold, review, and prepare deploys for NFT, gacha, DEX, and protocol launches."
+      "description": "Classify by chain family, then scaffold, review, and prepare unsigned token, NFT collection, gacha, DEX, and protocol launches."
     }
   ],
   "default_tools": {
@@ -216,7 +225,14 @@
       "btc_health",
       "btc_fees",
       "btc_inscription_info",
-      "solana_balance"
+      "solana_balance",
+      "portfolio_balance",
+      "portfolio_snapshot",
+      "portfolio_history",
+      "portfolio_value_graph",
+      "nft_inventory",
+      "nft_gallery",
+      "nft_pnl"
     ],
     "prepare": [
       "evm_prepare",
@@ -224,7 +240,8 @@
       "evm_protocol_quote",
       "jupiter_quote",
       "jupiter_prepare",
-      "bitcoin_inscribe_prepare"
+      "bitcoin_inscribe_prepare",
+      "nft_prepare_list"
     ],
     "never_public_default": [
       "evm_sign",
@@ -268,6 +285,11 @@
     "solana-nft-marketplace",
     "solana-nft-mint",
     "hypercore-hype-staking",
-    "hypercore-validator-delegation"
+    "hypercore-validator-delegation",
+    "multichain-token-launch",
+    "multichain-nft-collection-launch",
+    "multichain-balance",
+    "nft-inventory-gallery-pnl",
+    "portfolio-balance-history-graph"
   ]
 }

package/bin/oracle-data-mcp.mjs

@@ -2,14 +2,17 @@
 // Oracle data MCP — read-only multichain market/discovery plane.
 // Loaded by an Oracle/Hermes profile. Never expose signing or broadcast here.
 //
-// Every tool is a READ. No key, no signing, no broadcast. Routes to the Oracle
-// data server read plane (/data/call), which is unauthenticated on loopback.
+// Every tool is a READ or a prepared unsigned action. No key handling, signing,
+// or broadcast. Routes to the Oracle data server read/prepare plane (/data/call),
+// which is unauthenticated on loopback.
 // This is the "scan all public APIs" surface: DeFiLlama protocol TVL, DexScreener
 // token/search, LI.FI + Uniswap quotes, multi-chain RPC balances/blocks.
 //
 // Mirrors the Oracle exec MCP stdio JSON-RPC shape.
 
+import fs from "node:fs";
 import process from "node:process";
+import { fileURLToPath } from "node:url";
 import { env } from "../src/oracle-env.mjs";
 
 const DATA_URL = (env("ORACLE_DATA_URL", "MAD_DESK_URL", "http://127.0.0.1:8787")).replace(/\/$/, "");
@@ -96,6 +99,201 @@ const tools = [
       },
     },
   },
+  {
+    name: "portfolio_balance",
+    description:
+      "Read-only balance aggregation across every configured EVM chain plus Solana, Bitcoin, and Hyperliquid. Reports native assets, supported token/collectible reads, failed or missing providers, unverified assets, timestamps, and known priced value without pretending it is a complete total. Public addresses only; never signs or broadcasts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          description: "Optional public wallet addresses by family. Omit configured families to use ORACLE_*_ADDRESS defaults.",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: {
+          type: "array",
+          items: { type: "number" },
+          description: "Optional EVM chain subset. Default is every configured EVM chain.",
+        },
+        includeTokens: { type: "boolean", description: "Include supported token reads. Default true." },
+        includeCollectibles: { type: "boolean", description: "Include supported collectible reads. Default true." },
+        includePrices: { type: "boolean", description: "Fetch current DeFiLlama native prices. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_snapshot",
+    description:
+      "Query the current multichain balance and NFT inventory, then append one compact profile-local observation for historical tracking. Stores public-address fingerprint, coverage, breakdown, and known priced value only; no keys, signatures, executable payloads, or raw NFT metadata. Returns the live balance, NFT result, and recorded snapshot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        evmChainIds: { type: "array", items: { type: "number" } },
+        includeTokens: { type: "boolean" },
+        includeCollectibles: { type: "boolean" },
+        includePrices: { type: "boolean" },
+        includeNfts: { type: "boolean", description: "Include provider-estimated NFT value. Default true." },
+      },
+    },
+  },
+  {
+    name: "portfolio_history",
+    description:
+      "Read profile-local portfolio observations in a time range. Unknown or unavailable values remain null and are never converted to zero. Defaults to the configured public-address portfolio fingerprint.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean", description: "Return observations for every public-address fingerprint in this profile." },
+        since: { type: "string", description: "Inclusive ISO 8601 lower bound." },
+        until: { type: "string", description: "Inclusive ISO 8601 upper bound." },
+        limit: { type: "number", description: "1-1000, default 100." },
+        order: { type: "string", enum: ["asc", "desc"] },
+      },
+    },
+  },
+  {
+    name: "portfolio_value_graph",
+    description:
+      "Render a static SVG line graph from profile-local portfolio snapshots. Plots known priced value only, labels incomplete coverage, includes provider-estimated NFT values when recorded, and omits unavailable observations instead of plotting fake zeroes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+            hyperliquid: { type: "string" },
+          },
+        },
+        portfolioId: { type: "string" },
+        allPortfolios: { type: "boolean" },
+        since: { type: "string" },
+        until: { type: "string" },
+        limit: { type: "number", description: "Historical observations to consider, max 1000." },
+        maxPoints: { type: "number", description: "Rendered point cap, 2-500, default 200." },
+      },
+    },
+  },
+  {
+    name: "nft_inventory",
+    description:
+      "Read all discoverable NFTs for configured EVM, Solana, and Bitcoin addresses. Returns normalized assets, image URLs, estimated values, per-chain partial failures, flagged/NSFW items separated from visible items, listing coverage, and explicit unsupported chains. Read-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: {
+            evm: { type: "string" },
+            solana: { type: "string" },
+            bitcoin: { type: "string" },
+          },
+        },
+        chains: { type: "array", items: { type: "string" }, description: "Optional chain slug subset." },
+        pageSize: { type: "number", description: "OpenSea items per page, max 200." },
+        maxPages: { type: "number", description: "Maximum pages per chain, max 25." },
+        bitcoinLimit: { type: "number" },
+        includePnl: { type: "boolean", description: "Include OpenSea-indexed account PnL when available. Default true." },
+        costBasis: { type: "object", description: "Optional user-supplied assetKey -> {costUsd,feesUsd,acquiredAt,source}. Missing basis stays unavailable, never zero." },
+      },
+    },
+  },
+  {
+    name: "nft_gallery",
+    description:
+      "Generate one static NFT contact-sheet image page from wallet inventory or supplied normalized items. External metadata is never rendered as HTML; only allowlisted JPEG/PNG/WebP bytes are embedded and unsafe or missing media becomes a placeholder.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        items: { type: "array", items: { type: "object" }, description: "Optional normalized inventory items. Omit to scan configured wallets." },
+        page: { type: "number", description: "1-based gallery page." },
+        pageSize: { type: "number", description: "1-12 items per page." },
+      },
+    },
+  },
+  {
+    name: "nft_pnl",
+    description:
+      "NFT PnL with explicit methodology. Returns OpenSea-indexed account-level PnL where available plus per-item unrealized estimates only when both user-supplied acquisition cost and provider estimated current value exist. Missing history is unavailable, never zero.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        addresses: {
+          type: "object",
+          properties: { evm: { type: "string" }, solana: { type: "string" }, bitcoin: { type: "string" } },
+        },
+        chains: { type: "array", items: { type: "string" } },
+        costBasis: { type: "object" },
+      },
+    },
+  },
+  {
+    name: "nft_prepare_list",
+    description:
+      "Prepare an NFT listing for OpenSea EVM, Magic Eden Solana, or Satflow Bitcoin after explicit user review. Requires userConfirmed=true plus asset, marketplace, price, currency where applicable, and future expiry. Returns approval/signing actions, an unsigned Solana transaction, or an unsigned Bitcoin PSBT. Never signs, submits, or broadcasts.",
+    inputSchema: {
+      type: "object",
+      required: ["marketplace", "userConfirmed"],
+      properties: {
+        marketplace: { type: "string", enum: ["opensea", "magiceden", "magiceden-sol", "satflow"] },
+        userConfirmed: { type: "boolean" },
+        chain: { type: "string" },
+        seller: { type: "string" },
+        contract: { type: "string" },
+        tokenId: { type: "string" },
+        quantity: { type: "number" },
+        priceAmount: { type: "string" },
+        currency: { type: "string" },
+        endTime: { type: "string" },
+        useCreatorFee: { type: "boolean" },
+        taker: { type: "string" },
+        tokenMint: { type: "string" },
+        tokenATA: { type: "string" },
+        auctionHouse: { type: "string" },
+        priceSol: { type: "string" },
+        expiry: { description: "Future ISO 8601 timestamp or Unix seconds." },
+        inscriptionId: { type: "string" },
+        runesOutput: { type: "string" },
+        ordAddress: { type: "string" },
+        receiveAddress: { type: "string" },
+        priceSats: { type: "string" },
+        tapKey: { type: "string" },
+        collectionSlug: { type: "string" },
+      },
+    },
+  },
   {
     name: "rpc_balance",
     description:
@@ -427,6 +625,24 @@ const ROUTES = {
       fromAddress: a.fromAddress || DEFAULT_ADDRESS || undefined,
     },
   }),
+  portfolio_balance: (a) => ({
+    provider: "portfolio",
+    op: "balances",
+    args: {
+      addresses: a.addresses,
+      evmChainIds: a.evmChainIds,
+      includeTokens: a.includeTokens,
+      includeCollectibles: a.includeCollectibles,
+      includePrices: a.includePrices,
+    },
+  }),
+  portfolio_snapshot: (a) => ({ provider: "portfolio", op: "snapshot", args: a }),
+  portfolio_history: (a) => ({ provider: "portfolio", op: "history", args: a }),
+  portfolio_value_graph: (a) => ({ provider: "portfolio", op: "valueGraph", args: a }),
+  nft_inventory: (a) => ({ provider: "nft-portfolio", op: "inventory", args: a }),
+  nft_gallery: (a) => ({ provider: "nft-portfolio", op: "gallery", args: a }),
+  nft_pnl: (a) => ({ provider: "nft-portfolio", op: "pnl", args: a }),
+  nft_prepare_list: (a) => ({ provider: "nft-portfolio", op: "prepareList", args: a }),
   rpc_balance: (a) => {
     const addr = a.address || DEFAULT_ADDRESS;
     if (!addr) throw new Error("address required (set ORACLE_DEFAULT_ADDRESS to supply a default)");
@@ -567,7 +783,21 @@ async function handle(request) {
   if (method === "tools/call") {
     try {
       const result = await callTool(params?.name, params?.arguments || {});
-      send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      if (result?.dataBase64 && /^image\/(?:svg\+xml|png|jpeg|webp)$/.test(String(result.mimeType || ""))) {
+        const { dataBase64, ...metadata } = result;
+        send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            content: [
+              { type: "image", data: dataBase64, mimeType: result.mimeType },
+              { type: "text", text: JSON.stringify(metadata, null, 2) },
+            ],
+          },
+        });
+      } else {
+        send({ jsonrpc: "2.0", id, result: { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } });
+      }
     } catch (err) {
       send({ jsonrpc: "2.0", id, result: { isError: true, content: [{ type: "text", text: err.message }] } });
     }
@@ -596,7 +826,20 @@ function startStdioLoop() {
   });
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+// npm bin wrappers are symlinks. Comparing import.meta.url to argv[1] as strings
+// fails for `npx oracle-data-mcp` / node_modules/.bin/oracle-data-mcp and the
+// process exits without ever starting the stdio loop (Hermes sees Connection closed).
+function isMainModule() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
   startStdioLoop();
 }
 

package/bin/oracle-init.mjs

@@ -176,6 +176,71 @@ function record(kind, detail) {
   log(`${APPLY ? "  ✔" : "  ·"} ${kind}: ${detail}`);
 }
 
+// Write Hermes mcp_servers.oracle-data directly into the profile config.
+// Prefer this over `hermes mcp add`: current Hermes takes --command and --args
+// as separate tokens, prompts interactively for tool enablement, and the old
+// installer form `--command "node <path>"` silently no-ops under execFileSync.
+function yamlScalar(value) {
+  if (
+    value === "" ||
+    /[:#\[\]{},&*!|>'"%@`\s]/.test(value) ||
+    /^(?:null|true|false|\d+)$/i.test(value)
+  ) {
+    return JSON.stringify(value);
+  }
+  return value;
+}
+
+function mcpServerBlock(serverName, scriptPath) {
+  return [
+    `  ${serverName}:`,
+    "    command: node",
+    "    args:",
+    `      - ${yamlScalar(scriptPath)}`,
+    "    enabled: true",
+  ].join("\n");
+}
+
+function wireMcpIntoConfig(configPath, serverName, scriptPath) {
+  const entry = mcpServerBlock(serverName, scriptPath);
+  if (!fs.existsSync(configPath)) {
+    fs.writeFileSync(configPath, `mcp_servers:\n${entry}\n`, "utf8");
+    return "created";
+  }
+
+  let txt = fs.readFileSync(configPath, "utf8");
+  if (
+    txt.includes(scriptPath) &&
+    new RegExp(`^\\s*${serverName}:\\s*$`, "m").test(txt)
+  ) {
+    return "present";
+  }
+
+  // Replace an existing server block of the same name (simple indented map).
+  const serverRe = new RegExp(
+    `^([ \\t]*)${serverName}:\\s*\\n(?:\\1[ \\t]+.*\\n)*`,
+    "m",
+  );
+  if (serverRe.test(txt)) {
+    txt = txt.replace(serverRe, `${entry}\n`);
+    fs.writeFileSync(configPath, txt, "utf8");
+    return "updated";
+  }
+
+  if (/^mcp_servers:\s*$/m.test(txt) || /^mcp_servers:\s*\n/m.test(txt)) {
+    txt = txt.replace(/^(mcp_servers:\s*\n)/m, `$1${entry}\n`);
+  } else if (/^_config_version:.*$/m.test(txt)) {
+    txt = txt.replace(
+      /^(_config_version:.*\n)/m,
+      `$1mcp_servers:\n${entry}\n`,
+    );
+  } else {
+    txt = `mcp_servers:\n${entry}\n${txt}`;
+  }
+  fs.writeFileSync(configPath, txt, "utf8");
+  return "wired";
+}
+
 // ---------------------------------------------------------------- main
 
 const schema = loadSchema();
@@ -363,34 +428,39 @@ for (const def of profiles) {
     }
   }
 
-  // MCP: the read plane. This is the one step that genuinely needs the CLI, since
-  // it edits the profile's own config. Without it, print the command instead.
-  for (const m of def.mcp || []) {
-    const cmd = path.join(ROOT, "bin", "oracle-data-mcp.mjs");
-    if (!hermes) {
-      record("mcp manual", `hermes -p ${def.id} mcp add ${m} --command "node ${cmd}"`);
-      mcpManual.push({ lane: def.id, server: m, command: `hermes -p ${def.id} mcp add ${m} --command "node ${cmd}"` });
-      continue;
-    }
-    record("wire mcp", `${m} (${def.id})`);
-    if (APPLY && m === "oracle-data") {
-      try {
-        execFileSync(
-          "hermes",
-          ["-p", def.id, "mcp", "add", "oracle-data", "--command", `node ${cmd}`],
-          { stdio: "pipe", timeout: 60_000 },
-        );
-      } catch {
-        // Already registered, or this Hermes build wants different flags. Not fatal:
-        // the profile is usable, it just needs the MCP wired by hand.
-        record("mcp note", `could not auto-wire ${m} for ${def.id}; add it manually`);
-        mcpManual.push({ lane: def.id, server: m, command: `hermes -p ${def.id} mcp add ${m} --command "node ${cmd}"` });
+  // MCP: write Hermes config directly. CLI is optional convenience only.
+    for (const m of def.mcp || []) {
+      const scriptPath = path.join(ROOT, "bin", "oracle-data-mcp.mjs");
+      const configPath = path.join(laneDir, "config.yaml");
+      const manual = `hermes -p ${def.id} mcp add ${m} --command node --args ${scriptPath}`;
+
+      if (m !== "oracle-data") {
+        record("mcp manual", manual);
+        mcpManual.push({ lane: def.id, server: m, command: manual });
+        continue;
+      }
+
+      record(
+        "wire mcp",
+        `${m} (${def.id}) -> ${path.relative(os.homedir(), configPath)}`,
+      );
+      if (APPLY) {
+        try {
+          fs.mkdirSync(laneDir, { recursive: true });
+          const how = wireMcpIntoConfig(configPath, m, scriptPath);
+          record(
+            "mcp config",
+            `${how}: ${path.relative(os.homedir(), configPath)}`,
+          );
+        } catch (err) {
+          record("mcp note", `could not write ${configPath}: ${err.message}`);
+          mcpManual.push({ lane: def.id, server: m, command: manual });
+        }
       }
     }
-  }
 
-  record("posture", `DISARMED (${(def.posture.grantActions || []).join(", ")})`);
-}
+    record("posture", `DISARMED (${(def.posture.grantActions || []).join(", ")})`);
+  }
 
 const summary = {
   ok: true,
@@ -414,10 +484,13 @@ if (JSON_OUT) {
     log("pass --force to overwrite (a timestamped .bak is written first).");
   }
   if (mcpManual.length) {
-    log("\nMCP wiring needs the hermes CLI. Run these when it is available:");
+    log("\nMCP wiring needed a manual follow-up:");
     for (const m of mcpManual) log(`  ${m.command}`);
   }
   if (!APPLY) log("re-run with --apply to make changes.");
-  log("\nEvery lane is DISARMED. Set each lane's model in:");
+  log("\nEvery lane is DISARMED. Start the read plane, then chat a lane:");
+  log("  npx oracle-data                 # 127.0.0.1:8787 — MCP tools need this");
+  log("  hermes -p oracle chat");
+  log("\nSet each lane's model in:");
   log(`  ${path.join(hermesRoot(), "profiles", "<lane>", "config.yaml")}`);
 }