gaia-docs-sync

name

gaia-docs-sync

description

Regenerate and commit Class S site-served artifacts after registry changes, then sync documentation across the main repo and the adjacent wiki. Use this skill when: you've changed registry/nodes/, registry/named/, or named-skills.json and need to regenerate docs/graph/* so the live website reflects the update; CI Guard E (docs-cohesion.yml) is failing because Class S artifacts are out of date; someone says "sync the docs", "regenerate docs", "run gaia dev docs", "update the site graph", "commit the Class S artifacts", "website is stale", or "update the wiki"; or you're finishing a registry PR and need to ensure docs/graph/gaia.json, docs/graph/gaia.gexf, docs/graph/gaia.svg, and docs/graph/named/index.json are committed alongside the source change. Also covers updating README.md, docs/index.html, and mirroring changes to the adjacent wiki repo at ../gaia-wiki.

gaia-docs-sync

Keep the live website (gaiaskilltree.com) and the project wiki in lockstep with the registry. GitHub Pages publishes main:/docs as-is — if Class S artifacts aren't committed, the site is dark or stale.

Background: Why two artifact classes

Class P files (registry/gaia.json, registry/named-skills.json, etc.) are gitignored pipeline internals — regenerated by gaia dev docs but never committed. Class S files (docs/graph/gaia.json, docs/graph/named/index.json, docs/graph/gaia.gexf, docs/graph/gaia.svg) ARE committed and are the exact bytes the browser fetches. Any registry change that doesn't include a Class S regen will either break the site or leave it showing old data. CI Guard E in docs-cohesion.yml enforces this pairing.

---

Workflow A — Registry change requires Class S regen

Run this whenever you've modified registry/nodes/, registry/named/, or any file that gaia dev docs reads to produce the site graph.

Step 1: Confirm you're on the right branch

git branch --show-current

Use a docs/*, review/meta/*, or cli/* branch depending on what drove the change. Never regenerate on main directly.

Step 2: Run regeneration

gaia dev docs

This produces both Class P (gitignored, don't touch) and Class S (tracked, must commit). Watch for warnings — gaia dev docs warnings are load-bearing; a silent failure leaves the prior Class S state on disk.

Step 3: Verify Class S files changed

git diff --stat docs/graph/

If docs/graph/ shows no diff but you changed the registry, something went wrong — investigate before proceeding.

Step 4: Stage only Class S artifacts

git add docs/graph/gaia.json docs/graph/named/index.json docs/graph/gaia.gexf docs/graph/gaia.svg

Stage only these files, not the gitignored Class P files. Accidentally staging registry/gaia.json (Class P) introduces a file that .gitignore should own and will cause confusion on the next gaia dev docs run.

Step 5: Commit alongside the source change

git add registry/nodes/ registry/named/   # or whatever source files changed
git commit -m "docs: regenerate Class S artifacts after <summary>"

Keeping the source change and its Class S output in the same commit makes the PR diff self-contained and satisfies Guard E.

Step 6: Push and open PR

git push -u origin <branch-name>
gh pr create --title "docs: <summary>" --body "$(cat <<'EOF'
## Summary
- <what changed in the registry>
- Regenerated Class S artifacts via `gaia dev docs`

## Test plan
- [ ] CI Guard E (docs-cohesion.yml) passes
- [ ] `docs/graph/gaia.json` diff looks reasonable (node count change expected)
EOF
)"

---

Workflow B — Human-authored docs and wiki sync

Run this when editing README.md, docs/index.html, or any page that should also appear on the wiki.

Step 1: Update main repo documentation

Edit the target files in the main repo (e.g., README.md, docs/index.html).

The pre-commit hook may regenerate docs automatically — let it succeed rather than bypassing it.

git add <files>
git commit -m "docs: <summary of changes>"
git push -u origin <branch-name>
gh pr create --title "docs: <summary>" --body "<detailed description>"

Step 2: Pull or clone the wiki

The wiki lives in a separate git repository. Keep it adjacent to the main repo so paths stay consistent.

# First time:
git clone https://github.com/gaia-research/gaia-skill-tree.wiki.git ../gaia-wiki

# Already cloned:
cd ../gaia-wiki && git pull origin master

Step 3: Mirror the changes to wiki pages

Identify which wiki pages correspond to the main-repo changes:

Main repo file	Wiki equivalent
README.md (CLI reference)	CLI-Reference.md
docs/index.html (getting started)	Getting-Started.md
CONTEXT.md (nomenclature)	Home.md

Apply the same technical content. The wiki and main repo must describe identical capabilities — divergence causes user confusion and fails the accuracy constraint.

Step 4: Commit and push wiki directly to master

The wiki has no PR flow — push straight to master.

cd ../gaia-wiki
git add <updated-files>.md
git commit -m "docs: <summary of changes>"
git push origin master

---

Constraints

Do not stamp versions on Class S files. docs/graph/gaia.json, docs/tree.md, and docs/index.html must not carry a version field or banner. The lockstep verifier checks only pyproject.toml, packages/*/package.json — a version stamp on a rendered artifact will break unrelated PRs when they inherit a stale stamp (Issue #807 retro).

Do not manually patch ?v= cache-bust strings. Add new HTML pages to build_html_cache_busting() in scripts/build_docs.py instead — the function auto-applies versioned query strings to all .css and .js references on every gaia dev docs run.

Keep the wiki adjacent at ../gaia-wiki. The clone path is assumed by this workflow and by any scripts that cross-reference both repos.

Auto-sync never touches docs/badges/. The CI auto-sync workflow explicitly skips badge regeneration to prevent stale-snapshot wipes. Badge updates require a human-run infra/badge-* PR.