@swarmvaultai/cli 0.1.3 → 0.1.5

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
 
@@ -23,9 +23,12 @@ Installed commands:
 mkdir my-vault
 cd my-vault
 swarmvault init
+sed -n '1,120p' swarmvault.schema.md
 swarmvault ingest ./notes.md
 swarmvault compile
 swarmvault query "What keeps recurring?" --save
+swarmvault explore "What should I research next?" --steps 3
+swarmvault lint --deep
 swarmvault graph serve
 ```
 
@@ -41,6 +44,9 @@ Create a workspace with:
 - `state/`
 - `agent/`
 - `swarmvault.config.json`
+- `swarmvault.schema.md`
+
+The schema file is the vault-specific instruction layer. Edit it to define naming rules, categories, grounding expectations, and exclusions before a serious compile.
 
 ### `swarmvault ingest <path-or-url>`
 
@@ -58,14 +64,48 @@ 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.
+
 ### `swarmvault query "<question>" [--save]`
 
-Query the compiled vault. With `--save`, the answer is written into `wiki/outputs/` so the result becomes part of the vault.
+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:
+
+- `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.
+
+### `swarmvault explore "<question>" [--steps <n>]`
 
-### `swarmvault lint`
+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`.
@@ -83,6 +123,8 @@ 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`.
+
 ### `swarmvault graph serve`
 
 Start the local graph UI backed by `state/graph.json`.
@@ -118,10 +160,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,74 +1,122 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { Command } from "commander";
 import process from "process";
 import {
   compileVault,
+  exploreVault,
   importInbox,
   ingestInput,
   initVault,
   installAgent,
   lintVault,
+  loadVaultConfig,
   queryVault,
   startGraphServer,
   startMcpServer,
   watchVault
 } from "@swarmvaultai/engine";
+import { Command } 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.3");
+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);
+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.").action(async () => {
   await initVault(process.cwd());
-  process.stdout.write("Initialized SwarmVault workspace.\n");
+  if (isJson()) {
+    emitJson({ status: "initialized", rootDir: process.cwd() });
+  } 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}.
-`
-  );
+  if (isJson()) {
+    emitJson(result);
+  } 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}
-`);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(result.answer);
+    if (result.savedTo) {
+      log(`Saved to ${result.savedTo}`);
+    }
   }
 });
-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").action(async (question, options) => {
+  const stepCount = Number.parseInt(options.steps ?? "3", 10);
+  const result = await exploreVault(process.cwd(), question, Number.isFinite(stepCount) ? stepCount : 3);
+  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);
@@ -76,17 +124,26 @@ graph.command("serve").description("Serve the local graph viewer.").option("--po
 });
 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);
   });
 });
 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 +152,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.3",
+  "version": "0.1.5",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "commander": "^14.0.1",
-    "@swarmvaultai/engine": "0.1.3"
+    "@swarmvaultai/engine": "0.1.5"
   },
   "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"
   }
 }