README

Wiki tooling

This wiki is generated from the ZCode repo-wiki for the termsprawl workspace, not edited by hand. These two files are the generator and its exclusion list, so the wiki can be regenerated identically.

Regenerating

The source is the repo-wiki ZCode keeps per workspace, keyed by project id:

~/.zcode/v2/repo-wiki/<project-hash>/wiki.json

For this repo the hash is 1be98b513a39 (matching the workspaceKey in task.json). wiki.json holds every page's markdown; draft-pages/ holds the same pages individually.

# 1. note the revision the wiki should describe
cd ~/workspace/projects/termsprawl && git rev-parse HEAD

# 2. export, pinning source citations to that revision
python3 .tools/export-wiki.py \
  --wiki ~/.zcode/v2/repo-wiki/1be98b513a39/wiki.json \
  --out . \
  --blob-base https://github.com/dazeb/termsprawl/blob/<full-sha> \
  --exclude .tools/wiki-exclude.txt

# 3. review, then publish
git add -A && git commit -m "docs: refresh wiki" && git push gitea main

Why --exclude exists

The repo-wiki is generated from the working tree, so it can document work that is not committed anywhere. wiki-exclude.txt lists pages that cite such files. Publishing those would describe unreleased code as shipped and leave source links pointing at paths that 404.

Remove a title from that file once its code is committed, then regenerate. To find which pages have become publishable:

cd ~/workspace/projects/termsprawl
git status --porcelain          # nothing uncommitted -> safe to publish all

What the exporter emits

File	Purpose
<Page Title>.md	one per page, markdown verbatim
Home.md	landing page with the sectioned contents
_Sidebar.md	navigation, grouped by the catalog tree's sections
_Footer.md	provenance — the revision the wiki describes

Source citations in the generated markdown are relative paths with line ranges (src/core/pty-manager.ts#L1-L305), which resolve to nothing in a wiki. --blob-base rewrites them into commit-pinned permalinks so they resolve to the exact revision the page describes. Run without it to leave them as-is.

Titles containing / become - in filenames; every other character is percent-encoded in link destinations, which is what Gitea and GitHub generate themselves for their own wiki URLs.

Publishing to GitHub

GitHub does not create <repo>.wiki.git until a first wiki page exists, and it has no REST API for writing wiki pages, so the first page must be created in the web UI (that has been done — the wiki's root commit is GitHub's own "Initial Home page").

After that, publish by building on GitHub's existing commit rather than force-pushing over it:

git fetch github
git checkout -b github-publish github/master   # GitHub's own root commit
git checkout main -- .                          # lay this content on top
git add -A
git commit -m "docs: publish generated repo wiki"
git push github github-publish:master

Notes:

• GitHub's wiki branch is master; Gitea's is main. Both get the same content; only the branch names differ.
• The two wikis therefore have divergent histories (GitHub's is rooted at its own initial page). Keep main as the working branch and push it to Gitea; keep a github-publish branch based on github/master for GitHub.
• Locally the wiki is a subdirectory of no other repo: termsprawl has no wiki directory, and this repo lives beside it.