---
title: OpenWiki
description: How the generated codebase wiki relates to this Blume site.
---

[OpenWiki](https://github.com/langchain-ai/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

| Surface | Audience | Mermaid | Host |
| --- | --- | --- | --- |
| **This site** (`apps/docs`) | Partners + engineers browsing | **Yes** on `.mdx` pages (Blume `<blume-mermaid>`) | GitHub Pages + `localhost:4322` |
| **OpenWiki** (`openwiki/`) | Agents + local wiki reading | Source has fences; GitHub may render; Blume Pages does **not** auto-import the whole tree | Repo only |

Curated developer pages under [/developers](/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

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

Do **not** run bare `openwiki --update` (local `.worktrees/` can OOM). Ops: [`docs/runbooks/openwiki.md`](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/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](/developers/scalar)). 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`](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/openwiki/quickstart.md)
- [`openwiki/integrations/public-api-and-docs.md`](https://github.com/blinqx-hq/basenet-rebuild-poc/blob/main/openwiki/integrations/public-api-and-docs.md)

Cross-link back: [Partner guides](/partner) · [Public API on this site](/developers/public-api)