@abuswami1996/agent-md 0.1.6 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- Fixed rendered primitive behavior in the bundled browser viewer, including forms, tabs, timelines, query sorting, and flowchart labels.
+- Added safe static artifact bundling for converted HTML so local embeds and diagram source files render without the live `/artifact` endpoint.
+- Improved live viewer UX for loading, root-level file grouping, stale document selection, diagnostics, and source/sidebar click stability.
+- Expanded the generated Agent Markdown skill with agent-friendly validation, preview, conversion, and repair guidance.
+
 ## 0.1.6
 
 - Added `agent-md convert --file_name <file.agent.md> --html` for writing static HTML files.

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,8 +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.
@@ -345,10 +368,41 @@ Supported MVP primitives:
 - ::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 validate --file <file.agent.md>
+- 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 --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
@@ -429,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);
 }
@@ -516,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" });
       }
     }
   }
@@ -537,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);
@@ -564,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) {
@@ -595,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;
 }
@@ -663,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);
   }
@@ -720,7 +791,7 @@ program.command("convert").description("Convert an Agent Markdown document to an
   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);
+  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)}`));
@@ -836,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);
@@ -852,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);
@@ -960,10 +1071,10 @@ 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) {
+async function buildStaticHtml(document, source, root, config) {
   const viewerDistDir = await findViewerDistDir();
-  const payload = { document, source };
-  if (!viewerDistDir) return renderStaticHtml(document, source);
+  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);
@@ -1009,6 +1120,43 @@ async function replaceAsync(source, pattern, replacer) {
   }
   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>`;
 }
@@ -1034,14 +1182,18 @@ 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, source) {
+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({ 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}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>${document.nodes.map(renderStaticNode).join("\n")}</main></body></html>`;
+${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]);
@@ -1055,9 +1207,14 @@ function renderStaticNode(node) {
   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"><strong>${escapeHtml(node.message)}</strong></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]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abuswami1996/agent-md",
-  "version": "0.1.6",
+  "version": "0.2.0",
   "description": "Local-first Agent Markdown runtime, validator, browser viewer, and agent skill installer.",
   "license": "MIT",
   "author": "Abhinav Swaminathan",

package/viewer-dist/assets/index-CtGGcFUm.css

@@ -0,0 +1 @@
+:root{--background:#f8fafc;--card:#fff;--muted:#f1f5f9;--muted-foreground:#64748b;--foreground:#0f172a;--border:#e2e8f0;--primary:#2563eb;--danger:#dc2626;--warning:#d97706;--agent-md-chart-1:#2563eb;--agent-md-chart-2:#16a34a;--agent-md-chart-3:#f59e0b;color:var(--foreground);background:var(--background);font-family:Inter,ui-sans-serif,system-ui,sans-serif}body{margin:0}.app-frame{background:var(--background);min-height:100vh;padding:16px}.browser-shell{border:1px solid var(--border);background:var(--card);border-radius:10px;flex-direction:column;min-height:min(75vh,680px);display:flex;overflow:hidden}.browser-shell.static-shell{min-height:auto}.file-sidebar{z-index:2;border-bottom:1px solid color-mix(in srgb,var(--border) 60%,transparent);background:var(--card);width:100%;position:relative}.sidebar-strip{background:color-mix(in srgb,var(--muted) 40%,transparent);border-bottom:1px solid color-mix(in srgb,var(--border) 60%,transparent);color:var(--muted-foreground);padding:9px 12px;font-size:12px;font-weight:500}.file-tree{overscroll-behavior:contain;max-height:min(40vh,320px);overflow:auto}.folder-group{border-bottom:1px solid color-mix(in srgb,var(--border) 60%,transparent)}.folder-group:last-child{border-bottom:0}.folder-row{background:color-mix(in srgb,var(--muted) 25%,transparent);align-items:flex-start;gap:8px;padding:8px 12px;display:flex}.folder-name{letter-spacing:.06em;text-transform:uppercase;color:var(--muted-foreground);font-size:11px;font-weight:700}.folder-count{color:color-mix(in srgb,var(--muted-foreground) 80%,transparent);font-size:10px}ul{margin:0;padding:4px 0;list-style:none}.file-row{text-align:left;width:100%;color:var(--muted-foreground);cursor:pointer;background:0 0;border:0;align-items:flex-start;gap:8px;padding:7px 12px;font-size:12px;line-height:1.25;transition:background-color .12s,color .12s;display:flex}.file-row span:nth-child(2){overflow-wrap:anywhere;min-width:0}.file-row:hover{background:color-mix(in srgb,var(--muted) 80%,transparent);color:var(--foreground)}.file-row.active{background:color-mix(in srgb,var(--primary) 10%,transparent);color:var(--foreground);font-weight:500}.tree-icon{flex:none;width:14px;height:14px}.folder-icon{color:var(--muted-foreground)}.file-icon{opacity:.7;margin-top:2px}.status{border-radius:999px;flex:none;width:7px;height:7px;margin-top:4px;margin-left:auto}.ok-dot{background:#16a34a}.warning-dot{background:var(--warning)}.error-dot{background:var(--danger)}.preview-pane{z-index:1;flex-direction:column;flex:1;min-width:0;display:flex;position:relative;overflow:auto}.preview-header{z-index:3;border-bottom:1px solid color-mix(in srgb,var(--border) 60%,transparent);background:var(--card);justify-content:space-between;align-items:flex-start;gap:16px;padding:14px 16px;display:flex;position:sticky;top:0}.preview-header h3{overflow-wrap:anywhere;margin:0;font-size:13px;font-weight:600;line-height:1.35}.preview-header p{color:var(--muted-foreground);margin:3px 0 0;font-size:11px}.mode-button{border:1px solid var(--border);background:var(--card);color:var(--muted-foreground);cursor:pointer;border-radius:6px;padding:5px 8px;font-size:11px}.mode-button:hover{background:var(--muted);color:var(--foreground)}.preview-body{min-width:0;padding:16px;overflow:auto}.diagnostics-panel{border-top:1px solid color-mix(in srgb,var(--border) 60%,transparent);background:color-mix(in srgb,var(--muted) 30%,transparent);padding:8px 12px}.diagnostics-panel p{color:var(--muted-foreground);margin:4px 0;font-size:11px}.empty-state{color:var(--muted-foreground);font-size:13px}.agent-md-document{font-size:13px;line-height:1.55}.agent-md-document h1{margin:0 0 14px;font-size:24px}.agent-md-document h2{margin:18px 0 10px;font-size:18px}.agent-md-document h3{margin:0 0 10px;font-size:13px}.agent-md-card{border:1px solid color-mix(in srgb,var(--border) 75%,transparent);background:var(--card);box-shadow:none;border-radius:8px;margin:10px 0;padding:12px}.agent-md-embed-header{justify-content:space-between;align-items:flex-start;gap:12px;display:flex}.agent-md-embed-header h3{margin-bottom:2px}.agent-md-embed-header small,.agent-md-embed-caption,.agent-md-embed-loading{color:var(--muted-foreground);font-size:11px}.agent-md-embed-header a{color:var(--primary);font-size:12px;text-decoration:none}.agent-md-embed-header a:hover{text-decoration:underline}.agent-md-embed-image,.agent-md-embed-media{border:1px solid var(--border);border-radius:8px;max-width:100%;display:block}.agent-md-embed-markdown{border-top:1px solid var(--border);margin-top:10px;padding-top:10px}.agent-md-embed-text{max-height:360px}.agent-md-metric strong{margin-top:6px;font-size:22px;display:block}.agent-md-error,.error{border-color:color-mix(in srgb,var(--danger) 35%,var(--border));background:color-mix(in srgb,var(--danger) 6%,var(--card))}.warning{border-color:color-mix(in srgb,var(--warning) 35%,var(--border));background:color-mix(in srgb,var(--warning) 6%,var(--card))}.agent-md-tabs>div:first-child{border-bottom:1px solid var(--border);gap:4px;margin-bottom:10px;display:flex}.agent-md-tabs button{color:var(--muted-foreground);cursor:pointer;background:0 0;border:0;padding:6px 8px;font-size:12px}.agent-md-tabs button:hover,.agent-md-tabs button.active{background:var(--muted);color:var(--foreground)}.agent-md-tabs-pill>div:first-child{border-bottom:0}.agent-md-tabs-pill button{border-radius:999px}.agent-md-tabs-pill button.active{background:var(--primary);color:#fff}.agent-md-tabs-card>div:first-child{border-bottom:0}.agent-md-tabs-card button{border:1px solid var(--border);background:var(--card);border-radius:6px}.agent-md-tabs-card button.active{background:var(--muted);border-color:var(--primary)}.agent-md-timeline-horizontal{grid-template-columns:repeat(auto-fit,minmax(180px,1fr));gap:10px;display:grid}.agent-md-timeline-event{border-left:2px solid var(--border);margin:10px 0;padding-left:10px}.agent-md-timeline-horizontal .agent-md-timeline-event{border-left:0;border-top:2px solid var(--border);padding-top:10px;padding-left:0}.agent-md-timeline-group,.agent-md-timeline-description{color:var(--muted-foreground)}.agent-md-form-fields{gap:10px;margin:10px 0;display:grid}.agent-md-form-field{gap:4px;display:grid}.agent-md-form-field-checkbox{align-items:center;gap:8px;display:flex}.agent-md-form-field-checkbox input{width:auto}.agent-md-form input,.agent-md-form select{max-width:360px}.agent-md-form-submit{border:1px solid var(--border);background:var(--primary);color:#fff;cursor:pointer;border-radius:6px;padding:6px 10px;font-size:12px}.agent-md-component-placeholder p{color:var(--muted-foreground);margin-bottom:0}.diagnostics-panel .info{border-color:color-mix(in srgb,var(--primary) 25%,var(--border));background:color-mix(in srgb,var(--primary) 5%,var(--card))}.agent-md-card svg text,.agent-md-card svg tspan{fill:var(--foreground)}.agent-md-card svg foreignObject,.agent-md-card svg .nodeLabel,.agent-md-card svg .nodeLabel p{color:var(--foreground)}.agent-md-simple-flow{color:var(--foreground);flex-wrap:wrap;align-items:center;gap:12px;padding:18px 8px;display:flex}.agent-md-simple-flow-vertical{flex-direction:column;align-items:flex-start}.agent-md-simple-flow-node{color:#0f172a;text-align:center;background:#eef2ff;border:2px solid #8b5cf6;border-radius:8px;min-width:120px;padding:18px 20px;font-weight:700}.agent-md-simple-flow-arrow{color:#0f172a;font-weight:700}table{border-collapse:collapse;width:100%;font-size:12px}th,td{border:1px solid color-mix(in srgb,var(--border) 70%,transparent);text-align:left;padding:6px 8px}th{background:color-mix(in srgb,var(--muted) 45%,transparent);cursor:pointer;color:var(--muted-foreground);font-size:11px}input,select{border:1px solid var(--border);border-radius:6px;padding:6px 8px;font-size:12px}pre{color:#e2e8f0;background:#0f172a;border-radius:8px;padding:12px;font-size:12px;overflow:auto}@media (width>=760px){.browser-shell{flex-direction:row}.file-sidebar{border-bottom:0;border-right:1px solid color-mix(in srgb,var(--border) 60%,transparent);width:min(100%,280px)}.file-tree{max-height:min(75vh,720px)}.preview-body{padding:18px 22px}}@media (width>=1280px){.file-sidebar{width:320px}}