@geraldmaron/construct 1.0.23 → 1.1.0

package/lib/audit-rules.mjs

@@ -0,0 +1,127 @@
+/**
+ * lib/audit-rules.mjs — static reference audit for the rules/ corpus.
+ *
+ * Rules are not retrieved into agent context through any single runtime path the
+ * way skills are (no `logSkillCall` analog fits — they are named by path in prose
+ * the host's Read tool resolves, or read by enforcement tooling), so "which rules
+ * earn their keep" is a STATIC question. A rule is load-bearing two ways:
+ *   1. GLOB-SCOPED — its frontmatter declares `paths:` globs (the Cline/Cursor
+ *      pattern), so it is intended to activate on a matching edit. Whether those
+ *      globs are actually delivered to each host's rule config is a separate
+ *      concern; here they mark the rule as intentionally scoped, not an orphan.
+ *   2. REFERENCED — the canonical `rules/<dir>/<name>` path token (with or without
+ *      the .md) appears somewhere in the active surface (personas, CLAUDE.md,
+ *      skills, all of lib/ except the minified dashboard bundles, registry/
+ *      contracts, other rules, scripts, the CLI).
+ * A rule that is neither glob-activated nor referenced is a true orphan — a
+ * pruning candidate. A rule's own file never counts as referencing itself.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// Directories and files that make up the "active surface" a rule could be cited
+// from. Code and prose both count — a rule named in a hook or in bin/construct is
+// as load-bearing as one named in a persona.
+
+const SURFACE_DIRS = ['personas', 'skills', 'rules', 'lib', 'specialists', 'scripts'];
+const SURFACE_FILES = ['CLAUDE.md', 'AGENTS.md', 'bin/construct', 'claude/settings.template.json'];
+const TEXT_EXT = new Set(['.md', '.mjs', '.js', '.json', '.txt', '.mdx']);
+
+// The minified Next.js dashboard bundles contain unrelated "rules/" tokens (the
+// markdown lexer's own grammar) that would read as false references.
+const SURFACE_SKIP = ['lib/server/static'];
+
+function isSkipped(full, root) {
+  const rel = path.relative(root, full);
+  return SURFACE_SKIP.some((s) => rel === s || rel.startsWith(`${s}${path.sep}`));
+}
+
+// A rule with `paths:` globs in its frontmatter is glob-activated by the host on a
+// matching edit — load-bearing regardless of whether it is named anywhere.
+function hasPathGlobs(absPath) {
+  try {
+    const head = fs.readFileSync(absPath, 'utf8').slice(0, 1200);
+    const fm = head.match(/^---\n([\s\S]*?)\n---/);
+    return Boolean(fm && /\n?paths:\s*\n\s*-\s+/.test(fm[1]));
+  } catch { return false; }
+}
+
+function collectRuleFiles(rulesDir) {
+  const out = [];
+  const walk = (dir) => {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) walk(full);
+      else if (ent.name.endsWith('.md')) out.push(path.relative(rulesDir, full).replace(/\.md$/, ''));
+    }
+  };
+  if (fs.existsSync(rulesDir)) walk(rulesDir);
+  return out;
+}
+
+function collectSurfaceText(root, ruleFileAbsSet) {
+  const texts = [];
+  const add = (full) => {
+    if (ruleFileAbsSet.has(full)) return;
+    if (!TEXT_EXT.has(path.extname(full))) return;
+    try { texts.push(fs.readFileSync(full, 'utf8')); } catch { /* unreadable — skip */ }
+  };
+  const walk = (dir) => {
+    let ents;
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of ents) {
+      const full = path.join(dir, ent.name);
+      if (isSkipped(full, root)) continue;
+      if (ent.isDirectory()) walk(full);
+      else add(full);
+    }
+  };
+  for (const d of SURFACE_DIRS) walk(path.join(root, d));
+  for (const f of SURFACE_FILES) add(path.join(root, f));
+  return texts.join('\n');
+}
+
+/**
+ * Audit which rules are referenced in the active surface.
+ * @returns {{ total: number, referenced: Array<{rule:string,refs:number}>, orphans: string[], issues: object[] }}
+ */
+export function auditRules({ rootDir, silent = false } = {}) {
+  const root = rootDir ?? REPO_ROOT;
+  const rulesDir = path.join(root, 'rules');
+  const ruleFiles = collectRuleFiles(rulesDir);
+  const ruleAbsSet = new Set(ruleFiles.map((r) => path.join(rulesDir, `${r}.md`)));
+  const surface = collectSurfaceText(root, ruleAbsSet);
+
+  const referenced = [];
+  const globScoped = [];
+  const orphans = [];
+  for (const rule of ruleFiles) {
+    // Count `rules/<rule>` occurrences (with or without the .md suffix) so a
+    // citation in any surface file marks the rule load-bearing.
+    const token = `rules/${rule}`;
+    const refs = surface.split(token).length - 1;
+    if (refs > 0) referenced.push({ rule, refs });
+    else if (hasPathGlobs(path.join(rulesDir, `${rule}.md`))) globScoped.push(rule);
+    else orphans.push(rule);
+  }
+  referenced.sort((a, b) => b.refs - a.refs);
+
+  const issues = [];
+  if (orphans.length > 0) issues.push({ kind: 'orphan-rules', items: orphans });
+
+  if (!silent) {
+    const line = (s) => process.stdout.write(`${s}\n`);
+    line(`Rule reference audit (${ruleFiles.length} rules: ${referenced.length} referenced, ${globScoped.length} glob-scoped, ${orphans.length} orphan):`);
+    if (orphans.length === 0) {
+      line('  ✓ Every rule is referenced or glob-scoped');
+    } else {
+      line(`  ⚠ Rules neither referenced nor glob-scoped (${orphans.length}) — pruning candidates:`);
+      for (const r of orphans) line(`      - rules/${r}.md`);
+    }
+  }
+
+  return { total: ruleFiles.length, referenced, globScoped, orphans, issues };
+}

package/lib/audit-skills.mjs

@@ -4,6 +4,12 @@
  * Reports: (a) skills with no agent owner, (b) agents with no skill bindings,
  * (c) skill paths declared in registry but missing on disk.
  * Called by 'construct audit skills' and incorporated into 'construct doctor'.
+ *
+ * A `roles/<base>[.<flavor>]` skill is owned when `<base>` is a specialist OR a role
+ * named in any profile (profiles/*.json) — a role skill loads when its specialist or
+ * profile role runs, even without a direct registry `skills:` binding. Counting only
+ * registry bindings over-reported orphans (it missed profile roles like `operator`
+ * from operations.json and conditional specialist flavors); see bead construct-ksfa.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -34,6 +40,34 @@ function collectSkillFiles(skillsDir) {
   return results;
 }
 
+// Collect every role name a profile declares — top-level `roles` and nested
+// `departments[].roles` — so a role skill counts as owned when a profile uses its
+// base even if no specialist declares the skill path directly.
+function collectProfileRoles(root) {
+  const dir = path.join(root, 'profiles');
+  const roles = new Set();
+  const scan = (node) => {
+    if (Array.isArray(node)) { node.forEach(scan); return; }
+    if (node && typeof node === 'object') {
+      if (Array.isArray(node.roles)) for (const r of node.roles) if (typeof r === 'string') roles.add(r);
+      for (const v of Object.values(node)) scan(v);
+    }
+  };
+  try {
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.json')) continue;
+      try { scan(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))); } catch { /* skip malformed */ }
+    }
+  } catch { /* no profiles dir */ }
+  return roles;
+}
+
+// The base of a role skill: roles/architect.data → architect; roles/qa → qa.
+function roleBase(skill) {
+  const m = skill.match(/^roles\/([^.]+)(?:\..*)?$/);
+  return m ? m[1] : null;
+}
+
 export function auditSkills({ rootDir, silent = false } = {}) {
   const root = rootDir ?? findConstructRoot();
   const registryPath = path.join(root, 'specialists', 'registry.json');
@@ -59,7 +93,15 @@ export function auditSkills({ rootDir, silent = false } = {}) {
     }
   }
 
-  const orphanSkills = [...allSkillFiles].filter((s) => !declaredSkills.has(s));
+  // Owning role bases = specialist names (registry) ∪ profile role names. A role
+  // skill is owned when its base is in this set, even without a direct binding.
+  const ownerBases = new Set([
+    ...(registry.specialists ?? []).map((a) => a.name.replace(/^cx-/, '')),
+    ...collectProfileRoles(root),
+  ]);
+  const isOwned = (s) => declaredSkills.has(s) || (ownerBases.has(roleBase(s)));
+
+  const orphanSkills = [...allSkillFiles].filter((s) => !isOwned(s));
 
   const issues = [];
   if (agentsWithNoSkills.length > 0) issues.push({ kind: 'agents-no-skills', items: agentsWithNoSkills });

package/lib/beads-client.mjs

@@ -252,6 +252,15 @@ export async function runBd(args, options = {}) {
  * Used as fallback when optimistic locking fails.
  */
 async function runWithLegacyLock(args, opts, cwd, commandDesc) {
+  // Telemetry: every legacy-fallback firing is recorded so the lock+queue removal
+  // decision rests on observed data — if this never fires over a representative
+  // window, the whole exclusive-lock path is removable; if it fires, the entries
+  // name the bd errors that actually need handling (bead construct-nhn5).
+  try {
+    const { logBeadsFallback } = await import('./telemetry/beads-fallback.mjs');
+    logBeadsFallback({ command: commandDesc || args[0] || 'unknown' });
+  } catch { /* telemetry is best-effort */ }
+
   // Clean up any stale locks before trying
   cleanupStaleLock({ cwd });
   cleanupStaleQueue({ cwd });

package/lib/beads-optimistic.mjs

@@ -1,14 +1,14 @@
 /**
- * lib/beads-optimistic.mjs — Optimistic locking and concurrent read support for beads.
+ * lib/beads-optimistic.mjs — concurrent reads + retry-on-conflict writes for beads.
  *
- * Addresses the beads lock contention issue by:
- * 1. Allowing concurrent reads (no lock required)
- * 2. Using optimistic locking for writes (version-based conflict detection)
- * 3. Automatic retry with exponential backoff on conflict
- * 4. Read-replicas for team mode (when available)
- *
- * Replaces the exclusive lock model with a more scalable approach
- * while maintaining consistency guarantees.
+ * Dolt commits are atomic, so it is the serializer: a write is executed and, on a
+ * transient conflict, retried with exponential backoff. There is no separate
+ * read-then-compare version check — that spanned two `bd` processes (a `bd show`
+ * to read the commit hash, then a `bd update`) and guarded nothing, since `bd
+ * update` accepts no expected version, so the window between the read and the
+ * write left the "optimistic lock" unable to actually detect a conflicting commit
+ * (bead construct-iufy). Reads run lock-free; `getBeadVersion` remains as an
+ * advisory reader, not a write-path primitive.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -34,8 +34,9 @@ const DEFAULT_RETRY_OPTIONS = {
 // ---------------------------------------------------------------------------
 
 /**
- * Read the current version of a bead from the database.
- * In Dolt, this uses the commit hash as a logical version.
+ * Read the current version of a bead from the database (the Dolt commit hash).
+ * Advisory only — exposed for callers that want to observe a bead's version; the
+ * write path does not gate on it (see file header).
  */
 export async function getBeadVersion(beadId, cwd = process.cwd()) {
   try {
@@ -56,75 +57,37 @@ export async function getBeadVersion(beadId, cwd = process.cwd()) {
 }
 
 /**
- * Execute a write operation with optimistic locking.
- * 
+ * Execute a bead write, retrying on a transient conflict. Dolt's atomic commit is
+ * the serializer; this does not pre-read or compare a version (see file header).
+ *
  * @param {Object} options
- * @param {string} options.beadId - The bead being modified
  * @param {Function} options.execute - Async function that performs the write
- * @param {string} options.expectedVersion - Version we expect the bead to have
  * @param {Object} options.retry - Retry configuration
  * @returns {Promise<{success: boolean, result: any, attempts: number}>}
  */
 export async function optimisticWrite({
-  beadId,
   execute,
-  expectedVersion,
   retry = DEFAULT_RETRY_OPTIONS,
-  cwd = process.cwd(),
 } = {}) {
   let attempts = 0;
   let delay = retry.baseDelayMs;
-  
+
   while (attempts < retry.maxRetries) {
     attempts++;
-    
-    // Verify version hasn't changed (optimistic check)
-    const currentVersion = await getBeadVersion(beadId, cwd);
-    
-    if (expectedVersion && currentVersion !== expectedVersion) {
-      // Conflict detected - another writer modified the bead
-      if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: `Optimistic lock conflict after ${attempts} attempts. Bead ${beadId} was modified by another process.`,
-          attempts,
-          currentVersion,
-          expectedVersion,
-        };
-      }
-      
-      // Wait with exponential backoff and jitter
-      const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
-      delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
-      continue;
-    }
-    
     try {
-      // Execute the write operation
       const result = await execute();
       return { success: true, result, attempts };
     } catch (error) {
       if (attempts >= retry.maxRetries) {
-        return {
-          success: false,
-          error: error.message,
-          attempts,
-        };
+        return { success: false, error: error.message, attempts };
       }
-      
-      // Retry on transient errors
       const jitter = Math.random() * 50;
-      await new Promise(r => setTimeout(r, delay + jitter));
+      await new Promise((r) => setTimeout(r, delay + jitter));
       delay = Math.min(delay * retry.backoffMultiplier, retry.maxDelayMs);
     }
   }
-  
-  return {
-    success: false,
-    error: `Max retries (${retry.maxRetries}) exceeded`,
-    attempts,
-  };
+
+  return { success: false, error: `Max retries (${retry.maxRetries}) exceeded`, attempts };
 }
 
 // ---------------------------------------------------------------------------
@@ -187,21 +150,10 @@ export async function updateBeadOptimistic(
   options = {}
 ) {
   const { actor = 'construct', cwd = process.cwd(), notes } = options;
-  
-  // Get current version before attempting update
-  const currentVersion = await getBeadVersion(beadId, cwd);
-  
-  if (!currentVersion) {
-    return {
-      success: false,
-      error: `Bead ${beadId} not found`,
-    };
-  }
-  
+
+  // A `bd update` on a missing bead exits non-zero and surfaces as a failed
+  // result, so no separate existence pre-check is needed.
   return optimisticWrite({
-    beadId,
-    expectedVersion: currentVersion,
-    cwd,
     execute: async () => {
       const args = ['update', beadId];
       

package/lib/bridges/copilot-proxy.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * lib/bridges/copilot-proxy.mjs — Minimal GitHub Copilot to OpenAI-compatible bridge.
+ *
+ * Translates standard OpenAI /v1/chat/completions requests to the Copilot API
+ * using the user's active `gh` CLI session.
+ */
+import http from 'node:http';
+import { execSync } from 'node:child_process';
+
+const PORT = parseInt(process.argv.find(a => a.startsWith('--port='))?.split('=')[1] || '5174', 10);
+
+let cachedSession = null;
+
+async function getCopilotToken() {
+  if (cachedSession && cachedSession.expires_at > (Date.now() / 1000) + 60) {
+    return cachedSession.token;
+  }
+
+  try {
+    const ghToken = execSync('gh auth token', { encoding: 'utf8' }).trim();
+    const res = await fetch('https://api.github.com/copilot_internal/v2/token', {
+      headers: {
+        'Authorization': `Bearer ${ghToken}`,
+        'Accept': 'application/json',
+      }
+    });
+
+    if (!res.ok) throw new Error(`Failed to get session token: ${res.statusText}`);
+    
+    cachedSession = await res.json();
+    return cachedSession.token;
+  } catch (err) {
+    console.error('Error fetching Copilot token:', err.message);
+    return null;
+  }
+}
+
+const server = http.createServer(async (req, res) => {
+  // CORS
+  res.setHeader('Access-Control-Allow-Origin', '*');
+  res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+  res.setHeader('Access-Control-Allow-Headers', '*');
+
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  if (req.url === '/v1/chat/completions' && req.method === 'POST') {
+    const token = await getCopilotToken();
+    if (!token) {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Failed to authenticate with GitHub Copilot via gh CLI.' }));
+      return;
+    }
+
+    let body = '';
+    req.on('data', chunk => { body += chunk; });
+    req.on('end', async () => {
+      try {
+        const payload = JSON.parse(body);
+        
+        // Map common model names to Copilot equivalents if needed
+        // For now, we pass them through or default to gpt-4o
+        const model = payload.model?.includes('gpt-4o') ? 'gpt-4o' : 
+                      payload.model?.includes('claude-3.5-sonnet') ? 'claude-3.5-sonnet' : 
+                      'gpt-4o';
+
+        const copilotRes = await fetch('https://api.githubcopilot.com/chat/completions', {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${token}`,
+            'Content-Type': 'application/json',
+            'Accept': 'application/json',
+            'X-Github-Api-Version': '2023-07-07',
+            'Editor-Version': 'vscode/1.90.0', // Spoof VS Code for compatibility
+          },
+          body: JSON.stringify({
+            ...payload,
+            model
+          })
+        });
+
+        res.writeHead(copilotRes.status, {
+          'Content-Type': copilotRes.headers.get('Content-Type'),
+        });
+
+        if (payload.stream) {
+           const reader = copilotRes.body.getReader();
+           while (true) {
+             const { done, value } = await reader.read();
+             if (done) break;
+             res.write(value);
+           }
+           res.end();
+        } else {
+          const data = await copilotRes.text();
+          res.end(data);
+        }
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+    });
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('Not Found');
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`Copilot Bridge listening on http://127.0.0.1:${PORT}`);
+});

package/lib/cli-commands.mjs

@@ -61,13 +61,14 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Machine setup (scoped per ADR-0029): --scope=project|user|both, default project',
-    usage: 'construct install [--scope=project|user|both] [--yes] [--no-docker] [--no-launch-agent] [--reconfigure]',
+    usage: 'construct install [--scope=project|user|both] [--yes] [--no-docker] [--no-launch-agent] [--reconfigure] [--with-docling]',
     options: [
       { flag: '--scope=<s>',      desc: 'project (default, no-op + guidance) | user (writes ~/.construct/, MCP, ~/.claude/* via consent) | both' },
       { flag: '--yes',            desc: 'Apply defaults without prompts (only meaningful with --scope=user|both)' },
       { flag: '--no-docker',      desc: 'Skip Docker-based service setup (local Postgres)' },
       { flag: '--no-launch-agent', desc: 'Skip background macOS LaunchAgent registration' },
       { flag: '--reconfigure',    desc: 'Re-prompt for service consent, ignoring cached answers' },
+      { flag: '--with-docling',   desc: 'Eagerly provision the docling document-extraction venv now (heavy, ~10 min; else lazy on first ingest)' },
     ],
   },
   {
@@ -936,6 +937,9 @@ export const CLI_COMMANDS = [
   { name: 'lint:contracts',    category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist contracts', usage: 'construct lint:contracts' },
   { name: 'lint:research',     category: 'Internal', core: false, internal: true, description: 'Internal lint: research artifacts', usage: 'construct lint:research' },
   { name: 'lint:templates',    category: 'Internal', core: false, internal: true, description: 'Internal lint: shipped templates', usage: 'construct lint:templates' },
+  { name: 'lint:prompts',      category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist prompt frontmatter + sections', usage: 'construct lint:prompts' },
+  { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
+  { name: 'registry:status',   category: 'Internal', core: false, internal: true, description: 'Dev: capability-matrix registry inspector', usage: 'construct registry:status' },
   { name: 'evaluator:rubrics', category: 'Internal', core: false, internal: true, description: 'Internal: list registered evaluator rubrics', usage: 'construct evaluator:rubrics' },
   { name: 'activation:status', category: 'Internal', core: false, internal: true, description: 'Internal: agent activation telemetry', usage: 'construct activation:status' },
   { name: 'prune',             category: 'Internal', core: false, internal: true, description: 'Internal: prune ephemeral storage entries', usage: 'construct prune' },

package/lib/comment-lint.mjs

@@ -86,7 +86,7 @@ function isConstructSelfRepo(rootDir) {
 
 function requiresHeader(rel) {
   const ext = path.extname(rel);
-  if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
+  if (['.yaml', '.yml', '.json', '.jsonl', '.toml', '.txt'].includes(ext)) return { required: false, type: null };
   const jsMatch = JS_HEADER_GLOBS.some(r => r.test(rel));
   const mdMatch = MD_HEADER_GLOBS.some(r => r.test(rel));
   // Exclude static assets under lib/server/static from requiring headers

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/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,