@geraldmaron/construct 1.2.2 → 1.3.0

package/lib/certification/skill-inventory.mjs

@@ -7,14 +7,17 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { artifactTypes, loadArtifactManifest } from '../artifact-manifest.mjs';
+import { validateSkillEffectiveness } from '../validators/skill-effectiveness.mjs';
+import { collectScopeRoleIds } from '../scopes/enrich.mjs';
 
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -37,22 +40,18 @@ function collectSkillFiles(skillsDir) {
   return results.sort();
 }
 
-function collectProfileRoles(root) {
-  const dir = path.join(root, 'profiles');
+function collectScopeRoles(root) {
+  const dir = path.join(root, 'specialists', 'org', 'scopes');
   const roles = new Set();
-  const scan = (node) => {
-    if (Array.isArray(node)) { node.forEach(scan); return; }
-    if (node && typeof node === 'object') {
-      if (Array.isArray(node.roles)) for (const r of node.roles) if (typeof r === 'string') roles.add(r);
-      for (const v of Object.values(node)) scan(v);
-    }
-  };
   try {
     for (const f of fs.readdirSync(dir)) {
       if (!f.endsWith('.json')) continue;
-      try { scan(JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'))); } catch { /* skip malformed */ }
+      try {
+        const raw = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+        for (const r of collectScopeRoleIds(raw, { rootDir: root })) roles.add(r);
+      } catch { /* skip malformed */ }
     }
-  } catch { /* no profiles dir */ }
+  } catch { /* no scopes dir */ }
   return roles;
 }
 
@@ -96,19 +95,20 @@ function verificationHooks(meta, body) {
 }
 
 function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
+  if (skillId.startsWith('brand/')) return ['cx-docs-keeper'];
   const owners = new Set();
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
   }
   const base = roleBase(skillId);
   if (base && ownerBases.has(base)) {
-    for (const agent of registry.specialists ?? []) {
+    for (const agent of Object.values(registry.specialists ?? {})) {
       if (agent.name === base || agent.name.replace(/^cx-/, '') === base) owners.add(`cx-${agent.name}`);
     }
-    if (!owners.size) owners.add(`profile-role:${base}`);
+    if (!owners.size) owners.add(`scope-role:${base}`);
   }
   if (declaredSkills.has(skillId) && owners.size === 0) {
-    for (const agent of registry.specialists ?? []) {
+    for (const agent of Object.values(registry.specialists ?? {})) {
       if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
     }
   }
@@ -138,10 +138,11 @@ function detectConflictingOutputs(skills) {
   for (const [artifactType, entries] of byType) {
     if (entries.length < 2) continue;
     const bars = new Set(entries.map((e) => e.verificationHooks.find((h) => h.kind === 'verificationBar')?.value ?? ''));
+    if (bars.size <= 1) continue;
     conflicts.push({
       artifactType,
       skillIds: entries.map((e) => e.id),
-      reason: bars.size > 1 ? 'divergent verificationBar across workflow skills' : 'multiple workflow skills claim the same manifest artifact type',
+      reason: 'divergent verificationBar across workflow skills',
     });
   }
   return conflicts;
@@ -154,15 +155,15 @@ export function defaultSkillInventoryPath(rootDir = process.cwd()) {
 export function buildSkillInventory({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
   const skillsDir = path.join(root, 'skills');
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const registry = loadRegistry({ rootDir: root });
   const manifest = loadArtifactManifest({ rootDir: root });
   const declaredSkills = new Set();
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     for (const skill of agent.skills ?? []) declaredSkills.add(skill);
   }
   const ownerBases = new Set([
-    ...(registry.specialists ?? []).map((a) => a.name.replace(/^cx-/, '')),
-    ...collectProfileRoles(root),
+    ...Object.values(registry.specialists ?? {}).map((a) => a.name.replace(/^cx-/, '')),
+    ...collectScopeRoles(root),
   ]);
   const workflowIds = workflowSkillIds(manifest);
 
@@ -202,6 +203,14 @@ export function buildSkillInventory({ rootDir } = {}) {
     });
   }
 
+  const effectiveness = validateSkillEffectiveness({ rootDir: root });
+  const effectivenessFindings = effectiveness.errors.map((message) => ({
+    kind: 'effectiveness',
+    severity: 'blocking',
+    message,
+  }));
+  blockingFindings.push(...effectivenessFindings);
+
   const payload = {
     version: 1,
     generatedAt: new Date().toISOString(),
@@ -209,6 +218,7 @@ export function buildSkillInventory({ rootDir } = {}) {
     skillCount: skills.length,
     skills,
     blockingFindings,
+    effectivenessFindings,
     digest: null,
   };
   const canonical = { ...payload, digest: undefined };
@@ -238,7 +248,9 @@ export function validateSkillInventory({ rootDir, inventory: supplied, checkFres
   }
 
   for (const finding of inventory.blockingFindings ?? []) {
-    if (finding.severity === 'blocking') warnings.push(`blocking finding recorded: ${finding.kind} ${finding.skillId ?? finding.artifactType ?? ''}`.trim());
+    if (finding.severity === 'blocking') {
+      errors.push(`blocking finding: ${finding.kind} ${finding.skillId ?? finding.message ?? finding.artifactType ?? ''}`.trim());
+    }
   }
 
   if (checkFreshness) {

package/lib/certification/skill-scenarios.mjs

@@ -8,16 +8,19 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { validateSkillEffectiveness } from '../validators/skill-effectiveness.mjs';
+import { auditSkillComposition } from '../skills/composition-graph.mjs';
 import { defaultSkillInventoryPath } from './skill-inventory.mjs';
 import { defaultScenarioCatalogPath } from './scenarios.mjs';
 
-const HIGH_RISK_SKILLS = new Set([
-  'docs/prd-workflow',
-  'docs/product-intelligence-workflow',
-  'docs/evidence-ingest-workflow',
-  'quality-gates/verify-security',
-  'security/threat-intel',
-]);
+const HIGH_RISK_SKILLS = null;
+
+function highRiskSkillIds(root) {
+  if (HIGH_RISK_SKILLS) return HIGH_RISK_SKILLS;
+  const file = defaultSkillInventoryPath(root);
+  const inventory = JSON.parse(fs.readFileSync(file, 'utf8'));
+  return new Set((inventory.skills ?? []).filter((s) => s.workflowSkill).map((s) => s.id));
+}
 
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
@@ -50,6 +53,8 @@ export function buildPositiveScenario(skill) {
     verificationSteps: [
       'skill file exists under skills/',
       'inventory lists owners and workflowSkill=true',
+      'effectiveness rubric passes (lint:scopes)',
+      'get_skill and specialist refs resolve (composition graph)',
     ],
     owners: skill.owners ?? [],
   };
@@ -80,6 +85,14 @@ export function validateSkillScenarioFixture(fixture, { rootDir } = {}) {
   if (fixture.mode === 'positive' && !Array.isArray(fixture.verificationSteps)) {
     errors.push('positive fixture requires verificationSteps');
   }
+  if (fixture.mode === 'positive' && fixture.verificationSteps?.includes('effectiveness rubric passes (lint:scopes)')) {
+    const eff = validateSkillEffectiveness({ rootDir: root });
+    if (!eff.valid) errors.push(`effectiveness: ${eff.errors.find((e) => e.startsWith(fixture.skillId)) ?? eff.errors[0]}`);
+  }
+  if (fixture.mode === 'positive' && fixture.verificationSteps?.includes('get_skill and specialist refs resolve (composition graph)')) {
+    const comp = auditSkillComposition({ rootDir: root });
+    if (!comp.pass) errors.push(`composition: ${comp.blocking[0] ?? 'blocking'}`);
+  }
   if (fixture.mode === 'negative') {
     if (fixture.expected?.silentSuccess !== false) errors.push('negative fixture must forbid silent success');
     if (!fixture.expected?.errorType) errors.push('negative fixture requires expected.errorType');
@@ -121,7 +134,7 @@ export function writeSkillScenarioFixtures({ rootDir } = {}) {
       model: { provider: 'hermetic', requestedId: 'fixture/skill', resolvedId: 'fixture/skill', tier: 'hermetic' },
     });
     lines.push(`- \`${skill.id}\` — positive: \`${relPositive}\``);
-    if (HIGH_RISK_SKILLS.has(skill.id)) {
+    if (highRiskSkillIds(root).has(skill.id)) {
       const negative = buildNegativeScenario(skill);
       const negativePath = path.join(dir, 'negative.json');
       fs.writeFileSync(negativePath, `${JSON.stringify(negative, null, 2)}\n`);

package/lib/certification/specialist-contracts.mjs

@@ -6,6 +6,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 
 import { validatePromptContent } from '../specialists/prompt-schema.mjs';
@@ -13,7 +14,7 @@ import { validatePromptContent } from '../specialists/prompt-schema.mjs';
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -73,8 +74,8 @@ export function checkSpecialistContract(agent, { rootDir } = {}) {
 
 export function auditSpecialistContracts({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
-  const results = (registry.specialists ?? []).map((agent) => checkSpecialistContract(agent, { rootDir: root }));
+  const registry = loadRegistry({ rootDir: root });
+  const results = Object.values(registry.specialists ?? {}).map((agent) => checkSpecialistContract(agent, { rootDir: root }));
   const failures = results.filter((r) => !r.pass);
   return {
     pass: failures.length === 0,

package/lib/certification/specialist-scenarios.mjs

@@ -7,6 +7,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 
 import { roleCardsDir } from './role-cards.mjs';
@@ -16,7 +17,7 @@ import { defaultScenarioCatalogPath } from './scenarios.mjs';
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
   while (true) {
-    if (fs.existsSync(path.join(current, 'specialists', 'registry.json'))) return current;
+    if (fs.existsSync(path.join(current, 'specialists', 'org'))) return current;
     const parent = path.dirname(current);
     if (parent === current) return path.resolve(startPath);
     current = parent;
@@ -75,8 +76,8 @@ export function validateSpecialistScenarioFixture(fixture, { rootDir } = {}) {
   if (!fixture?.capabilityId) errors.push('capabilityId required');
   if (!['normal', 'adversarial'].includes(fixture.mode)) errors.push('mode must be normal or adversarial');
 
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
-  const agent = (registry.specialists ?? []).find((entry) => `cx-${entry.name}` === fixture.specialistId);
+  const registry = loadRegistry({ rootDir: root });
+  const agent = Object.values(registry.specialists ?? {}).find((entry) => `cx-${entry.name}` === fixture.specialistId);
   if (!agent) errors.push(`unknown specialist: ${fixture.specialistId}`);
 
   const cardPath = path.join(roleCardsDir(root), `${fixture.specialistId}.role-card.json`);
@@ -110,7 +111,7 @@ export function validateSpecialistScenarioFixture(fixture, { rootDir } = {}) {
 
 export function writeSpecialistScenarioFixtures({ rootDir } = {}) {
   const root = findConstructRoot(rootDir);
-  const registry = JSON.parse(fs.readFileSync(path.join(root, 'specialists', 'registry.json'), 'utf8'));
+  const registry = loadRegistry({ rootDir: root });
   const readme = path.join(root, 'tests', 'certification', 'scenarios', 'specialists', 'README.md');
   fs.mkdirSync(path.dirname(readme), { recursive: true });
   const lines = [
@@ -127,7 +128,7 @@ export function writeSpecialistScenarioFixtures({ rootDir } = {}) {
   ];
   const catalogEntries = [];
 
-  for (const agent of registry.specialists ?? []) {
+  for (const agent of Object.values(registry.specialists ?? {})) {
     const specialistId = `cx-${agent.name}`;
     const cardPath = path.join(roleCardsDir(root), `${specialistId}.role-card.json`);
     if (!fs.existsSync(cardPath)) continue;
@@ -171,5 +172,5 @@ export function writeSpecialistScenarioFixtures({ rootDir } = {}) {
     && !String(s.id).startsWith('specialist.adversarial.'));
   catalog.scenarios = [...keep, ...catalogEntries];
   fs.writeFileSync(catalogPath, `${JSON.stringify(catalog, null, 2)}\n`);
-  return { specialistCount: (registry.specialists ?? []).length, catalogEntries: catalogEntries.length, readme };
+  return { specialistCount: Object.values(registry.specialists ?? {}).length, catalogEntries: catalogEntries.length, readme };
 }

package/lib/certification/status.mjs

@@ -6,6 +6,7 @@
  */
 
 import fs from 'node:fs';
+import { loadRegistry } from '../registry/loader.mjs';
 import path from 'node:path';
 
 import { loadCapabilityLedger } from '../capability-ledger.mjs';
@@ -28,13 +29,13 @@ function findConstructRoot(startPath = process.cwd()) {
 }
 
 function readRegistry(rootDir) {
-  const file = path.join(rootDir, 'specialists', 'registry.json');
-  if (!fs.existsSync(file)) return { specialists: [] };
-  return JSON.parse(fs.readFileSync(file, 'utf8'));
+  const dir = path.join(rootDir, 'specialists', 'org');
+  if (!fs.existsSync(dir)) return { specialists: [] };
+  return loadRegistry({ rootDir });
 }
 
 function listSpecialists(registry) {
-  return registry.specialists ?? [];
+  return Object.values(registry.specialists ?? {});
 }
 
 function normalizeStatus({ verdict = null, stale = false, neverRun = true }) {

package/lib/cli-commands.mjs

@@ -4,7 +4,6 @@
  * Consumed by:
  *   - bin/construct         (usage text + emoji output)
  *   - lib/completions.mjs   (bash + zsh completion generation)
- *   - lib/server/index.mjs  (/api/status → dashboard)
  *
  * Command Visibility:
  *   - core: true → shown in default --help (90% of users)
@@ -13,6 +12,8 @@
  */
 
 import { resolveColors } from './term-format.mjs';
+import { resolveUiColors } from './ui/theme.mjs';
+import { formatPathLink, terminalLinksEnabled } from './ui/links.mjs';
 import { surfaceForCommand } from './registry/surface-map.mjs';
 
 export const CLI_COMMANDS = [
@@ -23,26 +24,14 @@ export const CLI_COMMANDS = [
     category: 'Core',
     core: true,
     description: 'Start services for development',
-    usage: 'construct dev [--select] [--only=postgres,dashboard,...]',
+    usage: 'construct dev [--select] [--only=postgres,...]',
     examples: [
       { cmd: 'construct dev', desc: 'Start the default service set' },
-      { cmd: 'construct dev --only=dashboard', desc: 'Start just the dashboard' },
+      { cmd: 'construct dev --only=postgres', desc: 'Start just Postgres' },
     ],
     options: [
       { flag: '--select', desc: 'Pick which services to start from an interactive checklist' },
-      { flag: '--only=<a,b,c>', desc: 'Start only the named services (postgres, dashboard, telemetry, memory, opencode)' },
-    ],
-  },
-  {
-    name: 'dashboard',
-    emoji: '📊',
-    category: 'Core',
-    core: true,
-    description: 'Start the local dashboard/orchestration daemon (or --token to mint a dashboard token)',
-    usage: 'construct dashboard [--token]',
-    examples: [
-      { cmd: 'construct dashboard', desc: 'Launch the local dashboard daemon' },
-      { cmd: 'construct dashboard --token', desc: 'Mint a dashboard access token' },
+      { flag: '--only=<a,b,c>', desc: 'Start only the named services (postgres, telemetry, memory, opencode)' },
     ],
   },
   {
@@ -230,24 +219,24 @@ export const CLI_COMMANDS = [
     ],
   },
   {
-    name: 'profile',
+    name: 'scope',
     emoji: '🧭',
     category: 'Core',
     core: true,
-    description: 'Manage the active org profile and its lifecycle (draft, promote, archive, health)',
-    usage: 'construct profile show|list|set|create|drafts|archive|health',
+    description: 'Manage the active org scope and its lifecycle (draft, promote, archive, health)',
+    usage: 'construct scope show|list|set|create|drafts|archive|health',
     examples: [
-      { cmd: 'construct profile list', desc: 'List curated profiles' },
-      { cmd: 'construct profile set <id>', desc: 'Switch the active profile' },
+      { cmd: 'construct scope list', desc: 'List curated scopes' },
+      { cmd: 'construct scope set <id>', desc: 'Switch the active scope' },
     ],
     subcommands: [
-      { 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=…] [--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' },
+      { name: 'show', desc: 'Show the active scope' },
+      { name: 'list', desc: 'List curated scopes' },
+      { name: 'set <id>', desc: 'Switch the active scope (writes construct.config.json)' },
+      { name: 'create <id> [--display=…] [--role=…] [--department=…] [--yes|--dry-run]', desc: 'Scaffold a draft scope; previews and confirms by default, prompts interactively when no flags' },
+      { name: 'drafts', desc: 'List in-progress draft scopes' },
+      { name: 'archive <id> --reason="..."', desc: 'Move a curated scope into archive/scopes/<id>/' },
+      { name: 'health <id> [--days=N]', desc: 'Per-scope observation + outcome rollup' },
     ],
   },
   {
@@ -354,7 +343,7 @@ export const CLI_COMMANDS = [
       { flag: '--output=<path>', desc: 'Output path (default: .cx/publish/<name>.<format>)' },
       { flag: '--type=<doc-type>', desc: 'Manifest doc type for release gate (inferred when omitted)' },
       { flag: '--demo=<name>', desc: 'Terminal VHS tape to record (repeatable)' },
-      { flag: '--dashboard-demo=<name>', desc: 'Playwright demo spec basename (repeatable)' },
+      { flag: '--recording=<name>', desc: 'Playwright recording manifest (repeatable)' },
       { flag: '--figures', desc: 'Render d2/mermaid via diagram filter (default on)' },
       { flag: '--no-figures', desc: 'Skip diagram filter' },
       { flag: '--no-gate', desc: 'Skip artifact release gate (escape hatch only)' },
@@ -377,7 +366,6 @@ export const CLI_COMMANDS = [
       { flag: '--figures', desc: 'Include figure tooling (default on)' },
       { flag: '--no-figures', desc: 'Skip figure binaries' },
       { flag: '--demo=<name>', desc: 'Include terminal demo recorder check' },
-      { flag: '--dashboard-demo=<name>', desc: 'Include dashboard Playwright check' },
     ],
   },
   {
@@ -429,14 +417,12 @@ export const CLI_COMMANDS = [
     category: 'Models & Integrations',
     core: false,
     description: 'Show or update model tier assignments',
-    usage: 'construct models <list|set|free|reset|usage|cost|resolve>',
+    usage: 'construct models <list|set|free|reset|resolve>',
     subcommands: [
       { name: 'list', desc: 'Show current tier assignments' },
       { name: 'set --tier=<reasoning|standard|fast> --model=<model>', desc: 'Set a model for a tier' },
       { name: 'free', desc: 'List available free models' },
       { name: 'reset', desc: 'Reset all tier assignments' },
-      { name: 'usage', desc: 'Show token usage per tier' },
-      { name: 'cost', desc: 'Show cost breakdown' },
       { name: 'resolve --json', desc: 'Resolve the model for an embedded workflow given host context' },
     ],
   },
@@ -482,14 +468,6 @@ export const CLI_COMMANDS = [
     description: 'Run Construct as an Agent Client Protocol (ACP) server over stdio for Zed/JetBrains/VS Code ACP clients',
     usage: 'construct acp',
   },
-  {
-    name: 'chat',
-    emoji: '💬',
-    category: 'Models & Integrations',
-    core: false,
-    description: "Interactive terminal chat on Construct's owned agent loop, with a multi-pane transparency surface (live token/cost/context usage, reasoning, tool timeline, and the planned specialist route); switch models, change settings, and see a token/cost breakdown in-session. Use --accessible or --plain for the linear, screen-reader-friendly renderer",
-    usage: 'construct chat [--model <id>] [--free] [--web] [--list] [--resume[=file]] [--ascii] [--plain] [--accessible] [--no-thinking] [--no-path] [--no-specialists] [--no-tools] [--no-observability] [--quiet]',
-  },
   {
     name: 'mcp',
     emoji: '🔌',
@@ -596,7 +574,7 @@ export const CLI_COMMANDS = [
     emoji: '🔁',
     category: 'Observability',
     core: false,
-    surface: 'dashboard',
+    surface: 'thin-cli',
     description: 'Governed improvement loop — review, approve, and record apply/rollback for proposals',
     usage: 'construct improvement submit|review|pending|show|approve|apply|rollback|list',
   },
@@ -621,8 +599,14 @@ export const CLI_COMMANDS = [
     emoji: '👥',
     category: 'Work',
     core: false,
-    description: 'Team review and template listing',
-    usage: 'construct team <list|review>',
+    description: 'Team review and template listing (`team:add` / `team:remove` are internal registry editors)',
+    usage: 'construct team <list|show|review|templates>',
+    subcommands: [
+      { name: 'list', desc: 'List macro groups and squads (--kind group|squad)' },
+      { name: 'show', desc: 'Show one group or squad by id' },
+      { name: 'review', desc: 'Team review workflow' },
+      { name: 'templates', desc: 'List team doc templates' },
+    ],
   },
   {
     name: 'audit',
@@ -688,7 +672,7 @@ export const CLI_COMMANDS = [
     emoji: '🪞',
     category: 'Work',
     core: false,
-    description: 'Capture improvement feedback from chat session and update Construct core',
+    description: 'Capture improvement feedback and update Construct core',
     usage: 'construct reflect',
   },
   {
@@ -736,18 +720,17 @@ export const CLI_COMMANDS = [
     emoji: '🎬',
     category: 'Work',
     core: false,
-    description: 'Run guided demos via construct chat (default) or record VHS/asciinema tapes',
-    usage: 'construct demo <list|init|record|name> [--surface=chat|web|tape|dashboard] [--format=gif|mp4|webm] [--out=<path>] [--source-only]',
+    description: 'Run guided tours or record VHS/asciinema tapes',
+    usage: 'construct demo <list|init|record|tour|name> [--surface=tape|playwright] [--format=gif|mp4|webm] [--out=<path>] [--source-only]',
     strictFlags: true,
     options: [
-      { flag: '--surface=<s>', desc: 'chat (default) | web | tape | dashboard' },
-      { flag: '--model=<id>', desc: 'Pin model for chat demo' },
-      { flag: '--web', desc: 'Open web chat (/chat/) instead of terminal Ink' },
-      { flag: '--plain', desc: 'Linear chat renderer (accessibility / non-TTY)' },
-      { flag: '--free', desc: 'OpenRouter free-router mode for chat demo' },
+      { flag: '--surface=<s>', desc: 'tape (default) | playwright' },
+      { flag: '--accessible', desc: 'Screen-reader-friendly linear tour renderer' },
+      { flag: '--skip-input', desc: 'Tour: auto-advance without waiting for Enter (headless/CI)' },
       { flag: '--format=<f>',  desc: 'gif (default) | mp4 | webm (tape surface only)' },
       { flag: '--out=<path>',  desc: 'Output path (tape recording)' },
       { flag: '--from=<t>',    desc: 'Template for init: quickstart | diagram' },
+      { flag: '--from-project', desc: 'init: scaffold a project demo plug-in under .cx/demos/' },
       { flag: '--source-only', desc: 'Tape: write .tape only; skip recording' },
     ],
   },
@@ -890,7 +873,13 @@ export const CLI_COMMANDS = [
     category: 'Advanced',
     core: false,
     description: 'Skill relevance detection',
-    usage: 'construct skills scope|apply',
+    usage: 'construct skills <scope|apply|suggest|routing>',
+    subcommands: [
+      { name: 'scope', desc: 'Show skill scope for the active profile' },
+      { name: 'apply', desc: 'Apply skill profile to host config' },
+      { name: 'suggest', desc: 'Rank skills for an intent string' },
+      { name: 'routing', desc: 'Dump machine-readable routing table' },
+    ],
   },
   {
     name: 'hooks:health',
@@ -1135,7 +1124,6 @@ export const CLI_COMMANDS = [
   { name: 'hook',              category: 'Internal', core: false, internal: true, description: 'Hook dispatch — invoked by the harness, not by users', usage: 'construct hook <event>' },
   { name: 'seed-traces',       category: 'Internal', core: false, internal: true, description: 'Dev fixture: seed traces for testing', usage: 'construct seed-traces' },
   { name: 'migrate',           category: 'Internal', core: false, internal: true, description: 'Internal: run pending storage migrations', usage: 'construct migrate' },
-  { name: 'dashboard:sync',    category: 'Internal', core: false, internal: true, description: 'Internal: refresh dashboard state from the registry', usage: 'construct dashboard:sync' },
   { name: 'init:update',       category: 'Internal', core: false, internal: true, description: 'Internal: re-run init scaffolding for an existing project', usage: 'construct init:update' },
   { name: 'lint:agents',       category: 'Internal', core: false, internal: true, description: 'Internal lint: agent definitions', usage: 'construct lint:agents' },
   { name: 'lint:comments',     category: 'Internal', core: false, internal: true, description: 'Internal lint: source comments', usage: 'construct lint:comments' },
@@ -1145,8 +1133,17 @@ export const CLI_COMMANDS = [
   { name: 'lint:prompts',      category: 'Internal', core: false, internal: true, description: 'Internal lint: specialist prompt frontmatter + sections', usage: 'construct lint:prompts' },
   { name: 'specialist',        category: 'Internal', core: false, internal: true, description: 'Maintainer tool: scaffold, edit, and lint specialist prompts', usage: 'construct specialist <create|edit|lint>' },
   { name: 'registry:status',   category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Dev: capability registry inspector', usage: 'construct registry:status [--json]' },
-  { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Validate registry/capabilities.json against repo reality', usage: 'construct registry:validate [--json]' },
+  { name: 'registry:validate', category: 'Internal', core: false, internal: true, surface: 'internal', strictFlags: true, description: 'Validate registry/capabilities.json against repo reality; --unified validates specialists/org (+ .cx overlay) invariants', usage: 'construct registry:validate [--json] [--unified]', options: [
+    { flag: '--json', desc: 'Emit the validation report as JSON' },
+    { flag: '--unified', desc: 'Validate the unified registry (specialists/org + optional .cx overlay) against its 13 invariants instead of the capability registry' },
+  ] },
   { name: 'registry:generate-docs', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Generate docs/guides/reference/capabilities.md from registry', usage: 'construct registry:generate-docs' },
+  { name: 'registry:diff',     category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Show unified registry changes vs. last commit', usage: 'construct registry:diff [--json]' },
+  { name: 'registry:prune',    category: 'Internal', core: false, internal: true, surface: 'internal', description: 'List orphaned specialist prompts and skills', usage: 'construct registry:prune [--json]' },
+  { name: 'team:add',          category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Add a new team to the unified registry', usage: 'construct team:add <team-id>' },
+  { name: 'team:remove',       category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Remove a team from the unified registry', usage: 'construct team:remove <team-id> [--force]' },
+  { name: 'specialist:add',    category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Add a new specialist to a team', usage: 'construct specialist:add <specialist-id> --team <team-id>' },
+  { name: 'specialist:remove', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Remove a specialist from the unified registry', usage: 'construct specialist:remove <specialist-id> [--force]' },
   { name: 'oracle', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Oracle meta-controller — fleet health review and bounded-auto maintenance', usage: 'construct oracle start|status|review|pending|approve|gaps|reconcile' },
   { name: 'matrix', category: 'Internal', core: false, internal: true, surface: 'internal', description: 'Living dependency matrix — build/inspect the typed file↔capability↔workflow↔test graph', usage: 'construct matrix build|stat|query <node-id> [--json]' },
   { name: 'impact', category: 'Diagnostics', core: false, internal: false, surface: 'thin-cli', description: 'Change-impact analysis — map changed files to affected tests, capabilities, and workflows', usage: 'construct impact [files…] [--stdin] [--run] [--json]' },
@@ -1222,7 +1219,8 @@ export function getCommandSpec(name) {
 // every command. Internal commands fall back to a minimal block.
 
 export function formatCommandHelp(name, { colors = false } = {}) {
-  const c = resolveColors({ enabled: colors });
+  const c = resolveUiColors({ enabled: colors });
+  const linksOn = terminalLinksEnabled(process.env);
   const spec = getCommandSpec(name);
   if (!spec) {
     return `Unknown command: ${name}\n\nRun 'construct --help' for available commands.\n`;
@@ -1271,7 +1269,8 @@ export function formatCommandHelp(name, { colors = false } = {}) {
     lines.push(`${c.dim}Next:${c.reset} ${next}`);
     lines.push('');
   }
-  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in docs/guides/reference/cli/.`);
+  const cliDocs = formatPathLink('docs/guides/reference/cli/', c, { enabled: linksOn });
+  lines.push(`${c.dim}See also:${c.reset} run \`construct --help\` for all commands; full reference in ${cliDocs}.`);
   lines.push('');
   return lines.join('\n');
 }

package/lib/comment-lint.mjs

@@ -93,10 +93,6 @@ function requiresHeader(rel) {
   if (['.yaml', '.yml', '.json', '.jsonl', '.toml', '.txt'].includes(ext)) return { required: false, type: null };
   const jsMatch = JS_HEADER_GLOBS.some(r => r.test(rel));
   const mdMatch = MD_HEADER_GLOBS.some(r => r.test(rel));
-  // Exclude static assets under lib/server/static from requiring headers
-  if (rel.startsWith('lib/server/static/')) {
-    return { required: false, type: null };
-  }
   // Exclude test fixture data files — these are project artifacts, not source files.
   if (rel.startsWith('tests/fixtures/projects/')
     || rel.startsWith('tests/fixtures/artifacts/')
@@ -324,7 +320,7 @@ function checkArtifactBanned(content, rel) {
 
 // Internal specialist role ids (cx-business-strategist, cx-product-manager, …) are
 // implementation detail; in a consuming project's deliverable they read as a tool-identity
-// leak. The set is anchored to the real role ids from specialists/registry.json — an
+// leak. The set is anchored to the real role ids from specialists/org — an
 // open-ended /cx-[a-z-]+/ also matches unrelated npm packages (cx-ray, cx-pro, cx-widget)
 // and would fail the release gate on legitimate user content. Drift from the registry is
 // caught by tests/tool-invisibility.test.mjs, not at runtime: this module sits on the hook

package/lib/completions.mjs

@@ -31,6 +31,7 @@ function subcommandDesc(subcommand) {
 
 function buildBash() {
   const names = CLI_COMMANDS.map(c => c.name).join(' ');
+  const globalFlags = '--help -h --all -a --version -V';
 
   const subcommandCases = CLI_COMMANDS
     .filter(c => c.subcommands?.length)
@@ -68,15 +69,28 @@ _construct_completions() {
   }
 
   local commands="${names}"
+  local global_flags="${globalFlags}"
 
-  # First argument: complete command names
+  # First argument: subcommand names or global flags
   if [[ $cword -eq 1 ]]; then
-    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=($(compgen -W "$global_flags" -- "$cur"))
+    else
+      COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    fi
     return 0
   fi
 
   local cmd="\${words[1]}"
 
+  # Global flag continuation
+  if [[ "$cmd" == -* ]]; then
+    if [[ "$cur" == -* ]]; then
+      COMPREPLY=($(compgen -W "$global_flags" -- "$cur"))
+      return 0
+    fi
+  fi
+
   # Subcommands
   if [[ $cword -eq 2 ]]; then
     case "$cmd" in
@@ -100,6 +114,9 @@ complete -F _construct_completions construct
 }
 
 function buildZsh() {
+  const globalFlagDescriptions = ['--help', '-h', '--all', '-a', '--version', '-V']
+    .map((f) => `    '${f}:global flag' \\`)
+    .join('\n');
   const commandDescriptions = CLI_COMMANDS
     .map(c => `    '${c.name}:${c.emoji || ''} ${(c.description || '').replace(/'/g, "\\'")}' \\`)
     .join('\n');
@@ -140,6 +157,7 @@ ${subcommandFunctions}
 _construct_commands() {
   local commands
   commands=(
+${globalFlagDescriptions}
 ${commandDescriptions}
   )
   _describe -t commands 'construct command' commands