@geraldmaron/construct 1.2.1 → 1.2.2

package/lib/init-unified.mjs

@@ -175,10 +175,7 @@ function detectProjectType(targetPath) {
 function suggestLanes(targetPath, projectType) {
   const suggestions = [];
   const files = fs.readdirSync(targetPath);
-  
-  // Always suggest intake for collecting feedback
-  suggestions.push({ lane: 'intake', reason: 'Collect incoming requests and feedback', recommended: true });
-  
+
   // ADRs for any non-trivial project
   if (projectType.type !== 'docs') {
     suggestions.push({ lane: 'adrs', reason: 'Track architectural decisions', recommended: true });
@@ -365,33 +362,6 @@ Attendees: {{attendees}}
 - [ ] @owner: Task description (due: {{date}})`;
 }
 
-function buildIntakeTemplate() {
-  return `# Intake: {{source}}
-
-Received: {{date}}
-From: {{from}}
-Priority: {{priority}}
-
-## What arrived
-
-Brief description of what was received.
-
-## Why it matters
-
-Why this intake item is important to process.
-
-## How it should be ingested
-
-Processing instructions:
-- [ ] Step 1
-- [ ] Step 2
-- [ ] Step 3
-
-## Notes
-
-<!-- Caveats, access concerns, or cleanup notes. -->`;
-}
-
 function writeIfMissing(filePath, content) {
   if (fs.existsSync(filePath)) {
     skipped.push(path.relative(target, filePath));
@@ -418,8 +388,6 @@ function copyLaneTemplates(laneKey) {
       content = buildNotesTemplate();
     } else if (templateName === '__meeting-notes-template__') {
       content = buildMeetingNotesTemplate();
-    } else if (templateName === "__intake-template__") {
-      content = buildIntakeTemplate();
     } else {
       const templatePath = path.join(TEMPLATE_DIR, templateName);
       if (fs.existsSync(templatePath)) {
@@ -543,8 +511,8 @@ function discoverProjectDirs(targetPath) {
 // Extra inbox-style directories the user can opt into. These are NOT
 // source-code, doc, or test directories: they're places where unsorted
 // signals tend to land (downloads, scratch notes, exported research). The
-// built-in `.cx/inbox/` and `docs/intake/` are always watched and not
-// listed here.
+// canonical `inbox/` at the project root is always watched and not listed
+// here.
 //
 // Historically this list included `src/`, `docs/`, `tests/`, etc., and
 // `init --yes` auto-enabled every one that existed in the project. That
@@ -555,10 +523,9 @@ function discoverProjectDirs(targetPath) {
 const INTAKE_DIR_PRESETS = [];
 
 async function askIntakeCollection(targetPath, skipInteractive) {
-  // Non-interactive default: empty parentDirs. The built-in zones
-  // (.cx/inbox/ and docs/intake/ when present) handle every well-defined
-  // signal path. Users who want to watch additional directories opt in
-  // explicitly via `construct intake config set --add-dir=<path>`.
+  // Non-interactive default: empty parentDirs. The canonical `inbox/` zone
+  // handles every well-defined signal path. Users who want to watch additional
+  // directories opt in explicitly via `construct intake config set --add-dir=<path>`.
   if (skipInteractive) {
     return null;
   }
@@ -583,7 +550,7 @@ async function askIntakeCollection(targetPath, skipInteractive) {
   console.log('  INTAKE COLLECTION');
   console.log('═══════════════════════════════════════════════════════════');
   console.log('');
-  console.log('Intake watches `.cx/inbox/` and `docs/intake/` by default.');
+  console.log('Intake watches `inbox/` at the project root.');
   console.log('Add extra directories ONLY if signals (customer notes, exports,');
   console.log('PDFs, etc.) regularly land there. Do not select code or finished');
   console.log('artifact directories like src/, docs/, or tests/.');
@@ -599,7 +566,7 @@ async function askIntakeCollection(targetPath, skipInteractive) {
   if (selected.length === 0) {
     console.log('');
     console.log('No extra directories selected. The inbox watcher will scan');
-    console.log('.cx/inbox/ and docs/intake/ only. Add more later with:');
+    console.log('`inbox/` only. Add more later with:');
     console.log('  construct intake config set --add-dir=<path>');
     console.log('');
     return null;
@@ -866,37 +833,35 @@ async function main() {
 
 
   // Detect existing project content once; the result feeds three decisions
-  // below: skip .cx/inbox/ on custom intake, skip lane scaffolding for lanes
-  // already covered elsewhere, and skip per-lane templates/ when root
-  // templates/ already has them. --force bypasses every check.
+  // below: skip the inbox/ drop zone on custom intake, skip lane scaffolding
+  // for lanes already covered elsewhere, and skip per-lane templates/ when
+  // root templates/ already has them. --force bypasses every check.
 
   const { detectExistingContent, shouldSkipProjectInbox, shouldScaffoldLane, formatDeferralSummary } =
     await import('./init/detect-existing-structure.mjs');
   const detection = detectExistingContent(target);
   const inboxDecision = shouldSkipProjectInbox(detection, { force: forceScaffold });
 
-  if (inboxDecision.skip) {
-    console.log(`[init:intake] skipping .cx/inbox/ — ${inboxDecision.reason}. Run with --force to scaffold anyway.`);
-    skipped.push('.cx/inbox/ (deferred to existing intake)');
-  } else {
-    // `.cx/inbox/` is the local intake drop zone the watcher polls; under the gitignored
-    // `.cx/` tree the directory must exist on disk but needs no keep file.
-
-    fs.mkdirSync(path.join(target, ".cx", "inbox"), { recursive: true });
-    created.push(".cx/inbox/");
-  }
-
-  // Universal project-root inbox/ drop zone. Raw drops stay out of source via
-  // host-disposition IGNORED_PATTERNS (ADR-0027 §1). Skipped when custom intake
-  // pipeline already owns the project root.
+  // Single canonical drop zone (ADR-0045 §C): the visible project-root `inbox/`.
+  // Raw drops stay out of source via host-disposition IGNORED_PATTERNS
+  // (ADR-0027 §1). Machine/runtime intake state lives under the gitignored
+  // `.cx/intake/` tree, created lazily by the queue on first use — init no
+  // longer scaffolds the deprecated `.cx/inbox/` drop zone. Skipped when a
+  // custom intake pipeline already owns the project root.
 
   if (!inboxDecision.skip) {
-    const projectInbox = path.join(target, 'inbox');
-    if (!fs.existsSync(projectInbox)) {
-      fs.mkdirSync(projectInbox, { recursive: true });
+    const rootInbox = path.join(target, 'inbox');
+    if (!fs.existsSync(rootInbox)) {
+      fs.mkdirSync(rootInbox, { recursive: true });
       created.push('inbox/');
     }
 
+    // Writers assemble files under `inbox/.staging/` and atomically rename them
+    // into `inbox/`; the gitignored staging dir keeps a half-written drop
+    // invisible to the watcher until it lands.
+
+    fs.mkdirSync(path.join(rootInbox, '.staging'), { recursive: true });
+
     if (intakeCap?.dedup === 'sha256') {
       const { saveManifest, loadManifest, MANIFEST_REL_PATH } = await import('./intake/manifest.mjs');
       const manifestExists = fs.existsSync(path.join(target, MANIFEST_REL_PATH));
@@ -906,11 +871,10 @@ async function main() {
       }
     }
   } else {
+    console.log(`[init:intake] skipping inbox/ — ${inboxDecision.reason}. Run with --force to scaffold anyway.`);
     skipped.push('inbox/ (deferred to existing intake)');
   }
 
-  // Legacy archetype block removed — root inbox/ is universal (construct-1arm).
-
   // Gitignore every Construct-generated artifact whose disposition is `ignored`
   // (ADR-0027 §1): the six adapter dirs, the `.construct/` launcher, `.cx/`
   // runtime state, and the generated config files all carry machine-specific
@@ -1075,28 +1039,18 @@ async function main() {
     console.warn(`⚠️  Could not inject agent-instruction block: ${err.message}`);
   }
 
-  // Intake collection — always write intake-config.json with safe defaults
-  // so the user can inspect what's watched and edit the file directly. Empty
-  // parentDirs is the correct default: the inbox watcher always scans
-  // .cx/inbox/ and docs/intake/ (when present); extra dirs are opt-in.
+  // Intake policy — write the single-zone model (ADR-0045 §C) so the user can
+  // inspect what's watched and edit it directly. The canonical `inbox/` at the
+  // project root is the only drop zone; empty parentDirs is correct — extra
+  // dirs are opt-in.
 
   const intakeConfig = (await askIntakeCollection(target, skipInteractive)) ?? { parentDirs: [], maxDepth: 4 };
 
-  if (inboxDecision.skip) intakeConfig.includeProjectInbox = false;
-
-  intakeConfig.includeRootInbox = !inboxDecision.skip;
-  intakeConfig.includeArchetypeInbox = intakeConfig.includeRootInbox;
-
   const { saveIntakePolicy } = await import('./config/intake-policy.mjs');
   try {
     saveIntakePolicy(target, {
       maxDepth: intakeConfig.maxDepth,
       additionalDirs: intakeConfig.parentDirs ?? [],
-      zones: {
-        rootInbox: intakeConfig.includeRootInbox !== false,
-        projectInbox: intakeConfig.includeProjectInbox !== false,
-        docsIntake: intakeConfig.includeDocsIntake !== false,
-      },
     });
     created.push('construct.config.json (intakePolicy)');
   } catch (err) {
@@ -1115,7 +1069,7 @@ async function main() {
   // Create documentation system if lanes specified
   if (lanes.length > 0) {
     // Filter out lanes that the project already covers elsewhere
-    // (issue #97: don't create docs/meetings/ when internal/meetings/
+    // (issue #97: don't create docs/notes/meetings/ when internal/meetings/
     // has 12 markdown files). --force bypasses the filter.
 
     const deferredLanes = [];
@@ -1210,7 +1164,7 @@ async function main() {
     const seed = await syncFileStateToSql(target, { env: process.env, project: projectName });
     if (seed?.status === 'ok' && (seed.documentsSynced || 0) > 0) {
       console.log(`\n🔍 Indexed existing project material: ${seed.documentsSynced} doc(s), ${seed.embeddingsSynced || 0} embeddings.`);
-      console.log(`   The agent can now compare new intake (.cx/inbox/, docs/intake/) against your existing PRDs, ADRs, and notes.`);
+      console.log(`   The agent can now compare new intake (inbox/) against your existing PRDs, ADRs, and notes.`);
     }
   } catch { /* silent — corpus seeding is best-effort, not a setup blocker */ }
   
@@ -1241,9 +1195,9 @@ async function main() {
     console.log(`${++step}. Edit plan.md`);
     console.log('   Add your current work and tasks');
     console.log('');
-    if (lanes.includes('intake')) {
+    if (created.includes('inbox/')) {
       console.log(`${++step}. Use Intake`);
-      console.log('   Drop files in .cx/inbox/ for processing');
+      console.log('   Drop files in inbox/ for processing');
       console.log('   Run: construct intake');
       console.log('');
     }

package/lib/init.mjs

@@ -77,12 +77,14 @@ function main() {
     content: `${JSON.stringify({ version: 1, formality: 3, toneOverride: {}, audienceLexicon: { prefer: [], avoid: [] } }, null, 2)}\n`,
     generator: "construct/init",
   });
-  // `.cx/` already exists from the context writes above and is gitignored in full
-  // (ADR-0027), so a keep file there could never be tracked; `.cx/inbox/` is the local
-  // intake drop zone the watcher polls. Create the directories; write no dead keep file.
+  // Single canonical drop zone (ADR-0045 §C): the visible project-root `inbox/`,
+  // covered by the host .gitignore (ADR-0027 §1). Writers stage under the
+  // gitignored `inbox/.staging/` and atomically rename in; the watcher consumes
+  // only complete top-level files. Machine/runtime intake state lives under the
+  // gitignored `.cx/intake/`, created lazily by the queue.
 
-  fs.mkdirSync(path.join(target, ".cx", "inbox"), { recursive: true });
-  created.push(".cx/inbox/");
+  fs.mkdirSync(path.join(target, "inbox", ".staging"), { recursive: true });
+  created.push("inbox/");
 
   process.stdout.write(`\nConstruct init → ${target}\n\n`);
   if (created.length) {

package/lib/install/desktop-binary-download.mjs

@@ -2,7 +2,8 @@
  * lib/install/desktop-binary-download.mjs — downloads the Construct chat desktop binary.
  *
  * Fetches the platform-matching construct-chat binary from the latest GitHub
- * release and writes it to ~/.construct/bin/. Called by `construct install --scope=user`.
+ * release and writes it to the bin/ subdir of the XDG state dir. Called by
+ * `construct install --scope=user`.
  * Network failures are non-fatal: returns { status: 'skipped', reason } so the
  * rest of setup can proceed without the desktop binary.
  */
@@ -10,6 +11,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { stateDir } from '../config/xdg.mjs';
+
 const GITHUB_REPO = 'geraldmaron/construct';
 
 function assetName() {
@@ -46,7 +49,7 @@ async function downloadAsset(url, dest, env) {
 
 // Returns { status: 'downloaded'|'skipped'|'failed' }; 'skipped' and 'failed' are both non-fatal.
 export async function downloadDesktopBinary({ homeDir, env = process.env } = {}) {
-  const binDir = path.join(homeDir, '.construct', 'bin');
+  const binDir = path.join(stateDir(homeDir), 'bin');
   const dest = path.join(binDir, destBinaryName());
   const name = assetName();
 

package/lib/intake/daemon.mjs

@@ -1,10 +1,14 @@
 /**
  * lib/intake/daemon.mjs — Continuous intake daemon with safeguards.
  *
- * Polls `.cx/inbox/` for new files, classifies them via the existing intake
- * classifier, and writes packets to `.cx/intake/pending/`. Packets past their
- * TTL move to `.cx/intake/dead-letter/`; failed classification retries up to
- * the budget then dead-letters with the failure reason.
+ * Polls the canonical project-root `inbox/` for new files, classifies them via
+ * the existing intake classifier, and writes packets to `.cx/intake/pending/`.
+ * Packets past their TTL move to `.cx/intake/dead-letter/`; failed
+ * classification retries up to the budget then dead-letters with the reason.
+ *
+ * Atomic handoff (ADR-0045 §C): only complete top-level files are enqueued.
+ * Dotfiles and the `inbox/.staging/` assembly directory are skipped, so a file
+ * a writer is still staging is invisible until it is renamed into `inbox/`.
  *
  * Built on lib/daemons/contract.mjs — every safeguard (bounded lifetime,
  * idle shutdown, heartbeat, killswitch, single-writer lock) applies.
@@ -12,30 +16,49 @@
 
 import { readdirSync, statSync, readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
 import { join, basename } from 'node:path';
-import { homedir } from 'node:os';
 
 import { createDaemon, classifyPacket } from '../daemons/contract.mjs';
 import { memoryCapMbFor } from '../resources/process-budget.mjs';
+import { stateDir } from '../config/xdg.mjs';
 
 const KILLSWITCH_ENV = 'CONSTRUCT_INTAKE_DAEMON';
 
-function inboxDir(cwd) { return join(cwd, '.cx', 'inbox'); }
+function inboxDir(cwd) { return join(cwd, 'inbox'); }
 function pendingDir(cwd) { return join(cwd, '.cx', 'intake', 'pending'); }
 function deadLetterDir(cwd) { return join(cwd, '.cx', 'intake', 'dead-letter'); }
-function heartbeatPath() { return join(homedir(), '.construct', 'intake-daemon.heartbeat'); }
+function heartbeatPath() { return join(stateDir(), 'intake-daemon.heartbeat'); }
 
 function ensureDir(dir) {
   try { mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
 }
 
+// A writer staging into `inbox/.staging/` and renaming into `inbox/` is the
+// atomic handoff. As a backstop for writers that drop in place, a file whose
+// size is still moving between two stats is mid-write — skip it this tick.
+
+function isSizeStable(full) {
+  try {
+    const a = statSync(full);
+    const b = statSync(full);
+    return a.size === b.size;
+  } catch {
+    return false;
+  }
+}
+
 function listInboxFiles(cwd) {
   const dir = inboxDir(cwd);
   if (!existsSync(dir)) return [];
   let entries;
   try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+
+  // Only complete top-level files: dotfiles (and the `.staging/` assembly dir)
+  // are skipped, so a file a writer is still staging is invisible until rename.
+
   return entries
     .filter((e) => e.isFile() && !e.name.startsWith('.'))
-    .map((e) => join(dir, e.name));
+    .map((e) => join(dir, e.name))
+    .filter((full) => isSizeStable(full));
 }
 
 /**

package/lib/intake/intake-config.mjs

@@ -1,16 +1,14 @@
 /**
  * lib/intake/intake-config.mjs — intake watcher config facade.
  *
- * Reads and writes intake policy via construct.config.json intakePolicy.
- * Legacy .cx/intake-config.json remains a warned compatibility fallback.
+ * Reads and writes intake policy via construct.config.json intakePolicy, the
+ * only config source (single-zone model, ADR-0045 §C).
  */
 
 import { shouldCreateCx } from '../project-detection.mjs';
 import {
-  loadIntakePolicy,
   resolvedIntakeConfig,
   saveIntakePolicy,
-  migrateLegacyIntakeConfig,
   DEFAULT_INTAKE_POLICY,
 } from '../config/intake-policy.mjs';
 import {
@@ -19,38 +17,22 @@ import {
   INTAKE_DEPTH_GUIDANCE,
   describeIntakeDepth,
 } from './constants.mjs';
-import { INTAKE_CONFIG_FILE } from './legacy-paths.mjs';
-import { join } from 'node:path';
 
 export {
   INTAKE_DEFAULT_MAX_DEPTH,
   INTAKE_HARD_MAX_DEPTH,
   INTAKE_DEPTH_GUIDANCE,
   describeIntakeDepth,
-  INTAKE_CONFIG_FILE,
-  migrateLegacyIntakeConfig,
   DEFAULT_INTAKE_POLICY,
 };
 
 export const DEFAULT_INTAKE_CONFIG = Object.freeze({
   parentDirs: [],
   maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
-  includeProjectInbox: true,
-  includeDocsIntake: true,
-  includeArchetypeInbox: true,
-  includeRootInbox: true,
 });
 
-export function intakeConfigPath(rootDir) {
-  return join(rootDir, INTAKE_CONFIG_FILE);
-}
-
 export function loadIntakeConfig(rootDir, env = process.env) {
-  const cfg = resolvedIntakeConfig(rootDir, env);
-  if (cfg.legacyWarning && process.stderr.isTTY) {
-    process.stderr.write(`[intake-config] ${cfg.legacyWarning}\n`);
-  }
-  return cfg;
+  return resolvedIntakeConfig(rootDir, env);
 }
 
 export function saveIntakeConfig(rootDir, patch = {}) {
@@ -60,24 +42,15 @@ export function saveIntakeConfig(rootDir, patch = {}) {
 
   const policyPatch = {};
   if (patch.maxDepth !== undefined) policyPatch.maxDepth = patch.maxDepth;
-  if (patch.includeProjectInbox !== undefined) policyPatch.projectInbox = patch.includeProjectInbox;
-  if (patch.includeDocsIntake !== undefined) policyPatch.docsIntake = patch.includeDocsIntake;
-  if (patch.includeArchetypeInbox !== undefined || patch.includeRootInbox !== undefined) {
-    policyPatch.rootInbox = patch.includeRootInbox ?? patch.includeArchetypeInbox;
-  }
   if (Array.isArray(patch.parentDirs)) policyPatch.additionalDirs = patch.parentDirs;
 
   const { policy } = saveIntakePolicy(rootDir, policyPatch);
-  return policyToLegacyShape(policy);
+  return policyToConfigShape(policy);
 }
 
-function policyToLegacyShape(policy) {
+function policyToConfigShape(policy) {
   return {
     parentDirs: policy.additionalDirs,
     maxDepth: policy.maxDepth,
-    includeProjectInbox: policy.zones.projectInbox,
-    includeDocsIntake: policy.zones.docsIntake,
-    includeArchetypeInbox: policy.zones.rootInbox,
-    includeRootInbox: policy.zones.rootInbox,
   };
 }

package/lib/integrations/intake-integrations.mjs

@@ -18,6 +18,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
+import { configDir } from '../config/xdg.mjs';
 
 // ── Multi-method auth helpers ────────────────────────────────────────────
 
@@ -268,8 +269,8 @@ export async function createJiraTicket(packet, { host, email, token, project, is
   const resolvedToken = token || auth.token || process.env.JIRA_API_TOKEN;
   const resolvedProject = project || auth.project || process.env.JIRA_PROJECT;
 
-  if (!resolvedHost) return { ok: false, externalUrl: null, externalId: null, error: 'JIRA_HOST not set (e.g. https://your-domain.atlassian.net). Check ~/.construct/config.env or shell rc.' };
-  if (!resolvedEmail || !resolvedToken) return { ok: false, externalUrl: null, externalId: null, error: 'JIRA_USER and JIRA_API_TOKEN required. Check ~/.construct/config.env, ~/.env, or 1Password.' };
+  if (!resolvedHost) return { ok: false, externalUrl: null, externalId: null, error: 'JIRA_HOST not set (e.g. https://your-domain.atlassian.net). Check ~/.config/construct/config.env or shell rc.' };
+  if (!resolvedEmail || !resolvedToken) return { ok: false, externalUrl: null, externalId: null, error: 'JIRA_USER and JIRA_API_TOKEN required. Check ~/.config/construct/config.env, ~/.env, or 1Password.' };
   if (!resolvedProject) return { ok: false, externalUrl: null, externalId: null, error: 'JIRA_PROJECT not set (e.g. PROJ)' };
 
   const t = packet?.triage || {};
@@ -385,8 +386,8 @@ export async function publishArtifactToConfluence(artifact, { host, email, token
   const resolvedToken = token || auth.token || process.env.CONFLUENCE_API_TOKEN;
   const resolvedSpace = space || auth.space || process.env.CONFLUENCE_SPACE;
 
-  if (!resolvedHost) return { ok: false, externalUrl: null, externalId: null, error: 'CONFLUENCE_HOST not set (e.g. https://your-domain.atlassian.net/wiki). Check ~/.construct/config.env or shell rc.' };
-  if (!resolvedEmail || !resolvedToken) return { ok: false, externalUrl: null, externalId: null, error: 'CONFLUENCE_USER and CONFLUENCE_API_TOKEN required. Check ~/.construct/config.env, ~/.env, or 1Password.' };
+  if (!resolvedHost) return { ok: false, externalUrl: null, externalId: null, error: 'CONFLUENCE_HOST not set (e.g. https://your-domain.atlassian.net/wiki). Check ~/.config/construct/config.env or shell rc.' };
+  if (!resolvedEmail || !resolvedToken) return { ok: false, externalUrl: null, externalId: null, error: 'CONFLUENCE_USER and CONFLUENCE_API_TOKEN required. Check ~/.config/construct/config.env, ~/.env, or 1Password.' };
   if (!resolvedSpace) return { ok: false, externalUrl: null, externalId: null, error: 'CONFLUENCE_SPACE not set (e.g. PROD)' };
 
   const prefix = { prd: 'PRD', adr: 'ADR', rfc: 'RFC' }[artifact.type] || artifact.type.toUpperCase();
@@ -608,7 +609,7 @@ function resolveCredentialSync(varName, homeDir) {
     }
   } catch { /* skip */ }
   try {
-    const cfgPath = join(homeDir, '.construct', 'config.env');
+    const cfgPath = join(configDir(homeDir), 'config.env');
     if (existsSync(cfgPath)) {
       const content = readFileSync(cfgPath, 'utf8');
       const m = content.match(new RegExp(`^${varName}=(.+)$`, 'm'));
@@ -703,9 +704,9 @@ function resolveCredential(varName, homeDir) {
     }
   } catch { /* skip */ }
 
-  // ~/.construct/config.env
+  // config.env in the XDG config dir
   try {
-    const cfgPath = join(homeDir, '.construct', 'config.env');
+    const cfgPath = join(configDir(homeDir), 'config.env');
     if (existsSync(cfgPath)) {
       const content = readFileSync(cfgPath, 'utf8');
       const m = content.match(new RegExp(`^${varName}=(.+)$`, 'm'));

package/lib/knowledge/rag.mjs

@@ -7,7 +7,7 @@
  *
  * Sources indexed:
  *   - Observations       (.cx/observations/)
- *   - Artifacts          (docs/adr/, docs/prd/, docs/rfc/)
+ *   - Artifacts          (docs/decisions/adr/, docs/specs/prd/, docs/decisions/rfc/)
  *   - Snapshots          (.cx/snapshot.md + any configured output paths)
  *   - Approval queue     (.cx/approval-queue.jsonl)
  *
@@ -102,7 +102,7 @@ function loadMarkdownChunks(dir, source) {
  */
 function loadArtifactChunks(rootDir) {
   const chunks = [];
-  for (const subdir of ['docs/adr', 'docs/prd', 'docs/rfc', 'docs/concepts/architecture.md']) {
+  for (const subdir of ['docs/adr', 'docs/prd', 'docs/rfc', 'docs/guides/concepts/architecture.md']) {
     const full = path.resolve(rootDir, subdir);
     if (subdir.endsWith('.md')) {
       if (!fs.existsSync(full)) continue;

package/lib/knowledge/search.mjs

@@ -6,11 +6,11 @@
  * `knowledge_search` MCP tool — no daemon, no network, no external deps.
  *
  * Sources searched (in priority order):
- *   1. docs/concepts/*.md    — architecture, agents, gates, durable state
- *   2. docs/start/*.mdx      — install + first task
+ *   1. docs/guides/concepts/*.md    — architecture, agents, gates, durable state
+ *   2. docs/guides/start/*.mdx      — install + first task
  *   3. docs/README.md        — docs index + contract
  *   4. .cx/knowledge/        — operator-written internal docs
- *   5. Any *.md in docs/cookbook/ — task-oriented recipes
+ *   5. Any *.md in docs/guides/cookbook/ — task-oriented recipes
  *   6. <projectRoot>/.cx/knowledge/** — the cwd project's knowledge tree,
  *      including `external/research/` written by `construct knowledge add`,
  *      so foreign-project queries surface project content alongside bundled docs.
@@ -47,17 +47,17 @@ function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
   const sources = [];
 
   const priority = [
-    'docs/concepts/architecture.md',
-    'docs/concepts/agents-and-personas.mdx',
-    'docs/concepts/gates-and-enforcement.md',
-    'docs/concepts/beads-and-state.md',
-    'docs/concepts/prompt-surfaces.md',
-    'docs/concepts/knowledge-layout.md',
-    'docs/concepts/deployment-model.md',
-    'docs/concepts/embedding-boundary.md',
+    'docs/guides/concepts/architecture.md',
+    'docs/guides/concepts/agents-and-personas.mdx',
+    'docs/guides/concepts/gates-and-enforcement.md',
+    'docs/guides/concepts/beads-and-state.md',
+    'docs/guides/concepts/prompt-surfaces.md',
+    'docs/guides/concepts/knowledge-layout.md',
+    'docs/guides/concepts/deployment-model.md',
+    'docs/guides/concepts/embedding-boundary.md',
     'docs/README.md',
-    'docs/start/install.mdx',
-    'docs/start/first-task.mdx',
+    'docs/guides/start/install.mdx',
+    'docs/guides/start/first-task.mdx',
   ];
 
   for (const rel of priority) {
@@ -66,12 +66,12 @@ function buildSourceList(repoRoot = REPO_ROOT, projectRoot = null) {
   }
 
   // Cookbook recipes (task-oriented how-tos)
-  const cookbookDir = join(repoRoot, 'docs', 'cookbook');
+  const cookbookDir = join(repoRoot, 'docs', 'guides', 'cookbook');
   if (existsSync(cookbookDir)) {
     for (const file of readdirSync(cookbookDir)) {
       if (file.endsWith('.md') || file.endsWith('.mdx')) {
         const full = join(cookbookDir, file);
-        sources.push({ path: full, rel: `docs/cookbook/${file}`, priority: 2 });
+        sources.push({ path: full, rel: `docs/guides/cookbook/${file}`, priority: 2 });
       }
     }
   }

package/lib/maintenance/cleanup.mjs

@@ -10,8 +10,9 @@
  * Triggered from two entry points:
  *   - `construct cleanup`            — manual sweep, optionally --dry-run
  *   - bin/construct startup check    — automatic when the installed version
- *                                       differs from ~/.construct/.cleanup-stamp,
- *                                       so an upgrade reclaims disk without
+ *                                       differs from the XDG state-dir
+ *                                       .cleanup-stamp, so an upgrade reclaims
+ *                                       disk without
  *                                       requiring a manual command.
  *
  * Scope is deliberately narrow: only artifacts whose retention is owned by
@@ -24,6 +25,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
+import { stateDir, cacheDir } from '../config/xdg.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
+
 const HARD_BUDGET_MS = 5000;
 
 // Size caps in bytes. Each entry: [filename relative to ~/.cx/, maxBytes].
@@ -92,7 +96,7 @@ function rotationConfig(env = process.env) {
  * were oversized before the cap existed.
  */
 export function cleanupEmbedLog({ homeDir = os.homedir(), env = process.env, dryRun = false } = {}) {
-  const dir = path.join(homeDir, '.cx', 'runtime');
+  const dir = path.join(doctorRoot(homeDir), 'runtime');
   const baseLog = path.join(dir, 'embed-daemon.log');
   const { maxBytes, keep } = rotationConfig(env);
 
@@ -149,7 +153,7 @@ export function cleanupEmbedLog({ homeDir = os.homedir(), env = process.env, dry
  * recent records survive.
  */
 export function cleanupJsonlLogs({ homeDir = os.homedir(), dryRun = false } = {}) {
-  const dir = path.join(homeDir, '.cx');
+  const dir = doctorRoot(homeDir);
   const summary = { truncated: [], freedBytes: 0 };
   if (!fs.existsSync(dir)) return summary;
 
@@ -168,11 +172,11 @@ export function cleanupJsonlLogs({ homeDir = os.homedir(), dryRun = false } = {}
 }
 
 /**
- * Age out ~/.construct/cache/ entries older than `maxAgeDays`. Cache hits are
+ * Age out XDG cache-dir entries older than `maxAgeDays`. Cache hits are
  * idempotent and re-fetched on demand, so pruning is safe.
  */
 export function cleanupCacheDir({ homeDir = os.homedir(), maxAgeDays = 30, dryRun = false } = {}) {
-  const dir = path.join(homeDir, '.construct', 'cache');
+  const dir = cacheDir(homeDir);
   const summary = { removed: [], freedBytes: 0 };
   if (!fs.existsSync(dir)) return summary;
 
@@ -249,18 +253,18 @@ export function formatBytes(bytes) {
 // ---------------------------------------------------------------------------
 // Version stamp — drives automatic cleanup on upgrade.
 //
-// ~/.construct/.cleanup-stamp records the last version that ran cleanup.
-// On every CLI invocation, bin/construct compares the current package
+// The .cleanup-stamp in the XDG state dir records the last version that ran
+// cleanup. On every CLI invocation, bin/construct compares the current package
 // version to the stamp. A mismatch triggers a single cleanup pass and
 // writes the new version into the stamp. The first ever invocation also
 // triggers cleanup (no stamp present) — this is what unblocks existing
 // installs that already have 34 GB logs sitting around.
 // ---------------------------------------------------------------------------
 
-const STAMP_RELATIVE = path.join('.construct', '.cleanup-stamp');
+const STAMP_FILENAME = '.cleanup-stamp';
 
 export function stampPath(homeDir = os.homedir()) {
-  return path.join(homeDir, STAMP_RELATIVE);
+  return path.join(stateDir(homeDir), STAMP_FILENAME);
 }
 
 export function readVersionStamp({ homeDir = os.homedir() } = {}) {

package/lib/mcp/server.mjs

@@ -859,7 +859,7 @@ const ALL_TOOL_DEFS = [
     },
     {
       name: 'profile_create',
-      description: 'Scaffold a draft org profile under `.cx/profiles/draft-<id>/` (requirements.md + profile.json + persona stubs + department charters). Writes durable state — requires `confirm=true`. For curated catalog work, follow `docs/concepts/profile-lifecycle.md` after creation.',
+      description: 'Scaffold a draft org profile under `.cx/profiles/draft-<id>/` (requirements.md + profile.json + persona stubs + department charters). Writes durable state — requires `confirm=true`. For curated catalog work, follow `docs/guides/concepts/profile-lifecycle.md` after creation.',
       inputSchema: {
         type: 'object',
         required: ['confirm', 'id'],