update-docs

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

Page	Owns
overview/index.mdx (the root index.mdx)	Elevator pitch, hero copy, top-level links. Rarely changes.
overview/architecture.mdx	Three-process model diagram, protocol boundary descriptions.
overview/quickstart.mdx	The 5-minute path: install, declare one action, run the gateway, see Claude call it.
overview/why.md	Positioning vs browser automation / Playwright / chat widgets.
protocol/index.mdx	One-page protocol overview. Update when a new top-level concept lands.
protocol/wire-format.mdx	JSON-RPC envelope, method names, id rules.
protocol/transport.md	WebSocket URL, framing, origin allowlist, reconnect behavior.
protocol/handshake.mdx	tesseron/hello, welcome, claim code, tools/list_changed.
protocol/actions.mdx	Action declaration, namespacing, invoke / validate / return.
protocol/progress-cancellation.mdx	actions/progress, AbortSignal, actions/cancel.
protocol/sampling.mdx	Handler re-entry into the agent's LLM.
protocol/elicitation.mdx	ctx.confirm and ctx.elicit.
protocol/resources.mdx	Readable / subscribable resource projection.
protocol/errors.mdx	Every defined error code and what raises it.
protocol/lifecycle.mdx	Session state machine, what happens to pending work.
protocol/security.mdx	Origin enforcement, claim flow, trust boundaries.
sdk/typescript/index.mdx	Install, packages/ landscape, first action snippet.
sdk/typescript/action-builder.md	tesseron.action(...) fluent API.
sdk/typescript/standard-schema.md	Zod / Valibot / etc. adapter plumbing.
sdk/typescript/context.md	ActionContext methods: progress, sample, confirm, elicit, signal.
sdk/typescript/resources.md	tesseron.resource(...) builder, subscribe contract.
sdk/typescript/core.md	@tesseron/core exports, custom transport extension points.
sdk/typescript/web.md	@tesseron/web browser adapter.
sdk/typescript/server.md	@tesseron/server Node adapter.
sdk/typescript/react.md	useTesseronAction, useTesseronResource, useTesseronConnection.
sdk/typescript/mcp.md	@tesseron/mcp gateway CLI, config, origin allowlist.
sdk/python/index.md	Planned Python SDK - only update when roadmap changes.
sdk/porting.md	How to port Tesseron to another language.
examples/index.mdx	Table of the example apps.
examples/<name>.md	Individual example app walk-through.

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.