Add the codebase-wiki starter pack — an agent-authored, navigable…

.changeset/codebase-wiki-starter-pack.md

@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": minor
+---
+
+Add the `codebase-wiki` starter pack — an agent-authored, navigable wiki of your codebase. `ok seed --pack codebase-wiki` scaffolds a `wiki/` knowledge base (architecture, modules, flows, concepts, and guides — each with a page template) plus an `OVERVIEW` hub and a generation log. The new `workflow({ kind: "wiki" })` guide drives an agent to generate — and later incrementally refresh — the wiki from source, with mermaid diagrams, cross-linked pages, and source references, tuned by two natural-language knobs (`audience`: internal/public, `depth`: tour/standard/exhaustive). Version-controlled and private by default; the wiki doubles as durable grounding context for future agent sessions.

packages/app/src/components/PackCardGrid.tsx

@@ -2,6 +2,7 @@
 import { Trans, useLingui } from '@lingui/react/macro';
 import {
   ArrowRight,
+  BookMarked,
   Compass,
   FileCheck,
   GitBranch,
@@ -19,6 +20,7 @@ import { cn } from '@/lib/utils';
 const PACK_ICONS: Record<OkPackId, React.ComponentType<{ className?: string }>> = {
   'knowledge-base': Library,
   'software-lifecycle': GitBranch,
+  'codebase-wiki': BookMarked,
   'plain-notes': StickyNote,
   worldbuilding: Compass,
   'writing-pipeline': PenLine,

packages/app/src/lib/desktop-bridge-types.ts

@@ -51,6 +51,7 @@ export interface OkSeedError {
 export type OkPackId =
   | 'knowledge-base'
   | 'software-lifecycle'
+  | 'codebase-wiki'
   | 'plain-notes'
   | 'worldbuilding'
   | 'writing-pipeline'

packages/core/src/desktop-bridge.ts

@@ -267,6 +267,7 @@ interface OkSeedError {
 type OkPackId =
   | 'knowledge-base'
   | 'software-lifecycle'
+  | 'codebase-wiki'
   | 'plain-notes'
   | 'worldbuilding'
   | 'writing-pipeline'

packages/server/assets/skills/packs/codebase-wiki/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: open-knowledge-pack-codebase-wiki
+description: "How to work in a Codebase Wiki project (the `codebase-wiki` starter pack): an agent-authored, source-grounded wiki of the surrounding codebase. Read when the project has a `wiki/` knowledge base with `architecture/`, `modules/`, `flows/`, `concepts/`, and `guides/` sections plus `wiki/OVERVIEW.md`. Carries the per-folder rules and freshness + log discipline, summarizes the audience/depth knobs and source-reference convention, and points to the `workflow({ kind: 'wiki' })` guide for the full generate/refresh procedure. Complements the platform `open-knowledge` skill; does not replace it."
+compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires Open Knowledge MCP server. Installed project-local by `ok seed --pack codebase-wiki`."
+metadata:
+  pack: "codebase-wiki"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# 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 is pack guidance. The platform `open-knowledge` skill still governs every markdown operation (read/write/preview/linking/grounding). 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 — call **`workflow({ kind: "wiki" })`** and follow the phased, STOP-gated guide. 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.
+
+The `workflow({ kind: "wiki" })` guide is the authoritative source for exactly how each knob shapes the output — invoke 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 produce **no dead-link noise** (the graph only tracks `.md`/`.mdx` edges). Never invent paths — reference only files you actually read.
+
+The full rules — the GitHub-URL / relative fallback, the `#Lxx` caveat, and the exact code-span shape — live in the `workflow({ kind: "wiki" })` guide.
+
+## Per-folder rules
+
+**`architecture/`** — One page per architectural area (boundaries, layers, subsystems, cross-cutting concerns). Each: a `mermaid` system-context or component diagram, key components (with source refs), and the design decisions behind them. Uses the `architecture-page` template. At `depth: tour`, modules fold in here.
+
+**`modules/`** — 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 `module-page` template. Skipped at `tour`; sub-module depth scales with the knob.
+
+**`flows/`** — Key end-to-end sequences as `mermaid` sequence / flow diagrams + narrative. Uses the `flow-page` template; add a **Failure modes** section at `exhaustive`. Link every module and concept the flow crosses.
+
+**`concepts/`** — Atomic glossary pages (one term each): definition, why it matters, where it lives in the code. Uses the `concept-page` template. Keep small and densely cross-linked so each concept becomes a hub.
+
+**`guides/`** — Task-oriented "how / where do I change X" walkthroughs: goal, steps, relevant code, gotchas. Uses the `guide-page` template. Populated at `standard`, rich at `exhaustive`, thin/empty at `tour`.
+
+## Freshness discipline (MUST)
+
+`OVERVIEW.md` frontmatter carries `source_commit` — the git HEAD the wiki was last generated/refreshed against. It is the freshness anchor: refresh mode diffs `source_commit..HEAD` to update only the affected pages, then re-stamps it. **Always re-stamp `source_commit` after a generate or refresh run** — a stale anchor silently breaks incremental refresh.
+
+## Log discipline (MUST)
+
+`wiki/log.md` 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 (`architecture-page`, `module-page`, `flow-page`, `concept-page`, `guide-page`). Create with `write({ document: { path, template: "<name>" } })`. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above and in the `workflow({ kind: "wiki" })` guide, not repeated inside document bodies.

packages/server/assets/skills/project/SKILL.md

@@ -489,6 +489,7 @@ Typical day-2 flow: user shares a URL → `ingest` (preserve) → user asks "now
 
 - `knowledge-base` — source-grounded research articles
 - `software-lifecycle` — proposals, decisions, specs
+- `codebase-wiki` — agent-authored wiki of your codebase
 - `plain-notes` — notes + daily journal
 - `worldbuilding` — fiction story wiki
 - `writing-pipeline` — drafts → published

packages/server/scripts/build-skill-bundles.test.ts

@@ -123,11 +123,13 @@ describe('buildPackSkills', () => {
     expect(buildPackSkills(fixture({ discovery: '# d\n', project: '# p\n' }))).toEqual([]);
   });
 
-  test('repo assets — all six starter packs are present to build', () => {
+  test('repo assets — all eight starter packs are present to build', () => {
     const packsDir = join(defaultPaths().skillsDir, 'packs');
     const expected = [
+      'codebase-wiki',
       'entity-vault',
       'knowledge-base',
+      'okf',
       'plain-notes',
       'software-lifecycle',
       'worldbuilding',

packages/server/src/mcp/tools/discover-body.ts

@@ -163,7 +163,7 @@ Six sub-passes, each with its own STOP gate.
 
 ### 5b. Hub identification (⛔ STOP gate 5b)
 
-1. Run \`links({ kind: "hubs" })\` — surfaces existing high-fan-out docs.
+1. Run \`links({ kind: "hubs" })\` — surfaces the most-linked-to docs (highest *inbound* links), i.e. pages already acting as hubs.
 2. For each substantial \`[KB]\` folder (those that got templates in Phase 4):
    - Check if a hub already exists (\`<folder>/README.md\`, \`<folder>/INDEX.md\`, \`<folder>/CATALOGUE.md\`).
    - If yes: don't create a new one (anti-pattern: don't create INDEX.md hubs).