@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/document-ingest.mjs

@@ -9,7 +9,7 @@
  */
 import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
-import { extractDocumentText, extractDocumentTextAsync, extractDocumentTextNodeNative, extractDocumentMetadata, isExtractableDocumentPath } from './document-extract.mjs';
+import { extractDocumentTextAsync, extractDocumentTextNodeNative, 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';
@@ -157,9 +157,9 @@ function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
 // can stall (a large PDF, a slow model download) or fail. Without a bound the
 // caller hangs: the CLI never returns, and the ingest_document MCP tool blocks
 // until the client times out and surfaces an opaque error. Bound the whole
-// docling attempt and fall back to the legacy extractor so ingest always returns
-// a usable result, with the fallback recorded in droppedInfo. Override the bound
-// with CONSTRUCT_DOCLING_TIMEOUT_MS (0 disables the timeout).
+// docling attempt and fall back to the node-native extractor so ingest always
+// returns a usable result, with the fallback recorded in droppedInfo. Override
+// the bound with CONSTRUCT_DOCLING_TIMEOUT_MS (0 disables the timeout).
 
 const DOCLING_TIMEOUT_MS = (() => {
   const raw = Number(process.env.CONSTRUCT_DOCLING_TIMEOUT_MS);
@@ -176,15 +176,15 @@ export function withTimeout(promise, ms, onTimeoutMessage) {
 
 /**
  * Run the high-fidelity (docling) extractor with a bound, falling back to the
- * legacy extractor on timeout or any failure so a caller never hangs. The
+ * node-native extractor on timeout or any failure so a caller never hangs. The
  * extractor functions are injectable for testing; production uses the real
- * docling-async and legacy-sync extractors.
+ * docling-async and node-native extractors.
  */
 export async function extractWithDoclingFallback(sourcePath, {
   maxChars = null,
   timeoutMs = DOCLING_TIMEOUT_MS,
   asyncExtract = extractDocumentTextAsync,
-  syncExtract = extractDocumentText,
+  nodeNativeExtract = extractDocumentTextNodeNative,
 } = {}) {
   try {
     return await withTimeout(
@@ -193,24 +193,23 @@ export async function extractWithDoclingFallback(sourcePath, {
       `docling extraction exceeded ${Math.round(timeoutMs / 1000)}s`,
     );
   } catch (err) {
-    const legacy = syncExtract(sourcePath, { maxChars });
-    legacy.droppedInfo = [
-      ...(legacy.droppedInfo ?? []),
+    const fallback = await nodeNativeExtract(sourcePath, { maxChars });
+    fallback.droppedInfo = [
+      ...(fallback.droppedInfo ?? []),
       {
         kind: 'docling-fallback',
         count: 1,
-        reason: `High-fidelity (docling) extraction failed or timed out (${err.message}); used the legacy extractor. Re-run after \`construct install --with-docling\`, or pass --legacy-extractor to skip docling.`,
+        reason: `High-fidelity (docling) extraction failed or timed out (${err.message}); used the node-native extractor. Re-run after \`construct install --with-docling\`, or pass --fidelity=fast to skip docling.`,
         recoverable: true,
       },
     ];
-    return legacy;
+    return fallback;
   }
 }
 
 // The default adapter path prefers the Node-native extractor (unpdf/mammoth) so
-// plain PDF/DOCX ingest needs no Python venv; it self-degrades to the sync
-// system-binary extractor when the optional dep is absent. High-fidelity stays
-// on docling, reserved for scanned/layout-critical and audio/video.
+// plain PDF/DOCX ingest needs no Python venv; high-fidelity stays on docling for
+// scanned/layout-critical content and formats without a Node backend.
 
 function extractViaAdapter(sourcePath, { highFidelity, maxChars }) {
   return highFidelity
@@ -354,6 +353,7 @@ export async function ingestDocuments(inputPaths, {
     droppedInfo: results.flatMap((r) => r.droppedInfo.map((d) => ({ ...d, sourcePath: r.sourcePath }))),
     droppedCount: totalDrops,
     highFidelity,
+    fidelity: highFidelity ? 'high' : 'fast',
     ingestion: {
       strategy: resolvedStrategy.strategy,
       fallback: resolvedStrategy.fallback,
@@ -373,7 +373,7 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
   let target = 'knowledge/internal';
   let sync = false;
   let strict = false;
-  let highFidelity = true;
+  let fidelity = 'high';
   let strategy = null;
   let orchestration = null;
 
@@ -384,21 +384,30 @@ export async function runIngestCli(argv = process.argv.slice(2), { cwd = process
     else if (arg.startsWith('--strategy=')) strategy = arg.split('=').slice(1).join('=');
     else if (arg === '--strategy') strategy = '';
     else if (arg.startsWith('--orchestration=')) orchestration = arg.split('=').slice(1).join('=');
-    else if (arg === '--sync') sync = true;
+    else if (arg.startsWith('--fidelity=')) {
+      const value = arg.split('=').slice(1).join('=');
+      if (value !== 'fast' && value !== 'high') {
+        throw new Error(`Unsupported fidelity: ${value}. Valid values: fast, high`);
+      }
+      fidelity = value;
+    } else if (arg === '--sync') sync = true;
     else if (arg === '--strict') strict = true;
-    else if (arg === '--legacy-extractor') highFidelity = false;
+    else if (arg === '--legacy-extractor') fidelity = 'fast';
     else if (strategy === '') strategy = arg;
     else inputs.push(arg);
   }
 
+  const highFidelity = fidelity === 'high';
+
   if (inputs.length === 0) {
     throw new Error(
       `Usage: construct ingest <file-or-dir> [more paths] [--out=FILE] [--out-dir=DIR] ` +
-      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--legacy-extractor]\n` +
+      `[--target=sibling|knowledge/<subdir>] [--strategy=adapter|provider] [--orchestration=prompt-only|orchestrated] [--sync] [--strict] [--fidelity=fast|high]\n` +
       `  --strategy: extraction strategy override (adapter = local extractors; provider = configured provider/model)\n` +
       `  --orchestration: prompt-only (deterministic extraction) or orchestrated (engage the specialist chain)\n` +
       `  --strict: exit non-zero if any extraction drops occur\n` +
-      `  --legacy-extractor: use the pre-docling regex extractor (lower fidelity)\n` +
+      `  --fidelity=fast|high: fast = node-native extractors; high = docling (default)\n` +
+      `  --legacy-extractor: deprecated alias for --fidelity=fast\n` +
       `  knowledge subdirs: ${KNOWLEDGE_SUBDIRS.join(', ')}`,
     );
   }

package/lib/embed/auto-sources.mjs

@@ -0,0 +1,44 @@
+/**
+ * lib/embed/auto-sources.mjs — resolve embed auto-discovery sources from project config.
+ *
+ * When embed.yaml is absent, builds provider source records from typed
+ * construct.config.json targets merged with legacy env lists. Falls back
+ * to broad provider defaults only when no targets are configured.
+ */
+
+import { loadProjectConfig } from '../config/project-config.mjs';
+import {
+  resolveEffectiveSourceTargetsFromConfig,
+  targetsToEmbedSources,
+  legacyEnvSourceTargets,
+} from '../config/source-targets.mjs';
+
+export function resolveAutoEmbedSources({ cwd = process.cwd(), env = process.env, registry }) {
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+
+  if (targets.length === 0) {
+    return registry.autoSources(env);
+  }
+
+  const configuredProviders = new Set(targets.map((t) => t.provider));
+  const hasLegacyForUnconfigured = (provider) =>
+    legacyEnvSourceTargets(env).some((t) => t.provider === provider);
+
+  const sources = targetsToEmbedSources(targets);
+
+  for (const name of registry.names()) {
+    if (configuredProviders.has(name)) continue;
+    if (hasLegacyForUnconfigured(name)) continue;
+    const instance = registry.get(name);
+    if (typeof instance?.defaultSources !== 'function') continue;
+  }
+
+  const seen = new Set();
+  return sources.filter((s) => {
+    const key = `${s.provider}:${(s.refs ?? []).join(',')}:${JSON.stringify(s.repos ?? s.project ?? s.team ?? s.channels ?? '')}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}

package/lib/embed/cli.mjs

@@ -392,16 +392,17 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   const { loadEmbedConfig, EMPTY_CONFIG } = await import('./config.mjs');
   const { SnapshotEngine, renderMarkdown } = await import('./snapshot.mjs');
   const { ProviderRegistry } = await import('./providers/registry.mjs');
-  const { loadConstructEnv } = await import('../env-config.mjs');
+  const { prepareConstructEnv } = await import('../runtime-env.mjs');
 
-  const env = loadConstructEnv();
+  const env = prepareConstructEnv();
   const registry = await ProviderRegistry.fromEnv(env);
 
   let cfg;
   if (fs.existsSync(configPath)) {
     cfg = loadEmbedConfig(configPath);
   } else {
-    cfg = { ...EMPTY_CONFIG, sources: registry.autoSources(env) };
+    const { resolveAutoEmbedSources } = await import('./auto-sources.mjs');
+    cfg = { ...EMPTY_CONFIG, sources: resolveAutoEmbedSources({ cwd: process.cwd(), env, registry }) };
   }
 
   if (!cfg.sources.length) {

package/lib/embed/daemon.mjs

@@ -58,54 +58,11 @@ function logCatch(source, err) {
 }
 
 /**
- * Resolve an LLM API key from multiple sources: env → config.env → ~/.env → shell rc.
- * Supports 1Password op:// refs in .zshrc or other shell config files for the
- * telemetry-generation probe.
+ * Resolve an LLM API key via the shared secret resolver (cached op read per process).
  */
 async function resolveLLMKey(varName, env) {
-  if (env[varName] && typeof env[varName] === 'string' && env[varName].length > 0) return env[varName];
-  const homeDir = homedir();
-  const files = [join(homeDir, '.construct', 'config.env'), join(homeDir, '.env')];
-  for (const file of files) {
-    try {
-      if (!existsSync(file)) continue;
-      const content = readFileSync(file, 'utf8');
-      const m = content.match(new RegExp(`^${varName}=["']?(.+?)["']?$`, 'm'));
-      if (m && m[1]) return m[1].trim();
-    } catch { /* skip */ }
-  }
-  // Check shell rc files for exports and command substitutions (including op:// refs)
-  const rcs = [join(homeDir, '.zshrc'), join(homeDir, '.bashrc'), join(homeDir, '.bash_profile'), join(homeDir, '.profile')];
-  const { spawnSync } = await import('child_process');
-  for (const rc of rcs) {
-    if (!existsSync(rc)) continue;
-    try {
-      const content = readFileSync(rc, 'utf8');
-
-      // op:// ref via 1Password CLI
-      const opRe = new RegExp(`export\\s+${varName}=["']?\\$\\(op read '([^']+)'\\)["']?`, 'm');
-      const opMatch = content.match(opRe);
-      if (opMatch) {
-        try {
-          const r = spawnSync('op', ['read', opMatch[1]], { encoding: 'utf8', timeout: 5000 });
-          if (r.status === 0 && r.stdout?.trim()) return r.stdout.trim();
-        } catch { /* op read failed */ }
-      }
-
-      // Source the rc file and echo — handles any $(...) command substitution
-      const anyExportRe = new RegExp(`^\\s*export\\s+${varName}=`, 'm');
-      if (anyExportRe.test(content)) {
-        try {
-          const r = spawnSync('zsh', ['-c', `source "${rc}" 2>/dev/null; echo "\${${varName}}"`], { encoding: 'utf8', timeout: 5000 });
-          if (r.status === 0 && r.stdout?.trim()) {
-            const val = r.stdout.trim().split('\n').pop()?.trim();
-            if (val && !val.includes('ERROR') && !val.includes('op read') && !val.startsWith('$(')) return val;
-          }
-        } catch { /* shell eval failed */ }
-      }
-    } catch { /* skip */ }
-  }
-  return null;
+  const { resolveSecret } = await import('../providers/secret-resolver.mjs');
+  return resolveSecret(varName, { env, cwd: process.cwd() });
 }
 
 // ─── Root dir resolution ─────────────────────────────────────────────────────
@@ -614,6 +571,21 @@ export class EmbedDaemon {
       { runImmediately: true },
     );
 
+    // ── Job 7: rss-cap ────────────────────────────────────────────────────────
+    const { memoryCapMbFor, rssOverCap, currentRssMb } = await import('../resources/process-budget.mjs');
+    const rssCapMb = memoryCapMbFor('embed-daemon', this.#rootDir, this.#env);
+    this.#scheduler.register(
+      'rss-cap',
+      60_000,
+      async () => {
+        if (!rssOverCap(rssCapMb)) return;
+        process.stderr.write(
+          `[embed] RSS ${Math.round(currentRssMb())}MB exceeds cap ${rssCapMb}MB — stopping daemon\n`,
+        );
+        this.stop();
+      },
+    );
+
     // ── Job 0: telemetry-setup ───────────────────────────────────────────────────
 // On startup — ensure annotation queues and eval configs exist (idempotent)
 this.#scheduler.register(

package/lib/embed/demand-fetch.mjs

@@ -19,6 +19,11 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { loadConstructEnv } from '../env-config.mjs';
 import { addObservation } from '../observation-store.mjs';
+import { loadProjectConfig } from '../config/project-config.mjs';
+import {
+  resolveEffectiveSourceTargetsFromConfig,
+  resolveKnownSourcesFromTargets,
+} from '../config/source-targets.mjs';
 
 // ─── Self-query detection ────────────────────────────────────────────────────
 
@@ -62,7 +67,13 @@ function isSelfQuery(query) {
  * @param {object} env
  * @returns {{ id: string, provider: string, ref: string, display: string }[]}
  */
-export function resolveKnownSources(env = process.env) {
+export function resolveKnownSources(env = process.env, cwd = process.cwd()) {
+  const { config } = loadProjectConfig(cwd, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  if (targets.length > 0) {
+    return resolveKnownSourcesFromTargets(targets);
+  }
+
   const sources = [];
 
   // GitHub repos
@@ -112,8 +123,8 @@ export function resolveKnownSources(env = process.env) {
  * @param {object} env
  * @returns {{ provider: string, ref: string, display: string } | null}
  */
-export function matchSourceFromQuery(query, env = process.env) {
-  const sources = resolveKnownSources(env);
+export function matchSourceFromQuery(query, env = process.env, cwd = process.cwd()) {
+  const sources = resolveKnownSources(env, cwd);
   const q = query.toLowerCase();
 
   // Exact or substring match — longest id wins
@@ -138,13 +149,12 @@ export function matchSourceFromQuery(query, env = process.env) {
  * @param {object} [opts.env]        - Env override
  * @returns {Promise<DemandFetchResult>}
  */
-export async function demandFetch({ query, rootDir, env } = {}) {
+export async function demandFetch({ query, rootDir, env, cwd } = {}) {
   const resolvedEnv = env ?? loadConstructEnv();
   const root = rootDir ?? (resolvedEnv.CX_DATA_DIR?.trim() || homedir());
+  const projectRoot = cwd ?? root;
 
-  // Provider match takes priority: if the query names a configured repo/project,
-  // always fetch from that provider — even if isSelfQuery() also fires.
-  const match = matchSourceFromQuery(query, resolvedEnv);
+  const match = matchSourceFromQuery(query, resolvedEnv, projectRoot);
 
   // Self-referential queries about Construct itself → route to knowledge_search,
   // but only when no external provider source was matched.
@@ -168,8 +178,7 @@ export async function demandFetch({ query, rootDir, env } = {}) {
   }
 
   if (!match) {
-    // No specific source match and not a self-query — fetch from all configured providers
-    return demandFetchAll({ query, rootDir: root, env: resolvedEnv });
+    return demandFetchAll({ query, rootDir: root, env: resolvedEnv, cwd: projectRoot });
   }
 
   // Dynamically import provider registry to avoid loading all providers at module init
@@ -188,7 +197,7 @@ export async function demandFetch({ query, rootDir, env } = {}) {
   }
 
   // Build read calls for the matched source and execute them
-  const readCalls = buildReadCalls(match, resolvedEnv);
+  const readCalls = buildReadCalls(match, resolvedEnv, projectRoot);
   if (!readCalls.length) {
     return {
       ok: false,
@@ -281,23 +290,32 @@ export async function demandFetch({ query, rootDir, env } = {}) {
  * @param {object} [opts.env]      - Resolved env
  * @returns {Promise<DemandFetchResult>}
  */
-async function demandFetchAll({ query, rootDir, env } = {}) {
+async function demandFetchAll({ query, rootDir, env, cwd } = {}) {
   const { ProviderRegistry } = await import('./providers/registry.mjs');
   const registry = await ProviderRegistry.fromEnv(env);
-  const providerNames = registry.names();
+  const projectRoot = cwd ?? rootDir ?? process.cwd();
+  const { config } = loadProjectConfig(projectRoot, env);
+  const targets = resolveEffectiveSourceTargetsFromConfig(config, env);
+  const scoped = targets.length > 0;
+
+  const providerNames = scoped
+    ? [...new Set(targets.map((t) => t.provider))].filter((name) => registry.get(name))
+    : registry.names();
 
   if (!providerNames.length) {
     return {
       ok: false,
       reason: 'no_providers',
-      message: 'No provider credentials configured in config.env',
+      message: scoped
+        ? 'No provider credentials configured for the declared source targets'
+        : 'No provider credentials configured in config.env',
       items: [],
     };
   }
 
   const allItems = [];
   const errors = [];
-  const sources = resolveKnownSources(env);
+  const sources = resolveKnownSources(env, projectRoot);
 
   // Group known sources by provider so we can batch-fetch per-provider
   const byProvider = new Map();
@@ -306,11 +324,16 @@ async function demandFetchAll({ query, rootDir, env } = {}) {
     byProvider.get(src.provider).push(src);
   }
 
-  // Also include providers that have no explicit sources (Jira, Linear default fetch)
   for (const name of providerNames) {
     if (!byProvider.has(name)) byProvider.set(name, []);
   }
 
+  if (scoped) {
+    for (const key of [...byProvider.keys()]) {
+      if (!providerNames.includes(key)) byProvider.delete(key);
+    }
+  }
+
   for (const [providerName, provSources] of byProvider) {
     const provider = registry.get(providerName);
     if (!provider) continue;
@@ -318,10 +341,12 @@ async function demandFetchAll({ query, rootDir, env } = {}) {
     // Build read calls — one set per known source, or a default if none listed
     const matchList = provSources.length > 0
       ? provSources
-      : [{ provider: providerName, ref: null, display: providerName }];
+      : (scoped ? [] : [{ provider: providerName, ref: null, display: providerName }]);
+
+    if (!matchList.length) continue;
 
     for (const src of matchList) {
-      const readCalls = buildReadCalls(src, env);
+      const readCalls = buildReadCalls(src, env, projectRoot);
       if (!readCalls.length) continue;
       for (const { ref, opts, display } of readCalls) {
         try {
@@ -384,7 +409,7 @@ async function demandFetchAll({ query, rootDir, env } = {}) {
  * @param {object} env
  * @returns {{ ref: string, opts: object, display: string }[]}
  */
-function buildReadCalls(match, env) {
+function buildReadCalls(match, env, cwd = process.cwd()) {
   if (match.provider === 'github') {
     const opts = { repos: [match.ref], limit: 25 };
     return [
@@ -397,7 +422,13 @@ function buildReadCalls(match, env) {
     ];
   }
   if (match.provider === 'jira') {
-    const projects = (env.JIRA_PROJECTS ?? '').split(',').map(p => p.trim()).filter(Boolean);
+    const { config } = loadProjectConfig(cwd, env);
+    const targets = resolveEffectiveSourceTargetsFromConfig(config, env)
+      .filter((t) => t.provider === 'jira')
+      .map((t) => t.selector.project);
+    const projects = targets.length
+      ? targets
+      : (env.JIRA_PROJECTS ?? '').split(',').map((p) => p.trim()).filter(Boolean);
     const recencyDays = parseInt(env.JIRA_FETCH_RECENCY_DAYS, 10) || 30;
 
     let jql;

package/lib/embed/inbox.mjs

@@ -148,6 +148,12 @@ export function resolveInboxDirs(rootDir, env = process.env) {
   const config = loadIntakeConfig(rootDir, env);
   const dirs = [];
 
+  if (config.includeRootInbox ?? config.includeArchetypeInbox) {
+    const rootInbox = join(rootDir, ARCHETYPE_INBOX_SUBDIR);
+    mkdirSync(rootInbox, { recursive: true });
+    dirs.push(rootInbox);
+  }
+
   if (config.includeProjectInbox) {
     const projectInbox = join(rootDir, DEFAULT_INBOX_SUBDIR);
     mkdirSync(projectInbox, { recursive: true });
@@ -159,16 +165,6 @@ export function resolveInboxDirs(rootDir, env = process.env) {
     if (existsSync(docsIntake)) dirs.push(docsIntake);
   }
 
-  // Archetype inbox is a profile-driven drop zone for raw source files
-  // (capabilities.intake.inbox). Off by default; init flips it on when the
-  // active profile declares the capability so non-archetype projects keep
-  // their pre-Piece-C behavior.
-
-  if (config.includeArchetypeInbox) {
-    const archetypeInbox = join(rootDir, ARCHETYPE_INBOX_SUBDIR);
-    if (existsSync(archetypeInbox)) dirs.push(archetypeInbox);
-  }
-
   for (const candidate of config.parentDirs) {
     if (!candidate) continue;
     if (!existsSync(candidate)) continue;

package/lib/embed/worker.mjs

@@ -8,7 +8,7 @@
 
 import os from 'node:os';
 import path from 'node:path';
-import { loadConstructEnv } from '../env-config.mjs';
+import { prepareConstructEnv } from '../runtime-env.mjs';
 import { EmbedDaemon } from './daemon.mjs';
 
 function parseArgv(argv) {
@@ -19,7 +19,7 @@ function parseArgv(argv) {
 }
 
 const configPath = parseArgv(process.argv.slice(2));
-const env = loadConstructEnv();
+const env = prepareConstructEnv();
 
 // If no config file, build an auto-discovered config inline and inject it
 let daemonOpts = { env };
@@ -28,8 +28,9 @@ if (configPath) {
 } else {
   const { ProviderRegistry } = await import('./providers/registry.mjs');
   const { EMPTY_CONFIG } = await import('./config.mjs');
+  const { resolveAutoEmbedSources } = await import('./auto-sources.mjs');
   const registry = await ProviderRegistry.fromEnv(env);
-  const sources = registry.autoSources(env);
+  const sources = resolveAutoEmbedSources({ cwd: process.cwd(), env, registry });
   daemonOpts.registry = registry;
   daemonOpts.config = {
     ...EMPTY_CONFIG,

package/lib/embedded-contract/index.mjs

@@ -13,6 +13,7 @@ import { recommendPlan as recommendPlanCore } from './triage.mjs';
 import { invokeWorkflow as invokeWorkflowCore } from './workflow-invoke.mjs';
 import { buildCapabilityContract } from './capability.mjs';
 import { resolveExecution as resolveExecutionCore } from './execution.mjs';
+import { planArtifactWorkflow as planArtifactWorkflowCore, runArtifactWorkflow as runArtifactWorkflowCore } from '../artifact-workflow.mjs';
 
 export { CONTRACT_VERSION, MIN_CLIENT_CONTRACT_VERSION, isClientCompatible } from './contract-version.mjs';
 export { APPROVAL_MODES } from './audit.mjs';
@@ -85,3 +86,13 @@ export function describeCapabilities({ env, cwd, rootDir } = {}) {
 export function resolveExecution(request = {}, { env, cwd, registryPath } = {}) {
   return wrapContractResult(resolveExecutionCore(request, { env, cwd, registryPath }), { surface: 'sdk', env, cwd });
 }
+
+/** Plan a manifest-backed artifact workflow without executing specialists. */
+export function planArtifactWorkflow(request = {}, { env, cwd, rootDir } = {}) {
+  return wrapContractResult(planArtifactWorkflowCore(request, { cwd, rootDir }), { surface: 'sdk', env, cwd });
+}
+
+/** Run only locally observable artifact steps and return truthful provenance. */
+export function runArtifactWorkflow(request = {}, { env, cwd, rootDir } = {}) {
+  return wrapContractResult(runArtifactWorkflowCore(request, { cwd, rootDir }), { surface: 'sdk', env, cwd });
+}

package/lib/embedded-contract/model-resolve.mjs

@@ -61,15 +61,15 @@ function matchCapabilities(modelId, requested, warnings) {
   return matched;
 }
 
-function familyByProvider(hostProvider, env) {
+function familyByProvider(hostProvider, env, allowAmbient) {
   if (!hostProvider || typeof hostProvider !== 'string') return null;
-  const families = listModelFamilies({ env });
+  const families = listModelFamilies({ env, allowAmbient });
   return families.find((f) => f.id === hostProvider)
     || families.find((f) => f.id === `openrouter-${hostProvider}`)
     || null;
 }
 
-function success({ selectedModel, family, tier, resolutionSource, fallbackReason = null, tierSource = null, capabilities, warnings, env }) {
+function success({ selectedModel, family, tier, resolutionSource, fallbackReason = null, tierSource = null, capabilities, warnings, env, allowAmbient }) {
   return {
     selectedModel,
     selectedProvider: family ? family.id : null,
@@ -123,28 +123,28 @@ function configError({ tier, reason, remediation, warnings }) {
  * @param {string} [opts.registryPath]
  * @returns {object}
  */
-export function resolveEmbeddedModel(request = {}, { env = process.env, registryPath = null } = {}) {
+export function resolveEmbeddedModel(request = {}, { env = process.env, registryPath = null, allowAmbient = env === process.env } = {}) {
   const { workflowType, requestedTier, hostModel, hostProvider, capabilities, allowCrossProviderFallback = false } = request;
   const tier = resolveTier({ requestedTier, workflowType });
   const warnings = [];
 
-  const hostFamily = hostModel ? describeModelFamily(hostModel, { env }) : null;
+  const hostFamily = hostModel ? describeModelFamily(hostModel, { env, allowAmbient }) : null;
 
   if (hostModel && hostFamily) {
-    return success({ selectedModel: hostModel, family: hostFamily, tier, resolutionSource: 'host-model', capabilities, warnings, env });
+    return success({ selectedModel: hostModel, family: hostFamily, tier, resolutionSource: 'host-model', capabilities, warnings, env, allowAmbient });
   }
   if (hostModel && !hostFamily) {
     warnings.push(`Host model "${hostModel}" is not a recognized provider family; attempting same-family or tier fallback.`);
   }
 
-  const family = hostFamily || familyByProvider(hostProvider, env);
+  const family = hostFamily || familyByProvider(hostProvider, env, allowAmbient);
   if (family) {
     const model = family.tiers[tier];
     if (model) {
       const fallbackReason = hostModel
         ? `Exact host model unavailable; resolved the ${tier} model in the same provider family (${family.id}).`
         : `Resolved the ${tier} model within the host provider family (${family.id}).`;
-      return success({ selectedModel: model, family, tier, resolutionSource: 'same-family-fallback', fallbackReason, capabilities, warnings, env });
+      return success({ selectedModel: model, family, tier, resolutionSource: 'same-family-fallback', fallbackReason, capabilities, warnings, env, allowAmbient });
     }
   }
 
@@ -166,7 +166,7 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
       : 'No host context supplied; used the Construct tier default.';
     return success({
       selectedModel: defaultModel,
-      family: describeModelFamily(defaultModel, { env }),
+      family: describeModelFamily(defaultModel, { env, allowAmbient }),
       tier,
       resolutionSource: 'tier-default',
       fallbackReason,
@@ -174,6 +174,7 @@ export function resolveEmbeddedModel(request = {}, { env = process.env, registry
       capabilities,
       warnings,
       env,
+      allowAmbient,
     });
   }
 

package/lib/env-config.mjs

@@ -8,6 +8,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { API_KEY_CREDENTIALS } from './providers/credential-catalog.mjs';
+import { extractOpRef } from './providers/secret-resolver.mjs';
 
 export function parseEnvFile(filePath) {
   if (!filePath || !fs.existsSync(filePath)) return {};
@@ -88,6 +90,22 @@ const ENV_SHADOW_WARN = new Set([
   'CONSTRUCT_DEPLOYMENT_MODE',
 ]);
 
+const CREDENTIAL_ENV_KEYS = new Set(
+  API_KEY_CREDENTIALS.flatMap((entry) => entry.envVars),
+);
+
+function isOpReference(value) {
+  return Boolean(extractOpRef(value));
+}
+
+function preferInjectedCredential(envValue, fileValue) {
+  return Boolean(
+    envValue
+    && !isOpReference(envValue)
+    && isOpReference(fileValue),
+  );
+}
+
 export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = process.env, warn = true } = {}) {
   const rootEnv = rootDir ? parseEnvFile(path.join(rootDir, '.env')) : {};
   const userEnv = parseEnvFile(getUserEnvPath(homeDir));
@@ -103,6 +121,7 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
       // silently and no user action is needed.
       if (!env[key]) continue;
       if (key in fileEnv && fileEnv[key] !== env[key]) {
+        if (preferInjectedCredential(env[key], fileEnv[key])) continue;
         process.stderr.write(
           `[construct] WARNING: process.env.${key} (${env[key].slice(0, 6)}…) ` +
           `differs from config.env value (${fileEnv[key].slice(0, 6)}…). ` +
@@ -115,7 +134,14 @@ export function loadConstructEnv({ rootDir, homeDir = os.homedir(), env = proces
 
   // process.env is the base; config.env (file) values override shell values
   // so that credentials set in the dashboard always win over stale shell exports.
+  // Materialized credentials from `op run` (or an explicit export) win over stored
+  // op:// references so one 1Password auth per invocation is enough.
   const merged = { ...env, ...fileEnv };
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    if (preferInjectedCredential(env[key], fileEnv[key])) {
+      merged[key] = env[key];
+    }
+  }
   const databaseUrl = resolveDatabaseUrl(merged);
   if (databaseUrl && !cleanEnvValue(merged.DATABASE_URL)) {
     merged.DATABASE_URL = databaseUrl;