| name | update-docs |
| description | Update documentation in docs/ based on recent code changes. Reads git history since a watermark commit, maps changed files to doc pages, and makes surgical edits to keep docs in sync with code. |
Update Docs
Detect code changes since the last run and update affected documentation pages.
- references/mapping.md — code-to-doc page mapping
- Follow
docs/CONTRIBUTING.md and docs/AGENTS.md for writing style
Workflow
1. Read watermark
Read .claude/skills/docs/watermark for the last processed commit SHA. If the file is missing (first run), use the commit from 30 days ago as the starting point: git log --before="30 days ago" --format=%H -1 main.
2. Gather changes
Run git log --oneline --no-merges --name-only <watermark>..HEAD to get changed files and commit messages since the watermark.
3. Map changes to doc pages
Cross-reference changed files against the code-to-doc mapping in references/mapping.md. Also use judgment for unmapped files (e.g., new crates or modules that clearly affect user-facing behavior).
Filter to user-facing behavioral changes only:
- New features, flags, commands, config options, node types
- Changed behavior, renamed APIs, new integrations
- Bug fixes that affect documented behavior
Skip:
- Internal refactors with no behavior change
- Test-only changes
- CI/CD pipeline changes
- Dependency bumps
- Code style or linting changes
If nothing affects docs, tell the user and stop.
4. Read code and docs
For each affected doc page: read the current MDX file and the relevant source files. Identify sections that are outdated, missing, or incorrect.
5. Update doc pages
Surgical edits only — change only affected sections. Preserve existing voice, structure, heading hierarchy, and Mintlify component usage.
- Add code examples for new features (CLI commands, config snippets, DOT syntax)
- Insert rows into reference tables in logical position
- Add new sections for entirely new capabilities
- Update existing descriptions when behavior changes
- Never edit
docs/api-reference/fabro-api.yaml — that is the API workflow's source of truth
6. Validate DOT examples
If any updated page contains ```dot code blocks with digraph definitions, run ./test/docs/run_tests.sh validate. Fix any failures before proceeding.
7. Write watermark
Write the output of git rev-parse HEAD to .claude/skills/docs/watermark.
8. Summarize
List updated doc pages and what changed in each.
