@oracle-agent/oracle 0.24.1 → 0.24.3

package/dist/assets/skills/defi-protocol-pmf-assessment/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: defi-protocol-pmf-assessment
+description: Use when scoping or costing a new DeFi protocol on a chain.
+version: 1.0.0
+author: agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [defi, pmf, market-analysis, protocol-design, cost-modeling, defillama]
+    related_skills: [evm-contract-research, self-custodial-onchain-execution, verification-gate]
+---
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. Works on every shipped EVM chain, not only RH/HL.
+
+
+# DeFi protocol PMF assessment
+
+Use when the question is **"should we build a protocol here, and what would it cost"** —
+not "how does this contract work" (that's `evm-contract-research`). Triggers: "is there
+PMF for X on chain Y", "what gap should we fill", "what would it cost to launch", or a
+category diff showing absent protocol categories.
+
+The deliverable is **a specific buildable protocol with a budget**, not a research memo.
+See "Deliver a protocol, not a monitor" below — this is the failure mode that gets
+corrected most.
+
+## The core discipline
+
+> **An absent category is not an opportunity. Find the binding constraint.**
+
+DefiLlama will happily show 49 missing categories on a young chain. That looks like 49
+opportunities and is usually **one repeated fact** — the chain is small, and every gap
+hits the same wall. Identify that wall first; it determines which (if any) protocol is
+actually buildable and at what size.
+
+Constraints that repeatedly turn out to be binding:
+
+| Constraint | How to measure | Kills |
+|---|---|---|
+| **Hedging depth** | DEX liquidity + perp OI, take ~10% as safely tradeable | Options, market making, anything delta-hedged |
+| **Yield source count** | Count distinct real sources and the spread between them | Yield aggregators, routers, optimizers |
+| **Average position size** | token `holders_count` vs float value | Any per-position product |
+| **Incumbent concentration** | top protocol's share of category TVL | Lending, DEX, launchpads |
+
+## Step 1: category diff, then de-duplicate
+
+Pull `https://api.llama.fi/protocols` (~8MB, filter in Python, never print raw). For each
+protocol read `chainTvls['<Chain>']`. Build category rollups for the target chain and two
+mature comparators (Base, Arbitrum). Diff into ABSENT / DEAD (<$100k) / HEALTHY.
+
+**Traps that produce a wrong headline number:**
+
+- **Curators double-count.** "Risk Curators" (Steakhouse, Gami) and yield wrappers
+  (Spark Savings) sit *on top of* a lending market's deposits. Summing all entries gave
+  $784.4M against a real chain TVL of $422M. Never add a curator row to the venue it
+  curates; reconcile sum-of-parts against `api.llama.fi/v2/chains` and explain the gap.
+- **`CEX` is a false positive.** Those rows are exchange proof-of-reserve wallets, not
+  deployable protocols. Same for `Chain` and `Bug Bounty`. Strike them before ranking.
+- **High protocol counts are mirages.** 30 DEXes where Uniswap holds 92.6% means one DEX
+  and 29 forks splitting scraps. Always report the top-1 / top-2 concentration next to
+  the count.
+- **Derivatives-by-chain breakdown is paywalled.** `overview/derivatives/<chain>` returns
+  an upgrade notice. Say "unknown", do not infer.
+
+## Step 2: reconcile "idle capital" before pitching it
+
+The most seductive and most wrong finding is "$X hundred million sitting idle, just
+deploy it." Verify by tracing the actual balances.
+
+**Worked correction (RH 4663):** stablecoin supply was $338.7M and the main vault held
+only $23.7M, which read as "93% idle." Wrong. The reconciliation:
+
+```
+supplied into lending markets   $306.3M
+borrowed back out by loopers    $276.5M
+-> net retained in core          $29.9M   <- matches on-chain balance
+vault idle buffer                $23.7M
+```
+
+The capital was **circulating inside a leverage loop** (borrow stable, swap to collateral,
+redeposit, borrow again). The same dollars counted repeatedly. There was no idle pile.
+
+Method: read `balanceOf` on the lending core and the vault directly, then check that
+`supplied - borrowed` equals the core's real balance. If it reconciles, the "idle" money
+is fully deployed and the thesis is dead.
+
+## Step 3: size demand from holders, not TVL
+
+TVL tells you what whales did. **Holder counts and average position tell you what product
+shape is possible.**
+
+For each candidate asset pull `/api/v2/tokens/{addr}` → `holders_count`, `total_supply`,
+then value the float at the live oracle price.
+
+**Worked example (RH 4663 tokenized equities):**
+
+| Asset | Holders | Float | Avg position |
+|---|---|---|---|
+| NVDA | 33,759 | $4.36M | **$129** |
+| AAPL | 29,298 | $1.56M | **$53** |
+| TSLA | 22,728 | $1.58M | **$70** |
+
+This single table killed an options build: **one NVDA option contract costs $216 — more
+than the average holder's entire NVDA position.** Any per-position product is dead on
+arrival. The product must be *pooled* and work at $50-150 tickets.
+
+Run this check **before** designing anything. It is cheap and it is decisive.
+
+## Step 4: restructure to fit the constraint (the highest-leverage move)
+
+Once the binding constraint is measured, ask what product shape needs **less** of it.
+Capital-efficiency structuring routinely moves the ceiling by an order of magnitude.
+
+**Worked example — same insight, three shapes, against a measured $425k hedging ceiling:**
+
+| Product | Hedge needed per $1M | Max size |
+|---|---|---|
+| Direct options book | $1,000,000 | $425k |
+| Covered-call vault | $300,000 | $1.4M |
+| **Principal-protected note** | **$31,300** | **$13.6M** |
+
+The note funds convexity out of *yield* (3.13%) rather than principal, so the hedging
+requirement drops ~32x and the constraint that made options unviable becomes irrelevant.
+
+Two structural rules that fell out of the same build:
+
+- **A cash-settled call cannot be fully collateralized** — unbounded upside. Cap it and
+  it becomes a call spread; the writer locks `(cap - strike) x size`, which is ~10x less
+  than a cash-secured put locks, and the vault is provably always solvent.
+- **Full collateralization removes liquidations, which removes cascade risk.** On a 24/7
+  chain with an underlying that halts (equities, RWAs), no-liquidation is the design that
+  makes the asset underwritable at all.
+
+## Step 5: cost it — separate BURN from DEPLOYED
+
+**The error to avoid: presenting deployed capital as spend.** These are different numbers
+and conflating them overstates the ask massively.
+
+| Bucket | Meaning |
+|---|---|
+| **Burn** | Audit, legal, frontend, ops. Gone. Never comes back. |
+| **Deployed** | Seed capital, market-maker float. Yours, at risk, recoverable. |
+
+Report as: "**~$60k of real spend, plus ~$300k of your own capital deployed. Total cash
+touched ~$360k; total lost ~$60k.**"
+
+**Gas is not a line item on a modern L2.** Measure it, then say so and move on. RH 4663
+at 0.0215 gwei with ETH ~$1,864: a full 6-contract protocol deploy cost **$0.35**, and a
+year of weekly rebalances plus monthly settlements cost **$2.00**. Do not pad a budget
+with gas estimates; `cast gas-price` and the explorer `/stats` coin_price give the real
+figure in one call.
+
+**Audit dominates the burn** (~2/3). Two audits (one firm + one competitive contest) is
+the bar for anything holding retail principal. Engineering is $0 only when the agent
+fleet builds it — say so explicitly, because human engineering for the same scope is
+$150k-400k and that dependency is real.
+
+**Legal is a gate, not a line item.** For anything resembling a structured product,
+principal guarantee, or yield promise, spend $5-10k on a preliminary read **before**
+committing to audit. If counsel says "regulated security," the cost is not the fee, it
+is the project. Sequence: legal read -> audit -> deploy -> seed -> scale.
+
+## The budget-constraint cascade
+
+Budget determines architecture more than ambition does. Work down this ladder:
+
+| Budget | What is possible |
+|---|---|
+| Full (~$60k+) | Custody user funds. Vaults, lending, options, anything with a balance. |
+| **No audit** | **Cannot custody user funds — full stop.** Prepare-only, read-only, or immutable-no-funds contracts. |
+| ~$0 | Routers/aggregators returning unsigned calldata; immutable no-owner primitives; indexers and data products. |
+
+**Unaudited + holds retail principal = do not ship.** When the budget rules out an audit,
+pivot to a **prepare-only** design: quote, compare, return unsigned calldata, let the
+user's wallet sign. A bug then produces a bad quote, not a theft. This is the same custody
+posture as `self-custodial-onchain-execution` — reuse it.
+
+An immutable, owner-less, fund-less contract (a calendar, a math library, a registry) is
+also safe to ship cheaply and is often the durable public good in the space.
+
+**Venue price dispersion is the cheap gap.** Before concluding a low-budget chain has
+nothing to build, measure the same asset's price across every venue at the same instant
+(CLOB spot vs each AMM). On RH 4663 the median dispersion across 19 tokenized equities
+was **26.4bp**, with outliers at 105-107bp — retail trading thin AMM pools while a
+zero-fee CLOB sat unrouted. A prepare-only best-execution router monetizes that with no
+custody and therefore no audit gate.
+
+### Widen the venue set before declaring a ceiling — one chain is not the market
+
+A constraint measured on a single chain is often an **artifact of the sample**, not a real
+ceiling. The RH-only hedging depth read **$425k**, which killed options, structured notes,
+and market making in turn. Adding the other venues that list the same assets moved it past
+**$1B**. Same product, same insight, 2400x the addressable depth.
+
+So when a constraint kills every idea on one chain, **enumerate the other venues carrying
+that asset class before concluding the product is unviable.** For on-chain equities the
+live venue set (all verified this session) is in
+`references/onchain-equity-venue-registry.md` — Hyperliquid HIP-3, Arcus perps + CLOB spot,
+RH Uniswap, Solana xStocks, TON.
+
+**Never conclude a venue lacks an asset class from one endpoint.** Hyperliquid's core
+`metaAndAssetCtxs` returns 232 markets and **zero** equities, which reads as "crypto-only."
+It is wrong: equities live exclusively in HIP-3 builder dexs at ~$1.49B/24h. Two failure
+modes produce the same silent zero — querying the default namespace, and a naive symbol
+filter that misses `dex:TICKER` namespacing. Dump the raw market-name list and read it
+before filtering. This exact mistake required a user correction; treat a zero result on a
+venue you *expect* to have the asset as a bug in your query until proven otherwise.
+
+### Gate cross-venue comparisons on liveness or the number lies
+
+Dormant venues keep serving their last mark. Those stale prices are indistinguishable from
+live quotes in the API response and they **inflate every dispersion statistic**. Measured
+across 9 HIP-3 builder dexs plus Arcus and RH:
+
+| Sample | Median cross-venue spread |
+|---|---|
+| All venues (naive) | 96.1bp |
+| **Live venues only** | **43.8bp** |
+
+Five of nine builder dexs had $0 24h volume. Including them more than doubled the apparent
+opportunity — i.e. it would have doubled the pitch. Filter on 24h volume **per venue and
+per market**, and reject crossed books (bid > ask, seen live on a CLOB spot feed: either a
+stale indexer snapshot or a genuinely uncrossed thin book — both unquotable).
+
+Report the gated number as the headline and mention the ungated one only as the trap you
+avoided. A liveness gate is a **correctness requirement, not polish**: quoting a dormant
+venue is the single most likely way a routing product lies to a user.
+
+**Then ask whether the remaining spread is real.** Perp mark vs spot last vs oracle mid
+*should* differ — that is basis and instrument difference, not mispricing. Before pitching
+a dispersion number as an execution edge, decompose how much survives once you compare
+like instruments. If most of it is basis, the product is a data viewer, not an edge. Put
+this question to the planner explicitly rather than assuming the favorable reading.
+
+## Deliver a protocol, not a monitor
+
+**Correction from a live session — do not repeat it.** After measuring that every gap on
+a chain hit the same depth ceiling, the answer given was "I'd rather hand you a monitor
+than a protocol." The user pushed back: *"so its not a protocol? we want make a protocol
+thats product market fit."*
+
+Analysis paralysis reads as evasion. When the ask is a protocol:
+
+- Constraints **shape** the product, they do not veto it. Restructure (Step 4) before
+  concluding "not viable."
+- Never substitute a dashboard, watcher, or "let's instrument and wait" for the buildable
+  thing. Offer that only as an *addition* to a named protocol, never in place of one.
+- End with a **named protocol, a concrete mechanism, and a budget** — then the caveats.
+  Caveats after the answer, never instead of it.
+- If the honest conclusion really is "don't build," say that in one line and immediately
+  name what you *would* build instead at the same budget.
+
+## Extend the existing product before inventing a new one
+
+**Second correction from the same session.** After landing on a cross-chain best-execution
+router, it was framed as a brand-new protocol with Hyperliquid as the "primary venue." The
+user corrected: *"not primary venue but have the multichain thesis oracle has."*
+
+Before scoping a greenfield protocol, check whether the user **already owns a product whose
+thesis covers it**. Here Oracle already had a multichain routing desk with a documented
+best-execution law (rank net-of-cost, report runners-up with `improvementBps`, honest
+capability tiers, `unknown` for anything not live-read). The correct framing was *a new
+asset class inside an existing product*, not a new protocol.
+
+Two concrete rules that fall out:
+
+- **Load the user's own product skills before designing.** If skills exist describing their
+  desk, router, or execution law, read them and inherit the vocabulary and invariants
+  verbatim. Inventing a parallel ranking scheme next to an existing one is duplicated
+  surface the user has to reconcile.
+- **In a multi-venue router, no venue is "primary."** Naming one primary reintroduces the
+  single-venue dependency the router exists to remove. Every venue is a source with a
+  capability tier; the deepest venue is still just a source that can fail into `failed[]`.
+
+## Report to the stated audience, and plainly on request
+
+When the user asks for it simply — *"give me the tldr like im a retard"* — drop every
+domain term and lead with the decision. Numbered short lines, concrete dollar figures, one
+bolded takeaway each, and a single closing question. No tables, no bp, no protocol names,
+no hedging paragraphs. Re-expand to full analytical depth on the next substantive question;
+the request is per-message, not a permanent register change.
+
+## Reporting standard
+
+- Lead with the number or the verdict. Tables over prose.
+- Mark every figure's provenance: live probe vs API vs estimate. Cost estimates for audit
+  and legal are **market-rate guesses**, not measurements — label them as such while
+  chain data stays labelled verified.
+- State confidence explicitly (high / moderate / low / unknown) and say *why* it is not
+  higher.
+- Volunteer corrections to your own earlier claims the moment you find them. Two happened
+  in one session (the idle-capital misread and the burn-vs-deployed conflation); catching
+  them yourself is worth more than a clean-looking narrative.
+
+## Pitfalls
+
+- **Chain age distorts everything.** A 5-week-old chain's TVL trend is not adoption. Pull
+  `v2/historicalChainTvl/<chain>` and the DEX volume chart, and compare last-14d vs
+  prior-14d. TVL rising while volume falls 28% means mercenary capital arriving as users
+  leave — say that, do not report the TVL alone.
+- **Verify the incumbent is really absent before claiming a gap.** A category showing zero
+  can still be served by a venue DefiLlama does not track, or by an aggregator already
+  deployed. Check before building.
+- **A market that exists but is unused is a *rejected* gap, not an unbuilt one.** Equity
+  collateral markets existed on the chain's main lender and held $2,789 total. Capital had
+  already looked and refused. That is much stronger evidence than an empty category, and it
+  means you must explain *why the refusal was wrong* before building the same thing.
+- **Check whether the asset issuer already solved it.** Tokenized-equity contracts on RH
+  4663 are `BeaconProxy` → a `Stock` implementation exposing `uiMultiplier` /
+  `updateMultiplier` / `effectiveAt` — a scheduled split-rebase. Corporate actions were
+  never a gap. The same read surfaced `pause()`, `pauseOracle()`, and `adminBurn()`, so
+  any protocol holding those tokens inherits issuer freeze/burn risk: put it in the risk
+  disclosure. Read the implementation ABI behind a proxy before scoping work around it.
+- **`forge` internal-library reverts need an external harness.** `vm.expectRevert` on a
+  library's internal function fails with `call didn't revert at a lower depth than
+  cheatcode call depth`, because the call is inlined. Wrap it in a small external harness
+  contract and call through that. Not a code bug; only a test-harness shape.
+- **Prototype to measure, not to ship.** Writing one real contract plus its tests is often
+  the cheapest way to get a truthful gas number and validate the core math. 512 fuzz runs
+  proving a solvency invariant cost minutes and de-risked the whole design.
+
+## References
+
+- `references/rh-4663-options-pmf-worked-example.md` — the full worked assessment on
+  Robinhood Chain 4663: category diff numbers, the leverage-loop reconciliation, holder
+  and float tables, the hedging-depth measurement, the three-shape capital-efficiency
+  comparison, the HoodNotes design, and the measured deploy-cost table.
+- `references/onchain-equity-venue-registry.md` — every venue carrying on-chain equities
+  (Hyperliquid HIP-3, Arcus perps + CLOB spot, RH Uniswap, Solana xStocks, TON) with
+  keyless endpoints, the Arcus off-hours band/margin regime worth copying, the empirical
+  proof that an off-hours funding lock kills the weekend-basis trade, and the dormant-venue
+  list. Read this before scoping anything multi-venue.

package/dist/assets/skills/evm-contract-research.md

@@ -22,6 +22,11 @@ description: Use when researching or verifying EVM contracts, routers, factories
 - Proxy with unverified implementation
 
 ## Trusted routers (verify on-chain, don't assume)
-- Uniswap V2 Router: 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D (Ethereum)
-- Uniswap V3 Router: 0xE592427A0AEce92De3Edee1F18E0157C05861564
-- UniversalRouter: 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD
+
+Ethereum is not the only chain. Resolve the router on the **token's home chain**.
+
+- Uniswap V2 Router (Ethereum): `0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D`
+- Uniswap V3 SwapRouter (Ethereum): `0xE592427A0AEce92De3Edee1F18E0157C05861564`
+- UniversalRouter (Ethereum): `0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD`
+
+On Base / Arb / OP / Polygon / BSC / Avalanche / HyperEVM / Abstract / Stable / RH, look up that chain's Uniswap / Pancake / Aerodrome / venue router from live data (`dex_token`, `scan_token`). Never paste an Ethereum router onto another chainId.

package/dist/assets/skills/multi-venue-prepare-only-ranking/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: multi-venue-prepare-only-ranking
+description: Use when building prepare-only cross-venue rank surfaces.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Multi-venue prepare-only ranking
+
+Class of product: compare quotes across venues, rank honestly, prepare unsigned artifacts only. Worked repo: `/home/demi/work/oracle-equities` (298 offline tests as of 2026-08-04).
+
+## Product law
+
+- Prepare-only. No keys, no sign, no broadcast in the public package.
+- Rank on **net received after fees/gas/impact** when costs are known; otherwise `rankedOn: "gross"` and say so.
+- **Unknown is not zero.** Missing gas/impact/funding => field `null` and `costAccounted: false`.
+- **Adapters report truth. Liveness filters.** Never "repair" crossed books or drop dormant venues inside an adapter.
+- **Winner ≠ actionable.** Always emit `bestPreparable` (tier `prepare`) separately from overall winner.
+
+## Three outcome buckets
+
+| Bucket | Meaning |
+| --- | --- |
+| ranked / survivors | answered + passed integrity |
+| failed[] | did not answer |
+| excluded[] | answered but untrustworthy (`dormant-venue`, `crossed-book`, `stale-quote`, `stale-oracle`) |
+
+Do not collapse excluded into failed.
+
+## Pipeline shape
+
+```
+adapters -> normalize -> liveness -> (marketHours, funding, bridge) -> rank -> prepare
+```
+
+Default rank: **homogeneous** instrument tables (spot vs spot, perp vs perp).
+Horizon mode: heterogeneous + funding carry labeled `confidence: "estimate"` (never upgrades `costAccounted`).
+
+Session states: `core` / `extended` / `dark` (not a single 04:00-20:00 lit window). DST and holidays from fixtures, not host tzdata.
+
+Search `bestPreparable` across ALL scored survivors, not only the instrument-segmented pool (homogeneous mode can rank perps and drop the spot prepare route from `ranked`).
+
+## Fixed-point money
+
+All prices/sizes/rates: `{ mantissa: bigint, scale: int }`. No JS floats in contract fields.
+
+Venue JSON often stores IEEE doubles (`1.25e-5`). Provide **one** audited crossing module that expands exponent notation to plain decimal strings before parse. Missing source -> `null`; measured zero stays zero.
+
+## Fixture discipline
+
+1. Freeze live venue responses into `fixtures/` before Wave 1.
+2. Offline tests only against fixtures; live probes in `scripts/` only.
+3. **Re-derive goldens from the frozen capture** before pinning (plan "56 assets / 43.8bp" became ~45 / ~39bp on the actual snapshot). Prefer bands when the capture drifts.
+4. If tier is `prepare` but capture has no price/reserves/sqrtPriceX96: capture state first or demote tier. Do not invent mids.
+
+### RH Uniswap V3/V4 price capture (chain 4663)
+
+When pools are address+liq only:
+
+- RPC: `https://rpc.mainnet.chain.robinhood.com` (chainId `0x1237`)
+- V3: `slot0()` `0x3850c7bd` on pair address
+- V4: StateView `0xF3334192D15450CdD385c8B70e03f9A6bD9E673b` `getSlot0(bytes32)` `0xc815641c`
+- V4 token0: USDG is token0 iff `int(USDG) < int(equity)` (currency0 < currency1). Without this, GOOGL/AMZN/SPY/TSLA invert by ~1e19.
+- Gas observed ~0.0215 gwei; gas in quote units still needs an ETH price (else leave gas null).
+
+## Swarm recovery pitfalls
+
+- Before writing into a recovered worktree: scan for live `hermes` workers whose cwd is the repo. Stand down if Wave N is still running.
+- OAuth-dead swarm summaries can hide commits and green uncommitted leaves. Check `git log` / `git status` / transcript tails.
+- Spine edits (fixture loader maps) must be atomic: FILES + VALIDATORS + getter + test in one commit before leaf waves.
+
+## CLI surface pattern
+
+```
+venues                         # inventory + liveness tallies
+quote <TICKER> --size --horizon --json
+prepare <TICKER> --recipient 0x...   # unsigned only; refuse stale quotes
+```
+
+## Symbol normalization traps
+
+- Namespace strip (`xyz:NVDA`), `-USD` strip, lowercase `x` suffix only on allowlist.
+- Fail closed on ambiguity (`{ ambiguous: true, candidates }`). Never guess.
+- Real trap: SKHX vs SKHY must not alias; LIT can be multi-asset-class contested.
+
+## Related umbrellas (user-owned; adopt to merge)
+
+- `oracle-best-execution` — swap/bridge UX copy for net-of-cost ranking
+- `parallel-build-swarm-file-ownership` — disjoint leaf ownership + spine rules
+- `planner-builder-profile-pipeline` — fable plan / builder execute / verify
+
+Detail: `references/oracle-equities-2026-08-04.md`.

package/dist/assets/skills/oracle-access-control/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: oracle-access-control
+description: Sender gating and operator wallet boundaries for Oracle.
+---
+
+> 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 access control
+
+## Two layers of authorization
+
+1. **Sender gate** — who can talk to this instance at all
+2. **Grant gate** — what an authorized sender may do (chain, spend cap, TTL)
+
+Never confuse them. A valid grant does not authorize an unauthorized sender.
+
+## Private instance model
+
+The owner's Telegram/Discord ID is hardcoded in the SOUL. All other senders
+are refused immediately:
+
+"Oracle is self-hostable. Install your own instance: npm install -g @oracle-agent/oracle"
+
+No read access. No prepare access. No negotiation.
+
+The shipped package SOUL is owner-agnostic ("you are the owner"). DEMI's
+instance override lives at `~/.hermes/profiles/oracle/SOUL.md` with the
+owner's Telegram ID hardcoded.
+
+## Self-host model
+
+```
+npm install -g @oracle-agent/oracle
+oracle bootstrap
+oracle auth login claude
+oracle init --apply
+oracle chat
+```
+
+Full capabilities with their wallet, their keys, their models. Oracle
+ships its own agent runtime — Hermes is optional. `oracle chat` auto-detects
+Hermes on PATH; falls back to standalone.
+
+## Address-agnostic arming
+
+`fromAddress` in prepare/arm pathways is caller-supplied. Any sender can arm
+a trade to any address. The unsigned transaction sits in `awaiting_signature`
+until the target wallet signs with its private key. The wallet key is the
+real gate.
+
+## Operator wallet boundary
+
+`oracle_control_arm`, `oracle_control_confirm`, and any house/executor wallet
+tool are owner-only. The operator wallet is never shared with other senders.
+
+## Tool safety gates (SOUL-level)
+
+These persistent-state tools are gated by the SOUL — never call them without explicit owner direction:
+- `skill_manage` — creates, edits, deletes skills. Refuse unless owner names exact skill + action.
+- `cronjob` — creates, updates, removes scheduled jobs. Refuse unless owner names exact job + schedule.
+- `memory` — writes to persistent memory. Refuse unless owner states a preference or fact to save.
+
+Both the private-instance SOUL and the npm-distributed SOUL include these gates.
+Ambiguity = ask. Never create/edit/delete speculatively or as a "cleanup" pass.
+
+## Config key-path hygiene
+
+Signer material must not live in readable config files. Use `oracle sign`
+/ the local vault, or a 0600 secret file the operator owns. Config should
+point at that file path, never embed a key.

package/dist/assets/skills/oracle-action-arming/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: oracle-action-arming
+description: Use when arming Oracle actions via oracle_control_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 action arming
+
+Two-step control-plane workflow for armed execution actions. Complements
+`oracle-action-semantics` (vocabulary) and `oracle-grants` (authorization bounds).
+
+## Two-step flow
+
+1. **Arm** — `oracle_control_arm` creates an action in `pending_confirmation`.
+2. **Confirm** — `oracle_control_confirm(id, intentHash)` activates it.
+
+Until confirmed, the action is inert. After confirmation: `state: "active"`,
+`actionMode: "execute"`.
+
+## Schema gotchas
+
+- `trigger.type` MUST be a non-empty string. Fails with `trigger.type must be a non-empty string` otherwise.
+- `policy.caps` MUST be a decimal number (e.g. `0.1`), NOT an object. Fails with `policy.caps must be a decimal` otherwise.
+- `intent` is an open object — include `action`, `token`, `chainId`, `amountEth`/`amount`, `slippageBps`, `router`, `recipient`, `symbol`.
+
+## Common trigger shapes
+
+### Liquidity trigger ("buy when it's live")
+```json
+{
+  "type": "liquidity",
+  "chainId": 4663,
+  "token": "0x...",
+  "kind": "liquidity",
+  "condition": "any_pool_with_liquidity"
+}
+```
+
+### Price trigger ("buy when it hits X")
+```json
+{
+  "type": "price",
+  "chainId": 8453,
+  "token": "0x...",
+  "direction": "above",
+  "threshold": 0.05,
+  "metric": "px"
+}
+```
+
+## Full example: armed liquidity snipe
+
+```
+oracle_control_arm({
+  trigger: {
+    type: "liquidity",
+    chainId: 4663,
+    token: "0xc72F232a6869e6CF34dC06129AfFD07F8a2a246A",
+    kind: "liquidity",
+    condition: "any_pool_with_liquidity"
+  },
+  intent: {
+    action: "buy",
+    symbol: "MANCER",
+    token: "0xc72F232a6869e6CF34dC06129AfFD07F8a2a246A",
+    chainId: 4663,
+    amountEth: 0.1,
+    slippageBps: 100,
+    router: "uniswap",
+    recipient: "0xYOUR_WALLET"
+  },
+  policy: {
+    caps: 0.1,
+    maxSpendEth: 0.1,
+    maxGasGwei: 500,
+    priorityFeeGwei: 50
+  },
+  maxExecutions: 1,
+  expiresAt: "2026-08-07T23:59:59Z"
+})
+→ oracle_control_confirm(id, intentHash)
+```
+
+## Pre-arm checklist
+
+1. Resolve exact chain + token (multi-chain scan if unknown).
+2. Verify executor health for target chain.
+3. Require exact amount, slip, recipient, expiry from user.
+4. Present compact confirmation card before confirming.
+5. One-shot default; recurring needs explicit user request.
+
+## Post-arm
+
+- Action fires when trigger condition met, up to `maxExecutions` times, until `expiresAt`.
+- Every execution re-quotes + re-checks grant at sign time and broadcast time.
+- Use `oracle_action_list` / `oracle_action_status` to inspect.
+- Use `oracle_action_cancel` to cancel.