@geraldmaron/construct 1.2.1 → 1.2.3

package/lib/document-ingest.mjs

@@ -137,19 +137,29 @@ function collectInputFiles(inputPath, { maxDepth = 10 } = {}) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+// Ingest writes a markdown rendering of the source, preserving the source name
+// for provenance (report.pdf → report.pdf.md). A source already in markdown keeps
+// its name unchanged so it never gains a second extension (_template.md →
+// _template.md, not _template.md.md).
+
+function markdownOutputName(sourcePath) {
+  const base = basename(sourcePath);
+  return /\.md$/i.test(base) ? base : `${base}.md`;
+}
+
 function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
   if (outputPath) return normalizeOutputPath(outputPath, cwd);
   if (target === 'sibling') {
-    return join(dirname(sourcePath), `${basename(sourcePath)}.md`);
+    return join(dirname(sourcePath), markdownOutputName(sourcePath));
   }
   // knowledge/<subdir> targets land in .cx/knowledge/<subdir>/
   if (target.startsWith('knowledge/')) {
     const sub = target.slice('knowledge/'.length);
     const resolvedDir = normalizeOutputPath(`${KNOWLEDGE_ROOT}/${sub}`, cwd);
-    return join(resolvedDir, `${basename(sourcePath)}.md`);
+    return join(resolvedDir, markdownOutputName(sourcePath));
   }
   const resolvedDir = normalizeOutputPath(outputDir || DEFAULT_TARGET_DIR, cwd);
-  return join(resolvedDir, `${basename(sourcePath)}.md`);
+  return join(resolvedDir, markdownOutputName(sourcePath));
 }
 
 // The high-fidelity (docling) path provisions a Python venv and downloads ML

package/lib/efficiency.mjs

@@ -6,13 +6,14 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 const HIGH_BYTES_THRESHOLD = 750_000;
 const HIGH_REPEATED_RATIO = 0.4;
 const HIGH_LARGE_READ_COUNT = 3;
 
 export function readEfficiencyLog(homeDir) {
-  const filePath = join(homeDir, '.cx', 'session-efficiency.json');
+  const filePath = join(doctorRoot(homeDir), 'session-efficiency.json');
   if (!existsSync(filePath)) return null;
   try {
     return JSON.parse(readFileSync(filePath, 'utf8'));

package/lib/embed/approval-queue.mjs

@@ -10,7 +10,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
+
+import { doctorRoot } from '../config/xdg.mjs';
 
 export class ApprovalQueue {
   #items = new Map();   // id → ApprovalItem
@@ -171,6 +172,6 @@ export class ApprovalQueue {
   }
 
   static defaultPersistPath() {
-    return path.join(os.homedir(), '.cx', 'approval-queue.jsonl');
+    return path.join(doctorRoot(), 'approval-queue.jsonl');
   }
 }

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');

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/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,31 +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.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 });
-    dirs.push(projectInbox);
-  }
-
-  if (config.includeDocsIntake) {
-    const docsIntake = join(rootDir, DOCS_INTAKE_SUBDIR);
-    if (existsSync(docsIntake)) dirs.push(docsIntake);
-  }
+  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;
@@ -177,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).
@@ -198,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'); }
@@ -269,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/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'));

package/lib/env-config.mjs

@@ -1,13 +1,16 @@
 /**
  * lib/env-config.mjs — Read and write Construct environment configuration files.
  *
- * Provides helpers to load ~/.cx/env, merge with process.env, and persist
- * key/value pairs back to disk. Backs setup, model-router, and the MCP
- * server when they resolve API keys and model overrides without leaking secrets.
+ * Provides helpers to load the user config.env (XDG config dir) and a project
+ * .env, merge them with process.env, and persist key/value pairs back to disk.
+ * Project .env wins over user config.env, which wins over shell exports. Backs
+ * setup, model-router, and the MCP server when they resolve API keys and model
+ * overrides without leaking secrets.
  */
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { configDir } from './config/xdg.mjs';
 import { API_KEY_CREDENTIALS } from './providers/credential-catalog.mjs';
 import { extractOpRef } from './providers/secret-resolver.mjs';
 
@@ -26,7 +29,7 @@ export function parseEnvFile(filePath) {
 }
 
 export function getUserConfigDir(homeDir = os.homedir()) {
-  return path.join(homeDir, '.construct');
+  return configDir(homeDir);
 }
 
 export function getUserEnvPath(homeDir = os.homedir()) {
@@ -109,31 +112,50 @@ function preferInjectedCredential(envValue, 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));
-  const fileEnv = { ...rootEnv, ...userEnv };
+
+  // Most-specific config wins: project .env overrides user config.env, which
+  // overrides shell exports. A repo's local .env is closer to the work than a
+  // machine-wide default, so it takes the file-tier precedence.
+  const fileEnv = { ...userEnv, ...rootEnv };
+  const userEnvPath = getUserEnvPath(homeDir);
 
   if (warn) {
+    // Every key that both files define to a different value is a real shadow:
+    // project .env silently wins, so surface it rather than gating on a
+    // hardcoded credential subset.
+    for (const key of Object.keys(rootEnv)) {
+      if (!(key in userEnv)) continue;
+      if (rootEnv[key] === userEnv[key]) continue;
+      if (preferInjectedCredential(rootEnv[key], userEnv[key])) continue;
+      process.stderr.write(
+        `[construct] WARNING: ${key} is set in both project .env (${rootEnv[key].slice(0, 6)}…) ` +
+        `and ${userEnvPath} (${userEnv[key].slice(0, 6)}…). ` +
+        `Project .env wins. To silence: remove the key from one file.\n`,
+      );
+    }
+
     for (const key of Object.keys(env)) {
       if (ENV_SHADOW_IGNORE.has(key)) continue;
       if (!ENV_SHADOW_WARN.has(key)) continue;
       // Only warn when process.env has a non-empty competing value.
       // An empty-string env var (e.g. Claude for Desktop clears ANTHROPIC_API_KEY
-      // so its internal auth is used instead) is not a real conflict — config.env wins
-      // silently and no user action is needed.
+      // so its internal auth is used instead) is not a real conflict — the file
+      // value wins 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)}…). ` +
-          `config.env will be used. To silence: unset the shell variable or ` +
-          `update ~/.construct/config.env to match.\n`,
+          `differs from the config file value (${fileEnv[key].slice(0, 6)}…). ` +
+          `The config file will be used. To silence: unset the shell variable or ` +
+          `update the config file to match.\n`,
         );
       }
     }
   }
 
-  // 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.
+  // process.env is the base; .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 };

package/lib/features.mjs

@@ -9,13 +9,14 @@ import { readFileSync, existsSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { loadPluginRegistry } from './plugin-registry.mjs';
+import { configDir } from './config/xdg.mjs';
 
 function getHomeDir(overrides = {}) {
   return overrides.homeDir ?? homedir();
 }
 
 function getFeaturesFile(overrides = {}) {
-  return overrides.featuresFile ?? join(getHomeDir(overrides), '.construct', 'features.json');
+  return overrides.featuresFile ?? join(configDir(getHomeDir(overrides)), 'features.json');
 }
 
 function getClaudeSettingsPath(overrides = {}) {
@@ -145,10 +146,10 @@ function getProjectMcpPaths(overrides = {}) {
  * Load Claude.ai server-side managed MCP IDs.
  * These are integrations connected through Claude.ai's web interface
  * (e.g., Notion, Google Drive) that aren't discoverable from local config.
- * Users declare them via ~/.construct/claude-ai-mcps.json: { "mcps": ["notion", "slack"] }
+ * Users declare them via claude-ai-mcps.json in the XDG config dir: { "mcps": ["notion", "slack"] }
  */
 function getClaudeAiManagedMcps(overrides = {}) {
-  const p = overrides.claudeAiMcpsPath ?? join(getHomeDir(overrides), '.construct', 'claude-ai-mcps.json');
+  const p = overrides.claudeAiMcpsPath ?? join(configDir(getHomeDir(overrides)), 'claude-ai-mcps.json');
   if (!existsSync(p)) return [];
   try {
     const data = JSON.parse(readFileSync(p, 'utf8'));