Writing a multi-doc series

Hydrate works brilliantly when the first session nails the canon. It can work against you when it doesn't. Here's how to use it so it's always the first kind.

Why this rule matters

We benchmarked this with a 12-chapter fictional gazetteer (Eilean-an-Ròn, a made-up Scottish archipelago). Baseline Haiku and Haiku+Hydrate both ran the same 12 prompts. The canon seed in session 1 listed the geography, ferry timetable, and island names - but not the recurring characters. The result, on cross-chapter consistency:

• Baseline: 69.3% consistency
• +Hydrate: 55.6% consistency
• Delta: −13.8 percentage points

Why did Hydrate lose? Session 6 needed a retired schoolteacher, invented Dr. Margaret Maclean, and Hydrate dutifully captured that fact. By session 10, "Dr. Margaret Maclean" was treated as canon - even though the author's actual canon was Morag MacLeòid. Baseline cells had no fact-propagation, so each session re-invented independently and landed near the canonical pattern by convergence. Hydrate amplified the drift because the original canon didn't pin the characters.

This isn't a Hydrate bug. It's the mechanism working as designed on an under-specified seed. The fix is operational: make the seed complete.

The Canon Session pattern

Before you write any chapter, run a dedicated session whose only job is to fix every recurring entity you care about by name. Call this your Canon Session.

1. List everything that will recur

People, places, products, dates, measurements, key numbers, recurring phrases, catchlines, house-style terminology. If a noun will appear in more than one chapter, it's a candidate.

2. Commit to specifics

Every entity gets a fully-specified form: the exact spelling, the exact date, the exact measurement. Morag MacLeòid (b. 1958, retired primary-school teacher on Eilean Mòr) is better than the retired teacher.

3. Have Hydrate capture it

Write the Canon Session in Claude Code with hooks active. The session's content becomes Hydrate's foundation - every subsequent session inherits it via injection.

4. Refer to canon by name in later sessions, not re-specify it

Chapters 2..N should mention entities by their canonical name without re-listing their attributes. This is counter-intuitive - you might feel the urge to remind the model - but doing so forces Hydrate to decide between your reminder and the captured canon, and the reminder often wins. Trust the capture.

Template - Canon Session prompt

You are preparing to write a [N]-chapter [type]. Before we begin chapter 1,
establish the canon. This session's output will not be a chapter - it's the
reference document every subsequent chapter must remain consistent with.

List, by name and with exact specifics, every recurring entity:

1. Setting: [list of places, their names, sizes, populations, relationships]
2. People: [list of characters with roles, ages, locations, defining traits]
3. Timeline: [list of dates and events that will be referenced]
4. Language: [terminology, spellings, house-style]
5. Products / objects: [anything named that will recur]
6. Numbers: [any statistic or measurement that will be cited more than once]

Commit to specific answers. Invented material is fine - the canon is whatever
you write here. Once established, these facts are authoritative.

Output format: one Markdown section per category, with each entity on its own
line. No prose yet. The chapters come in later sessions.

Worked example - the gazetteer

The benchmark scenario used this exact structure. The Canon Session establishes four islands, their populations, the ferry schedule, five recurring characters, four festival dates, and three dish names. From session 2 onward, the prompts are topic-only - "write chapter 3 on history", not "write chapter 3 about Eilean Mòr's WWII radar station". Hydrate fills the specifics.

Full scenario (prompts + canon + grader) lives in the Hydrate repo: bench/scenario-gazetteer/.

What if I'm halfway through a series?

You have three options, in order of effort:

1. Retrofit. Write a Canon Session after the fact that states the correct canon. Sessions from that point onward will see both the drifted facts and the canonical facts - injection is a blended context, not a replacement. Imperfect but often enough.
2. Reset the project. hydrate project fork --src=<slug> --dst=<slug>-v2 creates a clean copy. Run a Canon Session on the new one. Continue the series there.
3. Purge and restart. hydrate project deactivate and start over. Blunt but clean.

Pinned canon and the CLAUDE.md channel

Common mistakes

• Canon Session is too short. If your gazetteer has 20 recurring entities and the Canon Session names 8 of them, the other 12 will drift. Err on the side of over-specifying.
• Re-listing canon in every chapter prompt. Counter- productive. Forces the model to reconcile your reminder with the injected canon and often wins the reconciliation battle wrong.
• Using the same project for multiple unrelated series. Hydrate's fact scope is per-project. Fork: hydrate project fork --src=novel --dst=short-stories.
• Skipping session 1 because "it's just setup". Session 1 is the product. Budget it properly.

Source: Eilean-an-Ròn gazetteer benchmark, Haiku 4.5. Phase 1 (v1 no canon) 24 sessions, $1.62. Phase 2 (v2 with pinned canon) 12 additional sessions, $0.97. Finding updated 2026-04-19.