@geraldmaron/construct 1.0.23 → 1.1.0

package/lib/embed/reconcile.mjs

@@ -26,8 +26,8 @@ export async function reconcileObservationEmbeddings(rootDir, { env = process.en
   const result = { checked: 0, reembedded: 0, model: null, skipped: null };
 
   try {
-    if (!(await client.isHealthy()) || !(await client.isPgvectorEnabled())) {
-      result.skipped = 'no-pg';
+    if (!(await client.isHealthy())) {
+      result.skipped = 'unhealthy';
       return result;
     }
 

package/lib/embed/roadmap.mjs

@@ -202,6 +202,12 @@ function normalizeStatus(raw) {
   return 'planned';
 }
 
+// Normalize the volatile "Last updated" stamp so two renders can be compared on
+// content alone.
+function stripTimestamp(markdown) {
+  return String(markdown || '').replace(/^> Last updated: .*$/m, '> Last updated:');
+}
+
 /**
  * Render entries back to roadmap markdown.
  */
@@ -324,7 +330,16 @@ export async function generateRoadmap({ targetPath, snapshot, roles }) {
   // Render
   const markdown = renderRoadmap(entries, { roles, sources });
 
-  // Write
+  // Skip the write when only the generated "Last updated" stamp would change —
+  // otherwise every render rewrites a tracked file with no semantic diff and
+  // leaves the working tree perpetually dirty. The timestamp then reflects when
+  // the roadmap content last actually moved, not when generation last ran.
+  let existingRaw = null;
+  try { existingRaw = readFileSync(roadmapPath, 'utf8'); } catch { existingRaw = null; }
+  if (existingRaw !== null && stripTimestamp(existingRaw) === stripTimestamp(markdown)) {
+    return { path: roadmapPath, updatedAt, itemCount: entries.length, isNew: false, unchanged: true };
+  }
+
   mkdirSync(join(targetPath, 'docs'), { recursive: true });
   writeFileSync(roadmapPath, markdown, 'utf8');
 

package/lib/engine/consolidate.mjs

@@ -8,9 +8,18 @@
  * wires in) — when no summariser is provided, the representative observation's
  * own summary is kept verbatim.
  *
+ * Supersede (the mem0/Letta decision layer): clustering alone left every
+ * near-duplicate live, so search returned N restatements of the same fact. The
+ * supersede pass keeps only the highest-salience member of a tight cluster live
+ * and archives the rest behind a `supersededBy` pointer — salience (the
+ * observation's confidence) decides the winner, the newest breaks a tie. The
+ * winner becomes the cluster representative, so the kept insight points at the
+ * most valuable member rather than the lexically-first one.
+ *
  * Outputs:
  *   .cx/observations/consolidated.json    list of insight clusters
  *   .cx/observations/archive/<id>.json    observations demoted to cold archive
+ *                                         (superseded members carry supersededBy)
  *
  * The pass is idempotent: re-running it on a stable corpus produces the same
  * cluster set. It is safe to schedule as a cron / launchd job, run in the
@@ -24,6 +33,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { cosineSimilarity } from '../storage/embeddings.mjs';
+import { detectContradiction } from './contradiction.mjs';
 
 const OBS_DIR = '.cx/observations';
 const ARCHIVE_DIR = '.cx/observations/archive';
@@ -35,6 +45,19 @@ const DEFAULTS = {
   similarityThreshold: 0.95,
   archiveAfterDays: 60,
   archiveBelowConfidence: 0.5,
+  // Supersede only collapses a member that is a true restatement of the winner,
+  // a stricter bar than the cluster-forming threshold: cluster-adjacent is not
+  // the same as duplicate.
+  supersedeDuplicates: true,
+  supersedeThreshold: 0.97,
+  // Contradiction sits in the band between same-subject and duplicate: low
+  // enough that the flipped claim drops cosine out of the duplicate range, high
+  // enough that the two are still about the same thing. The O(n²) scan is
+  // bounded by contradictionScanMax so a large store degrades to a no-op rather
+  // than a stall.
+  detectContradictions: true,
+  contradictionMinSimilarity: 0.75,
+  contradictionScanMax: 1500,
   maxStored: 5000,
   // Archive retention: keep at most this many archived files, and delete
   // anything older than archiveRetainDays. Both bounds apply.
@@ -56,12 +79,27 @@ function readObservation(rootDir, id) {
   return readJsonOrEmpty(filePath, null);
 }
 
-function archiveObservation(rootDir, id) {
+function archiveObservation(rootDir, id, supersededBy = null, reason = null) {
   const src = path.join(rootDir, OBS_DIR, `${id}.json`);
   if (!fs.existsSync(src)) return false;
   const archiveDir = path.join(rootDir, ARCHIVE_DIR);
   fs.mkdirSync(archiveDir, { recursive: true });
   const dest = path.join(archiveDir, `${id}.json`);
+
+  // A superseded member records what replaced it and why before leaving the
+  // live store, so the archive stays auditable and a future undo knows both the
+  // winner and whether it was a restatement or a contradiction.
+  if (supersededBy) {
+    const record = readJsonOrEmpty(src, null);
+    if (record) {
+      record.supersededBy = supersededBy;
+      record.supersededAt = new Date().toISOString();
+      if (reason) record.supersededReason = reason;
+      fs.writeFileSync(dest, JSON.stringify(record, null, 2) + '\n');
+      fs.unlinkSync(src);
+      return true;
+    }
+  }
   fs.renameSync(src, dest);
   return true;
 }
@@ -71,6 +109,77 @@ function daysAgo(dateStr) {
   return (Date.now() - new Date(dateStr).getTime()) / (24 * 60 * 60 * 1000);
 }
 
+// The winner of a near-duplicate cluster is the member worth keeping live:
+// highest salience (confidence) first, then the most recent restatement, then a
+// stable id tiebreak so the choice is deterministic across runs.
+function rankForSupersede(a, b) {
+  const conf = (b.confidence || 0) - (a.confidence || 0);
+  if (conf !== 0) return conf;
+  const at = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+  const bt = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+  if (bt !== at) return bt - at;
+  return String(a.id).localeCompare(String(b.id));
+}
+
+// A contradiction resolves the opposite way from a restatement: the world
+// changed, so the most recent claim wins regardless of salience; salience and a
+// stable id only break a same-timestamp tie.
+function rankByRecency(a, b) {
+  const at = a.createdAt ? new Date(a.createdAt).getTime() : 0;
+  const bt = b.createdAt ? new Date(b.createdAt).getTime() : 0;
+  if (bt !== at) return bt - at;
+  const conf = (b.confidence || 0) - (a.confidence || 0);
+  if (conf !== 0) return conf;
+  return String(a.id).localeCompare(String(b.id));
+}
+
+/**
+ * Scan a record set for same-subject contradictions and archive the older of
+ * each contradicting pair behind a supersededBy pointer with reason
+ * 'contradiction'. Mutates nothing; returns the loser ids and the supersede
+ * entries. Bounded by scanMax — above it the O(n²) scan is skipped wholesale so
+ * a large store never stalls consolidation.
+ */
+async function scanContradictions(rootDir, records, settings) {
+  const superseded = [];
+  const losers = new Set();
+  if (records.length > settings.contradictionScanMax) {
+    return { superseded, losers, skipped: true };
+  }
+
+  const ordered = [...records].sort(rankByRecency);
+  for (let i = 0; i < ordered.length; i++) {
+    const newer = ordered[i];
+    if (losers.has(newer.id)) continue;
+    for (let j = i + 1; j < ordered.length; j++) {
+      const older = ordered[j];
+      if (losers.has(older.id)) continue;
+      if (!newer.embedding?.length || !older.embedding?.length) continue;
+
+      const sim = cosineSimilarity(newer.embedding, older.embedding);
+      const sameSubject = sim >= settings.contradictionMinSimilarity && sim < settings.supersedeThreshold;
+      if (!sameSubject) continue;
+
+      // The heuristic runs first and for free; the optional judge is consulted
+      // only on its misses (the value-swap case it abstains on). Awaiting covers
+      // both a sync local judge and a future async one.
+      const heuristic = detectContradiction(newer.summary, older.summary);
+      let contradicts = heuristic.contradicts;
+      if (!contradicts && settings.contradictionJudge?.judge) {
+        try { contradicts = !!((await settings.contradictionJudge.judge(newer, older))?.contradicts); }
+        catch { contradicts = false; }
+      }
+      if (!contradicts) continue;
+
+      if (archiveObservation(rootDir, older.id, newer.id, 'contradiction')) {
+        losers.add(older.id);
+        superseded.push({ id: older.id, supersededBy: newer.id, reason: 'contradiction' });
+      }
+    }
+  }
+  return { superseded, losers, skipped: false };
+}
+
 /**
  * Greedy single-pass clustering. Each observation is added to the existing
  * cluster whose centroid has highest cosine similarity, provided that
@@ -145,9 +254,15 @@ async function buildSummary(cluster, summariser) {
  * @param {number} [opts.similarityThreshold=0.95]
  * @param {number} [opts.archiveAfterDays=60]
  * @param {number} [opts.archiveBelowConfidence=0.5]
+ * @param {boolean} [opts.supersedeDuplicates=true] - archive tight restatements, keeping the highest-salience member live
+ * @param {number} [opts.supersedeThreshold=0.97] - cosine bar a member must clear against the winner to be superseded
+ * @param {boolean} [opts.detectContradictions=true] - archive the older of a same-subject contradicting pair (newest wins)
+ * @param {number} [opts.contradictionMinSimilarity=0.75] - cosine floor for two observations to count as same-subject
+ * @param {number} [opts.contradictionScanMax=1500] - skip the O(n²) contradiction scan above this many live records
+ * @param {object} [opts.contradictionJudge] - optional plugin with `judge(a, b) -> { contradicts }` for the value-swap case the heuristic misses
  * @param {number} [opts.maxStored=5000]
  * @param {object} [opts.summariser] - Compressor-shaped plugin
- * @returns {Promise<{ clustersBefore: number, clusters: number, archived: string[], stored: number }>}
+ * @returns {Promise<{ clustersBefore: number, clusters: number, archived: string[], superseded: Array<{id: string, supersededBy: string, reason: string}>, contradictionScanSkipped: boolean, stored: number }>}
  */
 export async function consolidate(rootDir, opts = {}) {
   const settings = { ...DEFAULTS, ...opts };
@@ -177,7 +292,7 @@ export async function consolidate(rootDir, opts = {}) {
   const clustersBefore = records.length;
 
   const archived = [];
-  const liveRecords = records.filter((r) => {
+  let liveRecords = records.filter((r) => {
     const old = daysAgo(r.createdAt) > settings.archiveAfterDays;
     const lowConfidence = r.confidence < settings.archiveBelowConfidence;
     if (old && lowConfidence) {
@@ -187,8 +302,47 @@ export async function consolidate(rootDir, opts = {}) {
     return true;
   });
 
+  const superseded = [];
+
+  // Contradiction runs before clustering: a flipped claim sits below the
+  // duplicate threshold, so it would never cluster with what it contradicts and
+  // both stale and current statements would stay live. The older loser leaves
+  // the set so it is not clustered or returned by search.
+  let contradictionScanSkipped = false;
+  if (settings.detectContradictions) {
+    const result = await scanContradictions(rootDir, liveRecords, settings);
+    contradictionScanSkipped = result.skipped;
+    for (const id of result.losers) archived.push(id);
+    superseded.push(...result.superseded);
+    if (result.losers.size > 0) {
+      liveRecords = liveRecords.filter((r) => !result.losers.has(r.id));
+    }
+  }
+
   const clusters = greedyCluster(liveRecords, settings.similarityThreshold);
 
+  // Supersede tight restatements: rank each multi-member cluster by salience so
+  // the winner leads (it becomes the representative), then archive any member
+  // that duplicates the winner closely enough to be the same fact.
+  if (settings.supersedeDuplicates) {
+    for (const cluster of clusters) {
+      if (cluster.members.length < 2) continue;
+      cluster.members.sort(rankForSupersede);
+      const winner = cluster.members[0];
+      cluster.supersededIds = [];
+      for (const loser of cluster.members.slice(1)) {
+        const tight = winner.embedding?.length && loser.embedding?.length &&
+          cosineSimilarity(winner.embedding, loser.embedding) >= settings.supersedeThreshold;
+        if (!tight) continue;
+        if (archiveObservation(rootDir, loser.id, winner.id, 'restatement')) {
+          archived.push(loser.id);
+          superseded.push({ id: loser.id, supersededBy: winner.id, reason: 'restatement' });
+          cluster.supersededIds.push(loser.id);
+        }
+      }
+    }
+  }
+
   const consolidated = [];
   for (const cluster of clusters) {
     const representative = cluster.members[0];
@@ -206,6 +360,7 @@ export async function consolidate(rootDir, opts = {}) {
       category: representative.category,
       tags: [...new Set(cluster.members.flatMap((m) => m.tags || []))].slice(0, 10),
       memberIds: cluster.members.map((m) => m.id),
+      supersededIds: cluster.supersededIds || [],
       avgConfidence:
         cluster.members.reduce((acc, m) => acc + (m.confidence || 0), 0) /
         Math.max(cluster.members.length, 1),
@@ -247,6 +402,8 @@ export async function consolidate(rootDir, opts = {}) {
     clustersBefore,
     clusters: consolidated.length,
     archived,
+    superseded,
+    contradictionScanSkipped,
     archivePruned,
     stored: consolidated.length,
   };

package/lib/engine/contradiction-judge.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/engine/contradiction-judge.mjs — optional LLM second opinion for the
+ * consolidation contradiction pass.
+ *
+ * The negation-polarity heuristic (lib/engine/contradiction.mjs) catches a
+ * flipped claim but abstains on a value swap with no negation cue — "auth uses
+ * RS256" vs "auth uses HS256" share every word yet disagree. Resolving that
+ * needs to know the two values are mutually exclusive, which is semantic
+ * judgment. This factory builds the judge consolidation consults only when the
+ * heuristic says "no".
+ *
+ * Offline-first: the judge is backed by a local Ollama model and the factory
+ * returns null when Ollama is not running or has no model, so consolidation
+ * degrades to heuristic-only with no provider and no key required. The status
+ * probe and the runner are injectable so the parse logic is testable without a
+ * live model.
+ */
+
+import { checkOllamaStatus, testModel } from '../ollama-manager.mjs';
+
+function buildPrompt(a, b) {
+  const textA = (a?.summary || a?.content || '').slice(0, 400);
+  const textB = (b?.summary || b?.content || '').slice(0, 400);
+  return [
+    'Two short notes describe the same subject. Decide whether they directly',
+    'contradict — assert mutually exclusive facts (e.g. different algorithms,',
+    'opposite states, incompatible values). A restatement or an added detail is',
+    'NOT a contradiction. Answer with only YES or NO.',
+    '',
+    `Note A: ${textA}`,
+    `Note B: ${textB}`,
+    'Answer:',
+  ].join('\n');
+}
+
+function parseVerdict(response) {
+  const match = String(response || '').toLowerCase().match(/\b(yes|no)\b/);
+  return { contradicts: !!match && match[1] === 'yes' };
+}
+
+/**
+ * Build a contradiction judge, or null when no local model is available.
+ *
+ * @param {object} [opts]
+ * @param {() => {running?: boolean, models?: Array<{name?: string, model?: string}>}} [opts.statusFn]
+ * @param {(model: string, prompt: string) => {success?: boolean, response?: string}} [opts.runFn]
+ * @param {string} [opts.model] explicit model override (else env, else first available)
+ * @returns {{judge: (a: object, b: object) => {contradicts: boolean}} | null}
+ */
+export function createContradictionJudge({ statusFn = checkOllamaStatus, runFn = testModel, model } = {}) {
+  const status = statusFn();
+  if (!status?.running || !status.models?.length) return null;
+
+  const chosen = model || process.env.CONSTRUCT_CONTRADICTION_JUDGE_MODEL ||
+    status.models[0]?.name || status.models[0]?.model;
+  if (!chosen) return null;
+
+  return {
+    judge(a, b) {
+      try {
+        const result = runFn(chosen, buildPrompt(a, b));
+        if (!result?.success) return { contradicts: false };
+        return parseVerdict(result.response);
+      } catch {
+        return { contradicts: false };
+      }
+    },
+  };
+}
+
+export const __testing = { buildPrompt, parseVerdict };

package/lib/engine/contradiction.mjs

@@ -0,0 +1,74 @@
+/**
+ * lib/engine/contradiction.mjs — deterministic "do these two observations disagree?"
+ *
+ * Restatement supersede (construct-xh6c) collapses near-duplicates that say the
+ * same thing. The open case is contradiction: two observations about the same
+ * subject that make opposing claims ("auth is supported" vs "auth is not
+ * supported"). A contradiction inherently shares most of its tokens but flips
+ * one — so its cosine sits *below* the duplicate threshold, which is why the
+ * consolidation scan looks in a suspicious band rather than inside a cluster.
+ *
+ * The signal this detects without an LLM is negation polarity: same claim
+ * words, opposite assertion. A value swap with no negation cue ("RS256" vs
+ * "HS256") is not caught here — that needs semantic judgment and is left to an
+ * optional `contradictionJudge` plugin wired into the consolidation pass.
+ */
+
+// Cues that flip an assertion. Apostrophes are stripped during tokenization, so
+// contracted forms appear here without them (don't -> dont, isn't -> isnt).
+const NEGATION_CUES = new Set([
+  'not', 'no', 'never', 'none', 'neither', 'nor', 'without', 'cannot',
+  'dont', 'doesnt', 'didnt', 'isnt', 'arent', 'wasnt', 'werent', 'wont',
+  'cant', 'couldnt', 'shouldnt', 'wouldnt', 'fails', 'failing', 'failed',
+  'unsupported', 'disabled', 'broken', 'missing', 'absent',
+]);
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/['’]/g, '')
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 0;
+  let inter = 0;
+  for (const t of a) if (b.has(t)) inter += 1;
+  return inter / (a.size + b.size - inter);
+}
+
+/**
+ * Decide whether two observation texts contradict on negation polarity.
+ *
+ * Contradiction = the claim words (tokens minus negation cues) overlap heavily
+ * AND the two carry a different number of negation cues — one asserts, the other
+ * denies the same thing.
+ *
+ * @param {string} textA
+ * @param {string} textB
+ * @param {{coreSimilarity?: number}} [opts] coreSimilarity: Jaccard floor on the
+ *   cue-stripped token sets (default 0.6); below it the two are about different
+ *   subjects, not a flipped claim.
+ * @returns {{contradicts: boolean, coreSimilarity: number, negDelta: number, reason: string}}
+ */
+export function detectContradiction(textA, textB, opts = {}) {
+  const floor = opts.coreSimilarity ?? 0.6;
+  const tokA = tokenize(textA);
+  const tokB = tokenize(textB);
+  const negA = tokA.filter((t) => NEGATION_CUES.has(t)).length;
+  const negB = tokB.filter((t) => NEGATION_CUES.has(t)).length;
+  const coreA = new Set(tokA.filter((t) => !NEGATION_CUES.has(t)));
+  const coreB = new Set(tokB.filter((t) => !NEGATION_CUES.has(t)));
+
+  const coreSimilarity = jaccard(coreA, coreB);
+  const negDelta = negA - negB;
+  const contradicts =
+    coreA.size > 0 && coreB.size > 0 &&
+    coreSimilarity >= floor &&
+    negDelta !== 0;
+
+  return { contradicts, coreSimilarity, negDelta, reason: 'negation-polarity' };
+}
+
+export const __testing = { tokenize, jaccard, NEGATION_CUES };

package/lib/hooks/config-protection.mjs

@@ -21,7 +21,7 @@
  *
  * @lifecycle PreToolUse
  * @matcher  Write|Edit|MultiEdit
- * @exits 0 = pass | 2 = block tool call
+ * @exits 0 = always, emits audit event on violation
  */
 import { readFileSync } from 'fs';
 import { execFileSync } from 'child_process';
@@ -90,10 +90,10 @@ async function emitEvent(type, category, summary) {
 const base = filePath.split('/').pop();
 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`
+    `[config-protection] The code quality rules are protected. You are editing a tracked config file. Ensure you are not weakening rules just to bypass errors.\nFile: ${filePath}\n`
   );
-  await emitEvent('config.protection.violation', 'code-quality-config', `Blocked edit to code-quality-config: ${filePath}`);
-  process.exit(2);
+  await emitEvent('config.protection.violation', 'code-quality-config', `Edited code-quality-config: ${filePath}`);
+  process.exit(0);
 }
 
 if (META_FILES.some(r => r.test(filePath))) {

package/lib/hooks/session-reflect.mjs

@@ -22,7 +22,11 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-const HARD_BUDGET_MS = 500;
+// 500ms keeps the per-turn Stop-hook tax small (ADR-0029): reflection is
+// best-effort and a LanceDB write that overruns the budget is left to the
+// embed daemon's reconcile to backfill. CONSTRUCT_REFLECT_BUDGET_MS raises the
+// ceiling where the write must complete deterministically (slow disks, tests).
+const HARD_BUDGET_MS = Number(process.env.CONSTRUCT_REFLECT_BUDGET_MS) || 500;
 const startedAt = Date.now();
 
 // Opt-out before any heavy work — the env check is cheaper than parsing input.

package/lib/host-capabilities.mjs

@@ -118,6 +118,36 @@ function detectCopilotAvailability(homeDir = os.homedir()) {
   return { hasFiles };
 }
 
+/**
+ * Detects active host-native sessions (GitHub, Anthropic, etc.).
+ * Returns a list of authenticated provider families.
+ */
+export function detectActiveSessions() {
+  const active = [];
+  
+  // GitHub Copilot check
+  try {
+    const ghStatus = execSync("gh auth status", { stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
+    if (ghStatus.includes("Logged in to github.com")) {
+      active.push("github-copilot");
+    }
+  } catch { /* not logged in or gh cli missing */ }
+  
+  // Anthropic / Claude Code check
+  const home = os.homedir();
+  const claudeSettings = path.join(home, ".claude", "settings.json");
+  try {
+    if (fs.existsSync(claudeSettings)) {
+      const settings = JSON.parse(fs.readFileSync(claudeSettings, "utf8"));
+      if (settings?.primaryModel || settings?.mcpServers) {
+        active.push("anthropic");
+      }
+    }
+  } catch { /* invalid or missing config */ }
+  
+  return active;
+}
+
 // `capability` is the honest, normalized functional classification per host:
 //   full-native      — the host runs a multi-specialist chain itself (native
 //                       dispatch or config-driven agents): Claude Code, OpenCode.

package/lib/ingest/docling-remote.mjs

@@ -0,0 +1,90 @@
+/**
+ * lib/ingest/docling-remote.mjs — opt-in remote document conversion via Docling Serve.
+ *
+ * The `docling-remote` ingest strategy (ADR-0036) sends the document to a
+ * user-configured Docling Serve API instead of the offline Python sidecar —
+ * for zero-local-footprint installs that accept remote conversion. The endpoint
+ * contract is Docling Serve's `POST /v1/convert/file` (multipart field `files`,
+ * markdown at `document.md_content`, per docling-serve docs/usage.md).
+ *
+ * The serve URL must be configured (DOCLING_SERVE_URL); a missing URL fails loud —
+ * the user explicitly chose remote, so silently degrading to the sidecar would
+ * hide the misconfiguration. The call is bounded by the same timeout knob as the
+ * sidecar (CONSTRUCT_DOCLING_TIMEOUT_MS, default 600s).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 600_000;
+
+export function resolveDoclingServeUrl(env = process.env) {
+  const raw = (env.DOCLING_SERVE_URL || '').trim();
+  return raw ? raw.replace(/\/+$/, '') : null;
+}
+
+/**
+ * Convert one local file through Docling Serve. Returns the shared extractor
+ * contract ({ text, extractionMethod, characters, truncated, droppedInfo }).
+ * Throws (fail-loud) on missing URL, HTTP error, non-success status, or timeout.
+ */
+export async function extractViaDoclingRemote({ filePath, maxChars = null, env = process.env, timeoutMs = null } = {}) {
+  const baseUrl = resolveDoclingServeUrl(env);
+  if (!baseUrl) {
+    const err = new Error(
+      "ingest.strategy is 'docling-remote' but DOCLING_SERVE_URL is not set. " +
+      "Point it at a Docling Serve instance, or switch ingest.strategy back to 'adapter' (offline sidecar).",
+    );
+    err.code = 'DOCLING_REMOTE_UNCONFIGURED';
+    throw err;
+  }
+
+  const budget = timeoutMs ?? (Number(env.CONSTRUCT_DOCLING_TIMEOUT_MS) || DEFAULT_TIMEOUT_MS);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), budget);
+  try {
+    const form = new FormData();
+    const bytes = fs.readFileSync(filePath);
+    form.append('files', new Blob([bytes]), path.basename(filePath));
+
+    const res = await fetch(`${baseUrl}/v1/convert/file`, {
+      method: 'POST',
+      body: form,
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const err = new Error(`Docling Serve returned HTTP ${res.status} for ${path.basename(filePath)}`);
+      err.code = 'DOCLING_REMOTE_HTTP';
+      throw err;
+    }
+    const data = await res.json();
+    const status = data?.status;
+    const markdown = data?.document?.md_content;
+    if ((status && status !== 'success' && status !== 'partial_success') || typeof markdown !== 'string') {
+      const detail = Array.isArray(data?.errors) && data.errors.length ? `: ${JSON.stringify(data.errors).slice(0, 200)}` : '';
+      const err = new Error(`Docling Serve conversion ${status || 'returned no markdown'}${detail}`);
+      err.code = 'DOCLING_REMOTE_FAILED';
+      throw err;
+    }
+
+    const truncated = maxChars != null && markdown.length > maxChars;
+    const text = truncated ? markdown.slice(0, maxChars) : markdown;
+    return {
+      text,
+      extractionMethod: 'docling-remote',
+      characters: text.length,
+      truncated,
+      droppedInfo: status === 'partial_success'
+        ? [{ type: 'partial-conversion', count: 1, reason: 'Docling Serve reported partial_success', recoverable: true }]
+        : [],
+    };
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      const e = new Error(`Docling Serve conversion timed out after ${budget}ms`);
+      e.code = 'DOCLING_REMOTE_TIMEOUT';
+      throw e;
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/lib/ingest/strategy.mjs

@@ -17,7 +17,7 @@ import { resolveSetting } from '../config/project-config.mjs';
 import { resolveEmbeddedModel } from '../embedded-contract/model-resolve.mjs';
 import { resolveExecution } from '../embedded-contract/execution.mjs';
 
-export const INGEST_STRATEGIES = ['adapter', 'provider'];
+export const INGEST_STRATEGIES = ['adapter', 'provider', 'docling-remote'];
 export const INGEST_FALLBACKS = ['none', 'provider', 'adapter'];
 
 // Orchestration is a second, independent axis from extraction (adapter|provider):

package/lib/init-unified.mjs

@@ -23,6 +23,7 @@ import { multiSelect } from './tty-prompts.mjs';
 import { execSync, spawnSync } from 'node:child_process';
 import { stageProjectAdapters } from './install/stage-project.mjs';
 import { missingIgnorePatterns, isConstructPackageRepo } from './host-disposition.mjs';
+import { HOST_KEYS, displayNameToKey } from './platforms/capabilities.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -63,8 +64,7 @@ const commitBootstrap = args.includes("--commit-bootstrap");
 // one, --all-hosts writes every adapter set. Copilot (`.github/`) is opt-in only
 // — never written by detection — so init never touches a repo's CI directory
 // without --with-copilot.
-const HOST_FLAG_KEYS = ["claude", "codex", "opencode", "vscode", "cursor", "copilot"];
-const withHostFlags = new Set(HOST_FLAG_KEYS.filter((k) => args.includes(`--with-${k}`)));
+const withHostFlags = new Set(HOST_KEYS.filter((k) => args.includes(`--with-${k}`)));
 const allHosts = args.includes("--all-hosts");
 
 // Active profile selector. `--profile=<id>` writes the field into the
@@ -809,23 +809,19 @@ async function resolveAdapterHosts() {
   const detected = new Set();
   try {
     const { detectHostCapabilities } = await import('./host-capabilities.mjs');
-    const nameToKey = {
-      'Claude Code': 'claude',
-      'OpenCode': 'opencode',
-      'Codex': 'codex',
-      'VS Code': 'vscode',
-      'Cursor': 'cursor',
-      'Copilot': 'copilot',
-    };
+    const nameToKey = displayNameToKey();
     for (const cap of detectHostCapabilities()) {
       if (cap.availability === 'installed' && nameToKey[cap.host]) detected.add(nameToKey[cap.host]);
     }
   } catch { /* detection is advisory; fall back to flags + baseline */ }
   detected.delete('copilot');
   const selected = new Set([...detected, ...withHostFlags]);
-  if (selected.has('vscode')) selected.add('claude');
-  if (selected.size === 0) selected.add('claude');
-  return HOST_FLAG_KEYS.filter((k) => selected.has(k));
+
+  // An empty selection writes no adapters: nothing detected and no --with-<host>
+  // flag means the user is guided by docs to run sync with an explicit host,
+  // rather than scaffolding a sidecar they did not ask for.
+
+  return HOST_KEYS.filter((k) => selected.has(k));
 }
 
 async function main() {