@geraldmaron/construct 1.0.7 → 1.0.9

package/lib/document-extract.mjs

@@ -5,10 +5,18 @@
  * Office zip containers via unzip, and PDFs via pdftotext or macOS-native fallbacks.
  * Also provides extractDocumentMetadata() for structured metadata (title, authors,
  * dates, links) from source document frontmatter and content.
+ *
+ * All paths now return { text, structured, droppedInfo, method, ... } where
+ * droppedInfo is an array of { kind, count, reason, recoverable } objects
+ * describing information that was silently dropped during extraction.
+ * Audio/video files throw a typed { code: 'ASR_REQUIRED' } error.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { makeDropInfo } from './extractors/shared/drop-info.mjs';
+import { extractTranscript } from './extractors/transcript.mjs';
+import { extractCalendar } from './extractors/calendar.mjs';
 
 // 50 MB hard cap mirrors lib/embed/inbox.mjs and lib/observation-store.mjs.
 // Anything larger is intentionally not extracted to keep the daemon path
@@ -20,15 +28,27 @@ export const UTF8_TEXT_EXTS = new Set([
   '.js', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.sh', '.bash',
   '.html', '.css', '.csv', '.tsv', '.xml', '.env', '.env.example', '.conf', '.ini', '.tf', '.hcl',
   '.sql', '.log',
-  '.vtt', '.srt', '.lrc', '.transcript',
 ]);
 
+// Transcript formats — routed to lib/extractors/transcript.mjs for structured extraction.
+export const TRANSCRIPT_EXTS = new Set(['.vtt', '.srt', '.lrc', '.transcript']);
+
+// Calendar formats — routed to lib/extractors/calendar.mjs.
+export const CALENDAR_EXTS = new Set(['.ics']);
+
+// Audio/video formats — inbox-compatible but require ASR; extractDocumentText
+// throws { code: 'ASR_REQUIRED' } so callers can route to needs-asr/ queue.
+export const AUDIO_VIDEO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.mp4', '.mov', '.avi', '.mkv', '.flac', '.ogg', '.webm', '.m4v']);
+
 export const ZIP_DOCUMENT_EXTS = new Set(['.docx', '.xlsx', '.pptx', '.odt', '.ods']);
 export const RICH_TEXT_EXTS = new Set(['.doc', '.rtf']);
 export const MDLS_DOCUMENT_EXTS = new Set(['.xls', '.ppt', '.pages', '.numbers', '.key']);
-export const EMAIL_DOCUMENT_EXTS = new Set(['.eml']);
+export const EMAIL_DOCUMENT_EXTS = new Set(['.eml', '.msg']);
 export const EXTRACTABLE_DOCUMENT_EXTS = new Set([
   ...UTF8_TEXT_EXTS,
+  ...TRANSCRIPT_EXTS,
+  ...CALENDAR_EXTS,
+  ...AUDIO_VIDEO_EXTS,
   ...ZIP_DOCUMENT_EXTS,
   ...RICH_TEXT_EXTS,
   ...MDLS_DOCUMENT_EXTS,
@@ -36,6 +56,10 @@ export const EXTRACTABLE_DOCUMENT_EXTS = new Set([
   '.pdf',
 ]);
 
+// Minimum extracted characters per page that distinguishes text-bearing PDFs
+// from scanned images. Below this threshold droppedInfo is emitted.
+const PDF_MIN_TEXT_THRESHOLD = 50;
+
 function normalizeText(value) {
   return String(value)
     .replace(/\r\n/g, '\n')
@@ -88,7 +112,7 @@ function extractUtf8(filePath, extension) {
   const text = extension === '.html' || extension === '.xml'
     ? stripMarkup(raw)
     : normalizeText(raw);
-  return { text, method: 'utf8' };
+  return { text, method: 'utf8', droppedInfo: [], structured: null };
 }
 
 function zipEntries(filePath) {
@@ -102,13 +126,82 @@ function unzipEntry(filePath, entryPath) {
 function extractZipDocument(filePath, extension) {
   const entries = zipEntries(filePath);
   let targets = [];
+  const droppedInfo = [];
 
   if (extension === '.docx') {
     targets = entries.filter((entry) => entry === 'word/document.xml' || entry.startsWith('word/header') || entry.startsWith('word/footer'));
+
+    // Count embedded images (word/media/ folder entries)
+    const imageCount = entries.filter((e) => e.startsWith('word/media/')).length;
+    if (imageCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'inline-image', count: imageCount, reason: 'Embedded images not extracted from DOCX', recoverable: true }));
+    }
+
+    // Count tables in the main document XML
+    try {
+      const docXml = unzipEntry(filePath, 'word/document.xml');
+      const tableCount = (docXml.match(/<w:tbl[\s>]/g) || []).length;
+      if (tableCount > 0) {
+        droppedInfo.push(makeDropInfo({ kind: 'table', count: tableCount, reason: 'Table structure flattened; cell boundaries and column headers not preserved', recoverable: true }));
+      }
+    } catch { /* ignore — main extraction still proceeds */ }
+
+    // Count comments
+    if (entries.includes('word/comments.xml')) {
+      try {
+        const commentsXml = unzipEntry(filePath, 'word/comments.xml');
+        const commentCount = (commentsXml.match(/<w:comment\s/g) || []).length;
+        if (commentCount > 0) {
+          droppedInfo.push(makeDropInfo({ kind: 'comment', count: commentCount, reason: 'Document review comments not included in extracted text', recoverable: true }));
+        }
+      } catch { /* ignore */ }
+    }
   } else if (extension === '.xlsx') {
     targets = entries.filter((entry) => entry === 'xl/sharedStrings.xml' || /^xl\/worksheets\/sheet\d+\.xml$/.test(entry));
+
+    // Count formula cells across all worksheets
+    let formulaCount = 0;
+    for (const sheetEntry of entries.filter((e) => /^xl\/worksheets\/sheet\d+\.xml$/.test(e))) {
+      try {
+        const sheetXml = unzipEntry(filePath, sheetEntry);
+        formulaCount += (sheetXml.match(/<f\b/g) || []).length;
+      } catch { /* ignore */ }
+    }
+    if (formulaCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'formula', count: formulaCount, reason: 'Spreadsheet formulas not evaluated; only cell string values extracted', recoverable: true }));
+    }
+
+    // Count embedded images
+    const imageCount = entries.filter((e) => e.startsWith('xl/media/')).length;
+    if (imageCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'inline-image', count: imageCount, reason: 'Embedded images not extracted from XLSX', recoverable: true }));
+    }
   } else if (extension === '.pptx') {
     targets = entries.filter((entry) => /^ppt\/slides\/slide\d+\.xml$/.test(entry));
+
+    // Count speaker notes slides
+    const notesCount = entries.filter((e) => /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(e)).length;
+    if (notesCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'speaker-notes', count: notesCount, reason: 'Speaker notes slides not included in extracted text', recoverable: true }));
+    }
+
+    // Count slides with animation sequences
+    let animationCount = 0;
+    for (const slideEntry of targets) {
+      try {
+        const slideXml = unzipEntry(filePath, slideEntry);
+        if (/<p:timing\b/.test(slideXml)) animationCount++;
+      } catch { /* ignore */ }
+    }
+    if (animationCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'animation', count: animationCount, reason: 'Slide animation timing sequences not preserved in extracted text', recoverable: false }));
+    }
+
+    // Count embedded images
+    const imageCount = entries.filter((e) => e.startsWith('ppt/media/')).length;
+    if (imageCount > 0) {
+      droppedInfo.push(makeDropInfo({ kind: 'inline-image', count: imageCount, reason: 'Embedded images not extracted from PPTX', recoverable: true }));
+    }
   } else if (extension === '.odt' || extension === '.ods') {
     targets = entries.filter((entry) => entry === 'content.xml');
   }
@@ -116,7 +209,7 @@ function extractZipDocument(filePath, extension) {
   if (targets.length === 0) throw new Error(`No readable document entries found for ${extension}`);
 
   const text = normalizeText(targets.map((entry) => stripMarkup(unzipEntry(filePath, entry))).join('\n\n'));
-  return { text, method: 'zip-xml' };
+  return { text, method: 'zip-xml', droppedInfo, structured: null };
 }
 
 function extractRichText(filePath) {
@@ -126,6 +219,8 @@ function extractRichText(filePath) {
   return {
     text: normalizeText(run('textutil', ['-convert', 'txt', '-stdout', filePath])),
     method: 'textutil',
+    droppedInfo: [],
+    structured: null,
   };
 }
 
@@ -133,6 +228,8 @@ function extractPdfWithPdftotext(filePath) {
   return {
     text: normalizeText(run('pdftotext', ['-layout', '-nopgbrk', filePath, '-'])),
     method: 'pdftotext',
+    droppedInfo: [],
+    structured: null,
   };
 }
 
@@ -152,12 +249,14 @@ print(document.string ?? "")
   return {
     text: normalizeText(run('swift', ['-e', script, filePath])),
     method: 'swift-pdfkit',
+    droppedInfo: [],
+    structured: null,
   };
 }
 
 function extractPdfWithMdls(filePath) {
   const text = extractWithMdls(filePath);
-  return { text, method: 'mdls' };
+  return { text, method: 'mdls', droppedInfo: [], structured: null };
 }
 
 function extractWithMdls(filePath) {
@@ -167,16 +266,40 @@ function extractWithMdls(filePath) {
 }
 
 function extractPdf(filePath) {
-  if (commandExists('pdftotext')) return extractPdfWithPdftotext(filePath);
-  if (process.platform === 'darwin' && commandExists('swift')) {
+  let extracted;
+  if (commandExists('pdftotext')) {
+    extracted = extractPdfWithPdftotext(filePath);
+  } else if (process.platform === 'darwin' && commandExists('swift')) {
     try {
-      return extractPdfWithSwift(filePath);
+      extracted = extractPdfWithSwift(filePath);
     } catch {
-      return extractPdfWithMdls(filePath);
+      extracted = extractPdfWithMdls(filePath);
     }
+  } else if (process.platform === 'darwin' && commandExists('mdls')) {
+    extracted = extractPdfWithMdls(filePath);
+  } else {
+    throw new Error('No PDF extraction backend available');
+  }
+
+  // Scanned-PDF heuristic: if extracted text is very short relative to file size,
+  // the PDF probably contains only images and needs OCR to be useful.
+  const stat = statSync(filePath);
+  const pages = Math.max(1, Math.ceil(stat.size / 50_000));
+  const threshold = PDF_MIN_TEXT_THRESHOLD * pages;
+  if (extracted.text.length < threshold) {
+    const ocrHint = process.env.CONSTRUCT_PDF_OCR_HINT || 'none';
+    const hintMsg = ocrHint !== 'none'
+      ? `OCR backend hint: ${ocrHint}. See docs/intake/scanned-pdfs.md.`
+      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/intake/scanned-pdfs.md.';
+    extracted.droppedInfo.push(makeDropInfo({
+      kind: 'scanned-pdf',
+      count: pages,
+      reason: `Extracted text (${extracted.text.length} chars) is below minimum threshold for ${pages} page(s); document may be a scanned image. ${hintMsg}`,
+      recoverable: true,
+    }));
   }
-  if (process.platform === 'darwin' && commandExists('mdls')) return extractPdfWithMdls(filePath);
-  throw new Error('No PDF extraction backend available');
+
+  return extracted;
 }
 
 export function isExtractableDocumentPath(filePath) {
@@ -263,16 +386,16 @@ function decodeTransferEncoded(text, encoding) {
   return text;
 }
 
-// Walk a parsed MIME entity, returning the first text/plain body it finds
-// and a flat list of attachment filenames encountered along the way. The
-// walker stops at depth 8 so a hand-crafted pathological message cannot
-// exhaust the stack.
+// Walk a parsed MIME entity, returning the first text/plain body it finds,
+// a flat list of attachment filenames, and counts of dropped HTML parts and
+// inline images. The walker stops at depth 8 so a hand-crafted pathological
+// message cannot exhaust the stack.
 function walkMimeForPlainText(rawEntity, depth = 0) {
-  if (depth > 8) return { text: '', attachments: [] };
+  if (depth > 8) return { text: '', attachments: [], droppedHtmlParts: 0, droppedImages: 0 };
   const sepIdx = rawEntity.indexOf('\n\n') !== -1
     ? rawEntity.indexOf('\n\n')
     : rawEntity.indexOf('\r\n\r\n');
-  if (sepIdx === -1) return { text: '', attachments: [] };
+  if (sepIdx === -1) return { text: '', attachments: [], droppedHtmlParts: 0, droppedImages: 0 };
   const headerBlock = rawEntity.slice(0, sepIdx);
   const body = rawEntity.slice(sepIdx).replace(/^\r?\n\r?\n/, '');
   const headers = parseRfc5322Headers(headerBlock);
@@ -283,28 +406,44 @@ function walkMimeForPlainText(rawEntity, depth = 0) {
   if (type.startsWith('multipart/')) {
     const attachments = [];
     let firstPlain = '';
+    let droppedHtmlParts = 0;
+    let droppedImages = 0;
     for (const seg of splitMultipart(body, params.boundary)) {
       const child = walkMimeForPlainText(seg, depth + 1);
       attachments.push(...child.attachments);
+      droppedHtmlParts += child.droppedHtmlParts;
+      droppedImages += child.droppedImages;
       if (!firstPlain && child.text) firstPlain = child.text;
     }
-    return { text: firstPlain, attachments };
+    return { text: firstPlain, attachments, droppedHtmlParts, droppedImages };
   }
 
   if (disposition.type === 'attachment' && filename) {
-    return { text: '', attachments: [filename] };
+    return { text: '', attachments: [filename], droppedHtmlParts: 0, droppedImages: 0 };
   }
 
   if (type === '' || type === 'text/plain') {
     return {
       text: decodeTransferEncoded(body, headers['content-transfer-encoding']),
       attachments: [],
+      droppedHtmlParts: 0,
+      droppedImages: 0,
     };
   }
 
+  // HTML body part that would be useful if plain/text was absent
+  if (type === 'text/html') {
+    return { text: '', attachments: [], droppedHtmlParts: 1, droppedImages: 0 };
+  }
+
+  // Inline images (image/* with no attachment disposition)
+  if (type.startsWith('image/') && disposition.type !== 'attachment') {
+    return { text: '', attachments: [], droppedHtmlParts: 0, droppedImages: 1 };
+  }
+
   // Non-plain leaves with an explicit filename are treated as attachments.
-  if (filename) return { text: '', attachments: [filename] };
-  return { text: '', attachments: [] };
+  if (filename) return { text: '', attachments: [filename], droppedHtmlParts: 0, droppedImages: 0 };
+  return { text: '', attachments: [], droppedHtmlParts: 0, droppedImages: 0 };
 }
 
 /**
@@ -346,14 +485,19 @@ export function extractEmlMessage(filePath) {
 
   let bodyText = '';
   const attachments = [];
+  let droppedHtmlParts = 0;
+  let droppedImages = 0;
   if (type.startsWith('multipart/')) {
     for (const seg of splitMultipart(body, params.boundary)) {
       const child = walkMimeForPlainText(seg);
       attachments.push(...child.attachments);
+      droppedHtmlParts += child.droppedHtmlParts;
+      droppedImages += child.droppedImages;
       if (!bodyText && child.text) bodyText = child.text;
     }
   } else {
     bodyText = decodeTransferEncoded(body, headers['content-transfer-encoding']);
+    if (type === 'text/html') droppedHtmlParts++;
   }
 
   const subject = headers.subject || '';
@@ -367,16 +511,37 @@ export function extractEmlMessage(filePath) {
     text,
     headers: { subject, from, date, to },
     attachments,
+    droppedHtmlParts,
+    droppedImages,
+    structured: {
+      subject,
+      from,
+      date,
+      to,
+      attachments: attachments.map((name) => ({ filename: name })),
+    },
   };
 }
 
 function extractEml(filePath) {
   const message = extractEmlMessage(filePath);
+  const droppedInfo = [];
+  if ((message.droppedHtmlParts || 0) > 0) {
+    droppedInfo.push(makeDropInfo({ kind: 'html-part', count: message.droppedHtmlParts, reason: 'HTML email body parts not included (plain-text preferred)', recoverable: true }));
+  }
+  if ((message.droppedImages || 0) > 0) {
+    droppedInfo.push(makeDropInfo({ kind: 'inline-image', count: message.droppedImages, reason: 'Inline images from multipart/related not extracted', recoverable: true }));
+  }
+  if ((message.attachments || []).length > 0) {
+    droppedInfo.push(makeDropInfo({ kind: 'attachment', count: message.attachments.length, reason: `Attachment bodies not extracted (filenames preserved): ${message.attachments.join(', ')}`, recoverable: true }));
+  }
   return {
     text: message.text,
     method: message.skipped ? 'eml-skipped' : 'eml',
     skipped: message.skipped || null,
     attachments: message.attachments,
+    droppedInfo,
+    structured: message.structured || null,
   };
 }
 
@@ -467,14 +632,40 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
   }
 
+  // Audio and video files cannot be text-extracted without ASR.
+  // Throw a typed error so callers can route to .cx/intake/needs-asr/.
+  if (AUDIO_VIDEO_EXTS.has(extension)) {
+    const err = new Error(
+      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/intake/audio-video.md.`,
+    );
+    err.code = 'ASR_REQUIRED';
+    err.extension = extension;
+    throw err;
+  }
+
   let extracted;
-  if (UTF8_TEXT_EXTS.has(extension)) extracted = extractUtf8(resolvedPath, extension);
-  else if (ZIP_DOCUMENT_EXTS.has(extension)) extracted = extractZipDocument(resolvedPath, extension);
-  else if (RICH_TEXT_EXTS.has(extension)) extracted = extractRichText(resolvedPath);
-  else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) extracted = { text: extractWithMdls(resolvedPath), method: 'mdls' };
-  else if (EMAIL_DOCUMENT_EXTS.has(extension)) extracted = extractEml(resolvedPath);
-  else if (extension === '.pdf') extracted = extractPdf(resolvedPath);
-  else throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+  if (UTF8_TEXT_EXTS.has(extension)) {
+    extracted = extractUtf8(resolvedPath, extension);
+  } else if (TRANSCRIPT_EXTS.has(extension)) {
+    // Transcript formats return the full { text, structured, droppedInfo } envelope.
+    const envelope = extractTranscript(resolvedPath);
+    extracted = { text: envelope.text, method: 'transcript', droppedInfo: envelope.droppedInfo, structured: envelope.structured };
+  } else if (CALENDAR_EXTS.has(extension)) {
+    const envelope = extractCalendar(resolvedPath);
+    extracted = { text: envelope.text, method: 'ics', droppedInfo: envelope.droppedInfo, structured: envelope.structured };
+  } else if (ZIP_DOCUMENT_EXTS.has(extension)) {
+    extracted = extractZipDocument(resolvedPath, extension);
+  } else if (RICH_TEXT_EXTS.has(extension)) {
+    extracted = extractRichText(resolvedPath);
+  } else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) {
+    extracted = { text: extractWithMdls(resolvedPath), method: 'mdls', droppedInfo: [], structured: null };
+  } else if (EMAIL_DOCUMENT_EXTS.has(extension)) {
+    extracted = extractEml(resolvedPath);
+  } else if (extension === '.pdf') {
+    extracted = extractPdf(resolvedPath);
+  } else {
+    throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+  }
 
   const text = extracted.text;
   const limit = Number.isFinite(Number(maxChars)) && Number(maxChars) > 0
@@ -489,6 +680,8 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     text: truncated ? `${text.slice(0, limit)}\n` : text,
     truncated,
     characters: text.length,
+    droppedInfo: extracted.droppedInfo ?? [],
+    structured: extracted.structured ?? null,
   };
   // Surface eml-specific metadata so callers (intake, ingest) can route
   // attachment filenames and oversize-skip markers without re-parsing.

package/lib/document-ingest.mjs

@@ -170,6 +170,8 @@ export async function ingestDocuments(inputPaths, {
       extractionMethod: extracted.extractionMethod,
       truncated: extracted.truncated,
       characters: extracted.characters,
+      droppedInfo: extracted.droppedInfo ?? [],
+      structured: extracted.structured ?? null,
       metadata: { title, authors: metadata?.authors || [], dates: metadata?.dates || {} },
     });
   }

package/lib/embed/inbox.mjs

@@ -21,9 +21,10 @@
  *   // result: { processed: [...], skipped: number, errors: [...] }
  */
 
-import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { isExtractableDocumentPath } from '../document-extract.mjs';
+import { homedir } from 'node:os';
+import { isExtractableDocumentPath, AUDIO_VIDEO_EXTS } from '../document-extract.mjs';
 import { ingestDocuments } from '../document-ingest.mjs';
 import { addObservation } from '../observation-store.mjs';
 import { inferKnowledgeTarget, knowledgeDirForCategory } from '../knowledge/layout.mjs';
@@ -39,6 +40,37 @@ const DOCS_INTAKE_SUBDIR = 'docs/intake';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
 const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+// ─── Extraction-warning helpers ───────────────────────────────────────────────
+
+function extractionWarningsLog() {
+  return join(homedir(), '.cx', 'intake', 'extraction-warnings.jsonl');
+}
+
+function needsAsrDir() {
+  return join(homedir(), '.cx', 'intake', 'needs-asr');
+}
+
+function writeExtractionWarning({ sourcePath, droppedInfo }) {
+  if (!droppedInfo?.length) return;
+  const logPath = extractionWarningsLog();
+  try {
+    mkdirSync(join(homedir(), '.cx', 'intake'), { recursive: true });
+    const line = JSON.stringify({ ts: new Date().toISOString(), sourcePath, droppedInfo }) + '\n';
+    appendFileSync(logPath, line);
+  } catch { /* non-fatal */ }
+}
+
+function writeAsrPacket({ sourcePath, extension, errorMessage }) {
+  try {
+    const dir = needsAsrDir();
+    mkdirSync(dir, { recursive: true });
+    const id = `asr-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+    const packet = { id, ts: new Date().toISOString(), sourcePath, extension, error: errorMessage };
+    writeFileSync(join(dir, `${id}.json`), JSON.stringify(packet, null, 2));
+    return id;
+  } catch { return null; }
+}
+
 function nextAvailablePath(targetPath) {
   if (!existsSync(targetPath)) return targetPath;
   const dot = targetPath.lastIndexOf('.');
@@ -306,6 +338,10 @@ export class InboxWatcher {
               if (contentIdx !== -1) extractedText = md.slice(contentIdx + 20).trim();
             } catch (err) { process.stderr.write('[inbox.mjs] read-extracted-text: ' + (err?.message ?? String(err)) + '\n'); }
 
+            // Write extraction warnings JSONL for any dropped structured content.
+            const droppedInfo = fileResult.droppedInfo ?? [];
+            writeExtractionWarning({ sourcePath: candidate.path, droppedInfo });
+
             recordInboxObservation(this.#rootDir, {
               sourcePath: candidate.path,
               outputPath: fileResult.outputPath,
@@ -333,6 +369,7 @@ export class InboxWatcher {
                   outputPath: fileResult.outputPath,
                   characters: fileResult.characters,
                   knowledgeSubdir,
+                  droppedInfo,
                 },
                 env: this.#env,
               });
@@ -347,7 +384,15 @@ export class InboxWatcher {
             processed.push({ path: candidate.path, outputPath: fileResult.outputPath, docsPath, characters: fileResult.characters, knowledgeSubdir, intakeId });
           }
         } catch (err) {
-          errors.push({ path: candidate.path, error: err.message });
+          // Audio/video files cannot be text-extracted without ASR. Route to
+          // the needs-asr queue so the signal is preserved for later processing.
+          if (err.code === 'ASR_REQUIRED') {
+            const asrId = writeAsrPacket({ sourcePath: candidate.path, extension: err.extension, errorMessage: err.message });
+            state[key] = { mtimeMs: candidate.mtimeMs, processedAt: new Date().toISOString(), needsAsr: true, asrId };
+            processed.push({ path: candidate.path, needsAsr: true, asrId });
+          } else {
+            errors.push({ path: candidate.path, error: err.message });
+          }
         }
       }
     }

package/lib/embed/role-framing.mjs

@@ -12,7 +12,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const REGISTRY_PATH = join(__dirname, '..', '..', 'agents', 'registry.json');
+const REGISTRY_PATH = join(__dirname, '..', '..', 'specialists', 'registry.json');
 
 let _registryCache = null;
 
@@ -22,7 +22,7 @@ function loadRegistry() {
     _registryCache = JSON.parse(readFileSync(REGISTRY_PATH, 'utf8'));
   } catch (err) {
     process.stderr.write('[role-framing.mjs] loadRegistry: ' + (err?.message ?? String(err)) + '\n');
-    _registryCache = { agents: [] };
+    _registryCache = { specialists: [] };
   }
   return _registryCache;
 }
@@ -35,7 +35,7 @@ function loadRegistry() {
 export function getOrientation(roleName) {
   if (!roleName) return null;
   const registry = loadRegistry();
-  const agent = (registry.agents ?? []).find((a) => a.name === roleName);
+  const agent = (registry.specialists ?? []).find((a) => a.name === roleName);
   return agent?.embedOrientation ?? null;
 }
 

package/lib/env-config.mjs

@@ -97,11 +97,17 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
     for (const key of Object.keys(env)) {
       if (ENV_SHADOW_IGNORE.has(key)) continue;
       if (!ENV_SHADOW_WARN.has(key)) continue;
+      // Only warn when process.env has a non-empty competing value.
+      // An empty-string env var (e.g. Claude for Desktop clears ANTHROPIC_API_KEY
+      // so its internal auth is used instead) is not a real conflict — config.env wins
+      // silently and no user action is needed.
+      if (!env[key]) continue;
       if (key in fileEnv && fileEnv[key] !== env[key]) {
         process.stderr.write(
-          `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) shadows ` +
-          `config.env value (${fileEnv[key].slice(0, 6)}…). ` +
-          `Unset the shell variable or update ~/.construct/config.env.\n`,
+          `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) ` +
+          `differs from config.env value (${fileEnv[key].slice(0, 6)}…). ` +
+          `config.env will be used. To silence: unset the shell variable or ` +
+          `update ~/.construct/config.env to match.\n`,
         );
       }
     }