Codebase wiki

An AI reads your code and writes a plain-English guide to it: how it's built, how the pieces fit, with diagrams and links back to the real files. The guide lives right in your repo, stays private, and helps the next person (or AI) get up to speed fast. Built on the Codebase wiki starter pack.

A codebase wiki is an agent-authored map of a codebase — architecture, modules, key flows, and domain concepts — written as navigable, diagram-rich markdown that lives in the repo. Think DeepWiki, but the pages are files you own: version-controlled, diffable, private by default, human and agent co-editable, and doubling as durable grounding context for every future agent session.

There's no separate Q&A product bolted on. Q&A is your OpenKnowledge-grounded agent plus search: once the wiki exists, any agent session can read it back, follow its backlinks, and answer "where do I change X?" from pages that cite real source files.

New joiners get a navigable map before they touch anything, ramping in an afternoon instead of reverse-engineering over months. Maintainers generate the architecture once and refresh it as code moves, so they stop re-explaining it to every new contributor. Agent-assisted developers keep the wiki as grounding context, so future sessions read it first instead of rediscovering the same structure. And for OSS, it doubles as a public architecture guide with GitHub-linked sources and no secrets — contributors navigate the project without you.

The shape

wiki/
  OVERVIEW.md     hub: what it is, a big-picture architecture diagram, a nav map to every section
  log.md          append-only generation / refresh audit trail
  architecture/   system boundaries, layers, subsystems, cross-cutting concerns + diagrams
  modules/        one page per package / module: purpose, entry points, key files, deps
  flows/          key end-to-end flows as sequence / flow diagrams + narrative
  concepts/       glossary: atomic pages for domain terms and core abstractions
  guides/         task-oriented "how / where do I change X" walkthroughs

Every section links to the others: a flow page links every module it crosses; a module page links the concepts it implements. That dense cross-linking is what makes the wiki navigable — each concept page becomes a hub for everywhere it appears.

Two knobs: audience and depth

You don't configure the wiki in a settings file — you say what you want in plain language, and the choice is recorded in OVERVIEW.md frontmatter so refreshes stay consistent.

Knob	Values	What it changes
audience	`internal` (default) · `public`	`public` means polished prose, no secrets or internal infra or ticket numbers, and GitHub-URL source references instead of relative paths
depth	`tour` · `standard` (default) · `exhaustive`	Scales coverage from OVERVIEW + architecture + top flows, up through per-package module pages, concepts, and task guides

So "build the wiki, public and exhaustive" and "just give me a quick internal tour" produce very different artifacts from the same pack.

The scenario

You've inherited a 200-file TypeScript service and have to add a feature this week. Instead of grepping blind:

The agent surveys the repo, writes OVERVIEW.md with a top-level architecture diagram, then fills architecture/, modules/, flows/, and concepts/ — each page carrying a mermaid diagram and links to the specific files it read. An hour later you open flows/request-lifecycle.md, see the sequence diagram, follow the link into modules/auth.md, and know exactly where your feature slots in. Next week, after you've merged, refresh updates only the pages your diff touched.

What's in your project after seeding

Pick Codebase wiki in the starter-pack picker, or run:

ok seed --pack codebase-wiki

The pack scaffolds the wiki/ tree above with a stubbed OVERVIEW.md (empty source_commit), a starter template per section (architecture-page, module-page, flow-page, concept-page, guide-page), and wiki/log.md. Each folder's .ok/frontmatter.yml teaches the agent that section's job, so guidance lives next to the action rather than inside every page.

Seeding also installs a skill

ok seed --pack codebase-wiki installs the Codebase wiki project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the generate / refresh procedure, the audience and depth knobs, and the source-reference discipline — read automatically, and editable like any other doc. It lands as a real SKILL.md committed to your repo, one per detected editor. See Skills and what OpenKnowledge writes to disk.

Generate, then refresh

Don't ask the agent to free-hand it. The pack drives generation through a phased, guided workflow that auto-detects which mode you're in:

To update it later, once it exists:

Either prompt works — the pack auto-detects which mode to run from source_commit in OVERVIEW.md:

Generate (a stubbed OVERVIEW.md): survey → overview → architecture → modules → flows → concepts → a final link-graph audit that catches orphans and dead links.
Refresh (a stamped OVERVIEW.md): diff the recorded source_commit against current HEAD, update only the affected pages, and re-stamp.

OVERVIEW.md carries source_commit — the git commit the wiki was last built against. It's the freshness anchor: refresh diffs from it, so the wiki tracks the code instead of drifting into fiction.

Two toolsets, on purpose. The agent reads source code with native file tools (it's not markdown, so OpenKnowledge doesn't index it) and authors the wiki with OpenKnowledge — so every page lands as a real CRDT document with attribution and history. Source references are grounded: the agent links only files it actually read, never invented paths.

Cadence

When	Do
First arrival at a repo	Generate at `standard` depth; skim `OVERVIEW.md` and the architecture pages
Onboarding someone	Point them at the wiki; regenerate at `exhaustive` if they need module-level depth
After a significant merge	Refresh — the agent updates only the pages the diff touched and re-stamps `source_commit`
Going public	Regenerate with `audience: public` for GitHub-linked, secret-free prose