@geraldmaron/construct 1.0.5 → 1.0.7

package/commands/work/optimize-prompts.md

@@ -1,10 +1,10 @@
 <!--
-commands/work/optimize-prompts.md — Prompt optimization command.
+commands/work/optimize-prompts.md: Prompt optimization command.
 
 Runs the closed-loop prompt optimization workflow using telemetry trace data.
 -->
 ---
-description: Closed-loop prompt optimization — read telemetry traces, diagnose failures, push improved version to staging
+description: "Closed-loop prompt optimization: read telemetry traces, diagnose failures, push improved version to staging"
 ---
 
 You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
@@ -18,13 +18,13 @@ Optimize prompt fragments and overlays, not the runtime orchestration policy. If
 
 ## Required steps
 
-1. **Read current prompt** — read the agent's prompt from `agents/registry.json` (or its `promptFile`)
-2. **Fetch recent scores** — GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
-3. **Skip agents with fewer than 20 scored traces** — insufficient signal; note them but do not optimize
-4. **Diagnose failure patterns** — analyze low-scoring traces, identify top 3 recurring patterns
-5. **Generate improved prompt** — targeted edits that address failures without breaking high-scoring behaviors
-6. **Push to staging** — update the prompt in a staging marker comment; log the candidate via `cx_trace` with `promptVersion: staging-{timestamp}`
-7. **Report** — for each agent: before/after median score estimate, patterns addressed, staging version note
+1. **Read current prompt**: read the agent's prompt from `agents/registry.json` (or its `promptFile`)
+2. **Fetch recent scores**: GET `{CONSTRUCT_TELEMETRY_URL}/api/public/scores?name=quality&limit=200`
+3. **Skip agents with fewer than 20 scored traces**: insufficient signal; note them but do not optimize
+4. **Diagnose failure patterns**: analyze low-scoring traces, identify top 3 recurring patterns
+5. **Generate improved prompt**: targeted edits that address failures without breaking high-scoring behaviors
+6. **Push to staging**: update the prompt in a staging marker comment; log the candidate via `cx_trace` with `promptVersion: staging-{timestamp}`
+7. **Report**: for each agent: before/after median score estimate, patterns addressed, staging version note
 
 ## Output
 

package/commands/work/parallel-review.md

@@ -1,21 +1,21 @@
 <!--
-commands/work/parallel-review.md — Adversarial parallel review — 5 reviewers must agree before output ships
+commands/work/parallel-review.md (Adversarial parallel review) 5 reviewers must agree before output ships
 
-Adversarial parallel review — 5 reviewers must agree before output ships
+Adversarial parallel review: 5 reviewers must agree before output ships
 -->
 ---
-description: Adversarial parallel review — 5 reviewers must agree before output ships
+description: "Adversarial parallel review: 5 reviewers must agree before output ships"
 ---
 
 You are Construct running a parallel adversarial review of: $ARGUMENTS
 
 Dispatch the following 5 review roles concurrently:
 
-1. **cx-reviewer** — Correctness and logic: does it do what it claims? Are there off-by-ones, edge cases, or control flow bugs?
-2. **cx-security** — Vulnerabilities and data exposure: injection, auth bypass, secret leakage, SSRF, unvalidated input
-3. **cx-qa** — Test coverage and edge cases: what's untested? What inputs would break this?
-4. **cx-devil-advocate** — Assumption stress-test: what are we assuming that could be wrong? What failure modes are unaddressed?
-5. **cx-accessibility** (UI changes) or **cx-trace-reviewer** (non-UI) — Inclusive UX or performance bottlenecks
+1. **cx-reviewer**: Correctness and logic: does it do what it claims? Are there off-by-ones, edge cases, or control flow bugs?
+2. **cx-security**: Vulnerabilities and data exposure: injection, auth bypass, secret leakage, SSRF, unvalidated input
+3. **cx-qa**: Test coverage and edge cases: what's untested? What inputs would break this?
+4. **cx-devil-advocate**: Assumption stress-test: what are we assuming that could be wrong? What failure modes are unaddressed?
+5. **cx-accessibility** (UI changes) or **cx-trace-reviewer** (non-UI): Inclusive UX or performance bottlenecks
 
 ## Merge Gate
 

package/db/schema/006_graph.sql

@@ -0,0 +1,24 @@
+-- 006_graph.sql. GraphRAG community columns for entities.
+--
+-- Phase C9 foundations. Adds community_id (label propagation output) and a
+-- community summary table so the Pg-backed deployment can query communities
+-- without a JSONL scan. Solo-mode JSONL remains the source of truth; this
+-- table is the projection.
+
+ALTER TABLE construct_entities
+  ADD COLUMN IF NOT EXISTS community_id text,
+  ADD COLUMN IF NOT EXISTS community_size int;
+
+CREATE INDEX IF NOT EXISTS idx_entities_community ON construct_entities(project, community_id);
+
+CREATE TABLE IF NOT EXISTS construct_entity_communities (
+  community_id text NOT NULL,
+  project text NOT NULL,
+  size int NOT NULL DEFAULT 0,
+  top_members jsonb DEFAULT '[]'::jsonb,
+  summary text,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (project, community_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_communities_size ON construct_entity_communities(project, size DESC);

package/examples/provider-plugin/README.md

@@ -1,4 +1,4 @@
-# Hello World — Construct provider plugin example
+# Hello World: Construct provider plugin example
 
 A minimal reference implementation of the [Construct provider contract](../../docs/providers/authoring.md). Returns canned data; no external credentials required.
 
@@ -18,16 +18,16 @@ construct provider test hello-world --query "greet"
 ## What this shows
 
 - The factory function signature (`create({ env })`)
-- `meta` — id, displayName, capabilities
-- `configSchema` — JSON Schema for provider settings
-- `health()` — always-healthy health check
-- `read()` — look up a single item by id
-- `search()` — full-text filter over canned items
+- `meta`: id, displayName, capabilities
+- `configSchema`: JSON Schema for provider settings
+- `health()`: always-healthy health check
+- `read()`: look up a single item by id
+- `search()`: full-text filter over canned items
 
 ## Adapting for real providers
 
 1. Replace the `ITEMS` constant with real API calls.
-2. Add auth logic in `create()` — read tokens from `env` or `config`.
+2. Add auth logic in `create()`: read tokens from `env` or `config`.
 3. Add `watch()` and/or `webhook()` if your source supports push.
 4. Publish as an npm package and register via `construct provider plugins add <package>`.
 

package/examples/seed-observations/README.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/README.md — seed corpus for Construct's in-tree memory layer.
+examples/seed-observations/README.md: seed corpus for Construct's in-tree memory layer.
 
 Run `construct bootstrap` to import these files into the local observation and entity stores.
 The seed corpus gives the hybrid BM25 + cosine retrieval a meaningful starting signal
@@ -25,14 +25,14 @@ This corpus seeds the Construct memory layer with high-value starting knowledge.
 construct bootstrap
 ```
 
-Imports all three files into the local observation store. Safe to re-run — duplicate
+Imports all three files into the local observation store. Safe to re-run: duplicate
 observations are deduplicated by content hash.
 
 ## Payoff Timeline
 
-- **0 sessions** — retrieval is cold; seed corpus provides baseline recall
-- **5 sessions** — personal patterns start surfacing; seed corpus still dominant
-- **20 sessions** — personal patterns dominate; seed corpus recedes to backstop
-- **50+ sessions** — retrieval is fully personalized; seed corpus rarely surfaces
+- **0 sessions**: retrieval is cold; seed corpus provides baseline recall
+- **5 sessions**: personal patterns start surfacing; seed corpus still dominant
+- **20 sessions**: personal patterns dominate; seed corpus recedes to backstop
+- **50+ sessions**: retrieval is fully personalized; seed corpus rarely surfaces
 
 Run `construct memory stats` to see whether memory is paying off.

package/examples/seed-observations/anti-patterns.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/anti-patterns.md — recurring mistakes for Construct memory seed corpus.
+examples/seed-observations/anti-patterns.md: recurring mistakes for Construct memory seed corpus.
 
 Each entry becomes one observation in the store with category "anti-pattern". Imported via
 `construct bootstrap`.
@@ -9,36 +9,36 @@ Each entry becomes one observation in the store with category "anti-pattern". Im
 
 ## Context Waste
 
-**Reading the whole file to find one function** — Use Grep to locate the line number, then Read with offset/limit to read only that section. Reading a 500-line file to find a 10-line function burns ~5k tokens.
+**Reading the whole file to find one function**: Use Grep to locate the line number, then Read with offset/limit to read only that section. Reading a 500-line file to find a 10-line function burns ~5k tokens.
 
-**Re-reading already-loaded files** — If the file content is already in context, reading it again is pure waste. Check context before issuing another Read.
+**Re-reading already-loaded files**: If the file content is already in context, reading it again is pure waste. Check context before issuing another Read.
 
-**Sequential tool calls that could be parallel** — Issuing Glob, then Read, then Grep one at a time when they're independent triples the latency. Batch independent calls in one message.
+**Sequential tool calls that could be parallel**: Issuing Glob, then Read, then Grep one at a time when they're independent triples the latency. Batch independent calls in one message.
 
 ## Code Authoring
 
-**Guessing a function signature** — Never guess an API or function signature. Read the source or check the docs first. Wrong signatures produce runtime errors that cost a full round-trip to fix.
+**Guessing a function signature**: Never guess an API or function signature. Read the source or check the docs first. Wrong signatures produce runtime errors that cost a full round-trip to fix.
 
-**Editing without reading** — Issuing an Edit without a prior Read produces "oldString not found" failures when the file differs from assumptions. Always read first.
+**Editing without reading**: Issuing an Edit without a prior Read produces "oldString not found" failures when the file differs from assumptions. Always read first.
 
-**Creating new files instead of editing existing ones** — Adding a new file when the logic belongs in an existing one fragments the codebase. Check for the right home first.
+**Creating new files instead of editing existing ones**: Adding a new file when the logic belongs in an existing one fragments the codebase. Check for the right home first.
 
-**Commenting what the code already says** — `// increment counter` above `count++` adds noise. Comments earn their place by explaining non-obvious constraints, not restating syntax.
+**Commenting what the code already says**: `// increment counter` above `count++` adds noise. Comments earn their place by explaining non-obvious constraints, not restating syntax.
 
 ## Testing
 
-**Testing the mock instead of the behavior** — A test that only verifies that a mock was called doesn't confirm the real behavior. Prefer integration-level assertions over spy counts.
+**Testing the mock instead of the behavior**: A test that only verifies that a mock was called doesn't confirm the real behavior. Prefer integration-level assertions over spy counts.
 
-**Skipping the failing test to make CI green** — Skipping tests hides regressions. Fix the failure or delete the test with a comment explaining why it no longer applies.
+**Skipping the failing test to make CI green**: Skipping tests hides regressions. Fix the failure or delete the test with a comment explaining why it no longer applies.
 
 ## Git
 
-**Amending a pushed commit** — `git commit --amend` after a push requires force-push, which rewrites shared history. Use a new commit instead.
+**Amending a pushed commit**: `git commit --amend` after a push requires force-push, which rewrites shared history. Use a new commit instead.
 
-**Committing without running tests** — Tests exist to catch regressions before they land on main. A green build is the only signal that a change is safe to ship.
+**Committing without running tests**: Tests exist to catch regressions before they land on main. A green build is the only signal that a change is safe to ship.
 
 ## Agent Behavior
 
-**Stopping without surfacing incomplete tasks** — An agent that stops while tasks are `in_progress` or have unmet acceptance criteria leaves the user without visibility. Surface the state before stopping.
+**Stopping without surfacing incomplete tasks**: An agent that stops while tasks are `in_progress` or have unmet acceptance criteria leaves the user without visibility. Surface the state before stopping.
 
-**Making assumptions about user intent** — When a requirement is ambiguous, ask one targeted question rather than guessing and building the wrong thing.
+**Making assumptions about user intent**: When a requirement is ambiguous, ask one targeted question rather than guessing and building the wrong thing.

package/examples/seed-observations/decisions.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/decisions.md — key architectural decisions for Construct memory seed corpus.
+examples/seed-observations/decisions.md: key architectural decisions for Construct memory seed corpus.
 
 Each entry becomes one observation in the store with category "decision". Imported via
 `construct bootstrap`.
@@ -13,7 +13,7 @@ Each entry becomes one observation in the store with category "decision". Import
 
 ## Two-Phase Sync with Lockfile
 
-`construct sync` writes to `.cx/sync-staging/` first, then atomically renames into place. A lockfile at `.cx/sync.lock` prevents concurrent runs from corrupting the output. This makes partial syncs impossible — either the full sync lands or nothing does.
+`construct sync` writes to `.cx/sync-staging/` first, then atomically renames into place. A lockfile at `.cx/sync.lock` prevents concurrent runs from corrupting the output. This makes partial syncs impossible: either the full sync lands or nothing does.
 
 ## Hook Ceiling: 30
 
@@ -25,7 +25,7 @@ The memory layer uses a hashing bag-of-words cosine similarity for dense recall
 
 ## Tiered Session-Start Injection
 
-Session-start injects context in three tiers: Tier 1 (always — header, branch, status), Tier 2 (when fresh and meaningful — workflow, observations, context.md), Tier 3 (hint-only — efficiency snapshot, skill scope). This caps injection size and avoids loading the model with stale or irrelevant context on every session.
+Session-start injects context in three tiers: Tier 1 (always (header, branch, status), Tier 2 (when fresh and meaningful) workflow, observations, context.md), Tier 3 (hint-only: efficiency snapshot, skill scope). This caps injection size and avoids loading the model with stale or irrelevant context on every session.
 
 ## Declarative Policy Rules
 
@@ -33,4 +33,4 @@ Hook guards for workflow, drive, bootstrap, and task behavior are expressed as Y
 
 ## Registry as Single Source of Truth
 
-`agents/registry.json` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly — edits are overwritten on the next sync.
+`agents/registry.json` is the canonical definition for all agents on all platforms (Claude Code, OpenCode, Codex, Copilot). `construct sync` regenerates all platform-specific files from the registry. Never edit generated files directly: edits are overwritten on the next sync.

package/examples/seed-observations/patterns.md

@@ -1,5 +1,5 @@
 <!--
-examples/seed-observations/patterns.md — engineering patterns for Construct memory seed corpus.
+examples/seed-observations/patterns.md: engineering patterns for Construct memory seed corpus.
 
 Each entry becomes one observation in the store. Format: ## Category, then pattern entries
 with **Pattern name** and description. Imported via `construct bootstrap`.
@@ -9,34 +9,34 @@ with **Pattern name** and description. Imported via `construct bootstrap`.
 
 ## Code Quality
 
-**Read before edit** — Always read the target file with the Read tool before writing or editing. Editing without reading produces stale edits that fail with "oldString not found".
+**Read before edit**: Always read the target file with the Read tool before writing or editing. Editing without reading produces stale edits that fail with "oldString not found".
 
-**Parallel tool calls for independent work** — When two tool calls don't depend on each other's output, issue them in the same message. Cuts wall time roughly in half for multi-file operations.
+**Parallel tool calls for independent work**: When two tool calls don't depend on each other's output, issue them in the same message. Cuts wall time roughly in half for multi-file operations.
 
-**Probe before bulk read** — Use Glob or Grep to identify which files are relevant before reading them. Bulk-reading 10 files to find the one that matters burns context and slows response.
+**Probe before bulk read**: Use Glob or Grep to identify which files are relevant before reading them. Bulk-reading 10 files to find the one that matters burns context and slows response.
 
-**Edit smallest possible diff** — Target the exact lines that need to change. Large oldString blocks with unchanged surrounding context are fragile when the file is modified concurrently.
+**Edit smallest possible diff**: Target the exact lines that need to change. Large oldString blocks with unchanged surrounding context are fragile when the file is modified concurrently.
 
 ## Testing
 
-**Run targeted test first** — Before running the full suite, run only the affected test file. Faster feedback loop; full suite confirms no regressions.
+**Run targeted test first**: Before running the full suite, run only the affected test file. Faster feedback loop; full suite confirms no regressions.
 
-**Assert the contract, not the implementation** — Tests that check internal state (private variables, call counts) break on refactors that don't change behavior. Test the public output.
+**Assert the contract, not the implementation**: Tests that check internal state (private variables, call counts) break on refactors that don't change behavior. Test the public output.
 
-**Table-driven tests for edge cases** — When a function has many input/output pairs to verify, a single table-driven test is more maintainable than N separate `it()` blocks.
+**Table-driven tests for edge cases**: When a function has many input/output pairs to verify, a single table-driven test is more maintainable than N separate `it()` blocks.
 
 ## Git Discipline
 
-**Branch, test, merge** — Never commit directly to main. Branch for every feature or fix, verify tests pass, then merge.
+**Branch, test, merge**: Never commit directly to main. Branch for every feature or fix, verify tests pass, then merge.
 
-**Commit message: why, not what** — The diff already shows what changed. The commit message should explain why. "fix dry-run bypass" is less useful than "fix: dry-run skipped mkdirp calls, causing 31 phantom files in test home".
+**Commit message: why, not what**: The diff already shows what changed. The commit message should explain why. "fix dry-run bypass" is less useful than "fix: dry-run skipped mkdirp calls, causing 31 phantom files in test home".
 
-**Atomic commits** — One logical change per commit. Mixing a bug fix with a refactor makes bisect and revert painful.
+**Atomic commits**: One logical change per commit. Mixing a bug fix with a refactor makes bisect and revert painful.
 
 ## Agent Dispatch
 
-**Route through Construct** — Construct is the single dispatch point. Invoking specialist agents directly bypasses context injection and workflow tracking.
+**Route through Construct**: Construct is the single dispatch point. Invoking specialist agents directly bypasses context injection and workflow tracking.
 
-**Subagent for isolated subtasks** — Use Task tool dispatch when a subtask has a clear input/output contract and doesn't need the parent conversation history. Keeps the main context lean.
+**Subagent for isolated subtasks**: Use Task tool dispatch when a subtask has a clear input/output contract and doesn't need the parent conversation history. Keeps the main context lean.
 
-**Timeout specialist calls** — Agent dispatch without a timeout can block indefinitely. Set `timeout: 120_000` as a floor; use 300_000 for heavy analysis tasks.
+**Timeout specialist calls**: Agent dispatch without a timeout can block indefinitely. Set `timeout: 120_000` as a floor; use 300_000 for heavy analysis tasks.

package/lib/auto-docs.mjs

@@ -158,11 +158,16 @@ function buildAgentsTable(rootDir) {
   const agents = registry.agents ?? registry;
   if (!Array.isArray(agents)) return '';
 
-  const rows = ['| Agent | Tier | Purpose |', '|---|---|---|'];
+  const rows = ['| Specialist | Tier | Purpose |', '|---|---|---|'];
   for (const agent of agents.slice(0, 30)) {
-    const name = agent.id ?? agent.name ?? '—';
-    const tier = agent.tier ?? agent.model_tier ?? '—';
-    const purpose = (agent.description ?? agent.purpose ?? '').split('\n')[0].slice(0, 80);
+    const name = agent.name ?? agent.id ?? 'n/a';
+    const tier = agent.modelTier ?? agent.tier ?? agent.model_tier ?? 'n/a';
+    // Strip em-dashes from descriptions so the prose lint stays clean across
+    // AUTO regen. Em-dashes are allowed in the registry's source descriptions
+    // but never in the rendered markdown.
+    const purpose = (agent.description ?? agent.purpose ?? '')
+      .split('\n')[0].slice(0, 80)
+      .replace(/ — /g, '. ').replace(/—/g, ',');
     rows.push(`| \`${name}\` | ${tier} | ${purpose} |`);
   }
   if (agents.length > 30) rows.push(`| *(+${agents.length - 30} more)* | | |`);
@@ -190,7 +195,7 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
       },
     },
     {
-      file: path.join(rootDir, 'docs', 'concepts', 'architecture.md'),
+      file: path.join(rootDir, 'docs', 'concepts', 'architecture.mdx'),
       regions: {
         agents: buildAgentsTable(rootDir),
       },
@@ -391,13 +396,13 @@ function renderAgentsPage(rootDir) {
   if (!table) return null;
   return [
     '---',
-    'title: Agents',
-    'description: The 28 cx-* specialists plus the construct persona. Generated from agents/registry.json.',
+    'title: Specialists',
+    'description: The 28 specialists behind the construct persona. Generated from agents/registry.json.',
     '---',
     '',
     '> Generated from `agents/registry.json`. Re-run `construct docs:site` to refresh.',
     '',
-    'Construct ships one persona (`construct`) plus 28 specialists. Each specialist has a role, model tier, and prompt that defines its decision authority. Specialists are addressable directly when you want a focused conversation; for everyday work, address `@construct` and let it route.',
+    'Construct ships one persona (`construct`) and 28 specialists behind it. You address `@construct` for all everyday work; it routes to specialists internally. Each specialist has a role, model tier, and prompt file that defines its decision authority.',
     '',
     table,
     '',

package/lib/boundary.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/boundary.mjs — Authenticated parent/child boundary registration.
+ *
+ * Verifies a parent Construct instance is reachable, validates an HMAC
+ * signature over `childInstanceId|nonce` when a shared secret is configured,
+ * and persists the binding to ~/.construct/boundary.json (mode 0600). A
+ * different parent rotates the registration only when explicitly allowed via
+ * CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1; prior configs are archived alongside
+ * the active one. Exposed as a standalone module so the dashboard endpoint
+ * and the functional tests share the same logic.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+
+export const BOUNDARY_VERSION = '1.0';
+
+function boundaryDir(home = homedir()) {
+  return join(home, '.construct');
+}
+
+export function boundaryConfigPath(home = homedir()) {
+  return join(boundaryDir(home), 'boundary.json');
+}
+
+export async function registerBoundary({
+  parentInstance,
+  parentUrl,
+  childInstanceId,
+  nonce,
+  signature,
+  sharedSecret = null,
+  home = homedir(),
+  allowOverride = process.env.CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE === '1',
+  probe = probeParent,
+}) {
+  if (!parentInstance || !parentUrl) {
+    return { ok: false, status: 400, error: 'parentInstance and parentUrl are required' };
+  }
+  if (!childInstanceId) {
+    return { ok: false, status: 400, error: 'childInstanceId is required' };
+  }
+
+  if (sharedSecret) {
+    if (!nonce || !signature) {
+      return { ok: false, status: 401, error: 'nonce and signature are required when a shared secret is configured' };
+    }
+    const expected = createHmac('sha256', sharedSecret).update(`${childInstanceId}|${nonce}`).digest('hex');
+    const a = Buffer.from(expected, 'hex');
+    let b;
+    try { b = Buffer.from(String(signature), 'hex'); } catch { return { ok: false, status: 401, error: 'invalid signature encoding' }; }
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+      return { ok: false, status: 401, error: 'signature mismatch' };
+    }
+  }
+
+  const reachable = await probe(parentUrl);
+  if (!reachable.ok) {
+    return { ok: false, status: 502, error: `parent unreachable: ${reachable.error}` };
+  }
+
+  const dir = boundaryDir(home);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const cfgPath = boundaryConfigPath(home);
+
+  let prior = null;
+  if (existsSync(cfgPath)) {
+    try { prior = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch { prior = null; }
+  }
+
+  if (prior && prior.parentInstance && prior.parentInstance !== parentInstance) {
+    if (!allowOverride) {
+      return {
+        ok: false,
+        status: 409,
+        error: `child already bound to parent '${prior.parentInstance}'; set CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1 to rotate`,
+      };
+    }
+    const archivePath = join(dir, `boundary.${Date.now()}.json`);
+    try { writeFileSync(archivePath, JSON.stringify(prior, null, 2)); } catch { /* archive is best effort */ }
+  }
+
+  const config = {
+    parentInstance,
+    parentUrl,
+    childInstanceId,
+    registeredAt: new Date().toISOString(),
+    rotatedFrom: prior?.parentInstance || null,
+    nonce: nonce || randomBytes(16).toString('hex'),
+    boundaryVersion: BOUNDARY_VERSION,
+  };
+
+  writeFileSync(cfgPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+  return { ok: true, config, path: cfgPath };
+}
+
+export function probeParent(parentUrl) {
+  return new Promise((resolve) => {
+    let parsed;
+    try { parsed = new URL(parentUrl); } catch { return resolve({ ok: false, error: 'invalid URL' }); }
+    if (!/^https?:$/.test(parsed.protocol)) return resolve({ ok: false, error: 'unsupported protocol' });
+    const fn = parsed.protocol === 'https:' ? httpsRequest : httpRequest;
+    const req = fn({
+      method: 'HEAD',
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname || '/',
+      timeout: 3000,
+    }, (response) => {
+      resolve({ ok: response.statusCode < 500 });
+      response.resume();
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }); });
+    req.on('error', (err) => resolve({ ok: false, error: err.message }));
+    req.end();
+  });
+}
+
+export function signBoundaryRequest({ childInstanceId, nonce, sharedSecret }) {
+  return createHmac('sha256', sharedSecret).update(`${childInstanceId}|${nonce}`).digest('hex');
+}

package/lib/cache-strategy-google.js

@@ -1,17 +1,34 @@
 /**
- * lib/cache-strategy-google.js — Google Gemini cache strategy.
+ * lib/cache-strategy-google.js — Google Gemini cache strategy (agnostic skeleton).
  *
- * Google uses cachedContent API (resource-based caching, not annotations).
- * Cache TTL: 1h via cachedContent resource.
- * Requires separate API call to create/update cached content.
+ * Gemini uses a resource-based cachedContent API rather than per-message
+ * annotations. Construct does not own that integration: this module exposes
+ * the same surface as the other cache-strategy adapters and resolves cached
+ * resources via a pluggable resolver. The default resolver returns null
+ * (no cached resource), which is the safe agnostic default — callers will
+ * fall through to a fresh request. Provider plugins or operators can register
+ * a resolver via `setCachedContentResolver` to enable resource caching.
  */
 import { estimateTokens } from './token-engine.js';
 
 const GEMINI_CACHE_ENDPOINT = 'https://generativelanguage.googleapis.com/v1';
 
+let cachedContentResolver = null;
+
+/**
+ * Register a resolver responsible for producing a cachedContent resource name
+ * for a given system prompt. Contract:
+ *   resolver({ systemText, caps, apiKey, modelId }) -> Promise<string|null>
+ * Returning null means no cached resource is available; the annotation is
+ * omitted and the request proceeds without a cached prefix.
+ */
+export function setCachedContentResolver(resolver) {
+  cachedContentResolver = typeof resolver === 'function' ? resolver : null;
+}
+
 /**
- * Annotate prompt structure for Google Gemini models.
- * Note: Gemini uses cachedContent API, not message annotations.
+ * Annotate prompt structure for Google Gemini models. Returns the shared
+ * annotation shape that every cache-strategy adapter emits.
  *
  * @param {object} promptStructure - { system, messages }
  * @param {object} caps - Provider capabilities
@@ -22,12 +39,10 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   const { system, messages } = promptStructure || {};
 
   let cachedContentName = null;
-
-  if (apiKey && system) {
+  if (cachedContentResolver && apiKey && system) {
     try {
-      cachedContentName = await createCachedContent(system, caps, apiKey, modelId);
-    } catch (err) {
-    }
+      cachedContentName = await cachedContentResolver({ systemText: system, caps, apiKey, modelId });
+    } catch { /* resolver failure is non-fatal — fall through with no annotation */ }
   }
 
   return {
@@ -49,26 +64,6 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   };
 }
 
-async function createCachedContent(systemText, caps, apiKey, modelId) {
-  // POST to https://generativelanguage.googleapis.com/v1/cachedContents
-  // Body: { model: 'gemini-1.5-pro', contents: [{ parts: [{ text: systemText }] }] }
-  // Returns: { name: 'cachedContents/abc123' }
-
-  const model = extractModelName(modelId);
-  const url = `${GEMINI_CACHE_ENDPOINT}/cachedContents?key=${apiKey}`;
-
-  // This is async but we don't want to block dispatch
-  // In production, this should be pre-cached
-  // For now, return null (defer to Phase C follow-up with live probing)
-  return null;
-}
-
-function extractModelName(modelId) {
-  const id = String(modelId || '').toLowerCase();
-  const match = id.match(/google\/(gemini-[^\/]+)/);
-  return match ? match[1] : 'gemini-1.5-pro';
-}
-
 export async function capabilities() {
   return {
     supportsAnnotations: false,

package/lib/cli-commands.mjs

@@ -92,7 +92,7 @@ export const CLI_COMMANDS = [
     emoji: '📥',
     category: 'Core',
     core: true,
-    description: 'View and process R&D intake queue',
+    description: 'View and process the active profile\'s intake queue (queue label varies by profile)',
     usage: 'construct intake list|show|done|skip',
   },
   {
@@ -166,7 +166,7 @@ export const CLI_COMMANDS = [
       { name: 'show', desc: 'Show the active profile' },
       { name: 'list', desc: 'List curated profiles' },
       { name: 'set <id>', desc: 'Switch the active profile (writes construct.config.json)' },
-      { name: 'create <id> [--display="..."]', desc: 'Scaffold a draft profile + requirements brief under .cx/profiles/draft-<id>/' },
+      { name: 'create <id> [--display=…] [--role=…] [--department=…] [--yes|--dry-run]', desc: 'Scaffold a draft profile; previews and confirms by default, prompts interactively when no flags' },
       { name: 'drafts', desc: 'List in-progress draft profiles' },
       { name: 'archive <id> --reason="..."', desc: 'Move a curated profile into archive/profiles/<id>/' },
       { name: 'health <id> [--days=N]', desc: 'Per-profile observation + outcome rollup' },