@oracle-agent/oracle 0.24.1 → 0.24.2

package/dist/assets/skills/oracle-airdrop-calculator/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: oracle-airdrop-calculator
+description: Use when scanning a wallet for airdrop eligibility.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Airdrop calculator (Oracle)
+
+Use when DEMI asks to check a wallet's airdrop eligibility, scan for potential drops, or check "what airdrops am I qualified for." General-purpose — not tied to any single campaign.
+
+## Architecture (shipped 2026-08-06)
+
+```
+Oracle app API
+  → GET /api/oracle/airdrop?wallet=0x...&format=summary|full
+  → scanner.ts       Blockscout V2 multi-chain activity profiler
+  → campaign.ts      known-campaign registry (12 programs, 8 ecosystems)
+  → scorer.ts        eligibility matching engine
+```
+
+Code roots in `~/projects/oracle-app/`:
+- `lib/oracle/airdrop/scanner.ts` — parallel Blockscout V2 scan
+- `lib/oracle/airdrop/campaigns.ts` — campaign criteria registry
+- `lib/oracle/airdrop/scorer.ts` — scoring engine
+- `app/api/oracle/airdrop/route.ts` — API route
+
+## How it works
+
+**Scanner** profiles a wallet across all supported EVM chains using public Blockscout V2 APIs:
+- `GET /api/v2/addresses/{wallet}/counters` → `transactions_count`
+- `GET /api/v2/addresses/{wallet}` → `coin_balance` + `exchange_rate`
+- `GET /api/v2/addresses/{wallet}/transactions` → age + protocol interactions (5s timeout, optional)
+- `GET /api/v2/addresses/{wallet}/token-balances` → USD-denominated holdings
+
+Chains are scanned in parallel (3 at a time). Transactions fetch has a 5s timeout — on huge wallets it times out gracefully and returns counters-only data.
+
+**Campaign registry** holds 12 known programs with explicit criteria:
+- Confirmed: Hyperliquid Points, HL Perps, Locals→STABLE
+- Likely: HyperEVM Ecosystem, DeFi Power User
+- Speculative: Base, Arbitrum, Optimism, Polygon, Abstract, LI.FI Loyalty, Across Bridge
+
+**Scorer** compares wallet profile against each campaign's criteria, producing:
+- `eligibility` 0-100%
+- `verdict`: eligible / partial / ineligible / unknown
+- `matchedCriteria` + `missedCriteria` lists
+- Per-criterion detail logs
+
+## API
+
+```
+# Summary (fast, overview only)
+GET /api/oracle/airdrop?wallet=0x...&format=summary
+
+# Full (campaign-by-campaign detail)
+GET /api/oracle/airdrop?wallet=0x...&format=full
+```
+
+Response includes `totalTx`, `totalVolumeUsd`, `chainCount`, `isMultiChain`, `walletAgeDays`, and per-campaign scores.
+
+## Adding campaigns
+
+Edit `lib/oracle/airdrop/campaigns.ts` — add an entry to the `CAMPAIGNS` array:
+```ts
+{
+  id: "unique-id",
+  name: "Human Name",
+  token: "TICKER",
+  chainId: "base",
+  status: "active" | "upcoming" | "completed" | "rumored",
+  confidence: "confirmed" | "likely" | "speculative",
+  criteria: [
+    { kind: "tx_count", min: 10, description: "10+ tx" },
+    { kind: "volume_usd", min: 1000, description: "$1k+ volume" },
+    { kind: "chain_used", chainId: "base", description: "Activity on Base" },
+    { kind: "protocol_used", contract: "0x...", chainId: 8453, label: "Protocol Name" },
+    { kind: "wallet_age_days", min: 30, description: "30+ days old" },
+    { kind: "nft_held", contract: "0x...", chainId: 999, label: "NFT Name" },
+    { kind: "points_eligible", program: "hyperliquid", description: "Points program" },
+  ],
+  source: "https://official.source",
+  allocationEstimate: "Range or methodology description",
+}
+```
+
+`nft_held` and `points_eligible` criteria are skipped in scoring (require dedicated APIs). All other criteria are checkable from Blockscout data alone.
+
+## Blockscout V2 API quirks
+
+- **Counters endpoint is `/counters`** not `/addresses/{wallet}` for tx count — the address endpoint does NOT include `tx_count`
+- **`transactions_count` is a string**, not a number — parseInt it
+- **Transactions `to` field** is `{ hash: "0x..." }` not a flat string
+- **Token balances** nest: `{ token: { exchange_rate, decimals }, value }` — not flat
+- **`coin_balance`** is in wei (divide by 1e18)
+- **`exchange_rate`** is a USD string on the address object
+
+## Performance design
+
+- Parallel scan (3 chains at a time) avoids rate-limiting
+- Transaction fetch has 5s timeout — skips gracefully on huge wallets
+- 0 tx on a chain = early return, skip remaining fetches
+- Summary mode skips per-campaign detail for fast response
+
+## Pitfalls
+
+- Blockscout instances vary by chain — URLs are hardcoded per chain in `blockscoutUrl()`
+- Chains without Blockscout return `error: "no explorer available"`
+- A wallet with 0 tx everywhere returns `ineligible` for all campaigns — not an error
+- `nft_held` and `points_eligible` criteria always return "unknown" — they need dedicated API integration
+- The `totalVolumeUsd` is based on current token holdings, not historical trade volume — it's a lower bound

package/dist/assets/skills/oracle-desk-product/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: oracle-desk-product
+description: Use for Oracle product law, self-host C+B, NL confirm/arm.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Oracle desk product
+
+Class-level product law for the Oracle multichain agent desk (app + CLI self-host).
+
+## One-line definition
+
+**Oracle = multi-chain, self-custodial, locally hosted agent harness.**
+
+| Word | Meaning |
+|---|---|
+| Multi-chain | EVM + Sol + BTC + HL/RH/Stable |
+| Self-custodial | Keys on user machine or user wallet — never house cloud |
+| Locally hosted | Desk/exec/policy on 127.0.0.1 / their box by default |
+| Agent harness | NL chat → quote → confirm/arm → policy → sign → receipt |
+
+## C + B (custody + rails)
+
+| Layer | |
+|---|---|
+| **C** | `oracle sign init` on **their** disk. **Never paste seed in app UI.** |
+| **B** | `~/.config/oracle/agent-policy.json` — $/trade, $/day, chains, slip, TTL, arm/disarm, **`noLimits`** |
+
+### Policy-file integrity — RESOLVED (2026-08-08, multi-model audit 5/5 HIGH)
+`agent-policy.json` now carries a **SHA-256 `integrity` field** over its canonical
+body (fixed field order in `canonicalPolicyBody`). `loadAgentPolicy` fails CLOSED:
+a file edited outside `saveAgentPolicy` (e.g. `echo '{"noLimits":true}' >
+agent-policy.json`) no longer hashes to its own integrity → loads as **DISARMED**,
+never as a broader grant. Save re-signs every write (mode 0600). Rules:
+- Never let a tampered file WIDEN caps — always disarmed.
+- Missing `integrity` on an existing file is tolerated (pre-upgrade files still
+  load), but any present-yet-mismatched integrity disarms.
+- Unit check before shipping changes: valid passes, tampered fails, missing fails.
+- Legacy `unlimited` key still maps to `noLimits` for compat.
+
+### Policy modes
+
+- **With limits** — enforce before agent sign; daily ledger  
+- **No limits** — skip caps; **Disarm still kills**; all-EVM preset  
+- API: `POST /api/oracle/agent/policy` actions `no_limits` \| `with_limits` \| `arm` \| `disarm`
+
+DEMI Mac often: noLimits + armed + all EVM.
+
+### Agent parity — the admin/no-fees variant shares ONE policy source (RESOLVED 2026-08-09)
+
+There are TWO packages, NOT one:
+- `@oracle-agent/oracle` — public npm. Prepare-only by default/hosted; self-hosters get
+  encrypted local vault + loopback signer for **their** keys, with public fees
+  (`~/projects/oracle`).
+- `@oracle-agent/agent` — ADMIN variant, same capability, **zero** Oracle fees; DEMI's
+  local signer/key vault (`~/projects/oracle-agent`, SEPARATE repo). One-way dep:
+  agent pins `oracle`; oracle never imports agent. Separate repos/releases.
+
+**Naming LAW (DEMI 2026-08-09): the word "operator" is GONE from the product surface.**
+It is the AGENT everywhere. The old npm name ``@oracle-agent/agent` (private, never npm)` was **fully
+unpublished 2026-08-09 (now E404)** — deprecation was only the stopgap; the tarball is
+gone and the name must never be published again. Bins renamed: `oracle-operator` →
+`oracle-agent`, `oracle-operator-caps` → `oracle-agent-caps`. Repo+dir renamed
+`oracle-operator` → `oracle-agent`. When touching copy/docs/code: never reintroduce
+"operator" for the product role. KEEP the EVM-standard homonym "operator"
+(setApprovalForAll/approve — the approved address) and the comparison-operator identifier
+in action-runner; those are unrelated to the product role and must stay. If a doc/code
+audit turns up a product-role "operator", rename it to "agent" (see
+`references/agent-rename-and-npm.md`).
+
+**Renames are not done when the source is clean — they are done when the SHIPPED
+ARTIFACT is clean.** A rename landed in source can still reach users through stale
+build output: a packaged desktop runtime kept telling users to
+`npm i -g @oracle-agent/oracle` (a package that no longer exists)
+because cached content-hashed chunks rode along in the artifact. After any product-surface
+rename, grep the packaged runtime for the old token, not just the repo.
+
+Parity trigger = product-version (product law changes like custody semantics), NOT repo-version.
+"Similar" is not "verified identical" — when asked if the two are in parity, DIFF the security
+surfaces, don't assume.
+
+### Public local signer: product law vs shipped fact (DEMI law; verify every claim)
+DEMI's intended public product is **self-hosted Oracle + a loopback local signer for the
+user's own keys**. The private `@oracle-agent/agent` remains the ADMIN/no-fees vault and is
+never published. The split is about WHOSE keys, not whether self-hosting is allowed.
+
+Do **not** turn the product target into a shipped-capability claim. Before answering "does
+public have a local signer?", verify these three surfaces independently:
+1. `origin/main` public package: signer commands/modules and custody-boundary tests.
+2. Published npm `latest`: version and packed artifact, not merely source main.
+3. This machine's deployment: active binary path plus loopback signer service/port.
+
+Report them separately. A private deployment having `oracle-signer` active on `127.0.0.1`
+does not prove npm users receive it. A locally hosted model/data/policy loop does not imply
+a bundled signer. A merged feature is not public until the npm artifact containing it is
+published and inspected.
+
+**Current verified state as of 2026-08-12:** public npm `@oracle-agent/oracle@0.24.0`
+ships the optional encrypted local vault + short-lived loopback signer. Hosted/default
+Oracle stays prepare-only. Self-host after `oracle sign init|import` is **auto-armed**
+for user-initiated actions. Public still charges the disclosed fee card; Administrator
+(`@oracle-agent/agent`, never on npm) stays zero-fee with DEMI's keys.
+
+Public signer families are **EVM, Solana, Bitcoin only** — not separate HL/Poly
+account surfaces. Do not resurrect Tread.fi OEMS/API protocol interaction; TradFi
+algorithms (TWAP/VWAP/POV/iceberg/IS) are native Oracle planners, not an external
+broker.
+
+A merged PR is still not "shipped" until `npm view @oracle-agent/oracle version`
+matches the intended release and the packed tarball was secret-scanned. Never accept
+"key file exists" or "service is active" as proof that public onboarding works.
+
+Detail: `references/public-admin-parity.md`.
+
+**Key-path wiring bug found + fixed 2026-08-09 (verify this stays wired).** `oracle sign
+import` wrote the key to `<config>/keys/evm.json` and armed `exec.env`, but the loopback
+signer daemon resolves key material from the vault path written by `oracle sign import`.
+A freshly imported key was **silently
+never picked up** by `oracle signer` — import reported success, signing just never found
+it. Fix: import now also writes `signer.env` pointing both vars at the file it created,
+preserving other entries (`wireSignerKeyEnv` in `src/cli/commands/sign.mjs`; regression
+test in `test/cli-signplane.test.mjs` asserts key material, shred, arm, AND env wiring).
+Lesson for this class: "the key file exists on disk" is NOT proof the signer can sign —
+trace provision → env → daemon resolution end to end before claiming a signer works.
+Note `sign.mjs` is ESM: helpers need `await import("node:fs"/"node:path")`, and `join`
+scoped inside a verb block is not visible to a module-level helper.
+
+The gap found 2026-08-09: agent enforced only its own env caps (`ORACLE_MAX_NOTIONAL_USD`, …)
+and NEVER read the app's `agent-policy.json` — two B walls that could drift (app UI noLimits
+while signer still enforced env caps; env raised while app route still capped). Fixed:
+- `src/agent-policy-file.mjs` reads the SAME `~/.config/oracle/agent-policy.json` with the SAME
+  SHA-256 integrity algorithm (`oracle-agent-policy:v1:` + canonical 10-field body). Verified
+  hash-for-hash identical to the app — a file signed by the app verifies on the signer.
+- Tampered/corrupt/no-integrity policy → signer DISARMS regardless of env (a disarmed app must
+  mean a disarmed signer; no split-brain escape hatch).
+- Valid file merges maxUsdPerTrade/maxUsdPerDay as the cap FLOOR; env caps may only TIGHTEN.
+- Valid noLimits lifts file dollar caps but env caps stay authoritative.
+- KEEP the hash algorithm byte-identical across both sides — a mismatch silently disarms.
+
+Detail + the full parity diff table: `references/agent-parity.md`.
+
+## Chat trade flow (required UX)
+
+```
+user:  swap .1 eth to base
+app:   Prepared · not signed
+user:  confirm | arm | yes | go
+app:   policy → execute → tx hash
+user:  cancel
+app:   drop quote
+```
+
+- Parse `swap .1 eth to base` → ETH→**USDC** on **Base** (leading-dot amounts OK).
+- Primary = **conversational** confirm/arm; buttons secondary.
+- Default: **confirm each trade** until auto-within-rails is explicit.
+- Chat `arm` = execute **pending quote**. Settings Arm = kill-switch allow execute. Disambiguate.
+
+### Arm disambiguation — RESOLVED (2026-08-08, multi-model audit consensus 5/5)
+The two `arm` surfaces are now labeled differently in the UI:
+- **Settings global kill-switch**: button **"Enable execution" / "Disable execution"**, status
+  pill **"execution on" / "execution off"** (never "armed"). Copy: *"Global kill-switch ·
+  distinct from chat 'arm' (one trade)"* and *"Chat 'arm' still requires this kill-switch on."*
+- **Chat `arm`**: unchanged — executes ONE pending quote via `parseConfirmIntent`. It fails
+  closed when the Settings kill-switch is off (`checkAgentPolicy` `disarmed` gate).
+- Internal `agent-policy.json` field stays `armed` (API compat) — the change is UI-label only
+  in `AgentPolicySettings.tsx`. Keep these labels distinct; do not collapse them back to one
+  "arm" word.
+
+### Receipt discipline in the UI — RESOLVED (2026-08-08, multi-model audit consensus 4/5)
+- Celebration overlay fires ONLY when `trade.status === "done" && trade.txHash` — no receipt
+  hash, no fireworks. "Done" without a hash is a UI claim, not proof.
+- Agent path with no txHash says: *"Submitted — no receipt hash returned. Verify on-chain
+  before treating as settled."* Never print bare "Done." without a hash.
+- Per-trade confirm is structurally enforced via `confirmToken` even under `noLimits` — the
+  "no dollar cap but still confirm" invariant holds at the chat layer.
+
+### Confirm-token one-time consume — RESOLVED (2026-08-09, Grok 4.5 red-team leg)
+Grok 4.5 (6th auditor) found: owner confirm tokens were verified by HMAC + 3-min TTL only,
+with NO spent-nonce tracking — the same token could replay the identical intent within the
+TTL window. Fix: `lib/oracle/confirm-nonce.ts` (`tryConsumeNonce`) — a shared atomic
+spent-nonce registry consumed by BOTH owner-exec routes (`owner/swap`, `trade/quote`). A
+second use of any token fails "already used — re-quote". Rules:
+- Token mints bind 14 intent fields (nonce, chainId, tokenIn, amountIn, txTo, source, ...)
+  — replaying a token against different intent fields fails HMAC anyway.
+- Strategy/shadow modules must have ZERO edges to owner-exec (verified clean).
+- Keep the consume check inside verify, right after TTL check, before returning ok.
+- Regression tests: `test/confirm-nonce.test.mjs`.
+
+Code: `lib/oracle/confirm-nonce.ts`, `app/api/oracle/owner/swap/route.ts`, `app/api/oracle/trade/quote/route.ts`.
+
+Code: `lib/oracle/swap-intent.ts`, `ChatDeskPane`, `/api/oracle/trade/quote`.
+
+## Sessions persist, and they are scoped BY CHAIN (DEMI law 2026-08-09)
+
+DEMI: *"oracle should also have sessions on the side so when you go back to chat
+you dont lose where you left off IE, building something and if you were on a
+chain it should seperate sessions by chain."*
+
+- The chat surface is **not stateless**. Returning to chat resumes exactly where
+  the last session stopped — mid-build, mid-comparison, mid-prepare.
+- Sessions are **partitioned by chain**. Work begun while pinned to a chain
+  belongs to that chain's thread; `/chain` switches thread, and switching back
+  restores that chain's in-flight context instead of starting cold or bleeding
+  another chain's state into it.
+- `~/.config/oracle/active-chain.json` already tracks the pinned chain and is
+  the natural partition key.
+- "Which chain was I on" and "what was I doing" are the SAME lookup. Losing
+  either is the failure this exists to prevent.
+- Session state carries build/trade context ONLY. **Oracle never holds the
+  keys** — never persist passphrases, tokens, or key material into a session.
+
+## Custody honesty
+
+- Wallet path: address only + wallet popup sign.  
+- Agent path: local agent key via CLI, not app paste.  
+- B-alone (Permit2 session) ≠ “sign every time”; product is **C+B**.
+
+## Self-host surfaces
+
+- `/api/oracle/selfhost/status|init` — local desk URLs, no keys  
+- Onboarding: Your machine. Your agent. Your keys.  
+- Downloaders ≠ Arch Tailscale default (DEMI thin-client is ops-only)
+
+## Portfolio
+
+- Coin list primary; Swap/Send prefill  
+- **TokenLogo** on holdings when picture exists  
+- Stable ERC-20 (FEFER): watch-token probe  
+
+## Navigation + rail (audit-consensus decisions, 2026-08-08)
+
+- **Tab labels describe function, never repeat the brand.** Primary chat tab is
+  **"Desk"** (NOT "Oracle" — the audit called brand-name tabs a same-brand
+  collision; the product mark in the header stays "Oracle"). Swap tab is
+  **"Simulate"** (dry-run sandbox naming; the NL harness lives in Desk, so
+  Prepare/confirm/sign are NOT a separate stage tab).
+- **Portfolio rail defaults OPEN on desktop ≥1280px**, closed on smaller
+  viewports, and the user's explicit collapse/expand persists to
+  `localStorage("oracle-rail-open")`. The default is applied in a mounted
+  effect (SSR-safe — initial state is always false, so no hydration mismatch).
+- **Every mono figure uses tabular-nums + lining-nums** (globals.css on
+  `.font-mono`, `.font-mono-ui`, code/kbd) — JB Mono digits align vertically;
+  this is what makes a financial desk font a financial desk font.
+
+## Evals
+
+- Existing: `packages/oracle/test`, `adversarial-bench.mjs`, Hermes `skill_eval.py`  
+- Desired desk suite: parse → quote → policy → confirm/arm → receipt (fixture RPC)
+
+## Fees — MINIMAL, disclosed, and pinned (DEMI law 2026-08-09)
+
+DEMI's standing preference: **"whats our bps fees they should be minimal."**
+When a change makes a fee legible, do not recite the code comment as if it
+settled the rate — state the real numbers from source and propose one.
+
+Current rate card (all OFF unless a recipient is configured; holders pay zero):
+
+| Rail | bps |
+|---|---|
+| swap | 5 |
+| bridge | 5 |
+| perps / nft | 0 |
+| HL builder codes | perp 2 · spot 1 · hip3 1 · hip4 1 (cap 10) |
+
+**One flat rate beats per-action tiers.** Bridge was 15 bps until 2026-08-09 on
+a "longer settlement, more failure modes" rationale — that prices OUR effort,
+not user value, on a heavily comparison-shopped action. It was also
+structurally self-defeating: only `lifi`/`paraswap` apply the integrator fee
+while bridge candidates are `lifi`/`relay`/`across`, so once the router began
+subtracting our own fee from `netOut`, the high tier handicapped the one venue
+that charged it — collecting almost nothing while making an identical bridge
+cost different amounts depending on which venue won. A per-venue accident is
+not a pricing tier.
+
+Three invariants to keep:
+
+- **A cost we charge is a cost we rank on.** Subtract the fee before ranking
+  routes, including on the degraded/gross path — a fee taken off the output is
+  exactly known even when gas is not. Otherwise "cheapest" is a number the user
+  never receives, breaking hard rule 0.
+- **Disclosure must reach a user, not just exist.** `describeFee()` sat with
+  zero production callers for a whole release: defined, unit-tested, rendered
+  nowhere. A disclosure function nobody calls is an unenforced invariant. Grep
+  for CALLERS outside the module and its tests before believing a fee is shown.
+- **Never stack rails.** perps/nft carry a 0 bps integrator tier precisely so a
+  Hyperliquid trade is charged only by its builder code. This is now pinned by
+  a test — if either tier goes nonzero, one action gets billed twice.
+
+**Pin every beneficiary of a value transfer.** Both paying addresses
+(`ORACLE_INTEGRATOR_FEE_RECIPIENT` and `ORACLE_HL_BUILDER_ADDRESS`) were
+shape-validated only (`0x` + 40 hex), so anything that could write an env var —
+a shell rc, a CI var, a stray `.env`, an npm postinstall — silently redirected
+user money. Both now check `~/.config/oracle/fee-recipient` (0600, one file for
+both rails so they cannot disagree) and fail **CLOSED to ZERO fee** on
+mismatch, never to "charge anyway to an unverified address." Unpinned installs
+are unchanged, so it is opt-in. Be honest about scope in the code comment: the
+pin does not stop code that can also rewrite the pin file — it raises the bar
+from "any env write anywhere" to "write this specific file" and makes the
+authorized recipient auditable.
+
+## Audit discipline (DEMI preference, corrected 2026-08-09)
+
+- **After a multi-model audit, apply EVERY recommendation.** Do not list
+  "kept intentionally" dissent items as the default outcome — DEMI reads that
+  as unfinished work ("i thought we fixed all") and will say "keep what you
+  recommend", meaning fix them. Only truly user-directed keeps survive, and
+  only with explicit sign-off per item.
+- When a red-team/audit finding says "must verify in-repo", verify it against
+  the tree BEFORE reporting — a red-team claim is a hypothesis, not a fact.
+- Report the verdict count as N/M across auditors (e.g. 5/6 ship-with-fixes)
+  and name which auditor dissented.
+- 7-auditor roster: deepseek-v4-pro · deepseek-v4-flash · gpt-5.6-sol · opus-5 ·
+  opus-4-8 · fable-5 · grok-4.5 (xai-oauth). Both DeepSeek legs route through
+  **`nous-direct`** (`deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`) —
+  the bare `deepseek` provider has an empty credential pool and its
+  `No usable credentials` error does NOT mean the model is unavailable. Harness:
+  `~/.hermes/profiles/oracle/scripts/oracle-multimodel-audit.sh`, brief refreshed
+  to current state before each run. Full procedure: `multi-model-product-audit`.
+
+## Pitfalls
+
+- Electron fake-home can hide `~/.config/oracle` / force execute off — use `ORACLE_REAL_HOME`.  
+- Never claim house signs for downloaders.  
+- Do not auto-broadcast on quote.  
+- Overlap: `oracle-public-product-ux` (chrome/themes); this skill owns product definition + confirm/arm + noLimits.
+
+## References
+
+- `references/nl-confirm-arm.md` — chat confirm/arm parse + arm disambiguation  
+- `references/agent-policy-nolimits.md` — noLimits / API actions  
+- `references/agent-parity.md` — agent=admin variant parity diff, shared-policy hash fix, merge-vs-remote-CI-shape-tests technique  
+- `references/agent-rename-and-npm.md` — the 2026-08-09 operator→agent rename procedure + npm unpublish/deprecate/2FA knowledge
+- `references/public-admin-parity.md` — public vs Admin: whose keys, fees, auto-arm, EVM/SOL/BTC-only signer, no Tread OEMS  
+
+## Related
+
+- `oracle-public-product-ux` — app chrome, themes (overlaps; curator may merge later)  
+- `oracle-action-semantics` — watch vs arm planes  
+- `oracle-fleet-desk-wiring` — DEMI Mac→Arch  

package/dist/assets/skills/oracle-evm/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: oracle-evm
+description: Use for any EVM chain desk work — ETH, Base, Arb, OP, Polygon, BSC, Avalanche, HyperEVM, Abstract, Stable, RH, or a registered extra chain.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+# Oracle EVM desk
+
+Same agent, same vault, same key. Different `chainId`.
+
+Do **not** treat Robinhood (4663) or HyperEVM (999) as the only EVM surfaces.
+If the token’s home chain is Base / Arb / ETH / …, work there.
+
+## Shipped registry (`src/chains.mjs`)
+
+| key | chainId | name |
+|---|---|---|
+| ethereum | 1 | Ethereum |
+| optimism | 10 | OP Mainnet |
+| bsc | 56 | BNB Smart Chain |
+| polygon | 137 | Polygon |
+| abstract | 2741 | Abstract |
+| base | 8453 | Base |
+| hyperevm | 999 | HyperEVM |
+| stable | 988 | Stable Mainnet |
+| avalanche | 43114 | Avalanche C-Chain |
+| arbitrum | 42161 | Arbitrum One |
+| robinhood | 4663 | Robinhood Chain |
+
+Unknown chain → `oracle chain list`, then DexScreener via `oracle_cli` `data call dex-screener …`. If still ambiguous, ask. Never guess a chainId.
+
+A new EVM chain can be registered at runtime (`registerChain`). Unsupported = `UNAVAILABLE`, not fake coverage.
+
+## How to work a request
+
+1. Resolve home chain first (`dex_search` / `dex_token`).
+2. Pin: `oracle chain use <key>` (or `argv ['chain','use','base']` via `oracle_cli` is not allowed — chain use is a CLI pin; in native chat use `/chain`).
+3. Quote net of gas: `oracle_cli` `route swap` / `route bridge`. Rank on **net received**.
+4. Prepare unsigned. Confirm is human. `signer_execute` needs a confirmationNonce.
+5. Receipt or it did not happen.
+
+## Surfaces (all EVM)
+
+- swap / bridge / approve / mint
+- token + contract research
+- meme scan (`evm_token_sniper_scan` is the same scanner on every supported EVM)
+- NFT mint gas-war caps
+- RFQ / tokenized assets when the venue exists on that chain
+
+Solana and Bitcoin are separate signer families. HL L1 perps and Polymarket are data/prepare venues, not extra EVM signer families.
+
+## Related
+
+`chain` · `evm-contract-research` · `oracle-best-execution` · `oracle-meme-token-sniper` · `oracle-multichain-convert` · `venue-capability-boundaries`

package/dist/assets/skills/oracle-harness/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: oracle-harness
+description: Use when deciding what Oracle native absorbs from Hermes, Claude, Codex, or other clients.
+---
+
+# Oracle is the harness
+
+Oracle native (`oracle chat`) is the product loop. Other clients are **feature sources** and optional engines, not the home.
+
+## Absorb (public)
+
+From Hermes / Claude / Codex / Cursor-class agents, ship the **desk capabilities**, not the brand:
+
+| Capability | Oracle surface |
+|---|---|
+| Agent loop + tools | standalone client (16–50 steps) |
+| Skills | packaged + `~/.config/oracle/skills/<name>/SKILL.md` |
+| Memory / cron / todos / session | native tools |
+| Web fetch + search | `web_fetch` / `web_search` |
+| Bounded browser + vision | `browser_exec` / `vision_analyze` |
+| MCP in and out | `mcp_list` / `mcp_call` + `oracle mcp install` |
+| Plugins | `oracle plugins install` |
+| Multi-model | `oracle setup model` / `/model` |
+| Attach another engine | `oracle chat --backend hermes\|claude\|codex` |
+| Quote / route / prepare | `oracle_cli` |
+| Local sign | vault + loopback `signer_execute` (human nonce) |
+| All shipped EVM | `oracle-evm` — same vault, different chainId |
+| Your desk across your machines | `oracle-thin-client` / `oracle-tailscale` placeholders |
+
+## Do not absorb into public
+
+- Fleet SSH / Kanban / Orca / Pop-PC2
+- GitHub admin packs (Admin overlay only)
+- Someone else's Tailnet or thin-client `desk.json`
+- Generic unrestricted shell / desktop CUA on the signer box
+- House executor wallets
+
+## Rule
+
+If a feature makes the **crypto desk** better and stays fail-closed, take it.
+If it only exists to operate DEMI's machines, leave it on Admin Hermes.