claude-second-brain 0.5.1 → 1.0.0

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "claude-second-brain",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "The fastest way to start your personal knowledge base powered by Obsidian, Claude Code, qmd, and GitHub.",
   "type": "module",
   "bin": {
-    "claude-second-brain": "./bin/create.js"
+    "claude-second-brain": "./bin/create.js",
+    "csb": "./bin/create.js"
   },
   "scripts": {
     "docs:dev": "vocs dev",

package/template/.claude/skills/brain-ingest/SKILL.md

@@ -8,6 +8,23 @@ argument-hint: "File path (e.g. raw-sources/articles/my-article.md), URL, or lea
 
 Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 
+## Brain Discovery
+
+All commands target the **default brain** registered in `~/.claude-second-brain/config.toml`.
+Resolve paths at call time via the `claude-second-brain` CLI — do not bake paths into this file:
+
+```bash
+BRAIN_PATH=$(npx -y claude-second-brain path)       # absolute path to the default brain's directory
+```
+
+qmd commands go through the CLI proxy, which sets `INDEX_PATH` for you:
+
+```bash
+npx -y claude-second-brain qmd -- query -c wiki "<terms>"
+```
+
+Pass `--brain <name>` before the `--` to target a non-default brain.
+
 ## Inputs
 
 - **File path** — a file in `raw-sources/articles/`, `raw-sources/pdfs/`, or `raw-sources/personal/`
@@ -27,7 +44,7 @@ Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 - Let the user's response shape which topics get deep treatment before proceeding
 
 **Step 3 — Create source summary page**
-- File: `wiki/sources/[slug].md` (slug = kebab-case from title)
+- File: `$BRAIN_PATH/wiki/sources/[slug].md` (slug = kebab-case from title)
 - Sections: title, author/date, one-paragraph abstract, key claims (bulleted), notable quotes (max 3), synthesis note, links to wiki pages this source touches
 - Frontmatter: `type: source-summary`, `tags`, `updated: YYYY-MM-DD`
 
@@ -35,8 +52,8 @@ Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 - Add the new source to the Sources Ingested section: one-line description + `[[wiki/sources/slug]]` link
 
 **Step 5 — Identify affected wiki pages**
-- Run: `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<source topic and key claims>"`
-- Also Glob `wiki/*.md` and `wiki/sources/*.md` to catch anything qmd missed
+- Run: `npx -y claude-second-brain qmd -- query -c wiki "<source topic and key claims>"`
+- Also Glob `$BRAIN_PATH/wiki/*.md` and `$BRAIN_PATH/wiki/sources/*.md` to catch anything qmd missed
 - List all pages to create or update before proceeding
 
 **Step 6 — Update or create wiki pages**
@@ -54,7 +71,7 @@ Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 - Otherwise skip this step
 
 **Step 9 — Append to log**
-- Append to `wiki/log.md` (never overwrite):
+- Append to `$BRAIN_PATH/wiki/log.md` (never overwrite):
   ```
   ## [YYYY-MM-DD] ingest | Source Title
 

package/template/.claude/skills/brain-rebuild/SKILL.md

@@ -25,9 +25,9 @@ All commands run from the vault root.
 - Read `CLAUDE.md` to understand the documented schema and any references to collection names
 - List current state from qmd:
   ```bash
-  INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection list
-  INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context list
-  INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
+  INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd collection list
+  INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd context list
+  INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd status
   ```
 
 ### Step 2 — Analyze the wiki
@@ -66,7 +66,7 @@ Edit `scripts/qmd/setup.ts` to reflect the new schema:
 If collection names changed:
 
 - Update every occurrence in `CLAUDE.md` (e.g. `qmd query -c wiki` → new name)
-- Update `.claude/skills/brain-ingest/SKILL.md`, `.claude/skills/brain-search/SKILL.md`, `.claude/skills/lint/SKILL.md`, `.claude/skills/qmd-cli/SKILL.md` — anywhere collection names are hard-coded
+- Update `.claude/skills/brain-ingest/SKILL.md`, `.claude/skills/brain-search/SKILL.md`, `.claude/skills/lint/SKILL.md` — anywhere collection names are hard-coded
 - Use Grep to find any remaining stale references before moving on
 
 ### Step 7 — Tear down the old schema
@@ -74,13 +74,13 @@ If collection names changed:
 For each existing collection that no longer fits the new schema:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection remove <old-name>
+INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd collection remove <old-name>
 ```
 
 For each obsolete context:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context rm <path>
+INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd context rm <path>
 ```
 
 ### Step 8 — Register the new schema
@@ -104,9 +104,9 @@ This indexes all files under the new collections and generates fresh embeddings.
 ### Step 10 — Verify and report
 
 ```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection list
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context list
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
+INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd collection list
+INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd context list
+INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd status
 ```
 
 Confirm the new collections appear, contexts match the plan, and document/embedding counts are non-zero. Report a summary of what changed (collections added/removed/renamed, contexts updated, files re-indexed, references updated in CLAUDE.md and skills).

package/template/.claude/skills/brain-refresh/SKILL.md

@@ -8,6 +8,18 @@ argument-hint: "Optional: 'force' to force re-embedding of every chunk (slow, us
 
 Refreshes the qmd index so search reflects the current state of the vault. Wraps `pnpm qmd:reindex` (incremental) and the qmd CLI's force-embed flag.
 
+## Brain Discovery
+
+All commands target the **default brain** registered in `~/.claude-second-brain/config.toml`.
+Resolve the brain root via the CLI and run qmd through the CLI proxy:
+
+```bash
+BRAIN_PATH=$(npx -y claude-second-brain path)
+npx -y claude-second-brain qmd -- status
+```
+
+Pass `--brain <name>` before the `--` to target a non-default brain.
+
 ## When to Use
 
 - After a `/brain-ingest` session (or several) — batch the refresh, don't run after every file edit
@@ -17,13 +29,13 @@ Refreshes the qmd index so search reflects the current state of the vault. Wraps
 
 ## Procedure
 
-All commands run from the vault root.
+All `pnpm qmd:*` commands must run from `$BRAIN_PATH`; the CLI proxy (`claude-second-brain qmd`) works from anywhere.
 
 ### Default — Incremental Refresh
 
 Run:
 ```bash
-pnpm qmd:reindex
+cd "$BRAIN_PATH" && pnpm qmd:reindex
 ```
 
 This script does two things:
@@ -38,10 +50,10 @@ When the user passes `force`, re-embed **every** chunk — not just the changed
 
 ```bash
 # Step 1 — update the file index first
-pnpm qmd:reindex
+cd "$BRAIN_PATH" && pnpm qmd:reindex
 
 # Step 2 — force re-embed everything
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd embed -f
+npx -y claude-second-brain qmd -- embed -f
 ```
 
 Force mode is slow — confirm with the user before proceeding if the wiki is large.
@@ -51,7 +63,7 @@ Force mode is slow — confirm with the user before proceeding if the wiki is la
 After refresh, confirm with:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
+npx -y claude-second-brain qmd -- status
 ```
 
 Document and embedding counts should be non-zero and reflect recent activity. If embeddings show as `0` or far below document count, re-run the refresh.
@@ -61,3 +73,4 @@ Document and embedding counts should be non-zero and reflect recent activity. If
 - First run downloads ~2GB of GGUF models — expected, one-time
 - Do not run this after every single file edit — batch it after a session
 - This skill does **not** change the qmd schema (collections, contexts). For that, use `/brain-rebuild`
+- If `query` or `search` commands fail with "collection not found", run `pnpm qmd:setup` from the vault root to re-register collections, then re-run this skill

package/template/.claude/skills/brain-search/SKILL.md

@@ -8,12 +8,24 @@ argument-hint: "The question or topic to query (e.g. 'what do I know about trans
 
 Runs the 4-step query workflow defined in CLAUDE.md. Answers come with inline `[[wiki/page]]` citations — not a list of files.
 
+## Brain Discovery
+
+All commands target the **default brain** registered in `~/.claude-second-brain/config.toml`.
+Resolve paths and run qmd via the `claude-second-brain` CLI — do not bake paths into this file:
+
+```bash
+BRAIN_PATH=$(npx -y claude-second-brain path)       # absolute path to the default brain's directory
+npx -y claude-second-brain qmd -- query -c wiki "<question>"
+```
+
+Pass `--brain <name>` before the `--` to target a non-default brain.
+
 ## Workflow
 
 **Step 1 — Search the wiki**
-- Run hybrid search: `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<question>"`
-- Read `wiki/index.md` to confirm coverage and catch any pages qmd didn't surface
-- Read the 2–5 most relevant pages in full before synthesizing
+- Run hybrid search: `npx -y claude-second-brain qmd -- query -c wiki "<question>"`
+- Read `$BRAIN_PATH/wiki/index.md` to confirm coverage and catch any pages qmd didn't surface
+- Read the 2–5 most relevant pages in full before synthesizing (paths relative to `$BRAIN_PATH`)
 
 **Step 2 — Synthesize an answer**
 - Write the answer with inline `[[wiki/page]]` citations throughout
@@ -24,12 +36,12 @@ Runs the 4-step query workflow defined in CLAUDE.md. Answers come with inline `[
 - If the answer draws together multiple pages in a novel way, ask:
   > "This answer synthesizes several pages in a useful way — want me to file it as a Q&A page?"
 - If yes:
-  - Create `wiki/qa/[slug].md` with frontmatter `type: qa`
+  - Create `$BRAIN_PATH/wiki/qa/[slug].md` with frontmatter `type: qa`
   - Add to the Q&A section in `wiki/index.md`
   - Add `[[wiki/qa/slug]]` cross-links from the relevant topic pages
 
 **Step 4 — Log (if significant)**
-- For queries that reveal new understanding or surface a gap worth tracking, append to `wiki/log.md`:
+- For queries that reveal new understanding or surface a gap worth tracking, append to `$BRAIN_PATH/wiki/log.md`:
   ```
   ## [YYYY-MM-DD] query | Brief question summary
 

package/template/CLAUDE.md

@@ -111,7 +111,7 @@ Run this workflow whenever the user adds a new source. Do not skip steps.
 - Add the new source to the Sources section with a one-line description and link.
 
 **Step 5 — Identify affected wiki pages**
-- Run `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<source topic and key claims>"` to surface related existing wiki pages.
+- Run `INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd query -c wiki "<source topic and key claims>"` to surface related existing wiki pages.
 - Also Glob `wiki/*.md` and `wiki/sources/*.md` to ensure completeness.
 - List all pages to create or update.
 
@@ -142,7 +142,7 @@ Run this workflow whenever the user adds a new source. Do not skip steps.
 Run this workflow when the user asks a question against the wiki.
 
 **Step 1 — Search the wiki**
-- Run `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<question>"` to surface semantically relevant pages.
+- Run `INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd query -c wiki "<question>"` to surface semantically relevant pages.
 - Read `wiki/index.md` to confirm coverage and catch any pages qmd didn't surface.
 - Read the 2-5 most relevant pages fully.
 
@@ -212,15 +212,15 @@ N issues found, N fixed. [Brief summary of notable findings.]
 ## Search Tool
 
 This vault uses **qmd** (`pnpm dlx @tobilu/qmd`) for local semantic and full-text search.
-Collections and contexts are registered via `pnpm qmd:setup` and stored at `__QMD_PATH__` (gitignored).
+Collections and contexts are registered via `pnpm qmd:setup` and stored at `.qmd/index.sqlite` (gitignored, relative to vault root).
 
-Key commands:
+Key commands (run from the vault root):
 
 | Command | Use |
 |---------|-----|
-| `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<question>"` | Hybrid search — best for topic discovery |
-| `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd search -c wiki "<terms>"` | Fast keyword search (BM25, no LLM) |
-| `INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd vsearch -c wiki "<question>"` | Pure vector/semantic search |
+| `INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd query -c wiki "<question>"` | Hybrid search — best for topic discovery |
+| `INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd search -c wiki "<terms>"` | Fast keyword search (BM25, no LLM) |
+| `INDEX_PATH=.qmd/index.sqlite pnpm dlx @tobilu/qmd vsearch -c wiki "<question>"` | Pure vector/semantic search |
 
 Add `--json` for structured output. Omit `-c wiki` to search all collections (wiki, raw-sources, human, daily-notes).
 

package/template/README.md

@@ -13,23 +13,14 @@ Inspired by [Andrej Karpathy's approach to LLM-powered knowledge management](htt
 ## Quick start
 
 ```bash
-# 1. Install tools (node + pnpm via mise)
-mise install
+# 1. Generate vector embeddings (first run downloads ~2GB of GGUF models — once per machine)
+pnpm qmd:reindex
 
-# 2. Install dependencies
-pnpm install
-
-# 3. Open Claude Code
+# 2. Open Claude Code
 claude
 ```
 
-Inside Claude Code, run:
-
-```
-/setup
-```
-
-Registers the qmd collections and generates local vector embeddings. First run downloads ~2GB of GGUF models — once.
+qmd collections are already registered by the CLI during scaffolding — `pnpm qmd:reindex` just needs to build the index.
 
 **Then open this folder in Obsidian.** The Git plugin is pre-configured — enable it in Obsidian settings and your wiki syncs automatically.
 
@@ -51,10 +42,6 @@ Registers the qmd collections and generates local vector embeddings. First run d
 
 **`/brain-rebuild`** — **Destructive.** Redesigns the qmd schema: analyzes the wiki, proposes new collections and contexts, waits for your approval, then patches `scripts/qmd/setup.ts`, drops the old index, and rebuilds embeddings from scratch.
 
-### Setup
-
-**`/setup`** — First-time initialization. Registers the qmd collections and generates local vector embeddings. Run once after scaffolding.
-
 ---
 
 ## How it works
@@ -158,14 +145,14 @@ claude-second-brain/
 
 ## Installing and updating skills
 
-Skills are slash commands Claude Code loads from `.claude/skills/[name]/SKILL.md` in this vault. The wiki ships with `/brain-ingest`, `/brain-search`, `/brain-refresh`, `/brain-rebuild`, `/lint`, `/setup`, and `/qmd-cli` pre-installed.
+Skills are slash commands Claude Code loads from `.claude/skills/[name]/SKILL.md` in this vault. The wiki ships with `/brain-ingest`, `/brain-search`, `/brain-refresh`, `/brain-rebuild`, and `/lint` pre-installed.
 
 ### Update built-in wiki skills
 
 Pull the latest skills from the upstream template:
 
 ```bash
-# Install or update all 7 wiki skills
+# Install or update all 5 wiki skills
 npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills -a claude-code -y
 
 # Or update a specific skill
@@ -192,6 +179,17 @@ This wraps `pnpm qmd:reindex` — you can also run that command directly if you'
 
 ---
 
+## Managing brains
+
+From anywhere:
+
+```bash
+npx claude-second-brain ls           # list all brains
+npx claude-second-brain rm <name>    # remove a brain
+```
+
+---
+
 ## License
 
 MIT

package/template/scripts/qmd/reindex.ts

@@ -11,26 +11,38 @@
  */
 
 import { createStore } from "@tobilu/qmd"
+import { mkdir } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
 
-const DB = "__QMD_PATH__"
+const VAULT = join(dirname(fileURLToPath(import.meta.url)), "../..")
+const DB = join(VAULT, ".qmd", "index.sqlite")
 
-const store = await createStore({ dbPath: DB })
+try {
+  await mkdir(dirname(DB), { recursive: true })
+  const store = await createStore({ dbPath: DB })
 
-console.log("Updating file index...")
-const result = await store.update({
-  onProgress: ({ collection, file, current, total }: any) => {
-    process.stdout.write(`\r  [${collection}] ${current}/${total} ${file}`.padEnd(80))
-  },
-})
-console.log(
-  `\n  indexed: ${result.indexed} | updated: ${result.updated} | ` +
-  `removed: ${result.removed} | needs embedding: ${result.needsEmbedding}`
-)
+  console.log("Updating file index...")
+  const result = await store.update({
+    onProgress: ({ collection, file, current, total }: any) => {
+      process.stdout.write(`\r  [${collection}] ${current}/${total} ${file}`.padEnd(80))
+    },
+  })
+  console.log(
+    `\n  indexed: ${result.indexed} | updated: ${result.updated} | ` +
+    `removed: ${result.removed} | needs embedding: ${result.needsEmbedding}`
+  )
 
-console.log("Generating embeddings...")
-await store.embed({
-  onProgress: ({ current, total, collection }: any) => {
-    process.stdout.write(`\r  [${collection}] ${current}/${total}`.padEnd(60))
-  },
-})
-console.log("\nDone.")
+  console.log("Generating embeddings...")
+  await store.embed({
+    onProgress: ({ current, total, collection }: any) => {
+      process.stdout.write(`\r  [${collection}] ${current}/${total}`.padEnd(60))
+    },
+  })
+  console.log("\nDone.")
+} catch (err: any) {
+  console.error(`\n[qmd:reindex] ${err?.message || err}`)
+  console.error(`  vault: ${VAULT}`)
+  console.error(`  db:    ${DB}`)
+  process.exit(1)
+}

package/template/scripts/qmd/setup.ts

@@ -10,48 +10,57 @@
  */
 
 import { createStore } from "@tobilu/qmd"
+import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 
 const VAULT = join(dirname(fileURLToPath(import.meta.url)), "../..")
-const DB = "__QMD_PATH__"
+const DB = join(VAULT, ".qmd", "index.sqlite")
 
-const store = await createStore({ dbPath: DB })
+try {
+  await mkdir(dirname(DB), { recursive: true })
+  const store = await createStore({ dbPath: DB })
 
-// --- Collections (idempotent) ---
-const existingCols = await store.listCollections()
-const existing = new Set(existingCols.map((c: any) => c.name))
+  // --- Collections (idempotent) ---
+  const existingCols = await store.listCollections()
+  const existing = new Set(existingCols.map((c: any) => c.name))
 
-async function ensureCollection(name: string, relPath: string, pattern: string) {
-  if (existing.has(name)) {
-    console.log(`  skip (exists): ${name}`)
-    return
+  async function ensureCollection(name: string, relPath: string, pattern: string) {
+    if (existing.has(name)) {
+      console.log(`  skip (exists): ${name}`)
+      return
+    }
+    await store.addCollection(name, { path: join(VAULT, relPath), pattern })
+    console.log(`  added: ${name}`)
   }
-  await store.addCollection(name, { path: join(VAULT, relPath), pattern })
-  console.log(`  added: ${name}`)
-}
 
-console.log("Collections:")
-await ensureCollection("wiki",        "wiki",        "**/*.md")
-await ensureCollection("raw-sources", "raw-sources", "**/*.md")
-
-// --- Global context ---
-console.log("\nContexts:")
-await store.setGlobalContext(
-  "Personal knowledge vault. Uses Obsidian [[wiki/page]] wikilinks. " +
-  "Wiki pages have YAML frontmatter: type (overview|topic|entity|source-summary|qa), " +
-  "tags, sources, related, updated."
-)
-
-// wiki/
-await store.addContext("wiki", "",         "LLM-maintained synthesized knowledge base — the authoritative wiki layer")
-await store.addContext("wiki", "/sources", "Source summaries — one page per ingested source, with abstract, key claims, and synthesis notes")
-await store.addContext("wiki", "/qa",      "Filed Q&A answers that synthesize multiple wiki pages around a notable question")
-
-// raw-sources/
-await store.addContext("raw-sources", "",          "Raw source material — immutable originals, never modified after ingestion")
-await store.addContext("raw-sources", "/articles", "Web articles saved as markdown")
-await store.addContext("raw-sources", "/pdfs",     "PDF files or their extracted text")
-await store.addContext("raw-sources", "/personal", "Personal notes flagged for wiki ingestion")
-
-console.log("\nSetup complete. Run: pnpm qmd:reindex")
+  console.log("Collections:")
+  await ensureCollection("wiki",        "wiki",        "**/*.md")
+  await ensureCollection("raw-sources", "raw-sources", "**/*.md")
+
+  // --- Global context ---
+  console.log("\nContexts:")
+  await store.setGlobalContext(
+    "Personal knowledge vault. Uses Obsidian [[wiki/page]] wikilinks. " +
+    "Wiki pages have YAML frontmatter: type (overview|topic|entity|source-summary|qa), " +
+    "tags, sources, related, updated."
+  )
+
+  // wiki/
+  await store.addContext("wiki", "",         "LLM-maintained synthesized knowledge base — the authoritative wiki layer")
+  await store.addContext("wiki", "/sources", "Source summaries — one page per ingested source, with abstract, key claims, and synthesis notes")
+  await store.addContext("wiki", "/qa",      "Filed Q&A answers that synthesize multiple wiki pages around a notable question")
+
+  // raw-sources/
+  await store.addContext("raw-sources", "",          "Raw source material — immutable originals, never modified after ingestion")
+  await store.addContext("raw-sources", "/articles", "Web articles saved as markdown")
+  await store.addContext("raw-sources", "/pdfs",     "PDF files or their extracted text")
+  await store.addContext("raw-sources", "/personal", "Personal notes flagged for wiki ingestion")
+
+  console.log("\nSetup complete. Run: pnpm qmd:reindex")
+} catch (err: any) {
+  console.error(`\n[qmd:setup] ${err?.message || err}`)
+  console.error(`  vault: ${VAULT}`)
+  console.error(`  db:    ${DB}`)
+  process.exit(1)
+}

package/template/.claude/skills/qmd-cli/SKILL.md

@@ -1,168 +0,0 @@
----
-name: qmd-cli
-description: 'Use qmd CLI to manage collections, index documents, search, and query a local semantic knowledge base. Use when the user mentions qmd, searching a collection, indexing files, running queries, hybrid search, BM25, vector search, or managing a document index. Covers: collection add/list/remove/rename, context management, get/multi-get, update, embed, query, search, vsearch, and MCP server commands.'
-argument-hint: 'qmd command to run or describe what you want to do (e.g., "query wiki for X", "add folder to collection")'
----
-
-# qmd CLI
-
-Local semantic document index with hybrid search (BM25 + vector), collection management, and MCP server.
-
-## Vault DB
-
-This vault keeps its index at `__QMD_PATH__`. All CLI commands **must** prefix with `INDEX_PATH=__QMD_PATH__`:
-
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "..."
-```
-
-The scripts `pnpm qmd:setup` and `pnpm qmd:reindex` write to this same file. The CLI must match.
-
----
-
-## Collection Management
-
-```bash
-# Create/index a collection
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection add <path> --name <name> --mask <glob-pattern>
-# e.g.:
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection add wiki --name wiki --mask "**/*.md"
-
-# List all collections with details
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection list
-
-# Remove a collection
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection remove <name>
-
-# Rename a collection
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection rename <old-name> <new-name>
-```
-
-## Listing Files
-
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd ls
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd ls [collection[/path]]
-```
-
-## Context
-
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context add [path] "description text"
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context list
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context rm <path>
-```
-
-## Retrieving Documents
-
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd get <file>[:line] [-l N] [--from N]
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd multi-get <pattern> [-l N] [--max-bytes N]
-```
-
-**Multi-get format flags:** `--json`, `--csv`, `--md`, `--xml`, `--files`
-
-## Indexing & Maintenance
-
-```bash
-# Show index status and collections
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
-
-# Re-index all collections
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd update [--pull]
-
-# Create vector embeddings (900 tokens/chunk, 15% overlap)
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd embed [-f]
-
-# Remove cache and orphaned data, vacuum DB
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd cleanup
-```
-
-> After bulk ingest sessions, run `update` then `embed` to keep the index fresh.
-
-## Search & Query
-
-| Command | Description |
-|---------|-------------|
-| `qmd query <query>` | **Recommended** — hybrid search with query expansion + reranking |
-| `qmd search <query>` | Full-text keyword search (BM25, no LLM) |
-| `qmd vsearch <query>` | Pure vector/semantic similarity search |
-
-### Search Options
-
-```
--n <num>               Number of results (default: 5, or 20 for --files)
---all                  Return all matches (use with --min-score to filter)
---min-score <num>      Minimum similarity score
---full                 Output full document instead of snippet
---line-numbers         Add line numbers to output
---files                Output docid,score,filepath,context
---json                 JSON output with snippets
---csv                  CSV output
---md                   Markdown output
---xml                  XML output
--c, --collection <name>  Filter results to a specific collection
-```
-
-### Examples
-
-```bash
-# Hybrid search across all collections
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query "distributed systems consensus"
-
-# Search only the wiki collection, JSON output
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "transformer architecture" --json
-
-# Keyword-only search, top 10, markdown output
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd search -c wiki "kafka" -n 10 --md
-
-# Vector search with full documents
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd vsearch "attention mechanism" --full
-
-# Filter by score threshold
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query "machine learning" --all --min-score 0.7
-```
-
-## MCP Server
-
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd mcp
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd mcp --http [--port N]
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd mcp --http --daemon
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd mcp stop
-```
-
-## Global Options
-
-```
---index <name>    Use a custom index name (default: index)
-```
-
-Note: use `INDEX_PATH` env var rather than `--index` — `INDEX_PATH` accepts a file path while `--index` only accepts a short name mapped to `~/.cache/qmd/`.
-
-## Typical Workflows
-
-### First-time setup for this vault
-```bash
-# Handled by the /setup skill:
-pnpm qmd:setup
-pnpm qmd:reindex
-```
-
-### After a bulk ingest session
-```bash
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd update
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd embed
-```
-
-### Research workflow
-```bash
-# Discover relevant pages
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<topic>"
-
-# Get a specific file
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd get wiki/distributed-systems.md
-
-# Get multiple related files
-INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd multi-get "wiki/kafka.md,wiki/distributed-systems.md" --md
-```