Skip to main content

Wiki Publishing

See also: Tooling and Scripts, CI CD and Deploys, Data Model

The wiki/ folder in the main repo is the wiki — there is no GitHub wiki and no publish workflow (the old publish-wiki.yml mirror was removed 2026-07-19; a private-repo GitHub wiki isn't readable without paying for seats). Agents and contributors read the markdown directly; humans who want a browsable site serve it locally:

Serving the wiki​

bun run wiki:serve   # http://localhost:4201 — pages render from wiki/*.md on EVERY request
bun run wiki:site    # static export → dist/wiki (index.html = Home)

tools/wiki/render-site.ts (+ serve-wiki.ts) renders GitHub-flavored markdown with the wiki conventions intact: [[Page Title]] / [[Alias|Page Title]] cross-links, relative [text](../Page.md) links, _Sidebar.md as the nav, and ```mermaid fences rendered client-side with a vendored mermaid bundle (no CDN — the site works offline). Because wiki:serve renders per request, an edit or a wiki:build regeneration shows up on reload; there is no watcher or rebuild step.

Deployment: every PR gets a wiki preview alongside the app and Storybook — deploy-preview.yml builds dist/wiki and deploys it to a Firebase Hosting preview channel on the stretched-dev-wiki site (1-day expiry; the action comments the URL on the PR). Preview channels are unlisted-URL public — the wiki documents internals, and Harlo accepted that exposure for PR review (2026-08-02). There is deliberately no always-on hosted wiki; if one is ever wanted, that's a fresh decision for NEXT-STEPS.md.

The generated section (wiki/generated/)​

Machine-written pages — never hand-edit them. Every page opens with a visible banner naming its generator, its data source, and the refresh command; all diagrams are mermaid fences, so the pages render on GitHub and in the local site alike. Generated Docs (wiki/generated/README.md — itself generated from the page registry in tools/build-wiki.ts) is the canonical index of the section and the guide for adding a new generated page — this page deliberately doesn't duplicate that table.

Data Model is the older hybrid pattern: a hand-written page whose ERD block is injected between ERD:START/ERD:END markers from the stretched-types README.

Commands and gates​

bun run wiki:build         # regenerate every page whose inputs are available + link-check
bun run wiki:check         # gate (pre-push + CI docs job): stale page or broken link ⇒ exit 1
bun run wiki:bundle:check  # gate for Production-Bundle.md ONLY — needs a fresh prod build
bun run wiki:test          # unit tests for the generators (tools/build-wiki.spec.ts)

Same contract as types:erd / stories / remote-config / tokens: nothing regenerates silently at push time — a stale artifact fails the gate with the command to run, you regenerate and commit. Two timing details:

  • wiki:bundle:check runs right after the production build (after bundle:check) in both the pre-push hook and CI's test job — never in the build-less docs job, and wiki:check never diffs the bundle page. So the page is always checked against the build that just ran.
  • The coverage page merges, it doesn't demand. A project with a coverage-summary.json on disk gets fresh numbers; a project without one keeps its committed row. The gate only fails when data you HAVE disagrees with the page. If a stale summary from another branch trips it, rerun that suite with --coverage (or delete coverage/<project>) and wiki:build.

Editing the wiki (hand-written pages)​

  1. Edit or add a wiki/*.md page (in a PR).
  2. New page? Name it Your-Title.md (hyphens become spaces in the title), add it to wiki/_Sidebar.md and Home, and link it from related pages.
  3. Cross-link with [[Page Title]] (e.g. [[Data Model]]).
  4. Run bun run wiki:check locally before pushing (wiki:build to also refresh generated pages).

When to update a page​

Source files that a page documents carry a pointer of the form:

> 📖 **Wiki:** see [[Page Title]] for … Update that page when you change …

If you touch code behind a 📖 Wiki pointer, update the referenced page in the same change. Generated pages are the exception — they regenerate themselves; you only ever run bun run wiki:build (never hand-edit the output).