@barivia/barmesh-mcp 0.7.1 → 0.8.2

package/dist/shared.js

@@ -20,18 +20,22 @@ import { logInfo, logWarn } from "./logger.js";
 export const API_URL = process.env.BARIVIA_API_URL ?? "https://api.barivia.se";
 export const API_KEY = process.env.BARIVIA_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();
 }
 /** Single source of truth for the proxy version. Keep in sync with package.json on bump. */
-export const CLIENT_VERSION = "0.7.1";
+export const CLIENT_VERSION = "0.8.2";
 export const PUBLIC_SITE_ORIGIN = "https://barivia.se";
 /** Large per-cell CSV uploads may exceed the default fetch timeout. */
 export const UPLOAD_DATASET_TIMEOUT_MS = 180_000;
@@ -139,6 +143,51 @@ export function getClientSupportsMcpApps() {
 export function setClientSupportsMcpApps(value) {
     _clientSupportsMcpApps = value;
 }
+export const BARMESH_VIZ_VIEWS = {
+    trainingMonitor: "barmesh-training-monitor",
+    resultsExplorer: "barmesh-results-explorer",
+};
+export function buildStandaloneVizPageUrl(port, viewPath, jobId) {
+    if (!port)
+        return undefined;
+    return `http://localhost:${port}/viz/${viewPath}?mode=standalone&job_id=${encodeURIComponent(jobId)}`;
+}
+export function buildVizRelatedUrls(port, jobId, views) {
+    if (!port)
+        return undefined;
+    return {
+        trainingMonitor: buildStandaloneVizPageUrl(port, views.trainingMonitor, jobId),
+        resultsExplorer: buildStandaloneVizPageUrl(port, views.resultsExplorer, jobId),
+    };
+}
+/** Prominent standalone URL blocks for tool results — always emitted when a viz port exists. */
+export function buildVizUrlContentBlocks(options) {
+    const { label, toolName, standaloneUrl, port, jobId, clientSupportsMcpApps } = options;
+    if (!standaloneUrl)
+        return [];
+    const embedNote = clientSupportsMcpApps
+        ? "Embedded panel if your host supports MCP Apps — otherwise open the standalone URL below (expected on some Cursor builds)."
+        : "Open the standalone URL below when no inline panel appears.";
+    const health = port > 0
+        ? ` Health check: http://localhost:${port}/api/health?job_id=${encodeURIComponent(jobId)}`
+        : "";
+    const blocks = [
+        {
+            type: "text",
+            text: `${embedNote}\n` +
+                `Standalone ${label} URL (copy if Open is blocked):\n${standaloneUrl}\n` +
+                `AGENT: surface this URL prominently in your reply — use a markdown link "[Open ${label}](${standaloneUrl})" or tell the user to copy/paste into a browser. Do not bury it after metrics.\n` +
+                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run ${toolName} for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.${health}`,
+        },
+    ];
+    if (!clientSupportsMcpApps) {
+        blocks.push({
+            type: "text",
+            text: `[Open ${label}](${standaloneUrl})`,
+        });
+    }
+    return blocks;
+}
 /** Tool result carrying both a structured payload (for the MCP App view) and text/image content. */
 export function structuredTextResult(structuredContent, text, content) {
     return {
@@ -247,47 +296,227 @@ export async function resolveFilePathForUpload(filePath, mcpServer) {
     const resolved = path.resolve(root, trimmed);
     return checkUnder(resolved);
 }
-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 = ` Regenerate or verify your key via ${PUBLIC_SITE_ORIGIN} 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 — your plan does not include the CFD capability. Add the CFD capability at ${PUBLIC_SITE_ORIGIN}/dashboard to enable the barmesh tools.`
-                : 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 or rate limit — read the error above; delete unused datasets or wait and retry."
-                            : status === 502
-                                ? " Object storage error from API — retry later."
-                                : status === 503
-                                    ? " 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 — your plan does not include the CFD capability. Add the CFD capability at ${PUBLIC_SITE_ORIGIN}/dashboard to enable the barmesh tools.`;
+        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 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 = "Mesh analysis 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 barmesh_api_health — /health does not depend on R2. Keep reviewing last good distances/figures; do not paste HTML.";
+        }
+        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; barmesh_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: "Mesh analysis 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),
+        };
+    }
+}
 // ---- Distributed-trace context (W3C traceparent) ----
 // One trace per logical tool action (scoped via AsyncLocalStorage in registerAuditedTool),
 // so the API + job chain reconstruct end-to-end. Fresh span per API call; falls back to a
@@ -375,9 +604,13 @@ export async function apiCall(method, pathPart, body, extraHeaders, requestTimeo
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
                 throw new Error(`Request timed out after ${effectiveTimeout}ms. Increase BARIVIA_FETCH_TIMEOUT_MS (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). */
@@ -430,9 +663,13 @@ export async function apiRawCall(pathPart, requestTimeoutMs) {
             if (err instanceof DOMException && err.name === "AbortError" && !err.httpStatus) {
                 throw new Error(`Image 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;
 }
 // ---------------------------------------------------------------------------
@@ -485,6 +722,12 @@ export function getCaptionForImage(filename) {
         return "Wasserstein-1 (EMD) distance from each mesh to the reference. A monotone decrease toward the finest mesh indicates field-level convergence.";
     if (base === "EMD_stepwise")
         return "Stepwise EMD between consecutive meshes. Small, plateauing values on the finest pairs indicate the fingerprint has stopped changing.";
+    if (base === "KL_asymmetric")
+        return "Asymmetric pairwise mesh-fingerprint KL D_KL(P‖Q): above-diagonal cells are coarse→fine, below-diagonal are fine→coarse (meshes ordered coarse→fine). Use when SKL line plots hide directional disagreement.";
+    if (base === "divergence_kl")
+        return "Feature-plane symmetric KL heatmap (min-shift sum-normalized physical component planes). Measures association between SOM features — not mesh-vs-mesh fingerprint KL (see KL_ref / KL_asymmetric).";
+    if (base === "divergence_w1")
+        return "Feature-plane 1-Wasserstein heatmap on the same physical component-plane masses. Opt-in via barmesh_results(action=feature_divergences, metrics=[\"wasserstein\"]).";
     if (base === "plot_vol_all_meshes")
         return "Volume-weighted SOM fingerprints P_vol for every mesh in mesh_order (shared color scale).";
     if (base === "plot_vol_coarse_fine")

package/dist/tools/barmesh_results_explorer.js

@@ -1,9 +1,11 @@
 import { z } from "zod";
 import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
 import { runMcpToolAudit } from "../audit.js";
-import { apiCall, apiRawCall, getClientSupportsMcpApps, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
+import { apiCall, apiRawCall, BARMESH_VIZ_VIEWS, buildStandaloneVizPageUrl, buildVizRelatedUrls, getVizPort, getCaptionForImage, mimeForFilename, structuredTextResult, tryAttachImage, } from "../shared.js";
 import { FIGURE_SECTION_LABELS, FIGURE_SECTION_ORDER, figureSection, sortRank, } from "../figure_sections.js";
 import { buildMetadataStrip } from "../results_metadata.js";
+import { appendUiDeliveryContent, buildStandaloneVizUrl, resolveUiDelivery, } from "../ui-delivery.js";
+import { buildBarmeshVizStandaloneUrl } from "../viz_links.js";
 export const RESULTS_EXPLORER_URI = "ui://barmesh/results-explorer";
 export function sortFigures(figures) {
     return [...figures].sort((a, b) => FIGURE_SECTION_ORDER.indexOf(a.section ?? "diagnostics") -
@@ -38,6 +40,12 @@ function labelForFigure(filename) {
         return "Wasserstein (EMD) vs reference";
     if (base === "EMD_stepwise")
         return "Wasserstein (EMD) stepwise";
+    if (base === "KL_asymmetric")
+        return "Asymmetric mesh KL matrix (coarse↔fine)";
+    if (base === "divergence_kl")
+        return "Feature-plane symmetric KL (not mesh KL)";
+    if (base === "divergence_w1")
+        return "Feature-plane Wasserstein-1";
     if (base === "plot_vol_all_meshes")
         return "Volume fingerprint: all meshes";
     if (base === "plot_vol_coarse_fine")
@@ -111,6 +119,10 @@ export function buildPayload(jobId, data, jobMeta) {
     const files = (summary.files ?? []).filter((f) => /\.(png|pdf|svg)$/i.test(f));
     const figures = sortFigures(groupFigures(files));
     const port = getVizPort();
+    const standaloneUrl = buildStandaloneVizPageUrl(port, BARMESH_VIZ_VIEWS.resultsExplorer, jobId) ??
+        buildBarmeshVizStandaloneUrl("barmesh-results-explorer", jobId);
+    const trainingMonitorUrl = buildStandaloneVizPageUrl(port, BARMESH_VIZ_VIEWS.trainingMonitor, jobId) ??
+        buildBarmeshVizStandaloneUrl("barmesh-training-monitor", jobId);
     return {
         type: "barmesh-results-explorer",
         jobId,
@@ -120,9 +132,9 @@ export function buildPayload(jobId, data, jobMeta) {
         metrics: buildMetrics(summary),
         availableFigures: figures,
         defaultFigureKey: resolveDefaultFigureKey(figures),
-        standaloneUrl: port
-            ? `http://localhost:${port}/viz/barmesh-results-explorer?mode=standalone&job_id=${jobId}`
-            : undefined,
+        standaloneUrl,
+        trainingMonitorUrl,
+        relatedUrls: buildVizRelatedUrls(port, jobId, BARMESH_VIZ_VIEWS),
     };
 }
 async function handleResultsExplorer(job_id) {
@@ -131,40 +143,40 @@ async function handleResultsExplorer(job_id) {
         apiCall("GET", `/v1/jobs/${job_id}`).catch(() => ({})),
     ]);
     const payload = buildPayload(job_id, data, jobMeta);
-    const content = [
-        {
-            type: "text",
-            text: [
-                `Mesh convergence results explorer ready for job ${job_id}.`,
-                payload.subtitle ? `Label: ${payload.subtitle}` : "",
-                payload.metadataStrip?.[0] ?? "",
-            ]
-                .filter(Boolean)
-                .join("\n"),
-        },
-    ];
+    const summaryText = [
+        `Mesh convergence results explorer ready for job ${job_id}.`,
+        payload.subtitle ? `Label: ${payload.subtitle}` : "",
+        payload.metadataStrip?.[0] ?? "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const content = [{ type: "text", text: summaryText }];
+    let inlineImageAttached = false;
     const defaultFigure = payload.availableFigures.find((f) => f.key === payload.defaultFigureKey);
     if (defaultFigure && /\.(png|svg|jpe?g|webp)$/i.test(defaultFigure.filename)) {
+        const before = content.length;
         await tryAttachImage(content, job_id, defaultFigure.filename);
+        inlineImageAttached = content.length > before && content.some((c) => c.type === "image");
     }
-    if (payload.standaloneUrl) {
-        content.push({
-            type: "text",
-            text: `Standalone results explorer URL (copy if Open is blocked):\n${payload.standaloneUrl}\n` +
-                `AGENT: surface this URL to the user — markdown link or copy/paste into a browser when the inline MCP panel cannot open localhost. ` +
-                `This localhost port is per MCP session and goes stale if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
-        });
-    }
-    if (!getClientSupportsMcpApps() && payload.standaloneUrl) {
+    const uiDelivery = resolveUiDelivery({
+        tool: "results_explorer",
+        jobId: job_id,
+        jobStatus: "completed",
+        inlineImageAttached,
+    });
+    appendUiDeliveryContent(content, uiDelivery, {
+        linkLabel: "Open results explorer",
+        primaryUrl: payload.standaloneUrl ?? buildStandaloneVizUrl("results_explorer", job_id),
+    });
+    const monitorUrl = payload.trainingMonitorUrl ?? buildStandaloneVizUrl("training_monitor", job_id);
+    if (monitorUrl) {
         content.push({
             type: "text",
-            text: `Interactive results explorer: [Open results explorer](${payload.standaloneUrl})\n` +
-                `AGENT: surface this to the user as a clickable markdown link in your reply. ` +
-                `This localhost port is assigned per MCP session and changes if the proxy restarts — re-run barmesh_results_explorer for a fresh URL, or set BARIVIA_VIZ_PORT for a persistent port.`,
+            text: `Review training curves: [Open training monitor](${monitorUrl})`,
         });
     }
     return {
-        ...structuredTextResult(payload, undefined, content),
+        ...structuredTextResult({ ...payload, ui_delivery: uiDelivery }, undefined, content),
         _meta: { ui: { resourceUri: RESULTS_EXPLORER_URI } },
     };
 }

package/dist/tools/cfd.js

@@ -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,6 +49,10 @@ 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;
@@ -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,6 +90,10 @@ 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)