sdk-knowledge-maintenance

name	sdk-knowledge-maintenance
description	Maintain the internal SDK knowledge base under documentation/internal/sdk-knowledge/ — the layer of verified SDK behavioral facts (defaults, fallbacks, ownership, lifecycle, cross-runtime semantics) that each carry a source pointer into packages/**/src. Covers the three-artifact split (guides teach, this KB records verified facts, the authoring skill holds principles — facts never go in a skill), the _template.md skeleton every per-SDK file copies, and capturing shared facts once in shared/ so guide families reuse one canonical wording. Use when adding or editing a per-SDK knowledge file, recording an SDK API you just verified against source while doing other work, reading the KB before re-grepping the SDK, keeping it in sync after the SDK changes, or editing any file under documentation/internal/sdk-knowledge/. Triggers on "sdk knowledge", "internal knowledge base", "record verified facts", "source pointer". Not guide prose and not the authoring skill.
argument-hint	[SDK to record or knowledge file to edit]
paths	documentation/internal/sdk-knowledge/**

Maintaining the internal SDK knowledge base

Use this skill whenever you add to, edit, or read the internal knowledge base under documentation/internal/sdk-knowledge/. It owns the maintenance behavior that keeps that base a trustworthy, verified fact store — so the practice survives beyond any single task. It does not teach SDK facts (those live in the base) and it is not the guide-authoring skill.

Read the base's own documentation/internal/sdk-knowledge/README.md and documentation/internal/sdk-knowledge/_template.md as the canonical source-of-truth for the directory layout and the per-SDK section skeleton. This skill teaches the behavior; those files own the exact shape.

The three-artifact split

Three artifacts, three jobs. Keep each fact in exactly the right one.

• The guides (documentation/guides/) — public, teach-first prose for readers.
• This knowledge base (documentation/internal/sdk-knowledge/) — internal, verified SDK facts, each with a source: pointer. Terse notes, not prose.
• The authoring skill (skills/optimization-guide-authoring) — how to write good guides; transferable principles only.

The load-bearing rule: behavior belongs in the knowledge base; exact interface shape belongs in the types; neither belongs in a skill. A concrete symbol may anchor a behavioral fact without copying its signature, props, or return shape into the base.

Core maintenance behaviors

These are the transferable behaviors this skill exists to preserve.

• Record the current state, not the history that produced it. The base describes how the SDK works now, for a reader who does not know what it looked like before and does not need to. Never write change-ledger language: no "no longer", "now exports", "was removed", "used to", "gains", "newly added", "renamed from", "remains supported", PR/issue numbers, version-bump framing, or "this changed because…". State the fact plainly in the present tense. When the SDK changes, edit the fact in place so it reads as if it were always true — do not append a note about the change or strike through the old value. (Genuine runtime conditionals — "after reading headers the route cannot use ISR" — are present-tense behavior, not history, and are fine.)
• Every fact carries a source: pointer in the grammar. Pointers are machine-checked by pnpm knowledge:check; the grammar is defined in the base's own README.md#source-pointer-grammar and is symbol-anchored — <sdk>#<relpath>#<symbol> (plus impl:, concept:, kb:, extern:), never line numbers (they drift). A fact without a resolvable pointer is a claim, not knowledge — do not add it. Never point a fact at a guide or "the accepted guide" to satisfy the rule; that is circular and the checker rejects it. Anchor on the symbol the fact is actually about. Resolution is a provenance/integrity check, not semantic proof.
• Capture once, as a byproduct of verification. When you verify an SDK API against source while doing other work (writing a guide, fixing a bug, answering a question), record what you confirmed here before the context is lost, with its grammar pointer. Do not run net-new verification passes just to fill the base in; do not re-derive a fact the base already holds.
• Read the base before re-tracing behavior from the SDK. It exists so authors and future regeneration reuse verified behavioral facts instead of re-reading implementation in packages/**/src. Check here first for behavior; only trace source to confirm or extend it. (Interface shape — a signature, prop, or return type — is cheap to look up directly from the types and does not need the base.)
• Keep it in sync when the SDK changes. If a symbol, prop, cookie, config key, export path, or return shape you touched is recorded here, update the entry and its source: pointer in the same change. Stale facts are worse than missing ones. pnpm knowledge:check runs in CI on every change to packages/**/src, so a rename that orphans a pointer fails the build on your PR — fix it here, do not wait for a follow-up.
• Capture shared facts once, in shared/. SDK-neutral concepts go in shared/concepts.md; canonical terms in shared/vocabulary.md. Per-SDK files link to them instead of restating them. This single canonical wording is how a guide family stays consistent: guides reuse it rather than each paraphrasing the same fact.
• Fix cross-guide drift when you find it; do not log it. If a term, API name, or value that must match across a guide family has diverged, reconcile it now — correct the guide, and if the shared wording was missing, add it once to shared/. Do not keep a running list of known-broken things to reconcile later; an unfixed divergence is a bug, not a record. (A per-framework difference that is correct — e.g. NEXT_PUBLIC_ vs a Vite-style prefix — is not drift; state it as a fact in the relevant per-SDK file, not as a divergence to resolve.)

Adding a new SDK file

1. Copy _template.md into the right family directory (e.g. web/, or a new sibling like native/ when a family first needs one — do not create empty family dirs ahead of need).
2. Keep every heading, in the template's order. Fill each section with verified facts and source: pointers.
3. For a section with no entries for this SDK, keep the heading and write None. — never delete the heading.
4. Put anything shared with sibling SDKs in shared/ and link to it; do not duplicate shared vocabulary or concepts into the per-SDK file.

Not in scope

• Guide prose under documentation/guides/ — reader-facing, teach-first; owned by the optimization-guide-authoring skill.
• The authoring skill itself — principles only; it must never accumulate SDK facts.
• Concept docs under documentation/concepts/ and generated TypeDoc under docs/.
• Committing — review owns commits; do not git-commit the base as part of maintenance.

Before you finish

• pnpm knowledge:check passes. This is the gate: it resolves every source: pointer against real files and symbols and enforces the grammar and template. Run it and fix every problem before finishing — do not leave the base in a state that fails the checker. If you touched packages/**/src in the same session, this also catches any recorded fact your change orphaned.
• Every new or changed fact has a resolvable source: pointer in the grammar (symbol-anchored, no line numbers, never pointing at a guide).
• Every entry reads as present-tense current state, with no change-ledger language ("no longer", "now", "was removed", "used to", PR/issue numbers, version-bump framing). Changes were edited in place, not appended as history.
• New per-SDK files match _template.md heading-for-heading, with None. for empty sections.
• Shared facts live once in shared/ and are linked, not restated.
• Any cross-guide drift you noticed is fixed now (guide corrected, shared wording added to shared/ if it was missing), not deferred.
• No SDK fact leaked into a skill; no reader-facing prose leaked into the base.
• Formatting is clean: pnpm exec prettier --write documentation/internal/sdk-knowledge.