@barivia/barsom-mcp 0.15.3 → 0.17.0

package/README.md

@@ -1,6 +1,6 @@
 # @barivia/barsom-mcp
 
-MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. The npm package is **`@barivia/barsom-mcp`**; many configs label the server **`analytics-engine`** (the MCP server name in the client JSON). **`guide_barsom_workflow`** is the canonical bootstrap: it loads plan-scoped workflow text from the Barivia API when online (tool map, async rules, training modes, SOP). If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `train` (`map`, `siom_map`, `impute`, `floop_siom` where entitled, `baseline_study`), `jobs` (status/list/compare/cancel/delete), `results`, and `inference`. **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results.
+MCP proxy for the Barivia Analytics Engine — connects any stdio MCP client (Cursor, Claude Desktop, etc.) to the barSOM cloud API. The npm package is **`@barivia/barsom-mcp`**; many configs label the server **`analytics-engine`** (the MCP server name in the client JSON). **`guide_barsom_workflow`** is the canonical bootstrap: it loads plan-scoped workflow text from the Barivia API when online (tool map, async rules, training modes, SOP). If the API is unreachable, it returns a short offline stub. Core tools are `datasets`, `train` (`map`, `siom_map`, `impute`, `floop_siom` where entitled), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/export/download/recolor), and `inference` (predict/batch_predict/impute_column/compare/project_columns/transition_flow/report). **Optional MCP App tools** (`training_prep`, `training_monitor`, `results_explorer`) add embedded or localhost viz; they are **not required** to complete upload → train → poll → results, though `results_explorer` is the preferred way to browse figures.
 
 **Pre-training help (pick one):** **`prepare_training`** prompt = narrative checklist (tier-scoped from the API when online); **`training_guidance`** tool = structured presets and parameter hints; **`training_prep`** tool = interactive UI plus **`submit_prepared_training`**.
 
@@ -103,10 +103,11 @@ All training is submitted via the `train` tool; every action is async and return
 | Action | Use when |
 |--------|----------|
 | `map` | New map training job — full control: model type, grid, epochs, cyclic/temporal features, transforms. Complete-case data only (no NaNs in training columns). |
-| `impute` | Sparse training data: accelerated missSOM / SIOM missSOM — trains a map and imputes missing cells in one job. Defaults: `model=auto`, `cv_folds=5`. Returns map artifacts + `imputed.csv`, `imputation_mask.csv`, optional `quality.csv` / `imputation_uncertainty.csv`. `quality.csv` reports two labeled numbers per column: `kfold_holdout_pool` (honest held-out) and `resubstitution_optimistic` (in-sample, optimistic — not validation). Plain numeric columns only. Valid parent for `inference(impute_column)`. |
+| `impute` | Sparse training: missSOM / SIOM missSOM — map + `imputed.csv`. Supports **`transforms`**, **`temporal_features`**, **`cyclic_features`**, **`normalization_methods`** (zscore/mad/sigmoidal/none — **not** sepd or rank). Defaults: `model=auto`, `cv_folds=5`. Valid parent for `inference(impute_column)`. |
 | `siom_map` | Self-interacting map — same grid-map workflow plus SIOM controls such as `gamma`, `siom_decay`, and penalty selection. |
 | `floop_siom` | FLooP-SIOM — growing node-budget manifold; default `topology=free` (CHL); optional `topology=chain` for strict 1D linked list. Requires Premium/Enterprise (`all_algorithms`). |
-| `baseline_study` | Auto-configured baseline SOM for a dataset (heuristic grid + MAD normalization). |
+
+For a quick first map, use `train(action=map, preset=quick)` (or `normalize=mad` with a grid sized from the preview row count) — see the `baseline_explore` preset in `training_guidance`.
 
 ### `jobs(action)` — lifecycle
 
@@ -118,7 +119,7 @@ All training is submitted via the `train` tool; every action is async and return
 | `cancel` | Stopping a running job |
 | `delete` | Permanently removing a job + its S3 files |
 
-`jobs(action=train_map | train_siom_map | train_impute | train_floop_siom | run_baseline_study | batch_predict)` still work as **deprecated** forwarders to `train(...)` / `inference(batch_predict)` for one release (each prints a deprecation note). Migrate to `train` / `inference`.
+`jobs` is **lifecycle only**. Submit training with the `train` tool and run scoring / post-training map ops with `inference`. (The old `jobs(action=train_*/run_baseline_study/batch_predict)` forwarders were **removed in 0.17.0** — see Migration notes.)
 
 ### `results(action)`
 
@@ -128,7 +129,8 @@ All training is submitted via the `train` tool; every action is async and return
 | `export` | instant | Learning curve (training_log), weight matrix (weights), node stats (nodes) |
 | `download` | instant | Saving figures to a local folder |
 | `recolor` | async | Changing colormap or output format without retraining |
-| `transition_flow` | async | Temporal state transition analysis on time-ordered data |
+
+Temporal state-transition analysis moved to **`inference(action=transition_flow)`** in 0.17.0 (read the resulting figure with `results(action=get/download)`).
 
 All visualizations and metrics come from **`results(action=get)`**. Grid-map jobs return combined map figures, component planes, and quality metrics; FLooP-SIOM jobs return structure/coverage figures, occupation/profile views, and metrics. Use `figures=all` or `export_type=...` for more. There is no separate `analyze` tool.
 
@@ -142,6 +144,7 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 | `impute_column` | Fill a numeric **target_column** not used in training: **requires** `dataset_id` + `target_column`. Parent job: completed **train(action=map)** or **train(action=impute)**. Dataset must contain all training features plus the target. Pools observed target values from rows mapped to this row's BMU and topology neighbors (BMU + neighbors, often 7 nodes on hex interior; fewer on borders unless the map is periodic). `only_missing` (default true); `impute_aggregation`: mean or median. **Not** held-out validated — map-local estimate. Output **`imputed.csv`**. For holes across many training columns, prefer **train(action=impute)** first. | 5–120s |
 | `compare` | density-diff heatmap + top gained/lost nodes — drift, A/B, cohort | 30–120s |
 | `project_columns` | Project one or more dataset columns onto the trained map (component planes) | async |
+| `transition_flow` | Temporal state-transition arrows on the trained map (time-ordered rows only). Pass the training `job_id`; returns a new result `job_id` for `results(get/download)`. `lag`/`min_transitions`/`top_k` tune it. | 30–60s |
 | `report` | Report **manifest** (figure names, download URLs, metrics, cluster summary) — sync; use with `results(download)` on the training `job_id` for `report.pdf` when present; build custom PDFs in Quarto/Jupyter | immediate |
 
 ### `account(action)`
@@ -161,7 +164,7 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 |------|------|
 | `training_prep` | Review variables, transforms, hyperparameters before submit |
 | `submit_prepared_training` | Submit the reviewed prep (`review_token` + `explicit_confirm=true`) |
-| `training_monitor` | Visual progress for a `job_id`; optional — `jobs(action=status)` is enough |
+| `training_monitor` | Live QE + topographic-error curves (ordering/convergence, dual y-axis), FLooP step progress when applicable; optional — `jobs(action=status)` is enough |
 | `results_explorer` | Browse metrics and figures after training completes |
 | `_fetch_figure` | **Host / App only** — Results Explorer invokes this for one raster figure; not for agent chat |
 
@@ -179,7 +182,11 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 
 ### Migration notes
 
-- **Training moved to the `train` tool (0.14.0):** submit training via `train(action=map | siom_map | impute | floop_siom | baseline_study)`; `jobs` now covers lifecycle only (`status`/`list`/`compare`/`cancel`/`delete`). `batch_predict` moved to `inference(action=batch_predict)`. The old `jobs(action=train_map | train_siom_map | train_impute | train_floop_siom | run_baseline_study | batch_predict)` actions still work as **deprecated forwarders** for one release (each prints a deprecation note); they will be removed later. Update Cursor / Claude Desktop configs and prompts to the new tools.
+- **Surface cleanup (0.17.0, breaking):**
+  - `train(action=baseline_study)` **removed** — use `train(action=map, preset=quick)` (the `baseline_explore` preset in `training_guidance`).
+  - `results(action=transition_flow)` **removed** — it is now **`inference(action=transition_flow)`** (a frozen-map operation). Read the resulting figure with `results(action=get/download)` on the returned job_id.
+  - The deprecated `jobs(action=train_map | train_siom_map | train_impute | train_floop_siom | run_baseline_study | batch_predict)` forwarders are **removed**. Submit training via `train`; run scoring / map ops via `inference`. `jobs` is lifecycle-only and no longer accepts training parameters.
+- **Training moved to the `train` tool (0.14.0):** submit training via `train(action=map | siom_map | impute | floop_siom)`; `jobs` now covers lifecycle only (`status`/`list`/`compare`/`cancel`/`delete`). `batch_predict` is `inference(action=batch_predict)`. (The 0.14.0–0.16.x deprecated `jobs(train_*)` forwarders were removed in 0.17.0; see above.) Update Cursor / Claude Desktop configs and prompts to the new tools.
 - **`explore_map` removed (0.13.0):** the deprecated alias of `results_explorer` is gone. Update any Cursor / Claude Desktop / MCP config or call site to use **`results_explorer`**.
 - **`train_floop_chain` removed (0.13.0):** the deprecated alias of `jobs(action=train_floop_siom)` is gone. Use **`train(action=floop_siom)`**.
 - **Shorter `info` prompt:** Clients that relied on the old long `info` text should use **`guide_barsom_workflow`** or server **instructions** for the full story.

package/dist/index.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as n,RESOURCE_MIME_TYPE as s}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as a}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d,CLIENT_VERSION as u}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as _,JOBS_DESCRIPTION_BASE as b}from"./tools/jobs.js";import{registerResultsTool as y}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as w}from"./tools/explore_map.js";import{registerAccountTool as j}from"./tools/account.js";import{registerInferenceTool as v}from"./tools/inference.js";import{registerGuideBarsomTool as P}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as x}from"./tools/training_guidance.js";import{registerFeedbackTool as I}from"./tools/feedback.js";import{registerTrainingPrepTools as k,TRAINING_PREP_URI as T}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as O}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as A}from"./prepare_training_prompt.js";i||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const S=new e({name:"analytics-engine",version:u,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `train(action=map)`, `train(action=siom_map)`, or `train(action=floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool). Then `jobs(compare)`, `results(download/recolor/transition_flow)`, or `inference` as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool map (compact)\n\n| Area | Tool | Notes |\n|------|------|--------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete |\n| Train | `train` | map, siom_map, impute (sparse data: map + dense imputed.csv), floop_siom (entitled), baseline_study — all async, returns job_id |\n| Jobs | `jobs` | status, list, compare, cancel, delete (lifecycle). jobs(train_*/run_baseline_study/batch_predict) still work as deprecated forwarders → use train / inference |\n| Results | `results` | get (figures="none" for metrics-only), export, download, recolor (async), transition_flow (async; time-ordered rows only) |\n| Inference | `inference` | predict (regime-aware; output="compact"|"annotated"), batch_predict (fan out many predict jobs), impute_column (neighbor-pool fill for a non-training column), compare, project_columns, report |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow` | orientation + SOP |\n| Parameters | `training_guidance` | presets and field hints (API-scoped) |\n| Prep | `prepare_training` prompt, `training_prep` + `submit_prepared_training` | checklist / interactive UI |\n| Explore | `results_explorer`, `training_monitor` | optional MCP Apps; `jobs(status)` and `results(get)` suffice without them |\n| Other | `send_feedback` | only after user agrees |\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions, `results(recolor)`, `results(transition_flow)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints; `training_prep` = UI + guarded submit. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `recolor`, `transition_flow`, or `project_columns`, use the **new** `job_id` returned for follow-up `results` if applicable.'});n(S,w,w,{mimeType:s},async()=>{const e=await c("results-explorer");return{contents:[{uri:w,mimeType:s,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(S,T,T,{mimeType:s},async()=>{const e=await c("training-prep");return{contents:[{uri:T,mimeType:s,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(S,O,O,{mimeType:s},async()=>{const e=await c("training-monitor");return{contents:[{uri:O,mimeType:s,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),P(S),h(S),k(S),M(S),f(S),g(S),_(S,b),y(S),j(S),v(S),x(S),I(S),S.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool).","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map/siom_map/impute/floop_siom/baseline_study; pass `label` for readable compare rows), `jobs` (status/list/compare/cancel/delete), `results` (get/download/export/recolor/transition_flow; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints) · `training_prep` + `submit_prepared_training` (interactive UI).","","**Optional UI:** `results_explorer`, `training_monitor` — nice for browsing; not required if you use `results` + `jobs(status)`.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `transition_flow` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),S.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints; training_prep tool = interactive UI + submit_prepared_training.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await A(e)}}]}));const C=new t;(async function(){try{const e=await a(l,p,c);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=S.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(s))},await S.connect(C)})().catch(console.error);
+import{McpServer as e}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport as t}from"@modelcontextprotocol/sdk/server/stdio.js";import{z as o}from"zod";import{getUiCapability as r,registerAppResource as n,RESOURCE_MIME_TYPE as s}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as i}from"./viz-server.js";import{API_KEY as a,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d,CLIENT_VERSION as u}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as _,JOBS_DESCRIPTION_BASE as h}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as y,RESULTS_EXPLORER_URI as w}from"./tools/explore_map.js";import{registerAccountTool as j}from"./tools/account.js";import{registerInferenceTool as v}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as k}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as T}from"./tools/training_prep.js";import{registerTrainingMonitorTool as A,TRAINING_MONITOR_URI as M}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as S}from"./prepare_training_prompt.js";a||(console.error("Error: BARIVIA_API_KEY not set. Set it in your MCP client config."),process.exit(1));const O=new e({name:"analytics-engine",version:u,instructions:'# Barivia Mapping Analytics Engine\n\nSelf-organizing map (SOM) analytics: project high-dimensional data to a 2D grid for clusters, gradients, and anomalies.\n\n## Workflow (short)\n\nUpload (`datasets(upload)`) → `datasets(preview)` and `datasets(analyze)` before train → submit one of `train(action=map)`, `train(action=siom_map)`, or `train(action=floop_siom)` (only if plan allows FLooP) → poll `jobs(status)` every 10–15s until `completed` → `results(get)` for metrics and figures (there is no separate analyze tool), then `results_explorer(job_id)` to browse the figures interactively. Then `jobs(compare)`, `results(download/recolor)`, or `inference` (predict / compare / project_columns / impute_column / transition_flow) as needed.\n\n**Full detail:** Call `guide_barsom_workflow` for plan-scoped tool map, training modes, async rules, optional MCP App UIs, and step-by-step SOP (from the Barivia API when online).\n\n## Tool taxonomy (one tool per stage — do not mix)\n\n| Stage | Tool(s) | Contract |\n|-------|---------|----------|\n| Data | `datasets` | upload, preview, analyze, list, **get** (status/staging), subset, add_expression, reduce_spectral, delete — ingest + feature engineering, no map |\n| Train submit | `train` **or** `training_prep` → `submit_prepared_training` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list, compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (figures="none" for metrics-only), export, download, recolor (async). Read/render completed jobs |\n| Frozen-map ops | `inference` | predict (regime-aware; "compact"|"annotated"), batch_predict, impute_column (neighbor-pool fill for a non-training column), compare (cohort density-diff), project_columns, transition_flow (time-ordered rows only), report. No weight updates |\n| Account | `account` | status, burst/compute actions, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `training_guidance`, `prepare_training` prompt | orientation, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_prep`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees |\n\n### Avoid these mis-routes\n- `jobs(compare)` = metrics table across **training runs** (pick best in a sweep). `inference(compare)` = density-diff of one map vs a **second dataset** (drift/cohort). Different tools.\n- Post-training map analysis (predict, compare, project_columns, impute_column, **transition_flow**) is all **inference** — not `results`. `results` is presentation/artifacts only (`recolor` stays here: it re-renders, it doesn\'t touch data).\n- Project a quantity onto the map: existing columns → `inference(project_columns)`; a formula → `datasets(add_expression, project_onto_job=<job>)`.\n\n## Async pattern\n\n- **Manual poll:** Training submits return `job_id` immediately — poll `jobs(status)` every 10–15s. **Running is not failed**; large grids or FLooP-SIOM can take many minutes. `max_nodes` (FLooP) is a total node budget, not grid side length.\n- **Often auto-polled:** `inference` actions (incl. `transition_flow`) and `results(recolor)` may wait in-proxy; if you get a `job_id`, poll `jobs(status)` the same way.\n\nCredits: jobs consume compute credits; check `account(status)` before big runs. Per-request HTTP timeout defaults to 60s (`datasets(analyze)` is async + auto-polled, so it is not bound by it); on slow networks raise `BARIVIA_FETCH_TIMEOUT_MS`. Timeouts are NOT auto-retried (avoids duplicating slow/expensive work).\n\n## Constraints\n\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints; `training_prep` = interactive UI that shows the **resolved per-column normalization / transforms / grid / epochs** and lets the user tweak before a guarded `submit_prepared_training`. Prefer `training_prep` when the user wants to review or fine-tune preprocessing before committing a job; use `train` directly when parameters are already confirmed. Do not guess tiers or FLooP entitlement.\n- `inference(predict)`: prefer `dataset_id` for batch and for SIOM/irregular maps; single-row `rows` uses a fast path that can fail on some topologies — retry with `dataset_id`. FLooP-SIOM: if predict jobs fail while grid SIOM works, capture errors + `job_id`.\n- Column names are case-sensitive — match `datasets(preview)`.\n- Default training path is numeric/cyclic/temporal; use explicit `categorical_features` for baseline categoricals. `predict` must match the model contract.\n- After `results(recolor)`, `inference(transition_flow)`, or `inference(project_columns)`, use the **new** `job_id` returned for follow-up `results` if applicable.'});n(O,w,w,{mimeType:s},async()=>{const e=await c("results-explorer");return{contents:[{uri:w,mimeType:s,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(O,T,T,{mimeType:s},async()=>{const e=await c("training-prep");return{contents:[{uri:T,mimeType:s,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(O,M,M,{mimeType:s},async()=>{const e=await c("training-monitor");return{contents:[{uri:M,mimeType:s,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(O),y(O),I(O),A(O),f(O),g(O),_(O,h),b(O),j(O),v(O),P(O),k(O),O.prompt("info","Short orientation for the Barivia Mapping MCP. For full plan-scoped workflow, tool map, and SOP, the model should call guide_barsom_workflow. Use when the user asks what this MCP can do or how to get started.",{},()=>({messages:[{role:"user",content:{type:"text",text:["Give a concise, scannable answer (headers + bullets):","","**What it is:** MCP client to the Barivia mapping engine (2D SOM / SIOM / FLooP-SIOM when entitled) over HTTPS.","","**First step:** Call `guide_barsom_workflow` for plan-scoped bootstrap (full tool list, async rules, training modes, optional MCP Apps, SOP).","","**Core path:** `datasets(upload)` → `datasets(preview)` + `datasets(analyze)` → choose training action → poll `jobs(status)` every 10–15s until completed → `results(get)` (all main figures/metrics; no separate analyze tool) → `results_explorer(job_id)` to browse figures.","",'**Key tools:** `datasets` (data; reduce_spectral for spectra/long blocks), `train` (map/siom_map/impute/floop_siom; pass `label` for readable compare rows; preset=quick for a fast first map), `jobs` (status/list/compare/cancel/delete — lifecycle only), `results` (get/download/export/recolor; figures="none" for metrics-only), `inference` (predict; batch_predict; impute_column for topology-neighbor pool fill; compare; project_columns; transition_flow; report), `account` (status/credits/queue).',"","**Prep help:** `prepare_training` prompt (checklist) · `training_guidance` (presets/JSON hints) · `training_prep` + `submit_prepared_training` (interactive UI showing resolved normalization/params to review before submit).","","**Browse results:** `results_explorer(job_id)` is the preferred way to explore figures after a first `results(get)` glance; `training_monitor` shows live progress. Both optional — `results` + `jobs(status)` suffice headless.","","**After training:** `jobs(compare)` across runs, `results(recolor)`, `inference(project_columns)` for variables not in training, `inference(transition_flow)` only if rows are time-ordered.","","**Rules:** Running ≠ failed. Column names must match `datasets(preview)` exactly. Do not call `_fetch_figure` from chat (host/UI only); use `results(get)` or `results_explorer`.","","Offer `send_feedback` only after asking the user."].join("\n")}}]})),O.prompt("prepare_training","Narrative pre-training checklist (prompt). Use after upload and before train. Content is tier-scoped from the API when online. Prep ladder: this prompt = story checklist; training_guidance tool = JSON presets/parameter hints; training_prep tool = interactive UI + submit_prepared_training.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>({messages:[{role:"user",content:{type:"text",text:await S(e)}}]}));const C=new t;(async function(){try{const e=await i(l,p,c);m(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=O.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(s))},await O.connect(C)})().catch(console.error);

package/dist/job_status_format.js

@@ -1,4 +1,36 @@
 /** Format jobs(status) text from GET /v1/jobs/:id payload. Exported for tests. */
+function formatElapsedPart(data, status) {
+    const wall = data.wall_elapsed_sec != null && !Number.isNaN(Number(data.wall_elapsed_sec))
+        ? Number(data.wall_elapsed_sec)
+        : null;
+    const kernel = data.kernel_elapsed_sec != null && !Number.isNaN(Number(data.kernel_elapsed_sec))
+        ? Number(data.kernel_elapsed_sec)
+        : data.training_elapsed_sec != null && !Number.isNaN(Number(data.training_elapsed_sec))
+            ? Number(data.training_elapsed_sec)
+            : null;
+    if (wall != null && wall >= 0) {
+        const wallR = Math.round(wall);
+        if (status === "completed" &&
+            kernel != null &&
+            kernel >= 0 &&
+            Math.abs(wallR - Math.round(kernel)) >= 2) {
+            return `elapsed: ${wallR}s (kernel training: ${Math.round(kernel)}s)`;
+        }
+        return `elapsed: ${wallR}s`;
+    }
+    if (kernel != null && kernel >= 0) {
+        return `elapsed: ${Math.round(kernel)}s`;
+    }
+    const startedAt = data.started_at != null ? String(data.started_at) : null;
+    if (startedAt) {
+        const startedMs = Date.parse(startedAt);
+        if (!Number.isNaN(startedMs)) {
+            const elapsedSec = Math.max(0, Math.round((Date.now() - startedMs) / 1000));
+            return `elapsed: ${elapsedSec}s`;
+        }
+    }
+    return null;
+}
 export function formatJobStatusText(job_id, data) {
     const status = String(data.status ?? "unknown");
     const progress = (data.progress ?? 0) * 100;
@@ -23,10 +55,20 @@ export function formatJobStatusText(job_id, data) {
     const startedAt = data.started_at != null ? String(data.started_at) : null;
     if (startedAt) {
         parts.push(`started_at: ${startedAt}`);
-        const startedMs = Date.parse(startedAt);
-        if (!Number.isNaN(startedMs)) {
-            const elapsedSec = Math.max(0, Math.round((Date.now() - startedMs) / 1000));
-            parts.push(`elapsed: ${elapsedSec}s`);
+    }
+    const elapsedPart = formatElapsedPart(data, status);
+    if (elapsedPart) {
+        parts.push(elapsedPart);
+    }
+    if (status === "running") {
+        const etaSec = data.training_eta_sec != null ? Number(data.training_eta_sec) : null;
+        if (etaSec != null && etaSec > 0) {
+            parts.push(`ETA ~${Math.round(etaSec)}s`);
+        }
+        const epoch = data.epoch != null ? Number(data.epoch) : null;
+        const totalEpochs = data.total_epochs != null ? Number(data.total_epochs) : null;
+        if (epoch != null && totalEpochs != null && totalEpochs > 0) {
+            parts.push(`epoch ${epoch}/${totalEpochs}`);
         }
     }
     const datasetRows = data.dataset_rows != null ? Number(data.dataset_rows) : null;
@@ -48,11 +90,25 @@ export function formatJobStatusText(job_id, data) {
         const finalizeId = data.finalize_job_id != null && String(data.finalize_job_id) !== ""
             ? String(data.finalize_job_id)
             : null;
-        if (finalizeId) {
+        const finalizeFailed = data.finalize_failed === true;
+        const finalizeStatus = data.finalize_status != null && String(data.finalize_status) !== ""
+            ? String(data.finalize_status)
+            : null;
+        if (finalizeFailed) {
+            const stage = data.finalize_failure_stage != null && String(data.finalize_failure_stage) !== ""
+                ? ` [${String(data.finalize_failure_stage)}]`
+                : "";
+            parts.push(`Training kernel completed but finalize_training failed${stage} (finalize_job_id=${finalizeId ?? "unknown"}). ` +
+                `${data.finalize_error ?? "No artifacts uploaded — poll finalize job or retry finalize before results(get)."}`);
+        }
+        else if (finalizeId) {
             parts.push(`Training kernel done; finalize_training still running (finalize_job_id=${finalizeId}). Poll jobs(action=status) again to auto-wait, or poll that job directly before results(get).`);
         }
+        else if (finalizeStatus === "pending" || finalizeStatus === "running") {
+            parts.push(`Training kernel done; finalize_training ${finalizeStatus}. Poll jobs(action=status) before results(get).`);
+        }
         else {
-            parts.push(`Results ready. Use results(action=get, job_id="${job_id}") to retrieve.`);
+            parts.push(`Results ready. Use results(action=get, job_id="${job_id}") for metrics, then results_explorer(job_id="${job_id}") to browse the figures interactively.`);
         }
     }
     else if (status === "failed") {

package/dist/shared.js

@@ -26,7 +26,7 @@ export const RETRYABLE_STATUS = new Set([502, 503, 504]);
  * X-Barsom-Client-Version so the server can annotate tool guidance with the
  * wrapper version each action requires. Keep in sync with package.json on bump.
  */
-export const CLIENT_VERSION = "0.15.3";
+export const CLIENT_VERSION = "0.17.0";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Self-serve account dashboard (manage plan, billing, and API keys). */
@@ -499,6 +499,23 @@ function formatGuidanceScopeSuffix(config) {
     }
     return "";
 }
+/** Fetch normalization guide markdown from API. */
+export async function fetchNormalizationGuideFromApi() {
+    try {
+        const data = (await apiCall("GET", "/v1/docs/normalization"));
+        const md = data?.markdown;
+        if (typeof md === "string" && md.trim().length > 0) {
+            return md.trim();
+        }
+        return null;
+    }
+    catch (e) {
+        if (e?.httpStatus === 401 || e?.httpStatus === 403) {
+            throw e;
+        }
+        return null;
+    }
+}
 /** Fetch training guidance from API (used by training_guidance tool). Domain knowledge returned when asked; valid license required. Hints are filtered by plan (allowed_job_types). */
 export async function fetchTrainingGuidanceFromApi() {
     try {
@@ -508,17 +525,21 @@ export async function fetchTrainingGuidanceFromApi() {
         const presetBlock = Array.isArray(presetDesc) && presetDesc.length > 0
             ? "Presets: " + presetDesc.join(" | ") + "\n\n"
             : "";
+        const normGuide = await fetchNormalizationGuideFromApi();
+        const normBlock = normGuide
+            ? "\n\n--- Normalization guide (MAD vs SEPD, decision ladder) ---\n\n" + normGuide
+            : "\n\n(Normalization guide: GET /v1/docs/normalization — MAD vs SEPD decision ladder.)";
         const hints = config?.training_hints;
         if (Array.isArray(hints) && hints.length > 0) {
-            return presetBlock + "Parameter guidance (from API):\n- " + hints.join("\n- ") + scopeSuffix;
+            return presetBlock + "Parameter guidance (from API):\n- " + hints.join("\n- ") + scopeSuffix + normBlock;
         }
         const pg = config?.parameter_guidance;
         if (pg && typeof pg === "object") {
             const lines = Object.entries(pg).map(([k, v]) => `${k}: ${v}`);
-            return presetBlock + "Parameter guidance (from API):\n- " + lines.join("\n- ") + scopeSuffix;
+            return presetBlock + "Parameter guidance (from API):\n- " + lines.join("\n- ") + scopeSuffix + normBlock;
         }
         if (presetBlock)
-            return presetBlock + "No additional parameter guidance in config." + scopeSuffix;
+            return presetBlock + "No additional parameter guidance in config." + scopeSuffix + normBlock;
     }
     catch (e) {
         if (e?.httpStatus === 401 || e?.httpStatus === 403)

package/dist/tools/datasets.js

@@ -75,6 +75,29 @@ function formatAnalyzeResult(data, dataset_id) {
         }
         lines.push(``);
     }
+    const normHints = data.normalization_hints;
+    if (normHints && Object.keys(normHints).length > 0) {
+        lines.push(`Normalization hints (suggestions only — confirm before train):`);
+        for (const col of columns) {
+            const h = normHints[col];
+            if (h)
+                lines.push(`  • ${col}: ${h}`);
+        }
+        lines.push(`  See training_guidance for MAD vs SEPD decision ladder.`, ``);
+    }
+    const stagingStats = data.column_staging_stats;
+    if (stagingStats && Object.keys(stagingStats).length > 0) {
+        lines.push(`Full-dataset staging stats (from stats.json; hints above are sample-based):`);
+        for (const col of columns) {
+            const st = stagingStats[col];
+            if (!st)
+                continue;
+            const count = st.count;
+            const nullCount = st.null_count;
+            lines.push(`  • ${col}: count=${count ?? "?"}, null_count=${nullCount ?? "?"}`);
+        }
+        lines.push(``);
+    }
     const nextSteps = [];
     if (trainList.length > 0) {
         nextSteps.push(`Train with columns: [${trainList.join(", ")}].`);
@@ -112,7 +135,7 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~100 MB, pre
 
 action=upload: PREFER file_path — server reads from workspace root (token-efficient; no file content in context). Accepts .csv, .tsv, .csv.gz, .tsv.gz. Use csv_data only for small inline pastes (e.g. <10KB). Returns dataset ID. Then use datasets(action=preview) before train(action=map). If plain CSV exceeds the 5 GB upload cap, gzip it first (.csv.gz).
 
-Step 0 (before upload): (1) CSV with header; one row per observation. (2) Columns you will use for training must be numeric (or datetime if you will use temporal extraction). (3) Complete-case path (train action=map): no NaNs in training columns. Sparse path (train action=impute): missing cells in training columns are OK — the job trains missSOM and returns dense imputed.csv; plain numeric columns only. (4) Categoricals: encode (e.g. one-hot, label) or exclude — do not use raw categorical columns as training features; preview shows which columns are non-numeric. (5) Optional: if you plan to use transition_flow, sort rows chronologically before upload.
+Step 0 (before upload): (1) CSV with header; one row per observation. (2) Columns you will use for training must be numeric (or datetime if you will use temporal extraction). (3) Complete-case path (train action=map): no NaNs in training columns. Sparse path (train action=impute): missing cells in training columns are OK — the job trains missSOM and returns dense imputed.csv; plain numeric columns only. (4) Categoricals: encode (e.g. one-hot, label) or exclude — do not use raw categorical columns as training features; preview shows which columns are non-numeric. (5) Optional: if you plan to use inference(action=transition_flow), sort rows chronologically before upload.
 Step 1 (after upload): always datasets(action=preview) to verify column types and spot cyclics/datetime, then choose train_map (complete-case) or train_impute (sparse) before submit.
 
 action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train(action=map) on an unfamiliar dataset.

package/dist/tools/explore_map.js

@@ -158,7 +158,7 @@ async function handleResultsExplorer(job_id) {
 export function registerExploreMapTool(server) {
     const toolConfig = {
         title: "Results Explorer",
-        description: "Interactive results explorer for a completed map job. Opens a simple responsive view for browsing key metrics and available figures. Falls back to a standalone localhost page when needed.",
+        description: "PREFERRED way to browse a completed map's figures after a first results(get) glance. Interactive explorer for a completed map job: a responsive view of key metrics and every available figure (combined, U-matrix, hit histogram, component planes). Embeds as an MCP App or falls back to a standalone localhost page. Offer it to the user once a train job completes; results(get) remains the headless/metrics path.",
         inputSchema: {
             job_id: z.string().describe("Job ID of a completed map training job"),
         },

package/dist/tools/inference.js

@@ -62,9 +62,10 @@ export function registerInferenceTool(server) {
 | impute_column | Fill a numeric column (not used in training) by pooling observed values on the BMU plus topology neighbors (typically 6 on hex; periodic maps wrap) | 5–120s |
 | compare | Comparing hit distributions of a second dataset against training (drift, A/B); needs one trained job_id + dataset B. NOT jobs(compare), which tabulates metrics across multiple training runs. | 30–120s |
 | project_columns | Project one or more dataset columns onto the map (component planes); dataset can be training set or partial-feature set | 10–90s |
+| transition_flow | Temporal state-transition arrows on the trained map. Only meaningful when the scored rows are in chronological order. | 30–60s |
 | report | Get a report manifest (artifact keys + URLs) to build your own report in Quarto/Notebook/script | Immediate (sync) |
 
-Sync/async: predict, impute_column, and compare are async jobs that the proxy auto-polls and usually returns on completion; if one returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...). batch_predict does NOT auto-poll — it returns a list of submitted job_ids; poll each with jobs(action=status).
+Sync/async: predict, impute_column, compare, and transition_flow are async jobs that the proxy auto-polls and usually returns on completion; if one returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...). batch_predict does NOT auto-poll — it returns a list of submitted job_ids; poll each with jobs(action=status).
 Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict (output="compact") → predictions.csv; predict (output="annotated") → annotated.csv; impute_column → imputed.csv; compare → density-diff figure (e.g. density_diff.png).
 report is the only synchronous inference action — returns manifest immediately; no job to poll.
 NOT FOR: Retraining or changing the map — all actions treat the trained map as frozen.
@@ -86,10 +87,11 @@ action=impute_column: Map-local imputation on the frozen trained map (read-only;
 
 action=compare: density-diff of a cohort dataset against the training set on ONE trained map — NOT jobs(action=compare) (which tabulates QE/TE/EV metrics across multiple training runs to pick the best). dataset_id must refer to a dataset with the same feature set as training (same column names and preprocessing, including cyclic expansion). A = training dataset; B = cohort to compare. Density-diff: positive = B gained vs A; negative = A had more. Returns density-diff heatmap (e.g. density_diff.png).
 action=project_columns: Project one or more columns from a dataset onto the trained map. Pass dataset_id (the dataset containing the columns) and columns (array of column names). Uses cached BMUs when dataset is the training set; supports partial-feature mapping when dataset has only a subset of training features. Returns one component plane image per column. Get files via results(action=download, job_id=<returned_job_id>).
+action=transition_flow: Temporal state-transition arrows drawn on the trained map grid (U-matrix background). Post-training analysis of how observations move across the map over time — use ONLY when rows are in chronological order; on unordered data the arrows are meaningless. You pass the training job_id; the API returns a NEW result job_id (use it for results(action=get/download)). lag=1 (default) = consecutive rows; lag=N = N-step horizon (e.g. 24 for daily cycles in hourly data). min_transitions filters noisy arrows (increase for large datasets). Auto-polled.
 action=report: Returns a report manifest for the given job_id (job must be completed). Includes figure_manifest (logical names → filenames), download_urls for all artifacts, cluster_summary when available, and summary metrics. Stakeholder report PDF (if generated) is available via results(action=download, job_id=<training_job_id>), filename e.g. report.pdf.`, {
         action: z
-            .enum(["predict", "batch_predict", "impute_column", "compare", "project_columns", "report"])
-            .describe("predict: score rows; batch_predict: fan out many predict jobs at once; impute_column: topology-neighbor pool imputation for a column not in training; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report."),
+            .enum(["predict", "batch_predict", "impute_column", "compare", "project_columns", "transition_flow", "report"])
+            .describe("predict: score rows; batch_predict: fan out many predict jobs at once; impute_column: topology-neighbor pool imputation for a column not in training; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; transition_flow: temporal state-transition arrows on the map (time-ordered rows only); report: manifest of primitives for custom report."),
         job_id: z.string().describe("Job ID of a completed map training job"),
         inputs: z
             .array(z.object({
@@ -114,11 +116,48 @@ action=report: Returns a report manifest for the given job_id (job must be compl
             .describe("action=impute_column: instantaneous (default) = pool mean/median; categorical = pool mode; cumulative = monotonic-counter (pool aggregation is rough; warns). A monotonic-counter warning is emitted automatically regardless."),
         weighting: z.enum(["distance", "uniform"]).optional()
             .describe("action=impute_column: distance (default) weights pooled values by map-neighbourhood proximity (closer BMU nodes count more); uniform is a flat pool."),
-    }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n, target_column, only_missing, impute_aggregation, cv_folds, target_column_kind, weighting, inputs }) => {
+        lag: z.number().int().min(1).optional().default(1)
+            .describe("action=transition_flow: step lag (default 1 = consecutive rows). Use larger for periodic horizons (e.g. 24 for daily cycles in hourly data)."),
+        min_transitions: z.number().int().min(1).optional()
+            .describe("action=transition_flow: minimum transition count to draw an arrow (default: auto). Increase to filter noise on large datasets."),
+        top_k: z.number().int().min(1).optional().default(10)
+            .describe("action=transition_flow: number of top-flow nodes in the statistics summary (default 10)."),
+    }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n, target_column, only_missing, impute_aggregation, cv_folds, target_column_kind, weighting, inputs, lag, min_transitions, top_k }) => {
         const dpiMap = { standard: 1, retina: 2, print: 4 };
         const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
         if (action === "batch_predict")
             return runBatchPredict({ job_id, inputs });
+        if (action === "transition_flow") {
+            const body = { lag: lag ?? 1, output_format: output_format ?? "png" };
+            if (min_transitions !== undefined)
+                body.min_transitions = min_transitions;
+            if (top_k !== undefined)
+                body.top_k = top_k;
+            if (colormap !== undefined)
+                body.colormap = colormap;
+            if (output_dpi && output_dpi !== "retina")
+                body.output_dpi = dpiMap[output_dpi] ?? 2;
+            const data = (await apiCall("POST", `/v1/results/${job_id}/transition-flow`, body));
+            const flowJobId = data.id;
+            const poll = await pollUntilComplete(flowJobId, 120_000);
+            if (poll.status === "completed") {
+                const res = (await apiCall("GET", `/v1/results/${flowJobId}`));
+                const summary = (res.summary ?? {});
+                const stats = (summary.flow_stats ?? {});
+                const content = [{ type: "text", text: [
+                            `Transition Flow (job: ${flowJobId}) | Parent map: ${job_id} | Lag: ${lag ?? 1}`,
+                            `Active flow nodes: ${stats.active_flow_nodes ?? "N/A"} | Total transitions: ${stats.total_transitions ?? "N/A"}`,
+                            `Mean magnitude: ${stats.mean_magnitude !== undefined ? Number(stats.mean_magnitude).toFixed(4) : "N/A"}`,
+                            `Arrows show net directional drift on the map; use a larger lag for longer-term structure. To persist: results(action=download, job_id="${flowJobId}").`,
+                        ].join("\n") }];
+                await tryAttachImage(content, flowJobId, `transition_flow_lag${lag ?? 1}.${output_format ?? "png"}`);
+                return { content };
+            }
+            if (poll.status === "failed") {
+                return { content: [{ type: "text", text: `inference(transition_flow) job ${flowJobId} failed: ${poll.error ?? "unknown error"}` }] };
+            }
+            return { content: [{ type: "text", text: `inference(transition_flow) job ${flowJobId} submitted. Poll with jobs(action=status, job_id="${flowJobId}"), then results(action=get, job_id="${flowJobId}").` }] };
+        }
         if (action === "predict") {
             const outputStyle = output ?? "compact";
             if (outputStyle === "annotated" && rows) {

package/dist/tools/jobs.js

@@ -3,10 +3,7 @@ import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { formatJobCancelText, formatJobStatusText } from "../job_status_format.js";
 import { pollFinalizeIfPresent, refreshJobAfterFinalize } from "../train_finalize.js";
-import { runTrain } from "./train.js";
-import { runBatchPredict } from "./inference.js";
-import { TRAINING_INPUT_SCHEMA } from "./training_core.js";
-export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle).
+export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle only).
 
 | Action | Use when |
 |--------|----------|
@@ -16,7 +13,7 @@ export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle).
 | cancel | Stopping a running or pending job to free the worker |
 | delete | Permanently removing a job and all its S3 result files |
 
-To SUBMIT training, use the **train** tool (train(action=map | siom_map | impute | floop_siom | baseline_study)); to score data, use **inference**. The jobs(action=train_map | train_siom_map | train_impute | train_floop_siom | run_baseline_study | batch_predict) actions still work as **deprecated** forwarders for one release — migrate to train / inference.
+To SUBMIT training, use the **train** tool (train(action=map | siom_map | impute | floop_siom)); to score data or run post-training map operations (predict, batch_predict, compare, project_columns, impute_column, transition_flow), use **inference**.
 
 ASYNC POLLING PROTOCOL (action=status):
 - Poll every 10-15 seconds. Do NOT poll faster — it wastes context.
@@ -66,6 +63,16 @@ export function renderCompareTable(comparisons) {
     const candidates = [
         { key: "grid", label: "Grid", render: renderGrid },
         { key: "epochs", label: "Epochs", render: renderEpochs },
+        { key: "topology", label: "Topology", render: fmtAny },
+        { key: "max_nodes", label: "MaxNodes", render: fmtAny },
+        { key: "n_initial", label: "NInitial", render: fmtAny },
+        { key: "growth_interval", label: "GrowthInt", render: fmtAny },
+        { key: "gamma", label: "Gamma", render: fmtAny },
+        { key: "siom_decay", label: "SIOMDecay", render: fmtAny },
+        { key: "elastic_lambda", label: "Elasticλ", render: fmtAny },
+        { key: "elastic_mu", label: "Elasticμ", render: fmtAny },
+        { key: "elastic_anchor", label: "ElasticAnchor", render: fmtAny },
+        { key: "effort", label: "Effort", render: fmtAny },
         { key: "model", label: "Model", render: fmtAny },
         { key: "periodic", label: "Periodic", render: fmtAny },
         { key: "backend", label: "Backend", render: fmtAny },
@@ -127,27 +134,15 @@ export function renderCompareTable(comparisons) {
     }
     return lines.join("\n");
 }
-/** Deprecated jobs(train_*) / run_baseline_study actions -> the train tool's concise actions. */
-const TRAIN_ALIAS = {
-    train_map: "map",
-    train_siom_map: "siom_map",
-    train_impute: "impute",
-    train_floop_siom: "floop_siom",
-    run_baseline_study: "baseline_study",
-};
 export function registerJobsTool(server, description) {
     registerAuditedTool(server, "jobs", description, {
         action: z
-            .enum([
-            "status", "list", "compare", "cancel", "delete",
-            // Deprecated forwarders (kept for one release; use train / inference).
-            "train_map", "train_siom_map", "train_impute", "train_floop_siom", "run_baseline_study", "batch_predict",
-        ])
-            .describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files. DEPRECATED forwarders: train_map/train_siom_map/train_impute/train_floop_siom/run_baseline_study (use the train tool); batch_predict (use inference)."),
+            .enum(["status", "list", "compare", "cancel", "delete"])
+            .describe("status: check progress; list: see all jobs; compare: metrics table; cancel: stop job; delete: remove job + files. (Training is submitted via the train tool; scoring / post-training map ops via inference.)"),
         job_id: z
             .string()
             .optional()
-            .describe("Job ID — required for action=status, cancel, delete, and the deprecated batch_predict (parent training job)."),
+            .describe("Job ID — required for action=status, cancel, delete."),
         job_ids: z
             .array(z.string())
             .optional()
@@ -155,44 +150,9 @@ export function registerJobsTool(server, description) {
         dataset_id: z
             .string()
             .optional()
-            .describe("action=list: filter jobs by this dataset ID. Also required by the deprecated train_* forwarders."),
-        label: z
-            .string()
-            .max(120)
-            .optional()
-            .describe("Optional run label for the deprecated train_* forwarders (≤120 chars; appears in jobs(list) and the jobs(compare) table)."),
-        inputs: z
-            .array(z.object({
-            dataset_id: z.string().optional(),
-            rows: z.array(z.record(z.string(), z.number())).optional(),
-        }))
-            .optional()
-            .describe("Deprecated batch_predict forwarder: array of inputs; each item has dataset_id and/or rows."),
-        // Deprecated: training parameters accepted only by the jobs(train_*) forwarders.
-        // Submit training via the `train` tool instead; these are removed in a later release.
-        ...TRAINING_INPUT_SCHEMA,
+            .describe("action=list: filter jobs by this dataset ID."),
     }, async (args) => {
         const { action, job_id, job_ids, dataset_id } = args;
-        // ---- Deprecated forwarders -> train / inference ----
-        const mapped = TRAIN_ALIAS[action];
-        if (mapped) {
-            const result = await runTrain(mapped, args);
-            return {
-                content: [
-                    ...result.content,
-                    { type: "text", text: `Note: jobs(action=${action}) is deprecated; use train(action=${mapped}).` },
-                ],
-            };
-        }
-        if (action === "batch_predict") {
-            const result = await runBatchPredict({ job_id, inputs: args.inputs });
-            return {
-                content: [
-                    ...result.content,
-                    { type: "text", text: "Note: jobs(action=batch_predict) is deprecated; use inference(action=batch_predict)." },
-                ],
-            };
-        }
         // ---- Lifecycle ----
         if (action === "status") {
             if (!job_id)