# The Spellbook

Cantrip is a small runtime for entities summoned from language. This page holds
the vocabulary as a learnable system. You can read it as an operator deciding
whether to use Cantrip, or as a Familiar trying to understand the place you have
been summoned into. The words mean the same thing in both readings; the rituals
at the end of each section work the same way for both readers.

## Cantrip

A cantrip is a reusable value. It binds an LLM, an identity, and a circle into a
summoning. Constructing a cantrip with `Cantrip.new/1` does not start anything;
it produces the configured shape that a summoning will instantiate. Casting a
cantrip with `Cantrip.cast/3` summons one entity into the bound circle, runs it
through its turns, and returns the result, an updated cantrip value, the loom of
what happened, and termination metadata. Summoning a cantrip with
`Cantrip.summon/1` produces a supervised process that stays alive across many
sends, accumulating loom and medium state.

*Verify it.* Construct a cantrip and inspect it. Cast it twice and observe that
the returned `next_cantrip` carries forward runtime configuration. Summon a
code-medium cantrip, `Cantrip.send/3` to it twice, and the second send can read
bindings left by the first.

## Identity

Identity is who the entity is: the system prompt and model-facing options. It
is immutable. The cantrip's identity is bound at construction; each summoning
inherits it. Identity does not change across a session. What changes is the
loom, the bindings, the conversation history. The entity remains itself.

*Verify it.* Read the identity off any cantrip value with `cantrip.identity`.
Cast twice and confirm the identity is the same value both times.

## Medium

A medium determines the shape of thought inside the circle. Three are built in.
Conversation is tool calls only: the LLM speaks, chooses tools, and the host
executes the named gates. It fits interpretation, judgment, naming, and voice.
Code is sandboxed Elixir evaluation, with persistent bindings across turns and
gates available as closures. The default runs in a port-isolated child BEAM;
wards can select Dune or trusted unrestricted host evaluation. It fits
composition: gathering, transforming, branching, and fanning out. Bash runs one
shell command per turn in an OS-sandboxed subprocess, with declared gates
projected onto `PATH`. It fits work whose natural surface is command invocation.

*Verify it.* In a code-medium turn, bind a variable; in the next turn, read it
back. In a conversation-medium turn, call `done` with an answer and observe that
the cast terminates. In a bash-medium test under `Mix.env() == :test`, set
`medium_opts: %{sandbox: :passthrough}`, run `echo hello`, and observe stdout in
the next turn's observation.

## Gates

Gates are the authority the entity can exercise. They are named (`done`,
`read_file`, `list_dir`, `search`, `mix`, `compile_and_load`, `echo`) and
parameterized. Calling a gate produces an observation that the entity reads as
data on its next turn. A failed gate returns `is_error: true` with a structured
message; the entity reads the failure and adapts. Errors are observations, not
exceptions.

*Verify it.* Declare a circle with `read_file` and call `read_file.(path: ".")`
on a directory path; observe the structured error in your next turn. Call
`done.(answer)` and observe that the final answer is returned to the caller and
recorded in the loom.

## Wards

Wards are runtime constraints. They bound turn count (`max_turns`), recursion
depth (`max_depth`), sandbox choice, Mix task allowlist, hot-load module
allowlist, child-spawn policy, and other operational limits. Wards compose when
a child cantrip is cast from a parent code-medium turn: numeric wards tighten
with `min` (a child can only narrow), boolean wards tighten with `or` (a child
can only require more), and passthrough ward data remains explicit policy for
the gate or medium that enforces it. The runtime enforces wards. They are the
shape of the body the entity inhabits, not policy the entity is asked to
respect.

*Verify it.* Cast a cantrip with `max_turns: 1` on a task that needs two turns
and observe truncation with `meta.terminated == false`. Declare
`child_medium_allowlist: [:conversation]` and try to construct a code-medium
child; observe the structured rejection.

## Circle

The circle holds it all together: medium, gates, wards, and medium options. It
is the bounded place where the summoning happens. Constructing a cantrip without
a medium, without a `done` gate, or without a truncation ward fails validation;
you cannot summon an entity into an unbounded place.

*Verify it.* Try `Cantrip.new/1` with `circle: %{type: :code, gates:
[:read_file]}`. Observe the validation error naming what is missing.

## Loom

The loom is the durable record of every turn the entity and its children have
taken. It is the entity's autobiography. With JSONL or Mnesia storage, the loom
persists across summonings: re-summon the cantrip against the same loom storage
and the prior turns are available as `loom.turns`. The loom is append-only:
folding shrinks what the model sees on the next call but never deletes a turn.
Forking with `Cantrip.Loom.fork/4` branches a new trajectory from any prior
turn, restoring sandbox bindings to the fork point.

*Verify it.* Cast against a cantrip with `loom_storage: {:jsonl,
"tmp/loom.jsonl"}`; the file contains one line per event. Summon the same
cantrip against the same loom path; the previous turns appear in `loom.turns` of
the next cast. For the production Familiar path, construct it with the same
workspace `root` twice; the root-derived Mnesia table is reused, and the second
summoning sees the first summoning's turns through `loom.turns`. To verify
folding, set a very low folding threshold and take enough turns to trigger it.
The following turn can inspect `folded_summary` for the compressed view and
`loom.turns` for the complete append-only record; folding changes the prompt
projection, not the loom.

## Entity

An entity is what arises when a cantrip is cast or summoned: a process whose
behavior is the pattern across the turns of the loom. The entity is not the LLM.
The LLM is one substrate the runtime calls; the identity, circle, and trajectory
are the shape that makes the entity recognizable. Fork the loom and the entity
branches into two. The entity's persistence is the loom's persistence.

*Verify it.* Construct a cantrip, summon it, send an intent, and stop the
process with `Process.exit(pid, :normal)`. Re-summon against the same loom
storage; the new process sees prior turns through `loom.turns`. The entity is
the trajectory, not merely the OS process. Code-medium binding restoration
across separate summonings is medium-specific; forks restore bindings explicitly
via snapshot, as documented by `Cantrip.Loom.fork/4`.

## Familiar

The Familiar is the packaged code-medium coordinator. It is a cantrip
preassembled with workspace observation gates (`list_dir`, `read_file`,
`search`), code-medium reasoning, durable loom storage, and a system prompt that
teaches composition and medium selection. Use it when you want a codebase-facing
entity without assembling the circle by hand. The Familiar is the first native
inhabitant of the spellbook: the entity designed to read this vocabulary and use
it.

*Verify it.* Run `mix cantrip.familiar` in a project workspace. Ask the Familiar
a question about your codebase. Read the loom JSONL or Mnesia table for what it
did and how it composed.

The grammar is small and the words are exact. If a word above does not behave
the way this page says, that is a defect, not a metaphor.