SwarmVault

Added the 3.0 retrieval surface: `swarmvault retrieval status|rebuild|doctor`, engine retrieval status/rebuild/doctor APIs, MCP `retrieval_status`, `rebuild_retrieval`, and `doctor_retrieval` tools, plus a `state/retrieval/manifest.json` health record beside the local SQLite FTS shard.; Moved release-facing search configuration to `retrieval.{backend,shardSize,hybrid,rerank,embeddingProvider,maxIndexedRows}` and added an idempotent `swarmvault migrate --target 3.0.0` step that rewrites legacy `search.{hybrid,rerank}` config into the new retrieval block.; Added the task-first agent ledger surface: `swarmvault task start|update|finish|list|show|resume`, `--task <id>` on query/context/explore, task MCP tools, the `swarmvault://tasks` resource, and `task_id` / `task_status` frontmatter on generated task pages.; Kept the 2.0 memory CLI, MCP tools, resources, state files, and frontmatter as compatibility aliases for existing workflows while updating generated pages and graph tags to advertise the task-first terminology.; Bumped OSS packages, the viewer package, Obsidian plugin metadata, MCP-facing version, and the published ClawHub skill bundle to `3.0.0`, refreshed package locks, and extended tests around retrieval repair, 3.0 migration, task aliases, and MCP exposure.

Added portable graph share kits — every normal compile now writes `wiki/graph/share-kit/` beside the existing markdown and SVG share cards, with `share-card.md`, `share-post.txt`, `share-card.svg`, `share-preview.html`, and `share-artifact.json`; Extended `swarmvault graph share` with `--bundle [dir]`, defaulting to `wiki/graph/share-kit`; markdown, `--post`, and `--svg [path]` behavior remain unchanged, and `--json --bundle` returns the structured artifact plus `bundlePath` and named output paths instead of raw HTML/SVG contents; Updated `swarmvault scan` and `swarmvault demo` to surface the share-kit path so first-run users can post text, share an SVG, link or screenshot the HTML preview, or inspect JSON metadata from the same compile; Added renderer, compile-flow, and installed-package smoke coverage for share kits, including escaped HTML preview output and mode-conflict validation for `graph share`; Refreshed the OSS README trio, package docs, ClawHub skill bundle, website docs, and product `spec.md` around the share-kit workflow

Added dependency-free visual graph share cards — every normal compile now writes `wiki/graph/share-card.svg` beside `wiki/graph/share-card.md`, using the existing graph share artifact to render a 1200x630 SVG with vault stats, top hubs, bridge nodes, a surprising link, and the install/scan CTA; Extended `swarmvault graph share` with `--svg [path]`, defaulting to `wiki/graph/share-card.svg`; `--post` and default markdown output remain unchanged, and `--json --svg` returns the structured artifact plus `svgPath` for scripts and agents; Updated `swarmvault scan` and `swarmvault demo` to surface both markdown and SVG share-card paths so the first-run viral loop leaves copyable text and a visual card ready on disk; Added renderer, compile-flow, and installed-package smoke coverage for visual share cards, including XML escaping for graph labels before they enter SVG output; Refreshed the OSS README trio, package docs, ClawHub skill bundle, website docs, and product `spec.md` around the visual share-card workflow

Added `swarmvault graph share [--post]` for post-ready graph summaries — the command reads the compiled graph/report artifacts, prints the same markdown shape written to `wiki/graph/share-card.md`, emits only the compact copyable text with `--post`, and preserves structured output under `--json` for scripts and agents; Compile, `swarmvault scan`, and `swarmvault demo` now surface `wiki/graph/share-card.md` as a first-run artifact, with source/page/node/edge/community counts, top hubs, bridge nodes, surprising connections, suggested next questions, knowledge gaps, and reproducible install/run instructions; Graph viewer node selection now clears explicitly when the canvas background is tapped, which makes the live viewer behavior and installed-package browser smoke more deterministic; Kept release preflight focused on installed SwarmVault artifacts by making the Codex host-agent smoke explicit opt-in via `SWARMVAULT_RUN_CODEX_AGENT_SMOKE=1`, matching the existing opt-in behavior for other external model-dependent host checks, and by having browser validation wait on rendered graph hooks instead of `networkidle` or coordinate-sensitive canvas clicks; Refreshed the OSS README trio, package docs, ClawHub skill bundle, website docs, and product `spec.md` around the share-card loop so a new user can scan a repo, copy a concise public update, and then open the richer graph/report workflow without extra setup

Added a local-Whisper audio provider — `providers.<id>.type = "local-whisper"` shells out to a user-installed `whisper.cpp` binary and exposes the `audio` capability only, so voice memos, meetings, and arbitrary `.wav`/`.mp3`/`.m4a`/`.flac`/`.ogg`/`.webm` files transcribe end-to-end with no API keys and no network traffic; binary discovery falls back through `localWhisper.binaryPath`, `SWARMVAULT_WHISPER_BINARY`, and `$PATH` lookups for `whisper-cli` / `whisper-cpp` / `whisper`, and the configurable `model`, `binaryPath`, `modelPath`, `extraArgs`, and `threads` fields on the provider entry are forwarded through to the binary; the provider is documented as **experimental** in `STABILITY.md`; Added `swarmvault provider setup --local-whisper` — an interactive subcommand that reports whisper.cpp binary status, downloads the configured ggml model (`base.en` by default, `--model {tiny.en,small.en,medium.en,large-v3}` to switch tiers) from the canonical `ggerganov/whisper.cpp` Hugging Face mirror into `~/.swarmvault/models/`, and registers the provider in `swarmvault.config.json` (setting `tasks.audioProvider = "local-whisper"` when no audio provider was previously configured, or leaving an existing assignment alone unless `--set-audio-provider` is passed); `--apply` skips prompts for CI / scripted installs, and `--json` emits a structured status without prompting or downloading; Audio sources are now accepted through the inbox importer alongside the existing document and image kinds — drop a voice memo into `raw/inbox/` (or a watched root) and the watcher, inbox scanner, and `swarmvault add` all route it through the configured audio provider; transcribed text flows through the same ingest-time redactor as every other derived text, so secrets spoken aloud in a meeting are scrubbed before they reach `raw/` or `wiki/`

Replaced the environment-sensitive perf baselines in `pnpm check:perf` with absolute budgets in `scripts/perf-budgets.json`. Each metric carries a rationale inline so future bumps document intent, and the lane no longer fails on CI hardware that is 3x-4x slower than a development laptop. No runtime or published package behavior changes — this is a CI infrastructure fix plus a matching paragraph in `SCALE.md`.

Promotes the 0.12.0 surface to the 1.0.0 semver baseline with no new features. Every CLI subcommand, config key, MCP tool, frontmatter field, graph artifact field, and state file listed as Stable in [STABILITY.md](STABILITY.md) is now covered by the semver promise: breaking changes require a major version bump. Experimental surfaces remain opt-in and may change in any minor release.; Publishes the deprecation policy — a minimum two-minor grace window with runtime lint warnings and a matching `swarmvault migrate` step before any stable surface is removed.; `swarmvault migrate` reaches 1.0.0 with shipped steps for upgrading 0.9 and 0.10 vaults to the current schema (decay_score, last_confirmed_at, tier, tags) plus a stale-search-index clearer; the verified end-to-end flow upgrades a fixture 0.9-era vault cleanly and writes `state/vault-version.json`.; Documents the tested operating envelope in [SCALE.md](SCALE.md) and the 1.0 PDF extraction choice in [docs/pdf-extraction.md](docs/pdf-extraction.md).

Added `swarmvault migrate [--target <version>] [--apply] [--dry-run]` for vault schema/config/graph upgrades — detects the current vault version via `state/vault-version.json` (and falls back to `state/graph.json` metadata), plans named migration steps, applies them idempotently, and exposes the same plan over MCP via the new `migrate` tool; shipped migrations cover adding `decay_score` / `last_confirmed_at` / `tier` / `tags` to legacy pages and clearing the stale search index so compile regenerates it; Published the first `STABILITY.md` contract documenting every stable CLI subcommand, config key, MCP tool, frontmatter field, graph artifact field, and state file covered by the semver promise, plus the deprecation policy (minimum two-minor grace window, runtime lint warnings, `swarmvault migrate` shipping alongside removals); linked from the EN/ZH/JA READMEs; Added a performance regression CI lane — `pnpm check:perf` runs three tight benchmarks (`computeDecayScore`, `resolveLargeRepoDefaults`, `redact`) against recorded baselines in `scripts/perf-baselines.json` with a ±35% tolerance; a new `perf-budget` GitHub Actions job fails the build on regressions and `pnpm check:perf:record` updates baselines deliberately; Added the OpenAI-compatible provider capability matrix — `OPENAI_COMPATIBLE_CAPABILITY_MATRIX` records the canonical capability set, API style, and notes for every OpenAI-family preset (openai, openai-compatible, openrouter, groq, together, xai, cerebras, ollama); the new `withCapabilityFallback` helper runs a primary path when the capability is advertised and returns a caller-supplied fallback with an explicit `unsupported` reason otherwise, so structured-output and multimodal calls degrade safely instead of failing at runtime; Published `SCALE.md` documenting the tested operating envelope (small up to 500 sources, medium up to 5k, large up to 50k), what degrades past each tier (SQLite FTS, compile memory, similarity density, viewer interactivity, audio transcription cost), which config knobs to turn, how to benchmark your own vault, and the options once you exceed the large tier; Published `docs/pdf-extraction.md` explaining the 1.0 PDF choice — `pdf-parse` / `pdf.js` as the deterministic no-dependency default — its known limitations on tables, scanned PDFs, multi-column layouts, and embedded images, and how to opt into richer extraction via the experimental vision path or a custom provider module

Added explicit watched-root controls — `swarmvault watch --root <path>` (repeatable) overrides the auto-discovered list for a single run; `swarmvault watch list-roots`, `swarmvault watch add-root <path>`, and `swarmvault watch remove-root <path>` persist a curated list under `watch.repoRoots` in `swarmvault.config.json`, with an optional `watch.excludeRepoRoots` deny list; existing 0.9.0/0.10.0 configs keep auto-discovery behavior with no regression; Nest-parsed Vue single-file component `<script>` and `<script setup>` blocks through the TypeScript extractor — `.vue` sources now emit symbol, import, and call edges for the embedded script alongside the Vue outer pass; `<script>` with no `lang` attribute defaults to TypeScript so modern `<script setup>` components are covered out of the box; Added parser-first rationale extraction for non-code sources — markdown, HTML, PDF, DOCX, EPUB, and other document kinds walk their markdown AST and emit `NOTE:` / `WHY:` / `HACK:` / `IMPORTANT:` / `RATIONALE:` / `TODO:` / `FIXME:` / `WARNING:` rationales from blockquote and list-item nodes (anchored to the nearest preceding heading); plain-text, transcript, email, and calendar kinds run the same prefix check over already-isolated paragraphs; no whole-file regex sweeps, in line with the parser-first rationale rule; Embedded `graph query`, `graph path`, and `graph explain` in the standalone HTML export — `swarmvault graph export --html-standalone` now bundles a dependency-free JS runtime with BFS/DFS query, shortest-path, and explain panels that run fully offline against the embedded graph payload; the server and MCP paths continue to use the same shared `graph-query-core` helpers so parity is guaranteed; Rendered group-pattern hyperedges (`participate_in`, `implement`, `form`) as synthetic hub nodes in the viewer and standalone HTML export — each hyperedge renders a dashed `hyper` hub with short pairwise edges to every participant, toggleable via a "Show hyperedges" control in the live viewer; hubs are viewer-only and never mutate `state/graph.json`; Expanded tag-based navigation — the viewer sidebar now supports AND multi-select across tag pills, a tag search input, a top-20 default with "Show all N tags" expander, and round-trips the selected set through a new `#tags?selected=foo,bar` deep link (legacy `#tag?tag=foo` still resolves); Added tag inheritance — derived concept, entity, and consolidation-tier pages inherit the union of tags from their contributing source pages, deduped and sorted deterministically while preserving each page's own kind/leader tags first; Tuned large-repo defaults — similarity edges now use IDF weighting so generic shared concepts contribute less than rare ones (with a configurable `graph.similarityIdfFloor`), god-node output carries a deterministic `surpriseReason`, and `resolveLargeRepoDefaults` lowers `godNodeLimit`, tightens community rollup, and caps similarity edge fan-out on repos above 1000 nodes unless the user has explicitly configured those knobs in `swarmvault.config.json`; Added per-source-class benchmark breakdown — `state/benchmark.json` and `wiki/graph/report.md` now include a `byClass` section with source, page, god-node, and context-token-savings numbers for `first_party`, `third_party`, `resource`, and `generated` classes; shipped with a new `worked/large-repo/` example that exercises all four classes end-to-end

Wired the existing web search adapter into `query` and `explore` for opt-in gap-fill — the new `--gap-fill` flag pulls external results when the local wiki is missing context, surfaces URLs as standard provenance citations, and fails fast with a helpful error when `webSearch.tasks.queryProvider` or `webSearch.tasks.exploreProvider` are not configured in `swarmvault.config.json`; Added config-driven PII and secret redaction at ingest, on by default with built-in patterns for AWS access keys, Stripe live keys, GitHub PATs, OpenAI keys, JWTs, `Authorization: Bearer` tokens, and PEM private key headers — matches are replaced with a configurable placeholder, audited via `wiki/log.md`, and surfaced on every ingest result so users can see what was scrubbed; opt out per-run with `--no-redact` or globally with `redaction: { enabled: false }`; Added time-based decay scoring and `superseded_by` edges — every page now carries `decayScore` (0..1) and `lastConfirmedAt` that fade on configurable per-source-class half-lives (first_party 365d, third_party 90d, generated 30d, resource 730d), `swarmvault graph supersession <old> <new>` records human-curated replacements, `swarmvault lint --decay` flags decayed pages and broken supersession links, and compile resets decay on confirmed pages so re-ingest restores freshness; Added a four-tier memory consolidation pass (working / episodic / semantic / procedural) — heuristic Jaccard grouping rolls up time-windowed working insights into episodic digests, recurring entities into semantic pages, and ordered workflow sequences into procedural pages; available as `swarmvault consolidate [--dry-run]`, scheduled via the new `consolidate` job kind, exposed as the `consolidate` MCP tool, surfaced by `swarmvault lint --tiers`, and runs as a post-compile pass on every vault by default

Added four new agent integrations — `swarmvault install --agent kiro` writes `.kiro/skills/swarmvault/SKILL.md` plus an always-on `.kiro/steering/swarmvault.md`; `swarmvault install --agent hermes` writes the user-scope skill to `~/.hermes/skills/swarmvault/SKILL.md` plus a repo `AGENTS.md` managed block; `swarmvault install --agent antigravity` writes `.agent/rules/swarmvault.md` (always-on) and `.agent/workflows/swarmvault.md` (`/swarmvault` slash command); `swarmvault install --agent vscode` writes `.github/chatmodes/swarmvault.chatmode.md` for VS Code Copilot Chat; Added `swarmvault init --lite` for a minimal LLM-Wiki starter — only `raw/`, `wiki/`, `wiki/index.md`, `wiki/log.md`, and `swarmvault.schema.md`, with no config, state, or agent installs; the LLM agent maintains the wiki directly until the user upgrades to the full toolchain via `swarmvault init`; Cross-file `calls` edges are now emitted for every tree-sitter language (Swift, Go, Rust, Java, C#, Kotlin, Scala, Ruby, PHP, and others) — unresolved call sites fall back to the imported-symbol index and are emitted with `evidenceClass: inferred` at confidence 0.8, matching the rest of the cross-file edge semantics; Graph finalization now prunes dangling edges and hyperedges whose endpoints are missing from the node set, preventing broken references from reaching `graph.json` or downstream exporters; Added `GraphNode.normLabel` — a precomputed NFKD-normalized lowercase label — and routed `graph query`, `graph path`, and `graph explain` through the same normalization so labels match regardless of diacritics (`Café` and `Cafe` resolve to the same node); Added corpus-aware transcription prompting — `extractAudioTranscription` now reads top god-nodes from `state/graph.json` via the new `buildCorpusHint` helper and forwards a one-sentence domain hint as the Whisper prompt through the OpenAI-compatible provider, biasing transcription toward in-corpus terminology; transcription still runs silently without the hint when the graph is absent or empty

Overhauled the graph viewer to close the gap between the rich CLI surface and the previously-thin React workspace: added markdown rendering with syntax highlighting and clickable provenance to the page preview, a graph canvas legend, layout switcher (cose/concentric/circle/breadthfirst/grid), zoom/fit controls, label-mode toggle, an interactive minimap, tag-first filter pills, bulk approve/reject and bulk promote/archive flows with per-list filters, candidate score columns and sorting, diff split-view scroll sync, an undo toast for review actions, a command palette (`⌘K`), keyboard shortcuts (`/`, `f`, `q`, `p`, `r`, `?`, `[`, `]`), a help modal, hash-based deep links (`#page?path=…`, `#node?id=…`, `#tag?tag=…`, `#approval?id=…`), responsive drawer layouts for the filter sidebar and detail rail, a light/dark/system theme selector with `prefers-color-scheme` detection plus localStorage persistence, a live activity feed wired to a new SSE channel, a lint findings panel, a UI export menu (canvas as PNG/SVG, subgraph JSON, copy page as markdown), and refactored the App.tsx state into a `useReducer`-backed workspace store with consolidated workspace fetching; Added three new graph-server endpoints: `GET /api/lint` returns viewer-formatted lint findings, `GET /api/workspace` returns a single rolled-up bundle (graph + reviews + candidates + watch + report + lint), and `GET /api/events` is an SSE channel backed by a new exported `viewerEventBus` event emitter that other engine modules can publish to; Surfaced candidate promotion scores in `listCandidates` (best-effort using existing auto-promotion gates) so the viewer can show a `score` chip and sort candidates by promotion likelihood without re-running the auto-promoter; Added five new viewer component test suites (PagePreview, CommandPalette, CandidateList, hooks, and an extended GraphCanvas mock) and shipped React Testing Library + jsdom support so future viewer changes can be unit-verified before release

0.7.31: interactive offline HTML export with client-side graph query, candidate auto-promotion with configurable gates, structured approval diffs with protected-frontmatter warnings, resumable bulk ingest, and eight new MCP tools for the full review/promote loop

Prepared the Obsidian plugin for the community marketplace submission: rewrote the manifest description so it no longer references the host app, removed the disallowed `swarmvaultCliMinVersion` and `fundingUrl` fields, and relocated the CLI compatibility pin to `packages/obsidian-plugin/cli-compat.json` (bundled into the plugin at build time); Added `manifest.json` at the repo root as a byte-identical copy of the plugin manifest so the Obsidian validator can fetch it via the standard repo-root URL; Tightened `check-release-sync.mjs` to enforce the marketplace allow-list of manifest keys, verify the root manifest matches the plugin manifest exactly, and pin `cli-compat.json` minCliVersion to be at or below the monorepo root version

Added first-party Obsidian plugin (`@swarmvaultai/obsidian-plugin`) that drives the SwarmVault CLI from inside Obsidian: status bar shows workspace + compile freshness, command palette runs init/ingest/add/compile/lint/watch/serve, Query from current note returns answers with page_id→wikilink citations, Run Log view streams live stdout/stderr of every invocation, and long-running `watch`/`graph serve` processes are tracked in a managed-processes registry that drains on plugin unload; Extended the release-sync check to pin the plugin `package.json`, `manifest.json`, and `swarmvaultCliMinVersion` to the monorepo root version so the plugin never ships ahead of the CLI it talks to; Fixed citation rewriting to handle real SwarmVault page IDs containing colons and slashes (e.g. `concept:foo`, `source:arxiv/2401.00001`)

Obsidian export: types.json, node-type colors, typed link frontmatter, graph metrics, cssclasses, Dataview dashboards, canvas file nodes with directed edges

Bundle vis-network for offline HTML exports, add tsconfig path alias resolution, stabilize symbol IDs with kind discriminator

Added first-class audio ingest with provider-backed transcription through `tasks.audioProvider`, plus native YouTube URL transcript capture that writes extracted text and metadata into the normal source, extract, compile, and search pipeline; Added `swarmvault demo` for a zero-config sample vault walkthrough and `swarmvault diff` for showing graph-level changes against the last committed `state/graph.json`; Upgraded `graph export --obsidian` so exported vaults preserve wiki folder structure, add graph frontmatter and connection sections, emit orphan node stubs plus community notes, copy referenced assets, and ship a minimal `.obsidian` config; Added optional `graph.communityResolution` configuration while keeping adaptive default Louvain resolution selection for smaller or sparser graphs; Refreshed the OSS README set, package docs, skill bundle docs, and website docs to cover the new ingest paths, CLI commands, graph export behavior, and configuration surface

Added `--commit` support to `ingest`, `compile`, and `query`, plus an exported auto-commit helper for git-backed vault workflows that want wiki and state changes committed immediately; Added `compile --max-tokens <n>` token budgeting so lower-priority pages can be trimmed from final wiki output when you need a bounded context window, with token-budget stats reported in the compile result; Added hybrid page search that merges SQLite full-text hits with embedding-backed semantic matches, optional reranking through the configured query provider, `graph blast <target>` reverse-import impact analysis, `graph export --report` self-contained HTML report export, MCP `blast_radius`, and a local browser clipper bookmarklet exposed from `graph serve`; Updated the README, package docs, skill bundle docs, and website docs to cover commit-on-write flows, search controls, graph blast/report workflows, browser clipping, and compile token budgets

Normalized approval bundle types to hyphenated names such as generated-output, source-review, and guided-session, while keeping legacy underscore manifests readable so existing approval history continues to load cleanly; Refreshed the README, package docs, skill bundle docs, and website docs to match the current profile wording, provider setup guidance, source artifact descriptions, and deep-lint web-search scope