@geraldmaron/construct 1.1.0 → 1.2.0

package/lib/doctor/watchers/cx-budget.mjs

@@ -0,0 +1,98 @@
+/**
+ * lib/doctor/watchers/cx-budget.mjs — .cx/ disk budget maintenance.
+ *
+ * When project .cx/ usage crosses the configured cap, runs age/count prune.
+ * When still over cap after retention prune, emergency-reclaims oldest
+ * traces and worker logs (hard-reject categories only).
+ *
+ * Tick: 15 min.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import { escalate } from '../escalate.mjs';
+import {
+  measureUsage,
+  planPrune,
+  executePrune,
+  planEmergencyReclaim,
+} from '../../resources/budget.mjs';
+
+export const name = 'cx-budget';
+export const intervalMs = 15 * 60 * 1000;
+
+function projectRoot() {
+  return process.env.CONSTRUCT_PROJECT_ROOT || process.cwd();
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const root = projectRoot();
+  const cxDir = join(root, '.cx');
+  if (!existsSync(cxDir)) {
+    return { actions, escalations, notes: [{ skipped: 'no .cx directory' }] };
+  }
+
+  const before = measureUsage(root, process.env);
+  if (before.totalCxUsageRatio <= 0.8) {
+    return { actions, escalations, notes: [{ usageRatio: before.totalCxUsageRatio }] };
+  }
+
+  const planned = planPrune(root, process.env);
+  let reclaimed = { removed: [], bytesFreed: 0 };
+  if (planned.length) {
+    reclaimed = executePrune(planned);
+    record({
+      kind: 'action',
+      watcher: name,
+      action: 'prune',
+      target: '.cx/',
+      summary: `retention prune removed ${reclaimed.removed.length} file(s), freed ${reclaimed.bytesFreed} bytes`,
+      context: { planned: planned.length, removed: reclaimed.removed.length },
+    });
+    actions.push({ type: 'prune', target: '.cx/', removed: reclaimed.removed.length });
+  }
+
+  const afterPrune = measureUsage(root, process.env);
+  if (afterPrune.totalCxUsageRatio > 1) {
+    const emergency = planEmergencyReclaim(root, 0, process.env);
+    if (emergency.length) {
+      const emergencyResult = executePrune(emergency);
+      record({
+        kind: 'action',
+        watcher: name,
+        action: 'emergency-reclaim',
+        target: '.cx/traces|.cx/runtime/worker',
+        summary: `emergency reclaim removed ${emergencyResult.removed.length} file(s), freed ${emergencyResult.bytesFreed} bytes`,
+        context: emergencyResult,
+      });
+      actions.push({ type: 'emergency-reclaim', removed: emergencyResult.removed.length });
+    }
+  }
+
+  const after = measureUsage(root, process.env);
+  if (after.totalCxUsageRatio > 1) {
+    const usedMb = Math.round(after.totalCxBytes / 1024 / 1024);
+    const capMb = Math.round(after.totalCxCap / 1024 / 1024);
+    const r = await escalate({
+      watcher: name,
+      eventType: 'service.down',
+      summary: `.cx/ still over cap after prune (${usedMb}MB / ${capMb}MB) — raise resources.disk.totalCxMaxMb or delete load-bearing state manually`,
+      context: { usageRatio: after.totalCxUsageRatio, usedMb, capMb },
+    });
+    escalations.push({ eventType: 'service.down', result: r });
+  }
+
+  return {
+    actions,
+    escalations,
+    notes: [{
+      usageBefore: before.totalCxUsageRatio,
+      usageAfter: after.totalCxUsageRatio,
+      bytesFreed: reclaimed.bytesFreed,
+    }],
+  };
+}

package/lib/doctor/watchers/graph-staleness.mjs

@@ -0,0 +1,52 @@
+/**
+ * lib/doctor/watchers/graph-staleness.mjs — dependency graph freshness watcher.
+ *
+ * Ticks every 30 minutes. When registry/contracts/workflow seeds changed since
+ * the last `construct graph build`, records an audit entry so doctor surfaces
+ * stale-graph drift without waiting for the next Oracle tick.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { record } from '../audit.mjs';
+import { checkGraphStaleness } from '../../graph/staleness.mjs';
+import { isConstructPackageRepo } from '../../host-disposition.mjs';
+
+export const name = 'graph-staleness';
+export const intervalMs = 30 * 60 * 1000;
+
+function projectRoot() {
+  return process.env.CONSTRUCT_PROJECT_ROOT || process.cwd();
+}
+
+export async function tick() {
+  const actions = [];
+  const escalations = [];
+  const root = projectRoot();
+  const graphDir = join(root, '.cx', 'graph');
+
+  if (!existsSync(graphDir) && !isConstructPackageRepo(root)) {
+    return { actions, escalations, notes: [{ skipped: 'no graph and not construct package repo' }] };
+  }
+
+  const state = checkGraphStaleness(root);
+  if (!state.present) {
+    return { actions, escalations, notes: [{ present: false }] };
+  }
+  if (!state.stale) {
+    return { actions, escalations, notes: [{ present: true, stale: false }] };
+  }
+
+  record({
+    kind: 'action',
+    watcher: name,
+    action: 'graph-stale',
+    target: '.cx/graph/',
+    summary: state.staleReason,
+    context: { storedHash: state.storedHash, currentHash: state.currentHash },
+  });
+  actions.push({ type: 'graph-stale', target: '.cx/graph/' });
+
+  return { actions, escalations, notes: [state] };
+}

package/lib/doctor/watchers/process-pressure.mjs

@@ -2,9 +2,10 @@
  * lib/doctor/watchers/process-pressure.mjs — continuous process pressure guard.
  *
  * Runs the runtime-pressure cleanup on a recurring tick so stale Construct
- * helpers don't accumulate between `construct up` invocations. Any killed
- * process is recorded; if the same service-class has been killed >=2 times
- * in the last hour, escalates so cx-sre can investigate the underlying churn.
+ * helpers and leaked VHS demo-recorder processes don't accumulate between
+ * `construct dev` invocations. Any killed process is recorded; if the same
+ * service-class has been killed >=2 times in the last hour, escalation lets
+ * cx-sre investigate the underlying churn.
  *
  * Tick: 60s.
  */

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

@@ -1,7 +1,7 @@
 /**
  * lib/doctor/watchers/service-health.mjs — continuous service probes.
  *
- * Probes the services `construct up` starts (postgres, dashboard,
+ * Probes the services `construct dev` starts (postgres, dashboard,
  * cm, opencode). 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 +

package/lib/document-export.mjs

@@ -1,32 +1,135 @@
 /**
- * lib/document-export.mjs — markdown → PDF / DOCX / HTML export via external
- * binaries (Pandoc + Typst), per ADR-0024.
+ * lib/document-export.mjs — artifact export to PDF / DOCX / DOC / deck / PPTX / HTML /
+ * RTF / ODT / EPUB / LaTeX / TXT / MD / MDX via external binaries (Pandoc + Typst,
+ * LibreOffice for legacy .doc, pptxgenjs for PPTX), per ADR-0024.
  *
- * Bound to system-binary tooling discovered at runtime, never bundled in core
- * (ADR-0001 zero-npm-core; ADR-0014 optional-capability pattern). Both engines
- * are spawned as separate processes — Pandoc isolates its GPLv2+ licence at
- * the process boundary; Typst is the Apache-2.0 PDF engine driven through
- * Pandoc's `--pdf-engine=typst` flag, so a single Pandoc invocation produces
- * every target format the contract supports.
- *
- * detect(format) reports availability without spawning the engine for real.
- * exportMarkdown({ inputPath, outputPath, format, env }) spawns the engine and
- * returns a structured result. Both surface actionable "install X" guidance
- * when a required binary is absent; neither throws on missing tooling.
+ * Export **source** is Construct-authored markdown (typed artifacts). **Output**
+ * spans many distributable formats. Ingest (separate pipeline) accepts PDF, Office,
+ * email, AV, and plain text — see docs/reference/document-io.md.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  resolvePdfTemplatePath,
+  parseArtifactMetadata,
+  pandocMetadataArgs,
+  preprocessMarkdownForPdfExport,
+  distributionFontsDir,
+} from './publish-template.mjs';
+import {
+  preprocessMarkdownDiagrams,
+  buildDistributionDiagramEnv,
+  countDiagramFences,
+} from './diagram-export.mjs';
+import { exportDeckPptx, pptxgenPresent } from './deck-export-pptx.mjs';
+import { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
+import { convertDocxToDoc, libreOfficeInstallHint, libreOfficePresent, resolveLibreOfficeBin } from './libreoffice-export.mjs';
+
+export const EXPORT_FORMATS = ['pdf', 'docx', 'doc', 'deck', 'pptx', 'html', 'rtf', 'odt', 'epub', 'tex', 'txt', 'md', 'mdx'];
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-export const EXPORT_FORMATS = ['pdf', 'docx', 'html'];
+// Pandoc drives typeset formats; pptxgenjs builds slide decks; legacy `.doc` has no
+// pandoc writer — export DOCX first, then LibreOffice headless down-converts.
 
 const FORMAT_ENGINES = {
-  pdf: { engine: 'pandoc', pdfEngine: 'typst', extraBinaries: ['typst'] },
-  docx: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
-  html: { engine: 'pandoc', pdfEngine: null, extraBinaries: [] },
+  pdf: { engine: 'pandoc', writer: null, pdfEngine: 'typst', extraBinaries: ['typst'] },
+  docx: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  doc: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [], via: 'libreoffice', intermediate: 'docx' },
+  deck: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  pptx: { engine: 'pptxgenjs', writer: null, pdfEngine: null, extraBinaries: [] },
+  html: { engine: 'pandoc', writer: null, pdfEngine: null, extraBinaries: [] },
+  rtf: { engine: 'pandoc', writer: 'rtf', pdfEngine: null, extraBinaries: [] },
+  odt: { engine: 'pandoc', writer: 'odt', pdfEngine: null, extraBinaries: [] },
+  epub: { engine: 'pandoc', writer: 'epub', pdfEngine: null, extraBinaries: [] },
+  tex: { engine: 'pandoc', writer: 'latex', pdfEngine: null, extraBinaries: [] },
+  txt: { engine: 'pandoc', writer: 'plain', pdfEngine: null, extraBinaries: [] },
+  md: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
+  mdx: { engine: 'copy', writer: null, pdfEngine: null, extraBinaries: [] },
 };
 
+export function htmlTemplatePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-web.html');
+  return fs.existsSync(p) ? p : null;
+}
+
+export function deckTemplatePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-deck.html');
+  return fs.existsSync(p) ? p : null;
+}
+
+export function docxReferencePath(repoRoot = REPO_ROOT) {
+  const p = path.join(repoRoot, 'templates', 'distribution', 'construct-reference.docx');
+  return fs.existsSync(p) ? p : null;
+}
+
+export { resolvePdfTemplatePath } from './publish-template.mjs';
+
+export function pdfEngineFontOpts(repoRoot = REPO_ROOT) {
+  const fontPath = distributionFontsDir(repoRoot);
+  return [
+    '--pdf-engine-opt', `--font-path=${fontPath}`,
+    '--pdf-engine-opt', '--ignore-system-fonts',
+    '--pdf-engine-opt', '--ignore-embedded-fonts',
+  ];
+}
+
+export function countPdfEmbeddedImages(pdfPath) {
+  try {
+    const data = fs.readFileSync(pdfPath);
+    const text = data.toString('latin1');
+    const raster = (text.match(/\/Subtype\s*\/Image/g) || []).length;
+    const vector = (text.match(/\/Subtype\s*\/Form/g) || []).length;
+    return raster + vector;
+  } catch {
+    return 0;
+  }
+}
+
+export function pdfRenderedDiagrams(pdfPath, sourceContent) {
+  const expected = countDiagramFences(sourceContent);
+  if (expected === 0) return true;
+  const embedded = countPdfEmbeddedImages(pdfPath);
+  if (embedded >= expected) return true;
+  try {
+    const text = fs.readFileSync(pdfPath).toString('latin1');
+    const rawD2 = /direction:\s*(right|down|left|up)/.test(text);
+    const rawMermaid = /flowchart\s+(TD|LR|BT|RL)/.test(text);
+    return !rawD2 && !rawMermaid && embedded > 0;
+  } catch {
+    return false;
+  }
+}
+
+export { pdfUsesBundledBrandSans } from './brand-fonts.mjs';
+
+/** @deprecated use pdfUsesBundledBrandSans */
+export function pdfUsesBundledInter(pdfPath) {
+  return pdfUsesBundledBrandSans(pdfPath);
+}
+
+export function diagramFilterPath() {
+  return path.join(REPO_ROOT, 'vendor', 'pandoc-ext', 'diagram.lua');
+}
+
+export function detectPdfTemplate({
+  artifactType = null,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
+  const templatePath = resolvePdfTemplatePath({ artifactType, cwd, repoRoot });
+  return {
+    present: Boolean(templatePath),
+    path: templatePath,
+    message: templatePath
+      ? `PDF template: ${path.relative(repoRoot, templatePath)}`
+      : 'PDF template missing: templates/distribution/construct-pdf.typ',
+  };
+}
+
 function whichBin(name, env = process.env) {
   const cmd = process.platform === 'win32' ? 'where' : 'which';
   const result = spawnSync(cmd, [name], { encoding: 'utf8', env });
@@ -45,28 +148,77 @@ function binVersion(name, args = ['--version'], env = process.env) {
 function installHint(name) {
   if (name === 'pandoc') return 'Install pandoc to enable document export (e.g. `brew install pandoc` on macOS, `apt install pandoc` on Debian/Ubuntu, or https://pandoc.org/installing.html).';
   if (name === 'typst') return 'Install typst to enable PDF export via Pandoc (`brew install typst` on macOS, https://github.com/typst/typst/releases for binaries).';
+  if (name === 'construct-pdf.typ') return 'Bundled PDF template missing from templates/distribution/construct-pdf.typ (Construct install integrity issue).';
+  if (name === 'd2') return 'Install d2 for diagram blocks (`brew install d2`).';
+  if (name === 'mmdc') return 'Install mermaid-cli for mermaid blocks (`npm install -g @mermaid-js/mermaid-cli`).';
+  if (name === 'pptxgenjs') return 'Install pptxgenjs to enable PPTX export (`npm install pptxgenjs` in the Construct package).';
+  if (name === 'construct-deck.html') return 'Bundled deck template missing from templates/distribution/construct-deck.html (Construct install integrity issue).';
+  if (name === 'libreoffice') return libreOfficeInstallHint();
   return `Install ${name} to enable this export format.`;
 }
 
-// detect returns the same structure regardless of format so callers can render
-// availability uniformly. `present` is the single boolean a caller should gate
-// on; `missing` enumerates the binaries to install when present is false.
-
-export function detect(format, env = process.env) {
+export function detect(format, env = process.env, {
+  figures = false,
+  artifactType = null,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
   const config = FORMAT_ENGINES[format];
   if (!config) return { ok: false, format, present: false, missing: [], message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
-  const required = [config.engine, ...(config.extraBinaries || [])];
-  const status = required.map((name) => ({ name, path: whichBin(name, env), version: null }));
-  for (const s of status) if (s.path) s.version = binVersion(s.name, ['--version'], env);
+  if (config.engine === 'copy') {
+    return { ok: true, format, figures: false, present: true, binaries: [], missing: [], message: `Ready: source emit (${format})` };
+  }
+  const required = [];
+  if (config.engine === 'pptxgenjs') {
+    required.push('pptxgenjs');
+  } else {
+    required.push(config.engine, ...(config.extraBinaries || []));
+  }
+  if (format === 'pdf') {
+    const template = detectPdfTemplate({ artifactType, cwd, repoRoot });
+    if (!template.present) required.push('construct-pdf.typ');
+  }
+  if (format === 'deck' && !deckTemplatePath(repoRoot)) {
+    required.push('construct-deck.html');
+  }
+  if (format === 'doc' && !libreOfficePresent(env)) {
+    required.push('libreoffice');
+  }
+  if (figures) {
+    if (!fs.existsSync(diagramFilterPath())) required.push('diagram.lua');
+    if (!whichBin('d2', env) && !whichBin('dot', env)) required.push('d2');
+    if (!whichBin('mmdc', env)) required.push('mmdc');
+  }
+  const status = required.map((name) => {
+    if (name.endsWith('.lua')) {
+      return { name, path: fs.existsSync(diagramFilterPath()) ? diagramFilterPath() : null, version: null };
+    }
+    if (name.endsWith('.html')) {
+      return { name, path: deckTemplatePath(repoRoot), version: null };
+    }
+    if (name === 'pptxgenjs') {
+      return { name, path: pptxgenPresent() ? 'bundled' : null, version: null };
+    }
+    if (name === 'libreoffice') {
+      return { name, path: libreOfficePresent(env) ? resolveLibreOfficeBin(env) : null, version: null };
+    }
+    return { name, path: whichBin(name, env), version: null };
+  });
+  for (const s of status) {
+    if (s.path && !s.name.endsWith('.lua') && s.name !== 'pptxgenjs' && s.name !== 'libreoffice') {
+      s.version = binVersion(s.name, ['--version'], env);
+    }
+  }
   const missing = status.filter((s) => !s.path).map((s) => s.name);
   return {
     ok: true,
     format,
+    figures,
     present: missing.length === 0,
     binaries: status,
     missing,
     message: missing.length === 0
-      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'unknown'})`).join(', ')}`
+      ? `Ready: ${status.map((s) => `${s.name} (${s.version?.split(' ').slice(0, 2).join(' ') ?? 'bundled'})`).join(', ')}`
       : missing.map(installHint).join(' '),
   };
 }
@@ -76,31 +228,187 @@ function defaultOutputPath(inputPath, format) {
   return path.join(parsed.dir, `${parsed.name}.${format}`);
 }
 
-// exportMarkdown is the single contract callers depend on (CLI / MCP / SDK).
-// Returns { ok, format, inputPath, outputPath, engine, missing?, message }.
-// ok=false with a populated `missing` means a required binary is absent — the
-// caller surfaces `message` (which carries the install hint) instead of
-// retrying or crashing.
+export function parsePublishFrontmatter(inputPath) {
+  try {
+    const content = fs.readFileSync(inputPath, 'utf8');
+    if (!content.startsWith('---')) return null;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) return null;
+    const block = content.slice(3, end);
+    const publish = {};
+    let inPublish = false;
+    for (const line of block.split('\n')) {
+      if (/^publish:\s*$/.test(line)) { inPublish = true; continue; }
+      if (inPublish && /^\S/.test(line) && !line.startsWith(' ')) inPublish = false;
+      if (!inPublish) continue;
+      const m = line.match(/^\s+(\w+):\s*(.+)$/);
+      if (m) publish[m[1]] = m[2].replace(/^["']|["']$/g, '').trim();
+    }
+    return Object.keys(publish).length ? publish : null;
+  } catch {
+    return null;
+  }
+}
 
-export function exportMarkdown({ inputPath, outputPath, format, env = process.env, spawnFn = spawnSync } = {}) {
+function prepareExportInput(inputPath, { format = 'html', figures = false, metadata = null } = {}) {
+  let raw = fs.readFileSync(inputPath, 'utf8');
+  let processed = raw;
+  if ((format === 'pdf' || format === 'html') && metadata?.title) {
+    processed = preprocessMarkdownForPdfExport(processed, metadata);
+  }
+  if (figures) {
+    processed = preprocessMarkdownDiagrams(processed);
+  }
+  if (processed === raw) return { inputPath, cleanup: null };
+  const tmp = path.join(path.dirname(inputPath), `.construct-export-${path.basename(inputPath)}`);
+  fs.writeFileSync(tmp, processed, 'utf8');
+  return {
+    inputPath: tmp,
+    cleanup: () => { try { fs.unlinkSync(tmp); } catch { /* skip */ } },
+  };
+}
+
+// md and mdx are emitted straight from the authored source: the artifact already
+// is Markdown, and Construct-authored Markdown is MDX-compatible (fenced diagrams,
+// YAML frontmatter), so no transform is needed beyond writing the target file.
+
+function exportSourceCopy({ inputPath, target, format }) {
+  const content = fs.readFileSync(inputPath, 'utf8');
+  fs.writeFileSync(target, content, 'utf8');
+  return {
+    ok: true,
+    format,
+    inputPath,
+    outputPath: target,
+    engine: 'copy',
+    message: `Wrote ${path.relative(process.cwd(), target)}`,
+  };
+}
+
+export function exportMarkdown({
+  inputPath,
+  outputPath,
+  format,
+  figures = false,
+  artifactType = null,
+  env = process.env,
+  spawnFn = spawnSync,
+  cwd = process.cwd(),
+  repoRoot = REPO_ROOT,
+} = {}) {
   if (!inputPath) return { ok: false, format, message: 'exportMarkdown: inputPath is required.' };
   if (!EXPORT_FORMATS.includes(format)) return { ok: false, format, inputPath, message: `Unsupported format: ${format}. Supported: ${EXPORT_FORMATS.join(', ')}.` };
   if (!fs.existsSync(inputPath)) return { ok: false, format, inputPath, message: `exportMarkdown: input does not exist: ${inputPath}` };
 
-  const detection = detect(format, env);
+  const metadata = parseArtifactMetadata(inputPath);
+  const resolvedType = artifactType || metadata.artifactType || null;
+  const effectiveEnv = figures ? buildDistributionDiagramEnv(env) : env;
+
+  const detection = detect(format, effectiveEnv, { figures, artifactType: resolvedType, cwd, repoRoot });
   if (!detection.present) {
     return { ok: false, format, inputPath, missing: detection.missing, message: detection.message };
   }
 
   const config = FORMAT_ENGINES[format];
-  const target = outputPath || defaultOutputPath(inputPath, format);
+  const target = path.resolve(outputPath || defaultOutputPath(inputPath, format));
   fs.mkdirSync(path.dirname(target), { recursive: true });
 
+  if (config.engine === 'copy') {
+    return exportSourceCopy({ inputPath, target, format });
+  }
+
+  if (format === 'pptx') {
+    return exportDeckPptx({ inputPath, outputPath: target, metadata, repoRoot });
+  }
+
+  if (format === 'doc') {
+    const intermediate = path.join(path.dirname(target), `.construct-export-${path.basename(inputPath, path.extname(inputPath))}.docx`);
+    const docxResult = exportMarkdown({
+      inputPath,
+      outputPath: intermediate,
+      format: 'docx',
+      figures,
+      artifactType: resolvedType,
+      env: effectiveEnv,
+      spawnFn,
+      cwd,
+      repoRoot,
+    });
+    if (!docxResult.ok) return { ...docxResult, format: 'doc' };
+    const loResult = convertDocxToDoc({ docxPath: intermediate, outputPath: target, env: effectiveEnv, spawnFn });
+    try { fs.unlinkSync(intermediate); } catch { /* skip */ }
+    if (!loResult.ok) {
+      return {
+        ok: false,
+        format: 'doc',
+        inputPath,
+        outputPath: target,
+        missing: loResult.missing,
+        message: loResult.message,
+      };
+    }
+    return {
+      ok: true,
+      format: 'doc',
+      inputPath,
+      outputPath: target,
+      engine: 'libreoffice',
+      pdfEngine: null,
+      figures,
+      template: null,
+      message: loResult.message,
+    };
+  }
+
+  const prepared = prepareExportInput(inputPath, { format, figures, metadata });
+  const templatePath = format === 'pdf'
+    ? resolvePdfTemplatePath({ artifactType: resolvedType, cwd, repoRoot })
+    : null;
+
+  const metadataArgs = pandocMetadataArgs({
+    title: metadata.title,
+    subtitle: metadata.subtitle,
+    date: metadata.date,
+    status: metadata.status,
+    owner: metadata.owner,
+    artifactType: resolvedType || metadata.artifactType,
+    version: metadata.version,
+    docId: metadata.docId,
+    classification: metadata.classification,
+  });
+
   const args = ['-f', 'markdown', '-o', target, '--standalone'];
   if (config.pdfEngine) args.push(`--pdf-engine=${config.pdfEngine}`);
-  args.push(inputPath);
+  if (format === 'pdf') {
+    if (templatePath) args.push('--template', templatePath);
+    args.push(...pdfEngineFontOpts(repoRoot));
+    args.push(...metadataArgs);
+  } else if (format === 'html') {
+    const htmlTpl = htmlTemplatePath(repoRoot);
+    if (htmlTpl) args.push('--template', htmlTpl);
+    args.push('--embed-resources');
+    args.push(...metadataArgs);
+  } else if (format === 'deck') {
+    const deckTpl = deckTemplatePath(repoRoot);
+    if (deckTpl) args.push('--template', deckTpl);
+    args.push('--section-divs');
+    args.push('--embed-resources');
+    args.push(...metadataArgs);
+  } else if (format === 'docx') {
+    const ref = docxReferencePath(repoRoot);
+    if (ref) args.push('--reference-doc', ref);
+    args.push(...metadataArgs);
+  }
+  if (figures && fs.existsSync(diagramFilterPath())) {
+    args.push('--lua-filter', diagramFilterPath());
+  }
+  args.push(path.resolve(prepared.inputPath));
+
+  const spawnCwd = (format === 'pdf' && templatePath) ? path.dirname(templatePath) : path.dirname(prepared.inputPath);
+
+  const result = spawnFn(config.engine, args, { encoding: 'utf8', env: effectiveEnv, cwd: spawnCwd });
+  if (prepared.cleanup) prepared.cleanup();
 
-  const result = spawnFn(config.engine, args, { encoding: 'utf8', env });
   if (result.status !== 0) {
     return {
       ok: false,
@@ -112,6 +420,20 @@ export function exportMarkdown({ inputPath, outputPath, format, env = process.en
     };
   }
 
+  if (format === 'pdf' && 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)}`,
+      };
+    }
+  }
+
   return {
     ok: true,
     format,
@@ -119,6 +441,8 @@ export function exportMarkdown({ inputPath, outputPath, format, env = process.en
     outputPath: target,
     engine: config.engine,
     pdfEngine: config.pdfEngine,
+    figures,
+    template: templatePath,
     message: `Wrote ${path.relative(process.cwd(), target)}`,
   };
 }