@swarmvaultai/cli 0.4.0 → 0.5.0

package/README.md

@@ -22,9 +22,10 @@ Installed commands:
 ```bash
 mkdir my-vault
 cd my-vault
-swarmvault init --obsidian
+swarmvault init --obsidian --profile personal-research
 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 list
 swarmvault source reload --all
 sed -n '1,120p' swarmvault.schema.md
@@ -50,7 +51,7 @@ swarmvault graph push neo4j --dry-run
 
 ## Commands
 
-### `swarmvault init [--obsidian]`
+### `swarmvault init [--obsidian] [--profile personal-research]`
 
 Create a workspace with:
 
@@ -67,19 +68,23 @@ Create a workspace with:
 
 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 source add|list|reload|delete`
+### `swarmvault source add|list|reload|review|guide|delete`
 
 Manage recurring source roots through a registry-backed workflow.
 
 - `source add <input>` supports local directories, public GitHub repo root URLs such as `https://github.com/karpathy/micrograd`, and docs/wiki/help/reference/tutorial hubs
 - by default `source add` registers the source, syncs it into the vault, runs one compile, and writes a source brief to `wiki/outputs/source-briefs/<source-id>.md`
+- add `--guide` when you want a source brief, source review, source guide, and approval bundle for one-source-at-a-time integration
 - `source list` shows every managed source with its kind, status, and current brief path
 - `source reload [id]` re-syncs one source, or use `--all` to refresh everything in the registry and compile once
+- `source review <id>` stages a lighter source-scoped review artifact
+- `source guide <id>` stages the stronger guided-ingest bundle for that source scope
 - `source delete <id>` unregisters the source and removes transient sync state under `state/sources/<id>/`, but leaves canonical `raw/`, `wiki/`, and saved output artifacts intact
 
 Useful flags:
 
 - `--all`
+- `--guide`
 - `--no-compile`
 - `--no-brief`
 - `--max-pages <n>`
@@ -97,6 +102,7 @@ Ingest a local file path, directory path, or URL into immutable source storage a
 - use `source add` instead when the same local directory, public GitHub repo root, or docs hub should stay registered and reloadable
 - URL ingest still localizes remote image references by default
 - local file ingest supports markdown, text, reStructuredText, HTML, PDF, DOCX, images, and code
+- add `--guide` when you want a source brief, source review, source guide, and approval bundle after ingest
 - code-aware directory ingest currently covers JavaScript, JSX, TypeScript, TSX, Python, Go, Rust, Java, Kotlin, Scala, Lua, Zig, C#, C, C++, PHP, Ruby, and PowerShell
 
 Useful flags:

package/dist/index.js

@@ -17,6 +17,8 @@ import {
   exportGraphHtml,
   getGitHookStatus,
   getWatchStatus,
+  guideManagedSource,
+  guideSourceScope,
   importInbox,
   ingestDirectory,
   ingestInputDetailed,
@@ -224,9 +226,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 : "0.4.0";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.5.0";
   } catch {
-    return "0.4.0";
+    return "0.5.0";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -234,6 +236,21 @@ function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(value, 10);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function sourceScopeFromManifests(input, manifests) {
+  if (!manifests.length) {
+    return null;
+  }
+  const primary = manifests[0];
+  return {
+    id: primary?.sourceGroupId ?? primary?.sourceId ?? slugForCli(input),
+    title: primary?.sourceGroupTitle ?? primary?.title ?? input,
+    sourceIds: manifests.map((manifest) => manifest.sourceId),
+    kind: primary?.sourceKind
+  };
+}
+function slugForCli(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "source";
+}
 function isJson() {
   return program.opts().json === true;
 }
@@ -276,15 +293,20 @@ program.hook("postAction", async (_thisCommand, actionCommand) => {
     emitNotice(notice);
   }
 });
-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(process2.cwd(), { obsidian: options.obsidian ?? false });
+program.command("init").description("Initialize a SwarmVault workspace in the current directory.").option("--obsidian", "Generate a minimal .obsidian workspace alongside the vault", false).addOption(new Option("--profile <profile>", "Starter workspace profile").choices(["default", "personal-research"])).action(async (options) => {
+  await initVault(process2.cwd(), { obsidian: options.obsidian ?? false, profile: options.profile });
   if (isJson()) {
-    emitJson({ status: "initialized", rootDir: process2.cwd(), obsidian: options.obsidian ?? false });
+    emitJson({
+      status: "initialized",
+      rootDir: process2.cwd(),
+      obsidian: options.obsidian ?? false,
+      profile: options.profile ?? "default"
+    });
   } else {
     log("Initialized SwarmVault workspace.");
   }
 });
-program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--review", "Stage a source review artifact after ingest and compile", false).option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--include-third-party", "Also ingest repo files classified as third-party", false).option("--include-resources", "Also ingest repo files classified as resources", false).option("--include-generated", "Also ingest repo files classified as generated output", false).option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").action(
+program.command("ingest").description("Ingest a local file path, directory path, or URL into the raw SwarmVault workspace.").argument("<input>", "Local file path, directory path, or URL").option("--review", "Stage a source review artifact after ingest and compile", false).option("--guide", "Stage a guided source integration bundle after ingest and compile", false).option("--include-assets", "Download remote image assets when ingesting URLs", true).option("--no-include-assets", "Skip downloading remote image assets when ingesting URLs").option("--max-asset-size <bytes>", "Maximum number of bytes to fetch for a single remote image asset").option("--repo-root <path>", "Override the detected repo root when ingesting a directory").option("--include <glob...>", "Only ingest files matching one or more glob patterns").option("--exclude <glob...>", "Skip files matching one or more glob patterns").option("--max-files <n>", "Maximum number of files to ingest from a directory").option("--include-third-party", "Also ingest repo files classified as third-party", false).option("--include-resources", "Also ingest repo files classified as resources", false).option("--include-generated", "Also ingest repo files classified as generated output", false).option("--no-gitignore", "Ignore .gitignore rules when ingesting a directory").action(
   async (input, options) => {
     const maxAssetSize = typeof options.maxAssetSize === "string" && options.maxAssetSize.trim() ? parsePositiveInt(options.maxAssetSize, 0) || void 0 : void 0;
     const maxFiles = typeof options.maxFiles === "string" && options.maxFiles.trim() ? parsePositiveInt(options.maxFiles, 0) || void 0 : void 0;
@@ -308,8 +330,7 @@ program.command("ingest").description("Ingest a local file path, directory path,
       (fs) => fs.stat(input).then((stat) => stat.isDirectory() ? ingestDirectory(process2.cwd(), input, commonOptions) : null).catch(() => null)
     ) : null;
     if (directoryResult) {
-      const review3 = options.review && (directoryResult.imported.length || directoryResult.updated.length) ? await (async () => {
-        await compileVault(process2.cwd(), {});
+      const scope2 = options.review || options.guide ? await (async () => {
         const pathModule = await import("path");
         const absoluteInput = pathModule.resolve(process2.cwd(), input);
         const sourceIds = (await listManifests(process2.cwd())).filter((manifest) => {
@@ -319,14 +340,24 @@ program.command("ingest").description("Ingest a local file path, directory path,
           const relative = pathModule.relative(absoluteInput, pathModule.resolve(manifest.originalPath));
           return relative === "" || !relative.startsWith("..") && !pathModule.isAbsolute(relative);
         }).map((manifest) => manifest.sourceId);
-        return sourceIds.length ? await reviewSourceScope(process2.cwd(), {
+        return sourceIds.length ? {
           id: `directory-${absoluteInput.split(pathModule.sep).pop() ?? "source"}`,
           title: absoluteInput.split(pathModule.sep).pop() ?? absoluteInput,
-          sourceIds
-        }) : void 0;
+          sourceIds,
+          kind: "directory"
+        } : void 0;
+      })() : void 0;
+      const shouldStage = Boolean(scope2 && (directoryResult.imported.length || directoryResult.updated.length));
+      const review3 = shouldStage && options.review && !options.guide ? await (async () => {
+        await compileVault(process2.cwd(), {});
+        return await reviewSourceScope(process2.cwd(), scope2);
+      })() : void 0;
+      const guide2 = shouldStage && options.guide ? await (async () => {
+        await compileVault(process2.cwd(), {});
+        return await guideSourceScope(process2.cwd(), scope2);
       })() : void 0;
       if (isJson()) {
-        emitJson(review3 ? { ingest: directoryResult, review: review3 } : directoryResult);
+        emitJson(guide2 ? { ingest: directoryResult, guide: guide2 } : review3 ? { ingest: directoryResult, review: review3 } : directoryResult);
       } else {
         log(
           `Imported ${directoryResult.imported.length} file(s), updated ${directoryResult.updated.length}, skipped ${directoryResult.skipped.length}.`
@@ -334,21 +365,24 @@ program.command("ingest").description("Ingest a local file path, directory path,
         if (review3) {
           log(`Staged source review at ${review3.reviewPath}.`);
         }
+        if (guide2) {
+          log(`Staged source guide at ${guide2.guidePath}.`);
+        }
       }
       return;
     }
     const ingest = await ingestInputDetailed(process2.cwd(), input, commonOptions);
-    const review2 = options.review && (ingest.created.length || ingest.updated.length || ingest.unchanged.length) ? await (async () => {
+    const scope = sourceScopeFromManifests(input, [...ingest.created, ...ingest.updated, ...ingest.unchanged]);
+    const review2 = options.review && !options.guide && scope && (ingest.created.length || ingest.updated.length || ingest.unchanged.length) ? await (async () => {
+      await compileVault(process2.cwd(), {});
+      return await reviewSourceScope(process2.cwd(), scope);
+    })() : void 0;
+    const guide = options.guide && scope && (ingest.created.length || ingest.updated.length || ingest.unchanged.length) ? await (async () => {
       await compileVault(process2.cwd(), {});
-      const scopeSourceIds = [...ingest.created, ...ingest.updated, ...ingest.unchanged].map((manifest) => manifest.sourceId);
-      return await reviewSourceScope(process2.cwd(), {
-        id: ingest.created[0]?.sourceGroupId ?? ingest.updated[0]?.sourceGroupId ?? ingest.unchanged[0]?.sourceGroupId ?? scopeSourceIds[0],
-        title: [...ingest.created, ...ingest.updated, ...ingest.unchanged][0]?.sourceGroupTitle ?? [...ingest.created, ...ingest.updated, ...ingest.unchanged][0]?.title ?? input,
-        sourceIds: scopeSourceIds
-      });
+      return await guideSourceScope(process2.cwd(), scope);
     })() : void 0;
     if (isJson()) {
-      emitJson(review2 ? { ingest, review: review2 } : ingest);
+      emitJson(guide ? { ingest, guide } : review2 ? { ingest, review: review2 } : ingest);
     } else {
       const primary = [...ingest.created, ...ingest.updated, ...ingest.unchanged][0];
       if (ingest.created.length + ingest.updated.length + ingest.removed.length <= 1 && primary) {
@@ -361,6 +395,9 @@ program.command("ingest").description("Ingest a local file path, directory path,
       if (review2) {
         log(`Staged source review at ${review2.reviewPath}.`);
       }
+      if (guide) {
+        log(`Staged source guide at ${guide.guidePath}.`);
+      }
     }
   }
 );
@@ -376,12 +413,13 @@ program.command("add").description("Capture supported URLs into normalized markd
   }
 });
 var source = program.command("source").description("Manage recurring local files, directories, public repos, and docs sources.");
-source.command("add").description("Register and sync a managed source from a local file, directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "Local file path, directory path, public GitHub repo root URL, or docs hub URL").option("--no-compile", "Register and sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--review", "Stage a source review artifact after sync and compile", false).option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
+source.command("add").description("Register and sync a managed source from a local file, directory, public GitHub repo root URL, or docs hub URL.").argument("<input>", "Local file path, directory path, public GitHub repo root URL, or docs hub URL").option("--no-compile", "Register and sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--review", "Stage a source review artifact after sync and compile", false).option("--guide", "Stage a guided source integration bundle after sync and compile", false).option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
   async (input, options) => {
     const result = await addManagedSource(process2.cwd(), input, {
       compile: options.compile,
       brief: options.brief,
       review: options.review,
+      guide: options.guide,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
       maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
     });
@@ -389,7 +427,7 @@ source.command("add").description("Register and sync a managed source from a loc
       emitJson(result);
     } else {
       log(
-        `Registered ${result.source.kind} source ${result.source.id}. Status: ${result.source.status}.${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefGenerated ? ` Brief: ${result.source.briefPath}` : ""}${result.review ? ` Review: ${result.review.reviewPath}` : ""}`
+        `Registered ${result.source.kind} source ${result.source.id}. Status: ${result.source.status}.${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefGenerated ? ` Brief: ${result.source.briefPath}` : ""}${result.review ? ` Review: ${result.review.reviewPath}` : ""}${result.guide ? ` Guide: ${result.guide.guidePath}` : ""}`
       );
     }
   }
@@ -406,13 +444,15 @@ source.command("list").description("List managed sources registered in this vaul
     }
   }
 });
-source.command("reload").description("Re-sync one managed source or all managed sources, then optionally compile and refresh briefs.").argument("[id]", "Managed source id").option("--all", "Reload all managed sources", false).option("--no-compile", "Re-sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
+source.command("reload").description("Re-sync one managed source or all managed sources, then optionally compile and refresh briefs.").argument("[id]", "Managed source id").option("--all", "Reload all managed sources", false).option("--no-compile", "Re-sync without compiling the vault").option("--no-brief", "Skip source brief generation after sync").option("--review", "Stage a source review artifact after sync and compile", false).option("--guide", "Stage a guided source integration bundle after sync and compile", false).option("--max-pages <n>", "Maximum number of pages to crawl for docs sources").option("--max-depth <n>", "Maximum crawl depth for docs sources").action(
   async (id, options) => {
     const result = await reloadManagedSources(process2.cwd(), {
       id,
       all: options.all ?? false,
       compile: options.compile,
       brief: options.brief,
+      review: options.review,
+      guide: options.guide,
       maxPages: options.maxPages ? parsePositiveInt(options.maxPages, 0) || void 0 : void 0,
       maxDepth: options.maxDepth ? parsePositiveInt(options.maxDepth, 0) || void 0 : void 0
     });
@@ -420,7 +460,7 @@ source.command("reload").description("Re-sync one managed source or all managed
       emitJson(result);
     } else {
       log(
-        `Reloaded ${result.sources.length} source(s).${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefPaths.length ? ` Briefs: ${result.briefPaths.length}.` : ""}`
+        `Reloaded ${result.sources.length} source(s).${result.compile ? ` Compiled ${result.compile.sourceCount} source(s).` : ""}${result.briefPaths.length ? ` Briefs: ${result.briefPaths.length}.` : ""}${result.reviews.length ? ` Reviews: ${result.reviews.length}.` : ""}${result.guides.length ? ` Guides: ${result.guides.length}.` : ""}`
       );
     }
   }
@@ -441,6 +481,14 @@ source.command("review").description("Stage a source review artifact for a manag
     log(`Staged source review at ${result.reviewPath}.`);
   }
 });
+source.command("guide").description("Stage a guided source integration bundle for a managed source id or raw source id.").argument("<id>", "Managed source id or raw source id").action(async (id) => {
+  const result = await guideManagedSource(process2.cwd(), id);
+  if (isJson()) {
+    emitJson(result);
+  } else {
+    log(`Staged source guide at ${result.guidePath}.`);
+  }
+});
 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(process2.cwd(), dir);
@@ -651,7 +699,7 @@ review.command("list").description("List staged approval bundles and their resol
   }
   for (const approval of approvals) {
     log(
-      `${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount} created=${approval.createdAt}`
+      `${approval.approvalId}${approval.bundleType ? ` [${approval.bundleType}]` : ""}${approval.title ? ` ${approval.title}` : ""} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount} created=${approval.createdAt}`
     );
   }
 });
@@ -661,9 +709,13 @@ review.command("show").description("Show the entries inside a staged approval bu
     emitJson(approval);
     return;
   }
-  log(`${approval.approvalId} pending=${approval.pendingCount} accepted=${approval.acceptedCount} rejected=${approval.rejectedCount}`);
+  log(
+    `${approval.approvalId}${approval.bundleType ? ` [${approval.bundleType}]` : ""}${approval.title ? ` ${approval.title}` : ""} 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());
+    log(
+      `- ${entry.status} ${entry.changeType}${entry.label ? ` [${entry.label}]` : ""} ${entry.pageId} ${entry.nextPath ?? entry.previousPath ?? ""}`.trim()
+    );
     if (entry.changeSummary) log(`  Summary: ${entry.changeSummary}`);
     if (entry.diff) {
       log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmvaultai/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Global CLI for SwarmVault.",
   "type": "module",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@swarmvaultai/engine": "0.4.0",
+    "@swarmvaultai/engine": "0.5.0",
     "commander": "^14.0.1"
   },
   "devDependencies": {