@geraldmaron/construct 1.0.18 → 1.0.20

package/lib/embedded-contract/ingest.mjs

@@ -10,13 +10,18 @@
  * error or a clearly-flagged best-effort fallback — never silent gibberish.
  *
  * Surfaces (CLI/MCP/SDK) own I/O and call this; the contract cores stay pure and
- * receive the resolved text plus an `ingestion` metadata block to echo back.
+ * receive the resolved text plus an `ingestion` metadata block to echo back. The
+ * `ingestion` block records the resolved strategy (adapter | provider) and the
+ * provider/model when one was selected, so the extraction choice is never opaque.
  */
 
 import { readFileSync } from 'node:fs';
 import { extname } from 'node:path';
 
 import { extractDocumentTextAsync, isExtractableDocumentPath } from '../document-extract.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import { resolveIngestStrategy } from '../ingest/strategy.mjs';
+import { extractViaProvider } from '../ingest/provider-extract.mjs';
 
 /**
  * Resolve contract input from inline text or a file path.
@@ -25,9 +30,14 @@ import { extractDocumentTextAsync, isExtractableDocumentPath } from '../document
  * @param {string} [opts.input]     Inline text (returned as-is when provided).
  * @param {string} [opts.filePath]  Path to extract when no inline text is given.
  * @param {number} [opts.maxChars]
+ * @param {object} [opts.config]    Loaded project config (for strategy resolution).
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.strategy]  Explicit strategy override.
+ * @param {string} [opts.cwd]       Working directory for locating project config.
+ * @param {Function} [opts.fetchImpl] Injectable fetch for provider extraction (tests).
  * @returns {Promise<{text:string, ingestion:(object|null), error:(object|null)}>}
  */
-export async function resolveInput({ input = '', filePath = '', maxChars = null } = {}) {
+export async function resolveInput({ input = '', filePath = '', maxChars = null, config = null, env = process.env, strategy = null, cwd = process.cwd(), fetchImpl = undefined } = {}) {
   if (input && input.trim()) {
     return { text: input, ingestion: null, error: null };
   }
@@ -35,6 +45,48 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
     return { text: '', ingestion: null, error: null };
   }
 
+  const projectConfig = config || loadProjectConfig(cwd, env).config;
+  const resolved = resolveIngestStrategy({ config: projectConfig, env, override: strategy });
+  const strategyMeta = { strategy: resolved.strategy, fallback: resolved.fallback, model: resolved.model, provider: resolved.provider };
+
+  // Provider strategy runs a concrete provider-backed extraction. On failure
+  // the fallback policy decides: `adapter` routes to the local extractor and
+  // records the fallback; any other policy surfaces the structured provider
+  // error rather than silently masking the strategy mismatch.
+
+  let providerFallback = null;
+  if (resolved.strategy === 'provider') {
+    try {
+      const extracted = await extractViaProvider({ filePath, model: resolved.model, provider: resolved.provider, maxChars, env, ...(fetchImpl ? { fetchImpl } : {}) });
+      return {
+        text: extracted.text || '',
+        ingestion: {
+          sourcePath: filePath,
+          extractionMethod: extracted.extractionMethod,
+          characters: extracted.characters,
+          truncated: extracted.truncated,
+          droppedInfo: extracted.droppedInfo || [],
+          ...strategyMeta,
+          fallbackApplied: null,
+        },
+        error: null,
+      };
+    } catch (providerErr) {
+      if (resolved.fallback !== 'adapter') {
+        return {
+          text: '',
+          ingestion: { sourcePath: filePath, extractionMethod: 'provider-failed', droppedInfo: [], ...strategyMeta },
+          error: {
+            code: providerErr.code || 'PROVIDER_EXTRACTION_FAILED',
+            reason: providerErr.message,
+            remediation: providerErr.remediation || 'Set ingest.fallback to "adapter" to use the local extractor, or select the adapter strategy.',
+          },
+        };
+      }
+      providerFallback = { from: 'provider', to: 'adapter', reason: providerErr.message, code: providerErr.code || 'PROVIDER_EXTRACTION_FAILED' };
+    }
+  }
+
   if (isExtractableDocumentPath(filePath)) {
     try {
       const extracted = await extractDocumentTextAsync(filePath, { maxChars });
@@ -46,17 +98,19 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
           characters: extracted.characters,
           truncated: extracted.truncated,
           droppedInfo: extracted.droppedInfo || [],
+          ...strategyMeta,
+          fallbackApplied: providerFallback,
         },
         error: null,
       };
     } catch (err) {
       if (err && err.code === 'ASR_REQUIRED') {
-        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) or transcribe the file before sending.' } };
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [], ...strategyMeta }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) or transcribe the file before sending.' } };
       }
       if (err && /WHISPER_BINARY_MISSING/.test(String(err.message))) {
-        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [] }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) to transcribe audio/video.' } };
+        return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'asr-required', droppedInfo: [], ...strategyMeta }, error: { code: 'ASR_REQUIRED', reason: err.message, remediation: 'Install whisper-cli (brew install whisper-cpp) to transcribe audio/video.' } };
       }
-      return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'EXTRACTION_FAILED', reason: err.message, remediation: 'Verify the file is readable and of a supported type.' } };
+      return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [], ...strategyMeta }, error: { code: 'EXTRACTION_FAILED', reason: err.message, remediation: 'Verify the file is readable and of a supported type.' } };
     }
   }
 
@@ -68,10 +122,10 @@ export async function resolveInput({ input = '', filePath = '', maxChars = null
     const text = readFileSync(filePath, 'utf8');
     return {
       text,
-      ingestion: { sourcePath: filePath, extractionMethod: 'raw-utf8', droppedInfo: [], note: `No structured extractor for ${extname(filePath) || 'this type'}; read as plain text.` },
+      ingestion: { sourcePath: filePath, extractionMethod: 'raw-utf8', droppedInfo: [], note: `No structured extractor for ${extname(filePath) || 'this type'}; read as plain text.`, ...strategyMeta, fallbackApplied: providerFallback },
       error: null,
     };
   } catch (err) {
-    return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [] }, error: { code: 'FILE_UNREADABLE', reason: err.message, remediation: 'Check the path and permissions.' } };
+    return { text: '', ingestion: { sourcePath: filePath, extractionMethod: 'failed', droppedInfo: [], ...strategyMeta }, error: { code: 'FILE_UNREADABLE', reason: err.message, remediation: 'Check the path and permissions.' } };
   }
 }

package/lib/gates-audit.mjs

@@ -76,8 +76,8 @@ function parseCIJobs(rootDir) {
     const path = join(dir, file);
     if (!existsSync(path)) continue;
     const yml = readFileSync(path, 'utf8');
-    const jobNames = [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
-    const stepNames = [...yml.matchAll(/^      - name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+    const jobNames = [...yml.matchAll(/^ {4}name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+    const stepNames = [...yml.matchAll(/^ {6}- name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
     names.push(...jobNames, ...stepNames);
   }
   return names.map((n) => n.replace(/\$\{\{\s*matrix\.(\w+)\s*\}\}/g, (_, k) => `<${k}>`));

package/lib/hooks/_lib/output-mode.mjs

@@ -0,0 +1,101 @@
+/**
+ * lib/hooks/_lib/output-mode.mjs — capability-aware SessionStart output routing.
+ *
+ * A SessionStart hook's stdout is injected into the model's context. In a
+ * non-interactive / SDK / `claude -p` one-shot, that verbose context pollutes a
+ * caller's machine-oriented stdout and can spill startup payloads into editors
+ * and logs. This resolver picks the channel the payload should use so stdout
+ * stays reserved for the caller's output contract while diagnostics remain
+ * recoverable.
+ *
+ * Modes (`CONSTRUCT_HOOK_OUTPUT_MODE` env or `hooks.outputMode` config, env >
+ * config > default): `stdout` injects as context (interactive default),
+ * `stderr` writes to stderr, `silent` writes only to a debug log, and `auto`
+ * resolves to stdout when interactive and silent when not.
+ *
+ * Honest limitation: Claude Code exposes no reliable in-hook signal for
+ * interactive vs print/SDK mode (`CLAUDECODE=1` is set in both; `isTTY` is false
+ * even interactively because hooks run without a controlling terminal). So
+ * `auto` detects non-interactive only from signals that ARE reliable — `CI`,
+ * `NODE_ENV=test`, and an explicit `CONSTRUCT_NONINTERACTIVE` flag — and SDK /
+ * host adapters set `CONSTRUCT_HOOK_OUTPUT_MODE` explicitly. `auto` never
+ * suppresses on an ambiguous signal, so real interactive sessions keep their
+ * rich startup context.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+import { resolveSetting, loadProjectConfig } from '../../config/project-config.mjs';
+import { HOOK_OUTPUT_MODES } from '../../config/schema.mjs';
+
+export { HOOK_OUTPUT_MODES };
+
+function truthyFlag(value) {
+  if (value === undefined || value === null) return false;
+  const v = String(value).trim().toLowerCase();
+  return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
+}
+
+/**
+ * Whether the invocation is non-interactive, using only reliable signals.
+ * @param {Record<string,string>} [env]
+ * @returns {boolean}
+ */
+export function isNonInteractive(env = process.env) {
+  if (env.CI === 'true') return true;
+  if (env.NODE_ENV === 'test') return true;
+  if (truthyFlag(env.CONSTRUCT_NONINTERACTIVE)) return true;
+  return false;
+}
+
+function normalizeMode(value) {
+  const m = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  return HOOK_OUTPUT_MODES.includes(m) ? m : null;
+}
+
+/**
+ * Resolve the concrete output channel for the SessionStart payload.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]
+ * @param {Record<string,string>} [opts.env]
+ * @param {object} [opts.config]   loaded project config; read from cwd when omitted
+ * @returns {{mode:('stdout'|'stderr'|'silent'), requested:string, source:string, nonInteractive:boolean}}
+ */
+export function resolveHookOutputMode({ cwd = process.cwd(), env = process.env, config } = {}) {
+  let cfg = config;
+  if (cfg === undefined) {
+    try { cfg = loadProjectConfig(cwd, env).config; } catch { cfg = null; }
+  }
+  const setting = resolveSetting({ config: cfg, jsonPath: 'hooks.outputMode', env, envKey: 'CONSTRUCT_HOOK_OUTPUT_MODE', defaultValue: 'auto' });
+  const requested = normalizeMode(setting.value) || 'auto';
+  const nonInteractive = isNonInteractive(env);
+  const mode = requested !== 'auto' ? requested : (nonInteractive ? 'silent' : 'stdout');
+  return { mode, requested, source: setting.source, nonInteractive };
+}
+
+/**
+ * Route the SessionStart payload to the resolved channel. `silent` preserves the
+ * payload in a debug log so diagnostics stay available without touching the
+ * caller's stdout/stderr. Returns the channel actually used.
+ *
+ * @param {object} opts
+ * @param {string} opts.payload
+ * @param {string} opts.mode      one of stdout|stderr|silent
+ * @param {string} [opts.homeDir]
+ * @param {{write:Function}} [opts.stdout]
+ * @param {{write:Function}} [opts.stderr]
+ * @returns {string} the channel used
+ */
+export function writeHookContext({ payload, mode, homeDir = homedir(), stdout = process.stdout, stderr = process.stderr } = {}) {
+  if (mode === 'stdout') { stdout.write(payload); return 'stdout'; }
+  if (mode === 'stderr') { stderr.write(payload); return 'stderr'; }
+  try {
+    const dir = join(homeDir, '.cx');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'session-start-last.log'), payload);
+  } catch { /* best effort — never block the session on a debug-log write */ }
+  return 'silent';
+}

package/lib/hooks/config-protection.mjs

@@ -3,8 +3,10 @@
  * lib/hooks/config-protection.mjs — protects code-quality config from being weakened.
  *
  * Runs as PreToolUse on Edit|Write|MultiEdit. Blocks edits to eslint /
- * prettier / tsconfig / biome / stylelint configs. Those rules are a contract
- * with the codebase; weakening them is almost always a bug fix in disguise.
+ * prettier / tsconfig / biome / stylelint configs — but only once the config
+ * is an established contract, i.e. tracked in git. A config that is not yet
+ * tracked is being introduced or authored: first-time setup and pre-commit
+ * iteration are allowed; weakening a committed config stays blocked.
  *
  * Meta-system files (hooks, registry, settings template, install/setup
  * entrypoints) are audited but NOT blocked. Editing them is normal work on
@@ -22,6 +24,8 @@
  * @exits 0 = pass | 2 = block tool call
  */
 import { readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import { dirname } from 'path';
 import { logHookFailure } from './_lib/log.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || (() => {
@@ -56,6 +60,21 @@ const META_FILES = [
   /(?:^|\/)tsconfig(\.[^/]+)?\.json$/i,
 ];
 
+// A config is a contract worth protecting only once it is committed. `git
+// ls-files --error-unmatch` exits 0 for a tracked path and non-zero otherwise,
+// so an untracked (newly introduced) config is allowed through.
+
+function isTrackedInGit(p) {
+  try {
+    execFileSync('git', ['ls-files', '--error-unmatch', p], {
+      cwd: dirname(p), stdio: 'ignore', timeout: 1000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function emitEvent(type, category, summary) {
   try {
     const { emitRoleEvent } = await import('../roles/hook-emit.mjs');
@@ -69,7 +88,7 @@ async function emitEvent(type, category, summary) {
 }
 
 const base = filePath.split('/').pop();
-if (PROTECTED.some(r => r.test(base))) {
+if (PROTECTED.some(r => r.test(base)) && isTrackedInGit(filePath)) {
   process.stderr.write(
     `[config-protection] The code quality rules are protected. Fix the code to meet the existing standards — don't weaken the rules.\nFile: ${filePath}\n`
   );

package/lib/hooks/guard-bash.mjs

@@ -136,7 +136,7 @@ if (process.env.CONSTRUCT_ROLES !== 'off') {
             verdict = checkAction({ personaId, action: 'bash', target: trimmed });
           }
           if (!verdict.allowed && verdict.reason === 'outside-fence') {
-            const allowedList = (() => {
+            const allowedList = await (async () => {
               try { const { loadManifest } = await import('../roles/manifest.mjs'); const m = loadManifest(personaId); return m?.fence?.allowedCommands?.join(', ') || 'see role-manifests.json'; } catch { return 'see role-manifests.json'; }
             })();
             process.stderr.write(

package/lib/hooks/session-start.mjs

@@ -23,6 +23,7 @@ import { createSession, lastSession, buildResumeContext } from '../session-store
 import { listObservations, searchObservations } from '../observation-store.mjs';
 import { countEntities } from '../entity-store.mjs';
 import { logHookFailure } from './_lib/log.mjs';
+import { resolveHookOutputMode, writeHookContext } from './_lib/output-mode.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = resolve(MODULE_DIR, '..', '..', 'bin', 'construct');
@@ -378,7 +379,18 @@ try {
   permissionPostureNote = buildPermissionPostureLine({ cwd });
 } catch { /* best effort */ }
 
-process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`);
+// SessionStart context is injected via stdout. In non-interactive / SDK runs
+// that pollutes the caller's output contract, so the resolved output mode routes
+// the payload to stdout (interactive), stderr, or a debug log (silent).
+
+const payload = `${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`;
+try {
+  const { mode } = resolveHookOutputMode({ cwd, env: process.env });
+  writeHookContext({ payload, mode });
+} catch (err) {
+  logHookFailure({ hook: 'session-start', err, phase: 'emit' });
+  process.stdout.write(payload);
+}
 // Auto-bootstrap the policy-engine gate. session-start has just emitted
 // branch + recent commits + prior observations + context-state — that is
 // already grounding; mark the session bootstrapped so the PreToolUse rule

package/lib/ingest/provider-extract.mjs

@@ -0,0 +1,200 @@
+/**
+ * lib/ingest/provider-extract.mjs — concrete provider-backed document extraction.
+ *
+ * The `provider` ingest strategy routes document understanding through the
+ * configured provider/model instead of the local binary adapters. This module
+ * is that route: it reads a file, builds a provider-native request, and returns
+ * extracted text in the same shape `extractDocumentTextAsync` produces so every
+ * caller treats adapter and provider results uniformly.
+ *
+ * Capability is honest, never silently degraded. Images and PDFs are sent as
+ * multimodal blocks (Anthropic `image`/`document`, OpenRouter `image_url`);
+ * text-class files are sent inline for faithful extraction/normalization;
+ * audio/video and Office/zip documents are NOT chat-extractable and raise a
+ * specific `PROVIDER_MEDIA_UNSUPPORTED` so the strategy's fallback policy — not
+ * a hidden code path — decides whether the local adapter handles them. Provider
+ * selection follows the resolved model (Anthropic when the provider/model is
+ * Claude-family, OpenRouter otherwise); a missing key surfaces as a structured
+ * `PROVIDER_KEY_MISSING` rather than an opaque HTTP failure.
+ *
+ * `fetchImpl` and `env` are injectable so the provider path is exercised end to
+ * end against a mock provider without a live key.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+import {
+  AUDIO_VIDEO_EXTS,
+  UTF8_TEXT_EXTS,
+  TRANSCRIPT_EXTS,
+  CALENDAR_EXTS,
+} from '../document-extract.mjs';
+
+export const PROVIDER_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
+
+const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+const DEFAULT_PROMPT = 'Extract the complete textual content of this document faithfully and verbatim. Preserve headings, lists, and tables as Markdown. Do not summarize, interpret, or add commentary — output only the extracted content.';
+
+const MAX_OUTPUT_TOKENS = 4096;
+
+function providerError(code, reason, remediation) {
+  const err = new Error(reason);
+  err.code = code;
+  err.remediation = remediation;
+  return err;
+}
+
+function classifyMedia(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  if (PROVIDER_IMAGE_EXTS.has(ext)) return 'image';
+  if (ext === '.pdf') return 'pdf';
+  if (AUDIO_VIDEO_EXTS.has(ext)) return 'audio-video';
+  if (UTF8_TEXT_EXTS.has(ext) || TRANSCRIPT_EXTS.has(ext) || CALENDAR_EXTS.has(ext)) return 'text';
+  return 'binary-doc';
+}
+
+function isAnthropic(provider, model) {
+  return /anthropic|claude/i.test(provider || '') || /claude/i.test(model || '');
+}
+
+// Key resolution mirrors the daemon's cheap sources (env, then the two dotenv
+// files) without the shell-rc/1Password walk, which belongs to long-running
+// processes rather than a per-file extraction call. Ambient dotenv discovery
+// only augments the real process env; a caller that injects an explicit env
+// object (embedded callers, tests) is authoritative and hermetic.
+
+function resolveKey(varName, env, allowAmbient) {
+  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
+  if (!allowAmbient) return null;
+  for (const file of [join(homedir(), '.construct', 'config.env'), join(homedir(), '.env')]) {
+    try {
+      if (!existsSync(file)) continue;
+      const m = readFileSync(file, 'utf8').match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
+      if (m && m[1]) return m[1].trim();
+    } catch { /* unreadable dotenv is not authoritative */ }
+  }
+  return null;
+}
+
+async function bodyExcerpt(res) {
+  try {
+    const text = await res.text();
+    return text.slice(0, 200);
+  } catch {
+    return '';
+  }
+}
+
+async function callAnthropic({ model, apiKey, content, fetchImpl }) {
+  const res = await fetchImpl('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': apiKey, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+    body: JSON.stringify({
+      model: model.replace(/^anthropic\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      messages: [{ role: 'user', content }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXTRACTION_FAILED', `Anthropic extraction failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and ANTHROPIC_API_KEY, or set ingest.fallback to "adapter".');
+  }
+  const data = await res.json();
+  return (data.content || []).filter((b) => b && b.type === 'text').map((b) => b.text).join('');
+}
+
+async function callOpenRouter({ model, apiKey, content, fetchImpl }) {
+  const res = await fetchImpl('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${apiKey}`, 'content-type': 'application/json', 'HTTP-Referer': 'https://github.com/construct' },
+    body: JSON.stringify({
+      model: model.replace(/^openrouter\//, ''),
+      max_tokens: MAX_OUTPUT_TOKENS,
+      messages: [{ role: 'user', content }],
+    }),
+  });
+  if (!res.ok) {
+    throw providerError('PROVIDER_EXTRACTION_FAILED', `OpenRouter extraction failed (HTTP ${res.status}): ${await bodyExcerpt(res)}`, 'Verify the model id and OPENROUTER_API_KEY, or set ingest.fallback to "adapter".');
+  }
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || '';
+}
+
+/**
+ * Extract a document's text through the configured provider/model.
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath
+ * @param {string} opts.model            resolved provider model id
+ * @param {string} [opts.provider]       resolved provider id (selects the API)
+ * @param {number} [opts.maxChars]       truncate returned text to this length
+ * @param {Record<string,string>} [opts.env]
+ * @param {Function} [opts.fetchImpl]    injectable fetch (for tests)
+ * @param {string} [opts.prompt]
+ * @returns {Promise<{text:string, extractionMethod:string, characters:number, truncated:boolean, droppedInfo:Array}>}
+ */
+export async function extractViaProvider({ filePath, model, provider = null, maxChars = null, env = process.env, fetchImpl = globalThis.fetch, prompt = DEFAULT_PROMPT } = {}) {
+  if (!filePath) throw providerError('PROVIDER_NO_INPUT', 'No file path supplied for provider extraction.', 'Pass a readable file path.');
+  if (!model) throw providerError('PROVIDER_MODEL_UNRESOLVED', 'Provider strategy selected but no provider model resolved.', 'Configure the model tier registry so the ingest tier resolves a model, or set ingest.fallback to "adapter".');
+  if (typeof fetchImpl !== 'function') throw providerError('PROVIDER_NO_FETCH', 'No fetch implementation available for provider extraction.', 'Run on a runtime with global fetch (Node 18+) or inject fetchImpl.');
+
+  const media = classifyMedia(filePath);
+  if (media === 'audio-video') {
+    throw providerError('PROVIDER_MEDIA_UNSUPPORTED', `Provider chat extraction does not transcribe audio/video (${extname(filePath)}).`, 'Use the adapter strategy (whisper ASR) for audio/video, or set ingest.fallback to "adapter".');
+  }
+  if (media === 'binary-doc') {
+    throw providerError('PROVIDER_MEDIA_UNSUPPORTED', `Provider chat extraction does not accept ${extname(filePath) || 'this type'} directly.`, 'Use the adapter strategy for Office/zip documents, or set ingest.fallback to "adapter".');
+  }
+
+  const anthropic = isAnthropic(provider, model);
+  const keyVar = anthropic ? 'ANTHROPIC_API_KEY' : 'OPENROUTER_API_KEY';
+  const apiKey = resolveKey(keyVar, env, env === process.env);
+  if (!apiKey) {
+    throw providerError('PROVIDER_KEY_MISSING', `No API key for ${anthropic ? 'Anthropic' : 'OpenRouter'} provider extraction.`, `Set ${keyVar}, or set ingest.fallback to "adapter".`);
+  }
+
+  let text;
+  if (media === 'text') {
+    const raw = readFileSync(filePath, 'utf8');
+    const promptText = `${prompt}\n\n---\n${raw}`;
+    text = anthropic
+      ? await callAnthropic({ model, apiKey, fetchImpl, content: [{ type: 'text', text: promptText }] })
+      : await callOpenRouter({ model, apiKey, fetchImpl, content: promptText });
+  } else {
+    const base64 = readFileSync(filePath).toString('base64');
+    if (anthropic) {
+      const mediaBlock = media === 'image'
+        ? { type: 'image', source: { type: 'base64', media_type: IMAGE_MIME[extname(filePath).toLowerCase()], data: base64 } }
+        : { type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: base64 } };
+      text = await callAnthropic({ model, apiKey, fetchImpl, content: [mediaBlock, { type: 'text', text: prompt }] });
+    } else if (media === 'pdf') {
+      throw providerError('PROVIDER_MEDIA_UNSUPPORTED', 'PDF provider extraction requires an Anthropic-family model in this build.', 'Select an Anthropic ingest model, or set ingest.fallback to "adapter".');
+    } else {
+      const dataUrl = `data:${IMAGE_MIME[extname(filePath).toLowerCase()]};base64,${base64}`;
+      text = await callOpenRouter({ model, apiKey, fetchImpl, content: [{ type: 'text', text: prompt }, { type: 'image_url', image_url: { url: dataUrl } }] });
+    }
+  }
+
+  text = text || '';
+  let truncated = false;
+  if (maxChars && text.length > maxChars) {
+    text = text.slice(0, maxChars);
+    truncated = true;
+  }
+
+  return {
+    text,
+    extractionMethod: `provider:${anthropic ? 'anthropic' : 'openrouter'}:${model}`,
+    characters: text.length,
+    truncated,
+    droppedInfo: [],
+  };
+}

package/lib/ingest/strategy.mjs

@@ -0,0 +1,95 @@
+/**
+ * lib/ingest/strategy.mjs — resolve the ingest extraction strategy and provider model.
+ *
+ * Construct's ingest path historically extracted documents through local binary
+ * adapters (docling/whisper/pdftotext) without surfacing that choice. This module
+ * makes the choice explicit and configurable:
+ *   - `adapter` (default): the local-extractor pipeline, byte-for-byte unchanged.
+ *   - `provider`: route document understanding through the configured provider/model.
+ * A `fallback` policy (`none`/`provider`/`adapter`) governs what happens on
+ * primary-path failure; the default `none` never silently masks a strategy
+ * mismatch. Resolution precedence matches the project-config convention:
+ * env > config > default. Provider/model identification reuses the embedded model
+ * resolution contract and the tier registry so no second selection surface exists.
+ */
+
+import { resolveSetting } from '../config/project-config.mjs';
+import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
+
+export const INGEST_STRATEGIES = ['adapter', 'provider'];
+export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
+
+export const DEFAULT_INGEST_STRATEGY = 'adapter';
+export const DEFAULT_INGEST_FALLBACK = 'none';
+
+function coerceEnum(value, allowed) {
+  if (typeof value !== 'string') return null;
+  const lowered = value.trim().toLowerCase();
+  return allowed.includes(lowered) ? lowered : null;
+}
+
+// The strategy step a document-understanding model serves under is `fast`; ingest
+// is an extraction/understanding pass, not a reasoning workflow. The embedded
+// resolution contract maps this tier to a concrete provider/model.
+
+const INGEST_WORKFLOW_TYPE = 'evidence-ingest';
+
+function resolveProviderModel({ env, registryPath }) {
+  const resolved = resolveEmbeddedModel({ workflowType: INGEST_WORKFLOW_TYPE }, { env, registryPath });
+  return {
+    model: resolved.selectedModel || null,
+    provider: resolved.selectedProvider || null,
+    resolutionSource: resolved.resolutionSource || null,
+    error: resolved.error || null,
+  };
+}
+
+/**
+ * Resolve the effective ingest strategy, fallback policy, and provider model.
+ *
+ * Precedence for both strategy and fallback is env > config > explicit override
+ * > default, where an explicit `override` (a CLI flag) wins over env/config when
+ * provided. The returned `model`/`provider` are non-null only when the resolved
+ * strategy is `provider` or when `fallback` could route to a provider.
+ *
+ * @param {object} opts
+ * @param {object} [opts.config]      loaded project config object
+ * @param {Record<string,string>} [opts.env]
+ * @param {string} [opts.override]    explicit strategy override (CLI flag)
+ * @param {string} [opts.registryPath]
+ * @returns {{strategy:string, fallback:string, model:(string|null), provider:(string|null), modelResolution:(object|null)}}
+ */
+export function resolveIngestStrategy({ config = null, env = process.env, override = null, registryPath = null } = {}) {
+  const overrideStrategy = coerceEnum(override, INGEST_STRATEGIES);
+
+  const fromSettings = resolveSetting({
+    config,
+    jsonPath: 'ingest.strategy',
+    env,
+    envKey: 'CONSTRUCT_INGEST_STRATEGY',
+    defaultValue: DEFAULT_INGEST_STRATEGY,
+  });
+  const strategy = overrideStrategy
+    || coerceEnum(fromSettings.value, INGEST_STRATEGIES)
+    || DEFAULT_INGEST_STRATEGY;
+
+  const fallbackSetting = resolveSetting({
+    config,
+    jsonPath: 'ingest.fallback',
+    env,
+    envKey: 'CONSTRUCT_INGEST_FALLBACK',
+    defaultValue: DEFAULT_INGEST_FALLBACK,
+  });
+  const fallback = coerceEnum(fallbackSetting.value, INGEST_FALLBACKS) || DEFAULT_INGEST_FALLBACK;
+
+  const needsProviderModel = strategy === 'provider' || fallback === 'provider';
+  const modelResolution = needsProviderModel ? resolveProviderModel({ env, registryPath }) : null;
+
+  return {
+    strategy,
+    fallback,
+    model: modelResolution?.model || null,
+    provider: modelResolution?.provider || null,
+    modelResolution,
+  };
+}

package/lib/init-docs.mjs

@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
 
 import { suggestDocsLaneForFile } from './docs-routing.mjs';
 import { stampFrontmatter } from "./doc-stamp.mjs";
+import { multiSelect, selectOption } from './tty-prompts.mjs';
 import readline from "node:readline";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));