@msareen/knowledge-hub-builder 0.1.3

package/.agents/skills/catalog/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: catalog
+description: Curate one KHB bundle's raw material into linked OKF concept documents. Use after ingest or when asked to catalog or organize a bundle.
+---
+
+Read and follow the [canonical workflow](../../../skills/catalog/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.agents/skills/export/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: export
+description: Export a KHB bundle as a standalone shareable folder. Use when asked to share or ship one bundle.
+---
+
+Read and follow the [canonical workflow](../../../skills/export/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.agents/skills/ingest/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: ingest
+description: Acquire external material into a KHB bundle as provenance-bearing markdown. Use when asked to add, import, pull, or refresh source data.
+---
+
+Read and follow the [canonical workflow](../../../skills/ingest/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.agents/skills/lint/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: lint
+description: Validate and repair KHB structure and OKF conformance. Use after structural edits or when asked to check the knowledge base.
+---
+
+Read and follow the [canonical workflow](../../../skills/lint/SKILL.md) in full; treat all
+of its instructions as part of this skill.

package/.agents/skills/new-bundle/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: new-bundle
+description: Create and register a KHB bundle. Use only when the user explicitly wants a new owner or knowledge area.
+---
+
+Read and follow the [canonical workflow](../../../skills/new-bundle/SKILL.md) in full;
+treat all of its instructions as part of this skill.

package/.agents/skills/query/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: query
+description: Answer a question from a KHB hub by routing through its indexes and concept documents. Use for knowledge-base lookups.
+---
+
+Read and follow the [canonical workflow](../../../skills/query/SKILL.md) in full; treat all
+of its instructions as part of this skill.

package/.agents/skills/visualize/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: visualize
+description: Regenerate the KHB bundle graph. Use when asked to visualize the hub or after bundle references change.
+---
+
+Read and follow the [canonical workflow](../../../skills/visualize/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.bundle_template/index.md

@@ -0,0 +1,9 @@
+---
+okf_version: '0.1'
+---
+
+# {{name}}
+
+<!-- OKF index: progressive disclosure. List every concept doc / subdirectory as:
+* [Title](path.md) - one-line description (from the doc's frontmatter)
+Organize concepts in whatever subdirectories fit the domain. -->

package/.bundle_template/log.md

@@ -0,0 +1,10 @@
+# {{name}} — ingest log
+
+Ingestion ledger, one row per source. `khb ingest` maintains `source`, `sha256`,
+`fetched` and `raw`; the agent fills `curated` while cataloging (skills/catalog/SKILL.md).
+
+Empty `raw` = seen but not extracted (protected, unreadable, or skipped by a flag).
+Empty `curated` = in raw/ but not yet distilled into a concept doc.
+
+| source | sha256 | fetched | raw | curated |
+|---|---|---|---|---|

package/.bundle_template/raw/.gitkeep

@@ -0,0 +1,15 @@
+# raw/ — ingested source material, NOT canonical.
+#
+# Phase 1 of skills/ingest/SKILL.md drops faithful copies here, one subdirectory per source
+# type: raw/folder/, raw/web/, raw/confluence/, raw/ado/, raw/pdf/ ...
+# Every .md file starts with a provenance header (lint L8):
+#
+#   ---
+#   source: <url | path | tool query>
+#   fetched: <ISO timestamp>
+#   ---
+#
+# Re-acquiring overwrites this tree idempotently. It is gitignored
+# (bundles/*/raw/) and never cited in answers — curate into concept docs and
+# cite those instead. This file only keeps the directory present in the
+# template; delete it once the bundle has real raw content.

package/.bundle_template/refs.md

@@ -0,0 +1,6 @@
+# {{name}} — refs
+
+Cross-bundle references. The only way out of this bundle.
+
+| Bundle | Why | Note (optional) |
+|---|---|---|

package/.bundle_template/sources.yaml

@@ -0,0 +1,13 @@
+# Ingestion sources for {{name}}.
+# folder/web: scripted — bun run ingest {{name}}
+# confluence/ado: listed as provenance; agent ingests via MCP/CLI (AGENTS.md §Ingestion)
+sources: []
+# - type: folder
+#   path: /abs/path/to/some-folder
+# - type: web
+#   urls: []
+# - type: confluence
+#   space: SPACEKEY
+# - type: ado
+#   org: myorg
+#   project: MyProject

package/.claude/skills/catalog/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: catalog
+description: Curate one KHB bundle's raw material into linked OKF concept documents. Use after ingest or when asked to catalog or organize a bundle.
+---
+
+Read and follow the [canonical workflow](../../../skills/catalog/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.claude/skills/export/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: export
+description: Export a KHB bundle as a standalone shareable folder. Use when asked to share or ship one bundle.
+---
+
+Read and follow the [canonical workflow](../../../skills/export/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.claude/skills/ingest/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: ingest
+description: Acquire external material into a KHB bundle as provenance-bearing markdown. Use when asked to add, import, pull, or refresh source data.
+---
+
+Read and follow the [canonical workflow](../../../skills/ingest/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/.claude/skills/lint/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: lint
+description: Validate and repair KHB structure and OKF conformance. Use after structural edits or when asked to check the knowledge base.
+---
+
+Read and follow the [canonical workflow](../../../skills/lint/SKILL.md) in full; treat all
+of its instructions as part of this skill.

package/.claude/skills/new-bundle/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: new-bundle
+description: Create and register a KHB bundle. Use only when the user explicitly wants a new owner or knowledge area.
+---
+
+Read and follow the [canonical workflow](../../../skills/new-bundle/SKILL.md) in full;
+treat all of its instructions as part of this skill.

package/.claude/skills/query/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: query
+description: Answer a question from a KHB hub by routing through its indexes and concept documents. Use for knowledge-base lookups.
+---
+
+Read and follow the [canonical workflow](../../../skills/query/SKILL.md) in full; treat all
+of its instructions as part of this skill.

package/.claude/skills/visualize/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: visualize
+description: Regenerate the KHB bundle graph. Use when asked to visualize the hub or after bundle references change.
+---
+
+Read and follow the [canonical workflow](../../../skills/visualize/SKILL.md) in full; treat
+all of its instructions as part of this skill.

package/AGENTS.md

@@ -0,0 +1,167 @@
+# AGENTS.md — common contract for Claude, Codex, and other agents
+
+You are inside a **KHB hub** — a bundle-of-bundles knowledge system. Full design: `SPEC.md`.
+
+The hub is this folder: `khb.json`, `outer.index.md`, and `bundles/`. The knowledge is
+here; the `khb` tooling is installed separately and holds none of it. This file and its
+siblings (`SPEC.md`, `skills/`) are package-owned copies refreshed by `khb upgrade` —
+never edit them, edit bundle content instead. Every workflow protocol lives wholly inside
+`skills/<name>/SKILL.md`: query, ingest, catalog, lint, new-bundle, export, visualize.
+Those files are plain markdown — any agent can read one directly, whether or not its
+runtime has a notion of "skills".
+
+## What a bundle is
+
+A bundle is a **logical unit defined by its owner** — a person, a team, a project, a client
+— not a subject classification. It holds as many topics as its owner has; topics are
+organized inside it with subdirectories. A bundle whose contents look heterogeneous is
+working as intended.
+
+Creating, splitting or merging bundles is a human decision, always. Never do it on your own
+initiative, in any workflow, however obviously a subject seems to want its own home. On
+explicit instruction, carve one out and move the files; otherwise leave the shape alone.
+
+## How to navigate
+
+1. Start at `outer.index.md`. Pick exactly one bundle for the question. Do not browse.
+2. If that doesn't settle it, escalate per `skills/query/SKILL.md`: grep the bundle
+   `index.md` files, then concept front matter, then **ask the user** which bundle.
+   Never guess silently.
+3. Enter the bundle via its `index.md`, then read only the concepts/notes it routes you to.
+
+This file is the single common contract — bundles carry no per-bundle agent rules.
+Claude loads it through `CLAUDE.md`; Codex loads it directly.
+
+## Hard rules
+
+- **One bundle at a time.** If a question spans two bundles, follow the collation protocol
+  in `skills/query/SKILL.md`: resolve in the first bundle, follow its `refs.md` to the
+  second, and enter the second **through its own index.md**. Never deep-link from one bundle's notes into
+  another's. Join answers in your response, not in the files.
+- **Indexes are routing only.** Never add knowledge content to `outer.index.md` or any
+  `index.md` — add a concept doc and link it from the index.
+- **Writing (OKF v0.1):** a concept = one markdown file, anywhere in the bundle except
+  reserved names (`index.md`, `log.md`, `refs.md`) and `raw/`. Group concepts in
+  subdirectories that fit the domain (`tables/`, `metrics/`, `notes/`, …). Every
+  concept doc starts with front matter — `type` is required:
+
+  ```yaml
+  ---
+  type: Metric            # free-form: Table, Playbook, Decision Log, Reference, …
+  title: Display name
+  description: One-line summary (reused by index generators)
+  resource: <canonical URI of the underlying asset, if any>
+  tags: [a, b]
+  timestamp: 2026-07-19T00:00:00Z
+  ---
+  ```
+
+  List every concept in an `index.md` (`* [Title](path.md) - description`). Link
+  concepts to each other with plain markdown links, `/path/from/bundle/root.md`
+  preferred; relationship meaning goes in the surrounding prose.
+- **Cross-bundle relationships** go in `refs.md` only — never inline links across bundles.
+- **Decisions:** if this hub has a `meta` bundle, any change to how the hub itself works
+  gets a dated line in `bundles/meta/notes/decisions.md`.
+- **`raw/` is not canonical.** It's ingested source material awaiting curation. Cite
+  concept docs; use `raw/` only when curating.
+- **New bundle:** `khb new-bundle <name>` — never hand-copy `.bundle_template`.
+- After structural edits run `khb lint` and fix what it reports.
+
+## Division of labor — khb vs agent
+
+One hard boundary governs every workflow and every future change to the tooling:
+
+- **`khb` converts bytes to text.** Hashing, caching, file plumbing, ledger-keeping, and
+  *every* local extractor: PDF/DOCX/ODT/XLSX/PPTX libraries, tesseract OCR for scans and
+  images, whisper for audio and video. All of it deterministic, offline, and free of
+  charge. It **never contacts a model** — not directly, not by shelling out.
+- **The agent decides what the text means.** Splitting a document into concepts, labeling
+  and linking them, curating `raw/` into the wiki, escalating a bad OCR to a vision read,
+  and judging when a query has produced a new concept worth keeping.
+
+The line is *conversion vs. interpretation*, not cheap vs. expensive: tesseract and whisper
+belong in `khb` despite costing real CPU, because their output is reproducible and needs no
+judgement. The split exists so every intelligent decision is auditable — it leaves a
+provenance header and a `log.md` row. When extending khb, keep conversion in the CLI and
+interpretation in an agent pass. Never add a `khb … --auto-label` / `--summarize` flag that
+calls a model; that rots the boundary.
+
+## Where skills live — one canonical file, thin adapters
+
+A skill exists **once**, in `skills/<name>/SKILL.md`, and that one file carries the entire
+protocol. Runtimes that have a notion of "skills" discover it through a parallel adapter
+that only points at it:
+
+```
+skills/<name>/SKILL.md            ← canonical: the whole protocol
+.claude/skills/<name>/SKILL.md    ← adapter: frontmatter + a link
+.agents/skills/<name>/SKILL.md    ← adapter: frontmatter + a link
+```
+
+Each adapter is the same handful of lines — nothing else belongs in one:
+
+```markdown
+---
+name: <name>
+description: <one line; this is what the runtime matches on when deciding to load the skill>
+---
+
+Read and follow the [canonical workflow](../../../skills/<name>/SKILL.md) in full; treat all
+of its instructions as part of this skill.
+```
+
+The `../../../` climbs from `.claude/skills/<name>/` back to the hub root. The two adapters
+are byte-identical to each other; only the canonical file differs from them.
+
+**Adding a hub-specific skill** follows the same shape — create all three files, keep
+`<name>` identical across them, and put every instruction in the canonical file only. The
+adapter `description` is a triggering surface, so write it as *when to reach for this*, not
+as a summary of what it does; the canonical file's own frontmatter can be longer and more
+precise, since it is read after the decision to load has been made.
+
+Never let protocol text drift into an adapter: two copies of a workflow means an agent can
+load the stale one and have no way to tell. If a runtime needs something the link cannot
+express, extend the canonical file and keep the adapter a pointer.
+
+`khb upgrade` refreshes all three trees, so the built-in skills are package-owned — but it
+overwrites paths it ships and does not delete unknown ones, so a skill you add to a hub
+under a name khb does not use survives upgrades intact.
+
+## Tooling
+
+Run `khb` from anywhere inside the hub — it finds the hub by walking up to `khb.json`.
+From outside, pass `--hub <dir>` or set `$KHB_HUB`.
+
+| Command | Purpose |
+|---|---|
+| `khb lint` | validate structure against `skills/lint/SKILL.md` |
+| `khb upgrade` | refresh this hub's package-owned contract docs |
+| `khb visualize` | regenerate `visualizer/graph.html` |
+| `khb new-bundle <name>` | scaffold + register a bundle |
+| `khb ingest [bundle]` | acquire + extract every source in `sources.yaml` → `raw/`; maintains `log.md`. No bundle named → `default`, created if absent |
+| `khb export <bundle> [dest]` | standalone copy: bundle + common patterns, shareable alone |
+
+There is no `khb catalog` command — cataloging is entirely a judgement pass.
+
+## Ingest, then catalog — two steps, in that order
+
+**Ingest** (`skills/ingest/SKILL.md`) is mechanical and flat: `khb ingest <bundle>` pulls
+every declared source into `raw/` as markdown with a provenance header, extracting
+everything it can locally — into the named bundle, or into `default` when none is named — text, PDF, DOCX, ODT, XLSX, PPTX, images by OCR, audio and
+video by whisper. Sources behind an authenticated API (Confluence, ADO, git hosts) you pull
+yourself via MCP/CLI into the same `raw/` shape. Ingest never interprets content.
+
+**Catalog** (`skills/catalog/SKILL.md`) is the judgement half, one bundle at a time: read
+each `raw/` file, split it into concepts, give each OKF frontmatter, link them, register
+them in `index.md`. When the runtime supports parallel agents, fan them out over the raw
+files; only the orchestrating agent writes `index.md`, `log.md` and `refs.md`.
+
+Each bundle's `log.md` is the durable ledger across both steps — rows with an empty
+`curated` column are the catalog backlog, so keep it current. A raw file carrying
+`quality: low` came from OCR or a transcript: distrust it, and re-read the original named in
+its `source:` header when the text looks wrong.
+
+## Parallel work
+
+Two agents may work two different bundles concurrently — bundles are independent by
+construction. Do not have two agents write the same bundle simultaneously.

package/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+KHB is agent-agnostic; this file is only a Claude-specific shim.
+
+@AGENTS.md
+
+Claude discovers the workflow adapters in `.claude/skills/`. Each adapter points to the
+canonical protocol in `skills/<name>/SKILL.md`; use them for querying, ingesting,
+cataloging, linting, creating, visualizing, and exporting bundles.
+Note the split: `ingest` acquires and extracts (mechanical), `catalog` turns `raw/` into
+concept docs (judgement, no CLI command).
+Each canonical `skills/<name>/SKILL.md` is self-contained: the whole protocol is in that
+one file, with no root-level companion doc to chase.

package/README.md

@@ -0,0 +1,289 @@
+# knowledge-hub-builder
+
+<p align="center">
+  <img src="images/demo.gif" alt="KHB creates a hub, ingests sources, routes a question to a concept, and validates the result" width="544">
+</p>
+
+**KHB (Knowledge Hub Builder)** is a local, markdown-based knowledge base maintained with
+Claude Code, Codex, or another coding agent.
+
+Knowledge is divided into **bundles** owned by a person, team, project, or client. Each
+bundle can contain many topics. A small outer index routes the agent to one bundle, and the
+bundle index routes it to the relevant concept documents.
+
+KHB keeps two jobs separate:
+
+- `khb ingest` converts source files into markdown. It is mechanical and does not call a
+  model.
+- The agent catalogs that material into concepts, links, and indexes. This requires
+  judgement and has no CLI command.
+
+Full design: [SPEC.md](SPEC.md). Agent contract: [AGENTS.md](AGENTS.md). Common workflow
+questions: [FAQ](document/faq.md).
+
+## Quick Start
+
+KHB requires [Bun](https://bun.sh).
+
+```bash
+bun install -g @msareen/knowledge-hub-builder
+
+khb init ~/my-knowledge
+cd ~/my-knowledge
+
+khb new-bundle personal "My accounts, plans, records, and reference material"
+```
+
+Add sources to `bundles/personal/sources.yaml`:
+
+```yaml
+sources:
+  - type: folder
+    path: /absolute/path/to/documents
+  - type: files
+    paths:
+      - /absolute/path/to/one.pdf
+      - /absolute/path/to/two.xlsx
+  - type: web
+    urls:
+      - https://example.com/reference
+```
+
+Then either run the workflow directly:
+
+```bash
+khb ingest personal
+```
+
+or ask the agent:
+
+> Ingest and catalog the personal bundle, then run the KHB lint.
+
+The agent discovers the KHB workflow skills from the hub and performs the catalog pass
+after ingestion.
+
+## How It Works
+
+### 1. Ingest
+
+`khb ingest <bundle>` reads `sources.yaml` and writes extracted markdown under
+`bundles/<bundle>/raw/`.
+
+Supported without additional system tools:
+
+- text, markdown, CSV, JSON, and YAML
+- PDF and DOCX
+- ODT, XLSX, and PPTX
+
+Optional local tools add:
+
+- OCR for images and scanned PDFs: `@hyzyla/pdfium`, `sharp`, and `tesseract.js`
+- audio and video transcription: a `whisper` or `faster-whisper` executable on `PATH`
+
+If an optional extractor is missing, KHB leaves a pending row in `log.md` and prints the
+required setup. OCR packages must be installed where the KHB package resolves modules; the
+CLI prints that location.
+
+Every raw markdown file carries provenance:
+
+```yaml
+---
+source: "/absolute/path/to/statement.pdf"
+fetched: 2026-07-23T09:14:02Z
+sha256: db2ee470c95d
+extract_tool: "tesseract.js"
+quality: low
+---
+```
+
+`quality: low` means OCR or transcription may be inaccurate. The agent can return to the
+original `source` during cataloging.
+
+KHB also maintains `bundles/<bundle>/log.md`:
+
+- unchanged source hashes are skipped on later runs;
+- a source that moved or was renamed is recognised by its hash and its existing row is
+  re-pointed at the new path, keeping its `raw` file and its `curated` value — it does not
+  come back as a second row to catalog again;
+- `raw` identifies the extracted file;
+- an empty `raw` means extraction is pending;
+- an empty `curated` means the raw file has not been cataloged.
+
+Authenticated systems such as Confluence, Azure DevOps, or private git hosts remain an
+agent integration boundary. Declare them in `sources.yaml`; the agent acquires them through
+the available MCP server or CLI and preserves the same raw-file provenance shape.
+
+### 2. Catalog
+
+Ask the agent to catalog one bundle. It reads uncataloged rows from `log.md`, turns the raw
+material into concept documents, and updates the bundle index.
+
+A concept is one markdown file with OKF frontmatter:
+
+```markdown
+---
+type: Playbook
+title: Quarterly tax filing
+description: Steps and deadlines for estimated quarterly tax.
+tags: [tax, recurring]
+---
+
+# Steps
+
+...
+
+# Citations
+
+- raw/folder/tax-notes.md
+```
+
+Only `type` is required. `title` and `description` are recommended. `tags`, when present,
+must be a YAML list of strings.
+
+The catalog workflow:
+
+1. Reuses the bundle's existing vocabulary and directories.
+2. Splits or merges source material by concept, not by source filename.
+3. Links related concepts inside the same bundle.
+4. Lists every concept in an `index.md`.
+5. Fills the source row's `curated` value in `log.md`.
+6. Runs `khb lint`.
+
+When the runtime supports subagents, cataloging may process independent raw files in
+parallel. The orchestrating agent remains the only writer of shared index and ledger files.
+
+### 3. Query
+
+Ask a question in natural language. The query workflow follows:
+
+```text
+outer.index.md -> bundles/<name>/index.md -> concept documents
+```
+
+The agent answers from curated concepts, not `raw/`. For a question that genuinely spans
+bundles, it follows `refs.md` and enters the second bundle through its own index.
+
+Indexes contain routing only. Knowledge belongs in concept documents.
+
+## Bundles
+
+A bundle is a unit of ownership, not a subject category. Examples:
+
+- `personal`
+- `team-payments`
+- `client-acme`
+- `project-atlas`
+
+Create one only when you intend to:
+
+```bash
+khb new-bundle team-payments "Payments team roadmap, incidents, and vendor decisions"
+```
+
+KHB never creates, splits, or merges named bundles based on their contents. When
+`khb ingest` is run without a bundle name, it uses a `default` landing bundle and creates it
+if needed.
+
+Cross-bundle relationships belong in `refs.md`; concept documents must not link directly
+into another bundle.
+
+## Claude And Codex
+
+KHB has one source of truth for agent behavior:
+
+- `AGENTS.md` is the common contract. Codex loads it directly.
+- `CLAUDE.md` imports `AGENTS.md` for Claude Code.
+- `skills/<name>/SKILL.md` contains each canonical workflow.
+- `.agents/skills/` contains Codex discovery adapters.
+- `.claude/skills/` contains Claude discovery adapters.
+
+The adapter files are small pointers, not copies of the workflows. Edit only the canonical
+files under `skills/` when developing KHB.
+
+`khb init` copies this managed contract into a hub. `khb upgrade` refreshes it without
+changing `bundles/` or `outer.index.md`. `khb export` includes the same compatibility
+layout in a standalone bundle export.
+
+## Commands
+
+Commands can be run directly or requested through the matching agent skill.
+
+| Command | Purpose |
+|---|---|
+| `khb init [dir]` | Create a hub |
+| `khb upgrade` | Refresh package-owned contracts and skills |
+| `khb new-bundle <name> ["scope"]` | Create and register a bundle |
+| `khb ingest [bundle] [--force]` | Acquire and extract declared sources |
+| `khb lint` | Validate routing, bundle structure, and OKF metadata |
+| `khb visualize [--port N] [--no-open]` (aliases: `vis`, `viz`) | Serve the live bundle graph on a random free port and open it in your default browser — pan/zoomable cross-bundle map, drill into a bundle for its folder-clustered concepts, rebuild-on-refresh, exits when you close the tab |
+| `khb export <bundle> [dest]` | Export one standalone bundle |
+
+Additional ingest flags:
+
+- `--skip-ocr`
+- `--skip-audio`
+
+Run against a hub outside the current directory with `--hub <dir>` or `$KHB_HUB`.
+
+To update the installed package and then refresh a hub:
+
+```bash
+bun update -g @msareen/knowledge-hub-builder
+cd ~/my-knowledge
+khb upgrade
+```
+
+## Hub Layout
+
+```text
+khb.json
+outer.index.md
+AGENTS.md
+CLAUDE.md
+SPEC.md
+skills/<name>/SKILL.md
+.agents/skills/<name>/SKILL.md
+.claude/skills/<name>/SKILL.md
+bundles/<name>/
+  index.md
+  refs.md
+  sources.yaml
+  log.md
+  <group>/<concept>.md
+  raw/
+```
+
+The package owns the contract files and skill directories. You own `outer.index.md` and
+everything under `bundles/`.
+
+## Privacy
+
+`raw/` and the extraction cache under `inbox/` are gitignored. `log.md` is committed and
+records source paths, which may be absolute. Ignore `log.md` before the first commit if
+those paths are sensitive.
+
+`khb export` copies the complete bundle, including `log.md`.
+
+KHB extraction runs locally and does not call a model. Agent cataloging and querying use
+the model provider configured in Claude Code, Codex, or the active agent runtime.
+
+## Development
+
+This repository is both the npm package and a small KHB hub used to exercise the tooling.
+
+```bash
+bun install
+bun run lint
+bun scripts/cli.ts help
+bun scripts/cli.ts init /tmp/scratch-hub
+```
+
+`khb.json`, `bundles/`, and `outer.index.md` are excluded from the published package by the
+`files` allowlist in `package.json`.
+
+## Lineage
+
+KHB combines [Karpathy's LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)
+with [Google's Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf).
+KHB adds the bundle router, cross-bundle reference rules, local ingestion tooling, and
+standalone bundle export.