claude-second-brain 0.4.0 → 0.5.0

package/README.md

@@ -100,7 +100,7 @@ The wiki ships with a set of slash commands that cover the full workflow. No man
 
 ### Daily workflow
 
-**`/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.
+**`/brain-ingest`** — Drop a file into `raw-sources/articles/`, `raw-sources/pdfs/`, or `raw-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.
 
 **`/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.
 
@@ -133,6 +133,61 @@ 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["raw-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  │        │ /brain-ingest       │        │     Wiki grows      │
@@ -171,7 +226,7 @@ All pages cross-link with Obsidian `[[wikilinks]]`. Contradictions are flagged w
 ```
 my-brain/
 ├── CLAUDE.md              ← The schema. Claude reads this every session.
-├── sources/               ← Your raw inputs. Claude never modifies these.
+├── raw-sources/           ← Your raw inputs. Claude never modifies these.
 │   ├── articles/
 │   ├── pdfs/
 │   └── personal/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-second-brain",
-  "version": "0.4.0",
-  "description": "Scaffold an LLM-maintained Obsidian knowledge wiki",
+  "version": "0.5.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"

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

@@ -1,7 +1,7 @@
 ---
 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"
+argument-hint: "File path (e.g. raw-sources/articles/my-article.md), URL, or leave blank if source is pasted in chat"
 ---
 
 # Brain Ingest
@@ -10,7 +10,7 @@ Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 
 ## Inputs
 
-- **File path** — a file in `sources/articles/`, `sources/pdfs/`, or `sources/personal/`
+- **File path** — a file in `raw-sources/articles/`, `raw-sources/pdfs/`, or `raw-sources/personal/`
 - **URL** — fetch and read the full content directly
 - **Pasted text** — treat whatever the user has shared as the source
 
@@ -63,6 +63,6 @@ Runs the full 9-step ingest workflow defined in CLAUDE.md. Do not skip steps.
 
 ## Hard Rules
 
-- Never modify anything in `sources/` — immutable raw inputs
+- Never modify anything in `raw-sources/` — immutable raw inputs
 - Every wiki page must have frontmatter with at least `type` and `updated`
 - One source summary page per source — never merge two sources into one

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

@@ -12,7 +12,7 @@ Redesigns the qmd schema based on what the wiki actually contains today, then re
 
 - 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
+- After significant reorganization of `wiki/` or `raw-sources/` folder structure
 - Never as a routine refresh — for that, use `/brain-refresh`
 
 ## Procedure
@@ -32,7 +32,7 @@ All commands run from the vault root.
 
 ### Step 2 — Analyze the wiki
 
-- Glob `wiki/**/*.md` and `sources/**/*.md`
+- Glob `wiki/**/*.md` and `raw-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.
 
@@ -116,4 +116,4 @@ Confirm the new collections appear, contexts match the plan, and document/embedd
 - 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
+- Do not touch `wiki/`, `raw-sources/`, or any user content — this skill changes the index schema, not the data

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

@@ -11,7 +11,7 @@ Refreshes the qmd index so search reflects the current state of the vault. Wraps
 ## 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
+- After manual edits to `wiki/` or `raw-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
 

package/template/CLAUDE.md

@@ -18,7 +18,7 @@ Claude is responsible for: summarizing, cross-referencing, filing, and maintaini
 ```
 claude-second-brain/
 ├── CLAUDE.md              ← This file. The schema.
-├── sources/               ← Raw source material. IMMUTABLE — Claude never modifies these.
+├── raw-sources/           ← Raw source material. IMMUTABLE — Claude never modifies these.
 │   ├── articles/          ← Web articles saved as markdown
 │   ├── pdfs/              ← PDF files or extracted text
 │   └── personal/          ← Personal notes flagged for ingestion
@@ -95,7 +95,7 @@ Run this workflow whenever the user adds a new source. Do not skip steps.
 
 **Step 1 — Read the source**
 - If URL: fetch and read the full content.
-- If file in `sources/`: read it with the Read tool.
+- If file in `raw-sources/`: read it with the Read tool.
 - If pasted text: treat as the source.
 
 **Step 2 — Discuss with the user**
@@ -199,7 +199,7 @@ N issues found, N fixed. [Brief summary of notable findings.]
 
 ## Hard Rules
 
-1. **Never modify anything in `sources/`**. These are immutable raw inputs.
+1. **Never modify anything in `raw-sources/`**. These are immutable raw inputs.
 2. **Never touch existing vault files** (daily-notes, misc, ideas, root-level .md files, .obsidian/). The wiki lives only in `wiki/`.
 3. **Always append to `wiki/log.md`** — never overwrite it.
 4. **One source summary per ingested source** in `wiki/sources/`. Never merge two sources into one summary page.

package/template/README.md

@@ -36,7 +36,7 @@ Registers the qmd collections and generates local vector embeddings. First run d
 
 ### 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.
+**`/brain-ingest`** — Add a file to `raw-sources/articles/`, `raw-sources/pdfs/`, or `raw-sources/personal/`, then run `/brain-ingest`. Claude summarizes the source, asks what aspects matter most, updates related wiki pages, flags contradictions, and logs everything.
 
 **`/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.
 
@@ -54,6 +54,63 @@ Registers the qmd collections and generates local vector embeddings. First run d
 
 ---
 
+## 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["raw-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
 
 If this repo lives inside your iCloud Drive folder, Obsidian Mobile reads it with no extra setup. Graph view, backlinks, offline access — all working. The Git plugin handles sync automatically when you commit and push.
@@ -81,7 +138,7 @@ All pages cross-link with Obsidian `[[wikilinks]]`. Contradictions are flagged w
 ```
 claude-second-brain/
 ├── CLAUDE.md              ← The schema. Claude reads this every session.
-├── sources/               ← Your raw inputs. Claude never modifies these.
+├── raw-sources/           ← Your raw inputs. Claude never modifies these.
 │   ├── articles/          ← Web articles saved as markdown
 │   ├── pdfs/              ← PDFs or extracted text
 │   └── personal/          ← Brain dumps, rough notes

package/template/scripts/qmd/setup.ts

@@ -32,7 +32,7 @@ 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("raw-sources", "raw-sources", "**/*.md")
 
 // --- Global context ---
 console.log("\nContexts:")
@@ -47,7 +47,7 @@ await store.addContext("wiki", "",         "LLM-maintained synthesized knowledge
 await store.addContext("wiki", "/sources", "Source summaries — one page per ingested source, with abstract, key claims, and synthesis notes")
 await store.addContext("wiki", "/qa",      "Filed Q&A answers that synthesize multiple wiki pages around a notable question")
 
-// sources/
+// raw-sources/
 await store.addContext("raw-sources", "",          "Raw source material — immutable originals, never modified after ingestion")
 await store.addContext("raw-sources", "/articles", "Web articles saved as markdown")
 await store.addContext("raw-sources", "/pdfs",     "PDF files or their extracted text")