Audit and update all documentation moving parts for ai-platform-engineering. Checks release blog posts, features page, agent docs, homepage version strings, Docusaurus version config, and sidebar completeness. Fixes what is stale and reports what needs manual attention. Use after cutting a release, adding a new agent, or updating platform features.
Audit and update all documentation moving parts for ai-platform-engineering. Checks release blog posts, features page, agent docs, homepage version strings, Docusaurus version config, and sidebar completeness. Fixes what is stale and reports what needs manual attention. Use after cutting a release, adding a new agent, or updating platform features.
update-docs
Audit every documentation surface in ai-platform-engineering and fix what is out of date.
What this skill checks
#
Surface
Stale when…
1
Release blog posts
A git tag exists with no matching docs/releases/ file
2
Homepage version string
Helm --version in docs/src/pages/index.tsx doesn't match latest git tag
3
Docusaurus version config
lastVersion in docusaurus.config.ts doesn't match latest git tag
4
Docusaurus version snapshot
A tag exists but no versioned_docs/version-X.Y.Z/ snapshot
5
Features page
docs/src/pages/features.tsx tiles don't reflect new feature docs in docs/docs/features/
6
Agent docs
A directory under ai_platform_engineering/agents/ has no matching docs/docs/agents/<name>.md
7
Sidebar completeness
A directory under docs/docs/ is not referenced in docs/sidebars.ts
8
Navbar version label
The 0.4.X (Latest) label in the navbar version dropdown is behind the latest tag
Execution context
Runs in two modes:
Coding agent (Claude Code) — runs git, find, grep directly and writes fixes to disk.
Chat-only — renders a checklist of findings; states which files to edit and what to change.
Step 1 — Collect ground truth
Run all of the following in parallel.
# Latest stable git tag
LATEST=$(git tag --sort=-version:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
echo"Latest tag: $LATEST"# All release tags
git tag --sort=-version:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$'# Existing release blog posts (extract version from filename)ls docs/releases/*.md 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | tr'-''.'# Current lastVersion in docusaurus config
grep 'lastVersion' docs/docusaurus.config.ts
# Current Helm version string on homepage
grep -o "'--version [0-9.]*'" docs/src/pages/index.tsx ||
grep -o '"--version [0-9.]*"' docs/src/pages/index.tsx ||
grep 'version' docs/src/pages/index.tsx | grep helm | head -3
# Versioned snapshotsls docs/versioned_docs/
# Agent implementation directoriesls ai_platform_engineering/agents/
# Agent doc filesls docs/docs/agents/*.md 2>/dev/null | xargs -I{} basename {} .md
# Feature doc filesls docs/docs/features/*.md 2>/dev/null | xargs -I{} basename {} .md
# Top-level docs directoriesls -d docs/docs/*/
# Sidebar entries
grep -E "^\s+'[a-z]" docs/sidebars.ts | head -40
Step 2 — Run the audit
For each check, produce a PASS ✅ or STALE ⚠️ result.
Check 1 — Release blog posts
Compare every git tag against docs/releases/.
for tag in $(git tag --sort=-version:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$'); do
slug=$(echo$tag | tr'.''-')
match=$(ls docs/releases/*release-${slug}.md 2>/dev/null | wc -l)
echo"$tag: $match post(s)"done
If a tag has 0 posts → STALE: call /release-docs for that version, or flag for manual creation.
If a post exists → PASS.
Check 2 — Homepage version string
LATEST=$(git tag --sort=-version:refname | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | head -1)
grep -n "$LATEST\|--version" docs/src/pages/index.tsx | head -5
If the Helm --version value ≠ $LATEST → STALE: update HELM_CMD constant and any hardcoded version strings in index.tsx.
Fix: replace every occurrence of the old version string with $LATEST.
Check 3 — Docusaurus lastVersion
grep 'lastVersion' docs/docusaurus.config.ts
If lastVersion ≠ $LATEST → STALE: update lastVersion in docs/docusaurus.config.ts.
Check 4 — Versioned snapshot exists
ls docs/versioned_docs/
If versioned_docs/version-$LATEST/ does not exist → STALE: run:
cd docs && npm run docusaurus -- docs:version $LATEST
Then update docusaurus.config.ts to add the new version entry and set it as lastVersion.
Check 5 — Features page vs feature docs
# Titles in the features page
grep "title:" docs/src/pages/features.tsx | grep -oP "(?<=')[^']+(?=')"# Feature doc files that existls docs/docs/features/*.md | xargs -I{} basename {} .md
For each docs/docs/features/<name>.md that has no matching tile in features.tsx → STALE: add a tile.
Report the list; ask the user which new features to add tiles for before editing.
