@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/intake/filesystem-queue.mjs

@@ -0,0 +1,158 @@
+/**
+ * lib/intake/filesystem-queue.mjs — filesystem adapter for the IntakeQueue interface.
+ *
+ * Backs the `.cx/intake/{pending,processed,skipped}/` layout used in solo
+ * mode. Implements the contract defined in lib/intake/queue.mjs: enqueue,
+ * listPending, read, markProcessed, markSkipped, reopen, count. The
+ * Postgres adapter (for team and enterprise modes) lives alongside and
+ * implements the same shape so callers do not branch on backend.
+ */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const QUEUE_SUBDIR = '.cx/intake';
+
+export function queueRoot(rootDir) {
+  return path.join(rootDir, QUEUE_SUBDIR);
+}
+
+export function pendingDir(rootDir) {
+  return path.join(queueRoot(rootDir), 'pending');
+}
+
+export function processedDir(rootDir) {
+  return path.join(queueRoot(rootDir), 'processed');
+}
+
+export function skippedDir(rootDir) {
+  return path.join(queueRoot(rootDir), 'skipped');
+}
+
+function slugify(value) {
+  return String(value || 'untitled')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'untitled';
+}
+
+let counter = 0;
+function timestamp() {
+  // Milliseconds + a per-process counter to guarantee uniqueness even when
+  // two enqueues fire in the same millisecond.
+  counter = (counter + 1) % 1000;
+  const c = String(counter).padStart(3, '0');
+  return `${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23)}-${c}`;
+}
+
+export class FilesystemIntakeQueue {
+  constructor(rootDir) {
+    if (!rootDir) throw new Error('FilesystemIntakeQueue: rootDir is required');
+    this.rootDir = rootDir;
+  }
+
+  enqueue(entry) {
+    if (!entry?.intake?.sourcePath) throw new Error('enqueue: entry.intake.sourcePath is required');
+    const dir = pendingDir(this.rootDir);
+    mkdirSync(dir, { recursive: true });
+
+    const ts = timestamp();
+    const slug = slugify(path.basename(entry.intake.sourcePath, path.extname(entry.intake.sourcePath)));
+    const id = `${ts}-${slug}`;
+    const filePath = path.join(dir, `${id}.json`);
+
+    const payload = { id, createdAt: new Date().toISOString(), status: 'pending', ...entry };
+    writeFileSync(filePath, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+    return { id, filePath };
+  }
+
+  listPending() {
+    const dir = pendingDir(this.rootDir);
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => {
+        const filePath = path.join(dir, name);
+        try {
+          const data = JSON.parse(readFileSync(filePath, 'utf8'));
+          return { ...data, filePath };
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => (a.createdAt || '').localeCompare(b.createdAt || ''));
+  }
+
+  count() {
+    const dir = pendingDir(this.rootDir);
+    if (!existsSync(dir)) return 0;
+    return readdirSync(dir).filter((name) => name.endsWith('.json')).length;
+  }
+
+  read(id) {
+    for (const dir of [pendingDir(this.rootDir), processedDir(this.rootDir), skippedDir(this.rootDir)]) {
+      const filePath = path.join(dir, `${id}.json`);
+      if (existsSync(filePath)) {
+        const data = JSON.parse(readFileSync(filePath, 'utf8'));
+        return { ...data, filePath };
+      }
+    }
+    return null;
+  }
+
+  markProcessed(id, { processedBy = 'unknown', notes = '' } = {}) {
+    const src = path.join(pendingDir(this.rootDir), `${id}.json`);
+    if (!existsSync(src)) throw new Error(`markProcessed: no pending entry ${id}`);
+    const data = JSON.parse(readFileSync(src, 'utf8'));
+    data.status = 'processed';
+    data.processedAt = new Date().toISOString();
+    data.processedBy = processedBy;
+    if (notes) data.notes = notes;
+
+    const dst = path.join(processedDir(this.rootDir), `${id}.json`);
+    mkdirSync(path.dirname(dst), { recursive: true });
+    writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    rmSync(src);
+    return { id, filePath: dst };
+  }
+
+  markSkipped(id, { skippedBy = 'unknown', reason = '' } = {}) {
+    const src = path.join(pendingDir(this.rootDir), `${id}.json`);
+    if (!existsSync(src)) throw new Error(`markSkipped: no pending entry ${id}`);
+    const data = JSON.parse(readFileSync(src, 'utf8'));
+    data.status = 'skipped';
+    data.skippedAt = new Date().toISOString();
+    data.skippedBy = skippedBy;
+    if (reason) data.reason = reason;
+
+    const dst = path.join(skippedDir(this.rootDir), `${id}.json`);
+    mkdirSync(path.dirname(dst), { recursive: true });
+    writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    rmSync(src);
+    return { id, filePath: dst };
+  }
+
+  reopen(id) {
+    for (const dir of [processedDir(this.rootDir), skippedDir(this.rootDir)]) {
+      const src = path.join(dir, `${id}.json`);
+      if (!existsSync(src)) continue;
+      const data = JSON.parse(readFileSync(src, 'utf8'));
+      data.status = 'pending';
+      delete data.processedAt;
+      delete data.processedBy;
+      delete data.notes;
+      delete data.skippedAt;
+      delete data.skippedBy;
+      delete data.reason;
+
+      const dst = path.join(pendingDir(this.rootDir), `${id}.json`);
+      mkdirSync(path.dirname(dst), { recursive: true });
+      writeFileSync(dst, JSON.stringify(data, null, 2) + '\n', 'utf8');
+      rmSync(src);
+      return { id, filePath: dst, from: path.basename(dir) };
+    }
+    throw new Error(`reopen: no processed or skipped entry ${id}`);
+  }
+}

package/lib/intake/intake-config.mjs

@@ -0,0 +1,132 @@
+/**
+ * lib/intake/intake-config.mjs — user-facing intake watcher config.
+ *
+ * Lets the user define which directories the inbox watcher scans and how
+ * deep it descends through subdirectories. Persists to
+ * `<rootDir>/.cx/intake-config.json` and merges with env-driven defaults so
+ * CLI, dashboard, and process env all converge on the same answer.
+ *
+ * Schema:
+ *   {
+ *     parentDirs: string[]   // absolute or rootDir-relative
+ *     maxDepth: number       // 0 = only the parent dir, no subdirs
+ *     includeProjectInbox: boolean  // always include <rootDir>/.cx/inbox
+ *     includeDocsIntake: boolean    // include <rootDir>/docs/intake when present
+ *   }
+ *
+ * maxDepth guidance (surfaced verbatim in the dashboard):
+ *   0 — only files directly inside the parent dir
+ *   1 — parent dir + its immediate subdirs
+ *   2 — two levels of subdirs (a common default for project intake roots)
+ *   3+ — deep scans; use with care on large trees
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { shouldCreateCx } from '../project-detection.mjs';
+
+export const INTAKE_CONFIG_FILE = '.cx/intake-config.json';
+export const INTAKE_DEFAULT_MAX_DEPTH = 4;
+export const INTAKE_HARD_MAX_DEPTH = 16;
+
+export const INTAKE_DEPTH_GUIDANCE = [
+  { value: 0, label: 'Only this directory', detail: 'Scans files directly in the parent dir, ignores all subdirs.' },
+  { value: 1, label: 'One level deep', detail: 'Parent dir plus its immediate subdirs (e.g. parent/intake/file.md).' },
+  { value: 2, label: 'Two levels deep', detail: 'Parent and two subdirs. A reasonable default for organized intake roots.' },
+  { value: 4, label: 'Four levels (default)', detail: 'Catches most nested layouts without scanning huge trees.' },
+  { value: 8, label: 'Deep scan', detail: 'Useful for archives. Slower; skip if the parent contains build output.' },
+  { value: INTAKE_HARD_MAX_DEPTH, label: 'Unlimited (capped)', detail: `Walks up to ${INTAKE_HARD_MAX_DEPTH} levels — effectively unlimited. May be slow.` },
+];
+
+export const DEFAULT_INTAKE_CONFIG = Object.freeze({
+  parentDirs: [],
+  maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
+  includeProjectInbox: true,
+  includeDocsIntake: true,
+});
+
+export function intakeConfigPath(rootDir) {
+  return join(rootDir, INTAKE_CONFIG_FILE);
+}
+
+function clampDepth(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n) || n < 0) return INTAKE_DEFAULT_MAX_DEPTH;
+  return Math.min(Math.floor(n), INTAKE_HARD_MAX_DEPTH);
+}
+
+function normalizeDir(dir, rootDir) {
+  if (typeof dir !== 'string') return null;
+  const trimmed = dir.trim();
+  if (!trimmed) return null;
+  return isAbsolute(trimmed) ? trimmed : resolve(rootDir, trimmed);
+}
+
+function parseEnvDirs(env) {
+  const raw = String(env?.CX_INBOX_DIRS ?? '').trim();
+  if (!raw) return [];
+  return raw.split(':').map((p) => p.trim()).filter(Boolean);
+}
+
+export function loadIntakeConfig(rootDir, env = process.env) {
+  const file = intakeConfigPath(rootDir);
+  let stored = {};
+  if (existsSync(file)) {
+    try { stored = JSON.parse(readFileSync(file, 'utf8')); } catch { stored = {}; }
+  }
+
+  const parentDirs = []
+    .concat(Array.isArray(stored.parentDirs) ? stored.parentDirs : [])
+    .concat(parseEnvDirs(env))
+    .map((dir) => normalizeDir(dir, rootDir))
+    .filter(Boolean);
+
+  const seen = new Set();
+  const uniqueDirs = [];
+  for (const dir of parentDirs) {
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    uniqueDirs.push(dir);
+  }
+
+  const envDepth = env?.CX_INTAKE_MAX_DEPTH;
+  const maxDepth = clampDepth(envDepth ?? stored.maxDepth ?? DEFAULT_INTAKE_CONFIG.maxDepth);
+
+  return {
+    parentDirs: uniqueDirs,
+    maxDepth,
+    includeProjectInbox: stored.includeProjectInbox !== false,
+    includeDocsIntake: stored.includeDocsIntake !== false,
+  };
+}
+
+export function saveIntakeConfig(rootDir, patch = {}) {
+  if (!shouldCreateCx(rootDir)) {
+    throw new Error('Refusing to write intake config: directory is not an initialized construct project. Run `construct init` first.');
+  }
+  const current = loadIntakeConfig(rootDir, {});
+  const next = {
+    parentDirs: Array.isArray(patch.parentDirs)
+      ? patch.parentDirs.map((dir) => normalizeDir(dir, rootDir)).filter(Boolean)
+      : current.parentDirs,
+    maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
+    includeProjectInbox: patch.includeProjectInbox !== undefined ? Boolean(patch.includeProjectInbox) : current.includeProjectInbox,
+    includeDocsIntake: patch.includeDocsIntake !== undefined ? Boolean(patch.includeDocsIntake) : current.includeDocsIntake,
+  };
+
+  const file = intakeConfigPath(rootDir);
+  mkdirSync(join(rootDir, '.cx'), { recursive: true });
+  writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+  return next;
+}
+
+export function describeIntakeDepth(depth = INTAKE_DEFAULT_MAX_DEPTH) {
+  const value = clampDepth(depth);
+  const exact = INTAKE_DEPTH_GUIDANCE.find((g) => g.value === value);
+  if (exact) return exact;
+  return {
+    value,
+    label: `Custom depth (${value})`,
+    detail: `Walks up to ${value} levels of subdirectories below each parent.`,
+  };
+}

package/lib/intake/postgres-queue.mjs

@@ -0,0 +1,198 @@
+/**
+ * lib/intake/postgres-queue.mjs — Postgres adapter for the IntakeQueue interface.
+ *
+ * Backs team and enterprise deployment modes. Implements the same six-method
+ * contract as FilesystemIntakeQueue (enqueue, listPending, count, read,
+ * markProcessed, markSkipped, reopen) plus a claim() method that uses
+ * SELECT ... FOR UPDATE SKIP LOCKED so concurrent workers cannot grab the
+ * same pending item.
+ *
+ * Triage fields (intake_type, rd_stage, primary_owner, recommended_action,
+ * risk, requires_approval, confidence) are flattened into typed columns for
+ * efficient filtering; the full packet — including suggestion / related /
+ * excerpt / query — lives in payload jsonb so the on-disk and in-table
+ * shapes round-trip without loss.
+ */
+
+import path from 'node:path';
+
+function slugify(value) {
+  return String(value || 'untitled')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'untitled';
+}
+
+let counter = 0;
+function timestamp() {
+  // Milliseconds + a per-process counter to guarantee uniqueness even when
+  // two enqueues fire in the same millisecond (test loops, batched ingests).
+  counter = (counter + 1) % 1000;
+  const c = String(counter).padStart(3, '0');
+  return `${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 23)}-${c}`;
+}
+
+function rowToEntry(row) {
+  if (!row) return null;
+  const payload = row.payload || {};
+  return {
+    id: row.id,
+    createdAt: row.created_at instanceof Date ? row.created_at.toISOString() : row.created_at,
+    status: row.status,
+    ...payload,
+    processedAt: row.processed_at instanceof Date ? row.processed_at.toISOString() : row.processed_at || undefined,
+    processedBy: row.processed_by || undefined,
+    notes: row.notes || undefined,
+    skippedAt: row.skipped_at instanceof Date ? row.skipped_at.toISOString() : row.skipped_at || undefined,
+    skippedBy: row.skipped_by || undefined,
+    reason: row.skip_reason || undefined,
+    claimedAt: row.claimed_at instanceof Date ? row.claimed_at.toISOString() : row.claimed_at || undefined,
+    claimedBy: row.claimed_by || undefined,
+  };
+}
+
+export class PostgresIntakeQueue {
+  constructor({ sql, project, tenantId = null } = {}) {
+    if (!sql) throw new Error('PostgresIntakeQueue: sql client is required');
+    if (!project) throw new Error('PostgresIntakeQueue: project is required');
+    this.sql = sql;
+    this.project = project;
+    this.tenantId = tenantId;
+  }
+
+  async enqueue(entry) {
+    if (!entry?.intake?.sourcePath) throw new Error('enqueue: entry.intake.sourcePath is required');
+
+    const ts = timestamp();
+    const slug = slugify(path.basename(entry.intake.sourcePath, path.extname(entry.intake.sourcePath)));
+    const id = `${ts}-${slug}`;
+    const triage = entry.triage || {};
+
+    await this.sql`
+      INSERT INTO construct_intake_items (
+        id, project, tenant_id, status,
+        intake_type, rd_stage, primary_owner, recommended_action,
+        risk, requires_approval, confidence, payload
+      ) VALUES (
+        ${id}, ${this.project}, ${this.tenantId}, 'pending',
+        ${triage.intakeType || null}, ${triage.rdStage || null},
+        ${triage.primaryOwner || null}, ${triage.recommendedAction || null},
+        ${triage.risk || null}, ${triage.requiresApproval || false},
+        ${typeof triage.confidence === 'number' ? triage.confidence : null},
+        ${this.sql.json(entry)}
+      )
+    `;
+    return { id };
+  }
+
+  async listPending({ limit = 100 } = {}) {
+    const rows = await this.sql`
+      SELECT * FROM construct_intake_items
+      WHERE project = ${this.project}
+        AND (${this.tenantId}::text IS NULL OR tenant_id IS NOT DISTINCT FROM ${this.tenantId})
+        AND status = 'pending'
+      ORDER BY created_at ASC
+      LIMIT ${limit}
+    `;
+    return rows.map(rowToEntry);
+  }
+
+  async count() {
+    const rows = await this.sql`
+      SELECT COUNT(*)::int AS n FROM construct_intake_items
+      WHERE project = ${this.project}
+        AND (${this.tenantId}::text IS NULL OR tenant_id IS NOT DISTINCT FROM ${this.tenantId})
+        AND status = 'pending'
+    `;
+    return rows[0]?.n ?? 0;
+  }
+
+  async read(id) {
+    const rows = await this.sql`
+      SELECT * FROM construct_intake_items
+      WHERE id = ${id}
+        AND project = ${this.project}
+        AND (${this.tenantId}::text IS NULL OR tenant_id IS NOT DISTINCT FROM ${this.tenantId})
+      LIMIT 1
+    `;
+    return rows[0] ? rowToEntry(rows[0]) : null;
+  }
+
+  async markProcessed(id, { processedBy = 'unknown', notes = '' } = {}) {
+    const result = await this.sql`
+      UPDATE construct_intake_items
+      SET status = 'processed', processed_at = now(), processed_by = ${processedBy},
+          notes = ${notes || null}, updated_at = now()
+      WHERE id = ${id}
+        AND project = ${this.project}
+        AND status IN ('pending', 'claimed')
+      RETURNING id
+    `;
+    if (result.count === 0) throw new Error(`markProcessed: no pending entry ${id}`);
+    return { id };
+  }
+
+  async markSkipped(id, { skippedBy = 'unknown', reason = '' } = {}) {
+    const result = await this.sql`
+      UPDATE construct_intake_items
+      SET status = 'skipped', skipped_at = now(), skipped_by = ${skippedBy},
+          skip_reason = ${reason || null}, updated_at = now()
+      WHERE id = ${id}
+        AND project = ${this.project}
+        AND status IN ('pending', 'claimed')
+      RETURNING id
+    `;
+    if (result.count === 0) throw new Error(`markSkipped: no pending entry ${id}`);
+    return { id };
+  }
+
+  async reopen(id) {
+    const result = await this.sql`
+      UPDATE construct_intake_items
+      SET status = 'pending',
+          processed_at = NULL, processed_by = NULL, notes = NULL,
+          skipped_at = NULL, skipped_by = NULL, skip_reason = NULL,
+          claimed_at = NULL, claimed_by = NULL,
+          updated_at = now()
+      WHERE id = ${id}
+        AND project = ${this.project}
+        AND status IN ('processed', 'skipped')
+      RETURNING id, (CASE WHEN processed_at IS NOT NULL THEN 'processed' ELSE 'skipped' END) AS from_status
+    `;
+    if (result.count === 0) throw new Error(`reopen: no processed or skipped entry ${id}`);
+    return { id, from: result[0]?.from_status || 'unknown' };
+  }
+
+  /**
+   * Atomically claim the next pending intake item for a worker.
+   * Uses SELECT ... FOR UPDATE SKIP LOCKED so concurrent workers across
+   * processes / containers cannot grab the same item. Returns the claimed
+   * entry (with status='claimed'), or null when the queue is empty.
+   */
+  async claim({ claimedBy }) {
+    if (!claimedBy) throw new Error('claim: claimedBy is required');
+    return await this.sql.begin(async (tx) => {
+      const rows = await tx`
+        SELECT * FROM construct_intake_items
+        WHERE project = ${this.project}
+          AND (${this.tenantId}::text IS NULL OR tenant_id IS NOT DISTINCT FROM ${this.tenantId})
+          AND status = 'pending'
+        ORDER BY created_at ASC
+        FOR UPDATE SKIP LOCKED
+        LIMIT 1
+      `;
+      const row = rows[0];
+      if (!row) return null;
+      await tx`
+        UPDATE construct_intake_items
+        SET status = 'claimed', claimed_at = now(), claimed_by = ${claimedBy}, updated_at = now()
+        WHERE id = ${row.id}
+      `;
+      row.status = 'claimed';
+      row.claimed_by = claimedBy;
+      row.claimed_at = new Date();
+      return rowToEntry(row);
+    });
+  }
+}

package/lib/intake/prepare.mjs

@@ -0,0 +1,139 @@
+/**
+ * lib/intake/prepare.mjs — turn a fresh inbox ingestion into an R&D intake packet.
+ *
+ * Called by `InboxWatcher.poll()` after each successful file ingestion.
+ * Four deterministic preparation steps, then write the result to the
+ * intake queue:
+ *
+ *   1. Suggest a docs lane via lib/docs-routing.mjs (postmortem? PRD?).
+ *   2. Query the corpus via lib/storage/hybrid-query.mjs for top-K existing
+ *      docs related to the new content. Uses the file's filename + first
+ *      paragraph as the query (no LLM call needed for retrieval).
+ *   3. Extract a short excerpt of the new content for the agent to see
+ *      without reopening the file.
+ *   4. Run classifyRdIntake to produce the R&D triage object (intake type,
+ *      owner persona, recommended chain, action, risk).
+ *
+ * The agent — invoked manually or via session-start hook nudge — reads
+ * the resulting `.cx/intake/pending/<id>.json` and does the real
+ * comparison work (overlap with existing PRD? contradicts ADR? new RFC
+ * candidate?). The daemon never calls an LLM. This separation keeps the
+ * daemon cheap and predictable; the model spend stays with the agent.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+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 { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
+
+const DEFAULT_RELATED_LIMIT = 5;
+const EXCERPT_CHARS = 800;
+const QUERY_CHARS = 500;
+
+export async function prepareIntakeForIngestedFile({
+  rootDir,
+  ingestedFile,
+  env = process.env,
+  relatedLimit = DEFAULT_RELATED_LIMIT,
+  hybridSearchFn = buildHybridSearchResultsAsync,
+  queue,
+  readFileFn = readContent,
+  classifyFn = classifyRdIntake,
+} = {}) {
+  if (!rootDir) throw new Error('prepareIntakeForIngestedFile: rootDir is required');
+  if (!ingestedFile?.sourcePath) throw new Error('prepareIntakeForIngestedFile: ingestedFile.sourcePath is required');
+
+  const extracted = readFileFn(ingestedFile.outputPath) || '';
+  const query = buildQuery(ingestedFile.sourcePath, extracted);
+
+  let related = [];
+  try {
+    const search = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
+    related = (search?.results || []).map((hit) => ({
+      path: hit.source_path || hit.id,
+      title: hit.title || hit.id,
+      score: hit.score,
+      summary: hit.summary || '',
+    }));
+  } catch (err) {
+    related = [];
+    if (process.env.CONSTRUCT_DEBUG_INTAKE === '1') {
+      process.stderr.write(`[intake:prepare] hybrid search failed: ${err.message}\n`);
+    }
+  }
+
+  const lane = suggestDocsLaneForFile(ingestedFile.sourcePath, extracted) || null;
+  const triage = classifyFn({
+    sourcePath: ingestedFile.sourcePath,
+    extractedText: extracted,
+    related,
+  });
+
+  // Detect customer mentions and update profiles
+  const customerMentions = detectCustomerMentions(extracted.slice(0, 2000));
+  const customers = customerMentions.map((c) => c.customerId);
+
+  const entry = {
+    intake: {
+      sourcePath: ingestedFile.sourcePath,
+      outputPath: ingestedFile.outputPath,
+      characters: ingestedFile.characters,
+      knowledgeSubdir: ingestedFile.knowledgeSubdir,
+    },
+    triage,
+    suggestion: lane ? { lane, source: 'docs-routing.suggestDocsLaneForFile' } : null,
+    related,
+    excerpt: extracted.slice(0, EXCERPT_CHARS),
+    query,
+    customers: customers.length ? customers : undefined,
+  };
+
+  const intakeQueue = queue || createIntakeQueue(rootDir, env);
+  const result = intakeQueue.enqueue(entry);
+  const intakeId = result?.id || '';
+
+  // Update customer profiles with new evidence
+  for (const mention of customerMentions) {
+    try {
+      const intakeType = triage?.intakeType || 'insight';
+      const excerptPreview = (extracted || '').slice(0, 200).replace(/\n/g, ' ').trim();
+      linkSignalToCustomer(mention.customerId, {
+        id: intakeId,
+        type: 'intake',
+        sourcePath: ingestedFile.sourcePath,
+        summary: `[${intakeType}] ${ingestedFile.sourcePath.split('/').pop()}${excerptPreview ? ` — ${excerptPreview.slice(0, 100)}` : ''}`,
+      });
+    } catch (err) {
+      if (process.env.CONSTRUCT_DEBUG_INTAKE === '1') {
+        process.stderr.write(`[intake:prepare] customer profile update failed for ${mention.customerId}: ${err.message}\n`);
+      }
+    }
+  }
+
+  return result;
+}
+
+function buildQuery(sourcePath, extracted) {
+  const filename = path.basename(sourcePath, path.extname(sourcePath))
+    .replace(/[-_]+/g, ' ')
+    .trim();
+  const firstParagraph = (extracted || '').split(/\n\s*\n/).find((p) => p.trim().length > 20) || '';
+  const combined = `${filename}\n\n${firstParagraph}`.slice(0, QUERY_CHARS).trim();
+  return combined || filename || 'untitled intake';
+}
+
+function readContent(outputPath) {
+  if (!outputPath || !existsSync(outputPath)) return '';
+  try {
+    const text = readFileSync(outputPath, 'utf8');
+    const marker = text.indexOf('## Extracted Content');
+    if (marker !== -1) return text.slice(marker + '## Extracted Content'.length).trim();
+    return text;
+  } catch {
+    return '';
+  }
+}