Docs Update From Diff

Overview

Inspect local diffs, derive the documentation impact, and update only the repository's docs/ pages. Treat the current code as the source of truth and keep changes scoped, specific, and navigable.

Read references/docs-surface.md before editing if the affected feature does not map cleanly to an existing docs section.

Workflow

1. Build the change set

Start from local Git state, not from assumptions.

• Inspect git status --short, git diff --stat, and targeted git diff output.
• Focus on non-doc changes first so the documentation delta is grounded in code.
• Ignore README.md and other non-docs/ content unless they help confirm intent.

2. Derive the docs impact

For every changed behavior, extract the user-facing or developer-facing facts that documentation must reflect.

• New command, flag, config key, default, workflow, or limitation
• Renamed behavior or removed behavior
• Changed examples, paths, or setup steps
• New feature that belongs in an existing page but is not mentioned yet

Prefer updating an existing page over creating a new page. Create a new page only when the feature introduces a stable topic that would make an existing page harder to follow.

3. Find the right docs location

Map each change to the smallest correct documentation surface:

• End-user behavior: docs/users/**
• Developer internals, SDKs, contributor workflow, tooling: docs/developers/**
• Shared landing or navigation changes: root docs/** and _meta.ts

If you add a new page, update the nearest _meta.ts in the same docs section so the page is discoverable.

4. Write the update

Edit documentation with the following bar:

• State the current behavior, not the implementation history
• Use concrete commands, file paths, setting keys, and defaults from the diff
• Remove or rewrite stale text instead of stacking caveats on top of it
• Keep examples aligned with the current CLI and repository layout
• Preserve the repository's existing docs tone and heading structure

5. Cross-check before finishing

Verify that the updated docs cover the actual delta:

• Search docs/ for old names, removed flags, or outdated examples
• Confirm links and relative paths still make sense
• Confirm any new page is included in the relevant _meta.ts
• Re-read the changed docs against the code diff, not against memory

Practical heuristics

• If a change affects commands, also check quickstart, workflows, and feature pages for drift.
• If a change affects configuration, also check docs/users/configuration/settings.md, feature pages, and auth/provider docs.
• If a change affects tools or agent behavior, check both docs/users/features/** and docs/developers/tools/** when relevant.
• If tests reveal expected behavior more clearly than implementation code, use tests to confirm wording.

Deliverable

Produce the docs edits under docs/ that make the current local changes understandable to a reader who has not seen the diff. Keep the final summary short and identify which pages were updated.