Keeping the Wiki in Sync

The Franklin cell wiki has two kinds of page:

1. Hand-authored pages — narrative, architecture, doctrine. Edited directly.

2. Generated pages (*.generated.md) — derived from the substrate sources by

scripts/sync_wiki.py. Never edit these by hand; the drift gate will

overwrite them.

Generated pages stay correct the moment a new schema version or CLI command lands,

because they are rebuilt from the source of truth rather than transcribed.

---

Source of truth

The CLI page is exactly what gaiaftcl --help prints — whoever adds a command

updates that one usage block, and the wiki follows.

---

The flow

Regenerate (after adding/changing a schema or CLI command):

python3 scripts/sync_wiki.py

Download manifest (site/downloads/version.json on deploy) is written by

scripts/build_wiki_site.py (v1 open demo vs v2 keyed sovereign). Re-run the

production site build after changing Download channels or

GaiaFTCL v2 sovereign mesh.

Drift gate (CI / pre-commit — exits non-zero if a generated page is stale):

python3 scripts/sync_wiki.py --check

--check fails when a regenerate would change Schema-Catalog.generated.md or

CLI-Reference.generated.md — i.e. a schema or command landed without the wiki

being refreshed. The fix is always the same: run python3 scripts/sync_wiki.py

and commit the result.

Dead navigation links in _Sidebar.md (a slug with no matching .md) print as a

warning. Add --strict to turn that into a hard failure for CI.

python3 scripts/sync_wiki.py --check --strict

---

Wire it into the commit cycle

Add the drift gate to the repo's pre-commit hook so a stale wiki blocks the commit:

# .git/hooks/pre-commit
python3 scripts/sync_wiki.py --check || {
  echo "wiki out of sync — run: python3 scripts/sync_wiki.py" >&2
  exit 1
}

Or as a CI step alongside the GAMP5 audits.

---

Adding a new schema version

1. Add cells/xcode/Sources/GaiaFTCLCore/NarratorSchemaV<NN>.swift with the

standard header line // NarratorSchemaV<NN>.swift — <one-line purpose>. and a

CREATE TABLE (or migration) body.

2. Run python3 scripts/sync_wiki.py. The new migration appears in the Schema

Catalog automatically — table name, columns, NATS subject, append-only and

federation-cosignature flags are all read from the source.

Adding a new CLI command

1. Route it in GaiaFTCLCLIEntry.swift and add its line to the master usage block

in printUsageAndExit.

2. Run python3 scripts/sync_wiki.py. The CLI Reference picks up the new surface.

---

Federation signing

Generated pages are signed the same way as any wiki section:

gaiaftcl wiki sign --section Schema-Catalog --output wiki/Schema-Catalog-signatures.json
gaiaftcl wiki sign --section CLI-Reference  --output wiki/CLI-Reference-signatures.json

This writes a manifest JSON sealing each page's SHA-256, byte count, canonical

witness, and a federation signature quintet. Until a section is signed it serves

with a substrate-honest pending-signature notice.

---

Publishing

scripts/publish_wiki.sh mirrors the wiki/ tree to the GitHub-hosted wiki

(gaiaFTCL.wiki.git) with a GPG-signed commit. Run it only when you intend to push

the wiki live.