Codebase Wiki pack — how to work here
This project holds an
agent-authored wiki of a codebase — DeepWiki, but living in the repo. A coding agent reads the source and writes a navigable, diagram-rich, source-grounded wiki as markdown under
. It is version-controlled and diffable, private by default, human+agent co-editable, renders in OK's live preview, and doubles as durable grounding context for future agent sessions. There is no separate Q&A surface — Q&A is "the OK-grounded agent +
".
This skill is pack guidance. The platform
skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the wiki workflow on top.
The shape
wiki/
OVERVIEW.md hub: what it is, a big-picture architecture diagram, a nav map to every section.
Frontmatter carries `profile` (audience/depth) + `source_commit` (freshness anchor).
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 / core abstractions
guides/ task-oriented "how / where do I change X" (filled at depth >= standard)
Generating + refreshing
Don't free-hand it — read
references/generate-and-refresh.md and follow the phased, STOP-gated procedure. It auto-detects mode: a stubbed
(empty
) →
generate (survey → overview → architecture → modules → flows → concepts → link-graph audit); a stamped
→
refresh (diff
, update only affected pages, re-stamp).
Two toolsets. Read source code with NATIVE tools (
/
/
/
) — OK MCP does not index non-markdown source. Author and audit the wiki with OK MCP verbs (
/
for pages,
/
for the graph). Never hand-write wiki markdown with native
/
.
The two knobs
Two natural-language knobs, read from the user's request (e.g. "build the wiki, public and exhaustive") and recorded in
frontmatter (
profile: <audience>/<depth>
) so refreshes stay consistent:
- — (default) or . means polished prose, no secrets / internal infra / ticket numbers, and GitHub-URL source references.
- — | (default) | . Scales coverage from OVERVIEW + architecture + top flows up through per-package module pages, concepts, and task guides.
references/generate-and-refresh.md is the authoritative source for exactly how each knob shapes the output — read it before generating.
Source-reference convention
- Intra-wiki navigation → OK doc links — they build the backlink / hub / orphan graph, so link liberally; density is how the wiki stays navigable.
- Code references → relative links + symbol code-spans () or GitHub blob URLs (). Source-file links stay out of the navigation graph ( tracks only / edges, so they never show as graph dead-links or orphans) — but a wrong-depth path still surfaces in the write/edit response (, or if it overshoots the content root), so count the hops from the page's folder. Never invent paths — reference only files you actually read.
The full rules — the GitHub-URL / relative fallback, the
caveat, and the exact code-span shape — live in
references/generate-and-refresh.md.
Per-folder rules
— One page per architectural area (boundaries, layers, subsystems, cross-cutting concerns). Each: a
system-context or component diagram, key components (with source refs), and the design decisions behind them. Uses the
template. At
, modules fold in here.
— One page per package / module: purpose, responsibilities, public API / entry points, key files (linked per the convention), dependencies, and flows it participates in. Uses the
template. Skipped at
; sub-module depth scales with the knob.
— Key end-to-end sequences as
sequence / flow diagrams + narrative. Uses the
template; add a
Failure modes section at
. Link every module and concept the flow crosses.
— Atomic glossary pages (one term each): definition, why it matters, where it lives in the code. Uses the
template. Keep small and densely cross-linked so each concept becomes a hub.
— Task-oriented "how / where do I change X" walkthroughs: goal, steps, relevant code, gotchas. Uses the
template. Populated at
, rich at
, thin/empty at
.
Freshness discipline (MUST)
frontmatter carries
— the git HEAD the wiki was last generated/refreshed against. It is the freshness anchor: refresh mode diffs
to update only the affected pages, then re-stamps it.
Always re-stamp after a generate or refresh run — a stale anchor silently breaks incremental refresh.
Log discipline (MUST)
is an append-only audit trail.
Append one dated entry per generation or refresh run — one per run, not per page. Reference touched pages as markdown links (
[Server](./modules/server.md)
) so they register in the backlink graph. Entry shape:
markdown
## YYYY-MM-DD: <generate | refresh>
- Profile: <audience>/<depth>
- source_commit: <short-sha> (was <prev-sha> on refresh)
- Coverage: <sections / packages written or updated>
- Pages: [Overview](./OVERVIEW.md), [Server](./modules/server.md), ...
Templates
Each folder ships a starter template (
,
,
,
,
). Create with
write({ document: { path, template: "<name>" } })
. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above and in
references/generate-and-refresh.md, not repeated inside document bodies.