@geraldmaron/construct 1.2.1 → 1.2.3

package/lib/config/project-config.mjs

@@ -8,9 +8,15 @@
  * corresponding env-var value at load time. Pointers keep API keys in
  * `.env` where they belong; the JSON config never sees a secret literal.
  *
- * Precedence rule for consumers: env var if set > config.json > default.
- * `resolveSetting(config, jsonPath, env, envKey, default)` encodes it
- * once so call sites stay consistent.
+ * Two project tiers, most-specific wins: a gitignored
+ * `construct.config.local.json` sibling merges OVER the committed
+ * `construct.config.json`. List settings (sources.targets, intake
+ * additionalDirs, permission allowlists) merge + dedupe; scalars and objects
+ * override key-by-key.
+ *
+ * Precedence rule for consumers: env var if set > config (local ▷ committed)
+ * > default. `resolveSetting(config, jsonPath, env, envKey, default)` encodes
+ * the rule once so call sites stay consistent.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -18,6 +24,7 @@ import { CONFIG_SCHEMA_VERSION, DEFAULT_PROJECT_CONFIG, validateProjectConfig, F
 import { validateSourceTargets } from './source-targets.mjs';
 
 export const PROJECT_CONFIG_FILENAME = 'construct.config.json';
+export const PROJECT_LOCAL_CONFIG_FILENAME = 'construct.config.local.json';
 
 export function findProjectConfigPath(cwd = process.cwd()) {
   let dir = path.resolve(cwd);
@@ -62,6 +69,64 @@ function deepMerge(base, override) {
   return out;
 }
 
+// Identity for list-tier dedupe: object entries collapse on their `id`
+// (source targets, typed selectors) so a local override that re-declares an id
+// replaces the committed entry rather than duplicating it; everything else
+// dedupes on structural equality.
+
+function listKey(item) {
+  if (item !== null && typeof item === 'object' && !Array.isArray(item) && typeof item.id === 'string') {
+    return `id:${item.id}`;
+  }
+  return `json:${JSON.stringify(item)}`;
+}
+
+function mergeList(base, override) {
+  const out = [];
+  const seen = new Map();
+  for (const item of [...(base || []), ...(override || [])]) {
+    const key = listKey(item);
+    if (seen.has(key)) {
+      out[seen.get(key)] = item;
+    } else {
+      seen.set(key, out.length);
+      out.push(item);
+    }
+  }
+  return out;
+}
+
+// Project-local tier merge (most-specific wins): lists merge + dedupe so a local
+// override adds to committed lists (extra source targets, intake dirs, allowlist
+// entries) instead of clobbering them; scalars and objects override key-by-key.
+
+function mergeConfigTier(base, override) {
+  if (override === undefined) return base;
+  if (Array.isArray(base) && Array.isArray(override)) return mergeList(base, override);
+  if (override === null || typeof override !== 'object' || Array.isArray(override)) return override;
+  const out = Array.isArray(base) ? [...(base || [])] : { ...(base || {}) };
+  for (const [k, v] of Object.entries(override)) {
+    out[k] = mergeConfigTier(base?.[k], v);
+  }
+  return out;
+}
+
+function loadLocalConfigOverlay(configPath) {
+  const localPath = path.join(path.dirname(configPath), PROJECT_LOCAL_CONFIG_FILENAME);
+  if (!fs.existsSync(localPath)) return { raw: null, path: null, errors: [] };
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(localPath, 'utf8'));
+  } catch (err) {
+    return { raw: null, path: localPath, errors: [`failed to parse ${localPath}: ${err.message}`] };
+  }
+  const validation = validateProjectConfig(raw, { partial: true });
+  if (!validation.valid) {
+    return { raw: null, path: localPath, errors: (validation.errors ?? []).map((e) => `${localPath}: ${e}`) };
+  }
+  return { raw, path: localPath, errors: [] };
+}
+
 export function loadProjectConfig(cwd = process.cwd(), env = process.env) {
   const configPath = findProjectConfigPath(cwd);
   if (!configPath) {
@@ -99,13 +164,38 @@ export function loadProjectConfig(cwd = process.cwd(), env = process.env) {
       errors: allErrors,
     };
   }
+  const overlay = loadLocalConfigOverlay(configPath);
+  if (overlay.errors.length) {
+    return {
+      path: configPath,
+      raw,
+      config: structuredClone(DEFAULT_PROJECT_CONFIG),
+      source: 'invalid',
+      errors: overlay.errors,
+    };
+  }
+  if (overlay.raw?.sources?.targets !== undefined) {
+    const overlayTargetErrors = validateSourceTargets(overlay.raw.sources.targets);
+    if (overlayTargetErrors.length) {
+      return {
+        path: configPath,
+        raw,
+        config: structuredClone(DEFAULT_PROJECT_CONFIG),
+        source: 'invalid',
+        errors: overlayTargetErrors.map((e) => `${overlay.path}: ${e}`),
+      };
+    }
+  }
+
   const merged = deepMerge(structuredClone(DEFAULT_PROJECT_CONFIG), raw);
-  const resolved = interpolateSecrets(merged, env);
+  const withLocal = overlay.raw ? mergeConfigTier(merged, overlay.raw) : merged;
+  const resolved = interpolateSecrets(withLocal, env);
   return {
     path: configPath,
     raw,
+    localPath: overlay.path,
     config: resolved,
-    source: 'file',
+    source: overlay.raw ? 'file+local' : 'file',
     errors: [],
   };
 }

package/lib/config/schema.mjs

@@ -53,11 +53,6 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   }),
   intakePolicy: Object.freeze({
     maxDepth: 4,
-    zones: Object.freeze({
-      rootInbox: true,
-      projectInbox: true,
-      docsIntake: true,
-    }),
     additionalDirs: [],
   }),
   artifactWorkflow: Object.freeze({
@@ -151,15 +146,6 @@ export const FIELD_RULES = {
     fields: {
       maxDepth: { type: 'number' },
       additionalDirs: { type: 'array' },
-      zones: {
-        type: 'object',
-        required: false,
-        fields: {
-          rootInbox: { type: 'boolean' },
-          projectInbox: { type: 'boolean' },
-          docsIntake: { type: 'boolean' },
-        },
-      },
     },
   },
   artifactWorkflow: {
@@ -269,10 +255,10 @@ function checkType(value, expected) {
   return typeof value === expected;
 }
 
-function validateField(value, rule, path) {
+function validateField(value, rule, path, partial = false) {
   const errors = [];
   if (value === undefined) {
-    if (rule.required) errors.push(`${path}: required field missing`);
+    if (rule.required && !partial) errors.push(`${path}: required field missing`);
     return errors;
   }
   if (!checkType(value, rule.type)) {
@@ -287,19 +273,23 @@ function validateField(value, rule, path) {
   }
   if (rule.fields && checkType(value, 'object')) {
     for (const [key, subRule] of Object.entries(rule.fields)) {
-      errors.push(...validateField(value[key], subRule, `${path}.${key}`));
+      errors.push(...validateField(value[key], subRule, `${path}.${key}`, partial));
     }
   }
   return errors;
 }
 
-export function validateProjectConfig(raw) {
+// `partial` validation skips the required-field check so a sparse override file
+// (construct.config.local.json) validates, while still type- and enum-checking
+// every key that is present.
+
+export function validateProjectConfig(raw, { partial = false } = {}) {
   const errors = [];
   if (!checkType(raw, 'object')) {
     return { valid: false, errors: ['root: must be an object'] };
   }
   for (const [key, rule] of Object.entries(FIELD_RULES)) {
-    errors.push(...validateField(raw[key], rule, key));
+    errors.push(...validateField(raw[key], rule, key, partial));
   }
   if (raw.version !== undefined && raw.version !== CONFIG_SCHEMA_VERSION) {
     errors.push(`version: expected ${CONFIG_SCHEMA_VERSION}, got ${raw.version}`);

package/lib/config/xdg.mjs

@@ -0,0 +1,63 @@
+/**
+ * lib/config/xdg.mjs — single source of truth for Construct's user-scope base
+ * directories, following the XDG Base Directory specification.
+ *
+ * Keeps config (versionable settings), state (durable runtime data), and cache
+ * (regenerable transients) on separate roots so each can be backed up, synced,
+ * and pruned independently:
+ *
+ *   configDir() → $XDG_CONFIG_HOME/construct  (default ~/.config/construct)
+ *   stateDir()  → $XDG_STATE_HOME/construct   (default ~/.local/state/construct)
+ *   cacheDir()  → $XDG_CACHE_HOME/construct   (default ~/.cache/construct)
+ *
+ * Per the XDG spec, an env var is honored only when it is set AND absolute;
+ * a relative or empty value is ignored and the default applies. Every helper
+ * takes an optional homeDir for testability, mirroring the existing homeDir
+ * params across the codebase.
+ *
+ * Clean break: there is no legacy `~/.construct/*` read here. Existing installs
+ * re-run `construct install --scope=user` to repopulate at the XDG paths.
+ */
+import os from 'node:os';
+import path from 'node:path';
+
+// Leaf segment appended under each resolved base.
+
+const APP = 'construct';
+
+// XDG honors an env override only when it names an absolute path; anything
+// relative or empty falls through to the spec default so a stray cwd-relative
+// value can never relocate user state under the process working directory.
+
+function resolveBase(envValue, fallbackSegments, homeDir) {
+  if (typeof envValue === 'string' && path.isAbsolute(envValue)) {
+    return envValue;
+  }
+  return path.join(homeDir, ...fallbackSegments);
+}
+
+export function configDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_CONFIG_HOME, ['.config'], homeDir);
+  return path.join(base, APP);
+}
+
+export function stateDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_STATE_HOME, ['.local', 'state'], homeDir);
+  return path.join(base, APP);
+}
+
+// The global doctor/telemetry/runtime axis (formerly rooted at ~/.cx) now
+// resolves to the XDG state dir. CONSTRUCT_DOCTOR_ROOT, shared by the
+// telemetry/doctor/oracle ecosystem for test isolation, still wins when set to
+// a non-empty value; otherwise stateDir() supplies the durable default.
+
+export function doctorRoot(homeDir = os.homedir(), env = process.env) {
+  const override = env.CONSTRUCT_DOCTOR_ROOT;
+  if (typeof override === 'string' && override.trim()) return override;
+  return stateDir(homeDir, env);
+}
+
+export function cacheDir(homeDir = os.homedir(), env = process.env) {
+  const base = resolveBase(env.XDG_CACHE_HOME, ['.cache'], homeDir);
+  return path.join(base, APP);
+}

package/lib/contracts/violation-log.mjs

@@ -25,12 +25,12 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 
 // contract-violations are PROJECT-SCOPED: resolves to

package/lib/cost-ledger.mjs

@@ -5,7 +5,7 @@
  * before they blow the daily budget. Separate from lib/roles/ because both
  * the gateway and the cost watcher consume it.
  *
- * Storage: ~/.cx/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
+ * Storage: <doctorRoot>/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
  * Rotates: entries older than 30 days are pruned on each write.
  *
  * Budgets are env-driven defaults; explicit `CONSTRUCT_BUDGET_<PERSONA>` wins.
@@ -15,16 +15,17 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { cwd as procCwd } from 'node:process';
 
+import { doctorRoot } from './config/xdg.mjs';
+
 const PRUNE_DAYS = 30;
 const DEFAULT_PER_PERSONA = 10.0;
 const DEFAULT_TOTAL = 50.0;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function ledgerPath() {
   return join(rootDir(), 'cost-ledger.json');

package/lib/cost.mjs

@@ -8,6 +8,7 @@
  */
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 function numberFrom(...values) {
   for (const value of values) {
@@ -82,7 +83,7 @@ export function normalizeCostEntry(entry = {}) {
 }
 
 export function readCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (!existsSync(logPath)) return [];
   try {
     return readFileSync(logPath, 'utf8')
@@ -97,7 +98,7 @@ export function readCostLog(homeDir) {
 }
 
 export function clearCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (existsSync(logPath)) writeFileSync(logPath, '');
 }
 

package/lib/decisions/registry.mjs

@@ -7,7 +7,7 @@
  * contracts as the single source of truth.
  *
  * Three decision sources are indexed:
- *   - ADRs           docs/adr/*.md            (status + supersedes parsed from body)
+ *   - ADRs           docs/decisions/adr/*.md            (status + supersedes parsed from body)
  *   - Contracts      specialists/contracts.json (executable postconditions = enforcement)
  *   - Rules          rules/**\/*.md            (enforcement link via frontmatter; bead wvbf.4)
  *
@@ -37,7 +37,7 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ENFORCES_LINE_RE = /^(?:\/\/|#|\*)?\s*@enforces\s+(\S+)\s*$/;
 
 // The body carries Status and Supersedes as markdown definition lines, not
-// frontmatter (see docs/adr/templates/_template.md); parse them positionally.
+// frontmatter (see docs/decisions/adr/templates/_template.md); parse them positionally.
 
 // ADR field styles vary across the lane: inline bold (`- **Status**: x`,
 // `**Status:** X`) and heading-then-value (`## Status` followed by the value on
@@ -121,7 +121,7 @@ function collectEnforcementBindings({ repoRoot }) {
 }
 
 function adrDecisions({ repoRoot, bindings }) {
-  const dir = join(repoRoot, 'docs', 'adr');
+  const dir = join(repoRoot, 'docs', 'decisions', 'adr');
   const out = [];
   if (!existsSync(dir)) return out;
   for (const name of readdirSync(dir)) {

package/lib/distill.mjs

@@ -9,8 +9,8 @@
 import { readdirSync, statSync, readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, closeSync } from 'fs';
 import { join, extname, relative, dirname, basename } from 'path';
 import { execSync, spawnSync } from 'child_process';
-import { homedir } from 'os';
 import { getActiveOverlays } from './headhunt.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 import { withGenAiSpan, GenAiAttrs } from './telemetry/otel-tracer.mjs';
 import {
   EXTRACTABLE_DOCUMENT_EXTS,
@@ -347,7 +347,7 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
 
   const prompt = structured.prompt;
   if (mode === 'prompt' || !hasClaude()) {
-    const tmpFile = out || join(homedir(), '.cx', 'distill-prompt.txt');
+    const tmpFile = out || join(doctorRoot(), 'distill-prompt.txt');
     try { mkdirSync(dirname(tmpFile), { recursive: true }); } catch { /* exists */ }
     writeFileSync(tmpFile, prompt);
     process.stderr.write(`\n⚠ Prompt written to: ${tmpFile}\n`);

package/lib/docs-verify.mjs

@@ -210,7 +210,9 @@ function gitTrackedMdFiles(cwd, dir) {
 
 function checkIntakeTraceability(cwd) {
   const intakeFedDirs = [
+    path.join(cwd, 'docs', 'specs', 'prd'),
     path.join(cwd, 'docs', 'prd'),
+    path.join(cwd, 'docs', 'notes', 'research'),
     path.join(cwd, 'docs', 'research'),
     path.join(cwd, '.cx', 'knowledge', 'internal'),
   ];

package/lib/doctor/audit.mjs

@@ -6,17 +6,18 @@
  * what the L0 layer did while they weren't looking — and the basis for rolling
  * back a misfire if rules are wrong.
  *
- * Path: ~/.cx/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
+ * Path: <doctorRoot>/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { doctorRoot } from '../config/xdg.mjs';
+
 const MAX_LINES = 2000;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function logPath() {
   return join(rootDir(), 'doctor-log.jsonl');

package/lib/doctor/cli.mjs

@@ -10,7 +10,6 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { readState } from './index.mjs';

package/lib/doctor/index.mjs

@@ -7,12 +7,11 @@
  * never starves the others. Termination via SIGTERM/SIGINT triggers a clean
  * shutdown that records a final audit entry.
  *
- * State file: ~/.construct/doctor.json (pid, started, lastTick).
+ * State file: doctor.json in the XDG state dir (pid, started, lastTick).
  * Audit log:  ~/.cx/doctor-log.jsonl.
  */
 
 import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from './audit.mjs';
@@ -26,8 +25,9 @@ import * as consistency from './watchers/consistency.mjs';
 import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 import * as cxBudget from './watchers/cx-budget.mjs';
 import * as graphStaleness from './watchers/graph-staleness.mjs';
+import { stateDir } from '../config/xdg.mjs';
 
-const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
+const STATE_PATH = join(stateDir(), 'doctor.json');
 const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness];
 
 let running = false;
@@ -35,7 +35,7 @@ let timers = [];
 let lastTickAt = {};
 
 function writeState(state) {
-  const dir = join(homedir(), '.construct');
+  const dir = stateDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify({ ...state, updatedAt: Date.now() }));
 }

package/lib/doctor/report.mjs

@@ -8,10 +8,10 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { recent } from './audit.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 import { getTotalDailySpend, getDailySpend, totalBudget, personaBudget, dayKey } from '../cost-ledger.mjs';
 
 function parseWindow(arg) {
@@ -67,8 +67,8 @@ export async function runReport(args = []) {
   const since = Date.now() - windowMs;
 
   const auditEntries = recent({ since, limit: 10000 });
-  const events = readJsonl(join(homedir(), '.cx', 'events.jsonl')).filter((e) => e.ts >= since);
-  const pending = readJsonl(join(homedir(), '.cx', 'role-pending.jsonl')).filter((e) => e.ts >= since);
+  const events = readJsonl(join(doctorRoot(), 'events.jsonl')).filter((e) => e.ts >= since);
+  const pending = readJsonl(join(doctorRoot(), 'role-pending.jsonl')).filter((e) => e.ts >= since);
 
   const summary = summarizeActions(auditEntries);
   const eventsByType = groupBy(events, (e) => e.type);

package/lib/doctor/watchers/bd-watch.mjs

@@ -4,7 +4,7 @@
  * Every 5 min, polls bd for open issues labeled `next:cx-<role>` where the
  * target persona is onboarded in the role framework. Newly-seen issues are
  * enqueued as pending invocations so session-start surfaces them to
- * Construct. Seen issues are remembered in ~/.cx/bd-watch-seen.json to
+ * Construct. Seen issues are remembered in <doctorRoot>/bd-watch-seen.json to
  * prevent re-emission while the label remains.
  *
  * Closes a gap in agent-tracker: agent-tracker only catches handoffs that
@@ -16,20 +16,20 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { appendBounded } from '../../logging/rotate.mjs';
 import { resolveProjectScope } from '../../project-root.mjs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { listOnboardedPersonas, loadManifest } from '../../roles/manifest.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 
 export const name = 'bd-watch';
 export const intervalMs = 5 * 60 * 1000;
 
-const SEEN_PATH = join(homedir(), '.cx', 'bd-watch-seen.json');
-const PENDING_PATH = join(homedir(), '.cx', 'role-pending.jsonl');
+const SEEN_PATH = join(doctorRoot(), 'bd-watch-seen.json');
+const PENDING_PATH = join(doctorRoot(), 'role-pending.jsonl');
 
 function ensureDir() {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 

package/lib/doctor/watchers/cost.mjs

@@ -10,10 +10,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 import {
   getTotalDailySpend,
   getDailySpend,
@@ -26,15 +26,15 @@ import {
 export const name = 'cost';
 export const intervalMs = 10 * 60 * 1000;
 
-const SESSION_COST_PATH = join(homedir(), '.cx', 'session-cost.jsonl');
-const STATE_PATH = join(homedir(), '.cx', 'cost-watcher-state.json');
+const SESSION_COST_PATH = join(doctorRoot(), 'session-cost.jsonl');
+const STATE_PATH = join(doctorRoot(), 'cost-watcher-state.json');
 
 function loadState() {
   if (!existsSync(STATE_PATH)) return { lastIngestedTsMs: 0 };
   try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return { lastIngestedTsMs: 0 }; }
 }
 function saveState(state) {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state));
 }

package/lib/doctor/watchers/disk.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'disk';
 export const intervalMs = 5 * 60 * 1000;
@@ -54,7 +55,7 @@ function rotateTarget({ path: relPath, maxLines }) {
 }
 
 function pruneRuntimeLogs() {
-  const runtimeDir = join(homedir(), '.construct', '.runtime');
+  const runtimeDir = join(cacheDir(), '.runtime');
   if (!existsSync(runtimeDir)) return { pruned: 0 };
   const maxAgeMs = 7 * 24 * 60 * 60 * 1000;
   const now = Date.now();
@@ -99,11 +100,11 @@ export async function tick() {
       kind: 'action',
       watcher: name,
       action: 'prune',
-      target: '.construct/.runtime/',
+      target: '.cache/construct/.runtime/',
       summary: `pruned ${runtimePrune.pruned} stale runtime log(s) (>7 days)`,
       context: runtimePrune,
     });
-    actions.push({ type: 'prune', target: '.construct/.runtime/' });
+    actions.push({ type: 'prune', target: '.cache/construct/.runtime/' });
   }
 
   const free = freeBytesAt(homedir());

package/lib/doctor/watchers/service-health.mjs

@@ -13,12 +13,12 @@
 
 import { spawnSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync, openSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { configDir, stateDir, cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'service-health';
 export const intervalMs = 60 * 1000;
@@ -56,7 +56,7 @@ function probeTcp(host, port, timeoutMs = 1500) {
 }
 
 function probeDashboardPort() {
-  const statePath = join(homedir(), '.construct', 'dashboard.json');
+  const statePath = join(stateDir(), 'dashboard.json');
   if (!existsSync(statePath)) return true;
   try {
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
@@ -68,7 +68,7 @@ function probeDashboardPort() {
 }
 
 function probeMemoryHealth() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   if (!existsSync(envPath)) return true;
   try {
     const env = readFileSync(envPath, 'utf8');
@@ -87,7 +87,7 @@ function dockerRestart(container) {
 
 function detachSpawn(command, args, logName) {
   try {
-    const runtimeDir = join(homedir(), '.construct', '.runtime');
+    const runtimeDir = join(cacheDir(), '.runtime');
     if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
     const logPath = join(runtimeDir, logName);
     const fd = openSync(logPath, 'a');
@@ -106,7 +106,7 @@ function respawnViaConstructUp() {
 }
 
 function respawnCm() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   let port = '4231';
   try {
     if (existsSync(envPath)) {

package/lib/document-export.mjs

@@ -5,7 +5,7 @@
  *
  * Export **source** is Construct-authored markdown (typed artifacts). **Output**
  * spans many distributable formats. Ingest (separate pipeline) accepts PDF, Office,
- * email, AV, and plain text — see docs/reference/document-io.md.
+ * email, AV, and plain text — see docs/guides/reference/document-io.md.
  */
 
 import fs from 'node:fs';

package/lib/document-extract.mjs

@@ -345,8 +345,8 @@ function extractPdf(filePath) {
   if (extracted.text.length < threshold) {
     const ocrHint = process.env.CONSTRUCT_PDF_OCR_HINT || 'none';
     const hintMsg = ocrHint !== 'none'
-      ? `OCR backend hint: ${ocrHint}. See docs/intake/scanned-pdfs.md.`
-      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/intake/scanned-pdfs.md.';
+      ? `OCR backend hint: ${ocrHint}. See docs/guides/intake/scanned-pdfs.md.`
+      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/guides/intake/scanned-pdfs.md.';
     extracted.droppedInfo.push(makeDropInfo({
       kind: 'scanned-pdf',
       count: pages,
@@ -692,7 +692,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   // Throw a typed error so callers can route to .cx/intake/needs-asr/.
   if (AUDIO_VIDEO_EXTS.has(extension)) {
     const err = new Error(
-      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/intake/audio-video.md.`,
+      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/guides/intake/audio-video.md.`,
     );
     err.code = 'ASR_REQUIRED';
     err.extension = extension;