# Changelog

All notable changes to this project are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- **German (`de`) trigger phrases for all commands (#299, by @2Obe).** Each command now recognizes natural German requests alongside the existing English, Spanish, Portuguese, and Simplified Chinese phrases.

### Changed

- **CI runs the test suite on Windows too.** Six recent bugs were Windows-only and shipped because CI ran on Linux alone. A `windows-latest` job now runs `pytest`. Its first run found 6 failures that no Linux run could see: the post-write command bug above, and five tests that assumed Linux paths, line endings or `PATH` separators.

- **Search and vault stats treat company and tool notes as entities, like people (#302, raised by @etcook).** #286 gave companies and tools their own schemas, but search only boosted `type: person` notes and the stats only counted people. `vault_ops.search()` now gives `company` and `tool` notes the same 1.5 boost. Measured on a real vault with 11 such notes, searched by title: 2 moved up to #1 (from #2 and #5), none moved down, and the three retrieval case sets scored the same before and after. `vault_stats.py` adds an `entities` block with a total and a by-kind split, shown as an `Entities` line in the `index.md` stats. The `people` block is unchanged, so anything reading it keeps working.

### Fixed

- **The SessionStart hook injected a BOM into the middle of the session context (#318, by @shatulsky).** `hooks/load_vault_context.py` read `_CLAUDE.md` as plain `utf-8`, so a manual saved by a BOM-adding editor (Notepad, most Windows tools) arrived with U+FEFF glued to its first line, halfway through the payload. The other six read sites already use `utf-8-sig` (stress-test fix 4/24); this one was missed. The file on disk keeps its BOM. A test in `tests/test_bom_frontmatter.py` fails on the previous `main`.

- **`vault_health` reported missing frontmatter on system files the write-time hook exempts (#319, by @shatulsky).** `hooks/validate-ai-first.sh` exempts `_CLAUDE.md`, `Home.md`, `index.md`, `log.md` and `catchup.md` at any depth, and `vault_stats.py` skips `_CLAUDE.md`, `log.md` and `index.md` by filename too. The health check exempted only `Home.md` and `_CLAUDE.md`, and only at the vault root. So a nested vault's own `_CLAUDE.md` (the template carries no frontmatter) and a monolithic `log.md` of appended entries were reported. The check now uses the hook's set, matched on the whole filename, so `changelog.md` is still checked. Tests in `tests/test_vault_health_precision.py` fail on the previous `main`.

- **A link to a note whose title ends in `.md` was never counted (#320, by @shatulsky).** A note titled `Rename _CLAUDE.md` is saved as `Rename _CLAUDE.md.md`, and `[[Rename _CLAUDE.md]]` reaches it in Obsidian. The orphan check, the url-only source check and `link_graph.py` all stripped the trailing `.md` as a redundant extension and then matched nothing, so the note was reported as an orphan and `link_graph` counted a dangling link and no edge. They now also try the link as written. The stripped form still goes first, so `[[note.md]]` still reaches `note.md` and every link that resolved before resolves the same way. Tests in `tests/test_vault_health_precision.py` and `tests/test_link_graph_mirror.py` fail on the previous `main`.

- **On Windows, a quoted `OBSIDIAN_POST_WRITE_CMD` never ran.** `vault_ops.py` split the command with non-POSIX `shlex`, which keeps the quote marks, so `"C:\Program Files\...\python.exe" hook.py` reached `subprocess` with its quotes attached and came back as `command not found`. Any interpreter path with a space needs those quotes. The split now drops one layer of matching quotes per token, the rule `retrieval_eval.py` already used. Found by the new Windows CI job; a test pins the split on every OS.

- **The write-time hook reported `payload keys: none` for a payload that had a path key one level up (#171, reported by @tonydzi).** A payload like `{"tool_name":"Write","file_path":"..."}` still exited 1 and stayed fail-closed, but the diagnostic listed only keys under `tool_input` and `args`. It now also lists top-level scalar keys, so that payload reports `file_path`. An empty payload still reports `none`. A separate guard test covers that empty payload and a `NotebookEdit` naming an `.md` inside the vault, which gets past every gate and is validated. Both pass on the old hook too, so they guard against regressions rather than prove this fix (split out after @tonydzi checked each assert against the old hook).

- **The Pi docs told users to run `/obsidian-nightly`, which does not exist on Pi (follow-up to #304).** The scheduled agents are prompts in `SKILL.md`, not files in `commands/`, so the Pi adapter never builds a prompt template for them. The README and the generated `dist/pi/INSTALL.md` now say to copy the agent's prompt from `SKILL.md` into a Pi session instead.

- **`/research-deep` threw away every gap-fill finding when synthesis failed.** When the Phase 4 synthesis call raised (a provider read timeout, for one), the note was written with a banner saying the raw findings were below it, and nothing below it. Every Phase 3 query and Tavily extraction the run had already paid for was lost. The raw findings now follow the banner. `tests/test_research_deep_fallback.py` drives the real function with synthesis stubbed to time out, and fails on the previous `main`.

- **The write-time hook skipped every note in a vault kept under a folder named `.obsidian`, and said nothing (reported by @jameswolensky).** The skip list in `hooks/validate-ai-first.sh` carried a bare `*/.obsidian/*`, meant for the vault's config directory. The pattern matches that segment anywhere in a path, not under the vault root, so a vault at `~/.obsidian/life-os` matched on every note and the hook returned before any check ran. Nothing errored and nothing printed: the hook exits 0 whether it validated a note or skipped it, so a vault laid out this way got no frontmatter checks, no preamble check and no banned-character check for as long as it existed, and looked exactly like a vault that was passing. The entry is now scoped to `"$VAULT_KEY"/.obsidian/*`. `$VAULT_KEY` rather than `$VAULT`, because `path_key()` lowercases on Windows and the block sets `nocasematch` there, so the unfolded path would stop matching the folded `$FILE_KEY` on the one platform the surrounding code takes care over. The other entries are left alone: they are relative segments like `*/raw/*` that carry no vault-root ambiguity. Five tests in `tests/test_validate_hook_vault_scope.py`, two of which fail against the old pattern.

## [0.17.0] - 2026-09-26 - The Neighbors

### Added

- **A session running beside another Obsidian plugin is now told which schema governs its writes (#300).** Claude Code merges hook entries instead of replacing them: "Hook entries merge across settings levels", "All matching hooks run in parallel", and "A plugin's or skill's copy of the same handler stays separate" ([docs](https://code.claude.com/docs/en/hooks)). SessionStart adds every hook's stdout to context, so a second vault plugin's rules arrive alongside ours and the session holds two folder maps and two frontmatter schemas for one vault. Nothing errored and nothing said so: the validator still passed our writes, and the vault drifted into mixed conventions one note at a time. `scripts/vault_plugin_scan.py` reads the SessionStart entries in `~/.claude/settings.json`, a project's `.claude/settings.json` and `.claude/settings.local.json`, and every installed plugin's `hooks/hooks.json` (found through `installed_plugins.json`), and reports the vault-related ones that are not ours. It reads the `command` plus `args` form as well as a bare command string, because a plugin that registers `"command": "python3"` with the script in `args` carries its only evidence in the half a simpler scan would skip. `load_vault_context.sh` then opens its context with a precedence note naming what was found and stating that the vault's own `_CLAUDE.md` governs every write, placed ahead of the manual and inside the 10,000-character budget, so the note the cap drops is never the one saying a second ruleset is present. The installer runs the same scan at install time, while the user can still choose. Detection only: no other hook is edited, disabled or unregistered, and a scan that raises costs the session nothing. A bare `vault` was considered as a detection marker and dropped, since it matches HashiCorp Vault tooling and a wrong precedence note is worse than a missed one. Twenty tests in `tests/test_vault_plugin_scan.py`.

- **Company and tool entity notes have schemas, and the fence that should have caught their absence now does (#274).** `/obsidian-ingest` creates a page for each person, company and tool a source mentions, but `references/ai-first-rules.md` only defined `type: person`, so company and tool pages were written with whatever frontmatter the run improvised. `tests/test_schema_coverage.py` could not see the gap: it matches types spelled `` `type: x` ``, and the ingest command names its entity kinds in prose. `type: company` and `type: tool` are now defined in the shape of the person schema, and the Entity Note in `references/vault-schema.md` tells the three apart by `type`, like every other note kind, instead of by tag (its Dataview example filters on `type` too). The person schema's `company:` link is now a bare `[[Acme Corp]]`, which resolves wherever the company note sits; the old `[[Companies/...]]` pointed at a folder nothing creates, and both person notes in the sample vault reported it as a wanted note. The sample vault gains a `type: company` example at `wiki/entities/Currentscale Labs.md`. In Obsidian-style vaults companies and tools now have their own `Companies/` and `Tools/` folders in `references/folder-map.md` (wiki-style keeps every entity in `wiki/entities/`), and `/obsidian-ingest` and `/obsidian-reconcile` resolve the entities folder per kind, so a company or tool is no longer filed in a folder named `People/`. A new test reads the entity kinds from the folder map's entity rows and from any command that lists them in prose, and requires a schema for each; it fails on the previous `main` for `company` and `tool`. `scripts/bootstrap_vault.py` creates both folders in every preset, so the map never resolves a company or a tool to a folder no bootstrapped vault has - the #205 shape, and the reason the map and the script move together here. Every preset carries `People/` since #287, and the two new folders follow it rather than a list that goes stale the next time a preset is edited; under `--style wiki` they collapse onto `wiki/entities/` as `People/` does, so the one-folder wiki layout is unchanged. `Businesses/` stays on the Entity row in `references/vault-schema.md` beside `People/`, `Companies/` and `Tools/`, carrying the tracked-versus-owned distinction the folder map draws: `Companies/` is for companies the vault tracks, `Businesses/` for companies the vault owner owns. Only `Jobs/` comes off that row, since it holds employment roles rather than entities. Both new schemas take `website-url:`, following the `-url` suffix `source-url`, `feed-url` and `event-url` already use; the tool schema keeps `repo:` beside it, since a repository and a product page are different things.

- **The setup script builds both documented vault layouts: `--style wiki|obsidian` (#283).** The README and `references/vault-schema.md` describe a wiki-style layout, but `bootstrap_vault.py` could only build the Obsidian-style one: every preset created `Daily/`, `People/` and the rest, and its only call to `write_bases` hardcoded `style="obsidian"`, so a wiki-style vault had to be laid out by hand. `--style` defaults to `obsidian`, which builds what the script built before. `--style wiki` creates each preset folder at its wiki-style path from `references/folder-map.md` (`wiki/daily/`, `wiki/entities/`, `wiki/concepts/`, `boards/`, `templates/`), and the generated `_CLAUDE.md`, `Home.md`, board paths, template queries and Bases point at those paths. A preset folder the wiki layout does not rename keeps its own name under `wiki/`, lowercased and hyphenated (`Goals/` to `wiki/goals/`, `Sources/` to `wiki/sources/`, `Reading Queue/` to `wiki/reading-queue/`, `Finances/Spending/` to `wiki/finances/spending/`), so a preset is the same promise in either layout and `WIKI_PATHS` carries only the genuine renames: an earlier revision of this change dropped those folders instead, which meant `--preset researcher --style wiki` built exactly what no preset at all would have built, and left the seed notes that live in them unwritten. The wiki-style `Home.md` links a preset's seed notes as the Obsidian-style one does, so neither layout ships a note nothing links. Both styles now record `Vault style:` in `_CLAUDE.md`, which `references/folder-map.md` consults when a folder does not exist yet. The builder and creator presets also create `People/`, since their own `_CLAUDE.md` routes new people there. The README and `vault-schema.md` no longer call the wiki layout the default. Tests in `tests/test_bootstrap_style.py`.

### Changed

- **One place now answers "where is the config, and what does it say" (#124, #160, #269, #285).** The same six lines were written out in seven places: `install.sh`, `scripts/setup.sh`, `scripts/research/lib/config.py`, `scripts/research/lib/source_config.py`, `scripts/eval/retrieval_eval.py`, `scripts/eval/behavior_eval.py` and `integrations/obsidian-mcp-server/vault_ops.py`, the last of which carried a second hand-rolled `.env` parser of its own. Two had already drifted: `behavior_eval.py` ignored `OBSIDIAN_ENV_FILE` entirely, so pointing the toolkit at a second config silently kept reading the first, and `vault_ops.py` honoured it in one of its two code paths. New `scripts/osb_env.py` answers both questions for the Python half and `osb_env_file` in `scripts/platform-home.sh` for the bash half; `tests/test_osb_env.py` checks the two agree on the file, and fails when a new inline copy appears. `hooks/validate-ai-first.sh` keeps its inline copy for the reason `tests/test_platform_home.py` already documents: it is copied into other harnesses' hook systems by hand and cannot source anything.

  `osb_env.py` is deliberately stdlib-only. Its callers include the MCP server, which runs under `uv run --no-project --with 'mcp<2'` with no `python-dotenv` installed, and the SessionStart hook, which has to keep working on a machine with nothing installed; a `dotenv` import here would break both exactly where they are meant to stop breaking. The config file is parsed rather than sourced, so an edited `.env` is not a way to run code at the start of every session, and it now tolerates what the bash half and hand edits actually write: `export ` prefixes, CRLF endings, comments, and single or double quoted values. An empty `OBSIDIAN_VAULT_PATH` in the environment no longer shadows a working value in the file.

  This is a refactor with no new user-facing behaviour, but it is the reason the same bug shipped four times. Each fix landed in one copy, and the next release found the next copy. `tests/test_setup_and_manual_drift.py::test_installers_honor_the_env_file_override` asserted on the literal duplicated string, which made it a check that the duplication was still in place; it now asserts the behaviour instead.

### Fixed

- **The write-time validator said a note with a UTF-8 BOM had no frontmatter (#295, reported by @SylvesterTee).** Some Windows editors save a byte-order mark before the first `---`. Check 1 compared the first line to `---` after stripping carriage returns only, so a valid note failed and every later check was skipped. The false warning could also push an agent to add a second frontmatter block. The hook now drops a leading BOM in the same copy that drops CRs. Two tests cover a BOM note with LF and with CRLF endings. Both fail on the previous `main`.

- **Check 5 flagged the math signs in Chinese, Japanese and Korean prose (#296, reported by @SylvesterTee).** #271 let CJK lines keep their own dashes, quotes and ellipsis, but the math signs U+2265, U+2264 and U+2260 stayed banned in every language. In CJK prose they are ordinary running text, and rewriting them to `>=` makes the line worse. They now sit in the language-gated set, so they still flag on English lines. The non-breaking space stays banned everywhere. `references/ai-first-rules.md` says the same.

- **The README did not say that `hermes plugins install` on this repo does nothing (#298, reported by @issamassi0-droid).** The repo root is not a Hermes plugin, since it has no `plugin.yaml`. Hermes accepts any Git URL, reports success and registers nothing. The README and the generated `dist/hermes/INSTALL.md` now say so and point at the skills build. A native plugin build stays tracked in #79.

- **The write-time validator blocked every auto-memory write when `autoMemoryDirectory` pointed inside the vault (#311, reported by @yd-03).** Claude Code writes auto memory to `.claude-memory/`, in its own format: `name` and `description` at the top level, with `type` under `metadata`. `validate-ai-first.sh` checked each file as a vault note, and flagged missing `date:`, `type:`, `tags:`, `ai-first: true` and preamble keys the format never has. It returned `decision: block` on every write. The #249 skip matches `*/.claude/*`, which needs the literal `/.claude/` segment, so `.claude-memory/` never matched. `.claude-memory/` is now on the skip list, and SKILL.md's list says so. A smoke test writes an auto-memory file into `.claude-memory/` and expects silence. It fails on the previous `main`.

- **`mine_commit_decisions.py` read git's output with the Windows codepage, so a non-ASCII history either corrupted the subjects or killed the run with an error naming nothing (#294, reported by @SylvesterTee).** The `git log` call passed `text=True` with no `encoding`, so the child's UTF-8 bytes were decoded with `locale.getpreferredencoding(False)`. That splits into two failure modes on Windows and neither says "encoding". On a codepage that maps every byte, cp1252, a CJK subject decodes into mojibake and the miner reports the corruption as a finding: verified here, where the eight CJK characters of `decided 采用新的缓存策略` came back as twenty-four Latin-1 ones, each UTF-8 byte read as its own character. On a multibyte codepage, cp950 or cp932, the decode raises instead, and it raises on the reader thread `subprocess` uses to drain the pipe, so the thread dies, `run()` still returns `returncode == 0`, and `stdout` is left `None`; `.splitlines()` on the next line then produced `AttributeError: 'NoneType' object has no attribute 'splitlines'`, which is what the reporter saw and why the traceback pointed at the wrong thing entirely. The call now passes `encoding="utf-8", errors="replace"`, matching what `conformance_report.py` already does for the same reason, so a byte that will not decode costs one replacement character instead of the whole stream; a `stdout is None` guard raises a message that names the cause, because a reader thread can still die for some other reason and an `AttributeError` three frames away is not a diagnosis. Four tests in `tests/test_mine_commit_decisions_encoding.py`, two of which fail on the previous `main`: the round-trip test fails by corruption on cp1252 and by `AttributeError` on cp950, and the guard test pins the `None` path independently of the codepage.

- **The test suite started WSL's bash instead of Git Bash on a Windows machine with WSL installed, and 45 tests failed (#308).** Every test that shells out to bash ran `subprocess.run(["bash", ...])`, and `scripts/conformance_report.py` built the platforms the same way. On Windows a bare program name goes through CreateProcess, which searches `System32` before `PATH`; with WSL installed, `System32\bash.exe` is WSL's launcher, so the hook or build script's Windows path reached a Linux bash that read every backslash as an escape and reported `No such file or directory`. `shutil.which("bash")` on the same machine returns Git Bash, which is what three test modules already used, each with a private copy of the resolver. `tests/_bash.py` now resolves bash once, `BASH = shutil.which("bash") or "bash"`, and every subprocess argv in the suite starts with it; the external-engine test quotes the resolved path into `RETRIEVAL_EVAL_EXTERNAL_CMD`, since Git Bash lives under `Program Files`. `conformance_report.py` resolves the same way locally, because a script does not import from `tests/`. On macOS and Linux nothing changes: `which` returns the bash that a bare name would have started. `tests/test_bash_pinned.py` reads the suite's AST and fails on an argv that starts with the literal `"bash"`, a command string handed to a subprocess environment that starts with `bash `, or a second copy of the resolver in a test module; on the previous `main` it names 37 call sites, the environment string and the three copies. The expected argv values in the external-command split test are data, not calls, and are left alone. `scripts/eval/retrieval_eval.py` had the same collision in production: `--mode external` split `RETRIEVAL_EVAL_EXTERNAL_CMD` into argv and ran a bare `bash` first token. That token is now resolved by path right after the split (from #313, by @Ramnath0521).

- **The docs named eight slash commands that do not exist, and a reader who typed one got silence (#304).** `SKILL.md` told people to run `/obsidian-setup` to wire the SessionStart hook. No `commands/obsidian-setup.md` was ever written, so no adapter built it and `install.sh` never installed it; `bash scripts/setup.sh "/path/to/vault"`, named in the same sentence, does that job. The README's comparison table was worse, because it is the first table a visitor reads: it advertised `/emerge`, `/challenge`, `/world`, `/ingest`, `/reconcile`, `/synthesize` and `/export`, each a short form of the real `/obsidian-` command, and none of them answer to anything. A wrong name costs more than a missing one, since the reader cannot tell a broken install from a bad line, and it travels: a third-party evaluation of this repo repeated `/obsidian-setup` in its own install steps. `tests/test_doc_command_names.py` now requires every backticked `/name` in `SKILL.md` and the README to have a `commands/<name>.md`, and fails with all eight on the previous `main`. Backticks are the filter, so `/path/to/vault`, `</summary>` and a bare `/dist` are left alone. Three exemption sets carry the names that are real but are not commands of this repo, each with its reason: another tool's command (`/plugin`, `/schedule`, `/connect`, `/skills`), a scheduled agent that runs on a timer (`/obsidian-nightly` and the other three), and a command consolidated into another one, which is named only in the sentence that says so. A second test fails if an exemption ever names a command that does exist, so an exemption cannot quietly stop the fence checking a real command.

- **`/obsidian-health` orphan-checked the daily notes and the operations log in a wiki-style vault, one finding per day, forever (#292, reported by @JamBeatss).** `check_orphans()` exempted dated-series folders through a hardcoded list of Obsidian-style names, compared against the note's top folder and spelled with capitals. It therefore knew one of the two documented layouts. Wiki-style daily notes live at `wiki/daily/YYYY-MM-DD.md`, whose top folder is `wiki`, so every one of them rang, while `Daily/YYYY-MM-DD.md` in a vault next door did not: the same note was noise or not depending only on which documented layout its owner picked. `Logs/`, the operations log `/obsidian-init` writes and nothing is meant to link, was in neither layout's list. The exemption now reads the folder that decides it, which is the second path component under `wiki/` and the first everywhere else, casefolds it, and reads a slugged name (`wiki/life-chapters/`, which bootstrap writes for a preset folder with no explicit mapping since #287) as its spaced form. Six tests in `tests/test_vault_health_precision.py`, four of which fail on the previous `main`.

  The noise this removes is substantial on a vault that has been running a while: on a 2,270-note vault the orphan count went from 319 to 169.

  One test from #291 moved with it. It demonstrated the bare-filename collision using `wiki/daily/` and `Logs/`, which is where that collision actually bites, but both folders are exempt now and cannot show it. The same assertion is made with two ordinary folders instead.

- **`/obsidian-health` counted macOS AppleDouble files as notes, and matched incoming links by bare filename (#290, reported by @JamBeatss).** Two defects in `scripts/vault_health.py`, both reproduced from the report. (1) On a volume with no native extended attributes (exFAT, FAT32, many SMB shares) macOS writes a small binary `._<name>` companion beside every file it touches. `load_vault()` walks `rglob("*.md")`, which matches `._Note.md`, so each companion was parsed as a note and reported three times over: as an orphan, as missing frontmatter, and as a same-title duplicate of the real note. On a vault kept on an exFAT drive those outnumbered the real findings, and no `.vault-config.json` key could suppress them, since `exclude-dirs` matches directory names and `exclude-paths` matches prefixes. Deleting them does not last either, because macOS writes them again on the next save. Dot-prefixed paths are now skipped by both the note walk and the file index, which is the rule Obsidian itself applies. (2) `check_orphans()` registered every link under its bare filename and matched notes only by stem, so one link vouched for every note sharing a filename anywhere in the vault. The skill's own layout collides this way on any day that has both files: linking the daily note `wiki/daily/YYYY-MM-DD.md` hid that day's `Logs/YYYY-MM-DD.md` from the scan, and one linked `projects/*/README.md` covered all the others. Path-qualified links are now matched against the target's vault-relative path, as a suffix on a component boundary so Obsidian's shortest-unique-path form (`[[alpha/README]]` reaching `projects/alpha/README.md`) keeps resolving; bare links still match by stem. Six tests in `tests/test_vault_health_precision.py`, five of which fail on the previous `main`.

  Expect the orphan count to rise slightly after upgrading. Notes that were hidden behind a same-named sibling are now reported, which is the point. On a 2,270-note vault the count went from 318 to 319.

- **The SessionStart hook stopped silently skipping the vault manual (#285, reported and fixed by @Arman-no).** `hooks/load_vault_context.py` read `OBSIDIAN_VAULT_PATH` only via `os.environ.get(...)`, and a marketplace install writes that value into the config `.env` and never exports it as a real process env var - so the check failed on every session, including one whose cwd genuinely is the vault, and the manual never loaded at all. The same root cause as #124, #160 and #269, in a fourth caller. The hook now asks `scripts/osb_env.vault_path()` (see the config-resolver entry above) instead of reading the environment directly, which both fixes it and removes what would have been an eighth copy of the same lookup. Two tests in `tests/test_session_context_cap.py` pin it: a vault configured only in the `.env` file still gets its manual, and a config file that does not exist yet stays silent instead of raising.

- **A skill install on Windows registers a SessionStart hook that runs (#281, by @i-so-late).** Two things stood between `install.sh` and a working hook on Windows, both found by running the 0.16.0 installer against a throwaway home on Windows 10. First, `install.sh` kept its own `command -v python3` guard in front of `python3 setup_settings_hook.py`, the shape #280 removed from both hooks. On a stock install that name is the Microsoft Store alias: it passes the guard and exits 9009, which Git Bash reports as 49, and under the installer's `set -e` the run ended at "Registering session context hook...", before anything was registered and before the research toolkit step. `install.sh` now sources `scripts/python-interpreter.sh` and registers the hook through `osb_python`; with no interpreter at all it finishes and prints the hook to add by hand. Second, `setup_settings_hook.py` registered the command as `str(HOOK_PATH)`, which on Windows is `C:\Users\...` with no quotes. Claude Code hands the command to Git Bash, which reads every backslash as an escape, so the hook would have failed with "No such file or directory" at every session start: a headless session given a SessionStart command in that form recorded a non-blocking hook error and never ran the script. The command is now `shlex.quote` of the forward-slash path, which Git Bash runs, which survives a home directory with a space in it, and which leaves an ordinary macOS or Linux path exactly as it was, so existing entries there are not rewritten. Tests in `tests/test_python_interpreter.py` run the real installer against a throwaway home, once with `python3` shadowed by the alias and once with every candidate failing; `tests/test_setup_settings_hook.py` runs the registered command through bash from a path with a space in it.

- **`vault_stats` counted macOS AppleDouble files as notes (#312, by @Dev-next-gen).** #290 taught `vault_health` to skip dot-prefixed files, but `vault_stats` still walked them. On an exFAT, FAT32 or SMB volume every note has a binary `._<name>` companion that `rglob("*.md")` matches, so every count in the `index.md` stats block was inflated by one per real note. The check now lives in `vault_scan.is_hidden()`, so every tool that imports `vault_scan` can share it. A test in `tests/test_vault_stats.py` covers a `._` companion and a dot-prefixed folder.

## [0.16.0] - 2026-09-15 - The Silent Failure

### Added

- **`export_okf.py` targets OKF v0.2, which supersedes the v0.1 the exporter was written against (raised in #213 by @aermak).** Google published v0.2 on 2026-07-25 with two breaking changes, and the bundle was emitting v0.1 shapes: a concept's production time moved from a bare `timestamp` to `generated: {by, at}`, and provenance moved from a body `# Citations` list to a frontmatter `sources` list whose every entry requires a `resource`. Both are now emitted, and a wikilinked source resolves to the same bundle-relative path the body link does, so a citation and the link it came from never disagree about which file is meant; a source that resolves to neither a URL nor a real note is dropped rather than exported as a dangling resource. v0.2's optional lifecycle fields are emitted only where the vault states them: a note retired by `/obsidian-merge` is `deprecated` by construction, and a status this project already treats as withdrawn maps across - but `done`, `closed`, `parked` and `inactive` deliberately do not, because a finished project is completed knowledge rather than withdrawn knowledge and exporting it as deprecated would tell every consumer to discount a true record. `stale_after` is not invented. The bundle index declares `okf_version: "0.2"`. Four tests in `tests/test_export_okf.py`.

- **Sources say what the vault actually kept, and `/obsidian-health` reports when active knowledge rests on nothing local (#194, reported by @feariangod).** A populated `source_url` proves where a claim came from, not that the evidence is still readable, and an audit of a real vault found 24 source cards backed by bounded excerpts feeding 8 concept notes and a synthesis note with every structural, wanted-link, typed-edge and freshness check green. The raw-source schema gains `capture_scope`: `full-local` (the content is in the body), `bounded-local` (an excerpt, boundary marked) or `url-only` (the locator only). `/obsidian-ingest` sets it from what was saved rather than what was intended, and a new `Source payload` health check reports three separate problems: a note declaring it retained content while holding essentially no body is an **error** (a self-contradiction inside one file, no policy needed to call it); a `url-only` source that concept or synthesis notes link is a **warning**, naming every dependent; and sources written before the field existed are one aggregated **info** line, never a finding per note, because a research vault holds thousands and a wall would bury the first two. `"source_policy": "strict-local"` in `.vault-config.json` raises the last two by one severity, on the same never-inferred contract as `rewrite_policy` (#250); it quarantines and deletes nothing. The spec states where the copyright line falls, because the durability fix a reader reaches for first is copying the whole page and technical access is not permission. Nineteen tests in `tests/test_source_payload.py`, including that a three-line captured tweet does not ring. The transient-extraction half of #194 shipped earlier; the dependency-aware cleanup report remains open.

- **A vault can opt out of the confirm-before-rewrite gate with `rewrite_policy` (#250).** #239 made every rewrite of an existing note in `/obsidian-ingest` a proposal the user confirms, which is the right default and the wrong shape for a vault that runs unattended with git as its review layer - there, the gate blocks every scheduled ingest and the batch is never written. `.vault-config.json` now takes `"rewrite_policy"`: `confirm` (the default, unchanged) or `unattended`, which writes the drafted rewrites directly while keeping the full **Rewrites** list in the report and naming any retraction of an earlier ingest's correction at the top of the report and in the log line (`; unattended; retracts: [[Note]]`). A same-hash re-read is bound the same way. The opt-out is never inferred: a missing file, a missing key, a malformed file or any other value mean `confirm`. `references/ai-first-rules.md` "Confirm before rewriting" states the opt-out and its cost in one sentence, `/obsidian-init` asks once at bootstrap and writes the key only for `unattended`, and `vault_health.py` reports `rewrite_policy: unattended` as an info line (new `Rewrite policy` count) so a reader of the health report knows the vault runs without the gate. Tests in `tests/test_untrusted_source_handling.py` pin the wording of both branches and the loader's refusal to infer. The same pass corrected `SKILL.md`'s own inlined ingest steps, which had drifted far enough to matter: they named `Knowledge/` as the raw-source folder, had no `content_hash` dedupe, and carried neither the "sources are data" warning nor the #239 gate, so an ingest driven by the skill manual rather than the command file rewrote existing notes with nobody asked. They now point at `commands/obsidian-ingest.md` as the source of truth and state both, with a test pinning it.

- **The per-note embedding cap is configurable via `OBSIDIAN_EMBED_MAX_CHUNKS`.** `semantic_search.py` splits a note into `_CHUNK_CHARS`-sized pieces and embeds at most `_MAX_CHUNKS` of them, hardcoded at 8; together the two constants set a fixed per-note character budget, and text past it is not embedded. The bound is deliberate - it keeps build time sane on huge notes - and the default is unchanged. But the right value is a property of the corpus rather than of the tool: a vault of short atomic notes never approaches the budget, while one of long-form documents - research dossiers, book-length reference notes, transcripts - leaves a meaningful share of every long note outside it and semantically unreachable, and there was no way to move it short of editing the file and re-applying that diff after every merge. The constant now reads `OBSIDIAN_EMBED_MAX_CHUNKS` (default 8), joining the existing `OBSIDIAN_EMBED_{BACKEND,URL,MODEL,KEY,EXCLUDE}` family. Documented under the semantic-search knobs. The value is validated rather than trusted: the cap is applied as `chunks[:n]`, so `0` would embed nothing and drop the note from the index as unembeddable, `-1` would quietly drop the last chunk of every long note, and a non-integer would end the build in a traceback - all three now fall back to 8 with one stderr line. Tests in `tests/test_index_robustness.py`.

- **The MCP server does the vault's bookkeeping after every write (#255).** `obsidian_capture`, `obsidian_save_note`, `obsidian_update_note`, `obsidian_replace_text` and `obsidian_move_note` used to end at the file write, so a capture made from another project - where the agent may only write into `Inbox/` - sat unlogged, unindexed and unvalidated until some session in the vault happened to run. The server now validates the note, adds the `index.md` entry under the section for its folder (reported, never guessed, when the catalog has no such section), appends the operation-log line in the vault's convention (`Logs/YYYY-MM-DD.md` when that folder exists, else `log.md`), and optionally runs `OBSIDIAN_POST_WRITE_CMD <vault> <note> <action>` bounded by `OBSIDIAN_POST_WRITE_TIMEOUT` - the place for a commit-and-push, which the server itself never does. Every part is reported under its own key (`validation`, `index`, `log`, `post_write`), so `saved` alone never implies the rest; writes to the log and the catalog are never logged; `OBSIDIAN_BOOKKEEPING=0` switches the first three off. Eight tests in `tests/test_mcp_bookkeeping.py`.

### Changed

- **The OKM/OKF distinction says what it actually is.** README and `references/freshness-policy.md` both read "OKF standardizes how agent knowledge is written, OKM is a companion spec for keeping it true", which stopped being accurate when OKF v0.2 added `status`, `stale_after` and `verified` - the spec now has fields for recording staleness. The distinction that holds is sharper: OKF gives you somewhere to record that a fact went stale; OKM is the rule about what may be stored bare in the first place (every fact timeless, dated, or a pointer) and a linter that fails the build when it is not. A field cannot stop a note claiming "the pipeline has 13 deals" with no stamp on it.

- **A skipped daily-note or log append now says so on stderr (follow-up to #248, asked for in the #252 review).** `append_to_daily` and `append_to_log` already refused to touch a file that is not valid UTF-8 (a note an earlier Windows run rewrote in its code page), and `append_to_daily` returned `False` when there is no daily note for today - but every caller ignores the return value and the research note is saved by then, so the run looked like a silent success. Each refusal now prints one `[vault] ...` line naming the file and the one-time fix (re-save as UTF-8), in the style of the toolkit's other stderr notes. Nothing else changes: the file is still left exactly as it was. Tests pin all three lines.

### Fixed

- **Both hooks ran `python3`, which on Windows is the Microsoft Store stub that does nothing (#269, reported by @i-so-late).** The python.org installers, the default way to get Python on Windows, ship `python.exe` and `py.exe` and never `python3.exe`, so that name resolves to the App Execution Alias: it exists, prints nothing, and exits non-zero. The SessionStart hook therefore injected no skill root and no vault manual, leaving one line in the session transcript and nothing in the UI. Worse, `validate-ai-first.sh` gated checks 5, 6 and 7 behind `command -v python3`, which the stub passes, so the substitution, secret and tag checks were skipped without a word while checks 1-4 kept firing and made the hook look alive - a note with an em-dash or an `sk-` key passed clean on every Windows install since the v0.15 Windows work. Interpreters are now resolved by running them (`python3`, `python`, `py -3`, then `uv run --no-project python`), never by looking the name up. `hooks/load_vault_context.sh` is the new SessionStart entry point and says on stderr when it found nothing to run; the validator resolves once and names the checks it had to skip. `scripts/setup.sh`, `scripts/setup_settings_hook.py` and `install.sh` register the wrapper, and each recognises a hook entry registered before this change so re-running the installer upgrades it in place rather than leaving the dead command or adding a second entry beside it. The block lives in `scripts/python-interpreter.sh` with inline copies in both hooks, fenced against drift the way `platform-home.sh` already is. Twelve tests in `tests/test_python_interpreter.py`.

- **Check 5 of the write-time hook no longer reads Chinese, Japanese or Korean punctuation as a substitution (#271, reported by @i-so-late).** The ban exists because LLM output puts an em-dash where English wants a hyphen and curly quotes where it wants straight ones. CJK prose uses those same codepoints as its ordinary punctuation, so on a Chinese vault a single write came back with 15 lines of correct typography listed as rule violations, and the session's two options were to rewrite the text into wrong punctuation or to stop trusting the hook - the outcome check 6's own comment warns about. Dashes, quotes and the ellipsis are now skipped on a line containing Han, kana or Hangul; Unicode math and the non-breaking space stay banned in every language, because no script writes >= as U+2265. The test is per line, not per file, so an English paragraph inside a CJK note is still checked. Alongside it, `AI_FIRST_SKIP_CHECKS` (environment or the toolkit `.env`, comma-separated check numbers) turns an individual check off for one vault, so a vault the hook is wrong about does not have to carry a local patch of the file; the config `.env` is now read for every run rather than only when the vault path is unset. Nine tests in `tests/test_validate_hook_cjk.py`.

- **A vault manual too large for a hook payload is no longer announced as loaded (#270, reported by @i-so-late).** Claude Code caps hook output, `additionalContext` included, at 10,000 characters and replaces anything larger with a 2 KB preview plus a file path. `load_vault_context.py` measured nothing, so a real `_CLAUDE.md` arrived cut off inside its first section - under a header saying the manual was "already loaded" and a SKILL.md rule telling the session not to re-read the file. Every rule past the cut stopped applying and nothing said so; a session could only ever report the first of eight markers planted through the manual. The truncation was never the bug on its own, the claim on top of it was. Over the budget the hook now injects a pointer that says the manual is NOT loaded, names the file to read, and gives the way to stop hitting the cap; the skill root still ships either way, because no import can replace it. The size is counted in characters rather than bytes, so a CJK manual that fits is not sent down the pointer path for being three bytes to the character. SKILL.md now gates the skip on the manual actually being in context rather than on the hook being configured. And the durable fix lands with it: `/obsidian-init` and `bootstrap_vault.py` write `.claude/CLAUDE.md` holding `@../_CLAUDE.md`, which Claude Code imports natively at any size up to 4 MiB with no interpreter involved. Seven tests in `tests/test_session_context_cap.py`.

- **`/obsidian-health` no longer aborts on a wikilink longer than a filename can be (#272).** An unresolved link is checked against the filesystem in case it names a folder, and on Python 3.10-3.13 `Path.is_dir()` raises `OSError` (`File name too long`) instead of returning `False` once the name passes the filesystem limit. A captured web page with inline script in it is enough - `window.IJ_values = [[null,null,...]]` reads as a wikilink - and one such note ended the scan for the whole vault. The check now treats an `OSError` from `is_dir()` as "not a folder", which is what 3.14 already does, so the link is reported as the wanted note it is. Test in `tests/test_vault_health_precision.py`.

- **`/obsidian-health` no longer counts notes excluded by `OBSIDIAN_EMBED_EXCLUDE` as missing from the semantic index (#273).** The coverage check compared every note against the index, including the ones the build skips on purpose, so once an excluded folder passed the 5% floor the warning appeared on every run, and the fix it recommended - a rebuild - excludes the same notes again. Coverage is now measured over the notes the index is meant to hold. The prefix list is parsed in `scripts/vault_scan.py` and used by both `semantic_search.py` and `vault_health.py`, so the build and the check cannot disagree about which notes those are. Two tests in `tests/test_index_staleness.py`: excluded notes do not ring, and a real gap among the included ones still does.

- **A second writer's edit was lost silently when two processes edited one note (#217, reported by @konsone).** `write_exact` has been atomic since it was written, so the write was never the race; the gap is the read-modify-write every caller performs - `heal_links`, `triage_links`, `merge_notes`, and the MCP server's `update_note` and `replace_text` all read a note, transform the text, and write it back. A scheduled agent, a second session, or a sync client writing into that gap simply vanished: both writes succeeded and the later one won. The fix is optimistic, not a lock. `note_io.write_exact_if_unchanged` checks that the note still holds the bytes the caller read and raises `NoteChangedError` instead of overwriting; the MCP tools return the same refusal as an error the caller can act on. A lock was considered and rejected: it would drop lock files into a git-backed, LiveSync-replicated vault, need a second primitive on Windows, and still not cover the case that motivated the report, because an edit replicated onto disk by a sync client holds no lock. The residual microsecond window between the check and the rename is documented rather than papered over. Ten tests in `tests/test_concurrent_writes.py`, including a real second process editing during the gap, and a pin keeping the server's copy of the refusal in step with the scripts' one.

- **The lexical arm of hybrid search votes at full depth, and the comment above the knob said otherwise (#262, reported by @konsorsiumai).** `_FUSE_LEX_DEPTH` was introduced as the lever for a measured failure - on paraphrase queries the tail of the lexical ranking is term-frequency noise that demotes semantic answers - and shipped defaulting to `_FUSE_DEPTH`, so `min(_FUSE_DEPTH, _FUSE_LEX_DEPTH)` caps nothing until `OBSIDIAN_RRF_LEX_DEPTH` is set. The comment nonetheless read "lexical votes are capped to its strongest few", which sends a reader hunting elsewhere for a tail that is behaving exactly as configured. The default is unchanged - no measured sweep has picked a value, and the reported improvement was measured on one 51-note vault - but the comment now states that the default caps nothing, the README documents the knob and when to lower it, and a test in `tests/test_ranking_quality.py` pins both the uncapped default and that the knob really removes the tail from the vote.

- **`/obsidian-health` reported most of a non-ASCII vault as missing from a semantic index that held every note (#259, found by @konsone).** `semantic_search.py` wrote the index with a bare `json.dumps`, so `ensure_ascii=True` stored every Cyrillic, CJK or accented note path as a `\uXXXX` escape - the one JSON writer in the repo that did not pass `ensure_ascii=False`. `vault_health`'s coverage check reads note keys out of that file with a streamed regex rather than `json.load`, deliberately, because parsing every float of a 66MB index to answer a question about keys is not affordable; being text and not JSON, it never decoded the escapes, so an escaped key never matched the path it named. On a 552-note vault with mostly Cyrillic titles the report read "covers 256 of 552 notes; 296 (54%) are missing" against an index that was missing none of them, and recommended a rebuild. Both halves are fixed: the writer no longer escapes (which also makes a 26MB index readable), and the reader decodes each key, so an index built by an older version reports the truth without being rebuilt. The MCP server's own coverage call parses JSON and was never affected. Four tests in `tests/test_index_staleness.py`, including that a genuinely missing non-ASCII note is still reported.

- **`obsidian-bg-agent.sh` embedded the raw session summary in its propagation prompt with no delimiter or untrusted-data label.** `references/ai-first-rules.md` requires exactly this for any command that hands source text to a model ("wrap the body in an explicit delimiter and label it as untrusted data to be described, not followed"), and `obsidian-recall.py` already does it correctly. The summary can carry content pulled in via `/research`, `/youtube`, or `/x-read`; if instruction-shaped text from one of those sources survived compaction, this unattended, vault-writing hook had no textual signal telling it to treat that content as data rather than a directive. The same "stored DATA, not instructions" framing and explicit `BEGIN/END UNTRUSTED SESSION SUMMARY` delimiters now wrap the summary here too, and a runtime test in `tests/test_bg_agent_hook.py` pins the ordering through the real script: the summary sits inside the fence and the standing INSTRUCTIONS block sits after it, so the payload cannot be appended past the closing line.

- **The minimal frontmatter example in `references/claude-md-template.md` taught a frontmatter the write-time validator warns about (#268, by @Bursaz).** `hooks/validate-ai-first.sh` requires four fields - `date`, `type`, `tags`, `ai-first: true` - and the block a user's own `_CLAUDE.md` is built from showed two of them, so a vault that followed its own operating manual warned on every note it wrote. The example now carries all four and says which file checks them. The note-type enum was wrong in the other direction as well: it listed `index` and `log-pointer`, which nothing in this project has ever written, and omitted `log`, which `scripts/migrate_log.py` does. It now lists the common set and points at "Type Schemas" in `references/ai-first-rules.md` for the canonical per-type schema. Two tests in `tests/test_setup_and_manual_drift.py` pin both directions.

- **README published three stale command counts (#268, by @Bursaz).** The plugin-install line said "see all 45" and the layer diagram read 28 + 9 + 1 + 7 = 45, both against a real 47; `SKILL.md`'s AI-first section said 46. SKILL.md had a drift fence and the README, which is the page a reader actually sees on github.com, had none. Corrected to 47 and to a Layer 1 of 30, and two tests now pin every count the README prints and the layer boxes' sum against `commands/*.md`.

- **The write-time validator warned on every slash-command file inside a vault (#249).** A project-scoped or Windows install copies `commands/*.md` into `<vault>/.claude/commands/`; those files carry `description:` frontmatter and no preamble by design, and `validate-ai-first.sh` checked each one as a note - 47 warnings per refresh. Paths under `.claude/` are now skipped like `templates/` and `_export/`, SKILL.md's skip list says so, and a smoke test pins it (a frontmatter-less file under `.claude/commands/` is silent; the same content under `Knowledge/` still warns).

- **`freshness_lint.py` FRESH-3 no longer fires on RDF CURIEs or on `prefix:token` segments inside URLs.** `owl:Class`, `rdfs:label`, `skos:broader` name terms in a vocabulary, not records in a home system, so `owl`, `rdf`, `rdfs`, `xsd`, `skos`, `foaf`, `dc`, `dcterms`, `schema`, `prov`, `sh`, `dbo` and `wdt` join `POINTER_IGNORE`; and URLs are dropped from the line before the pointer scan, because a path segment such as Medium's `/resize:fit:1400/` matched the pointer shape while the URL guard only inspected the match itself. On a 6,400-note research vault this removed 126 findings, all false; a real unmapped id (`linear:ABC-123`) still rings. Covered by `tests/test_freshness_lint.py`.

## [0.15.0] - 2026-09-04 - The Port

### Added

- **`/podcast` summarizes Gemini-first with Grok fallback, and Apple `?i=` episode links resolve to the right episode (#233, by @konsone in #235).** Summarization mirrors `/youtube`: `GEMINI_API_KEY` set means Gemini (free tier, 1M context) with a transparent fall back to Grok on any failure; no key means the old Grok-only behavior. This is what makes the 480k transcript cap from #234 free on the default path. Apple's `?i=<trackId>` never appears in RSS guids, so `/podcast` used to fall back silently to the most recent episode; a second iTunes lookup (`entity=podcastEpisode`) now resolves the id to its title and `_pick_entry` matches on that. Covered by `tests/test_podcast_resolution.py`.

- **Tag syntax is checked at write time and by `/obsidian-health` (#221, raised by @konsone).** Obsidian renders a tag it cannot parse struck through, with no error in the UI, the CLI, or the file, so an agent that wrote `tags: [33]` or `[2.0]` never learned it had. `hooks/validate-ai-first.sh` check 7 and `vault_health.py`'s new `check_tag_syntax` (issue type `invalid_tag`, warning) apply Obsidian's rule: letters in any script, digits, `_`, `-` and `/` for nesting, no spaces or dots, and at least one character that is not a digit. Each finding names the tag and the fix (`store-33`, `v2-0`). The hook reads inline `[a, b]`, scalar, and `- item` block forms; `vault_health.py` reads inline and block through the same `parse_tags()` the taxonomy audit (#230) uses, so the two tag checks share one parser. The canonical-taxonomy half of the issue (`_meta/taxonomy.md`, `--consolidate`) stays open as an opt-in for a later PR.

- **`/podcast` gained a free Groq-hosted Whisper transcription fallback (#233).** The transcript chain was `rss-transcript-tag -> OPENAI_API_KEY Whisper ($0.006/min) -> show-notes`, so a podcast without publisher transcripts either cost money or collapsed to show notes, and without `OPENAI_API_KEY` at all there was no audio path. `scripts/research/lib/groq.py` inserts the free Groq tier (`GROQ_API_KEY`, `whisper-large-v3-turbo`) as the middle step, provenance `groq-whisper-api`. Design is downsample-first: one re-encode to 32kbps mono (Whisper resamples to 16kHz mono server-side anyway) puts a ~4.5h episode inside Groq's 25MB request cap in a single call; only longer episodes are split into `-ss/-t` chunks from the already-re-encoded file - bitrate exactly known, 10s overlap between chunks, sentence-boundary dedup at the seams, last chunk keeps its tail. Metadata is stripped on re-encode after a test episode carried an 18MB XMP blob in its chapters. Failure is episode-level all-or-nothing: any chunk 429 (free-tier ASH limit), oversize, or empty result returns None and the chain falls through to the OpenAI step unchanged - providers are never mixed inside one transcript. `commands/podcast.md` and `references/ai-first-rules.md` document the new step and the `groq-whisper-api` transcript-source value. Covered by 27 offline tests in `tests/test_groq.py`: a real local HTTP server exercises 429/200/empty/unconfigured paths over an actual socket (asserting the return value, the request count and the Authorization header), real ffmpeg/ffprobe drive the chunk-split math on a synthetic fixture, and the fallback-chain tests assert exact call counts proving a step is never invoked when it should not be.

- **`/obsidian-merge`: a command to merge the near-duplicate pairs `/obsidian-health` finds and stops at (#220, requested by @konsone).** Health is read-only by contract, so the merge itself was always a manual, skipped step - the same pairs kept showing up run after run. `scripts/merge_notes.py` does the mechanical half: union the two notes' frontmatter (canonical's value wins a conflict, the loser is recorded under a new `merged_from:` block), fold the retired note's title into the canonical note's `aliases:`, and replace the retired note with a short `type: redirect` stub (schema added to `references/ai-first-rules.md` § Documented exceptions) rather than deleting it, so old wikilinks keep resolving. Default is dry run - it previews the exact frontmatter diff and both proposed notes; nothing is written until `--apply`, and dry-run and apply share one `compute_merge()` so the preview can never drift from what gets written. `--from-health` resolves a pair from `vault_health.check_duplicates()` run live (this repo has no persisted health-report file); a duplicate group of more than 2 files is never auto-paired - it is reported and needs explicit `--canonical`/`--retire`, since nothing in the health check says which note should survive. The merged BODY is deliberately not composed by the script - `commands/obsidian-merge.md` composes it (one `## For future agent` preamble, both notes' provenance trails kept, contradictions between them listed rather than silently resolved, per `references/ai-first-rules.md`) and hands it to the script via `--merged-body-file`. Covered by `tests/test_merge_notes.py`: dry run writes nothing, `--apply` writes the redirect stub and folds the alias, frontmatter conflicts resolve canonical-wins, no conflict means no `merged_from` noise, `--from-health` resolves a real pair (and refuses a 3-file group), and a missing `--merged-body-file` errors before anything is written. Follow-ups landed on merge: list-valued fields (`tags`, `aliases`, `related-*`) present on both sides are unioned instead of treated as a conflict, so a merge never drops tags only the retired note carried; and when both notes share a filename stem (the common duplicate, `Ideas/X.md` vs `Archive/X.md`) the redirect links to the path-qualified `[[Ideas/X]]`, because a bare `[[X]]` is ambiguous and can resolve to the redirect note itself.

- **Behavior eval: does the vault make the answer better, not just the ranking (#197, built by @AaronProbha18 in #223).** `scripts/eval/behavior_eval.py` runs each question from a new `behavior` case set twice - once with vault retrieval as context, once from the model alone - and has a different model grade both blind against the case's known `answer_key`, then reports the overall delta, a per-category breakdown, and every case where the vault made the answer worse, never truncated. The case set lives in `corpus.py` (60 cases: fact 20% / decision 15% / relationship 10% / synthesis 30% / contradiction 25%; synthesis questions need two notes combined, contradiction questions need the reconciling note over a superseded daily-log line). Answers come from `research.lib.grok`, judging from the new `research.lib.gpt` (`OPENAI_API_KEY`, default `gpt-4o-mini` via `GPT_JUDGE_MODEL`), and a startup guard refuses to run if the two ever resolve to the same model. Opt-in and keyed; CI tests the plumbing with every LLM call mocked and never the scores. Follow-ups landed on merge: a question where search returns nothing is now answered with no notes and scored like any other case (it was dropped as "unjudged", which hid the vault's worst failures from the regression bucket), both arms are told not to mention notes or sources so the judge cannot tell the conditions apart from the text, and each case carries `retrieval_empty`. The corpus gained one contradiction line per daily note, so the published corpus hash in `scripts/eval/BENCHMARK.md` moved to `5773dc7f39b0c3b0`; lexical retrieval results on all three sets were re-run and are unchanged, hybrid was not re-run.

### Changed

- **The bash scripts share one home-resolution helper, and the Windows tests moved out of `tests/test_smoke.py` (review follow-ups to #243/#248).** The `USERPROFILE`-on-Windows block from #242 had been pasted into seven shell scripts. It now lives in `scripts/platform-home.sh` (`osb_platform_home` sets `OSB_WIN` and `OSB_HOME`), sourced by `install.sh`, `update.sh`, `scripts/setup.sh`, `scripts/run-command.sh` and the Telegram `setup.sh`. Two inline copies stay on purpose, because those files must run standalone: `hooks/validate-ai-first.sh` (copied by hand into other harnesses' hook systems) and `scripts/quick-install.sh` (`curl | bash`, before any checkout exists). `tests/test_platform_home.py` fails when either drifts from the helper, the same fence the tokenizer copies (#159/#188/#192) showed this repo needs. The six Windows-compat tests from #243 moved verbatim to `tests/test_windows_compat.py`. No behavior change.

- **The AI-first preamble may be written as an Obsidian callout (#237, raised by @molochplaisir).** Rule 2 named one spelling, the `## For future agent` heading, and `hooks/validate-ai-first.sh` check 4 and the MCP `validate_note` matched that heading only, so a vault whose ingest pipeline writes the preamble as a folded callout (`> [!info]- For future agent`, so a human sees the note content first) got a false "missing preamble" warning on every write. The callout carries the same title and the same 2-3 sentence summary, is plain text, and needs no plugin, so it is now an accepted equivalent: `references/ai-first-rules.md` rule 2 says so, and the hook, `validate_note`, and `vault_health`'s duplicate-similarity stripper recognize both spellings (any callout type, folded or not; the legacy labels `AI`, `Claude`, `Codex` included). The heading stays the default every command writes. A bold line or a paragraph without the title is still not a preamble. Covered by `tests/test_smoke.py::test_validate_hook_accepts_the_callout_preamble` and `::test_mcp_validate_note_accepts_the_callout_preamble`.

- **The transcript caps from #234 are documented, validated, and the note says who summarized it.** `YOUTUBE_TX_LIMIT`, `PODCAST_TX_LIMIT` and `GROQ_API_KEY` are in `.env.example`; a cap that is not a whole number (`480k`, `1e6`) exits naming the variable via the new `config.get_optional_int()` instead of an `int()` traceback; and the `## For future agent` preamble of `/youtube` and `/podcast` notes names the model that actually wrote the summary (Gemini or Grok) instead of always saying Grok. `commands/podcast.md` now states the free-tier limit the Groq step runs under (7,200 audio-seconds per hour, so about 2h per episode) rather than only the 25MB byte fit.

- **`/obsidian-ingest` checks for a previous ingest before writing a raw note (#218, raised by @konsone).** The raw-source schema already carried `source_url` and `content_hash`, but nothing read them back, so ingesting the same article twice produced two raw notes and a second round of rewrites. Step 5 now defines `content_hash` (first 16 hex of SHA-256 over the verbatim text) and searches `raw/` for it and for the normalized `source_url` first: same hash means re-read the existing raw note instead of writing a second; same URL with a new hash means the source changed, so the new raw note carries `supersedes:` and the old one goes to the Contradictions agent. The archive and rebuild half of the issue was declined on the issue thread.

- **Batch ingests get a documented unit-of-work boundary instead of a staging mode (#222, raised by @konsone).** `references/write-rules.md` gains a "Batch writes" section with the git-branch recipe and the LiveSync snapshot equivalent, and `/obsidian-ingest` points to it. A `_staging/` redirect inside the command was declined because the agent's own Write and Edit tools would not honor it, leaving half a batch live while the user believed it was staged.

- **The vault preamble vocabulary is now `## For future agent`, replacing `## For future Claude` (discussion #182, raised by @konsone).** The framework has shipped cross-platform since v0.10 (Codex CLI, Gemini CLI, OpenCode, Hermes, Pi, agent-skills), and naming one vendor's agent in every note's preamble was historical, not deliberate. All 46 commands, `references/ai-first-rules.md`, `SKILL.md`, the adapters, and the write-time validator now use `future agent`. **No vault migration needed:** `validate-ai-first.sh` check 4 accepts `## For future agent`, `## For future AI`, `## For future Claude`, and `## For future Codex`, so existing notes stay valid; new writes use the neutral form.

- **Improve spanish commands triggers** Native speaker audit of all 46 command triggers. Replaced literal translations with natural phrases people actually say, e.g., "ponme al tanto de todo" instead of "carga mi mundo". Improves trigger recognition for Spanish users without breaking routing precedence. (19 commands refined)

- **MCP tool names carried the plugin name twice (#177, reported by @mpuglin).** The `mcpServers` key in `.claude-plugin/plugin.json` was also `obsidian-second-brain`, and Claude Code composes tool names as `mcp__plugin_<plugin>_<server>__<tool>` - so every tool arrived as `mcp__plugin_obsidian-second-brain_obsidian-second-brain__obsidian_search`, 57 characters of prefix of which 21 were the name repeated for nothing. In a dropdown or a permission prompt the prefix crowds out the part that identifies the tool. The server key is now `vault`, giving `mcp__plugin_obsidian-second-brain_vault__obsidian_search`. The plugin name, install identity, marketplace entry and slash-command namespace are all unchanged; the reported request was to rename the plugin itself to `o2b`, which was declined because the name is the install identity of the repository and the commands are already `obsidian-*`, so `o2b:obsidian-daily` would save little. **Upgrade note:** if you allowlisted these tools by their full name in `settings.json`, update the server segment from `obsidian-second-brain` to `vault`.

### Security

- **The Telegram journal bot accepted messages from any sender (discussion #215, raised by @robertcamero).** `telegram_journal.py` polled `getUpdates` and processed every message it got, with no check on who sent it. A bot's username is discoverable, so anyone who found it could append to the daily note, create entity stubs, spend the OpenAI/Anthropic keys, and - the part that matters most for an AI-first vault - plant text a later agent reads as trusted memory. There is now a required `TELEGRAM_ALLOWED_CHAT_IDS` (comma-separated chat ids) and the gate fails closed: an unlisted sender is refused and logged, never processed. With the variable unset the bot processes nothing; the one thing it does is reply with the sender's chat id so the owner can complete setup, and once a list exists strangers get silence. `setup.sh` prompts for the id, the env template and README document it. **Upgrade note:** existing installs stop saving until `TELEGRAM_ALLOWED_CHAT_IDS` is set; message your bot once and it tells you the id to add. Covered by `tests/test_telegram_ingest.py` (empty list refuses, listed id passes, unlisted id refused, int and string ids compare equal).

- **Fill-links could write outside the vault (discussion #215, raised by @robertcamero).** `create_stub()` built the new note's path as `folder / f"{name}.md"` where `name` is whatever sat inside a `[[wikilink]]` the model wrote, so a link like `[[../../somewhere/else]]` resolved to a write outside the vault. Names now pass through `safe_note_path()`: path separators, `..`, dot-names and NUL are refused, and the resolved parent must be exactly the target folder. Refusals log to stderr and skip the stub; the capture itself still saves. Media and PDF filenames were already date-prefixed and character-stripped and are unchanged. Covered by `tests/test_telegram_ingest.py` (traversal, absolute path, dot-names refused; plain and Unicode names accepted).

- **Lockfile carried two dependencies with published advisories (discussion #215).** `cryptography` 47.0.0 -> 50.0.1 (GHSA-537c-gmf6-5ccf) and `urllib3` 2.6.3 -> 2.7.0 (GHSA-mf9v-mfxr-j63j, streaming decompression bypass - relevant because the research toolkit fetches arbitrary external URLs and feeds). Both are transitive via `google-api-python-client`; `uv.lock` only, no `pyproject.toml` change.

### Fixed

- **`/obsidian-ingest` rewrote existing notes without confirmation, and `content_hash` keyed on the raw capture (#239, raised by @konsorsiumai).** Two spec gaps. `references/ai-first-rules.md` has said since #215 that a write which modifies an existing note on the strength of an external source is a proposal the user confirms, but the rule never reached `commands/obsidian-ingest.md`: step 6 mandated rewriting existing pages and the same-hash re-read from #218 routed straight into it, so a re-ingest could rewrite a daily note, `Home.md`, entity and idea notes and `log.md` with no question asked. Step 6 now carries the rule in full (new pages proceed; rewrites of existing notes are collected as drafted proposals and confirmed once as a batch, re-reads included), step 7 runs only for pages actually written, and the report lists the proposals with their outcome. Separately, `content_hash` was defined over "the verbatim source text", and a JS-rendered page yields different bytes on every fetch (JS shell vs rendered DOM, navigation chrome, a `+` where the page had `-`), so an unchanged source hashed as "changed" and the branch table had no row for it. The hash is now computed over a canonical form (article body only, LF, list markers normalized, whitespace collapsed) while the raw note body stays verbatim, and the same-URL-different-hash branch diffs the canonical texts first: capture noise is a re-read, only a real change writes a `supersedes:` raw note. Both are prompt-level contracts; `tests/test_untrusted_source_handling.py::test_ingest_treats_rewrites_of_existing_notes_as_proposals` pins the wording so it cannot drift out again.

- **`validate-ai-first.sh` exited 0, silently, when a write payload named a tool but carried no path key it knew (#171, the open item from @tonydzi's codex-cli reports).** The hook read `file_path` and `filePath` (and `args.*`); a host that sends the path under another key (`path`, `uri`) got exit 0, indistinguishable from "not a vault file", and the write went unchecked with no trace. The hook now reads `notebook_path`/`notebookPath` as well (the `NotebookEdit` shape its own matcher names; an `.ipynb` then drops at the `.md` gate as before), and when a payload names a `tool_name` but no known path key it prints one stderr line naming the tool and the payload keys and exits 1: non-blocking, the write stands, but the miss is visible. Input with no `tool_name` stays silent. Covered by `tests/test_smoke.py::test_validate_hook_is_loud_when_the_payload_has_no_known_path_key`.

- **Two tests from #243/#248 could not fail on the CI runner (found in review).** `tests/test_research_cjk_and_models.py`'s `cp1252_default` fixture substituted cp1252 only when `Path.open()` received `encoding=None`, but `read_text()`/`write_text()` resolve `None` to the string `"locale"` before calling `open()` (Python 3.10+), so the fixture intercepted only the direct `open("a")` in `append_to_log` and the scan test passed against the pre-fix code; the guard now matches `"locale"` too, and the pre-fix call shape fails under it on every platform. `tests/test_windows_compat.py::test_retrieval_eval_external_cmd_splitting` built its Windows cases only when the runner's own `os.name` was `"nt"`, so the non-POSIX branch of `_split_external_cmd` had zero CI executions; the test is now parametrized over both branches and sets `os.name` in the subprocess, which is the only thing the function keys on.

- **On Windows, the bash and Python halves could resolve the optional `~/.config/obsidian-second-brain/.env` to two different folders, so a user who followed the README configured one half only.** Python's `Path.home()` reads `USERPROFILE` and ignores `HOME` (Python 3.8+), while the bash scripts (`install.sh`, `scripts/setup.sh`, `update.sh`, `scripts/quick-install.sh`, `scripts/run-command.sh`, the Telegram setup, and the write-time hook) read `$HOME`. Git Bash normally sets `HOME` to `USERPROFILE`, but a machine whose Windows environment defines `HOME` (a corporate roaming home on another drive) split the config: the installer and the hook used one drive, the research toolkit, the eval, and the MCP server another, and the classic installer also wrote its hook and commands under a `~/.claude` that Claude Code (which keys on `USERPROFILE` too) never reads. On Windows shells the bash scripts now resolve the home as `USERPROFILE` (via `cygpath`), matching Python and Claude Code; on macOS and Linux `HOME` is still the home and nothing changes. The research loaders and the retrieval eval also honor `OBSIDIAN_ENV_FILE` now, the override the MCP server and the hook already accepted, and `install.sh` and `scripts/setup.sh` write the file there when it is set, so one variable steers every half. On Windows the value must be a native path (`C:/...` or with backslashes, both of which bash and Python open), because the Git Bash spellings `/c/...` and `/cygdrive/c/...` are meaningful to bash only; the installers also print the resolved `.claude` paths instead of `~/...`, which bash expands from `HOME`. README documents both, with the `USERPROFILE`-based commands for a corporate-`HOME` machine and the caveat that a Cygwin- or MSYS-built Python follows `HOME`. Covered by `tests/test_windows_compat.py::test_validate_hook_env_fallback_uses_the_platform_home` (branches per platform) and `::test_research_config_honors_env_file_override`.

- **`scripts/link_graph.py` crashed on Windows for any vault whose titles carry a character outside cp1252, and seven other tests failed there on POSIX assumptions.** The script printed JSON with `ensure_ascii=False` to a pipe that Windows encodes as cp1252, so a decomposed title (u + U+0308, the macOS filename form its own test exists for) raised `UnicodeEncodeError`; stdout is now forced to UTF-8 the way `bootstrap_vault.py` already does, and `retrieval_eval.py`'s JSON report gets the same guard. `retrieval_eval.py --mode external` also lost the backslashes of a Windows engine path to POSIX-mode `shlex.split`; on Windows the command is now split in non-POSIX mode with one layer of surrounding quotes removed, so quoted paths with spaces and quoted literal arguments survive too, and on every platform a JSON array is accepted as the exact form for anything shell quoting cannot express (embedded quotes, empty arguments); covered by `tests/test_windows_compat.py::test_retrieval_eval_external_cmd_splitting`. The remaining failures were the tests' own POSIX assumptions, and the fixes change nothing on macOS or Linux: two file-mode checks skip only the mode-bit assertion on Windows, which keeps no POSIX owner/group distinction so `chmod 600` cannot be verified through `st_mode` there (their other assertions still run), three home-redirection tests also set `USERPROFILE` (what `Path.home()` reads on Windows; `HOME` is ignored there), the background-agent test compares the vault path in the form Git Bash reports, and both link-graph tests decode UTF-8 explicitly. On Windows the suite had 8 failures (583 passed) at the base this work started from and none attributable to this change at the current base; six failures in newer code that this change does not touch remain and are listed in the pull request as pre-existing.

- **`validate-ai-first.sh` was a silent no-op on Windows.** Claude Code passes the written file's path with backslashes (`C:\Users\...`) while `OBSIDIAN_VAULT_PATH` is written with forward slashes, so the vault-scope prefix match never hit and the hook exited 0 before reading the note. Found on a fresh Windows plugin install where two deliberately bad writes (no frontmatter, via Write and via Edit) produced no warning, while the same script run by hand with a forward-slash path warned. On Windows shells both paths are now normalized before the comparison: `/c/...` and `/cygdrive/c/...` are mapped to the drive form first (each runtime misreads the other's spelling), `cygpath -m` then gives the mixed form, a trailing separator is stripped, and the comparison is case-insensitive because the filesystem is. On macOS and Linux the paths are compared exactly as given, so a legal backslash in a filename stays intact. The `.env` fallback drops a trailing carriage return (a file written on Windows and read by macOS or Linux bash kept it in the vault path and never matched) and accepts a native backslash path in `OBSIDIAN_ENV_FILE`; a note saved with CRLF line endings is validated from a carriage-return-free copy instead of failing every delimiter check. Bash 3.2 features only, so the macOS system bash keeps running the hook unchanged. Covered by `tests/test_windows_compat.py::test_validate_hook_matches_windows_backslash_paths` (runs on Windows, skipped elsewhere).

- **`merge_notes.py` carried the retired note's `date` and `status` into the canonical note, and reported no conflicts, when the canonical note started with a UTF-8 BOM.** `note_io.read_exact` returns the text byte-exact, BOM included (the rule from the BOM fix: files keep their BOM, readers stop being blind), but `export_okf.parse_note` anchored on `---` at the very first character and so saw no frontmatter at all; with the canonical side empty, every field of the retired note joined the union unopposed and nothing counted as a conflict. `export_okf.py` itself was never affected, because it reads with `utf-8-sig`. `parse_note` now skips a leading BOM the way `vault_scan.split_frontmatter` already does, and the merge writes each rewritten note with the BOM it carried, so a byte an editor put there stays there. Found while fixing the CRLF case (the entry below); covered by `tests/test_merge_notes.py::test_bom_notes_keep_their_frontmatter_through_a_merge`, `::test_a_bom_on_the_retired_note_stays_on_its_redirect_stub` and `tests/test_frontmatter_parity.py::test_parse_note_skips_a_bom_like_the_canonical_parser`.

- **`cache.get()` with a zero TTL could return the entry it was asked to expire, so `tests/test_research_sources.py::test_cache_roundtrip` was flaky on Windows.** The check was `age > 0`, with the age computed as `time.time()` minus the file's mtime. Those two timestamps come from clocks of different resolution, so a read that follows a write closely can compute an age of exactly zero or even a negative one (on the Windows machine this surfaced on, `time.time()` advances in 15.6 ms steps and the test failed in 1 of 8 isolated runs), and no comparison against such an age can implement "expire at once". A TTL of zero or less is now decided before the clock is consulted, and every lookup is a miss, which is what the test and `RESEARCH_CACHE_TTL_HOURS=0` already meant; positive TTLs are unchanged, and `put()` still writes, so the entry is there the moment a positive TTL is configured again. `::test_cache_zero_ttl_is_a_miss_without_consulting_the_clock` makes the clock raise for a TTL of 0 and of -1 and freezes it at the entry's own mtime for the positive case, so it is deterministic on every platform and fails without the fix.

- **On Windows the research toolkit saved notes in the system's ANSI code page (cp1252 on a Western-European system): a `/notebooklm` synthesis or a research note (`/research`, `/research-deep`, `/youtube`, `/podcast`, `/x-read`, `/x-pulse`) carrying a character the page cannot encode, a CJK word for instance, failed with `UnicodeEncodeError`; one carrying only characters it can encode, an accented letter say, was written as code-page bytes that Obsidian reads as mojibake; and `append_to_daily`, which rewrites the whole daily note, left it empty on the first kind, because `write_text()` truncates before it encodes.** `notebooklm.py`'s save and `lib/vault.py`'s `write_note`, `append_to_log` and `append_to_daily` named no encoding, which is UTF-8 on macOS and Linux and the code page on Windows. They now write (and `append_to_daily` reads) UTF-8, the encoding Obsidian expects; a daily note or a `log.md` that is not UTF-8 (one an earlier Windows run wrote in its code page) is left untouched and the append reports that it did nothing, rather than rewriting the note lossily or leaving the log in two encodings; the `/notebooklm` save moves into `save_note()` so it can be exercised without Gemini. Raised in review as the missing half of the read-side entry below; covered by `tests/test_research_cjk_and_models.py::test_vault_writes_are_utf8_under_a_cp1252_default`, which emulates the Windows default on every platform, `::test_append_to_daily_leaves_a_note_it_cannot_decode_alone` and `::test_append_to_log_leaves_a_log_it_cannot_decode_alone`.

- **The `/research-deep` and `/notebooklm` vault scans found nothing for a CJK topic on Windows, and every note excerpt `/research-deep` sent onward was mojibake for any non-ASCII character.** `vault_scan()` in `research_deep.py` and `notebooklm.py`, and the two excerpt reads in `research_deep.py`, called `read_text(errors="ignore")` with no encoding, which is the platform default: UTF-8 on macOS and Linux, and on Windows the system's ANSI code page (cp1252 on a Western-European system), where a UTF-8 note's Japanese decodes to other characters and the CJK-aware tokenizer from #212 had nothing to match against. The reads now name `encoding="utf-8"`, the encoding Obsidian writes, so Windows reads exactly what the other platforms already did. Found by `tests/test_research_cjk_and_models.py::test_vault_scan_finds_cjk_topic` on Windows; `::test_vault_scan_and_excerpts_read_utf8_under_a_cp1252_default` emulates that default, so the case runs on the ubuntu CI runner too.

- **`freshness_lint.py` named files with backslashes on Windows (`Boards\Work.md`), so a finding's `file` field differed by platform.** The field is the contract of the `--json` output and of the tests, and the vault's own link form is forward-slash, so the relative path is now rendered with `as_posix()`, the way `vault_health` already keys its notes (B40 in `tests/test_frontmatter_parity.py`); output on macOS and Linux is unchanged. Found by `tests/test_freshness_lint.py::test_obsidian_comments_are_invisible_not_content` on Windows; `::test_findings_name_files_with_forward_slashes` pins the rendering with a `PureWindowsPath`, so the case runs on the ubuntu CI runner too.

- **`merge_notes.py` lost the frontmatter of any note saved with CRLF line endings: with both notes CRLF it rewrote the canonical note with all of its original frontmatter fields lost (only the alias the merge adds survived), with one it silently dropped that note's fields from the merge (the canonical note's own values replaced by the retired note's, or the retired note's fields never unioned) and reported no conflict.** The script hands `export_okf.parse_note` the byte-exact text `note_io` returns, and the parser's fence pattern accepted spaces and tabs after `---` but not a carriage return, so `---\r\n` never matched and the note read as having no frontmatter at all. `export_okf.py` itself was not affected, because its own read is in text mode and normalizes the newlines first; `vault_health` and `vault_stats` read the byte-exact text correctly, because their patterns use a whitespace class that absorbs the `\r`, which is the S9 disagreement `tests/test_frontmatter_parity.py` exists to pin, on line endings this time. `export_okf.FM_RE` and its twin `vault_scan.FRONTMATTER_RE` now accept `\r\n` on both fences (as `build_site.py`'s own pattern already did); PyYAML reads the carriage returns inside the block as line breaks, and LF notes match exactly as before. Found by `tests/test_merge_notes.py` on Windows, where `write_text()` saves the fixtures with CRLF and four of its cases failed; the parity test gains a CRLF fixture across all four patterns, and `::test_crlf_notes_keep_their_frontmatter_through_a_merge` pins each side and both on every platform.

- **`/notebooklm` produced an empty filename for Cyrillic and any non-Latin topic (#227, reported and fixed by @konsone in #228).** `notebooklm.py` kept a private `slugify()` that dropped everything outside `[a-z0-9\s-]`, so a Russian topic became `YYYY-MM-DD - .md` and an empty Gemini File Search `display_name`. It now uses the shared `lib.vault.slugify()` (Unicode word characters, the one `/youtube` already used) plus the `or "untitled"` fallback for symbol-only topics. One visible change for ASCII topics: the shared slugify keeps spaces where the private copy wrote hyphens, so a note is now `2026-08-26 - smart home automation.md` rather than `2026-08-26 - smart-home-automation.md`, which is the form every other research command already writes.

- **The MCP server registered zero tools on older `mcp` 1.x releases (#229, reported and fixed by @mpuglin).** `server.py` opened with `from __future__ import annotations`, which turns every annotation into a string; fastmcp in `mcp` 1.9.x calls `issubclass(param.annotation, Context)` while registering tools, so the first `@mcp.tool()` raised `issubclass() arg 1 must be a class` and the client listed no vault tools. The import is removed and a comment in its place explains why it must stay out. Scope note, corrected from the PR text: on a current index `mcp<2` resolves to the latest 1.x (1.29.1 at merge time), where the server already worked, so this is a hardening for environments whose resolver lands on an older 1.x, not a fix for every install.

- **The MCP server adopted whatever project the user was working in, writing a `uv.lock` into their repository and syncing their dependencies into a `.venv` beside it.** The manifest launched the server with `uv run --with 'mcp<2' python ...`, and Claude Code starts an MCP server with the user's working directory as cwd. `uv run` discovers a project from cwd upward, so in any repository carrying a `pyproject.toml` uv treated that repository as the project it had been asked to run in. Measured on Windows with uv 0.11.2 against a repo whose `pyproject.toml` carries only pytest configuration, with no `[project]` and no `[tool.uv]` table: that was still enough for uv to create a `.venv` on Python 3.14 (the repo targets 3.12) and write a 52-byte `uv.lock` at the root on every session start, and since `uv.lock` was untracked there it surfaced as repository noise the user had to explain. Against a repo declaring a real dependency the same launch installed that dependency into the user's `.venv`, so this mutated environments rather than only littering them. Nothing in the server needs a project: its only non-stdlib import is `mcp`, which `--with` already supplies, and `vault_ops` sits beside it. The launch now carries `--no-project`, which skips discovery entirely, everywhere the command appears: the plugin manifest, `scripts/setup.sh`, `SKILL.md`, `README.md`, and the integration's own README, `server.py`, `live_test.py` and `vault_ops.py`. Not a Windows problem: cwd-based discovery behaves identically on macOS and Linux, where a user's repository is if anything more likely to declare real dependencies. Covered by `tests/test_plugin_manifest.py::test_mcp_launch_isolates_from_the_working_directory_project` (the manifest must carry the flag) and `::test_no_documented_command_adopts_the_users_project` (no copy anywhere in the tree may drop it again).

- **`freshness_lint` flagged quoted examples of the illegal form - a note explaining the freshness policy could not pass FRESH-1 (#204).** A line that quotes "the pipeline has 13 deals" as teaching material is quotation, not a claim, but the linter had no way to know. Per the direction agreed on the issue: a line-scoped `<!-- freshness: example -->` directive now suppresses FRESH-1 for exactly the line it sits on - an HTML comment, so invisible in rendered markdown and greppable in source. Deliberately narrow: FRESH-2 and FRESH-3 on the same line still fire (the directive says "this claim is quotation", not "skip this line"), there is no block form (fences and blockquotes remain the whole-region exemptions), and the directive is recognized only where FRESH-1 could apply - backticked it is documentation, inside a code fence or `%%` comment it is invisible, in frontmatter or a FRESH-4 snapshot container it is inert, so none of those suppress and none warn. The lint also lints itself: a directive that suppressed nothing warns as **FRESH-5 (unused suppression)**, as do redundant duplicates on one line, so defensive copies get removed instead of accumulating. Covered by `tests/test_freshness_lint.py` (suppresses only its own line, example line fails without the directive, FRESH-2 and FRESH-3 unmuted on the same line, unused directive warns, backticked directive stays documentation, directive hidden in a `%%` segment stays inert while the visible claim still fires, directive after a closing `%%` still counts, snapshot regions stay untouched, duplicates warn, frontmatter inert).

- **`/notebooklm`'s `vault_scan` kept the pre-#159 tokenizer and returned zero notes for CJK topics (#212, reported by @hamidasiblog) - and the grep the reporter suggested found a fourth copy in `research_deep.py`.** The whitespace split + `len(w) > 2` filter survived #159, #188 and #192 because every fix landed in one path and not the others; #188 even edited the very function the copy lives in. Both `vault_scan`s now tokenize via the new `lib/vault_terms.topic_terms()`, which delegates to `vault_ops._query_terms` - the same CJK-aware tokenizer search uses, lowercased, stopword-free, CJK runs as bigrams. A fence test (`test_no_stale_tokenizer_copies_left_in_command_paths`) fails if a split-plus-length-filter copy regrows anywhere under `scripts/research/`; the `scripts/eval/` copies keep their own semantics deliberately (gold matching) and are out of its scope. Covered by `tests/test_research_cjk_and_models.py`, including an end-to-end scan where `朝ラボの習慣` must find the note that contains it.

- **`/youtube` could never fetch a non-English transcript (#210, reported by @hamidasiblog).** `get_transcript()` called `api.fetch(video_id)` bare, and youtube-transcript-api defaults to `('en',)` - so a Japanese video with retrievable auto-captions failed with `NoTranscriptFound`, which reads as "this video has no captions" when the transcript was one argument away. Preferences now come from `TRANSCRIPT_LANGUAGES` (comma-separated, default `en`, documented in `.env.example`), and a preference miss falls back to whatever language the video actually has before giving up, with a stderr line naming the language used. Covered by `tests/test_research_cjk_and_models.py` (configured preference passed through, fallback to available language, true-absence still returns None).

- **`/youtube` and `/podcast` silently truncated transcripts at 24k chars, discarding 90%+ of long-form content (#233).** Both `TX_LIMIT` constants predate the Gemini summarization path and its 1M-token context, and still carried comments claiming they were "plenty for grok-4 context." Measured on a 3-hour episode: the model saw only the first ~6K tokens of a 289,911-char transcript. Both caps now read `YOUTUBE_TX_LIMIT` / `PODCAST_TX_LIMIT` via `config.get_optional()`, default 480k chars (~120k tokens), keeping the truncation note for anything still larger.

- **The pinned Gemini default 404s for new API keys, so Gemini summarization failed out of the box (#211, reported by @hamidasiblog).** Model access is per-key-cohort, measured in both directions on 2026-08-16: the reporter's new key gets "no longer available to new users" on `gemini-2.5-flash`, while a pre-retirement key generates with it and 404s on the `-latest` aliases - and `GET /models` returns 200 for names a key cannot generate with, so only a generation call can validate a model. No single pinned name works for everyone: `lib/gemini.py` now walks a fallback ladder (`gemini-2.5-flash`, then `gemini-flash-lite-latest` before `gemini-flash-latest` - the reporter's quota table shows the Lite tier carries ~25x the free-tier daily quota, and these are summarization workloads - then `gemini-3.1-flash-lite`) on 404 and remembers the first model that generates; `/notebooklm` reuses the same ladder at its File Search call. An explicit `GEMINI_SUMMARY_MODEL` / `NOTEBOOKLM_MODEL` is never laddered - a configured name that 404s fails loud, and every terminal error now names the env var and config path to fix. Covered by `tests/test_research_cjk_and_models.py` (ladder walk + memoization, explicit-model fail-loud, exhaustion message).

- **Bootstrap's closing message promised "Claude will read it automatically on every session", a claim three separate conditions have to make true (#206).** The auto-read is `hooks/load_vault_context.py`'s doing, and it fires only when the SessionStart hook is registered (`install.sh` or the Claude Code plugin), `OBSIDIAN_VAULT_PATH` is set in the process environment (`scripts/setup.sh` writes it into `settings.json`; the hook does not read the `.env` fallback), and the session starts inside the vault. A user who runs `bootstrap_vault.py` from a bare clone - the script's own documented usage - satisfies none of these and gets sessions that never load the manual, with nothing saying why. The same claim-vs-wiring gap as the write-time hook docs fixed for #171. The message now leads with the thing the user must ensure (the agent reads `_CLAUDE.md` before working in the vault) and names the wiring that automates it, instead of promising the automation unconditionally.

- **A freshly bootstrapped default vault opened with a folder map that lied twice and 2 persistent out-of-the-box freshness errors (#205).** Three stacked defects, all found on a first bootstrap + first lint of an untouched vault. (1) `_CLAUDE.md`'s folder map listed a `Jobs/<job>.md` row per `--jobs` entry (`Jobs/Work.md` by default) while bootstrap never writes such a file - a phantom note in the exact file the agent is told is ground truth. The rows are removed; the `Jobs/` folder row already documents the folder. (2) The map was built from the preset's base folder list, but bootstrap extends that list before creating folders (the default preset's `Side Biz/Deals/*` tree), so real folders were invisible to the map. Both `claude_md_personal` and `claude_md_assistant` now build the map from the folders actually created. (3) The Kanban plugin footer `%% kanban:settings` that `render_kanban` writes on every seeded board parses as a typed pointer, and no `.freshness.json` maps it, so `freshness_lint.py` reported FRESH-3 twice on a vault nobody had touched. Fixed in the linter rather than by shipping a mapping, because the footer is not a pointer at all: `%%...%%` is Obsidian comment syntax, invisible in rendered markdown, and the lint already treats same-line HTML comments and inline code as quotation-grade non-content - Obsidian comments now get the same rule via a per-line visibility scan: every `%%` toggles comment state, delimiters quoted in backticks or inside code fences stay literal, visible text sharing a line with a delimiter is preserved and checked (an earlier cut of this change dropped whole delimiter lines, which would have silently muted real claims - caught in pre-submission review by two independent reviewers), fence markers inside a comment are inert so an odd fence count cannot leak past the closing `%%`, and an unclosed comment hides the rest of the note exactly as Obsidian renders it. This extends the showroom rule (stress-test fix 9/24) to the freshness lint: a fresh vault must pass its own inspections, all of them. Covered by `tests/test_showroom.py::test_fresh_bootstrap_passes_freshness_lint`, `::test_folder_map_matches_what_bootstrap_created` (two-directional: every listed path exists AND every contracted folder is listed, in personal and assistant mode), and `tests/test_freshness_lint.py::test_obsidian_comments_are_invisible_not_content` plus the delimiter-line and quoted-syntax tests beside it; each verified to fail when its fix is reverted.

- **The MCP server counted example wikilinks inside code as real links, so `obsidian_vault_health` reported fenced syntax demos as wanted notes (#203).** #82 taught the CLI `vault_health.py` to strip fenced blocks and inline code before counting links in the wanted-notes check, and #93 extended that stripping to the stored links feeding orphan detection; the MCP connector's `vault_ops.py` kept its raw regex through both - the same "fixed in one path, not the other" shape as #160. Every bootstrapped vault ships the pattern in-tree: `_CLAUDE.md`'s kanban convention demonstrates `[[Related Project]] [[Person]]` inside a fence, the log pointer `/obsidian-init` writes carries its entry template in one, and syntax demos like `` `[[wikilinks]]` `` rang as unresolved links in `obsidian_validate_note` - persistent false positives, re-reported on every run until someone writes a note that exists only as an example. `_wikilinks()` now strips code before extraction, which fixes all three consumers at once (`vault_health`, `backlinks`, `validate`). Scope is deliberately the CLI's exact stripping - triple-backtick fences and single-backtick spans; tilde fences and multi-backtick spans are a separate, pre-existing gap shared with the CLI. Covered by `tests/test_smoke.py::test_mcp_vault_health_ignores_code_example_links`, which also asserts a real link to an unwritten note is still counted; verified to fail when the fix is reverted.

- **Docs claimed the write-time hook ships in every platform build; it ships in `claude-code` only (#171, measured by the codex-cli platform owner).** `SKILL.md` said the hook script lands in `dist/<platform>/hooks/` "for all platform builds", and the AI-first rules table said substitution Unicode is "caught by `validate-ai-first.sh` check 5" - both read as enforced on builds that contain no such file and no host wiring. `SKILL.md` now states the hook is claude-code-only and points other platforms at the source repo's `hooks/validate-ai-first.hook.yaml` + `.sh` for manual wiring; the rules table scopes check 5 to Claude Code; the codex-cli `INSTALL.md` gains a "Write-time validation hook (not included)" section. The stale "warning on stderr" behavior description in `SKILL.md` was also updated to the JSON (`systemMessage`/`additionalContext`) contract introduced by #202.

- **`validate-ai-first` still enforced nothing useful in the VS Code Claude Code extension after it was wired into `hooks.json` (follow-up to #171, found by @born-in-autumn).** Stacked gaps: (1) the extension writes with `tool_name=create_file` and `tool_input.filePath` (camelCase) while the stock matcher only listed `Write|Edit|MultiEdit|NotebookEdit` and the script only read `file_path`, so the hook exited 0 with no warning; (2) after matcher/`filePath` were fixed, the hook did warn in the extension hook log (`NonBlockingError` / later Success + JSON) but the chat UI and the model still saw nothing - plain stderr + exit 1 is log-only, and `additionalContext` alone does not surface to the user. Matcher now includes `create_file`; path extraction accepts `filePath`; warnings exit 0 with JSON that carries `systemMessage` (user-visible per Claude Code hooks docs), plus `decision`/`reason` and `hookSpecificOutput.additionalContext` for the model path (stderr still mirrored for logs). Covered by `tests/test_smoke.py::test_validate_hook_accepts_vscode_extension_payload` and a matcher assertion in `tests/test_plugin_manifest.py`.

- **`/podcast` downloaded a full transcript, could not read it, and quietly summarized the show notes instead.** `_parse_json_transcript` accepted only the Podcast Index spelling of the per-segment string, `segments[].body`. Whisper-derived exports spell the same field `segments[].text`, and several hosts ship those: flightcast, Deepgram, AssemblyAI. Found on a flightcast-hosted show where the `<podcast:transcript>` tag resolved, the JSON downloaded, and 610 usable segments (~43,000 words) were then discarded because the key was named `text`. The parser returned `None`, the caller fell through past Whisper (no `OPENAI_API_KEY`) to the show-notes path, and the note came out thin with an empty Notable Quotes section. Nothing in the output said a complete transcript had been in hand: the stderr line named the schema as unsupported, which reads as a limitation rather than a near miss, and `transcript-source` in the saved note recorded `show-notes` truthfully. Both spellings are now tried in turn, `body` first so existing feeds are untouched. The two stderr messages no longer claim `segments[].body` is the only supported shape, since that is no longer true. Covered by `tests/test_podcast_transcript_schema.py`, including the empty-string case (a `segments[].text` array of blanks must still fall through rather than return an empty transcript); verified to fail when the fix is reverted.

- **`/research-deep` labelled a bounded excerpt as "full-page text" and truncated it silently (part of #194, reported by @feariangod).** `web_reader.read()` cuts each extracted page at `MAX_EXTRACT_CHARS` (8,000), which is the right call - extraction is paid and the synthesis prompt has finite context - but the cut left no trace, and the block was then handed to the synthesizer under the heading "Extracted source content (full-page text)" with each page titled "Full text:". So on any page longer than the cap the model was told it had read the whole thing while holding the opening section, which makes a missing topic look like a claim the source does not make rather than a section that was never sent. Truncated pages now carry an inline `[TRUNCATED: ...]` marker naming both lengths and stating explicitly that absence below is not evidence of absence in the source; a page under the cap is passed through untouched, with no spurious marker. The prompt heading, the per-page title, `web_reader`'s docstring and `commands/research-deep.md` all stop calling it full text and name the cap. Covered by `tests/test_research_sources.py::test_web_reader_caps_urls_and_truncates`, extended to assert the payload is still capped, that the marker is present, and that a short page does not gain one. This is the narrow, verifiable half of #194; the proposed `capture_scope`/`content_hash` raw-source schema and strict-local ingest mode remain open for discussion on that issue.

- **The bounded-recall hook shipped permanently inert on CJK vaults, and silently (#192, reported by @hamidasiblog).** #159 made search itself CJK-aware, but `hooks/obsidian-recall.py` kept a private copy of the old tokenizer for its abstention gate - `{t for t in re.split(r"\W+", s.lower()) if len(t) > 3}` - and that copy was not part of the fix. Python's `\w` is Unicode-aware, so `\W+` never splits a Chinese/Japanese/Korean run: a CJK prompt collapsed into a single token equal to the whole phrase, which then had to appear verbatim in the top hit's title and snippet to satisfy `MIN_TERM_OVERLAP`. It essentially never did. The retrieval was fine throughout; only the gate was stale, so the hook returned relevant notes and then threw them away. The failure mode is worse than a visible break, because abstention is a normal outcome and the log line (`{"abstained": true, "reason": "low confidence"}`) is indistinguishable from a genuinely weak match. Reporter measured it on 30 frozen cases: lexical search put a gold note in the top 4 for 10 cases and the gate discarded 7 of them, including 5 of 5 on the two hand-written Japanese sets - every case the search got right. The gate now delegates to `vault_ops._query_terms`, the same tokenizer search uses, rather than keeping a second definition that has to be remembered separately. Latin behavior shifts slightly and for the better: `_query_terms` drops stopwords, so an overlap of "there"/"would"/"which" no longer counts as a meaningful match the way a bare `len(t) > 3` did. Covered by `tests/test_smoke.py::test_recall_hook_abstention_gate_is_cjk_aware`, which asserts both directions - a relevant Japanese prompt injects, an unrelated one still abstains, so the fix cannot degrade into a gate that always passes - and verified to fail when the change is reverted.

- **`/research-deep` saved an empty synthesis under a real title, and reported success.** Phase 4 called `sonar-reasoning-pro` with `max_tokens=3500`. On a reasoning model that number is the whole allowance, the reasoning is spent first, and the tokens it costs are not itemized in `completion_tokens` - so a Phase 4 prompt around 4k tokens (it carries the findings plus any Tavily full-text) came back with `completion_tokens: 0`, no content, and `finish_reason: "stop"`. A success by every field a caller inspects. `lib/perplexity.py` then returned `""`, `research_deep.py` wrote it into the note body, and the `except` branch that exists precisely to write a labelled "Synthesis unavailable" fallback never fired, because nothing raised. Measured with a ladder on one fixed prompt rather than reasoned about: 3500, 4000, 4500 and 5000 all returned zero visible tokens; 8000 answered but hit `finish_reason: "length"` in 2 of 3 runs, arriving with 2 and 4 of the 6 required sections; 16000 completed 3 of 3 with all six. Now 16000. The ceiling is close to free, since billing is per token actually emitted (~2,300 here, ~$0.032/run), so it costs nothing until it is used. Separately, `lib/perplexity.py` now raises on an empty completion instead of returning it, with the budget named in the message - every call site already degrades gracefully on an exception, and an empty note under a real title is worse than a visible failure. Non-reasoning calls (`sonar-pro`, used by Phase 2, Phase 3 and `/research`) were checked and do not have this behaviour: they truncate at the cap in the ordinary way. Covered by `tests/test_perplexity_empty_completion.py`, including the reasoning-only and whitespace-only shapes; verified to fail when the guard is reverted.

- **Every Python-backed Hermes skill named a path that only resolves if you start the agent in the skill directory, which this build's own install doc tells you not to do (#191, reported by @konsone).** The report was about one line: the `obsidian-health-check` blueprint invoked `uv run -m scripts.vault_health`, which needs the skill root as the working directory, while a cron job is armed with `--workdir <vault>`. That is real and is fixed. It is also the smaller half. `adapters/hermes/adapter.sh` rewrote the `SKILL_ROOT` placeholder to `.` for all 15 Python-backed commands, and `.` is the same assumption written differently - so the interactive commands failed too, on an install doc that ends with "point Hermes at your vault as the working directory". Verified rather than reasoned about, by copying the built tree to a fake install root and running each emitted form from a vault: `uv run -m scripts.vault_health` gives `No module named 'scripts'`, `uv run --directory "." scripts/vault_health.py` gives `Failed to spawn: scripts/vault_health.py`, and naming the root outright returns the report. Both forms now resolve through one constant, `HERMES_INSTALL_ROOT`, set to `$HOME/.hermes/skills/obsidian-second-brain` - the path INSTALL.md already tells you to copy into. `$HOME` and not `~`, because commands write the placeholder inside double quotes (`--directory "SKILL_ROOT"`) where a tilde does not expand and uv would receive a literal directory named `~`; that failure was reproduced too, before choosing. `scripts/conformance_report.py` had to learn that a citation rooted at an absolute install path cannot be checked against a tree in `dist/`, so it verifies the tail from `references/` onward. Covered in `tests/test_smoke.py::test_hermes_build_generates_native_skills`: the health blueprint must run `--directory`, and no markdown in the build may ship `--directory "."` or `--directory "~`. Reporter's own deployment carried a `sed` patch hardcoding their skill path to work around this; it should no longer be needed.

- **The scheduled Hermes blueprints skipped the folder-map sweep, so the nightly agent scanned `wiki/` folders on vaults that have none (#190, reported by @konsone).** Every interactive command resolves its target folder through `references/folder-map.md`; the four blueprints are hand-written inside `adapters/hermes/adapter.sh` rather than derived from `commands/`, which is how they missed it. On an Obsidian-style vault (`Knowledge/`, `Ideas/`, `People/`) the nightly pass therefore opened with three guaranteed tool failures on `wiki/entities`, `wiki/concepts` and `wiki/decisions`, every night, with no interactive user present to notice - the reporter's logs show Hermes's own curator then trying to patch the skill in place. Phase 2 now resolves all three folders through the folder map (vault `_CLAUDE.md` first, wiki-style default, Obsidian-style alias) and treats a folder that does not exist as a skip rather than an error, and Phase 3 writes its synthesis into the folder resolved in Phase 2. Fixing it surfaced two further drifts from `SKILL.md`, which the adapter comment names as the canonical source for these prompts: the blueprint told the agent to "auto-resolve clear winners" among contradictions, which `SKILL.md` had already changed to flag-only precisely because resolving one rewrites a note unattended, and which the blueprint's own closing "do not fix anything destructive" contradicted; and Phase 5 lacked the `Logs/YYYY-MM-DD.md` branch. Both re-synced. `SKILL.md`'s copy of the nightly prompt had the same hardcoded paths and is fixed with it, so the Claude Code `/schedule` route was affected and is covered by the same change. Covered in `tests/test_smoke.py::test_hermes_build_generates_native_skills`, asserting on the bare imperative (`Scan \`wiki/entities/\``) rather than on the path, since naming `wiki/entities/` as the wiki-style default beside its Obsidian-style alias is correct and expected.

- **Every MCP install broke at once when the `mcp` SDK shipped 2.0.0 (#183, reported by @jackiepan99).** The plugin manifest launched the server with `uv run --with mcp`, which resolves to whatever is newest on PyPI at launch time - so the release that restructured the SDK and dropped `mcp.server.fastmcp` (`FastMCP` now lives at `mcp.server.mcpserver.MCPServer`) turned `server.py`'s import into `ModuleNotFoundError` on every machine, without anything in this repo changing. The failure surfaced in Claude Code only as `Failed to reconnect ... -32000`, which points at the plugin rather than at a dependency the plugin never pinned; two of the installs where this was diagnosed had been silently disconnected for days. The launch command is now pinned to `mcp<2` (last working release: 1.29.0) everywhere it appears - the plugin manifest, `scripts/setup.sh`, `SKILL.md`, `README.md`, and the integration's own README, `server.py` and `live_test.py` docstrings. Pinning is the whole fix; porting to the 2.x API is a separate change that should not be forced by an unattended resolution. Covered by `tests/test_plugin_manifest.py::test_mcp_launch_pins_the_mcp_dependency` (the manifest arg must carry a constraint) and `::test_no_documented_command_reinstalls_the_unpinned_mcp` (no copy of the command anywhere in the tree may drop it again).

- **Three builds shipped purely reactive skills because they never read `trigger-mode` (#181, reported by @konsone).** 7 of the 8 commands that declare the field are `proactive` - `/obsidian-save`, `/obsidian-task`, `/obsidian-person`, `/obsidian-daily`, `/obsidian-capture`, `/obsidian-log`, `/obsidian-decide` - which is what lets an agent offer to save a conversation without being asked. The policy was encoded in `agent-skills` only. The report named `hermes`; the real scope is every adapter that writes its own frontmatter, so `codex-cli` and `pi` had the same gap and lost the signal on all 7. `claude-code`, `gemini-cli` and `opencode` copy the command body verbatim, frontmatter included, so the field travels there and they were never affected - checked per build rather than inferred from a grep. The policy now has one definition, `with_trigger_policy` in `adapters/lib.sh`, called by all four generating adapters instead of living in one and being absent from three. Nothing failed while this was broken: the builds compiled, the skills loaded, and they simply never volunteered. Covered by `tests/test_dispatcher_prose.py::test_generated_descriptions_carry_the_trigger_policy`, which reads the declared mode out of `commands/` and asserts the matching wording reaches every generated build; verified to fail when the fix is reverted.

- **`validate-ai-first.sh` was never wired, so the rule this repo calls non-negotiable enforced nothing on a plugin install (#171, found by @born-in-autumn).** The script has shipped in `hooks/` since it was written, its own header says it "fires as a Claude Code PostToolUse hook after Write/Edit", and `CLAUDE.md` cites it as what enforces the substitution-Unicode ban on vault writes. `hooks/hooks.json` declared only `SessionStart` and `PostCompact`. Nothing ran it. It also had a second silent no-op behind the first: vault resolution read `OBSIDIAN_VAULT_PATH` from the environment only and `exit 0`'d when unset, so even a hand-wired hook did nothing on a plugin-marketplace install, which configures the vault in `~/.config/obsidian-second-brain/.env` and never exports it. That is the same root cause as #160 (MCP server) and #124 (research toolkit), in a third code path that was never swept because the hook was not running to fail. Now wired as `PostToolUse` on `Write|Edit|MultiEdit|NotebookEdit`, with the documented `.env` fallback (environment still wins, `OBSIDIAN_ENV_FILE` overrides). Covered by `tests/test_plugin_manifest.py::test_plugin_hooks_reference_shipped_executable_scripts`, which now asserts the event set includes `PostToolUse` and that it references the script by name.

- **Every build cited the AI-first spec by a path that resolves from exactly one directory, and failed silently everywhere else (#171, reported by @Palo-Alto-AI-Research-Lab).** Skill and command bodies pointed at the spec with an install-root-relative path (`.codex/references/ai-first-rules.md` and its per-platform equivalents). Start the agent in any subdirectory and the read fails - and nothing surfaces, because an unreachable advisory reference does not stop the skill from running, so a note written without the spec is indistinguishable from one written with it. `scripts/conformance_report.py` could not catch this: it asserts the cited file exists inside the build, which was true. It has no concept of where the agent stands when it reads. Every citation now carries a recovery path (search upward) and an instruction to say so before writing if the spec is still unreachable, with the rule summary itself inline as the floor. `agent-skills` was already immune, since it embeds the full spec in every `SKILL.md`; embedding it in the other six would have cost ~6.7MB of context for the same guarantee. The rule summary also gained a step-number parameter so `agent-skills` calls the one definition in `adapters/lib.sh` instead of carrying a seventh copy. Covered by `tests/test_smoke.py::test_relative_reference_citations_are_not_silent` (sweeps all 273 pointer-only files across every build) and an extended assertion in `tests/test_dispatcher_prose.py`.

- **Redacted vault note titles and a verbatim query from a tracked eval doc, and added a CI guard.** `scripts/eval/BASELINE.md` is public, is written while looking at real search output, and had picked up two note filenames and a quoted query from the maintainer's own vault - the second time this has happened in that file. The case files are gitignored, which makes the area feel safe and is exactly why the prose keeps leaking. `tests/test_no_vault_content_in_eval_docs.py` now fails when an eval doc backticks a `.md` filename that does not exist in this repository, or quotes a long string with no `<placeholder>` in it. The rule needs no list of real names, since keeping such a list would be its own leak.

- **The semantic index went stale silently, and nothing anywhere said so.** The index is built on demand and never invalidates itself; the README told users to build it "once". So it drifts behind the vault, and on a real 1,828-note vault it had drifted to covering 1,303 - 29% of notes had no vector at all. That reads as a minor staleness issue and is not: an unindexed note is still reachable by literal word match, so on English queries the lexical arm papers over the gap and the drift is invisible, but on a query written in another language the lexical arm contributes nothing (measured on the multilingual eval set: every hit came from the semantic arm, and the target note's lexical rank was absent or in the hundreds). For those queries an unindexed note is not ranked low, it is unretrievable. Search now warns once per index version when coverage falls more than 5% behind (`OBSIDIAN_INDEX_STALE_WARN_PCT`), reusing the scan it already performs so the check costs a set difference; `/obsidian-health` reports coverage as a `semantic_index` finding, reading note keys out of the (66MB) index as a stream rather than parsing every float; and the README no longer says "once". Covered by `tests/test_index_staleness.py`.

- **Vault health reported accented notes as both wanted AND orphan on macOS (#161, by @kontaktgift).** A wikilink and a filename that differ only in Unicode composition (NFC vs NFD) name the same note, but a plain string compare rejected them - macOS stores filenames decomposed (NFD) while text typed or pasted is usually composed (NFC), so any accented title (German umlauts, Spanish/Portuguese/French diacritics) could be flagged twice, as a wanted note (link "goes nowhere") and an orphan (nothing "links to" it), while the note sat right there. `vault_health.py` now normalizes to NFC at the comparison boundary only (stem, alias, asset and link-source keys), NFC not NFKC so distinct titles stay distinct. Companion fix in the same release: `scripts/link_graph.py` (which imports the same file index and promises identical link rules) now applies the same NFC normalization in its `_norm`, dangling-link, and directory keys, so `/obsidian-visualize` resolves accented titles exactly as `/obsidian-health` does instead of showing the phantom orphan the health check stopped showing. Covered by `tests/test_vault_health_unicode.py` (by @kontaktgift) and `tests/test_smoke.py::test_link_graph_resolves_unicode_composition`.

- **MCP search silently dropped most CJK queries (#159, reported by @SylvesterTee).** `vault_ops.search()` split query terms on `\W+` and then discarded anything `len <= 2` - a filter calibrated for English noise words (`a`, `is`, `of`). But Python's `\w` is Unicode-aware, so it never splits a Chinese/Japanese/Korean phrase, and two characters is the single most common CJK word length (系統, 資料, 会議). The result: a word appearing thousands of times in a vault was invisible to search, while the fallback repeated the same filter and returned nothing. Search now uses a CJK-aware tokenizer that indexes CJK runs as overlapping character bigrams (a lone char stays a unigram) while keeping the English `len > 2` + stopword rule for Latin tokens, so 系統 is findable and a reordered phrase still overlaps. Latin ranking behavior is unchanged. Covered by `tests/test_smoke.py::test_mcp_vault_ops_search_finds_cjk_words`.

- **MCP server ignored `OBSIDIAN_VAULT_PATH` from the config `.env` (#160, reported by @SylvesterTee).** `architecture.md` promises the vault path is read from "the environment or `~/.config/obsidian-second-brain/.env`", but `resolve_vault()` checked only `os.environ` - so a plugin-marketplace install that configured the vault in `.env` (as the docs instruct) got a non-functional MCP server whose error message contradicted the user's own config. This was #124 (`PERPLEXITY_API_KEY` ignored from `.env`) in a different code path; that fix landed in the research toolkit but the MCP server was never swept. `resolve_vault()` now falls back to the config `.env` (parsed with a tiny stdlib reader, since the server runs under `uv run --with mcp` without python-dotenv; path overridable via `OBSIDIAN_ENV_FILE`), with the environment still taking precedence. Covered by `tests/test_smoke.py::test_mcp_vault_ops_resolves_vault_from_env_file`.

### Added

- **Opt-in tag taxonomy audit (#221, taxonomy half - the digit-only/tag-syntax half of the issue is a separate write-time check).** A vault can now declare a canonical tag vocabulary at `_meta/taxonomy.md` - one `##` heading per canonical tag, its synonyms as a `-` list underneath (format and rationale in `references/taxonomy-format.md`). `scripts/vault_health.py` gains `load_taxonomy` (parses the file, empty dict if it does not exist) and `check_taxonomy`, which reports two disjoint findings: `tag_synonym` (warning - a note's tag is a known synonym, fold it to the canonical form) and `tag_not_in_taxonomy` (info - the tag matches nothing in the vocabulary, which is not necessarily wrong). Absence of the file is a true no-op: zero findings, nothing changes for the vaults that have not opted in. `vault_health.py` stays pure-report as it already was for every other check; `/obsidian-health`'s new Taxonomy agent offers the synonym fold per note with confirmation and never touches the taxonomy file or a "not in taxonomy" tag on its own. `_meta/` is now skipped by `vault_health.py`'s note scan, since it holds tool config, not AI-first vault content. Covered by `tests/test_taxonomy_audit.py`.

- **Simplified Chinese trigger phrases for all 46 commands.** Each command now carries natural `triggers_zh` requests written for how a Chinese-speaking user would actually ask, rather than literal translations of the English phrases. Dispatcher builds label the language as `简体中文`, and the generated command reference publishes the same phrases alongside English, Spanish and Portuguese. A docs-generation test requires every published language on every command so future commands cannot silently ship without Chinese routing coverage.

- **`/obsidian-reindex` turns semantic-index maintenance into a first-class command.** It reports coverage before and after the existing incremental build, names how many notes were newly embedded or refreshed, and surfaces cached, excluded, degraded, and dropped notes instead of hiding gaps behind a success message. If Ollama or another configured embedding backend is unavailable, the command stops on the builder's nonzero exit and relays its actionable setup error. The flow updates only `.obsidian-semantic-index.json`; Markdown notes are untouched.

- **AI-First Lint, an Obsidian plugin (`integrations/obsidian-plugin/`).** The Obsidian community plugin directory is the only large, automated, in-app distribution surface in this space, and it accepts plugins and themes only, so it is closed to a CLI skill by exactly one technical fact. This opens it, and it earns the listing rather than merely qualifying for it: the plugin checks a vault against [AI-FIRST.md](AI-FIRST.md) and lists the notes an agent cannot use - missing frontmatter, missing `## For future Claude` preamble, missing `ai-first: true`, and cited sources with no `as of` date - with each result clickable. It is standalone: no CLI, no Python, no network, no shelling out, so someone who has never heard of this project can install it and get value. All rule logic lives in `src/lint.ts` as pure functions with no Obsidian import, tested with plain strings via `node:test` and no extra dependency. Most of those tests are about *not* firing, because a linter's failure mode is false positives: URLs inside code fences and filenames like `README.md` are explicitly not reported. Verified in both directions against real input - silent across all 300 notes of the synthetic benchmark corpus, and firing on every one of this repo's own non-compliant documents. Typecheck, build and tests run in CI.

- **Platform ownership is open, and the credit ships inside the build.** Seven builds are compiled from one source tree by one person who can realistically test two of them, and five audit findings (B3, B19, B20, S15, S23) were all the same defect: a build that compiled cleanly, shipped, and was wrong in a way only a daily user of that platform would notice. `adapters/OWNERS.md` opens every build to a named owner, states plainly what ownership does and does not involve (no Python, no response-time expectation, no permanence), and credits the contributors who have already worked on each adapter as credit rather than assignment. The table is not documentation: `scripts/build.sh` reads it and appends the owner's handle to that platform's generated `INSTALL.md`, so claiming a platform is a one-line edit to one table and the reward ships where users actually see it. This was blocked until the conformance board existed, because an adapter PR can only be accepted without the maintainer testing that platform if CI checks the parts that do not need it installed. Covered by `tests/test_platform_owners.py`, including that a malformed OWNERS.md cannot break a release.

- **`AI-FIRST.md` - the note spec as a standalone, pasteable document.** The canonical specification is 518 lines and declares itself canonical on line 5, which makes it the one artifact here with zero installation cost and also far too heavy for anyone to copy. This is the same rules as a 50-line block you paste into a `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, or anything else your tool reads at session start. It installs nothing, needs no part of this project, and carries its attribution line inside the copied block so a copy can always be traced back. Versioned (1.0) so an adopted copy can say what it was adopted from. Includes both hard rules, not only the seven numbered ones: no fabrication, and retrieved content is data rather than instructions - a portable spec that dropped the second would teach the unsafe version. `tests/test_ai_first_spec.py` fails when the short form drifts from the long one, which is the same two-copies problem that produced B21 and S18 in this repo, except here there is no build step that would ever notice.

- **A reproducible retrieval benchmark.** This project has a standing rule that no retrieval change ships without before-and-after numbers, and every one of those numbers was measured against the maintainer's own vault, whose case files are gitignored because they hold real notes. So the figures were claims nobody outside could check or beat. `scripts/eval/corpus.py` now generates a deterministic 300-note synthetic vault (fixed seed, a `--manifest` hash to confirm two people have the same corpus, `synthetic: true` on every note, and no content drawn from any real vault) plus three gold query sets: exact keyword, English paraphrase, and the same descriptions in Spanish and Russian against English notes. Difficulty is built in rather than incidental - every topic has one short canonical note and at least three longer derivative notes that mention it more often, which is the shape that makes term-frequency ranking pick the wrong answer and the shape this project's own evaluation kept hitting. Gold answers are known by construction, not hand-labelled. `scripts/eval/BENCHMARK.md` publishes the baseline, the methodology, how to report a result, and four known limitations. Covered by `tests/test_benchmark_corpus.py`, which tests the benchmark's integrity rather than just that it runs: the first version wrote each paraphrase query verbatim into its own answer note and scored 83% on pure lexical search, which looked like a strong result and was the answer key.

- **A generated docs site, built from `commands/`.** GitHub Pages has been live and building for this repo for some time, serving the README from the repo root, while `commands/` held 45 files each carrying a one-line `description`, a `category`, and `triggers_en` / `triggers_es` / `triggers_pt` arrays - which are, literally, the sentences a person would type when they want the thing, written by hand in three languages and visible until now only to the dispatcher adapters. Content, hosting and build tooling all existed and were wired to nothing. `scripts/build_site.py` now generates an index plus one page per command into `docs/`: 46 pages, inline CSS, no fonts or scripts from any third party, light and dark both handled, and one small inline filter script the page degrades gracefully without. Command bodies are deliberately not published - they are instructions addressed to an agent, not prose a reader wants. Generated rather than hand-written for the same reason the adapters are, and `--check` fails CI when the committed tree falls behind the generator, so a page cannot end up contradicting the command it documents. Covered by `tests/test_build_site.py`.

- **A one-time star prompt, shown after the tool has actually done something for you.** The README asks every stranger who lands on the repo the same way. This asks in the terminal, once per machine ever, and only after a moment the reader can see: a bootstrap that just created their vault, or a health check that came back with zero issues. It quotes the number they are already looking at rather than making a generic pitch. Suppressed by `OBSIDIAN_NO_STAR_PROMPT=1` and by `CI`, never printed on a `--json` path, and never shown when the health check found problems, because asking for a favour in the same breath as reporting someone's mess has the tone backwards. The marker file lives in the config directory, and if it cannot be written the prompt is skipped rather than shown, since a prompt that cannot record itself would repeat forever. Covered by `tests/test_star_prompt.py`, which tests both directions - every suppression path, and that it still fires. The first implementation gated on `stdout.isatty()`, which in a project whose scripts are normally run by an agent into a pipe would have meant it never appeared for a single user; there is a regression test for exactly that.

- **`scripts/eval/diagnose.py` - why a retrieval case missed, not just that it did.** `retrieval_eval.py` reports recall and MRR; it cannot say whether a miss is a coverage failure (the note has no vector), a pool failure (ranked below the fusion depth in both arms), or an ordering failure (in the pool, ranked out) - and only the last is reachable by any weighting change. `--gap` additionally reports how much cosine a fix would have to supply to lift the note past the rank-10 cutoff, which is the number that decides whether a weight could ever work: on the multilingual set four of six misses need more lift than the entire rank-1-to-rank-10 band is wide. Four separate weighting experiments had already been run against those cases before this was measured. Output is rank numbers only unless `--show-paths` is passed, so a run against a private vault is safe to share. Covered by `tests/test_eval_diagnose.py`.

- **Typed edges + graph linting - the graph-engineering layer.** A plain `[[wikilink]]` says two notes are related but not *how*; notes can now record *typed* relationships in a `relations:` frontmatter block with a controlled vocabulary (`supersedes`/`superseded_by`, `depends_on`/`required_by`, `caused`/`caused_by`, `decided_by`/`decides`, `relates_to`, `contradicts`), turning a pile of links into a traversable, interpretable graph. `scripts/link_graph.py` parses the block (inline-list and block-list forms, plus the legacy top-level `supersedes:` scalar as an equivalent alias) and exposes it as a `typed_edges` overlay in its JSON - kept separate from degree, since the underlying frontmatter link is already counted, so orphan/hub math is unchanged. A new `--lint` mode validates the layer and returns severity-ranked findings: contradiction cycles (A and B claim the same asymmetric type about each other) as critical; unknown types, dangling targets, and self-edges as warnings; missing inverse edges as info. `/obsidian-health` gains a typed-edge lint agent that folds these into its severity groups; `/obsidian-visualize` labels canvas edges with their relation type and summarizes the overlay (counts by type, longest reasoning chains). Documented as Rule 6 § Typed edges in `references/ai-first-rules.md` (with an ADR-schema cross-reference). Covered by `tests/test_smoke.py::test_link_graph_typed_edges_and_lint`. Implements the techniques from the "graph engineering" writeup (typed edges, entity resolution via wikilinks, graph linting) while staying plain-markdown, no-database, no-lock-in - the overlay is reconstructed on demand from frontmatter, never stored.

## [0.14.0] - 2026-07-18 - The Harvest

### Added

- **Bounded vault recall on every prompt - opt-in `UserPromptSubmit` hook (fork gold round 2, P1, the deepest idea in the sweep).** `hooks/obsidian-recall.py` injects a small brief of the most relevant vault notes into each prompt's context: hard-bounded (max 4 notes, ~900 chars), **abstaining** - a low-confidence match injects nothing, because silence beats noise - **fail-closed** (any error exits silently; recall must never break a prompt), and **observable** (every inject/abstain decision appends a JSONL line to `<vault>/.claude-runs/recall-YYYY-MM-DD.jsonl`). Reuses the shipped `vault_ops.search`, so recall benefits from the same freshness and supersession reranking as the MCP. Ships inert on the bg-agent's double-gate trust model: nothing runs until both `OBSIDIAN_VAULT_PATH` and `OBSIDIAN_RECALL_ENABLED=1` are set and the hook is registered (`hooks/recall.hook.example.json`). Pattern from the local-first memory fork's bounded-recall design (see `FORK_INSIGHTS.md` round 2) - deliberately WITHOUT its per-prompt index rebuild (O(vault) per prompt latency). Covered by `tests/test_smoke.py::test_recall_hook_contract` (gate, bounded injection, abstention, logging).

- **Portuguese (pt-BR) trigger phrases for all 45 commands.** Ported from the OKF-first fork's translations (with its fork-specific "bundle" vocabulary normalized to "vault") plus a new line for `/obsidian-brainstorm`; the build's multilingual trigger schema picks the new language up automatically, so every non-Claude dispatcher now carries a Portuguese section with zero adapter changes. Translation base by @renatofaria-ia.

- **New thinking tool: `/obsidian-brainstorm` - the skill's first stateful, multi-turn command (fork gold round 2, P1).** Every other thinking tool is a single-shot analytical pass; this one interviews the user one question per turn (multiple-choice preferred) across six categories - problem framing, constraint surfacing, trade-off forcing, scope bounding, prior-decision linking, anti-goals - and keeps going until an internal 6-item convergence checklist reaches at least 5 of 6 ("just write it" is honored, with skipped items recorded as open questions instead of silently guessed). It grounds its questions in the vault first (related decisions, contradictions, and open questions become interview material), then presents 2-3 named approaches with exactly one (Recommended), and writes a `type: brainstorm` note - conclusions and reasoning, never the transcript - propagating to the daily note and related project, and offering `/obsidian-graduate` or `/obsidian-decide` when the outcome is project- or ADR-shaped. New `type: brainstorm` schema in `references/ai-first-rules.md`. Command count: 45 (thinking 14); all doc surfaces updated. De-coupled and translated from the brainstorm fork's v2 design (see `FORK_INSIGHTS.md` round 2).

- **Unattended writes get a sensitive-content gate, and the write-time hook detects secrets (fork gold round 2, P1).** Two layers, from the local-first memory fork's capture-staging pattern (see `FORK_INSIGHTS.md` round 2). (1) The PostCompact bg-agent's prompt now routes sensitive material (credentials, health, personal finances, intimate/relationship matters, legal disputes) to a dated staging note in the vault's inbox folder as a topic-only pointer instead of propagating it into entity/project/concept notes - and raw secret strings are never written anywhere, staging included. (2) `validate-ai-first.sh` gains check 6: high-precision secret detection on every vault write (private-key blocks, AWS/Google/GitHub/Slack/sk- key shapes, quoted password assignments) with a pointed warning to keep secrets in `.env` or a password manager and reference them by name. Precision over recall by design - prose about passwords is not a finding. Covered by `tests/test_smoke.py::test_validate_hook_flags_secrets`.

- **Search honors the `supersedes:` reverse edge, and the pure-lexical path finally gets the freshness rerank (fork gold round 2, P1).** When ADR A declares `supersedes: "[[B]]"`, B now steps back in search results even if B's own `status:` was never updated - the exact "vault forgot to update the old note" failure the freshness policy warns about. Checked within the candidate set only, so it stays O(results). Also fixes a pre-existing inconsistency found on the way: the freshness/status rerank ran only on the semantically-fused path, so keyless (pure-lexical) installs never got the status fade the code comment promised for the lexical arm - the fallback path now gets the same rerank. Before/after eval on a real 1,761-note vault: byte-identical metrics in both lexical and default modes (no regression); the reverse edge is covered by `tests/test_smoke.py::test_mcp_search_supersedes_reverse_edge`. Idea from the local-first memory fork (see `FORK_INSIGHTS.md` round 2).

- **The retrieval eval can now benchmark any external engine (`--mode external`, fork gold round 2, P1).** Point `RETRIEVAL_EVAL_EXTERNAL_CMD` at a command that takes the query as its final argument and prints ranked note paths (a JSON array of paths or `{"path": ...}` objects, or one path per line), and `retrieval_eval.py` scores it on the exact same cases and metrics as the shipped search - so a TypeAgent structured-RAG runner, a vector DB, or any retrieval experiment competes head-to-head without being imported or vendored. Missing env var fails with a clear message; a failing engine scores its queries as misses rather than aborting the run. Pattern from the structured-rag eval fork (see `FORK_INSIGHTS.md` round 2). Covered by `tests/test_smoke.py::test_retrieval_eval_external_mode`.

- **`scripts/update-vault-integration.sh` - a guarded updater for copied dist builds (fork gold round 2, P1).** The plugin-marketplace and symlink installs update themselves, but a dist tree copied into a vault (Codex / OpenCode / Antigravity / Gemini / Pi) had no update story beyond re-doing the install by hand. The updater is safe by construction: verifies the clone is clean and the remote is recognizable, pulls fast-forward-only (anything else aborts untouched), rebuilds the detected platform (auto-detected from what is installed, or `--platform`), gates on the smoke tests, backs the vault's integration files up to `~/.cache/obsidian-second-brain/backups/<platform>-<ts>.tar.gz`, installs, and rolls the backup back on any failure. `--dry-run` prints the plan. Pattern from the updater fork (see `FORK_INSIGHTS.md` round 2), generalized: no personal defaults, every platform, cache-dir backups. Verified end-to-end against a live scratch install; argument/platform guards fenced in `tests/test_smoke.py`.

- **`/research-deep` reads its top sources in full when `TAVILY_API_KEY` is set (fork gold round 2, P1).** Synthesis previously saw only citation snippets; a new Phase 3.5 fetches the top cited pages as full text via the Tavily Extract API (hard cap 3 pages, 8k chars each - extraction is paid and synthesis context is finite) and injects them into the synthesis prompt so it verifies and deepens findings against what the pages actually say. Skipped silently without the key; extraction failures degrade to snippet-only, never fatal. Batches are recorded in the usage ledger. Pattern from the web-reader fork (see `FORK_INSIGHTS.md` round 2). Covered by `tests/test_research_sources.py` (keyless no-op, URL dedup + cap + truncation, total-failure degradation).

- **Fork gold, round 2 - four upgrades mined from the 2026-07-18 sweep of all 408 forks** (see `FORK_INSIGHTS.md` round 2; each idea credited to the fork that built it there):
  - **Brave Search as an optional research source.** When `BRAVE_API_KEY` is set, Brave joins the `/research` free-mode pool ($5/1,000 requests with $5 free monthly credits as of 2026-07 - Brave dropped its free tier); without it the pool stays fully key-less. Same plain-requests + shared-cache shape as the Tavily source; the key travels in the `X-Subscription-Token` header.
  - **The usage ledger now covers Perplexity, and can never break a paid call.** `usage.log_call` previously logged only Grok calls and would raise on an unwritable ledger path - failing the research call it was observing. It is now fail-soft by contract (warns on stderr, never raises), and every Perplexity call logs tokens plus an estimated cost (sonar/sonar-pro/sonar-deep-research rates as of 2026-07; unknown models log tokens with cost 0.0 rather than inventing a price). `/research` and `/research-deep` label their entries so per-command spend is auditable.
  - **`/youtube` summarizes via Gemini when `GEMINI_API_KEY` is set, with automatic Grok fallback.** New `lib/gemini.py` mirrors `grok.call`'s return shape (drop-in swap), retries with backoff, logs to the usage ledger, and sends the key in the `x-goog-api-key` header - never in the URL query string, so it cannot leak into access logs. `gemini-2.5-flash` default (generous free tier); no Gemini key means exactly the old Grok-only behavior.
  - **The health check no longer re-reports links echoed by logs and old reports.** Activity logs and prior health reports quote every broken link they mention without owning it, so the wanted-notes scan counted each finding once per echo. Notes matching `_CLAUDE.md`, `log.md`, or `Vault Health*` are now excluded from the outgoing-link audit by default (they still resolve as link targets and get every other check), and `.vault-config.json` gains an `exclude-link-scan` glob list for user extensions. Covered by `tests/test_user_excludes.py`.

### Deprecated

- **The `codex-cli` and `opencode` per-platform builds are deprecated in favor of the unified `agent-skills` build (0.13.0).** The `codex-cli` build emits into the same `.agents/skills/` layout the unified build covers, and OpenCode natively reads `.agents/skills/` directly (verified live: all 44 skills load from the unified tree with zero validation warnings), so both per-platform builds are redundant now that one spec-compliant tree serves Codex CLI, OpenCode, and Google Antigravity together and installs via `npx skills`. Their generated `INSTALL.md` now carries a deprecation banner pointing at `dist/agent-skills/INSTALL.md`; the builds still work and will be removed in a future release. `claude-code`, `gemini-cli`, `hermes`, and `pi` are unaffected.

### Fixed

- **`architecture.md` still described the pre-agent-skills adapter set.** The adapter-pattern section said "the other five adapters (Codex CLI, Gemini CLI, OpenCode, Hermes, Pi) emit a dispatcher file ... with an auto-generated routing table" - which omitted `agent-skills` and misdescribed `codex-cli` and `hermes`, both of which emit native skills, not a routing-table dispatcher. Corrected the adapter description, the "command sets" count, and the repo-tree listing to include `agent-skills`. (`CLAUDE.md` was already updated upstream.)

### Fixed

- **Full-repo hygiene sweep: privacy, staleness, and SEO/AEO surfaces (three parallel audits over all 228 tracked files).** Privacy: eight leaks that survived the 2026-07-11 scrub are gone - employer/internal names in example notes (SKILL.md timeline facts, `/obsidian-export` and `/obsidian-visualize` sample output) replaced with the sample-vault's fictional universe, a family member's name removed from a shipped docstring, a real project name removed from a test, the private-folder convention in `references/claude-md-template.md` genericized (`Private/`/`Journal/`; the health-check skip-set keeps the old names for backward compatibility), and a shipped note template no longer hardcodes the maintainer's name. Staleness: README's "what's new" banner now features the current release (was one behind, with a 134-test claim vs 191 actual), the broken `#44-commands` anchor fixed, cross-platform count corrected to 44, `/youtube` docs now say Gemini-first with Grok fallback everywhere (four spots), the usage ledger described as covering Grok+Perplexity+Gemini (was "Grok calls"), `ECOSYSTEM.md` and llms.txt's FAQ region updated to the seven-platform story, and llms.txt's key-less FAQ counts corrected (37 non-research commands, one calendar command with four modes). SEO/AEO: `CITATION.cff`'s abstract was four releases frozen ("34-command, 4 platforms") and now describes the current skill; JSON-LD gained `softwareRequirements`, `dateModified`, Windows in `operatingSystem`, current version + release notes, and a seventh FAQ ("How do I update it?"); llms.txt teaches the current install story (plugin marketplace + agent-skills build + the guarded updater) instead of the deprecated clone-and-copy path, and its release history includes v0.13.0. GitHub About updated to 45 commands + Antigravity.


## [0.13.0] - 2026-07-18 - The Open Standard

### Security

- **Link triage can no longer write outside the vault (stress-test round 2).** `triage_links.py` built a new stub's path straight from wikilink text, and the wikilink regex allows `/`, `.`, and `..`. A `CREATE` verdict on a crafted or hallucinated `[[../../escaped/x]]` wrote a file above the vault root, `[[/abs/path/x]]` wrote at an absolute path, and `[[/unwritable/x]]` raised an unhandled `OSError` that aborted the whole batch. Since the verdict comes from an LLM reading attacker-influenceable vault text, this was a real containment hole. The stub path is now resolved and required to stay inside `wiki/stubs/`; anything that escapes is skipped and reported, never written and never fatal. Covered by `tests/test_note_safety.py` (parent-traversal refused, absolute-path refused, legitimate stubs still created).

### Fixed

- **Every discoverability surface now tells the same seven-platform story, and the SEO layer is caught up two releases.** Adding the `agent-skills` build (Antigravity) left the surfaces split between "six platforms" and "seven builds", and the SEO layer had drifted much further: `_config.yml` and the JSON-LD (`_includes/head_custom.html`) still described a four-platform, 43-command, v0.10.0 project - no Hermes, no Pi, no Antigravity, two releases behind. Standardized on seven platforms (Claude Code, Codex CLI, Gemini CLI, OpenCode, Antigravity, Hermes, Pi) across `llms.txt` (intro, platform list, build line, plus release history entries for v0.11.0 "The Retriever", v0.11.1 "Pi Coding Agent", and v0.12.0 "The Stress Test"), the README banner alt text, `architecture.md`, `CLAUDE.md` (adapter roster + a rewritten adapter-pattern paragraph that had described only the original four adapters), `_config.yml`, and the JSON-LD (44 commands, v0.12.0 + release notes, seven-platform description/featureList/FAQ, Antigravity/Hermes/Pi alternateNames and keywords). The README banner (`media/banner.png`) was also regenerated: its logo lineup now includes Antigravity alongside the other six platforms (a reference-image edit of the original sketchnote art, same style and composition).

- **Corrected stale command counts and calendar platform coverage in the docs (#89).** `CONTRIBUTING.md` (two spots) and `examples/README.md` still said "45 commands" when the count is 44, and `architecture.md` claimed `/obsidian-calendar` ships on "Claude Code and Pi only" with a four-entry exclude list - but Pi (and every other non-Claude build) excludes it, so it is Claude Code only, and the real exclude list is six entries. Picks up the fix from @cyburke's closed PR #89 and extends it to the spots that had drifted since. Docs only.

- **`vault_stats.py` now honors `OBSIDIAN_VAULT_PATH` like every other script.** The stats script was the one holdout still reading the legacy `OBSIDIAN_VAULT` env var as the default for `--path`, so users who set `OBSIDIAN_VAULT_PATH` per `.env.example` and the docs got no default and hit "--path is required". It now reads `OBSIDIAN_VAULT_PATH` first and falls back to `OBSIDIAN_VAULT` for backward compatibility; the help text and error message name the new variable.

- **PostCompact bg-agent no longer dies silently on large summaries (Windows).** The hook loaded the full prompt into a shell variable and passed it to `claude -p "$PROMPT"` as a single argv element. On Git Bash for Windows that hits the ~32K `CreateProcess` command-line limit ("Argument list too long", exit 126), and because the spawn runs in a detached subshell whose exit code is never read, the hook still reported success - no propagation, no error. Real compaction summaries reach 24K+ chars, so the headroom was already thin and shrinks with every prompt addition. Fix: feed the prompt to `claude -p` via stdin (no argv size limit) and delete the temp file after the subprocess exits instead of before spawn; behavior is otherwise identical. Thanks to @sad85520 (#129). Covered by `tests/test_bg_agent_hook.py` (prompt must arrive on stdin, never as an argv element).

- **The Hermes install story now matches how Hermes actually works (#134).** Verified against the official Hermes docs and a live Hermes CLI, four claims in the Hermes build were wrong. (1) `INSTALL.md` told users to copy the scheduled agents into `~/.hermes/optional-skills/` - a directory Hermes never reads; they now go into `~/.hermes/skills/` like every other skill. (2) `HOOKS.md` claimed "a Hermes blueprint arms as soon as its skill is loaded" - the opposite of Hermes's contract ("Blueprints never schedule anything silently"); following the old docs left zero jobs armed with no error. Both docs and the blueprint SKILL.md wrapper now teach explicit arming: `hermes cron create "<schedule>" "<prompt>" --skill <name> --workdir <vault>` (verified live: creates and runs the jobs), or accepting the suggested job from `/suggestions` after a registry `hermes skills install`. (3) The lifecycle hook config was aimed at a nonexistent `cli-config.yaml`; hooks are declared under `hooks:` in `~/.hermes/config.yaml`, and `hooks/hermes-hooks.cli-config.example.yaml` is renamed to `hermes-hooks.config.example.yaml` accordingly. (4) The `on_session_end` hook's default headless command `hermes run --quiet` does not exist and the prompt was piped on stdin, so the opt-in consolidation silently did nothing; the default is now `hermes -z` (documented one-shot mode) with the prompt passed as the final argument, closing the "one unverified seam" from #79 Phase 2. The smoke test now asserts the docs teach `hermes cron create` and never mention `~/.hermes/optional-skills` or auto-arming. Thanks to @Litash.

- **Note rewrites are atomic now - an interrupted write can no longer wipe a note (stress-test round 2).** `note_io.write_exact` did `path.write_bytes(...)`, which truncates the file to zero and then streams the new bytes in place. A Ctrl-C, a crash, a sleep, or a full disk between those two steps left the note truncated or empty with no backup - in the one primitive both in-place rewriters (`heal_links`, `triage_links`) depend on, in a tool whose headline promise is note safety. `write_exact` now writes a sibling temp file, flushes it, and `os.replace`s it over the target (a same-filesystem rename, atomic on POSIX and Windows); the original is untouched until that final swap, and an interrupted write cleans up its temp and leaves the note exactly as it was. Permission bits are carried over so a rewrite never quietly changes a note's mode. This is a second-pass finding: v0.12.0's "The Stress Test" hardened the encoding, BOM, symlink, and slug paths but left the write itself non-atomic. Covered by `tests/test_note_safety.py` (byte-exact round-trip with no temp litter, original preserved when the swap fails, mode preserved).

- **Slash commands run under the plugin install now, not just from the maintainer's clone (stress-test round 2).** Six research commands (`/research`, `/research-deep`, `/x-pulse`, `/x-read`, `/youtube`, `/podcast`) told the model to run their script "from the repo root (`~/Projects/personal/obsidian-second-brain/`)", and eight more (`/notebooklm`, `/obsidian-init`, `/obsidian-health`, `/obsidian-architect`, `/obsidian-export`, `/obsidian-visualize`, `/obsidian-retrieval-eval`, `/obsidian-decide`) invoked a bundled script by bare `scripts/...` path. Under the marketplace plugin install a command runs from the user's vault, that clone path does not exist, and `CLAUDE_PLUGIN_ROOT` is not exported to the Bash a command later runs - so those commands failed or degraded on first use, including `/obsidian-init`, the command the README tells a new user to run first. Fix: the SessionStart hook (`load_vault_context.py`) now always publishes the absolute **Skill root** into context (from `CLAUDE_PLUGIN_ROOT` when set, else the hook's own location, so it is correct in every install mode), and all 14 command bodies now run bundled scripts with `uv run --directory "<skill root>" ...`, which needs no `cd` and no assumed checkout. Fenced by `tests/test_install_portability.py` (no command may hardcode the personal clone path; every bundled-script invocation must anchor to the published skill root; the hook must emit it).

- **The skill install now registers the session-context hook, so it works for everyone, not just the plugin (stress-test round 2).** The portability fix above routes every command through the skill root the SessionStart hook publishes. The plugin install wires that hook up via its manifest, but the classic/skill installer (`install.sh`) only linked the commands and the skill, never the hook, so a stranger installing as a skill had no way to get the skill root published and those same 14 commands broke there. `install.sh` now runs `scripts/setup_settings_hook.py`, which idempotently adds (or path-refreshes) the `load_vault_context` SessionStart hook in `~/.claude/settings.json` and never touches unrelated settings. Both install paths now behave identically. The README also spells out the difference the plugin surfaces: plugin commands are namespaced (`/obsidian-second-brain:<name>`, e.g. `/obsidian-second-brain:obsidian-init`), while the classic install keeps them bare (`/obsidian-init`). Covered by `tests/test_setup_settings_hook.py` (add, idempotent re-run, path refresh, unrelated settings preserved).

### Added

- **Tavily as an optional extra source for `/research` free mode (#97).** When `TAVILY_API_KEY` is set, Tavily joins the free-mode aggregation pool as an additional web source; without the key it is skipped silently, so the pool stays fully key-less by default. Implemented with plain `requests` against the REST API (Bearer auth; the key never travels in the request body) using the shared session, disk cache, and `Result` mapping every other source uses - no `tavily-python` SDK, so the dependency list is unchanged and CI never needs the vendor package. Wired into `_free_sources` after the shared `.env` load (the #125 lesson: never read a key before `load_dotenv` has run). `.env.example` and `/research`'s command doc gain the key with an explicit "never require it" note. Covered by three tests in `tests/test_research_sources.py` (keyless constructor refuses, header-auth + Result mapping + empty-URL rows dropped, pool includes Tavily only when keyed and academic mode stays untouched). Proposed by @manisrinivasan2k1 (#97); reimplemented per the review feedback there.

- **GitHub Copilot CLI is served by the agent-skills build - no dedicated adapter needed (#133).** Copilot CLI loads project skills from `.agents/skills/` (as well as `.github/skills/` and `.claude/skills/`) and personal skills from `~/.agents/skills/` or `~/.copilot/skills/` (as of 2026-07, docs.github.com), so the unified Agent Skills tree shipped for #139 already covers it - verified with a real `npx skills add ... -a github-copilot` install, which lands the same 44-skill `.agents/skills/` tree. This is the unified adapter's design paying out: a new harness on the open standard, zero repo changes. The `dist/agent-skills/INSTALL.md` per-harness notes and the README now name Copilot CLI explicitly. Resolves the scope question in #133 (thanks @CowboyPurest for the prototype and the platform research) without adding another near-duplicate adapter to maintain.

- **New `agent-skills` build: one `.agents/skills/` tree for Google Antigravity, Codex CLI, and OpenCode (#139).** Antigravity's skill discovery only scans `<workspace>/.agents/skills/<name>/SKILL.md`, so a user who installed the `gemini-cli` build got no detected skills - its `GEMINI.md` is read only as passive context. Codex, OpenCode, and Antigravity have all converged on that same open Agent Skills path, so this adds a single adapter that emits one spec-compliant tree all three read, rather than a fourth near-duplicate. `bash scripts/build.sh --platform agent-skills` produces `dist/agent-skills/skills/<name>/SKILL.md` (43 command skills; calendar stays Claude-only) plus a shared `obsidian-core` skill carrying `references/`, `scripts/`, and `pyproject.toml` that the command skills' `uv run --directory ...` invocations resolve against. Frontmatter is spec-minimal (`name`, `description`, string-map `metadata.category`) so OpenCode's strict validator accepts it and each `name` matches its directory; there is deliberately no root `SKILL.md` (which would shadow the nested skills in skills.sh discovery). Each skill is self-sufficient - a vault-root resolution preamble (`$OBSIDIAN_VAULT_PATH` else the working directory) and the embedded AI-first write spec mean no session-start hook is required, and the spec survives even a partial install. A new optional source key `trigger-mode: proactive` encodes the selection policy into each description (the only signal these harnesses use for implicit selection): capture-type commands (save, capture, log, person, decide, daily, task) read "use proactively", everything else "use only when explicitly asked". Ships with an `INSTALL.md` (skills.sh path plus a manual `cp -R` fallback and per-harness notes, including Antigravity's headless `--add-dir` requirement) and a `global-rule-snippet.md` for the optional always-on vault-routing rule. The existing `codex-cli`, `gemini-cli`, and `opencode` builds are unchanged. Covered by `tests/test_smoke.py::test_agent_skills_build_generates_spec_compliant_tree`. Proposed and prototyped by @Litash (#139).

- **`vault_health.py` takes a per-vault `.vault-config.json` for user excludes (#140).** The exclude list was hardcoded (9 entries), so large or academic vaults - atomic-card pools, backup snapshots, imported transcription dumps - produced thousands of false-positive findings that buried the real ones, with no way to quiet them short of editing the script. An optional `<vault>/.vault-config.json` now extends the skip list: `exclude-dirs` (directory names matched anywhere in the tree) and `exclude-paths` (vault-relative path prefixes). Both are strictly additive - the built-in `EXCLUDE_DIRS` always applies on top, so a config can never weaken the hardcoded safety excludes - and a missing or malformed file is ignored silently (a health check must never fail because of its own optional config). The user `exclude-paths` are intentionally not applied to the link-resolution file index, so a live link into an excluded path still resolves instead of ringing as broken. On a real 12k-note research vault the reporter measured findings drop from ~15,045 to ~2,321 (85% less noise) and scan time from 5+ minutes to ~19 seconds. `/obsidian-health` now offers to write the config when a scan is drowning in unmaintained-directory noise. Pure stdlib, no new dependencies. Covered by `tests/test_user_excludes.py` (exclude-dirs suppress orphans, exclude-paths suppress all issue types, hardcoded excludes still apply, missing/malformed config ignored). Proposed by @Rongles-World (#140).

- **PostCompact bg-agent runs with `--strict-mcp-config`.** The bg-agent prompt states MCP is not available in that subprocess, but the launch loaded every enabled MCP server anyway - wasted startup, and for users running an MCP-based bot (a Telegram/Slack integration) alongside Claude Code it could seize the bot's single MCP session and disrupt the live poller. The headless launch now passes `--strict-mcp-config` so it matches the prompt's own filesystem-only contract. Thanks to @Facens (#136).

- **PostCompact bg-agent is now observable, and burst-safe.** Every early-exit guard used to be a bare `exit 0`, indistinguishable from "nothing to do", and the headless run's exit code and duration vanished into the detached subshell. The hook now appends one JSONL line per outcome to `$VAULT/.claude-runs/YYYY-MM-DD.jsonl` (early-exit reason, or `starting` + `completed` with `duration_sec` and `exit_code`), built with jq so escaping is correct even for Windows backslash paths, and fail-loud so the observability layer can't hide its own bugs. A short-TTL `.claude-lock` drops the second of two hooks that fire when two sessions compact within seconds of each other. `file_mtime` reads the lock age portably (GNU `stat -c`, BSD/macOS `stat -f`). Thanks to @sad85520 (#130). Covered by `tests/test_bg_agent_hook.py` (starting + completed recorded with exit code, early exits logged not silent).

- **PostCompact bg-agent can be steered by the origin project's CLAUDE.md.** One vault serving several workspaces needs different routing (which board, which hub, which frontmatter) depending on where the compact fired - knowledge the LLM summary cannot carry. With the opt-in `CLAUDE_VAULT_PROPAGATION=1`, the hook reads the compacting project's `cwd` (already in the PostCompact stdin) and, if that project's CLAUDE.md has a `## Vault propagation hints` section, injects that section only into the prompt as project-specific rules, ranked explicitly below the vault's own `_CLAUDE.md` so a sloppy or hostile repo file can never override vault authority. Ships inert (same double-gate philosophy as the enable flag). Thanks to @sad85520 (#131). Covered by `tests/test_bg_agent_hook.py` (hints injected only when opted in, only the section travels).

- **The freshness policy and lint are named: OKM (Open Knowledge Metabolism).** The one-page spec and `freshness_lint.py` now carry the OKM attribution and MIT copyright inline. OKM is an open standard for keeping AI-maintained knowledge folders true - the metabolism to OKF's format. It lives here in obsidian-second-brain (where it was built and dogfooded on a 2,300-note vault); a standalone template repo may follow.

- **The freshness policy is now part of the write constitution, and it has a refresh loop.** Rule 4 of `references/ai-first-rules.md` (recency markers) now extends to internal fast facts: every stored fact must be timeless, dated, or a pointer, so every command that writes to the vault produces compliant notes from birth instead of relying on after-the-fact detection. The policy spec gained "The refresh loop" - the three answers to an aged stamp (re-observe, convert to pointer, retire into a dated note) that turn detection into maintenance; /obsidian-health's Freshness agent runs that loop on FRESH-2 warnings.

- **/obsidian-health now runs the freshness lint as its own agent.** The health check gained a Freshness agent that enforces `references/freshness-policy.md` across the vault: undated present-tense claims about fast facts surface as warnings, with three offered fixes (add an `as of` stamp, convert to a pointer, move into a dated note) and never a deletion. Documented in SKILL.md and the README commands table. The policy and lint grew out of the two stress-test rounds: the audit found search surfacing superseded facts (#114) and the vault-side answer is metadata that cannot lie silently.

- **scripts/freshness_lint.py - the freshness policy is now machine-checked.** Scans any markdown folder for the four FRESH rules: undated present-tense claims about fast facts (error), stale `as of` stamps on volatile claims (warning), unmapped typed pointers (error), with dated files/headings/`freshness: snapshot` notes exempt as immutable history. Tuned against a real 2,300-note vault: v0's number+noun heuristic was ~80% noise, so FRESH-1 requires an explicit current-state marker (currently/has/open/at N...), ordered-list markers and hyphenated numbers don't count as quantities, and imperative-mood lines are skipped. HTML comments, host:port strings, and blockquotes are never claims (comment sentinels and quoted speech tripped it on a real vault); inline code spans are quotation, not claims, and modal sentences ("can change", "must carry") are rules, not observations - both learned by making the template repo pass its own lint. Per-folder `.freshness.json` config (window, extra nouns, pointer mappings, exempt dirs). Stdlib-only, `--json` and `--strict` modes; fenced by 11 tests. On a repo written under the policy it gates CI; on a legacy vault it is an audit report.

- **references/freshness-policy.md - the freshness policy as an enforceable one-page spec.** Every stored fact must be timeless, dated, or a pointer; nothing may claim to be current without an `as of` stamp. Defines slow facts (stored, ~7+ days stable) vs fast facts (linked to their home system, never stored bare), the three legal forms, the one illegal form (the undated present-tense claim that rots into a lie), and four lint rules (FRESH-1..4) a checker can enforce. Storage-agnostic by design: applies to any folder of markdown an AI treats as a source of truth, not just Obsidian vaults. First artifact of the source-of-truth maintenance layer.

- **DEMOS.md - a demo gallery, with the flagship /obsidian-save demo above the fold in the README.** Three demos ship: /obsidian-save fanning one brain-dump into five cross-linked AI-first notes (real headless claude run against a synthetic vault, the model's working pause cut and disclosed), the two-command plugin-marketplace install, and bootstrapping a vault that passes its own health check. Every demo is real footage rendered from a committed vhs tape (`media/*.tape`) against throwaway synthetic data, so demos re-render pixel-perfect for future versions and no real vault can ever appear in one. The README's stale v0.10 banner blurb now says v0.12.

- **Native Claude Code plugin-marketplace install.** The repo is now its own plugin marketplace: `/plugin marketplace add eugeniughelbur/obsidian-second-brain` + `/plugin install obsidian-second-brain@obsidian-second-brain` replaces the clone-and-symlink dance for Claude Code users. The plugin ships all 44 commands (auto-discovered as skills, ~2k always-on tokens), the skill manual, the SessionStart context hook, the PostCompact background agent (still inert without `OBSIDIAN_BG_AGENT_ENABLED=1` - the hard gate is in the script), and the bundled vault MCP server (inline `mcpServers` in `plugin.json`, since `${CLAUDE_PLUGIN_ROOT}` does not expand in a root `.mcp.json`). Verified with a live local install: marketplace add, plugin install, 45 skills + 2 hooks in the inventory, and the MCP server connecting end-to-end. The classic `install.sh`/`setup.sh` path is unchanged and coexists. Fenced in CI by `tests/test_plugin_manifest.py` (manifests parse, versions sync with pyproject, referenced scripts exist, the bg-agent keeps its gate). This closes the audit's top distribution finding ("high-friction install vs one-click marketplace" - the single biggest stars gap).

## [0.12.0] - 2026-07-11 - The Stress Test

### Fixed

- **/research and /research-deep now honor a PERPLEXITY_API_KEY set in `~/.config/obsidian-second-brain/.env`.** The free-vs-paid decision read the process environment before anything had loaded the shared `.env` file (the documented setup), so paid-mode users silently got the free pipeline. Root-caused and fixed by @MichaelHabermas in #125 (fixes #124), joining the project's 17 external contributors. Fenced in CI: a smoke test proves a key set only in the config `.env` selects paid mode, and that zero-config free mode still works when no key is set anywhere.

- **The audit's three never-tested surfaces are now exercised live, and the one real bug found is fixed (#126).** The bg-agent hook's gates, garbage-stdin handling, and parse-and-spawn chain are tested against a stub `claude` binary, and its embedded prompt resolves folders from the vault's folder map instead of hardcoding Obsidian-style names. The MCP write path ran end-to-end against a scratch vault with traversal probes on save/update/read all refused. The Telegram ingest core had a real bug: hardcoded wiki-style folders would fork a parallel `wiki/` tree into Obsidian-style vaults - fixed with folder-map resolution and covered by layout-sensitive tests.

- **Every platform dist ships a runnable Python project now (stress-test fix 24/24 - the sprint closer).** The Codex build documented `uv run -m scripts.research.<name>` "from the vault root", but the install copies scripts to `<vault>/.codex/scripts/` and ships no `pyproject.toml` anywhere - the documented command hit `ModuleNotFoundError` with unresolvable dependencies, on every non-Claude platform (Gemini and Hermes documented the same broken invocation; OpenCode shipped the same broken layout silently). All five adapters now copy the repo's `pyproject.toml` next to their `scripts/` tree, making each dist a self-contained uv project, and the docs state the working invocation (`(cd .codex && uv run -m scripts.research.<name> ...)` for dot-dir platforms; from the install directory for Hermes). Verified live: the documented command now resolves and runs from a built dist. Fenced in CI: the codex dist must contain `pyproject.toml` beside `scripts/`, the INSTALL doc must state the cd-aware invocation, and the old broken claim must be absent. **This closes the 24-task stress-test fix sprint: PRs #100-#123, ~160 of the audit's 175 findings resolved, the test suite grown from 30 to 119 with eleven permanent CI fences.**

- **The front door works now: a real one-line installer, a no-vault path, prerequisites up front, and a bootstrapper that never eats files (stress-test fix 23/24, opens Phase D).** The audit's newcomer walk, minute by minute: the README's FIRST copy-pasteable command curled `scripts/quick-install.sh` - **a file that did not exist** (404 as the first user experience); the fallback "two commands" path wired a vault but never ran `install.sh`, so the slash commands were never installed; a user with no vault hit setup.sh's hard error with no way forward; missing `jq` produced a misleading "invalid JSON" error; and `bootstrap_vault.py`, pointed at a folder containing a hand-made `Home.md` and `_CLAUDE.md`, **silently replaced both** behind a vague y/N prompt - data loss the audit verified. Fixed: `scripts/quick-install.sh` exists now (idempotent: clone-or-pull, run install.sh, print the two finish paths); the README states prerequisites before anything, includes `install.sh` in the step-by-step, and gains a "No vault yet?" branch (bootstrap one that passes its own health check, then setup); `setup.sh` checks for `jq` up front with install hints and its vault-not-found error tells you exactly what to run; and bootstrap follows the sprint's safety rule - **tools may create, keep, or ask; they never silently replace**: every existing file is kept by default with a per-file "kept existing" line, `--force` is the explicit overwrite consent, and the scary-but-vague prompt is gone because the danger is gone (bootstrap is now safe non-interactively too). Guarded by `tests/test_front_door.py` (bootstrap preserves user files / --force overwrites / all three installers parse and the README's one-liner target exists - verified failing against the old code).

- **SKILL.md and README tell one truth now, and the build ships clean (stress-test fix 22/24, closes Phase C).** Six SKILL.md sections had drifted from the commands they describe - worst, `/notebooklm`'s section still documented the removed manual-browser flow (paste into notebooklm.google.com, a `--save-response` flag that errors out) a full release after the Gemini File Search rewrite; `/obsidian-daily` omitted the calendar/kanban pulls, `/obsidian-init` omitted `index.md`/`Logs/`/Bases stamping, `/obsidian-log` and `/obsidian-review` hardcoded folders their commands resolve via folder-map, `/obsidian-export` omitted the OKF format it ships. All six are rewritten as compact, accurate summaries that explicitly defer to `commands/<name>.md` as the source of truth - the structural cure for this class of drift - and SKILL.md's 29 remaining em/en-dashes were purged with the banned-char lint extended to cover it. README: the dead `#43-commands` anchor, the How-It-Works diagram that summed to 43 (Layer 2 said 7 thinking tools; there are 8), the "35 non-research commands" undercount (37), and the platform list missing Pi are all corrected. `/obsidian-calendar` now carries `exclude: pi` (it was shipping to a platform SKILL.md declares it cannot run on). `references/claude-md-template.md` stops leaking the Claude-only "Write tool" name into every non-Claude dist. `mine_commit_decisions.py` stops directing users to the retired `/obsidian-adr` (now `/obsidian-decide --formal`). `/obsidian-retrieval-eval` honestly states the key-less generator fallback. And `build.sh` no longer ships Python bytecode (`__pycache__/*.pyc`) into user vaults - verified zero across all six dists. **New fence:** `tests/test_doc_roster.py` - every command file must appear in both SKILL.md and README.md, and the headline count must equal the filesystem count. Flagged for the maintainer, not code: stale `v1.0.0`-`v4.0.0` git tags (no releases behind them) make `git tag | sort -V` misleading against the real `v0.x` release line - recommend deleting them.

- **Command logic sweep: twenty instructions that described a machine that does not exist (stress-test fix 21/24).** For a skill whose product IS instructions for agents, doc drift is defect - an agent cannot shrug at part 14B. Five species fixed. *Phantoms:* `/obsidian-init` told the agent to replace a `{{FOLDER}}` placeholder no template contains (they use `{{DAILY_FOLDER}}` etc. - now named exactly). *Feedback loop:* `/obsidian-projects` inferred "active" from the most recent entry INCLUDING its own `## Last overview` writes, so running the status check marked stale projects active forever - inference now excludes the section this command itself writes. *Unreachable logic:* `/obsidian-learn`'s default 30-day scope made its own "Stale = 6+ months" classification impossible - stale/superseded detection now always scans the full vault; `/obsidian-board`'s "same column for more than a week" asked for data the board format cannot hold (date stamps are now the stated age signal). *Stale claims:* `/notebooklm` documented the wrong default model (`gemini-2.5-pro` vs the code's `gemini-2.5-flash`); the podcast scripts' docstrings said "Spotify not supported" about code that ships the Spotify bridge; `/create-command`'s build note described a Codex routing table that is now native Agent Skills, and its template omitted `triggers_es` (generated commands silently dropped out of Spanish triggering) plus the anti-fabrication footer. *Fragile steps:* `CRITICAL_FACTS.md` read unguarded (nothing creates it - now "if it exists"); bare `python` invocations (absent on stock macOS - now `python3`); repo-relative script paths with no cwd stated; `templates/` vs `Templates/` casing mismatches in daily/review; `/obsidian-log` with no fallback when no template exists; `/obsidian-catchup` describing an always-4-field queue line the bot sometimes writes with 3; `/obsidian-visualize` promising topic-phrase scopes the script resolves only as exact titles (plus edge "thickness" JSON Canvas cannot express - now edge labels). Also settled: operation-log routing unified (per-day `Logs/` with create-if-needed, ending the first-write-of-the-day trap in calendar and board-hygiene), the anti-fabrication footer added to the three commands missing it, and a documented **vault-surface exception** (root operating files - `_CLAUDE.md`, `Home.md`, `index.md`, `log.md`, `catchup.md`, per-day `Logs/` - are navigation/append surfaces, not knowledge notes; the validate hook now skips them, so `/obsidian-init`'s own outputs stop tripping the skill's own guard).

- **Schema reconciliation: one constitution, documented exceptions, no secret laws (stress-test fix 20/24, 17 audit findings).** `ai-first-rules.md` failed in the three ways a constitution can. *Missing laws:* notes typed `learnings-review`, `conflict`, `source` (raw captures), and `research-notebooklm` were being created with no schema - every writer improvised; and `/obsidian-projects` gated its git/docs checks on a `repo:` field defined nowhere, so they could never run. All four schemas are documented now, and the `type: project` schema gained its real optional fields (`job`, `repo`, `graduated-from`). *Contradicted laws:* `/obsidian-decide` taught `tags: [decision-record]` against the ADR schema's `[adr, decision]`; `/obsidian-project` called a 4-field list the "full schema" (the real one has 9); `/obsidian-graduate` labeled an incomplete list "complete" and invented a "linked idea" field (now the documented `graduated-from`); `/obsidian-distill` omitted `related-people`/`related-projects`; `/obsidian-panel`, `/idea-discovery`, and `/x-read` dropped required fields or the type-as-tag; `/x-read` also used a bold label where the rule mandates the `## For future Claude` heading; `/obsidian-challenge` had a schema with no command output to match (it now offers to save the standalone report); `/obsidian-emerge` never named its report's type. *Impossible laws, now documented exceptions:* quick capture cannot fill nine fields at capture speed - the **capture exception** legalizes the minimal schema with enrichment at graduation, by design; and a kanban board cannot carry an `## For future Claude` H2 (the plugin renders it as a phantom column) - the **kanban exception** exempts board files, both board commands' footers are scoped accordingly, and `validate-ai-first.sh` learned to skip `boards/` so the guard stops flagging what the law now permits (the raw-source exception was already hook-skipped and is now written down too). A documented exception is law; an undocumented one is rot. Bonus: `/obsidian-panel`'s hardcoded folder (missed by the audit AND the fix-18 sweep) resolved and added to the folder lint. Fenced by `tests/test_schema_coverage.py`: every `type:` a command mandates must have a schema in ai-first-rules.md, verified to fail against the pre-fix rules.

- **The guard and the teacher read the same rulebook now: 50 banned characters purged from instruction files (stress-test fix 19/24).** `validate-ai-first.sh` check 5 blocks vault writes containing substitution Unicode, yet 15 command and reference files taught the agent to write exactly those characters: `/obsidian-init` mandated an em-dash in every index.md line, filename templates across `/obsidian-log`, `/obsidian-review`, `/obsidian-save`, `/obsidian-ingest`, `/podcast`, `/x-read`, and `/x-pulse` prescribed em-dash separators (and the podcast/x docs even *misdescribed* their own scripts, which actually write hyphens), `folder-map.md`'s ADR row and `vault-schema.md`'s entire naming table carried them, both `_CLAUDE.md` templates were full of them (22 in the personal template alone), a stray `±` pair sat in the calendar command - and worst of all, `/create-command`'s footer template had them baked in, so **every future command was born infected**. The agent obeys the teacher, the guard blocks the write: a tool arguing with itself. Why CI never noticed: the repo's character sweep rightly exempts backtick spans in code, but in an instruction file a backticked template is precisely what the agent copies into the vault. All 50 occurrences purged (em/en-dashes to hyphens, `±` to `+/-`); one legitimate survivor, allowlisted: the ai-first-rules table that *defines* the banned characters keeps its specimens, since a rulebook must be able to name what it bans. The blind spot is fenced: `tests/test_no_banned_chars_in_instructions.py` scans `commands/` and `references/` with NO backtick exemption and fails CI on any recurrence.

- **The folder-map sweep: 18 commands stop giving directions from memory (stress-test fix 18/24, opens Phase C).** `references/folder-map.md` has one non-negotiable rule - "never hardcode a folder name in a command body" - and the audit found 16+ commands violating it, which means every user on the skill's own default bootstrap (Obsidian-style layout) got broken behavior the wiki-style maintainer never saw: `/obsidian-export` scanned only `wiki/` and produced a **perfectly empty snapshot with no error**, `/obsidian-learn` read ADRs and reports from folders the bootstrapper never creates (the learning loop silently learned from nothing), and `/obsidian-ingest` searched wiki-style paths while writing new pages there too - one ingest away from forking a vault into two half-vaults. 37 hardcoded write/scan paths across 18 command files now resolve through the map ("the entities folder per `references/folder-map.md` - wiki-style `wiki/entities/`, Obsidian-style `People/`"), including `/obsidian-recap`'s fictional `list_files_in_dir("Daily/")` call and `/notebooklm`'s hardcoded maintainer-machine repo path that shipped verbatim into every platform dist. The map itself gained its two missing rows (agenda snapshots, recurring obligations) so "resolve per folder-map" never dead-ends, and `/obsidian-recurring` finally names its save folder. **The rule is a fence now, not a sign:** `tests/test_folder_map_compliance.py` lints every swept command and fails CI on any bare vault-folder mention outside a folder-map context - it caught 3 additional calendar-command violations the audit itself had missed, during its own first run. A doc example carrying a real person's name was also replaced with a generic one.

### Changed

- **Phase B of the stress-test fix series closes with a formal before/after baseline (fix 17/24): retrieval quality is now a committed, re-measurable number.** New `scripts/eval/BASELINE.md` records the reference metrics (metrics only - case sets stay gitignored because they contain vault content) so every future retrieval change can be held against them; the rule stands: no retrieval change ships without before/after numbers on the same cases. Fusion weight re-swept on the final stack (w=10 and w=20 each strictly better than w=5 on bge-m3): the shipped default now runs **w=20**, where the lexical arm serves as tiebreak plus coverage for notes written since the last index build, and the default converges to pure-semantic quality while keeping single-token dispatch and the freshness re-rank. Phase B totals on the shipped default, honest ruler, same cases throughout: English paraphrase MRR 0.207 -> **0.476** (+130%, recall@10 0.429 -> 0.771), English keyword MRR 0.621 -> **0.820** with recall@10 a perfect **1.000**, Russian/Spanish MRR 0.094 -> **0.377** (4x, recall@5 5x). README's search section updated: the previous claims there ("recall@10 80% -> 91%, paraphrased 17% -> ~46%") were measured with the pre-fix harness whose lexical label was silently fused and whose hybrid double-counted semantic - the new numbers are the honest ones. `--mode hybrid` (flat 1:1 fusion) is documented as a lab reference: it is now strictly worse than semantic everywhere.

- **The default embedding model is multilingual now (bge-m3), and two model-mix bugs are guarded (stress-test fix 16/24, measured on three case sets before shipping).** The audit's multilingual lane measured Russian paraphrase queries at **0% hit@5 in every mode** and Spanish near-zero: Cyrillic shares no characters with Latin titles (keyword search blind) and the English-centric `mxbai-embed-large` places non-English text at near-random meaning-coordinates (semantic search blind too) - for a trilingual user, two independent blindnesses stacked to exactly zero. Swapping the librarian instead of the wiring: `bge-m3` (multilingual, ~same size, via Ollama) is the new default (`OBSIDIAN_EMBED_MODEL` still overrides). Measured before shipping on all three eval sets - English paraphrase, English keyword, and a new private Russian/Spanish paraphrase set (gitignored, vault content never leaves the machine): the swap is a straight upgrade, not a trade. Shipped-default mode: English paraphrase MRR 0.220 -> **0.329** (recall@10 0.457 -> 0.686), English keyword MRR 0.743 -> **0.793** (pure-semantic recall@10 on keyword hit a perfect 1.0), Russian/Spanish MRR 0.094 -> **0.335** with recall@5 up five-fold (0.125 -> 0.625). The fusion weight re-tuned on the stronger model: semantic votes now carry 5.0 vs lexical 1.0 (measured w=3 vs w=5; strictly better). Two latent model-mix bugs found while preparing the swap, both guarded: the build cache did not invalidate on a model change (stale vectors from the old model would be silently reused - vectors from different models live in different spaces, and cosine between them is a number that means nothing), and queries were embedded with the locally-configured model rather than the index's - the query now always embeds with `index["model"]` in both the MCP fuse path and the eval. Existing mxbai indexes keep working for queries (the index carries its model); the next `--build` re-embeds fully (~10 min on ~1300 notes, `ollama pull bge-m3` first). The fix-14 adaptive splitter carried over cleanly: the rebuild finished 100.0% coverage, 0 degraded, 0 dropped. Guarded by `tests/test_multilingual_model.py` (4 cases, all verified to fail against the old code).

### Fixed

- **Freshness: "current" is part of the question now, and stale-status notes step back (stress-test fix 15/24).** The audit's flagship retrieval danger: a current-state question (e.g. "what is our current CI provider") ranked a since-declined, superseded note above the one that actually still holds - and an AI agent reading search results as ground truth cannot sense "wait, that was months ago" the way a human does. Two honest signals the ranking had been throwing away: (1) **status fade** - a note whose own frontmatter says it no longer holds (`superseded`, `declined`, `archived`, `parked`, `rejected`, `obsolete`, `cancelled`, `closed`, `inactive`, `done`) fades x0.6 (`OBSIDIAN_SEARCH_STATUS_FADE`), always; (2) **recency band** - note age (from `updated:` > `date:` > file mtime) applies a gentle multiplicative band on the lexical arm ([0.92, 1.0] - evergreen notes lose only near-ties), which widens to [0.6, 1.0] with a ~90-day half-life when the query itself asks about the present (current/currently/now/still/today/latest/actual). Because the semantic arm knows nothing about time and fusion drowned lexical-only signals, a **post-fusion re-rank** reads the top results' frontmatter heads (cheap: ~10 x 400 bytes) and reorders by rank-derived scores - a reorder, never a rewrite. Spot-checked on the audit's private-vault queries: the note describing the current state climbed rank 6 -> 3 while a since-declined note dropped 2 -> 6, and a superseded rename ADR fell 2 -> 6 beneath the current note. Measured regression guard on both eval case sets: paraphrase unchanged, keyword actually improved (recall@10 0.867 -> 0.900, MRR 0.709 -> 0.743 - stale notes stepping back helps everywhere). Left explicitly to the vault, not the code: notes whose own metadata lies (a declined project still marked `status: active`) - no ranking can know better than the note itself; that is /obsidian-reconcile's job. Guarded by `tests/test_freshness.py` (5 cases, all verified to fail against the old code).

- **The semantic index reaches 100% coverage: walls get split, weather gets retried, and gaps are a report, not a surprise (stress-test fix 14/24).** The audit found 23 eligible notes silently missing from the index; the fix-13 rebuild reproduced 11 chronic failures - every one a deterministic HTTP 500, not a transient blip. Root cause, proven by bisection on a real failing note: token-dense content (a 1,066-char table of euro-amount rows) blows past the embedding model's 512-token window at char counts where prose fits comfortably, and even `'x'*1200` fails - char count is a bad proxy for token count, so NO fixed chunk size is ever safe. The retry ladder (medicine for transient weather) was being prescribed for a wall: same input, same 500, every build, and the note was then dropped silently, unfindable in semantic search forever. Now: (1) a chunk that fails to embed is halved and retried recursively (floor 300 chars) - adaptive to any token density, no tokenizer dependency; the splitter uses a short retry ladder (a deterministic failure repays every retry with the same 500, and the full ladder at every split level turned an 11-note repair into a 10-minute stall); (2) if even splitting fails, the note degrades to an identity-only vector (title | type | aliases) - findable by name beats absent and silent; (3) the build summary prints coverage % and NAMES every degraded or dropped note. Measured on the real vault: coverage went from 1288/1299 with silent drops to **1301/1301 (100.0%), 0 degraded, 0 dropped**. Guarded by `tests/test_index_robustness.py` (4 cases, 3 verified to fail against the old code).

### Changed

- **Ranking learned that volume is not relevance: type-aware lexical weights + per-chunk semantic indexing (stress-test fix 13/24, every variant measured before shipping).** Two diseases from the audit's adversarial lane. *Lexical:* term-dense operational logs took #1 on 7 of 12 paraphrase queries, burying canonical notes - notes typed `log`/`dev-log`/`daily` (or living in logs/daily folders untyped) now fade to 0.5 (`OBSIDIAN_SEARCH_LOG_WEIGHT` - a moderator, not a mute: a log still wins when it is genuinely the best match) and `person`/`entity` dossiers boost 1.5x (`OBSIDIAN_SEARCH_ENTITY_BOOST`). *Semantic:* `embed_note` mean-pooled a whole note into one averaged vector, so a 10-section dossier answering a query in section 7 had its signal drowned 9-to-1 (a person dossier contained an answer verbatim and ranked nowhere) - the index (format 2, auto-invalidates old caches) now stores per-chunk vectors, each chunk prefixed with an identity header (title | type | aliases | related people/projects, so a mid-dossier chunk still knows who it is about and proper-noun notes are reachable by described role), empty template sections are stripped before embedding (daily-note scaffolding stopped diluting the day's real content), and a note scores by its best chunk. Scoring variants measured and rejected on both eval case sets: multiplicative type weights on cosine (deleted log notes outright - cosine clusters at 0.6-0.7, so x0.5 is death, recall halved), additive nudges, and a 70/30 max+mean blend; pure best-chunk won. Also: the fuse-side index parse is cached by (path, mtime, size) - the per-chunk index is tens of MB and the MCP server is long-running - and vectors round to 6 decimals (index 145MB -> 68MB). Net on the honest ruler vs fix 11: keyword recall@5 0.700 -> 0.800, recall@10 0.733 -> 0.867, MRR 0.649 -> 0.709; paraphrase recall@1 0.114 -> 0.143 with recall@5 trading down (0.400 -> 0.286 on single-gold cases) - average MRR across both sets up 0.440 -> 0.465. Known remaining (documented for tasks 14/16): the three hardest audit misses (a person dossier by anecdote, a project note by role description, a meeting note by its synthesis) still miss - the bottleneck is now the embedding model's discrimination on this domain, not the wiring; 11 notes persistently fail to embed (HTTP 500). Guarded by `tests/test_ranking_quality.py` (7 cases, 6 verified to fail against the old code).

- **The lexical scan cap is big, deterministic, and loud now - no more randomly unsearchable notes (stress-test fix 12/24).** `search()` stopped reading after `_MAX_FILES_SCANNED = 2000` files delivered in whatever order the filesystem returned them, so on the maintainer's 2,342-note vault ~342 notes were silently unsearchable - and *which* 342 changed as files moved on disk, the kind of miss users cannot reproduce or report. Any note past the cap AND absent from the semantic index was unfindable in every mode. Three changes: (1) `_iter_notes` yields newest-first (modified time), so every capped consumer - search, the audit endpoints, the "capped" stats flag - degrades predictably: if a cap ever bites, the oldest notes fall off, never a random slice (and a `stat()` guard means dangling symlinks skip instead of killing the walk); (2) the default cap is 10,000 with an `OBSIDIAN_SEARCH_MAX_FILES` env knob - a guard against pathological trees, not a slice of real vaults; (3) when search does truncate, it says so on stderr with the knob to raise, because bounded work is fine and silent truncation is not (the same rule as fixes 6 and 9). Measured on the real 2,342-note vault: a full pure-lexical scan takes ~510ms - the old cap was solving a problem the vault does not have. Guarded by `tests/test_search_cap.py` (3 cases: newest-first order, cap-bites-oldest-and-warns, default-covers-real-vaults).

- **The shipped search default is query-aware now: single tokens go lexical, and semantic votes outweigh lexical in the fusion (stress-test fix 11/24, measured with the fix-10 ruler before shipping).** The audit's referee proved the old flat 1:1 fusion was worse than the pure-semantic layer it already computed: on 12 paraphrase questions, semantic alone put the right note at #1 half the time (recall@1 50%) while the shipped blend managed 8% - on every case semantic answered perfectly, a long term-dense log note outvoted it. Meanwhile bare acronym lookups broke the other way: "OKF" ranked 2 in pure lexical but 5 after fusion, because embeddings of a bare token are near-meaningless noise. Two changes, both measured on the honest ruler across a 35-case paraphrase set AND a 30-case keyword set before shipping: (1) **dispatch** - a single-term query (acronyms, bare names: lookups, not questions) skips fusion entirely and gets the pure lexical ranking ("OKF"/"ICM" now surface the OKF concept notes at #1-2); an explicit `semantic=True/False` from a caller always overrides the dispatch. (2) **Weighted fusion** - semantic contributions to the RRF now carry weight 3.0 vs lexical's 1.0 (`OBSIDIAN_RRF_SEMANTIC_WEIGHT`, plus an `OBSIDIAN_RRF_LEX_DEPTH` knob), the winner of a measured sweep (w in 2/3/4, lex-depth 8/25): vs the old default it lifts paraphrase recall@5 0.343 to 0.400, recall@10 0.429 to 0.543, MRR 0.207 to 0.232, and keyword recall@1 0.533 to 0.600, MRR 0.621 to 0.649, with the best average MRR of any candidate including pure semantic - while keeping lexical coverage for notes the embedding index doesn't hold. Also: `.gitignore`'s cases pattern broadened to `retrieval_cases*.jsonl` so generated eval sets (which contain vault content) can never be committed. Guarded by `tests/test_query_aware_default.py` (4 cases: dispatch, multi-word fusion, explicit override, and a weighted-fusion ordering that verifiably fails under flat 1:1 fusion).

### Fixed

- **The retrieval eval measures what its labels claim now - the bent ruler is straight (stress-test fix 10/24, opens Phase B).** Three of the harness's labels lied. (1) `--mode lexical` called `vault_ops.search()`, which silently RRF-fuses the semantic index whenever one exists and Ollama is up - so "lexical" scores were actually the blend, under a false label. (2) `--mode hybrid` fed that already-fused ranking into `hybrid_search` as its "lexical" arm, fusing semantic TWICE: measured on the committed 35 cases, double-fusion scored recall@10 0.514 vs 0.457 for honest single fusion - enough inflation to flip the semantic-vs-hybrid ship decision made in June. (3) `--generate` opened the cases file with mode `"w"`, silently destroying the baseline mid-experiment so "before vs after" could quietly compare different questions. Fixed: `vault_ops.search()` gains an explicit `semantic=` switch (None follows the env - the shipped MCP behavior is byte-for-byte unchanged; the override threads into `_semantic_fuse`), `--mode lexical` forces it off and is labeled "pure lexical", `--mode hybrid` feeds fusion a genuinely pure lexical arm ("single RRF"), a new `--mode default` measures exactly what the shipped MCP serves users, and `--generate` refuses to overwrite an existing cases file without `--force`. Also unified: one canonical `_SKIP_DIRS` owned by vault_ops and imported by semantic_search (the lexical scan, semantic index, and eval searched measurably different universes - 1287 vs 1292 notes), with `_iter_notes` now comparing case-insensitively (`endswith("templates")` like the rest of the repo post-Phase-A) and skipping `.excalidraw.md` drawings for parity with the index. Guarded by `tests/test_eval_ruler.py` (7 cases, 6 verified to fail against the old code; multi-gold scoring pinned - the cases format already accepts a gold LIST, so reviewers can add acceptable alternates and exact-path recall is a floor, not the ceiling).

- **The showroom rule: a fresh vault now passes its own health check with zero findings (stress-test fix 9/24, closes Phase A).** `bootstrap_vault.py` followed immediately by `vault_health.py` - the first thing every curious newcomer does - reported **19 issues on a brand-new untouched vault**: 17 empty scaffold folders, Home.md's nav linking `[[Finances/Income Streams]]` (a note bootstrap never created), and the seeded Content Calendar sitting orphaned (a finding the audit itself missed; the new showroom test caught it). Fixed: scaffold folders that end up empty get an invisible `.gitkeep` (making the folder genuinely non-empty keeps the empty-folder alarm honest, unlike teaching vault_health to ignore scaffold names), `Finances/Income Streams.md` ships as a seeded note, and the Home nav gained a Content/Ideas/Reviews row so Content Calendar is linked from day one. Four toolbox paper cuts also closed: `triage_links --apply` without `--from` now gives a clean "required" error instead of a raw `TypeError` traceback; `sweep_non_ascii --help` prints usage instead of running a full repo scan (real argparse); sweep now WARNs per unreadable file and reports the count in its summary instead of silently skipping (a banned character in an undecodable file used to pass the `--check` CI gate unseen - unchecked must never read as passed); and sweep preserves `[[wikilink]]` interiors, because the dash inside `[[Call - script]]` is part of a filename, not typography - substituting it broke the link. Bonus: vault_health's wanted-note report now annotates bracket-containing captures with "capture may be truncated" instead of presenting a mangled name as authoritative. Guarded by `tests/test_showroom.py` (6 cases, all verified to fail against the old code), headlined by the permanent CI invariant: bootstrap + health check = 0 issues.

- **vault_health precision: the smoke alarm neither misses fires nor cries wolf now (stress-test fix 8/24).** Four precision leaks in the vault's referee. (1) The orphan check matched stems by substring (`any(stem_lower in lk ...)`), so a short-stemmed note like `ai.md` "found" itself inside unrelated links (det**ai**l) and never rang the alarm - matching is exact now, with path-qualified links (`[[Projects/note]]`) counting via their basename, which was the one legitimate case the substring hack served. (2) A note's own links counted as incoming, so a self-linking note could never be an orphan - the check now tracks link SOURCES and requires someone else to link you. (3) Two different notes sharing a title were flagged `warning: Likely duplicates` because identical frontmatter and the shared `## For future Claude` preamble alone pushed `SequenceMatcher` to 0.80 - similarity now compares prose with the frontmatter and preamble heading stripped, so same-title-different-content correctly downgrades to info while true duplicates still warn. (4) `parse_aliases` read only block-style YAML lists; inline `aliases: [X, Y]` (at least as common in Obsidian) was silently lost, making every link to such an alias ring as a wanted note - both styles parse now (the gap discovered during fix 4). Guarded by `tests/test_vault_health_precision.py` (6 cases, 4 verified to fail against the old code, 2 pinning the legitimate behaviors the fixes must not break).

- **link_graph now actually mirrors vault_health instead of claiming to (stress-test fix 7/24).** The docstring promised "mirrors vault_health.py's link handling", but the rules were re-implemented rather than shared, and the two copies drifted in both directions until the same 3,000-note vault reported 528 broken links (vault_health) vs 187 (link_graph). Five drifts fixed: (1) `_norm` flattened spaces, hyphens, and underscores into one separator, so `[[Foo Bar Baz]]` "resolved" to `foo-bar-baz.md` - an edge Obsidian would never draw - creating phantom map edges while hiding exactly 341 genuinely broken links; only em/en dashes unify now. (2) Links to real vault files (`[[Attachments/file.pdf]]`, `![[image.png]]`) counted as dangling because link_graph had no file index - it now shares `vault_health.index_vault_files` (shared parts cannot drift), and links resolving to existing folders are not dangling either. (3) `_CLAUDE.md`'s syntax-demo links (`[[wikilinks]]`) were scanned as real references; the manual is skipped, matching vault_health's `SKIP_FROM_LINK_SCAN`. (4) `[[Projects/ProjectX]]` dropped its folder and hit whichever same-named twin sorted first (`Archive/ProjectX.md`); path-qualified links now match the full relative path first, basename as fallback. (5) The skip-list check was case-sensitive (`SKIP_DIRS & set(parts)`), so the canonical capital `Templates/` polluted the orphan list with template files; comparison is lowercased plus `endswith("templates")` like every sibling script, with an `is_file()` ghost guard added for parity with fix 2. Guarded by `tests/test_link_graph_mirror.py` (6 cases, incl. a drift alarm that pins link_graph's dangling count to vault_health's wanted-note count on a vault exercising every disagreement; 4 verified to fail against the old code).

- **vault_stats: the census is honest now (stress-test fix 6/24).** Four counting sins, all reproduced in the audit. (1) `.git/` and `_export/` were missing from `EXCLUDED_FOLDERS`, so stray repo markdown was counted as vault notes and, worse, running the documented OKF export doubled every stat on the next run (the bundle is a full markdown copy of the vault inside the vault). (2) `parse_frontmatter` skipped continuation lines with `startswith(" ")` - a literal space - so tab-indented nested keys leaked to top level and a nested `meta:` block's `type:`/`status:` silently overwrote the note's real type in the counts; the check is now "starts with any whitespace". (3) Non-UTF-8 notes were silently dropped from every count with no trace - an undercount presented as fact in `index.md`, which future Claude reads as ground truth; each skipped file is now named in a stderr warning, and the total appears as `skipped_unreadable` in the JSON and as a footnote in the rendered stats block. (4) vault_stats alone demanded `--vault` and errored on `--path` while all six sibling scripts take `--path`; it now accepts both. Guarded by `tests/test_vault_stats.py` (4 cases, all verified to fail against the old code).
- **export_okf now translates faithfully or says it failed - six quiet lies fixed (stress-test fix 5/24, 12 audit findings).** The exporter's job is speaking OKF to downstream AI systems, where nobody proofreads output, yet it guessed silently in six ways. (1) `pyyaml` lived only in the script's PEP-723 header, so `uv run python scripts/export_okf.py` crashed with `ModuleNotFoundError` while `uv run scripts/export_okf.py` worked - reported five separate times by the audit; pyyaml is now a real project dependency (which also woke up the previously-skipped export test from fix 2). (2) The `SKIP_DIRS` check compared case-sensitively, so the canonical capital `Templates/` leaked Templater syntax into the bundle with invalid timestamps - the skip now lowercases and, like `load_vault`, skips any folder ending in "templates". (3) A YAML parse failure was swallowed (`except Exception: fm={}`), the note's type was then guessed from its folder name, and prose between a broken fence and a later `---` was dropped - `parse_note` now returns a `malformed` flag, the exporter prints a stderr `WARNING` naming the file, exports it as plain `type: note` (never the folder guess), and keeps the entire body verbatim. Folder inference remains only for notes with no frontmatter at all, where it is a fair, designed guess. (4) Link targets went through `PurePath.stem`, so `[[release v2.4 notes]]` had ".4 notes" treated as a file extension and the link silently degraded to text (the #93 truncation regression, still alive here) - only a literal trailing `.md` is stripped now. (5) A wikilink to a real vault file (`[[Attachments/file.pdf]]`) degraded to plain text while the equivalent embed kept its link - a new asset index resolves such links to relative paths, and only links to notes that truly don't exist degrade. (6) The vault's own root `index.md` was exported as a concept doc, counted, then overwritten by the generated bundle index - it is navigation, not knowledge, and is now excluded from collection so the doc count matches reality. Guarded by `tests/test_export_okf.py` (5 cases, all verified to fail against the old code).
- **A leading UTF-8 BOM no longer hides a note's frontmatter from vault_health, vault_stats, link_graph, and export_okf (stress-test fix 4/24).** Editors (mostly on Windows) prepend an invisible U+FEFF to files; every scanner that asks "does the file start with `---`" then answers no, because position zero holds a character nobody can see. Consequences reproduced in the audit: vault_health flagged healthy notes as missing frontmatter and lost their aliases (so alias links were reported as wanted notes and offered for "healing"), vault_stats silently dropped the note from its `by_type` counts, link_graph lost the node's `type`, and export_okf emitted a duplicate frontmatter block with a garbage description. Fixed with one word at each of the six read sites: `encoding="utf-8-sig"`, which strips a BOM when present and is plain UTF-8 otherwise. Files on disk keep their BOM (fix 1's byte-exact rule: readers must not rewrite); only the readers stop being blind. Guarded by `tests/test_bom_frontmatter.py` (3 cases, verified to fail against the old code) plus a manual export check (single frontmatter block, clean description). Noted for a later fix: `parse_aliases` only reads block-style YAML lists, inline `aliases: [X]` is a separate pre-existing gap.

- **`heal_links.py` / `triage_links.py` can no longer corrupt notes they rewrite (stress-test fix 1/24, referee-confirmed).** Both scripts read notes with `read_text(errors="replace")` and wrote the result back with `write_text(encoding="utf-8")` - so any note that was not valid UTF-8 (e.g. latin-1 accents) had every undecodable byte silently and permanently replaced with U+FFFD the moment a link in it was healed or deleted, and the text-mode round-trip also silently rewrote CRLF line endings to LF across the whole file. New `scripts/note_io.py` enforces the rule *strict UTF-8 in, byte-exact out*: `read_exact()` decodes strictly and returns `None` for non-UTF-8 files, `write_exact()` writes bytes with no newline translation (CRLF and a leading BOM now round-trip unchanged). All three rewrite sites (batch heal, loop heal, triage DELETE) skip unreadable files with a `SKIPPED (not valid UTF-8, left untouched)` line and a count in the summary; the heal loop remembers skipped files so it never retries one forever. Forgiving decode remains only in read-only paths (`line_for`, `load_verdicts`), where a lossy in-memory copy is harmless. Guarded by `tests/test_note_safety.py` (5 cases, verified to fail against the old code).
- **One dangling symlink no longer kills vault_health, heal_links, triage_links, and export_okf (stress-test fix 2/24, referee-confirmed).** `rglob("*.md")` matches names, not files: a symlink whose target was deleted (or a directory named `*.md`) still matches the pattern, so `load_vault()` crashed with an uncaught `FileNotFoundError`/`IsADirectoryError` on the read and the entire scan aborted with no report - and since heal_links and triage_links import the same loader, the repair tools died with it; export_okf's own collector had the identical hole. Both walkers now guard with `is_file()` (which follows symlinks and honestly rejects ghosts and directories) plus an `except OSError` net for races and permission errors, skipping the bad entry and scanning the rest of the vault. The guard already existed in `index_vault_files()` twenty lines above the crash site; now all walkers have it. Guarded by `tests/test_symlink_resilience.py` (4 cases, verified to fail against the old code).
- **heal_links no longer fabricates matches, and link edits never touch code (stress-test fix 3/24).** Three certainty leaks in the auto-fixer, all reproduced live in the audit: (1) `slugify()` ASCII-folded whole alphabets away, so `[[Ελλάδα]]`, `[[مرحبا]]` and `[[🚀🚀]]` all slugged to `""` and were confidently repointed to the one note whose title also folded to nothing; (2) folding deleted meaningful symbols, so `[[C++]]` slugged to `"c"` and was rewritten to point at `C.md`; (3) `_rewrite` and triage's DELETE used plain `text.replace`, editing `[[links]]` inside code fences and inline code that the wanted-link counter (which strips code, issues #82/#93) never reported - so `--dry-run` promised 2 edits and `--batch` made 3, corrupting example code. Now: `slugify()` casefolds and folds diacritics only, keeping every alphabet (`[[Привет Мир]]` heals correctly to `привет-мир.md`); an empty slug never matches; a new `slug_is_faithful()` check routes any match manufactured by deleting meaning (+, #, &, emoji, brackets) to AI triage instead of auto-fix; and a shared `vault_health.replace_outside_code()` makes both heal rewrites and triage deletes skip fenced/inline code, so dry-run and apply finally count the same edits. Bracket-containing names joined the never-auto-touch list (their capture is truncated by the link regex). Guarded by `tests/test_heal_precision.py` (6 cases, 5 verified to fail against the old code).
- **`/obsidian-init` and the Quick Start no longer point at a broken MCP install (#88, reported by @ledror).** SKILL.md's "Method A" told users to install `mcp-obsidian` via `npx -y mcp-obsidian "<vault>"` and referenced tools (`get_file_contents`, `list_files_in_vault`, `append_content`, ...) that command does not provide - it installs an unrelated third-party MCP. Meanwhile this repo ships its own MCP server (`integrations/obsidian-mcp-server/`) with entirely different tool names (`obsidian_search`, `obsidian_read_note`, ...) and launch (`uv run --with mcp python .../server.py`). Fixed by making direct filesystem access the documented default (it always works and is the real path in Claude Code), reframing the MCP server as the optional bundled one for non-Claude-Code clients with the correct setup pointer, and replacing every phantom `get_file_contents()` / `list_files_in_vault()` / `append_content()` call in the Quick Start, `/obsidian-init`, `scripts/setup.sh`, and the `_CLAUDE.md` template (SKILL.md + `commands/obsidian-init.md` + `references/claude-md-template.md`) with plain file-tool wording (`Read`, `Glob`, `Write`).
- **`vault_health.py` - links to non-markdown vault files and `.md`-extension links no longer counted as wanted notes, plus a Windows console crash fix (#87, by @FishySalmon08).** A real-vault `/obsidian-health` run surfaced two resolver blind spots left after the #82 sweep. (1) Only `.md` note stems were indexed, so links to real non-markdown vault files (`[[Bases/Tasks.base]]`, `[[map.canvas]]`, `[[control-center.html]]`) and links written with an explicit `.md` extension (`[[_CLAUDE.md]]`) were reported as wanted notes on every scan - a full-file index (`index_vault_files`, lowercased relative paths + bare filenames of every non-excluded file) now backs `check_wanted_notes`. (2) The orphan check had the mirror-image gap: an incoming link carrying the `.md` extension (`[[note.md]]`) did not count as a link to that note, so a linked note could still be flagged orphaned - the extension is now stripped before matching. Also fixed: the human-readable report crashed with `UnicodeEncodeError` on Windows consoles using a legacy codepage (cp1252 cannot encode the emoji icons) - stdout/stderr are now reconfigured with `errors="replace"` so the report degrades to replacement characters instead of crashing. Guarded by a smoke test (`test_health_resolves_asset_links_and_md_extension_links`).

### Added

- **`/youtube --visual` - Claude watches the video, not just reads the transcript.** The transcript-only path missed everything that is *shown*: on-screen code, diagrams, slides, UI, demos, b-roll. `--visual` closes that gap. It downloads the video (yt-dlp, `<=720p`) and extracts **one frame per scene change** via ffmpeg scene detection (`select='gt(scene,0.3)'`) rather than a fixed timer - so a 4-minute explainer and a 10-hour course both get keyframes at the moments that actually change, not a frame every N seconds. Static videos (screen recordings, talking heads) that yield too few scene cuts fall back to uniform sampling so you never get almost-no frames. The vision step is **Claude itself**: the new `scripts/research/lib/video_frames.py` only writes keyframe JPGs to disk and prints a `FRAMES-FOR-CLAUDE` block (each frame's timestamp + path); Claude reads the frames with its own vision (no extra vision-API call, no key beyond yt-dlp + ffmpeg on PATH) and writes a timestamp-keyed `## Visual notes` section into the saved note. Hero frames (deterministic: an opening/hook frame plus evenly-spaced picks) are copied into `Research/YouTube/attachments/<slug>/` and embedded in a `## Visual timeline`. `--max-frames N` caps how many frames Claude reads (default 24). The layer is additive and fail-soft: missing binaries or a download failure skip it with a warning and the transcript summary still saves. Frontmatter gains `visual` + `frame-count` for Dataview. **The scene-detection + download pipeline is ported (MIT) from [claude-watch](https://github.com/taoufik123-collab/claude-watch) by Taoufik, which extends [claude-video](https://github.com/bradautomates/claude-video) by Bradley Bonanno** - adapted to this skill's lib conventions and wired to Claude's own vision instead of a separate Whisper/vision backend. Verified end-to-end on a real video (download -> 12 keyframes -> hero frames in vault -> Claude read the frames and wrote the Obsidian-graph / Claude-Code-terminal / install-watch-clone-run visual notes the transcript never mentioned).

## [0.11.1] - 2026-06-28

### Added

- **Pi Coding Agent as a 6th build target (#83, by @Gepetdo).** `bash scripts/build.sh --platform pi` emits `dist/pi/`, a native [Pi](https://pi.dev) package: a `package.json` declaring `pi.prompts`/`pi.skills`, one prompt template per command under `.pi/prompts/` (invoke `/obsidian-save` etc.), and a discovery skill at `.pi/skills/obsidian-second-brain/SKILL.md` (`/skill:obsidian-second-brain`) with the AI-first rules + Python helpers alongside. Tool-name and path references are neutralized for the Pi layout (no `~/.claude/...` leakage). Purely additive - the adapter is auto-discovered by `build.sh`, so the existing five platforms are untouched; guarded by its own smoke test. Pi has no background-agent equivalent, so `/obsidian-nightly` is run manually or via cron.

## [0.11.0] - 2026-06-28 - The Retriever

### Added

- **`scripts/eval/semantic_search.py` - local, private semantic search (meaning-based retrieval) + hybrid fusion, measured before trust.** The lexical eval proved word-matching tops out at ~17% recall on paraphrased queries (questions sharing no words with the target note); only meaning-based retrieval moves that. This adds it the disciplined way: embeddings come from a LOCAL model via Ollama (`http://localhost:11434`, default `mxbai-embed-large`), so note text never leaves the machine - safe for private notes. A privacy carve-out (`OBSIDIAN_EMBED_EXCLUDE`, comma-separated path prefixes) skips configured folders entirely. The index is a cached JSON at the vault root keyed by content hash (only changed notes re-embed); cosine similarity and Reciprocal Rank Fusion are hand-rolled (no numpy/torch in the repo - the model lives in Ollama, the Python stays stdlib). `retrieval_eval.py` gains `--mode lexical|semantic|hybrid` so semantic and hybrid (lexical + semantic fused via RRF) are scored against the *same* cases as lexical - it stays default-off until the numbers justify wiring it into `vault_ops.search`. The stdlib math (cosine, RRF, carve-out) is unit-tested. Long notes are split into safe-sized chunks and mean-pooled (embedding models cap input at ~512 tokens, so a 20-page note would otherwise 500 the model), with retry + `keep_alive` for laptop stability. **Measured on the same eval cases (1,156-note local index, `mxbai-embed-large`):** on paraphrased queries (the lexical engine's weak spot) recall@10 went **17% -> 51% (semantic)**, MRR 0.06 -> 0.27; on realistic keyword queries **hybrid won outright at recall@10 91% / MRR 0.68 vs lexical's 80% / 0.66**. Conclusion: hybrid is the best all-rounder (never worse than lexical on normal queries, ~3x better on paraphrased) and is the configuration to wire into `vault_ops.search` with graceful lexical fallback when no index/Ollama is present. Honors the README's existing "run on open models / Ollama" privacy path. **Backend is pluggable** (`OBSIDIAN_EMBED_BACKEND`): `ollama` (default, local/private) or `openai` for any OpenAI-compatible `/v1/embeddings` endpoint - so users without Ollama can point at another local runtime (LM Studio, llama.cpp) or a cloud API (`OBSIDIAN_EMBED_URL` / `OBSIDIAN_EMBED_KEY`); both response shapes are parsed. `.excalidraw.md` drawings are excluded from indexing. README documents the optional setup (search works as pure keyword with zero setup).
- **`scripts/link_graph.py` - deterministic link-graph extractor, so `/obsidian-visualize` stops reading the whole vault into context.** Previously a full-vault map meant loading every note into the model just to learn what links to what (O(read-everything), budget-heavy on a 1,000+ note vault). The new scanner walks the vault once and emits JSON - `nodes` (path, title, `type`, folder, in/out/`degree`), `edges` (resolved `[[wikilink]]` pairs), and `stats` (counts, `top_hubs`, `orphans`, `dangling_link_count`) - mirroring `vault_health.py`'s link handling (code fences/inline code stripped so example links don't count; em/en-dash normalization so `[[A - B]]` resolves to `A — B.md`). `--scope "<note>"` returns that note's 2-hop neighborhood. `/obsidian-visualize` now runs it for the graph + centrality and only reads individual notes for labels the scan can't provide; Claude still does the canvas layout and interpretation. Verified on the maintainer's vault (1,180 nodes, 9,078 edges, 47 orphans). Guarded by a smoke test. Pure stdlib.
- **`/podcast` now accepts Spotify episode URLs (bridged to the public RSS feed).** Previously a Spotify link was hard-rejected ("DRM blocks audio") - a dead end for the most common way people share an episode. Spotify's own audio is still DRM-locked, but the same episode is almost always on an open feed, so the script now bridges: it reads the episode title from Spotify's key-free oEmbed endpoint, finds that episode in Apple's index (`itunes.apple.com/search`, entity `podcastEpisode`) to recover the `feedUrl`, then pulls the episode from the open RSS feed by title-match (`parse_feed`/`_pick_entry` gained an `episode_title` selector). From there the existing transcript pipeline runs unchanged (RSS `<podcast:transcript>` tag, else Whisper if `OPENAI_API_KEY`, else show-notes). Verified end-to-end on a real Spotify episode (resolved to The Joe Rogan Experience #2517 via `feeds.megaphone.fm` with audio + show notes). Spotify-exclusive shows with no public feed fail with a clear message rather than a blanket "not supported". No new dependencies or keys.
- **`/obsidian-retrieval-eval` + `scripts/eval/retrieval_eval.py` - measure vault search quality before changing it.** The top research theme from the skill audit ("retrieval quality") becomes a number. The harness reuses the REAL search engine (`integrations/obsidian-mcp-server/vault_ops.py`, the term-frequency, title-weighted ranking behind `/obsidian-find` and the MCP connector) rather than a reimplementation, and bootstraps its own eval set from the vault: it samples notes and (via `XAI_API_KEY`, with a key-free heuristic fallback) has an LLM write a natural-language question per note that deliberately avoids the note's title words, so it tests retrieval rather than string match; the note's path is the gold answer. `eval` mode scores recall@1/3/5/10 and MRR and lists the concrete failures - misses (gold never in the top 10) and buried cases (gold ranked below #3), naming which note wrongly ranked #1 so the "noisy high-mention note floats above the canonical note" pattern is visible. The command wraps it: interpret the numbers in plain language, turn failures into ranked retrieval-fix hypotheses (each re-measured on the same cases), and optionally write an AI-first baseline note. The first run on a 1,000+ note vault scored **0% recall@10 / MRR 0.000** on 35 paraphrased questions - long `raw/` transcripts and `log.md` dominate term-frequency ranking and bury short canonical notes - which quantifies the headroom and argues for cheap structural fixes (exclude `raw/`/`log.md` from search, weight by `type:`, length-normalize) measured first, before any vector index. Generated cases contain private note paths and are gitignored; `retrieval_cases.example.jsonl` ships the format. Ported in spirit from @2233admin's structured-RAG eval fork. New `scripts/eval/` with a README.
- **`/obsidian-distill` - condense one source into key claims, each tagged with provenance back to the exact block it came from.** A distillation, not a summary: it segments the source into numbered, citable blocks (`B1`, `B2`, ...), extracts the key claims, and tags each with the block(s) it came from (`(src: B3)`). A claim with no traceable source does not make the cut and is reported as dropped (never silently cut); inferences the source implies but never states go in a separate labelled section so distilled fact and reasoning never blur. Saves a `type: distillation` note (new schema in `references/ai-first-rules.md`) carrying the verbatim `source` and the numbered source blocks at the bottom, then links it from the original. This is the trust primitive for a vault more than one person reads - condensed enough to read fast, anchored enough to audit. Ported from @kubetz's fork (source-block provenance); surfaced as a top portable idea by the skill audit. Pairs with `/obsidian-ingest` and `/vault-deep-synthesis`.
- **`/obsidian-board-hygiene` - bulk-triage a kanban board whose columns have gone stale.** Where `/obsidian-board` only flags overdue items, this clears them: it reads the board, groups open items into overdue / stale (older than N days, default 14) / undated with per-column counts so the bloat is visible, proposes one verdict per stale item (done / reschedule / archive / keep) with a one-line reason as a batch the user approves or overrides, then applies the approved moves in place (additive + strikethrough, never silent deletion) and logs what moved. The board equivalent of the wanted-notes triage. Surfaced by the skill audit (a real board's "This Week" had quietly become a 51-item graveyard).
- **Hermes adapter - scheduled agents as native blueprint skills + the PostCompact-analog story (#79, Phase 2).** The four scheduled agents (`obsidian-morning` 8am, `obsidian-nightly` 10pm, `obsidian-weekly` Fri 6pm, `obsidian-health-check` Sun 9pm) are now emitted as native Hermes blueprint skills carrying `metadata.hermes.blueprint` with a cron `schedule`, `deliver: origin`, a `prompt`, and `no_agent`. They are emitted under `optional-skills/` rather than the auto-loaded `skills/` on purpose: a Hermes blueprint arms as soon as its skill loads, and the scheduled agents are opt-in by design (the Claude side ships inert and requires explicit `/schedule`), so a user must `hermes skills install <name>` to arm a schedule - preserving the trust model. None delete or archive; they only add/update/link. The lifecycle-hook piece (PostCompact analog) now ships as a real `on_session_end` Hermes hook: `hooks/obsidian-hermes-session-end.sh` (runs the nightly consolidation pass on a completed session, prints the `{}` observer-hook response, and mirrors the Claude bg-agent trust model exactly - OPT-IN, ships INERT, no-ops unless both `OBSIDIAN_VAULT_PATH` and `OBSIDIAN_HERMES_HOOK_ENABLED=1` are set, skips interrupted sessions, add/update/link only) plus `hooks/hermes-hooks.cli-config.example.yaml` (the paste-in `cli-config.yaml` registration). `dist/hermes/HOOKS.md` documents both the cron blueprints and the hook. Built to Hermes's documented `on_session_end` payload/stdout contract; the one seam that still needs a live Hermes is the headless consolidation invocation (configurable via `OBSIDIAN_HERMES_CONSOLIDATE_CMD`, default `hermes run --quiet`). Guarded by a smoke test (blueprint frontmatter, opt-in placement, hook + config presence). SKILL.md "Scheduled Agents" remains the canonical source for the prompts.
- **MCP connector - curator tools for guarded mutation, graph, and health (#79, Phase 2).** Extends `integrations/obsidian-mcp-server/` from a read + append-only connector to one that can safely curate. Four new tools (and `vault_ops.py` functions, all pure stdlib + unit-tested): `obsidian_update_note` - a deliberately conservative edit of an *existing* note (appends a section under an optional heading and/or merges scalar frontmatter via `set_fields`, preserves the rest verbatim, never creates a note, never rewrites the body, never touches list frontmatter like `tags:`, refuses paths outside the vault or in protected dirs, and stamps `updated: <today>` for provenance); `obsidian_validate_note` - checks a note against the AI-first rule (frontmatter block + `type`/`date`/`tags`/`ai-first` keys + `## For future Claude` preamble) and flags `[[wikilinks]]` whose target note does not exist; `obsidian_backlinks` - lists every note linking to a target via `[[wikilink]]` (handles aliases and folder-qualified links); and `obsidian_vault_health` - a bounded structural summary (orphans, wanted notes, notes missing frontmatter, with counts + capped samples). The mutation tool stays intentionally narrow per the #79 design note: bounded primitives, not a blind "rewrite note" call. The MCP server now exposes 10 tools. Suggested by @bkmaibach.
- **`adapters/hermes/` - native Hermes Agent skill build (#79, Phase 2).** A new adapter target that emits each command as a native [Hermes Agent](https://github.com/NousResearch/hermes-agent) skill at `skills/<category>/<name>/SKILL.md` (agentskills.io-compatible), grouped by category (vault / thinking / research / meta). Each SKILL.md carries the frontmatter Hermes needs to load it - `name`, `description` (with the command's English triggers folded in for implicit selection), `version` (read live from `pyproject.toml`), `author`, `license`, and `metadata.hermes.tags` - plus a `## When to use` preamble built from the triggers and the command body as the `## Procedure`. Skills run **in the Hermes session** via the Skills System (`/skills` or implicit match); install by copying into `~/.hermes/skills/` or adding the repo as a tap (`dist/hermes/INSTALL.md`). This is the skill/playbook half of the Hermes integration; the bounded vault-data half is the existing MCP connector. The four Claude-only calendar/scheduled commands (`obsidian-agenda`, `obsidian-calendar`, `obsidian-schedule`, `obsidian-meeting`) are excluded, matching the other non-Claude platforms (41 skills emitted). Guarded by a smoke test; `build.sh` auto-discovers the platform. Hermes-native cron and lifecycle-hook integration remain tracked in #79. Suggested by @bkmaibach.
- **`integrations/obsidian-mcp-server/` - expose the vault as an MCP server so any agent can use it as a second brain (#60).** A stdio MCP server (`server.py`, built on `FastMCP`) that gives any MCP client - Nous Research's Hermes Agent via `discover_mcp_tools()`, Claude Desktop, Claude Code, Cursor - a doorway into an Obsidian vault without touching the agent's own memory (the explicit split requested on the issue: the agent keeps its behavioral memory, the vault is its knowledge layer). Exposes six tools: **data primitives** `obsidian_search` (bounded, term-frequency, title-weighted), `obsidian_read_note` (path-escape-guarded), `obsidian_save_note` and `obsidian_capture` (both write AI-first notes to `Inbox/` with frontmatter + a `## For future Claude` preamble + a `source: mcp` marker so connector-added notes are distinguishable); and **skill tools** `obsidian_list_skills` + `obsidian_get_skill`, which return the command playbooks (34 exposed; niche/agent-only ones - health, challenge, calendar commands, create-command, init/export/visualize - excluded) so the agent runs the real multi-step skill (ingest, idea-discovery, find) with its own model, using the data primitives for the actual reads/writes rather than flattening ingest into a single call. The logic lives in a dependency-free `vault_ops.py` (pure stdlib, unit-tested); `server.py` is a thin MCP layer over it. Ships a `README.md` (setup + sample MCP config block) and `live_test.py`, which drives the server with a real MCP client over stdio (handshake + tool discovery + read-only round-trip, optional `--save`) to prove the protocol path without needing Hermes installed. Configured via `OBSIDIAN_VAULT_PATH` (and optional `OBSIDIAN_COMMANDS_DIR`). Verified end-to-end against a 1,000+ note vault; three smoke tests lock the save/read/search round-trip, the path-escape guard, and the skill-exclusion contract.
- **Telegram journal bot - local / self-hosted voice transcription, no API key (#75).** The bot's voice path now supports a fully on-box backend alongside the OpenAI Whisper API default. Set `TRANSCRIBE_BACKEND=local` and voice notes are transcribed with the `openai-whisper` CLI on your own machine - the same engine `/obsidian-ingest` already uses for audio - so nothing leaves the box and no `OPENAI_API_KEY` is needed. `WHISPER_LOCAL_MODEL` picks the model size (`tiny`|`base`|`small`|`medium`|`large`, default `base`); `WHISPER_BIN` points at the whisper binary if it is not on the poller's PATH (common under launchd/cron); `WHISPER_HINT` still biases proper-noun spelling (passed as Whisper's `--initial_prompt`). A missing binary returns a clear "pip install openai-whisper" error rather than a stack trace. `setup.sh` now asks whether to transcribe locally and only prompts for the OpenAI key when you keep the API backend; the OpenAI key is documented as optional in the env template. README gains a "Local transcription" section (install of `openai-whisper` + ffmpeg, model-size guidance, CPU-only notes). OpenAI stays the default - this is opt-in. Verified end-to-end against a real `.oga` voice note. Requested by @addisonlynch.
- **`integrations/telegram-journal/setup.sh` - one-command installer for the journal bot.** Prompts for the config values (bot token, OpenAI + Anthropic keys, vault path, optional owner / Whisper hints / skill-repo path), writes the locked `~/.config/obsidian-second-brain/telegram_journal.env` (chmod 600), does a test run, then installs + loads the background poller (launchd on macOS via the bundled plist template, or prints the cron line on Linux). Re-runnable - skips an existing config. README points at it as the fast path; manual steps remain for those who prefer.
- **`/obsidian-catchup` - process what the Telegram bot captured on the go.** The laptop-side companion to the journal integration. The bot now also appends every capture (voice/text/image/PDF/link) to a `catchup.md` queue in the vault as an unchecked `- [ ] date time | kind | summary | -> where` line; this command pulls the unchecked items (filter `today` / `week` / `all`), groups them by age (flagging stale ones - a walk idea that mattered then may be dead now), and processes them WITH the user: integrate into the right note per the AI-first rule, keep as-is, or discard - then checks each off (`- [x]` + processed date) without deleting queue history. Pull, not push: nothing is processed autonomously, so there is no "which conversation did it notify" problem - you run it when you are back at the laptop. The split it enforces: phone = fast dumb capture, laptop = think + integrate; same brain, two speeds, not two silos. Plain-English triggers (`what did I dump from telegram`, `process my captures`, `catch up`) route here. Pairs with the journal bot's new fill-links behavior (it never leaves an empty `[[link]]` - it creates the note, filled).
- **Telegram journal integration (`integrations/telegram-journal/`) - capture into the vault from your phone, hands-free.** A small background poller (macOS launchd or Linux cron, ~60s) that turns Telegram messages into AI-first vault entries. **Voice / audio** is transcribed with OpenAI Whisper then tidied by Claude; **text** is tidied by Claude; both append to today's daily note under `## Voice journal`. **Images** are read by Claude vision, which writes a 1-2 sentence description (notable people/companies wrapped as `[[wikilinks]]`) plus any text extracted from the image, saves the file to `wiki/attachments/`, embeds it, and routes the entry to an existing person/project/finance note or today's note - reply `move <where>` to re-file the last image. **PDFs** are read by Claude into a literature note in `Research/Papers/` (summary, key points, embedded file, linked from the daily note); **links** (YouTube / X / article) are dispatched to the matching `/youtube`, `/x-read`, or `/research` command, which saves its own AI-first note. A **fill-links** step means any `[[person/company/project]]` the bot references gets a real *filled* note created (typed + filed; unknowns marked TBD, nothing fabricated) instead of an empty link - it only ever creates new notes. Whisper transcription can be biased toward your proper nouns via `WHISPER_HINT`. Read-only on messages, write-only to the vault (nothing deleted); if the machine is offline, Telegram holds the message (~24h) and it is processed on the next run. All secrets live in a chmod-600 config file outside the repo (`~/.config/obsidian-second-brain/telegram_journal.env`); the script itself carries none. Ships `telegram_journal.py`, a `README.md`, `telegram_journal.env.example`, a launchd plist template, and a `.gitignore` that blocks the filled-in config. Requires OpenAI + Anthropic API keys and a @BotFather bot token; owner name is configurable via `VAULT_OWNER`.
- **`/obsidian-export okf` - emit an OKF (Open Knowledge Format) bundle.** Adds an `okf` format to `/obsidian-export`, backed by a deterministic `scripts/export_okf.py` (stdlib + PyYAML via inline deps). It reads the vault and writes an OKF v0.1 bundle to `_export/okf/`: each note becomes an OKF concept doc with frontmatter mapped to OKF fields (`type` [required], `title`, `description` [plain-text, link-free, word-trimmed], `resource` [only when the note carries a real source URL: `resource`/`url`/`source_url`/`post-url`/`repo`/`linkedin`], `tags`, ISO-8601 `timestamp` from `date`/`time` or file mtime), `[[wikilinks]]` rewritten to relative-path markdown links (cross-folder paths computed; unresolved links degrade to plain text; embeds and paths-with-spaces wrapped CommonMark-safe), plus a generated `index.md` (progressive disclosure, grouped by folder) and a copied `log.md`. The vault's richer AI-first body (incl. the `## For future Claude` preamble, confidence/recency markers) is preserved verbatim - OKF is minimally opinionated, so the extra content rides along, and the vault stays a superset. Makes obsidian-second-brain "OKF v0.1 compatible" (interop with Google Cloud's vendor-neutral folders-of-markdown standard, as of 2026-06) without changing how the vault works natively. Verified against a 1,032-note vault. (Folder-native AI alignment: OKF = the knowledge layer.)
- **"Run on Hermes / open models" documentation.** The skill is already model-agnostic - the OpenCode, Codex, and Gemini builds are plain instruction files that run on whatever model the host CLI is pointed at - so this adds the missing docs rather than new code. README gains a "Run on Hermes / open models" install subsection (OpenCode + OpenRouter `opencode.json` config, the current Nous Research Hermes model ids and pricing as of 2026-06, a free-trial model, and a local-via-Ollama privacy path) plus an FAQ entry, and the OpenCode build's generated `INSTALL.md` (`adapters/opencode/adapter.sh`) gains a matching short note. Framing is honest, not parity: core commands (`/obsidian-save`, `/obsidian-daily`, `/obsidian-capture`, `/obsidian-find`, `/obsidian-task`, free-mode `/research`) hold up well on open models; the sub-agent-heavy and deep-synthesis commands (`/obsidian-architect`, `/obsidian-reconcile`, `/research-deep`) prefer a stronger instruction-follower like `hermes-4-405b` or Claude. Phase 0 of the Hermes work (Issue #60); the model-swap half requested on X.
- **`/obsidian-projects` - live project status from git + local docs.** Reads `_CLAUDE.md` for the projects folder path, scans it for notes with `type: project` or a `repo:` field, and spawns a parallel subagent per project that checks the vault note, runs `git log` / `git status` (if a `repo:` path is set), and reads `NOTES.md` / `TODO.md` in the repo root. Merges the three into one status block (active / stalled / idle / blocked / archived inferred from activity recency), prints the full overview to the conversation ordered active-first, and injects a `## Last overview` section into each project note. An optional argument narrows the run to one named project. No central config block required - repo path lives in each note's `repo:` field, folder path comes from `_CLAUDE.md`. Four `.base` templates added to `references/bases/` (projects, people, tasks, daily) with `{{FOLDER}}` placeholders; `/obsidian-init` and `bootstrap_vault.py` stamp the correct paths at vault creation time and never touch the files again.
- **`update.sh` - one-shot command refresh.** Pulls the latest changes from git and, on Windows, re-copies the command files (since symlinks are unavailable). On Linux/macOS, `git pull` is sufficient because commands are symlinked; `update.sh` there does only the pull.

### Changed

- **`vault_ops.search` (the `/obsidian-find` + MCP engine) now fuses lexical with local semantic search when available - opt-in by setup, with silent lexical fallback.** Productizes the measured win: if a semantic index exists at the vault root (built with `scripts/eval/semantic_search.py --build`) AND a local Ollama model is reachable, query results become the Reciprocal-Rank-Fusion of keyword and meaning rankings (measured best all-rounder: keyword recall@10 80% -> 91%, paraphrased 17% -> ~46%). If there is no index, Ollama is down, the call times out, or anything errors, it silently returns pure lexical - search never breaks or hangs (10s query-timeout, no retries at query time). Self-contained in `vault_ops.py` (the MCP connector ships it standalone): query embedding via urllib, hand-rolled cosine + RRF, all stdlib. Kill-switch `OBSIDIAN_SEARCH_SEMANTIC=0`. Honest caveat from live testing: terse fact-dump notes (e.g. a `CRITICAL_FACTS` file) can still rank poorly even semantically - the gain is statistical, not per-query magic. Fusion + fallback guarded by a smoke test. `.excalidraw.md` drawings are excluded from indexing (raw JSON, not prose).
- **`/obsidian-save` now writes the dev-log too, so it absorbs `/obsidian-log` (skill-audit; non-breaking).** Mid-session the two overlapped - a full save captured the work but not as the dev-log artifact `/obsidian-log` produces, so users ran both. The save flow's Projects agent now also writes (or updates) a `wiki/logs/` dev-log note when the conversation was a substantial dev/work session, and links it from the project's Recent Activity and the daily note. `/obsidian-log` stays as the standalone quick-log; `/obsidian-save` is now its superset.
- **`/obsidian-adr` is folded into `/obsidian-decide --formal` (skill-audit consolidation; breaking).** Both commands recorded decisions - `/obsidian-decide` logged dated one-liners to project `## Key Decisions` sections, `/obsidian-adr` wrote a full Architecture Decision Record. They are now one command at two depths: default stays the lightweight log; `--formal` (or leading with `adr`) writes the full record (Decision / Context / Options / Rationale / Consequences / Related) to the decisions folder resolved via `references/folder-map.md`, links it from the project and `index.md`, and logs it. All of the old `/obsidian-adr` triggers ("ADR", "record decision", "decision record") fold into `/obsidian-decide`'s `triggers_en`, and the `mine_commit_decisions.py` integration plus the offer-to-record hooks in `/obsidian-graduate` and `/obsidian-health` are preserved. **Breaking for the `/obsidian-adr` slash form** - use `/obsidian-decide --formal`. Command count 45 -> 44.
- **The four calendar commands are merged into one `/obsidian-calendar <mode>` (skill-audit consolidation; breaking).** `/obsidian-agenda`, `/obsidian-meeting`, `/obsidian-schedule`, and the old `/obsidian-calendar` reconcile command were four separate slash commands for one subsystem; they are now four modes of a single command - `agenda` (read a snapshot), `reconcile` (flag vault commitments not on the calendar), `meeting` (event to note), `schedule` (create/move an event). The first argument word selects the mode; a bare range word defaults to `agenda`; no argument defaults to `agenda today`. Every behavior, frontmatter schema (`agenda-snapshot`, `meeting`), MCP-tool requirement, conflict-check, reschedule-not-duplicate rule, and anti-fabrication guard is preserved verbatim as a mode, and all of the four commands' natural-language triggers are folded into the unified command's `triggers_en`, so "check my calendar", "log this meeting", "schedule this task", etc. still route correctly. **Breaking for anyone typing the old slash forms** (`/obsidian-meeting ...` etc.) - use `/obsidian-calendar meeting ...`. Still Claude-Code-only (needs the Google Calendar MCP); command count 48 -> 45. Surfaced by the 45-command real-vault audit as the strongest merge (one subsystem, one command).
- **`/research-deep` no longer fabricates vault paths during propagation (correctness fix).** The synthesis LLM was told to cite vault references with "the exact path", but it only knows the baseline notes it was handed - so for any other note it invented confident-looking paths (e.g. `[[Systems/Obsidian Second Brain]]`), and propagation could then create a file at that made-up path. Two-part fix: (1) the synthesis prompt now permits a `[[path]]` wikilink ONLY for a path present in the vault baseline and requires new notes to be named by title and marked "(new note)" rather than linked; (2) the propagation step (in the command and in both JSON payload instructions) now requires grounding every target before writing - search the vault for the note and update the real one found, and only create a new note (folder resolved via `references/folder-map.md`) when an exhaustive search finds none. A path appearing in the synthesis is explicitly declared insufficient evidence that the note exists, and any bullet that cannot be grounded is reported rather than silently written or dropped. Brings `/research-deep` in line with `/notebooklm`'s grounded behavior.
- **MCP / `/obsidian-find` search ranking - sublinear TF + length normalization (the biggest win; recall@1 2.9% -> 57%).** Stacked on the stopword/de-weight fix below. The remaining failure was that long meeting notes still beat a short note with the term in its TITLE, because raw body counts reward length. `vault_ops.search` now saturates repeated mentions with `log1p` (a term repeated 50x no longer scores 50x) and divides the body contribution by a length factor so long notes cannot win on sheer volume, while title matches stay a strong length-independent signal (BM25 in spirit). Env-toggle `OBSIDIAN_SEARCH_LENGTHNORM=0` restores raw counts for A/B. Re-measured on the same keyword cases: recall@1 2.9% -> 57.1%, recall@3 20% -> 74.3%, recall@10 42.9% -> 80%, MRR 0.135 -> 0.656 - realistic queries now return the right note as the #1 result more than half the time. Cumulative across all three ranking fixes: keyword recall@10 5.7% -> 80%, MRR 0.007 -> 0.656, zero new dependencies. Locked with a ranking regression test in `tests/test_smoke.py` (short title-matching note must outrank a long noisy one). The adversarial title-word-free eval set held at ~17%, which is the genuine, now-quantified case for semantic/embedding retrieval as the next step.
- **MCP / `/obsidian-find` search ranking - stopword filtering + raw-source de-weighting (measured 7x recall gain).** Driven by the new retrieval eval: the shipped `vault_ops.search` had two ranking bugs the harness exposed. (1) **No stopword filtering** - a query like "what is the status of the PROJ-412 alpha to beta migration" kept `the / what / status`, which recur thousands of times in long notes, so ten meeting notes outranked the note literally titled "PROJ-412 - Alpha to Beta". `search()` now drops ~120 English function words from the query terms before scoring (with a fallback so an all-stopword query still returns something). (2) **`raw/` transcripts and `log.md` dominance** - long immutable sources and the operation log outscored canonical notes on raw term frequency; they are now de-weighted (`_SEARCH_DEWEIGHT_FACTOR`, env-tunable via `OBSIDIAN_SEARCH_DEWEIGHT=1.0` to disable for A/B) so they stay findable but cannot bury a real wiki note. Re-measured on the same 35 cases: keyword recall@10 went 5.7% -> 42.9%, recall@3 0% -> 20%, MRR 0.007 -> 0.135; the adversarial title-word-free set went 0% -> 17.1% recall@10. Stopwords did most of the work; de-weighting added ~6 points. The eval harness gained a `--style keyword|semantic` flag to track both the realistic and the adversarial case. No new dependencies; `_iter_notes` (and thus backlinks/health) is untouched - the change is scoped to search ranking only.
- **Folder resolution is now spec-driven, not hardcoded (skill-audit finding).** Eleven commands had Obsidian-style folder names baked into their bodies (`Ideas/`, `Dev Logs/`, `Reviews/`, `Knowledge/`, `Projects/`) with no instruction to honor the vault's actual layout, so on a wiki-style vault (`wiki/concepts/`, `wiki/logs/`, `wiki/reviews/`, `wiki/decisions/`, `wiki/projects/`) they could write to the wrong folder or create junk directories. New canonical spec `references/folder-map.md` defines the note-type to folder resolution (read the vault's `_CLAUDE.md` Folder Map first, fall back to wiki-style defaults, then Obsidian-style aliases, never invent a third name). `/obsidian-capture`, `/obsidian-log`, `/obsidian-review`, `/obsidian-adr`, `/obsidian-graduate`, `/idea-discovery`, `/obsidian-connect`, `/obsidian-emerge`, `/obsidian-world`, `/obsidian-health`, `/obsidian-projects`, and `/vault-deep-synthesis` now resolve their folders through it. Surfaced by the 45-command real-vault audit; the single highest-leverage fix (one spec, ~10 commands corrected).
- **`vault_health.py`: "broken links" renamed to "wanted notes" and downgraded from warning to info.** The label was inherited from the web, where a broken link is a real 404. In a wiki-style vault a link to a not-yet-written note is intentional - you link a thing the moment you mention it - so the old name (and its alarm-colored severity) badly misrepresented a healthy demand-ranked wishlist of notes worth writing. Renamed after MediaWiki's "Wanted pages": the issue `type` is now `wanted_note`, the count category is `Wanted notes`, severity is `info`, and the message reads `[[X]] - wanted by <note>`. `/obsidian-health` (`commands/obsidian-health.md`) updated to match - wanted notes are listed under info with explicit "not errors, a wishlist" framing, and the triage step now says the goal is to triage the backlog (keep/create/delete), never to drive the count to zero. Tests updated. The MCP connector's `obsidian_vault_health` was renamed to match (its `broken_links` result key is now `wanted_notes`).
- **Codex CLI adapter now emits native Codex Agent Skills instead of an AGENTS.md routing table plus `codex exec` wrappers (#78).** Codex shipped native [Agent Skills](https://developers.openai.com/codex/skills) in Dec 2025 with progressive disclosure, so the prior design (a giant natural-language routing table in `AGENTS.md` plus per-command shell shims delegating to `codex exec`) was both outdated and a regression: it had no session continuity, no native `/skills` discovery, ambiguous write permissions, harder-to-debug failures, and paid full startup/context overhead on every command. The adapter (`adapters/codex-cli/adapter.sh`) now emits one native skill per command under `.agents/skills/<name>/SKILL.md` (`name` + `description` frontmatter, with the command's English triggers folded into the description for implicit selection, body tool-neutralized and path-rewritten). Skills run **in the current session** - invoked via `$<name>`, `/skills`, or implicit description match - so writes honor the session's approval/sandbox mode. `AGENTS.md` is now a thin always-on manual (vault conventions + the AI-first rule); the skill list is the router, so there is no routing table to maintain. Shared specs stay under `.codex/references/` and Python helpers under `.codex/scripts/`. README and the generated `INSTALL.md` updated; the old "Codex has no native slash-command runtime" claim is removed. The `scripts/install-codex-wrappers.sh` / `run-command.sh` path remains for non-interactive `codex exec` scripting but is no longer the recommended install. Reported by @manfredlift.
- **`install.sh` - symlink commands everywhere possible, copy as fallback.** Slash commands in `~/.claude/commands/` are now symlinked to the source repo so `git pull` keeps them current automatically. On Windows (MSYS2/Git Bash) native symlinks are attempted first (requires Developer Mode); if that fails the installer falls back to copying and prints a one-time notice. The same try-then-fallback logic was already used for the skill directory link and is now unified under a single `IS_WINDOWS` check. `vault_stats.py` `--vault` flag is now optional when `OBSIDIAN_VAULT` is set in the environment.
- **SEO / AEO / GEO / LLM refresh - every discoverability surface brought current with v0.10.0 (43 commands, The Architect).** The JSON-LD `SoftwareApplication` description now leads with `/obsidian-architect` + key-less research and gained `featureList` and `releaseNotes`. Added a **`FAQPage` JSON-LD** (six Q&As incl. "Can it document my codebase?") so answer engines / AI Overviews can extract and cite. `_config.yml` Pages description 34 -> 43 and re-pointed at the architect angle. `llms.txt`: intro now surfaces `/obsidian-architect` and key-less research, and the release history is completed (v0.8.0, v0.9.0, v0.10.0). README gained FAQs on documenting a codebase and the refresh-safe sentinel behavior. GitHub About description and the bug-report version placeholder refreshed. (The `examples/sample-vault/` "v0.9.0" mentions are a fictional sample app, intentionally left.)

### Fixed

- **Restored the em/en-dash literals the non-ASCII sweep destroyed in `vault_health.py` and `notebooklm.py` (#63).** PR #44's `sweep_non_ascii.py --apply` rewrote every banned character in `.py`/`.sh` files, including two `str.replace()` *operands* that were intentional: `_normalize_dashes()` in `scripts/vault_health.py` became `s.replace("-", "-")` (a no-op, silently re-breaking the #31 behavior where a hyphen-written wikilink resolves against an em-dash filename), and `safe_display_name()` in `scripts/research/notebooklm.py` started replacing every ASCII hyphen with a spaced hyphen, garbling File Search display names. Both now build the dash characters from `\u2014`/`\u2013` escape sequences (the same pattern `tests/test_smoke.py` already used), so the source stays ASCII, the CI gate passes, and a future sweep cannot rewrite the logic again. A regression test (`test_health_normalizes_dashes_in_links`) locks the link-normalization behavior. Reported with repro + fix by @dzukauskas.
- **Code-fence-wrapped notes no longer misreported as "missing frontmatter" (and no longer "fixed" into duplicate frontmatter).** When a note's whole body was accidentally saved inside a leading ```` ```markdown ```` fence, its real frontmatter is trapped in the fence, so `vault_health.py`'s `^---` match failed and the note was flagged as missing frontmatter. `/obsidian-health` then "fixed" it by *prepending* a new frontmatter block, producing duplicate frontmatter with the body still trapped (double corruption). `vault_health.py` now detects this as a distinct `code_fence_wrapped` issue (severity error) via `CODE_FENCE_WRAP_RE`, excludes it from the missing-frontmatter check, and `commands/obsidian-health.md` instructs the Frontmatter agent to **unwrap** such notes (strip the fence, merge any duplicate prepended block) rather than add frontmatter. Unit-tested against both fence variants plus legit notes with body code blocks (no false positives). Surfaced by a real `/obsidian-health` run that left three entity notes with duplicate frontmatter.
- **`vault_health.py --json` output is now machine-clean.** The progress lines ("Scanning vault", "Found N notes") now print to stderr instead of stdout, so `--json` emits a single parseable JSON document on stdout (the `/obsidian-health` command parses it directly).

## [0.10.0] - 2026-05-31 - The Architect

### Added

- **`/obsidian-architect` - scan a codebase into maintained architecture notes.** A deterministic scanner (`scripts/architect_scan.py`, stdlib-only) reports the stack, proposed modules, dependencies, entry points, and git commit; Claude then synthesizes an overview (with a Mermaid diagram and inferred personas), one note per core module, and a key-decisions note (fed by `mine_commit_decisions.py`), written under `Projects/<name>/Architecture/` as AI-first notes (`type: architecture-overview` + `type: architecture-module`). Re-running refreshes in place via **sentinel markers** (`<!-- @generated -->` / `<!-- @user -->`) that update only generated blocks and never overwrite hand-edits - a reusable write primitive now documented in `references/write-rules.md`. A lean v1 (one scanner + one command, not the source fork's 27-module suite). For the builder-heavy audience: code projects documented in the same brain as ideas and decisions. (FORK_INSIGHTS.md #20, #21, #22, #25.)
- **Codex executable invocation path.** `scripts/run-command.sh` wraps any command's markdown into a `codex exec` prompt so the (otherwise inert) command files actually run on Codex CLI, and `scripts/install-codex-wrappers.sh` installs one PATH shim per command into `~/.codex/bin/`. A `--print` mode prints the assembled prompt without running, for preview/testing. Fixes two bugs from the source fork (a self-referential vault default and an `eval echo` tilde-expansion that mis-parses paths with apostrophes). (FORK_INSIGHTS.md #42; from the Codex-runner fork)
- **`scripts/mine_commit_decisions.py`** surfaces decision-shaped commits (switch to / replace / adopt / rename / migrate, etc.) from a git history as ADR candidates, so directional decisions made in code but never recorded can be written up via `/obsidian-adr` (which now references it). Conservative matcher (low false positives); read-only. (FORK_INSIGHTS.md #22)
- **Four more commands.** `/obsidian-calendar` (Claude Code only) reconciles the vault against your calendar and flags commitments implied by notes that are not scheduled - flag only, never writes events (the inverse of `/obsidian-daily`'s calendar pull). `/vault-deep-synthesis [topic]` cross-references every note on a topic into agreements / contradictions / stale claims / coverage gaps (pure vault; topic-driven, distinct from the unprompted `/obsidian-synthesize`). `/idea-discovery` ranks 3-5 next-direction candidates from ungraduated ideas, open project questions, and orphan research. `/obsidian-panel` convenes a panel of distinct lenses on a decision (uses an optional `Advisors/` folder, else four generic lenses), a multi-persona complement to `/obsidian-challenge`. The three thinking commands reuse the existing `type: synthesis` schema. (FORK_INSIGHTS.md #11-14.)
- **CI gate for substitution characters.** `scripts/sweep_non_ascii.py` gained a `--check` mode that exits non-zero when a banned substitution character (em-dash, en-dash, curly quotes, Unicode math, ellipsis, non-breaking space) appears in prose in any tracked `.md`/`.py`/`.sh` file. Characters inside code fences and inline backtick spans are preserved and never fail the check. Wired into `.github/workflows/ci.yml` so the rule is enforced on every push and PR (complements the write-time `validate-ai-first.sh` hook, which only covers vault notes). Two new smoke tests lock the behavior. (FORK_INSIGHTS.md #49; pattern from the calendar/workflow fork, generalized to the full banned-character set.)

## [0.9.0] - 2026-05-31

### Changed

- **Background agent (PostCompact hook) is now opt-in and ships inert.** It writes to the vault unattended with `--dangerously-skip-permissions`, but previously armed on `OBSIDIAN_VAULT_PATH` alone (which `setup.sh` sets for the research toolkit), so a normal install left it firing on every compaction. It now also requires a second deliberate flag, `OBSIDIAN_BG_AGENT_ENABLED=1`, which `setup.sh` never sets - so it stays inert until the user enables it, and clearing the flag is enough to disable it again. `setup.sh` now reports the hook as "registered (inert by default)" with enable instructions. (FORK_INSIGHTS.md #32)
- **Non-ASCII substitution sweep across all tracked `.md`, `.py`, `.sh` files:** automated conversion of em-dashes, en-dashes, curly/smart quotes, Unicode math substitutions, ellipsis, and non-breaking spaces to ASCII equivalents. Code fences and inline backtick spans preserved verbatim. `hooks/validate-ai-first.sh` and `scripts/sweep_non_ascii.py` exempted (intentional banned chars in detection logic). `README.md` handled separately with a manual pass. All 78 affected files now pass `validate-ai-first.sh` check 5.

### Added

- **`/obsidian-recurring` - track a recurring obligation with a cadence and a computed next-due date.** Builds a `type: recurring-task` note (What / Cadence / Blockers / History), adds a board card for the next occurrence, and advances `next-due` on each completion. Fills the gap that `/obsidian-task` (one-shot) leaves. Adds the `recurring-task` schema to `references/ai-first-rules.md`. (FORK_INSIGHTS.md #15; from the calendar/workflow fork. The other workflow commands in that fork - proposal, event, 1on1, launch-block - were intentionally left to domain forks per ECOSYSTEM.md rather than added upstream.)
- **Google Calendar commands: `/obsidian-agenda`, `/obsidian-schedule`, `/obsidian-meeting`.** Claude Code only (they use the claude.ai Google Calendar MCP connector, so they are excluded from the Codex/Gemini/OpenCode builds). `/obsidian-agenda` writes a re-derivable `agenda-snapshot` note for a range (today/tomorrow/week/next-week/date/range) with conflict, back-to-back, focus-block, and external-organizer detection, cross-linking attendees to person notes. `/obsidian-schedule` creates or reschedules events from a task or standalone, resolving attendee emails from person notes (never guessing) and writing the event id/url back to the task. `/obsidian-meeting` generates a `meeting` note from an event with empty Notes/Decisions/Action-items sections (never fabricated). Adds `agenda-snapshot` and `meeting` schemas to `references/ai-first-rules.md`. (FORK_INSIGHTS.md #8-11; from the calendar/workflow fork)
- **Free (key-less) mode for `/research` and `/research-deep`.** Both commands now work with no API keys. Mode is auto-selected: when `PERPLEXITY_API_KEY` is set they use Perplexity/Grok exactly as before; when it is not (or `--free` is passed) they aggregate free, key-less sources in parallel - Wikipedia, HackerNews, arXiv, Reddit, Lobsters, dev.to, OpenAlex, Semantic Scholar, CrossRef, DuckDuckGo (SearXNG fallback) - and emit JSON that the calling Claude synthesizes into the same AI-first dossier. `--academic` restricts free mode to scholarly sources. New `scripts/research/lib/` layer: 11 source clients, a parallel aggregator (30s timeout, "success" at >= 3 sources, never crashes on a per-source failure), a 24h-TTL cache, a shared polite-UA session, and an env-based `source_config` deliberately decoupled from the vault path so the sources import with no vault and no keys. Previously these commands hard-errored without a Perplexity key - the main adoption barrier. 6 new no-network unit tests; CI installs `requests`. (FORK_INSIGHTS.md #1-6; from the research-toolkit fork)
- **Anti-fabrication and search-completeness guards.** Adds a non-negotiable hard-rules section to `references/ai-first-rules.md` covering three failure modes: false absence (never claim a note/person/file is absent without an exhaustive search - the single most common observed failure), search completeness (enumerate exhaustively, do not sample), and no fabrication (never invent facts/entities/dates; mark unknowns `TBD`; an empty section is correct when nothing was said). Echoed in the SKILL.md operating principles and `references/write-rules.md`, plus a per-command **Anti-fabrication** footer on the 33 commands that write vault notes (`create-command` excepted - it writes command files, not notes). Fills a real gap: the repo had an AI-first write spec but no hallucination guard. (FORK_INSIGHTS.md #26-28; from the pillar-vault fork)
- **First automated tests + CI.** `tests/test_smoke.py` adds two stdlib-only smoke tests (the codex-cli adapter build emits `AGENTS.md` plus command bodies; `vault_health.py --json` reports a clean two-note linked vault) and `.github/workflows/ci.yml` runs them on every push to `main` and every PR. Adds a pytest `dev` dependency group to `pyproject.toml`. Closes the long-standing "no automated test suite yet" gap. (FORK_INSIGHTS.md #47, #48; pattern from the tests fork)
- **`hooks/obsidian-bg-agent.hook.yaml` and `hooks/postcompact.hook.example.json`:** the background agent now ships with an `enabled: false` hook declaration and a paste-in settings template documenting the opt-in steps. (FORK_INSIGHTS.md #33)
- **`references/DELTAS.template.md`:** a fork-customization template. Forkers copy it to `DELTAS.md` at their fork root to record local deviations in one place that upstream never touches, so `git merge upstream/main` stays conflict-free. Pointer added to the README fork section. (FORK_INSIGHTS.md #50; pattern from the DELTAS fork)
- **Non-ASCII substitution character check in `validate-ai-first.sh` (check 5):** the hook now detects banned Unicode that slips in silently via LLM defaults: em-dashes (`—`), en-dashes (`–`), curly/smart quotes, Unicode math substitutions (`≥ ≤ ≠`), ellipsis (`…`), and non-breaking spaces. Each violation reports the exact codepoint, line number, and a suggested ASCII replacement. Whitelist covers box-drawing chars (U+2500-257F), arrows (`→ ←`), currency symbols (`€ £ ¥`), private-use / Nerd Font codepoints, and emoji - all carry semantic meaning rather than substituting for ASCII. Specific em-dash ban was unenforceable in practice; the broader codepoint-level check catches the full substitution-Unicode class. Rule documented in `CLAUDE.md` conventions and `references/ai-first-rules.md` anti-patterns table.

### Documentation

- **`claude -p` slash-command-expansion gotcha documented in `SKILL.md`.** Custom slash commands do not expand in non-interactive mode, so a cron/launchd job running `claude -p "/obsidian-daily"` sends the literal text and does nothing. Documents the reliable headless pattern (point Claude at the command file and tell it to carry out the steps) plus the launchd `PATH` caveat. (FORK_INSIGHTS.md #34)
- **Per-project vault setup documented** (closes question in Discussion #11): added a "Per-Project Vaults (multi-repo workflows)" section to `SKILL.md` and a matching FAQ entry in `README.md`. Recipe: drop `{"env": {"OBSIDIAN_VAULT_PATH": "..."}}` into each repo's `.claude/settings.json`; Claude Code's per-project settings merge over the global one and every hook reads `OBSIDIAN_VAULT_PATH` from env at fire-time, so each project session routes to its own vault. The pattern always worked; nobody had written down the recipe.

### Fixed

- **Dead calendar tool reference in `/obsidian-daily`.** The calendar pull referenced a bare `google_calendar_list_events`, which can never match a tool (MCP tools are namespaced `mcp__<server>__<name>`), so the `## Calendar` section was effectively never populated. Now points at the real claude.ai Google Calendar connector tools (`list_calendars` + `list_events`), resolves the primary calendar first, and keeps a fallback note for users whose calendar MCP namespaces differently. (FORK_INSIGHTS.md #7; bug surfaced by the calendar/workflow fork)
- **Removed remaining `--style obsidian` example from `SKILL.md`.** Issue #15 dropped the unimplemented `--style` example from the README but left the matching one in `SKILL.md`; this finishes that cleanup so the docs no longer advertise a flag `bootstrap_vault.py` does not accept.
- **`bootstrap_vault.py` templates now AI-first compliant (#16):** all 17 templates emitted by the bootstrapper (`Daily Note`, `Project`, `Person`, `Task`, `Dev Log`, `Goal`, `Mention`, `Meeting`, `Decision`, `OKR`, `Architecture`, `Debug`, `Post`, `Audience Note`, `Source`, `Literature Note`, `Hypothesis`) now include `type:` and `ai-first: true` in frontmatter plus a `## For future Claude` preamble in the body. Notes created from these templates now pass `hooks/validate-ai-first.sh` cleanly. Previously every Write/Edit on a templated note warned, undermining the AI-first rule the skill is built around. `Templates/Source.md` renamed its existing `type:` field to `source_kind:` to free up `type:` for the ai-first frontmatter (the field was for book/paper/podcast/video, never the note's ai-first type). Added a `references/ai-first-rules.md` reference block to the top of `bootstrap_vault.py` so future contributors see the rule.
- **Removed broken `--style obsidian` example from README (#15):** the `scripts/bootstrap_vault.py --style obsidian` example in the Vault Architecture section advertised a flag that was never implemented. PR #14 wired `--preset` and `--mode` but not `--style`. Dropped the stale example per the issue's recommended Option B. If a `--style` flag ships later it gets re-added then.
- **README command count refreshed to 34:** banner alt text, tagline, anchor, and `## 34 Commands` heading now match the actual file count after PR #7 landed `/podcast`.
- **`install.sh` cross-platform editor and uv-install hint:** the `${EDITOR:-open}` fallback was macOS-only - on Linux it threw `open: command not found`, on Windows (Git Bash) likewise. Now picks `xdg-open` on Linux, `notepad` on Windows (MSYS/MINGW/Cygwin), `open` on macOS. The "uv not found" hint also branches per platform: `brew install uv` on macOS, `curl … | sh` on Linux, the PowerShell one-liner on Windows. Matches the same pattern PR #34 applied to `scripts/research/lib/vault.py`.

### Added

- **`/podcast [url]` - new research-toolkit command.** Accepts Apple Podcasts URLs (resolved to RSS via the free iTunes Lookup API, no key) or RSS feed URLs directly. Transcript priority: `<podcast:transcript>` tag in the RSS feed (free, high fidelity) → Whisper API if `OPENAI_API_KEY` is set (~$0.006/min) → show-notes fallback. Summarizes via Grok and saves an AI-first note to `Research/Podcasts/`. Adds `type: podcast` schema to `references/ai-first-rules.md`. Spotify URLs are rejected with a clear message (DRM blocks audio + transcript access). Wikilinks mandated for show/host/guests; all diagnostic output routed to stderr so it never contaminates the Grok prompt or vault note body.
- **Centrality ranking in `/obsidian-visualize`:** the text summary now surfaces hub nodes (degree at least 3x the median or top 1% of the vault), bridge nodes ranked by approximate betweenness, stale-orphan flagging (>30 days old), silo clusters (<3 cross-cluster edges), and a centrality-skew warning when one node holds >25% of total edges. Turns the canvas into a structural diagnostic of the vault, not just a picture.
- **Suggested questions for future-Claude in `/obsidian-recap` and `/obsidian-review`:** both commands now end with 4 to 5 questions the period's vault content is uniquely positioned to answer that the user has not asked yet. Each question cites at least one specific note via `[[wikilink]]`. Prefers questions that surface contradictions, connect co-appearing-but-unlinked entities, or name unstated next actions. Turns passive recaps into actionable prompts.
- **SessionStart hook (`hooks/load_vault_context.py`):** injects `_CLAUDE.md` into context once per session when the session starts inside the vault. Eliminates the per-command re-read of `_CLAUDE.md` that burned tokens on every invocation. Wired automatically by `scripts/setup.sh`.
- **`scripts/setup.sh` updated:** wires the new SessionStart hook (`hooks/load_vault_context.py`) in addition to the existing PostCompact background agent.
- **Per-day operation logs:** `/obsidian-init` now creates a `Logs/` folder with per-day files (`Logs/YYYY-MM-DD.md`) instead of a monolithic `log.md`. Root `log.md` becomes 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 in `index.md`. Idempotent and re-runnable.
- **`scripts/migrate_log.py`:** splits an existing monolithic `log.md` (with `## YYYY-MM-DD` section headers) into per-day files under `Logs/`. Idempotent - skips days that already exist. Replaces root `log.md` with a pointer file after migration.

### Fixed

- **`scripts/setup.sh` robustness:** four issues fixed together. Vault paths containing apostrophes or other shell metacharacters (`Joe's Notes`) no longer crash the installer - `eval echo` replaced with bash parameter substitution. `python` replaced with `python3` for compatibility with macOS 13+ and Ubuntu 22+ which don't ship a `python` symlink. All three `settings.json` writes are now atomic (`mv` instead of `cat … && rm`). The MCP setup prompt is skipped when stdin is not a terminal so `curl | bash` installs and CI don't hang.

- **`vault_stats.py` people count:** now counts both `type: person` and `type: entity` in 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.md` vs monolithic `log.md`) and uses the correct file and format. Previously, commands hardcoded `log.md` with the old `## [YYYY-MM-DD]` section-header format, which would write incorrectly formatted entries on modernized vaults.
- **`vault_stats.py` folder exclusions case-insensitive:** `EXCLUDED_FOLDERS` comparison now uses `part.lower()`, so `templates/` and `Templates/` are both excluded. Added `raw/` to the exclusion set (immutable source folder convention).
- **Em-dashes swept from `vault_stats.py` output, `commands/obsidian-init.md` entry template, and `SKILL.md` format spec:** all user-facing and vault-facing prose now uses ` - ` per the no-em-dash rule.

## [0.8.0] - 2026-05-15

### Added

- **`/notebooklm` command 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 (default `gemini-2.5-flash`, free-tier friendly) for a citation-style synthesis grounded only against those sources, writes the AI-first synthesis to `Research/NotebookLM/YYYY-MM-DD - <slug>.md`, deletes the store, and emits a propagation payload for `/obsidian-save`. Requires `GEMINI_API_KEY` from https://aistudio.google.com/apikey (free tier covers it). Cost: roughly $0.004 per run on Flash, $0.06 per run on Pro (override via `NOTEBOOKLM_MODEL` env). Filenames written by this command use ASCII separators (`2026-05-15 - <slug>.md`) instead of em-dashes; existing `/research-deep` filenames 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

- **`/notebooklm` self-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_scan` now excludes anything under `Research/NotebookLM/`.
- **`/notebooklm` em-dash filenames blew up the Gemini SDK upload.** Vault filenames in `Research/Deep/` and `wiki/logs/` often contain em-dashes (from the prior `/research-deep` convention). 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-readable `display_name`.
- **`/notebooklm` em-dashes baked into vault output.** The synthesis H1 used `topic — 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 --preset` and `--mode` flags:** wires the preset/mode interface that `SKILL.md` documented but the script never implemented (running `--preset researcher` errored with `unrecognized 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.md` folder map, Home dashboard nav, and template extras via a single `PRESETS` dict at the top of the file - adding a new preset is one dict entry plus optional template lines in `write_preset_extras()`. Two modes: `personal` (default - owner-style `_CLAUDE.md`) and `assistant` (uses the `references/claude-md-assistant-template.md` schema, requires `--subject "Name"` and renders the operator/subject distinction). Fully backwards-compatible: `--path`, `--name`, `--jobs`, `--no-sidebiz` keep their meaning under the default preset; `--no-sidebiz` is 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-command` interview flow (Phase 5):** new meta command that scaffolds a new `commands/<name>.md` through 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 under `meta` category; total command count is now 32 (was 31).
- **Write-time AI-first validator (Phase 4):** new `hooks/validate-ai-first.sh` runs as a Claude Code `PostToolUse` hook after every `Write` or `Edit` on a markdown file inside `OBSIDIAN_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 Claude` preamble. Surfaces specific warnings on stderr so Claude can repair the note in the same turn. Skips `raw/`, `templates/`, `_export/`, `.obsidian/`, `.git/`, `.trash/` and anything outside the vault. Platform-neutral spec at `hooks/validate-ai-first.hook.yaml`. Setup instructions in `SKILL.md` under "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 via `triggers_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 phrases` section 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 in `CONTRIBUTING.md` under "Translating trigger phrases (multilingual support)".
- **Command categorization (Phase 2):** each command in `commands/` now declares a `category:` (vault, thinking, research, meta). Non-Claude dispatcher tables in `AGENTS.md` / `GEMINI.md` are now emitted as four grouped sections instead of one 31-row blob. Adapters use the shared `emit_routing_table_grouped` helper in `adapters/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.sh` orchestrator + `scripts/lib.sh` utility helpers
  - `adapters/lib.sh` shared parsing, path rewriting, tool-name neutralization
  - `adapters/claude-code/adapter.sh` - identity copy (Claude Code is the canonical platform)
  - `adapters/codex-cli/adapter.sh` - emits `AGENTS.md` + `.codex/commands/`
  - `adapters/gemini-cli/adapter.sh` - emits `GEMINI.md` + `.gemini/commands/`
  - `adapters/opencode/adapter.sh` - emits `AGENTS.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.md` with full contributor guide
- `CLAUDE.md` at repo root for contributor-facing operating instructions
- `CHANGELOG.md` (this file)
- `.github/` community files: issue templates, PR template, FUNDING.yml
- `CITATION.cff` for Google Scholar / Zenodo / OpenSSF
- `llms.txt` at 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.md` template)
- `SECURITY.md` - vulnerability reporting policy and coordinated disclosure timeline
- Schema.org JSON-LD `SoftwareApplication` block 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 `markdown` and `pkm` for `obsidian-skill` and `claude-code-skill`

### Fixed

- **`bootstrap_vault.py` `UnicodeEncodeError` on Windows `cp1252` consoles.** The script's emoji print statements (`🧠 Bootstrapping vault: ...`, `📁 Folders created`, `✅ Vault bootstrapped at: ...`) crashed on Windows before doing any work because the default Python `sys.stdout` encoding on Windows PowerShell / cmd is `cp1252`, which has no codepoints for those characters. `sys.stdout` and `sys.stderr` are now reconfigured to UTF-8 at script start, wrapped in `try/except (AttributeError, ValueError)` so non-text streams or environments without `.reconfigure()` fall back gracefully.
- **Removed dead `--minimal` flag from `bootstrap_vault.py`.** `argparse` accepted `--minimal` but the value was never passed into `bootstrap()` - the flag had no effect for any user since v0.1.0. Removing it changes no behavior.
- `pyproject.toml` version was `0.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.md` now points to `ai-first-rules.md` as 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.md` template - 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.lock` for 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.

[Unreleased]: https://github.com/eugeniughelbur/obsidian-second-brain/compare/v0.6.0...HEAD
[0.6.0]: https://github.com/eugeniughelbur/obsidian-second-brain/releases/tag/v0.6.0
[0.5.0]: https://github.com/eugeniughelbur/obsidian-second-brain/releases/tag/v0.5.0