@geraldmaron/construct 1.2.0 → 1.2.2

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/playwright-demo.mjs

@@ -80,6 +80,8 @@ export function transcodeWebmToMp4(src, dest) {
   const result = spawnSync(ffmpeg, [
     '-y', '-i', src,
     '-c:v', 'libx264',
+    '-crf', '18',
+    '-preset', 'medium',
     '-pix_fmt', 'yuv420p',
     '-movflags', '+faststart',
     dest,

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 {

package/lib/project-root.mjs

@@ -4,12 +4,12 @@
  * Writers that own per-project state (contract violations, audit reads, agent
  * dispatches, intent verifications) call `resolveProjectScope()` to decide
  * which `<project>/.cx/<file>.jsonl` to write to. When no project is
- * detected, the call returns `null` and writers fall back to the legacy
- * user-scope path (`~/.cx/<file>.jsonl`) so existing standalone hook
+ * detected, the call returns `null` and writers fall back to the global
+ * user-scope path (`<doctorRoot>/<file>.jsonl`) so existing standalone hook
  * invocations don't lose data.
  *
  * Writers that own cross-project telemetry (skill calls, role-pending,
- * session cost) keep using `~/.cx/` but tag each entry with the
+ * session cost) keep using the global doctor root but tag each entry with the
  * `projectId` from `resolveProjectId()` so a reader can attribute the
  * entry to a specific project later.
  *
@@ -24,6 +24,8 @@ import path from 'node:path';
 import os from 'node:os';
 import { createHash } from 'node:crypto';
 
+import { doctorRoot } from './config/xdg.mjs';
+
 const HOME = os.homedir();
 const MARKERS = ['.cx', '.construct'];
 const cache = new Map();   // cwd → { projectRoot, projectId, scope } | null
@@ -84,13 +86,13 @@ export function resolveProjectScope(cwd = process.cwd()) {
 
 /**
  * For project-scoped writers: returns the `<project>/.cx/<basename>` path
- * when cwd is inside a Construct project, otherwise the legacy
- * `~/.cx/<basename>` path. Callers pass just the file basename; this helper
- * resolves the directory side. ensureDir=true creates the parent dir.
+ * when cwd is inside a Construct project, otherwise the global
+ * `<doctorRoot>/<basename>` path. Callers pass just the file basename; this
+ * helper resolves the directory side. ensureDir=true creates the parent dir.
  */
 export function resolveProjectScopedPath(basename, { cwd, ensureDir = true } = {}) {
   const scope = resolveProjectScope(cwd ?? process.cwd());
-  const dir = scope ? scope.cxDir : path.join(HOME, '.cx');
+  const dir = scope ? scope.cxDir : doctorRoot();
   if (ensureDir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   return path.join(dir, basename);
 }

package/lib/provider-capabilities.js

@@ -18,9 +18,10 @@
  */
 import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 
-const CAPABILITY_CACHE_PATH = join(homedir(), '.cx', 'provider-capabilities.json');
+import { doctorRoot } from './config/xdg.mjs';
+
+const CAPABILITY_CACHE_PATH = join(doctorRoot(), 'provider-capabilities.json');
 const CAPABILITY_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 
 const ADAPTERS = {
@@ -110,7 +111,7 @@ function readCapabilityCache() {
 
 function writeCapabilityCache(capabilities) {
   try {
-    mkdirSync(join(homedir(), '.cx'), { recursive: true });
+    mkdirSync(doctorRoot(), { recursive: true });
     writeFileSync(CAPABILITY_CACHE_PATH, JSON.stringify({
       fetchedAt: Date.now(),
       capabilities,

package/lib/providers/auth-manager.mjs

@@ -11,10 +11,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
+import { configDir } from '../config/xdg.mjs';
 
 function authDir() {
   const home = process.env.HOME || homedir();
-  const dir = path.join(home, '.construct', 'auth');
+  const dir = path.join(configDir(home), 'auth');
   try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* ignore */ }
   return dir;
 }

package/lib/providers/copilot-auth.mjs

@@ -11,7 +11,7 @@
  * its token is rejected by the exchange endpoint.
  *
  * Credentials persist to two places: Construct's own store
- * (~/.construct/auth/github-copilot.json) and the de-facto standard
+ * (github-copilot.json under the XDG config dir auth/) and the de-facto standard
  * ~/.config/github-copilot/apps.json that other tools read and write, so a login
  * here is reusable elsewhere and an existing login is reused here. The access
  * token is refreshed from the refresh token when it expires; the session token
@@ -22,6 +22,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { configDir } from '../config/xdg.mjs';
 
 const CLIENT_ID = 'Iv1.b507a08c87ecfe98';
 const DEVICE_CODE_URL = 'https://github.com/login/device/code';
@@ -53,7 +54,7 @@ function homeDir() {
 }
 
 function constructStorePath() {
-  return path.join(homeDir(), '.construct', 'auth', 'github-copilot.json');
+  return path.join(configDir(homeDir()), 'auth', 'github-copilot.json');
 }
 
 function appsStorePath() {

package/lib/providers/creds.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/providers/creds.mjs — credential management for provider integrations.
  *
- * Reads and writes provider credentials stored in `~/.construct/config.env`.
+ * Reads and writes provider credentials stored in the user config.env (XDG config dir).
  * Each provider block is delimited by comment markers so the file can be
  * parsed without a full ini/dotenv library and can also be sourced by a shell.
  *
@@ -24,11 +24,12 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { configDir } from '../config/xdg.mjs';
 
 const CONFIG_FILE = 'config.env';
 
 function constructDir() {
-  return path.join(os.homedir(), '.construct');
+  return configDir();
 }
 
 export function credsFilePath() {

package/lib/providers/registry.mjs

@@ -4,7 +4,7 @@
  * Resolution order (last-write wins):
  *
  *   1. Built-in factories under `lib/providers/<id>/index.mjs` (loaded lazily).
- *   2. Operator overrides at `~/.construct/providers.json`:
+ *   2. Operator overrides at `providers.json` in the XDG config dir:
  *        { "providers": [{ "id": "...", "package": "...", "options": {} }] }
  *   3. Project overrides at `<projectRoot>/.cx/providers.json` (same shape).
  *
@@ -21,11 +21,11 @@
  */
 
 import { readFileSync, existsSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, isAbsolute, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { assertProviderContract } from './contract.mjs';
 import { getBreaker } from './circuit-breaker.mjs';
+import { configDir } from '../config/xdg.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
@@ -92,7 +92,7 @@ async function instantiate(mod, options) {
 
 function gatherOverrides(rootDir) {
   const out = [];
-  const userConfig = readJsonIfExists(join(homedir(), '.construct', 'providers.json'));
+  const userConfig = readJsonIfExists(join(configDir(), 'providers.json'));
   if (userConfig?.providers) out.push(...userConfig.providers);
   const projectConfig = readJsonIfExists(join(rootDir, '.cx', 'providers.json'));
   if (projectConfig?.providers) out.push(...projectConfig.providers);

package/lib/providers/secret-resolver.mjs

@@ -3,7 +3,7 @@
  *
  * Resolves a canonical environment variable (for example ANTHROPIC_API_KEY) by
  * walking the same sources the rest of Construct trusts, in priority order:
- * process env, ~/.construct/config.env, ~/.env, the project .env, then shell rc
+ * process env, the XDG config dir config.env, ~/.env, the project .env, then shell rc
  * files (.zshrc/.bashrc/.bash_profile/.profile). When the value carries a
  * 1Password reference — a bare `op://vault/item/field` or the shell form
  * `$(op read 'op://...')` — it is resolved through the `op` CLI and cached for
@@ -22,6 +22,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { discoverAlternateRawForVar } from './credential-sources.mjs';
+import { configDir } from '../config/xdg.mjs';
 
 // The 1Password desktop integration prompts for biometric unlock on the first
 // read after the vault locks, and that interactive round-trip routinely takes
@@ -111,7 +112,7 @@ function readShellRcVar(varName, home) {
 function rawCandidate(varName, { env, cwd, home }) {
   const direct = env?.[varName];
   if (typeof direct === 'string' && direct.length > 0) return direct;
-  const files = [path.join(home, '.construct', 'config.env'), path.join(home, '.env'), path.join(cwd, '.env')];
+  const files = [path.join(configDir(home), 'config.env'), path.join(home, '.env'), path.join(cwd, '.env')];
   for (const file of files) {
     const value = readDotenvVar(file, varName);
     if (value) return value;

package/lib/read-tracker-store.mjs

@@ -9,6 +9,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { doctorRoot } from './config/xdg.mjs';
 
 const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
 const REPEATED_READ_WARNING_THRESHOLD = 5;
@@ -20,7 +21,7 @@ const EFFICIENCY_LARGE_READ_LIMIT = 400;
 
 export function readTrackerPaths(env = process.env) {
   const home = env.CX_HOME_OVERRIDE || env.HOME || homedir();
-  const cxDir = join(home, '.cx');
+  const cxDir = doctorRoot(home);
   return {
     cxDir,
     efficiencyStore: join(cxDir, 'session-efficiency.json'),

package/lib/reconcile/mcp-entry-reconcile.mjs

@@ -21,7 +21,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { homeDir } from '../paths.mjs';
+import { homeDir, constructDir } from '../paths.mjs';
 import {
   getCodexConfigPath,
   buildCodexMcpEntry,
@@ -34,7 +34,7 @@ function escapeRegExp(value) {
 }
 
 function registryMcpServers() {
-  const installed = path.join(homeDir(), '.construct', 'specialists', 'registry.json');
+  const installed = path.join(constructDir(), 'specialists', 'registry.json');
   const bundled = fileURLToPath(new URL('../../specialists/registry.json', import.meta.url));
   for (const src of [installed, bundled]) {
     try {

package/lib/reflect.mjs

@@ -13,9 +13,10 @@ import { loadConstructEnv } from './env-config.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
 import { extractSessionObservation } from './reflect/extractor.mjs';
 import { readContextState, contextSummaryLine } from './context-state.mjs';
+import { configDir } from './config/xdg.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
-const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
+const USER_ENV_PATH = join(configDir(HOME), 'config.env');
 
 /**
  * Main reflect command handler.

package/lib/registry/generate-docs.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/registry/generate-docs.mjs — generate reference docs from registry/capabilities.json.
  *
- * Writes docs/reference/capabilities.md so the human-readable capability matrix
+ * Writes docs/guides/reference/capabilities.md so the human-readable capability matrix
  * cannot drift from the machine-readable registry.
  */
 
@@ -62,7 +62,7 @@ export function generateCapabilitiesDoc({ rootDir = REPO_ROOT, write = true } =
   }
 
   const content = `${lines.join('\n')}\n`;
-  const out = path.join(rootDir, 'docs', 'reference', 'capabilities.md');
+  const out = path.join(rootDir, 'docs', 'guides', 'reference', 'capabilities.md');
   if (!write) return { out, content, drift: fs.existsSync(out) ? fs.readFileSync(out, 'utf8') !== content : true };
   fs.mkdirSync(path.dirname(out), { recursive: true });
   fs.writeFileSync(out, content);