@geraldmaron/construct 1.2.0 → 1.2.2

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/constants.mjs

@@ -0,0 +1,29 @@
+/**
+ * lib/intake/constants.mjs — shared intake watcher depth constants and guidance.
+ */
+
+export const INTAKE_DEFAULT_MAX_DEPTH = 4;
+export const INTAKE_HARD_MAX_DEPTH = 16;
+
+export const INTAKE_DEPTH_GUIDANCE = [
+  { value: 0, label: 'Only this directory', detail: 'Scans files directly in the parent dir, ignores all subdirs.' },
+  { value: 1, label: 'One level deep', detail: 'Parent dir plus its immediate subdirs (e.g. parent/intake/file.md).' },
+  { value: 2, label: 'Two levels deep', detail: 'Parent and two subdirs. A reasonable default for organized intake roots.' },
+  { value: 4, label: 'Four levels (default)', detail: 'Catches most nested layouts without scanning huge trees.' },
+  { value: 8, label: 'Deep scan', detail: 'Useful for archives. Slower; skip if the parent contains build output.' },
+  { value: INTAKE_HARD_MAX_DEPTH, label: 'Unlimited (capped)', detail: `Walks up to ${INTAKE_HARD_MAX_DEPTH} levels — effectively unlimited. May be slow.` },
+];
+
+export function describeIntakeDepth(depth = INTAKE_DEFAULT_MAX_DEPTH) {
+  const n = Number(depth);
+  const value = !Number.isFinite(n) || n < 0
+    ? INTAKE_DEFAULT_MAX_DEPTH
+    : Math.min(Math.floor(n), INTAKE_HARD_MAX_DEPTH);
+  const exact = INTAKE_DEPTH_GUIDANCE.find((g) => g.value === value);
+  if (exact) return exact;
+  return {
+    value,
+    label: `Custom depth (${value})`,
+    detail: `Walks up to ${value} levels of subdirectories below each parent.`,
+  };
+}

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,136 +1,56 @@
 /**
- * lib/intake/intake-config.mjs — user-facing intake watcher config.
+ * lib/intake/intake-config.mjs — intake watcher config facade.
  *
- * Lets the user define which directories the inbox watcher scans and how
- * deep it descends through subdirectories. Persists to
- * `<rootDir>/.cx/intake-config.json` and merges with env-driven defaults so
- * CLI, dashboard, and process env all converge on the same answer.
- *
- * Schema:
- *   {
- *     parentDirs: string[]   // absolute or rootDir-relative
- *     maxDepth: number       // 0 = only the parent dir, no subdirs
- *     includeProjectInbox: boolean  // always include <rootDir>/.cx/inbox
- *     includeDocsIntake: boolean    // include <rootDir>/docs/intake when present
- *   }
- *
- * maxDepth guidance (surfaced verbatim in the dashboard):
- *   0 — only files directly inside the parent dir
- *   1 — parent dir + its immediate subdirs
- *   2 — two levels of subdirs (a common default for project intake roots)
- *   3+ — deep scans; use with care on large trees
+ * Reads and writes intake policy via construct.config.json intakePolicy, the
+ * only config source (single-zone model, ADR-0045 §C).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
 import { shouldCreateCx } from '../project-detection.mjs';
-import { ensureCxDir } from '../project-init-shared.mjs';
-
-export const INTAKE_CONFIG_FILE = '.cx/intake-config.json';
-export const INTAKE_DEFAULT_MAX_DEPTH = 4;
-export const INTAKE_HARD_MAX_DEPTH = 16;
-
-export const INTAKE_DEPTH_GUIDANCE = [
-  { value: 0, label: 'Only this directory', detail: 'Scans files directly in the parent dir, ignores all subdirs.' },
-  { value: 1, label: 'One level deep', detail: 'Parent dir plus its immediate subdirs (e.g. parent/intake/file.md).' },
-  { value: 2, label: 'Two levels deep', detail: 'Parent and two subdirs. A reasonable default for organized intake roots.' },
-  { value: 4, label: 'Four levels (default)', detail: 'Catches most nested layouts without scanning huge trees.' },
-  { value: 8, label: 'Deep scan', detail: 'Useful for archives. Slower; skip if the parent contains build output.' },
-  { value: INTAKE_HARD_MAX_DEPTH, label: 'Unlimited (capped)', detail: `Walks up to ${INTAKE_HARD_MAX_DEPTH} levels — effectively unlimited. May be slow.` },
-];
+import {
+  resolvedIntakeConfig,
+  saveIntakePolicy,
+  DEFAULT_INTAKE_POLICY,
+} from '../config/intake-policy.mjs';
+import {
+  INTAKE_DEFAULT_MAX_DEPTH,
+  INTAKE_HARD_MAX_DEPTH,
+  INTAKE_DEPTH_GUIDANCE,
+  describeIntakeDepth,
+} from './constants.mjs';
+
+export {
+  INTAKE_DEFAULT_MAX_DEPTH,
+  INTAKE_HARD_MAX_DEPTH,
+  INTAKE_DEPTH_GUIDANCE,
+  describeIntakeDepth,
+  DEFAULT_INTAKE_POLICY,
+};
 
 export const DEFAULT_INTAKE_CONFIG = Object.freeze({
   parentDirs: [],
   maxDepth: INTAKE_DEFAULT_MAX_DEPTH,
-  includeProjectInbox: true,
-  includeDocsIntake: true,
-  includeArchetypeInbox: false,
 });
 
-export function intakeConfigPath(rootDir) {
-  return join(rootDir, INTAKE_CONFIG_FILE);
-}
-
-function clampDepth(value) {
-  const n = Number(value);
-  if (!Number.isFinite(n) || n < 0) return INTAKE_DEFAULT_MAX_DEPTH;
-  return Math.min(Math.floor(n), INTAKE_HARD_MAX_DEPTH);
-}
-
-function normalizeDir(dir, rootDir) {
-  if (typeof dir !== 'string') return null;
-  const trimmed = dir.trim();
-  if (!trimmed) return null;
-  return isAbsolute(trimmed) ? trimmed : resolve(rootDir, trimmed);
-}
-
-function parseEnvDirs(env) {
-  const raw = String(env?.CX_INBOX_DIRS ?? '').trim();
-  if (!raw) return [];
-  return raw.split(':').map((p) => p.trim()).filter(Boolean);
-}
-
 export function loadIntakeConfig(rootDir, env = process.env) {
-  const file = intakeConfigPath(rootDir);
-  let stored = {};
-  if (existsSync(file)) {
-    try { stored = JSON.parse(readFileSync(file, 'utf8')); } catch { stored = {}; }
-  }
-
-  const parentDirs = []
-    .concat(Array.isArray(stored.parentDirs) ? stored.parentDirs : [])
-    .concat(parseEnvDirs(env))
-    .map((dir) => normalizeDir(dir, rootDir))
-    .filter(Boolean);
-
-  const seen = new Set();
-  const uniqueDirs = [];
-  for (const dir of parentDirs) {
-    if (seen.has(dir)) continue;
-    seen.add(dir);
-    uniqueDirs.push(dir);
-  }
-
-  const envDepth = env?.CX_INTAKE_MAX_DEPTH;
-  const maxDepth = clampDepth(envDepth ?? stored.maxDepth ?? DEFAULT_INTAKE_CONFIG.maxDepth);
-
-  return {
-    parentDirs: uniqueDirs,
-    maxDepth,
-    includeProjectInbox: stored.includeProjectInbox !== false,
-    includeDocsIntake: stored.includeDocsIntake !== false,
-    includeArchetypeInbox: stored.includeArchetypeInbox === true,
-  };
+  return resolvedIntakeConfig(rootDir, env);
 }
 
 export function saveIntakeConfig(rootDir, patch = {}) {
   if (!shouldCreateCx(rootDir)) {
     throw new Error('Refusing to write intake config: directory is not an initialized construct project. Run `construct init` first.');
   }
-  const current = loadIntakeConfig(rootDir, {});
-  const next = {
-    parentDirs: Array.isArray(patch.parentDirs)
-      ? patch.parentDirs.map((dir) => normalizeDir(dir, rootDir)).filter(Boolean)
-      : current.parentDirs,
-    maxDepth: clampDepth(patch.maxDepth ?? current.maxDepth),
-    includeProjectInbox: patch.includeProjectInbox !== undefined ? Boolean(patch.includeProjectInbox) : current.includeProjectInbox,
-    includeDocsIntake: patch.includeDocsIntake !== undefined ? Boolean(patch.includeDocsIntake) : current.includeDocsIntake,
-    includeArchetypeInbox: patch.includeArchetypeInbox !== undefined ? Boolean(patch.includeArchetypeInbox) : current.includeArchetypeInbox,
-  };
 
-  const file = intakeConfigPath(rootDir);
-  ensureCxDir(rootDir);
-  writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
-  return next;
+  const policyPatch = {};
+  if (patch.maxDepth !== undefined) policyPatch.maxDepth = patch.maxDepth;
+  if (Array.isArray(patch.parentDirs)) policyPatch.additionalDirs = patch.parentDirs;
+
+  const { policy } = saveIntakePolicy(rootDir, policyPatch);
+  return policyToConfigShape(policy);
 }
 
-export function describeIntakeDepth(depth = INTAKE_DEFAULT_MAX_DEPTH) {
-  const value = clampDepth(depth);
-  const exact = INTAKE_DEPTH_GUIDANCE.find((g) => g.value === value);
-  if (exact) return exact;
+function policyToConfigShape(policy) {
   return {
-    value,
-    label: `Custom depth (${value})`,
-    detail: `Walks up to ${value} levels of subdirectories below each parent.`,
+    parentDirs: policy.additionalDirs,
+    maxDepth: policy.maxDepth,
   };
 }

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

@@ -58,7 +58,7 @@ import {
   profileCreate, profileArchive, sandboxList, learningStatus,
   knowledgeGraphAsk,
 } from './tools/profile.mjs';
-import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve } from './tools/embedded-contract.mjs';
+import { modelResolve, triageRecommend, workflowInvoke, capabilityDescribe, executionResolve, artifactWorkflow } from './tools/embedded-contract.mjs';
 
 const DEFAULT_ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ROOT_DIR = resolve(process.env.CX_TOOLKIT_DIR || DEFAULT_ROOT_DIR);
@@ -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'],
@@ -1134,6 +1134,23 @@ const ALL_TOOL_DEFS = [
         },
       },
     },
+    {
+      name: 'artifact_workflow',
+      description: 'Plan a manifest-backed document artifact workflow and return a truthful provenance report. It separates planned steps from locally executed validation/export and never claims a host-planned specialist review or rewrite was completed. Durable local export requires approval_mode=allow-durable-write.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          input: { type: 'string', description: 'Natural-language artifact request.' },
+          artifact_type: { type: 'string', description: 'Registered manifest document class.' },
+          file_path: { type: 'string', description: 'Optional existing source document for local validation/export.' },
+          format: { type: 'string', description: 'Distribution format such as pdf, docx, html, deck, or pptx.' },
+          output_path: { type: 'string', description: 'Optional output destination when locally exporting.' },
+          branding: { type: 'string', enum: ['construct', 'plain'], description: 'Construct is default; plain is an explicit opt-out.' },
+          overrides: { type: 'object', description: 'Per-invocation manifest workflow overrides.' },
+          approval_mode: { type: 'string', enum: ['proposal-only', 'requires-human-approval', 'allow-durable-write'], description: 'Only allow-durable-write performs local validation/export.' },
+        },
+      },
+    },
     {
       name: 'model_resolve',
       description: 'Resolve which model an embedded Construct workflow should use given the host/IDE provider context. Precedence: host model → same-provider-family fallback → Construct tier default → structured config error. Never reads or returns credential values (requiresCredential is a boolean) and never claims unverified provider health. Read-only; performs no writes.',
@@ -1421,6 +1438,7 @@ export async function dispatchToolByName(name, args = {}) {
     else if (name === 'workflow_invoke') result = await workflowInvoke(args);
     else if (name === 'capability_describe') result = capabilityDescribe(args);
     else if (name === 'construct_execution_resolve') result = executionResolve(args);
+    else if (name === 'artifact_workflow') result = artifactWorkflow(args);
     else if (name === 'orchestration_run') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationRun(args); }
     else if (name === 'orchestration_status') { const m = await import('./tools/orchestration-run.mjs'); result = await m.orchestrationStatus(args); }
     else if (name === 'construct_call') {

package/lib/mcp/tools/embedded-contract.mjs

@@ -14,6 +14,7 @@ import { invokeWorkflow as invokeWorkflowCore } from '../../embedded-contract/wo
 import { buildCapabilityContract } from '../../embedded-contract/capability.mjs';
 import { resolveExecution as resolveExecutionCore } from '../../embedded-contract/execution.mjs';
 import { resolveInput } from '../../embedded-contract/ingest.mjs';
+import { runArtifactWorkflow as runArtifactWorkflowCore } from '../../artifact-workflow.mjs';
 
 async function ingestArgs(args) {
   if (args.input || !args.file_path) return { input: args.input, ingestion: undefined };
@@ -91,3 +92,16 @@ export function executionResolve(args = {}) {
   };
   return wrapContractResult(resolveExecutionCore(request), { surface: 'mcp' });
 }
+
+export function artifactWorkflow(args = {}) {
+  return wrapContractResult(runArtifactWorkflowCore({
+    input: args.input || args.request,
+    artifactType: args.artifact_type,
+    filePath: args.file_path,
+    format: args.format,
+    outputPath: args.output_path,
+    branding: args.branding,
+    overrides: args.overrides,
+    approvalMode: args.approval_mode,
+  }), { surface: 'mcp' });
+}

package/lib/mcp/tools/project.mjs

@@ -13,6 +13,7 @@ import { inspectContextState } from '../../context-state.mjs';
 import { loadWorkflow, summarizeWorkflow, inspectWorkflowHealth } from '../../workflow-state.mjs';
 import { readCurrentModels, resolveExecutionContractModelMetadata, selectModelTierForWorkCategory } from '../../model-router.mjs';
 import { buildPublicHealthSurface } from '../../status.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 
 export function exec(cmd, cwd) {
   return execSync(cmd, { stdio: 'pipe', timeout: 10000, cwd }).toString().trim();
@@ -60,7 +61,7 @@ function isBinary(buffer) {
 }
 
 export function agentHealth(args) {
-  const reviewDir = join(homedir(), '.cx', 'performance-reviews');
+  const reviewDir = join(doctorRoot(), 'performance-reviews');
 
   if (!existsSync(reviewDir)) {
     return { error: "No performance reviews found. Run 'construct review' to generate one." };