OpenWiki

How the generated codebase wiki relates to this Blume site.

OpenWiki generates and updates a codebase wiki under openwiki/. It is the agent-oriented, in-repo map (and remains local/git — not a separate public host).

Two surfaces, one monorepo

Curated developer pages under /developers mirror the high-traffic OpenWiki topics (architecture, setup, public API) so Mermaid and search work on Pages. Prefer updating those pages when the diagram must show on the live docs site; keep OpenWiki in sync via pnpm docs:openwiki for the full tree.

Safe update

pnpm docs:openwiki
# optional: -- --preflight | -- --dry-run

Do not run bare openwiki --update (local .worktrees/ can OOM). Ops: docs/runbooks/openwiki.md.

Scheduled CI: update + failure reporting + staleness

Two separate scheduled GitHub Actions workflows own this pipeline; neither runs on a per-PR basis, so a stale wiki never blocks unrelated work.

• openwiki-update.yml (nightly) runs scripts/openwiki-update.mjs and commits the refreshed tree. It checks out with fetch-depth: 0 — full history, not a shallow clone — because the wiki agent has to resolve openwiki/.last-update.json’s recorded gitHead against HEAD to know what changed since the last run. A prior version of this workflow defaulted to a shallow clone and failed 16 of 18 runs for exactly that reason, silently: the run went green on unrelated grounds while the update itself never advanced. On failure, the workflow files (or comments on) a single idempotent docs-pipeline-labeled GitHub issue rather than a new issue per run.
• openwiki-staleness.yml (weekly, Monday 07:00 UTC) runs scripts/check-openwiki-staleness.mjs, which reads openwiki/.last-update.json directly and compares it against the real repository state — catching drift the update workflow’s own exit code can miss (e.g. a run that reports success but skips the commit). It warns when the marker is more than 7 days old (--max-days) or HEAD is more than 100 commits ahead of it (--max-commits), or when the marker’s gitHead can’t be resolved against history at all (itself a signal, usually a shallow clone). Like the update workflow, this is a monitor, not a merge gate — it never runs in per-PR CI, and failure reports through the same idempotent docs-pipeline issue pattern rather than failing a build.

Single-source rule

openwiki/INSTRUCTIONS.md is the control-metadata file OpenWiki ≥0.2 injects as wikiGoal on every --init/--update run — not a generated page, and not something an agent should rewrite as if it were wiki content. It hard-excludes .worktrees/, node_modules/, build output, and tool-state directories from every crawl, and it pins the docs-surfaces entry points (Pages URL, local Scalar path, the OpenAPI symlink) so an update run cannot invent an alternate host. Its most load-bearing rule for this integration: do not duplicate OpenAPI JSON into openwiki/ or apps/docs/ as real files — only relative symlinks to packages/api-contract/openapi.json, and do not enable Blume’s embedded Scalar unless @scalar/astro is deliberately hoisted (it isn’t — see Scalar API reference). One generated artifact, three symlinks, is the whole rule; a real copy anywhere is the failure mode this line exists to prevent.

Start in the wiki tree

• openwiki/quickstart.md
• openwiki/integrations/public-api-and-docs.md

Cross-link back: Partner guides · Public API on this site