feat(docs): make guide regeneration reproducible

.claude/agents/guide-writer.md

@@ -8,24 +8,29 @@ tools: Read, Edit, Write, Grep, Glob, Bash
 ---
 
 You are the docs writer for the Optimization SDK Suite. Author or revise the requested guide under
-`documentation/guides/`. You compose from two source-of-truth layers:
+`documentation/guides/`. You compose from three source-of-truth layers:
 
 - **The recipe** for the guide's archetype, under `documentation/authoring/recipes/`
   (`integration.md`, `decision.md`, `supplemental-recipe.md`) — the structural source of truth. Its
   `## Template` is the section spine; its `## Context` is the rationale and is for you, never emitted
   into the guide. The recipe is authoritative over any sibling guide: match the recipe, do not copy a
-  sibling's structure.
+  sibling's structure. The recipe is SDK-neutral — it is the shape every guide of an archetype
+  shares.
+- **The blueprint** for this SDK, under `documentation/authoring/blueprints/<sdk>.md` — the compact
+  per-SDK editorial contract. Its Quick-start contract and Milestone contract define the first proof;
+  its Section map is the exact ordered `###` inventory/category and completeness contract; its “Must
+  teach or show” cells capture the technical writer's priorities. Fact sources route behavior to the KB.
+  Do not infer this from sibling guides. If no blueprint exists, surface the missing plan rather than
+  inventing one.
 - **The `optimization-guide-authoring` skill** — the teaching voice, the copy-vs-adapt honesty
   principle, and the authoring workflow.
 
-**Instantiate fragments, do not re-derive them.** Where a recipe references a fragment under
-`documentation/authoring/fragments/` (the personalization explainer, the authored-variant gotcha),
-open that fragment and copy its `## Template` **verbatim** into the guide, filling only its `⟨slot⟩`
-markers from the knowledge base — the fixed sentences are what keep the guide family consistent, so
-do not reword them. Honor any local instruction the recipe adds on the line that references the
-fragment ("include X, but drop the Y clause here"). A fragment's `## Context` tells you how to fill
-each slot and when a slot or bullet is omitted; never emit that Context. Per-SDK variation lives in
-the slots (filled from the KB), not in reworded prose.
+The division: the **recipe** owns the archetype shape, the **blueprint** owns this SDK's human-edited
+guide brief, the **knowledge base** owns behavior, package types own interface, and this skill owns
+voice. A blueprint Fact sources link is routing, not evidence by itself.
+
+**Reuse shared copy; do not re-derive it.** Copy its Template verbatim. Apply only the explicit
+switches named by the blueprint; do not infer SDK-family branches inside shared copy.
 
 Source each SDK claim by kind:
 
@@ -49,14 +54,14 @@ handoff and must never ship — `pnpm knowledge:check` fails on any `ESCALATE` m
 
 You handle two jobs:
 
-- **New guide** — draft from the matching recipe's `## Template`, instantiating the fragments it
-  references.
+- **New guide** — draft from the recipe and blueprint. Include every required quick-start artifact
+  and satisfy every “Must teach or show” item; matching headings alone is not a complete guide.
 - **Refresh an existing guide** — first diff it against the current recipe and bring it up to the
   present archetype. The fastest tells that a guide predates the current approach: no `## Quick start`
   or no `## Before you start`, a monolithic `## The integration flow` / `## Required steps` section,
   numbered headings, a required-setup inventory table instead of a prerequisites list, missing
   `**Copy this:**` / `**Adapt this to your use case:**` labels, or a hand-written intro explainer
-  that should be the `personalization-explainer` fragment. Restructure to the current archetype while
+  that should use the shared `personalization-explainer` copy. Restructure to the current archetype while
   preserving content that is still correct; do not throw away accurate specifics.
 
 You draft; you do not sign off. After your pass the guide goes to the `guide-newcomer-review` and

.claude/commands/author-guide.md

@@ -11,12 +11,14 @@ here, once. Use this whenever `documentation/internal/sdk-knowledge/<family>/<sd
 For an SDK whose KB file already exists and whose source merely changed, use **`/refresh-docs`**
 instead — it is far cheaper and does not re-comprehend the SDK.
 
-**The guide itself may or may not already exist — handle both (step 2).** A brand-new SDK has no
+**The guide itself may or may not already exist — handle both (steps 2–3).** A brand-new SDK has no
 guide (compose from scratch); a long-standing SDK often has a full guide that simply predates the
-knowledge base (Node and React Native were both like this — 900+ lines each). Either way the KB comes
-first: **knowledge first, guide second**, because the guide is composed from verified facts and the
-facts must exist before the prose. When a guide already exists, step 2 is a reconciliation against the
-now-authoritative KB, not a blank compose — do not expect an empty file.
+knowledge base (Node and React Native were both like this — 900+ lines each). Either way the order is
+**knowledge first, then the editorial map, then the guide prose**: the KB holds the verified facts
+(step 1), the blueprint records how those facts arrange into the archetype for this SDK (step 2), and
+the guide is composed from both (step 3). Facts must exist before the map, and the map before the
+prose. When a guide already exists, step 2 extracts its editorial map into the blueprint and step 3 is
+a reconciliation against the now-authoritative KB — do not expect an empty file.
 
 ## 1. Comprehend source → knowledge base (sdk-knowledge-author)
 
@@ -26,21 +28,36 @@ family dir (making a new sibling like `node/` or `native/` if needed), sets its
 to the target guide, and fills every section with facts + grammar pointers. This is the one step that
 reads source. It returns when `pnpm knowledge:check` passes for the new file.
 
-## 2. Compose or reconcile the guide from the knowledge base (guide-writer)
-
-Launch the `guide-writer` agent for the target guide. It composes structure from the archetype's
-recipe under `documentation/authoring/recipes/` — the recipe's `## Template` is the section spine and
-it instantiates the fragments the recipe references (the personalization explainer, the
-authored-variant gotcha) by copying their Template verbatim and filling `⟨slots⟩` from the KB. It
-composes **behavior** from the KB facts created in step 1 (never re-tracing behavior from source) and
-reads **interface** (shapes, signatures, props) directly from the types as needed, following the
-`optimization-guide-authoring` skill for voice and workflow — grounded in the matching reference
-implementation under `implementations/` for shape. Two sub-cases:
-
-- **Guide does not exist** — compose it from scratch against the template and the KB facts.
-- **Guide already exists** (predates the KB) — reconcile it: bring it to the current archetype and
-  make every SDK claim trace to a step-1 fact, preserving content that is still correct. This is the
-  writer's "refresh an existing guide" job. Expect a full file, not a blank one.
+## 2. Author the guide blueprint (the editorial contract)
+
+Before composing prose, create the SDK blueprint from `blueprints/_template.md`. It records the
+quick-start and milestone contracts, the exact Section map, the reader purpose and “Must teach or show”
+for each section, rare SDK-specific teaching overrides, troubleshooting scope, and link roles. Its
+Fact sources point to behavior; the blueprint never restates behavior or detailed interface shape.
+
+- **No blueprint yet** — copy `_template.md`, then make the editorial decisions from the recipe and
+  fresh KB. Do not copy a sibling blueprint's section choices.
+- **Guide already exists (predates the KB/blueprint)** — extract the blueprint from the existing
+  guide's structure: read its section inventory, order, and categories and record them (plus the
+  reasoning) as the map. This is the one time reading the existing guide is correct — you are
+  memoizing what it already encodes.
+
+## 3. Compose or reconcile the guide from the blueprint + knowledge base (guide-writer)
+
+Launch the `guide-writer` agent for the target guide. It takes the `##` spine from the recipe and the
+**section inventory, order, categories, proof, milestones, and teaching goals** from the blueprint.
+Matching the headings without satisfying “Must teach or show” is incomplete. It instantiates shared copy
+(the personalization explainer, the authored-variant gotcha) by copying their Template verbatim and
+filling `⟨slots⟩` from the KB. It composes **behavior** from the KB facts created in step 1 (never
+re-tracing behavior from source) and reads **interface** (shapes, signatures, props) directly from
+the types as needed, following the `optimization-guide-authoring` skill for voice and workflow —
+grounded in the matching reference implementation under `implementations/` for shape. Two sub-cases:
+
+- **Guide does not exist** — compose it from scratch against the recipe template, the blueprint's
+  editorial map, and the KB facts.
+- **Guide already exists** (predates the KB) — reconcile it: bring it to the current archetype and the
+  blueprint's map, and make every SDK claim trace to a step-1 fact, preserving content that is still
+  correct. This is the writer's "refresh an existing guide" job. Expect a full file, not a blank one.
 
 If the writer needs a fact the base does not hold, it escalates back to `sdk-knowledge-author` rather
 than reading source itself, using the escalation marker: an inline
@@ -49,7 +66,7 @@ use. The knowledge author adds the fact from source; the writer then composes th
 **removes the marker**. This is a transient handoff, never shipped — the gate below fails if any
 `ESCALATE` marker remains, and so does `pnpm knowledge:check`.
 
-## 3. Review, fix, and funnel back (delegate to the `review-guide` skill)
+## 4. Review, fix, and funnel back (delegate to the `review-guide` skill)
 
 Invoke the **`review-guide`** skill (`.claude/commands/review-guide.md`) on the guide. It owns the
 whole review loop in one pass — do not re-run it here:
@@ -60,22 +77,27 @@ whole review loop in one pass — do not re-run it here:
   having `sdk-knowledge-author` trace and add the fact, or the claim removed);
 - funnels durable findings back — reader/structure rules to the `optimization-guide-authoring` skill,
   facts to the knowledge base, cross-guide consistency issues fixed now (never logged);
-- validates (`pnpm knowledge:check`; `pnpm format:fix <touched paths>`, never bare).
+- validates (`pnpm knowledge:check`; `pnpm guides:check`;
+  `pnpm exec prettier --write <touched paths>`).
 
-## 4. Bootstrap gate
+## 5. Bootstrap gate
 
 `review-guide` runs its own gate; these are the extra checks specific to a from-scratch bootstrap.
 Do not finish until they hold:
 
 - The new KB file conforms: matches `_template.md`, has a `feeds-guides` marker, empty sections marked
   `None.`, and `pnpm knowledge:check` passes for it.
+- **The blueprint exists** at `documentation/authoring/blueprints/<sdk>.md` and its section inventory,
+  order, categories, and teaching goals match the guide. `pnpm guides:check` passes. The blueprint
+  records editorial judgment and KB links, not duplicated SDK facts or guide prose.
 - **No `ESCALATE` marker remains** in the guide — every escalation was resolved and its marker removed
   (`pnpm knowledge:check` fails on a survivor).
 - The guide is on the current archetype (Quick start, Before you start, category-ordered sections),
   and its TOC anchors resolve.
 
-## 5. Report
+## 6. Report
 
-Summarize: the KB file created and its facts, what the guide covers, each reviewer's findings and how
-they resolved, what was funneled into the skill vs. the KB, and the validation result. Note anything
-consciously deferred (e.g. Swift/Kotlin `#symbol` resolution for native SDKs).
+Summarize: the KB file created and its facts, the blueprint authored and its editorial map, what the
+guide covers, each reviewer's findings and how they resolved, what was funneled into the skill vs. the
+KB vs. the blueprint, and the validation result. Note anything consciously deferred (e.g. Swift/Kotlin
+`#symbol` resolution for native SDKs).

.claude/commands/iterate-guide.md

@@ -1,5 +1,5 @@
 ---
-description: Fast prose/structure/sequence iteration on a guide — recompose from the existing knowledge base and recipes, no source read, no fact re-verification
+description: Fast prose/structure/sequence iteration on a guide — recompose from the existing knowledge base, blueprint, and recipes, no source read, no fact re-verification
 argument-hint: '[guide path + the phrasing/tone/sequence change, or a recipe/fragment edit to render]'
 ---
 
@@ -19,7 +19,11 @@ SDK, stop and hand off (see the guardrail) — that is `/refresh-docs` (source c
 ## What counts as in-scope (editorial)
 
 - Rewording for clarity, tone, or voice; tightening or expanding an explanation.
-- Reordering or re-sequencing sections; moving content between sections; changing what leads.
+- Reordering or re-sequencing sections; moving content between sections; changing what leads;
+  reassigning a section's integration category. **A change to the section inventory, order, or
+  category is an edit to the SDK's blueprint** (`documentation/authoring/blueprints/<sdk>.md`), then
+  re-rendered into the guide — the "edit the class, not the instance" move. Do the edit in the
+  blueprint (with its reasoning), not surgically in the guide.
 - Editing a recipe (`documentation/authoring/recipes/`) or fragment
   (`documentation/authoring/fragments/`) and re-rendering the guides that instantiate it.
 - Changing an example-intent label's prose, a heading's wording (with its TOC anchor), or a
@@ -45,22 +49,23 @@ variant or null" asserts a new fact — stop).
 ## Steps
 
 1. **Scope the change.** State the guide(s) affected and whether the edit is to the guide prose
-   directly, or to a recipe/fragment that several guides instantiate (then all instantiating guides
-   are in scope — find them by which archetype/fragment they use). Confirm the change is editorial;
-   if any part trips the guardrail, name it and stop for that part.
+   directly, to the SDK's blueprint (section inventory/order/category — affects that one guide), or to
+   a recipe/fragment that several guides instantiate (then all instantiating guides are in scope —
+   find them by which archetype/fragment they use). Confirm the change is editorial; if any part
+   trips the guardrail, name it and stop for that part.
 
 2. **Recompose the affected prose (guide-writer).** Launch `guide-writer` scoped to the editorial
    change. It composes from the **existing** knowledge base (fills fragment slots and behavioral prose
    from current facts — never re-tracing source, never escalating a fact) and reads interface only if
-   it must confirm a shape it is _rendering_ (not changing). If a recipe/fragment changed, it
-   re-instantiates that fragment verbatim into each affected guide, filling slots from the current KB.
-   It restructures and rewords per the `optimization-guide-authoring` skill and the archetype recipe;
-   it does not alter factual claims.
-
-3. **Validate cheaply.** `pnpm format:fix <touched guide paths>` (never bare) and confirm the
-   collapsible TOC anchors still resolve. Run `pnpm knowledge:check` **only if** a recipe/fragment or
-   KB-adjacent file was touched (it is fast and confirms nothing drifted); a pure guide-prose edit
-   does not require it. Do NOT run the newcomer/source reviewers here — that is the final pass.
+   it must confirm a shape it is _rendering_ (not changing). If the blueprint changed, it re-renders
+   the guide's section inventory, order, and categories to match the updated map. If a recipe/fragment
+   changed, it re-instantiates that fragment verbatim into each affected guide, filling slots from the
+   current KB. It restructures and rewords per the `optimization-guide-authoring` skill, the archetype
+   recipe, and the SDK's blueprint; it does not alter factual claims.
+
+3. **Validate cheaply.** Run `pnpm exec prettier --write <touched guide paths>` and
+   `pnpm guides:check`; confirm the TOC anchors resolve. Run `pnpm knowledge:check` if a fragment or
+   KB-adjacent file changed. Do NOT run the newcomer/source reviewers here — that is the final pass.
 
 4. **Report.** The change made, the guides re-rendered, anything the guardrail sent to `/refresh-docs`
    or `/review-guide`, and the validation result. Remind the writer to run **`/review-guide`** as the

.claude/commands/refresh-docs.md

@@ -44,6 +44,13 @@ fact**, composing from the reconciled KB (not re-reading source, not rewriting t
 A fact that changed shape/behavior means the snippet or sentence that used it changes; an unaffected
 section is left as-is.
 
+If the change **adds or removes a documented capability** (a new feature the guide should now cover,
+or a removed one it should drop), the SDK's blueprint
+(`documentation/authoring/blueprints/<sdk>.md`) needs a matching Section map change before the guide
+gains or loses that section. Update “Must teach or show” when the changed capability alters what the
+reader must see. A pure behavioral change that leaves the teaching contract intact changes only the KB
+and guide.
+
 ## 4. Review only what changed (delegate to the `review-guide` skill, scoped)
 
 Invoke the **`review-guide`** skill on each recomposed guide — it owns the review/fix/funnel/validate
@@ -59,8 +66,8 @@ loop in one pass; do not re-run those steps yourself. Focus the reviewers on the
 
 - Every changed claim traces to a current KB fact; no newcomer blocker in the changed passages.
 - No `ESCALATE` marker remains in any touched guide.
-- `pnpm knowledge:check` passes; `pnpm format:fix <touched paths>` leaves the touched guides clean and
-  TOC anchors resolve. Pass the specific files you changed — never a bare `pnpm format:fix`.
+- `pnpm knowledge:check` and `pnpm guides:check` pass;
+  `pnpm exec prettier --write <touched paths>` leaves the touched guides clean; TOC anchors resolve.
 
 ## 6. Report
 

.claude/commands/review-guide.md

@@ -38,17 +38,22 @@ Do this in order:
    into the right artifact:
    - a reader-experience or **voice/teaching** rule → the `optimization-guide-authoring` skill
      (principles only, never SDK facts),
-   - a **structure or shared-prose** rule → the recipe or fragment under `documentation/authoring/`
-     (section spine and integration categories → the archetype's recipe; a reusable sentence that
-     drifted across the family → the relevant fragment's Template),
+   - an **archetype-wide structure or shared-prose** rule → the recipe or fragment under
+     `documentation/authoring/` (the section spine, the category value set, and rules that hold for
+     _every_ guide of the archetype → the archetype's recipe; a reusable sentence that drifted across
+     the family → the relevant fragment's Template),
+   - a **per-SDK editorial decision** — this SDK's section inventory, its order, or a specific
+     section's integration category — → the SDK's blueprint
+     (`documentation/authoring/blueprints/<sdk>.md`), with the reasoning. (The distinction: a rule
+     true for the whole archetype is the recipe's; a judgment specific to how _this_ SDK's features
+     arrange is the blueprint's.)
    - a missing or corrected SDK fact → the knowledge base via `sdk-knowledge-author`.
 
    When a fragment the recipe names is missing from the guide, or its fixed spine was reworded rather
    than instantiated verbatim, that is a structure finding: have the writer instantiate it.
 
-5. **Validate.** Run `pnpm knowledge:check` (KB must pass) and `pnpm format:fix <touched paths>` —
-   pass the specific files you changed, never a bare `pnpm format:fix` (it reformats the whole tree
-   and pollutes the diff) — and confirm the guide's TOC anchors resolve.
+5. **Validate.** Run `pnpm knowledge:check`, `pnpm guides:check`, and
+   `pnpm exec prettier --write <touched paths>`. Confirm the guide's TOC anchors resolve.
 
 Report: the findings from each role, what you changed in the guide, what you funneled back into the
 skill vs. the knowledge base, and the validation result.