@geraldmaron/construct 1.2.0 → 1.2.2

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.0",
+  "version": "1.2.2",
   "type": "module",
   "packageManager": "npm@11.5.1",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
@@ -52,7 +52,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 +80,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",