agentic-mermaid 0.1.2 → 0.2.0

package/dist/{chunk-WI35L7IR.js → chunk-FDM43XU7.js}

@@ -13,7 +13,7 @@ import {
   renderPngGraphicalProjection,
   snapshotHostBackendPolicy,
   snapshotResourceManifest
-} from "./chunk-ZYMMKQ3I.js";
+} from "./chunk-BJYMBT4I.js";
 
 // src/agent/png.ts
 import { fileURLToPath } from "url";
@@ -612,4 +612,4 @@ export {
   renderMermaidPNGWithReceipt,
   createMermaidPNGRenderer
 };
-//# sourceMappingURL=chunk-WI35L7IR.js.map
+//# sourceMappingURL=chunk-FDM43XU7.js.map

package/dist/{chunk-4QECACIA.js → chunk-MYPDVZCO.js}

@@ -52,6 +52,7 @@ import {
   normalizeMermaidSource,
   normalizeV11Shape,
   ok,
+  parseAccessibilityDirective,
   parseActorLinks,
   parseClassDeclaration,
   parseClassDiagram,
@@ -92,7 +93,7 @@ import {
   visualWidth,
   wcagCssContrastRatio,
   wrapperPrefix
-} from "./chunk-ZYMMKQ3I.js";
+} from "./chunk-BJYMBT4I.js";
 
 // src/agent/trace-log.ts
 var appendFn;
@@ -2819,26 +2820,25 @@ function collectFlowchartActions(source) {
   return out;
 }
 function actionSourceLines(source, maskMarkdownStrings = false) {
-  const out = [];
   const lines = source.split(/\r?\n/);
-  let inAccessibilityBlock = false;
-  let inMarkdownString = false;
+  const out = [];
   for (let index = 0; index < lines.length; index++) {
-    const preserveActionText = maskMarkdownStrings && !inMarkdownString && splitFlowchartStatements(lines[index]).some((statement) => /^(?:click|href)\s+/i.test(statement.trim()));
-    const masked = maskMarkdownStrings && !preserveActionText ? maskMarkdownStringContent(lines[index], inMarkdownString) : { text: lines[index], open: false };
-    inMarkdownString = masked.open;
-    const text = masked.text.trim();
-    if (inAccessibilityBlock) {
-      if (text.includes("}")) inAccessibilityBlock = false;
-      continue;
+    const directive = parseAccessibilityDirective(lines, index);
+    if (directive === void 0) break;
+    if (directive === null) out.push({ text: lines[index].trim(), line: index + 1 });
+    else {
+      if (directive.suffixLine) out.push({ text: directive.suffixLine.trim(), line: directive.endIndex + 1 });
+      index = directive.endIndex;
     }
-    const block = text.match(/^accDescr\s*:?\s*\{\s*(.*)$/i);
-    if (block) {
-      if (!block[1].includes("}")) inAccessibilityBlock = true;
-      continue;
-    }
-    if (/^acc(?:Title|Descr)(?:\s*:|\s+)/i.test(text)) continue;
-    out.push({ text, line: index + 1 });
+  }
+  if (!maskMarkdownStrings) return out;
+  let inMarkdownString = false;
+  for (const sourceLine of out) {
+    const preserveActionText = !inMarkdownString && splitFlowchartStatements(sourceLine.text).some((statement) => /^(?:click|href)\s+/i.test(statement.trim()));
+    if (preserveActionText) continue;
+    const masked = maskMarkdownStringContent(sourceLine.text, inMarkdownString);
+    inMarkdownString = masked.open;
+    sourceLine.text = masked.text.trim();
   }
   return out;
 }
@@ -4699,4 +4699,4 @@ export {
   layoutMermaidWithReceipt,
   layoutMermaid
 };
-//# sourceMappingURL=chunk-4QECACIA.js.map
+//# sourceMappingURL=chunk-MYPDVZCO.js.map

package/dist/{index-D54dqSdC.d.ts → index-DWPa2MJs.d.ts}

@@ -31,7 +31,7 @@ interface ExtensionIdentity<Kind extends string = string> {
 /** Host contract versions understood by this runtime. Requirements for other
  * namespaced contracts are retained but deliberately deferred to their owner. */
 declare const KNOWN_EXTENSION_CONTRACT_VERSIONS: Readonly<{
-    readonly core: string;
+    readonly core: "0.2.0";
     readonly scene: "2.0.0";
 }>;
 interface ExtensionCompatibilityResolution {
@@ -4822,6 +4822,11 @@ declare function knownFamilies(): FamilyId[];
 declare function knownBuiltinFamilies(): BuiltinFamilyId[];
 declare function detectRegisteredFamilyFromFirstLine(firstLine: string, mode?: 'strict' | 'loose'): FamilyId | null;
 
+interface MermaidAccessibility {
+    title?: string;
+    descr?: string;
+}
+
 type MermaidConfigScalar = string | number | boolean | null;
 type MermaidConfigValue = MermaidConfigScalar | MermaidConfigValue[] | MermaidConfigMap;
 interface MermaidConfigMap {
@@ -5134,9 +5139,7 @@ interface MermaidSourceComment {
     text: string;
     line: number;
 }
-interface MermaidSourceAccessibility {
-    title?: string;
-    descr?: string;
+interface MermaidSourceAccessibility extends MermaidAccessibility {
 }
 interface NormalizedMermaidSource {
     /** Original bytes supplied at the public boundary. */

package/dist/index.d.ts

@@ -1 +1 @@
-export { g0 as ARCHITECTURE_ICON_LIMITS, g as AnyPort, r as ArchitectureVisualOverrides, s as AsciiRenderColorMode, A as AsciiRenderOptions, t as AsciiWidthError, u as AsciiWidthErrorReason, B as BACKEND_CONFORMANCE_CHECK_IDS, v as BACKEND_CONFORMANCE_FIXTURE_ID, w as BACKEND_CONFORMANCE_VERSION, x as BINDABLE_ROLE_STYLE_PROPERTIES, y as BINDABLE_SCENE_ROLES, z as BRAND_CONSTRAINT_DESCRIPTORS, C as BRAND_CONSTRAINT_KINDS, g1 as BROWSER_CANVAS_RUNTIME, G as BUILTIN_SCENE_ROLE_TRAITS, I as BackendCapabilityConformanceResult, J as BackendCapabilityConformanceStatus, K as BackendConformanceCheck, L as BackendConformanceCheckId, M as BackendConformanceReport, N as BackendDescriptor, O as BackendRegistrationOptions, Q as BindableSceneRole, S as BrandConstraint, T as BrandConstraintAction, U as BrandConstraintKind, g2 as BrowserPngDiagnostic, g3 as BrowserPngFontSource, g4 as BrowserPngRasterContext, g5 as BrowserPngRasterResult, g6 as BrowserPngRasterizer, g7 as BrowserPngRuntimeProvenance, g8 as BuiltinSceneRole, X as CAPABILITY_NEGOTIATION_VERSION, Y as CORE_CAPABILITY_OFFERS, Z as CORE_SCENE_FEATURES, _ as CORE_SCENE_OPERATIONS, $ as CORE_SCENE_PRIMITIVES, a0 as CapabilityDecision, a1 as CapabilityId, a2 as CapabilityOffer, a3 as CapabilityRequirement, a4 as CapabilityRequirementLevel, a5 as CapabilityResolution, g9 as CapabilityValidationResult, ad as CliRenderTransport, ae as CodeModeRenderTransport, ga as ConfigDiagnostic, af as ConnectorContourSemantics, gb as ConnectorDash, gc as ConnectorDirection, gd as ConnectorEndpointAnchor, ag as ConnectorEndpoints, ah as ConnectorGeometry, ai as ConnectorHitGeometry, aj as ConnectorLabelDescriptor, ak as ConnectorMark, al as ConnectorRelationship, am as ConnectorRoute, an as ConnectorStroke, ao as ConnectorSubpath, ap as ConnectorTerminalLabelProjection, aq as ConnectorTerminalMarkerPlacement, ar as ConnectorTerminalMarkerProjection, as as ConnectorTerminalProjection, at as ConnectorTerminalStrokeLoss, ge as CoreSceneFeature, gf as CoreSceneOperation, gg as CoreScenePrimitive, gh as CoreSceneRole, gi as DEFAULTS, av as DefaultBackend, gj as DiagramColors, aB as DiamondFacet, gk as DocumentMark, gl as ESSENTIAL_SCENE_PRIMITIVE_CAPABILITIES, gm as ESSENTIAL_SCENE_PRIMITIVE_OPERATIONS, aC as EXACT_ROLE_STYLE_CONTRACT, aD as EXACT_STYLE_SCENE_ROLES, aE as EXTERNAL_SCENE_API_VERSION, aG as EdgeRouteCertificate, gn as EssentialScenePrimitiveCapability, go as EssentialScenePrimitiveOperation, aO as ExactStyleSceneRole, gp as ExtensionCollisionError, gq as ExtensionCompatibility, gr as ExtensionCompatibilityDecision, gs as ExtensionCompatibilityResolution, aP as ExtensionDiagramBody, aQ as ExtensionIdentity, gt as ExtensionProvenance, gu as ExtensionRegistration, aR as ExtensionValidDiagram, aT as ExternalSceneConnector, aU as ExternalSceneConnectorGeometry, aV as ExternalSceneConnectorLabel, aW as ExternalSceneContainer, aX as ExternalSceneDataMark, aY as ExternalSceneDocument, aZ as ExternalSceneGeometry, a_ as ExternalSceneInput, a$ as ExternalSceneMarker, b0 as ExternalSceneNode, b1 as ExternalSceneNodeBase, b2 as ExternalSceneShape, b3 as ExternalSceneText, bg as FamilyDetectionDiagnostic, bh as FamilyEdgeRouteCertificate, bo as FamilyRouteCertificate, gv as Geometry, gw as GitGraphBranch, gx as GitGraphCommit, gy as GitGraphCommitType, gz as GitGraphDiagram, gA as GitGraphDuplicateCommitError, gB as GitGraphParseError, gC as GitGraphRuntimeConfig, gD as GroupMark, bJ as HOSTED_FONT_RESOURCES, H as HostBackendPolicy, gE as HostBackendSelection, gF as HostedFontFace, gG as HostedFontResource, gH as JourneyRuntimeConfig, gI as KNOWN_EXTENSION_CONTRACT_VERSIONS, bQ as LayoutRouteCertificate, bR as LayoutRouteClass, bT as LibraryRenderTransport, bU as MAX_HOSTED_PNG_BYTES, bV as MAX_HOSTED_PNG_PIXELS, bW as MAX_PNG_FONT_DIRECTORIES, bX as MAX_PNG_FONT_DIRECTORY_LENGTH, bY as MAX_PNG_PIXELS, bZ as MAX_PNG_RASTER_DIMENSION, gJ as MarkPaint, b_ as MarkerDescriptor, gK as MarkerSerializationOptions, gL as MarkerShape, gM as MermaidBrowserPNGRenderer, gN as MermaidBrowserPNGRendererHostOptions, b$ as MermaidFamilyClassification, c0 as MermaidFamilyDetectionError, gO as MermaidGraph, gP as MermaidRenderer, gQ as MermaidRendererHostOptions, gR as MermaidRuntimeConfig, gS as MermaidThemeVariables, gT as MindmapDiagram, gU as MindmapDuplicateIdError, gV as MindmapNode, gW as MindmapParseError, gX as MindmapRuntimeConfig, gY as MindmapShape, c6 as NATIVE_PNG_HOST_ONLY_OPTION_FIELDS, c7 as NATIVE_PNG_OUTPUT_POLICY_FIELDS, gZ as NamespacedSceneRole, c8 as NativePngHostOnlyOptionField, c9 as NativePngOutputPolicyField, g_ as OUTPUT_COLOR_PROFILE, g$ as OUTPUT_SECURITY_POLICY_VERSION, h0 as OutputSecurityDiagnostic, h1 as OutputSecurityMode, h2 as OutputSecurityResult, cb as PNG_DEFAULT_FONT_FAMILY, cc as PNG_DEFAULT_SCALE, cd as PNG_FONT_SOURCES, ce as PNG_NAPI_RUNTIME, cf as PNG_OUTPUT_OPTION_FIELDS, cg as PNG_OUTPUT_OPTION_FIELD_DESCRIPTORS, ch as PNG_OUTPUT_POLICY_VERSION, ci as PNG_WASM_RUNTIME, cj as PORTABLE_PNG_OUTPUT_OPTION_FIELDS, ck as PRIMITIVE_REALIZATIONS, P as ParsedDiagram, h3 as ParsedDiagramFamilyMismatchError, h4 as PieRuntimeConfig, h5 as PngColorProfileReceipt, h6 as PngDimensions, cr as PngFitTo, cs as PngFontSource, ct as PngOutputOptionField, cu as PngOutputOptionFieldDescriptor, cv as PngOutputOptionInputKind, cw as PngOutputOptionPolicyState, cx as PngOutputOptionReceiptState, cy as PngOutputOptionScope, a as PngOutputPolicyInput, cz as PngRasterDimensions, c as PngRuntimeProvenance, cA as PortSemanticRole, cB as PortSide, cC as PortablePngOutputOptionField, cD as PortablePngOutputOptions, fX as PositionedDiagram, h7 as PositionedGitGraphDiagram, h8 as PositionedGraph, h9 as PositionedMindmapDiagram, cE as PreservedDiagramBody, cF as PreservedSourceSpans, cG as PreservedValidDiagram, ha as PrimitiveCapabilityClaim, hb as PrimitiveRealization, hc as QuadrantRuntimeConfig, cM as RENDER_CONTRACT_VERSION, cN as RENDER_OUTPUTS, cO as RENDER_OUTPUT_DESCRIPTORS, cP as RESOURCE_MANIFEST, cQ as RESOURCE_MANIFEST_VERSION, cR as ROLE_STYLE_PROPERTY_DESCRIPTORS, hd as RadarRuntimeConfig, cX as RegionContainmentCertificate, cY as RenderCapabilityError, he as RenderContext, R as RenderOptions, hf as RenderOutput, cZ as RenderOutputDescriptor, c_ as RenderOutputTransports, b as RenderRequestReceipt, hg as RenderableMarkerDescriptor, c$ as RenderedAscii, hh as RenderedBrowserPng, f$ as RenderedSvg, hi as ResolvedArchitectureIcon, hj as ResolvedColors, d5 as ResolvedPngOutputPolicy, hk as ResolvedSceneRoleTraits, d6 as ResolvedTerminalOutputPolicy, hl as ResolvedTerminalStyle, hm as ResourceLicense, hn as ResourceManifest, ho as ResourceManifestEntry, d8 as RoleStyleFor, d9 as RoleStyleSpec, da as RoleStyles, db as RouteBlocker, dc as RouteCertificate, dd as RouteClass, de as RoutePortAssignment, df as SCENE_CONTRACT_VERSION, dg as SCENE_ROLE_DESCRIPTORS, dh as SCENE_VALIDATION_LIMITS, di as SCENE_VALIDATION_VERSION, dj as SEMANTIC_BINDING_CHANNELS, dk as SHARED_RENDER_OPTION_FIELDS, dl as STYLE_COLOR_TOKEN_DESCRIPTORS, dm as STYLE_SPEC_FIELD_DESCRIPTORS, dn as STYLE_SPEC_FORMAT_VERSION, hp as SceneBox, hq as SceneConnectorHit, dp as SceneDoc, hr as SceneFeature, hs as SceneMarkKind, dq as SceneNode, ht as SceneNodeBase, hu as SceneOperation, hv as ScenePoint, hw as ScenePrimitive, dr as SceneRole, hx as SceneRoleDescriptor, hy as SceneRoleTraits, hz as SceneSketchPolicy, ds as SceneValidationDiagnostic, dt as SceneValidationDiagnosticCode, du as SceneValidationError, dv as SceneValidationOptions, dw as SceneValidationResult, dx as SemanticBinding, dy as SemanticBindingChannel, dz as SemanticChannels, dA as SemanticSlots, hA as ShapeMark, dM as SourceSpan, dN as SourceSpanPoint, hB as StateRuntimeConfig, dT as StyleBackend, dU as StyleBackendContext, dV as StyleColors, dW as StyleDescriptor, dX as StyleInput, dY as StyleReferenceResolution, dZ as StyleRegistrationOptions, hC as StyleRegistryKind, d_ as StyleSpec, hD as SvgRelationSemantics, hE as SvgSemanticAccessibility, hF as SvgSemanticIdentity, d$ as TERMINAL_BOUNDED_PADDING_X, e0 as TERMINAL_DEFAULT_BOX_BORDER_PADDING, e1 as TERMINAL_DEFAULT_PADDING_X, e2 as TERMINAL_DEFAULT_PADDING_Y, e3 as TERMINAL_OUTPUT_POLICY_VERSION, hG as TERMINAL_STYLE_VERSION, e4 as TEXT_MEASUREMENT_CONTRACT, hH as TerminalConnectorProjection, hI as TerminalConnectorProjectionReceipt, e5 as TerminalOutputPolicyError, e6 as TerminalOutputPolicyInput, hJ as TerminalProjectionDiagnostic, fY as TerminalProjectionDiagnosticCode, hK as TerminalProjectionSecurityContext, hL as TextMark, e7 as TextMeasurementContract, e8 as TextMeasurementInput, e9 as TextMeasurementResult, hM as TimelineRuntimeConfig, hN as XyChartRuntimeConfig, hO as applyOutputSecurityPolicy, hP as applyPngColorProfile, hQ as architectureIconManifest, hR as architectureToMermaidGraph, eV as assertHostedPngRasterBudget, eW as assertPngRasterBudget, hS as assertRenderableMarker, eX as assertValidSceneDoc, eY as buildExternalScene, hT as canonicalExtensionId, e_ as classifyMermaidFamilyFromFirstLine, hU as connectorHitDistance, e$ as createExtensionIdentity, hV as createMermaidBrowserPNGRenderer, hW as createMermaidRenderer, hX as essentialScenePrimitiveOperation, hY as evaluateExtensionCompatibility, hZ as fromShikiTheme, f5 as getBackend, f8 as getStyle, h_ as hitTestConnector, h$ as hitTestSceneConnectors, f9 as hostedFontResource, fa as inferBackend, i0 as inlineResolvedColors, i1 as inspectPngColorProfile, i2 as inspectPngDimensions, fd as knownBackendDescriptors, fg as knownStyleDescriptors, fh as knownStyles, fi as measureText, fj as measureTextWidth, fk as negotiateCapabilities, fl as negotiateRenderCapabilities, fm as normalizePortablePngBackground, fo as omitPngOutputOptions, i3 as parseArchitectureDiagram, i4 as parseExtensionId, i5 as parseGitGraph, i6 as parseMindmap, fp as parseRegisteredMermaid, fq as parseSemVer, fr as pngNapiRuntimeProvenance, fs as pngOutputOptionsJsonSchema, ft as pngRasterDimensions, fu as prepareSvgForPngRasterization, fv as projectNativePngOutputPolicyInput, fw as projectPortablePngOutputOptions, fx as registerBackend, i7 as registerExtension, fy as registerStyle, i8 as renderContractDigest, fZ as renderMermaidASCII, i9 as renderMermaidASCIIWithReceipt, ia as renderMermaidPNGInBrowserWithReceipt, f_ as renderMermaidSVG, ib as renderMermaidSVGAsync, ic as renderMermaidSVGWithReceipt, id as resolveArchitectureIcon, ie as resolveColors, ig as resolveDiagramColors, fz as resolvePngOutputPolicy, fA as resolvePortablePngOutputPolicy, fB as resolveSceneRoleTraits, fC as resolveStyleReference, fD as resolveStyleStack, fE as resolveTerminalOutputPolicy, fF as runBackendConformance, fG as sceneRoleTraits, fH as semVerSatisfies, ih as serializeGitGraph, ii as serializeMarkerResource, ij as serializeMarkerResources, ik as serializeMindmap, fI as sharedRenderOptionsJsonSchema, il as snapshotResourceManifest, fJ as styleInputJsonSchema, fK as styleSpecJsonSchema, fL as svgIntrinsicDimensions, fM as terminalConnectorCapabilityClaims, fO as validatePrimitiveCapabilities, fP as validateResourceManifest, fQ as validateSceneDoc, fR as validateSerializableRenderOptions, fS as validateStyleSpec, fT as verifyNoExternalRefs, fU as verifyResourceBytes, im as verifySvgDocumentEnvelope } from './index-D54dqSdC.js';
+export { g0 as ARCHITECTURE_ICON_LIMITS, g as AnyPort, r as ArchitectureVisualOverrides, s as AsciiRenderColorMode, A as AsciiRenderOptions, t as AsciiWidthError, u as AsciiWidthErrorReason, B as BACKEND_CONFORMANCE_CHECK_IDS, v as BACKEND_CONFORMANCE_FIXTURE_ID, w as BACKEND_CONFORMANCE_VERSION, x as BINDABLE_ROLE_STYLE_PROPERTIES, y as BINDABLE_SCENE_ROLES, z as BRAND_CONSTRAINT_DESCRIPTORS, C as BRAND_CONSTRAINT_KINDS, g1 as BROWSER_CANVAS_RUNTIME, G as BUILTIN_SCENE_ROLE_TRAITS, I as BackendCapabilityConformanceResult, J as BackendCapabilityConformanceStatus, K as BackendConformanceCheck, L as BackendConformanceCheckId, M as BackendConformanceReport, N as BackendDescriptor, O as BackendRegistrationOptions, Q as BindableSceneRole, S as BrandConstraint, T as BrandConstraintAction, U as BrandConstraintKind, g2 as BrowserPngDiagnostic, g3 as BrowserPngFontSource, g4 as BrowserPngRasterContext, g5 as BrowserPngRasterResult, g6 as BrowserPngRasterizer, g7 as BrowserPngRuntimeProvenance, g8 as BuiltinSceneRole, X as CAPABILITY_NEGOTIATION_VERSION, Y as CORE_CAPABILITY_OFFERS, Z as CORE_SCENE_FEATURES, _ as CORE_SCENE_OPERATIONS, $ as CORE_SCENE_PRIMITIVES, a0 as CapabilityDecision, a1 as CapabilityId, a2 as CapabilityOffer, a3 as CapabilityRequirement, a4 as CapabilityRequirementLevel, a5 as CapabilityResolution, g9 as CapabilityValidationResult, ad as CliRenderTransport, ae as CodeModeRenderTransport, ga as ConfigDiagnostic, af as ConnectorContourSemantics, gb as ConnectorDash, gc as ConnectorDirection, gd as ConnectorEndpointAnchor, ag as ConnectorEndpoints, ah as ConnectorGeometry, ai as ConnectorHitGeometry, aj as ConnectorLabelDescriptor, ak as ConnectorMark, al as ConnectorRelationship, am as ConnectorRoute, an as ConnectorStroke, ao as ConnectorSubpath, ap as ConnectorTerminalLabelProjection, aq as ConnectorTerminalMarkerPlacement, ar as ConnectorTerminalMarkerProjection, as as ConnectorTerminalProjection, at as ConnectorTerminalStrokeLoss, ge as CoreSceneFeature, gf as CoreSceneOperation, gg as CoreScenePrimitive, gh as CoreSceneRole, gi as DEFAULTS, av as DefaultBackend, gj as DiagramColors, aB as DiamondFacet, gk as DocumentMark, gl as ESSENTIAL_SCENE_PRIMITIVE_CAPABILITIES, gm as ESSENTIAL_SCENE_PRIMITIVE_OPERATIONS, aC as EXACT_ROLE_STYLE_CONTRACT, aD as EXACT_STYLE_SCENE_ROLES, aE as EXTERNAL_SCENE_API_VERSION, aG as EdgeRouteCertificate, gn as EssentialScenePrimitiveCapability, go as EssentialScenePrimitiveOperation, aO as ExactStyleSceneRole, gp as ExtensionCollisionError, gq as ExtensionCompatibility, gr as ExtensionCompatibilityDecision, gs as ExtensionCompatibilityResolution, aP as ExtensionDiagramBody, aQ as ExtensionIdentity, gt as ExtensionProvenance, gu as ExtensionRegistration, aR as ExtensionValidDiagram, aT as ExternalSceneConnector, aU as ExternalSceneConnectorGeometry, aV as ExternalSceneConnectorLabel, aW as ExternalSceneContainer, aX as ExternalSceneDataMark, aY as ExternalSceneDocument, aZ as ExternalSceneGeometry, a_ as ExternalSceneInput, a$ as ExternalSceneMarker, b0 as ExternalSceneNode, b1 as ExternalSceneNodeBase, b2 as ExternalSceneShape, b3 as ExternalSceneText, bg as FamilyDetectionDiagnostic, bh as FamilyEdgeRouteCertificate, bo as FamilyRouteCertificate, gv as Geometry, gw as GitGraphBranch, gx as GitGraphCommit, gy as GitGraphCommitType, gz as GitGraphDiagram, gA as GitGraphDuplicateCommitError, gB as GitGraphParseError, gC as GitGraphRuntimeConfig, gD as GroupMark, bJ as HOSTED_FONT_RESOURCES, H as HostBackendPolicy, gE as HostBackendSelection, gF as HostedFontFace, gG as HostedFontResource, gH as JourneyRuntimeConfig, gI as KNOWN_EXTENSION_CONTRACT_VERSIONS, bQ as LayoutRouteCertificate, bR as LayoutRouteClass, bT as LibraryRenderTransport, bU as MAX_HOSTED_PNG_BYTES, bV as MAX_HOSTED_PNG_PIXELS, bW as MAX_PNG_FONT_DIRECTORIES, bX as MAX_PNG_FONT_DIRECTORY_LENGTH, bY as MAX_PNG_PIXELS, bZ as MAX_PNG_RASTER_DIMENSION, gJ as MarkPaint, b_ as MarkerDescriptor, gK as MarkerSerializationOptions, gL as MarkerShape, gM as MermaidBrowserPNGRenderer, gN as MermaidBrowserPNGRendererHostOptions, b$ as MermaidFamilyClassification, c0 as MermaidFamilyDetectionError, gO as MermaidGraph, gP as MermaidRenderer, gQ as MermaidRendererHostOptions, gR as MermaidRuntimeConfig, gS as MermaidThemeVariables, gT as MindmapDiagram, gU as MindmapDuplicateIdError, gV as MindmapNode, gW as MindmapParseError, gX as MindmapRuntimeConfig, gY as MindmapShape, c6 as NATIVE_PNG_HOST_ONLY_OPTION_FIELDS, c7 as NATIVE_PNG_OUTPUT_POLICY_FIELDS, gZ as NamespacedSceneRole, c8 as NativePngHostOnlyOptionField, c9 as NativePngOutputPolicyField, g_ as OUTPUT_COLOR_PROFILE, g$ as OUTPUT_SECURITY_POLICY_VERSION, h0 as OutputSecurityDiagnostic, h1 as OutputSecurityMode, h2 as OutputSecurityResult, cb as PNG_DEFAULT_FONT_FAMILY, cc as PNG_DEFAULT_SCALE, cd as PNG_FONT_SOURCES, ce as PNG_NAPI_RUNTIME, cf as PNG_OUTPUT_OPTION_FIELDS, cg as PNG_OUTPUT_OPTION_FIELD_DESCRIPTORS, ch as PNG_OUTPUT_POLICY_VERSION, ci as PNG_WASM_RUNTIME, cj as PORTABLE_PNG_OUTPUT_OPTION_FIELDS, ck as PRIMITIVE_REALIZATIONS, P as ParsedDiagram, h3 as ParsedDiagramFamilyMismatchError, h4 as PieRuntimeConfig, h5 as PngColorProfileReceipt, h6 as PngDimensions, cr as PngFitTo, cs as PngFontSource, ct as PngOutputOptionField, cu as PngOutputOptionFieldDescriptor, cv as PngOutputOptionInputKind, cw as PngOutputOptionPolicyState, cx as PngOutputOptionReceiptState, cy as PngOutputOptionScope, a as PngOutputPolicyInput, cz as PngRasterDimensions, c as PngRuntimeProvenance, cA as PortSemanticRole, cB as PortSide, cC as PortablePngOutputOptionField, cD as PortablePngOutputOptions, fX as PositionedDiagram, h7 as PositionedGitGraphDiagram, h8 as PositionedGraph, h9 as PositionedMindmapDiagram, cE as PreservedDiagramBody, cF as PreservedSourceSpans, cG as PreservedValidDiagram, ha as PrimitiveCapabilityClaim, hb as PrimitiveRealization, hc as QuadrantRuntimeConfig, cM as RENDER_CONTRACT_VERSION, cN as RENDER_OUTPUTS, cO as RENDER_OUTPUT_DESCRIPTORS, cP as RESOURCE_MANIFEST, cQ as RESOURCE_MANIFEST_VERSION, cR as ROLE_STYLE_PROPERTY_DESCRIPTORS, hd as RadarRuntimeConfig, cX as RegionContainmentCertificate, cY as RenderCapabilityError, he as RenderContext, R as RenderOptions, hf as RenderOutput, cZ as RenderOutputDescriptor, c_ as RenderOutputTransports, b as RenderRequestReceipt, hg as RenderableMarkerDescriptor, c$ as RenderedAscii, hh as RenderedBrowserPng, f$ as RenderedSvg, hi as ResolvedArchitectureIcon, hj as ResolvedColors, d5 as ResolvedPngOutputPolicy, hk as ResolvedSceneRoleTraits, d6 as ResolvedTerminalOutputPolicy, hl as ResolvedTerminalStyle, hm as ResourceLicense, hn as ResourceManifest, ho as ResourceManifestEntry, d8 as RoleStyleFor, d9 as RoleStyleSpec, da as RoleStyles, db as RouteBlocker, dc as RouteCertificate, dd as RouteClass, de as RoutePortAssignment, df as SCENE_CONTRACT_VERSION, dg as SCENE_ROLE_DESCRIPTORS, dh as SCENE_VALIDATION_LIMITS, di as SCENE_VALIDATION_VERSION, dj as SEMANTIC_BINDING_CHANNELS, dk as SHARED_RENDER_OPTION_FIELDS, dl as STYLE_COLOR_TOKEN_DESCRIPTORS, dm as STYLE_SPEC_FIELD_DESCRIPTORS, dn as STYLE_SPEC_FORMAT_VERSION, hp as SceneBox, hq as SceneConnectorHit, dp as SceneDoc, hr as SceneFeature, hs as SceneMarkKind, dq as SceneNode, ht as SceneNodeBase, hu as SceneOperation, hv as ScenePoint, hw as ScenePrimitive, dr as SceneRole, hx as SceneRoleDescriptor, hy as SceneRoleTraits, hz as SceneSketchPolicy, ds as SceneValidationDiagnostic, dt as SceneValidationDiagnosticCode, du as SceneValidationError, dv as SceneValidationOptions, dw as SceneValidationResult, dx as SemanticBinding, dy as SemanticBindingChannel, dz as SemanticChannels, dA as SemanticSlots, hA as ShapeMark, dM as SourceSpan, dN as SourceSpanPoint, hB as StateRuntimeConfig, dT as StyleBackend, dU as StyleBackendContext, dV as StyleColors, dW as StyleDescriptor, dX as StyleInput, dY as StyleReferenceResolution, dZ as StyleRegistrationOptions, hC as StyleRegistryKind, d_ as StyleSpec, hD as SvgRelationSemantics, hE as SvgSemanticAccessibility, hF as SvgSemanticIdentity, d$ as TERMINAL_BOUNDED_PADDING_X, e0 as TERMINAL_DEFAULT_BOX_BORDER_PADDING, e1 as TERMINAL_DEFAULT_PADDING_X, e2 as TERMINAL_DEFAULT_PADDING_Y, e3 as TERMINAL_OUTPUT_POLICY_VERSION, hG as TERMINAL_STYLE_VERSION, e4 as TEXT_MEASUREMENT_CONTRACT, hH as TerminalConnectorProjection, hI as TerminalConnectorProjectionReceipt, e5 as TerminalOutputPolicyError, e6 as TerminalOutputPolicyInput, hJ as TerminalProjectionDiagnostic, fY as TerminalProjectionDiagnosticCode, hK as TerminalProjectionSecurityContext, hL as TextMark, e7 as TextMeasurementContract, e8 as TextMeasurementInput, e9 as TextMeasurementResult, hM as TimelineRuntimeConfig, hN as XyChartRuntimeConfig, hO as applyOutputSecurityPolicy, hP as applyPngColorProfile, hQ as architectureIconManifest, hR as architectureToMermaidGraph, eV as assertHostedPngRasterBudget, eW as assertPngRasterBudget, hS as assertRenderableMarker, eX as assertValidSceneDoc, eY as buildExternalScene, hT as canonicalExtensionId, e_ as classifyMermaidFamilyFromFirstLine, hU as connectorHitDistance, e$ as createExtensionIdentity, hV as createMermaidBrowserPNGRenderer, hW as createMermaidRenderer, hX as essentialScenePrimitiveOperation, hY as evaluateExtensionCompatibility, hZ as fromShikiTheme, f5 as getBackend, f8 as getStyle, h_ as hitTestConnector, h$ as hitTestSceneConnectors, f9 as hostedFontResource, fa as inferBackend, i0 as inlineResolvedColors, i1 as inspectPngColorProfile, i2 as inspectPngDimensions, fd as knownBackendDescriptors, fg as knownStyleDescriptors, fh as knownStyles, fi as measureText, fj as measureTextWidth, fk as negotiateCapabilities, fl as negotiateRenderCapabilities, fm as normalizePortablePngBackground, fo as omitPngOutputOptions, i3 as parseArchitectureDiagram, i4 as parseExtensionId, i5 as parseGitGraph, i6 as parseMindmap, fp as parseRegisteredMermaid, fq as parseSemVer, fr as pngNapiRuntimeProvenance, fs as pngOutputOptionsJsonSchema, ft as pngRasterDimensions, fu as prepareSvgForPngRasterization, fv as projectNativePngOutputPolicyInput, fw as projectPortablePngOutputOptions, fx as registerBackend, i7 as registerExtension, fy as registerStyle, i8 as renderContractDigest, fZ as renderMermaidASCII, i9 as renderMermaidASCIIWithReceipt, ia as renderMermaidPNGInBrowserWithReceipt, f_ as renderMermaidSVG, ib as renderMermaidSVGAsync, ic as renderMermaidSVGWithReceipt, id as resolveArchitectureIcon, ie as resolveColors, ig as resolveDiagramColors, fz as resolvePngOutputPolicy, fA as resolvePortablePngOutputPolicy, fB as resolveSceneRoleTraits, fC as resolveStyleReference, fD as resolveStyleStack, fE as resolveTerminalOutputPolicy, fF as runBackendConformance, fG as sceneRoleTraits, fH as semVerSatisfies, ih as serializeGitGraph, ii as serializeMarkerResource, ij as serializeMarkerResources, ik as serializeMindmap, fI as sharedRenderOptionsJsonSchema, il as snapshotResourceManifest, fJ as styleInputJsonSchema, fK as styleSpecJsonSchema, fL as svgIntrinsicDimensions, fM as terminalConnectorCapabilityClaims, fO as validatePrimitiveCapabilities, fP as validateResourceManifest, fQ as validateSceneDoc, fR as validateSerializableRenderOptions, fS as validateStyleSpec, fT as verifyNoExternalRefs, fU as verifyResourceBytes, im as verifySvgDocumentEnvelope } from './index-DWPa2MJs.js';

package/dist/index.js

@@ -164,7 +164,7 @@ import {
   verifyNoExternalRefs,
   verifyResourceBytes,
   verifySvgDocumentEnvelope
-} from "./chunk-ZYMMKQ3I.js";
+} from "./chunk-BJYMBT4I.js";
 export {
   ARCHITECTURE_ICON_LIMITS,
   AsciiWidthError,

package/dist/mcp-cli-5J47WEY3.js

@@ -0,0 +1,17 @@
+import {
+  MCP_CLI_HELP,
+  MCP_FLAG_SPECS,
+  parseMcpCliOptions,
+  runMcpCli
+} from "./chunk-2P5FKUQC.js";
+import "./chunk-2SILJDW2.js";
+import "./chunk-FDM43XU7.js";
+import "./chunk-MYPDVZCO.js";
+import "./chunk-BJYMBT4I.js";
+export {
+  MCP_CLI_HELP,
+  MCP_FLAG_SPECS,
+  parseMcpCliOptions,
+  runMcpCli
+};
+//# sourceMappingURL=mcp-cli-5J47WEY3.js.map

package/docs/README.md

@@ -1,6 +1,6 @@
 # Agentic Mermaid documentation
 
-This directory holds the long-form documentation. The root README is intentionally short and routes readers here.
+This directory holds the long-form documentation. The root README is intentionally short and routes readers here. Consumer guides are included in the npm package; repository-only links use canonical GitHub URLs so this hub also works from an installed tarball.
 
 ## User docs
 
@@ -12,7 +12,7 @@ This directory holds the long-form documentation. The root README is intentional
 | [`theming.md`](./theming.md) | Two-color themes, built-in themes, custom themes, Shiki import. |
 | [`style-authoring.md`](./style-authoring.md) | Style model, stack semantics, field reference, rubric, and validation commands. |
 | [`custom-style-cookbook.md`](./custom-style-cookbook.md) | Complete custom style JSON files, screenshots, schema usage, CLI commands, and the documentation-only Cupertino-, Vercel-, and Cloudflare Workers-inspired prototypes. |
-| [`design/families/style-switch-contact-sheet.html`](./design/families/style-switch-contact-sheet.html) | Self-contained interactive contact sheet for every registered family and every built-in Look/Palette Style resource. |
+| [`design/families/style-switch-contact-sheet.html`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/style-switch-contact-sheet.html) | Self-contained interactive contact sheet for every registered family and every built-in Look/Palette Style resource. |
 | [`custom-fonts.md`](./custom-fonts.md) | How custom Styles select and resolve fonts across SVG, PNG, browser, and MCP surfaces. |
 | [`react.md`](./react.md) | Zero-flash React rendering with CSS variables. |
 | [`ascii.md`](./ascii.md) | Terminal output, ASCII vs Unicode, color modes, XY charts. |
@@ -36,7 +36,7 @@ This directory holds the long-form documentation. The root README is intentional
 | [`mcp-http-transport.md`](./mcp-http-transport.md) | Local HTTP/SSE MCP quickstart plus hosted `/mcp` call-shape notes. |
 | [`agent-workflow-examples.md`](./agent-workflow-examples.md) | Runnable MCP/CLI and improvement-loop examples. |
 | [`../skills/`](../skills/) | Agent-agnostic skill bundles. |
-| [`../skill-evals/`](../skill-evals/) | Skill eval manifest, fixtures, and benchmark instructions. |
+| [`../skill-evals/`](https://github.com/adewale/agentic-mermaid/tree/main/skill-evals) | Skill eval manifest, fixtures, and benchmark instructions. |
 
 ## Contributor / project docs
 
@@ -47,26 +47,26 @@ The design docs split into two tiers — **system** (how the engine works, cross
 
 | Doc | Purpose |
 |---|---|
-| [`project/brand-primitives-plan.md`](./project/brand-primitives-plan.md) | Normative appearance/family-contract decision and A/B dependency/acceptance plan; live status is owned by root `TODO.md`. |
-| [`design/system/`](./design/system/README.md) | **Start here.** Current resolved-request, family-descriptor, positioned-artifact, and output-security architecture overview (dogfooded, drift-proof). |
-| [`design/system/route-contracts.md`](./design/system/route-contracts.md) | Route contracts: edge classification, direct-lane proofs, certifying straightener (issue #25). |
-| [`design/system/layout-rubric.md`](./design/system/layout-rubric.md) | Deterministic layout-quality rubric: metrics, CI gates, and property oracles. |
-| [`design/system/source-preservation-ladder.md`](./design/system/source-preservation-ladder.md) | The structured\|opaque family-adoption contract (levels L0–L4). |
-| [`design/mermaid-family-fidelity-audit.md`](./design/mermaid-family-fidelity-audit.md) | Mermaid 11.16 syntax accounting and Mermaid/Wikipedia visual-metaphor audit for every registered family. |
-| [`design/style-palette-compatibility.md`](./design/style-palette-compatibility.md) | Registry-derived exhaustive algebra plus complexity-aware variable-strength Style/Palette/family compatibility receipt. |
-| [`design/system/ugly-layouts.md`](./design/system/ugly-layouts.md) | Ugly-layout detector: catalogued failure shapes and heuristics. |
+| [`project/brand-primitives-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/brand-primitives-plan.md) | Normative appearance/family-contract decision and A/B dependency/acceptance plan; live status is owned by root `TODO.md`. |
+| [`design/system/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/README.md) | **Start here.** Current resolved-request, family-descriptor, positioned-artifact, and output-security architecture overview (dogfooded, drift-proof). |
+| [`design/system/route-contracts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/route-contracts.md) | Route contracts: edge classification, direct-lane proofs, certifying straightener (issue #25). |
+| [`design/system/layout-rubric.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/layout-rubric.md) | Deterministic layout-quality rubric: metrics, CI gates, and property oracles. |
+| [`design/system/source-preservation-ladder.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/source-preservation-ladder.md) | The structured\|opaque family-adoption contract (levels L0–L4). |
+| [`design/mermaid-family-fidelity-audit.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/mermaid-family-fidelity-audit.md) | Mermaid 11.16 syntax accounting and Mermaid/Wikipedia visual-metaphor audit for every registered family. |
+| [`design/style-palette-compatibility.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/style-palette-compatibility.md) | Registry-derived exhaustive algebra plus complexity-aware variable-strength Style/Palette/family compatibility receipt. |
+| [`design/system/ugly-layouts.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/system/ugly-layouts.md) | Ugly-layout detector: catalogued failure shapes and heuristics. |
 
 ### Per-family design notes
 
 | Doc | Purpose |
 |---|---|
-| [`design/families/`](./design/families/README.md) | Per-family hub: which families have a design note, and where each family's other surfaces live. |
-| [`design/families/architecture-beta.md`](./design/families/architecture-beta.md) | `architecture-beta` diagram-type implementation notes. |
-| [`design/families/gantt.md`](./design/families/gantt.md) | Gantt support specification and compatibility boundaries. |
-| [`design/families/gantt-research.md`](./design/families/gantt-research.md) | Gantt literature review and commercial UX survey. |
-| [`design/families/journey.md`](./design/families/journey.md) | Journey diagram implementation notes. |
-| [`design/families/xychart.md`](./design/families/xychart.md) | XY chart implementation notes. |
-| [`design/families/flowchart-parser-conformance.md`](./design/families/flowchart-parser-conformance.md) | Flowchart syntax conformance catalogue and unsupported-syntax warning policy (issue #36). |
+| [`design/families/`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/README.md) | Per-family hub: which families have a design note, and where each family's other surfaces live. |
+| [`design/families/architecture-beta.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/architecture-beta.md) | `architecture-beta` diagram-type implementation notes. |
+| [`design/families/gantt.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt.md) | Gantt support specification and compatibility boundaries. |
+| [`design/families/gantt-research.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/gantt-research.md) | Gantt literature review and commercial UX survey. |
+| [`design/families/journey.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/journey.md) | Journey diagram implementation notes. |
+| [`design/families/xychart.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/xychart.md) | XY chart implementation notes. |
+| [`design/families/flowchart-parser-conformance.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/design/families/flowchart-parser-conformance.md) | Flowchart syntax conformance catalogue and unsupported-syntax warning policy (issue #36). |
 
 > All per-family notes live in `design/families/` and all cross-cutting notes in `design/system/`.
 
@@ -74,21 +74,21 @@ The design docs split into two tiers — **system** (how the engine works, cross
 
 | Doc | Purpose |
 |---|---|
-| [`contributing/adding-diagram-types.md`](./contributing/adding-diagram-types.md) | How to add a Mermaid-supported diagram family. |
-| [`contributing/visual-review-evidence.md`](./contributing/visual-review-evidence.md) | Which reproducible visual artifacts are required for layout/rendering changes. |
-| [`contributing/diagram-family-citizenship.md`](./contributing/diagram-family-citizenship.md) | Enforced good-citizen checklist and matrix for family/surface drift (issue #41). |
-| [`contributing/harvesting-upstream-tests.md`](./contributing/harvesting-upstream-tests.md) | How to vendor upstream/fork test suites into an executable compatibility bench. |
-| [`contributing/releasing.md`](./contributing/releasing.md) | How to cut an npm release (GitHub Release → provenance publish) and flip the "published" copy. |
-| [`layout-characterization/README.md`](./layout-characterization/README.md) | Layout and visual testing approach: properties, contact sheets, raster contracts, and approval artifacts. |
+| [`contributing/adding-diagram-types.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/adding-diagram-types.md) | How to add a Mermaid-supported diagram family. |
+| [`contributing/visual-review-evidence.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/visual-review-evidence.md) | Which reproducible visual artifacts are required for layout/rendering changes. |
+| [`contributing/diagram-family-citizenship.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/diagram-family-citizenship.md) | Enforced good-citizen checklist and matrix for family/surface drift (issue #41). |
+| [`contributing/harvesting-upstream-tests.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/harvesting-upstream-tests.md) | How to vendor upstream/fork test suites into an executable compatibility bench. |
+| [`contributing/releasing.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/releasing.md) | How to cut an npm release (GitHub Release → provenance publish) and flip the "published" copy. |
+| [`layout-characterization/README.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/layout-characterization/README.md) | Layout and visual testing approach: properties, contact sheets, raster contracts, and approval artifacts. |
 | [`svg-semantic-contract.md`](./svg-semantic-contract.md) | Typed Scene identity, geometry, references, and accessibility contract. |
 | [`mutation-testing.md`](./mutation-testing.md) | Mutation lanes, survivor handling, and fault-sensitivity evidence. |
-| [`project/divergences.md`](./project/divergences.md) | Deliberate divergences and guardrails. |
-| [`project/lessons-learned.md`](./project/lessons-learned.md) | Evergreen engineering lessons distilled from the archived fork narrative. |
-| [`project/agent-interface-contract-audit-2026-07.md`](./project/agent-interface-contract-audit-2026-07.md) | PR #162 defect provenance, review of PRs #157/#160, testing root causes, and recurrence controls. |
-| [`project/complexity-aware-test-portfolio-plan.md`](./project/complexity-aware-test-portfolio-plan.md) | Implemented measured migration from overlapping family/style matrices to automatic complexity-aware conformance, variable-strength interaction coverage, and periodic contact-sheet review. |
-| [`contributing/lessons-learned.md`](./contributing/lessons-learned.md) | Dated contributor process lessons (newest first). |
-| [`project/dogfooding-docs-strategy.md`](./project/dogfooding-docs-strategy.md) | How we render and pin our own docs with our own tools. |
-| [`project/archive/`](./project/archive/) | Status-marked landing/completion evidence and frozen historical records; never live backlog authority. |
+| [`project/divergences.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/divergences.md) | Deliberate divergences and guardrails. |
+| [`project/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/lessons-learned.md) | Evergreen engineering lessons distilled from the archived fork narrative. |
+| [`project/agent-interface-contract-audit-2026-07.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/agent-interface-contract-audit-2026-07.md) | PR #162 defect provenance, review of PRs #157/#160, testing root causes, and recurrence controls. |
+| [`project/complexity-aware-test-portfolio-plan.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/complexity-aware-test-portfolio-plan.md) | Implemented measured migration from overlapping family/style matrices to automatic complexity-aware conformance, variable-strength interaction coverage, and periodic contact-sheet review. |
+| [`contributing/lessons-learned.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/contributing/lessons-learned.md) | Dated contributor process lessons (newest first). |
+| [`project/dogfooding-docs-strategy.md`](https://github.com/adewale/agentic-mermaid/blob/main/docs/project/dogfooding-docs-strategy.md) | How we render and pin our own docs with our own tools. |
+| [`project/archive/`](https://github.com/adewale/agentic-mermaid/tree/main/docs/project/archive) | Status-marked landing/completion evidence and frozen historical records; never live backlog authority. |
 | [`issue-derived-test-cases.md`](./issue-derived-test-cases.md) | Issue-derived regression coverage map. |
 | [`mermaid-layout-complaints.md`](./mermaid-layout-complaints.md) | Mermaid layout complaint catalog, root causes, and coverage scorecard. |
 
@@ -97,8 +97,8 @@ The design docs split into two tiers — **system** (how the engine works, cross
 - [`../README.md`](../README.md) — landing page and quick starts.
 - [`../CHANGELOG.md`](../CHANGELOG.md) — release notes.
 - [`../SECURITY.md`](../SECURITY.md) — conventional security entrypoint.
-- [`../TODO.md`](../TODO.md) — only active backlog with unchecked boxes.
+- [`../TODO.md`](https://github.com/adewale/agentic-mermaid/blob/main/TODO.md) — only active backlog with unchecked boxes.
 - [`../Instructions_for_agents.md`](../Instructions_for_agents.md) — canonical agent guide emitted by CLI.
 - [`../AGENT_NATIVE.md`](../AGENT_NATIVE.md) — agent-native architecture/spec entrypoint.
-- [`../PRODUCT.md`](../PRODUCT.md) — canonical product brief (brand register).
-- [`../DESIGN.md`](../DESIGN.md) — canonical website design system.
+- [`../PRODUCT.md`](https://github.com/adewale/agentic-mermaid/blob/main/PRODUCT.md) — canonical product brief (brand register).
+- [`../DESIGN.md`](https://github.com/adewale/agentic-mermaid/blob/main/DESIGN.md) — canonical website design system.

package/docs/agent-api-cookbook.md

@@ -0,0 +1,317 @@
+# Agentic Mermaid agent API cookbook
+
+This is the practical API reference for agents and agent authors. It complements the short [`Instructions_for_agents.md`](../Instructions_for_agents.md) guide and the deeper [`AGENT_NATIVE.md`](../AGENT_NATIVE.md) rationale.
+
+## Mental model
+
+Agentic Mermaid is not just a renderer. It is a structured edit loop:
+
+1. **Parse** Mermaid source into a `ValidDiagram`.
+2. **Narrow** existing structured diagrams to the family you intend to edit.
+3. **Mutate** with typed operations instead of string-splicing source.
+4. **Verify** before any commit point.
+5. **Serialize** only after inspecting `verify.ok`, `verify.warnings`, and, when relevant, `verify.layout`.
+
+For brand-new diagrams, author Mermaid source directly, then parse/verify/render. For existing modeled diagrams, prefer typed mutation so edits preserve structure and round-trip predictably.
+
+## Pick the right channel
+
+| Channel | Use when | Surface |
+|---|---|---|
+| Library | You can run TypeScript/JavaScript | `import ... from 'agentic-mermaid/agent'` |
+| MCP Code Mode | An agent needs multi-step edits in one sandboxed call | local `agentic-mermaid-mcp`, global `mermaid.*` |
+| Hosted MCP | No local install is available, or a client wants bounded HTTP tools | `https://agentic-mermaid.dev/mcp` tools: `execute`, render/verify/describe, `mutate`, `build` |
+| CLI | Shell-only verification, rendering, preview, or one-shot mutation | `am ...` |
+
+All channels expose the same core contract: parse, optionally narrow, mutate, verify, serialize/render. Agentic Mermaid outputs SVG, PNG, ASCII, Unicode, and JSON layout.
+
+## Recipe: author a new diagram
+
+Use direct source authoring for new diagrams. Do not construct a diagram by calling `mutate` repeatedly unless you specifically need a mutation trace.
+
+```ts
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG } from 'agentic-mermaid/agent'
+
+const source = `flowchart LR
+  User --> Login
+  Login --> Dashboard`
+
+const parsed = parseRegisteredMermaid(source)
+if (!parsed.ok) throw new Error(parsed.error.map(e => e.message).join('\n'))
+
+const verify = verifyMermaid(parsed.value)
+if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
+
+const svg = renderMermaidSVG(parsed.value, { security: 'strict' })
+```
+
+CLI equivalent:
+
+```bash
+am verify diagram.mmd
+am preview diagram.mmd --security strict --open
+am render diagram.mmd --format svg > diagram.svg
+```
+
+## Recipe: edit an existing flowchart safely
+
+```ts
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+
+const parsed = parseRegisteredMermaid('flowchart TD\n  API --> DB')
+if (!parsed.ok) throw new Error('parse failed')
+
+const flow = asFlowchart(parsed.value)
+if (!flow) throw new Error(`not a structured flowchart: ${parsed.value.kind}`)
+
+const r1 = mutate(flow, { kind: 'add_node', id: 'Cache', label: 'Cache' })
+if (!r1.ok) throw new Error(r1.error.message)
+
+const r2 = mutate(r1.value, { kind: 'add_edge', from: 'API', to: 'Cache' })
+if (!r2.ok) throw new Error(r2.error.message)
+
+const verify = verifyMermaid(r2.value)
+if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
+
+const source = serializeMermaid(r2.value)
+```
+
+CLI equivalent:
+
+```bash
+am mutate flow.mmd --ops '[
+  {"kind":"add_node","id":"Cache","label":"Cache"},
+  {"kind":"add_edge","from":"API","to":"Cache"}
+]'
+```
+
+`am mutate` verifies before emitting source. If verification fails, it exits `3` and omits `source`.
+
+## Recipe: batch mutations with rollback
+
+When applying several edits, keep the previous verified value. If a mutation or verification fails, return the last known-good diagram and the failure reason.
+
+```ts
+import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid, type FlowchartMutationOp } from 'agentic-mermaid/agent'
+
+export function applyFlowchartOps(source: string, ops: FlowchartMutationOp[]) {
+  const parsed = parseRegisteredMermaid(source)
+  if (!parsed.ok) return { ok: false as const, phase: 'parse', error: parsed.error }
+
+  let current = asFlowchart(parsed.value)
+  if (!current) return { ok: false as const, phase: 'narrow', family: parsed.value.kind }
+
+  const initialVerify = verifyMermaid(current)
+  if (!initialVerify.ok) return { ok: false as const, phase: 'initial-verify', warnings: initialVerify.warnings }
+  let lastGood = current
+
+  for (const op of ops) {
+    const next = mutate(current, op)
+    if (!next.ok) return { ok: false as const, phase: 'mutate', op, error: next.error, source: serializeMermaid(lastGood) }
+
+    const verify = verifyMermaid(next.value)
+    if (!verify.ok) {
+      return { ok: false as const, phase: 'verify', op, warnings: verify.warnings, source: serializeMermaid(lastGood) }
+    }
+
+    current = next.value
+    lastGood = current
+  }
+
+  return { ok: true as const, source: serializeMermaid(current), verify: verifyMermaid(current) }
+}
+```
+
+## Recipe: handle opaque fallback bodies
+
+Every built-in renderable family has a typed mutation path when its modeled subset narrows successfully. Unmodeled syntax is preserved as an opaque fallback body: it still parses, verifies, renders, and serializes losslessly, but family narrowers return `null` for that particular body.
+
+```ts
+import { parseRegisteredMermaid, asFlowchart, verifyMermaid, serializeMermaid } from 'agentic-mermaid/agent'
+
+const parsed = parseRegisteredMermaid(source)
+if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
+
+const flow = asFlowchart(parsed.value)
+if (!flow) {
+  return {
+    phase: 'unsupported-family',
+    family: parsed.value.kind,
+    source: serializeMermaid(parsed.value),
+    note: 'This body is opaque. Use source-level editing only if explicitly requested; then re-parse and verify.'
+  }
+}
+
+const verify = verifyMermaid(flow)
+```
+
+For source-level edits, preserve as much original source as possible, then run `parseRegisteredMermaid` and `verifyMermaid` again before returning it.
+
+## Recipe: inspect quality without screenshots
+
+`verifyMermaid` is structural. It catches reliable warning codes and returns layout JSON; it is not a subjective aesthetics score.
+
+```ts
+import { parseRegisteredMermaid, verifyMermaid, measureQuality, layoutMermaid, analyzeMermaid } from 'agentic-mermaid/agent'
+
+const parsed = parseRegisteredMermaid(source)
+if (!parsed.ok) throw new Error('parse failed')
+
+const verify = verifyMermaid(parsed.value, { labelCharCap: 28 })
+const quality = measureQuality(layoutMermaid(parsed.value))
+const routes = layoutMermaid(parsed.value, { debug: true }) // opt-in route, family-edge, and region certificates
+const analysis = analyzeMermaid(parsed.value) // feedback edges, actions, Gantt critical path/slack
+
+return {
+  ok: verify.ok,
+  warnings: verify.warnings,
+  bounds: verify.layout.bounds,
+  quality,
+  routeCertificates: routes.edges.map(e => e.route).filter(Boolean),
+  familyCertificates: routes.certificates ?? [],
+  analysis,
+}
+```
+
+For a unified render plus inert action regions, use
+`renderMermaidWithActions`. ASCII and Unicode artifacts include structured
+terminal `warnings`; an `ASCII_RENDER_FAILED` condition throws instead of
+returning an empty output as a successful artifact. SVG actions are marked
+`embedded-inert` only when their target metadata is present in that SVG.
+This includes Sequence `link`/`links` actor menus as well as admitted
+Flowchart, Class, and Gantt interactions; strict SVG removes authored href
+metadata and reports those actions through the sidecar only.
+
+Route, family-edge, and region certificates are opt-in; when graph-edge or family-edge certificates are present, `sourcePort`/`targetPort` are exact endpoint anchors where the family exposes them, and `sourcePortAssignment`/`targetPortAssignment` describe side, ordered slot, slot count, and semantic role for graph routes. Timeline/chart certificates use region-containment fields instead. Debug layouts also expose V1 `regions` and source-only `actions` sidecars so agents can attach UI affordances without executing Mermaid callbacks.
+
+For a renderer-neutral hit surface, use the same API for every output:
+
+```ts
+import { renderMermaidWithActions } from 'agentic-mermaid/agent'
+
+const rendered = renderMermaidWithActions(source, {
+  format: 'png',
+  options: { fitTo: { width: 1200 } },
+})
+// rendered.output is PNG bytes; actionSurface actions reference pixel regions.
+for (const action of rendered.actionSurface.actions) {
+  if (action.region) console.log(action.target, action.disposition, action.region.bounds)
+}
+```
+
+Use render artifacts for human visual review:
+
+```ts
+import { renderMermaidSVG, renderMermaidASCII, renderMermaidPNG } from 'agentic-mermaid/agent'
+
+const svg = renderMermaidSVG(diagram, { security: 'strict' })
+const ascii = renderMermaidASCII(diagram, { useAscii: true, targetWidth: 80 })
+const png = renderMermaidPNG(diagram, { fitTo: { width: 1600 }, background: '#fff' })
+```
+
+## Recipe: write SVG, PNG, and ASCII artifacts
+
+Library channel:
+
+```ts
+import { writeFileSync } from 'node:fs'
+import { parseRegisteredMermaid, verifyMermaid, renderMermaidSVG, renderMermaidPNG, renderMermaidASCII } from 'agentic-mermaid/agent'
+
+const parsed = parseRegisteredMermaid(source)
+if (!parsed.ok) throw new Error(parsed.error.map(e => e.message).join('\n'))
+
+const verify = verifyMermaid(parsed.value)
+if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
+
+writeFileSync('diagram.svg', renderMermaidSVG(parsed.value, { security: 'strict' }))
+writeFileSync('diagram.png', renderMermaidPNG(parsed.value, { fitTo: { width: 1200 }, background: '#fff' }))
+writeFileSync('diagram.txt', renderMermaidASCII(parsed.value, { useAscii: true }))
+```
+
+CLI channel:
+
+```bash
+am verify diagram.mmd
+am render diagram.mmd --format svg > diagram.svg
+am render diagram.mmd --format png --output diagram.png
+am render diagram.mmd --format ascii > diagram.txt
+```
+
+MCP channel:
+
+- Local MCP: use Code Mode for parse/narrow/mutate/verify/serialize.
+- Local MCP: use the `render_png` helper for base64 PNG bytes when the host needs a raster artifact.
+- Local HTTP/SSE mode: use `render_png` with `output: "file"` or `output: "url"` when the host wants a managed artifact instead of inline base64.
+- Hosted MCP: call `describe_sdk` for one family's compact op signatures or exact field schema, then use direct `render_svg`, `render_ascii`, `render_png`, `verify`, and `describe` for one-shot work; `render_ascii` accepts `targetWidth` as a hard display-cell bound and returns `ASCII_TARGET_WIDTH_IMPOSSIBLE` details when it cannot fit. Use declarative `mutate`/`build` for straightforward op-list edits; reserve hosted `execute` for logic those tools do not express.
+- Use local library/CLI/MCP for sensitive diagrams, offline work, larger inputs, or local file/URL PNG artifacts.
+
+## Recipe: MCP Code Mode
+
+In MCP Code Mode, do not import. The server injects `mermaid.*` as a global. Return JSON-serializable values.
+
+```ts
+const parsed = mermaid.parseRegisteredMermaid('flowchart TD\n  API --> DB')
+if (!parsed.ok) return { phase: 'parse', errors: parsed.error }
+
+const flow = mermaid.asFlowchart(parsed.value)
+if (!flow) return { phase: 'narrow', family: parsed.value.kind }
+
+const next = mermaid.mutate(flow, { kind: 'rename_node', from: 'DB', to: 'Database' })
+if (!next.ok) return { phase: 'mutate', error: next.error }
+
+const verify = mermaid.verifyMermaid(next.value)
+if (!verify.ok) return { phase: 'verify', warnings: verify.warnings }
+
+return { source: mermaid.serializeMermaid(next.value) }
+```
+
+Code Mode constraints:
+
+- No imports, dynamic imports, `async`/`await`, or Promise jobs.
+- SDK-returned diagrams are read-only; edit through `mermaid.mutate`.
+- Binary output such as PNG should usually be produced by a narrow helper or host code, not by large Code Mode payloads. `agentic-mermaid-mcp --transport http` serves managed URL artifacts from `/artifacts/<name>`.
+
+## Mutation operation discovery
+
+Use `am capabilities --json` for the registry-derived family roster, edit policy, narrower, and mutation-op names. In the library or Code Mode, use `describeOps(family)` or `opSignatures(family)` for exact fields, requiredness, enums, constraints, and defaults. Hosted MCP callers can request one family's schema with `describe_sdk`. These surfaces are generated from the same registry; this cookbook deliberately does not maintain another crib sheet.
+
+Unsupported typed mutation is a stop signal, not a prompt to fake structure. Either report the unsupported family or perform explicit source-level editing followed by parse/verify.
+
+## Warning-code crib sheet
+
+Tier 1 warnings are reliable structural/source checks. Do not suppress Tier 1 errors unless you fully understand the consequence.
+
+| Code | Meaning |
+|---|---|
+| `EMPTY_DIAGRAM` | Nothing renderable |
+| `EDGE_MISANCHORED` | Edge endpoint is not attached to a real target |
+| `OFF_CANVAS` | Node or edge segment lies outside canvas bounds |
+| `GROUP_BREACH` | Member lies outside its group bounds |
+| `UNKNOWN_SHAPE` | Shape fell back because the name is unrecognized |
+| `LABEL_OVERFLOW` | Label exceeds `labelCharCap` |
+| `UNRESOLVABLE_SCHEDULE` | Gantt parses but its schedule cannot resolve; render would fail |
+| `RENDER_FAILED` | Any family: verifies structurally but the strict render parser rejects the canonical source; `reason` carries the renderer error |
+
+Tier 2 warnings are advisory geometric checks — route tripwires for flowchart/state, plus boundary-anchor/overlap checks on class/ER entity boxes: `NODE_OVERLAP`, `ROUTE_SELF_CROSS`, and the route-contract tripwires `ROUTE_HITCH`, `ROUTE_UNEXPLAINED_BEND`, `ROUTE_LABEL_ON_SHARED_TRUNK`, `ROUTE_SELF_LOOP_OCCUPANCY`, `ROUTE_CONTAINER_MISANCHOR`, `ROUTE_SHAPE_MISANCHOR`, `ROUTE_STALE_AFTER_NODE_MOVE`.
+
+Tier 3 covers advisory lint plus caller-selected inspect-only Brand policy: `DUPLICATE_EDGE`, `UNREACHABLE_NODE`, `DECISION_BRANCH_UNLABELED`, `COMMENT_DROPPED`, `UNSUPPORTED_SYNTAX`, `CONTENT_DROPPED_ON_ROUNDTRIP`, `INEFFECTIVE_CONFIG`, `LOW_CONTRAST`, `BRAND_CONSTRAINT_WARNING`, `BRAND_CONSTRAINT_ERROR`. `LOW_CONTRAST` preserves authored paint and reports its foreground, final opaque background, ratio, and minimum; transparent output is not measured because its host backdrop is unknown. Brand constraints inspect final contrast, accent-area, or mono-role evidence without repainting or relayout. Advisory findings do not flip `verify.ok`; `BRAND_CONSTRAINT_ERROR` does only because the caller explicitly selected `action: "error"`.
+
+## Common anti-patterns
+
+- Regenerating an existing structured diagram instead of mutating it.
+- Concatenating source for an edit covered by a typed op.
+- Serializing before reading `verify.ok` and `verify.warnings`.
+- Treating `verify.ok` as a human aesthetics score.
+- Calling `mutate` on opaque fallback bodies.
+- Hiding unsupported-family results. Return them explicitly so the caller can choose a source-level path.
+
+## Minimal decision tree
+
+```text
+Do you have a brand-new diagram?
+  yes → write Mermaid source → parse → verify → render/return
+  no  → parse existing source
+        structured narrower exists?
+          yes → mutate → verify → serialize
+          no  → preserve source; report unsupported-family unless source-level editing was requested
+```