@geraldmaron/construct 1.2.1 → 1.2.3

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'],

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." };

package/lib/model-cheapest-provider.mjs

@@ -21,10 +21,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { getProviderModelCatalog, PROVIDER_FAMILY_TIERS } from './model-router.mjs';
 import { getPricingForModels, formatPricingLabel } from './model-pricing.mjs';
+import { configDir } from './config/xdg.mjs';
 
 const CHEAPEST_PREF_KEY = 'CHEAPEST_PROVIDER_ENABLED';
 const CHEAPEST_CHECKED_KEY = 'CHEAPEST_PROVIDER_CHECKED';
-const ENV_PATH = path.join(os.homedir(), '.construct', 'config.env');
+const ENV_PATH = path.join(configDir(), 'config.env');
 
 /**
  * Resolve the cheapest configured provider for a given tier.
@@ -32,7 +33,7 @@ const ENV_PATH = path.join(os.homedir(), '.construct', 'config.env');
  * @param {string} tier - One of "reasoning", "standard", "fast"
  * @param {object} [opts]
  * @param {object} [opts.env] - Environment object (default: process.env)
- * @param {string} [opts.envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {string} [opts.envPath] - Path to config.env (default: config.env in the XDG config dir)
  * @param {Function} [opts.getPricingForModels] - Injectable pricing fetcher
  * @returns {Promise<{
  *   providerId: string|null,
@@ -130,7 +131,7 @@ export async function rankConfiguredProvidersByCost(tier, opts = {}) {
 /**
  * Check if the user has opted into cheapest-provider selection.
  *
- * @param {string} [envPath] - Path to config.env (default: ~/.construct/config.env)
+ * @param {string} [envPath] - Path to config.env (default: config.env in the XDG config dir)
  * @param {object} [opts.env] - Environment override
  * @returns {boolean}
  */

package/lib/model-pricing.mjs

@@ -16,10 +16,11 @@
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
-const DEFAULT_CACHE_FILE = path.join(os.homedir(), '.cx', 'model-pricing.json');
+import { doctorRoot } from './config/xdg.mjs';
+
+const DEFAULT_CACHE_FILE = path.join(doctorRoot(), 'model-pricing.json');
 const CACHE_TTL_MS = 5 * 60 * 1000;
 const OPENROUTER_ENDPOINT = 'https://openrouter.ai/api/v1/models';
 

package/lib/model-router.mjs

@@ -41,6 +41,7 @@ import {
   loadModelsCatalogContext,
   mergeLiveModelsIntoProviders,
 } from "./models/catalog.mjs";
+import { configDir } from "./config/xdg.mjs";
 
 function uniqueStrings(values = []) {
   return [...new Set(values.filter((value) => typeof value === "string" && value.trim()))];
@@ -380,7 +381,7 @@ function hasCopilotCredential() {
   const home = process.env.HOME || process.env.USERPROFILE || '';
   if (!home) return false;
   const candidates = [
-    path.join(home, '.construct', 'auth', 'github-copilot.json'),
+    path.join(configDir(home), 'auth', 'github-copilot.json'),
     path.join(home, '.config', 'github-copilot', 'apps.json'),
     path.join(home, '.config', 'github-copilot', 'hosts.json'),
   ];
@@ -421,7 +422,7 @@ function isProviderConfigured(familyId, env, { allowAmbient = true } = {}) {
     } catch { /* not available */ }
   }
 
-  // Any credential source counts — env, ~/.construct/config.env, ~/.env, the
+  // Any credential source counts — env, the XDG config dir config.env, ~/.env, the
   // project .env, and shell rc exports — and a stored 1Password op:// reference
   // counts as configured because the resolver reads it lazily at call time.
   if (hasAnySecret(varNames, { env, allowAmbient })) return true;
@@ -569,7 +570,7 @@ function availabilityNotice(rejected) {
   if (rejected.reason === 'provider_not_configured') {
     const family = rejected.provider || '';
     if (family.startsWith('openrouter')) {
-      return `Saved ${label} — OpenRouter not configured. Set OPENROUTER_API_KEY in ~/.construct/config.env or run \`construct creds set openrouter\`.`;
+      return `Saved ${label} — OpenRouter not configured. Set OPENROUTER_API_KEY in ~/.config/construct/config.env or run \`construct creds set openrouter\`.`;
     }
     return `Saved ${label} — provider not configured.`;
   }

package/lib/models/catalog.mjs

@@ -12,6 +12,7 @@ import os from 'node:os';
 import { pollFreeModels } from '../model-free-selector.mjs';
 import { resolveFirstSecret } from '../providers/secret-resolver.mjs';
 import { loadProjectConfig } from '../config/project-config.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 export const MODEL_VISIBILITY_MODES = ['all_configured', 'tier_defaults', 'explicit'];
 
@@ -36,7 +37,7 @@ function uniqueStrings(values = []) {
 }
 
 function cachePath(homeDir = os.homedir()) {
-  return path.join(homeDir, '.cx', CACHE_FILENAME);
+  return path.join(doctorRoot(homeDir), CACHE_FILENAME);
 }
 
 export function resolveModelsConfig(projectConfig = {}) {

package/lib/models/execution-capability-profile.mjs

@@ -32,6 +32,7 @@ import { getModelVerdict } from '../ollama/capability-store.mjs';
 import { isLocalModel } from '../mcp/tool-budget.mjs';
 import { transportForProviderGroup, classifyCapabilityClass } from './behavior-matrix.mjs';
 import { resolveCapabilityTier, resolveModelOperatingProfile } from '../model-router.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 export const EXECUTION_PROFILE_SCHEMA_VERSION = 1;
 
@@ -81,7 +82,7 @@ function hasVendorAdapter(modelId) {
 
 function loadOverridesFile(homeDir) {
   try {
-    const raw = JSON.parse(readFileSync(join(homeDir, '.cx', OVERRIDES_FILENAME), 'utf8'));
+    const raw = JSON.parse(readFileSync(join(doctorRoot(homeDir), OVERRIDES_FILENAME), 'utf8'));
     if (raw && typeof raw === 'object' && raw.models && typeof raw.models === 'object') return raw.models;
   } catch { /* absent or malformed — no overrides */ }
   return {};

package/lib/models/provider-poll.mjs

@@ -18,6 +18,7 @@ import { resolveFirstSecret } from '../providers/secret-resolver.mjs';
 import { getProviderModelCatalog } from '../model-router.mjs';
 import { listInstalledOllamaModels, toOllamaNativeModelId } from '../ollama/installed-models.mjs';
 import { getPricingForModels } from '../model-pricing.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const FETCH_TIMEOUT_MS = 10_000;
 const CACHE_TTL_MS = 10 * 60 * 1000;
@@ -37,7 +38,7 @@ const PROVIDER_LABELS = {
 const PROVIDER_ORDER = ['anthropic', 'openai', 'github-copilot', 'openrouter', 'ollama', 'local'];
 
 function cachePath(homeDir = os.homedir()) {
-  return path.join(homeDir, '.cx', CACHE_FILENAME);
+  return path.join(doctorRoot(homeDir), CACHE_FILENAME);
 }
 
 async function fetchJson(url, { headers = {}, signal } = {}) {

package/lib/ollama-manager.mjs

@@ -8,7 +8,6 @@
 
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 
 // argv-array form for every shell-out: no shell interpolation, model names and
 // JSON bodies are passed as discrete arguments / stdin so user-supplied values

package/lib/op-log.mjs

@@ -22,12 +22,13 @@ import path from 'node:path';
 import os from 'node:os';
 
 import { makeLogger, newRequestId } from './logger.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
 const NOOP_LOGGER = Object.freeze({ debug() {}, info() {}, warn() {}, error() {} });
 
 export function startOpLog(op, { homeDir = os.homedir(), env = process.env, now = new Date() } = {}) {
   const id = newRequestId();
-  const dir = path.join(homeDir, '.cx');
+  const dir = doctorRoot(homeDir);
   const stamp = now.toISOString().replace(/[:.]/g, '-');
   const logPath = path.join(dir, `${op}-${stamp}.log`);
 

package/lib/opencode-runtime-plugin.mjs

@@ -28,6 +28,7 @@ import {
 import { syncModelPricing, refreshPricingCatalog } from "./telemetry/model-pricing-catalog.mjs";
 import { estimateUsageCost } from "./telemetry/model-pricing-catalog.mjs";
 import { buildSessionPrelude } from "./intake/session-prelude.mjs";
+import { doctorRoot } from './config/xdg.mjs';
 
 const EFFICIENCY_SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
 const EFFICIENCY_REPEATED_READ_THRESHOLD = 5;
@@ -94,7 +95,7 @@ const COOLDOWN_MS = 10 * 60 * 1000;
 
 function getStatePath(env = process.env) {
   const home = env.HOME || homedir();
-  return join(home, ".cx", "construct-opencode-fallback.json");
+  return join(doctorRoot(home), "construct-opencode-fallback.json");
 }
 
 function flatten(value) {
@@ -520,7 +521,7 @@ export function buildRuntimeTracePayload(event, { env = process.env } = {}) {
 
 function efficiencyStorePath(env = process.env) {
   const home = env.HOME || homedir();
-  return join(home, ".cx", "session-efficiency.json");
+  return join(doctorRoot(home), "session-efficiency.json");
 }
 
 function loadEfficiencyStats(nowIso, env = process.env) {

package/lib/oracle/artifact-gate.mjs

@@ -50,8 +50,11 @@ function collectBypassArtifacts(projectDir) {
 
 function collectReviewerGaps(projectDir) {
   const roots = [
+    path.join(projectDir, 'docs', 'specs', 'prd'),
     path.join(projectDir, 'docs', 'prd'),
+    path.join(projectDir, 'docs', 'decisions', 'adr'),
     path.join(projectDir, 'docs', 'adr'),
+    path.join(projectDir, 'docs', 'decisions', 'rfc'),
     path.join(projectDir, 'docs', 'rfc'),
   ];
   const gaps = [];

package/lib/oracle/cli.mjs

@@ -20,11 +20,12 @@ import {
 import { runOracleTick, listPending, approvePending, defaultRootDir } from './actions.mjs';
 import { collectOracleGaps, formatOracleGapsReport } from './gaps.mjs';
 import { reconcileOracleHygieneBeads } from './reconcile.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const MODULE_FILE = fileURLToPath(import.meta.url);
 
 function runtimeDir(homeDir) {
-  return path.join(homeDir, '.cx', 'runtime', 'oracle');
+  return path.join(doctorRoot(homeDir), 'runtime', 'oracle');
 }
 
 async function cmdStart(args, { rootDir, projectDir, homeDir }) {

package/lib/oracle/execute.mjs

@@ -16,9 +16,10 @@ import { recordAndMaybeInvoke } from '../roles/gateway.mjs';
 import { validateCapabilityRegistry } from '../registry/validate.mjs';
 import { writeRoutingArtifact } from './dispatch.mjs';
 import { routeAction } from './routing.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 function rolePendingPath(homeDir = homedir()) {
-  const root = process.env.CONSTRUCT_ROLES_ROOT || path.join(homeDir, '.cx');
+  const root = process.env.CONSTRUCT_ROLES_ROOT || doctorRoot(homeDir);
   return path.join(root, 'role-pending.jsonl');
 }
 
@@ -40,7 +41,7 @@ async function dispatchSpecialist({ action, projectDir, homeDir, personaId, even
   });
 
   const prevRolesRoot = process.env.CONSTRUCT_ROLES_ROOT;
-  process.env.CONSTRUCT_ROLES_ROOT = path.join(homeDir, '.cx');
+  process.env.CONSTRUCT_ROLES_ROOT = doctorRoot(homeDir);
 
   const event = {
     project: projectDir,

package/lib/oracle/index.mjs

@@ -13,11 +13,12 @@ import { homedir } from 'node:os';
 import { createDaemon } from '../daemons/contract.mjs';
 import { memoryCapMbFor } from '../resources/process-budget.mjs';
 import { runOracleTick, defaultRootDir } from './actions.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 export const KILLSWITCH_ENV = 'CONSTRUCT_ORACLE';
 
 function runtimeDir(homeDir = homedir()) {
-  return path.join(homeDir, '.cx', 'runtime', 'oracle');
+  return path.join(doctorRoot(homeDir), 'runtime', 'oracle');
 }
 
 export function heartbeatPath(homeDir = homedir()) {

package/lib/oracle/read-model.mjs

@@ -21,6 +21,7 @@ import { collectArtifactGateSignals } from './artifact-gate.mjs';
 import { loadGraph, nodesByType, dependentsOf } from '../graph/store.mjs';
 import { hashFiles } from '../graph/build-from-registry.mjs';
 import { readViolationSupersedeCutoff } from '../contracts/violation-log.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const RECENT_MS = 24 * 60 * 60 * 1000;
 const DOCTOR_LIMIT = 50;
@@ -128,7 +129,7 @@ function collectContractViolations(projectDir) {
 }
 
 function collectDoctorLog(homeDir) {
-  const file = path.join(homeDir, '.cx', 'doctor-log.jsonl');
+  const file = path.join(doctorRoot(homeDir), 'doctor-log.jsonl');
   const since = Date.now() - RECENT_MS;
   const recent = readRecentJsonl(file, { since, limit: DOCTOR_LIMIT });
   return {
@@ -205,7 +206,7 @@ function collectBeadsOpenCount(projectDir) {
 }
 
 function collectHookFailures(homeDir) {
-  const file = path.join(homeDir, '.cx', 'doctor-log.jsonl');
+  const file = path.join(doctorRoot(homeDir), 'doctor-log.jsonl');
   const since = Date.now() - RECENT_MS;
   const recent = readRecentJsonl(file, { since, limit: DOCTOR_LIMIT });
   const failures = recent.filter((r) =>

package/lib/performance/generate.mjs

@@ -24,11 +24,12 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
+
+import { doctorRoot } from '../config/xdg.mjs';
 
 const WINDOW_DAYS = 7;
-const REVIEW_DIR = path.join(os.homedir(), '.cx', 'performance-reviews');
-const COST_LEDGER = path.join(os.homedir(), '.cx', 'session-cost.jsonl');
+const REVIEW_DIR = path.join(doctorRoot(), 'performance-reviews');
+const COST_LEDGER = path.join(doctorRoot(), 'session-cost.jsonl');
 
 function quantile(values, q) {
   if (!values.length) return null;

package/lib/platforms/capabilities.mjs

@@ -6,7 +6,7 @@
  * local-model provisioning, instructions-only). The host enumeration, the
  * displayName-to-id map, the hasNativeSubagents matrix, and the global hook /
  * MCP allowlists all derive from this one registry so sync and init read host
- * capabilities as data. See docs/adr/0033-platform-capability-registry.md.
+ * capabilities as data. See docs/decisions/adr/0033-platform-capability-registry.md.
  *
  * Hand-rolled validation (no AJV/zod) so this loads dependency-free on the
  * bootstrap paths that run before npm install — same constraint as

package/lib/plugin-registry.mjs

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { homedir } from "node:os";
 import { dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { configDir } from "./config/xdg.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const MANIFEST_VERSION = 1;
@@ -123,7 +124,7 @@ export function resolvePluginDirs({ cwd = process.cwd(), homeDir = homedir(), en
   return [...new Set([
     join(cwd, ".cx", "plugins"),
     join(cwd, ".construct", "plugins"),
-    join(homeDir, ".construct", "plugins"),
+    join(configDir(homeDir), "plugins"),
     ...extra,
   ].map((dir) => resolve(dir)))];
 }

package/lib/profiles/lifecycle.mjs

@@ -41,7 +41,7 @@ function archiveDir(cwd, id) {
 
 const REQUIREMENTS_BRIEF = (id, displayName) => `# Profile requirements: ${displayName} (${id})
 
-This brief is a discovery and design contract for a new Construct profile. Methodology lives in \`docs/concepts/persona-research.md\` and lifecycle in \`docs/concepts/profile-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft profile is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
+This brief is a discovery and design contract for a new Construct profile. Methodology lives in \`docs/guides/concepts/persona-research.md\` and lifecycle in \`docs/guides/concepts/profile-lifecycle.md\`. Treat each section as a task to dispatch to the named specialist. A draft profile is not ready to promote until every section has evidence backing it. The aim is research-grounded, not opinion-grounded.
 
 Specialists used here are the existing Construct cx-* personas (already in the registry). They are dispatched the standard way; this doc just names which questions each one owns.
 
@@ -145,7 +145,7 @@ const DRAFT_PROFILE_TEMPLATE = (id, displayName) => ({
 function personaTemplate(displayName) {
   return `# ${displayName}
 
-> Persona research artifact. Methodology: \`docs/concepts/persona-research.md\`. Fill from evidence; opinion is rejected at review.
+> Persona research artifact. Methodology: \`docs/guides/concepts/persona-research.md\`. Fill from evidence; opinion is rejected at review.
 
 ## Goals
 - <What does success look like for this role?>
@@ -178,7 +178,7 @@ function personaTemplate(displayName) {
 function departmentTemplate(id, displayName) {
   return `# ${displayName} (${id})
 
-> Department charter. One paragraph: what this department owns, what it does not own, who it hands off to. Frame from organizational-design research (\`docs/concepts/persona-research.md\` § departmental structure).
+> Department charter. One paragraph: what this department owns, what it does not own, who it hands off to. Frame from organizational-design research (\`docs/guides/concepts/persona-research.md\` § departmental structure).
 
 ## Charter
 

package/lib/project-profile.mjs

@@ -14,6 +14,7 @@
  */
 import { existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { configDir } from './config/xdg.mjs';
 
 // Detection rules. Each rule checks a filesystem signal and emits one or more
 // tags. Keep rules tight — false positives cascade into bad filter decisions.
@@ -430,7 +431,7 @@ export function enumerateInstalledSkills(homeDir = (process.env.HOME || process.
     // Codex
     join(homeDir, '.codex', 'skills'),
     // Construct native
-    join(homeDir, '.construct', 'skills'),
+    join(configDir(homeDir), 'skills'),
   ];
   for (const dir of candidates) {
     try {