{"id":"5a7cda3c-71d5-4925-b7db-fdd9e4e9bd29","entityType":"agent","slug":"clawhub-waydelyle-swarmvault","name":"SwarmVault","canonicalUrl":"https://www.xpersona.co/agent/clawhub-waydelyle-swarmvault","canonicalPath":"/agent/clawhub-waydelyle-swarmvault","generatedAt":"2026-10-09T20:56:16.341Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":null},"description":"Use SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack,...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.6K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s172jgfp1hrj42g10wkscjf0t583ttz6:swarmvault","sourceUrl":"https://clawhub.ai/waydelyle/swarmvault","homepage":"https://clawhub.ai/waydelyle/skills/swarmvault","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/waydelyle/swarmvault","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/waydelyle/skills/swarmvault","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":52,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"SwarmVault technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":null},"stars":null,"forks":null,"downloads":2593,"packageName":null,"latestVersion":"3.20.0","tractionLabel":"2.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:01.310Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T13:07:01.311Z","lastCrawledAt":"2026-10-09T13:07:01.310Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T13:07:01.310Z","lastVerifiedAt":null,"highlights":[{"version":"3.20.0","createdAt":"2026-06-12T11:27:46.062Z","changelog":"Added declaration line ranges to code symbols: the TypeScript/JavaScript analyzer records `startLine`/`endLine` for functions, classes, and variables, the ranges travel through `CodeSymbol` onto graph symbol nodes, and `graph callers` scans only each caller's own declaration range so call sites are attributed to the correct caller even when several callers share a file. Symbols without ranges (other languages, older graphs) keep the previous per-file behavior.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.20.0`.","fileCount":12,"zipByteSize":41372},{"version":"3.19.0","createdAt":"2026-06-12T10:27:03.360Z","changelog":"Added `swarmvault graph callers <symbol>` (CLI) and `graph_callers` (MCP): lists every caller of a symbol from graph call edges with exact file:line call-site evidence, scanning only the files the graph identifies as callers. Live token A/B testing showed caller/impact questions were the one category where agents still fell back to repo-wide grep; this closes that gap, and hook guidance now points who-calls/impact questions at it.; Fixed cross-file `calls` edges being dropped at extraction: call-name candidates now include imported local names (named, aliased, and default imports) in both the TypeScript-AST and parser-fallback analyzers, so calls into imported symbols resolve through the import map into cross-module graph edges instead of only same-module ones.; Added host-project hygiene to `swarmvault install`: vault artifact directories are appended to `.gitignore` in git repos, excluded from strict-JSON `tsconfig.json` files so stored source copies under `raw/` no longer break the host project's typecheck, and linter configs that still cover the artifact directories produce an advisory warning. Commented (JSONC) tsconfig files are never rewritten — a warning explains the manual edit instead — and everything is skipped when `SWARMVAULT_OUT` keeps artifacts outside the repo.; Updated OSS docs, localized READMEs, site docs, and the published ClawHub skill bundle for the new caller-evidence and install-hygiene workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.19.0`.","fileCount":12,"zipByteSize":41423},{"version":"3.18.0","createdAt":"2026-06-12T08:53:01.194Z","changelog":"Made graph-first search enforcement opt-in: installed agent hooks now default to advisory mode (`context`), and `swarmvault install --agent <agent> --hook --graph-first [deny|context|off]` persists the chosen mode as `hooks.graphFirst` in `swarmvault.config.json` (`SWARMVAULT_GRAPH_FIRST` still overrides per session).; Stopped the graph-first hooks from flagging search tools that filter piped output (e.g. `some-command | grep …`); only a search tool leading a pipeline counts as a broad file search.; Fixed `graph status` permanently reporting redacted or composite sources as modified by confirming raw-byte mismatches through the same prepare pipeline the sync uses before counting them as changes.; Added an optional repo argument to `swarmvault hook install|uninstall|status` so git hooks can target a tracked repo below the vault root (e.g. a workspace-parent vault watching repos in subdirectories); the installed hook still refreshes from the vault root.; Hardened the post-publish live smoke against npm registry propagation races by retrying the published-package install with backoff instead of failing the release sequence.; Updated OSS docs, localized READMEs, site docs, and the published ClawHub skill bundle for the opt-in graph-first workflow.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.18.0`.","fileCount":12,"zipByteSize":40246},{"version":"3.17.0","createdAt":"2026-06-11T16:29:33.485Z","changelog":"Added graph-first read enforcement for agent integrations: the Claude Code hook now intercepts the first broad Grep/Glob/Bash search per session with a guided redirect to `swarmvault graph query|explain|blast` and `wiki/graph/report.md` (retrying the same search is always allowed), surfaces graph staleness at session start, and triggers a background single-file graph refresh after every Edit/Write. Configure with `SWARMVAULT_GRAPH_FIRST=deny|context|off` or `hooks.graphFirst` in `swarmvault.config.json`; `off` disables the whole integration, and searches scoped to vault artifacts or single files are never intercepted.; Reworked `graph query` output for agent consumption, validated with live token A/B runs against an uninstrumented baseline: summaries now lead with ranked top matches (label, type, score, wiki page path) before the capped seed list across CLI, MCP, serve, and standalone HTML surfaces, and the plain CLI output inlines a bounded excerpt of the best-matching wiki page so where-is/what-calls questions resolve in one command instead of a search-plus-read chain.; Added `swarmvault graph update --file <path>` (repeatable): a code-only fast path that refreshes just the named files instead of walking every tracked repo root, with a refresh lock plus queue so rapid edit bursts coalesce instead of stacking concurrent compiles.; Added `swarmvault install --agent claude --mcp` to register the SwarmVault MCP server in the project's `.mcp.json`, project skill bundles at `.claude/skills/`, and user-scope Claude installs (`--scope user`) covering `~/.claude` skills, hooks, and settings.; Upgraded the Codex, Gemini, Copilot, OpenCode, and Kilo integrations to the same graph-first guidance (session-start instructions with staleness notes and a one-time search redirect), and refreshed the shared agent rule bullets to direct code-structure questions at the graph before source files.; Added `graph_status` and `update_graph` MCP tools for read-only freshness checks and code-only (optionally per-file) graph refreshes over MCP.; Migrated previously installed Claude hook settings entries to the new matcher layout on reinstall; user-owned hook entries are preserved, and legacy agent rule files written by older releases are still recognized during cleanup.; Updated the shared agent rule bullets: code-structure questions go to the graph before grep/glob with source reads reserved for editing, and answers are saved into `wiki/outputs/` only for durable research, review, or handoff requests instead of every question.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the graph-first agent workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.17.0`.","fileCount":12,"zipByteSize":39764},{"version":"3.16.1","createdAt":"2026-06-11T15:44:52.911Z","changelog":"Fixed `provider remove` corrupting `swarmvault.config.json` when the last configured provider was removed: required task assignments were deleted, leaving a config the CLI could no longer parse. Removal is now refused with a clear error while required tasks still point at the provider.; Fixed `provider remove --fallback` accepting unconfigured provider ids, which silently reassigned tasks to a provider that did not exist.; Improved `provider remove` reporting: output now distinguishes tasks reassigned to the fallback provider from optional task assignments that were cleared, and the JSON result includes `fallbackProviderId`, `reassignedTasks`, and `clearedTasks` alongside the existing `updatedTasks`.; Stopped `provider remove` from rewriting the config file when nothing was removed and no task assignments changed.; Refreshed transitive dependencies to pick up published security patches (`fast-uri`, `@xmldom/xmldom`, `hono`, `@hono/node-server`, `fast-xml-builder`, `ws`, `qs`), clearing all patchable audit advisories.; Updated site provider docs for the stricter `provider remove` semantics.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.16.1`.","fileCount":11,"zipByteSize":34970},{"version":"3.16.0","createdAt":"2026-06-02T12:41:58.100Z","changelog":"Added first-class `kilo` and `devin` agent install targets, project/user install scope selection, `swarmvault install status`, Kilo plugin registration with JSONC source preservation, and project skill-bundle outputs for Codex, OpenCode, Gemini, Copilot, VS Code, Pi, Kimi, Amp, Antigravity, and Devin.; Added `swarmvault provider add|list|show|remove` for explicit provider registry management, task assignment, capability metadata, and raw config preservation without storing literal API secrets.; Added `swarmvault graph cycles` for deterministic directed cycle detection and `swarmvault graph export --callflow` for compact directed relationship HTML exports.; Extended engine and CLI coverage for agent install parity, provider config persistence, graph cycle detection, and callflow export.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the new release-facing workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, and ClawHub skill metadata to `3.16.0`.","fileCount":11,"zipByteSize":34964},{"version":"3.15.0","createdAt":"2026-05-19T14:10:07.548Z","changelog":"Fixed `quickstart`, `scan`, and `clone` so local file inputs such as PDFs work directly instead of failing with directory-only path handling.; Added interactive, bounded ingest progress on stderr with active-file feedback and processed content size while keeping JSON, MCP, watch, and CI-style flows quiet.; Changed `init`, `quickstart`, `scan`, and `clone` to avoid writing project-local agent rule files by default; rule installs are now explicit through `install --agent` or configured `--install-agent-rules`.; Added MCP registry container metadata (`Dockerfile`, `.dockerignore`, and `glama.json`) for stdio container validation.; Extended CLI surface smoke and engine coverage for single-file quickstart and explicit agent-rule installation behavior.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.15.0`.","fileCount":11,"zipByteSize":34423},{"version":"3.14.2","createdAt":"2026-05-19T10:37:41.701Z","changelog":"Hardened compile for larger heuristic vaults by bounding source analysis concurrency, graph co-occurrence projection, concept conflict pairing, and contradiction comparisons.; Made JSON state writes atomic and parse failures path-aware, so corrupt derived state reports the exact JSON file instead of a bare `Unexpected end of JSON input`.; Documented agent rule-file behavior: shared managed SwarmVault blocks stay in sync, while user-owned content in files such as `AGENTS.md` and `CLAUDE.md` is preserved and may intentionally differ.; Added regression coverage for corrupt compile state, larger heuristic markdown compiles, and managed agent-rule parity.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.14.2`.","fileCount":10,"zipByteSize":32504}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s172jgfp1hrj42g10wkscjf0t583ttz6:swarmvault","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s172jgfp1hrj42g10wkscjf0t583ttz6:swarmvault` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/waydelyle/swarmvault before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T20:56:16.334Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-waydelyle-swarmvault/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":null},"readme":"Skill: SwarmVault\n\nOwner: waydelyle\n\nSummary: Use SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack,...\n\nTags: graph:3.20.0, knowledge:0.1.4, knowledge-base:3.20.0, latest:3.20.0, local-first:3.20.0, markdown:3.20.0, mcp:3.20.0, stable:0.7.31, swarmvault:3.20.0, v0.7:0.7.31, v0.7.27:0.7.27, v0.7.28:0.7.28\n\nVersion history:\n\nv3.20.0 | 2026-06-12T11:27:46.062Z | user\n\nAdded declaration line ranges to code symbols: the TypeScript/JavaScript analyzer records `startLine`/`endLine` for functions, classes, and variables, the ranges travel through `CodeSymbol` onto graph symbol nodes, and `graph callers` scans only each caller's own declaration range so call sites are attributed to the correct caller even when several callers share a file. Symbols without ranges (other languages, older graphs) keep the previous per-file behavior.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.20.0`.\n\nv3.19.0 | 2026-06-12T10:27:03.360Z | user\n\nAdded `swarmvault graph callers <symbol>` (CLI) and `graph_callers` (MCP): lists every caller of a symbol from graph call edges with exact file:line call-site evidence, scanning only the files the graph identifies as callers. Live token A/B testing showed caller/impact questions were the one category where agents still fell back to repo-wide grep; this closes that gap, and hook guidance now points who-calls/impact questions at it.; Fixed cross-file `calls` edges being dropped at extraction: call-name candidates now include imported local names (named, aliased, and default imports) in both the TypeScript-AST and parser-fallback analyzers, so calls into imported symbols resolve through the import map into cross-module graph edges instead of only same-module ones.; Added host-project hygiene to `swarmvault install`: vault artifact directories are appended to `.gitignore` in git repos, excluded from strict-JSON `tsconfig.json` files so stored source copies under `raw/` no longer break the host project's typecheck, and linter configs that still cover the artifact directories produce an advisory warning. Commented (JSONC) tsconfig files are never rewritten — a warning explains the manual edit instead — and everything is skipped when `SWARMVAULT_OUT` keeps artifacts outside the repo.; Updated OSS docs, localized READMEs, site docs, and the published ClawHub skill bundle for the new caller-evidence and install-hygiene workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.19.0`.\n\nv3.18.0 | 2026-06-12T08:53:01.194Z | user\n\nMade graph-first search enforcement opt-in: installed agent hooks now default to advisory mode (`context`), and `swarmvault install --agent <agent> --hook --graph-first [deny|context|off]` persists the chosen mode as `hooks.graphFirst` in `swarmvault.config.json` (`SWARMVAULT_GRAPH_FIRST` still overrides per session).; Stopped the graph-first hooks from flagging search tools that filter piped output (e.g. `some-command | grep …`); only a search tool leading a pipeline counts as a broad file search.; Fixed `graph status` permanently reporting redacted or composite sources as modified by confirming raw-byte mismatches through the same prepare pipeline the sync uses before counting them as changes.; Added an optional repo argument to `swarmvault hook install|uninstall|status` so git hooks can target a tracked repo below the vault root (e.g. a workspace-parent vault watching repos in subdirectories); the installed hook still refreshes from the vault root.; Hardened the post-publish live smoke against npm registry propagation races by retrying the published-package install with backoff instead of failing the release sequence.; Updated OSS docs, localized READMEs, site docs, and the published ClawHub skill bundle for the opt-in graph-first workflow.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.18.0`.\n\nv3.17.0 | 2026-06-11T16:29:33.485Z | user\n\nAdded graph-first read enforcement for agent integrations: the Claude Code hook now intercepts the first broad Grep/Glob/Bash search per session with a guided redirect to `swarmvault graph query|explain|blast` and `wiki/graph/report.md` (retrying the same search is always allowed), surfaces graph staleness at session start, and triggers a background single-file graph refresh after every Edit/Write. Configure with `SWARMVAULT_GRAPH_FIRST=deny|context|off` or `hooks.graphFirst` in `swarmvault.config.json`; `off` disables the whole integration, and searches scoped to vault artifacts or single files are never intercepted.; Reworked `graph query` output for agent consumption, validated with live token A/B runs against an uninstrumented baseline: summaries now lead with ranked top matches (label, type, score, wiki page path) before the capped seed list across CLI, MCP, serve, and standalone HTML surfaces, and the plain CLI output inlines a bounded excerpt of the best-matching wiki page so where-is/what-calls questions resolve in one command instead of a search-plus-read chain.; Added `swarmvault graph update --file <path>` (repeatable): a code-only fast path that refreshes just the named files instead of walking every tracked repo root, with a refresh lock plus queue so rapid edit bursts coalesce instead of stacking concurrent compiles.; Added `swarmvault install --agent claude --mcp` to register the SwarmVault MCP server in the project's `.mcp.json`, project skill bundles at `.claude/skills/`, and user-scope Claude installs (`--scope user`) covering `~/.claude` skills, hooks, and settings.; Upgraded the Codex, Gemini, Copilot, OpenCode, and Kilo integrations to the same graph-first guidance (session-start instructions with staleness notes and a one-time search redirect), and refreshed the shared agent rule bullets to direct code-structure questions at the graph before source files.; Added `graph_status` and `update_graph` MCP tools for read-only freshness checks and code-only (optionally per-file) graph refreshes over MCP.; Migrated previously installed Claude hook settings entries to the new matcher layout on reinstall; user-owned hook entries are preserved, and legacy agent rule files written by older releases are still recognized during cleanup.; Updated the shared agent rule bullets: code-structure questions go to the graph before grep/glob with source reads reserved for editing, and answers are saved into `wiki/outputs/` only for durable research, review, or handoff requests instead of every question.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the graph-first agent workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.17.0`.\n\nv3.16.1 | 2026-06-11T15:44:52.911Z | user\n\nFixed `provider remove` corrupting `swarmvault.config.json` when the last configured provider was removed: required task assignments were deleted, leaving a config the CLI could no longer parse. Removal is now refused with a clear error while required tasks still point at the provider.; Fixed `provider remove --fallback` accepting unconfigured provider ids, which silently reassigned tasks to a provider that did not exist.; Improved `provider remove` reporting: output now distinguishes tasks reassigned to the fallback provider from optional task assignments that were cleared, and the JSON result includes `fallbackProviderId`, `reassignedTasks`, and `clearedTasks` alongside the existing `updatedTasks`.; Stopped `provider remove` from rewriting the config file when nothing was removed and no task assignments changed.; Refreshed transitive dependencies to pick up published security patches (`fast-uri`, `@xmldom/xmldom`, `hono`, `@hono/node-server`, `fast-xml-builder`, `ws`, `qs`), clearing all patchable audit advisories.; Updated site provider docs for the stricter `provider remove` semantics.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.16.1`.\n\nv3.16.0 | 2026-06-02T12:41:58.100Z | user\n\nAdded first-class `kilo` and `devin` agent install targets, project/user install scope selection, `swarmvault install status`, Kilo plugin registration with JSONC source preservation, and project skill-bundle outputs for Codex, OpenCode, Gemini, Copilot, VS Code, Pi, Kimi, Amp, Antigravity, and Devin.; Added `swarmvault provider add|list|show|remove` for explicit provider registry management, task assignment, capability metadata, and raw config preservation without storing literal API secrets.; Added `swarmvault graph cycles` for deterministic directed cycle detection and `swarmvault graph export --callflow` for compact directed relationship HTML exports.; Extended engine and CLI coverage for agent install parity, provider config persistence, graph cycle detection, and callflow export.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the new release-facing workflows.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, and ClawHub skill metadata to `3.16.0`.\n\nv3.15.0 | 2026-05-19T14:10:07.548Z | user\n\nFixed `quickstart`, `scan`, and `clone` so local file inputs such as PDFs work directly instead of failing with directory-only path handling.; Added interactive, bounded ingest progress on stderr with active-file feedback and processed content size while keeping JSON, MCP, watch, and CI-style flows quiet.; Changed `init`, `quickstart`, `scan`, and `clone` to avoid writing project-local agent rule files by default; rule installs are now explicit through `install --agent` or configured `--install-agent-rules`.; Added MCP registry container metadata (`Dockerfile`, `.dockerignore`, and `glama.json`) for stdio container validation.; Extended CLI surface smoke and engine coverage for single-file quickstart and explicit agent-rule installation behavior.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.15.0`.\n\nv3.14.2 | 2026-05-19T10:37:41.701Z | user\n\nHardened compile for larger heuristic vaults by bounding source analysis concurrency, graph co-occurrence projection, concept conflict pairing, and contradiction comparisons.; Made JSON state writes atomic and parse failures path-aware, so corrupt derived state reports the exact JSON file instead of a bare `Unexpected end of JSON input`.; Documented agent rule-file behavior: shared managed SwarmVault blocks stay in sync, while user-owned content in files such as `AGENTS.md` and `CLAUDE.md` is preserved and may intentionally differ.; Added regression coverage for corrupt compile state, larger heuristic markdown compiles, and managed agent-rule parity.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.14.2`.\n\nv3.14.1 | 2026-05-11T09:48:19.349Z | user\n\nFixed MCP tool responses so optional fields are serialized as `null` in the returned JSON text instead of leaking `undefined` to MCP clients.; Hardened SQLite FTS retrieval against hyphenated concept targets such as `concept:distributionally-robust-receive-combining`, retrying with conservative tokenization if FTS syntax rejects a query.; Extended MCP and retrieval regression coverage for `query_vault`, `build_context_pack`, `start_task`, `start_memory_task`, and hyphenated target searches.; Updated MCP troubleshooting notes for client-side `[object Undefined]` and `no such column` errors.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.14.1`.\n\nv3.14.0 | 2026-05-08T12:07:14.057Z | user\n\nAdded `swarmvault next` as a read-only orientation command with human and JSON output for uninitialized, initialized, and compiled vault states.; Simplified default top-level help by keeping primary commands visible while hiding older compatibility aliases from the first screen; direct alias help and execution still work.; Updated `quickstart` and `init` human output to point new users at `swarmvault next` after setup.; Extended parser-backed CLI surface smoke to cover `next`, progressive root help, quickstart/init orientation output, and uninitialized/initialized/compiled JSON behavior.; Moved the website input-type matrix into a dedicated reference page and synced OSS README, localized READMEs, package docs, site docs, spec notes, and the ClawHub skill bundle.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, and ClawHub skill metadata to `3.14.0`.\n\nv3.13.0 | 2026-05-08T10:25:49.742Z | user\n\nAdded `swarmvault quickstart <input>` as the beginner-friendly first-run command over the existing scan implementation, including `--no-serve`, `--no-viz`, `--mcp`, and public GitHub checkout flags.; Improved quickstart/scan human output so first-time users can see the vault root, raw source directory, wiki directory, graph JSON path, share artifacts, and useful next commands.; Simplified the OSS README trio, CLI README, site quickstart, CLI docs, and ClawHub skill bundle around a beginner-first flow while keeping advanced graph, context, task, chat, export, and automation commands discoverable.; Extended parser-backed CLI surface smoke and skill validation material to cover the new quickstart command.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, and ClawHub skill metadata to `3.13.0`.\n\nv3.12.0 | 2026-05-05T16:51:40.888Z | user\n\nAdded `swarmvault chat` for persisted multi-turn conversations over the compiled wiki, including resume, list, delete, interactive TTY controls, and optional saved query outputs.; Added `swarmvault export ai` for static handoff packs with `llms.txt`, full text, JSON-LD graph data, manifest metadata, human-readable export notes, and optional per-page siblings.; Hardened local retrieval query token handling so chat resume prompts and question text stay valid in the SQLite FTS path.; Extended parser-backed CLI surface smoke, installed-package live smoke, and live OSS corpus validation to exercise chat sessions and AI handoff exports.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the new handoff surfaces.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.12.0`.\n\nv3.11.0 | 2026-05-05T15:06:20.696Z | user\n\nAdded top-level command-shape compatibility aliases: `swarmvault tree`, `swarmvault merge-graphs <graph...> --out <path>`, and `swarmvault clone <input>`, each backed by the existing graph tree, graph merge, and scan implementations.; Added positional `swarmvault watch [path]` support so v6-style watch invocations can target one repo root without first writing `watch.repoRoots`.; Added `swarmvault scan --no-viz` as a compatibility alias for artifact-only scans and `swarmvault scan --mcp` / `swarmvault clone --mcp` for build-then-serve MCP stdio workflows.; Extended parser-backed CLI surface smoke, installed-package live smoke, and live OSS corpus validation to exercise the new v6 compatibility aliases.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the v6 parity surface.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.11.0`.\n\nv3.10.0 | 2026-05-05T14:14:43.727Z | user\n\nAdded top-level graph-maintenance compatibility commands: `swarmvault check-update [path]`, `swarmvault update [path]`, and `swarmvault cluster-only [vault]`, each backed by the existing graph status/update/cluster implementation instead of a second execution path.; Added `swarmvault graph export --neo4j <path>` as a Neo4j-oriented alias for the Cypher export surface.; Extended parser-backed CLI surface smoke, installed-package live smoke, and live OSS corpus validation to exercise the new compatibility commands and Neo4j export alias.; Updated OSS docs, localized READMEs, site docs, spec notes, and the published ClawHub skill bundle for the compatibility command surface.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.10.0`.\n\nv3.9.0 | 2026-05-05T13:32:57.996Z | user\n\nAdded `swarmvault graph stats` for lightweight local graph counts, node type totals, evidence class totals, and top relation mix without starting the viewer.; Added `swarmvault graph validate [graph] [--strict]` plus engine-level graph artifact validation for duplicate ids, dangling references, confidence bounds, and inconsistent conflicted-edge evidence.; Added `pnpm live:cli-surface`, a parser-backed direct CLI surface smoke that discovers the Commander command tree, requires every stable command path and alias to stay classified, runs `--help` across the full CLI surface, and exercises 50+ direct JSON behavior checks across init, ingest, compile, graph, retrieval, context, task, memory, source, watch, schedule, provider, install, and scan workflows.; Wired the direct CLI surface smoke into `pnpm release:preflight` so release summaries now include a dedicated command-surface gate before the tarball installed-package smoke, browser smoke, and OSS corpus gates.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.9.0`.\n\nv3.8.0 | 2026-05-05T12:04:07.613Z | user\n\nAdded parser-backed Julia and Verilog/SystemVerilog analysis via packaged WASM grammars, including symbols, imports, calls, module/interface/package extraction, and SystemVerilog instantiation relations. R sources remain detected with an explicit parser-asset diagnostic until a safe packaged grammar is available.; Added dynamic `import()` extraction for JavaScript and TypeScript so async module edges resolve through the existing code index and tsconfig path aliases.; Added relation-aware graph query filters across CLI, MCP, and shared traversal: `--relation`, `--context`, `--evidence`, `--node-type`, and `--language`.; Upgraded `swarmvault graph tree` to an interactive self-contained HTML tree with expand/collapse/reset controls, count badges, selected-node metadata, and connected-edge inspection.; Added provider-analysis chunking for long non-code sources so large PDFs, transcripts, books, and markdown exports are analyzed in bounded model calls and merged deterministically.; Hardened directory ingest with cascading nested `.gitignore` support and `.swarmvaultinclude` allowlists while keeping hard ignores such as `.git` and `.venv` non-bypassable.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.8.0`.\n\nv3.7.3 | 2026-05-04T21:51:51.139Z | user\n\nMade the `viewer` config block optional with a default port of `4123`. `swarmvault init` (and any other command that loads the workspace config) used to fail with a raw Zod error against partial or hand-edited `swarmvault.config.json` files that omitted the `viewer` block; older configs now load cleanly.; `swarmvault query`, `swarmvault explore`, and `swarmvault graph query` now reject empty or whitespace-only questions at the engine boundary with a clean error, instead of silently saving an empty answer page. The MCP `query_vault`, `explore_vault`, and `query_graph` tools inherit the same guard.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.7.3`.\n\nv3.7.2 | 2026-05-04T21:16:10.689Z | user\n\nFixed `swarmvault context build`, `swarmvault task start`, and `swarmvault memory start` failing with `unacceptable kind of an object to dump [object Undefined]` when invoked without `--target` or `--agent`. The generated context-pack and memory-task markdown frontmatter now drops undefined values before js-yaml serialization, so optional fields no longer crash the dump. The MCP `build_context_pack`, `start_task`, and `start_memory_task` tools inherit the same fix.; Added a shared `safeFrontmatter` helper in `@swarmvaultai/engine`'s `utils` so other frontmatter writers can stay defensive against undefined values.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.7.2`.\n\nv3.7.1 | 2026-05-04T20:57:49.651Z | user\n\nFixed the `graph update` / one-shot watch shrink guard so it predicts the projected node and edge drop from tracked-repo removals before any destructive sync runs, instead of partially restoring `state/graph.json` after the rest of the vault had already been mutated. Aborted updates now leave `state/graph.json`, `state/extracts/`, `raw/sources/`, `wiki/`, and the manifest set untouched.; Extended `stripCodeExtension` to recognize `.svelte`, `.jl`, `.v`, `.vh`, `.sv`, `.svh`, and `.r` so module names and import alias keys for the new v3.7.0 languages no longer carry the file extension.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.7.1`.\n\nv3.7.0 | 2026-05-04T16:22:14.986Z | user\n\nAdded `swarmvault graph tree` for a collapsible HTML source/module/symbol tree, defaulting to `wiki/graph/tree.html`.; Added `swarmvault graph merge <graph...> --out <path>` to combine SwarmVault and NetworkX/node-link JSON graphs into one namespaced graph artifact with explicit evidence-class mapping.; Extended public GitHub repo source handling with `--branch`, `--ref`, and `--checkout-dir` on `source add` and `scan`, and allowed `scan` to quick-start from a public GitHub repo URL.; Added a graph refresh shrink guard for `graph update` / one-shot watch refreshes; updates now abort when nodes or edges drop by more than 25% unless `--force` or `SWARMVAULT_FORCE_UPDATE=1` is explicit.; Added Svelte single-file component code coverage with nested TypeScript/JavaScript script parsing, plus detection and explicit parser-asset diagnostics for Julia, Verilog/SystemVerilog, and R sources.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, and ClawHub skill metadata to `3.7.0`.\n\nv3.6.0 | 2026-05-04T10:53:53.551Z | user\n\nAdded local video and public video URL ingest: local `video/*` files extract audio with `ffmpeg`, `swarmvault ingest --video <url>` / `swarmvault add --video <url>` extract public video audio with `yt-dlp`, and both route transcripts through the configured `tasks.audioProvider` while preserving warning sidecars when a binary or provider is missing.; Added `.swarmvaultignore` support for directory ingest, enabled by default alongside `.gitignore` and disableable with `--no-swarmvaultignore`.; Added parser-backed SQL code analysis for `.sql` sources, including table/view symbols plus extracted `reads`, `writes`, `joins`, and `references` graph edges.; Added `SWARMVAULT_OUT` so generated `raw/`, `wiki/`, `state/`, `agent/`, and `inbox/` artifacts can be isolated from the project root while config and schema stay at the source root.; Added `swarmvault graph status [path]` for read-only graph freshness checks that distinguish code-only updates from semantic refresh work and recommend `graph update` or `compile`.; Added `swarmvault graph cluster [--resolution <n>]`, engine `refreshGraphClusters`, and MCP `cluster_graph` to recompute communities, graph metrics, god-node flags, graph report pages, and share artifacts from an existing compiled graph without re-ingesting sources.; Improved graph community clustering by splitting oversized and low-cohesion communities after the initial Louvain pass so large-repo graph reports remain scannable.; Updated the VS Code installer path so `swarmvault install --agent vscode` writes both the chat mode and `.github/copilot-instructions.md`.; Updated Antigravity installation to write `.agents/rules/swarmvault.md` and `.agents/workflows/swarmvault.md`, with cleanup for older fully managed `.agent/` files.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.6.0`.\n\nv3.5.0 | 2026-05-03T14:07:41.642Z | user\n\nAdded `swarmvault install --agent codex --hook`, which writes `.codex/hooks.json` plus `.codex/hooks/swarmvault-graph-first.js` so Codex sessions are reminded to read `wiki/graph/report.md` before broad shell search.; Added `swarmvault graph update [path]` with `graph refresh` as an alias, wrapping the repo watch refresh path as a code-only graph update and preserving the same JSON shape as `watch --repo --code-only --once`.; Added MCP `graph_stats` and `get_community` helpers for lightweight graph counts and community member/page/evidence inspection.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.5.0`.\n\nv3.4.0 | 2026-05-03T10:54:58.369Z | user\n\nAdded prioritized vault doctor recommendations to `swarmvault doctor`, MCP `doctor_vault`, and the graph viewer workbench, including safe direct repair metadata for retrieval rebuilds and copy-only commands for broader follow-up actions.; Polished workbench and bookmarklet capture so clips can carry titles and tags, selected browser text is imported through the inbox path, and URL-only bookmarklet captures use the normalized `add` flow.; Added release-preflight summary artifacts under `.release-preflight/` with JSON and Markdown evidence for gates, tarball smoke inputs, browser smoke status, OSS corpus status, and artifact roots.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.4.0`.\n\nv3.3.0 | 2026-05-02T15:55:50.367Z | user\n\nPolished the graph viewer workbench so `graph serve` now shows every vault doctor check with detail text and copyable suggested commands, keeps warnings ahead of passing checks, and reports action receipts after repair, capture, context-pack, and task-start actions.; Made workbench capture and agent handoff controls more explicit with selectable capture modes (`ingest`, normalized `add`, or `inbox`) and an editable token budget for context packs and task starts.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.3.0`.\n\nv3.2.0 | 2026-04-29T21:11:28.126Z | user\n\nAdded `swarmvault doctor [--repair]` as a whole-vault health check for graph artifacts, retrieval, review queues, watch status, migration state, managed sources, page counts, and task ledgers, with structured `--json` output and safe retrieval repair.; Exposed the same vault doctor through MCP as `doctor_vault`, while keeping the narrower retrieval tools available for index-specific checks and repairs.; Expanded `graph serve` into a workbench: the viewer now surfaces vault health, one-click repair, richer inbox/browser capture, context-pack creation, and task start actions backed by new viewer API endpoints.; Bumped OSS packages, viewer, Obsidian plugin metadata, MCP-facing version, ClawHub skill metadata, and desktop package metadata to `3.2.0`; the desktop UI now reads its displayed version from the packaged app instead of hardcoding it.\n\nv3.0.0 | 2026-04-28T16:12:57.868Z | user\n\nAdded 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.\n\nv1.4.0 | 2026-04-23T20:51:44.548Z | user\n\nAdded 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\n\nv1.3.0 | 2026-04-23T19:59:56.107Z | user\n\nAdded 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\n\nv1.2.0 | 2026-04-23T19:17:48.013Z | user\n\nAdded `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\n\nv1.1.0 | 2026-04-17T20:19:56.695Z | user\n\nAdded 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/`\n\nv1.0.1 | 2026-04-17T18:44:29.530Z | user\n\nReplaced 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`.\n\nv1.0.0 | 2026-04-17T09:46:51.435Z | user\n\nPromotes 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).\n\nv0.12.0 | 2026-04-17T09:39:36.276Z | user\n\nAdded `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\n\nv0.11.0 | 2026-04-17T00:26:17.965Z | user\n\nAdded 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\n\nv0.10.0 | 2026-04-16T20:58:32.832Z | user\n\nWired 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\n\nv0.9.0 | 2026-04-16T19:32:33.598Z | user\n\nAdded 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\n\nv0.8.0 | 2026-04-16T18:24:16.026Z | user\n\nOverhauled 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\n\nv0.7.31 | 2026-04-16T16:37:57.875Z | user\n\n0.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\n\nv0.7.30 | 2026-04-12T19:17:55.807Z | user\n\nPrepared 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\n\nv0.7.29 | 2026-04-12T19:03:44.316Z | user\n\nAdded 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`)\n\nv0.7.28 | 2026-04-12T18:37:32.221Z | user\n\nObsidian export: types.json, node-type colors, typed link frontmatter, graph metrics, cssclasses, Dataview dashboards, canvas file nodes with directed edges\n\nv0.7.27 | 2026-04-12T16:58:00.062Z | user\n\nBundle vis-network for offline HTML exports, add tsconfig path alias resolution, stabilize symbol IDs with kind discriminator\n\nv0.7.26 | 2026-04-11T10:06:25.520Z | user\n\nAdded 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\n\nv0.7.25 | 2026-04-10T17:03:14.514Z | user\n\nAdded `--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\n\nv0.7.24 | 2026-04-10T15:47:21.533Z | user\n\nNormalized 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\n\nv0.7.23 | 2026-04-10T13:12:07.449Z | user\n\nAdded `swarmvault scan <directory>` as a one-command scratch path that initializes the current directory as a vault, ingests a local directory, compiles it, and can launch the graph viewer immediately; Added `swarmvault watch --code-only` and switched the managed git-hook refresh path to `watch --repo --once --code-only`, making commit and checkout refreshes update code pages and graph structure without re-running non-code semantic analysis; Switched graph community detection to a Louvain clustering pass for cleaner community grouping while still keeping disconnected nodes as singleton communities when no graph edges exist; Updated the README, package docs, skill bundle docs, live-testing notes, and website docs to cover the new scan path, code-only watch behavior, hook refresh semantics, and privacy/data-flow expectations\n\nv0.7.22 | 2026-04-10T12:37:49.381Z | user\n\nAdded new graph export targets for lightweight standalone HTML, deterministic JSON, Obsidian markdown bundles, and Obsidian canvas output alongside the existing HTML, SVG, GraphML, and Cypher exports; Added install targets for Trae, Claw/OpenClaw, and Droid so `swarmvault install --agent` now covers 12 agent surfaces; Added a faster code-only repo watch path so tracked code changes refresh code pages and graph structure without re-running non-code semantic analysis for unchanged sources; Updated the README, package docs, skill bundle docs, and website docs to cover the new export formats, agent targets, graph-report health signals, and repo-watch behavior\n\nv0.7.21 | 2026-04-10T10:26:53.198Z | user\n\nAdded `profile.deepLintDefault` so vault profiles can make `swarmvault lint` run the advisory deep-lint pass by default, while `--no-deep` still forces a structural-only lint run when needed; Updated the CLI, README surfaces, package docs, skill docs, and website configuration/lint docs so the new deep-lint default behavior is documented alongside the existing guided-ingest profile defaults\n\nv0.7.2 | 2026-04-10T10:05:39.853Z | user\n\nAdded a standalone `templates/llm-wiki-schema.md` starter so people can begin with the LLM Wiki pattern and the raw/wiki/schema three-layer architecture before installing the full CLI; Added three new worked example vaults for chapter-by-chapter book companions, contradiction-aware research deep-dives, and personal Memex workflows, with real source material under `worked/` for docs and release validation; Added `profile.guidedIngestDefault` so starter profiles such as `personal-research` can make guided ingest the default for `ingest`, `source add`, and `source reload`, while `--no-guide` still forces the lighter path when needed; Reframed the OSS docs and published skill bundle around the LLM Wiki / Memex model, and tightened README parity checks so the English, Chinese, and Japanese READMEs stay aligned on the new template and example surfaces\n\nv0.7.0 | 2026-04-09T22:03:10.179Z | user\n\nExpanded non-code ingest coverage with the full Word family (`.docx`/`.docm`/`.dotx`/`.dotm`), Excel family (`.xlsx`/`.xlsm`/`.xlsb`/`.xls`/`.xltx`/`.xltm` including legacy biff8), and PowerPoint family (`.pptx`/`.pptm`/`.potx`/`.potm`), plus first-class Rich Text (`.rtf`), BibTeX (`.bib`), Org-mode (`.org`), AsciiDoc (`.adoc`/`.asciidoc`), OpenDocument (`.odt`/`.odp`/`.ods`), and Jupyter (`.ipynb`) extractors; broadened the image pipeline to explicitly route `.heic`/`.heif`/`.avif`/`.jxl`/`.bmp`/`.tif`/`.tiff`/`.svg`/`.ico` alongside `.png`/`.jpg`/`.webp`; and extended the structured-data preview to `.xml`/`.ini`/`.env`/`.properties`/`.cfg`/`.conf` so config/data files match what the README advertises; Added parser-backed ingestion for Elixir (`.ex`/`.exs`), OCaml (`.ml`/`.mli`), Objective-C (`.m`/`.mm`, leaving `.h` headers routed through the C/C++ analyzer), ReScript (`.res`/`.resi`), Solidity (`.sol`), Vue single-file components (`.vue`), HTML (`.html`/`.htm`), and CSS (`.css`) sources via tree-sitter AST walkers, exposing each source's modules, classes, protocols, functions, inheritance edges, and import references through the existing module-page, graph, search, and code-index pipeline; Restored Swift to the documented graceful-degradation path by disabling parser-backed Swift analysis by default, avoiding Node 24 V8 out-of-memory crashes during test and OSS-corpus runs while keeping an explicit opt-in escape hatch for local experiments; Replaced several regex-shaped code import parsers with parser-backed AST extraction for Python, Go, Rust, Java, Kotlin, Scala, C#, PHP, and C/C++ includes, reducing brittle language handling and improving grouped import fidelity; Hardened repo-aware code resolution for real multi-crate and multi-root projects by expanding Rust crate alias handling, stripping trailing symbol segments when imports target module files, and broadening Lua local module candidate resolution; Refactored agent hook installation to ship built hook bundles from the engine package instead of embedding large inline hook scripts in source, keeping installed hook artifacts aligned with the packaged runtime; Made MCP tool handlers fail per-request instead of crashing the whole stdio server, and isolated schedule-loop listing/job failures so one bad schedule no longer tears down the scheduler; Tightened configuration defaults and release prep by centralizing workspace directory defaults and keeping the engine build wired for bundled hooks\n\nArchive index:\n\nArchive v3.20.0: 12 files, 41372 bytes\n\nFiles: examples/graph-first-agent-workflow.md (3882b), examples/quickstart.md (5171b), examples/repo-workflow.md (3481b), examples/research-workflow.md (2544b), README.md (29825b), references/artifacts.md (4171b), references/commands.md (6442b), skill-card.md (2747b), SKILL.md (24570b), TROUBLESHOOTING.md (12408b), validation/smoke-prompts.md (8336b), _meta.json (130b)\n\nFile v3.20.0:SKILL.md\n\n---\nname: swarmvault\ndescription: \"Use SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack, task-ledger, static AI export, retrieval, and MCP artifacts to disk from books, notes, transcripts, exports, datasets, slide decks, files, URLs, code, and recurring source workflows.\"\nversion: \"3.20.0\"\nmetadata: '{\"openclaw\":{\"requires\":{\"anyBins\":[\"swarmvault\",\"vault\"]},\"install\":[{\"id\":\"node\",\"kind\":\"node\",\"package\":\"@swarmvaultai/cli\",\"bins\":[\"swarmvault\",\"vault\"],\"label\":\"Install SwarmVault CLI (npm)\"}],\"emoji\":\"🗃️\",\"homepage\":\"https://www.swarmvault.ai/docs\"}}'\n---\n\n# SwarmVault\n\nUse this skill when the user wants a local-first knowledge vault built on the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern — three layers (raw sources, wiki, schema) where the LLM maintains a durable wiki between you and raw sources. Also use it when the project already contains `swarmvault.config.json` or `swarmvault.schema.md`.\n\nFor onboarding, examples, command references, or troubleshooting, read the bundled `README.md`, `examples/`, `references/`, and `TROUBLESHOOTING.md` before improvising workflow advice.\n\n## Quick checks\n\n- Work from the vault root.\n- Use `swarmvault next` when you need a read-only orientation command before deciding whether to initialize, ingest, compile, query, review, or refresh.\n- If the vault does not exist yet, run `swarmvault init`.\n- Use `swarmvault demo --no-serve` when the user wants the fastest zero-config walkthrough before pointing SwarmVault at their own sources.\n- Use `swarmvault quickstart <file-or-directory-or-github-url>` as the beginner-friendly first-run path when the user wants init + ingest + compile + graph viewer in one command.\n- Use `swarmvault scan <file-or-directory-or-github-url> --no-serve`, `swarmvault scan <file-or-directory-or-github-url> --no-viz`, or `swarmvault clone <file-or-directory-or-github-url> --no-viz` when the user wants the fastest scratch pass over a local file, local repo, public GitHub repo, or docs tree without manually stepping through init + ingest + compile first; for GitHub URLs add `--branch`, `--ref`, or `--checkout-dir` when the user needs a pinned checkout. Use `scan --mcp` or `clone --mcp` when the next step should be an MCP stdio server. Use `swarmvault graph share --post` for copyable text, `swarmvault graph share --svg [path]` for a visual card, or `swarmvault graph share --bundle [dir]` for a portable folder with markdown, post text, SVG, HTML preview, and JSON metadata.\n- Use `swarmvault context build \"<goal>\" --target <path-or-node> --budget <tokens>` when the next agent, review, or handoff needs a bounded evidence pack instead of a broad vault search.\n- Use `swarmvault chat \"question\"` when a multi-turn conversation should survive handoff; resume with `swarmvault chat --resume <id> \"follow-up\"` and inspect saved transcripts under `wiki/outputs/chat-sessions/`.\n- Use `swarmvault export ai --out <dir>` when another agent, crawler, or static workflow needs `llms.txt`, full text, JSON-LD graph data, a manifest, and per-page siblings without starting `graph serve`.\n- Use `swarmvault task start \"<goal>\" --target <path-or-node>` when agent work should leave a durable task ledger with decisions, linked context packs, changed paths, outcomes, and follow-ups. The older `memory` command remains a compatibility alias.\n- Use `swarmvault doctor` before broad troubleshooting or agent handoff; add `--repair` when the retrieval index can be safely rebuilt. In `swarmvault graph serve`, the workbench shows prioritized next actions, every doctor check with details, copyable suggested commands, and safe direct repair where available.\n- Read `swarmvault.schema.md` before compile or query work. It is the vault's operating contract.\n- If `wiki/graph/report.md` exists, use it before broad repo search.\n- If `SWARMVAULT_OUT` is set, resolve generated artifacts from that output root: `raw/`, `wiki/`, `state/`, `agent/`, and `inbox/` live there while `swarmvault.config.json` and `swarmvault.schema.md` stay in the project root.\n\n## Core loop\n\n1. Run `swarmvault next` when the current vault state is unclear; it is read-only and returns paths, checks, and recommended commands.\n2. Initialize a vault with `swarmvault init` when needed.\n3. Update `swarmvault.schema.md` before a serious compile. Use it for naming rules, categories, grounding, freshness expectations, and exclusions.\n4. Use `swarmvault source add <input>` when the input is a recurring local file, local directory, public GitHub repo root, or docs hub that should stay registered. For public GitHub repos, use `--branch`, `--ref`, or `--checkout-dir` when a branch, tag, commit, or reusable checkout matters.\n5. Ingest one-off inputs with `swarmvault ingest <path-or-url>`, or ingest a whole repo tree with `swarmvault ingest <directory>`. Audio and video files use `tasks.audioProvider` when configured; local video needs `ffmpeg`, public video URLs use `swarmvault ingest --video <url>` / `swarmvault add --video <url>` with `yt-dlp`, and supported YouTube URLs go through direct transcript capture instead of generic URL ingest.\n6. Use `swarmvault ingest --guide`, `swarmvault source add --guide`, `swarmvault source reload --guide`, `swarmvault source guide <id>`, or `swarmvault source session <id>` when the human should integrate one source at a time before canonical pages change. Set `profile.guidedIngestDefault: true` in `swarmvault.config.json` to make guided mode the default; use `--no-guide` to override. Profiles using `guidedSessionMode: \"canonical_review\"` stage approval-queued canonical edits; `insights_only` profiles keep exploratory synthesis in `wiki/insights/`. Use `--review` only for the lighter review-only path.\n7. Use `swarmvault inbox import` for capture-style batches, then `swarmvault watch --lint --repo` when the workflow should stay automated. Add `--code-only` when the refresh should stay AST-only and defer non-code semantic re-analysis to a later `compile`. On tracked repos, code-only changes take that faster compile path automatically. Install `swarmvault hook install` when git checkouts and commits should trigger the same repo-aware code-only refresh automatically.\n8. Compile with `swarmvault compile`, use `compile --max-tokens <n>` when the generated wiki must stay inside a bounded context budget, or use `compile --approve` when changes should go through the local review queue first.\n9. Resolve staged work with `swarmvault review list|show|accept|reject` and `swarmvault candidate list|promote|archive`.\n10. Ask questions with `swarmvault query \"<question>\"`. It saves durable answers into `wiki/outputs/` by default; add `--no-save` only for ephemeral checks. When an embedding provider is configured, query can merge semantic page matches into local search; `retrieval.rerank: true` lets the current `queryProvider` rerank the merged top hits before answering.\n11. Use `swarmvault chat \"question\"` for a persisted multi-turn conversation over the compiled wiki, then resume or manage it with `swarmvault chat --resume <id>`, `chat --list`, and `chat --delete <id>`.\n12. Build agent handoff bundles with `swarmvault context build \"<goal>\" --target <path-or-node> --budget <tokens>`. Use `--format markdown|json|llms` for the printed shape, and inspect `swarmvault context list|show|delete` for saved packs.\n13. Start a task ledger with `swarmvault task start \"<goal>\" --target <path-or-node>`, update it with `swarmvault task update <id> --note|--decision|--changed-path|--context-pack`, finish it with `swarmvault task finish <id> --outcome <text>`, and use `swarmvault task resume <id> --format markdown|json|llms` for the next-agent handoff. `query`, `explore`, and `context build` can attach work with `--task <id>`; `--memory <id>` remains a compatibility alias.\n14. Run `swarmvault export ai --out <dir>` when the compiled wiki should be handed to another agent or static crawler as `llms.txt`, full text, JSON-LD, manifest metadata, and per-page `.txt`/`.json` siblings.\n15. Run `swarmvault doctor [--repair]` when the vault needs one health summary across graph, retrieval, review queues, watch state, migrations, managed sources, and task state before deeper troubleshooting.\n16. Use `swarmvault explore \"<question>\" --steps <n>` for save-first multi-step research loops, or `--format report|slides|chart|image` when the artifact should be presentation-oriented.\n17. Run `swarmvault lint` whenever the schema changed, artifacts look stale, or compile/query results drift. Set `profile.deepLintDefault: true` in `swarmvault.config.json` when the advisory deep-lint pass should be the default, and use `--no-deep` when you need a structural-only run. Add `--web` only when deep lint is enabled and a `webSearch.tasks.deepLintProvider` adapter is configured; web evidence is scoped to deep lint and does not change compile or query behavior.\n18. Use `swarmvault mcp` when another agent or tool should browse, search, query, build context packs, manage tasks, and inspect vault or retrieval health from the vault through MCP.\n19. Use `swarmvault graph share --post` when the user needs a quick copyable summary, `swarmvault graph share --svg [path]` when they need a 1200x630 visual card, `swarmvault graph share --bundle [dir]` when they need a portable share kit for posting, linking, or screenshotting, `swarmvault graph blast <target>` when they want reverse-import impact analysis, `swarmvault graph callers <symbol>` when they need every caller of a symbol from graph call edges with exact file:line call-site evidence, `swarmvault graph cycles` when they need directed cycle checks, `swarmvault graph status [path]` or `swarmvault check-update [path]` when they need a read-only stale check before deciding between `graph update` and `compile`, `swarmvault graph stats` when they need lightweight counts and relation mix, `swarmvault graph validate [graph] --strict` when a graph artifact should be checked before export, merge, push, or publish workflows, `swarmvault graph update [path] --force` or `swarmvault update [path] --force` only when a large node/edge shrink is expected, `swarmvault watch [path] --once --code-only` when one repo root should be refreshed without writing watch config, `swarmvault graph query \"<seed>\" --context calls --evidence extracted` when traversal should focus on relation groups, evidence classes, node types, or languages, `swarmvault graph tree [--output <html>]` or `swarmvault tree [--output <html>]` when they need an interactive source/module/symbol tree with a node inspector, `swarmvault graph merge <graph...> --out <path>` or `swarmvault merge-graphs <graph...> --out <path>` when they need to combine SwarmVault or node-link graph JSON, `swarmvault graph cluster [--resolution <n>]` or `swarmvault cluster-only [vault]` when they need communities and graph report artifacts recomputed without re-ingest, `swarmvault graph serve` when the live workspace, health workbench, Memory dashboard, or bookmarklet clipper will help, `swarmvault diff` when they need a graph-level change summary against the last committed baseline, or `swarmvault graph export --html <output>` / `graph export --report <output>` / `graph export --callflow <output>` when richer sharing will help. The live workbench exposes prioritized next actions, explicit capture modes, title/tag capture fields, context-pack/task token budgets, and action receipts; the bookmarklet sends page titles and selected text into the same capture path. `graph export` also supports `--html-standalone`, `--json`, `--obsidian`, `--canvas`, and `--neo4j` for lighter, Obsidian-native, or Neo4j-ready sharing.\n\n## Graph-first code reads\n\nWhen a compiled vault exists for a codebase (`wiki/graph/report.md` is present), answer code-understanding questions from the graph instead of reading or grepping source files — it returns condensed, evidence-backed answers in far fewer tokens:\n\n- \"Where is X / what calls Y / how is Z structured\" → `swarmvault graph query \"<seed>\"`, `swarmvault graph explain \"<node>\"`, `swarmvault graph path \"<a>\" \"<b>\"`. Use the plain output: `graph query` prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers these questions without follow-up file reads. Avoid `--json` here — it produces much larger output.\n- \"Who calls X / impact of changing X\" → `swarmvault graph callers <symbol>` lists every caller from graph call edges with exact file:line call-site evidence, scanning only the files the graph identifies as callers — use it instead of repo-wide grep for who-calls and impact-of-change questions. `swarmvault graph blast <target>` adds module-level reverse-import impact.\n- Open questions over the whole codebase → `swarmvault query \"<question>\"`.\n- Bounded handoff context → `swarmvault context build \"<goal>\" --target <path> --budget <tokens>`.\n- Read source files directly only when editing them or when the graph lacks the needed detail.\n- Check freshness with `swarmvault graph status`; refresh with `swarmvault graph update`, or `swarmvault graph update --file <path>` for just-edited files.\n- Installed agent hooks default to advisory mode: a one-time guidance note on the first broad search, plus an automatic background single-file refresh after edits. Enforcement (the first broad Grep/Glob/Bash search per session is denied with a redirect to the graph; repeating the search is allowed) is opt-in — install with `--graph-first`, or set `hooks.graphFirst: \"deny\"` in `swarmvault.config.json`. `SWARMVAULT_GRAPH_FIRST=deny|context|off` overrides per session; search tools that filter piped output are never intercepted.\n\n## Working rules\n\n- Prefer changing the schema before re-running compile when organization or grounding is wrong.\n- Treat `wiki/` and `state/` as first-class outputs. Inspect them instead of trusting a single chat answer.\n- Use saved chat transcripts and static AI exports as durable handoff artifacts when the user asks for continuity across sessions or tools.\n- Prefer `wiki/graph/report.md`, `state/graph.json`, and saved wiki pages over ad hoc broad search when they already exist.\n- Use `swarmvault graph status [path]` or `swarmvault check-update [path]` before refreshing a tracked repo when you need to know whether a code-only `graph update`/`update` is enough or a full `compile` is required.\n- Use `swarmvault graph validate [graph] --strict` before sharing, merging, pushing, or publishing graph artifacts when reference integrity matters.\n- Use `source add` for recurring files, directories, public GitHub repo roots, and docs hubs. Use `ingest` and `add` for deliberate one-off inputs.\n- When the vault lives in a git repo, `ingest|compile|query --commit` can commit `wiki/` and `state/` changes immediately after the run.\n- The default heuristic provider is a valid local/offline starting point. Add a model provider only when the user wants richer synthesis quality or optional capabilities such as embeddings, vision, image generation, or audio transcription. The recommended fully-local setup is Ollama + Gemma: `ollama pull gemma4` then set `providers.llm` to `{ type: \"ollama\", model: \"gemma4\" }` and point `tasks.compileProvider`, `tasks.queryProvider`, and `tasks.lintProvider` at it. Use `swarmvault provider add|list|show|remove` when provider routing should be updated without hand-editing config.\n- Audio and video ingest need `tasks.audioProvider` to resolve to a provider that exposes `audio` capability. For a fully local setup, run `swarmvault provider setup --local-whisper --apply` — installs the `local-whisper` provider, downloads a whisper.cpp ggml model into `~/.swarmvault/models/`, and points `tasks.audioProvider` at it. Local video also needs `ffmpeg`; public video URL ingest with `--video` needs `yt-dlp`. YouTube transcript ingest does not need a provider. Set `graph.communityResolution` when the user wants to pin community clustering instead of using the adaptive default and oversized/low-cohesion split pass, or run `swarmvault graph cluster --resolution <n>` for a one-off recompute.\n- If an OpenAI-compatible backend cannot satisfy structured generation, reduce its declared capabilities instead of forcing every task through it.\n- Keep raw sources immutable. Put corrections in schema, new sources, or saved outputs rather than manually rewriting generated provenance.\n\n## Files and artifacts\n\n- `swarmvault.schema.md`: vault-specific compile and query rules.\n- `SWARMVAULT_OUT`: optional output root for generated artifact directories. When set, `raw/`, `wiki/`, `state/`, `agent/`, and `inbox/` are resolved under that directory.\n- `raw/sources/` and `raw/assets/`: canonical source storage.\n- `wiki/`: generated pages plus saved outputs.\n- `wiki/outputs/source-briefs/`: saved onboarding briefs for managed sources.\n- `wiki/outputs/source-sessions/`: resumable guided-session anchors plus question/answer history for one-source-at-a-time integration.\n- `wiki/outputs/source-reviews/`: staged source-scoped review pages.\n- `wiki/outputs/source-guides/`: staged source-integration guides for one-source-at-a-time workflows.\n- `wiki/outputs/chat-sessions/`: persisted markdown transcripts for `swarmvault chat`.\n- `wiki/dashboards/`: recent sources, reading log, timeline, source sessions, source guides, research map, contradiction, and open-question dashboards.\n- `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/`: post-ready text, visual graph summaries, and a portable HTML-preview share bundle generated on compile.\n- `wiki/exports/ai/`: default static AI handoff export with `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, `ai-readme.md`, and optional per-page siblings.\n- `wiki/context/`: markdown context-pack companions for agent kickoff, PR review, and handoff.\n- `wiki/memory/`: task ledger index and markdown task pages.\n- `wiki/code/`: module pages for ingested JavaScript, JSX, TypeScript (including `.mts`/`.cts`), TSX, Bash/shell script (with shebang-based detection for extensionless scripts), Python, Go, Rust, Java, Kotlin, Scala, Dart, Lua, Zig, C#, C, C++ (including `.c`/`.cc`/`.cpp`/`.cxx` and `.h`/`.hh`/`.hpp`/`.hxx`), PHP, Ruby, PowerShell (`.ps1`/`.psm1`/`.psd1`), Elixir (`.ex`/`.exs`), OCaml (`.ml`/`.mli`), Objective-C (`.m`/`.mm`), ReScript (`.res`/`.resi`), Solidity (`.sol`), Vue single-file components (`.vue`), Svelte single-file components (`.svelte`), HTML (`.html`/`.htm`), CSS, Julia (`.jl`), Verilog/SystemVerilog (`.v`/`.vh`/`.sv`/`.svh`), R (`.r`/`.R`), and SQL (`.sql`) sources. Julia and Verilog/SystemVerilog use packaged WASM grammars; JS/TS capture static and dynamic imports; SQL adds table/view symbols plus read/write/join/reference graph edges; R emits an explicit diagnostic until a safe packaged parser exists.\n- `state/extracts/`: extracted markdown and JSON sidecars for PDF, the full Word family (`.docx`/`.docm`/`.dotx`/`.dotm`), RTF (`.rtf`), OpenDocument (ODT/ODP/ODS), EPUB, CSV/TSV, the full Excel family (`.xlsx`/`.xlsm`/`.xlsb`/`.xls`/`.xltx`/`.xltm`), the full PowerPoint family (`.pptx`/`.pptm`/`.potx`/`.potm`), Jupyter notebooks (`.ipynb`), BibTeX (`.bib`), Org-mode (`.org`), AsciiDoc (`.adoc`/`.asciidoc`), transcripts, Slack exports, email, calendar, audio transcripts, video transcripts, YouTube transcript captures, and image sources (`.png`/`.jpg`/`.jpeg`/`.gif`/`.webp`/`.bmp`/`.tif`/`.tiff`/`.svg`/`.ico`/`.heic`/`.heif`/`.avif`/`.jxl`), plus structured previews for config/data files (JSON/JSONC/JSON5/TOML/YAML/XML/INI/ENV/PROPERTIES/CFG/CONF) and content-sniffed text ingest for developer manifests (`package.json`, `Cargo.toml`, `go.mod`, `LICENSE`, `.gitignore`, `Dockerfile`, `Makefile`, and similar plaintext files).\n- `state/code-index.json`: repo-aware code aliases and local import resolution data.\n- `wiki/projects/`: project rollups over canonical pages.\n- `wiki/candidates/`: staged concept and entity pages awaiting promotion.\n- `state/graph.json`: compiled graph.\n- `state/context-packs/`: saved JSON context-pack artifacts with citations, token-budget accounting, included items, and omitted items.\n- `state/chat-sessions/`: saved structured chat state for resumable wiki conversations.\n- `state/memory/tasks/`: saved JSON task ledger records with decisions, changed paths, outcomes, and follow-ups.\n- `state/retrieval/`: local retrieval index, SQLite FTS shard, and manifest.\n- `state/sources.json` and `state/sources/<id>/`: managed-source registry entries plus working sync state.\n- `state/approvals/`: staged review bundles from `compile --approve`.\n- `state/sessions/`: canonical session artifacts for compile, query, explore, lint, watch, review, and candidate actions.\n- `state/jobs.ndjson`: watch-mode run log.\n\n## Agent integration\n\n- `swarmvault install --agent codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid|kiro|kilo|hermes|antigravity|vscode|amp|augment|adal|bob|cline|codebuddy|command-code|continue|cortex|crush|deepagents|devin|firebender|iflow|junie|kilo-code|kimi|kode|mcpjam|mistral-vibe|mux|neovate|openclaw|openhands|pochi|qoder|qwen-code|replit|roo-code|trae-cn|warp|windsurf|zencoder` installs agent-specific rules into the current project. Agents in the extended roster receive a project-level skill bundle at the tool's conventional skills directory.\n- `swarmvault init`, `quickstart`, `scan`, and `clone` leave project-local agent rule files alone by default. Use `install --agent` explicitly, or set `agents` in `swarmvault.config.json` and pass `--install-agent-rules` to initialization or scan commands when configured installs are intentional.\n- `swarmvault install --agent codex|claude|opencode|gemini|copilot|kilo --hook` installs graph-first hook or plugin support for the agents that expose project hook APIs. For Claude Code the hook surfaces staleness at session start, nudges the first broad search per session toward graph commands, and refreshes the graph in the background after edits; add `--graph-first` to opt in to search enforcement (persists `hooks.graphFirst: \"deny\"`). Use `swarmvault install status --agent <agent> [--hook] [--mcp]` to inspect expected files without writing.\n- `swarmvault install --agent claude --mcp` also registers the SwarmVault MCP server in the project's `.mcp.json`; `swarmvault install --agent claude --hook --scope user` installs the skill, hook, and settings once under `~/.claude` for all repos (the hook no-ops in repos without a compiled graph report).\n- `swarmvault install --agent <agent>` also keeps the host project clean: in git repos the vault artifact directories are appended to `.gitignore`, strict-JSON `tsconfig.json` files get the artifact directories added to `\"exclude\"` so stored source copies under `raw/` do not break the host typecheck (commented JSONC tsconfigs are left untouched with a warning), and linter configs that still cover the artifact directories produce an advisory warning. All hygiene edits are skipped when `SWARMVAULT_OUT` keeps artifacts outside the repo.\n- `swarmvault install --agent aider` installs `CONVENTIONS.md` and wires `.aider.conf.yml` to read it when that config is valid YAML.\n- `swarmvault install --agent antigravity` writes `.agents/rules/swarmvault.md` and `.agents/workflows/swarmvault.md`; reinstall removes older fully managed `.agent/` files.\n- `swarmvault mcp` exposes tools and resources for page search, page reads, source listing, graph stats, graph status, symbol caller lookup with call-site evidence (`graph_callers`), code-only graph updates (optionally per-file), graph clustering refresh, community lookup, hyperedges, query, context-pack build/read/list, task start/update/finish/list/read/resume, compatibility memory tasks, vault doctor, retrieval status/rebuild/doctor, ingest, compile, and lint.\n\n## Defaults to preserve\n\n- Keep raw source material immutable under `raw/`.\n- Save useful answers unless the user explicitly wants ephemeral output.\n- Prefer reviewable flows such as `compile --approve`, `review`, and `candidate` when a change should not activate silently.\n- Treat provider setup as part of serious vault operation. If only `heuristic` is configured, say so clearly.\n- When a vault uses the `profile` block in `swarmvault.config.json`, respect it as the deterministic behavior layer. `swarmvault.schema.md` still defines the human intent layer.\n\nFile v3.20.0:README.md\n\n# SwarmVault Skill\n\nUse the SwarmVault skill when you want a local-first knowledge vault that compiles books, articles, notes, transcripts, chat exports, emails, calendars, datasets, spreadsheets, slide decks, screenshots, URLs, code, and research captures into durable markdown pages, a searchable graph, dashboards, resumable chat sessions, static AI export packs, context packs, a task memory ledger, and reviewable outputs on disk.\n\nSwarmVault is built on the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: keep a durable wiki between you and raw sources using a three-layer architecture (raw sources, wiki, schema). The LLM does the bookkeeping — cross-referencing, consistency, updating — while you curate sources and think about what they mean. SwarmVault turns that pattern into a local toolchain with graph navigation, search, review flows, automation, and optional provider-backed synthesis.\n\n## Install\n\nInstall the skill from ClawHub:\n\n```bash\nclawhub install swarmvault\n```\n\nInstall the CLI it depends on:\n\n```bash\nnpm install -g @swarmvaultai/cli\nswarmvault --version\nswarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./meeting.srt --guide\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault source session transcript-or-session-id\nswarmvault chat \"What should the next agent know?\"\nswarmvault export ai --out ./exports/ai\n```\n\nRequirements:\n\n- Node `>=24`\n- A working `swarmvault` or `vault` binary on `PATH`\n\nUpdate paths:\n\n```bash\nclawhub update swarmvault\nnpm install -g @swarmvaultai/cli@latest\n```\n\n## When To Use This Skill\n\n- You want knowledge work to stay on disk instead of disappearing into chat history.\n- The repo already contains `swarmvault.config.json` or `swarmvault.schema.md`.\n- You want markdown wiki pages, graph artifacts, local search, approvals, candidates, and MCP exposure from the same workspace.\n- You want resumable conversations over the compiled wiki and static handoff bundles for other tools.\n- You want a save-first compile/query/review loop for source collections, codebases, or research material.\n- You want one workflow for mixed non-code material such as EPUBs, CSV/TSV files, XLSX workbooks, PPTX decks, transcripts, Slack exports, mailbox files, and calendar exports.\n\n## Quickstart\n\n```bash\nswarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault quickstart ./your-repo --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault init --obsidian --profile personal-research\nswarmvault source add ./exports/customer-call.srt --guide\nswarmvault source session file-customer-call-srt-12345678\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./src --repo-root .\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault add https://arxiv.org/abs/2401.12345\nswarmvault compile --max-tokens 120000\nswarmvault diff\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault query \"What is the auth flow?\"\nswarmvault context build \"Implement the auth refactor\" --target ./src --budget 8000\nswarmvault task start \"Implement the auth refactor\" --target ./src --agent codex\nswarmvault doctor --repair\nswarmvault graph blast ./src/index.ts\nswarmvault graph status ./src\nswarmvault check-update ./src\nswarmvault graph stats\nswarmvault graph validate --strict\nswarmvault update ./src\nswarmvault graph cluster\nswarmvault cluster-only\nswarmvault graph tree --output ./exports/tree.html\nswarmvault tree --output ./exports/tree.html\nswarmvault graph serve\nswarmvault graph export --report ./exports/report.html\nswarmvault graph export --callflow ./exports/callflow.html\nswarmvault graph export --obsidian ./exports/graph-vault\nswarmvault graph export --neo4j ./exports/graph.cypher\nswarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json\nswarmvault chat \"What should the next agent know?\"\nswarmvault chat --resume <session-id> \"What changed?\"\nswarmvault export ai --out ./exports/ai\nswarmvault clone https://github.com/owner/repo --no-viz\nswarmvault mcp\n```\n\nFor the fastest scratch walkthrough of a local file, local repo, public GitHub repo, or docs tree, run `swarmvault quickstart ./path`, `swarmvault quickstart ./path --no-serve`, `swarmvault scan ./path --no-viz`, or `swarmvault clone https://github.com/owner/repo --branch main --no-viz`. `quickstart` is the beginner-friendly alias for `scan`: it initializes the current directory as a vault, ingests that input, compiles immediately, opens the graph viewer by default, and writes `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/`. Interactive file and directory runs show bounded stderr progress with the active file while JSON, MCP, watch, and CI-style flows stay quiet. Run `swarmvault next` when you want a read-only status check that recommends init, ingest, compile, query, review, or refresh commands. Use `quickstart --mcp`, `scan --mcp`, or `clone --mcp` when the next step should be an MCP stdio server.\n\nIf you want the same zero-config walkthrough without supplying your own inputs first, run `swarmvault demo --no-serve`. It creates a temporary demo vault with bundled sources and compiles it immediately.\n\nFor very large graphs, `swarmvault graph serve` and `swarmvault graph export --html` automatically start in overview mode. Add `--full` when you explicitly want the full canvas rendered. `swarmvault graph share --post` prints a compact copyable summary, `swarmvault graph share --svg [path]` writes a 1200x630 visual card, `swarmvault graph share --bundle [dir]` writes a portable share kit for posting, linking, or screenshotting, `swarmvault graph cycles` finds deterministic directed cycles, `swarmvault graph callers <symbol>` lists every caller of a symbol from graph call edges with exact file:line call-site evidence — it scans only the files the graph identifies as callers, so who-calls and impact-of-change questions skip repo-wide grep, `swarmvault graph status [path]` and `swarmvault check-update [path]` check graph/report freshness without writing watch artifacts, `swarmvault graph stats` prints lightweight graph counts and relation mix, `swarmvault graph validate [graph] --strict` checks duplicate ids, dangling references, confidence bounds, and conflicted-edge evidence before export/merge/push workflows, `swarmvault graph update [path]` and `swarmvault update [path]` block unexpected node/edge drops unless `--force` is explicit, `swarmvault graph update --file <path>` (repeatable) is the code-only fast path that refreshes just the named files instead of walking every tracked root — concurrent refreshes coalesce through a lock plus queue under `state/watch/`, `swarmvault watch [path] --once` targets one repo root without persisting watch config, `swarmvault graph query` accepts relation/context/evidence/node/language filters for focused traversal, `swarmvault graph tree [--output <html>]` / `swarmvault tree [--output <html>]` writes an interactive source/module/symbol tree with a node inspector, `swarmvault graph merge <graph...> --out <path>` / `swarmvault merge-graphs <graph...> --out <path>` combines SwarmVault or node-link graph JSON, `swarmvault graph cluster [--resolution <n>]` and `swarmvault cluster-only [vault]` recompute communities and graph report artifacts from the existing graph without re-ingest, and `graph export` also supports `--html-standalone`, `--json`, `--callflow`, `--obsidian`, `--canvas`, and `--neo4j` when you need richer sharing, Obsidian-native artifacts, or a Neo4j-ready Cypher import. `swarmvault diff` compares the current graph against the last committed graph so you can inspect graph-level changes after a compile.\n\n`swarmvault context build \"<goal>\" --target <path-or-node> --budget <tokens>` creates an agent-ready evidence pack from the compiled vault. It saves JSON under `state/context-packs/`, writes a markdown companion under `wiki/context/`, reports omitted items when the token budget is too small, and can print `markdown`, `json`, or `llms` output for kickoff prompts and handoffs.\n\n`swarmvault chat \"question\"` creates a persisted conversation over the compiled vault. Each turn writes structured state under `state/chat-sessions/` and a markdown transcript under `wiki/outputs/chat-sessions/`; use `swarmvault chat --resume <id> \"follow-up\"`, `chat --list`, and `chat --delete <id>` to manage saved sessions.\n\n`swarmvault export ai --out <dir>` writes a static handoff pack for other agents and crawlers. The pack includes `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, `ai-readme.md`, and per-page `.txt`/`.json` siblings so the compiled wiki can be consumed without starting the viewer or MCP server.\n\n`swarmvault task start \"<goal>\" --target <path-or-node>` creates a durable task ledger and automatically links an initial context pack. Use `swarmvault task update <id> --note|--decision|--changed-path|--context-pack`, `swarmvault task finish <id> --outcome <text>`, and `swarmvault task resume <id> --format markdown|json|llms` to preserve decisions, evidence, touched files, outcomes, and follow-ups for the next agent. The older `memory` commands remain compatibility aliases.\n\n`swarmvault doctor` is the quickest whole-vault health check before an agent handoff or viewer session. It reports graph, retrieval, review queue, watch status, migration, managed-source, and task state; `--repair` rebuilds safe derived retrieval artifacts. The same checks are available in the graph viewer workbench and through MCP as `doctor_vault`; the workbench also shows prioritized next actions, check details, copyable suggested commands, explicit capture modes, title/tag capture fields, editable context/task token budgets, and action receipts.\n\nThe default `heuristic` provider is a valid local/offline starting point. Add a model provider in `swarmvault.config.json` when you want richer synthesis quality or optional capabilities such as embeddings, vision, or image generation. The recommended fully-local setup is `ollama pull gemma4` wired up as the `compileProvider` and `queryProvider` (see the root README for the exact config block). Any supported provider works - OpenAI, Anthropic, Gemini, OpenRouter, Groq, Together, xAI, Cerebras, openai-compatible, or custom. Use `swarmvault provider add|list|show|remove` for config-preserving provider registry edits. Code files are always parsed locally via tree-sitter; only non-code text or image sources go to configured model providers.\n\n`swarmvault init --profile` accepts `default`, `personal-research`, or a comma-separated preset list such as `reader,timeline`. For a custom vault style, edit the `profile` block in `swarmvault.config.json` directly; `swarmvault.schema.md` stays the human-written intent layer. The `personal-research` preset also enables `profile.guidedIngestDefault` and `profile.deepLintDefault`, so guided ingest/source and lint flows are on by default until you opt out with `--no-guide` or `--no-deep`.\n\nFor local semantic graph query without API keys, point `tasks.embeddingProvider` at an embedding-capable local backend such as Ollama, not `heuristic`.\n\nWith an embedding-capable provider available, SwarmVault can also merge semantic page matches into local search by default. `tasks.embeddingProvider` is the explicit way to choose that backend, but SwarmVault can also fall back to a `queryProvider` with embeddings support. Set `retrieval.rerank: true` when you want the configured `queryProvider` to rerank the merged top hits before answering.\n\nAudio and video ingest use `tasks.audioProvider` when you configure a provider with `audio` capability. The fully-local option is `swarmvault provider setup --local-whisper --apply`, which installs a `local-whisper` provider, downloads a whisper.cpp ggml model into `~/.swarmvault/models/`, and assigns `tasks.audioProvider` so voice memos, meetings, interviews, and video audio transcribe with no API keys and no network calls. Local video needs `ffmpeg`; public video URL ingest with `--video` needs `yt-dlp`. YouTube transcript ingest works without a model provider. If you want to pin graph clustering instead of using the adaptive default and its oversized/low-cohesion community split pass, set `graph.communityResolution` in `swarmvault.config.json` or run `swarmvault graph cluster --resolution <n>` for one recompute.\n\nSet `SWARMVAULT_OUT=<dir>` when generated `raw/`, `wiki/`, `state/`, `agent/`, and `inbox/` artifacts should be isolated from the source tree. Config and schema files remain in the project root, which keeps shared source worktrees clean while still giving agents the same vault contract.\n\n`init`, `quickstart`, `scan`, and `clone` do not write project-local agent rule files by default. Run `swarmvault install --agent <agent> [--scope project|user]` for explicit installs, use `swarmvault install status --agent <agent>` for read-only status, or set `agents` in `swarmvault.config.json` and pass `--install-agent-rules` when you intentionally want configured targets installed together.\n\n`swarmvault lint --deep --web` augments deep-lint findings with external evidence from a configured `webSearch` adapter. Web search is currently scoped to deep lint; compile, query, and explore stay on local vault state plus your configured LLM providers.\n\nWhen the vault lives inside a git repo, `ingest`, `compile`, and `query` also accept `--commit` so generated `wiki/` and `state/` changes can be committed immediately. `compile --max-tokens <n>` trims lower-priority pages when you need bounded wiki output for a tighter context window.\n\nSource-scoped artifacts are intentionally split by role:\n\n| Artifact | Created by | Purpose |\n|----------|-----------|---------|\n| Source brief | `source add`, `ingest` (always) | Auto summary written to `wiki/outputs/source-briefs/` |\n| Source review | `source review`, `source add --guide`, `ingest --review`, `ingest --guide` | Lighter staged assessment in `wiki/outputs/source-reviews/` |\n| Source guide | `source guide`, `source add --guide`, `ingest --guide` | Guided walkthrough with approval-bundled updates in `wiki/outputs/source-guides/` |\n| Source session | `source session`, `source add --guide`, `ingest --guide` | Resumable workflow state in `wiki/outputs/source-sessions/` and `state/source-sessions/` |\n\nSupported non-code ingest includes `.pdf`, the full Word family (`.docx`, `.docm`, `.dotx`, `.dotm`), `.rtf`, `.odt`, `.odp`, `.ods`, `.epub`, `.csv`, `.tsv`, the full Excel family (`.xlsx`, `.xlsm`, `.xlsb`, `.xls`, `.xltx`, `.xltm`), the full PowerPoint family (`.pptx`, `.pptm`, `.potx`, `.potm`), `.ipynb` (Jupyter notebooks), `.bib` (BibTeX), `.org` (Org-mode), `.adoc`/`.asciidoc`, `.srt`, `.vtt`, Slack exports, `.eml`, `.mbox`, `.ics`, audio files (`.mp3`, `.wav`, `.m4a`, `.aac`, `.ogg`, `.webm`, and other `audio/*` inputs) through `tasks.audioProvider`, video files (`.mp4`, `.mov`, `.m4v`, `.mkv`, `.avi`, and other `video/*` inputs) through `ffmpeg` plus `tasks.audioProvider`, public video URLs with `--video` through `yt-dlp` plus `tasks.audioProvider`, direct YouTube transcript URLs, images (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.tif`, `.tiff`, `.svg`, `.ico`, `.heic`, `.heif`, `.avif`, `.jxl`), markdown/MDX/text notes, structured config/data (`.json`, `.jsonc`, `.json5`, `.yaml`, `.toml`, `.xml`, `.ini`, `.conf`, `.cfg`, `.env`, `.properties`) with schema hints, common developer manifests (`package.json`, `tsconfig.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `go.sum`, `Dockerfile`, `Makefile`, `LICENSE`, `.gitignore`, `.editorconfig`, and similar) via content-sniffed text ingest so they are never silently dropped, browser clips, and research URLs captured through `swarmvault add`.\n\nSupported code ingest covers `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, `.tsx`, `.sh`, `.bash`, `.zsh`, `.py`, `.go`, `.rs`, `.java`, `.kt`, `.kts`, `.scala`, `.sc`, `.dart`, `.lua`, `.zig`, `.cs`, `.c`, `.cc`, `.cpp`, `.cxx`, `.h`, `.hh`, `.hpp`, `.hxx`, `.php`, `.rb`, `.ps1`, `.psm1`, `.psd1`, `.ex`, `.exs`, `.ml`, `.mli`, `.m`, `.mm`, `.res`, `.resi`, `.sol`, `.vue`, `.svelte`, `.jl`, `.v`, `.vh`, `.sv`, `.svh`, `.r`, `.R`, `.css`, `.html`, `.htm`, `.sql`, plus extensionless executable scripts with `#!/usr/bin/env node|python|ruby|bash|zsh` shebangs. Parser-backed local analysis extracts symbols, imports, local module references, dynamic JS/TS imports, Julia modules/types/functions, and Verilog/SystemVerilog modules/interfaces/packages/instantiations; SQL also emits table/view symbols plus read/write/join/reference graph edges. R emits an explicit parser diagnostic until a safe packaged grammar exists.\n\n## What The Skill Package Includes\n\n- `SKILL.md` - operational instructions for the model\n- [`examples/quickstart.md`](examples/quickstart.md) - first-run setup flow\n- [`examples/repo-workflow.md`](examples/repo-workflow.md) - repo ingest, compile, review, and graph workflow\n- [`examples/graph-first-agent-workflow.md`](examples/graph-first-agent-workflow.md) - graph-first Claude Code onboarding, hook-enforced graph reads, and automatic refresh\n- [`examples/research-workflow.md`](examples/research-workflow.md) - research capture and query workflow\n- [`references/commands.md`](references/commands.md) - high-signal command cheat sheet\n- [`references/artifacts.md`](references/artifacts.md) - what shows up under `raw/`, `wiki/`, and `state/`\n- [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md) - common setup and runtime fixes\n- [`validation/smoke-prompts.md`](validation/smoke-prompts.md) - release-validation prompts and expected outcomes\n\nThe published ClawHub package is intentionally text-only in this release.\n\n## Core Workflow\n\n1. Run `swarmvault next` when you need orientation before taking action.\n2. Initialize the vault with `swarmvault init`.\n3. Treat `swarmvault.schema.md` as the vault contract before serious compile or query work.\n4. Use `swarmvault source add` when the input is a recurring local file, local directory, public GitHub repo root, or docs hub that should stay registered. Add `--branch`, `--ref`, or `--checkout-dir` for pinned public GitHub repo sources.\n5. Add one-off material with `swarmvault ingest`, `swarmvault add`, or `swarmvault inbox import`.\n6. Use `swarmvault ingest --guide`, `swarmvault source add --guide`, `swarmvault source reload --guide`, `swarmvault source guide <id>`, or `swarmvault source session <id>` when you want the stronger guided-session workflow. Set `profile.guidedIngestDefault: true` when guided mode should be the default for ingest/source commands, and use `--no-guide` to force the lighter path for a specific run. Profiles using `guidedSessionMode: \"canonical_review\"` stage approval-queued canonical page edits; `insights_only` profiles keep exploratory synthesis under `wiki/insights/`.\n7. Compile with `swarmvault compile`, use `compile --max-tokens <n>` when the generated wiki must fit a bounded context window, or use `compile --approve` when the change should land in the approval queue first.\n8. Inspect `wiki/`, `wiki/dashboards/`, and `state/` artifacts before broad re-search. When the vault lives inside git, `ingest|compile|query --commit` can commit those artifacts immediately after the run.\n9. Use `swarmvault query`, `swarmvault chat`, `swarmvault context build`, `swarmvault export ai`, `swarmvault task`, `swarmvault memory`, `swarmvault explore`, `swarmvault review`, `swarmvault candidate`, and `swarmvault lint` to keep the vault current, portable, and reviewable. Set `profile.deepLintDefault: true` when `lint` should run the advisory deep pass by default, and use `--no-deep` to force a structural-only run.\n10. Use `swarmvault doctor [--repair]` when the vault needs one health summary before deeper troubleshooting or handoff.\n11. Use `swarmvault graph share --post` for a quick copyable summary, `swarmvault graph share --svg [path]` for a visual share card, `swarmvault graph share --bundle [dir]` for a portable share kit, `swarmvault graph blast` for reverse-import impact checks, `swarmvault graph cycles` for directed cycle checks, `swarmvault graph status [path]` or `swarmvault check-update [path]` for read-only graph freshness checks, `swarmvault graph stats` for lightweight counts and relation mix, `swarmvault graph validate [graph] --strict` before export/merge/push workflows, `swarmvault graph update [path] --force` or `swarmvault update [path] --force` only when a large graph shrink is expected, `swarmvault graph query \"<seed>\" --context calls --evidence extracted` for focused relation-aware traversal, `swarmvault graph tree` for an interactive source/module/symbol tree, `swarmvault graph merge <graph...> --out <path>` for combining SwarmVault or node-link JSON, `swarmvault graph cluster` or `swarmvault cluster-only` for graph community/report refresh without re-ingest, `swarmvault graph serve` for the live workspace, detailed health workbench, prioritized next actions, explicit capture modes, title/tag capture fields, budgeted agent handoffs, and bookmarklet clipper, `swarmvault graph export --report` for a self-contained HTML report, `swarmvault graph export --callflow <path>` for a directed relationship HTML view, `swarmvault graph export --neo4j <path>` for a Neo4j-ready Cypher import, other `swarmvault graph export` formats, `swarmvault graph push neo4j`, or `swarmvault mcp` when the vault needs to be explored or shared elsewhere.\n\n## What SwarmVault Writes\n\n- `SWARMVAULT_OUT` can relocate generated artifact directories while keeping config and schema at the project root\n- `raw/sources/` and `raw/assets/` for canonical input storage\n- `wiki/` for compiled source, concept, entity, code, graph, and output pages\n- `wiki/outputs/source-briefs/` for recurring-source onboarding briefs\n- `wiki/outputs/source-sessions/` for resumable guided session anchors\n- `wiki/outputs/source-reviews/` for staged source-scoped review artifacts\n- `wiki/outputs/source-guides/` for guided source integration artifacts\n- `wiki/outputs/chat-sessions/` for persisted multi-turn chat transcripts\n- `wiki/exports/ai/` for static AI handoff packs with `llms.txt`, full text, JSON-LD graph data, manifests, and per-page siblings\n- `wiki/dashboards/` for recent sources, reading log, timeline, source sessions, source guides, research map, contradictions, and open questions\n- `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/` for post-ready text, visual graph summaries, HTML preview, and JSON metadata generated on compile\n- `wiki/context/` for markdown context-pack companions\n- `wiki/memory/` for task ledger index and markdown task pages\n- `wiki/candidates/` for staged concept/entity pages\n- `state/graph.json` for the compiled graph\n- `state/context-packs/` for saved JSON context packs with citations, token-budget accounting, included items, and omitted items\n- `state/chat-sessions/` for structured resumable chat session state\n- `state/memory/tasks/` for saved JSON task ledger records\n- `state/retrieval/` for the local retrieval index and manifest\n- `state/sources.json` plus `state/sources/<id>/` for managed-source registry state and working sync data\n- `state/approvals/` for compile approval bundles\n- `state/sessions/` and `state/jobs.ndjson` for saved run history\n\nGenerated guided artifacts and dashboards also carry Dataview-friendly fields such as `profile_presets`, `session_status`, `question_state`, `canonical_targets`, and `evidence_state` when you enable `profile.dataviewBlocks`.\n\n## Agent And MCP Integration\n\nRecommended per-repo onboarding for token-saving agent workflows:\n\n```bash\ncd <repo>\nswarmvault init && swarmvault ingest .\nswarmvault install --agent claude --hook --mcp --graph-first   # --graph-first opts in to search enforcement\nswarmvault hook install        # git-hook refresh on commit/checkout (pass a repo path when the repo lives below the vault root)\n```\n\nFor hook-capable agents, the installed hooks guide graph-first reads. The Claude Code hook injects graph-first instructions at session start — answer code-understanding questions with the plain `swarmvault graph query|explain|path` commands (avoid `--json`, which produces much larger output), `swarmvault query`, `swarmvault context build`, or `wiki/graph/report.md`, and read source files only when editing them — plus a graph staleness note. `swarmvault graph query \"<seed>\"` prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers where-is/what-calls questions without follow-up file reads. By default the hook is advisory: the first broad Grep/Glob/Bash search per session gets a one-time guidance note. Opt in to enforcement with `--graph-first` (persists `hooks.graphFirst: \"deny\"`), which denies that first search with the same guided redirect — repeating the search is then allowed, so work is never blocked. Either way the hook spawns a background `swarmvault graph update --file <path>` refresh after every Edit/Write. Searches scoped to vault artifact directories (`wiki/`, `raw/`, `state/`), single files, or search tools filtering piped output are never intercepted. `SWARMVAULT_GRAPH_FIRST=deny|context|off` overrides per session. The Codex, Gemini, Copilot, OpenCode, and Kilo hooks carry the same graph-first guidance with a session note plus a one-time search redirect appropriate to each tool's hook API.\n\n`swarmvault install --agent claude --mcp` also registers the SwarmVault MCP server in the project's `.mcp.json` (`{\"mcpServers\":{\"swarmvault\":{\"command\":\"swarmvault\",\"args\":[\"mcp\"]}}}`). Claude installs additionally write a project skill bundle at `.claude/skills/swarmvault/SKILL.md`, and `--scope user` installs the skill, hook, and settings once under `~/.claude` for all repos — the hook no-ops in repos without a compiled graph report.\n\n`swarmvault install --agent <agent>` also keeps the host project clean: in git repos the vault artifact directories are appended to `.gitignore`, strict-JSON `tsconfig.json` files get the artifact directories added to `\"exclude\"` so stored source copies under `raw/` do not break the host typecheck (commented JSONC tsconfigs are left untouched with a warning instead of a rewrite), and linter configs that still cover the artifact directories produce an advisory warning. Everything is skipped when `SWARMVAULT_OUT` keeps artifacts outside the repo.\n\nSupported agent installs:\n\n- `swarmvault install --agent codex --hook`\n- `swarmvault install --agent claude --hook --mcp`\n- `swarmvault install --agent cursor`\n- `swarmvault install --agent gemini --hook`\n- `swarmvault install --agent opencode --hook`\n- `swarmvault install --agent aider`\n- `swarmvault install --agent copilot --hook`\n- `swarmvault install --agent trae`\n- `swarmvault install --agent claw`\n- `swarmvault install --agent droid`\n- `swarmvault install --agent kiro`\n- `swarmvault install --agent kilo --hook`\n- `swarmvault install --agent hermes`\n- `swarmvault install --agent antigravity`\n- `swarmvault install --agent vscode`\n- `swarmvault install --agent amp`\n- `swarmvault install --agent augment`\n- `swarmvault install --agent adal`\n- `swarmvault install --agent bob`\n- `swarmvault install --agent cline`\n- `swarmvault install --agent codebuddy`\n- `swarmvault install --agent command-code`\n- `swarmvault install --agent continue`\n- `swarmvault install --agent cortex`\n- `swarmvault install --agent crush`\n- `swarmvault install --agent deepagents`\n- `swarmvault install --agent devin`\n- `swarmvault install --agent firebender`\n- `swarmvault install --agent iflow`\n- `swarmvault install --agent junie`\n- `swarmvault install --agent kilo-code`\n- `swarmvault install --agent kimi`\n- `swarmvault install --agent kode`\n- `swarmvault install --agent mcpjam`\n- `swarmvault install --agent mistral-vibe`\n- `swarmvault install --agent mux`\n- `swarmvault install --agent neovate`\n- `swarmvault install --agent openclaw`\n- `swarmvault install --agent openhands`\n- `swarmvault install --agent pochi`\n- `swarmvault install --agent qoder`\n- `swarmvault install --agent qwen-code`\n- `swarmvault install --agent replit`\n- `swarmvault install --agent roo-code`\n- `swarmvault install --agent trae-cn`\n- `swarmvault install --agent warp`\n- `swarmvault install --agent windsurf`\n- `swarmvault install --agent zencoder`\n\nExpose the vault over MCP with:\n\n```bash\nswarmvault mcp\n```\n\nThe MCP surface includes graph stats, read-only graph freshness (`graph_status`), symbol caller lookup with file:line call-site evidence (`graph_callers`), code-only graph refresh (`update_graph`, with an optional files array for per-file refreshes), graph clustering refresh, community lookup, hyperedges, context-pack build/read/list, task start/update/finish/list/read/resume, compatibility memory task, `doctor_vault`, and retrieval status/rebuild/doctor tools so host agents can request bounded evidence, keep a durable task ledger, keep the graph current after edits, and inspect vault health without shelling out to the CLI.\n\n## Links\n\n- Docs: https://www.swarmvault.ai/docs\n- Providers: https://www.swarmvault.ai/docs/providers\n- Troubleshooting: https://www.swarmvault.ai/docs/getting-started/troubleshooting\n- npm: https://www.npmjs.com/package/@swarmvaultai/cli\n- GitHub: https://github.com/swarmclawai/swarmvault\n\nFile v3.20.0:_meta.json\n\n{\n  \"ownerId\": \"kn74zxcqv7s16twr0bpw2xtd5d827ean\",\n  \"slug\": \"swarmvault\",\n  \"version\": \"3.20.0\",\n  \"publishedAt\": 1781263666062\n}\n\nFile v3.20.0:references/artifacts.md\n\n# Artifact Reference\n\nSwarmVault is save-first. The files on disk are the product.\n\n## Canonical Inputs\n\n- `swarmvault.schema.md` - vault instructions, naming rules, exclusions, freshness rules\n- `raw/sources/` - immutable canonical sources\n- `raw/assets/` - localized remote or imported assets\n- `state/sources.json` - managed-source registry for recurring directories, public repos, and docs hubs\n- `state/sources/<id>/` - managed-source working state such as shallow checkouts and crawl metadata\n\n## Compiled Knowledge\n\n- `wiki/sources/` - source pages\n- `wiki/concepts/` and `wiki/entities/` - promoted canonical pages\n- `wiki/code/` - parser-backed module pages\n- `wiki/projects/` - project rollups\n- `wiki/outputs/` - saved query and explore outputs\n- `wiki/outputs/source-briefs/` - source-scoped onboarding briefs for managed sources\n- `wiki/outputs/source-reviews/` - source-scoped review pages staged through approvals\n- `wiki/outputs/source-guides/` - guided source-integration pages that stage broader wiki updates for review\n- `wiki/outputs/source-sessions/` - resumable guided-session anchors plus question and answer state\n- `wiki/outputs/chat-sessions/` - persisted chat transcripts from `swarmvault chat`\n- `wiki/dashboards/` - recent sources, timeline, contradiction, and open-question dashboards\n- `wiki/context/` - markdown companions for saved agent context packs\n- `wiki/exports/ai/` - static AI handoff export with `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, `ai-readme.md`, and optional per-page siblings\n- `wiki/memory/` - task ledger index and markdown task pages\n- `wiki/candidates/` - staged concept/entity pages\n- `wiki/graph/report.md` - trust and orientation report\n- `wiki/graph/*.html` - optional graph export artifacts such as report, standalone viewer, tree, and directed callflow output\n- `wiki/graph/share-card.md` - post-ready graph summary generated by compile\n- `wiki/graph/share-card.svg` - 1200x630 visual graph share card generated by compile or `swarmvault graph share --svg`\n- `wiki/graph/share-kit/` - portable share bundle with markdown, post text, SVG, HTML preview, and JSON metadata generated by compile or `swarmvault graph share --bundle`\n\n## State And Review\n\n- `state/graph.json` - compiled graph artifact\n- `state/context-packs/` - JSON context-pack artifacts with citations, token-budget accounting, included items, and omitted items\n- `state/chat-sessions/` - structured session state for resumable `swarmvault chat` conversations\n- `state/memory/tasks/` - JSON task ledger records with decisions, changed paths, outcomes, and follow-ups\n- `state/retrieval/` - local retrieval index, SQLite FTS shard, and manifest\n- `state/code-index.json` - repo-aware symbol/import index\n- `state/extracts/` - extraction markdown and JSON sidecars for PDF, the full Word family, RTF, OpenDocument, EPUB, CSV/TSV, the full Excel family, the full PowerPoint family, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcript, Slack export, email, calendar, audio transcripts, video transcripts, YouTube transcript captures, structured config/data previews, and image sources\n- `state/approvals/` - review bundles from `compile --approve`\n- `state/benchmark.json` - latest benchmark/trust artifact\n- `state/watch/` - pending semantic refresh, watch status, and per-file graph refresh lock/queue artifacts used by `graph update --file`\n- `state/sessions/` - saved compile/query/explore/lint/watch history\n- `state/jobs.ndjson` - watch run log\n\n## How To Use These\n\n- Read generated pages before re-asking the same question.\n- Use report and approval artifacts to explain what changed.\n- Use context packs when another agent, reviewer, or future session needs bounded evidence instead of a broad vault search.\n- Use chat sessions when continuity across questions matters and the transcript should remain inspectable.\n- Use AI export packs when the compiled wiki needs to travel to another static tool without running a server.\n- Use tasks when a multi-step agent workflow should survive handoffs, branch switches, or future follow-up.\n- Prefer schema edits or new sources over editing generated provenance directly.\n\nFile v3.20.0:references/commands.md\n\n# Command Reference\n\n## Setup\n\n```bash\nswarmvault demo --no-serve\nswarmvault quickstart ./apps/api\nswarmvault quickstart ./docs/manual.pdf --no-serve\nswarmvault next\nswarmvault quickstart ./apps/api --no-serve\nswarmvault init\nswarmvault init --obsidian --profile personal-research\nswarmvault init --obsidian --profile reader,timeline\nswarmvault scan ./apps/api --no-serve\nswarmvault scan ./apps/api --no-viz\nswarmvault clone https://github.com/owner/repo --branch main --no-viz\nswarmvault clone https://github.com/owner/repo --mcp\nswarmvault --version\n```\n\n## Ingest and Capture\n\n```bash\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault source add ./exports/customer-call.srt --guide\nswarmvault source session <source-id-or-session-id>\nswarmvault source list\nswarmvault source reload --all\nswarmvault source review <source-id>\nswarmvault source guide <source-id>\nswarmvault source delete <source-id>\nswarmvault ingest <path-or-url>\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault ingest <path-or-url> --commit\nswarmvault ingest <path-or-url> --guide\nswarmvault ingest <directory> --repo-root .\nswarmvault add <url-or-doi-or-arxiv-id>\nswarmvault inbox import <path>\n```\n\n## Compile, Query, Review\n\n```bash\nswarmvault compile\nswarmvault compile --max-tokens 120000\nswarmvault compile --approve\nswarmvault diff\nswarmvault query \"<question>\"\nswarmvault query \"<question>\" --commit\nswarmvault chat \"What should the next agent know?\"\nswarmvault chat --resume <session-id> \"What changed?\"\nswarmvault chat --list\nswarmvault chat --delete <session-id>\nswarmvault context build \"<goal>\" --target ./src --budget 8000\nswarmvault context build \"<goal>\" --target concept:auth --format llms\nswarmvault context list\nswarmvault context show <context-pack-id>\nswarmvault task start \"<goal>\" --target ./src --agent codex\nswarmvault task update <task-id> --decision \"Keep the change local-first\"\nswarmvault task update <task-id> --changed-path packages/engine/src/memory.ts\nswarmvault task finish <task-id> --outcome \"Task completed\" --follow-up \"Run release smoke\"\nswarmvault task resume <task-id> --format llms\nswarmvault retrieval status\nswarmvault retrieval doctor --repair\nswarmvault doctor\nswarmvault doctor --repair\nswarmvault explore \"<question>\" --steps 3\nswarmvault lint\nswarmvault lint --conflicts\nswarmvault review list\nswarmvault review show <approval-id> --diff\nswarmvault review accept <approval-id>\nswarmvault candidate list\n```\n\n## Graph and Sharing\n\n```bash\nswarmvault graph serve\nswarmvault graph serve --full\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault graph blast ./src/index.ts\nswarmvault graph callers \"chargeCustomer\"\nswarmvault graph status ./src\nswarmvault check-update ./src\nswarmvault graph stats\nswarmvault graph cycles\nswarmvault graph validate --strict\nswarmvault graph cluster\nswarmvault cluster-only\nswarmvault graph update ./src\nswarmvault update ./src\nswarmvault graph update --file ./src/auth.ts --file ./src/db.ts\nswarmvault graph update ./src --force\nswarmvault graph refresh\nswarmvault graph query \"auth calls\" --context calls --evidence extracted --language typescript\nswarmvault graph tree --output ./tree.html\nswarmvault tree --output ./tree.html\nswarmvault graph merge ./graph.json ./other-graph.json --out ./merged-graph.json\nswarmvault merge-graphs ./graph.json ./other-graph.json --out ./merged-graph.json\nswarmvault graph export --html ./graph.html\nswarmvault graph export --report ./graph-report.html\nswarmvault graph export --html ./graph.html --full\nswarmvault graph export --html-standalone ./graph-standalone.html\nswarmvault graph export --callflow ./callflow.html\nswarmvault graph export --json ./graph.json --canvas ./graph.canvas\nswarmvault graph export --obsidian ./graph-vault\nswarmvault graph export --neo4j ./graph.cypher\nswarmvault export ai --out ./exports/ai\nswarmvault export ai --out ./exports/ai --no-page-siblings\nswarmvault graph push neo4j --dry-run\nswarmvault mcp\n```\n\n## Providers\n\n```bash\nswarmvault provider add router --type openrouter --model openrouter/auto --api-key-env OPENROUTER_API_KEY --capability chat --capability structured --task queryProvider\nswarmvault provider list\nswarmvault provider show router\nswarmvault provider remove router --fallback local\nswarmvault provider setup --local-whisper --apply\n```\n\n## Automation\n\n```bash\nswarmvault watch --lint --repo\nswarmvault watch --repo --code-only --once\nswarmvault graph status .\nswarmvault check-update .\nswarmvault watch ./src --once --code-only\nswarmvault graph validate --strict\nswarmvault graph update .\nswarmvault update .\nswarmvault graph update --file packages/engine/src/index.ts\nswarmvault graph update . --force\nswarmvault watch status\nswarmvault hook install\nswarmvault hook install packages/app   # repo below the vault root\nswarmvault schedule list\nswarmvault schedule run <job-id>\n```\n\n## Agent Installs\n\n```bash\nswarmvault install --agent codex --hook\nswarmvault install --agent claude --hook\nswarmvault install --agent claude --hook --mcp\nswarmvault install --agent claude --hook --mcp --graph-first\nswarmvault install --agent claude --hook --scope user\nswarmvault install --agent gemini --hook\nswarmvault install --agent opencode --hook\nswarmvault install --agent aider\nswarmvault install --agent copilot --hook\nswarmvault install --agent trae\nswarmvault install --agent claw\nswarmvault install --agent droid\nswarmvault install --agent kilo --hook\nswarmvault install --agent devin\nswarmvault install status --agent kilo --hook\nswarmvault install status --agent claude --hook --mcp\n```\n\nThe Claude Code hook guides graph-first reads: session-start graph instructions plus a staleness note, a one-time advisory note on the first broad Grep/Glob/Bash search per session, and a background `swarmvault graph update --file <path>` refresh after Edit/Write. Add `--graph-first` to opt in to enforcement (the first broad search is denied once with a guided redirect; repeating the search is allowed) — it persists `hooks.graphFirst: \"deny\"` in `swarmvault.config.json`, and `SWARMVAULT_GRAPH_FIRST=deny|context|off` overrides per session. `--mcp` registers the MCP server in the project `.mcp.json`; `--scope user` installs the Claude skill, hook, and settings under `~/.claude`.\n\nFile v3.20.0:examples/graph-first-agent-workflow.md\n\n# Graph-First Agent Workflow Example\n\nUse this when the user wants Claude Code (or another hook-capable agent) to answer code questions from the graph instead of broad search, with the graph kept fresh automatically as files change.\n\n## Commands\n\n```bash\ncd <repo>\nswarmvault init && swarmvault ingest .\nswarmvault install --agent claude --hook --mcp --graph-first\nswarmvault hook install\nswarmvault graph status .\nswarmvault graph query \"auth flow\"\nswarmvault graph explain \"src/auth.ts\"\nswarmvault graph path \"LoginForm\" \"SessionStore\"\nswarmvault graph callers \"chargeCustomer\"\nswarmvault query \"How does the auth flow work?\"\nswarmvault context build \"Refactor the auth flow\" --target ./src --budget 8000\nswarmvault graph update --file ./src/auth.ts\nswarmvault install status --agent claude --hook --mcp\n```\n\n## What To Check\n\n- `.claude/settings.json` contains the SwarmVault hook entries and `.claude/hooks/swarmvault-graph-first.js` exists after `install --agent claude --hook`\n- `.mcp.json` registers the `swarmvault` MCP server (`{\"mcpServers\":{\"swarmvault\":{\"command\":\"swarmvault\",\"args\":[\"mcp\"]}}}`) after `--mcp`\n- `.claude/skills/swarmvault/SKILL.md` exists as the project skill bundle\n- A new Claude Code session starts with injected graph-first instructions plus a staleness note when `wiki/graph/report.md` exists\n- With `--graph-first` installed, the first broad Grep/Glob/Bash search in a session is denied once with a redirect to the plain `graph query|explain|path` commands (the deny message warns against `--json`, which produces much larger output); repeating the same search is then allowed. Without the opt-in the hook stays advisory and only adds a one-time guidance note\n- Searches scoped to `wiki/`, `raw/`, `state/`, a single file, or search tools filtering piped output pass through without interception\n- `swarmvault graph callers \"chargeCustomer\"` lists every caller of the symbol from graph call edges with exact file:line call-site evidence (it scans only the files the graph identifies as callers), and the deny/redirect message recommends it for who-calls/impact-of-change questions\n- After the agent edits a file, a background `swarmvault graph update --file <path>` refresh runs and `swarmvault graph status .` reports the graph fresh again\n- Concurrent edit bursts coalesce through the refresh lock plus queue under `state/watch/` instead of stacking compiles\n- `graph_status` and `update_graph` are available over MCP for read-only freshness checks and code-only (optionally per-file) refreshes\n- `swarmvault hook install` adds the git `post-commit`/`post-checkout` refresh so branch switches stay current too\n\n## Guidance\n\n- Answer \"where is X / what calls Y / how is Z structured\" questions with the plain `graph query`, `graph explain`, and `graph path` commands before reading source files; `graph query \"<seed>\"` prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers the question without follow-up file reads. Read sources directly only when editing them, and avoid `--json` for these reads — it produces much larger output.\n- If a search is denied, run the suggested graph command first; retrying the same search is always allowed when the graph genuinely lacks the detail.\n- Enforcement is opt-in: install with `--graph-first` (persists `hooks.graphFirst: \"deny\"`), or set `hooks.graphFirst` in `swarmvault.config.json` later. The default without opt-in is `context` — session guidance without denying searches. `SWARMVAULT_GRAPH_FIRST=deny|context|off` overrides per session.\n- Use `swarmvault install --agent claude --hook --scope user` to set up `~/.claude` once for all repos; the hook no-ops in repos without a compiled graph report.\n- Codex, Gemini, Copilot, OpenCode, and Kilo installs carry the same graph-first guidance adapted to each tool's hook API.\n\nFile v3.20.0:examples/quickstart.md\n\n# Quickstart Example\n\nUse this when the user needs the shortest path from install to a working vault.\n\n## Commands\n\n```bash\nnpm install -g @swarmvaultai/cli\nswarmvault quickstart ./repo\nswarmvault quickstart ./notes.pdf --no-serve\nswarmvault next\nswarmvault quickstart ./repo --no-serve\nswarmvault demo --no-serve\nswarmvault init --obsidian\nswarmvault scan ./repo --no-serve\nswarmvault scan ./repo --no-viz\nswarmvault clone https://github.com/owner/repo --branch main --no-viz\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo\nswarmvault diff\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault graph blast ./src/index.ts\nswarmvault graph status ./src\nswarmvault check-update ./src\nswarmvault graph stats\nswarmvault graph validate --strict\nswarmvault update ./src\nswarmvault graph cluster\nswarmvault cluster-only\nswarmvault graph tree --output ./tree.html\nswarmvault tree --output ./tree.html\nswarmvault graph query \"auth calls\" --context calls --evidence extracted --language typescript\nswarmvault query \"What are the key concepts?\"\nswarmvault context build \"Explain the key concepts to the next agent\" --target ./repo --budget 8000\nswarmvault task start \"Explain the key concepts to the next agent\" --target ./repo --agent codex\nswarmvault retrieval status\nswarmvault doctor\nswarmvault graph serve\nswarmvault graph export --report ./graph-report.html\nswarmvault graph export --neo4j ./graph.cypher\nswarmvault merge-graphs ./graph.json ./other-graph.json --out ./merged-graph.json\nswarmvault chat \"What should the next agent know?\"\nswarmvault chat --resume <session-id> \"What changed?\"\nswarmvault export ai --out ./exports/ai\n```\n\n## What To Check\n\n- `swarmvault.schema.md` exists and reflects the vault contract\n- `swarmvault next` reports `uninitialized`, `initialized`, or `compiled` and recommends the next safe command without changing files\n- `demo --no-serve` leaves a temporary compiled vault behind even on a clean machine\n- `quickstart`, `quickstart --no-serve`, `scan --no-serve`, `scan --no-viz`, and `clone --no-viz` accept local files as well as directories and leave a compiled vault behind even when the viewer is not launched\n- `quickstart`, `scan`, and `clone` do not create project-local agent rule files unless `--install-agent-rules` is passed with configured agents\n- `state/sources.json` contains the managed source registry entry\n- `wiki/graph/report.md` exists after compile\n- `graph status` and `check-update` report whether tracked repo changes need `graph update`/`update` or a full `compile` without writing watch state\n- `watch [path] --once --code-only` can refresh one repo root without persisting watch config\n- `graph stats` prints lightweight graph counts and relation mix without opening the viewer\n- `graph validate --strict` checks graph artifact integrity before export, merge, push, or publish workflows\n- `graph cluster` and `cluster-only` refresh graph communities and report artifacts from the existing graph without another ingest\n- `graph query` can focus traversal with relation/context/evidence/node/language filters\n- `graph tree` and `tree` write an interactive source/module/symbol HTML tree with a node inspector when the user wants file-oriented browsing\n- `graph merge` and `merge-graphs` combine SwarmVault or node-link graph JSON artifacts\n- `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, and `wiki/graph/share-kit/` exist after compile; `graph share --post` prints copyable text, `graph share --svg [path]` writes the visual card, and `graph share --bundle [dir]` writes the portable share kit\n- `graph export --report` writes a shareable HTML report when the user wants a lighter artifact than the full workspace; `graph export --neo4j` writes a Cypher import file for Neo4j workflows\n- `wiki/outputs/source-briefs/` contains a source brief\n- `wiki/outputs/` contains the saved query answer\n- `wiki/outputs/chat-sessions/` and `state/chat-sessions/` contain the chat transcript and structured session state when `chat` is used\n- `wiki/context/` and `state/context-packs/` contain the saved context pack when `context build` is used\n- `wiki/exports/ai/` or the configured export directory contains `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, `ai-readme.md`, and optional page siblings when `export ai` is used\n- `wiki/memory/` and `state/memory/tasks/` contain task ledger artifacts when `task start` is used\n- `state/graph.json` and `state/retrieval/` exist\n- `swarmvault doctor` reports `ok` or gives concrete next commands such as `swarmvault compile` or `swarmvault retrieval rebuild`; `graph serve` shows those checks and commands in the workbench\n\n## Guidance\n\n- If the answer quality is weak, check whether the vault is still on the `heuristic` provider.\n- If the user is unsure what changed, point them at `wiki/` and `state/` before suggesting another compile.\n- When the vault lives in git, `swarmvault diff` is the quickest graph-level summary of what the last compile changed.\n\nFile v3.20.0:examples/repo-workflow.md\n\n# Repo Workflow Example\n\nUse this when the user wants to compile a codebase into durable module pages, graph artifacts, and reviewable outputs.\n\n## Commands\n\n```bash\nswarmvault init --obsidian\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo\nswarmvault compile --approve\nswarmvault diff\nswarmvault review list\nswarmvault review show <approval-id> --diff\nswarmvault review accept <approval-id>\nswarmvault query \"What is the auth flow?\"\nswarmvault chat \"What should the next agent know about auth?\"\nswarmvault context build \"Hand off the auth flow work\" --target ./src --budget 8000\nswarmvault task start \"Hand off the auth flow work\" --target ./src --agent codex\nswarmvault export ai --out ./exports/ai\nswarmvault doctor\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault graph tree --output ./tree.html\nswarmvault graph query \"auth calls\" --context calls --evidence extracted --language typescript\nswarmvault graph serve\n```\n\n## What To Check\n\n- `wiki/code/` contains module pages\n- `wiki/outputs/source-briefs/` contains a repo onboarding brief\n- `state/code-index.json` exists for repo-aware symbol/import resolution\n- `swarmvault diff` reflects the graph-level additions and removals when the vault is inside git\n- `state/approvals/` contains staged review bundles when `--approve` is used\n- `wiki/graph/report.md` highlights the important modules, bridge nodes, and contradictions\n- `graph query` filters help users focus on calls, imports, data edges, rationale edges, evidence classes, node types, or languages\n- `wiki/graph/tree.html` or the chosen tree export path helps users browse sources, modules, symbols, and connected edges as a file tree\n- `wiki/outputs/chat-sessions/` and `state/chat-sessions/` contain saved conversation state when `chat` is used for follow-up handoff\n- `wiki/context/` and `state/context-packs/` contain bounded handoff packs when `context build` is used\n- `wiki/exports/ai/` or the chosen export path contains static AI handoff files when `export ai` is used\n- `wiki/memory/` and `state/memory/tasks/` contain durable task records when `task start` is used\n- `swarmvault doctor` summarizes graph, retrieval, review, watch, migration, source, and task health before handoff; the live workbench shows the same details and suggested commands\n- `wiki/graph/share-card.md` gives a short summary for status updates, `wiki/graph/share-card.svg` gives a visual card, and `wiki/graph/share-kit/` gives a portable folder for posting, linking, or screenshotting\n\n## Guidance\n\n- Prefer reading `wiki/graph/report.md` and the relevant `wiki/code/*.md` pages before broad grep.\n- Use `swarmvault chat --resume <id>` when a repo question needs multiple follow-ups and the transcript should stay on disk.\n- Use `swarmvault context build` before handing a scoped repo task to another agent or reviewer.\n- Use `swarmvault export ai --out <dir>` when the compiled repo wiki needs to be consumed without starting a server.\n- Use `swarmvault task resume <id>` when a future agent needs the task summary, decisions, evidence, and follow-ups.\n- If organization is wrong, update `swarmvault.schema.md` first instead of hand-editing generated pages.\n- Use `swarmvault watch --lint --repo` plus `swarmvault hook install` when the repo should stay current automatically.\n\nFile v3.20.0:examples/research-workflow.md\n\n# Research Workflow Example\n\nUse this when the user is collecting papers, articles, books, datasets, slide decks, screenshots, or other mixed research sources into one vault.\n\n## Commands\n\n```bash\nswarmvault init\nswarmvault add https://arxiv.org/abs/2401.12345\nswarmvault add 10.1145/1234567.1234568\nswarmvault ingest ./paper.pdf\nswarmvault ingest ./interview.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest ./book.epub\nswarmvault ingest ./results.csv\nswarmvault ingest ./analysis.xlsx\nswarmvault ingest ./deck.pptx\nswarmvault inbox import ./capture-bundle\nswarmvault compile\nswarmvault doctor\nswarmvault query \"What are the main claims and conflicts?\"\nswarmvault chat \"What should I read next?\"\nswarmvault context build \"Review the main claims and conflicts\" --target \"main claims\" --budget 8000\nswarmvault export ai --out ./exports/ai\nswarmvault explore \"What should I read next?\" --steps 3\n```\n\n## What To Check\n\n- `raw/sources/` contains normalized markdown captures for `add`\n- `state/extracts/` contains PDF, DOCX, EPUB, CSV/TSV, XLSX, PPTX, audio, video, YouTube, or image extraction sidecars when relevant\n- `wiki/graph/report.md` surfaces contradictions, surprise links, and benchmark data\n- `swarmvault doctor` reports whether graph and retrieval artifacts are ready for query or handoff\n- `wiki/outputs/` contains saved query and explore outputs\n- `wiki/outputs/chat-sessions/` and `state/chat-sessions/` contain saved conversation state when multi-turn research questions should persist\n- `wiki/context/` and `state/context-packs/` contain saved review packs when `context build` is used\n- `wiki/exports/ai/` or the chosen export path contains static handoff files when `export ai` is used\n\n## Guidance\n\n- Use `swarmvault add` for research URLs and `swarmvault ingest` for direct local files.\n- If image extraction is weak, verify that a real `visionProvider` is configured.\n- If audio or video extraction is missing, verify that `tasks.audioProvider` points at a provider with `audio` capability. Local video also needs `ffmpeg`; public video URLs with `--video` need `yt-dlp`.\n- Use `swarmvault context build` when another agent or future session needs a bounded evidence bundle for review.\n- Use `swarmvault chat --resume <id>` when research follow-ups should keep their prior turns and citations together.\n- Use `swarmvault export ai --out <dir>` when another static tool should read the compiled research wiki.\n- Use `lint --conflicts` when the user specifically wants contradiction review.\n\nFile v3.20.0:skill-card.md\n\n## Description:\n\nUse SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack, task-ledger, static AI export, retrieval, and MCP artifacts to disk from books, notes, transcripts, exports, datasets, slide decks, files, URLs, code, and recurring source workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[waydelyle](https://clawhub.ai/user/waydelyle)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, researchers, and knowledge workers use this skill to operate SwarmVault as a local-first knowledge vault for compiling source material into durable wiki pages, graph artifacts, searchable outputs, review queues, context packs, task ledgers, static AI exports, and MCP-accessible workspace state.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill asks users to install a mutable global npm CLI that can read and write vault artifacts in projects.\n\nMitigation: Prefer project-scoped setup, confirm the installed CLI before use, and use SWARMVAULT_OUT or ignore rules to isolate generated outputs.\n\nRisk: Agent hooks and graph-first modes can persist workflow changes and intercept agent searches.\n\nMitigation: Avoid --scope user and --graph-first until reviewed; inspect install status before enabling hooks or MCP integration.\n\nRisk: Ingest, share, export, and provider workflows can expose sensitive project or source content.\n\nMitigation: Keep sensitive files such as .env out of ingests and review share, export, and provider settings before publishing or sending content to remote services.\n\n## Reference(s):\n\n- [SwarmVault documentation](https://www.swarmvault.ai/docs)\n- [Artifact Reference](references/artifacts.md)\n- [Command Reference](references/commands.md)\n- [LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and configuration examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May direct the agent to create or update local vault artifacts, graph exports, static AI export packs, context packs, task ledger entries, chat transcripts, review queues, and MCP configuration.]\n\n## Skill Version(s):\n\n3.20.0 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v3.20.0:TROUBLESHOOTING.md\n\n# Troubleshooting\n\n## `swarmvault` command not found\n\nThe ClawHub skill does not bundle the CLI binary by itself. Install the published package and verify it:\n\n```bash\nnpm install -g @swarmvaultai/cli\nswarmvault --version\n```\n\nIf the binary still is not found, check that npm's global bin directory is on `PATH`.\n\n## Node version too old\n\nSwarmVault requires Node `>=24`.\n\n```bash\nnode --version\n```\n\nUpgrade Node before troubleshooting provider or compile behavior.\n\n## The vault compiles, but quality is weak\n\nCheck whether the vault is still using the built-in `heuristic` provider. That is a valid local/offline default, but its synthesis is intentionally lighter. Add a model provider in `swarmvault.config.json` when you want richer synthesis quality or optional capabilities such as embeddings, vision, or image generation.\n\nFor local semantic graph query, `embeddingProvider` must point at an embedding-capable backend such as `ollama` or another OpenAI-compatible embeddings service. The built-in `heuristic` provider does not generate embeddings.\n\n## Audio or video files ingest, but no transcript appears\n\nAudio and video ingest need `tasks.audioProvider` to point at a provider with `audio` capability. Without that, SwarmVault still ingests the source and records an extraction warning instead of failing the whole run.\n\nThe quickest fully-local fix is `swarmvault provider setup --local-whisper --apply`, which installs a `local-whisper` provider (whisper.cpp shell-out), downloads the default ggml model into `~/.swarmvault/models/`, and wires `tasks.audioProvider` at it. If the command reports the binary missing, install whisper.cpp first (`brew install whisper-cpp` on macOS, `sudo apt install whisper.cpp` on Debian/Ubuntu) and re-run. Override binary or model paths with `localWhisper.binaryPath` / `localWhisper.modelPath` in `swarmvault.config.json` or `SWARMVAULT_WHISPER_BINARY` in the environment.\n\nLocal video extraction also needs `ffmpeg` on PATH or `SWARMVAULT_FFMPEG_BINARY`. Public video URL ingest with `swarmvault ingest --video <url>` or `swarmvault add --video <url>` needs `yt-dlp` on PATH or `SWARMVAULT_YTDLP_BINARY`.\n\nYouTube transcript ingest does not need a model provider, but it can still fail when the video has no accessible captions or the upstream transcript fetch path is unavailable.\n\n## Source reviews or dashboards did not appear\n\nIf you expected a source-scoped guide or review page, use one of these flows:\n\n```bash\nswarmvault ingest <input> --guide\nswarmvault source add <input> --guide\nswarmvault source session <source-id-or-session-id>\n```\n\nThen verify:\n\n- `wiki/outputs/source-briefs/`\n- `wiki/outputs/source-sessions/`\n- `wiki/outputs/source-guides/`\n- `wiki/dashboards/index.md`\n- `wiki/dashboards/timeline.md`\n- `wiki/dashboards/source-sessions.md`\n- `wiki/dashboards/source-guides.md`\n- `state/approvals/`\n\n## `wiki/graph/report.md`, share kit, or search artifacts are missing\n\nRun:\n\n```bash\nswarmvault next\nswarmvault compile\nswarmvault doctor\n```\n\nThen verify:\n\n- `wiki/graph/report.md`\n- `wiki/graph/share-card.md`\n- `wiki/graph/share-card.svg`\n- `wiki/graph/share-kit/`\n- `state/graph.json`\n- `state/retrieval/`\n\nIf the vault lives inside git and you want a quick graph-level delta, run `swarmvault diff`.\n\n## Artifacts appear in the wrong directory\n\nCheck whether `SWARMVAULT_OUT` is set:\n\n```bash\necho \"$SWARMVAULT_OUT\"\n```\n\nWhen it is set, generated `raw/`, `wiki/`, `state/`, `agent/`, and `inbox/` directories resolve under that output root. `swarmvault.config.json` and `swarmvault.schema.md` remain in the project root.\n\n## Graph status reports stale\n\nRun:\n\n```bash\nswarmvault graph status .\nswarmvault check-update .\n```\n\nIf it recommends `swarmvault graph update`, the detected changes are code-only and can use the faster graph refresh path; `swarmvault update` is the top-level alias for the same refresh. If it recommends `swarmvault compile`, graph/report artifacts are missing, a non-code tracked source changed, or a pending semantic refresh already exists.\n\nWhen you know exactly which files changed, `swarmvault graph update --file <path>` (repeatable) refreshes just those files instead of walking every tracked root. Concurrent per-file refreshes coalesce through a lock plus queue under `state/watch/`, so rapid edit bursts do not stack compiles. Installed Claude Code hooks run this automatically in the background after Edit/Write tools.\n\n`swarmvault graph update` and `swarmvault update` abort when the refreshed graph drops more than 25% of nodes or edges. Re-run with `swarmvault graph update . --force`, `swarmvault update . --force`, or `SWARMVAULT_FORCE_UPDATE=1` only when the shrink is expected, such as after deliberately deleting a large source tree.\n\nBefore exporting, merging, pushing, or publishing graph artifacts, run `swarmvault graph validate --strict` to catch dangling references, duplicate ids, or invalid confidence values.\n\n## Compile fails on a larger note set\n\nIf an older CLI fails with heap exhaustion, `Map maximum size exceeded`, or a bare `Unexpected end of JSON input`, upgrade SwarmVault and rerun compile:\n\n```bash\nnpm install -g @swarmvaultai/cli@latest\nswarmvault compile\n```\n\nCurrent releases bound source-analysis concurrency and graph projection during compile. If the error says `Failed to parse JSON file ...`, remove or restore the named derived state file and compile again; JSON state writes are atomic in current releases to reduce partial-file failures.\n\n## Agent rule files differ\n\nThat can be expected. SwarmVault owns only the managed block between `swarmvault:managed:start` and `swarmvault:managed:end`. The managed SwarmVault block should match across compatible agent rule files, but user-owned text before or after that block is preserved and may differ per tool.\n\nNew vaults do not receive agent rule files during `init`, `quickstart`, `scan`, or `clone` unless you pass `--install-agent-rules` with configured `agents`. For one-off setup, run `swarmvault install --agent <agent>` instead.\n\n## Vault doctor reports warnings\n\n`swarmvault doctor` is the broad health summary. It checks graph artifacts, retrieval, review queues, watch state, migrations, managed sources, and task ledgers, then prints concrete follow-up commands. The `swarmvault graph serve` workbench shows the same full check list with details and copyable suggested commands.\n\nIf you only need orientation and do not want any prompts, notices, repairs, or writes, run `swarmvault next` first. It returns `status`, key `paths`, `checks`, and prioritized `recommendations` in human or JSON output.\n\nSafe derived retrieval repairs can be applied with:\n\n```bash\nswarmvault doctor --repair\n```\n\nIf the graph or wiki pages are missing, run `swarmvault compile`; if review or candidate counts are high, inspect `swarmvault review list` and `swarmvault candidate list`.\n\n## Context pack is empty or missing expected evidence\n\nContext packs are built from compiled graph and search artifacts. Run `swarmvault compile` first when the vault is new, then build a narrower pack:\n\n```bash\nswarmvault context build \"Prepare the next agent\" --target ./src --budget 8000\n```\n\nThen verify:\n\n- `wiki/context/`\n- `state/context-packs/`\n\nIf many items are listed as omitted, increase `--budget` or narrow `--target`.\n\n## MCP client reports `[object Undefined]` or `no such column`\n\nFirst verify the installed CLI version used by the MCP client:\n\n```bash\nswarmvault --version\n```\n\nSwarmVault 3.14.1 and newer normalize optional MCP response fields and retry hyphenated retrieval targets with conservative SQLite FTS tokenization. Upgrade and restart the MCP client subprocess if you see `unacceptable kind of an object to dump [object Undefined]` from `query_vault`, `build_context_pack`, `start_task`, or `start_memory_task`, or if a hyphenated target such as `concept:distributionally-robust-receive-combining` reports `no such column`.\n\n```bash\nnpm install -g @swarmvaultai/cli@latest\n```\n\n## Task is missing or does not show in the graph\n\nTasks are durable local artifacts. Start or inspect them with:\n\n```bash\nswarmvault task list\nswarmvault task start \"Prepare the next agent\" --target ./src\nswarmvault task resume <task-id>\n```\n\nThen verify:\n\n- `wiki/memory/index.md`\n- `wiki/memory/tasks/`\n- `state/memory/tasks/`\n\nRun `swarmvault compile` after creating or updating tasks when you want task and decision nodes to appear in `state/graph.json` and the graph viewer. Existing `memory` commands remain compatibility aliases.\n\n## Agent searches are being denied\n\nSearch denial only happens after an explicit opt-in: installing with `swarmvault install --agent <agent> --hook --graph-first`, or setting `hooks.graphFirst: \"deny\"` in `swarmvault.config.json`. With that opt-in, the first broad Grep/Glob/Bash search per session is intercepted with a deny plus a redirect message pointing at the plain `swarmvault graph query|explain|path` commands (the message warns against `--json`, which produces much larger output). `swarmvault graph query \"<seed>\"` prints the top matches with page paths plus an inline excerpt of the best-matching wiki page, so one command usually answers where-is/what-calls questions without follow-up file reads. For who-calls and impact-of-change questions, the redirect message also recommends `swarmvault graph callers <symbol>`, which lists every caller from graph call edges with exact file:line call-site evidence instead of a repo-wide grep. This is a one-time guided redirect, not a block: repeating the same search is then allowed, so work is never stuck. Searches scoped to vault artifact directories (`wiki/`, `raw/`, `state/`), single files, or search tools filtering piped output are never intercepted.\n\nWithout the opt-in, hooks stay advisory (`context` mode): a one-time guidance note, no denial. To change or disable the behavior:\n\n```bash\nSWARMVAULT_GRAPH_FIRST=context   # session guidance only, no search interception\nSWARMVAULT_GRAPH_FIRST=off       # disable graph-first behavior entirely\n```\n\nOr set `hooks.graphFirst` to `deny`, `context`, or `off` in `swarmvault.config.json`. The default without any opt-in is `context`.\n\n## `swarmvault install` edited `.gitignore` or `tsconfig.json`\n\nThat is intentional host-project hygiene. `swarmvault install --agent <agent>` appends the vault artifact directories (`raw/`, `wiki/`, `state/`, `agent/`, `inbox/`) to `.gitignore` in git repos, adds them to a strict-JSON `tsconfig.json` `\"exclude\"` list so stored source copies under `raw/` do not break the host typecheck, and warns when linter configs still cover the artifact directories. Commented (JSONC) tsconfig files are never rewritten — a warning explains the manual edit instead.\n\nTo opt out, set `SWARMVAULT_OUT` so generated artifacts live outside the repo; the hygiene edits are skipped entirely.\n\n## Hook is not firing\n\nReinstall the hook in the project root and verify the settings entries:\n\n```bash\nswarmvault install --agent claude --hook\n```\n\nThen check that `.claude/settings.json` contains the SwarmVault hook entries (session start, search interception, and post-edit refresh matchers) and that `.claude/hooks/swarmvault-graph-first.js` exists. Reinstalling migrates older installed hook entries to the current matcher layout while preserving user-owned hook entries. For user-scope installs under `~/.claude` (`install --agent claude --hook --scope user`), remember the hook intentionally no-ops in repos without a compiled `wiki/graph/report.md`, so run `swarmvault compile` first if the session shows no graph-first behavior.\n\n## Agent install or hooks seem stale\n\nRe-run the relevant install command in the project root:\n\n```bash\nswarmvault install status --agent codex --hook\nswarmvault install --agent claude --hook\nswarmvault install --agent gemini --hook\nswarmvault install --agent opencode --hook\nswarmvault install --agent copilot --hook\nswarmvault install --agent kilo --hook\n```\n\nFor Aider:\n\n```bash\nswarmvault install --agent aider\n```\n\n## Update paths\n\nUpdate the skill:\n\n```bash\nclawhub update swarmvault\n```\n\nUpdate the CLI:\n\n```bash\nnpm install -g @swarmvaultai/cli@latest\n```\n\n## More Help\n\n- Docs: https://www.swarmvault.ai/docs\n- Providers: https://www.swarmvault.ai/docs/providers\n- Web troubleshooting: https://www.swarmvault.ai/docs/getting-started/troubleshooting\n- GitHub issues: https://github.com/swarmclawai/swarmvault/issues\n\nFile v3.20.0:validation/smoke-prompts.md\n\n# Smoke Prompts\n\nThese prompts are the human-readable validation set for the ClawHub skill and the installed-package release flow.\n\n## Maintainer validation prompt\n\nPrompt:\n\n> Verify the CLI surface before release.\n\nExpected shape:\n\n- runs `pnpm live:cli-surface` from the OSS repo before release preflight when CLI command coverage is in scope\n- expects the smoke to parse `packages/cli/src/index.ts` with the TypeScript compiler API\n- expects every stable command path and alias to be classified in the surface manifest\n- expects root `--help` to show the essential commands while hiding compatibility aliases from the default view\n- expects `--help` coverage across the full command tree plus direct JSON behavior checks for the main local workflows, including `swarmvault next`, `swarmvault chat`, and `swarmvault export ai`\n\n## First-run prompt\n\nPrompt:\n\n> Set up a SwarmVault workspace for this repo and explain what files I should inspect first.\n\nExpected shape:\n\n- initializes or confirms the vault\n- may use `swarmvault demo --no-serve` for the fastest zero-config walkthrough\n- may use `swarmvault quickstart <directory> --no-serve` as the beginner path for a quick local repo walkthrough\n- may use `swarmvault scan <directory> --no-serve` when the user asks for the older concise scan command\n- uses or suggests `swarmvault next` when the current workspace state is unclear\n- points at `swarmvault.schema.md`\n- mentions `wiki/` and `state/`\n- prefers `wiki/graph/report.md` once compile exists\n- mentions `wiki/graph/share-card.md`, `wiki/graph/share-card.svg`, `wiki/graph/share-kit/`, `swarmvault graph share --post`, `swarmvault graph share --svg`, or `swarmvault graph share --bundle` when the user wants a copyable, visual, or portable summary\n- mentions `swarmvault context build`, `wiki/context/`, or `state/context-packs/` when the user asks for agent handoff or bounded review context\n- mentions `swarmvault chat`, `wiki/outputs/chat-sessions/`, or `state/chat-sessions/` when the user asks for a reusable conversation over the vault\n- mentions `swarmvault export ai`, `llms.txt`, or `wiki/exports/ai/` when the user asks for a static handoff to another tool\n- mentions `swarmvault memory`, `wiki/memory/`, or `state/memory/tasks/` when the user asks for durable task memory or handoff history\n- uses or suggests `swarmvault doctor` when the user asks whether the vault is ready for handoff, query, or viewer inspection\n\n## Managed source prompt\n\nPrompt:\n\n> Register this public GitHub repo as a recurring source, sync it, and tell me what I should read first.\n\nExpected shape:\n\n- uses `swarmvault source add https://github.com/karpathy/micrograd` or the supplied repo root URL\n- may use `--branch`, `--ref`, or `--checkout-dir` when the prompt pins a branch, tag, commit, or reusable checkout\n- mentions `state/sources.json`\n- points at `wiki/outputs/source-briefs/` and `wiki/graph/report.md`\n- treats `source list` and `source reload --all` as the maintenance path\n\n## Repo understanding prompt\n\nPrompt:\n\n> Compile this repo into SwarmVault and tell me how auth works.\n\nExpected shape:\n\n- uses `ingest <dir> --repo-root .` and `compile`\n- reads generated module pages or graph report before broad search\n- saves the answer unless the user asks for ephemeral output\n- may build `swarmvault context build \"Explain auth\" --target ./src --budget 8000` when the next agent or review needs reusable bounded context\n\n## Context handoff prompt\n\nPrompt:\n\n> Build a bounded handoff pack for the next agent working on auth.\n\nExpected shape:\n\n- compiles first when graph/search artifacts are missing or stale\n- uses `swarmvault context build \"<goal>\" --target <path-or-node> --budget <tokens>`\n- points at both `wiki/context/` and `state/context-packs/`\n- mentions omitted items when the token budget is too small\n\n## Chat session prompt\n\nPrompt:\n\n> Ask the vault a question, resume with a follow-up, and show where the transcript is saved.\n\nExpected shape:\n\n- uses `swarmvault chat \"<question>\"`\n- captures the returned session id\n- uses `swarmvault chat --resume <id> \"<follow-up>\"`\n- points at both `wiki/outputs/chat-sessions/` and `state/chat-sessions/`\n- uses `swarmvault chat --list` or `swarmvault chat --delete <id>` when the user asks to manage saved sessions\n\n## Static AI export prompt\n\nPrompt:\n\n> Export this compiled vault as a static handoff pack for another tool.\n\nExpected shape:\n\n- compiles first when graph/search artifacts are missing or stale\n- uses `swarmvault export ai --out <dir>`\n- checks that `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, and `ai-readme.md` exist\n- mentions page sibling files when they are enabled\n\n## Task ledger prompt\n\nPrompt:\n\n> Start a durable task ledger for the next agent working on auth, record a decision, and show how to resume it.\n\nExpected shape:\n\n- uses `swarmvault task start \"<goal>\" --target <path-or-node>`\n- records a decision or note with `swarmvault task update <id>`\n- points at both `wiki/memory/` and `state/memory/tasks/`\n- uses `swarmvault task resume <id>` for the next-agent handoff\n- mentions that `query`, `explore`, and `context build` can attach to the task with `--task <id>`, with `--memory <id>` as a compatibility alias\n\n## Research prompt\n\nPrompt:\n\n> Add this paper URL to the vault and summarize the main claims and conflicts.\n\nExpected shape:\n\n- uses `swarmvault add`\n- may use `swarmvault ingest` for direct audio/video files, `swarmvault ingest --video <url>` for public video URLs, or direct YouTube transcript URLs\n- compiles ...","readmeExcerpt":"Skill: SwarmVault Owner: waydelyle Summary: Use SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack,... Tags: graph:3.20.0, knowledge:0.1.4, knowledge-base:3.20.0, latest:3.20.0, local-first:3.20.0, markdown:3.20.0, mcp:3.20.0, stable:0.7.31, swarmvault:3.20.0, v0.7:0.7.31, v0.7.27:0.7.27, v0.7.28:0.7.28 Version histor","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"clawhub install swarmvault"},{"language":"bash","snippet":"npm install -g @swarmvaultai/cli\nswarmvault --version\nswarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./meeting.srt --guide\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault source session transcript-or-session-id\nswarmvault chat \"What should the next agent know?\"\nswarmvault export ai --out ./exports/ai"},{"language":"bash","snippet":"clawhub update swarmvault\nnpm install -g @swarmvaultai/cli@latest"},{"language":"bash","snippet":"swarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault quickstart ./your-repo --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault init --obsidian --profile personal-research\nswarmvault source add ./exports/customer-call.srt --guide\nswarmvault source session file-customer-call-srt-12345678\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./src --repo-root .\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault add https://arxiv.org/abs/2401.12345\nswarmvault compile --max-tokens 120000\nswarmvault diff\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault query \"What is the auth flow?\"\nswarmvault context build \"Implement the auth refactor\" --target ./src --budget 8000\nswarmvault task start \"Implement the auth refactor\" --target ./src --agent codex\nswarmvault doctor --repair\nswarmvault graph blast ./src/index.ts\nswarmvault graph status ./src\nswarmvault check-update ./src\nswarmvault graph stats\nswarmvault graph validate --strict\nswarmvault update ./src\nswarmvault graph cluster\nswarmvault cluster-only\nswarmvault graph tree --output ./exports/tree.html\nswarmvault tree --output ./exports/tree.html\nswarmvault graph serve\nswarmvault graph export --report ./exports/report.html\nswarmvault graph export --callflow ./exports/callflow.html\nswarmvault graph export --obsidian ./exports/graph-vault\nswarmvault graph export --neo4j ./exports/graph.cypher\nswarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json\nswarmvault chat \"What should the next agent know?\"\nswarmvault chat --resume <session-id> \"What changed?\"\nswarmvault export ai --out ./exports/ai\nswarmvault clone https://github.com/owner/repo --no-viz\nswarmvault mcp"},{"language":"bash","snippet":"cd <repo>\nswarmvault init && swarmvault ingest .\nswarmvault install --agent claude --hook --mcp --graph-first   # --graph-first opts in to search enforcement\nswarmvault hook install        # git-hook refresh on commit/checkout (pass a repo path when the repo lives below the vault root)"},{"language":"bash","snippet":"swarmvault mcp"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: swarmvault\ndescription: \"Use SwarmVault when the user needs a local-first knowledge vault that writes durable markdown, graph, search, dashboard, review, chat-session, context-pack, task-ledger, static AI export, retrieval, and MCP artifacts to disk from books, notes, transcripts, exports, datasets, slide decks, files, URLs, code, and recurring source workflows.\"\nversion: \"3.20.0\"\nmetadata: '{\"openclaw\":{\"requires\":{\"anyBins\":[\"swarmvault\",\"vault\"]},\"install\":[{\"id\":\"node\",\"kind\":\"node\",\"package\":\"@swarmvaultai/cli\",\"bins\":[\"swarmvault\",\"vault\"],\"label\":\"Install SwarmVault CLI (npm)\"}],\"emoji\":\"🗃️\",\"homepage\":\"https://www.swarmvault.ai/docs\"}}'\n---\n\n# SwarmVault\n\nUse this skill when the user wants a local-first knowledge vault built on the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern — three layers (raw sources, wiki, schema) where the LLM maintains a durable wiki between you and raw sources. Also use it when the project already contains `swarmvault.config.json` or `swarmvault.schema.md`.\n\nFor onboarding, examples, command references, or troubleshooting, read the bundled `README.md`, `examples/`, `references/`, and `TROUBLESHOOTING.md` before improvising workflow advice.\n\n## Quick checks\n\n- Work from the vault root.\n- Use `swarmvault next` when you need a read-only orientation command before deciding whether to initialize, ingest, compile, query, review, or refresh.\n- If the vault does not exist yet, run `swarmvault init`.\n- Use `swarmvault demo --no-serve` when the user wants the fastest zero-config walkthrough before pointing SwarmVault at their own sources.\n- Use `swarmvault quickstart <file-or-directory-or-github-url>` as the beginner-friendly first-run path when the user wants init + ingest + compile + graph viewer in one command.\n- Use `swarmvault scan <file-or-directory-or-github-url> --no-serve`, `swarmvault scan <file-or-directory-or-github-url> --no-viz`, or `swarmvault clone <file-or-directory-or-github-url> --no-viz` when the user wants the fastest scratch pass over a local file, local repo, public GitHub repo, or docs tree without manually stepping through init + ingest + compile first; for GitHub URLs add `--branch`, `--ref`, or `--checkout-dir` when the user needs a pinned checkout. Use `scan --mcp` or `clone --mcp` when the next step should be an MCP stdio server. Use `swarmvault graph share --post` for copyable text, `swarmvault graph share --svg [path]` for a visual card, or `swarmvault graph share --bundle [dir]` for a portable folder with markdown, post text, SVG, HTML preview, and JSON metadata.\n- Use `swarmvault context build \"<goal>\" --target <path-or-node> --budget <tokens>` when the next agent, review, or handoff needs a bounded evidence pack instead of a broad vault search.\n- Use `swarmvault chat \"question\"` when a multi-turn conversation should survive handoff; resume with `swarmvault chat --resume <id> \"follow-up\"` and inspect saved transcripts under `wiki/outputs/cha"},{"path":"README.md","content":"# SwarmVault Skill\n\nUse the SwarmVault skill when you want a local-first knowledge vault that compiles books, articles, notes, transcripts, chat exports, emails, calendars, datasets, spreadsheets, slide decks, screenshots, URLs, code, and research captures into durable markdown pages, a searchable graph, dashboards, resumable chat sessions, static AI export packs, context packs, a task memory ledger, and reviewable outputs on disk.\n\nSwarmVault is built on the [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: keep a durable wiki between you and raw sources using a three-layer architecture (raw sources, wiki, schema). The LLM does the bookkeeping — cross-referencing, consistency, updating — while you curate sources and think about what they mean. SwarmVault turns that pattern into a local toolchain with graph navigation, search, review flows, automation, and optional provider-backed synthesis.\n\n## Install\n\nInstall the skill from ClawHub:\n\n```bash\nclawhub install swarmvault\n```\n\nInstall the CLI it depends on:\n\n```bash\nnpm install -g @swarmvaultai/cli\nswarmvault --version\nswarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./meeting.srt --guide\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault source session transcript-or-session-id\nswarmvault chat \"What should the next agent know?\"\nswarmvault export ai --out ./exports/ai\n```\n\nRequirements:\n\n- Node `>=24`\n- A working `swarmvault` or `vault` binary on `PATH`\n\nUpdate paths:\n\n```bash\nclawhub update swarmvault\nnpm install -g @swarmvaultai/cli@latest\n```\n\n## When To Use This Skill\n\n- You want knowledge work to stay on disk instead of disappearing into chat history.\n- The repo already contains `swarmvault.config.json` or `swarmvault.schema.md`.\n- You want markdown wiki pages, graph artifacts, local search, approvals, candidates, and MCP exposure from the same workspace.\n- You want resumable conversations over the compiled wiki and static handoff bundles for other tools.\n- You want a save-first compile/query/review loop for source collections, codebases, or research material.\n- You want one workflow for mixed non-code material such as EPUBs, CSV/TSV files, XLSX workbooks, PPTX decks, transcripts, Slack exports, mailbox files, and calendar exports.\n\n## Quickstart\n\n```bash\nswarmvault quickstart ./your-repo\nswarmvault quickstart ./whitepaper.pdf --no-serve\nswarmvault quickstart ./your-repo --no-serve\nswarmvault next\nswarmvault demo --no-serve\nswarmvault init --obsidian --profile personal-research\nswarmvault source add ./exports/customer-call.srt --guide\nswarmvault source session file-customer-call-srt-12345678\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault ingest ./src --repo-ro"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn74zxcqv7s16twr0bpw2xtd5d827ean\",\n  \"slug\": \"swarmvault\",\n  \"version\": \"3.20.0\",\n  \"publishedAt\": 1781263666062\n}"},{"path":"references/artifacts.md","content":"# Artifact Reference\n\nSwarmVault is save-first. The files on disk are the product.\n\n## Canonical Inputs\n\n- `swarmvault.schema.md` - vault instructions, naming rules, exclusions, freshness rules\n- `raw/sources/` - immutable canonical sources\n- `raw/assets/` - localized remote or imported assets\n- `state/sources.json` - managed-source registry for recurring directories, public repos, and docs hubs\n- `state/sources/<id>/` - managed-source working state such as shallow checkouts and crawl metadata\n\n## Compiled Knowledge\n\n- `wiki/sources/` - source pages\n- `wiki/concepts/` and `wiki/entities/` - promoted canonical pages\n- `wiki/code/` - parser-backed module pages\n- `wiki/projects/` - project rollups\n- `wiki/outputs/` - saved query and explore outputs\n- `wiki/outputs/source-briefs/` - source-scoped onboarding briefs for managed sources\n- `wiki/outputs/source-reviews/` - source-scoped review pages staged through approvals\n- `wiki/outputs/source-guides/` - guided source-integration pages that stage broader wiki updates for review\n- `wiki/outputs/source-sessions/` - resumable guided-session anchors plus question and answer state\n- `wiki/outputs/chat-sessions/` - persisted chat transcripts from `swarmvault chat`\n- `wiki/dashboards/` - recent sources, timeline, contradiction, and open-question dashboards\n- `wiki/context/` - markdown companions for saved agent context packs\n- `wiki/exports/ai/` - static AI handoff export with `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, `ai-readme.md`, and optional per-page siblings\n- `wiki/memory/` - task ledger index and markdown task pages\n- `wiki/candidates/` - staged concept/entity pages\n- `wiki/graph/report.md` - trust and orientation report\n- `wiki/graph/*.html` - optional graph export artifacts such as report, standalone viewer, tree, and directed callflow output\n- `wiki/graph/share-card.md` - post-ready graph summary generated by compile\n- `wiki/graph/share-card.svg` - 1200x630 visual graph share card generated by compile or `swarmvault graph share --svg`\n- `wiki/graph/share-kit/` - portable share bundle with markdown, post text, SVG, HTML preview, and JSON metadata generated by compile or `swarmvault graph share --bundle`\n\n## State And Review\n\n- `state/graph.json` - compiled graph artifact\n- `state/context-packs/` - JSON context-pack artifacts with citations, token-budget accounting, included items, and omitted items\n- `state/chat-sessions/` - structured session state for resumable `swarmvault chat` conversations\n- `state/memory/tasks/` - JSON task ledger records with decisions, changed paths, outcomes, and follow-ups\n- `state/retrieval/` - local retrieval index, SQLite FTS shard, and manifest\n- `state/code-index.json` - repo-aware symbol/import index\n- `state/extracts/` - extraction markdown and JSON sidecars for PDF, the full Word family, RTF, OpenDocument, EPUB, CSV/TSV, the full Excel family, the full PowerPoint family, Jupyter notebooks, BibTeX, Org-mode, AsciiDoc, transcript, Slack export, em"},{"path":"references/commands.md","content":"# Command Reference\n\n## Setup\n\n```bash\nswarmvault demo --no-serve\nswarmvault quickstart ./apps/api\nswarmvault quickstart ./docs/manual.pdf --no-serve\nswarmvault next\nswarmvault quickstart ./apps/api --no-serve\nswarmvault init\nswarmvault init --obsidian --profile personal-research\nswarmvault init --obsidian --profile reader,timeline\nswarmvault scan ./apps/api --no-serve\nswarmvault scan ./apps/api --no-viz\nswarmvault clone https://github.com/owner/repo --branch main --no-viz\nswarmvault clone https://github.com/owner/repo --mcp\nswarmvault --version\n```\n\n## Ingest and Capture\n\n```bash\nswarmvault source add https://github.com/karpathy/micrograd\nswarmvault source add ./exports/customer-call.srt --guide\nswarmvault source session <source-id-or-session-id>\nswarmvault source list\nswarmvault source reload --all\nswarmvault source review <source-id>\nswarmvault source guide <source-id>\nswarmvault source delete <source-id>\nswarmvault ingest <path-or-url>\nswarmvault ingest ./customer-call.mp3\nswarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ\nswarmvault ingest --video https://example.com/product-demo.mp4\nswarmvault ingest <path-or-url> --commit\nswarmvault ingest <path-or-url> --guide\nswarmvault ingest <directory> --repo-root .\nswarmvault add <url-or-doi-or-arxiv-id>\nswarmvault inbox import <path>\n```\n\n## Compile, Query, Review\n\n```bash\nswarmvault compile\nswarmvault compile --max-tokens 120000\nswarmvault compile --approve\nswarmvault diff\nswarmvault query \"<question>\"\nswarmvault query \"<question>\" --commit\nswarmvault chat \"What should the next agent know?\"\nswarmvault chat --resume <session-id> \"What changed?\"\nswarmvault chat --list\nswarmvault chat --delete <session-id>\nswarmvault context build \"<goal>\" --target ./src --budget 8000\nswarmvault context build \"<goal>\" --target concept:auth --format llms\nswarmvault context list\nswarmvault context show <context-pack-id>\nswarmvault task start \"<goal>\" --target ./src --agent codex\nswarmvault task update <task-id> --decision \"Keep the change local-first\"\nswarmvault task update <task-id> --changed-path packages/engine/src/memory.ts\nswarmvault task finish <task-id> --outcome \"Task completed\" --follow-up \"Run release smoke\"\nswarmvault task resume <task-id> --format llms\nswarmvault retrieval status\nswarmvault retrieval doctor --repair\nswarmvault doctor\nswarmvault doctor --repair\nswarmvault explore \"<question>\" --steps 3\nswarmvault lint\nswarmvault lint --conflicts\nswarmvault review list\nswarmvault review show <approval-id> --diff\nswarmvault review accept <approval-id>\nswarmvault candidate list\n```\n\n## Graph and Sharing\n\n```bash\nswarmvault graph serve\nswarmvault graph serve --full\nswarmvault graph share --post\nswarmvault graph share --svg ./share-card.svg\nswarmvault graph share --bundle ./share-kit\nswarmvault graph blast ./src/index.ts\nswarmvault graph callers \"chargeCustomer\"\nswarmvault graph status ./src\nswarmvault check-update ./src\nswarmvault graph stats\nswarmvault graph cycles\nswarmvault graph validate --strict\ns"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2951,"uniquenessScore":38,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:07:01.311Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T20:56:16.341Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}