@geraldmaron/construct 1.2.1 → 1.2.3

package/lib/auto-docs.mjs

@@ -11,7 +11,7 @@
  *
  * buildSite() is retained for compatibility; the public site now renders docs/
  * directly through Next.js (apps/docs/) and buildFumadocsReference() emits
- * generated reference Markdown into docs/reference/.
+ * generated reference Markdown into docs/guides/reference/.
  */
 
 import fs from 'node:fs';
@@ -78,7 +78,7 @@ function buildCoreDocsContract() {
     '| `.cx/context.md` | Human-readable resumable project context | Active work, decisions, architecture assumptions, or open questions change |',
     '| `.cx/context.json` | Machine-readable resumable context | Context state needs to stay in sync with `.cx/context.md` |',
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
-    '| `docs/concepts/architecture.mdx` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
+    '| `docs/guides/concepts/architecture.mdx` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
     '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
@@ -191,7 +191,7 @@ function buildAgentsTable(rootDir) {
 // --- public API ---
 
 /**
- * Regenerate all AUTO regions in README.md, docs/README.md, and docs/concepts/architecture.mdx.
+ * Regenerate all AUTO regions in README.md, docs/README.md, and docs/guides/concepts/architecture.mdx.
  * Returns { changed: string[], checked: boolean }.
  * With check:true writes nothing and sets changed to files that would differ.
  */
@@ -209,7 +209,7 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
       },
     },
     {
-      file: path.join(rootDir, 'docs', 'concepts', 'architecture.mdx'),
+      file: path.join(rootDir, 'docs', 'guides', 'concepts', 'architecture.mdx'),
       regions: {
         agents: buildAgentsTable(rootDir),
       },
@@ -268,7 +268,7 @@ export function checkDocsCoverage({ rootDir } = {}) {
   // Build a combined corpus: docs/README.md + every linked guide file
   let corpus = docsReadme;
   for (const target of linkTargets) {
-    if (!target.startsWith('./how-to/') && !target.startsWith('./cookbook/')) continue;
+    if (!target.startsWith('./guides/cookbook/')) continue;
     const filePath = path.join(rootDir, 'docs', target.replace(/^\.\//, ''));
     const content = readFile(filePath);
     if (content) corpus += '\n' + content;
@@ -423,7 +423,7 @@ function renderAgentsPage(rootDir) {
 }
 
 /**
- * Emit MDX reference pages into docs/reference/ for the Next.js docs site
+ * Emit MDX reference pages into docs/guides/reference/ for the Next.js docs site
  * in apps/docs/. Mirrors the data sources behind AUTO regions and buildSite()
  * but writes Markdown files the docs app can pull in directly (no MkDocs
  * intermediate). Name kept for backwards compatibility with callers that
@@ -432,7 +432,7 @@ function renderAgentsPage(rootDir) {
  */
 export function buildFumadocsReference({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
-  const refDir = path.join(rootDir, 'docs', 'reference');
+  const refDir = path.join(rootDir, 'docs', 'guides', 'reference');
   const cliDir = path.join(refDir, 'cli');
   fs.mkdirSync(cliDir, { recursive: true });
 
@@ -468,7 +468,7 @@ export function buildFumadocsReference({ rootDir } = {}) {
       const slug = slugify(cat);
       const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
       if (!commands.length) return null;
-      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+      return `- [${cat}](/guides/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
     }).filter(Boolean),
     '',
   ].join('\n');
@@ -499,7 +499,7 @@ export function buildFumadocsReference({ rootDir } = {}) {
 
 export function checkFumadocsReferenceDrift({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
-  const refDir = path.join(rootDir, 'docs', 'reference');
+  const refDir = path.join(rootDir, 'docs', 'guides', 'reference');
   const cliDir = path.join(refDir, 'cli');
   const drift = [];
 
@@ -534,7 +534,7 @@ export function checkFumadocsReferenceDrift({ rootDir } = {}) {
       const slug = slugify(cat);
       const commands = CLI_COMMANDS_BY_CATEGORY[cat] ?? [];
       if (!commands.length) return null;
-      return `- [${cat}](/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
+      return `- [${cat}](/guides/reference/cli/${slug}) — ${commands.length} command${commands.length === 1 ? '' : 's'}`;
     }).filter(Boolean),
     '',
   ].join('\n');

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

@@ -429,14 +429,12 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models <list|set|free|reset|usage|cost|resolve>',
+    usage: 'construct models <list|set|free|reset|resolve>',
     subcommands: [
       { name: 'list', desc: 'Show current tier assignments' },
       { name: 'set --tier=<reasoning|standard|fast> --model=<model>', desc: 'Set a model for a tier' },
       { name: 'free', desc: 'List available free models' },
       { name: 'reset', desc: 'Reset all tier assignments' },
-      { name: 'usage', desc: 'Show token usage per tier' },
-      { name: 'cost', desc: 'Show cost breakdown' },
       { name: 'resolve --json', desc: 'Resolve the model for an embedded workflow given host context' },
     ],
   },
@@ -1112,7 +1110,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 +1144,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 +1269,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/legacy-config-migration.mjs

@@ -0,0 +1,59 @@
+/**
+ * lib/config/legacy-config-migration.mjs — one-time forward migration of model
+ * tier overrides from the pre-XDG legacy config into the active XDG config.
+ *
+ * The config move to $XDG_CONFIG_HOME/construct (see lib/config/xdg.mjs) is a
+ * clean break with no legacy read, so any install that set CX_MODEL_* before
+ * the move keeps those values stranded in ~/.construct/config.env. Resolution
+ * reads only the XDG path, so doctor then reports "no tier configured" until
+ * the user hand-copies the keys. This mirrors the stranded tier overrides
+ * forward, and never overwrites a value the XDG config already defines.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { parseEnvFile, writeEnvValues } from '../env-config.mjs';
+import { configDir } from './xdg.mjs';
+
+// Only model tier overrides migrate. API keys and other secrets are
+// intentionally out of scope — they are re-established through the credential
+// bootstrap, not copied between paths.
+
+const MIGRATABLE_KEY = /^(?:CX|CONSTRUCT)_MODEL_[A-Z0-9_]+$/;
+
+export function legacyConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, '.construct', 'config.env');
+}
+
+/**
+ * Migrate stranded CX_MODEL_ and CONSTRUCT_MODEL_ tier overrides from the
+ * legacy config into the XDG config. Returns the keys that were written so
+ * callers can surface a one-time message and refresh their in-process env.
+ */
+export function migrateLegacyModelConfig({ homeDir = os.homedir(), env = process.env } = {}) {
+  const legacyPath = legacyConfigPath(homeDir);
+  const xdgPath = path.join(configDir(homeDir, env), 'config.env');
+  const result = { performed: false, migrated: {}, legacyPath, xdgPath };
+
+  if (legacyPath === xdgPath || !fs.existsSync(legacyPath)) return result;
+
+  const legacyEnv = parseEnvFile(legacyPath);
+  const xdgEnv = parseEnvFile(xdgPath);
+
+  const migrated = {};
+  for (const [key, value] of Object.entries(legacyEnv)) {
+    if (!MIGRATABLE_KEY.test(key)) continue;
+    if (value === '' || value === undefined) continue;
+    if (xdgEnv[key] !== undefined && xdgEnv[key] !== '') continue;
+    migrated[key] = value;
+  }
+
+  if (Object.keys(migrated).length === 0) return result;
+
+  writeEnvValues(xdgPath, migrated);
+  result.performed = true;
+  result.migrated = migrated;
+  return result;
+}