@geraldmaron/construct 1.3.1 → 1.4.0

package/lib/certification/artifact-gates.mjs

@@ -53,11 +53,16 @@ export function validateAllGoldenArtifactGates({ rootDir } = {}) {
   return { pass: errors.length === 0, results, errors, matrix: artifactGateMatrix({ rootDir: root }) };
 }
 
+// The committed gate matrix is a deterministic projection of the rootDir; no
+// wall-clock field, so regenerating it (the artifact-gates test writes it on every
+// run) yields a byte-identical file instead of a timestamp-only diff on a tracked
+// artifact. The matrix content is the signal; when it changes, the diff is real.
+
 export function writeArtifactGateMatrixDoc({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
   const out = path.join(root, 'tests', 'certification', 'artifacts', 'gate-matrix.json');
   fs.mkdirSync(path.dirname(out), { recursive: true });
-  const payload = { generatedAt: new Date().toISOString(), matrix: artifactGateMatrix({ rootDir: root }) };
+  const payload = { matrix: artifactGateMatrix({ rootDir: root }) };
   fs.writeFileSync(out, `${JSON.stringify(payload, null, 2)}\n`);
   return out;
 }

package/lib/cli-commands.mjs

@@ -346,6 +346,7 @@ export const CLI_COMMANDS = [
       { flag: '--recording=<name>', desc: 'Playwright recording manifest (repeatable)' },
       { flag: '--figures', desc: 'Render d2/mermaid via diagram filter (default on)' },
       { flag: '--no-figures', desc: 'Skip diagram filter' },
+      { flag: '--preview', desc: 'Render the export to images and report what was verified' },
       { flag: '--no-gate', desc: 'Skip artifact release gate (escape hatch only)' },
       { flag: '--source-only', desc: 'Write sources only' },
       { flag: '--strict', desc: 'Exit 2 when toolchain or release gate fails (default)' },
@@ -453,11 +454,12 @@ export const CLI_COMMANDS = [
     emoji: '🎼',
     category: 'Models & Integrations',
     core: false,
-    description: 'Construct-owned local orchestration runtime, in-process or against the local daemon (--remote)',
-    usage: 'construct orchestrate <run|status> [options] [--remote]',
+    description: 'Construct-owned local orchestration runtime and readiness preflight',
+    usage: 'construct orchestrate <run|status|preflight> [options] [--remote]',
     subcommands: [
       { name: 'run "<request>" [--strategy S] [--host H] [--worker-backend provider] [--no-construct] [--no-execute] [--json] [--remote]', desc: 'Plan and run a request through a Construct-owned specialist chain; --remote drives the local daemon over HTTP' },
       { name: 'status [run-id] [--json] [--remote]', desc: 'Inspect a run, or list recent runs (locally or from the daemon)' },
+      { name: 'preflight [--host H] [--json] [--no-probe]', desc: 'Verify orchestration tool attachment/readiness and return a typed reason plus recovery step' },
     ],
   },
   {
@@ -1144,7 +1146,7 @@ export const CLI_COMMANDS = [
   { name: 'team:remove',       category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Remove a team from the unified registry', usage: 'construct team:remove <team-id> [--force]' },
   { name: 'specialist:add',    category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Add a new specialist to a team', usage: 'construct specialist:add <specialist-id> --team <team-id>' },
   { name: 'specialist:remove', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Remove a specialist from the unified registry', usage: 'construct specialist:remove <specialist-id> [--force]' },
-  { name: 'oracle', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
+  { name: 'oracle', emoji: '🔮', category: 'Core', core: true, description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
   { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
   { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
   { name: 'rules', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Rule and hook reference telemetry rollup', usage: 'construct rules usage [--since=30d]' },

package/lib/codex-config.mjs

@@ -70,12 +70,18 @@ function resolveArgs(args, resolvedValues) {
   );
 }
 
+// Codex has no runtime env interpolation (see docs/guides/reference/mcp-tools.md),
+// so a stdio `env` block must hold literal values, not host env-ref forms — the
+// value-to-reference flip is deliberately not applied here. An unresolved `__NAME__`
+// template or a 1Password `op://` reference would be passed verbatim to the child and
+// fail, so both are dropped rather than written.
+
 function resolveEnv(env, resolvedValues) {
   if (!env || typeof env !== 'object' || Array.isArray(env)) return {};
   return Object.fromEntries(
     Object.entries(env)
       .map(([key, value]) => [key, typeof value === 'string' ? resolveTemplateString(value, resolvedValues) : value])
-      .filter(([, value]) => typeof value !== 'string' || !value.includes('__')),
+      .filter(([, value]) => typeof value !== 'string' || (!value.includes('__') && !value.startsWith('op://'))),
   );
 }
 

package/lib/deck-export-pptx.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { BRAND_TOKENS, INK } from './brand-tokens.mjs';
 import { createPptxGenerator, embedBundledSansInPptx, embedBundledMonoInPptx, BRAND_SANS_FAMILY } from './brand-fonts.mjs';
 import { parseArtifactMetadata } from './publish-template.mjs';
+import { injectMermaidBrandTheme, injectD2DistributionDefaults, buildDistributionDiagramEnv } from './diagram-export.mjs';
 
 const require = createRequire(import.meta.url);
 const MODULE_URL = pathToFileURL(fileURLToPath(import.meta.url)).href;
@@ -42,6 +43,13 @@ const CARD_INK_BAR = 0.045;
 const CARD_BADGE_W = 0.22;
 const CARD_MIN_H = 0.28;
 
+// Readability floors. 8pt is the smallest projectable body size; below it slide text is
+// unreadable at distance. A slide must not stack more list items than a viewer can hold, and
+// must not pack so much that fitting it (pptxgen shrink-to-fit) drives the font under the floor.
+
+export const DECK_FONT_FLOOR_PT = 8;
+export const MAX_BULLETS_PER_SLIDE = 8;
+
 function ptSize(token) {
   return parseFloat(String(token || '').replace('pt', '')) || 10;
 }
@@ -226,6 +234,11 @@ function estimateListHeight(block, layout) {
 
 function estimateBlockHeight(block, layout = { w: CW }) {
   if (block.type === 'heading') return 0;
+  if (block.type === 'diagram') return 2.6;
+  if (block.type === 'code') {
+    const lineCount = String(block.code || '').split('\n').length;
+    return Math.min(3.0, 0.2 + lineCount * lineHeightIn(T.small) * 1.1);
+  }
   if (block.type === 'text') {
     const len = cellPlainLength(block.text);
     const fontSize = len > 140 ? T.small : T.body;
@@ -295,6 +308,28 @@ export function auditDeckMarkdownLayout(markdown, metadata = {}) {
       y += estimateBlockHeight(block, layout);
     }
 
+    const listItemCount = blocks
+      .filter((b) => b.type === 'bullet' || b.type === 'number')
+      .reduce((sum, b) => sum + b.items.length, 0);
+    if (listItemCount > MAX_BULLETS_PER_SLIDE) {
+      slideIssues.push({
+        code: 'bullet_density',
+        detail: `${listItemCount} list items exceed the ${MAX_BULLETS_PER_SLIDE}-bullet readability limit`,
+      });
+    }
+
+    // pptxgen shrinks text to fit its box, so a slide estimated taller than the budget would
+    // render at a proportionally smaller font. Flag when that implied font drops below the floor.
+
+    const fitRatio = y > 0 ? Math.min(1, SLIDE_CONTENT_BUDGET_IN / y) : 1;
+    const impliedFont = T.body * fitRatio;
+    if (impliedFont < DECK_FONT_FLOOR_PT) {
+      slideIssues.push({
+        code: 'font_below_floor',
+        detail: `fitting this slide implies ~${impliedFont.toFixed(1)}pt, below the ${DECK_FONT_FLOOR_PT}pt floor`,
+      });
+    }
+
     if (layout.mode === 'ink-panel') {
       const panelBottom = 0.28 + 0.05 + 0.18 + 0.38 + 0.72;
       if (panelBottom > SLIDE_CONTENT_BUDGET_IN * 0.55) {
@@ -419,16 +454,39 @@ function hex(hexColor) {
   return String(hexColor || '').replace(/^#/, '');
 }
 
+// A level-1 `# ` heading starts a new slide (pandoc slide-level 1, matching the HTML
+// deck template), as do explicit `---` / `****` rules. Boundaries inside fenced code are
+// ignored so a `#` comment in a d2 block or a `---` in a snippet never splits a slide.
+
 function splitSlides(markdown) {
   let body = String(markdown || '');
   if (body.startsWith('---')) {
     const end = body.indexOf('\n---', 3);
     if (end !== -1) body = body.slice(end + 4);
   }
-  return body
-    .split(/\n(?:---|\*\*\*\*)\n/)
-    .map((chunk) => chunk.trim())
-    .filter(Boolean);
+
+  const parts = [];
+  let current = [];
+  let inFence = false;
+  const flush = () => {
+    if (current.some((line) => line.trim())) parts.push(current.join('\n'));
+    current = [];
+  };
+  for (const line of body.split('\n')) {
+    if (/^```/.test(line)) inFence = !inFence;
+    if (!inFence && /^#\s+\S/.test(line)) {
+      flush();
+      current.push(line);
+      continue;
+    }
+    if (!inFence && /^(?:---|\*\*\*\*)\s*$/.test(line)) {
+      flush();
+      continue;
+    }
+    current.push(line);
+  }
+  flush();
+  return parts.map((chunk) => chunk.trim()).filter(Boolean);
 }
 
 function parseInlineRuns(text, base = {}) {
@@ -504,6 +562,27 @@ function slideBlocks(chunk) {
     const raw = lines[i];
     const line = raw.trimEnd();
 
+    const fence = line.match(/^```\s*([\w-]*)\s*$/);
+    if (fence) {
+      flushPara();
+      flushList();
+      const lang = fence[1].toLowerCase();
+      i += 1;
+      const code = [];
+      while (i < lines.length && !/^```\s*$/.test(lines[i].trimEnd())) {
+        code.push(lines[i]);
+        i += 1;
+      }
+      i += 1;
+      const body = code.join('\n');
+      if (lang === 'mermaid' || lang === 'd2') {
+        blocks.push({ type: 'diagram', lang, code: body });
+      } else {
+        blocks.push({ type: 'code', lang, code: body });
+      }
+      continue;
+    }
+
     if (isTableLine(line) && i + 1 < lines.length && isTableSeparator(lines[i + 1])) {
       flushPara();
       flushList();
@@ -969,7 +1048,104 @@ function addListCards(slide, pptx, block, y, maxY, layout = {}) {
   return cy + 0.04;
 }
 
-function addContentSlide(pptx, chunk, slideIndex, totalSlides, deckTitle) {
+// PNG carries width/height as big-endian uint32 at byte offsets 16 and 20 (the IHDR
+// chunk). Reading the header avoids an image dependency just to fit a diagram by aspect.
+
+function pngDimensions(file) {
+  const buf = fs.readFileSync(file);
+  if (buf.length > 24 && buf[0] === 0x89 && buf[1] === 0x50) {
+    return { w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+  }
+  return null;
+}
+
+// Diagram fences are rendered to PNG with the same monochrome sketch styling as the
+// PDF/HTML path: mmdc for mermaid (hand-drawn theme injected), d2 --sketch for d2. A
+// missing renderer returns a typed error so the caller can record it, never a silent drop.
+
+function renderDiagramToPng(lang, code, tmpDir, baseEnv, idx) {
+  const env = buildDistributionDiagramEnv(baseEnv);
+  const out = path.join(tmpDir, `diagram-${idx}.png`);
+  if (lang === 'mermaid') {
+    const src = path.join(tmpDir, `diagram-${idx}.mmd`);
+    fs.writeFileSync(src, injectMermaidBrandTheme(code));
+    const args = ['-i', src, '-o', out, '-b', 'transparent', '-s', '2', '-w', '1600'];
+    if (env.CONSTRUCT_MERMAID_PPTR_CONFIG) args.push('-p', env.CONSTRUCT_MERMAID_PPTR_CONFIG);
+    const r = spawnSync('mmdc', args, { encoding: 'utf8', env });
+    if (r.status !== 0 || !fs.existsSync(out)) return { error: (r.stderr || 'mmdc failed').trim().slice(0, 200) };
+  } else {
+    const src = path.join(tmpDir, `diagram-${idx}.d2`);
+    fs.writeFileSync(src, injectD2DistributionDefaults(code));
+    const r = spawnSync('d2', ['--sketch', '--pad', '16', '--theme', '0', src, out], { encoding: 'utf8', env });
+    if (r.status !== 0 || !fs.existsSync(out)) return { error: (r.stderr || 'd2 failed').trim().slice(0, 200) };
+  }
+  const dim = pngDimensions(out) || { w: 1600, h: 900 };
+  return { path: out, w: dim.w, h: dim.h };
+}
+
+function addDiagramImage(slide, pptx, block, y, maxY, layout, renderCtx) {
+  const availH = maxY - y - 0.04;
+  if (availH < 0.6) return y;
+  const rendered = renderDiagramToPng(block.lang, block.code, renderCtx.tmpDir, renderCtx.env, renderCtx.seq);
+  renderCtx.seq += 1;
+  renderCtx.attempted += 1;
+
+  if (rendered.error) {
+    renderCtx.errors.push({ lang: block.lang, error: rendered.error });
+    const box = clampBox(layout.x, y, layout.w, Math.min(availH, 0.9));
+    slide.addShape(pptx.shapes.RECTANGLE, {
+      ...box,
+      fill: { color: hex(BRAND_TOKENS.surface.alt) },
+      line: { color: hex(BRAND_TOKENS.line.hairline), width: 0.75 },
+      rectRadius: 0.04,
+    });
+    addWrappedText(slide, `[${block.lang} diagram could not render]`, {
+      x: box.x + 0.14, y: box.y + 0.1, w: box.w - 0.28, h: box.h - 0.16,
+    }, T.small, { color: BRAND_TOKENS.ink.muted, italic: true });
+    return box.y + box.h + 0.1;
+  }
+
+  renderCtx.rendered += 1;
+  const availW = layout.w;
+  const imgAspect = rendered.w / rendered.h;
+  let drawW = availW;
+  let drawH = availW / imgAspect;
+  if (drawH > availH) {
+    drawH = availH;
+    drawW = availH * imgAspect;
+  }
+  const ix = layout.x + (availW - drawW) / 2;
+  slide.addImage({ path: rendered.path, x: ix, y, w: drawW, h: drawH });
+  return y + drawH + 0.1;
+}
+
+function addCodeBlock(slide, pptx, block, y, maxY, layout) {
+  const fontSize = T.small;
+  const lineCount = String(block.code || '').split('\n').length;
+  const estH = Math.min(maxY - y - 0.04, 0.2 + lineCount * lineHeightIn(fontSize) * 1.1);
+  const box = clampBox(layout.x, y, layout.w, estH);
+  slide.addShape(pptx.shapes.RECTANGLE, {
+    ...box,
+    fill: { color: hex(BRAND_TOKENS.surface.default) },
+    line: { color: hex(BRAND_TOKENS.line.hairline), width: 0.75 },
+    rectRadius: 0.04,
+  });
+  slide.addText(String(block.code || ''), {
+    x: box.x + 0.12,
+    y: box.y + 0.08,
+    w: box.w - 0.24,
+    h: box.h - 0.16,
+    fontFace: BRAND_TOKENS.typography.fontMono,
+    color: hex(BRAND_TOKENS.ink.strong),
+    fontSize,
+    valign: 'top',
+    wrap: true,
+    fit: 'shrink',
+  });
+  return box.y + box.h + 0.1;
+}
+
+function addContentSlide(pptx, chunk, slideIndex, totalSlides, deckTitle, renderCtx) {
   const slide = pptx.addSlide();
   addSlideChrome(slide, pptx, { slideIndex, totalSlides, title: deckTitle });
   addSlideAccent(slide);
@@ -1015,6 +1191,10 @@ function addContentSlide(pptx, chunk, slideIndex, totalSlides, deckTitle) {
       y = addListCards(slide, pptx, block, y, maxY, contentLayout);
     } else if (block.type === 'table') {
       y = addTableBlock(slide, pptx, block, y, maxY);
+    } else if (block.type === 'diagram' && renderCtx) {
+      y = addDiagramImage(slide, pptx, block, y, maxY, contentLayout, renderCtx);
+    } else if (block.type === 'code') {
+      y = addCodeBlock(slide, pptx, block, y, maxY, contentLayout);
     }
   }
 }
@@ -1078,21 +1258,44 @@ export async function exportDeckPptxAsync({
   const fontEmbed = await embedBundledSansInPptx(pptx, repoRoot);
   await embedBundledMonoInPptx(pptx, repoRoot);
 
-  addTitleSlide(pptx, metadata, totalSlides);
-  contentChunks.forEach((chunk, index) => {
-    addContentSlide(pptx, chunk, index + 2, totalSlides, metadata.title || '');
-  });
+  const renderCtx = {
+    tmpDir: fs.mkdtempSync(path.join(os.tmpdir(), 'pptx-fig-')),
+    env: process.env,
+    seq: 0,
+    attempted: 0,
+    rendered: 0,
+    errors: [],
+  };
 
   try {
-    await pptx.writeFile({ fileName: outputPath });
-  } catch (err) {
-    return {
-      ok: false,
-      format: 'pptx',
-      inputPath,
-      outputPath,
-      message: `PPTX export failed: ${err.message}`,
-    };
+    addTitleSlide(pptx, metadata, totalSlides);
+    contentChunks.forEach((chunk, index) => {
+      addContentSlide(pptx, chunk, index + 2, totalSlides, metadata.title || '', renderCtx);
+    });
+
+    if (renderCtx.attempted > 0 && renderCtx.rendered === 0) {
+      return {
+        ok: false,
+        format: 'pptx',
+        inputPath,
+        outputPath,
+        message: `PPTX export failed: 0/${renderCtx.attempted} diagram(s) rendered. Ensure d2 and mermaid-cli are installed (mmdc needs Chrome; set PUPPETEER_EXECUTABLE_PATH). First error: ${renderCtx.errors[0]?.error || 'unknown'}`,
+      };
+    }
+
+    try {
+      await pptx.writeFile({ fileName: outputPath });
+    } catch (err) {
+      return {
+        ok: false,
+        format: 'pptx',
+        inputPath,
+        outputPath,
+        message: `PPTX export failed: ${err.message}`,
+      };
+    }
+  } finally {
+    fs.rmSync(renderCtx.tmpDir, { recursive: true, force: true });
   }
 
   return {
@@ -1104,6 +1307,8 @@ export async function exportDeckPptxAsync({
     slideCount: totalSlides,
     layout,
     fontsEmbedded: fontEmbed.embedded,
+    diagramsRendered: renderCtx.rendered,
+    diagramWarnings: renderCtx.errors,
     message: `Wrote ${outputPath}`,
   };
 }

package/lib/diagram-quality.mjs

@@ -0,0 +1,161 @@
+/**
+ * lib/diagram-quality.mjs — Diagram quality heuristics beyond syntax/render success.
+ *
+ * A diagram can render cleanly and still be unreadable: too many nodes to follow, labels too long
+ * to fit, a flowchart decision with no branch labels (only the happy path drawn), or a sequence
+ * diagram with too few participants to be worth a diagram. analyzeDiagramQuality parses mermaid and
+ * d2 source and returns typed findings for each gap. It judges purpose and legibility, not syntax —
+ * the render path already proves a diagram compiles. Consumed by the publish diagram preprocessor,
+ * which surfaces findings as advisory warnings unless frontmatter opts into strict.
+ */
+
+export const MAX_NODES = 24;
+export const MAX_LABEL_CHARS = 48;
+export const MIN_SEQUENCE_PARTICIPANTS = 2;
+
+// Unlabeled edges are deliberately NOT a finding: a bare arrow is idiomatic in dependency and
+// data-flow diagrams (`A --> B` reads as "A produces B"), so flagging it would punish correct
+// diagrams. Edge labeling only matters at decision branches, which decision_without_branches owns.
+
+export const DIAGRAM_QUALITY_CODES = Object.freeze([
+  'node_density_high',
+  'label_too_long',
+  'decision_without_branches',
+  'sequence_too_few_participants',
+]);
+
+// mermaid declares its kind on the first non-directive line; d2 has no header, so anything that is
+// neither a mermaid kind nor empty is treated as d2.
+
+export function detectDiagramKind(code, lang) {
+  const body = String(code || '').replace(/^%%\{[\s\S]*?\}%%/m, '');
+  const first = body.split('\n').map((l) => l.trim()).find(Boolean) || '';
+  if (/^sequenceDiagram\b/.test(first)) return 'sequence';
+  if (/^(flowchart|graph)\b/.test(first)) return 'flowchart';
+  if (lang === 'mermaid') return 'mermaid-other';
+  return 'd2';
+}
+
+function stripDirectives(code) {
+  return String(code || '').replace(/^%%\{[\s\S]*?\}%%/m, '').trim();
+}
+
+// Flowchart: node ids appear in `id[label]` / `id{decision}` definitions and on both sides of an
+// edge. Decision nodes use {}; edge labels ride in `-->|label|` or `-- label -->`.
+
+function analyzeFlowchart(code) {
+  const findings = [];
+  const lines = stripDirectives(code).split('\n').slice(1).map((l) => l.trim()).filter(Boolean);
+  const nodes = new Set();
+  const decisions = new Set();
+  const outgoing = new Map();
+
+  const nodeDef = /([A-Za-z0-9_]+)\s*([[({])([^\])}]*)[\])}]/g;
+  const edge = /([A-Za-z0-9_]+)\s*(?:[ox]?[-.=]+[->]*\|([^|]*)\||[-.=]+[->]+)\s*([A-Za-z0-9_]+)/;
+
+  for (const line of lines) {
+    let m;
+    while ((m = nodeDef.exec(line))) {
+      nodes.add(m[1]);
+      if (m[2] === '{') decisions.add(m[1]);
+      if ((m[3] || '').trim().length > MAX_LABEL_CHARS) {
+        findings.push({ code: 'label_too_long', detail: `node ${m[1]} label is ${m[3].trim().length} chars (max ${MAX_LABEL_CHARS})` });
+      }
+    }
+    const e = edge.exec(line);
+    if (e) {
+      nodes.add(e[1]);
+      nodes.add(e[3]);
+      const label = (e[2] || '').trim();
+      if (label.length > MAX_LABEL_CHARS) findings.push({ code: 'label_too_long', detail: `edge ${e[1]}->${e[3]} label is ${label.length} chars (max ${MAX_LABEL_CHARS})` });
+      outgoing.set(e[1], (outgoing.get(e[1]) || 0) + 1);
+    }
+  }
+
+  if (nodes.size > MAX_NODES) findings.push({ code: 'node_density_high', detail: `${nodes.size} nodes exceed the ${MAX_NODES}-node readability limit` });
+  for (const d of decisions) {
+    if ((outgoing.get(d) || 0) < 2) {
+      findings.push({ code: 'decision_without_branches', detail: `decision ${d} has ${(outgoing.get(d) || 0)} outgoing branch(es); a decision needs at least the yes/no paths` });
+    }
+  }
+  return findings;
+}
+
+// Sequence: `participant X` declarations plus actors on either side of a message arrow.
+
+function analyzeSequence(code) {
+  const findings = [];
+  const lines = stripDirectives(code).split('\n').slice(1).map((l) => l.trim()).filter(Boolean);
+  const participants = new Set();
+
+  for (const line of lines) {
+    const decl = line.match(/^(?:participant|actor)\s+([A-Za-z0-9_]+)/);
+    if (decl) { participants.add(decl[1]); continue; }
+    const msg = line.match(/^([A-Za-z0-9_]+)\s*-[->x)]+\s*([A-Za-z0-9_]+)\s*:(.*)$/);
+    if (msg) {
+      participants.add(msg[1]);
+      participants.add(msg[2]);
+      if (msg[3].trim().length > MAX_LABEL_CHARS) findings.push({ code: 'label_too_long', detail: `message ${msg[1]}->${msg[2]} is ${msg[3].trim().length} chars (max ${MAX_LABEL_CHARS})` });
+    }
+  }
+
+  if (participants.size < MIN_SEQUENCE_PARTICIPANTS) {
+    findings.push({ code: 'sequence_too_few_participants', detail: `${participants.size} participant(s); a sequence needs at least ${MIN_SEQUENCE_PARTICIPANTS}` });
+  }
+  if (participants.size > MAX_NODES) findings.push({ code: 'node_density_high', detail: `${participants.size} participants exceed the ${MAX_NODES} limit` });
+  return findings;
+}
+
+// d2: connections `a -> b`, optional `: label`; standalone `id: label` names a node.
+
+function analyzeD2(code) {
+  const findings = [];
+  const lines = stripDirectives(code).split('\n').map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+  const nodes = new Set();
+
+  for (const line of lines) {
+    const conn = line.match(/^([A-Za-z0-9_.]+)\s*(?:<->|->|<-|--)\s*([A-Za-z0-9_.]+)\s*(?::(.*))?$/);
+    if (conn) {
+      nodes.add(conn[1]);
+      nodes.add(conn[2]);
+      const label = (conn[3] || '').trim();
+      if (label.length > MAX_LABEL_CHARS) findings.push({ code: 'label_too_long', detail: `edge ${conn[1]}->${conn[2]} label is ${label.length} chars (max ${MAX_LABEL_CHARS})` });
+      continue;
+    }
+    const node = line.match(/^([A-Za-z0-9_.]+)\s*:\s*(.+)$/);
+    if (node) {
+      nodes.add(node[1]);
+      if (node[2].trim().length > MAX_LABEL_CHARS) findings.push({ code: 'label_too_long', detail: `node ${node[1]} label is ${node[2].trim().length} chars (max ${MAX_LABEL_CHARS})` });
+    }
+  }
+
+  if (nodes.size > MAX_NODES) findings.push({ code: 'node_density_high', detail: `${nodes.size} nodes exceed the ${MAX_NODES}-node readability limit` });
+  return findings;
+}
+
+export function analyzeDiagramQuality(code, { lang } = {}) {
+  const kind = detectDiagramKind(code, lang);
+  let findings = [];
+  if (kind === 'flowchart') findings = analyzeFlowchart(code);
+  else if (kind === 'sequence') findings = analyzeSequence(code);
+  else if (kind === 'd2') findings = analyzeD2(code);
+  return { ok: findings.length === 0, kind, findings };
+}
+
+// Every fenced mermaid/d2 block in a document, analyzed and flattened into one advisory list so
+// the publish path can surface legibility warnings. `cx_diagram_quality: strict` in frontmatter
+// is honored by the caller to escalate these from warnings to gate failures.
+
+export function lintDocumentDiagrams(markdown) {
+  const src = String(markdown || '');
+  const warnings = [];
+  const fenceRe = /```(mermaid|d2)\n([\s\S]*?)```/g;
+  let match;
+  let index = 0;
+  while ((match = fenceRe.exec(src))) {
+    index += 1;
+    const { kind, findings } = analyzeDiagramQuality(match[2], { lang: match[1] });
+    for (const finding of findings) warnings.push({ diagram: index, kind, ...finding });
+  }
+  return { ok: warnings.length === 0, warnings };
+}

package/lib/document-export.mjs

@@ -175,7 +175,7 @@ export function detectPdfTemplate({
   };
 }
 
-function whichBin(name, env = process.env) {
+export function whichBin(name, env = process.env) {
   const cmd = process.platform === 'win32' ? 'where' : 'which';
   const result = spawnSync(cmd, [name], { encoding: 'utf8', env });
   if (result.status !== 0) return null;

package/lib/env-config.mjs

@@ -3,9 +3,11 @@
  *
  * Provides helpers to load the user config.env (XDG config dir) and a project
  * .env, merge them with process.env, and persist key/value pairs back to disk.
- * Project .env wins over user config.env, which wins over shell exports. Backs
- * setup, model-router, and the MCP server when they resolve API keys and model
- * overrides without leaking secrets.
+ * Project .env wins over user config.env, which wins over shell exports. The
+ * on-demand resolver (lib/providers/secret-resolver.mjs) shares this file-tier
+ * order — project .env over config.env — so a key resolves the same way on both
+ * paths. Backs setup, model-router, and the MCP server when they resolve API keys
+ * and model overrides without leaking secrets.
  */
 import fs from 'node:fs';
 import os from 'node:os';
@@ -128,9 +130,8 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
       if (rootEnv[key] === userEnv[key]) continue;
       if (preferInjectedCredential(rootEnv[key], userEnv[key])) continue;
       process.stderr.write(
-        `[construct] WARNING: ${key} is set in both project .env (${rootEnv[key].slice(0, 6)}…) ` +
-        `and ${userEnvPath} (${userEnv[key].slice(0, 6)}…). ` +
-        `Project .env wins. To silence: remove the key from one file.\n`,
+        `[construct] WARNING: ${key} is set to different values in project .env ` +
+        `and ${userEnvPath}. Project .env wins. To silence: remove the key from one file.\n`,
       );
     }
 
@@ -145,8 +146,7 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
       if (key in fileEnv && fileEnv[key] !== env[key]) {
         if (preferInjectedCredential(env[key], fileEnv[key])) continue;
         process.stderr.write(
-          `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) ` +
-          `differs from the config file value (${fileEnv[key].slice(0, 6)}…). ` +
+          `[construct] WARNING: process.env.${key} differs from the config file value. ` +
           `The config file will be used. To silence: unset the shell variable or ` +
           `update the config file to match.\n`,
         );