@skill-map/cli 0.40.0 → 0.41.0

package/dist/cli/tutorial/sm-tutorial/SKILL.md

@@ -919,6 +919,11 @@ Tell the tester:
 > the field you'll edit next, so leave the card open and the
 > change will be obvious.
 >
+> ⚠ Heads-up: the inspector header shows a few action buttons
+> (Bump, Close, etc). **Don't click any of them yet** , some of
+> them write files to your project and we cover that flow
+> deliberately in step 13. For now, just look.
+>
 > Now open `.claude/agents/demo-agent.md` in your editor of
 > choice. In the **frontmatter** at the top of the file, change
 > the `description:` field to any text you want, the actual
@@ -1409,9 +1414,13 @@ permission. After you say yes, the choice persists per-checkout
 (gitignored) and the prompt never appears again.
 
 We'll demonstrate by creating an empty annotation scaffold for
-`notes/todo.md`.
+`notes/todo.md`. **Reset any prior consent state first** so the
+prompt actually appears (an earlier step may have flipped the flag
+without you noticing, in which case `sm sidecar annotate` would
+skip straight past the prompt and the lesson would not land):
 
 ```bash
+rm -f notes/todo.sm .skill-map/settings.local.json
 sm sidecar annotate notes/todo.md
 ```
 

package/dist/cli.js

@@ -3855,7 +3855,7 @@ var UPDATE_CHECK_TEXTS = {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.40.0",
+  version: "0.41.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -4287,40 +4287,40 @@ var updateCheckHook = {
 };
 
 // plugins/built-ins.ts
-var claudeProvider2 = { ...claudeProvider, pluginId: "claude", version: "0.40.0" };
-var atDirectiveExtractor2 = { ...atDirectiveExtractor, pluginId: "claude", version: "0.40.0" };
-var slashCommandExtractor2 = { ...slashCommandExtractor, pluginId: "claude", version: "0.40.0" };
-var antigravityProvider2 = { ...antigravityProvider, pluginId: "antigravity", version: "0.40.0" };
-var openaiProvider2 = { ...openaiProvider, pluginId: "openai", version: "0.40.0" };
-var agentSkillsProvider2 = { ...agentSkillsProvider, pluginId: "agent-skills", version: "0.40.0" };
-var coreMarkdownProvider2 = { ...coreMarkdownProvider, pluginId: "core", version: "0.40.0" };
-var annotationsExtractor2 = { ...annotationsExtractor, pluginId: "core", version: "0.40.0" };
-var externalUrlCounterExtractor2 = { ...externalUrlCounterExtractor, pluginId: "core", version: "0.40.0" };
-var markdownLinkExtractor2 = { ...markdownLinkExtractor, pluginId: "core", version: "0.40.0" };
-var mcpToolsExtractor2 = { ...mcpToolsExtractor, pluginId: "core", version: "0.40.0" };
-var toolsCounterExtractor2 = { ...toolsCounterExtractor, pluginId: "core", version: "0.40.0" };
-var annotationFieldUnknownAnalyzer2 = { ...annotationFieldUnknownAnalyzer, pluginId: "core", version: "0.40.0" };
-var annotationOrphanAnalyzer2 = { ...annotationOrphanAnalyzer, pluginId: "core", version: "0.40.0" };
-var annotationStaleAnalyzer2 = { ...annotationStaleAnalyzer, pluginId: "core", version: "0.40.0" };
-var contributionOrphanAnalyzer2 = { ...contributionOrphanAnalyzer, pluginId: "core", version: "0.40.0" };
-var issueCounterAnalyzer2 = { ...issueCounterAnalyzer, pluginId: "core", version: "0.40.0" };
-var jobFileOrphanAnalyzer2 = { ...jobFileOrphanAnalyzer, pluginId: "core", version: "0.40.0" };
-var linkConflictAnalyzer2 = { ...linkConflictAnalyzer, pluginId: "core", version: "0.40.0" };
-var linkCounterAnalyzer2 = { ...linkCounterAnalyzer, pluginId: "core", version: "0.40.0" };
-var linkSelfLoopAnalyzer2 = { ...linkSelfLoopAnalyzer, pluginId: "core", version: "0.40.0" };
-var nameReservedAnalyzer2 = { ...nameReservedAnalyzer, pluginId: "core", version: "0.40.0" };
-var nodeStabilityAnalyzer2 = { ...nodeStabilityAnalyzer, pluginId: "core", version: "0.40.0" };
-var nodeSupersededAnalyzer2 = { ...nodeSupersededAnalyzer, pluginId: "core", version: "0.40.0" };
-var referenceBrokenAnalyzer2 = { ...referenceBrokenAnalyzer, pluginId: "core", version: "0.40.0" };
-var referenceRedundantAnalyzer2 = { ...referenceRedundantAnalyzer, pluginId: "core", version: "0.40.0" };
-var schemaViolationAnalyzer2 = { ...schemaViolationAnalyzer, pluginId: "core", version: "0.40.0" };
-var signalCollisionAnalyzer2 = { ...signalCollisionAnalyzer, pluginId: "core", version: "0.40.0" };
-var triggerCollisionAnalyzer2 = { ...triggerCollisionAnalyzer, pluginId: "core", version: "0.40.0" };
-var asciiFormatter2 = { ...asciiFormatter, pluginId: "core", version: "0.40.0" };
-var jsonFormatter2 = { ...jsonFormatter, pluginId: "core", version: "0.40.0" };
-var nodeBumpAction2 = { ...nodeBumpAction, pluginId: "core", version: "0.40.0" };
-var nodeSupersedeAction2 = { ...nodeSupersedeAction, pluginId: "core", version: "0.40.0" };
-var updateCheckHook2 = { ...updateCheckHook, pluginId: "core", version: "0.40.0" };
+var claudeProvider2 = { ...claudeProvider, pluginId: "claude", version: "0.41.0" };
+var atDirectiveExtractor2 = { ...atDirectiveExtractor, pluginId: "claude", version: "0.41.0" };
+var slashCommandExtractor2 = { ...slashCommandExtractor, pluginId: "claude", version: "0.41.0" };
+var antigravityProvider2 = { ...antigravityProvider, pluginId: "antigravity", version: "0.41.0" };
+var openaiProvider2 = { ...openaiProvider, pluginId: "openai", version: "0.41.0" };
+var agentSkillsProvider2 = { ...agentSkillsProvider, pluginId: "agent-skills", version: "0.41.0" };
+var coreMarkdownProvider2 = { ...coreMarkdownProvider, pluginId: "core", version: "0.41.0" };
+var annotationsExtractor2 = { ...annotationsExtractor, pluginId: "core", version: "0.41.0" };
+var externalUrlCounterExtractor2 = { ...externalUrlCounterExtractor, pluginId: "core", version: "0.41.0" };
+var markdownLinkExtractor2 = { ...markdownLinkExtractor, pluginId: "core", version: "0.41.0" };
+var mcpToolsExtractor2 = { ...mcpToolsExtractor, pluginId: "core", version: "0.41.0" };
+var toolsCounterExtractor2 = { ...toolsCounterExtractor, pluginId: "core", version: "0.41.0" };
+var annotationFieldUnknownAnalyzer2 = { ...annotationFieldUnknownAnalyzer, pluginId: "core", version: "0.41.0" };
+var annotationOrphanAnalyzer2 = { ...annotationOrphanAnalyzer, pluginId: "core", version: "0.41.0" };
+var annotationStaleAnalyzer2 = { ...annotationStaleAnalyzer, pluginId: "core", version: "0.41.0" };
+var contributionOrphanAnalyzer2 = { ...contributionOrphanAnalyzer, pluginId: "core", version: "0.41.0" };
+var issueCounterAnalyzer2 = { ...issueCounterAnalyzer, pluginId: "core", version: "0.41.0" };
+var jobFileOrphanAnalyzer2 = { ...jobFileOrphanAnalyzer, pluginId: "core", version: "0.41.0" };
+var linkConflictAnalyzer2 = { ...linkConflictAnalyzer, pluginId: "core", version: "0.41.0" };
+var linkCounterAnalyzer2 = { ...linkCounterAnalyzer, pluginId: "core", version: "0.41.0" };
+var linkSelfLoopAnalyzer2 = { ...linkSelfLoopAnalyzer, pluginId: "core", version: "0.41.0" };
+var nameReservedAnalyzer2 = { ...nameReservedAnalyzer, pluginId: "core", version: "0.41.0" };
+var nodeStabilityAnalyzer2 = { ...nodeStabilityAnalyzer, pluginId: "core", version: "0.41.0" };
+var nodeSupersededAnalyzer2 = { ...nodeSupersededAnalyzer, pluginId: "core", version: "0.41.0" };
+var referenceBrokenAnalyzer2 = { ...referenceBrokenAnalyzer, pluginId: "core", version: "0.41.0" };
+var referenceRedundantAnalyzer2 = { ...referenceRedundantAnalyzer, pluginId: "core", version: "0.41.0" };
+var schemaViolationAnalyzer2 = { ...schemaViolationAnalyzer, pluginId: "core", version: "0.41.0" };
+var signalCollisionAnalyzer2 = { ...signalCollisionAnalyzer, pluginId: "core", version: "0.41.0" };
+var triggerCollisionAnalyzer2 = { ...triggerCollisionAnalyzer, pluginId: "core", version: "0.41.0" };
+var asciiFormatter2 = { ...asciiFormatter, pluginId: "core", version: "0.41.0" };
+var jsonFormatter2 = { ...jsonFormatter, pluginId: "core", version: "0.41.0" };
+var nodeBumpAction2 = { ...nodeBumpAction, pluginId: "core", version: "0.41.0" };
+var nodeSupersedeAction2 = { ...nodeSupersedeAction, pluginId: "core", version: "0.41.0" };
+var updateCheckHook2 = { ...updateCheckHook, pluginId: "core", version: "0.41.0" };
 var builtInBundles = [
   {
     id: "claude",
@@ -4898,6 +4898,7 @@ var defaults_default = {
     strict: false,
     followSymlinks: false,
     maxFileSizeBytes: 1048576,
+    maxNodes: 256,
     watch: {
       debounceMs: 300
     },
@@ -7037,6 +7038,8 @@ async function loadScanResult(db) {
       roots: parseJsonArray(metaRow.rootsJson),
       providers: parseJsonArray(metaRow.providersJson),
       scannedBy,
+      recommendedNodeLimit: metaRow.recommendedNodeLimit,
+      overrideMaxNodes: metaRow.overrideMaxNodes,
       nodes,
       links,
       issues,
@@ -7060,6 +7063,11 @@ async function loadScanResult(db) {
     scannedAt,
     roots: ["."],
     providers: [],
+    // Synthetic envelope, default to the design cap (256) so SPA reads
+    // the same shape across cold-boot and pre-cap-aware DBs. A real
+    // scan overwrites scan_meta with the live values on next run.
+    recommendedNodeLimit: 256,
+    overrideMaxNodes: null,
     nodes,
     links,
     issues,
@@ -7645,7 +7653,14 @@ function metaToRow(result) {
     providersJson: JSON.stringify(result.providers),
     statsFilesWalked: result.stats.filesWalked,
     statsFilesSkipped: result.stats.filesSkipped,
-    statsDurationMs: result.stats.durationMs
+    statsDurationMs: result.stats.durationMs,
+    ...projectNodeLimitColumns(result)
+  };
+}
+function projectNodeLimitColumns(result) {
+  return {
+    recommendedNodeLimit: result.recommendedNodeLimit ?? 256,
+    overrideMaxNodes: result.overrideMaxNodes ?? null
   };
 }
 function extractorRunToRow(record) {
@@ -15673,17 +15688,26 @@ async function walkAndExtract(opts) {
   const walkOptions = opts.ignoreFilter ? { ignoreFilter: opts.ignoreFilter } : {};
   let filesWalked = 0;
   let index = 0;
+  const effectiveMaxNodes = opts.overrideMaxNodes ?? opts.recommendedNodeLimit;
+  let capReached = false;
   const activeProviders = opts.providers.filter((provider) => {
     if (!provider.gatedByActiveLens) return true;
     if (opts.activeProvider === null) return true;
     return provider.id === opts.activeProvider;
   });
-  for (const provider of activeProviders) {
+  const advance = async (raw, provider) => {
+    const advanced = await processRawNode(raw, provider, wctx, accum, claimedPaths, index + 1);
+    if (advanced) index += 1;
+  };
+  outer: for (const provider of activeProviders) {
     for await (const raw of resolveProviderWalk(provider)(opts.roots, walkOptions)) {
       filesWalked += 1;
       if (claimedPaths.has(raw.path)) continue;
-      const advanced = await processRawNode(raw, provider, wctx, accum, claimedPaths, index + 1);
-      if (advanced) index += 1;
+      if (accum.nodes.length >= effectiveMaxNodes) {
+        capReached = true;
+        break outer;
+      }
+      await advance(raw, provider);
     }
   }
   const orphanSidecars = discoverOrphanSidecars(opts.roots);
@@ -15694,6 +15718,9 @@ async function walkAndExtract(opts) {
     cachedPaths: accum.cachedPaths,
     frontmatterIssues: accum.frontmatterIssues,
     filesWalked,
+    recommendedNodeLimit: opts.recommendedNodeLimit,
+    overrideMaxNodes: opts.overrideMaxNodes,
+    capReached,
     enrichments: [...accum.enrichmentBuffer.values()],
     extractorRuns: accum.extractorRuns,
     contributions: accum.contributionsBuffer,
@@ -15972,7 +15999,9 @@ async function runScanInternal(_kernel, options) {
     priorExtractorRuns: setup.priorExtractorRuns,
     providerFrontmatter: setup.providerFrontmatter,
     pluginStores: options.pluginStores,
-    activeProvider: activeProviderId
+    activeProvider: activeProviderId,
+    recommendedNodeLimit: options.recommendedNodeLimit ?? 256,
+    overrideMaxNodes: options.overrideMaxNodes ?? null
   });
   const activeProvider = activeProviderId ? exts.providers.find((p) => p.id === activeProviderId) ?? null : null;
   const resolved = resolveSignals({
@@ -16140,6 +16169,8 @@ function buildScanReturn(walked, issues, renameOps, stats, options, setup) {
       roots: options.roots,
       providers: setup.exts.providers.map((a) => a.id),
       scannedBy: SCANNED_BY,
+      recommendedNodeLimit: walked.recommendedNodeLimit,
+      overrideMaxNodes: walked.overrideMaxNodes,
       nodes: walked.nodes,
       links: walked.internalLinks,
       issues,
@@ -16830,7 +16861,8 @@ async function runScanForCommand(opts) {
     extensions,
     referenceablePaths,
     ctx.cwd,
-    activeProvider
+    activeProvider,
+    cfg.scan.maxNodes
   );
   const willPersist = !opts.noBuiltIns && !opts.dryRun;
   return willPersist ? runPersistPath(opts, dbPath, jobsDir, strict, loadPrior, runScanWith, extensions) : runEphemeralPath(opts, dbPath, strict, loadPrior, runScanWith);
@@ -16931,7 +16963,7 @@ function makePriorLoader(noBuiltIns, strict) {
     return loaded;
   };
 }
-function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider) {
+function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider, recommendedNodeLimit) {
   return async (prior, priorExtractorRuns, orphanJobFiles) => {
     if (opts.changed && prior === null) {
       opts.stderr.write(SCAN_RUNNER_TEXTS.changedNoPriorWarning);
@@ -16946,6 +16978,7 @@ function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, exte
       cwd: scanCwd,
       prior,
       activeProvider,
+      recommendedNodeLimit,
       ...priorExtractorRuns ? { priorExtractorRuns } : {},
       ...orphanJobFiles ? { orphanJobFiles } : {}
     });
@@ -16959,15 +16992,15 @@ function buildRunScanOptions(args2) {
     tokenize: !opts.noTokens,
     ignoreFilter: args2.ignoreFilter,
     strict: args2.strict,
-    emitter: opts.emitterFactory ? opts.emitterFactory() : createStderrProgressEmitter(opts.stderr, {
-      colorEnabled: opts.colorEnabled === true
-    }),
+    emitter: buildRunScanEmitter(opts),
     // Orphan job-file detection, empty list means "no orphans
     // visible from this caller" (legacy behaviour). The orchestrator
     // defaults to `[]` when the field is absent; we always pass the
     // array (possibly empty) to keep the wiring uniform.
     orphanJobFiles: orphanJobFiles ?? [],
-    activeProvider: args2.activeProvider
+    activeProvider: args2.activeProvider,
+    recommendedNodeLimit: args2.recommendedNodeLimit,
+    overrideMaxNodes: opts.maxNodes ?? null
   };
   if (args2.extensions) runOptions.extensions = args2.extensions;
   if (prior) {
@@ -16979,6 +17012,12 @@ function buildRunScanOptions(args2) {
   runOptions.cwd = args2.cwd;
   return runOptions;
 }
+function buildRunScanEmitter(opts) {
+  if (opts.emitterFactory) return opts.emitterFactory();
+  return createStderrProgressEmitter(opts.stderr, {
+    colorEnabled: opts.colorEnabled === true
+  });
+}
 async function runPersistPath(opts, dbPath, jobsDir, strict, loadPrior, runScanWith, extensions) {
   let outcome;
   try {
@@ -21004,6 +21043,22 @@ var SCAN_TEXTS = {
   persistedTo: "     {{dbPath}}\n",
   /** Body line for dry-run mode, same indent, marker tail. */
   wouldPersist: "     would persist to {{dbPath}}  (dry-run)\n",
+  /**
+   * Cap-hit notice, printed when the walker stopped accepting nodes
+   * because `--max-nodes` (or the `scan.maxNodes` setting) was reached.
+   * `{{glyph}}` is the yellow warning glyph, `{{limit}}` the effective
+   * cap, `{{source}}` either `--max-nodes` or `scan.maxNodes`. The hint
+   * names both escape routes the user has: trimming `.skillmapignore`
+   * (preferred) or raising the cap with `--max-nodes <N>`.
+   */
+  scanCappedNotice: "{{glyph}}  Scan capped at {{limit}} nodes ({{source}}).\n     {{hint}}\n",
+  scanCappedNoticeHint: "Trim .skillmapignore to exclude noisy paths (preferred), or re-run with --max-nodes <N> to raise the cap. Past the recommended limit the graph is hard to read and analyzer signal drops.",
+  /**
+   * Validation message for an invalid `--max-nodes` value. Surfaced as a
+   * §3.1b two-line block.
+   */
+  maxNodesInvalid: "{{glyph}}  --max-nodes must be an integer >= 1 (got `{{value}}`).\n   {{hint}}\n",
+  maxNodesInvalidHint: "Pass a positive integer, e.g. --max-nodes 256.",
   // --- scan compare-with sub-verb --------------------------------------
   compareErrorPrefix: "sm scan compare-with: {{message}}\n",
   compareDumpNotFound: "dump file not found: {{path}}",
@@ -21167,7 +21222,9 @@ function createWatcherRuntime(opts) {
         tokenize,
         ignoreFilter,
         strict,
-        emitter
+        emitter,
+        recommendedNodeLimit: cfg.scan.maxNodes,
+        overrideMaxNodes: opts.maxNodesOverride ?? null
       };
       if (cfg.scan.referencePaths.length > 0) {
         const walk2 = walkReferencePaths(cfg.scan.referencePaths, cwd);
@@ -21380,7 +21437,12 @@ var WATCH_TEXTS = {
    * accepted shape so the operator can re-run without `--help`.
    */
   maxConsecutiveFailuresInvalid: "{{glyph}}  sm watch: --max-consecutive-failures must be a non-negative integer (got {{raw}}).\n   {{hint}}\n",
-  maxConsecutiveFailuresInvalidHint: "Pass an integer >= 0 (0 disables the circuit-breaker; the default is 5)."
+  maxConsecutiveFailuresInvalidHint: "Pass an integer >= 0 (0 disables the circuit-breaker; the default is 5).",
+  /**
+   * §3.1b two-line block. Validation rejection for `--max-nodes`.
+   */
+  maxNodesInvalid: "{{glyph}}  sm watch: --max-nodes must be an integer >= 1 (got {{raw}}).\n   {{hint}}\n",
+  maxNodesInvalidHint: "Pass a positive integer, e.g. --max-nodes 256."
 };
 
 // cli/commands/watch.ts
@@ -21443,6 +21505,7 @@ async function runWatchLoop(opts) {
     circuitBreaker: { maxConsecutiveFailures: breakerLimit },
     killSwitches: readConformanceKillSwitches(),
     ...opts.maxBatches !== void 0 ? { maxBatches: opts.maxBatches } : {},
+    ...opts.maxNodes !== void 0 ? { maxNodesOverride: opts.maxNodes } : {},
     events: {
       onBatch: (outcome) => {
         if (outcome.kind === "ok") {
@@ -21556,6 +21619,10 @@ var WatchCommand = class extends SmCommand {
     required: false,
     description: "Shut down with exit 2 after N consecutive batch failures (default 5; 0 disables the breaker)."
   });
+  maxNodes = Option28.String("--max-nodes", {
+    required: false,
+    description: "Per-batch override of scan.maxNodes (default 256). Bidirectional: raises OR lowers the recommended cap on classified nodes. When a batch hits the cap, additional files are dropped and the UI surfaces the persistent oversized banner. Validation: integer >= 1."
+  });
   // Long-running verb, the watcher prints its own "stopped" line on
   // SIGINT / SIGTERM. Adding `done in <…>` after that would be noise.
   emitElapsed = false;
@@ -21563,6 +21630,8 @@ var WatchCommand = class extends SmCommand {
     const roots = this.roots.length > 0 ? this.roots : ["."];
     const breaker = parseBreakerLimit(this.maxConsecutiveFailures, this.context.stderr, this.noColor);
     if (breaker === null) return ExitCode.Error;
+    const maxNodes = parseMaxNodesLimit(this.maxNodes, this.context.stderr, this.noColor);
+    if (maxNodes === null) return ExitCode.Error;
     const watchOpts = {
       roots,
       json: this.json,
@@ -21575,6 +21644,7 @@ var WatchCommand = class extends SmCommand {
       printer: this.printer
     };
     if (breaker !== void 0) watchOpts.maxConsecutiveFailures = breaker;
+    if (maxNodes !== void 0) watchOpts.maxNodes = maxNodes;
     return runWatchLoop(watchOpts);
   }
 };
@@ -21595,6 +21665,23 @@ function parseBreakerLimit(raw, stderr, noColor) {
   }
   return parsed;
 }
+function parseMaxNodesLimit(raw, stderr, noColor) {
+  if (raw === void 0) return void 0;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) {
+    const stderrTty = stderr;
+    const ansi = ansiFor({ isTTY: stderrTty.isTTY === true, noColorFlag: noColor });
+    stderr.write(
+      tx(WATCH_TEXTS.maxNodesInvalid, {
+        glyph: ansi.red("\u2715"),
+        raw,
+        hint: ansi.dim(WATCH_TEXTS.maxNodesInvalidHint)
+      })
+    );
+    return null;
+  }
+  return n;
+}
 
 // cli/commands/scan.ts
 var ScanCommand = class extends SmCommand {
@@ -21662,10 +21749,16 @@ var ScanCommand = class extends SmCommand {
   yes = Option29.Boolean("--yes", false, {
     description: "Non-interactive mode for ambiguous activeProvider auto-detect. With `--yes`, multiple provider markers (.claude/, .codex/, AGENTS.md, .cursor/) under the scan tree exit non-zero instead of prompting the operator. Set the lens manually via `sm config set activeProvider <id>` and re-run."
   });
+  maxNodes = Option29.String("--max-nodes", {
+    required: false,
+    description: "Per-invocation override of `scan.maxNodes` (default 256). Bidirectional: raises OR lowers the recommended cap on classified nodes. When the walker hits the cap, additional files are dropped and the scan is marked oversized in scan_meta (the UI raises a persistent banner pointing at the .skillmapignore editor in Settings \u2192 Project). Validation: integer >= 1."
+  });
   // Each branch in the orchestrator maps to one validation gate
   // (--watch alias / --changed mutex / -g mutex / dispatch).
   // Splitting per branch scatters the gate from the value it gates.
   async run() {
+    const parsedMaxNodes = this.parseMaxNodesFlag();
+    if (parsedMaxNodes.kind === "error") return parsedMaxNodes.exit;
     if (this.watch) return this.runWatchAlias();
     if (this.changed && this.noBuiltIns) {
       const ansi = this.ansiFor("stderr");
@@ -21701,10 +21794,33 @@ var ScanCommand = class extends SmCommand {
       killSwitches: readConformanceKillSwitches(),
       colorEnabled,
       yes: this.yes,
-      style
+      style,
+      ...parsedMaxNodes.value !== void 0 ? { maxNodes: parsedMaxNodes.value } : {}
     });
     return outcome.kind === "ok" ? this.renderOutcome(outcome.result, outcome.persistedTo, outcome.dbPath, outcome.strict) : this.renderFailure(outcome);
   }
+  /**
+   * Parse `--max-nodes <N>`. Returns either the integer value (or
+   * `undefined` when the flag was omitted) or an error sentinel after
+   * printing the validation block. Invalid (non-integer, < 1) exits 2
+   * per spec/cli-contract.md §Node cap.
+   */
+  parseMaxNodesFlag() {
+    if (this.maxNodes === void 0) return { kind: "ok", value: void 0 };
+    const n = Number(this.maxNodes);
+    if (!Number.isInteger(n) || n < 1) {
+      const ansi = this.ansiFor("stderr");
+      this.printer.info(
+        tx(SCAN_TEXTS.maxNodesInvalid, {
+          glyph: ansi.red("\u2715"),
+          value: this.maxNodes,
+          hint: ansi.dim(SCAN_TEXTS.maxNodesInvalidHint)
+        })
+      );
+      return { kind: "error", exit: ExitCode.Error };
+    }
+    return { kind: "ok", value: n };
+  }
   /**
    * `--watch` is a thin alias for the `sm watch` verb. Combining
    * `--watch` with one-shot-only flags is incoherent, the watcher
@@ -21724,6 +21840,7 @@ var ScanCommand = class extends SmCommand {
     }
     this.emitElapsed = false;
     const roots = this.roots.length > 0 ? this.roots : ["."];
+    const parsedMaxNodes = this.parseMaxNodesFlag();
     return runWatchLoop({
       roots,
       json: this.json,
@@ -21733,7 +21850,8 @@ var ScanCommand = class extends SmCommand {
       db: this.db,
       noPlugins: this.noPlugins,
       context: this.context,
-      printer: this.printer
+      printer: this.printer,
+      ...parsedMaxNodes.kind === "ok" && parsedMaxNodes.value !== void 0 ? { maxNodes: parsedMaxNodes.value } : {}
     });
   }
   /**
@@ -21820,8 +21938,32 @@ var ScanCommand = class extends SmCommand {
         })
       );
     }
+    this.maybePrintCapNotice(result, ansi);
     return exitCode2;
   }
+  /**
+   * Surface the §Node cap notice when the walker actually stopped
+   * accepting files because of the cap. Derivation: `filesWalked >
+   * effectiveLimit` means the walker incremented past the cap at least
+   * once (i.e. classified the (limit+1)-th raw before breaking). When
+   * the project has EXACTLY the cap many files the loop ends naturally
+   * without ever firing the break, so the notice stays silent.
+   */
+  maybePrintCapNotice(result, ansi) {
+    const recommended = result.recommendedNodeLimit;
+    if (recommended === void 0) return;
+    const override = result.overrideMaxNodes ?? null;
+    const effectiveLimit = override ?? recommended;
+    if (result.stats.filesWalked <= effectiveLimit) return;
+    this.printer.info(
+      tx(SCAN_TEXTS.scanCappedNotice, {
+        glyph: ansi.yellow("\u26A0"),
+        limit: String(effectiveLimit),
+        source: override !== null ? "--max-nodes" : "scan.maxNodes",
+        hint: ansi.dim(SCAN_TEXTS.scanCappedNoticeHint)
+      })
+    );
+  }
   /**
    * `--json` output path. Under `--strict` (H4) self-validates the
    * ScanResult against `scan-result.schema.json` before emitting it,
@@ -24285,6 +24427,9 @@ function createWatcherService(opts) {
     if (opts.debounceMsOverride !== void 0) {
       runtimeOpts.debounceMsOverride = opts.debounceMsOverride;
     }
+    if (opts.options.maxNodes !== void 0) {
+      runtimeOpts.maxNodesOverride = opts.options.maxNodes;
+    }
     return runtimeOpts;
   };
   return {
@@ -24362,7 +24507,11 @@ async function runPersistedScan(c, deps) {
         // BFF has no TTY; ambiguous activeProvider must be resolved by
         // the operator via the Settings UI (PATCH /api/active-provider)
         // before the scan, not via interactive prompt here.
-        yes: true
+        yes: true,
+        // `--max-nodes` from the `sm serve` invocation (or the bare
+        // `sm --max-nodes <N>` shortcut) flows through to every scan
+        // the BFF runs so the override is honoured end-to-end.
+        ...deps.options.maxNodes !== void 0 ? { maxNodes: deps.options.maxNodes } : {}
       });
       if (outcome.kind !== "ok") {
         throw new HTTPException13(500, {
@@ -24466,7 +24615,10 @@ async function runFreshScan(deps) {
     printer: bffScanRunnerPrinter,
     // BFF has no TTY; ambiguous activeProvider is the operator's
     // problem to resolve via the Settings UI, not via prompt here.
-    yes: true
+    yes: true,
+    // Carry `--max-nodes` from `sm serve` into the fresh-scan path
+    // too so a UI-driven refresh honours the same cap as the watcher.
+    ...deps.options.maxNodes !== void 0 ? { maxNodes: deps.options.maxNodes } : {}
   });
   if (outcome.kind !== "ok") {
     throw new HTTPException13(500, {
@@ -24488,6 +24640,12 @@ function emptyScanResult() {
     scannedAt: Date.now(),
     roots: ["."],
     providers: [],
+    // Surface the design default so the SPA reads the same field shape
+    // on cold boot as on populated DBs. 256 mirrors `scan.maxNodes`
+    // from `src/config/defaults.json`; the temporary testing default
+    // (2) only applies after a real scan walks through the kernel.
+    recommendedNodeLimit: 256,
+    overrideMaxNodes: null,
     nodes: [],
     links: [],
     issues: [],
@@ -25200,6 +25358,8 @@ function validateServerOptions(input) {
   if (watcherError !== null) return { ok: false, error: watcherError };
   const debounceError = validateWatcherDebounce(input.watcherDebounceMs);
   if (debounceError !== null) return { ok: false, error: debounceError };
+  const maxNodesError = validateMaxNodes(input.maxNodes);
+  if (maxNodesError !== null) return { ok: false, error: maxNodesError };
   const noUiError = validateNoUi(filled.noUi, filled.uiDist);
   if (noUiError !== null) return { ok: false, error: noUiError };
   const options = {
@@ -25217,6 +25377,9 @@ function validateServerOptions(input) {
   if (input.watcherDebounceMs !== void 0) {
     options.watcherDebounceMs = input.watcherDebounceMs;
   }
+  if (input.maxNodes !== void 0) {
+    options.maxNodes = input.maxNodes;
+  }
   return { ok: true, options };
 }
 function applyDefaults(input) {
@@ -25277,6 +25440,17 @@ function validateWatcherDebounce(value) {
   }
   return null;
 }
+function validateMaxNodes(value) {
+  if (value === void 0) return null;
+  if (!Number.isInteger(value) || value < 1) {
+    return {
+      code: "max-nodes-invalid",
+      message: `--max-nodes must be an integer >= 1 (got ${value})`,
+      value: String(value)
+    };
+  }
+  return null;
+}
 function validateNoUi(noUi, uiDist) {
   if (noUi && uiDist !== null) {
     return {
@@ -25556,6 +25730,12 @@ var SERVE_TEXTS = {
    */
   watcherDebounceInvalid: "{{glyph}}  sm serve: --watcher-debounce-ms must be a non-negative integer (got {{value}}).\n   {{hint}}\n",
   watcherDebounceInvalidHint: "Pass an integer >= 0 (e.g. 250).",
+  /**
+   * §3.1b error block for an invalid `--max-nodes <N>`. Same shape as
+   * the watcher-debounce template family.
+   */
+  maxNodesInvalid: "{{glyph}}  sm serve: --max-nodes must be an integer >= 1 (got {{value}}).\n   {{hint}}\n",
+  maxNodesInvalidHint: "Pass a positive integer, e.g. --max-nodes 256.",
   // --- --no-ui flag-validation failures (ExitCode.Error) ------------------
   /**
    * §3.1b error block when `--no-ui` is paired with an explicit
@@ -25825,6 +26005,10 @@ var ServeCommand = class extends SmCommand {
   // who want to tighten / relax the watcher's batching window without
   // editing settings.json. Hidden flag, the Usage block omits it.
   watcherDebounceMs = Option31.String("--watcher-debounce-ms", { required: false, hidden: true });
+  maxNodes = Option31.String("--max-nodes", {
+    required: false,
+    description: "Per-invocation override of scan.maxNodes (default 256). Bidirectional: raises OR lowers the recommended cap on classified nodes. Applies to every scan the server runs (initial watcher pass, debounced batches, POST /api/scan, GET /api/scan?fresh=1). Same flag is honoured on the bare `sm` invocation, which routes to `sm serve`."
+  });
   // Long-running daemon, `done in <…>` after a graceful shutdown is
   // noise. Mirrors `sm watch`'s opt-out.
   emitElapsed = false;
@@ -25903,6 +26087,17 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
+    const maxNodesResult = parseMaxNodes(this.maxNodes);
+    if (!maxNodesResult.ok) {
+      this.printer.info(
+        tx(SERVE_TEXTS.maxNodesInvalid, {
+          glyph: errGlyph,
+          value: sanitizeForTerminal(maxNodesResult.value),
+          hint: stderrAnsi.dim(SERVE_TEXTS.maxNodesInvalidHint)
+        })
+      );
+      return ExitCode.Error;
+    }
     const input = {
       dbPath,
       uiDist: resolvedUiDist,
@@ -25916,6 +26111,7 @@ var ServeCommand = class extends SmCommand {
     if (portResult.port !== void 0) input.port = portResult.port;
     if (this.host !== void 0) input.host = this.host;
     if (debounceResult.value !== void 0) input.watcherDebounceMs = debounceResult.value;
+    if (maxNodesResult.value !== void 0) input.maxNodes = maxNodesResult.value;
     const validation = validateServerOptions(input);
     if (!validation.ok) {
       this.printer.info(formatValidationError(validation.error, stderrAnsi));
@@ -25985,6 +26181,12 @@ function parseDebounce(raw) {
   if (parsed === null) return { ok: false, value: raw };
   return { ok: true, value: parsed };
 }
+function parseMaxNodes(raw) {
+  if (raw === void 0) return { ok: true, value: void 0 };
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 1) return { ok: false, value: raw };
+  return { ok: true, value: n };
+}
 function resolveUiDist(ctx, raw) {
   if (raw === void 0) {
     return { ok: true, uiDist: resolveDefaultUiDist(ctx) };
@@ -26031,6 +26233,12 @@ function formatValidationError(err, ansi) {
         value: sanitizeForTerminal(err.value),
         hint: ansi.dim(SERVE_TEXTS.watcherDebounceInvalidHint)
       });
+    case "max-nodes-invalid":
+      return tx(SERVE_TEXTS.maxNodesInvalid, {
+        glyph: errGlyph,
+        value: sanitizeForTerminal(err.value),
+        hint: ansi.dim(SERVE_TEXTS.maxNodesInvalidHint)
+      });
     case "no-ui-conflicts-ui-dist":
       return tx(SERVE_TEXTS.noUiConflictsUiDist, {
         glyph: errGlyph,
@@ -27409,7 +27617,7 @@ var logLevel = resolveLogLevel({
   errStream: process.stderr
 });
 configureLogger(new Logger({ level: logLevel, stream: process.stderr }));
-var bareArgs = args.length === 0 ? resolveBareDefault() : null;
+var bareArgs = resolveBareInvocation(args);
 var routedArgs = routeHelpArgs(bareArgs ?? args, cli);
 var lifecycleDispatcher = makeHookDispatcher(
   builtIns().hooks ?? [],
@@ -27452,6 +27660,20 @@ await lifecycleDispatcher.dispatch(
   makeEvent("shutdown", { exitCode })
 );
 process.exit(exitCode);
+function resolveBareInvocation(rawArgs) {
+  if (rawArgs.length === 0) return resolveBareDefault();
+  const first = rawArgs[0];
+  const passthrough = /* @__PURE__ */ new Set(["--help", "-h", "--version", "-V", "-v"]);
+  if (first !== void 0 && first.startsWith("-") && !passthrough.has(first)) {
+    const isSingleDashLong = !first.startsWith("--") && first.length > 2;
+    if (isSingleDashLong) return null;
+    if (existsSync30(defaultProjectDbPath(defaultRuntimeContext()))) {
+      return ["serve", ...rawArgs];
+    }
+    return resolveBareDefault();
+  }
+  return null;
+}
 function resolveBareDefault() {
   const ctx = defaultRuntimeContext();
   if (existsSync30(defaultProjectDbPath(ctx))) {