@barivia/barsom-mcp 0.22.4 → 0.23.0

package/dist/audit.js

@@ -110,10 +110,12 @@ function stripAuditMeta(result) {
 function errorCodeFrom(err) {
     if (err && typeof err === "object") {
         const e = err;
+        if (e.errorCode)
+            return e.errorCode;
         if (e.httpStatus !== undefined)
             return `http_${e.httpStatus}`;
         const m = e.message ?? "";
-        const codeMatch = m.match(/error_code:\s*(\w+)/);
+        const codeMatch = m.match(/error_code[=:]\s*(\w+)/);
         if (codeMatch)
             return codeMatch[1];
     }

package/dist/deferred_feedback.js

@@ -0,0 +1,88 @@
+/**
+ * Local offline queue for send_feedback when the API or object storage is down.
+ * Persists under ~/.barivia/deferred-feedback (or BARIVIA_FEEDBACK_QUEUE_DIR).
+ * Proxies flush the queue on the next successful feedback submission.
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+export function deferredFeedbackQueueDir() {
+    const override = process.env.BARIVIA_FEEDBACK_QUEUE_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(os.homedir(), ".barivia", "deferred-feedback");
+}
+async function ensureQueueDir() {
+    const dir = deferredFeedbackQueueDir();
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+function entryPath(dir, id) {
+    return path.join(dir, `${id}.json`);
+}
+export async function enqueueDeferredFeedback(product, body, lastError) {
+    const dir = await ensureQueueDir();
+    const id = randomUUID();
+    const entry = {
+        id,
+        product,
+        created_at: new Date().toISOString(),
+        body,
+        ...(lastError ? { last_error: lastError } : {}),
+    };
+    const filePath = entryPath(dir, id);
+    await fs.writeFile(filePath, JSON.stringify(entry, null, 2), "utf8");
+    return { id, path: filePath };
+}
+export async function listDeferredFeedback(product) {
+    const dir = deferredFeedbackQueueDir();
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const out = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(dir, name), "utf8");
+            const entry = JSON.parse(raw);
+            if (product && entry.product !== product)
+                continue;
+            out.push(entry);
+        }
+        catch {
+            /* skip corrupt */
+        }
+    }
+    out.sort((a, b) => a.created_at.localeCompare(b.created_at));
+    return out;
+}
+/**
+ * Attempt to submit each queued entry via `submit`. Successful entries are deleted.
+ * Failures leave the file in place for a later retry.
+ */
+export async function flushDeferredFeedback(product, submit) {
+    const entries = await listDeferredFeedback(product);
+    let flushed = 0;
+    const errors = [];
+    const dir = deferredFeedbackQueueDir();
+    for (const entry of entries) {
+        try {
+            await submit(entry.body);
+            await fs.unlink(entryPath(dir, entry.id)).catch(() => undefined);
+            flushed += 1;
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+        }
+    }
+    const remaining = (await listDeferredFeedback(product)).length;
+    return { flushed, remaining, errors };
+}

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 s,RESOURCE_MIME_TYPE as n}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 u,setClientSupportsMcpApps as d,CLIENT_VERSION as m}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as g}from"./tools/train.js";import{registerJobsTool as h,JOBS_DESCRIPTION_BASE as _}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 v}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as x}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as k}from"./tools/training_guidance.js";import{registerFeedbackTool as P}from"./tools/feedback.js";import{registerTrainingMonitorTool as A,TRAINING_MONITOR_URI as I}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as C}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 M=new e({name:"analytics-engine",version:m,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` | 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 (default=combined only; figures="none" for metrics-only sweeps; figures="all" or results_explorer/download for every plot), 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, history, add_funds |\n| Bootstrap | `guide_barsom_workflow`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `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- **Do not auto-subset:** Never call `datasets(subset)` or `sample_n` unless the user explicitly asks for a filter, slice, or random sample. Train and analyze on the uploaded `dataset_id` at full row count — GPU staging/prepare handles hundreds of thousands of rows quickly; silent downsampling hides real prepare/train behavior and wastes scale demos. Use small named fixtures (e.g. sample.csv, periodic_load) only when the user or runbook names them.\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. 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- **Large results / MCP timeouts:** For sweeps, `jobs(compare)`, or metrics-only reads use `results(action=get, figures="none")`. Default `get` inlines combined only. For every plot use `results_explorer` or `results(action=download)`, not `figures="all"` in chat unless the user wants all images inline.\n\n## UI delivery (heterogeneous MCP clients)\n\nHosts differ (Cursor, Claude Desktop, CLI agents): some embed MCP App panels; others list `ui://` but never mount them (expected on some Cursor builds); others are text-only. Tool results **always lead with a standalone localhost URL** — that is the intended fallback, not a broken App.\n\n| Tier | When | Agent should |\n|------|------|--------------|\n| **embedded** | Client advertises MCP Apps | Let the panel render **and** surface the standalone localhost URL from tool output / `ui_delivery.urls` (hosts often list Apps but do not mount). |\n| **localhost** | No MCP Apps; viz server running | Post the markdown link from tool output to the user (never broken workspace paths). Re-post after job completes if needed. |\n| **inline_image** | No Apps / override `inline` | Summarize metrics; inline raster (combined.png, learning curve) is attached automatically — show it in the reply. |\n| **text_only** | Viz server down | Use `jobs(status)` + `results(get)`; no panel or localhost link. |\n\nEvery `training_monitor` / `results_explorer` response includes a structured `ui_delivery` block (`delivery`, `urls`, `hint_for_agent`). Follow `hint_for_agent` without user prompting. Standalone viz pages cross-link monitor ↔ results for the same `job_id`.\n\n**Env overrides:** `BARIVIA_UI_DELIVERY=auto|apps|localhost|inline` (default `auto`). `BARIVIA_VIZ_PORT` pins the localhost viz port across proxy restarts. **Diagnostics:** `account(action=status)` reports detected MCP Apps support, viz port, and active tier.'});s(M,w,w,{mimeType:n},async()=>{const e=await c("results-explorer");return{contents:[{uri:w,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),s(M,I,I,{mimeType:n},async()=>{const e=await c("training-monitor");return{contents:[{uri:I,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),x(M),y(M),A(M),f(M),g(M),h(M,_),b(M),v(M),j(M),k(M),P(M),M.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 + resolved normalization/params) — review, then submit with `train`.","","**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 auto-subset — never call `datasets(subset)` / `sample_n` unless the user explicitly asks; train on the full uploaded `dataset_id`. 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")}}]})),M.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. Review, then submit with train.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{const t=await C(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const T=new t;(async function(){try{const e=await a(l,p,c);u(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=M.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=r(t);d(!!o?.mimeTypes?.includes(n))},await M.connect(T)})().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 s,registerAppResource as r,RESOURCE_MIME_TYPE as n}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 u,setClientSupportsMcpApps as d,CLIENT_VERSION as m}from"./shared.js";import{registerDatasetsTool as f}from"./tools/datasets.js";import{registerTrainTool as h}from"./tools/train.js";import{registerJobsTool as g,JOBS_DESCRIPTION_BASE as b}from"./tools/jobs.js";import{registerResultsTool as _}from"./tools/results.js";import{registerExploreMapTool as y,RESULTS_EXPLORER_URI as w}from"./tools/explore_map.js";import{registerAccountTool as v}from"./tools/account.js";import{registerInferenceTool as j}from"./tools/inference.js";import{registerGuideBarsomTool as k}from"./tools/guide_barsom.js";import{registerTrainingGuidanceTool as x}from"./tools/training_guidance.js";import{registerFeedbackTool as P}from"./tools/feedback.js";import{registerTrainingMonitorTool as A,TRAINING_MONITOR_URI as I}from"./tools/training_monitor.js";import{resolvePrepareTrainingPrompt as C}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 T=new e({name:"analytics-engine",version:m,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` | map, siom_map, impute (sparse → map + dense imputed.csv), floop_siom (entitled). Async, returns job_id. Submit only |\n| Lifecycle | `jobs` | status, list (slim + limit/cursor/status/job_type/has_results), update (label/description/tags), compare (**training runs**), cancel, delete. No training/scoring here |\n| Artifacts | `results` | get (default=combined only; figures="none" for metrics-only sweeps; figures="all" or results_explorer/download for every plot), export, download, recolor (async). Read/render completed jobs. Results catalog = `jobs(list, has_results=true)` |\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, history, **inventory** (markdown datasets+jobs overview), add_funds, **health** (API liveness via GET /health — no R2) |\n| Bootstrap | `guide_barsom_workflow`, `train`, `training_guidance`, `prepare_training` prompt | orientation, submit map/siom/impute/floop, parameter hints, narrative checklist (API/tier-scoped) |\n| Explore (UI) | `results_explorer`, `training_monitor` | richer UX over the same API; `jobs(status)`+`results(get)` still suffice headless |\n| Other | `send_feedback` | only after user agrees; queues locally if API/storage is down |\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## Org inventory recipe\n\nTo rebuild a durable markdown overview of an org (datasets + jobs):\n1. `account(action=inventory)` — preferred one-shot (datasets name/id/rows/cols/description/tags + slim recent jobs).\n2. Or compose: `datasets(list)` + `jobs(action=list, limit=50)` (page with `cursor` / filter with `status` / `job_type` / `has_results=true` for a results catalog).\n3. Set `description` + `tags` on `datasets(upload|update)` and `train(...)` / `jobs(update)` so duplicates stay navigable.\n\n## API briefly unavailable (pause, do not crash)\nIf tools return `api_unreachable` / gateway HTML / slim `error_code` lines: summarize in **one calm sentence** — never paste Cloudflare HTML. The proxy already burst-retried (**3** tries, ~**2s** apart); honor `retry_after_sec` (~**30**) before another round. Use `account(action=health)` (no R2). Local downloads and prior results stay usable; `send_feedback` queues under `~/.barivia/deferred-feedback` and flushes when the API returns. Do not start large uploads/trains until `account(status)` or health looks healthy again.\n\n## Constraints\n\n- **Do not auto-subset:** Never call `datasets(subset)` or `sample_n` unless the user explicitly asks for a filter, slice, or random sample. Train and analyze on the uploaded `dataset_id` at full row count — GPU staging/prepare handles hundreds of thousands of rows quickly; silent downsampling hides real prepare/train behavior and wastes scale demos. Use small named fixtures (e.g. sample.csv, periodic_load) only when the user or runbook names them.\n- Prep ladder: `prepare_training` prompt = narrative checklist; `training_guidance` = structured hints (presets, resolved normalization/transforms, grid/epochs). Review these, then submit with `train`. 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- **Large results / MCP timeouts:** For sweeps, `jobs(compare)`, or metrics-only reads use `results(action=get, figures="none")`. Default `get` inlines combined only. For every plot use `results_explorer` or `results(action=download)`, not `figures="all"` in chat unless the user wants all images inline.\n\n## UI delivery (heterogeneous MCP clients)\n\nHosts differ (Cursor, Claude Desktop, CLI agents): some embed MCP App panels; others list `ui://` but never mount them (expected on some Cursor builds); others are text-only. Tool results **always lead with a standalone localhost URL** — that is the intended fallback, not a broken App.\n\n| Tier | When | Agent should |\n|------|------|--------------|\n| **embedded** | Client advertises MCP Apps | Let the panel render **and** surface the standalone localhost URL from tool output / `ui_delivery.urls` (hosts often list Apps but do not mount). |\n| **localhost** | No MCP Apps; viz server running | Post the markdown link from tool output to the user (never broken workspace paths). Re-post after job completes if needed. |\n| **inline_image** | No Apps / override `inline` | Summarize metrics; inline raster (combined.png, learning curve) is attached automatically — show it in the reply. |\n| **text_only** | Viz server down | Use `jobs(status)` + `results(get)`; no panel or localhost link. |\n\nEvery `training_monitor` / `results_explorer` response includes a structured `ui_delivery` block (`delivery`, `urls`, `hint_for_agent`). Follow `hint_for_agent` without user prompting. Standalone viz pages cross-link monitor ↔ results for the same `job_id`.\n\n**Env overrides:** `BARIVIA_UI_DELIVERY=auto|apps|localhost|inline` (default `auto`). `BARIVIA_VIZ_PORT` pins the localhost viz port across proxy restarts. **Diagnostics:** `account(action=status)` reports detected MCP Apps support, viz port, and active tier.'});r(T,w,w,{mimeType:n},async()=>{const e=await c("results-explorer");return{contents:[{uri:w,mimeType:n,text:e??"<html><body>Results Explorer view not built yet. Run: npm run build:views</body></html>"}]}}),r(T,I,I,{mimeType:n},async()=>{const e=await c("training-monitor");return{contents:[{uri:I,mimeType:n,text:e??"<html><body>Training Monitor view not built yet.</body></html>"}]}}),k(T),y(T),A(T),f(T),h(T),g(T,b),_(T),v(T),j(T),x(T),P(T),T.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 + resolved normalization/params) — review, then submit with `train`.","","**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 auto-subset — never call `datasets(subset)` / `sample_n` unless the user explicitly asks; train on the full uploaded `dataset_id`. 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")}}]})),T.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. Review, then submit with train.",{dataset_id:o.string().describe("Dataset ID to prepare for training")},async({dataset_id:e})=>{const t=await C(e);return{messages:[{role:"user",content:{type:"text",text:(t.used_fallback?`[offline fallback ${t.fallback_version}]\n\n`:"")+t.text}}]}});const M=new t;(async function(){try{const e=await a(l,p,c);u(e)}catch(e){process.env.BARIVIA_VIZ_PORT&&console.error("Barivia viz server failed to start:",e)}const e=T.server;e.oninitialized=()=>{const t=e.getClientCapabilities(),o=s(t);d(!!o?.mimeTypes?.includes(n))},await T.connect(M)})().catch(console.error);

package/dist/inventory_format.js

@@ -0,0 +1,69 @@
+/** Shared markdown inventory formatting for account(inventory) / jobs list. */
+export function formatTags(tags) {
+    if (!Array.isArray(tags) || tags.length === 0)
+        return "";
+    return tags.map((t) => String(t)).filter(Boolean).join(", ");
+}
+export function formatDatasetInventoryLine(ds) {
+    const id = String(ds.id ?? "");
+    const name = String(ds.name ?? "");
+    const rows = ds.rows != null ? Number(ds.rows) : "?";
+    const cols = ds.cols != null ? Number(ds.cols) : "?";
+    const st = ds.status != null ? String(ds.status) : "ready";
+    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+    const desc = ds.description != null && String(ds.description).trim() !== ""
+        ? ` — ${String(ds.description).trim()}`
+        : "";
+    const tags = formatTags(ds.tags);
+    const tagsBit = tags ? ` [${tags}]` : "";
+    return `${name} (${id}) — ${rows}×${cols}${statusBit}${tagsBit}${desc}`;
+}
+export function formatJobInventoryLine(job) {
+    const id = String(job.id ?? "");
+    const st = String(job.status ?? "");
+    const label = job.label != null && job.label !== "" ? String(job.label) : null;
+    const jt = job.job_type != null ? String(job.job_type) : "?";
+    const ds = job.dataset_id != null ? String(job.dataset_id) : "";
+    const created = job.created_at != null ? String(job.created_at) : "";
+    const result = job.result_ref != null && String(job.result_ref) !== "" ? "yes" : "no";
+    const tags = formatTags(job.tags);
+    const tagsBit = tags ? ` [${tags}]` : "";
+    const desc = job.description != null && String(job.description).trim() !== ""
+        ? ` — ${String(job.description).trim()}`
+        : "";
+    const head = label ? `${label} (id: ${id})` : `id: ${id}`;
+    return `${head} — ${st} | type=${jt} | dataset=${ds} | created=${created} | result=${result}${tagsBit}${desc}`;
+}
+export function extractJobsList(data) {
+    if (Array.isArray(data)) {
+        return { jobs: data, next_cursor: null };
+    }
+    if (data && typeof data === "object") {
+        const obj = data;
+        const jobs = Array.isArray(obj.jobs) ? obj.jobs : [];
+        const next = obj.next_cursor != null && String(obj.next_cursor) !== ""
+            ? String(obj.next_cursor)
+            : null;
+        return { jobs, next_cursor: next };
+    }
+    return { jobs: [], next_cursor: null };
+}
+export function buildJobsListQuery(opts) {
+    const qs = new URLSearchParams();
+    if (opts.dataset_id)
+        qs.set("dataset_id", opts.dataset_id);
+    if (opts.status)
+        qs.set("status", opts.status);
+    if (opts.job_type)
+        qs.set("job_type", opts.job_type);
+    if (opts.has_results)
+        qs.set("has_results", "true");
+    if (opts.limit != null)
+        qs.set("limit", String(opts.limit));
+    if (opts.cursor)
+        qs.set("cursor", opts.cursor);
+    if (opts.fields)
+        qs.set("fields", opts.fields);
+    const s = qs.toString();
+    return s ? `/v1/jobs?${s}` : "/v1/jobs";
+}

package/dist/shared.js

@@ -20,12 +20,16 @@ export const API_URL = process.env.BARIVIA_API_URL ??
     "https://api.barivia.se";
 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 ?? "60000", 10);
-export const MAX_RETRIES = 2;
-export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "1000", 10);
+/** Retries after the first attempt; default 2 → 3 total tries. Override with BARIVIA_MAX_RETRIES. */
+export const MAX_RETRIES = parseInt(process.env.BARIVIA_MAX_RETRIES ?? "2", 10);
+/** Delay between burst retries (ms). Default 2000 → ~2s between each of the 3 attempts. */
+export const RETRY_BASE_MS = parseInt(process.env.BARIVIA_RETRY_BASE_MS ?? "2000", 10);
 export const RETRYABLE_STATUS = new Set([502, 503, 504]);
-/** Exponential backoff for transient API retries (attempt 0 → base, 1 → 2×, …). */
-export function retryDelayMs(attempt) {
-    return RETRY_BASE_MS * 2 ** attempt;
+/** Cool-down hint after the burst is exhausted — agents should wait before another round. */
+export const UNAVAILABLE_RETRY_AFTER_SEC = 30;
+/** Fixed delay between burst retries (not exponential). */
+export function retryDelayMs(_attempt) {
+    return RETRY_BASE_MS;
 }
 function newRequestId() {
     return randomUUID();
@@ -35,7 +39,7 @@ function newRequestId() {
  * 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.22.4";
+export const CLIENT_VERSION = "0.23.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). */
@@ -374,52 +378,237 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
             `"C:\\\\Users\\\\you\\\\data.csv") or a file:// URI. For relative paths, set BARIVIA_WORKSPACE_ROOT in your MCP config.`);
     }
 }
-/** User-visible API error line (includes request id for support). Exported for tests. */
-export function formatApiErrorMessage(status, bodyText, requestId) {
+function looksLikeHtml(bodyText) {
+    const t = bodyText.trim().slice(0, 200).toLowerCase();
+    return t.startsWith("<!doctype") || t.startsWith("<html") || /<\s*html[\s>]/.test(t);
+}
+function isStorageErrorCode(code) {
+    if (!code)
+        return false;
+    const c = code.toLowerCase();
+    return c === "storage_upload_failed" || (c.includes("storage") && !c.includes("unavailable"));
+}
+/**
+ * Classify an HTTP API failure into a compact structured error.
+ * Gateway HTML 502/503 bodies are never echoed — they become api_unreachable.
+ */
+export function classifyApiError(status, bodyText, requestId) {
     let parsed = null;
-    try {
-        const j = JSON.parse(bodyText);
-        if (j && typeof j === "object")
-            parsed = j;
-    }
-    catch {
-        /* ignore */
+    const html = looksLikeHtml(bodyText);
+    if (!html && bodyText.trim()) {
+        try {
+            const j = JSON.parse(bodyText);
+            if (j && typeof j === "object")
+                parsed = j;
+        }
+        catch {
+            /* non-JSON */
+        }
     }
-    const detail = (parsed?.error != null && String(parsed.error)) ||
-        (bodyText.trim() ? bodyText.trim() : `HTTP ${status}`);
-    const code = parsed?.error_code != null ? ` (error_code: ${parsed.error_code})` : "";
+    const apiCode = parsed?.error_code != null ? String(parsed.error_code) : "";
+    const apiMsg = parsed?.error != null && String(parsed.error).trim()
+        ? String(parsed.error).trim()
+        : "";
+    let cause = "server";
+    let error_code = apiCode || `http_${status}`;
+    let message = apiMsg || `HTTP ${status}`;
+    let hint = "";
+    let retryable = status === 502 || status === 503 || status === 504;
     const accountHint = ` Check your email or manage your key at ${PUBLIC_DASHBOARD_URL} if needed.`;
-    const hint = status === 400
-        ? " Check parameter types and required fields."
-        : status === 401
-            ? ` Check BARIVIA_API_KEY in your MCP config.${accountHint}`
-            : status === 403
-                ? ` Access denied for this operation (plan or permissions).${accountHint}`
-                : status === 402
-                    ? ` Credits or subscription may be insufficient — upgrade at ${PUBLIC_DASHBOARD_URL}.`
-                    : status === 404
-                        ? " The resource may not exist or may have been deleted."
-                        : status === 409
-                            ? " The job may not be in the expected state."
-                            : status === 429
-                                ? " Plan limit (e.g. dataset cap) or rate limit — read the error above; delete unused datasets or wait and retry."
-                                : status === 502
-                                    ? " Object storage (R2/S3) error from API — retry later."
-                                    : status === 503
-                                        ? parsed?.error_code === "system_info_unavailable"
-                                            ? " System info (plan/queue) temporarily unavailable — retry later."
-                                            : " API or database temporarily unavailable — retry later."
-                                        : status >= 500
-                                            ? " Server error — retry later."
-                                            : "";
-    const rid = ` (request id: ${requestId} — include if contacting support)`;
-    return `${detail}${code}${hint}${rid}`;
+    if (status === 400) {
+        cause = "client";
+        hint = "Check parameter types and required fields.";
+        retryable = false;
+    }
+    else if (status === 401) {
+        cause = "auth";
+        error_code = apiCode || "unauthorized";
+        hint = `Check BARIVIA_API_KEY in your MCP config.${accountHint}`;
+        retryable = false;
+    }
+    else if (status === 403) {
+        cause = "auth";
+        error_code = apiCode || "forbidden";
+        hint = `Access denied for this operation (plan or permissions).${accountHint}`;
+        retryable = false;
+    }
+    else if (status === 402) {
+        cause = "client";
+        hint = `Credits or subscription may be insufficient — upgrade at ${PUBLIC_DASHBOARD_URL}.`;
+        retryable = false;
+    }
+    else if (status === 404) {
+        cause = "client";
+        hint = "The resource may not exist or may have been deleted.";
+        retryable = false;
+    }
+    else if (status === 409) {
+        cause = "client";
+        hint = "The job may not be in the expected state.";
+        retryable = false;
+    }
+    else if (status === 429) {
+        cause = "rate_limit";
+        hint = "Plan limit (e.g. dataset cap) or rate limit — delete unused datasets or wait and retry.";
+        retryable = true;
+    }
+    else if (status === 502 || status === 503 || status === 504) {
+        if (isStorageErrorCode(apiCode) || /object storage|r2\/s3|storage upload/i.test(apiMsg)) {
+            cause = "storage";
+            error_code = apiCode || "storage_upload_failed";
+            message = apiMsg || "Object storage (R2/S3) error from API.";
+            hint = "Retry later; feedback may still succeed via DB when storage is degraded.";
+        }
+        else if (html || !parsed) {
+            cause = "api_unreachable";
+            error_code = apiCode || "api_unreachable";
+            message = "API temporarily unavailable (gateway/tunnel returned a non-JSON error).";
+            hint =
+                `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+                    "Use account(action=health) — /health does not depend on R2. Pause — do not paste HTML.";
+        }
+        else if (apiCode === "system_info_unavailable") {
+            cause = "server";
+            message = apiMsg || "System info (plan/queue) temporarily unavailable.";
+            hint = `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        }
+        else if (apiCode === "feedback_unavailable" || apiCode === "database_error") {
+            cause = "server";
+            error_code = apiCode;
+            message = apiMsg || "API or database temporarily unavailable.";
+            hint =
+                `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s; send_feedback queues locally if the API stays down.`;
+        }
+        else {
+            cause = "server";
+            message = apiMsg || `HTTP ${status}`;
+            hint = `API or database temporarily unavailable — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        }
+    }
+    else if (status >= 500) {
+        cause = "server";
+        hint = `Server error — wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry.`;
+        retryable = true;
+    }
+    else if (!apiMsg && html) {
+        cause = "api_unreachable";
+        error_code = "api_unreachable";
+        message = `HTTP ${status} (non-JSON gateway body)`;
+        hint = `Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. Do not paste HTML.`;
+        retryable = status >= 500;
+    }
+    const retry_after_sec = retryable ? UNAVAILABLE_RETRY_AFTER_SEC : undefined;
+    return {
+        status,
+        error_code,
+        message,
+        hint,
+        request_id: requestId,
+        retryable,
+        cause,
+        ...(retry_after_sec !== undefined ? { retry_after_sec } : {}),
+    };
+}
+/** User-visible API error line (slim; includes request id). Exported for tests. */
+export function formatApiErrorMessage(status, bodyText, requestId) {
+    const c = classifyApiError(status, bodyText, requestId);
+    const parts = [
+        c.message,
+        `error_code=${c.error_code}`,
+        `cause=${c.cause}`,
+        c.retry_after_sec != null ? `retry_after_sec=${c.retry_after_sec}` : "",
+        c.hint,
+        `request_id=${c.request_id}`,
+    ].filter((p) => p && String(p).trim());
+    return parts.join(" | ");
 }
 function throwApiError(status, bodyText, requestId) {
+    const classified = classifyApiError(status, bodyText, requestId);
     const err = new Error(formatApiErrorMessage(status, bodyText, requestId));
     err.httpStatus = status;
+    err.errorCode = classified.error_code;
+    err.requestId = requestId;
+    err.retryable = classified.retryable;
+    err.cause = classified.cause;
+    err.retryAfterSec = classified.retry_after_sec;
+    err.classified = classified;
     throw err;
 }
+/** Final network failure after the burst — same calm shape as gateway HTML 502. */
+function throwNetworkUnreachable(requestId, err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    const classified = {
+        status: 0,
+        error_code: "api_unreachable",
+        message: "API temporarily unavailable (network error).",
+        hint: `Proxy already tried 3 times (~2s apart). Wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s, then retry. ` +
+            `Detail: ${detail.slice(0, 120)}`,
+        request_id: requestId,
+        retryable: true,
+        cause: "api_unreachable",
+        retry_after_sec: UNAVAILABLE_RETRY_AFTER_SEC,
+    };
+    const msg = [
+        classified.message,
+        `error_code=${classified.error_code}`,
+        `cause=${classified.cause}`,
+        `retry_after_sec=${classified.retry_after_sec}`,
+        classified.hint,
+        `request_id=${classified.request_id}`,
+    ].join(" | ");
+    const out = new Error(msg);
+    out.httpStatus = 0;
+    out.errorCode = classified.error_code;
+    out.requestId = requestId;
+    out.retryable = true;
+    out.cause = "api_unreachable";
+    out.retryAfterSec = UNAVAILABLE_RETRY_AFTER_SEC;
+    out.classified = classified;
+    throw out;
+}
+/**
+ * Liveness (+ optional readiness) probe against the API origin.
+ * Uses GET /health which never touches R2 — safe during storage outages.
+ */
+export async function probeApiHealth() {
+    const base = { storage: "not_probed" };
+    try {
+        const live = await fetchWithTimeout(`${API_URL}/health`, { method: "GET" }, 8_000);
+        const liveText = await live.text();
+        if (!live.ok) {
+            return { ...base, liveness: "down", readiness: "unknown", detail: `health HTTP ${live.status}` };
+        }
+        let readiness = "unknown";
+        let db;
+        let redis;
+        try {
+            const ready = await fetchWithTimeout(`${API_URL}/ready`, { method: "GET" }, 8_000);
+            const readyText = await ready.text();
+            try {
+                const j = JSON.parse(readyText);
+                readiness = ready.ok && j.status === "ready" ? "ready" : "not_ready";
+                db = j.db;
+                redis = j.redis;
+            }
+            catch {
+                readiness = ready.ok ? "ready" : "not_ready";
+            }
+        }
+        catch {
+            readiness = "unknown";
+        }
+        void liveText;
+        return { ...base, liveness: "ok", readiness, db, redis };
+    }
+    catch (err) {
+        return {
+            ...base,
+            liveness: "down",
+            readiness: "unknown",
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 /**
  * @param requestTimeoutMs Optional per-request timeout (default `BARIVIA_FETCH_TIMEOUT_MS`).
  */
@@ -532,9 +721,13 @@ export async function apiCall(method, path, body, extraHeaders, requestTimeoutMs
                 !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS in your MCP env (e.g. 120000) for slow or large requests. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 /** Fetch raw bytes from the API (for image downloads). */
@@ -596,9 +789,13 @@ export async function apiRawCall(path, requestTimeoutMs) {
                 !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (e.g. 120000) for large images. (request id: ${requestId})`);
             }
+            if (err instanceof TypeError)
+                throwNetworkUnreachable(requestId, err);
             throw err;
         }
     }
+    if (lastError instanceof TypeError)
+        throwNetworkUnreachable(requestId, lastError);
     throw lastError;
 }
 // ---------------------------------------------------------------------------

package/dist/tools/account.js

@@ -1,27 +1,95 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, CLIENT_VERSION } from "../shared.js";
+import { apiCall, CLIENT_VERSION, probeApiHealth, structuredTextResult, UNAVAILABLE_RETRY_AFTER_SEC, } from "../shared.js";
 import { getMcpClientDiagnostics } from "../ui-delivery.js";
+import { listDeferredFeedback } from "../deferred_feedback.js";
+import { buildJobsListQuery, extractJobsList, formatDatasetInventoryLine, formatJobInventoryLine, } from "../inventory_format.js";
+function degradedStatusResult(opts) {
+    const retry_after_sec = UNAVAILABLE_RETRY_AFTER_SEC;
+    const payload = {
+        ok: false,
+        retry_after_sec,
+        api_reachable: false,
+        message: "Barivia is temporarily unavailable (we could not reach the API). " +
+            "Your local files and prior downloads are still fine. Try again in about 30 seconds.",
+        offline_ok: [
+            "already-downloaded results",
+            "local CSVs",
+            "draft notes / deferred feedback queue",
+        ],
+        needs_api: ["upload", "train", "feedback flush", "list/status", "other cloud tools"],
+        request_id: opts.requestId ?? null,
+        hint_for_host: "Barivia: reconnecting…",
+        detail: opts.detail ?? null,
+    };
+    const rid = opts.requestId
+        ? ` (request id: ${opts.requestId} — include if contacting support)`
+        : "";
+    const text = [
+        payload.message + rid,
+        `retry_after_sec=${retry_after_sec} | api_reachable=false`,
+        `AGENT: Calm banner ("${payload.hint_for_host}"); do not dump HTML. Proxy already burst-retried; wait ~${retry_after_sec}s before another round. Do not start large uploads/trains until ok.`,
+    ].join("\n");
+    return structuredTextResult(payload, text);
+}
 export function registerAccountTool(server) {
-    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, add funds.
+    registerAuditedTool(server, "account", `Manage your Barivia account — check plan/license info, view usage history, rebuild an org inventory, add funds, or probe API health.
 
 | Action | Use when |
 |--------|----------|
-| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance |
+| status | Before large jobs — see plan tier, GPU availability, queue depth, training time estimates, credit balance. When the API is down, returns calm \`{ok:false, retry_after_sec}\` instead of HTML. |
 | history | Viewing recent compute usage and credit spend |
+| inventory | Rebuild a durable markdown overview of datasets + recent jobs (agent-friendly org catalog) |
 | add_funds | Getting instructions to add credits |
+| health | Diagnose API reachability during outages — GET /health + /ready; does **not** probe R2/object storage |
 
 action=status: Returns plan tier, compute class (CPU/GPU), usage limits, live queue state, training time estimates, and credit balance.
   Use BEFORE large jobs to check GPU availability and estimate wait time.
+  When the API/gateway is down, returns structured \`{ok:false, retry_after_sec, …}\` — treat as a pause, not a crash.
+action=inventory: Lists datasets (name/id/rows/cols/description/tags) and slim recent jobs (label/id/status/job_type/dataset_id/created_at/result). Prefer this over hand-assembling datasets(list)+jobs(list). Page jobs with jobs(action=list, cursor=…).
+action=health: Lightweight liveness/readiness (no R2). Use when tools return api_unreachable or before retrying deferred send_feedback.
 Capacity is shared LOCAL/GKE worker pools — there is no per-key cloud burst lease.
 NOT FOR: Training itself — use train(action=map). This tool only manages the account.`, {
         action: z
-            .enum(["status", "history", "add_funds"])
-            .describe("status: plan/license/queue info; history: recent compute usage; add_funds: instructions"),
-        limit: z.number().optional().describe("action=history: number of records to return (default: 10)"),
+            .enum(["status", "history", "inventory", "add_funds", "health"])
+            .describe("status: plan/license/queue info; history: recent compute usage; inventory: datasets+jobs overview; add_funds: instructions; health: API liveness without R2"),
+        limit: z.number().optional().describe("action=history or inventory: number of job records to return (default: 10 history / 50 inventory)"),
     }, async ({ action, limit }) => {
+        if (action === "health") {
+            const health = await probeApiHealth();
+            const deferred = await listDeferredFeedback("barsom").catch(() => []);
+            const lines = [
+                `API liveness: ${health.liveness}`,
+                `API readiness: ${health.readiness}`,
+                health.db ? `DB: ${health.db}` : null,
+                health.redis ? `Redis: ${health.redis}` : null,
+                `Object storage (R2): ${health.storage} (intentionally not checked)`,
+                health.detail ? `Detail: ${health.detail}` : null,
+                `Deferred feedback drafts (barsom): ${deferred.length}`,
+                health.liveness === "down"
+                    ? `retry_after_sec=${UNAVAILABLE_RETRY_AFTER_SEC} (wait before another tool round)`
+                    : null,
+            ].filter(Boolean);
+            return structuredTextResult({
+                ...health,
+                deferred_feedback_pending: deferred.length,
+                ...(health.liveness === "down"
+                    ? { ok: false, retry_after_sec: UNAVAILABLE_RETRY_AFTER_SEC }
+                    : { ok: true }),
+            }, lines.join("\n"));
+        }
         if (action === "status") {
-            const data = (await apiCall("GET", "/v1/system/info"));
+            let data;
+            try {
+                data = (await apiCall("GET", "/v1/system/info"));
+            }
+            catch (err) {
+                const e = err;
+                return degradedStatusResult({
+                    requestId: e.requestId,
+                    detail: e.message,
+                });
+            }
             const plan = data.plan ?? {};
             const backend = data.backend ?? {};
             const status = data.status ?? {};
@@ -95,6 +163,42 @@ NOT FOR: Training itself — use train(action=map). This tool only manages the a
                 content: [{ type: "text", text: `Credit Balance: $${(data.credit_balance_cents / 100).toFixed(2)}\n\nRecent Usage:\n${history}` }]
             };
         }
+        if (action === "inventory") {
+            const jobLimit = limit && limit > 0 ? Math.min(Math.floor(limit), 100) : 50;
+            const [datasetsRaw, jobsRaw] = await Promise.all([
+                apiCall("GET", "/v1/datasets"),
+                apiCall("GET", buildJobsListQuery({ limit: jobLimit })),
+            ]);
+            const datasets = Array.isArray(datasetsRaw) ? datasetsRaw : [];
+            const { jobs, next_cursor } = extractJobsList(jobsRaw);
+            const lines = [
+                `# Org inventory`,
+                ``,
+                `## Datasets (${datasets.length})`,
+            ];
+            if (datasets.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const ds of datasets)
+                    lines.push(`- ${formatDatasetInventoryLine(ds)}`);
+            }
+            lines.push(``, `## Jobs (latest ${jobs.length}${next_cursor ? ", more available" : ""})`);
+            if (jobs.length === 0) {
+                lines.push("(none)");
+            }
+            else {
+                for (const job of jobs)
+                    lines.push(`- ${formatJobInventoryLine(job)}`);
+            }
+            if (next_cursor) {
+                lines.push(``);
+                lines.push(`More jobs: jobs(action=list, cursor="${next_cursor}", limit=${jobLimit})`);
+            }
+            lines.push(``);
+            lines.push(`Tips: set description/tags on datasets(upload|update) and train(...)/jobs(update). Filter jobs with status/job_type/has_results.`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
         if (action === "add_funds") {
             return {
                 content: [{ type: "text", text: `To add funds to your account, please visit the Barivia Billing Portal (integration pending) or ask your administrator to use the CLI tool:
@@ -102,7 +206,7 @@ bash scripts/billing/manage-credits.sh add <org_id> <amount_usd>` }]
             };
         }
         return {
-            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, add_funds.` }]
+            content: [{ type: "text", text: `Unknown action: ${action}. Valid: status, history, inventory, add_funds, health.` }]
         };
     });
 }

package/dist/tools/datasets.js

@@ -6,6 +6,7 @@ import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
 import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, structuredTextResult, pollUntilComplete, POLL_DERIVE_MAX_MS, POLL_ANALYZE_MAX_MS, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../job_status_format.js";
+import { formatDatasetInventoryLine, formatTags } from "../inventory_format.js";
 /**
  * Normalize a nullable string field from the API. Returns "" for absent values,
  * empty strings, and the literal SQL/serialization sentinels "missing"/"null"
@@ -137,8 +138,9 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~100 MB, pre
 | upload | You have a CSV or .csv.gz file to add — do this first |
 | preview | Before train(action=map) — always preview an unfamiliar dataset to spot cyclics, nulls, column types |
 | analyze | Pre-training column analysis: correlation matrix, periodicity ranking, column recommendations (train / drop / project later). Run after preview, before train_map. |
-| list | Finding dataset IDs for train_map, preview, or subset — see all available datasets |
-| get | Fetch one dataset by id — status, staging fields, ingest_error (use after upload or when staging is slow) |
+| list | Finding dataset IDs for train_map, preview, or subset — see all available datasets (includes description/tags) |
+| get | Fetch one dataset by id — status, staging fields, ingest_error, description/tags (use after upload or when staging is slow) |
+| update | Edit name / description / tags on an existing dataset (helps navigate duplicates) |
 | subset | ONLY when the user asks for row_range, filters, or sample_n — never auto-shrink before train/analyze |
 | add_expression | Add a computed column from an expression (dataset_id + name + expression). With project_onto_job=<training_job_id>, instead projects the computed expression onto that map as a component plane in one step (no column added). |
 | reduce_spectral | Collapse a long ordered numeric block (e.g. 1000-point spectrum, time series, sensor fingerprint) into a small per-row feature set so the SOM can train on signal-dense features. Methods: pca, log_sample, uniform_sample, stats. |
@@ -151,9 +153,12 @@ Step 1 (after upload): always datasets(action=preview) to verify column types an
 
 action=preview: Show columns, stats, sample rows, cyclic/datetime detections. ALWAYS preview before train(action=map) on an unfamiliar dataset.
 action=analyze: Pre-training analysis on numeric columns — Pearson correlation, autocorrelation periodicity scores, and column recommendations (train, consider_dropping, project_later, low_variance). Use to choose which columns to include in training and which to project onto the map after training.
-action=list: List all datasets belonging to the organisation with id, name, rows, cols, created_at (use created_at or id to distinguish datasets with the same name).
-action=get: Fetch one dataset by dataset_id — returns status, staged_prefix, staged_version, ingest_error, and stage_job_id when staging is pending.
+action=list: List all datasets belonging to the organisation with id, name, rows, cols, created_at, description, tags (use tags/description or id to distinguish datasets with the same name).
+action=get: Fetch one dataset by dataset_id — returns status, staged_prefix, staged_version, ingest_error, description/tags, and stage_job_id when staging is pending.
+action=update: PATCH name/description/tags on an existing dataset.
+action=upload: Optional description and tags help later inventory (also settable via update).
 DO NOT AUTO-SUBSET: Call action=subset only when the user explicitly requests a filter, slice, or random sample. Default path is upload → preview/analyze → train on the full dataset_id (GPU handles scale). Never downsample to "save time" or "be helpful".
+Org overview: account(action=inventory) for a markdown datasets+jobs catalog.
 
 action=subset: Create a new dataset from a subset of an existing one. Requires name and at least one of row_range, filters, or sample_n.
   - row_range: [start, end] 1-based inclusive (e.g. [1, 2000] for first 2000 rows)
@@ -175,9 +180,11 @@ BEST FOR: Tabular numeric data. CSV with header required.
 NOT FOR: Real-time data streams or binary files — upload a snapshot CSV instead.
 ESCALATION: If upload fails with column errors, open the file locally and verify the header row. If preview shows nulls in training columns: use train(action=impute) for sparse data, or clean/subset for train(action=map).`, {
         action: z
-            .enum(["upload", "preview", "analyze", "list", "get", "subset", "delete", "add_expression", "reduce_spectral"])
-            .describe("upload: add CSV or .csv.gz; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; get: fetch one dataset metadata (status/staging); subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression (or, with project_onto_job, project the expression onto a trained map as a component plane); reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
-        name: z.string().optional().describe("Dataset name (required for action=upload and subset)"),
+            .enum(["upload", "preview", "analyze", "list", "get", "update", "subset", "delete", "add_expression", "reduce_spectral"])
+            .describe("upload: add CSV or .csv.gz; preview: inspect columns/stats; analyze: pre-training correlation and periodicity; list: see all datasets; get: fetch one dataset metadata (status/staging); update: edit name/description/tags; subset: create filtered subset; delete: remove dataset; add_expression: add derived column from expression (or, with project_onto_job, project the expression onto a trained map as a component plane); reduce_spectral: collapse a long ordered numeric block (e.g. spectrum, time series) into a small per-row feature set via PCA / log_sample / uniform_sample / stats"),
+        name: z.string().optional().describe("Dataset name (required for action=upload and subset; optional for update)"),
+        description: z.string().optional().describe("Optional free-text description (upload/update). Pass \"\" on update to clear."),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation (upload/update). Pass [] on update to clear."),
         file_path: z.string().optional().describe("Path to local CSV or .csv.gz (PREFERRED): absolute path, file:// URI, or path relative to the workspace root. Token-efficient; server reads file. NOTE: relative paths resolve against the MCP workspace root — in Cursor/IDE clients that root is often the MCP install dir, not your project, so set BARIVIA_WORKSPACE_ROOT in the MCP config env (or just pass an absolute path) if a relative path is 'not accessible'. Use .csv.gz for large scientific tables."),
         csv_data: z.string().optional().describe("Inline CSV string for small pastes only (<10KB). Avoid for large files — use file_path instead to avoid token explosion."),
         dataset_id: z.string().optional().describe("Dataset ID (required for preview, get, subset, and delete)"),
@@ -266,7 +273,7 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             .int()
             .optional()
             .describe("action=subset: RNG seed for sample_n (default 42; same seed + dataset reproduces the same sample)."),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, columns_range, columns_except, k, sample_n, sample_seed }) => {
+    }, async ({ action, name, description, tags, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, expression, options, project_onto_job, aggregation, output_format, method, columns_block, columns_range, columns_except, k, sample_n, sample_seed }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("datasets(upload) requires name");
@@ -306,7 +313,12 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                     const idem = await streamFileSha256(resolved);
                     let init;
                     try {
-                        init = (await apiCall("POST", "/v1/datasets/upload-url", { name, size_bytes: stat.size }, { "Idempotency-Key": idem }));
+                        const uploadUrlBody = { name, size_bytes: stat.size };
+                        if (description !== undefined)
+                            uploadUrlBody.description = description;
+                        if (tags !== undefined)
+                            uploadUrlBody.tags = tags;
+                        init = (await apiCall("POST", "/v1/datasets/upload-url", uploadUrlBody, { "Idempotency-Key": idem }));
                     }
                     catch (e) {
                         const msg = e instanceof Error ? e.message : String(e);
@@ -344,12 +356,17 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 // Content-Encoding: gzip), never decoding them as UTF-8 text.
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
-                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
+                    const gzHeaders = {
                         "X-Dataset-Name": name,
                         "Content-Type": uploadContentType,
                         "Content-Encoding": "gzip",
                         "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(gzBytes).digest("hex"),
-                    }, UPLOAD_DATASET_TIMEOUT_MS));
+                    };
+                    if (description !== undefined)
+                        gzHeaders["X-Dataset-Description"] = description;
+                    if (tags !== undefined)
+                        gzHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
+                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, gzHeaders, UPLOAD_DATASET_TIMEOUT_MS));
                     const gid = data.id ?? data.dataset_id;
                     if (gid != null)
                         data.suggested_next_step = `${suggestDatasetPreview(String(gid))} to inspect columns before training.`;
@@ -373,6 +390,10 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
                 // the original dataset server-side instead of creating a duplicate.
                 "Idempotency-Key": createHash("sha256").update(`${name}\n`).update(body).digest("hex"),
             };
+            if (description !== undefined)
+                uploadHeaders["X-Dataset-Description"] = description;
+            if (tags !== undefined)
+                uploadHeaders["X-Dataset-Tags"] = JSON.stringify(tags);
             let uploadBody = body;
             if (Buffer.byteLength(body, "utf-8") > GZIP_THRESHOLD) {
                 uploadBody = gzipSync(Buffer.from(body, "utf-8"));
@@ -681,15 +702,9 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             const data = (await apiCall("GET", "/v1/datasets"));
             if (Array.isArray(data)) {
                 const lines = data.map((ds) => {
-                    const id = String(ds.id ?? "");
-                    const name = String(ds.name ?? "");
-                    const rows = ds.rows != null ? Number(ds.rows) : "?";
-                    const cols = ds.cols != null ? Number(ds.cols) : "?";
-                    const st = ds.status != null ? String(ds.status) : "ready";
-                    const statusBit = st !== "ready" ? ` | status=${st}` : "";
+                    const base = formatDatasetInventoryLine(ds);
                     const ingestErr = cleanNullable(ds.ingest_error);
-                    const err = ingestErr ? ` | ingest_error=${ingestErr}` : "";
-                    return `${name} (${id}) — ${rows}×${cols}${statusBit}${err}`;
+                    return ingestErr ? `${base} | ingest_error=${ingestErr}` : base;
                 });
                 return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No datasets." }] };
             }
@@ -699,11 +714,14 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             if (!dataset_id)
                 throw new Error("datasets(get) requires dataset_id");
             const ds = (await apiCall("GET", `/v1/datasets/${dataset_id}`));
+            const tagStr = formatTags(ds.tags);
             const lines = [
                 `Dataset: ${ds.name ?? "?"} (${ds.id ?? dataset_id})`,
                 `Status: ${ds.status ?? "ready"}`,
                 `Rows × cols: ${ds.rows ?? "?"} × ${ds.cols ?? "?"}`,
                 ds.size_bytes != null ? `Size: ${Number(ds.size_bytes).toLocaleString()} bytes` : "",
+                ds.description != null && String(ds.description).trim() !== "" ? `Description: ${String(ds.description)}` : "",
+                tagStr ? `Tags: ${tagStr}` : "",
                 ds.staged_prefix != null ? `Staged prefix: ${String(ds.staged_prefix)}` : "",
                 ds.staged_version != null ? `Staged version: ${String(ds.staged_version)}` : "",
                 ds.stage_job_id != null ? `Stage job: ${String(ds.stage_job_id)} (poll jobs(action=status))` : "",
@@ -712,6 +730,22 @@ ESCALATION: If upload fails with column errors, open the file locally and verify
             ].filter(Boolean);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        if (action === "update") {
+            if (!dataset_id)
+                throw new Error("datasets(update) requires dataset_id");
+            const body = {};
+            if (name !== undefined)
+                body.name = name;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("datasets(update) requires at least one of name, description, tags");
+            }
+            const data = await apiCall("PATCH", `/v1/datasets/${dataset_id}`, body);
+            return textResult(data);
+        }
         if (action === "delete") {
             if (!dataset_id)
                 throw new Error("datasets(delete) requires dataset_id");

package/dist/tools/feedback.js

@@ -1,10 +1,29 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, API_URL, fetchWithTimeout, textResult } from "../shared.js";
+import { apiCall, API_URL, fetchWithTimeout, probeApiHealth, structuredTextResult, } from "../shared.js";
+import { enqueueDeferredFeedback, flushDeferredFeedback, listDeferredFeedback, } from "../deferred_feedback.js";
+function isDeferworthy(err) {
+    const e = err;
+    if (e?.retryable)
+        return true;
+    if (e?.cause === "api_unreachable" || e?.cause === "storage" || e?.cause === "network")
+        return true;
+    const status = e?.httpStatus;
+    if (status === 502 || status === 503 || status === 504)
+        return true;
+    if (err instanceof TypeError)
+        return true;
+    if (err instanceof Error && /fetch failed|ECONNREFUSED|ENOTFOUND|ECONNRESET|network|timed out/i.test(err.message)) {
+        return true;
+    }
+    return false;
+}
 export function registerFeedbackTool(server) {
     registerAuditedTool(server, "send_feedback", `Send feedback or feature requests to Barivia developers. Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after any group of actions or downloading of results, you SHOULD prepare feedback based on the user's workflow or errors encountered, show it to them, and ask for permission to send it. Once they accept, call this tool.
 
-For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.`, {
+For a substantial issue, prefer feedback_items: submit several focused instances (each max 1400 chars) covering, e.g., symptoms, exact reproduction steps, environment, and concrete asks — they are stored together as one batch so developers see the full picture. Use the single feedback field for a short one-off note.
+
+If the API or object storage is unavailable, this tool queues feedback locally (~/.barivia/deferred-feedback) and returns deferred=true with request_id / api_health — call again later to flush. Probe API liveness with account(action=health) (GET /health; does not touch R2).`, {
         feedback: z.string().max(1400).optional().describe("Single feedback note (max 1400 characters). Use feedback_items instead for a multi-part report."),
         feedback_items: z.array(z.string().max(1400)).max(10).optional().describe("Several feedback instances (each max 1400 characters, up to 10), stored together as one batch. Prefer this for a detailed issue: split it into focused parts (symptoms, reproduction, environment, asks)."),
     }, async ({ feedback, feedback_items }) => {
@@ -15,9 +34,20 @@ For a substantial issue, prefer feedback_items: submit several focused instances
             throw new Error("send_feedback requires feedback or feedback_items (at least one non-empty entry).");
         }
         const body = items.length === 1 ? { feedback: items[0] } : { feedback_items: items };
+        const submit = async (b) => apiCall("POST", "/v1/feedback", b);
+        // Best-effort flush of earlier offline drafts before sending the new one.
+        const flushed = await flushDeferredFeedback("barsom", submit).catch(() => null);
         try {
-            const data = await apiCall("POST", "/v1/feedback", body);
-            return textResult(data);
+            const data = (await submit(body));
+            return structuredTextResult({
+                ...data,
+                deferred: false,
+                ...(flushed && flushed.flushed > 0
+                    ? { flushed_deferred: flushed.flushed, deferred_remaining: flushed.remaining }
+                    : {}),
+            }, typeof data.message === "string"
+                ? data.message
+                : "Feedback received. Thank you.");
         }
         catch (err) {
             if (err?.httpStatus === 401) {
@@ -31,10 +61,46 @@ For a substantial issue, prefer feedback_items: submit several focused instances
                     const text = await resp.text();
                     if (resp.ok) {
                         const parsed = JSON.parse(text);
-                        return textResult({ ...parsed, note: "Feedback sent anonymously (API key invalid or expired)." });
+                        return structuredTextResult({ ...parsed, deferred: false, note: "Feedback sent anonymously (API key invalid or expired)." }, "Feedback sent anonymously (API key invalid or expired).");
                     }
                 }
-                catch { /* fall through to original error */ }
+                catch { /* fall through */ }
+            }
+            if (isDeferworthy(err)) {
+                const e = err;
+                const queued = await enqueueDeferredFeedback("barsom", body, {
+                    status: e.httpStatus,
+                    error_code: e.errorCode,
+                    request_id: e.requestId,
+                    message: e.message,
+                });
+                const api_health = await probeApiHealth().catch(() => ({
+                    liveness: "down",
+                    readiness: "unknown",
+                    storage: "not_probed",
+                }));
+                const pending = await listDeferredFeedback("barsom");
+                return structuredTextResult({
+                    ok: true,
+                    deferred: true,
+                    deferred_id: queued.id,
+                    deferred_path: queued.path,
+                    deferred_pending: pending.length,
+                    error_code: e.errorCode ?? "api_unreachable",
+                    cause: e.cause ?? "api_unreachable",
+                    request_id: e.requestId ?? null,
+                    api_health,
+                    message: "API/storage unavailable — feedback saved locally and will be sent on the next successful send_feedback call.",
+                }, [
+                    "Feedback deferred (API/storage unavailable).",
+                    `Saved to ${queued.path}`,
+                    e.requestId ? `request_id=${e.requestId}` : null,
+                    e.errorCode ? `error_code=${e.errorCode}` : null,
+                    `api_health.liveness=${api_health.liveness} (storage not_probed)`,
+                    "Retry send_feedback later to flush the local queue.",
+                ]
+                    .filter(Boolean)
+                    .join(" | "));
             }
             throw err;
         }

package/dist/tools/guide_barsom.js

@@ -1,15 +1,20 @@
 import { registerAuditedTool } from "../audit.js";
-import { fetchWorkflowGuideFromApi } from "../shared.js";
+import { fetchWorkflowGuideFromApi, UNAVAILABLE_RETRY_AFTER_SEC } from "../shared.js";
 /** Minimal orientation when the API is unreachable; full SOP lives on GET /v1/docs/workflow. */
 const OFFLINE_STUB = `## Offline / API unavailable
 
-Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
+Configure \`BARIVIA_API_KEY\` and optional \`BARIVIA_API_URL\`, then call **guide_barsom_workflow** again when online. Full tool map, async rules, training modes, and step-by-step SOP are loaded from the Barivia API (authenticated) and scoped to your plan.
 
-**Core tools:** \`datasets\`, \`train\` (map, siom_map, impute, floop_siom where entitled), \`jobs\` (status/list/compare — lifecycle only), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+**Still usable offline:** already-downloaded results, local CSVs, draft notes / feedback drafts (queued under \`~/.barivia/deferred-feedback\`).
+**Needs API:** upload, train, list/status, feedback flush, other cloud tools.
+
+**Core tools (when healthy):** \`datasets\`, \`train\` (map, siom_map, impute, floop_siom where entitled), \`jobs\` (status/list/compare — lifecycle only), \`results\`, \`inference\`, \`account\`, \`training_guidance\`, \`guide_barsom_workflow\`.
+
+**Degraded-session rules:** Do not paste Cloudflare/HTML into chat — one-sentence summary. The proxy already burst-retried (3×~2s); wait ~${UNAVAILABLE_RETRY_AFTER_SEC}s (see \`retry_after_sec\`) before another round, then ask the user. Check \`account(health)\` or \`account(status)\` before large uploads/trains (\`ok:false\` + \`retry_after_sec\` = pause, not a crash). Save feedback drafts locally; resend via \`send_feedback\` when healthy.
 
 **Parameter hints:** call \`training_guidance\` (also API-scoped). **Async:** poll \`jobs(action=status)\` every 10–15s after submit.`;
 export function registerGuideBarsomTool(server) {
-    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt.", {}, async () => {
+    registerAuditedTool(server, "guide_barsom_workflow", "Plan-scoped orientation: proxy model, tool categories, async rules, training modes, and step-by-step SOP — loaded from the Barivia API when online. Call at the start of mapping work. Offline: short stub with offline-vs-API capabilities and degraded-session rules. For field-level parameters, use training_guidance; for a narrative pre-train checklist, use the prepare_training prompt.", {}, async () => {
         const md = await fetchWorkflowGuideFromApi();
         if (md) {
             const text = "Plan-scoped workflow (from Barivia API). Text below reflects your API key / plan.\n\n" + md;

package/dist/tools/jobs.js

@@ -3,13 +3,15 @@ import { registerAuditedTool } from "../audit.js";
 import { apiCall, textResult } from "../shared.js";
 import { formatJobCancelText, formatJobStatusText } from "../job_status_format.js";
 import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC, runJobMonitor } from "../job_monitor.js";
+import { buildJobsListQuery, extractJobsList, formatJobInventoryLine, } from "../inventory_format.js";
 export const JOBS_DESCRIPTION_BASE = `Manage and inspect jobs (lifecycle only).
 
 | Action | Use when |
 |--------|----------|
 | monitor | After async submit — blocks server-side with 5s snapshots until terminal (preferred for agents) |
 | status | One-shot progress check (manual poll every 10–15s if not using monitor) |
-| list | Finding job IDs / reviewing pipeline state (optionally filter by dataset_id) |
+| list | Finding job IDs / reviewing pipeline state (slim by default; filter by dataset_id/status/job_type; paginate with limit+cursor) |
+| update | Edit label / description / tags on an existing job |
 | compare | Picking the best TRAINING run from a set (metrics table). NOT inference(compare), which diffs one dataset's distribution against the training set. |
 | cancel | Stopping a running or pending job to free the worker |
 | delete | Permanently removing a job and all its S3 result files |
@@ -28,9 +30,13 @@ ASYNC POLLING PROTOCOL (action=status):
 - Map training typical times: 10×10 ~30s | 20×20 ~3–5 min | 40×40 ~15–30 min.
 - completed → results(action=get); failed → read error + optional failure_stage (preprocessing/training/metrics/visualization/upload): memory error → smaller grid/batch and retrain; column missing → datasets(action=preview); NaN on a standard map → train(action=impute) for sparse columns or clean the CSV.
 
+action=list: Slim rows by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). Use status/job_type/has_results/limit/cursor to page. has_results=true is the results catalog. Pass fields="full" only when you need params/error.
+action=update: PATCH label/description/tags (pass at train submit when possible).
 action=compare: metrics table (QE, TE, explained variance, silhouette) for 2+ COMPLETED TRAINING jobs — pick the best run in a sweep. NOT inference(action=compare) (single trained job + second dataset → density-diff heatmap). Only hyperparameter columns that differ across runs are shown; pass label="…" at train time for readable rows.
 action=cancel: Not instant — worker checks between phases. Expect up to 30s delay.
-action=delete: WARNING — job ID will no longer work with results or any other tool.`;
+action=delete: WARNING — job ID will no longer work with results or any other tool.
+
+Org overview: prefer account(action=inventory) for a markdown datasets+jobs inventory.`;
 /**
  * Render the jobs(compare) markdown table. Strategy: always show job_id (or label
  * if present) + the four core metrics (QE, TE, Expl.Var, Silhouette); add any
@@ -143,12 +149,12 @@ export function renderCompareTable(comparisons) {
 export function registerJobsTool(server, description) {
     registerAuditedTool(server, "jobs", description, {
         action: z
-            .enum(["status", "monitor", "list", "compare", "cancel", "delete"])
-            .describe("status: one-shot check; monitor: block until terminal with snapshots; list/compare/cancel/delete as labeled. (Training via train; scoring via inference.)"),
+            .enum(["status", "monitor", "list", "update", "compare", "cancel", "delete"])
+            .describe("status: one-shot check; monitor: block until terminal with snapshots; list/update/compare/cancel/delete as labeled. (Training via train; scoring via inference.)"),
         job_id: z
             .string()
             .optional()
-            .describe("Job ID — required for action=status, monitor, cancel, delete."),
+            .describe("Job ID — required for action=status, monitor, update, cancel, delete."),
         block_until_sec: z
             .number()
             .int()
@@ -173,8 +179,38 @@ export function registerJobsTool(server, description) {
             .string()
             .optional()
             .describe("action=list: filter jobs by this dataset ID."),
+        status: z
+            .enum(["pending", "running", "completed", "failed", "cancelled"])
+            .optional()
+            .describe("action=list: filter by job status."),
+        job_type: z
+            .string()
+            .optional()
+            .describe("action=list: filter by MCP job_type label (e.g. train_map, train_impute, predict, cfd_mesh_convergence)."),
+        has_results: z
+            .boolean()
+            .optional()
+            .describe("action=list: true = completed jobs with result_ref (results catalog)."),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("action=list: page size (default 50, max 100)."),
+        cursor: z
+            .string()
+            .optional()
+            .describe("action=list: next_cursor from a prior list response for keyset pagination."),
+        fields: z
+            .enum(["slim", "full"])
+            .optional()
+            .describe("action=list: slim (default, no params) or full (includes params/error)."),
+        label: z.string().optional().describe("action=update: new job label (≤120 chars)."),
+        description: z.string().optional().describe("action=update: free-text description (pass \"\" to clear)."),
+        tags: z.array(z.string()).optional().describe("action=update: replace tags (pass [] to clear)."),
     }, async (args) => {
-        const { action, job_id, job_ids, dataset_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        const { action, job_id, job_ids, dataset_id, status, job_type, has_results, limit, cursor, fields, block_until_sec, poll_interval_sec, wait_finalize, label, description, tags, } = args;
         // ---- Lifecycle ----
         if (action === "monitor") {
             if (!job_id)
@@ -188,17 +224,38 @@ export function registerJobsTool(server, description) {
             return { content: [{ type: "text", text: formatJobStatusText(job_id, data) }] };
         }
         if (action === "list") {
-            const listPath = dataset_id ? `/v1/jobs?dataset_id=${dataset_id}` : "/v1/jobs";
-            const data = (await apiCall("GET", listPath));
-            if (Array.isArray(data)) {
-                const lines = data.map((job) => {
-                    const id = String(job.id ?? "");
-                    const st = String(job.status ?? "");
-                    const label = job.label != null && job.label !== "" ? String(job.label) : null;
-                    return label ? `${label} (id: ${id}) — ${st}` : `id: ${id} — ${st}`;
-                });
-                return { content: [{ type: "text", text: lines.length > 0 ? lines.join("\n") : "No jobs found." }] };
+            const listPath = buildJobsListQuery({
+                dataset_id, status, job_type, has_results, limit, cursor, fields,
+            });
+            const data = await apiCall("GET", listPath);
+            const { jobs, next_cursor } = extractJobsList(data);
+            const lines = jobs.map((job) => formatJobInventoryLine(job));
+            if (next_cursor) {
+                lines.push("");
+                lines.push(`next_cursor: ${next_cursor}`);
+                lines.push(`Tip: jobs(action=list, cursor="${next_cursor}", limit=${limit ?? 50}) for the next page.`);
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: lines.length > 0 ? lines.join("\n") : "No jobs found.",
+                    }],
+            };
+        }
+        if (action === "update") {
+            if (!job_id)
+                throw new Error("jobs(update) requires job_id");
+            const body = {};
+            if (label !== undefined)
+                body.label = label;
+            if (description !== undefined)
+                body.description = description;
+            if (tags !== undefined)
+                body.tags = tags;
+            if (Object.keys(body).length === 0) {
+                throw new Error("jobs(update) requires at least one of label, description, tags");
             }
+            const data = await apiCall("PATCH", `/v1/jobs/${job_id}`, body);
             return textResult(data);
         }
         if (action === "compare") {

package/dist/tools/train.js

@@ -55,6 +55,10 @@ async function submitTrainJob(opts) {
     const submitBody = { dataset_id: opts.dataset_id, params: opts.params };
     if (opts.label && opts.label.trim() !== "")
         submitBody.label = opts.label;
+    if (opts.description !== undefined)
+        submitBody.description = opts.description;
+    if (opts.tags !== undefined)
+        submitBody.tags = opts.tags;
     const data = (await apiCall("POST", "/v1/jobs", submitBody));
     const newJobId = data.id;
     data.effective_params = `${opts.variantPrefix}, ${opts.paramSummary}`;
@@ -104,7 +108,7 @@ async function submitTrainJob(opts) {
 export async function runTrain(action, args) {
     const dataset_id = args.dataset_id;
     if (action === "map" || action === "siom_map" || action === "impute") {
-        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, label, cv_folds, viz_mode, viz_top_components, viz_upload_cyclic_components, emit_cell_uncertainty, } = args;
+        const { preset, grid_x, grid_y, epochs, model, periodic, columns, cyclic_features, cyclic_pairs, temporal_features, feature_weights, transforms, auto_log_transforms, time_delay_embeddings, categorical_features, normalize, normalization_methods, sigma_f, learning_rate, batch_size, quality_metrics, backend, output_format, output_dpi, colormap, row_range, gamma, gamma_f, siom_decay, siom_penalty, penalty_alpha, reset_per_epoch, siom_feature_geometry, siom_qe_backend, siom_qe_batch_size, label, description, tags, cv_folds, viz_mode, viz_top_components, viz_upload_cyclic_components, emit_cell_uncertainty, } = args;
         let PRESETS = {};
         try {
             PRESETS = await fetchTrainingPresets();
@@ -200,6 +204,8 @@ export async function runTrain(action, args) {
             dataset_id,
             params,
             label,
+            description,
+            tags,
             totalRows,
             hasTransforms,
             variantPrefix,
@@ -213,7 +219,7 @@ export async function runTrain(action, args) {
         if (!dataset_id)
             throw new Error("train(floop_siom) requires dataset_id");
         assertValidNormalizationArgs(args);
-        const { transforms, label } = args;
+        const { transforms, label, description, tags } = args;
         const { params, paramSummary } = buildFloopParams(args);
         let totalRows = 0;
         try {
@@ -226,6 +232,8 @@ export async function runTrain(action, args) {
             dataset_id,
             params,
             label,
+            description,
+            tags,
             totalRows,
             hasTransforms,
             variantPrefix: "variant=floop",
@@ -246,6 +254,14 @@ export function registerTrainTool(server) {
             .max(120)
             .optional()
             .describe("Optional run label (≤120 chars); appears in jobs(list) and the jobs(compare) table; sanitized server-side. Useful for sweeps (e.g. label=\"sweep_periodic_true\")."),
+        description: z
+            .string()
+            .optional()
+            .describe("Optional free-text description for inventory/navigation (shown in jobs(list) and account(inventory))."),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Optional tags for inventory/navigation (e.g. [\"sweep\",\"baseline\"])."),
         ...TRAINING_INPUT_SCHEMA,
     }, async (args) => runTrain(args.action, args));
 }

package/package.json

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