@swarmvaultai/cli 0.1.4 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 `@swarmvaultai/cli` is the global command-line entry point for SwarmVault.
 
-It gives you the `swarmvault` command for building a local-first knowledge vault from files, URLs, browser clips, and saved query outputs.
+It gives you the `swarmvault` command for building a local-first knowledge vault from files, URLs, browser clips, saved query outputs, and guided exploration runs.
 
 ## Install
 
@@ -22,27 +22,34 @@ Installed commands:
 ```bash
 mkdir my-vault
 cd my-vault
-swarmvault init
+swarmvault init --obsidian
 sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault compile
-swarmvault query "What keeps recurring?" --save
+swarmvault query "What keeps recurring?"
+swarmvault query "Turn this into slides" --format slides
+swarmvault explore "What should I research next?" --steps 3
+swarmvault lint --deep
 swarmvault graph serve
+swarmvault graph export --html ./exports/graph.html
 ```
 
 ## Commands
 
-### `swarmvault init`
+### `swarmvault init [--obsidian]`
 
 Create a workspace with:
 
 - `inbox/`
 - `raw/`
 - `wiki/`
+- `wiki/insights/`
 - `state/`
+- `state/sessions/`
 - `agent/`
 - `swarmvault.config.json`
 - `swarmvault.schema.md`
+- optional `.obsidian/` workspace files when `--obsidian` is passed
 
 The schema file is the vault-specific instruction layer. Edit it to define naming rules, categories, grounding expectations, and exclusions before a serious compile.
 
@@ -54,7 +61,7 @@ Ingest a local file path or URL into immutable source storage and write a manife
 
 Import supported files from the configured inbox directory. This is meant for browser-clipper style markdown bundles and other capture workflows. Local image and asset references are preserved and copied into canonical storage under `raw/assets/`.
 
-### `swarmvault compile`
+### `swarmvault compile [--approve]`
 
 Compile the current manifests into:
 
@@ -62,19 +69,78 @@ Compile the current manifests into:
 - structured graph data in `state/graph.json`
 - local search data in `state/search.sqlite`
 
-The compiler also reads `swarmvault.schema.md` and records a `schema_hash` in generated pages so schema edits can mark pages stale.
+The compiler also reads `swarmvault.schema.md` and records a `schema_hash` plus lifecycle metadata such as `status`, `created_at`, `updated_at`, `compiled_from`, and `managed_by` in generated pages so schema edits can mark pages stale without losing lifecycle state.
 
-### `swarmvault query "<question>" [--save]`
+New concept and entity pages are staged into `wiki/candidates/` first. A later matching compile promotes them into `wiki/concepts/` or `wiki/entities/`.
 
-Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules. With `--save`, the answer is written into `wiki/outputs/` so the result becomes part of the vault.
+With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.
 
-### `swarmvault lint`
+### `swarmvault review list|show|accept|reject`
+
+Inspect and resolve staged approval bundles created by `swarmvault compile --approve`.
+
+- `review list` shows pending, accepted, and rejected entry counts per bundle
+- `review show <approvalId>` shows each staged entry plus its current and staged content
+- `review accept <approvalId> [targets...]` applies pending entries to the live wiki
+- `review reject <approvalId> [targets...]` marks pending entries as rejected without mutating active wiki paths
+
+Targets can be page ids such as `concept:approval-concept` or relative wiki paths such as `concepts/approval-concept.md`.
+
+### `swarmvault candidate list|promote|archive`
+
+Inspect and resolve staged concept and entity candidates.
+
+- `candidate list` shows every current candidate plus its active destination path
+- `candidate promote <target>` promotes a candidate immediately into `wiki/concepts/` or `wiki/entities/`
+- `candidate archive <target>` removes a candidate from the staged set
+
+Targets can be page ids or relative paths under `wiki/candidates/`.
+
+### `swarmvault query "<question>" [--no-save] [--format markdown|report|slides]`
+
+Query the compiled vault. The query layer also reads `swarmvault.schema.md`, so answers follow the vault’s own structure and grounding rules.
+
+By default, the answer is written into `wiki/outputs/` and immediately registered in:
+
+- `wiki/index.md`
+- `wiki/outputs/index.md`
+- `state/graph.json`
+- `state/search.sqlite`
+
+Saved outputs also carry related page, node, and source metadata so SwarmVault can refresh related source, concept, and entity pages immediately.
+
+Human-authored pages in `wiki/insights/` are also indexed into search and query context, but SwarmVault does not rewrite them after initialization.
+
+### `swarmvault explore "<question>" [--steps <n>]`
+
+Run a save-first multi-step research loop.
+
+Each step:
+
+- queries the vault
+- saves the answer into `wiki/outputs/`
+- generates follow-up questions
+- chooses the next follow-up deterministically
+
+The command also writes a hub page linking the root question, saved step pages, and generated follow-up questions.
+
+### `swarmvault lint [--deep] [--web]`
 
 Run anti-drift and vault health checks such as stale pages, missing graph artifacts, and other structural issues.
 
+`--deep` adds an LLM-powered advisory pass that can report:
+
+- `coverage_gap`
+- `contradiction_candidate`
+- `missing_citation`
+- `candidate_page`
+- `follow_up_question`
+
+`--web` can only be used with `--deep`. It enriches deep-lint findings with external evidence snippets and URLs from a configured web-search provider.
+
 ### `swarmvault watch [--lint] [--debounce <ms>]`
 
-Watch the inbox directory and trigger import and compile cycles when files change. With `--lint`, each cycle also runs linting. Run metadata is appended to `state/jobs.ndjson`.
+Watch the inbox directory and trigger import and compile cycles when files change. With `--lint`, each cycle also runs linting. Each cycle writes a canonical session artifact to `state/sessions/`, and compatibility run metadata is still appended to `state/jobs.ndjson`.
 
 ### `swarmvault mcp`
 
@@ -89,11 +155,15 @@ Run SwarmVault as a local MCP server over stdio. This exposes the vault to compa
 - `compile_vault`
 - `lint_vault`
 
-The MCP surface also exposes `swarmvault://schema` and includes `schemaPath` in `workspace_info`.
+The MCP surface also exposes `swarmvault://schema`, `swarmvault://sessions`, `swarmvault://sessions/{path}`, and includes `schemaPath` in `workspace_info`.
 
 ### `swarmvault graph serve`
 
-Start the local graph UI backed by `state/graph.json`.
+Start the local graph workspace backed by `state/graph.json`, `/api/search`, and `/api/page`.
+
+### `swarmvault graph export --html <output>`
+
+Export the graph workspace as a standalone HTML file with embedded graph and page data for offline sharing.
 
 ### `swarmvault install --agent <codex|claude|cursor>`
 
@@ -126,10 +196,39 @@ Example:
 
 Generic OpenAI-compatible APIs are supported through config when the provider follows the OpenAI request shape closely enough.
 
+Deep lint web augmentation uses a separate `webSearch` config block. Example:
+
+```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"
+    }
+  }
+}
+```
+
 ## Troubleshooting
 
 - If you are running from a source checkout and `graph serve` says the viewer build is missing, run `pnpm build` in the repository first
 - If a provider claims OpenAI compatibility but fails structured generation, declare only the capabilities it actually supports
+- If `lint --deep --web` fails immediately, make sure a `webSearch` provider is configured and mapped to `tasks.deepLintProvider`
 - Node 24 may emit an experimental warning for `node:sqlite`; that is expected in the current release
 
 ## Links

package/dist/index.js

@@ -1,92 +1,295 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
 import process from "process";
 import {
+  acceptApproval,
+  archiveCandidate,
   compileVault,
+  exploreVault,
+  exportGraphHtml,
   importInbox,
   ingestInput,
   initVault,
   installAgent,
   lintVault,
+  listApprovals,
+  listCandidates,
+  loadVaultConfig,
+  promoteCandidate,
   queryVault,
+  readApproval,
+  rejectApproval,
+  listSchedules,
+  runSchedule,
+  serveSchedules,
   startGraphServer,
   startMcpServer,
   watchVault
 } from "@swarmvaultai/engine";
+import { Command, Option } from "commander";
 var program = new Command();
-program.name("swarmvault").description("SwarmVault is a local-first LLM wiki compiler with graph outputs and pluggable providers.").version("0.1.4");
-program.command("init").description("Initialize a SwarmVault workspace in the current directory.").action(async () => {
-  await initVault(process.cwd());
-  process.stdout.write("Initialized SwarmVault workspace.\n");
+program.name("swarmvault").description("SwarmVault is a local-first LLM wiki compiler with graph outputs and pluggable providers.").version("0.1.7").option("--json", "Emit structured JSON output", false);
+function isJson() {
+  return program.opts().json === true;
+}
+function emitJson(data) {
+  process.stdout.write(`${JSON.stringify(data)}
+`);
+}
+function log(message) {
+  if (isJson()) {
+    process.stderr.write(`${message}
+`);
+  } else {
+    process.stdout.write(`${message}
+`);
+  }
+}
+program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).action(async (options) => {
+  await initVault(process.cwd(), { obsidian: options.obsidian ?? false });
+  if (isJson()) {
+    emitJson({ status: "initialized", rootDir: process.cwd(), obsidian: options.obsidian ?? false });
+  } else {
+    log("Initialized SwarmVault workspace.");
+  }
 });
 program.command("ingest").description("Ingest a local file path or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path or URL").action(async (input) => {
   const manifest = await ingestInput(process.cwd(), input);
-  process.stdout.write(`${manifest.sourceId}
-`);
+  if (isJson()) {
+    emitJson(manifest);
+  } else {
+    log(manifest.sourceId);
+  }
 });
 var inbox = program.command("inbox").description("Inbox and capture workflows.");
 inbox.command("import").description("Import supported files from the configured inbox directory.").argument("[dir]", "Optional inbox directory override").action(async (dir) => {
   const result = await importInbox(process.cwd(), dir);
-  process.stdout.write(
-    `Imported ${result.imported.length} source(s) from ${result.inputDir}. Scanned: ${result.scannedCount}. Attachments: ${result.attachmentCount}. Skipped: ${result.skipped.length}.
-`
-  );
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(
+      `Imported ${result.imported.length} source(s) from ${result.inputDir}. Scanned: ${result.scannedCount}. Attachments: ${result.attachmentCount}. Skipped: ${result.skipped.length}.`
+    );
+  }
 });
-program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").action(async () => {
-  const result = await compileVault(process.cwd());
-  process.stdout.write(
-    `Compiled ${result.sourceCount} source(s), ${result.pageCount} page(s). Changed: ${result.changedPages.length}.
-`
-  );
+program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").option("--approve", "Stage a review bundle without applying active page changes", false).action(async (options) => {
+  const result = await compileVault(process.cwd(), { approve: options.approve ?? false });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    if (result.staged) {
+      log(`Staged ${result.changedPages.length} change(s) for review at ${result.approvalDir}.`);
+    } else {
+      log(`Compiled ${result.sourceCount} source(s), ${result.pageCount} page(s). Changed: ${result.changedPages.length}.`);
+    }
+  }
 });
-program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--save", "Persist the answer to wiki/outputs", false).action(async (question, options) => {
-  const result = await queryVault(process.cwd(), question, options.save ?? false);
-  process.stdout.write(`${result.answer}
-`);
-  if (result.savedTo) {
-    process.stdout.write(`Saved to ${result.savedTo}
-`);
+program.command("query").description("Query the compiled SwarmVault wiki.").argument("<question>", "Question to ask SwarmVault").option("--no-save", "Do not persist the answer to wiki/outputs").addOption(new Option("--format <format>", "Output format").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")).action(async (question, options) => {
+  const result = await queryVault(process.cwd(), {
+    question,
+    save: options.save ?? true,
+    format: options.format
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(result.answer);
+    if (result.savedPath) {
+      log(`Saved to ${result.savedPath}`);
+    }
   }
 });
-program.command("lint").description("Run anti-drift and wiki-health checks.").action(async () => {
-  const findings = await lintVault(process.cwd());
+program.command("explore").description("Run a save-first multi-step exploration loop against the vault.").argument("<question>", "Root question to explore").option("--steps <n>", "Maximum number of exploration steps", "3").addOption(new Option("--format <format>", "Output format for step pages").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")).action(async (question, options) => {
+  const stepCount = Number.parseInt(options.steps ?? "3", 10);
+  const result = await exploreVault(process.cwd(), {
+    question,
+    steps: Number.isFinite(stepCount) ? stepCount : 3,
+    format: options.format
+  });
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Exploration hub saved to ${result.hubPath}`);
+    log(`Completed ${result.stepCount} step(s).`);
+  }
+});
+program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint", false).option("--web", "Augment deep lint with configured web search", false).action(async (options) => {
+  const findings = await lintVault(process.cwd(), {
+    deep: options.deep ?? false,
+    web: options.web ?? false
+  });
+  if (isJson()) {
+    emitJson(findings);
+    return;
+  }
   if (!findings.length) {
-    process.stdout.write("No findings.\n");
+    log("No findings.");
     return;
   }
   for (const finding of findings) {
-    process.stdout.write(
-      `[${finding.severity}] ${finding.code}: ${finding.message}${finding.pagePath ? ` (${finding.pagePath})` : ""}
-`
-    );
+    log(`[${finding.severity}] ${finding.code}: ${finding.message}${finding.pagePath ? ` (${finding.pagePath})` : ""}`);
   }
 });
 var graph = program.command("graph").description("Graph-related commands.");
 graph.command("serve").description("Serve the local graph viewer.").option("--port <port>", "Port override").action(async (options) => {
   const port = options.port ? Number.parseInt(options.port, 10) : void 0;
   const server = await startGraphServer(process.cwd(), port);
-  process.stdout.write(`Graph viewer running at http://localhost:${server.port}
-`);
+  if (isJson()) {
+    emitJson({ port: server.port, url: `http://localhost:${server.port}` });
+  } else {
+    log(`Graph viewer running at http://localhost:${server.port}`);
+  }
   process.on("SIGINT", async () => {
     await server.close();
     process.exit(0);
   });
 });
+graph.command("export").description("Export the graph viewer as a single self-contained HTML file.").requiredOption("--html <output>", "Output HTML file path").action(async (options) => {
+  const outputPath = await exportGraphHtml(process.cwd(), options.html);
+  if (isJson()) {
+    emitJson({ outputPath });
+  } else {
+    log(`Exported graph HTML to ${outputPath}`);
+  }
+});
+var review = program.command("review").description("Review staged compile approval bundles.");
+review.command("list").description("List staged approval bundles and their resolution status.").action(async () => {
+  const approvals = await listApprovals(process.cwd());
+  if (isJson()) {
+    emitJson(approvals);
+    return;
+  }
+  if (!approvals.length) {
+    log("No approval bundles.");
+    return;
+  }
+  for (const approval of approvals) {
+    log(
+      `${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount} created=${approval.createdAt}`
+    );
+  }
+});
+review.command("show").description("Show the entries inside a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").action(async (approvalId) => {
+  const approval = await readApproval(process.cwd(), approvalId);
+  if (isJson()) {
+    emitJson(approval);
+    return;
+  }
+  log(`${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount}`);
+  for (const entry of approval.entries) {
+    log(`- ${entry.status} ${entry.changeType} ${entry.pageId} ${entry.nextPath ?? entry.previousPath ?? ""}`.trim());
+  }
+});
+review.command("accept").description("Accept all pending entries, or selected entries, from a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").argument("[targets...]", "Optional page ids or paths to accept").action(async (approvalId, targets) => {
+  const result = await acceptApproval(process.cwd(), approvalId, targets);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Accepted ${result.updatedEntries.length} entr${result.updatedEntries.length === 1 ? "y" : "ies"} from ${approvalId}.`);
+  }
+});
+review.command("reject").description("Reject all pending entries, or selected entries, from a staged approval bundle.").argument("<approvalId>", "Approval bundle identifier").argument("[targets...]", "Optional page ids or paths to reject").action(async (approvalId, targets) => {
+  const result = await rejectApproval(process.cwd(), approvalId, targets);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Rejected ${result.updatedEntries.length} entr${result.updatedEntries.length === 1 ? "y" : "ies"} from ${approvalId}.`);
+  }
+});
+var candidate = program.command("candidate").description("Candidate page workflows.");
+candidate.command("list").description("List staged concept and entity candidates.").action(async () => {
+  const candidates = await listCandidates(process.cwd());
+  if (isJson()) {
+    emitJson(candidates);
+    return;
+  }
+  if (!candidates.length) {
+    log("No candidates.");
+    return;
+  }
+  for (const entry of candidates) {
+    log(`${entry.pageId} ${entry.path} -> ${entry.activePath}`);
+  }
+});
+candidate.command("promote").description("Promote a candidate into its active concept or entity path.").argument("<target>", "Candidate page id or path").action(async (target) => {
+  const result = await promoteCandidate(process.cwd(), target);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Promoted ${result.pageId} to ${result.path}`);
+  }
+});
+candidate.command("archive").description("Archive a candidate by removing it from the active candidate set.").argument("<target>", "Candidate page id or path").action(async (target) => {
+  const result = await archiveCandidate(process.cwd(), target);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Archived ${result.pageId}`);
+  }
+});
 program.command("watch").description("Watch the inbox directory and run import/compile cycles on changes.").option("--lint", "Run lint after each compile cycle", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
   const debounceMs = Number.parseInt(options.debounce ?? "900", 10);
+  const { paths } = await loadVaultConfig(process.cwd());
   const controller = await watchVault(process.cwd(), {
     lint: options.lint ?? false,
     debounceMs: Number.isFinite(debounceMs) ? debounceMs : 900
   });
-  process.stdout.write("Watching inbox for changes. Press Ctrl+C to stop.\n");
+  if (isJson()) {
+    emitJson({ status: "watching", inboxDir: paths.inboxDir });
+  } else {
+    log("Watching inbox for changes. Press Ctrl+C to stop.");
+  }
+  process.on("SIGINT", async () => {
+    await controller.close();
+    process.exit(0);
+  });
+});
+var schedule = program.command("schedule").description("Run scheduled vault maintenance jobs.");
+schedule.command("list").description("List configured schedule jobs and their next run state.").action(async () => {
+  const schedules = await listSchedules(process.cwd());
+  if (isJson()) {
+    emitJson(schedules);
+    return;
+  }
+  if (!schedules.length) {
+    log("No schedules configured.");
+    return;
+  }
+  for (const entry of schedules) {
+    log(
+      `${entry.jobId} enabled=${entry.enabled} task=${entry.taskType} next=${entry.nextRunAt ?? "n/a"} last=${entry.lastRunAt ?? "never"} status=${entry.lastStatus ?? "n/a"} approval=${entry.lastApprovalId ?? "none"}`
+    );
+  }
+});
+schedule.command("run").description("Run one configured schedule job immediately.").argument("<jobId>", "Schedule identifier").action(async (jobId) => {
+  const result = await runSchedule(process.cwd(), jobId);
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(
+    `${jobId} ${result.success ? "completed" : "failed"} (${result.taskType})${result.approvalId ? ` approval=${result.approvalId}` : ""}${result.error ? ` error=${result.error}` : ""}`
+  );
+});
+schedule.command("serve").description("Run the local schedule loop.").option("--poll <ms>", "Polling interval in milliseconds", "30000").action(async (options) => {
+  const pollMs = Number.parseInt(options.poll ?? "30000", 10);
+  const controller = await serveSchedules(process.cwd(), Number.isFinite(pollMs) ? pollMs : 3e4);
+  if (isJson()) {
+    emitJson({ status: "serving", pollMs: Number.isFinite(pollMs) ? pollMs : 3e4 });
+  } else {
+    log("Serving schedules. Press Ctrl+C to stop.");
+  }
   process.on("SIGINT", async () => {
     await controller.close();
     process.exit(0);
   });
 });
 program.command("mcp").description("Run SwarmVault as a local MCP server over stdio.").action(async () => {
+  if (isJson()) {
+    process.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio" })}
+`);
+  }
   const controller = await startMcpServer(process.cwd());
   process.on("SIGINT", async () => {
     await controller.close();
@@ -95,12 +298,19 @@ program.command("mcp").description("Run SwarmVault as a local MCP server over st
 });
 program.command("install").description("Install SwarmVault instructions for an agent in the current project.").requiredOption("--agent <agent>", "codex, claude, or cursor").action(async (options) => {
   const target = await installAgent(process.cwd(), options.agent);
-  process.stdout.write(`Installed rules into ${target}
-`);
+  if (isJson()) {
+    emitJson({ agent: options.agent, target });
+  } else {
+    log(`Installed rules into ${target}`);
+  }
 });
 program.parseAsync(process.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
-  process.stderr.write(`${message}
+  if (isJson()) {
+    emitJson({ error: message });
+  } else {
+    process.stderr.write(`${message}
 `);
+  }
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "@swarmvaultai/engine": "0.1.4"
+    "@swarmvaultai/engine": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",
@@ -48,6 +48,6 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
     "test": "node -e \"process.exit(0)\"",
-    "lint": "tsc --noEmit"
+    "typecheck": "tsc --noEmit"
   }
 }