Skip to content

Fastest way to scaffold your LLM powered personal knowledge base - Obsidian, Claude Code, qmd, Github

feat: auto-register qmd collections + add CLI reference docs

jessepinkman99002c717d71ce08
diff --git a/.github/workflows/pack-test.yml b/.github/workflows/pack-test.yml
index 94ec7c5..969470d 100644
--- a/.github/workflows/pack-test.yml
+++ b/.github/workflows/pack-test.yml
@@ -75,6 +75,7 @@ jobs:
check "~/.claude/skills/brain-ingest/.csb-version" "$HOME/.claude/skills/brain-ingest/.csb-version"
check "~/.claude/skills/brain-search/.csb-version" "$HOME/.claude/skills/brain-search/.csb-version"
check "~/.claude/skills/brain-refresh/.csb-version" "$HOME/.claude/skills/brain-refresh/.csb-version"
+ check ".qmd/index.sqlite (created by auto qmd:setup)" "$VAULT/.qmd/index.sqlite"
grep_check() {
local label="$1"
diff --git a/bin/create.js b/bin/create.js
old mode 100644
new mode 100755
index 449d570..3303a74
--- a/bin/create.js
+++ b/bin/create.js
@@ -687,6 +687,28 @@ async function createBrain(initialName) {
if (pnpmOk) spin.stop("dependencies installed")
else spin.stop("pnpm install failed — run it manually inside your vault", 1)
+ // 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 qmdOk = run(["mise", "exec", "--", "pnpm", "qmd:setup"], targetDir)
+ if (qmdOk) spin.stop("qmd collections registered")
+ else spin.stop("pnpm qmd:setup failed — run it manually inside your vault", 1)
+ } 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")
const skillResult = await installGlobalSkills({ isInteractive })
@@ -777,7 +799,8 @@ async function createBrain(initialName) {
const nextSteps = [
`${pc.cyan(`cd ${brainDisplayPath}`)}`,
- `${pc.cyan("claude")} open Claude Code, then run ${pc.bold("/setup")}`,
+ `${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")
diff --git a/docs/pages/cli.mdx b/docs/pages/cli.mdx
new file mode 100644
index 0000000..b0dced7
--- /dev/null
+++ b/docs/pages/cli.mdx
@@ -0,0 +1,92 @@
+# CLI Reference
+
+The `claude-second-brain` CLI creates and manages brains registered in `~/.claude-second-brain/config.toml`. Run it via `npx claude-second-brain`, `pnpm dlx claude-second-brain`, or — if installed globally with `npm i -g claude-second-brain` — the shorter `csb` alias.
+
+All examples below use `claude-second-brain`; substitute `csb` if you've installed it globally.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `claude-second-brain` | Create a new brain (interactive). |
+| `claude-second-brain <name>` | Create a new brain named `<name>`, skipping the name prompt. |
+| `claude-second-brain ls` | List all registered brains. The default brain is marked with `*`. |
+| `claude-second-brain rm <name>` | Delete a brain directory and remove its entry from `config.toml`. |
+| `claude-second-brain path [flags]` | Print the path of the default (or named) brain. |
+| `claude-second-brain qmd [flags] -- …` | Run `qmd` against the default (or named) brain. |
+| `claude-second-brain help` | Show usage. |
+
+`ls` is also available as `list`, and `rm` as `remove`.
+
+## Create a brain
+
+```bash
+npx claude-second-brain # interactive — prompts for name + remote
+npx claude-second-brain my-brain # skip the name prompt
+```
+
+Creates the brain at `~/.claude-second-brain/<name>/`, runs `mise install`, `pnpm install`, `pnpm qmd:setup`, `git init`, and registers it in `~/.claude-second-brain/config.toml`. The first brain created is set as the default.
+
+During the interactive flow the CLI asks:
+
+- **Brain name** — defaults to `my-brain`.
+- **Git remote** — `GitHub`, `Cloudflare Artifacts`, or `Skip`. See [GitHub](/remotes/github) and [Cloudflare Artifacts](/remotes/cloudflare-artifacts).
+- **Repo name** — only shown when a remote is selected; defaults to the brain name.
+- **Artifacts namespace** — only shown for Cloudflare; defaults to `default`.
+- **Register qmd collections now?** — confirms running `pnpm qmd:setup`.
+
+## List brains
+
+```bash
+npx claude-second-brain ls
+```
+
+Prints each registered brain with its path, creation date, and git remote. The default brain is shown in bold with a `*` marker.
+
+## Remove a brain
+
+```bash
+npx claude-second-brain rm my-brain # prompts for confirmation
+npx claude-second-brain rm my-brain --yes # skip the confirmation
+npx claude-second-brain rm # interactive — pick from a list
+```
+
+Deletes the brain's directory under `~/.claude-second-brain/` and removes its entry from `config.toml`. If you remove the default brain and others remain, the first remaining brain becomes the new default.
+
+Flags:
+
+- `-y`, `--yes` — skip the confirmation prompt.
+
+## Print a path
+
+```bash
+npx claude-second-brain path # default brain root
+npx claude-second-brain path --qmd # default brain's qmd index
+npx claude-second-brain path --config # ~/.claude-second-brain/config.toml
+npx claude-second-brain path --brain work --qmd # a specific brain's qmd index
+```
+
+Flags:
+
+- `--root` *(default)* — the brain's directory (e.g. `~/.claude-second-brain/my-brain`).
+- `--qmd` — the brain's qmd SQLite index (e.g. `~/.claude-second-brain/my-brain/.qmd/index.sqlite`).
+- `--config` — the central config path. Ignores `--brain`.
+- `--brain <name>` — target a specific brain instead of the default.
+
+Used by the global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) to resolve paths at call time so they work from any working directory.
+
+## Run qmd against a brain
+
+```bash
+npx claude-second-brain qmd -- query -c wiki "distributed systems"
+npx claude-second-brain qmd --brain work -- search -c wiki "kafka"
+```
+
+Forwards all arguments after `--` to `npx @tobilu/qmd`, with `INDEX_PATH` set to the resolved brain's qmd index. Flags:
+
+- `--brain <name>` — target a specific brain instead of the default.
+- `--` — end of CLI flags; everything after is passed to qmd verbatim.
+
+## Exit status
+
+Every command exits non-zero on failure (invalid brain name, missing config, etc.) and writes the error to stderr.
diff --git a/docs/pages/getting-started.mdx b/docs/pages/getting-started.mdx
index 6007443..92a1eed 100644
--- a/docs/pages/getting-started.mdx
+++ b/docs/pages/getting-started.mdx
@@ -57,6 +57,8 @@ Open `~/.claude-second-brain/my-brain/` as a vault in Obsidian — the folder is
Run `npx claude-second-brain` (or `csb` if installed globally) again to create additional brains. Each gets its own folder under `~/.claude-second-brain/` and its own isolated qmd index. The global skills (`/brain-ingest`, `/brain-search`, `/brain-refresh`) always operate on the **default brain** in `~/.claude-second-brain/config.toml`. The first brain created is set as the default automatically.
+See the [CLI Reference](/cli) for `ls`, `rm`, `path`, and `qmd` subcommands that manage and target specific brains.
+
## Access from anywhere
**Edit anywhere — Claude Code on desktop or mobile.** Claude Code's GitHub integration lets you open the repo and work from anywhere — ingest a source, run a query, or update a page from your phone.
diff --git a/template/.claude/skills/setup/SKILL.md b/template/.claude/skills/setup/SKILL.md
index 029487f..2d0b98e 100644
--- a/template/.claude/skills/setup/SKILL.md
+++ b/template/.claude/skills/setup/SKILL.md
@@ -7,8 +7,8 @@ argument-hint: "Optional: 'reindex' to skip registration and only re-index files
# Vault Setup
## When to Use
-- First-time setup after cloning
-- Re-registering qmd collections (e.g., after config changes)
+- First-time indexing (collections are already registered by `npx claude-second-brain`)
+- Re-registering qmd collections after manual config changes
- Re-indexing after a bulk wiki ingest session (run step 2 only)
## Procedure
@@ -17,14 +17,14 @@ All commands run from the vault root.
### Full Setup (first time)
-**Step 1 — Register collections and contexts**
+**Step 1 — Register collections and contexts** *(already done by the scaffold — re-run only if needed)*
Run:
```bash
pnpm qmd:setup
```
-Registers the two core qmd collections (`wiki`, `raw-sources`) 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. `npx claude-second-brain` runs this automatically after `pnpm install`, so a fresh vault already has collections registered.
**Step 2 — Index files and generate embeddings**
diff --git a/vocs.config.ts b/vocs.config.ts
index 53aad7a..0340a1f 100644
--- a/vocs.config.ts
+++ b/vocs.config.ts
@@ -37,6 +37,7 @@ export default defineConfig({
sidebar: [
{ text: 'Introduction', link: '/' },
{ text: 'Getting Started', link: '/getting-started' },
+ { text: 'CLI Reference', link: '/cli' },
{
text: 'Concepts',
items: [