skilldocs: what a figaro sees when it sees a system reminder

A figaro reads its own context and had nowhere to learn what the tags in it
mean. The index now opens with the four it will actually meet -- board key,
study, study:@id, fork -- and says the thing that is easy to get wrong: they
are STATE, not the user speaking.

forms.md gains the agent-facing half of the same picture: the four species and
which of them can reach a context uninvited (one), what a change looks like
(folded per window, the value it ENDS at, exists:false for a death), and the
two knobs -- the study verbs and system.study_incantation.

Not documented, because it does not exist: on-demand recall of a value that
was truncated away. Nothing truncates a studied value today; a delta carries
it whole. Better to say 'keep them small' than to promise a recall verb that
would have to be written first.

Author: gluck

skills/figaro/SKILL.md

@@ -9,6 +9,23 @@ A local coding-agent daemon. One static Go binary, three roles: the `CLI` you
 type at, the `Angelus` supervisor that outlives your shell, and one `Agent` per
 conversation. An **aria** is one conversation.
 
+## If you are a figaro, reading your own context
+
+Your context carries `<system-reminder name="…">` blocks. **They are state,
+not the user speaking**: the daemon injects them at each turn, and they are
+the only way you see anything outside your own conversation.
+
+| tag | what it is |
+|---|---|
+| `name="<key>"` | one key of **your bound form** (your board): `cwd`, `mantra`, `aria_id`, whatever your outfit set. `figaro set <key> <value>` changes it. |
+| `name="study"` | you began or stopped observing a form: `{form, observing, state, version}`. `state` is the whole form as it stood when observation began. |
+| `name="study:@id"` | that form **changed**: `{form, changes, set, removed, version}` — and `"exists":false` when it was deleted (the copy survives, so history still renders). |
+| `name="fork"` | you are a branch, and where you came from. |
+
+A form you do not study is invisible to you. See [forms.md](forms.md) for the
+four species — bound form, unbound form, studied form, role — what arrives on
+change, and what configures it.
+
 ## The gestures
 
 Nine commands cover almost everything. Exact forms, not summaries.

skills/figaro/forms.md

@@ -35,6 +35,39 @@ fig set --id @a1b2c3 target-aria <id>  # now it's a ROLE: fig send @a1b2c3 reach
   verbs that need a figaro (`send`, `listen`) resolve it *at each
   invocation*: repoint the key and the next send reaches the successor.
 
+## What a figaro SEES of all this
+
+Four species, one id namespace, and only one of them reaches your context
+uninvited:
+
+| species | what it is | how you see it |
+|---|---|---|
+| **bound form** | your own board | one `<system-reminder name="<key>">` per key, every turn |
+| **unbound form** `@x` | free-standing state, no figaro | not at all, unless you study it |
+| **studied form** | an unbound form you observe | a `study` block when you begin, a `study:@x` block on each change |
+| **role** | a form carrying `target-aria` | an ordinary form: visible only if you study it. `fig cast` studies it for you |
+
+**On change** you get one `study:@x` block per user message, folded: several
+patches inside one window arrive as a single block (`"changes":2`), and it
+carries the value the key ENDS at, not the intermediate ones. A deleted source
+arrives as `"exists":false` — its copy outlives it, so the history you were
+shown still makes sense. Values are **not truncated**: a delta carries the
+whole changed value, so keep studied values small if context matters.
+
+**What configures it**
+
+- `fig study @x` / `fig drop @x` — the subscription itself. It lives on your
+  board as `system.studies`, which is system-managed: only the verbs write it.
+- `system.study_incantation` on **your own board**: `{onstudy, onupdate,
+  ondrop}`, a sentence added to each event so a figaro is told what the change
+  MEANS to it, not just what changed.
+- Nothing else. There is no per-key filter today: a studied form is mirrored
+  whole.
+
+**Recommended**: put a short primer in your **base outfit** — every key an
+outfit sets becomes a reminder of that name, so every figaro you ever mint
+inherits it. One key, a few lines, and no figaro has to be told twice.
+
 ## What refuses, and why
 
 - `fig send @x` on a plain (non-role) form: *"@x is a form, not a