kb

kb CLI and Knowledge Base Pattern

Build and maintain a self-compiling Obsidian markdown knowledge base using the kb CLI. The LLM reads raw sources, writes cross-linked wiki articles, files Q&A results back into the corpus, and runs lint-and-heal passes. The CLI also supports codebase ingestion with deep inspection commands for code quality, architecture health, and symbol relationships.

Each topic lives in its own folder inside the Obsidian vault, either directly at the vault root (e.g. go-best-practices/) or nested by configured glob (e.g. harness/goclaw/). All topics share a single Obsidian vault, commonly the repo root. Read references/architecture.md for the full rationale and the four-phase pipeline (ingest → compile → query → lint).

Every topic has a lifecycle mode recorded in topic.yaml — wiki (the default) or okf:

• A wiki topic is the Karpathy research lab described throughout this skill. It contains raw/, wiki/, outputs/, and bases/ subtrees plus topic-level CLAUDE.md, topic.yaml, and log.md, and follows the ingest → compile → query → lint loop.
• An OKF topic is a portable Open Knowledge Format catalog (a "bundle") that other people's agents and tools consume. It is flat: typed concept files at the bundle root, plus a generated index.md, a log.md, an OKF-flavored CLAUDE.md, and the AGENTS.md symlink — no raw//wiki//outputs/ pyramid. See the OKF Dual-Mode section below and references/okf-mode.md.

Mode is opt-in per topic and invisible to existing users: absent/empty mode normalizes to wiki, so every existing topic behaves exactly as before.

The topic's CLAUDE.md is the schema document and topic marker — it tells the LLM the scope, conventions, current articles, and research gaps for that topic. topic.yaml is the structured source of truth for topic metadata (slug, title, domain). AGENTS.md may symlink to CLAUDE.md for Codex parity, but the valid-topic marker is CLAUDE.md.

Prerequisites

1. Verify the kb binary is available:

   kb version
   

2. For search and index commands, verify QMD is installed:

   qmd --version
   # If missing: npm install -g @tobilu/qmd
   

3. Supported source languages for codebase analysis: TypeScript (.ts), TSX (.tsx), JavaScript (.js), JSX (.jsx), Go (.go).
4. For repo-root vaults, configure kb.toml at the vault root:

   [vault]
   root = "."
   topic_globs = ["*", "harness/*", "social-media/*"]
   

Pattern Overview

Based on Andrej Karpathy's LLM Wiki pattern, the KB treats the LLM as a compiler that reads raw source documents and produces a structured, cross-linked markdown wiki. The four-phase loop:

1. Ingest — Scrape/curate sources via kb CLI → raw/ (immutable staging)
2. Compile — LLM reads raw/, writes wiki/concepts/ articles (3000-4000 words, dense wikilinks)
3. Query — Q&A against wiki → file answers to outputs/queries/, promote strong answers to wiki
4. Lint — Automated structural checks + LLM-driven semantic healing

Read references/architecture.md for the full rationale, context-window vs RAG tradeoffs, and multi-topic vault design.

OKF Dual-Mode

kb supports two distinct knowledge lifecycles, selected per topic by mode:

• wiki (default) — a research lab: ingest → compile → query → lint. Obsidian [[wikilinks]], the wiki frontmatter schema, the raw/+wiki/+outputs/ pyramid. This is the lifecycle the rest of this skill documents.
• okf — a portable catalog: declare → consume. A flat bundle of typed concepts that conforms to the Open Knowledge Format (OKF) v0.1, meant to be shared and consumed by other people's agents and tools. Plain relative markdown links, the OKF producer-field contract, a generated index.md.

The two are not derived from each other; the high-leverage move is distilling research into the catalog — turning a finished wiki concept into a typed OKF concept. kb makes that one command (kb promote), mechanical and non-LLM, then validates the result (kb okf check).

OKF bundle layout (what kb topic new --mode okf scaffolds):

<bundle>/
  CLAUDE.md        # OKF-flavored schema/marker (topic marker)
  AGENTS.md        # symlink → CLAUDE.md
  topic.yaml       # mode: okf
  index.md         # generated; frontmatter okf_version: "0.1"; concepts grouped by type
  log.md           # "# Directory Update Log"; ISO-date (## YYYY-MM-DD) headings, newest first
  <concept>.md     # typed concept files, flat at the bundle root (added by promote/authoring)

There is no raw//wiki//outputs//bases/ in OKF mode. index.md and log.md are auto-maintained by kb (regenerated on scaffold and on every promote).

OKF concept contract — every concept .md carries four producer fields in frontmatter (emitted alphabetically): description, timestamp (RFC3339, UTC), title, type, plus optional tags. type is the only field OKF v0.1 strictly requires; the other three and the relative-link style are two deliberate, documented deviations matching Google's reference tooling. Concept bodies use relative markdown links ([label](other-concept.md)), never [[wikilinks]].

Two deviations from the written OKF spec are intentional (ADR-002): emit the four producer fields (spec mandates only type) and emit relative links (spec recommends absolute /path.md, which breaks GitHub rendering).

Read references/okf-mode.md for the full bundle layout, frontmatter contract, promote transform rules, conformance ruleset, and the concept-path/link model.

Related Skills

This skill orchestrates several companion skills for the LLM-driven phases:

• obsidian-markdown — author wiki articles with valid Obsidian Flavored Markdown (wikilinks, callouts, embeds, properties).
• obsidian-bases — create .base files under <topic>/bases/ for dashboard views, filters, and formulas.
• obsidian-cli — interact with the running Obsidian vault from the command line (open notes, search, refresh indexes).

kb CLI Quick Reference

Topic management

kb topic new <slug> <title> <domain>              # scaffold a new wiki topic (mode: wiki, default)
kb topic new <slug> <title> <domain> --mode okf   # scaffold a flat OKF bundle (mode: okf)
kb topic list                                      # list all topics in the vault
kb topic info <topic-id>                           # topic metadata (counts, last log entry)

--mode accepts wiki (default) or okf. An OKF topic scaffolds the flat bundle layout (see the OKF Dual-Mode section), not the wiki pyramid.

OKF bundles (promote + conformance)

kb promote <wiki-doc> --to <okf-topic> --type <Type>                  # distill a wiki concept into an OKF bundle
kb promote <wiki-doc> --to <okf-topic> --type <Type> --description "…" # override the generated description
kb okf check <okf-topic>                                               # validate OKF v0.1 conformance (lenient)
kb okf check <okf-topic> --strict --format json                       # promote local-standard warnings to errors (CI gate)

kb promote is mechanical, non-LLM, and non-destructive: it reads a compiled wiki document, remaps its frontmatter to the OKF producer contract, rewrites [[wikilinks]] to relative markdown links, writes a new typed concept at the bundle root, regenerates the bundle's index.md, and inserts a newest-first log.md entry. The source wiki document is left untouched. Both --to and --type are required, and --to must resolve to a mode: okf topic or promote errors before writing. The concept filename is a slug of the source document's base name (collisions get a -2, -3 suffix), so its filename and every inbound link share one canonical key. kb promote emits the JSON ConceptResult (writtenPath, type, linksRewritten, unresolvedLinks, warnings).

kb okf check is lenient by default per OKF §9 (tolerates broken cross-links, unknown type values, missing optional fields) so externally produced bundles pass. It emits diagnostics as severity, kind, filePath, target, message and exits non-zero when any error is present (and on warnings too under --strict). Hard errors include a concept with a missing/empty type and unparseable frontmatter; local-standard warnings include a missing producer field (title/description/timestamp) and a type outside the configured vocabulary. The type vocabulary is the local standard in kb.toml:

[okf]
# Local OKF concept type vocabulary. Empty (the default) means `kb okf check`
# never warns about unknown types until you opt into a local standard.
types = ["Voice Profile", "Offer", "Playbook"]

When [okf].types is non-empty, a --type (or existing concept type) outside the list is a warning — --strict turns it into a CI-failing error, preventing type drift (Voice Profile vs voice-profile).

Ingestion (auto-generates frontmatter, auto-appends to log.md)

kb ingest url <url> --topic <topic-id>        # scrape a web URL via Firecrawl
kb ingest file <path> --topic <topic-id>      # convert local file (PDF, DOCX, EPUB, HTML, images w/OCR, etc.)
kb ingest youtube <url> --topic <topic-id>    # extract a single YouTube transcript -> raw/youtube/
kb ingest channel <url> --topic <topic-id>    # bulk-extract a YouTube channel/playlist -> raw/youtube/
kb ingest instagram <url> --topic <topic-id>  # Instagram reel/video (caption + transcript) -> raw/instagram/
kb ingest bookmarks <path> --topic <topic-id> # ingest a bookmark-cluster markdown file
kb ingest codebase <path> --topic <topic-id>  # an

---

*Content truncated.*