feat(vault): multi-vault discovery + selection — v0.3.0

[bezata]

Summary

• Adds a new `vault.*` namespace (4 tools) that lets an LLM enumerate the user's Obsidian vaults and switch between them for the session. Tool surface 62 → 66 across 16 namespaces.
• Fully backwards compatible — `OBSIDIAN_VAULT_PATH` behaves identically to v0.2.5, no existing tool signatures change, and all 56 pre-existing tests pass unmodified. The precedence chain gains a middle slot that collapses to v0.2.5 exactly when `vault.select` is never called: `arg > session > env > error`.
• `obsidian.json` discovery is marked EXPERIMENTAL. Obsidian's vault registry has no documented API — every third-party tool parses the internal `obsidian.json` file. We parse it by default for zero-config onboarding, but label it experimental in tool descriptions, CHANGELOG, ENVIRONMENT.md, and MIGRATION.md because the format is internal to Obsidian and could change without notice. Toggle with `KOBSIDIAN_VAULT_DISCOVERY=off`; parse failures never crash the server.
• Cross-platform CI required. Depends on #17 (the CI matrix PR) landing first so we have a confirmed green macOS + Windows + Linux baseline before this merges.

The 4 new tools

Tool	What	Annotation
`vault.list`	Merge + dedup vaults from `OBSIDIAN_VAULT_PATH` + `OBSIDIAN_VAULT_=` env vars + parsed `obsidian.json`. Each item carries `{id, name, path, isDefault, isActive, source, lastOpened?, exists}`.	`READ_ONLY`
`vault.current`	Echo the vault filesystem tools resolve to right now, plus the `reason` (session-selected | env-default | none) + env default + live-Obsidian REST caveat.	`READ_ONLY`
`vault.select`	Set the session-active vault by exactly one of `id`, `name`, or `path`. `path` accepts ad-hoc absolute directories, so the LLM can point at a fresh/empty vault to initialise.	`ADDITIVE`
`vault.reset`	Clear the session selection; fall back to `OBSIDIAN_VAULT_PATH`. Idempotent.	`IDEMPOTENT_ADDITIVE`

Discovery sources (in priority order)

Source	Status	Toggle
`OBSIDIAN_VAULT_PATH`	Documented, stable, always included	—
`OBSIDIAN_VAULT_=path` env vars	Documented, stable	—
`obsidian.json` parsing	EXPERIMENTAL — Obsidian's undocumented registry, stable since 1.0	`KOBSIDIAN_VAULT_DISCOVERY=on` (default) / `off`

`obsidian.json` paths per OS

• macOS: `~/Library/Application Support/obsidian/obsidian.json`
• Windows: `%APPDATA%\obsidian\obsidian.json` (with home fallback)
• Linux: `$XDG_CONFIG_HOME/obsidian/…` → `~/.config/obsidian/…` → Flatpak → Snap
• Escape hatch: `KOBSIDIAN_OBSIDIAN_CONFIG=/abs/path/obsidian.json` for portable installs / WSL.

Security / gating

• `KOBSIDIAN_VAULT_ALLOW=name1,name2,/abs/path` — allowlist filtering (names or absolute paths).
• `KOBSIDIAN_VAULT_DENY=...` — denylist, applied after allowlist.
• `OBSIDIAN_VAULT_PATH` is never filtered by either, preventing operator self-lockout.
• `vault.select` distinguishes `not_found` (vault doesn't exist) from `unauthorized` (vault exists but is blocked) for better error UX.

Changes outside `vault.*`

• Every filesystem tool description gets a one-line session-vault note appended at registration time (via `buildDescription()` in `create-server.ts` — centralised, no per-file edits). `workspace.` and `commands.` get the inverse note: they bridge to the live Obsidian instance via `OBSIDIAN_API_URL` and are NOT affected by the selection.
• `pick-vault` prompt — MCP server-side prompt template that Claude Desktop surfaces as a slash command; walks `vault.list` → presents options → calls `vault.select`.
• Stale prompt text — fixed the `ingest-source` prompt's leftover references to `notes.insertAfterHeading` / `notes.append` (removed in v0.2.5) → now `notes.edit` with the appropriate `mode`.
• `DomainContext` extended with `session: SessionState` + `vaults: VaultCache`. Additive — consumers destructuring `{env, api}` continue to work unmodified.

HTTP transport caveat

Multi-client HTTP deployments share the `DomainContext` across requests, so `vault.select` is process-global today. `vault.select`'s description warns about this; concurrent HTTP clients should pass `vaultPath` per call. Per-`Mcp-Session-Id` scoping is deferred to a future v0.3.x.

Test plan

• 4 new test files, 49 new assertions — platform-mocked path resolution, fixture parsing, precedence chain (all 8 set/unset combos), integration with real temp-dir vaults
• 7 fixture `obsidian.json` files (macOS, Windows escaped-backslash, Linux, malformed, no-vaults, empty-vaults, with-unknown-keys)
• All 56 v0.2.5 tests still pass unmodified
• `bun run typecheck` — clean
• `bun run lint` — clean
• `bun run test` — 111/111 passing on Windows
• `bun run build` — stdio 2.1 MB + http 1.51 MB
• `docs/tool-inventory.json` regenerated — 66 tools
• CI matrix green on `macos-latest` + `windows-latest` + `ubuntu-latest` (depends on ci: add cross-platform test matrix (macos + windows + linux) #17 landing first — after that, this PR will get the matrix)
• Manual smoke on the maintainer's Windows machine: `vault.list` returns real obsidian.json vaults; `vault.select { name: "…" }` flips the vault; `notes.list` hits it.
• Manual smoke on macOS (borrowed/cloud): same four steps, confirm `vault.list.obsidianConfigPath` is `~/Library/Application Support/obsidian/obsidian.json`.

After merge

Tag `v0.3.0` on the merge commit — `release.yml` handles mcpb bundles + npm publish via OIDC Trusted Publishing.

🤖 Generated with Claude Code