qkb: Instructions file for Claude Code

qkb — Project Instructions

Hybrid BM25 + vector search for Obsidian-style knowledge-base vaults, with frontmatter treated as structured metadata. TypeScript (Node ≥20, better-sqlite3 + sqlite-vec, node-llama-cpp, commander CLI, @modelcontextprotocol/sdk MCP server). Package @miguelarios/qkb, command qkb.

The original Python implementation (qkb-search, v0.3.0) is no longer in the tree; it is on PyPI and in git history. Source comments that cite legacy/python/... or a *.py module refer to the last release that still carried it: git show v0.4.3:legacy/python/src/qkb/<module>.py.

Source of truth

• GitHub issues are the roadmap. The MVP is tracked in #19 (sub-issues, label mvp). File new work as issues with the templates below rather than as plan documents; close issues from PRs (Closes #N).
• docs/plans/2026-07-20-typescript-rewrite.md — the TypeScript rewrite plan (complete, kept for history).
• docs/plans/2026-07-06-phase1-mvp.md — the original Python implementation plan, kept for history.
• docs/GUIDE.md — user guide: how notes are read, declared/sibling fields, related notes, ranking. Keep it in sync with behavior changes.
• docs/DESIGN.md — technical design. docs/adr/architecture-decisions.md — decision log; ADRs win over DESIGN.md on conflict.
• docs/PRD.md — success criteria. Primary: ≥8/10 golden queries return the target doc in the top 3.

Commands

npm test                                   # unit tests (vitest, no Ollama, FakeProvider)
npx biome check . && npx tsc --noEmit      # lint/format + typecheck
npm run build                              # tsc -> dist/

Hard rules

• This repo is public. No real names, personal contexts, private hostnames/IPs, or vault content in code, tests, fixtures, docs, or commit messages. Test data uses synthetic values (Alice Smith, example.com, homelab-traefik-style contexts). The gitleaks pre-commit hook enforces this — if it blocks a commit, fix the data; NEVER --no-verify.
• The owner's real golden-query file lives at ~/.config/qkb/golden_queries.yaml — read/run it locally, never copy it (or its contents) into the repo.
• The Obsidian vault is read-only. Never write into it.
• Unit tests must pass offline: no model download, no Ollama, no network — use the fake provider. Tests that need a real model live in test/integration/ and run only with npm run test:integration.
• Releases: merging a chore(release): X.Y.Z PR publishes to npm (release on merge — see .github/workflows/release.yml). An agent may open that PR when asked: bump package.json + package-lock.json (npm version X.Y.Z --no-git-tag-version) and add a ## X.Y.Z (YYYY-MM-DD) section to CHANGELOG.md, nothing else. Merging it, and pushing v* tags, is owner-only.