@geraldmaron/construct 1.2.0 → 1.2.2

package/lib/embed/cli.mjs

@@ -21,6 +21,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { configDir } from '../config/xdg.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const STATE_FILE = 'embed-daemon.json';
 const LOG_FILE   = 'embed-daemon.log';
@@ -30,7 +32,7 @@ const LOG_FILE   = 'embed-daemon.log';
 // ---------------------------------------------------------------------------
 
 function runtimeDir(homeDir = os.homedir()) {
-  return path.join(homeDir, '.cx', 'runtime');
+  return path.join(doctorRoot(homeDir), 'runtime');
 }
 
 function statePath(homeDir = os.homedir()) {
@@ -273,8 +275,8 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   const { config } = parseArgs(args);
   const configPath = config
     ? path.resolve(config)
-    : fs.existsSync(path.join(os.homedir(), '.construct', 'embed.yaml'))
-      ? path.join(os.homedir(), '.construct', 'embed.yaml')
+    : fs.existsSync(path.join(configDir(), 'embed.yaml'))
+      ? path.join(configDir(), 'embed.yaml')
       : null;
 
   const workerPath = _workerPath ?? path.join(rootDir, 'lib', 'embed', 'worker.mjs');
@@ -374,7 +376,7 @@ async function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
   process.stdout.write(`  pid:        ${state.pid}\n`);
   process.stdout.write(`  config:     ${state.configPath}\n`);
   process.stdout.write(`  rootDir:    ${rootDir}\n`);
-  process.stdout.write(`  inbox:      ${path.join(rootDir, '.cx', 'inbox')}\n`);
+  process.stdout.write(`  inbox:      ${path.join(rootDir, 'inbox')}\n`);
   process.stdout.write(`  started at: ${state.startedAt}\n`);
   process.stdout.write(`  log:        ${logPath(homeDir)}\n`);
 }
@@ -387,7 +389,7 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   const { config } = parseArgs(args);
   const configPath = config
     ? path.resolve(config)
-    : path.join(os.homedir(), '.construct', 'embed.yaml');
+    : path.join(configDir(), 'embed.yaml');
 
   const { loadEmbedConfig, EMPTY_CONFIG } = await import('./config.mjs');
   const { SnapshotEngine, renderMarkdown } = await import('./snapshot.mjs');
@@ -401,7 +403,8 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   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/config.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/embed/config.mjs — embed mode configuration schema and loader.
  *
- * Reads embed.yaml from ~/.construct/embed.yaml (or a supplied path) and validates
+ * Reads embed.yaml from the XDG config dir (or a supplied path) and validates
  * the file against the expected schema. Returns a parsed, normalized config object.
  *
  * Schema:
@@ -55,6 +55,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { configDir, stateDir } from '../config/xdg.mjs';
 
 const DEFAULTS = {
   snapshot: { intervalMs: 300_000, maxItems: 100 },
@@ -74,13 +75,13 @@ const DEFAULTS = {
  *     ref: github.com/org/project-y
  *     path: /Users/user/Github/project-y      # both — prefer local, fall back to remote
  *   - type: workspace                         # always present as fallback
- *     path: ~/.construct/workspace
+ *     path: <XDG_STATE_HOME>/construct/workspace
  *
  * roles:
  *   primary: product-manager    # shapes embed analysis lens
  *   secondary: architect        # persistent background concern
  */
-export const DEFAULT_WORKSPACE_PATH = path.join(os.homedir(), '.construct', 'workspace');
+export const DEFAULT_WORKSPACE_PATH = path.join(stateDir(), 'workspace');
 
 export const WORKSPACE_DOCS_LANES = ['adrs', 'prds', 'memos', 'notes', 'intake'];
 
@@ -99,7 +100,7 @@ export const DEFAULT_OPERATING_PROFILE = {
   },
   focalResources: [
     { type: 'plan', path: 'plan.md', purpose: 'active implementation plan' },
-    { type: 'architecture', path: 'docs/concepts/architecture.md', purpose: 'system architecture and operating model' },
+    { type: 'architecture', path: 'docs/guides/concepts/architecture.md', purpose: 'system architecture and operating model' },
     { type: 'knowledge', path: '.cx/knowledge', purpose: 'typed project knowledge and ingested evidence' },
     { type: 'runtime', path: '.cx/roadmap.md', purpose: 'generated roadmap output' },
   ],
@@ -351,5 +352,5 @@ export function parseEmbedYaml(text) {
 }
 
 export function defaultEmbedConfigPath() {
-  return path.join(os.homedir(), '.construct', 'embed.yaml');
+  return path.join(configDir(), 'embed.yaml');
 }

package/lib/embed/daemon.mjs

@@ -13,7 +13,7 @@
  *   - approval-expiry   — expires stale approval queue items
  *   - eval-dataset-sync — syncs scored traces to telemetry dataset items
  *   - prompt-regression-check — detects low-quality score clusters per promptHash
- *   - inbox-watcher     — ingests new files from .cx/inbox/ + CX_INBOX_DIRS into
+ *   - inbox-watcher     — ingests new files from inbox/ + CX_INBOX_DIRS into
  *                         observations (agnostic: specs, ADRs, meeting notes, etc.)
  *   - roadmap           — cross-references open items + observations → .cx/roadmap.md
  *
@@ -48,6 +48,7 @@ import { emitEmbedNotification, notifySlack } from './notifications.mjs';
 import { intentToCategory } from './providers/slack.mjs';
 import { runTelemetrySetup } from '../telemetry/setup.mjs';
 import { emitTraceEvent, newTraceId, newSpanId } from '../worker/trace.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 /**
  * Log a non-fatal error to stderr. Use instead of empty catch {} blocks
@@ -121,8 +122,8 @@ function resolveDaemonStatePath(env = process.env) {
 
 // ─── Self-repair helpers ────────────────────────────────────────────────────
 
-const LOCK_PATH = join(homedir(), '.cx', 'sync.lock');
-const DAEMON_STATE_PATH = join(homedir(), '.cx', 'runtime', 'embed-daemon.json');
+const LOCK_PATH = join(doctorRoot(), 'sync.lock');
+const DAEMON_STATE_PATH = join(doctorRoot(), 'runtime', 'embed-daemon.json');
 
 /**
  * Run in-process health checks and fix what can be fixed.
@@ -562,7 +563,7 @@ export class EmbedDaemon {
       'daemon-log-rotation',
       60_000,
       async () => {
-        const logPath = join(homedir(), '.cx', 'runtime', 'embed-daemon.log');
+        const logPath = join(doctorRoot(), 'runtime', 'embed-daemon.log');
         const capMb = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_MB) || 50;
         const maxBytes = Math.floor(capMb * 1024 * 1024);
         const maxSegments = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_SEGMENTS) || 5;
@@ -729,7 +730,7 @@ this.#scheduler.register(
     // Every 2 min — scan configured inbox dirs for new files, ingest them, and
     // record observations. Agnostic to content: specs, ADRs, meeting notes,
     // internal docs, PDFs, Office files — anything on the local filesystem.
-    // Dirs: <rootDir>/.cx/inbox/ always; CX_INBOX_DIRS env for extra paths.
+    // Dirs: <rootDir>/inbox/ always; CX_INBOX_DIRS env for extra paths.
     this.#scheduler.register(
       'inbox-watcher',
       2 * 60_000,

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-live-watcher.mjs

@@ -3,7 +3,7 @@
  *
  * Registers a node:fs.watch listener on each inbox directory and triggers
  * `InboxWatcher.poll()` shortly after filesystem activity settles, so files
- * dropped into `.cx/inbox/` flow through ingest + the review queue in
+ * dropped into `inbox/` flow through ingest + the review queue in
  * seconds rather than waiting for the scheduler's next interval.
  *
  * Two limits keep this stable across platforms:

package/lib/embed/inbox.mjs

@@ -6,10 +6,14 @@
  * handles specs, ADRs, meeting notes, internal docs, research, PDFs,
  * Office files, plain text, code, or any format supported by document-extract.
  *
- * Watch dirs (in priority order):
- *   1. CX_INBOX_DIRS env var — colon-separated absolute paths
- *   2. <rootDir>/.cx/inbox/  — per-project drop folder (always included)
- *   3. <rootDir>/docs/intake/ — project intake drop zone when docs init is used
+ * Watch dirs:
+ *   1. <rootDir>/inbox/      — the canonical project-root drop zone (always watched)
+ *   2. CX_INBOX_DIRS env var + intakePolicy.additionalDirs — opt-in extra paths
+ *
+ * Atomic handoff (ADR-0045 §C): writers stage a file under `inbox/.staging/`
+ * and atomically rename it into `inbox/`. The watcher ignores `.staging/` and
+ * dotfiles, and skips any top-level file whose size is still changing between
+ * two stats, so a partially-written drop is never consumed mid-write.
  *
  * State tracking:
  *   <rootDir>/.cx/runtime/inbox-state.json — maps filePath → processedAt
@@ -23,7 +27,6 @@
 
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { homedir } from 'node:os';
 import { isExtractableDocumentPath, AUDIO_VIDEO_EXTS } from '../document-extract.mjs';
 import { ingestDocuments } from '../document-ingest.mjs';
 import { addObservation } from '../observation-store.mjs';
@@ -36,29 +39,29 @@ import { loadIntakeConfig, INTAKE_DEFAULT_MAX_DEPTH } from '../intake/intake-con
 import { loadManifest, recordFile, hasFile, sha256Of, MANIFEST_REL_PATH } from '../intake/manifest.mjs';
 import { gatherAttribution } from '../intake/attribution.mjs';
 import { acquirePollLock, releasePollLock } from '../intake/poll-lock.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const STATE_FILE = '.cx/runtime/inbox-state.json';
-const DEFAULT_INBOX_SUBDIR = '.cx/inbox';
-const DOCS_INTAKE_SUBDIR = 'docs/intake';
-const ARCHETYPE_INBOX_SUBDIR = 'inbox';
+const ROOT_INBOX_SUBDIR = 'inbox';
+const STAGING_SUBDIR = '.staging';
 const MAX_FILE_SIZE_BYTES = 50 * 1024 * 1024; // 50 MB hard cap
 const STALE_STATE_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 // ─── Extraction-warning helpers ───────────────────────────────────────────────
 
 function extractionWarningsLog() {
-  return join(homedir(), '.cx', 'intake', 'extraction-warnings.jsonl');
+  return join(doctorRoot(), 'intake', 'extraction-warnings.jsonl');
 }
 
 function needsAsrDir() {
-  return join(homedir(), '.cx', 'intake', 'needs-asr');
+  return join(doctorRoot(), 'intake', 'needs-asr');
 }
 
 function writeExtractionWarning({ sourcePath, droppedInfo }) {
   if (!droppedInfo?.length) return;
   const logPath = extractionWarningsLog();
   try {
-    mkdirSync(join(homedir(), '.cx', 'intake'), { recursive: true });
+    mkdirSync(join(doctorRoot(), 'intake'), { recursive: true });
     const line = JSON.stringify({ ts: new Date().toISOString(), sourcePath, droppedInfo }) + '\n';
     appendFileSync(logPath, line);
   } catch { /* non-fatal */ }
@@ -139,35 +142,20 @@ function writeState(rootDir, state) {
 
 /**
  * Resolve inbox watch directories from the persisted intake-config.
- * Always includes <rootDir>/.cx/inbox/ (created on first use) when the
- * config has includeProjectInbox: true (default).
- * Includes <rootDir>/docs/intake/ when it exists and includeDocsIntake is true.
- * `parentDirs` from intake-config.json plus CX_INBOX_DIRS env var add extras.
+ * The canonical <rootDir>/inbox/ is always watched (ADR-0045 §C). `parentDirs`
+ * from intake-config plus CX_INBOX_DIRS env var add opt-in extras.
+ *
+ * The canonical inbox gets a `.staging/` subdir on resolution so writers have
+ * a stable place to assemble a file before the atomic rename into `inbox/`.
  */
 export function resolveInboxDirs(rootDir, env = process.env) {
   const config = loadIntakeConfig(rootDir, env);
   const dirs = [];
 
-  if (config.includeProjectInbox) {
-    const projectInbox = join(rootDir, DEFAULT_INBOX_SUBDIR);
-    mkdirSync(projectInbox, { recursive: true });
-    dirs.push(projectInbox);
-  }
-
-  if (config.includeDocsIntake) {
-    const docsIntake = join(rootDir, DOCS_INTAKE_SUBDIR);
-    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);
-  }
+  const rootInbox = join(rootDir, ROOT_INBOX_SUBDIR);
+  mkdirSync(rootInbox, { recursive: true });
+  mkdirSync(join(rootInbox, STAGING_SUBDIR), { recursive: true });
+  dirs.push(rootInbox);
 
   for (const candidate of config.parentDirs) {
     if (!candidate) continue;
@@ -181,6 +169,20 @@ export function resolveInboxDirs(rootDir, env = process.env) {
 
 // ─── File scanning ────────────────────────────────────────────────────────────
 
+// Dotfiles and dot-directories — including the `inbox/.staging/` assembly
+// area writers rename out of — are skipped wholesale, so a staged file is
+// never visible to the scanner until it lands at a top-level name.
+
+function isStableFile(full) {
+  try {
+    const a = statSync(full);
+    const b = statSync(full);
+    return a.size === b.size && a.mtimeMs === b.mtimeMs ? a : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Walk `dir` up to `maxDepth` subdirectory levels.
  * maxDepth=0 → only files in `dir` itself (no subdirs).
@@ -202,11 +204,15 @@ function scanDir(dir, maxDepth = INTAKE_DEFAULT_MAX_DEPTH) {
         }
         if (!entry.isFile()) continue;
         if (!isExtractableDocumentPath(full)) continue;
-        try {
-          const st = statSync(full);
-          if (st.size === 0 || st.size > MAX_FILE_SIZE_BYTES) continue;
-          results.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
-        } catch (err) { process.stderr.write('[inbox.mjs] scan-file-stat: ' + (err?.message ?? String(err)) + '\n'); }
+
+        // Stability backstop for writers that drop in place instead of staging:
+        // a file whose size/mtime is still moving between two stats is mid-write,
+        // so leave it for the next poll once it settles.
+
+        const st = isStableFile(full);
+        if (!st) continue;
+        if (st.size === 0 || st.size > MAX_FILE_SIZE_BYTES) continue;
+        results.push({ path: full, size: st.size, mtimeMs: st.mtimeMs });
       }
     }
   } catch (err) { process.stderr.write('[inbox.mjs] scan-dir: ' + (err?.message ?? String(err)) + '\n'); }
@@ -273,7 +279,12 @@ function maybePromoteToDocs(rootDir, { sourcePath, extractedText }) {
   if (!existsSync(laneDir)) return null;
 
   const sourceName = sourcePath.split('/').pop() ?? 'intake-doc';
-  const targetPath = nextAvailablePath(join(laneDir, `${sourceName}.md`));
+
+  // A source already in markdown keeps its name; others gain a .md rendering
+  // suffix. Without the guard an intake item named foo.md promotes to foo.md.md.
+
+  const docFileName = /\.md$/i.test(sourceName) ? sourceName : `${sourceName}.md`;
+  const targetPath = nextAvailablePath(join(laneDir, docFileName));
   const title = sourceName.replace(/\.[^.]+$/, '').replace(/[-_]+/g, ' ').trim() || 'Promoted intake document';
   const markdown = [
     '# ' + title,

package/lib/embed/intake-metrics.mjs

@@ -16,7 +16,8 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+
+import { doctorRoot } from '../config/xdg.mjs';
 
 /**
  * Scan an intake directory and return file metadata.
@@ -125,7 +126,7 @@ export function computeIntakeMetrics({ rootDir } = {}) {
   // — Metrics from recommendation store
   let recStats = { active: 0, dismissed: 0, total: 0 };
   try {
-    const recIndexPath = join(homedir(), '.cx', 'intake', 'recommendations-index.json');
+    const recIndexPath = join(doctorRoot(), 'intake', 'recommendations-index.json');
     if (existsSync(recIndexPath)) {
       const index = JSON.parse(readFileSync(recIndexPath, 'utf8'));
       const entries = Object.values(index);

package/lib/embed/reconcile.mjs

@@ -12,7 +12,7 @@
  * with no changes re-embeds nothing.
  *
  * Reconciliation-on-sync is preferred over a fixed-interval polling cron (see
- * docs/research/vector-search-best-practices.md): the pass runs where Construct
+ * docs/notes/research/vector-search-best-practices.md): the pass runs where Construct
  * already touches storage (the model-change re-embed, the storage CLI), keys
  * idempotency on a content hash, and re-embeds on model change.
  */

package/lib/embed/semantic.mjs

@@ -21,9 +21,10 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
 
-const CACHE_DIR = join(homedir(), '.cx', 'cache', 'embeddings');
+import { doctorRoot } from '../config/xdg.mjs';
+
+const CACHE_DIR = join(doctorRoot(), 'cache', 'embeddings');
 const INDEX_FILE = join(CACHE_DIR, 'index.json');
 const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
 const DIMENSIONS = 384;

package/lib/embed/supervision.mjs

@@ -21,13 +21,15 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+import { stateDir, doctorRoot } from '../config/xdg.mjs';
+
 const HOME = os.homedir();
 const PLATFORM = process.platform;
 const NODE_BIN = process.execPath;
 
 // Path to the construct bin — we use absolute path so launchd/systemd can find it.
 function constructBin() {
-  const local = path.join(HOME, '.construct', 'bin', 'construct');
+  const local = path.join(stateDir(HOME), 'bin', 'construct');
   if (fs.existsSync(local)) return local;
   const result = spawnSync('which', ['construct'], { encoding: 'utf8' });
   return result.status === 0 ? result.stdout.trim() : 'construct';
@@ -195,7 +197,7 @@ function windowsStatus() {
 // ── Public API ──────────────────────────────────────────────────────────────
 
 function logPath() {
-  return path.join(HOME, '.cx', 'runtime', 'embed-daemon.log');
+  return path.join(doctorRoot(), 'runtime', 'embed-daemon.log');
 }
 
 /**

package/lib/embed/worker.mjs

@@ -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/engine/registry.mjs

@@ -3,7 +3,7 @@
  *
  * Resolution order (last-write wins):
  *   1. Built-in defaults (lib/engine/defaults.mjs)
- *   2. ~/.construct/plugins.json   (operator-level overrides)
+ *   2. plugins.json in the XDG config dir   (operator-level overrides)
  *   3. <project>/.cx/plugins.json  (repo-level overrides)
  *   4. CONSTRUCT_PLUGIN_<LAYER> environment variables (one-off overrides)
  *
@@ -20,11 +20,11 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, isAbsolute, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { LAYERS, assertContract } from './contracts.mjs';
 import { loadDefaults } from './defaults.mjs';
+import { configDir } from '../config/xdg.mjs';
 
 const ENV_PREFIX = 'CONSTRUCT_PLUGIN_';
 
@@ -43,7 +43,7 @@ function readJsonIfExists(path) {
 function gatherOverrides(rootDir) {
   const overrides = [];
 
-  const userConfig = readJsonIfExists(join(homedir(), '.construct', 'plugins.json'));
+  const userConfig = readJsonIfExists(join(configDir(), 'plugins.json'));
   if (userConfig?.plugins) overrides.push(...userConfig.plugins);
 
   const projectConfig = readJsonIfExists(join(rootDir, '.cx', 'plugins.json'));