Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift.
Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each.
docs/.docs/CONTRIBUTING.mdx before writing any content. It contains the current style guide and formatting rules.Determine the commit range. The user may provide one explicitly (e.g., "since v0.2.0" or "last 30 commits"). If not, default to commits since the head of the main branch.
# Commits since a tag
git log v0.2.0..HEAD --oneline --no-merges
# Or last 50 commits
git log -50 --oneline --no-merges
Filter to commits that are likely to affect docs. Look for these signals:
feat, fix, refactor, perf commits often change behavior. docs commits are already doc changes. chore, ci, test commits rarely need doc updates.crates/openshell-cli/, python/, proto/, deploy/, or policy-related code are high-signal.tests/, e2e/, .github/, tasks/, or internal-only modules.# Show files changed per commit to assess impact
git log v0.2.0..HEAD --oneline --no-merges --name-only
For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point:
| Code area | Likely doc page(s) |
|---|---|
crates/openshell-cli/ (gateway commands) | docs/sandboxes/manage-gateways.mdx |
crates/openshell-cli/ (sandbox commands) | docs/sandboxes/manage-sandboxes.mdx |
crates/openshell-cli/ (provider commands) | docs/sandboxes/manage-providers.mdx |
crates/openshell-cli/ (new top-level command) | May need a new page or docs/reference/ entry |
| Proxy or policy code | docs/sandboxes/policies.mdx, docs/reference/policy-schema.mdx |
| Inference code | docs/inference/configure.mdx |
python/ (SDK changes) | docs/reference/ or docs/get-started/quickstart.mdx |
proto/ (API changes) | docs/reference/ |
deploy/ (Dockerfile, Helm) | docs/sandboxes/manage-gateways.mdx, docs/about/architecture.mdx |
| Community sandbox definitions | docs/sandboxes/community-sandboxes.mdx |
If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
For each commit that needs a doc update, read the full diff to understand the change:
git show <commit-hash> --stat
git show <commit-hash>
Extract:
Before editing, read the full target doc page to understand its current content and structure:
# Read the file
Identify where the new content should go. Follow the page's existing structure.
Write the doc update following the rules in docs/CONTRIBUTING.mdx. Key reminders:
shell language for copyable commands, with no $ prompt prefix.text fences for transcripts, logs, or shell sessions that should not be copied verbatim.sidebar-title, keywords, and position when they are relevant. Use frontmatter slug only for folder-discovered pages or absolute URL overrides.sidebar-title for short nav labels. For explicit navigation entries, keep relative slug values in docs/index.yml instead of page frontmatter.page: entries in docs/index.yml. Fern still requires them. If the page defines sidebar-title, set page: to that value. Otherwise set page: to the page frontmatter title.skip-slug: true in docs/index.yml when a child page should live at the parent section path.keywords as a comma-separated string.When updating an existing page:
When creating a new page:
docs/CONTRIBUTING.mdx.docs/index.yml.After drafting all updates, present a summary to the user:
## Doc Updates from Commits
### Updated pages
- `docs/sandboxes/manage-gateways.mdx`: Added `--gpu` flag documentation (from commit abc1234).
- `docs/reference/policy-schema.mdx`: Updated network policy schema for new `tls_inspect` field (from commit def5678).
### New pages needed
- None (or list any new pages created).
### Commits with no doc impact
- `chore(deps): bump tokio` (abc1234) — internal dependency, no user-facing change.
- `test(e2e): add gateway timeout test` (def5678) — test-only change.
After making changes, validate the Fern docs locally:
mise run docs
If a human needs to inspect rendering while iterating, they can also run:
mise run docs:serve
Check for:
<Warning> callout.User says: "Catch up the docs for everything merged since v0.2.0."
git log v0.2.0..HEAD --oneline --no-merges --name-only.feat, fix, refactor, perf commits touching user-facing code.mise run docs to verify.