@geraldmaron/construct 1.2.1 → 1.2.3

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

@@ -3,8 +3,8 @@
  * lib/setup.mjs — Machine-scoped first-run setup wizard for Construct.
  *
  * Installs cm/cass, configures managed defaults, pre-warms the embedding model,
- * wires MCP integrations, and writes ~/.construct/config.env. 
- * Invoked by `construct install` and by lib/install/first-invocation.mjs 
+ * wires MCP integrations, and writes the XDG user config (~/.config/construct/config.env).
+ * Invoked by `construct install` and by lib/install/first-invocation.mjs
  * when a TTY user is missing resources.
  *
  * Project-scoped scaffolding (`.cx/`, AGENTS.md, plan.md, adapters) lives
@@ -22,6 +22,8 @@ import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 
 import { ensureUserConfigDir, getUserEnvPath, writeEnvValues } from './env-config.mjs';
+import { migrateLegacyModelConfig } from './config/legacy-config-migration.mjs';
+import { configDir, stateDir, doctorRoot } from './config/xdg.mjs';
 import { DEFAULT_WORKSPACE_PATH, WORKSPACE_DOCS_LANES } from './embed/config.mjs';
 import {
   DEFAULT_DEPLOYMENT_MODE,
@@ -64,7 +66,7 @@ Flags:
                       before setup; does not uninstall a global construct CLI
 
 What --scope=user does:
-  - creates ~/.construct/config.env
+  - creates ~/.config/construct/config.env
   - ensures OpenCode config exists
   - configures managed defaults for local vector retrieval (LanceDB)
   - checks required runtime tools and installs cm and cass when available
@@ -97,7 +99,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 +268,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 +350,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)');
@@ -407,6 +409,14 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     return;
   }
 
+  // Forward-migrate model tier overrides stranded in the pre-XDG legacy config
+  // before any legacy-global cleanup deletes ~/.construct, so an upgrade keeps
+  // the user's tier selection without a manual copy.
+  const modelMigration = migrateLegacyModelConfig({ homeDir });
+  if (modelMigration.performed) {
+    console.log(`Migrated ${Object.keys(modelMigration.migrated).join(', ')} from ${modelMigration.legacyPath} → ${modelMigration.xdgPath}`);
+  }
+
   if (cleanupLegacyGlobal) {
     runLegacyGlobalCleanup({ homeDir, dryRun: false });
     if (scope === 'project') {
@@ -587,7 +597,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 +615,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 +631,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'

package/lib/telemetry/client.mjs

@@ -5,7 +5,6 @@
  * CONSTRUCT_TRACE_BACKEND and never throws into callers.
  */
 import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 

package/lib/telemetry/intent-verifications.mjs

@@ -13,18 +13,18 @@
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // intent-verifications are PROJECT-SCOPED — a verification belongs to a
-// specific routing decision in a specific project. DEFAULT_LOG_PATH stays
-// at the legacy user-scope location for back-compat with readers that
-// imported the constant; the writer below resolves per-call so each
-// invocation lands in the project's .cx/ when one is detected.
+// specific routing decision in a specific project. DEFAULT_LOG_PATH resolves
+// to the global doctor root for back-compat with readers that imported the
+// constant; the writer below resolves per-call so each invocation lands in
+// the project's .cx/ when one is detected.
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'intent-verifications.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'intent-verifications.jsonl');
 
 /**
  * Fire-and-forget append of one verification event.

package/lib/telemetry/model-pricing-catalog.mjs

@@ -15,13 +15,14 @@
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join } from "path";
-import { homedir } from "os";
+
+import { doctorRoot } from "../config/xdg.mjs";
 
 const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
 const LITELLM_PRICING_URL =
   "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
 const PRICING_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const PRICING_CACHE_PATH = join(homedir(), ".cx", "pricing-cache.json");
+const PRICING_CACHE_PATH = join(doctorRoot(), "pricing-cache.json");
 
 export function describePricingCatalogFreshness() {
   try {
@@ -133,7 +134,7 @@ async function fetchLiteLLMPricing(fetchImpl = globalThis.fetch) {
       });
     }
     try {
-      mkdirSync(join(homedir(), ".cx"), { recursive: true });
+      mkdirSync(doctorRoot(), { recursive: true });
       writeFileSync(PRICING_CACHE_PATH, JSON.stringify({ fetchedAt: Date.now(), models }));
     } catch { /* non-critical */ }
     return models;

package/lib/telemetry/rule-calls.mjs

@@ -1,16 +1,16 @@
 /**
  * lib/telemetry/rule-calls.mjs — record when a rule path is referenced at runtime.
  *
- * Mirrors hook-calls telemetry: append-only JSONL at ~/.cx/rule-calls.jsonl.
+ * Mirrors hook-calls telemetry: append-only JSONL at <doctorRoot>/rule-calls.jsonl.
  * Consumed by `construct rules usage` for consolidation decisions.
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'rule-calls.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'rule-calls.jsonl');
 
 /**
  * @param {object} event

package/lib/telemetry/skill-calls.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/telemetry/skill-calls.mjs — measure which skill files actually get loaded.
  *
- * Appends one JSON line per skill load to ~/.cx/skill-calls.jsonl so
+ * Appends one JSON line per skill load to <doctorRoot>/skill-calls.jsonl so
  * `construct skills usage/orphans/hot/correlate-quality` can answer:
  * which skills have no load events in a 30-day window (pruning candidates),
  * which skills are loaded from many agents (hot paths), and which skills
@@ -15,17 +15,17 @@
  */
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { appendBounded } from '../logging/rotate.mjs';
 import { resolveProjectScope } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 // Skill calls are CROSS-PROJECT telemetry — a single log lets you see which
 // skills load hot across every project the user has run Construct in. Stays
 // at user scope; each entry is tagged with `projectId` so a reader can
 // attribute usage to a specific project without losing the global view.
 
-export const DEFAULT_LOG_PATH = path.join(os.homedir(), '.cx', 'skill-calls.jsonl');
+export const DEFAULT_LOG_PATH = path.join(doctorRoot(), 'skill-calls.jsonl');
 
 /**
  * Fire-and-forget log of a skill load event.

package/lib/template-registry.mjs

@@ -70,4 +70,5 @@ export const TEMPLATE_OWNERSHIP_EXEMPTIONS = new Set([
   'rfc-platform',
   'prd-platform',
   'prd-business',
+  'README',
 ]);

package/lib/templates/visual-requirements.mjs

@@ -3,7 +3,7 @@
  *
  * Loads structure and visual requirements from specialists/artifact-manifest.json
  * (single source of truth) and merges legacy types not yet in the manifest.
- * Paired with docs/concepts/doc-visual-matrix.md; pinned by template tests.
+ * Paired with docs/guides/concepts/doc-visual-matrix.md; pinned by template tests.
  */
 
 import { validateArtifactPostconditions } from '../contracts/validate.mjs';

package/lib/test-corpus-inventory.mjs

@@ -173,7 +173,7 @@ export function computeReleaseCriticalGaps(ledger) {
   for (const row of SHIPPED_MATRIX_CAPABILITIES) {
     if (ledgerCoversHint(allLedgerIds, row.ledgerHints)) continue;
     gaps.push({
-      source: 'docs/audit/capability-matrix.md',
+      source: 'docs/operations/audit/capability-matrix.md',
       capability: row.id,
       status: 'shipped',
       reason: 'no ledger entry matches shipped capability hints',

package/lib/uninstall/uninstall.mjs

@@ -24,7 +24,7 @@
  *   --dry-run             print the plan, change nothing
  *   --yes                 non-interactive; remove auto-risk items, skip ask-risk items
  *   --yes --all           non-interactive; remove both auto- and ask-risk items
- *   --keep-state          only remove project-scope launcher + adapters; preserve .cx/, ~/.construct, Postgres
+ *   --keep-state          only remove project-scope launcher + adapters; preserve .cx/, the XDG user dirs, Postgres
  *   --with-images         also remove the shared pgvector Docker image (off by default; ADR-0027)
  *   --scope=project|machine|all   limit which categories are evaluated (default: all)
  */
@@ -37,6 +37,7 @@ import { fileURLToPath } from 'node:url';
 
 import { multiSelect } from '../tty-prompts.mjs';
 import { getUserConfigDir, getUserEnvPath } from '../env-config.mjs';
+import { stateDir, cacheDir, doctorRoot } from '../config/xdg.mjs';
 import { removeTomlTables, tomlString } from '../codex-config.mjs';
 import { postgresContainerName, LEGACY_PG_CONTAINER } from '../home-namespace.mjs';
 
@@ -84,12 +85,13 @@ function buildCategories({ cwd, home, withImages = false }) {
   const projectPlanMd = path.join(cwd, 'plan.md');
   const userHome = home;
   const userConstructDir = getUserConfigDir(userHome);
+  const userStateDir = stateDir(userHome);
   const userConfigEnv = getUserEnvPath(userHome);
-  const userEmbedCache = path.join(userConstructDir, 'cache', 'embeddings');
-  const userVectorIndex = path.join(userConstructDir, 'vector');
-  const userWorkspace = path.join(userConstructDir, 'workspace');
+  const userEmbedCache = path.join(cacheDir(userHome), 'embeddings');
+  const userVectorIndex = path.join(userStateDir, 'vector');
+  const userWorkspace = path.join(userStateDir, 'workspace');
   const userPgComposeDir = path.join(userConstructDir, 'services', 'postgres');
-  const userCxDir = path.join(userHome, '.cx');
+  const userCxDir = doctorRoot(userHome);
   const launchAgentPlist = path.join(userHome, 'Library', 'LaunchAgents', `${PRESSURE_GUARD_LABEL}.plist`);
   const claudeSettings = path.join(userHome, '.claude', 'settings.json');
   const opencodeConfig = path.join(userHome, '.config', 'opencode', 'opencode.json');
@@ -172,7 +174,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-workspace',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.construct/workspace and ~/.construct/vector',
+      label: `${rel(userHome, userWorkspace)} and ${rel(userHome, userVectorIndex)}`,
       detect: () => existsAny(userWorkspace) || existsAny(userVectorIndex),
       describe: () => 'Removes the per-user working dir and fallback JSON vector index. Both are regenerated on next use.',
       execute: () => {
@@ -186,7 +188,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-cx',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.cx (daemon state, logs)',
+      label: `${rel(userHome, userCxDir)} (daemon state, logs)`,
       detect: () => existsAny(userCxDir),
       describe: () => `Removes ${rel(userHome, userCxDir)}. Daemon PIDs, telemetry, setup logs; all regenerated on next setup.`,
       execute: () => removePath(userCxDir),
@@ -195,7 +197,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-embedding-cache',
       scope: 'machine',
       risk: 'ask',
-      label: '~/.construct/cache/embeddings (~22 MB ONNX model)',
+      label: `${rel(userHome, userEmbedCache)} (~22 MB ONNX model)`,
       detect: () => existsAny(userEmbedCache),
       describe: () => 'Removes the cached ONNX embedding model. Skip if you plan to reinstall soon — re-downloading takes a minute.',
       execute: () => removePath(userEmbedCache),
@@ -204,7 +206,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-config-env',
       scope: 'machine',
       risk: 'ask',
-      label: '~/.construct/config.env (API keys + consent flags)',
+      label: `${rel(userHome, userConfigEnv)} (API keys + consent flags)`,
       detect: () => existsAny(userConfigEnv),
       describe: () => 'Removes saved API keys (Anthropic/OpenAI/telemetry/etc.) and bootstrap consent. Skip if you intend to reinstall and reuse the keys.',
       execute: () => removePath(userConfigEnv),
@@ -231,7 +233,7 @@ function buildCategories({ cwd, home, withImages = false }) {
       id: 'machine-postgres-compose',
       scope: 'machine',
       risk: 'auto',
-      label: '~/.construct/services/postgres/ (compose file)',
+      label: `${rel(userHome, userPgComposeDir)} (compose file)`,
       detect: () => existsAny(userPgComposeDir),
       describe: () => 'Removes the local docker-compose.yml. Run after removing the container.',
       execute: () => removePath(userPgComposeDir),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -17,6 +17,7 @@
     "bin/construct",
     "bin/construct-postinstall.mjs",
     "lib/**",
+    "apps/chat/engine/**",
     "specialists/**",
     "examples/**",
     "personas/**",
@@ -52,7 +53,7 @@
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
     "test": "node scripts/run-tests.mjs",
-    "test:functional": "node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
+    "test:functional": "XDG_CONFIG_HOME= XDG_STATE_HOME= XDG_CACHE_HOME= node --test --test-timeout=120000 --test-concurrency=1 tests/functional/*.functional.test.mjs",
     "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "lint:js": "eslint bin/construct \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"tests/**/*.mjs\"",
     "coverage": "c8 --reporter=text-summary --reporter=lcov --src=lib --src=bin node scripts/run-tests.mjs --exclude=tests/functional",
@@ -80,7 +81,7 @@
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct docs:site --check && node ./bin/construct registry:generate-docs --check && node ./bin/construct docs:verify --strict && node scripts/alignment/census.mjs --ratchet && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node ./bin/construct certify gate && node scripts/lint-commits-pr.mjs",
     "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
     "audit:published": "node scripts/audit-published-artifact.mjs",
-    "version": "node scripts/sync-construct-version.mjs && git add .construct/version",
+    "version": "node scripts/sync-construct-version.mjs && git add -f .construct/version",
     "release:preflight": "node scripts/pre-release-check.mjs",
     "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",