Docs Update

Whenever a developer finishes implementing a feature in the SDK or the CLI, they invoke this skill to update the docs website, adding or updating the content. That way, every new feature PR opens with its documentation already in place.

Route a source change to the documentation pages it invalidated. Propose the smallest patch that makes them correct again.

Everything you write is read by a developer building a local AI application on QVAC, an open-source ecosystem. docs/website is their developer portal: it teaches how to use the SDK and the CLI, never how the codebase works internally. Write for that reader in Phase 3 and Phase 5.

Run this skill only when the developer asks for it. The source API must be stable. Do not run it mid-implementation: developers iterate on an API several times before it settles, and prose written against a moving surface is the waste this skill exists to avoid.

What this skill reads and writes

There are three observed source packages: packages/sdk, packages/sdk-python, packages/cli. They are read-only.

Never edit anything under packages/**. If a source file is wrong, report it and stop. Fixing source is the developer's job.

The writable surface is defined in references/docs-scope.md. Read that file before writing anything. A write outside the allowlist aborts the run and reverts every patch already applied.

One constraint from that file shapes every phase, so it is repeated here. The SDK and the CLI are each cut into one documentation line per published version, and this skill writes to the current line only — the folder written in parentheses, sdk/(v0.20) and cli/(v0.14). It documents the working tree, which is the release not yet cut; a line already cut documents a release already shipped. Resolve the folder each run, never from memory:

ls docs/website/content/docs/sdk | grep '^(v'
ls docs/website/content/docs/cli | grep '^(v'

The two scripts that read the docs — the Phase 4 router and the Phase 6 parity gate — resolve it the same way and exit 2 if a collection has anything other than exactly one current line. Page paths below are written sdk/<line>/…, and the routing map uses the same placeholder.

Pipeline objects

The skill builds four objects, in order. Each one appears as a block in the final report.

Cardinality:

1 SOURCE_CHANGE_SET  ->  1 DOCS_IMPACT   (always one, never split)
1 DOCS_IMPACT        ->  N pages         (routing is a union of hits)
1 page               ->  N targets       (distinct sections of that page)
1 target             ->  1 reason + 1 patch

DOCS_IMPACT is always a single report. Never split it. Never estimate how many pages it will touch. The router produces the page grouping, deterministically.

You have exactly two jobs in this pipeline, and both are verifiable: describe the change (Phase 3), and judge a concrete page you have in front of you (Phase 4). Nothing here asks you how many independent impacts a change contains. That question has no ground truth, and nothing downstream needs the answer.

States

A state classifies the documentary impact of a change, and decides what the skill does next: proceed to routing, stop and report, or ask the developer a question.

There are eight. Six classify one source file. Two describe the whole run.

The two page-creation states are the same operation on different subtrees, and they are mutually exclusive. Separate them by what the symbol is about, not by where its source file sits. A symbol that performs inference — it takes a prompt, audio, or an image and returns a generated result — is an AI capability. A symbol that acquires, inspects, or prepares a model without performing inference is a model-lifecycle topic. completion and transcribe are the first. downloadAsset and assessModelFit are the second.

Assign the file-scoped states one source file at a time. If one file is unresolved, keep the patches already proposed for the files that routed cleanly.

Both scripts report a single run-level state field, and it is advisory. You own the state machine, not the scripts.

The collector decides only the two states it can prove alone, NO_SOURCE_CHANGE and NO_DOCS_IMPACT, and reports CONTINUE for everything else. CONTINUE is not one of the seven states: it means the script reached no verdict and Phase 3 must judge. The router reports its best guess from the routing signals it can see. Treat either field as a starting point, then refine per file as you work.

The final report carries one state in its header. Choose it this way. If any file is HUMAN_INPUT_REQUIRED, then report HUMAN_INPUT_REQUIRED, and list the resolved patches alongside the pending question. Else if every patch was applied and validated, then report DONE. Else report the state that every file shares.

Decision flow

This is every path through the skill, and every point where it stops. The phases below implement this flow.

Developer finishes the feature
        │
        ▼
  /qv-docs-update
        │
        ▼
Phase 1 — resolve the merge base; collect committed, staged,
          unstaged and untracked changes
        │
        ├── nothing changed ──────────────► NO_SOURCE_CHANGE      STOP
        ├── every changed file `internal` ─► NO_DOCS_IMPACT       STOP
        ▼
Phase 1 — export diff, TSDoc diff, auxiliary context
        │
        ▼
Phase 2 — build SOURCE_CHANGE_SET
        │
        ▼
Phase 3 — classify against the impact policy
        │
        ├── nothing user-facing ──────────► NO_DOCS_IMPACT        STOP
        ├── a generated surface covers it ─► GENERATED_DOCS_ONLY  STOP
        ├── is the behaviour supported? ──► HUMAN_INPUT_REQUIRED  STOP
        │   the repo does not say
        ▼
      DOCS_UPDATE_REQUIRED
        │
        ▼
Phase 4 — run the router
        │
        ├── new_capability_symbols ───────► NEW_CAPABILITY_PAGE
        │   symbol performs inference       four append-only edits,
        │                                   then Phase 6
        │
        ├── new_capability_symbols ───────► NEW_MODELS_PAGE
        │   symbol is model lifecycle       three append-only edits,
        │                                   then Phase 6
        │
        ├── unrouted and user-facing ─────► HUMAN_INPUT_REQUIRED
        │                                   for that source only;
        │                                   routed pages continue
        ▼
Phase 4 — filter each candidate; write one reason for each
        │
        ▼
Phase 5 — write the patch; present the diff
        │
        ├── developer rejects ────────────► revise, present again
        ▼
Apply to disk
        │
        ▼
Phase 6 — five gates
        │
        ├── any gate fails ───────────────► report the error, leave
        │                                   the patches on disk,
        │                                   do not declare DONE    STOP
        ▼
      DONE

Phase 1 — Collect the source change

• Inputs: the current git working tree.
• Outputs: /tmp/qv-docs-scs.json (written by the script), plus three records you gather by hand: export diff, TSDoc diff, auxiliary context.
• Expected result: every changed path in the three packages is accounted for and carries a bucket, across all four git states. A file missed here is invisible to every later phase.

Start with the script. It resolves the merge base, collects changes across all four git states (committed on the branch, staged, unstaged, untracked), and classifies every path into a bucket.

1. Run the collector.

bash .agents/skills/qv-docs-update/scripts/collect-source-changes.sh > /tmp/qv-docs-scs.json

The output has this shape:

{
  "state": "CONTINUE",
  "base": { "ref": "tether/main", "sha": "3f2a91c…", "short": "3f2a91c", "via": "url" },
  "strong_evidence": true,
  "buckets": ["api", "examples"],
  "file_count": 2,
  "files": [{ "path": "packages/sdk/src/client/api/completion-stream.ts", "bucket": "api", "status": "M" }]
}

Each file carries a bucket. The bucket decides which router runs in Phase 4.

The script decides two states on its own. It reports NO_SOURCE_CHANGE when nothing changed, and NO_DOCS_IMPACT when every changed file is internal. Every other run reports CONTINUE: changes exist, and their documentary impact is Phase 3's to judge.

2. If state is NO_SOURCE_CHANGE or NO_DOCS_IMPACT, then stop and emit the no-update report. Else continue.

strong_evidence is true when any of examples, api, or cli-command was touched. Treat it as weight in Phase 3, not as a verdict. Do not put it in the report.

base.via records how the base was chosen: url when a remote points at tetherto/qvac, explicit when the developer passed --base, single-remote when neither applied and the clone has exactly one remote. Report the base with its via. A single-remote base plus an implausible file_count means the base is wrong, so stop and say so rather than routing hundreds of files.

The script cannot read the public export surface. Get it from the barrel, comparing the base against the working tree.

3. If no changed file is in the api or surface bucket, then skip to step 5. Else read the barrel at the base and in the working tree, and record added, removed, and renamed exports.

git show <base-sha>:packages/sdk/src/client/api/index.ts

Compare it against the current packages/sdk/src/client/api/index.ts. The barrel is the authority on what is public.

4. Read the diff of every file in the api and surface buckets, then record each changed function signature and each changed TSDoc block.

git diff <base-sha> -- <file-path>

For an untracked file, read the file directly. There is no diff to read.

5. Gather auxiliary context.

Collect three things: the branch commit messages (git log <base-sha>..HEAD --format=%s), the PR title and body (gh pr view --json title,body, only when a PR exists), and any changed test that exercises an affected symbol. A new test often states new behaviour more plainly than the diff does.

Phase 2 — Build SOURCE_CHANGE_SET

• Inputs: everything collected in Phase 1.
• Outputs: one SOURCE_CHANGE_SET text block.
• Expected result: the block carries every fact the later phases need, so nothing downstream has to reopen the raw diff.

This object is what you read from here on. Do not go back to the raw diff after this phase.

1. Write the SOURCE_CHANGE_SET block in this exact shape.

SOURCE_CHANGE_SET

Base: tether/main @ 3f2a91c (via url)
Packages: packages/sdk

Buckets:
- api:       packages/sdk/src/client/api/completion-stream.ts
- examples:  packages/sdk/examples/completion-events.ts
- surface:   packages/sdk/src/types/generation.ts

Exports:
- changed:   completion() — new optional parameter `maxTokens?: number`
- unchanged: all others

TSDoc:
- completion(): @param maxTokens added

Tests:
- packages/sdk/test/completion-max-tokens.test.ts (new)

Phase 3 — Build DOCS_IMPACT

• Inputs: the SOURCE_CHANGE_SET block, and references/docs-impact-policy.md.
• Outputs: one DOCS_IMPACT text block, and a state.
• Expected result: the block states the change in the user's terms, not the code's, and every later claim in a patch traces back to something written here.

The question here is not "did the code change?". Phase 1 already answered that. Ask two questions instead, and answer both.

First: did a claim the docs make stop being true, or become incomplete?

Second: with the docs exactly as they stand today, can a user use the feature that changed?

The two catch different failures. The first catches a page that went stale. The second catches a page that is still entirely correct and yet leaves the user unable to reach the new capability. A new optional parameter usually makes no existing sentence false, and still leaves the user with no way to learn that the parameter exists. If the answer to either question is bad, the change has documentary impact.

1. Read references/docs-impact-policy.md.
2. Write the DOCS_IMPACT block in this exact shape.

DOCS_IMPACT

User-facing change:
completion() accepts an optional maxTokens parameter.

Public surface affected:
- completion()
- GenerateTextOptions.maxTokens

Behaviour:
- maxTokens caps the total tokens generated in the response.
- Omitted, current behaviour is unchanged.

Generated coverage:
- The API summary will list completion() with the new signature.
- The API summary will NOT describe what maxTokens means. It omits parameter descriptions by design.

Documentary implication:
maxTokens is essential to controlling output, so it belongs on the capability page, per the policy on essential parameters.

3. If the repo does not settle whether the changed behaviour is public and supported, then emit HUMAN_INPUT_REQUIRED, put that exact question to the developer, and stop.

This is the impact ambiguity, not the routing one. It appears when an observable behaviour changed and no barrel export, no TSDoc, no test and no page says whether that behaviour is part of the contract or an accident of the implementation. Documenting an accident is worse than documenting nothing, because the next change silently breaks a promise the docs made. Ask instead of inferring. Phase 4 raises the same state for a different reason: there the behaviour is known and the page is not.

4. If the state is NO_DOCS_IMPACT or GENERATED_DOCS_ONLY, then stop and emit the no-update report. Else continue.

When you claim GENERATED_DOCS_ONLY, name the covering surface in the report. An unnamed claim is not checkable.

Phase 4 — Route to DOCS_TARGETS

• Inputs: /tmp/qv-docs-scs.json, and the DOCS_IMPACT block.
• Outputs: one DOCS_TARGETS block, grouped by page, with a written reason per candidate.
• Expected result: every candidate the router produced is either kept with a reason, or dismissed with a reason. None is silently dropped.

The router reads the JSON from Phase 1, not the SOURCE_CHANGE_SET.

1. Run the router.

bun run .agents/skills/qv-docs-update/scripts/route-docs-targets.ts --input /tmp/qv-docs-scs.json

The output has this shape:

{
  "state": "DOCS_UPDATE_REQUIRED",
  "base": { "ref": "tether/main", "sha": "3f2a91c…", "short": "3f2a91c", "via": "url" },
  "r3_used": false,
  "high_page_count": false,
  "new_capability_symbols": [],
  "pages": [
    {
      "page": "sdk/(v0.20)/ai-capabilities/text-generation.mdx",
      "targets": [
        {
          "page": "sdk/(v0.20)/ai-capabilities/text-generation.mdx",
          "section": "Examples › Usage",
          "sectionLevel": 3,
          "via": "R1",
          "source": "packages/sdk/examples/completion-events.ts",
          "evidence": "file=<rootDir>/packages/sdk/examples/completion-events.ts",
          "line": 185
        }
      ]
    }
  ],
  "unrouted": [{ "source": "…", "bucket": "…", "status": "M", "reason": "…" }],
  "discarded": [{ "page": "…", "source": "…", "via": "R4", "reason": "…" }]
}

Read the fields as follows:

• pages[].targets[] are the candidates. Each one is a page section to judge in step 3.
• evidence is the authored binding the router matched. It is a fact about the repo, not a guess.
• line is where that binding sits in the page. Use it to find the section fast.
• section is null on a page-level hit: every R3 hit, and the cli/<line>/http-server/** subtree of R4. The router bound the page, not a section, because the map and the subtree rule name pages only.
• unrouted[] are source files no router could place. Handle them in step 5.
• discarded[] are hits that fell outside the allowlist or hit a path declared undocumented. Copy them into the report. Never re-add them.
• new_capability_symbols[] are new exported symbols in client/api/ with no page. Each one means NEW_CAPABILITY_PAGE.
• r3_used is true only when every hit came from the area map. It is run-level, so a run with one R1 hit and one R3 hit reports false. To weigh a single candidate, read its via field instead: R3 is the declared fallback, so treat an R3 candidate with more suspicion than an R1, R2 or R4 hit.
• high_page_count is true when the router produced more than four pages. It is counted before your filtering, so recount after step 3.

There are four routers, and their hits are unioned. R1, R2 and R4 are exact: each resolves a binding that already exists in the content. R3 is the declared fallback and labels itself as such.

Four router behaviours affect how you read the output:

• R1 has no false-positive mode. No page inlines a full example. A TS example also routes the page that shows its transpiled dist/**.js counterpart.
• R2 takes symbols from the barrel, not the filename. completion-stream.ts exports completion, so the anchor is #completion and never #completionstream. rag.ts exports nine functions and transcribe.ts exports two. Use the same rule when you write a link in a patch.
• R2 also has a secondary pass for a symbol linked somewhere other than its anchor, reported as the weaker binding. text-generation.mdx links the text `batchCompletion()` to the batch-processing page instead of to its API anchor, and carries a paragraph on how that function shares parallel slots. That page is a real target even though the anchor is absent. A symbol mentioned in prose with no link at all is routed by nothing.
• R4 also routes the narrative sections that describe a command outside ## Reference, and for serve/ it adds the whole cli/<line>/http-server/** subtree. That subtree is in the CLI's line, not the SDK's: the HTTP server ships in the SDK and is documented under qvac serve, and the two collections are versioned independently.
• R3 runs per file, not per run. It picks up only the files the exact routers could not resolve. A commit that touches an example and a config module gets an R1 hit for the example, and R3 still runs for the config module. One file's exact hit never suppresses the fallback for another file.

A pages: [] entry in the routing map is a positive declaration that a path is intentionally not documented. It is why a file can be unrouted without becoming a question.

2. Read each candidate section in the page it belongs to.

Judge the page itself, not the diff. Read the section with DOCS_IMPACT in hand.

If section is null, then read the whole page and choose the section yourself, then state that choice and its justification in the candidate's Reason. This is the one place where you pick a target the router did not name, so make the choice auditable rather than silent. If no section on the page fits, dismiss the candidate — do not invent a section for it.

3. For each candidate, answer this question in writing: did this section become incorrect, incomplete, misleading, or materially insufficient after the change described in DOCS_IMPACT?

Keep the candidate if the answer is yes. Dismiss it if the answer is no. Either way, write the reason. A page that routed by accident has no answer to "which claim here went stale?", and that is what removes it.

The Reason field is the contract for the patch. Phase 5 is bound to it, so write it precisely.

4. Write the DOCS_TARGETS block, grouped by page, in this exact shape.

DOCS_TARGETS — 2 pages, 3 targets

sdk/(v0.20)/ai-capabilities/text-generation.mdx
  1. Section: "Features"
     Via:     R2 (completion -> /sdk/reference/api#completion)
     Reason:  the list of generation controls is complete today and would
              become incomplete by omitting maxTokens.
     Action:  list maxTokens among the controls.

  2. Section: "Examples › Usage"
     Via:     R1 (packages/sdk/examples/completion-events.ts)
     Reason:  the introductory sentence describes what the script does, and the
              script now demonstrates the new parameter.
     Action:  update the introductory sentence.

sdk/(v0.20)/configuration/index.mdx
  3. Section: "Reference"
     Via:     R3 (packages/sdk/src/client/config-loader/**)
     Reason:  R3 bound the page and named no section; "Reference" is the only
              section that enumerates config keys, and its key table lacks the
              new one.
     Action:  add the key, its accepted values, and its default.

Dismissed:
- sdk/(v0.20)/ai-capabilities/batch-processing.mdx
  Reason: links completion() only by comparison; no claim went stale.

There is no page limit, and multi-page is a normal result.

The team rule "1 change == 1 scope" describes the scope of the change in the source. It says nothing about how many pages document that change, and the two are different quantities. A new CLI command that reads a new config key is perfectly scoped, and it needs both cli/<line>/index.mdx and the configuration page. Do not drop a target to keep the page count down. The gate against wide routing is the written reason, not a count.

5. If more than four pages survived filtering, then emit this note and continue. It never blocks.

Routing produced 6 pages after filtering. That is allowed but uncommon. Worth
checking whether routing went wide (candidates that should have been dismissed)
or the source change mixes scopes. The patches stand.

6. For each entry in new_capability_symbols[], classify the symbol by the rule in States, then run the matching subprocedure, below. If the symbol performs inference, run NEW_CAPABILITY_PAGE. Else run NEW_MODELS_PAGE.

Both subprocedures also apply to a symbol the router could not place because no page links its anchor yet. R2 binds a page by the /sdk/reference/api#<symbol> link it already contains, so a public symbol that no prose page mentions routes to nothing and reaches unrouted[] whether or not it is new in this run. A symbol in that position, exported from the barrel and listed in the API summary, needs the page the routers found missing rather than a question to the developer. Confirm the absence before creating the page: search the current line, docs/website/content/docs/sdk/<line>/, for the symbol name and for its anchor, and treat a hit under reference/ as no coverage, since the API summary and the release notes are both generated there. Search that line alone — a hit in a line already cut says the symbol was documented for a shipped release, not that the current one covers it.

7. For each entry in unrouted[] that is user-facing and carries no newSymbol, emit HUMAN_INPUT_REQUIRED for that source and ask which page covers the topic.

new_capability_symbols[] is derived from unrouted[], so a new symbol appears in both lists. Step 6 already handled it. Asking about it here would create the page and then ask which page covers the topic.

The answer becomes a new routing-map.yaml entry. That is how the map grows. A source file that is not user-facing needs no question: ignore it.

Phase 5 — Write and apply DOCS_PATCH

• Inputs: the DOCS_TARGETS block, and references/editorial-guidelines.md.
• Outputs: one patch per target, applied to disk after approval.
• Expected result: each patch settles exactly one target's Reason, and changes nothing else.

Work page by page. Close every target on one page before opening the next, so the developer reviews one file at a time.

1. Read references/editorial-guidelines.md.
2. Read the whole target page, then locate the target section by its heading.
3. Write the smallest change that settles that target's Reason, and nothing beyond it.

If the new text asserts something the Reason does not support, it is scope creep or hallucination. Delete it and write it again.

Match the patch to the change type:

4. Present the diff to the developer before writing to disk.
5. If the developer approves, then apply the patch and preserve the rest of the page byte for byte. Else revise the patch and present it again.

Phase 6 — Validate

• Inputs: the applied patches.
• Outputs: a pass or fail per gate, reported in the Validation: block.
• Expected result: all five gates pass, and the state becomes DONE.

There are five gates. Run them in order. If any gate fails, report the error, leave the patches on disk for the developer to fix, and do not declare DONE.

1. List the files this run wrote — the targets patched in Phase 5, plus the registration points when a page-creation subprocedure ran (four for NEW_CAPABILITY_PAGE, three for NEW_MODELS_PAGE) — and check each one against the allowlist in references/docs-scope.md.

Check the files this run wrote, never the dirty working tree. The tree legitimately holds the developer's own changes under packages/**, which Phase 1 collected on purpose. Treating those as scope violations would abort every run. To confirm nothing else in the website was touched, run git status --short -- docs/website/ and verify that every path it lists is one you wrote.

A file outside the allowlist aborts the run. Revert everything already applied. The three restricted files pass only when the diff is an append inside the one block their row names — the AI-capabilities grid in ecosystem/index.mdx and the pages array of ai-capabilities/meta.json under NEW_CAPABILITY_PAGE, the pages array of models/meta.json under NEW_MODELS_PAGE. src/lib/custom-tree.ts is not among them: it declares the sidebars of the two unversioned collections, and this skill adds a page to neither.

2. Run git diff and review the full diff.

Check three things: which files and sections were touched, whether the patch is proportional to the source change, and whether any editorial edit unrelated to the source change slipped in. Remove anything unrelated.

This review is the only gate that catches a well-formed but false sentence. Every other gate catches a broken patch: invalid MDX, a file= pointing at nothing, a dead route. A sentence claiming a default is 512 when it is 1024 compiles, renders, and passes all of them. Do not skip this gate.

The skill relies on the developer here, and that works because the reviewer is the person who just wrote the feature. If this skill is ever run where the reviewer is not the feature's author — a CI companion, a sweep over someone else's branch, a batch over old commits — that premise no longer holds. Say so in the report instead of declaring DONE.

3. Check that every symbol cited in a patch exists in packages/sdk/src/client/api/index.ts, and that every file= directive introduced resolves to a real file on disk.
4. If the run created a capability page, then run the parity script.

bun run .agents/skills/qv-docs-update/scripts/check-capability-parity.ts

It cross-checks all four registration points, verifies the card's icon is imported and matches the sidebar's, and catches registrations pointing at pages that do not exist. Three of the four points fail silently without it: omit the card, the bullet, or the sidebar entry and the build still succeeds, the tests still pass, and the capability is missing everywhere a user would look.

If the run created a models page instead, then check its three registration points by hand: the page file exists and declares an icon:, sdk/<line>/index.mdx carries a bullet linking its URL under ### Utilities, and sdk/<line>/models/meta.json lists its slug. The script does not cover models/. The silent failure is the same one — omit the bullet or the slug and every other gate still passes — so do not skip this because no command reports it.

5. Run the website suites from docs/website/.

bun run test:examples   # file refs, example type-check, transpilation, inline blocks, Python
bun run test            # website suite (link integrity, open graph, …)
bun run build           # static build; catches broken MDX and broken routes

Subprocedure — NEW_CAPABILITY_PAGE

This is not a phase. It is a conditional subprocedure, and it runs only when a change institutes a new AI capability. Two places call it: Phase 4, for each entry in new_capability_symbols[], and Phase 5, for the last row of the patch-shape table. When it finishes, go to Phase 6. Gate 4 exists to validate it.

• Inputs: the new symbol, its example file, and its model family.
• Outputs: four edits: one new page, three appends.
• Expected result: the parity script in Phase 6 passes.

A new capability is not "create an MDX". It is one operation with four points, every time. All four are appends. Nothing else is touched.

The capability belongs to the release being documented, so all of this happens in the current line and in no other. A line already cut shipped without the capability.

1. If the change requires touching any file outside those four, then stop and emit HUMAN_INPUT_REQUIRED. The case is not a new capability.
2. Create the page from the template, and declare its icon in the frontmatter.

A versioned collection composes its navigation from the content, so a page carries its own icon rather than a hand-written tree carrying it. The icon is not derivable from the source: propose a Lucide name, use the same one in the card at step 3, and flag it in the report as needing editorial confirmation.

3. Append the slug to content/docs/sdk/<line>/ai-capabilities/meta.json.

The pages array is explicit and ordered, with no catch-all, so it is the whole of the sidebar for that folder. Without this entry the page is reachable by URL and invisible in navigation.

{
  "title": "AI capabilities",
  "pages": ["text-generation", "…", "image-classification"]
}

4. Append the card and its icon import to content/docs/ecosystem/index.mdx.

The grid lives on the Ecosystem overview — the page the old site index became — and its cards point at the version-less capability URLs, which the current line answers. Both edits are required. Without the import, the build breaks.

import { MessagesSquare, /* … */, Shapes, Eye, Brain, /* … */ } from 'lucide-react'

  <Card href="/sdk/ai-capabilities/image-classification" title={<span className="inline-flex items-center gap-2"><Shapes className="size-4 text-[var(--color-fd-primary)]" />Image classification</span>}>
    Classify images into labels with confidence scores via a customized GGML backend.
  </Card>

If the icon name collides in MDX scope, then alias it. Image is imported as Image as ImageIcon for that reason. The page's frontmatter declares the Lucide export itself, so it reads icon: Image where the card reads <ImageIcon>, and the parity gate resolves the alias before comparing them.

5. Append the bullet to content/docs/sdk/<line>/index.mdx, under ### AI tasks.

That page is the SDK collection overview, the one the old introduction.mdx became.

* [**Image classification:**](/sdk/ai-capabilities/image-classification) assigning class labels with confidence scores to images, via [a customized GGML backend](https://github.com/tetherto/qvac/tree/main/packages/classification-ggml).

6. Use the same icon in the page's frontmatter (step 2) and the card (step 4).
7. Write the card and bullet descriptions from this formula, which is already present as an MDX comment in both files.

{/* <Task name>: <what computation is performed> for <what the developer achieves> via <engine> */}

Base all three strings — frontmatter description, card, bullet — on the same sentence. They describe the same thing at different lengths and must agree.

Subprocedure — NEW_MODELS_PAGE

This is not a phase. It is a conditional subprocedure, and it runs only when a change institutes a new model-lifecycle topic — acquiring, inspecting, or preparing a model, with no inference performed. Two places call it: Phase 4 step 6, and the patch-shape table in Phase 5. When it finishes, go to Phase 6.

• Inputs: the symbol, its example file, and the question the topic answers for a user.
• Outputs: three edits: one new page, two appends.
• Expected result: the page, its slug in models/meta.json, and the bullet all exist and agree.

It is the NEW_CAPABILITY_PAGE operation on the models/ subtree, with one point fewer. There is no card, because the Ecosystem overview's only grid is ## AI capabilities and this topic is not one.

Like a capability, the topic belongs to the release being documented, so every edit lands in the current line.

1. If the change requires touching any file outside those three, then stop and emit HUMAN_INPUT_REQUIRED. The case is not a model-lifecycle topic.
2. Create the page, following the shape both existing models/ pages share.

frontmatter:  title, icon, description, schemaType: HowTo
## Overview
## Functions
<topic sections>
## Example
<Callout type="success"> footer tip

It is close to the capability skeleton and differs in two ways. There is no ## Models section: the topic is about handling models, not about which ones a task supports. And the topic sections carry the page, so they are the bulk of it rather than an optional extra — download-lifecycle.mdx has five, sharded-models.mdx two.

Open ## Overview by naming the function and the question it answers for the user, then link the function to its API anchor. Do not open by naming an inference engine: that opening belongs to capability pages, which have one, and this topic does not.

3. Append the slug to content/docs/sdk/<line>/models/meta.json.

{
  "title": "Models",
  "pages": ["download-lifecycle", "sharded-models", "assess-model-fit"]
}

4. Append the bullet to content/docs/sdk/<line>/index.mdx, under ### Utilities.

Model-lifecycle topics go in ### Utilities, not ### AI tasks. All three existing pages are already there.

* [**Sharded models:**](/sdk/models/sharded-models) download a model that is sharded into multiple parts.

5. Declare a Lucide icon in the page's frontmatter and flag it in the report as needing editorial confirmation.

The icon is not derivable from the source. Unlike a capability, this page has only one icon to choose, since there is no card to keep in agreement.

6. Base the frontmatter description and the bullet on the same sentence. Both describe the topic, at different lengths, and must agree. Keep the description to one line, as both existing pages do.

Report formats

Emit one of these three at the end of the run.

Run with updates:

qv-docs-update — DONE

Source impact:
completion() accepts an optional maxTokens parameter.

Routing:
- sdk/(v0.20)/ai-capabilities/text-generation.mdx  via R2 (symbol)  -> section "Features"
- sdk/(v0.20)/ai-capabilities/text-generation.mdx  via R1 (example) -> section "Examples › Usage"

Generated coverage:
- The API summary covers the signature. It does not cover the parameter's meaning.

Documentation updated:
- sdk/(v0.20)/ai-capabilities/text-generation.mdx (2 sections, +7 −2)

Validation:
- scope ok
- diff reviewed
- grounding ok
- test:examples ok
- test ok
- build ok

Run with no update:

qv-docs-update — NO_DOCS_IMPACT

Changes detected in packages/sdk (buckets: internal, client-other).
No public surface changed; no documentary claim became incorrect or incomplete.

Run partially blocked. The resolved patch survives:

qv-docs-update — HUMAN_INPUT_REQUIRED

Source impact:
completion() accepts an optional maxTokens parameter.

Resolved:
- sdk/(v0.20)/ai-capabilities/text-generation.mdx  "Features"  via R2  +4 −0
  (patch proposed, awaiting approval)

Pending:
- The change in src/types/streaming.ts is user-facing and no router hit. Which
  page covers this topic? The answer becomes a new routing-map.yaml entry.

The proposed patch stands — answering the pending question does not invalidate it.

Out of scope

Do not do any of the following:

• Route by anything other than the four bindings and the declared area map. There is no covers frontmatter, no embeddings, no semantic search.
• Add managed markers inside MDX. The allowlist is path-level only.
• Ground a patch beyond symbol existence and file= resolution. Broad factual validation is v2. The developer reviewing the diff wrote the feature, so they catch a false claim.
• Judge the style guide with a second model pass.
• Trigger this skill automatically. Hook-based auto-detection belongs to a CI companion outside this skill.
• Create a page for anything other than a new AI capability or a new model-lifecycle topic. Those two are derivable from a source change, because a public symbol with no page is a fact the routers report. A new page from an information-architecture decision is permanently out of scope: reorganising pages that already cover their subject is not derivable from a source change. A new CLI command is a new section of cli/<line>/index.mdx. A new Python example is a tab on an existing page, or a section of sdk/<line>/python-sdk.mdx.

Files

• references/docs-scope.md — allowlist, denylist, append-only surfaces.
• references/docs-impact-policy.md — what counts as user-facing impact.
• references/routing-map.yaml — the R3 area map.
• references/editorial-guidelines.md — how to write the patch.
• references/capability-page-template.mdx — skeleton for a new capability page.
• scripts/collect-source-changes.sh — Phase 1.
• scripts/route-docs-targets.ts — Phase 4.
• scripts/check-capability-parity.ts — Phase 6, gate 4.