@geraldmaron/construct 1.2.1 → 1.2.3

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

package/lib/hooks/readme-age-check.mjs

@@ -17,11 +17,11 @@
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { execSync } from 'node:child_process';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { emitRoleEvent } from '../roles/hook-emit.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const STATE_PATH = join(homedir(), '.cx', 'readme-age-state.json');
+const STATE_PATH = join(doctorRoot(), 'readme-age-state.json');
 const STALE_DAYS = 90;
 const SUPPRESS_DAYS = 7;
 

package/lib/hooks/session-optimize.mjs

@@ -14,18 +14,19 @@
  */
 import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'fs';
 import { join, dirname } from 'path';
-import { homedir } from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 
+import { doctorRoot } from '../config/xdg.mjs';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = join(__dirname, '..', '..', 'bin', 'construct');
 
 const OPTIMIZATION_THRESHOLD = 0.7;
 const MIN_TRACES_PER_AGENT = 3;
 const OPTIMIZATION_DAYS = 7;
-const OPTIMIZATION_LOG_DIR = join(homedir(), '.cx', 'optimization-logs');
-const REVIEWS_DIR = join(homedir(), '.cx', 'performance-reviews');
+const OPTIMIZATION_LOG_DIR = join(doctorRoot(), 'optimization-logs');
+const REVIEWS_DIR = join(doctorRoot(), 'performance-reviews');
 
 mkdirSync(OPTIMIZATION_LOG_DIR, { recursive: true });
 

package/lib/hooks/session-start.mjs

@@ -24,6 +24,7 @@ import { listObservations, searchObservations } from '../observation-store.mjs';
 import { countEntities } from '../entity-store.mjs';
 import { logHookFailure } from './_lib/log.mjs';
 import { resolveHookOutputMode, writeHookContext } from './_lib/output-mode.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
 const CONSTRUCT_BIN = resolve(MODULE_DIR, '..', '..', 'bin', 'construct');
@@ -64,11 +65,11 @@ function fileIsFresh(path) {
 // stale context files inject only the digest line as fallback (Tier 2 → Tier 1
 // degradation), full body only when modified within the freshness window.
 const localCtx = join(cwd, '.cx', 'context.md');
-const globalCtx = join(homedir(), '.cx', 'context.md');
+const globalCtx = join(doctorRoot(), '.cx', 'context.md');
 let context = '';
 let contextStale = false;
 const localState = readContextState(cwd);
-const globalState = localState ? null : readContextState(homedir());
+const globalState = localState ? null : readContextState(doctorRoot());
 const stateContext = localState || globalState;
 const stateContextPath = localState ? localCtx : globalCtx;
 if (stateContext?.markdown) {
@@ -151,7 +152,7 @@ try {
 
 // Record memory injection stats for the Stop hook to persist into .cx/memory-stats.jsonl.
 try {
-  const memStatsPath = join(homedir(), '.cx', 'session-memory-stats.json');
+  const memStatsPath = join(doctorRoot(), 'session-memory-stats.json');
   const injected = observationsNote ? (observationsNote.match(/^- /gm) || []).length : 0;
   writeFileSync(memStatsPath, JSON.stringify({
     project: projectName,
@@ -162,7 +163,7 @@ try {
 } catch { /* best effort */ }
 
 // Pending typecheck warning
-const tcPath = join(homedir(), '.cx', 'pending-typecheck.txt');
+const tcPath = join(doctorRoot(), 'pending-typecheck.txt');
 let pendingNote = '';
 try {
   const pending = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
@@ -400,7 +401,7 @@ try {
 try {
   const sessionId = input?.session_id || input?.sessionId;
   if (sessionId) {
-    const bootstrapPath = join(homedir(), ".cx", "bootstrap-state.json");
+    const bootstrapPath = join(doctorRoot(), "bootstrap-state.json");
     let state = {};
     try { state = JSON.parse(readFileSync(bootstrapPath, "utf8")) || {}; } catch {}
     const now = Date.now();

package/lib/hooks/stop-notify.mjs

@@ -27,6 +27,7 @@ import { captureSessionArtifacts } from '../artifact-capture.mjs';
 import { appendSessionStats } from '../memory-stats.mjs';
 import { estimateUsageCost } from '../telemetry/model-pricing-catalog.mjs';
 import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 function loadTranscriptCheckpoints(checkpointPath) {
   try {
@@ -148,12 +149,12 @@ if (raw) process.stdout.write(raw);
 try { flushReadTrackerDeltas({ env: process.env }); } catch { /* non-critical */ }
 
 const home = homedir();
-const tsResultPath = join(home, '.cx', 'ts-result.txt');
-const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');
-const countPath = join(home, '.cx', 'files-changed-count.txt');
-const costLogPath = join(home, '.cx', 'session-cost.jsonl');
-const lastAgentPath = join(home, '.cx', 'last-agent.json');
-const checkpointPath = join(home, '.cx', 'transcript-checkpoints.json');
+const tsResultPath = join(doctorRoot(home), 'ts-result.txt');
+const warnFlagsPath = join(doctorRoot(home), 'warn-flags.txt');
+const countPath = join(doctorRoot(home), 'files-changed-count.txt');
+const costLogPath = join(doctorRoot(home), 'session-cost.jsonl');
+const lastAgentPath = join(doctorRoot(home), 'last-agent.json');
+const checkpointPath = join(doctorRoot(home), 'transcript-checkpoints.json');
 
 // Consume-clear like warn-flags/files-changed below: a TS result is reported
 // once, not re-fired on every subsequent no-op Stop. stop-typecheck rewrites
@@ -304,7 +305,7 @@ try {
   }
 } catch { /* non-critical */ }
 
-const memStatsPath = join(home, '.cx', 'session-memory-stats.json');
+const memStatsPath = join(doctorRoot(home), 'session-memory-stats.json');
 try {
   if (existsSync(memStatsPath)) {
     const memStats = JSON.parse(readFileSync(memStatsPath, 'utf8'));
@@ -323,7 +324,7 @@ try {
 // repeat Stop events within the window to avoid review-spam.
 try {
   const homeDir = process.env.HOME || homedir();
-  const stampPath = join(homeDir, '.cx', 'performance-reviews', '.last-run');
+  const stampPath = join(doctorRoot(homeDir), 'performance-reviews', '.last-run');
   let lastRun = 0;
   try { lastRun = Number(readFileSync(stampPath, 'utf8')) || 0; } catch { /* fresh */ }
   if (Date.now() - lastRun > 24 * 60 * 60 * 1000) {

package/lib/hooks/stop-typecheck.mjs

@@ -15,6 +15,7 @@ import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { execSync } from 'child_process';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // Stop hooks must echo stdin to stdout
 let raw = '';
@@ -22,9 +23,9 @@ try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
 if (raw) process.stdout.write(raw);
 
 const home = homedir();
-const tcPath = join(home, '.cx', 'pending-typecheck.txt');
-const tsResultPath = join(home, '.cx', 'ts-result.txt');
-const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');
+const tcPath = join(doctorRoot(home), 'pending-typecheck.txt');
+const tsResultPath = join(doctorRoot(home), 'ts-result.txt');
+const warnFlagsPath = join(doctorRoot(home), 'warn-flags.txt');
 
 // Read pending files
 const pending = existsSync(tcPath)