@geraldmaron/construct 1.2.1 → 1.2.2

package/lib/contracts/violation-log.mjs

@@ -25,12 +25,12 @@
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
-import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
 import { resolveProjectScopedPath } from '../project-root.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
-const CX_DIR = join(homedir(), '.cx');
+const CX_DIR = doctorRoot();
 const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 
 // contract-violations are PROJECT-SCOPED: resolves to

package/lib/cost-ledger.mjs

@@ -5,7 +5,7 @@
  * before they blow the daily budget. Separate from lib/roles/ because both
  * the gateway and the cost watcher consume it.
  *
- * Storage: ~/.cx/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
+ * Storage: <doctorRoot>/cost-ledger.json — small JSON object keyed by `<dayKey>:<personaId>`.
  * Rotates: entries older than 30 days are pruned on each write.
  *
  * Budgets are env-driven defaults; explicit `CONSTRUCT_BUDGET_<PERSONA>` wins.
@@ -15,16 +15,17 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { cwd as procCwd } from 'node:process';
 
+import { doctorRoot } from './config/xdg.mjs';
+
 const PRUNE_DAYS = 30;
 const DEFAULT_PER_PERSONA = 10.0;
 const DEFAULT_TOTAL = 50.0;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function ledgerPath() {
   return join(rootDir(), 'cost-ledger.json');

package/lib/cost.mjs

@@ -8,6 +8,7 @@
  */
 import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 function numberFrom(...values) {
   for (const value of values) {
@@ -82,7 +83,7 @@ export function normalizeCostEntry(entry = {}) {
 }
 
 export function readCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (!existsSync(logPath)) return [];
   try {
     return readFileSync(logPath, 'utf8')
@@ -97,7 +98,7 @@ export function readCostLog(homeDir) {
 }
 
 export function clearCostLog(homeDir) {
-  const logPath = join(homeDir, '.cx', 'session-cost.jsonl');
+  const logPath = join(doctorRoot(homeDir), 'session-cost.jsonl');
   if (existsSync(logPath)) writeFileSync(logPath, '');
 }
 

package/lib/decisions/registry.mjs

@@ -7,7 +7,7 @@
  * contracts as the single source of truth.
  *
  * Three decision sources are indexed:
- *   - ADRs           docs/adr/*.md            (status + supersedes parsed from body)
+ *   - ADRs           docs/decisions/adr/*.md            (status + supersedes parsed from body)
  *   - Contracts      specialists/contracts.json (executable postconditions = enforcement)
  *   - Rules          rules/**\/*.md            (enforcement link via frontmatter; bead wvbf.4)
  *
@@ -37,7 +37,7 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const ENFORCES_LINE_RE = /^(?:\/\/|#|\*)?\s*@enforces\s+(\S+)\s*$/;
 
 // The body carries Status and Supersedes as markdown definition lines, not
-// frontmatter (see docs/adr/templates/_template.md); parse them positionally.
+// frontmatter (see docs/decisions/adr/templates/_template.md); parse them positionally.
 
 // ADR field styles vary across the lane: inline bold (`- **Status**: x`,
 // `**Status:** X`) and heading-then-value (`## Status` followed by the value on
@@ -121,7 +121,7 @@ function collectEnforcementBindings({ repoRoot }) {
 }
 
 function adrDecisions({ repoRoot, bindings }) {
-  const dir = join(repoRoot, 'docs', 'adr');
+  const dir = join(repoRoot, 'docs', 'decisions', 'adr');
   const out = [];
   if (!existsSync(dir)) return out;
   for (const name of readdirSync(dir)) {

package/lib/distill.mjs

@@ -9,8 +9,8 @@
 import { readdirSync, statSync, readFileSync, writeFileSync, existsSync, mkdirSync, openSync, readSync, closeSync } from 'fs';
 import { join, extname, relative, dirname, basename } from 'path';
 import { execSync, spawnSync } from 'child_process';
-import { homedir } from 'os';
 import { getActiveOverlays } from './headhunt.mjs';
+import { doctorRoot } from './config/xdg.mjs';
 import { withGenAiSpan, GenAiAttrs } from './telemetry/otel-tracer.mjs';
 import {
   EXTRACTABLE_DOCUMENT_EXTS,
@@ -347,7 +347,7 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
 
   const prompt = structured.prompt;
   if (mode === 'prompt' || !hasClaude()) {
-    const tmpFile = out || join(homedir(), '.cx', 'distill-prompt.txt');
+    const tmpFile = out || join(doctorRoot(), 'distill-prompt.txt');
     try { mkdirSync(dirname(tmpFile), { recursive: true }); } catch { /* exists */ }
     writeFileSync(tmpFile, prompt);
     process.stderr.write(`\n⚠ Prompt written to: ${tmpFile}\n`);

package/lib/docs-verify.mjs

@@ -210,7 +210,9 @@ function gitTrackedMdFiles(cwd, dir) {
 
 function checkIntakeTraceability(cwd) {
   const intakeFedDirs = [
+    path.join(cwd, 'docs', 'specs', 'prd'),
     path.join(cwd, 'docs', 'prd'),
+    path.join(cwd, 'docs', 'notes', 'research'),
     path.join(cwd, 'docs', 'research'),
     path.join(cwd, '.cx', 'knowledge', 'internal'),
   ];

package/lib/doctor/audit.mjs

@@ -6,17 +6,18 @@
  * what the L0 layer did while they weren't looking — and the basis for rolling
  * back a misfire if rules are wrong.
  *
- * Path: ~/.cx/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
+ * Path: <doctorRoot>/doctor-log.jsonl (overridable via CONSTRUCT_DOCTOR_ROOT for tests).
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+import { doctorRoot } from '../config/xdg.mjs';
+
 const MAX_LINES = 2000;
 
 function rootDir() {
-  return process.env.CONSTRUCT_DOCTOR_ROOT || join(homedir(), '.cx');
+  return doctorRoot();
 }
 function logPath() {
   return join(rootDir(), 'doctor-log.jsonl');

package/lib/doctor/cli.mjs

@@ -10,7 +10,6 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { readState } from './index.mjs';

package/lib/doctor/index.mjs

@@ -7,12 +7,11 @@
  * never starves the others. Termination via SIGTERM/SIGINT triggers a clean
  * shutdown that records a final audit entry.
  *
- * State file: ~/.construct/doctor.json (pid, started, lastTick).
+ * State file: doctor.json in the XDG state dir (pid, started, lastTick).
  * Audit log:  ~/.cx/doctor-log.jsonl.
  */
 
 import { writeFileSync, existsSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from './audit.mjs';
@@ -26,8 +25,9 @@ import * as consistency from './watchers/consistency.mjs';
 import * as mcpProtocol from './watchers/mcp-protocol.mjs';
 import * as cxBudget from './watchers/cx-budget.mjs';
 import * as graphStaleness from './watchers/graph-staleness.mjs';
+import { stateDir } from '../config/xdg.mjs';
 
-const STATE_PATH = join(homedir(), '.construct', 'doctor.json');
+const STATE_PATH = join(stateDir(), 'doctor.json');
 const WATCHERS = [disk, cost, processPressure, serviceHealth, bdWatch, handoffs, consistency, mcpProtocol, cxBudget, graphStaleness];
 
 let running = false;
@@ -35,7 +35,7 @@ let timers = [];
 let lastTickAt = {};
 
 function writeState(state) {
-  const dir = join(homedir(), '.construct');
+  const dir = stateDir();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify({ ...state, updatedAt: Date.now() }));
 }

package/lib/doctor/report.mjs

@@ -8,10 +8,10 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { recent } from './audit.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 import { getTotalDailySpend, getDailySpend, totalBudget, personaBudget, dayKey } from '../cost-ledger.mjs';
 
 function parseWindow(arg) {
@@ -67,8 +67,8 @@ export async function runReport(args = []) {
   const since = Date.now() - windowMs;
 
   const auditEntries = recent({ since, limit: 10000 });
-  const events = readJsonl(join(homedir(), '.cx', 'events.jsonl')).filter((e) => e.ts >= since);
-  const pending = readJsonl(join(homedir(), '.cx', 'role-pending.jsonl')).filter((e) => e.ts >= since);
+  const events = readJsonl(join(doctorRoot(), 'events.jsonl')).filter((e) => e.ts >= since);
+  const pending = readJsonl(join(doctorRoot(), 'role-pending.jsonl')).filter((e) => e.ts >= since);
 
   const summary = summarizeActions(auditEntries);
   const eventsByType = groupBy(events, (e) => e.type);

package/lib/doctor/watchers/bd-watch.mjs

@@ -4,7 +4,7 @@
  * Every 5 min, polls bd for open issues labeled `next:cx-<role>` where the
  * target persona is onboarded in the role framework. Newly-seen issues are
  * enqueued as pending invocations so session-start surfaces them to
- * Construct. Seen issues are remembered in ~/.cx/bd-watch-seen.json to
+ * Construct. Seen issues are remembered in <doctorRoot>/bd-watch-seen.json to
  * prevent re-emission while the label remains.
  *
  * Closes a gap in agent-tracker: agent-tracker only catches handoffs that
@@ -16,20 +16,20 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { appendBounded } from '../../logging/rotate.mjs';
 import { resolveProjectScope } from '../../project-root.mjs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { listOnboardedPersonas, loadManifest } from '../../roles/manifest.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 
 export const name = 'bd-watch';
 export const intervalMs = 5 * 60 * 1000;
 
-const SEEN_PATH = join(homedir(), '.cx', 'bd-watch-seen.json');
-const PENDING_PATH = join(homedir(), '.cx', 'role-pending.jsonl');
+const SEEN_PATH = join(doctorRoot(), 'bd-watch-seen.json');
+const PENDING_PATH = join(doctorRoot(), 'role-pending.jsonl');
 
 function ensureDir() {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 

package/lib/doctor/watchers/cost.mjs

@@ -10,10 +10,10 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
+import { doctorRoot } from '../../config/xdg.mjs';
 import {
   getTotalDailySpend,
   getDailySpend,
@@ -26,15 +26,15 @@ import {
 export const name = 'cost';
 export const intervalMs = 10 * 60 * 1000;
 
-const SESSION_COST_PATH = join(homedir(), '.cx', 'session-cost.jsonl');
-const STATE_PATH = join(homedir(), '.cx', 'cost-watcher-state.json');
+const SESSION_COST_PATH = join(doctorRoot(), 'session-cost.jsonl');
+const STATE_PATH = join(doctorRoot(), 'cost-watcher-state.json');
 
 function loadState() {
   if (!existsSync(STATE_PATH)) return { lastIngestedTsMs: 0 };
   try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return { lastIngestedTsMs: 0 }; }
 }
 function saveState(state) {
-  const dir = join(homedir(), '.cx');
+  const dir = doctorRoot();
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state));
 }

package/lib/doctor/watchers/disk.mjs

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'disk';
 export const intervalMs = 5 * 60 * 1000;
@@ -54,7 +55,7 @@ function rotateTarget({ path: relPath, maxLines }) {
 }
 
 function pruneRuntimeLogs() {
-  const runtimeDir = join(homedir(), '.construct', '.runtime');
+  const runtimeDir = join(cacheDir(), '.runtime');
   if (!existsSync(runtimeDir)) return { pruned: 0 };
   const maxAgeMs = 7 * 24 * 60 * 60 * 1000;
   const now = Date.now();
@@ -99,11 +100,11 @@ export async function tick() {
       kind: 'action',
       watcher: name,
       action: 'prune',
-      target: '.construct/.runtime/',
+      target: '.cache/construct/.runtime/',
       summary: `pruned ${runtimePrune.pruned} stale runtime log(s) (>7 days)`,
       context: runtimePrune,
     });
-    actions.push({ type: 'prune', target: '.construct/.runtime/' });
+    actions.push({ type: 'prune', target: '.cache/construct/.runtime/' });
   }
 
   const free = freeBytesAt(homedir());

package/lib/doctor/watchers/service-health.mjs

@@ -13,12 +13,12 @@
 
 import { spawnSync, spawn } from 'node:child_process';
 import { existsSync, readFileSync, openSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { record } from '../audit.mjs';
 import { escalate } from '../escalate.mjs';
+import { configDir, stateDir, cacheDir } from '../../config/xdg.mjs';
 
 export const name = 'service-health';
 export const intervalMs = 60 * 1000;
@@ -56,7 +56,7 @@ function probeTcp(host, port, timeoutMs = 1500) {
 }
 
 function probeDashboardPort() {
-  const statePath = join(homedir(), '.construct', 'dashboard.json');
+  const statePath = join(stateDir(), 'dashboard.json');
   if (!existsSync(statePath)) return true;
   try {
     const state = JSON.parse(readFileSync(statePath, 'utf8'));
@@ -68,7 +68,7 @@ function probeDashboardPort() {
 }
 
 function probeMemoryHealth() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   if (!existsSync(envPath)) return true;
   try {
     const env = readFileSync(envPath, 'utf8');
@@ -87,7 +87,7 @@ function dockerRestart(container) {
 
 function detachSpawn(command, args, logName) {
   try {
-    const runtimeDir = join(homedir(), '.construct', '.runtime');
+    const runtimeDir = join(cacheDir(), '.runtime');
     if (!existsSync(runtimeDir)) mkdirSync(runtimeDir, { recursive: true });
     const logPath = join(runtimeDir, logName);
     const fd = openSync(logPath, 'a');
@@ -106,7 +106,7 @@ function respawnViaConstructUp() {
 }
 
 function respawnCm() {
-  const envPath = join(homedir(), '.construct', 'config.env');
+  const envPath = join(configDir(), 'config.env');
   let port = '4231';
   try {
     if (existsSync(envPath)) {

package/lib/document-export.mjs

@@ -5,7 +5,7 @@
  *
  * Export **source** is Construct-authored markdown (typed artifacts). **Output**
  * spans many distributable formats. Ingest (separate pipeline) accepts PDF, Office,
- * email, AV, and plain text — see docs/reference/document-io.md.
+ * email, AV, and plain text — see docs/guides/reference/document-io.md.
  */
 
 import fs from 'node:fs';

package/lib/document-extract.mjs

@@ -345,8 +345,8 @@ function extractPdf(filePath) {
   if (extracted.text.length < threshold) {
     const ocrHint = process.env.CONSTRUCT_PDF_OCR_HINT || 'none';
     const hintMsg = ocrHint !== 'none'
-      ? `OCR backend hint: ${ocrHint}. See docs/intake/scanned-pdfs.md.`
-      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/intake/scanned-pdfs.md.';
+      ? `OCR backend hint: ${ocrHint}. See docs/guides/intake/scanned-pdfs.md.`
+      : 'Set CONSTRUCT_PDF_OCR_HINT=tesseract|pdfocr to enable OCR. See docs/guides/intake/scanned-pdfs.md.';
     extracted.droppedInfo.push(makeDropInfo({
       kind: 'scanned-pdf',
       count: pages,
@@ -692,7 +692,7 @@ export function extractDocumentText(filePath, { maxChars = null } = {}) {
   // Throw a typed error so callers can route to .cx/intake/needs-asr/.
   if (AUDIO_VIDEO_EXTS.has(extension)) {
     const err = new Error(
-      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/intake/audio-video.md.`,
+      `Audio/video extraction requires ASR. Set CONSTRUCT_ASR_BACKEND=whisper|assemblyai to enable. See docs/guides/intake/audio-video.md.`,
     );
     err.code = 'ASR_REQUIRED';
     err.extension = extension;

package/lib/document-ingest.mjs

@@ -137,19 +137,29 @@ function collectInputFiles(inputPath, { maxDepth = 10 } = {}) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 
+// Ingest writes a markdown rendering of the source, preserving the source name
+// for provenance (report.pdf → report.pdf.md). A source already in markdown keeps
+// its name unchanged so it never gains a second extension (_template.md →
+// _template.md, not _template.md.md).
+
+function markdownOutputName(sourcePath) {
+  const base = basename(sourcePath);
+  return /\.md$/i.test(base) ? base : `${base}.md`;
+}
+
 function resolveOutputPath(sourcePath, { cwd, outputPath, outputDir, target }) {
   if (outputPath) return normalizeOutputPath(outputPath, cwd);
   if (target === 'sibling') {
-    return join(dirname(sourcePath), `${basename(sourcePath)}.md`);
+    return join(dirname(sourcePath), markdownOutputName(sourcePath));
   }
   // knowledge/<subdir> targets land in .cx/knowledge/<subdir>/
   if (target.startsWith('knowledge/')) {
     const sub = target.slice('knowledge/'.length);
     const resolvedDir = normalizeOutputPath(`${KNOWLEDGE_ROOT}/${sub}`, cwd);
-    return join(resolvedDir, `${basename(sourcePath)}.md`);
+    return join(resolvedDir, markdownOutputName(sourcePath));
   }
   const resolvedDir = normalizeOutputPath(outputDir || DEFAULT_TARGET_DIR, cwd);
-  return join(resolvedDir, `${basename(sourcePath)}.md`);
+  return join(resolvedDir, markdownOutputName(sourcePath));
 }
 
 // The high-fidelity (docling) path provisions a Python venv and downloads ML

package/lib/efficiency.mjs

@@ -6,13 +6,14 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { doctorRoot } from './config/xdg.mjs';
 
 const HIGH_BYTES_THRESHOLD = 750_000;
 const HIGH_REPEATED_RATIO = 0.4;
 const HIGH_LARGE_READ_COUNT = 3;
 
 export function readEfficiencyLog(homeDir) {
-  const filePath = join(homeDir, '.cx', 'session-efficiency.json');
+  const filePath = join(doctorRoot(homeDir), 'session-efficiency.json');
   if (!existsSync(filePath)) return null;
   try {
     return JSON.parse(readFileSync(filePath, 'utf8'));

package/lib/embed/approval-queue.mjs

@@ -10,7 +10,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import os from 'node:os';
+
+import { doctorRoot } from '../config/xdg.mjs';
 
 export class ApprovalQueue {
   #items = new Map();   // id → ApprovalItem
@@ -171,6 +172,6 @@ export class ApprovalQueue {
   }
 
   static defaultPersistPath() {
-    return path.join(os.homedir(), '.cx', 'approval-queue.jsonl');
+    return path.join(doctorRoot(), 'approval-queue.jsonl');
   }
 }

package/lib/embed/cli.mjs

@@ -21,6 +21,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { configDir } from '../config/xdg.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 const STATE_FILE = 'embed-daemon.json';
 const LOG_FILE   = 'embed-daemon.log';
@@ -30,7 +32,7 @@ const LOG_FILE   = 'embed-daemon.log';
 // ---------------------------------------------------------------------------
 
 function runtimeDir(homeDir = os.homedir()) {
-  return path.join(homeDir, '.cx', 'runtime');
+  return path.join(doctorRoot(homeDir), 'runtime');
 }
 
 function statePath(homeDir = os.homedir()) {
@@ -273,8 +275,8 @@ async function cmdEmbedStart(args, { homeDir = os.homedir(), rootDir, _workerPat
   const { config } = parseArgs(args);
   const configPath = config
     ? path.resolve(config)
-    : fs.existsSync(path.join(os.homedir(), '.construct', 'embed.yaml'))
-      ? path.join(os.homedir(), '.construct', 'embed.yaml')
+    : fs.existsSync(path.join(configDir(), 'embed.yaml'))
+      ? path.join(configDir(), 'embed.yaml')
       : null;
 
   const workerPath = _workerPath ?? path.join(rootDir, 'lib', 'embed', 'worker.mjs');
@@ -374,7 +376,7 @@ async function cmdEmbedStatus(_args, { homeDir = os.homedir() } = {}) {
   process.stdout.write(`  pid:        ${state.pid}\n`);
   process.stdout.write(`  config:     ${state.configPath}\n`);
   process.stdout.write(`  rootDir:    ${rootDir}\n`);
-  process.stdout.write(`  inbox:      ${path.join(rootDir, '.cx', 'inbox')}\n`);
+  process.stdout.write(`  inbox:      ${path.join(rootDir, 'inbox')}\n`);
   process.stdout.write(`  started at: ${state.startedAt}\n`);
   process.stdout.write(`  log:        ${logPath(homeDir)}\n`);
 }
@@ -387,7 +389,7 @@ async function cmdEmbedSnapshot(args, { homeDir = os.homedir() } = {}) {
   const { config } = parseArgs(args);
   const configPath = config
     ? path.resolve(config)
-    : path.join(os.homedir(), '.construct', 'embed.yaml');
+    : path.join(configDir(), 'embed.yaml');
 
   const { loadEmbedConfig, EMPTY_CONFIG } = await import('./config.mjs');
   const { SnapshotEngine, renderMarkdown } = await import('./snapshot.mjs');

package/lib/embed/config.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/embed/config.mjs — embed mode configuration schema and loader.
  *
- * Reads embed.yaml from ~/.construct/embed.yaml (or a supplied path) and validates
+ * Reads embed.yaml from the XDG config dir (or a supplied path) and validates
  * the file against the expected schema. Returns a parsed, normalized config object.
  *
  * Schema:
@@ -55,6 +55,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { configDir, stateDir } from '../config/xdg.mjs';
 
 const DEFAULTS = {
   snapshot: { intervalMs: 300_000, maxItems: 100 },
@@ -74,13 +75,13 @@ const DEFAULTS = {
  *     ref: github.com/org/project-y
  *     path: /Users/user/Github/project-y      # both — prefer local, fall back to remote
  *   - type: workspace                         # always present as fallback
- *     path: ~/.construct/workspace
+ *     path: <XDG_STATE_HOME>/construct/workspace
  *
  * roles:
  *   primary: product-manager    # shapes embed analysis lens
  *   secondary: architect        # persistent background concern
  */
-export const DEFAULT_WORKSPACE_PATH = path.join(os.homedir(), '.construct', 'workspace');
+export const DEFAULT_WORKSPACE_PATH = path.join(stateDir(), 'workspace');
 
 export const WORKSPACE_DOCS_LANES = ['adrs', 'prds', 'memos', 'notes', 'intake'];
 
@@ -99,7 +100,7 @@ export const DEFAULT_OPERATING_PROFILE = {
   },
   focalResources: [
     { type: 'plan', path: 'plan.md', purpose: 'active implementation plan' },
-    { type: 'architecture', path: 'docs/concepts/architecture.md', purpose: 'system architecture and operating model' },
+    { type: 'architecture', path: 'docs/guides/concepts/architecture.md', purpose: 'system architecture and operating model' },
     { type: 'knowledge', path: '.cx/knowledge', purpose: 'typed project knowledge and ingested evidence' },
     { type: 'runtime', path: '.cx/roadmap.md', purpose: 'generated roadmap output' },
   ],
@@ -351,5 +352,5 @@ export function parseEmbedYaml(text) {
 }
 
 export function defaultEmbedConfigPath() {
-  return path.join(os.homedir(), '.construct', 'embed.yaml');
+  return path.join(configDir(), 'embed.yaml');
 }

package/lib/embed/daemon.mjs

@@ -13,7 +13,7 @@
  *   - approval-expiry   — expires stale approval queue items
  *   - eval-dataset-sync — syncs scored traces to telemetry dataset items
  *   - prompt-regression-check — detects low-quality score clusters per promptHash
- *   - inbox-watcher     — ingests new files from .cx/inbox/ + CX_INBOX_DIRS into
+ *   - inbox-watcher     — ingests new files from inbox/ + CX_INBOX_DIRS into
  *                         observations (agnostic: specs, ADRs, meeting notes, etc.)
  *   - roadmap           — cross-references open items + observations → .cx/roadmap.md
  *
@@ -48,6 +48,7 @@ import { emitEmbedNotification, notifySlack } from './notifications.mjs';
 import { intentToCategory } from './providers/slack.mjs';
 import { runTelemetrySetup } from '../telemetry/setup.mjs';
 import { emitTraceEvent, newTraceId, newSpanId } from '../worker/trace.mjs';
+import { doctorRoot } from '../config/xdg.mjs';
 
 /**
  * Log a non-fatal error to stderr. Use instead of empty catch {} blocks
@@ -121,8 +122,8 @@ function resolveDaemonStatePath(env = process.env) {
 
 // ─── Self-repair helpers ────────────────────────────────────────────────────
 
-const LOCK_PATH = join(homedir(), '.cx', 'sync.lock');
-const DAEMON_STATE_PATH = join(homedir(), '.cx', 'runtime', 'embed-daemon.json');
+const LOCK_PATH = join(doctorRoot(), 'sync.lock');
+const DAEMON_STATE_PATH = join(doctorRoot(), 'runtime', 'embed-daemon.json');
 
 /**
  * Run in-process health checks and fix what can be fixed.
@@ -562,7 +563,7 @@ export class EmbedDaemon {
       'daemon-log-rotation',
       60_000,
       async () => {
-        const logPath = join(homedir(), '.cx', 'runtime', 'embed-daemon.log');
+        const logPath = join(doctorRoot(), 'runtime', 'embed-daemon.log');
         const capMb = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_MB) || 50;
         const maxBytes = Math.floor(capMb * 1024 * 1024);
         const maxSegments = Number(process.env.CONSTRUCT_EMBED_LOG_MAX_SEGMENTS) || 5;
@@ -729,7 +730,7 @@ this.#scheduler.register(
     // Every 2 min — scan configured inbox dirs for new files, ingest them, and
     // record observations. Agnostic to content: specs, ADRs, meeting notes,
     // internal docs, PDFs, Office files — anything on the local filesystem.
-    // Dirs: <rootDir>/.cx/inbox/ always; CX_INBOX_DIRS env for extra paths.
+    // Dirs: <rootDir>/inbox/ always; CX_INBOX_DIRS env for extra paths.
     this.#scheduler.register(
       'inbox-watcher',
       2 * 60_000,

package/lib/embed/inbox-live-watcher.mjs

@@ -3,7 +3,7 @@
  *
  * Registers a node:fs.watch listener on each inbox directory and triggers
  * `InboxWatcher.poll()` shortly after filesystem activity settles, so files
- * dropped into `.cx/inbox/` flow through ingest + the review queue in
+ * dropped into `inbox/` flow through ingest + the review queue in
  * seconds rather than waiting for the scheduler's next interval.
  *
  * Two limits keep this stable across platforms: