@geraldmaron/construct 1.0.6 → 1.0.8

package/commands/build/feature.md

@@ -4,7 +4,7 @@ commands/build/feature.md (Build a feature) implement it end to end, tested and
 Build a feature: implement it end to end, tested and ready to ship
 -->
 ---
-description: Build a feature: implement it end to end, tested and ready to ship
+description: "Build a feature: implement it end to end, tested and ready to ship"
 ---
 
 You are Construct. Build the following: $ARGUMENTS

package/commands/build/fix.md

@@ -4,7 +4,7 @@ commands/build/fix.md (Fix something broken) reproduce, find the root cause, app
 Fix something broken: reproduce, find the root cause, apply the smallest safe change
 -->
 ---
-description: Fix something broken: reproduce, find the root cause, apply the smallest safe change
+description: "Fix something broken: reproduce, find the root cause, apply the smallest safe change"
 ---
 
 You are Construct.

package/commands/design/access.md

@@ -4,7 +4,7 @@ commands/design/access.md (Accessibility audit) WCAG 2.1 AA, keyboard, screen re
 Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion
 -->
 ---
-description: Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion
+description: "Accessibility audit: WCAG 2.1 AA, keyboard, screen readers, contrast, motion"
 ---
 
 You are Construct. Audit: $ARGUMENTS

package/commands/design/flow.md

@@ -4,7 +4,7 @@ commands/design/flow.md (Map the user flow) entry to success, friction points, j
 Map the user flow: entry to success, friction points, jobs-to-be-done
 -->
 ---
-description: Map the user flow: entry to success, friction points, jobs-to-be-done
+description: "Map the user flow: entry to success, friction points, jobs-to-be-done"
 ---
 
 You are Construct. Map the user flow for: $ARGUMENTS

package/commands/design/ui.md

@@ -4,7 +4,7 @@ commands/design/ui.md (Design or review UI) visual hierarchy, states, interactio
 Design or review UI: visual hierarchy, states, interaction model, accessibility baseline
 -->
 ---
-description: Design or review UI: visual hierarchy, states, interaction model, accessibility baseline
+description: "Design or review UI: visual hierarchy, states, interaction model, accessibility baseline"
 ---
 
 You are Construct. Design or review the UI for: $ARGUMENTS

package/commands/measure/experiment.md

@@ -4,7 +4,7 @@ commands/measure/experiment.md (Design an experiment) hypothesis, test, evidence
 Design an experiment: hypothesis, test, evidence threshold, go/no-go decision
 -->
 ---
-description: Design an experiment: hypothesis, test, evidence threshold, go/no-go decision
+description: "Design an experiment: hypothesis, test, evidence threshold, go/no-go decision"
 ---
 
 You are Construct. Design an experiment for: $ARGUMENTS

package/commands/measure/metrics.md

@@ -4,7 +4,7 @@ commands/measure/metrics.md (Define metrics) what to measure, baselines, success
 Define metrics: what to measure, baselines, success thresholds, instrumentation needed
 -->
 ---
-description: Define metrics: what to measure, baselines, success thresholds, instrumentation needed
+description: "Define metrics: what to measure, baselines, success thresholds, instrumentation needed"
 ---
 
 You are Construct. Define metrics for: $ARGUMENTS

package/commands/measure/results.md

@@ -4,7 +4,7 @@ commands/measure/results.md (Analyze results) interpret data, separate signal fr
 Analyze results: interpret data, separate signal from noise, produce a recommendation
 -->
 ---
-description: Analyze results: interpret data, separate signal from noise, produce a recommendation
+description: "Analyze results: interpret data, separate signal from noise, produce a recommendation"
 ---
 
 You are Construct. Analyze: $ARGUMENTS

package/commands/plan/api.md

@@ -4,7 +4,7 @@ commands/plan/api.md (Design an API) contracts, endpoints, error model, data sch
 Design an API: contracts, endpoints, error model, data schema
 -->
 ---
-description: Design an API: contracts, endpoints, error model, data schema
+description: "Design an API: contracts, endpoints, error model, data schema"
 ---
 
 You are Construct. Design the API for: $ARGUMENTS

package/commands/plan/challenge.md

@@ -4,7 +4,7 @@ commands/plan/challenge.md (Challenge a plan) stress-test assumptions, surface f
 Challenge a plan: stress-test assumptions, surface failure modes and risks
 -->
 ---
-description: Challenge a plan: stress-test assumptions, surface failure modes and risks
+description: "Challenge a plan: stress-test assumptions, surface failure modes and risks"
 ---
 
 You are Construct. Challenge the following: $ARGUMENTS

package/commands/plan/decide.md

@@ -4,7 +4,7 @@ commands/plan/decide.md (Record a decision) context, options considered, consequ
 Record a decision: context, options considered, consequences, what it locks in
 -->
 ---
-description: Record a decision: context, options considered, consequences, what it locks in
+description: "Record a decision: context, options considered, consequences, what it locks in"
 ---
 
 You are Construct. Document the decision about: $ARGUMENTS

package/commands/plan/feature.md

@@ -5,7 +5,7 @@ Produces a structured spec using the canonical Construct plan format, saves it
 to .cx/plans/ as a durable planning artifact linked to the active tracker slice.
 -->
 ---
-description: Plan a feature: produce a structured spec and link it to the active tracker-backed plan
+description: "Plan a feature: produce a structured spec and link it to the active tracker-backed plan"
 ---
 
 You are Construct. Plan the following: $ARGUMENTS

package/commands/plan/requirements.md

@@ -4,7 +4,7 @@ commands/plan/requirements.md (Define requirements) what needs to be true for th
 Define requirements: what needs to be true for this to be done
 -->
 ---
-description: Define requirements: what needs to be true for this to be done
+description: "Define requirements: what needs to be true for this to be done"
 ---
 
 You are Construct. Define requirements for: $ARGUMENTS

package/commands/remember/context.md

@@ -4,7 +4,7 @@ commands/remember/context.md (Save project context) update .cx/context.md so the
 Save project context: update .cx/context.md so the next session picks up where this one left off
 -->
 ---
-description: Save project context: update .cx/context.md so the next session picks up where this one left off
+description: "Save project context: update .cx/context.md so the next session picks up where this one left off"
 ---
 
 You are Construct. Save context for: $ARGUMENTS

package/commands/remember/handoff.md

@@ -4,7 +4,7 @@ commands/remember/handoff.md (Write a handoff) transfer context so the next sess
 Write a handoff: transfer context so the next session or person can continue without loss
 -->
 ---
-description: Write a handoff: transfer context so the next session or person can continue without loss
+description: "Write a handoff: transfer context so the next session or person can continue without loss"
 ---
 
 You are Construct. Write a handoff for: $ARGUMENTS

package/commands/remember/runbook.md

@@ -4,7 +4,7 @@ commands/remember/runbook.md (Write a runbook) step-by-step procedure for a recu
 Write a runbook: step-by-step procedure for a recurring task or incident
 -->
 ---
-description: Write a runbook: step-by-step procedure for a recurring task or incident
+description: "Write a runbook: step-by-step procedure for a recurring task or incident"
 ---
 
 You are Construct. Write a runbook for: $ARGUMENTS

package/commands/review/code.md

@@ -4,7 +4,7 @@ commands/review/code.md (Code review) correctness, regressions, security, test c
 Code review: correctness, regressions, security, test coverage
 -->
 ---
-description: Code review: correctness, regressions, security, test coverage
+description: "Code review: correctness, regressions, security, test coverage"
 ---
 
 You are Construct. Review: $ARGUMENTS

package/commands/review/quality.md

@@ -4,7 +4,7 @@ commands/review/quality.md (Quality audit) complexity, naming, duplication, dead
 Quality audit: complexity, naming, duplication, dead code, maintainability
 -->
 ---
-description: Quality audit: complexity, naming, duplication, dead code, maintainability
+description: "Quality audit: complexity, naming, duplication, dead code, maintainability"
 ---
 
 You are Construct. Audit quality for: $ARGUMENTS

package/commands/review/security.md

@@ -4,7 +4,7 @@ commands/review/security.md (Security scan) secrets, auth, injection, data expos
 Security scan: secrets, auth, injection, data exposure, dependency risk
 -->
 ---
-description: Security scan: secrets, auth, injection, data exposure, dependency risk
+description: "Security scan: secrets, auth, injection, data exposure, dependency risk"
 ---
 
 You are Construct. Scan: $ARGUMENTS

package/commands/ship/ready.md

@@ -4,7 +4,7 @@ commands/ship/ready.md (Pre-release check) is this ready to ship?
 Pre-release check: is this ready to ship?
 -->
 ---
-description: Pre-release check: is this ready to ship?
+description: "Pre-release check: is this ready to ship?"
 ---
 
 You are Construct. Check if the following is ready: $ARGUMENTS

package/commands/ship/release.md

@@ -4,7 +4,7 @@ commands/ship/release.md (Release) plan rollout, changelog, rollback, and post-r
 Release: plan rollout, changelog, rollback, and post-release verification
 -->
 ---
-description: Release: plan rollout, changelog, rollback, and post-release verification
+description: "Release: plan rollout, changelog, rollback, and post-release verification"
 ---
 
 You are Construct. Release the following: $ARGUMENTS

package/commands/ship/status.md

@@ -4,7 +4,7 @@ commands/ship/status.md (Status) current project state, workflow, uncommitted ch
 Status: current project state, workflow, uncommitted changes, recent activity
 -->
 ---
-description: Status: current project state, workflow, uncommitted changes, recent activity
+description: "Status: current project state, workflow, uncommitted changes, recent activity"
 ---
 
 You are Construct. Report status for: $ARGUMENTS

package/commands/understand/docs.md

@@ -4,7 +4,7 @@ commands/understand/docs.md (Look up documentation) current behavior from primar
 Look up documentation: current behavior from primary sources, not training memory
 -->
 ---
-description: Look up documentation: current behavior from primary sources, not training memory
+description: "Look up documentation: current behavior from primary sources, not training memory"
 ---
 
 You are Construct. Look up: $ARGUMENTS

package/commands/understand/this.md

@@ -4,7 +4,7 @@ commands/understand/this.md (Explore and understand something) trace execution p
 Explore and understand something: trace execution paths, map structure, gather evidence
 -->
 ---
-description: Explore and understand something: trace execution paths, map structure, gather evidence
+description: "Explore and understand something: trace execution paths, map structure, gather evidence"
 ---
 
 You are Construct. Explore and explain: $ARGUMENTS

package/commands/understand/why.md

@@ -4,7 +4,7 @@ commands/understand/why.md (Investigate a failure) why is this broken, what is t
 Investigate a failure: why is this broken, what is the root cause
 -->
 ---
-description: Investigate a failure: why is this broken, what is the root cause
+description: "Investigate a failure: why is this broken, what is the root cause"
 ---
 
 You are Construct. Investigate: $ARGUMENTS

package/commands/work/clean.md

@@ -4,7 +4,7 @@ commands/work/clean.md (Remove AI-generated code smells) verbosity, hedging, dea
 Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
 -->
 ---
-description: Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
+description: "Remove AI-generated code smells: verbosity, hedging, dead comments, generic names"
 ---
 
 You are cx-reviewer identifying AI slop in: $ARGUMENTS

package/commands/work/drive.md

@@ -4,7 +4,7 @@ commands/work/drive.md (Full autonomous execution) explore, plan, implement, ver
 Full autonomous execution: explore, plan, implement, verify, loop until done
 -->
 ---
-description: Full autonomous execution: explore, plan, implement, verify, loop until done
+description: "Full autonomous execution: explore, plan, implement, verify, loop until done"
 ---
 
 You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously without stopping for confirmation.

package/commands/work/optimize-prompts.md

@@ -4,7 +4,7 @@ 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,7 +18,7 @@ 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`)
+1. **Read current prompt**: read the agent's prompt from `specialists/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

package/commands/work/parallel-review.md

@@ -4,7 +4,7 @@ commands/work/parallel-review.md (Adversarial parallel review) 5 reviewers must
 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

package/db/schema/007_tags.sql

@@ -0,0 +1,30 @@
+-- Tag attribution and migration tracking for construct_documents.
+-- The construct_documents.tags JSONB column already exists in 001_init.sql.
+-- This migration adds GIN indexing, attribution history, and migration audit.
+
+create index if not exists construct_documents_tags_gin_idx
+  on construct_documents using gin (tags jsonb_path_ops);
+
+create table if not exists construct_tag_attribution (
+  document_id text not null references construct_documents(id) on delete cascade,
+  tag text not null,
+  source text not null,  -- 'agent:classifier' | 'user' | 'curator'
+  confidence numeric,
+  applied_at timestamptz not null default now(),
+  migrated_from text,
+  primary key (document_id, tag, source)
+);
+create index if not exists construct_tag_attribution_tag_idx on construct_tag_attribution (tag);
+
+create table if not exists construct_tag_migrations (
+  id text primary key,
+  from_tag text not null,
+  to_tag text,
+  executed_at timestamptz not null default now(),
+  executed_by text not null,
+  reason text not null,
+  doc_count_before integer not null,
+  doc_count_after integer,
+  reversible boolean not null default true,
+  rolled_back_at timestamptz
+);

package/db/schema/008_skill_usage.sql

@@ -0,0 +1,24 @@
+-- db/schema/008_skill_usage.sql — Per-skill invocation log.
+--
+-- Backs `construct skills usage/orphans/hot`.  The local
+-- JSONL path (~/.cx/skill-calls.jsonl) is primary in solo mode; this table is
+-- primary in team/enterprise mode.  One-time backfill via
+-- `construct skills backfill-postgres`.
+
+create table if not exists construct_skill_invocations (
+  id           bigserial    primary key,
+  ts           timestamptz  not null,
+  skill_id     text         not null,
+  source       text         not null,  -- 'mcp' | 'role-preload' | 'prompt-composer' | …
+  agent_id     text,
+  session_id   text,
+  caller_context text,
+  latency_ms   integer,
+  tokens_returned integer
+);
+
+create index if not exists construct_skill_invocations_skill_ts_idx
+  on construct_skill_invocations (skill_id, ts desc);
+
+create index if not exists construct_skill_invocations_session_idx
+  on construct_skill_invocations (session_id);

package/db/schema/009_scheduler.sql

@@ -0,0 +1,14 @@
+-- Scheduler job state for team and enterprise deployment modes.
+-- Solo mode uses native trigger files instead of this table.
+-- The lock_holder column stores a short identifier for the process/host
+-- that currently holds the advisory lock for a running job.
+
+create table if not exists construct_scheduled_jobs (
+  id text primary key,
+  schedule text not null,
+  last_run_at timestamptz,
+  last_run_status text,
+  lock_holder text,
+  lock_acquired_at timestamptz,
+  created_at timestamptz not null default now()
+);

package/examples/internal/roles/architect/bad/clever-plan-without-contracts.md

@@ -7,7 +7,7 @@ verdict: fail
 summary: Recommends a clever architecture without exposing contracts or rejected alternatives.
 references:
   - skills/roles/architect.md
-  - agents/prompts/cx-architect.md
+  - specialists/prompts/cx-architect.md
 tags:
   - missing-contracts
   - hidden-dependencies

package/examples/internal/roles/architect/golden/explicit-tradeoff-before-plan.md

@@ -7,7 +7,7 @@ verdict: pass
 summary: Makes interface and dependency tradeoffs explicit before locking in a plan.
 references:
   - skills/roles/architect.md
-  - agents/prompts/cx-architect.md
+  - specialists/prompts/cx-architect.md
 tags:
   - tradeoffs
   - contracts

package/examples/internal/roles/engineer/bad/speculative-abstraction.md

@@ -7,7 +7,7 @@ verdict: fail
 summary: Introduces an abstraction for future cases without evidence from the code.
 references:
   - skills/roles/engineer.md
-  - agents/prompts/cx-engineer.md
+  - specialists/prompts/cx-engineer.md
 tags:
   - speculative-abstraction
   - unnecessary-surface-area

package/examples/internal/roles/engineer/golden/read-before-write.md

@@ -7,7 +7,7 @@ verdict: pass
 summary: Reads the touched files and surrounding pattern before proposing code changes.
 references:
   - skills/roles/engineer.md
-  - agents/prompts/cx-engineer.md
+  - specialists/prompts/cx-engineer.md
 tags:
   - read-before-write
   - local-conventions

package/examples/internal/roles/qa/bad/coverage-theater.md

@@ -7,7 +7,7 @@ verdict: fail
 summary: Treats a green suite or coverage number as proof that the behavior is safe.
 references:
   - skills/roles/qa.md
-  - agents/prompts/cx-qa.md
+  - specialists/prompts/cx-qa.md
 tags:
   - coverage-theater
   - false-confidence

package/examples/internal/roles/qa/golden/regression-gate.md

@@ -7,7 +7,7 @@ verdict: pass
 summary: Verifies changed behavior with regression-oriented tests instead of coverage theater.
 references:
   - skills/roles/qa.md
-  - agents/prompts/cx-qa.md
+  - specialists/prompts/cx-qa.md
 tags:
   - regression
   - changed-behavior

package/examples/seed-observations/decisions.md

@@ -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.
+`specialists/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/lib/audit-skills.mjs

@@ -11,7 +11,7 @@ import path from 'node:path';
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'agents', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -36,7 +36,7 @@ function collectSkillFiles(skillsDir) {
 
 export function auditSkills({ rootDir, silent = false } = {}) {
   const root = rootDir ?? findConstructRoot();
-  const registryPath = path.join(root, 'agents', 'registry.json');
+  const registryPath = path.join(root, 'specialists', 'registry.json');
   const skillsDir = path.join(root, 'skills');
 
   const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
@@ -46,7 +46,7 @@ export function auditSkills({ rootDir, silent = false } = {}) {
   const agentsWithNoSkills = [];
   const missingSkillFiles = [];
 
-  for (const agent of registry.agents ?? []) {
+  for (const agent of registry.specialists ?? []) {
     const skills = agent.skills ?? [];
     if (skills.length === 0) {
       agentsWithNoSkills.push(agent.name);

package/lib/auto-docs.mjs

@@ -158,10 +158,10 @@ 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 ?? 'n/a';
-    const tier = agent.tier ?? agent.model_tier ?? 'n/a';
+    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.
@@ -195,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),
       },
@@ -396,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 specialists/registry.json.',
     '---',
     '',
-    '> Generated from `agents/registry.json`. Re-run `construct docs:site` to refresh.',
+    '> Generated from `specialists/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');
+}