claude-second-brain 0.5.0 → 0.6.0

package/README.md

@@ -63,7 +63,7 @@ The CLI will ask:
 - **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`.
+Then scaffolds the vault, installs `mise` + `node` + `pnpm`, runs `pnpm install`, and `git init`.
 
 **Step 2 — Initialize inside Claude Code**
 

package/bin/create.js

@@ -65,6 +65,187 @@ async function patchVault(targetDir, qmdPath, brainName) {
   }
 }
 
+// Resolve the `wrangler` CLI as either an installed binary or `npx wrangler` fallback.
+function resolveWranglerCli() {
+  if (commandExists("wrangler")) return { cmd: "wrangler", prefix: [] }
+  return { cmd: "npx", prefix: ["wrangler"] }
+}
+
+// Strip ANSI escape sequences that wrangler injects into stdout.
+function stripAnsi(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1B\[[0-9;]*[A-Za-z]/g, "")
+}
+
+// Wrangler prints a decorative banner (⛅, ❅, etc.) alongside the token.
+// Find the actual token line — a long run of Bearer-safe ASCII chars — and ignore the rest.
+function extractBearerToken(stdout) {
+  const lines = stripAnsi(stdout).split(/\r?\n/)
+  const candidates = lines
+    .map(l => l.trim())
+    .filter(l => /^[A-Za-z0-9._~+/=-]{20,}$/.test(l))
+  // Prefer the longest candidate (real tokens are longer than any accidental match).
+  candidates.sort((a, b) => b.length - a.length)
+  return candidates[0] || null
+}
+
+function truncate(s, n = 80) {
+  if (!s) return ""
+  return s.length > n ? s.slice(0, n) + "…" : s
+}
+
+// End-to-end Cloudflare Artifacts setup: auth, create repo, set remote, push.
+// Every failure logs the exact step, exit codes, stderr, and HTTP bodies so the
+// user can see where in the flow the break happened.
+async function setupCloudflareRemote({ targetDir, repoName, namespace, spin }) {
+  // Honor an existing API token as a shortcut — skip wrangler entirely.
+  let cfApiToken = process.env.CLOUDFLARE_API_TOKEN
+  let tokenSource = "CLOUDFLARE_API_TOKEN env"
+
+  if (!cfApiToken) {
+    // wrangler login requests artifacts:write by default — use it for auth.
+    const wrangler = resolveWranglerCli()
+    const wranglerLabel = [wrangler.cmd, ...wrangler.prefix].join(" ")
+
+    p.log.info(`Checking Cloudflare auth via \`${wranglerLabel} whoami\`...`)
+    const authCheck = spawnSync(wrangler.cmd, [...wrangler.prefix, "whoami"], { stdio: "pipe" })
+    const whoamiOut = stripAnsi(authCheck.stdout?.toString() || "") + "\n" + stripAnsi(authCheck.stderr?.toString() || "")
+    let loggedIn = authCheck.status === 0
+    // Wrangler's existing session may predate Artifacts — it warns "missing some expected Oauth scopes"
+    // and lists "artifacts:write". Detect that and force a re-login.
+    const hasArtifactsScope = /^\s*-\s*artifacts\s*\(write\)/im.test(whoamiOut)
+    const missingArtifactsScope = /missing some expected Oauth scopes/i.test(whoamiOut)
+      && /artifacts:write/i.test(whoamiOut)
+    const needsRelogin = loggedIn && (!hasArtifactsScope || missingArtifactsScope)
+
+    if (!loggedIn) {
+      const stderr = authCheck.stderr?.toString().trim()
+      p.log.info(`wrangler whoami exited ${authCheck.status}${stderr ? ` (${truncate(stderr, 160)})` : ""}`)
+    } else if (needsRelogin) {
+      p.log.info("Your wrangler session is missing the artifacts:write scope — re-login required.")
+    }
+
+    if (!loggedIn || needsRelogin) {
+      p.log.info("Starting wrangler login (grants artifacts:write scope)...")
+      const loginResult = spawnSync(wrangler.cmd, [...wrangler.prefix, "login"], { stdio: "inherit" })
+      loggedIn = loginResult.status === 0
+      if (!loggedIn) {
+        p.log.warn(`wrangler login exited ${loginResult.status} — set CLOUDFLARE_API_TOKEN and re-run.`)
+        return null
+      }
+
+      // Verify the new session actually has artifacts:write before proceeding.
+      const verify = spawnSync(wrangler.cmd, [...wrangler.prefix, "whoami"], { stdio: "pipe" })
+      const verifyOut = stripAnsi(verify.stdout?.toString() || "") + "\n" + stripAnsi(verify.stderr?.toString() || "")
+      if (!/^\s*-\s*artifacts\s*\(write\)/im.test(verifyOut)) {
+        p.log.warn("wrangler login completed but artifacts:write scope is still missing.")
+        p.log.warn("Upgrade wrangler (npm i -g wrangler@latest) or set CLOUDFLARE_API_TOKEN manually.")
+        return null
+      }
+    }
+
+    // Retrieve the OAuth token wrangler stored; it refreshes automatically if expired.
+    p.log.info(`Fetching OAuth token via \`${wranglerLabel} auth token\`...`)
+    const tokenResult = spawnSync(wrangler.cmd, [...wrangler.prefix, "auth", "token"], { stdio: "pipe" })
+    const rawStdout = tokenResult.stdout?.toString() || ""
+    const rawStderr = tokenResult.stderr?.toString() || ""
+
+    if (tokenResult.status !== 0) {
+      p.log.warn(`wrangler auth token exited ${tokenResult.status}`)
+      if (rawStderr.trim()) p.log.warn(`stderr: ${truncate(rawStderr.trim(), 400)}`)
+      if (rawStdout.trim()) p.log.warn(`stdout: ${truncate(rawStdout.trim(), 400)}`)
+      return null
+    }
+
+    cfApiToken = extractBearerToken(rawStdout)
+    if (!cfApiToken) {
+      p.log.warn("Could not parse a Bearer-safe token from wrangler output.")
+      p.log.warn(`raw stdout: ${truncate(rawStdout.trim(), 400)}`)
+      if (rawStderr.trim()) p.log.warn(`raw stderr: ${truncate(rawStderr.trim(), 400)}`)
+      return null
+    }
+    tokenSource = "wrangler auth token"
+  }
+
+  // Guard against tokens that contain non-ASCII (which would crash fetch's header encoder).
+  if (!/^[\x20-\x7E]+$/.test(cfApiToken)) {
+    p.log.warn(`Token from ${tokenSource} contains non-ASCII characters — refusing to use it.`)
+    p.log.warn(`token preview: ${truncate(cfApiToken, 60)}`)
+    return null
+  }
+
+  p.log.info(`Using token from ${tokenSource} (length ${cfApiToken.length}, prefix ${cfApiToken.slice(0, 8)}…)`)
+
+  const baseUrl = `https://artifacts.cloudflare.net/v1/api/namespaces/${namespace}`
+  spin.start(`Creating Cloudflare Artifact ${pc.dim(repoName)} at ${pc.dim(baseUrl)}`)
+
+  let res
+  let rawBody = ""
+  try {
+    res = await fetch(`${baseUrl}/repos`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${cfApiToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ name: repoName, default_branch: "main" }),
+    })
+    rawBody = await res.text()
+  } catch (err) {
+    spin.stop(`Network error calling Artifacts API: ${err.message}`, 1)
+    return null
+  }
+
+  let createData
+  try {
+    createData = rawBody ? JSON.parse(rawBody) : {}
+  } catch {
+    spin.stop(`Artifacts API returned non-JSON (HTTP ${res.status})`, 1)
+    p.log.warn(`body: ${truncate(rawBody, 400)}`)
+    return null
+  }
+
+  if (!res.ok || !createData?.success) {
+    const errMsg = createData?.errors?.[0]?.message || createData?.message || "unknown error"
+    spin.stop(`Artifacts API failed (HTTP ${res.status}): ${errMsg}`, 1)
+    p.log.warn(`full response: ${truncate(rawBody, 400)}`)
+    return null
+  }
+
+  const { remote, token: repoToken } = createData.result
+  if (!remote || !repoToken) {
+    spin.stop("Artifacts API succeeded but response is missing remote/token", 1)
+    p.log.warn(`response: ${truncate(rawBody, 400)}`)
+    return null
+  }
+
+  const remoteAddResult = spawnSync("git", ["remote", "add", "origin", remote], { cwd: targetDir, stdio: "pipe" })
+  if (remoteAddResult.status !== 0) {
+    spin.stop(`git remote add failed (exit ${remoteAddResult.status})`, 1)
+    const stderr = remoteAddResult.stderr?.toString().trim()
+    if (stderr) p.log.warn(`git stderr: ${truncate(stderr, 400)}`)
+    return null
+  }
+
+  const pushResult = spawnSync(
+    "git",
+    ["-c", `http.extraHeader=Authorization: Bearer ${repoToken}`, "push", "-u", "origin", "main"],
+    { cwd: targetDir, stdio: "pipe" }
+  )
+  if (pushResult.status !== 0) {
+    spin.stop(`git push to Cloudflare Artifact failed (exit ${pushResult.status})`, 1)
+    const stderr = pushResult.stderr?.toString().trim()
+    const stdout = pushResult.stdout?.toString().trim()
+    if (stderr) p.log.warn(`git stderr: ${truncate(stderr, 400)}`)
+    if (stdout) p.log.warn(`git stdout: ${truncate(stdout, 400)}`)
+    return { repoToken, remote }
+  }
+
+  spin.stop(`Cloudflare Artifact created: ${pc.cyan(repoName)}`)
+  p.log.info(`Remote: ${pc.dim(remote)}`)
+  return { repoToken, remote }
+}
+
 async function installGlobalSkills(qmdPath) {
   const globalSkillsDir = join(homedir(), ".claude", "skills")
 
@@ -100,37 +281,56 @@ async function main() {
     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: defaultQmdPath,
-      defaultValue: defaultQmdPath,
+      placeholder: displayQmdPath,
+      defaultValue: displayQmdPath,
     })
     if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
-    qmdPath = answer
+    qmdPath = expandHome(answer)
   } else {
     qmdPath = defaultQmdPath
   }
 
-  let createGhRepo = false
-  let ghRepoName = null
+  let remoteProvider = "none"
+  let repoName = null
+  let cfNamespace = "default"
   if (isInteractive) {
-    const confirm = await p.confirm({
-      message: "Create a private GitHub repo?",
-      initialValue: false,
+    const provider = await p.select({
+      message: "Where to host the Git remote?",
+      options: [
+        { value: "github", label: "GitHub", hint: "default" },
+        { value: "cloudflare", label: "Cloudflare Artifacts" },
+        { value: "none", label: "Skip — I'll add a remote later" },
+      ],
+      initialValue: "github",
     })
-    if (p.isCancel(confirm)) { p.cancel("Setup cancelled."); process.exit(0) }
-    createGhRepo = confirm
+    if (p.isCancel(provider)) { p.cancel("Setup cancelled."); process.exit(0) }
+    remoteProvider = provider
 
-    if (createGhRepo) {
+    if (remoteProvider !== "none") {
       const answer = await p.text({
-        message: "GitHub repo name?",
+        message: "Repo name?",
         placeholder: targetName,
         defaultValue: targetName,
       })
       if (p.isCancel(answer)) { p.cancel("Setup cancelled."); process.exit(0) }
-      ghRepoName = answer
+      repoName = answer
+    }
+
+    if (remoteProvider === "cloudflare") {
+      const ns = await p.text({
+        message: "Artifacts namespace?",
+        placeholder: "default",
+        defaultValue: "default",
+      })
+      if (p.isCancel(ns)) { p.cancel("Setup cancelled."); process.exit(0) }
+      cfNamespace = ns
     }
   }
 
@@ -163,7 +363,7 @@ async function main() {
   // 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)}`)
+  spin.stop(`qmd index → ${pc.dim(toDisplayPath(qmdPath))}`)
 
   // Install mise if not present
   if (!commandExists("mise")) {
@@ -173,13 +373,24 @@ async function main() {
     else spin.stop("Failed to install mise — run: npm install -g @jdxcode/mise", 1)
   }
 
-  // Run mise install inside the new vault to install bun
-  spin.start("Installing bun via mise")
+  // Run mise install inside the new vault to install node + pnpm
+  spin.start("Installing node + pnpm via mise")
   run(["mise", "trust"], targetDir)
   const miseOk = run(["mise", "install"], targetDir)
-  if (miseOk) spin.stop("bun installed")
+  if (miseOk) spin.stop("node + pnpm installed")
   else spin.stop("mise install failed — run it manually inside your vault", 1)
 
+  // Install vault dependencies via pnpm
+  spin.start("Installing vault dependencies")
+  const pnpmOk = run(["mise", "exec", "--", "pnpm", "install"], targetDir)
+  if (pnpmOk) spin.stop("dependencies installed")
+  else spin.stop("pnpm install failed — run it manually inside your vault", 1)
+
+  // Install global skills
+  spin.start("Installing global Claude skills")
+  await installGlobalSkills(qmdPath)
+  spin.stop(`Global skills installed → ${pc.dim(toDisplayPath(join(homedir(), ".claude", "skills")))}`)
+
   // Git init
   spin.start("Initializing git repo")
   const gitOk = run(["git", "init"], targetDir)
@@ -192,9 +403,9 @@ async function main() {
   }
 
   // GitHub repo (optional)
-  if (createGhRepo) {
+  if (remoteProvider === "github") {
     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`)
+      p.log.warn(`gh CLI not found — install from https://cli.github.com, then run:\n  gh repo create ${repoName} --private --source=. --remote=origin --push`)
     } else {
       const authCheck = spawnSync("gh", ["auth", "status"], { stdio: "pipe" })
       let loggedIn = authCheck.status === 0
@@ -205,33 +416,49 @@ async function main() {
       }
 
       if (loggedIn) {
-        spin.start(`Creating GitHub repo ${pc.dim(ghRepoName)}`)
+        spin.start(`Creating GitHub repo ${pc.dim(repoName)}`)
         const ghOk = run(
-          ["gh", "repo", "create", ghRepoName, "--private", "--source=.", "--remote=origin", "--push"],
+          ["gh", "repo", "create", repoName, "--private", "--source=.", "--remote=origin", "--push"],
           targetDir
         )
         if (ghOk) {
-          spin.stop(`GitHub repo created (private): ${pc.cyan(ghRepoName)}`)
+          spin.stop(`GitHub repo created (private): ${pc.cyan(repoName)}`)
         } else {
-          spin.stop(`gh repo create failed — run: gh repo create ${ghRepoName} --private --source=. --remote=origin --push`, 1)
+          spin.stop(`gh repo create failed — run: gh repo create ${repoName} --private --source=. --remote=origin --push`, 1)
         }
       }
     }
   }
 
-  // Install global skills
-  spin.start("Installing global Claude skills")
-  await installGlobalSkills(qmdPath)
-  spin.stop("Global skills installed")
+  // Cloudflare Artifacts repo (optional)
+  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}`)
+    }
+  }
 
   // Next steps
+  const remoteSteps = remoteProvider === "cloudflare"
+    ? [
+        `${pc.dim("# Mint a fresh git push/pull token when the current one expires:")}`,
+        `${pc.cyan(`TOKEN=$(wrangler auth token)`)}`,
+        `${pc.cyan(`curl -X POST https://artifacts.cloudflare.net/v1/api/namespaces/${cfNamespace}/tokens \\`)}`,
+        `${pc.cyan(`  -H "Authorization: Bearer $TOKEN" \\`)}`,
+        `${pc.cyan(`  -H "Content-Type: application/json" \\`)}`,
+        `${pc.cyan(`  -d '{"repo":"${repoName}","scope":"write","ttl":86400}'`)}`,
+      ]
+    : remoteProvider === "none"
+      ? [
+          `${pc.cyan("git remote add origin <url>")}  connect to a remote for sync`,
+          `${pc.cyan("git push -u origin main")}`,
+        ]
+      : []
+
   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")}`,
-    ] : []),
+    ...remoteSteps,
   ].join("\n")
 
   p.note(nextSteps, "Next steps")

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "claude-second-brain",
-  "version": "0.5.0",
+  "version": "0.6.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"
   },
+  "scripts": {
+    "docs:dev": "vocs dev",
+    "docs:build": "vocs build",
+    "docs:preview": "vocs preview"
+  },
   "files": [
     "bin/",
     "template/",
     "image.png"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
+  "packageManager": "pnpm@10.8.0",
   "dependencies": {
     "@clack/prompts": "^1.2.0",
     "picocolors": "^1.1.1"
@@ -22,5 +28,12 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/jessepinkman9900/claude-second-brain"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^6.0.2",
+    "vocs": "1.4.1"
   }
 }

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

@@ -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_PATH__ bunx @tobilu/qmd query -c wiki "<source topic and key claims>"`
+- 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
 - List all pages to create or update before proceeding
 

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__ bunx @tobilu/qmd collection list
-  INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
-  INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
+  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
   ```
 
 ### Step 2 — Analyze the wiki
@@ -74,20 +74,20 @@ If collection names changed:
 For each existing collection that no longer fits the new schema:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection remove <old-name>
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection remove <old-name>
 ```
 
 For each obsolete context:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context rm <path>
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context rm <path>
 ```
 
 ### Step 8 — Register the new schema
 
 Run:
 ```bash
-bun scripts/qmd/setup.ts
+pnpm qmd:setup
 ```
 
 This is idempotent — collections that already exist (e.g. ones you kept) are skipped; new ones are added; contexts are upserted.
@@ -96,7 +96,7 @@ This is idempotent — collections that already exist (e.g. ones you kept) are s
 
 Run:
 ```bash
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 ```
 
 This indexes all files under the new collections and generates fresh embeddings.
@@ -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__ bunx @tobilu/qmd collection list
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
+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
 ```
 
 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

@@ -6,7 +6,7 @@ argument-hint: "Optional: 'force' to force re-embedding of every chunk (slow, us
 
 # 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.
+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.
 
 ## When to Use
 
@@ -23,7 +23,7 @@ All commands run from the vault root.
 
 Run:
 ```bash
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 ```
 
 This script does two things:
@@ -38,10 +38,10 @@ When the user passes `force`, re-embed **every** chunk — not just the changed
 
 ```bash
 # Step 1 — update the file index first
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 
 # Step 2 — force re-embed everything
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed -f
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd embed -f
 ```
 
 Force mode is slow — confirm with the user before proceeding if the wiki is large.
@@ -51,7 +51,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__ bunx @tobilu/qmd status
+INDEX_PATH=__QMD_PATH__ pnpm dlx @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.

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

@@ -11,7 +11,7 @@ Runs the 4-step query workflow defined in CLAUDE.md. Answers come with inline `[
 ## Workflow
 
 **Step 1 — Search the wiki**
-- Run hybrid search: `INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "<question>"`
+- 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
 

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

@@ -13,10 +13,10 @@ Local semantic document index with hybrid search (BM25 + vector), collection man
 This vault keeps its index at `__QMD_PATH__`. All CLI commands **must** prefix with `INDEX_PATH=__QMD_PATH__`:
 
 ```bash
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "..."
+INDEX_PATH=__QMD_PATH__ pnpm dlx @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.
+The scripts `pnpm qmd:setup` and `pnpm qmd:reindex` 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_PATH__ bunx @tobilu/qmd collection add <path> --name <name> --mask <glob-pattern>
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection add <path> --name <name> --mask <glob-pattern>
 # e.g.:
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection add wiki --name wiki --mask "**/*.md"
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection add wiki --name wiki --mask "**/*.md"
 
 # List all collections with details
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection list
 
 # Remove a collection
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection remove <name>
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection remove <name>
 
 # Rename a collection
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection rename <old-name> <new-name>
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection rename <old-name> <new-name>
 ```
 
 ## Listing Files
 
 ```bash
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd ls
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd ls [collection[/path]]
+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__ 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>
+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__ 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]
+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`
@@ -66,16 +66,16 @@ INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd multi-get <pattern> [-l N] [--max-bytes
 
 ```bash
 # Show index status and collections
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
 
 # Re-index all collections
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd update [--pull]
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd update [--pull]
 
 # Create vector embeddings (900 tokens/chunk, 15% overlap)
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed [-f]
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd embed [-f]
 
 # Remove cache and orphaned data, vacuum DB
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd cleanup
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd cleanup
 ```
 
 > After bulk ingest sessions, run `update` then `embed` to keep the index fresh.
@@ -108,28 +108,28 @@ INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd cleanup
 
 ```bash
 # Hybrid search across all collections
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query "distributed systems consensus"
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query "distributed systems consensus"
 
 # Search only the wiki collection, JSON output
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query -c wiki "transformer architecture" --json
+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__ bunx @tobilu/qmd search -c wiki "kafka" -n 10 --md
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd search -c wiki "kafka" -n 10 --md
 
 # Vector search with full documents
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd vsearch "attention mechanism" --full
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd vsearch "attention mechanism" --full
 
 # Filter by score threshold
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd query "machine learning" --all --min-score 0.7
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query "machine learning" --all --min-score 0.7
 ```
 
 ## MCP Server
 
 ```bash
-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
+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
@@ -145,24 +145,24 @@ Note: use `INDEX_PATH` env var rather than `--index` — `INDEX_PATH` accepts a
 ### First-time setup for this vault
 ```bash
 # Handled by the /setup skill:
-bun scripts/qmd/setup.ts
-bun scripts/qmd/reindex.ts
+pnpm qmd:setup
+pnpm qmd:reindex
 ```
 
 ### After a bulk ingest session
 ```bash
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd update
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd embed
+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__ bunx @tobilu/qmd query -c wiki "<topic>"
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd query -c wiki "<topic>"
 
 # Get a specific file
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd get wiki/distributed-systems.md
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd get wiki/distributed-systems.md
 
 # Get multiple related files
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd multi-get "wiki/kafka.md,wiki/distributed-systems.md" --md
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd multi-get "wiki/kafka.md,wiki/distributed-systems.md" --md
 ```

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

@@ -21,7 +21,7 @@ All commands run from the vault root.
 
 Run:
 ```bash
-bun scripts/qmd/setup.ts
+pnpm qmd:setup
 ```
 
 Registers the two core qmd collections (`wiki`, `raw-sources`) and their path-level context descriptions. Idempotent — safe to re-run.
@@ -30,7 +30,7 @@ Registers the two core qmd collections (`wiki`, `raw-sources`) and their path-le
 
 Run:
 ```bash
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 ```
 
 Scans all collections for new/changed files and generates vector embeddings. The first run downloads ~2GB of local GGUF models — this will take a while.
@@ -39,7 +39,7 @@ Scans all collections for new/changed files and generates vector embeddings. The
 
 Skip step 1 and run only:
 ```bash
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 ```
 
 Do **not** re-run after every single file edit — batch it after a session.
@@ -50,17 +50,17 @@ Run these three commands to confirm everything is working:
 
 ```bash
 # List registered collections (expect: wiki, raw-sources)
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd collection list
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd collection list
 
 # List registered contexts
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd context list
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd context list
 
 # Show index status and embedding counts
-INDEX_PATH=__QMD_PATH__ bunx @tobilu/qmd status
+INDEX_PATH=__QMD_PATH__ pnpm dlx @tobilu/qmd status
 ```
 
 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
-- If `bunx @tobilu/qmd` commands fail after setup, re-run step 1 then step 2
+- `node` and `pnpm` are managed via `mise` — ensure `mise install` and `pnpm install` have been run before setup
+- If `pnpm dlx @tobilu/qmd` commands fail after setup, re-run step 1 then step 2

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__ bunx @tobilu/qmd query -c wiki "<source topic and key claims>"` to surface related existing 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.
 - 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__ bunx @tobilu/qmd query -c wiki "<question>"` to surface semantically relevant pages.
+- Run `INDEX_PATH=__QMD_PATH__ 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.
 
@@ -211,21 +211,21 @@ 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 at `__QMD_PATH__` (gitignored).
+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).
 
 Key commands:
 
 | Command | Use |
 |---------|-----|
-| `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 |
+| `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 |
 
 Add `--json` for structured output. Omit `-c wiki` to search all collections (wiki, raw-sources, human, daily-notes).
 
 **Re-indexing:** After a bulk ingest session run:
 ```bash
-bun scripts/qmd/reindex.ts
+pnpm qmd:reindex
 ```
 Do NOT re-index after every single file edit.

package/template/README.md

@@ -13,10 +13,13 @@ Inspired by [Andrej Karpathy's approach to LLM-powered knowledge management](htt
 ## Quick start
 
 ```bash
-# 1. Install tools
+# 1. Install tools (node + pnpm via mise)
 mise install
 
-# 2. Open Claude Code
+# 2. Install dependencies
+pnpm install
+
+# 3. Open Claude Code
 claude
 ```
 
@@ -185,7 +188,7 @@ After a bulk ingest session, re-index to keep search current:
 /brain-refresh
 ```
 
-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).
+This wraps `pnpm qmd:reindex` — 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/mise.toml

@@ -1,2 +1,3 @@
 [tools]
-bun = "1.3.10"
+node = "22"
+pnpm = "10.8.0"

package/template/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "claude-second-brain-vault",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "qmd:setup": "tsx scripts/qmd/setup.ts",
+    "qmd:reindex": "tsx scripts/qmd/reindex.ts"
+  },
+  "dependencies": {
+    "@tobilu/qmd": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "packageManager": "pnpm@10.8.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3",
+      "esbuild",
+      "node-llama-cpp",
+      "tree-sitter-go",
+      "tree-sitter-javascript",
+      "tree-sitter-python",
+      "tree-sitter-rust",
+      "tree-sitter-typescript"
+    ]
+  }
+}

package/template/scripts/qmd/reindex.ts

@@ -4,10 +4,10 @@
  * First run downloads ~2GB of GGUF models — expected, one-time.
  *
  * Run from vault root:
- *   bun scripts/qmd/reindex.ts
+ *   pnpm qmd:reindex
  *
  * Suitable as a cronjob:
- *   0 * * * * cd /home/user/my-brain && bun scripts/qmd/reindex.ts
+ *   0 * * * * cd /home/user/my-brain && pnpm qmd:reindex
  */
 
 import { createStore } from "@tobilu/qmd"

package/template/scripts/qmd/setup.ts

@@ -3,16 +3,17 @@
  * Safe to re-run: skips collections that already exist, upserts contexts.
  *
  * Run once from vault root:
- *   bun scripts/qmd/setup.ts
+ *   pnpm qmd:setup
  *
  * After setup, index the vault:
- *   bun scripts/qmd/reindex.ts
+ *   pnpm qmd:reindex
  */
 
 import { createStore } from "@tobilu/qmd"
-import { join } from "path"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
 
-const VAULT = join(import.meta.dir, "../..")
+const VAULT = join(dirname(fileURLToPath(import.meta.url)), "../..")
 const DB = "__QMD_PATH__"
 
 const store = await createStore({ dbPath: DB })
@@ -53,4 +54,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")
 
-console.log("\nSetup complete. Run: bun scripts/qmd/reindex.ts")
+console.log("\nSetup complete. Run: pnpm qmd:reindex")

package/template/scripts/qmd/tsconfig.json

@@ -1,29 +1,19 @@
 {
   "compilerOptions": {
-    // Environment setup & latest features
     "lib": ["ESNext"],
     "target": "ESNext",
-    "module": "Preserve",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "moduleDetection": "force",
-    "jsx": "react-jsx",
     "allowJs": true,
 
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
     "noEmit": true,
 
-    // Best practices
     "strict": true,
     "skipLibCheck": true,
     "noFallthroughCasesInSwitch": true,
     "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false
+    "noImplicitOverride": true
   }
 }

package/template/scripts/qmd/package.json

@@ -1,14 +0,0 @@
-{
-  "name": "qmd",
-  "private": true,
-  "peerDependencies": {
-    "typescript": "^5"
-  },
-  "dependencies": {
-    "@tobilu/qmd": "^2.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^25.6.0",
-    "@types/bun": "latest"
-  }
-}