@polycode-projects/seonix 0.6.0 → 0.7.0

package/bin/cli.mjs

@@ -13,6 +13,10 @@
 //   seonix cli index_repository '{"multi_root":"<abs-dir>"}' → estate discovery: every immediate
 //     child directory carrying a .git (dir or file) is indexed as a repo, merged into
 //     <multi_root>/.seonix/ (discovered/skipped counts logged to stderr)
+//   seonix cli sync '{"multi_root":"<abs-dir>"}' → incrementally re-index the estate: fingerprint
+//     every child repo (git/gitparent/plain), re-extract ONLY the changed ones (per-repo cache in
+//     .seonix/cache/), one union rebuild = exact full-re-index. Unchanged-everything = byte-stable
+//     no-op. Same path as index_repository with "sync":true on a multi_root. Writes .seonix/manifest.json
 //   seonix cli digest '{"repo_path":"<abs>","modules":[…]}' → architecture map + per-module
 //                                                           context bundles to stdout (no-MCP arm)
 //   seonix cli digest '{"repo_path":"<abs>","query":"<free text>"}' → same, but auto-locates +
@@ -36,12 +40,19 @@
 // cwd = that repo) loads it by default. No flags, no config files.
 
 import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
 import { startServer } from "../src/server.mjs";
 import { dispatchTool, buildContextBundle } from "../src/server.mjs";
-import { indexRepository, indexRepositories, discoverRepos } from "../src/extract.mjs";
+import { indexRepository, indexRepositories, discoverRepos, syncRepositories } from "../src/extract.mjs";
+import { renderSummaryMd } from "../src/summary.mjs";
 import { loadConfig, DEFAULT_GRAPH_REL } from "../src/config.mjs";
 import * as source from "../src/source.mjs";
 import { parseEntities, renderSearch, rankModulesByProximity, searchModulesRanked, selectRankedModules, DEFAULT_SCORE_GAP } from "../src/codegraph.mjs";
+import { loadTomlConfig, normalizeConfig, mergeEffective, CONFIG_FILE } from "../src/toml-config.mjs";
+import { compileGlobs } from "../src/walk.mjs";
+import { createTelemetry } from "../src/telemetry.mjs";
 
 /** Build a config pointed at a specific repo's artifact (for `cli` sub-commands that
  *  take a repo_path), or fall back to the cwd-derived default. */
@@ -56,6 +67,73 @@ function parsePayload(payload) {
   catch { return null; }
 }
 
+/** Load a repo's seonix.toml as a normalized config, or null. Returns null IMMEDIATELY when
+ *  `args.config === false` (the BENCH-IMMUNITY flag — an arm's index/locate/digest must NEVER read a
+ *  subject repo's seonix.toml) OR when no seonix.toml exists. So on the bench path, and with no
+ *  seonix.toml present, every command is byte-identical to today (existsSync short-circuits before any
+ *  read). Sits next to configFor. Async: normalizeConfig may read a `repositories` file. */
+async function tomlFor(repoPath, args = {}) {
+  if (args && args.config === false) return null;
+  const dir = repoPath || process.cwd();
+  if (!existsSync(join(dir, CONFIG_FILE))) return null; // absent → shipped defaults, byte-identical
+  const raw = await loadTomlConfig(dir); // present-but-invalid THROWS (security: never swallow a misparse)
+  if (!raw) return null;
+  return await normalizeConfig(raw, { configDir: dir });
+}
+
+// The unwired-key warning is emitted at most once per process (= once per run).
+let _warnedUnwired = false;
+/** Warn once for every seonix.toml key normalizeConfig recognized but no consumer wires yet. */
+function warnUnwired(toml) {
+  if (_warnedUnwired || !toml || !Array.isArray(toml.unwired) || !toml.unwired.length) return;
+  _warnedUnwired = true;
+  for (const k of toml.unwired) {
+    process.stderr.write(`seonix: seonix.toml key ${k} is recognized but not yet implemented — ignored\n`);
+  }
+}
+
+/** Shipped defaults for the tune knobs — the `defaults` source of `config --effective` and the
+ *  digest/locate consumers. Deliberately small: only knobs with a stable scalar shipped default. */
+const TUNE_DEFAULTS = { tune: { scoreGapK: DEFAULT_SCORE_GAP, literalMention: true } };
+
+/** Resolve the digest query-mode tuning knobs, precedence explicit arg > seonix.toml [tune] > default.
+ *  literal_mention is tri-state (shipped ON; a toml `false` disables; an explicit arg wins either way).
+ *  score_gap is arg-wins (`false` = disable → null), else the toml default, else DEFAULT_SCORE_GAP.
+ *  With `toml` null (no file / bench path) both equal today's inline values → byte-identical. */
+function resolveDigestTune(args, toml) {
+  const t = (toml && toml.tune) || {};
+  const literalMention = args.literal_mention !== undefined
+    ? args.literal_mention !== false
+    : (t.literalMention !== undefined ? t.literalMention !== false : true);
+  let scoreGapK;
+  if (args.score_gap !== undefined) scoreGapK = args.score_gap === false ? null : (Number.isFinite(args.score_gap) ? args.score_gap : DEFAULT_SCORE_GAP);
+  else if (t.scoreGapK !== undefined) scoreGapK = t.scoreGapK;
+  else scoreGapK = DEFAULT_SCORE_GAP;
+  return { literalMention, scoreGapK };
+}
+
+/** Resolve the locate-phase ranker levers, precedence explicit arg > seonix.toml [tune] > shipped
+ *  default. With `toml` null (no seonix.toml OR the bench `config:false` path) every value equals
+ *  today's inline arg-derived value, so the emitted ranking stays byte-identical. */
+function resolveLocateTune(args, toml) {
+  const t = (toml && toml.tune) || {};
+  const pick = (argVal, tomlVal, dflt) =>
+    argVal !== undefined ? !!argVal : (tomlVal !== undefined ? !!tomlVal : dflt);
+  const literalMention = args.literal_mention !== undefined
+    ? args.literal_mention !== false
+    : (t.literalMention !== undefined ? t.literalMention !== false : true);
+  const out = {
+    literalMention,
+    demoteNonProd: pick(args.demote_nonprod, t.demoteNonProd, false),
+    callAdjacency: pick(args.call_adjacency, t.callAdjacency, false),
+    implOfInterface: pick(args.impl_of_interface, t.implOfInterface, false),
+    beamSearch: pick(args.beam_search, t.beamSearch, false),
+  };
+  if (Number.isFinite(Number(args.beam_width))) out.beamWidth = Number(args.beam_width);
+  else if (Number.isFinite(Number(t.beamWidth))) out.beamWidth = Number(t.beamWidth);
+  return out;
+}
+
 const DIGEST_MODULE_CAP = 12;   // bound the no-MCP digest — a handful of changed modules
 const DIGEST_SECONDARY_CAP = 2; // B2: at most this many SECONDARY modules get a (trimmed) bundle
 const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
@@ -77,6 +155,15 @@ const TIER_RANK = { NONE: 0, TINY: 1, MID: 2, LARGE: 3, FULL: 4 };
 async function runDigest(args) {
   const repoPath = args.repo_path;
   if (!repoPath) { process.stderr.write("seonix: digest requires repo_path\n"); process.exit(2); }
+  // seonix.toml [tune] defaults the query-mode knobs (arg > seonix.toml > default). Skipped entirely
+  // on the bench path (config:false → tomlFor null) and when no seonix.toml exists → byte-identical.
+  const toml = await tomlFor(repoPath, args);
+  warnUnwired(toml);
+  // Opt-in telemetry (default OFF → null → `tel?.record` is a no-op, no file). LOG FILE ONLY —
+  // stdout is the digest injected into the no-MCP arm, so telemetry must never touch it. The
+  // seonix.toml [telemetry] toggle rides in via `toml`; SEONIX_TELEMETRY still wins both ways.
+  const tel = createTelemetry({ env: process.env, config: configFor(repoPath), toml, surface: "cli" });
+  const tune = resolveDigestTune(args, toml);
   let modules = Array.isArray(args.modules) ? args.modules.slice(0, DIGEST_MODULE_CAP) : [];
   let autoSelected = null; // for the header, when `query` drove selection
   if (!modules.length && args.query) {
@@ -86,8 +173,8 @@ async function runDigest(args) {
     // lockstep with the `seonix_locate` handler so `cli digest '{query}'` ≡ `cli seonix_locate` for the
     // same query. A strict no-op unless the query carries a ≥3-component dotted path / repo-relative
     // path; searchModulesRanked derives rawQuery from the query when literalMention is on.
-    const ranked = searchModulesRanked(graph, args.query, { literalMention: args.literal_mention !== false });
-    const scoreGapK = args.score_gap === false ? null : (Number.isFinite(args.score_gap) ? args.score_gap : DEFAULT_SCORE_GAP);
+    const ranked = searchModulesRanked(graph, args.query, { literalMention: tune.literalMention });
+    const scoreGapK = tune.scoreGapK;
     modules = selectRankedModules(ranked, { top_k: Number.isFinite(args.top_k) ? args.top_k : 2, scoreGapK }).slice(0, DIGEST_MODULE_CAP);
     autoSelected = modules;
     if (!modules.length) process.stderr.write(`seonix: digest query "${args.query}" matched no modules — empty digest\n`);
@@ -145,7 +232,16 @@ async function runDigest(args) {
   // rig's own parser depends on.
   const header = `# seonix-digest tier=${effTier} topup=${topup} modules=${emitted}`
     + (autoSelected ? ` selected=${autoSelected.join(",") || "(none)"}` : "");
-  process.stdout.write([header, ...body].join("\n") + "\n");
+  const out = [header, ...body].join("\n") + "\n";
+  process.stdout.write(out);
+  // One telemetry line for the digest surface: the selected modules + the effective tier/topup the
+  // header already carries, plus the injected body size. `tier` here MUST equal the header's tier=.
+  tel?.record({
+    surface: "digest",
+    query: args.query ? { raw: args.query } : undefined,
+    response: { count: emitted, node_ids: modules, tier: effTier, topup },
+    cost: { returned_chars: out.length, returned_tokens_est: Math.ceil(out.length / 4) },
+  });
 }
 
 /** Read all of stdin (best-effort; resolves "" if none). */
@@ -182,6 +278,28 @@ async function hookAugment() {
   }
 }
 
+/** A7: incremental estate sync. Shared by `cli sync '{multi_root}'` and index_repository's
+ *  `"sync":true` on a multi_root. Re-extracts only the changed member repos; prints
+ *  per-category counts to stderr and the summary MD to stdout (byte-stable no-op prints
+ *  neither a rewrite nor a summary). */
+async function runSync(multiRoot, { ignores, historyDepth }) {
+  const res = await syncRepositories(multiRoot, {
+    ignores, historyDepth,
+    log: (line) => process.stderr.write(`seonix: ${line}\n`),
+  });
+  if (res.noop) {
+    process.stderr.write(`seonix: sync ${multiRoot}: ${res.unchanged.length} repo(s) unchanged — no rewrite\n`);
+    process.stdout.write(`# seonix sync: ${res.unchanged.length} repo(s) unchanged (no rewrite)\n`);
+    return;
+  }
+  process.stderr.write(
+    `seonix: sync ${multiRoot}: +${res.added.length} added, ~${res.changed.length} changed, ` +
+      `-${res.removed.length} removed, ${res.unchanged.length} unchanged ` +
+      `(re-extracted ${res.reextracted.length}) → ${res.graphFile}\n`,
+  );
+  process.stdout.write(`${renderSummaryMd(res.summary)}\n`);
+}
+
 async function main() {
   const [mode, sub, payload] = process.argv.slice(2);
 
@@ -200,10 +318,47 @@ async function main() {
         process.stderr.write(`seonix: ${given.join(" + ")} are mutually exclusive — pass exactly one\n`);
         process.exit(2);
       }
-      if (given.length === 0) {
+      // seonix.toml: config dir = the explicit repo/estate path, else out_root, else cwd (where the
+      // file sits). Skipped entirely on the bench path (config:false → tomlFor null → byte-identical).
+      const toml = await tomlFor(args.repo_path || args.multi_root || args.out_root || process.cwd(), args);
+      warnUnwired(toml);
+      // repositories: seonix.toml MAY supply the repo set when NO explicit path arg is given
+      // (explicit repo_path/repo_paths/multi_root always win).
+      const tomlRepos = (given.length === 0 && toml && Array.isArray(toml.repositories) && toml.repositories.length)
+        ? toml.repositories : null;
+      if (given.length === 0 && !tomlRepos) {
         process.stderr.write("seonix: index_repository requires repo_path, repo_paths or multi_root\n");
         process.exit(2);
       }
+      // A5 `history_depth`: unified cap over BOTH git-history passes. 0 = skip history entirely;
+      // N>0 = `git log -n N`; absent = today's defaults. Precedence: explicit arg > seonix.toml
+      // [index].history_depth > default. Consumed by indexRepository/indexRepositories → extractRepo.
+      let historyDepth;
+      const rawHistoryDepth = args.history_depth !== undefined ? args.history_depth
+        : (toml && toml.index && toml.index.historyDepth !== undefined ? toml.index.historyDepth : undefined);
+      if (rawHistoryDepth !== undefined) {
+        if (!Number.isInteger(rawHistoryDepth) || rawHistoryDepth < 0) {
+          process.stderr.write("seonix: history_depth must be a non-negative integer (0 = skip git history)\n");
+          process.exit(2);
+        }
+        historyDepth = rawHistoryDepth;
+      }
+      // [index].exclude/secret_exclude → a compiled additive matcher (compileGlobs: ordered, `!`
+      // re-includes); [index].languages → the extractor language gate. Both are consumed by
+      // extractRepo (via indexRepository/indexRepositories → extraIgnores/languages), so they take
+      // effect at index time. Byte-identical with no toml (extraIgnores stays null, languages undefined).
+      let extraIgnores = null;
+      let tomlLanguages;
+      if (toml && toml.index) {
+        extraIgnores = compileGlobs([...(toml.index.exclude || []), ...(toml.index.secretExclude || [])]);
+        tomlLanguages = toml.index.languages;
+      }
+      // A7: `"sync":true` on a multi_root routes through the SAME incremental-sync code
+      // path as `cli sync` — fingerprint the estate, re-extract only changed members.
+      if (args.multi_root && args.sync === true) {
+        await runSync(args.multi_root, { ignores: args.ignores !== false, historyDepth });
+        return;
+      }
       const t0 = Date.now();
       const emitSummary = (graphFile, counts, head) => {
         process.stderr.write(
@@ -218,18 +373,22 @@ async function main() {
       };
 
       if (args.repo_path) {
-        const { graphFile, counts } = await indexRepository(args.repo_path, { ignores: args.ignores !== false });
+        const { graphFile, counts, summary } = await indexRepository(args.repo_path, { ignores: args.ignores !== false, historyDepth, extraIgnores, languages: tomlLanguages });
         emitSummary(graphFile, counts, "");
+        // A1: the human summary MD goes to STDOUT (bench ignores index stdout — safe;
+        // the machine-readable counts stay on stderr above).
+        process.stdout.write(`${renderSummaryMd(summary)}\n`);
         return;
       }
 
-      let repoPaths = args.repo_paths;
-      let outRoot = args.out_root || "";
+      let repoPaths = args.repo_paths || tomlRepos; // seonix.toml `repositories` when no explicit paths
+      let outRoot = args.out_root || (toml && toml.outRoot) || "";
+      let skippedRows = []; // [{name, reason}] from multi_root discovery → A1 summary
       if (args.multi_root) {
         const { repos, skipped } = await discoverRepos(args.multi_root);
         process.stderr.write(
           `seonix: multi_root ${args.multi_root}: ${repos.length} repo(s) discovered` +
-            (skipped.length ? `; skipped ${skipped.length} non-repo child dir(s): ${skipped.join(", ")}` : "") + "\n",
+            (skipped.length ? `; skipped ${skipped.length} non-repo child dir(s): ${skipped.map((s) => s.name).join(", ")}` : "") + "\n",
         );
         if (!repos.length) {
           process.stderr.write("seonix: multi_root contains no repositories (no child directory has a .git)\n");
@@ -237,17 +396,44 @@ async function main() {
         }
         repoPaths = repos;
         outRoot = args.multi_root;
+        skippedRows = skipped;
       }
       if (!Array.isArray(repoPaths) || repoPaths.length === 0) {
         process.stderr.write("seonix: repo_paths must be a non-empty array of absolute paths\n");
         process.exit(2);
       }
-      const { graphFile, counts, repos } = await indexRepositories(repoPaths, {
+      const { graphFile, counts, repos, summary } = await indexRepositories(repoPaths, {
         ignores: args.ignores !== false,
         outRoot,
+        historyDepth,
+        extraIgnores,
+        languages: tomlLanguages,
+        skipped: skippedRows,
         log: (line) => process.stderr.write(`seonix: ${line}\n`),
       });
       emitSummary(graphFile, counts, `${repos.length} repos, `);
+      process.stdout.write(`${renderSummaryMd(summary)}\n`);
+      return;
+    }
+
+    // sync mode (A7): `cli sync '{"multi_root":"<abs>"}'` — incrementally re-index an
+    // estate, re-extracting only the child repos whose fingerprint changed since the last
+    // manifest. exit 2 without multi_root.
+    if (sub === "sync") {
+      const args = parsePayload(payload);
+      if (args === null || !args.multi_root) {
+        process.stderr.write("seonix: sync requires a JSON arg with multi_root, e.g. '{\"multi_root\":\"/abs\"}'\n");
+        process.exit(2);
+      }
+      let historyDepth;
+      if (args.history_depth !== undefined) {
+        if (!Number.isInteger(args.history_depth) || args.history_depth < 0) {
+          process.stderr.write("seonix: history_depth must be a non-negative integer (0 = skip git history)\n");
+          process.exit(2);
+        }
+        historyDepth = args.history_depth;
+      }
+      await runSync(args.multi_root, { ignores: args.ignores !== false, historyDepth });
       return;
     }
 
@@ -273,15 +459,23 @@ async function main() {
         process.exit(2);
       }
       const config = configFor(args.repo_path);
+      // seonix.toml [tune] defaults the locate levers (arg > seonix.toml > default). Skipped on the
+      // bench path (config:false → tomlFor null) and when no seonix.toml exists → byte-identical.
+      const toml = await tomlFor(args.repo_path, args);
+      warnUnwired(toml);
+      // Opt-in telemetry (default OFF → null → no-op, no file). stdout is the ranked list the rig
+      // parses, so telemetry is LOG FILE ONLY. seonix.toml [telemetry] rides in via `toml`.
+      const tel = createTelemetry({ env: process.env, config, toml, surface: "cli" });
+      const tune = resolveLocateTune(args, toml);
       try {
         const graph = parseEntities(await source.fetchEntities(config));
         // B016 recall-lever flags (LOCATE-phase, per-arm; output byte-identical when absent).
         const ranked = searchModulesRanked(graph, args.query || "", {
-          demoteNonProd: !!args.demote_nonprod, // R1a: demote examples//fixtures//test-* paths
-          callAdjacency: !!args.call_adjacency, // E1a: resolved-call adjacency bonus
-          implOfInterface: !!args.impl_of_interface, // E1b: C# impl-of-interface boost
-          beamSearch: !!args.beam_search, // §5.15: multi-ply discriminative expansion
-          ...(Number.isFinite(Number(args.beam_width)) ? { beamWidth: Number(args.beam_width) } : {}),
+          demoteNonProd: tune.demoteNonProd, // R1a: demote examples//fixtures//test-* paths
+          callAdjacency: tune.callAdjacency, // E1a: resolved-call adjacency bonus
+          implOfInterface: tune.implOfInterface, // E1b: C# impl-of-interface boost
+          beamSearch: tune.beamSearch, // §5.15: multi-ply discriminative expansion
+          ...(tune.beamWidth !== undefined ? { beamWidth: tune.beamWidth } : {}),
           // B018 §8.1.3 literal-mention lever: match verbatim dotted-name/path mentions in the RAW
           // query (which the locate tokenizer destroys). searchModulesRanked derives rawQuery from the
           // query arg when literalMention is on; the rig passes the raw problem as the query, so literal
@@ -292,10 +486,35 @@ async function main() {
           // with no ≥3-component dotted path / repo-relative path, so it never perturbs the cells the
           // headline B018 numbers were measured on. The low-level scoreModules default (codegraph.mjs)
           // stays literalMention=false; the product surface opts in explicitly, right here.
-          literalMention: args.literal_mention !== false,
+          literalMention: tune.literalMention,
           ...(args.raw_query != null ? { rawQuery: String(args.raw_query) } : {}),
+          // A4 (B016 recall lever, SPIRAL): a bounded-radius ego walk from the lexical seeds that MAY
+          // surface lexically-invisible modules — the one lever that breaks the lexical ceiling.
+          // scoreModules short-circuits on spiral:false (spiralExpand never runs), so with no spiral
+          // flag every key below is absent-or-inert and the emitted ranking is byte-identical to the
+          // pre-A4 locate surface. Same snake_case→camelCase idiom as demote_nonprod / beam_width.
+          spiral: !!args.spiral,
+          ...(Number.isFinite(Number(args.spiral_depth)) && Number(args.spiral_depth) > 0
+            ? { spiralDepth: Number(args.spiral_depth) } : {}), // hop radius from the seeds (>0 only)
+          ...(args.spiral
+            // spiralNodeLimit: how many newly-reached nodes the spiral may surface. The CLI surface
+            // defaults to 100 — deliberately ABOVE the internal SPIRAL_NODE_LIMIT_DEFAULT of 12 —
+            // because `cli seonix_locate` is a RECALL PROBE, not a token budget: surface everything
+            // reachable and let the caller/rig trim. `limit` overrides it (positive finite only).
+            ? { spiralNodeLimit: Number.isFinite(Number(args.limit)) && Number(args.limit) > 0 ? Number(args.limit) : 100 }
+            : {}),
         });
         process.stdout.write(ranked.map((r) => `${r.path}\t${r.score}`).join("\n") + "\n");
+        // Telemetry for the locate surface: the ranked count + the top few paths/scores.
+        tel?.record({
+          surface: "locate",
+          query: { raw: String(args.query || "") },
+          response: {
+            count: ranked.length,
+            node_ids: ranked.slice(0, 3).map((r) => r.path),
+            scores: ranked.slice(0, 3).map((r) => r.score),
+          },
+        });
       } catch (e) {
         process.stderr.write(`seonix: ${e?.message || e}\n`);
         process.exit(1);
@@ -345,6 +564,41 @@ async function main() {
       return;
     }
 
+    // store_rebuild (C12): force-(re)build the opt-in node:sqlite store from the current
+    // graph.json. The store is a derived, rebuildable companion — read paths never auto-build
+    // it, so this is the explicit way to (re)materialize it after an index or a graph.json edit.
+    if (sub === "store_rebuild") {
+      const args = parsePayload(payload);
+      if (args === null) {
+        process.stderr.write("seonix: store_rebuild expects a JSON arg, e.g. '{\"repo_path\":\"/abs\"}'\n");
+        process.exit(2);
+      }
+      const { graphFile } = configFor(args.repo_path);
+      const { readFile, stat } = await import("node:fs/promises");
+      const { writeStore, storeFileFor, verifyStore } = await import("../src/store.mjs");
+      const { expandGraphPayload } = await import("../src/graph-format.mjs");
+      try {
+        const text = await readFile(graphFile, "utf8");
+        // Expand the interned v2 wire form to the classic in-memory shape writeStore builds from
+        // (a v1 graph is passthrough). Without this, store_rebuild on a v2 graph.json would build
+        // an edge-less store while verifyStore still reports success (the sha matches).
+        const payloadObj = expandGraphPayload(JSON.parse(text));
+        const dbPath = storeFileFor(graphFile);
+        const sourceStat = await stat(graphFile);
+        const t0 = Date.now();
+        await writeStore(dbPath, payloadObj, { sourceStat, sourceText: text });
+        const ok = await verifyStore(dbPath, graphFile);
+        process.stderr.write(
+          `seonix: store ${ok ? "rebuilt" : "rebuilt (verify FAILED)"} in ${Date.now() - t0}ms → ${dbPath}\n`,
+        );
+        if (!ok) process.exit(1);
+      } catch (e) {
+        process.stderr.write(`seonix: store_rebuild failed: ${e?.message || e}\n`);
+        process.exit(1);
+      }
+      return;
+    }
+
     // tool-query fallback: any other `cli <toolName> '{…}'` routes to the MCP dispatcher,
     // so "cold" tools are invokable from Bash without an MCP connection.
     if (sub) {
@@ -354,9 +608,18 @@ async function main() {
         process.exit(2);
       }
       const config = configFor(args.repo_path);
+      // seonix.toml [telemetry] toggle for the generic tool surface (byte-identical with no toml:
+      // tomlFor short-circuits to null on the bench path and when no seonix.toml exists).
+      const toml = await tomlFor(args.repo_path, args);
+      const tel = createTelemetry({ env: process.env, config, toml, surface: "cli" });
       try {
         const text = await dispatchTool(sub, args, { config });
         process.stdout.write(text + "\n");
+        // Telemetry for the generic tool surface: which tool + how many chars it returned.
+        tel?.record({
+          tool: sub,
+          cost: { returned_chars: text.length, returned_tokens_est: Math.ceil(text.length / 4) },
+        });
       } catch (e) {
         process.stderr.write(`seonix: ${e?.message || e}\n`);
         process.exit(1);
@@ -392,13 +655,46 @@ async function main() {
     return;
   }
 
+  // `seonix init [--dotnet] [--force]`: seed a seonix.toml in the cwd from the shipped template
+  // (or the dotnet estate template with --dotnet). Refuses to overwrite an existing file (exit 2)
+  // unless --force. The write is a raw Buffer copy → byte-equal to the template.
+  if (mode === "init") {
+    const dotnet = process.argv.includes("--dotnet");
+    const force = process.argv.includes("--force");
+    const src = fileURLToPath(new URL(`../templates/${dotnet ? "seonix-dotnet.toml" : "seonix.toml"}`, import.meta.url));
+    const dest = join(process.cwd(), CONFIG_FILE);
+    if (existsSync(dest) && !force) {
+      process.stderr.write(`seonix: ${CONFIG_FILE} already exists — pass --force to overwrite\n`);
+      process.exit(2);
+    }
+    await writeFile(dest, await readFile(src));
+    process.stdout.write(`seonix: wrote ${dest} — edit it, then \`seonix config --effective\` to review.\n`);
+    return;
+  }
+
+  // `seonix config --effective [--repo <abs>]`: print the merged {effective, sources} config
+  // (sorted keys) for the repo dir (default cwd). Without --effective, print usage and exit 2.
+  if (mode === "config") {
+    if (!process.argv.includes("--effective")) {
+      process.stderr.write("seonix: usage: seonix config --effective [--repo <abs>]\n");
+      process.exit(2);
+    }
+    const ri = process.argv.indexOf("--repo");
+    const repo = ri !== -1 && process.argv[ri + 1] ? process.argv[ri + 1] : process.cwd();
+    const raw = existsSync(join(repo, CONFIG_FILE)) ? await loadTomlConfig(repo) : null;
+    const toml = raw ? await normalizeConfig(raw, { configDir: repo }) : null;
+    const merged = mergeEffective({ toml, defaults: TUNE_DEFAULTS });
+    process.stdout.write(JSON.stringify(merged, null, 2) + "\n");
+    return;
+  }
+
   if (mode === undefined) {
     await startServer(); // bare invocation → MCP stdio server
     return;
   }
 
   process.stderr.write(`seonix: unknown invocation "${process.argv.slice(2).join(" ")}". ` +
-    "Use bare (MCP server), `cli index_repository …`, `cli <tool> …`, `chat`, `hook-augment`, or `viz`.\n");
+    "Use bare (MCP server), `cli index_repository …`, `cli <tool> …`, `chat`, `hook-augment`, `viz`, `init`, or `config --effective`.\n");
   process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "description": "SEONIX — a deterministic, offline, $0 code-graph tool that makes a cheap coding agent edit like an expensive one. Indexes a repo with Python ast + git (zero model calls) and renders a bounded edit-digest.",
@@ -45,6 +45,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cytoscape": "^3.30.0",
+    "smol-toml": "^1.7.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c-sharp": "^0.21.3",
     "tree-sitter-java": "^0.21.0",

package/src/ask.mjs

@@ -649,6 +649,16 @@ const NEST_SENTINEL = "zzinnerset";
 // Filler words dropped at the front of a relative predicate / anaphora filter.
 const PRED_LEAD_SKIP = new Set(["that", "which", "who", "are", "is", "was", "were", "do", "does", "also", "still", "both", "and"]);
 const FRAME_WORDS = new Set(["which", "what", "who", "list", "show", "find", "give", "me", "us", "all"]);
+// Determiners that may sit in front of the SUBJECT noun of a subject-relative query
+// ("THE modules that import X", "THOSE classes that extend Base"). Peeled in
+// parseRelationalOrQualified so the marker-gated compositional path catches them exactly
+// as it already catches the bare "modules that import X" — otherwise the leading article
+// keeps the subject noun off position 0, the compositional production bails, and
+// keyword-spot mis-reads the trailing "that" as a subject pronoun (→ a false
+// "needs a selected node" miss). Kept SEPARATE from FRAME_WORDS so peeling a determiner
+// does not by itself flag the clause as a `framed` interrogative (which would turn a
+// trailing unknown adjective into a qualifier miss on its own).
+const LEADING_DETERMINERS = new Set(["the", "a", "an", "these", "those"]);
 
 const splitWords = (text) => String(text).replace(/\?+\s*$/, "").replace(/,/g, " ").split(/\s+/).filter(Boolean);
 const entityNoun = (w) => (ENTITY_TO_TYPE[w] ? { entityType: ENTITY_TO_TYPE[w], placeholder: false }
@@ -916,6 +926,10 @@ function parseRelationalOrQualified(w, lc, nlp, depth) {
   let i = 0;
   while (i < lc.length && FRAME_WORDS.has(lc[i])) i += 1;
   const framed = i > 0;
+  // peel a leading determiner (see LEADING_DETERMINERS) — a bare "the"/"those" in front of
+  // the subject noun, so "the modules that import X" reaches the same production as the
+  // bare "modules that import X". Not folded into `framed` on purpose.
+  while (i < lc.length && LEADING_DETERMINERS.has(lc[i])) i += 1;
   const quals = [];
   while (i < lc.length && QUALIFIERS[lc[i]]) { quals.push(lc[i]); i += 1; }
   const noun = i < lc.length ? entityNoun(lc[i]) : null;

package/src/browser.mjs

@@ -92,18 +92,22 @@ const attr = (ind, key) => {
  * correct; this fallback makes gitCommitOrder itself repo-set-agnostic and testable.)
  * @param {string} repo
  * @param {Iterable<string>} graphCommitIds
- * @param {{datesBySha?: Map<string,string>|null}} [opts]
+ * @param {{datesBySha?: Map<string,string>|null, warn?: (s: string) => void}} [opts]
  */
-export async function gitCommitOrder(repo, graphCommitIds, { datesBySha = null } = {}) {
+export async function gitCommitOrder(repo, graphCommitIds, { datesBySha = null, warn = (s) => process.stderr.write(s) } = {}) {
   const shas = new Set([...graphCommitIds].map((id) => String(id).replace(/^commit:/, "")));
   let ordered = [];
   try {
+    // Bounded: a wedged/huge git never hangs the caller — SIGKILL after 30s, then the
+    // graceful date/graph-order fallback below. The failure is WARNED, never silent.
     const { stdout } = await execFileP("git", ["-C", repo, "log", "--format=%H"], {
       maxBuffer: 64 * 1024 * 1024,
+      timeout: 30_000,
+      killSignal: "SIGKILL",
     });
     ordered = stdout.trim().split("\n").reverse().filter((s) => shas.has(s));
-  } catch {
-    /* fall through to graph/date order */
+  } catch (err) {
+    warn(`seonix: git log (commit order) failed in ${repo}: ${String(err.message || err)}; using date/graph order\n`);
   }
   if (!ordered.length && datesBySha) {
     // Merged-graph fallback: one commit date axis across every repo (tie-break by sha
@@ -127,22 +131,27 @@ export async function gitCommitOrder(repo, graphCommitIds, { datesBySha = null }
  * got folded in. Best-effort: an empty Map on any git failure, so callers
  * degrade to "no merge info" the same way a HEAD-only index already degrades.
  * @param {string} repo
+ * @param {{warn?: (s: string) => void}} [opts]
  * @returns {Promise<Map<string, string[]>>} sha -> parent shas, git's own order
  *   (a root commit maps to []).
  */
-export async function gitCommitParents(repo) {
+export async function gitCommitParents(repo, { warn = (s) => process.stderr.write(s) } = {}) {
   const parents = new Map();
   try {
+    // Same bound as gitCommitOrder — merge info is best-effort, but a failure is
+    // WARNED (never silent) before degrading to the empty "no merge info" map.
     const { stdout } = await execFileP("git", ["-C", repo, "log", "--format=%H %P"], {
       maxBuffer: 64 * 1024 * 1024,
+      timeout: 30_000,
+      killSignal: "SIGKILL",
     });
     for (const line of stdout.trim().split("\n")) {
       if (!line) continue;
       const [sha, ...ps] = line.split(" ").filter(Boolean);
       if (sha) parents.set(sha, ps);
     }
-  } catch {
-    /* empty map — merge info is best-effort, never fatal */
+  } catch (err) {
+    warn(`seonix: git log (commit parents) failed in ${repo}: ${String(err.message || err)}; merge info unavailable\n`);
   }
   return parents;
 }