kb: Instructions file for Claude Code

CLAUDE.md

Project Overview

kb is a single-binary Go CLI for building and maintaining topic-based knowledge bases in the Karpathy KB pattern. It handles the non-LLM workflow: topic scaffolding, multi-source ingestion, structural linting, codebase analysis, QMD indexing/search, and KB-oriented inspection commands. Semantic judgments (ingest gates, classification, linking, retrieval) go through a required decision model (Jev over OpenRouter); a generation model writes only short literals, never article prose.

Reference TypeScript source: ~/dev/projects/kodebase

Source of Truth

• KB pivot tech spec: .compozy/tasks/kb-pivot/_techspec.md
• KB pivot task tracker: .compozy/tasks/kb-pivot/_tasks.md
• KB pivot workflow memory: .compozy/tasks/kb-pivot/memory/
• Decision model spec (kb-jev, revision 3): .wayfinder/kb-jev/spec.md; cross-package contracts: .claude/plans/kb-jev.md; domain vocabulary: CONTEXT.md

Critical Rules

• make verify is the non-negotiable completion gate: fmt -> lint -> test -> build -> boundaries.
• make lint must report zero findings.
• Use go get for dependency changes.
• Never use destructive git restore/reset/checkout/clean/rm commands without explicit approval.
• Prefer local repository inspection over web search for codebase questions.
• kb-written frontmatter keys carry no namespace prefix: they are plain (summary, concepts, triage, genre, ...) and ownership comes from decisions.OwnedKeys plus value hashes.

Active Build Surface

make verify
make fmt
make lint
make test
make test-integration
make build
make deps
make help

• make build compiles ./... and writes bin/kb from cmd/kb.

Active Package Layout

Path	Responsibility
cmd/kb	Program entrypoint for the kb binary
internal/cli	Cobra root, subcommands, flag resolution, and command I/O
internal/topic	Topic scaffolding, listing, and topic metadata lookup
internal/ingest	Ingest orchestration, frontmatter assembly, raw writes, and log entries
internal/convert	Converter registry and format-specific file converters
internal/firecrawl	Firecrawl REST client for kb ingest url, including the fresh-refetch options (maxAge, waitFor, onlyMainContent)
internal/mediadl	Shared yt-dlp + STT engine: audio/caption download, ffmpeg segmentation, and transcript extraction reused by youtube and instagram
internal/youtube	YouTube URL parsing, channel/bulk ingestion, and frontmatter over the mediadl core
internal/instagram	Instagram reel/video URL parsing and caption+transcript composition over the mediadl core
internal/frontmatter	Shared frontmatter parsing and generation helpers
internal/lint	KB lint engine (structural and decision-workflow kinds; never calls a model) and report rendering
internal/generate	Codebase-to-KB pipeline used by kb ingest codebase and the hidden legacy generate alias
internal/scanner	Source discovery and ignore handling for codebase ingest
internal/adapter	Tree-sitter parsing adapters
internal/graph	Graph normalization for codebase snapshots
internal/metrics	File, symbol, directory, and smell metrics
internal/vault	Topic path helpers, render/write logic, vault reads, and inspect snapshot loading
internal/qmd	QMD subprocess integration for index and search
internal/output	Table, JSON, and TSV formatting
internal/models	Shared domain models and interfaces
internal/config	TOML config plus env-backed runtime overrides
internal/logger	Slog logger setup
internal/version	Build metadata surfaced by kb version
internal/decisions	Decision engine: Engine.Decide, transport to the OpenRouter decisions endpoint, receipt validation, receipts cache, banding, budget, concurrency, redaction, run summary, and the OwnedKeys list
internal/generation	Generation-model client for short literals over OpenRouter chat completions (strict JSON schema, reasoning disabled, fallback model), sharing the run budget and receipts
internal/questions	Embedded, versioned question banks, loader (guard prefix, schema check, bank hash), composite banks, topic extra banks, and regression cases
internal/resolve	Obsidian-style link resolution and link extraction shared by lint, refs, and link; quarantine path helpers
internal/corpus	Topic document loader, body and value hashes, BM25, alias dictionary and mention scan, section-aware excerpts, provenance state, .decisions/state.jsonl, and the byte-preserving owned-key writer
internal/contract	Selection contract parse/validate/hash/render, CLAUDE.md section import and render, topic.yaml settings (contract, drafts, decisions block), path globs
internal/contract/topicyaml	Node-level topic.yaml editor that keeps untouched keys, comments, and key order
internal/session	Per-run bundle for decision-backed commands: config, topic, settings, contract, engine, generation client, lazy corpus, state store, writer, review store, decision modes; fails fast without OPENROUTER_API_KEY
internal/scope	kb topic contract workflow: draft, CLAUDE.md import, self-check, impact preview, activation
internal/classify	Classification facets, generated literals (summary, entities, questions, criterion, aliases), the shared gate judgment, recapture/remove queues, concept proposals, vocabulary draft/accept
internal/quality	Code quality checks run before any quality question (not_an_article, thin, error_page)
internal/gate	Ingest gates: exact dedupe, pre-fetch relevance, code quality, refetch, post-fetch quality and relevance, near-duplicate, quarantine
internal/link	Link candidates, per-document judgment, write policy (frontmatter relations, body links), reverse pass
internal/find	Retrieval judge (candidates, judgment, ranking with named exclusions) and facet counts
internal/review	Review queue store, labels, import-labels, import-links, calibration with holdout, impact-preview ledger
internal/refs	Inbound-reference scan, quarantine and restore, quarantine-ledger.jsonl
internal/actions	kb review accept|reject dispatcher over refs, link, gate, and classify
internal/okf	OKF bundle promote, conformance check, and decision-model type suggestion
internal/fakes	httptest fakes for the OpenRouter decisions and generation endpoints and Firecrawl, used by tests