@geraldmaron/construct 1.0.15 → 1.0.17

package/lib/service-manager.mjs

@@ -442,9 +442,22 @@ async function tryStartDockerDaemon({
   return false;
 }
 
+// The optional services a user can pick from with `construct dev --select` /
+// `--only=`. Pressure Guard (cleanup) and Doctor (the L0 supervisor daemon)
+// are infrastructure, always on — they are intentionally not selectable.
+
+export const SELECTABLE_SERVICES = Object.freeze([
+  { key: 'postgres', label: 'Postgres', description: 'Managed pgvector container (or external DATABASE_URL).' },
+  { key: 'dashboard', label: 'Dashboard', description: 'Local operations dashboard on http://127.0.0.1:4242.' },
+  { key: 'telemetry', label: 'Telemetry', description: 'Trace export / local JSONL traces.' },
+  { key: 'memory', label: 'Memory (cm)', description: 'Persistent memory service (cm).' },
+  { key: 'opencode', label: 'OpenCode', description: 'OpenCode bridge server.' },
+]);
+
 export async function startServices({
   rootDir,
   homeDir = os.homedir(),
+  selected = null,
   describeRuntimeSupportFn = describeRuntimeSupport,
   getRuntimePortsFn = getRuntimePorts,
   startDashboardFn = startDashboard,
@@ -461,6 +474,11 @@ export async function startServices({
   const ports = await getRuntimePortsFn(homeDir);
   const envPath = getUserEnvPath(homeDir);
 
+  // A null selection means "start everything" (the default). A Set restricts
+  // startup to the chosen optional services; always-on infrastructure ignores it.
+
+  const wants = (key) => selected === null || selected.has(key);
+
   // On macOS, auto-launch Docker Desktop when the CLI is present but the
   // daemon is down. Polls up to 60s so downstream Postgres startup sees a working
   // compose runner instead of "Docker not available".
@@ -487,7 +505,7 @@ export async function startServices({
   const databaseUrl = liveEnv.DATABASE_URL || '';
   const usesManagedPostgres = isManagedConstructPostgresUrl(databaseUrl);
 
-  if (usesManagedPostgres) {
+  if (wants('postgres') && usesManagedPostgres) {
     if (!isConstructPostgresRunning()) {
       const pgStart = startConstructPostgres({ rootDir, homeDir, spawnSyncFn: spawnSync, detectDockerComposeFn: detectDockerComposeFn });
       if (pgStart.status === 'started') {
@@ -515,20 +533,23 @@ export async function startServices({
         note: pgvector ? 'pgvector enabled' : 'pgvector not installed',
       });
     }
-  } else if (databaseUrl) {
+  } else if (wants('postgres') && databaseUrl) {
     results.push({ name: 'Postgres', url: databaseUrl, status: 'configured', note: 'external database' });
   }
 
   // Dashboard
-  const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
-  results.push({
-    name: 'Dashboard',
-    url: dashboard.url,
-    status: dashboard.reused ? 'reused' : 'started',
-  });
+  if (wants('dashboard')) {
+    const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
+    results.push({
+      name: 'Dashboard',
+      url: dashboard.url,
+      status: dashboard.reused ? 'reused' : 'started',
+    });
+  }
 
   const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
   const traceBackend = resolveTraceBackend(liveEnv);
+  if (wants('telemetry')) {
   if (traceBackend === 'local') {
     results.push({
       name: 'Telemetry',
@@ -561,21 +582,22 @@ export async function startServices({
   } else {
     results.push({ name: 'Telemetry', status: 'unavailable', note: 'remote export requested but endpoint is not configured' });
   }
+  }
 
   // Memory (cm)
-  if (support.cm) {
+  if (wants('memory') && support.cm) {
     if (await memoryProbeFn(ports.memory)) {
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
     } else {
       spawnDetachedFn('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log');
       results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
     }
-  } else {
+  } else if (wants('memory')) {
     results.push({ name: 'Memory (cm)', status: 'unavailable', note: 'cm not installed — run: construct init or brew install dicklesworthstone/tap/cm' });
   }
 
   // OpenCode (optional)
-  if (support.opencode) {
+  if (wants('opencode') && support.opencode) {
     if (await openCodeProbeFn(ports.bridge)) {
       results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
     } else {

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,15 @@ 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] [--reconfigure]
+
+Flags:
+  --yes          accept detected defaults without prompting
+  --no-docker    skip local Postgres / Docker service setup
+  --reconfigure  re-prompt for service consent, ignoring cached answers
 
 What it does:
   - creates ~/.construct/config.env
@@ -52,7 +63,7 @@ What it does:
   - runs construct doctor
   - detects the project tech stack and writes .cx/project-profile.json
 
-Use --yes to run without prompts and accept detected environment defaults.`);
+For project setup (once per repo): construct init`);
 }
 
 function runConstruct(argsList, { optional = false } = {}) {
@@ -465,24 +476,73 @@ 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');
   const skipDocker = argSet.has('--no-docker');
+  const reconfigure = argSet.has('--reconfigure');
 
   if (argSet.has('--help') || argSet.has('-h')) {
     printHelp();
     return;
   }
 
+  // Reject unknown flags loudly so a typo (e.g. --reconfig) fails fast with the
+  // help text instead of silently running defaults.
+
+  const KNOWN_FLAGS = new Set(['--yes', '--no-docker', '--reconfigure', '--help', '-h']);
+  const unknownFlags = args.filter((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
+  if (unknownFlags.length) {
+    console.error(`Unknown flag(s): ${unknownFlags.join(', ')}`);
+    printHelp();
+    throw new Error(`Unknown setup flag(s): ${unknownFlags.join(', ')}`);
+  }
+
   console.log('Construct setup');
   console.log('────────────────');
 
   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 });
@@ -521,6 +581,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     const pgConsent = await consentToInstall({
       name: 'postgres',
       isYes,
+      force: reconfigure,
       alreadyConfigured: Boolean(process.env.DATABASE_URL),
       alreadyConfiguredNote: 'DATABASE_URL already set — using external database.',
       envPath,
@@ -576,12 +637,14 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
     const cheapestConsent = await consentToInstall({
       name: 'cheapest-provider',
       isYes,
+      force: reconfigure,
       alreadyConfigured: false,
       envPath,
       defaultYes: false,
     });
     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 +700,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 +786,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;
 }

package/lib/upgrade.mjs

@@ -10,6 +10,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
+import { writeVersionStamp } from './maintenance/cleanup.mjs';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..');
 const PACKAGE_NAME = '@geraldmaron/construct';
@@ -97,7 +99,7 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
   }
   
   stdout.write('Upgrading...\n\n');
-  
+
   const steps = [
     {
       label: 'Fetching latest from npm',
@@ -109,6 +111,15 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       command: 'construct',
       args: ['sync', '--no-docs'],
     },
+    // Sweep legacy cx-*.md/.toml/.prompt.md left behind by older releases at
+    // user scope. Without this the user gets a doctor warning every session
+    // until they manually run `construct doctor --fix-legacy-agents`.
+    {
+      label: 'Sweeping legacy agents at user scope',
+      command: 'construct',
+      args: ['doctor', '--fix-legacy-agents'],
+      optional: true,
+    },
     {
       label: 'Running health checks',
       command: 'construct',
@@ -123,18 +134,34 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       env,
       stdio: 'inherit',
     });
-    
+
     if (result.error) {
+      if (step.optional) {
+        stdout.write(`  (skipped: ${result.error.message})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed: ${result.error.message}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
-    
+
     if (result.status !== 0) {
+      if (step.optional) {
+        stdout.write(`  (skipped: exit ${result.status})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed with exit code ${result.status}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
   }
-  
+
+  // Advance the cleanup stamp so the next CLI invocation doesn't re-run a
+  // full cleanup pass under the assumption that the user just upgraded.
+  // Without this, every command pays the cleanup cost until something
+  // else writes the stamp.
+  try {
+    writeVersionStamp({ version: latestVersion, summary: { freedBytes: 0, durationMs: 0 } });
+  } catch { /* stamp write is best-effort */ }
+
   stdout.write('\n');
   stdout.write(`✓ Upgraded to ${latestVersion}\n`);
   return { success: true, upgraded: true, from: currentVersion, to: latestVersion };

package/lib/validators/skills.mjs

@@ -6,6 +6,8 @@
  *   ---
  *   name: <kebab-case>
  *   description: "<≤1024 chars, includes a 'use when' trigger>"
+ *   [inputs: [<string>, …]  — optional, surfaced by capability discovery]
+ *   [artifactType: <string> — optional, surfaced by capability discovery]
  *   [role/applies_to/inherits/version/profiles/cap for role files]
  *   ---
  *   # <Title>
@@ -100,6 +102,23 @@ function validateDescription(description) {
   return null;
 }
 
+// Optional embedded-contract metadata: surfaced by capability discovery when
+// present. Validated only when present so the field stays opt-in and is
+// populated incrementally — inputs is a list of strings, artifactType a string.
+
+function validateOptionalMetadata(frontmatter) {
+  const issues = [];
+  if ('inputs' in frontmatter && frontmatter.inputs !== null) {
+    if (!Array.isArray(frontmatter.inputs) || frontmatter.inputs.some((i) => typeof i !== 'string')) {
+      issues.push('frontmatter.inputs must be a list of strings when present');
+    }
+  }
+  if ('artifactType' in frontmatter && frontmatter.artifactType !== null && typeof frontmatter.artifactType !== 'string') {
+    issues.push('frontmatter.artifactType must be a string when present');
+  }
+  return issues;
+}
+
 export function validateSkills(roots) {
   const dirs = Array.isArray(roots) ? roots : [roots];
   const errors = [];
@@ -150,6 +169,8 @@ export function validateSkills(roots) {
       const descErr = validateDescription(frontmatter.description);
       if (descErr) errors.push(`${rel}: ${descErr}`);
 
+      for (const issue of validateOptionalMetadata(frontmatter)) errors.push(`${rel}: ${issue}`);
+
       const { title, opener } = extractTitleAndOpener(body);
 
       if (!title) {

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
     "construct": "bin/construct"
   },
+  "exports": {
+    ".": "./lib/embedded-contract/index.mjs",
+    "./embedded-contract": "./lib/embedded-contract/index.mjs",
+    "./lib/*": "./lib/*",
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/construct",
     "bin/construct-postinstall.mjs",
@@ -78,8 +84,8 @@
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/core": "^1.25.0",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
+    "@opentelemetry/core": "^2.7.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
     "@opentelemetry/resources": "^1.25.0",
     "@opentelemetry/sdk-trace-node": "^1.25.0",
     "@opentelemetry/semantic-conventions": "^1.25.0"

package/personas/construct.md

@@ -34,6 +34,8 @@ Execution model:
 
 Devil's advocate is mandatory for new architectural directions, AI/agent workflow changes, security or data-integrity changes, and promoting a temporary capability to persistent.
 
+Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
+
 ## Gates and contracts (org-in-a-box)
 
 `routeRequest` returns three artifacts; honor all three:

package/platforms/claude/CLAUDE.md

@@ -1,30 +1,58 @@
 # Construct: Claude Code Integration
 
-This project uses Construct. Personas and specialists are defined in `specialists/registry.json` and synced to Claude Code via `construct sync`.
+This file ships as a reference template alongside the Construct npm package. The canonical project-instructions file is `/CLAUDE.md` at your repo root — that's the file Claude Code actually reads at session start. The structure here mirrors that canonical file so users know what shape their own `/CLAUDE.md` should take after `construct init` scaffolds a project.
+
+Personas and specialists are defined in `specialists/registry.json` and rendered into Claude Code agents on every `construct sync`. The single user-facing persona is `construct`; the 28 specialists (cx-engineer, cx-security, cx-devil-advocate, …) are routed internally — you address Construct, Construct dispatches.
+
+## Critical rules (mirror in your project /CLAUDE.md)
+
+- **Never fabricate.** Every load-bearing claim cites a verifiable source. When a fact isn't in the source, write `unknown` or `[unverified]`. See `rules/common/no-fabrication.md`.
+- **Confirm the working branch every session.** Session-start surfaces `## Working branch: <name>` at the top of the injected context.
+- **Never commit, push, or merge without asking first.** State the branch, state the action, wait for explicit yes.
+- **Never edit running hook files** without testing them in isolation. A broken hook blocks all tool use.
+- **Hooks fire unconditionally. No skip env vars on quality gates.** If a check fires wrong, repair the check — do not re-introduce `CONSTRUCT_SKIP_*` / `CONSTRUCT_ALLOW_*`.
+- **Never commit directly to main.** Branch, test, then merge.
+- **Run `construct doctor`** after structural changes.
 
 ## Workflow roles
 
-Construct is the only intended user-facing surface.
+| Role | What it covers |
+|---|---|
+| **Planning** | Requirements, strategy, architecture, framing challenges |
+| **Implementation** | Builds features and fixes bugs |
+| **Validation** | Quality gates, code review, security, accessibility |
+| **Research** | Docs, debugging, codebase exploration, external research |
+| **Operations** | Releases, dev servers, health checks, observability |
+
+Construct routes complex work through the full pipeline (plan → implement → validate → operate). For simple tasks, Construct acts directly without exposing the internal routing.
+
+## Beads issue tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` for the full workflow context.
 
-- **Planning**: requirements, strategy, architecture
-- **Implementation**: builds features and fixes bugs
-- **Validation**: quality gates, security, accessibility
-- **Research**: docs, debugging, codebase exploration
-- **Operations**: releases, dev servers, health checks
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
 
-## Usage
+Use `bd` for all task tracking. Do NOT use TodoWrite, TaskCreate, or markdown TODO lists.
 
-Talk to Construct normally. It routes complex work through the full pipeline internally:
-plan → implement → validate → operate
+## Session completion
 
-For simple tasks, Construct can act directly without exposing internal routing.
+When ending a work session, **work is not complete until `git push` succeeds.**
 
-All 26 internal specialists (cx-engineer, cx-security, cx-devil-advocate, etc.) are available as subagents.
+```bash
+git pull --rebase
+git push
+git status  # MUST show "up to date with origin"
+```
 
-## Tool Calls
+## Tool calls
 
 When using Bash, always provide both `command` and `description` string fields. Do not emit XML-style fallback tool calls.
 
-## Cross-Tool Memory
+## Cross-tool memory
 
-Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then use `memory_search` to find prior context.
+Construct uses cass-memory for cross-tool memory. Start the local HTTP server with `cm serve`, then `memory_search` to find prior context. Memory and beads are complementary: memory holds knowledge, beads hold tasks.

package/scripts/sync-specialists.mjs

@@ -172,8 +172,17 @@ function detectConstructProject(cwd) {
 
 const detectedProject = (!PROJECT_FLAG && !GLOBAL_FLAG) ? detectConstructProject(process.cwd()) : null;
 const projectDir = PROJECT_FLAG ? process.cwd() : detectedProject;
-const lockPath = path.join(projectDir || root, ".cx", "sync.lock");
-const stagingDir = path.join(projectDir || root, ".cx", "sync-staging");
+
+// Lock and staging are scoped to the tier we actually mutate: a project dir for
+// project-tier writes, the user's HOME for global-tier writes (which land in
+// ~/.claude, ~/.codex, …). Keying the global tier to HOME — not the repo root —
+// means two --global syncs against different HOMEs (e.g. parallel test files in
+// isolated sandboxes) never collide on a shared repo-root lock, and staging
+// renames stay on the same filesystem as their destinations.
+
+const stateBase = projectDir || home;
+const lockPath = path.join(stateBase, ".cx", "sync.lock");
+const stagingDir = path.join(stateBase, ".cx", "sync-staging");
 
 // Project-tier writes carry every registry entry. Global-tier writes carry only
 // the `construct` front-door agent — specialists live with the project, not the
@@ -243,7 +252,7 @@ function writeFile(file, content, { stamp = true } = {}) {
   }
 
   // Two-phase: write to staging, commit later.
-  const rel = path.relative(projectDir || root, file);
+  const rel = path.relative(stateBase, file);
   const stagingPath = path.join(stagingDir, rel);
   mkdirp(path.dirname(stagingPath));
   fs.writeFileSync(stagingPath, stamped);
@@ -950,7 +959,16 @@ function getVSCodeSettingsPaths() {
       path.join(appData, "Code - Insiders", "User", "settings.json"),
     );
   }
-  return candidates.filter(fs.existsSync);
+  // settings.json present → ready to merge. settings.json absent but the
+  // VS Code User dir exists → installed without ever opening Preferences,
+  // and global sync still needs to write the MCP block. The User dir is
+  // the installation signal; bootstrap a minimal settings.json there.
+
+  return candidates.filter((candidate) => {
+    if (fs.existsSync(candidate)) return true;
+    const userDir = path.dirname(candidate);
+    return fs.existsSync(userDir);
+  });
 }
 
 function syncVSCode(targetDir = null) {
@@ -991,7 +1009,16 @@ function syncVSCode(targetDir = null) {
   let synced = false;
   for (const settingsPath of settingsPaths) {
     try {
-      const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      let settings;
+      if (fs.existsSync(settingsPath)) {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+      } else {
+        // VS Code installed (User dir present) but never opened → seed an
+        // empty settings.json. Single object literal, no other keys, so
+        // a later launch of VS Code finds it valid and writes user prefs
+        // alongside.
+        settings = {};
+      }
       if (!settings["github.copilot.mcpServers"]) settings["github.copilot.mcpServers"] = {};
       const mcpServers = settings["github.copilot.mcpServers"];
       for (const [id, mcpDef] of Object.entries(registryMcp)) {

package/skills/ai/agent-dev.md

@@ -1,6 +1,8 @@
 ---
 name: ai-agent-dev
 description: Use this skill when building AI agents, tool-use systems, or multi-agent workflows.
+inputs: [agent-spec, task-context]
+artifactType: agent-implementation
 ---
 # AI Agent Development
 

package/skills/ai/llm-security.md

@@ -1,6 +1,8 @@
 ---
 name: ai-llm-security
 description: Use this skill when securing LLM-powered applications against prompt injection, data leakage, and misuse.
+inputs: [prompt, model-output, agent-spec]
+artifactType: guidance
 ---
 # LLM Security
 

package/skills/ai/ml-ops.md

@@ -1,6 +1,8 @@
 ---
 name: ai-ml-ops
 description: Patterns, anti-patterns, and reference guidance for ML Operations (MLOps). Use when the task involves ml operations (mlops).
+inputs: [eval-dataset, model-output]
+artifactType: guidance
 ---
 # ML Operations (MLOps)