@geraldmaron/construct 1.0.15 → 1.0.16

package/lib/contracts/validate.mjs

@@ -157,16 +157,24 @@ export function findContract({ producer, consumer, id, contractsPath = CONTRACTS
  * itself a contract violation (MCP best-practice 2025 — no silent skip on
  * tool-argument omission).
  */
-export function validateHandoff({
-  producer,
-  consumer,
-  id,
-  artifact,
-  packet,
-  contractsPath = CONTRACTS_PATH,
-  repoRoot = REPO_ROOT,
-  enforcement = 'block',
-}) {
+export function validateHandoff(opts = {}) {
+  const {
+    producer,
+    consumer,
+    id,
+    artifact,
+    packet,
+    contractsPath = CONTRACTS_PATH,
+    repoRoot = REPO_ROOT,
+    enforcement = 'block',
+  } = opts;
+  // Distinguish caller-supplied repoRoot from the default. Only an explicit
+  // repoRoot routes the violation log write — the default REPO_ROOT is for
+  // joining schema paths in this module, and forwarding it to the logger
+  // would override the cwd-based project-scope resolver that the test
+  // suite (and runtime project state) relies on.
+  const explicitRepoRoot = Object.prototype.hasOwnProperty.call(opts, 'repoRoot') ? repoRoot : undefined;
+
   const errors = [];
   const postconditionFailures = [];
 
@@ -193,6 +201,7 @@ export function validateHandoff({
       logViolation(`${producer}->${consumer}`, 'output', errors, packet ?? artifact, {
         verdict: postconditionFailures.length > 0 ? 'BLOCKED_CONTRACT' : 'CONTRACT_VIOLATION',
         postconditionFailures,
+        repoRoot: explicitRepoRoot,
       });
       return enforcement === 'block'
         ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`, ...errors], contract: null }
@@ -247,6 +256,7 @@ export function validateHandoff({
   logViolation(contract.id, 'output', errors, packet ?? artifact, {
     verdict,
     postconditionFailures,
+    repoRoot: explicitRepoRoot,
   });
 
   if (enforcement === 'block') return { ok: false, status: 'BLOCKED_CONTRACT', errors, contract };

package/lib/contracts/violation-log.mjs

@@ -39,10 +39,22 @@ const LAST_AGENT = join(CX_DIR, 'last-agent.json');
 // cwd/HOME changes inside the same process (tests, harness reuse) route
 // correctly.
 
-function logFile() {
+function logFile(repoRoot) {
+  // Explicit repoRoot bypasses the marker-walk in resolveProjectScope: the
+  // caller has already decided the scope (test fixture, sandbox, embedded
+  // worktree). Without this, a fixture without a `.cx/` marker falls back
+  // to ~/.cx/ and pollutes the developer's home log.
+  if (repoRoot) return join(repoRoot, '.cx', 'contract-violations.jsonl');
   return resolveProjectScopedPath('contract-violations.jsonl', { ensureDir: false });
 }
 
+// Exposed for diagnostic surfaces (e.g. doctor) that need to print the
+// real path. Resolves on every call so cwd/HOME changes inside the same
+// process route correctly. `repoRoot` overrides cwd-based resolution so
+// callers running against a fixture (tests, sandboxes) can isolate their
+// log writes from the developer's project log.
+export function violationLogPath(repoRoot) { return logFile(repoRoot); }
+
 function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
 
 function readLastAgent() {
@@ -50,44 +62,47 @@ function readLastAgent() {
   catch { return 'construct'; }
 }
 
-function readTailRecord() {
-  const file = logFile();
+function readTailRecord(repoRoot) {
+  const file = logFile(repoRoot);
   const lastLine = readLastLineAcrossSegments(file);
   if (!lastLine) return null;
   try { return JSON.parse(lastLine); }
   catch { return null; }
 }
 
-function readPrevLineHash() {
-  const file = logFile();
+function readPrevLineHash(repoRoot) {
+  const file = logFile(repoRoot);
   const lastLine = readLastLineAcrossSegments(file);
   return lastLine ? sha256(lastLine) : null;
 }
 
-function nextSequence() {
-  const tail = readTailRecord();
+function nextSequence(repoRoot) {
+  const tail = readTailRecord(repoRoot);
   const prior = Number.isInteger(tail?.sequence) ? tail.sequence : 0;
   return prior + 1;
 }
 
 /**
  * Append a violation record. Best-effort: file I/O failures are swallowed
- * so logging never crashes the caller.
+ * so logging never crashes the caller. `extra.repoRoot` (extracted, not
+ * persisted) routes the write to a fixture log when callers run against
+ * a tmpdir — required for test isolation.
  */
 export function logViolation(contractId, direction, missing, packet, extra = {}) {
   try {
-    const file = logFile();
+    const { repoRoot, ...persistedExtra } = extra || {};
+    const file = logFile(repoRoot);
     mkdirSync(dirname(file), { recursive: true });
     const record = {
       ts: new Date().toISOString(),
-      sequence: nextSequence(),
+      sequence: nextSequence(repoRoot),
       agent: readLastAgent(),
       contractId,
       direction,
       missing,
       packet_keys: packet && typeof packet === 'object' ? Object.keys(packet) : null,
-      prev_line_hash: readPrevLineHash(),
-      ...extra,
+      prev_line_hash: readPrevLineHash(repoRoot),
+      ...persistedExtra,
     };
     appendBounded('contract-violations', file, JSON.stringify(record) + '\n');
   } catch { /* logging is best-effort */ }

package/lib/hooks/stop-notify.mjs

@@ -26,6 +26,7 @@ import { listSessions, loadSession, updateSession } from '../session-store.mjs';
 import { captureSessionArtifacts } from '../artifact-capture.mjs';
 import { appendSessionStats } from '../memory-stats.mjs';
 import { estimateUsageCost } from '../telemetry/model-pricing-catalog.mjs';
+import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 
 function loadTranscriptCheckpoints(checkpointPath) {
   try {
@@ -140,6 +141,12 @@ let raw = '';
 try { raw = readFileSync(0, 'utf8'); } catch { /* non-critical */ }
 if (raw) process.stdout.write(raw);
 
+// PostToolUse Read hooks append delta lines instead of rewriting the full
+// read-tracker JSON on every call. Stop fires once per session end; this
+// is the canonical point to fold accumulated deltas back into the JSON.
+// Already wired into pre-compact + audit-reads; Stop is the third anchor.
+try { flushReadTrackerDeltas({ env: process.env }); } catch { /* non-critical */ }
+
 const home = homedir();
 const tsResultPath = join(home, '.cx', 'ts-result.txt');
 const warnFlagsPath = join(home, '.cx', 'warn-flags.txt');

package/lib/install/first-invocation.mjs

@@ -24,8 +24,12 @@ import { parseEnvFile, writeEnvValues, getUserEnvPath } from '../env-config.mjs'
 import { probeAll, formatProbe } from '../bootstrap/resources.mjs';
 
 const BOOTSTRAP_CHECKED_KEY = 'BOOTSTRAP_CHECKED';
+// 'install' is the actual handler name in bin/construct's dispatch map;
+// 'setup' is kept for backwards-compat in case anything still routes via
+// that key. Without 'install' the probe will re-prompt the user while
+// they're already running the very command meant to satisfy it.
 const SKIP_COMMANDS = new Set([
-  'hook', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor',
+  'hook', 'install', 'setup', 'uninstall', 'version', 'help', 'completions', 'doctor', 'upgrade', 'update',
 ]);
 
 export function shouldSkipProbe({ command, env = process.env, stdin = process.stdin } = {}) {

package/lib/intake/prepare.mjs

@@ -32,12 +32,13 @@ import path from 'node:path';
 import { buildHybridSearchResultsAsync } from '../storage/hybrid-query.mjs';
 import { suggestDocsLaneForFile } from '../docs-routing.mjs';
 import { createIntakeQueue } from './queue.mjs';
-import { classifyRdIntake } from './classify.mjs';
+import { classifyRdIntake, suggestTags } from './classify.mjs';
 import { detectCustomerMentions, linkSignalToCustomer, updateCustomerProfile } from '../embed/customer-profiles.mjs';
 import { resolveActiveProfile } from '../profiles/loader.mjs';
 import { emitBestEffort as emitRoleEvent } from '../roles/event-bus.mjs';
 import { gatherAttribution, stampAttribution } from './attribution.mjs';
 import { MANIFEST_REL_PATH } from './manifest.mjs';
+import { loadVocabulary } from '../tags/vocabulary.mjs';
 
 const DEFAULT_RELATED_LIMIT = 5;
 const EXCERPT_CHARS = 800;
@@ -66,12 +67,18 @@ export async function prepareIntakeForIngestedFile({
 
   let related = [];
   try {
-    const search = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
-    related = (search?.results || []).map((hit) => ({
-      path: hit.source_path || hit.id,
+    const raw = await hybridSearchFn(rootDir, query, { limit: relatedLimit, env });
+    // Test mocks return an array directly; production wrapper returns
+    // { results: [...] }. Accept both shapes so suggestTags sees the
+    // same `related` regardless of caller. Preserve `tags` for the
+    // related-inherit suggestion path.
+    const hits = Array.isArray(raw) ? raw : (raw?.results || []);
+    related = hits.map((hit) => ({
+      path: hit.source_path || hit.path || hit.id,
       title: hit.title || hit.id,
       score: hit.score,
       summary: hit.summary || '',
+      tags: Array.isArray(hit.tags) ? hit.tags : undefined,
     }));
   } catch (err) {
     related = [];
@@ -98,6 +105,16 @@ export async function prepareIntakeForIngestedFile({
 
   const droppedInfo = ingestedFile.droppedInfo ?? [];
 
+  // Tag auto-attribution: deterministic suggestions from triage + related
+  // doc inheritance, filtered against the project tag vocabulary. Vocab
+  // load failures fall through with empty suggestions — never block the
+  // packet write on a missing/malformed vocab file.
+
+  let vocab = null;
+  try { vocab = loadVocabulary(rootDir); }
+  catch { vocab = null; }
+  const tagSuggestions = suggestTags(triage, related, vocab);
+
   const baseEntry = {
     intake: {
       sourcePath: ingestedFile.sourcePath,
@@ -112,6 +129,7 @@ export async function prepareIntakeForIngestedFile({
     excerpt: extracted.slice(0, EXCERPT_CHARS),
     query,
     customers: customers.length ? customers : undefined,
+    tags: tagSuggestions.length > 0 ? tagSuggestions : undefined,
   };
 
   // Capability detection mirrors inbox.mjs: stamp provenance onto the packet

package/lib/integrations/intake-integrations.mjs

@@ -88,6 +88,22 @@ function resolveConfluenceAuth(homeDir) {
 
 // ── GitHub Issues ────────────────────────────────────────────────────────
 
+// A packet that originated from a demo/fixture/inbox-test source must not
+// be published to a real GitHub repo. The caller can override via
+// `publishDemo: true` when the demo run is intentional (e.g. an explicit
+// integration test that creates and then deletes the issue). Default-safe.
+
+export function isDemoIntakePacket(packet) {
+  if (process.env.CONSTRUCT_DEMO === '1') return true;
+  if (process.env.CONSTRUCT_INTAKE_DEMO === '1') return true;
+  const sourcePath = String(packet?.intake?.sourcePath || packet?.sourcePath || '');
+  if (!sourcePath) return false;
+  if (sourcePath.includes('/tests/fixtures/')) return true;
+  if (sourcePath.includes('/.cx/intake/demo/')) return true;
+  if (sourcePath.includes('/cx-intake-demo')) return true;
+  return false;
+}
+
 /**
  * Create a GitHub issue from an intake packet.
  *
@@ -98,9 +114,19 @@ function resolveConfluenceAuth(homeDir) {
  * @param {string} [opts.apiUrl] - GitHub API URL (default: api.github.com)
  * @param {string} [opts.host] - GitHub host (default: github.com)
  * @param {object} [opts.fetchImpl]
- * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string }>}
+ * @param {boolean} [opts.publishDemo] - Override the demo-source gate
+ * @returns {Promise<{ ok: boolean, externalUrl: string|null, externalId: string|null, error?: string, skipped?: string }>}
  */
-export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch } = {}) {
+export async function createGitHubIssue(packet, { repo, token, apiUrl, host, fetchImpl = globalThis.fetch, publishDemo = false } = {}) {
+  if (!publishDemo && isDemoIntakePacket(packet)) {
+    return {
+      ok: false,
+      externalUrl: null,
+      externalId: null,
+      skipped: 'demo-source',
+      error: 'Refused to publish: packet originated from a demo/fixture path (set CONSTRUCT_DEMO=0 and re-run with --publish-issues to override).',
+    };
+  }
   const hd = homedir();
   const auth = resolveGitHubAuth(hd);
   const resolvedRepo = repo || auth.repo || process.env.GITHUB_REPO;

package/lib/mcp/tools/telemetry.mjs

@@ -18,6 +18,7 @@ import { buildStatus } from '../../status.mjs';
 import { readEfficiencyLog, buildCompactEfficiencyDigest } from '../../efficiency.mjs';
 import { addObservation } from '../../observation-store.mjs';
 import { loadConstructEnv } from '../../env-config.mjs';
+import { createSqlClient, closeSqlClient } from '../../storage/backend.mjs';
 
 // Load config.env once at module init so config.env values win over shell env
 // (shell env may have stale/truncated credentials from earlier sessions)
@@ -243,6 +244,35 @@ export async function cxScore(args) {
       }
     }
 
+    // Postgres write-through (team/enterprise). Backs the
+    // construct_skill_quality_correlation view that `construct skills
+    // correlate-quality` reads — without this, the view stays empty and
+    // the CLI surface that promised correlation data delivered nothing.
+    // Best-effort: a missing DATABASE_URL or schema misalignment never
+    // blocks the score from reaching the remote telemetry or the local
+    // observation store above.
+
+    if (Number.isFinite(numericValue)) {
+      const sqlClient = createSqlClient(process.env);
+      if (sqlClient) {
+        try {
+          await sqlClient`
+            insert into construct_cx_scores (ts, trace_id, session_id, agent_id, name, value, comment)
+            values (
+              ${new Date().toISOString()},
+              ${traceId},
+              ${args.session_id ?? null},
+              ${args.agent_id ?? args.name ?? null},
+              ${args.name ?? 'quality'},
+              ${numericValue},
+              ${args.comment ?? null}
+            )
+          `;
+        } catch { /* best-effort write — never block on DB issues */ }
+        finally { await closeSqlClient(sqlClient).catch(() => {}); }
+      }
+    }
+
     return { ok: true, traceId, backend: client.backend, remoteStatus: client.remoteStatus };
   } catch (err) {
     return { ok: false, error: err.message };

package/lib/orchestration-policy.mjs

@@ -352,6 +352,21 @@ export function classifyRoleFlavors(request = '') {
   };
 }
 
+// One line per non-null flavor: "cx-<role>: loaded <role>.<flavor>
+// overlay". Verbose chat surface + cx_trace span attribute; lets a
+// post-hoc reviewer see which overlays drove a given dispatch.
+
+export function formatOverlaySelection(roleFlavors) {
+  if (!roleFlavors || typeof roleFlavors !== 'object') return [];
+  const lines = [];
+  for (const [role, flavor] of Object.entries(roleFlavors)) {
+    if (!flavor) continue;
+    const specialist = `cx-${role.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+    lines.push(`${specialist}: loaded ${role}.${flavor} overlay`);
+  }
+  return lines;
+}
+
 export function detectRiskFlags(request = '') {
   const text = String(request).toLowerCase();
   return {

package/lib/roles/gateway.mjs

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { emit, _paths } from './event-bus.mjs';
@@ -54,7 +54,36 @@ function appendPending(entry) {
   appendFileSync(pendingPath(), JSON.stringify(entry) + '\n');
 }
 
+// Paths under the OS tmpdir are by definition test fixtures or sandbox
+// runs, not real project state. Escalating from them spawns persistent
+// beads for ephemeral files — pure tracker noise. macOS resolves
+// $TMPDIR through a /private/var/folders/... symlink; the raw tmpdir
+// and its /private prefix are both checked so either resolved form
+// matches.
+
+export function isTestFixturePath(p) {
+  if (!p || typeof p !== 'string') return false;
+  const tmp = tmpdir();
+  if (p.startsWith(tmp)) return true;
+  if (p.startsWith('/private' + tmp)) return true;
+  if (p.startsWith('/tmp/')) return true;
+  // macOS canonical user-tmp prefix when $TMPDIR is set elsewhere
+  if (/^\/private\/var\/folders\/[^/]+\/[^/]+\/T\//.test(p)) return true;
+  if (/^\/var\/folders\/[^/]+\/[^/]+\/T\//.test(p)) return true;
+  return false;
+}
+
+function eventIsFromTestFixture(event) {
+  if (isTestFixturePath(event?.cwd)) return true;
+  if (isTestFixturePath(event?.project)) return true;
+  if (isTestFixturePath(event?.context?.filePath)) return true;
+  return false;
+}
+
 export function shouldEscalate(event, manifest, now = Date.now()) {
+  if (eventIsFromTestFixture(event)) {
+    return { escalate: false, reason: 'test-fixture-path' };
+  }
   const fp = event.fingerprint;
   const pending = readPending();
 

package/lib/scheduler/index.mjs

@@ -94,14 +94,34 @@ registerJob({
   handler: async () => ({ status: 'noop', reason: 'not yet implemented' }),
 });
 
+// Doc hygiene scan cadence is deployment-aware. Solo runs nightly because
+// a single contributor's doc drift accumulates slowly. Team and enterprise
+// runs hourly because many writers can shift the surface within a workday,
+// and the higher limit (50 vs 25) gives the reconcile worker enough headroom
+// to keep up. Mode/schedule resolved at module-load so a single registry
+// entry covers both topologies.
+
+const DOC_HYGIENE_SOLO_CRON = '0 2 * * *';
+const DOC_HYGIENE_TEAM_CRON = '0 * * * *';
+
+export function resolveDocHygieneSchedule(env = process.env) {
+  const mode = getDeploymentMode(env);
+  const isTeamish = mode === 'team' || mode === 'enterprise';
+  return {
+    mode: isTeamish ? 'team' : 'solo',
+    schedule: isTeamish ? DOC_HYGIENE_TEAM_CRON : DOC_HYGIENE_SOLO_CRON,
+    limit: isTeamish ? 50 : 25,
+  };
+}
+
+const docHygiene = resolveDocHygieneSchedule();
 registerJob({
   id: 'doc-hygiene-scan',
-  schedule: '0 2 * * *',
-  mode: 'solo',
+  schedule: docHygiene.schedule,
+  mode: docHygiene.mode,
   handler: async ({ cwd, env }) => {
     const { findHygieneCandidates } = await import('../hygiene/scan.mjs');
-    const mode = getDeploymentMode(env);
-    const limit = mode === 'solo' ? 25 : 50;
+    const { limit } = resolveDocHygieneSchedule(env);
     const candidates = findHygieneCandidates({ cwd, limit });
     return {
       status: 'ok',

package/lib/server/insights.mjs

@@ -14,6 +14,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { readCostLog, summarizeCostData } from '../cost.mjs';
+import { getRebrand } from '../profiles/rebrand.mjs';
 
 const TELEMETRY_TIMEOUT_MS = 3500;
 
@@ -309,12 +310,23 @@ function summarizeIntakeQueue(env, cwd = process.cwd()) {
       }
     } catch { /* skip */ }
 
+    // Profile-aware labels: the active profile's rebrand block (e.g.
+    // rnd → "Intake queue"/"signal"; sales-ops → "Lead inbox"/"lead")
+    // travels in the payload so the dashboard renders the right noun
+    // without hardcoding "intake" anywhere user-facing.
+
+    let rebrand;
+    try { rebrand = getRebrand(cwd); }
+    catch { rebrand = { intakeQueueLabel: 'Intake queue', signalNoun: 'signal' }; }
+
     return {
       state: pendingCount === 0 && processedCount === 0 && skippedCount === 0 ? 'empty' : 'ok',
       pending: pendingCount,
       processed: processedCount,
       skipped: skippedCount,
       customerLinked,
+      label: rebrand.intakeQueueLabel,
+      itemNoun: rebrand.signalNoun,
     };
   } catch (err) {
     return { state: 'unreachable', message: err.message };

package/lib/setup.mjs

@@ -1,10 +1,16 @@
 #!/usr/bin/env node
 /**
- * lib/setup.mjs — Interactive first-run setup wizard for Construct.
+ * lib/setup.mjs — Machine-scoped first-run setup wizard for Construct.
  *
- * Guides users through provider selection, API key entry, and model tier
- * assignment. Writes the resulting config to ~/.cx/env and optionally to
- * project-level .env. Invoked by `construct init` and on first init.
+ * Installs cm/cass, configures managed defaults, starts local Postgres
+ * (consent-driven), pre-warms the embedding model, wires MCP integrations,
+ * and writes ~/.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
+ * in lib/init-unified.mjs — invoked by `construct init`. These two flows
+ * are intentionally separate: install runs once per machine, init runs
+ * once per repo.
  */
 
 import fs from 'node:fs';
@@ -36,10 +42,10 @@ const LOCAL_POSTGRES_DB = 'construct';
 const LOCAL_DATABASE_URL = `postgresql://${LOCAL_POSTGRES_USER}:${LOCAL_POSTGRES_PASSWORD}@127.0.0.1:${LOCAL_POSTGRES_PORT}/${LOCAL_POSTGRES_DB}`;
 
 function printHelp() {
-  console.log(`Construct setup
+  console.log(`Construct install — machine setup (once per machine)
 
 Usage:
-  construct init [--yes] [--no-docker]
+  construct install [--yes] [--no-docker]
 
 What it does:
   - creates ~/.construct/config.env
@@ -52,6 +58,7 @@ What it does:
   - runs construct doctor
   - detects the project tech stack and writes .cx/project-profile.json
 
+For project setup (once per repo): construct init
 Use --yes to run without prompts and accept detected environment defaults.`);
 }
 
@@ -465,6 +472,35 @@ export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   };
 }
 
+// $HOME/.construct/lib/hooks/* is the resolution path for Claude Code
+// Stop-hook commands. Absent symlink → every Stop hook fails silently,
+// including stop-notify (dashboard cost feed). Idempotent: matching
+// symlink left alone, stale symlink replaced, real dir refused.
+
+export function ensureLibSymlink({ homeDir = HOME, rootDir = ROOT_DIR } = {}) {
+  const target = path.join(homeDir, '.construct', 'lib');
+  const source = path.join(rootDir, 'lib');
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  let stat = null;
+  try { stat = fs.lstatSync(target); } catch { stat = null; }
+  if (!stat) {
+    fs.symlinkSync(source, target, 'dir');
+    return { status: 'created', target, source };
+  }
+  if (stat.isSymbolicLink()) {
+    const current = fs.readlinkSync(target);
+    if (current === source) return { status: 'kept', target, source };
+    fs.unlinkSync(target);
+    fs.symlinkSync(source, target, 'dir');
+    return { status: 'replaced', target, source, previous: current };
+  }
+  return {
+    status: 'conflict',
+    target,
+    message: `${target} exists and is not a symlink — leaving alone. Move or remove it, then re-run \`construct install\` to wire the hooks.`,
+  };
+}
+
 export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME } = {}) {
   const argSet = new Set(args);
   const isYes = argSet.has('--yes');
@@ -480,9 +516,17 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
 
   const envPath = ensureUserConfig(homeDir);
   const opencodePath = ensureOpenCodeConfig();
+  const libLink = ensureLibSymlink({ homeDir, rootDir });
 
   console.log(`User config: ${envPath}`);
   console.log(`OpenCode config: ${opencodePath}`);
+  if (libLink.status === 'created' || libLink.status === 'replaced') {
+    console.log(`Hook lib link: ${libLink.target} → ${libLink.source} (${libLink.status})`);
+  } else if (libLink.status === 'kept') {
+    console.log(`Hook lib link: ${libLink.target} already in place`);
+  } else if (libLink.status === 'conflict') {
+    console.log(`Hook lib link: ${libLink.message}`);
+  }
   warnIfGlobalCommandIsUnavailable();
 
   const cmInstall = ensureCmInstalled({ env: process.env });
@@ -582,6 +626,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     });
     if (cheapestConsent.decision) {
       try {
+        const { applyToEnv } = await import('./model-router.mjs');
         const selections = await selectCheapestForAllTiers({ env: process.env });
         const applied = {};
         for (const tier of ['reasoning', 'standard', 'fast']) {
@@ -637,7 +682,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
 
   if (isYes) {
     console.log('\nManaged setup:');
-    console.log(`  Deployment mode: ${getDeploymentMode(env) || DEFAULT_DEPLOYMENT_MODE} (set in construct.config.json — runtime env override available via ${DEPLOYMENT_MODE_ENV_KEY})`);
+    console.log(`  Deployment mode: ${getDeploymentMode(process.env) || DEFAULT_DEPLOYMENT_MODE} (set in construct.config.json — runtime env override available via ${DEPLOYMENT_MODE_ENV_KEY})`);
     console.log(`  Vector index: ${managedValues.CONSTRUCT_VECTOR_INDEX_PATH}`);
     console.log(`  Vector model: ${managedValues.CONSTRUCT_VECTOR_MODEL}`);
     console.log(`  Trace backend: ${managedValues.CONSTRUCT_TRACE_BACKEND}`);
@@ -723,12 +768,12 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     runConstruct(['mcp', 'add', 'github', '--auto'], { optional: true });
   } else {
     console.log('\nManaged defaults written:');
-    console.log(`  Deployment mode: ${getDeploymentMode(env) || DEFAULT_DEPLOYMENT_MODE} (set in construct.config.json — runtime env override available via ${DEPLOYMENT_MODE_ENV_KEY})`);
+    console.log(`  Deployment mode: ${getDeploymentMode(process.env) || DEFAULT_DEPLOYMENT_MODE} (set in construct.config.json — runtime env override available via ${DEPLOYMENT_MODE_ENV_KEY})`);
     console.log(`  Vector index: ${managedValues.CONSTRUCT_VECTOR_INDEX_PATH}`);
     console.log(`  Trace backend: ${managedValues.CONSTRUCT_TRACE_BACKEND}${managedValues.CONSTRUCT_TELEMETRY_URL ? ` (${managedValues.CONSTRUCT_TELEMETRY_URL})` : ''}`);
     console.log(`  Pressure guard: swap ${managedValues.CONSTRUCT_PRESSURE_GUARD_SWAP_GB} GiB, opencode max ${managedValues.CONSTRUCT_PRESSURE_GUARD_MAX_OPENCODE}`);
     console.log('\nFor unattended setup, including local Postgres when Docker is running:');
-    console.log('  construct init --yes');
+    console.log('  construct install --yes');
   }
 
   runConstruct(['sync']);

package/lib/update.mjs

@@ -10,6 +10,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+import { writeVersionStamp } from './maintenance/cleanup.mjs';
+
 const PACKAGE_NAME = '@geraldmaron/construct';
 
 function readPackageJson(dir) {
@@ -70,6 +72,15 @@ export function buildUpdatePlan({ cwd }) {
         args: [binPath, 'sync', '--no-docs'],
         cwd: sourceRoot,
       },
+      // Sweep legacy cx-*.md/.toml/.prompt.md left over from older releases
+      // at user scope, so the next doctor doesn't surface the warning.
+      {
+        label: 'Sweep legacy agents at user scope',
+        command: process.execPath,
+        args: [binPath, 'doctor', '--fix-legacy-agents'],
+        cwd: sourceRoot,
+        optional: true,
+      },
       {
         label: 'Run health checks',
         command: process.execPath,
@@ -84,14 +95,24 @@ function formatCommand(command, args) {
   return [command, ...args].join(' ');
 }
 
-function runStep(step, { spawn, env }) {
+function runStep(step, { spawn, env, stdout }) {
   const result = spawn(step.command, step.args, {
     cwd: step.cwd,
     env,
     stdio: 'inherit',
   });
-  if (result?.error) throw result.error;
+  if (result?.error) {
+    if (step.optional) {
+      stdout?.write?.(`  (skipped: ${result.error.message})\n`);
+      return;
+    }
+    throw result.error;
+  }
   if ((result?.status ?? 1) !== 0) {
+    if (step.optional) {
+      stdout?.write?.(`  (skipped: exit ${result?.status ?? 1})\n`);
+      return;
+    }
     throw new Error(`${step.label} failed with exit code ${result.status ?? 1}`);
   }
 }
@@ -107,9 +128,16 @@ export function runUpdate({ cwd, env = process.env, spawn = spawnSync, stdout =
   for (const step of plan.steps) {
     stdout.write(`→ ${step.label}\n`);
     stdout.write(`  ${formatCommand(step.command, step.args)}\n`);
-    runStep(step, { spawn, env });
+    runStep(step, { spawn, env, stdout });
   }
 
+  // Advance the cleanup stamp to the checkout version so the next CLI
+  // invocation doesn't run a full cleanup pass on the assumption that
+  // an upgrade just happened.
+  try {
+    writeVersionStamp({ version: plan.version, summary: { freedBytes: 0, durationMs: 0 } });
+  } catch { /* stamp write is best-effort */ }
+
   stdout.write('\n✓ Construct updated from current checkout.\n');
   return plan;
 }