@polycode-projects/seonix 0.2.0 → 0.3.0

package/README.md

@@ -1,21 +1,49 @@
 # @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.
-
-> **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.
+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.** Measured as **mean** input tokens per both-solved task (paired
+> arms, identical model pin): on the Django localisation suite the no-MCP
+> `seonix` digest cut mean input tokens **38% on Haiku 4.5** (`BENCHMARK_016.md`
+> restatement, N=5). Under the score-gap default shipped 2026-07-02 (R1b), the
+> re-tested Django cell on Sonnet 4.6 shows a **41% mean** cut and a C# cell on
+> Sonnet 4.6 shows **57.9% mean**, clearing the ≥50% decision bar. Indexing costs
+> **$0**. The win is model-conditional; full method, numbers and the measurement
+> contract are in the repo.
 
 - **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
@@ -25,8 +53,11 @@ npx @polycode-projects/seonix index /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
 
@@ -44,15 +75,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
 
@@ -61,17 +119,68 @@ 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.
+self-contained HTML file, the same view that runs live on the website.
+
+## Chat
+
+```bash
+seonix chat [--repo /abs/path]
+```
+
+An interactive prompt over the mechanical `seonix_ask` engine (deterministic, no
+model calls): type a question about the indexed codebase — e.g. `which modules
+import walk.mjs` — and the graph answers; `/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: a structured sidecar
+(`.seonix/sessions/*.jsonl`) records which entities each turn asked about, the
+session enters `graph.json` as a `Session` individual with `mgx:asksAbout` edges
+(re-attached on every re-index), and it appears on the `seonix viz` timeline.
+
+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 (ts-morph), 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>]                           → interactive prompt over the mechanical seonix_ask engine; /exit to leave; session log → <repo>/.seonix/session-<uuidv7>.log
 //
 // 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,6 +362,13 @@ async function main() {
     return;
   }
 
+  if (mode === "chat") {
+    const { runChat } = await import("../src/chat.mjs");
+    const i = process.argv.indexOf("--repo");
+    await runChat({ repoPath: i !== -1 ? process.argv[i + 1] : undefined });
+    return;
+  }
+
   if (mode === undefined) {
     await startServer(); // bare invocation → MCP stdio server
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polycode-projects/seonix",
-  "version": "0.2.0",
+  "version": "0.3.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> {

package/src/ask-nlp.mjs

@@ -0,0 +1,73 @@
+// ask-nlp.mjs — the OPTIONAL wink-nlp adapter behind ask.mjs's lemma/POS tier.
+//
+// BOUNDARY (hard, do not move): this file is Node-only and is NEVER inlined into
+// the viewer bundle. viz.mjs's askSource() inlines codegraph.mjs + ask-vocab.mjs +
+// ask.mjs ONLY and strips their import lines, so the portable single-file HTML has
+// no wink, no model, and no `nlpAdapter` binding at all — ask.mjs reaches this
+// module exclusively through a `typeof nlpAdapter === "function"` guard and
+// degrades to adapter-less parsing (lemma/POS tiers off; the curated tables and
+// the bounded edit-distance tier still work, browser and Node alike). Keeping the
+// ~1MB CJS model out of the page is the point of the split.
+//
+// wink-nlp and wink-eng-lite-web-model are CJS — loaded via createRequire, the
+// same Node-module-resolution approach viz.mjs uses to locate cytoscape (resolve
+// through the module system, never a guessed path). The require happens lazily on
+// first use and failure is cached as null: a checkout without the optional deps
+// installed answers exactly like the browser bundle, it never throws.
+
+import { createRequire } from "node:module";
+
+let cached; // undefined = not tried yet; null = unavailable (tried once, honestly off)
+
+/** Lazily build the {lemma, posTags} adapter, or null when wink isn't loadable.
+ *  Deterministic: wink-nlp's tagger/lemmatiser is a fixed model with no sampling,
+ *  so the same input always yields the same tags/lemmas across processes. */
+export function nlpAdapter() {
+  if (cached !== undefined) return cached;
+  try {
+    const require = createRequire(import.meta.url);
+    const winkNLP = require("wink-nlp");
+    const model = require("wink-eng-lite-web-model");
+    const nlp = winkNLP(model);
+    const its = nlp.its;
+    cached = {
+      /** Lowercase lemma of a single token ("imported" -> "import"); the word
+       *  itself when wink has nothing better (unknown words come back as-is). */
+      lemma(word) {
+        const w = String(word || "");
+        try {
+          const out = nlp.readDoc(w).tokens().out(its.lemma);
+          return String(out[0] || w).toLowerCase();
+        } catch {
+          return w.toLowerCase();
+        }
+      },
+      /** UPOS tags aligned to the CALLER's word array. wink re-tokenizes (it
+       *  splits "walk.mjs" into three tokens), so each input word is greedily
+       *  matched to the run of wink tokens that spell it and takes its FIRST
+       *  sub-token's tag; null per word on any surprise, never a throw. */
+      posTags(words) {
+        try {
+          const toks = nlp.readDoc(words.join(" ")).tokens();
+          const texts = toks.out();
+          const tags = toks.out(its.pos);
+          const out = [];
+          let k = 0;
+          for (const w of words) {
+            if (k >= texts.length) { out.push(null); continue; }
+            out.push(tags[k]);
+            let acc = texts[k];
+            k += 1;
+            while (acc.length < w.length && k < texts.length) { acc += texts[k]; k += 1; }
+          }
+          return out;
+        } catch {
+          return words.map(() => null);
+        }
+      },
+    };
+  } catch {
+    cached = null;
+  }
+  return cached;
+}