claude-second-brain 0.3.0 → 0.4.1

package/README.md

@@ -3,7 +3,7 @@
 
 **Your notes don't compound. This wiki does.**
 
-[![npm](https://img.shields.io/npm/v/claude-second-brain)](https://www.npmjs.com/package/claude-second-brain) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jessepinkman9900/claude-second-brain)
+[![npm](https://img.shields.io/npm/v/claude-second-brain)](https://www.npmjs.com/package/claude-second-brain) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jessepinkman9900/claude-second-brain)
 
 
 The fastest way to start your personal knowledge base powered by Obsidian, Claude Code, qmd, and GitHub.
@@ -19,7 +19,7 @@ One command gives you a fully wired knowledge system:
 - The scaffolded folder **is your Obsidian vault** — open it directly in [Obsidian](https://obsidian.md), with [obsidian-git](https://github.com/Vinzent03/obsidian-git) pre-configured for seamless sync
 - GitHub is the source of truth — version history, anywhere access, and a backup you control
 
-You've been reading papers, articles, and books for years. Drop a source in, run `/ingest`, and Claude reads it — extracts what matters, cross-links it to everything you already know, and files it. Ask a question six months later and get cited answers, not a list of files to re-read.
+You've been reading papers, articles, and books for years. Drop a source in, run `/brain-ingest`, and Claude reads it — extracts what matters, cross-links it to everything you already know, and files it. Ask a question six months later and get cited answers, not a list of files to re-read.
 
 > **Inspired by [Andrej Karpathy's approach to LLM-powered knowledge management](https://x.com/karpathy/status/2040470801506541998?s=20)** — share an "idea file" with an LLM agent and let it build and maintain your knowledge base.
 
@@ -58,12 +58,17 @@ Everything is pre-configured. You bring the sources.
 npx claude-second-brain
 ```
 
-Creates your vault (the folder itself is the Obsidian vault), installs `mise` + `bun`, and runs `git init` with an initial commit.
+The CLI will ask:
+- **Folder name** — where to create your vault (default: `my-brain`)
+- **qmd index path** — where to store the local search index (default: `~/.cache/qmd/index.sqlite`)
+- **GitHub repo** — optionally create a private repo and push automatically (requires `gh` CLI)
+
+Then scaffolds the vault, installs `mise` + `bun`, and runs `git init`.
 
 **Step 2 — Initialize inside Claude Code**
 
 ```bash
-cd my-wiki && claude
+cd my-brain && claude
 ```
 
 Then run:
@@ -74,27 +79,43 @@ Then run:
 
 Registers the qmd collections and generates local vector embeddings. First run downloads ~2GB of GGUF models — once.
 
-**Step 3 — Push to GitHub and open in Obsidian**
+**Step 3 — Open in Obsidian (and push to GitHub if not done)**
+
+**If you created a GitHub repo during setup**, it's already pushed — skip straight to opening in Obsidian.
+
+**If you skipped GitHub during setup**, connect it now:
 
 ```bash
-git remote add origin https://github.com/you/my-wiki.git
+git remote add origin https://github.com/you/my-brain.git
 git push -u origin main
 ```
 
-Open `my-wiki/` as a vault in Obsidian — the folder is already a valid Obsidian vault. The Git plugin is pre-configured — enable it and sync is automatic.
+Open `my-brain/` as a vault in Obsidian — the folder is already a valid Obsidian vault. The Git plugin is pre-configured — enable it and sync is automatic.
 
 ---
 
 ## Claude Code skills included
 
-The wiki ships with three slash commands that cover the full workflow. No manual prompting, no copy-pasting.
+The wiki ships with a set of slash commands that cover the full workflow. No manual prompting, no copy-pasting.
+
+### Daily workflow
 
-**`/ingest`** — Drop a file into `sources/articles/`, `sources/pdfs/`, or `sources/personal/`. Run `/ingest`. Claude summarizes the source, asks what matters most to you, creates a `wiki/sources/` page, updates or creates related topic pages, flags any contradictions with existing knowledge, and logs everything.
+**`/brain-ingest`** — Drop a file into `sources/articles/`, `sources/pdfs/`, or `sources/personal/`. Run `/brain-ingest`. Claude summarizes the source, asks what matters most to you, creates a `wiki/sources/` page, updates or creates related topic pages, flags any contradictions with existing knowledge, and logs everything.
 
-**`/query`** — Ask anything about what you know. Claude runs hybrid semantic search across the wiki, reads the most relevant pages, and writes an answer with inline `[[wiki/page]]` citations. If the answer synthesizes multiple pages in a novel way, it offers to file it as a permanent `wiki/qa/` entry.
+**`/brain-search`** — Ask anything about what you know. Claude runs hybrid semantic search across the wiki, reads the most relevant pages, and writes an answer with inline `[[wiki/page]]` citations. If the answer synthesizes multiple pages in a novel way, it offers to file it as a permanent `wiki/qa/` entry.
 
 **`/lint`** — Health-check the wiki. Surfaces orphan pages, broken links, unresolved contradictions, and data gaps. Reports findings and applies fixes where possible.
 
+### Maintenance
+
+**`/brain-refresh`** — Re-scan the vault for new or changed files and regenerate vector embeddings. Run after a bulk ingest session or manual edits. Pass `force` to re-embed every chunk (e.g. after changing the embedding model).
+
+**`/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. Use only when the current structure no longer fits how you search.
+
+### Setup
+
+**`/setup`** — First-time initialization. Registers the qmd collections and generates local vector embeddings. Run once after scaffolding.
+
 ---
 
 ## Access from anywhere
@@ -112,9 +133,64 @@ It's a plain GitHub repo. View and edit files directly in the browser at any tim
 
 ## How it works
 
+Sources flow in on the left, Claude synthesizes them into the wiki, qmd indexes every page into a local hybrid search index, and GitHub makes the whole vault editable from Obsidian and Claude Code on any device.
+
+```mermaid
+flowchart TB
+  subgraph Sources["sources/ — raw, immutable"]
+    direction LR
+    S1[articles/]
+    S2[pdfs/]
+    S3[personal/]
+  end
+
+  subgraph Skills["Claude Code skills"]
+    direction LR
+    I["/brain-ingest"]
+    Q["/brain-search"]
+    R["/brain-refresh"]
+  end
+
+  subgraph Wiki["wiki/ — cross-linked synthesis"]
+    direction LR
+    W1[overview.md]
+    W2[topic / entity pages]
+    W3[sources/]
+    W4[qa/]
+  end
+
+  QMD[("qmd.sqlite<br/>vector + BM25<br/>hybrid index")]
+
+  subgraph Remote["GitHub — source of truth"]
+    GH[private repo]
+  end
+
+  subgraph Read["Read / edit anywhere"]
+    direction LR
+    OB["Obsidian<br/>graph · backlinks · mobile"]
+    CC["Claude Code<br/>desktop + mobile"]
+  end
+
+  User((you))
+
+  Sources -->|read| I
+  I -->|write pages, cross-link,<br/>flag contradictions| Wiki
+  R -.->|chunk + embed<br/>changed files| QMD
+  Wiki -.->|indexed by| QMD
+  User -->|ask a question| Q
+  Q -->|hybrid search| QMD
+  QMD -->|top-k pages| Q
+  Q -->|cited answer| User
+  Wiki <-->|"obsidian-git<br/>auto commit / pull"| GH
+  GH --> OB
+  GH --> CC
+```
+
+### The ingest loop, zoomed in
+
 ```
 ┌─────────────────────┐        ┌─────────────────────┐        ┌─────────────────────┐
-│   Drop in a source  │        │  /ingest in Claude  │        │     Wiki grows      │
+│   Drop in a source  │        │ /brain-ingest       │        │     Wiki grows      │
 │                     │        │        Code         │        │                     │
 │  · article          │──────▶ │                     │──────▶ │  · cross-linked     │
 │  · PDF              │        │  reads + extracts   │        │    pages            │
@@ -125,7 +201,7 @@ It's a plain GitHub repo. View and edit files directly in the browser at any tim
                                                               └─────────────────────┘
 ```
 
-Query it anytime with `/query`. Get answers with inline `[[wiki/page]]` citations, not a list of files.
+Query it anytime with `/brain-search`. Get answers with inline `[[wiki/page]]` citations, not a list of files.
 
 ---
 
@@ -148,7 +224,7 @@ All pages cross-link with Obsidian `[[wikilinks]]`. Contradictions are flagged w
 ## Directory layout
 
 ```
-my-wiki/
+my-brain/
 ├── CLAUDE.md              ← The schema. Claude reads this every session.
 ├── sources/               ← Your raw inputs. Claude never modifies these.
 │   ├── articles/
@@ -165,9 +241,33 @@ my-wiki/
 
 ---
 
+## Installing and updating skills
+
+Skills are slash commands Claude Code loads from `.claude/skills/[name]/SKILL.md`. `/brain-ingest`, `/brain-search`, and `/brain-refresh` install globally to `~/.claude/skills/` during setup so they work in any Claude Code session. `/brain-rebuild`, `/lint`, `/setup`, and `/qmd-cli` live inside the vault at `.claude/skills/`.
+
+### Update the built-in wiki skills
+
+The wiki's own skills are scaffolded at creation time. To pull in improvements, use `npx skills` pointing to the template skills directory in this repo:
+
+```bash
+# Install or update all 7 wiki skills from the latest template
+npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills -a claude-code -y
+
+# Or update a specific skill
+npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills --skill brain-ingest -a claude-code -y
+```
+
+Once installed via `npx skills`, future updates are a single command:
+
+```bash
+npx skills update -a claude-code
+```
+
+---
+
 ## Roadmap
 
-- [ ] GitHub Actions for scheduled re-indexing
+- [ ] GitHub Actions to invoke `/brain-refresh` on a schedule
 - [ ] GitHub agentic workflows — auto-ingest on push, scheduled lint, auto-summary on new sources
 - [ ] More Claude Code skills (source discovery, topic clustering)
 

package/bin/create.js

@@ -1,14 +1,25 @@
 #!/usr/bin/env node
-import { cp, rename, access } from "fs/promises"
+import { cp, rename, access, readFile, writeFile, mkdir } from "fs/promises"
+import { readdirSync, readFileSync } from "fs"
 import { join, dirname } from "path"
 import { fileURLToPath } from "url"
 import { spawnSync } from "child_process"
-import { createInterface } from "readline/promises"
+import { homedir } from "os"
+import * as p from "@clack/prompts"
+import pc from "picocolors"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const TEMPLATE = join(__dirname, "../template")
+const { version } = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8"))
 
+// Non-interactive commands — output piped (won't corrupt spinner)
 function run(cmd, cwd) {
+  const result = spawnSync(cmd[0], cmd.slice(1), { cwd, stdio: "pipe" })
+  return result.status === 0
+}
+
+// Interactive commands (e.g. gh auth login) — must inherit stdio; call outside spinner
+function runInteractive(cmd, cwd) {
   const result = spawnSync(cmd[0], cmd.slice(1), { cwd, stdio: "inherit" })
   return result.status === 0
 }
@@ -18,14 +29,109 @@ function commandExists(cmd) {
   return result.status === 0
 }
 
+async function patchVault(targetDir, qmdPath, brainName) {
+  const filesToPatch = [
+    join(targetDir, "scripts/qmd/setup.ts"),
+    join(targetDir, "scripts/qmd/reindex.ts"),
+    join(targetDir, "CLAUDE.md"),
+  ]
+
+  const skillsDir = join(targetDir, ".claude/skills")
+  try {
+    for (const skill of readdirSync(skillsDir)) {
+      filesToPatch.push(join(skillsDir, skill, "SKILL.md"))
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err
+  }
+
+  await Promise.all(filesToPatch.map(async file => {
+    try {
+      let content = await readFile(file, "utf8")
+      content = content.replaceAll("__QMD_PATH__", qmdPath)
+      await writeFile(file, content, "utf8")
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err
+    }
+  }))
+
+  const readmePath = join(targetDir, "README.md")
+  try {
+    let readme = await readFile(readmePath, "utf8")
+    readme = readme.replaceAll("__BRAIN_NAME__", brainName)
+    await writeFile(readmePath, readme, "utf8")
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err
+  }
+}
+
+async function installGlobalSkills(qmdPath) {
+  const globalSkillsDir = join(homedir(), ".claude", "skills")
+
+  await Promise.all(["brain-ingest", "brain-search", "brain-refresh"].map(async skillName => {
+    const srcFile = join(TEMPLATE, ".claude/skills", skillName, "SKILL.md")
+    const destDir = join(globalSkillsDir, skillName)
+
+    let content = await readFile(srcFile, "utf8")
+    content = content.replaceAll("__QMD_PATH__", qmdPath)
+
+    await mkdir(destDir, { recursive: true })
+    await writeFile(join(destDir, "SKILL.md"), content, "utf8")
+  }))
+}
+
 async function main() {
-  let targetName = process.argv[2]
+  const isInteractive = Boolean(process.stdin.isTTY)
 
+  p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
+
+  let targetName = process.argv[2]
   if (!targetName) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout })
-    const answer = await rl.question("Where to create your wiki? (my-wiki) › ")
-    rl.close()
-    targetName = answer.trim() || "my-wiki"
+    const answer = await p.text({
+      message: "Where to create your brain?",
+      placeholder: "my-brain",
+      defaultValue: "my-brain",
+    })
+    if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
+    targetName = answer
+  }
+
+  const defaultQmdPath = join(
+    process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
+    "qmd", "index.sqlite"
+  )
+  let qmdPath
+  if (isInteractive) {
+    const answer = await p.text({
+      message: "Where to store the qmd index?",
+      placeholder: defaultQmdPath,
+      defaultValue: defaultQmdPath,
+    })
+    if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
+    qmdPath = answer
+  } else {
+    qmdPath = defaultQmdPath
+  }
+
+  let createGhRepo = false
+  let ghRepoName = null
+  if (isInteractive) {
+    const confirm = await p.confirm({
+      message: "Create a private GitHub repo?",
+      initialValue: false,
+    })
+    if (p.isCancel(confirm)) { p.cancel("Setup cancelled."); process.exit(0) }
+    createGhRepo = confirm
+
+    if (createGhRepo) {
+      const answer = await p.text({
+        message: "GitHub repo name?",
+        placeholder: targetName,
+        defaultValue: targetName,
+      })
+      if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
+      ghRepoName = answer
+    }
   }
 
   const targetDir = join(process.cwd(), targetName)
@@ -33,17 +139,17 @@ async function main() {
   // Fail fast if target already exists
   try {
     await access(targetDir)
-    console.error(`\nError: "${targetName}" already exists. Choose a different name or delete it first.`)
+    p.cancel(`"${targetName}" already exists. Choose a different name or delete it first.`)
     process.exit(1)
   } catch {
     // Directory doesn't exist — good to go
   }
 
-  // 1. Scaffold
-  console.log(`\nCreating ${targetName}...`)
-  await cp(TEMPLATE, targetDir, { recursive: true })
+  const spin = p.spinner()
 
-  // npm strips .gitignore from published packages — rename the template copy back
+  // Scaffold
+  spin.start("Scaffolding project")
+  await cp(TEMPLATE, targetDir, { recursive: true })
   try {
     await rename(
       join(targetDir, ".gitignore.template"),
@@ -52,49 +158,87 @@ async function main() {
   } catch {
     // .gitignore.template not present (e.g. running locally where npm didn't strip it)
   }
+  spin.stop(`${targetName}/ created`)
 
-  console.log(`✓ Created ${targetName}/`)
+  // Patch vault files with chosen qmd path
+  spin.start("Configuring qmd index path")
+  await patchVault(targetDir, qmdPath, targetName)
+  spin.stop(`qmd index → ${pc.dim(qmdPath)}`)
 
-  // 2. Install mise if not present
+  // Install mise if not present
   if (!commandExists("mise")) {
-    console.log("\nInstalling mise...")
+    spin.start("Installing mise")
     const ok = run(["npm", "install", "-g", "@jdxcode/mise"])
-    if (ok) {
-      console.log("✓ Installed mise")
-    } else {
-      console.error("  Failed to install mise — install manually: npm install -g @jdxcode/mise")
-    }
+    if (ok) spin.stop("mise installed")
+    else spin.stop("Failed to install mise — run: npm install -g @jdxcode/mise", 1)
   }
 
-  // 3. Run mise install inside the new vault to install bun
-  console.log("\nInstalling bun via mise...")
+  // Run mise install inside the new vault to install bun
+  spin.start("Installing bun via mise")
+  run(["mise", "trust"], targetDir)
   const miseOk = run(["mise", "install"], targetDir)
-  if (miseOk) {
-    console.log("✓ Installed bun")
-  } else {
-    console.error("  mise install failed — run it manually inside your vault")
-  }
+  if (miseOk) spin.stop("bun installed")
+  else spin.stop("mise install failed — run it manually inside your vault", 1)
 
-  // 4. Git init
-  console.log("\nInitializing git repo...")
+  // Git init
+  spin.start("Initializing git repo")
   const gitOk = run(["git", "init"], targetDir)
   if (gitOk) {
     run(["git", "add", "."], targetDir)
     run(["git", "commit", "-m", "initial commit"], targetDir)
-    console.log("✓ Git repo initialized")
+    spin.stop("git repo initialized")
   } else {
-    console.error("  git init failed — run it manually inside your vault")
+    spin.stop("git init failed — run it manually inside your vault", 1)
+  }
+
+  // GitHub repo (optional)
+  if (createGhRepo) {
+    if (!commandExists("gh")) {
+      p.log.warn(`gh CLI not found — install from https://cli.github.com, then run:\n  gh repo create ${ghRepoName} --private --source=. --remote=origin --push`)
+    } else {
+      const authCheck = spawnSync("gh", ["auth", "status"], { stdio: "pipe" })
+      let loggedIn = authCheck.status === 0
+
+      if (!loggedIn) {
+        p.log.info("Not logged in to GitHub. Starting login...")
+        loggedIn = runInteractive(["gh", "auth", "login"], targetDir)
+      }
+
+      if (loggedIn) {
+        spin.start(`Creating GitHub repo ${pc.dim(ghRepoName)}`)
+        const ghOk = run(
+          ["gh", "repo", "create", ghRepoName, "--private", "--source=.", "--remote=origin", "--push"],
+          targetDir
+        )
+        if (ghOk) {
+          spin.stop(`GitHub repo created (private): ${pc.cyan(ghRepoName)}`)
+        } else {
+          spin.stop(`gh repo create failed — run: gh repo create ${ghRepoName} --private --source=. --remote=origin --push`, 1)
+        }
+      }
+    }
   }
 
-  console.log(`\n✓ Done! Your wiki is ready.\n`)
-  console.log("Next steps:")
-  console.log(`  cd ${targetName}`)
-  console.log("  claude                      # open Claude Code, then run /setup")
-  console.log("  git remote add origin <url> # connect to GitHub for sync + Obsidian Mobile")
-  console.log("  git push -u origin main")
+  // Install global skills
+  spin.start("Installing global Claude skills")
+  await installGlobalSkills(qmdPath)
+  spin.stop("Global skills installed")
+
+  // Next steps
+  const nextSteps = [
+    `${pc.cyan(`cd ${targetName}`)}`,
+    `${pc.cyan("claude")}          open Claude Code, then run ${pc.bold("/setup")}`,
+    ...(!createGhRepo ? [
+      `${pc.cyan("git remote add origin <url>")}  connect to GitHub for sync`,
+      `${pc.cyan("git push -u origin main")}`,
+    ] : []),
+  ].join("\n")
+
+  p.note(nextSteps, "Next steps")
+  p.outro("Happy knowledge building!")
 }
 
 main().catch(err => {
-  console.error(err.message)
+  p.cancel(err.message)
   process.exit(1)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-second-brain",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Scaffold an LLM-maintained Obsidian knowledge wiki",
   "type": "module",
   "bin": {
@@ -14,6 +14,10 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "picocolors": "^1.1.1"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",

package/template/.claude/skills/{ingest → brain-ingest}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: ingest
-description: "Ingest a new source into the wiki. Reads the source, summarizes it, creates a wiki/sources/ page, updates affected topic and entity pages, flags contradictions, and logs the activity. Trigger phrases: /ingest, ingest [file or URL], add this source, read and file this, process this article/paper/note."
+name: brain-ingest
+description: "Ingest a new source into the wiki. Reads the source, summarizes it, creates a wiki/sources/ page, updates affected topic and entity pages, flags contradictions, and logs the activity. Trigger phrases: /brain-ingest, ingest [file or URL], add this source, read and file this, process this article/paper/note."
 argument-hint: "File path (e.g. sources/articles/my-article.md), URL, or leave blank if source is pasted in chat"
 ---
 
-# Ingest
+# Brain Ingest
 
 Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 
@@ -35,7 +35,7 @@ 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.sqlite bunx @tobilu/qmd query -c wiki "<source topic and key claims>"`
+- Run: `INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "<source topic and key claims>"`
 - Also Glob `wiki/*.md` and `wiki/sources/*.md` to catch anything qmd missed
 - List all pages to create or update before proceeding
 

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

@@ -0,0 +1,119 @@
+---
+name: brain-rebuild
+description: "Redesign the qmd schema for this vault — analyze the current wiki, recommend a new set of collections and contexts, update scripts/qmd/setup.ts, then tear down and rebuild the index from scratch. Destructive. Trigger phrases: /brain-rebuild, rebuild the brain, restructure qmd, redesign collections, redo contexts, recompute schema."
+argument-hint: "Optional: a hint about the desired structure (e.g. 'split wiki by domain', 'add a separate collection for qa pages')"
+---
+
+# Brain Rebuild
+
+Redesigns the qmd schema based on what the wiki actually contains today, then rebuilds the index from scratch. **Destructive** — wipes existing collections/contexts and their embeddings. Always get explicit user approval before applying changes.
+
+## When to Use
+
+- The wiki has grown and the current single `wiki` collection no longer matches how the user searches
+- The user wants finer-grained contexts (e.g. distinct context descriptions per sub-folder)
+- After significant reorganization of `wiki/` or `sources/` folder structure
+- Never as a routine refresh — for that, use `/brain-refresh`
+
+## Procedure
+
+All commands run from the vault root.
+
+### Step 1 — Survey the current state
+
+- Read `scripts/qmd/setup.ts` to see the current collections and contexts
+- Read `CLAUDE.md` to understand the documented schema and any references to collection names
+- List current state from qmd:
+  ```bash
+  INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
+  INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
+  INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
+  ```
+
+### Step 2 — Analyze the wiki
+
+- Glob `wiki/**/*.md` and `sources/**/*.md`
+- Read enough pages (especially `wiki/index.md` and `wiki/overview.md`) to understand actual topic clusters, page-type distribution, and folder structure
+- Identify natural groupings: by domain (e.g. ml, distributed-systems, finance), by page type (topics vs entities vs qa), by source provenance, etc.
+
+### Step 3 — Propose a new schema
+
+Produce a recommendation that includes:
+
+- **Collections** — name, root path (relative to vault), file glob pattern. Justify each split.
+- **Contexts** — global context, plus per-collection and per-subpath context descriptions. Each context should be a one-sentence description that helps a future search disambiguate between similar pages.
+- **Migration impact** — what changes for `/brain-ingest`, `/brain-search`, `/lint`, and `CLAUDE.md` (e.g. if collection name `wiki` becomes `wiki-topics`, all `-c wiki` invocations break)
+
+Present the recommendation as a clear diff against the current schema. Do not modify any files yet.
+
+### Step 4 — Get explicit approval
+
+Ask the user: "Apply this schema? This will drop existing collections and their embeddings, then rebuild from scratch. Re-embedding the full wiki may take significant time and download GGUF models if not cached."
+
+Do not proceed without an explicit yes.
+
+### Step 5 — Update `scripts/qmd/setup.ts`
+
+Edit `scripts/qmd/setup.ts` to reflect the new schema:
+
+- Update the `ensureCollection` calls (add, remove, or rename)
+- Update `setGlobalContext` and the `addContext` calls
+- Leave the `DB` constant alone — its value was substituted at scaffold time and must not change
+- Keep the script idempotent
+
+### Step 6 — Update related references
+
+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
+- Use Grep to find any remaining stale references before moving on
+
+### Step 7 — Tear down the old schema
+
+For each existing collection that no longer fits the new schema:
+
+```bash
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection remove <old-name>
+```
+
+For each obsolete context:
+
+```bash
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context rm <path>
+```
+
+### Step 8 — Register the new schema
+
+Run:
+```bash
+bun scripts/qmd/setup.ts
+```
+
+This is idempotent — collections that already exist (e.g. ones you kept) are skipped; new ones are added; contexts are upserted.
+
+### Step 9 — Rebuild embeddings from scratch
+
+Run:
+```bash
+bun scripts/qmd/reindex.ts
+```
+
+This indexes all files under the new collections and generates fresh embeddings.
+
+### Step 10 — Verify and report
+
+```bash
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
+INDEX_PATH=__QMD_PATH__ bunx @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).
+
+## Hard Rules
+
+- Never apply schema changes without explicit user approval at Step 4
+- Never delete a collection without first showing the user what will be dropped
+- Always update `CLAUDE.md` and skill files in lockstep with collection renames — stale `-c <name>` references will silently break `/brain-search`
+- Do not touch `wiki/`, `sources/`, or any user content — this skill changes the index schema, not the data

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

@@ -0,0 +1,63 @@
+---
+name: brain-refresh
+description: "Refresh the qmd index for this vault — re-scans all collections for new/changed files and regenerates vector embeddings. Use after a bulk ingest session, after manual file edits, or whenever search feels stale. Trigger phrases: /brain-refresh, refresh the brain, refresh embeddings, re-embed wiki, update qmd index, refresh search index."
+argument-hint: "Optional: 'force' to force re-embedding of every chunk (slow, useful after embedding model changes)"
+---
+
+# Brain Refresh
+
+Refreshes the qmd index so search reflects the current state of the vault. Wraps `bun scripts/qmd/reindex.ts` (incremental) and the qmd CLI's force-embed flag.
+
+## When to Use
+
+- After a `/brain-ingest` session (or several) — batch the refresh, don't run after every file edit
+- After manual edits to `wiki/` or `sources/` files
+- When `/brain-search` results feel stale or miss recently added content
+- After upgrading `@tobilu/qmd` or changing the embedding model — use `force` mode
+
+## Procedure
+
+All commands run from the vault root.
+
+### Default — Incremental Refresh
+
+Run:
+```bash
+bun scripts/qmd/reindex.ts
+```
+
+This script does two things:
+1. **Update** — scans collections for new, changed, or deleted files and updates the index
+2. **Embed** — generates vector embeddings for any chunks that need them
+
+Only chunks that changed get re-embedded, so this is fast on subsequent runs.
+
+### Force Mode (`force` argument)
+
+When the user passes `force`, re-embed **every** chunk — not just the changed ones. Use after embedding-model changes or if embeddings appear corrupted.
+
+```bash
+# Step 1 — update the file index first
+bun scripts/qmd/reindex.ts
+
+# Step 2 — force re-embed everything
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed -f
+```
+
+Force mode is slow — confirm with the user before proceeding if the wiki is large.
+
+## Verify
+
+After refresh, confirm with:
+
+```bash
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/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.
+
+## Notes
+
+- 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`

package/template/.claude/skills/{query → brain-search}/SKILL.md

@@ -1,17 +1,17 @@
 ---
-name: query
-description: "Query the wiki to answer a question. Searches semantically, synthesizes an answer with inline citations, and optionally files the answer as a permanent Q&A page. Trigger phrases: /query, what do I know about, search the wiki, find everything about, what does the wiki say about."
+name: brain-search
+description: "Query the wiki to answer a question. Searches semantically, synthesizes an answer with inline citations, and optionally files the answer as a permanent Q&A page. Trigger phrases: /brain-search, what do I know about, search the wiki, find everything about, what does the wiki say about."
 argument-hint: "The question or topic to query (e.g. 'what do I know about transformer architecture?')"
 ---
 
-# Query
+# Brain Search
 
 Runs the 4-step query workflow defined in CLAUDE.md. Answers come with inline `[[wiki/page]]` citations — not a list of files.
 
 ## Workflow
 
 **Step 1 — Search the wiki**
-- Run hybrid search: `INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query -c wiki "<question>"`
+- Run hybrid search: `INDEX_PATH=__QMD_PATH__ bunx @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
 

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

@@ -10,10 +10,10 @@ Local semantic document index with hybrid search (BM25 + vector), collection man
 
 ## Vault DB
 
-This vault keeps its index at `qmd.sqlite` in the vault root (gitignored). All CLI commands **must** prefix with `INDEX_PATH=qmd.sqlite` (relative path works when running from the vault root, which is always the case here):
+This vault keeps its index at `__QMD_PATH__`. All CLI commands **must** prefix with `INDEX_PATH=__QMD_PATH__`:
 
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query -c wiki "..."
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "..."
 ```
 
 The scripts `bun scripts/qmd/setup.ts` and `bun scripts/qmd/reindex.ts` write to this same file. The CLI must match.
@@ -24,40 +24,40 @@ The scripts `bun scripts/qmd/setup.ts` and `bun scripts/qmd/reindex.ts` write to
 
 ```bash
 # Create/index a collection
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection add <path> --name <name> --mask <glob-pattern>
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection add <path> --name <name> --mask <glob-pattern>
 # e.g.:
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection add wiki --name wiki --mask "**/*.md"
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection add wiki --name wiki --mask "**/*.md"
 
 # List all collections with details
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection list
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
 
 # Remove a collection
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection remove <name>
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection remove <name>
 
 # Rename a collection
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection rename <old-name> <new-name>
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection rename <old-name> <new-name>
 ```
 
 ## Listing Files
 
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd ls
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd ls [collection[/path]]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd ls
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd ls [collection[/path]]
 ```
 
 ## Context
 
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd context add [path] "description text"
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd context list
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd context rm <path>
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context add [path] "description text"
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context rm <path>
 ```
 
 ## Retrieving Documents
 
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd get <file>[:line] [-l N] [--from N]
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd multi-get <pattern> [-l N] [--max-bytes N]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd get <file>[:line] [-l N] [--from N]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd multi-get <pattern> [-l N] [--max-bytes N]
 ```
 
 **Multi-get format flags:** `--json`, `--csv`, `--md`, `--xml`, `--files`
@@ -66,16 +66,16 @@ INDEX_PATH=qmd.sqlite bunx @tobilu/qmd multi-get <pattern> [-l N] [--max-bytes N
 
 ```bash
 # Show index status and collections
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd status
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
 
 # Re-index all collections
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd update [--pull]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd update [--pull]
 
 # Create vector embeddings (900 tokens/chunk, 15% overlap)
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd embed [-f]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed [-f]
 
 # Remove cache and orphaned data, vacuum DB
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd cleanup
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd cleanup
 ```
 
 > After bulk ingest sessions, run `update` then `embed` to keep the index fresh.
@@ -108,28 +108,28 @@ INDEX_PATH=qmd.sqlite bunx @tobilu/qmd cleanup
 
 ```bash
 # Hybrid search across all collections
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query "distributed systems consensus"
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query "distributed systems consensus"
 
 # Search only the wiki collection, JSON output
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query -c wiki "transformer architecture" --json
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "transformer architecture" --json
 
 # Keyword-only search, top 10, markdown output
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd search -c wiki "kafka" -n 10 --md
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd search -c wiki "kafka" -n 10 --md
 
 # Vector search with full documents
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd vsearch "attention mechanism" --full
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd vsearch "attention mechanism" --full
 
 # Filter by score threshold
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query "machine learning" --all --min-score 0.7
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query "machine learning" --all --min-score 0.7
 ```
 
 ## MCP Server
 
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd mcp
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd mcp --http [--port N]
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd mcp --http --daemon
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd mcp stop
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd mcp
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd mcp --http [--port N]
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd mcp --http --daemon
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd mcp stop
 ```
 
 ## Global Options
@@ -151,18 +151,18 @@ bun scripts/qmd/reindex.ts
 
 ### After a bulk ingest session
 ```bash
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd update
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd embed
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd update
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed
 ```
 
 ### Research workflow
 ```bash
 # Discover relevant pages
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query -c wiki "<topic>"
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "<topic>"
 
 # Get a specific file
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd get wiki/distributed-systems.md
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd get wiki/distributed-systems.md
 
 # Get multiple related files
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd multi-get "wiki/kafka.md,wiki/distributed-systems.md" --md
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd multi-get "wiki/kafka.md,wiki/distributed-systems.md" --md
 ```

package/template/.claude/skills/setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: "Initialize this obsidian-agent-memory vault. Registers qmd collections and generates vector embeddings. Use when: setting up for the first time, re-registering collections, or re-indexing after a bulk ingest session. Trigger phrases: /setup, setup vault, initialize collections, reindex, register qmd."
+description: "Initialize this claude-second-brain vault. Registers qmd collections and generates vector embeddings. Use when: setting up for the first time, re-registering collections, or re-indexing after a bulk ingest session. Trigger phrases: /setup, setup vault, initialize collections, reindex, register qmd."
 argument-hint: "Optional: 'reindex' to skip registration and only re-index files"
 ---
 
@@ -24,7 +24,7 @@ Run:
 bun scripts/qmd/setup.ts
 ```
 
-Registers the four qmd collections (`wiki`, `raw-sources`, `human`, `daily-notes`) and their path-level context descriptions. Idempotent — safe to re-run.
+Registers the two core qmd collections (`wiki`, `raw-sources`) and their path-level context descriptions. Idempotent — safe to re-run.
 
 **Step 2 — Index files and generate embeddings**
 
@@ -49,17 +49,17 @@ Do **not** re-run after every single file edit — batch it after a session.
 Run these three commands to confirm everything is working:
 
 ```bash
-# List registered collections (expect: wiki, raw-sources, human, daily-notes)
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd collection list
+# List registered collections (expect: wiki, raw-sources)
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
 
 # List registered contexts
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd context list
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
 
 # Show index status and embedding counts
-INDEX_PATH=qmd.sqlite bunx @tobilu/qmd status
+INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
 ```
 
-All four collections should appear in `collection list`. `status` should show non-zero document and embedding counts — if embeddings are 0, re-run step 2.
+Both collections should appear in `collection list`. `status` should show non-zero document and embedding counts — if embeddings are 0, re-run step 2.
 
 ## Notes
 - `bun` is managed via `mise` — ensure `mise install` has been run before setup

package/template/.gitignore.template

@@ -21,8 +21,8 @@ coverage
 
 # logs
 logs
-_.log
-report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+*.log
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
 
 # dotenv environment variable files
 .env

package/template/CLAUDE.md

@@ -51,6 +51,9 @@ Summary of one ingested source. Slug is kebab-case derived from the title. One p
 ### `qa` — `wiki/qa/[slug].md`
 A filed answer to a notable query. Created when an answer synthesizes multiple pages in a way worth preserving.
 
+### `admin` — `wiki/index.md`, `wiki/log.md`
+Special system/administrative pages. Not synthesis content. There are exactly two: `index.md` (master index) and `log.md` (activity log).
+
 ---
 
 ## Frontmatter Format
@@ -59,7 +62,7 @@ All wiki pages use this YAML frontmatter:
 
 ```yaml
 ---
-type: overview | topic | entity | source-summary | qa
+type: overview | topic | entity | source-summary | qa | admin
 tags: [tag1, tag2]
 sources: ["[[wiki/sources/source-slug]]"]
 related: ["[[wiki/related-page]]"]
@@ -67,7 +70,7 @@ updated: YYYY-MM-DD
 ---
 ```
 
-- `type`: Required. One of the five page types above.
+- `type`: Required. One of the six page types above.
 - `tags`: Optional. Lowercase, hyphenated. Topics for the Obsidian tag pane.
 - `sources`: Links to the `wiki/sources/` pages that informed this page.
 - `related`: Links to other wiki pages directly relevant to this one.
@@ -108,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 `bunx @tobilu/qmd query -c wiki "<source topic and key claims>"` to surface related existing wiki pages.
+- Run `INDEX_PATH=__QMD_PATH__ bunx @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.
 
@@ -139,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 `bunx @tobilu/qmd query -c wiki "<question>"` to surface semantically relevant pages.
+- Run `INDEX_PATH=__QMD_PATH__ bunx @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.
 
@@ -209,15 +212,15 @@ N issues found, N fixed. [Brief summary of notable findings.]
 ## Search Tool
 
 This vault uses **qmd** (`bunx @tobilu/qmd`) for local semantic and full-text search.
-Collections and contexts are registered via `bun scripts/qmd/setup.ts` and stored in `qmd.sqlite` at the vault root (gitignored).
+Collections and contexts are registered via `bun scripts/qmd/setup.ts` and stored at `__QMD_PATH__` (gitignored).
 
 Key commands:
 
 | Command | Use |
 |---------|-----|
-| `INDEX_PATH=qmd.sqlite bunx @tobilu/qmd query -c wiki "<question>"` | Hybrid search — best for topic discovery |
-| `INDEX_PATH=qmd.sqlite bunx @tobilu/qmd search -c wiki "<terms>"` | Fast keyword search (BM25, no LLM) |
-| `INDEX_PATH=qmd.sqlite bunx @tobilu/qmd vsearch -c wiki "<question>"` | Pure vector/semantic search |
+| `INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "<question>"` | Hybrid search — best for topic discovery |
+| `INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd search -c wiki "<terms>"` | Fast keyword search (BM25, no LLM) |
+| `INDEX_PATH=__QMD_PATH__ bunx @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

@@ -1,4 +1,6 @@
-# claude-second-brain
+# __BRAIN_NAME__
+
+built using [claude-second-brain](https://github.com/jessepinkman9900/claude-second-brain)
 
 **Your notes don't compound. This wiki does.**
 
@@ -32,12 +34,81 @@ Registers the qmd collections and generates local vector embeddings. First run d
 
 ## Your Claude Code skills
 
-**`/ingest`** — Add a file to `sources/articles/`, `sources/pdfs/`, or `sources/personal/`, then run `/ingest`. Claude summarizes the source, asks what aspects matter most, updates related wiki pages, flags contradictions, and logs everything.
+### Daily workflow
+
+**`/brain-ingest`** — Add a file to `sources/articles/`, `sources/pdfs/`, or `sources/personal/`, then run `/brain-ingest`. Claude summarizes the source, asks what aspects matter most, updates related wiki pages, flags contradictions, and logs everything.
 
-**`/query`** — Ask anything: `what do I know about [topic]?` Claude searches the wiki semantically and returns a cited answer. If it synthesizes multiple pages in a useful way, it offers to file it as a permanent `wiki/qa/` entry.
+**`/brain-search`** — Ask anything: `what do I know about [topic]?` Claude searches the wiki semantically and returns a cited answer. If it synthesizes multiple pages in a useful way, it offers to file it as a permanent `wiki/qa/` entry.
 
 **`/lint`** — Health-check the wiki. Finds orphan pages, broken links, unresolved contradictions, and data gaps. Reports findings and fixes what it can.
 
+### Maintenance
+
+**`/brain-refresh`** — Re-scan the vault for new or changed files and regenerate vector embeddings. Run after a bulk ingest session or manual edits. Pass `force` to re-embed every chunk.
+
+**`/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
+
+Sources flow in on the left, Claude synthesizes them into the wiki, qmd indexes every page into a local hybrid search index, and GitHub makes the whole vault editable from Obsidian and Claude Code on any device.
+
+```mermaid
+flowchart TB
+  subgraph Sources["sources/ — raw, immutable"]
+    direction LR
+    S1[articles/]
+    S2[pdfs/]
+    S3[personal/]
+  end
+
+  subgraph Skills["Claude Code skills"]
+    direction LR
+    I["/brain-ingest"]
+    Q["/brain-search"]
+    R["/brain-refresh"]
+  end
+
+  subgraph Wiki["wiki/ — cross-linked synthesis"]
+    direction LR
+    W1[overview.md]
+    W2[topic / entity pages]
+    W3[sources/]
+    W4[qa/]
+  end
+
+  QMD[("qmd.sqlite<br/>vector + BM25<br/>hybrid index")]
+
+  subgraph Remote["GitHub — source of truth"]
+    GH[private repo]
+  end
+
+  subgraph Read["Read / edit anywhere"]
+    direction LR
+    OB["Obsidian<br/>graph · backlinks · mobile"]
+    CC["Claude Code<br/>desktop + mobile"]
+  end
+
+  User((you))
+
+  Sources -->|read| I
+  I -->|write pages, cross-link,<br/>flag contradictions| Wiki
+  R -.->|chunk + embed<br/>changed files| QMD
+  Wiki -.->|indexed by| QMD
+  User -->|ask a question| Q
+  Q -->|hybrid search| QMD
+  QMD -->|top-k pages| Q
+  Q -->|cited answer| User
+  Wiki <-->|"obsidian-git<br/>auto commit / pull"| GH
+  GH --> OB
+  GH --> CC
+```
+
 ---
 
 ## Obsidian Mobile
@@ -82,15 +153,39 @@ 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.
+
+### Update built-in wiki skills
+
+Pull the latest skills from the upstream template:
+
+```bash
+# Install or update all 7 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
+npx skills add https://github.com/jessepinkman9900/claude-second-brain/tree/main/template/.claude/skills --skill brain-ingest -a claude-code -y
+```
+
+Once installed via `npx skills`, future updates are a single command:
+
+```bash
+npx skills update -a claude-code
+```
+
+---
+
 ## Re-indexing
 
 After a bulk ingest session, re-index to keep search current:
 
-```bash
-bun scripts/qmd/reindex.ts
+```
+/brain-refresh
 ```
 
-Or run `/setup` again inside Claude Code.
+This wraps `bun scripts/qmd/reindex.ts` — you can also run that command directly if you're not inside Claude Code. Pass `force` to `/brain-refresh` to re-embed every chunk (e.g. after changing the embedding model).
 
 ---
 

package/template/scripts/qmd/reindex.ts

@@ -7,14 +7,12 @@
  *   bun scripts/qmd/reindex.ts
  *
  * Suitable as a cronjob:
- *   0 * * * * cd /home/user/obsidian-agent-memory && bun scripts/qmd/reindex.ts
+ *   0 * * * * cd /home/user/my-brain && bun scripts/qmd/reindex.ts
  */
 
 import { createStore } from "@tobilu/qmd"
-import { join } from "path"
 
-const VAULT = join(import.meta.dir, "../..")
-const DB = join(VAULT, "qmd.sqlite")
+const DB = "__QMD_PATH__"
 
 const store = await createStore({ dbPath: DB })
 

package/template/scripts/qmd/setup.ts

@@ -13,7 +13,7 @@ import { createStore } from "@tobilu/qmd"
 import { join } from "path"
 
 const VAULT = join(import.meta.dir, "../..")
-const DB = join(VAULT, "qmd.sqlite")
+const DB = "__QMD_PATH__"
 
 const store = await createStore({ dbPath: DB })
 
@@ -33,8 +33,6 @@ async function ensureCollection(name: string, relPath: string, pattern: string)
 console.log("Collections:")
 await ensureCollection("wiki",        "wiki",        "**/*.md")
 await ensureCollection("raw-sources", "sources",     "**/*.md")
-await ensureCollection("human",       "human",       "**/*.md")
-await ensureCollection("daily-notes", "daily-notes", "**/*.md")
 
 // --- Global context ---
 console.log("\nContexts:")
@@ -55,13 +53,4 @@ await store.addContext("raw-sources", "/articles", "Web articles saved as markdo
 await store.addContext("raw-sources", "/pdfs",     "PDF files or their extracted text")
 await store.addContext("raw-sources", "/personal", "Personal notes flagged for wiki ingestion")
 
-// human/
-await store.addContext("human", "",             "User's personal notes — not Claude-maintained; covers work, social life, investing, hobbies, and more")
-await store.addContext("human", "/ideas",       "Brainstorming and exploratory ideas")
-await store.addContext("human", "/job-hunt",    "Job search notes and preparation")
-await store.addContext("human", "/misc",        "Miscellaneous personal notes")
-
-// daily-notes/
-await store.addContext("daily-notes", "", "User's daily and weekly journal entries, dated by year and week number")
-
 console.log("\nSetup complete. Run: bun scripts/qmd/reindex.ts")

package/template/wiki/index.md

@@ -1,5 +1,5 @@
 ---
-type: overview
+type: admin
 tags: []
 updated: 2026-01-01
 ---
@@ -8,7 +8,7 @@ updated: 2026-01-01
 
 ## Sources Ingested
 
-_No sources ingested yet. Run `/ingest` to add your first source._
+_No sources ingested yet. Run `/brain-ingest` to add your first source._
 
 ## Topic Pages
 

package/template/wiki/log.md

@@ -1,5 +1,5 @@
 ---
-type: overview
+type: admin
 tags: []
 updated: 2026-01-01
 ---