Codebase Wiki pack — how to work here

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 wiki/. 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 + search".

This skill is pack guidance. The platform /open-knowledge 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 OVERVIEW.md (empty source_commit) → generate (survey → overview → architecture → modules → flows → concepts → link-graph audit); a stamped source_commit → refresh (diff source_commit..HEAD, update only affected pages, re-stamp).

Two toolsets. Read source code with NATIVE tools (Read/Grep/Glob/Bash) — OK MCP does not index non-markdown source. Author and audit the wiki with OK MCP verbs (write/edit for pages, links/search for the graph). Never hand-write wiki markdown with native Write/Edit.

The two knobs

Two natural-language knobs, read from the user's request (e.g. "build the wiki, public and exhaustive") and recorded in OVERVIEW.md frontmatter (profile: <audience>/<depth>) so refreshes stay consistent:

• audience — internal (default) or public. public means polished prose, no secrets / internal infra / ticket numbers, and GitHub-URL source references.
• depth — tour | standard (default) | exhaustive. 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 (internal) or GitHub blob URLs (public). Source-file links stay out of the navigation graph (links tracks only .md/.mdx edges, so they never show as graph dead-links or orphans) — but a wrong-depth path still surfaces in the write/edit brokenLinks response (no-such-file, or unresolvable if it overshoots the content root), so count the ../ hops from the page's folder. Never invent paths — reference only files you actually read.