@polycode-projects/seonix 0.6.1 → 0.7.1

package/README.md

@@ -110,10 +110,286 @@ within one repo. Query a merged graph by passing the merge root as `repo_path`
 ## 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, 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.
+with **no server**. The stdio MCP server still ships and is fully supported (bare
+`seonix` starts it) — it's just not the recommended default, because even
+mitigated the interactive tool loop never cleared the 50% bar: 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.
+
+## CLI reference
+
+Every invocation shape `bin/cli.mjs` dispatches on, verified against the current source.
+
+### Bare invocation — MCP stdio server
+
+```bash
+seonix
+```
+
+No flags, no config file. Starts the stdio MCP server against
+`<cwd>/.seonix/graph.json` (override with `SEONIX_GRAPH_FILE`). MCP launchers
+should start it with cwd = the indexed worktree.
+
+### `cli index_repository` — build the graph
+
+```bash
+seonix cli index_repository '{"repo_path":"/abs/repo"}'
+seonix cli index_repository '{"repo_paths":["/abs/repo1","/abs/repo2"],"out_root":"/abs/dir"}'
+seonix cli index_repository '{"multi_root":"/abs/estate"}'
+```
+
+`repo_path` / `repo_paths`+`out_root` / `multi_root` are mutually exclusive — pass
+exactly one (or let `seonix.toml`'s `repositories` supply the set when none is
+given explicitly). Shared JSON options:
+
+- `ignores` (bool, default `true`) — honour the repo's `.seonixignore`. Pass
+  `"ignores":false` to index everything regardless (the bench harness always
+  passes this, so a subject repo's own `.seonixignore` never shapes an arm's index).
+- `config` (bool, default `true`) — read `seonix.toml` from the target dir. Pass
+  `"config":false` to skip it entirely (byte-identical to no-file behaviour; the
+  bench harness's index/locate/digest calls always pass this).
+- `sync` (bool) — on a `multi_root` call, `"sync":true` routes through the same
+  incremental path as `cli sync` instead of a full re-index.
+- `history_depth` (non-negative integer) — cap on the git-history pass (both the
+  commit walk and the history-symbol pass). `0` skips git history entirely;
+  absent uses the default depth. Precedence: this arg > `seonix.toml`
+  `[index].history_depth` > default.
+
+Writes `<out_root-or-repo_path>/.seonix/graph.json` (+ manifest for
+`multi_root`/`sync`), prints indexed counts to stderr and a human summary MD to
+stdout.
+
+### `cli sync` — incremental estate re-index
+
+```bash
+seonix cli sync '{"multi_root":"/abs/estate"}'
+```
+
+Fingerprints every child repo of `multi_root` and re-extracts only the ones that
+changed since the last run (per-repo cache under `.seonix/cache/`); one union
+rebuild is exact-equal to a full re-index, and an unchanged estate is a byte-stable
+no-op. Accepts `ignores` and `history_depth` as above. Writes
+`.seonix/manifest.json`.
+
+### `cli digest` — the no-MCP injection payload
+
+```bash
+seonix cli digest '{"repo_path":"/abs/repo","modules":["path/to/mod.mjs","other/mod.py"]}'
+seonix cli digest '{"repo_path":"/abs/repo","query":"add a truncate filter to the article view"}'
+```
+
+Two ways to pick the modules: an explicit `modules` array, or a `query` string —
+`query` auto-locates and score-gap-selects the modules in one call (`modules`
+wins if both are given). Prints an architecture map + a size-adaptive context
+bundle per module to stdout, headed by a machine-readable line the rig parses:
+`# seonix-digest tier=<NONE|TINY|MID|LARGE|FULL> topup=<bool> modules=<N>
+[selected=<comma-list>]` (`selected=` only appears in query mode).
+
+Tuning flags (all optional, precedence explicit arg > `seonix.toml [tune]` >
+shipped default):
+
+- `top_k` (int, query mode only, default 2) — how many modules `query` mode selects.
+- `score_gap` (number, or `false` to disable) — the score-gap cutoff for query-mode selection.
+- `literal_mention` (bool, default `true`) — credit verbatim dotted-name/path mentions in the raw query text.
+- `min` (bool) — force the leanest bundle (no auto top-up).
+- `untuned` (bool) — the pre-tuning escalation behaviour.
+- `max` (bool) — the injection ceiling: every requested module gets a FULL (untrimmed) bundle instead of primary-full + capped trimmed secondaries.
+
+### `cli seonix_locate` — ranked module list (recall probe)
+
+```bash
+seonix cli seonix_locate '{"query":"…","repo_path":"/abs/repo"}'
+```
+
+Prints `<relpath>\t<score>` per line, highest first — the raw ranking a caller
+(or the rig) can threshold itself. Recall/precision levers, all optional
+(precedence arg > `seonix.toml [tune]` > default, all default `false` unless noted):
+
+- `demote_nonprod` — demote `examples/`/`fixtures/`/`test-*` paths.
+- `call_adjacency` — resolved-call adjacency bonus.
+- `impl_of_interface` — C# impl-of-interface boost.
+- `beam_search` (+ `beam_width`) — multi-ply discriminative beam expansion.
+- `literal_mention` (default `true`) — verbatim dotted-name/path mention matching against the raw query.
+- `raw_query` — forward a separately-normalized raw problem text for literal matching (else derived from `query`).
+- `spiral` (+ `spiral_depth`, `limit`) — a bounded-radius, degree-ordered ego-neighbourhood walk from the lexical seeds that can surface lexically-invisible modules. `spiral_depth` is the hop radius (only honoured if `>0`); `limit` overrides how many newly-reached nodes the spiral may surface (default 100 — deliberately above the internal 12-node default, since this CLI surface is a recall probe, not a token budget).
+
+### `cli browser_link` — NL request → Chronograph URL
+
+```bash
+seonix cli browser_link '{"query":"classes that change with render","base":"https://example.com"}'
+```
+
+Maps a natural-language-ish request to the code-browser query grammar
+deterministically (no model call), self-tests the resulting link against the
+local temporal graph (must match ≥1 node and every cursor must resolve), then
+prints the URL — or exits 1 with the failure reason(s) rather than printing a
+dead link. Accepts `repo_path` (which repo's graph to test against), `base` (the
+URL prefix the link is built on), `at` / `b` (the two temporal cursors — single
+cursor / diff-cursor), `scope` (restrict the graph to a package-prefix set,
+same values as `viz --scope`), and `grammar:true` (take `query` as grammar
+verbatim, skipping NL mapping).
+
+### `cli store_rebuild` — force-rebuild the sqlite store
+
+```bash
+seonix cli store_rebuild '{"repo_path":"/abs/repo"}'
+```
+
+Force-(re)builds the opt-in `node:sqlite` resident store (see
+[SEONIX_STORE](#seonix_store--seonix_graph_format) below) from the current
+`graph.json`. The store is a derived, rebuildable companion — read paths never
+auto-build it, so this is the explicit way to (re)materialize it after an index
+or a manual `graph.json` edit.
+
+### `cli <toolName>` — generic MCP tool fallback
+
+```bash
+seonix cli seonix_ask '{"query":"which modules import codegraph"}'
+seonix cli seonix_context '{"symbol":"buildContextBundle","repo_path":"/abs/repo"}'
+```
+
+Any sub-command name that isn't one of the above routes straight to the MCP tool
+dispatcher, so any tool in the server's surface — cold or hot — is invokable from
+Bash with no MCP connection. `repo_path` in the JSON arg selects the target
+graph; every other key is passed through as the tool's own arguments.
+
+### `hook-augment` — PreToolUse Grep/Glob augmenter
+
+```bash
+seonix hook-augment   # reads a PreToolUse hook event JSON from stdin
+```
+
+Reads the hook event from stdin, extracts the Grep/Glob pattern, and — if the
+local graph has a hit — writes `{hookSpecificOutput:{hookEventName,
+additionalContext}}` to stdout so the agent sees seon typed-graph hits alongside
+its own search. Silent (exit 0, no output) on any failure — empty/malformed
+input, no graph, no hit — the **never-block contract**.
+
+### `init [--dotnet]` — seed a seonix.toml
+
+```bash
+seonix init             # single-repo template
+seonix init --dotnet     # estate/.NET template (repositories + broader include_text/exclude)
+seonix init --force      # overwrite an existing seonix.toml
+```
+
+Copies the shipped template to `./seonix.toml` (byte-for-byte). Refuses to
+overwrite an existing file unless `--force` (exit 2).
+
+### `config --effective [--repo <abs>]`
+
+```bash
+seonix config --effective
+seonix config --effective --repo /abs/repo
+```
+
+Prints the merged `{effective, sources}` config (sorted keys) as JSON — every
+knob's resolved value plus which source won it (`"arg"` | `"seonix.toml"` |
+`"default"`). `--repo` defaults to cwd. Requires `--effective`; without it,
+prints usage and exits 2.
+
+### `viz` — render the code-map / code-browser / timeline
+
+```bash
+seonix viz --focus <Symbol> --out graph.html
+seonix viz --serve --port 8080 --focus <Symbol>
+```
+
+Flags: `--focus <sym>` (default: highest-degree module), `--depth N` (default 2),
+`--hub N` (hub-degree cap, default 40), `--max N` (node cap, default 200), `--out
+f.html` (default `seon-graph.html`), `--data-out f.json` (split viewer + sidecar
+data file instead of embedding), `--graph <path>` (override the graph.json
+location), `--repo-url <url> --ref <branch>` (source links), `--site-nav`
+(add the site's absolute home entry), `--nlp` (include the optional wink-nlp
+lemma tier in the chat panel), `--force-inline` (embed the full graph inline even
+past the size gate that would otherwise split it out with a message).
+
+By default `viz` also writes a `code-browser.html` (Chronograph) and a
+`timeline.html` next to `--out` with a working header nav; override their paths
+with `--browser-out f.html` / `--browser-data-out f.json` / `--timeline-out
+f.html`, or suppress both siblings with `--graph-only`. `--scope
+product|<prefixes>` filters the Chronograph browser/timeline to a package
+prefix set. `--limit N` caps the commit timeline to the newest N commits (0 =
+unlimited; default 100 — an estate-scale timeline stays openable, with a "newest
+N of M" header note when truncated).
+
+`--serve [--port N]` serves the same viewer live against this repo's own index
+(code browser at `/code-browser.html`, alias `/browser`; timeline at
+`/timeline.html`; live re-annotates on HEAD change via `/code-browser-version`) —
+port 0 (default) picks a free port.
+
+### `chat` — interactive client over the mechanical ask engine
+
+```bash
+seonix chat [--repo /abs/path] [--with-claude|--with-copilot]
+```
+
+See [Chat](#chat) below for the full behaviour (slash-commands, focus tracking,
+conversational manners, session logging, the opt-in `--with-claude`/
+`--with-copilot` LLM fallback).
+
+### `SEONIX_STORE` / `SEONIX_GRAPH_FORMAT`
+
+Two opt-in/opt-out environment knobs, orthogonal to everything above:
+`SEONIX_STORE=sqlite` turns on the resident `node:sqlite` store as a derived,
+rebuildable companion to `graph.json` (rebuild it explicitly with `cli
+store_rebuild`; unset, nothing sqlite loads). `SEONIX_GRAPH_FORMAT` controls the
+graph's on-disk wire format — the interned v2 form is the shipped default;
+set `SEONIX_GRAPH_FORMAT=1` to opt back out to the legacy v1 form.
+
+## Configuration (seonix.toml)
+
+An optional `seonix.toml` at a repo (or estate) root steers indexing and
+scoring. Absent file = shipped defaults, byte-for-byte today's behaviour.
+`seonix init` (or `seonix init --dotnet` for an estate) seeds a commented
+template — see `packages/seonix/templates/seonix.toml` and
+`templates/seonix-dotnet.toml` for the full annotated reference.
+
+- **`repositories`** — the repo set for an estate config: an inline array of
+  paths, or a string naming a newline-delimited file (both resolved relative
+  to the config file). Only consulted when no explicit `repo_path` /
+  `repo_paths` / `multi_root` arg is given.
+- **`out_root`** — where the merged graph artifact is written (default `.`).
+- **`[index]`**
+  - `languages` — the AST languages to parse (`javascript`, `typescript`, `python`, `csharp`, `java`, …).
+  - `exclude` — additive glob excludes on top of `.seonixignore` (ordered; a leading `!` re-includes).
+  - `secret_exclude` — a hard, fail-safe-ON glob list (env files, keys, certs) that is never indexed and never grabbed as text, even as a text/structure source.
+  - `history_depth` — cap on the git-history pass (0 = skip entirely). Precedence: CLI arg > this key > default.
+  - `include_text`, `include_structure`, `respect_gitignore`, `markdown_sections`, `vue` — recognized and normalized, but **not yet wired to a consumer** (see "unwired keys" below).
+- **`[tune]`** — the locate/digest scoring knobs: `score_gap_k`, `literal_mention` (shipped default `true`), `demote_non_prod`, `call_adjacency`, `impl_of_interface`, `beam_search` (+ `beam_width`), `embed_rank`, `prose_layers`.
+- **`[tune.expansion]`** — graph-traversal expansion mode used by locate/the viewer's navigation: `strategy` (`none` | `beam` | `spiral` | `ppr`; `none` is the byte-identical shipped default), `nodes` (breadth/token-budget cap), `q` (proportion of most-distinctive neighbours followed per step), `depth` (hop radius).
+- **`[telemetry]`** — `enabled = true` opts in (see [Telemetry](#telemetry) below).
+
+**Precedence, everywhere:** explicit CLI arg > `seonix.toml` value > shipped
+default. `seonix cli … '{"config":false}'` (always set on the bench path) skips
+reading `seonix.toml` entirely, so a subject repo's config file can never shape
+a benchmark arm. A `seonix.toml` key that parses and normalizes but has no
+wired consumer yet (`index.include_text`, `index.include_structure`,
+`index.respect_gitignore`, `index.markdown_sections`, `index.vue`) triggers a
+one-time stderr warning per process rather than silently doing nothing.
+`seonix config --effective [--repo <abs>]` prints the fully merged config plus,
+per key, which source won it.
+
+## Telemetry
+
+Opt-in, off by default, and the OFF path is **byte-identical** to no telemetry
+existing at all — no file, no stdout/stderr change. Turn it on with
+`SEONIX_TELEMETRY=1` (env always wins both directions — `SEONIX_TELEMETRY=0`
+force-disables even if the toml turns it on) or `[telemetry] enabled = true` in
+`seonix.toml`.
+
+When enabled, each `cli` invocation (digest / locate / the generic tool
+fallback) appends fire-and-forget JSONL lines to
+`<repo>/.seonix/seonix-<uuidv7>.log` — one line per query, schema-versioned
+(`v: 1`) with an `id` (the invocation id, reusable across a host's own trace
+via `SEONIX_INVOCATION_ID`), a monotonic `seq`, and per-surface fields
+(`query`, `response`, `perf`, `cost`). A structural redactor drops any
+`text`/`content`/`snippet` field at any depth and truncates long strings —
+**telemetry never records file contents**, only ids/paths/scores/sizes/counts.
+Writes are swallowed on error: telemetry can never throw, block a query, or
+touch stdout (stdout is the MCP transport / the digest injected into the
+no-MCP arm).
 
 ## Visualise