### Install and verify SwarmVault CLI

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/TROUBLESHOOTING.md

Use these commands to install the global CLI package and confirm the installation.

```bash
npm install -g @swarmvaultai/cli
swarmvault --version
```

--------------------------------

### Install and Scan Repository

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Install the CLI globally and initiate a scan on a local directory to generate a knowledge graph.

```bash
npm install -g @swarmvaultai/cli
swarmvault scan ./your-repo       # point it at your own codebase or docs
# → knowledge graph opens in your browser
```

--------------------------------

### Install Cursor Agent

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Install the Cursor AI coding agent.

```bash
swarmvault install --agent cursor
```

--------------------------------

### Install Agents

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/references/commands.md

Commands for installing and configuring various AI agents.

```bash
swarmvault install --agent codex
swarmvault install --agent claude --hook
swarmvault install --agent gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent aider
swarmvault install --agent copilot --hook
swarmvault install --agent trae
swarmvault install --agent claw
swarmvault install --agent droid
```

--------------------------------

### Generate source guides and dashboards

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/TROUBLESHOOTING.md

Use these commands to trigger the generation of source-scoped guides and session reviews.

```bash
swarmvault ingest <input> --guide
swarmvault source add <input> --guide
swarmvault source session <source-id-or-session-id>
```

--------------------------------

### Agent Installs

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/references/commands.md

Commands for installing various AI agents.

```APIDOC
## Agent Installs

### Description
Commands for installing various AI agents.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
- **agent** (string) - Required - The name of the agent to install (e.g., codex, claude, gemini).
- **hook** (boolean) - Optional - Installs the agent with a hook.

#### Request Body
None

### Request Example
```bash
swarmvault install --agent codex
swarmvault install --agent claude --hook
swarmvault install --agent gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent aider
swarmvault install --agent copilot --hook
swarmvault install --agent trae
swarmvault install --agent claw
swarmvault install --agent droid
```

### Response
#### Success Response (200)
Command execution output.

#### Response Example
N/A
```

--------------------------------

### Install Other Supported Agents

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Install various other supported AI coding agents.

```bash
swarmvault install --agent codex
```

```bash
swarmvault install --agent goose
```

```bash
swarmvault install --agent aider
```

```bash
swarmvault install --agent trae
```

```bash
swarmvault install --agent droid
```

--------------------------------

### Install Packaged Skills with ClawHub

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.zh-CN.md

Install packaged skills for OpenClaw or ClawHub. This includes the SKILL.md, README, examples, and troubleshooting guides.

```bash
clawhub install swarmvault
```

--------------------------------

### Setup Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/references/commands.md

Commands for initializing and configuring SwarmVault.

```APIDOC
## Setup Commands

### Description
Commands for initializing and configuring SwarmVault.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
swarmvault demo --no-serve
swarmvault init
swarmvault init --obsidian --profile personal-research
swarmvault init --obsidian --profile reader,timeline
swarmvault scan ./apps/api --no-serve
swarmvault --version
```

### Response
#### Success Response (200)
Command execution output.

#### Response Example
N/A
```

--------------------------------

### Install GitHub Copilot with Hook

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Install the GitHub Copilot agent with a hook enabled.

```bash
swarmvault install --agent copilot --hook
```

--------------------------------

### Install agent integrations

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Commands to install rules for various supported AI agents.

```bash
swarmvault install --agent codex
```

```bash
swarmvault install --agent claude
```

```bash
swarmvault install --agent cursor
```

```bash
swarmvault install --agent goose
```

```bash
swarmvault install --agent pi
```

```bash
swarmvault install --agent gemini
```

```bash
swarmvault install --agent opencode
```

```bash
swarmvault install --agent aider
```

```bash
swarmvault install --agent copilot
```

```bash
swarmvault install --agent trae
```

```bash
swarmvault install --agent claw
```

```bash
swarmvault install --agent droid
```

--------------------------------

### Install and Build Project Dependencies

Source: https://github.com/swarmclawai/swarmvault/blob/main/CONTRIBUTING.md

Run these commands to install dependencies, lint, test, and build the project. These are standard commands for managing Node.js projects with pnpm.

```bash
pnpm install
pnpm lint
pnpm test
pnpm build
```

--------------------------------

### Install Swarmvault Agents

Source: https://github.com/swarmclawai/swarmvault/blob/main/docs/live-testing.md

Commands to install various AI agents for the Swarmvault CLI.

```bash
swarmvault install --agent codex
```

```bash
swarmvault install --agent claude
```

```bash
swarmvault install --agent opencode --hook
```

```bash
swarmvault install --agent gemini --hook
```

```bash
swarmvault install --agent copilot --hook
```

```bash
swarmvault install --agent aider
```

```bash
swarmvault install --agent trae
```

```bash
swarmvault install --agent claw
```

```bash
swarmvault install --agent droid
```

--------------------------------

### Install Swarmvault Agents

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.zh-CN.md

Install Swarmvault knowledge base rules into your coding agent. Use the `--hook` flag for agents that support it.

```bash
swarmvault install --agent claude --hook    # Claude Code + graph-first hook
```

```bash
swarmvault install --agent codex            # Codex
```

```bash
swarmvault install --agent cursor           # Cursor
```

```bash
swarmvault install --agent copilot --hook   # GitHub Copilot CLI + hook
```

```bash
swarmvault install --agent gemini --hook    # Gemini CLI + hook
```

```bash
swarmvault install --agent trae             # Trae
```

```bash
swarmvault install --agent claw             # Claw / OpenClaw skill target
```

```bash
swarmvault install --agent droid            # Droid / Factory rules target
```

--------------------------------

### Install Gemini CLI with Hook

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Install the Gemini CLI agent with a hook enabled.

```bash
swarmvault install --agent gemini --hook
```

--------------------------------

### Install Aider configuration

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/SKILL.md

Sets up CONVENTIONS.md and configures .aider.conf.yml for Aider integration.

```bash
swarmvault install --agent aider
```

--------------------------------

### Serve Full Graph Overview

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Starts the graph server in overview mode, suitable for large graphs. Add --full to render the entire canvas.

```bash
swarmvault graph serve --full
```

--------------------------------

### Install or update agents

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/TROUBLESHOOTING.md

Re-run installation commands to refresh agent hooks or install specific agents like Aider.

```bash
swarmvault install --agent claude --hook
swarmvault install --agent gemini --hook
swarmvault install --agent opencode --hook
swarmvault install --agent copilot --hook
```

```bash
swarmvault install --agent aider
```

--------------------------------

### Verify SwarmVault Installation

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Check the currently installed version of the SwarmVault CLI.

```bash
swarmvault --version
```

--------------------------------

### Install SwarmVault Agent

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/README.md

Use these commands to install different agents for SwarmVault. Some agents support a --hook option for specific integrations.

```bash
swarmvault install --agent codex
```

```bash
swarmvault install --agent claude --hook
```

```bash
swarmvault install --agent cursor
```

```bash
swarmvault install --agent gemini --hook
```

```bash
swarmvault install --agent opencode --hook
```

```bash
swarmvault install --agent aider
```

```bash
swarmvault install --agent copilot --hook
```

```bash
swarmvault install --agent trae
```

```bash
swarmvault install --agent claw
```

```bash
swarmvault install --agent droid
```

--------------------------------

### Install SwarmVault CLI

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/obsidian-plugin/README.md

Install the SwarmVault CLI globally using npm. This is a prerequisite for the Obsidian plugin.

```sh
npm i -g @swarmvaultai/cli
```

--------------------------------

### Install Agent with Graph-First Hook

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Install an AI coding agent with a graph-first hook enabled.

```bash
swarmvault install --agent claude --hook
```

--------------------------------

### Install agent-specific rules

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/SKILL.md

Installs rules for supported agents into the current project.

```bash
swarmvault install --agent codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid
```

--------------------------------

### Guided Session Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Commands for creating and managing resumable source sessions.

```bash
ingest --guide
source add --guide
source reload --guide
source guide <id>
source session <id>
```

--------------------------------

### Serve Graph Interface

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/quickstart.md

Start a local server to view the vault's graph interface. This allows for interactive exploration of the vault's data.

```bash
swarmvault graph serve
```

--------------------------------

### Install Swarmvault Hooks

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/repo-workflow.md

Install necessary Git hooks to enable automatic updates and linting when using `swarmvault watch --repo`.

```bash
swarmvault hook install
```

--------------------------------

### Install Agent-Specific Rules

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Install agent-specific rules into the current project using `swarmvault install --agent`. This command ensures agents understand the SwarmVault workspace contract. Hook-capable installs are available for several agents.

```bash
swarmvault install --agent <codex|claude|cursor|goose|pi|gemini|opencode|aider|copilot|trae|claw|droid>
```

```bash
swarmvault install --agent claude --hook
```

```bash
swarmvault install --agent gemini --hook
```

```bash
swarmvault install --agent opencode --hook
```

```bash
swarmvault install --agent copilot --hook
```

--------------------------------

### Install Agent Configurations

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Installs agent-specific configuration files for supported IDEs or all configured agents.

```typescript
import { installAgent, installConfiguredAgents } from "@swarmvaultai/engine";

const rootDir = process.cwd();

// Install for Claude Code with hook
const result = await installAgent(rootDir, "claude", { hook: true });
console.log("Target:", result.target);
console.log("All targets:", result.targets);
// Targets: CLAUDE.md, .claude/settings.json, .claude/hooks/swarmvault-graph-first.js

// Install for Cursor
await installAgent(rootDir, "cursor", {});
// Target: .cursor/rules/swarmvault.mdc

// Install for GitHub Copilot with hook
await installAgent(rootDir, "copilot", { hook: true });
// Targets: .github/copilot-instructions.md, AGENTS.md, .github/hooks/*

// Install all agents configured in swarmvault.config.json
await installConfiguredAgents(rootDir);
```

--------------------------------

### Install SwarmVault CLI

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/quickstart.md

Install the SwarmVault CLI globally using npm. This command is required before using any other swarmvault commands.

```bash
npm install -g @swarmvaultai/cli
```

--------------------------------

### Guided Ingest and Source Session Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/CHANGELOG.md

Commands for managing resumable guided source sessions and ingestion workflows.

```bash
swarmvault ingest --guide
```

```bash
swarmvault source add --guide
```

```bash
swarmvault source reload --guide
```

```bash
swarmvault source session <id>
```

```bash
swarmvault source guide <id>
```

--------------------------------

### Install agent hooks

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/SKILL.md

Installs graph-first hook or plugin support for agents that expose project hook APIs.

```bash
swarmvault install --agent claude|opencode|gemini|copilot --hook
```

--------------------------------

### Guided Session Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/README.md

Commands for utilizing the guided-session workflow for ingestion and source management.

```bash
swarmvault ingest --guide
```

```bash
swarmvault source add --guide
```

```bash
swarmvault source reload --guide
```

```bash
swarmvault source guide <id>
```

```bash
swarmvault source session <id>
```

--------------------------------

### Expose Vault via MCP Server

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Initializes and starts an MCP server to expose vault tools over stdio.

```typescript
import { createMcpServer, startMcpServer } from "@swarmvaultai/engine";

const rootDir = process.cwd();

// Create MCP server instance
const server = await createMcpServer(rootDir);

// MCP tools available:
// - workspace_info: Get vault configuration and paths
// - search_pages: Search compiled pages
// - read_page: Read page content by ID or path
// - list_sources: List all source manifests
// - query_vault: Query the vault
// - ingest_input: Ingest a file or URL
// - compile_vault: Compile the vault (supports maxTokens)
// - lint_vault: Run lint checks
// - blast_radius: Trace code change impact

// Start MCP server over stdio
await startMcpServer(rootDir);
```

--------------------------------

### Build SwarmVault Obsidian Plugin

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/obsidian-plugin/README.md

Install project dependencies and build the SwarmVault Obsidian plugin using pnpm. This command is for development purposes.

```sh
pnpm install
pnpm --filter @swarmvaultai/obsidian-plugin build
```

--------------------------------

### SwarmVault Graph Serve

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Starts the local graph workspace, serving API endpoints for search, page retrieval, and graph queries.

```APIDOC
## swarmvault graph serve

### Description
Start the local graph workspace backed by `state/graph.json`, `/api/search`, `/api/page`, and local graph query/path/explain endpoints.

It also exposes `/api/bookmarklet` and `/api/clip`, so a running local viewer can ingest the current browser page through a bookmarklet without leaving the browser.

### Method
CLI COMMAND

### Endpoint
N/A
```

--------------------------------

### Run Local Smoke Testing Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/docs/live-testing.md

Execute these commands from the OSS repository to verify the core vault flows and CLI installation path.

```bash
pnpm install
pnpm release:preflight
pnpm live:smoke:heuristic
pnpm exec playwright install chromium
pnpm live:smoke:heuristic:browser
pnpm live:smoke:neo4j
pnpm live:oss:corpus
pnpm skill:inspect
```

--------------------------------

### Run Built-in Demo

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Initialize a sample vault with three sources and open the graph viewer without requiring a local repository.

```bash
swarmvault demo
```

--------------------------------

### Initialize and Configure Swarmvault

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/references/commands.md

Commands for setting up the environment and initializing project configurations.

```bash
swarmvault demo --no-serve
swarmvault init
swarmvault init --obsidian --profile personal-research
swarmvault init --obsidian --profile reader,timeline
swarmvault scan ./apps/api --no-serve
swarmvault --version
```

--------------------------------

### Development Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/viewer/README.md

Standard commands for building, linting, and testing the package during development.

```bash
pnpm build
pnpm lint
pnpm test
```

--------------------------------

### Initialize Vault with Obsidian Integration

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/quickstart.md

Initialize a new vault with specific configuration for Obsidian integration.

```bash
swarmvault init --obsidian
```

--------------------------------

### Dataview Query Example

Source: https://github.com/swarmclawai/swarmvault/blob/main/worked/personal-knowledge-base/README.md

An example of a Dataview query used within dashboard pages to display source information.

```dataview
TABLE source_ids AS "Sources", freshness AS "Last Updated"
FROM "wiki/entities"
SORT freshness DESC
```

--------------------------------

### Ingest Subtitle File

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Ingests a subtitle file (e.g., SRT) into SwarmVault. The --guide flag enables guided ingest for this file.

```bash
swarmvault ingest ./meeting.srt --guide
```

--------------------------------

### Initialize and Manage Vault

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/README.md

Core commands for initializing the vault and adding content.

```bash
swarmvault init
```

```bash
swarmvault source add
```

```bash
swarmvault ingest
```

```bash
swarmvault add
```

```bash
swarmvault inbox import
```

--------------------------------

### swarmvault init

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Initializes a new SwarmVault workspace with the required directory structure and configuration files.

```APIDOC
## swarmvault init

### Description
Creates a workspace with standard directories (inbox, raw, wiki, etc.) and configuration files (swarmvault.config.json, swarmvault.schema.md).

### Parameters
#### Options
- **--obsidian** (flag) - Optional - Includes .obsidian workspace files.
- **--profile** (string) - Optional - Sets the vault profile (e.g., 'default', 'personal-research', 'reader,timeline').
```

--------------------------------

### Vault Initialization and Graph Management

Source: https://github.com/swarmclawai/swarmvault/blob/main/CHANGELOG.md

Commands for initializing research profiles and managing graph visualizations.

```bash
swarmvault init --profile personal-research
```

```bash
swarmvault graph serve
```

```bash
swarmvault graph export --html
```

--------------------------------

### Expose Knowledge Base via MCP

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.zh-CN.md

Directly expose your knowledge base using the MCP command.

```bash
swarmvault mcp
```

--------------------------------

### Uninstall Git Hooks

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Uninstall previously installed git hooks.

```bash
swarmvault hook uninstall
```

--------------------------------

### Check Git Hook Status

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Check the status of installed git hooks.

```bash
swarmvault hook status
```

--------------------------------

### Compile, Query, and Review

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/references/commands.md

Commands for processing data, querying the knowledge base, and managing review workflows.

```bash
swarmvault compile
swarmvault compile --max-tokens 120000
swarmvault compile --approve
swarmvault diff
swarmvault query "<question>"
swarmvault query "<question>" --commit
swarmvault explore "<question>" --steps 3
swarmvault lint
swarmvault lint --conflicts
swarmvault review list
swarmvault review show <approval-id> --diff
swarmvault review accept <approval-id>
swarmvault candidate list
```

--------------------------------

### Compile with Token Budgeting

Source: https://github.com/swarmclawai/swarmvault/blob/main/README.md

Limit generated wiki output by trimming lower-priority pages based on a token budget.

```bash
compile --max-tokens <n>
```

--------------------------------

### Watch Inbox for Changes

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Start the watch mode to monitor the inbox for changes.

```bash
swarmvault watch
```

--------------------------------

### Initialize SwarmVault

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/SKILL.md

Run this command when the vault does not exist yet. Ensure you are in the vault root directory.

```bash
swarmvault init
```

--------------------------------

### Explain a Specific Node

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Get a detailed explanation for a specific node within the knowledge graph.

```bash
swarmvault graph explain "concept:drift"
```

--------------------------------

### Set Up File Watching and Automation with SwarmVault Engine

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Configure and manage file watching for the vault, run watch cycles, and install/uninstall Git hooks for automation.

```typescript
import {
  watchVault,
  runWatchCycle,
  getWatchStatus,
  installGitHooks,
  uninstallGitHooks,
  getGitHookStatus,
  syncTrackedRepos,
} from "@swarmvaultai/engine";

const rootDir = process.cwd();

// Check watch status
const status = await getWatchStatus(rootDir);
console.log("Watched repos:", status.watchedRepoRoots);
console.log("Pending refresh:", status.pendingSemanticRefresh.length);
if (status.lastRun) {
  console.log("Last run:", status.lastRun.startedAt);
  console.log("Success:", status.lastRun.success);
}

// Run one watch cycle
const cycleResult = await runWatchCycle(rootDir, {
  repo: true,
  lint: true,
  codeOnly: false,
});

// Start continuous watcher
const watcher = await watchVault(rootDir, {
  lint: true,
  repo: true,
  debounceMs: 1000,
});

// Later: stop the watcher
await watcher.close();

// Sync tracked repositories
const syncResult = await syncTrackedRepos(rootDir);
console.log("Imported:", syncResult.imported.length);
console.log("Updated:", syncResult.updated.length);
console.log("Removed:", syncResult.removed.length);

// Manage git hooks
const hookStatus = await getGitHookStatus(rootDir);
console.log("Post-commit:", hookStatus.postCommit);
console.log("Post-checkout:", hookStatus.postCheckout);

await installGitHooks(rootDir);
// await uninstallGitHooks(rootDir);
```

--------------------------------

### Configure Web Search Provider

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Sets up an HTTP-based search provider for deep linting web augmentation.

```json
{
  "webSearch": {
    "providers": {
      "evidence": {
        "type": "http-json",
        "endpoint": "https://search.example/api/search",
        "method": "GET",
        "apiKeyEnv": "SEARCH_API_KEY",
        "apiKeyHeader": "Authorization",
        "apiKeyPrefix": "Bearer ",
        "queryParam": "q",
        "limitParam": "limit",
        "resultsPath": "results",
        "titleField": "title",
        "urlField": "url",
        "snippetField": "snippet"
      }
    },
    "tasks": {
      "deepLintProvider": "evidence"
    }
  }
}
```

--------------------------------

### Watch and Lint Repository Automatically

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/repo-workflow.md

Automatically monitor the repository for changes, lint the code, and update the Swarmvault index. Requires Swarmvault hooks to be installed.

```bash
swarmvault watch --lint --repo
```

--------------------------------

### Initialize SwarmVault

Source: https://github.com/swarmclawai/swarmvault/blob/main/worked/personal-knowledge-base/README.md

Initialize the vault with the personal-research profile to enable specific dashboard and Dataview features.

```bash
swarmvault init --obsidian --profile personal-research
```

--------------------------------

### Test Provider Paths

Source: https://github.com/swarmclawai/swarmvault/blob/main/docs/live-testing.md

Commands to verify integration with specific AI providers.

```bash
pnpm live:smoke:ollama
```

```bash
export ANTHROPIC_API_KEY=...
pnpm live:smoke:anthropic
```

```bash
export OPENAI_API_KEY=...
pnpm live:smoke:openai
```

--------------------------------

### Manage SwarmVault Sources

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Manages recurring sources with registry-backed sync. Supports adding, listing, reloading, and deleting managed sources, including guided sessions.

```typescript
import {
  addManagedSource,
  listManagedSourceRecords,
  reloadManagedSources,
  deleteManagedSource,
  guideManagedSource,
  reviewManagedSource,
  resumeSourceSession,
} from "@swarmvaultai/engine";

const rootDir = process.cwd();

// Add a GitHub repository
const result = await addManagedSource(
  rootDir,
  "https://github.com/karpathy/micrograd",
  {
    compile: true,
    brief: true,
    maxPages: 100,
    maxDepth: 3,
  }
);
console.log("Source ID:", result.source.id);
console.log("Brief path:", result.source.briefPath);
console.log("Source IDs:", result.source.sourceIds);

// Add with guided session
const guided = await addManagedSource(rootDir, "./local-docs", {
  guide: true,
  compile: true,
});
if (guided.guide?.awaitingInput) {
  console.log("Questions:", guided.guide.questions);
}

// List all managed sources
const sources = await listManagedSourceRecords(rootDir);
for (const source of sources) {
  console.log(`${source.id}: ${source.title} (${source.status})`);
}

// Reload all sources
const reloaded = await reloadManagedSources(rootDir, {
  all: true,
  compile: true,
  brief: true,
});
console.log("Reloaded:", reloaded.sources.length);

// Resume a guided session with answers
const session = await resumeSourceSession(rootDir, "session-id", {
  guideAnswers: {
    "question-1": "My answer to question 1",
    "question-2": "My answer to question 2",
  },
});
console.log("Session status:", session.status);

// Delete a managed source
const deleted = await deleteManagedSource(rootDir, "source-id");
console.log("Removed:", deleted.removed.title);
```

--------------------------------

### Ingest Research Sources Incrementally

Source: https://github.com/swarmclawai/swarmvault/blob/main/worked/research-deep-dive/README.md

Ingests research source files one by one to observe the wiki's evolution. The --guide flag enables interactive extraction decisions and highlights concept/entity updates.

```sh
swarmvault ingest raw/rag-survey-2024.md --guide
```

```sh
swarmvault ingest raw/compiled-knowledge-karpathy.md --guide
```

```sh
swarmvault ingest raw/hybrid-approaches-2025.md --guide
```

```sh
swarmvault ingest raw/production-rag-lessons.md --guide
```

--------------------------------

### Ingest Local Files or URLs

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Ingest local files, directories, or URLs into immutable source storage. Supports various file types, recursive directory ingestion, and gitignore behavior. Can be used with guided session modes.

```APIDOC
## POST /swarmvault ingest <path-or-url>

### Description
Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.

### Method
POST

### Endpoint
`/swarmvault ingest <path-or-url>`

### Parameters
#### Path Parameters
- **path-or-url** (string) - Required - The local file path, directory path, or URL to ingest.

#### Query Parameters
- **--commit** (boolean) - Optional - Stages `wiki/` and `state/` changes and creates a git commit if the vault root is inside a git worktree.
- **--no-gitignore** (boolean) - Optional - Directory ingest respects `.gitignore` by default; this flag disables that behavior.
- **--guide** (boolean) - Optional - Enables a resumable source session, source brief, source review, source guide, and approval-bundled canonical page edits when `profile.guidedSessionMode` is `canonical_review`.
- **--no-guide** (boolean) - Optional - Forces a plain ingest for one run, overriding `profile.guidedIngestDefault`.
- **--repo-root** (string) - Optional - Specifies the repository root path.
- **--answers-file** (string) - Optional - Path to an answers file.
- **--include** (glob...) - Optional - Glob patterns to include.
- **--exclude** (glob...) - Optional - Glob patterns to exclude.
- **--max-files** (integer) - Optional - Maximum number of files to ingest.
- **--include-third-party** (boolean) - Optional - Include third-party dependencies.
- **--include-resources** (boolean) - Optional - Include resource bundles.
- **--include-generated** (boolean) - Optional - Include generated output.
- **--no-include-assets** (boolean) - Optional - Do not include assets.
- **--max-asset-size** (bytes) - Optional - Maximum size of assets to include.

### Request Example
```json
{
  "path_or_url": "/path/to/local/directory",
  "commit": true
}
```

### Response
#### Success Response (200)
- **manifests** (array) - Paths to the generated manifests.
- **code_index** (string) - Path to the `state/code-index.json` file if repo-aware ingest is used.

#### Response Example
```json
{
  "manifests": [
    "state/manifests/manifest1.json",
    "state/manifests/manifest2.json"
  ],
  "code_index": "state/code-index.json"
}
```
```

--------------------------------

### Multi-Step Exploration

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Run automated research loops that build on previous answers using the 'explore' command with the '--steps' flag.

```bash
# Run a 3-step exploration
swarmvault explore "What should I research next?" --steps 3
```

```bash
# Exploration with report format
swarmvault explore "Analyze the architecture patterns" \
  --steps 5 \
  --format report
```

--------------------------------

### Ingest Local and Remote Files

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/README.md

Ingest various file types into SwarmVault. Supports local files like SRT and MP3, as well as remote content like YouTube videos. Use the --guide flag for specific file types.

```bash
swarmvault ingest ./meeting.srt --guide
```

```bash
swarmvault ingest ./customer-call.mp3
```

```bash
swarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ
```

--------------------------------

### Initialize a Demo Vault

Source: https://github.com/swarmclawai/swarmvault/blob/main/skills/swarmvault/examples/quickstart.md

Initialize a temporary demo vault without serving it. Useful for quickly testing the CLI's functionality.

```bash
swarmvault demo --no-serve
```

--------------------------------

### MCP Server Lifecycle

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/engine/README.md

Endpoints for initializing and running the MCP server instance.

```APIDOC
## POST /mcp/create

### Description
Creates a new MCP server instance for a given root directory.

### Method
POST

### Parameters
#### Request Body
- **rootDir** (string) - Required - The root directory path for the vault.

## POST /mcp/start

### Description
Starts the MCP server over stdio.

### Method
POST

### Parameters
#### Request Body
- **rootDir** (string) - Required - The root directory path for the vault.
```

--------------------------------

### SwarmVault CLI Workflow Commands

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Common commands for initializing, ingesting, querying, and managing a SwarmVault workspace.

```bash
mkdir my-vault
cd my-vault
swarmvault init --obsidian --profile personal-research
swarmvault init --obsidian --profile reader,timeline
swarmvault demo
swarmvault source add https://github.com/karpathy/micrograd
swarmvault source add https://example.com/docs/getting-started
swarmvault source add ./exports/customer-call.srt --guide
swarmvault source session file-customer-call-srt-12345678
swarmvault source list
swarmvault source reload --all
sed -n '1,120p' swarmvault.schema.md
swarmvault ingest ./notes.md
swarmvault ingest ./customer-call.mp3
swarmvault ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ
swarmvault ingest ./repo
swarmvault add https://arxiv.org/abs/2401.12345
swarmvault compile --max-tokens 120000
swarmvault diff
swarmvault benchmark
swarmvault query "What keeps recurring?" --commit
swarmvault query "Turn this into slides" --format slides
swarmvault explore "What should I research next?" --steps 3
swarmvault lint --deep
swarmvault graph blast ./src/index.ts
swarmvault graph query "Which nodes bridge the biggest clusters?"
swarmvault graph explain "concept:drift"
swarmvault watch status
swarmvault watch --repo --once
swarmvault hook install
swarmvault graph serve
swarmvault graph export --report ./exports/report.html
swarmvault graph export --html ./exports/graph.html
swarmvault graph export --cypher ./exports/graph.cypher
swarmvault graph push neo4j --dry-run
```

--------------------------------

### swarmvault scan

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/cli/README.md

Quickly initializes a scratch vault from a local directory, ingests sources, and compiles the vault.

```APIDOC
## swarmvault scan

### Description
Initializes the current directory as a SwarmVault workspace, ingests the directory, compiles the vault, and starts the graph server.

### Parameters
#### Path Parameters
- **directory** (string) - Required - The local directory to scan.

#### Options
- **--port** (number) - Optional - Specifies the viewer port.
- **--no-serve** (flag) - Optional - Prevents starting the graph server.
```

--------------------------------

### Execute Swarmvault CLI Workflow

Source: https://github.com/swarmclawai/swarmvault/blob/main/worked/mixed-corpus/README.md

Run these commands sequentially to ingest, compile, serve, and export a markdown-first corpus.

```bash
swarmvault ingest ./worked/mixed-corpus
```

```bash
swarmvault compile
```

```bash
swarmvault graph serve
```

```bash
swarmvault graph export --svg ./exports/mixed.svg
```

--------------------------------

### Export Knowledge Graph in Multiple Formats

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Export the knowledge graph simultaneously in several different formats.

```bash
swarmvault graph export \
  --html ./exports/graph.html \
  --json ./exports/graph.json \
  --svg ./exports/graph.svg
```

--------------------------------

### Initialize a New Vault

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Create a new workspace with optional Obsidian integration and specific profiles.

```bash
# Basic initialization with Obsidian support
swarmvault init --obsidian --profile personal-research

# Initialize with specific presets
swarmvault init --obsidian --profile reader,timeline

# The vault structure created:
# my-vault/
# ├── swarmvault.schema.md       # User-editable vault instructions
# ├── raw/                       # Immutable source files
# ├── wiki/                      # Compiled wiki pages
# ├── state/                     # Graph, search index, embeddings
# ├── .obsidian/                 # Optional Obsidian workspace
# └── agent/                     # Generated agent helpers
```

--------------------------------

### Show Approval Details with Diff

Source: https://context7.com/swarmclawai/swarmvault/llms.txt

Display the details of a specific approval item along with its diff.

```bash
swarmvault review show approval-12345 --diff
```

--------------------------------

### Initialize Swarmvault Vault

Source: https://github.com/swarmclawai/swarmvault/blob/main/worked/book-reading/README.md

Initializes a new Swarmvault project in the current directory, configured for Obsidian.

```bash
mkdir book-wiki && cd book-wiki
swarmvault init --obsidian
```

--------------------------------

### Execute Vault Operations

Source: https://github.com/swarmclawai/swarmvault/blob/main/packages/engine/README.md

Demonstrates a full workflow including vault initialization, source management, querying, and graph exporting.

```ts
import {
  addInput,
  addManagedSource,
  benchmarkVault,
  compileVault,
  exploreVault,
  exportGraphHtml,
  exportGraphFormat,
  getWatchStatus,
  importInbox,
  initVault,
  installGitHooks,
  listManagedSourceRecords,
  loadVaultSchemas,
  pushGraphNeo4j,
  queryGraphVault,
  queryVault,
  reloadManagedSources,
  runWatchCycle,
  watchVault
} from "@swarmvaultai/engine";

const rootDir = process.cwd();

await initVault(rootDir, { obsidian: true });
const schemas = await loadVaultSchemas(rootDir);
console.log(schemas.root.path);
const managed = await addManagedSource(rootDir, "https://github.com/karpathy/micrograd");
console.log(managed.source.id);
await addInput(rootDir, "https://arxiv.org/abs/2401.12345");
await importInbox(rootDir);
await compileVault(rootDir, {});
const benchmark = await benchmarkVault(rootDir);
console.log(benchmark.avgQueryTokens);

const saved = await queryVault(rootDir, { question: "What changed most recently?" });
console.log(saved.savedPath);

const graphQuery = await queryGraphVault(rootDir, "Which nodes bridge the biggest communities?");
console.log(graphQuery.summary);

const exploration = await exploreVault(rootDir, { question: "What should I investigate next?", steps: 3, format: "report" });
console.log(exploration.hubPath);

await exportGraphHtml(rootDir, "./exports/graph.html");
await exportGraphFormat(rootDir, "graphml", "./exports/graph.graphml");
await pushGraphNeo4j(rootDir, {
  uri: "bolt://127.0.0.1:7687",
  username: "neo4j",
  passwordEnv: "NEO4J_PASSWORD",
  dryRun: true
});

await runWatchCycle(rootDir, { repo: true });
console.log(await getWatchStatus(rootDir));
console.log(await listManagedSourceRecords(rootDir));
await reloadManagedSources(rootDir, { all: true, compile: true });
await installGitHooks(rootDir);

const watcher = await watchVault(rootDir, { lint: true, repo: true });
```