franalgaba__grimoire/docs

Grimoire Documentation

This documentation follows the Diátaxis framework. If you're new, start with the execution mode you want to use.

Start here

Grimoire uses the same spell syntax in both environments. The differences are guarantees and tooling.

• VM mode (in-agent, best-effort): run spells inside an agent session with snapshot data and no adapters. For quick protocol prototyping, use venue CLI snapshots. Start with Getting started and Run spells in VM mode.
• Deterministic runtime (CLI): compile, simulate, and cast with adapters and state persistence. Start with Getting started and Run spells with the CLI.

If you want the full comparison, see Execution modes.

Advisory steps (**...** and advise) call Pi when a model is configured (spell model, CLI model/provider, or Pi defaults). If no model is available, the runtime uses the spell fallback. See CLI reference and Pi advisory execution spec.

Suggested flow: explore in VM → record advisory in CLI simulate → replay deterministically in cast. See Run spells with the CLI.

If you are contributing to the repo, see CONTRIBUTING.md and Run tests and checks.

Updating (user view)

• Update the CLI: npm i -g @grimoirelabs/cli@latest
• Use npx for latest without install: npx -y @grimoirelabs/cli@latest <command>
• Update packages in your project: npm i @grimoirelabs/core@latest @grimoirelabs/venues@latest
• Update the VM skill: re-install with npx skills add https://github.com/franalgaba/grimoire (or copy skills/grimoire-vm into your agent skills directory again)

Tutorials

Step-by-step guides for newcomers.

• Getting started (choose a mode)
• Write your first spell
• Execute a spell with venues

How-to guides

Task-focused recipes.

• Run spells with the CLI
• Run spells in VM mode
• VM quickstart (snapshot-driven)
• Transition to deterministic execution
• Configure slippage and constraints
• Bridge with Across
• Add and organize spells
• Add a new venue adapter
• Build spells programmatically
• Run tests and checks
• Publish packages

Reference

Authoritative specifications.

• Spell syntax reference
• Grimoire DSL spec
• Core API reference
• Venues package reference
• CLI reference
• IR schema reference
• Action constraints reference
• Grimoire VM spec
• Grimoire VM conformance
• Pi advisory execution spec

Explanation

Background and design rationale.

• System architecture
• Compiler pipeline
• Venue adapter model
• Approval and multi-tx flows
• Execution modes
• Business model modes
• Grimoire extensions spec (draft)