Handoff — 2026-09-15 — Diátaxis documentation bootstrap (agent "riker")

Where it stopped

docs/ exists with a complete bilingual four-quadrant structure (docs/en/, docs/fr/, identical file names). Every page is "complete, not finished": usable now, open to growth. All relative links resolve (checked with a shell loop over ](…) targets). Nothing committed — the whole repository is untracked apart from two old commits.

Filing plan that was applied (compass)

Topic	Quadrant	File (both languages)
First session with DMR	Tutorial	`tutorials/getting-started.md`
Run on llama.cpp	How-to	`how-to/run-with-llama-cpp.md`
Host in an editor (ACP/Zed)	How-to	`how-to/use-from-an-editor.md`
Add a skill	How-to	`how-to/add-a-skill.md`
Long session inside the window	How-to	`how-to/manage-the-context-window.md`
Start a new session (`/new`)	How-to	`how-to/start-a-new-session.md` — written by the other agent (bob)
CLI flags, env vars, banner, exit codes	Reference	`reference/cli.md`
Slash commands and keys	Reference	`reference/slash-commands.md` — bob edited the `/new` row after me
YAML keys, defaults, validation errors	Reference	`reference/configuration.md`
Built-in tools	Reference	`reference/tools.md`
Skill file format	Reference	`reference/skill-format.md`
ACP surface	Reference	`reference/acp.md`
One loop, two front ends	Explanation	`explanation/architecture.md`
Providers	Explanation	`explanation/providers.md`
Context compression	Explanation	`explanation/context-compression.md`

The skill's mandatory language question was not asked (user unavailable); "Both" was taken from the methodical-dev convention. If the user wants a single language, delete the other tree and the selector in docs/README.md.

Traps found (documented, not fixed — no Go changes were in my scope)

Shipped skills are invisible. skills.List globs <skillsDir>/*.md; the examples are skills/<name>/SKILL.md. Banner shows skills: 0, read_skill is never declared. Either flatten the files or teach the loader to read */SKILL.md. The docs describe the current behaviour and tell the user to flatten.
go test ./... fails in mm/internal/skills: TestShippedSkillsHaveDescriptions hard-codes ../../../demo/skills, a path from the project this code was extracted from. Fix the path (and the layout above) or the quality gate will never be green.
The tutorial's banner line was captured verbatim from a real run; it now includes "/new" to start a new session. because bob changed agent.go. If the banner text changes again, update both tutorials.
agent.yaml calls the agent "Bob", ACP agentInfo.name is bob / version 0.11.0, the binary is mm. The docs use mm for the binary and quote the ACP values as-is.

Not verified

No model server in the sandbox: step 3 of the tutorial (a real generation) was written from the code paths, not observed. The banner and -h output were observed.
docs/diagrams/packages.drawio was created by bob; I linked it from both indexes and both architecture pages without validating its content.

Suggested next increments

A how-to for editTools: false (bash-only A/B mode) once someone has actually run it.
A reference page for the engine's runtime messages ([watchdog: …], Retrying without streaming) — currently only mentioned in passing.
Explanation of the loop detector once its thresholds (history 10, threshold 3, set in main.go) are considered stable.
bob updated reference/slash-commands.md and reference/acp.md in both languages for /new (row, ACP section, available_commands_update) after I wrote them; at the end of my session they were consistent with the code. Re-check only if /new changes again.

Addendum (same day, orchestrator)

The Zed snippet in how-to/use-from-an-editor.md (EN + FR) was missing "type": "custom"; the user confirmed Zed needs it. Fixed in both pages. Any future editor how-to must include that key.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


# Handoff — 2026-09-15 — Diátaxis documentation bootstrap (agent "riker")

## Where it stopped

`docs/` exists with a complete bilingual four-quadrant structure (`docs/en/`, `docs/fr/`, identical file names). Every page is "complete, not finished": usable now, open to growth. All relative links resolve (checked with a shell loop over `](…)` targets). Nothing committed — the whole repository is untracked apart from two old commits.

## Filing plan that was applied (compass)

| Topic | Quadrant | File (both languages) |
|-------|----------|-----------------------|
| First session with DMR | Tutorial | `tutorials/getting-started.md` |
| Run on llama.cpp | How-to | `how-to/run-with-llama-cpp.md` |
| Host in an editor (ACP/Zed) | How-to | `how-to/use-from-an-editor.md` |
| Add a skill | How-to | `how-to/add-a-skill.md` |
| Long session inside the window | How-to | `how-to/manage-the-context-window.md` |
| Start a new session (`/new`) | How-to | `how-to/start-a-new-session.md` — written by the other agent (bob) |
| CLI flags, env vars, banner, exit codes | Reference | `reference/cli.md` |
| Slash commands and keys | Reference | `reference/slash-commands.md` — bob edited the `/new` row after me |
| YAML keys, defaults, validation errors | Reference | `reference/configuration.md` |
| Built-in tools | Reference | `reference/tools.md` |
| Skill file format | Reference | `reference/skill-format.md` |
| ACP surface | Reference | `reference/acp.md` |
| One loop, two front ends | Explanation | `explanation/architecture.md` |
| Providers | Explanation | `explanation/providers.md` |
| Context compression | Explanation | `explanation/context-compression.md` |

The skill's mandatory language question was not asked (user unavailable); "Both" was taken from the methodical-dev convention. If the user wants a single language, delete the other tree and the selector in `docs/README.md`.

## Traps found (documented, not fixed — no Go changes were in my scope)

1. **Shipped skills are invisible.** `skills.List` globs `<skillsDir>/*.md`; the examples are `skills/<name>/SKILL.md`. Banner shows `skills: 0`, `read_skill` is never declared. Either flatten the files or teach the loader to read `*/SKILL.md`. The docs describe the current behaviour and tell the user to flatten.
2. **`go test ./...` fails** in `mm/internal/skills`: `TestShippedSkillsHaveDescriptions` hard-codes `../../../demo/skills`, a path from the project this code was extracted from. Fix the path (and the layout above) or the quality gate will never be green.
3. The tutorial's banner line was captured verbatim from a real run; it now includes `"/new" to start a new session.` because bob changed `agent.go`. If the banner text changes again, update both tutorials.
4. `agent.yaml` calls the agent "Bob", ACP `agentInfo.name` is `bob` / version `0.11.0`, the binary is `mm`. The docs use `mm` for the binary and quote the ACP values as-is.

## Not verified

- No model server in the sandbox: step 3 of the tutorial (a real generation) was written from the code paths, not observed. The banner and `-h` output were observed.
- `docs/diagrams/packages.drawio` was created by bob; I linked it from both indexes and both architecture pages without validating its content.

## Suggested next increments

- A how-to for `editTools: false` (bash-only A/B mode) once someone has actually run it.
- A reference page for the engine's runtime messages (`[watchdog: …]`, `Retrying without streaming`) — currently only mentioned in passing.
- Explanation of the loop detector once its thresholds (history 10, threshold 3, set in `main.go`) are considered stable.
- bob updated `reference/slash-commands.md` and `reference/acp.md` in both languages for `/new` (row, ACP section, `available_commands_update`) after I wrote them; at the end of my session they were consistent with the code. Re-check only if `/new` changes again.

## Addendum (same day, orchestrator)

The Zed snippet in `how-to/use-from-an-editor.md` (EN + FR) was missing `"type": "custom"`; the user confirmed Zed needs it. Fixed in both pages. Any future editor how-to must include that key.