Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs(open-knowledge): a workflow page for every starter pack (#2426)

tim-inkeep58a59cb4818f
diff --git a/.changeset/write-template-availability-nudge.md b/.changeset/write-template-availability-nudge.md
new file mode 100644
index 000000000..a3039c891
--- /dev/null
+++ b/.changeset/write-template-availability-nudge.md
@@ -0,0 +1,10 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Nudge agents toward folder templates on write. When a document is created in a
+folder that ships templates but the write passed no `template`, the `write`
+tool now lists the folder's available templates in its result and suggests
+passing one next time. The write still lands unchanged — the hint is advisory,
+so folders that pre-selected a shape stop getting free-form docs just because
+the agent wrote from memory without listing the folder first.
diff --git a/docs/content/meta.json b/docs/content/meta.json
index 7517e2c34..ee64d4832 100644
--- a/docs/content/meta.json
+++ b/docs/content/meta.json
@@ -4,6 +4,8 @@
"pages": [
"---GET STARTED---",
"...get-started",
+ "---WORKFLOWS---",
+ "...workflows",
"---MIGRATE---",
"...migrate",
"---INTEGRATIONS---",
@@ -12,8 +14,6 @@
"...features",
"---ADVANCED---",
"...advanced",
- "---WORKFLOWS---",
- "...workflows",
"---REFERENCE---",
"...reference"
]
diff --git a/docs/content/workflows/codebase-wiki.mdx b/docs/content/workflows/codebase-wiki.mdx
new file mode 100644
index 000000000..ddc60ad7a
--- /dev/null
+++ b/docs/content/workflows/codebase-wiki.mdx
@@ -0,0 +1,128 @@
+---
+title: Codebase wiki
+icon: LuNetwork
+description: "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.
+
+```html preview
+<div style="padding:18px">
+ <div id="loop" style="display:flex;flex-wrap:wrap;gap:10px;align-items:stretch"></div>
+ <div class="cap">The agent reads source with native tools, then authors the wiki with OpenKnowledge — diagrams, cross-links, and source references, one section at a time.</div>
+</div>
+<style>
+#loop .card{flex:1;min-width:150px;border:1px solid var(--border);border-radius:12px;padding:12px 14px;background:var(--card);transition:box-shadow .3s,border-color .3s;cursor:pointer}
+#loop .card .t{font-weight:600;font-size:13px}
+#loop .card .s{color:var(--muted-foreground);font-size:11.5px;margin-top:3px;line-height:1.35}
+#loop .card.on{border-color:var(--primary);box-shadow:0 0 0 3px var(--accent-soft)}
+#loop .card.on .t{color:var(--accent-ink)}
+.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px}
+.cap::before{content:"\21BB ";color:var(--primary);font-weight:700}
+@media (prefers-reduced-motion:reduce){#loop .card{transition:none}}
+</style>
+<script>
+var steps=[["1 · Survey","agent reads the repo: entry points, packages, dependency shape"],["2 · Author","writes architecture / modules / flows / concepts as linked pages + mermaid diagrams"],["3 · Ground","every claim references a real file it read — no invented paths"],["4 · Refresh","on the next run, diffs the commit range and updates only what changed"]];
+var loop=document.getElementById("loop"),cards=[];
+steps.forEach(function(s,i){
+ var d=document.createElement("div");d.className="card";
+ var t=document.createElement("div");t.className="t";t.textContent=s[0];
+ var sub=document.createElement("div");sub.className="s";sub.textContent=s[1];
+ d.appendChild(t);d.appendChild(sub);
+ d.onclick=function(){pinned=true;set(i);};
+ loop.appendChild(d);cards.push(d);
+});
+var cur=0,pinned=false;
+function set(i){cur=i;cards.forEach(function(n,j){n.classList.toggle("on",j===i);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){if(!pinned)set((cur+1)%cards.length);},1600);}
+</script>
+```
+
+There's no separate Q&A product bolted on. Q&A *is* your OpenKnowledge-grounded agent plus [search](../reference/agentic-search.mdx): 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:
+
+<CopyPrompt>Build a codebase wiki for this repo. Internal audience, standard depth.</CopyPrompt>
+
+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:
+
+```bash
+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.
+
+<Callout type="info" title="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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
+## 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:
+
+<CopyPrompt>Generate the codebase wiki.</CopyPrompt>
+
+To update it later, once it exists:
+
+<CopyPrompt>Refresh the codebase wiki.</CopyPrompt>
+
+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.
+
+<Callout type="info">
+ **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.
+</Callout>
+
+## 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 |
+
+## Further reading
+
+- **[Software lifecycle workflow](./software-lifecycle.mdx).** The proposals → decisions → specs the wiki's code implements.
+- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** Same source-grounded discipline, aimed at external sources instead of your own code.
+- **[Agentic search](../reference/agentic-search.mdx).** How an agent retrieves across the wiki — search, grep, and backlinks over live files, no vector database.
+- **[Agent activity](../features/agent-activity.mdx).** Every wiki page write, attributed and diffable.
diff --git a/docs/content/workflows/entity-vault.mdx b/docs/content/workflows/entity-vault.mdx
index 4c2b4f28f..bb668af19 100644
--- a/docs/content/workflows/entity-vault.mdx
+++ b/docs/content/workflows/entity-vault.mdx
@@ -1,7 +1,7 @@
---
title: Entity vault (GBrain-compatible) workflow
icon: LuBoxes
-description: A GBrain-compatible Markdown workflow for people, companies, meetings, and concepts. OpenKnowledge is the cockpit/editor/review layer; Garry Tan's gbrain can import or sync the same vault for indexing and automation.
+description: "A personal memory for the people, companies, and meetings in your world. Each one gets its own page that an AI keeps up to date as you learn more, and you can correct anything by hand. Works with Garry Tan's gbrain if you use it, but doesn't need it."
---
An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized around typed dossiers: people, companies, meetings, concepts, originals, and media. Each durable dossier has two zones:
@@ -11,12 +11,38 @@ An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized a
OpenKnowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain), if you install it, can import/sync the same vault and add its DB-backed retrieval, graph extraction, embedding, and automation. OK does **not** replace `gbrain`; it gives GBrain-style Markdown brains a human cockpit for review, correction, attribution, and Git-visible edits.
-## Who this is for
+```html preview
+<div style="padding:18px">
+ <div id="dv" style="max-width:430px;margin:0 auto;border:1px solid var(--border);border-radius:12px;overflow:hidden;background:var(--card)">
+ <div style="padding:10px 14px;border-bottom:1px solid var(--border);font-weight:600;font-size:13px">Jane Founder <span style="color:var(--muted-foreground);font-weight:400">· person</span></div>
+ <div style="padding:11px 14px">
+ <div style="font-size:10.5px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted-foreground)">Compiled truth</div>
+ <div id="dv-truth" style="font-size:12.5px;margin-top:4px;line-height:1.45"></div>
+ </div>
+ <div style="padding:11px 14px;border-top:1px dashed var(--border)">
+ <div style="font-size:10.5px;text-transform:uppercase;letter-spacing:.05em;color:var(--muted-foreground)">Timeline (append-only)</div>
+ <div id="dv-tl" style="margin-top:6px;display:flex;flex-direction:column;gap:5px"></div>
+ </div>
+ </div>
+ <div class="cap">Two zones per dossier: a compiled truth the agent rewrites as evidence changes, and a timeline it only ever appends to.</div>
+</div>
+<style>
+.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px;text-align:center}
+.cap::before{content:"\1F9E0 ";font-weight:700}
+#dv-tl .b{font-size:11.5px;color:var(--muted-foreground);border-left:2px solid var(--accent-soft);padding-left:8px;animation:dvin .4s ease}
+@keyframes dvin{from{opacity:0;transform:translateY(3px)}to{opacity:1;transform:none}}
+</style>
+<script>
+var truths=["Co-founder and CEO of Jane Co.","Co-founder and CEO of Jane Co. Ex-profiler; sharp on cost-per-token economics.","Co-founder and CEO of Jane Co. Ex-profiler; sharp on cost-per-token economics. Go-to-market still forming."];
+var bullets=["2026-05-12 · coffee — described the observability wedge","2026-05-13 · agent enrichment — prior OSS profiler work","2026-05-20 · intro from Alex — GTM still developing"];
+var truth=document.getElementById("dv-truth"),tl=document.getElementById("dv-tl");
+function render(i){truth.textContent=truths[i];tl.innerHTML="";for(var j=0;j<=i;j++){var b=document.createElement("div");b.className="b";b.textContent=bullets[j];tl.appendChild(b);}}
+var cur=0;render(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){cur=(cur+1)%3;render(cur);},1800);}
+</script>
+```
-- You want a second brain that tracks **people, companies, meetings, and concepts**, not just source documents.
-- You want agents to maintain dossiers while you keep final editorial control.
-- You already use `gbrain` and want a visual/editor layer over the Markdown files it indexes.
-- You do not use `gbrain` yet, but want a portable GBrain-compatible Markdown shape you can adopt later.
+Founders and investors get a second brain over **people, companies, meetings, and concepts** — a network that's queryable, not just a pile of source documents. Agents maintain the dossiers while you keep final editorial control, so wrong claims get corrected by hand rather than trusted blindly. If you already run `gbrain`, this is a visual editor layer over the Markdown it indexes; if you don't yet, the GBrain-compatible Markdown shape is portable, so adopting that engine later is never a migration.
## The division of labor
@@ -56,6 +82,10 @@ your-project/
Each folder includes an `.ok/frontmatter.yml` description that agents see during file listings/searches, plus templates under `.ok/templates/`.
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack entity-vault` installs the **Entity vault** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the dossier conventions — compiled-truth vs. append-only timeline, path-qualified links, the correction loop — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
## Markdown shape
A person dossier generated from the pack starts in a GBrain-compatible shape:
@@ -160,7 +190,7 @@ For a GBrain-literate reviewer, the demo target is not "OK replaces GBrain." It
Aha moment: **GBrain makes agent memory useful; OK makes the Markdown memory inspectable, correctable, and collaborative.**
-## Routine
+## Cadence
| Cadence | What |
| --- | --- |
diff --git a/docs/content/workflows/karpathy-llm-wiki.mdx b/docs/content/workflows/karpathy-llm-wiki.mdx
index 7f9d5d095..d49f84d22 100644
--- a/docs/content/workflows/karpathy-llm-wiki.mdx
+++ b/docs/content/workflows/karpathy-llm-wiki.mdx
@@ -1,7 +1,7 @@
---
title: LLM wiki
icon: LuBrain
-description: "An AI second brain that doesn't rot: a wiki of your own files an agent reads, writes, and keeps organized. What an LLM wiki is, and how to build one with the Knowledge base starter pack."
+description: "Point an AI at a folder of your own notes and let it keep them organized, linked, and easy to search. The more you add, the tidier it gets instead of messier. Built on the Knowledge base starter pack."
---
An LLM wiki is a knowledge base of your own markdown files that an agent reads, writes, and keeps organized. You supply the raw material. The agent files it, links it, and cites it. It gets more organized the more you use it.
@@ -56,10 +56,7 @@ The rest of this guide builds one end to end. The pattern is Andrej Karpathy's,
The point of this guide is to show how **OpenKnowledge's features compose** to make the pattern feel native: the starter-pack picker scaffolds the layout in one click; per-folder templates + agent-readable folder frontmatter teach the LLM the conventions (Karpathy's centralized `CLAUDE.md` / `AGENTS.md` schema, distributed per-folder); the `workflow` tool's `ingest`, `research`, and `consolidate` kinds cover the sources → provisional → canonical pipeline; the WYSIWYG editor + CRDT keep editing frictionless; the activity panel attributes every write; the `links` tool keeps the source graph clean. Every step uses three or four of these together. That's the product.
-## Who this is for
-
-- **You're new to LLM-curated PKM.** You've felt the pull of "the LLM should remember my context for me" but you don't want a vault that turns into a junk drawer of unprocessed clips. Start here.
-- **You already practice Karpathy's pattern in another tool** (Obsidian, plain folders, Claude projects). You want to know what OpenKnowledge does differently, and what you keep.
+If you're new to LLM-curated PKM, the draw is an agent that remembers your context without the vault turning into a junk drawer of unprocessed clips — notes that compound instead of rotting. If you're already practicing Karpathy's pattern in Obsidian, plain folders, or Claude projects, the question is what OpenKnowledge does differently and what carries over.
Either way, by the end of this guide you'll have a working source-grounded knowledge base, a routine for adding sources, and a daily-driver agent setup that interrogates the vault on your behalf.
@@ -162,6 +159,10 @@ You'll get `external-sources/`, `research/`, `articles/`, the three matching tem
The starter-pack picker is idempotent (safe to re-run on the same project).
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack knowledge-base` (or the desktop starter-pack picker) installs the **Knowledge base** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the layer discipline described below — the `ingest` / `research` / `consolidate` conventions and the provisional-to-canonical promotion — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
### 3. Confirm your agent host is wired
If you accepted the desktop app's first-launch offer to wire up your agent assistant, you're done. If not, in your agent assistant ([Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), or [Codex](../integrations/codex.mdx)), ask:
diff --git a/docs/content/workflows/meta.json b/docs/content/workflows/meta.json
index 385a15e64..d3d69ef6a 100644
--- a/docs/content/workflows/meta.json
+++ b/docs/content/workflows/meta.json
@@ -1,5 +1,14 @@
{
"title": "Workflows",
"icon": "LuWorkflow",
- "pages": ["karpathy-llm-wiki", "entity-vault", "supporting-open-knowledge-format"]
+ "pages": [
+ "karpathy-llm-wiki",
+ "codebase-wiki",
+ "software-lifecycle",
+ "entity-vault",
+ "writing-pipeline",
+ "supporting-open-knowledge-format",
+ "worldbuilding",
+ "plain-notes"
+ ]
}
diff --git a/docs/content/workflows/plain-notes.mdx b/docs/content/workflows/plain-notes.mdx
new file mode 100644
index 000000000..86a559e1a
--- /dev/null
+++ b/docs/content/workflows/plain-notes.mdx
@@ -0,0 +1,91 @@
+---
+title: Plain notes
+icon: LuNotebookPen
+description: "The simplest setup: one folder for notes and one for a daily journal. Just write, link the things worth linking, and a connected web of notes builds itself. Built on the Plain notes starter pack."
+---
+**Plain notes** is the "I just want to write" layout. Two folders, no structure imposed: a flat `notes/` for topics and a `daily/` journal. You write; you link the things worth linking; and a navigable graph emerges on its own. It's the pack to reach for when the other packs feel like too much scaffolding for what you're actually doing.
+
+```html preview
+<div style="padding:16px">
+ <div id="pn" style="display:flex;gap:18px;flex-wrap:wrap;justify-content:center">
+ <svg id="pn-graph" viewBox="0 0 200 160" style="width:200px;height:160px" role="img" aria-label="Notes linking into a small graph"></svg>
+ <div id="pn-days" style="display:flex;flex-direction:column;gap:6px;justify-content:center"></div>
+ </div>
+ <div class="cap">Left: mention something in a note and it becomes a link — the graph builds itself. Right: each day's entry links to yesterday's, so the journal is also a chain.</div>
+</div>
+<style>
+.cap{margin-top:10px;color:var(--muted-foreground);font-size:12.5px;text-align:center}
+.cap::before{content:"\1F517 ";font-weight:700}
+#pn-graph line{stroke:var(--border);stroke-width:1.5}
+#pn-graph line.lit{stroke:var(--primary)}
+#pn-graph circle{fill:var(--card);stroke:var(--border);stroke-width:1.5;transition:stroke .3s}
+#pn-graph circle.on{stroke:var(--primary)}
+.day{border:1px solid var(--border);border-radius:9px;padding:6px 11px;font-size:12px;font-weight:600;color:var(--muted-foreground);background:var(--card);transition:border-color .3s,color .3s}
+.day.on{border-color:var(--primary);color:var(--accent-ink)}
+@media (prefers-reduced-motion:reduce){#pn-graph circle,#pn-graph line,.day{transition:none}}
+</style>
+<script>
+var P=[[100,30],[45,100],[155,95],[100,140]],GE=[[0,1],[0,2],[1,3],[2,3]];
+var g=document.getElementById("pn-graph"),NS="http://www.w3.org/2000/svg",gl=[],gc=[];
+GE.forEach(function(e){var l=document.createElementNS(NS,"line");l.setAttribute("x1",P[e[0]][0]);l.setAttribute("y1",P[e[0]][1]);l.setAttribute("x2",P[e[1]][0]);l.setAttribute("y2",P[e[1]][1]);g.appendChild(l);gl.push({el:l,a:e[0],b:e[1]});});
+P.forEach(function(p,i){var c=document.createElementNS(NS,"circle");c.setAttribute("cx",p[0]);c.setAttribute("cy",p[1]);c.setAttribute("r",8);g.appendChild(c);gc.push(c);});
+var days=["Mon","Tue","Wed","Thu"],box=document.getElementById("pn-days"),de=[];
+days.forEach(function(d){var el=document.createElement("div");el.className="day";el.textContent=d+" — daily entry";box.appendChild(el);de.push(el);});
+var cur=0;
+function set(i){gc.forEach(function(c,j){c.classList.toggle("on",j===i%gc.length);});gl.forEach(function(o){o.el.classList.toggle("lit",o.a===i%gc.length||o.b===i%gc.length);});de.forEach(function(el,j){el.classList.toggle("on",j===i%de.length);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){cur=(cur+1)%4;set(cur);},1400);}
+</script>
+```
+
+There's no pipeline and no lifecycle here. The only discipline is the linking habit — and OpenKnowledge's graph, backlinks, and search do the rest.
+
+Note-takers get a plain notes app backed by markdown they own, with an agent keeping everything linked and nothing locked in a proprietary format. Journalers get each daily entry chained to the last, with mood and gratitude fields, so the journal is also a navigable graph to look back across. And if you're not sure which pack to pick, this is the lightest possible starting point — begin now and promote notes into a more structured layout later.
+
+## The folders
+
+```
+notes/ one file per topic, flat
+daily/ one journal entry per day (YYYY-MM-DD.md)
+```
+
+The pack ships just two templates — `note` and `daily`. The daily entry has a light shape (morning intentions, capture through the day, evening reflection) plus optional `mood`, `top3`, and `gratitude` frontmatter fields you fill when journaling, so you can look back across days later.
+
+## The one habit: link liberally
+
+The entire value of this pack is the graph that emerges from links. So when a note or entry mentions something worth its own page, link it — and if that page doesn't exist yet, stub it. The agent does this for you:
+
+<CopyPrompt>Turn today's notes into a daily entry. Link anything worth its own page and stub the ones that don't exist yet. Link this entry to yesterday's.</CopyPrompt>
+
+On the first entry of a day the agent links back to yesterday's entry and pre-fills the date, so your linear journal is also a navigable graph you can walk in either direction.
+
+## What's in your project after seeding
+
+Pick **Plain notes** in the starter-pack picker, or run:
+
+```bash
+ok seed --pack plain-notes
+```
+
+The pack creates `notes/` and `daily/` at the project root (no subfolder), each with its `.ok/frontmatter.yml` guidance and template. That's the whole footprint — minimal on purpose.
+
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack plain-notes` installs the **Plain notes** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance that gives the agent the linking habit and the daily-chain behavior — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
+## Cadence
+
+| When | Do |
+| --- | --- |
+| Any time | Drop a note in `notes/`; link the nouns worth their own page |
+| Each morning or evening | A `daily/` entry; let the agent chain it to yesterday and fill mood / gratitude |
+| Weekly | Ask the agent to link loosely-related notes so the graph tightens |
+| When a topic outgrows a note | Promote it — or switch to a more structured pack for that area |
+
+## Further reading
+
+- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** When your notes become source-grounded research, this is the pack to graduate to.
+- **[Writing pipeline workflow](./writing-pipeline.mdx).** When your notes grow into essays or newsletters, this pack adds ideas → drafts → published stage gates.
+- **[Core Concepts](../reference/core-concepts.md).** Links, backlinks, and the well-connected graph that make the emergent structure visible.
+- **[Skills](../features/skills.mdx).** What the installed pack skill is, and how to edit it.
+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.
diff --git a/docs/content/workflows/software-lifecycle.mdx b/docs/content/workflows/software-lifecycle.mdx
new file mode 100644
index 000000000..dfda4a242
--- /dev/null
+++ b/docs/content/workflows/software-lifecycle.mdx
@@ -0,0 +1,153 @@
+---
+title: Software lifecycle
+icon: LuGitPullRequest
+description: "One home for the docs an engineering team writes around its code: the pitch for a change, the decision that settles it, the plan to build it, and the write-up when something breaks. Each links to the next, and an AI keeps the connections current. Built on the Software lifecycle starter pack."
+---
+A **software lifecycle** knowledge base is where an engineering team's thinking lives before, during, and after the code: the proposal that argued for a change, the decision that settled it, the spec that built it, and the postmortem written when it broke. Those are the usual names for each stage, and if they're new to you the page explains them as it goes. One folder per stage, one flow connecting them, and an AI that keeps the links between them honest.
+
+```html preview
+<div style="padding:18px">
+ <div id="flow" style="display:flex;flex-wrap:wrap;gap:8px;align-items:stretch"></div>
+ <div class="cap">Each stage is a folder of markdown. The arrows are links the agent maintains, so a spec always points back to the decision that authorized it.</div>
+</div>
+<style>
+#flow .node{flex:1;min-width:118px;border:1px solid var(--border);border-radius:12px;padding:11px 13px;background:var(--card);transition:box-shadow .3s,border-color .3s;cursor:pointer}
+#flow .node .t{font-weight:600;font-size:13px}
+#flow .node .s{color:var(--muted-foreground);font-size:11.5px;margin-top:2px}
+#flow .node.on{border-color:var(--primary);box-shadow:0 0 0 3px var(--accent-soft)}
+#flow .node.on .t{color:var(--accent-ink)}
+#flow .arrow{align-self:center;color:var(--muted-foreground)}
+.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px}
+.cap::before{content:"\2192 ";color:var(--primary);font-weight:700}
+@media (prefers-reduced-motion:reduce){#flow .node{transition:none}}
+</style>
+<script>
+var steps=[["proposals/","argue for a change"],["decisions/","freeze the ADR"],["specs/","implement it"],["postmortems/","when it breaks"]];
+var flow=document.getElementById("flow"),nodes=[];
+steps.forEach(function(s,i){
+ if(i){var a=document.createElement("div");a.className="arrow";a.textContent="→";flow.appendChild(a);}
+ var d=document.createElement("div");d.className="node";
+ var t=document.createElement("div");t.className="t";t.textContent=s[0];
+ var sub=document.createElement("div");sub.className="s";sub.textContent=s[1];
+ d.appendChild(t);d.appendChild(sub);
+ d.onclick=function(){pinned=true;set(i);};
+ flow.appendChild(d);nodes.push(d);
+});
+var cur=0,pinned=false;
+function set(i){cur=i;nodes.forEach(function(n,j){n.classList.toggle("on",j===i);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){if(!pinned)set((cur+1)%nodes.length);},1500);}
+</script>
+```
+
+The stages are the standard artifacts an engineering org already produces — RFCs, ADRs, specs, blameless postmortems, runbooks — but here they live as linked markdown an agent reads and writes alongside you, not as scattered Google Docs, Notion pages, and Slack threads that nobody can trace six months later.
+
+Engineering leads get every proposal, decision, and spec in one linked graph, with the agent surfacing what supersedes what, so design docs stop rotting across scattered tools. OSS maintainers give contributors the *why* behind the code — in accepted proposals and frozen ADRs — instead of leaving them to do archaeology through closed PRs. On-call engineers get postmortems that link to each other and stub the follow-up guides automatically, so recurring incidents become visible instead of quietly repeating.
+
+## The flow
+
+```
+proposals/ in-flight, RFC-shape design proposals (draft → fcp → accepted/rejected)
+ ↓ accepted
+decisions/ frozen ADRs — the record of what was decided
+ ↓ derived
+specs/ implementation specs for accepted proposals
+ ↓ when things break
+postmortems/ blameless incident write-ups
+guides/ how-to / onboarding / runbooks — referenced throughout
+```
+
+The pack ships a template for each: `proposal`, `decision`, `spec` / `plan` / `tasks` (the [GitHub spec-kit](https://github.com/github/spec-kit) three-file shape), `postmortem`, and `guide` / `onboarding-guide` / `runbook`. Templates carry only structure; what each section is for is taught to the agent by the folder itself, so document bodies stay clean.
+
+## The scenario
+
+Your team is deciding whether to move the job queue off Postgres onto a dedicated broker. Over two weeks:
+
+1. An engineer writes `proposals/0007-dedicated-job-broker.md` — motivation, design, drawbacks, alternatives, unresolved questions. Status `draft`.
+2. After review it reaches `fcp` (final comment period), then `accepted`. The agent graduates it into `decisions/0007-adopt-nats-for-jobs.md`, a frozen ADR that links back to the proposal.
+3. Implementation gets a `specs/007-job-broker/` folder — `spec.md`, `plan.md`, `tasks.md` — referencing the parent decision.
+4. Three weeks post-ship the broker drops messages under load. `postmortems/2026-07-14-job-broker-message-loss.md` captures the timeline and root cause, and the agent surfaces a `Related:` link to an older queue postmortem that shares the subsystem.
+
+Nothing here is new to your team. What's new: it's all one linked graph an agent can read back to you, and the links stay correct because the agent maintains them.
+
+## What's in your project after seeding
+
+Pick **Software lifecycle** in the starter-pack picker, or run:
+
+```bash
+ok seed --pack software-lifecycle
+```
+
+By default the pack nests everything under a `project-docs/` subfolder:
+
+```
+your-project/
+└── project-docs/
+ ├── proposals/ 0001-feature-name.md …
+ ├── decisions/ NNNN-title.md (ADRs)
+ ├── specs/ NNN-name/{spec,plan,tasks}.md
+ ├── postmortems/ YYYY-MM-DD-name.md
+ └── guides/ how-to / onboarding / runbooks
+```
+
+Each folder carries an `.ok/frontmatter.yml` description the agent reads on every directory listing, plus its templates under `.ok/templates/`. That description is where the workflow lives — so the agent knows an accepted proposal graduates to `decisions/`, that ADRs freeze once accepted, and that a new decision superseding an old one links back via `Supersedes:`.
+
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack software-lifecycle` installs the **Software lifecycle** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the status flows, the `Supersedes:` scanning, the postmortem follow-ups — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
+## What the agent does for you
+
+The pack teaches the agent behaviors you'd otherwise have to remember. _They're encoded in the pack skill and run **when you prompt the agent** — not background automations that fire on a timer._
+
+| When | The agent | Why it matters |
+| --- | --- | --- |
+| A new decision lands | Scans existing ADRs touching the same subsystem, surfaces `Supersedes:` candidates before commit | The decision log stays a true chain, not a pile |
+| A proposal sits at `draft` > 14 days | Surfaces it to advance, park, or close | Stale proposals don't silently die |
+| A postmortem is published | Scans action items for guide-shaped follow-ups and stubs a guide pre-filled with the symptom | The fix becomes documented, not just discussed |
+| A new postmortem | Adds a `Related:` block linking prior postmortems in the same subsystem | Recurring incidents become visible |
+
+## Step by step
+
+### 1. Seed the pack
+
+In a fresh project, open the starter-pack picker and choose **Software lifecycle** (or run `ok seed --pack software-lifecycle`). Confirm the subfolder — leave `project-docs/` or point it at wherever your team's docs live.
+
+### 2. Write the first proposal
+
+In your agent, from a rough idea:
+
+<CopyPrompt>Draft a proposal in proposals/ for moving our job queue off Postgres onto a dedicated broker. Use the proposal template: motivation, design, drawbacks, alternatives, unresolved questions. Status: draft.</CopyPrompt>
+
+Review it in the editor. The frontmatter tracks `status`; advance it to `fcp` then `accepted` as review progresses.
+
+### 3. Graduate it to a decision
+
+<CopyPrompt>This proposal is accepted. Create the ADR in decisions/, link it back to the proposal, and flag any existing decisions it supersedes.</CopyPrompt>
+
+The agent writes the frozen record and — per the pack behavior — checks the subsystem for supersede candidates.
+
+### 4. Derive the spec
+
+<CopyPrompt>Create an implementation spec for the accepted broker decision under specs/, using the spec / plan / tasks templates. Reference the parent decision.</CopyPrompt>
+
+### 5. Write postmortems as incidents happen
+
+<CopyPrompt>Write a blameless postmortem for the job-broker message loss on 2026-07-14: summary, timeline, root cause, what went well, action items. Link related prior postmortems.</CopyPrompt>
+
+## Cadence
+
+| When | Do |
+| --- | --- |
+| Per design change | A proposal in `proposals/`; advance its status as review moves |
+| On acceptance | Graduate to a `decisions/` ADR with a `Supersedes:` chain where relevant |
+| Per implementation | A `specs/NNN-name/` folder derived from the decision |
+| Per incident | A blameless postmortem; let the agent link related ones and stub follow-up guides |
+| Monthly | Ask the agent to surface stale `draft` proposals and guides past their `last_verified` date |
+
+## Further reading
+
+- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** The source-grounded counterpart, if you're curating external sources rather than a doc lifecycle.
+- **[Codebase wiki workflow](./codebase-wiki.mdx).** An agent-authored wiki of the code the specs implement.
+- **[Agent activity](../features/agent-activity.mdx).** How every proposal, decision, and spec edit lands with attribution.
+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.
diff --git a/docs/content/workflows/supporting-open-knowledge-format.mdx b/docs/content/workflows/supporting-open-knowledge-format.mdx
index 0fe2abc55..29230ac93 100644
--- a/docs/content/workflows/supporting-open-knowledge-format.mdx
+++ b/docs/content/workflows/supporting-open-knowledge-format.mdx
@@ -1,7 +1,7 @@
---
title: Supporting the Open Knowledge Format
icon: LuFileCode
-description: Scaffold a knowledge base that is conformant with Google's Open Knowledge Format (OKF) from the first commit — without enforcing anything.
+description: "Start a knowledge base that already follows Google's Open Knowledge Format, so any OKF tool can read it later. You get the right setup out of the box, and you're still free to write however you like."
---
Open Knowledge ships a starter pack named **`okf`** that scaffolds a knowledge base **conformant with Google's [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the first commit** — without enforcing anything. You get a portable, OKF-ready bundle out of the box, and you stay free to author however you like.
@@ -9,6 +9,34 @@ Open Knowledge ships a starter pack named **`okf`** that scaffolds a knowledge b
**OKF here means Google's Open Knowledge _Format_** — a vendor-neutral file-format spec (a directory of markdown files with YAML frontmatter), announced by Google Cloud in June 2026. Read the [OKF v0.1 spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md).
</Callout>
+```html preview
+<div style="padding:18px">
+ <div id="okf" style="display:flex;flex-wrap:wrap;gap:8px;justify-content:center"></div>
+ <div class="cap">One rule keeps the bundle conformant: every non-reserved doc carries a non-empty <code>type</code>. Reserved index.md and log.md stay frontmatter-free.</div>
+</div>
+<style>
+.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px;text-align:center}
+.cap::before{content:"\2713 ";color:var(--primary);font-weight:700}
+#okf .doc{border:1px solid var(--border);border-radius:10px;padding:9px 12px;background:var(--card);min-width:118px;transition:border-color .3s,box-shadow .3s}
+#okf .doc.on{border-color:var(--primary);box-shadow:0 0 0 3px var(--accent-soft)}
+#okf .doc .f{font-weight:600;font-size:12px}
+#okf .doc .ty{font-size:11px;margin-top:3px;color:var(--accent-ink)}
+#okf .doc .rv{font-size:11px;margin-top:3px;color:var(--muted-foreground)}
+@media (prefers-reduced-motion:reduce){#okf .doc{transition:none}}
+</style>
+<script>
+var docs=[["concept.md","type: concept",0],["reference.md","type: reference",0],["note.md","type: note",0],["index.md","reserved · no frontmatter",1],["log.md","reserved · no frontmatter",1]];
+var root=document.getElementById("okf"),cards=[];
+docs.forEach(function(d){var el=document.createElement("div");el.className="doc";var f=document.createElement("div");f.className="f";f.textContent=d[0];var m=document.createElement("div");m.className=d[2]?"rv":"ty";m.textContent=d[1];el.appendChild(f);el.appendChild(m);root.appendChild(el);cards.push(el);});
+var cur=0;
+function set(i){cards.forEach(function(c,j){c.classList.toggle("on",j===i);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){cur=(cur+1)%cards.length;set(cur);},1200);}
+</script>
+```
+
+The point is portability from day one: a knowledge base you can hand to any tool that reads Google's Open Knowledge Format, already conformant so indexing, exporting, or sharing with an OKF-aware consumer later is never a migration project. And the discipline is **pre-populated, not enforced** — you get conformance without the editor linting or blocking you.
+
## What the pack seeds
Run it with `ok seed --pack okf`. It scaffolds:
@@ -22,7 +50,7 @@ Run it with `ok seed --pack okf`. It scaffolds:
| `index.md` | Reserved OKF navigation hub | — (reserved) |
| `log.md` | Reserved OKF change history | — (reserved) |
-Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`open-knowledge-pack-okf`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`.
+Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`open-knowledge-pack-okf`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`. Like every seeded file, that `SKILL.md` is committed to your repo and editable; see [Skills](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
## Conformance is pre-populated, not enforced
@@ -41,6 +69,17 @@ So three habits are all it takes to keep the KB handable to a strict OKF consume
Open Knowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is.
+## Cadence
+
+Three habits keep the bundle handable to a strict OKF consumer as it grows. The seeded templates already do the first; the rest is light discipline, not enforcement.
+
+| When | Do |
+|---|---|
+| Creating a doc | Use **New from template** — it sets `type` for you |
+| Reserved files | Keep `index.md` / `log.md` lowercase and frontmatter-free |
+| Links | Use standard markdown links; `[[wiki-link]]` shorthand normalizes on export |
+| Handing it off | Nothing special — the bundle is conformant as you go |
+
## Further reading
- **[Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)** — the canonical OKF v0.1 specification (Google Cloud).
diff --git a/docs/content/workflows/worldbuilding.mdx b/docs/content/workflows/worldbuilding.mdx
new file mode 100644
index 000000000..d8380fed2
--- /dev/null
+++ b/docs/content/workflows/worldbuilding.mdx
@@ -0,0 +1,108 @@
+---
+title: Worldbuilding
+icon: LuSparkles
+description: "A living encyclopedia for a story you're writing: characters, places, factions, and lore, each on its own page that links to the others. Mention someone new and the AI adds a page for them; contradict your own canon and it flags it. Built on the Worldbuilding starter pack."
+---
+A **worldbuilding** knowledge base is a living encyclopedia of your story world. Characters, settings, themes, factions, and lore — each its own page, all linking to each other. The graph *is* the product: the value isn't any single entry, it's the web connecting them, and an agent that grows and guards that web as you write.
+
+```html preview
+<div style="padding:16px">
+ <svg id="web" viewBox="0 0 460 220" style="width:100%;max-width:520px;display:block;margin:0 auto" role="img" aria-label="A graph of story entities linking to each other"></svg>
+ <div class="cap">Mention a name that isn't captured yet and the agent stubs its page and backlinks it. Every entity becomes a hub for everywhere it appears.</div>
+</div>
+<style>
+.cap{margin-top:10px;color:var(--muted-foreground);font-size:12.5px;text-align:center}
+.cap::before{content:"\29C9 ";color:var(--primary);font-weight:700}
+#web line{stroke:var(--border);stroke-width:1.5}
+#web line.lit{stroke:var(--primary)}
+#web .n circle{fill:var(--card);stroke:var(--border);stroke-width:1.5;transition:stroke .3s,filter .3s}
+#web .n.on circle{stroke:var(--primary);filter:drop-shadow(0 0 5px var(--accent-soft))}
+#web .n text{fill:var(--muted-foreground);font-size:10px;text-anchor:middle;font-weight:600}
+#web .n.on text{fill:var(--accent-ink)}
+@media (prefers-reduced-motion:reduce){#web .n circle,#web line{transition:none}}
+</style>
+<script>
+var N=[["Kael",120,50],["Iron Pact",300,45],["Duskfen",70,150],["The Sundering",250,160],["Betrayal",380,120]];
+var E=[[0,1],[0,2],[1,3],[2,3],[0,4],[3,4]];
+var svg=document.getElementById("web"),NS="http://www.w3.org/2000/svg",lines=[],nodes=[];
+E.forEach(function(e){var l=document.createElementNS(NS,"line");l.setAttribute("x1",N[e[0]][1]);l.setAttribute("y1",N[e[0]][2]);l.setAttribute("x2",N[e[1]][1]);l.setAttribute("y2",N[e[1]][2]);svg.appendChild(l);lines.push({el:l,a:e[0],b:e[1]});});
+N.forEach(function(n,i){var g=document.createElementNS(NS,"g");g.setAttribute("class","n");var c=document.createElementNS(NS,"circle");c.setAttribute("cx",n[1]);c.setAttribute("cy",n[2]);c.setAttribute("r",7);var t=document.createElementNS(NS,"text");t.setAttribute("x",n[1]);t.setAttribute("y",n[2]-12);t.textContent=n[0];g.appendChild(c);g.appendChild(t);g.onclick=function(){pinned=true;set(i);};svg.appendChild(g);nodes.push(g);});
+var cur=0,pinned=false;
+function set(i){cur=i;nodes.forEach(function(g,j){g.classList.toggle("on",j===i);});lines.forEach(function(o){o.el.classList.toggle("lit",o.a===i||o.b===i);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){if(!pinned)set((cur+1)%nodes.length);},1500);}
+</script>
+```
+
+Unlike the other packs, the flow here isn't a pipeline — it's a network that thickens over time. Your job is to write scenes and notes; the agent's job is to keep the encyclopedia consistent with them.
+
+Novelists and screenwriters lean on it to stop losing track of their own canon as the story grows. Game masters keep a navigable world bible — who controls which region, which faction hates which. Narrative-design teams use it to hold a shared setting together as more people contribute.
+
+## The folders
+
+| Folder | Holds | The story question it answers |
+| --- | --- | --- |
+| `characters/` | One page per character (PC + NPC); type, status, faction, first appearance | *Who* |
+| `settings/` | Locations, regions, world-rules; region, controlling faction, danger level | *Where* |
+| `themes/` | Recurring narrative concerns (love, betrayal, identity), each with its tension | *Why* |
+| `factions/` | Political, social, criminal, magical, religious groups | *Who's aligned with whom* |
+| `lore/` | History, mythology, cosmology, magic systems | *What's true about the world* |
+
+The pack ships templates for the shapes that recur — `faction`, `political-faction`, `religion`, `lore`, `magic-system`, `historical-event`, and the core character / setting / theme pages.
+
+## The two behaviors that make it worth it
+
+This is where the agent earns its keep:
+
+- **Auto-stub on mention.** When a chapter, session log, or existing entry names someone or somewhere not yet captured, the agent stubs a page in the right folder and backlinks it to where it came up. Your canon grows as you write, not in a separate cataloguing session.
+- **Flag contradictions.** When a character's `faction` contradicts their actions in a scene, or a setting gets described two ways, the agent *surfaces* the conflict rather than silently "fixing" it — because in fiction a contradiction is often a plot point, not a bug. You decide whether it's a mistake or a mystery.
+
+## The scenario
+
+You write a chapter where Kael, a member of the Iron Pact, quietly warns the people of Duskfen before a raid. You drop the scene in and ask:
+
+<CopyPrompt>Update the world encyclopedia from this chapter. Stub any characters, settings, or factions I mention that don't have pages yet, and link them. Flag anything that contradicts existing canon.</CopyPrompt>
+
+The agent stubs `characters/kael.md` linked to `factions/iron-pact.md` and `settings/duskfen.md` — then notes that Kael warning Duskfen contradicts the Iron Pact's stated hostility toward it. Is Kael a traitor, a double agent, or did you misremember the Pact's alignment? That flag is the agent doing worldbuilding *with* you.
+
+## What's in your project after seeding
+
+Pick **Worldbuilding** in the starter-pack picker, or run:
+
+```bash
+ok seed --pack worldbuilding
+```
+
+By default the pack nests under a `world/` subfolder:
+
+```
+your-project/
+└── world/
+ ├── characters/
+ ├── settings/
+ ├── themes/
+ ├── factions/
+ └── lore/
+```
+
+Each folder's `.ok/frontmatter.yml` teaches the agent that entity type and its auto-stub / contradiction behavior, so the guidance never clutters the entries themselves.
+
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack worldbuilding` installs the **Worldbuilding** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the auto-stub and contradiction-flagging behaviors — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
+## Cadence
+
+| When | Do |
+| --- | --- |
+| After writing a scene or session | Ask the agent to update the encyclopedia — stub new entities, link mentions, flag contradictions |
+| Periodically | Thread the graph: ask it to link characters ↔ factions ↔ settings ↔ lore so each entry is a hub |
+| Before a big reveal | Ask it to surface every page that touches the character or lore involved, so continuity holds |
+| Monthly | Ask the agent to audit dead links and stubbed-but-never-filled entities |
+
+## Further reading
+
+- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** The same wiki-graph discipline, aimed at real-world sources instead of a fictional world.
+- **[Entity vault workflow](./entity-vault.mdx).** The non-fiction sibling — track real people, companies, and meetings the same way you track characters and factions.
+- **[Core Concepts](../reference/core-concepts.md).** Links and backlinks — the connected graph you navigate the world through.
+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.
diff --git a/docs/content/workflows/writing-pipeline.mdx b/docs/content/workflows/writing-pipeline.mdx
new file mode 100644
index 000000000..1a2b82942
--- /dev/null
+++ b/docs/content/workflows/writing-pipeline.mdx
@@ -0,0 +1,118 @@
+---
+title: Writing pipeline
+icon: LuPenTool
+description: "Three folders that move a piece of writing from idea to published: catch ideas before they slip away, draft with an AI while every revision is saved automatically, and leave finished pieces untouched. Built on the Writing pipeline starter pack."
+---
+A **writing pipeline** is the shortest honest path from a premise to a published piece: three folders, one direction of travel. Ideas you capture before they fade, drafts you actually work on, and published work you leave alone. No named-revision folders, no ceremony — the CRDT history covers your revisions, and an agent nudges pieces along so nothing stalls.
+
+```html preview
+<div style="padding:18px">
+ <div id="pipe" style="display:flex;flex-wrap:wrap;gap:8px;align-items:stretch"></div>
+ <div class="cap">One direction of travel. A premise gets promoted to a draft when you commit to it; a draft gets published when it ships — and then it's immutable.</div>
+</div>
+<style>
+#pipe .node{flex:1;min-width:130px;border:1px solid var(--border);border-radius:12px;padding:12px 14px;background:var(--card);transition:box-shadow .3s,border-color .3s;cursor:pointer}
+#pipe .node .t{font-weight:600;font-size:13px}
+#pipe .node .s{color:var(--muted-foreground);font-size:11.5px;margin-top:3px;line-height:1.35}
+#pipe .node.on{border-color:var(--primary);box-shadow:0 0 0 3px var(--accent-soft)}
+#pipe .node.on .t{color:var(--accent-ink)}
+#pipe .arrow{align-self:center;color:var(--muted-foreground);font-size:12px;text-align:center;min-width:64px}
+.cap{margin-top:12px;color:var(--muted-foreground);font-size:12.5px}
+.cap::before{content:"\2192 ";color:var(--primary);font-weight:700}
+@media (prefers-reduced-motion:reduce){#pipe .node{transition:none}}
+</style>
+<script>
+var steps=[["ideas/","one-line premises, captured before they fade"],["drafts/","active prose; CRDT history covers revisions"],["published/","shipped work — treat as immutable"]];
+var edges=["commit to it","ship it"];
+var pipe=document.getElementById("pipe"),nodes=[];
+steps.forEach(function(s,i){
+ if(i){var a=document.createElement("div");a.className="arrow";a.innerHTML="→<br><span style='font-size:10px'>"+edges[i-1]+"</span>";pipe.appendChild(a);}
+ var d=document.createElement("div");d.className="node";
+ var t=document.createElement("div");t.className="t";t.textContent=s[0];
+ var sub=document.createElement("div");sub.className="s";sub.textContent=s[1];
+ d.appendChild(t);d.appendChild(sub);
+ d.onclick=function(){pinned=true;set(i);};
+ pipe.appendChild(d);nodes.push(d);
+});
+var cur=0,pinned=false;
+function set(i){cur=i;nodes.forEach(function(n,j){n.classList.toggle("on",j===i);});}
+set(0);
+if(!matchMedia("(prefers-reduced-motion:reduce)").matches){setInterval(function(){if(!pinned)set((cur+1)%nodes.length);},1600);}
+</script>
+```
+
+The point is to keep the friction where it belongs. Capturing an idea should cost one line. Drafting should feel like writing, not file management. And publishing should be a deliberate step that freezes the piece — to revise later, you copy it back to a new draft rather than editing history.
+
+Essayists and newsletter writers get a frictionless place to capture premises before good ideas escape. Drafting with an AI collaborator happens on the actual piece, every revision in the timeline, instead of scattered across chat windows. And shipped work stays separate from work in progress — a clean record of published pieces with canonical URLs and channels.
+
+## The flow
+
+```
+ideas/ one-line premises, headlines, fragments — kept short on purpose
+ ↓ commit to writing it
+drafts/ active prose; frontmatter tracks status, word count, parent idea
+ ↓ ship
+published/ shipped work; carries published_at, canonical_url, channel — immutable
+```
+
+The pack ships an `idea`, `draft`, and `published` template. Structure only — the meaning of each stage lives in the folder guidance the agent reads, so your prose stays uncluttered.
+
+## The scenario
+
+A thought hits you on a walk: *"the best abstraction is the one you didn't write."* You drop it into `ideas/` as a single line. Two weeks later you commit to it:
+
+<CopyPrompt>Promote the "best abstraction is the one you didn't write" idea into a draft. Pull the premise into the draft template and set status: drafting.</CopyPrompt>
+
+You write it with your agent over a few sessions — every revision captured in the [timeline](../features/timeline-and-recovery.mdx), no manual versioning. When it's ready you publish, and the piece moves to `published/` with its canonical URL filled in. The draft's full history stays intact; the published copy is frozen.
+
+## What's in your project after seeding
+
+Pick **Writing pipeline** in the starter-pack picker, or run:
+
+```bash
+ok seed --pack writing-pipeline
+```
+
+By default the pack nests under a `writing/` subfolder:
+
+```
+your-project/
+└── writing/
+ ├── ideas/ one file per premise, flat
+ ├── drafts/ active prose; status: drafting | review
+ └── published/ shipped, immutable
+```
+
+Each folder carries its `.ok/frontmatter.yml` guidance and templates. If a draft needs research notes, the agent creates `drafts/<slug>/research/` on demand rather than cluttering the top level.
+
+<Callout type="info" title="Seeding also installs a skill">
+ `ok seed --pack writing-pipeline` installs the **Writing pipeline** project skill into your agent editors (Claude Code, Cursor, Codex, OpenCode). It's the "how to work here" guidance behind the behaviors below — the stage promotions, the idle-draft nudges, the publish-time URL fill — 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](../features/skills.mdx) and [what OpenKnowledge writes to disk](../reference/what-open-knowledge-writes.mdx).
+</Callout>
+
+## What the agent does for you
+
+_These behaviors are encoded in the pack skill and run **when you prompt the agent** — they are not background automations that fire on a timer._
+
+| When you ask | The agent |
+| --- | --- |
+| An idea sits idle > 30 days | Surfaces it to park or promote — so `ideas/` stays a live shortlist, not a graveyard |
+| A draft sits idle > 14 days | Nudges it; for drafts in `review`, suggests publication targets based on `target_form` |
+| A draft needs sources | Creates `drafts/<slug>/research/` on demand instead of a top-level folder |
+| You publish | Auto-fills `canonical_url` when you paste a Substack / Ghost / Mirror URL into the file |
+
+## Cadence
+
+| When | Do |
+| --- | --- |
+| Whenever a premise strikes | One line into `ideas/`. That's the whole capture step |
+| When you commit to a piece | Promote the idea into `drafts/`; write with your agent, revisions tracked automatically |
+| On ship | Move to `published/`; let the agent fill `canonical_url` and `channel` |
+| To revise a published piece | Copy it back to a new draft — never edit `published/` in place |
+| Monthly | Ask the agent to surface stale ideas and stalled drafts |
+
+## Further reading
+
+- **[LLM wiki workflow](./karpathy-llm-wiki.mdx).** If your writing is source-grounded research rather than original prose, the source-curation posture fits better.
+- **[Editor](../features/editor.mdx).** The WYSIWYG surface you'll actually draft in.
+- **[Timeline and recovery](../features/timeline-and-recovery.mdx).** Where your draft revisions live — the reason there are no named-revision folders.
+- **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** MCP-capable agent hosts.
diff --git a/packages/server/src/mcp/tools/shared.ts b/packages/server/src/mcp/tools/shared.ts
index 7b17da40b..86b0c7247 100644
--- a/packages/server/src/mcp/tools/shared.ts
+++ b/packages/server/src/mcp/tools/shared.ts
@@ -184,6 +184,13 @@ export const documentResultBaseShape = {
"Advisory entries discriminated by `kind`. Write-integrity kinds — `content-divergence` (converged Y.Text didn't byte-match what you composed) and `disk-edit-reconciled` (an out-of-band disk edit was folded in before your write) — mean re-read the doc. The renderability kind `mermaid-parse-error` means the write landed but that fence will not render — fix it and re-edit.",
),
brokenLinks: brokenLinksOutputField,
+ templateHint: z
+ .array(z.object({ name: z.string(), description: z.string().optional() }))
+ .min(1)
+ .optional()
+ .describe(
+ "Templates the parent folder offers, present only when a create passed no `template`. A nudge — the write already landed; pass `template` next time to match the folder's shape.",
+ ),
} as const;
/**
diff --git a/packages/server/src/mcp/tools/verb-tools.test.ts b/packages/server/src/mcp/tools/verb-tools.test.ts
index 8c83b039e..df3484a6d 100644
--- a/packages/server/src/mcp/tools/verb-tools.test.ts
+++ b/packages/server/src/mcp/tools/verb-tools.test.ts
@@ -228,6 +228,89 @@ describe('edit({ template }) — fence trailing whitespace (fm-delimiter hazard)
});
});
+describe('write({ document }) — template-availability nudge on create', () => {
+ // Templates only get used if the agent knows they exist; it may write from
+ // memory without an `exec ls` first. So a create into a folder that ships a
+ // template, with no `template` passed, surfaces the folder's menu — without
+ // blocking the write that already landed.
+ function withWriteStub(cwd: string, run: (handler: Handler) => Promise<void>) {
+ const stub = Bun.serve({
+ port: 0,
+ async fetch(req) {
+ if (req.method === 'POST' && new URL(req.url).pathname === '/api/agent-write-md') {
+ const body = (await req.json()) as { docName?: string };
+ return Response.json({
+ docName: body.docName,
+ systemSubscriberCount: 1,
+ brokenLinks: [],
+ });
+ }
+ return Response.json({ error: 'unexpected request' }, { status: 404 });
+ },
+ });
+ let handler: Handler | undefined;
+ const server = {
+ registerTool(_name: string, _cfg: unknown, h: Handler) {
+ handler = h;
+ },
+ } as unknown as ServerInstance;
+ registerWrite(server, {
+ serverUrl: `http://127.0.0.1:${stub.port}`,
+ config: BASE_CONFIG,
+ resolveCwd: async () => cwd,
+ } as unknown as Parameters<typeof registerWrite>[1]);
+ if (!handler) throw new Error('tool did not register');
+ return (async () => {
+ try {
+ await run(handler);
+ } finally {
+ stub.stop(true);
+ }
+ })();
+ }
+
+ function seedNoteTemplate(cwd: string) {
+ mkdirSync(join(cwd, 'notes', '.ok', 'templates'), { recursive: true });
+ writeFileSync(
+ join(cwd, 'notes', '.ok', 'templates', 'note.md'),
+ '---\ntitle: Note\ndescription: A plain note\n---\n\n# \n',
+ );
+ }
+
+ test('create with no template nudges toward the folder template (text + structured)', async () => {
+ const cwd = newProject();
+ seedNoteTemplate(cwd);
+ await withWriteStub(cwd, async (write) => {
+ const r = await write({ document: { path: 'notes/first', content: '# First\n' } });
+ expect(r.isError).toBeUndefined();
+ expect(textOf(r)).toContain('templates you can start from: note (A plain note)');
+ const doc = (r.structuredContent?.document ?? {}) as Record<string, unknown>;
+ const hint = doc.templateHint as Array<{ name: string }> | undefined;
+ expect(hint?.[0]?.name).toBe('note');
+ });
+ });
+
+ test('create WITH a template does not nudge', async () => {
+ const cwd = newProject();
+ seedNoteTemplate(cwd);
+ await withWriteStub(cwd, async (write) => {
+ const r = await write({ document: { path: 'notes/second', template: 'note' } });
+ expect(r.isError).toBeUndefined();
+ expect(textOf(r)).not.toContain('templates you can start from');
+ });
+ });
+
+ test('create in a folder with no templates does not nudge', async () => {
+ const cwd = newProject();
+ mkdirSync(join(cwd, 'scratch'), { recursive: true });
+ await withWriteStub(cwd, async (write) => {
+ const r = await write({ document: { path: 'scratch/note', content: '# Note\n' } });
+ expect(r.isError).toBeUndefined();
+ expect(textOf(r)).not.toContain('templates you can start from');
+ });
+ });
+});
+
describe('D13 migration meta-test — no retired tool name survives in the skill surface', () => {
const RETIRED = [
'write_document',
diff --git a/packages/server/src/mcp/tools/write.ts b/packages/server/src/mcp/tools/write.ts
index ecb61e5ba..e305e817e 100644
--- a/packages/server/src/mcp/tools/write.ts
+++ b/packages/server/src/mcp/tools/write.ts
@@ -128,6 +128,12 @@ type WriteOneResult =
position: string;
fromTemplate?: string;
extensionNote?: string;
+ /**
+ * Templates the parent folder offers, surfaced only on a create that
+ * passed no `template`. Nudges the agent toward the folder's shape
+ * without blocking the write that already landed.
+ */
+ templateHint?: readonly { name: string; description?: string }[];
raw: WriteApiResult;
}
| { docName: string; ok: false; error: string };
@@ -276,6 +282,22 @@ async function writeOneDoc(
effectivePosition = 'replace';
}
+ // Nudge: creating a doc in a folder that ships templates, but reaching for
+ // none. Templates only get used if the agent knows they exist, and it may
+ // write from memory without an `exec ls` first — so surface the folder's menu
+ // on the write itself. Create-only (an overwrite/append is deliberate) and
+ // skipped when a template WAS used.
+ let templateHint: readonly { name: string; description?: string }[] | undefined;
+ if (spec.template === undefined && !docExists) {
+ const available = resolveTemplatesAvailable(cwd, parentFolderOf(docName), { depth: 1 });
+ if (available.length > 0) {
+ templateHint = available.map((t) => ({
+ name: t.name,
+ ...(t.description ? { description: t.description } : {}),
+ }));
+ }
+ }
+
if (spec.template !== undefined) {
const parentFolder = parentFolderOf(docName);
const available = resolveTemplatesAvailable(cwd, parentFolder, { depth: 1 });
@@ -377,10 +399,22 @@ async function writeOneDoc(
position: effectivePosition,
...(spec.template !== undefined ? { fromTemplate: spec.template } : {}),
...(extensionNote ? { extensionNote } : {}),
+ ...(templateHint ? { templateHint } : {}),
raw: result,
};
}
+/**
+ * One-line nudge listing a folder's available templates. Info (`ℹ`), not a
+ * warning (`⚠`) — the write landed; this only points at a cleaner next time.
+ */
+function formatTemplateHintLine(hint: readonly { name: string; description?: string }[]): string {
+ const list = hint
+ .map((t) => (t.description ? `${t.name} (${t.description})` : t.name))
+ .join(', ');
+ return `ℹ This folder has templates you can start from: ${list}. Pass \`template: "${hint[0]?.name ?? ''}"\` next time to match the folder's shape (the doc still landed).`;
+}
+
// ─────────────────────────── target handlers ───────────────────────────
async function handleFolder(
@@ -698,6 +732,7 @@ async function handleBatch(
position: r.position,
...(preview ? { previewUrl: preview.url } : {}),
...(warnings ? { warnings } : {}),
+ ...(r.templateHint ? { templateHint: r.templateHint } : {}),
brokenLinks,
};
});
@@ -718,6 +753,11 @@ async function handleBatch(
const brokenBrief = formatBrokenLinkBrief(d.brokenLinks);
if (brokenBrief) baseParts.push(brokenBrief);
}
+ if (r.ok && r.templateHint) {
+ baseParts.push(
+ `ℹ ${r.templateHint.length} template${r.templateHint.length === 1 ? '' : 's'} available here (pass \`template\`).`,
+ );
+ }
return baseParts.join(' ');
});
const perDocNotes = documents.flatMap((spec, i) => {
@@ -788,6 +828,7 @@ async function handleSingleDoc(
lines.push(...formatAdvisoryLines(advisoryWarnings));
}
lines.push(...formatBrokenLinkLines(brokenLinks));
+ if (w.templateHint) lines.push(formatTemplateHintLine(w.templateHint));
const text = lines.join('\n');
// Uniform preview envelope top-level; document-specific signals nest under
@@ -800,6 +841,7 @@ async function handleSingleDoc(
if (hints) document.hints = hints;
if (summaryResult) document.summary = summaryResult;
if (advisoryWarnings) document.warnings = advisoryWarnings;
+ if (w.templateHint) document.templateHint = w.templateHint;
const warning = noPreviewAnywhere ? buildPreviewAttachWarning(preview, autoOpen) : undefined;
return textPlusStructured(text, nestDocResult(preview, warning, document));
}