@barivia/barsom-mcp 0.8.0 → 0.9.0

package/README.md

@@ -126,7 +126,8 @@ All actions use a frozen trained map — no retraining. Derived columns use **`d
 
 | Action | Output | Timing |
 |--------|--------|--------|
-| `predict` | Score rows against the trained map. **Inputs:** `dataset_id` (defaults to the parent training dataset) **or** inline `rows` (≤500). **Output style** (`output` param): `"compact"` → `predictions.csv` (row_id, bmu_x/y, bmu_node_index, cluster_id [+ QE / qe_p95 / potential_anomaly when scoring **new** data]); `"annotated"` → `enriched.csv` (original CSV + BMU columns appended). **Regime auto-detected:** when the resolved dataset matches the training dataset, QE columns are intentionally omitted in compact output (training-set fit ≠ generalisation; the p95 anomaly flag would be circular). Prefer `dataset_id` for batches and SIOM/irregular maps. | 5–120s |
+| `predict` | Score rows against the trained map. **Inputs:** `dataset_id` (defaults to the parent training dataset) **or** inline `rows` (≤500). **Output style** (`output` param): `"compact"` → `predictions.csv` (row_id, bmu_x/y, bmu_node_index, cluster_id [+ QE / qe_p95 / potential_anomaly when scoring **new** data]); `"annotated"` → `annotated.csv` (original CSV + BMU columns appended). **Regime auto-detected:** when the resolved dataset matches the training dataset, QE columns are intentionally omitted in compact output (training-set fit ≠ generalisation; the p95 anomaly flag would be circular). Prefer `dataset_id` for batches and SIOM/irregular maps. | 5–120s |
+| `impute_column` | Fill a numeric **target_column** not used in training: **requires** `dataset_id` + `target_column`. 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`**. | 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 |
 | `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 |
@@ -168,7 +169,6 @@ The right viewer depends on **(MCP App support)** **and** **(can the human reach
 ### Migration notes
 
 - **`explore_map` → `results_explorer`:** Update Cursor, Claude Desktop, or other MCP configs that still reference `explore_map`. The alias remains for backward compatibility.
-- **`inference(action=enrich)` → `inference(action=predict, output="annotated")`:** the `enrich` action has been removed in favor of regime-aware `predict`. Calling `predict` with `output="annotated"` (and the default training dataset) returns the same `enriched.csv` artifact. Calling `predict` on the training dataset with the default `output="compact"` now correctly omits QE / `qe_p95` / `potential_anomaly` fields — those are fitting errors on training data, not generalisation metrics.
 - **Shorter `info` prompt:** Clients that relied on the old long `info` text should use **`guide_barsom_workflow`** or server **instructions** for the full story.
 
 ### `send_feedback`

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 a}from"@modelcontextprotocol/ext-apps/server";import{startVizServer as s}from"./viz-server.js";import{API_KEY as i,apiCall as l,apiRawCall as p,loadViewHtml as c,setVizPort as m,setClientSupportsMcpApps as d}from"./shared.js";import{registerDatasetsTool as u}from"./tools/datasets.js";import{registerJobsTool as f,JOBS_DESCRIPTION_BASE as g}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as b}from"./tools/explore_map.js";import{registerAccountTool as w}from"./tools/account.js";import{registerInferenceTool as y}from"./tools/inference.js";import{registerGuideBarsomTool as j}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as v}from"./tools/training_guidance.js";import{registerFeedbackTool as P}from"./tools/feedback.js";import{registerTrainingPrepTools as x,TRAINING_PREP_URI as I}from"./tools/training_prep.js";import{registerTrainingMonitorTool as k,TRAINING_MONITOR_URI as M}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as O}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:"0.8.0",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 `jobs(train_map)`, `jobs(train_siom_map)`, or `jobs(train_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, subset, add_expression, reduce_spectral (pca/log_sample/uniform_sample/stats for long ordered numeric blocks), delete |\n| Jobs | `jobs` | train_map, train_siom_map, train_floop_siom (entitled), status, list, compare, cancel, delete, batch_predict, run_baseline_study; `train_floop_chain` = deprecated alias for train_floop_siom |\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"; "annotated" replaces the removed `enrich`), 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; `explore_map` = deprecated alias of `results_explorer`; `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. Slow networks: users can raise `BARIVIA_FETCH_TIMEOUT_MS`.\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,b,b,{mimeType:a},async()=>{const e=await c("results-explorer");return{contents:[{uri:b,mimeType:a,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(S,I,I,{mimeType:a},async()=>{const e=await c("training-prep");return{contents:[{uri:I,mimeType:a,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(S,M,M,{mimeType:a},async()=>{const e=await c("training-monitor");return{contents:[{uri:M,mimeType:a,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),j(S),h(S),x(S),k(S),u(S),f(S,g),_(S),w(S),y(S),v(S),P(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), `jobs` (train/poll/compare/…; train_map accepts an optional `label` for readable compare rows), `results` (get/download/export/recolor/transition_flow; figures="none" for metrics-only), `inference` (predict regime-aware with output="compact"|"annotated"; replaces enrich, 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 O(e)}}]}));const A=new t;(async function(){try{const e=await s(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(a))},await S.connect(A)})().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 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{registerJobsTool as g,JOBS_DESCRIPTION_BASE as _}from"./tools/jobs.js";import{registerResultsTool as b}from"./tools/results.js";import{registerExploreMapTool as h,RESULTS_EXPLORER_URI as y}from"./tools/explore_map.js";import{registerAccountTool as w}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as v}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as P}from"./tools/training_guidance.js";import{registerFeedbackTool as x}from"./tools/feedback.js";import{registerTrainingPrepTools as I,TRAINING_PREP_URI as k}from"./tools/training_prep.js";import{registerTrainingMonitorTool as M,TRAINING_MONITOR_URI as O}from"./tools/training_monitor.js";import{resolvePrepareTrainingPromptText as S}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 A=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 `jobs(train_map)`, `jobs(train_siom_map)`, or `jobs(train_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, subset, add_expression, reduce_spectral (pca/log_sample/uniform_sample/stats for long ordered numeric blocks), delete |\n| Jobs | `jobs` | train_map, train_siom_map, train_floop_siom (entitled), status, list, compare, cancel, delete, batch_predict, run_baseline_study; `train_floop_chain` = deprecated alias for train_floop_siom |\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"), 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; `explore_map` = deprecated alias of `results_explorer`; `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. Slow networks: users can raise `BARIVIA_FETCH_TIMEOUT_MS`.\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(A,y,y,{mimeType:s},async()=>{const e=await c("results-explorer");return{contents:[{uri:y,mimeType:s,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),n(A,k,k,{mimeType:s},async()=>{const e=await c("training-prep");return{contents:[{uri:k,mimeType:s,text:e??"<html><body>Training Preparation view not built yet.</body></html>"}]}}),n(A,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>"}]}}),v(A),h(A),I(A),M(A),f(A),g(A,_),b(A),w(A),j(A),P(A),x(A),A.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), `jobs` (train/poll/compare/…; train_map accepts an optional `label` for readable compare rows), `results` (get/download/export/recolor/transition_flow; figures="none" for metrics-only), `inference` (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")}}]})),A.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 T=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=A.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(s))},await A.connect(T)})().catch(console.error);

package/dist/shared.js

@@ -14,6 +14,12 @@ export const API_KEY = process.env.BARIVIA_API_KEY ?? process.env.BARSOM_API_KEY
 export const FETCH_TIMEOUT_MS = parseInt(process.env.BARIVIA_FETCH_TIMEOUT_MS ?? "30000", 10);
 export const MAX_RETRIES = 2;
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
+/**
+ * Single source of truth for the proxy version. Sent to the API as
+ * 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.9.0";
 /** User-facing links; keep aligned with barivia.se / api.barivia.se. */
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Poll window for datasets(add_expression) / derive jobs (server-side work can exceed 30s). */
@@ -256,12 +262,18 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
         Authorization: `Bearer ${API_KEY}`,
         "Content-Type": contentType,
         "X-Request-ID": requestId,
+        "X-Barsom-Client-Version": CLIENT_VERSION,
         ...extraHeaders,
     };
     let serializedBody;
     if (body !== undefined) {
-        serializedBody =
-            contentType === "application/json" ? JSON.stringify(body) : String(body);
+        if (body instanceof Uint8Array) {
+            serializedBody = body; // pre-encoded bytes (e.g. gzipped CSV upload)
+        }
+        else {
+            serializedBody =
+                contentType === "application/json" ? JSON.stringify(body) : String(body);
+        }
     }
     const effectiveTimeout = requestTimeoutMs ?? FETCH_TIMEOUT_MS;
     const t0 = Date.now();

package/dist/tools/datasets.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { gzipSync } from "node:zlib";
 import { z } from "zod";
 import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, POLL_DERIVE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, } from "../shared.js";
 export function registerDatasetsTool(server) {
@@ -33,7 +34,7 @@ action=subset: Create a new dataset from a subset of an existing one. Requires n
   - Single filter object is also accepted (auto-wrapped).
 action=reduce_spectral: Run a pre-training reducer over an ordered block of numeric columns. All four methods produce one feature vector per row (rows in = rows out; only the column dimension is collapsed) and append derived columns to the dataset. Choose by data shape:
   - pca:            top-k principal components — general first try when many columns are correlated (spectroscopy, gene panels, sensor arrays). Returns explained_variance_ratio.
-  - log_sample:     keep k columns at log-spaced indices — SAXS/scattering, audio frequency bands, attenuation curves (anywhere the index axis is logarithmically informative).
+  - log_sample:     keep k columns at log-spaced indices — SAXS/WAXS & powder diffraction, log-frequency / octave-like audio, attenuation vs wavelength (UV–Vis–IR stacks), depth profiling, chromatography retention ladders — anywhere column order is exponential, logarithmic, or perceptually log-spaced.
   - uniform_sample: keep k columns at evenly-spaced indices — regularly-sampled time series, frame-by-frame features, evenly-binned histograms.
   - stats:          6 fixed per-row statistics (mean, std, min, max, skew, integral) — cheap baseline for any sequenced numeric block; k is ignored.
   Required params: name (prefix for derived columns), method, columns_block (ordered source column names ≥ 2), k (≥ 1, < length(columns_block); ignored for stats).
@@ -114,7 +115,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 if (ext !== ".csv" && ext !== ".tsv") {
                     throw new Error("Only .csv and .tsv files can be uploaded as datasets.");
                 }
-                const MAX_UPLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
+                const MAX_UPLOAD_BYTES = 256 * 1024 * 1024; // 256 MB (gzip keeps the wire payload small)
                 try {
                     const stat = await fs.stat(resolved);
                     if (stat.size > MAX_UPLOAD_BYTES) {
@@ -135,10 +136,19 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             else {
                 throw new Error("datasets(upload) requires file_path or csv_data. Prefer file_path for token efficiency.");
             }
-            const data = (await apiCall("POST", "/v1/datasets", body, {
+            // gzip large CSVs to keep the wire payload (and the API's compressed-body
+            // cap) small; the API transparently decompresses. Small bodies stay plain.
+            const GZIP_THRESHOLD = 1024 * 1024; // 1 MB
+            const uploadHeaders = {
                 "X-Dataset-Name": name,
                 "Content-Type": "text/csv",
-            }, UPLOAD_DATASET_TIMEOUT_MS));
+            };
+            let uploadBody = body;
+            if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
+                uploadBody = gzipSync(Buffer.from(body, "utf-8"));
+                uploadHeaders["Content-Encoding"] = "gzip";
+            }
+            const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null)
                 data.suggested_next_step = `Suggested next step: datasets(action=preview, dataset_id=${id}) to inspect columns before training.`;

package/dist/tools/inference.js

@@ -35,12 +35,13 @@ export function registerInferenceTool(server) {
 | Action | Use when | Timing |
 |--------|----------|--------|
 | predict | Scoring rows against the trained map (new data OR the training set itself) | 5–120s |
+| 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) | 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 |
 | report | Get a report manifest (artifact keys + URLs) to build your own report in Quarto/Notebook/script | Immediate (sync) |
 
-Sync/async: predict and compare are async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
-Artifacts: When complete, use results(action=download, job_id=<returned_job_id>) to get: predict (output="compact") → predictions.csv; predict (output="annotated") → enriched.csv; compare → density-diff figure (e.g. density_diff.png).
+Sync/async: predict, impute_column, and compare are async jobs. The proxy auto-polls and usually returns when the job completes. If it returns a job_id instead (e.g. timeout), poll jobs(action=status, job_id=...) then results(action=download, job_id=...) to retrieve the artifact.
+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.
 ESCALATION: If any action returns "missing column", verify column names with datasets(action=preview). Column names are case-sensitive and must match the training feature set exactly.
@@ -51,7 +52,7 @@ action=predict: Score rows against the trained map.
     - rows (≤500 inline). Always treated as new data.
   Output style (output param, default "compact"):
     - "compact"   → predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id [, quantization_error, potential_anomaly]).
-    - "annotated" → enriched.csv (the full source CSV with bmu_x, bmu_y, bmu_node_index, cluster_id appended). Requires a dataset (no inline rows). Replaces the previous inference(action=enrich) — migrate by passing output="annotated".
+    - "annotated" → annotated.csv (full source CSV with bmu_x, bmu_y, bmu_node_index, cluster_id appended). Requires a dataset (no inline rows).
   Regime auto-detected:
     - If the resolved dataset matches the parent training dataset, regime="training" and QE / qe_p95 / potential_anomaly fields are omitted from the compact output. QE on training data is fitting error, not a generalisation metric, and the p95 anomaly flag would be circular. Use a held-out dataset for quality assessment.
     - Otherwise regime="new" and the full QE columns are returned.
@@ -59,22 +60,32 @@ action=predict: Score rows against the trained map.
   Routing: prefer dataset_id for many rows or whenever the map uses irregular SIOM / GeneralTopology layouts — the async worker path is the supported batch scorer. Single-row rows take a fast stateless path that may return invalid_inference_input on some topologies; if so, retry with dataset_id (a one-row dataset is fine). FLooP-SIOM: use dataset_id predict first.
   When the scored set has at most ${PREDICT_PREVIEW_ROW_CAP} rows, completed responses include a short per-line preview in the tool text for chat agents.
 
+action=impute_column: Map-local imputation as read-only post-processing (the trained map is frozen; not a held-out validity claim). Requires dataset_id + target_column. The dataset must contain all training features (same names and cyclic expansion as predict) plus the target column. target_column must NOT have been in jobs(train_map) columns — train without it, then impute. Pools finite target values from rows whose BMUs lie on this row's BMU and its topology neighbors (BMU + neighbors, often 7 nodes on hex interior; fewer on borders if the parent map is non-periodic; periodic hex wraps), aggregated neighbourhood-distance-weighted by default (weighting="distance" — closer nodes count more; weighting="uniform" for a flat pool). Excludes the current row from its own pool. only_missing (default true): keep observed values. impute_aggregation: mean or median of the pool. Optional cv_folds (2-20) writes quality.csv (held-out MAE/RMSE/R2); target_column_kind handles categorical (mode) / cumulative (warns). Output imputed.csv: row_id, target_original, target_imputed, impute_source (observed | imputed | insufficient_data), bmu_node_index, n_patch_nodes, n_pool_rows, pool_std, pool_p5, pool_p95.
+
 action=compare: 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=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", "compare", "project_columns", "report"])
-            .describe("predict: score rows; compare: drift/cohort diff heatmap; project_columns: project dataset columns onto map; report: manifest of primitives for custom report. (Note: the previous 'enrich' action is now predict with output=\"annotated\".)"),
+            .enum(["predict", "impute_column", "compare", "project_columns", "report"])
+            .describe("predict: score rows; 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."),
         job_id: z.string().describe("Job ID of a completed map training job"),
-        dataset_id: z.string().optional().describe("action=predict/compare/project_columns: Dataset ID. predict=data to score (defaults to the training dataset when omitted); compare=dataset B; project_columns=dataset with columns to project."),
+        dataset_id: z.string().optional().describe("action=predict/impute_column/compare/project_columns: Dataset ID. predict=data to score (defaults to the training dataset when omitted); impute_column=dataset with training features + target_column; compare=dataset B; project_columns=dataset with columns to project."),
         columns: z.array(z.string()).optional().describe("action=project_columns: column names to project onto the map (must exist in the dataset)."),
         rows: z.array(z.record(z.string(), z.union([z.number(), z.string()]))).optional().describe("action=predict: inline rows to score (max 500). For a single inline row, raw categorical strings are allowed for baseline categorical_features models. Batch rows should remain numeric and match the training schema."),
-        output: z.enum(["compact", "annotated"]).optional().default("compact").describe("action=predict: output style. compact = predictions.csv (default); annotated = enriched.csv (original CSV + BMU columns). Use annotated to get the training set with BMU labels appended (the former inference(action=enrich) workflow)."),
+        output: z.enum(["compact", "annotated"]).optional().default("compact").describe("action=predict: output style. compact = predictions.csv (default); annotated = annotated.csv (original rows plus bmu_x, bmu_y, bmu_node_index, cluster_id)."),
         colormap: z.string().optional().describe("action=compare: colormap for diff heatmap (default: balance). action=report: n/a."),
         output_format: z.enum(["png", "pdf", "svg"]).optional().default("png").describe("action=compare: output format for heatmap (default: png)"),
         output_dpi: z.enum(["standard", "retina", "print"]).optional().default("retina").describe("Resolution: standard (1x), retina (2x, default), print (4x)"),
         top_n: z.number().int().min(1).max(50).optional().default(10).describe("action=compare: number of top gained/lost nodes to report (default: 10)"),
-    }, async ({ action, job_id, dataset_id, columns, rows, output, colormap, output_format, output_dpi, top_n }) => {
+        target_column: z.string().optional().describe("action=impute_column: numeric column to impute (must not be a training feature)."),
+        only_missing: z.boolean().optional().default(true).describe("action=impute_column: if true, leave observed values unchanged."),
+        impute_aggregation: z.enum(["mean", "median"]).optional().default("mean").describe("action=impute_column: aggregation over pooled neighbor rows."),
+        cv_folds: z.number().int().min(2).max(20).optional().describe("action=impute_column: if set (2-20), run k-fold cross-validation on observed target cells and emit quality.csv with MAE / RMSE / R2 (held-out). Omit to skip."),
+        target_column_kind: z.enum(["instantaneous", "cumulative", "categorical"]).optional()
+            .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 }) => {
         const dpiMap = { standard: 1, retina: 2, print: 4 };
         const numericDpi = dpiMap[output_dpi ?? "retina"] ?? 2;
         if (action === "predict") {
@@ -122,7 +133,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 const regime = String(summary.regime ?? "new");
                 const effectiveStyle = String(summary.output_style ?? outputStyle);
                 const isAnnotated = effectiveStyle === "annotated";
-                const artifactName = isAnnotated ? "enriched.csv" : "predictions.csv";
+                const artifactName = isAnnotated ? "annotated.csv" : "predictions.csv";
                 const headerLine = isAnnotated
                     ? `Annotated dataset ready — job: ${predictJobId}`
                     : `Predictions complete — job: ${predictJobId}`;
@@ -133,7 +144,7 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                     ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
                     : "";
                 const outputLine = isAnnotated
-                    ? `Output: enriched.csv (original CSV + bmu_x, bmu_y, bmu_node_index, cluster_id appended). Clusters: ${summary.n_clusters ?? Object.keys(summary.cluster_counts ?? {}).length}.`
+                    ? `Output: annotated.csv (original CSV + bmu_x, bmu_y, bmu_node_index, cluster_id appended). Clusters: ${summary.n_clusters ?? Object.keys(summary.cluster_counts ?? {}).length}.`
                     : (regime === "training"
                         ? `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id). Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`
                         : `Output: predictions.csv (row_id, bmu_x, bmu_y, bmu_node_index, cluster_id, quantization_error, potential_anomaly). Summary includes mean_qe, max_qe, qe_p95. Clusters: ${Object.keys(summary.cluster_counts ?? {}).length}.`);
@@ -152,6 +163,44 @@ action=report: Returns a report manifest for the given job_id (job must be compl
                 return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} failed: ${poll.error ?? "unknown error"}` }] };
             return { content: [{ type: "text", text: `inference(predict) job ${predictJobId} submitted. Poll with jobs(action=status, job_id="${predictJobId}").` }] };
         }
+        if (action === "impute_column") {
+            if (!dataset_id)
+                throw new Error("inference(impute_column) requires dataset_id");
+            if (!target_column?.trim())
+                throw new Error("inference(impute_column) requires target_column");
+            const body = {
+                dataset_id,
+                target_column: target_column.trim(),
+                only_missing: only_missing ?? true,
+                aggregation: impute_aggregation ?? "mean",
+            };
+            if (cv_folds !== undefined)
+                body.cv_folds = cv_folds;
+            if (target_column_kind !== undefined)
+                body.target_column_kind = target_column_kind;
+            if (weighting !== undefined)
+                body.weighting = weighting;
+            const data = (await apiCall("POST", `/v1/results/${job_id}/impute_column`, body));
+            const imputeJobId = data.id;
+            const poll = await pollUntilComplete(imputeJobId, 120_000);
+            if (poll.status === "completed") {
+                const results = (await apiCall("GET", `/v1/results/${imputeJobId}`));
+                const summary = (results.summary ?? {});
+                const urls = (results.download_urls ?? {});
+                return { content: [{ type: "text", text: [
+                                `Impute column complete — job: ${imputeJobId}`,
+                                `Target: ${summary.target_column ?? target_column} | aggregation: ${summary.aggregation ?? impute_aggregation} | only_missing: ${summary.only_missing ?? only_missing}`,
+                                `Rows: ${summary.n_rows ?? "?"} | imputed rows (source=imputed): ${summary.n_imputed ?? "?"} | insufficient_data: ${summary.n_insufficient ?? "?"}`,
+                                `Mean patch nodes: ${summary.mean_patch_nodes !== undefined ? Number(summary.mean_patch_nodes).toFixed(2) : "N/A"} (BMU + neighbors; hex interior often ~7).`,
+                                urls["imputed.csv"] ? `Download imputed.csv: ${urls["imputed.csv"]}` : "Use results(action=get, download) for URLs.",
+                                "",
+                                "Map-local estimates only — not a substitute for held-out validation.",
+                            ].join("\n") }] };
+            }
+            if (poll.status === "failed")
+                return { content: [{ type: "text", text: `inference(impute_column) job ${imputeJobId} failed: ${poll.error ?? "unknown error"}` }] };
+            return { content: [{ type: "text", text: `inference(impute_column) job ${imputeJobId} submitted. Poll with jobs(action=status, job_id="${imputeJobId}").` }] };
+        }
         if (action === "compare") {
             if (!dataset_id)
                 throw new Error("inference(compare) requires dataset_id (dataset B)");

package/dist/tools/jobs.js

@@ -5,7 +5,7 @@ export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs.
 | Action | Use when |
 |--------|----------|
 | status | Polling after any async job submission — call every 10–15s |
-| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters. Response includes job_type (train_map, report, recolor, project, transition_flow, compare, predict, reduce_spectral) to filter or display. |
+| list | Finding job IDs, checking what is pending/completed, reviewing hyperparameters. Response includes job_type (train_map, report, recolor, project, transition_flow, compare, predict, impute_column, annotated_dataset, reduce_spectral) to filter or display. |
 | compare | Picking the best training run from a set of completed jobs |
 | train_map | Submitting a new map training job — returns job_id for polling |
 | train_siom_map | Submitting a self-interacting map training job — same map flow with SIOM coverage control |
@@ -251,8 +251,9 @@ export function registerJobsTool(server, description) {
             .optional()
             .describe("Optional run label (≤120 chars) for train_map / train_siom_map / train_floop_siom — appears in jobs(list) and the jobs(compare) table; sanitized server-side. Useful for sweeps (e.g. label=\"sweep_periodic_true\")."),
         preset: z.enum(["quick", "standard", "refined", "high_res"]).optional(),
-        grid_x: z.number().int().optional(),
-        grid_y: z.number().int().optional(),
+        grid_x: z.number().int().optional()
+            .describe("Grid width. Omit grid_x AND grid_y (and preset) to auto-size the map (~5·√√n per side); the result reports hit_stats.active_node_fraction and a grid_suggestion when too many nodes are dead."),
+        grid_y: z.number().int().optional().describe("Grid height. See grid_x for auto-sizing."),
         epochs: z.preprocess((v) => {
             if (v === undefined || v === null)
                 return v;

package/dist/tools/results.js

@@ -29,7 +29,7 @@ action=export: Structured data exports. Use export_type= to choose what to expor
   - export_type=nodes: per-node hit count + feature stats. Profile clusters and operating modes.
 
 action=download: Save figures to disk. Use so user can open, share, or version files locally.
-  - folder: e.g. "." or "./results". Interpreted relative to the client's current working directory (or workspace). If job has a label, a named subfolder may be created.
+  - folder: e.g. "." or "./results". Interpreted relative to the client's current working directory (or workspace). Files are always written into a per-job subfolder (the job label, else the job_id) under this folder, so downloading several jobs into one folder never overwrites the shared filenames every job emits (e.g. summary.json).
   - figures: "all" (default) or array of filenames.
   - include_json: also save summary.json.
 
@@ -64,7 +64,7 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
         folder: z
             .string()
             .optional()
-            .describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to the client's current working directory (or workspace)."),
+            .describe("action=download: directory path to save files (e.g. '.' or './results'). Relative to the client's current working directory (or workspace). Files land in a per-job subfolder (job label or job_id) under this path."),
         colormap: z
             .string()
             .optional()
@@ -202,17 +202,14 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 }
             }
             else if (jobType === "enrich_dataset") {
-                // Historical job kind: pre-merge `enrich_dataset` worker output. New jobs
-                // never produce this — they use predict with output_style="annotated"
-                // (job_type="predict"). Kept as a read-only display path so old completed
-                // jobs remain reviewable.
+                // Older exports: summary.job_type from stored results (read-only display).
                 const files = summary.files ?? [];
+                const csvArtifact = files.find((f) => typeof f === "string" && f.endsWith(".csv")) ?? "artifact.csv";
                 content.push({ type: "text", text: [
-                        `Annotated Dataset (legacy enrich_dataset job) — ${resultsHeader}`,
+                        `Annotated dataset (older export) — ${resultsHeader}`,
                         `Parent map job: ${summary.parent_job_id ?? "N/A"} | Rows: ${summary.n_rows ?? summary.n_samples ?? 0}`,
                         `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
-                        `Use results(action=download, job_id="${job_id}") to save enriched.csv.`,
-                        `(For new jobs, use inference(action=predict, output="annotated").)`,
+                        `Use results(action=download, job_id="${job_id}") to save ${csvArtifact}.`,
                     ].join("\n") });
             }
             else if (jobType === "predict") {
@@ -227,7 +224,7 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 const metricsLine = (regime !== "training" && !isAnnotated)
                     ? `Mean QE: ${summary.mean_qe !== undefined ? Number(summary.mean_qe).toFixed(4) : "N/A"} | Max QE: ${summary.max_qe !== undefined ? Number(summary.max_qe).toFixed(4) : "N/A"} | qe_p95: ${summary.qe_p95 !== undefined ? Number(summary.qe_p95).toFixed(4) : "N/A"}`
                     : "";
-                const downloadName = isAnnotated ? "enriched.csv" : "predictions.csv";
+                const downloadName = isAnnotated ? "annotated.csv" : "predictions.csv";
                 content.push({ type: "text", text: [
                         `${headerLabel} — ${resultsHeader}`,
                         `Parent map job: ${summary.parent_job_id ?? "N/A"} | Regime: ${regime} | Style: ${outputStyle}`,
@@ -238,6 +235,18 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                         trainingCaveat,
                     ].filter(Boolean).join("\n") });
             }
+            else if (jobType === "impute_column") {
+                const files = summary.files ?? [];
+                content.push({ type: "text", text: [
+                        `Impute column — ${resultsHeader}`,
+                        `Parent map job: ${summary.parent_job_id ?? "N/A"} | Target: ${summary.target_column ?? "?"} | Rows: ${summary.n_rows ?? "?"}`,
+                        `Aggregation: ${summary.aggregation ?? "?"} | only_missing: ${summary.only_missing ?? "?"} | imputed: ${summary.n_imputed ?? "?"} | insufficient: ${summary.n_insufficient ?? "?"}`,
+                        `Mean patch nodes: ${summary.mean_patch_nodes !== undefined ? Number(summary.mean_patch_nodes).toFixed(2) : "N/A"}`,
+                        `Output: ${files.filter((f) => f !== "summary.json").join(", ")}`,
+                        `Use results(action=download, job_id="${job_id}") to save imputed.csv.`,
+                        "Map-local pool estimates — not held-out validated predictions.",
+                    ].join("\n") });
+            }
             else if (jobType === "reduce_spectral") {
                 const method = String(summary.method ?? "?");
                 const sourceCols = summary.source_columns ?? [];
@@ -554,7 +563,7 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
             const jobLabel = data.label != null && data.label !== "" ? String(data.label) : null;
             const files = summary.files ?? [];
             const jobType = summary.job_type ?? "train_som";
-            const needsAllFiles = ["enrich_dataset", "predict", "compare_datasets"].includes(jobType);
+            const needsAllFiles = ["enrich_dataset", "predict", "impute_column", "compare_datasets"].includes(jobType);
             const isImage = (f) => f.endsWith(".png") || f.endsWith(".svg") || f.endsWith(".pdf");
             let toDownload;
             if (figures === "all" || figures === "images" || figures === undefined) {
@@ -569,9 +578,11 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 toDownload = files.filter(isImage);
             }
             let resolvedDir = sandboxPath(folder, await getWorkspaceRootAsync(server));
-            if (jobLabel && (folder === "." || folder === "./results" || folder === "results")) {
-                resolvedDir = path.join(resolvedDir, jobLabel);
-            }
+            // Always namespace each job's files into its own subfolder so that
+            // downloading multiple jobs (or job types) into the same folder never
+            // overwrites the shared filenames every job emits (e.g. summary.json).
+            const jobSubfolder = (jobLabel ?? job_id).replace(/[^a-zA-Z0-9_.-]/g, "_");
+            resolvedDir = path.join(resolvedDir, jobSubfolder);
             if (jobType === "render_variant" && summary.colormap) {
                 const colormapDir = String(summary.colormap).replace(/[^a-zA-Z0-9_-]/g, "_");
                 resolvedDir = path.join(resolvedDir, colormapDir);
@@ -586,7 +597,8 @@ NOT FOR: Jobs that haven't completed. Use jobs(action=status) to check first.`,
                 }
                 catch { /* skip missing files */ }
             }
-            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${folder}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
+            const savedDir = path.join(folder, jobSubfolder);
+            return { content: [{ type: "text", text: saved.length > 0 ? `Saved ${saved.length} file(s) to ${savedDir}: ${saved.join(", ")}` : `No files saved. Check job_id and that the job is completed.` }] };
         }
         if (action === "recolor") {
             if (!colormap)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barivia/barsom-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "barSOM MCP proxy — connect any MCP client to the barSOM cloud API for Self-Organizing Map analytics",
   "keywords": [
     "mcp",