@geraldmaron/construct 1.2.3 → 1.3.1

package/lib/doctor/watchers/consistency.mjs

@@ -7,11 +7,11 @@
  *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
  *      dispatch resolves to an imported function, and every exported tool
  *      function in lib/mcp/tools/*.mjs is wired into the dispatch.
- *   3. Roles ↔ registry: every persona key in specialists/role-manifests.json
- *      resolves to a persona or agent name in specialists/registry.json.
+ *   3. Roles ↔ registry: every persona key in specialists/org
+ *      resolves to a persona or agent name in specialists/org.
  *   4. Persona promptFiles: every registry.personas[].promptFile and
  *      registry.agents[].promptFile exists on disk.
- *   5. Contracts ↔ schemas: specialists/contracts.json passes validateContractsFile
+ *   5. Contracts ↔ schemas: specialists/org passes validateContractsFile
  *      (cross-file refs, producer/consumer names, schema paths).
  *
  * Each violation produces an audit record. Blocking severity escalates to a
@@ -19,7 +19,8 @@
  * directory listings, no network.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { loadRegistry } from '../../registry/loader.mjs';
 import { join, dirname, resolve } from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -89,18 +90,39 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   const hosts = checkHostSurfaces({ repoRoot });
   collect(hosts, findings, passed, 'host-surfaces');
 
+  const { runCredentialParityChecks } = await import('./credential-parity.mjs');
+  const credentials = await runCredentialParityChecks({ rootDir: repoRoot });
+  collect(credentials, findings, passed, 'credential-parity');
+
   return { findings, passed };
 }
 
+// Drift categories split into two operator tiers. `actionable` findings are
+// project state a user can fix and surface by default. `internal` findings are
+// package/maintainer diagnostics about Construct's own registry and MCP wiring —
+// never user-actionable in a consumer project (this watcher resolves REPO_ROOT to
+// the installed package), so they stay behind `doctor consistency --strict`.
+
+const CATEGORY_TIERS = {
+  'mcp-drift': 'internal',
+  'roles-drift': 'internal',
+};
+
+function tierFor(category) {
+  return CATEGORY_TIERS[category] || 'actionable';
+}
+
 function collect(result, findings, passed, defaultCategory) {
   if (result.violations.length === 0) {
-    passed.push({ category: defaultCategory, summary: result.summary });
+    passed.push({ category: defaultCategory, summary: result.summary, tier: tierFor(defaultCategory) });
     return;
   }
   for (const v of result.violations) {
+    const category = v.category || defaultCategory;
     findings.push({
-      category: v.category || defaultCategory,
+      category,
       severity: v.severity || 'warning',
+      tier: v.tier || tierFor(category),
       summary: v.summary,
       target: v.target || null,
       details: v.details || null,
@@ -179,38 +201,51 @@ function checkMcpDrift({ repoRoot }) {
   }
 
   const serverSource = readFileSync(serverPath, 'utf8');
-  const dispatchedTools = new Set();
-  for (const m of serverSource.matchAll(/name === ['"]([a-z][a-z0-9_]*)['"]/g)) {
-    dispatchedTools.add(m[1]);
-  }
 
-  const exportedTools = new Set();
-  const entries = readdirSync(toolsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (!entry.isFile() || !entry.name.endsWith('.mjs')) continue;
-    const src = readFileSync(join(toolsDir, entry.name), 'utf8');
-    for (const m of src.matchAll(/export (?:async )?function (\w+)/g)) {
-      exportedTools.add(camelToSnake(m[1]));
+  // Candidate tool handlers are exactly the identifiers server.mjs imports from
+  // ./tools/*.mjs. Tool modules also export private helpers (exec, readJson) that
+  // are never MCP tools; scanning every `export function` swept those into the
+  // signal. Scoping to the server's own imports is the real contract surface.
+
+  const importedHandlers = new Set();
+  for (const m of serverSource.matchAll(/import\s*(?:type\s*)?\{([^}]*)\}\s*from\s*['"]\.\/tools\/[^'"]+['"]/g)) {
+    for (const ident of m[1].split(',')) {
+      const local = ident.trim().split(/\s+as\s+/).pop().trim();
+      if (local) importedHandlers.add(local);
     }
   }
 
-  for (const tool of exportedTools) {
-    if (KNOWN_NON_DISPATCH_TOOLS.has(tool)) continue;
-    if (!dispatchedTools.has(tool)) {
+  // A handler is wired when the dispatcher invokes it, regardless of the
+  // registered tool name. Handlers follow xxxTool→'xxx' and construct_xxx naming
+  // conventions, so matching exported names against `name === '<tool>'` strings is
+  // unreliable; matching the invoked identifier is convention-agnostic.
+
+  const invoked = new Set();
+  for (const m of serverSource.matchAll(/\b([A-Za-z_$][\w$]*)\s*\(/g)) {
+    invoked.add(m[1]);
+  }
+
+  for (const handler of importedHandlers) {
+    const snake = camelToSnake(handler);
+    if (KNOWN_NON_DISPATCH_TOOLS.has(handler) || KNOWN_NON_DISPATCH_TOOLS.has(snake)) continue;
+    if (!invoked.has(handler)) {
       violations.push({
         category: 'mcp-drift',
         severity: 'warning',
-        target: tool,
-        summary: `MCP tool exported but not dispatched: ${tool}`,
+        tier: 'internal',
+        target: snake,
+        summary: `MCP tool handler imported but never dispatched: ${handler}`,
       });
     }
   }
 
-  return { summary: `mcp: ${dispatchedTools.size} dispatched, ${exportedTools.size} exported, ${violations.length} drift`, violations };
+  return { summary: `mcp: ${importedHandlers.size} handlers, ${violations.length} drift`, violations };
 }
 
+// Handlers the server may import for re-export or test surface but intentionally
+// never dispatches. Matched by camelCase identifier or snake_case form.
+
 const KNOWN_NON_DISPATCH_TOOLS = new Set([
-  // Internal helpers exported for tests but never wired through MCP.
   'workflow_status_bound',
   'create_needs_main_input_packet',
 ]);
@@ -219,22 +254,82 @@ function camelToSnake(s) {
   return s.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
 }
 
+function readRegistrySnapshot(repoRoot) {
+  const registryPath = join(repoRoot, 'specialists', 'org');
+  if (!existsSync(registryPath)) return null;
+  const stat = statSync(registryPath);
+  if (stat.isDirectory()) return loadRegistry({ rootDir: repoRoot });
+  return JSON.parse(readFileSync(registryPath, 'utf8'));
+}
+
+function personaKeysFromRegistry(registry) {
+  const keys = new Set();
+
+  for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
+    if (specId) keys.add(specId.replace(/^cx-/, ''));
+    if (spec?.name) keys.add(String(spec.name).replace(/^cx-/, ''));
+  }
+
+  if (Array.isArray(registry?.specialists)) {
+    for (const spec of registry.specialists) {
+      if (spec?.id) keys.add(String(spec.id).replace(/^cx-/, ''));
+      if (spec?.name) keys.add(String(spec.name).replace(/^cx-/, ''));
+    }
+  }
+
+  if (registry?.orchestrator?.id) keys.add(String(registry.orchestrator.id).replace(/^cx-/, ''));
+  if (registry?.orchestrator?.name) keys.add(String(registry.orchestrator.name).replace(/^cx-/, ''));
+
+  return [...keys].sort();
+}
+
+function personaOwnersFromRegistry(registry) {
+  const owners = new Map();
+
+  function addOwner(rawId, owner) {
+    if (!rawId) return;
+    const personaId = String(rawId).replace(/^cx-/, '');
+    if (!owners.has(personaId)) owners.set(personaId, new Set());
+    owners.get(personaId).add(owner);
+  }
+
+  // One registry entity owns a persona once. A specialist's id and its own name
+  // normalize to the same persona by design (cx-architect / architect), so they
+  // must share a single owner token keyed on the entity — otherwise every
+  // specialist self-collides and reports a spurious "ambiguous" drift. Genuine
+  // ambiguity (two distinct specialists, or a specialist and the orchestrator,
+  // normalizing to the same persona) still yields owners.size > 1.
+
+  for (const [specId, spec] of Object.entries(registry?.specialists || {})) {
+    addOwner(specId, `specialist:${specId}`);
+    addOwner(spec?.name, `specialist:${specId}`);
+  }
+
+  if (Array.isArray(registry?.specialists)) {
+    for (const spec of registry.specialists) {
+      const owner = `specialist:${spec?.id || spec?.name || 'unknown'}`;
+      addOwner(spec?.id, owner);
+      addOwner(spec?.name, owner);
+    }
+  }
+
+  addOwner(registry?.orchestrator?.id, 'orchestrator');
+  addOwner(registry?.orchestrator?.name, 'orchestrator');
+  return owners;
+}
+
 // ── Check 3: roles ↔ registry ──────────────────────────────────────────────
 
 function checkRolesDrift({ repoRoot }) {
   const violations = [];
-  const manifestsPath = join(repoRoot, 'specialists', 'role-manifests.json');
-  const registryPath = join(repoRoot, 'specialists', 'registry.json');
-
-  if (!existsSync(manifestsPath) || !existsSync(registryPath)) {
-    return { summary: 'role manifests or registry missing', violations: [] };
+  if (!existsSync(join(repoRoot, 'specialists', 'org'))) {
+    return { summary: 'registry missing', violations: [] };
   }
 
-  const manifests = JSON.parse(readFileSync(manifestsPath, 'utf8'));
-  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  const registry = readRegistrySnapshot(repoRoot);
 
   const known = new Set();
-  for (const s of registry.specialists || []) {
+  for (const s of Object.values(registry.specialists || {})) {
     if (s?.name) { known.add(s.name); known.add(`cx-${s.name}`); }
   }
   if (registry.orchestrator?.name) {
@@ -242,35 +337,43 @@ function checkRolesDrift({ repoRoot }) {
     known.add(`cx-${registry.orchestrator.name}`);
   }
 
-  const personaKeys = Object.keys(manifests.personas || manifests || {});
+  const personaKeys = personaKeysFromRegistry(registry);
+  const personaOwners = personaOwnersFromRegistry(registry);
   for (const key of personaKeys) {
-    if (key === 'version' || key === 'description' || key === 'schemaVersion') continue;
     if (!known.has(key) && !known.has(`cx-${key}`)) {
       violations.push({
         category: 'roles-drift',
         severity: 'warning',
         target: key,
-        summary: `role-manifests persona '${key}' does not resolve to a registry persona/agent`,
+        summary: `role manifest '${key}' does not resolve to a registry persona/agent`,
       });
     }
   }
 
-  return { summary: `roles: ${personaKeys.length} manifest keys, ${violations.length} drift`, violations };
+  for (const [personaId, owners] of personaOwners.entries()) {
+    if (owners.size <= 1) continue;
+    violations.push({
+      category: 'roles-drift',
+      severity: 'warning',
+      target: personaId,
+      summary: `role manifest '${personaId}' is ambiguous after normalization: ${[...owners].join(', ')}`,
+    });
+  }
+
+  return { summary: `roles: ${personaKeys.length} personas, ${violations.length} drift`, violations };
 }
 
 // ── Check 4: persona promptFile existence ──────────────────────────────────
 
 function checkPersonaPrompts({ repoRoot }) {
   const violations = [];
-  const registryPath = join(repoRoot, 'specialists', 'registry.json');
-  if (!existsSync(registryPath)) return { summary: 'registry missing', violations: [] };
-
-  const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  const registry = readRegistrySnapshot(repoRoot);
+  if (!registry) return { summary: 'registry missing', violations: [] };
   let checked = 0;
 
   for (const list of [
     registry.orchestrator ? [registry.orchestrator] : [],
-    registry.specialists || [],
+    Object.values(registry.specialists || {}),
   ]) {
     for (const entry of list) {
       const ref = entry?.promptFile;
@@ -297,7 +400,9 @@ async function checkContractsDrift({ repoRoot }) {
   const violations = [];
   try {
     const { validateContractsFile } = await import('../../contracts/validate.mjs');
-    const result = validateContractsFile({ repoRoot });
+    const legacyContractsPath = join(repoRoot, 'specialists', 'contracts.json');
+    const opts = existsSync(legacyContractsPath) ? { contractsPath: legacyContractsPath, repoRoot } : { repoRoot };
+    const result = validateContractsFile(opts);
     if (!result.ok) {
       for (const err of result.errors) {
         violations.push({
@@ -327,7 +432,7 @@ function getVSCodeSettingsDir(homeDir) {
   return join(appData, 'Code', 'User');
 }
 
-function checkHostSurfaces({ repoRoot }) {
+function checkHostSurfaces({ repoRoot: _repoRoot }) {
   const violations = [];
   const homeDir = os.homedir();
   const surfaces = [

package/lib/doctor/watchers/credential-parity.mjs

@@ -0,0 +1,97 @@
+/**
+ * lib/doctor/watchers/credential-parity.mjs — advisory credential alignment checks.
+ *
+ * Surfaces when a pinned OpenRouter model or OpenCode default expects
+ * OPENROUTER_API_KEY but the canonical store and op-run catalog both lack it,
+ * or when OpenCode's openrouter provider has no auth wiring.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseEnvFile, getUserEnvPath } from '../../env-config.mjs';
+import { hasSecret } from '../../providers/secret-resolver.mjs';
+import { ensureOpenRouterProviderAuth } from '../../opencode-config.mjs';
+import { findOpenCodeConfigPath } from '../../opencode-config.mjs';
+
+export const name = 'credential-parity';
+export const intervalMs = 30 * 60 * 1000;
+
+function openRouterModelId(modelId) {
+  return typeof modelId === 'string' && /^openrouter\//.test(modelId);
+}
+
+function openCodeNeedsOpenRouter(homeDir) {
+  const configPath = findOpenCodeConfigPath();
+  if (!fs.existsSync(configPath)) return { needs: false, configPath };
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const defaultModel = config.model || config.defaultModel || '';
+    return { needs: openRouterModelId(defaultModel), configPath, config };
+  } catch {
+    return { needs: false, configPath };
+  }
+}
+
+function openRouterAuthWired(config) {
+  const probe = { provider: { openrouter: config?.provider?.openrouter || {} } };
+  ensureOpenRouterProviderAuth(probe);
+  const provider = probe.provider.openrouter;
+  return Boolean(
+    provider.apiKey
+    || provider.options?.headers?.Authorization,
+  );
+}
+
+export async function runCredentialParityChecks({ rootDir = process.cwd(), homeDir = os.homedir(), env = process.env } = {}) {
+  const violations = [];
+  const configPath = getUserEnvPath(homeDir);
+  const openRouterConfigured = hasSecret('OPENROUTER_API_KEY', { env, cwd: rootDir });
+
+  const openCode = openCodeNeedsOpenRouter(homeDir);
+  if (openCode.needs && !openRouterConfigured) {
+    violations.push({
+      category: 'credential-parity',
+      severity: 'advisory',
+      summary: `OpenCode default model uses OpenRouter but OPENROUTER_API_KEY is not configured (${openCode.configPath})`,
+    });
+  }
+
+  if (openCode.config && openCode.needs && !openRouterAuthWired(openCode.config)) {
+    violations.push({
+      category: 'credential-parity',
+      severity: 'advisory',
+      summary: 'OpenCode provider.openrouter has no apiKey env ref — run `construct sync --global`',
+    });
+  }
+
+  const xdgEnv = parseEnvFile(configPath);
+  const legacyEnv = parseEnvFile(path.join(homeDir, '.construct', 'config.env'));
+  if (legacyEnv.CONSTRUCT_OP_ENV_FILE && !xdgEnv.CONSTRUCT_OP_ENV_FILE) {
+    violations.push({
+      category: 'credential-parity',
+      severity: 'advisory',
+      summary: 'CONSTRUCT_OP_ENV_FILE is still in ~/.construct/config.env — run `construct install --scope=user` to migrate to XDG config',
+    });
+  }
+
+  return {
+    summary: violations.length
+      ? `credential-parity: ${violations.length} advisory finding(s)`
+      : 'credential-parity: ok',
+    violations,
+  };
+}
+
+export async function tick({ rootDir = process.cwd(), homeDir = os.homedir(), env = process.env } = {}) {
+  const result = await runCredentialParityChecks({ rootDir, homeDir, env });
+  return {
+    actions: [],
+    escalations: [],
+    findings: result.violations,
+    passed: result.violations.length === 0
+      ? [{ category: 'credential-parity', summary: result.summary }]
+      : [],
+  };
+}

package/lib/doctor/watchers/mcp-protocol.mjs

@@ -6,7 +6,7 @@
  * `initialize`, parse the response, send `tools/list`, report tool count.
  * cass-memory v0.2.x (the original cause of construct-1qt) rejects the
  * handshake outright; this watcher flags servers that fail the handshake so
- * the dashboard surfaces a protocol problem rather than a port-up false
+ * doctor surfaces a protocol problem rather than a port-up false
  * positive.
  *
  * Severity defaults to warning. Set `CONSTRUCT_MCP_PROTOCOL_BLOCKING=1` to

package/lib/doctor/watchers/service-health.mjs

@@ -1,8 +1,8 @@
 /**
  * lib/doctor/watchers/service-health.mjs — continuous service probes.
  *
- * Probes the services `construct dev` starts (postgres, dashboard,
- * cm, opencode). On 2 consecutive probe failures, attempts a restart of
+ * Probes the services `construct dev` starts (postgres, cm).
+ * On 2 consecutive probe failures, attempts a restart of
  * docker-backed services (postgres). On 2 consecutive failed
  * restarts, escalates `service.down` for cx-sre. Non-docker services log +
  * escalate after 3 consecutive failures — auto-restart needs original spawn
@@ -13,12 +13,11 @@
 
 import { spawnSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync, openSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
-import { configDir, stateDir, cacheDir } from '../../config/xdg.mjs';
+import { configDir, cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'service-health';
 export const intervalMs = 60 * 1000;
@@ -26,9 +25,6 @@ export const intervalMs = 60 * 1000;
 const failureCounts = {};
 const restartAttempts = {};
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = join(__dirname, '..', '..', '..');
-
 const services = [
   {
     id: 'postgres',
@@ -36,12 +32,6 @@ const services = [
     restart: () => dockerRestart('construct-postgres'),
     restartable: true,
   },
-  {
-    id: 'dashboard',
-    probe: () => probeDashboardPort(),
-    restart: () => respawnViaConstructUp('dashboard'),
-    restartable: true,
-  },
   {
     id: 'cm',
     probe: () => probeMemoryHealth(),
@@ -55,18 +45,6 @@ function probeTcp(host, port, timeoutMs = 1500) {
   return r.status === 0;
 }
 
-function probeDashboardPort() {
-  const statePath = join(stateDir(), 'dashboard.json');
-  if (!existsSync(statePath)) return true;
-  try {
-    const state = JSON.parse(readFileSync(statePath, 'utf8'));
-    if (!state.port) return true;
-    return probeTcp('127.0.0.1', state.port);
-  } catch {
-    return true;
-  }
-}
-
 function probeMemoryHealth() {
   const envPath = join(configDir(), 'config.env');
   if (!existsSync(envPath)) return true;
@@ -99,12 +77,6 @@ function detachSpawn(command, args, logName) {
   }
 }
 
-function respawnViaConstructUp() {
-  const bin = join(REPO_ROOT, 'bin', 'construct');
-  if (!existsSync(bin)) return { ok: false, error: 'bin/construct not found' };
-  return detachSpawn('node', [bin, 'up'], 'doctor-respawn-up.log');
-}
-
 function respawnCm() {
   const envPath = join(configDir(), 'config.env');
   let port = '4231';

package/lib/document-export.mjs

@@ -105,6 +105,50 @@ export function pdfRenderedDiagrams(pdfPath, sourceContent) {
   }
 }
 
+function rawDiagramSourcePattern() {
+  return /(?:flowchart\s+(?:TD|LR|BT|RL)|sequenceDiagram|classDiagram|stateDiagram|erDiagram|journey|gantt|pie\s+title|direction:\s*(?:right|down|left|up))/i;
+}
+
+function zipEntryText(zipPath, entryName, env = process.env) {
+  if (!whichBin('unzip', env)) return null;
+  const result = spawnSync('unzip', ['-p', zipPath, entryName], { encoding: 'utf8', env });
+  return result.status === 0 ? String(result.stdout || '') : null;
+}
+
+function zipEntryNames(zipPath, env = process.env) {
+  if (!whichBin('unzip', env)) return [];
+  const result = spawnSync('unzip', ['-Z1', zipPath], { encoding: 'utf8', env });
+  return result.status === 0
+    ? String(result.stdout || '').split('\n').map((line) => line.trim()).filter(Boolean)
+    : [];
+}
+
+export function docxRenderedDiagrams(docxPath, sourceContent, env = process.env) {
+  const expected = countDiagramFences(sourceContent);
+  if (expected === 0) return true;
+  const documentXml = zipEntryText(docxPath, 'word/document.xml', env);
+  if (!documentXml) return false;
+  if (rawDiagramSourcePattern().test(documentXml)) return false;
+  const rels = zipEntryText(docxPath, 'word/_rels/document.xml.rels', env) || '';
+  const entries = zipEntryNames(docxPath, env);
+  const mediaCount = entries.filter((entry) => entry.startsWith('word/media/')).length;
+  return mediaCount >= expected || /relationships\/image/i.test(rels);
+}
+
+export function htmlRenderedDiagrams(htmlPath, sourceContent) {
+  const expected = countDiagramFences(sourceContent);
+  if (expected === 0) return true;
+  let html = '';
+  try {
+    html = fs.readFileSync(htmlPath, 'utf8');
+  } catch {
+    return false;
+  }
+  if (rawDiagramSourcePattern().test(html)) return false;
+  const renderedCount = (html.match(/<(?:img|svg)\b/gi) || []).length;
+  return renderedCount >= expected || /data:image\//i.test(html);
+}
+
 export { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
 
 /** @deprecated use pdfUsesBundledBrandSans */
@@ -441,17 +485,37 @@ export function exportMarkdown({
     };
   }
 
-  if (format === 'pdf' && figures) {
+  if (figures) {
     const source = fs.readFileSync(inputPath, 'utf8');
     const expectedDiagrams = countDiagramFences(source);
-    if (expectedDiagrams > 0 && !pdfRenderedDiagrams(target, source)) {
-      return {
-        ok: false,
-        format,
-        inputPath,
-        outputPath: target,
-        message: `Export wrote PDF but rendered 0/${expectedDiagrams} diagram(s). Ensure d2 and mmdc are installed; mmdc needs Chrome (set PUPPETEER_EXECUTABLE_PATH or install Google Chrome). Pandoc stderr: ${(result.stderr || '').trim().slice(0, 300)}`,
-      };
+    if (expectedDiagrams > 0) {
+      if (format === 'pdf' && !pdfRenderedDiagrams(target, source)) {
+        return {
+          ok: false,
+          format,
+          inputPath,
+          outputPath: target,
+          message: `Export wrote PDF but rendered 0/${expectedDiagrams} diagram(s). Ensure d2 and mmdc are installed; mmdc needs Chrome (set PUPPETEER_EXECUTABLE_PATH or install Google Chrome). Pandoc stderr: ${(result.stderr || '').trim().slice(0, 300)}`,
+        };
+      }
+      if (format === 'docx' && !docxRenderedDiagrams(target, source, effectiveEnv)) {
+        return {
+          ok: false,
+          format,
+          inputPath,
+          outputPath: target,
+          message: `Export wrote DOCX but left diagram source unresolved. Ensure d2 and mermaid-cli rendered the figures before distributing the document. Pandoc stderr: ${(result.stderr || '').trim().slice(0, 300)}`,
+        };
+      }
+      if ((format === 'html' || format === 'deck') && !htmlRenderedDiagrams(target, source)) {
+        return {
+          ok: false,
+          format,
+          inputPath,
+          outputPath: target,
+          message: `Export wrote ${format.toUpperCase()} but left diagram source unresolved. Ensure d2 and mermaid-cli rendered the figures before distributing the document. Pandoc stderr: ${(result.stderr || '').trim().slice(0, 300)}`,
+        };
+      }
     }
   }