Wiki Sync

Mirrored from docs/governance/WIKI_SYNC.md (content sha256 e78d45674ffc) by scripts/Sync-Wiki.ps1. Edit the source, not this page -- the next sync overwrites it.

Wiki sync

The GitHub Wiki is a generated reading surface. It owns no fact: every page is either a mirror of one canonical file or an index derived from the source tree. scripts/Sync-Wiki.ps1 is the whole mechanism, and its page map (the $mirrors and $derived tables at the top) is the single list of what is published. Do not repeat that list here.

Why generate, not write

A wiki edited by hand is a second copy of the documentation that nothing keeps honest -- trap 6 in CLAUDE.md, with a web UI. Generating it means a stale wiki is a failed check rather than a surprise. It also keeps this repository the one home for each fact, per the table in CLAUDE.md.

Usage

# One-time: the wiki is its own git repository, cloned beside this one.
git clone https://github.com/dboles99/bachelorpadplus_rust.wiki.git ../bachelorpadplus_rust.wiki

./scripts/Sync-Wiki.ps1            # regenerate pages + metadata/wiki_manifest.json
./scripts/Sync-Wiki.ps1 -Check     # write nothing; exit 1 if the wiki has drifted
./scripts/Sync-Wiki.ps1 -Publish   # regenerate, validate, commit and push the wiki

Run it after any change to a mirrored file, an ADR, or a crate's //! header. Commit the refreshed metadata/wiki_manifest.json with that change.

What it checks before it writes

• Every mirror source exists.
• Every intra-wiki link names a page that exists.
• No page matches a secret pattern (API-key shapes, private-key headers).
• Links from a mirrored file to a repository file that does not exist are reported; -Strict makes them fatal. Those are defects in the source document and are fixed there, not patched in the wiki.

Links to files that are not mirrored become GitHub blob links at the branch named by -Ref (default: the current branch). Once the work merges to main (decision D13), run with -Ref main so the links outlive the feature branch.

What is deliberately not published

project/ (work queue, session notes, open questions), prompts/, and the .bpadx envelope review are internal working material or security review, not product documentation. They stay in the repository, and mirrored pages link to them on GitHub where a source document refers to them. To publish one, add it to the page map in a reviewed change.

The repository is public, so the wiki is too. The exclusions above are what keep internal working material out of it, and the secret-pattern check runs before every write.

Determinism

No timestamps and no model calls: two runs over unchanged sources produce identical bytes, so -Check is exact and a no-op sync commits nothing. Mirror banners carry a content hash of the source, not a date.

Agents

Page content is generated by the script, so no agent writes wiki prose. Agents are used for review, which is where a second opinion earns its cost, and they must come from a different vendor than the author of the change. Their findings are evidence to check against the source, not authority. See CLAUDE.md for the contract every agent works under. (AGENTS.md is an identical local copy that git ignores, so nothing published links to it.)