@geraldmaron/construct 1.2.1 → 1.2.2

package/README.md

@@ -28,7 +28,7 @@ Bootstrap local services (once per machine, opt-in to machine-scope writes):
 construct install --scope=user --yes
 ```
 
-`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
+`construct install` defaults to `--scope=project`, which writes nothing and prints scope guidance — see the [footprint contract](#footprint-contract) below or [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md). Use `--scope=user` for machine setup, `--scope=both` for both.
 
 Initialize a project:
 
@@ -87,7 +87,7 @@ Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deplo
 
 ## Intake
 
-Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
+Anything dropped into `inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
 
 Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
@@ -111,11 +111,11 @@ Construct's writes are scoped and disclosed up front. The default `construct ins
 | Machine | `construct install --scope=user` | `~/.construct/config.env`, `~/.construct/lib` (symlink), `~/.construct/services/`, `~/Library/LaunchAgents/` (macOS), MCP entries in `~/.config/opencode/opencode.json` and `~/.codex/config.toml`, marker block in `~/.claude/CLAUDE.md`, hook injection in `~/.claude/settings.json` (last two require interactive consent or `--yes`) |
 | Never touched | — | Shell rc files (`~/.bashrc`, `~/.zshrc`), npm global config, `git config --global` |
 
-Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/adr/0029-install-scopes-and-hook-budgets.md).
+Full table with file:line citations and the per-hook performance budget contract: [Architecture — Footprint contract](https://geraldmaron.github.io/construct/concepts/architecture#footprint-contract) and [ADR 0029](docs/decisions/adr/0029-install-scopes-and-hook-budgets.md).
 
 ## Learning loops
 
-Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/guides/concepts/learning-loops.mdx`](./docs/guides/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
 
 ## `.cx/` is local-only runtime state
 
@@ -226,7 +226,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 | `construct doc` | Verify or inspect auditability stamps on Construct-generated markdown files |
 | `construct docs:check` | Check for missing how-to guides (alias for `docs check`) |
 | `construct docs:reconcile` | Reconcile docs against the registry |
-| `construct docs:site` | Regenerate generated reference pages under docs/reference/ |
+| `construct docs:site` | Regenerate generated reference pages under docs/guides/reference/ |
 | `construct docs:update` | Regenerate AUTO-managed doc regions (alias for `docs update`) |
 | `construct docs:verify` | Validate documentation quality (alias for `docs verify`) |
 | `construct impact` | Change-impact analysis — map changed files to affected tests, capabilities, and workflows |
@@ -269,7 +269,7 @@ The embed daemon writes its supervisor stdout log to `~/.cx/runtime/embed-daemon
 
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
 - [`CHANGELOG.md`](./CHANGELOG.md). Release history.
-- [`docs/concepts/architecture.mdx`](./docs/concepts/architecture.mdx). Canonical architecture.
+- [`docs/guides/concepts/architecture.mdx`](./docs/guides/concepts/architecture.mdx). Canonical architecture.
 - [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure

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 = [];
@@ -739,13 +740,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 +766,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 +1070,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 +1516,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 +2015,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 +2113,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 +2613,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 +2630,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 +2681,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 +2849,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 +2886,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 +2898,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);
   }
 
@@ -4034,7 +4008,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 +4215,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 +4412,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 +4423,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 +4434,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 +4935,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 +5460,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 +6527,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 +6586,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');

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