📚 A self-maintaining docs pipeline: source → knowledge base → guides [NT-3625]

[Tim Beyer (TimBeyer)]

Read this first. This PR is not "rework the docs." It is a process for producing and
maintaining docs, arrived at through a deliberate design exploration. The guide/KB content is far
too large to review line by line, and reviewing it that way would miss the point. What is worth
your scrutiny is the design below: the model it commits to, why that model, and the tradeoffs
taken along the way. The mechanics are documented after, but the "why" is the review.

The problem we were actually solving

The previous docs PR (#358) produced good web-family guides and introduced three artifacts — public
guides, an internal knowledge base of verified SDK facts, and authoring skills. But they
were not tied into a cycle. Each was produced in a single agent context, and there was nothing to
stop them drifting apart from each other or from the SDK source. Two failure modes followed directly:

1. Silent rot. A fact in the knowledge base pointed at a line range in source; the source moved;
   nothing noticed. We found real examples — a pointer to OptimizedEntryResolver.ts:148-209 that no
   longer meant anything, source: accepted App Router guide pointers that were circular (a "fact"
   whose evidence was another doc), and stale directory paths from files that had since moved.
2. Re-derivation. Every time a guide was touched, its claims were re-verified against source from
   scratch. That is fine once; as a steady-state practice it means a small SDK change triggers a
   full, expensive re-comprehension of the codebase to rebuild docs — re-reading and re-reasoning
   about the whole SDK because someone renamed a prop.

The ask was to look at this as a whole SDLC — not just the from-scratch authoring path — and make
the pieces flow into each other, mostly automatically, with as little bespoke machinery as possible.

The core idea: the knowledge base is a compiler IR

The design that fell out of the exploration treats the three artifacts as a compilation pipeline:

        source→KB pointer                      feeds-guides marker
   ┌──────────────────────┐            ┌──────────────────────────┐
   │                      ▼            ▼                          │
 SOURCE ──▶ sdk-knowledge-author ──▶ KNOWLEDGE BASE ──▶ guide-writer ──▶ GUIDES
 packages/src   (the only reader        (verified facts,   (composes from      (readers)
                 of source code)         each pointed)       facts, not code)

• Source code is the source language.
• The knowledge base is the intermediate representation: terse, verified facts, each carrying a
  machine-checkable pointer back to the exact source symbol that proves it.
• The guides are the compiled target, for human readers.

The expensive step is comprehension — reading source and understanding what is true. The knowledge
base memoizes that step. Everything downstream (writing guides, reviewing them) reads facts, not
code. This is the hinge the whole design turns on, and it is what makes the steady state cheap.

Why this resolves the chicken-and-egg

There is a real tension: to know what to document you must first understand the code, so you cannot
"just read the knowledge base." The resolution is that comprehension is bounded differently in each
mode, and only one mode is expensive:

Mode	What runs	Cost
Bootstrap	full source→KB→guide for an SDK from nothing	expensive — once per SDK
Incremental	a source diff scopes the work: re-verify only the facts the change touches, recompose only the guides that consume them	cheap — the common case
Recompose	KB→guide with source unchanged (voice/structure only), driven by /iterate-guide	cheapest — reads no source

The comprehension cost — reading and reasoning about the whole SDK — is paid at bootstrap and
amortized. A one-line SDK change touches a handful of facts and a handful of guide passages, because
the dependency graph tells us exactly which ones, instead of re-reasoning about everything.

The dependency graph is bidirectional and machine-checked

This is the piece that makes incremental scoping deterministic rather than guesswork:

• source → KB: every fact ends in a source: pointer (e.g. core-sdk#CoreBase.ts#ContentfulConfig).
  Given a changed source file, we know exactly which facts are at risk.
• KB → guide: every per-SDK knowledge file declares <!-- feeds-guides: … -->. Given a changed
  fact, we know exactly which guide must be recomposed.

Both directions are validated in CI (pnpm knowledge:check): a pointer must resolve to a symbol that
actually exists in source (checked via the TypeScript compiler, not a regex), and a feeds-guides
target must be a real guide.

Design decisions, and the reasoning behind them

These were the forks in the road. They are where review attention is best spent.

• Symbol-anchored pointers, never line numbers. Line ranges drift on every edit; a symbol name
  survives refactors. The stale :148-209 pointer was the evidence. Pointers name a symbol
  (file#Symbol) and the validator confirms it is actually declared — so a rename fails the build
  instead of rotting silently. Line numbers are gone from the grammar entirely.

• A strict grammar, defined first, then enforced. Rather than write a parser to tolerate the
  messy free-text pointers that existed, we defined a clean grammar (the KB's README owns it) and
  migrated the base onto it. The migration was where the circular and stale pointers died. The
  grammar is the contract; the validator checks it.

• Deterministic where possible, agentic only where judgment is required. The dependency graph,
  pointer resolution, template conformance, and drift detection are plain deterministic checks (a
  ~700-line TypeScript validator using the compiler API — no new dependencies). Only the genuinely
  judgment-bound work — comprehending source into facts, composing teachable prose, reading a guide
  as a newcomer — is done by agents. This keeps CI honest and cheap and reserves model cost for what
  actually needs a model.

• Standards-compliant over Claude-exclusive. We researched the landscape first. AGENTS.md, Agent
  Skills (SKILL.md), and MCP are open, multi-vendor standards; subagent definitions and docs-drift
  tooling are not. So the load-bearing parts are portable — skills live in a tool-neutral top-level
  skills/ dir (already symlinked into .claude/ and .agents/), the validator is a normal pnpm
  script, CI is plain GitHub Actions. The Claude-specific pieces (agent wrappers, a Stop hook) are a
  thin convenience layer over that portable core, not the substrate. We deliberately did not
  reach for MCP/skill-kit here: those add install friction and suit a distributed, customer-facing
  product, not an internal CI loop.

• Fix drift, do not log it. An earlier artifact (consistency-notes.md) was a persisted work-log
  of "things to reconcile later." A file that catalogs known-broken things instead of fixing them is
  an anti-pattern; it was deleted and the skill instruction that produced it was replaced with "fix
  it now; shared wording lives once." Transient authoring state belongs to a workflow run, not a
  committed file.

• Do not compromise readability to satisfy tooling. When the validator hit a lint line-cap, the
  fix was to split it into modules and keep every explanatory comment — not to strip the docs. The
  validator is thoroughly commented precisely because it does subtle work.

Formalizing structure: recipes and fragments (the missing third artifact)

The original design closed the loop on facts — the KB is the machine-checked source of truth for
what the SDK does — but left structure unformalized. A guide's section spine, sequence, and shared
prose lived in two competing places: long-form rules inside the authoring skill, and the shipped
sibling guides themselves. An agent writing a new guide could anchor on either, and copying a sibling
was the easy pull — so "shared" wording survived only by imitation and drifted a little each time.
Meanwhile the KB was the fact authority but had no owner for editorial shape, and the natural person
to own that — a technical writer — had nowhere to work that wasn't either skill internals or a
single guide surgically.

This adds a fourth, writer-owned artifact under documentation/authoring/, splitting structure
out of the skill the same way the KB earlier split facts out of the guides:

• Recipes (recipes/, one per archetype) — the editorial spine: section order, which fragments a
  guide composes, and the rationale. The structural source of truth, authoritative over any sibling
  guide.
• Fragments (fragments/) — reusable reader-facing prose (the "New to personalization?" intro
  explainer, the mandatory authored-variant gotcha) with a fixed spine and knowledge-base-filled
  slots. This is the reader-facing mirror of the KB's shared/ — canonical wording captured once,
  instantiated per guide, rather than re-imitated.

Two design points worth scrutiny, because they mirror decisions already made for facts:

• It's prose the LLM instantiates, not a templating DSL. An early sketch leaned toward YAML
  frontmatter with tokens like opens_with: intro — which read as code but had no interpreter and no
  registry the tokens resolved to. The consumer of this layer is the guide-writer agent, whose
  native interface is natural language; a fake-precision schema would be strictly worse than prose.
  So recipes/fragments are prose, and each file splits into ## Context (agent-only rationale and
  fill rules, never rendered) and ## Template (the prose that becomes guide output). That split
  is the interface/behavior distinction one layer up: Context is judgment, Template is the artifact.
• Verbatim spine vs. composed-around-an-anchor. Fixed sentences are reproduced word-for-word (only
  slots filled), which is what keeps a guide family consistent — and makes a future check able to
  confirm instantiation by matching the fixed sentence. But not every bullet is verbatim: where the
  content is genuinely SDK-shaped (the entry-source hand-off differs by manual/managed/both), the
  fragment marks the bullet composed — free prose around a fixed anchor (the baseline-fallback
  clause) that must survive intact. This distinction was discovered empirically by running the
  pipeline (see below), not designed up front.

A third slash command drives the recompose mode this enables:

• /iterate-guide — editorial-only: recompose affected guides from the existing KB and recipes,
  reading no source and re-verifying no fact, because a pure-prose change moves no fact. Its guardrail
  is a hard stop: the moment an edit would change what a guide asserts about the SDK, it hands
  off to /refresh-docs (source changed) or /review-guide (verify vs. the base) rather than
  silently drifting a fact. This is the technical writer's tight inner loop — tune wording/tone/
  sequence, re-render, repeat — with /review-guide as the final gate.

Encoding the authoring process itself

The web-family guides in #358 were authored by agents, not by hand, and that work followed an
implicit division of labor: a writer, a reviewer reading as an average developer with no prior
knowledge, and a technical-foundation reviewer verifying every claim is true — with adjustments
funneled back into the skills. That division was never named or made repeatable; it lived only in how
the work happened to run. This PR makes it explicit as four roles, split so comprehension happens
exactly once:

Role	Reads	Produces	Cost
sdk-knowledge-author	source (the only role that does)	verified facts in the KB	expensive, scoped/memoized
guide-writer	KB facts	guide prose	cheap
guide-source-verifier	guide + KB	findings (a lookup; escalates gaps)	cheap
guide-newcomer-reviewer	guide	reader-experience findings	cheap

The important correction during design: verification is a consistency check against the knowledge
base, not a re-derivation from source. A guide claim is trustworthy when it matches a verified
fact; a claim with no backing fact is escalated to the knowledge author, not re-verified inline.
That is what keeps comprehension in one place.

Three slash commands drive the lifecycle modes:

• /author-guide — bootstrap: comprehend source into a new KB file first, then compose the guide
  from it, then review.
• /refresh-docs — incremental (the default): a source diff scopes a KB reconcile and a
  guide recompose, reviewing only what changed.
• /iterate-guide — recompose: editorial-only tuning from the existing KB and recipes, no source
  read (the technical writer's inner loop; see the recipes/fragments section above).

The loop is self-improving: durable review findings are funneled back into the right artifact —
reader/voice rules into the skill, structure and shared prose into the recipe or fragment, facts
into the knowledge base — never left as a TODO, so the next guide starts smarter.

Does it actually work? (three proofs)

We ran the workflow on the Node guide as the first real target. It:

• bootstrapped the first node/ knowledge-base file (the stateless ContentfulOptimization model,
  consent axes, cookie ownership, locale precedence — each with a resolvable source pointer);
• refreshed the guide from the pre-current structure (a ## Required setup table, change-narration
  prose) to the current archetype (plain-language intro, ## Before you start, performable verify
  step, source-grounded troubleshooting);
• verified all 41 load-bearing claims against source, and fixed 2 newcomer blockers + 15 friction
  items;
• funneled 6 durable reader-experience rules back into the authoring checklist;
• and surfaced real workflow bugs (agents running an unscoped format:fix), which are fixed here.

The run passing knowledge:check and producing a genuinely better guide — while teaching us where
the workflow itself was underspecified — is the evidence the loop is real, not aspirational.

React Native was then run as a second target, specifically to exercise the reshaped bootstrap
(knowledge-first) order. It held: the knowledge author ran before the guide writer, and the writer
escalated a missing fact rather than re-reading source — direct proof of the read-facts-not-code
discipline. It bootstrapped the first native/ family file, refreshed the guide to the archetype,
resolved 7 no-backing-fact claims by adding each fact from source (none turned out unfounded), and
correctly declined to propagate an onOfflineDrop shape to the iOS/Android sibling guides, since
their Swift/Kotlin source is not yet verifiable here — refusing to compose an unfounded claim is
exactly the discipline working.

The RN guide was then re-run through the full pipeline again — this time against the new
recipe/fragment layer — and that run is the sharpest proof the composition primitive works. The
guide-writer realigned two intro bullets to the personalization-explainer fragment spine, which
reconciled real drift between two already-pipelined guides (RN said the SDK "builds/keeps
consistent" a profile; Node's canonical wording, now the fragment, says "returns/uses to keep
consistent") — the fragment forcing a family back into one voice is precisely what it exists to do.
The same run surfaced three distinct classes of issue, each routed to the correct layer: a defect in
the new artifact (the explainer opener promised "five sentences" but its bullets are multi-sentence
— fixed to "points," and the empirical discovery that some bullets must be composed-around-an-anchor
rather than verbatim), a genuine KB gap (the "Experience API returns a profile" fact lived only in
node/node.md, leaving the RN claim unbacked in shared/ — promoted to shared/concepts.md and
referenced), and ordinary reader-experience fixes (a non-performable verify step, undefined
identifiers). Facts to the KB, structure to the fragment, reader rules to the checklist — the
funnel-back working as designed, on live output.

Then main moved under us — and that became the best proof of all. While this branch was open,
main shipped a managed-CDA rework (#364) that renamed an entire API family:
prefetchOptimizedEntries → prefetchManagedEntries, OptimizedEntryPrefetchDescriptor /
ServerOptimizedEntryHandoff → ManagedEntryDescriptor / ManagedEntryHandoff,
serverOptimizedEntries → prefetchedManagedEntries, a moved getOptimizedEntrySourceKey, plus new
getEntries() batching. Merging it produced conflicts in the knowledge base — and this is exactly the
scenario the whole design exists for. pnpm knowledge:check pinpointed every source pointer the
rename had invalidated, so each stale fact was re-anchored to the current declaring symbol against
the merged source, and main's genuinely-new facts were folded in — rather than a human eyeballing a
2,400-line diff and hoping to catch every renamed symbol. The merge lands with the full base green.
This is the steady-state value proposition demonstrated involuntarily: source changed, the graph
found the affected facts, and drift could not slip through silently.

What is deliberately not done yet

• Native SDKs (iOS/Android). The symbol check uses the TypeScript compiler, so it does not resolve
  Swift/Kotlin symbols. Those guides are not refreshed in this PR; the decision on a native
  symbol-check (vs. file-level pointers) is deferred and called out in the skills.
• A cross-guide consistency check. Replacing the deleted drift-log with a deterministic check that
  greps canonical shared phrases across a guide family is noted as a follow-up.
• guides:check (structural enforcement). The recipe/fragment layer is enforced today by the
  guide-writer and the review roles following it, not by a validator. A guides:check that verifies
  a guide instantiated its recipe's fragments (grepping the verbatim spines) and holds the fixed frame
  order is deferred — the verbatim-spine and fixed-anchor decisions were made precisely to keep that
  future check cheap. Structure is currently agent-enforced; facts remain machine-enforced.
• Recipe alignment of the other guides. Only the RN guide has been re-run through the new
  recipe/fragment layer so far. The other pipelined guides (Node, Web, React Web, Next.js App/Pages)
  already match the extracted fragment spines — since the fragments were extracted from them — but a
  confirming /iterate-guide pass per guide is a follow-up.
• The four remaining stale guides (iOS SwiftUI/UIKit, Android Compose/Views) and the
  decision guide (choosing-the-right-sdk.md) are not refreshed here — the native four are blocked on
  the symbol-check decision above; both are follow-ups that run through the same workflow.

How to review this PR

1. Read the design above — that is the substance. Push back on the model (KB-as-IR), the decisions
   (symbol anchors, deterministic-vs-agentic split, standards posture), and the role decomposition.
2. Skim the mechanics — the grammar in documentation/internal/sdk-knowledge/README.md, the
   recipe/fragment model in documentation/authoring/README.md, the validator in
   scripts/validate-sdk-knowledge.ts, and the skills/commands under skills/ and .claude/. The
   "Guides and the knowledge base" section of CONTRIBUTING.md is the one-screen orientation.
3. Do not attempt to line-review the guide/KB content. Instead, trust the gate: pnpm knowledge:check
   proves every fact resolves to real source. If you want to spot-check, pick one fact in
   node/node.md or native/react-native.md, follow its pointer into packages/, and confirm it is
   true — that is the loop working.

Draft so the design can be discussed before the remaining guides are run through the same workflow.

🤖 Generated with Claude Code

[Charles Hudson (phobetron)]

It might be worth having Alex take a look at this process.

[wiz-inc-38d59fb8d7]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	2
Software Management Findings	-
Total	2

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try using Wiz Code VS Code Extension.

[Lotfi Anwar L Arif (Lotfi-Arif)]

Repo instructions explicitly say not to add eslint-disable, eslint-disable-next-line, or eslint-disable-line unless requested. This adds a file-wide no-console disable. Please restructure CLI reporting to satisfy lint without the disable, or get explicit maintainer approval for the exception.

[Tim Beyer (TimBeyer)]

Fair flag — AGENTS.md does forbid adding eslint-disable without explicit sign-off. Signing off explicitly here, for two reasons:

Precedent. Every CLI script in the repo opens with this same file-wide disable and a descriptive reason:

• scripts/list-npm-package-targets.ts — /* eslint-disable no-console -- This CLI prints machine-readable records and errors. */
• lib/mocks/scripts/generateTypeDefinition.ts, fetchEntries.ts, copyGeneratedTypeDefinition.ts — /* eslint-disable no-console -- CLI */

This file follows that pattern exactly (line 1, with a reason). Restructuring this one alone would make it the odd one out among its siblings.

Reasoning. no-console guards against stray debug logging leaking into library/runtime code. For a CLI whose entire job is to print a validation report, console output is the intended behavior — so a file-wide disable is the honest scope: the whole file is a reporter, not a module with an incidental log. It's categorically unlike a rule such as no-explicit-any, where a disable would mask a real type-safety hazard; there's no accidental side effect being suppressed here, just an intentional output channel.

Leaving as-is on that basis.