Carbon Docs

Carbon Docs

docs is a built, opinionated documentation site — Fumadocs + Next.js (React 19), light-only, warm-paper aesthetic. It is no longer scaffolded; it exists and ships content. This skill is how to add or change docs in that system, in its house style, grounded in real Carbon code.

Announce at start: "Using the carbon-docs skill — authoring docs for {topic}."

First: ask which kind of page this is

Not all doc pages are equal — a settings toggle does not get the treatment a production flow gets, and the single biggest quality failure so far has been writing every page in the long narrative register. Before any research or writing, ask the user to pick the page type (AskUserQuestion, one question, your recommended type first — infer it from the topic). Skip the question only when the user already named the type in their request, or you're editing an existing page without changing its shape (keep its current type). Several pages in one request → one question covering them.

A page can mix types by section (an entity page that ends with a short settings section) — pick the dominant type for the page, then hold each section to its own shape. Troubleshooting/FAQ content never gets a reader-visible section: it goes in <AgentContext> (see Reference components).

No page ends cold. Every page closes pointing onward: entity and concept pages with a small <Cards> Related row, settings pages with where-it-lives links, guide chapters get "read next" for free. A page that just stops is an IA bug, not a style choice.

The house voice below scales with this choice: full narrative register belongs to Guides; entity pages dial it down to scannable-with-gotchas; settings/how-to pages drop it entirely. On a settings page the reader wants the steps, not an essay — two-factor auth is a 500-word how-to, not an 1,800-word meditation on passwords.

The single biggest mistake is writing plausible ERP-generic prose. Carbon's behavior is specific and often counterintuitive (WIP is a GL balance not a table; a payment is a posted entity applied via settlements; overhead IS absorbed into WIP per production event; fixed-asset disposal is scrapping-only). Every claim is grounded in source. See the prime directive below — it overrides everything.

What Carbon is: a manufacturing system — ERP (the office) + MES (the floor), one platform over one data model. Academy is not a third product pillar: it just hosts training video lessons, not a SaaS app a customer buys. Never frame Carbon as "ERP, MES, and training/Academy"; site, meta, and landing copy stay ERP + MES. (The academy app can appear in an architecture/monorepo listing — fine; describe it as video-lesson hosting, not a pillar.)

The prime directive — ground everything in source

The holy source of truth is the actual source code + the LATEST database migrations (packages/database/supabase/migrations/, newest by timestamp) — NOT ERP/CMMS general knowledge, NOT .claude/rules/ alone (it is often stale).

• Verify before you write. Every entity, status enum value, and transition named in docs must exist in real code. Confirm exact strings ("To Ship and Invoice", "Fully Depreciated"), the actions that drive them (service fns, routes, edge functions in packages/database/supabase/functions/), and what posts/gates (e.g. companySettings.accountingEnabled).
• Read the newest migration, not the first. Timestamps order them; a 2026 refactor may have rebuilt a subsystem the cache still describes the old way.
• Document only real, ACTIVE features. Omit placeholders / inactive / not-yet-shipped things (e.g. integration registry entries with active: false like QuickBooks/Sage). Don't surface them.
• Deliberately undocumented: the Implementation Hub (/x/get-started, packages/onboarding content) stays out of the docs by the user's decision — don't document it, and don't link to it.
• When code and cache disagree, code wins — and note the drift.
• Method: one research subagent per feature → a structured fact sheet with file:line refs (contract in Authoring workflow step 1) → then write from it. This is how every flow in the Guide was built. Don't skip it for anything non-trivial.

Three surfaces (know which you're touching)

Interlink across surfaces and flows: a Guide links into Reference for detail; Reference links back to the Guide for the story. (Guide chapters were given 12 cross-flow links — interlinking is expected, not optional.)

Authoring workflow (every change)

1. Research (grounded) → a fact sheet. Dispatch a research subagent per feature. It must return a structured fact sheet, not prose: entities/tables/columns; exact status strings and which entity owns each; transitions with the action that drives them (service fn / route / edge function) as file:line; gates and settings (companySettings.*, plan features); the real UI labels for every where-to-click; the gotchas a generic description would get wrong; and an explicit "could not verify" list — a gap on that list is more research work, never a writing improvisation. The writer then works ONLY from the fact sheet + the page-type template, and writing stays in the main loop on the main model — no model downgrades for prose; the fact sheet is the handoff, not a license for a weaker writer.
2. Pick the surface + placement (the page type was chosen up front). Guide flow + frontmatter, or Reference folder + meta.json + REFERENCE_GROUPS — run the placement checklist below before creating any new page.
3. Write in the house voice with the surface's real components (below). Lead with a concrete example. Decide media placement yourself as you write — don't wait to be asked. Drop a <Screenshot> slot wherever the reader needs to see the actual UI, with a label naming the real screen + state (the fact sheet's UI labels are the source); use <Figure> only when a registry key genuinely fits. Typical density by page type: settings/how-to 1 (the screen with the switch/steps), entity 1–2 (the list or detail view, or the lifecycle UI), guide chapters one per major beat, concept stubs none. Boy Scout rule: editing an existing Reference page that has no <Screenshot>? Add the one slot its type calls for while you're there — the Reference surface shipped with almost none, and it goes on the media manifest like any new slot. Reuse existing slots on a rewrite; never drop or re-label one that a real capture may already exist for. Slot labels double as the image's alt text once a capture lands, so write them as a description of what's shown (screen + state), never as a caption or a filename.
4. Verify — against the user's running dev server, read-only. They usually have pnpm --filter docs dev up. Never pkill/restart it, run next build, or rm .next under it — verify by fetching pages:

   cd docs
   pnpm exec fumadocs-mdx                 # regen .source if a content/frontmatter change didn't HMR
   curl -sS -X GET http://localhost:3002/docs/<slug> | grep -o "your new heading"   # confirm it rendered
   

   A green pnpm --filter docs build (✓ Generating static pages N/N) is the gold standard — but only in a clean checkout / when no dev server is running. tsc is noisy (a React 18/19 @types skew that next.config ignores) — grep your own files out of the errors rather than expecting zero.

Guides — the flow architecture

Frontmatter (source.config.ts schema):

---
title: From quote to order
description: An RFQ becomes a quote; an accepted quote becomes a sales order.
label: "(I)"          # display marker, roman numeral, per-flow
index: 0              # order WITHIN the flow (0,1,2…)
flow: quote-to-cash   # flow id (omit → defaults to "make-to-order")
flowName: Quote to cash   # flow tab label
flowIndex: 1          # order of the flow in the subnav (0 = first)
---

• Chapters sort by (flowIndex, index). The subnav is a flow switcher; the **sidebar + mobile selector
  • "read next" are scoped to the active flow**. The original 5 chapters (order/build/plan/floor/ship) carry no flow fields and fold into make-to-order (flowIndex 0) via defaults.
• Add a chapter to a flow: same flow/flowName/flowIndex, next index + label.
• Add a flow: new flowIndex + flowName; its chapters start at index: 0, label: "(I)".
• All chapter bodies render server-side on every page (the reader cross-fades, no route nav), so links to /guides/<slug> resolve. No code fences in guides (prose + components only).

Components (components/editorial/mdx.tsx):

• <Figure illustration="flow-overview" caption="…" /> — SVG from the registry. illustration MUST be a real key from components/editorial/illustrations.tsx (else it silently renders nothing). Valid keys: flow-overview, order-split, bom-tree, demand-forecast, planning-engine, shopfloor-loop, eight-d, traceability-graph, method-types, kit-vs-subassembly, reorder-policy, outside-processing, mes-station, issue-workflow, schedule-board, get-method, conversion-factor, opportunity-thread, cash-cycle, rfq-fanout, receive-bill-axes, wip-inflow, wip-to-cogs, depreciation-curve, asset-exit. For anything without a fitting key, use <Screenshot> instead — don't invent keys.
• <Screenshot label="Sales order dashboard" caption="…" ratio="wide|tall|square" /> — a standing slot for a real Carbon capture. Use it where the reader needs to see the actual UI (dashboard, a specific form/field, status, board, where-to-click) — not as decoration. Label the real, current screen + state precisely (verify it exists) so a real screenshot can drop straight in and the docs stay synced to the live Carbon UI. Default ratio="wide".
• <Callout tone="neutral|blue|green|amber" badge="WHY BATCH" title="…">body</Callout> — the workhorse. Use it to carry the Carbon-specific truth a generic description gets wrong. Tones: blue = explanatory "why", green = good-to-know/outcome, amber = caution/contrast, neutral = definitional.
• <Divider /> — closes a chapter before its wrap-up line.
• <Term>make to order</Term> — inline glossary term: dotted-underline; click/tap opens a popover with a grounded one-line definition + an optional "Learn more" link. Same component on both surfaces; definitions live in @carbon/glossary (packages/glossary/src/terms.ts), rendered by docs/components/editorial/glossary.tsx. See "Interlinking & the glossary" below.

Each ## heading becomes a sidebar rail entry — so structure chapters as 3–5 ## sections.

Reference — entity pages

• Frontmatter: title + description (+ plan for a paid-feature gate).
• Placement checklist — run it BEFORE creating any page. (1) Does an existing page already own this topic? Grep content/docs for the feature name; if a page covers it, extend that page with a section instead of creating a parallel one — a bucket page that re-documents features owned elsewhere is scattering, not architecture. (2) One noun per page. (3) If genuinely new: which sidebar group does it belong to (REFERENCE_GROUPS, next bullet)? If none fits, propose a group to the user rather than letting the page dangle ungrouped. (4) Sub-folders are exceptional — one entity = one page; change-orders/ is the only folder today, and splitting a feature across a new folder needs the user's sign-off first.
• Nav is TWO layers — miss the second and your page dangles at the bottom of the sidebar. Folders: content/docs/{reference,platform,building,integrations}/. A folder's meta.json pages array is authoritative for membership AND order (top-level section order is the root meta.json) — and the flat Product-reference list is additionally nested into sidebar groups by the hardcoded REFERENCE_GROUPS slug map in app/docs/layout.tsx, whose group order and within-group slug order are what the reader sees. A reference page missing from that map is appended ungrouped after the groups. So adding a reference page = slug into reference/meta.json and into the right REFERENCE_GROUPS group. Don't list index in pages — fumadocs treats index.mdx as the folder index and the nav renders it as "Overview"; listing it duplicates the title as a sibling. Integrations are their own top-level section (content/docs/integrations/) grouped by category — document only active integrations (omit active: false placeholders + commented-out ones).
• Components (components/editorial/reference-components.tsx + components/mdx.tsx):
  • <Callout type="info|note|warn|warning|error|success|tip" title?>…</Callout> — type → badge+tone (info/note→NOTE/blue, warn/warning/error→HEADS UP/amber, success/tip→GOOD TO KNOW/green). Note this is a different Callout API than the Guides one (type vs tone+badge).
  • <Cards><Card title href icon?>…</Card></Cards> — link-card grid (cross-surface navigation).
  • <EnvVars><EnvVar name type? default? required?>…</EnvVar></EnvVars> — field/parameter rows. The env-var page uses these; for an entity's field reference prefer <FieldTable> (below).
  • <FieldTable><Field name type? required?>desc</Field></FieldTable> (components/editorial/field-table.tsx) — the accordion field/parameter reference, the warm-paper take on Fumadocs' TypeTable. Use it for a | Field | Type | Description |-shaped table (item/job/line fields, routing, work-center, reorder/shelf-life policy fields, integration settings). type = the type token (omit when the table has no type column); required only when the source marks it so; the child is the description as MDX (so inline `code`, italics, <Term> render — that's why it's children, not a type={{}} prop). Registered in both mdx.tsx and editorial/mdx.tsx.
  • <StatusFlow entity="job"><Status name accent? branch? terminal?>meaning</Status></StatusFlow> (components/editorial/status-flow.tsx) — an interactive lifecycle widget (selectable pills → a detail Callout showing the meaning) that replaces a linear | Status | Meaning | table. Children in source (lifecycle) order; meanings are MDX. Flags: accent = the single pivotal milestone (≤1, optional); branch = a temporary returnable hold (Paused, On Hold, Needs Approval); terminal = an off-path exit (Cancelled, Voided, Lost, Expired). entity is REQUIRED in practice: it resolves each status's real ERP badge color from @carbon/utils/status-colors (statusColorMaps); omit it and every pill silently renders gray — that is a bug, not a style. If the entity has no map yet, add one to packages/utils/src/status-colors.ts, derived from the module's *Status.tsx component in the ERP (never guessed), then pass it. Use it ONLY for a linear lifecycle — a 2-axis comparison matrix (e.g. invoices sales-vs-purchase) or a small enum list stays a markdown table.
  • <AgentContext>…</AgentContext> — renders nothing on the site; its content ships only to the in-app agent's knowledge base (pnpm run generate:agent-kb → apps/erp/app/modules/agent/kb/, regenerated automatically by check-and-commit). Put troubleshooting/FAQ, exact error strings, and internal mechanics (table names, routes, enum internals) here — reader-facing prose stays free of them. Never write a reader-visible "Troubleshooting" section. About half the Reference pages still have no <AgentContext>: when your fact sheet surfaced exact error strings for a page you're editing, seed or extend its block while you're there.
  • <PlanBadge plan="Business" /> — flags a paid feature. Whole-page gate → set plan: Business in frontmatter; renders a small "Paid" pill inline with the page title (label is fixed to "Paid"; the plan value only feeds the hover tooltip + the banner copy). Section gate → drop <PlanBadge> in-body. Gated features = packages/ee/src/plan.ts. Don't badge free ones (email, exchange-rates).
  • Plan-gated pages also get a full-width announcement bar (components/plan-banner-bar.tsx, PlanBannerBar) rendered by the docs layout (app/docs/[[...slug]]/layout builds a url→plan map from plan frontmatter and passes it in) — sticky under the header, spanning the content area. Adding plan: Business frontmatter is all it takes; the badge and the bar both light up. Don't hand-place a banner in MDX.
  • Licensing model — get this right, it's been wrong before. See docs/content/docs/platform/licensing.mdx (the canonical page). Editions (packages/utils/src/types.ts enum Edition): Community (self-host, AGPLv3 open core), Enterprise (self-host + commercial license), Cloud (managed). EE features = code under packages/ee or any .ee file → require a commercial license per the repo LICENSE.
    • Carbon Cloud = the hosted SaaS at https://app.carbon.ms — NOT the /docs/platform/... deployment docs. Self-hosting recipes (Docker with Caddy, AWS with SST) live under docs/content/docs/platform/self-hosting/.
    • Cloud plans = Starter and Business only. Plan enum also has Partner, but Partner is internal-only — never mention it in reader-facing docs. Don't write "Business and Partner plans".
    • Never write "self-hosted isn't plan-gated." The runtime gate is Cloud-only (packages/ee/src/plan.server.ts returns early when CarbonEdition !== Edition.Cloud), but the license still governs: self-hosting runs in community mode; Enterprise/EE features need a commercial license. Frame it as a license boundary, not a technical lockout — features aren't "disabled" in Community.
  • <Steps>/<Step>, <Tabs>/<Tab> (fumadocs-ui), markdown tables, and code fences (dark panel).
  • <Term id?>…</Term> — inline glossary term (dotted underline → definition popover). The same component as the Guide; see "Interlinking & the glossary" below.
• Voice is more technical/scannable than the Guides — fields, constraints, tables — but still names the gotcha and links back to the Guide for the narrative.

House voice

Calibrated by the page type chosen up front: Guides get the full register below; entity pages keep the grounding and the gotchas but stay scannable; settings/how-to pages take only "quote real names exactly" and "ground every where-to-click" — no narrative, no rhetorical asides, no answering questions nobody asked. Cutting to budget beats compressing: drop whole asides, don't shorten every sentence.

• Active voice, second person, one term per concept. Never alternate synonyms for the same thing ("API key" one paragraph, "API token" the next) — the glossary term is the term, everywhere. No colloquialisms or idioms; the catalogs are translated and idioms don't survive it.
• Never state the obvious. "Click Save to save" documents nothing. A step earns its place by carrying something the button label doesn't already say.
• Short paragraphs — split at the idea boundary. A paragraph is one idea in 2–4 sentences (~70 words). When a draft paragraph carries two ideas ("what it is" AND "how time splits back"), break it in two rather than chaining clauses; a wall of prose is skipped, not read. Callout bodies obey the same cap. The gate below flags any prose paragraph over ~480 characters.
• Every page stands alone. A reader (or an AI retriever) lands cold from search: state the context and prerequisites in place rather than leaning on the previous page. How-to/settings pages name their prerequisites explicitly before the steps ("needs settings update permission", "requires the Slack integration connected").
• Second person, concrete, narrative. Anchor in the running example (the 90-unit humanoid-robot order). "Open the sales order dashboard." / "You don't build 90 robots as one monolithic job."
• Quote real status names exactly, in quotes: **"To Ship and Invoice"**, **"Posted"**, **"Open"**. Status strings live on a specific entity — confirm whether a value belongs to the header or the line (e.g. "To Ship and Invoice"/"To Invoice" are salesOrderStatus, NOT the salesOrderLineStatus enum Ordered/In Progress/Completed) before you attribute it, and state the transition fully (an order at "To Ship and Invoice" flips to "To Invoice" once everything has shipped but isn't billed — don't imply it sits at one value until fully closed).
• Em-dashes are rationed — count them. Hard budget: at most 1 per ~150 words of body prose (a 600-word page gets 4, total), never two in one paragraph, never a dash-pair parenthetical in an opening sentence, and none in title=, caption=, or frontmatter strings. Default to a period, comma, or colon; most dashes read better as two sentences. Do NOT mimic the dash-heavy style of this skill file or of older pages — "too many em-dashes" is the single most common copy note this project gets. Before declaring a page done, count (grep -o '—' <page>.mdx | wc -l) and cut to budget; when delegating prose to a subagent, put the budget in its prompt verbatim.
• Keep the running example's nouns and numbers exact. It's the sales order (don't drift to a bare "order" when instructing the reader) and it's 90 units (not "a robot"). Once you name the entity and the quantity, stay consistent every time — drift is what makes a tour feel sloppy.
• Ground every "where to click." When you tell the reader to act in the UI, copy the real button / modal / field labels from the JSX (in quotes) and confirm the capability exists on that exact path. A feature that lives elsewhere is not the same as one on the screen you're describing — "Carbon splits the order into three jobs" was wrong: the sales-order line's "Make to Order" → "Convert Line to Job" dialog makes one job per click (the N-jobs-of-M split is a separate bulk-jobs flow). Verify the action, not just the concept.
• Callouts carry the counterintuitive truth — the thing people get wrong. Title is a claim, body is the why. ("Quotes are optional — the opportunity is the thread.")
• Answer the reader's cross-question where it arises. Every claim raises a next question in the reader's head ("what if the job already started?", "does this touch existing orders?", "can I undo it?"). Anticipate the one or two most likely at each step and answer them inline, at that point in the prose — a short sentence, a Callout, or a <Term> gloss — never deferred to a separate FAQ section or page. Ground the answer in source like any other claim; if you can't answer it from code, that's a research gap, not a skip. A section that leaves its obvious "but what about…" hanging isn't done.
• Explain the why, name the mistake, point to the next step. If a paragraph does none of those, cut it.
• Interlink at natural seams ([make-to-order tour](/guides/order)).
• Lead, don't label. Don't open a page with a generic, repeated heading — no ## Introduction on guide chapters (the chapter title is rendered for you) and no ## Why it matters on reference pages. Open with 1–2 substantive lead sentences, then go straight to the real sections. A heading that's identical on every page is filler. Landing/index pages are "Overview", never "Introduction".
• Name things as they are now. Use a feature's current name; never narrate rename/removal history ("formerly item rules", "storage units used to…"). When an old name and the code disagree, the code wins.

Interlinking & the glossary

Two linking mechanisms — use both, deliberately, every time you touch a page. Internal linking compounds: a page that links out and glosses its jargon is worth more than the same prose in isolation.

• Markdown links carry navigation. Link the noun, inline, at natural seams; never "click here". A Guide links into Reference for fields; Reference links back to the Guide for the story ([make-to-order tour](/guides/order)). Cross-surface and cross-flow links are expected, not optional. But link only when the destination's title echoes your anchor text. A hard jump whose landing page has a different H1 disorients the reader — linking the phrase "quote to cash" to a chapter titled From quote to order got flagged as confusing. When the anchor is a concept (a flow name, a category) rather than a page literally called that, gloss it as a <Term> (definition popover + optional "Learn more" via href) instead of a bare link — the reader gets the meaning in place and can still navigate if they choose.
• <Term> carries definitions. Wrap a manufacturing/Carbon term a reader can hit cold (method type, replenishment system, WIP, outside operation, kit/subassembly…) so a click gives the gloss without leaving the page.
  • <Term>make to order</Term> slugifies the text to find the entry; <Term id="make-to-order">made</Term> when the display text differs from the slug.
  • First occurrence per page only — not every instance. Underlining every "order" is noise.
  • Definitions are a single source of truth: @carbon/glossary (packages/glossary/src/terms.ts), where each entry is slug → { term, definition } with term/definition as Lingui msg descriptors (rendered by docs/components/editorial/glossary.tsx). Add the entry there before you use a new term, and ground the definition in source (the prime directive applies — exact enum values, real behavior). Omit href when there's no dedicated page yet (the popover still shows the definition); the "Learn more" link auto-hides when it would point at the page you're already on.
  • Unknown slug → renders as plain text (never breaks prose) — a typo fails safe, not loud.

Enrichment pass. Whenever you create or edit a page, finish with a linking pass: wrap first-occurrence jargon in <Term>, add markdown cross-links at the seams, and add any missing glossary entries. Cheapest way to raise the whole site's connectivity.

Design / styling

• Light-only. Warm-paper palette: page bg #FBFBF9 / #F5F5F2; ink #262323 (+ rgba(38,35,35,0.x) for faint); accent #1E84B0 (links) / #00B0FF (focus/brand); hairlines #E7E7E3 / #E3E3DF.
• Inline Tailwind arbitrary values (text-[15px], bg-[#FBFBF9], border-[#E7E7E3]) — this app is standalone (NOT @carbon/react, NOT the ERP theme). Match the surrounding component's density and colors; don't introduce a new palette.
• Fonts: DM Sans (body), Fira Code (mono). Callout tone fills/borders: neutral #EFEFEB/#DADAD5, blue #DFF5FF/#A9DAF3, green #E4F8DA/#A8DB91, amber #FFF2D8/#E6CFA3.

Gotchas (hard-won)

• Frontmatter is YAML — never leave an unquoted colon in a value. A title:/description: value containing : (colon-space) is parsed as a nested mapping and throws YAMLException: bad indentation of a mapping entry. Either quote the whole value (description: "How it works: the short version.") or reword to drop the colon (a comma/period is usually the better fix). One bad frontmatter 500s the entire site, not just that page — fumadocs loads the whole source collection at module load, so the symptom is every page (guides included) returning 500 with the offending .mdx path in the stack. This bites hardest during an em-dash sweep: replacing a description: em-dash with a colon silently breaks YAML. pnpm exec fumadocs-mdx regen does NOT catch it (it passes) — the only reliable check is fetching a page (any page) and seeing 200 vs 500. When you delegate prose edits to subagents, tell them explicitly: in frontmatter, never introduce an unquoted colon.
• Shiki theme (source.config.ts → rehypeCodeOptions.themes): set both light and dark to the same "github-dark-default". A single theme (or a missing github-light) breaks the build for any content/docs file with a code fence (ShikiError: Theme github-light not found). Guides have no fences, so they're immune — handy for isolating a red build to the Reference side.
• Regen .source before typecheck after any frontmatter/schema change (the schema is baked into .source/ at generate time).
• Figure keys must exist — see the list above; a typo renders nothing, silently.
• Inline code chips are for identifiers, never statements. A full command, SQL statement, or long path in an inline `…` span renders as one unbroken chip that can overflow its container — anything that reads as a line of code goes in a fenced block (fences are fine inside Callouts), and inline stays for short tokens (companyId, crbn_…, Settings → X labels stay plain bold).
• Bare {…} in MDX is a JS expression. A token in prose like {item.id} (e.g. inside an example rule message) fails the build with item is not defined. Wrap any literal braces/tokens in backticks: `{item.id}`.
• Write blocks on existing files — natural collision protection when a parallel session co-writes the docs. Just write the next uncovered gap; don't pause to coordinate unless asked.
• curl GET can 405 in this sandbox (a method-less request reads as POST) — use the WebFetch tool for external pages; the pnpm registry works fine.
• Don't hand-edit the API reference (generated) — change the generator/schema and rebuild.

Deep-dive references (read when you reach the relevant phase)

• references/components.md — full component APIs for both surfaces + the illustration registry.
• references/writing-guide.md — the voice, the grounding rule, worked examples.
• references/information-architecture.md — the flow IA and the Reference meta.json nav.
• references/design-language.md — palette, fonts, the inline-Tailwind convention.

Note: references/scaffold.md, references/brand-integration.md, and assets/templates/* are scaffolding-era (how the app was first stood up, with Geist/@carbon/react/signature-touch templates). The app diverged from them. The live components in docs/components/{editorial,api}/ are the source of truth — read those, not the templates, when in doubt.

Verification bar

Mechanical gate — run on every touched page BEFORE the re-read; each must come back clean. These are deterministic, so there is no judgment call to get lazy on:

Measure READER-VISIBLE content only — raw wc -w counts frontmatter and the invisible <AgentContext> block too, overstating a page by up to 40% and making budgets meaningless:

awk '/<AgentContext>/{s=1} !s{print} /<\/AgentContext>/{s=0}' <page>.mdx | wc -w              # words vs the type's budget
awk '/<AgentContext>/{s=1} !s{print} /<\/AgentContext>/{s=0}' <page>.mdx | grep -o '—' | wc -l  # em-dashes ≤ 1 per ~150 words
grep -n '<StatusFlow>' <page>.mdx                         # bare = gray pills; must carry entity="…"
grep -nE '^(title|description): [^"]*: ' <page>.mdx       # unquoted colon-space = YAML, 500s the site
grep -m1 '^description:' <page>.mdx | wc -c               # ≤ ~170 raw (the SEO meta: 150–160 chars of text)
awk '/<AgentContext>/{s=1} !s{print} /<\/AgentContext>/{s=0}' <page>.mdx | grep -vE '^\s*([<#|`-]|$)' | awk 'length>480 {print "long paragraph: " substr($0,1,60) "…"}'   # split any hit at its idea boundary

Plus two eyeball checks no grep covers: a ## Troubleshooting heading may exist only inside <AgentContext>, and every <Figure illustration=…> key is in the registry list.

Never declare docs done without: the mechanical gate passing, the new content rendering (in the user's running dev server, or a clean pnpm --filter docs build), every internal link resolving, any new <Term> glossary entries grounded in source + their popovers rendering, names matching real code, no generic repeated headings, and a re-read that confirms each page says what matters / names the mistake / points onward.

Close with a media manifest. The final report to the user MUST end with the list of images/media the work needs captured — every unfilled <Screenshot> slot on a page you created or touched, one line each: page path — slot label (ratio) — what to capture (screen + state). Build it with grep -n '<Screenshot' <touched pages>. That list is the user's capture worklist; a slot you don't report is a slot that never gets filled. No new slots → say "no new media needed" explicitly. Then record progress (the .ai/plans/ plan file if one exists, + memory). Don't kill or rebuild under the user's running dev server.