update-docs

Update Tesseron docs

Keep docs/src/content/docs/ aligned with whatever just changed in packages/**. The docs are the published Starlight site and the contract Tesseron users read, so drift here is user-visible.

Prerequisites

• A recent edit to packages/** (use git diff / git diff --stat HEAD to see the change set).
• The docs tree at docs/src/content/docs/. If it's missing, stop and flag it.

Doc pages and what they own

Process

Step 1 - Inspect the change set

Run these in one go:

git status --short
git diff --stat HEAD
git diff HEAD -- packages/

Focus on exported symbols, public types, protocol method names, CLI flags, and .md/.mdx snippets inside packages. Ignore changes under **/*.test.ts, **/*.spec.ts, **/__tests__/**, tsconfig*.json, biome*.json, .changeset/, and CI config - those don't require doc updates.

Step 2 - Map changes to doc pages

For each modified public surface, find the doc pages that own it via the table above. Also rg across docs/src/content/docs/ for the renamed / changed symbol to catch incidental mentions the owner table misses:

rg --fixed-strings "oldSymbolName" docs/src/content/docs/

Step 3 - Edit the affected pages only

• Prefer Edit over Write. Targeted edits keep diffs reviewable.
• Preserve frontmatter (title, description). They feed both the sidebar and the injected docs index.
• Keep Starlight components intact: Diagram, Card, CardGrid, LinkCard, Code, Tabs, etc.
• Don't introduce em-dashes (-) in user-facing prose - use - or periods. Matches project voice.
• Update version numbers / package exports only when the actual package boundary shifted.

Step 4 - Update frontmatter description if the page focus shifted

The hook at .claude/hooks/inject-docs-index.py derives the injected index from description fields. If a page's scope changed materially (e.g., a method was promoted or removed), rewrite the description so it stays a one-line summary of what the page now covers.

Step 5 - Verify

cd docs && npx astro check

astro check catches broken frontmatter, bad component usage, and broken relative links. If the build is already wired into CI, rely on that instead; otherwise run it locally.

Step 6 - Report back

End your turn with a bullet list:

• Modified packages: packages/...
• Docs updated: docs/src/content/docs/...
• Docs reviewed but unchanged (and why)

What NOT to update

• .changeset/ files - maintained by the release workflow, not by this skill.
• README.md at repo root - stays in sync by hand; mention in your report if it looks stale so the user decides.
• The Starlight sidebar in docs/astro.config.mjs - only touch when a new page is added or a page is deleted, and even then prefer a note in the report so the user confirms ordering.
• Auto-generated TypeDoc / API reference output (if any).

Success criteria

• Every public-surface change is reflected in at least one doc page.
• No orphaned references to removed / renamed symbols remain in docs/.
• Frontmatter title / description accurate on every touched page.
• astro check passes (or CI equivalent).
• Report lists modified packages, updated docs, and reviewed-but-unchanged docs.