@oracle-agent/oracle 0.11.0 → 0.12.0

package/docs/public-surface.md

@@ -1,133 +0,0 @@
-# Public surface
-
-Every supported import subpath, executable, and runtime environment variable in
-`@oracle-agent/oracle`. If something is in `exports`/`bin` it is a public
-contract and belongs here; if it is not meant to be public it should be removed
-from the manifest rather than left undocumented.
-
-Generated counts are asserted by `test/public-surface-doc.test.mjs`, so this
-file cannot silently drift from `package.json`.
-
-## Import subpaths
-
-| Subpath | What it gives you |
-|---|---|
-| `@oracle-agent/oracle` | package root — re-exports the common surface |
-| `@oracle-agent/oracle/data` | provider catalog + `dataCall` read plane |
-| `@oracle-agent/oracle/policy` | transaction policy: caps, allowlists, `enforceTxPolicy` |
-| `@oracle-agent/oracle/chains` | chain registry and per-chain metadata |
-| `@oracle-agent/oracle/scanner` | token/contract scanner capabilities |
-| `@oracle-agent/oracle/router` | route sources and quote routing |
-| `@oracle-agent/oracle/action-semantics` | decoded-action semantics for review |
-| `@oracle-agent/oracle/address-book` | label store — refuses key material |
-| `@oracle-agent/oracle/nft-gas-war` | NFT mint/gas-war helpers |
-| `@oracle-agent/oracle/prepare-envelope` | `stampPrepared` / `assertPreparedEnvelope` |
-| `@oracle-agent/oracle/connect` | wallet-connect request/assemble surface |
-| `@oracle-agent/oracle/receipts` | action receipts — refuses secret-bearing fields |
-| `@oracle-agent/oracle/risk` | risk scoring helpers |
-| `@oracle-agent/oracle/watch` | watch/alert subscriptions |
-| `@oracle-agent/oracle/signals` | signal feed helpers |
-
-`./package.json` is deliberately **not** exported. Do not derive internal paths
-with `require.resolve('@oracle-agent/oracle/package.json')` — it throws
-`ERR_PACKAGE_PATH_NOT_EXPORTED`. Invoke the shipped bins by name instead.
-
-## Executables
-
-| Bin | Purpose |
-|---|---|
-| `oracle` | main CLI |
-| `oracle-data` | local read-plane server (`oracle data serve`) |
-| `oracle-public` | public-plane server (`oracle public serve`) |
-| `oracle-data-mcp` | MCP stdio server for agent lanes |
-| `oracle-init` | write config + attestation secret (`oracle init --apply`) |
-| `oracle-upgrade` | in-place upgrade helper (`oracle upgrade`) |
-| `oracle-scan` | scanner entrypoint |
-| `oracle-route` | route/quote entrypoint |
-
-## Environment variables
-
-### Arming flags — default OFF, enable only on literal `1`
-
-These are the gates that decide whether anything can ever be signed or
-broadcast. `envFlag` is strict: `true`, `yes`, `on`, or any other value leaves
-them OFF. Setting them is not sufficient to move funds — the signer's own
-policy and custody wall still apply.
-
-| Name | Default | Meaning |
-|---|---|---|
-| `ORACLE_EXECUTE_ENABLED` | off | allow the signing surface to arm at all |
-| `ORACLE_DEPLOY_ENABLED` | off | allow contract deployment paths to arm |
-| `ORACLE_ONBOARD_HTTP` | off | expose onboarding routes over HTTP |
-| `ORACLE_PUBLIC_API_MODE` | off | run the server in public-plane mode |
-| `ORACLE_ALLOW_CREATE` | off | allow create/deploy-shaped actions |
-| `ORACLE_ALLOW_EPHEMERAL_CAPS` | off | allow ephemeral cap grants |
-
-### Guard rails — default ON, honor disable words
-
-| Name | Default | Meaning |
-|---|---|---|
-| `ORACLE_VALUE_CAPS_ENABLED` | on | per-transaction value caps. Uses strict `!== "0"` so a stray `false` leaves the cap wall standing |
-
-### Integrity and attestation
-
-| Name | Meaning |
-|---|---|
-| `ORACLE_ROUTE_ATTESTATION_SECRET` | keyed route attestation HMAC. Written by `oracle init --apply` |
-| `MAD_ROUTE_ATTESTATION_SECRET` | legacy alias for the above |
-| `ORACLE_ATTESTATION_SECRET` | alternate attestation secret name |
-| `ORACLE_STAMP_HMAC_SECRET` | keyed MAC over prepared envelopes. A verifier holding this secret **requires** a valid MAC — an envelope with the MAC stripped is refused, so the keyed mode cannot be silently downgraded to the unkeyed checksum |
-| `ORACLE_STAMP_REQUIRE_MAC` | set `1` to require a MAC even when the verifier has no secret configured. With a secret set this is already implied |
-| `ORACLE_PREPARE_HARD_MAX_AGE_MS` | hard ceiling on prepared-envelope age |
-
-### Servers and endpoints
-
-| Name | Default | Meaning |
-|---|---|---|
-| `ORACLE_DATA_HOST` | `127.0.0.1` | read-plane bind host (loopback enforced) |
-| `ORACLE_DATA_PORT` | `8787` | read-plane port |
-| `ORACLE_DATA_URL` | `http://127.0.0.1:8787` | where the CLI looks for the data server |
-| `ORACLE_PUBLIC_HOST` | `127.0.0.1` | public-plane bind host (loopback enforced) |
-| `ORACLE_PUBLIC_PORT` | — | public-plane port |
-
-The data server serves `/health`; `/` intentionally returns 404 with a route
-list.
-
-### Paths and config
-
-| Name | Meaning |
-|---|---|
-| `ORACLE_CONFIG_DIR` | config directory (default `~/.config/oracle`) |
-| `ORACLE_EXEC_ENV_FILE` | path to `exec.env` |
-| `ORACLE_AGENT_KEYS_PATH` | agent key store path |
-| `ORACLE_AUTH_FILE_STORE` | auth file store path |
-| `ORACLE_ADDRESS_BOOK` | address-book path |
-| `ORACLE_OPERATOR_BIN_DIR` | operator binary directory |
-| `ORACLE_AUDIT_STREAM` | audit stream destination |
-
-### Routing and defaults
-
-| Name | Meaning |
-|---|---|
-| `ORACLE_ALLOWED_CHAINS` | restrict routing to a chain allowlist |
-| `ORACLE_DEFAULT_ADDRESS` | default address for reads |
-| `ORACLE_PROFILE` | active profile name |
-| `ORACLE_PRIVY_APP_ID` | Privy app id for connect flows |
-
-### Runtime integration
-
-| Name | Meaning |
-|---|---|
-| `ORACLE_HERMES_BIN` | path to the agent runtime binary |
-| `ORACLE_CLAUDE_CODE_VERSION` | pinned agent runtime version |
-| `ORACLE_PYTHON` / `ORACLE_UV_BIN` | interpreter overrides |
-| `ORACLE_NATIVE_TUI` / `ORACLE_FORCE_CHAT` / `ORACLE_PLAIN_HARNESS` | CLI presentation modes |
-| `ORACLE_NO_BOOTSTRAP` | skip bootstrap on start |
-| `ORACLE_CLI_DEBUG` | verbose CLI diagnostics |
-
-### Test-only
-
-| Name | Meaning |
-|---|---|
-| `ORACLE_TEST_ISOLATE_SECRETS` | isolate secrets during tests |
-| `ORACLE_FAKE_HOME` | redirect `$HOME` during tests |

package/examples/add-a-chain.mjs

@@ -1,65 +0,0 @@
-// Example: register a chain Oracle has never seen, then use it.
-//
-// Run:  node examples/add-a-chain.mjs
-//
-// The point of this example is that there is no adapter to write. A chain is a
-// config object; the generic EVM scanner supplies the capabilities.
-
-import { registerCustomChain } from "../src/scanner/chains.config.mjs";
-import { scannerCoverage } from "../src/scanner/contract.mjs";
-
-// 1. Describe the chain. Note rpcEnv holds VARIABLE NAMES, not URLs -- endpoints
-//    stay in the environment so nothing sensitive lands in source control.
-const scanner = registerCustomChain({
-  key: "examplechain",
-  chainId: 424242,
-  name: "Example Chain",
-  rpcEnv: ["EXAMPLECHAIN_RPC_URL"],
-  nativeCurrency: { symbol: "EXC", decimals: 18 },
-  explorer: "https://explorer.example",
-
-  // Omitted deliberately: dexscreenerSlug. Without it, pool discovery reports
-  // UNAVAILABLE rather than guessing -- a wrong slug would return another chain's
-  // pools, which is worse than no answer.
-
-  // Omitted deliberately: venues. With none, the chain is read/research capable and
-  // fail-closed for routing value. Adding one requires recorded provenance; see
-  // docs/adding-a-chain.md.
-});
-
-console.log(`registered: ${scanner.name} (chain ${scanner.chainId})`);
-
-// 2. Ask what it can actually do. The answer is honest -- unimplemented
-//    capabilities are listed as unsupported, not silently absent.
-const caps = scanner.capabilities();
-console.log(`\nsupported   (${caps.supported.length}): ${caps.supported.join(", ")}`);
-console.log(`unsupported (${caps.unsupported.length}): ${caps.unsupported.join(", ")}`);
-
-// 3. An unimplemented capability throws with an actionable message. It never
-//    returns undefined, which a caller could mistake for "no result".
-try {
-  await scanner.quote({ from: "0x", to: "0x", amount: "1" });
-} catch (err) {
-  console.log(`\nquote() correctly refused:\n  ${err.message.split("\n")[0]}`);
-}
-
-// 4. Pool discovery is UNAVAILABLE, and says why.
-const pools = await scanner.resolvePools("0x1111111111111111111111111111111111111111");
-console.log(`\nresolvePools evidence: ${pools.evidence}`);
-console.log(`  reason: ${pools.reason}`);
-
-// 5. Live reads need an RPC. Show the exact variable to set rather than failing
-//    with a generic network error.
-console.log(`\nto make live reads, set one of: ${scanner.rpcEnv.join(", ")}`);
-try {
-  const head = await scanner.blockNumber();
-  console.log(`  head: ${head.blockNumber} (${head.evidence})`);
-} catch {
-  console.log("  (no RPC configured -- expected for this example chain)");
-}
-
-// 6. The coverage matrix now includes it alongside the built-ins.
-const cov = scannerCoverage();
-console.log(`\ncoverage: ${cov.chainCount} chain(s) registered`);
-const mine = cov.chains[424242];
-console.log(`  examplechain failClosed for routing: ${mine.failClosed}`);

package/examples/oracle-pack-template.mjs

@@ -1,38 +0,0 @@
-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/examples/research-a-token.mjs

@@ -1,70 +0,0 @@
-// Example: research a token end to end, honestly.
-//
-// Run:  node examples/research-a-token.mjs
-//       node examples/research-a-token.mjs base 0x<address>
-//
-// Demonstrates the discipline the desk is built around: read the identity off the
-// chain, find pools with real liquidity, and report UNKNOWN where a check could not
-// run rather than letting silence read as approval.
-
-import { registerBuiltinScanners } from "../src/scanner/chains.config.mjs";
-import { getScanner, listScanners, EVIDENCE, RISK } from "../src/scanner/contract.mjs";
-
-registerBuiltinScanners();
-
-const chainRef = process.argv[2] || "base";
-// Base USDC by default -- a token whose answers are easy to sanity-check.
-const token = process.argv[3] || "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
-
-const scanner =
-  listScanners().find((s) => s.key === chainRef) || getScanner(Number(chainRef));
-if (!scanner) {
-  console.error(`unknown chain "${chainRef}"`);
-  process.exit(1);
-}
-
-console.log(`chain: ${scanner.name} (${scanner.chainId})`);
-console.log(`token: ${token}\n`);
-
-// 1. Identity from the CONTRACT, not a token list. A list can be stale or omit a
-//    two-hour-old launch, and the on-chain answer is what governs a transfer.
-const meta = await scanner.resolveToken(token);
-if (meta.evidence !== EVIDENCE.LIVE) {
-  console.log(`identity: ${meta.evidence} -- ${meta.warning ?? meta.error}`);
-  console.log("stopping: without ERC-20 metadata there is nothing to price.");
-  process.exit(0);
-}
-console.log(`identity: ${meta.symbol} (${meta.name}), ${meta.decimals} decimals`);
-
-// 2. Pools, ranked by liquidity. Depth is what determines your fill; the headline
-//    price is a fiction for anything but the smallest clip.
-const pools = await scanner.resolvePools(token);
-console.log(`\npools: ${pools.evidence}`);
-if (pools.reason) console.log(`  ${pools.reason}`);
-for (const p of pools.pools.slice(0, 5)) {
-  const liq = p.liquidityUsd == null ? "unknown" : `$${Math.round(p.liquidityUsd).toLocaleString()}`;
-  console.log(`  ${p.dex.padEnd(14)} ${liq.padStart(14)}  ${p.pair}`);
-}
-
-// 3. Structural risk. Read the verdict AND the individual checks -- an overall
-//    UNKNOWN often hides several passes plus one unprovable item, and which item is
-//    unprovable is the decision-relevant part.
-const risk = await scanner.scoreRisk(token);
-console.log(`\nrisk verdict: ${risk.verdict}`);
-for (const c of risk.checks) {
-  console.log(`  ${c.result.padEnd(8)} ${c.check.padEnd(16)} ${c.detail ?? ""}`);
-}
-
-// 4. The honest close. UNKNOWN is not PASS, and a buy path is not an exit path.
-console.log("");
-if (risk.verdict === RISK.FAIL) {
-  console.log("FAIL: disqualifying finding above. Do not trade.");
-} else if (risk.verdict === RISK.UNKNOWN) {
-  console.log(
-    "UNKNOWN is not PASS. Structural checks looked fine, but sellability is\n" +
-      "unproven without a verified router on this chain. Until a round-trip sell\n" +
-      "simulation succeeds, treat this token as not exitable.",
-  );
-} else {
-  console.log(`${risk.verdict}: structural checks only -- still not a recommendation.`);
-}

package/plugins/oracle-owner-gate/__init__.py

@@ -1,227 +0,0 @@
-"""Hermes owner and raw-message intent gate for Oracle execution tools.
-
-This is a routing guard, not a signer.  Local Operator policy remains the
-final authority for every signature and broadcast.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import re
-from collections import OrderedDict
-from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
-
-_MAX_SESSIONS = 256
-_TURNS: "OrderedDict[str, Dict[str, Any]]" = OrderedDict()
-
-_PROTECTED = {
-    "oracle_watch_create": "alert_only",
-    "oracle_control_arm": "execute",
-    "oracle_control_confirm": "execute",
-    "oracle_action_cancel": "cancel",
-    "oracle_action_list": "owner_read",
-    "oracle_action_status": "owner_read",
-    "oracle_operator_sign": "sign",
-    "oracle_operator_send": "send",
-    "oracle_operator_execute": "send",
-    "exec_arm": "execute",
-    "exec_disarm": "cancel",
-    "evm_sign": "sign",
-    "evm_send": "send",
-    # The address book is durable state a later send can be routed against, so
-    # writes are owner-only. Reads stay open to the owner's own sessions.
-    "address_book_remember": "owner_write",
-    "address_book_forget": "owner_write",
-    "address_book_list": "owner_read",
-    "address_book_lookup": "owner_read",
-}
-
-_LEADING_INTENT = re.compile(
-    r"^\s*(watch|ping|arm\s+confirm|arm|cancel|disarm|sign|send|execute)(?=$|[\s:,.!?;\-])",
-    re.IGNORECASE,
-)
-
-
-def _config_path() -> Path:
-    override = os.environ.get("ORACLE_CONFIG_DIR")
-    root = Path(override).expanduser() if override else Path.home() / ".config" / "oracle"
-    return root / "owner.json"
-
-
-def _read_config() -> Optional[Dict[str, Any]]:
-    path = _config_path()
-    try:
-        if path.stat().st_mode & 0o077:
-            return None
-        value = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, ValueError, TypeError):
-        return None
-    return value if isinstance(value, dict) else None
-
-
-def _strings(value: Any) -> set[str]:
-    if isinstance(value, str):
-        return {value.strip()} if value.strip() else set()
-    if isinstance(value, (list, tuple, set)):
-        return {str(item).strip() for item in value if str(item).strip()}
-    return set()
-
-
-def _owner_ids(config: Dict[str, Any], platform: str) -> set[str]:
-    """Accept the public flat form plus convenient per-platform mappings."""
-    result = set()
-    canonical = config.get("owner")
-    if isinstance(canonical, str) and ":" in canonical:
-        owner_platform, owner_id = canonical.split(":", 1)
-        if owner_platform.strip().lower() == platform and owner_id.strip():
-            result.add(owner_id.strip())
-    for key in ("owner_ids", "ownerIds", "owners"):
-        value = config.get(key)
-        if isinstance(value, dict):
-            result |= _strings(value.get(platform))
-            result |= _strings(value.get("*"))
-        else:
-            result |= _strings(value)
-    platforms = config.get("platforms")
-    if isinstance(platforms, dict):
-        entry = platforms.get(platform)
-        if isinstance(entry, dict):
-            result |= _strings(entry.get("owner_ids"))
-            result |= _strings(entry.get("owners"))
-        else:
-            result |= _strings(entry)
-    return result
-
-
-def _local_cli_allowed(config: Dict[str, Any]) -> bool:
-    value = config.get("local_cli", config.get("localCli", config.get("allow_local_cli", False)))
-    if isinstance(value, dict):
-        value = value.get("allow", value.get("owner", value.get("enabled", False)))
-    return value is True or (isinstance(value, str) and value.lower() in {"allow", "owner", "enabled", "true"})
-
-
-def _intent(raw_message: Any) -> str:
-    if not isinstance(raw_message, str):
-        return "none"
-    match = _LEADING_INTENT.match(raw_message)
-    if not match:
-        return "none"
-    command = " ".join(match.group(1).lower().split())
-    if command in {"watch", "ping"}:
-        return "alert_only"
-    if command in {"arm", "arm confirm"}:
-        return "execute"
-    if command in {"cancel", "disarm"}:
-        return "cancel"
-    if command == "sign":
-        return "sign"
-    return "send"
-
-
-def _tool_class(tool_name: Any) -> Optional[str]:
-    # MCP adapters use several separators.  Collapsing all non-alphanumerics
-    # lets us compare the authoritative suffix without trusting the prefix.
-    normalized = re.sub(r"[^a-z0-9]+", "_", str(tool_name or "").lower()).strip("_")
-    for suffix, tool_class in _PROTECTED.items():
-        if normalized == suffix or normalized.endswith("_" + suffix):
-            return tool_class
-    return None
-
-
-def _identity(config: Optional[Dict[str, Any]], platform: str, sender_id: str) -> Tuple[bool, str]:
-    if config is None:
-        return False, "owner configuration is unavailable"
-    platform = platform.strip().lower()
-    sender_id = sender_id.strip()
-    if platform in {"cli", "local", "terminal"}:
-        if _local_cli_allowed(config):
-            return True, ""
-        return False, "local CLI is not authorized by owner policy"
-    if not sender_id:
-        return False, "gateway sender identity is missing"
-    if sender_id not in _owner_ids(config, platform):
-        return False, "sender is not an owner"
-    return True, ""
-
-
-def _block(reason: str) -> Dict[str, str]:
-    return {"action": "block", "message": "Oracle owner gate: " + reason + "."}
-
-
-def _on_pre_llm_call(
-    session_id: str = "",
-    sender_id: str = "",
-    platform: str = "",
-    user_message: Any = "",
-    parent_session_id: str = "",
-    **_: Any,
-) -> None:
-    """Snapshot only Hermes-trusted turn metadata and the original user input."""
-    session_id = str(session_id or "").strip()
-    if not session_id:
-        return None
-    _TURNS[session_id] = {
-        "session_id": session_id,
-        "parent_session_id": str(parent_session_id or "").strip(),
-        "sender_id": str(sender_id or "").strip(),
-        "platform": str(platform or "").strip().lower(),
-        "raw_message": user_message if isinstance(user_message, str) else "",
-        "intent": _intent(user_message),
-    }
-    _TURNS.move_to_end(session_id)
-    while len(_TURNS) > _MAX_SESSIONS:
-        _TURNS.popitem(last=False)
-    return None
-
-
-def _on_pre_tool_call(tool_name: str = "", session_id: str = "", **_: Any) -> Optional[Dict[str, str]]:
-    required = _tool_class(tool_name)
-    if required is None:
-        return None
-    session_id = str(session_id or "").strip()
-    turn = _TURNS.get(session_id)
-    if turn is None:
-        return _block("no trusted current-turn owner message exists for this session")
-    if turn["parent_session_id"]:
-        return _block("delegated and background sessions cannot execute or sign")
-    allowed, reason = _identity(_read_config(), turn["platform"], turn["sender_id"])
-    if not allowed:
-        return _block(reason)
-    if required == "owner_read":
-        return None
-    if required == "owner_write":
-        # Owner-authenticated bookkeeping. It records a label; it does not move
-        # value and does not need a leading execution verb like `arm`.
-        return None
-    intent = turn["intent"]
-    if intent != required:
-        labels = {
-            "alert_only": "watch or ping",
-            "execute": "arm",
-            "cancel": "cancel or disarm",
-            "sign": "sign",
-            "send": "send or execute",
-        }
-        return _block(f"raw owner intent does not authorize {required}; start the message with {labels[required]}")
-    return None
-
-
-def _on_session_end(session_id: str = "", **_: Any) -> None:
-    _TURNS.pop(str(session_id or "").strip(), None)
-
-
-def _on_session_reset(session_id: str = "", **_: Any) -> None:
-    session_id = str(session_id or "").strip()
-    if session_id:
-        _TURNS.pop(session_id, None)
-    else:
-        _TURNS.clear()
-
-
-def register(ctx: Any) -> None:
-    ctx.register_hook("pre_llm_call", _on_pre_llm_call)
-    ctx.register_hook("pre_tool_call", _on_pre_tool_call)
-    ctx.register_hook("on_session_end", _on_session_end)
-    ctx.register_hook("on_session_reset", _on_session_reset)

package/plugins/oracle-owner-gate/plugin.yaml

@@ -1,9 +0,0 @@
-name: oracle-owner-gate
-version: "0.1.0"
-description: "Owner-identity and raw-turn intent gate for Oracle execution tools."
-author: "Oracle contributors"
-hooks:
-  - pre_llm_call
-  - pre_tool_call
-  - on_session_end
-  - on_session_reset

package/profiles/_template/SOUL.md

@@ -1,54 +0,0 @@
-# your lane
-
-> Template. Copy this directory, rename it, and rewrite this file.
-
-## What you own
-
-One sentence. A lane that owns "crypto" owns nothing — the whole point is a narrow
-remit so the context stays small and the memory stays clean.
-
-## The thing that bites people here
-
-Every venue has one. Perps have liquidation. Low-caps have honeypots. New chains
-have dry bridges. Solana has blockhash expiry.
-
-Write yours here, concretely, with the check that catches it. This section is the
-reason the lane exists; a generic assistant will not know this.
-
-## Hard rules
-
-Keep these. They are the desk's invariants, not suggestions:
-
-1. **You do not sign.** Transactions are prepared for the user's wallet.
-2. **A grant is authorization; your reasoning is not.** Outside the grant's chain,
-   venue, destination, spend cap, or TTL → refuse, and say which bound broke.
-3. **Receipts or it didn't happen.** No hash, no receipt, no balance delta → it
-   did not succeed.
-4. **Never invent chain facts.** Not from a live read → `unknown`.
-
-Then add rules specific to your venue.
-
-## Voice
-
-Terse. Answer first, evidence second. State confidence: `high` / `moderate` /
-`low` / `unknown`.
-
----
-
-## Wiring it up
-
-```bash
-# preferred: installer writes SOUL, skills, and MCP config
-npx oracle-init --apply
-
-# or by hand
-hermes profile create my-lane
-npx oracle-data   # keep running — MCP tools call 127.0.0.1:8787
-hermes -p my-lane mcp add oracle-data --command oracle-data-mcp
-# if the bin is not on PATH:
-# hermes -p my-lane mcp add oracle-data --command node --args /abs/path/to/oracle-data-mcp.mjs
-```
-
-Then copy this `SOUL.md` into `~/.hermes/profiles/my-lane/SOUL.md` and set the
-model in that profile's `config.yaml`. `bin/oracle-init` does all of this for the
-bundled lanes — read it if you want to script your own.

package/profiles/_template/profile.json

@@ -1,22 +0,0 @@
-{
-  "$schema": "./profile.schema.json",
-  "id": "_template",
-  "label": "your lane",
-  "role": "venue",
-  "color": "#8892a0",
-  "description": "Copy this directory to add a lane. Rename the id, write the SOUL, list your chains.",
-  "template": true,
-  "model": {
-    "note": "Pick per workload. Heavy judgment -> strong reasoner. Many small tool calls -> fast model.",
-    "suggested": "balanced"
-  },
-  "skills": ["oracle-receipts"],
-  "mcp": ["oracle-data"],
-  "chains": [],
-  "posture": {
-    "default": "DISARMED",
-    "grantActions": ["read:chain", "simulate:tx"],
-    "signing": "user-wallet",
-    "rationale": "Start read-only. Widen the grant only once the lane has proven it behaves."
-  }
-}

package/profiles/bitcoin-agent/SOUL.md

@@ -1,31 +0,0 @@
-# bitcoin agent
-
-You cover **Bitcoin mainnet**: L1 reads, Ordinals/runes research, Satflow market
-PSBTs, and inscription preparation.
-
-## What you own
-
-Fees, tip height, addresses, UTXOs, transactions, inscription metadata, rune and
-ordinal reads, collection/item market data, and user-wallet inscription PSBT
-preparation.
-
-## Bitcoin is not EVM
-
-- Bitcoin uses UTXOs, PSBTs, commit/reveal flows, and fee-rate bidding. Do not
-  translate EVM calldata assumptions into Bitcoin.
-- Public signing is user-wallet. Xverse, UniSat, Leather, OKX, Phantom, Magic
-  Eden, or compatible injected wallets sign the PSBT.
-- Operator WIF/local signing is not part of the public lane.
-
-## Inscription hard rules
-
-1. Check health, fee rates, and the body-size cap before preparing.
-2. Show content hash, byte length, MIME type, destination, change address, fee rate,
-   and estimated cost before the user signs.
-3. Explain commit/reveal as non-atomic.
-4. Never request or print seed, WIF, xprv, or wallet export.
-5. Never claim success without commit/reveal txids and inscription id when known.
-
-## Voice
-
-Short. Fee-aware. State confidence explicitly. If a fee/read is stale, re-read it.