@geraldmaron/construct 1.2.1 → 1.2.2

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

package/lib/roles/approval-surface.mjs

@@ -3,7 +3,7 @@
  *
  * When a persona-tagged session hits an action that lands in the fence's
  * `approvalRequired` bucket (commit, push, out-of-fence edit, etc.), this
- * module appends a marker to ~/.cx/approval-pending.jsonl and emits an SSE
+ * module appends a marker to <doctorRoot>/approval-pending.jsonl and emits an SSE
  * toast through the embed notification bus. The user sees a dashboard toast
  * instead of having to grep stderr.
  *
@@ -12,13 +12,14 @@
  */
 
 import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-const PENDING_PATH = join(homedir(), '.cx', 'approval-pending.jsonl');
+import { doctorRoot } from '../config/xdg.mjs';
+
+const PENDING_PATH = join(doctorRoot(), 'approval-pending.jsonl');
 
 function ensureDir() {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 

package/lib/roles/event-bus.mjs

@@ -14,7 +14,6 @@
 
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { resolveProjectScopedPath } from '../project-root.mjs';
 

package/lib/roles/gateway.mjs

@@ -11,15 +11,19 @@
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { emit, _paths } from './event-bus.mjs';
 import { route as routeEvent } from './router.mjs';
 import { runBd } from '../beads-client.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
+
+// CONSTRUCT_ROLES_ROOT still wins for the roles event ecosystem's test
+// isolation; the literal fallback follows the global doctor root instead of ~/.cx.
 
 function rootDir() {
-  return process.env.CONSTRUCT_ROLES_ROOT || join(homedir(), '.cx');
+  return process.env.CONSTRUCT_ROLES_ROOT || doctorRoot();
 }
 function pendingPath() {
   return join(rootDir(), 'role-pending.jsonl');

package/lib/rules-delivery.mjs

@@ -10,7 +10,7 @@
  * carry the `construct-` prefix and are swept when their rule stops matching, so
  * user-authored .mdc files are never touched (ADR-0027 ownership contract).
  * Claude/Codex/OpenCode have no per-rule glob mechanism; for them rules remain
- * reference-delivered (cited by path in prose) — see docs/concepts/rules-delivery.md.
+ * reference-delivered (cited by path in prose) — see docs/guides/concepts/rules-delivery.md.
  */
 import fs from 'node:fs';
 import path from 'node:path';

package/lib/runtime-pressure.mjs

@@ -10,6 +10,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+import { stateDir } from './config/xdg.mjs';
+
 const DEFAULTS = Object.freeze({
   enabled: '1',
   intervalSeconds: '300',
@@ -115,7 +117,7 @@ function summarizeTermination(entries) {
 
 function warningStatePath(env = process.env) {
   const homeDir = env.HOME || os.homedir();
-  return path.join(homeDir, '.construct', 'runtime', 'process-pressure-warnings.json');
+  return path.join(stateDir(homeDir), 'runtime', 'process-pressure-warnings.json');
 }
 
 function readWarningState(env = process.env) {
@@ -374,9 +376,9 @@ ${programArgs.map((arg) => `      <string>${plistEscape(arg)}</string>`).join('\
     <key>StartInterval</key>
     <integer>${intervalSeconds}</integer>
     <key>StandardOutPath</key>
-    <string>${plistEscape(path.join(homeDir, '.construct', 'runtime', 'pressure-release.log'))}</string>
+    <string>${plistEscape(path.join(stateDir(homeDir), 'runtime', 'pressure-release.log'))}</string>
     <key>StandardErrorPath</key>
-    <string>${plistEscape(path.join(homeDir, '.construct', 'runtime', 'pressure-release.log'))}</string>
+    <string>${plistEscape(path.join(stateDir(homeDir), 'runtime', 'pressure-release.log'))}</string>
   </dict>
 </plist>
 `;

package/lib/sandbox.mjs

@@ -18,11 +18,12 @@
  * lives under `~/.cx/sandboxes/<id>/` so they survive across CLI sessions.
  */
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-const ROOT = path.join(os.homedir(), '.cx', 'sandboxes');
+import { doctorRoot } from './config/xdg.mjs';
+
+const ROOT = path.join(doctorRoot(), 'sandboxes');
 
 function ensureRoot() {
   fs.mkdirSync(ROOT, { recursive: true });

package/lib/scheduler/solo.mjs

@@ -20,6 +20,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 
+import { doctorRoot } from '../config/xdg.mjs';
+
 // ---------------------------------------------------------------------------
 // Cron parsing helpers — minimal support for standard 5-field cron
 // ---------------------------------------------------------------------------
@@ -82,9 +84,9 @@ function writeLaunchdPlist(id, schedule, cwd) {
 ${calendarEntries}
     </dict>
     <key>StandardOutPath</key>
-    <string>${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stdout.log`)}</string>
+    <string>${path.join(doctorRoot(), 'scheduler', 'logs', `${id}.stdout.log`)}</string>
     <key>StandardErrorPath</key>
-    <string>${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stderr.log`)}</string>
+    <string>${path.join(doctorRoot(), 'scheduler', 'logs', `${id}.stderr.log`)}</string>
     <key>RunAtLoad</key>
     <false/>
 </dict>
@@ -120,8 +122,8 @@ Description=Construct job: ${id}
 Type=oneshot
 WorkingDirectory=${cwd}
 ExecStart=${constructBin} scheduler run ${id}
-StandardOutput=append:${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stdout.log`)}
-StandardError=append:${path.join(os.homedir(), '.cx', 'scheduler', 'logs', `${id}.stderr.log`)}
+StandardOutput=append:${path.join(doctorRoot(), 'scheduler', 'logs', `${id}.stdout.log`)}
+StandardError=append:${path.join(doctorRoot(), 'scheduler', 'logs', `${id}.stderr.log`)}
 `;
 
   fs.mkdirSync(unitDir, { recursive: true });

package/lib/server/auth.mjs

@@ -2,7 +2,7 @@
  * lib/server/auth.mjs — Dashboard authentication middleware.
  *
  * Token-based auth for the Construct dashboard. A single shared bearer token
- * is stored at ~/.construct/config.env under CONSTRUCT_DASHBOARD_TOKEN. If no
+ * is stored at config.env in the XDG config dir under CONSTRUCT_DASHBOARD_TOKEN. If no
  * token is configured the dashboard runs open (localhost-only by design). The
  * browser receives a short-lived session cookie on successful token exchange so
  * subsequent requests don't need to re-send the Authorization header.
@@ -16,9 +16,10 @@ import { randomBytes, timingSafeEqual } from 'crypto';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { configDir } from '../config/xdg.mjs';
 
 const HOME = homedir();
-const CONFIG_ENV = join(HOME, '.construct', 'config.env');
+const CONFIG_ENV = join(configDir(HOME), 'config.env');
 const SESSION_COOKIE = 'cx_session';
 const SESSION_TTL_MS = 8 * 60 * 60 * 1000; // 8 hours
 const SUPPORTED_OAUTH_PROVIDERS = new Set(['github', 'google']);
@@ -46,7 +47,7 @@ export function getDashboardToken() {
 }
 
 export function setDashboardToken(token) {
-  mkdirSync(join(HOME, '.construct'), { recursive: true });
+  mkdirSync(configDir(HOME), { recursive: true });
   const env = existsSync(CONFIG_ENV) ? readFileSync(CONFIG_ENV, 'utf8') : '';
   const lines = env.split('\n').filter(l => !l.startsWith('CONSTRUCT_DASHBOARD_TOKEN='));
   lines.push(`CONSTRUCT_DASHBOARD_TOKEN=${token}`);

package/lib/server/index.mjs

@@ -20,6 +20,7 @@ import { generateArtifact, listArtifacts } from '../embed/artifact.mjs';
 import { ApprovalQueue } from '../embed/approval-queue.mjs';
 import { resolveEmbedStatus } from '../embed/cli.mjs';
 import { loadConstructEnv, prepareConstructEnv } from '../runtime-env.mjs';
+import { configDir, doctorRoot } from '../config/xdg.mjs';
 import {
   isAuthConfigured, isAuthenticated, rejectUnauthorized,
   validateToken, createSession, sessionCookieHeader, clearSessionCookieHeader,
@@ -71,15 +72,15 @@ function assertSafeBind() {
 
 const STATIC_DIR = join(__dirname, 'static');
 const REGISTRY_FILE = join(ROOT_DIR, 'specialists', 'registry.json');
-const FEATURES_FILE = join(HOME, '.construct', 'features.json');
+const FEATURES_FILE = join(configDir(HOME), 'features.json');
 const WORKFLOW_FILE = join(ROOT_DIR, 'plan.md');
 const SKILLS_DIR = join(ROOT_DIR, 'skills');
 const COMMANDS_DIR = join(ROOT_DIR, 'commands');
-const SNAPSHOTS_FILE = join(HOME, '.cx', 'snapshots.jsonl');
-const APPROVAL_QUEUE_FILE = join(HOME, '.cx', 'approval-queue.jsonl');
-const CONFIG_ENV_FILE = join(HOME, '.construct', 'config.env');
-const EMBED_YAML_FILE = join(HOME, '.construct', 'embed.yaml');
-const CREDENTIAL_AUDIT_FILE = join(HOME, '.cx', 'credential-audit.jsonl');
+const SNAPSHOTS_FILE = join(doctorRoot(), 'snapshots.jsonl');
+const APPROVAL_QUEUE_FILE = join(doctorRoot(), 'approval-queue.jsonl');
+const CONFIG_ENV_FILE = join(configDir(HOME), 'config.env');
+const EMBED_YAML_FILE = join(configDir(HOME), 'embed.yaml');
+const CREDENTIAL_AUDIT_FILE = join(doctorRoot(), 'credential-audit.jsonl');
 
 // Provider → expected env vars. Source of truth for the credentials surface,
 // the per-provider health classification ("not configured" vs "unhealthy"),
@@ -97,7 +98,7 @@ const BUILTIN_CREDENTIAL_MAP = [
   { provider: 'salesforce',          label: 'Salesforce',    kind: 'integration', envVars: ['SALESFORCE_INSTANCE_URL', 'SALESFORCE_ACCESS_TOKEN'] },
 ];
 
-const CUSTOM_CREDENTIALS_FILE = join(HOME, '.construct', 'custom-credentials.json');
+const CUSTOM_CREDENTIALS_FILE = join(configDir(HOME), 'custom-credentials.json');
 
 // Env-var name validator: must match POSIX shell variable syntax and avoid
 // stomping built-in entries. Refusing $PATH / $HOME / OS-special prefixes
@@ -182,7 +183,7 @@ function resolveCredential(varName, env) {
     } catch { /* not available */ }
   }
 
-  const paths = [join(homeDir, '.construct', 'config.env'), join(homeDir, '.env')];
+  const paths = [join(configDir(homeDir), 'config.env'), join(homeDir, '.env')];
   for (const p of paths) {
     try {
       if (existsSync(p)) {
@@ -588,7 +589,7 @@ function handleConfig(req, res) {
         const { type, content } = JSON.parse(body || '{}');
         if (type !== 'env' && type !== 'embed') throw new Error('type must be env or embed');
         if (typeof content !== 'string') throw new Error('content must be a string');
-        mkdirSync(join(HOME, '.construct'), { recursive: true });
+        mkdirSync(configDir(HOME), { recursive: true });
         const target = type === 'env' ? CONFIG_ENV_FILE : EMBED_YAML_FILE;
         writeFileSync(target, content, 'utf8');
         res.writeHead(200, { 'Content-Type': 'application/json' });
@@ -1200,7 +1201,7 @@ const server = createServer(async (req, res) => {
 
   if (url.pathname === '/api/performance/reviews' && req.method === 'GET') {
     try {
-      const dir = join(HOME, '.cx', 'performance-reviews');
+      const dir = join(doctorRoot(), 'performance-reviews');
       if (!existsSync(dir)) {
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ reviews: [], total: 0, mockFiltered: 0, generatorImplemented: false }));
@@ -1327,7 +1328,7 @@ const server = createServer(async (req, res) => {
   if (url.pathname === '/api/mode' && req.method === 'GET') {
     try {
       const env = loadConstructEnv();
-      const embedYamlPath = join(HOME, '.construct', 'embed.yaml');
+      const embedYamlPath = join(configDir(HOME), 'embed.yaml');
       const embedStatus = resolveEmbedStatus(env);
       
       // Determine mode based on embed status and configuration
@@ -1374,7 +1375,7 @@ const server = createServer(async (req, res) => {
         parentUrl,
         isEmbedded,
         embedStatus: embedStatus.level,
-        embedConfigExists: existsSync(join(HOME, '.construct', 'embed.yaml')),
+        embedConfigExists: existsSync(join(configDir(HOME), 'embed.yaml')),
         capabilities: {
           modeDetection: true,
           snapshotStatus: true,
@@ -1620,7 +1621,7 @@ const server = createServer(async (req, res) => {
         rootDir: ROOT_DIR,
         guidance: INTAKE_DEPTH_GUIDANCE,
         hardMaxDepth: INTAKE_HARD_MAX_DEPTH,
-        defaults: { projectInbox: '.cx/inbox', docsIntake: 'docs/intake', rootInbox: 'inbox/' },
+        defaults: { rootInbox: 'inbox/' },
         label: rebrand.intakeQueueLabel,
         itemNoun: rebrand.signalNoun,
       }));
@@ -1780,7 +1781,7 @@ const server = createServer(async (req, res) => {
 
   if (url.pathname === '/api/providers/subscriptions' && req.method === 'GET') {
     try {
-      const file = join(HOME, '.construct', 'provider-subscriptions.json');
+      const file = join(configDir(HOME), 'provider-subscriptions.json');
       let data = { subscriptions: [] };
       if (existsSync(file)) {
         try { data = JSON.parse(readFileSync(file, 'utf8')); } catch { /* fall back to empty */ }
@@ -1810,7 +1811,7 @@ const server = createServer(async (req, res) => {
     res.writeHead(200, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({
       envPath: CONFIG_ENV_FILE,
-      overridesPath: join(HOME, '.construct', 'providers.json'),
+      overridesPath: join(configDir(HOME), 'providers.json'),
     }));
     return;
   }
@@ -2298,7 +2299,7 @@ const server = createServer(async (req, res) => {
           if (!resolved) throw new Error('op read returned an empty value');
 
           const { writeEnvValues, loadConstructEnv } = await import('../env-config.mjs');
-          mkdirSync(join(HOME, '.construct'), { recursive: true });
+          mkdirSync(configDir(HOME), { recursive: true });
           writeEnvValues(CONFIG_ENV_FILE, { [envVar]: resolved });
           process.env[envVar] = resolved;
           try { chmodSync(CONFIG_ENV_FILE, 0o600); } catch { /* perms best-effort */ }
@@ -2310,7 +2311,7 @@ const server = createServer(async (req, res) => {
           }
 
           try {
-            mkdirSync(join(HOME, '.cx'), { recursive: true });
+            mkdirSync(doctorRoot(), { recursive: true });
             appendFileSync(CREDENTIAL_AUDIT_FILE, JSON.stringify({ ts: new Date().toISOString(), action: 'set', envVar, source: '1password', opRef }) + '\n');
           } catch { /* audit best-effort */ }
 
@@ -2367,9 +2368,6 @@ const server = createServer(async (req, res) => {
           const next = saveIntakeConfig(ROOT_DIR, {
             parentDirs: Array.isArray(data.parentDirs) ? data.parentDirs : undefined,
             maxDepth: data.maxDepth,
-            includeProjectInbox: data.includeProjectInbox,
-            includeDocsIntake: data.includeDocsIntake,
-            includeRootInbox: data.includeRootInbox ?? data.includeArchetypeInbox,
           });
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(JSON.stringify({ success: true, config: next }));
@@ -2406,7 +2404,7 @@ const server = createServer(async (req, res) => {
           }
         } else if (url.pathname === '/api/providers/registry') {
           const { BUILT_INS } = await import('../providers/registry.mjs');
-          const overridesPath = join(HOME, '.construct', 'providers.json');
+          const overridesPath = join(configDir(HOME), 'providers.json');
           const { action, id, package: pkg, options } = data;
           if (!id || typeof id !== 'string' || !/^[\w-]+$/.test(id)) throw new Error('Invalid provider id');
           if (BUILT_INS.includes(id)) throw new Error(`cannot override built-in provider '${id}'`);
@@ -2432,7 +2430,7 @@ const server = createServer(async (req, res) => {
             throw new Error('action must be save or delete');
           }
 
-          mkdirSync(join(HOME, '.construct'), { recursive: true });
+          mkdirSync(configDir(HOME), { recursive: true });
           const tmp = overridesPath + '.tmp';
           writeFileSync(tmp, JSON.stringify(current, null, 2) + '\n');
           renameSync(tmp, overridesPath);
@@ -2460,7 +2458,7 @@ const server = createServer(async (req, res) => {
           if (value !== '' && typeof value !== 'string') throw new Error('value must be a string');
 
           const { writeEnvValues, parseEnvFile, loadConstructEnv } = await import('../env-config.mjs');
-          mkdirSync(join(HOME, '.construct'), { recursive: true });
+          mkdirSync(configDir(HOME), { recursive: true });
           const action = value === '' ? 'unset' : 'set';
 
           if (action === 'unset') {
@@ -2480,7 +2478,7 @@ const server = createServer(async (req, res) => {
           }
 
           try {
-            mkdirSync(join(HOME, '.cx'), { recursive: true });
+            mkdirSync(doctorRoot(), { recursive: true });
             appendFileSync(CREDENTIAL_AUDIT_FILE, JSON.stringify({ ts: new Date().toISOString(), action, envVar }) + '\n');
           } catch { /* audit append best-effort */ }
 
@@ -2488,7 +2486,7 @@ const server = createServer(async (req, res) => {
           res.end(JSON.stringify({ success: true }));
           notifyClients();
         } else if (url.pathname === '/api/providers/subscriptions') {
-          const subsPath = join(HOME, '.construct', 'provider-subscriptions.json');
+          const subsPath = join(configDir(HOME), 'provider-subscriptions.json');
           const { action, id, provider, name, config } = data;
           if (!id || typeof id !== 'string' || !/^[\w.-]+$/.test(id)) throw new Error('Invalid subscription id');
 
@@ -2509,7 +2507,7 @@ const server = createServer(async (req, res) => {
             throw new Error('action must be save or delete');
           }
 
-          mkdirSync(join(HOME, '.construct'), { recursive: true });
+          mkdirSync(configDir(HOME), { recursive: true });
           const tmp = subsPath + '.tmp';
           writeFileSync(tmp, JSON.stringify(current, null, 2) + '\n');
           renameSync(tmp, subsPath);

package/lib/server/insights.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readCostLog, summarizeCostData } from '../cost.mjs';
 import { getRebrand } from '../profiles/rebrand.mjs';
+import { configDir, doctorRoot } from '../config/xdg.mjs';
 
 const TELEMETRY_TIMEOUT_MS = 3500;
 
@@ -82,7 +83,7 @@ async function fetchTelemetrySummary(env, { limit = 100 } = {}) {
   // Fallback: read from local .cx/traces/ when Telemetry is unreachable or not configured.
   // The daemon always writes heartbeat, lifecycle, and probe events to local JSONL files.
   try {
-    const traceDir = path.join(os.homedir(), '.cx', 'traces');
+    const traceDir = path.join(doctorRoot(), 'traces');
     if (!fs.existsSync(traceDir)) return { state: 'empty', message: 'No local traces. Start the daemon with `construct dev`.' };
     const files = fs.readdirSync(traceDir).filter(f => f.endsWith('.jsonl')).sort().reverse();
     if (!files.length) return { state: 'empty', message: 'No local trace files.' };
@@ -412,7 +413,7 @@ function resolveModelCredential(primaryKey, altKey) {
     } catch { /* not available */ }
   }
 
-  const paths = [path.join(homeDir, '.construct', 'config.env'), path.join(homeDir, '.env')];
+  const paths = [path.join(configDir(homeDir), 'config.env'), path.join(homeDir, '.env')];
   for (const p of paths) {
     try {
       if (!fs.existsSync(p)) continue;
@@ -619,7 +620,7 @@ async function summarizeTelemetryLatency(env, { days = 7, limit = 50 } = {}) {
 
 function summarizeRetrievalEval(homeDir = os.homedir()) {
   try {
-    const cachePath = path.join(homeDir, '.cx', 'evals', 'retrieval-latest.json');
+    const cachePath = path.join(doctorRoot(homeDir), 'evals', 'retrieval-latest.json');
     if (!fs.existsSync(cachePath)) {
       return {
         state: 'empty',
@@ -630,7 +631,7 @@ function summarizeRetrievalEval(homeDir = os.homedir()) {
     const r = cached.report?.summary || cached.report || {};
     let history = [];
     try {
-      const historyPath = path.join(homeDir, '.cx', 'evals', 'retrieval-history.jsonl');
+      const historyPath = path.join(doctorRoot(homeDir), 'evals', 'retrieval-history.jsonl');
       if (fs.existsSync(historyPath)) {
         const lines = fs.readFileSync(historyPath, 'utf8').split('\n').filter(Boolean);
         history = lines.slice(-30).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);

package/lib/server/webhook.mjs

@@ -38,6 +38,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
 import { homedir as osHomedir } from 'os';
+import { configDir } from '../config/xdg.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 const ROOT_DIR = join(__dirname, '..', '..');
@@ -282,7 +283,7 @@ async function postSlackMessage(responseUrl, text, botToken) {
  * Load config.env values as an object.
  */
 function loadConfigEnv() {
-  const envFile = join(HOME, '.construct', 'config.env');
+  const envFile = join(configDir(HOME), 'config.env');
   if (!existsSync(envFile)) return {};
   const lines = readFileSync(envFile, 'utf8').split('\n');
   const out = {};

package/lib/service-manager.mjs

@@ -20,13 +20,15 @@ import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.
 import { memoryPort as derivedMemoryPort } from './home-namespace.mjs';
 import { readHeartbeat } from './daemons/contract.mjs';
 import { heartbeatPath } from './oracle/index.mjs';
+import { stateDir } from './config/xdg.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 
 const DASHBOARD_STATE_FILE = 'dashboard.json';
 
 const INSTALL_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 function runtimeStateDir(homeDir = os.homedir()) {
-  return path.join(homeDir, '.construct', 'runtime');
+  return path.join(stateDir(homeDir), 'runtime');
 }
 
 function dashboardStatePath(homeDir = os.homedir()) {
@@ -84,7 +86,7 @@ export function buildRuntimeRecoverySummary({ rootDir, homeDir = os.homedir(), r
     latestHandoff: relativeOrNull(rootDir, latestHandoffPath(rootDir)),
     beads: fs.existsSync(path.join(rootDir, '.beads', 'metadata.json')) ? '.beads/metadata.json' : null,
     userConfig: fs.existsSync(getUserEnvPath(homeDir)) ? getUserEnvPath(homeDir) : null,
-    userDataRoot: env.CX_DATA_DIR || path.join(homeDir, '.cx'),
+    userDataRoot: env.CX_DATA_DIR || doctorRoot(homeDir),
   };
 
   return {
@@ -215,7 +217,7 @@ export function stopDashboard(homeDir = os.homedir()) {
 }
 
 function doctorStatePath(homeDir) {
-  return path.join(homeDir, '.construct', 'doctor.json');
+  return path.join(stateDir(homeDir), 'doctor.json');
 }
 
 export function readDoctorState(homeDir = os.homedir()) {

package/lib/setup.mjs

@@ -22,6 +22,7 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { ensureUserConfigDir, getUserEnvPath, writeEnvValues } from './env-config.mjs';
+import { configDir, stateDir, doctorRoot } from './config/xdg.mjs';
 import { DEFAULT_WORKSPACE_PATH, WORKSPACE_DOCS_LANES } from './embed/config.mjs';
 import {
   DEFAULT_DEPLOYMENT_MODE,
@@ -97,7 +98,7 @@ function findCommand(command) {
 
 export function defaultVectorIndexPath(homeDir = HOME) {
   // LanceDB storage path
-  return path.join(homeDir, '.construct', 'vector', 'lancedb');
+  return path.join(stateDir(homeDir), 'vector', 'lancedb');
 }
 
 export async function buildManagedSetupValues({ homeDir = HOME, env = process.env } = {}) {
@@ -266,7 +267,7 @@ function ensureOpenCodeConfig() {
 export { ensureGitHooksPath } from './git-hooks-path.mjs';
 
 export function ensureLibSymlink({ homeDir = HOME, rootDir = ROOT_DIR } = {}) {
-  const target = path.join(homeDir, '.construct', 'lib');
+  const target = path.join(configDir(homeDir), 'lib');
   const source = path.join(rootDir, 'lib');
   fs.mkdirSync(path.dirname(target), { recursive: true });
   let stat = null;
@@ -348,12 +349,12 @@ function printInstallPlan({ scope, homeDir, withDocling, noLaunchAgent, cleanupL
   console.log('\nWould write:');
   console.log(`  · ${getUserEnvPath(homeDir)} (user config, managed defaults)`);
   console.log(`  · ${getCanonicalOpenCodeConfigPath(homeDir)} (OpenCode config)`);
-  console.log(`  · ${path.join(homeDir, '.construct', 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
-  console.log(`  · ${path.join(homeDir, '.construct', 'workspace')} (workspace docs scaffold)`);
+  console.log(`  · ${path.join(configDir(homeDir), 'lib')} → ${path.join(ROOT_DIR, 'lib')} (hook lib symlink)`);
+  console.log(`  · ${path.join(stateDir(homeDir), 'workspace')} (workspace docs scaffold)`);
   console.log(`  · ${path.dirname(defaultVectorIndexPath(homeDir))} (LanceDB vector store dir)`);
   console.log('\nWould check / install runtime tooling:');
   console.log('  · cm (memory CLI) and cass (session search) when available on PATH');
-  console.log('  · construct-chat desktop binary (from GitHub releases → ~/.construct/bin/)');
+  console.log(`  · construct-chat desktop binary (from GitHub releases → ${path.join(stateDir(homeDir), 'bin')})`);
   console.log('\nWould reach the network / external services:');
   console.log('  · embedding model warmup (loads from local cache; offline-safe, no download)');
   if (withDocling) console.log('  · docling Python venv provisioning via uv (~10 min)');
@@ -587,7 +588,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   runConstruct(['doctor']);
 
   const setupTs = new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-');
-  const setupLogPath = path.join(HOME, '.cx', `setup-${setupTs}.log`);
+  const setupLogPath = path.join(doctorRoot(), `setup-${setupTs}.log`);
   try {
     fs.mkdirSync(path.dirname(setupLogPath), { recursive: true });
     const logLines = [
@@ -605,7 +606,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
   console.log('  Traces:      local JSONL (.cx/traces)');
   console.log(`  Vector:      LanceDB (embedded)`);
   console.log(`    ${managedValues.CONSTRUCT_LANCEDB_PATH}`);
-  console.log('  Credentials are saved to ~/.construct/config.env for later reference.');
+  console.log(`  Credentials are saved to ${getUserEnvPath(homeDir)} for later reference.`);
 
   console.log('\nNext steps:');
   console.log('  construct provider add github     # Connect GitHub repository data');
@@ -621,7 +622,7 @@ function ensureUserConfig(homeDir = HOME) {
 }
 
 export function ensureWorkspace(homeDir = HOME) {
-  const wsPath = path.join(homeDir, '.construct', 'workspace');
+  const wsPath = path.join(stateDir(homeDir), 'workspace');
   const docsPath = path.join(wsPath, 'docs');
   for (const lane of WORKSPACE_DOCS_LANES) {
     fs.mkdirSync(path.join(docsPath, lane), { recursive: true });

package/lib/status.mjs

@@ -22,6 +22,7 @@ import { readCostLog, summarizeCostData, normalizeCostEntry } from './cost.mjs';
 import { readEfficiencyLog, summarizeEfficiencyData } from './efficiency.mjs';
 import { triggerAutoBackfillIfSparse } from './telemetry/backfill.mjs';
 import { resolveTraceBackend, telemetryProviderLabel } from './telemetry/client.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
 
 function readJSON(path) {
@@ -35,7 +36,7 @@ function readJSON(path) {
 
 
 function readSessionEfficiency(homeDir) {
-  const stats = readJSON(join(homeDir, '.cx', 'session-efficiency.json'));
+  const stats = readJSON(join(doctorRoot(homeDir), 'session-efficiency.json'));
   if (!stats) return null;
 
   const readCount = Number(stats.readCount || 0);
@@ -85,7 +86,7 @@ function readSessionEfficiency(homeDir) {
 }
 
 function readTelemetryRichness(homeDir) {
-  const stats = readJSON(join(homeDir, '.cx', 'session-telemetry.json'));
+  const stats = readJSON(join(doctorRoot(homeDir), 'session-telemetry.json'));
   if (!stats) return null;
 
   const total = Number(stats.total || 0);
@@ -134,7 +135,7 @@ export function readSessionUsage(homeDir) {
       totalCostUsd: 0,
       summary: 'No token usage recorded yet',
       lastInteraction: null,
-      source: join(homeDir, '.cx', 'session-cost.jsonl'),
+      source: join(doctorRoot(homeDir), 'session-cost.jsonl'),
       lastUpdatedAt: null,
     };
   }
@@ -180,7 +181,7 @@ export function readSessionUsage(homeDir) {
     totalCostUsd: data.totalCostUsd,
     summary: `${data.interactions} interaction${data.interactions === 1 ? '' : 's'} · ${data.providerTotalTokens.toLocaleString()} provider · ${billed.toLocaleString()} billed (${cacheReadPct}% cache read · ${cacheWritePct}% cache write · ${freshPct}% fresh)`,
     lastInteraction,
-    source: join(homeDir, '.cx', 'session-cost.jsonl'),
+    source: join(doctorRoot(homeDir), 'session-cost.jsonl'),
     lastUpdatedAt: lastInteraction.timestamp,
   };
 }
@@ -577,7 +578,7 @@ function buildSelfCheck() {
 
   // Embed daemon state
   try {
-    const stateFile = join(homedir(), '.cx', 'runtime', 'embed-daemon.json');
+    const stateFile = join(doctorRoot(), 'runtime', 'embed-daemon.json');
     if (existsSync(stateFile)) {
       const state = JSON.parse(readFileSync(stateFile, 'utf8'));
       if (state.status === 'running' && state.pid) {

package/lib/storage/embeddings-local.mjs

@@ -10,9 +10,10 @@
  * Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, quantized)
  */
 import { join } from 'node:path';
-import { homedir } from 'node:os';
 import { mkdirSync, existsSync } from 'node:fs';
 
+import { cacheDir as xdgCacheDir } from '../config/xdg.mjs';
+
 let modelPromise = null;
 let extractor = null;
 
@@ -23,7 +24,7 @@ async function getExtractor(cacheDir) {
   if (extractor) return extractor;
   if (modelPromise) return modelPromise;
 
-  const cachePath = cacheDir || join(homedir(), '.construct', 'cache', 'embeddings');
+  const cachePath = cacheDir || join(xdgCacheDir(), 'embeddings');
   if (!existsSync(cachePath)) {
     mkdirSync(cachePath, { recursive: true });
   }

package/lib/storage/sync.mjs

@@ -40,7 +40,7 @@ function toDocumentRows(rootDir, snapshot, project = 'construct') {
       title: 'Architecture docs',
       summary: body.slice(0, 240),
       body,
-      source_path: 'docs/concepts/architecture.md',
+      source_path: 'docs/guides/concepts/architecture.md',
       tags: ['architecture', 'docs'],
       content_hash: hashContent(body),
     });
@@ -64,7 +64,7 @@ function toDocumentRows(rootDir, snapshot, project = 'construct') {
   for (const doc of snapshot.productIntelDocs ?? []) {
     const body = doc.body;
     const rel = doc.path;
-    const kind = rel.startsWith('docs/prd/')
+    const kind = rel.startsWith('docs/specs/prd/')
       ? 'prd'
       : rel.startsWith('docs/meta-prd/')
         ? 'meta-prd'