claude-second-brain 0.6.0 → 1.0.0

package/bin/create.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { cp, rename, access, readFile, writeFile, mkdir } from "fs/promises"
-import { readdirSync, readFileSync } from "fs"
+import { cp, rename, access, readFile, writeFile, mkdir, rm } from "fs/promises"
+import { readFileSync } from "fs"
 import { join, dirname } from "path"
 import { fileURLToPath } from "url"
 import { spawnSync } from "child_process"
@@ -11,6 +11,8 @@ 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"))
+const CSB_ROOT   = join(homedir(), ".claude-second-brain")
+const CSB_CONFIG = join(CSB_ROOT, "config.toml")
 
 // Non-interactive commands — output piped (won't corrupt spinner)
 function run(cmd, cwd) {
@@ -18,6 +20,25 @@ function run(cmd, cwd) {
   return result.status === 0
 }
 
+// Like `run`, but returns captured stdout/stderr so callers can surface the
+// real failure to the user instead of a generic "failed" message.
+function runCapture(cmd, cwd) {
+  const result = spawnSync(cmd[0], cmd.slice(1), { cwd, stdio: "pipe", encoding: "utf8" })
+  return {
+    ok: result.status === 0,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  }
+}
+
+// Pick the most informative tail of a child process's output for an error message.
+function tailForError({ stdout, stderr }, lines = 10) {
+  const source = (stderr && stderr.trim()) ? stderr : stdout
+  const trimmed = (source || "").trim()
+  if (!trimmed) return ""
+  return trimmed.split("\n").slice(-lines).join("\n")
+}
+
 // 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" })
@@ -29,32 +50,9 @@ 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
-    }
-  }))
-
+async function patchVault(targetDir, brainName) {
+  // Only __BRAIN_NAME__ is substituted — all path resolution happens at
+  // invocation time via the `claude-second-brain` CLI subcommands.
   const readmePath = join(targetDir, "README.md")
   try {
     let readme = await readFile(readmePath, "utf8")
@@ -246,56 +244,502 @@ async function setupCloudflareRemote({ targetDir, repoName, namespace, spin }) {
   return { repoToken, remote }
 }
 
-async function installGlobalSkills(qmdPath) {
-  const globalSkillsDir = join(homedir(), ".claude", "skills")
+function parseGithubRepo(url) {
+  if (!url) return null
+  const m = url.match(/github\.com[:/]([^/\s]+)\/([^/\s.]+)/)
+  return m ? `${m[1]}/${m[2]}` : null
+}
+
+function parseCloudflareArtifact(url) {
+  if (!url || !/artifacts\.cloudflare/.test(url)) return null
+  const explicit = url.match(/namespaces\/([^/]+)\/repos\/([^/.]+)/)
+  if (explicit) return { namespace: explicit[1], repo: explicit[2] }
+  const parts = url.replace(/\.git$/, "").split("/").filter(Boolean)
+  if (parts.length >= 2) return { namespace: parts[parts.length - 2], repo: parts[parts.length - 1] }
+  return null
+}
 
-  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)
+async function resolveCloudflareToken() {
+  if (process.env.CLOUDFLARE_API_TOKEN) {
+    return { token: process.env.CLOUDFLARE_API_TOKEN, source: "CLOUDFLARE_API_TOKEN env" }
+  }
+  const wrangler = resolveWranglerCli()
+  const tokenResult = spawnSync(wrangler.cmd, [...wrangler.prefix, "auth", "token"], { stdio: "pipe" })
+  if (tokenResult.status !== 0) return null
+  const token = extractBearerToken(tokenResult.stdout?.toString() || "")
+  if (!token || !/^[\x20-\x7E]+$/.test(token)) return null
+  return { token, source: "wrangler auth token" }
+}
+
+function deleteGithubRepo(slug) {
+  if (!commandExists("gh")) return { ok: false, error: "gh CLI not installed" }
+  const r = spawnSync("gh", ["repo", "delete", slug, "--yes"], { stdio: "pipe" })
+  if (r.status !== 0) {
+    const stderr = r.stderr?.toString().trim() || `exit ${r.status}`
+    return { ok: false, error: truncate(stderr, 200) }
+  }
+  return { ok: true }
+}
+
+async function deleteCloudflareArtifact({ namespace, repo }) {
+  const auth = await resolveCloudflareToken()
+  if (!auth) return { ok: false, error: "no Cloudflare API token (set CLOUDFLARE_API_TOKEN or run `wrangler login`)" }
+  try {
+    const res = await fetch(`https://artifacts.cloudflare.net/v1/api/namespaces/${namespace}/repos/${repo}`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${auth.token}` },
+    })
+    if (!res.ok) {
+      const body = await res.text()
+      return { ok: false, error: `HTTP ${res.status}: ${truncate(body, 200)}` }
+    }
+    return { ok: true }
+  } catch (err) {
+    return { ok: false, error: err.message }
+  }
+}
+
+const GLOBAL_SKILLS = ["brain-ingest", "brain-search", "brain-refresh"]
+
+async function readSkillVersion(skillDir) {
+  try {
+    const raw = await readFile(join(skillDir, ".csb-version"), "utf8")
+    return JSON.parse(raw).version || null
+  } catch {
+    return null
+  }
+}
+
+// Decide whether to (re)install each global skill. Returns a map name→"install"|"skip".
+// Interactive mismatch prompts once per run with update-all / skip-all / ask-per-skill.
+async function planGlobalSkillInstall({ isInteractive }) {
+  const decisions = {}
+  const mismatches = []
+
+  for (const name of GLOBAL_SKILLS) {
+    const destDir = join(homedir(), ".claude", "skills", name)
+    const installed = await readSkillVersion(destDir)
+    if (!installed) {
+      decisions[name] = "install"
+    } else if (installed === version) {
+      decisions[name] = "skip"
+    } else {
+      mismatches.push({ name, installed })
+    }
+  }
 
-    let content = await readFile(srcFile, "utf8")
-    content = content.replaceAll("__QMD_PATH__", qmdPath)
+  if (mismatches.length === 0) return decisions
+
+  // CI / non-interactive / opt-out: silently update.
+  if (!isInteractive || process.env.CSB_SKIP_SKILL_UPDATES === "1") {
+    for (const m of mismatches) decisions[m.name] = "install"
+    return decisions
+  }
+
+  const mode = await p.select({
+    message: `${mismatches.length} global skill${mismatches.length === 1 ? "" : "s"} at a different version than this release (v${version}). Update?`,
+    options: [
+      { value: "update-all", label: "Update all" },
+      { value: "skip-all", label: "Keep existing (skip all)" },
+      { value: "ask", label: "Ask per skill" },
+    ],
+    initialValue: "update-all",
+  })
+  if (p.isCancel(mode)) {
+    for (const m of mismatches) decisions[m.name] = "skip"
+    return decisions
+  }
+
+  if (mode === "update-all") {
+    for (const m of mismatches) decisions[m.name] = "install"
+  } else if (mode === "skip-all") {
+    for (const m of mismatches) decisions[m.name] = "skip"
+  } else {
+    for (const m of mismatches) {
+      const ok = await p.confirm({
+        message: `Update "${m.name}" from v${m.installed} → v${version}?`,
+        initialValue: true,
+      })
+      decisions[m.name] = p.isCancel(ok) || !ok ? "skip" : "install"
+    }
+  }
+  return decisions
+}
+
+async function installGlobalSkills({ isInteractive }) {
+  const globalSkillsDir = join(homedir(), ".claude", "skills")
+  const decisions = await planGlobalSkillInstall({ isInteractive })
+
+  const installed = []
+  const skipped = []
+  const sameVersion = []
+
+  await Promise.all(GLOBAL_SKILLS.map(async name => {
+    const destDir = join(globalSkillsDir, name)
+    const decision = decisions[name]
+
+    if (decision === "skip") {
+      // Differentiate "already at this version" from "user declined update" for logging.
+      const current = await readSkillVersion(destDir)
+      if (current === version) sameVersion.push(name)
+      else skipped.push(name)
+      return
+    }
+
+    const srcFile = join(TEMPLATE, ".claude/skills", name, "SKILL.md")
+    const content = await readFile(srcFile, "utf8")
 
     await mkdir(destDir, { recursive: true })
     await writeFile(join(destDir, "SKILL.md"), content, "utf8")
+    await writeFile(
+      join(destDir, ".csb-version"),
+      JSON.stringify({ version, installed: new Date().toISOString() }, null, 2) + "\n",
+      "utf8",
+    )
+    installed.push(name)
   }))
+
+  return { installed, skipped, sameVersion }
 }
 
-async function main() {
+function parseConfig(content) {
+  if (!content) return { defaultBrain: null, brains: [], header: "" }
+  const blocks = content.split(/\n(?=\[\[brains\]\])/)
+  const header = blocks[0] || ""
+  // Prefer `default = …` over legacy `active = …` so existing configs upgrade
+  // transparently on the next write.
+  const defaultMatch =
+    header.match(/^default\s*=\s*"([^"]+)"/m) ||
+    header.match(/^active\s*=\s*"([^"]+)"/m)
+  const brains = blocks.slice(1).map(block => {
+    const get = re => (block.match(re) || [])[1] || ""
+    return {
+      raw: block,
+      name: get(/^name\s*=\s*"([^"]+)"/m),
+      path: get(/^path\s*=\s*"([^"]+)"/m),
+      qmd_index: get(/^qmd_index\s*=\s*"([^"]*)"/m),
+      created: get(/^created\s*=\s*"([^"]*)"/m),
+      git_remote: get(/^git_remote\s*=\s*"([^"]*)"/m),
+    }
+  }).filter(b => b.name)
+  return { defaultBrain: defaultMatch ? defaultMatch[1] : null, brains, header }
+}
+
+function printHelp() {
+  const lines = [
+    `${pc.bold("claude-second-brain")} v${version}`,
+    "",
+    "Usage:",
+    `  ${pc.cyan("claude-second-brain")}                         create a new brain (interactive)`,
+    `  ${pc.cyan("claude-second-brain <name>")}                  create a new brain named <name>`,
+    `  ${pc.cyan("claude-second-brain ls")}                      list all brains`,
+    `  ${pc.cyan("claude-second-brain rm [<name>…]")}            remove one or more brains (space to multi-select)`,
+    `  ${pc.cyan("claude-second-brain path [--brain N] [flag]")} print a path (flags: --root, --qmd, --config)`,
+    `  ${pc.cyan("claude-second-brain qmd [--brain N] -- …")}    run qmd against the resolved brain`,
+    `  ${pc.cyan("claude-second-brain help")}                    show this message`,
+  ]
+  console.log(lines.join("\n"))
+}
+
+// Resolve a brain entry from config. Name defaults to the `default` field.
+async function resolveBrain(name) {
+  let content
+  try {
+    content = await readFile(CSB_CONFIG, "utf8")
+  } catch {
+    throw new Error(`No config at ${CSB_CONFIG}. Run \`claude-second-brain <name>\` to create your first brain.`)
+  }
+  const { defaultBrain, brains } = parseConfig(content)
+  const target = name || defaultBrain
+  if (!target) {
+    const available = brains.map(b => b.name).join(", ")
+    const hint = available
+      ? `Pass --brain <name> (available: ${available}), or edit ${CSB_CONFIG} and set \`default = "<name>"\`.`
+      : `Run \`claude-second-brain <name>\` to create your first brain.`
+    throw new Error(`No default brain set in config.toml. ${hint}`)
+  }
+  const entry = brains.find(b => b.name === target)
+  if (!entry) {
+    const available = brains.map(b => b.name).join(", ") || "(none)"
+    throw new Error(`No brain named "${target}". Available: ${available}. Run \`claude-second-brain ls\` to list brains.`)
+  }
+  return entry
+}
+
+async function cmdPath(args) {
+  // Parse flags: --brain <name>, --root | --qmd | --config (default: --root)
+  let name = null
+  let mode = "root"
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === "--brain") { name = args[++i]; continue }
+    if (a === "--root")   { mode = "root"; continue }
+    if (a === "--qmd")    { mode = "qmd"; continue }
+    if (a === "--config") { mode = "config"; continue }
+    throw new Error(`Unknown path arg: ${a}`)
+  }
+  if (mode === "config") {
+    process.stdout.write(CSB_CONFIG + "\n")
+    return
+  }
+  const brain = await resolveBrain(name)
+  const out = mode === "qmd" ? brain.qmd_index : brain.path
+  process.stdout.write(out + "\n")
+}
+
+async function cmdQmd(args) {
+  // `claude-second-brain qmd [--brain N] [--] <qmd args…>`
+  let name = null
+  const rest = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === "--brain") { name = args[++i]; continue }
+    if (a === "--") { rest.push(...args.slice(i + 1)); break }
+    rest.push(a)
+  }
+  const brain = await resolveBrain(name)
+  const result = spawnSync("npx", ["-y", "@tobilu/qmd", ...rest], {
+    stdio: "inherit",
+    env: { ...process.env, INDEX_PATH: brain.qmd_index },
+  })
+  process.exit(result.status ?? 1)
+}
+
+async function listBrains() {
+  const toDisplayPath = p => p && p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p
+  let content
+  try {
+    content = await readFile(CSB_CONFIG, "utf8")
+  } catch {
+    p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
+    p.log.info("No brains yet. Run `claude-second-brain <name>` to create one.")
+    p.outro("")
+    return
+  }
+
+  const { defaultBrain, brains } = parseConfig(content)
+  p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
+
+  if (brains.length === 0) {
+    p.log.info("No brains registered in config.toml.")
+    p.outro("")
+    return
+  }
+
+  const rows = brains.map(b => {
+    const marker = b.name === defaultBrain ? pc.green("*") : " "
+    const name = b.name === defaultBrain ? pc.bold(b.name) : b.name
+    const remote = b.git_remote || pc.dim("—")
+    return `${marker} ${name}\n  path:    ${pc.dim(toDisplayPath(b.path))}\n  created: ${pc.dim(b.created || "—")}\n  remote:  ${pc.dim(remote)}`
+  })
+
+  p.note(rows.join("\n\n"), `${brains.length} brain${brains.length === 1 ? "" : "s"}`)
+  p.outro(defaultBrain ? `default: ${pc.cyan(defaultBrain)}` : "no default brain")
+}
+
+async function removeBrain(names, { yes = false } = {}) {
+  p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
+
+  let content
+  try {
+    content = await readFile(CSB_CONFIG, "utf8")
+  } catch {
+    p.cancel(`No config at ${CSB_CONFIG} — nothing to remove.`)
+    process.exit(1)
+  }
+
+  const { defaultBrain, brains, header } = parseConfig(content)
+
+  if (brains.length === 0) {
+    p.cancel("No brains registered in config.toml.")
+    process.exit(1)
+  }
+
+  const toDisplayPath = p => p && p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p
+
+  if (!names || names.length === 0) {
+    const pick = await p.multiselect({
+      message: "Which brain(s) to remove? (space to toggle, enter to confirm)",
+      options: brains.map(b => ({
+        value: b.name,
+        label: b.name === defaultBrain ? `${b.name} ${pc.dim("(default)")}` : b.name,
+        hint: toDisplayPath(b.path),
+      })),
+      required: true,
+    })
+    if (p.isCancel(pick)) { p.cancel("Cancelled."); process.exit(0) }
+    names = pick
+  }
+
+  const targets = names.map(n => {
+    const t = brains.find(b => b.name === n)
+    if (!t) {
+      p.cancel(`No brain named "${n}". Run \`claude-second-brain ls\` to see registered brains.`)
+      process.exit(1)
+    }
+    return t
+  })
+
+  if (!yes) {
+    const list = targets.map(t => `  • ${t.name} ${pc.dim(toDisplayPath(t.path))}`).join("\n")
+    const ok = await p.confirm({
+      message: `Remove ${targets.length} brain${targets.length === 1 ? "" : "s"}? This deletes the ${targets.length === 1 ? "directory" : "directories"} and config ${targets.length === 1 ? "entry" : "entries"}.\n${list}`,
+      initialValue: false,
+    })
+    if (p.isCancel(ok) || !ok) {
+      p.cancel("Cancelled.")
+      process.exit(0)
+    }
+  }
+
+  // Ask per-target whether to also delete the remote. Skip in -y mode — remote
+  // deletion is destructive beyond the local vault and requires explicit opt-in.
+  const remoteDecisions = new Map()
+  if (!yes) {
+    for (const target of targets) {
+      const gh = parseGithubRepo(target.git_remote)
+      const cf = parseCloudflareArtifact(target.git_remote)
+      if (!gh && !cf) continue
+      const label = gh ? `GitHub repo ${pc.cyan(gh)}` : `Cloudflare Artifact ${pc.cyan(`${cf.namespace}/${cf.repo}`)}`
+      const ok = await p.confirm({
+        message: `Also delete ${label} for "${target.name}"?`,
+        initialValue: false,
+      })
+      if (p.isCancel(ok)) { p.cancel("Cancelled."); process.exit(0) }
+      if (ok) {
+        remoteDecisions.set(target.name, gh
+          ? { kind: "github", slug: gh }
+          : { kind: "cloudflare", namespace: cf.namespace, repo: cf.repo })
+      }
+    }
+  }
+
+  const spin = p.spinner()
+
+  for (const target of targets) {
+    spin.start(`Deleting ${toDisplayPath(target.path)}`)
+    if (target.path) {
+      try {
+        await rm(target.path, { recursive: true, force: true })
+        spin.stop(`Removed ${pc.dim(toDisplayPath(target.path))}`)
+      } catch (err) {
+        spin.stop(`Failed to remove ${target.name}: ${err.message}`, 1)
+      }
+    } else {
+      spin.stop(`${target.name}: no path on config entry — skipping directory removal`, 1)
+    }
+  }
+
+  for (const [name, decision] of remoteDecisions) {
+    if (decision.kind === "github") {
+      spin.start(`Deleting GitHub repo ${decision.slug}`)
+      const result = deleteGithubRepo(decision.slug)
+      if (result.ok) {
+        spin.stop(`Removed GitHub repo ${pc.dim(decision.slug)}`)
+      } else {
+        spin.stop(`Failed to delete GitHub repo ${decision.slug}: ${result.error}`, 1)
+        p.log.warn(`Delete it manually: ${pc.cyan(`gh repo delete ${decision.slug} --yes`)} (or via https://github.com/${decision.slug}/settings)`)
+      }
+    } else {
+      spin.start(`Deleting Cloudflare Artifact ${decision.namespace}/${decision.repo}`)
+      const result = await deleteCloudflareArtifact(decision)
+      if (result.ok) {
+        spin.stop(`Removed Cloudflare Artifact ${pc.dim(`${decision.namespace}/${decision.repo}`)}`)
+      } else {
+        spin.stop(`Failed to delete Cloudflare Artifact for ${name}: ${result.error}`, 1)
+        p.log.warn(`Delete it manually:\n  ${pc.cyan(`TOKEN=$(wrangler auth token)`)}\n  ${pc.cyan(`curl -X DELETE https://artifacts.cloudflare.net/v1/api/namespaces/${decision.namespace}/repos/${decision.repo} \\`)}\n  ${pc.cyan(`  -H "Authorization: Bearer $TOKEN"`)}`)
+      }
+    }
+  }
+
+  // Rewrite config.toml without the removed brains.
+  const removedSet = new Set(names)
+  const remaining = brains.filter(b => !removedSet.has(b.name))
+  const removedDefault = removedSet.has(defaultBrain)
+  // Strip both legacy `active = …` and current `default = …` from the header;
+  // we rewrite it from scratch below.
+  let newHeader = header
+    .replace(/^active\s*=\s*"[^"]*"\s*\n?/m, "")
+    .replace(/^default\s*=\s*"[^"]*"\s*\n?/m, "")
+    .replace(/^\s+|\s+$/g, "")
+  if (removedDefault) {
+    if (remaining.length > 0) {
+      newHeader = `default = "${remaining[0].name}"${newHeader ? "\n" + newHeader : ""}`
+    }
+  } else if (defaultBrain) {
+    newHeader = `default = "${defaultBrain}"${newHeader ? "\n" + newHeader : ""}`
+  }
+
+  const entries = remaining.map(b => b.raw.replace(/^\s+|\s+$/g, ""))
+  const out = [newHeader, ...entries].filter(Boolean).join("\n\n").trimEnd() + "\n"
+  await writeFile(CSB_CONFIG, out, "utf8")
+
+  const defaultNow = parseConfig(out).defaultBrain
+  const n = targets.length
+  const removedMsg = `Removed ${n} brain${n === 1 ? "" : "s"}.`
+  p.outro(
+    removedDefault
+      ? (defaultNow ? `${removedMsg} Default brain is now ${pc.cyan(defaultNow)}.` : `${removedMsg} No brains left.`)
+      : removedMsg
+  )
+}
+
+async function writeConfig(brainName, brainPath, qmdPath, gitRemote) {
+  const entry = [
+    `[[brains]]`,
+    `name = "${brainName}"`,
+    `path = "${brainPath}"`,
+    `qmd_index = "${qmdPath}"`,
+    `created = "${new Date().toISOString().slice(0, 10)}"`,
+    `git_remote = "${gitRemote}"`,
+  ].join("\n")
+
+  let existing = null
+  try {
+    existing = await readFile(CSB_CONFIG, "utf8")
+  } catch {
+    // Config doesn't exist yet — create fresh
+  }
+
+  if (!existing || !existing.trim()) {
+    await writeFile(CSB_CONFIG, `default = "${brainName}"\n\n${entry}\n`, "utf8")
+    return
+  }
+
+  // Upsert: remove existing entry for this brain name, then append updated entry.
+  // Also migrate legacy `active = …` to `default = …` on any write.
+  // If the header lacks any default/active key (e.g. user hand-edited an empty
+  // file, or earlier versions of this CLI wrote entries without one), inject
+  // `default = "${brainName}"` so CLI subcommands can resolve a default.
+  const blocks = existing.split(/\n(?=\[\[brains\]\])/)
+  let header = blocks[0].replace(/^active\s*=/m, "default =")
+  if (!/^default\s*=/m.test(header)) {
+    header = `default = "${brainName}"\n\n${header.trimStart()}`
+  }
+  const otherBrains = blocks.slice(1).filter(b => !b.includes(`name = "${brainName}"`))
+  await writeFile(CSB_CONFIG, [header, ...otherBrains, entry].join("\n").trimEnd() + "\n", "utf8")
+}
+
+async function createBrain(initialName) {
   const isInteractive = Boolean(process.stdin.isTTY)
 
   p.intro(`${pc.bgCyan(pc.black(" claude-second-brain "))} v${version}`)
 
-  let targetName = process.argv[2]
+  let targetName = initialName
   if (!targetName) {
     const answer = await p.text({
-      message: "Where to create your brain?",
+      message: "Name of the brain?",
       placeholder: "my-brain",
       defaultValue: "my-brain",
     })
     if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
     targetName = answer
+  } else {
+    p.log.step(`Name of the brain?\n${pc.dim(targetName)}`)
   }
 
-  const defaultQmdPath = join(
-    process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
-    "qmd", "index.sqlite"
-  )
   const toDisplayPath = p => p.startsWith(homedir()) ? "~" + p.slice(homedir().length) : p
-  const expandHome = p => p.startsWith("~/") || p === "~" ? join(homedir(), p.slice(1)) : p
-  const displayQmdPath = toDisplayPath(defaultQmdPath)
-  let qmdPath
-  if (isInteractive) {
-    const answer = await p.text({
-      message: "Where to store the qmd index?",
-      placeholder: displayQmdPath,
-      defaultValue: displayQmdPath,
-    })
-    if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
-    qmdPath = expandHome(answer)
-  } else {
-    qmdPath = defaultQmdPath
-  }
+  const qmdPath = join(CSB_ROOT, targetName, ".qmd", "index.sqlite")
 
   let remoteProvider = "none"
   let repoName = null
@@ -334,7 +778,8 @@ async function main() {
     }
   }
 
-  const targetDir = join(process.cwd(), targetName)
+  await mkdir(CSB_ROOT, { recursive: true })
+  const targetDir = join(CSB_ROOT, targetName)
 
   // Fail fast if target already exists
   try {
@@ -358,12 +803,13 @@ async function main() {
   } catch {
     // .gitignore.template not present (e.g. running locally where npm didn't strip it)
   }
-  spin.stop(`${targetName}/ created`)
+  spin.stop(`${pc.dim(toDisplayPath(targetDir))} created`)
 
-  // Patch vault files with chosen qmd path
-  spin.start("Configuring qmd index path")
-  await patchVault(targetDir, qmdPath, targetName)
-  spin.stop(`qmd index → ${pc.dim(toDisplayPath(qmdPath))}`)
+  // Patch vault README (__BRAIN_NAME__). All other paths are resolved at
+  // runtime via `claude-second-brain path` / `claude-second-brain qmd`.
+  spin.start("Patching README")
+  await patchVault(targetDir, targetName)
+  spin.stop("README patched")
 
   // Install mise if not present
   if (!commandExists("mise")) {
@@ -386,10 +832,43 @@ async function main() {
   if (pnpmOk) spin.stop("dependencies installed")
   else spin.stop("pnpm install failed — run it manually inside your vault", 1)
 
-  // Install global skills
+  // Register qmd collections + contexts. Skip reindex — first reindex downloads
+  // ~2GB of GGUF models; user runs it explicitly when ready.
+  if (pnpmOk) {
+    let doQmdSetup = true
+    if (isInteractive) {
+      const ok = await p.confirm({
+        message: "Register qmd collections now? (wiki + raw-sources)",
+        initialValue: true,
+      })
+      if (p.isCancel(ok)) { p.cancel("Setup cancelled."); process.exit(0) }
+      doQmdSetup = ok
+    }
+    if (doQmdSetup) {
+      spin.start("Registering qmd collections (wiki, raw-sources)")
+      const qmdRes = runCapture(["mise", "exec", "--", "pnpm", "qmd:setup"], targetDir)
+      if (qmdRes.ok) {
+        spin.stop("qmd collections registered")
+      } else {
+        spin.stop("pnpm qmd:setup failed — run it manually inside your vault", 1)
+        const tail = tailForError(qmdRes)
+        if (tail) p.log.warn(`qmd:setup output:\n${tail}`)
+      }
+    } else {
+      p.log.info("Skipped qmd:setup — run `pnpm qmd:setup` from the vault root when ready.")
+    }
+  }
+
+  // Install global skills (version-aware — prompts to update when versions differ)
   spin.start("Installing global Claude skills")
-  await installGlobalSkills(qmdPath)
-  spin.stop(`Global skills installed → ${pc.dim(toDisplayPath(join(homedir(), ".claude", "skills")))}`)
+  const skillResult = await installGlobalSkills({ isInteractive })
+  const installedCount = skillResult.installed.length
+  const skippedCount = skillResult.skipped.length
+  const summary = [
+    installedCount > 0 ? `installed ${installedCount}` : null,
+    skippedCount > 0 ? `kept ${skippedCount}` : null,
+  ].filter(Boolean).join(", ") || "already up to date"
+  spin.stop(`Global skills ${summary} → ${pc.dim(toDisplayPath(join(homedir(), ".claude", "skills")))}`)
 
   // Git init
   spin.start("Initializing git repo")
@@ -431,14 +910,27 @@ async function main() {
   }
 
   // Cloudflare Artifacts repo (optional)
+  let gitRemote = remoteProvider === "github"
+    ? (() => {
+        const r = spawnSync("git", ["remote", "get-url", "origin"], { cwd: targetDir, stdio: "pipe" })
+        return r.status === 0 ? r.stdout.toString().trim() : ""
+      })()
+    : ""
   if (remoteProvider === "cloudflare") {
     const result = await setupCloudflareRemote({ targetDir, repoName, namespace: cfNamespace, spin })
     if (result?.repoToken) {
       p.log.warn(`Save your Artifacts repo token — it expires and you'll need to mint a new one:\n  ${result.repoToken}`)
     }
+    gitRemote = result?.remote || ""
   }
 
+  // Write central config
+  spin.start("Registering brain in config")
+  await writeConfig(targetName, targetDir, qmdPath, gitRemote)
+  spin.stop(`Config updated → ${pc.dim(toDisplayPath(CSB_CONFIG))}`)
+
   // Next steps
+  const brainDisplayPath = toDisplayPath(targetDir)
   const remoteSteps = remoteProvider === "cloudflare"
     ? [
         `${pc.dim("# Mint a fresh git push/pull token when the current one expires:")}`,
@@ -456,8 +948,9 @@ async function main() {
       : []
 
   const nextSteps = [
-    `${pc.cyan(`cd ${targetName}`)}`,
-    `${pc.cyan("claude")}          open Claude Code, then run ${pc.bold("/setup")}`,
+    `${pc.cyan(`cd ${brainDisplayPath}`)}`,
+    `${pc.cyan("pnpm qmd:reindex")}  ${pc.dim("# first run downloads ~2GB of embedding models")}`,
+    `${pc.cyan("claude")}            open Claude Code and start ingesting sources`,
     ...remoteSteps,
   ].join("\n")
 
@@ -465,6 +958,34 @@ async function main() {
   p.outro("Happy knowledge building!")
 }
 
+async function main() {
+  const [, , cmd, ...rest] = process.argv
+
+  if (cmd === "help" || cmd === "--help" || cmd === "-h") {
+    printHelp()
+    return
+  }
+  if (cmd === "ls" || cmd === "list") {
+    await listBrains()
+    return
+  }
+  if (cmd === "rm" || cmd === "remove") {
+    const names = rest.filter(a => !a.startsWith("-"))
+    const yes = rest.some(a => a === "-y" || a === "--yes")
+    await removeBrain(names, { yes })
+    return
+  }
+  if (cmd === "path") {
+    await cmdPath(rest)
+    return
+  }
+  if (cmd === "qmd") {
+    await cmdQmd(rest)
+    return
+  }
+  await createBrain(cmd)
+}
+
 main().catch(err => {
   p.cancel(err.message)
   process.exit(1)