Wiki maintenance¶

Local setup¶

Run from the independent wiki checkout (Tank Game/Docs) with Python 3.11. Create a virtual environment and install the pinned dependency closure:

python -m venv tooling/.venv
tooling/.venv/Scripts/python.exe -m pip install -r tooling/requirements.txt
tooling/.venv/Scripts/python.exe tooling/validate.py
tooling/.venv/Scripts/python.exe -m mkdocs build --strict -f tooling/mkdocs.yml
tooling/.venv/Scripts/python.exe -m mkdocs serve --strict -f tooling/mkdocs.yml

On Linux/macOS, use tooling/.venv/bin/python in place of the Windows executable. Open the local address printed by serve; stop it with Ctrl+C. The generated site goes to the sibling .wreck-squad-wiki-site directory outside the canonical content tree. Tooling, hidden files, and agent instructions are excluded from site discovery. Never stage generated HTML.

For local Cloudflare automation, copy .env.example to .env and set CLOUDFLARE_API_TOKEN. The real .env is ignored and must remain local.

The site provides hierarchical navigation, page TOCs, search, tags, highlighted code, Mermaid fences, palettes, and edit/source links. Git-derived update dates require repository history; CI checks out full history. The GitHub source view offers each page's History button. Uncommitted edits are not reflected in Git dates.

Edit and review without a site¶

Start in the House lifecycle map, then follow the launch protocol link. Search with rg, edit the canonical Markdown, and update its inbound context map when necessary. No MkDocs installation is needed to read, edit, or review Markdown.

git status --short
git switch -c codex/house-launch-update
rg -n "admission" multiplayer/house-lifecycle/launch-protocol.md
git diff --check
git diff -- multiplayer/house-lifecycle/launch-protocol.md
git add multiplayer/house-lifecycle/launch-protocol.md
git commit -m "docs: clarify House launch admission"
git show --stat HEAD

Push the branch and open a pull request in the private wiki repository. Cross-link game-source commits when ordering matters. A wiki commit and game-source commit are independent; do not stage parent changes as part of wiki work.

Validation and progressive migration¶

New pages require the frontmatter defined in the implementation seed. tooling/legacy-pages.json records the original unstandardized corpus, not a general exclusion pattern. Reviewed legacy pages with frontmatter are validated automatically. Remove their legacy entry when standardizing them so deleting frontmatter cannot bypass checks.

Validation checks section placement and lowercase kebab-case names on all content, plus required metadata, status, and dates on standardized pages. It checks relative Markdown links, images, reference links, and heading fragments across the entire corpus. Links must resolve inside the wiki; source references outside it should use repository URLs. Code examples and external URLs are not checked. Legacy link diagnostics remain informational until those pages are reviewed. The same validator runs as a MkDocs hook, so local strict builds and CI apply identical rules.

The imported debugging/ui-rehost.md uses Windows-1252 characters. Rendering decodes legacy non-UTF-8 pages in memory without rewriting the original bytes. Convert a page explicitly to UTF-8 when standardizing it.

CI and publication¶

Pull requests and pushes to main run validation and a strict build, retaining the site as an Actions artifact for 14 days. Download the artifact through the private repository's Actions run. After extraction, serve it with python -m http.server to use search and navigation in a local browser.

Pushes to main deploy the artifact to the Cloudflare Pages project wreck-squad-wiki, whose canonical hostname is wiki.brickleaf.games. Configure the repository secret CLOUDFLARE_API_TOKEN and variable CLOUDFLARE_ACCOUNT_ID; the token needs Cloudflare Pages: Edit for deployment. The initial proof of concept is public. Before treating it as private internal documentation, enable Cloudflare Access for the custom hostname and both production and preview pages.dev hostnames, then verify unauthenticated requests receive the Access login response.

Configure branch protection to require the build job if merging must be blocked on validation failures. Restrict production deployment to main.