@inkeep/open-knowledge 0.46.0-beta.7 → 0.46.0-beta.8

package/dist/THIRD_PARTY_NOTICES.md

@@ -4566,6 +4566,11 @@ Homepage: https://github.com/pillarjs/path-to-regexp
 
 Copyright (c) 2014 Blake Embrey (hello@blakeembrey.com)
 
+### `pend@1.2.0`
+Homepage: https://github.com/andrewrk/node-pend
+
+Copyright (c) 2014 Andrew Kelley
+
 ### `picomatch@4.0.5`
 Homepage: https://github.com/micromatch/picomatch
 
@@ -5559,6 +5564,11 @@ Homepage: https://github.com/yjs/y-protocols#readme
 
 Copyright (c) 2019 Kevin Jahns <kevin.jahns@protonmail.com>.
 
+### `yauzl@3.4.0`
+Homepage: https://github.com/thejoshwolfe/yauzl
+
+Copyright (c) 2014 Josh Wolfe
+
 ### `yazl@3.3.1`
 Homepage: https://github.com/thejoshwolfe/yazl
 

package/dist/{acp-harness-probe-BladNRtA.mjs → acp-harness-probe-4DjqrOhu.mjs}

@@ -1,3 +1,3 @@
-import{K as e}from"./sleep-IcuyYCzq.mjs";import{_ as t,b as n,d as r}from"./write-project-skill-BzhJIXSv.mjs";import{d as i}from"./init-CxYfITcc.mjs";import{execFileSync as a}from"node:child_process";import{dirname as o,join as s}from"node:path";import{existsSync as c,mkdirSync as l,readFileSync as u,writeFileSync as d}from"node:fs";import{homedir as f}from"node:os";var p=e();const m=`open-knowledge`;function h(e){try{e()}catch{}}var g=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(m,e).getPassword()}catch(t){return h(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return h(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return h(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(m,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(m,e).deletePassword()}catch{}}},_=class{backend=`file`;authFile;constructor(e){this.authFile=e??s(f(),`.ok`,`auth.yml`)}read(){if(!c(this.authFile))return{};try{return(0,p.parse)(u(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=o(this.authFile);c(t)||l(t,{recursive:!0,mode:448}),d(this.authFile,(0,p.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},v=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function y(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(m,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
+import{K as e}from"./sleep-IcuyYCzq.mjs";import{_ as t,b as n,d as r}from"./write-project-skill-DZsw6Rkw.mjs";import{d as i}from"./init-DWCsIT2Y.mjs";import{execFileSync as a}from"node:child_process";import{dirname as o,join as s}from"node:path";import{existsSync as c,mkdirSync as l,readFileSync as u,writeFileSync as d}from"node:fs";import{homedir as f}from"node:os";var p=e();const m=`open-knowledge`;function h(e){try{e()}catch{}}var g=class{backend=`keyring`;constructor(e){this.onKeychainRead=e}async get(e){let{Entry:t}=await import(`@napi-rs/keyring`),n;try{n=new t(m,e).getPassword()}catch(t){return h(()=>this.onKeychainRead?.({kind:`read-error`,host:e,error:t instanceof Error?t.name:`unknown`})),null}if(n==null)return h(()=>this.onKeychainRead?.({kind:`absent`,host:e})),null;try{return JSON.parse(n)}catch{return h(()=>this.onKeychainRead?.({kind:`corrupt-entry`,host:e,error:`corrupt-entry`})),null}}async set(e,t,n,r){let{Entry:i}=await import(`@napi-rs/keyring`),a=new i(m,e),o={login:t,token:n,...r};a.setPassword(JSON.stringify(o))}async clear(e){let{Entry:t}=await import(`@napi-rs/keyring`);try{new t(m,e).deletePassword()}catch{}}},_=class{backend=`file`;authFile;constructor(e){this.authFile=e??s(f(),`.ok`,`auth.yml`)}read(){if(!c(this.authFile))return{};try{return(0,p.parse)(u(this.authFile,`utf-8`))??{}}catch(e){let t=e instanceof Error?e.message:`unknown error`;return process.stderr.write(`[auth] Failed to parse ${this.authFile}: ${t}. Starting with empty credentials.\n`),{}}}write(e){let t=o(this.authFile);c(t)||l(t,{recursive:!0,mode:448}),d(this.authFile,(0,p.stringify)(e),{mode:384})}async get(e){return this.read()[e]??null}async set(e,t,n,r){let i=this.read();i[e]={login:t,token:n,...r},this.write(i)}async clear(e){let t=this.read();delete t[e],this.write(t)}},v=class{backend=`keyring`;constructor(e,t){this.keychain=e,this.file=t}async get(e){let t=await this.keychain.get(e);if(t!=null)return t;let n=await this.file.get(e);if(n==null)return null;try{await this.keychain.set(e,n.login,n.token,{gitProtocol:n.gitProtocol,name:n.name,email:n.email}),await this.file.clear(e),process.stderr.write(`[auth] migrated ${e} credential from ~/.ok/auth.yml to the OS keychain\n`)}catch{}return n}set(e,t,n,r){return this.keychain.set(e,t,n,r)}async clear(e){await this.keychain.clear(e),await this.file.get(e)!=null&&await this.file.clear(e)}};async function y(e,t){try{let{Entry:n}=await import(`@napi-rs/keyring`);return new n(m,`__probe__`),process.stderr.write(`[auth] token storage: OS keychain
 `),h(()=>t?.onBackendSelected?.({backend:`keyring`})),new v(new g(t?.onKeychainRead),new _(e))}catch(n){let r=n instanceof Error?`${n.name}: ${n.message}`:String(n);return process.stderr.write(`[auth] token storage: file (~/.ok/auth.yml) — OS keychain unavailable: ${r}\n`),h(()=>t?.onBackendSelected?.({backend:`file`,reason:r})),new _(e)}}function b(e){let t=null;return function(){if(t)return t;let n=2e3;return t=(async()=>{let t=null,r=new Promise(r=>{t=setTimeout(()=>{process.stderr.write(`[auth] token storage: keyring init exceeded ${n}ms; falling back to file (~/.ok/auth.yml)\n`),r(new _(e))},n)});try{return await Promise.race([y(e),r])}catch{return new _(e)}finally{t!==null&&clearTimeout(t)}})(),t}}function x(e){let t=b(e);return{async get(e){let n=await(await t()).get(e);return n===null?null:{token:n.token}}}}function S(e){let t=b(e);return{backend:`file`,async get(e){return(await t()).get(e)},async set(e,n,r,i){return(await t()).set(e,n,r,i)},async clear(e){return(await t()).clear(e)}}}async function C(e,t){let n=[],r=new _(t);await r.get(e)!=null&&(await r.clear(e),n.push(`file`));let i;try{let{Entry:t}=await import(`@napi-rs/keyring`);new t(m,`__probe__`);let r,a=await new g(e=>{e.kind===`read-error`&&(r=e.error??`read-error`)}).get(e);if(r!==void 0)i=r;else if(a!=null)try{new t(m,e).deletePassword(),n.push(`keychain`)}catch(e){i=e instanceof Error?e.name:`delete-error`}}catch{}return{touched:n,keychainError:i}}const w=[`/opt/homebrew/bin/gh`,`/usr/local/bin/gh`,`/opt/local/bin/gh`,`/snap/bin/gh`,`/usr/bin/gh`],T={encoding:`utf-8`,stdio:[`ignore`,`pipe`,`pipe`],timeout:5e3,windowsHide:!0};function E(e,t={}){let n=t._exec??a,r=t._fileExists??c,i=[`auth`,`token`,...e?[`--hostname`,e]:[]],o=[`gh`,...w.filter(r)];for(let e of o)try{let t=n(e,i,T).toString().trim();if(t.length>0)return{available:!0,token:t}}catch{}return{available:!1}}function D(e,a,o){let s=r[e],c=e===`opencode`?n:t,l=[],u=s.projectConfigPath?.(a);u!==void 0&&l.push({scope:`project`,configPath:u});try{l.push({scope:`user`,configPath:s.configPath(a,o)})}catch{}for(let t of l){let n=i(s,a,o,t.configPath);if(n!==null&&c(n))return{editorId:e,scope:t.scope,configPath:t.configPath}}return null}export{x as a,y as i,E as n,S as o,C as r,D as t};
-//# sourceMappingURL=acp-harness-probe-BladNRtA.mjs.map
+//# sourceMappingURL=acp-harness-probe-4DjqrOhu.mjs.map

package/dist/assets/skills/discovery/SKILL.md

@@ -1,9 +1,8 @@
 ---
 name: open-knowledge-discovery
-description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to share an OpenKnowledge project with collaborators, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill at `.claude/skills/open-knowledge/` whenever `ok init` runs. If the user appears to be editing markdown inside a `.ok/` project and this is the only OK skill loaded, advise them to re-run `ok init` to install the project-local skill."
+description: "Read when the user asks what OpenKnowledge is, wants to install it on a repository, wants to open or preview a single markdown file that is not part of an OpenKnowledge project, wants to share an OpenKnowledge project with collaborators, or asks how `ok init` / `ok cowork` / OK Desktop set up a project. Do NOT load to perform OpenKnowledge reads/writes — the runtime guidance for editing markdown inside an initialized OK project ships as a separate project-local skill at `.claude/skills/open-knowledge/` whenever `ok init` runs."
 compatibility: "Any agent host — no MCP server required. Pure discovery + install guidance."
 metadata:
-  version: "0.46.0-beta.7"
   author: "Inkeep"
   repository: "https://github.com/inkeep/open-knowledge"
 ---

package/dist/assets/skills/packs/codebase-wiki/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: open-knowledge-pack-codebase-wiki
-version: "0.18.0"
-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."
+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`, or when asked to generate or refresh a wiki of this codebase. Carries the per-folder rules and freshness + log discipline, summarizes the audience/depth knobs and source-reference convention, and bundles the full generate/refresh procedure in `references/`. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack codebase-wiki`."
 metadata:
   pack: "codebase-wiki"
@@ -12,7 +11,7 @@ metadata:
 
 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.
+> 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
 
@@ -30,7 +29,7 @@ wiki/
 
 ## 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).
+Don't free-hand it — read **[references/generate-and-refresh.md](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`.
 
@@ -41,14 +40,14 @@ Two natural-language knobs, read from the user's request (e.g. "build the wiki,
 - **`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.
+[references/generate-and-refresh.md](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.
 
-The full rules — the GitHub-URL / relative fallback, the `#Lxx` caveat, and the exact code-span shape — live in the `workflow({ kind: "wiki" })` guide.
+The full rules — the GitHub-URL / relative fallback, the `#Lxx` caveat, and the exact code-span shape — live in [references/generate-and-refresh.md](references/generate-and-refresh.md).
 
 ## Per-folder rules
 
@@ -81,4 +80,4 @@ The full rules — the GitHub-URL / relative fallback, the `#Lxx` caveat, and th
 
 ## 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.
+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 [references/generate-and-refresh.md](references/generate-and-refresh.md), not repeated inside document bodies.

package/dist/assets/skills/packs/codebase-wiki/references/generate-and-refresh.md

@@ -0,0 +1,160 @@
+# Codebase Wiki — Generate + Refresh
+
+The user wants a **wiki of this codebase**, living in their own repo. Read the source code and author a navigable, diagram-rich, source-grounded wiki as markdown INTO the OK knowledge base, under `wiki/`. It is version-controlled, private by default, co-editable, renders in OK's live preview, and becomes grounding context for future agent sessions.
+
+The content directory is the resolved `content.dir` — read it with `config({ key: 'content.dir' })` if you don't already know it. The wiki lives at `<content-dir>/wiki/`.
+
+**Two toolsets, two jobs.** Read source code with your 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, `exec` for markdown listings). Never hand-write the wiki markdown with native `Write`/`Edit` — that bypasses attribution, backlinks, and the live preview.
+
+**Server requirement.** Phases that author or audit the wiki (`write`/`edit`/`links`/`search`) need the OK Hocuspocus server. Source reading (native tools) and git do not. If a `write` returns "Hocuspocus server is not running", tell the user to run `ok start` and retry — do NOT fall back to native file writes for the wiki markdown.
+
+**Prerequisite.** This procedure assumes the `codebase-wiki` pack is seeded (`ok seed --pack codebase-wiki` → `wiki/` with `architecture/ modules/ flows/ concepts/ guides/`, each carrying folder frontmatter + a page template, plus `wiki/OVERVIEW.md` + `wiki/log.md`). If `exec("ls -A <content-dir>/wiki")` shows the layout is missing, tell the user to seed first, then start over.
+
+---
+
+## The two knobs
+
+Read these from the user's natural-language request (e.g. "build the wiki, public and exhaustive"). They are NOT engine config — they tune what you produce. Record the chosen profile in `wiki/OVERVIEW.md` frontmatter (`profile: <audience>/<depth>`) so refreshes stay consistent.
+
+| Knob | Values | Effect |
+|---|---|---|
+| `audience` | `internal` (default) or `public` | `internal`: dense; may cite internal infra; reference source via **relative links + symbol code-spans**. `public`: polished prose; **omit secrets, internal infra, ticket/PR numbers**; reference source via **GitHub blob URLs** (only if a remote exists — else fall back to relative). |
+| `depth` | `tour`, `standard` (default), or `exhaustive` | `tour`: OVERVIEW + architecture + top flows only (fold modules into architecture). `standard`: + one page per package/module + concepts. `exhaustive`: + sub-module pages, `guides/`, per-flow failure modes, denser diagrams. |
+
+Default when the user says nothing: `internal` / `standard`.
+
+---
+
+## Source-reference convention (how wiki pages point at code)
+
+- **Intra-wiki navigation** → OK doc links (`[Auth flow](../flows/auth.md)`). These build the full backlink / hub / orphan graph. Link liberally — density is how the wiki stays navigable.
+- **Code references, `internal`** → a relative markdown link to the source file plus an inline code-span for the symbol — e.g. the `bootServer()` symbol in `[boot.ts](../../packages/server/src/boot.ts)`. Relative source links click-open in the asset preview and stay out of the navigation graph (the `links` graph tracks only `.md`/`.mdx` edges, so source links never show as graph dead-links or orphans) — but the write/edit `brokenLinks` response DOES validate them: a wrong-depth path resolving to a missing file is reported `no-such-file`, and one that overshoots the content root is `unresolvable`. So count the `../` hops from the page's own folder, not the wiki root. A cosmetic `#Lxx` is fine but not navigable.
+- **Code references, `public`** → GitHub blob URLs (`https://github.com/<org>/<repo>/blob/<branch>/path/to/file.ts`) so a reader without the repo can follow them. Detect the remote with `git remote get-url origin`; if there is none, fall back to relative links.
+
+Never invent paths — every source reference must point at a file you actually read.
+
+---
+
+## Mode detection — generate vs. refresh
+
+`exec("cat <content-dir>/wiki/OVERVIEW.md")` and read its frontmatter:
+
+- **`source_commit` is empty / OVERVIEW is the seeded stub** → **GENERATE** (Phases 0-7 below).
+- **`source_commit` is stamped with a commit** → **REFRESH** (jump to the *Refresh mode* section). Reuse the recorded `profile` unless the user explicitly changes a knob.
+
+---
+
+## GENERATE — phased, STOP-gated
+
+Work the phases in order. Do not skip or batch ahead of a STOP gate. Each page is authored with OK `write`/`edit`; create from the seeded templates (`write({ document: { path, template: "<name>" } })`) so pages start with the right skeleton, then fill the sections.
+
+### Phase 0 — Resolve profile + scope (STOP gate 0)
+
+1. Resolve `audience` + `depth` from the request (default `internal/standard`).
+2. Propose the **coverage set** (which packages/dirs the wiki will document) and **exclusions** (vendored deps, build output, generated code, fixtures — `node_modules/`, `dist/`, `build/`, `vendor/`, `third_party/`, `coverage/`, lockfiles).
+3. Present profile + coverage + exclusions to the user. **Wait for confirmation.**
+
+### Phase 1 — Survey (no writes) (STOP gate 1)
+
+Read, don't write. Use native tools:
+
+1. **Detect the stack** — languages, build system, package manager, workspace/monorepo layout, entry points. (`Glob` for manifests: `package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `*.csproj`; read them.)
+2. **Bootstrap from existing docs** — READ `README`, `AGENTS.md`/`CLAUDE.md`, `ARCHITECTURE.md`, `CONTRIBUTING`, per-package READMEs. **Summarize and link to them; do NOT duplicate.** They are your highest-signal starting point.
+3. **Map the modules** — list packages/top-level source dirs; note each one's rough purpose and entry points.
+4. Produce an **inventory + a proposed page list scaled to `depth`**:
+   - `tour` → OVERVIEW + 1-3 architecture pages + top 1-3 flows.
+   - `standard` → + one module page per package + a concepts glossary.
+   - `exhaustive` → + sub-module pages, `guides/`, per-flow failure modes.
+5. Present the page list. **Wait for confirmation.**
+
+### Phase 2 — Overview hub
+
+Author `wiki/OVERVIEW.md` (edit the seeded stub in place):
+
+1. **What this is** — 1-2 paragraphs: what the project does, who it's for.
+2. **Architecture at a glance** — a big-picture `mermaid` diagram. Example:
+   ```mermaid
+   flowchart TD
+     CLI[ok CLI] --> Server[Hocuspocus server]
+     App[React editor] --> Server
+     Server --> Disk[(markdown + .ok/)]
+   ```
+   (Mermaid label text has sharp edges — if a write returns a `mermaid-parse-error` warning, fix that fence and re-edit. `palette({ components: ["Mermaid"] })` lists the gotchas.)
+3. **Navigation** — a map that links **every section and every page you will create**, as OK doc links. OVERVIEW is the hub; everything must be reachable from it.
+4. **Stamp frontmatter**: set `profile: <audience>/<depth>` and `source_commit: <git rev-parse HEAD>`. `source_commit` is the freshness anchor refresh mode diffs against — get it right.
+
+### Phase 3 — Architecture pages
+
+One page per architectural area (boundaries, layers, subsystems, cross-cutting concerns). Each: a system-context or component `mermaid` diagram, the key components (with source references per the convention), and the design decisions behind them. Cross-link the modules and flows each area touches. (At `depth: tour`, modules fold into these pages.)
+
+### Phase 4 — Module pages
+
+One page per package/module (skip at `tour`; scale sub-module depth by knob). Use the `module-page` template: purpose, responsibilities, public API / entry points, **key files** (linked per the convention), dependencies, and the flows it participates in. Cross-link concepts and flows.
+
+### Phase 5 — Flows
+
+Key end-to-end sequences (request lifecycle, build/deploy, a core interaction) as `mermaid` sequence or flow diagrams + narrative. At `exhaustive`, add a **Failure modes** section per flow. Link every module and concept the flow crosses.
+
+### Phase 6 — Concepts / glossary
+
+Atomic pages for domain terms and core abstractions (one term each): definition, why it matters, where it lives in the code. Keep them small and densely cross-linked so each concept becomes a hub for everywhere it appears. Link concepts from the architecture/module/flow pages that use them.
+
+### Phase 7 — Link-graph activation + audit
+
+1. Confirm **OVERVIEW links every page** (it is the nav hub). Add any missing nav links. This is OVERVIEW's check — it's a *source* (high out-degree), verified by forward links here, not by the `hubs` view below.
+2. Run `links({ kind: ["orphans", "hubs", "dead"] })`:
+   - **orphans** — pages nothing links to. Adopt each by linking it from OVERVIEW or a relevant section page (or, rarely, justify it as intentionally standalone).
+   - **hubs** — ranks by *inbound* links. Confirm your **concept/module pages** show up here — that's the signal cross-linking actually happened. Don't expect `OVERVIEW`: a freshly authored nav page has almost no inbound links, so it won't appear (and that's correct — its coverage was checked in step 1).
+   - **dead** — fix or remove every dead link. (Source-file links don't appear in this graph — only `.md`/`.mdx` edges are tracked — but they ARE validated by `brokenLinks` on each write/edit, per the code-reference rule above.)
+3. Append a `wiki/log.md` entry (see *Log discipline*).
+4. Tell the user the wiki is ready and surface the OVERVIEW preview URL.
+
+---
+
+## REFRESH mode (after code changes)
+
+Incremental by default — don't re-read the whole repo.
+
+1. Read `source_commit` + `profile` from `wiki/OVERVIEW.md` frontmatter. Reuse the profile unless the user changed a knob.
+2. `git diff --stat <source_commit>..HEAD`. Inspect the changed paths.
+3. **Map changed code → affected pages.** For each changed package/area, update its module/architecture/flow pages (read the changed source first). Update OVERVIEW only if the structure changed (new package, removed subsystem, new top-level flow).
+4. **Full-regen fallback.** If the diff is large or structural (many packages, a restructure), or git is unavailable / `source_commit` is missing, fall back to a full GENERATE pass rather than a partial patch.
+5. **Re-stamp** `source_commit` to the new `git rev-parse HEAD` and re-run the Phase 7 link-graph audit on the touched pages.
+6. Append a `wiki/log.md` refresh entry.
+
+---
+
+## Log discipline
+
+`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 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: <which sections/packages were written or updated>
+- Pages: [Overview](./OVERVIEW.md), [Server](./modules/server.md), ...
+```
+
+---
+
+## STOP rules / anti-patterns (load-bearing)
+
+- **Author wiki markdown only through OK `write`/`edit`** — never native `Write`/`Edit` (loses attribution, backlinks, live preview). Read source with native tools; write the wiki with OK.
+- **Summarize existing docs, don't duplicate them** — link to `README`/`ARCHITECTURE.md`; the wiki adds navigation and synthesis, not a copy.
+- **Every source reference points at a file you actually read** — no invented paths or symbols.
+- **Respect the profile** — at `audience: public`, never write secrets, internal infra, or ticket/PR numbers; reference code via GitHub URLs (or relative if no remote).
+- **OVERVIEW is the hub** — every page must be reachable from it. Don't leave orphans (Phase 7 catches them).
+- **Don't scaffold folders by hand** — the `codebase-wiki` pack already created `wiki/` with templates; if it's missing, seed first.
+- **Scale to `depth`** — don't write `guides/` or per-flow failure modes at `tour`; don't fold modules into architecture at `exhaustive`.
+- **Refresh is incremental** — diff `source_commit..HEAD` and touch only affected pages; full-regen only on large/structural diffs or when git is unavailable.
+
+---
+
+## Exit conditions
+
+- **Pack not seeded** — `wiki/` layout missing → tell the user to run `ok seed --pack codebase-wiki`, then start over. Exit.
+- **Server down** — a `write`/`links` call reports the server is not running → tell the user to run `ok start` and retry. Exit cleanly; resuming keeps already-written pages.
+- **User aborts at a STOP gate** → exit cleanly, leaving any already-written pages in place.
+- **Empty / unreadable repo** (no source detected in Phase 1) → tell the user there's nothing to document yet. Exit.

package/dist/assets/skills/packs/entity-vault/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: open-knowledge-pack-entity-vault
-version: "0.18.0"
-description: "How to work in a Personal CRM project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
+description: "How to work in a Personal CRM project (the `entity-vault` starter pack, GBrain-compatible): a typed-entity vault of people, companies, meetings, and concepts, each a dossier with a rewritable summary plus an append-only timeline. Read when the project has these folders, OR when asked to capture notes about a person or company, log a meeting, prep for an upcoming meeting, or answer who someone is and what was last said. Carries the dossier convention and entity-extraction behaviors so that guidance does not live inside template bodies or folder descriptions. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack entity-vault`."
 metadata:
   pack: "entity-vault"
@@ -12,7 +11,7 @@ metadata:
 
 A Personal CRM built as a typed-entity vault, inspired by Garry Tan's gbrain. Each entity is a dossier; the agent keeps dossiers current by extracting entities from meeting notes and original thinking. This skill holds those behaviors so templates and folder descriptions stay clean. The Markdown shape is **GBrain-compatible**: if the external `gbrain` CLI is installed, it can import/sync the same vault.
 
-> Pack guidance. The platform `open-knowledge` skill still governs every markdown operation.
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the dossier conventions on top.
 
 ## The dossier convention (the load-bearing rule)
 

package/dist/assets/skills/packs/knowledge-base/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: open-knowledge-pack-knowledge-base
-version: "0.18.0"
-description: "How to work in a Knowledge Base project (the `knowledge-base` starter pack). Read when the project has the three-layer source-grounded layout — `external-sources/` → `research/` → `articles/` — wired to the `workflow` MCP tool's ingest / research / consolidate kinds. Carries the pack's workflow, per-folder rules, status flows, and log discipline so this guidance does NOT live inside template bodies or log.md. Complements the platform `open-knowledge` skill; does not replace it."
+description: "How to work in a Knowledge Base project (the `knowledge-base` starter pack). Read when the project has the three-layer source-grounded layout — `external-sources/` → `research/` → `articles/` — or when asked how this project is organized. Carries the layer model, per-folder rules, status flows, and log discipline so this guidance does NOT live inside template bodies or log.md. The three procedures live elsewhere: ingest in the platform `open-knowledge` skill, research and consolidate as their own sibling skills in this pack. Complements the platform `open-knowledge` skill; does not replace it."
 compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."
 metadata:
   pack: "knowledge-base"
@@ -12,7 +11,7 @@ metadata:
 
 This project uses the **source-grounded knowledge-base** layout. The whole point is a closed evidence loop: nothing canonical exists without a traceable chain back to a preserved source. This skill holds the workflow so the templates and `log.md` can stay clean — when you create a doc from a template you get structure, and the *how* lives here.
 
-> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/grounding rules) still governs every markdown operation — this layers the KB workflow on top.
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the KB workflow on top.
 
 ## Link at creation
 
@@ -28,22 +27,40 @@ research/           provisional analysis            (produced by `research`)
 articles/           canonical, decided knowledge     (produced by `consolidate`)
 ```
 
-The loop is **ingest → research → consolidate** — each a `workflow({ kind })` guide you invoke (`workflow({ kind: 'ingest' })`, etc.). Every downstream claim traces upstream to a preserved source. Cite local paths in `external-sources/`, never bare web URLs — the KB must survive link rot.
+The loop is **ingest → research → consolidate**, mapped to [Karpathy's three-layer knowledge-base pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Every downstream claim traces upstream to a preserved source. Cite local paths in `external-sources/`, never bare web URLs — the KB must survive link rot.
+
+Karpathy's insight: "The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping." Humans abandon wikis because maintenance costs exceed perceived value. These procedures exist so an agent can do the bookkeeping (fetching, summarizing, cross-linking, superseding) without fatigue. Skipping the cross-linking, supersedes chains, or raw-source preservation is what turns a useful wiki back into an abandoned one.
+
+## The three procedures
+
+Each layer has a full, STOP-gated procedure, and each ships as its own skill so it loads only when the work calls for it. Execute the procedure yourself with the OK verbs — these are your **default move over a bare `write`** when the work fits a layer.
+
+| Procedure | Where it lives | When |
+| --- | --- | --- |
+| ingest | Platform `open-knowledge` skill (`references/ingest-and-sources.md`) — its Grounding rule depends on it everywhere, so it ships with every project, not just this pack. | Preserve a shared URL / PDF / file verbatim, OR you fetched a URL to ground a KB claim (binary sources preserved, not scraped). |
+| research | Sibling skill `open-knowledge-pack-knowledge-base-research` | Investigate / compare / synthesize multiple sources → `status: provisional` article + `sources:`. |
+| consolidate | Sibling skill `open-knowledge-pack-knowledge-base-consolidate` | A decision was actually made → commit canonical source-of-truth with a `supersedes:` chain. |
+
+Typical day-2 flow: user shares a URL → **ingest** (preserve) → user asks "now research this" → **research** (provisional article, ingesting more sources as needed) → decision lands → **consolidate** (canonical article, supersedes the research).
+
+**Don't chain silently.** After ingest, ask whether to proceed to research. After research, let the user decide whether the findings are ready to consolidate. Each procedure completes on its own terms — the user drives the transitions.
+
+**Autonomy gates vs session-level autonomy.** A procedure's STOP gates (research's scoping gate, consolidate's decision-confirmation gate) are NOT overridden by session-level "work without stopping for clarifying questions" hints. Those hints cover trivial back-and-forth ("which file did you mean?"); the gates exist for one-way-door decisions. When in doubt, the gate is authoritative.
 
 ## Per-folder rules
 
-**`external-sources/`** — Raw sources saved verbatim, not just cited: the actual fetched text of URLs, extracted text of PDFs, copies of referenced files. Each file's frontmatter carries the original URL, access date, and any author/publisher metadata. Produced by `ingest` (applies whether the user shared the URL or you fetched it yourself to ground a claim). Immutable after capture — update only to refresh a stale fetch. **No analysis here**; that belongs in `research/`.
+**`external-sources/`** — Raw sources saved verbatim, not just cited: the actual fetched text of URLs, extracted text of PDFs, copies of referenced files. Each file's frontmatter carries the original URL, access date, and any author/publisher metadata. Produced by the ingest procedure (applies whether the user shared the URL or you fetched it yourself to ground a claim). Immutable after capture — update only to refresh a stale fetch. **No analysis here**; that belongs in `research/`.
 
-**`research/`** — Provisional analysis synthesizing external sources. Produced by `research`. Every factual claim cites a specific doc in `external-sources/` (or an inline URL if ingest was skipped); no unsourced assertions. Keep the `sources:` frontmatter list aligned with the docs actually linked in the body. Promote to `articles/` via `consolidate` once the team decides the findings are stable.
+**`research/`** — Provisional analysis synthesizing external sources. Produced by the `research` skill. Every factual claim cites a specific doc in `external-sources/` (or an inline URL if ingest was skipped); no unsourced assertions. Keep the `sources:` frontmatter list aligned with the docs actually linked in the body. Promote to `articles/` via the `consolidate` skill once the team decides the findings are stable.
 
-**`articles/`** — Canonical knowledge, committed after a team decision. Produced by `consolidate`. Carries a `supersedes:` chain tying back to the `research/` docs it replaces (which in turn cite `external-sources/`) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.
+**`articles/`** — Canonical knowledge, committed after a team decision. Produced by the `consolidate` skill. Carries a `supersedes:` chain tying back to the `research/` docs it replaces (which in turn cite `external-sources/`) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.
 
 ## Status flow
 
 | Layer | `status` | Set when |
 |---|---|---|
 | `research/` | `provisional` | created |
-| `articles/` | `canonical` | promoted by `consolidate` after a decision |
+| `articles/` | `canonical` | promoted by consolidate after a decision |
 
 When a new article supersedes an older one, add the older article's path to the new one's `supersedes:` list.
 
@@ -51,7 +68,7 @@ When a new article supersedes an older one, add the older article's path to the
 
 There is a `log.md` at the project root. **Append one dated entry after any turn that creates, edits, or restructures content** — one entry per turn, not per file. Silent edits break the audit trail.
 
-Log: `ingest` runs (new sources), `research` / `consolidate` runs (provisional or canonical articles), direct `write` / `edit` / `move` / `delete` outside the three loop tools, `discover` runs, folder restructures, and `.ok/config.yml` changes.
+Log: `ingest` runs (new sources), `research` / `consolidate` runs (provisional or canonical articles), direct `write` / `edit` / `move` / `delete` outside the three procedures, project-onboarding runs, folder restructures, and `.ok/config.yml` changes.
 
 **Reference docs as markdown links, not bare paths** — `[path/to/doc](./path/to/doc.md)`, so the entry shows up in `links({ kind: "backlinks" })` for those docs. A bare path string does not register in the graph.
 

package/dist/assets/skills/packs/knowledge-base/consolidate/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: open-knowledge-pack-knowledge-base-consolidate
+description: "Promote existing research into a canonical article under `articles/` in a Knowledge Base project (the `knowledge-base` starter pack). Read when a decision has actually been made and the team wants the source-of-truth written down, or when asked to consolidate, canonicalize, promote research, or supersede an older article. Carries the decision-confirmation gate, the `supersedes:` chain that keeps the evidence trail intact, and the canonical voice. Does not conduct new research — that is the sibling `research` skill."
+compatibility: "Claude Code, Claude Desktop, Claude Cowork, Claude.ai web. Requires OpenKnowledge MCP server. Installed project-local by `ok seed --pack knowledge-base`."
+metadata:
+  pack: "knowledge-base"
+  author: "Inkeep"
+  repository: "https://github.com/inkeep/open-knowledge"
+---
+# Consolidate — promote research into a canonical article
+
+> This skill is pack guidance. The platform `open-knowledge` skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the procedure on top.
+
+Promote existing research on a topic into a canonical article under `articles/`. **Canonical, not provisional** — the output is the source of truth for future agents, not a snapshot of uncertainty.
+
+The content directory is the resolved `content.dir` — read it with `config({ key: 'content.dir' })` if you don't already know it. Paths below are relative to it.
+
+## STOP gate: has a decision actually been made?
+
+Consolidation is **promotion, not creation**. If the team hasn't decided, the resulting "canonical" article lies about the team's state of understanding — future agents read it, act on it, and the false certainty compounds.
+
+Before any write, confirm out loud with the user:
+
+- **What is the actual decision?** (e.g., "We chose Yjs for CRDT" — not "Yjs is one option")
+- **What alternatives were considered and rejected?** (these go in "Alternatives considered," not as equals)
+- **What's the rationale the team used?** (not your reconstruction from sources)
+
+If the decision is still open, **do not consolidate**. Tell the user: "The research is still provisional. When the team decides, come back and consolidate with the outcome." Then stop.
+
+## When to use this procedure
+
+- A team has made a decision after research and wants the outcome committed as canonical knowledge
+- You want to compact several provisional research notes into one authoritative article
+- A developer asks to "consolidate" or "finalize" the knowledge on a topic
+
+Do NOT consolidate when:
+- The team has not actually decided (the output would be misleading — keep it as research)
+- You have not read the underlying sources (the output would lack evidence)
+
+## Principle: canonical, not provisional
+
+A consolidated article is the **source of truth**. Agents reading it should not need to dig further for context — it should stand on its own. That means:
+
+- Clear, direct statements (no "tentative", no "initial findings")
+- Decisions stated as decisions, not options
+- Rationale explained so future readers understand the why
+- Trade-offs acknowledged but framed against the chosen path, not as a menu
+- Evidence linked but not the whole story — this article is the destination, not a trail
+
+## Steps
+
+### 1. Load the research + sources
+
+Locate research articles on this topic:
+
+- Use `exec("grep -rn <topic-keyword> <content-dir>")` to find prior research, or `exec("ls -A research")` if the project groups research in a known location
+- Read each research article fully via `exec("cat <path>")` (rich enrichment gives frontmatter + shadow-repo activity + project git history + backlinks)
+- Follow its `sources:` frontmatter list — read every referenced source file
+- Also read any existing canonical article on the topic — if one already exists, you may be **updating** it rather than creating a new one
+
+If there is no research to consolidate, stop. Consolidation is promotion, not creation. Do the `research` skill first.
+
+### 2. Re-confirm the decision
+
+You already confirmed the decision at the STOP gate at the top. This step is a brief re-check after loading the research in Step 1 — occasionally the research surfaces something that makes the "decision" look less decided than the user initially claimed (an un-rebutted open question, an alternative they forgot about). If the loaded research reveals that, pause and re-confirm with the user before writing.
+
+### 3. Write the canonical article
+
+**Persist as you go (MUST).** For a large consolidation drawing on several research docs, create the article skeleton — frontmatter + the headings below — first, then `edit` each section in as you finish it; don't hold the whole synthesis in context for one final write. A rate limit or crash mid-synthesis then costs you one section, not the entire article. (The platform skill's Writing section carries this rule for all long-running work: the knowledge base is your checkpoint.)
+
+Save inside the content directory. Path convention depends on the project:
+
+- If the project uses the three-layer lifecycle (`external-sources/` → `research/` → `articles/`), save under `articles/`, grouped by topic subfolder when the area is broad (e.g., `articles/editor/crdt-architecture.md`)
+- If the project has an existing canonical-docs layout (`docs/`, `guides/`, etc.), save there in a location that matches the project's conventions
+- Ask the user when the canonical location is ambiguous
+
+Frontmatter:
+
+```yaml
+---
+title: Descriptive title
+description: One-line summary of what this article covers
+status: canonical
+date: YYYY-MM-DD
+tags:
+  - topic-tag
+supersedes:
+  - <path-to-research-article>.md
+---
+```
+
+Structure:
+
+```markdown
+## Summary
+
+[One paragraph: what the decision is and why. A reader who reads only this paragraph should know the outcome.]
+
+## Context
+
+[What problem does this solve? What constraints shaped the decision?]
+
+## Decision
+
+[The chosen approach, stated directly. Not "we recommend" — "we chose".]
+
+## Rationale
+
+[Why this path over alternatives. Grounded in the constraints from Context.]
+
+## Trade-offs
+
+[What we gave up by choosing this path. Frame against the chosen decision, not as a menu.]
+
+## Alternatives considered
+
+[Briefly: what else was on the table, why it was rejected. Link to the research article for deeper analysis.]
+
+## Implementation notes
+
+[How this gets realized in the codebase — key files, patterns, gotchas.]
+
+## Further reading
+
+[Links to research articles and external sources for readers who want the trail.]
+```
+
+### 4. Link aggressively
+
+Canonical articles are destinations — they should be **linked heavily from everywhere they're relevant** and link **out to every related page** themselves. Underlinked canonical articles lose most of their value.
+
+- **Inside this article:** every noun-phrase that names another document (other canonical articles, related research, external-source pages, sibling topics) should be a standard markdown link, not plain prose.
+- **Every link must resolve.** Only link to docs that exist. If you mention a concept that *should* have its own page but doesn't yet, do NOT emit a broken link — either create that page in this pass, or record it as a tracked task (your host's task tool; if the host has none, tell the user) and leave the mention as plain prose. A broken link is debt, not a to-do marker.
+- **Update neighbors.** After writing, find 2-3 closely-related existing pages (via `exec("grep -rn <topic> <content-dir>")`) and add a link to the new article from each — usually under a "See also" section or inline where the new article is relevant. This makes the article discoverable via backlinks, not just by remembering the path.
+- **Link to the sources and superseded research** from "Further reading" — readers who want the trail can follow.
+
+### 5. Supersede the research
+
+Add a `supersedes:` list in the new article's frontmatter pointing at the research article(s) it consolidates. This creates an audit trail.
+
+Do NOT delete the research articles — they remain as historical context for how the decision was reached. Edit their frontmatter to add:
+
+```yaml
+superseded_by: <path-to-new-canonical-article>.md
+```
+
+### 6. Verify
+
+- File exists at the chosen path under the content directory
+- Has `status: canonical` frontmatter
+- Lists the research articles it supersedes
+- Research articles updated with `superseded_by` pointer
+- `exec("ls -A <target-dir>")` shows the new file
+
+## Non-goals
+
+- **Don't consolidate research that hasn't reached a decision** — the article would misrepresent the team's actual state of understanding
+- **Don't delete research articles** — they are the trail; keep them with a `superseded_by` marker
+- **Don't rewrite research prose verbatim** — canonical articles have a different voice (direct, decided) than research (exploratory, provisional)
+- **Don't skip the supersedes / superseded_by links** — the audit trail matters for future readers