grimoire

What this skill does

# Grimoire CLI Skill

This skill is the base operating playbook for Grimoire.

## When To Use

Use this skill when the task includes:

- install/setup of Grimoire tooling
- creating or editing `.spell` files
- syntax questions about DSL capability
- advisory (`advise`) authoring, debugging, and replay workflows
- setup/compile/validate/simulate/cast/resume workflows
- debugging spell compile/runtime failures

## Mandatory Loading Rules

All `references/` and `docs/` paths below are relative to this skill directory (`skills/grimoire/`). These rules are **required** — they solve syntax coverage gaps that cause authoring errors.

**STOP — read this first:** Do NOT search the codebase, grep for syntax patterns, or rely on memory for DSL syntax. The reference files bundled with this skill are the single source of truth. IMMEDIATELY use the Read tool on the files listed below before writing or editing any spell content.

1. For any `.spell` authoring/editing task — IMMEDIATELY read these files using the Read tool before doing anything else:
   - `references/syntax-capabilities.md`
   - `references/authoring-workflow.md`
2. For CLI flag details — IMMEDIATELY read using the Read tool:
   - `references/cli-quick-reference.md`
3. For any advisory task (`advise`, `advisors`, replay) — IMMEDIATELY read using the Read tool:
   - `docs/how-to/use-advisory-decisions.md`
   - `docs/explanation/advisory-decision-flow.md`
4. For local fork preview workflows — IMMEDIATELY read using the Read tool:
   - `references/anvil-cheatsheet.md`
   - `docs/how-to/simulate-on-anvil-fork.md`
5. For wallet setup and execution key flows — IMMEDIATELY read using the Read tool:
   - `docs/how-to/use-wallet-commands-end-to-end.md`
6. For RPC/signer/transaction diagnostics — IMMEDIATELY read using the Read tool:
   - `references/cast-cheatsheet.md`

## Installation Resolution

Select the first working invocation and reuse it for the session.

1. Global:
   - `npm i -g @grimoirelabs/cli`
   - command prefix: `grimoire`
2. No-install:
   - command prefix: `npx -y @grimoirelabs/cli`
3. Repo-local:
   - command prefix: `bun run packages/cli/src/index.ts --`

If one path fails, move to the next path automatically.

If `grimoire venue doctor ...` fails with `Unknown venue adapter "doctor"`, prefer repo-local invocation (`bun run packages/cli/src/index.ts`) or upgrade global CLI.

When using repo-local Bun execution, always keep the trailing `--` so Bun forwards flags to Grimoire instead of consuming them.

## Fast Start (Immediate Success Path)

Use this sequence before writing custom spells:

1. `<grimoire-cmd> --help`
2. `<grimoire-cmd> setup` (guided interactive execute onboarding)
3. `<grimoire-cmd> validate spells/compute-only.spell`
4. `<grimoire-cmd> simulate spells/compute-only.spell --chain 1`

If all three pass, proceed to spell authoring.

Setup security/runtime expectations:

- setup prompts for hidden passwords and never echoes input
- blank RPC input falls back to chain default public RPC
- setup may write `.grimoire/setup.env` unless `--no-save-password-env` is used
- CLI auto-loads nearest `.grimoire/setup.env` at startup without overriding existing env vars

## Authoring and Execution Policy

1. Read syntax references first (mandatory rule above).
2. Author/update spell.
3. Run `format` to canonicalize layout before validation.
4. Run `validate` (use `--strict` for advisory-heavy spells).
5. Fix errors/warnings and re-run until validation passes.
6. Run `simulate`.
7. Before venue metadata queries or value-moving runs, execute `venue doctor` for the target adapter/chain.
   - Example: `<grimoire-cmd> venue doctor --adapter uniswap --chain 1 --rpc-url <rpc> --json`
8. Before value-moving runs on EVM venues, verify endpoint and signer state with Foundry Cast quickchecks (`chain-id`, `block-number`, `balance`, `nonce`).
   - Do not apply Anvil/Cast checks to offchain venues such as `hyperliquid`.
9. For advisory steps intended for deterministic execution, record and then use `--advisory-replay <runId>` in dry-run/live cast.
10. If spell includes irreversible actions, require `cast --dry-run` before any live cast.
11. Ask for explicit user confirmation before live value-moving `cast`.
12. For cross-chain mode, require explicit per-chain RPC mappings:
   - `--rpc-url <sourceChainId>=<url>`
   - `--rpc-url <destinationChainId>=<url>`
13. For cross-chain Morpho actions, require explicit market mapping via:
   - `--morpho-market-id <actionRef>=<marketId>` (repeatable), or
   - `--morpho-market-map <path>`
14. For Morpho supply-only strategies, prefer `vault_deposit` / `vault_withdraw` (explicit vault address).
   - If vault address is missing, list candidate vaults and require user to pick one; never auto-select.
15. For Morpho market strategies (borrow/collateral/lend), require explicit `market_id` and use explicit actions:
   - `morpho_blue.supply_collateral(asset, amount, market_id)`
   - `morpho_blue.withdraw_collateral(asset, amount, market_id)`
16. Use bare `0x...` address literals in action token fields; quoted address-like strings trigger `QUOTED_ADDRESS_LITERAL`.
17. For Morpho doctor readiness checks, set wallet env explicitly (`GRIMOIRE_WALLET_ADDRESS` preferred, fallback `WALLET_ADDRESS`).
18. If a cross-chain run is left waiting, continue with `resume <runId>` (use `--watch` to poll settlement).
19. Never place passwords/private keys in agent prompts or inline command assignments.
20. Prefer keystore + `--password-env` over `--private-key` for dry-run/live casts.
21. Treat `.grimoire/setup.env` as plaintext secret material: keep local-only and rotate/remove when no longer needed.
22. For commands run outside the project tree, set `GRIMOIRE_SETUP_ENV_FILE=/abs/path/to/.grimoire/setup.env` when needed.

## Command Surface (Core)

- `init`
- `setup`
- `format`
- `compile`
- `compile-all`
- `validate`
- `triggers`
- `simulate`
- `cast`
- `venues`
- `venue`
- `venue doctor`
- `history`
- `log`
- `resume`
- `wallet` (`generate`, `address`, `balance`, `import`, `wrap`, `unwrap`)

Use `references/cli-quick-reference.md` for concise command signatures and safety-critical flags.

## Runtime Behavior Model

- One runtime semantics: preview first, commit only for execute paths.
- `simulate` and `cast --dry-run` are preview-only flows.
- Live `cast` can commit irreversible actions when policy and runtime checks pass.
- `simulate` supports explicit `--rpc-url`, with precedence: `--rpc-url` -> `RPC_URL_<chainId>` -> `RPC_URL`.
- Phase 1 cross-chain execution uses two-spell orchestration (`--destination-spell`) with one logical run id and resume support.
- Use `triggers <spell>` to discover stable handler ids natively before targeted execution.
- `simulate` and `cast` support selected-trigger execution via `--trigger-id`, `--trigger-index`, and legacy `--trigger`.
- For multi-handler spells, prefer `--trigger-id`; `--trigger` is label-based and can be ambiguous.
- Cross-chain `simulate` / `cast` must forward the same selected trigger into per-chain execution.
- In `--json` mode, parse stdout only; progress and spinner output can still appear on stderr.

## Query Functions (price / balance / apy / metric)

**Always prefer query functions over advisory for structured data fetching.** These are deterministic, fast, and don't require LLM calls.

- `price(BASE, QUOTE[, SOURCE])` — live token price via query provider (requires Alchemy RPC URL)
- `balance(ASSET[, ADDRESS])` — on-chain token balance via RPC (any RPC URL)
- `apy(VENUE, ASSET[, SELECTOR])` — venue-backed APY surface (for example Aave and Morpho)
- `metric(SURFACE, VENUE[, ASSET[, SELECTOR]])` — generic protocol metric surface
- Selector guidance:
- market/vault id selector: `apy(morpho, USDC, "wbtc-usdc-86")`
- vault selector (Morpho): `metric("vault_net_apy", morpho, USDC, "vault=0xVaultAddress")`
- Morpho `vault_apy` / `vault_net_apy` require explicit selector; do not rely on implicit defaults.
- key/value selector: `metric("