@geraldmaron/construct 1.0.10 → 1.0.12

package/README.md

@@ -2,15 +2,15 @@
 
 **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`
 
 ---
 
-> Heads up. Construct is an open source project I started. I am not a developer. This is a side project. There may be bugs, there may be defects, but I'm building it to learn in public. If you'd like to contribute, please do.
+> Heads up. I'm not a developer. Construct is a side project I'm vibe-coding to learn in public. There will be bugs, rough edges, and things that change without warning. The code is open source, the issues queue is real, and contributions are welcome. If you need production-grade tooling today, this isn't it yet.
 
 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';
@@ -69,7 +69,7 @@ function buildCoreDocsContract() {
     '| `.cx/context.md` | Human-readable resumable project context | Active work, decisions, architecture assumptions, or open questions change |',
     '| `.cx/context.json` | Machine-readable resumable context | Context state needs to stay in sync with `.cx/context.md` |',
     '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
-    '| `docs/concepts/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
+    '| `docs/concepts/architecture.mdx` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
     '',
     '`plan.md` is a local working document. `construct init` creates it for the active session, but it is gitignored and not committed; durable work belongs in the tracker (Beads or external).',
     '',
@@ -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',
 };
@@ -177,7 +177,7 @@ function buildAgentsTable(rootDir) {
 // --- public API ---
 
 /**
- * Regenerate all AUTO regions in README.md, docs/README.md, and docs/concepts/architecture.md.
+ * Regenerate all AUTO regions in README.md, docs/README.md, and docs/concepts/architecture.mdx.
  * Returns { changed: string[], checked: boolean }.
  * With check:true writes nothing and sets changed to files that would differ.
  */
@@ -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/gates-audit.mjs

@@ -28,22 +28,31 @@ const DEFAULT_ROOT_DIR = join(MODULE_DIR, '..');
 
 // Authoritative gate mapping. Each entry declares a CI job name and its
 // expected local mirror. `critical: true` means this gate MUST be in CI and
-// SHOULD be in branch-protection required checks; absence is a hard gap.
+// SHOULD have a local mirror; absence is a hard gap. Branch-protection
+// enforcement is checked via `requireMergeVia`: if set, the audit looks for
+// that aggregator context in required checks instead of the gate's own job
+// name. The `ci-required` aggregator job (ci.yml) wraps every conditional
+// job and reports the combined success/skipped/failure status, which lets
+// path-skipped jobs satisfy branch protection on doc-only PRs.
+//
 // `localMirror: 'ci-only'` flags gates that legitimately have no local
 // equivalent (e.g., dockerized integration tests).
 
+const MERGE_AGGREGATOR = 'ci-required';
+
 const GATE_DEFINITIONS = [
-  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: 'tests', critical: true },
-  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: 'tests', critical: true },
-  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: 'tests', critical: true },
-  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: 'tests', critical: true },
-  { ciJob: 'retrieval evals',                prePushLabel: 'evals', critical: true },
-  { ciJob: 'dependency CVE audit',           prePushLabel: 'audit', critical: true },
+  { ciJob: 'test (ubuntu-latest / node 22)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'test (macos-latest / node 22)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'test (ubuntu-latest / node 20)', prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'test (macos-latest / node 20)',  prePushLabel: 'tests', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'retrieval evals',                prePushLabel: 'evals', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'dependency CVE audit',           prePushLabel: 'audit', critical: true, requireMergeVia: MERGE_AGGREGATOR },
   { ciJob: 'secret scanning',                prePushLabel: null,  preCommitCheck: 'ECC secret scan',               critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
-  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only' },
-  { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true },
-  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree' },
-  { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body' },
+  { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true, requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body', requireMergeVia: MERGE_AGGREGATOR },
+  { ciJob: MERGE_AGGREGATOR,                 prePushLabel: null,  preCommitCheck: null,                            critical: true, note: 'aggregator: succeeds iff every wrapped conditional job in ci.yml ended in success or skipped', localMirror: 'ci-only' },
 ];
 
 function parseCIJobs(rootDir) {
@@ -51,14 +60,21 @@ function parseCIJobs(rootDir) {
   // (e.g. the `lint suite` job carrying comment policy + docs drift + gates
   // audit as steps) surface each step name as a gate signal. The audit's
   // job-name comparison treats jobs and steps as a flat union so gate
-  // definitions stay decoupled from CI structure.
-  const path = join(rootDir, '.github', 'workflows', 'ci.yml');
-  if (!existsSync(path)) return [];
-  const yml = readFileSync(path, 'utf8');
-  const jobNames = [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
-  const stepNames = [...yml.matchAll(/^      - name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
-  return [...jobNames, ...stepNames]
-    .map((n) => n.replace(/\$\{\{\s*matrix\.(\w+)\s*\}\}/g, (_, k) => `<${k}>`));
+  // definitions stay decoupled from CI structure. Reads ci.yml plus any
+  // sibling workflow files that emit required-to-merge contexts (currently
+  // pr-review.yml for the `review` job).
+  const dir = join(rootDir, '.github', 'workflows');
+  const files = ['ci.yml', 'pr-review.yml'];
+  const names = [];
+  for (const file of files) {
+    const path = join(dir, file);
+    if (!existsSync(path)) continue;
+    const yml = readFileSync(path, 'utf8');
+    const jobNames = [...yml.matchAll(/^    name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+    const stepNames = [...yml.matchAll(/^      - name:\s*(.+?)\s*$/gm)].map((m) => m[1].trim());
+    names.push(...jobNames, ...stepNames);
+  }
+  return names.map((n) => n.replace(/\$\{\{\s*matrix\.(\w+)\s*\}\}/g, (_, k) => `<${k}>`));
 }
 
 function parsePrePushJobs(rootDir) {
@@ -126,9 +142,15 @@ function identifyGaps(state) {
     }
 
     if (def.critical && protectionVisible) {
-      const required = branchProtection.requiredContexts.includes(def.ciJob);
+      const mergeContext = def.requireMergeVia || def.ciJob;
+      const required = branchProtection.requiredContexts.includes(mergeContext);
       if (!required) {
-        gaps.push({ kind: 'not-required-to-merge', gate: def.ciJob, critical: true });
+        gaps.push({
+          kind: 'not-required-to-merge',
+          gate: def.ciJob,
+          via: mergeContext === def.ciJob ? undefined : mergeContext,
+          critical: true,
+        });
       }
     }
 
@@ -231,7 +253,8 @@ export function formatReport(report) {
       const marker = g.critical ? '✗' : '⚠';
       const detail = g.note ? ` — ${g.note}` : '';
       const extra = g.kind === 'hooks-unwired' ? ` (expected ${g.expected}, actual ${g.actual})` : '';
-      lines.push(`  ${marker} ${g.kind}: ${g.gate || ''}${extra}${detail}`);
+      const via = g.via ? ` (via ${g.via})` : '';
+      lines.push(`  ${marker} ${g.kind}: ${g.gate || ''}${via}${extra}${detail}`);
     }
   }
   lines.push('');

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/init/detect-existing-structure.mjs

@@ -0,0 +1,265 @@
+/**
+ * lib/init/detect-existing-structure.mjs — Inspect a project for content
+ * directories, custom intake surfaces, and root template files so init/sync
+ * can defer to what's already there instead of scaffolding parallel trees.
+ *
+ * Returns a deterministic shape:
+ *   {
+ *     existingLanes: { <laneKey>: [{ path, markdownCount }, ...] },
+ *     customIntake: { ingestScript: string|null, intakePaths: string[] },
+ *     rootTemplates: { dir: string|null, files: string[] }
+ *   }
+ *
+ * Heuristics intentionally err on the side of "skip" — a directory is treated
+ * as a real lane only when it carries at least one markdown file. An empty
+ * docs/meetings/ that an earlier init scaffolded does NOT register; that lets
+ * re-running init be a no-op rather than a contradictory "skip what we just
+ * created" message.
+ *
+ * Issue #97 motivates this: `construct init` on an existing project with
+ * `internal/meetings/`, a custom `ingest` script, and root-level `templates/`
+ * created `docs/meetings/`, `.cx/inbox/`, and per-lane `templates/` folders
+ * that conflicted with the existing workflow.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Matches the LANE_ALIASES table in lib/init-docs.mjs / lib/init-unified.mjs.
+// Keep in sync if those grow new entries. The detector only needs alias →
+// lane mapping for directory-name matching; the full lane metadata lives in
+// the init modules that consume the result.
+
+export const LANE_DIR_ALIASES = {
+  adr: 'adrs',
+  adrs: 'adrs',
+  brief: 'briefs',
+  briefs: 'briefs',
+  changelog: 'changelogs',
+  changelogs: 'changelogs',
+  release: 'changelogs',
+  releases: 'changelogs',
+  intake: 'intake',
+  inbox: 'intake',
+  memo: 'memos',
+  memos: 'memos',
+  meeting: 'meetings',
+  meetings: 'meetings',
+  minutes: 'meetings',
+  retro: 'meetings',
+  retros: 'meetings',
+  note: 'notes',
+  notes: 'notes',
+  onboard: 'onboarding',
+  onboarding: 'onboarding',
+  postmortem: 'postmortems',
+  postmortems: 'postmortems',
+  incident: 'postmortems',
+  incidents: 'postmortems',
+  prd: 'prds',
+  prds: 'prds',
+  rfc: 'rfcs',
+  rfcs: 'rfcs',
+  runbook: 'runbooks',
+  runbooks: 'runbooks',
+};
+
+// Skip these top-level directories when scanning. Generated, vendored, or
+// already-Construct-managed trees never carry user content lanes.
+
+const SCAN_SKIP_DIRS = new Set([
+  '.git',
+  '.cx',
+  '.beads',
+  '.construct',
+  '.claude',
+  '.codex',
+  '.cursor',
+  '.vscode',
+  '.github',
+  '.husky',
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  'target',
+  '.next',
+  '.cache',
+  '.pnpm-store',
+  '.venv',
+  'venv',
+  '__pycache__',
+]);
+
+const MAX_SCAN_DEPTH = 3;
+
+// Common custom intake-script names. Project owners who hand-roll an ingest
+// path overwhelmingly name it one of these. Each is checked at repo root.
+
+const INTAKE_SCRIPT_CANDIDATES = ['ingest', 'ingest.sh', 'ingest.mjs', 'ingest.js', 'ingest.py'];
+
+// Common custom raw-intake directory shapes seen in real projects (issue #97
+// repro had data/customers/notes/raw/). Glob-free literal paths so detection
+// stays cheap and predictable.
+
+const INTAKE_PATH_CANDIDATES = [
+  'data/customers/notes/raw',
+  'data/intake',
+  'data/raw',
+  'ingestion',
+  'intake-pipeline',
+  'raw',
+];
+
+function countMarkdownFiles(dir) {
+  let count = 0;
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) count++;
+      if (entry.isDirectory() && !entry.name.startsWith('.')) {
+        count += countMarkdownFiles(path.join(dir, entry.name));
+      }
+      if (count >= 100) break;
+    }
+  } catch { /* unreadable dir is treated as empty */ }
+  return count;
+}
+
+function walkLaneDirs(rootDir, currentDir, depth, accumulator) {
+  if (depth > MAX_SCAN_DEPTH) return;
+  let entries = [];
+  try { entries = fs.readdirSync(currentDir, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (SCAN_SKIP_DIRS.has(entry.name)) continue;
+    const absPath = path.join(currentDir, entry.name);
+    const relPath = path.relative(rootDir, absPath);
+    const lower = entry.name.toLowerCase();
+    const laneKey = LANE_DIR_ALIASES[lower];
+    if (laneKey) {
+      // The newly-scaffolded docs/<lane>/ tree is what init writes, so it
+      // doesn't count as "existing" content. Other locations do.
+      const isOwnDocsTree = relPath === path.join('docs', LANE_DIR_ALIASES[lower]) || relPath === path.join('docs', lower);
+      if (!isOwnDocsTree) {
+        const markdownCount = countMarkdownFiles(absPath);
+        if (markdownCount > 0) {
+          if (!accumulator[laneKey]) accumulator[laneKey] = [];
+          accumulator[laneKey].push({ path: relPath, markdownCount });
+        }
+      }
+    }
+    walkLaneDirs(rootDir, absPath, depth + 1, accumulator);
+  }
+}
+
+function detectIntakeScript(rootDir) {
+  for (const candidate of INTAKE_SCRIPT_CANDIDATES) {
+    const candidatePath = path.join(rootDir, candidate);
+    if (!fs.existsSync(candidatePath)) continue;
+    try {
+      const stat = fs.statSync(candidatePath);
+      if (stat.isFile()) return candidate;
+    } catch { /* race with deletion — treat as absent */ }
+  }
+  return null;
+}
+
+function detectIntakePaths(rootDir) {
+  const found = [];
+  for (const rel of INTAKE_PATH_CANDIDATES) {
+    const abs = path.join(rootDir, rel);
+    if (fs.existsSync(abs)) found.push(rel);
+  }
+  return found;
+}
+
+function detectRootTemplates(rootDir) {
+  const templatesDir = path.join(rootDir, 'templates');
+  if (!fs.existsSync(templatesDir)) return { dir: null, files: [] };
+  try {
+    const entries = fs.readdirSync(templatesDir, { withFileTypes: true });
+    const files = entries
+      .filter((e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.mdx')))
+      .map((e) => e.name);
+    return { dir: 'templates', files };
+  } catch {
+    return { dir: null, files: [] };
+  }
+}
+
+export function detectExistingContent(rootDir) {
+  const existingLanes = {};
+  walkLaneDirs(rootDir, rootDir, 0, existingLanes);
+  return {
+    existingLanes,
+    customIntake: {
+      ingestScript: detectIntakeScript(rootDir),
+      intakePaths: detectIntakePaths(rootDir),
+    },
+    rootTemplates: detectRootTemplates(rootDir),
+  };
+}
+
+// Convenience helper: pretty-print the detection result for init's
+// "Skipped (deferred to existing project structure)" summary block.
+
+export function formatDeferralSummary(detection) {
+  const lines = [];
+  for (const [lane, matches] of Object.entries(detection.existingLanes)) {
+    const top = matches[0];
+    const extra = matches.length > 1 ? ` (+${matches.length - 1} more)` : '';
+    lines.push(`  • lane "${lane}": found existing ${top.path}/ (${top.markdownCount} md file${top.markdownCount === 1 ? '' : 's'})${extra}`);
+  }
+  if (detection.customIntake.ingestScript) {
+    lines.push(`  • intake: custom script ./${detection.customIntake.ingestScript} detected`);
+  }
+  if (detection.customIntake.intakePaths.length) {
+    lines.push(`  • intake: custom path${detection.customIntake.intakePaths.length === 1 ? '' : 's'} ${detection.customIntake.intakePaths.join(', ')} detected`);
+  }
+  if (detection.rootTemplates.dir && detection.rootTemplates.files.length) {
+    lines.push(`  • templates: root ./${detection.rootTemplates.dir}/ has ${detection.rootTemplates.files.length} template file${detection.rootTemplates.files.length === 1 ? '' : 's'}`);
+  }
+  return lines.join('\n');
+}
+
+// Maps a lane key to the root-template file base name init would otherwise
+// copy into docs/<lane>/templates/. Used so callers can ask "is the root
+// templates/ already covering this lane?" without re-deriving the mapping.
+
+export function rootTemplateCoversLane(detection, laneKey) {
+  if (!detection.rootTemplates.dir) return false;
+  const wanted = new Set([`${laneKey}.md`, `${laneKey.replace(/s$/, '')}.md`, `_template.md`, `template.md`]);
+  return detection.rootTemplates.files.some((f) => wanted.has(f.toLowerCase()));
+}
+
+// Single decision function so both init entry points (init-unified.mjs and
+// init-docs.mjs) skip the same lanes for the same reasons. force=true makes
+// every decision a pass-through so power users can scaffold over an existing
+// layout when they really want a parallel docs/ tree.
+
+export function shouldScaffoldLane(laneKey, detection, { force = false } = {}) {
+  if (force) return { skip: false };
+  const matches = detection.existingLanes?.[laneKey];
+  if (matches && matches.length > 0) {
+    const top = matches[0];
+    return {
+      skip: true,
+      reason: `existing ${top.path}/ has ${top.markdownCount} markdown file${top.markdownCount === 1 ? '' : 's'}`,
+    };
+  }
+  return { skip: false };
+}
+
+export function shouldSkipProjectInbox(detection, { force = false } = {}) {
+  if (force) return { skip: false };
+  const { ingestScript, intakePaths } = detection.customIntake || {};
+  if (ingestScript) {
+    return { skip: true, reason: `custom intake script ./${ingestScript} detected` };
+  }
+  if (intakePaths && intakePaths.length > 0) {
+    return { skip: true, reason: `custom intake path${intakePaths.length === 1 ? '' : 's'} ${intakePaths.join(', ')} detected` };
+  }
+  return { skip: false };
+}

package/lib/init-docs.mjs

@@ -38,6 +38,9 @@ const extrasArg = args.find((arg) => arg.startsWith("--extras="));
 const withArchitectureFlag = args.includes("--with-architecture");
 const suggestOrg = args.includes("--suggest-org");
 const organize = args.includes("--organize");
+// --force bypasses the existing-content detector so lanes already covered by
+// the project (e.g. internal/meetings/) still get a parallel docs/<lane>/.
+const forceScaffold = args.includes("--force");
 const targetArg = args.find((arg) => !arg.startsWith("--"));
 const target = path.resolve(targetArg ?? process.cwd());
 
@@ -750,17 +753,57 @@ async function main() {
 
   process.stdout.write(`\nConstruct init-docs → ${target}\n\n`);
 
-  writeIfMissing(path.join(docsDir, "README.md"), buildDocsReadme(projectName, allLaneKeys));
-if (withArchitecture) {
-  writeIfMissing(path.join(docsDir, "architecture.md"), buildArchitectureDoc(projectName, allLaneKeys));
-}
-  if (selectedLanes.includes('intake')) {
-    writeIfMissing(path.join(target, '.cx', 'inbox', '.gitkeep'), '');
+  // Inspect existing project content once and filter out lanes the project
+  // already covers (issue #97). --force bypasses every check.
+
+  const { detectExistingContent, shouldScaffoldLane, shouldSkipProjectInbox, formatDeferralSummary } =
+    await import('./init/detect-existing-structure.mjs');
+  const detection = detectExistingContent(target);
+
+  const deferredLanes = [];
+  const lanesToScaffold = [];
+  for (const laneKey of selectedLanes) {
+    const decision = shouldScaffoldLane(laneKey, detection, { force: forceScaffold });
+    if (decision.skip) {
+      deferredLanes.push({ laneKey, reason: decision.reason });
+    } else {
+      lanesToScaffold.push(laneKey);
+    }
+  }
+  const allScaffoldedLaneKeys = sortLaneKeys([...lanesToScaffold, ...selectedCustomLanes]);
+
+  if (lanesToScaffold.length > 0 || selectedCustomLanes.length > 0) {
+    writeIfMissing(path.join(docsDir, "README.md"), buildDocsReadme(projectName, allScaffoldedLaneKeys));
+  }
+  if (withArchitecture) {
+    writeIfMissing(path.join(docsDir, "architecture.md"), buildArchitectureDoc(projectName, allScaffoldedLaneKeys));
+  }
+  if (lanesToScaffold.includes('intake')) {
+    const inboxDecision = shouldSkipProjectInbox(detection, { force: forceScaffold });
+    if (inboxDecision.skip) {
+      process.stdout.write(`[init:docs] skipping .cx/inbox/ — ${inboxDecision.reason}. Run with --force to scaffold anyway.\n`);
+      skipped.push('.cx/inbox/ (deferred to existing intake)');
+    } else {
+      writeIfMissing(path.join(target, '.cx', 'inbox', '.gitkeep'), '');
+    }
+  }
+
+  for (const { laneKey, reason } of deferredLanes) {
+    process.stdout.write(`[init:docs] skipping docs/${DOC_LANES[laneKey].dir}/ — ${reason}. Run with --force to scaffold anyway.\n`);
+    skipped.push(`docs/${DOC_LANES[laneKey].dir}/ (deferred to existing project structure)`);
   }
 
-  for (const laneKey of selectedLanes) copyLaneTemplates(laneKey);
+  for (const laneKey of lanesToScaffold) copyLaneTemplates(laneKey);
   for (const laneKey of selectedCustomLanes) createCustomLane(laneKey);
 
+  if (!forceScaffold) {
+    const summary = formatDeferralSummary(detection);
+    if (summary) {
+      process.stdout.write('\nDeferred to existing project structure (use --force to scaffold anyway):\n');
+      process.stdout.write(`${summary}\n`);
+    }
+  }
+
   // Handle suggestion and organization of existing markdown files
   if (suggestOrg || organize) {
     if (organize && !skipInteractive) {

package/lib/init-unified.mjs

@@ -48,6 +48,10 @@ const verbose = args.includes("--verbose") || args.includes("-v");
 const interactive = args.includes("--interactive") || args.includes("-i");
 const quiet = args.includes("--quiet") || args.includes("-q");
 const skipInteractive = !interactive;
+// --force bypasses the existing-content detector so init writes its full
+// scaffold even when populated lane dirs / a custom intake script / a root
+// templates/ already exist (issue #97).
+const forceScaffold = args.includes("--force");
 
 // Active profile selector. `--profile=<id>` writes the field into the
 // project's construct.config.json so resolveActiveProfile picks it up
@@ -860,14 +864,29 @@ async function main() {
     generator: "construct/init",
   });
   
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", "inbox", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
+  // Detect existing project content once; the result feeds three decisions
+  // below: skip .cx/inbox/ on custom intake, skip lane scaffolding for lanes
+  // already covered elsewhere, and skip per-lane templates/ when root
+  // templates/ already has them. --force bypasses every check.
+
+  const { detectExistingContent, shouldSkipProjectInbox, shouldScaffoldLane, formatDeferralSummary } =
+    await import('./init/detect-existing-structure.mjs');
+  const detection = detectExistingContent(target);
+  const inboxDecision = shouldSkipProjectInbox(detection, { force: forceScaffold });
+
+  if (inboxDecision.skip) {
+    console.log(`[init:intake] skipping .cx/inbox/ — ${inboxDecision.reason}. Run with --force to scaffold anyway.`);
+    skipped.push('.cx/inbox/ (deferred to existing intake)');
+  } else {
+    writeStampedIfMissing({
+      targetRoot: target,
+      created,
+      skipped,
+      filePath: path.join(target, ".cx", "inbox", ".gitkeep"),
+      content: "",
+      generator: "construct/init",
+    });
+  }
 
   // Stage .construct/ launcher + sync .claude/ adapters so init produces the
   // same project shape as a fresh `npm install` of the package as a dep.
@@ -963,6 +982,11 @@ async function main() {
   console.log('[TRACE init:intake-ask]');
 
   const intakeConfig = (await askIntakeCollection(target, skipInteractive)) ?? { parentDirs: [], maxDepth: 4 };
+  // When a custom intake surface was detected, default includeProjectInbox
+  // to false so the watcher does not double-claim with the user's existing
+  // pipeline. User can opt in later via `construct config intake.includeProjectInbox=true`.
+
+  if (inboxDecision.skip) intakeConfig.includeProjectInbox = false;
   const { saveIntakeConfig } = await import('./intake/intake-config.mjs');
   try {
     saveIntakeConfig(target, intakeConfig);
@@ -986,17 +1010,36 @@ async function main() {
   
   // Create documentation system if lanes specified
   if (lanes.length > 0) {
-    // Create docs/README.md
-    writeIfMissing(
-      path.join(target, "docs", "README.md"),
-      buildDocsReadme(projectName)
-    );
-    
-    // Create selected lanes
+    // Filter out lanes that the project already covers elsewhere
+    // (issue #97: don't create docs/meetings/ when internal/meetings/
+    // has 12 markdown files). --force bypasses the filter.
+
+    const deferredLanes = [];
+    const lanesToScaffold = [];
     for (const laneKey of lanes) {
-      copyLaneTemplates(laneKey);
+      const decision = shouldScaffoldLane(laneKey, detection, { force: forceScaffold });
+      if (decision.skip) {
+        deferredLanes.push({ laneKey, reason: decision.reason });
+      } else {
+        lanesToScaffold.push(laneKey);
+      }
     }
-    
+    for (const { laneKey, reason } of deferredLanes) {
+      console.log(`[init:docs] skipping docs/${DOC_LANES[laneKey].dir}/ — ${reason}. Run with --force to scaffold anyway.`);
+      skipped.push(`docs/${DOC_LANES[laneKey].dir}/ (deferred to existing project structure)`);
+    }
+
+    if (lanesToScaffold.length > 0) {
+      writeIfMissing(
+        path.join(target, "docs", "README.md"),
+        buildDocsReadme(projectName)
+      );
+
+      for (const laneKey of lanesToScaffold) {
+        copyLaneTemplates(laneKey);
+      }
+    }
+
     // Create architecture.md if requested
     if (withArchitecture) {
       writeIfMissing(
@@ -1005,6 +1048,19 @@ async function main() {
       );
     }
   }
+
+  // End-of-init summary block for what got deferred to existing project
+  // structure. Mirrors the "Created:" section so users see WHY their docs/
+  // tree is leaner than the default scaffold.
+
+  if (!forceScaffold) {
+    const summary = formatDeferralSummary(detection);
+    if (summary && !quiet) {
+      console.log('');
+      console.log('Deferred to existing project structure (use --force to scaffold anyway):');
+      console.log(summary);
+    }
+  }
   
   // Output results (respect quiet mode)
   if (!quiet) {

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.10",
+  "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;