@skill-map/cli 0.61.4 → 0.62.0

package/dist/cli.js

@@ -1,6 +1,6 @@
 // cli/entry.ts
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d6e5d903-0942-5718-94b3-53a96de15b21")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d7ccbbda-dc56-582c-966a-4822e4bdcd83")}catch(e){}}();
 import { existsSync as existsSync33 } from "fs";
 import { Builtins, Cli as Cli2 } from "clipanion";
 
@@ -250,7 +250,7 @@ function bucketByKind(kind, instance, bag) {
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.61.4",
+  version: "0.62.0",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -812,6 +812,15 @@ function extractCodeRegions(input) {
   }
   return out;
 }
+var HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+var HTML_TAG_RE = /<\/?[a-zA-Z][a-zA-Z0-9-]*(?:\s+(?:"[^"]*"|'[^']*'|[^"'>])*)?\/?\s*>/g;
+function stripHtml(input) {
+  if (!input) return input;
+  return input.replace(HTML_COMMENT_RE, (m) => blank(m)).replace(HTML_TAG_RE, (m) => blank(m));
+}
+function stripCodeAndHtml(input) {
+  return stripHtml(stripCodeBlocks(input));
+}
 function stripFences(input) {
   const out = [];
   const lines = input.split("\n");
@@ -896,7 +905,7 @@ var atDirectiveExtractor = {
   extract(ctx) {
     const seenMentions = /* @__PURE__ */ new Set();
     const seenReferences = /* @__PURE__ */ new Set();
-    const body = stripCodeBlocks(ctx.body);
+    const body = stripCodeAndHtml(ctx.body);
     const lineStarts = computeLineStarts(body);
     const sourceDir = pathPosix.dirname(ctx.node.path);
     for (const match of body.matchAll(AT_RE)) {
@@ -982,7 +991,7 @@ var slashCommandExtractor = {
   precondition: { provider: ["claude"] },
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
-    const body = stripCodeBlocks(ctx.body);
+    const body = stripCodeAndHtml(ctx.body);
     const lineStarts = computeLineStarts(body);
     for (const match of body.matchAll(SLASH_RE)) {
       const original = match[1];
@@ -1566,7 +1575,7 @@ var externalUrlCounterExtractor = {
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
     const ignoredDomains = readIgnoredDomains(ctx.settings[SETTING_IGNORED_DOMAINS]);
-    const body = stripCodeBlocks(ctx.body);
+    const body = stripCodeAndHtml(ctx.body);
     const lineStarts = computeLineStarts(body);
     for (const match of body.matchAll(URL_RE)) {
       const original = stripTrailingPunctuation(match[0]);
@@ -1638,7 +1647,7 @@ var markdownLinkExtractor = {
   scope: "body",
   extract(ctx) {
     const seen = /* @__PURE__ */ new Set();
-    const body = stripCodeBlocks(ctx.body);
+    const body = stripCodeAndHtml(ctx.body);
     const lineStarts = computeLineStarts(body);
     const sourceDir = pathPosix3.dirname(ctx.node.path);
     for (const match of body.matchAll(LINK_RE)) {
@@ -5312,6 +5321,7 @@ var defaults_default = {
     tokenize: true,
     strict: false,
     maxFileSizeBytes: 1048576,
+    maxScan: 5e4,
     maxNodes: 256,
     watch: {
       debounceMs: 300
@@ -6207,7 +6217,7 @@ import { existsSync as existsSync11 } from "fs";
 import { mkdirSync as mkdirSync4 } from "fs";
 import { dirname as dirname8, resolve as resolve11 } from "path";
 import { DatabaseSync as DatabaseSync4 } from "node:sqlite";
-import { CamelCasePlugin, Kysely, sql as sql3 } from "kysely";
+import { CamelCasePlugin, Kysely, sql as sql4 } from "kysely";
 
 // kernel/i18n/storage.texts.ts
 var STORAGE_TEXTS = {
@@ -6304,8 +6314,8 @@ var NodeSqliteConnection = class {
   constructor(db) {
     this.#db = db;
   }
-  exec(sql4) {
-    this.#db.exec(sql4);
+  exec(sql5) {
+    this.#db.exec(sql5);
   }
   async executeQuery(query) {
     const stmt = this.#db.prepare(query.sql);
@@ -6338,7 +6348,7 @@ var AsyncMutex = class {
       this.#locked = true;
       return;
     }
-    await new Promise((resolve40) => this.#waiters.push(resolve40));
+    await new Promise((resolve43) => this.#waiters.push(resolve43));
     this.#locked = true;
   }
   unlock() {
@@ -6882,10 +6892,10 @@ function applyOneMigration(db, migration) {
       tx(MIGRATIONS_TEXTS.invalidVersion, { value: String(migration.version) })
     );
   }
-  const sql4 = readFileSync8(migration.filePath, "utf8");
+  const sql5 = readFileSync8(migration.filePath, "utf8");
   try {
     db.exec("BEGIN");
-    db.exec(sql4);
+    db.exec(sql5);
     db.prepare(
       `INSERT INTO config_schema_versions (scope, owner_id, version, description, applied_at)
        VALUES ('kernel', 'kernel', ?, ?, ?)`
@@ -6929,37 +6939,37 @@ import { join as join6 } from "path";
 function normalizePluginId(id) {
   return id.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
 }
-function stripComments(sql4) {
-  return sql4.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n\r]*/g, " ");
+function stripComments(sql5) {
+  return sql5.replace(/\/\*[\s\S]*?\*\//g, " ").replace(/--[^\n\r]*/g, " ");
 }
-function detectCommentMarkerInLiteral(sql4) {
+function detectCommentMarkerInLiteral(sql5) {
   let i = 0;
-  while (i < sql4.length) {
-    const ch = sql4[i];
+  while (i < sql5.length) {
+    const ch = sql5[i];
     if (ch === "'") {
-      const end = scanCheckedLiteral(sql4, i + 1, "'", "string literal");
+      const end = scanCheckedLiteral(sql5, i + 1, "'", "string literal");
       if (typeof end === "string") return end;
       i = end;
     } else if (ch === '"') {
-      const end = scanCheckedLiteral(sql4, i + 1, '"', "double-quoted identifier");
+      const end = scanCheckedLiteral(sql5, i + 1, '"', "double-quoted identifier");
       if (typeof end === "string") return end;
       i = end;
     } else if (ch === "`") {
-      i = skipUntilCloser(sql4, i + 1, "`");
+      i = skipUntilCloser(sql5, i + 1, "`");
     } else if (ch === "[") {
-      i = skipUntilCloser(sql4, i + 1, "]");
+      i = skipUntilCloser(sql5, i + 1, "]");
     } else {
       i++;
     }
   }
   return null;
 }
-function scanCheckedLiteral(sql4, start, closer, label) {
+function scanCheckedLiteral(sql5, start, closer, label) {
   const allowStack = closer === "'";
   let i = start;
-  while (i < sql4.length) {
-    const ch = sql4[i];
-    const next = sql4[i + 1];
+  while (i < sql5.length) {
+    const ch = sql5[i];
+    const next = sql5[i + 1];
     if (allowStack && ch === closer && next === closer) {
       i += 2;
       continue;
@@ -6980,10 +6990,10 @@ function findCommentMarker(ch, next, label) {
   }
   return null;
 }
-function skipUntilCloser(sql4, start, closer) {
+function skipUntilCloser(sql5, start, closer) {
   let i = start;
-  while (i < sql4.length) {
-    if (sql4[i] === closer) return i + 1;
+  while (i < sql5.length) {
+    if (sql5[i] === closer) return i + 1;
     i++;
   }
   return i;
@@ -7094,14 +7104,14 @@ function stripIdentifierWrapper(raw) {
   return raw;
 }
 var QUOTE_OPENERS = /* @__PURE__ */ new Set(["'", '"', "`", "["]);
-function splitStatements(sql4) {
+function splitStatements(sql5) {
   const out = [];
   let current = "";
   let i = 0;
-  while (i < sql4.length) {
-    const ch = sql4[i];
+  while (i < sql5.length) {
+    const ch = sql5[i];
     if (QUOTE_OPENERS.has(ch)) {
-      const consumed = copyQuotedRegion(sql4, i, ch);
+      const consumed = copyQuotedRegion(sql5, i, ch);
       current += consumed.text;
       i = consumed.next;
       continue;
@@ -7120,16 +7130,16 @@ function splitStatements(sql4) {
   if (tail.length > 0) out.push(tail);
   return out;
 }
-function copyQuotedRegion(sql4, start, opener) {
+function copyQuotedRegion(sql5, start, opener) {
   const closer = opener === "[" ? "]" : opener;
   const allowStack = opener === "'";
   let text = opener;
   let i = start + 1;
-  while (i < sql4.length) {
-    const ch = sql4[i];
+  while (i < sql5.length) {
+    const ch = sql5[i];
     text += ch;
     if (ch === closer) {
-      if (allowStack && sql4[i + 1] === closer) {
+      if (allowStack && sql5[i + 1] === closer) {
         text += closer;
         i += 2;
         continue;
@@ -7140,11 +7150,11 @@ function copyQuotedRegion(sql4, start, opener) {
   }
   return { text, next: i };
 }
-function validatePluginMigrationSql(sql4, normalizedId) {
-  const literalIssue = detectCommentMarkerInLiteral(sql4);
+function validatePluginMigrationSql(sql5, normalizedId) {
+  const literalIssue = detectCommentMarkerInLiteral(sql5);
   if (literalIssue) return { ok: false, violations: [literalIssue] };
   const prefix = `plugin_${normalizedId}_`;
-  const stripped = stripComments(sql4);
+  const stripped = stripComments(sql5);
   const violations = [
     ...detectForbiddenKeywords(stripped),
     ...detectStatementViolations(stripped, prefix)
@@ -7305,9 +7315,9 @@ function applyPluginMigrations(db, plugin, options = {}, files = discoverPluginM
 function preflightValidateAll(pending, normalizedId, pluginId) {
   const sources = /* @__PURE__ */ new Map();
   for (const m of pending) {
-    const sql4 = readFileSync9(m.filePath, "utf8");
-    sources.set(m.filePath, sql4);
-    const result = validatePluginMigrationSql(sql4, normalizedId);
+    const sql5 = readFileSync9(m.filePath, "utf8");
+    sources.set(m.filePath, sql5);
+    const result = validatePluginMigrationSql(sql5, normalizedId);
     if (!result.ok) {
       throw new Error(
         `Plugin ${pluginId}: migration ${formatMigrationName(m)} failed validation:
@@ -7317,8 +7327,8 @@ function preflightValidateAll(pending, normalizedId, pluginId) {
   }
   return sources;
 }
-function applyOnePluginMigration(db, plugin, migration, sql4, normalizedId) {
-  const result = validatePluginMigrationSql(sql4, normalizedId);
+function applyOnePluginMigration(db, plugin, migration, sql5, normalizedId) {
+  const result = validatePluginMigrationSql(sql5, normalizedId);
   if (!result.ok) {
     throw new Error(
       `Plugin ${plugin.id}: migration ${formatMigrationName(migration)} failed Layer-2 validation:
@@ -7327,7 +7337,7 @@ function applyOnePluginMigration(db, plugin, migration, sql4, normalizedId) {
   }
   try {
     db.exec("BEGIN");
-    db.exec(sql4);
+    db.exec(sql5);
     db.prepare(
       `INSERT INTO config_schema_versions (scope, owner_id, version, description, applied_at)
        VALUES ('plugin', ?, ?, ?, ?)`
@@ -7386,6 +7396,9 @@ async function loadPluginOverrideMap(db) {
   return out;
 }
 
+// kernel/adapters/sqlite/scan-load.ts
+import { sql as sql2 } from "kysely";
+
 // kernel/util/enum-parsers.ts
 var STABILITY_VALUES2 = Object.freeze([
   "experimental",
@@ -7482,40 +7495,11 @@ async function loadScanResult(db) {
     );
   }
   if (metaRow) {
-    const scannedBy = {
-      name: metaRow.scannedByName,
-      version: metaRow.scannedByVersion,
-      specVersion: metaRow.scannedBySpecVersion
-    };
-    const oversizedFiles = parseJsonArray(metaRow.oversizedFilesJson);
-    return {
-      schemaVersion: 1,
-      scannedAt: metaRow.scannedAt,
-      roots: parseJsonArray(metaRow.rootsJson),
-      providers: parseJsonArray(metaRow.providersJson),
-      scannedBy,
-      // Resolved encoder of the prior scan (see project-config.schema.json
-      // §tokenizer). NULL column → `undefined` domain field; the
-      // orchestrator's tokenizer-change check compares this against the
-      // freshly-resolved encoder and treats a missing prior value as a
-      // change (forcing a token recompute).
-      ...metaRow.tokenizer !== null ? { tokenizer: metaRow.tokenizer } : {},
-      recommendedNodeLimit: metaRow.recommendedNodeLimit,
-      overrideMaxNodes: metaRow.overrideMaxNodes,
-      oversizedFiles,
-      nodes,
-      links,
-      issues,
-      stats: {
-        filesWalked: metaRow.statsFilesWalked,
-        filesSkipped: metaRow.statsFilesSkipped,
-        filesOversized: metaRow.filesOversized,
-        nodesCount: nodes.length,
-        linksCount: links.length,
-        issuesCount: issues.length,
-        durationMs: metaRow.statsDurationMs
-      }
-    };
+    return buildScanResultFromMeta(metaRow, nodes, links, issues, {
+      nodesCount: nodes.length,
+      linksCount: links.length,
+      issuesCount: issues.length
+    });
   }
   let scannedAt = 0;
   for (const row of nodeRows) {
@@ -7527,11 +7511,13 @@ 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,
+    // Synthetic envelope, default to the design knobs (corpus ceiling
+    // 50000, render cap 256, not truncated) so the SPA reads the same
+    // shape across cold-boot and never-scanned scopes. A real scan
+    // overwrites scan_meta with the live values on next run.
+    scanCeiling: 5e4,
+    scanTruncated: false,
+    maxRenderNodes: 256,
     oversizedFiles: [],
     nodes,
     links,
@@ -7547,6 +7533,175 @@ async function loadScanResult(db) {
     }
   };
 }
+function buildScanResultFromMeta(metaRow, nodes, links, issues, counts) {
+  const scannedBy = {
+    name: metaRow.scannedByName,
+    version: metaRow.scannedByVersion,
+    specVersion: metaRow.scannedBySpecVersion
+  };
+  const oversizedFiles = parseJsonArray(metaRow.oversizedFilesJson);
+  return {
+    schemaVersion: 1,
+    scannedAt: metaRow.scannedAt,
+    roots: parseJsonArray(metaRow.rootsJson),
+    providers: parseJsonArray(metaRow.providersJson),
+    scannedBy,
+    // Resolved encoder of the prior scan (see project-config.schema.json
+    // §tokenizer). A NULL column maps to an absent domain field; the
+    // orchestrator's tokenizer-change check treats a missing prior value
+    // as a change (forcing a token recompute).
+    ...metaRow.tokenizer !== null ? { tokenizer: metaRow.tokenizer } : {},
+    scanCeiling: metaRow.scanCeiling,
+    scanTruncated: metaRow.scanTruncated === 1,
+    maxRenderNodes: metaRow.maxRenderNodes,
+    oversizedFiles,
+    nodes,
+    links,
+    issues,
+    stats: {
+      filesWalked: metaRow.statsFilesWalked,
+      filesSkipped: metaRow.statsFilesSkipped,
+      filesOversized: metaRow.filesOversized,
+      nodesCount: counts.nodesCount,
+      linksCount: counts.linksCount,
+      issuesCount: counts.issuesCount,
+      durationMs: metaRow.statsDurationMs
+    }
+  };
+}
+async function loadScanMeta(db, counts) {
+  const metaRow = await db.selectFrom("scan_meta").selectAll().executeTakeFirst();
+  const c = {
+    nodesCount: counts.nodes,
+    linksCount: counts.links,
+    issuesCount: counts.issues
+  };
+  if (metaRow) {
+    return buildScanResultFromMeta(metaRow, [], [], [], c);
+  }
+  return {
+    schemaVersion: 1,
+    scannedAt: Date.now(),
+    roots: ["."],
+    providers: [],
+    scanCeiling: 5e4,
+    scanTruncated: false,
+    maxRenderNodes: 256,
+    oversizedFiles: [],
+    nodes: [],
+    links: [],
+    issues: [],
+    stats: {
+      filesWalked: 0,
+      filesSkipped: 0,
+      filesOversized: 0,
+      nodesCount: c.nodesCount,
+      linksCount: c.linksCount,
+      issuesCount: c.issuesCount,
+      durationMs: 0
+    }
+  };
+}
+var DEFAULT_MAX_RENDER_NODES = 256;
+async function loadLiteNodes(db) {
+  const rows = await db.selectFrom("scan_nodes").select([
+    "path",
+    "kind",
+    "linksInCount",
+    "linksOutCount",
+    "tokensTotal",
+    "modifiedAtMs",
+    "sidecarStatus"
+  ]).orderBy("path", "asc").execute();
+  return rows.map((r) => ({
+    path: r.path,
+    kind: r.kind,
+    linksInCount: r.linksInCount,
+    linksOutCount: r.linksOutCount,
+    tokensTotal: r.tokensTotal,
+    modifiedAtMs: r.modifiedAtMs,
+    sidecarStatus: r.sidecarStatus
+  }));
+}
+async function loadIssueCountsByPath(db) {
+  const rows = await db.selectFrom(
+    sql2`(
+        SELECT je.value AS value, si.severity AS severity, COUNT(*) AS c
+        FROM scan_issues si, json_each(si.node_ids_json) je
+        WHERE si.severity IN ('error', 'warn')
+        GROUP BY je.value, si.severity
+      )`.as("incidence")
+  ).select(["value", "severity", "c"]).execute();
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const bucket = out.get(row.value) ?? { error: 0, warn: 0 };
+    if (row.severity === "error") bucket.error = Number(row.c);
+    else if (row.severity === "warn") bucket.warn = Number(row.c);
+    out.set(row.value, bucket);
+  }
+  return out;
+}
+async function loadEffectiveMaxRenderNodes(db) {
+  const metaRow = await db.selectFrom("scan_meta").select(["maxRenderNodes"]).executeTakeFirst();
+  return metaRow?.maxRenderNodes ?? DEFAULT_MAX_RENDER_NODES;
+}
+async function loadBranch(db, prefixes, limit) {
+  const uniquePrefixes = [...new Set(prefixes)];
+  const total = await countBranchNodes(db, uniquePrefixes);
+  const nodeRows = await applyBranchScope(
+    db.selectFrom("scan_nodes").selectAll(),
+    uniquePrefixes
+  ).orderBy("path", "asc").limit(limit).execute();
+  const nodes = nodeRows.map(rowToNode);
+  const pathSet = new Set(nodes.map((n) => n.path));
+  if (pathSet.size === 0) {
+    return { nodes, links: [], issues: [], total, paths: uniquePrefixes };
+  }
+  const paths = [...pathSet];
+  const [linkRows, issueRows] = await Promise.all([
+    db.selectFrom("scan_links").selectAll().where("sourcePath", "in", paths).where("targetPath", "in", paths).execute(),
+    db.selectFrom("scan_issues").selectAll().where(
+      ({ exists, selectFrom }) => exists(
+        selectFrom(
+          sql2`json_each(scan_issues.node_ids_json)`.as("je")
+        ).select(sql2`1`.as("one")).where(sql2.ref("je.value"), "in", paths)
+      )
+    ).execute()
+  ]);
+  return {
+    nodes,
+    links: linkRows.map(rowToLink),
+    issues: issueRows.map(rowToIssue),
+    total,
+    paths: uniquePrefixes
+  };
+}
+async function countBranchNodes(db, prefixes) {
+  const row = await applyBranchScope(
+    db.selectFrom("scan_nodes"),
+    prefixes
+  ).select(({ fn }) => fn.countAll().as("c")).executeTakeFirst();
+  return Number(row?.c ?? 0);
+}
+function applyBranchScope(query, prefixes) {
+  if (prefixes.length === 0) return query;
+  return query.where(
+    ({ eb, or }) => or(
+      prefixes.map(
+        (prefix) => (
+          // Per-prefix subtree predicate. `prefix || '/%'`: the `/%` lives
+          // in the template, `prefix` binds separately, so no user input is
+          // interpolated into the SQL. The two clauses are ORed so the
+          // prefix matches the folder node itself plus every descendant.
+          eb.or([
+            eb("path", "=", prefix),
+            eb("path", "like", sql2`${prefix} || '/%'`)
+          ])
+        )
+      )
+    )
+  );
+}
 function rowToNode(row) {
   const bytes = {
     frontmatter: row.bytesFrontmatter,
@@ -7702,7 +7857,7 @@ function parseJsonArray(s) {
 }
 
 // kernel/adapters/sqlite/scan-persistence.ts
-import { sql as sql2 } from "kysely";
+import { sql as sql3 } from "kysely";
 
 // kernel/adapters/sqlite/contributions.ts
 async function replaceAllScanContributions(trx, contributions, livePaths = /* @__PURE__ */ new Set(), registeredKeys = /* @__PURE__ */ new Set(), freshlyRunTuples = /* @__PURE__ */ new Set()) {
@@ -7767,9 +7922,9 @@ async function sweepPerTupleContributions(trx, contributions, freshlyRunTuples)
   const bufferKeys = buildContributionsBufferKeys(contributions);
   const tuplesByPluginExt = groupFreshlyRunTuplesByPluginExt(freshlyRunTuples);
   for (const [pe, nodes] of tuplesByPluginExt) {
-    const sep8 = pe.indexOf("\0");
-    if (sep8 < 0) continue;
-    await deleteStaleTupleRows(trx, pe.slice(0, sep8), pe.slice(sep8 + 1), [...nodes], bufferKeys);
+    const sep9 = pe.indexOf("\0");
+    if (sep9 < 0) continue;
+    await deleteStaleTupleRows(trx, pe.slice(0, sep9), pe.slice(sep9 + 1), [...nodes], bufferKeys);
   }
 }
 function buildContributionsBufferKeys(contributions) {
@@ -7909,9 +8064,9 @@ function schemaFingerprint(files) {
   const migrations = files ?? discoverMigrations();
   const hash = createHash("sha256");
   for (const m of migrations) {
-    const sql4 = existsSync10(m.filePath) ? readFileSync10(m.filePath, "utf8") : "";
-    hash.update(`${m.version}\0${m.description}\0${Buffer.byteLength(sql4)}\0`);
-    hash.update(sql4);
+    const sql5 = existsSync10(m.filePath) ? readFileSync10(m.filePath, "utf8") : "";
+    hash.update(`${m.version}\0${m.description}\0${Buffer.byteLength(sql5)}\0`);
+    hash.update(sql5);
   }
   const digest = hash.digest("hex");
   if (files === void 0) memoized = digest;
@@ -8017,7 +8172,7 @@ async function persistScanResult(db, result, inputs = {}) {
     await upsertEnrichmentLayer(trx, result, renameOps, enrichments);
     await flagStaleProbabilisticEnrichments(trx, result, enrichments);
   });
-  await sql2`PRAGMA wal_checkpoint(TRUNCATE)`.execute(db);
+  await sql3`PRAGMA wal_checkpoint(TRUNCATE)`.execute(db);
   return { renames };
 }
 function resolvePersistInputs(inputs) {
@@ -8072,36 +8227,36 @@ function collectKnownOrphanPaths(issues) {
   }
   return out;
 }
+var MAX_SQL_VARS = 2e4;
+async function chunkedInsert(trx, table, rows) {
+  if (rows.length === 0) return;
+  const columns = Object.keys(rows[0]).length || 1;
+  const batchSize = Math.max(1, Math.floor(MAX_SQL_VARS / columns));
+  for (let start = 0; start < rows.length; start += batchSize) {
+    await trx.insertInto(table).values(rows.slice(start, start + batchSize)).execute();
+  }
+}
 async function replaceAllScanZone(trx, result, scannedAt, extractorRuns) {
   await trx.deleteFrom("scan_issues").execute();
   await trx.deleteFrom("scan_links").execute();
   await trx.deleteFrom("scan_nodes").execute();
   await trx.deleteFrom("scan_meta").execute();
   await trx.deleteFrom("scan_extractor_runs").execute();
-  if (result.nodes.length > 0) {
-    await trx.insertInto("scan_nodes").values(result.nodes.map((n) => nodeToRow(n, scannedAt))).execute();
-  }
-  if (result.links.length > 0) {
-    await trx.insertInto("scan_links").values(result.links.map(linkToRow)).execute();
-  }
-  if (result.issues.length > 0) {
-    await trx.insertInto("scan_issues").values(result.issues.map(issueToRow)).execute();
-  }
+  await chunkedInsert(trx, "scan_nodes", result.nodes.map((n) => nodeToRow(n, scannedAt)));
+  await chunkedInsert(trx, "scan_links", result.links.map(linkToRow));
+  await chunkedInsert(trx, "scan_issues", result.issues.map(issueToRow));
   await trx.insertInto("scan_meta").values(metaToRow(result)).execute();
-  if (extractorRuns.length > 0) {
-    await trx.insertInto("scan_extractor_runs").values(extractorRuns.map(extractorRunToRow)).execute();
-  }
+  await chunkedInsert(trx, "scan_extractor_runs", extractorRuns.map(extractorRunToRow));
 }
 async function upsertEnrichmentLayer(trx, result, renameOps, enrichments) {
   const enrichmentLivePaths = new Set(result.nodes.map((n) => n.path));
   for (const op of renameOps) {
     await trx.updateTable("node_enrichments").set({ nodePath: op.to }).where("nodePath", "=", op.from).execute();
   }
-  if (enrichmentLivePaths.size > 0) {
-    const liveList = [...enrichmentLivePaths];
-    await trx.deleteFrom("node_enrichments").where("nodePath", "not in", liveList).execute();
-  } else {
-    await trx.deleteFrom("node_enrichments").execute();
+  const existingEnrichmentPaths = await trx.selectFrom("node_enrichments").select("nodePath").distinct().execute();
+  const deadEnrichmentPaths = existingEnrichmentPaths.map((r) => r.nodePath).filter((p) => !enrichmentLivePaths.has(p));
+  for (let start = 0; start < deadEnrichmentPaths.length; start += MAX_SQL_VARS) {
+    await trx.deleteFrom("node_enrichments").where("nodePath", "in", deadEnrichmentPaths.slice(start, start + MAX_SQL_VARS)).execute();
   }
   for (const enrichment of enrichments) {
     const row = enrichmentToRow(enrichment);
@@ -8286,8 +8441,9 @@ function projectOversizedColumns(result) {
 }
 function projectNodeLimitColumns(result) {
   return {
-    recommendedNodeLimit: result.recommendedNodeLimit ?? 256,
-    overrideMaxNodes: result.overrideMaxNodes ?? null
+    scanCeiling: result.scanCeiling ?? 5e4,
+    scanTruncated: result.scanTruncated ? 1 : 0,
+    maxRenderNodes: result.maxRenderNodes ?? 256
   };
 }
 function extractorRunToRow(record) {
@@ -8462,11 +8618,16 @@ var SqliteStorageAdapter = class {
     this.scans = {
       persist: (result, opts) => persistScansThroughNonTx(this.db, result, opts),
       load: () => loadScanResult(this.db),
+      loadMeta: async () => loadScanMeta(this.db, await countRows(this.db)),
       loadExtractorRuns: () => loadExtractorRuns(this.db),
       loadNodeEnrichments: () => loadNodeEnrichments(this.db),
       countRows: () => countRows(this.db),
       findNodes: (filter) => findNodes(this.db, filter),
-      findNode: (path2) => findNode(this.db, path2)
+      findNode: (path2) => findNode(this.db, path2),
+      listLiteNodes: () => loadLiteNodes(this.db),
+      issueCountsByPath: () => loadIssueCountsByPath(this.db),
+      effectiveMaxRenderNodes: () => loadEffectiveMaxRenderNodes(this.db),
+      loadBranch: (prefixes, limit) => loadBranch(this.db, prefixes, limit)
     };
     this.contributions = {
       listForNode: (nodePath) => loadContributionsForNode(this.db, nodePath),
@@ -8601,8 +8762,8 @@ async function findNodes(db, filter) {
     query = query.where(
       ({ exists, selectFrom, ref }) => exists(
         selectFrom(
-          sql3`json_each(scan_issues.node_ids_json)`.as("je")
-        ).innerJoin("scan_issues", (j) => j.onTrue()).select(sql3`1`.as("one")).whereRef(sql3.ref("je.value"), "=", ref("scan_nodes.path"))
+          sql4`json_each(scan_issues.node_ids_json)`.as("je")
+        ).innerJoin("scan_issues", (j) => j.onTrue()).select(sql4`1`.as("one")).whereRef(sql4.ref("je.value"), "=", ref("scan_nodes.path"))
       )
     );
   }
@@ -8674,8 +8835,8 @@ function applyIssueFilters(query, filter) {
     q = q.where(
       ({ exists, selectFrom }) => exists(
         selectFrom(
-          sql3`json_each(scan_issues.node_ids_json)`.as("je")
-        ).select(sql3`1`.as("one")).where(sql3.ref("je.value"), "=", target)
+          sql4`json_each(scan_issues.node_ids_json)`.as("je")
+        ).select(sql4`1`.as("one")).where(sql4.ref("je.value"), "=", target)
       )
     );
   }
@@ -8686,14 +8847,14 @@ function applyIssueFilters(query, filter) {
 }
 function applyNodePathsFilter(query, nodePaths) {
   if (nodePaths.length === 0) {
-    return query.where(sql3`0`, "=", 1);
+    return query.where(sql4`0`, "=", 1);
   }
   const targets = [...nodePaths];
   return query.where(
     ({ exists, selectFrom }) => exists(
       selectFrom(
-        sql3`json_each(scan_issues.node_ids_json)`.as("je")
-      ).select(sql3`1`.as("one")).where(sql3.ref("je.value"), "in", targets)
+        sql4`json_each(scan_issues.node_ids_json)`.as("je")
+      ).select(sql4`1`.as("one")).where(sql4.ref("je.value"), "in", targets)
     )
   );
 }
@@ -10632,7 +10793,7 @@ async function buildEnabledResolver(ctx) {
 
 // kernel/scan/walk-content.ts
 import { readFile, readdir, lstat } from "fs/promises";
-import { join as join9, relative as relative2, sep as sep3 } from "path";
+import { isAbsolute as isAbsolute4, join as join9, relative as relative2, resolve as resolve18, sep as sep3 } from "path";
 
 // kernel/scan/ignore.ts
 import { existsSync as existsSync14, readFileSync as readFileSync14 } from "fs";
@@ -10812,32 +10973,115 @@ async function* walkContent(roots, options) {
   const filter = options.ignoreFilter ?? buildIgnoreFilter();
   const extensions = options.extensions;
   const sizeLimit = buildSizeLimit(options);
+  if (options.scopedPaths !== void 0) {
+    yield* walkScoped(roots, options.scopedPaths, extensions, sizeLimit, parser);
+    return;
+  }
   for (const root of roots) {
     for await (const entry of walkRoot(root, root, filter, extensions, sizeLimit)) {
       const relPath = relative2(root, entry.full).split(sep3).join("/");
-      let raw;
-      try {
-        raw = await readFile(entry.full, "utf8");
-      } catch {
-        continue;
-      }
-      const parsed = parser.parse(raw, relPath);
-      yield {
-        path: relPath,
-        body: parsed.body,
-        frontmatterRaw: parsed.frontmatterRaw,
-        frontmatter: parsed.frontmatter,
-        // File mtime from the TOCTOU `lstat` (zero extra syscalls).
-        // Threaded onto the persisted `Node` as `modifiedAtMs`.
-        modifiedAtMs: entry.modifiedAtMs,
-        // Audit L1: forward parser diagnostics (e.g. malformed YAML)
-        // through the IRawNode surface so the orchestrator can
-        // convert them into warn-level kernel `Issue` rows. Omitted
-        // when the parser reported no issues (happy path).
-        ...parsed.issues && parsed.issues.length > 0 ? { parseIssues: parsed.issues } : {}
-      };
+      const rec = await traversedEntryToNode(entry, relPath, options.priorMtimes, parser);
+      if (rec !== null) yield rec;
+    }
+  }
+}
+async function traversedEntryToNode(entry, relPath, priorMtimes, parser) {
+  const priorMtime = priorMtimes?.get(relPath);
+  if (priorMtime !== void 0 && priorMtime === entry.modifiedAtMs) {
+    return buildUnchangedRecord(entry.full, relPath, entry.modifiedAtMs, parser);
+  }
+  const parsed = await readAndParse(entry.full, relPath, parser);
+  if (parsed === null) return null;
+  return {
+    path: relPath,
+    body: parsed.body,
+    frontmatterRaw: parsed.frontmatterRaw,
+    frontmatter: parsed.frontmatter,
+    // File mtime from the TOCTOU `lstat` (zero extra syscalls).
+    // Threaded onto the persisted `Node` as `modifiedAtMs`.
+    modifiedAtMs: entry.modifiedAtMs,
+    // Audit L1: forward parser diagnostics (e.g. malformed YAML)
+    // through the IRawNode surface so the orchestrator can
+    // convert them into warn-level kernel `Issue` rows. Omitted
+    // when the parser reported no issues (happy path).
+    ...parsed.parseIssues ? { parseIssues: parsed.parseIssues } : {}
+  };
+}
+function buildUnchangedRecord(full, relPath, modifiedAtMs, parser) {
+  return {
+    path: relPath,
+    body: "",
+    frontmatterRaw: "",
+    frontmatter: {},
+    modifiedAtMs,
+    unchanged: true,
+    reread: async () => {
+      const re = await readAndParse(full, relPath, parser);
+      return re ?? { body: "", frontmatterRaw: "", frontmatter: {} };
     }
+  };
+}
+async function* walkScoped(roots, scopedPaths, extensions, sizeLimit, parser) {
+  const absRoots = roots.map((r) => isAbsolute4(r) ? r : resolve18(r));
+  for (const scoped of scopedPaths) {
+    const rec = await scopedPathToNode(scoped, absRoots, extensions, sizeLimit, parser);
+    if (rec !== null) yield rec;
+  }
+}
+async function scopedPathToNode(scoped, absRoots, extensions, sizeLimit, parser) {
+  const full = isAbsolute4(scoped) ? scoped : resolve18(scoped);
+  const relPath = relativeFromRoots(full, absRoots);
+  if (relPath === null) return null;
+  if (!hasMatchingExtension(full, extensions)) return null;
+  const s = await statRegularFile(full, relPath, sizeLimit);
+  if (s === null) return null;
+  const parsed = await readAndParse(full, relPath, parser);
+  if (parsed === null) return null;
+  return {
+    path: relPath,
+    body: parsed.body,
+    frontmatterRaw: parsed.frontmatterRaw,
+    frontmatter: parsed.frontmatter,
+    modifiedAtMs: Math.round(s.mtimeMs),
+    ...parsed.parseIssues ? { parseIssues: parsed.parseIssues } : {}
+  };
+}
+async function statRegularFile(full, relPath, sizeLimit) {
+  let s;
+  try {
+    s = await lstat(full);
+  } catch {
+    return null;
+  }
+  if (!s.isFile()) return null;
+  if (sizeLimit.maxFileSizeBytes !== void 0 && s.size > sizeLimit.maxFileSizeBytes) {
+    sizeLimit.onOversizedFile?.({ path: relPath, bytes: s.size });
+    return null;
+  }
+  return s;
+}
+function relativeFromRoots(full, absRoots) {
+  for (const root of absRoots) {
+    const rel = relative2(root, full);
+    if (rel === "" || rel.startsWith("..") || isAbsolute4(rel)) continue;
+    return rel.split(sep3).join("/");
+  }
+  return null;
+}
+async function readAndParse(full, relPath, parser) {
+  let raw;
+  try {
+    raw = await readFile(full, "utf8");
+  } catch {
+    return null;
   }
+  const parsed = parser.parse(raw, relPath);
+  return {
+    body: parsed.body,
+    frontmatterRaw: parsed.frontmatterRaw,
+    frontmatter: parsed.frontmatter,
+    ...parsed.issues && parsed.issues.length > 0 ? { parseIssues: parsed.issues } : {}
+  };
 }
 function buildSizeLimit(options) {
   const sizeLimit = {};
@@ -10894,18 +11138,24 @@ function resolveProviderWalk(provider) {
     return walk3;
   }
   const read = provider.read ?? DEFAULT_READ_CONFIG;
-  return (roots, options) => {
-    const walkOptions = {
-      extensions: read.extensions,
-      parser: read.parser
-    };
-    if (options?.ignoreFilter) walkOptions.ignoreFilter = options.ignoreFilter;
-    if (options?.maxFileSizeBytes !== void 0) {
-      walkOptions.maxFileSizeBytes = options.maxFileSizeBytes;
-    }
-    if (options?.onOversizedFile) walkOptions.onOversizedFile = options.onOversizedFile;
-    return walkContent(roots, walkOptions);
+  return (roots, options) => walkContent(roots, buildWalkContentOptions(read, options));
+}
+function buildWalkContentOptions(read, options) {
+  const walkOptions = {
+    extensions: read.extensions,
+    parser: read.parser
   };
+  if (options) copyOptionalWalkOptions(walkOptions, options);
+  return walkOptions;
+}
+function copyOptionalWalkOptions(walkOptions, options) {
+  if (options.ignoreFilter) walkOptions.ignoreFilter = options.ignoreFilter;
+  if (options.maxFileSizeBytes !== void 0) {
+    walkOptions.maxFileSizeBytes = options.maxFileSizeBytes;
+  }
+  if (options.onOversizedFile) walkOptions.onOversizedFile = options.onOversizedFile;
+  if (options.priorMtimes) walkOptions.priorMtimes = options.priorMtimes;
+  if (options.scopedPaths) walkOptions.scopedPaths = options.scopedPaths;
 }
 
 // kernel/extensions/collect-view-contributions.ts
@@ -10995,7 +11245,7 @@ function isExtensionInstance(v) {
 }
 
 // core/runtime/plugin-runtime/warnings.ts
-import { resolve as resolve18 } from "path";
+import { resolve as resolve19 } from "path";
 
 // kernel/util/text.ts
 function truncateHead(s, max) {
@@ -11045,7 +11295,7 @@ function resolveRuntimeContext(opts) {
   return opts.runtimeContext ?? defaultRuntimeContext();
 }
 function resolveSearchPaths(opts, ctx) {
-  if (opts.pluginDir) return [resolve18(opts.pluginDir)];
+  if (opts.pluginDir) return [resolve19(opts.pluginDir)];
   return [defaultProjectPluginsDir(ctx)];
 }
 
@@ -11596,11 +11846,11 @@ function resolveActiveProvider(cwd, providers = []) {
 }
 
 // cli/util/path-display.ts
-import { isAbsolute as isAbsolute4, relative as pathRelative } from "path";
+import { isAbsolute as isAbsolute5, relative as pathRelative } from "path";
 function relativeIfBelow(path, cwd) {
-  if (!isAbsolute4(path)) return path;
+  if (!isAbsolute5(path)) return path;
   const rel = pathRelative(cwd, path);
-  if (rel === "" || rel.startsWith("..") || isAbsolute4(rel)) return path;
+  if (rel === "" || rel.startsWith("..") || isAbsolute5(rel)) return path;
   return rel;
 }
 
@@ -12324,7 +12574,7 @@ var CONFIG_COMMANDS = [
 
 // cli/commands/conformance.ts
 import { existsSync as existsSync19, readFileSync as readFileSync16 } from "fs";
-import { dirname as dirname12, resolve as resolve21 } from "path";
+import { dirname as dirname12, resolve as resolve22 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command5, Option as Option5 } from "clipanion";
 
@@ -12332,7 +12582,7 @@ import { Command as Command5, Option as Option5 } from "clipanion";
 import { spawnSync as spawnSync2 } from "child_process";
 import { cpSync, existsSync as existsSync17, mkdtempSync, readdirSync as readdirSync5, readFileSync as readFileSync15, rmSync, statSync as statSync3 } from "fs";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute5, join as join11, relative as relative3, resolve as resolve19 } from "path";
+import { isAbsolute as isAbsolute6, join as join11, relative as relative3, resolve as resolve20 } from "path";
 
 // conformance/i18n/runner.texts.ts
 var CONFORMANCE_RUNNER_TEXTS = {
@@ -12494,14 +12744,14 @@ function replaceFixture(scope, fixturesRoot, fixture) {
   cpSync(src, scope, { recursive: true });
 }
 function assertContained2(root, rel, label) {
-  if (isAbsolute5(rel)) {
+  if (isAbsolute6(rel)) {
     throw new Error(
       tx(CONFORMANCE_RUNNER_TEXTS.pathMustBeRelative, { label, path: rel, anchor: root })
     );
   }
-  const abs = resolve19(root, rel);
+  const abs = resolve20(root, rel);
   const r = relative3(root, abs);
-  if (r.startsWith("..") || isAbsolute5(r)) {
+  if (r.startsWith("..") || isAbsolute6(r)) {
     throw new Error(
       tx(CONFORMANCE_RUNNER_TEXTS.pathEscapesAnchor, { label, path: rel, anchor: root })
     );
@@ -12526,7 +12776,7 @@ function evaluateAssertion(a, ctx) {
       } catch (err) {
         return { ok: false, type: a.type, reason: formatErrorMessage(err) };
       }
-      const abs = resolve19(ctx.scope, a.path);
+      const abs = resolve20(ctx.scope, a.path);
       return existsSync17(abs) ? { ok: true, type: a.type } : {
         ok: false,
         type: a.type,
@@ -12541,7 +12791,7 @@ function evaluateAssertion(a, ctx) {
         return { ok: false, type: a.type, reason: formatErrorMessage(err) };
       }
       const fixturePath = join11(ctx.fixturesRoot, a.fixture);
-      const targetPath = resolve19(ctx.scope, a.path);
+      const targetPath = resolve20(ctx.scope, a.path);
       if (!existsSync17(targetPath)) {
         return {
           ok: false,
@@ -12724,7 +12974,7 @@ var CONFORMANCE_TEXTS = {
 
 // cli/util/conformance-scopes.ts
 import { existsSync as existsSync18, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
-import { dirname as dirname11, resolve as resolve20 } from "path";
+import { dirname as dirname11, resolve as resolve21 } from "path";
 import { createRequire as createRequire6 } from "module";
 import { fileURLToPath as fileURLToPath3 } from "url";
 function resolveSpecRoot4() {
@@ -12742,7 +12992,7 @@ function resolveCliWorkspaceRoot() {
   const here = dirname11(fileURLToPath3(import.meta.url));
   let cursor = here;
   for (let depth = 0; depth < 6; depth += 1) {
-    const candidate = resolve20(cursor, "plugins");
+    const candidate = resolve21(cursor, "plugins");
     if (existsSync18(candidate) && statSync4(candidate).isDirectory()) {
       return cursor;
     }
@@ -12762,12 +13012,12 @@ function collectProviderScopes(specRoot) {
   } catch {
     return out;
   }
-  const pluginsRoot = resolve20(workspaceRoot, "plugins");
+  const pluginsRoot = resolve21(workspaceRoot, "plugins");
   if (!existsSync18(pluginsRoot)) return out;
   for (const pluginEntry of readdirSync6(pluginsRoot)) {
-    const pluginDir = resolve20(pluginsRoot, pluginEntry);
+    const pluginDir = resolve21(pluginsRoot, pluginEntry);
     if (!isDir(pluginDir)) continue;
-    const providersRoot = resolve20(pluginDir, "providers");
+    const providersRoot = resolve21(pluginDir, "providers");
     if (!isDir(providersRoot)) continue;
     collectPluginProviderScopes(providersRoot, specRoot, out);
   }
@@ -12782,12 +13032,12 @@ function isDir(path) {
 }
 function collectPluginProviderScopes(providersRoot, specRoot, out) {
   for (const entry of readdirSync6(providersRoot)) {
-    const providerDir = resolve20(providersRoot, entry);
+    const providerDir = resolve21(providersRoot, entry);
     if (!isDir(providerDir)) continue;
-    const conformanceDir = resolve20(providerDir, "conformance");
+    const conformanceDir = resolve21(providerDir, "conformance");
     if (!existsSync18(conformanceDir)) continue;
-    const casesDir = resolve20(conformanceDir, "cases");
-    const fixturesDir = resolve20(conformanceDir, "fixtures");
+    const casesDir = resolve21(conformanceDir, "cases");
+    const fixturesDir = resolve21(conformanceDir, "fixtures");
     if (!existsSync18(casesDir) || !existsSync18(fixturesDir)) continue;
     out.push({
       id: `provider:${entry}`,
@@ -12804,8 +13054,8 @@ function specScope(specRoot) {
     id: "spec",
     kind: "spec",
     label: "spec",
-    casesDir: resolve20(specRoot, "conformance", "cases"),
-    fixturesDir: resolve20(specRoot, "conformance", "fixtures"),
+    casesDir: resolve21(specRoot, "conformance", "cases"),
+    fixturesDir: resolve21(specRoot, "conformance", "fixtures"),
     specRoot
   };
 }
@@ -12827,7 +13077,7 @@ function selectConformanceScopes(scope) {
 }
 function listCaseFiles(scope) {
   if (!existsSync18(scope.casesDir)) return [];
-  return readdirSync6(scope.casesDir).filter((entry) => entry.endsWith(".json")).sort().map((entry) => resolve20(scope.casesDir, entry));
+  return readdirSync6(scope.casesDir).filter((entry) => entry.endsWith(".json")).sort().map((entry) => resolve21(scope.casesDir, entry));
 }
 
 // cli/commands/conformance.ts
@@ -12844,13 +13094,13 @@ function resolveBinary() {
   const here = dirname12(fileURLToPath4(import.meta.url));
   let cursor = here;
   for (let depth = 0; depth < 6; depth += 1) {
-    const candidate = resolve21(cursor, "bin", "sm.js");
+    const candidate = resolve22(cursor, "bin", "sm.js");
     if (existsSync19(candidate)) return candidate;
     const parent = dirname12(cursor);
     if (parent === cursor) break;
     cursor = parent;
   }
-  return resolve21(here, "..", "..", "bin", "sm.js");
+  return resolve22(here, "..", "..", "bin", "sm.js");
 }
 var ConformanceRunCommand = class extends SmCommand {
   static paths = [["conformance", "run"]];
@@ -13103,7 +13353,7 @@ function writeStreamSnippet(stream, header, text) {
 var CONFORMANCE_COMMANDS = [ConformanceRunCommand];
 
 // cli/commands/db/backup.ts
-import { dirname as dirname13, join as join12, resolve as resolve22 } from "path";
+import { dirname as dirname13, join as join12, resolve as resolve23 } from "path";
 import { Command as Command6, Option as Option6 } from "clipanion";
 
 // cli/i18n/db.texts.ts
@@ -13216,7 +13466,7 @@ var DbBackupCommand = class extends SmCommand {
     const exit = requireDbOrExit(path, this.context.stderr);
     if (exit !== null) return exit;
     const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-    const outPath = this.out ? resolve22(this.out) : join12(dirname13(path), "backups", `${ts}.db`);
+    const outPath = this.out ? resolve23(this.out) : join12(dirname13(path), "backups", `${ts}.db`);
     await withSqlite({ databasePath: path, autoMigrate: false }, async (storage) => {
       storage.migrations.writeBackup(outPath);
     });
@@ -13233,7 +13483,7 @@ var DbBackupCommand = class extends SmCommand {
 
 // cli/commands/db/restore.ts
 import { chmod, copyFile, mkdir, rm } from "fs/promises";
-import { dirname as dirname14, resolve as resolve23 } from "path";
+import { dirname as dirname14, resolve as resolve24 } from "path";
 import { Command as Command7, Option as Option7 } from "clipanion";
 
 // cli/util/fs.ts
@@ -13283,7 +13533,7 @@ var DbRestoreCommand = class extends SmCommand {
   });
   async run() {
     const target = resolveDbPath({ db: this.db, ...defaultRuntimeContext() });
-    const sourcePath = resolve23(this.source);
+    const sourcePath = resolve24(this.source);
     const stderrAnsi = this.ansiFor("stderr");
     const sourceStat = await statOrNull(sourcePath);
     if (!sourceStat) {
@@ -13524,7 +13774,7 @@ var DbShellCommand = class extends SmCommand {
 
 // cli/commands/db/browser.ts
 import { spawn, spawnSync as spawnSync4 } from "child_process";
-import { resolve as resolve24 } from "path";
+import { resolve as resolve25 } from "path";
 import { Command as Command10, Option as Option9 } from "clipanion";
 var DbBrowserCommand = class extends SmCommand {
   static paths = [["db", "browser"]];
@@ -13557,7 +13807,7 @@ var DbBrowserCommand = class extends SmCommand {
   });
   positional = Option9.String({ required: false });
   async run() {
-    const path = this.positional ? resolve24(this.positional) : resolveDbPath({ db: this.db, ...defaultRuntimeContext() });
+    const path = this.positional ? resolve25(this.positional) : resolveDbPath({ db: this.db, ...defaultRuntimeContext() });
     if (!assertDbExists(path, this.context.stderr)) {
       this.printer.error(DB_TEXTS.browserRunScanFirstHint);
       return ExitCode.NotFound;
@@ -13647,8 +13897,8 @@ function listSchemaObjects(db, tables) {
     return db.prepare(`${baseQuery} ORDER BY rootpage`).all();
   }
   const placeholders = tables.map(() => "?").join(",");
-  const sql4 = `${baseQuery} AND (name IN (${placeholders}) OR tbl_name IN (${placeholders})) ORDER BY rootpage`;
-  return db.prepare(sql4).all(...tables, ...tables);
+  const sql5 = `${baseQuery} AND (name IN (${placeholders}) OR tbl_name IN (${placeholders})) ORDER BY rootpage`;
+  return db.prepare(sql5).all(...tables, ...tables);
 }
 function writeTableData(db, out, tableName) {
   const quoted = `"${tableName.replace(/"/g, '""')}"`;
@@ -14475,7 +14725,7 @@ var GraphCommand = class extends SmCommand {
 // cli/commands/help.ts
 import { readFileSync as readFileSync17 } from "fs";
 import { createRequire as createRequire7 } from "module";
-import { resolve as resolve25 } from "path";
+import { resolve as resolve26 } from "path";
 import { Command as Command15, Option as Option14 } from "clipanion";
 
 // cli/i18n/help.texts.ts
@@ -14789,7 +15039,7 @@ function resolveSpecVersion() {
   try {
     const req = createRequire7(import.meta.url);
     const indexPath = req.resolve("@skill-map/spec/index.json");
-    const pkgPath = resolve25(indexPath, "..", "package.json");
+    const pkgPath = resolve26(indexPath, "..", "package.json");
     const pkg = JSON.parse(readFileSync17(pkgPath, "utf8"));
     return pkg.version;
   } catch {
@@ -15097,7 +15347,7 @@ function registeredVerbPaths(cli2) {
 
 // cli/commands/hooks.ts
 import { chmod as chmod2, mkdir as mkdir3, readFile as readFile2, stat as stat2, writeFile } from "fs/promises";
-import { dirname as dirname16, resolve as resolve26 } from "path";
+import { dirname as dirname16, resolve as resolve27 } from "path";
 import { Command as Command16, Option as Option15 } from "clipanion";
 
 // cli/i18n/hooks.texts.ts
@@ -15200,8 +15450,8 @@ var HooksInstallCommand = class extends SmCommand {
       );
       return ExitCode.NotFound;
     }
-    const hooksDir = resolve26(repoRoot, ".git", "hooks");
-    const hookPath = resolve26(hooksDir, "pre-commit");
+    const hooksDir = resolve27(repoRoot, ".git", "hooks");
+    const hookPath = resolve27(hooksDir, "pre-commit");
     const existing = await pathExists(hookPath) ? await readFile2(hookPath, "utf8") : null;
     const planned2 = computePlannedHookContent(existing);
     if (planned2.kind === "already-installed") {
@@ -15259,7 +15509,7 @@ var HooksInstallCommand = class extends SmCommand {
 async function findGitRepoRoot(cwd) {
   let current = cwd;
   while (true) {
-    if (await pathExists(resolve26(current, ".git"))) return current;
+    if (await pathExists(resolve27(current, ".git"))) return current;
     const parent = dirname16(current);
     if (parent === current) return null;
     current = parent;
@@ -15270,8 +15520,8 @@ function computePlannedHookContent(existing) {
   if (existing.includes(SKILL_MAP_MARKER)) {
     return { kind: "already-installed", content: existing };
   }
-  const sep8 = existing.endsWith("\n") ? "" : "\n";
-  return { kind: "chained", content: existing + sep8 + "\n" + SKILL_MAP_BLOCK };
+  const sep9 = existing.endsWith("\n") ? "" : "\n";
+  return { kind: "chained", content: existing + sep9 + "\n" + SKILL_MAP_BLOCK };
 }
 async function ensureExecutableBit(path) {
   const mode = (await stat2(path)).mode;
@@ -15286,7 +15536,7 @@ import { Command as Command17, Option as Option16 } from "clipanion";
 
 // kernel/orchestrator/index.ts
 import { existsSync as existsSync23, statSync as statSync6 } from "fs";
-import { isAbsolute as isAbsolute7, resolve as resolve28 } from "path";
+import { isAbsolute as isAbsolute9, resolve as resolve30 } from "path";
 import { Tiktoken as Tiktoken2 } from "js-tiktoken/lite";
 
 // kernel/i18n/orchestrator.texts.ts
@@ -16232,7 +16482,7 @@ function collectBrokenLinks(links, nodes, ctx) {
   return broken;
 }
 function applyResolution(link, indexes, ctx) {
-  const resolution = resolve27(link, indexes, ctx);
+  const resolution = resolve28(link, indexes, ctx);
   if (resolution === "none") return;
   link.resolvedTarget = resolution;
 }
@@ -16247,7 +16497,7 @@ function buildIndexes(nodes, ctx) {
   }
   return { byPath: byPath3, byName, nodeByPath };
 }
-function resolve27(link, indexes, ctx) {
+function resolve28(link, indexes, ctx) {
   if (indexes.byPath.has(link.target)) return link.target;
   return resolveByName(link, indexes, ctx);
 }
@@ -16635,6 +16885,9 @@ function detectRenamesAndOrphans(prior, current, issues, silenced) {
   return ops;
 }
 
+// kernel/orchestrator/walk.ts
+import { isAbsolute as isAbsolute8, resolve as resolve29 } from "path";
+
 // kernel/sidecar/drift.ts
 function computeDriftStatus(args2) {
   const bodyDrift = args2.storedBodyHash !== args2.liveBodyHash;
@@ -16689,7 +16942,7 @@ function safeIsFile(path) {
 // kernel/orchestrator/node-build.ts
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync22 } from "fs";
-import { isAbsolute as isAbsolute6, resolve as resolvePath } from "path";
+import { isAbsolute as isAbsolute7, resolve as resolvePath } from "path";
 import "js-tiktoken/lite";
 import yaml4 from "js-yaml";
 
@@ -16852,7 +17105,7 @@ function resolveSidecarOverlay(relativePath2, nodePathForIssue, roots, liveBodyH
   };
 }
 function resolveAbsoluteMdPath(relativePath2, roots) {
-  if (isAbsolute6(relativePath2)) {
+  if (isAbsolute7(relativePath2)) {
     return existsSync22(relativePath2) ? relativePath2 : null;
   }
   for (const root of roots) {
@@ -16925,34 +17178,46 @@ async function walkAndExtract(opts) {
     oversizedSeen.add(info.path);
     oversizedFiles.push(info);
   };
+  const priorMtimes = buildPriorMtimes(opts);
   const walkOptions = {
     ...opts.ignoreFilter ? { ignoreFilter: opts.ignoreFilter } : {},
     onOversizedFile,
-    ...opts.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: opts.maxFileSizeBytes } : {}
+    ...opts.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: opts.maxFileSizeBytes } : {},
+    ...priorMtimes ? { priorMtimes } : {}
   };
-  let filesWalked = 0;
+  let filesWalked;
   let index = 0;
-  const effectiveMaxNodes = opts.overrideMaxNodes ?? opts.recommendedNodeLimit;
+  const { effectiveScanCeiling, effectiveMaxRenderNodes } = resolveEffectiveCaps(opts);
   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;
-  });
+  const activeProviders = opts.providers.filter(
+    (provider) => providerParticipates(provider, opts.activeProvider)
+  );
   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;
-      if (accum.nodes.length >= effectiveMaxNodes) {
-        capReached = true;
-        break outer;
-      }
-      await advance(raw, provider);
-    }
+  if (opts.incrementalChangedPaths !== void 0) {
+    filesWalked = await walkIncremental({
+      changedPaths: opts.incrementalChangedPaths,
+      activeProviders,
+      walkOptions,
+      wctx,
+      accum,
+      claimedPaths,
+      advance
+    });
+  } else {
+    const full = await walkFullTraversal({
+      activeProviders,
+      roots: opts.roots,
+      walkOptions,
+      accum,
+      claimedPaths,
+      effectiveScanCeiling,
+      advance
+    });
+    filesWalked = full.filesWalked;
+    capReached = full.capReached;
   }
   const orphanSidecars = discoverOrphanSidecars(opts.roots);
   return {
@@ -16963,9 +17228,9 @@ async function walkAndExtract(opts) {
     frontmatterIssues: accum.frontmatterIssues,
     filesWalked,
     oversizedFiles,
-    recommendedNodeLimit: opts.recommendedNodeLimit,
-    overrideMaxNodes: opts.overrideMaxNodes,
-    capReached,
+    scanCeiling: effectiveScanCeiling,
+    scanTruncated: capReached,
+    maxRenderNodes: effectiveMaxRenderNodes,
     enrichments: [...accum.enrichmentBuffer.values()],
     extractorRuns: accum.extractorRuns,
     contributions: accum.contributionsBuffer,
@@ -16976,6 +17241,119 @@ async function walkAndExtract(opts) {
     signals: accum.signals
   };
 }
+async function walkFullTraversal(args2) {
+  let filesWalked = 0;
+  let capReached = false;
+  outer: for (const provider of args2.activeProviders) {
+    for await (const raw of resolveProviderWalk(provider)(args2.roots, args2.walkOptions)) {
+      filesWalked += 1;
+      if (args2.claimedPaths.has(raw.path)) continue;
+      if (args2.accum.nodes.length >= args2.effectiveScanCeiling) {
+        capReached = true;
+        break outer;
+      }
+      await args2.advance(raw, provider);
+    }
+  }
+  return { filesWalked, capReached };
+}
+async function walkIncremental(args2) {
+  const changed = expandSidecarPaths(args2.changedPaths.changed, args2.wctx.priorNodesByPath);
+  const removed = expandSidecarPaths(args2.changedPaths.removed, args2.wctx.priorNodesByPath);
+  let filesWalked = 0;
+  const scopedAbs = [...changed].map((rel) => toAbsolute(rel, args2.wctx.opts.roots));
+  if (scopedAbs.length > 0) {
+    const scopedWalkOptions = { ...args2.walkOptions, scopedPaths: scopedAbs };
+    for (const provider of args2.activeProviders) {
+      for await (const raw of resolveProviderWalk(provider)(args2.wctx.opts.roots, scopedWalkOptions)) {
+        filesWalked += 1;
+        if (args2.claimedPaths.has(raw.path)) continue;
+        await args2.advance(raw, provider);
+      }
+    }
+  }
+  filesWalked += await injectUnchangedPriorNodes(args2, changed, removed);
+  return filesWalked;
+}
+async function injectUnchangedPriorNodes(args2, changed, removed) {
+  const providerById = new Map(args2.activeProviders.map((p) => [p.id, p]));
+  const universalFallback = args2.activeProviders.find((p) => !p.gatedByActiveLens) ?? args2.activeProviders[0];
+  let injected = 0;
+  for (const priorNode of args2.wctx.opts.prior?.nodes ?? []) {
+    if (!shouldInjectPriorNode(priorNode, changed, removed, args2.claimedPaths)) continue;
+    const provider = providerById.get(priorNode.provider) ?? universalFallback;
+    if (!provider) continue;
+    const raw = buildUnchangedRawNode(priorNode, provider, args2.wctx.opts.roots);
+    await args2.advance(raw, provider);
+    injected += 1;
+  }
+  return injected;
+}
+function shouldInjectPriorNode(priorNode, changed, removed, claimedPaths) {
+  const path = priorNode.path;
+  if (changed.has(path) || removed.has(path) || claimedPaths.has(path)) return false;
+  if (priorNode.virtual === true) return false;
+  return true;
+}
+function buildUnchangedRawNode(priorNode, provider, roots) {
+  const path = priorNode.path;
+  return {
+    path,
+    body: "",
+    frontmatterRaw: "",
+    frontmatter: {},
+    ...typeof priorNode.modifiedAtMs === "number" ? { modifiedAtMs: priorNode.modifiedAtMs } : {},
+    unchanged: true,
+    reread: async () => {
+      const abs = toAbsolute(path, roots);
+      for await (const re of resolveProviderWalk(provider)(roots, { scopedPaths: [abs] })) {
+        return {
+          body: re.body,
+          frontmatterRaw: re.frontmatterRaw,
+          frontmatter: re.frontmatter,
+          ...re.parseIssues ? { parseIssues: re.parseIssues } : {}
+        };
+      }
+      return { body: "", frontmatterRaw: "", frontmatter: {} };
+    }
+  };
+}
+function expandSidecarPaths(paths, priorNodesByPath) {
+  const out = /* @__PURE__ */ new Set();
+  for (const path of paths) {
+    if (path.endsWith(".sm")) {
+      const mdPath = `${path.slice(0, -".sm".length)}.md`;
+      if (priorNodesByPath.has(mdPath)) out.add(mdPath);
+      continue;
+    }
+    out.add(path);
+  }
+  return out;
+}
+function toAbsolute(relPath, roots) {
+  const root = roots[0] ?? ".";
+  const absRoot = isAbsolute8(root) ? root : resolve29(root);
+  return resolve29(absRoot, relPath);
+}
+function resolveEffectiveCaps(opts) {
+  return {
+    effectiveScanCeiling: opts.overrideScanCeiling ?? opts.scanCeiling,
+    effectiveMaxRenderNodes: opts.overrideMaxRenderNodes ?? opts.maxRenderNodes
+  };
+}
+function buildPriorMtimes(opts) {
+  if (!opts.enableCache || opts.prior === null || opts.tokenizerChanged) return void 0;
+  const map = /* @__PURE__ */ new Map();
+  for (const node of opts.prior.nodes) {
+    if (typeof node.modifiedAtMs === "number") map.set(node.path, node.modifiedAtMs);
+  }
+  return map.size > 0 ? map : void 0;
+}
+function providerParticipates(provider, activeProvider) {
+  if (!provider.gatedByActiveLens) return true;
+  if (activeProvider === null) return true;
+  return provider.id === activeProvider;
+}
 function createWalkAccumulators() {
   return {
     nodes: [],
@@ -17004,61 +17382,106 @@ function buildWalkContext(opts) {
   return { opts, priorNodesByPath, priorLinksByOriginating, priorFrontmatterIssuesByNode, shortIdToQualified };
 }
 async function processRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex) {
-  const bodyHash = sha256(raw.body);
-  const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
   if (Array.isArray(provider.roots) && provider.roots.length > 0) {
     if (!matchesAnyRoot(raw.path, provider.roots)) return false;
   }
+  if (raw.unchanged === true) {
+    const handled = await handleUnchangedRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex);
+    if (handled) return true;
+  }
+  const bodyHash = sha256(raw.body);
+  const frontmatterHash = sha256(canonicalFrontmatter(raw.frontmatter, raw.frontmatterRaw));
   const kind = provider.classify(raw.path, raw.frontmatter);
   if (kind === null) {
     return false;
   }
   claimedPaths.add(raw.path);
   const priorNode = wctx.priorNodesByPath.get(raw.path);
-  const nodeHashCacheEligible = wctx.opts.enableCache && // Tokenizer-change invalidation: when the resolved encoder differs
-  // from the one that produced the prior snapshot's counts, no node is
-  // cache-eligible, every node rebuilds so `buildNode` re-tokenizes
-  // with the current encoder. See `tokenizerChanged` on the options.
-  !wctx.opts.tokenizerChanged && wctx.opts.prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
+  const nodeHashCacheEligible = isNodeHashCacheEligible(wctx, priorNode, bodyHash, frontmatterHash);
+  await dispatchNode(
+    { raw, provider, kind, bodyHash, frontmatterHash, nodeHashCacheEligible, priorNode },
+    wctx,
+    accum,
+    nextIndex
+  );
+  return true;
+}
+function isNodeHashCacheEligible(wctx, priorNode, bodyHash, frontmatterHash) {
+  return wctx.opts.enableCache && !wctx.opts.tokenizerChanged && wctx.opts.prior !== null && priorNode !== void 0 && priorNode.bodyHash === bodyHash && priorNode.frontmatterHash === frontmatterHash;
+}
+async function handleUnchangedRawNode(raw, provider, wctx, accum, claimedPaths, nextIndex) {
+  const prior = wctx.priorNodesByPath.get(raw.path);
+  if (prior) {
+    claimedPaths.add(raw.path);
+    await dispatchNode(
+      {
+        raw,
+        provider,
+        kind: prior.kind,
+        bodyHash: prior.bodyHash,
+        frontmatterHash: prior.frontmatterHash,
+        nodeHashCacheEligible: true,
+        priorNode: prior,
+        ensureBody: () => rereadInto(raw)
+      },
+      wctx,
+      accum,
+      nextIndex
+    );
+    return true;
+  }
+  await rereadInto(raw);
+  return false;
+}
+async function dispatchNode(args2, wctx, accum, nextIndex) {
   const sidecarResolution = resolveSidecarOverlay(
-    raw.path,
-    raw.path,
+    args2.raw.path,
+    args2.raw.path,
     wctx.opts.roots,
-    bodyHash,
-    frontmatterHash
+    args2.bodyHash,
+    args2.frontmatterHash
   );
   const sidecarAnnotationsHash = sha256(
     canonicalSidecarAnnotations(sidecarResolution.overlay.annotations)
   );
   const cacheDecision = computeCacheDecision({
     extractors: wctx.opts.extractors,
-    kind,
+    kind: args2.kind,
     activeProvider: wctx.opts.activeProvider,
-    nodePath: raw.path,
-    bodyHash,
+    nodePath: args2.raw.path,
+    bodyHash: args2.bodyHash,
     sidecarAnnotationsHash,
-    nodeHashCacheEligible,
+    nodeHashCacheEligible: args2.nodeHashCacheEligible,
     priorExtractorRuns: wctx.opts.priorExtractorRuns
   });
   const ctx = {
-    raw,
-    provider,
-    kind,
-    bodyHash,
-    frontmatterHash,
+    raw: args2.raw,
+    provider: args2.provider,
+    kind: args2.kind,
+    bodyHash: args2.bodyHash,
+    frontmatterHash: args2.frontmatterHash,
     sidecarResolution,
     sidecarAnnotationsHash,
-    nodeHashCacheEligible,
+    nodeHashCacheEligible: args2.nodeHashCacheEligible,
     cacheDecision,
-    priorNode,
+    priorNode: args2.priorNode,
     index: nextIndex
   };
-  if (cacheDecision.fullCacheHit && priorNode) {
+  if (cacheDecision.fullCacheHit && args2.priorNode) {
     applyFullCacheHit(ctx, wctx, accum);
   } else {
+    if (args2.ensureBody) await args2.ensureBody();
     await applyExtractPath(ctx, wctx, accum);
   }
-  return true;
+}
+async function rereadInto(raw) {
+  if (!raw.reread) return;
+  const re = await raw.reread();
+  raw.body = re.body;
+  raw.frontmatter = re.frontmatter;
+  raw.frontmatterRaw = re.frontmatterRaw;
+  raw.unchanged = false;
+  if (re.parseIssues) raw.parseIssues = re.parseIssues;
 }
 function attachSidecar(node, resolution, sidecarRoots) {
   node.sidecar = resolution.overlay;
@@ -17271,9 +17694,18 @@ async function runScanInternal(_kernel, options) {
     providerFrontmatter: setup.providerFrontmatter,
     pluginStores: options.pluginStores,
     activeProvider: activeProviderId,
-    recommendedNodeLimit: options.recommendedNodeLimit ?? 256,
-    overrideMaxNodes: options.overrideMaxNodes ?? null,
-    ...options.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: options.maxFileSizeBytes } : {}
+    scanCeiling: options.scanCeiling ?? 5e4,
+    overrideScanCeiling: options.overrideScanCeiling ?? null,
+    maxRenderNodes: options.maxRenderNodes ?? 256,
+    overrideMaxRenderNodes: options.overrideMaxRenderNodes ?? null,
+    ...options.maxFileSizeBytes !== void 0 ? { maxFileSizeBytes: options.maxFileSizeBytes } : {},
+    // Watcher incremental fast path: only honoured when a prior exists,
+    // cache reuse is on, and the tokenizer is unchanged (else a scoped
+    // read would skip nodes whose token counts must be recomputed). The
+    // walker enumerates from the prior snapshot + reads only the changed
+    // files instead of traversing the corpus. Falls back to the full
+    // traversal + mtime-gate when the gate does not hold.
+    ...options.incrementalChangedPaths !== void 0 && prior !== null && setup.enableCache && !tokenizerChanged ? { incrementalChangedPaths: options.incrementalChangedPaths } : {}
   });
   const activeProvider = activeProviderId ? exts.providers.find((p) => p.id === activeProviderId) ?? null : null;
   const resolved = resolveSignals({
@@ -17471,8 +17903,9 @@ function buildScanReturn(walked, issues, renameOps, stats, options, setup, linkS
       providers: setup.exts.providers.map((a) => a.id),
       scannedBy: SCANNED_BY,
       tokenizer: setup.tokenizer,
-      recommendedNodeLimit: walked.recommendedNodeLimit,
-      overrideMaxNodes: walked.overrideMaxNodes,
+      scanCeiling: walked.scanCeiling,
+      scanTruncated: walked.scanTruncated,
+      maxRenderNodes: walked.maxRenderNodes,
       oversizedFiles: walked.oversizedFiles,
       nodes: walked.nodes,
       links: walked.internalLinks,
@@ -17501,7 +17934,7 @@ function validateRoots(roots) {
 function resolveActiveProviderOption(optionValue, roots, providers) {
   if (optionValue !== void 0) return optionValue;
   for (const root of roots) {
-    const absRoot = isAbsolute7(root) ? root : resolve28(root);
+    const absRoot = isAbsolute9(root) ? root : resolve30(root);
     if (!existsSync23(absRoot)) continue;
     const detected = detectProvidersFromFilesystem(absRoot, providers)[0] ?? null;
     if (detected !== null) return detected;
@@ -17510,10 +17943,10 @@ function resolveActiveProviderOption(optionValue, roots, providers) {
 }
 
 // kernel/scan/watcher.ts
-import { resolve as resolve29, relative as relative5, sep as sep5 } from "path";
+import { resolve as resolve31, relative as relative5, sep as sep5 } from "path";
 import chokidar from "chokidar";
 function createChokidarWatcher(opts) {
-  const absRoots = opts.roots.map((r) => resolve29(opts.cwd, r));
+  const absRoots = opts.roots.map((r) => resolve31(opts.cwd, r));
   const ignoreFilterOpt = opts.ignoreFilter;
   const getFilter = ignoreFilterOpt === void 0 ? void 0 : typeof ignoreFilterOpt === "function" ? ignoreFilterOpt : () => ignoreFilterOpt;
   const ignored = getFilter ? (path) => {
@@ -18036,7 +18469,7 @@ function resolveScanRoots(inputs) {
 // core/runtime/reference-paths-walker.ts
 import { readdirSync as readdirSync8, statSync as statSync7 } from "fs";
 import { homedir as osHomedir2 } from "os";
-import { isAbsolute as isAbsolute8, join as join14, resolve as resolve30 } from "path";
+import { isAbsolute as isAbsolute10, join as join14, resolve as resolve32 } from "path";
 var REFERENCE_WALK_MAX_FILES = 5e4;
 var SKIPPED_DIR_NAMES = /* @__PURE__ */ new Set([
   "node_modules",
@@ -18044,10 +18477,10 @@ var SKIPPED_DIR_NAMES = /* @__PURE__ */ new Set([
   SKILL_MAP_DIR
 ]);
 function resolveScanPath(raw, cwd) {
-  if (raw.startsWith("~/")) return resolve30(join14(osHomedir2(), raw.slice(2)));
-  if (raw === "~") return resolve30(osHomedir2());
-  if (isAbsolute8(raw)) return resolve30(raw);
-  return resolve30(cwd, raw);
+  if (raw.startsWith("~/")) return resolve32(join14(osHomedir2(), raw.slice(2)));
+  if (raw === "~") return resolve32(osHomedir2());
+  if (isAbsolute10(raw)) return resolve32(raw);
+  return resolve32(cwd, raw);
 }
 function walkReferencePaths(rawRoots, cwd) {
   const paths = /* @__PURE__ */ new Set();
@@ -18096,7 +18529,7 @@ function safeStat(path) {
 
 // core/runtime/active-provider-bootstrap.ts
 import { createInterface as createInterface3 } from "readline";
-import { isAbsolute as isAbsolute9, join as join15 } from "path";
+import { isAbsolute as isAbsolute11, join as join15 } from "path";
 async function bootstrapActiveProvider(opts) {
   const fromCwd = resolveActiveProvider(opts.cwd, opts.providers);
   if (fromCwd.source === "config") {
@@ -18155,7 +18588,7 @@ function aggregateDetected(cwd, effectiveRoots, cwdDetected, providers) {
     out.push(id);
   }
   for (const root of effectiveRoots) {
-    const absRoot = isAbsolute9(root) ? root : join15(cwd, root);
+    const absRoot = isAbsolute11(root) ? root : join15(cwd, root);
     const r = resolveActiveProvider(absRoot, providers);
     for (const id of r.detected) {
       if (seen.has(id)) continue;
@@ -18413,6 +18846,7 @@ async function runScanForCommand(opts) {
     referenceablePaths,
     ctx.cwd,
     activeProvider,
+    cfg.scan.maxScan,
     cfg.scan.maxNodes,
     cfg.scan.maxFileSizeBytes,
     cfg.tokenizer
@@ -18531,7 +18965,7 @@ function makePriorLoader(noBuiltIns, strict) {
     return loaded;
   };
 }
-function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider, recommendedNodeLimit, maxFileSizeBytes, tokenizer) {
+function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, extensions, referenceablePaths, scanCwd, activeProvider, scanCeiling, maxRenderNodes, maxFileSizeBytes, tokenizer) {
   return async (prior, priorExtractorRuns) => {
     if (opts.changed && prior === null) {
       opts.stderr.write(SCAN_RUNNER_TEXTS.changedNoPriorWarning);
@@ -18546,7 +18980,8 @@ function makeScanRunner(kernel, opts, effectiveRoots, ignoreFilter, strict, exte
       cwd: scanCwd,
       prior,
       activeProvider,
-      recommendedNodeLimit,
+      scanCeiling,
+      maxRenderNodes,
       maxFileSizeBytes,
       tokenizer,
       ...priorExtractorRuns ? { priorExtractorRuns } : {}
@@ -18564,8 +18999,10 @@ function buildRunScanOptions(args2) {
     strict: args2.strict,
     emitter: buildRunScanEmitter(opts),
     activeProvider: args2.activeProvider,
-    recommendedNodeLimit: args2.recommendedNodeLimit,
-    overrideMaxNodes: opts.maxNodes ?? null,
+    scanCeiling: args2.scanCeiling,
+    overrideScanCeiling: opts.maxScan ?? null,
+    maxRenderNodes: args2.maxRenderNodes,
+    overrideMaxRenderNodes: opts.maxNodes ?? null,
     maxFileSizeBytes: args2.maxFileSizeBytes
   };
   if (args2.extensions) runOptions.extensions = args2.extensions;
@@ -19510,7 +19947,7 @@ import { Command as Command19, Option as Option18 } from "clipanion";
 
 // kernel/jobs/orphan-files.ts
 import { readdirSync as readdirSync9, statSync as statSync8 } from "fs";
-import { join as join17, resolve as resolve31 } from "path";
+import { join as join17, resolve as resolve33 } from "path";
 function findOrphanJobFiles(jobsDir, referencedPaths) {
   let entries;
   try {
@@ -19528,7 +19965,7 @@ function findOrphanJobFiles(jobsDir, referencedPaths) {
     if (!entry.isFile()) continue;
     const name = entry.name;
     if (!name.endsWith(".md")) continue;
-    const abs = resolve31(join17(jobsDir, name));
+    const abs = resolve33(join17(jobsDir, name));
     if (!referencedPaths.has(abs)) orphans.push(abs);
   }
   orphans.sort();
@@ -20755,9 +21192,9 @@ function sortPluginsForPresentation(plugins) {
 }
 
 // cli/commands/plugins/shared.ts
-import { resolve as resolve32 } from "path";
+import { resolve as resolve34 } from "path";
 function resolveSearchPaths2(opts, cwd) {
-  if (opts.pluginDir) return [resolve32(opts.pluginDir)];
+  if (opts.pluginDir) return [resolve34(opts.pluginDir)];
   return [defaultProjectPluginsDir({ cwd })];
 }
 async function buildResolver() {
@@ -22071,7 +22508,7 @@ function resolveBareToggle(id, catalogue) {
 
 // cli/commands/plugins/create.ts
 import { existsSync as existsSync25, mkdirSync as mkdirSync5, writeFileSync } from "fs";
-import { dirname as dirname17, join as join18, resolve as resolve33 } from "path";
+import { dirname as dirname17, join as join18, resolve as resolve35 } from "path";
 import { Command as Command26, Option as Option25 } from "clipanion";
 
 // cli/commands/plugins/scaffold/action.ts
@@ -22521,7 +22958,7 @@ var PluginsCreateCommand = class extends SmCommand {
     const kind = this.kind;
     const ctx = defaultRuntimeContext();
     const baseDir = defaultProjectPluginsDir(ctx);
-    const targetDir = this.at ? resolve33(this.at) : join18(baseDir, this.pluginId);
+    const targetDir = this.at ? resolve35(this.at) : join18(baseDir, this.pluginId);
     if (existsSync25(targetDir) && !this.force) {
       this.printer.error(
         tx(PLUGINS_TEXTS.createRefuseOverwrite, {
@@ -23037,7 +23474,7 @@ var PLUGIN_COMMANDS = [
 
 // cli/commands/refresh.ts
 import { readFile as readFile4 } from "fs/promises";
-import { resolve as resolve34 } from "path";
+import { resolve as resolve36 } from "path";
 import { Command as Command30, Option as Option28 } from "clipanion";
 
 // cli/i18n/refresh.texts.ts
@@ -23345,7 +23782,7 @@ var RefreshCommand = class extends SmCommand {
       let body;
       try {
         assertContained(cwd, node.path);
-        const raw = await readFile4(resolve34(cwd, node.path), "utf8");
+        const raw = await readFile4(resolve36(cwd, node.path), "utf8");
         body = stripFrontmatterFence(raw);
       } catch (err) {
         if (!this.json) {
@@ -23418,7 +23855,7 @@ var IntentionalFailCommand = class extends SmCommand {
     setTimeout(() => {
       throw new Error(INTENTIONAL_FAIL_TEXTS.errorMessage);
     }, 0);
-    await new Promise((resolve40) => setTimeout(resolve40, 5e3));
+    await new Promise((resolve43) => setTimeout(resolve43, 5e3));
     return ExitCode.Issues;
   }
 };
@@ -23508,15 +23945,16 @@ var SCAN_TEXTS = {
   countInfoNoun: "info",
   countNoIssues: "0 issues",
   /**
-   * 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>`.
+   * Truncation notice, printed when the walker stopped accepting files
+   * because the walk ceiling `--max-scan` (or the `scan.maxScan`
+   * setting) was reached and extra files were dropped. `{{glyph}}` is
+   * the yellow warning glyph, `{{limit}}` the effective ceiling,
+   * `{{source}}` either `--max-scan` or `scan.maxScan`. The hint names
+   * both escape routes the user has: editing `.skillmapignore`
+   * (preferred) or raising the ceiling with `--max-scan <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.",
+  scanCappedNotice: "{{glyph}}  Scan truncated at {{limit}} files ({{source}}); extra files were dropped.\n     {{hint}}\n",
+  scanCappedNoticeHint: "Edit .skillmapignore to exclude noisy paths (preferred), or re-run with --max-scan <N> to raise the ceiling. Files past the ceiling are not parsed, analyzed, or reference-validated.",
   /**
    * File-size skip notice, printed (WARN, stderr) when the walker
    * skipped one or more files for exceeding `scan.maxFileSizeBytes`.
@@ -23531,6 +23969,12 @@ var SCAN_TEXTS = {
   scanSkippedFileNounSingular: "file",
   scanSkippedFileNounPlural: "files",
   scanSkippedFilesNoticeHint: "Raise scan.maxFileSizeBytes to include these, or add them to .skillmapignore to skip them on purpose.",
+  /**
+   * Validation message for an invalid `--max-scan` value. Surfaced as a
+   * §3.1b two-line block.
+   */
+  maxScanInvalid: "{{glyph}}  --max-scan must be an integer >= 1 (got `{{value}}`).\n   {{hint}}\n",
+  maxScanInvalidHint: "Pass a positive integer, e.g. --max-scan 50000.",
   /**
    * Validation message for an invalid `--max-nodes` value. Surfaced as a
    * §3.1b two-line block.
@@ -23579,7 +24023,7 @@ var SCAN_TEXTS = {
 import { Command as Command31, Option as Option29 } from "clipanion";
 
 // core/watcher/runtime.ts
-import { dirname as dirname18 } from "path";
+import { dirname as dirname18, isAbsolute as isAbsolute12, relative as relative7, resolve as resolve37, sep as sep6 } from "path";
 
 // core/runtime/fresh-resolver.ts
 async function buildFreshResolver(deps) {
@@ -23612,6 +24056,39 @@ async function rebuildWatcherDbOnDrift(dbPath, events) {
     events.onDriftReset?.({ dbVersion: drift.dbVersion, currentVersion: drift.currentVersion });
   }
 }
+function applyPriorStateToRunOptions(runOptions, priorState, changedPaths) {
+  if (!priorState) return;
+  runOptions.priorSnapshot = priorState.snapshot;
+  runOptions.enableCache = true;
+  runOptions.priorExtractorRuns = priorState.extractorRuns;
+  if (changedPaths) {
+    runOptions.incrementalChangedPaths = {
+      changed: changedPaths.changed,
+      removed: changedPaths.removed
+    };
+  }
+}
+function toIncrementalPaths(events, roots, cwd) {
+  const absRoots = roots.map((r) => isAbsolute12(r) ? r : resolve37(cwd, r));
+  const changed = /* @__PURE__ */ new Set();
+  const removed = /* @__PURE__ */ new Set();
+  for (const ev of events) {
+    const rel = relativeFromRoots2(ev.absolutePath, absRoots);
+    if (rel === null) continue;
+    if (ev.kind === "unlink") removed.add(rel);
+    else changed.add(rel);
+  }
+  if (changed.size === 0 && removed.size === 0) return null;
+  return { changed, removed };
+}
+function relativeFromRoots2(absolute, absRoots) {
+  for (const root of absRoots) {
+    const rel = relative7(root, absolute);
+    if (rel === "" || rel.startsWith("..") || isAbsolute12(rel)) continue;
+    return rel.split(sep6).join("/");
+  }
+  return null;
+}
 function createWatcherRuntime(opts) {
   const events = opts.events ?? {};
   const cwd = opts.runtimeContext.cwd;
@@ -23665,7 +24142,11 @@ function createWatcherRuntime(opts) {
     for (const warn of pluginRuntime.warnings) {
       events.onPluginWarning?.(warn);
     }
-    const runOnePass = async () => {
+    const notifyBatchStart = () => {
+      events.onBatchStart?.();
+    };
+    const runOnePass = async (changedPaths) => {
+      notifyBatchStart();
       const resolveEnabledOverride = await buildFreshResolver({
         databasePath: opts.dbPath,
         effectiveConfig: () => cfg,
@@ -23711,8 +24192,10 @@ function createWatcherRuntime(opts) {
         ignoreFilter,
         strict,
         emitter,
-        recommendedNodeLimit: cfg.scan.maxNodes,
-        overrideMaxNodes: opts.maxNodesOverride ?? null,
+        scanCeiling: cfg.scan.maxScan,
+        overrideScanCeiling: opts.maxScanOverride ?? null,
+        maxRenderNodes: cfg.scan.maxNodes,
+        overrideMaxRenderNodes: opts.maxNodesOverride ?? null,
         maxFileSizeBytes: cfg.scan.maxFileSizeBytes
       };
       if (cfg.scan.referencePaths.length > 0) {
@@ -23723,11 +24206,7 @@ function createWatcherRuntime(opts) {
         }
       }
       if (composed) runOptions.extensions = composed;
-      if (priorState) {
-        runOptions.priorSnapshot = priorState.snapshot;
-        runOptions.enableCache = true;
-        runOptions.priorExtractorRuns = priorState.extractorRuns;
-      }
+      applyPriorStateToRunOptions(runOptions, priorState, changedPaths);
       const ran = await runScanWithRenames(kernel, runOptions);
       const {
         result,
@@ -23754,11 +24233,11 @@ function createWatcherRuntime(opts) {
       );
       return result;
     };
-    handleBatch = async () => {
+    handleBatch = async (changedPaths) => {
       if (stopped) return;
       batchCount++;
       try {
-        const result = await runOnePass();
+        const result = await runOnePass(changedPaths);
         consecutiveFailures = 0;
         events.onBatch?.({ kind: "ok", result });
       } catch (err) {
@@ -23805,8 +24284,11 @@ function createWatcherRuntime(opts) {
         // `.skill-map/settings.json` edit, and chokidar's `ignored`
         // predicate must read the current value on every event.
         ignoreFilter: () => ignoreFilter,
-        onBatch: async () => {
-          if (handleBatch) await handleBatch();
+        onBatch: async ({ events: batchEvents }) => {
+          if (!handleBatch) return;
+          const changedPaths = toIncrementalPaths(batchEvents, opts.roots, cwd);
+          if (changedPaths) await handleBatch(changedPaths);
+          else await handleBatch();
         },
         onError: (err) => {
           events.onWatcherError?.(err.message);
@@ -23938,6 +24420,11 @@ var WATCH_TEXTS = {
    */
   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).",
+  /**
+   * §3.1b two-line block. Validation rejection for `--max-scan`.
+   */
+  maxScanInvalid: "{{glyph}}  sm watch: --max-scan must be an integer >= 1 (got {{raw}}).\n   {{hint}}\n",
+  maxScanInvalidHint: "Pass a positive integer, e.g. --max-scan 50000.",
   /**
    * §3.1b two-line block. Validation rejection for `--max-nodes`.
    */
@@ -24033,6 +24520,7 @@ async function runWatchLoop(opts) {
     circuitBreaker: { maxConsecutiveFailures: breakerLimit },
     killSwitches: readConformanceKillSwitches(),
     ...opts.maxBatches !== void 0 ? { maxBatches: opts.maxBatches } : {},
+    ...opts.maxScan !== void 0 ? { maxScanOverride: opts.maxScan } : {},
     ...opts.maxNodes !== void 0 ? { maxNodesOverride: opts.maxNodes } : {},
     events: {
       onBatch: (outcome) => {
@@ -24157,9 +24645,13 @@ var WatchCommand = class extends SmCommand {
     required: false,
     description: "Shut down with exit 2 after N consecutive batch failures (default 5; 0 disables the breaker)."
   });
+  maxScan = Option29.String("--max-scan", {
+    required: false,
+    description: "Per-batch override of scan.maxScan (default 50000), the WALK-INTAKE ceiling. The scan walks, parses, analyzes, and reference-validates the full corpus up to this number. Bidirectional: raises OR lowers the ceiling. When a batch hits it, additional files are dropped in stable order and the UI surfaces the persistent truncation banner. Validation: integer >= 1."
+  });
   maxNodes = Option29.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."
+    description: "Per-batch override of scan.maxNodes (default 256), the MAP RENDER cap (pure metadata): it does NOT bound the scan, only the graph projection. Bidirectional: raises OR lowers the render cap. Validation: integer >= 1."
   });
   // Long-running verb, the watcher prints its own "stopped" line on
   // SIGINT / SIGTERM. Adding `done in <…>` after that would be noise.
@@ -24168,6 +24660,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 maxScan = parseMaxScanLimit(this.maxScan, this.context.stderr, this.noColor);
+    if (maxScan === null) return ExitCode.Error;
     const maxNodes = parseMaxNodesLimit(this.maxNodes, this.context.stderr, this.noColor);
     if (maxNodes === null) return ExitCode.Error;
     const watchOpts = {
@@ -24182,6 +24676,7 @@ var WatchCommand = class extends SmCommand {
       printer: this.printer
     };
     if (breaker !== void 0) watchOpts.maxConsecutiveFailures = breaker;
+    if (maxScan !== void 0) watchOpts.maxScan = maxScan;
     if (maxNodes !== void 0) watchOpts.maxNodes = maxNodes;
     return runWatchLoop(watchOpts);
   }
@@ -24203,6 +24698,23 @@ function parseBreakerLimit(raw, stderr, noColor) {
   }
   return parsed;
 }
+function parseMaxScanLimit(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.maxScanInvalid, {
+        glyph: ansi.red("\u2715"),
+        raw,
+        hint: ansi.dim(WATCH_TEXTS.maxScanInvalidHint)
+      })
+    );
+    return null;
+  }
+  return n;
+}
 function parseMaxNodesLimit(raw, stderr, noColor) {
   if (raw === void 0) return void 0;
   const n = Number(raw);
@@ -24287,16 +24799,20 @@ var ScanCommand = class extends SmCommand {
   yes = Option30.Boolean("--yes", false, {
     description: "Non-interactive mode. For ambiguous activeProvider auto-detect, multiple provider markers (.claude/, .codex/, AGENTS.md, .cursor/) under the scan tree exit non-zero instead of prompting; set the lens manually via `sm config set activeProvider <id>` and re-run. Also auto-confirms the pre-1.0 schema-drift rebuild (when the DB was written by a different skill-map major.minor it is deleted and regenerated) instead of prompting."
   });
+  maxScan = Option30.String("--max-scan", {
+    required: false,
+    description: "Per-invocation override of `scan.maxScan` (default 50000). The WALK-INTAKE ceiling: the scan walks, parses, analyzes, and reference-validates the full corpus up to this number. Bidirectional: raises OR lowers the ceiling. When the walker hits it, additional files are dropped in stable order and the scan is marked truncated in scan_meta (the UI raises a persistent banner pointing at the .skillmapignore editor in Settings \u2192 Project). Validation: integer >= 1."
+  });
   maxNodes = Option30.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."
+    description: "Per-invocation override of `scan.maxNodes` (default 256). The MAP RENDER cap (pure metadata): it does NOT bound the scan, only how many nodes the graph view projects onto the canvas. Bidirectional: raises OR lowers the render cap. 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;
+    const caps = this.parseCapFlags();
+    if (caps.kind === "error") return caps.exit;
     if (this.watch) return this.runWatchAlias();
     if (this.changed && this.noBuiltIns) {
       const ansi = this.ansiFor("stderr");
@@ -24333,7 +24849,7 @@ var ScanCommand = class extends SmCommand {
       colorEnabled,
       yes: this.yes,
       style,
-      ...parsedMaxNodes.value !== void 0 ? { maxNodes: parsedMaxNodes.value } : {}
+      ...capOverrides(caps)
     });
     if (outcome.kind === "ok") {
       setScanExtensions(buildScanExtensionSet(outcome.executedExtensionIds));
@@ -24348,21 +24864,35 @@ var ScanCommand = class extends SmCommand {
     return 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.
+   * Parse both cap flags in one pass: `--max-scan <N>` (the WALK-INTAKE
+   * ceiling) and `--max-nodes <N>` (the MAP RENDER cap). Returns both
+   * resolved values (each `undefined` when its flag was omitted) or an
+   * error sentinel after printing the §3.1b validation block for the
+   * first offending flag. Invalid (non-integer, < 1) exits 2 per
+   * spec/cli-contract.md §Scan.
+   */
+  parseCapFlags() {
+    const scan = this.parseIntegerFlag(this.maxScan, SCAN_TEXTS.maxScanInvalid, SCAN_TEXTS.maxScanInvalidHint);
+    if (scan.kind === "error") return scan;
+    const nodes = this.parseIntegerFlag(this.maxNodes, SCAN_TEXTS.maxNodesInvalid, SCAN_TEXTS.maxNodesInvalidHint);
+    if (nodes.kind === "error") return nodes;
+    return { kind: "ok", maxScan: scan.value, maxNodes: nodes.value };
+  }
+  /**
+   * Shared integer-flag parser for `--max-scan` / `--max-nodes`. Both
+   * accept the same shape (integer >= 1) and render the same §3.1b
+   * validation block; only the template + hint differ.
    */
-  parseMaxNodesFlag() {
-    if (this.maxNodes === void 0) return { kind: "ok", value: void 0 };
-    const n = Number(this.maxNodes);
+  parseIntegerFlag(raw, invalidTemplate, invalidHint) {
+    if (raw === void 0) return { kind: "ok", value: void 0 };
+    const n = Number(raw);
     if (!Number.isInteger(n) || n < 1) {
       const ansi = this.ansiFor("stderr");
       this.printer.info(
-        tx(SCAN_TEXTS.maxNodesInvalid, {
+        tx(invalidTemplate, {
           glyph: ansi.red("\u2715"),
-          value: this.maxNodes,
-          hint: ansi.dim(SCAN_TEXTS.maxNodesInvalidHint)
+          value: raw,
+          hint: ansi.dim(invalidHint)
         })
       );
       return { kind: "error", exit: ExitCode.Error };
@@ -24388,7 +24918,7 @@ var ScanCommand = class extends SmCommand {
     }
     this.emitElapsed = false;
     const roots = this.roots.length > 0 ? this.roots : ["."];
-    const parsedMaxNodes = this.parseMaxNodesFlag();
+    const caps = this.parseCapFlags();
     return runWatchLoop({
       roots,
       json: this.json,
@@ -24399,7 +24929,7 @@ var ScanCommand = class extends SmCommand {
       noPlugins: this.noPlugins,
       context: this.context,
       printer: this.printer,
-      ...parsedMaxNodes.kind === "ok" && parsedMaxNodes.value !== void 0 ? { maxNodes: parsedMaxNodes.value } : {}
+      ...caps.kind === "ok" ? capOverrides(caps) : {}
     });
   }
   /**
@@ -24515,24 +25045,24 @@ var ScanCommand = class extends SmCommand {
     );
   }
   /**
-   * 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.
+   * Surface the §Scan truncation notice when the walker actually
+   * stopped accepting files because the walk ceiling (`scan.maxScan` or
+   * the `--max-scan` override) was reached and extra files were dropped.
+   * Fires on `result.scanTruncated`, the kernel sets it when the walker
+   * hit the ceiling; a project with at most the ceiling many files ends
+   * the loop naturally with `scanTruncated: false`, 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;
+    if (result.scanTruncated !== true) return;
+    const ceiling = result.scanCeiling;
+    if (ceiling === void 0) return;
+    const source = this.maxScan !== void 0 ? "--max-scan" : "scan.maxScan";
     this.printer.info(
       tx(SCAN_TEXTS.scanCappedNotice, {
         glyph: ansi.yellow("\u26A0"),
-        limit: String(effectiveLimit),
-        source: override !== null ? "--max-nodes" : "scan.maxNodes",
+        limit: String(ceiling),
+        source,
         hint: ansi.dim(SCAN_TEXTS.scanCappedNoticeHint)
       })
     );
@@ -24625,6 +25155,12 @@ function formatScanCounts(opts) {
 function countNoun(count3, singular, plural) {
   return count3 === 1 ? singular : plural;
 }
+function capOverrides(caps) {
+  const out = {};
+  if (caps.maxScan !== void 0) out.maxScan = caps.maxScan;
+  if (caps.maxNodes !== void 0) out.maxNodes = caps.maxNodes;
+  return out;
+}
 
 // cli/commands/scan-compare.ts
 import { access, readFile as readFile5 } from "fs/promises";
@@ -24877,11 +25413,11 @@ import { existsSync as existsSync31 } from "fs";
 import { Command as Command34, Option as Option32 } from "clipanion";
 
 // kernel/util/dev-mode.ts
-import { sep as sep6 } from "path";
+import { sep as sep7 } from "path";
 import { fileURLToPath as fileURLToPath5 } from "url";
 var SELF_PATH = fileURLToPath5(import.meta.url);
-var IS_DEV_BUILD = isDevBuildFromPath(SELF_PATH, sep6);
-function isDevBuildFromPath(filePath, separator = sep6) {
+var IS_DEV_BUILD = isDevBuildFromPath(SELF_PATH, sep7);
+function isDevBuildFromPath(filePath, separator = sep7) {
   return !filePath.includes(`${separator}node_modules${separator}`);
 }
 function isDevBuild() {
@@ -24907,7 +25443,7 @@ import { WebSocketServer } from "ws";
 // server/app.ts
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
-import { HTTPException as HTTPException17 } from "hono/http-exception";
+import { HTTPException as HTTPException18 } from "hono/http-exception";
 
 // core/config/service.ts
 var ConfigService = class {
@@ -24987,6 +25523,12 @@ var SERVER_TEXTS = {
   // Pagination caps on /api/nodes.
   paginationLimitTooLarge: "limit={{value}} exceeds the maximum of {{max}}.",
   paginationInvalidInteger: "{{name}}={{value}} is not a non-negative integer.",
+  // /api/branch, the `limit` query param must be a positive integer
+  // (>= 1). Non-integer / zero / negative rejects with 400 bad-query
+  // before the branch projection runs. A value above the scan's
+  // effective maxRenderNodes is silently clamped down (never an error),
+  // so this message only ever fires on a malformed / < 1 input.
+  branchInvalidLimit: "limit={{value}} is not a positive integer (>= 1).",
   // Required-query-param miss (used by `parseRequiredString`). The
   // route names the offending parameter so the operator gets a useful
   // 400 instead of a generic "missing input".
@@ -25393,20 +25935,148 @@ function registerAnnotationsRoute(app, deps) {
   });
 }
 
-// server/routes/contributions.ts
-import { HTTPException as HTTPException3 } from "hono/http-exception";
-
-// server/util/parse-query.ts
+// server/routes/branch.ts
 import { HTTPException as HTTPException2 } from "hono/http-exception";
-function parseCsv(value) {
-  if (value === void 0) return [];
-  return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-}
+
+// server/envelope.ts
+var REST_ENVELOPE_SCHEMA_VERSION = "1";
+function buildListEnvelope(opts) {
+  const counts = {
+    total: opts.total,
+    returned: opts.items.length
+  };
+  if (opts.page) counts.page = opts.page;
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind: opts.kind,
+    items: opts.items,
+    filters: opts.filters,
+    counts,
+    kindRegistry: opts.kindRegistry,
+    providerRegistry: opts.providerRegistry,
+    contributionsRegistry: opts.contributionsRegistry
+  };
+}
+function buildValueEnvelope(kind, value, kindRegistry, providerRegistry, contributionsRegistry) {
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind,
+    value,
+    kindRegistry,
+    providerRegistry,
+    contributionsRegistry
+  };
+}
+
+// server/routes/branch.ts
+var DEFAULT_MAX_RENDER_NODES2 = 256;
+function registerBranchRoute(app, deps) {
+  app.get("/api/branch", async (c) => {
+    const prefixes = c.req.queries("path")?.filter((p) => p.length > 0) ?? [];
+    const limitOverride = parseLimit(c.req.query("limit"));
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      async (adapter) => {
+        const maxRenderNodes = await adapter.scans.effectiveMaxRenderNodes();
+        const cap = limitOverride === void 0 ? maxRenderNodes : Math.min(limitOverride, maxRenderNodes);
+        const [branch, favSet] = await Promise.all([
+          adapter.scans.loadBranch(prefixes, cap),
+          adapter.favorites.listPaths()
+        ]);
+        const paths = branch.nodes.map((n) => n.path);
+        const [tagRows, contribRows] = await Promise.all([
+          adapter.tags.listForPaths(paths),
+          adapter.contributions.listForPaths(paths)
+        ]);
+        return { branch, favSet, tagRows, contribRows, cap };
+      }
+    );
+    return c.json(buildBranchResponse(prefixes, loaded));
+  });
+}
+function buildBranchResponse(prefixes, loaded) {
+  if (loaded === null) {
+    return {
+      schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+      kind: "branch",
+      branch: { paths: [...new Set(prefixes)], total: 0, rendered: 0, truncated: false, cap: DEFAULT_MAX_RENDER_NODES2 },
+      nodes: [],
+      links: [],
+      issues: []
+    };
+  }
+  const { branch, favSet, tagRows, contribRows, cap } = loaded;
+  const tagsByPath = groupTagsByPath(tagRows);
+  const contribByPath = groupContribsByPath(contribRows);
+  const nodes = branch.nodes.map((n) => ({
+    ...n,
+    isFavorite: favSet.has(n.path),
+    tags: tagsByPath.get(n.path) ?? [],
+    contributions: contribByPath.get(n.path) ?? []
+  }));
+  const rendered = nodes.length;
+  return {
+    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
+    kind: "branch",
+    branch: {
+      // Echo the de-duped prefixes the storage layer actually scoped on.
+      paths: branch.paths,
+      total: branch.total,
+      rendered,
+      truncated: branch.total > cap,
+      cap
+    },
+    nodes,
+    links: branch.links,
+    issues: branch.issues
+  };
+}
+function parseLimit(raw) {
+  if (raw === void 0 || raw.length === 0) return void 0;
+  const trimmed = raw.trim();
+  const parsed = Number.parseInt(trimmed, 10);
+  if (!Number.isInteger(parsed) || parsed < 1 || String(parsed) !== trimmed) {
+    throw new HTTPException2(400, {
+      message: tx(SERVER_TEXTS.branchInvalidLimit, { value: raw })
+    });
+  }
+  return parsed;
+}
+function groupTagsByPath(rows) {
+  const buckets = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const set = buckets.get(r.nodePath);
+    if (set) set.add(r.tag);
+    else buckets.set(r.nodePath, /* @__PURE__ */ new Set([r.tag]));
+  }
+  const out = /* @__PURE__ */ new Map();
+  for (const [path, set] of buckets) out.set(path, [...set].sort());
+  return out;
+}
+function groupContribsByPath(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const r of rows) {
+    const list = out.get(r.nodePath);
+    if (list) list.push(r);
+    else out.set(r.nodePath, [r]);
+  }
+  return out;
+}
+
+// server/routes/contributions.ts
+import { HTTPException as HTTPException4 } from "hono/http-exception";
+
+// server/util/parse-query.ts
+import { HTTPException as HTTPException3 } from "hono/http-exception";
+function parseCsv(value) {
+  if (value === void 0) return [];
+  return value.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 function parsePagination(query, defaults) {
   const offset = parseNonNegativeInt(query.offset, "offset", 0);
   const limit = parseNonNegativeInt(query.limit, "limit", defaults.limit);
   if (limit > defaults.max) {
-    throw new HTTPException2(400, {
+    throw new HTTPException3(400, {
       message: tx(SERVER_TEXTS.paginationLimitTooLarge, {
         value: limit,
         max: defaults.max
@@ -25420,7 +26090,7 @@ function parseBooleanFlag(value) {
 }
 function parseRequiredString(value, name) {
   if (typeof value !== "string" || value.length === 0) {
-    throw new HTTPException2(400, {
+    throw new HTTPException3(400, {
       message: tx(SERVER_TEXTS.queryRequiredString, { name })
     });
   }
@@ -25431,7 +26101,7 @@ function parseNonNegativeInt(raw, name, fallback) {
   const trimmed = raw.trim();
   const parsed = Number.parseInt(trimmed, 10);
   if (!Number.isInteger(parsed) || parsed < 0 || String(parsed) !== trimmed) {
-    throw new HTTPException2(400, {
+    throw new HTTPException3(400, {
       message: tx(SERVER_TEXTS.paginationInvalidInteger, { name, value: raw })
     });
   }
@@ -25442,7 +26112,7 @@ function parseNonNegativeInt(raw, name, fallback) {
 var QUALIFIED_ID_SEGMENT = /^[A-Za-z0-9._-]+$/;
 function parseQualifiedIdSegment(value, name) {
   if (!QUALIFIED_ID_SEGMENT.test(value)) {
-    throw new HTTPException3(400, {
+    throw new HTTPException4(400, {
       message: tx(SERVER_TEXTS.qualifiedIdMalformed, {
         name,
         value: sanitizeForTerminal(value)
@@ -25472,7 +26142,7 @@ function registerContributionsRoutes(app, deps) {
       (e) => e.pluginId === pluginId && e.extensionId === extensionId && e.contributionId === contributionId
     );
     if (!catalogEntry) {
-      throw new HTTPException3(404, {
+      throw new HTTPException4(404, {
         message: tx(SERVER_TEXTS.contributionUnknown, {
           pluginId: sanitizeForTerminal(pluginId),
           extensionId: sanitizeForTerminal(extensionId),
@@ -25503,46 +26173,14 @@ function registerContributionsRoutes(app, deps) {
 }
 
 // server/routes/config.ts
-import { HTTPException as HTTPException4 } from "hono/http-exception";
-
-// server/envelope.ts
-var REST_ENVELOPE_SCHEMA_VERSION = "1";
-function buildListEnvelope(opts) {
-  const counts = {
-    total: opts.total,
-    returned: opts.items.length
-  };
-  if (opts.page) counts.page = opts.page;
-  return {
-    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
-    kind: opts.kind,
-    items: opts.items,
-    filters: opts.filters,
-    counts,
-    kindRegistry: opts.kindRegistry,
-    providerRegistry: opts.providerRegistry,
-    contributionsRegistry: opts.contributionsRegistry
-  };
-}
-function buildValueEnvelope(kind, value, kindRegistry, providerRegistry, contributionsRegistry) {
-  return {
-    schemaVersion: REST_ENVELOPE_SCHEMA_VERSION,
-    kind,
-    value,
-    kindRegistry,
-    providerRegistry,
-    contributionsRegistry
-  };
-}
-
-// server/routes/config.ts
+import { HTTPException as HTTPException5 } from "hono/http-exception";
 function registerConfigRoute(app, deps) {
   app.get("/api/config", (c) => {
     let loaded;
     try {
       loaded = deps.configService.get();
     } catch (err) {
-      throw new HTTPException4(500, { message: formatErrorMessage(err) });
+      throw new HTTPException5(500, { message: formatErrorMessage(err) });
     }
     for (const warn of loaded.warnings) {
       log.warn(sanitizeForTerminal(warn));
@@ -25560,7 +26198,7 @@ function registerConfigRoute(app, deps) {
 }
 
 // server/routes/favorites.ts
-import { HTTPException as HTTPException5 } from "hono/http-exception";
+import { HTTPException as HTTPException6 } from "hono/http-exception";
 
 // server/path-codec.ts
 var PathCodecError = class extends Error {
@@ -25600,7 +26238,7 @@ function registerFavoritesRoutes(app, deps) {
       }
     );
     if (!result || !result.found) {
-      throw new HTTPException5(404, {
+      throw new HTTPException6(404, {
         message: tx(SERVER_TEXTS.nodeNotFound, { path: sanitizeForTerminal(nodePath) })
       });
     }
@@ -25620,14 +26258,57 @@ function decodePath(pathB64) {
     return decodeNodePath(pathB64);
   } catch (err) {
     if (err instanceof PathCodecError) {
-      throw new HTTPException5(404, { message: SERVER_TEXTS.pathB64Malformed });
+      throw new HTTPException6(404, { message: SERVER_TEXTS.pathB64Malformed });
     }
     throw err;
   }
 }
 
+// server/routes/folders.ts
+function registerFoldersRoute(app, deps) {
+  app.get("/api/folders", async (c) => {
+    const loaded = await tryWithSqlite(
+      { databasePath: deps.options.dbPath, autoBackup: false },
+      async (adapter) => {
+        const [liteNodes2, issueCounts2] = await Promise.all([
+          adapter.scans.listLiteNodes(),
+          adapter.scans.issueCountsByPath()
+        ]);
+        return { liteNodes: liteNodes2, issueCounts: issueCounts2 };
+      }
+    );
+    const liteNodes = loaded?.liteNodes ?? [];
+    const issueCounts = loaded?.issueCounts ?? /* @__PURE__ */ new Map();
+    const items = liteNodes.map((n) => {
+      const counts = issueCounts.get(n.path);
+      return {
+        path: n.path,
+        kind: n.kind,
+        linksInCount: n.linksInCount,
+        linksOutCount: n.linksOutCount,
+        tokensTotal: n.tokensTotal,
+        modifiedAtMs: n.modifiedAtMs,
+        errorCount: counts?.error ?? 0,
+        warnCount: counts?.warn ?? 0,
+        sidecarStatus: n.sidecarStatus
+      };
+    });
+    return c.json(
+      buildListEnvelope({
+        kind: "folders",
+        items,
+        filters: {},
+        total: items.length,
+        kindRegistry: deps.kindRegistry,
+        providerRegistry: deps.providerRegistry,
+        contributionsRegistry: deps.contributionsRegistry
+      })
+    );
+  });
+}
+
 // server/routes/graph.ts
-import { HTTPException as HTTPException6 } from "hono/http-exception";
+import { HTTPException as HTTPException7 } from "hono/http-exception";
 var DEFAULT_FORMAT2 = "ascii";
 var FORMAT_ID_PATTERN = /^[a-z0-9-]+$/;
 var FORMAT_ID_MAX = 32;
@@ -25635,7 +26316,7 @@ function registerGraphRoute(app, deps) {
   app.get("/api/graph", async (c) => {
     const format = c.req.query("format") ?? DEFAULT_FORMAT2;
     if (format.length > FORMAT_ID_MAX || !FORMAT_ID_PATTERN.test(format)) {
-      throw new HTTPException6(400, {
+      throw new HTTPException7(400, {
         // Sanitize defensively, the regex above already rejects ANSI
         // and control bytes, but the message interpolates user input
         // and the BFF mirrors error envelopes into the server log.
@@ -25651,7 +26332,7 @@ function registerGraphRoute(app, deps) {
     const formatter = formatters.find((f) => f.formatId === format);
     if (!formatter) {
       const available = formatters.map((f) => f.formatId).sort().join(", ");
-      throw new HTTPException6(400, {
+      throw new HTTPException7(400, {
         message: tx(SERVER_TEXTS.graphUnknownFormat, {
           format,
           available: available || "(none)"
@@ -25827,18 +26508,18 @@ function registerLinksRoute(app, deps) {
 }
 
 // server/routes/nodes.ts
-import { HTTPException as HTTPException7 } from "hono/http-exception";
+import { HTTPException as HTTPException8 } from "hono/http-exception";
 
 // server/node-body.ts
 import { constants as fsConstants2 } from "fs";
 import { open } from "fs/promises";
-import { isAbsolute as isAbsolute10, resolve as resolvePath2, relative as relativePath, sep as sep7 } from "path";
+import { isAbsolute as isAbsolute13, resolve as resolvePath2, relative as relativePath, sep as sep8 } from "path";
 async function readNodeBody(cwd, relPath) {
-  if (isAbsolute10(relPath)) return null;
+  if (isAbsolute13(relPath)) return null;
   const absRoot = resolvePath2(cwd);
   const absFile = resolvePath2(absRoot, relPath);
   const rel = relativePath(absRoot, absFile);
-  if (rel.startsWith("..") || rel.startsWith(sep7) || rel.length === 0) {
+  if (rel.startsWith("..") || rel.startsWith(sep8) || rel.length === 0) {
     return null;
   }
   let raw;
@@ -25938,7 +26619,7 @@ function registerNodesRoutes(app, deps) {
       nodePath = decodeNodePath(pathB64);
     } catch (err) {
       if (err instanceof PathCodecError) {
-        throw new HTTPException7(404, { message: SERVER_TEXTS.pathB64Malformed });
+        throw new HTTPException8(404, { message: SERVER_TEXTS.pathB64Malformed });
       }
       throw err;
     }
@@ -25970,7 +26651,7 @@ function registerNodesRoutes(app, deps) {
     const contributions = result?.contributions ?? [];
     const tags = result?.tags ?? [];
     if (!bundle) {
-      throw new HTTPException7(404, {
+      throw new HTTPException8(404, {
         message: tx(SERVER_TEXTS.nodeNotFound, { path: sanitizeForTerminal(nodePath) })
       });
     }
@@ -26022,7 +26703,7 @@ function registerNodesRoutes(app, deps) {
         const contribByPath = contributionsOmitted ? /* @__PURE__ */ new Map() : await groupContributionsByPath(
           await adapter.contributions.listForPaths(pagePaths)
         );
-        const tagByPath = groupTagsByPath(
+        const tagByPath = groupTagsByPath2(
           await adapter.tags.listForPaths(pagePaths)
         );
         return { contributionsByPath: contribByPath, tagsByPath: tagByPath };
@@ -26058,7 +26739,7 @@ function registerNodesRoutes(app, deps) {
 function parseIncludes(raw) {
   return new Set(parseCsv(raw));
 }
-function groupTagsByPath(rows) {
+function groupTagsByPath2(rows) {
   const buckets = /* @__PURE__ */ new Map();
   for (const r of rows) {
     const set = buckets.get(r.nodePath);
@@ -26080,11 +26761,11 @@ async function groupContributionsByPath(rows) {
 }
 
 // server/routes/plugins.ts
-import { HTTPException as HTTPException9 } from "hono/http-exception";
+import { HTTPException as HTTPException10 } from "hono/http-exception";
 
 // server/util/parse-body.ts
 import { Ajv2020 as Ajv20207 } from "ajv/dist/2020.js";
-import { HTTPException as HTTPException8 } from "hono/http-exception";
+import { HTTPException as HTTPException9 } from "hono/http-exception";
 function makeBodyValidator(schema, messages) {
   const ajv = new Ajv20207({ strict: false, allErrors: false });
   const validate = ajv.compile(schema);
@@ -26093,16 +26774,16 @@ function makeBodyValidator(schema, messages) {
     try {
       raw = await req.json();
     } catch {
-      throw new HTTPException8(400, { message: messages.notJson });
+      throw new HTTPException9(400, { message: messages.notJson });
     }
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-      throw new HTTPException8(400, { message: messages.notObject });
+      throw new HTTPException9(400, { message: messages.notObject });
     }
     if (validate(raw)) {
       return raw;
     }
     const message = resolveErrorMessage(validate.errors, messages);
-    throw new HTTPException8(400, { message });
+    throw new HTTPException9(400, { message });
   };
 }
 function resolveErrorMessage(errors, messages) {
@@ -26285,18 +26966,18 @@ function registerPluginsRoute(app, deps) {
   app.patch("/api/plugins/:id", async (c) => {
     const id = c.req.param("id");
     if (id.includes("/")) {
-      throw new HTTPException9(400, {
+      throw new HTTPException10(400, {
         message: tx(SERVER_TEXTS.pluginsCascadeRouteQualifiedRejected, { id })
       });
     }
     const handle = findHandle(id, deps);
     if (!handle) {
-      throw new HTTPException9(404, {
+      throw new HTTPException10(404, {
         message: tx(SERVER_TEXTS.pluginsUnknown, { id })
       });
     }
     if (isPluginLocked(id)) {
-      throw new HTTPException9(403, {
+      throw new HTTPException10(403, {
         message: tx(SERVER_TEXTS.pluginsLocked, { id })
       });
     }
@@ -26310,18 +26991,18 @@ function registerPluginsRoute(app, deps) {
     const extensionId = c.req.param("extensionId");
     const handle = findHandle(pluginId, deps);
     if (!handle) {
-      throw new HTTPException9(404, {
+      throw new HTTPException10(404, {
         message: tx(SERVER_TEXTS.pluginsUnknown, { id: pluginId })
       });
     }
     if (!hasExtension(handle, extensionId)) {
-      throw new HTTPException9(404, {
+      throw new HTTPException10(404, {
         message: tx(SERVER_TEXTS.pluginsExtensionUnknown, { pluginId, extensionId })
       });
     }
     const qualified = qualifiedExtensionId(pluginId, extensionId);
     if (isPluginLocked(qualified) || isPluginLocked(pluginId)) {
-      throw new HTTPException9(403, {
+      throw new HTTPException10(403, {
         message: tx(SERVER_TEXTS.pluginsExtensionLocked, { pluginId, extensionId })
       });
     }
@@ -26679,7 +27360,7 @@ function persistBulkSettings(deps, changes) {
     try {
       persistSettingsPatch(pluginId, extensionId, declarations, change.settings, cwd);
     } catch (err) {
-      throw new HTTPException9(500, {
+      throw new HTTPException10(500, {
         message: tx(SERVER_TEXTS.pluginsSettingsPersistFailed, {
           id: change.id,
           message: err instanceof Error ? err.message : String(err)
@@ -26727,7 +27408,7 @@ function hasExtension(handle, extensionId) {
 }
 
 // server/routes/preferences.ts
-import { HTTPException as HTTPException10 } from "hono/http-exception";
+import { HTTPException as HTTPException11 } from "hono/http-exception";
 function registerPreferencesRoute(app, _deps) {
   app.get("/api/preferences", (c) => {
     return c.json(buildEnvelope());
@@ -26759,7 +27440,7 @@ function applyPatch(body) {
       applyTelemetryPatch(body.telemetry);
     }
   } catch (err) {
-    throw new HTTPException10(400, {
+    throw new HTTPException11(400, {
       message: tx(SERVER_TEXTS.preferencesPersistFailed, {
         message: formatErrorMessage(err)
       })
@@ -26818,14 +27499,14 @@ var parsePatchBody2 = makeBodyValidator(PATCH_BODY_SCHEMA, {
 });
 
 // server/routes/project-ignore.ts
-import { HTTPException as HTTPException11 } from "hono/http-exception";
+import { HTTPException as HTTPException12 } from "hono/http-exception";
 
 // server/util/skillmapignore-io.ts
 import { existsSync as existsSync27, readFileSync as readFileSync18, writeFileSync as writeFileSync2 } from "fs";
-import { resolve as resolve35 } from "path";
+import { resolve as resolve38 } from "path";
 var IGNORE_FILENAME2 = ".skillmapignore";
 function readPatterns(cwd) {
-  const path = resolve35(cwd, IGNORE_FILENAME2);
+  const path = resolve38(cwd, IGNORE_FILENAME2);
   if (!existsSync27(path)) return [];
   let raw;
   try {
@@ -26836,7 +27517,7 @@ function readPatterns(cwd) {
   return raw.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0 && !l.startsWith("#"));
 }
 function writePatterns(cwd, nextPatterns) {
-  const path = resolve35(cwd, IGNORE_FILENAME2);
+  const path = resolve38(cwd, IGNORE_FILENAME2);
   const prior = existsSync27(path) ? safeRead(path) : "";
   const content = buildContent(prior, nextPatterns);
   writeFileSync2(path, content, "utf8");
@@ -26905,12 +27586,12 @@ async function applyPatch2(deps, body) {
   for (const raw of body.patterns) {
     const t = raw.trim();
     if (t.length === 0) {
-      throw new HTTPException11(400, {
+      throw new HTTPException12(400, {
         message: SERVER_TEXTS.projectIgnorePatternEmpty
       });
     }
     if (seen.has(t)) {
-      throw new HTTPException11(400, {
+      throw new HTTPException12(400, {
         message: tx(SERVER_TEXTS.projectIgnorePatternDuplicate, { pattern: t })
       });
     }
@@ -26921,7 +27602,7 @@ async function applyPatch2(deps, body) {
   try {
     writePatterns(cwd, trimmed);
   } catch (err) {
-    throw new HTTPException11(400, {
+    throw new HTTPException12(400, {
       message: tx(SERVER_TEXTS.projectIgnorePersistFailed, {
         message: formatErrorMessage(err)
       })
@@ -26999,7 +27680,7 @@ var parsePatchBody3 = makeBodyValidator(PATCH_BODY_SCHEMA2, {
 
 // server/routes/project-preferences.ts
 import { statSync as statSync9 } from "fs";
-import { HTTPException as HTTPException12 } from "hono/http-exception";
+import { HTTPException as HTTPException13 } from "hono/http-exception";
 function registerProjectPreferencesRoute(app, deps) {
   app.get("/api/project-preferences", (c) => {
     return c.json(buildEnvelope3(deps));
@@ -27037,7 +27718,7 @@ function applyScanWrites(body, cwd) {
   if (writes.length === 0) return { attempted: false, mutated: false };
   const missingPaths = collectMissingPaths(writes, cwd);
   if (missingPaths.length > 0) {
-    throw new HTTPException12(400, {
+    throw new HTTPException13(400, {
       message: tx(SERVER_TEXTS.projectPrefsPathNotFound, {
         paths: missingPaths.join(", ")
       })
@@ -27046,7 +27727,7 @@ function applyScanWrites(body, cwd) {
   const exposures = writes.map((w) => projectPathExposure({ key: w.key, value: w.value, cwd })).filter((e) => e.expandsSurface);
   if (exposures.length > 0 && body.confirm !== true) {
     const exposed = exposures.flatMap((e) => e.exposedPaths);
-    throw new HTTPException12(412, {
+    throw new HTTPException13(412, {
       message: tx(SERVER_TEXTS.projectPrefsConfirmRequired, {
         paths: exposed.join(", ")
       })
@@ -27064,7 +27745,7 @@ function writeSidecarWritersPolicy(value, cwd) {
   try {
     writeConfigValue("allowSidecarWriters", value, { target: "project", cwd });
   } catch (err) {
-    throw new HTTPException12(400, {
+    throw new HTTPException13(400, {
       message: tx(SERVER_TEXTS.projectPrefsPersistFailed, {
         key: "allowSidecarWriters",
         message: formatErrorMessage(err)
@@ -27115,7 +27796,7 @@ function runWrite(w, cwd) {
   try {
     writeConfigValue(w.key, w.value, { target: "project-local", cwd });
   } catch (err) {
-    throw new HTTPException12(400, {
+    throw new HTTPException13(400, {
       message: tx(SERVER_TEXTS.projectPrefsPersistFailed, {
         key: w.key,
         message: formatErrorMessage(err)
@@ -27217,7 +27898,7 @@ var parsePatchBody4 = makeBodyValidator(PATCH_BODY_SCHEMA3, {
 
 // server/routes/active-provider.ts
 import { existsSync as existsSync28 } from "fs";
-import { HTTPException as HTTPException13 } from "hono/http-exception";
+import { HTTPException as HTTPException14 } from "hono/http-exception";
 function registerActiveProviderRoute(app, deps) {
   app.get("/api/active-provider", async (c) => {
     return c.json(await buildEnvelope4(deps));
@@ -27258,7 +27939,7 @@ function applyLensSwitch(deps, newValue) {
   try {
     writeConfigValue("activeProvider", newValue, { target: "project", cwd });
   } catch (err) {
-    throw new HTTPException13(400, {
+    throw new HTTPException14(400, {
       message: tx(SERVER_TEXTS.activeProviderPersistFailed, {
         message: formatErrorMessage(err)
       })
@@ -27294,11 +27975,11 @@ var parsePatchBody5 = makeBodyValidator(PATCH_BODY_SCHEMA4, {
 });
 
 // server/routes/actions.ts
-import { HTTPException as HTTPException15 } from "hono/http-exception";
-import { resolve as resolve36 } from "path";
+import { HTTPException as HTTPException16 } from "hono/http-exception";
+import { resolve as resolve39 } from "path";
 
 // server/routes/node-loader.ts
-import { HTTPException as HTTPException14 } from "hono/http-exception";
+import { HTTPException as HTTPException15 } from "hono/http-exception";
 async function loadNode(deps, nodePath) {
   const persisted = await tryWithSqlite(
     { databasePath: deps.options.dbPath, autoBackup: false },
@@ -27306,7 +27987,7 @@ async function loadNode(deps, nodePath) {
   );
   const node = persisted?.nodes.find((n) => n.path === nodePath);
   if (!node) {
-    throw new HTTPException14(404, {
+    throw new HTTPException15(404, {
       message: tx(SERVER_TEXTS.nodeNotFound, { path: sanitizeForTerminal(nodePath) })
     });
   }
@@ -27355,9 +28036,9 @@ function registerActionsRoutes(app, deps) {
     let absPath;
     try {
       assertContained(deps.runtimeContext.cwd, node.path);
-      absPath = resolve36(deps.runtimeContext.cwd, node.path);
+      absPath = resolve39(deps.runtimeContext.cwd, node.path);
     } catch (err) {
-      throw new HTTPException15(400, { message: formatErrorMessage(err) });
+      throw new HTTPException16(400, { message: formatErrorMessage(err) });
     }
     const result = invokeAction(action, absPath, node, body, deps.runtimeContext.cwd);
     const report = result.report;
@@ -27397,7 +28078,7 @@ function registerActionsRoutes(app, deps) {
 }
 function parseSegment(value, name) {
   if (!QUALIFIED_ID_SEGMENT2.test(value)) {
-    throw new HTTPException15(400, {
+    throw new HTTPException16(400, {
       message: tx(SERVER_TEXTS.qualifiedIdMalformed, {
         name,
         value: sanitizeForTerminal(value)
@@ -27410,7 +28091,7 @@ function resolveInvokableAction(kernel, actionId) {
   const ext = kernel.registry.get("action", actionId);
   const action = ext;
   if (!action || typeof action.invoke !== "function") {
-    throw new HTTPException15(404, {
+    throw new HTTPException16(404, {
       message: tx(SERVER_TEXTS.actionUnknown, { actionId: sanitizeForTerminal(actionId) })
     });
   }
@@ -27442,7 +28123,7 @@ async function materializeWrites(writes, body, cwd) {
   } catch (err) {
     if (err instanceof EConsentRequiredError) throw err;
     if (err instanceof ESidecarWritersForbiddenError) throw err;
-    throw new HTTPException15(500, { message: formatErrorMessage(err) });
+    throw new HTTPException16(500, { message: formatErrorMessage(err) });
   }
 }
 function buildEnvelope5(actionId, nodePath, report, startedAt) {
@@ -27455,7 +28136,7 @@ function buildEnvelope5(actionId, nodePath, report, startedAt) {
 }
 
 // server/routes/scan.ts
-import { HTTPException as HTTPException16 } from "hono/http-exception";
+import { HTTPException as HTTPException17 } from "hono/http-exception";
 
 // server/scan-mutex.ts
 var inFlight = null;
@@ -27463,14 +28144,14 @@ async function withScanMutex(fn) {
   if (inFlight !== null) {
     throw new ScanBusyError();
   }
-  let resolve40;
+  let resolve43;
   inFlight = new Promise((r) => {
-    resolve40 = r;
+    resolve43 = r;
   });
   try {
     return await fn();
   } finally {
-    resolve40();
+    resolve43();
     inFlight = null;
   }
 }
@@ -27491,6 +28172,99 @@ function noopWritable() {
   });
 }
 
+// core/runtime/i18n/scan-spinner.texts.ts
+var SCAN_SPINNER_TEXTS = {
+  /**
+   * Animated (TTY) / single-line (non-TTY) label shown while a batch is
+   * in flight. No em dash, the trailing ellipsis is three ASCII dots.
+   */
+  scanning: "Scanning...",
+  /**
+   * Headline word for the completion line, framed by the caller as
+   * `{{glyph}} {{updated}}` (+ optional ` · {{stats}}` segment).
+   */
+  updated: "Map updated",
+  /**
+   * Optional stats segment appended after the headline when the batch
+   * outcome carried `nodesCount` / `durationMs`. The caller composes
+   * whichever of `{{nodes}}` / `{{durationMs}}` were defined and joins
+   * them with the middle-dot separator before passing the finished line.
+   */
+  nodesSegment: "{{nodes}} nodes",
+  durationSegment: "{{durationMs}}ms"
+};
+
+// core/runtime/scan-spinner.ts
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var FRAME_INTERVAL_MS = 80;
+var CLEAR_LINE = "\r\x1B[2K";
+var ESC_CYAN = "\x1B[36m";
+var ESC_GREEN = "\x1B[32m";
+var ESC_RESET2 = "\x1B[0m";
+function createScanSpinner(stream, opts = {}) {
+  const colorEnabled = opts.colorEnabled === true;
+  const label = opts.label ?? SCAN_SPINNER_TEXTS.scanning;
+  const isTty = stream.isTTY === true;
+  let active2 = false;
+  let frameIndex = 0;
+  let timer = null;
+  const safeWrite = (chunk) => {
+    try {
+      stream.write(chunk);
+    } catch {
+    }
+  };
+  const tintFrame = (frame) => colorEnabled ? `${ESC_CYAN}${frame}${ESC_RESET2}` : frame;
+  const drawFrame = () => {
+    const frame = FRAMES[frameIndex % FRAMES.length];
+    frameIndex += 1;
+    safeWrite(`${CLEAR_LINE}${tintFrame(frame)} ${label}`);
+  };
+  const start = () => {
+    if (active2) return;
+    active2 = true;
+    if (!isTty) {
+      safeWrite(`${label}
+`);
+      return;
+    }
+    frameIndex = 0;
+    drawFrame();
+    timer = setInterval(drawFrame, FRAME_INTERVAL_MS);
+    timer.unref?.();
+  };
+  const buildStatsSegment = (stats) => {
+    const segments = [];
+    if (stats.nodesCount !== void 0) {
+      segments.push(tx(SCAN_SPINNER_TEXTS.nodesSegment, { nodes: stats.nodesCount }));
+    }
+    if (stats.durationMs !== void 0) {
+      segments.push(tx(SCAN_SPINNER_TEXTS.durationSegment, { durationMs: stats.durationMs }));
+    }
+    return segments.length > 0 ? ` \xB7 ${segments.join(" \xB7 ")}` : "";
+  };
+  const stop = (stats) => {
+    if (!active2) return;
+    active2 = false;
+    if (timer !== null) {
+      clearInterval(timer);
+      timer = null;
+    }
+    if (isTty) safeWrite(CLEAR_LINE);
+    const check = colorEnabled ? `${ESC_GREEN}\u2713${ESC_RESET2}` : "\u2713";
+    const statsSegment = stats ? buildStatsSegment(stats) : "";
+    safeWrite(`${check} ${SCAN_SPINNER_TEXTS.updated}${statsSegment}
+`);
+  };
+  return {
+    start,
+    stop,
+    get active() {
+      return active2;
+    }
+  };
+}
+
 // server/events.ts
 function buildWatcherStartedEvent(data) {
   return {
@@ -27512,6 +28286,9 @@ function buildWatcherErrorEvent(data) {
 // server/watcher.ts
 function createWatcherService(opts) {
   let currentRuntime = null;
+  const spinner = opts.scanProgress ? createScanSpinner(opts.scanProgress.stream, {
+    colorEnabled: opts.scanProgress.colorEnabled
+  }) : void 0;
   const buildRuntimeOpts = () => {
     const runtimeOpts = {
       dbPath: opts.options.dbPath,
@@ -27527,7 +28304,16 @@ function createWatcherService(opts) {
       subscribeBeforeInitial: true,
       failOnInitialBatchError: false,
       events: {
+        // Light the "scanning" indicator the moment a batch begins (file
+        // save to re-scan). No-op when no `scanProgress` was passed.
+        onBatchStart: () => spinner?.start(),
         onBatch: (outcome) => {
+          spinner?.stop(
+            outcome.kind === "ok" ? {
+              nodesCount: outcome.result.stats.nodesCount,
+              durationMs: outcome.result.stats.durationMs
+            } : void 0
+          );
           if (outcome.kind === "error") {
             log.warn(
               tx(SERVER_TEXTS.watcherBatchFailed, {
@@ -27573,6 +28359,9 @@ function createWatcherService(opts) {
     if (opts.debounceMsOverride !== void 0) {
       runtimeOpts.debounceMsOverride = opts.debounceMsOverride;
     }
+    if (opts.options.maxScan !== void 0) {
+      runtimeOpts.maxScanOverride = opts.options.maxScan;
+    }
     if (opts.options.maxNodes !== void 0) {
       runtimeOpts.maxNodesOverride = opts.options.maxNodes;
     }
@@ -27628,13 +28417,16 @@ function registerScanRoute(app, deps) {
     if (parseBooleanFlag(c.req.query("fresh"))) {
       return c.json(await runFreshScan(deps));
     }
+    if (parseBooleanFlag(c.req.query("meta"))) {
+      return c.json(await loadPersistedScanMeta(deps));
+    }
     return c.json(await loadPersistedScan(deps));
   });
   app.post("/api/scan", async (c) => runPersistedScan(c, deps));
 }
 async function runPersistedScan(c, deps) {
   if (deps.options.noBuiltIns || deps.options.noPlugins) {
-    throw new HTTPException16(400, { message: SERVER_TEXTS.scanPostRequiresFullPipeline });
+    throw new HTTPException17(400, { message: SERVER_TEXTS.scanPostRequiresFullPipeline });
   }
   const dbExists = await tryWithSqlite(
     { databasePath: deps.options.dbPath, autoBackup: false },
@@ -27665,13 +28457,15 @@ async function runPersistedScan(c, deps) {
         // the operator via the Settings UI (PATCH /api/active-provider)
         // before the scan, not via interactive prompt here.
         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.
+        // `--max-scan` (walk ceiling) and `--max-nodes` (render cap)
+        // from the `sm serve` invocation (or the bare `sm --max-scan
+        // <N>` / `sm --max-nodes <N>` shortcut) flow through to every
+        // scan the BFF runs so both overrides are honoured end-to-end.
+        ...deps.options.maxScan !== void 0 ? { maxScan: deps.options.maxScan } : {},
         ...deps.options.maxNodes !== void 0 ? { maxNodes: deps.options.maxNodes } : {}
       });
       if (outcome.kind !== "ok") {
-        throw new HTTPException16(500, {
+        throw new HTTPException17(500, {
           message: outcome.kind === "guard-trip" ? tx(SERVER_TEXTS.scanGuardTrip, { existing: outcome.existing }) : outcome.message
         });
       }
@@ -27691,6 +28485,20 @@ async function buildBffResolverOverride(deps) {
     fallbackResolver: deps.pluginRuntime.resolveEnabled
   });
 }
+async function loadPersistedScanMeta(deps) {
+  const opened = await tryWithSqlite(
+    {
+      databasePath: deps.options.dbPath,
+      autoBackup: false,
+      versionCheck: { currentVersion: VERSION, printer: bffVersionCheckPrinter }
+    },
+    async (adapter) => adapter.scans.loadMeta()
+  );
+  if (opened === null) {
+    return emptyScanResult();
+  }
+  return opened;
+}
 async function loadPersistedScan(deps) {
   const opened = await tryWithSqlite(
     {
@@ -27719,7 +28527,7 @@ async function loadPersistedScan(deps) {
         if (list) list.push(r);
         else byPath3.set(r.nodePath, [r]);
       }
-      const tagsByPath = groupTagsByPath2(tagRows);
+      const tagsByPath = groupTagsByPath3(tagRows);
       return { loaded, favSet, contribByPath: byPath3, tagsByPath };
     }
   );
@@ -27736,7 +28544,7 @@ async function loadPersistedScan(deps) {
     }))
   };
 }
-function groupTagsByPath2(rows) {
+function groupTagsByPath3(rows) {
   const buckets = /* @__PURE__ */ new Map();
   for (const r of rows) {
     const set = buckets.get(r.nodePath);
@@ -27749,7 +28557,7 @@ function groupTagsByPath2(rows) {
 }
 async function runFreshScan(deps) {
   if (deps.options.noBuiltIns || deps.options.noPlugins) {
-    throw new HTTPException16(400, { message: SERVER_TEXTS.freshScanRequiresPipeline });
+    throw new HTTPException17(400, { message: SERVER_TEXTS.freshScanRequiresPipeline });
   }
   const resolveEnabledOverride = await buildBffResolverOverride(deps);
   const outcome = await runScanForCommand({
@@ -27779,12 +28587,14 @@ async function runFreshScan(deps) {
     // BFF has no TTY; ambiguous activeProvider is the operator's
     // problem to resolve via the Settings UI, not via prompt here.
     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.
+    // Carry `--max-scan` (walk ceiling) and `--max-nodes` (render cap)
+    // from `sm serve` into the fresh-scan path too so a UI-driven
+    // refresh honours the same knobs as the watcher.
+    ...deps.options.maxScan !== void 0 ? { maxScan: deps.options.maxScan } : {},
     ...deps.options.maxNodes !== void 0 ? { maxNodes: deps.options.maxNodes } : {}
   });
   if (outcome.kind !== "ok") {
-    throw new HTTPException16(500, {
+    throw new HTTPException17(500, {
       message: outcome.kind === "guard-trip" ? tx(SERVER_TEXTS.freshScanGuardTrip, { existing: outcome.existing }) : outcome.message
     });
   }
@@ -27810,12 +28620,14 @@ 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,
+    // Surface the design defaults so the SPA reads the same field shape
+    // on cold boot as on populated DBs. 50000 mirrors `scan.maxScan`
+    // (the walk ceiling) and 256 mirrors `scan.maxNodes` (the render
+    // cap), both from `src/config/defaults.json`. A real scan
+    // overwrites these with the live values on next run.
+    scanCeiling: 5e4,
+    scanTruncated: false,
+    maxRenderNodes: 256,
     nodes: [],
     links: [],
     issues: [],
@@ -27996,13 +28808,13 @@ function attachBroadcasterRoute(app, broadcaster) {
 
 // server/app.ts
 var BODY_LIMIT_BYTES = 1024 * 1024;
-var DbMissingError = class extends HTTPException17 {
+var DbMissingError = class extends HTTPException18 {
   constructor(message) {
     super(500, { message });
     this.name = "DbMissingError";
   }
 };
-var BulkValidationError = class extends HTTPException17 {
+var BulkValidationError = class extends HTTPException18 {
   id;
   code;
   constructor(init) {
@@ -28012,7 +28824,7 @@ var BulkValidationError = class extends HTTPException17 {
     this.code = init.code;
   }
 };
-var LoopbackGateError = class extends HTTPException17 {
+var LoopbackGateError = class extends HTTPException18 {
   code;
   constructor(init) {
     super(403, { message: init.message });
@@ -28020,7 +28832,7 @@ var LoopbackGateError = class extends HTTPException17 {
     this.code = init.code;
   }
 };
-var ConflictError = class extends HTTPException17 {
+var ConflictError = class extends HTTPException18 {
   code;
   constructor(init) {
     super(409, { message: init.message });
@@ -28028,7 +28840,7 @@ var ConflictError = class extends HTTPException17 {
     this.code = init.code;
   }
 };
-var ActionRefusedError = class extends HTTPException17 {
+var ActionRefusedError = class extends HTTPException18 {
   /** Refusal code: the report's `reason` when present, else `'action-refused'`. */
   code;
   details;
@@ -28056,7 +28868,7 @@ function createApp(deps) {
     bodyLimit({
       maxSize: BODY_LIMIT_BYTES,
       onError: () => {
-        throw new HTTPException17(413, { message: tx(SERVER_TEXTS.bodyTooLarge, { maxBytes: String(BODY_LIMIT_BYTES) }) });
+        throw new HTTPException18(413, { message: tx(SERVER_TEXTS.bodyTooLarge, { maxBytes: String(BODY_LIMIT_BYTES) }) });
       }
     })
   );
@@ -28089,6 +28901,8 @@ function createApp(deps) {
   registerNodesRoutes(app, routeDeps);
   registerLinksRoute(app, routeDeps);
   registerIssuesRoute(app, routeDeps);
+  registerFoldersRoute(app, routeDeps);
+  registerBranchRoute(app, routeDeps);
   registerGraphRoute(app, routeDeps);
   registerConfigRoute(app, routeDeps);
   registerPluginsRoute(app, routeDeps);
@@ -28102,7 +28916,7 @@ function createApp(deps) {
   registerActiveProviderRoute(app, routeDeps);
   registerProjectIgnoreRoute(app, routeDeps);
   app.all("/api/*", (c) => {
-    throw new HTTPException17(404, {
+    throw new HTTPException18(404, {
       message: tx(SERVER_TEXTS.unknownApiEndpoint, { path: sanitizeForTerminal(c.req.path) })
     });
   });
@@ -28110,7 +28924,7 @@ function createApp(deps) {
   app.use("*", createStaticHandler({ uiDist: deps.options.uiDist, noUi: deps.options.noUi }));
   app.get("*", createSpaFallback({ uiDist: deps.options.uiDist, noUi: deps.options.noUi }));
   app.notFound((c) => {
-    throw new HTTPException17(404, {
+    throw new HTTPException18(404, {
       message: tx(SERVER_TEXTS.unknownPath, { path: sanitizeForTerminal(c.req.path) })
     });
   });
@@ -28163,7 +28977,7 @@ function formatError2(err, c) {
   }
   const conflict = formatConflict(err, c);
   if (conflict) return conflict;
-  if (err instanceof HTTPException17) {
+  if (err instanceof HTTPException18) {
     const status = err.status;
     const envelope = {
       ok: false,
@@ -28509,6 +29323,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 maxScanError = validateMaxScan(input.maxScan);
+  if (maxScanError !== null) return { ok: false, error: maxScanError };
   const maxNodesError = validateMaxNodes(input.maxNodes);
   if (maxNodesError !== null) return { ok: false, error: maxNodesError };
   const noUiError = validateNoUi(filled.noUi, filled.uiDist);
@@ -28528,6 +29344,9 @@ function validateServerOptions(input) {
   if (input.watcherDebounceMs !== void 0) {
     options.watcherDebounceMs = input.watcherDebounceMs;
   }
+  if (input.maxScan !== void 0) {
+    options.maxScan = input.maxScan;
+  }
   if (input.maxNodes !== void 0) {
     options.maxNodes = input.maxNodes;
   }
@@ -28596,6 +29415,17 @@ function validateWatcherDebounce(value) {
   }
   return null;
 }
+function validateMaxScan(value) {
+  if (value === void 0) return null;
+  if (!Number.isInteger(value) || value < 1) {
+    return {
+      code: "max-scan-invalid",
+      message: `--max-scan must be an integer >= 1 (got ${value})`,
+      value: String(value)
+    };
+  }
+  return null;
+}
 function validateMaxNodes(value) {
   if (value === void 0) return null;
   if (!Number.isInteger(value) || value < 1) {
@@ -28620,7 +29450,7 @@ function validateNoUi(noUi, uiDist) {
 
 // server/paths.ts
 import { existsSync as existsSync30, statSync as statSync10 } from "fs";
-import { dirname as dirname19, isAbsolute as isAbsolute11, join as join20, resolve as resolve37 } from "path";
+import { dirname as dirname19, isAbsolute as isAbsolute14, join as join20, resolve as resolve40 } from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
 var DEFAULT_UI_REL = join20("ui", "dist", "ui", "browser");
 var PACKAGE_UI_REL = "ui";
@@ -28631,7 +29461,7 @@ function resolveDefaultUiDist(ctx) {
   return walkUpForUi(ctx.cwd);
 }
 function resolveExplicitUiDist(ctx, raw) {
-  return isAbsolute11(raw) ? raw : resolve37(ctx.cwd, raw);
+  return isAbsolute14(raw) ? raw : resolve40(ctx.cwd, raw);
 }
 function isUiBundleDir(path) {
   if (!existsSync30(path)) return false;
@@ -28665,7 +29495,7 @@ function resolvePackageBundledUiFrom(here) {
   return null;
 }
 function walkUpForUi(startDir) {
-  let current = resolve37(startDir);
+  let current = resolve40(startDir);
   for (let i = 0; i < 64; i++) {
     const candidate = join20(current, DEFAULT_UI_REL);
     if (isUiBundleDir(candidate)) return candidate;
@@ -28711,6 +29541,7 @@ async function createServer(options, extra = {}) {
       broadcaster
     };
     if (debounce !== void 0) svcOpts.debounceMsOverride = debounce;
+    if (extra.scanProgress) svcOpts.scanProgress = extra.scanProgress;
     const candidate = createWatcherService(svcOpts);
     try {
       await candidate.start();
@@ -28904,6 +29735,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-scan <N>`. Same shape as
+   * the watcher-debounce template family.
+   */
+  maxScanInvalid: "{{glyph}}  sm serve: --max-scan must be an integer >= 1 (got {{value}}).\n   {{hint}}\n",
+  maxScanInvalidHint: "Pass a positive integer, e.g. --max-scan 50000.",
   /**
    * §3.1b error block for an invalid `--max-nodes <N>`. Same shape as
    * the watcher-debounce template family.
@@ -28959,7 +29796,7 @@ var SERVE_TEXTS = {
 };
 
 // cli/util/serve-banner.ts
-import { relative as relative7, isAbsolute as isAbsolute12 } from "path";
+import { relative as relative8, isAbsolute as isAbsolute15 } from "path";
 var ESC2 = {
   reset: "\x1B[0m",
   bold: "\x1B[1m",
@@ -29106,9 +29943,9 @@ function resolveAnsi(colorEnabled) {
 }
 function formatDbPath(dbPath, cwd) {
   const safe = sanitizeForTerminal(dbPath);
-  if (!isAbsolute12(safe)) return safe;
-  const rel = relative7(cwd, safe);
-  if (rel === "" || rel.startsWith("..") || isAbsolute12(rel)) {
+  if (!isAbsolute15(safe)) return safe;
+  const rel = relative8(cwd, safe);
+  if (rel === "" || rel.startsWith("..") || isAbsolute15(rel)) {
     return safe;
   }
   return rel;
@@ -29189,9 +30026,13 @@ 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 = Option32.String("--watcher-debounce-ms", { required: false, hidden: true });
+  maxScan = Option32.String("--max-scan", {
+    required: false,
+    description: "Per-invocation override of scan.maxScan (default 50000), the WALK-INTAKE ceiling. The scan walks, parses, analyzes, and reference-validates the full corpus up to this number. Bidirectional: raises OR lowers the ceiling. 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`."
+  });
   maxNodes = Option32.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`."
+    description: "Per-invocation override of scan.maxNodes (default 256), the MAP RENDER cap (pure metadata): it does NOT bound the scan, only how many nodes the graph view projects onto the canvas. Bidirectional: raises OR lowers the render cap. 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.
@@ -29271,6 +30112,17 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
+    const maxScanResult = parseMaxScan(this.maxScan);
+    if (!maxScanResult.ok) {
+      this.printer.info(
+        tx(SERVE_TEXTS.maxScanInvalid, {
+          glyph: errGlyph,
+          value: sanitizeForTerminal(maxScanResult.value),
+          hint: stderrAnsi.dim(SERVE_TEXTS.maxScanInvalidHint)
+        })
+      );
+      return ExitCode.Error;
+    }
     const maxNodesResult = parseMaxNodes(this.maxNodes);
     if (!maxNodesResult.ok) {
       this.printer.info(
@@ -29295,6 +30147,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 (maxScanResult.value !== void 0) input.maxScan = maxScanResult.value;
     if (maxNodesResult.value !== void 0) input.maxNodes = maxNodesResult.value;
     const validation = validateServerOptions(input);
     if (!validation.ok) {
@@ -29303,10 +30156,19 @@ var ServeCommand = class extends SmCommand {
     }
     const driftAbort = await this.#rebuildOnDrift(dbPath, stderrAnsi, warnGlyph);
     if (driftAbort !== null) return driftAbort;
+    const stderr = this.context.stderr;
+    const isTTY = stderr.isTTY === true;
+    const colorEnabled = resolveColorEnabled({
+      isTTY,
+      noColorFlag: this.noColor,
+      env: process.env
+    });
     await initSentryBff(VERSION);
     let handle;
     try {
-      handle = await createServer(validation.options);
+      handle = await createServer(validation.options, {
+        scanProgress: { stream: stderr, colorEnabled }
+      });
     } catch (err) {
       const message = formatErrorMessage(err);
       this.printer.info(
@@ -29319,13 +30181,6 @@ var ServeCommand = class extends SmCommand {
       );
       return ExitCode.Error;
     }
-    const stderr = this.context.stderr;
-    const isTTY = stderr.isTTY === true;
-    const colorEnabled = resolveColorEnabled({
-      isTTY,
-      noColorFlag: this.noColor,
-      env: process.env
-    });
     let referencePaths = [];
     try {
       const cfg = loadConfig({ cwd: runtimeCtx.cwd }).effective;
@@ -29397,6 +30252,12 @@ function parseDebounce(raw) {
   if (parsed === null) return { ok: false, value: raw };
   return { ok: true, value: parsed };
 }
+function parseMaxScan(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 parseMaxNodes(raw) {
   if (raw === void 0) return { ok: true, value: void 0 };
   const n = Number(raw);
@@ -29455,6 +30316,12 @@ function formatValidationError(err, ansi) {
         value: sanitizeForTerminal(err.value),
         hint: ansi.dim(SERVE_TEXTS.watcherDebounceInvalidHint)
       });
+    case "max-scan-invalid":
+      return tx(SERVE_TEXTS.maxScanInvalid, {
+        glyph: errGlyph,
+        value: sanitizeForTerminal(err.value),
+        hint: ansi.dim(SERVE_TEXTS.maxScanInvalidHint)
+      });
     case "max-nodes-invalid":
       return tx(SERVE_TEXTS.maxNodesInvalid, {
         glyph: errGlyph,
@@ -29841,7 +30708,7 @@ function rankConfidenceForGrouping(c) {
 
 // cli/commands/sidecar.ts
 import { unlink as unlink3 } from "fs/promises";
-import { resolve as resolve38 } from "path";
+import { resolve as resolve41 } from "path";
 import { Command as Command36, Option as Option34 } from "clipanion";
 
 // cli/i18n/sidecar.texts.ts
@@ -29999,7 +30866,7 @@ var SidecarRefreshCommand = class extends SmCommand {
     let absPath;
     try {
       assertContained(ctx.cwd, node.path);
-      absPath = resolve38(ctx.cwd, node.path);
+      absPath = resolve41(ctx.cwd, node.path);
     } catch (err) {
       this.printer.error(
         tx(SIDECAR_TEXTS.refreshFailed, { glyph: errGlyph, message: formatErrorMessage(err) })
@@ -30283,7 +31150,7 @@ var SidecarAnnotateCommand = class extends SmCommand {
     let absPath;
     try {
       assertContained(ctx.cwd, node.path);
-      absPath = resolve38(ctx.cwd, node.path);
+      absPath = resolve41(ctx.cwd, node.path);
     } catch (err) {
       this.printer.error(
         tx(SIDECAR_TEXTS.annotateFailed, { glyph: errGlyph, message: formatErrorMessage(err) })
@@ -30535,7 +31402,7 @@ var STUB_COMMANDS = [
 
 // cli/commands/tutorial.ts
 import { cpSync as cpSync2, existsSync as existsSync32, mkdirSync as mkdirSync6, readdirSync as readdirSync10, rmSync as rmSync2, statSync as statSync11 } from "fs";
-import { dirname as dirname20, join as join21, resolve as resolve39 } from "path";
+import { dirname as dirname20, join as join21, resolve as resolve42 } from "path";
 import { createInterface as createInterface5 } from "readline";
 import { fileURLToPath as fileURLToPath7 } from "url";
 import { Command as Command38, Option as Option36 } from "clipanion";
@@ -30881,11 +31748,11 @@ function resolveSkillSourceDir() {
   const here = dirname20(fileURLToPath7(import.meta.url));
   const candidates = [
     // dev: src/cli/commands/ → repo-root .claude/skills/sm-tutorial/
-    resolve39(here, "../../..", SKILL_SOURCE_DIR),
+    resolve42(here, "../../..", SKILL_SOURCE_DIR),
     // bundled: dist/cli.js → dist/cli/tutorial/sm-tutorial (sibling)
-    resolve39(here, "cli/tutorial", SKILL_SLUG),
+    resolve42(here, "cli/tutorial", SKILL_SLUG),
     // bundled fallback: any-depth → cli/tutorial/sm-tutorial
-    resolve39(here, "../cli/tutorial", SKILL_SLUG)
+    resolve42(here, "../cli/tutorial", SKILL_SLUG)
   ];
   for (const candidate of candidates) {
     if (existsSync32(candidate) && statSync11(candidate).isDirectory()) {
@@ -31110,4 +31977,4 @@ function resolveBareDefault() {
   process.exit(ExitCode.Error);
 }
 //# sourceMappingURL=cli.js.map
-//# debugId=d6e5d903-0942-5718-94b3-53a96de15b21
+//# debugId=d7ccbbda-dc56-582c-966a-4822e4bdcd83