@abuswami1996/agent-md 0.1.5 → 0.2.0

package/dist/index.js

@@ -43,11 +43,32 @@ var primitiveNames = Object.keys(schemas);
 function issueToDiagnostic(issue, sourcePath, blockType, line) {
   const unknown = issue.code === "unrecognized_keys";
   const keys = unknown && "keys" in issue ? issue.keys.join(", ") : issue.path.join(".");
-  return { severity: unknown ? "warning" : "error", code: unknown ? "unknown_field" : "invalid_field", message: unknown ? `Unknown field "${keys}" on ::${blockType}.` : `${issue.path.join(".") || blockType}: ${issue.message}`, sourcePath, line, blockType };
+  const field = keys || void 0;
+  return {
+    severity: unknown ? "warning" : "error",
+    code: unknown ? "unknown_field" : "invalid_field",
+    message: unknown ? `Unknown field "${keys}" on ::${blockType}; it will be ignored.` : `Field "${keys || blockType}" is invalid on ::${blockType}: ${issue.message}`,
+    sourcePath,
+    line,
+    blockType,
+    field,
+    suggestion: unknown ? `Remove "${keys}" or replace it with a supported ::${blockType} field.` : `Update "${keys || blockType}" to match the ::${blockType} schema.`,
+    example: primitiveExample(blockType)
+  };
+}
+function primitiveExample(blockType) {
+  const examples = {
+    chart: "type: line\ndata: revenue\nx: month\ny: amount",
+    metric: "label: Revenue\ndata: revenue\nfield: amount\naggregate: sum",
+    table: "data: revenue\ncolumns: [month, amount]",
+    map: "data: locations\nlat: latitude\nlon: longitude",
+    embed: "src: ./artifact.md\nmode: preview"
+  };
+  return examples[blockType];
 }
 function validatePrimitive(name, attrs, sourcePath, line) {
   if (!primitiveNames.includes(name)) {
-    return { diagnostics: [{ severity: "error", code: "unknown_primitive", message: `Unknown directive ::${name}.`, sourcePath, line, blockType: name }] };
+    return { diagnostics: [{ severity: "error", code: "unknown_primitive", message: `Unknown directive ::${name}.`, sourcePath, line, blockType: name, suggestion: "Use a supported Agent Markdown primitive or remove this directive.", example: `Supported primitives: ${primitiveNames.map((primitive) => `::${primitive}`).join(", ")}` }] };
   }
   const result = schemas[name].safeParse(attrs);
   if (result.success) return { attrs: result.data, diagnostics: [] };
@@ -60,41 +81,41 @@ function normalizePrimitive(name, attrs, children, raw, sourcePath, line) {
   const data = validation.attrs;
   switch (name) {
     case "chart":
-      return { node: { ...data, type: "chart", chartType: data.type }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "chart", chartType: data.type, line }, diagnostics: validation.diagnostics };
     case "metric":
-      return { node: { ...data, type: "metric" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "metric", line }, diagnostics: validation.diagnostics };
     case "table":
-      return { node: { ...data, type: "table" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "table", line }, diagnostics: validation.diagnostics };
     case "diagram":
-      return { node: { ...data, type: "diagram", diagramType: data.type }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "diagram", diagramType: data.type, line }, diagnostics: validation.diagnostics };
     case "map":
-      return { node: { ...data, type: "map" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "map", line }, diagnostics: validation.diagnostics };
     case "timeline":
-      return { node: { ...data, type: "timeline" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "timeline", line }, diagnostics: validation.diagnostics };
     case "tabs": {
       const tabs = children.filter((child) => child.type === "component" && child.name === "__tab");
       const tabNodes = tabs.map((tab) => ({ label: String(tab.props?.label ?? ""), value: tab.props?.value ? String(tab.props.value) : void 0, children: Array.isArray(tab.props?.children) ? tab.props.children : [] }));
       const diagnostics = [...validation.diagnostics];
-      if (tabNodes.length === 0) diagnostics.push({ severity: "error", code: "tabs_empty", message: "::tabs requires at least one child ::tab.", sourcePath, line, blockType: "tabs" });
+      if (tabNodes.length === 0) diagnostics.push({ severity: "error", code: "tabs_empty", message: "::tabs requires at least one child ::tab.", sourcePath, line, blockType: "tabs", suggestion: "Add at least one nested ::tab block with a label.", example: ":::tabs\n::::tab\nlabel: Summary\nContent\n::::\n:::" });
       const labels = /* @__PURE__ */ new Set();
       for (const tab of tabNodes) {
-        if (!tab.label) diagnostics.push({ severity: "error", code: "tab_label_required", message: "Each ::tab requires a label.", sourcePath, line, blockType: "tabs" });
-        if (labels.has(tab.label)) diagnostics.push({ severity: "error", code: "tab_label_duplicate", message: `Duplicate tab label "${tab.label}".`, sourcePath, line, blockType: "tabs" });
+        if (!tab.label) diagnostics.push({ severity: "error", code: "tab_label_required", message: "Each ::tab requires a label.", sourcePath, line, blockType: "tabs", field: "label", suggestion: "Add a unique label to each child ::tab.", example: "label: Summary" });
+        if (labels.has(tab.label)) diagnostics.push({ severity: "error", code: "tab_label_duplicate", message: `Duplicate tab label "${tab.label}".`, sourcePath, line, blockType: "tabs", field: "label", suggestion: "Rename one of the duplicate tab labels so each label is unique.", example: "label: Details" });
         labels.add(tab.label);
       }
-      if (typeof data.default === "string" && !labels.has(data.default)) diagnostics.push({ severity: "error", code: "tab_default_missing", message: `Default tab "${data.default}" does not exist.`, sourcePath, line, blockType: "tabs" });
-      return { node: { type: "tabs", default: data.default, variant: data.variant, tabs: tabNodes }, diagnostics };
+      if (typeof data.default === "string" && !labels.has(data.default)) diagnostics.push({ severity: "error", code: "tab_default_missing", message: `Default tab "${data.default}" does not exist.`, sourcePath, line, blockType: "tabs", field: "default", suggestion: "Set default to one of the existing tab labels or remove the default field.", example: tabNodes[0]?.label ? `default: ${tabNodes[0].label}` : void 0 });
+      return { node: { type: "tabs", default: data.default, variant: data.variant, tabs: tabNodes, line }, diagnostics };
     }
     case "callout":
-      return { node: { type: "callout", calloutType: data.type ?? "note", title: data.title, body: data.body, children }, diagnostics: validation.diagnostics };
+      return { node: { type: "callout", calloutType: data.type ?? "note", title: data.title, body: data.body, children, line }, diagnostics: validation.diagnostics };
     case "embed":
-      return { node: { ...data, type: "embed" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "embed", line }, diagnostics: validation.diagnostics };
     case "form":
-      return { node: { type: "form", title: data.title, description: data.description, submitLabel: data.submitLabel, fields: data.fields.map((field) => ({ ...field, fieldType: field.type })) }, diagnostics: validation.diagnostics };
+      return { node: { type: "form", title: data.title, description: data.description, submitLabel: data.submitLabel, fields: data.fields.map((field) => ({ ...field, fieldType: field.type })), line }, diagnostics: validation.diagnostics };
     case "query":
-      return { node: { ...data, type: "query" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "query", line }, diagnostics: validation.diagnostics };
     case "component":
-      return { node: { ...data, type: "component" }, diagnostics: validation.diagnostics };
+      return { node: { ...data, type: "component", line }, diagnostics: validation.diagnostics };
     default:
       return { node: { type: "error", message: `Unsupported directive ::${name}`, raw, line }, diagnostics: validation.diagnostics };
   }
@@ -136,7 +157,7 @@ import YAML from "yaml";
 function parseAgentMarkdown({ source, sourcePath }) {
   const diagnostics = [];
   const { frontmatter, body } = extractFrontmatter(source, sourcePath, diagnostics);
-  if (/<script[\s>]/i.test(body)) diagnostics.push({ severity: "error", code: "script_blocked", message: "Scripts must never execute from Markdown content.", sourcePath });
+  if (/<script[\s>]/i.test(body)) diagnostics.push({ severity: "error", code: "script_blocked", message: "Scripts must never execute from Markdown content.", sourcePath, suggestion: "Remove the script tag and use Agent Markdown primitives for interactive content." });
   const { body: withoutData, dataSources } = extractDataBlocks(body, sourcePath, diagnostics);
   const nodes = parseDocumentBlocks(withoutData.split(/\r?\n/), sourcePath, diagnostics, 0, 1);
   return { format: "agent-md", version: String(frontmatter?.version ?? "0.1"), sourcePath, frontmatter, nodes, dataSources, diagnostics };
@@ -150,7 +171,7 @@ function extractFrontmatter(source, sourcePath, diagnostics) {
     const parsed = YAML.parse(raw) ?? {};
     return { frontmatter: typeof parsed === "object" ? parsed : {}, body: source.slice(end + 5).replace(/^\r?\n/, "") };
   } catch (error) {
-    diagnostics.push({ severity: "error", code: "frontmatter_parse_error", message: error instanceof Error ? error.message : "Invalid frontmatter", sourcePath, line: 1 });
+    diagnostics.push({ severity: "error", code: "frontmatter_parse_error", message: error instanceof Error ? error.message : "Invalid frontmatter", sourcePath, line: 1, suggestion: "Fix the YAML frontmatter or remove the frontmatter block.", example: "---\nformat: agent-md\nversion: 0.1\n---" });
     return { frontmatter: void 0, body: source.slice(end + 5).replace(/^\r?\n/, "") };
   }
 }
@@ -174,7 +195,7 @@ function extractDataBlocks(source, sourcePath, diagnostics) {
     try {
       dataSources[id] = parseInlineData(id, format, content.join("\n"));
     } catch (error) {
-      diagnostics.push({ severity: "error", code: "data_parse_error", message: error instanceof Error ? error.message : `Unable to parse data source ${id}`, sourcePath, line: startLine, blockType: "data" });
+      diagnostics.push({ severity: "error", code: "data_parse_error", message: error instanceof Error ? error.message : `Unable to parse data source ${id}`, sourcePath, line: startLine, blockType: "data", field: id, suggestion: `Fix the inline ${format} data block for "${id}" or replace it with a local data file reference.`, example: "```data revenue\nmonth,amount\nJan,10\n```" });
     }
   }
   return { body: kept.join("\n"), dataSources };
@@ -252,7 +273,7 @@ function parseDocumentBlocks(lines, sourcePath, diagnostics, depth, baseLine) {
       block.content.push(current);
     }
     if (depth >= 5) {
-      diagnostics.push({ severity: "error", code: "max_nesting_depth", message: "Directive nesting depth exceeds 5.", sourcePath, line: block.startLine, blockType: name });
+      diagnostics.push({ severity: "error", code: "max_nesting_depth", message: "Directive nesting depth exceeds 5.", sourcePath, line: block.startLine, blockType: name, suggestion: "Flatten nested directives so no block is nested more than five levels deep." });
       nodes.push({ type: "error", message: "Directive nesting depth exceeds 5.", raw: block.raw.join("\n"), line: block.startLine });
       continue;
     }
@@ -301,7 +322,7 @@ function splitPropsAndBody(lines, sourcePath, startLine, diagnostics) {
       const parsed = YAML.parse(yamlText);
       attrs = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
     } catch (error) {
-      diagnostics.push({ severity: "error", code: "directive_yaml_error", message: error instanceof Error ? error.message : "Invalid directive YAML", sourcePath, line: startLine });
+      diagnostics.push({ severity: "error", code: "directive_yaml_error", message: error instanceof Error ? error.message : "Invalid directive YAML", sourcePath, line: startLine, suggestion: "Fix the YAML fields at the top of this directive before the body content.", example: "title: Example\ndata: revenue" });
     }
   }
   return { attrs, body: lines.slice(splitAt).join("\n"), bodyOffset: splitAt + 1 };
@@ -328,7 +349,10 @@ Rules:
 - Do not emit JavaScript.
 - Prefer named data blocks or local files.
 - Add frontmatter with format: agent-md and version: 0.1.
-- Run agent-md validate before considering a document complete.
+- Run agent-md validate --file <file.agent.md> --json --for-agent before considering a document complete.
+- If validation returns errors, repair the document and validate again. Treat warnings as worth reviewing, not necessarily fatal unless the user asked for strict validation.
+- When the user wants a shareable rendered artifact, run agent-md convert --file_name <file.agent.md> --html after validation.
+- When browser/manual preview is useful, run agent-md serve --root <project> --host 127.0.0.1 --port <port> --no-open and inspect the local viewer.
 
 Supporting files in this skill directory:
 - agent-md.config.json: default runtime configuration.
@@ -343,6 +367,42 @@ Supported MVP primitives:
 - ::callout for notes, warnings, decisions, risks, and tips.
 - ::tabs for grouped alternative views.
 - ::diagram, ::timeline, ::query, ::embed, ::form, ::map, and ::component are supported with conservative validation and graceful fallbacks.
+
+Authoring workflow for agents:
+- Start with a small valid report, then add primitives incrementally.
+- Prefer inline summary data for charts when source files are large; use the full local file for tables or queries.
+- Keep directive YAML fields aligned to column 1 inside the directive block. Do not indent top-level fields like data:, x:, y:, or fields:.
+- Use YAML block scalars for prose containing colons, quotes, or backticks, for example body: >- on callouts.
+- For callouts, prefer an explicit body: field when the body is short prose.
+- For forms, each field uses type: text, number, select, checkbox, or date. Select fields need options.
+- For tabs, each child tab needs a unique label, and default must match one of those labels.
+- For diagrams, inline source is safest. src may reference a local .mmd or .mermaid file inside the project.
+- For embeds, use local project files. Markdown, text, JSON, CSV, TSV, images, PDFs, and videos are the safest choices. HTML embeds are blocked unless trusted config explicitly allows them.
+- Do not reference remote data or artifacts unless the project config explicitly allows it; the default config is local-only.
+- Custom components render as safe placeholders unless allowCustomComponents is enabled for a trusted project.
+
+Useful commands:
+- agent-md init --agent cursor
+- agent-md validate --file <file.agent.md> --json --for-agent
+- agent-md validate --file <file.agent.md> --strict
+- agent-md validate --root <project-root> --config agent-md.config.json
+- agent-md convert --file_name <file.agent.md> --html
+- agent-md convert --file-name <file.agent.md> --html --output <output.html>
+- agent-md convert --file_name <file.agent.md> --html --root <project-root> --config agent-md.config.json
+- agent-md serve --root <project-root> --host 127.0.0.1 --port 3847 --no-open
+- agent-md serve --root <project-root> --all-md --no-open
+- agent-md export <file.agent.md> --format json
+- agent-md export <file.agent.md> --format markdown-fallback
+- agent-md vscode-extension --editor cursor
+
+Validation and repair notes:
+- --json --for-agent gives compact deterministic diagnostics with sourcePath, line, blockType, field, suggestion, and example.
+- Error diagnostics must be fixed before sharing. Info diagnostics, such as table pagination, can be acceptable.
+- unknown_field warnings usually mean the field will be ignored; remove the field or replace it with a supported schema field.
+- directive_yaml_error usually means malformed YAML inside a directive; check indentation, colons in prose, and unmatched brackets.
+- column_not_found and column_not_numeric mean the data loaded, but a primitive points at the wrong column or type.
+- data_file_error and artifact_file_error usually mean the referenced local path is missing, escapes the project root, or uses an unsupported extension.
+- After a clean validation, convert to HTML. When you're finished, tell the user how they can view the report either in their IDE or in a browser.
 `;
 var exampleAgentMarkdown = `---
 format: agent-md
@@ -423,7 +483,7 @@ import path from "path";
 import YAML2 from "yaml";
 import Papa from "papaparse";
 var dataExtensions = /* @__PURE__ */ new Set([".csv", ".tsv", ".json", ".yaml", ".yml", ".geojson"]);
-var artifactExtensions = /* @__PURE__ */ new Set([".pdf", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webm", ".mp4", ".html", ".txt", ".md", ".mmd", ".mermaid", ".csv", ".json"]);
+var artifactExtensions = /* @__PURE__ */ new Set([".pdf", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webm", ".mp4", ".html", ".txt", ".md", ".mmd", ".mermaid", ".csv", ".tsv", ".json"]);
 function isRemoteRef(ref) {
   return /^https?:\/\//i.test(ref);
 }
@@ -510,16 +570,13 @@ async function resolveDocumentData(document, projectRoot, config = defaultConfig
   const refs = [...new Set(document.nodes.flatMap(collectNodeDataRefs))];
   for (const ref of refs) {
     if (dataSources[ref]) continue;
-    if (isRemoteRef(ref)) {
-      diagnostics.push({ severity: "error", code: "remote_data_blocked", message: `Remote data reference is blocked: ${ref}`, sourcePath: document.sourcePath });
-      continue;
-    }
+    if (isRemoteRef(ref)) continue;
     if (dataExtensions.has(path.extname(ref).toLowerCase())) {
       try {
         const loaded = await loadDataFile(projectRoot, document.sourcePath, ref, config.limits);
         dataSources[ref] = loaded;
       } catch (error) {
-        diagnostics.push({ severity: "error", code: "data_file_error", message: error instanceof Error ? error.message : `Unable to load data source ${ref}`, sourcePath: document.sourcePath });
+        diagnostics.push({ severity: "error", code: "data_file_error", message: error instanceof Error ? error.message : `Unable to load data source ${ref}`, sourcePath: document.sourcePath, field: ref, suggestion: `Confirm "${ref}" exists inside the project and uses a supported data extension.`, example: "data: ./data/revenue.csv" });
       }
     }
   }
@@ -531,23 +588,33 @@ function validateReferences(nodes, dataSources, sourcePath, config = defaultConf
   const diagnostics = [];
   const visit = (node) => {
     const refs = collectNodeDataRefs(node);
-    for (const ref of refs) if (!dataSources[ref] && !dataExtensions.has(path.extname(ref).toLowerCase())) diagnostics.push({ severity: "error", code: "data_not_found", message: `Data source "${ref}" was not found.`, sourcePath, blockType: node.type });
+    for (const ref of refs) {
+      if (isRemoteRef(ref)) {
+        diagnostics.push({ severity: "error", code: "remote_data_blocked", message: `Remote data reference is blocked because remote data is disabled: ${ref}`, sourcePath, line: node.line, blockType: node.type, field: "data", suggestion: "Use a local inline data block or a local file path instead of an HTTP URL.", example: "data: ./data/revenue.csv" });
+      } else if (!dataSources[ref] && !dataExtensions.has(path.extname(ref).toLowerCase())) {
+        diagnostics.push({ severity: "error", code: "data_not_found", message: `Data source "${ref}" was not found.`, sourcePath, line: node.line, blockType: node.type, field: "data", suggestion: `Add an inline data block named "${ref}" or change the data field to an existing data source.`, example: `\`\`\`data ${ref}
+name,value
+Example,1
+\`\`\`` });
+      }
+    }
     const columnsByData = getReferencedColumns(node);
     for (const [data, columns] of Object.entries(columnsByData)) {
       const source = dataSources[data];
       if (!source?.columns || columns.length === 0) continue;
       const known = new Set(source.columns.map((column) => column.name));
-      for (const column of columns) if (!known.has(column)) diagnostics.push({ severity: "error", code: "column_not_found", message: `Column "${column}" was not found in data source "${data}".`, sourcePath, blockType: node.type });
+      const available = source.columns.map((column) => column.name).join(", ");
+      for (const column of columns) if (!known.has(column)) diagnostics.push({ severity: "error", code: "column_not_found", message: `Column "${column}" was not found in data source "${data}".`, sourcePath, line: node.line, blockType: node.type, field: column, suggestion: available ? `Use one of the available columns: ${available}.` : `Add "${column}" to data source "${data}" or update the directive field.`, example: columnExample(node, source.columns[0]?.name) });
     }
     if (node.type === "chart") {
       const rows = dataSources[node.data]?.rows?.length ?? 0;
-      if (rows > config.limits.maxChartRows) diagnostics.push({ severity: "warning", code: "chart_row_limit", message: `Chart uses ${rows} rows, above the ${config.limits.maxChartRows} row target.`, sourcePath, blockType: "chart" });
+      if (rows > config.limits.maxChartRows) diagnostics.push({ severity: "warning", code: "chart_row_limit", message: `Chart uses ${rows} rows, above the ${config.limits.maxChartRows} row target.`, sourcePath, line: node.line, blockType: "chart", suggestion: "Filter, aggregate, or sample the data before charting it." });
     }
     if (node.type === "table") {
       const rows = dataSources[node.data]?.rows?.length ?? 0;
-      if (rows > 500 && node.pagination !== false) diagnostics.push({ severity: "info", code: "table_paginated", message: "Tables over 500 rows are paginated by default.", sourcePath, blockType: "table" });
+      if (rows > 500 && node.pagination !== false) diagnostics.push({ severity: "info", code: "table_paginated", message: "Tables over 500 rows are paginated by default.", sourcePath, line: node.line, blockType: "table", suggestion: "Set pageSize or filter the data if the first page is too broad." });
     }
-    if (node.type === "component" && !config.security.allowCustomComponents) diagnostics.push({ severity: "warning", code: "custom_component_disabled", message: `Registered component "${node.name}" will render as a placeholder because custom components are disabled.`, sourcePath, blockType: "component" });
+    if (node.type === "component" && !config.security.allowCustomComponents) diagnostics.push({ severity: "warning", code: "custom_component_disabled", message: `Registered component "${node.name}" will render as a placeholder because custom components are disabled.`, sourcePath, line: node.line, blockType: "component", suggestion: "Enable custom components in config only for trusted projects, or replace this with a built-in primitive." });
     diagnostics.push(...validatePrimitiveSemantics(node, dataSources, sourcePath));
     if (node.type === "tabs") node.tabs.forEach((tab) => tab.children.forEach(visit));
     if (node.type === "callout") node.children?.forEach(visit);
@@ -558,28 +625,28 @@ function validateReferences(nodes, dataSources, sourcePath, config = defaultConf
 async function validateLocalArtifacts(nodes, projectRoot, sourcePath, config) {
   const diagnostics = [];
   const visit = async (node) => {
-    if (node.type === "embed") await validateArtifactRef(node.src, "embed", projectRoot, sourcePath, config, diagnostics);
-    if (node.type === "diagram" && node.src) await validateArtifactRef(node.src, "diagram", projectRoot, sourcePath, config, diagnostics);
+    if (node.type === "embed") await validateArtifactRef(node.src, "embed", projectRoot, sourcePath, config, diagnostics, node.line);
+    if (node.type === "diagram" && node.src) await validateArtifactRef(node.src, "diagram", projectRoot, sourcePath, config, diagnostics, node.line);
     if (node.type === "tabs") for (const tab of node.tabs) for (const child of tab.children) await visit(child);
     if (node.type === "callout") for (const child of node.children ?? []) await visit(child);
   };
   for (const node of nodes) await visit(node);
   return diagnostics;
 }
-async function validateArtifactRef(ref, blockType, projectRoot, sourcePath, config, diagnostics) {
+async function validateArtifactRef(ref, blockType, projectRoot, sourcePath, config, diagnostics, line) {
   if (isRemoteRef(ref)) {
-    diagnostics.push({ severity: "error", code: "remote_artifact_blocked", message: `Remote artifact reference is blocked: ${ref}`, sourcePath, blockType });
+    diagnostics.push({ severity: "error", code: "remote_artifact_blocked", message: `Remote artifact reference is blocked because remote artifacts are not loaded inline: ${ref}`, sourcePath, line, blockType, field: "src", suggestion: "Download the artifact into the project and reference it with a local relative path.", example: "src: ./artifacts/summary.md" });
     return;
   }
   try {
     const absolute = await resolveSafeRealPath(projectRoot, sourcePath, ref);
     const ext = path.extname(absolute).toLowerCase();
-    if (!artifactExtensions.has(ext) && blockType === "embed") diagnostics.push({ severity: "error", code: "unsupported_artifact", message: `Unsupported artifact extension: ${ext}`, sourcePath, blockType });
-    if (ext === ".html" && !config.security.allowHtmlEmbeds) diagnostics.push({ severity: "error", code: "html_embed_blocked", message: "HTML embeds are blocked by default.", sourcePath, blockType });
+    if (!artifactExtensions.has(ext) && blockType === "embed") diagnostics.push({ severity: "error", code: "unsupported_artifact", message: `Unsupported artifact extension: ${ext}`, sourcePath, line, blockType, field: "src", suggestion: "Use a supported local artifact type or link to the file from regular Markdown." });
+    if (ext === ".html" && !config.security.allowHtmlEmbeds) diagnostics.push({ severity: "error", code: "html_embed_blocked", message: "HTML embeds are opened or blocked for safety rather than executed inline.", sourcePath, line, blockType, field: "src", suggestion: "Use mode: link for HTML artifacts, or convert the content to Markdown/data primitives.", example: "mode: link" });
     const stat = await fs.stat(absolute);
-    if (stat.size > config.limits.maxEmbedSizeMb * 1024 * 1024) diagnostics.push({ severity: "error", code: "embed_size_limit", message: `Artifact exceeds ${config.limits.maxEmbedSizeMb} MB limit.`, sourcePath, blockType });
+    if (stat.size > config.limits.maxEmbedSizeMb * 1024 * 1024) diagnostics.push({ severity: "error", code: "embed_size_limit", message: `Artifact exceeds ${config.limits.maxEmbedSizeMb} MB limit.`, sourcePath, line, blockType, field: "src", suggestion: "Reduce the artifact size or link to it instead of previewing it." });
   } catch (error) {
-    diagnostics.push({ severity: "error", code: "artifact_file_error", message: error instanceof Error ? error.message : `Unable to access artifact ${ref}`, sourcePath, blockType });
+    diagnostics.push({ severity: "error", code: "artifact_file_error", message: error instanceof Error ? error.message : `Unable to access artifact ${ref}`, sourcePath, line, blockType, field: "src", suggestion: `Confirm "${ref}" exists inside the project and does not escape the project root.` });
   }
 }
 function validatePrimitiveSemantics(node, dataSources, sourcePath) {
@@ -589,37 +656,46 @@ function validatePrimitiveSemantics(node, dataSources, sourcePath) {
     const numericColumns = Array.isArray(node.y) ? node.y : node.y ? [node.y] : [];
     if (node.chartType === "pie" && node.value) numericColumns.push(node.value);
     for (const column of numericColumns) {
-      if (columnType(source, column) && columnType(source, column) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${column}" must be numeric for ::chart.`, sourcePath, blockType: "chart" });
+      if (columnType(source, column) && columnType(source, column) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${column}" must be numeric for ::chart.`, sourcePath, line: node.line, blockType: "chart", field: column, suggestion: `Use a numeric column for "${column}" or convert the data values to numbers.`, example: `${node.chartType === "pie" ? "value" : "y"}: amount` });
     }
   }
   if (node.type === "metric" && node.data && node.field && node.aggregate && node.aggregate !== "count") {
-    if (columnType(dataSources[node.data], node.field) && columnType(dataSources[node.data], node.field) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${node.field}" must be numeric for metric aggregation.`, sourcePath, blockType: "metric" });
+    if (columnType(dataSources[node.data], node.field) && columnType(dataSources[node.data], node.field) !== "number") diagnostics.push({ severity: "error", code: "column_not_numeric", message: `Column "${node.field}" must be numeric for metric aggregation.`, sourcePath, line: node.line, blockType: "metric", field: node.field, suggestion: "Use aggregate: count for non-numeric data, or point field at a numeric column.", example: "aggregate: count" });
   }
   if (node.type === "map") {
     const rows = dataSources[node.data]?.rows ?? [];
-    if (node.lat && columnType(dataSources[node.data], node.lat) !== "number") diagnostics.push({ severity: "error", code: "lat_not_numeric", message: `Latitude column "${node.lat}" must be numeric.`, sourcePath, blockType: "map" });
-    if (node.lon && columnType(dataSources[node.data], node.lon) !== "number") diagnostics.push({ severity: "error", code: "lon_not_numeric", message: `Longitude column "${node.lon}" must be numeric.`, sourcePath, blockType: "map" });
+    if (node.lat && columnType(dataSources[node.data], node.lat) && columnType(dataSources[node.data], node.lat) !== "number") diagnostics.push({ severity: "error", code: "lat_not_numeric", message: `Latitude column "${node.lat}" must be numeric.`, sourcePath, line: node.line, blockType: "map", field: node.lat, suggestion: "Use a latitude column with numeric decimal degree values.", example: "lat: latitude" });
+    if (node.lon && columnType(dataSources[node.data], node.lon) && columnType(dataSources[node.data], node.lon) !== "number") diagnostics.push({ severity: "error", code: "lon_not_numeric", message: `Longitude column "${node.lon}" must be numeric.`, sourcePath, line: node.line, blockType: "map", field: node.lon, suggestion: "Use a longitude column with numeric decimal degree values.", example: "lon: longitude" });
     for (const row of rows) {
       const lat = node.lat ? Number(row[node.lat]) : void 0;
       const lon = node.lon ? Number(row[node.lon]) : void 0;
-      if (lat != null && Number.isFinite(lat) && (lat < -90 || lat > 90)) diagnostics.push({ severity: "error", code: "lat_out_of_range", message: "Latitude values must be between -90 and 90.", sourcePath, blockType: "map" });
-      if (lon != null && Number.isFinite(lon) && (lon < -180 || lon > 180)) diagnostics.push({ severity: "error", code: "lon_out_of_range", message: "Longitude values must be between -180 and 180.", sourcePath, blockType: "map" });
+      if (lat != null && Number.isFinite(lat) && (lat < -90 || lat > 90)) diagnostics.push({ severity: "error", code: "lat_out_of_range", message: "Latitude values must be between -90 and 90.", sourcePath, line: node.line, blockType: "map", field: node.lat, suggestion: "Fix latitude values so every row is a decimal degree between -90 and 90.", example: "37.7749" });
+      if (lon != null && Number.isFinite(lon) && (lon < -180 || lon > 180)) diagnostics.push({ severity: "error", code: "lon_out_of_range", message: "Longitude values must be between -180 and 180.", sourcePath, line: node.line, blockType: "map", field: node.lon, suggestion: "Fix longitude values so every row is a decimal degree between -180 and 180.", example: "-122.4194" });
     }
   }
   if (node.type === "timeline") {
-    for (const event of node.events ?? []) if (Number.isNaN(Date.parse(event.date))) diagnostics.push({ severity: "error", code: "invalid_date", message: `Timeline event date "${event.date}" is invalid.`, sourcePath, blockType: "timeline" });
+    for (const event of node.events ?? []) if (Number.isNaN(Date.parse(event.date))) diagnostics.push({ severity: "error", code: "invalid_date", message: `Timeline event date "${event.date}" is invalid.`, sourcePath, line: node.line, blockType: "timeline", field: "date", suggestion: "Use ISO-style dates or another format JavaScript can parse reliably.", example: "date: 2026-05-13" });
   }
   if (node.type === "form") {
     const names = /* @__PURE__ */ new Set();
     for (const field of node.fields) {
-      if (names.has(field.name)) diagnostics.push({ severity: "error", code: "duplicate_field", message: `Duplicate form field "${field.name}".`, sourcePath, blockType: "form" });
+      if (names.has(field.name)) diagnostics.push({ severity: "error", code: "duplicate_field", message: `Duplicate form field "${field.name}".`, sourcePath, line: node.line, blockType: "form", field: field.name, suggestion: "Rename one of the duplicate form fields." });
       names.add(field.name);
-      if (field.fieldType === "select" && (!field.options || field.options.length === 0)) diagnostics.push({ severity: "error", code: "select_options_required", message: `Select field "${field.name}" requires options.`, sourcePath, blockType: "form" });
-      if (field.fieldType === "number" && field.default != null && typeof field.default !== "number") diagnostics.push({ severity: "error", code: "default_type_mismatch", message: `Default for "${field.name}" must be a number.`, sourcePath, blockType: "form" });
+      if (field.fieldType === "select" && (!field.options || field.options.length === 0)) diagnostics.push({ severity: "error", code: "select_options_required", message: `Select field "${field.name}" requires options.`, sourcePath, line: node.line, blockType: "form", field: field.name, suggestion: "Add at least one option to this select field.", example: "options: [A, B]" });
+      if (field.fieldType === "number" && field.default != null && typeof field.default !== "number") diagnostics.push({ severity: "error", code: "default_type_mismatch", message: `Default for "${field.name}" must be a number.`, sourcePath, line: node.line, blockType: "form", field: field.name, suggestion: "Use a numeric default value or remove the default.", example: "default: 10" });
     }
   }
   return diagnostics;
 }
+function columnExample(node, fallbackColumn) {
+  const column = fallbackColumn ?? "amount";
+  if (node.type === "chart") return `${node.chartType === "pie" ? "value" : "y"}: ${column}`;
+  if (node.type === "metric") return `field: ${column}`;
+  if (node.type === "table") return `columns: [${column}]`;
+  if (node.type === "map") return `lat: ${column}`;
+  if (node.type === "query") return `select: [${column}]`;
+  return void 0;
+}
 function columnType(source, column) {
   return source?.columns?.find((item) => item.name === column)?.type;
 }
@@ -627,7 +703,7 @@ function columnType(source, column) {
 // src/index.ts
 var program = new Command();
 var cliDir = path2.dirname(fileURLToPath(import.meta.url));
-var cliVersion = "0.1.5";
+var cliVersion = "0.1.6";
 var extensionId = "AbhinavSwaminathan.agent-md-preview";
 var viewerDistCandidates = [
   path2.resolve(cliDir, "../viewer-dist"),
@@ -657,14 +733,15 @@ program.command("init").option("--agent <agent>", "agent skill flavor", "generic
     console.log(pc.gray("Browser fallback: npx agent-md serve"));
   }
 });
-program.command("validate").option("--file <file>", "validate a single file").option("--json", "print JSON diagnostics").option("--strict", "treat warnings as failures").option("--root <root>", "project root", ".").option("--config <config>", "config path", "agent-md.config.json").action(async (options) => {
+program.command("validate").option("--file <file>", "validate a single file").option("--json", "print JSON diagnostics").option("--for-agent", "print compact deterministic JSON for repair agents").option("--strict", "treat warnings as failures").option("--root <root>", "project root", ".").option("--config <config>", "config path", "agent-md.config.json").action(async (options, command) => {
+  if (options.forAgent && !options.json) command.error("error: --for-agent requires --json");
   const root = path2.resolve(options.root);
   const config = await loadConfig(root, options.config);
   const files = options.file ? [path2.resolve(root, options.file)] : await scanMarkdownFiles(root, config, false);
   const results = await Promise.all(files.map((file) => parseAndResolve(file, root, config)));
   const diagnostics = results.flatMap((result) => result.diagnostics);
   if (options.json) {
-    console.log(JSON.stringify({ files: results, diagnostics }, null, 2));
+    console.log(JSON.stringify(options.forAgent ? formatForAgent(results) : { files: results, diagnostics }, null, 2));
   } else {
     printDiagnostics(results);
   }
@@ -703,6 +780,24 @@ program.command("export").argument("file").option("--format <format>", "html | j
   else if (options.format === "markdown-fallback") console.log(renderFallback(document));
   else console.log(renderStaticHtml(document));
 });
+program.command("convert").description("Convert an Agent Markdown document to another format").option("--file_name <file>", "Agent Markdown file to convert").option("--file-name <file>", "Agent Markdown file to convert").option("--html", "write a static HTML file").option("--output <file>", "output file path").option("--root <root>", "project root", ".").option("--config <config>", "config path", "agent-md.config.json").action(async (options, command) => {
+  const root = path2.resolve(options.root);
+  const file = options.file_name ?? options.fileName;
+  if (!file) command.error("error: required option '--file_name <file>' not specified");
+  if (!options.html) command.error("error: convert currently requires '--html'");
+  if (path2.extname(file) !== ".md" || !file.endsWith(".agent.md")) command.error("error: --file_name must point to a .agent.md file");
+  const config = await loadConfig(root, options.config);
+  const inputFile = path2.resolve(root, file);
+  const document = await parseAndResolve(inputFile, root, config);
+  const source = await fs2.readFile(document.sourcePath, "utf8");
+  const outputFile = path2.resolve(root, options.output ?? defaultHtmlOutputPath(file));
+  const html = await buildStaticHtml(document, source, root, config);
+  await fs2.mkdir(path2.dirname(outputFile), { recursive: true });
+  await fs2.writeFile(outputFile, html);
+  console.log(pc.green(`Wrote ${path2.relative(root, outputFile)}`));
+  printDiagnostics([document]);
+  process.exitCode = document.diagnostics.some((diagnostic) => diagnostic.severity === "error") ? 1 : 0;
+});
 program.command("vscode-extension").description("Print or run local VSCode/Cursor extension install instructions").option("--editor <editor>", "editor CLI to use: cursor or code", "cursor").option("--install", "install the bundled VSIX with the editor CLI").option("--force", "force reinstall when using --install", true).action(async (options) => {
   const vsix = await findVsix();
   if (!vsix) {
@@ -812,7 +907,7 @@ async function parseAndResolve(file, root, config) {
   const safeFile = await resolveSafeRealPath(root, path2.join(root, "agent-md.config.json"), file);
   const stat = await fs2.stat(safeFile);
   const diagnostics = [];
-  if (stat.size > config.limits.maxMarkdownSizeMb * 1024 * 1024) diagnostics.push({ severity: "warning", code: "markdown_size", message: `Markdown file exceeds ${config.limits.maxMarkdownSizeMb} MB target.`, sourcePath: safeFile });
+  if (stat.size > config.limits.maxMarkdownSizeMb * 1024 * 1024) diagnostics.push({ severity: "warning", code: "markdown_size", message: `Markdown file exceeds ${config.limits.maxMarkdownSizeMb} MB target.`, sourcePath: safeFile, suggestion: "Split the report or move large data into local data files." });
   const source = await fs2.readFile(safeFile, "utf8");
   const parsed = parseAgentMarkdown({ source, sourcePath: safeFile });
   const resolved = await resolveDocumentData(parsed, root, config);
@@ -828,12 +923,52 @@ function printDiagnostics(results) {
     for (const diagnostic of result.diagnostics) {
       const color = diagnostic.severity === "error" ? pc.red : diagnostic.severity === "warning" ? pc.yellow : pc.blue;
       console.log(color(`  ${diagnostic.severity.toUpperCase()}: ${diagnostic.message}`));
+      console.log(`    Code: ${diagnostic.code}`);
       if (diagnostic.line) console.log(`    Line: ${diagnostic.line}`);
       if (diagnostic.blockType) console.log(`    Block: ::${diagnostic.blockType}`);
+      if (diagnostic.field) console.log(`    Field: ${diagnostic.field}`);
       if (diagnostic.suggestion) console.log(`    Suggestion: ${diagnostic.suggestion}`);
+      if (diagnostic.example) console.log(`    Example: ${diagnostic.example}`);
     }
   }
 }
+function formatForAgent(results) {
+  const files = results.map((result) => {
+    const diagnostics = sortDiagnostics(result.diagnostics).map(compactDiagnostic);
+    return {
+      sourcePath: result.sourcePath,
+      ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+      diagnostics
+    };
+  }).sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+  return {
+    version: 1,
+    ok: files.every((file) => file.ok),
+    files,
+    diagnostics: files.flatMap((file) => file.diagnostics)
+  };
+}
+function sortDiagnostics(diagnostics) {
+  return [...diagnostics].sort(
+    (left, right) => left.sourcePath.localeCompare(right.sourcePath) || (left.line ?? 0) - (right.line ?? 0) || left.severity.localeCompare(right.severity) || left.code.localeCompare(right.code) || left.message.localeCompare(right.message)
+  );
+}
+function compactDiagnostic(diagnostic) {
+  return omitUndefined({
+    severity: diagnostic.severity,
+    code: diagnostic.code,
+    message: diagnostic.message,
+    sourcePath: diagnostic.sourcePath,
+    line: diagnostic.line,
+    blockType: diagnostic.blockType,
+    field: diagnostic.field,
+    suggestion: diagnostic.suggestion,
+    example: diagnostic.example
+  });
+}
+function omitUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
+}
 async function resolveRequestedDocument(root, config, allMd, file) {
   const requested = await resolveSafeRealPath(root, path2.join(root, "agent-md.config.json"), file);
   const allowed = await scanMarkdownFiles(root, config, allMd);
@@ -932,6 +1067,102 @@ async function findViewerDistDir() {
   }
   return void 0;
 }
+function defaultHtmlOutputPath(file) {
+  if (file.endsWith(".agent.md")) return `${file.slice(0, -".agent.md".length)}.html`;
+  return `${file.slice(0, -path2.extname(file).length)}.html`;
+}
+async function buildStaticHtml(document, source, root, config) {
+  const viewerDistDir = await findViewerDistDir();
+  const payload = await buildStaticPayload(document, source, root, config);
+  if (!viewerDistDir) return renderStaticHtml(document, source, payload);
+  const indexPath = path2.join(viewerDistDir, "index.html");
+  let html = await fs2.readFile(indexPath, "utf8");
+  html = stripModulePreloadLinks(html);
+  html = await inlineCssAssets(html, viewerDistDir);
+  html = await inlineScriptAssets(html, viewerDistDir);
+  return html.replace("</head>", `${staticPayloadScript(payload)}</head>`);
+}
+function stripModulePreloadLinks(html) {
+  return html.replace(/<link\b[^>]*\brel="modulepreload"[^>]*>/g, "");
+}
+async function inlineCssAssets(html, viewerDistDir) {
+  const cssLinkPattern = /<link\b([^>]*?)href="([^"]+\.css)"([^>]*)>/g;
+  return replaceAsync(html, cssLinkPattern, async (_match, before, href, after) => {
+    const css = await readViewerAsset(viewerDistDir, href);
+    return `<style data-agent-md-asset="${escapeHtmlAttribute(href)}"${before.includes("media=") || after.includes("media=") ? `${before}${after}`.match(/\smedia="[^"]+"/)?.[0] ?? "" : ""}>
+${css}
+</style>`;
+  });
+}
+async function inlineScriptAssets(html, viewerDistDir) {
+  const scriptPattern = /<script\b([^>]*?)src="([^"]+\.js)"([^>]*)><\/script>/g;
+  return replaceAsync(html, scriptPattern, async (_match, before, src, after) => {
+    const js = await readViewerAsset(viewerDistDir, src);
+    const isModule = `${before}${after}`.includes('type="module"');
+    const dataUrl = `data:text/javascript;base64,${Buffer.from(js).toString("base64")}`;
+    return `<script${isModule ? ' type="module"' : ""} data-agent-md-asset="${escapeHtmlAttribute(src)}" src="${dataUrl}"></script>`;
+  });
+}
+async function readViewerAsset(viewerDistDir, assetPath) {
+  const relative = decodeURIComponent(assetPath.replace(/^\/+/, ""));
+  const absolute = path2.resolve(viewerDistDir, relative);
+  const insideViewer = !path2.relative(viewerDistDir, absolute).startsWith("..") && !path2.isAbsolute(path2.relative(viewerDistDir, absolute));
+  if (!insideViewer) throw new Error(`Viewer asset escapes dist directory: ${assetPath}`);
+  return fs2.readFile(absolute, "utf8");
+}
+async function replaceAsync(source, pattern, replacer) {
+  const matches = [...source.matchAll(pattern)];
+  const replacements = await Promise.all(matches.map((match) => replacer(...match.map((value) => value ?? ""))));
+  let result = source;
+  for (let index = matches.length - 1; index >= 0; index--) {
+    const match = matches[index];
+    result = `${result.slice(0, match.index)}${replacements[index]}${result.slice((match.index ?? 0) + match[0].length)}`;
+  }
+  return result;
+}
+async function buildStaticPayload(document, source, root, config) {
+  return {
+    document,
+    source,
+    artifacts: await collectStaticArtifacts(document, root, config),
+    sourcePathLabel: path2.relative(root, document.sourcePath),
+    title: typeof document.frontmatter?.title === "string" ? document.frontmatter.title : void 0
+  };
+}
+async function collectStaticArtifacts(document, root, config) {
+  const artifacts = {};
+  for (const ref of collectArtifactRefs(document.nodes)) {
+    try {
+      const absolute = await resolveSafeRealPath(root, document.sourcePath, ref);
+      const ext = path2.extname(absolute).toLowerCase();
+      if (!artifactExtensions.has(ext) && !dataExtensions.has(ext)) continue;
+      if (ext === ".html" && !config.security.allowHtmlEmbeds) continue;
+      const stat = await fs2.stat(absolute);
+      if (stat.size > config.limits.maxEmbedSizeMb * 1024 * 1024) continue;
+      const mime = contentType(absolute);
+      if (isTextArtifact(ext)) {
+        artifacts[ref] = { kind: "text", mime, content: await fs2.readFile(absolute, "utf8") };
+      } else {
+        const body = await fs2.readFile(absolute);
+        artifacts[ref] = { kind: "data", mime, dataUrl: `data:${dataUrlMime(mime)};base64,${body.toString("base64")}` };
+      }
+    } catch {
+    }
+  }
+  return artifacts;
+}
+function isTextArtifact(ext) {
+  return [".md", ".mmd", ".mermaid", ".txt", ".json", ".csv", ".tsv"].includes(ext);
+}
+function dataUrlMime(mime) {
+  return mime.split(";")[0]?.trim() || "application/octet-stream";
+}
+function staticPayloadScript(payload) {
+  return `<script>window.__AGENT_MD_STATIC__=${jsonForScript(payload)};</script>`;
+}
+function jsonForScript(value) {
+  return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
 function contentType(file) {
   const ext = path2.extname(file);
   if (ext === ".html") return "text/html; charset=utf8";
@@ -951,14 +1182,39 @@ function contentType(file) {
   return "application/octet-stream";
 }
 function renderFallback(document) {
-  return document.nodes.map((node) => node.type === "markdown" ? node.value : `[${node.type}]`).join("\n\n");
+  const diagnostics = document.diagnostics.length ? `Diagnostics
+${document.diagnostics.map((diagnostic) => `- ${diagnostic.severity}: ${diagnostic.message}${diagnostic.suggestion ? ` Suggestion: ${diagnostic.suggestion}` : ""}`).join("\n")}
+
+` : "";
+  return diagnostics + document.nodes.map((node) => node.type === "markdown" ? node.value : `[${node.type}]`).join("\n\n");
 }
-function renderStaticHtml(document) {
-  return `<!doctype html><meta charset="utf8"><title>Agent Markdown</title><pre>${escapeHtml(JSON.stringify(document, null, 2))}</pre>`;
+function renderStaticHtml(document, source, payload) {
+  return `<!doctype html>
+<html><head><meta charset="utf8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Agent Markdown</title>
+${staticPayloadScript(payload ?? { document, source: source ?? "" })}
+<style>:root{font-family:Inter,ui-sans-serif,system-ui,sans-serif;color:#0f172a;background:#f8fafc}body{margin:0;padding:24px}.agent-md-card{border:1px solid #e2e8f0;border-radius:10px;background:white;padding:16px;margin:12px 0}.agent-md-error{border-color:#ef4444;background:#fef2f2}.diagnostics-panel{border:1px solid #cbd5e1;border-radius:12px;background:white;padding:16px;margin:18px 0}.diagnostic{border-left:4px solid #94a3b8;padding:10px 12px;margin:10px 0;background:#f8fafc}.diagnostic.error{border-color:#ef4444}.diagnostic.warning{border-color:#f59e0b}.diagnostic.info{border-color:#3b82f6}.meta{color:#475569;font-size:13px}pre{white-space:pre-wrap;background:#0f172a;color:#e2e8f0;padding:16px;border-radius:10px;overflow:auto}table{border-collapse:collapse;width:100%}th,td{border:1px solid #e2e8f0;padding:8px;text-align:left}th{background:#f1f5f9}</style></head>
+<body><main><h1>Agent Markdown</h1>${renderStaticDiagnostics(document.diagnostics)}${document.nodes.map(renderStaticNode).join("\n")}</main></body></html>`;
 }
 function escapeHtml(value) {
   return value.replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char]);
 }
+function escapeHtmlAttribute(value) {
+  return escapeHtml(value);
+}
+function renderStaticNode(node) {
+  if (node.type === "markdown") return `<section>${escapeHtml(node.value).replace(/\n/g, "<br>")}</section>`;
+  if (node.type === "metric") return `<section class="agent-md-card"><strong>${escapeHtml(node.label)}</strong><h2>${escapeHtml(String(node.value ?? ""))}</h2></section>`;
+  if (node.type === "table" || node.type === "query") return `<section class="agent-md-card"><strong>${escapeHtml(node.type)}</strong><pre>${escapeHtml(JSON.stringify(node, null, 2))}</pre></section>`;
+  if (node.type === "callout") return `<section class="agent-md-card"><strong>${escapeHtml(node.title ?? node.calloutType)}</strong><p>${escapeHtml(node.body ?? "")}</p></section>`;
+  if (node.type === "tabs") return `<section class="agent-md-card"><strong>Tabs</strong>${node.tabs.map((tab) => `<h3>${escapeHtml(tab.label)}</h3>${tab.children.map(renderStaticNode).join("")}`).join("")}</section>`;
+  if (node.type === "error") return `<section class="agent-md-card agent-md-error"><strong>${escapeHtml(node.message)}</strong><p>Check this block's fields and data references, then run agent-md validate again.</p></section>`;
+  return `<section class="agent-md-card"><strong>${escapeHtml(node.type)}</strong><pre>${escapeHtml(JSON.stringify(node, null, 2))}</pre></section>`;
+}
+function renderStaticDiagnostics(diagnostics) {
+  if (diagnostics.length === 0) return "";
+  const groups = ["error", "warning", "info"].map((severity) => [severity, diagnostics.filter((diagnostic) => diagnostic.severity === severity)]).filter(([, items]) => items.length > 0);
+  return `<section class="diagnostics-panel" aria-label="Diagnostics"><h2>Diagnostics</h2>${groups.map(([severity, items]) => `<h3>${escapeHtml(severity)} (${items.length})</h3>${items.map((diagnostic) => `<article class="diagnostic ${escapeHtml(diagnostic.severity)}"><strong>${escapeHtml(diagnostic.message)}</strong><p class="meta">${escapeHtml([diagnostic.code, diagnostic.line ? `line ${diagnostic.line}` : "", diagnostic.blockType ? `::${diagnostic.blockType}` : "", diagnostic.field ?? ""].filter(Boolean).join(" \xB7 "))}</p>${diagnostic.suggestion ? `<p>Suggestion: ${escapeHtml(diagnostic.suggestion)}</p>` : ""}${diagnostic.example ? `<pre>${escapeHtml(diagnostic.example)}</pre>` : ""}</article>`).join("")}`).join("")}</section>`;
+}
 async function openBrowser(url) {
   await import("child_process").then(({ execFile }) => execFile(process.platform === "darwin" ? "open" : "xdg-open", [url]));
 }