@polycode-projects/seonix 0.2.1 → 0.4.0

package/README.md

@@ -1,38 +1,72 @@
 # @polycode-projects/seonix
 
 **A deterministic, offline, $0 code-graph tool that makes a cheap coding agent
-edit like an expensive one.** SEONIX indexes a repository with Python's `ast` +
-`git log` — **zero model calls** — into a typed code graph, then renders a bounded
-**edit digest** you inject once at session start. Your agent edits from turn 1
-without fishing through the repo.
+edit like an expensive one.** SEONIX indexes a repository with Python's `ast` and
+`git log`, with **zero model calls**, into a typed code graph, then renders a
+bounded **edit digest** you inject once at session start. Your agent edits from
+turn 1 without fishing through the repo.
 
-> **Headline.** On Django localisation tasks the no-MCP `seonix` digest cut input
-> tokens **+72% median on Sonnet 4.6** and **+65% on Haiku 4.5** (−58% billed cost
-> per both-solved task), **6/6 solved**, **$0 to index**. The win is
-> model-conditional — full method, numbers and the measurement contract are in the
-> repo.
+> **Headline.** Measured as **mean** input tokens per both-solved task (paired
+> arms, identical model pin). Under the shipped score-gap default (R1b), B017
+> re-tested across three models on a held-out TypeScript corpus and the existing
+> suites: two cells clear the ≥50% decision bar, both on exploration-bound
+> complex tasks — a TypeScript middleware task on **Haiku 4.5 at 59.6%** and a C#
+> service task on **Sonnet 4.6 at 53.5%** — with several more in the 35 to 48%
+> range. Across all measured cells the token cut tracks the turn cut
+> (Pearson 0.91): seonix saves tokens by removing exploration turns, so tasks
+> whose edit site is obvious change little. Indexing costs **$0**. The win is
+> task- and model-conditional; full method, numbers and the measurement contract
+> are in `BENCHMARK_017.md`.
 
 - **Website / live demo:** https://seonix.polycode.co.uk
 - **Source + benchmarks:** https://gitlab.com/polycode-projects/seonix
 - **Licence:** AGPL-3.0-only
 
+## Cross-model comparison
+
+seonix on the cheaper **Sonnet 4.6** vs the flagship **Opus 4.8** out of the box,
+mean input tokens per solved run (N=3; N=5 where an otb cell reuses the B015
+baseline). `+` means seonix on Sonnet used fewer tokens.
+
+| full task name | otb / Opus 4.8 | solved | seonix / Sonnet 4.6 | solved | token change |
+| --- | --- | --- | --- | --- | --- |
+| ts-hono-utils-helper (simple) | 135k | 3/3 | 117k | 3/3 | +13% |
+| ts-hono-response-time-middleware | 345k | 3/3 | 555k | 3/3 | −61% |
+| ts-hono-json-envelope | 1,102k | 3/3 | 864k | 3/3 | +22% |
+| py-django-truncatelines-filter | 610k | 5/5 | 524k | 5/5 | +14% |
+| cs-eshoponweb-order-service-total | 318k | 5/5 | 154k | 3/3 | +51% |
+| cs-eshoponweb-basket-service-total | 353k | 5/5 | 255k | 3/3 | +28% |
+| js-express-request-id | 330k | 5/5 | 267k | 3/3 | +19% |
+| js-express-json-envelope | 174k | 5/5 | 185k | 3/3 | −7% |
+
+seonix on Sonnet used fewer input tokens than otb on Opus on six of these eight
+tasks at equal correctness on these tasks. This crosses model and arm together, so
+it is an illustration of practical value, not the paired within-model measurement
+the ≥50% decision rule uses. Across all 13 measured seonix cells the drop in input
+tokens is 0.91-correlated (Pearson) with the drop in turns (slope about 0.71):
+seonix saves tokens by letting the agent skip exploration turns, so where it
+removes no turns there is little to save.
+
 ## Install
 
 ```bash
 npm i -g @polycode-projects/seonix        # global — gives you the `seonix` bin on PATH
 # or one-shot, no install:
-npx @polycode-projects/seonix index /abs/path/to/repo
+npx @polycode-projects/seonix cli index_repository '{"repo_path":"/abs/path/to/repo"}'
 ```
 
 **Runtime prerequisites:** Node ≥ 24, **Python 3**, and **git** on `PATH` (the
-indexer shells out to Python's `ast` and `git log`). Indexing is fully local and
-deterministic — no API keys, no network calls, **$0**.
+indexer shells out to Python's `ast` and `git log`). A Java runtime is needed
+only to index Java through JavaParser, and the .NET SDK only to index C# through
+Roslyn; without them, indexing for that language falls back to the bundled
+tree-sitter parser. Indexing is fully local and deterministic: no API keys, no
+network calls, **$0**.
 
 ## Quickstart
 
 ```bash
 # 1. index your repo (deterministic, offline) — writes a machine-local .seonix/
-seonix index /abs/path/to/repo
+seonix cli index_repository '{"repo_path":"/abs/path/to/repo"}'
 
 # 2. self-locate the touched modules from the task text (no human-chosen target)
 seonix cli seonix_search '{"repo_path":"/abs/path/to/repo","query":"<your task>"}'
@@ -44,15 +78,42 @@ seonix cli digest '{"repo_path":"/abs/path/to/repo","modules":["<top hits>"]}' >
 claude --prompt "Use the seonix digest below to localise and make the change. $(cat digest.txt)"
 ```
 
-Add `.seonix/` to your `.gitignore` — it is machine-local and rebuilt from source.
+Add `.seonix/` to your `.gitignore`; it is machine-local and rebuilt from source.
+
+## Indexing multiple repositories
+
+`index_repository` takes one of three argument forms:
+
+```bash
+# one repo (unchanged): artifacts to <repo_path>/.seonix/, module ids unprefixed
+seonix cli index_repository '{"repo_path":"/abs/repo"}'
+
+# n explicit repos, merged into ONE graph at <out_root>/.seonix/
+seonix cli index_repository '{"repo_paths":["/abs/repo1","/abs/repo2"],"out_root":"/abs/dir"}'
+
+# estate discovery: every immediate child directory of multi_root that contains a
+# .git (dir or file) is indexed as a repo; artifacts to <multi_root>/.seonix/
+seonix cli index_repository '{"multi_root":"/abs/estate"}'
+```
+
+The forms are mutually exclusive. `out_root` defaults to the deepest common
+ancestor directory of the paths (or the current directory if that ancestor is the
+filesystem root). In the merged graph every module id and label is prefixed with
+the repo's directory basename (`mod:<repoName>/<relpath>`); when two repos share a
+basename the first in path sort order keeps the bare name and later ones get `-2`,
+`-3`, … appended. Each repo's git history and `.seonixignore` are handled per repo,
+exactly as in single mode. Cross-repo call edges only arise where a symbol name
+resolves uniquely across the whole merged graph; ambiguous names are dropped, as
+within one repo. Query a merged graph by passing the merge root as `repo_path`
+(e.g. `seonix cli seonix_search '{"repo_path":"/abs/estate","query":"…"}'`).
 
 ## The shape that ships
 
 The product is the **no-MCP digest path**: render the digest, inject it once, run
-with **no server**. The interactive MCP tool loop is retired — even mitigated it
-never cleared the 50% bar; the round-trip *count*, not the resident schema, is the
-cost. Use `seonix_search` (`locate`, self-derives the target) in production; pass
-a known target (`oracle`) only to measure the headroom.
+with **no server**. The interactive MCP tool loop is retired. Even mitigated it
+never cleared the 50% bar, because the cost lies in the round-trip count rather
+than the resident schema. Use `seonix_search` (`locate`, self-derives the target)
+in production; pass a known target (`oracle`) only to measure the headroom.
 
 ## Visualise
 
@@ -60,18 +121,136 @@ a known target (`oracle`) only to measure the headroom.
 seonix viz --focus <Symbol> --out graph.html
 ```
 
-Renders a focused, portable Cytoscape sub-graph of the typed code-map as one
-self-contained HTML file — the same view that runs live on the website.
+Renders a focused, portable Cytoscape sub-graph of the typed code-map, the same
+view that runs live on the website. By default it also writes a `code-browser.html`
+and a `timeline.html` beside it with a working header nav; pass `--graph-only`
+for just the single self-contained graph file.
+
+## Chat
+
+```bash
+seonix chat [--repo /abs/path] [--with-claude | --with-copilot]
+```
+
+An interactive client over the typed code-graph (deterministic, no model calls).
+With no `--repo` the target defaults to the **git root** (`git rev-parse
+--show-toplevel`), so running it from a nested package dir still indexes the whole
+repo; pass `--repo <path>` to override. Any **bare line** is a plain-English
+question dispatched through the mechanical `seonix_ask` engine — e.g. `which
+modules import walk.mjs` — and the graph answers. Aggregate questions are answered
+straight off the graph header: `how many classes are there` → `20 classes.`
+(`how many <classes|functions|modules|methods|commits>`, `count the …`, `number of
+…`). A near-miss structural question still gets the precise rephrase hint.
+
+**Conversational manners** (deterministic, zero-model, recognised *before* any graph
+dispatch). A small closed set of everyday expressions gets a templated reply rather
+than a grammar hint:
+
+| you say | you get |
+| --- | --- |
+| `hi` / `hello` / `hey` / `yo` / `g'day` / `good morning` (and `hello there`, with a small nod) | a short greeting + a nudge to ask or `/help` |
+| `thanks` / `ta` / `cheers` / `ty` | an "any time" acknowledgement |
+| `help` / `what can you do` / `who are you` / `?` | the orientation (the friendly help text; see also `/help`, `/stats`) |
+| `bye` / `goodbye` / `quit` / `see ya` | a farewell **and a clean end of session** (flushes the log, closes — the `/exit` path) |
+| `why` / `how` / `explain` / `say more` / `go on` / `elaborate` | **re-renders the last answer verbosely** — repeats it with the ask engine's traversal receipt and the full matched-entity list the terse render trims (no previous answer → it says so plainly) |
+
+These turns resolve no code entity, so — like `/help` — they are recorded as plain
+turns and never add `mgx:asksAbout` edges to the session graph.
+
+**Slash-commands** reach every other query tool in one line each: `/find <query>`
+(or `/search`) for a lexical search; `/context <symbol>` for the sized edit bundle
+(start here to change code) and `/snippet <symbol>` for exact source; `/describe`,
+`/signature`, `/members <class>`, `/subclasses <class>`, `/impact <module>`,
+`/callers`, `/callees`, `/tests <symbol>`, `/untested`, `/history <symbol>`,
+`/exports <module>` and `/arch [package]`, plus `/stats` for a one-screen overview
+(entity counts, relationship counts, package totals). An unknown `/command` just
+nudges you to `/help`; a bad symbol prints the tool's own clean error, never a stack.
+
+The client tracks a **focus** entity for multi-turn context. A command or an answer
+that resolves a primary entity remembers it (the prompt shows it, `seon(walk.mjs)>`);
+a bare `it`/`this`/`that` in a question then binds to it, and a no-argument entity
+command (`/context`, `/impact`, …) reuses it — so `what calls it` works straight
+after `/describe walk.mjs`. Set it explicitly with `/focus <symbol>`. With no focus
+set the client stays single-shot. `/help` lists the commands and the question
+shapes; `/exit` (or Ctrl+C/Ctrl+D) leaves.
+
+Each session is appended per turn to `<repo>/.seonix/session-<uuidv7>.log`, and
+becomes first-class graph data like a commit — **slash-command turns included**: a
+structured sidecar (`.seonix/sessions/*.jsonl`) records each turn's query, the
+command used, and the entities it resolved/answered; the session enters `graph.json`
+as a `Session` individual with `mgx:asksAbout` edges wherever a turn resolved an
+entity (re-attached on every re-index), and it appears on the `seonix viz` timeline.
+
+### Opt-in LLM fallback (`--with-claude` / `--with-copilot`)
+
+**Default OFF. Chat-only. Never in the benchmark, digest, or MCP path.** With a flag
+set, and *only* when the mechanical engine returns a genuine **miss** on a bare
+question (after the conversational layer and slash-commands have had their turn),
+chat consults an external LLM CLI — spawned in the target repo as cwd, with a
+timeout. To keep answers **graph-grounded** it asks the model to *compile one seonix
+command* (given the tool surface), then runs that command mechanically and shows the
+grounded result, **labelled `[LLM-assisted via …]`**. If the model can't produce a
+valid command, its raw text is shown instead, clearly marked `[answer from external
+model … — NOT the deterministic seonix engine]`; the two are never silently blended.
+
+- `--with-claude` → `claude -p "<compile-prompt>" --model haiku` (cheapest model).
+- `--with-copilot` → `gh copilot -- -p "<compile-prompt>" --allow-all-tools --no-color`.
+  **Limitation, honestly:** the GitHub Copilot CLI is an *agentic shell assistant*
+  (its native verbs are running commands and editing files), not a graph Q&A tool —
+  it has no knowledge of the seonix query surface beyond what the prompt hands it, so
+  it's a poorer fit than `claude -p` and is wired best-effort. Prefer `--with-claude`.
+
+Any failure — tool binary absent, non-zero exit, unparseable output, or timeout —
+degrades to the normal honest-miss hint; the flag never crashes or hangs the chat. If
+the flag is set but the binary is missing, chat says so **once at startup** and
+continues mechanical-only. No LLM call is ever made unless the flag is set **and** the
+mechanical engine missed — the hot path (and every benchmark run) stays zero-model.
+
+A real transcript against this repository's own index (verified answers):
+
+```text
+seon> where is buildContextBundle defined
+function buildContextBundle() is defined in packages/seonix/src/server.mjs at lines 138-260.
+
+seon> what uses codegraph.mjs
+bench/arms.mjs and bench/run.mjs and packages/seonix/src/ask.mjs and
+packages/seonix/src/chat.mjs and packages/seonix/src/extract.mjs and
+packages/seonix/src/server.mjs and packages/seonix/src/viz.mjs and scripts/rank-gate.mjs.
+
+seon> when did walk.mjs change
+packages/seonix/src/walk.mjs was last touched by commit a73ac1ba8bfb on 2026-07-01
+("feat(seonix): .seonixignore excludes […]"); 1 earlier commit recorded.
+
+seon> which changes touch commit 85073031
+commit 85073031ff05 touched modules packages/seonix/src/viz.mjs and
+packages/seonix/test/viz.test.mjs; functions buildViewerData() and cytoscapeSource().
+
+seon> which functions call bulidContextBundle
+assuming you meant buildContextBundle: in packages/seonix/src/server.mjs
+there is function dispatchTool().
+```
+
+Question shapes: `which <functions|classes|modules> <import|call|use|test|touch> <name>`,
+`what does <module> <import|export>`, `what uses <name>`, `where is <name> defined`,
+`where is <name> mentioned`, `when did <name> change`, `which changes touch commit <sha>`,
+`what does <term> mean`. Misspellings are corrected from a curated table, close
+near-misses resolve through a bounded edit-distance pass and are announced
+("assuming you meant"), and anything the graph cannot answer is a stated miss with
+a rephrase hint, never a guess.
 
 ## Languages
 
-Python (stdlib `ast`), JS/TS (ts-morph), and C# (Roslyn, with a tree-sitter
-fallback) — all merged into the one typed graph. The C# extractor source ships in
-`roslyn/`; build it on the consumer side if you index C#.
+Python (stdlib `ast`), JS/TS (the TypeScript compiler API, including CommonJS
+`require`/`module.exports`), C# (Roslyn, with a tree-sitter fallback) and Java
+(JavaParser, with a tree-sitter fallback), all merged into the one typed graph. The C# Roslyn helper's source ships in the package under `roslyn/`; build
+it on the consumer side (needs the .NET SDK) if you index C#. The Java JavaParser
+helper is a jar built from the repository's `java/` directory (`mvn package`) and
+is not included in the npm package, so a package install indexes Java with the
+tree-sitter fallback.
 
 ## Licence & safety
 
-**AGPL-3.0-only.** The network clause is intended for a hosted MCP tool — hosted
-derivatives stay open. The `seonix:` ontology vocabulary is CC-BY-4.0 (NOTICE
+**AGPL-3.0-only.** The network clause is intended for a hosted MCP tool, so that
+hosted derivatives stay open. The `seonix:` ontology vocabulary is CC-BY-4.0 (NOTICE
 credits SEON + FAMIX). SEONIX never writes to your global agent config and never
 phones home; everything it writes lives under `.seonix/`.

package/bin/cli.mjs

@@ -6,6 +6,13 @@
 //   seonix cli index_repository '{"repo_path":"<abs>"}' → deterministic index
 //     (honours <repo>/.seonixignore — gitignore-subset patterns; pass
 //      `"ignores":false` in the JSON arg to index everything regardless)
+//   seonix cli index_repository '{"repo_paths":["<abs1>","<abs2>",…],"out_root":"<abs-dir>"}' → index
+//     n repos into ONE merged graph at <out_root>/.seonix/ (module ids prefixed with each repo's
+//     directory basename; out_root defaults to the paths' deepest common ancestor directory).
+//     Mutually exclusive with repo_path.
+//   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 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 +
@@ -19,9 +26,10 @@
 //     (e.g. seonix cli seonix_ask '{"query":"<free text>"}' — mechanical, no-LLM NL question
 //      over the graph, PLAN_MECHANICAL_CHAT.md; no bespoke wiring needed, this fallback covers it)
 //   seonix hook-augment                                 → PreToolUse Grep/Glob augmenter (stdin→stdout)
-//   seonix viz [--focus <sym>] [--depth N] [--out f.html] [--data-out f.json] [--repo-url <gitlab url> --ref main] [--site-nav] → render a focused sub-graph to HTML (one shared viewer; data embedded, or split out with --data-out)
-//   seonix viz --browser-out f.html [--browser-data-out f.json] [--scope product|<prefixes>] → also render the Chronograph code browser (temporal scrub + two-cursor diff + narration + ghost-branch merges + keyboard nav; PLAN_CODE_BROWSER.md)
+//   seonix viz [--focus <sym>] [--depth N] [--out f.html] [--data-out f.json] [--repo-url <gitlab url> --ref main] [--site-nav] → render a focused sub-graph to HTML (one shared viewer; data embedded, or split out with --data-out). By default also writes code-browser.html + timeline.html next to --out with a working header nav; --graph-only suppresses the siblings
+//   seonix viz --browser-out f.html [--browser-data-out f.json] [--timeline-out f.html] [--scope product|<prefixes>] → override the sibling artifact paths (Chronograph code browser: temporal scrub + two-cursor diff + narration + ghost-branch merges + keyboard nav; archive/PLAN_CODE_BROWSER.md)
 //   seonix viz --serve [--port N] [--focus <sym>]        → serve the same viewer against THIS repo's index (the local equivalent of the site's #viz; code browser at /code-browser.html, live-reannotating on HEAD change via /code-browser-version)
+//   seonix chat [--repo <abs>] [--with-claude|--with-copilot] → interactive prompt over the mechanical seonix_ask engine; /exit to leave; session log → <repo>/.seonix/session-<uuidv7>.log. The optional --with-* flags add an opt-in LLM fallback used ONLY when the mechanical engine misses a bare question (chat-only, never in the benchmark path)
 //
 // The index step is offline and model-free (Python ast + git). It writes the
 // graph artifact to <repo_path>/.seonix/graph.json; the server (started with
@@ -30,7 +38,7 @@
 import { join } from "node:path";
 import { startServer } from "../src/server.mjs";
 import { dispatchTool, buildContextBundle } from "../src/server.mjs";
-import { indexRepository } from "../src/extract.mjs";
+import { indexRepository, indexRepositories, discoverRepos } from "../src/extract.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";
@@ -173,29 +181,68 @@ async function main() {
   const [mode, sub, payload] = process.argv.slice(2);
 
   if (mode === "cli") {
-    // index mode: `cli index_repository '{"repo_path":"<abs>"}'`
+    // index mode: `cli index_repository '{"repo_path":"<abs>"}'` (single repo, unchanged),
+    // '{"repo_paths":[…],"out_root":"<abs>"}' (explicit n-repo merge) or
+    // '{"multi_root":"<abs>"}' (discover child repos, merge into <multi_root>/.seonix/).
     if (sub === "index_repository") {
       const args = parsePayload(payload);
       if (args === null) {
         process.stderr.write("seonix: index_repository expects a JSON arg, e.g. '{\"repo_path\":\"/abs\"}'\n");
         process.exit(2);
       }
-      const repoPath = args.repo_path;
-      if (!repoPath) {
-        process.stderr.write("seonix: index_repository requires repo_path\n");
+      const given = ["repo_path", "repo_paths", "multi_root"].filter((k) => args[k] !== undefined);
+      if (given.length > 1) {
+        process.stderr.write(`seonix: ${given.join(" + ")} are mutually exclusive — pass exactly one\n`);
+        process.exit(2);
+      }
+      if (given.length === 0) {
+        process.stderr.write("seonix: index_repository requires repo_path, repo_paths or multi_root\n");
         process.exit(2);
       }
       const t0 = Date.now();
-      const { graphFile, counts } = await indexRepository(repoPath, { ignores: args.ignores !== false });
-      process.stderr.write(
-        `seonix: indexed ${counts.modules} modules, ${counts.functions} symbols, ` +
-          `${counts.edges} edges (${counts.callsSymbol} callsSymbol, ${counts.touchesSymbol} touchesSymbol), ` +
-          `${counts.commits} commits in ${Date.now() - t0}ms → ${graphFile}\n`,
-      );
-      process.stderr.write(
-        `seonix: history-symbol pass +${counts.historyMs}ms over ${counts.baseMs}ms base ` +
-          `= ${counts.historyPct}% (depth ${counts.historySymbolDepth}; budget ≤10%)\n`,
-      );
+      const emitSummary = (graphFile, counts, head) => {
+        process.stderr.write(
+          `seonix: indexed ${head}${counts.modules} modules, ${counts.functions} symbols, ` +
+            `${counts.edges} edges (${counts.callsSymbol} callsSymbol, ${counts.touchesSymbol} touchesSymbol), ` +
+            `${counts.commits} commits in ${Date.now() - t0}ms → ${graphFile}\n`,
+        );
+        process.stderr.write(
+          `seonix: history-symbol pass +${counts.historyMs}ms over ${counts.baseMs}ms base ` +
+            `= ${counts.historyPct}% (depth ${counts.historySymbolDepth}; budget ≤10%)\n`,
+        );
+      };
+
+      if (args.repo_path) {
+        const { graphFile, counts } = await indexRepository(args.repo_path, { ignores: args.ignores !== false });
+        emitSummary(graphFile, counts, "");
+        return;
+      }
+
+      let repoPaths = args.repo_paths;
+      let outRoot = args.out_root || "";
+      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",
+        );
+        if (!repos.length) {
+          process.stderr.write("seonix: multi_root contains no repositories (no child directory has a .git)\n");
+          process.exit(2);
+        }
+        repoPaths = repos;
+        outRoot = args.multi_root;
+      }
+      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, {
+        ignores: args.ignores !== false,
+        outRoot,
+        log: (line) => process.stderr.write(`seonix: ${line}\n`),
+      });
+      emitSummary(graphFile, counts, `${repos.length} repos, `);
       return;
     }
 
@@ -315,13 +362,26 @@ async function main() {
     return;
   }
 
+  if (mode === "chat") {
+    const { runChat } = await import("../src/chat.mjs");
+    const i = process.argv.indexOf("--repo");
+    // Opt-in LLM fallback (chat-only, default OFF, miss-gated — never in the benchmark
+    // path): --with-claude shells `claude -p`, --with-copilot shells `gh copilot -- -p`.
+    await runChat({
+      repoPath: i !== -1 ? process.argv[i + 1] : undefined,
+      withClaude: process.argv.includes("--with-claude"),
+      withCopilot: process.argv.includes("--with-copilot"),
+    });
+    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 …`, `hook-augment`, or `viz`.\n");
+    "Use bare (MCP server), `cli index_repository …`, `cli <tool> …`, `chat`, `hook-augment`, or `viz`.\n");
   process.exit(2);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.2.1",
+  "version": "0.4.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,10 +45,12 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cytoscape": "^3.30.0",
-    "ts-morph": "^24.0.0",
     "tree-sitter": "^0.21.1",
     "tree-sitter-c-sharp": "^0.21.3",
-    "tree-sitter-java": "^0.21.0"
+    "tree-sitter-java": "^0.21.0",
+    "typescript": "~5.6.2",
+    "wink-eng-lite-web-model": "^1.8.1",
+    "wink-nlp": "^2.4.0"
   },
   "scripts": {
     "test": "node --test \"test/**/*.test.mjs\"",

package/roslyn/Program.cs

@@ -56,6 +56,20 @@ List<string> CallsIn(SyntaxNode body) {
         name = OneLine(name);
         if (name.Length > 0) set.Add(Clip(name, 80));
     }
+    // Object creations count as call edges to the created type: `new X(...)` → "X".
+    // Always the BARE type identifier (generics/qualifiers stripped) so extract.mjs's
+    // unique-lastIdent registry can resolve it to the internal Class. Implicit
+    // `new(...)` (no type syntax) is a different node type and stays excluded.
+    foreach (var oc in body.DescendantNodes().OfType<ObjectCreationExpressionSyntax>()) {
+        var t = oc.Type;
+        if (t is QualifiedNameSyntax q) t = q.Right; // rightmost identifier
+        string tn = t switch {
+            GenericNameSyntax g => g.Identifier.Text,
+            IdentifierNameSyntax id => id.Identifier.Text,
+            _ => null
+        };
+        if (!string.IsNullOrEmpty(tn)) set.Add(Clip(tn, 80));
+    }
     return set.ToList();
 }
 
@@ -66,6 +80,38 @@ string Vis(SyntaxTokenList mods) {
 }
 bool IsPublic(SyntaxTokenList mods) => mods.Any(m => m.Text == "public");
 
+// Nested types qualify as Outer.Inner (members then inherit it via cname+"."+member).
+string QualName(BaseTypeDeclarationSyntax t) {
+    var name = t.Identifier.Text;
+    for (var p = t.Parent; p is BaseTypeDeclarationSyntax outer; p = p.Parent)
+        name = outer.Identifier.Text + "." + name;
+    return name;
+}
+
+// kind stays "class" for every type declaration; subkind distinguishes the flavour
+// (record covers `record struct` too — same syntax node). Plain class → null (omitted).
+string SubkindOf(BaseTypeDeclarationSyntax t) => t switch {
+    InterfaceDeclarationSyntax => "interface",
+    EnumDeclarationSyntax => "enum",
+    RecordDeclarationSyntax => "record",
+    StructDeclarationSyntax => "struct",
+    _ => null
+};
+
+// First non-empty line of the XML doc comment (///), tags stripped, clipped to 120
+// chars — mirrors the Java extractor's javadoc emission (extract.mjs consumes d.doc).
+string DocOf(SyntaxNode n) {
+    foreach (var trivia in n.GetLeadingTrivia()) {
+        if (trivia.GetStructure() is not DocumentationCommentTriviaSyntax dc) continue;
+        var text = System.Text.RegularExpressions.Regex.Replace(dc.ToFullString(), "<[^>]*>", " ");
+        foreach (var rawLine in text.Split('\n')) {
+            var s = rawLine.Trim().TrimStart('/').Trim();
+            if (s.Length > 0) return Clip(s, 120);
+        }
+    }
+    return "";
+}
+
 var modules = new List<object>();
 var failures = new List<string>();
 
@@ -91,17 +137,34 @@ foreach (var file in files) {
     var defines = new List<object>();
     var exports = new SortedSet<string>(StringComparer.Ordinal);
 
-    foreach (var type in rootNode.DescendantNodes().OfType<TypeDeclarationSyntax>()) {
-        var cname = type.Identifier.Text;
-        var bases = type.BaseList?.Types.Select(t => Clip(OneLine(t.ToString()), 80)).ToList() ?? new List<string>();
+    // BaseTypeDeclarationSyntax covers classes/interfaces/structs/records AND enums
+    // (TypeDeclarationSyntax alone missed EnumDeclarationSyntax entirely). Document
+    // order, so nested types follow their parent — names qualify via QualName.
+    foreach (var btd in rootNode.DescendantNodes().OfType<BaseTypeDeclarationSyntax>()) {
+        var cname = QualName(btd);
+        var bases = btd.BaseList?.Types.Select(t => Clip(OneLine(t.ToString()), 80)).ToList() ?? new List<string>();
         var cdef = new Dictionary<string, object> {
-            ["name"] = cname, ["kind"] = "class", ["lineno"] = LineOf(type), ["end_lineno"] = EndLineOf(type),
-            ["bases"] = bases, ["decorators"] = type.AttributeLists.SelectMany(a => a.Attributes).Select(a => OneLine(a.ToString())).ToList()
+            ["name"] = cname, ["kind"] = "class", ["lineno"] = LineOf(btd), ["end_lineno"] = EndLineOf(btd),
+            ["bases"] = bases, ["decorators"] = btd.AttributeLists.SelectMany(a => a.Attributes).Select(a => OneLine(a.ToString())).ToList()
         };
-        if (IsPublic(type.Modifiers)) exports.Add(cname);
-        var v = Vis(type.Modifiers); if (v != "") cdef["visibility"] = v;
+        var subkind = SubkindOf(btd); if (subkind != null) cdef["subkind"] = subkind;
+        var cdoc = DocOf(btd); if (cdoc != "") cdef["doc"] = cdoc;
+        if (IsPublic(btd.Modifiers)) exports.Add(cname);
+        var v = Vis(btd.Modifiers); if (v != "") cdef["visibility"] = v;
         defines.Add(cdef);
 
+        if (btd is EnumDeclarationSyntax en) {
+            foreach (var em in en.Members) {
+                defines.Add(new Dictionary<string, object> {
+                    ["name"] = $"{cname}.{em.Identifier.Text}", ["kind"] = "attribute",
+                    ["lineno"] = LineOf(em), ["end_lineno"] = EndLineOf(em), ["decorators"] = new List<string>(),
+                    ["is_constant"] = true
+                });
+            }
+            continue;
+        }
+        if (btd is not TypeDeclarationSyntax type) continue;
+
         foreach (var mem in type.Members) {
             if (mem is MethodDeclarationSyntax m) {
                 var md = new Dictionary<string, object> {
@@ -113,19 +176,24 @@ foreach (var file in files) {
                 };
                 if (m.Modifiers.Any(x => x.Text == "static")) md["is_static"] = true;
                 var mv = Vis(m.Modifiers); if (mv != "") md["visibility"] = mv;
+                var mdoc = DocOf(m); if (mdoc != "") md["doc"] = mdoc;
                 defines.Add(md);
             } else if (mem is ConstructorDeclarationSyntax ctor) {
-                defines.Add(new Dictionary<string, object> {
+                var ctd = new Dictionary<string, object> {
                     ["name"] = $"{cname}.{ctor.Identifier.Text}", ["kind"] = "method",
                     ["lineno"] = LineOf(ctor), ["end_lineno"] = EndLineOf(ctor), ["decorators"] = new List<string>(),
                     ["params"] = Clip(OneLine(string.Join(", ", ctor.ParameterList.Parameters.Select(p => p.ToString()))), 160),
                     ["calls"] = CallsIn(ctor.Body as SyntaxNode ?? ctor.ExpressionBody)
-                });
+                };
+                var cdoc2 = DocOf(ctor); if (cdoc2 != "") ctd["doc"] = cdoc2;
+                defines.Add(ctd);
             } else if (mem is PropertyDeclarationSyntax prop) {
-                defines.Add(new Dictionary<string, object> {
+                var pd = new Dictionary<string, object> {
                     ["name"] = $"{cname}.{prop.Identifier.Text}", ["kind"] = "attribute",
                     ["lineno"] = LineOf(prop), ["end_lineno"] = EndLineOf(prop), ["decorators"] = new List<string>()
-                });
+                };
+                var pdoc = DocOf(prop); if (pdoc != "") pd["doc"] = pdoc;
+                defines.Add(pd);
             } else if (mem is FieldDeclarationSyntax fld) {
                 foreach (var vd in fld.Declaration.Variables) {
                     defines.Add(new Dictionary<string, object> {