Maintain Documentation Quality
Keep docs aligned with ship-ai source-of-truth files and leverage Fumadocs components for clarity.
Use this workflow whenever architecture, feature flags, routes, or deployment behavior changes in ship-ai.
Reference set
This docs set should track: README.md, FEATURES.md, DEPLOYMENT.md, docs/OPTIONAL_SERVICES.md, docs/TELEGRAM_BOT.md, and docs/TROUBLESHOOTING.md in the ship-ai repository.
Sync Workflow
Pull and inspect source-of-truth docs
Check what changed in ship-ai docs and manifests before editing site content.
Update matching pages in this docs site
Touch the affected page groups (getting-started, codebase, features, operations, deployment, recipes) and keep terminology consistent with source.
Upgrade structure with Fumadocs primitives
Use components for readability: cards for navigation, callouts for warnings, steps for procedures, tabs for environment variants, files for topology snapshots.
Validate before merging
Run typecheck/build and verify docs rendering for broken links, duplicate/conflicting route slugs, and stale commands.
Fumadocs Component Patterns
Use <Steps> + <Step> for setup/deploy runbooks.
Use <Tabs> + <Tab> when instructions differ by environment.
Use <Callout type="warn"> for destructive commands.
Use <Callout type="info"> for scope and assumptions.
Use <Files>, <Folder>, and <File> to show repo structure.
Keep the tree high-level to avoid drift from low-value file churn.
LLM and Search Hygiene
- Keep docs pages concise, accurate, and route-stable so generated markdown/LLM exports stay useful.
- Refresh crawl-friendly artifacts (
llms.txt,llms-full.txt, sitemap) when major docs structure changes. - Prefer stable section names and explicit code references to improve retrieval quality.
Minimal Validation Commands
bun run typecheck
bun run build