@qe-mcp/ena 0.0.0-stage → 0.1.18

package/README.md

@@ -1,3 +1,649 @@
-# Temporary Holding Version
+# @qe-mcp/ena
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server that lets Claude and other AI assistants run
+[Epistemic Network Analysis (ENA)](https://www.epistemicnetwork.org/), ordered
+network analysis (ONA) and transmodal analysis (TMA) on your coded data. The
+analysis runs **on your machine** — no R or Python — and only results go to
+the assistant.
+
+## Get started
+
+In Claude Desktop, open the **Code** tab (or Claude Code in a terminal) and
+send:
+
+```
+Install ENA from https://qe-libs.org/mcp/qe-mcp-ena/
+```
+
+It downloads the bundle and opens the install dialog; click **Install**, then
+restart Claude Desktop. In a new chat, ask *"What ENA tools do you have?"* —
+it should list 14 — and then ask about your data, by file path: *"Is
+/Users/me/data/coded.csv suitable for ENA?"*
+
+**By hand** (no Claude Code): download
+[`qe-mcp-ena.mcpb`](https://qe-libs.org/mcp/qe-mcp-ena/qe-mcp-ena.mcpb),
+double-click it (or drag it into **Settings → Extensions**), click
+**Install**, and restart Claude Desktop.
+
+Using another app? See [Other apps](#other-apps).
+
+### The install warning
+
+![Claude Desktop's install dialog: "Installing will grant this extension access to everything on your computer…"](https://qe-libs.org/mcp/qe-mcp-ena/install-warning.png)
+
+Claude Desktop shows this for every extension outside Anthropic's reviewed
+directory. An extension is a program that runs under your account, so you are
+trusting its source — as with an R package from GitHub. This one reads the data
+files you name, writes files only when you ask for an export, makes no network
+connections and starts no other programs. Its code is on
+[npm](https://www.npmjs.com/package/@qe-mcp/ena).
+
+### Working with it
+
+- **Give a file path, not pasted data.** The server reads the file itself; the
+  rows stay on your machine. See [Privacy](#privacy).
+- **Describe the analysis in words.** No tool or parameter names needed — see
+  [Prompts](#prompts).
+- **The analysis guide is built in.** The assistant reads it (`ena_guide`)
+  before the first analysis. Apps with MCP prompts (Claude Desktop's **+**
+  menu, `/` in Claude Code) also offer `analyze_data`, `compare_groups` and
+  `order_and_sequence` as starting points.
+- **Optional skill.** The same guide as a Claude skill, `ena-analysis.zip`, is
+  on the ENA page. It lets Claude pick up the workflow from the first
+  mention of coded data, before any tool is called: upload it under
+  **Customize → Skills**, or unzip it into `~/.claude/skills/` for Claude Code.
+  It doesn't update itself, so download it again when you upgrade.
+
+## Other apps
+
+Every app except the Claude Desktop extension runs
+`npx --yes @qe-mcp/ena` and needs **Node.js 18 or later**. Name the
+server `ena`. Afterwards, open a new conversation and ask *"What ENA tools do
+you have?"* (in VS Code and Cursor, in agent mode).
+
+### Claude Code
+
+```bash
+claude mcp add --scope user ena -- npx --yes @qe-mcp/ena
+```
+
+`--scope user` makes it available in every project; leave it out for the
+current project only. Check with `claude mcp list`.
+
+### Claude Desktop, without the extension
+
+**Settings → Developer → Edit Config**, or edit the file directly — macOS:
+`~/Library/Application Support/Claude/claude_desktop_config.json`; Windows:
+`%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ena": {
+      "command": "npx",
+      "args": ["--yes", "@qe-mcp/ena"]
+    }
+  }
+}
+```
+
+Quit Claude Desktop completely (on Windows, from the system tray too) and
+reopen it. If Windows can't find `npx`, use `"command": "cmd"` and
+`"args": ["/c", "npx", "--yes", "@qe-mcp/ena"]`.
+
+### Cursor and Windsurf
+
+The same `mcpServers` block, in `~/.cursor/mcp.json` (or `.cursor/mcp.json`
+for one project) or `~/.codeium/windsurf/mcp_config.json`. Then enable `ena`
+in the app's MCP settings.
+
+### VS Code
+
+For GitHub Copilot in agent mode: `.vscode/mcp.json`, or **MCP: Add Server**
+from the Command Palette. The top-level key is `servers`:
+
+```json
+{
+  "servers": {
+    "ena": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["--yes", "@qe-mcp/ena"]
+    }
+  }
+}
+```
+
+### Anything else
+
+Any client that runs local (stdio) MCP servers: command `npx`, arguments
+`--yes @qe-mcp/ena`. Where a client doesn't show images, plots come back
+as file paths. The guide and the privacy instructions reach every client; only
+the privacy hook is Claude-specific.
+
+### Dev builds and local installs
+
+Dev builds are on the QE GitLab registry under the `dev` tag:
+
+```bash
+echo "@qe-mcp:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
+echo "@qe-libs:registry=https://gitlab.com/api/v4/projects/22522458/packages/npm/" >> ~/.npmrc
+npx --yes @qe-mcp/ena@dev
+```
+
+Pinned: `npm install -g @qe-mcp/ena`, then command `qe-mcp-ena`. From
+a clone: `npm install`, then command `node` with
+`/absolute/path/to/qe-mcp-ena/server.js`.
+
+### Installing with an assistant
+
+If you've been asked to install this from the page: in Claude Code, run the
+`claude mcp add` command under [Claude Code](#claude-code). For Claude
+Desktop, download the current bundle and open it — the install dialog
+appears, and the user clicks **Install**:
+
+```bash
+curl -L -o ~/Downloads/qe-mcp-ena.mcpb https://qe-libs.org/mcp/qe-mcp-ena/qe-mcp-ena.mcpb && open ~/Downloads/qe-mcp-ena.mcpb
+```
+
+```powershell
+Invoke-WebRequest https://qe-libs.org/mcp/qe-mcp-ena/qe-mcp-ena.mcpb -OutFile "$HOME\Downloads\qe-mcp-ena.mcpb"; Start-Process "$HOME\Downloads\qe-mcp-ena.mcpb"
+```
+
+Then have the user restart Claude Desktop and ask *"What ENA tools do you
+have?"* — 14 tools means it worked. Without a shell, walk them through the
+manual install under [Get started](#get-started). Don't edit
+`claude_desktop_config.json` for the extension, and never ask for the data to
+be pasted. A plain-text copy of this page is at
+[llms.txt](https://qe-libs.org/mcp/qe-mcp-ena/llms.txt).
+
+### Hosting it (remote MCP)
+
+Everything above runs the server on the user's own machine, which is what
+keeps their data there. For web clients that can only reach remote MCP
+endpoints (Claude.ai custom connectors, ChatGPT connectors, Gemini custom
+apps), the same package can serve MCP over streamable HTTP instead:
+
+```bash
+npx --yes @qe-mcp/ena --http --port 8000 --host 0.0.0.0
+```
+
+The endpoint is `/mcp`; `GET /healthz` answers for probes. `--port` and
+`--host` fall back to `$PORT` and `$HOST`; `--max-body-mb` caps request size
+(default 25).
+
+A hosted server has no access to anyone's files, so this mode is a different
+privacy promise, and it says so to the model. In `--http` mode:
+
+- Data arrives inline as `data_csv`; `data_path` is refused. The server
+  processes it in memory and stores nothing.
+- `ena_profile`, `ena_tables`, `ena_lines` and `ena_export` are not offered
+  (they read or write files), and the prompts are not listed (they take a
+  path). Plots come back as the inline PNG plus the SVG as text; no files are
+  written.
+- The server's instructions tell the model to say that the data leaves the
+  user's machine and must be de-identified, and to get their OK first.
+- `model_id`s carry a random suffix so one conversation cannot plot another's
+  model.
+
+Each request is answered statelessly, so any replica can take any request,
+but fitted models are cached in the process that fitted them: run one
+replica, or use sticky sessions, for `model_id`s to stay valid across calls.
+Put TLS and whatever authentication or rate limiting you need in front of it;
+the server itself does neither. `node test-http.mjs` starts it on a free port
+and checks all of the above.
+
+## Prompts
+
+Describe what you want; the assistant picks the tools. These use the columns
+of rENA's `RS.data` sample — units `Condition` and `UserName`, conversations
+`Condition` and `GroupName`, codes such as `Data` and `Design Reasoning`, and
+the unit-level variable `CONFIDENCE.Change`.
+
+### Getting started
+
+```
+I have coded discourse data at /path/to/data.csv. Is it suitable for ENA?
+```
+
+```
+What columns are in /path/to/data.csv? It's confidential — don't read the rows.
+```
+
+```
+Analyze /path/to/data.csv with ENA.
+```
+
+### Fitting a model
+
+```
+Fit ENA with units Condition and UserName, conversations Condition and GroupName, and codes Data, Technical Constraints and Design Reasoning.
+```
+
+```
+What window size does this data support?
+```
+
+```
+Refit with a window of 6.
+```
+
+```
+Model only the students, but keep the mentors' lines as context.
+```
+
+```
+Leave out the Data & Technical Constraints connection — it's an artifact of the task.
+```
+
+```
+Can this model be simplified? Drop the codes it doesn't need.
+```
+
+```
+Fit the post-test data in the same space as the pre-test model.
+```
+
+### Comparing groups
+
+```
+Compare FirstGame and SecondGame.
+```
+
+```
+Is the difference on dimension 1 significant?
+```
+
+```
+Show me the subtraction network.
+```
+
+### Rotating by a variable
+
+```
+Fit ENA with dimension 1 representing CONFIDENCE.Change.
+```
+
+```
+Put CONFIDENCE.Change on the x-axis, controlling for Condition.
+```
+
+### Order and sequence
+
+```
+Fit an ordered network model — which codes tend to follow which?
+```
+
+```
+Fit TMA with Modality as the mode column: chat lines look back 4 lines, tool actions only 1.
+```
+
+```
+Measure the window in time: 2 minutes, using the Timestamp column.
+```
+
+### Plots and files
+
+```
+Show unit FirstGame__steven z.
+```
+
+```
+Hide the weak connections and make the labels bigger — it's for a slide.
+```
+
+```
+Save the points and line weights as CSV so I can load them in R.
+```
+
+```
+Export this model so I can open it in the ENA Web Tool.
+```
+
+### Back to the data
+
+```
+Show me the lines behind Data & Design Reasoning for FirstGame, with the text column.
+```
+
+## Privacy
+
+The analysis runs in the server, on your machine. What reaches the AI model —
+and the provider behind your app — depends on how the data gets there:
+
+| How the data gets there | What the model sees |
+|---|---|
+| A file path (`data_path`) | No raw rows — only results |
+| Inline CSV (`data_csv`) | The whole CSV. For small demo data only |
+| Pasted into the chat, or opened with the app's own file tools | Everything pasted or read |
+
+**Results still contain** the unit labels (the values of your unit columns —
+pseudonymize the file first if they identify people), the group values you
+name, `ena_profile`'s values for columns with 10 or fewer distinct values, and
+derived statistics. Errors never quote the data file. Two tools write files
+that do contain your data — `ena_export` (a ZIP with the data file, for the ENA
+Web Tool) and `ena_lines` (a viewer with rows of it) — so treat those like the
+data file.
+
+**The server tells the model** to use file paths, never to open the data file
+with other tools, and to ask for a path instead of pasted data: in its
+instructions to every MCP client, in the tool descriptions and in the guide.
+These are instructions, not enforcement. To enforce them, keep the assistant
+out of your data folder with the app's permissions — in Claude Code, a deny
+rule such as `Read(./data/**)` in `.claude/settings.json`, plus the hook below.
+
+**Results come only from the server.** Every number and plot should come from
+this server, never from code the assistant writes; the server and every tool
+error say so. Each result carries `provenance` (e.g.
+`@qe-mcp/ena 0.1.18 (rena-wasm 0.1.14)`), the interactive plot names it
+in its footer and the SVG in its `<desc>`. A plot or table without it didn't
+come from this server.
+
+### Privacy gate hook (Claude Code)
+
+The hook blocks any `data_csv` payload over 50 rows. Copy the script (it ships
+in the npm package and the repository):
+
+```bash
+mkdir -p ~/.claude/hooks
+cp hooks/ena-privacy-gate.mjs ~/.claude/hooks/
+```
+
+Then add to `~/.claude/settings.json`, replacing `YOUR_USERNAME` (if you
+already have a `PreToolUse` list, add the entry to it):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__ena__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node /Users/YOUR_USERNAME/.claude/hooks/ena-privacy-gate.mjs"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+The matcher covers every tool of a server named `ena`. It takes effect without
+a restart. If you installed the hook before 0.1.12, copy it again: earlier
+versions only warned instead of blocking.
+
+## Reference
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `ena_guide` | The analysis guide — workflow, rotations, ONA/TMA, reading results. Called before the first analysis |
+| `ena_profile` | Column names, counts and binary detection for a local CSV — no row data |
+| `ena_inspect` | Is the data ENA-shaped? Suggests codes, units and conversations |
+| `ena_window` | Estimates the window size from the data (Cross-Covariance Decay, = rENA `ena.ccd`) |
+| `ena_fit` | Fits an ENA model and plots it; returns a `model_id` |
+| `ena_compare_groups` | Two-group model, rotated through the groups as the ENA Web Tool does, with per-dimension tests |
+| `tma_fit` | Fits a directed ONA or TMA model and plots it |
+| `ena_plot` | Another view of a fitted model: all units, a group, two groups overlaid, subtraction, one unit |
+| `ena_accumulate` / `tma_accumulate` | The accumulation step only: raw per-unit networks |
+| `ena_export` | Writes a fitted model as an ENA Web Tool project ZIP, to open there as the same model and plot |
+| `ena_simplify` | Simplifies a model with PRIA, the web tool's Simplify Model: removes the codes it can do without, and refits |
+| `ena_lines` | Shows the lines behind a connection in a local viewer — the web tool's Data View — with every window the model counted |
+| `ena_tables` | Writes a fitted model's points, node positions, line weights and connection counts as CSV files |
+
+### Fit options
+
+All fit and accumulate tools take `data_path` — a `.csv` or `.xlsx` file (the
+first worksheet, as in the ENA Web Tool) — or `data_csv`, with `units`,
+`conversations` and `codes`. Options:
+
+| Option | Meaning |
+|---|---|
+| `window_size` | Lines to look back, or `"Inf"` for every earlier line in the conversation. Omitted: the `ena_window` estimate (as a new set in the ENA Web Tool takes), or 4 when the data is too sparse for one. |
+| `binary` | Count each line's co-occurrences as present/absent (default `true`). |
+| `weight_model` | Weight each line's counts before summing per unit: `product` (raw), `sqrt`, `log` (= rENA `weight.by`). Overrides `binary`. |
+| `units_used` | Model only these units (labels as in the results); other units' lines still count as context (= rENA `units.used`). |
+| `mask_connections` | Connections to switch off, e.g. `["Data & Technical Constraints"]` — the ENA Web Tool's Code Masking Matrix. They count as 0 for every unit before normalization and rotation; for ordered models, `A & B` masks A → B only. Exported with `ena_export`. |
+| `exclude_conversations` | Conversations to leave out, named by their conversation values joined by `::` (e.g. `FirstGame::Electric`). Their lines are removed before anything else — not modeled, not context — as the web tool's former R backend did for excluded horizons. |
+| `order_by` | Order the lines by a column before windowing (the web tool's *Order*): ascending and stable, numeric when every value is a number. Row numbers in results still refer to the file. |
+| `sphere_norm` | Normalize each unit network to length 1 (default `true`); `false` scales all by the longest, so network size counts. |
+| `center_align_to_origin` | Keep units with empty networks at the origin and out of the centering (default `true`). Unordered models only. |
+| `dims` | Dimensions to return (default 2). |
+| `group_col`, `group1_value`, `group2_value` | Colour the plot by group, and test two groups on each dimension. `group_col` defaults to the first unit column when there are two or more. |
+
+Repeated `ena_fit` / `ena_compare_groups` calls with the same options return
+the cached model. `ena_plot` draws more views of a model by `model_id` without
+refitting; `x_dim` / `y_dim` put any of the model's dimensions on the axes
+(fits keep up to 6, as the ENA Web Tool does), and `flip_x` / `flip_y` mirror
+them.
+
+### Simplifying a model
+
+`ena_simplify` runs PRIA — the ENA Web Tool's Simplify Model, the same
+search as R's `PRIA::pria` — on a fitted model. It finds the largest set of
+codes, up to `remove_num` (default 3) and never leaving fewer than 3, whose
+removal keeps the model within `threshold` (default 0.95; 0.80–0.99) of the
+full one. If codes can go, it refits without them, with the window and every
+other setting unchanged, and returns the new model with `removed_codes`.
+
+### Rotations
+
+| `rotation` | Axes |
+|---|---|
+| *(omitted)* | As the ENA Web Tool rotates: with two or more unit columns and two or more values in the first (e.g. `Condition` in `["Condition", "UserName"]`), a GMR through that column's first two groups in data order — or `group1_value` / `group2_value` when `group_col` is that column — and the group tests on them; otherwise `svd`. `ena_compare_groups` always rotates this way through its two groups. |
+| `svd` | The directions of most variance — exploratory. |
+| `mean` | Dimension 1 runs through two group means (`group_col`, `group1_value`, `group2_value`). |
+| `generalized` | Dimension 1 represents a unit-level variable (= rENA `ena.rotate.by.generalized`). |
+| `rotation_from: <model_id>` | Project into another fitted model's space — the web tool's *Use Rotation Matrix From* (= rENA `rotation.set`). Same codes and network type required. |
+
+With one categorical target and two groups, the web tool's GMR gives the same
+axes as a means rotation.
+
+**Projecting into another model** (`ena_fit`, `tma_fit`): `rotation_from`
+takes a fitted model's `model_id`. The new model's units are centred and
+rotated with the source's rotation and drawn with its node positions, so
+the two share one space — a second cohort, a post-test, a held-out sample.
+Points match rENA's `ena.make.set(..., rotation.set = source$rotation)`.
+Exporting a projected model is refused: in the web tool the rotation comes
+from another set in the same project.
+
+**Generalized rotation** (`ena_fit`, `tma_fit`):
+
+- `x_var` — the target column, then optional covariates, which are controlled
+  for by Lasso (with pairwise `interactions` unless set to `false`).
+  A categorical target puts dimension 1 (GMR1) through the group means; a
+  numeric one puts it along the variable.
+- `y_var` — optional second target, for dimension 2 (GMR2).
+- `select_2_groups` — fit GMR1 on two values of a categorical target; the plot
+  and group tests then use those two groups.
+
+`x_var` and `y_var` must be unit-level — one value per unit, none missing. A
+unit with a missing value is rejected (rENA errors there too); leave it out
+with `units_used`. Results match rENA's to six decimal places, up to the sign
+of each axis. GMR1 explains no more variance than the first SVD dimension
+would: it's chosen for meaning, not variance.
+
+### ONA and TMA
+
+`tma_fit` builds **directed** networks: a connection A → B means code A was in
+the window — the *ground* — when code B appeared — the *response*.
+
+| Use | When |
+|---|---|
+| **ONA** (= R's `ona`) | Order matters: responses, sequences, what leads to what. Just units, conversations, codes and `window_size`. |
+| **TMA** (= R's `tma`) | Lines differ in kind — chat vs logged actions, mentor vs student — and each kind should look back a different distance or count with a different weight. |
+| `ena_fit` | Neither: undirected models are simpler to explain. |
+
+| Option | Meaning |
+|---|---|
+| `ordered` | Directed networks (default `true`); `false` gives undirected networks from the same windows. |
+| `stanza_modality` | Column whose value is the line's mode (e.g. `chat`, `log`). |
+| `stanza_ground` | Column(s) whose value on the *ground* (earlier) line selects the window — e.g. who said it. |
+| `stanza_response` | Column(s) whose value on the *responding* line selects the window. |
+| `stanza_overrides` | Per-combination `{ path, window, weight }`; others use `window_size` and weight 1. |
+| `window_type`, `time_column`, `time_unit` | `"time"` measures windows in time from `time_column`, in `secs` (default), `mins`, `hours`, `days` or `weeks`. Times can be numbers, `MM:SS`, `HH:MM:SS` or date-times. |
+| `horizons` | `{ by, rules }`: each unit gets its own horizon of observation instead of the conversations (tma's HOO rules). |
+
+**Override paths** list one value per factor: modality columns, then ground,
+then response. With `stanza_modality: "Modality"` and `stanza_ground: ["Role"]`:
+
+```json
+"stanza_overrides": [
+  { "path": ["log",  "Student"], "window": 1 },
+  { "path": ["chat", "Mentor"],  "window": 6, "weight": 2 }
+]
+```
+
+A path with the wrong number of values, or a value not in its column, is an
+error naming the expected order.
+
+**Horizons** — `{ "by": "Modality", "rules": { "chat": ["GroupName"], "log":
+["UserName"] } }` puts a chat line in the horizon of every unit in the same
+group, and a logged action only in its author's. Rows whose `by` value has no
+rule are left out.
+
+The rotations, group tests, `weight_model`, `units_used` and `sphere_norm` work
+as in `ena_fit`. To compare two groups with ordered networks, use `tma_fit`
+with `rotation: "mean"` — `ena_compare_groups` is undirected only.
+
+**Reading directed results:** n codes give n² connections, named `"A & B"` for
+A → B, including self-connections (A → A). Plots draw directed edges as tapered
+shapes with direction marks, each direction weighted separately; read exact
+weights from the results. In subtraction plots, an edge's colour shows which
+group has more of that direction.
+
+### Output
+
+Every fit and plot returns:
+
+- **`svg_plot`** — the network plot as SVG.
+- **`interactive_plot`** — a self-contained interactive HTML version, with
+  live controls for the web tool's Plot Settings: minimum edge weight, edge
+  scale, text size, unconnected codes, code / unit / group labels, unit
+  points, and confidence and outlier boxes. Open it in a browser to fine-tune
+  a plot without going back through the assistant.
+- **`png_plot`** and an **inline image**, shown in the chat by apps that
+  display tool images. PNGs come from the native `@resvg/resvg-js` where
+  `npm install` provides it, and otherwise — as in the Claude Desktop
+  extension — from `@resvg/resvg-wasm`, drawing labels with the bundled Inter
+  font.
+
+Files go to the system temp folder under `ena-viz/<process id>/` and last until
+the next restart.
+
+`ena_plot` takes the same settings, for plots that come back in the chat or
+go into a paper: `min_edge_weight` (the result reports `max_edge_weight` to
+scale it by), `hide_unconnected_codes`, `text_size`, `colors`
+(`{ "<group>": "<colour>" }`), `confidence_intervals` and `outlier_intervals`.
+They change only the drawing, never the model.
+
+Every fit also reports, per dimension, the **variance explained** and the
+**goodness of fit**: Pearson and Spearman correlations between the distances of
+the unit points and the distances of their network centroids (= rENA
+`ena.correlations`, the ENA Web Tool's Goodness of Fit). Below 0.9, the plotted
+points and the networks don't line up well enough to interpret the positions
+of points by the nodes near them; the summary flags it.
+
+### Lines behind a connection
+
+`ena_lines` writes a local HTML viewer of the lines that produced a connection
+for the units or group you choose, like the ENA Web Tool's Data View. Each line
+that contributed is shown with the window of lines it was connected to, grouped
+by conversation. The connection's codes are highlighted, and ground and
+response roles are marked for ordered models. Lines outside any window collapse
+into "… N lines …", which you can expand.
+
+- **Exact.** The lines come from the model's own per-line counts, and the
+  windows follow libtma's window rule, for ENA, ONA and TMA (modes, overrides,
+  time windows, horizons). Every line of the selection is re-checked against
+  the model, and the result reports the check.
+- **Columns.** By default the viewer shows what the web tool's Data View shows:
+  unit, conversation and code columns. Add others, such as the text, with
+  `columns`; any column can be switched on in the viewer.
+- **Private.** The tool returns counts and data-row numbers (`window_rows`;
+  add 1 for the spreadsheet row) — never text. The viewer contains rows of your
+  data file, so treat it like the data file. The assistant is told not to open
+  it.
+
+### Data tables
+
+`ena_tables` writes a model's tables as CSV, as the ENA Web Tool's Download
+Model does, into a new folder (by default next to the data file):
+
+| File | Rows | Columns |
+|---|---|---|
+| `nodes.csv` | codes | `code`, then one column per dimension (`SVD1`, `GMR1`, ...) |
+| `points.csv` | units | `ENA_UNIT`, then one column per dimension |
+| `line-weights.csv` | units | `ENA_UNIT`, the unit columns, then one `A & B` column per connection (normalized) |
+| `connection-counts.csv` | units | the same, with the raw accumulated counts |
+
+They hold up to 6 dimensions, unscaled, with the same values as rENA's
+`set$points`, `set$rotation$nodes`, `set$line.weights` and
+`set$connection.counts`. For ordered models, `A & B` is A → B.
+
+### Matching the ENA Web Tool
+
+Defaults, plots and exports follow the ENA Web Tool, so a model fit here is
+the same model, drawn the same way, once it is opened there. The conventions
+are copied from the web tool into `webena.js` and kept in step with it.
+
+- **Defaults**: the window (Cross-Covariance Decay) and the rotation (by the
+  first unit column's groups) above; units are grouped by the first unit
+  column, in the order the web tool lists them (integer-like values first,
+  then order of appearance); a single unit column makes one group of every
+  unit, named after it.
+- **Plots** are the web tool's comparison plot: unit points scaled to the
+  network as its *Scale Units* does, group means with 95% confidence boxes,
+  group colours `#cc423a`, `#218ebf`, `#9d5dbb`, … in group order, axes
+  labelled with their variance (`GMR1 (30.91%)`), and the network of one
+  group, one unit, or group 1 − group 2. Group networks are the mean line
+  weights rescaled to 0.1–1, as the web tool draws them, so a subtraction is
+  the difference of those; the numbers in the results (`group1_networks`,
+  `subtraction_network`, `top_differential`) are the plain means. A
+  subtraction's strongest edge is drawn 4 px wide; `magnify` is the web tool's
+  *Scale edge weights* (default 1).
+- **Export**: `ena_export` writes a project ZIP with the data file and a set
+  holding the units, conversations, codes, window, rotation, weight model,
+  sphere normalization, group colours and the plot to open with. In the web
+  tool, start a local session (*Run Offline*), click **Import** in the Sets
+  panel and open *Folder › &lt;set name&gt;*. Units left out with `units_used`
+  arrive excluded in the web tool's Units tab, `exclude_conversations` as
+  excluded horizons and `order_by` as the window Order; the web tool applies
+  them the same way.
+  A model the web tool has no setting for — transmodal or time windows, a GMR
+  on `x_var`, a rotation by a column other than the first unit column,
+  `center_align_to_origin: false` — is refused with the reason. The ZIP goes
+  next to the data file by default and never overwrites one.
+
+### Group statistics
+
+When two groups are named, results include a `stats` block for each dimension:
+group n, mean, SD and median; a Welch t-test with Cohen's d; and a
+Mann-Whitney U test with rank-biserial r — computed by libqe, the same code as
+rENA's group tests.
+
+- The Mann-Whitney p uses the normal approximation with continuity correction;
+  R's `wilcox.test()` is exact for small samples without ties, so it can differ
+  slightly.
+- `effect_r = 1 − 2U/(n1·n2)`: negative when group 1 tends higher.
+- Under a rotation through the groups (the default for grouped units, means
+  or GMR), dimension 1 is built to separate them, so its test confirms the
+  separation rather than testing it independently, and dimension 2's test is
+  always t = 0, p = 1.
+
+### Developing
+
+Tests drive the server over stdio, as an MCP client does:
+
+```bash
+node test-mcp.mjs /path/to/data.csv UnitColumn ConversationColumn Code1 Code2 Code3
+node test-tma.mjs
+node test-render.mjs
+```
+
+`bash scripts/build-mcpb.sh` builds `dist/qe-mcp-ena.mcpb`;
+`cd skill && zip -r ena-analysis.zip ena-analysis -x '*.DS_Store'` builds the
+skill. Releases build both automatically.