semiotic 3.4.2 → 3.5.1

package/ai/dist/mcp-server.js

@@ -6799,6 +6799,697 @@ var require_dist = __commonJS({
   }
 });
 
+// ai/componentMetadata.cjs
+var require_componentMetadata = __commonJS({
+  "ai/componentMetadata.cjs"(exports2, module2) {
+    "use strict";
+    var CATEGORY_ORDER = ["xy", "ordinal", "network", "geo", "realtime"];
+    var COMPONENTS_BY_CATEGORY = {
+      xy: [
+        "LineChart",
+        "AreaChart",
+        "StackedAreaChart",
+        "Scatterplot",
+        "QuadrantChart",
+        "MultiAxisLineChart",
+        "CandlestickChart",
+        "BubbleChart",
+        "Heatmap",
+        "ConnectedScatterplot",
+        "ScatterplotMatrix",
+        "MinimapChart"
+      ],
+      ordinal: [
+        "BarChart",
+        "StackedBarChart",
+        "LikertChart",
+        "GroupedBarChart",
+        "SwarmPlot",
+        "BoxPlot",
+        "Histogram",
+        "ViolinPlot",
+        "RidgelinePlot",
+        "DotPlot",
+        "PieChart",
+        "DonutChart",
+        "GaugeChart",
+        "FunnelChart",
+        "SwimlaneChart"
+      ],
+      network: [
+        "ForceDirectedGraph",
+        "SankeyDiagram",
+        "ChordDiagram",
+        "TreeDiagram",
+        "Treemap",
+        "CirclePack",
+        "OrbitDiagram"
+      ],
+      geo: [
+        "ChoroplethMap",
+        "ProportionalSymbolMap",
+        "FlowMap",
+        "DistanceCartogram"
+      ],
+      realtime: [
+        "RealtimeLineChart",
+        "RealtimeHistogram",
+        "RealtimeSwarmChart",
+        "RealtimeWaterfallChart",
+        "RealtimeHeatmap"
+      ]
+    };
+    var COMPONENT_TO_CATEGORY = /* @__PURE__ */ new Map();
+    for (const [category, names] of Object.entries(COMPONENTS_BY_CATEGORY)) {
+      for (const name of names) {
+        COMPONENT_TO_CATEGORY.set(name, category);
+      }
+    }
+    function schemaEntries(schema2) {
+      return schema2.tools.map((tool) => tool.function);
+    }
+    function categoryForComponent(name) {
+      const category = COMPONENT_TO_CATEGORY.get(name);
+      if (!category) {
+        throw new Error(`No AI component metadata category for "${name}"`);
+      }
+      return category;
+    }
+    function importPathForCategory(category) {
+      return category === "geo" ? "semiotic/geo" : `semiotic/${category}`;
+    }
+    function metadataForComponent2(entryOrName) {
+      const name = typeof entryOrName === "string" ? entryOrName : entryOrName.name;
+      const category = categoryForComponent(name);
+      return {
+        name,
+        category,
+        importPath: importPathForCategory(category),
+        renderable: category !== "realtime",
+        description: typeof entryOrName === "string" ? void 0 : entryOrName.description
+      };
+    }
+    function findComponent(schema2, name) {
+      const entries = schemaEntries(schema2);
+      const exact = entries.find((entry) => entry.name === name);
+      if (exact) return exact;
+      const lower = name.toLowerCase();
+      return entries.find((entry) => entry.name.toLowerCase() === lower);
+    }
+    function componentIndexFromSchema2(schema2) {
+      const components = schemaEntries(schema2).map(metadataForComponent2);
+      const categories = {};
+      for (const category of CATEGORY_ORDER) {
+        categories[category] = [];
+      }
+      for (const component of components) {
+        categories[component.category].push(component.name);
+      }
+      for (const names of Object.values(categories)) {
+        names.sort();
+      }
+      return {
+        version: schema2.version,
+        totalComponents: components.length,
+        renderableComponents: components.filter((component) => component.renderable).length,
+        browserOnlyComponents: components.filter((component) => !component.renderable).length,
+        categories,
+        components
+      };
+    }
+    module2.exports = {
+      CATEGORY_ORDER,
+      COMPONENTS_BY_CATEGORY,
+      categoryForComponent,
+      componentIndexFromSchema: componentIndexFromSchema2,
+      findComponent,
+      importPathForCategory,
+      metadataForComponent: metadataForComponent2,
+      schemaEntries
+    };
+  }
+});
+
+// ai/chartSuggestions.cjs
+var require_chartSuggestions = __commonJS({
+  "ai/chartSuggestions.cjs"(exports2, module2) {
+    "use strict";
+    var VALID_INTENTS = [
+      "comparison",
+      "trend",
+      "distribution",
+      "relationship",
+      "composition",
+      "geographic",
+      "network",
+      "hierarchy"
+    ];
+    var MAX_SAMPLE_SIZE = 5;
+    function summarizeFields(data, keys) {
+      const numericFields = [];
+      const stringFields = [];
+      const dateFields = [];
+      const geoFields = {};
+      const networkFields = {};
+      const hierarchyFields = {};
+      for (const key of keys) {
+        const values = data.map((d) => d[key]).filter((v) => v != null);
+        if (values.length === 0) continue;
+        const first = values[0];
+        if (typeof first === "number") {
+          numericFields.push(key);
+        } else if (typeof first === "string") {
+          if (/^\d{4}[-/]\d{2}/.test(first) && !Number.isNaN(Date.parse(first))) {
+            dateFields.push(key);
+          } else {
+            stringFields.push(key);
+          }
+        }
+        const kl = key.toLowerCase();
+        if (kl === "lat" || kl === "latitude") geoFields.lat = key;
+        if (kl === "lon" || kl === "lng" || kl === "longitude") geoFields.lon = key;
+        if (kl === "source" || kl === "from") networkFields.source = key;
+        if (kl === "target" || kl === "to") networkFields.target = key;
+        if (kl === "value" || kl === "weight" || kl === "amount") networkFields.value = key;
+        if (kl === "children" || kl === "values") hierarchyFields.children = key;
+        if (kl === "parent") hierarchyFields.parent = key;
+      }
+      return {
+        keys,
+        numericFields,
+        stringFields,
+        dateFields,
+        geoFields,
+        networkFields,
+        hierarchyFields
+      };
+    }
+    function jsxString(value) {
+      return JSON.stringify(String(value));
+    }
+    function jsxExpression(value) {
+      return `{${value}}`;
+    }
+    function uniqueNetworkNodes(data, sourceField, targetField) {
+      const ids = /* @__PURE__ */ new Set();
+      for (const datum of data) {
+        const source = datum[sourceField];
+        const target = datum[targetField];
+        if (source != null) ids.add(source);
+        if (target != null) ids.add(target);
+      }
+      return Array.from(ids).map((id) => ({ id }));
+    }
+    function suggestCharts2(args = {}) {
+      const data = args.data;
+      const intent = args.intent;
+      if (intent && !VALID_INTENTS.includes(intent)) {
+        return {
+          ok: false,
+          error: `Unknown intent "${intent}". Expected one of: ${VALID_INTENTS.join(", ")}.`
+        };
+      }
+      if (!data || !Array.isArray(data) || data.length === 0) {
+        return {
+          ok: false,
+          error: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy'."
+        };
+      }
+      if (data.length > MAX_SAMPLE_SIZE) {
+        return {
+          ok: false,
+          error: `Pass 1-${MAX_SAMPLE_SIZE} sample data objects; received ${data.length}. Use a representative sample instead of the full dataset.`
+        };
+      }
+      const sample = data[0];
+      if (!sample || typeof sample !== "object" || Array.isArray(sample)) {
+        return {
+          ok: false,
+          error: "Data items must be objects with key-value pairs."
+        };
+      }
+      const keys = Object.keys(sample);
+      const fields = summarizeFields(data, keys);
+      const suggestions = [];
+      const { numericFields, stringFields, dateFields, geoFields, networkFields, hierarchyFields } = fields;
+      const hasTime = dateFields.length > 0;
+      const hasCat = stringFields.length > 0;
+      const hasNum = numericFields.length > 0;
+      const hasGeo = Boolean(geoFields.lat && geoFields.lon);
+      const hasNetwork = Boolean(networkFields.source && networkFields.target);
+      const hasHierarchy = Boolean(hierarchyFields.children || hierarchyFields.parent);
+      if (hasNetwork && (!intent || intent === "network")) {
+        const src = networkFields.source;
+        const tgt = networkFields.target;
+        if (networkFields.value) {
+          suggestions.push({
+            component: "SankeyDiagram",
+            confidence: "high",
+            reason: `Data has ${src}->${tgt} with ${networkFields.value} - ideal for flow visualization`,
+            props: { edges: jsxExpression("data"), sourceAccessor: jsxString(src), targetAccessor: jsxString(tgt), valueAccessor: jsxString(networkFields.value) }
+          });
+        }
+        const nodes = uniqueNetworkNodes(data, src, tgt);
+        suggestions.push({
+          component: "ForceDirectedGraph",
+          confidence: networkFields.value ? "medium" : "high",
+          reason: `Data has ${src}->${tgt} edges - force layout shows network structure. ForceDirectedGraph requires explicit nodes, derived here from unique source/target IDs.`,
+          setup: [`const nodes = ${JSON.stringify(nodes, null, 2)}`],
+          derivedData: { nodes },
+          props: { nodes: jsxExpression("nodes"), edges: jsxExpression("data"), nodeIDAccessor: jsxString("id"), sourceAccessor: jsxString(src), targetAccessor: jsxString(tgt) }
+        });
+      }
+      if (hasHierarchy && hierarchyFields.children && Array.isArray(sample[hierarchyFields.children]) && (!intent || intent === "hierarchy")) {
+        const childrenAccessor = hierarchyFields.children;
+        suggestions.push({
+          component: "Treemap",
+          confidence: "high",
+          reason: `Data has nested ${childrenAccessor} structure - treemap shows hierarchical proportions. Use data[0] as the root node from the provided sample.`,
+          props: { data: jsxExpression("data[0]"), childrenAccessor: jsxString(childrenAccessor), ...numericFields[0] ? { valueAccessor: jsxString(numericFields[0]) } : {} }
+        });
+        suggestions.push({
+          component: "TreeDiagram",
+          confidence: "medium",
+          reason: `Tree layout shows hierarchical relationships. Use data[0] as the root node from the provided sample.`,
+          props: { data: jsxExpression("data[0]"), childrenAccessor: jsxString(childrenAccessor) }
+        });
+      }
+      if (hasGeo && (!intent || intent === "geographic")) {
+        const sizeField = numericFields.find((f) => f !== geoFields.lat && f !== geoFields.lon);
+        suggestions.push({
+          component: "ProportionalSymbolMap",
+          confidence: "high",
+          reason: `Data has ${geoFields.lat}/${geoFields.lon} coordinates - map shows spatial distribution`,
+          props: { points: jsxExpression("data"), xAccessor: jsxString(geoFields.lon), yAccessor: jsxString(geoFields.lat), ...sizeField ? { sizeBy: jsxString(sizeField) } : {} }
+        });
+      }
+      if (hasTime && hasNum && (!intent || intent === "trend")) {
+        const timeField = dateFields[0];
+        const valueField = numericFields[0];
+        suggestions.push({
+          component: "LineChart",
+          confidence: "high",
+          reason: `Data has dates (${timeField}) and numeric values (${valueField}) - line chart shows trends over time`,
+          props: { data: jsxExpression("data"), xAccessor: jsxString(timeField), yAccessor: jsxString(valueField), ...hasCat ? { lineBy: jsxString(stringFields[0]), colorBy: jsxString(stringFields[0]) } : {} }
+        });
+        if (hasCat) {
+          suggestions.push({
+            component: "StackedAreaChart",
+            confidence: "medium",
+            reason: `Multiple categories (${stringFields[0]}) over time - stacked area shows composition trends`,
+            props: { data: jsxExpression("data"), xAccessor: jsxString(timeField), yAccessor: jsxString(valueField), areaBy: jsxString(stringFields[0]), colorBy: jsxString(stringFields[0]) }
+          });
+        }
+      }
+      if (hasCat && hasNum && (!intent || intent === "comparison" || intent === "composition" || intent === "distribution")) {
+        const catField = stringFields[0];
+        const valField = numericFields[0];
+        if (!intent || intent === "comparison") {
+          suggestions.push({
+            component: "BarChart",
+            confidence: hasTime ? "medium" : "high",
+            reason: `Categorical field (${catField}) with values (${valField}) - bar chart for comparison`,
+            props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) }
+          });
+        }
+        if (stringFields.length >= 2 && (!intent || intent === "composition")) {
+          suggestions.push({
+            component: "StackedBarChart",
+            confidence: "medium",
+            reason: `Two categorical fields (${stringFields.join(", ")}) - stacked bar shows composition within categories`,
+            props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField), stackBy: jsxString(stringFields[1]) }
+          });
+        }
+        if (!intent || intent === "distribution") {
+          suggestions.push({
+            component: "Histogram",
+            confidence: "medium",
+            reason: `Numeric distribution of ${valField} - histogram shows value spread`,
+            props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) }
+          });
+        }
+        if (!intent || intent === "composition") {
+          const uniqueCats = new Set(data.map((d) => d[catField])).size;
+          if (uniqueCats <= 8) {
+            suggestions.push({
+              component: "DonutChart",
+              confidence: "medium",
+              reason: `${uniqueCats} categories - donut chart shows proportional composition`,
+              props: { data: jsxExpression("data"), categoryAccessor: jsxString(catField), valueAccessor: jsxString(valField) }
+            });
+          }
+        }
+      }
+      if (numericFields.length >= 2 && (!intent || intent === "relationship")) {
+        const xField = numericFields[0];
+        const yField = numericFields[1];
+        suggestions.push({
+          component: "Scatterplot",
+          confidence: "high",
+          reason: `Two numeric fields (${xField}, ${yField}) - scatterplot shows relationships`,
+          props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), ...hasCat ? { colorBy: jsxString(stringFields[0]) } : {}, ...numericFields[2] ? { sizeBy: jsxString(numericFields[2]) } : {} }
+        });
+        if (numericFields.length >= 3) {
+          suggestions.push({
+            component: "BubbleChart",
+            confidence: "medium",
+            reason: "Three numeric fields - bubble chart adds size dimension to scatter",
+            props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), sizeBy: jsxString(numericFields[2]) }
+          });
+        }
+      }
+      if (stringFields.length >= 2 && numericFields.length >= 1 && (!intent || intent === "relationship" || intent === "distribution" || intent === "composition")) {
+        const xField = stringFields[0];
+        const yField = stringFields[1];
+        const valueField = numericFields[0];
+        suggestions.push({
+          component: "Heatmap",
+          confidence: "medium",
+          reason: `Two categorical fields (${xField}, ${yField}) plus numeric values (${valueField}) - heatmap shows intensity across dimensions`,
+          props: { data: jsxExpression("data"), xAccessor: jsxString(xField), yAccessor: jsxString(yField), valueAccessor: jsxString(valueField) }
+        });
+      }
+      return {
+        ok: true,
+        intent,
+        fieldSummary: `Fields: ${keys.join(", ")} (${numericFields.length} numeric, ${stringFields.length} categorical, ${dateFields.length} date)`,
+        fields,
+        suggestions
+      };
+    }
+    function formatSuggestionReport2(result) {
+      if (!result.ok) return result.error;
+      if (result.suggestions.length === 0) {
+        return `Could not confidently recommend a chart type.
+
+${result.fieldSummary}
+
+Try providing intent ('${VALID_INTENTS.join("', '")}') to narrow recommendations, or use getSchema to browse available components.`;
+      }
+      const lines = result.suggestions.map((suggestion, i) => {
+        const propsStr = Object.entries(suggestion.props).map(([k, v]) => `${k}=${v}`).join(" ");
+        const setup = suggestion.setup ? `${suggestion.setup.join("\n")}
+` : "";
+        return `${i + 1}. **${suggestion.component}** (${suggestion.confidence} confidence)
+   ${suggestion.reason}
+\`\`\`tsx
+${setup}<${suggestion.component} ${propsStr} />
+\`\`\``;
+      });
+      const themingTip = `
+---
+**Styling**: All charts respond to CSS custom properties on any ancestor element:
+\`\`\`css
+.my-theme {
+  --semiotic-bg: #fff;
+  --semiotic-text: #333;
+  --semiotic-text-secondary: #666;
+  --semiotic-grid: #e0e0e0;
+  --semiotic-border: #e0e0e0;
+  --semiotic-font-family: sans-serif;
+  --semiotic-tooltip-bg: rgba(0,0,0,0.85);
+  --semiotic-tooltip-text: white;
+  --semiotic-tooltip-radius: 6px;
+}
+\`\`\`
+Or use \`<ThemeProvider theme="dark">\` / \`<ThemeProvider theme={{ colors: {...}, typography: {...} }}>\`.
+For accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import from \`semiotic/themes\`) - 8-color palette safe for all forms of color blindness.`;
+      return lines.join("\n\n") + themingTip;
+    }
+    module2.exports = {
+      VALID_INTENTS,
+      formatSuggestionReport: formatSuggestionReport2,
+      suggestCharts: suggestCharts2
+    };
+  }
+});
+
+// ai/behaviorContracts.cjs
+var require_behaviorContracts = __commonJS({
+  "ai/behaviorContracts.cjs"(exports2, module2) {
+    "use strict";
+    var path2 = require("path");
+    var fs2 = require("fs");
+    var DOC_MARKER_START = "<!-- semiotic-behavior-contracts:start -->";
+    var DOC_MARKER_END = "<!-- semiotic-behavior-contracts:end -->";
+    function loadStaticDataComponentsFromSchema() {
+      const candidates = [
+        path2.join(__dirname, "schema.json"),
+        path2.join(__dirname, "..", "schema.json")
+      ];
+      for (const schemaPath2 of candidates) {
+        try {
+          const schema2 = JSON.parse(fs2.readFileSync(schemaPath2, "utf8"));
+          const out = /* @__PURE__ */ new Set();
+          for (const tool of schema2.tools || []) {
+            const required2 = tool.function?.parameters?.required || [];
+            if (required2.includes("data")) out.add(tool.function.name);
+          }
+          if (out.size > 0) return out;
+        } catch {
+        }
+      }
+      return /* @__PURE__ */ new Set();
+    }
+    var REQUIRED_COMBINATIONS = [
+      {
+        component: "StackedAreaChart",
+        required: ["areaBy"],
+        staticRequired: ["data", "areaBy"],
+        pushRequired: ["areaBy"],
+        summary: "Stacked areas need a flat data array plus areaBy to identify the stacked series."
+      },
+      {
+        component: "BubbleChart",
+        required: ["sizeBy"],
+        staticRequired: ["data", "sizeBy"],
+        pushRequired: ["sizeBy"],
+        summary: "Bubbles need sizeBy in addition to x/y accessors so radius encodes data rather than a constant point size."
+      },
+      {
+        component: "StackedBarChart",
+        required: ["stackBy"],
+        staticRequired: ["data", "stackBy"],
+        pushRequired: ["stackBy"],
+        summary: "Stacked bars need stackBy to split each category into stack segments."
+      },
+      {
+        component: "GroupedBarChart",
+        required: ["groupBy"],
+        staticRequired: ["data", "groupBy"],
+        pushRequired: ["groupBy"],
+        summary: "Grouped bars need groupBy to split each category into side-by-side bars."
+      },
+      {
+        component: "SwimlaneChart",
+        required: ["subcategoryAccessor"],
+        staticRequired: ["data", "subcategoryAccessor"],
+        pushRequired: ["subcategoryAccessor"],
+        summary: "Swimlanes need subcategoryAccessor; colorBy defaults to the same field when not provided."
+      },
+      {
+        component: "GaugeChart",
+        required: ["value"],
+        staticRequired: ["value"],
+        pushRequired: [],
+        summary: "GaugeChart is value-only. thresholds, min, max, sweep, and arcWidth are optional."
+      },
+      {
+        component: "ForceDirectedGraph",
+        required: ["nodes", "edges"],
+        staticRequired: ["nodes", "edges"],
+        pushRequired: ["nodes", "edges"],
+        summary: "ForceDirectedGraph schema/rendering requires nodes and edges. If an agent infers nodes from edge endpoints, it must materialize a nodes array before returning code."
+      }
+    ];
+    var PUSH_MODE_COMPONENTS = [
+      "LineChart",
+      "AreaChart",
+      "StackedAreaChart",
+      "Scatterplot",
+      "BubbleChart",
+      "ConnectedScatterplot",
+      "BarChart",
+      "StackedBarChart",
+      "GroupedBarChart",
+      "SwarmPlot",
+      "BoxPlot",
+      "Histogram",
+      "ViolinPlot",
+      "RidgelinePlot",
+      "DotPlot",
+      "PieChart",
+      "DonutChart",
+      "LikertChart",
+      "SwimlaneChart",
+      "ForceDirectedGraph",
+      "SankeyDiagram",
+      "ChordDiagram",
+      "ProportionalSymbolMap",
+      "DistanceCartogram"
+    ];
+    var STATIC_DATA_COMPONENTS = loadStaticDataComponentsFromSchema();
+    var BEHAVIOR_CONTRACTS2 = [
+      {
+        id: "props.data-required-by-usage-mode",
+        category: "required-props",
+        title: "Data required by usage mode",
+        severity: "error",
+        appliesTo: {
+          components: PUSH_MODE_COMPONENTS
+        },
+        summary: "Static usage (`renderChart`, MCP previews, SSR snapshots, and copy/paste examples with immediate data) requires data in props. React push mode selects live ingestion by omitting data and mutating through a ref.",
+        agentAction: 'Pass usageMode="push" to `semiotic-ai --doctor` when validating ref-based JSX with no data prop. Keep usageMode="static" or omit it for renderChart/MCP/static configs where data must be present.'
+      },
+      {
+        id: "color.category-precedence",
+        category: "color",
+        title: "Categorical color precedence",
+        severity: "info",
+        appliesTo: {
+          propsAny: ["colorBy", "colorScheme"]
+        },
+        summary: "When colorBy is set, CategoryColorProvider/LinkedCharts category maps win for mapped categories. Unmapped categories fall back to explicit colorScheme, then ThemeProvider colors.categorical, then the built-in categorical fallback.",
+        agentAction: "Use colorBy for categorical encodings. Use CategoryColorProvider or LinkedCharts for cross-chart consistency, colorScheme for per-chart fallback palettes, and avoid frameProps style functions unless intentionally bypassing HOC color resolution."
+      },
+      {
+        id: "props.required-combinations",
+        category: "required-props",
+        title: "Required prop combinations",
+        severity: "error",
+        appliesTo: {
+          components: REQUIRED_COMBINATIONS.map((entry) => entry.component)
+        },
+        summary: "Some chart families need semantic props beyond data. These combinations are enforced by validation/schema for static configs and remain required in push mode unless explicitly noted.",
+        agentAction: "Before returning code, check the selected component against the required combinations list. For push mode, omit data but keep semantic props such as areaBy, sizeBy, stackBy, and groupBy.",
+        combinations: REQUIRED_COMBINATIONS
+      },
+      {
+        id: "streaming.push-mode-data",
+        category: "streaming",
+        title: "Push mode omits data",
+        severity: "warning",
+        appliesTo: {
+          components: PUSH_MODE_COMPONENTS
+        },
+        summary: "HOC push mode is selected by omitting the data prop entirely. Passing data={[]} is static empty data and can clear/reinitialize the frame on render.",
+        agentAction: "For live charts, create a ref, omit data, then call ref.current.push() or pushMany(). For static renderChart/MCP snapshots, provide data because renderChart cannot push later."
+      },
+      {
+        id: "streaming.ref-mutations-require-id-accessors",
+        category: "streaming",
+        title: "Ref mutations need stable IDs",
+        severity: "warning",
+        appliesTo: {
+          components: PUSH_MODE_COMPONENTS
+        },
+        summary: "push() and pushMany() can append without IDs, but remove(id) and update(id, updater) require a stable ID accessor: pointIdAccessor for XY/realtime charts, dataIdAccessor for ordinal charts, and nodeIDAccessor/edgeIdAccessor for network operations.",
+        agentAction: "When generating code that calls remove() or update(), include the matching ID accessor and make sure pushed rows carry that ID field."
+      },
+      {
+        id: "rendering.renderchart-static-props",
+        category: "rendering",
+        title: "renderChart uses static props only",
+        severity: "warning",
+        appliesTo: {},
+        summary: "MCP renderChart and semiotic/server renderChart render a single static SVG/PNG snapshot. Browser-only realtime components and future ref pushes are not renderable through that path.",
+        agentAction: "Use renderChart only with renderable HOC components and complete static data. For live behavior, return React code with a ref and do not promise MCP-rendered output."
+      }
+    ];
+    function hasOwn(value, key) {
+      return Object.prototype.hasOwnProperty.call(value, key);
+    }
+    function normalizeProps(props) {
+      return props && typeof props === "object" && !Array.isArray(props) ? props : {};
+    }
+    function appliesToComponent(contract, component) {
+      if (!component) return !contract.appliesTo?.components;
+      const components = contract.appliesTo?.components;
+      return !components || components.includes(component);
+    }
+    function appliesToProps(contract, props) {
+      const propsAny = contract.appliesTo?.propsAny;
+      if (!propsAny || propsAny.length === 0) return true;
+      return propsAny.some((prop) => hasOwn(props, prop) && props[prop] !== void 0);
+    }
+    function behaviorContractsFor2({ component, props } = {}) {
+      const normalizedProps = normalizeProps(props);
+      return BEHAVIOR_CONTRACTS2.filter(
+        (contract) => appliesToComponent(contract, component) && appliesToProps(contract, normalizedProps)
+      );
+    }
+    function normalizeUsageMode2(usageMode) {
+      if (usageMode === "push") return "push";
+      if (usageMode === "static" || usageMode === "renderChart" || usageMode === "server") return "static";
+      return "static";
+    }
+    function dataRequiredForUsageMode2(component, usageMode) {
+      if (!STATIC_DATA_COMPONENTS.has(component)) return false;
+      if (normalizeUsageMode2(usageMode) === "push" && PUSH_MODE_COMPONENTS.includes(component)) return false;
+      return true;
+    }
+    function requiredCombinationsFor(component) {
+      return REQUIRED_COMBINATIONS.filter((entry) => !component || entry.component === component);
+    }
+    function formatRequiredCombination(entry) {
+      const staticRequired = entry.staticRequired || entry.required;
+      const pushRequired = entry.pushRequired || entry.required.filter((prop) => prop !== "data");
+      const pushText = pushRequired.length > 0 ? pushRequired.join(" + ") : "not supported";
+      return `${entry.component}: static ${staticRequired.join(" + ")}; push ${pushText}. ${entry.summary}`;
+    }
+    function formatDoctorBehaviorContracts2(contracts) {
+      if (!contracts || contracts.length === 0) return "";
+      const lines = ["Behavior contracts:"];
+      for (const contract of contracts) {
+        lines.push(`  - [${contract.id}] ${contract.summary}`);
+        if (contract.combinations) {
+          for (const combo of contract.combinations) {
+            lines.push(`    ${formatRequiredCombination(combo)}`);
+          }
+        }
+        lines.push(`    Action: ${contract.agentAction}`);
+      }
+      return lines.join("\n");
+    }
+    function formatBehaviorContractsMarkdown({ compact = false } = {}) {
+      const lines = [
+        compact ? "## Behavior Contracts" : "## AI Behavior Contracts",
+        "",
+        DOC_MARKER_START,
+        "",
+        "These rules are generated from `ai/behaviorContracts.cjs` and are consumed by `semiotic-ai --doctor`, MCP resources, and docs checks.",
+        ""
+      ];
+      for (const contract of BEHAVIOR_CONTRACTS2) {
+        lines.push(`- **${contract.title}** (\`${contract.id}\`): ${contract.summary}`);
+        if (!compact) {
+          lines.push(`  Agent action: ${contract.agentAction}`);
+        }
+        if (contract.combinations) {
+          const combos = contract.combinations.map(formatRequiredCombination).join(" ");
+          lines.push(`  Required combinations: ${combos}`);
+        }
+      }
+      lines.push("", DOC_MARKER_END);
+      return lines.join("\n");
+    }
+    module2.exports = {
+      BEHAVIOR_CONTRACTS: BEHAVIOR_CONTRACTS2,
+      DOC_MARKER_END,
+      DOC_MARKER_START,
+      PUSH_MODE_COMPONENTS,
+      REQUIRED_COMBINATIONS,
+      STATIC_DATA_COMPONENTS,
+      behaviorContractsFor: behaviorContractsFor2,
+      dataRequiredForUsageMode: dataRequiredForUsageMode2,
+      formatBehaviorContractsMarkdown,
+      formatDoctorBehaviorContracts: formatDoctorBehaviorContracts2,
+      normalizeUsageMode: normalizeUsageMode2,
+      requiredCombinationsFor
+    };
+  }
+});
+
 // node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -31460,9 +32151,12 @@ var COMPONENT_REGISTRY = {
   Scatterplot: { component: import_ai.Scatterplot, category: "xy" },
   BubbleChart: { component: import_ai.BubbleChart, category: "xy" },
   Heatmap: { component: import_ai.Heatmap, category: "xy" },
+  ScatterplotMatrix: { component: import_ai.ScatterplotMatrix, category: "xy" },
+  MinimapChart: { component: import_ai.MinimapChart, category: "xy" },
   ConnectedScatterplot: { component: import_ai.ConnectedScatterplot, category: "xy" },
   QuadrantChart: { component: import_ai.QuadrantChart, category: "xy" },
   MultiAxisLineChart: { component: import_ai.MultiAxisLineChart, category: "xy" },
+  CandlestickChart: { component: import_ai.CandlestickChart, category: "xy" },
   BarChart: { component: import_ai.BarChart, category: "ordinal" },
   StackedBarChart: { component: import_ai.StackedBarChart, category: "ordinal" },
   GroupedBarChart: { component: import_ai.GroupedBarChart, category: "ordinal" },
@@ -31474,7 +32168,10 @@ var COMPONENT_REGISTRY = {
   RidgelinePlot: { component: import_ai.RidgelinePlot, category: "ordinal" },
   PieChart: { component: import_ai.PieChart, category: "ordinal" },
   DonutChart: { component: import_ai.DonutChart, category: "ordinal" },
+  GaugeChart: { component: import_ai.GaugeChart, category: "ordinal" },
   FunnelChart: { component: import_ai.FunnelChart, category: "ordinal" },
+  LikertChart: { component: import_ai.LikertChart, category: "ordinal" },
+  SwimlaneChart: { component: import_ai.SwimlaneChart, category: "ordinal" },
   ForceDirectedGraph: { component: import_ai.ForceDirectedGraph, category: "network" },
   ChordDiagram: { component: import_ai.ChordDiagram, category: "network" },
   SankeyDiagram: { component: import_ai.SankeyDiagram, category: "network" },
@@ -31523,27 +32220,72 @@ ${errors.join("\n")}`
 
 // ai/mcp-server.ts
 var import_ai3 = require("semiotic/ai");
+var {
+  componentIndexFromSchema,
+  metadataForComponent
+} = require_componentMetadata();
+var {
+  formatSuggestionReport,
+  suggestCharts
+} = require_chartSuggestions();
+var {
+  BEHAVIOR_CONTRACTS,
+  behaviorContractsFor,
+  dataRequiredForUsageMode,
+  formatDoctorBehaviorContracts,
+  normalizeUsageMode
+} = require_behaviorContracts();
 var schemaPath = path.resolve(__dirname, "../schema.json");
 var schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));
 var schemaByComponent = {};
 for (const tool of schema.tools) {
   schemaByComponent[tool.function.name] = tool.function;
 }
+var allComponentNames = Object.keys(schemaByComponent).sort();
 var componentNames = Object.keys(COMPONENT_REGISTRY).sort();
 var REPO = "nteract/semiotic";
+function aiFilePath(fileName) {
+  return path.resolve(__dirname, "..", fileName);
+}
+function readAIFile(fileName) {
+  return fs.readFileSync(aiFilePath(fileName), "utf-8");
+}
+function componentIndexJSON() {
+  return JSON.stringify(componentIndexFromSchema(schema), null, 2);
+}
+function textResource(uri, mimeType, text) {
+  return {
+    contents: [{
+      uri: uri.href,
+      mimeType,
+      text
+    }]
+  };
+}
+function promptMessage(text) {
+  return {
+    messages: [{
+      role: "user",
+      content: {
+        type: "text",
+        text
+      }
+    }]
+  };
+}
 async function getSchemaHandler(args) {
   const component = args.component;
   if (!component) {
-    const all = Object.keys(schemaByComponent).sort();
-    const renderable = new Set(Object.keys(COMPONENT_REGISTRY));
-    const list = all.map((name) => renderable.has(name) ? `${name} [renderable]` : name);
+    const list = allComponentNames.map((name) => metadataForComponent(name).renderable ? `${name} [renderable]` : name);
     return {
-      content: [{ type: "text", text: `Available components (${all.length}):
+      content: [{ type: "text", text: `Available components (${allComponentNames.length}):
 ${list.join(", ")}
 
 Components marked [renderable] can be rendered to SVG via renderChart (pass theme parameter for styled output). Others (Realtime*) require a browser environment.
 
-All charts support CSS custom properties for theming (--semiotic-bg, --semiotic-text, --semiotic-grid, etc.) and <ThemeProvider>. Use COLOR_BLIND_SAFE_CATEGORICAL (import from semiotic) for accessible color palettes.
+For full agent context, read MCP resources: semiotic://schema, semiotic://components, semiotic://behavior-contracts, semiotic://system-prompt, semiotic://examples.
+
+All charts support CSS custom properties for theming (--semiotic-bg, --semiotic-text, --semiotic-grid, etc.) and <ThemeProvider>. Use COLOR_BLIND_SAFE_CATEGORICAL (import from semiotic/themes) for accessible color palettes.
 
 Pass { component: '<name>' } to get the prop schema for a specific component.` }]
     };
@@ -31556,226 +32298,25 @@ Pass { component: '<name>' } to get the prop schema for a specific component.` }
       isError: true
     };
   }
-  const renderableNote = COMPONENT_REGISTRY[component] ? "This component can be rendered to SVG via renderChart." : "This component requires a browser environment and cannot be rendered via renderChart.";
+  const renderableNote = metadataForComponent(component).renderable ? "This component can be rendered to SVG via renderChart." : "This component requires a browser environment and cannot be rendered via renderChart.";
+  const contracts = behaviorContractsFor({ component, props: {} });
+  const contractText = contracts.length > 0 ? `
+
+Behavior contracts:
+${JSON.stringify(contracts, null, 2)}` : "";
   return {
     content: [{ type: "text", text: `${renderableNote}
 
-${JSON.stringify(entry, null, 2)}` }]
+${JSON.stringify(entry, null, 2)}${contractText}` }]
   };
 }
 async function suggestChartHandler(args) {
-  const data = args.data;
-  const intent = args.intent;
-  if (!data || !Array.isArray(data) || data.length === 0) {
-    return {
-      content: [{ type: "text", text: "Pass { data: [{ ... }, ...] } with 1-5 sample data objects. Optionally include intent: 'comparison' | 'trend' | 'distribution' | 'relationship' | 'composition' | 'geographic' | 'network' | 'hierarchy'." }],
-      isError: true
-    };
-  }
-  const sample = data[0];
-  if (!sample || typeof sample !== "object") {
-    return {
-      content: [{ type: "text", text: "Data items must be objects with key-value pairs." }],
-      isError: true
-    };
-  }
-  const keys = Object.keys(sample);
-  const suggestions = [];
-  const numericFields = [];
-  const stringFields = [];
-  const dateFields = [];
-  const geoFields = {};
-  const networkFields = {};
-  const hierarchyFields = {};
-  for (const key of keys) {
-    const values = data.map((d) => d[key]).filter((v) => v != null);
-    if (values.length === 0) continue;
-    const first = values[0];
-    if (typeof first === "number") {
-      numericFields.push(key);
-    } else if (typeof first === "string") {
-      if (/^\d{4}[-/]\d{2}/.test(first) && !isNaN(Date.parse(first))) {
-        dateFields.push(key);
-      } else {
-        stringFields.push(key);
-      }
-    }
-    const kl = key.toLowerCase();
-    if (kl === "lat" || kl === "latitude") geoFields.lat = key;
-    if (kl === "lon" || kl === "lng" || kl === "longitude") geoFields.lon = key;
-    if (kl === "source" || kl === "from") networkFields.source = key;
-    if (kl === "target" || kl === "to") networkFields.target = key;
-    if (kl === "value" || kl === "weight" || kl === "amount") networkFields.value = key;
-    if (kl === "children" || kl === "values") hierarchyFields.children = key;
-    if (kl === "parent") hierarchyFields.parent = key;
-  }
-  const hasTime = dateFields.length > 0;
-  const hasCat = stringFields.length > 0;
-  const hasNum = numericFields.length > 0;
-  const hasGeo = geoFields.lat && geoFields.lon;
-  const hasNetwork = networkFields.source && networkFields.target;
-  const hasHierarchy = hierarchyFields.children || hierarchyFields.parent;
-  if (hasNetwork && (!intent || intent === "network")) {
-    const src = networkFields.source;
-    const tgt = networkFields.target;
-    if (networkFields.value) {
-      suggestions.push({
-        component: "SankeyDiagram",
-        confidence: "high",
-        reason: `Data has ${src}\u2192${tgt} with ${networkFields.value} \u2014 ideal for flow visualization`,
-        props: { edges: "data", sourceAccessor: `"${src}"`, targetAccessor: `"${tgt}"`, valueAccessor: `"${networkFields.value}"` }
-      });
-    }
-    suggestions.push({
-      component: "ForceDirectedGraph",
-      confidence: networkFields.value ? "medium" : "high",
-      reason: `Data has ${src}\u2192${tgt} edges \u2014 force layout shows network structure. Nodes are auto-inferred from edges when not provided.`,
-      props: { edges: "data", sourceAccessor: `"${src}"`, targetAccessor: `"${tgt}"` }
-    });
-  }
-  if (hasHierarchy && (!intent || intent === "hierarchy")) {
-    suggestions.push({
-      component: "Treemap",
-      confidence: "high",
-      reason: `Data has nested ${hierarchyFields.children || "parent"} structure \u2014 treemap shows hierarchical proportions`,
-      props: { data: "rootObject", childrenAccessor: `"${hierarchyFields.children || "children"}"`, ...numericFields[0] ? { valueAccessor: `"${numericFields[0]}"` } : {} }
-    });
-    suggestions.push({
-      component: "TreeDiagram",
-      confidence: "medium",
-      reason: "Tree layout shows hierarchical relationships",
-      props: { data: "rootObject", childrenAccessor: `"${hierarchyFields.children || "children"}"` }
-    });
-  }
-  if (hasGeo && (!intent || intent === "geographic")) {
-    const sizeField = numericFields.find((f) => f !== geoFields.lat && f !== geoFields.lon);
-    suggestions.push({
-      component: "ProportionalSymbolMap",
-      confidence: "high",
-      reason: `Data has ${geoFields.lat}/${geoFields.lon} coordinates \u2014 map shows spatial distribution`,
-      props: { points: "data", xAccessor: `"${geoFields.lon}"`, yAccessor: `"${geoFields.lat}"`, ...sizeField ? { sizeBy: `"${sizeField}"` } : {} }
-    });
-  }
-  if (hasTime && hasNum && (!intent || intent === "trend")) {
-    const timeField = dateFields[0];
-    const valueField = numericFields[0];
-    suggestions.push({
-      component: "LineChart",
-      confidence: "high",
-      reason: `Data has dates (${timeField}) and numeric values (${valueField}) \u2014 line chart shows trends over time`,
-      props: { data: "data", xAccessor: `"${timeField}"`, yAccessor: `"${valueField}"`, ...hasCat ? { lineBy: `"${stringFields[0]}"`, colorBy: `"${stringFields[0]}"` } : {} }
-    });
-    if (hasCat) {
-      suggestions.push({
-        component: "StackedAreaChart",
-        confidence: "medium",
-        reason: `Multiple categories (${stringFields[0]}) over time \u2014 stacked area shows composition trends`,
-        props: { data: "data", xAccessor: `"${timeField}"`, yAccessor: `"${valueField}"`, areaBy: `"${stringFields[0]}"`, colorBy: `"${stringFields[0]}"` }
-      });
-    }
+  const result = suggestCharts(args);
+  const content = [{ type: "text", text: formatSuggestionReport(result) }];
+  if (!result.ok) {
+    return { content, isError: true, structuredContent: result };
   }
-  if (hasCat && hasNum && (!intent || intent === "comparison" || intent === "composition" || intent === "distribution")) {
-    const catField = stringFields[0];
-    const valField = numericFields[0];
-    if (!intent || intent === "comparison") {
-      suggestions.push({
-        component: "BarChart",
-        confidence: hasTime ? "medium" : "high",
-        reason: `Categorical field (${catField}) with values (${valField}) \u2014 bar chart for comparison`,
-        props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"` }
-      });
-    }
-    if (stringFields.length >= 2 && (!intent || intent === "composition")) {
-      suggestions.push({
-        component: "StackedBarChart",
-        confidence: "medium",
-        reason: `Two categorical fields (${stringFields.join(", ")}) \u2014 stacked bar shows composition within categories`,
-        props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"`, stackBy: `"${stringFields[1]}"` }
-      });
-    }
-    if (!intent || intent === "distribution") {
-      suggestions.push({
-        component: "Histogram",
-        confidence: "medium",
-        reason: `Numeric distribution of ${valField} \u2014 histogram shows value spread`,
-        props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"` }
-      });
-    }
-    if (!intent || intent === "composition") {
-      const uniqueCats = new Set(data.map((d) => d[catField])).size;
-      if (uniqueCats <= 8) {
-        suggestions.push({
-          component: "DonutChart",
-          confidence: "medium",
-          reason: `${uniqueCats} categories \u2014 donut chart shows proportional composition`,
-          props: { data: "data", categoryAccessor: `"${catField}"`, valueAccessor: `"${valField}"` }
-        });
-      }
-    }
-  }
-  if (numericFields.length >= 2 && (!intent || intent === "relationship")) {
-    const xField = numericFields[0];
-    const yField = numericFields[1];
-    suggestions.push({
-      component: "Scatterplot",
-      confidence: "high",
-      reason: `Two numeric fields (${xField}, ${yField}) \u2014 scatterplot shows relationships`,
-      props: { data: "data", xAccessor: `"${xField}"`, yAccessor: `"${yField}"`, ...hasCat ? { colorBy: `"${stringFields[0]}"` } : {}, ...numericFields[2] ? { sizeBy: `"${numericFields[2]}"` } : {} }
-    });
-    if (numericFields.length >= 3) {
-      suggestions.push({
-        component: "BubbleChart",
-        confidence: "medium",
-        reason: `Three numeric fields \u2014 bubble chart adds size dimension to scatter`,
-        props: { data: "data", xAccessor: `"${xField}"`, yAccessor: `"${yField}"`, sizeBy: `"${numericFields[2]}"` }
-      });
-    }
-    if (numericFields.length >= 2 && hasCat) {
-      suggestions.push({
-        component: "Heatmap",
-        confidence: "medium",
-        reason: `Numeric values across dimensions \u2014 heatmap shows density/intensity`,
-        props: { data: "data", xAccessor: `"${xField}"`, yAccessor: `"${hasCat ? stringFields[0] : yField}"`, valueAccessor: `"${hasCat ? numericFields[0] : numericFields[2] || yField}"` }
-      });
-    }
-  }
-  if (suggestions.length === 0) {
-    const fieldSummary = `Fields: ${keys.join(", ")} (${numericFields.length} numeric, ${stringFields.length} categorical, ${dateFields.length} date)`;
-    return {
-      content: [{ type: "text", text: `Could not confidently recommend a chart type.
-
-${fieldSummary}
-
-Try providing intent ('comparison', 'trend', 'distribution', 'relationship', 'composition', 'geographic', 'network', 'hierarchy') to narrow recommendations, or use getSchema to browse available components.` }]
-    };
-  }
-  const lines = suggestions.map((s, i) => {
-    const propsStr = Object.entries(s.props).map(([k, v]) => `${k}=${v}`).join(" ");
-    return `${i + 1}. **${s.component}** (${s.confidence} confidence)
-   ${s.reason}
-   \`<${s.component} ${propsStr} />\``;
-  });
-  const themingTip = `
----
-**Styling**: All charts respond to CSS custom properties on any ancestor element:
-\`\`\`css
-.my-theme {
-  --semiotic-bg: #fff;           /* chart background */
-  --semiotic-text: #333;         /* primary text */
-  --semiotic-text-secondary: #666; /* tick labels */
-  --semiotic-grid: #e0e0e0;      /* grid lines */
-  --semiotic-border: #e0e0e0;    /* axis lines, borders */
-  --semiotic-font-family: sans-serif;
-  --semiotic-tooltip-bg: rgba(0,0,0,0.85);
-  --semiotic-tooltip-text: white;
-  --semiotic-tooltip-radius: 6px;
-}
-\`\`\`
-Or use \`<ThemeProvider theme="dark">\` / \`<ThemeProvider theme={{ colors: {...}, typography: {...} }}>\`.
-For accessibility, use \`colorScheme={COLOR_BLIND_SAFE_CATEGORICAL}\` (import from \`semiotic\`) \u2014 8-color palette safe for all forms of color blindness.`;
-  return {
-    content: [{ type: "text", text: lines.join("\n\n") + themingTip }]
-  };
+  return { content, structuredContent: result };
 }
 async function renderChartHandler(args) {
   const component = args.component;
@@ -31789,6 +32330,12 @@ async function renderChartHandler(args) {
     };
   }
   if (!COMPONENT_REGISTRY[component]) {
+    if (schemaByComponent[component]) {
+      return {
+        content: [{ type: "text", text: `Component "${component}" is known but cannot be rendered via renderChart. It requires a browser/live environment. Renderable components: ${componentNames.join(", ")}` }],
+        isError: true
+      };
+    }
     return {
       content: [{ type: "text", text: `Unknown component "${component}". Available: ${componentNames.join(", ")}` }],
       isError: true
@@ -31841,9 +32388,16 @@ ${svg}` }],
     content: [{ type: "text", text: svg }]
   };
 }
+function filterUsageModeDiagnoses(component, usageMode, diagnoses) {
+  if (dataRequiredForUsageMode(component, usageMode)) return diagnoses;
+  return diagnoses.filter(
+    (d) => d.code !== "VALIDATION" || d.message !== `"data" is required for ${component}.`
+  );
+}
 async function diagnoseConfigHandler(args) {
   const component = args.component;
   const props = args.props ?? {};
+  const usageMode = normalizeUsageMode(args.usageMode);
   if (!component) {
     return {
       content: [{ type: "text", text: "Missing 'component' field. Provide { component: 'LineChart', props: { ... } }." }],
@@ -31851,21 +32405,31 @@ async function diagnoseConfigHandler(args) {
     };
   }
   const result = (0, import_ai3.diagnoseConfig)(component, props);
-  if (result.ok) {
-    const warnings = result.diagnoses.filter((d) => d.severity === "warning");
+  const diagnoses = filterUsageModeDiagnoses(component, usageMode, result.diagnoses);
+  const ok = diagnoses.every((d) => d.severity === "warning");
+  const usageModeNote = usageMode === "push" ? "Usage mode: push (data prop may be omitted; use a ref to push data).\n\n" : "";
+  if (ok) {
+    const warnings = diagnoses.filter((d) => d.severity === "warning");
     const msg = warnings.length > 0 ? `Configuration looks good with ${warnings.length} warning(s):
 ${warnings.map((w) => `\u26A0 [${w.code}] ${w.message}
   Fix: ${w.fix}`).join("\n")}` : `\u2713 Configuration looks good \u2014 no issues detected.`;
-    return { content: [{ type: "text", text: msg }] };
+    const contracts = formatDoctorBehaviorContracts(behaviorContractsFor({ component, props }));
+    return { content: [{ type: "text", text: `${usageModeNote}${contracts ? `${msg}
+
+${contracts}` : msg}` }] };
   }
-  const lines = result.diagnoses.map((d) => {
+  const lines = diagnoses.map((d) => {
     const icon = d.severity === "error" ? "\u2717" : "\u26A0";
     const fixLine = d.fix ? `
   Fix: ${d.fix}` : "";
     return `${icon} [${d.code}] ${d.message}${fixLine}`;
   });
   return {
-    content: [{ type: "text", text: lines.join("\n") }],
+    content: [{ type: "text", text: [
+      usageModeNote.trim(),
+      lines.join("\n"),
+      formatDoctorBehaviorContracts(behaviorContractsFor({ component, props }))
+    ].filter(Boolean).join("\n\n") }],
     isError: true
   };
 }
@@ -31974,6 +32538,120 @@ function createServer2() {
     name: "semiotic",
     version: schema.version || "3.0.0"
   });
+  srv.registerResource(
+    "semiotic-schema",
+    "semiotic://schema",
+    {
+      title: "Semiotic Component Schema",
+      description: "Machine-readable JSON schema for all Semiotic AI chart components.",
+      mimeType: "application/json"
+    },
+    (uri) => textResource(uri, "application/json", JSON.stringify(schema, null, 2))
+  );
+  srv.registerResource(
+    "semiotic-components",
+    "semiotic://components",
+    {
+      title: "Semiotic Component Index",
+      description: "Renderable/browser-only component index with MCP categories.",
+      mimeType: "application/json"
+    },
+    (uri) => textResource(uri, "application/json", componentIndexJSON())
+  );
+  srv.registerResource(
+    "semiotic-behavior-contracts",
+    "semiotic://behavior-contracts",
+    {
+      title: "Semiotic AI Behavior Contracts",
+      description: "Agent-visible semantic rules for color precedence, required prop combinations, streaming refs, and renderability.",
+      mimeType: "application/json"
+    },
+    (uri) => textResource(uri, "application/json", JSON.stringify({
+      version: schema.version,
+      contracts: BEHAVIOR_CONTRACTS
+    }, null, 2))
+  );
+  srv.registerResource(
+    "semiotic-system-prompt",
+    "semiotic://system-prompt",
+    {
+      title: "Semiotic AI System Prompt",
+      description: "Compact implementation guidance for AI assistants building with Semiotic.",
+      mimeType: "text/markdown"
+    },
+    (uri) => textResource(uri, "text/markdown", readAIFile("system-prompt.md"))
+  );
+  srv.registerResource(
+    "semiotic-examples",
+    "semiotic://examples",
+    {
+      title: "Semiotic AI Examples",
+      description: "Copy-paste examples for common Semiotic chart data shapes.",
+      mimeType: "text/markdown"
+    },
+    (uri) => textResource(uri, "text/markdown", readAIFile("examples.md"))
+  );
+  srv.registerPrompt(
+    "build-semiotic-chart",
+    {
+      title: "Build a Semiotic chart",
+      description: "Workflow for choosing a chart, validating props, and rendering a preview.",
+      argsSchema: {
+        intent: external_exports3.string().optional().describe("Visualization intent, e.g. trend, comparison, distribution, relationship, composition, network, hierarchy."),
+        dataDescription: external_exports3.string().optional().describe("Brief description of the data fields and sample rows."),
+        component: external_exports3.string().optional().describe("Optional preferred Semiotic component name.")
+      }
+    },
+    (args) => promptMessage([
+      "Build a production-ready Semiotic visualization.",
+      "",
+      `Intent: ${args.intent || "not specified"}`,
+      `Data: ${args.dataDescription || "not specified"}`,
+      `Preferred component: ${args.component || "not specified"}`,
+      "",
+      "Use this MCP workflow:",
+      "1. Read semiotic://system-prompt for compact API rules and pitfalls.",
+      "2. Read semiotic://behavior-contracts for semantic rules that schema shape alone cannot express.",
+      "3. If no component is specified, call suggestChart with 1-5 representative sample rows and the intent.",
+      "4. Call getSchema for the selected component before writing JSX or renderChart props.",
+      '5. Call diagnoseConfig with usageMode="static" for renderChart/static data, or usageMode="push" for ref-based React code that intentionally omits data.',
+      "6. Fix all diagnoseConfig errors before presenting code.",
+      "7. If the component is renderable and has static data, call renderChart once to verify it returns SVG.",
+      "8. Prefer sub-path imports such as semiotic/xy, semiotic/ordinal, semiotic/network, semiotic/geo, or semiotic/ai depending on the surrounding code.",
+      "",
+      "Return the final JSX or renderChart call plus any assumptions about fields, accessors, or aggregation."
+    ].join("\n"))
+  );
+  srv.registerPrompt(
+    "debug-semiotic-chart",
+    {
+      title: "Debug a Semiotic chart",
+      description: "Workflow for diagnosing bad props, rendering failures, and chart-quality issues.",
+      argsSchema: {
+        component: external_exports3.string().optional().describe("Semiotic component name, e.g. BarChart."),
+        problem: external_exports3.string().optional().describe("Observed failure, warning, or visual issue."),
+        props: external_exports3.string().optional().describe("Relevant chart props as JSON or a short summary.")
+      }
+    },
+    (args) => promptMessage([
+      "Debug this Semiotic chart with the MCP server.",
+      "",
+      `Component: ${args.component || "not specified"}`,
+      `Problem: ${args.problem || "not specified"}`,
+      `Props: ${args.props || "not provided"}`,
+      "",
+      "Use this MCP workflow:",
+      "1. Call getSchema for the component and compare the provided props against required props and accessor names.",
+      "2. Read semiotic://behavior-contracts for semantic rules around colors, required combinations, streaming refs, and renderability.",
+      '3. Call diagnoseConfig with usageMode="push" if the code intentionally omits data for a ref-push HOC; otherwise use usageMode="static".',
+      "4. Treat diagnoseConfig errors as blockers and warnings as review items.",
+      "5. If renderable and static data is available, call renderChart with a minimal reproduction to separate configuration issues from rendering bugs.",
+      "6. Check semiotic://examples for a nearby working pattern before inventing new props.",
+      "7. If the result looks like a Semiotic bug, call reportIssue with the component, props summary, diagnoseConfig output, and renderChart result.",
+      "",
+      "Return the smallest safe fix first, then mention any follow-up cleanup or issue-reporting step."
+    ].join("\n"))
+  );
   srv.tool(
     "getSchema",
     `Return the prop schema for a Semiotic chart component. Pass { component: '<name>' } to get its props, or omit component to list all available components. Components marked [renderable] can be passed to renderChart for static SVG output.`,
@@ -31991,7 +32669,7 @@ function createServer2() {
   );
   srv.tool(
     "renderChart",
-    `Render a Semiotic chart to static SVG or PNG. Returns SVG string (default) or Base64-encoded PNG image. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. PNG requires the 'sharp' package to be installed. Available components: ${componentNames.join(", ")}.`,
+    `Render a Semiotic chart to static SVG or PNG. This is a static snapshot path: props must include data immediately, and ref/push-mode charts cannot be rendered through this tool. Returns SVG string (default) or Base64-encoded PNG image. Optionally pass theme CSS custom properties (--semiotic-bg, --semiotic-text, etc.) to style the output. PNG requires the 'sharp' package to be installed. Available components: ${componentNames.join(", ")}.`,
     {
       component: external_exports3.string().describe("Chart component name, e.g. 'LineChart', 'BarChart'"),
       props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
@@ -32002,10 +32680,11 @@ function createServer2() {
   );
   srv.tool(
     "diagnoseConfig",
-    "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, color contrast issues, etc). Checks WCAG color contrast ratios and suggests COLOR_BLIND_SAFE_CATEGORICAL for accessibility. Returns a human-readable diagnostic report with actionable fixes.",
+    "Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, color contrast issues, etc). Pass usageMode='push' for ref-based React HOCs that intentionally omit data; omit usageMode or pass 'static' for renderChart/MCP/server configs where data is required. Checks WCAG color contrast ratios and suggests COLOR_BLIND_SAFE_CATEGORICAL for accessibility. Returns a human-readable diagnostic report with actionable fixes.",
     {
       component: external_exports3.string().describe("Chart component name, e.g. 'LineChart'"),
-      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }.")
+      props: external_exports3.record(external_exports3.string(), external_exports3.unknown()).optional().describe("Chart props object, e.g. { data: [...], xAccessor: 'x' }."),
+      usageMode: external_exports3.enum(["static", "push", "renderChart", "server"]).optional().describe("Validation mode. Use 'push' for ref-based React HOCs that omit data; use 'static' or omit for renderChart/MCP/static data configs.")
     },
     diagnoseConfigHandler
   );
@@ -32073,7 +32752,8 @@ async function main() {
     });
     httpServer.listen(port, () => {
       console.error(`Semiotic MCP server (HTTP) listening on http://localhost:${port}`);
-      console.error("Tools: getSchema, suggestChart, renderChart, diagnoseConfig, reportIssue");
+      console.error("Tools: getSchema, suggestChart, renderChart, diagnoseConfig, reportIssue, applyTheme");
+      console.error("Resources: semiotic://schema, semiotic://components, semiotic://behavior-contracts, semiotic://system-prompt, semiotic://examples");
     });
   } else {
     const srv = createServer2();