@swarmvaultai/cli 0.7.22 → 0.7.24

package/README.md

@@ -70,7 +70,19 @@ 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.
 
-`--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` starter profile 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`.
+`--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 scan <directory> [--port <port>] [--no-serve]`
+
+Quick-start a scratch vault from a local directory in one command.
+
+- initializes the current directory as a SwarmVault workspace
+- ingests the supplied directory as local sources
+- compiles the vault immediately
+- starts `graph serve` unless you pass `--no-serve`
+- respects `--port` when you want a specific viewer port
+
+Use this when you want the fastest repo or docs-tree walkthrough without first deciding on managed-source registration.
 
 ### `swarmvault source add|list|reload|review|guide|session|delete`
 
@@ -100,6 +112,15 @@ Useful flags:
 
 Managed sources write registry state to `state/sources.json`. Guided sessions write durable anchors to `wiki/outputs/source-sessions/` and session state to `state/source-sessions/`. In an interactive TTY, `--guide` can ask the session questions immediately; otherwise use `source session <id>` or `--answers-file <path>` to resume and stage the approval bundle later. Local directory entries remain compatible with `watch --repo`; remote GitHub and docs-crawl sources are manual `source reload` sources in this release.
 
+Source-scoped artifacts are intentionally split by role:
+
+| Artifact | Created by | Purpose |
+|----------|-----------|---------|
+| Source brief | `source add`, `ingest` (always) | Auto summary written to `wiki/outputs/source-briefs/` |
+| Source review | `source review`, `source add --guide`, `ingest --review`, `ingest --guide` | Lighter staged assessment in `wiki/outputs/source-reviews/` |
+| Source guide | `source guide`, `source add --guide`, `ingest --guide` | Guided walkthrough with approval-bundled updates in `wiki/outputs/source-guides/` |
+| Source session | `source session`, `source add --guide`, `ingest --guide` | Resumable workflow state in `wiki/outputs/source-sessions/` and `state/source-sessions/` |
+
 ### `swarmvault ingest <path-or-url>`
 
 Ingest a local file path, directory path, or URL into immutable source storage and write manifests to `state/manifests/`.
@@ -240,13 +261,13 @@ Run anti-drift and vault health checks such as stale pages, missing graph artifa
 
 Set `profile.deepLintDefault: true` when deep lint should be the default for `swarmvault lint`, and use `--no-deep` when one run should stay structural only.
 
-`--web` can only be used when deep lint is enabled, either explicitly with `--deep` or through `profile.deepLintDefault`. It enriches deep-lint findings with external evidence snippets and URLs from a configured web-search provider.
+`--web` can only be used when deep lint is enabled, either explicitly with `--deep` or through `profile.deepLintDefault`. It enriches deep-lint findings with external evidence snippets and URLs from a configured web-search provider. Web search is currently scoped to deep lint; other commands (compile, query, explore) use only local vault state.
 
 `--conflicts` filters the results down to contradiction-focused findings so you can audit conflicting claims without the rest of the lint output.
 
-### `swarmvault watch [--lint] [--repo] [--once] [--debounce <ms>]`
+### `swarmvault watch [--lint] [--repo] [--once] [--code-only] [--debounce <ms>]`
 
-Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. 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`.
+Watch the inbox directory and trigger import and compile cycles when files change. With `--repo`, each cycle also refreshes tracked repo roots that were previously ingested through directory ingest. With `--once`, SwarmVault runs one refresh cycle immediately instead of starting a long-running watcher. With `--code-only`, SwarmVault forces the narrower AST-only refresh path and skips non-code semantic re-analysis until you run a normal `compile`. 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`.
 
 When `--repo` sees non-code changes under tracked repo roots, SwarmVault records those files under `state/watch/pending-semantic-refresh.json`, marks affected compiled pages stale, and exposes the pending set through `watch status` and the local graph workspace instead of silently re-ingesting them.
 
@@ -264,7 +285,7 @@ Manage SwarmVault's local git hook blocks for the nearest git repository.
 - `hook uninstall` removes only the SwarmVault-managed hook block
 - `hook status` reports whether those managed hook blocks are installed
 
-The installed hooks run `swarmvault watch --repo --once` from the vault root so repo-aware source changes are re-ingested and recompiled after commit and checkout.
+The installed hooks run `swarmvault watch --repo --once --code-only` from the vault root so commit and checkout refreshes update code pages and graph structure quickly. Run a normal `swarmvault compile` when you also want non-code semantic re-analysis.
 
 ### `swarmvault mcp`
 

package/dist/index.js

@@ -270,9 +270,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.7.22";
+    return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.7.24";
   } catch {
-    return "0.7.22";
+    return "0.7.24";
   }
 }
 function parsePositiveInt(value, fallback) {
@@ -981,12 +981,13 @@ candidate.command("archive").description("Archive a candidate by removing it fro
     log(`Archived ${result.pageId}`);
   }
 });
-var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
+var watch = program.command("watch").description("Watch the inbox directory and optionally tracked repos, or run one refresh cycle immediately.").option("--lint", "Run lint after each compile cycle", false).option("--repo", "Also refresh tracked repo sources and watch their repo roots", false).option("--once", "Run one import/refresh cycle immediately instead of starting a watcher", false).option("--code-only", "Only re-extract code sources (AST-only, no LLM re-analysis)", false).option("--debounce <ms>", "Debounce window in milliseconds", "900").action(async (options) => {
   const debounceMs = parsePositiveInt(options.debounce, 900);
   if (options.once) {
     const result = await runWatchCycle(process2.cwd(), {
       lint: options.lint ?? false,
       repo: options.repo ?? false,
+      codeOnly: options.codeOnly ?? false,
       debounceMs
     });
     if (isJson()) {
@@ -1002,6 +1003,7 @@ var watch = program.command("watch").description("Watch the inbox directory and
   const controller = await watchVault(process2.cwd(), {
     lint: options.lint ?? false,
     repo: options.repo ?? false,
+    codeOnly: options.codeOnly ?? false,
     debounceMs
   });
   if (isJson()) {
@@ -1139,6 +1141,39 @@ program.command("install").description("Install SwarmVault instructions for an a
     }
   }
 );
+program.command("scan").description("Quick-start: initialize, ingest, compile, and serve a graph viewer in one command.").argument("<directory>", "Directory to scan").option("--port <port>", "Port for the graph viewer").option("--no-serve", "Skip launching the graph viewer after compile").action(async (directory, options) => {
+  const rootDir = process2.cwd();
+  await initVault(rootDir, {});
+  if (!isJson()) {
+    log("Initialized workspace.");
+  }
+  const result = await ingestDirectory(rootDir, directory, {});
+  if (!isJson()) {
+    log(`Ingested ${result.imported.length} file(s).`);
+  }
+  const compiled = await compileVault(rootDir, {});
+  if (!isJson()) {
+    log(`Compiled ${compiled.sourceCount} source(s), ${compiled.pageCount} page(s).`);
+  }
+  if (options.serve !== false) {
+    const port = options.port ? parsePositiveInt(options.port, 0) || void 0 : void 0;
+    const server = await startGraphServer(rootDir, port, { full: false });
+    if (isJson()) {
+      emitJson({ ...result, compiled, port: server.port, url: `http://localhost:${server.port}` });
+    } else {
+      log(`Graph viewer running at http://localhost:${server.port}`);
+    }
+    process2.on("SIGINT", async () => {
+      try {
+        await server.close();
+      } catch {
+      }
+      process2.exit(0);
+    });
+  } else if (isJson()) {
+    emitJson({ ...result, compiled });
+  }
+});
 program.parseAsync(process2.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   if (isJson()) {

package/package.json

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