@swarmvaultai/cli 3.11.0 → 3.13.0

package/README.md

@@ -29,67 +29,45 @@ The smoke parses `packages/cli/src/index.ts` with the TypeScript compiler API, c
 
 ## First Run
 
+Start in an empty folder or scratch folder:
+
 ```bash
 mkdir my-vault
 cd my-vault
-swarmvault init --obsidian --profile personal-research
-swarmvault init --obsidian --profile reader,timeline
+swarmvault quickstart ../your-repo
+```
+
+That single command initializes a vault, ingests the input, compiles the wiki and graph, writes share artifacts, and opens the local graph viewer. It is the beginner-friendly alias for `swarmvault scan`.
+
+No input ready yet?
+
+```bash
 swarmvault demo
-swarmvault source add https://github.com/karpathy/micrograd
-swarmvault source add https://github.com/owner/repo --branch main --checkout-dir .swarmvault-checkouts/repo
-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 --video https://example.com/product-demo.mp4
-swarmvault ingest ./repo
+```
+
+After the first compile, use:
+
+```bash
+swarmvault query "What are the key concepts?"
+swarmvault graph serve
+swarmvault doctor
+swarmvault candidate list
+```
+
+Use the step-by-step flow when you want more control:
+
+```bash
+swarmvault init --obsidian --profile personal-research
+swarmvault ingest ./src --repo-root .
+swarmvault ingest ./meeting.srt --guide
 swarmvault add https://arxiv.org/abs/2401.12345
-swarmvault compile --max-tokens 120000
-swarmvault diff
-swarmvault graph share --post
-swarmvault graph share --svg ./share-card.svg
-swarmvault graph share --bundle ./share-kit
-swarmvault benchmark
-swarmvault query "What keeps recurring?" --commit
-swarmvault context build "Ship this feature safely" --target ./src --budget 8000
-swarmvault task start "Ship this feature safely" --target ./src --agent codex
-swarmvault retrieval status
-swarmvault doctor --repair
-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 status ./src
-swarmvault check-update ./src
-swarmvault graph stats
-swarmvault graph validate --strict
-swarmvault graph update .
-swarmvault update .
-swarmvault graph cluster
-swarmvault cluster-only
-swarmvault graph tree --output ./exports/tree.html
-swarmvault tree --output ./exports/tree.html
-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 compile
+swarmvault query "What is the auth flow?"
 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 export --neo4j ./exports/graph.cypher
-swarmvault graph merge ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
-swarmvault merge-graphs ./exports/graph.json ./other-graph.json --out ./exports/merged-graph.json
-swarmvault graph push neo4j --dry-run
-swarmvault clone https://github.com/owner/repo --no-viz
 ```
 
+Use `source add` for recurring inputs (`swarmvault source add https://github.com/karpathy/micrograd`, `swarmvault source add https://example.com/docs/getting-started`, `swarmvault source list`, `swarmvault source reload --all`, and `swarmvault source session file-customer-call-srt-12345678`). Use advanced graph/context surfaces when needed: `swarmvault graph status ./src`, `swarmvault check-update ./src`, `swarmvault update ./src`, `swarmvault graph stats`, `swarmvault graph validate --strict`, `swarmvault graph cluster`, `swarmvault cluster-only`, `swarmvault tree --output ./exports/tree.html`, `swarmvault export ai --out ./exports/ai`, `swarmvault context build "Ship this feature safely" --target ./src --budget 8000`, and `swarmvault task start "Ship this feature safely" --target ./src --agent codex`.
+
 ## Commands
 
 ### `swarmvault init [--obsidian] [--profile <alias-or-presets>]`
@@ -113,6 +91,19 @@ Set `SWARMVAULT_OUT=<dir>` when generated artifacts should be isolated from the
 
 `--profile` accepts `default`, `personal-research`, or a comma-separated preset list such as `reader,timeline`. For fully custom vault behavior, edit the `profile` block in `swarmvault.config.json`; that deterministic profile layer works alongside the human-written `swarmvault.schema.md`. The `personal-research` preset also sets `profile.guidedIngestDefault: true` and `profile.deepLintDefault: true`, so guided ingest/source and lint flows are on by default until you override them with `--no-guide` or `--no-deep`.
 
+### `swarmvault quickstart <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
+
+Beginner-friendly alias for `swarmvault scan`.
+
+- initializes the current directory as a SwarmVault workspace
+- ingests the supplied local directory, or registers/syncs the supplied public GitHub repo root URL
+- compiles wiki, graph, search, and share artifacts immediately
+- prints the generated `raw/`, `wiki/`, `state/graph.json`, and `wiki/graph/` paths in human output
+- starts `graph serve` unless you pass `--no-serve` or `--no-viz`
+- keeps the same JSON output contract as `scan`
+
+Use this as the default first-run command in docs and onboarding.
+
 ### `swarmvault scan <directory|github-url> [--port <port>] [--no-serve] [--no-viz] [--mcp] [--branch <name>] [--ref <ref>] [--checkout-dir <path>]`
 
 Quick-start a scratch vault from a local directory or public GitHub repo root URL in one command.
@@ -155,6 +146,28 @@ Compare the current `state/graph.json` against the last committed graph in git.
 - when no git baseline exists, falls back to a summary of the current graph state
 - supports `--json` for structured automation output
 
+### `swarmvault chat [question...] [--resume [id]] [--list] [--delete <id>]`
+
+Ask the compiled wiki in a persisted multi-turn session.
+
+- without a question, opens an interactive TTY chat loop with `/help`, `/sessions`, `/status`, `/clear`, and `/exit`
+- with a question, runs one turn and persists the transcript under `wiki/outputs/chat-sessions/`
+- stores structured session state under `state/chat-sessions/`
+- `--resume <id>` resumes by id or unique prefix; `--resume` alone resumes the most recent session
+- `--list` prints saved sessions and `--delete <id>` removes one
+- `--save-output` also writes each turn as a regular `wiki/outputs/` query page
+- supports `--format markdown|report|slides|chart|image`, `--gap-fill`, and global `--json`
+
+### `swarmvault export ai [--out <dir>] [--max-full-chars <n>] [--no-page-siblings]`
+
+Write a static AI handoff pack for agents, crawlers, and documentation systems.
+
+- defaults to `wiki/exports/ai/`
+- writes `llms.txt`, `llms-full.txt`, `graph.jsonld`, `manifest.json`, and `ai-readme.md`
+- writes per-page `.txt` and `.json` siblings under `pages/` unless `--no-page-siblings` is passed
+- caps `llms-full.txt` with `--max-full-chars` so huge vaults stay bounded
+- includes SHA-256 hashes and file metadata in `manifest.json`
+
 ### `swarmvault doctor [--repair]`
 
 Run a whole-vault health check before handing the workspace to an agent or opening the live viewer.

package/dist/index.js

@@ -12,6 +12,7 @@ import {
   addManagedSource,
   addWatchedRoot,
   archiveCandidate,
+  askChatSession,
   autoCommitWikiChanges,
   benchmarkVault,
   blastRadiusVault,
@@ -20,6 +21,7 @@ import {
   compileVault,
   consolidateVault,
   createSupersessionEdge,
+  deleteChatSession,
   deleteContextPack,
   deleteManagedSource,
   doctorRetrieval,
@@ -27,6 +29,7 @@ import {
   downloadWhisperModel,
   explainGraphVault,
   exploreVault,
+  exportAiPack,
   exportGraphFormat,
   exportGraphHtml,
   exportGraphReportHtml,
@@ -51,6 +54,7 @@ import {
   lintVault,
   listApprovals,
   listCandidates,
+  listChatSessions,
   listContextPacks,
   listGodNodes,
   listManagedSourceRecords,
@@ -315,9 +319,9 @@ program.name("swarmvault").description("SwarmVault is a local-first knowledge co
 function readCliVersion() {
   try {
     const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.11.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "3.13.0";
   } catch {
-    return "3.11.0";
+    return "3.13.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -604,10 +608,19 @@ async function runScanCommand(input, options) {
   const shareKitPath = path2.join(paths.wikiDir, "graph", "share-kit");
   if (!isJson()) {
     log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+    log(`Vault workspace: ${rootDir}`);
+    log(`Raw sources: ${paths.rawDir}`);
+    log(`Wiki output: ${paths.wikiDir}`);
+    log(`Graph JSON: ${paths.graphPath}`);
     log(`Share card: ${shareCardPath}`);
     log(`Visual card: ${shareCardSvgPath}`);
     log(`Share kit: ${shareKitPath}`);
-    log("Post text: swarmvault graph share --post");
+    log("");
+    log("Next steps:");
+    log('  swarmvault query "What are the key concepts?"');
+    log("  swarmvault graph serve");
+    log("  swarmvault doctor");
+    log("  swarmvault candidate list");
   }
   if (options.mcp) {
     process2.stderr.write(`${JSON.stringify({ status: "running", transport: "stdio", compiled: compiled.sourceCount })}
@@ -649,6 +662,105 @@ async function runScanCommand(input, options) {
     emitJson({ ...result, compiled, shareCardPath, shareCardSvgPath, shareKitPath });
   }
 }
+async function resolveChatResumeId(resume) {
+  if (!resume) {
+    return void 0;
+  }
+  if (typeof resume === "string") {
+    return resume;
+  }
+  const sessions = await listChatSessions(process2.cwd());
+  return sessions[0]?.id;
+}
+function logChatSessions(sessions) {
+  if (!sessions.length) {
+    log("No chat sessions yet.");
+    return;
+  }
+  for (const session of sessions) {
+    log(`${session.id}  ${session.turnCount} turn${session.turnCount === 1 ? "" : "s"}  ${session.title}`);
+    log(`  updated: ${session.updatedAt}`);
+    log(`  markdown: ${session.markdownPath}`);
+  }
+}
+async function runChatQuestion(question, options) {
+  const sessionId = await resolveChatResumeId(options.resume);
+  return askChatSession(process2.cwd(), {
+    question,
+    sessionId,
+    saveOutput: options.saveOutput ?? false,
+    gapFill: options.gapFill ?? false,
+    format: options.format,
+    maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+  });
+}
+async function runInteractiveChat(options) {
+  if (isJson()) {
+    throw new Error("Interactive chat is not available with --json. Pass a question for one-shot JSON output.");
+  }
+  if (!process2.stdin.isTTY) {
+    throw new Error("Pass a chat question, or run `swarmvault chat` in an interactive terminal.");
+  }
+  let sessionId = await resolveChatResumeId(options.resume);
+  log(sessionId ? `Resuming chat session ${sessionId}.` : "Starting a new chat session.");
+  log("Type /help for commands or /exit to quit.");
+  const reader = createInterface({ input: process2.stdin, output: process2.stdout });
+  try {
+    while (true) {
+      const input = (await reader.question("swarmvault> ")).trim();
+      if (!input) {
+        continue;
+      }
+      if (input === "/exit" || input === "/quit") {
+        break;
+      }
+      if (input === "/help") {
+        log(
+          [
+            "/help              Show commands",
+            "/sessions          List chat sessions",
+            "/status            Show vault health summary",
+            "/clear             Start a fresh session",
+            "/exit              Quit"
+          ].join("\n")
+        );
+        continue;
+      }
+      if (input === "/sessions") {
+        logChatSessions(await listChatSessions(process2.cwd()));
+        continue;
+      }
+      if (input === "/status") {
+        const report = await doctorVault(process2.cwd(), {});
+        log(`Vault health: ${report.ok ? "ok" : "needs attention"} (${report.recommendations.length} recommendation(s))`);
+        for (const recommendation of report.recommendations.slice(0, 5)) {
+          log(`- ${recommendation.label}: ${recommendation.command ?? recommendation.summary}`);
+        }
+        continue;
+      }
+      if (input === "/clear") {
+        sessionId = void 0;
+        log("Started a fresh chat session.");
+        continue;
+      }
+      const result = await askChatSession(process2.cwd(), {
+        question: input,
+        sessionId,
+        saveOutput: options.saveOutput ?? false,
+        gapFill: options.gapFill ?? false,
+        format: options.format,
+        maxHistoryTurns: parsePositiveInt(options.maxHistoryTurns, 6)
+      });
+      sessionId = result.session.id;
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+      await maybeEmitHeuristicNotice(["chat"]);
+    }
+  } finally {
+    reader.close();
+  }
+}
 program.hook("postAction", async (_thisCommand, actionCommand) => {
   const notices = await collectCliNotices({
     commandPath: getCommandPath(actionCommand),
@@ -659,6 +771,7 @@ program.hook("postAction", async (_thisCommand, actionCommand) => {
     emitNotice(notice);
   }
 });
+program.command("quickstart").description("Beginner path: initialize, ingest, compile, and optionally open the graph viewer in one command.").argument("<input>", "Directory or public GitHub repo root URL to turn into a vault").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").option("--no-viz", "Compatibility alias for --no-serve; skip launching the graph viewer after compile").option("--mcp", "Start the MCP stdio server after compile instead of launching the graph viewer", false).option("--branch <name>", "GitHub branch to clone when the input is a public repo URL").option("--ref <ref>", "Git ref, tag, or commit to check out when the input is a public repo URL").option("--checkout-dir <path>", "Persistent checkout directory for a public GitHub repo input").action(runScanCommand);
 program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).option(
   "--profile <profile>",
   "Starter workspace profile or comma-separated preset list (for example: personal-research or reader,timeline)"
@@ -1027,6 +1140,44 @@ program.command("query").description("Query the compiled SwarmVault wiki.").argu
     await maybeEmitHeuristicNotice(["query"]);
   }
 );
+program.command("chat").description("Ask the compiled wiki in a persisted multi-turn chat session.").argument("[question...]", "Question to ask in a chat session").option("--resume [id]", "Resume a chat session by id/prefix, or the most recent session when no id is supplied").option("--list", "List saved chat sessions", false).option("--delete <id>", "Delete a saved chat session by id/prefix").option("--save-output", "Also persist each answer as a regular wiki/outputs query page", false).option("--gap-fill", "Pull external web-search evidence when the local wiki has gaps (requires webSearch.tasks.queryProvider).").option("--max-history-turns <n>", "Number of prior turns to include as conversational context", "6").addOption(
+  new Option("--format <format>", "Answer format for generated turns").choices(["markdown", "report", "slides", "chart", "image"]).default("markdown")
+).action(
+  async (questionParts, options) => {
+    if (options.list) {
+      const sessions = await listChatSessions(process2.cwd());
+      if (isJson()) {
+        emitJson(sessions);
+      } else {
+        logChatSessions(sessions);
+      }
+      return;
+    }
+    if (options.delete) {
+      const deleted = await deleteChatSession(process2.cwd(), options.delete);
+      if (isJson()) {
+        emitJson(deleted);
+      } else {
+        log(`Deleted chat session ${deleted.id}`);
+      }
+      return;
+    }
+    const question = (questionParts ?? []).join(" ").trim();
+    if (!question) {
+      await runInteractiveChat(options);
+      return;
+    }
+    const result = await runChatQuestion(question, options);
+    if (isJson()) {
+      emitJson(result);
+    } else {
+      log(result.answer);
+      log(`Session: ${result.session.id}`);
+      log(`Saved transcript: ${result.markdownPath}`);
+    }
+    await maybeEmitHeuristicNotice(["chat"]);
+  }
+);
 var context = program.command("context").description("Build and manage token-bounded agent context packs.");
 context.command("build").description("Build a cited, token-bounded context pack for an agent task.").argument("<goal>", "Task, question, or goal the agent needs context for").option("--target <target>", "Optional page, node, path, project, or label to anchor the pack").option("--budget <tokens>", "Approximate token budget for included context", String(8e3)).option("--task <id>", "Attach the context pack to an agent task").option("--memory <id>", "Compatibility alias for --task").addOption(new Option("--format <format>", "Output format").choices(["markdown", "json", "llms"]).default("markdown")).action(
   async (goal, options) => {
@@ -1294,6 +1445,23 @@ program.command("benchmark").description("Measure graph-guided context reduction
     }
   }
 });
+var exportCommand = program.command("export").description("Export portable SwarmVault artifacts.");
+exportCommand.command("ai").description("Export static AI handoff files for agents, crawlers, and documentation systems.").option("--out <dir>", "Output directory", path2.join("wiki", "exports", "ai")).option("--max-full-chars <n>", "Maximum characters to include in llms-full.txt", "5000000").option("--no-page-siblings", "Skip per-page .txt and .json sibling files").action(async (options) => {
+  const result = await exportAiPack(process2.cwd(), {
+    outDir: options.out,
+    maxFullChars: parsePositiveInt(options.maxFullChars, 5e6),
+    pageSiblings: options.pageSiblings ?? true
+  });
+  if (isJson()) {
+    emitJson(result);
+    return;
+  }
+  log(`Exported AI handoff pack to ${result.outputDir}`);
+  log(`Files: ${result.files.length}; pages: ${result.pageCount}; nodes: ${result.nodeCount}; edges: ${result.edgeCount}`);
+  if (result.truncatedFullText) {
+    log("llms-full.txt was truncated; rerun with --max-full-chars for a larger export.");
+  }
+});
 program.command("lint").description("Run anti-drift and wiki-health checks.").option("--deep", "Run LLM-powered advisory lint (default: from config)").option("--no-deep", "Skip deep lint even if enabled in config").option("--web", "Augment deep lint with configured web search", false).option("--conflicts", "Filter to contradiction findings only", false).option("--decay", "Filter to decay-related findings only", false).option("--tiers", "Filter to consolidation-tier findings only", false).action(async (options) => {
   const lintConfig = await loadVaultConfig(process2.cwd()).catch(() => null);
   const deepEnabled = options.decay || options.tiers ? false : options.deep ?? lintConfig?.config.profile.deepLintDefault ?? false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "prepublishOnly": "node ../../scripts/check-release-sync.mjs && node ../../scripts/check-published-manifests.mjs"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "3.11.0",
+    "@swarmvaultai/engine": "3.13.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {