@geraldmaron/construct 1.0.11 → 1.0.12

package/README.md

@@ -2,7 +2,7 @@
 
 **One AI interface. A team of specialists behind it. Hard gates. Runs locally, or deploys for teams.**
 
-📖 **[Read the docs →](https://geraldmaron.github.io/construct/)** · 🚀 **[5-minute quickstart →](https://geraldmaron.github.io/construct/docs/start)** · 📦 `npm install -g @geraldmaron/construct`
+📖 **[Read the docs →](https://geraldmaron.github.io/construct/)** · 🚀 **[5-minute quickstart →](https://geraldmaron.github.io/construct/start)** · 📦 `npm install -g @geraldmaron/construct`
 
 ---
 
@@ -10,7 +10,7 @@
 
 Construct sits on top of Claude Code, OpenCode, Codex, Cursor, and Copilot. You talk to one persona called `construct`. Behind it is a team of specialists shaped by your **org profile**: software R&D by default, with curated profiles for operations, creative, and research orgs, plus a schema-validated escape hatch for custom profiles. Each profile organizes its specialists by department (Product, Engineering, Operations, etc.) and carries its own intake taxonomy, doc templates, and role set. Sessions survive boundary changes via durable state in `.cx/`, beads, and a local vector index. Solo by default. Can deploy centrally for teams that want shared memory, telemetry, queues, and policy.
 
-`construct profile show|list|set <id>` to switch. See [Profile lifecycle](https://geraldmaron.github.io/construct/docs/concepts/profile-lifecycle) for how new profiles are built (it's a research process, not a JSON exercise).
+`construct profile show|list|set <id>` to switch. See [Profile lifecycle](https://geraldmaron.github.io/construct/concepts/profile-lifecycle) for how new profiles are built (it's a research process, not a JSON exercise).
 
 The team and enterprise modes exist because I wanted to learn what shipping a real multi-tenant tool would look like. The project is still open source, the code is still public, and the bar is still "does this help me learn." Run it solo if that's all you need.
 
@@ -39,20 +39,33 @@ Open your editor and talk to `@construct`. A walkthrough lives in `construct_gui
 
 No Node? Try `brew install geraldmaron/construct/construct`. Cloning a project that already uses Construct? `npx -y @geraldmaron/construct init` wires it up.
 
-[Five minute walkthrough](https://geraldmaron.github.io/construct/docs/start).
+[Five minute walkthrough](https://geraldmaron.github.io/construct/start).
+
+## Usage
+
+Most days, the loop is:
+
+```bash
+construct status          # confirm services and editor adapters are healthy
+construct sync            # refresh host adapters after registry, prompt, or config changes
+construct intake list     # review new signals, if your project uses the inbox
+construct doctor          # diagnose install, service, MCP, and adapter drift
+```
+
+In your editor, start with `@construct`. Ask for the outcome, not the specialist. Construct routes to the right specialist chain, keeps durable state in `.cx/` and Beads, and blocks risky mutations until the configured gates pass.
 
 ## What you can do
 
 | If you want to... | Read |
 |---|---|
-| Install and run a first task | [Start](https://geraldmaron.github.io/construct/docs/start) |
-| Understand how it works | [Architecture](https://geraldmaron.github.io/construct/docs/concepts/architecture) |
-| Pick a deployment mode | [Deployment model](https://geraldmaron.github.io/construct/docs/concepts/deployment-model) |
-| Drop a signal and triage it | [Intake and triage](https://geraldmaron.github.io/construct/docs/concepts/intake-and-triage) |
-| Add a custom specialist | [Add a custom agent](https://geraldmaron.github.io/construct/docs/cookbook/add-a-custom-agent) |
-| Fix a blocked commit or red CI | [Fix a policy violation](https://geraldmaron.github.io/construct/docs/cookbook/fix-a-policy-violation) |
-| Plug in your own LLM | [Plug in your own LLM](https://geraldmaron.github.io/construct/docs/cookbook/plug-in-your-own-llm) |
-| Look up a CLI command | [CLI reference](https://geraldmaron.github.io/construct/docs/reference/cli) |
+| Install and run a first task | [Start](https://geraldmaron.github.io/construct/start) |
+| Understand how it works | [Architecture](https://geraldmaron.github.io/construct/concepts/architecture) |
+| Pick a deployment mode | [Deployment model](https://geraldmaron.github.io/construct/concepts/deployment-model) |
+| Drop a signal and triage it | [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage) |
+| Add a custom specialist | [Add a custom specialist](https://geraldmaron.github.io/construct/cookbook/add-a-custom-agent) |
+| Fix a blocked commit or red CI | [Fix a policy violation](https://geraldmaron.github.io/construct/cookbook/fix-a-policy-violation) |
+| Plug in your own LLM | [Plug in your own LLM](https://geraldmaron.github.io/construct/cookbook/plug-in-your-own-llm) |
+| Look up a CLI command | [CLI reference](https://geraldmaron.github.io/construct/reference/cli) |
 
 Works with Anthropic, OpenRouter, Ollama, and other OpenAI-compatible providers.
 
@@ -64,21 +77,21 @@ Three modes. `solo` is the default and runs everything locally. Filesystem queue
 
 `enterprise` adds tenant isolation, RBAC and ABAC scaffolding, isolated worker containers, signed MCP allowlists, and mandatory audit.
 
-Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deployment model](https://geraldmaron.github.io/construct/docs/concepts/deployment-model).
+Pick or change modes with `construct config mode [solo|team|enterprise]`. [Deployment model](https://geraldmaron.github.io/construct/concepts/deployment-model).
 
 ## Intake
 
 Anything dropped into `.cx/inbox/` (a bug report, a customer comment, a competitor PDF, a postmortem draft) is classified by the active profile's intake taxonomy. The default `rnd` profile uses bug, user-signal, experiment, architecture, incident, security, requirement, research, ops, eval-finding, launch-asset, legal-compliance. The `operations` profile uses request, incident, ops, security, docs. The `creative` profile uses brief, content-request, asset, experiment, report. The `research` profile uses question, study, synthesis, report.
 
-Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/docs/concepts/intake-and-triage).
+Each signal gets a primary owner and a recommended handoff chain. Inspect with `construct intake list` and `construct intake show <id>`. Generate a task graph with `construct graph from-intake <id>`. The classifier runs in the daemon and is deterministic. The agent in your editor does the actual analysis. [Intake and triage](https://geraldmaron.github.io/construct/concepts/intake-and-triage).
 
 ## Hard gates
 
-Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/docs/concepts/gates-and-enforcement).
+Every code mutation runs through enforcement. No secrets committed, tests green, docs current, comments lint-clean, CI passes. Gates live in three places: write-time, commit-time, CI safety net. They can only be bypassed with explicit env vars so every exception leaves an audit trail. [Gates and enforcement](https://geraldmaron.github.io/construct/concepts/gates-and-enforcement).
 
 ## Learning loops
 
-Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.md`](./docs/concepts/learning-loops.md) for what's wired, what's coming, and how to turn pieces off.
+Construct gets smarter on its own. Every session ends with an automatic capture: tools used, files touched, what the final reply said. That goes into `.cx/observations/` and is searchable from the next session. See [`docs/concepts/learning-loops.mdx`](./docs/concepts/learning-loops.mdx) for what's wired, what's coming, and how to turn pieces off.
 
 ## Core commands
 
@@ -124,6 +137,16 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 | `construct workflow` | Instantiate workflow templates (PRD-to-review chains, onboarding, handoffs) |
 | `construct workspace` | Manage PM workspaces for multi-PM signal routing |
 
+### Models & Integrations
+
+| Command | What it does |
+|---|---|
+| `construct claude:allow` | Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it) |
+| `construct hosts` | Show host support for Construct orchestration |
+| `construct mcp` | Manage MCP integrations |
+| `construct models` | Show or update model tier assignments |
+| `construct plugin` | Manage external Construct plugin manifests |
+
 ### Integrations
 
 | Command | What it does |
@@ -145,6 +168,14 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 | `construct telemetry` | Query telemetry traces and latency data |
 | `construct telemetry-backfill` | Backfill sparse traces with observations (trace backend) |
 
+### Diagnostics
+
+| Command | What it does |
+|---|---|
+| `construct audit` | Audit Construct internals and review the mutation trail |
+| `construct cleanup` | Release dev-agent memory pressure by cleaning stale helper and bridge processes |
+| `construct doc` | Verify or inspect auditability stamps on Construct-generated markdown files |
+
 ### Advanced
 
 | Command | What it does |
@@ -176,7 +207,7 @@ Construct gets smarter on its own. Every session ends with an automatic capture:
 
 - [`CONTRIBUTING.md`](./CONTRIBUTING.md). Branch workflow, gates, review expectations.
 - [`CHANGELOG.md`](./CHANGELOG.md). Release history.
-- [`docs/concepts/architecture.md`](./docs/concepts/architecture.md). Canonical architecture.
+- [`docs/concepts/architecture.mdx`](./docs/concepts/architecture.mdx). Canonical architecture.
 - [`AGENTS.md`](./AGENTS.md). Agent operating contract.
 
 ## Project structure

package/lib/auto-docs.mjs

@@ -1,5 +1,5 @@
 /**
- * lib/auto-docs.mjs — regenerate managed regions in markdown docs and build the MkDocs site tree.
+ * lib/auto-docs.mjs — regenerate managed regions in markdown docs and generated docs-site references.
  *
  * Managed regions are HTML comment markers in the form:
  *   <!-- AUTO:region-name -->
@@ -9,8 +9,8 @@
  * Running regenerateDocs() is idempotent. With check:true it returns whether
  * anything would change without writing files — the mode CI uses to detect drift.
  *
- * buildSite() writes site/docs/ from the same sources feeding the AUTO regions
- * so the GitHub Pages site never drifts from the in-repo markdown.
+ * buildSite() is retained for compatibility; the public site now renders docs/
+ * directly through Fumadocs and buildFumadocsReference() emits generated pages.
  */
 
 import fs from 'node:fs';
@@ -93,7 +93,7 @@ const DIR_DESCRIPTIONS = {
   opencode: 'OpenCode integration config',
   personas: 'Persona prompt definitions',
   rules: 'Coding and quality standards',
-  site: 'MkDocs source for the GitHub Pages documentation site',
+  site: 'Legacy docs-site output',
   skills: 'Reusable domain knowledge files',
   tests: 'Test suite',
 };
@@ -237,12 +237,12 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
  * Check CLI command coverage against how-to links in docs/README.md.
  *
  * Returns an object with:
- *   - covered: string[]    commands that have a linked how-to
- *   - uncovered: string[]  commands with no how-to link in docs/README.md
+ *   - covered: string[]    commands that have a linked guide
+ *   - uncovered: string[]  commands with no linked guide in docs/README.md
  *   - total: number
  *
- * A command is considered covered if its name appears in any markdown link
- * inside the how-to guides section of docs/README.md.
+ * A command is considered covered if its name appears in docs/README.md or in
+ * a linked cookbook/how-to guide.
  */
 export function checkDocsCoverage({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();
@@ -251,11 +251,10 @@ export function checkDocsCoverage({ rootDir } = {}) {
   // Extract all href targets from markdown links in docs/README.md
   const linkTargets = [...docsReadme.matchAll(/\[.*?\]\((.*?)\)/g)].map(m => m[1]);
 
-  // Build a combined corpus: docs/README.md + every linked how-to file
-  const howToDir = path.join(rootDir, 'docs', 'how-to');
+  // Build a combined corpus: docs/README.md + every linked guide file
   let corpus = docsReadme;
   for (const target of linkTargets) {
-    if (!target.startsWith('./how-to/')) continue;
+    if (!target.startsWith('./how-to/') && !target.startsWith('./cookbook/')) continue;
     const filePath = path.join(rootDir, 'docs', target.replace(/^\.\//, ''));
     const content = readFile(filePath);
     if (content) corpus += '\n' + content;
@@ -307,15 +306,13 @@ export function checkDocsCoverage({ rootDir } = {}) {
 // Categories surfaced in the Fumadocs reference. Internal commands (e.g.,
 // `construct hook <name>`) are not user-facing reference material.
 const REFERENCE_CATEGORIES = [
-  'Services',
-  'Agents & Sync',
+  'Core',
   'Work',
-  'Embed',
   'Models & Integrations',
-  'Providers',
+  'Integrations',
   'Observability',
-  'Docs',
   'Diagnostics',
+  'Advanced',
 ];
 
 function slugify(category) {

package/lib/cli-commands.mjs

@@ -749,8 +749,10 @@ for (const cat of Object.keys(CLI_COMMANDS_BY_CATEGORY)) {
 export const CATEGORY_ORDER = [
   'Core',
   'Work',
+  'Models & Integrations',
   'Integrations',
   'Observability',
+  'Diagnostics',
   'Advanced',
 ];
 

package/lib/hooks/registry-sync.mjs

@@ -2,7 +2,7 @@
 /**
  * lib/hooks/registry-sync.mjs — Registry sync hook — reminds to run construct sync after registry changes.
  *
- * Runs as PostToolUse after edits to agents/registry.json. Checks if the file was modified and emits a reminder to run construct sync to regenerate platform adapters.
+ * Runs as PostToolUse after edits to specialists/registry.json. Checks if the file was modified and emits a reminder to run construct sync to regenerate platform adapters.
  *
  * @p95ms 12000
  * @maxBlockingScope none (PostToolUse, non-blocking)

package/lib/sync/skill-frontmatter.mjs

@@ -0,0 +1,71 @@
+/**
+ * lib/sync/skill-frontmatter.mjs — Build Anthropic Agent Skills frontmatter
+ * for SKILL.md files emitted by sync-specialists.
+ *
+ * Anthropic Skills require YAML frontmatter with at minimum `name` and
+ * `description`. The description gates skill selection — without it, the
+ * loader silently skips the file (the user-reported bug: 141 files dropped).
+ * Source Construct skills carry an HTML comment header with the description;
+ * extractSkillDescription pulls it out.
+ *
+ * Also exports a conservative stripLeadingFrontmatter helper so we never
+ * emit double-frontmatter when the source body already has its own block.
+ */
+
+const HTML_COMMENT_RE = /^<!--([\s\S]*?)-->/;
+// Matches the source skill comment header shape: `skills/path/foo.md (Title)
+// Use when X.\n...rest of comment...`. Group 1 captures the optional title,
+// group 2 captures all subsequent prose inside the comment. No /m flag — `$`
+// matches end of input, not end of line, so multi-line "Use when..." prose
+// is captured in full and firstSentence() picks the first terminator.
+
+const SOURCE_HEADER_RE = /^skills\/[\w./-]+\s*(?:\(([^)]+)\))?\s*([\s\S]*?)$/;
+
+// Anthropic Skills cap descriptions at 1024 chars; this cap is tighter so
+// the YAML stays readable in `construct skills list` output too.
+const DESCRIPTION_MAX = 240;
+
+export function buildSkillFrontmatter(name, sourceContent) {
+  const skillName = String(name).replace(/\//g, '.');
+  const description = extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`;
+  const safeDescription = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'");
+  return `---\nname: ${skillName}\ndescription: "${safeDescription}"\n---\n`;
+}
+
+export function extractSkillDescription(content) {
+  if (!content) return null;
+  const commentMatch = content.match(HTML_COMMENT_RE);
+  if (commentMatch) {
+    const inner = commentMatch[1].trim();
+    const headerMatch = inner.match(SOURCE_HEADER_RE);
+    if (headerMatch) {
+      const prose = (headerMatch[2] || '').trim();
+      if (prose) return firstSentence(prose);
+    }
+    const lines = inner.split('\n').map((l) => l.trim()).filter(Boolean);
+    if (lines.length >= 2) return firstSentence(lines.slice(1).join(' '));
+  }
+  const body = content.replace(HTML_COMMENT_RE, '').trim();
+  const paragraphs = body.split(/\n\s*\n/);
+  for (const p of paragraphs) {
+    const trimmed = p.trim();
+    if (trimmed.startsWith('#')) continue;
+    if (trimmed) return firstSentence(trimmed);
+  }
+  return null;
+}
+
+function firstSentence(text) {
+  const match = text.match(/^[\s\S]*?[.!?](?:\s|$)/);
+  return (match ? match[0] : text).trim();
+}
+
+export function stripLeadingFrontmatter(content) {
+  if (!content) return content;
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) return content;
+  const closeIdx = content.indexOf('\n---', 4);
+  if (closeIdx === -1) return content;
+  const afterClose = content.indexOf('\n', closeIdx + 1);
+  if (afterClose === -1) return '';
+  return content.slice(afterClose + 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {

package/scripts/sync-specialists.mjs

@@ -41,6 +41,7 @@ import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs
 import { resolveActiveProfile } from "../lib/profiles/loader.mjs";
 import { resolveTiersForPrimary } from "../lib/model-router.mjs";
 import { stampFrontmatter } from "../lib/doc-stamp.mjs";
+import { buildSkillFrontmatter, stripLeadingFrontmatter } from "../lib/sync/skill-frontmatter.mjs";
 
 const home = os.homedir();
 const root = path.resolve(import.meta.dirname, "..");
@@ -180,9 +181,18 @@ function releaseLock() {
  */
 const _stagedPairs = []; // [{ staging, real, content }]
 
-function writeFile(file, content) {
+function writeFile(file, content, { stamp = true } = {}) {
   mkdirp(path.dirname(file));
-  const stamped = file.endsWith('.md') ? stampFrontmatter(content, { generator: 'construct/sync-specialists' }) : content;
+  // Doc-stamp wraps content with cx_doc_id + body_hash YAML frontmatter for
+  // tamper detection. That's right for content artifacts (research findings,
+  // knowledge files), wrong for host-platform adapter files that have their
+  // own frontmatter contract (Claude Code agents, Copilot prompts, Anthropic
+  // Agent Skills) or are user-managed (CLAUDE.md, copilot-instructions.md).
+  // Stamping those produces double-frontmatter that breaks the host loader.
+  // Callers writing those files pass { stamp: false }.
+
+  const shouldStamp = stamp && file.endsWith('.md');
+  const stamped = shouldStamp ? stampFrontmatter(content, { generator: 'construct/sync-specialists' }) : content;
 
   if (DRY_RUN) {
     // Stage in memory only — compare against current on-disk content.
@@ -641,7 +651,7 @@ function syncClaude(entries, targetDir = null) {
   for (const entry of entries) {
     const name = adapterName(entry);
     const md = claudeAgentMarkdown(entry, entries);
-    writeFile(path.join(claudeAgentsDir, `${name}.md`), md);
+    writeFile(path.join(claudeAgentsDir, `${name}.md`), md, { stamp: false });
   }
   removeStaleAdapters(claudeAgentsDir, ".md", entries);
 
@@ -663,7 +673,8 @@ ${personaList}
 ## Internal Specialists
 
 ${specialistList || "(all specialists are internal — routed through Construct)"}`;
-    writeFile(claudeMdPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd));
+    // User-managed file with our managed-block carved out — never doc-stamp.
+    writeFile(claudeMdPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd), { stamp: false });
 
     // Sync MCP servers into ~/.claude/settings.json if it exists
     const claudeSettingsPath = path.join(home, ".claude", "settings.json");
@@ -797,7 +808,7 @@ function syncCopilot(entries) {
   const promptsDir = path.join(home, ".github", "prompts");
   if (!DRY_RUN) mkdirp(promptsDir);
   for (const entry of entries) {
-    writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries));
+    writeFile(path.join(promptsDir, `${adapterName(entry)}.prompt.md`), copilotPrompt(entry, entries), { stamp: false });
   }
   removeStaleAdapters(promptsDir, ".prompt.md", entries);
 
@@ -811,7 +822,8 @@ function syncCopilot(entries) {
 Copilot does not expose true spawnable subagents. Use these reusable prompt profiles for role-specific passes:
 
 ${list || "(all specialists are internal — use construct for all tasks)"}`;
-  writeFile(instructionsPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd));
+  // User-managed file with our managed-block carved out — never doc-stamp.
+  writeFile(instructionsPath, replaceManagedBlock(existing, note, mdManagedStart, mdManagedEnd), { stamp: false });
 }
 
 // --- VS Code adapter ---
@@ -1143,20 +1155,12 @@ function collectSkills() {
   return results;
 }
 
-/**
- * Prefix prepended to every generated SKILL.md. The comment must survive
- * round-trips — it is the canonical signal that a file was produced by sync
- * and must not be hand-edited.
- */
-const SKILL_GENERATED_PREFIX = "# Generated by construct sync\n\n";
-
 /**
  * Write collected skills to both .claude/skills/ and .agents/skills/ in
- * SKILL.md directory format.
- *
- * Idempotency: content written is deterministic; writing the same content
- * twice is a no-op because writeFile skips unchanged files in dry-run mode
- * and two-phase staging in normal mode produces identical results.
+ * SKILL.md directory format. Each file gets Anthropic Agent Skills frontmatter
+ * (name + description) so the loader can index it. Doc-stamping is opted out
+ * — a doc-stamp YAML block before the real frontmatter produces double-
+ * frontmatter the loader can't parse.
  */
 function syncSkills() {
   const skills = collectSkills();
@@ -1166,9 +1170,13 @@ function syncSkills() {
   const agentsSkillsDir = path.join(home, ".agents", "skills");
 
   for (const { name, content } of skills) {
-    const generated = `${SKILL_GENERATED_PREFIX}${content}`;
-    writeFile(path.join(claudeSkillsDir, name, "SKILL.md"), generated);
-    writeFile(path.join(agentsSkillsDir, name, "SKILL.md"), generated);
+    const frontmatter = buildSkillFrontmatter(name, content);
+    // Strip any existing frontmatter from the source body so we don't emit two
+    // blocks if a hand-authored skill already carries one.
+    const body = stripLeadingFrontmatter(content);
+    const generated = `${frontmatter}\n${body}`;
+    writeFile(path.join(claudeSkillsDir, name, "SKILL.md"), generated, { stamp: false });
+    writeFile(path.join(agentsSkillsDir, name, "SKILL.md"), generated, { stamp: false });
   }
 
   return skills.length;