@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/hooks/session-start.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 300
  * @maxBlockingScope SessionStart
+ *
+ * @lifecycle SessionStart
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, existsSync, statSync, writeFileSync } from 'fs';
 import { execSync } from 'child_process';
@@ -267,7 +271,7 @@ try {
   if (hasSources) {
     const parts = [];
     if (repos.length > 0) parts.push(`GitHub repos: ${repos.join(', ')}`);
-    if (jiraConfigured) parts.push(`Jira: ${process.env.JIRA_BASE_URL}`);
+    if (jiraConfigured) parts.push('Jira: configured');
     if (linearConfigured) parts.push('Linear: configured');
     // Surface which sources are wired so `provider_fetch` is the obvious
     // tool for questions about them. The "fetch first, don't answer from
@@ -321,6 +325,49 @@ try {
   brokerStatusNote = `\n${buildBrokerStatusLine({ env: process.env })}\n`;
 } catch { /* best effort */ }
 
+// Missing-env-vars notice. Reads .env.example from the project root,
+// compares against .env and process.env, lists keys whose example value
+// is a placeholder and whose live value is unset. Empty string when the
+// project has no .env.example or all required keys are populated.
+
+const envCheckNote = buildEnvCheckNote(cwd);
+
+function buildEnvCheckNote(rootDir) {
+  const examplePath = join(rootDir, '.env.example');
+  if (!existsSync(examplePath)) return '';
+  const example = parseEnvFile(examplePath);
+  if (example.size === 0) return '';
+  const envFile = parseEnvFile(join(rootDir, '.env'));
+  const PLACEHOLDER = /^(YOUR_|<|__|\$\{|REPLACE|ADD_|INSERT_|xxx|TODO)/i;
+  const missing = [];
+  for (const [key, exampleVal] of example) {
+    const required = !exampleVal || PLACEHOLDER.test(exampleVal);
+    if (!required) continue;
+    const liveFromEnvFile = envFile.has(key) && envFile.get(key) !== '' && !PLACEHOLDER.test(envFile.get(key));
+    const liveFromProcessEnv = process.env[key] && !PLACEHOLDER.test(process.env[key]);
+    if (!liveFromEnvFile && !liveFromProcessEnv) missing.push(key);
+  }
+  if (missing.length === 0) return '';
+  const noun = missing.length === 1 ? 'variable' : 'variables';
+  const list = missing.map((k) => `  - ${k}`).join('\n');
+  return `\n## Environment check — ${missing.length} required ${noun} not set\n${list}\nAdd these to .env before running the app.\n`;
+}
+
+function parseEnvFile(p) {
+  const map = new Map();
+  if (!existsSync(p)) return map;
+  for (const line of readFileSync(p, 'utf8').split('\n')) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith('#')) continue;
+    const eq = stripped.indexOf('=');
+    if (eq === -1) continue;
+    const key = stripped.slice(0, eq).trim();
+    const val = stripped.slice(eq + 1).trim();
+    if (key) map.set(key, val);
+  }
+  return map;
+}
+
 // Permission posture: surface gaps in ~/.claude/settings.json permissions.allow
 // so the agent can ask the user to close them instead of stumbling into the
 // classifier mid-task. Empty string when no gaps — keeps the banner small.
@@ -331,7 +378,7 @@ try {
   permissionPostureNote = buildPermissionPostureLine({ cwd });
 } catch { /* best effort */ }
 
-process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}\n${footer}${pendingNote}\n`);
+process.stdout.write(`${header}\n${body}${stateNote}${efficiencyNote}${observationsNote}${concurrencyNote}${skillScopeNote}${dropNote}${embedStatusNote}${sourcesNote}${selfKnowledgeNote}${rolesNote}${intakeReviewNote}${brokerStatusNote}${permissionPostureNote}${envCheckNote}\n${footer}${pendingNote}\n`);
 // Auto-bootstrap the policy-engine gate. session-start has just emitted
 // branch + recent commits + prior observations + context-state — that is
 // already grounding; mark the session bootstrapped so the PreToolUse rule

package/lib/hooks/session-tracking-refresh.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/session-tracking-refresh.mjs — keep the project's tracking
+ * surfaces current at session end.
+ *
+ * Runs as a Stop hook in parallel with the other Stop-time hooks. Touches
+ * three surfaces:
+ *
+ *   - `.cx/context.md` + `.cx/context.json` — refresh Active Work, Recent
+ *     Decisions, and Architecture Notes from the session's observations,
+ *     commits, and bead state changes.
+ *   - `plan.md` — sync the bead-status table with current `bd show <id>`
+ *     truth; if every referenced bead has closed and the plan has been
+ *     idle for >1h, archive a copy to `.cx/handoffs/<date>-plan-landed.md`
+ *     and reset `plan.md` to the standard template.
+ *
+ * Best-effort. Failures degrade silently. Wall-clock budgeted at 2000 ms
+ * total — bd shells out, and a plan with several bead refs needs one
+ * `bd show` per ref. Exits 0 on any error so the session close path is
+ * never blocked.
+ *
+ * Only runs inside Construct projects (presence of `.cx/`) — same gate as
+ * the other Stop hooks.
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @p95ms 2000
+ * @maxBlockingScope none (Stop, non-blocking)
+ * @exits 0 = pass
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { readHookInput } from './_lib/input.mjs';
+import { logHookFailure } from './_lib/log.mjs';
+
+const HARD_BUDGET_MS = 2000;
+const startedAt = Date.now();
+
+const input = readHookInput();
+const cwd = input?.cwd || process.cwd();
+
+// Only run inside Construct projects.
+if (!existsSync(join(cwd, '.cx'))) process.exit(0);
+
+const deadline = setTimeout(() => process.exit(0), HARD_BUDGET_MS);
+deadline.unref();
+
+try {
+  // Order matters. archivePlanIfLanded reads plan.md's mtime to decide
+  // whether the plan has been idle long enough to retire. syncPlanFile
+  // mutates plan.md when bead statuses drift — which bumps mtime and
+  // makes the plan look "recently touched" to the archive check. Run
+  // archive first (true idle mtime), then sync the survivor.
+  const { archivePlanIfLanded, syncPlanFile, refreshContextMd } = await import('../tracking-surfaces.mjs');
+  await archivePlanIfLanded({ rootDir: cwd });
+  await syncPlanFile({ rootDir: cwd });
+  await refreshContextMd({ rootDir: cwd });
+} catch (err) {
+  logHookFailure({ hook: 'session-tracking-refresh', err, phase: 'refresh' });
+}
+
+const elapsed = Date.now() - startedAt;
+if (elapsed > HARD_BUDGET_MS) {
+  try {
+    process.stderr.write(`[session-tracking-refresh] over budget: ${elapsed}ms\n`);
+  } catch { /* stderr closed */ }
+}
+
+process.exit(0);

package/lib/hooks/stop-notify.mjs

@@ -11,8 +11,14 @@
  *
  * @p95ms 500
  * @maxBlockingScope Stop
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
-import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { appendBounded } from '../logging/rotate.mjs';
+import { resolveProjectScope } from '../project-root.mjs';
 import { execSync } from 'child_process';
 import { homedir } from 'os';
 import { join, dirname } from 'path';
@@ -228,7 +234,12 @@ try {
     if (agentName) entry.agent = agentName;
     if (taskKey) entry.task_key = taskKey;
 
-    try { appendFileSync(costLogPath, JSON.stringify(entry) + '\n'); } catch { /* non-critical */ }
+    // Cross-project ledger — keep at user scope but tag with projectId so a
+    // reader can attribute spend to a specific project.
+
+    const scope = resolveProjectScope();
+    if (scope?.projectId) entry.projectId = scope.projectId;
+    try { appendBounded('session-cost', costLogPath, JSON.stringify(entry) + '\n'); } catch { /* non-critical */ }
 
     totalCostUsd += priced.costUsd;
     turnsLogged += 1;

package/lib/hooks/stop-typecheck.mjs

@@ -6,6 +6,10 @@
  *
  * @p95ms 2000
  * @maxBlockingScope Stop
+ *
+ * @lifecycle Stop
+ * @matcher  *
+ * @exits 0 = pass
  */
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { execSync } from 'child_process';

package/lib/hooks/test-watch.mjs

@@ -8,9 +8,13 @@
  *
  * @p95ms 30
  * @maxBlockingScope none (async, non-blocking)
+ *
+ * @lifecycle PostToolUse
+ * @matcher  Bash
+ * @exits 0 = pass
  */
 
-import { readFileSync, existsSync, appendFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { logHookFailure } from './_lib/log.mjs';
@@ -56,13 +60,13 @@ try {
     }
     state[name] = { failedAt: now };
   }
-  appendFileSync(flakeTrackerPath, '');
   const trimmed = {};
   for (const [k, v] of Object.entries(state)) {
     if ((v.failedAt || v.passedAt || 0) > now - 24 * 60 * 60 * 1000) trimmed[k] = v;
   }
-  const writeFileSync = (await import('node:fs')).writeFileSync;
   writeFileSync(flakeTrackerPath, JSON.stringify(trimmed));
-} catch { /* best effort */ }
+} catch (err) {
+  logHookFailure({ hook: 'test-watch', err, phase: 'flake-track' });
+}
 
 process.exit(0);

package/lib/ingest/chunker.mjs

@@ -0,0 +1,94 @@
+/**
+ * lib/ingest/chunker.mjs — paragraph-boundary chunker with sentence overlap.
+ *
+ * 2026-06 best practice notes:
+ *   - Recursive/sentence chunking remains the high-recall default (~85-90%
+ *     on 2026 RAG benchmarks). Semantic chunking gains only ~2-3% recall at
+ *     ~14× the embedding cost and only matters above ~5k token docs.
+ *   - Parent-document retrieval is the meaningful 2026 upgrade beyond
+ *     paragraph chunking — track separately if recall plateaus.
+ *
+ * Strategy:
+ *   1. Split markdown by blank-line paragraph boundaries.
+ *   2. Pack paragraphs into chunks under maxChars (default 1500 ≈ 375 tokens).
+ *   3. Add 1-2 sentence overlap between consecutive chunks to preserve
+ *      cross-chunk anchors.
+ *   4. Preserve markdown structure: never split inside a fenced code block.
+ */
+
+const DEFAULT_MAX_CHARS = 1500;
+const DEFAULT_OVERLAP_SENTENCES = 2;
+const SENTENCE_RE = /[^.!?]+[.!?]+["')\]]*\s*/g;
+
+export function splitSentences(text) {
+  const matches = text.match(SENTENCE_RE);
+  if (matches && matches.length) return matches.map((s) => s.trim()).filter(Boolean);
+  return text.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function tailSentences(text, count) {
+  const sentences = splitSentences(text);
+  return sentences.slice(-count).join(' ');
+}
+
+function splitParagraphs(markdown) {
+  const blocks = [];
+  let buffer = '';
+  let inFence = false;
+  for (const line of markdown.split('\n')) {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (!inFence && line.trim() === '' && buffer.trim()) {
+      blocks.push(buffer.trim());
+      buffer = '';
+      continue;
+    }
+    buffer += line + '\n';
+  }
+  if (buffer.trim()) blocks.push(buffer.trim());
+  return blocks;
+}
+
+export function chunkMarkdown(markdown, { maxChars = DEFAULT_MAX_CHARS, overlapSentences = DEFAULT_OVERLAP_SENTENCES } = {}) {
+  const paragraphs = splitParagraphs(markdown || '');
+  if (paragraphs.length === 0) return [];
+
+  const chunks = [];
+  let current = '';
+  let chunkIndex = 0;
+  const flushChunk = () => {
+    if (!current.trim()) return;
+    const text = current.trim();
+    chunks.push({
+      index: chunkIndex++,
+      text,
+      chars: text.length,
+    });
+    const overlap = overlapSentences > 0 ? tailSentences(text, overlapSentences) : '';
+    current = overlap ? overlap + '\n\n' : '';
+  };
+
+  for (const para of paragraphs) {
+    if (current.length + para.length + 2 > maxChars && current.trim()) {
+      flushChunk();
+    }
+    if (para.length > maxChars) {
+      flushChunk();
+      const sentences = splitSentences(para);
+      let buf = '';
+      for (const s of sentences) {
+        if (buf.length + s.length + 1 > maxChars && buf.trim()) {
+          chunks.push({ index: chunkIndex++, text: buf.trim(), chars: buf.trim().length });
+          buf = (overlapSentences > 0 ? tailSentences(buf, overlapSentences) : '') + (overlapSentences > 0 ? ' ' : '');
+        }
+        buf += s + ' ';
+      }
+      if (buf.trim()) {
+        current = buf.trim() + '\n\n';
+      }
+      continue;
+    }
+    current += (current ? '\n\n' : '') + para;
+  }
+  flushChunk();
+  return chunks;
+}

package/lib/ingest/pipeline.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/ingest/pipeline.mjs — orchestrate the content-hashed ingest pipeline.
+ *
+ * Flow: hash → de-dup → extract via docling/whisper → chunk → write to
+ * .cx/ingest/<sha>/. Returns a record describing what was stored along
+ * with any droppedInfo surfaced by the extractor.
+ *
+ * Idempotent: re-ingesting the same content (by sha256) returns the
+ * existing record without re-extracting.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { extractDocumentTextAsync } from '../document-extract.mjs';
+import { hashFile, defaultIngestRoot, readRecord, writeRecord } from './store.mjs';
+import { chunkMarkdown } from './chunker.mjs';
+
+export async function ingestFile(filePath, { cwd = process.cwd(), force = false } = {}) {
+  const absPath = path.resolve(filePath);
+  const stat = await fs.stat(absPath);
+  if (!stat.isFile()) throw new Error(`not a regular file: ${absPath}`);
+
+  const root = defaultIngestRoot(cwd);
+  const sha256 = await hashFile(absPath);
+
+  if (!force) {
+    const existing = await readRecord(root, sha256);
+    if (existing) return { ...existing, status: 'cached' };
+  }
+
+  const extracted = await extractDocumentTextAsync(absPath);
+  const markdown = extracted.markdown ?? extracted.text ?? '';
+  const chunks = chunkMarkdown(markdown);
+
+  const source = {
+    sourcePath: absPath,
+    fileName: path.basename(absPath),
+    extension: extracted.extension,
+    bytes: stat.size,
+    sha256,
+    ingestedAt: new Date().toISOString(),
+  };
+
+  const meta = {
+    extractionMethod: extracted.extractionMethod,
+    extractorMetadata: extracted.metadata ?? null,
+    droppedInfo: extracted.droppedInfo ?? [],
+    chunkCount: chunks.length,
+    chunkChars: chunks.reduce((a, c) => a + c.chars, 0),
+  };
+
+  const record = await writeRecord(root, { sha256, source, meta, markdown });
+  return { ...record, status: 'ingested', droppedInfo: meta.droppedInfo, chunks };
+}

package/lib/ingest/store.mjs

@@ -0,0 +1,82 @@
+/**
+ * lib/ingest/store.mjs — content-addressed ingest store at .cx/ingest/<hash>/.
+ *
+ * Each ingested document is stored under its SHA-256 content hash:
+ *   .cx/ingest/<sha256>/source.json   — original path, size, sha256, ingestedAt
+ *   .cx/ingest/<sha256>/markdown.md   — extracted markdown body
+ *   .cx/ingest/<sha256>/meta.json     — extractor metadata, droppedInfo, chunks
+ *
+ * Idempotent: re-ingesting a file with the same content is a no-op (returns
+ * the existing record). Re-running ingestion is the safe default.
+ *
+ * 2026-06 best practice notes:
+ *   - SHA-256 is still the universal content-addressing primitive. BLAKE3 is
+ *     ~2.3× faster on M-series and worth considering at multi-GB scale,
+ *     but is not the industry default and adds an unfamiliar dependency.
+ *     Revisit if ingest throughput becomes a measured bottleneck.
+ *   - Storing markdown body separately from metadata keeps the embedding
+ *     and search paths simple: they only read markdown.md and look up
+ *     provenance from meta.json on demand.
+ */
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export function defaultIngestRoot(cwd = process.cwd()) {
+  return path.join(cwd, '.cx', 'ingest');
+}
+
+export async function hashFile(filePath) {
+  return new Promise((resolveHash, reject) => {
+    const hash = createHash('sha256');
+    const stream = createReadStream(filePath);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('error', reject);
+    stream.on('end', () => resolveHash(hash.digest('hex')));
+  });
+}
+
+function recordDirFor(root, sha256) {
+  return path.join(root, sha256);
+}
+
+export async function readRecord(root, sha256) {
+  const dir = recordDirFor(root, sha256);
+  try {
+    const [source, meta, markdown] = await Promise.all([
+      fs.readFile(path.join(dir, 'source.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'meta.json'), 'utf8').then(JSON.parse),
+      fs.readFile(path.join(dir, 'markdown.md'), 'utf8'),
+    ]);
+    return { sha256, source, meta, markdown, dir };
+  } catch {
+    return null;
+  }
+}
+
+export async function writeRecord(root, { sha256, source, meta, markdown }) {
+  const dir = recordDirFor(root, sha256);
+  await fs.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fs.writeFile(path.join(dir, 'source.json'), JSON.stringify(source, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n', 'utf8'),
+    fs.writeFile(path.join(dir, 'markdown.md'), markdown, 'utf8'),
+  ]);
+  return { sha256, dir, source, meta, markdown };
+}
+
+export async function listRecords(root) {
+  let entries;
+  try { entries = await fs.readdir(root, { withFileTypes: true }); }
+  catch { return []; }
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sha = entry.name;
+    if (!/^[a-f0-9]{64}$/.test(sha)) continue;
+    const record = await readRecord(root, sha);
+    if (record) records.push(record);
+  }
+  return records;
+}

package/lib/init-unified.mjs

@@ -812,12 +812,28 @@ async function main() {
     const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('./config/project-config.mjs');
     const found = findProjectConfigPath(target);
     const cfgPath = found || path.join(target, PROJECT_CONFIG_FILENAME);
-    const cfg = found ? (loadProjectConfig(target) || { version: 1 }) : { version: 1 };
+
+    // loadProjectConfig returns a wrapper { path, raw, config, source, errors }.
+    // Persist .raw (the on-disk JSON) so user customizations survive and
+    // defaults are not silently materialized into the file.
+
+    const loaded = found ? loadProjectConfig(target) : null;
+    const cfg = loaded?.raw ? { ...loaded.raw } : { version: 1 };
     cfg.profile = profileId;
     writeProjectConfig(cfgPath, cfg, { validate: true });
     if (!quiet) console.log(`Profile set to ${profileId}.`);
   }
-  
+
+  // Resolve active profile to drive capability-gated scaffolding (intake
+  // archetype, attribution stamping). Falls back to rnd when no profile is
+  // configured — matches resolveActiveProfile semantics elsewhere.
+
+  const { resolveActiveProfile } = await import('./profiles/loader.mjs');
+  const activeProfile = resolveActiveProfile(target, profileId) ?? null;
+  const intakeCap = activeProfile?.capabilities?.intake ?? null;
+  const { gatherAttribution } = await import('./intake/attribution.mjs');
+  const attribution = intakeCap?.attribution ? gatherAttribution() : null;
+
   // Always create core Construct files
   writeStampedIfMissing({
     targetRoot: target,
@@ -826,8 +842,9 @@ async function main() {
     filePath: path.join(target, "AGENTS.md"),
     content: buildAgentsGuide(projectName),
     generator: "construct/init",
+    attribution,
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -835,17 +852,18 @@ async function main() {
     filePath: path.join(target, "plan.md"),
     content: buildPlanTemplate(),
     generator: "construct/init",
+    attribution,
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
     skipped,
     filePath: path.join(target, ".cx", "context.json"),
-    content: buildContextJson(projectName),
+    content: buildContextJson(projectName, { attribution }),
     generator: "construct/init",
   });
-  
+
   writeStampedIfMissing({
     targetRoot: target,
     created,
@@ -853,6 +871,7 @@ async function main() {
     filePath: path.join(target, ".cx", "context.md"),
     content: buildContextMarkdown(),
     generator: "construct/init",
+    attribution,
   });
   
   writeStampedIfMissing({
@@ -888,6 +907,56 @@ async function main() {
     });
   }
 
+  // Intake-archetype scaffolding. When the active profile declares
+  // capabilities.intake.inbox, scaffold a project-root inbox/ drop zone
+  // (with a .gitignore so raw drops never enter source) and seed the
+  // dedup manifest. The existing-structure detection already opted us
+  // out of clobbering a user's pipeline above.
+
+  if (intakeCap?.inbox && !inboxDecision.skip) {
+    const projectInbox = path.join(target, 'inbox');
+    if (!fs.existsSync(projectInbox)) {
+      fs.mkdirSync(projectInbox, { recursive: true });
+      created.push('inbox/');
+    }
+    const inboxGitignore = path.join(projectInbox, '.gitignore');
+    if (!fs.existsSync(inboxGitignore)) {
+      fs.writeFileSync(inboxGitignore, '*\n!.gitignore\n', 'utf8');
+      created.push('inbox/.gitignore');
+    }
+
+    if (intakeCap.dedup === 'sha256') {
+      const { saveManifest, loadManifest, MANIFEST_REL_PATH } = await import('./intake/manifest.mjs');
+      const manifestExists = fs.existsSync(path.join(target, MANIFEST_REL_PATH));
+      if (!manifestExists) {
+        saveManifest(target, loadManifest(target));
+        created.push(MANIFEST_REL_PATH);
+      }
+    }
+  }
+
+  // Ensure `.cx/` is in project .gitignore. .cx/ is runtime state — observations,
+  // sessions, vector index, and traces (with daily JSONL files that can exceed
+  // GitHub's 100 MB file-size limit). Idempotent: if `.cx/` (or a broader
+  // pattern like `.cx` / `*` / `**`) already matches, leave the file alone.
+
+  try {
+    const gitignorePath = path.join(target, '.gitignore');
+    const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+    const lines = existing.split('\n').map((l) => l.trim());
+    const alreadyIgnored = lines.some((l) =>
+      l === '.cx' || l === '.cx/' || l === '.cx/**' || l === '*' || l === '**'
+    );
+    if (!alreadyIgnored) {
+      const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+      const block = `${prefix}\n# Construct runtime state — local-only, never source\n.cx/\n`;
+      fs.writeFileSync(gitignorePath, existing + block, 'utf8');
+      created.push(existing.length === 0 ? '.gitignore (added .cx/)' : '.gitignore (appended .cx/)');
+    }
+  } catch (err) {
+    console.warn(`⚠️  Could not update .gitignore: ${err.message}`);
+  }
+
   // Stage .construct/ launcher + sync .claude/ adapters so init produces the
   // same project shape as a fresh `npm install` of the package as a dep.
 
@@ -911,23 +980,12 @@ async function main() {
       created.push('.claude/ (agents + settings)');
     }
 
-    // Also sync home-level adapters for all 6 host surfaces (Copilot, OpenCode,
-    // Codex, VS Code, Cursor, plus Claude home) so the user's environment is
-    // fully wired after init. Project-local Claude adapters were written above.
-    const syncScript = path.join(ROOT_DIR, 'scripts', 'sync-specialists.mjs');
-    if (fs.existsSync(syncScript)) {
-      const { spawnSync } = await import('node:child_process');
-      const homeResult = spawnSync(process.execPath, [syncScript], {
-        cwd: target,
-        stdio: 'pipe',
-        env: { ...process.env, CONSTRUCT_PROJECT_ROOT: target },
-        timeout: 120000,
-      });
-      if (homeResult.status !== 0) {
-        const errMsg = homeResult.stderr.toString().substring(0, 200);
-        console.warn(`⚠️  Home adapter sync had issues (exit ${homeResult.status}): ${errMsg}`);
-      }
-    }
+    // construct init writes project scope only. Global wiring (the `construct`
+    // front-door agent in `~/.claude/agents/`, `~/.codex/agents/`, etc.) is
+    // installed once by `construct sync --global` or the npm postinstall.
+    // Specialists, slash commands, and skills live with the repo per each
+    // host's documented best-practice scope.
+
   } catch (err) {
     console.warn(`⚠️  Adapter staging failed: ${err.message}`);
   }
@@ -987,6 +1045,15 @@ async function main() {
   // pipeline. User can opt in later via `construct config intake.includeProjectInbox=true`.
 
   if (inboxDecision.skip) intakeConfig.includeProjectInbox = false;
+
+  // Archetype: flip includeArchetypeInbox on so resolveInboxDirs picks up
+  // the project-root inbox/ drop zone alongside .cx/inbox/. Mirrors the
+  // existing includeProjectInbox / includeDocsIntake toggles rather than
+  // polluting parentDirs (which is reserved for user-explicit dirs).
+
+  if (intakeCap?.inbox) {
+    intakeConfig.includeArchetypeInbox = true;
+  }
   const { saveIntakeConfig } = await import('./intake/intake-config.mjs');
   try {
     saveIntakeConfig(target, intakeConfig);