@geraldmaron/construct 1.2.0 → 1.2.2

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/export-branding.mjs

@@ -0,0 +1,32 @@
+/**
+ * lib/export-branding.mjs — one honest branding contract for distribution exports.
+ */
+
+import { BRAND_CAPABLE_FORMATS, PLAIN_OUTPUT_FORMATS } from './artifact-manifest.mjs';
+
+export const EXPORT_BRANDING_CAPABILITIES = Object.freeze({
+  pdf: { capable: true, mechanism: 'typst-template', asset: 'construct-pdf.typ' },
+  html: { capable: true, mechanism: 'pandoc-template', asset: 'construct-web.html' },
+  deck: { capable: true, mechanism: 'pandoc-template', asset: 'construct-deck.html' },
+  pptx: { capable: true, mechanism: 'native-pptx', asset: 'pptxgenjs' },
+  docx: { capable: true, mechanism: 'reference-doc', asset: 'construct-reference.docx' },
+  doc: { capable: true, mechanism: 'docx-reference-via-libreoffice', asset: 'construct-reference.docx' },
+  rtf: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  odt: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  epub: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  tex: { capable: true, mechanism: 'pandoc-writer', asset: null },
+  txt: { capable: false, mechanism: 'plain-source', asset: null },
+  md: { capable: false, mechanism: 'plain-source', asset: null },
+  mdx: { capable: false, mechanism: 'plain-source', asset: null },
+});
+
+export function resolveExportBranding(format, requested = 'construct') {
+  const capability = EXPORT_BRANDING_CAPABILITIES[format];
+  if (!capability) return { requested, applied: 'none', capable: false, reason: 'unsupported format' };
+  if (!BRAND_CAPABLE_FORMATS.includes(format) || PLAIN_OUTPUT_FORMATS.includes(format)) {
+    return { requested, applied: 'none', capable: false, reason: 'format has no styling surface' };
+  }
+  if (requested === 'plain') return { requested, applied: 'plain', capable: true, mechanism: capability.mechanism, reason: 'explicit opt-out' };
+  return { requested: 'construct', applied: 'construct', capable: true, mechanism: capability.mechanism, asset: capability.asset, reason: 'default policy' };
+}
+

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

package/lib/hooks/context-window-recovery.mjs

@@ -12,9 +12,9 @@
  * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
 import { readContextState, writeContextState } from '../context-state.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const CONTEXT_LIMIT_PATTERNS = [
   'context window', 'maximum context', 'too long', 'prompt is too long',
@@ -23,7 +23,7 @@ const CONTEXT_LIMIT_PATTERNS = [
 ];
 
 const COOLDOWN_MS = 10 * 60 * 1000;
-const STATE_PATH = join(homedir(), '.cx', 'context-recovery.json');
+const STATE_PATH = join(doctorRoot(), 'context-recovery.json');
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
@@ -42,7 +42,7 @@ try {
   if (now - (state.lastTriggeredAt || 0) < COOLDOWN_MS) process.exit(0);
 } catch { /* first run */ }
 
-const cxDir = join(homedir(), '.cx');
+const cxDir = doctorRoot();
 try { mkdirSync(cxDir, { recursive: true }); } catch { /* exists */ }
 try { writeFileSync(STATE_PATH, JSON.stringify({ lastTriggeredAt: now })); } catch { /* best effort */ }
 
@@ -50,7 +50,7 @@ const cwd = input?.cwd || process.cwd();
 
 let existingContext = '';
 try {
-  const state = readContextState(cwd) || readContextState(homedir());
+  const state = readContextState(cwd) || readContextState(doctorRoot());
   if (state?.markdown) existingContext = String(state.markdown).slice(0, 800);
   else if (state?.context) existingContext = String(state.context).slice(0, 800);
 } catch { /* none */ }
@@ -66,7 +66,7 @@ const recoveryContext = [
 const projectCxDir = join(cwd, '.cx');
 try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
 try { writeContextState(cwd, { source: 'context-window-recovery', recoveryContext, format: 'json' }, { markdown: recoveryContext }); } catch { /* best effort */ }
-try { writeContextState(homedir(), { source: 'context-window-recovery', recoveryContext, format: 'json' }, { markdown: recoveryContext }); } catch { /* best effort */ }
+try { writeContextState(doctorRoot(), { source: 'context-window-recovery', recoveryContext, format: 'json' }, { markdown: recoveryContext }); } catch { /* best effort */ }
 
 process.stdout.write([
   ``,

package/lib/hooks/dep-audit.mjs

@@ -15,10 +15,10 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { homedir } from 'node:os';
 import { join, dirname, basename } from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { logHookFailure } from './_lib/log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
 if (!filePath) process.exit(0);
@@ -31,7 +31,7 @@ if (!MANIFESTS.has(file)) process.exit(0);
 if (/node_modules|\/dist\/|\/build\/|\/\.git\//.test(filePath)) process.exit(0);
 
 const projectDir = dirname(filePath);
-const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
+const warnFlagsPath = join(doctorRoot(), 'warn-flags.txt');
 
 function appendWarn(msg) {
   try { appendBounded('bash-warn-flags', warnFlagsPath, msg + '\n'); }

package/lib/hooks/doc-coupling-check.mjs

@@ -19,10 +19,11 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 
-const STATE_PATH = join(homedir(), '.cx', 'doc-coupling.json');
+import { doctorRoot } from '../config/xdg.mjs';
+
+const STATE_PATH = join(doctorRoot(), 'doc-coupling.json');
 const CODE_RE = /^(lib|bin|src|app)\/.*\.(?:m?js|jsx?|tsx?|cjs)$/;
 const DOC_RE = /^(?:CHANGELOG\.md|docs\/.+\.md|\.cx\/context\.(?:md|json))$/;
 const THRESHOLDS = [3, 5, 10];

package/lib/hooks/edit-accumulator.mjs

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { logHookFailure } from './_lib/log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const TS_EXTS = new Set(['.ts','.tsx','.js','.mjs','.jsx','.cjs']);
 const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
@@ -28,7 +29,7 @@ if (!filePath) process.exit(0);
 
 const ext = path.extname(filePath);
 const home = homedir();
-const countPath = path.join(home, '.cx', 'files-changed-count.txt');
+const countPath = path.join(doctorRoot(home), 'files-changed-count.txt');
 
 // Always increment the total files-changed counter for notify
 try {
@@ -41,7 +42,7 @@ try {
 // Only accumulate TS/JS files for typecheck
 if (!TS_EXTS.has(ext)) process.exit(0);
 
-const tcPath = path.join(home, '.cx', 'pending-typecheck.txt');
+const tcPath = path.join(doctorRoot(home), 'pending-typecheck.txt');
 try {
   const existing = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
   if (!existing.includes(filePath)) {

package/lib/hooks/edit-guard.mjs

@@ -14,10 +14,10 @@
 import { readFileSync, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, resolve } from 'path';
-import { homedir } from 'os';
 import { logHookFailure } from './_lib/log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const HASH_STORE = join(homedir(), '.cx', 'file-hashes.json');
+const HASH_STORE = join(doctorRoot(), 'file-hashes.json');
 
 function storedHash(absPath) {
   try {
@@ -48,7 +48,7 @@ function absOf(p) { return p.startsWith('/') ? p : resolve(cwd, p); }
 
 if ((toolName === 'Edit' || toolName === 'Write' || toolName === 'MultiEdit') && process.env.CONSTRUCT_ROLES !== 'off') {
   try {
-    const lastAgentPath = join(homedir(), '.cx', 'last-agent.json');
+    const lastAgentPath = join(doctorRoot(), 'last-agent.json');
     if (existsSync(lastAgentPath)) {
       const last = JSON.parse(readFileSync(lastAgentPath, 'utf8'));
       const lastTs = last?.ts ? Date.parse(last.ts) : 0;

package/lib/hooks/guard-bash.mjs

@@ -13,9 +13,9 @@
  */
 import { createInterface } from 'readline';
 import { readFileSync, existsSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
 import { logHookFailure } from './_lib/log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const BLOCK_PATTERNS = [
   {
@@ -99,7 +99,7 @@ for (const { pattern, reason } of WARN_PATTERNS) {
 
 if (process.env.CONSTRUCT_ROLES !== 'off') {
   try {
-    const cxDir = join(homedir(), '.cx');
+    const cxDir = doctorRoot();
     const id = String(process.env.CONSTRUCT_AGENT_ID || '').replace(/^cx-/, '');
     let agentData = null;
 

package/lib/hooks/model-fallback.mjs

@@ -32,8 +32,9 @@ import {
   writeProviderCooldown,
 } from '../model-router.mjs';
 import { readHookInput } from './_lib/input.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const cooldownPath = join(homedir(), '.cx', 'provider-cooldowns.json');
+const cooldownPath = join(doctorRoot(), 'provider-cooldowns.json');
 const envPath = join(process.cwd(), '.env');
 
 const input = readHookInput();

package/lib/hooks/policy-engine.mjs

@@ -24,6 +24,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { doctorRoot } from '../config/xdg.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')) || {}; } catch { process.exit(0); }
@@ -55,7 +56,7 @@ if (hookEvent === 'PreToolUse') {
   const READ_TOOLS = new Set(['Read', 'Grep', 'Glob', 'LS', 'NotebookRead']);
   const BLOCKED_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'TodoWrite']);
 
-  const stateDir = join(home, '.cx');
+  const stateDir = doctorRoot(home);
   const statePath = join(stateDir, 'bootstrap-state.json');
   const sessionId = input.session_id || input.sessionId || 'default';
 
@@ -147,7 +148,7 @@ if (hookEvent === 'Stop') {
 
   const branch = safeExec('git branch --show-current');
   const isFeatureBranch = branch && branch !== 'main' && branch !== 'dev' && branch !== 'master';
-  const filesChangedPath = join(home, '.cx', 'files-changed-count.txt');
+  const filesChangedPath = join(doctorRoot(home), 'files-changed-count.txt');
   let filesChanged = 0;
   try { filesChanged = parseInt(readFileSync(filesChangedPath, 'utf8').trim() || '0', 10); } catch {}
 
@@ -188,7 +189,7 @@ if (hookEvent === 'Stop') {
     }
   }
 
-  const driveSessionPath = join(home, '.cx', 'drive-session.json');
+  const driveSessionPath = join(doctorRoot(home), 'drive-session.json');
   if (existsSync(driveSessionPath)) {
     let ds = {};
     try { ds = JSON.parse(readFileSync(driveSessionPath, 'utf8')); } catch {}

package/lib/hooks/pre-compact.mjs

@@ -17,10 +17,10 @@
  * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
-import { homedir } from 'os';
 import { join } from 'path';
 import { writeContextState, contextMarkdownPath, contextJsonPath } from '../context-state.mjs';
 import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // Section headings that are auto-generated by this hook. Any other heading in
 // the existing context.md is treated as manually authored and preserved.
@@ -100,8 +100,8 @@ const transcriptPath = input?.transcript_path || '';
 const filesChanged = [];
 const decisions = [];
 const pendingTodos = [];
-const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
-const efficiencyPath = join(homedir(), '.cx', 'session-efficiency.json');
+const warnFlagsPath = join(doctorRoot(), 'warn-flags.txt');
+const efficiencyPath = join(doctorRoot(), 'session-efficiency.json');
 let lastSummary = '';
 
 if (transcriptPath && existsSync(transcriptPath)) {
@@ -275,12 +275,12 @@ if (decisions.length) {
   try { writeFileSync(join(decisionsDir, `${slug}.md`), decisionDoc); } catch { /* best effort */ }
 }
 
-const globalCxDir = join(homedir(), '.cx');
+const globalCxDir = join(doctorRoot(), '.cx');
 try { mkdirSync(globalCxDir, { recursive: true }); } catch { /* exists */ }
-const globalMdPath = contextMarkdownPath(homedir());
+const globalMdPath = contextMarkdownPath(doctorRoot());
 const globalManualSections = extractManualSections(globalMdPath);
 const globalFinalContent = content + (globalManualSections ? '\n' + globalManualSections : '');
-const globalMergedJson = mergeExistingJson(contextJsonPath(homedir()), contextJson);
-try { writeContextState(homedir(), { ...globalMergedJson, contextSummary: lastSummary }, { markdown: globalFinalContent }); } catch { /* best effort */ }
+const globalMergedJson = mergeExistingJson(contextJsonPath(doctorRoot()), contextJson);
+try { writeContextState(doctorRoot(), { ...globalMergedJson, contextSummary: lastSummary }, { markdown: globalFinalContent }); } catch { /* best effort */ }
 
 process.exit(0);