Changelog
All notable changes to this project are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
Unreleased
Added
- SessionStart hook (
hooks/load_vault_context.py): injects_CLAUDE.mdinto context once per session when the session starts inside the vault. Eliminates the per-command re-read of_CLAUDE.mdthat burned tokens on every invocation. Wired automatically byscripts/setup.sh. scripts/setup.shupdated: wires the new SessionStart hook (hooks/load_vault_context.py) in addition to the existing PostCompact background agent.- Per-day operation logs:
/obsidian-initnow creates aLogs/folder with per-day files (Logs/YYYY-MM-DD.md) instead of a monolithiclog.md. Rootlog.mdbecomes a pointer file only. Cheaper to read, faster to query. scripts/vault_stats.py: computes vault stats (notes by type, project/task counts by status, people by strength) and rewrites the<!-- BEGIN STATS -->/<!-- END STATS -->markers inindex.md. Idempotent and re-runnable.scripts/migrate_log.py: splits an existing monolithiclog.md(with## YYYY-MM-DDsection headers) into per-day files underLogs/. Idempotent — skips days that already exist. Replaces rootlog.mdwith a pointer file after migration.
Fixed
-
scripts/setup.shrobustness: four issues fixed together. Vault paths containing apostrophes or other shell metacharacters (Joe's Notes) no longer crash the installer -eval echoreplaced with bash parameter substitution.pythonreplaced withpython3for compatibility with macOS 13+ and Ubuntu 22+ which don’t ship apythonsymlink. All threesettings.jsonwrites are now atomic (mvinstead ofcat … && rm). The MCP setup prompt is skipped when stdin is not a terminal socurl | bashinstalls and CI don’t hang. vault_stats.pypeople count: now counts bothtype: personandtype: entityin the People aggregate. Real vaults using either convention report the correct count.- Log layout routing in all commands: every
/obsidian-*command that reads or appends to the operation log now explicitly detects the vault layout (Logs/YYYY-MM-DD.mdvs monolithiclog.md) and uses the correct file and format. Previously, commands hardcodedlog.mdwith the old## [YYYY-MM-DD]section-header format, which would write incorrectly formatted entries on modernized vaults. vault_stats.pyfolder exclusions case-insensitive:EXCLUDED_FOLDERScomparison now usespart.lower(), sotemplates/andTemplates/are both excluded. Addedraw/to the exclusion set (immutable source folder convention).- Em-dashes swept from
vault_stats.pyoutput,commands/obsidian-init.mdentry template, andSKILL.mdformat spec: all user-facing and vault-facing prose now uses ` - ` per the no-em-dash rule.
[0.8.0] — 2026-05-15
Added
/notebooklmcommand rewritten end to end — no browser, one HTTP call. Replaces the prior bundle-and-paste workflow (which required opening notebooklm.google.com manually and pasting the response back into the terminal) with a single-phase command that calls Google’s Gemini File Search API directly. Same architectural shape as/research-deep: one HTTP call, no manual step. Under the hood: scans the vault for the top 12 relevant notes (Research/NotebookLM/ excluded so the synthesis doesn’t self-reference its own bundle), uploads them to an ephemeral Gemini File Search store, asks Gemini (defaultgemini-2.5-flash, free-tier friendly) for a citation-style synthesis grounded only against those sources, writes the AI-first synthesis toResearch/NotebookLM/YYYY-MM-DD - <slug>.md, deletes the store, and emits a propagation payload for/obsidian-save. RequiresGEMINI_API_KEYfrom https://aistudio.google.com/apikey (free tier covers it). Cost: roughly $0.004 per run on Flash, $0.06 per run on Pro (override viaNOTEBOOKLM_MODELenv). Filenames written by this command use ASCII separators (2026-05-15 - <slug>.md) instead of em-dashes; existing/research-deepfilenames untouched. The two research tracks (open-web via/research-deep, vault-grounded via/notebooklm) are designed to run in parallel for high-stakes topics. Contradictions across the two tracks are where the insight is.
Fixed
/notebooklmself-reference bug. Previous implementation re-scanned the vault during the save phase, which scored the bundle file (written during the start phase) as a top hit. The synthesis linked to its own input bundle as a vault baseline. Fix:vault_scannow excludes anything underResearch/NotebookLM/./notebooklmem-dash filenames blew up the Gemini SDK upload. Vault filenames inResearch/Deep/andwiki/logs/often contain em-dashes (from the prior/research-deepconvention). The Gemini SDK puts the basename in a Content-Disposition header, and httpx rejects non-ASCII headers. Fix: copy each source to a temp path with an ASCII-safe name before upload; preserve the original path as the human-readabledisplay_name./notebooklmem-dashes baked into vault output. The synthesis H1 usedtopic — NotebookLM synthesis (date)and the preamble had mid-sentence em-dashes. The voice rule says no em-dashes anywhere. Both now use a colon and a period-restructure respectively.
[0.7.0] — 2026-05-13
Added
bootstrap_vault.py --presetand--modeflags: wires the preset/mode interface thatSKILL.mddocumented but the script never implemented (running--preset researchererrored withunrecognized arguments: --preset researcher --mode personal). Five presets land at once, matching the existing SKILL.md description verbatim:default(preserves existing Life-OS layout — no change in behavior when no flag is passed),executive(Decisions/People/Meetings/OKRs · Boards: OKRs/Quarterly/Weekly),builder(Projects/Dev Logs/Architecture/Debugging · Boards: Backlog/Sprint/In Progress/Done),creator(Content/Ideas/Audience/Publishing · Boards: Ideas/Drafts/Scheduled/Published),researcher(Sources/Literature/Hypotheses/Methodology/Synthesis · Boards: Reading/Processing/Synthesized/Done). Each preset declares its folder list, kanban columns,_CLAUDE.mdfolder map, Home dashboard nav, and template extras via a singlePRESETSdict at the top of the file — adding a new preset is one dict entry plus optional template lines inwrite_preset_extras(). Two modes:personal(default — owner-style_CLAUDE.md) andassistant(uses thereferences/claude-md-assistant-template.mdschema, requires--subject "Name"and renders the operator/subject distinction). Fully backwards-compatible:--path,--name,--jobs,--no-sidebizkeep their meaning under the default preset;--no-sidebizis silently ignored on non-default presets. The vault-not-empty check now ignores.obsidian/so re-running on a vault that only has Obsidian config no longer prompts./create-commandinterview flow (Phase 5): new meta command that scaffolds a newcommands/<name>.mdthrough a 9-phase conversation — zero markdown editing. Asks intent, name, category, triggers, behavior steps, AI-first compliance, and external API needs, then writes a fully-formed command file (frontmatter + body + AI-first footer where applicable) using the Write tool. The new file flows automatically into every platform via the existing adapters — no extra build steps. Lowers the contribution bar so anyone can extend the skill, and every command added through this flow lands AI-first-compliant by construction. Listed undermetacategory; total command count is now 32 (was 31).- Write-time AI-first validator (Phase 4): new
hooks/validate-ai-first.shruns as a Claude CodePostToolUsehook after everyWriteorEditon a markdown file insideOBSIDIAN_VAULT_PATH. Warns (non-blocking) when the file fails the AI-first rule: missing frontmatter delimiters, missing required fields (date,type,tags,ai-first: true), tabs in YAML, or missing## For future Claudepreamble. Surfaces specific warnings on stderr so Claude can repair the note in the same turn. Skipsraw/,templates/,_export/,.obsidian/,.git/,.trash/and anything outside the vault. Platform-neutral spec athooks/validate-ai-first.hook.yaml. Setup instructions inSKILL.mdunder “Write-Time AI-First Validator (PostToolUse Hook)”. This is the write-time cleanup primitive that the Second Brain for Companies thesis depends on — humans write inconsistent input, the validator enforces AI-first discipline automatically. - Multilingual trigger phrases (Phase 3): every command now declares
triggers_<lang>:lines in its frontmatter. English (triggers_en:) is populated for all 31 commands; the schema is extensible to any language viatriggers_es:,triggers_it:,triggers_fr:,triggers_de:,triggers_pt:,triggers_ru:,triggers_ja:(community contributions welcome). The non-Claude dispatchers (AGENTS.md,GEMINI.md) now include a## Trigger phrasessection grouped by language then by category, so AI agents on those platforms can match natural-language requests without seeing the slash form. Adapters auto-detect which languages are populated; empty languages do not appear in the output. Documented inCONTRIBUTING.mdunder “Translating trigger phrases (multilingual support)”. - Command categorization (Phase 2): each command in
commands/now declares acategory:(vault, thinking, research, meta). Non-Claude dispatcher tables inAGENTS.md/GEMINI.mdare now emitted as four grouped sections instead of one 31-row blob. Adapters use the sharedemit_routing_table_groupedhelper inadapters/lib.sh, so the categorization carries through automatically when a new command is added. No breaking changes — Claude Code build is still a byte-exact identity copy. - Multi-platform adapter pattern (Phase 1): one source, four platforms.
scripts/build.shorchestrator +scripts/lib.shutility helpersadapters/lib.shshared parsing, path rewriting, tool-name neutralizationadapters/claude-code/adapter.sh— identity copy (Claude Code is the canonical platform)adapters/codex-cli/adapter.sh— emitsAGENTS.md+.codex/commands/adapters/gemini-cli/adapter.sh— emitsGEMINI.md+.gemini/commands/adapters/opencode/adapter.sh— emitsAGENTS.md+.opencode/commands/- Auto-generated routing tables (parses each command’s
description:frontmatter) - Tool-name neutralization for non-Claude platforms (
Read tool→read files, etc.) - Per-platform
exclude:frontmatter field for opt-outs - Build output goes to
dist/<platform>/(gitignored)
CODE_OF_CONDUCT.md(Contributor Covenant v2.1)CONTRIBUTING.mdwith full contributor guideCLAUDE.mdat repo root for contributor-facing operating instructionsCHANGELOG.md(this file).github/community files: issue templates, PR template, FUNDING.ymlCITATION.cfffor Google Scholar / Zenodo / OpenSSFllms.txtat repo root for AI crawlers (ChatGPT, Claude, Perplexity)- FAQ section in README to boost AI-search citation rate
- GitHub Pages site with Cayman theme + jekyll-seo-tag + jekyll-sitemap
- Banner image and polished author hero in README
examples/sample-vault/showing 6 AI-first compliant note types (daily, person, project, idea, devlog, plus_CLAUDE.mdtemplate)SECURITY.md— vulnerability reporting policy and coordinated disclosure timeline- Schema.org JSON-LD
SoftwareApplicationblock on the Pages site (_includes/head_custom.html) for rich-result eligibility and AI-search citation - 3 new FAQ entries targeting “Obsidian plugin vs Claude Code skill” search intent
Changed
- GitHub About description rewritten to lead with “Claude Code skill for Obsidian”
- README banner alt text now contains the full search-intent phrasing
- GitHub topics: swapped
markdownandpkmforobsidian-skillandclaude-code-skill
Fixed
bootstrap_vault.pyUnicodeEncodeErroron Windowscp1252consoles. The script’s emoji print statements (🧠 Bootstrapping vault: ...,📁 Folders created,✅ Vault bootstrapped at: ...) crashed on Windows before doing any work because the default Pythonsys.stdoutencoding on Windows PowerShell / cmd iscp1252, which has no codepoints for those characters.sys.stdoutandsys.stderrare now reconfigured to UTF-8 at script start, wrapped intry/except (AttributeError, ValueError)so non-text streams or environments without.reconfigure()fall back gracefully.- Removed dead
--minimalflag frombootstrap_vault.py.argparseaccepted--minimalbut the value was never passed intobootstrap()— the flag had no effect for any user since v0.1.0. Removing it changes no behavior. pyproject.tomlversion was0.1.0, now matches the v0.6.0 release tag.
0.6.0 — 2026-04-26
Added
references/ai-first-rules.md— canonical spec for vault writes (the 7 rules, frontmatter schemas per note type, preamble templates, anti-patterns, audit checklist).
Changed
- All 31 commands now explicitly reference the AI-first rule. Surgical cross-reference per command file, no body rewrites. Closes the gap where two Claude sessions on the same conversation could produce inconsistently structured notes.
references/write-rules.mdnow points toai-first-rules.mdas the foundation.SKILL.md— new “AI-first vault rule” section under Core Operating Principles.
Notes
- 29 files changed, +406 lines, 0 breaking changes. Additive only.
0.5.0 — 2026-04-26
Added
- Research Toolkit — five new commands that turn the vault into a live research workspace.
/x-read [url]— verbatim X post + thread + TL;DR + key claims + reply sentiment (Grok-4 + x_search)./x-pulse [topic]— what’s hot on X, gaps, working hooks, post ideas (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, summarized AI-first (youtube-transcript-api + YouTube Data API v3 + Grok-4).
- Section 0 of
_CLAUDE.mdtemplate — first version of the AI-first vault rule, applied to all 5 research commands from day one. - API key handling at
~/.config/obsidian-second-brain/.env(Mac-local, never synced). pyproject.toml+uv.lockfor Python dependency management.- Auto-open behavior: every research save pops Obsidian to the new note via
obsidian://open?....
Notes
- Command count went 26 → 31. Same install, same
_CLAUDE.md. - Without API keys, the original 26 commands still work — research toolkit degrades gracefully.