@geraldmaron/construct 1.2.1 → 1.2.2

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

package/lib/health-check.mjs

@@ -11,6 +11,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { extractOpRef, hasAnySecret, hasSecret } from './providers/secret-resolver.mjs';
+import { configDir } from './config/xdg.mjs';
 
 const isWindows = os.platform() === 'win32';
 
@@ -110,8 +111,8 @@ export async function checkPrerequisites(options = {}) {
   });
   
   // Check user config
-  const hasUserConfig = existsSync(path.join(homeDir || os.homedir(), '.construct', 'config.env')) ||
-                        existsSync(path.join(homeDir || os.homedir(), '.construct'));
+  const hasUserConfig = existsSync(path.join(configDir(homeDir || os.homedir()), 'config.env')) ||
+                        existsSync(configDir(homeDir || os.homedir()));
   checks.push({
     name: 'User config',
     required: false,
@@ -176,7 +177,7 @@ function readCredentialRaw(varName, homeDir) {
   for (const envPath of [
     path.join(process.cwd(), '.env'),
     path.join(homeDir, '.env'),
-    path.join(homeDir, '.construct', 'config.env'),
+    path.join(configDir(homeDir), 'config.env'),
   ]) {
     if (!existsSync(envPath)) continue;
     try {
@@ -222,7 +223,7 @@ export function describeCredentialPresence(varName, { homeDir = os.homedir(), cw
   for (const envPath of [
     path.join(cwd, '.env'),
     path.join(homeDir, '.env'),
-    path.join(homeDir, '.construct', 'config.env'),
+    path.join(configDir(homeDir), 'config.env'),
   ]) {
     if (!existsSync(envPath)) continue;
     try {
@@ -295,7 +296,7 @@ const CREDENTIAL_VARS = [
 ];
 
 /**
- * Link discovered credential references into ~/.construct/config.env without
+ * Link discovered credential references into the XDG config dir config.env without
  * invoking `op read`. Plain values and op:// refs are persisted as found.
  * @param {Object} options
  * @param {string} options.homeDir
@@ -342,7 +343,7 @@ export function detectCredentials(options = {}) {
   // GitHub Copilot: a device-flow credential (Construct's own store or the shared
   // github-copilot store) is the usable signal; the VS Code extension and the
   // copilot CLI are softer fallbacks.
-  const copilotAuthStore = existsSync(path.join(homeDir, '.construct', 'auth', 'github-copilot.json')) ||
+  const copilotAuthStore = existsSync(path.join(configDir(homeDir), 'auth', 'github-copilot.json')) ||
     existsSync(path.join(homeDir, '.config', 'github-copilot', 'apps.json')) ||
     existsSync(path.join(homeDir, '.config', 'github-copilot', 'hosts.json'));
   const copilotDir = path.join(homeDir, '.vscode', 'extensions');

package/lib/hook-health.mjs

@@ -15,8 +15,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
+import { configDir, doctorRoot } from './config/xdg.mjs';
 
-const CX_DIR = path.join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const HOOK_HEALTH_DIR = path.join(CX_DIR, 'hook-health');
 const HEALTH_CHECK_INTERVAL_MS = 60 * 1000; // 1 minute
 
@@ -266,12 +267,12 @@ async function checkSingleHook(hookId, config, hookPath) {
 }
 
 function findHookPath(hookName) {
-  // Check standard locations
+  // The user hook symlink lives in the XDG config dir; the project-local
+  // .construct/lib and the npm-global install are fallbacks.
   const possiblePaths = [
-    path.join(homedir(), '.construct', 'lib', 'hooks', `${hookName}.mjs`),
+    path.join(configDir(), 'lib', 'hooks', `${hookName}.mjs`),
     path.join(process.cwd(), '.construct', 'lib', 'hooks', `${hookName}.mjs`),
     path.join(homedir(), '.npm-global', 'lib', 'node_modules', '@geraldmaron/construct', 'lib', 'hooks', `${hookName}.mjs`),
-    // Try to find from PATH
   ];
   
   for (const p of possiblePaths) {

package/lib/hooks/_lib/log.mjs

@@ -5,7 +5,7 @@
  * a regression in the hook harness or a malformed payload does not block the
  * user. The trade-off is silent failure: until now, hook regressions were
  * invisible. This helper writes a single JSONL entry per failure to
- * ~/.cx/hook-failures.jsonl so `construct doctor` can surface the top
+ * <doctorRoot>/hook-failures.jsonl so `construct doctor` can surface the top
  * failing hooks without changing the fail-open behavior of any individual
  * hook.
  *
@@ -21,9 +21,10 @@
 
 import { appendFileSync, statSync, renameSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 
-const LOG_DIR = join(homedir(), '.cx');
+import { doctorRoot } from '../../config/xdg.mjs';
+
+const LOG_DIR = doctorRoot();
 const LOG_PATH = join(LOG_DIR, 'hook-failures.jsonl');
 const LOG_ROTATED_PATH = join(LOG_DIR, 'hook-failures.1.jsonl');
 const LOG_MAX_BYTES = 1_048_576; // 1 MiB

package/lib/hooks/_lib/output-mode.mjs

@@ -29,6 +29,7 @@ import { homedir } from 'node:os';
 
 import { resolveSetting, loadProjectConfig } from '../../config/project-config.mjs';
 import { HOOK_OUTPUT_MODES } from '../../config/schema.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 
 export { HOOK_OUTPUT_MODES };
 
@@ -93,7 +94,7 @@ export function writeHookContext({ payload, mode, homeDir = homedir(), stdout =
   if (mode === 'stdout') { stdout.write(payload); return 'stdout'; }
   if (mode === 'stderr') { stderr.write(payload); return 'stderr'; }
   try {
-    const dir = join(homeDir, '.cx');
+    const dir = doctorRoot(homeDir);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(join(dir, 'session-start-last.log'), payload);
   } catch { /* best effort — never block the session on a debug-log write */ }

package/lib/hooks/agent-tracker.mjs

@@ -24,10 +24,10 @@
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { appendBounded } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
 import { emit as emitRoleEvent } from '../roles/event-bus.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 import { logHookFailure } from './_lib/log.mjs';
 
 let input = {};
@@ -74,8 +74,7 @@ if (errorIndicators.some(ind => lowerResult.includes(ind))) {
 
 // Record agent invocation
 try {
-  const home = homedir();
-  const cxDir = join(home, '.cx');
+  const cxDir = doctorRoot();
   mkdirSync(cxDir, { recursive: true });
   
   // Update last-agent files for coordination (shared + per-agent)
@@ -188,7 +187,7 @@ try {
       // role-pending stays at user scope (a handoff might span projects),
       // but each entry gets a projectId tag so a reader can attribute it.
 
-      const pendingPath = join(homedir(), '.cx', 'role-pending.jsonl');
+      const pendingPath = join(doctorRoot(), 'role-pending.jsonl');
       const { resolveProjectScope } = await import('../project-root.mjs');
       const scope = resolveProjectScope();
       const bdMatch = /\b(construct-[a-z0-9]+)\b/i.exec(resultText) || [];

package/lib/hooks/audit-reads.mjs

@@ -33,13 +33,13 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, resolve, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { logHookFailure } from './_lib/log.mjs';
 import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
 import { flushReadTrackerDeltas, recordReadDelta } from '../read-tracker-store.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 // audit-reads.jsonl is PROJECT-SCOPED — reads happen in a specific project,
 // not across the user's whole machine. resolveProjectScopedPath returns
 // <project>/.cx/audit-reads.jsonl when the hook fires from inside a

package/lib/hooks/audit-trail.mjs

@@ -36,12 +36,12 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, resolve } from 'node:path';
-import { homedir } from 'node:os';
 import { appendAuditRecord } from '../audit-trail.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
 import { logHookFailure } from './_lib/log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const AUDIT_FILE = resolveProjectScopedPath('audit-trail.jsonl', { ensureDir: false });
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 const MUTATING_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'Bash']);

package/lib/hooks/bash-output-logger.mjs

@@ -21,12 +21,12 @@
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { appendBounded } from '../logging/rotate.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const SIZE_THRESHOLD_CHARS = 4000;
-const LOG_DIR = join(homedir(), '.cx', 'bash-logs');
-const WARN_FLAGS = join(homedir(), '.cx', 'warn-flags.txt');
+const LOG_DIR = join(doctorRoot(), 'bash-logs');
+const WARN_FLAGS = join(doctorRoot(), 'warn-flags.txt');
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }

package/lib/hooks/brand-prose-lint.mjs

@@ -33,6 +33,6 @@ if (!result.violations.length) process.exit(0);
 const output = formatBrandViolations([result]);
 process.stderr.write(`${output}\n`);
 process.stderr.write(
-  '\nBrand policy blocked this edit (marketing voice, retired fonts, or Construct/cli naming). See docs/reference/branding.md and docs/STYLE.md.\n',
+  '\nBrand policy blocked this edit (marketing voice, retired fonts, or Construct/cli naming). See docs/guides/reference/branding.md and docs/STYLE.md.\n',
 );
 process.exit(2);

package/lib/hooks/ci-status-check.mjs

@@ -27,11 +27,12 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { execSync, spawn } from 'node:child_process';
-import { homedir } from 'node:os';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const CACHE_PATH = join(homedir(), '.cx', 'ci-status-cache.json');
+import { doctorRoot } from '../config/xdg.mjs';
+
+const CACHE_PATH = join(doctorRoot(), 'ci-status-cache.json');
 const CACHE_TTL_MS = 60_000;
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REFRESHER = resolve(HERE, '..', '..', 'scripts', 'refresh-ci-status.mjs');

package/lib/hooks/context-watch.mjs

@@ -33,10 +33,10 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { resolveContextWindow } from '../telemetry/model-pricing-catalog.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const COST_LOG = join(CX_DIR, 'session-cost.jsonl');
 const EFFICIENCY = join(CX_DIR, 'session-efficiency.json');
 const STATE = join(CX_DIR, 'context-watch-state.json');