Docs maintenance

#Update Checklist

When behavior changes, check whether these pages need edits:

• CLI reference for command and option changes
• Usage for common workflow changes
• Configuration for config key changes
• Artifacts for artifact file changes
• Label semantics for label behavior changes
• Troubleshooting for new failure modes
• Operations runbook for scheduler or host changes
• Architecture for contributor-facing module changes
• docs/docs.json for navigation changes

#CLI Drift Check

Compare docs against runtime help:

bun run roark.ts --help

The command list and options in CLI reference should match that output.

#Link Check

List Markdown links:

rg -n '\[[^]]+\]\(([^)]+)\)' README.md docs

For local links, confirm the target file exists and anchors still make sense after heading changes.

#Navigation Check

Every user-facing page should be reachable from at least one of:

• root README.md
• Roark documentation
• docs/docs.json

Pages that are intentionally obscure should say why in their nearest parent page.

#Page Shape

Prefer this structure:

1. what the page is for
2. minimal command or example
3. concepts or reference details
4. failure and safety notes when relevant
5. next steps

#Next Steps

• Use Architecture before changing workflow internals.
• Use CLI reference before changing command help.
• Use Troubleshooting before adding new failure behavior.