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.