@msareen/knowledge-hub-builder 0.1.3

package/scripts/visualize.ts

@@ -0,0 +1,104 @@
+// khb visualize — scan bundles + refs + concept links, serve an interactive graph from a
+// local server. Two zoom levels: bundles (outer graph, refs.md edges) and, click a bundle,
+// its concepts (inner graph, markdown-link edges) with a panel to view a concept's body.
+// Unpinned, it picks a random free port (and retries on another if that one's taken)
+// rather than fighting over one fixed number; it also exits on its own once the browser
+// tab goes away, since a background `khb visualize` nobody's looking at is just a stray
+// process. `--port N` pins a specific port.
+import { buildGraphData, readConceptFile } from "./lib/graph";
+import { renderGraphPage } from "./lib/graph-page";
+
+const argv = process.argv.slice(2);
+// port 0 asks the OS for any free port — no fixed default to collide with something else
+// already running on the machine. Both `--port N` and `--port=N` pin it, since the docs
+// have always shown the spaced form.
+const eqArg = argv.find((a) => a.startsWith("--port="));
+const spacedArg = argv[argv.indexOf("--port") + 1];
+const requestedPort = eqArg
+  ? Number(eqArg.slice("--port=".length))
+  : argv.includes("--port") && spacedArg
+    ? Number(spacedArg)
+    : 0;
+const noOpen = argv.includes("--no-open");
+
+function summarize(data: ReturnType<typeof buildGraphData>) {
+  const concepts = Object.values(data.bundleGraphs).reduce((n, g) => n + g.concepts.length, 0);
+  const links = Object.values(data.bundleGraphs).reduce((n, g) => n + g.edges.length, 0);
+  return `${data.bundles.length} bundles, ${data.bundleEdges.length} refs, ${concepts} concepts, ${links} concept links`;
+}
+
+let data = buildGraphData();
+
+// The page pings /api/heartbeat every few seconds and beacons /api/close on unload.
+// Nothing marks the server "connected" until the first heartbeat, so a slow first
+// page-load never races the idle timeout below.
+let connected = false;
+let lastHeartbeat = Date.now();
+const IDLE_TIMEOUT_MS = 10_000;
+const HEARTBEAT_INTERVAL_MS = 3_000;
+
+const fetchHandler = (req: Request) => {
+  const url = new URL(req.url);
+  if (url.pathname === "/")
+    return new Response(renderGraphPage(data), { headers: { "content-type": "text/html; charset=utf-8" } });
+  if (url.pathname === "/api/graph") {
+    if (url.searchParams.get("rebuild")) data = buildGraphData();
+    return Response.json(data);
+  }
+  if (url.pathname === "/api/file") {
+    const bundle = url.searchParams.get("bundle") ?? "";
+    const path = url.searchParams.get("path") ?? "";
+    const body = readConceptFile(bundle, path);
+    return body === undefined
+      ? new Response("not found", { status: 404 })
+      : new Response(body, { headers: { "content-type": "text/plain; charset=utf-8" } });
+  }
+  if (url.pathname === "/api/heartbeat") {
+    connected = true;
+    lastHeartbeat = Date.now();
+    return new Response("ok");
+  }
+  if (url.pathname === "/api/close" && req.method === "POST") {
+    console.log("khb visualize — browser closed, shutting down.");
+    setTimeout(() => process.exit(0), 50); // let the response flush first
+    return new Response("ok");
+  }
+  return new Response("not found", { status: 404 });
+};
+
+let server;
+try {
+  server = Bun.serve({ port: requestedPort, fetch: fetchHandler });
+} catch (e) {
+  if (requestedPort && (e as { code?: string }).code === "EADDRINUSE") {
+    console.warn(`Port ${requestedPort} is busy — picking a free one instead.`);
+    server = Bun.serve({ port: 0, fetch: fetchHandler });
+  } else throw e;
+}
+
+setInterval(() => {
+  if (connected && Date.now() - lastHeartbeat > IDLE_TIMEOUT_MS) {
+    console.log("khb visualize — browser tab gone, shutting down.");
+    process.exit(0);
+  }
+}, HEARTBEAT_INTERVAL_MS).unref();
+
+const url = `http://localhost:${server.port}`;
+console.log(`khb visualize → ${url}  (${summarize(data)})`);
+
+// Open the default browser. If that fails the URL is already printed above, so a headless
+// or locked-down box just falls back to copy-paste rather than erroring out.
+if (!noOpen) {
+  const cmd =
+    process.platform === "win32"
+      ? ["cmd", "/c", "start", "", url]
+      : process.platform === "darwin"
+        ? ["open", url]
+        : ["xdg-open", url];
+  try {
+    Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" }).unref();
+  } catch {
+    console.warn("Could not launch a browser — open the URL above yourself.");
+  }
+}
+console.log(`The server exits on its own once you close the tab. Ctrl+C also works.`);

package/skills/catalog/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: catalog
+description: Turn one bundle's raw/ material into OKF concept docs — read each raw file, split it into sub-topics, label each with type/title/description/tags, link them, and register them in index.md. Uses parallel subagents when the runtime supports them. Use after khb ingest, or when the user asks to curate, catalog, organize, or write up a bundle.
+---
+
+# Catalog a bundle
+
+The second half of the pipeline: `khb ingest` produced faithful text in `raw/`; catalog
+turns that text into **knowledge**. One bundle at a time, always.
+
+The unit of output is the **concept** — one idea, one markdown file, OKF frontmatter,
+registered in an index. A raw file is not a concept. A 40-page contract is a dozen concepts;
+three meeting transcripts about the same decision are one. Splitting and merging is the
+whole job, and it is why this pass needs a model and `khb ingest` does not.
+
+`khb` has no `catalog` command. Nothing here is mechanical enough to script.
+
+**Catalog classifies concepts and links them. It never reorganizes bundles.** The splitting
+it does is *within* a bundle — raw files into concepts, concepts into subdirectories. A
+bundle is a logical unit its owner defined (a person, a team, a project) and it holds many
+topics by design, so finding three unrelated subjects in one bundle is the expected case,
+not a problem to fix. Never create a bundle, move material to another bundle, or propose a
+split because the contents look heterogeneous. If material clearly belongs to someone else,
+it gets a `refs.md` line and stays where it is.
+
+## 1. Scope the work
+
+```
+khb ingest <bundle>          # if the user asked to catalog something not yet ingested
+```
+
+That only moves bytes for sources already declared in the bundle's `sources.yaml`; if the
+material isn't declared yet, you are at the start of the [ingest skill](../ingest/SKILL.md),
+not this one.
+
+The worklist is `bundles/<bundle>/log.md`: **every row with a `raw` path and an empty
+`curated` column.** Nothing else records what is outstanding, so work from the ledger rather
+than from a directory listing — a `raw/` file whose row is already filled has been done.
+
+Rows with an empty `raw` were never extracted; they are ingest's problem, not yours. If
+there are many, say so and offer to fix ingest first.
+
+## 2. Read the map before writing anything
+
+Open the bundle's `index.md` and any nested indexes, and list the existing concepts: path,
+`title`, `type`, `tags`. This is the **vocabulary**, and it does two jobs — it stops you
+coining `billing` when `invoices` already exists, and it is what lets a new concept link to
+an old one. Hold it in this thread; every subagent gets a copy.
+
+Also decide the **grouping** now, before any file is written: which subdirectories the new
+concepts go in (`contracts/`, `metrics/`, `notes/`, `playbooks/` — whatever fits this
+domain; structure carries no fixed meaning). Reuse existing directories wherever they fit.
+Inventing a new subdirectory per raw file is the classic failure here.
+
+## 3. Seed wave — one file, checked by hand
+
+Pick the most representative raw file and delegate it to **one subagent** with the prompt
+below. Use a fast, economical model when the runtime exposes model selection; otherwise use
+its default subagent. If subagents are unavailable, do the same work in the current thread.
+Then read what it wrote. You are checking the shape, not the facts: right granularity,
+frontmatter complete, titles that read like knowledge rather than filenames. Correct the
+prompt if it is off, and take the concept titles it produced into your vocabulary before
+going wide.
+
+## 4. Bulk wave — the rest in parallel
+
+Use one subagent per remaining raw file and start them concurrently when the runtime
+supports parallel delegation. Group several small files into one task when they are
+obviously the same subject; never split one file across two tasks. Without subagents,
+process the files sequentially in the current thread and keep the same single-writer rules.
+
+Parallel subagents cannot see each other's output, so two rules are absolute:
+
+- **Every prompt carries the vocabulary.** Otherwise you get `q3-budget`, `budget-q3` and
+  `quarterly-budget` as three concepts.
+- **Subagents write concept docs only.** `index.md`, `log.md` and `refs.md` have exactly one
+  writer — you, in step 5. Concurrent edits to a shared index silently lose rows.
+
+Prompt each subagent with, substituting the bracketed parts:
+
+> Read `bundles/<bundle>/raw/<file>.md`. It is ingested source material with a provenance
+> header naming the original file.
+>
+> Split its content into distinct **concepts** — one idea per concept. A concept is
+> something someone would ask a question about on its own. Do not summarize the document as
+> a whole, and do not create a concept per section heading.
+>
+> Write each concept as its own markdown file in `bundles/<bundle>/<group>/`, named
+> `<kebab-case-title>.md`. If that filename already exists and is about something else,
+> append `-2`. Each file starts with OKF frontmatter:
+>
+> ```yaml
+> ---
+> type: <Table | Metric | Playbook | Decision Log | Reference | Contract | …>
+> title: <display name>
+> description: <one line, under 20 words>
+> tags: [<lowercase kebab-case>]
+> timestamp: <ISO from the source if it has one, else today>
+> ---
+> ```
+>
+> Then the body: the actual knowledge, in your own words, structured with headings. End with
+> a `# Citations` section listing the raw file path and the `source:` value from its header.
+>
+> Link to related concepts with plain markdown links using bundle-root paths
+> (`/metrics/churn.md`). You may link to any of these existing concepts:
+> `<vocabulary: path — title — description, one per line>`
+> Reuse an existing concept's subject rather than restating it: if this file only adds a
+> detail to one of the above, say so in your reply instead of writing a near-duplicate.
+> Never link outside this bundle.
+>
+> If the provenance header says `quality: low`, the text came from OCR or a transcript and
+> may be garbled. Do not invent through it — quote what is legible, and flag what is not in
+> your reply.
+>
+> If the file contains nothing worth keeping (a receipt, boilerplate, a duplicate), write
+> nothing and say so.
+>
+> Reply with one line per concept you wrote: `<path> | <title> | <description>`, then any
+> flags. Do not edit `index.md`, `log.md` or `refs.md`.
+
+## 5. Merge — you, single writer
+
+Everything in this step happens in this thread, sequentially, because every file it touches
+is shared.
+
+1. **Review and dedupe.** Read the concepts the wave produced. Two files covering the same
+   idea get merged into the better one and the loser deleted. A concept that only restates
+   an existing one gets folded into it instead.
+2. **Cross-link.** Subagents could link to pre-existing concepts but not to each other's
+   output. Add the sibling links now — that is where most of a bundle's value ends up.
+3. **Register every concept in `index.md`**, in the OKF form
+   `* [Title](path.md) - description`. **An unindexed concept is invisible to every query**
+   and lint will flag it. Add a nested `index.md` if a subdirectory grew past ~10 concepts.
+4. **Fill the `curated` column in `log.md`** for every row you worked. Use the concept
+   paths, comma-separated. For a raw file you deliberately declined, write `declined` — a
+   row that stays empty will be offered as backlog forever.
+5. **Foreign material → `refs.md`.** A raw file that turns out to belong to a different
+   bundle is not curated here: note the target bundle and the reason in `refs.md` and, if
+   the user agrees, add the source to that bundle's `sources.yaml`. Never inline-link across
+   bundles, and never copy the content over.
+
+## 6. Verify
+
+```
+khb lint          # index coverage, frontmatter, ref targets, no cross-bundle links
+khb visualize     # optional: refresh visualizer/graph.html
+```
+
+Fix every error before finishing. Then report: concepts created, raw files declined, rows
+still outstanding, and anything you flagged as low-quality and worth re-reading from source.
+
+## Judgement notes
+
+- **Curate selectively.** Raw is bulk; concepts are distilled. Most corpora are 80% receipts
+  and boilerplate. Declining is a real outcome, not a failure.
+- **Granularity.** If two concepts are always read together, they are one. If one concept
+  has two `# Schema` sections, it is two.
+- **Write knowledge, not summaries.** "This document discusses the retention policy" is
+  useless; the retention policy is what belongs in the file.
+- **Never put content in an index.** Indexes route. Knowledge goes in a concept doc.
+- **`quality: low` sources** deserve a look at the original before you commit their claims —
+  the `source:` path in the raw header is exactly for this. Reading a chart or a scanned
+  table with vision recovers what OCR dropped.

package/skills/export/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: export
+description: Export a KHB bundle as a standalone shareable folder with the common patterns injected. Use when the user wants to share or ship a single bundle.
+---
+
+# Export a bundle
+
+Bundles stay lean inside the hub because the common patterns live at hub root; export
+injects those patterns so the folder works alone with any agent.
+
+1. Run `khb export <bundle> [dest]` (default dest: `export/<bundle>/`). The command
+   **refuses to write into an existing destination** — re-exporting means removing the old
+   folder first, or passing a new `dest`.
+2. The result is a miniature hub, with the bundle itself one level down:
+
+   ```
+   <dest>/bundle/            the bundle, copied whole
+   <dest>/outer.index.md     single-bundle router pointing at bundle/index.md
+   <dest>/AGENTS.md          the contract, plus CLAUDE.md
+   <dest>/skills/            the canonical protocols (query, ingest, lint, …)
+   <dest>/.claude/skills/    discovery adapters, and .agents/skills/ likewise
+   <dest>/README.md          provenance: what this is and when it was exported
+   ```
+
+3. Tell the user two things before they send it anywhere:
+   - `refs.md` entries pointing at other bundles **will not resolve** — the export is one
+     bundle, and its cross-bundle pointers now dangle.
+   - The copy is literal, so `raw/` and `log.md` go with it. `log.md` records **absolute
+     source paths** from the machine that ingested them, and `raw/` is uncurated source
+     material that was never written for an outside reader. Check both before sharing
+     outside the team, and prune if they say more than intended.

package/skills/ingest/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: ingest
+description: Acquire external material (folders, files, web pages, Confluence, ADO, git) into a KHB bundle's raw/ folder as markdown with provenance — one flat mechanical phase, no interpretation. Use when the user wants to add, import, dump, pull, or refresh source data in the knowledge base.
+---
+
+# Ingest into KHB
+
+**Ingest gets bytes into `bundles/<bundle>/raw/` as markdown with a provenance header.
+That is all it does.** It is one flat phase, it is mechanical, and it ends the moment the
+text exists. Deciding what the text *means* — splitting it into concepts, titling,
+tagging, linking, indexing — is the [catalog skill](../catalog/SKILL.md), a separate step
+you run afterwards.
+
+Do not curate here. Do not create, split, or merge bundles here — routing material to a
+bundle that exists is fine, reshaping the hub is not. If you find yourself reading a document
+to understand it, you have left this skill.
+
+## 1. Declare the sources
+
+Ingest is bundle-first: material lands in one bundle, and you say where it comes from. Edit
+`bundles/<bundle>/sources.yaml`:
+
+```yaml
+sources:
+  - type: folder          # walk a directory tree
+    path: /abs/path/to/project-x
+  - type: files           # a scattered, explicitly named set
+    paths:
+      - /abs/path/to/one.pdf
+      - /abs/path/to/two.xlsx
+  - type: web
+    urls:
+      - https://example.com/design-doc
+  # Types with no scripted ingester are still declared here, for the record —
+  # you pull them yourself in step 3.
+  - type: confluence
+    space: PROJX
+```
+
+If the user has not explicitly named the source locations, inspect the bundle's current
+`sources.yaml`, then ask which files, folders, URLs, or services to ingest. Include any
+existing declarations in the question so the user can confirm or replace them. Do not
+infer sources from nearby files, edit `sources.yaml`, or run `khb ingest` until the user
+answers.
+
+Nothing is copied by declaring a source.
+
+**Which bundle — take the first of these that applies, and do not go further:**
+
+1. **The user named a bundle** → use it. A named bundle that does not exist is an error,
+   not an invitation to create one.
+2. **The hub has bundles and exactly one plainly owns the material** → use it, and say
+   which you picked. If several could own it, ask which — this is the only bundle question
+   ingest ever asks.
+3. **Anything else** — no bundle named, or the hub has no bundles at all → `default`,
+   created on the spot, without asking.
+
+Never ask the user to name or create a bundle *for the ingest to land in*. `default` exists
+so that question never has to be asked at this stage: bytes always have somewhere to go, and
+which bundle owns them is a cheaper decision later, once the text exists and the user can see
+what they actually have.
+
+**The `default` bundle.** When no bundle is named, ingest targets `default` and creates it
+if the hub has none — a first `khb ingest` never fails for want of a destination. It is not a
+way around step 2: when a bundle in the hub plainly owns the material, that bundle wins. What
+lands there is ordinary bundle content: catalog it like any other. Do **not** graduate it into new
+bundles on your own — a bundle is a logical unit the user defines (a person, a team, a
+project), so material leaves `default` only when the user says which bundle owns it. An
+explicitly named bundle that doesn't exist is still an error — only `default` is conjured.
+
+## 2. Run it
+
+```
+khb ingest                          # no bundle named → the 'default' bundle
+khb ingest <bundle>                 # incremental: unchanged content hashes are skipped
+khb ingest <bundle> --force         # re-acquire everything
+khb ingest <bundle> --skip-ocr      # leave scans and images unread
+khb ingest <bundle> --skip-audio    # leave audio/video untranscribed
+```
+
+One command handles every scripted source in `sources.yaml` and extracts everything it can,
+locally. Read the summary it prints — the counts are the state of the world:
+
+| line | meaning |
+|---|---|
+| `unchanged, skipped` | already acquired at this exact content hash |
+| `extracted` / `reused from the extraction cache` | converted now / converted by an earlier run or another bundle |
+| `read by OCR` / `transcribed` | lossy routes — see quality, below |
+| `marked quality: low` | verify these against the source when cataloging |
+| `not extracted` | got a ledger row with an empty `raw`; the per-file line says why |
+
+Above that summary, every file gets its own trace — announced *before* the work starts, so a
+run that is taking minutes always names the file it is taking them on:
+
+```
+[ 7/94] D:\corpus\board-pack.pdf
+        extracting pdf …
+        no text layer, 12p — scanned, running OCR (seconds per page)
+          page 1/12 — 1843 chars
+          …
+        extracted → raw/folder/board-pack.pdf.md  [tesseract.js @ 216dpi, quality: low] (48.1s)
+```
+
+There is no quiet mode, and this is deliberate: the trace is the audit trail for a pass that
+rewrites `raw/`. When something looks wrong later, that line — tool, quality, elapsed — is
+what tells you which file to distrust and which extractor to blame.
+
+### What khb extracts
+
+All of it runs locally and none of it contacts a model — that is the `AGENTS.md` division of
+labor. khb converts bytes to text as cheaply as possible; your judgement is spent on
+curation, not transcription.
+
+| Format | Tool | Quality |
+|---|---|---|
+| `.md .txt .rst .adoc .html .csv .json .yaml` | copied verbatim | high |
+| `.pdf` (born-digital) | `unpdf`, then `pdftotext` if on PATH | high |
+| `.docx` / `.odt` / `.pptx` | `mammoth` / `fflate` / `fflate`, `pandoc` if on PATH | high |
+| `.xlsx` | `fflate` → one markdown table per sheet | high |
+| `.pdf` (scanned, no text layer) | `pdfium` + `tesseract.js`, automatically | **low** |
+| `.png .jpg .webp .tif .gif` | `tesseract.js`, automatically | **low** |
+| `.mp3 .wav .m4a .mp4 .mov .mkv` | local `whisper` / `faster-whisper` | **low** |
+
+Extracted text is cached hub-wide by content hash at `inbox/extracted/<sha256>.md`, so the
+same file appearing in two bundles converts once.
+
+OCR and transcription need optional dependencies. When they are missing khb says so once and
+records the affected files as pending rather than failing the run:
+
+```
+bun add @hyzyla/pdfium sharp tesseract.js    # OCR — ~75 MB WASM, no system binary
+pip install -U openai-whisper                # transcription (faster-whisper also works)
+```
+
+Install them where `khb` resolves modules from — for a global install that is the khb
+package directory, not your hub. khb prints the exact `cd … && bun add …` to use.
+
+## 3. Sources khb cannot reach
+
+Anything behind an authenticated API has no scripted ingester, because maintaining API
+wrappers is not what this tool is for. Pull those yourself with the site's MCP server or
+official CLI, and write the result into `raw/<type>/` **in exactly the format khb
+produces** — same folder shape, same header — so the catalog pass cannot tell the
+difference:
+
+| Source | How |
+|---|---|
+| Confluence | MCP server or `confluence` CLI → `raw/confluence/<page>.md` |
+| Azure DevOps | MCP/CLI → wiki pages, work items → `raw/ado/<item>.md` |
+| GitHub / GitLab issues, PRs, wikis | `gh` / `glab` CLI → `raw/git/<thing>.md` |
+| Source code repository | do **not** copy — record the location in `sources.yaml` and read it in place |
+| A diagram or chart no OCR can read | vision read the image → `raw/images/<file>.md`, `extract_tool: claude-vision` |
+
+Then add the row to `log.md` yourself (`source`, `sha256` if you have it, `fetched`, `raw`),
+so the ledger stays the complete record regardless of who did the fetching.
+
+### The provenance header — the contract
+
+Every file in `raw/` starts with it. This is the reason ingest is a separate phase from
+catalog: extraction is sometimes lossy, and curation must always be able to walk back to the
+original bytes.
+
+```yaml
+---
+source: /abs/path/to/original.pdf     # or the url, or the tool query
+fetched: 2026-07-23T09:14:02Z
+sha256: db2ee470c95d
+extract_tool: tesseract.js            # what produced the text below
+quality: low                          # high = real text; low = OCR or a transcript
+---
+```
+
+`quality: low` is a standing invitation to distrust the body. When cataloging one of these
+and the text reads thin, garbled, or contradictory, **open the `source:` file and read it
+directly** — a vision pass over a chart or a scanned table recovers what OCR drops. Rewrite
+the `raw/` file with `extract_tool: claude-vision` and `quality: high` when you do.
+
+## 4. The ledger — `log.md`
+
+Every bundle keeps its ingest ledger in `log.md` (OKF-reserved, so it is never mistaken for
+a concept doc, and committed, so it survives `raw/` being deleted and re-derived).
+
+| column | owner | meaning |
+|---|---|---|
+| `source` | khb | origin URI: absolute path, url, or tool query |
+| `sha256` | khb | content hash (12-char prefix) — drives skip-unchanged, move detection and dedup |
+| `fetched` | khb | ISO timestamp of last acquisition |
+| `raw` | khb | bundle-relative `raw/` path; **empty = never extracted** |
+| `curated` | agent | concept doc(s) distilled from it; **empty = catalog backlog** |
+
+`khb ingest` maintains the first four and never touches `curated`.
+
+### Moved and renamed sources
+
+The bytes are a source's identity; the path is only where they live today. When a file
+appears at a path the ledger has not seen, khb looks for an existing row with the same hash
+whose own path has since disappeared. If exactly one matches, that row is **re-pointed** at
+the new path: same `raw` file (concepts cite it by name, so it is never renamed), same
+`curated`, and the raw file's `source:` provenance header is corrected. Nothing is
+re-extracted and nothing re-enters the backlog.
+
+Two cases are deliberately *not* treated as moves, because both would silently rewire
+provenance:
+
+- **Copy** — the twin row's path still exists, so these are two real sources with the same
+  bytes. Both are ingested; the run says so, and folding or declining the second is a
+  cataloging judgement.
+- **Ambiguous** — several vanished rows share the hash, so which one moved here is
+  unknowable. The new file is ingested as its own source and the run says why.
+
+Still on you, not khb: a source **modified in place** keeps its `curated` value, so the
+concept derived from it does not re-enter the backlog even though its material changed.
+Watch for `raw/` files whose content shifted and re-catalog them deliberately.
+
+## Hand off
+
+Ingest is done when the summary shows nothing unexpectedly pending. Report to the user what
+landed, what didn't and why, and how many rows are uncurated — then continue with the
+[catalog skill](../catalog/SKILL.md) to turn `raw/` into concept docs.
+
+## Hygiene
+
+- `raw/` is gitignored, derived, and **never canonical**. Never cite it in an answer.
+- Never copy a bulk corpus into a bundle wholesale. Extraction shrinks documents to text;
+  source-code repos and media libraries stay where they are and get a `sources.yaml` entry.
+- The same file in two bundles: one bundle owns it, the other gets a `refs.md` entry. Never
+  two copies. The content hash in `log.md` is how you spot it.
+- `log.md` records absolute source paths. If those paths are themselves sensitive, gitignore
+  it before the first commit.

package/skills/lint/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: lint
+description: Validate KHB structure (routing integrity, bundle shape, OKF conformance). Use after any structural edit, or when the user asks to check/validate/fix the knowledge base.
+---
+
+# Lint KHB
+
+1. Run `khb lint` from anywhere inside the hub — it walks up to `khb.json` to find the root.
+2. Fix every ERROR (structure, routing, OKF frontmatter); judge warnings case by case
+   (broken index links may be intentional not-yet-written knowledge).
+3. Re-run until 0 errors. If a fix changes root files **and the hub has a `meta` bundle**,
+   log it in `bundles/meta/notes/decisions.md`. No meta bundle means no decision log — do
+   not create one to have somewhere to write.
+
+## The rules (L1–L9)
+
+Enforced by `khb lint`. Combines KHB routing rules with
+OKF v0.1 conformance (see the OKF spec). Reserved filenames: `index.md`, `log.md`
+(OKF) and `refs.md` (KHB). Every other `.md` in a bundle — outside `raw/` —
+is a **concept document**.
+
+### Bundle shape
+
+- L1. Every `bundles/<name>/` has: `index.md`, `refs.md`, `sources.yaml`. Concept docs
+  live in whatever subdirectory grouping fits the domain. No per-bundle AGENTS.md —
+  root `AGENTS.md` is the common contract; `khb export` injects it for standalone
+  sharing.
+- L2. Bundle names: lowercase, digits, hyphens (`^[a-z0-9][a-z0-9-]*$`).
+
+### Routing integrity
+
+- L3. Every bundle is listed in `outer.index.md`; every bundle linked from
+  `outer.index.md` exists on disk.
+- L4. Every concept doc is listed in at least one of the bundle's `index.md` files
+  (error). Index links pointing at missing files are a warning only — OKF treats
+  broken links as not-yet-written knowledge.
+- L5. Index files contain routing only: headings, bullet/table link lines, one-line
+  descriptions. Paragraph-length prose is a violation (warning).
+
+### Independence
+
+- L6. No markdown link from a concept doc into another bundle's files. Cross-bundle
+  pointers live in `refs.md` only.
+- L7. Every target bundle named in `refs.md` exists.
+
+### Provenance
+
+- L8. Files under `raw/` carry a provenance header (warning): frontmatter present, a
+  non-empty `source:`, and `quality:` — if set — reading exactly `high` or `low`.
+  `source` is what makes a bad extraction recoverable, so a raw file without one is
+  uncatalogable, not merely untidy.
+
+### OKF conformance
+
+- L9. Concept frontmatter is the machine-readable half of a concept, so it is validated
+  as data rather than glanced at:
+  - frontmatter block present, and **parses as YAML** (error) — a malformed block means
+    every field is silently lost.
+  - non-empty `type` (error) — the one OKF v0.1 §9 requirement. Its *value* stays
+    free-form: `Metric`, `Playbook`, `Runbook`, anything the domain needs.
+  - `title` and `description` present (warning) — indexes and index generators read them.
+  - `tags`, if present, is a YAML list of strings (error). `tags: "a, b"` is a string and
+    filters as one opaque value; `tags: [a, b]` is two tags.
+  - `timestamp`, if present, parses as an ISO-8601 datetime (warning).
+  - unknown top-level keys (warning). The known set is `type`, `title`, `description`,
+    `resource`, `tags`, `timestamp` — `resource` is optional and unvalidated, but it is
+    known, so it costs no warning. OKF is permissive and extra keys are legal, but `titel:`
+    is a typo that silently drops the field, and one warning line is cheaper than a field
+    nobody notices is missing.

package/skills/new-bundle/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: new-bundle
+description: Create a new KHB bundle — a logical unit owned by a person, team, project or client. Use when the user wants to add a new owner/area to the knowledge base.
+---
+
+# New bundle
+
+A bundle is a **logical unit, defined by whoever owns its material** — a person, a team, a
+project, a client. It is not a subject classification. One bundle holds as many topics as
+its owner has; topics are organized *inside* it with subdirectories, not by making more
+bundles.
+
+Creating a bundle is always a human decision. Never create one because material looks like
+it belongs to a new subject, and never split an existing one on your own initiative — an
+agent splits a bundle only when explicitly told to.
+
+1. Pick a name: lowercase, digits, hyphens. Name the owner or the context, not the subject
+   (`team-payments`, `client-acme`, `notes`), and expect its scope line to list several
+   topics — that is correct, not a signal to split.
+2. Run `khb new-bundle <name> "<one-line scope>"` — scaffolds from
+   `.bundle_template/` and registers in `outer.index.md`.
+3. Fill in the "Route here when" column in `outer.index.md`. Write it as a trigger for
+   *whose* material this is, since one bundle answers for many topics.
+4. Declare inputs in `sources.yaml` (see the ingest skill to pull them).
+5. `khb lint`.