@polycode-projects/the-mechanical-code-talker 2.11.12 → 3.0.0

package/README.md

@@ -1150,8 +1150,10 @@ node bin/tmct.mjs cli tmct_untested '{"repo_path":"examples/mini-webapp"}'
 
 ## The repository interface
 
-tmct is not an indexer, so it consumes a graph through a typed contract any
-producer can implement. That contract is first-class: a **versioned (1.1.0),
+tmct consumes a graph through a typed contract any producer can implement —
+including its own `tmct index` command, which walks a repo's source and writes
+the graph, and any external producer (seonix, a CI indexer, a hand-written JSON
+file) feeding the same seam. That contract is first-class: a **versioned (1.1.0),
 OWL-grounded, machine-readable service definition** (`docs/repository-interface.md`
 plus a JSON schema) of every service, its arguments, result types, and error
 contract. The interface returns a miss as a normal value. It never throws to

package/bin/tmct.mjs

@@ -2,7 +2,8 @@
 // tmct — The Mechanical Code Talker. The headline entry is CHAT: a bare
 // invocation drops you into a tolerant, offline, $0 prompt that guides you
 // toward precision queries about a repository (ELIZA/PARRY-style, but obsessed
-// with software). No model calls; tmct keeps no codebase index of its own.
+// with software). No model calls; tmct indexes a repo on request (tmct index)
+// or reads a graph any other producer wrote.
 //
 //   tmct                                   → interactive chat (the headline)
 //   tmct chat [--repo <abs>] [--plain]     → same, explicit
@@ -49,7 +50,7 @@ process.on("warning", (warning) => {
 const HELP = `tmct — The Mechanical Code Talker
 
 A tolerant, offline, $0 chat that guides you toward precision queries about a
-software repository. No model calls; no codebase index of its own.
+software repository. No model calls; index a repo with \`tmct index\`, or read any producer's graph.
 
 Usage:
 ${renderUsage()}
@@ -986,6 +987,36 @@ async function main() {
     return;
   }
 
+  if (mode === "index") {
+    // `tmct index` — the code-graph PRODUCER. Walks a repo's own source, parses
+    // it (JS/TS today, via the TypeScript compiler API), reads git history, and
+    // writes <repo>/.tmct/graph.json — the same artifact chat/serve/cli read
+    // through the provider seam. This is tmct producing a graph for the first
+    // time; the seam that consumes one is unchanged.
+    const rest = process.argv.slice(3);
+    const { strFlag } = await import("../src/services/cli-args.mjs");
+    const { resolve: resolvePath } = await import("node:path");
+    const { indexRepository } = await import("../src/index/index-repo.mjs");
+    const repoFlag = strFlag(rest, ["--repo"]);
+    const repoRoot = repoFlag ? resolvePath(process.cwd(), repoFlag) : process.cwd();
+    const noHistory = rest.includes("--no-history");
+    const stats = await indexRepository(repoRoot, noHistory ? { historyDepth: 0 } : {});
+    for (const { pass, message } of stats.gitErrors || []) {
+      process.stderr.write(`tmct index: WARNING git history pass '${pass}' — ${message} (graph built without those edges)\n`);
+    }
+    const perLang = Object.entries(stats.perLang)
+      .map(([lang, s]) => `${lang}: ${s.modules} modules, ${s.symbols} symbols`).join("; ");
+    const kib = (stats.bytes / 1024).toFixed(1);
+    process.stdout.write(
+      `tmct index — wrote ${stats.graphFile} (${stats.modules} modules, ${stats.symbols} symbols; ${kib} KiB)\n`
+      + (perLang ? `${perLang}\n` : "no supported source found under the repo\n"),
+    );
+    if (stats.failures?.length) {
+      process.stderr.write(`tmct index: ${stats.failures.length} file(s) failed to parse (skipped): ${stats.failures.slice(0, 5).join(", ")}${stats.failures.length > 5 ? ", …" : ""}\n`);
+    }
+    return;
+  }
+
   if (mode === "import") {
     // `tmct import` — activate+seed into an ALREADY-initialized repo, reusing
     // the SAME resolvePluggableInput/activatePluggableInput seam `init`'s own

package/corpus/tier2/generate.mjs

@@ -173,7 +173,7 @@ export const CORPUSES = {
     ],
   },
 
-  // PLAN_AGENTS.md Phase 1's "wider general-knowledge seed set" bullet: the
+  // The wider general-knowledge seed set: the
   // three corpuses above are all code-domain-specific (a LANGUAGE or a cloud
   // DOMAIN); this one deliberately is NOT — everyday-knowledge concepts (the
   // natural world, weather, food, common objects) with zero code-domain

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@polycode-projects/the-mechanical-code-talker",
-  "version": "2.11.12",
+  "version": "3.0.0",
   "private": false,
   "type": "module",
-  "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; no codebase index of its own.",
+  "description": "The Mechanical Code Talker (tmct) — a tolerant, offline, $0 chat surface that guides you toward precision queries about a software repository. ELIZA/PARRY-style but domain-obsessed with code. No model calls; indexes a repo on request (tmct index) or reads any producer's graph.",
   "keywords": [
     "chatbot",
     "no-llm",
@@ -78,6 +78,7 @@
     "ink": "^7.1.0",
     "react": "^19.2.7",
     "smol-toml": "^1.7.0",
+    "typescript": "~5.6.2",
     "wink-eng-lite-web-model": "^1.8.1",
     "wink-nlp": "^2.4.0"
   },

package/src/adapters/source.mjs

@@ -3,12 +3,14 @@
 // stub it); in production it reads the JSON artifact the deterministic indexer
 // wrote to config.graphFile. No network, no model calls.
 //
-// This module is the PROVIDER SEAM (docs/adapter-contract.md):
-// any graph producer can feed tmct either by writing the entities-payload JSON
-// where config.graphFile points, or by registering a custom loader with
-// registerProvider() — no indexer is ever imported here. tmct only READS
-// through this seam; its own writes go to .tmct/memory/ (src/memory/), never
-// back into a provider's artifact.
+// This module is the READ SEAM (docs/adapter-contract.md): any graph producer
+// can feed tmct either by writing the entities-payload JSON where
+// config.graphFile points, or by registering a custom loader with
+// registerProvider(). The PRODUCER lives elsewhere — tmct's own `tmct index`
+// (src/index/) is one such producer, and it writes through that same file path,
+// not through this module. Keeping the reader and the producer in separate module
+// trees is deliberate: this module only READS, and tmct's own writes go to
+// .tmct/memory/ (src/memory/), never back into a provider's graph artifact.
 
 import { readFile } from "node:fs/promises";
 import { ToolError } from "./config.mjs";

package/src/domain/cli-verbs.mjs

@@ -68,6 +68,15 @@ export const CLI_VERBS = [
       { flag: "[--memory-backend <default|memory|sqlite>]", prose: ["write tmct.toml's [memory] backend", "(same flag name as `tmct chat`) — a later `tmct chat`", "in this repo picks it up with no flag needed"] },
     ],
   },
+  {
+    mode: "index",
+    errorLabel: "index",
+    usage: "tmct index [--repo <abs>]",
+    prose: ["produce a code graph from a repo's OWN source (default: cwd):"],
+    flags: [
+      { flag: "[--no-history]", prose: ["walk the tree, parse JS/TS with the TypeScript compiler", "API, read git history, and write <repo>/.tmct/graph.json —", "the artifact chat/serve/cli then read. --no-history skips", "the git passes (no commit/touches/cochange edges)"] },
+    ],
+  },
   {
     mode: "import",
     errorLabel: "import",

package/src/index/extract-jsts.mjs

@@ -0,0 +1,251 @@
+// JS/TS extractor — TypeScript compiler API (direct `typescript` dep). Uses
+// ts.createSourceFile per file (no Program / no type-checker): the fast,
+// deterministic, offline structural pass. Covers .ts/.tsx/.js/.jsx/.mjs/.cjs.
+// Emits the `{path,dotted,imports,defines,calls,exports}` contract
+// graph-build.mjs's buildEntities() consumes.
+//
+// Both module systems are read: ESM import/export declarations AND a CommonJS
+// pass (top-level CJS require calls with literal specifiers → imports;
+// module.exports / exports.name assignments → exports) — CJS-only repos were
+// producing edge-empty graphs before the CJS pass existed.
+//
+// Fidelity note: params/returns are ANNOTATION strings (Group-A mechanical), not
+// resolved types — the same honesty the Python path keeps ("returns = annotation
+// only"). A type-RESOLVED pass (real Program + checker) is a research horizon,
+// not run here.
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import ts from "typescript";
+import { walk, relPath } from "./walk.mjs";
+
+const EXTS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"];
+const stripExt = (p) => p.replace(/\.(tsx?|jsx?|mjs|cjs)$/i, "");
+
+function scriptKind(path) {
+  if (/\.tsx$/i.test(path)) return ts.ScriptKind.TSX;
+  if (/\.ts$/i.test(path)) return ts.ScriptKind.TS;
+  if (/\.jsx$/i.test(path)) return ts.ScriptKind.JSX;
+  return ts.ScriptKind.JS;
+}
+
+const lineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+const endLineOf = (sf, node) => sf.getLineAndCharacterOfPosition(node.getEnd()).line + 1;
+
+/** "(a: string, b = 3)" → "a: string, b = 3" (annotation strings; not resolved). */
+function paramsText(sf, node) {
+  const ps = node.parameters || [];
+  return ps.map((p) => p.getText(sf).replace(/\s+/g, " ").trim()).join(", ").slice(0, 160);
+}
+function returnText(sf, node) {
+  return node.type ? node.type.getText(sf).replace(/\s+/g, " ").trim().slice(0, 80) : "";
+}
+function firstDocLine(sf, node) {
+  const ranges = ts.getLeadingCommentRanges(sf.text, node.getFullStart()) || [];
+  for (const r of ranges) {
+    const raw = sf.text.slice(r.pos, r.end);
+    const m = raw.replace(/^\/\*\*?|\*\/$/g, "").split("\n").map((l) => l.replace(/^\s*\*?\s?/, "").trim()).find(Boolean);
+    if (m) return m.slice(0, 120);
+  }
+  return "";
+}
+const hasMod = (node, kind) => (node.modifiers || []).some((m) => m.kind === kind);
+function visibilityOf(node) {
+  if (hasMod(node, ts.SyntaxKind.PrivateKeyword)) return "private";
+  if (hasMod(node, ts.SyntaxKind.ProtectedKeyword)) return "protected";
+  return "";
+}
+function decoratorsOf(sf, node) {
+  const ds = ts.canHaveDecorators?.(node) ? ts.getDecorators?.(node) : null;
+  return (ds || []).map((d) => d.expression.getText(sf).replace(/\s+/g, " ").slice(0, 80));
+}
+
+/** Collect callee names within a node body (coarse; unparsed call target). */
+function callsIn(sf, node) {
+  const out = new Set();
+  const visit = (n) => {
+    if (ts.isCallExpression(n)) {
+      const t = n.expression;
+      let name = "";
+      if (ts.isIdentifier(t)) name = t.text;
+      else if (ts.isPropertyAccessExpression(t)) name = t.getText(sf);
+      if (name) out.add(name.slice(0, 80));
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(node, visit);
+  return [...out].sort();
+}
+
+export async function extractFile(absPath, root) {
+  const text = await readFile(absPath, "utf8").catch(() => null);
+  if (text == null) return { failed: true, path: relPath(root, absPath) };
+  const path = relPath(root, absPath);
+  let sf;
+  try {
+    sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path));
+  } catch {
+    return { failed: true, path };
+  }
+  const dir = dirname(path);
+  const imports = new Set();
+  const calls = new Set();
+  const defines = [];
+  const exports = new Set();
+
+  const resolveSpecifier = (spec) => {
+    if (!spec || !spec.startsWith(".")) { if (spec) imports.add(spec); return; } // bare/external
+    const joined = join(dir, spec).split(/[\\/]/).join("/");
+    const base = stripExt(joined);
+    imports.add(base);
+    imports.add(`${base}/index`); // dir-import fallback (./foo → ./foo/index)
+  };
+
+  // CommonJS pass: CJS require / module.exports repos were leaving graphs
+  // edge-empty. Top-level statements only, STRICTLY literal arguments — a
+  // computed specifier is skipped, never guessed (the house "no wrong edge" rule).
+  /** A CJS require call with a single literal arg → its specifier, else null. */
+  const requireSpecifier = (node) =>
+    node && ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === "require" &&
+    node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0])
+      ? node.arguments[0].text
+      : null;
+  /** Peel a `.member` access / parens down to the require call (never enters functions). */
+  const requireIn = (expr) => {
+    let e = expr;
+    while (e && (ts.isPropertyAccessExpression(e) || ts.isParenthesizedExpression(e) || ts.isNonNullExpression?.(e))) e = e.expression;
+    return requireSpecifier(e);
+  };
+  const isModuleExports = (e) =>
+    ts.isPropertyAccessExpression(e) && ts.isIdentifier(e.expression) && e.expression.text === "module" && e.name.text === "exports";
+  const isExportsRef = (e) => isModuleExports(e) || (ts.isIdentifier(e) && e.text === "exports");
+
+  const addFn = (name, node, kind, extra = {}) => {
+    defines.push({
+      name, kind, lineno: lineOf(sf, node), end_lineno: endLineOf(sf, node),
+      decorators: decoratorsOf(sf, node),
+      params: paramsText(sf, node), returns: returnText(sf, node),
+      calls: callsIn(sf, node), doc: firstDocLine(sf, node),
+      ...(visibilityOf(node) ? { visibility: visibilityOf(node) } : {}),
+      ...extra,
+    });
+  };
+
+  for (const stmt of sf.statements) {
+    // imports / re-exports
+    if (ts.isImportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      resolveSpecifier(stmt.moduleSpecifier.text);
+    } else if (ts.isExportDeclaration(stmt) && stmt.moduleSpecifier && ts.isStringLiteral(stmt.moduleSpecifier)) {
+      resolveSpecifier(stmt.moduleSpecifier.text);
+    }
+    const exported = hasMod(stmt, ts.SyntaxKind.ExportKeyword);
+
+    if (ts.isFunctionDeclaration(stmt) && stmt.name) {
+      addFn(stmt.name.text, stmt, "function");
+      if (exported) exports.add(stmt.name.text);
+    } else if (ts.isClassDeclaration(stmt) && stmt.name) {
+      const cname = stmt.name.text;
+      const bases = [];
+      for (const h of stmt.heritageClauses || []) for (const t of h.types) bases.push(t.getText(sf).slice(0, 80));
+      defines.push({
+        name: cname, kind: "class", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+        bases, decorators: decoratorsOf(sf, stmt), doc: firstDocLine(sf, stmt),
+      });
+      if (exported) exports.add(cname);
+      for (const mem of stmt.members) {
+        if (ts.isMethodDeclaration(mem) || ts.isConstructorDeclaration(mem) ||
+            ts.isGetAccessor(mem) || ts.isSetAccessor(mem)) {
+          const mn = mem.name ? mem.name.getText(sf) : "constructor";
+          addFn(`${cname}.${mn}`, mem, "method");
+        } else if (ts.isPropertyDeclaration(mem) && mem.name) {
+          defines.push({
+            name: `${cname}.${mem.name.getText(sf)}`, kind: "attribute",
+            lineno: lineOf(sf, mem), end_lineno: endLineOf(sf, mem), decorators: decoratorsOf(sf, mem),
+          });
+        }
+      }
+    } else if (ts.isInterfaceDeclaration(stmt) && stmt.name) {
+      // interfaces map to Class nodes (type surface) — useful for TS-heavy repos
+      defines.push({
+        name: stmt.name.text, kind: "class", subkind: "interface",
+        lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+        bases: (stmt.heritageClauses || []).flatMap((h) => h.types.map((t) => t.getText(sf).slice(0, 80))),
+        decorators: [], doc: firstDocLine(sf, stmt),
+      });
+      if (exported) exports.add(stmt.name.text);
+    } else if (ts.isVariableStatement(stmt)) {
+      const isConst = (stmt.declarationList.flags & ts.NodeFlags.Const) !== 0;
+      for (const d of stmt.declarationList.declarations) {
+        // CJS import: const X = <require 'spec'> / const {a} = <require 'spec'> /
+        // const Y = <require 'spec'>.member — BEFORE the identifier-only gate so a
+        // destructuring binding still records the import edge.
+        const reqSpec = requireIn(d.initializer);
+        if (reqSpec != null) resolveSpecifier(reqSpec);
+        if (!ts.isIdentifier(d.name)) continue;
+        const vn = d.name.text;
+        const init = d.initializer;
+        // arrow/function assigned to a const → treat as a function define
+        if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+          addFn(vn, init, "function");
+        } else if (isConst && /^[A-Z0-9_]+$/.test(vn)) {
+          defines.push({ name: vn, kind: "global", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+            decorators: [], value: (init ? init.getText(sf) : "").replace(/\s+/g, " ").slice(0, 80), is_constant: true });
+        } else if (init && ts.isCallExpression(init)) {
+          // live-object global (e.g. const router = Router()) — a registration anchor
+          defines.push({ name: vn, kind: "global", lineno: lineOf(sf, stmt), end_lineno: endLineOf(sf, stmt),
+            decorators: [], value: init.getText(sf).replace(/\s+/g, " ").slice(0, 80) });
+        }
+        if (exported) exports.add(vn);
+      }
+    } else if (ts.isExportAssignment?.(stmt)) {
+      exports.add("default");
+    } else if (ts.isExpressionStatement(stmt)) {
+      // CJS exports + side-effect/re-export requires. Walk `=` chains so
+      // `exports = module.exports = X` records one default export, and
+      // `module.exports = <require './lib'>` records both the export and the import.
+      let expr = stmt.expression;
+      while (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+        const lhs = expr.left;
+        if (isExportsRef(lhs)) exports.add("default");
+        else if (ts.isPropertyAccessExpression(lhs) && isExportsRef(lhs.expression)) {
+          exports.add(lhs.name.text);
+        }
+        expr = expr.right;
+      }
+      const reqSpec = requireIn(expr); // covers a bare side-effect require too
+      if (reqSpec != null) resolveSpecifier(reqSpec);
+    }
+  }
+
+  // module-level coarse calls (whole file)
+  const visit = (n) => {
+    if (ts.isCallExpression(n)) {
+      const t = n.expression;
+      let name = "";
+      if (ts.isIdentifier(t)) name = t.text;
+      else if (ts.isPropertyAccessExpression(t)) name = t.getText(sf);
+      if (name) calls.add(name.slice(0, 80));
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(sf, visit);
+
+  return {
+    path, dotted: stripExt(path),
+    imports: [...imports].sort(), defines, calls: [...calls].sort(), exports: [...exports].sort(),
+  };
+}
+
+/** Ingest a whole tree → {modules, failures, fileCount} contract. */
+export async function ingest(root, { ignore = null } = {}) {
+  const files = await walk(root, EXTS, ignore);
+  const modules = [];
+  const failures = [];
+  for (const f of files) {
+    const mod = await extractFile(f, root);
+    if (mod.failed) failures.push(mod.path);
+    else modules.push(mod);
+  }
+  return { modules, failures, fileCount: files.length };
+}
+
+export const meta = { id: "tsc", language: "js/ts", lib: "typescript compiler API", exts: EXTS };

package/src/index/extract-python.mjs

@@ -0,0 +1,46 @@
+// Python extractor — stdlib `ast`, zero npm dependency. Runs extract_ast.py as a
+// subprocess over the whole repo (the script does its own deterministic walk and
+// emits one JSON doc: {modules:[{path,dotted,imports,defines,calls,exports}]} —
+// the same contract the in-process JS/TS extractor emits) and parses the result.
+//
+// Requires a `python3` interpreter at index time (TMCT_PYTHON overrides). This is
+// a runtime tool, not an npm dependency — no parser library ships. When no .py
+// files are present the subprocess never runs; when python3 is missing but .py
+// files exist, the backend degrades: it skips them and reports the count as
+// failures rather than crashing the whole index (JS/TS still produces its graph).
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { walk, relPath } from "./walk.mjs";
+import { exec } from "./spawn.mjs";
+
+const AST_SCRIPT = join(dirname(fileURLToPath(import.meta.url)), "extract_ast.py");
+const EXTS = [".py"];
+const PYTHON = () => process.env.TMCT_PYTHON || "python3";
+
+/** Ingest every .py file under `root` → {modules, failures, fileCount} contract.
+ *  `ignore` prunes the presence check; extract_ast.py applies its own SKIP_DIRS
+ *  when it walks, so the module set follows the script's exclusions. */
+export async function ingest(root, { ignore = null } = {}) {
+  const files = await walk(root, EXTS, ignore);
+  if (files.length === 0) return { modules: [], failures: [], fileCount: 0 };
+
+  const python = PYTHON();
+  const res = await exec(python, [AST_SCRIPT, root]);
+  if (res.code !== 0) {
+    const why = res.stderr.trim().split("\n").pop()?.slice(-200) || `exit ${res.code}`;
+    process.stderr.write(
+      `tmct index: python backend skipped ${files.length} .py file(s) — "${python}" unavailable or failed (${why})\n`,
+    );
+    return { modules: [], failures: files.map((f) => relPath(root, f)), fileCount: files.length };
+  }
+  let parsed;
+  try { parsed = JSON.parse(res.stdout); }
+  catch {
+    process.stderr.write(`tmct index: python backend produced non-JSON (is "${python}" a Python 3.9+ interpreter?)\n`);
+    return { modules: [], failures: files.map((f) => relPath(root, f)), fileCount: files.length };
+  }
+  const modules = Array.isArray(parsed?.modules) ? parsed.modules : [];
+  return { modules, failures: [], fileCount: files.length };
+}
+
+export const meta = { id: "ast", language: "python", lib: "python stdlib ast", exts: EXTS };

package/src/index/extract_ast.py

@@ -0,0 +1,364 @@
+#!/usr/bin/env python3
+"""Deterministic, offline static extraction for tmct (Python).
+
+Stdlib `ast` only — no third-party parser, no model calls. Walks every *.py file
+under repo_path and emits ONE JSON document on stdout:
+
+    {"modules": [
+        {"path": "<repo-relative>", "dotted": "django.utils.text",
+         "imports": ["django.utils.functional", ...],   # candidate dotted targets
+         "defines": [{"name": "slugify", "kind": "function", "lineno": 12,
+                      "decorators": ["register.filter(is_safe=True)"]},
+                     {"name": "Truncator", "kind": "class", "bases": ["object"], ...},
+                     {"name": "Truncator.chars", "kind": "method", ...},
+                     {"name": "Truncator.text", "kind": "attribute", ...}, ...],
+         "calls": ["str.strip", "re.sub", ...]},          # coarse callee names
+        ...
+    ]}
+
+Resolution of import candidates and call targets to internal modules happens in
+buildEntities against the registry of discovered modules — this script stays a
+pure per-file parser. Run: python3 extract_ast.py <repo_path>.
+"""
+
+import ast
+import json
+import os
+import sys
+
+SKIP_DIRS = {".git", ".tmct", ".hg", ".svn", "node_modules", ".venv", "venv",
+             "__pycache__", ".tox", ".mypy_cache", ".pytest_cache", "build", "dist"}
+
+
+def dotted_for(rel_path):
+    """Repo-relative .py path -> dotted module + its package."""
+    parts = rel_path[:-3].split(os.sep)  # drop ".py"
+    if parts and parts[-1] == "__init__":
+        parts = parts[:-1]
+        pkg = ".".join(parts)
+        return pkg, pkg  # a package: dotted == its own package
+    dotted = ".".join(parts)
+    pkg = ".".join(parts[:-1])
+    return dotted, pkg
+
+
+def import_targets(node, pkg):
+    """Candidate dotted module targets for one Import/ImportFrom node."""
+    out = []
+    if isinstance(node, ast.Import):
+        for alias in node.names:
+            out.append(alias.name)  # import a.b.c -> "a.b.c"
+    elif isinstance(node, ast.ImportFrom):
+        if node.level:  # relative: from . / from .mod import x
+            base_parts = pkg.split(".") if pkg else []
+            base_parts = base_parts[: len(base_parts) - (node.level - 1)] if node.level > 1 else base_parts
+            base = ".".join(base_parts)
+            mod = f"{base}.{node.module}" if node.module else base
+        else:
+            mod = node.module or ""
+        if mod:
+            out.append(mod)
+            # `from a.b import c` may import submodule a.b.c — record as a candidate too.
+            for alias in node.names:
+                if alias.name and alias.name != "*":
+                    out.append(f"{mod}.{alias.name}")
+    return out
+
+
+def decorator_str(dec):
+    try:
+        return ast.unparse(dec)
+    except Exception:
+        return ""
+
+
+def names_in_target(tgt):
+    """Plain-name assignment targets (Name, or Name elements of a Tuple/List)."""
+    if isinstance(tgt, ast.Name):
+        return [tgt.id]
+    if isinstance(tgt, (ast.Tuple, ast.List)):
+        out = []
+        for el in tgt.elts:
+            out.extend(names_in_target(el))
+        return out
+    return []
+
+
+# --- mechanical enrichments (deterministic ast facts; no type inference) ----------
+# params, return annotation, raises/catches, self-field access, static/abstract/
+# visibility flags, and the first docstring line. All are free from `ast` alone;
+# everything here stays honest (e.g. raises are the literal `raise` targets, not a
+# resolved type).
+
+def _unparse(node):
+    try:
+        return ast.unparse(node)
+    except Exception:
+        return ""
+
+
+def _exc_name(node):
+    """The named type of a raised/caught exception expression (drop the call args)."""
+    if isinstance(node, ast.Call):
+        node = node.func
+    return _unparse(node)
+
+
+def raised_excs(fn):
+    out = []
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Raise) and n.exc is not None:
+            nm = _exc_name(n.exc)
+            if nm:
+                out.append(nm)
+    return sorted(set(out))
+
+
+def caught_excs(fn):
+    out = []
+    for n in ast.walk(fn):
+        if isinstance(n, ast.ExceptHandler) and n.type is not None:
+            t = n.type
+            elts = t.elts if isinstance(t, (ast.Tuple, ast.List)) else [t]
+            for el in elts:
+                nm = _exc_name(el)
+                if nm:
+                    out.append(nm)
+    return sorted(set(out))
+
+
+def self_field_names(fn):
+    """`self.x` attribute names touched in a method body (read or write)."""
+    out = set()
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Attribute) and isinstance(n.value, ast.Name) and n.value.id == "self":
+            out.add(n.attr)
+    return sorted(out)
+
+
+def calls_in(fn):
+    """Coarse callee names invoked WITHIN one function/method body (for the
+    symbol-granular call graph). Names are the unparsed call target (e.g.
+    'helper', 'self.foo', 're.sub'); resolution to a single in-repo symbol id —
+    and the unique-name discipline — happens in buildEntities. Reuses the existing
+    per-function ast walk (no extra parse pass)."""
+    out = set()
+    for n in ast.walk(fn):
+        if isinstance(n, ast.Call):
+            try:
+                nm = ast.unparse(n.func)
+            except Exception:
+                nm = ""
+            if nm:
+                out.add(nm)
+    return sorted(out)
+
+
+def first_doc_line(node):
+    try:
+        d = ast.get_docstring(node, clean=True)
+    except Exception:
+        d = None
+    if not d:
+        return ""
+    return d.strip().split("\n", 1)[0].strip()[:120]
+
+
+def visibility_of(name):
+    short = name.rsplit(".", 1)[-1]
+    if short.startswith("__") and not short.endswith("__"):
+        return "private"
+    if short.startswith("_") and not short.startswith("__"):
+        return "protected"
+    return ""  # public is the default — omitted to keep the graph lean
+
+
+def func_extras(node, name, decorators, is_method):
+    """Compact, only-when-present enrichment dict for a function/method define."""
+    extras = {}
+    sig = _unparse(node.args)
+    if sig:
+        extras["params"] = sig[:160]
+    if getattr(node, "returns", None) is not None:
+        r = _unparse(node.returns)
+        if r:
+            extras["returns"] = r[:80]
+    raises = raised_excs(node)
+    if raises:
+        extras["raises"] = raises[:12]
+    catches = caught_excs(node)
+    if catches:
+        extras["catches"] = catches[:12]
+    if is_method:
+        fields = self_field_names(node)
+        if fields:
+            extras["self_fields"] = fields[:24]
+    # per-function callee names — the raw material for the symbol-granular
+    # callsSymbol edge (caller fn -> callee fn). Collected here so the subject
+    # (the enclosing def) is known; buildEntities resolves names to symbol ids.
+    callees = calls_in(node)
+    if callees:
+        extras["calls"] = callees[:50]
+    decset = " ".join(decorators)
+    if "staticmethod" in decset or "classmethod" in decset:
+        extras["is_static"] = True
+    if "abstractmethod" in decset or "abstractproperty" in decset:
+        extras["is_abstract"] = True
+    vis = visibility_of(name)
+    if vis:
+        extras["visibility"] = vis
+    doc = first_doc_line(node)
+    if doc:
+        extras["doc"] = doc
+    return extras
+
+
+def parse_module(src, rel_path):
+    dotted, pkg = dotted_for(rel_path)
+    try:
+        tree = ast.parse(src, filename=rel_path)
+    except (SyntaxError, ValueError):
+        return None  # skip unparseable files (py2 fixtures, templates, etc.)
+
+    imports = []
+    defines = []
+    calls = set()
+    globals_seen = set()
+    exports = []  # names in a literal __all__ (the module's declared public surface)
+
+    def string_list(v):
+        # names from a literal list/tuple of string constants (else [])
+        if not isinstance(v, (ast.List, ast.Tuple)):
+            return []
+        out = []
+        for el in v.elts:
+            if isinstance(el, ast.Constant) and isinstance(el.value, str):
+                out.append(el.value)
+        return out
+
+    def end_of(n):
+        return getattr(n, "end_lineno", None) or n.lineno
+
+    def short_value(v):
+        try:
+            s = ast.unparse(v)
+        except Exception:
+            return ""
+        return s.replace("\n", " ")[:80]
+
+    def add_global(name, target_node, value_node):
+        # Module-level "live object" globals (RHS is a call, e.g. register =
+        # template.Library()) and ALL-CAPS constants — the registration anchors and
+        # config values a sibling-adding task must replicate. Skip noisy locals.
+        if name in globals_seen or value_node is None:
+            return
+        is_call = isinstance(value_node, ast.Call)
+        if not (is_call or name.isupper()):
+            return
+        globals_seen.add(name)
+        rec = {"name": name, "kind": "global", "lineno": target_node.lineno,
+               "end_lineno": end_of(target_node), "decorators": [],
+               "value": short_value(value_node)}
+        if name.isupper():
+            rec["is_constant"] = True
+        vis = visibility_of(name)
+        if vis:
+            rec["visibility"] = vis
+        defines.append(rec)
+
+    # Top-level defs/classes, plus one level of class methods (e.g. Truncator.chars).
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            decs = [decorator_str(d) for d in node.decorator_list]
+            defines.append({"name": node.name, "kind": "function", "lineno": node.lineno,
+                            "end_lineno": end_of(node), "decorators": decs,
+                            **func_extras(node, node.name, decs, is_method=False)})
+        elif isinstance(node, ast.ClassDef):
+            cdoc = first_doc_line(node)
+            cvis = visibility_of(node.name)
+            cls_extra = {}
+            if cdoc:
+                cls_extra["doc"] = cdoc
+            if cvis:
+                cls_extra["visibility"] = cvis
+            defines.append({"name": node.name, "kind": "class", "lineno": node.lineno,
+                            "end_lineno": end_of(node),
+                            "bases": [decorator_str(b) for b in node.bases],
+                            "decorators": [decorator_str(d) for d in node.decorator_list],
+                            **cls_extra})
+            seen_attrs = set()
+            for sub in node.body:
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    mdecs = [decorator_str(d) for d in sub.decorator_list]
+                    defines.append({"name": f"{node.name}.{sub.name}", "kind": "method",
+                                    "lineno": sub.lineno, "end_lineno": end_of(sub),
+                                    "decorators": mdecs,
+                                    **func_extras(sub, f"{node.name}.{sub.name}", mdecs, is_method=True)})
+                elif isinstance(sub, ast.AnnAssign) and isinstance(sub.target, ast.Name):
+                    if sub.target.id not in seen_attrs:
+                        seen_attrs.add(sub.target.id)
+                        defines.append({"name": f"{node.name}.{sub.target.id}", "kind": "attribute",
+                                        "lineno": sub.lineno, "end_lineno": end_of(sub), "decorators": []})
+                elif isinstance(sub, ast.Assign):
+                    for tgt in sub.targets:
+                        for nm in names_in_target(tgt):
+                            if nm in seen_attrs:
+                                continue
+                            seen_attrs.add(nm)
+                            defines.append({"name": f"{node.name}.{nm}", "kind": "attribute",
+                                            "lineno": sub.lineno, "end_lineno": end_of(sub), "decorators": []})
+        elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            if node.target.id == "__all__" and node.value is not None:
+                exports = string_list(node.value)
+            else:
+                add_global(node.target.id, node, node.value)
+        elif isinstance(node, ast.Assign):
+            if any(isinstance(t, ast.Name) and t.id == "__all__" for t in node.targets):
+                exports = string_list(node.value)
+            else:
+                for tgt in node.targets:
+                    for nm in names_in_target(tgt):
+                        add_global(nm, node, node.value)
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            imports.extend(import_targets(node, pkg))
+        elif isinstance(node, ast.Call):
+            try:
+                name = ast.unparse(node.func)
+            except Exception:
+                name = ""
+            if name:
+                calls.add(name)
+
+    return {"path": rel_path.replace(os.sep, "/"), "dotted": dotted,
+            "imports": sorted(set(imports)), "defines": defines, "calls": sorted(calls),
+            "exports": exports}
+
+
+def main():
+    if len(sys.argv) < 2:
+        sys.stderr.write("usage: extract_ast.py <repo_path>\n")
+        sys.exit(2)
+    root = os.path.abspath(sys.argv[1])
+    modules = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in filenames:
+            if not fn.endswith(".py"):
+                continue
+            abs_path = os.path.join(dirpath, fn)
+            rel_path = os.path.relpath(abs_path, root)
+            try:
+                with open(abs_path, "r", encoding="utf-8") as fh:
+                    src = fh.read()
+            except (OSError, UnicodeDecodeError):
+                continue
+            mod = parse_module(src, rel_path)
+            if mod:
+                modules.append(mod)
+    json.dump({"modules": modules}, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()

package/src/index/index-repo.mjs

@@ -0,0 +1,173 @@
+// The deterministic, offline code-graph PRODUCER. Walks a repo, runs the
+// registered language extractors, reads git history, and assembles the typed
+// `entities` payload via graph-build.mjs's buildEntities() — the one write-path
+// primitive tmct already had but never called against real source. Writes
+// <repo>/.tmct/graph.json, the artifact the provider seam (source.mjs) reads.
+//
+// ZERO model calls: CPU-bound static parsing + git only. This is the write side
+// of the reader/producer boundary source.mjs documents — source.mjs READS a
+// graph, this module PRODUCES one; they are deliberately separate modules.
+
+import { writeFile, mkdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { buildEntities } from "../adapters/graph-build.mjs";
+import { ingestSchemaDocs } from "../tools/schema-docs.mjs";
+import { loadIgnores, relPath } from "./walk.mjs";
+import { ingestRepo, LANG_EXTS } from "./registry.mjs";
+import { exec } from "./spawn.mjs";
+
+// Every file extension the index covers — gates the git-log file filters so
+// history is collected for exactly the languages the extractors parsed.
+const INDEXED_EXTS = new Set(LANG_EXTS);
+const isIndexedFile = (f) => {
+  const dot = f.lastIndexOf(".");
+  return dot >= 0 && INDEXED_EXTS.has(f.slice(dot).toLowerCase());
+};
+
+const GIT_LOG_COMMITS = 300;      // module-level history depth (cheap; name-only)
+const HISTORY_SYMBOL_DEPTH = 120; // symbol-level line-range pass depth (the costly one)
+// Git history is the one place this producer shells an unbounded command over
+// arbitrary repo history, so it gets a hard wall-clock timeout: a wedged or
+// pathological `git log` can never hang an index.
+const GIT_TIMEOUT_MS = 300_000;
+
+function gitDepth(env = process.env) {
+  const n = Number(env.TMCT_GIT_DEPTH);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : GIT_LOG_COMMITS;
+}
+function historySymbolDepth(env = process.env) {
+  const raw = env.TMCT_HISTORY_SYMBOL_DEPTH;
+  if (raw === undefined || raw === "") return HISTORY_SYMBOL_DEPTH;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : HISTORY_SYMBOL_DEPTH;
+}
+
+/** A one-line failure reason for a git-history exec, or null on clean success.
+ *  Partial parseable output is ALWAYS kept by the caller — this only records WHY
+ *  the result may be incomplete, so an index never silently loses history edges
+ *  without saying so. */
+function gitPassError({ code, stderr, timedOut, truncated }) {
+  if (timedOut) return "timed out after 300s";
+  if (code !== 0) {
+    const tail = String(stderr || "").trim().split("\n").pop()?.slice(-200) || "";
+    return `git exited ${code}${tail ? `: ${tail}` : ""}`;
+  }
+  if (truncated) return "output truncated — history incomplete";
+  return null;
+}
+
+/** git log → {commits:[{sha, author, date, subject, files[]}], error}. Header
+ *  record fields are \x1e-separated; commits are \x1f-separated. */
+async function runGitLog(repoPath, depth = gitDepth()) {
+  const res = await exec("git",
+    ["log", "-n", String(depth), "--no-renames", "--name-only",
+      "--pretty=format:%x1f%H%x1e%an%x1e%aI%x1e%s"],
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const out = [];
+  for (const chunk of res.stdout.split("\x1f")) {
+    const nl = chunk.indexOf("\n");
+    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim();
+    if (!header) continue;
+    const [sha, author = "", date = "", subject = ""] = header.split("\x1e");
+    if (!sha) continue;
+    const files = (nl === -1 ? "" : chunk.slice(nl + 1))
+      .split("\n").map((l) => l.trim()).filter(isIndexedFile);
+    out.push({ sha: sha.trim(), author, date, subject, files });
+  }
+  return { commits: out, error: gitPassError(res) };
+}
+
+/** git log -p --unified=0 → {hunks:[{sha, ranges:{path:[[start,end],…]}}], error}.
+ *  Parses the NEW-side hunk header (`+c,d`) into the changed line range; the
+ *  assembly step intersects those with current symbol spans. Depth 0 → no pass. */
+async function runGitLogHunks(repoPath, depth = historySymbolDepth()) {
+  if (!depth) return { hunks: [], error: null };
+  const res = await exec("git",
+    ["log", "-n", String(depth), "--no-renames", "--no-color", "--unified=0",
+      "--pretty=format:%x1f%H"],
+    { cwd: repoPath, timeout: GIT_TIMEOUT_MS });
+  const out = [];
+  let cur = null;
+  let file = null;
+  for (const line of res.stdout.split("\n")) {
+    if (line.startsWith("\x1f")) {
+      cur = { sha: line.slice(1).trim(), ranges: {} };
+      if (cur.sha) out.push(cur); else cur = null;
+      file = null;
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith("+++ ")) {
+      const m = line.match(/^\+\+\+ b\/(.+?)\s*$/);
+      file = m && isIndexedFile(m[1]) ? m[1] : null;
+      if (file && !cur.ranges[file]) cur.ranges[file] = [];
+      continue;
+    }
+    if (file && line.startsWith("@@")) {
+      const m = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/);
+      if (!m) continue;
+      const start = Number(m[1]);
+      const count = m[2] === undefined ? 1 : Number(m[2]);
+      cur.ranges[file].push(count > 0 ? [start, start + count - 1] : [start, start]);
+    }
+  }
+  return { hunks: out, error: gitPassError(res) };
+}
+
+/** One repo's raw extraction — parsers + git, NO graph assembly. `historyDepth`:
+ *  undefined → defaults; 0 → skip both git passes; N>0 → cap both at N. */
+export async function extractRepo(repoPath, { ignores = true, historyDepth } = {}) {
+  const ignore = ignores ? await loadIgnores(repoPath) : null;
+  const skipHistory = historyDepth === 0;
+  const nameDepth = historyDepth === undefined ? gitDepth() : historyDepth;
+  const symbolDepth = historyDepth === undefined ? historySymbolDepth() : historyDepth;
+  // A git-less repo is a first-class case — no `.git`, no history, silently.
+  const hasGit = skipHistory ? false : await stat(join(repoPath, ".git")).then(() => true).catch(() => false);
+
+  const gitErrors = [];
+  const [langResult, gitLog] = await Promise.all([
+    ingestRepo(repoPath, { ignore }),
+    hasGit ? runGitLog(repoPath, nameDepth) : Promise.resolve({ commits: [], error: null }),
+  ]);
+  if (gitLog.error) gitErrors.push({ pass: "name-only", message: gitLog.error });
+
+  const runSymbol = hasGit && symbolDepth > 0;
+  const hunks = runSymbol ? await runGitLogHunks(repoPath, symbolDepth) : { hunks: [], error: null };
+  if (hunks.error) gitErrors.push({ pass: "symbol-hunk", message: hunks.error });
+
+  return {
+    modules: langResult.modules, perLang: langResult.perLang, failures: langResult.failures,
+    commits: gitLog.commits, symbolHistory: hunks.hunks, gitErrors,
+    historyDepth: { name: hasGit ? nameDepth : 0, symbol: runSymbol ? symbolDepth : 0 },
+  };
+}
+
+/** Assemble the entities payload from a raw extraction. Runs ingestSchemaDocs so
+ *  the written artifact is the writer-ingested form (the same convention the
+ *  committed fixtures carry — schema self-docs are baked in at produce time). */
+export function assembleEntities({ modules, commits = [], symbolHistory = [], generatedAt = "", prose = true }) {
+  const entities = buildEntities(modules, commits, { generatedAt, symbolHistory, prose });
+  ingestSchemaDocs(entities);
+  return entities;
+}
+
+/** Index a repo end to end: extract + assemble + write <repo>/.tmct/graph.json.
+ *  Returns {graphFile, bytes, modules, symbols, perLang, gitErrors, historyDepth}. */
+export async function indexRepository(repoPath, { ignores = true, historyDepth, prose = true, generatedAt } = {}) {
+  const raw = await extractRepo(repoPath, { ignores, historyDepth });
+  const entities = assembleEntities({
+    modules: raw.modules, commits: raw.commits, symbolHistory: raw.symbolHistory,
+    generatedAt: generatedAt ?? new Date().toISOString(), prose,
+  });
+  const graphFile = join(repoPath, ".tmct", "graph.json");
+  await mkdir(dirname(graphFile), { recursive: true });
+  const payload = JSON.stringify(entities);
+  await writeFile(graphFile, payload);
+  const symbols = raw.modules.reduce((n, m) => n + (m.defines?.length || 0), 0);
+  return {
+    graphFile, bytes: payload.length, modules: raw.modules.length, symbols,
+    perLang: raw.perLang, failures: raw.failures, gitErrors: raw.gitErrors, historyDepth: raw.historyDepth,
+  };
+}
+
+export { relPath };

package/src/index/registry.mjs

@@ -0,0 +1,37 @@
+// The extractor REGISTRY — the single place a language backend plugs in. Keyed
+// by language; `exts` is the file-extension surface it owns, `extractor` the
+// module that turns those files into the shared `{modules:[…]}` contract. Every
+// backend emits the SAME shape (path, dotted, imports, defines, calls, exports),
+// so everything downstream (index-repo.mjs, buildEntities) is language-agnostic.
+import * as jsts from "./extract-jsts.mjs";
+import * as python from "./extract-python.mjs";
+
+export const REGISTRY = {
+  "js/ts": { exts: jsts.meta.exts, extractor: jsts },
+  python: { exts: python.meta.exts, extractor: python },
+};
+
+/** The full set of file extensions the registry covers (sorted, lower-cased). */
+export const LANG_EXTS = [...new Set(Object.values(REGISTRY).flatMap((r) => r.exts))].sort();
+
+/** Parse every registered language under `root` and merge the per-language module
+ *  lists into one. Returns {modules, perLang, totalFiles, failures}. A language
+ *  with zero files present is silently absent from `perLang`. */
+export async function ingestRepo(root, { ignore = null } = {}) {
+  const allModules = [];
+  const perLang = {};
+  let totalFiles = 0;
+  const allFailures = [];
+  for (const [lang, { extractor }] of Object.entries(REGISTRY)) {
+    const t0 = Date.now();
+    const { modules, failures, fileCount } = await extractor.ingest(root, { ignore });
+    const ms = Date.now() - t0;
+    if (fileCount === 0) continue; // language not present
+    for (const m of modules) allModules.push(m);
+    totalFiles += fileCount;
+    for (const f of failures) allFailures.push(f);
+    const symbols = modules.reduce((n, m) => n + (m.defines?.length || 0), 0);
+    perLang[lang] = { lib: extractor.meta.lib, files: fileCount, modules: modules.length, symbols, failures: failures.length, ms };
+  }
+  return { modules: allModules, perLang, totalFiles, failures: allFailures };
+}

package/src/index/spawn.mjs

@@ -0,0 +1,35 @@
+// Shared child-process runner for the producer's out-of-process backends (git
+// history, the Python AST extractor). Collects stdout, never rejects, and arms an
+// optional SIGKILL wall-clock so a wedged subprocess can never hang an index.
+
+import { spawn } from "node:child_process";
+
+/** spawn, collect stdout; resolve {code, stdout, stderr, timedOut, truncated}
+ *  (never reject). `timeout` (ms, >0) arms a SIGKILL wall-clock; `truncated` is set
+ *  when stdout exceeded maxBuffer (dropped bytes → an incomplete result the caller
+ *  must NOT treat as authoritative). */
+export function exec(cmd, args, { cwd, maxBuffer = 512 * 1024 * 1024, timeout = 0 } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd });
+    let stdout = "";
+    let stderr = "";
+    let size = 0;
+    let truncated = false;
+    let timedOut = false;
+    const timer = timeout > 0 ? setTimeout(() => { timedOut = true; child.kill("SIGKILL"); }, timeout) : null;
+    child.stdout?.on("data", (d) => { size += d.length; if (size <= maxBuffer) stdout += d; else truncated = true; });
+    child.stderr?.on("data", (d) => (stderr += d));
+    child.on("close", (code) => {
+      if (timer) clearTimeout(timer);
+      if (timedOut) {
+        resolve({ code: -1, stdout, stderr: stderr + `timed out after ${Math.round(timeout / 1000)}s`, timedOut: true, truncated });
+      } else {
+        resolve({ code: code ?? -1, stdout, stderr, timedOut: false, truncated });
+      }
+    });
+    child.on("error", (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + String(err), timedOut, truncated });
+    });
+  });
+}

package/src/services/chat-session.mjs

@@ -332,9 +332,9 @@ export async function createSession({
     // no code graph → point at how to GET one (a graph producer / --repo / the shipped
     // example), and at what IS answerable now — `vocabHint` is only ever a term
     // confirmed to resolve in THIS session's actual seed state (see vocabExampleHint),
-    // never a hardcoded example that might not have been seeded. tmct reads graphs;
-    // it never indexes code itself.
-    ...(noCodeGraph ? [`for code structure, point me at a .tmct/graph.json with --repo <path> or try \`npm run example:mini\` (tmct reads graphs, it doesn't index code). ${vocabHint}`] : []),
+    // never a hardcoded example that might not have been seeded. tmct can index a
+    // repo itself (`tmct index`) or read a graph any other producer wrote.
+    ...(noCodeGraph ? [`for code structure, index this repo with \`tmct index\`, or point me at a .tmct/graph.json with --repo <path> (or try \`npm run example:mini\`). ${vocabHint}`] : []),
     "pass --repo <path> to target a different repo",
     "ask a question, or /help for commands (/stats for an overview) — /exit to leave",
   ];

package/src/services/chat.mjs

@@ -602,7 +602,7 @@ export function answerCount(graph, query) {
     // empty — an honest, non-dangling message pointing at how to load one.
     if (!kinds.length) {
       return `I can't count "${noun}" — no code graph is loaded yet, so there's nothing to count ` +
-        `(point me at one with --repo, or run "npm run example:mini").`;
+        `(index this repo with "tmct index", point me at another with --repo, or run "npm run example:mini").`;
     }
     return `I can't count "${noun}". I count: ${kinds.join(", ")}. ` +
       `Try "how many classes are there".`;
@@ -2077,8 +2077,8 @@ function orientationAnswer(templates, graph, vocabHint) {
  *  null), matching the file's "never crash, always degrade to one honest line"
  *  ethos. Kept short and hand-written so it never drifts silently. */
 const ORIENTATION_EMPTY_FALLBACK = "I'm tmct — a deterministic, offline chat assistant (no LLM). "
-  + "For code structure (imports, calls, definitions) point me at a repo with `--repo <path>`, "
-  + "or try the shipped example `npm run example:mini`. tmct reads graphs; it doesn't index code itself. /help for commands.";
+  + "For code structure (imports, calls, definitions) run `tmct index` here, point me at a repo with `--repo <path>`, "
+  + "or try the shipped example `npm run example:mini`. /help for commands.";
 
 /** A dynamic orientation string for the meta/self lane: a /stats-style overview
  *  when a code graph is loaded, else the honest empty-graph orientation — rendered
@@ -13009,8 +13009,8 @@ async function runAsk(query, { config, source, graph, focus, last, templates, me
       answer = `${answer}\n(I don't know that yet — you can teach me: say "remember: <thing> is a <kind>".)`;
       note(trace, "intermediate: HONEST-EMPTY POLISH — a browser miss points at the teach lane, not the CLI-only --repo remedy");
     } else {
-      answer = `${answer}\n(this repo has no code graph — for structure, point me at a \`.tmct/graph.json\` with \`--repo <path>\` or run \`npm run example:mini\`; tmct doesn't index code itself.)`;
-      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a --repo/tmct init pointer appended");
+      answer = `${answer}\n(this repo has no code graph — index it with \`tmct index\`, point me at a \`.tmct/graph.json\` with \`--repo <path>\`, or run \`npm run example:mini\`.)`;
+      note(trace, "intermediate: HONEST-EMPTY POLISH — the loaded graph has 0 modules, so the dead-end got a tmct index/--repo pointer appended");
     }
   }
   // TEACH-OFFER: a "what is X" miss where X is genuinely unknown EVERYWHERE —