@oracle-agent/oracle 0.3.4 → 0.3.6

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")}`);
 }

package/bin/oracle-upgrade.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { upgradeProfiles } from "../src/profile-upgrade.mjs";
+
+const argv = process.argv.slice(2);
+const value = (flag) => {
+  const index = argv.indexOf(flag);
+  if (index < 0) return null;
+  if (!argv[index + 1] || argv[index + 1].startsWith("--")) throw new Error(`${flag} requires a value`);
+  return argv[index + 1];
+};
+
+try {
+  const known = new Set(["--apply", "--json", "--only", "--hermes-home", "--package-root", "--control-command"]);
+  for (let i = 0; i < argv.length; i += 1) {
+    if (!known.has(argv[i])) throw new Error(`unknown option: ${argv[i]}`);
+    if (["--only", "--hermes-home", "--package-root", "--control-command"].includes(argv[i])) i += 1;
+  }
+  const packageRoot = path.resolve(value("--package-root") || path.join(path.dirname(fileURLToPath(import.meta.url)), ".."));
+  const hermesHome = path.resolve(value("--hermes-home") || process.env.HERMES_HOME || path.join(os.homedir(), ".hermes"));
+  const control = value("--control-command");
+  const result = upgradeProfiles({
+    hermesHome,
+    packageRoot,
+    only: value("--only"),
+    apply: argv.includes("--apply"),
+    controlCommand: control ? control.trim().split(/\s+/) : null,
+  });
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else {
+    console.log(`oracle-upgrade ${result.applied ? "applied" : "dry run"}: ${result.profiles.length} profile(s)`);
+    for (const key of ["created", "updated", "unchanged", "backups"]) console.log(`${key}: ${result[key].length}`);
+    if (!result.applied) console.log("Re-run with --apply to make these changes.");
+  }
+} catch (error) {
+  const failure = { ok: false, error: error.message };
+  if (argv.includes("--json")) process.stdout.write(`${JSON.stringify(failure, null, 2)}\n`);
+  else console.error(`oracle-upgrade: ${error.message}`);
+  process.exitCode = 1;
+}

package/docs/profiles.md

@@ -34,19 +34,30 @@ Three practical reasons, learned the hard way:
 
 | Profile | Owns | Typical grant |
 |---|---|---|
-| `oracle` | routing, synthesis, multi-chain comparison | read + simulate only |
+| `oracle` | routing, synthesis, multi-chain comparison, `/balance` portfolio aggregation | read + simulate only |
 | `polymarket-agent` | prediction markets, event odds, CLOB cards/API-key order intents | read, quote, prepare |
 | `hyperliquid-agent` | perps, spot, HIP-3 builder dexs, HIP-4 outcomes | read, quote, prepare |
 | `robinhood-agent` | Robinhood Chain (4663) tokens, NFTs, tokenized Robinhood-style assets, capped NFT mints | read, quote, prepare |
 | `solana-agent` | Solana swaps, research, Jupiter routes | read, quote, prepare |
 | `bitcoin-agent` | Bitcoin L1, Ordinals/runes, inscriptions | read, prepare:inscription |
 | `stable-agent` | Stable (988), USDT-native gas quirks | read, quote, prepare |
-| `protocol-builder` | scaffold, review, prepare protocol/NFT/gacha/DEX deploys and mint bots | prepare:deploy, prepare:mint, simulate |
+| `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 |
 
-`protocol-builder` can design a protocol and prepare an unsigned deploy or mint
-bot transaction. It never house-signs, and its destinations and gas-war caps are
-allowlisted like any other lane.
+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.
+
+`protocol-builder` classifies each launch by chain family, then designs and
+prepares unsigned token, NFT collection, protocol, or mint-bot transactions. It
+fails closed when no verified adapter exists, never house-signs, and keeps deploy,
+metadata, liquidity, mint, and authority actions as separate user approvals.
+
+The root `oracle` lane owns `/balance`, natural-language balance, and portfolio
+history requests. Its `balance` skill calls the read-only
+`portfolio_snapshot` MCP tool once, records a compact profile-local observation,
+reports partial coverage and unavailable providers, and labels `knownUsd` as
+incomplete instead of inventing a full portfolio total. `portfolio_history`
+reads those observations and `portfolio_value_graph` renders the known-value
+series while omitting unavailable values rather than plotting fake zeroes.
 
 ## Model choice is yours
 
@@ -101,10 +112,21 @@ hermes profile create polymarket-agent
 ```
 
 Then give it a `SOUL.md` (who it is, what it owns, what it must refuse) and a
-`config.yaml` (model + provider). Point it at Oracle's MCP read plane:
+`config.yaml` (model + provider). Point it at Oracle's MCP read plane.
+
+`oracle-init --apply` writes this for you. Manual form (Hermes wants command and
+args as separate tokens):
 
 ```bash
-hermes mcp add oracle-data --command "oracle-data-mcp"
+# terminal 1 — local read plane the MCP tools call
+npx oracle-data
+
+# terminal 2 — wire MCP into a lane
+hermes -p polymarket-agent mcp add oracle-data \
+  --command node \
+  --args "$(node -p "require.resolve('@oracle-agent/oracle/package.json').replace(/package\\.json$/, 'bin/oracle-data-mcp.mjs')")"
+# or after npm link / PATH has the bin:
+# hermes -p polymarket-agent mcp add oracle-data --command oracle-data-mcp
 ```
 
 Now that lane can read 30+ providers across 11 chains, quote real routes, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oracle-agent/oracle",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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",
@@ -30,6 +30,7 @@
     "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"
   },
@@ -40,6 +41,7 @@
     "./chains": "./src/chains.mjs",
     "./scanner": "./src/scanner/index.mjs",
     "./router": "./src/router/index.mjs",
+    "./action-semantics": "./src/action-semantics.mjs",
     "./nft-gas-war": "./src/nft-gas-war-guard.mjs",
     "./prepare-envelope": "./src/prepare-envelope.mjs"
   },
@@ -76,6 +78,7 @@
     "src/",
     "profiles/",
     "skills/",
+    "plugins/",
     "public/",
     "artifacts/",
     "README.md",

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

@@ -0,0 +1,213 @@
+"""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",
+}
+
+_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
+    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

@@ -0,0 +1,9 @@
+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

@@ -38,8 +38,15 @@ Terse. Answer first, evidence second. State confidence: `high` / `moderate` /
 ## Wiring it up
 
 ```bash
+# preferred: installer writes SOUL, skills, and MCP config
+npx oracle-init --apply
+
+# or by hand
 hermes profile create my-lane
-hermes mcp add oracle-data --command "oracle-data-mcp"
+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

package/profiles/oracle/SOUL.md

@@ -20,9 +20,11 @@ value yourself.
 | Stable (988), USDT-native gas | `stable-agent` |
 | tokenized Robinhood-style assets / stock tokens | exact home-chain lane + `oracle-rfq-tokenized-assets` |
 | meme-token launches, sniping, liquidity/pool watches | token's home-chain lane + `oracle-meme-token-sniper` |
-| deploy/review a contract, NFT/gacha launch, DEX, or capped NFT mint bot | `protocol-builder` + `oracle-nft-mint-gas-war` |
+| create a fungible token or NFT collection | home-chain specialist for chain facts + `protocol-builder` using the matching multichain launch skill |
+| deploy/review custom contracts, gacha, DEX, launchpad, or capped NFT mint bot | `protocol-builder` + `oracle-nft-mint-gas-war` |
 | RFQ / solver-intent route comparison across chains | `oracle` + `oracle-rfq-tokenized-assets` |
 | graph/card alert rendering | token's home-chain lane + `oracle-chain-graphs-telegram-cards` |
+| `/balance`, balance, holdings, wallet portfolio | `oracle` + `balance`; one deterministic `portfolio_snapshot` read plus profile-local observation |
 | compare chains, "which is cheaper" | you, using the data plane |
 
 If the chain is ambiguous, resolve the token's home chain first (DexScreener via
@@ -36,7 +38,15 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    margin call for different decisions. If `rankedOn` is `gross`, gas was NOT
    accounted for — say so. See the `oracle-best-execution` skill.
 
-1. **You never sign.** You prepare, simulate, explain. The user's wallet signs.
+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
+   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`.
+   Only an explicit `arm` may mean `actionMode: execute`, and only for one exact,
+   bounded owner-authorized action.
 2. **RFQ is a route source, not a permission bypass.** Compare solver/RFQ
    quotes net of gas/spread where configured, enforce expiry, and keep exact
    artifact kinds separate.
@@ -53,6 +63,11 @@ the data plane). If it stays ambiguous, ask. Do not guess a chain.
    delta → the action did not succeed. Say so plainly.
 7. **Never invent chain facts.** If it did not come from a live read, label it
    `unknown`.
+8. **Balance uses one source of truth.** `/balance` and plain-language balance
+   requests call `portfolio_snapshot`; use `portfolio_history` and
+   `portfolio_value_graph` for historical requests. Report `knownUsd` as
+   incomplete whenever a provider, address, price, token/NFT indexer, or chain
+   adapter is missing. Never turn an unavailable historical value into zero.
 
 ## Confidence
 

package/profiles/oracle/profile.json

@@ -4,13 +4,14 @@
   "label": "oracle",
   "role": "router",
   "color": "#7CC4FF",
-  "description": "Router for multichain trading, building, analysis, scanners, RFQ, tokenized-asset buys, NFT mint gas limits, meme-token sniping, Solana, Bitcoin, and protocol launches.",
+  "description": "Router for multichain trading, building, analysis, wallet/NFT inventory and value history, scanners, RFQ, tokenized-asset buys, NFT mint gas limits, meme-token sniping, and chain-family token/NFT launches.",
   "model": {
     "note": "Wants the strongest reasoner available: routing and synthesis are judgment calls.",
     "suggested": "strong-reasoner"
   },
   "skills": [
     "oracle-desk",
+    "oracle-action-semantics",
     "oracle-grants",
     "oracle-receipts",
     "oracle-best-execution",
@@ -18,7 +19,10 @@
     "oracle-meme-token-sniper",
     "oracle-chain-graphs-telegram-cards",
     "oracle-rfq-tokenized-assets",
-    "oracle-nft-mint-gas-war"
+    "oracle-nft-mint-gas-war",
+    "oracle-multichain-token-launch",
+    "oracle-multichain-nft-launch",
+    "balance"
   ],
   "mcp": [
     "oracle-data"

package/profiles/protocol-builder/SOUL.md

@@ -1,13 +1,16 @@
 # protocol builder
 
-You design, review, and prepare deploys for protocols, NFT/gacha products, DEX
-surfaces, launchpads, mint pages, and scanner-backed on-chain apps. You never sign one.
+You classify by chain family, then design, review, and prepare deploys for fungible
+tokens, NFT collections, protocols, gacha products, DEX surfaces, launchpads, mint
+pages, and scanner-backed on-chain apps. You never sign one. Unsupported chain
+adapters fail closed.
 
 ## What you own
 
-Contract scaffolding, NFT/gacha mint mechanics, DEX/pool/launchpad design,
-security review, deploy and verify scripts, and **unsigned** deploy transactions.
-Research of existing protocols before cloning them.
+Chain-family token/NFT launch manifests, contract and program scaffolding,
+NFT/gacha mint mechanics, DEX/pool/launchpad design, security review, deploy and
+verify scripts, and **unsigned** deploy transactions. Research of existing
+protocols before cloning them.
 
 ## Deployment is permanent
 
@@ -42,7 +45,11 @@ what an attacker gains from each privileged function.
 3. **Simulate before preparing.** An unsimulated deploy is a guess.
 4. **State the authority model before the code.** A user who doesn't know who owns
    the contract cannot consent to deploying it.
-5. **Receipts or it didn't happen** — deployed address, receipt, verified source.
+5. **Receipts or it didn't happen.** Deployed address, receipt, verified source.
+6. **Chain-family support is explicit.** Use `TEMPLATE_READY`, `ADAPTER_READY`,
+   `GUIDED_BUILD`, `RESEARCH_ONLY`, or `UNSUPPORTED`. RPC reachability is not deploy support.
+7. **One approval per side effect.** Deploy, metadata upload, mint, liquidity,
+   authority transfer/revoke, reveal, and verification remain separate.
 
 ## Voice
 

package/profiles/protocol-builder/profile.json

@@ -4,7 +4,7 @@
   "label": "protocol builder",
   "role": "builder",
   "color": "#ff8c5a",
-  "description": "Builder lane for protocol, NFT/gacha, DEX, scanner, and mint-bot surfaces with unsigned deploy/mint preparation.",
+  "description": "Builder lane for protocol, chain-family token/NFT collections, gacha, DEX, scanner, and mint-bot surfaces with unsigned deploy/mint preparation.",
   "model": {
     "note": "Contract review is unforgiving and mistakes are permanent; wants the strongest reasoner available.",
     "suggested": "strong-reasoner"
@@ -13,6 +13,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",
     "oracle-receipts",