@barivia/barmesh-mcp 0.7.0 → 0.8.0

package/dist/tools/cfd.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult } from "../shared.js";
+import { apiCall, textResult, suggestAfterCfdSubmit } from "../shared.js";
 import { pollCfdPrepareIfPresent } from "../cfd_prepare.js";
 export function registerCfdTools(server) {
     registerAuditedTool(server, "barmesh_mesh_convergence", `Run SOM-based mesh-convergence analysis on an uploaded combined per-cell CSV.
@@ -10,14 +10,14 @@ What it does (one call): joint-normalizes all meshes, trains one SOM on a strati
 BEST FOR: A mesh-refinement study where you want a field-level (not just scalar) view of whether the mesh has converged.
 NOT FOR: Single scalar quantities of interest — use barmesh_richardson for classical GCI.
 ASYNC: This is a queued job. It returns a job id immediately. Then poll barmesh_jobs(action=status) every 10-20s; datacenter-scale grids plus EMD can take a few minutes — keep polling. On completion call barmesh_results(action=get).
-COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time.`, {
+COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh label that is not present; forgetting the cell-volume column at upload time; multi-topology studies (uniform U + graded G meshes) without explicit mesh_order — equal cell counts sort U-then-G and invent bogus stepwise pairs (U160|G20). Pass mesh_order coarse→fine interleaved by refinement (U20,G20,U40,G40,…) or use preset=cavity which defaults interleaved when U/G labels are detected.`, {
         dataset_id: z.string().describe("Dataset ID from barmesh_datasets(upload)"),
         feature_columns: z.array(z.string()).describe("Per-cell numeric feature columns to train the SOM on (e.g. [\"p\",\"U_mag\",\"k\",\"log_epsilon\"])"),
         preset: z.enum(["generic", "cavity", "pitz", "datacenter"]).optional().describe("Hyperparameter preset; defaults to generic. cavity/pitz/datacenter reproduce the published settings."),
         mesh_column: z.string().optional().describe("Column with the mesh label (default mesh_id)"),
         volume_column: z.string().optional().describe("Cell-volume column for fingerprint weights (default V; equal weights if absent)"),
         reference_mesh: z.string().optional().describe("Mesh label used as reference (default: the mesh with the most cells = finest)"),
-        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count)"),
+        mesh_order: z.array(z.string()).optional().describe("Explicit coarse-to-fine mesh order (default: ascending cell count; cavity preset and tied U/G cell counts auto-interleave U20→G20→U40→G40→…)"),
         grid: z.array(z.number().int()).optional().describe("SOM grid [rows, cols] (overrides preset)"),
         epochs: z.array(z.number().int()).optional().describe("[ordering, convergence] epochs (overrides preset)"),
         batch_size: z.number().int().optional().describe("SOM batch size (overrides preset)"),
@@ -34,8 +34,10 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         normalization_methods: z.record(z.enum(["zscore", "mad", "sigmoidal", "sepd", "none"])).optional().describe("Per-feature normalization override; keys must be in feature_columns."),
         row_range: z.tuple([z.number().int().min(1), z.number().int().min(1)]).optional().describe("1-based inclusive [start, end] row slice applied during preprocessing (and to mesh labels / cell volumes)."),
         label: z.string().optional().describe("Optional job label"),
+        description: z.string().optional().describe("Optional free-text description for inventory"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),
     }, async (args) => {
-        const { dataset_id, label, ...rest } = args;
+        const { dataset_id, label, description, tags, ...rest } = args;
         const params = {};
         for (const [k, v] of Object.entries(rest)) {
             if (v !== undefined && v !== null)
@@ -47,12 +49,16 @@ COMMON MISTAKES: omitting feature_columns (required); choosing a reference_mesh
         const body = { dataset_id, params };
         if (typeof label === "string" && label.length > 0)
             body.label = label;
+        if (description !== undefined)
+            body.description = description;
+        if (tags !== undefined)
+            body.tags = tags;
         const data = (await apiCall("POST", "/v1/cfd/mesh-convergence", body));
         await pollCfdPrepareIfPresent(data, "barmesh_mesh_convergence");
         const id = data.id;
         if (id != null) {
             const prep = data.prepare_job_id != null ? " (dataset prepare complete)" : "";
-            data.suggested_next_step = `Run barmesh_training_monitor(job_id="${id}") or barmesh_jobs(action=monitor, job_id="${id}")${prep}; on completion call barmesh_results(action=get, job_id="${id}").`;
+            data.suggested_next_step = suggestAfterCfdSubmit(String(id), prep);
         }
         return textResult(data);
     });
@@ -63,7 +69,7 @@ What it does: from a small CSV with one row per mesh (a mesh label, a representa
 BEST FOR: Scalar benchmarks (reattachment length, centerline values, probe readings) where a classical asymptotic-convergence check is expected.
 NOT FOR: High-dimensional field comparison — use barmesh_mesh_convergence (complementary).
 ASYNC: queued job; poll barmesh_jobs(action=status), then barmesh_results(action=get).
-COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV.`, {
+COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with different mesh sets in one CSV; mixing uniform (U…) and graded (G…) mesh families in one CSV — classical GCI assumes one topology per job; run separate Richardson jobs per family (e.g. G160|G80|G40 graded, U160|U80|U40 uniform).`, {
         dataset_id: z.string().describe("Dataset ID (one row per mesh)"),
         qoi_columns: z.array(z.string()).describe("Scalar QoI column names to extrapolate"),
         mesh_column: z.string().optional().describe("Mesh label column (default mesh_id)"),
@@ -72,8 +78,10 @@ COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with diff
         dimension: z.number().int().optional().describe("Spatial dimension d for deriving h from cell count (default 3)"),
         safety_factor: z.number().optional().describe("GCI safety factor Fs (default 1.25, Roache)"),
         label: z.string().optional().describe("Optional job label"),
+        description: z.string().optional().describe("Optional free-text description for inventory"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation"),
     }, async (args) => {
-        const { dataset_id, label, ...rest } = args;
+        const { dataset_id, label, description, tags, ...rest } = args;
         const params = {};
         for (const [k, v] of Object.entries(rest)) {
             if (v !== undefined && v !== null)
@@ -82,10 +90,14 @@ COMMON MISTAKES: not providing h_column or n_cells_column; mixing QoIs with diff
         const body = { dataset_id, params };
         if (typeof label === "string" && label.length > 0)
             body.label = label;
+        if (description !== undefined)
+            body.description = description;
+        if (tags !== undefined)
+            body.tags = tags;
         const data = (await apiCall("POST", "/v1/cfd/richardson", body));
         const id = data.id;
         if (id != null)
-            data.suggested_next_step = `Run barmesh_training_monitor(job_id="${id}") or barmesh_jobs(action=monitor, job_id="${id}"); on completion call barmesh_results(action=get, job_id="${id}").`;
+            data.suggested_next_step = suggestAfterCfdSubmit(String(id));
         return textResult(data);
     });
 }

package/dist/tools/datasets.js

@@ -4,8 +4,9 @@ import { z } from "zod";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, } from "../shared.js";
+import { apiCall, getWorkspaceRootAsync, resolveFilePathForUpload, textResult, pollUntilComplete, UPLOAD_DATASET_TIMEOUT_MS, LARGE_UPLOAD_BYTES, PRESIGNED_PUT_TIMEOUT_MS, POLL_STAGE_MAX_MS, streamFileSha256, putPresignedStream, resolveUploadContentType, suggestMeshDatasetPreview, } from "../shared.js";
 import { GZIP_UPLOAD_HINT } from "../upload_hints.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".
@@ -23,12 +24,14 @@ Formats: plain CSV/TSV or gzip (.csv.gz / .tsv.gz). For files above ~64 MB, pref
 
 | Action | Use when |
 |--------|----------|
-| upload | You have prepared a combined per-cell CSV (mesh_id + feature columns + cell volume V). Do this first. |
+| upload | You have prepared a combined per-cell CSV (mesh_id + feature columns + cell volume V). Do this first. Optional description/tags help inventory. |
 | preview | After upload — verify the mesh column, feature columns, and volume column are present and numeric. |
-| get | Fetch one dataset by id — status, staging fields, ingest_error (use after upload or when staging is slow). |
-| list | Find dataset IDs for analysis. |
+| get | Fetch one dataset by id — status, staging fields, ingest_error, description/tags (use after upload or when staging is slow). |
+| list | Find dataset IDs for analysis (includes description/tags). |
+| update | Edit name / description / tags on an existing dataset. |
 | subset | Shrink a huge per-cell table server-side (row_range, filters, or sample_n). |
 | delete | Remove a dataset permanently. |
+| inventory | Prefer barmesh_jobs(action=inventory) for a full datasets+jobs markdown overview. |
 
 action=upload: PREFER file_path — server reads from workspace root (token-efficient). Accepts .csv, .tsv, .csv.gz, .tsv.gz. Use csv_data only for small inline pastes (<10KB). If plain CSV exceeds the 5 GB upload cap, gzip it first (.csv.gz).
 
@@ -37,9 +40,11 @@ NOT FOR: Raw OpenFOAM case directories — extract a per-cell CSV first (see bar
 COMMON MISTAKES: omitting the cell-volume column (defaults to equal weights, which weakens the fingerprint); inconsistent feature columns across meshes.
 ESCALATION: If preview shows a feature column as non-numeric, fix the extraction and re-upload.`, {
         action: z
-            .enum(["upload", "preview", "list", "get", "subset", "delete"])
-            .describe("upload: add CSV or .csv.gz; preview: inspect columns; list: see all datasets; get: fetch one dataset metadata (status/staging); subset: create filtered subset; delete: remove dataset"),
-        name: z.string().optional().describe("Dataset name (required for upload and subset)"),
+            .enum(["upload", "preview", "list", "get", "update", "subset", "delete"])
+            .describe("upload: add CSV or .csv.gz; preview: inspect columns; list: see all datasets; get: fetch one dataset metadata (status/staging); update: edit name/description/tags; subset: create filtered subset; delete: remove dataset"),
+        name: z.string().optional().describe("Dataset name (required for upload and subset; optional for update)"),
+        description: z.string().optional().describe("Optional free-text description (upload/update)"),
+        tags: z.array(z.string()).optional().describe("Optional tags for inventory/navigation (upload/update)"),
         file_path: z
             .string()
             .optional()
@@ -86,14 +91,16 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             .int()
             .optional()
             .describe("action=subset: RNG seed for sample_n (default 42)."),
-    }, async ({ action, name, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, sample_n, sample_seed, }) => {
+    }, async ({ action, name, description, tags, file_path, csv_data, dataset_id, n_rows, row_range, filters, filter, sample_n, sample_seed, }) => {
         if (action === "upload") {
             if (!name)
                 throw new Error("barmesh_datasets(upload) requires name.");
             let body;
+            let uploadContentType = "text/csv";
             if (file_path && file_path.length > 0) {
                 await apiCall("GET", "/v1/system/info");
                 const resolved = await resolveFilePathForUpload(file_path, server);
+                uploadContentType = resolveUploadContentType(resolved);
                 const lower = resolved.toLowerCase();
                 const isGzipInput = lower.endsWith(".gz");
                 const baseExt = path.extname(isGzipInput ? lower.slice(0, -3) : lower);
@@ -119,7 +126,12 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                     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);
@@ -134,10 +146,10 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                             id: datasetId,
                             status: init.status,
                             idempotent_replay: true,
-                            suggested_next_step: `barmesh_datasets(action=preview, dataset_id=${datasetId})`,
+                            suggested_next_step: suggestMeshDatasetPreview(datasetId),
                         });
                     }
-                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? "application/octet-stream", PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
+                    await putPresignedStream(init.upload_url, resolved, init.content_type ?? uploadContentType, PRESIGNED_PUT_TIMEOUT_MS, isGzipInput);
                     const fin = (await apiCall("POST", `/v1/datasets/${datasetId}/finalize`, {}));
                     const jobId = (fin.id ?? fin.job_id);
                     const poll = await pollUntilComplete(jobId, POLL_STAGE_MAX_MS);
@@ -150,21 +162,26 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
                         status: ready ? "ready" : "staging",
                         job_id: jobId,
                         suggested_next_step: ready
-                            ? `barmesh_datasets(action=preview, dataset_id=${datasetId}) to verify mesh, feature, and volume columns.`
-                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}") then barmesh_datasets(action=preview, dataset_id=${datasetId}).`,
+                            ? suggestMeshDatasetPreview(datasetId)
+                            : `Still staging; poll barmesh_jobs(action=status, job_id="${jobId}") then ${suggestMeshDatasetPreview(datasetId)}.`,
                     });
                 }
                 if (isGzipInput) {
                     const gzBytes = await fs.readFile(resolved);
-                    const data = (await apiCall("POST", "/v1/datasets", gzBytes, {
+                    const gzHeaders = {
                         "X-Dataset-Name": name,
-                        "Content-Type": "text/csv",
+                        "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 = `Next: barmesh_datasets(action=preview, dataset_id=${gid}) to verify the mesh, feature, and volume columns.`;
+                        data.suggested_next_step = suggestMeshDatasetPreview(String(gid));
                     }
                     return textResult(data);
                 }
@@ -179,9 +196,13 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const GZIP_THRESHOLD = 1024 * 1024;
             const uploadHeaders = {
                 "X-Dataset-Name": name,
-                "Content-Type": "text/csv",
+                "Content-Type": uploadContentType,
                 "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"));
@@ -190,7 +211,7 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const data = (await apiCall("POST", "/v1/datasets", uploadBody, uploadHeaders, UPLOAD_DATASET_TIMEOUT_MS));
             const id = data.id ?? data.dataset_id;
             if (id != null) {
-                data.suggested_next_step = `Next: barmesh_datasets(action=preview, dataset_id=${id}) to verify the mesh, feature, and volume columns.`;
+                data.suggested_next_step = suggestMeshDatasetPreview(String(id));
             }
             return textResult(data);
         }
@@ -225,15 +246,9 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             const data = (await apiCall("GET", "/v1/datasets"));
             if (Array.isArray(data)) {
                 const lines = data.map((ds) => {
-                    const id = String(ds.id ?? "");
-                    const dsName = 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 `${dsName} (${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." }] };
             }
@@ -243,11 +258,14 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             if (!dataset_id)
                 throw new Error("barmesh_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 barmesh_jobs(action=status))` : "",
@@ -256,6 +274,22 @@ ESCALATION: If preview shows a feature column as non-numeric, fix the extraction
             ].filter(Boolean);
             return { content: [{ type: "text", text: lines.join("\n") }] };
         }
+        if (action === "update") {
+            if (!dataset_id)
+                throw new Error("barmesh_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("barmesh_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("barmesh_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, "barmesh_send_feedback", `Send feedback or feature requests to Barivia developers (CFD mesh-convergence / barmesh workflow). Use when the user has suggestions, ran into issues, or wants something improved. Do NOT call without asking the user first — but after a mesh-convergence or Richardson session, 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 (e.g. gateway HTML 502 mid-demo), this tool queues feedback locally (~/.barivia/deferred-feedback, shared with barsom send_feedback) and returns deferred=true with request_id + api_health from GET /health (no R2). Call again later to flush.`, {
         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,19 @@ For a substantial issue, prefer feedback_items: submit several focused instances
             throw new Error("barmesh_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);
+        const flushed = await flushDeferredFeedback("barmesh", 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 +60,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("barmesh", 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("barmesh");
+                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 barmesh_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 barmesh_send_feedback later to flush the local queue.",
+                ]
+                    .filter(Boolean)
+                    .join(" | "));
             }
             throw err;
         }

package/dist/tools/guide.js

@@ -1,20 +1,36 @@
 import { registerAuditedTool } from "../audit.js";
-import { apiCall, textResult } from "../shared.js";
-const OFFLINE_GUIDE = `barmesh: CFD mesh-convergence on the Barivia API.
-Two tracks: barmesh_mesh_convergence (SOM fingerprint distances) and barmesh_richardson (classical GCI).
-Workflow: barmesh_prepare_mesh_data -> barmesh_datasets(upload) -> barmesh_mesh_convergence / barmesh_richardson -> barmesh_training_monitor (default visual MCP App; post-hoc review when already done) or barmesh_jobs(monitor/status) headless fallback -> barmesh_results(get) -> barmesh_results_explorer for figures.
-(API unreachable; this is the offline summary. Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
+import { apiCall, probeApiHealth, structuredTextResult, textResult } from "../shared.js";
+import { listDeferredFeedback } from "../deferred_feedback.js";
+const OFFLINE_GUIDE = `Mesh analysis API temporarily unavailable — figures already on disk stay available; new jobs/feedback will wait.
+
+barmesh offline summary (demo-safe): keep reviewing the last good distances, GCI CSV, and downloaded figures. Say the API is unavailable plainly; the proxy already burst-retried (~3×2s) — wait ~30s before another round. Do not treat the session as failed.
+
+Two tracks (when API returns):
+- barmesh_mesh_convergence — SOM volume-fingerprint distances (symmetric KL + Wasserstein-1 vs reference and stepwise)
+- barmesh_richardson — classical Richardson / GCI on scalar QoIs (one mesh family per CSV: uniform OR graded, not mixed)
+
+Workflow (when API returns):
+1. barmesh_prepare_mesh_data — recipe for the combined per-cell CSV (mesh_id + features + cell volume V)
+2. barmesh_datasets(upload) → barmesh_datasets(preview)
+3. barmesh_mesh_convergence and/or barmesh_richardson — returns job_id
+   - Multi-topology cavity studies: pass mesh_order interleaved (U20,G20,U40,G40,…) or preset=cavity
+4. barmesh_training_monitor (visual MCP App) or barmesh_jobs(action=monitor) headless — poll until complete
+5. barmesh_results(action=get) → barmesh_results_explorer for figures (mesh_convergence) or richardson_gci.csv summary (Richardson)
+
+(Set BARIVIA_API_KEY / BARIVIA_API_URL when reconnecting.)`;
 const OFFLINE_PREP = `barmesh mesh-data prep (offline summary; API unreachable):
 Build ONE combined per-cell CSV across all meshes of the refinement study:
 - one row per cell; a mesh label column (mesh_id); the physical channels you want compared (e.g. p, U_mag, k, log_epsilon — log-compress turbulence quantities); and a cell-volume column (V) for fingerprint weighting.
 - keep the SAME feature columns across every mesh; pick the finest mesh as the reference.
+- multi-topology (U + G): pass mesh_order coarse→fine interleaved by refinement (U20,G20,U40,G40,U80,G80,U160,G160) or use preset=cavity.
 Then: barmesh_datasets(upload) -> barmesh_mesh_convergence. (Set BARIVIA_API_KEY / BARIVIA_API_URL.)`;
 export function registerGuideTool(server) {
     registerAuditedTool(server, "barmesh_guide_workflow", `Get the barmesh CFD mesh-convergence workflow and tool map from the API (tier-scoped).
 
 BEST FOR: First call in a session — orients you on the two tracks (SOM fingerprint distances and Richardson/GCI), the upload->submit->poll->results flow, and what your plan allows.
 NOT FOR: Step-by-step mesh-data preparation — use barmesh_prepare_mesh_data for that.
-ESCALATION: If the response says your plan does not include CFD tools, the analysis tools will return 403; contact Barivia to enable the cfd entitlement.`, {}, async () => {
+ESCALATION: If the response says your plan does not include CFD tools, the analysis tools will return 403; contact Barivia to enable the cfd entitlement.
+UNAVAILABLE: If the API is down, this tool returns a calm offline summary — say so plainly, keep reviewing last good results, and suggest retry later (~30s).`, {}, async () => {
         try {
             const data = (await apiCall("GET", "/v1/cfd/guide"));
             return textResult({
@@ -33,7 +49,7 @@ ESCALATION: If the response says your plan does not include CFD tools, the analy
 
 BEST FOR: Before barmesh_datasets(upload) — tells you which physical channels to extract, how to label meshes (mesh_id), the cell-volume column (V), and how to pick the reference mesh.
 NOT FOR: Submitting jobs — after preparing the CSV, use barmesh_datasets(upload) then barmesh_mesh_convergence.
-COMMON MISTAKES: forgetting the per-cell cell-volume column; using different channels across meshes; not log-compressing turbulence quantities (k, epsilon, omega).`, {}, async () => {
+COMMON MISTAKES: forgetting the per-cell cell-volume column; using different channels across meshes; not log-compressing turbulence quantities (k, epsilon, omega); multi-topology U+G studies without mesh_order (use interleaved U20,G20,U40,G40,… or preset=cavity).`, {}, async () => {
         try {
             const data = (await apiCall("GET", "/v1/cfd/prep"));
             return textResult({ recipe: data.recipe, entitled: data.entitled });
@@ -44,4 +60,22 @@ COMMON MISTAKES: forgetting the per-cell cell-volume column; using different cha
             return textResult(OFFLINE_PREP);
         }
     });
+    registerAuditedTool(server, "barmesh_api_health", `Probe Barivia API liveness/readiness without touching object storage (R2).
+
+BEST FOR: Mid-demo outages — distinguish "API process up" from storage/gateway failures when barmesh_send_feedback or uploads fail.
+Uses GET /health (always 200 if process alive) and GET /ready (DB; Redis best-effort). storage is always not_probed.
+Also reports how many deferred barmesh feedback drafts are queued locally.`, {}, async () => {
+        const health = await probeApiHealth();
+        const deferred = await listDeferredFeedback("barmesh").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 (barmesh): ${deferred.length}`,
+        ].filter(Boolean);
+        return structuredTextResult({ ...health, deferred_feedback_pending: deferred.length }, lines.join("\n"));
+    });
 }

package/dist/tools/jobs.js

@@ -5,17 +5,28 @@ import { pollCfdFinalizeIfPresent, refreshJobAfterFinalize } from "../cfd_finali
 import { formatJobStatusText } from "../job_status_format.js";
 import { DEFAULT_BLOCK_UNTIL_SEC, DEFAULT_POLL_INTERVAL_SEC } from "../job_monitor.js";
 import { runBlockingMonitor } from "../blocking_monitor.js";
+import { buildJobsListQuery, extractJobsList, formatDatasetInventoryLine, formatJobInventoryLine, } from "../inventory_format.js";
 export function registerJobsTool(server) {
-    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, or list jobs.
+    registerAuditedTool(server, "barmesh_jobs", `Check job status, block until terminal, list/update jobs, or rebuild an org inventory.
 
-BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check.
+| Action | Use when |
+|--------|----------|
+| monitor | After async submit — blocks with snapshots until terminal (preferred for agents) |
+| status | One-shot progress check |
+| list | Slim recent jobs (filter/page with limit/cursor/status/job_type/has_results) |
+| update | Edit label / description / tags |
+| inventory | Markdown overview of datasets + recent jobs |
+
+BEST FOR: action=monitor after submit (one call, throttled snapshots — preferred for agents). action=status for a single one-shot check. action=inventory for a durable org catalog.
 MONITOR MODES: barmesh_training_monitor — default visual MCP App (live curves, post-hoc review on completed jobs). barmesh_jobs(action=monitor) — headless blocking snapshots for agents (live or post-hoc review; attaches learning_curve.png when already completed).
 ASYNC PROTOCOL: monitor blocks server-side until completed/failed or block_until timeout (default ${DEFAULT_BLOCK_UNTIL_SEC}s, poll every ${DEFAULT_POLL_INTERVAL_SEC}s). status is one-shot; poll every 10-20s manually if not using monitor. When status=completed, call barmesh_results(action=get, job_id=...) then barmesh_results_explorer(job_id=...).
-ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.`, {
+LIST: slim by default (label,id,status,job_type,dataset_id,created_at,result_ref,description,tags — no fat params). has_results=true is the results catalog.
+ESCALATION: status=failed returns an error message and (when available) a failure_stage; read it before retrying.
+UNAVAILABLE: If the mesh analysis API is temporarily unavailable, say so plainly, pause (proxy already burst-retried; wait ~retry_after_sec), and keep reviewing the last good distances/figures — do not treat the demo as failed. Suggest retry later.`, {
         action: z
-            .enum(["status", "monitor", "list"])
-            .describe("status: one-shot check; monitor: block until terminal with snapshots; list: recent jobs"),
-        job_id: z.string().optional().describe("Job ID (required for status and monitor)"),
+            .enum(["status", "monitor", "list", "update", "inventory"])
+            .describe("status: one-shot check; monitor: block until terminal; list: slim paginated jobs; update: metadata; inventory: datasets+jobs overview"),
+        job_id: z.string().optional().describe("Job ID (required for status, monitor, update)"),
         block_until_sec: z
             .number()
             .int()
@@ -32,8 +43,33 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             .boolean()
             .optional()
             .describe("action=monitor only: wait for cfd_finalize (default true)"),
+        dataset_id: z.string().optional().describe("action=list: filter by dataset ID"),
+        status: z
+            .enum(["pending", "running", "completed", "failed", "cancelled"])
+            .optional()
+            .describe("action=list: filter by status"),
+        job_type: z
+            .string()
+            .optional()
+            .describe("action=list: MCP job_type label (e.g. cfd_mesh_convergence, cfd_richardson)"),
+        has_results: z
+            .boolean()
+            .optional()
+            .describe("action=list: true = completed jobs with result_ref"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("action=list/inventory: page size (default 50)"),
+        cursor: z.string().optional().describe("action=list: next_cursor from a prior page"),
+        fields: z.enum(["slim", "full"]).optional().describe("action=list: slim (default) or full"),
+        label: z.string().optional().describe("action=update: new label"),
+        description: z.string().optional().describe("action=update: free-text description"),
+        tags: z.array(z.string()).optional().describe("action=update: replace tags"),
     }, async (args) => {
-        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize } = args;
+        const { action, job_id, block_until_sec, poll_interval_sec, wait_finalize, dataset_id, status, job_type, has_results, limit, cursor, fields, label, description, tags, } = args;
         if (action === "monitor") {
             if (!job_id)
                 throw new Error("barmesh_jobs(monitor) requires job_id.");
@@ -43,16 +79,86 @@ ESCALATION: status=failed returns an error message and (when available) a failur
             if (!job_id)
                 throw new Error("barmesh_jobs(status) requires job_id.");
             let data = (await apiCall("GET", `/v1/jobs/${job_id}`));
-            const status = String(data.status ?? "");
+            const statusVal = String(data.status ?? "");
             let note = null;
-            if (status === "completed" && data.finalize_job_id) {
+            if (statusVal === "completed" && data.finalize_job_id) {
                 ({ note } = await pollCfdFinalizeIfPresent(job_id, data));
                 data = await refreshJobAfterFinalize(job_id);
             }
             const statusText = await formatJobStatusText(job_id, data);
             return textResult({ ...data, status_text: note ? `${statusText}\n${note}` : statusText });
         }
-        const data = await apiCall("GET", "/v1/jobs");
-        return textResult(data);
+        if (action === "list") {
+            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: barmesh_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("barmesh_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("barmesh_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 === "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 (barmesh)`,
+                ``,
+                `## 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: barmesh_jobs(action=list, cursor="${next_cursor}", limit=${jobLimit})`);
+            }
+            lines.push(``);
+            lines.push(`Tips: set description/tags on barmesh_datasets(upload|update) and barmesh_mesh_convergence / barmesh_jobs(update).`);
+            return { content: [{ type: "text", text: lines.join("\n") }] };
+        }
+        throw new Error("Invalid action");
     });
 }