@geraldmaron/construct 1.0.14 → 1.0.16

package/lib/document-extract.mjs

@@ -1,15 +1,19 @@
 /**
  * lib/document-extract.mjs — shared local document extraction for retrieval and MCP reads.
  *
- * Handles plain-text formats directly, XML/HTML via lightweight tag stripping,
- * 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.
+ * Two extraction paths:
+ *   - 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.
  *
- * 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.
+ * `extractDocumentMetadata` returns frontmatter + title/authors/dates.
+ *
+ * All paths return droppedInfo as { kind, count, reason, recoverable }[] so
+ * info loss is observable rather than silent.
  */
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { basename, extname, resolve } from 'node:path';
@@ -689,3 +693,64 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   if (extracted.skipped) result.skipped = extracted.skipped;
   return result;
 }
+
+// Async high-fidelity extraction path. Routes PDF/Office/HTML through the
+// docling Python sidecar (layout-aware markdown) and audio/video through
+// whisper.cpp (Metal-accelerated on macOS). Text/transcript/calendar/email
+// paths reuse the sync extraction since regex-stripping is the right tool
+// for those formats. Returns the same { text, droppedInfo, ... } shape as
+// the sync extractor plus a `markdown` field for paths that produce it.
+//
+// 2026-06 best practice: this is the path new callers should use. The sync
+// extractDocumentText is preserved for backwards compatibility with
+// pre-async callers; PDF/Office output via that path is lower fidelity
+// (tables flattened, formulas dropped) and emits a droppedInfo notice.
+
+export async function extractDocumentTextAsync(filePath, { maxChars = null } = {}) {
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) throw new Error(`File not found: ${resolvedPath}`);
+  const extension = extname(resolvedPath).toLowerCase();
+  if (!EXTRACTABLE_DOCUMENT_EXTS.has(extension)) {
+    throw new Error(`Unsupported document type: ${extension || 'unknown'}`);
+  }
+
+  if (AUDIO_VIDEO_EXTS.has(extension)) {
+    const { extractViaWhisper } = await import('./document-extract/whisper-client.mjs');
+    const out = await extractViaWhisper(resolvedPath);
+    return finalizeAsyncResult({ resolvedPath, extension, extractionMethod: 'whisper', extracted: out, maxChars });
+  }
+
+  const doclingFormats = new Set([
+    '.pdf',
+    ...ZIP_DOCUMENT_EXTS,
+    ...RICH_TEXT_EXTS,
+    ...MDLS_DOCUMENT_EXTS,
+  ]);
+  if (doclingFormats.has(extension)) {
+    const { extractViaDocling } = await import('./document-extract/docling-client.mjs');
+    const out = await extractViaDocling(resolvedPath);
+    return finalizeAsyncResult({ resolvedPath, extension, extractionMethod: 'docling', extracted: out, maxChars });
+  }
+
+  return extractDocumentText(resolvedPath, { maxChars });
+}
+
+function finalizeAsyncResult({ resolvedPath, extension, extractionMethod, extracted, maxChars }) {
+  const text = extracted.markdown ?? extracted.text ?? '';
+  const limit = Number.isFinite(Number(maxChars)) && Number(maxChars) > 0
+    ? Math.min(Number(maxChars), 200_000)
+    : null;
+  const truncated = limit !== null && text.length > limit;
+  return {
+    filePath: resolvedPath,
+    extension,
+    extractionMethod,
+    text: truncated ? `${text.slice(0, limit)}\n` : text,
+    markdown: extracted.markdown ?? null,
+    metadata: extracted.metadata ?? null,
+    truncated,
+    characters: text.length,
+    droppedInfo: extracted.droppedInfo ?? [],
+    structured: extracted.structured ?? null,
+  };
+}

package/lib/document-ingest.mjs

@@ -7,7 +7,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve } from 'node:path';
-import { extractDocumentText, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
+import { extractDocumentText, extractDocumentTextAsync, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
 import { syncFileStateToSql } from './storage/sync.mjs';
 import { stampFrontmatter } from './doc-stamp.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS } from './knowledge/layout.mjs';
@@ -127,6 +127,8 @@ export async function ingestDocuments(inputPaths, {
   outputDir = null,
   target = 'knowledge/internal',
   sync = false,
+  strict = false,
+  highFidelity = true,
   env = process.env,
 } = {}) {
   if (!Array.isArray(inputPaths) || inputPaths.length === 0) {
@@ -142,8 +144,12 @@ export async function ingestDocuments(inputPaths, {
   }
 
   const results = [];
+  let totalDrops = 0;
   for (const sourcePath of files) {
-    const extracted = extractDocumentText(sourcePath, { maxChars: 200_000 });
+    const extracted = highFidelity
+      ? await extractDocumentTextAsync(sourcePath, { maxChars: 200_000 })
+      : extractDocumentText(sourcePath, { maxChars: 200_000 });
+    totalDrops += (extracted.droppedInfo ?? []).reduce((a, d) => a + (Number(d.count) || 1), 0);
     const metadata = extractDocumentMetadata(sourcePath);
     const targetPath = resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target });
     ensureDir(dirname(targetPath));
@@ -184,6 +190,13 @@ export async function ingestDocuments(inputPaths, {
     });
   }
 
+  if (strict && totalDrops > 0) {
+    const err = new Error(`--strict: ${totalDrops} dropped items across ${results.filter(r => r.droppedInfo.length).length} files`);
+    err.code = 'INGEST_DROPS';
+    err.droppedInfo = results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath })));
+    throw err;
+  }
+
   return {
     status: 'ok',
     target: outputPath ? 'custom' : target,
@@ -197,6 +210,9 @@ export async function ingestDocuments(inputPaths, {
     indexedLocally: true,
     storageSync: syncResult,
     files: results,
+    droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
+    droppedCount: totalDrops,
+    highFidelity,
   };
 }
 
@@ -206,19 +222,25 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let outputDir = null;
   let target = 'knowledge/internal';
   let sync = false;
+  let strict = false;
+  let highFidelity = true;
 
   for (const arg of argv) {
     if (arg.startsWith('--out=')) outputPath = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--out-dir=')) outputDir = arg.split('=').slice(1).join('=');
     else if (arg.startsWith('--target=')) target = arg.split('=').slice(1).join('=');
     else if (arg === '--sync') sync = true;
+    else if (arg === '--strict') strict = true;
+    else if (arg === '--legacy-extractor') highFidelity = false;
     else inputs.push(arg);
   }
 
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--sync]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--sync] [--strict] [--legacy-extractor]\n` +
+      `  --strict: exit non-zero if any extraction drops occur\n` +
+      `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }
@@ -229,5 +251,5 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     );
   }
 
-  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, env });
+  return ingestDocuments(inputs, { cwd, outputPath, outputDir, target, sync, strict, highFidelity, env });
 }

package/lib/embed/daemon.mjs

@@ -1095,7 +1095,12 @@ this.#scheduler.register(
                 outputTokens = data.usage?.completion_tokens || 0;
               }
             }
-          } catch { /* probe call failed — still record timing */ }
+          } catch (probeErr) {
+            // Probe call failed; record the timing entry but surface the
+            // failure to the daemon log so operators can distinguish a 0ms
+            // success from a hard error. Don't crash the daemon.
+            process.stderr.write(`[embed] Probe call failed: ${probeErr.message}\n`);
+          }
 
           const endTime = Date.now();
 

package/lib/flavors/loader.mjs

@@ -6,7 +6,7 @@
  *   - validateFlavor(path) — frontmatter conformance check against the schema
  *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
  *
- * The cap is enforced at sync time and in lint-prose's sibling lint-flavors.
+ * The cap is enforced at sync time and in lint-profiles.
  * Six flavors per role per profile is the current ceiling; bumping requires
  * an ADR. Existing roles like qa already have 6, so the cap is set tight.
  */

package/lib/handoffs/contract.mjs

@@ -38,7 +38,7 @@
  *
  * `parseHandoff` is intentionally permissive — pre-contract handoffs with
  * no frontmatter still parse with status='legacy' so they aren't lost.
- * `validateHandoff` is the strict version, used when writing.
+ * `validateHandoffFile` is the strict version, used when writing.
  */
 
 import { readFileSync } from 'node:fs';
@@ -109,7 +109,7 @@ export function parseHandoffFile(filePath) {
   return parseHandoff(text);
 }
 
-export function validateHandoff(parsed) {
+export function validateHandoffFile(parsed) {
   const errors = [];
   const fm = parsed?.frontmatter || {};
   if (fm.schema !== HANDOFF_SCHEMA_VERSION) errors.push(`schema must be '${HANDOFF_SCHEMA_VERSION}'`);

package/lib/hooks/session-start.mjs

@@ -271,7 +271,7 @@ try {
   if (hasSources) {
     const parts = [];
     if (repos.length > 0) parts.push(`GitHub repos: ${repos.join(', ')}`);
-    if (jiraConfigured) parts.push(`Jira: ${process.env.JIRA_BASE_URL}`);
+    if (jiraConfigured) parts.push('Jira: configured');
     if (linearConfigured) parts.push('Linear: configured');
     // Surface which sources are wired so `provider_fetch` is the obvious
     // tool for questions about them. The "fetch first, don't answer from

package/lib/hooks/stop-notify.mjs

@@ -26,6 +26,7 @@ import { listSessions, loadSession, updateSession } from '../session-store.mjs';
 import { captureSessionArtifacts } from '../artifact-capture.mjs';
 import { appendSessionStats } from '../memory-stats.mjs';
 import { estimateUsageCost } from '../telemetry/model-pricing-catalog.mjs';
+import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 
 function loadTranscriptCheckpoints(checkpointPath) {
   try {
@@ -140,6 +141,12 @@ let raw = '';
 try { raw = readFileSync(0, 'utf8'); } catch { /* non-critical */ }
 if (raw) process.stdout.write(raw);
 
+// PostToolUse Read hooks append delta lines instead of rewriting the full
+// read-tracker JSON on every call. Stop fires once per session end; this
+// is the canonical point to fold accumulated deltas back into the JSON.
+// Already wired into pre-compact + audit-reads; Stop is the third anchor.
+try { flushReadTrackerDeltas({ env: process.env }); } catch { /* non-critical */ }
+
 const home = homedir();
 const tsResultPath = join(home, '.cx', 'ts-result.txt');
 const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');

package/lib/ingest/chunker.mjs

@@ -0,0 +1,94 @@
+/**
+ * lib/ingest/chunker.mjs — paragraph-boundary chunker with sentence overlap.
+ *
+ * 2026-06 best practice notes:
+ *   - Recursive/sentence chunking remains the high-recall default (~85-90%
+ *     on 2026 RAG benchmarks). Semantic chunking gains only ~2-3% recall at
+ *     ~14× the embedding cost and only matters above ~5k token docs.
+ *   - Parent-document retrieval is the meaningful 2026 upgrade beyond
+ *     paragraph chunking — track separately if recall plateaus.
+ *
+ * Strategy:
+ *   1. Split markdown by blank-line paragraph boundaries.
+ *   2. Pack paragraphs into chunks under maxChars (default 1500 ≈ 375 tokens).
+ *   3. Add 1-2 sentence overlap between consecutive chunks to preserve
+ *      cross-chunk anchors.
+ *   4. Preserve markdown structure: never split inside a fenced code block.
+ */
+
+const DEFAULT_MAX_CHARS = 1500;
+const DEFAULT_OVERLAP_SENTENCES = 2;
+const SENTENCE_RE = /[^.!?]+[.!?]+["')\]]*\s*/g;
+
+export function splitSentences(text) {
+  const matches = text.match(SENTENCE_RE);
+  if (matches && matches.length) return matches.map((s) => s.trim()).filter(Boolean);
+  return text.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function tailSentences(text, count) {
+  const sentences = splitSentences(text);
+  return sentences.slice(-count).join(' ');
+}
+
+function splitParagraphs(markdown) {
+  const blocks = [];
+  let buffer = '';
+  let inFence = false;
+  for (const line of markdown.split('\n')) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && line.trim() === '' && buffer.trim()) {
+      blocks.push(buffer.trim());
+      buffer = '';
+      continue;
+    }
+    buffer += line + '\n';
+  }
+  if (buffer.trim()) blocks.push(buffer.trim());
+  return blocks;
+}
+
+export function chunkMarkdown(markdown, { maxChars = DEFAULT_MAX_CHARS, overlapSentences = DEFAULT_OVERLAP_SENTENCES } = {}) {
+  const paragraphs = splitParagraphs(markdown || '');
+  if (paragraphs.length === 0) return [];
+
+  const chunks = [];
+  let current = '';
+  let chunkIndex = 0;
+  const flushChunk = () => {
+    if (!current.trim()) return;
+    const text = current.trim();
+    chunks.push({
+      index: chunkIndex++,
+      text,
+      chars: text.length,
+    });
+    const overlap = overlapSentences > 0 ? tailSentences(text, overlapSentences) : '';
+    current = overlap ? overlap + '\n\n' : '';
+  };
+
+  for (const para of paragraphs) {
+    if (current.length + para.length + 2 > maxChars && current.trim()) {
+      flushChunk();
+    }
+    if (para.length > maxChars) {
+      flushChunk();
+      const sentences = splitSentences(para);
+      let buf = '';
+      for (const s of sentences) {
+        if (buf.length + s.length + 1 > maxChars && buf.trim()) {
+          chunks.push({ index: chunkIndex++, text: buf.trim(), chars: buf.trim().length });
+          buf = (overlapSentences > 0 ? tailSentences(buf, overlapSentences) : '') + (overlapSentences > 0 ? ' ' : '');
+        }
+        buf += s + ' ';
+      }
+      if (buf.trim()) {
+        current = buf.trim() + '\n\n';
+      }
+      continue;
+    }
+    current += (current ? '\n\n' : '') + para;
+  }
+  flushChunk();
+  return chunks;
+}

package/lib/ingest/pipeline.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/ingest/pipeline.mjs — orchestrate the content-hashed ingest pipeline.
+ *
+ * Flow: hash → de-dup → extract via docling/whisper → chunk → write to
+ * .cx/ingest/<sha>/. Returns a record describing what was stored along
+ * with any droppedInfo surfaced by the extractor.
+ *
+ * Idempotent: re-ingesting the same content (by sha256) returns the
+ * existing record without re-extracting.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { extractDocumentTextAsync } from '../document-extract.mjs';
+import { hashFile, defaultIngestRoot, readRecord, writeRecord } from './store.mjs';
+import { chunkMarkdown } from './chunker.mjs';
+
+export async function ingestFile(filePath, { cwd = process.cwd(), force = false } = {}) {
+  const absPath = path.resolve(filePath);
+  const stat = await fs.stat(absPath);
+  if (!stat.isFile()) throw new Error(`not a regular file: ${absPath}`);
+
+  const root = defaultIngestRoot(cwd);
+  const sha256 = await hashFile(absPath);
+
+  if (!force) {
+    const existing = await readRecord(root, sha256);
+    if (existing) return { ...existing, status: 'cached' };
+  }
+
+  const extracted = await extractDocumentTextAsync(absPath);
+  const markdown = extracted.markdown ?? extracted.text ?? '';
+  const chunks = chunkMarkdown(markdown);
+
+  const source = {
+    sourcePath: absPath,
+    fileName: path.basename(absPath),
+    extension: extracted.extension,
+    bytes: stat.size,
+    sha256,
+    ingestedAt: new Date().toISOString(),
+  };
+
+  const meta = {
+    extractionMethod: extracted.extractionMethod,
+    extractorMetadata: extracted.metadata ?? null,
+    droppedInfo: extracted.droppedInfo ?? [],
+    chunkCount: chunks.length,
+    chunkChars: chunks.reduce((a, c) => a + c.chars, 0),
+  };
+
+  const record = await writeRecord(root, { sha256, source, meta, markdown });
+  return { ...record, status: 'ingested', droppedInfo: meta.droppedInfo, chunks };
+}

package/lib/ingest/store.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/ingest/store.mjs — content-addressed ingest store at .cx/ingest/<hash>/.
+ *
+ * Each ingested document is stored under its SHA-256 content hash:
+ *   .cx/ingest/<sha256>/source.json   — original path, size, sha256, ingestedAt
+ *   .cx/ingest/<sha256>/markdown.md   — extracted markdown body
+ *   .cx/ingest/<sha256>/meta.json     — extractor metadata, droppedInfo, chunks
+ *
+ * Idempotent: re-ingesting a file with the same content is a no-op (returns
+ * the existing record). Re-running ingestion is the safe default.
+ *
+ * 2026-06 best practice notes:
+ *   - SHA-256 is still the universal content-addressing primitive. BLAKE3 is
+ *     ~2.3× faster on M-series and worth considering at multi-GB scale,
+ *     but is not the industry default and adds an unfamiliar dependency.
+ *     Revisit if ingest throughput becomes a measured bottleneck.
+ *   - Storing markdown body separately from metadata keeps the embedding
+ *     and search paths simple: they only read markdown.md and look up
+ *     provenance from meta.json on demand.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function defaultIngestRoot(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'ingest');
+}
+
+export async function hashFile(filePath) {
+  return new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('error', reject);
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+function recordDirFor(root, sha256) {
+  return path.join(root, sha256);
+}
+
+export async function readRecord(root, sha256) {
+  const dir = recordDirFor(root, sha256);
+  try {
+    const [source, meta, markdown] = await Promise.all([
+      fs.readFile(path.join(dir, 'source.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'meta.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'markdown.md'), 'utf8'),
+    ]);
+    return { sha256, source, meta, markdown, dir };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeRecord(root, { sha256, source, meta, markdown }) {
+  const dir = recordDirFor(root, sha256);
+  await fs.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fs.writeFile(path.join(dir, 'source.json'), JSON.stringify(source, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'markdown.md'), markdown, 'utf8'),
+  ]);
+  return { sha256, dir, source, meta, markdown };
+}
+
+export async function listRecords(root) {
+  let entries;
+  try { entries = await fs.readdir(root, { withFileTypes: true }); }
+  catch { return []; }
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sha = entry.name;
+    if (!/^[a-f0-9]{64}$/.test(sha)) continue;
+    const record = await readRecord(root, sha);
+    if (record) records.push(record);
+  }
+  return records;
+}

package/lib/install/first-invocation.mjs

@@ -24,8 +24,12 @@ import { parseEnvFile, writeEnvValues, getUserEnvPath } from '../env-config.mjs'
 import { probeAll, formatProbe } from '../bootstrap/resources.mjs';
 
 const BOOTSTRAP_CHECKED_KEY = 'BOOTSTRAP_CHECKED';
+// 'install' is the actual handler name in bin/construct's dispatch map;
+// 'setup' is kept for backwards-compat in case anything still routes via
+// that key. Without 'install' the probe will re-prompt the user while
+// they're already running the very command meant to satisfy it.
 const SKIP_COMMANDS = new Set([
-  'hook', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor',
+  'hook', 'install', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor', 'upgrade', 'update',
 ]);
 
 export function shouldSkipProbe({ command, env = process.env, stdin = process.stdin } = {}) {

package/lib/intake/prepare.mjs

@@ -32,12 +32,13 @@ import path from 'node:path';
 import { buildHybridSearchResultsAsync } from '../storage/hybrid-query.mjs';
 import { suggestDocsLaneForFile } from '../docs-routing.mjs';
 import { createIntakeQueue } from './queue.mjs';
-import { classifyRdIntake } from './classify.mjs';
+import { classifyRdIntake, suggestTags } from './classify.mjs';
 import { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
 import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 import { gatherAttribution, stampAttribution } from './attribution.mjs';
 import { MANIFEST_REL_PATH } from './manifest.mjs';
+import { loadVocabulary } from '../tags/vocabulary.mjs';
 
 const DEFAULT_RELATED_LIMIT = 5;
 const EXCERPT_CHARS = 800;
@@ -66,12 +67,18 @@ export async function prepareIntakeForIngestedFile({
 
   let related = [];
   try {
-    const search = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
-    related = (search?.results || []).map((hit) => ({
-      path: hit.source_path || hit.id,
+    const raw = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
+    // Test mocks return an array directly; production wrapper returns
+    // { results: [...] }. Accept both shapes so suggestTags sees the
+    // same `related` regardless of caller. Preserve `tags` for the
+    // related-inherit suggestion path.
+    const hits = Array.isArray(raw) ? raw : (raw?.results || []);
+    related = hits.map((hit) => ({
+      path: hit.source_path || hit.path || hit.id,
       title: hit.title || hit.id,
       score: hit.score,
       summary: hit.summary || '',
+      tags: Array.isArray(hit.tags) ? hit.tags : undefined,
     }));
   } catch (err) {
     related = [];
@@ -98,6 +105,16 @@ export async function prepareIntakeForIngestedFile({
 
   const droppedInfo = ingestedFile.droppedInfo ?? [];
 
+  // Tag auto-attribution: deterministic suggestions from triage + related
+  // doc inheritance, filtered against the project tag vocabulary. Vocab
+  // load failures fall through with empty suggestions — never block the
+  // packet write on a missing/malformed vocab file.
+
+  let vocab = null;
+  try { vocab = loadVocabulary(rootDir); }
+  catch { vocab = null; }
+  const tagSuggestions = suggestTags(triage, related, vocab);
+
   const baseEntry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
@@ -112,6 +129,7 @@ export async function prepareIntakeForIngestedFile({
     excerpt: extracted.slice(0, EXCERPT_CHARS),
     query,
     customers: customers.length ? customers : undefined,
+    tags: tagSuggestions.length > 0 ? tagSuggestions : undefined,
   };
 
   // Capability detection mirrors inbox.mjs: stamp provenance onto the packet

package/lib/integrations/intake-integrations.mjs

@@ -88,6 +88,22 @@ function resolveConfluenceAuth(homeDir) {
 
 // ── GitHub Issues ────────────────────────────────────────────────────────
 
+// A packet that originated from a demo/fixture/inbox-test source must not
+// be published to a real GitHub repo. The caller can override via
+// `publishDemo: true` when the demo run is intentional (e.g. an explicit
+// integration test that creates and then deletes the issue). Default-safe.
+
+export function isDemoIntakePacket(packet) {
+  if (process.env.CONSTRUCT_DEMO === '1') return true;
+  if (process.env.CONSTRUCT_INTAKE_DEMO === '1') return true;
+  const sourcePath = String(packet?.intake?.sourcePath || packet?.sourcePath || '');
+  if (!sourcePath) return false;
+  if (sourcePath.includes('/tests/fixtures/')) return true;
+  if (sourcePath.includes('/.cx/intake/demo/')) return true;
+  if (sourcePath.includes('/cx-intake-demo')) return true;
+  return false;
+}
+
 /**
  * Create a GitHub issue from an intake packet.
  *
@@ -98,9 +114,19 @@ function resolveConfluenceAuth(homeDir) {
  * @param {string} [opts.apiUrl] - GitHub API URL (default: api.github.com)
  * @param {string} [opts.host] - GitHub host (default: github.com)
  * @param {object} [opts.fetchImpl]
- * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string }>}
+ * @param {boolean} [opts.publishDemo] - Override the demo-source gate
+ * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string, skipped?: string }>}
  */
-export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch } = {}) {
+export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch, publishDemo = false } = {}) {
+  if (!publishDemo && isDemoIntakePacket(packet)) {
+    return {
+      ok: false,
+      externalUrl: null,
+      externalId: null,
+      skipped: 'demo-source',
+      error: 'Refused to publish: packet originated from a demo/fixture path (set CONSTRUCT_DEMO=0 and re-run with --publish-issues to override).',
+    };
+  }
   const hd = homedir();
   const auth = resolveGitHubAuth(hd);
   const resolvedRepo = repo || auth.repo || process.env.GITHUB_REPO;

package/lib/knowledge/search.mjs

@@ -80,6 +80,18 @@ function buildSourceList(repoRoot = REPO_ROOT) {
     }
   }
 
+  // User-ingested documents (PDF/Office/audio routed through docling + whisper)
+  const ingestRoot = join(repoRoot, '.cx', 'ingest');
+  if (existsSync(ingestRoot)) {
+    for (const entry of readdirSync(ingestRoot)) {
+      const dir = join(ingestRoot, entry);
+      const markdown = join(dir, 'markdown.md');
+      if (!/^[a-f0-9]{64}$/.test(entry)) continue;
+      if (!existsSync(markdown)) continue;
+      sources.push({ path: markdown, rel: relative(repoRoot, markdown), priority: 4, source: 'ingest' });
+    }
+  }
+
   return sources;
 }