v0.14.0 - The Harvest

We scanned all 408 forks of this repo and shipped the gold back upstream

Round 2 of the fork sweep (round 1 was at 166 forks, 2026-05-30). Every diverging fork was compared and deep-read; the best ideas landed upstream the same day, each credited to the fork that built it in FORK_INSIGHTS.md - and where a stalled PR existed, its author is a co-author on the merge.

New thinking tool: /obsidian-brainstorm (#153)

The skill's 45th command and its first stateful, multi-turn tool: a Socratic interview - one question per turn, six question categories, convergence-gated - that ends in a design note with named alternatives and exactly one (Recommended). Grounds its questions in your vault's own decisions and contradictions.

Bounded vault recall (#155, opt-in)

A UserPromptSubmit hook that injects a small brief of relevant vault notes into every prompt: max 4 notes / ~900 chars, abstains when confidence is low, fail-closed, and logs every decision for audit. Inert until you arm it (OBSIDIAN_RECALL_ENABLED=1).

Research toolkit upgrades (#147, #148)

• Brave Search and Tavily join /research free mode when keyed; the pool stays key-less without them
• Full-page source reading: /research-deep fetches its top cited pages via Tavily Extract and synthesizes from actual page text, not snippets
• /youtube summarizes via Gemini free tier with automatic Grok fallback
• The usage ledger is fail-soft and now covers Perplexity + Gemini, labeled per command

Search and safety (#151, #152)

• supersedes: [[B]] in an ADR now fades B in search results even if B's own status was never updated; the pure-lexical path finally gets the freshness rerank it was documented to have
• The write-time hook detects secret material (keys, tokens, private-key blocks) in vault notes; the unattended bg-agent routes sensitive content to a staging note and never writes raw secrets anywhere

Operations (#149, #150, #154)

• scripts/update-vault-integration.sh: a guarded updater for copied dist builds - ff-only pull, smoke-test gate, backup + rollback
• The retrieval eval benchmarks any external engine (--mode external) on the same cases and metrics
• Portuguese (pt-BR) triggers for all 45 commands (translation base by @renatofaria-ia)

Also

• codex-cli and opencode builds deprecated in favor of the unified agent-skills tree (thanks @Litash, #146)
• Full-repo hygiene sweep: 8 privacy fixes, ~15 staleness fixes, SEO/AEO surfaces brought current incl. a four-releases-frozen CITATION.cff (#156)

Fork credits this round: the local-first memory fork, the api-ledger fork, the brave-source fork, the web-reader fork, the updater fork, the brainstorm fork, the structured-rag eval fork, the OKF-first fork. Test suite: 191.

Full detail in CHANGELOG.md.

v0.13.0 - The Open Standard

One tree, every harness

Codex CLI, OpenCode, Google Antigravity, and GitHub Copilot CLI all converged on the same open Agent Skills standard: workspace skills at .agents/skills/<name>/SKILL.md. This release meets them there with one build that serves them all - and any future harness on the standard works with zero repo changes.

The unified agent-skills build (#139, #141)

bash scripts/build.sh --platform agent-skills emits one spec-compliant tree: 43 command skills plus a shared obsidian-core engine skill (the Python toolkit, the AI-first write spec, and its uv project). Each skill is self-sufficient - vault-root resolution via $OBSIDIAN_VAULT_PATH (or the working directory) and the embedded write spec, so no session-start hook is needed. Install with npx skills add ./dist/agent-skills -a codex -a opencode -a antigravity or a plain cp -R.

Live-verified: skills.sh discovers exactly 44 skills; OpenCode's strict validator loads all 44 with zero warnings; the engine runs from the installed tree with dependencies resolving from the shipped pyproject. A new trigger-mode: proactive source key encodes the selection policy per skill (capture commands trigger proactively; everything else waits to be asked). Proposed and prototyped by @Litash.

GitHub Copilot CLI: covered without an adapter (#133)

Copilot CLI reads .agents/skills/ natively (per GitHub's docs), so the unified build already serves it - verified with a real npx skills add ... -a github-copilot install. The scope question closed with zero new maintenance surface. Thanks @CowboyPurest for the prototype and platform research.

Tavily as an optional research source (#97, #145)

When TAVILY_API_KEY is set, Tavily joins the /research free-mode pool as an extra web source; without it the pool stays fully key-less. Plain requests, Bearer auth, shared cache - no SDK dependency. Proposed by @manisrinivasan2k1.

Per-vault health-check excludes (#140, #142)

<vault>/.vault-config.json extends vault_health.py's exclude list (exclude-dirs + exclude-paths, strictly additive, malformed files ignored silently). On the reporter's 12k-note research vault: findings dropped 15,045 to 2,321 and scan time 5+ minutes to ~19 seconds. Proposed by @Rongles-World.

Also in this release

• Security: link triage can no longer write outside the vault (stub paths are contained to wiki/stubs/).
• Data safety: note rewrites are atomic - an interrupted write can never wipe a note.
• The PostCompact bg-agent survives large summaries on Windows (stdin, not argv), runs with --strict-mcp-config (thanks @Facens), and logs per-run JSONL observability (thanks @sad85520).
• The Hermes install story now matches how Hermes actually works - blueprints never arm on install (thanks @Litash).
• Slash commands run under the plugin install, not just the maintainer's clone; the skill installer registers the session-context hook.
• vault_stats.py honors OBSIDIAN_VAULT_PATH; Telegram journal writes to native folders on Obsidian-style vaults (thanks @yannick-opg).
• Every discoverability surface now tells the same seven-platform story (Claude Code, Codex, Gemini CLI, OpenCode, Antigravity, Hermes, Pi), the SEO layer caught up two releases, and the banner got its seventh logo.
• Retrieval re-baselined on a live vault after a week of growth: stable, no regression.
• New README Contributors section - 18+ external contributors, and stalled proposals get reimplemented with the original author credited as co-author.

Full detail in CHANGELOG.md. Test suite: 177.

v0.12.0 - The Stress Test

We stress-tested our own tool with 32 AI agents. Then fixed what they found.

A 4-lane adversarial audit (every command file, hostile synthetic vaults against every script, live retrieval quality on a 2,300-note vault, and a competitor teardown) produced 175 findings. This release closes ~160 of them across 24 PRs (#100-#123), in four phases.

Phase A - Data safety: tools that cannot eat your notes

• heal_links/triage_links could permanently corrupt non-UTF-8 notes and silently rewrite line endings: strict UTF-8 in, byte-exact out, with non-UTF-8 files skipped loudly (#100)
• One dangling symlink no longer kills the health check, the healers, or the exporter (#101)
• The link healer only auto-fixes certain matches now: no more foreign-alphabet links "matching" unrelated notes, no [[C++]] -> C.md, no edits inside code fences (#102)
• A leading BOM can't hide frontmatter; exports translate faithfully or say they failed; stats stopped double-counting after exports; link_graph actually mirrors vault_health (pinned by a drift-alarm test) (#103-#107)
• A fresh bootstrap passes its own health check with zero findings - now a CI invariant (#108)

Phase B - Retrieval: search 2-4x better, measured honestly

• The eval harness itself was lying (its "lexical" mode was secretly fused; "hybrid" double-counted semantic). Straightened first, so every claim below is real (#109)
• Query-aware defaults: exact tokens go lexical, semantic votes lead the fusion (#110, re-tuned in #116)
• The silent 2,000-file scan cap is gone; ranking learned that volume is not relevance (logs fade, dossiers speak per-section); the index reached 100% coverage via adaptive chunk-splitting (#111-#113)
• Freshness: "current"-intent queries stop surfacing superseded notes and declined offers above the current truth (#114)
• Multilingual default model (bge-m3): non-English queries went from ~0 to working, and English improved too. Migration: ollama pull bge-m3, then rebuild the index once (--build, ~10 min; existing indexes keep answering correctly until you do) (#115)
• The reference numbers are committed in scripts/eval/BASELINE.md: keyword recall@10 1.0, paraphrase recall@10 0.77, non-English recall@5 0.63 (#116)

Phase C - Commands and docs tell one truth

• 37 hardcoded folder paths across 18 commands now resolve via the folder map - /obsidian-export no longer produces an empty snapshot on default-bootstrapped vaults (#117)
• 50 banned characters purged from instruction files - the skill stops teaching agents to write what its own validation hook blocks (#118)
• Schema reconciliation: 4 missing note-type schemas added, 8 commands aligned, and the real-world exceptions (quick capture, kanban boards, raw sources, vault-surface files) are now documented law the hook understands (#119)
• 20 "manual for a different machine" bugs fixed, including a status check that read its own output as evidence (#120)
• SKILL.md's six drifted sections now defer to the command files as the single source of truth; README counts match the filesystem; builds ship no Python bytecode (#121)
• Five new CI lints enforce all of the above permanently

Phase D - The front door

• The README's one-line installer pointed at a file that did not exist. It exists now (idempotent), prerequisites are stated up front, there's a path for users with no vault yet, and the bootstrapper never overwrites your files - keep-by-default, --force is the consent (#122)
• Every platform dist ships a runnable Python project, so the research toolkit works on Codex, Gemini, OpenCode, Hermes, and Pi - not just Claude Code (#123)

After the sprint closed (same day)

• External contribution (one of 17 outside contributors to date): /research and /research-deep silently ignored a PERPLEXITY_API_KEY set in the config .env - the free-vs-paid decision ran before anything had loaded the file. Root-caused and fixed by @MichaelHabermas (#125, fixes #124), now fenced in CI
• The audit's three never-tested surfaces (bg-agent hook, MCP write path, Telegram ingest) ran live; the one real bug found - Telegram ingest hardcoding wiki-style folders - is fixed with folder-map resolution (#126)

Numbers

• Test suite: 30 -> 129 tests, including 11 permanent invariants (byte-safety, ghost resilience, drift alarms, folder/character/schema/roster lints, the showroom rule, front-door safety, dist runnability)
• Full changelog: see CHANGELOG.md under 0.12.0

Breaking / migration notes: the default embedding model is now bge-m3 (OBSIDIAN_EMBED_MODEL overrides; one-time index rebuild recommended); vault_stats accepts --path (old --vault still works); bootstrap keeps existing files by default (use --force for the old overwrite behavior); the semantic index format is v2 (rebuilds automatically invalidate old caches).

v0.11.1 - Pi Coding Agent

Adds Pi Coding Agent as a 6th build target (PR #83, by @Gepetdo).

bash scripts/build.sh --platform pi emits dist/pi/ - a native Pi package: a package.json declaring pi.prompts/pi.skills, one prompt template per command under .pi/prompts/ (invoke /obsidian-save, /obsidian-daily, ...), and a discovery skill at .pi/skills/obsidian-second-brain/SKILL.md (/skill:obsidian-second-brain), with the AI-first rules and Python helpers alongside.

Install: pi install ./dist/pi (or copy dist/pi/.pi/ into your vault root).

Purely additive - the adapter is auto-discovered by build.sh, so the existing five platforms (Claude Code, Codex, Gemini, OpenCode, Hermes) are untouched. All 6 platforms build, 27 smoke tests pass.

Thanks @Gepetdo for the contribution.

v0.11.0 - The Retriever

Search went from broken to hybrid. This release seals a large skill-audit + retrieval sprint: every command was real-tested, keyword search was fixed ~7x, and an optional local-and-private semantic layer now fuses in for meaning-based recall. It also ships the previously-unreleased Hermes, MCP-connector, Telegram-journal, and OKF-export work.

Breaking changes (migration)

Two command consolidations from the audit. Natural-language triggers still route correctly; only the explicit slash forms changed:

• Calendar: /obsidian-agenda, /obsidian-meeting, /obsidian-schedule, and the old calendar-reconcile are now one command with modes.
  • /obsidian-agenda week -> /obsidian-calendar agenda week
  • /obsidian-meeting last -> /obsidian-calendar meeting last
  • /obsidian-schedule task:... -> /obsidian-calendar schedule task:...
  • calendar gap-check -> /obsidian-calendar reconcile
• Decisions: /obsidian-adr -> /obsidian-decide --formal (default /obsidian-decide still logs lightweight decisions).

Highlights

Retrieval (the headline)

• Keyword search fixed ~7x in vault_ops.search (the /obsidian-find + MCP engine): stopword filtering, raw/log de-weighting, and BM25-style sublinear-TF + length normalization. Measured on a 1,000+ note vault: recall@1 0% -> 57%, recall@10 5.7% -> 80%.
• Optional local semantic search + hybrid (scripts/eval/semantic_search.py): embeddings from a local model (Ollama by default; pluggable to any OpenAI-compatible endpoint), chunk + mean-pool for long notes, cosine + Reciprocal-Rank-Fusion, a privacy carve-out, and a cached index. Fused into search with silent lexical fallback so it never breaks or hangs. Paraphrased recall@10 17% -> 51%; keyword hybrid -> 91%. Off by default; opt-in by setup. OBSIDIAN_SEARCH_SEMANTIC=0 to disable.
• /obsidian-retrieval-eval - measures search quality (recall@k, MRR) so changes are verified, not guessed.

New commands

• /obsidian-distill - condense a source into claims, each with provenance back to the exact block.
• /obsidian-board-hygiene - bulk-triage a stale kanban board.

Bigger platform work (previously unreleased)

• Hermes Agent native skill build + MCP curator tools + scheduled-agent blueprints.
• MCP server (integrations/obsidian-mcp-server/) exposing the vault to any MCP client.
• Telegram journal bot for phone capture + /obsidian-catchup.
• OKF export (/obsidian-export okf) for Open Knowledge Format interop.

Also changed

• Folder resolution is spec-driven (references/folder-map.md) - 12 commands no longer hardcode folder names.
• /research-deep no longer fabricates vault paths during propagation (grounds every target first).
• /podcast accepts Spotify URLs (bridges to the public RSS feed).
• /obsidian-save absorbs /obsidian-log (writes the dev-log too).
• /create-command fast-path skips the interview when the seed is complete.
• scripts/link_graph.py - /obsidian-visualize no longer reads the whole vault into context.

44 commands, multi-platform, 26 smoke tests green. Full detail in CHANGELOG.md.

v0.10.0 - The Architect

Your code projects, documented in the same brain as your ideas and decisions.

Headline: /obsidian-architect

Point it at a software project and it writes a maintained set of architecture notes into your vault - an overview (with a Mermaid diagram and inferred personas), one note per core module, and a key-decisions note. Re-run it to refresh: sentinel markers (<!-- @generated --> / <!-- @user -->) mean a refresh updates only the generated content and never clobbers your hand-edits. A deterministic, stdlib-only scanner produces the facts; Claude synthesizes the prose. Built lean (one scanner + one command).

Also new since v0.9.0

• /obsidian-calendar - reconciles the vault against your calendar, flags commitments that are not scheduled (flag only).
• /vault-deep-synthesis [topic] - cross-references every note on a topic: agreements, contradictions, stale claims, gaps.
• /idea-discovery - ranks 3-5 next-direction candidates from ideas, open questions, and orphan research.
• /obsidian-panel - convenes a panel of distinct lenses on a decision; a multi-persona complement to /obsidian-challenge.
• Codex executable runner (scripts/run-command.sh + wrappers) - run the commands on Codex CLI, where the markdown was previously inert.
• commit-decisions miner - surfaces decision-shaped commits as ADR candidates for /obsidian-adr.
• Substitution-character CI gate - fails any PR that introduces an em-dash (or other banned character) in source prose.

43 commands total. The fork-merge project that drove v0.9.0 and v0.10.0 is now complete: ~32 of the 50 analyzed fork ideas shipped, every top-priority item done. See FORK_INSIGHTS.md for the full analysis and the intentional won't-do list. Full detail in CHANGELOG.md.

v0.9.0 - Free key-less research, calendar commands, anti-hallucination guards

The biggest release since the multi-platform ship. Headlined by free, key-less research - the #1 adoption barrier is gone.

Highlights

• /research and /research-deep now work with no API keys. When no PERPLEXITY_API_KEY is set, they aggregate free, key-less sources in parallel (Wikipedia, HackerNews, arXiv, Reddit, Lobsters, dev.to, OpenAlex, Semantic Scholar, CrossRef, DuckDuckGo) and Claude synthesizes the same AI-first dossier. Keyed users keep the Perplexity/Grok path unchanged. --free forces it; --academic restricts to scholarly sources.
• Google Calendar commands (Claude Code): /obsidian-agenda (snapshot with conflict / focus-block / external-organizer detection), /obsidian-schedule (create or reschedule events from a task), /obsidian-meeting (meeting note from an event).
• /obsidian-recurring - track a recurring obligation with a cadence and a computed next-due date.
• Anti-fabrication + false-absence + search-completeness guards - the first hallucination guard in the canonical AI-first spec, echoed across the commands.
• First automated tests + CI - smoke tests on the adapter build and vault_health.py, run on every PR.
• Background agent is now opt-in and ships inert - it no longer arms on install; it requires a deliberate OBSIDIAN_BG_AGENT_ENABLED=1.

Also

• Per-day operation logs, /podcast, SessionStart hook, centrality ranking in /obsidian-visualize, references/DELTAS.template.md for forkers, the claude -p headless gotcha documented, and a long list of bootstrap_vault.py / setup.sh / cross-platform fixes.

Many of these were merged from community fork ideas - see FORK_INSIGHTS.md for the full analysis. Full detail in CHANGELOG.md.

v0.8.0 - /notebooklm rewrite: no browser, one HTTP call

Headline

/notebooklm rewritten end to end. The old version required opening notebooklm.google.com, pasting in a bundle, asking the question, copying the response back into the terminal. The new version is a single command, single HTTP call, no browser. Same architectural shape as /research-deep.

Under the hood it uploads the top 12 relevant vault notes to a Gemini File Search store, asks Gemini for a citation-style synthesis grounded only against those sources, writes the AI-first synthesis to Research/NotebookLM/, and deletes the store. Cost: roughly $0.004 per run on gemini-2.5-flash (free tier covers it) or $0.06 on paid gemini-2.5-pro.

This unlocks the dual-track research pattern:

• /research-deep pulls the open-web view (Perplexity + Grok)
• /notebooklm reads your own vault (Gemini File Search)
• Run both. Contradictions across the two are where the insight is.

What's in this release

Added

• /notebooklm Gemini File Search rewrite (see headline)
• Dual-track research story baked into the README (hero rewrite + v0.8 callout + /notebooklm "in action" example)
• New README banner: Mode B Terminal Teal, four platform pills, v0.8 callout, vault-graph mesh
• GEMINI_API_KEY added to setup docs and .env.example

Fixed (caught during the rewrite's end-to-end test)

• /notebooklm self-reference bug: previous save phase re-scanned the vault and pulled its own start-phase bundle file in as a baseline link
• /notebooklm em-dash filenames blew up the Gemini SDK upload (httpx rejects non-ASCII Content-Disposition headers); fixed by copying each source to a temp path with an ASCII-safe name before upload
• /notebooklm em-dashes baked into the synthesis template (H1 and preamble); now use colon and period-restructure

Setup

# Get a free Gemini API key
open https://aistudio.google.com/apikey

# Add to your env
echo 'GEMINI_API_KEY=...' >> ~/.config/obsidian-second-brain/.env

# Sync deps
cd ~/.claude/skills/obsidian-second-brain && git pull && uv sync

Then from any Claude Code session:

/notebooklm your topic here

The synthesis lands in Research/NotebookLM/YYYY-MM-DD - <slug>.md and /obsidian-save propagates updates to entities and projects.

Also in this release (administrative)

• Versions: pyproject.toml and CITATION.cff both at 0.8.0
• CHANGELOG: the bloated [Unreleased] section was split into [0.8.0] (today) and a properly-dated [0.7.0] entry for the Phase 1-5 + bootstrap_vault work that was sitting in Unreleased
• Command count: 33 (unchanged from v0.7; /notebooklm was already counted but its implementation is materially different)

Full diff: v0.6.0...v0.8.0

v0.6.0 — AI-First Rule Wired Into All 31 Commands

🧠 v0.6.0 — Phase 2: AI-First Rule Wired Everywhere

The follow-up to v0.5.0. All 26 existing commands now explicitly enforce the AI-first vault rule — the same rule the 5 research commands have followed since day one.

Why this matters: the AI-first rule was established in v0.5 (_CLAUDE.md Section 0), but the existing commands relied on Claude inferring it from the operating manual. v0.6 wires it explicitly into every command, so any Claude session applies the same standard whether or not _CLAUDE.md was fully loaded.

---

📜 New canonical spec: references/ai-first-rules.md

The single source of truth for how Claude writes vault notes. Includes:

• The 7 rules — self-contained context, "For future Claude" preamble, rich frontmatter, recency markers per claim, sources verbatim, mandatory [[wikilinks]], confidence levels
• Frontmatter schemas per note type — daily, project, person, idea, task, decision, devlog, review, research/research-deep/x-read/x-pulse/youtube, adr, synthesis/emerge/connect/challenge
• Preamble templates — ready-to-use "For future Claude" templates for each note type
• Common anti-patterns — what NOT to do, with reasons (e.g. "see above" breaks isolation reads, plain-text names break the link graph)
• Audit checklist — the 10-item check used to validate any single note against the rule

---

🔗 All 31 commands now reference it

Every command (/obsidian-save, /obsidian-decide, /obsidian-person, /obsidian-daily, ...) now ends with an explicit AI-first directive:

**AI-first rule:** Every note created or updated by this command MUST
follow `references/ai-first-rules.md` — `## For future Claude` preamble,
rich frontmatter, recency markers per external claim, mandatory
`[[wikilinks]]`, sources verbatim, and confidence levels where applicable.

Surgical — no command body rewritten. Just one consistent cross-reference per file.

---

📚 Documentation updates

• references/write-rules.md — top-of-file callout pointing at ai-first-rules.md as the foundation; the propagation/linking/kanban/status/archiving rules sit on top
• SKILL.md — new "AI-first vault rule" section under Core Operating Principles documents the 7 rules inline so readers see them without chasing a reference
• _CLAUDE.md template — Section 0 was added in v0.5; v0.6 reinforces it from multiple angles

---

🧪 What this fixes in practice

Before v0.6, two different Claude sessions running /obsidian-save on identical conversations could produce notes with different levels of structure depending on whether _CLAUDE.md was loaded and how attentively the model read Section 0. Some sessions added preambles, some didn't. Some used [[wikilinks]] consistently, some used plain-text names. Recency markers were inconsistent.

After v0.6, every command's instruction set itself enforces the rule. The model can't miss it — it's literally in the prompt that drives the command. Result: vault notes from /obsidian-save, /obsidian-decide, /obsidian-person, etc. now match the same AI-first standard the v0.5 research commands have produced from day one.

---

🔍 Audit your vault

The new references/ai-first-rules.md includes an audit checklist. To find pre-v0.6 vault notes that don't yet meet the standard:

/obsidian-health

The health check flags notes missing the AI-first preamble, missing ai-first: true frontmatter, or with bare claims that lack recency markers. You can then ask Claude to fix specific notes one at a time, or batch-update by note type.

---

📦 Stats

• 29 files changed (SKILL.md, 26 commands, write-rules.md, new ai-first-rules.md)
• +406 lines (almost entirely the new spec + cross-references)
• 0 breaking changes — additive only, existing commands behave the same, just with stronger guarantees

---

🎯 What's next

Phase 2 closes the loop on the AI-first rule. From here:

• Phase 3 (community-driven): refine the type schemas based on actual vault usage — which fields are actually queryable via Dataview, which are dead weight?
• Optional: add an /obsidian-audit-ai-first command that runs the audit checklist programmatically across all vault notes and produces a fix list

---

Upgrade from v0.5:

cd ~/.claude/skills/obsidian-second-brain && git pull
# nothing to re-run — commands pick up the new instructions automatically

Full diff: v0.5.0...v0.6.0

v0.5.0 — Research Toolkit

🧠 v0.5.0 — Research Toolkit

The biggest release since v0.4. Five new commands turn the vault into a live research workspace, with vault-first synthesis that knows what you already know.

26 → 31 commands. Same install. Same _CLAUDE.md. New layer.

---

⚡ The 5 New Commands

Command	What it does	Powered by
/x-read [url]	Verbatim X post + thread + TL;DR + key claims + reply sentiment + voices to watch	Grok-4 + x_search
/x-pulse [topic]	What's hot on X, gaps, working hooks, post ideas you can write today	Grok-4.20-reasoning + x_search
/research [topic]	Web research dossier with citations, recency markers, contrarian views, open questions	Perplexity Sonar Pro
/research-deep [topic]	Vault-first. Scans vault → identifies gaps → fills only those → synthesizes a delta report → propagates updates via /obsidian-save	Perplexity sonar-reasoning-pro + Grok + vault scan
/youtube [url]	Transcript + metadata + top comments → AI-first summary with verbatim quotes	youtube-transcript-api + YouTube Data API v3 + Grok-4

Plain English triggers all five too: "read this tweet", "what's hot on X about AI", "research X memory tools", "do deep research on X", "summarize this YouTube video".

---

🧬 New Vault-Wide Rule: AI-First Notes

Section 0 of _CLAUDE.md now enforces a rule across all 31 commands: every vault note is designed for future-Claude to read and reason over, not for human review.

That means every research note (and every existing command's output going forward) follows:

1. Self-contained context — explains itself, doesn't rely on backlinks alone
2. "For future Claude" preamble — 2-3 sentence summary so Claude can decide relevance in 10 seconds
3. Rich, consistent frontmatter — type, topic, tags, related-people, sources, confidence
4. Recency markers per claim — "Mem0 raised $24M (as of 2026-04)" so future-Claude knows what to verify
5. Sources preserved verbatim — every external claim has its source URL inline
6. Cross-links mandatory — every person, project, idea uses [[wikilinks]]
7. Confidence levels — stated | high | medium | speculation

The rule applies to all 5 new research commands from day one. Phase 2 (separate release) will audit the existing 26 commands.

---

🔌 Setup

API keys live at ~/.config/obsidian-second-brain/.env (Mac-local, never in repo, never synced). Run install.sh and answer "y" to the research prompt — it walks you through it. Or set up manually with cp .env.example ~/.config/obsidian-second-brain/.env.

Key	Required for	Where	Cost
XAI_API_KEY	/x-read, /x-pulse, /research-deep (X), /youtube (summary)	console.x.ai	Pay-per-use, ~$0.05/call
PERPLEXITY_API_KEY	/research, /research-deep	perplexity.ai/settings/api	Pay-per-use, ~$0.02–$0.50/call
YOUTUBE_API_KEY	/youtube metadata + comments (optional)	console.cloud.google.com	Free tier (10k units/day)

Without API keys, the original 26 commands still work. Research toolkit degrades gracefully — never blocks core vault operation.

---

🛠 Stack

• Python 3.10+ with uv for dep management (zero venv friction)
• xAI Grok via the new Agent Tools API (/v1/responses endpoint, tools: [{"type": "x_search"}])
• Perplexity Sonar via the standard chat completions endpoint
• youtube-transcript-api for free transcript extraction (no API key needed)
• YouTube Data API v3 (free tier, optional) for metadata and comments

---

💾 Save Behavior

Every research command saves to a dedicated subfolder under Research/ in your vault, with full AI-first frontmatter:

Research/
├── X-reads/      # /x-read outputs (chat-only by default; saved on request)
├── X-pulse/      # /x-pulse outputs
├── Web/          # /research outputs
├── Deep/         # /research-deep outputs (vault-first synthesis)
└── YouTube/      # /youtube outputs

Auto-open: every save pops Obsidian directly to the new note via obsidian://open?.... Disable with RESEARCH_AUTOOPEN=0 if you're running batch saves or scheduled agents.

Cost tracking for Grok calls is logged to ~/.research-toolkit/usage.log. View monthly totals via:

uv run python -c "from scripts.research.lib.usage import month_total; t,c = month_total(); print(f'\${t:.2f} across {c} calls')"

---

🧪 What Was Tested

End-to-end real-world testing confirmed all 5 commands working, with several Tools API issues surfaced and fixed during testing:

• ✅ /x-read on a real Garry Tan X post → verbatim post, replies, sentiment breakdown ($0.05)
• ✅ /x-pulse "AI automation" → 4 themes with rep posts, gaps, hooks, post ideas ($0.13)
• ✅ /research "best personal workflow setup" → full dossier, 7 cited sources (~$0.04)
• ✅ /research-deep on the same topic → 5 targeted queries, vault baseline scan (8 notes), delta synthesis with 6 contradictions/updates flagged (~$0.50)
• ✅ /youtube on a real video → 16k-char transcript + 15 comments + structured summary ($0.04)

---

🐛 Bug Fixes Surfaced During Testing

• xAI Live Search API got deprecated mid-build → migrated to the new Agent Tools API (tools: [{"type": "x_search"}])
• Grok-4 leaks internal tool-call XML in some responses → added regex stripper in the Grok client
• Perplexity <think> reasoning blocks showed up in saved notes → added stripper in the Perplexity client (handles closed and unclosed tags)
• sonar-deep-research ignores user prompt structure (hardcoded 10k-word academic-narrative format) → switched /research-deep synthesis to sonar-reasoning-pro, which actually follows markdown-structure instructions
• sonar-reasoning deprecated by Perplexity → bumped to sonar-reasoning-pro
• grok-4.20-reasoning was wasted overhead on extract-and-format tasks → switched /x-read and /youtube defaults to grok-4 (~55% cheaper, same output quality). /x-pulse keeps the reasoning model for genuine multi-post synthesis.

---

🔮 What's Next (Phase 2)

• Audit the existing 26 /obsidian-* commands against the AI-first rule
• Standardize frontmatter schemas across all command types
• Add "For future Claude" preamble templates to all command outputs
• Verify mandatory wikilink rules across the codebase

---

🙏 Credits

Designed via a 20-question grill-me interview (grill-me skill). Built end-to-end in one session. Special thanks to Claude Opus 4.7 (1M context) as the implementation pair.

---

Install:

git clone https://github.com/eugeniughelbur/obsidian-second-brain ~/.claude/skills/obsidian-second-brain
bash ~/.claude/skills/obsidian-second-brain/install.sh

Upgrade from v0.4:

cd ~/.claude/skills/obsidian-second-brain && git pull
bash install.sh   # answer 'y' to set up the research toolkit

Full diff: v0.4...v0.5