name: update-docs
description: Use this skill after any change to `packages/**` source that shifts Tesseron's public surface - protocol messages, exported types, action/resource builder APIs, ActionContext methods, transports, gateway CLI flags, or React hooks - to sync `docs/src/content/docs/` so the Starlight site matches the code. Triggers on "update the docs", "sync docs", "docs are stale after this change", or when a session ends with public-surface edits unaccompanied by doc edits. Do NOT trigger for test-only, tooling-only, or internal refactors that leave the public surface identical.

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.