@geraldmaron/construct 1.0.24 → 1.1.1

package/lib/config/schema.mjs

@@ -24,7 +24,7 @@ export const DEFAULT_PROFILE_ID = 'rnd';
 
 export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cursor'];
 
-export const INGEST_STRATEGIES = ['adapter', 'provider'];
+export const INGEST_STRATEGIES = ['adapter', 'provider', 'docling-remote'];
 export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
 export const INGEST_ORCHESTRATIONS = ['prompt-only', 'orchestrated'];
 

package/lib/demo.mjs

@@ -0,0 +1,245 @@
+/**
+ * lib/demo.mjs — `construct demo` command, produces a reproducible terminal
+ * recording of a Construct workflow from a `.tape` script, rendering to
+ * GIF/MP4/WebM via VHS, degrading to asciinema, and finally to emitting the
+ * `.tape` source + install hint when no recorder is installed.
+ *
+ * Tool evaluation (2026-06), against: reproducible-from-code, headless CI
+ * render, distribution formats, license:
+ *   - VHS (charm.sh, MIT): records a `.tape` script (declarative keystrokes +
+ *     timing) to GIF/MP4/WebM headlessly via an embedded ttyd + ffmpeg. The
+ *     `.tape` is deterministic and diffable — the source of truth lives in the
+ *     repo, the artifact regenerates in CI. Chosen as PRIMARY: reproducible,
+ *     embeddable in README/docs, multiple output formats.
+ *   - asciinema (asciinema.org, GPL-3.0): records a terminal session to a
+ *     `.cast` JSON. Reproducible and lightweight but interactive-capture by
+ *     nature and GIF export needs the separate `agg` tool. Chosen as FALLBACK
+ *     when VHS is absent; we drive it non-interactively via `asciinema rec -c`.
+ *   - Playwright (dashboard): out of scope here — it is a dev-only browser
+ *     driver for the web UI, not a terminal recorder, and lives with the
+ *     dashboard tests rather than this command.
+ *
+ * Degradation contract: when neither vhs nor asciinema is on PATH the command
+ * still succeeds (exit 0) by writing the `.tape` SOURCE plus an install hint.
+ * No bundled binaries, no npm dependencies; recorders are detected at runtime,
+ * mirroring lib/runtime/whisper-bootstrap.mjs.
+ *
+ * Output: .cx/demos/<name>-<ts>.<ext> (recording) and the `.tape` source.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve, dirname } from 'node:path';
+
+const FORMATS = ['gif', 'mp4', 'webm'];
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+// Recorder detection follows the optional-external-tool pattern: probe PATH,
+// return a structured descriptor, never throw. VHS is preferred for its
+// declarative `.tape` model and multi-format output; asciinema is the fallback.
+
+export function locateRecorder() {
+  const vhs = which('vhs');
+  if (vhs) return { engine: 'vhs', binary: vhs };
+  const asciinema = which('asciinema');
+  if (asciinema) return { engine: 'asciinema', binary: asciinema };
+  return null;
+}
+
+export function installHint() {
+  if (process.platform === 'darwin') return 'brew install vhs   (or: brew install asciinema)';
+  if (process.platform === 'linux') return 'See https://github.com/charmbracelet/vhs#installation   (or: pip install asciinema)';
+  return 'See https://github.com/charmbracelet/vhs#installation';
+}
+
+// Built-in workflow tapes. Each is a VHS `.tape`: declarative Type/Enter/Sleep
+// directives that record a real walkthrough. Commands are illustrative and
+// safe to replay; tapes are the source of truth, regenerated in CI.
+
+const TAPES = {
+  quickstart: (out) => `# construct demo: quickstart — plan then build
+Output ${out}
+Set FontSize 18
+Set Width 1100
+Set Height 600
+Set Theme "Dracula"
+Set TypingSpeed 60ms
+
+Type "construct plan 'add a rate limiter to the API'"
+Sleep 500ms
+Enter
+Sleep 2s
+
+Type "construct build"
+Sleep 500ms
+Enter
+Sleep 2s
+
+Type "construct ship status"
+Sleep 500ms
+Enter
+Sleep 2s
+`,
+  diagram: (out) => `# construct demo: diagram — render an architecture diagram
+Output ${out}
+Set FontSize 18
+Set Width 1100
+Set Height 600
+Set Theme "Dracula"
+Set TypingSpeed 60ms
+
+Type "construct diagram 'web app: client -> api -> db'"
+Sleep 500ms
+Enter
+Sleep 2s
+`,
+};
+
+export const TAPE_NAMES = Object.keys(TAPES);
+
+export function generateTape(name, outputArtifact) {
+  const builder = TAPES[name];
+  if (!builder) return null;
+  return builder(outputArtifact);
+}
+
+// VHS reads the Output directive from the .tape, so the artifact path is baked
+// into the source before rendering. The render is fully headless.
+
+function renderWithVhs(binary, tapePath) {
+  return spawnSync(binary, [tapePath], { encoding: 'utf8', timeout: 180_000 });
+}
+
+// asciinema can't replay a VHS .tape, so for the fallback we extract the
+// `Type`/`Enter` lines into a single shell command string and capture it
+// non-interactively into a .cast file. The .tape source is still written so
+// the canonical, VHS-renderable form is preserved.
+
+function tapeToShellCommand(tapeSource) {
+  const commands = [];
+  let pending = '';
+  for (const line of tapeSource.split('\n')) {
+    const typeMatch = line.match(/^Type\s+"(.*)"\s*$/);
+    if (typeMatch) { pending = typeMatch[1]; continue; }
+    if (/^Enter\s*$/.test(line) && pending) { commands.push(pending); pending = ''; }
+  }
+  return commands.join(' && ');
+}
+
+function renderWithAsciinema(binary, tapeSource, outPath) {
+  const command = tapeToShellCommand(tapeSource) || 'echo "construct demo"';
+  return spawnSync(binary, ['rec', '--overwrite', '-c', command, outPath], { encoding: 'utf8', timeout: 180_000 });
+}
+
+export function printHelp() {
+  console.log(`Usage: construct demo <name> [options]
+
+Produces a reproducible terminal recording of a Construct workflow from a
+.tape script. Renders to GIF/MP4/WebM via VHS (primary) or a .cast via
+asciinema (fallback). When neither recorder is installed, writes the .tape
+SOURCE plus an install hint and exits 0.
+
+Tapes:
+  ${TAPE_NAMES.join('\n  ')}
+
+Options:
+  --format <f>   gif (default) | mp4 | webm   (VHS only)
+  --out <path>   Output path (default: .cx/demos/<name>-<ts>.<ext>)
+  --source-only  Always write the .tape source; skip recording
+  -h, --help     Show this message
+
+Recorders (detected at runtime, never bundled):
+  VHS        ${process.platform === 'darwin' ? 'brew install vhs' : 'https://github.com/charmbracelet/vhs#installation'}
+  asciinema  ${process.platform === 'darwin' ? 'brew install asciinema' : 'pip install asciinema'}
+
+Examples:
+  construct demo quickstart
+  construct demo diagram --format mp4
+  construct demo quickstart --source-only
+`);
+}
+
+function parseArgs(argv) {
+  const options = { format: 'gif', out: null, sourceOnly: false, name: null };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--source-only') { options.sourceOnly = true; continue; }
+    if (arg === '--format') { options.format = argv[++i]; continue; }
+    if (arg.startsWith('--format=')) { options.format = arg.slice(9); continue; }
+    if (arg === '--out') { options.out = argv[++i]; continue; }
+    if (arg.startsWith('--out=')) { options.out = arg.slice(6); continue; }
+    positional.push(arg);
+  }
+  options.name = positional[0] || null;
+  return options;
+}
+
+export async function runDemoCli(argv = [], { cwd = process.cwd() } = {}) {
+  const options = parseArgs(argv);
+  if (options.help || !options.name) {
+    printHelp();
+    if (!options.help && !options.name) process.exit(1);
+    return;
+  }
+  if (!TAPE_NAMES.includes(options.name)) {
+    console.error(`Unknown demo: ${options.name}. Valid: ${TAPE_NAMES.join(', ')}`);
+    process.exit(1);
+  }
+  if (!FORMATS.includes(options.format)) {
+    console.error(`Unknown format: ${options.format}. Valid: ${FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const recorder = options.sourceOnly ? null : locateRecorder();
+
+  const dir = options.out ? dirname(resolve(cwd, options.out)) : join(cwd, '.cx', 'demos');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const baseName = options.out
+    ? resolve(cwd, options.out).replace(/\.[^./]+$/, '')
+    : join(dir, `${options.name}-${timestamp()}`);
+
+  // asciinema emits .cast; VHS emits the requested image format. The Output
+  // directive baked into the tape must match the artifact VHS will write.
+
+  const artifactExt = recorder?.engine === 'asciinema' ? 'cast' : options.format;
+  const artifactPath = `${baseName}.${artifactExt}`;
+  const tapeSource = generateTape(options.name, artifactPath);
+  const tapePath = `${baseName}.tape`;
+  writeFileSync(tapePath, tapeSource, 'utf8');
+
+  if (!recorder) {
+    console.log(`Demo tape (${options.name}) written to:`);
+    console.log(`  ${tapePath}`);
+    console.log(`\nNo terminal recorder found. To produce a recording, install one:`);
+    console.log(`  ${installHint()}`);
+    console.log(`\nThen: vhs "${tapePath}"`);
+    return;
+  }
+
+  const render = recorder.engine === 'vhs'
+    ? renderWithVhs(recorder.binary, tapePath)
+    : renderWithAsciinema(recorder.binary, tapeSource, artifactPath);
+
+  if (render.status === 0 && existsSync(artifactPath)) {
+    console.log(`Demo (${options.name}) recorded via ${recorder.engine} to:`);
+    console.log(`  ${artifactPath}`);
+    console.log(`Tape: ${tapePath}`);
+    return;
+  }
+
+  console.log(`Demo tape written to:`);
+  console.log(`  ${tapePath}`);
+  console.log(`\nRecorder ${recorder.engine} failed (exit ${render.status}); tape preserved.`);
+  if (render.stderr) console.log(`  ${render.stderr.trim().split('\n').slice(0, 3).join('\n  ')}`);
+}

package/lib/diagram.mjs

@@ -0,0 +1,300 @@
+/**
+ * lib/diagram.mjs — `construct diagram` command, generates code-driven
+ * architecture/flow diagrams from a natural-language description and renders
+ * them to SVG/PNG via an external diagram binary, degrading to source-only
+ * output when no renderer is installed.
+ *
+ * Tool evaluation (2026-06), against: visual distinctiveness, reproducible
+ * from code, headless Node/CI SVG+PNG render, theming, license:
+ *   - D2 (terrastruct, MPL-2.0): single self-contained Go binary, distinctive
+ *     sketch look plus first-class themes, headless `d2 in.d2 out.svg|png`,
+ *     deterministic from a text file. Chosen as PRIMARY for visual
+ *     distinctiveness and one-binary install.
+ *   - Graphviz `dot` (EPL-1.0): ubiquitous, almost always already present on
+ *     CI images and dev machines, headless `dot -Tsvg|-Tpng`. Chosen as
+ *     FALLBACK for reach when D2 is absent.
+ *   - Mermaid: renders natively in many viewers but headless image export
+ *     needs mermaid-cli, which pulls a headless-Chromium npm tree — disallowed
+ *     by ADR-0001 (zero-npm-core). Used only as the SOURCE we emit when no
+ *     binary is present, reusing lib/wireframe.mjs's Mermaid generators so the
+ *     description still yields a viewable diagram in GitHub/Notion/OpenCode.
+ *
+ * Degradation contract: when neither D2 nor dot is on PATH the command still
+ * succeeds (exit 0) by writing the diagram SOURCE (.d2 by default, or .mmd
+ * Mermaid for diagram kinds wireframe.mjs already models) plus an install
+ * hint. No bundled binaries, no npm dependencies; renderers are detected at
+ * runtime, mirroring lib/runtime/whisper-bootstrap.mjs.
+ *
+ * Output: .cx/diagrams/<slug>-<ts>.<ext>.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve, dirname } from 'node:path';
+
+import { generateWireframe } from './wireframe.mjs';
+
+const TYPES = ['architecture', 'flow', 'sequence', 'state', 'er', 'class'];
+const FORMATS = ['svg', 'png'];
+
+function slugify(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'diagram';
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+}
+
+function which(bin) {
+  const result = spawnSync(process.platform === 'win32' ? 'where' : 'which', [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+// Renderer detection follows the optional-external-tool pattern: probe PATH,
+// return a structured descriptor, never throw. D2 is preferred for its
+// distinctive look; dot is the ubiquitous fallback.
+
+export function locateRenderer() {
+  const d2 = which('d2');
+  if (d2) return { engine: 'd2', binary: d2, sourceExt: 'd2' };
+  const dot = which('dot');
+  if (dot) return { engine: 'dot', binary: dot, sourceExt: 'dot' };
+  return null;
+}
+
+export function installHint() {
+  if (process.platform === 'darwin') return 'brew install d2   (or: brew install graphviz)';
+  if (process.platform === 'linux') return 'curl -fsSL https://d2lang.com/install.sh | sh   (or install graphviz via your distro)';
+  return 'See https://d2lang.com/tour/install or https://graphviz.org/download/';
+}
+
+function inferType(description, explicit) {
+  if (explicit) return explicit;
+  const text = String(description || '').toLowerCase();
+  if (/\b(sequence|handshake|request|response|api call)\b/.test(text)) return 'sequence';
+  if (/\b(state|status|transition|machine|lifecycle)\b/.test(text)) return 'state';
+  if (/\b(entity|schema|database|table|relationship|foreign key)\b/.test(text)) return 'er';
+  if (/\b(class|inheritance|interface)\b/.test(text)) return 'class';
+  if (/\b(flow|funnel|step|decision|process)\b/.test(text)) return 'flow';
+  return 'architecture';
+}
+
+// Parse `a -> b -> c` (or `a → b → c`) chains out of the description so a
+// terse architecture prompt produces a real edge graph rather than a single
+// node. Falls back to treating the whole description as one node.
+
+function parseNodes(description) {
+  const text = String(description || '');
+  const arrowSplit = text.split(/\s*(?:->|→|=>)\s*/).map((s) => s.trim()).filter(Boolean);
+  if (arrowSplit.length >= 2) {
+    const stripped = arrowSplit.map((s) => s.replace(/^[a-z0-9\s]*:\s*/i, '').trim() || s);
+    return stripped.map((label) => label.split(/[,/]/)[0].trim()).filter(Boolean);
+  }
+  return [];
+}
+
+function nodeId(label, index) {
+  const id = String(label).toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return id || `n${index}`;
+}
+
+function d2Source(description, nodes) {
+  const header = `# ${description}\n# D2 source — render: d2 this.d2 out.svg  (https://d2lang.com)\n`;
+  if (nodes.length >= 2) {
+    const lines = nodes.map((label, i) => `${nodeId(label, i)}: ${label}`);
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+      lines.push(`${nodeId(nodes[i], i)} -> ${nodeId(nodes[i + 1], i + 1)}`);
+    }
+    return `${header}${lines.join('\n')}\n`;
+  }
+  return `${header}node: ${description || 'Component'}\n`;
+}
+
+function dotSource(description, nodes) {
+  const header = `// ${description}\n// Graphviz DOT source — render: dot -Tsvg this.dot -o out.svg\n`;
+  const body = [];
+  if (nodes.length >= 2) {
+    nodes.forEach((label, i) => body.push(`  ${nodeId(label, i)} [label="${label}"];`));
+    for (let i = 0; i < nodes.length - 1; i += 1) {
+      body.push(`  ${nodeId(nodes[i], i)} -> ${nodeId(nodes[i + 1], i + 1)};`);
+    }
+  } else {
+    body.push(`  node [label="${description || 'Component'}"];`);
+  }
+  return `${header}digraph G {\n  rankdir=LR;\n${body.join('\n')}\n}\n`;
+}
+
+// For diagram kinds wireframe.mjs already models (flow/sequence/state/er) we
+// reuse its Mermaid generators when emitting source-only output, so the
+// description maps to a richer diagram than a bare D2 chain.
+
+const WIREFRAME_KINDS = { flow: 'flow', sequence: 'sequence', state: 'state', er: 'er' };
+
+export function generateDiagram({ description = '', type = null, theme = null } = {}) {
+  const kind = inferType(description, type);
+  const nodes = parseNodes(description);
+
+  let source;
+  let engineHint;
+  if (nodes.length >= 2 || kind === 'architecture' || kind === 'class') {
+    source = d2Source(description, nodes);
+    engineHint = 'd2';
+  } else {
+    const wf = generateWireframe({ description, type: WIREFRAME_KINDS[kind] || 'flow' });
+    source = wf.content;
+    engineHint = 'mermaid';
+  }
+  return { kind, nodes, source, engineHint, theme };
+}
+
+// Render via the detected binary. D2 themes map to numeric ids; an invalid
+// theme name is ignored rather than failing the render. Returns the render
+// result so the caller can fall back to source-only on any non-zero exit.
+
+function renderWithD2(binary, sourcePath, outPath, { format, theme }) {
+  const args = [];
+  if (theme) {
+    const themeId = D2_THEMES[theme.toLowerCase()];
+    if (themeId != null) args.push('--theme', String(themeId));
+  }
+  args.push(sourcePath, outPath);
+  return spawnSync(binary, args, { encoding: 'utf8', timeout: 60_000 });
+}
+
+const D2_THEMES = {
+  neutral: 0,
+  'neutral-grey': 1,
+  'flagship-terrastruct': 3,
+  'cool-classics': 4,
+  'mixed-berry-blue': 5,
+  'grape-soda': 6,
+  aubergine: 7,
+  'colorblind-clear': 8,
+  'vanilla-nitro-cola': 100,
+  'orange-creamsicle': 101,
+  sketch: 200,
+};
+
+function renderWithDot(binary, sourcePath, outPath, { format }) {
+  return spawnSync(binary, [`-T${format}`, sourcePath, '-o', outPath], { encoding: 'utf8', timeout: 60_000 });
+}
+
+export function printHelp() {
+  console.log(`Usage: construct diagram <description> [options]
+
+Generates a code-driven diagram from a description and renders it to SVG/PNG
+via D2 (primary) or Graphviz dot (fallback). When neither renderer is
+installed, writes the diagram SOURCE plus an install hint and exits 0.
+
+Options:
+  --type <t>     architecture (default) | flow | sequence | state | er | class
+  --format <f>   svg (default) | png
+  --theme <name> D2 theme name (e.g. neutral, sketch, cool-classics)
+  --out <path>   Output path (default: .cx/diagrams/<slug>-<ts>.<ext>)
+  --source-only  Always write the source file; skip rendering
+  -h, --help     Show this message
+
+Renderers (detected at runtime, never bundled):
+  D2     ${process.platform === 'darwin' ? 'brew install d2' : 'https://d2lang.com/tour/install'}
+  dot    ${process.platform === 'darwin' ? 'brew install graphviz' : 'https://graphviz.org/download/'}
+
+Examples:
+  construct diagram "web app: client -> api -> db"
+  construct diagram "auth flow" --type flow
+  construct diagram "client -> api -> db" --format png --theme sketch
+`);
+}
+
+function parseArgs(argv) {
+  const options = { type: null, format: 'svg', theme: null, out: null, sourceOnly: false, description: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') { options.help = true; continue; }
+    if (arg === '--source-only') { options.sourceOnly = true; continue; }
+    if (arg === '--type') { options.type = argv[++i]; continue; }
+    if (arg.startsWith('--type=')) { options.type = arg.slice(7); continue; }
+    if (arg === '--format') { options.format = argv[++i]; continue; }
+    if (arg.startsWith('--format=')) { options.format = arg.slice(9); continue; }
+    if (arg === '--theme') { options.theme = argv[++i]; continue; }
+    if (arg.startsWith('--theme=')) { options.theme = arg.slice(8); continue; }
+    if (arg === '--out') { options.out = argv[++i]; continue; }
+    if (arg.startsWith('--out=')) { options.out = arg.slice(6); continue; }
+    options.description.push(arg);
+  }
+  options.description = options.description.join(' ').trim();
+  return options;
+}
+
+export async function runDiagramCli(argv = [], { cwd = process.cwd() } = {}) {
+  const options = parseArgs(argv);
+  if (options.help || !options.description) {
+    printHelp();
+    if (!options.help && !options.description) process.exit(1);
+    return;
+  }
+  if (options.type && !TYPES.includes(options.type)) {
+    console.error(`Unknown type: ${options.type}. Valid: ${TYPES.join(', ')}`);
+    process.exit(1);
+  }
+  if (!FORMATS.includes(options.format)) {
+    console.error(`Unknown format: ${options.format}. Valid: ${FORMATS.join(', ')}`);
+    process.exit(1);
+  }
+
+  const result = generateDiagram({ description: options.description, type: options.type, theme: options.theme });
+  const renderer = options.sourceOnly ? null : locateRenderer();
+
+  const slug = slugify(options.description);
+  const dir = options.out ? dirname(resolve(cwd, options.out)) : join(cwd, '.cx', 'diagrams');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  // Source is always written. When the source is Mermaid (reused wireframe
+  // output) the .d2/.dot renderers can't consume it, so we keep the source
+  // extension honest and skip the binary render in that case.
+
+  const renderableSource = result.engineHint !== 'mermaid';
+  const sourceExt = result.engineHint === 'mermaid' ? 'md' : (renderer ? renderer.sourceExt : 'd2');
+  const baseName = options.out
+    ? resolve(cwd, options.out).replace(/\.[^./]+$/, '')
+    : join(dir, `${slug}-${timestamp()}`);
+  const sourcePath = `${baseName}.${sourceExt}`;
+
+  let source = result.source;
+  if (renderer && renderableSource) {
+    source = renderer.engine === 'dot' ? dotSource(options.description, result.nodes) : d2Source(options.description, result.nodes);
+  }
+  writeFileSync(sourcePath, source, 'utf8');
+
+  if (!renderer || !renderableSource) {
+    console.log(`Diagram source (${result.kind}, ${result.engineHint}) written to:`);
+    console.log(`  ${sourcePath}`);
+    if (!renderer) {
+      console.log(`\nNo diagram renderer found. To render SVG/PNG, install one:`);
+      console.log(`  ${installHint()}`);
+    } else {
+      console.log(`\nThis diagram kind renders as Mermaid; paste into any Mermaid-aware viewer (GitHub, Notion, OpenCode).`);
+    }
+    return;
+  }
+
+  const outPath = `${baseName}.${options.format}`;
+  const render = renderer.engine === 'd2'
+    ? renderWithD2(renderer.binary, sourcePath, outPath, { format: options.format, theme: options.theme })
+    : renderWithDot(renderer.binary, sourcePath, outPath, { format: options.format });
+
+  if (render.status === 0 && existsSync(outPath)) {
+    console.log(`Diagram (${result.kind}) rendered via ${renderer.engine} to:`);
+    console.log(`  ${outPath}`);
+    console.log(`Source: ${sourcePath}`);
+    return;
+  }
+
+  console.log(`Diagram source written to:`);
+  console.log(`  ${sourcePath}`);
+  console.log(`\nRenderer ${renderer.engine} failed (exit ${render.status}); source preserved.`);
+  if (render.stderr) console.log(`  ${render.stderr.trim().split('\n').slice(0, 3).join('\n  ')}`);
+}

package/lib/doctor/index.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/doctor/index.mjs — `construct-doctor` daemon main loop.
  *
- * Long-running Node process spawned by `construct up`. Holds the L0 watchers
+ * Long-running Node process spawned by `construct dev`. Holds the L0 watchers
  * for resource pressure, service health, disk + log rotation, and cost. Each
  * watcher ticks on its own interval; the loop is bounded so a slow watcher
  * never starves the others. Termination via SIGTERM/SIGINT triggers a clean

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

@@ -2,7 +2,7 @@
  * 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
+ * helpers 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, escalates so cx-sre can investigate the underlying churn.
  *

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-extract/docling-client.mjs

@@ -21,10 +21,11 @@ const SIDECAR_SCRIPT = path.resolve(path.dirname(fileURLToPath(import.meta.url))
 const REQUEST_TIMEOUT_MS = 300_000;
 
 let activeSidecar = null;
+let sidecarStarting = null;
 let requestSeq = 0;
 
-function spawnSidecar({ runtimeDir } = {}) {
-  const { pythonBin } = ensureDoclingVenv({ runtimeDir });
+async function spawnSidecar({ runtimeDir } = {}) {
+  const { pythonBin } = await ensureDoclingVenv({ runtimeDir });
   const child = spawn(pythonBin, [SIDECAR_SCRIPT], {
     stdio: ['pipe', 'pipe', 'pipe'],
     env: { ...process.env, PYTHONUNBUFFERED: '1' },
@@ -89,14 +90,23 @@ function spawnSidecar({ runtimeDir } = {}) {
   return sidecar;
 }
 
-function getSidecar() {
+// Provisioning is now async, so two concurrent extracts could both spawn a
+// sidecar. Cache the in-flight start promise so the first call wins and the rest
+// await it; once resolved, the running sidecar is reused directly.
+
+async function getSidecar() {
   if (activeSidecar && activeSidecar.child.exitCode === null && !activeSidecar.child.killed) return activeSidecar;
-  activeSidecar = spawnSidecar();
-  return activeSidecar;
+  if (!sidecarStarting) {
+    sidecarStarting = spawnSidecar().then(
+      (s) => { activeSidecar = s; sidecarStarting = null; return s; },
+      (e) => { sidecarStarting = null; throw e; },
+    );
+  }
+  return sidecarStarting;
 }
 
 export async function extractViaDocling(filePath) {
-  const sidecar = getSidecar();
+  const sidecar = await getSidecar();
   const result = await sidecar.send('extract', { path: path.resolve(filePath) });
   return result;
 }

package/lib/document-extract/docling-sidecar.py

@@ -36,10 +36,40 @@ except ImportError as exc:
 _converter = None
 
 
+# By default docling emits a bare `<!-- image -->` marker and discards pixel data,
+# so embedded figures are lost. Enable picture-image generation on the PDF
+# pipeline and export markdown with images embedded as base64 data URIs; the Node
+# side externalizes those into an assets/ directory. The configuration is wrapped
+# so a docling API change degrades to the default converter instead of crashing.
+
+def build_converter():
+    try:
+        from docling.datamodel.base_models import InputFormat
+        from docling.datamodel.pipeline_options import PdfPipelineOptions
+        from docling.document_converter import PdfFormatOption
+
+        pdf_options = PdfPipelineOptions()
+        pdf_options.generate_picture_images = True
+        pdf_options.images_scale = 2.0
+        return DocumentConverter(
+            format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pdf_options)}
+        )
+    except Exception:
+        return DocumentConverter()
+
+
+def export_markdown(doc):
+    try:
+        from docling_core.types.doc import ImageRefMode
+        return doc.export_to_markdown(image_mode=ImageRefMode.EMBEDDED)
+    except Exception:
+        return doc.export_to_markdown()
+
+
 def get_converter():
     global _converter
     if _converter is None:
-        _converter = DocumentConverter()
+        _converter = build_converter()
     return _converter
 
 
@@ -53,7 +83,7 @@ def extract(params):
 
     result = get_converter().convert(str(path))
     doc = result.document
-    markdown = doc.export_to_markdown()
+    markdown = export_markdown(doc)
 
     metadata = {
         "format": result.input.format.value if hasattr(result.input, "format") else None,