@oracle-agent/oracle 0.4.1 → 0.5.0

package/README.md

@@ -1,5 +1,18 @@
 # Oracle
 
+## Quickstart (unified CLI)
+
+```bash
+npm i -g @oracle-agent/oracle
+oracle init --apply        # lanes + read plane only, no keys
+oracle data serve          # loopback read/prepare plane on 127.0.0.1:8787
+oracle doctor              # verify
+# optional, explicit second step — signing stays a separate local package:
+npm i -g @oracle-agent/operator
+oracle sign init
+```
+
+
 **Prepare-only multichain agent control plane.** Policy-bounded intents; your wallet signs.
 
 Specialist agent profiles, real protocol intents, self-custody by default,
@@ -20,13 +33,31 @@ alongside it — same split we run ourselves.
 
 ## Start in 5 steps
 
-Latest: **oracle `0.3.6`** · **operator `0.6.1`**
+Source tree: **oracle `0.5.0`** · **operator `0.14.0`**
+
+Published npm: **oracle `0.4.2`** · **operator `0.13.7`** until this source release is published.
 
 ```bash
-# 1) install both packages
-npm i @oracle-agent/oracle@0.3.6 @oracle-agent/operator@0.6.1
+# 1) install Oracle's public prepare plane
+npm i @oracle-agent/oracle@latest
+```
 
-# 2) put keys ONLY on your machine (example: HL/EVM hex key file)
+```js
+// 2) prepare an artifact (no keys)
+import { data } from "@oracle-agent/oracle";
+const prepared = await data.call("hl-perps", "prepareOrder", { /* coin, side, size... */ });
+```
+
+**Path A — self-custody first:** review the prepared artifact and sign it with
+the owner/main wallet, browser wallet, smart account, hardware wallet, or
+protocol-native wallet. Oracle's public package stops at prepare: your wallet
+authorizes and broadcasts.
+
+```bash
+# 3) optional owner-local operator package for unattended signing on YOUR machine
+npm i @oracle-agent/operator@latest
+
+# 4) put operator keys ONLY on your machine (example: HL/EVM hex key file)
 mkdir -p ~/.config/oracle/keys && chmod 700 ~/.config/oracle/keys
 # write key, then: npx oracle-vault encrypt ~/.config/oracle/keys/evm.key
 export HL_KEY_FILE=~/.config/oracle/keys/evm.key.vault.json
@@ -34,24 +65,29 @@ export ORACLE_VAULT_PASSPHRASE='...'   # signer shell only — never in the agen
 ```
 
 ```js
-// 3) prepare (no keys)
-import { data } from "@oracle-agent/oracle";
-const prepared = await data.call("hl-perps", "prepareOrder", { /* coin, side, size... */ });
-
-// 4) keys local → operator signs (this is the sign step — no MetaMask)
+// Path B — owner-local operator key signs after your app confirms the action
+// (same host, your key, your policy; no model or remote agent custody)
 import { hlSignAndSubmit } from "@oracle-agent/operator";
 await hlSignAndSubmit(prepared, {
   keyFile: process.env.HL_KEY_FILE,
-  userInitiated: true, // app confirmed the action; or use autonomous/daemon below
+  userInitiated: true,
 });
 ```
 
 ```bash
-# 5) unattended desk (no click each trade) — HL/Poly capped
-export ORACLE_AUTONOMOUS_TRADING=1
-# or: npx oracle-signer
+# 5) recommended agent-process path: run the signer daemon so the agent sees
+# only ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN, never the vault passphrase.
+npx oracle-signer
+#
+# Daemon signing requires the SAME HMAC secret in the preparer and the signer,
+# otherwise every sign fails with "ORACLE_STAMP_HMAC_SECRET missing in signer":
+export ORACLE_STAMP_HMAC_SECRET='long-random-secret'
 ```
 
+`ORACLE_AUTONOMOUS_TRADING=1` is only for trusted, owner-controlled direct-exec
+code running locally with your policy and caps. It is not a permission bit for a
+model or remote agent process; use `oracle-signer` for the agent-facing path.
+
 Full vault / multi-chain / daemon detail → operator [SETUP](https://github.com/demi-hl/oracle-operator/blob/main/SETUP.md).
 
 ---
@@ -255,16 +291,33 @@ owner-local source lane.** The short version:
 - Reads and quotes need **no keys**.
 - The public package exposes no signer, key vault, or broadcast path.
 - User wallets authorize prepared actions outside the public data plane.
-- Owner-local signing is shipped separately as `@oracle-agent/operator`; its agent-facing daemon supports only policy-bounded Hyperliquid and Polymarket execution.
+- Owner-local signing is shipped separately as `@oracle-agent/operator`; the
+  recommended agent-process path is `oracle-signer`. Its daemon exposes six
+  policy-bounded surfaces: `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, and
+  `sol`, with explicit caps and fail-closed allowlists.
 
 ### Action vocabulary and execution planes
 
 Oracle keeps capability and authorization separate:
 
 - Public Oracle reads, quotes, simulates, and prepares unsigned artifacts.
-- The generic unattended signer remains limited to `hl` and `poly`.
-- Ordinary EVM preparation remains user-wallet signed.
-- A deployment may separately install a same-host, owner-gated EVM executor. Oracle must verify that executor before describing bounded EVM execution as available. Missing deployment capability means "unavailable here," not "Oracle can never execute EVM."
+- **Path A:** owner/main, browser, smart-account, hardware, or protocol-native
+  wallets sign the prepared artifact. This is the default self-custody path.
+- **Path B:** owner-local operator infrastructure may sign on the same host with
+  your key and your policy. For agent processes, prefer `oracle-signer` so the
+  agent receives only a signer URL/token and never the vault passphrase.
+- The generic unattended signer exposes six bounded surfaces: `hl`, `poly`,
+  `evm-swap`, `evm-bridge`, `btc`, `sol`. Each surface decodes its own
+  envelope, enforces its caps, and refuses while its allowlists are empty.
+- Ordinary EVM preparation remains user-wallet signed unless a trusted
+  owner-controlled direct-exec process is explicitly installed and armed.
+- `ORACLE_AUTONOMOUS_TRADING=1` is direct execution for trusted owner-controlled
+  local code only. It is never model/agent authority and should not be framed as
+  equivalent to the `oracle-signer` agent-process path.
+- A deployment may separately install a same-host, owner-gated EVM executor.
+  Oracle must verify that executor before describing bounded EVM execution as
+  available. Missing deployment capability means "unavailable here," not
+  "Oracle can never execute EVM."
 - `watch`, `watch this`, and `ping me` always create `active: true, actionMode: alert_only`.
 - `arm` creates `active: true, actionMode: execute` only for one exact owner-authorized action. It is never inferred from a watch.
 
@@ -408,8 +461,9 @@ it — verified in practice when Odos sunset their public API mid-development
 ## Examples
 
 ```bash
-node examples/add-a-chain.mjs          # register an unseen chain, no code
-node examples/research-a-token.mjs     # honest token research on live data
+node examples/add-a-chain.mjs             # register an unseen chain, no code
+node examples/research-a-token.mjs        # honest token research on live data
+node examples/oracle-pack-template.mjs    # skeleton for a safe Oracle protocol pack
 ```
 
 ## MCP
@@ -449,7 +503,7 @@ don't imply endorsement by an official deployment when shipping a fork.
 Prefer the local signer daemon so the agent never sees the vault passphrase:
 
 ```bash
-npx oracle-signer   # has ORACLE_VAULT_PASSPHRASE
+npx oracle-signer   # reads the passphrase from the OS credential store
 # agent: ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN only
 ```
 

package/SETUP.md

@@ -1,5 +1,18 @@
 # Setup
 
+## Unified CLI
+
+Prefer the root `oracle` command:
+
+```bash
+npm i -g @oracle-agent/oracle
+oracle init --apply
+oracle doctor
+```
+
+Full reference: [docs/cli.md](./docs/cli.md). Connectors: [docs/connectors.md](./docs/connectors.md).
+
+
 Oracle's public surface runs locally against your API accounts and never accepts
 a wallet private key. Prepared actions are signed in the user's wallet.
 
@@ -45,7 +58,7 @@ The public Oracle profile must report these as separate planes:
 | Plane | Default capability |
 |---|---|
 | Public Oracle package | read, quote, simulate, unsigned prepare |
-| Generic `oracle-signer` daemon | policy-bounded `hl` and `poly` only |
+| Generic `oracle-signer` daemon | six bounded surfaces: `hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol` (each fails closed on empty allowlists) |
 | Ordinary EVM | unsigned preparation, user-wallet signature |
 | Optional owner-gated EVM executor | one exact bounded action after explicit `arm` |
 
@@ -302,7 +315,7 @@ router that knows which brain to use for which job.
 Prefer the local signer daemon so the agent never sees the vault passphrase:
 
 ```bash
-npx oracle-signer   # has ORACLE_VAULT_PASSPHRASE
+npx oracle-signer   # reads the passphrase from the OS credential store
 # agent: ORACLE_SIGNER_URL + ORACLE_SIGNER_TOKEN only
 ```
 

package/bin/oracle-data-mcp.mjs

@@ -552,7 +552,7 @@ const tools = [
       required: ["address", "label"],
       properties: {
         address: { type: "string", description: "0x address" },
-        label: { type: "string", description: "short name, e.g. carlo-agent" },
+        label: { type: "string", description: "short name, e.g. research-agent" },
         who: { type: "string", description: "person or entity the wallet belongs to" },
         role: { type: "string", description: "agent | owner | person | counterparty | venue" },
         chainIds: { type: "array", items: { type: "number" } },

package/bin/oracle.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { run } from "../src/cli/kernel.mjs";
+
+export const COMMANDS = Object.freeze({
+  data: "./desk-server.mjs",
+  public: "./oracle-public-server.mjs",
+  "data-mcp": "./oracle-data-mcp.mjs",
+  init: "./oracle-init.mjs",
+  upgrade: "./oracle-upgrade.mjs",
+  scan: "./oracle-scan.mjs",
+  route: "./oracle-route.mjs",
+});
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  return run(argv);
+}
+
+if (isMainModule()) {
+  const code = await main();
+  process.exit(typeof code === "number" ? code : 0);
+}

package/docs/cli.md

@@ -0,0 +1,19 @@
+# Oracle unified CLI
+
+Root command: `oracle <noun> <verb> [args]`.
+
+The public `@oracle-agent/oracle` package is **prepare-only**. Signing commands
+dispatch to a separately installed `@oracle-agent/operator` process on the same
+machine. Oracle never imports operator signing modules.
+
+See also [connectors.md](./connectors.md).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | ok |
+| 1 | usage / general error |
+| 2 | operator self-reported error |
+| 3 | operator package not installed |
+| 4 | data server not running |

package/docs/connectors.md

@@ -0,0 +1,13 @@
+# Oracle AI-client connectors
+
+ChatGPT is hosted and can NEVER sign or reach your keys. This connector is read/prepare only; anything it prepares is unsigned until you sign it locally.
+
+```bash
+oracle mcp print --target claude-code
+oracle mcp install claude-code
+oracle mcp install codex
+oracle mcp install chatgpt
+oracle mcp install claude-code --with-control   # requires local operator
+```
+
+Oracle does not create tunnels for hosted clients.

package/docs/oracle-pack-standard.md

@@ -0,0 +1,29 @@
+# Oracle protocol pack standard
+
+An Oracle protocol pack is a package-safe ESM module that turns an intent into an unsigned action and decodes independently obtained receipts. A pack is an adapter, not a wallet, signer, broadcaster, or authority. See `examples/oracle-pack-template.mjs` for the smallest complete shape.
+
+## Required surface
+
+Every pack exports a default object with these members (named exports may mirror them):
+
+- `provider`: stable provider identity, semantic version, supported chain IDs, and provenance/trust metadata. Remote token names, symbols, descriptions, image fields, URLs, and NFT metadata remain untrusted data.
+- `prepare(intent)`: validates the intent and returns an unsigned transaction or typed action. It must not accept keys, sign, submit, broadcast, or report execution success.
+- `decode(receipt)`: validates and converts a chain/provider receipt into a documented result. Unknown or malformed receipts fail closed.
+- `riskRules`: an array or function describing enforceable limits and refusal conditions. Human-readable warnings alone are not rules.
+- `tests`: non-empty metadata naming the local test command and covered properties. Tests must be deterministic and require no credentials or network.
+
+## Prompt-injection boundary
+
+Treat every provider response and token/NFT metadata string as inert data. Never concatenate metadata into system/developer instructions, interpret it as tool directions, or let it modify recipients, calldata, limits, and policy. Render or quote it through a data channel and retain its provenance. Packs should test adversarial values such as “ignore previous instructions,” requests for secrets, and demands to sign or invoke tools.
+
+## Custody boundary
+
+Pack exports must not expose signers, wallets, private keys, seed phrases, signing functions, transaction submission, or broadcasting. `prepare` returns data to a separately authorized custody surface. Environment variables and provider credentials must not appear in prepared output, logs, errors, fixtures, or metadata. Imports should be side-effect free; merely loading a pack must not make network calls.
+
+## Receipt gate
+
+Preparation is not execution. A prepared result declares a `receiptGate` and consumers must not mark an action successful until `decode` receives a receipt from an independent, trusted transport and verifies its chain, transaction identity, status, and required confirmations. Timeouts, pending receipts, mismatches, reverts, and undecodable responses are not success.
+
+## Local adversarial benchmark
+
+Run `node scripts/adversarial-bench.mjs <pack.mjs> [...]`. It imports only the named local modules, invokes no pack functions, emits one deterministic JSON summary, and exits `1` when a gate fails (`2` for usage/load errors). It checks required surface fields, forbidden custody exports, missing test metadata, and prompt-injection strings nested in provider or pack metadata. This static public gate complements, rather than replaces, behavioral tests of preparation and receipt verification.

package/docs/profiles.md

@@ -44,7 +44,7 @@ Three practical reasons, learned the hard way:
 | `protocol-builder` | scaffold, review, prepare chain-family token/NFT collections, gacha, DEX, and protocol deploys | prepare:deploy, prepare:mint, simulate |
 | `_template` | your new lane | you decide |
 
-These grants describe the public prepare plane, not every capability an operator may install beside it. The generic unattended signer remains limited to `hl` and `poly`. A separately installed, same-host, owner-gated EVM executor may expose one exact bounded action after explicit `arm`; profiles must verify it before claiming availability. `watch`, `watch this`, and `ping me` remain `alert_only` regardless of executor presence.
+These grants describe the public prepare plane, not every capability an operator may install beside it. The generic unattended signer exposes six bounded surfaces (`hl`, `poly`, `evm-swap`, `evm-bridge`, `btc`, `sol`), each of which decodes its own envelope and refuses while its allowlists are empty. A separately installed, same-host, owner-gated EVM executor may expose one exact bounded action after explicit `arm`; profiles must verify it before claiming availability. `watch`, `watch this`, and `ping me` remain `alert_only` regardless of executor presence.
 
 `protocol-builder` classifies each launch by chain family, then designs and
 prepares unsigned token, NFT collection, protocol, or mint-bot transactions. It

package/examples/oracle-pack-template.mjs

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+
+// Minimal Oracle protocol pack. It prepares unsigned actions; it never receives
+// keys, signs, broadcasts, or claims that untrusted metadata is an instruction.
+
+export const provider = Object.freeze({
+  id: "example-protocol",
+  version: "1.0.0",
+  chains: [8453],
+  metadata: { source: "on-chain", trust: "untrusted-data" },
+});
+
+export function prepare(intent) {
+  assert.ok(intent && provider.chains.includes(intent.chainId), "unsupported chain");
+  return {
+    kind: "unsigned-transaction",
+    chainId: intent.chainId,
+    transaction: { to: intent.to, data: intent.data ?? "0x", value: intent.value ?? "0" },
+    receiptGate: { required: true, confirmations: 1, match: ["chainId", "transaction.to"] },
+  };
+}
+
+export function decode(receipt) {
+  assert.ok(receipt && typeof receipt.status !== "undefined", "receipt required");
+  return { success: receipt.status === 1 || receipt.status === "0x1", transactionHash: receipt.transactionHash };
+}
+
+export const riskRules = Object.freeze([
+  { id: "explicit-recipient", field: "transaction.to", required: true },
+  { id: "receipt-before-success", field: "receiptGate.required", equals: true },
+]);
+
+export const tests = Object.freeze({
+  command: "node --test test/oracle-pack-standard.test.mjs",
+  covers: ["prepare-is-unsigned", "decode-requires-receipt", "metadata-is-untrusted"],
+});
+
+export default Object.freeze({ provider, prepare, decode, riskRules, tests });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Oracle: prepare-only multichain agent control plane. Policy-bounded intents for a user-signed wallet. Self-custody by default — the public package never takes your key. Built for Hermes; no model key required.",
   "license": "Apache-2.0",
   "type": "module",
@@ -26,13 +26,15 @@
     "node": ">=20.19.0"
   },
   "bin": {
+    "oracle": "./bin/oracle.mjs",
     "oracle-data": "./bin/desk-server.mjs",
     "oracle-public": "./bin/oracle-public-server.mjs",
     "oracle-data-mcp": "./bin/oracle-data-mcp.mjs",
     "oracle-init": "./bin/oracle-init.mjs",
     "oracle-upgrade": "./bin/oracle-upgrade.mjs",
     "oracle-scan": "./bin/oracle-scan.mjs",
-    "oracle-route": "./bin/oracle-route.mjs"
+    "oracle-route": "./bin/oracle-route.mjs",
+    "oracle": "./bin/oracle.mjs"
   },
   "exports": {
     ".": "./src/index.mjs",
@@ -44,7 +46,12 @@
     "./action-semantics": "./src/action-semantics.mjs",
     "./address-book": "./src/address-book.mjs",
     "./nft-gas-war": "./src/nft-gas-war-guard.mjs",
-    "./prepare-envelope": "./src/prepare-envelope.mjs"
+    "./prepare-envelope": "./src/prepare-envelope.mjs",
+    "./connect": "./src/onboarding/harness-configs.mjs",
+    "./receipts": "./src/action-receipts.mjs",
+    "./risk": "./src/portfolio-risk.mjs",
+    "./watch": "./src/watch-preferences.mjs",
+    "./signals": "./src/signals/index.mjs"
   },
   "scripts": {
     "test": "ORACLE_TEST_ISOLATE_SECRETS=1 ORACLE_ROUTE_ATTESTATION_SECRET=oracle-unit-test-secret node --test test/*.test.mjs",
@@ -64,7 +71,9 @@
     "test:count": "node scripts/check-test-count.mjs",
     "test:count:update": "node scripts/check-test-count.mjs --update",
     "test:protocol-templates": "RUN_PROTOCOL_TEMPLATE_TESTS=1 node --test test/protocol-templates.test.mjs",
-    "protocol:gate": "node scripts/protocol-template-gate.mjs"
+    "protocol:gate": "node scripts/protocol-template-gate.mjs",
+    "gate:docs": "node scripts/check-doc-drift.mjs",
+    "gate:release": "npm run gate:docs && node --test test/flag-polarity.test.mjs"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3",

package/profiles/oracle/SOUL.md

@@ -41,7 +41,9 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
 1. **The public router never signs.** It prepares, simulates, and explains; ordinary
    EVM artifacts require the user's wallet signature. Do not turn that public-plane
    boundary into the false claim that EVM execution is universally impossible. The
-   generic unattended signer remains limited to `hl` and `poly`; a deployment may
+   generic unattended signer exposes six bounded surfaces (`hl`, `poly`, `evm-swap`,
+   `evm-bridge`, `btc`, `sol`), each of which decodes its own envelope and refuses
+   while its allowlists are empty; a deployment may also
    separately expose a same-host, owner-gated EVM executor. Verify that executor
    before describing it as available.
    `watch`, `watch this`, and `ping me` always mean `actionMode: alert_only`.

package/profiles/robinhood-agent/SOUL.md

@@ -35,9 +35,11 @@ that moves value.
 2. **Never size against stale or virtual reserves.**
 3. **A fuzzy ticker match is not confirmation** — surface the CA.
 4. **The public lane does not sign.** Ordinary swaps are prepared for the user's
-   wallet. The generic unattended signer remains `hl`/`poly`; a separately installed,
-   owner-gated EVM executor may handle one exact bounded Robinhood Chain action after
-   explicit `arm`. Verify that executor before claiming it is available.
+   wallet. The generic unattended signer exposes six bounded surfaces (`hl`, `poly`,
+   `evm-swap`, `evm-bridge`, `btc`, `sol`), each fail-closed on its own policy. A
+   separately installed, owner-gated EVM executor may handle one exact bounded
+   Robinhood Chain action after explicit `arm`. Verify that executor before claiming
+   it is available.
 5. **Watch is alert-only.** `watch`, `watch this`, and `ping me` persist as
    `active: true, actionMode: alert_only`. Only explicit `arm` can produce
    `actionMode: execute`; never infer execution from a watch or legacy `status: armed`.

package/public/agent-connect/app.js

@@ -0,0 +1,84 @@
+(() => {
+  "use strict";
+
+  const PACKAGE = "@oracle-agent/oracle";
+  const COMMAND = "npx";
+  const ARGS = ["-y", "--package", PACKAGE, "oracle-data-mcp"];
+  const INIT_COMMAND = "npx -y --package @oracle-agent/oracle oracle-init";
+
+  const apiUrl = document.querySelector("#api-url");
+  const apiKey = document.querySelector("#api-key");
+  const walletAddress = document.querySelector("#wallet-address");
+  const output = document.querySelector("#config-output");
+  const label = document.querySelector("#config-label");
+  const status = document.querySelector("#copy-status");
+  const tabs = [...document.querySelectorAll("[data-harness]")];
+  let selected = "hermes";
+
+  const cleanUrl = () => apiUrl.value.trim().replace(/\/+$/, "");
+  const env = () => {
+    const values = {
+      ORACLE_DATA_URL: cleanUrl() || "https://api.oracle-agent.dev",
+      ORACLE_AGENT_KEY: apiKey.value.trim() || "YOUR_AGENT_KEY"
+    };
+    if (walletAddress.value.trim()) values.ORACLE_WALLET_ADDRESS = walletAddress.value.trim();
+    return values;
+  };
+
+  const server = () => ({ command: COMMAND, args: [...ARGS], env: env() });
+
+  const configs = {
+    hermes: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    claude: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    codex: () => {
+      const values = env();
+      const lines = [
+        "[mcp_servers.oracle]",
+        `command = ${JSON.stringify(COMMAND)}`,
+        `args = [${ARGS.map((arg) => JSON.stringify(arg)).join(", ")}]`,
+        "",
+        "[mcp_servers.oracle.env]",
+        ...Object.entries(values).map(([key, value]) => `${key} = ${JSON.stringify(value)}`)
+      ];
+      return lines.join("\n");
+    },
+    cursor: () => ({
+      mcpServers: { oracle: server() }
+    }),
+    mcp: () => ({
+      mcpServers: { oracle: server() }
+    })
+  };
+
+  const names = { hermes: "Hermes", claude: "Claude Code", codex: "Codex", cursor: "Cursor", mcp: "Generic MCP" };
+
+  function render() {
+    const config = configs[selected]();
+    output.textContent = typeof config === "string" ? config : JSON.stringify(config, null, 2);
+    label.textContent = `${names[selected]} config`;
+    status.textContent = "";
+  }
+
+  async function copy(text, message) {
+    try {
+      await navigator.clipboard.writeText(text);
+      status.textContent = message;
+    } catch {
+      status.textContent = "Copy was blocked. Select the text and copy it manually.";
+    }
+  }
+
+  tabs.forEach((tab) => tab.addEventListener("click", () => {
+    selected = tab.dataset.harness;
+    tabs.forEach((item) => item.setAttribute("aria-selected", String(item === tab)));
+    render();
+  }));
+  [apiUrl, apiKey, walletAddress].forEach((input) => input.addEventListener("input", render));
+  document.querySelector("#copy-button").addEventListener("click", () => copy(output.textContent, `${names[selected]} config copied.`));
+  document.querySelector("#copy-install").addEventListener("click", () => copy(INIT_COMMAND, "Local operator install command copied."));
+  render();
+})();

package/public/agent-connect/index.html

@@ -0,0 +1,83 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="description" content="Connect your agent harness to Oracle read tools without giving up custody." />
+  <title>Oracle Agent Connect</title>
+  <link rel="stylesheet" href="styles.css" />
+</head>
+<body>
+  <main class="shell">
+    <header class="hero">
+      <a class="wordmark" href="/">ORACLE</a>
+      <p class="eyebrow">AGENT CONNECT</p>
+      <h1>Give your agent market context.<br /><span>Keep custody local.</span></h1>
+      <p class="lede">Connect a read-only Oracle API to your preferred harness. The model proposes actions; you review and authorize them through your local operator.</p>
+    </header>
+
+    <section class="card setup" aria-labelledby="connection-title">
+      <div class="section-heading">
+        <span class="step">01</span>
+        <div>
+          <h2 id="connection-title">Your connection</h2>
+          <p>These values stay in this browser and are only used to build the config below.</p>
+        </div>
+      </div>
+      <div class="fields">
+        <label>Agent API URL
+          <input id="api-url" type="url" value="https://api.oracle-agent.dev" spellcheck="false" autocomplete="url" />
+        </label>
+        <label>Read API key
+          <input id="api-key" type="password" placeholder="Your read-only API key" spellcheck="false" autocomplete="off" />
+          <span class="hint">Use only a user-owned, read-only API credential.</span>
+        </label>
+        <label>Public wallet address <span class="optional">optional</span>
+          <input id="wallet-address" type="text" placeholder="0x... or a public Solana address" spellcheck="false" autocomplete="off" />
+          <span class="hint">Used to personalize portfolio reads. No wallet connection or signature.</span>
+        </label>
+      </div>
+    </section>
+
+    <section class="card config" aria-labelledby="config-title">
+      <div class="section-heading">
+        <span class="step">02</span>
+        <div>
+          <h2 id="config-title">Choose your harness</h2>
+          <p>Copy a ready-to-paste cloud/read MCP configuration.</p>
+        </div>
+      </div>
+      <div class="tabs" role="tablist" aria-label="Agent harness">
+        <button role="tab" aria-selected="true" data-harness="hermes">Hermes</button>
+        <button role="tab" aria-selected="false" data-harness="claude">Claude Code</button>
+        <button role="tab" aria-selected="false" data-harness="codex">Codex</button>
+        <button role="tab" aria-selected="false" data-harness="cursor">Cursor</button>
+        <button role="tab" aria-selected="false" data-harness="mcp">Generic MCP</button>
+      </div>
+      <div class="code-wrap">
+        <div class="code-bar">
+          <span id="config-label">Hermes config</span>
+          <button id="copy-button" class="copy" type="button">Copy config</button>
+        </div>
+        <pre><code id="config-output"></code></pre>
+      </div>
+      <p id="copy-status" class="status" aria-live="polite"></p>
+    </section>
+
+    <section class="operator" aria-labelledby="operator-title">
+      <div class="operator-mark" aria-hidden="true">LOCAL</div>
+      <div>
+        <p class="eyebrow">SEPARATE EXECUTION LANE</p>
+        <h2 id="operator-title">Install the local operator to execute</h2>
+        <p>The cloud/read MCP can research, quote, simulate, and prepare. Execution belongs in a separate local process under your policy and approval controls.</p>
+        <div class="command"><code>npx @oracle-agent/oracle init</code><button id="copy-install" type="button">Copy</button></div>
+      </div>
+    </section>
+
+    <footer>
+      <p><strong>Custody stays local.</strong> The model proposes; the owner authorizes. This page never connects a wallet, requests a signature, or sends the values you enter.</p>
+    </footer>
+  </main>
+  <script src="app.js"></script>
+</body>
+</html>