feat(docs): make guide regeneration reproducible

[Tim Beyer (TimBeyer)]

Summary

This PR adds a complete authoring system for Optimization SDK integration guides.

The system makes the costly part of documentation work reusable: SDK behavior is derived from the implementation once, recorded with source pointers, and then consumed by writers and reviewers. It also captures the SDK-specific editorial decisions that previously existed only in finished guides, so a new guide does not need an expert to reconstruct the reader journey from scratch.

The merged result is deliberately human-facing. Technical writers can shape the teaching sequence and required outcomes in ordinary Markdown. Agents help draft and verify the guide, but do not own the editorial contract or certify their own work.

Why

The existing SDK knowledge base answers behavioral questions, and the guide recipes describe shared guide patterns. That still left an important gap: neither artifact said how one SDK's facts should become a complete reader journey—what to teach, in which order, with which proof, and at what depth.

Historically, those decisions were embedded in the accepted guide itself. That worked for maintenance, but made genuinely new guides hard to reproduce without an SDK expert or an existing document to imitate.

This PR adds the missing editorial layer and connects it to the existing knowledge, authoring, and review workflows.

What this PR merges

A four-part authoring model

Artifact	Responsibility	Primary owner
Recipe	The shared teaching sequence for a guide archetype, such as an integration guide	Documentation team
Blueprint	The SDK-specific reader journey: section, category, purpose, what it must teach or show, and its fact sources	Technical writer with SDK input
Shared copy	Small pieces of reader-facing wording that genuinely need to remain consistent across guides	Documentation team
SDK knowledge	Verified behavioral facts, defaults, fallbacks, ownership, lifecycle, and source pointers	SDK maintainers and knowledge authors

Interface details remain cheap and self-verifying: writers and technical reviewers may inspect the current public types in packages/**/src. Behavioral claims come from the verified SDK knowledge base instead of being re-traced through the implementation for every guide.

Six SDK blueprints are included, plus a canonical blueprint template. Every blueprint uses the same human-readable schema:

• Section
• Category
• Purpose
• Must teach or show
• Fact sources

Together, the six blueprints define 88 planned guide sections.

The authoring workflow

For normal guide maintenance:

1. Start from the accepted guide rather than discarding good existing work.
2. Read its recipe, SDK blueprint, shared copy, and relevant knowledge files.
3. Preserve or improve the documented reader outcome.
4. Look up current package source for interface facts; use the knowledge base for behavior.
5. Run an independent newcomer review and technical-foundation review for substantial changes.

For a genuinely new guide, the same inputs provide the initial structure and technical foundation. New guides should expect a deeper drafting and review loop because no accepted reader experience exists yet.

The three authoring roles have distinct authority:

• The writer produces or revises the guide.
• The newcomer reviewer checks whether an average developer can understand and perform it.
• The technical-foundation reviewer verifies interface claims against source and behavioral claims against the knowledge base.

If a behavioral claim cannot be supported by the knowledge base, it is escalated to knowledge authoring instead of being guessed or re-derived ad hoc.

Validation and tooling

This PR adds pnpm guides:check, backed by scripts/validate-guide-authoring.ts. It validates:

• the blueprint schema and section categories;
• links from blueprints to their fact sources;
• expected guide headings and section order;
• required guide structure and navigation;
• links in rendered guide Markdown;
• leaked internal escalation markers.

The existing knowledge validator is extended alongside the new authoring model. CI now runs the guide validator as part of the documentation integrity checks.

Contributor guidance, the guide authoring skill, Claude agents and commands, and project-scoped Codex agents all use the same workflow. The Codex setup includes dedicated writer, newcomer-reviewer, technical-verifier, and knowledge-author roles, plus an advisory hook that runs the relevant validators when documentation-system files change.

Guide and knowledge alignment

The integration recipe, shared copy, existing SDK guides, and relevant knowledge files are aligned with the new contracts. Missing behavioral facts discovered during the work were added to the knowledge base with source pointers.

The accepted guides remain the publication baseline. Generated experiment drafts are not merged as replacements.

What this means for contributors

• Technical writers can change the reader journey without editing an LLM-oriented specification.
• SDK maintainers can contribute verified behavioral knowledge without writing the finished guide.
• Agents can draft from maintained inputs without repeating expensive application-level tracing.
• Existing guides remain the starting point for routine refreshes.
• New and substantially rewritten guides cannot be accepted solely on the writer's self-assessment; independent reader and technical reviews remain required.

Reproducibility means reaching the same excellent, performable reader outcome—not reproducing identical prose.

Validation

• pnpm guides:check
  • 6 blueprints
  • 88 planned sections
  • links and rendered guide structure valid
• pnpm knowledge:check
  • 747 source pointers across 8 fact files
  • no leaked ESCALATE markers
• pnpm exec eslint scripts/validate-guide-authoring.ts
• pnpm format:check
• git diff --check
• Clean-room fixture validation
  • 1 Next.js App Router blueprint
  • 15 planned sections
  • links and rendered guide structure valid

---

Implementation history: how we got here

This section records the experiments and intermediate designs that informed the merged system. It is not a description of additional machinery being merged.

1. Identify the missing layer

Initial clean-room exercises withheld existing guide prose and attempted to compose Node and React Web guides from the knowledge base, recipes, and shared copy. They recovered much of the content but lost SDK-specific structure, category choices, proof points, and depth.

That showed the knowledge base was not the main gap. The missing information was editorial: how verified facts become one SDK's reader journey. Blueprints were introduced to capture that judgment separately from both facts and final prose.

After adding the first blueprints and filling genuine knowledge gaps, clean-room drafts converged much more closely on the expected section inventory and ordering.

2. Test whether stricter evidence bookkeeping improved depth

The next iterations tried to make blueprint obligations mechanically auditable with Evidence IDs, evidence atoms, coverage ledgers, and writer-produced receipts.

Fast/mini and Luna clean-room runs still produced shallow or technically incorrect guides. More importantly, writers could claim that an obligation was covered even when the procedure or example was incomplete. The receipts added apparent certainty without becoming an independent source of truth.

That experiment established that the writer cannot also be the acceptance authority. Independent newcomer and technical reviews provide the meaningful quality gate.

3. Return the authoring inputs to human language

The final iteration removed the Evidence-ID and receipt machinery and reduced blueprints to compact technical-writer briefs using Purpose, Must teach or show, and Fact sources.

A final isolated Terra run generated the Next.js App Router guide without access to the accepted guide, sibling guide prose, prior drafts, dist, or .rslib. It could use current package source for interfaces, the SDK knowledge base for behavior, the authoring inputs, concepts, and the reference implementation.

The result was a coherent 4,551-word draft covering all 15 planned sections, and the fixture validator passed. Independent review still found publish-blocking gaps and code errors, including an incomplete managed-fetching handoff, non-performable live-update verification, invalid analytics and Custom Flag examples, and incorrect preview readiness handling.

Those obligations and facts were already present in the maintained inputs. No missing behavioral knowledge fact was identified in the final run. Adding more model-specific prompt clauses would therefore have increased complexity without addressing the failure mode.

Resulting decisions

The implementation history led to the final boundaries used by this PR:

1. Keep blueprints as human-editable editorial briefs.
2. Keep interface lookup available to writers and technical reviewers.
3. Memoize expensive behavioral comprehension in the SDK knowledge base.
4. Treat clean-room generation as an occasional system stress test, not the normal refresh workflow.
5. Require independent newcomer and technical-foundation review instead of writer-produced coverage receipts.
6. Use capable models for drafting while keeping technical writers and reviewers in control of the published outcome.

[Charles Hudson (phobetron)]

Nobody expects the Spanish inquisition!

[Charles Hudson (phobetron)]

Can I assume there's no model-agnostic way to handle some of these concerns? I'm also wondering what authoring or updating a guide looks like from a contributor's perspective, how we'd tell the agent to do the thing, etc.

[Tim Beyer (TimBeyer)]

What exactly do you mean with "model-agnostic"?
Also the contributing part is written down in https://github.com/contentful/optimization/blob/main/documentation/authoring/README.md but somehow in https://github.com/contentful/optimization/blob/3541cec7b94af691b232284268912c9cd3468348/documentation/authoring/README.md the agent decided to aggressively overwrite that. Will make sure it's more of a merge.

[Tim Beyer (TimBeyer)]

Updated the instructions in https://github.com/contentful/optimization/blob/ab14a9eaf81ad98067041e6b2fc8c80149fdfe63/documentation/authoring/README.md