@geraldmaron/construct 1.2.1 → 1.2.2

package/lib/bootstrap/built-ins.mjs

@@ -14,8 +14,8 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import os from 'node:os';
 import { registerResource, getResource } from './resources.mjs';
+import { cacheDir } from '../config/xdg.mjs';
 
 function probeCommandVersion(cmd, args = ['--version']) {
   const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: 3000 });
@@ -56,8 +56,8 @@ async function probePostgresContainer() {
 
 async function probeEmbeddingModel() {
   const cachePath = join(
-    os.homedir(),
-    '.construct', 'cache', 'embeddings',
+    cacheDir(),
+    'embeddings',
     'Xenova', 'all-MiniLM-L6-v2', 'onnx', 'model_quantized.onnx'
   );
   if (existsSync(cachePath)) {

package/lib/boundary.mjs

@@ -3,7 +3,7 @@
  *
  * Verifies a parent Construct instance is reachable, validates an HMAC
  * signature over `childInstanceId|nonce` when a shared secret is configured,
- * and persists the binding to ~/.construct/boundary.json (mode 0600). A
+ * and persists the binding to boundary.json in the XDG config dir (mode 0600). A
  * different parent rotates the registration only when explicitly allowed via
  * CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1; prior configs are archived alongside
  * the active one. Exposed as a standalone module so the dashboard endpoint
@@ -16,11 +16,12 @@ import { homedir } from 'node:os';
 import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
 import { request as httpRequest } from 'node:http';
 import { request as httpsRequest } from 'node:https';
+import { configDir } from './config/xdg.mjs';
 
 export const BOUNDARY_VERSION = '1.0';
 
 function boundaryDir(home = homedir()) {
-  return join(home, '.construct');
+  return configDir(home);
 }
 
 export function boundaryConfigPath(home = homedir()) {

package/lib/brand-prose.mjs

@@ -37,7 +37,7 @@ const EXCLUDE_PATH =
   /(node_modules|\.git|audit-artifacts|scripts\/audit|CHANGELOG\.md|fonts\/legacy\/|\.next\/|\/out\/|tests\/e2e\/reports\/|package-lock\.json)/;
 
 const DOC_EXEMPT =
-  /(?:^|\/)(docs\/STYLE\.md|docs\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
+  /(?:^|\/)(docs\/STYLE\.md|docs\/guides\/reference\/branding\.md|templates\/distribution\/fonts\/README\.md)$/;
 
 const HOOK_SCOPED =
   /^(docs\/|skills\/|specialists\/|personas\/|templates\/|rules\/|apps\/(dashboard|docs|chat)\/)/;

package/lib/cache-governor.js

@@ -10,10 +10,10 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { normalizeCostEntry } from './cost.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
-const STRATEGY_PATH = join(homedir(), '.cx', 'cache-strategy.json');
+const STRATEGY_PATH = join(doctorRoot(), 'cache-strategy.json');
 const REVIEW_INTERVAL_MS = 10 * 60 * 1000; // 10 minutes between adjustments
 
 function readStrategy() {
@@ -27,7 +27,7 @@ function readStrategy() {
 
 function writeStrategy(data) {
   try {
-    mkdirSync(join(homedir(), '.cx'), { recursive: true });
+    mkdirSync(doctorRoot(), { recursive: true });
     writeFileSync(STRATEGY_PATH, JSON.stringify(data, null, 2));
   } catch { /* best effort */ }
 }
@@ -153,7 +153,7 @@ export function onPostToolUse({ costLogPath, provider, dryRun = false } = {}) {
   // Read cost log
   const entries = [];
   try {
-    const logPath = costLogPath || join(homedir(), '.cx', 'session-cost.jsonl');
+    const logPath = costLogPath || join(doctorRoot(), 'session-cost.jsonl');
     if (!existsSync(logPath)) return { adjusted: false, reason: 'No cost log' };
 
     const lines = readFileSync(logPath, 'utf8')

package/lib/certification/document-io-fixtures.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/certification/document-io-fixtures.mjs — intake fixture catalog for document I/O tests.
  *
- * Maps docs/reference/document-io.md supported intake categories to committed
+ * Maps docs/guides/reference/document-io.md supported intake categories to committed
  * files under tests/fixtures/document-io/<category>/.
  */
 

package/lib/chat/config.mjs

@@ -14,8 +14,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 export const LAYER_KEYS = ['thinking', 'path', 'specialists', 'tools', 'observability'];
 export const PERMISSION_MODES = ['ask', 'allow_once', 'allow_always', 'reject'];
@@ -64,7 +64,7 @@ function mergeConfig(base, override) {
 }
 
 export function globalConfigPath() {
-  return path.join(os.homedir(), '.cx', CONFIG_BASENAME);
+  return path.join(doctorRoot(), CONFIG_BASENAME);
 }
 
 export function projectConfigPath({ cwd = process.cwd() } = {}) {

package/lib/chat/desktop-binary.mjs

@@ -1,8 +1,8 @@
 /**
  * lib/chat/desktop-binary.mjs — resolve the Construct chat desktop window binary.
  *
- * Search order: CONSTRUCT_CHAT_DESKTOP_BIN, repo dev build, ~/.construct/bin,
- * then packaged sidecar next to construct.
+ * Search order: CONSTRUCT_CHAT_DESKTOP_BIN, repo dev build, the bin/ subdir of
+ * the XDG state dir, then packaged sidecar next to construct.
  */
 
 import fs from 'node:fs';
@@ -10,6 +10,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { stateDir } from '../config/xdg.mjs';
+
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(HERE, '..', '..');
 
@@ -50,7 +52,7 @@ export function desktopBinaryCandidates({ repoRoot = REPO_ROOT, homeDir = os.hom
     env.CONSTRUCT_CHAT_DESKTOP_BIN,
     path.join(tauriRoot, 'release', name),
     path.join(tauriRoot, 'debug', name),
-    path.join(homeDir, '.construct', 'bin', name),
+    path.join(stateDir(homeDir), 'bin', name),
     path.join(repoRoot, 'apps', 'chat', 'desktop', 'bin', name),
   ].filter(Boolean);
 }

package/lib/cli-commands.mjs

@@ -1112,7 +1112,7 @@ export const CLI_COMMANDS = [
     emoji: '📄',
     category: 'Diagnostics',
     core: false,
-    description: 'Regenerate generated reference pages under docs/reference/',
+    description: 'Regenerate generated reference pages under docs/guides/reference/',
     usage: 'construct docs:site [--check]',
   },
   {
@@ -1146,7 +1146,7 @@ export const CLI_COMMANDS = [
   { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
   { name: 'registry:status',   category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Dev: capability registry inspector', usage: 'construct registry:status [--json]' },
   { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Validate registry/capabilities.json against repo reality', usage: 'construct registry:validate [--json]' },
-  { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
+  { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/guides/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
   { name: 'oracle', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
   { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
   { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
@@ -1271,7 +1271,7 @@ export function formatCommandHelp(name, { colors = false } = {}) {
     lines.push(`${c.dim}Next:${c.reset} ${next}`);
     lines.push('');
   }
-  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/reference/cli/.`);
+  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/guides/reference/cli/.`);
   lines.push('');
   return lines.join('\n');
 }

package/lib/cli-service-inventory.mjs

@@ -25,7 +25,7 @@ function handlerNames(rootDir) {
 export function buildCliServiceInventory({ rootDir = process.cwd() } = {}) {
   const handlers = handlerNames(rootDir);
   return CLI_COMMANDS.filter((spec) => !spec.internal).map((spec) => {
-    const page = path.join(rootDir, 'docs', 'reference', 'cli', `${slugify(spec.category)}.md`);
+    const page = path.join(rootDir, 'docs', 'guides', 'reference', 'cli', `${slugify(spec.category)}.md`);
     const pageText = fs.existsSync(page) ? fs.readFileSync(page, 'utf8') : '';
     return {
       name: spec.name,

package/lib/comment-lint.mjs

@@ -34,11 +34,15 @@ const MD_HEADER_GLOBS = [
 // Scope is deliberately narrow — READMEs, cookbook, concepts, and reference are
 // unaffected. The patterns live in BANNED_ARTIFACT below; the severity (block
 // vs warn) is controlled by CONSTRUCT_ARTIFACT_LINT_MODE.
+// Match this repo's bucketed layout (docs/specs/prd, docs/decisions/adr, …) and
+// the flat init-lane layout that `construct init` scaffolds downstream (docs/prd,
+// docs/adr, …), so artifact-prose linting fires in either project shape.
+
 const ARTIFACT_PATH_GLOBS = [
-  /^docs\/prd\//,
-  /^docs\/adr\//,
-  /^docs\/rfc\//,
-  /^docs\/research\//,
+  /^docs\/(?:specs\/)?prd\//,
+  /^docs\/(?:decisions\/)?adr\//,
+  /^docs\/(?:decisions\/)?rfc\//,
+  /^docs\/(?:notes\/)?research\//,
   /^\.cx\/knowledge\//,
   /^\.cx\/handoffs\//,
   /^\.cx\/research\//,
@@ -55,7 +59,7 @@ function isArtifactPath(rel) {
 // Deliverable surfaces where a tool-identity leak (rules/common/tool-invisibility.md)
 // matters: project docs and the durable .cx knowledge / research / handoff / strategy
 // stores. Broader than the fabrication-scoped ARTIFACT_PATH_GLOBS because a strategy
-// lands in docs/ root, not only docs/prd.
+// lands in docs/ root, not only docs/specs/prd.
 
 const DELIVERABLE_LEAK_GLOBS = [
   /^docs\/.*\.md$/,

package/lib/config/alias.mjs

@@ -3,7 +3,7 @@
  *
  * Lookup precedence:
  *   1. CONSTRUCT_ALIAS env var (per-session override)
- *   2. ~/.construct/config.json.aliasOverride (user-level, lets each
+ *   2. config.json.aliasOverride in the XDG config dir (user-level, lets each
  *      user on the same project see their own branding without
  *      committing it)
  *   3. construct.config.json.alias (project-level, committed)
@@ -17,6 +17,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { loadProjectConfig } from './project-config.mjs';
+import { configDir } from './xdg.mjs';
 
 export const DEFAULT_ALIAS = 'Construct';
 export const ALIAS_ENV_KEY = 'CONSTRUCT_ALIAS';
@@ -29,7 +30,7 @@ export function resolveAlias({ cwd = process.cwd(), env = process.env, homeDir =
   }
 
   try {
-    const userCfgPath = path.join(homeDir, '.construct', 'config.json');
+    const userCfgPath = path.join(configDir(homeDir), 'config.json');
     if (fs.existsSync(userCfgPath)) {
       const userCfg = JSON.parse(fs.readFileSync(userCfgPath, 'utf8'));
       const userAlias = userCfg?.aliasOverride;

package/lib/config/intake-policy.mjs

@@ -1,12 +1,16 @@
 /**
  * lib/config/intake-policy.mjs — project-scoped intake watcher policy.
  *
- * Resolves watch zones, scan depth, and additional directories from
- * construct.config.json intakePolicy, with warned fallback to legacy
- * .cx/intake-config.json and env overrides.
+ * Resolves the canonical drop zone, scan depth, and additional directories from
+ * construct.config.json intakePolicy (the only config source), with env
+ * overrides and a default when intakePolicy is absent.
+ *
+ * Single-zone model (ADR-0045 §C): the only drop zone is the project-root
+ * `inbox/`, always watched. `additionalDirs` (opt-in extra dirs) and `maxDepth`
+ * remain configurable. There are no other zones — `.cx/inbox/` and `docs/intake/`
+ * are not watched and not scaffolded.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { loadProjectConfig, writeProjectConfig, findProjectConfigPath, PROJECT_CONFIG_FILENAME } from './project-config.mjs';
 import {
@@ -15,17 +19,11 @@ import {
   INTAKE_DEPTH_GUIDANCE,
   describeIntakeDepth,
 } from '../intake/constants.mjs';
-import { INTAKE_CONFIG_FILE } from '../intake/legacy-paths.mjs';
 
 export { INTAKE_DEFAULT_MAX_DEPTH, INTAKE_HARD_MAX_DEPTH, INTAKE_DEPTH_GUIDANCE, describeIntakeDepth };
 
 export const DEFAULT_INTAKE_POLICY = Object.freeze({
   maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
-  zones: Object.freeze({
-    rootInbox: true,
-    projectInbox: true,
-    docsIntake: true,
-  }),
   additionalDirs: [],
 });
 
@@ -48,69 +46,24 @@ function parseEnvDirs(env) {
   return raw.split(':').map((p) => p.trim()).filter(Boolean);
 }
 
-function readLegacyIntakeConfig(rootDir) {
-  const file = join(rootDir, INTAKE_CONFIG_FILE);
-  if (!existsSync(file)) return null;
-  try {
-    return JSON.parse(readFileSync(file, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
 export function intakePolicyFromProjectConfig(config) {
   const raw = config?.intakePolicy ?? {};
-  const zones = raw.zones ?? {};
   return {
     maxDepth: clampDepth(raw.maxDepth ?? DEFAULT_INTAKE_POLICY.maxDepth),
-    zones: {
-      rootInbox: zones.rootInbox !== false,
-      projectInbox: zones.projectInbox !== false,
-      docsIntake: zones.docsIntake !== false,
-    },
     additionalDirs: Array.isArray(raw.additionalDirs)
       ? raw.additionalDirs.map((d) => String(d).trim()).filter(Boolean)
       : [],
   };
 }
 
-export function legacyIntakeToPolicy(stored = {}) {
-  return {
-    maxDepth: clampDepth(stored.maxDepth ?? INTAKE_DEFAULT_MAX_DEPTH),
-    zones: {
-      rootInbox: stored.includeArchetypeInbox === true || stored.includeRootInbox === true,
-      projectInbox: stored.includeProjectInbox !== false,
-      docsIntake: stored.includeDocsIntake !== false,
-    },
-    additionalDirs: Array.isArray(stored.parentDirs) ? stored.parentDirs : [],
-  };
-}
-
-export function policyToLegacyIntakeShape(policy) {
-  return {
-    parentDirs: policy.additionalDirs,
-    maxDepth: policy.maxDepth,
-    includeProjectInbox: policy.zones.projectInbox,
-    includeDocsIntake: policy.zones.docsIntake,
-    includeArchetypeInbox: policy.zones.rootInbox,
-    includeRootInbox: policy.zones.rootInbox,
-  };
-}
-
 export function loadIntakePolicy(rootDir, env = process.env) {
   const { config, path: configPath, raw } = loadProjectConfig(rootDir, env);
-  const legacy = readLegacyIntakeConfig(rootDir);
   let policy;
   let source = 'default';
-  let legacyWarning = null;
 
   if (configPath && raw?.intakePolicy) {
     policy = intakePolicyFromProjectConfig(config);
     source = 'project-config';
-  } else if (legacy) {
-    policy = legacyIntakeToPolicy(legacy);
-    source = 'legacy-intake-config';
-    legacyWarning = `Using deprecated ${INTAKE_CONFIG_FILE}; migrate with \`construct intake config migrate\``;
   } else {
     policy = structuredClone(DEFAULT_INTAKE_POLICY);
     source = 'default';
@@ -134,10 +87,8 @@ export function loadIntakePolicy(rootDir, env = process.env) {
 
   return {
     maxDepth,
-    zones: { ...policy.zones },
     additionalDirs: uniqueDirs,
     source,
-    legacyWarning,
   };
 }
 
@@ -146,12 +97,7 @@ export function resolvedIntakeConfig(rootDir, env = process.env) {
   return {
     parentDirs: policy.additionalDirs,
     maxDepth: policy.maxDepth,
-    includeProjectInbox: policy.zones.projectInbox,
-    includeDocsIntake: policy.zones.docsIntake,
-    includeArchetypeInbox: policy.zones.rootInbox,
-    includeRootInbox: policy.zones.rootInbox,
     source: policy.source,
-    legacyWarning: policy.legacyWarning,
   };
 }
 
@@ -160,14 +106,8 @@ export function saveIntakePolicy(rootDir, patch = {}, options = {}) {
   const { config } = loadProjectConfig(rootDir, {});
   const current = intakePolicyFromProjectConfig(config.intakePolicy ? config : { intakePolicy: DEFAULT_INTAKE_POLICY });
 
-  const nextZones = { ...current.zones, ...(patch.zones ?? {}) };
   const next = {
     maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
-    zones: {
-      rootInbox: patch.rootInbox !== undefined ? Boolean(patch.rootInbox) : (patch.zones?.rootInbox ?? nextZones.rootInbox),
-      projectInbox: patch.projectInbox !== undefined ? Boolean(patch.projectInbox) : (patch.zones?.projectInbox ?? nextZones.projectInbox),
-      docsIntake: patch.docsIntake !== undefined ? Boolean(patch.docsIntake) : (patch.zones?.docsIntake ?? nextZones.docsIntake),
-    },
     additionalDirs: Array.isArray(patch.additionalDirs)
       ? patch.additionalDirs.map((dir) => normalizeDir(dir, rootDir)).filter(Boolean)
       : current.additionalDirs,
@@ -197,13 +137,3 @@ export function saveIntakePolicy(rootDir, patch = {}, options = {}) {
   writeProjectConfig(configPath, updated);
   return { policy: next, configPath };
 }
-
-export function migrateLegacyIntakeConfig(rootDir) {
-  const legacy = readLegacyIntakeConfig(rootDir);
-  if (!legacy) {
-    return { migrated: false, reason: 'no legacy file' };
-  }
-  const policy = legacyIntakeToPolicy(legacy);
-  saveIntakePolicy(rootDir, policy);
-  return { migrated: true, policy };
-}

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