@geraldmaron/construct 1.2.1 → 1.2.3

package/bin/construct

@@ -38,6 +38,7 @@ import {
   PROJECT_CONFIG_FILENAME,
 } from '../lib/config/project-config.mjs';
 import { validateProjectConfig } from '../lib/config/schema.mjs';
+import { configDir, doctorRoot } from '../lib/config/xdg.mjs';
 import {
   DEPLOYMENT_MODES,
   DEPLOYMENT_MODE_ENV_KEY,
@@ -400,7 +401,7 @@ async function cmdDoctor() {
       }
 
       // .env files
-      for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), join(homedir(), '.construct', 'config.env')]) {
+      for (const envPath of [join(process.cwd(), '.env'), join(homedir(), '.env'), getUserEnvPath(homedir())]) {
         if (fs.existsSync(envPath)) {
           try {
             const content = fs.readFileSync(envPath, 'utf8');
@@ -592,7 +593,7 @@ async function cmdDoctor() {
   // minute at 50MB, but a freshly-upgraded install with a 34GB legacy
   // log shouldn't wait 60s. --fix-embed-log forces rotation now.
 
-  const embedLogPath = path.join(userHome, '.cx', 'runtime', 'embed-daemon.log');
+  const embedLogPath = path.join(doctorRoot(userHome), 'runtime', 'embed-daemon.log');
   if (fs.existsSync(embedLogPath)) {
     const sizeMb = fs.statSync(embedLogPath).size / 1024 / 1024;
     const FORCE_THRESHOLD_MB = Number(process.env.CONSTRUCT_DOCTOR_EMBED_LOG_FORCE_MB) || 500;
@@ -627,11 +628,11 @@ async function cmdDoctor() {
     'intent-verifications.jsonl',
   ];
   const legacyState = projectScopedNames
-    .map((name) => ({ name, path: path.join(userHome, '.cx', name) }))
+    .map((name) => ({ name, path: path.join(doctorRoot(userHome), name) }))
     .filter((p) => fs.existsSync(p.path) && fs.statSync(p.path).size > 0);
 
   if (legacyState.length > 0 && wantsFixMigrateState) {
-    const archiveDir = path.join(userHome, '.cx', 'legacy');
+    const archiveDir = path.join(doctorRoot(userHome), 'legacy');
     fs.mkdirSync(archiveDir, { recursive: true });
     const ts = new Date().toISOString().replace(/[:.]/g, '-');
     const moved = [];
@@ -652,6 +653,21 @@ async function cmdDoctor() {
     );
   }
 
+  // Mirror model tier overrides stranded in the pre-XDG legacy config forward
+  // before resolving tiers, so an install upgraded across the XDG move reports
+  // configured without a manual copy. Applied to process.env too so the check
+  // below sees the just-migrated values in the same run.
+  try {
+    const { migrateLegacyModelConfig } = await import('../lib/config/legacy-config-migration.mjs');
+    const migration = migrateLegacyModelConfig({ homeDir: HOME });
+    if (migration.performed) {
+      Object.assign(process.env, migration.migrated);
+      println(`  fix: migrated ${Object.keys(migration.migrated).join(', ')} from ${migration.legacyPath} → ${migration.xdgPath}`);
+    }
+  } catch (err) {
+    add(`Models — legacy config migration failed: ${err.message}`, false, true);
+  }
+
   // Tier model selection. Construct ships with no default — at least
   // one tier must be configured (registry.json primary OR CX_MODEL_*
   // env override) before any LLM-backed workflow can run.
@@ -739,13 +755,13 @@ async function cmdDoctor() {
     const vscodeSettingsOk = vscodeSettingsPaths.some((candidate) => fs.existsSync(candidate));
     if (vscodeSettingsOk) add('VS Code settings file', true, true);
   }
-  add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(path.join(HOME, '.construct')), true);
+  add('User config ready', fs.existsSync(getUserEnvPath(HOME)) || fs.existsSync(configDir(HOME)), true);
   add('skills/ directory', fs.existsSync(path.join(ROOT_DIR, 'skills')));
   add('rules/common/', fs.existsSync(path.join(ROOT_DIR, 'rules', 'common')));
   add('specialists/prompts/ directory', fs.existsSync(path.join(ROOT_DIR, 'specialists', 'prompts')));
   add('Hybrid storage env keys documented', fs.existsSync(path.join(ROOT_DIR, '.env.example')));
-  fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
-  add('~/.cx/performance-reviews/ ready', true);
+  fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
+  add('performance-reviews/ ready', true);
 
   // construct.config.json — optional today (config is permitted to be absent;
   // env vars + defaults still work). The check enforces that when the file
@@ -765,33 +781,29 @@ async function cmdDoctor() {
 
   // Claude Code Stop-hook installation check. The settings template
   // wires several Stop hooks (policy-engine / stop-typecheck /
-  // stop-notify / readme-age-check) that reference
-  // $HOME/.construct/lib/hooks/*. If that path doesn't resolve, every
-  // Stop hook fails silently — including stop-notify, which is what
-  // appends session cost data. Result: the dashboard stops updating
-  // and the user sees stale data. Surface loudly so the fix is one
-  // command away.
+  // stop-notify / readme-age-check) whose commands sync resolves to the
+  // hook lib symlink. If those scripts don't resolve, every Stop hook
+  // fails silently — including stop-notify, which is what appends session
+  // cost data. Result: the dashboard stops updating and the user sees stale
+  // data. Surface loudly so the fix is one command away.
   try {
     const settingsPath = path.join(HOME, '.claude', 'settings.json');
     if (fs.existsSync(settingsPath)) {
       const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
       const stopHooks = settings?.hooks?.Stop || [];
-      const installRoot = path.join(HOME, '.construct', 'lib', 'hooks');
-      const installed = fs.existsSync(installRoot);
+      const installRoot = path.join(configDir(HOME), 'lib', 'hooks');
       const referenced = [];
       for (const group of stopHooks) {
         for (const h of (group?.hooks || [])) {
           const cmd = String(h?.command || '');
-          const m = cmd.match(/\.construct\/lib\/hooks\/([a-zA-Z0-9_-]+\.mjs)/);
+          const m = cmd.match(/(?:^|["\s])(\/[^"\s]*\/lib\/hooks\/[a-zA-Z0-9_-]+\.mjs)/);
           if (m) referenced.push(m[1]);
         }
       }
-      const missing = installed
-        ? referenced.filter((f) => !fs.existsSync(path.join(installRoot, f)))
-        : referenced;
+      const missing = referenced.filter((scriptPath) => !fs.existsSync(scriptPath));
       if (referenced.length > 0 && missing.length > 0) {
         add(
-          `Claude Stop hooks broken: ${missing.length} hook${missing.length === 1 ? '' : 's'} missing in ~/.construct/lib/hooks/. Symlink the install: ln -sfn ${ROOT_DIR}/lib ~/.construct/lib`,
+          `Claude Stop hooks broken: ${missing.length} hook${missing.length === 1 ? '' : 's'} do not resolve. Re-run \`construct install --scope=user\` (symlinks ${ROOT_DIR}/lib → ${installRoot.replace(/\/hooks$/, '')}).`,
           false,
           false,
         );
@@ -1073,7 +1085,7 @@ async function cmdDoctor() {
     }
 
     try {
-      const failuresPath = path.join(HOME, '.cx', 'hook-failures.jsonl');
+      const failuresPath = path.join(doctorRoot(), 'hook-failures.jsonl');
       if (fs.existsSync(failuresPath)) {
         const lines = fs.readFileSync(failuresPath, 'utf8').trim().split('\n').filter(Boolean);
         const cutoff = Date.now() - 24 * 60 * 60 * 1000;
@@ -1519,7 +1531,7 @@ async function cmdMigrate(args) {
 }
 
 async function cmdReview(args) {
-  fs.mkdirSync(path.join(HOME, '.cx', 'performance-reviews'), { recursive: true });
+  fs.mkdirSync(path.join(doctorRoot(), 'performance-reviews'), { recursive: true });
   const sub = args[0];
 
   if (!sub || sub === 'run') {
@@ -2018,7 +2030,7 @@ async function _cmdPricing(args) {
     const f = describePricingCatalogFreshness();
     if (!f.present) { info(f.message); return; }
     try {
-      const cached = JSON.parse(fs.readFileSync(path.join(HOME, '.cx', 'pricing-cache.json'), 'utf8'));
+      const cached = JSON.parse(fs.readFileSync(path.join(doctorRoot(), 'pricing-cache.json'), 'utf8'));
       const divergences = checkPricingDivergence(cached.models || []);
       if (divergences.length === 0) { info('No pricing divergences (>25%) between LiteLLM and the static fallback.'); return; }
       println(`⚠  ${divergences.length} divergence(s):`);
@@ -2116,15 +2128,13 @@ async function printIntakeHelp() {
   println('  construct intake metrics               Show pipeline volume, velocity, and processing stats.');
   println('  construct intake integrate <id> <system>    Push intake to external system (github, jira, confluence).');
   println('  construct intake integrate <id> <system> --create-issue  Create an issue from the intake packet.');
-  println('  construct intake config               Show current watch dirs + scan depth.');
+  println('  construct intake config               Show the inbox/ drop zone + scan depth.');
   println('  construct intake config set --depth=N [--add-dir=PATH] [--remove-dir=PATH]');
+  println('                                       Update intake config. --depth caps at the hard limit.');
   println('  construct intake extraction-warnings [--since=7d] [--kind=table] [--limit=50]');
   println('                                       Summarize ~/.cx/intake/extraction-warnings.jsonl (dropped content log).');
   println('  construct intake needs-asr list       List audio/video files awaiting ASR transcription.');
   println('  construct intake needs-asr show <id>  Show a specific ASR-pending packet.');
-  println('                                       Update intake config. --depth caps at the hard limit.');
-  println('  construct intake config set --include-project-inbox=on|off');
-  println('  construct intake config set --include-docs-intake=on|off');
 }
 
 function parseKvFlags(args, keys) {
@@ -2618,7 +2628,6 @@ async function cmdIntakeReroute(args, cwd) {
 
 async function cmdIntakeExtractionWarnings(args) {
   const { createReadStream, existsSync } = await import('node:fs');
-  const { homedir } = await import('node:os');
   const { join } = await import('node:path');
   const { createInterface } = await import('node:readline');
 
@@ -2636,7 +2645,7 @@ async function cmdIntakeExtractionWarnings(args) {
     }
   }
 
-  const logPath = join(homedir(), '.cx', 'intake', 'extraction-warnings.jsonl');
+  const logPath = join(doctorRoot(), 'intake', 'extraction-warnings.jsonl');
   if (!existsSync(logPath)) {
     println('No extraction warnings recorded yet.');
     return;
@@ -2687,11 +2696,10 @@ async function cmdIntakeExtractionWarnings(args) {
 
 async function cmdIntakeNeedsAsr(args) {
   const { existsSync, readdirSync, readFileSync } = await import('node:fs');
-  const { homedir } = await import('node:os');
   const { join } = await import('node:path');
 
   const sub = args[0] || 'list';
-  const asrDir = join(homedir(), '.cx', 'intake', 'needs-asr');
+  const asrDir = join(doctorRoot(), 'intake', 'needs-asr');
 
   if (sub === 'list') {
     if (!existsSync(asrDir)) { println('No audio/video files awaiting ASR.'); return; }
@@ -2856,33 +2864,23 @@ async function cmdIntakeConfig(args) {
   const cwd = process.cwd();
 
   const action = args[0];
-  if (action === 'migrate') {
-    const { migrateLegacyIntakeConfig } = await import('../lib/intake/intake-config.mjs');
-    const result = migrateLegacyIntakeConfig(cwd);
-    if (!result.migrated) {
-      info(result.reason ?? 'nothing to migrate');
-      return;
-    }
-    info('Migrated .cx/intake-config.json → construct.config.json intakePolicy');
-    println(JSON.stringify(result.policy, null, 2));
-    return;
-  }
+
+  // Single-zone model (ADR-0045 §C): the canonical `inbox/` is always watched.
+  // Only maxDepth and additionalDirs are configurable.
 
   if (!action || action === 'show') {
     const cfg = loadIntakeConfig(cwd, process.env);
     const desc = describeIntakeDepth(cfg.maxDepth);
     println(`Intake config (root: ${cwd})`);
     println('');
-    println(`  includeProjectInbox: ${cfg.includeProjectInbox ? 'on' : 'off'} (.cx/inbox)`);
-    println(`  includeRootInbox:    ${(cfg.includeRootInbox ?? cfg.includeArchetypeInbox) ? 'on' : 'off'} (inbox/)`);
-    println(`  includeDocsIntake:   ${cfg.includeDocsIntake ? 'on' : 'off'} (docs/intake)`);
+    println('  drop zone:           inbox/ (always watched)');
     println(`  maxDepth:            ${cfg.maxDepth} — ${desc.label}`);
     println(`                       ${desc.detail}`);
     println(`  hardMaxDepth:        ${INTAKE_HARD_MAX_DEPTH}`);
     if (cfg.parentDirs.length === 0) {
-      println('  parentDirs:          (none — only the built-in zones are watched)');
+      println('  additionalDirs:      (none — only inbox/ is watched)');
     } else {
-      println('  parentDirs:');
+      println('  additionalDirs:');
       for (const dir of cfg.parentDirs) println(`    - ${dir}`);
     }
     println('');
@@ -2903,15 +2901,6 @@ async function cmdIntakeConfig(args) {
   const depthFlag = tail.find((a) => a.startsWith('--depth='));
   if (depthFlag) patch.maxDepth = Number(depthFlag.split('=')[1]);
 
-  const projectFlag = tail.find((a) => a.startsWith('--include-project-inbox='));
-  if (projectFlag) patch.includeProjectInbox = /^(on|true|1|yes)$/i.test(projectFlag.split('=')[1] || '');
-
-  const docsFlag = tail.find((a) => a.startsWith('--include-docs-intake='));
-  if (docsFlag) patch.includeDocsIntake = /^(on|true|1|yes)$/i.test(docsFlag.split('=')[1] || '');
-
-  const rootFlag = tail.find((a) => a.startsWith('--include-root-inbox='));
-  if (rootFlag) patch.includeRootInbox = /^(on|true|1|yes)$/i.test(rootFlag.split('=')[1] || '');
-
   const addFlags = tail.filter((a) => a.startsWith('--add-dir='));
   const removeFlags = tail.filter((a) => a.startsWith('--remove-dir='));
 
@@ -2924,7 +2913,7 @@ async function cmdIntakeConfig(args) {
   }
 
   if (Object.keys(patch).length === 0) {
-    errorln('Nothing to change. Pass --depth=N, --add-dir=PATH, --remove-dir=PATH, --include-project-inbox=on|off, or --include-docs-intake=on|off.');
+    errorln('Nothing to change. Pass --depth=N, --add-dir=PATH, or --remove-dir=PATH.');
     process.exit(1);
   }
 
@@ -3799,7 +3788,15 @@ async function cmdOrchestrate(args) {
 }
 
 async function cmdModels(args) {
-  if (args[0] === 'resolve') {
+  const envPath = getUserEnvPath(HOME);
+  const sub = args[0] && !args[0].startsWith('-') ? args[0] : null;
+  const KNOWN_SUBCOMMANDS = new Set(['list', 'set', 'free', 'reset', 'resolve']);
+  if (sub && !KNOWN_SUBCOMMANDS.has(sub)) {
+    errorln(`Unknown models subcommand: ${sub}. Run \`construct models --help\` for the supported set.`);
+    process.exit(1);
+  }
+
+  if (sub === 'resolve') {
     const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
     const { resolveEmbeddedModel } = await import('../lib/embedded-contract/model-resolve.mjs');
     const { wrapContractResult } = await import('../lib/embedded-contract/envelope.mjs');
@@ -3816,21 +3813,37 @@ async function cmdModels(args) {
     println(JSON.stringify(envelope, null, 2));
     return;
   }
+  // Legacy flag forms stay as compatibility aliases for the documented
+  // subcommands. Each emits a one-line deprecation notice on stderr so stdout
+  // stays clean while operators migrate to `models set|reset|free`.
   const tier = args.find((arg) => arg.startsWith('--tier='))?.split('=')[1] ?? '';
-  const setModel = args.find((arg) => arg.startsWith('--set='))?.split('=')[1] ?? '';
-  const envPath = getUserEnvPath(HOME);
-  if (args.includes('--reset')) {
+  const modelFlag = args.find((arg) => arg.startsWith('--model='))?.split('=')[1];
+  const legacySetFlag = args.find((arg) => arg.startsWith('--set='))?.split('=')[1];
+  const setModel = modelFlag ?? legacySetFlag ?? '';
+
+  if (sub === 'reset' || args.includes('--reset')) {
+    if (sub !== 'reset') errorln('Note: `construct models --reset` is a deprecated alias for `construct models reset`.');
     resetEnv(envPath);
-    println('Removed CX_MODEL_* overrides from ~/.construct/config.env.');
+    println(`Removed CX_MODEL_* overrides from ${envPath}.`);
     await cmdSync([]);
     return;
   }
-  if (tier && setModel) {
+  if (sub === 'set' || (sub === null && tier && setModel)) {
+    if (!tier || !setModel) {
+      errorln('Usage: construct models set --tier=<reasoning|standard|fast> --model=<provider/model-id>');
+      process.exit(1);
+    }
+    if (modelFlag === undefined && legacySetFlag !== undefined) {
+      errorln('Note: `--set=<model>` is a deprecated alias for `--model=<model>`.');
+    }
+    if (sub === null) {
+      errorln('Note: `construct models --tier=… --set=…` is a deprecated alias for `construct models set --tier=… --model=…`.');
+    }
     const registry = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'specialists', 'registry.json'), 'utf8'));
     const preferFree = args.includes('--prefer-free');
     const preferFreeSameFamily = args.includes('--prefer-free-same-family');
     const inferred = setModelWithTierInference(envPath, tier, setModel, registry.models ?? {}, { preferFree, preferFreeSameFamily });
-    println(`Set ${tier} -> ${setModel} in ~/.construct/config.env`);
+    println(`Set ${tier} -> ${setModel} in ${envPath}`);
     if (preferFreeSameFamily) println('Prefer-free-same-family mode: enabled');
     if (preferFree) println('Prefer-free mode: enabled');
     println(`Resolved tier set:`);
@@ -3840,7 +3853,8 @@ async function cmdModels(args) {
     await cmdSync([]);
     return;
   }
-  if (args.includes('--poll')) {
+  if (sub === 'free' || args.includes('--poll')) {
+    if (sub !== 'free') errorln('Note: `construct models --poll` is a deprecated alias for `construct models free`.');
     const apiKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
     if (!apiKey) {
       errorln('Error: no OpenRouter API key found in OPENROUTER_API_KEY or OpenCode config.');
@@ -3867,7 +3881,7 @@ async function cmdModels(args) {
       if (id) selections[currentTier] = id;
     }
     applyToEnv(envPath, selections);
-    println('Written to ~/.construct/config.env. Running construct sync...');
+    println(`Written to ${envPath}. Running construct sync...`);
     await cmdSync([]);
     return;
   }
@@ -3904,12 +3918,12 @@ async function cmdModels(args) {
     for (const [tier, model] of Object.entries(selections)) {
       println(`  ${tier.padEnd(11)} ${model}`);
     }
-    println('Written to ~/.construct/config.env. Running construct sync...');
+    println(`Written to ${envPath}. Running construct sync...`);
     setCheapestProviderPreference(envPath, true);
     await cmdSync([]);
     return;
   }
-  if (args.includes('--list') || args[0] === 'list') {
+  if (args.includes('--list') || sub === 'list') {
     const { getProviderModelCatalog } = await import('../lib/model-router.mjs');
     const { listChatModels } = await import('../apps/chat/engine/models.mjs');
     const catalog = getProviderModelCatalog({ env: process.env, cwd: process.cwd() });
@@ -3939,7 +3953,7 @@ async function cmdModels(args) {
     println('No tier has a model selected. Construct ships with no default.');
     println('Pick one of:');
     println('  • Dashboard → Models page (single source of truth)');
-    println('  • construct models --set=<provider/model-id> --tier=reasoning|standard|fast');
+    println('  • construct models set --tier=<reasoning|standard|fast> --model=<provider/model-id>');
     println('  • construct models --apply           Poll OpenRouter free catalog and seed all tiers');
   }
 }
@@ -4034,7 +4048,7 @@ async function cmdPluginEngine(args) {
   const [action = 'list', ...rest] = args;
   const isGlobal = rest.includes('--global');
   const targetPath = isGlobal
-    ? path.join(HOME, '.construct', 'plugins.json')
+    ? path.join(configDir(HOME), 'plugins.json')
     : path.join(process.cwd(), '.cx', 'plugins.json');
 
   function readPluginsJson() {
@@ -4241,7 +4255,7 @@ async function cmdEvals(args) {
     const report = await evaluateFixture(fixturePath);
 
     try {
-      const cacheDir = path.join(HOME, '.cx', 'evals');
+      const cacheDir = path.join(doctorRoot(), 'evals');
       fs.mkdirSync(cacheDir, { recursive: true });
       const ts = new Date().toISOString();
       fs.writeFileSync(
@@ -4438,7 +4452,7 @@ async function cmdDocsCheck(args) {
     println('Commands with no linked how-to in docs/README.md:');
     for (const name of result.uncovered) println(`  ✗  construct ${name}`);
     println('');
-    println(`Add cookbook recipes under docs/cookbook/ and link them from the cookbook index.`);
+    println(`Add cookbook recipes under docs/guides/cookbook/ and link them from the cookbook index.`);
     process.exitCode = 1;
   }
 }
@@ -4449,7 +4463,7 @@ async function cmdDocsSite(args = []) {
   if (check) {
     const { drift } = checkFumadocsReferenceDrift({ rootDir: ROOT_DIR });
     if (drift.length === 0) {
-      ok('docs/reference/ is up to date.');
+      ok('docs/guides/reference/ is up to date.');
       return;
     }
     println('');
@@ -4460,9 +4474,9 @@ async function cmdDocsSite(args = []) {
   }
   const { written } = buildFumadocsReference({ rootDir: ROOT_DIR });
   if (written.length === 0) {
-    ok('docs/reference/ already up to date.');
+    ok('docs/guides/reference/ already up to date.');
   } else {
-    ok(`docs/reference/ regenerated (${written.length} file${written.length === 1 ? '' : 's'}).`);
+    ok(`docs/guides/reference/ regenerated (${written.length} file${written.length === 1 ? '' : 's'}).`);
   }
 }
 
@@ -4961,7 +4975,7 @@ async function cmdProvider(args) {
       if (!id) { errorln(`Usage: construct provider plugins ${action} <id> [<package>]`); process.exit(1); }
       const isGlobal = args.includes('--global');
       const targetPath = isGlobal
-        ? path.join(HOME, '.construct', 'providers.json')
+        ? path.join(configDir(HOME), 'providers.json')
         : path.join(process.cwd(), '.cx', 'providers.json');
       let data = { providers: [] };
       try { data = JSON.parse(fs.readFileSync(targetPath, 'utf8')); } catch { /* fresh */ }
@@ -5486,7 +5500,7 @@ async function cmdTelemetryQuery(args) {
   println('  errors [--agent=<name>] [--since=24h]                error span summary');
   println('  trace <traceId>                                       full span tree');
   println('');
-  println('For Langfuse/Honeycomb/Grafana Tempo/Datadog, see docs/concepts/observability.md');
+  println('For Langfuse/Honeycomb/Grafana Tempo/Datadog, see docs/guides/concepts/observability.md');
 }
 
 async function cmdHook(args) {
@@ -6553,7 +6567,7 @@ const handlers = new Map([
 
         println('');
         println(`Scaffolding a new profile draft. Three questions, then a preview.`);
-        println(`Background: docs/concepts/persona-research.md and docs/concepts/profile-lifecycle.md`);
+        println(`Background: docs/guides/concepts/persona-research.md and docs/guides/concepts/profile-lifecycle.md`);
         println('');
         if (!displayName) displayName = await ask('Display name?', id);
         if (seedDepartments.length === 0) {
@@ -6612,7 +6626,7 @@ const handlers = new Map([
         println('');
         println(`✓ draft created at ${pathMod.relative(process.cwd(), result.dir)}`);
         println('');
-        println(`Next steps (in order, per docs/concepts/profile-lifecycle.md):`);
+        println(`Next steps (in order, per docs/guides/concepts/profile-lifecycle.md):`);
         println(`  1. Discover  (cx-ux-researcher): fill personas/<role>.md from interviews + primary sources.`);
         println(`  2. Frame     (cx-product-manager): fill departments/<dept>.md charters and intake taxonomy.`);
         println(`  3. Architect (cx-architect): reconcile role reuse vs new; populate departments[] in profile.json.`);

package/commands/plan/decide.md

@@ -11,4 +11,4 @@ ADR format:
 - FILES AFFECTED: paths future contributors should inspect
 - FOLLOW-UP: docs, tests, migrations, or risks to track
 
-Save to `docs/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/` if those directories exist.
+Save to `docs/decisions/adr/ADR-{NNN}-{slug}.md` and `.cx/decisions/` if those directories exist.

package/commands/remember/runbook.md

@@ -11,4 +11,4 @@ Structure:
 - ROLLBACK: how to undo if something goes wrong
 - ESCALATION: who to contact and when
 
-Save to `docs/runbooks/{service}-{operation}.md` if the directory exists.
+Save to `docs/operations/runbooks/{service}-{operation}.md` if the directory exists.

package/examples/README.md

@@ -78,7 +78,7 @@ Required internal coverage:
 - Name the expected behavior in repo terms: branch confirmation, approval boundary, routing, verification, blocker surfacing, anti-pattern avoidance.
 - For bad examples, show the failure plainly and explain why it violates the surface contract.
 
-See `docs/concepts/prompt-surfaces.md` for the canonical public-vs-internal taxonomy.
+See `docs/guides/concepts/prompt-surfaces.md` for the canonical public-vs-internal taxonomy.
 
 ## Scope
 

package/examples/distribution/README.md

@@ -39,4 +39,4 @@ Edit sources, then re-run the generator. Outputs land in `.tmp/distribution-exam
 node bin/construct export examples/distribution/sources/adr.md --to=pdf --figures
 ```
 
-See [branding.md](../../docs/reference/branding.md) and [diagram-and-demo.md](../../docs/cookbook/diagram-and-demo.md).
+See [branding.md](../../docs/guides/reference/branding.md) and [diagram-and-demo.md](../../docs/guides/cookbook/diagram-and-demo.md).

package/examples/distribution/sources/adr.md

@@ -51,7 +51,7 @@ tokens -> dash
 
 ## Decision
 
-Adopt `lib/brand-tokens.mjs` as the single source of truth for visual brand primitives. Document naming, voice, tone, and profile rebrand in `docs/reference/branding.md`. Enforce retired-font drift with `scripts/audit/03d-brand.mjs` in the audit ratchet.
+Adopt `lib/brand-tokens.mjs` as the single source of truth for visual brand primitives. Document naming, voice, tone, and profile rebrand in `docs/guides/reference/branding.md`. Enforce retired-font drift with `scripts/audit/03d-brand.mjs` in the audit ratchet.
 
 ## Rationale
 
@@ -79,6 +79,6 @@ Two-way door for documentation and audit scope; one-way for shipped PDFs already
 
 ## References
 
-- `docs/reference/branding.md`
+- `docs/guides/reference/branding.md`
 - `lib/brand-tokens.mjs`
 - https://fonts.google.com/specimen/Space+Grotesk (accessed 2026-06-22)

package/examples/distribution/sources/deck-one-pager.md

@@ -60,6 +60,6 @@ One token set across all distributable formats:
 
 - Export: `construct export … --to=pptx`
 - Regenerate: `npm run examples:deck`
-- Matrix: [Document I/O reference](/reference/document-io)
+- Matrix: [Document I/O reference](/guides/reference/document-io)
 
 Review outputs in `.tmp/distribution-examples/`.

package/examples/distribution/sources/prd-platform.md

@@ -157,5 +157,5 @@ https://langchain-ai.github.io/langgraph/ (accessed 2026-06-19).
 
 - Construct artifact manifest: `specialists/artifact-manifest.json`
 - PRD workflow skill: `skills/docs/prd-workflow.md`
-- Publish cookbook: `docs/cookbook/diagram-and-demo.md`
+- Publish cookbook: `docs/guides/cookbook/diagram-and-demo.md`
 - Golden D2 sources: `tests/fixtures/publish/diagrams/`

package/examples/distribution/sources/research-brief.md

@@ -32,7 +32,7 @@ Searched arXiv and vendor docs (2024–2026), reviewed three internal ADRs on in
 |---|---|---|---|---|---|---|---|
 | Multi-agent survey | secondary | B | 3 | 2023-08-01 | https://arxiv.org/abs/2308.08155 | yes | Patterns for specialist routing |
 | LangGraph overview | primary | A | 4 | 2025-01-15 | https://langchain-ai.github.io/langgraph/ | yes | Stateful agent graphs |
-| Construct architecture | primary | A | 5 | 2026-06-01 | docs/concepts/architecture.mdx | yes | Internal contract |
+| Construct architecture | primary | A | 5 | 2026-06-01 | docs/guides/concepts/architecture.mdx | yes | Internal contract |
 
 ## Findings
 
@@ -77,4 +77,4 @@ Ship distribution examples (`npm run examples:distribution`) so evaluators can c
 ## References
 
 - https://arxiv.org/abs/2308.08155 (accessed 2026-06-22)
-- `docs/cookbook/diagram-and-demo.md`
+- `docs/guides/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/rfc-platform.md

@@ -78,5 +78,5 @@ sequenceDiagram
 
 ## References
 
-- `docs/reference/branding.md`
+- `docs/guides/reference/branding.md`
 - `scripts/generate-deck-examples.mjs` (prior art)

package/examples/distribution/sources/runbook.md

@@ -99,5 +99,5 @@ Preserve `construct tools detect --json` output and the failing pandoc/typst std
 
 ## References
 
-- `docs/reference/document-io.md`
-- `docs/cookbook/diagram-and-demo.md`
+- `docs/guides/reference/document-io.md`
+- `docs/guides/cookbook/diagram-and-demo.md`

package/examples/distribution/sources/strategy.md

@@ -26,7 +26,7 @@ Host-native agents optimize for single-session chat. Enterprise platform teams n
 ## Goals
 
 1. **Prove value in five minutes** — `npm run examples:distribution` produces a browsable gallery with figures.
-2. **One brand contract** — `docs/reference/branding.md` + `03d-brand` audit ratchet.
+2. **One brand contract** — `docs/guides/reference/branding.md` + `03d-brand` audit ratchet.
 3. **Profile-aware language** — intake queue labels follow active profile rebrand in CLI, session prelude, and dashboard API.
 
 ## Non-goals

package/lib/agent-instructions/inject.mjs

@@ -71,7 +71,7 @@ export function buildConstructIntegrationBody({ hasBeadsBlock = false, variant =
     '- **Durable state** lives in `.cx/` (context, knowledge, intake, traces) and Beads.',
     '  If services are down, resume from `plan.md`, `.cx/context.md`, the latest',
     '  `.cx/handoffs/` file, Beads, and git.',
-    '- **Signals**: drop a file into `.cx/inbox/`; `construct intake` classifies and routes it.',
+    '- **Signals**: drop a file into `inbox/`; `construct intake` classifies and routes it.',
     '- **Specialists** (architect, reviewer, security, …) are dispatched by Construct — you',
     '  do not call them directly.',
     tracker,

package/lib/artifact-type-from-path.mjs

@@ -41,12 +41,16 @@ function inferRfcSubtype(rel, base) {
   return 'rfc';
 }
 
+// Match both this repo's bucketed layout (docs/specs/prd, docs/decisions/adr, …)
+// and the init-lane layout that `construct init` scaffolds downstream (docs/prd,
+// docs/adr, …), so artifact-type inference works in either project shape.
+
 const PREFIX_RULES = [
-  [/^docs\/prd\//, inferPrdSubtype],
-  [/^docs\/adr\//, () => 'adr'],
-  [/^docs\/rfc\//, inferRfcSubtype],
-  [/^docs\/research\//, () => 'research-brief'],
-  [/^docs\/runbooks?\//, () => 'runbook'],
+  [/^docs\/(?:specs\/)?prd\//, inferPrdSubtype],
+  [/^docs\/(?:decisions\/)?adr\//, () => 'adr'],
+  [/^docs\/(?:decisions\/)?rfc\//, inferRfcSubtype],
+  [/^docs\/(?:notes\/)?research\//, () => 'research-brief'],
+  [/^docs\/(?:operations\/)?runbooks?\//, () => 'runbook'],
   [/^\.cx\/research\//, () => 'research-brief'],
 ];
 

package/lib/audit-specialists.mjs

@@ -3,7 +3,7 @@
  *
  * Merges live registry, contracts, skills, prompts, and audit-enrichments into
  * one machine-readable matrix. Powers `construct audit specialists` and the
- * human-readable docs/concepts/specialist-skill-audit.md companion.
+ * human-readable docs/guides/concepts/specialist-skill-audit.md companion.
  */
 
 import fs from 'node:fs';

package/lib/audit-trail.mjs

@@ -16,17 +16,17 @@
  * Corrupted links cannot be re-derived, so a `chain_reset` boundary line seals
  * the damaged prefix as immutable legacy and re-bases the live chain;
  * verifyChain validates only from the last boundary forward. See
- * docs/concepts/observability.md.
+ * docs/guides/concepts/observability.md.
  */
 import { readFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 
 import { appendBounded, readLastLineAcrossSegments } from './logging/rotate.mjs';
 import { withFileLockSync } from './storage/file-lock.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
-const AUDIT_FILE = join(homedir(), '.cx', 'audit-trail.jsonl');
+const AUDIT_FILE = join(doctorRoot(), 'audit-trail.jsonl');
 
 function sha256(input) {
   return createHash('sha256').update(input).digest('hex');