@geraldmaron/construct 1.2.3 → 1.3.1

package/lib/document-extract.mjs

@@ -5,10 +5,8 @@
  *   - Async (preferred): `extractDocumentTextAsync` routes PDF/Office/HTML
  *     through the docling Python sidecar and audio/video through whisper.cpp.
  *     Returns { text, markdown, metadata, droppedInfo, ... }.
- *   - Sync (legacy): `extractDocumentText` keeps regex/CLI extractors.
- *     PDF/Office output is lower fidelity (tables flattened, formulas
- *     dropped, scanned pages return empty). Audio/video throws
- *     { code: 'ASR_REQUIRED' } on this path.
+ *   - Sync (legacy): `extractDocumentText` for text/transcript/calendar/email;
+ *     PDF/Office zip formats require docling or the node-native unpdf/mammoth path.
  *
  * `extractDocumentMetadata` returns frontmatter + title/authors/dates.
  *
@@ -46,17 +44,12 @@ export const AUDIO_VIDEO_EXTS = new Set(['.mp3', '.wav', '.m4a', '.mp4', '.mov',
 
 export const ZIP_DOCUMENT_EXTS = new Set(['.docx', '.xlsx', '.pptx', '.odt', '.ods']);
 
-// Office zip formats with no Node-native backend — callers must route through docling
-// or opt into the legacy zip-xml path via CONSTRUCT_ALLOW_LEGACY_EXTRACT=1.
+// Office zip formats with no Node-native backend require docling.
 const OFFICE_REQUIRES_DOCLING_EXTS = new Set(['.xlsx', '.pptx', '.odt', '.ods']);
 
-function legacyExtractAllowed(env = process.env) {
-  return env.CONSTRUCT_ALLOW_LEGACY_EXTRACT === '1';
-}
-
 function makeOfficeRequiresDoclingError(extension) {
   const err = new Error(
-    `${extension} extraction requires docling. Run \`construct install --with-docling\`, use high-fidelity ingest, or set CONSTRUCT_ALLOW_LEGACY_EXTRACT=1 for the legacy zip-xml path.`,
+    `${extension} extraction requires docling. Run \`construct install --with-docling\` or use high-fidelity ingest.`,
   );
   err.code = 'OFFICE_REQUIRES_DOCLING';
   err.extension = extension;
@@ -65,7 +58,7 @@ function makeOfficeRequiresDoclingError(extension) {
 
 function makePdfRequiresDoclingError() {
   const err = new Error(
-    'PDF extraction requires docling, the node-native unpdf backend, or CONSTRUCT_ALLOW_LEGACY_EXTRACT=1 for pdftotext/PDFKit.',
+    'PDF extraction requires docling or the node-native unpdf backend. Run `construct install --with-docling` or ensure unpdf is installed.',
   );
   err.code = 'PDF_REQUIRES_DOCLING';
   return err;
@@ -85,9 +78,6 @@ 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)
@@ -149,103 +139,6 @@ function extractUtf8(filePath, extension) {
   return { text, method: 'utf8', droppedInfo: [], structured: null };
 }
 
-function zipEntries(filePath) {
-  return run('unzip', ['-Z1', filePath]).split('\n').map((line) => line.trim()).filter(Boolean);
-}
-
-function unzipEntry(filePath, entryPath) {
-  return run('unzip', ['-p', 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');
-  }
-
-  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', droppedInfo, structured: null };
-}
-
 // Minimal RTF-to-text: strip control words, groups, and escapes. RTF is a
 // text format, so this works everywhere; it is the cross-platform fallback when
 // textutil (macOS only) is absent. Lossy on complex documents, but never throws.
@@ -280,84 +173,12 @@ function extractRichText(filePath, extension) {
   throw new Error('textutil not available for rich-text extraction');
 }
 
-function extractPdfWithPdftotext(filePath) {
-  return {
-    text: normalizeText(run('pdftotext', ['-layout', '-nopgbrk', filePath, '-'])),
-    method: 'pdftotext',
-    droppedInfo: [],
-    structured: null,
-  };
-}
-
-function extractPdfWithSwift(filePath) {
-  const script = `
-import Foundation
-import PDFKit
-
-let path = CommandLine.arguments[1]
-let url = URL(fileURLWithPath: path)
-guard let document = PDFDocument(url: url) else {
-  fputs("Unable to open PDF\\n", stderr)
-  exit(1)
-}
-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', droppedInfo: [], structured: null };
-}
-
 function extractWithMdls(filePath) {
   const text = normalizeText(run('mdls', ['-raw', '-name', 'kMDItemTextContent', filePath]));
   if (!text || text === '(null)') throw new Error('Spotlight text extraction unavailable');
   return text;
 }
 
-function extractPdf(filePath) {
-  let extracted;
-  if (commandExists('pdftotext')) {
-    extracted = extractPdfWithPdftotext(filePath);
-  } else if (process.platform === 'darwin' && commandExists('swift')) {
-    try {
-      extracted = extractPdfWithSwift(filePath);
-    } catch {
-      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/guides/intake/scanned-pdfs.md.`
-      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/guides/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,
-    }));
-  }
-
-  return extracted;
-}
-
 export function isExtractableDocumentPath(filePath) {
   return EXTRACTABLE_DOCUMENT_EXTS.has(extname(filePath).toLowerCase());
 }
@@ -710,10 +531,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
     const envelope = extractCalendar(resolvedPath);
     extracted = { text: envelope.text, method: 'ics', droppedInfo: envelope.droppedInfo, structured: envelope.structured };
   } else if (ZIP_DOCUMENT_EXTS.has(extension)) {
-    if (!legacyExtractAllowed()) {
-      throw makeOfficeRequiresDoclingError(extension);
-    }
-    extracted = extractZipDocument(resolvedPath, extension);
+    throw makeOfficeRequiresDoclingError(extension);
   } else if (RICH_TEXT_EXTS.has(extension)) {
     extracted = extractRichText(resolvedPath, extension);
   } else if (MDLS_DOCUMENT_EXTS.has(extension) && process.platform === 'darwin' && commandExists('mdls')) {
@@ -721,10 +539,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   } else if (EMAIL_DOCUMENT_EXTS.has(extension)) {
     extracted = extractEml(resolvedPath);
   } else if (extension === '.pdf') {
-    if (!legacyExtractAllowed()) {
-      throw makePdfRequiresDoclingError();
-    }
-    extracted = extractPdf(resolvedPath);
+    throw makePdfRequiresDoclingError();
   } else {
     throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
   }
@@ -798,12 +613,9 @@ export async function extractDocumentTextNodeNative(filePath, { maxChars = null
       if (text) {
         return buildExtractionResult(resolvedPath, extension, { text, method: nodeBackend.method, droppedInfo: [], structured: null }, maxChars);
       }
-    } catch { /* optional dep absent or parse failure — legacy path only when explicitly allowed */ }
-    if (!legacyExtractAllowed()) {
-      if (extension === '.docx') throw makeOfficeRequiresDoclingError(extension);
-      throw makePdfRequiresDoclingError();
-    }
-    return extractDocumentText(resolvedPath, { maxChars });
+    } catch { /* optional dep absent or parse failure */ }
+    if (extension === '.docx') throw makeOfficeRequiresDoclingError(extension);
+    throw makePdfRequiresDoclingError();
   }
 
   return extractDocumentText(resolvedPath, { maxChars });

package/lib/embed/artifact.mjs

@@ -3,9 +3,8 @@
  *
  * Generates PRDs, RFCs, and ADRs as structured markdown files under docs/.
  * Each artifact type has a fixed schema and front-matter. Numbering is auto-
- * incremented by scanning the target directory. Entry points cover the CLI,
- * the embed daemon when analysis triggers a recommendation, and the dashboard
- * API.
+ * incremented by scanning the target directory. Entry points cover the CLI
+ * and the embed daemon when analysis triggers a recommendation.
  */
 
 import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'fs';

package/lib/embed/cli.mjs

@@ -10,7 +10,7 @@
  * Exports:
  *   resolveEmbedStatus(env, homeDir) — returns { level, label, detail }
  *     level: 'running' | 'stopped' | 'none'
- *     Consumed by session-start hook and dashboard /api/embed/status endpoint.
+ *     Consumed by session-start hook and `construct embed status`.
  *
  *   autoStartEmbedIfNeeded(env, rootDir, homeDir) — spawns daemon when
  *     provider credentials are present but daemon is stopped. No-op if already

package/lib/embed/config.mjs

@@ -38,7 +38,6 @@
  *     - type: slack               # post to a Slack channel
  *       provider: slack
  *       channel: C12345
- *     - type: dashboard           # push to the Construct dashboard
  *
  *   approval:
  *     require:                    # action types that need approval before dispatch
@@ -138,7 +137,7 @@ export const DEFAULT_OPERATING_PROFILE = {
   },
   riskModel: {
     detect: ['blocked work', 'missing owner', 'stale cadence', 'source errors', 'missing focal resource', 'unapproved high-risk action'],
-    dashboardStatus: { ok: 'no known gaps', attention: 'gaps or source errors exist', blocked: 'required focal resource or approval path missing' },
+    riskStatus: { ok: 'no known gaps', attention: 'gaps or source errors exist', blocked: 'required focal resource or approval path missing' },
   },
 };
 

package/lib/embed/customer-profiles.mjs

@@ -128,7 +128,7 @@ export function createCustomerProfile({ name, owner, workspace, status = 'active
     updatedAt: new Date().toISOString(),
   };
 
-  const content = `---
+const content = `---
 cx_doc_id: ${randomUUID()}
 created_at: ${profile.createdAt}
 updated_at: ${profile.updatedAt}

package/lib/embed/daemon.mjs

@@ -737,7 +737,7 @@ this.#scheduler.register(
       async () => {
         const result = await this.#inboxWatcher.poll();
         if (result.processed.length) {
-          const { getRebrand } = await import('../profiles/rebrand.mjs');
+          const { getRebrand } = await import('../scopes/rebrand.mjs');
           const { signalNoun } = getRebrand(this.#rootDir);
           const noun = result.processed.length === 1 ? signalNoun : `${signalNoun}s`;
           process.stderr.write(`[embed] Classified ${result.processed.length} ${noun} from [${result.dirs.join(', ')}]\n`);
@@ -932,9 +932,8 @@ this.#scheduler.register(
     );
 
     // ── Job 13: telemetry-heartbeat ──────────────────────────────────────
-    // Every 5 min — emit a daemon.heartbeat trace event so the
-    // dashboard always has recent data, even when no agent/worker activity
-    // has occurred. The heartbeat is fire-and-forget; failure is non-fatal.
+    // Every 5 min — emit a daemon.heartbeat trace event so telemetry backends
+    // always have recent data, even when no agent/worker activity has occurred.
     this.#scheduler.register(
       'telemetry-heartbeat',
       5 * 60_000,
@@ -962,8 +961,8 @@ this.#scheduler.register(
 
     // ── Job 14: telemetry-generation ─────────────────────────────────────────
     // Every 5 min — make a tiny LLM call and record it as a telemetry generation
-    // observation so the dashboard's Latency/TTFT/Throughput/Error sections
-    // always have recent data to display, even when no agent sessions are active.
+    // observation so external telemetry backends always have recent data to display,
+    // even when no agent sessions are active.
     this.#scheduler.register(
       'telemetry-generation',
       5 * 60_000,

package/lib/embed/demand-fetch.mjs

@@ -149,11 +149,36 @@ export function matchSourceFromQuery(query, env = process.env, cwd = process.cwd
  * @param {object} [opts.env]        - Env override
  * @returns {Promise<DemandFetchResult>}
  */
-export async function demandFetch({ query, rootDir, env, cwd } = {}) {
+export async function demandFetch({ query, rootDir, env, cwd, teamId = null, targetIds = null, registry: injectedRegistry = null, providerRegistry = null } = {}) {
   const resolvedEnv = env ?? loadConstructEnv();
   const root = rootDir ?? (resolvedEnv.CX_DATA_DIR?.trim() || homedir());
   const projectRoot = cwd ?? root;
 
+  // Team-scoped fetch: resolve the team's declared sources and drive the fetch
+  // from them. A requested target outside the team is a typed OUT_OF_SCOPE error
+  // — never a silent wrong-source fetch. Resolution is by typed selector, so the
+  // team's effective sources are stable rather than substring-matched.
+  if (teamId) {
+    const { resolveTeamSources } = await import('../config/source-targets.mjs');
+    let registry = injectedRegistry;
+    if (!registry) {
+      const { loadRegistry } = await import('../registry/loader.mjs');
+      try { registry = loadRegistry({ rootDir: projectRoot, skipValidation: true }); } catch { registry = null; }
+    }
+    let targets = resolveTeamSources(teamId, { registry, config: {}, env: resolvedEnv });
+    if (Array.isArray(targetIds) && targetIds.length) {
+      const known = new Set(targets.map((t) => t.id));
+      const unknown = targetIds.filter((id) => !known.has(id));
+      if (unknown.length) {
+        return { ok: false, reason: 'OUT_OF_SCOPE', message: `target_ids not in team ${teamId}: ${unknown.join(', ')}`, items: [], teamId, targetIds };
+      }
+      targets = targets.filter((t) => targetIds.includes(t.id));
+    }
+    if (targets.length) {
+      return demandFetchTeam({ teamId, targets, rootDir: root, env: resolvedEnv, providerRegistry });
+    }
+  }
+
   const match = matchSourceFromQuery(query, resolvedEnv, projectRoot);
 
   // Self-referential queries about Construct itself → route to knowledge_search,
@@ -259,7 +284,7 @@ export async function demandFetch({ query, rootDir, env, cwd } = {}) {
         category: 'insight',
         summary: item.title ?? item.summary ?? item.id,
         content: buildObservationContent(item, match),
-        tags: ['demand-fetch', match.provider, match.ref ?? match.provider],
+        tags: ['demand-fetch', match.provider, match.ref ?? match.provider, ...(teamId ? [`team:${teamId}`] : [])],
         confidence: 0.9,
         source: `demand-fetch:${match.provider}`,
       });
@@ -275,6 +300,7 @@ export async function demandFetch({ query, rootDir, env, cwd } = {}) {
     match,
     written,
     errors: errorItems.length ? errorItems : undefined,
+    ...(teamId ? { teamId } : {}),
   };
 }
 
@@ -451,6 +477,92 @@ function buildReadCalls(match, env, cwd = process.cwd()) {
   return [];
 }
 
+// Read calls for one resolved team source, honoring the target's own filters
+// (jira jql, github refs/limit, slack oldest) rather than the generic defaults.
+
+function buildReadCallsForTarget(target) {
+  const sel = target.selector ?? {};
+  const f = target.filters ?? {};
+  const display = `${target.provider}/${sel.repo ?? sel.project ?? sel.team ?? sel.channel ?? target.id}`;
+  switch (target.provider) {
+    case 'github': {
+      const opts = { repos: [sel.repo], limit: Number.isInteger(f.limit) ? f.limit : 25 };
+      const refs = Array.isArray(f.refs) ? f.refs : ['meta', 'readme', 'docs', 'prs', 'issues', 'commits'];
+      return refs.map((ref) => ({ ref, opts, display }));
+    }
+    case 'jira': {
+      const jql = typeof f.jql === 'string'
+        ? f.jql
+        : `project = "${sel.project}" AND statusCategory != Done ORDER BY updated DESC`;
+      return [{ ref: 'issues', opts: { jql, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    }
+    case 'linear':
+      return [{ ref: 'issues', opts: { team: sel.team, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    case 'slack':
+      return [{ ref: 'messages', opts: { channels: [sel.channel], oldest: Number.isInteger(f.oldest) ? f.oldest : 86400, limit: Number.isInteger(f.limit) ? f.limit : 50 }, display }];
+    default:
+      return [];
+  }
+}
+
+// Drive the fetch from a team's resolved sources: one provider read per target,
+// every observation tagged team:<id> + target:<id> so results stay retrievable by
+// team scope. providerRegistry is injectable for hermetic tests.
+
+async function demandFetchTeam({ teamId, targets, rootDir, env, providerRegistry = null }) {
+  let registry = providerRegistry;
+  if (!registry) {
+    const { ProviderRegistry } = await import('./providers/registry.mjs');
+    registry = await ProviderRegistry.fromEnv(env);
+  }
+
+  const allItems = [];
+  const errors = [];
+  let written = 0;
+
+  for (const target of targets) {
+    const provider = registry.get(target.provider);
+    if (!provider) {
+      errors.push({ provider: target.provider, targetId: target.id, message: `provider "${target.provider}" not registered` });
+      continue;
+    }
+    for (const { ref, opts, display } of buildReadCallsForTarget(target)) {
+      try {
+        const items = await provider.read(ref, opts);
+        for (const item of items ?? []) {
+          if (item.type === 'error') { errors.push(item); continue; }
+          allItems.push(item);
+          try {
+            addObservation(rootDir, {
+              role: 'construct',
+              category: 'insight',
+              summary: item.title ?? item.summary ?? item.id,
+              content: buildObservationContent(item, { provider: target.provider, ref: target.id, display }),
+              tags: ['demand-fetch', 'team', target.provider, `team:${teamId}`, `target:${target.id}`],
+              confidence: 0.88,
+              source: `demand-fetch:team:${teamId}:${target.id}`,
+            });
+            written++;
+          } catch (err) { process.stderr.write('[demand-fetch.mjs] team-store-obs: ' + (err?.message ?? String(err)) + '\n'); }
+        }
+      } catch (err) {
+        errors.push({ provider: target.provider, targetId: target.id, message: err.message });
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0 || allItems.length > 0,
+    reason: allItems.length ? 'team_fetched' : 'team_empty',
+    message: `Fetched ${allItems.length} item(s) from team ${teamId} (${targets.length} source(s)), stored ${written} observation(s)`,
+    items: allItems,
+    teamId,
+    targetIds: targets.map((t) => t.id),
+    written,
+    errors: errors.length ? errors : undefined,
+  };
+}
+
 function buildObservationContent(item, match) {
   const lines = [`Source: ${match.display}`, `Provider: ${match.provider}`];
   if (item.url) lines.push(`URL: ${item.url}`);

package/lib/embed/docs-lifecycle.mjs

@@ -227,9 +227,11 @@ export async function runDocsLifecycle(opts) {
   const actions = [];
   const recommendations = [];
   const conflicts = [];
-
-  // Auto-suppress stale recommendations before generating new ones
-  const suppressed = autoSuppressStale();
+  const localTargets = targets.filter((target) => target.access !== 'remote' && target.path);
+  let suppressed = 0;
+  for (const target of localTargets) {
+    suppressed += autoSuppressStale({ project: target.path });
+  }
 
   for (const target of targets) {
     const gaps = detectDocGaps(target, { snapshot, roleLens });
@@ -266,6 +268,7 @@ export async function runDocsLifecycle(opts) {
         recencyBonus: 2,
         sourceSignalIds: payload.intakeIds || [],
         lane: gap.lane,
+        project: target.path,
       });
       recommendations.push(recResult);
       allGaps.push({ ...gap, target: targetLabel(target), recommendation: recResult });
@@ -276,13 +279,14 @@ export async function runDocsLifecycle(opts) {
       const artifactRecs = recommendArtifacts(snapshot, { rootDir: target.path });
       for (const rec of artifactRecs) {
         // Use recommendation store for dedup
-        const { active, existing } = isRecommendationActive(rec.type, rec.title);
+        const { active, existing } = isRecommendationActive(rec.type, rec.title, { project: target.path });
         if (!active) {
           const recResult = createRecommendation({
             type: rec.type,
             title: rec.title,
             reason: rec.reason,
             signalCount: 1,
+            project: target.path,
           });
           recommendations.push(recResult);
           allGaps.push({
@@ -340,7 +344,7 @@ export async function runDocsLifecycle(opts) {
     }
   }
 
-  const stats = recommendationStats();
+  const stats = recommendationStats({ project: localTargets[0]?.path });
 
   return {
     gaps: allGaps,

package/lib/embed/intake-metrics.mjs

@@ -2,8 +2,8 @@
  * lib/embed/intake-metrics.mjs — Intake pipeline observability.
  *
  * Aggregates volume, velocity, processing time, and acceptance rate from
- * the filesystem intake queue. Designed for the dashboard /api/insights
- * endpoint and the `construct intake metrics` CLI.
+ * the filesystem intake queue. Consumed by `construct intake metrics` and
+ * MCP insight tools.
  *
  * Data sources:
  *   .cx/intake/pending/   — JSON files waiting for triage

package/lib/embed/notifications.mjs

@@ -1,9 +1,8 @@
 /**
  * lib/embed/notifications.mjs — embed action notification bus.
  *
- * Decoupled event emitter for embed daemon → dashboard SSE.
- * The dashboard server subscribes to this bus; the daemon emits events.
- * Slack stub is wired but no-ops without config.
+ * In-process event emitter for embed daemon lifecycle and operator toasts.
+ * Slack webhook delivery is optional via notifySlack.
  */
 
 import { EventEmitter } from 'node:events';