@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/ingest/degraded-extract.mjs

@@ -0,0 +1,96 @@
+/**
+ * lib/ingest/degraded-extract.mjs — manifest-governed extraction with a declared fallback chain.
+ *
+ * lib/document-ingest.mjs already bounds a docling attempt with a timeout and
+ * falls back to the node-native extractor on any failure; extractWithChain adds
+ * the governance piece LMCP-K2 requires — the fallback path comes from the
+ * docling ingestion-provider manifest's `degradation.chain` (docling ->
+ * node-native -> refuse) rather than being implicit in the calling code, and
+ * every result is stamped `degraded` so a caller can tell "docling ran" from
+ * "docling was unavailable and a lower-fidelity extractor stood in." A file
+ * type outside the node-native backend's coverage (xlsx/pptx/odt/ods) walks the
+ * chain straight to `refuse` and throws, per the manifest's terminal step.
+ */
+import { degradationChain, probeInstall } from './sidecar-providers.mjs';
+
+const NODE_NATIVE_EXTS = new Set(['.pdf', '.docx']);
+
+function degradedResult(extracted, { chainStep, reason }) {
+  return {
+    ...extracted,
+    degraded: true,
+    degradationStep: chainStep,
+    droppedInfo: [
+      ...(extracted.droppedInfo ?? []),
+      {
+        kind: 'ingestion-provider-degraded',
+        count: 1,
+        reason,
+        recoverable: true,
+      },
+    ],
+  };
+}
+
+/**
+ * extractWithChain(filePath, opts) — run docling extraction governed by the
+ * docling manifest's declared degradation chain.
+ *
+ * @param {object} opts
+ * @param {string} opts.extension lowercased file extension (drives node-native eligibility)
+ * @param {Function} opts.doclingExtract async (filePath) => extraction result; throws on failure
+ * @param {Function} [opts.nodeNativeExtract] async (filePath) => extraction result; throws on failure
+ * @param {Function} [opts.installProbeImpl] injectable probeInstall (fake probes for tests)
+ * @param {boolean} [opts.skipInstallProbe] when true, always attempts doclingExtract
+ *        regardless of the install probe (used when the caller already knows
+ *        docling ran, e.g. contract-test doubles)
+ * @returns {Promise<object>} extraction result; `degraded: true` when the chain fell through
+ */
+export async function extractWithChain(filePath, {
+  extension,
+  doclingExtract,
+  nodeNativeExtract = null,
+  installProbeImpl = probeInstall,
+  skipInstallProbe = false,
+} = {}) {
+  const chain = degradationChain('docling');
+  if (!chain) {
+    throw new Error('docling ingestion-provider manifest is missing or has no degradation chain declared');
+  }
+
+  const installed = skipInstallProbe || installProbeImpl('docling').installed;
+  if (installed) {
+    try {
+      const extracted = await doclingExtract(filePath);
+      return { ...extracted, degraded: false, degradationStep: 'docling' };
+    } catch (err) {
+      return fallToNodeNative(filePath, { extension, nodeNativeExtract, reason: `docling extraction failed: ${err.message}` });
+    }
+  }
+
+  return fallToNodeNative(filePath, { extension, nodeNativeExtract, reason: 'docling is not installed' });
+}
+
+async function fallToNodeNative(filePath, { extension, nodeNativeExtract, reason }) {
+  const nodeNativeEligible = NODE_NATIVE_EXTS.has(extension) && typeof nodeNativeExtract === 'function';
+  if (!nodeNativeEligible) {
+    const err = new Error(
+      `${reason}; no node-native fallback covers '${extension}' — refusing per the docling degradation chain. ` +
+      'Run `construct provider test docling` for diagnosis, or `construct install --with-docling`.',
+    );
+    err.code = 'INGESTION_PROVIDER_REFUSED';
+    err.chainStep = 'refuse';
+    throw err;
+  }
+
+  try {
+    const extracted = await nodeNativeExtract(filePath);
+    return degradedResult(extracted, { chainStep: 'node-native', reason: `${reason}; used the node-native extractor (${extracted.extractionMethod}).` });
+  } catch (err) {
+    const refuseErr = new Error(`${reason}; node-native fallback also failed: ${err.message} — refusing.`);
+    refuseErr.code = 'INGESTION_PROVIDER_REFUSED';
+    refuseErr.chainStep = 'refuse';
+    refuseErr.cause = err;
+    throw refuseErr;
+  }
+}

package/lib/ingest/docling-remote.mjs

@@ -14,6 +14,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveNonNegativeSetting } from '../env-config.mjs';
 
 const DEFAULT_TIMEOUT_MS = 600_000;
 
@@ -38,7 +39,7 @@ export async function extractViaDoclingRemote({ filePath, maxChars = null, env =
     throw err;
   }
 
-  const budget = timeoutMs ?? (Number(env.CONSTRUCT_DOCLING_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS);
+  const budget = timeoutMs ?? resolveNonNegativeSetting(env, 'CONSTRUCT_DOCLING_TIMEOUT_MS', DEFAULT_TIMEOUT_MS);
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), budget);
   try {

package/lib/ingest/provider-extract.mjs

@@ -21,10 +21,8 @@
  * 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 { configDir } from '../config/xdg.mjs';
+import { readFileSync } from 'node:fs';
+import { extname } from 'node:path';
 
 import {
   AUDIO_VIDEO_EXTS,
@@ -32,6 +30,7 @@ import {
   TRANSCRIPT_EXTS,
   CALENDAR_EXTS,
 } from '../document-extract.mjs';
+import { resolveSecret } from '../providers/secret-resolver.mjs';
 
 export const PROVIDER_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp']);
 
@@ -67,23 +66,12 @@ 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(configDir(), '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 */ }
+  try {
+    return resolveSecret(varName, { env, allowAmbient });
+  } catch {
+    return null;
   }
-  return null;
 }
 
 async function bodyExcerpt(res) {

package/lib/ingest/sidecar-providers.mjs

@@ -0,0 +1,196 @@
+/**
+ * lib/ingest/sidecar-providers.mjs — governed install/health probes for ingestion sidecars.
+ *
+ * docling (document extraction, provisioned via uv venv) and whisper (audio
+ * transcription, provisioned as a system/cached binary) are ingestion providers
+ * declared as `ingestion-provider` manifests under lib/extensions/manifests/.
+ * The single place that turns a manifest's `installProbe` and `healthCheck`
+ * declarations into an actual probe result, and exposes the manifest's
+ * `degradation.chain` for the ingest pipeline to consume.
+ *
+ * Every probe accepts an injectable `exec`/`fs` seam so doctor and CLI tests can
+ * exercise the present AND absent code paths without depending on the real uv
+ * venv or whisper-cli binary being installed on the test machine (FAKE probes).
+ * Nothing here throws on absence — a missing sidecar is a reportable state
+ * (`installed: false`), never a crash.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+
+import { loadManifestsFromDir, resolveManifestDirs } from '../extensions/loader.mjs';
+
+export const SIDECAR_PROVIDER_IDS = ['docling', 'whisper'];
+
+function loadManifest(id) {
+  const { builtin } = resolveManifestDirs();
+  const { manifests, errors } = loadManifestsFromDir(builtin);
+  const manifest = manifests.find((m) => m.id === id && m.kind === 'ingestion-provider');
+  if (!manifest) {
+    const relevantError = errors.find((e) => e.includes(`${id}.manifest.json`));
+    return { manifest: null, error: relevantError || `no ingestion-provider manifest found for '${id}'` };
+  }
+  return { manifest, error: null };
+}
+
+function which(bin, { execImpl = spawnSync } = {}) {
+  const checker = process.platform === 'win32' ? 'where' : 'which';
+  const result = execImpl(checker, [bin], { encoding: 'utf8' });
+  if (result.status !== 0) return null;
+  return result.stdout.trim().split('\n')[0] || null;
+}
+
+// docling's install probe reads the venv marker the same way
+// lib/runtime/uv-bootstrap.mjs does, but through an injectable fs seam so tests
+// can simulate "marker present, venv missing" (stale install) and "nothing
+// present" without touching the real filesystem.
+
+function probeDoclingInstall({ runtimeDir, existsImpl = existsSync, readFileImpl = readFileSync } = {}) {
+  const pythonBin = join(runtimeDir, '.venv', 'bin', 'python');
+  const pythonBin3 = join(runtimeDir, '.venv', 'bin', 'python3');
+  const venvPython = existsImpl(pythonBin) ? pythonBin : (existsImpl(pythonBin3) ? pythonBin3 : null);
+  const markerPath = join(runtimeDir, '.install-marker.json');
+
+  if (!existsImpl(markerPath)) {
+    return { installed: false, version: null, reason: 'no install marker at ' + markerPath };
+  }
+  let marker;
+  try {
+    marker = JSON.parse(readFileImpl(markerPath, 'utf8'));
+  } catch (err) {
+    return { installed: false, version: null, reason: `install marker unreadable: ${err.message}` };
+  }
+  if (!venvPython) {
+    return { installed: false, version: marker.doclingVersion || null, reason: 'install marker present but venv python binary missing (stale install)' };
+  }
+  return { installed: true, version: marker.doclingVersion || null, reason: null, pythonBin: venvPython, runtimeDir };
+}
+
+// whisper's install probe mirrors lib/runtime/whisper-bootstrap.mjs's PATH +
+// cached-binary lookup, again through an injectable exec/fs seam.
+
+function probeWhisperInstall({ runtimeDir, candidates, cachedBinaryRel, execImpl = spawnSync, existsImpl = existsSync } = {}) {
+  for (const candidate of candidates) {
+    const found = which(candidate, { execImpl });
+    if (found) return { installed: true, version: null, reason: null, binary: found, source: 'system' };
+  }
+  const cached = join(runtimeDir, cachedBinaryRel);
+  if (existsImpl(cached)) {
+    return { installed: true, version: null, reason: null, binary: cached, source: 'cached' };
+  }
+  return { installed: false, version: null, reason: `not found on PATH (${candidates.join(', ')}) or cached at ${cached}` };
+}
+
+/**
+ * probeInstall(id, opts) — install probe for a governed ingestion provider.
+ *
+ * @param {string} id 'docling' | 'whisper'
+ * @param {object} [opts]
+ * @param {string} [opts.runtimeDir] override runtime dir (defaults to manifest's declared default under cwd)
+ * @param {string} [opts.cwd]
+ * @param {Function} [opts.existsImpl] injectable fs.existsSync (fake probes)
+ * @param {Function} [opts.readFileImpl] injectable fs.readFileSync (fake probes)
+ * @param {Function} [opts.execImpl] injectable spawnSync (fake probes)
+ * @returns {{ ok: boolean, installed: boolean, version: (string|null), reason: (string|null), manifest: object }}
+ */
+export function probeInstall(id, { runtimeDir = null, cwd = process.cwd(), existsImpl = existsSync, readFileImpl = readFileSync, execImpl = spawnSync } = {}) {
+  const { manifest, error } = loadManifest(id);
+  if (!manifest) return { ok: false, installed: false, version: null, reason: error, manifest: null };
+
+  const probeSpec = manifest.installProbe;
+  const resolvedRuntimeDir = runtimeDir || join(cwd, probeSpec.defaultRuntimeDir);
+
+  if (probeSpec.kind === 'venv-marker') {
+    const result = probeDoclingInstall({ runtimeDir: resolvedRuntimeDir, existsImpl, readFileImpl });
+    return { ok: true, ...result, manifest };
+  }
+  if (probeSpec.kind === 'binary-on-path') {
+    const result = probeWhisperInstall({
+      runtimeDir: resolvedRuntimeDir,
+      candidates: probeSpec.candidates,
+      cachedBinaryRel: probeSpec.cachedBinary,
+      execImpl,
+      existsImpl,
+    });
+    return { ok: true, ...result, manifest };
+  }
+  return { ok: false, installed: false, version: null, reason: `unknown installProbe.kind '${probeSpec.kind}'`, manifest };
+}
+
+/**
+ * probeHealth(id, opts) — health check for a governed ingestion provider.
+ *
+ * Runs only when the install probe reports `installed: true`; a not-installed
+ * provider is unhealthy by definition and this short-circuits without
+ * spawning a process (so a missing binary never masquerades as an
+ * exec failure).
+ *
+ * @param {string} id 'docling' | 'whisper'
+ * @param {object} [opts] same injectable seams as probeInstall, plus:
+ * @param {Function} [opts.execImpl] injectable spawnSync for the health subprocess (fake probes)
+ * @returns {{ ok: boolean, healthy: boolean, detail: string, installProbe: object }}
+ */
+export function probeHealth(id, { runtimeDir = null, cwd = process.cwd(), existsImpl = existsSync, readFileImpl = readFileSync, execImpl = spawnSync } = {}) {
+  const installProbe = probeInstall(id, { runtimeDir, cwd, existsImpl, readFileImpl, execImpl });
+  if (!installProbe.ok) {
+    return { ok: false, healthy: false, detail: installProbe.reason, installProbe };
+  }
+  if (!installProbe.installed) {
+    return { ok: true, healthy: false, detail: `${id} not installed: ${installProbe.reason}`, installProbe };
+  }
+
+  const check = installProbe.manifest.healthCheck;
+  if (check.kind !== 'subprocess-version') {
+    return { ok: false, healthy: false, detail: `unknown healthCheck.kind '${check.kind}'`, installProbe };
+  }
+
+  const command = check.command === '<resolvedBinary>'
+    ? installProbe.binary
+    : check.command.replace('<runtimeDir>', installProbe.runtimeDir);
+  const args = check.args.map((a) => (a === '<runtimeDir>' ? installProbe.runtimeDir : a));
+  const result = execImpl(command, args, { encoding: 'utf8', timeout: check.timeoutMs });
+
+  if (result.error) {
+    return { ok: true, healthy: false, detail: `${id} health check failed to spawn: ${result.error.message}`, installProbe };
+  }
+  if (result.status !== 0) {
+    return { ok: true, healthy: false, detail: `${id} health check exited ${result.status}: ${(result.stderr || result.stdout || '').trim().slice(0, 200)}`, installProbe };
+  }
+  const output = (result.stdout || result.stderr || '').trim();
+  return { ok: true, healthy: true, detail: output ? `${id} ${output.split('\n')[0]}` : `${id} healthy`, installProbe };
+}
+
+/**
+ * degradationChain(id) — the manifest-declared fallback chain for a provider.
+ *
+ * @param {string} id
+ * @returns {{ chain: Array<{id:string, mode:string, description:string}>, terminal: string, resultMarking: string }|null}
+ */
+export function degradationChain(id) {
+  const { manifest } = loadManifest(id);
+  return manifest?.degradation || null;
+}
+
+/**
+ * testProvider(id, opts) — combined install+health probe shaped for CLI/doctor
+ * consumption (`construct provider test docling`). Never throws: an absent
+ * provider degrades loudly (`ok: true, healthy: false`) rather than crashing.
+ *
+ * @param {string} id
+ * @param {object} [opts] same injectable seams as probeHealth
+ * @returns {{ id: string, installed: boolean, healthy: boolean, version: (string|null), detail: string, degradation: object|null }}
+ */
+export function testProvider(id, opts = {}) {
+  if (!SIDECAR_PROVIDER_IDS.includes(id)) {
+    return { id, installed: false, healthy: false, version: null, detail: `unknown ingestion provider '${id}'; known: ${SIDECAR_PROVIDER_IDS.join(', ')}`, degradation: null };
+  }
+  const health = probeHealth(id, opts);
+  return {
+    id,
+    installed: !!health.installProbe?.installed,
+    healthy: health.healthy,
+    version: health.installProbe?.version || null,
+    detail: health.detail,
+    degradation: degradationChain(id),
+  };
+}

package/lib/ingest-tooling.mjs

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { resolveDoclingServeUrl } from './ingest/docling-remote.mjs';
+import { defaultRuntimeDir } from './runtime/uv-bootstrap.mjs';
 
 function whichBin(name) {
   const cmd = process.platform === 'win32' ? 'where' : 'which';
@@ -17,12 +18,17 @@ function whichBin(name) {
   return (result.stdout || '').trim().split('\n')[0] || null;
 }
 
-export function doclingVenvPath(cwd = process.cwd()) {
-  return path.join(cwd, '.cx', 'runtime', 'docling', '.venv');
+// One shared, machine-scoped venv (construct-rf26.16), not project-keyed —
+// no cwd/project argument, so every caller on this machine resolves the
+// identical path. `defaultRuntimeDir()` (lib/runtime/uv-bootstrap.mjs) is
+// the single source of truth for where the venv lives.
+
+export function doclingVenvPath() {
+  return path.join(defaultRuntimeDir(), '.venv');
 }
 
-export function detectDoclingSidecar({ cwd = process.cwd() } = {}) {
-  const venv = doclingVenvPath(cwd);
+export function detectDoclingSidecar() {
+  const venv = doclingVenvPath();
   const python = process.platform === 'win32'
     ? path.join(venv, 'Scripts', 'python.exe')
     : path.join(venv, 'bin', 'python');
@@ -79,7 +85,7 @@ export function detectDoclingRemote(env = process.env) {
 
 export function detectIngestPipeline({ cwd = process.cwd(), env = process.env, repoRoot = cwd } = {}) {
   const steps = {
-    docling: detectDoclingSidecar({ cwd }),
+    docling: detectDoclingSidecar(),
     nodeNative: detectNodeNativeDeps({ repoRoot }),
     whisper: detectWhisper(env),
     doclingRemote: detectDoclingRemote(env),

package/lib/init-unified.mjs

@@ -26,6 +26,7 @@ import { missingIgnorePatterns, isConstructPackageRepo } from './host-dispositio
 import { HOST_KEYS, displayNameToKey } from './platforms/capabilities.mjs';
 import { DOC_LANES, LANE_ORDER, DOC_PRESETS } from './init/doc-lanes.mjs';
 import { initWorkflow } from './workflow-state.mjs';
+import { isMainModule } from './roots.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -45,6 +46,7 @@ const withPostmortemsFlag = args.includes("--with-postmortems");
 const withArchitectureFlag = args.includes("--with-architecture");
 const withReadmeFlag = args.includes("--with-readme");
 const withDevcontainerFlag = args.includes("--devcontainer");
+const withSeedIndexFlag = args.includes("--seed-index");
 
 // Behavior flags
 const verbose = args.includes("--verbose") || args.includes("-v");
@@ -56,6 +58,10 @@ const skipInteractive = !interactive;
 // templates/ already exist (issue #97).
 const forceScaffold = args.includes("--force");
 
+// --no-beads skips tracker initialization entirely and marks beads as disabled
+// in the result. Use when the host environment cannot run bd (e.g. ephemeral CI).
+const noBeads = args.includes("--no-beads");
+
 // `bd init` is git-native and unconditionally commits its bootstrap; ADR-0027
 // §3 requires init to leave the host repo's commit history untouched unless the
 // user opts in. --commit-bootstrap keeps that commit; the default withholds it.
@@ -986,41 +992,49 @@ async function main() {
     skipped.push('.cx/construct_guide.md');
   }
 
-  // Auto-init beads
+  // Auto-init beads. Fail-closed: a tracker failure leaves the project in an
+  // inconsistent state (no hooks, no issue tracking) — better to stop early than
+  // silently proceed. Pass --no-beads to opt out for ephemeral/CI environments.
   const beadsMeta = path.join(target, ".beads", "metadata.json");
-  if (!fs.existsSync(beadsMeta) && !isToolRepo) {
+  let beadsReady = false;
+  if (noBeads) {
+    console.log('  ⚠️  Skipping task tracker initialization (--no-beads).');
+    skipped.push('.beads/ (--no-beads)');
+  } else if (!fs.existsSync(beadsMeta) && !isToolRepo) {
     console.log('');
     console.log('Initializing the task tracker (beads — local-first, git-synced, works offline)…');
     fs.mkdirSync(path.join(target, ".beads"), { recursive: true });
-    try {
-      const beads = initializeBeadsTracker(target, { commitBootstrap });
-      created.push(".beads/ (initialized)");
-      const prefixNote = beads?.prefix ? ` — issues prefixed \`${beads.prefix}-\`` : "";
-      console.log(`  ✓ Task tracker ready${prefixNote}. Run \`bd quickstart\` to start.`);
-      if (beads?.withheldCommit) {
-        console.log("    Bootstrap files left uncommitted (commit them yourself, or re-run with --commit-bootstrap).");
-      }
-    } catch (e) {
-      console.warn("⚠️  Beads init failed:", e.message);
+    const beads = initializeBeadsTracker(target, { commitBootstrap });
+    created.push(".beads/ (initialized)");
+    const prefixNote = beads?.prefix ? ` — issues prefixed \`${beads.prefix}-\`` : "";
+    console.log(`  ✓ Task tracker ready${prefixNote}. Run \`bd quickstart\` to start.`);
+    if (beads?.withheldCommit) {
+      console.log("    Bootstrap files left uncommitted (commit them yourself, or re-run with --commit-bootstrap).");
     }
     console.log('');
+    beadsReady = true;
+  } else if (fs.existsSync(beadsMeta)) {
+    beadsReady = true;
   }
 
   // Wire the project's git hooks to .beads/hooks so Construct's pre-commit
   // secret-scan and policy gates activate. Owned by init, not install (ADR-0027
   // §3): install must never mutate the cwd repo. Idempotent — no-op when
   // .beads/hooks/pre-commit is absent or a non-default custom path is set.
+  // Skipped when beads is disabled or was not successfully initialized.
 
-  try {
-    const { ensureGitHooksPath } = await import('./git-hooks-path.mjs');
-    const hooks = ensureGitHooksPath({ cwd: target });
-    if (hooks.status === 'set') {
-      created.push('git core.hooksPath → .beads/hooks');
-      if (!quiet) console.log(`  ✓ ${hooks.message}`);
-    } else if (hooks.status === 'warning' && !quiet) {
-      console.log(`  ⚠️  ${hooks.message}`);
-    }
-  } catch { /* git-hooks wiring is advisory; init proceeds */ }
+  if (beadsReady) {
+    try {
+      const { ensureGitHooksPath } = await import('./git-hooks-path.mjs');
+      const hooks = ensureGitHooksPath({ cwd: target });
+      if (hooks.status === 'set') {
+        created.push('git core.hooksPath → .beads/hooks');
+        if (!quiet) console.log(`  ✓ ${hooks.message}`);
+      } else if (hooks.status === 'warning' && !quiet) {
+        console.log(`  ⚠️  ${hooks.message}`);
+      }
+    } catch { /* git-hooks wiring is advisory; init proceeds */ }
+  }
 
   // Inject Construct's integration guidance into AGENTS.md and CLAUDE.md as a
   // versioned, hash-stamped marker block (ADR-0027 §2). Runs after bd init so
@@ -1154,22 +1168,25 @@ async function main() {
     }
   }
 
-  // Seed the vector index from the project's existing docs so the agent
-  // can compare new intake against established PRDs/RFCs/ADRs from day
-  // one. Best-effort: skipped silently when Postgres + embedding model
-  // aren't ready yet (DATABASE_URL unset, no ONNX cache). User can re-run
-  // `construct ingest` or `construct init` later to seed manually.
+  // Vector-index seeding (embedding the project's existing docs so the agent
+  // can compare new intake against established PRDs/RFCs/ADRs) is opt-in via
+  // --seed-index (construct-rf26.17): the default init path performs zero
+  // embedding work and never touches LanceDB, so a project that never uses
+  // semantic search never pays for the model cache or the index directory.
+  // `construct ingest` provisions both lazily on first real use.
+
+  if (withSeedIndexFlag) {
+    try {
+      const { syncFileStateToSql } = await import('./storage/sync.mjs');
+      const projectName = path.basename(target);
+      const seed = await syncFileStateToSql(target, { env: process.env, project: projectName });
+      if (seed?.status === 'ok' && (seed.documentsSynced || 0) > 0) {
+        console.log(`\n🔍 Indexed existing project material: ${seed.documentsSynced} doc(s), ${seed.embeddingsSynced || 0} embeddings.`);
+        console.log(`   The agent can now compare new intake (inbox/) against your existing PRDs, ADRs, and notes.`);
+      }
+    } catch { /* silent — corpus seeding is best-effort, not a setup blocker */ }
+  }
 
-  try {
-    const { syncFileStateToSql } = await import('./storage/sync.mjs');
-    const projectName = path.basename(target);
-    const seed = await syncFileStateToSql(target, { env: process.env, project: projectName });
-    if (seed?.status === 'ok' && (seed.documentsSynced || 0) > 0) {
-      console.log(`\n🔍 Indexed existing project material: ${seed.documentsSynced} doc(s), ${seed.embeddingsSynced || 0} embeddings.`);
-      console.log(`   The agent can now compare new intake (inbox/) against your existing PRDs, ADRs, and notes.`);
-    }
-  } catch { /* silent — corpus seeding is best-effort, not a setup blocker */ }
-  
   // ── Devcontainer recipe ────────────────────────────────────────────────
   if (withDevcontainerFlag) {
     const dcDir = path.join(target, '.devcontainer');
@@ -1252,7 +1269,7 @@ async function main() {
   }
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((error) => {
     console.error(`Error: ${error.message}`);
     process.exit(1);

package/lib/init-update.mjs

@@ -21,6 +21,7 @@ import {
   needsConstructGuideUpdate,
   writeConstructGuideProposal,
 } from "./init-update-guide.mjs";
+import { isMainModule } from './roots.mjs';
 
 const args = process.argv.slice(2);
 const dryRun = args.includes("--dry-run");
@@ -226,7 +227,7 @@ async function main() {
   console.log("To replace .cx/construct_guide.md with the shipped template: construct init:update --apply-guide");
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   main().catch((error) => {
     console.error(`Error: ${error.message}`);
     process.exit(1);

package/lib/install/legacy-global-cleanup.mjs

@@ -62,6 +62,30 @@ function stripClaudeSettings(homeDir, opts) {
   if (changed) writeJson(filePath, settings, { ...opts, label: '~/.claude/settings.json Construct entries' });
 }
 
+// construct-ranh moved Claude Code's MCP write path off ~/.claude/settings.json
+// (never read by the CLI for server definitions) to ~/.claude.json's top-level
+// `mcpServers`. A post-fix install registers MCP servers there, so this must be
+// stripped alongside settings.json for the memory/cass/construct-mcp bridges to
+// be fully removed.
+
+function stripClaudeUserConfig(homeDir, opts) {
+  const filePath = path.join(homeDir, '.claude.json');
+  const config = readJson(filePath);
+  if (!config || typeof config !== 'object') return;
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') return;
+
+  let changed = false;
+  for (const key of CONSTRUCT_MCP_KEYS) {
+    if (key in config.mcpServers) {
+      delete config.mcpServers[key];
+      changed = true;
+    }
+  }
+  if (Object.keys(config.mcpServers).length === 0) delete config.mcpServers;
+
+  if (changed) writeJson(filePath, config, { ...opts, label: '~/.claude.json Construct MCP entries' });
+}
+
 function stripOpenCode(homeDir, opts) {
   const filePath = path.join(homeDir, '.config', 'opencode', 'opencode.json');
   const config = readJson(filePath);
@@ -173,6 +197,7 @@ export function cleanupLegacyGlobalConstruct({ homeDir, dryRun = false } = {}) {
   });
 
   stripClaudeSettings(homeDir, opts);
+  stripClaudeUserConfig(homeDir, opts);
   stripOpenCode(homeDir, opts);
   stripVsCode(homeDir, opts);
   stripCodex(homeDir, opts);