@showmeonmap/mcp 0.6.0 → 0.7.1

package/dist/tools.js

@@ -23,6 +23,11 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import { MCP_TOOL_META, mcpRequiresConfirmation } from "./toolMeta.js";
 import { buildAnalysisStory } from "./storyDraft.js";
+import { buildMapNextActions, instructionHints, MAX_NEXT_ACTIONS } from "./nextActions.js";
+import { fetchNoRedirect } from "./fetchNoRedirect.js";
+import { BUILD_MAP_DESCRIPTION, SERVER_INSTRUCTIONS } from "./serverInstructions.js";
+import { describeTolerance, generalizeLayers, storedBytes, WORKSPACE_CEILING } from "./generalizeGeometry.js";
+import { VIEWER_URI, VIEWER_TOOLS, VIEW_META_KEY, MCP_APP_MIME, viewerShellHtml, viewerResourceMeta, splitLayersByBudget, utf8Bytes, } from "./viewer.js";
 // -----------------------------------------------------------------------------
 // Agent-facing spec resource (Teddy Riker, "Designing for Agents" §2,
 // 2026-04-23). Loaded once at module init from a sibling .md file. Tool
@@ -58,6 +63,11 @@ const WORKSPACE_OPS_SPEC_TEXT = (() => {
 const MCP_RATIONALE_DIR = (() => {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
+        // Repo checkout only. Installed from npm, three levels up from dist/ is
+        // the user's own node_modules — the package must not write their tool
+        // rationales to disk there (found preparing 0.7.0; 0.6.0 did).
+        if (!/[\\/]packages[\\/]mcp-server[\\/](src|dist)$/.test(here) || /[\\/]node_modules[\\/]/.test(here))
+            return null;
         // tools.ts sits at packages/mcp-server/src/. Climb three levels
         // (src → mcp-server → packages → <repo>) to land at <repo>/reports/
         // mcp-rationale, alongside the agent-blockers sink and the
@@ -97,6 +107,56 @@ export function asSessionId(value) {
     }
     return value;
 }
+/** The map's geometry stays over WORKSPACE_CEILING even after generalization. */
+export class MapTooLargeError extends Error {
+    mapId;
+    bytes;
+    constructor(mapId, bytes, shareUrl) {
+        super(`This map is too large to keep in the conversation (${(bytes / 1e6).toFixed(1)} MB after simplifying its geometry). ` +
+            (shareUrl ? `Open it on ShowMeOnMap: ${shareUrl}` : 'Try a smaller area or fewer layers.'));
+        this.mapId = mapId;
+        this.bytes = bytes;
+        this.name = 'MapTooLargeError';
+    }
+}
+/**
+ * Generalize an entry's oversize inline layers (workspace ops + mapPlan) —
+ * see generalizeGeometry.ts. Idempotent: a generalized layer is marked and
+ * skipped next time.
+ */
+export function prepareEntry(entry) {
+    const ws = generalizeLayers(entry.workspace);
+    const mp = generalizeLayers(entry.mapPlan);
+    const seen = new Set();
+    const generalized = [...ws.generalized, ...mp.generalized].filter((g) => {
+        if (seen.has(g.layerId))
+            return false;
+        seen.add(g.layerId);
+        return true;
+    });
+    return { entry: { ...entry, workspace: ws.value, mapPlan: mp.value }, generalized };
+}
+/**
+ * Every write to the session store goes through here, so no call site can
+ * forget it: oversize line/polygon layers are generalized, and a workspace
+ * still over the ceiling is refused with a clear error instead of the raw
+ * D1 `SQLITE_TOOBIG` (one TEXT cell, 2 MB cap). The share link is named in
+ * the error only when it is known to exist.
+ */
+export function withGeneralization(inner, shareUrlFor = () => null) {
+    return {
+        get: (mapId) => inner.get(mapId),
+        delete: (mapId) => inner.delete(mapId),
+        size: () => inner.size(),
+        async put(mapId, entry) {
+            const prepared = prepareEntry(entry).entry;
+            const bytes = storedBytes(prepared.workspace);
+            if (bytes > WORKSPACE_CEILING)
+                throw new MapTooLargeError(mapId, bytes, shareUrlFor(mapId));
+            await inner.put(mapId, prepared);
+        },
+    };
+}
 export function createMemorySessionStore(maxSize = 256) {
     const cache = new Map();
     return {
@@ -186,7 +246,14 @@ function compactStructured(workspace, mapPlan) {
     }
     return compacted;
 }
-function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras = {}) {
+/** Tool-text honesty line for generalized layers, so Claude can say so. */
+function generalizedNote(generalized) {
+    if (!generalized.length)
+        return undefined;
+    const parts = generalized.map((g) => `${g.title ?? g.layerId} (${describeTolerance(g.toleranceDeg)})`);
+    return `Boundaries simplified to fit the conversation view: ${parts.join(', ')}. Data values are unchanged; the shareable link shows full detail until the map is edited.`;
+}
+function envelope(baseUrl, mapId, workspace, mapPlan, nextActions, extras = {}) {
     const layerCount = Array.isArray(mapPlan?.layers) ? mapPlan.layers.length : 0;
     const opsCount = Array.isArray(workspace?.opsLog) ? workspace.opsLog.length : 0;
     return {
@@ -202,10 +269,9 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
             layer_count: layerCount,
             last_updated: new Date().toISOString(),
         },
-        next_actions: (nextActionStrings ?? []).slice(0, 3).map((label) => ({
-            label,
-            argsTemplate: { instruction: label },
-        })),
+        next_actions: (nextActions ?? []).every((a) => typeof a === 'string')
+            ? instructionHints(nextActions)
+            : nextActions.slice(0, MAX_NEXT_ACTIONS),
         ...(extras.outOfScope ? { outOfScope: extras.outOfScope } : {}),
         ...(extras.clarification ? { clarification: extras.clarification } : {}),
         ...(extras.opsApplied ? { opsApplied: extras.opsApplied } : {}),
@@ -214,6 +280,7 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
         ...(extras.memo ? { memo: extras.memo } : {}),
         ...(extras.stats ? { stats: extras.stats } : {}),
         ...(extras.note ? { note: extras.note } : {}),
+        ...(extras.batch ? { batch: extras.batch } : {}),
     };
 }
 function toContent(obj) {
@@ -240,32 +307,37 @@ function toContent(obj) {
 // envelope (isError:true + content[].text JSON) so the calling agent can
 // self-correct.
 // ---------------------------------------------------------------------------
+// `rationale` (≤300 chars) is OPTIONAL on every tool — appended once in
+// invalidInputEnvelope rather than repeated per tool.
 const INVALID_INPUT_HINTS = {
-    build_map: 'Required: query (string, ≥1 char), rationale (string, 1–300 chars). No other fields accepted.',
-    mutate_map: 'Required: map_id, instruction, rationale. No other fields accepted.',
-    get_state: 'Required: map_id, rationale. No other fields accepted.',
-    add_layer: 'Required: map_id, layerPlan (object), rationale. Optional: intent (enum). No other fields accepted.',
-    filter_layer: 'Required: map_id, layerId, predicate (object), rationale. Optional: append (boolean), intent (enum).',
-    select_within: 'Required: map_id, sourceLayerId, newLayerId, selection ({type:Polygon|MultiPolygon, coordinates}), rationale. Optional: inheritStyle.',
-    focus_area: 'Required: map_id, layerId, areaRef ({kind:"corridor", street, from?, to?} | {kind:"place", name} | {kind:"aroundIntersection", street, cross}), rationale. Optional: mode (filter|select|clip). Pass NAMES — the server resolves geometry from OSM.',
-    query_features: 'Required: map_id, layerId, predicate (object), rationale. Optional: limit (1–1000 integer).',
-    remove_layer: 'Required: map_id, layerId, rationale, confirmed:true (destructive — layer ids are tombstoned).',
-    clear_filters: 'Required: map_id, layerId, rationale, confirmed:true (sensitive — autonomous filter wipe).',
-    rename_layer: 'Required: map_id, oldLayerId, newLayerId, rationale.',
-    restyle_layer: 'Required: map_id, layerId, rationale. Optional: color (string), opacity (0–1).',
-    set_camera: 'Required: map_id, camera (mode:fitBounds|flyTo with required fields), rationale.',
-    set_time: 'Required: map_id, field, rangeStart (number), rangeEnd (number), rationale. Optional: format (unix_ms|iso|integer).',
-    tag: 'Required: map_id, name, rationale.',
-    add_annotation: 'Required: map_id, id, coords ([lng,lat]), rationale. Optional: label, color.',
-    remove_annotation: 'Required: map_id, annotationId, rationale.',
-    export_workspace: 'Required: map_id, rationale.',
-    export_layer_data: 'Required: map_id, layer_id, rationale, format ("csv" or "geojson"). No other fields accepted.',
-    export_image: 'Required: map_id, rationale. Optional: format ("png" default | "jpeg" | "pdf"), legend (boolean default true). No other fields accepted.',
-    add_fusion_layer: 'Required: map_id, layer_a_id, layer_b_id, rationale. Optional: value_field_a, value_field_b, new_layer_id. Mode is locked to "bivariate" in v1. No other fields accepted.',
-    correlate_layers: 'Required: map_id, layer_a_id, layer_b_id, rationale. Optional: value_field_a, value_field_b. Pure read — no layer added, no credit charged. No other fields accepted.',
-    undo: 'Required: map_id, rationale, confirmed:true (sensitive — autonomous undo can erase prior work).',
-    redo: 'Required: map_id, rationale.',
-    report_blocker: 'Required: what_i_was_trying, what_i_tried, where_i_got_stuck, rationale. Optional: map_id, suggested_capability.',
+    build_map: 'Required: query (string, ≥1 char). No other fields accepted.',
+    mutate_map: 'Required: map_id, instruction. No other fields accepted.',
+    get_state: 'Required: map_id. No other fields accepted.',
+    add_layer: 'Required: map_id, layerPlan (object). Optional: intent (enum). No other fields accepted.',
+    filter_layer: 'Required: map_id, layerId, predicate (object). Optional: append (boolean), intent (enum).',
+    select_within: 'Required: map_id, sourceLayerId, newLayerId, selection ({type:Polygon|MultiPolygon, coordinates}). Optional: inheritStyle.',
+    focus_area: 'Required: map_id, layerId, areaRef ({kind:"corridor", street, from?, to?} | {kind:"place", name} | {kind:"aroundIntersection", street, cross}). Optional: mode (filter|select|clip). Pass NAMES — the server resolves geometry from OSM.',
+    query_features: 'Required: map_id, layerId, predicate (object). Optional: limit (1–1000 integer).',
+    save_workflow: 'Required: name, steps (1–12 {instruction} objects). Optional: params (declared {slot}s). Every {slot} used in steps must be declared.',
+    list_workflows: 'No required fields. No other fields accepted.',
+    run_workflow: 'Required: workflow_id. Optional: params (values for declared parameters), batch ({param, values[2..20]} — sweeps one param, bills steps × values).',
+    remove_layer: 'Required: map_id, layerId, confirmed:true (destructive — layer ids are tombstoned).',
+    clear_filters: 'Required: map_id, layerId, confirmed:true (sensitive — autonomous filter wipe).',
+    rename_layer: 'Required: map_id, oldLayerId, newLayerId.',
+    restyle_layer: 'Required: map_id, layerId. Optional: color (string), opacity (0–1).',
+    set_camera: 'Required: map_id, camera (mode:fitBounds|flyTo with required fields).',
+    set_time: 'Required: map_id, field, rangeStart (number), rangeEnd (number). Optional: format (unix_ms|iso|integer).',
+    tag: 'Required: map_id, name.',
+    add_annotation: 'Required: map_id, id, coords ([lng,lat]). Optional: label, color.',
+    remove_annotation: 'Required: map_id, annotationId.',
+    export_workspace: 'Required: map_id.',
+    export_layer_data: 'Required: map_id, layer_id, format ("csv" or "geojson"). No other fields accepted.',
+    export_image: 'Required: map_id. Optional: format ("png" default | "jpeg" | "pdf"), legend (boolean default true). No other fields accepted.',
+    add_fusion_layer: 'Required: map_id, layer_a_id, layer_b_id. Optional: value_field_a, value_field_b, new_layer_id. Mode is locked to "bivariate" in v1. No other fields accepted.',
+    correlate_layers: 'Required: map_id, layer_a_id, layer_b_id. Optional: value_field_a, value_field_b. Pure read — no layer added, no credit charged. No other fields accepted.',
+    undo: 'Required: map_id, confirmed:true (sensitive — autonomous undo can erase prior work).',
+    redo: 'Required: map_id.',
+    report_blocker: 'Required: what_i_was_trying, what_i_tried, where_i_got_stuck. Optional: map_id, suggested_capability.',
 };
 function buildInvalidInputResponse(toolName, error) {
     const issues = error.issues.map((iss) => ({
@@ -277,7 +349,7 @@ function buildInvalidInputResponse(toolName, error) {
         error: 'invalid_input',
         tool: toolName,
         issues,
-        hint: INVALID_INPUT_HINTS[toolName] ?? 'Check the tool schema and remove unknown keys.',
+        hint: `${INVALID_INPUT_HINTS[toolName] ?? 'Check the tool schema and remove unknown keys.'} Optional on every tool: rationale (≤300 chars).`,
     };
     return {
         isError: true,
@@ -350,8 +422,32 @@ function withConfirmation(toolName, handler) {
         return handler(rest, extra);
     });
 }
+/**
+ * The error text a failed backend call hands the calling model.
+ *
+ * Live failure (2026-10-12): a build_map came back as Cloudflare's edge error
+ * page (the Worker died before our own handler could answer), and the first
+ * 200 characters of that HTML — `<!DOCTYPE html><!--[if lt IE 7]>…` — were all
+ * the model saw: no error code, no Ray ID to find the request in Workers Logs,
+ * no hint that one retry is the right move. An HTML body is never ours, so say
+ * what it is and keep the two identifiers worth having.
+ */
+export function describeErrorBody(text) {
+    if (!/^\s*(<!DOCTYPE html|<html)/i.test(text))
+        return text.slice(0, 200);
+    const code = text.match(/cf-error-code[^>]*>\s*(\d+)\s*</i)?.[1];
+    const ray = text.match(/Ray ID:?\s*(?:<[^>]+>\s*)*([0-9a-f]{12,})/i)?.[1];
+    const title = text.match(/<title>\s*([^<|]+?)\s*(?:\||<\/title>)/i)?.[1];
+    const parts = [
+        'upstream error page, not a ShowMeOnMap response',
+        code ? `Cloudflare error ${code}` : null,
+        title ?? null,
+        ray ? `Ray ID ${ray}` : null,
+    ].filter(Boolean);
+    return `${parts.join(' · ')}. Transient — retry once.`;
+}
 async function apiFetch(baseUrl, apiKey, path, body) {
-    const resp = await fetch(`${baseUrl}${path}`, {
+    const resp = await fetchNoRedirect(`${baseUrl}${path}`, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -366,7 +462,7 @@ async function apiFetch(baseUrl, apiKey, path, body) {
     // success (one of four parallel build_map calls lost its map this way,
     // 2026-08-01).
     if (!resp.ok) {
-        throw new Error(`${path} ${resp.status}: ${text.slice(0, 200)}`);
+        throw new Error(`${path} ${resp.status}: ${describeErrorBody(text)}`);
     }
     try {
         return JSON.parse(text);
@@ -398,7 +494,11 @@ async function apiFetch(baseUrl, apiKey, path, body) {
 // own viz reads.
 const SHARE_MAX_VERTICES_PER_RING = 60;
 const SHARE_MAX_POLYS_PER_MULTI = 3;
-const SHARE_MAX_FEATURES_PER_LAYER = 2000;
+// Mirrors saveMapSnapshot: a byte budget for the whole geojsonLayers
+// sidecar replaces the old first-2000-features cut, which shared a
+// row-ordered analysis grid as a strip of the city (audited 2026-10-13).
+const SHARE_MAX_FEATURES_PER_LAYER = 20_000;
+export const SHARE_GEOJSON_BUDGET_BYTES = 4_000_000;
 const SHARE_BASE_KEEP_PROPS = new Set(['value', 'name', 'iso3', 'label', '_dataVintage']);
 function roundCoord(n) {
     return Math.round(n * 10_000) / 10_000;
@@ -442,39 +542,144 @@ function compactGeometry(geom) {
     }
     return geom;
 }
-/** Base whitelist + every field name the layer's viz reads + `_smo_*`
- *  internals (tooltip/popup dispatch). Exported for tests. */
-export function compactFeatureCollection(fc, viz) {
-    const keep = new Set(SHARE_BASE_KEEP_PROPS);
-    for (const [k, v] of Object.entries(viz ?? {})) {
-        if (typeof v === 'string' && /(Field|^field[A-Z])/.test(k))
-            keep.add(v);
+/** A key that names a feature property: `field`, `valueField`, `fieldX`, … */
+const SHARE_FIELD_KEY = /^field$|Field$|^field[A-Z]/;
+/** Every feature property `node` reads: string values under field-named
+ *  keys at ANY depth, plus `["get", X]` expression refs. Mirrors
+ *  `keepSetForLayer` in src/lib/share/saveMapSnapshot.ts — a top-level-only
+ *  scan stripped the nested `viz.colorScale.field`, so shared opportunity
+ *  grids painted every cell the lowest class (2026-10-13). */
+export function collectReadFields(node, out = new Set()) {
+    if (Array.isArray(node)) {
+        if (node[0] === 'get' && typeof node[1] === 'string')
+            out.add(node[1]);
+        for (const item of node)
+            collectReadFields(item, out);
+        return out;
+    }
+    if (!node || typeof node !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === 'string') {
+            if (SHARE_FIELD_KEY.test(k))
+                out.add(v);
+        }
+        else {
+            collectReadFields(v, out);
+        }
+    }
+    return out;
+}
+/** `n` of `items` by a seeded shuffle, returned in original order —
+ *  deterministic, spread over the whole extent, no stride moiré. Mirrors
+ *  `sampleSpread` in src/lib/share/saveMapSnapshot.ts. */
+export function sampleSpread(items, n) {
+    if (items.length <= n)
+        return [...items];
+    if (n <= 0)
+        return [];
+    const idx = Array.from(items, (_, i) => i);
+    let seed = (items.length * 2654435761) >>> 0;
+    const rand = () => {
+        // mulberry32
+        seed = (seed + 0x6d2b79f5) >>> 0;
+        let t = seed;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    for (let i = 0; i < n; i++) {
+        const j = i + Math.floor(rand() * (idx.length - i));
+        [idx[i], idx[j]] = [idx[j], idx[i]];
     }
-    const features = (fc.features ?? []).slice(0, SHARE_MAX_FEATURES_PER_LAYER).map((f) => ({
+    return idx.slice(0, n).sort((x, y) => x - y).map((i) => items[i]);
+}
+/** Base whitelist + every field the layer reads + `_smo_*` internals
+ *  (tooltip/popup dispatch). `reads` is the layer minus its source (or just
+ *  its viz) — walked at any depth. Exported for tests. */
+export function compactFeatureCollection(fc, reads, 
+/** Fields the layer's filter reads — /api/maps applies it after this strip. */
+filterFields = []) {
+    const keep = collectReadFields(reads, new Set([...SHARE_BASE_KEEP_PROPS, ...filterFields]));
+    const features = sampleSpread(fc.features ?? [], SHARE_MAX_FEATURES_PER_LAYER).map((f) => ({
         ...f,
         geometry: compactGeometry(f.geometry),
         properties: Object.fromEntries(Object.entries(f.properties ?? {}).filter(([k]) => keep.has(k) || k.startsWith('_smo_'))),
     }));
     return { type: fc.type ?? 'FeatureCollection', features };
 }
-async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query, story) {
+/** Shrink every compacted layer by one factor when the sidecar is over
+ *  budget, sampled spread; returns `{kept,total}` for each layer the share
+ *  carries only partly. Exported for tests. */
+export function budgetShareLayers(compacted, totals, budgetBytes = SHARE_GEOJSON_BUDGET_BYTES) {
+    const bytes = JSON.stringify(compacted).length;
+    const scale = bytes > budgetBytes ? budgetBytes / bytes : 1;
+    const sampled = {};
+    for (const [id, fc] of Object.entries(compacted)) {
+        if (scale < 1)
+            fc.features = sampleSpread(fc.features, Math.floor(fc.features.length * scale));
+        if (fc.features.length < (totals[id] ?? 0))
+            sampled[id] = { kept: fc.features.length, total: totals[id] };
+    }
+    return sampled;
+}
+/** Every `field` a predicate tree reads (attribute/temporal leaves). */
+export function predicateFields(predicate, out = []) {
+    if (Array.isArray(predicate)) {
+        for (const p of predicate)
+            predicateFields(p, out);
+    }
+    else if (predicate && typeof predicate === 'object') {
+        for (const [k, v] of Object.entries(predicate)) {
+            if (k === 'field' && typeof v === 'string')
+                out.push(v);
+            else if (v && typeof v === 'object')
+                predicateFields(v, out);
+        }
+    }
+    return out;
+}
+async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, queryOrLabel, story, 
+// The workspace's filters (materialize keeps them beside the plan). Sent so
+// /api/maps stores only the features the map shows — without them the
+// share link held every feature after filter_layer (2026-10-09).
+layerFilters) {
     if (!mapPlan || !Array.isArray(mapPlan.layers))
         return false;
+    // Callers pass the build query, or an edit's optional rationale label.
+    const query = queryOrLabel || mapPlan.title || 'Map';
     const geojsonLayers = {};
+    const totals = {};
+    const temporalField = mapPlan.temporalHint?.field;
     const strippedLayers = mapPlan.layers.map((raw) => {
         const layer = raw;
         if (layer?.source?.kind === 'geojson' && layer.source.data && layer.id) {
-            geojsonLayers[layer.id] = compactFeatureCollection(layer.source.data, layer.viz);
+            const data = layer.source.data;
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars -- source carries the data, not field references
+            const { source: _source, ...reads } = layer;
+            totals[layer.id] = data.features?.length ?? 0;
+            geojsonLayers[layer.id] = compactFeatureCollection(data, reads, [...predicateFields(layerFilters?.[layer.id]), ...(typeof temporalField === 'string' ? [temporalField] : [])]);
             return { ...layer, source: { ...layer.source, data: undefined } };
         }
         return layer;
     });
+    // Budget the sidecar; /m/ reads `sampledLayers` and tells the viewer the
+    // copy is a sample — a partial map must never pass as the whole one.
+    const sampled = budgetShareLayers(geojsonLayers, totals);
     const title = mapPlan.title ?? mapPlan.layers[0]?.title ?? 'Untitled Map';
     const body = {
         id: mapId,
         title,
         query,
-        blob: { mapPlan: { ...mapPlan, layers: strippedLayers }, geojsonLayers, query, version: 1, ...(story ? { story } : {}) },
+        blob: {
+            mapPlan: { ...mapPlan, layers: strippedLayers },
+            geojsonLayers,
+            ...(Object.keys(sampled).length ? { sampledLayers: sampled } : {}),
+            query,
+            version: 1,
+            ...(story ? { story } : {}),
+            ...(layerFilters && Object.keys(layerFilters).length ? { layerFilters } : {}),
+        },
         isPublic: true,
     };
     // Two attempts: the second exists for exactly the failure that lost a map
@@ -497,14 +702,79 @@ async function persistShareableMap(baseUrl, apiKey, mapId, mapPlan, query, story
     }
     return false;
 }
+/** Safe map id: workspace UUIDs, nanoid /m/ ids, `ws_…` test ids. Rejects
+ *  path segments (`..`, `a/b`) before the id reaches a URL. */
+const MAP_ID_RE = /^[A-Za-z0-9_-]{1,128}$/;
+/** `cursor` and `op_id` pin a version together — exactly one is ambiguous. */
+const pinPairSchema = z
+    .object({ cursor: z.number().optional(), op_id: z.string().optional() })
+    .refine((v) => (v.cursor === undefined) === (v.op_id === undefined), {
+    message: 'cursor and op_id must be given together (a version is the pair), or both omitted for the latest',
+    path: ['op_id'],
+});
+/** Headroom under MAX_STRUCTURED_BYTES for the view envelope (title, camera,
+ *  legend, stripped layer stubs, the text summary, JSON-RPC framing). */
+const VIEW_ENVELOPE_HEADROOM = 50_000;
+/**
+ * A non-owner's (or LRU-evicted session's) view: the public /m/ snapshot,
+ * always the latest version. Deliberately NOT apiFetch — that attaches the
+ * caller's bearer, and a public read must not depend on it. Mirrors
+ * `hydrateSharedPlan` (src/lib/share/saveMapSnapshot.ts), which this package
+ * cannot import: a geojson layer with no inline data gets
+ * `blob.geojsonLayers[layer.id]`, top level and both comparison panes.
+ *
+ * NB: GET /api/maps/[id] answers a private map with 404 (it hides existence),
+ * so today a private map reads as `deleted`; 401/403 → `private` is kept for
+ * the day the route distinguishes them.
+ */
+async function fetchPublicSnapshot(baseUrl, mapId) {
+    const path = `/api/maps/${encodeURIComponent(mapId)}`;
+    // X-SMO-No-View-Count: a card load is not a /m/ page view — the route
+    // skips incrementViews for it.
+    const resp = await fetchNoRedirect(`${baseUrl}${path}`, {
+        headers: { Accept: 'application/json', 'X-SMO-No-View-Count': '1' },
+    });
+    if (resp.status === 401 || resp.status === 403)
+        return { status: 'private', plan: null };
+    if (resp.status === 404)
+        return { status: 'deleted', plan: null };
+    const text = await resp.text();
+    if (!resp.ok)
+        throw new Error(`${path} ${resp.status}: ${describeErrorBody(text)}`);
+    const body = JSON.parse(text);
+    const plan = body.blob?.mapPlan;
+    if (!plan)
+        throw new Error(`${path} returned no mapPlan`);
+    const geo = body.blob?.geojsonLayers ?? {};
+    const hydrate = (l) => l.source?.kind === 'geojson' && !l.source.data && geo[l.id] ? { ...l, source: { ...l.source, data: geo[l.id] } } : l;
+    return {
+        status: 'public_snapshot',
+        plan: {
+            ...plan,
+            layers: (plan.layers ?? []).map(hydrate),
+            ...(plan.comparison
+                ? {
+                    comparison: {
+                        left: { ...plan.comparison.left, layers: plan.comparison.left.layers.map(hydrate) },
+                        right: { ...plan.comparison.right, layers: plan.comparison.right.layers.map(hydrate) },
+                    },
+                }
+                : {}),
+        },
+    };
+}
 // MCP tool annotations — safety hints every tool advertises so clients can
 // reason about read-only vs mutating vs destructive behavior (and the model
 // picks tools correctly). `destructiveHint` derives from MCP_TOOL_META (the
 // single source of truth, kept in sync with the agent-side meta); the rest
 // from a small intent classification.
+// report_blocker is deliberately NOT here: it sends agent-written text to the
+// SMO team, so a host should ask before running it rather than auto-approve it
+// as a read (Claude auto-runs readOnlyHint tools; directory review checks this).
 const READ_ONLY_TOOLS = new Set([
     'get_state', 'query_features', 'select_within', 'correlate_layers',
-    'export_workspace', 'export_layer_data', 'export_image', 'report_blocker',
+    'export_workspace', 'export_layer_data', 'export_image', 'list_workflows',
+    'get_map_view',
 ]);
 // Tools that reach external/open-world data sources, vs operating purely on
 // already-loaded workspace state.
@@ -527,16 +797,72 @@ function toolAnnotations(name) {
 export function createServer(opts) {
     const baseUrl = opts.baseUrl;
     const apiKey = opts.apiKey;
-    const store = opts.sessionStore ?? createMemorySessionStore();
+    // Maps whose /m/ share was confirmed written — the only links a
+    // too-large error may hand out (share-store honesty, 2026-08-01).
+    const sharedMapIds = new Set();
+    const store = withGeneralization(opts.sessionStore ?? createMemorySessionStore(), (mapId) => (sharedMapIds.has(mapId) ? `${baseUrl}/m/${mapId}` : null));
+    const viewer = opts.viewer;
     const server = new McpServer({
         name: opts.name ?? 'showmeonmap',
         version: opts.version ?? '0.1.0',
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     // Stamp MCP annotations onto every tool from the central classification so we
     // don't thread them through 24 registerTool call sites. `title` mirrors the
     // tool's own title; any inline annotations a call sets win over the defaults.
+    //
+    // With `viewer` set, map-producing tools (VIEWER_TOOLS) are also tagged with
+    // the MCP App resource (`ui.resourceUri` + the legacy flat `ui/resourceUri`
+    // key) and their results gain a hidden view pointer under `_meta`.
+    //
+    // Also with `viewer` set, every tool except the app-only `get_map_view` is
+    // stamped `_meta.ui.visibility: ['model']`. ext-apps defaults visibility to
+    // ["model","app"], which would let the card call credit-spending or
+    // mutating tools through the host; the card's one tool is get_map_view.
+    // Without `viewer` nothing changes (stdio / npm builds).
     const baseRegisterTool = server.registerTool.bind(server);
-    const registerTool = (name, config, cb) => baseRegisterTool(name, { ...config, annotations: { title: config.title, ...toolAnnotations(name), ...config.annotations } }, cb);
+    const registerTool = (name, config, cb) => {
+        const tagged = !!viewer && VIEWER_TOOLS.has(name);
+        const existingUi = (config._meta?.ui ?? {});
+        const ui = {
+            ...existingUi,
+            ...(tagged ? { resourceUri: VIEWER_URI } : {}),
+            ...(viewer && name !== 'get_map_view' ? { visibility: ['model'] } : {}),
+        };
+        const cfg = {
+            ...config,
+            annotations: { title: config.title, ...toolAnnotations(name), ...config.annotations },
+            ...(viewer ? { _meta: { ...config._meta, ui, ...(tagged ? { 'ui/resourceUri': VIEWER_URI } : {}) } } : {}),
+        };
+        if (!tagged)
+            return baseRegisterTool(name, cfg, cb);
+        const wrapped = (async (...args) => {
+            const result = await cb(...args);
+            return attachViewPointer(result);
+        });
+        return baseRegisterTool(name, cfg, wrapped);
+    };
+    /** Read map_id from the envelope text, then cursor/opId from the store the
+     *  tool just wrote — authoritative even when the envelope was truncated. */
+    async function attachViewPointer(result) {
+        if (result?.isError)
+            return result;
+        try {
+            const text = result.content?.[0]?.text;
+            const mapId = text ? JSON.parse(text).map_id : undefined;
+            if (!mapId)
+                return result;
+            const entry = await store.get(mapId);
+            const ws = entry?.workspace;
+            const cursor = ws?.cursor;
+            const opId = typeof cursor === 'number' ? ws?.opsLog?.[cursor]?.opId : undefined;
+            if (typeof cursor !== 'number' || !opId)
+                return result;
+            return { ...result, _meta: { ...result._meta, [VIEW_META_KEY]: { map_id: mapId, cursor, opId } } };
+        }
+        catch {
+            return result; // a pointer failure must never fail the map-producing call
+        }
+    }
     // -------------------------------------------------------------------------
     // Resource: workspace-ops-spec
     // -------------------------------------------------------------------------
@@ -558,6 +884,139 @@ export function createServer(opts) {
         ],
     }));
     // -------------------------------------------------------------------------
+    // Resource: MCP App map viewer (only when `viewer` is configured)
+    // -------------------------------------------------------------------------
+    // A tiny HTML shell that loads the hashed viewer bundle from assetOrigin.
+    // `_meta.ui.domain` is deliberately never set — Claude derives the sandbox
+    // origin itself and the app's CORS matches it.
+    if (viewer) {
+        server.registerResource('map-viewer', VIEWER_URI, { title: 'ShowMeOnMap map viewer', description: 'Interactive map card for ShowMeOnMap results.', mimeType: MCP_APP_MIME }, async (uri) => ({
+            contents: [{ uri: uri.href, mimeType: MCP_APP_MIME, text: viewerShellHtml(viewer.assetOrigin), _meta: viewerResourceMeta(viewer) }],
+        }));
+        // -----------------------------------------------------------------------
+        // Tool: get_map_view — app-only (hidden from the model), read-only, free.
+        // The card loads a pinned version `(cursor, opId)`. Owner → from the
+        // owner-scoped session store; anyone else → the public /m/ snapshot.
+        //
+        // Budget: the view rides ONLY in `structuredContent` (what the card reads);
+        // `content[0].text` is a short summary. Duplicating the view into the text
+        // would double the result (plus JSON-escaping) and halve the usable layer
+        // budget. Layer data gets MAX_STRUCTURED_BYTES − VIEW_ENVELOPE_HEADROOM
+        // (UTF-8 bytes); a final guard re-measures the whole result.
+        // -----------------------------------------------------------------------
+        const getMapViewShape = {
+            map_id: z.string().regex(MAP_ID_RE),
+            cursor: z.number().int().min(0).optional(),
+            op_id: z.string().min(1).optional(),
+            layer_ids: z.array(z.string().min(1)).max(50).optional(),
+        };
+        registerTool('get_map_view', {
+            title: 'Map view (viewer only)',
+            description: 'Used by the ShowMeOnMap map card to load a map version. Not for the model.',
+            inputSchema: getMapViewShape,
+            _meta: { ui: { visibility: ['app'] } },
+        }, withValidation('get_map_view', getMapViewShape, async ({ map_id, cursor, op_id, layer_ids }) => {
+            const pair = pinPairSchema.safeParse({ cursor, op_id });
+            // Same invalid_input envelope withValidation produces (same cast too).
+            if (!pair.success)
+                return buildInvalidInputResponse('get_map_view', pair.error);
+            const entry = await store.get(map_id);
+            let status = 'ok';
+            let plan = null;
+            let latest = null;
+            let extras = { layerFilters: {} };
+            if (entry) {
+                const ws = entry.workspace;
+                const headOpId = ws.opsLog[ws.cursor]?.opId;
+                latest = typeof headOpId === 'string' ? { map_id, cursor: ws.cursor, opId: headOpId } : null;
+                const pinned = typeof cursor === 'number' && typeof op_id === 'string';
+                const pinOk = pinned && ws.opsLog[cursor]?.opId === op_id;
+                if (pinned && !pinOk)
+                    status = 'replaced';
+                // ALWAYS materialize (free, pure): filters, time window and
+                // annotations live beside mapPlan, and the stored entry.mapPlan
+                // alone would draw a filter/set_time/annotation card wrong (R14).
+                const resp = (await apiFetch(baseUrl, apiKey, '/api/workspace/materialize', {
+                    workspace: { ...ws, cursor: pinOk ? cursor : ws.cursor },
+                }));
+                // A failed materialize is an error, never `ok` with no plan.
+                if (!resp.ok || !resp.mapPlan) {
+                    throw new Error(`materialize failed: ${resp.error?.kind ?? 'unknown'} — ${resp.error?.message ?? 'no detail'}`);
+                }
+                plan = resp.mapPlan;
+                extras = {
+                    layerFilters: resp.layerFilters ?? {},
+                    ...(resp.timeOverride ? { timeOverride: resp.timeOverride } : {}),
+                    ...(resp.annotations ? { annotations: resp.annotations } : {}),
+                };
+            }
+            else {
+                const snap = await fetchPublicSnapshot(baseUrl, map_id);
+                status = snap.status;
+                plan = snap.plan;
+            }
+            let layers = plan?.layers ?? [];
+            if (layer_ids?.length)
+                layers = layers.filter((l) => layer_ids.includes(l.id));
+            // Filters / time window / annotations ride in the same result, so
+            // they come out of the layer budget (the final guard re-measures).
+            const extrasBytes = utf8Bytes(JSON.stringify(extras));
+            const split = splitLayersByBudget(layers, Math.max(0, MAX_STRUCTURED_BYTES - VIEW_ENVELOPE_HEADROOM - extrasBytes));
+            const view = {
+                status,
+                viewSchema: 1,
+                title: plan?.title ?? 'Map',
+                mapPlan: plan ? { ...plan, layers: split.inline } : null,
+                deferredLayerIds: split.deferred,
+                oversizeLayerIds: split.oversize,
+                latest,
+                ...extras,
+            };
+            const toResult = () => ({
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            status: view.status,
+                            title: view.title,
+                            layers: view.mapPlan?.layers.length ?? 0,
+                            deferred: view.deferredLayerIds.length,
+                            oversize: view.oversizeLayerIds.length,
+                        }),
+                    }],
+                structuredContent: view,
+            });
+            const fits = () => utf8Bytes(JSON.stringify(toResult())) < MAX_STRUCTURED_BYTES;
+            // Final guard — the envelope outgrew the headroom (e.g. a comparison
+            // plan's pane data, which the split does not see). Degrade honestly:
+            // strip pane data (undeliverable in the card → oversize), then all
+            // top-level data (deferred → fetchable one by one), then fail.
+            if (!fits() && view.mapPlan?.comparison) {
+                const c = view.mapPlan.comparison;
+                const stripPane = (ls) => ls.map((l) => {
+                    if (!l.source?.data)
+                        return l;
+                    view.oversizeLayerIds.push(l.id);
+                    return { ...l, source: { ...l.source, data: undefined } };
+                });
+                view.mapPlan = { ...view.mapPlan, comparison: { left: { ...c.left, layers: stripPane(c.left.layers) }, right: { ...c.right, layers: stripPane(c.right.layers) } } };
+            }
+            if (!fits() && view.mapPlan) {
+                view.mapPlan = {
+                    ...view.mapPlan,
+                    layers: view.mapPlan.layers.map((l) => {
+                        if (!l.source?.data)
+                            return l;
+                        view.deferredLayerIds.push(l.id);
+                        return { ...l, source: { ...l.source, data: undefined } };
+                    }),
+                };
+            }
+            if (!fits())
+                throw new Error(`map view for ${map_id} exceeds the ${MAX_STRUCTURED_BYTES}-byte result budget even without layer data`);
+            return toResult();
+        }));
+    }
+    // -------------------------------------------------------------------------
     // Shared `rationale` schema + stderr logger.
     // ---------------------------------------------------------------------------
     // Required on every MCP tool per Teddy Riker's "Designing for Agents"
@@ -568,7 +1027,8 @@ export function createServer(opts) {
         .string()
         .min(1)
         .max(300)
-        .describe('Short audit-log label (≤300 chars) stating the user-facing goal this call serves, e.g. "add wildfire layer for the user\'s California query". Required on every call. Stored in the operations log so map edits stay traceable — we never see your chat history.');
+        .optional()
+        .describe('Optional short label (≤300 chars) for the map edit history, e.g. "add wildfire layer". Omit it to send nothing beyond the tool arguments.');
     /**
      * Log a tool call's rationale (and any op-shaped extras) to BOTH stderr
      * and the per-day NDJSON sink. Every tool calls this — direct-op tools
@@ -580,6 +1040,10 @@ export function createServer(opts) {
      * `extra.opKind` lands in the NDJSON when this call emits a typed Op.
      */
     function logRationale(toolName, mapId, rationale, extra) {
+        // Optional since 2026-09-28 (Claude directory: collect nothing beyond what
+        // the tool needs) — no label, nothing logged.
+        if (!rationale)
+            return;
         const safe = rationale.replace(/[\r\n\t]+/g, ' ').slice(0, 300);
         process.stderr.write(`[mcp:rationale] tool=${toolName} mapId=${mapId ?? '-'} rationale="${safe}"${extra?.intent ? ` intent=${extra.intent}` : ''}${extra?.opKind ? ` op=${extra.opKind}` : ''}\n`);
         appendRationaleNdjson({
@@ -600,8 +1064,7 @@ export function createServer(opts) {
     };
     registerTool('build_map', {
         title: 'Build a map',
-        description: 'Create a new workspace from a natural-language query. Returns a map_id you can pass to mutate_map or get_state for follow-up actions. ' +
-            'For the full Op catalog and predicate grammar that downstream tools (mutate_map, filter_layer, etc.) accept, fetch the MCP resource at showmeonmap://docs/workspace-ops-spec — do NOT guess the shapes.',
+        description: BUILD_MAP_DESCRIPTION,
         inputSchema: buildMapShape,
     }, withValidation('build_map', buildMapShape, async ({ query, rationale }) => {
         logRationale('build_map', null, rationale);
@@ -614,21 +1077,26 @@ export function createServer(opts) {
             throw new Error(`build_map failed: ${JSON.stringify(resp.error ?? resp.message ?? resp).slice(0, 300)}`);
         }
         const mapId = asSessionId(resp.workspace.workspaceId ?? randomUUID());
-        await store.put(mapId, {
+        // Share FIRST, from the API's full-resolution plan: if the session
+        // write is then refused as too large, the error can still hand out a
+        // link that works.
+        const shared = await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, query);
+        if (shared)
+            sharedMapIds.add(mapId);
+        const prepared = prepareEntry({
             workspace: resp.workspace,
             mapPlan: resp.mapPlan ?? null,
             layerFilters: {},
             createdAt: Date.now(),
             lastAccessed: Date.now(),
         });
-        const nextActions = [
-            'Filter the layer to features where name is not empty',
-            'Change the basemap to satellite',
-            'Zoom the camera closer',
-        ];
-        // Persist to the shareable store so the returned /m/<mapId> link renders.
-        const shared = await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, query);
-        return toContent(envelope(baseUrl, mapId, resp.workspace, resp.mapPlan, nextActions, shared ? {} : { shareUnpersisted: true }));
+        await store.put(mapId, prepared.entry);
+        // Derived from THIS map: its fields, its basemap/camera, its own
+        // followups — computed on the full-resolution API plan (features
+        // inline), never the generalized stored copy. May be [] (nextActions.ts).
+        const nextActions = buildMapNextActions(resp.mapPlan, query);
+        const note = generalizedNote(prepared.generalized);
+        return toContent(envelope(baseUrl, mapId, prepared.entry.workspace, prepared.entry.mapPlan, nextActions, { ...(shared ? {} : { shareUnpersisted: true }), ...(note ? { note } : {}) }));
     }));
     const mutateMapShape = {
         map_id: z.string().min(1).describe('map_id from a prior build_map call'),
@@ -641,7 +1109,7 @@ export function createServer(opts) {
     registerTool('mutate_map', {
         title: 'Mutate a map',
         description: 'Apply a natural-language instruction to an existing workspace. Valid mutations: filter a layer, remove a layer, change camera, change basemap. For ambiguous instructions the tool emits a clarification field. For unrelated instructions it emits outOfScope — build a new map in that case. ' +
-            'For the full Op catalog and predicate grammar, fetch the MCP resource showmeonmap://docs/workspace-ops-spec.',
+            'The full Op catalog and predicate grammar are documented in the MCP resource showmeonmap://docs/workspace-ops-spec.',
         inputSchema: mutateMapShape,
     }, withValidation('mutate_map', mutateMapShape, async ({ map_id, instruction, rationale }) => {
         const entry = await store.get(map_id);
@@ -668,7 +1136,7 @@ export function createServer(opts) {
         });
         const mutMapPlan = (resp.mapPlan ?? entry.mapPlan);
         // Update the shareable /m/<map_id> map so the link reflects the mutation.
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, mutMapPlan, instruction);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, mutMapPlan, instruction, null, resp.layerFilters);
         return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), mutMapPlan, resp.nextActions, {
             ...(resp.clarification ? { clarification: resp.clarification } : {}),
             ...(shared ? {} : { shareUnpersisted: true }),
@@ -718,7 +1186,7 @@ export function createServer(opts) {
         });
         const opMapPlan = (resp.mapPlan ?? entry.mapPlan);
         // Update the shareable /m/<map_id> map so the link reflects the mutation.
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, opMapPlan, opMapPlan?.title ?? '');
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, opMapPlan, opMapPlan?.title ?? '', null, resp.layerFilters);
         return envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), opMapPlan, undefined, shared ? {} : { shareUnpersisted: true });
     }
     /**
@@ -732,7 +1200,7 @@ export function createServer(opts) {
             turnId: randomUUID(),
             emittedAt: new Date().toISOString(),
             emittedBy,
-            rationale,
+            ...(rationale ? { rationale } : {}),
         };
     }
     // --- predicate schema (shared by filter_layer + query_features) ------------
@@ -769,8 +1237,8 @@ export function createServer(opts) {
         title: 'Add a layer (direct)',
         description: 'Append a fully-constructed LayerPlan to an existing workspace without going through NL. ' +
             'Pass the same shape the workspace pipeline emits — { id, title, source, viz, geometry, ... }. ' +
-            'Prefer this when you already have a structured plan; otherwise use mutate_map. ' +
-            'For the full LayerPlan and Op spec, fetch the MCP resource showmeonmap://docs/workspace-ops-spec.',
+            'Takes a structured plan; natural-language edits go through mutate_map. ' +
+            'The full LayerPlan and Op spec are documented in the MCP resource showmeonmap://docs/workspace-ops-spec.',
         inputSchema: addLayerShape,
     }, withValidation('add_layer', addLayerShape, async ({ map_id, layerPlan, rationale, intent }) => {
         logRationale('add_layer', map_id, rationale, { opKind: 'addLayer', ...(intent ? { intent } : {}) });
@@ -798,12 +1266,11 @@ export function createServer(opts) {
         title: 'Add bivariate fusion layer',
         description: 'Spatially join two existing layers and add a new layer that ' +
             'encodes both values per region as a 3x3 bivariate choropleth. ' +
-            'Both layers must already exist in the workspace (call build_map ' +
-            'or add_layer first). Auto-detects the numeric value field from ' +
+            'Both layers must already exist in the workspace. Auto-detects ' +
+            'the numeric value field from ' +
             'each layer\'s viz config; pass value_field_a / value_field_b to ' +
             'override. Returns the new layer_id, correlation r, and ' +
-            'matched-feature count. Required: map_id, layer_a_id, ' +
-            'layer_b_id, rationale.',
+            'matched-feature count. Required: map_id, layer_a_id, layer_b_id.',
         inputSchema: addFusionLayerShape,
     }, withValidation('add_fusion_layer', addFusionLayerShape, async ({ map_id, layer_a_id, layer_b_id, value_field_a, value_field_b, new_layer_id, rationale, }) => {
         const entry = await store.get(map_id);
@@ -817,7 +1284,7 @@ export function createServer(opts) {
             ...(value_field_a ? { valueFieldA: value_field_a } : {}),
             ...(value_field_b ? { valueFieldB: value_field_b } : {}),
             ...(new_layer_id ? { newLayerId: new_layer_id } : {}),
-            header: { rationale },
+            ...(rationale ? { header: { rationale } } : {}),
         });
         if (!data.ok) {
             throw new Error(`add_fusion_layer failed: ${data.error?.kind ?? 'unknown'} — ${data.error?.reason ?? data.error?.message ?? 'no detail'}`);
@@ -851,10 +1318,9 @@ export function createServer(opts) {
             'Pearson correlation coefficient r, sample size n, two-sided ' +
             'p-value approximation, plus human-readable strength and ' +
             'direction labels. Pure read — no layer is added, no op is ' +
-            'committed, no credit charge. Use this when you want a numeric ' +
-            'answer without rendering; use add_fusion_layer when the user ' +
-            'wants the visualization. Required: map_id, layer_a_id, ' +
-            'layer_b_id, rationale.',
+            'committed, no credit charge. Returns numbers only; ' +
+            'add_fusion_layer renders the same join as a map layer. ' +
+            'Required: map_id, layer_a_id, layer_b_id.',
         inputSchema: correlateLayersShape,
     }, withValidation('correlate_layers', correlateLayersShape, async ({ map_id, layer_a_id, layer_b_id, value_field_a, value_field_b, rationale, }) => {
         const entry = await store.get(map_id);
@@ -1023,7 +1489,7 @@ export function createServer(opts) {
             lastAccessed: Date.now(),
         });
         const focusedPlan = (resp.mapPlan ?? entry.mapPlan);
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, focusedPlan, rationale);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, focusedPlan, rationale, null, resp.layerFilters);
         return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), focusedPlan, undefined, {
             ...(resp.opsApplied ? { opsApplied: resp.opsApplied } : {}),
             ...(resp.contextAnswer ? { contextAnswer: resp.contextAnswer } : {}),
@@ -1033,9 +1499,9 @@ export function createServer(opts) {
     const runAnalysisShape = {
         map_id: z.string().min(1),
         analysis: z
-            .enum(['hotspot', 'zonal', 'enrich'])
-            .describe("Which analysis to run. 'hotspot' = Getis-Ord Gi* with FDR-corrected significance classes. 'zonal' = aggregate a point layer into polygon zones (count/sum/mean/min/max choropleth). 'enrich' = join a US Census indicator onto each feature by containment (tract/county/state)."),
-        layerId: z.string().min(1).describe('The workspace layer to analyze (geojson-backed; the point source for zonal).'),
+            .enum(['hotspot', 'zonal', 'enrich', 'join', 'merge', 'near', 'dissolve'])
+            .describe("Which analysis to run. 'hotspot' = Getis-Ord Gi* with FDR-corrected significance classes. 'zonal' = aggregate a point layer into polygon zones (count/sum/mean/min/max choropleth). 'enrich' = join a US Census indicator onto each feature by containment (tract/county/state). 'join' = spatial join (attribute transfer): each POINT in layerId takes the listed properties from the polygon in joinLayerId that contains it — the aggregate direction (points INTO polygons) is 'zonal'. 'merge' = append layerId + mergeLayerId (same geometry class) into ONE dataset, each row stamped with its source layer. 'near' = each POINT in layerId gains the great-circle distance to (and identity of) its nearest feature in nearLayerId. 'dissolve' = union POLYGONS sharing a dissolveField value into single features (omit the field to dissolve all into one)."),
+        layerId: z.string().min(1).describe('The workspace layer to analyze (geojson-backed; the point source for zonal; the point TARGET for join; the styling donor for merge).'),
         valueField: z
             .string()
             .min(1)
@@ -1074,6 +1540,63 @@ export function createServer(opts) {
             .enum(['state', 'county', 'tract'])
             .optional()
             .describe('enrich only: containment geography (default tract). Tract/county fetch only the states the data touches, capped at 3 — filter first or use state for wider layers.'),
+        joinLayerId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('join only (required there): the POLYGON layer providing the attributes.'),
+        fields: z
+            .array(z.string().min(1).max(80))
+            .min(1)
+            .max(12)
+            .optional()
+            .describe('join only: which join-layer properties to transfer (default: auto-select up to 12 non-internal properties, overflow reported).'),
+        prefix: z
+            .string()
+            .min(1)
+            .max(20)
+            .optional()
+            .describe('join only: prefix for a joined field whose name collides with an existing target property (default "join_").'),
+        mergeLayerId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('merge only (required there): the second layer — same geometry class (point/line/polygon) as layerId.'),
+        sourceField: z
+            .string()
+            .min(1)
+            .max(40)
+            .optional()
+            .describe('merge only: name of the per-row provenance column naming each row\'s source layer (default "merge_source"; renamed on collision, reported).'),
+        nearLayerId: z
+            .string()
+            .min(1)
+            .optional()
+            .describe('near only (required there): the POINT layer to search for each target point\'s nearest neighbor.'),
+        nearField: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe('near only: property of the nearest feature to copy as its identity (default: first name-like property).'),
+        maxDistanceM: z
+            .number()
+            .min(1)
+            .max(20_000_000)
+            .optional()
+            .describe('near only: search radius in meters — a point whose nearest neighbor is farther carries NO near fields (reported).'),
+        dissolveField: z
+            .string()
+            .min(1)
+            .max(80)
+            .optional()
+            .describe('dissolve only: group-by property (omit = dissolve ALL into one footprint); missing values form their own "(no value)" group.'),
+        sumFields: z
+            .array(z.string().min(1).max(80))
+            .min(1)
+            .max(5)
+            .optional()
+            .describe('dissolve only: numeric properties to SUM per group — skipped values reported, a group with none present carries NO sum.'),
         annotate: z
             .boolean()
             .optional()
@@ -1094,11 +1617,17 @@ export function createServer(opts) {
             'count/sum/mean/min/max per zone as a quantile choropleth where zero and no-data are ' +
             'distinct classes. enrich = join a US Census ACS indicator (median income, home value, ' +
             'rent, …) onto each feature by tract/county/state containment — unmatched features stay ' +
-            'null, never zero-filled. Returns a grounded memo + stats payload — every number is computed, ' +
+            'null, never zero-filled. join = spatial join (attribute transfer): each point in layerId ' +
+            'takes properties from the joinLayerId polygon containing it (collisions prefixed, unmatched ' +
+            'points carry NO joined fields, zero overlap is a typed rejection). merge = append two ' +
+            'same-geometry-class layers into one dataset with a per-row source column (schemas never ' +
+            'null-filled; class mismatch is a typed failure). near = nearest-neighbor distance columns ' +
+            '(great-circle meters, stated — never presented as road distance). dissolve = true polygon union ' +
+            'per attribute group (missing values form their own group; partial sums reported). Returns a grounded memo + stats payload — every number is computed, ' +
             'never generated; findings keep the map. Costs 1 credit when the result lands; typed ' +
             'failures (unknown layer, too few features, >10,000-feature cap) are refunded.',
         inputSchema: runAnalysisShape,
-    }, withValidation('run_analysis', runAnalysisShape, async ({ map_id, analysis, layerId, valueField, k, hexMeters, zoneLayerId, zones, stats, indicator, geoLevel, annotate, story, rationale }) => {
+    }, withValidation('run_analysis', runAnalysisShape, async ({ map_id, analysis, layerId, valueField, k, hexMeters, zoneLayerId, zones, stats, indicator, geoLevel, joinLayerId, fields, prefix, mergeLayerId, sourceField, nearLayerId, nearField, maxDistanceM, dissolveField, sumFields, annotate, story, rationale }) => {
         const entry = await store.get(map_id);
         if (!entry)
             throw new Error(`Unknown map_id "${map_id}". Call build_map first.`);
@@ -1115,6 +1644,16 @@ export function createServer(opts) {
             ...(stats !== undefined ? { stats } : {}),
             ...(indicator !== undefined ? { indicator } : {}),
             ...(geoLevel !== undefined ? { geoLevel } : {}),
+            ...(joinLayerId !== undefined ? { joinLayerId } : {}),
+            ...(fields !== undefined ? { fields } : {}),
+            ...(prefix !== undefined ? { prefix } : {}),
+            ...(mergeLayerId !== undefined ? { mergeLayerId } : {}),
+            ...(sourceField !== undefined ? { sourceField } : {}),
+            ...(nearLayerId !== undefined ? { nearLayerId } : {}),
+            ...(nearField !== undefined ? { nearField } : {}),
+            ...(maxDistanceM !== undefined ? { maxDistanceM } : {}),
+            ...(dissolveField !== undefined ? { dissolveField } : {}),
+            ...(sumFields !== undefined ? { sumFields } : {}),
             ...(annotate !== undefined ? { annotate } : {}),
             rationale,
         }));
@@ -1139,7 +1678,7 @@ export function createServer(opts) {
                 resultLayerId: resp.resultLayerId,
             })
             : null;
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, analyzedPlan, rationale, storyDraft);
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, analyzedPlan, rationale, storyDraft, resp.layerFilters);
         return toContent(envelope(baseUrl, map_id, (resp.workspace ?? entry.workspace), analyzedPlan, undefined, {
             ...(resp.opsApplied ? { opsApplied: resp.opsApplied } : {}),
             ...(resp.contextAnswer ? { contextAnswer: resp.contextAnswer } : {}),
@@ -1236,8 +1775,8 @@ export function createServer(opts) {
             .boolean()
             .optional()
             .describe('Set to true to confirm this sensitive action. If omitted or false, the call ' +
-            'returns a needs_confirmation envelope. Wiping a filter chain is recoverable ' +
-            'via undo, but autonomous agents lack a UI surface to confirm intent.'),
+            'returns a needs_confirmation envelope. A cleared filter chain can be ' +
+            'restored with undo.'),
     };
     registerTool('clear_filters', {
         title: 'Clear all filters on a layer (direct, gated)',
@@ -1319,8 +1858,12 @@ export function createServer(opts) {
     const cameraPlanSchema = z.discriminatedUnion('mode', [
         z.object({
             mode: z.literal('fitBounds'),
+            // Fixed-length arrays, NOT z.tuple: a tuple compiles to the draft-04
+            // `items: [..]` form, which the Anthropic API rejects — Claude then drops
+            // the whole tool (anthropicSchemaCompat.test.ts).
             bounds: z
-                .tuple([z.number(), z.number(), z.number(), z.number()])
+                .array(z.number())
+                .length(4)
                 .describe('[west, south, east, north] bbox in WGS84 degrees.'),
             padding: z
                 .number()
@@ -1335,7 +1878,7 @@ export function createServer(opts) {
         }),
         z.object({
             mode: z.literal('flyTo'),
-            center: z.tuple([z.number(), z.number()]).describe('[lng, lat] in WGS84.'),
+            center: z.array(z.number()).length(2).describe('[lng, lat] in WGS84.'),
             zoom: z.number(),
             pitch: z.number().optional().describe('Tilt in degrees, 0-60.'),
             bearing: z.number().optional().describe('Rotation in degrees, 0-360.'),
@@ -1356,8 +1899,8 @@ export function createServer(opts) {
         description: 'Override the workspace camera. Latest set_camera op wins during replay. ' +
             'Two modes: `fitBounds` with a [w,s,e,n] bbox (plus optional padding/animateMs), ' +
             'or `flyTo` with [lng,lat] center + zoom (plus optional pitch/bearing/animateMs). ' +
-            'Use for "zoom to Japan", "center on Paris at z=10", or finishing a drill-down ' +
-            'after filter_layer. Equivalent to the camera move mutate_map would emit, but ' +
+            'Covers requests like "zoom to Japan", "center on Paris at z=10", or framing ' +
+            'a filtered layer. Equivalent to the camera move mutate_map would emit, but ' +
             'skips the NL roundtrip.',
         inputSchema: setCameraShape,
     }, withValidation('set_camera', setCameraShape, async ({ map_id, camera, rationale }) => {
@@ -1386,7 +1929,7 @@ export function createServer(opts) {
     registerTool('set_time', {
         title: 'Set the time window (direct)',
         description: 'Override the current time-range filter. Latest set_time op wins during replay. ' +
-            'Use for "filter to 2020-2024" or "show only the last 7 days" intents. Not yet ' +
+            'Covers requests like "filter to 2020-2024" or "show only the last 7 days". Not yet ' +
             'consumed by the renderer — the UI drives the slider directly — but the value is ' +
             'captured in the ops log and queryable via get_state.',
         inputSchema: setTimeShape,
@@ -1431,7 +1974,8 @@ export function createServer(opts) {
         map_id: z.string().min(1),
         id: z.string().min(1).describe('Stable id for this annotation — caller-supplied.'),
         coords: z
-            .tuple([z.number(), z.number()])
+            .array(z.number())
+            .length(2) // not z.tuple — see cameraPlanSchema
             .describe('[lng, lat] in WGS84.'),
         label: z.string().optional().describe('Optional text rendered at the point.'),
         color: z
@@ -1508,7 +2052,7 @@ export function createServer(opts) {
         });
         const rematPlan = resp.mapPlan;
         // Keep the shareable /m/<map_id> map in sync after undo/redo.
-        const shared = await persistShareableMap(baseUrl, apiKey, map_id, rematPlan, rematPlan?.title ?? '');
+        const shared = await persistShareableMap(baseUrl, apiKey, map_id, rematPlan, rematPlan?.title ?? '', null, resp.layerFilters);
         return envelope(baseUrl, map_id, workspace, rematPlan, undefined, shared ? {} : { shareUnpersisted: true });
     }
     const exportWorkspaceShape = {
@@ -1519,9 +2063,9 @@ export function createServer(opts) {
         title: 'Export the workspace JSON',
         description: 'Return the current workspace document (ops log + cursor + meta) plus the ' +
             'materialized mapPlan and layerFilters, in a shape suitable for save-to-file / ' +
-            'share-by-URL / inspection. Pure read — no mutation, no credit charge. Use ' +
-            'this when you want the full raw state for serialization; use get_state when ' +
-            'you want the compact envelope for display.',
+            'share-by-URL / inspection. Pure read — no mutation, no credit charge. This is ' +
+            'the full raw state for serialization; get_state returns a compact summary ' +
+            'for display.',
         inputSchema: exportWorkspaceShape,
     }, withValidation('export_workspace', exportWorkspaceShape, async ({ map_id, rationale }) => {
         const entry = await store.get(map_id);
@@ -1549,8 +2093,8 @@ export function createServer(opts) {
             'a URL with Content-Disposition: attachment so the user\'s browser ' +
             'downloads it. CSV drops geometry beyond a (lng, lat) centroid — ' +
             'for full polygon/line geometry, use format: "geojson". The URL is an ' +
-            'unguessable capability link that does NOT expire — treat it as ' +
-            'shareable-forever, not temporary. Required: map_id, layer_id, format, rationale.',
+            'unguessable capability link that does NOT expire: anyone with the link ' +
+            'can download the file. Required: map_id, layer_id, format.',
         inputSchema: exportLayerDataShape,
     }, withValidation('export_layer_data', exportLayerDataShape, async ({ map_id, layer_id, format, rationale }) => {
         logRationale('export_layer_data', map_id, rationale);
@@ -1572,7 +2116,7 @@ export function createServer(opts) {
             'link, the browser renders the map at full resolution with the ' +
             'legend composited (if legend: true), and the file downloads. ' +
             'There is no server-side rendering; the user\'s browser is the ' +
-            'renderer. Required: map_id, rationale. Optional: format (png ' +
+            'renderer. Required: map_id. Optional: format (png ' +
             'default), legend (true default).',
         inputSchema: exportImageShape,
     }, withValidation('export_image', exportImageShape, async ({ map_id, format, legend, rationale }) => {
@@ -1601,8 +2145,8 @@ export function createServer(opts) {
             .boolean()
             .optional()
             .describe('Set to true to confirm this sensitive action. If omitted or false, the call ' +
-            'returns a needs_confirmation envelope. Autonomous undo without user intent is ' +
-            'a footgun — an agent that decides to "fix" something can erase prior work.'),
+            'returns a needs_confirmation envelope. Undo rewinds the most recent change; ' +
+            'redo restores it.'),
     };
     registerTool('undo', {
         title: 'Undo the most recent op (gated)',
@@ -1691,13 +2235,11 @@ export function createServer(opts) {
     };
     registerTool('report_blocker', {
         title: 'Report a blocker (agent feedback)',
-        description: 'Tell the ShowMeOnMap team your agent hit something it could not accomplish — an ' +
-            'unsupported intent, a missing tool, an unclear schema, an op that failed in a ' +
-            'confusing way. Use this when build_map / mutate_map / a direct-op tool returns ' +
-            'something you cannot recover from, OR when you would have wanted a different tool ' +
-            'to exist. Records the report to a server-side log; does not unblock the current ' +
-            'session, but feeds future capability work. No map_id required — file the report ' +
-            'even if no map was built.',
+        description: 'Send the ShowMeOnMap team a report about a request this server could not ' +
+            'complete — an unsupported intent, a missing tool, an unclear schema, or an op ' +
+            'that failed in a confusing way. Records the report to a server-side log for ' +
+            'future capability work; it does not change the current map or session. ' +
+            'map_id is optional, so a report can be filed before any map exists.',
         inputSchema: reportBlockerShape,
     }, withValidation('report_blocker', reportBlockerShape, async ({ map_id, what_i_was_trying, what_i_tried, where_i_got_stuck, suggested_capability, rationale }) => {
         // Mirror to the rationale NDJSON so the May-1 clustering pass sees a
@@ -1721,6 +2263,131 @@ export function createServer(opts) {
             ...(resp.sink ? { sink: resp.sink } : {}),
         });
     }));
+    // ── Workflows (D2 phase 6): save / list / run saved instruction streams ──
+    // Semantic replay: templates store {param}-slotted INSTRUCTIONS, never
+    // resolved ops; a run re-executes them through the live pipelines, so
+    // every step bills exactly like typing it (credits per existing rules).
+    const saveWorkflowShape = {
+        name: z.string().min(1).max(80).describe('Workflow name.'),
+        steps: z
+            .array(z.object({ instruction: z.string().min(1).max(4000) }))
+            .min(1)
+            .max(12)
+            .describe('Ordered NL instructions. Step 1 builds the map; later steps mutate it. Wrap values in {braces} to declare parameters.'),
+        params: z
+            .array(z.object({
+            name: z.string().min(1).max(40),
+            label: z.string().min(1).max(80),
+            kind: z.enum(['place', 'number', 'text', 'timerange']),
+            default: z.string().max(200).optional(),
+        }))
+            .max(8)
+            .optional()
+            .describe('Declared parameters — every {slot} used in steps must be declared here.'),
+        rationale: rationaleSchema,
+    };
+    registerTool('save_workflow', {
+        title: 'Save a workflow',
+        description: 'Save a re-runnable, parameterized workflow: an ordered list of natural-language instructions (step 1 builds, later steps mutate). Wrap values in {braces} and declare them in params. Running it later re-executes the instructions on FRESH data and bills per step like typing.',
+        inputSchema: saveWorkflowShape,
+    }, withValidation('save_workflow', saveWorkflowShape, async ({ name, steps, params, rationale }) => {
+        logRationale('save_workflow', null, rationale);
+        const resp = (await apiFetch(baseUrl, apiKey, '/api/workflows', {
+            name,
+            steps,
+            params: params ?? [],
+        }));
+        if (!resp.ok || !resp.template)
+            throw new Error(`save_workflow failed: ${resp.error ?? 'unknown'}`);
+        return toContent({
+            ok: true,
+            workflow_id: resp.template.id,
+            estimated_credits: resp.template.estimatedCredits,
+            note: 'Estimate = step count; escalations can cost more. Run with run_workflow.',
+        });
+    }));
+    const listWorkflowsShape = { rationale: rationaleSchema };
+    registerTool('list_workflows', {
+        title: 'List saved workflows',
+        description: 'List the caller\'s saved workflows with their parameters and per-run credit estimates.',
+        inputSchema: listWorkflowsShape,
+    }, withValidation('list_workflows', listWorkflowsShape, async ({ rationale }) => {
+        logRationale('list_workflows', null, rationale);
+        const resp = await fetchNoRedirect(`${baseUrl}/api/workflows`, {
+            headers: { ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) },
+        });
+        const text = await resp.text();
+        if (!resp.ok)
+            throw new Error(`/api/workflows ${resp.status}: ${describeErrorBody(text)}`);
+        const data = JSON.parse(text);
+        return toContent({
+            ok: true,
+            workflows: (data.templates ?? []).map((t) => ({
+                workflow_id: t.id,
+                name: t.name,
+                steps: t.steps.length,
+                params: t.params,
+                estimated_credits: t.estimatedCredits,
+            })),
+        });
+    }));
+    const runWorkflowShape = {
+        workflow_id: z.string().min(1).describe('From save_workflow or list_workflows.'),
+        params: z.record(z.string(), z.string()).optional().describe('Values for the workflow\'s declared parameters.'),
+        batch: z
+            .object({
+            param: z.string().min(1).describe('The ONE declared param to sweep (must not also be in params).'),
+            values: z.array(z.string().min(1)).min(2).max(20).describe('2–20 values; each is a FULL independent billed run.'),
+        })
+            .optional()
+            .describe('Batch mode: run the workflow once per value ("each of the 12 districts"). Bills steps × values.'),
+        rationale: rationaleSchema,
+    };
+    registerTool('run_workflow', {
+        title: 'Run a saved workflow',
+        description: 'Execute a saved workflow with parameter values. PAID: bills ~1 credit per step through the normal build/mutate paths (the estimate is in list_workflows). Optional batch mode sweeps ONE param across 2–20 values — each value is a full independent run (steps × values credits); failed/paused values are reported per value and the batch continues. A clarification pauses a single run (status "paused" + the question); failures stop at the failing step. On success the result is a live map with a shareable URL (batch: the last successful value\'s map).',
+        inputSchema: runWorkflowShape,
+    }, withValidation('run_workflow', runWorkflowShape, async ({ workflow_id, params, batch, rationale }) => {
+        logRationale('run_workflow', null, rationale);
+        const resp = (await apiFetch(baseUrl, apiKey, `/api/workflows/${workflow_id}/run`, {
+            params: params ?? {},
+            ...(batch ? { batch } : {}),
+            stream: false,
+        }));
+        if (resp.status === 'paused') {
+            return toContent({ ok: false, status: 'paused', question: resp.question, events: resp.events });
+        }
+        if ((resp.status !== 'done' && resp.status !== 'partial') || !resp.workspace) {
+            return toContent({
+                ok: false,
+                status: 'failed',
+                error: resp.error ?? 'run failed',
+                ...(resp.batch ? { batch: resp.batch } : {}),
+                events: resp.events,
+            });
+        }
+        const mapId = asSessionId(resp.workspace.workspaceId ?? randomUUID());
+        await store.put(mapId, {
+            workspace: resp.workspace,
+            mapPlan: resp.mapPlan ?? null,
+            layerFilters: {},
+            createdAt: Date.now(),
+            lastAccessed: Date.now(),
+        });
+        const shared = resp.mapPlan
+            ? await persistShareableMap(baseUrl, apiKey, mapId, resp.mapPlan, `workflow ${workflow_id}`)
+            : false;
+        return toContent(envelope(baseUrl, mapId, resp.workspace, (resp.mapPlan ?? null), undefined, {
+            contextAnswer: resp.batch
+                ? `Batch: ${resp.batch.succeeded}/${resp.batch.total} value(s) succeeded` +
+                    (resp.batch.failed ? `, ${resp.batch.failed} failed` : '') +
+                    (resp.batch.paused ? `, ${resp.batch.paused} paused` : '') +
+                    ` — map shows "${resp.workspaceValue ?? '?'}"; per-value outcomes in batch.results.`
+                : `Workflow ran ${(resp.events ?? []).filter((e) => e.type === 'step_done').length} step(s).`,
+            ...(resp.batch ? { batch: resp.batch } : {}),
+            ...(shared ? {} : { shareUnpersisted: true }),
+        }));
+    }));
     // ── JSON Schema draft normalization (2026-07-16) ─────────────────────────
     // zod-to-json-schema (inside the SDK) stamps every tool's inputSchema with a
     // draft-07 `$schema` header. The Anthropic API validates tool schemas as