Skip to content

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

Generated page Built from
Schema Catalog cells/xcode/Sources/GaiaFTCLCore/NarratorSchemaV*.swift
CLI Reference the master usage block in cells/xcode/Sources/GaiaFTCLCLI/GaiaFTCLCLIEntry.swift

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

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.

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 907f4340c2384f44…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.