@geraldmaron/construct 1.0.10 → 1.0.11

package/README.md

@@ -6,7 +6,7 @@
 
 ---
 
-> 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.
 

package/lib/auto-docs.mjs

@@ -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).',
     '',
@@ -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.
  */

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/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/package.json

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