Docs sync

Keep documentation honest after a release: one agent reads what changed in the code, another reads the docs, and a third writes the fixes. The first two never edit anything.

Find what changed

Point an agent at the range since the last docs update:

beswarm agent start --name changes --agent claude --group docs \
  --prompt "List every user-facing change between tag v1.4.0 and HEAD: new or removed commands, flags, options, defaults, config keys, error messages. Read the diff and the CLI help, not just commit messages. Don't edit files. Write a table to reports/docs/changes.md with file:line for each." \
  --wait --timeout 1200

Find what the docs say

In parallel, have a second agent inventory the docs:

beswarm agent start --name inventory --agent gemini --group docs \
  --prompt "Read every page under docs/. List each command, flag and default they document, with page and heading. Don't edit files. Write to reports/docs/inventory.md." \
  --wait --timeout 1200

Write the fixes

Give the editing agent its own worktree and both reports:

beswarm worktree add --name docs-sync --workspace site
beswarm agent start --name editor --agent claude <terminal-id> --group docs \
  --prompt "Compare ../../reports/docs/changes.md with ../../reports/docs/inventory.md. Update the docs for anything missing, wrong or removed. Match the existing style. Don't document anything you can't find in the code. Run the docs build before you finish." \
  --wait --timeout 1800

Review the diff in .worktrees/docs-sync, merge, then beswarm agent close --group docs.

note

Ask the editor to say where each fact came from. A docs agent that can't find a flag in the code should leave it out, not guess.