@swarmvaultai/cli 0.1.5 → 0.1.7

package/README.md

@@ -22,29 +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.
 
@@ -56,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:
 
@@ -64,20 +69,47 @@ 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/`.
+
+With `--approve`, compile writes a staged review bundle into `state/approvals/` without applying active wiki changes.
+
+### `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.
 
-With `--save`, the answer is written into `wiki/outputs/` and immediately registered in:
+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 later compiles can link them back into the wiki.
+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>]`
 
@@ -108,7 +140,7 @@ Run anti-drift and vault health checks such as stale pages, missing graph artifa
 
 ### `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`
 
@@ -123,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>`
 

package/dist/index.js

@@ -3,22 +3,33 @@
 // src/index.ts
 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 } from "commander";
+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.5").option("--json", "Emit structured JSON output", false);
+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;
 }
@@ -35,10 +46,10 @@ function log(message) {
 `);
   }
 }
-program.command("init").description("Initialize a SwarmVault workspace in the current directory.").action(async () => {
-  await initVault(process.cwd());
+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() });
+    emitJson({ status: "initialized", rootDir: process.cwd(), obsidian: options.obsidian ?? false });
   } else {
     log("Initialized SwarmVault workspace.");
   }
@@ -62,28 +73,40 @@ inbox.command("import").description("Import supported files from the configured
     );
   }
 });
-program.command("compile").description("Compile manifests into wiki pages, graph JSON, and search index.").action(async () => {
-  const result = await compileVault(process.cwd());
+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 {
-    log(`Compiled ${result.sourceCount} source(s), ${result.pageCount} page(s). Changed: ${result.changedPages.length}.`);
+    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);
+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.savedTo) {
-      log(`Saved to ${result.savedTo}`);
+    if (result.savedPath) {
+      log(`Saved to ${result.savedPath}`);
     }
   }
 });
-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").action(async (question, options) => {
+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, Number.isFinite(stepCount) ? stepCount : 3);
+  const result = await exploreVault(process.cwd(), {
+    question,
+    steps: Number.isFinite(stepCount) ? stepCount : 3,
+    format: options.format
+  });
   if (isJson()) {
     emitJson(result);
   } else {
@@ -122,6 +145,89 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
     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());
@@ -139,6 +245,46 @@ program.command("watch").description("Watch the inbox directory and run import/c
     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" })}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.1.5",
+  "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.5"
+    "@swarmvaultai/engine": "0.1.7"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",