@geraldmaron/construct 1.0.20 → 1.0.23

package/lib/init-unified.mjs

@@ -14,7 +14,6 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import {
-  buildAgentsGuide,
   buildContextJson,
   buildContextMarkdown,
   buildPlanTemplate,
@@ -23,6 +22,7 @@ import {
 import { multiSelect } from './tty-prompts.mjs';
 import { execSync, spawnSync } from 'node:child_process';
 import { stageProjectAdapters } from './install/stage-project.mjs';
+import { missingIgnorePatterns, isConstructPackageRepo } from './host-disposition.mjs';
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const ROOT_DIR = path.join(__dirname, "..");
@@ -53,6 +53,20 @@ const skipInteractive = !interactive;
 // templates/ already exist (issue #97).
 const forceScaffold = args.includes("--force");
 
+// `bd init` is git-native and unconditionally commits its bootstrap; ADR-0027
+// §3 requires init to leave the host repo's commit history untouched unless the
+// user opts in. --commit-bootstrap keeps that commit; the default withholds it.
+const commitBootstrap = args.includes("--commit-bootstrap");
+
+// Adapter selection (construct-4xy6 / ADR-0027 §1). By default init writes
+// adapters only for hosts detected on the machine; --with-<host> force-includes
+// one, --all-hosts writes every adapter set. Copilot (`.github/`) is opt-in only
+// — never written by detection — so init never touches a repo's CI directory
+// without --with-copilot.
+const HOST_FLAG_KEYS = ["claude", "codex", "opencode", "vscode", "cursor", "copilot"];
+const withHostFlags = new Set(HOST_FLAG_KEYS.filter((k) => args.includes(`--with-${k}`)));
+const allHosts = args.includes("--all-hosts");
+
 // Active profile selector. `--profile=<id>` writes the field into the
 // project's construct.config.json so resolveActiveProfile picks it up
 // on first run. Unknown ids are rejected with the available catalog.
@@ -322,61 +336,35 @@ function normalizeAnswer(value) {
 
 
 
-function buildDocsReadme(projectName) {
-  return `# ${projectName} Documentation
-
-This directory contains the structured documentation system for ${projectName}.
-
-## Lanes
-
-Each subdirectory represents a documentation lane with a specific purpose:
-
-- **adr/** – Architecture decision records
-- **briefs/** – Research, evidence, and one-pager documents  
-- **changelogs/** – User-facing release notes
-- **intake/** – Raw source material awaiting processing
-- **memos/** – Decision memos and internal arguments
-- **meetings/** – Meeting notes and minutes
-- **notes/** – Working notes and lightweight context
-- **onboarding/** – Setup guides and first-day workflows
-- **postmortems/** – Blameless incident reports
-- **prds/** – Product and capability requirement documents
-- **rfcs/** – Architecture and implementation proposals
-- **runbooks/** – Operational procedures and diagnostics
-
-## Usage
-
-### Adding Documents
-
-Place new documents in the appropriate lane directory. Each lane has templates in its \`templates/\` subdirectory.
+// Index only the lanes actually scaffolded — advertising lanes that have no
+// directory sends readers to dead links. Project-framed: this is the team's doc
+// surface, not Construct's tooling, so the body carries no `construct` commands.
 
-### Consistency Rules
-
-- Use the templates as starting points
-- Keep documents focused on one lane's purpose
-- Update related documents when making changes
-- Link to beads issues in \`plan.md\`
-
-### Quality Gates
+function buildDocsReadme(projectName, selectedLanes = []) {
+  const laneLines = [...selectedLanes]
+    .sort()
+    .map((lane) => {
+      const meta = DOC_LANES[lane];
+      const label = meta?.title ?? lane;
+      const laneDir = meta?.dir ?? lane;
+      const desc = meta?.description ?? "Custom documentation lane.";
+      return `- [${label}](./${laneDir}/) — ${desc}`;
+    });
 
-Run \`construct docs:verify\` to check documentation quality.
+  return `# ${projectName} Documentation
 
-\`\`\`bash
-# Validate all documentation
-construct docs:verify
+> The canonical home for this project's long-lived documents — decision records, briefs, notes, and runbooks.
 
-# Quick check (critical only)
-construct docs:verify --quick
+## Operating model
 
-# Attempt to fix issues
-construct docs:verify --fix
-\`\`\`
+- Keep each document focused on one lane's purpose; start from the per-lane \`templates/\`.
+- Link durable work to the project's tracker and \`plan.md\`, and update related documents in the same change.
+- Prune a lane when it stops serving a real purpose rather than letting it collect stale templates.
 
-## Maintenance
+## Lanes
 
-- Review documentation quarterly with \`construct init:update\`
-- Remove stale documents that no longer reflect reality
-- Update README.md when architecture changes`;
+${laneLines.join("\n")}
+`;
 }
 
 function buildLaneReadme(laneKey) {
@@ -698,52 +686,28 @@ async function askIntakeCollection(targetPath, skipInteractive) {
   return { parentDirs: selected, maxDepth: 4 };
 }
 
+// A greenfield README belongs to the project, not to Construct: a neutral
+// skeleton the owner fills in. Construct's presence is one delineated pointer to
+// AGENTS.md, never project-identity content or a tooling command reference —
+// matching how a native agent stays out of the host's README (ADR-0027 §2).
+
 function buildProjectReadme(projectName) {
   return `# ${projectName}
 
-## Getting Started
-
-This project uses [Construct](https://github.com/geraldmaron/construct) for agentic software development.
-
-## Usage
-
-From inside OpenCode, Claude Code, or similar agent surfaces:
-
-\`\`\`text
-@construct build the feature and ship it when it's verified
-@construct fix the bug  
-@construct review the changes before release
-\`\`\`
+> Briefly describe what this project does and who it is for.
 
-Construct routes work across specialists, maintains project state, and ensures quality gates pass before shipping.
+## Getting started
 
-## Project Structure
-
-- \`AGENTS.md\` — Operating contract for AI agents
-- \`plan.md\` — Current implementation plan
-- \`.cx/context.md\` — Session context and handoff state
-- \`docs/\` — Documentation system (if initialized with \`construct init --docs-preset\`)
+Document how to install dependencies and run the project.
 
 ## Development
 
-\`\`\`bash
-# Initialize project with Construct
-construct init --docs-preset=lean
-
-# Check documentation quality
-construct docs:verify
+Document how to build, test, and contribute.
 
-# Run tests
-npm test
-\`\`\`
+---
 
-## CI Enforcement
-
-This project enforces documentation quality:
-- README.md must exist and be current
-- AGENTS.md must have required sections
-- plan.md must be updated weekly
-- .cx/context.md must track active work`;
+<sub>Agent workflows for this repository are configured in [\`AGENTS.md\`](AGENTS.md), managed with [Construct](https://github.com/geraldmaron/construct).</sub>
+`;
 }
 
 function preflight(target) {
@@ -776,11 +740,45 @@ function preflight(target) {
   return { clean };
 }
 
-function initializeBeadsTracker(target) {
+function gitHeadSha(cwd) {
+  const r = spawnSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+// Restore the host repo's commit pointer to where init found it, leaving every
+// bd-written file in the working tree (uncommitted, unstaged) for the user to
+// commit on their own terms. When the bootstrap commit was the repo's first,
+// drop the branch ref so the repo returns to "no commits yet". bd's issue data
+// lives in Dolt, not this git commit, so the tracker stays fully functional.
+
+function undoBootstrapCommit(cwd, headBefore) {
+  const headAfter = gitHeadSha(cwd);
+  if (!headAfter || headAfter === headBefore) return false;
+  if (headBefore) {
+    spawnSync("git", ["reset", "--mixed", headBefore], { cwd, stdio: "ignore" });
+  } else {
+    spawnSync("git", ["update-ref", "-d", "HEAD"], { cwd, stdio: "ignore" });
+    spawnSync("git", ["reset"], { cwd, stdio: "ignore" });
+  }
+  return true;
+}
+
+function initializeBeadsTracker(target, { commitBootstrap = false } = {}) {
+  // bd init prints verbose, host-specific output (a doubled "Claude Code
+  // integration installed", a "Restart Claude Code" line that ignores the other
+  // synced hosts) that interleaves with Construct's own flow. Capture it and let
+  // the caller print one clean summary; the captured prefix names the issue ids.
+
+  // bd init is git-native and unconditionally commits its bootstrap (.beads/*,
+  // .gitignore, agent files) with no flag to suppress it. Capture HEAD first so
+  // the commit can be withheld unless --commit-bootstrap (ADR-0027 §3).
+
+  const headBefore = gitHeadSha(target);
+
   const result = spawnSync("bd", ["init"], {
     cwd: target,
     encoding: "utf8",
-    stdio: "inherit",
+    stdio: ["ignore", "pipe", "pipe"],
     killSignal: "SIGTERM",
     timeout: 30_000,
   });
@@ -792,8 +790,42 @@ function initializeBeadsTracker(target) {
     throw result.error;
   }
   if (result.status !== 0) {
-    throw new Error(`bd init exited with code ${result.status ?? "unknown"}`);
+    const tail = (result.stderr || result.stdout || "").trim().split("\n").slice(-2).join(" ");
+    throw new Error(`bd init exited with code ${result.status ?? "unknown"}${tail ? `: ${tail}` : ""}`);
   }
+  const withheldCommit = commitBootstrap ? false : undoBootstrapCommit(target, headBefore);
+  const prefixMatch = (result.stdout || "").match(/Issue prefix:\s*(\S+)/);
+  return { prefix: prefixMatch ? prefixMatch[1] : null, withheldCommit };
+}
+
+// Resolve the host adapter sets init should write (construct-4xy6). Returns null
+// for "all hosts" (--all-hosts), otherwise the union of detected hosts and
+// --with-<host> flags. Copilot is excluded from detection so `.github/` is only
+// written on explicit --with-copilot; selecting VS Code pulls in claude because
+// VS Code reads `.claude/agents` natively; an empty result falls back to claude.
+
+async function resolveAdapterHosts() {
+  if (allHosts) return null;
+  const detected = new Set();
+  try {
+    const { detectHostCapabilities } = await import('./host-capabilities.mjs');
+    const nameToKey = {
+      'Claude Code': 'claude',
+      'OpenCode': 'opencode',
+      'Codex': 'codex',
+      'VS Code': 'vscode',
+      'Cursor': 'cursor',
+      'Copilot': 'copilot',
+    };
+    for (const cap of detectHostCapabilities()) {
+      if (cap.availability === 'installed' && nameToKey[cap.host]) detected.add(nameToKey[cap.host]);
+    }
+  } catch { /* detection is advisory; fall back to flags + baseline */ }
+  detected.delete('copilot');
+  const selected = new Set([...detected, ...withHostFlags]);
+  if (selected.has('vscode')) selected.add('claude');
+  if (selected.size === 0) selected.add('claude');
+  return HOST_FLAG_KEYS.filter((k) => selected.has(k));
 }
 
 async function main() {
@@ -813,27 +845,49 @@ async function main() {
     console.log(`Initializing Construct in ${path.relative(process.cwd(), target) || "."}`);
   }
 
-  // Persist --profile=<id> into construct.config.json. Validate against the
-  // curated catalog so a typo never silently falls back to rnd.
-  if (profileId) {
-    const { loadProfile, listProfiles } = await import('./profiles/loader.mjs');
-    if (!loadProfile(profileId)) {
-      console.error(`Unknown profile: ${profileId}. Available: ${listProfiles().join(', ')}`);
-      process.exit(1);
-    }
+  // Scaffold the central project config so the configuration surface is
+  // discoverable (ADR-0027 §1 / construct-e13x). Organized by design —
+  // surfaces all major configurable blocks (deployment, telemetry,
+  // orchestration, etc.) so the user can discover and edit options easily.
+  // A fresh file is written on every init; skip-if-exists preserves user edits.
+
+  {
     const { findProjectConfigPath, loadProjectConfig, writeProjectConfig, PROJECT_CONFIG_FILENAME } = await import('./config/project-config.mjs');
+    const { DEFAULT_PROJECT_CONFIG } = await import('./config/schema.mjs');
+
+    if (profileId) {
+      const { loadProfile, listProfiles } = await import('./profiles/loader.mjs');
+      if (!loadProfile(profileId)) {
+        console.error(`Unknown profile: ${profileId}. Available: ${listProfiles().join(', ')}`);
+        process.exit(1);
+      }
+    }
     const found = findProjectConfigPath(target);
     const cfgPath = found || path.join(target, PROJECT_CONFIG_FILENAME);
 
-    // 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}.`);
+    // loadProjectConfig returns { path, raw, config, source }. Persist .raw (the
+    // on-disk JSON) so user customizations survive and defaults are not silently
+    // materialized into the file.
+
+    if (!found) {
+      const cfg = {
+        $schema: "./node_modules/@geraldmaron/construct/schemas/project-config.schema.json",
+        ...DEFAULT_PROJECT_CONFIG,
+        profile: profileId || 'rnd',
+      };
+      // Explicitly write the full default config object so all options are
+      // visible and discoverable to the user in the file. The $schema property
+      // provides inline documentation and validation in supported editors.
+      writeProjectConfig(cfgPath, cfg, { validate: true, silent: true });
+      created.push(PROJECT_CONFIG_FILENAME);
+      if (!quiet && profileId) console.log(`Profile set to ${profileId}.`);
+    } else if (profileId) {
+      const loaded = loadProjectConfig(target);
+      const cfg = loaded?.raw ? { ...loaded.raw } : { version: 1 };
+      cfg.profile = profileId;
+      writeProjectConfig(cfgPath, cfg, { validate: true, silent: true });
+      if (!quiet) console.log(`Profile set to ${profileId}.`);
+    }
   }
 
   // Resolve active profile to drive capability-gated scaffolding (intake
@@ -846,16 +900,11 @@ async function main() {
   const { gatherAttribution } = await import('./intake/attribution.mjs');
   const attribution = intakeCap?.attribution ? gatherAttribution() : null;
 
-  // Always create core Construct files
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, "AGENTS.md"),
-    content: buildAgentsGuide(projectName),
-    generator: "construct/init",
-    attribution,
-  });
+  // AGENTS.md and CLAUDE.md are user-owned files (ADR-0027 §2). Construct does
+  // not author their bodies — bd init creates them with the project skeleton and
+  // the Beads block, and the injectIntoAgentFile pass below adds Construct's
+  // guidance as a fenced marker block only. Pre-writing a doctrine body here
+  // would land un-fenced Construct content that sync/doctor cannot reconcile.
 
   writeStampedIfMissing({
     targetRoot: target,
@@ -886,15 +935,10 @@ async function main() {
     attribution,
   });
   
-  writeStampedIfMissing({
-    targetRoot: target,
-    created,
-    skipped,
-    filePath: path.join(target, ".cx", ".gitkeep"),
-    content: "",
-    generator: "construct/init",
-  });
-  
+  // `.cx/` already exists from the context writes above and is gitignored in full
+  // (ADR-0027), so a keep file there could never be tracked. No dead keep file is written.
+
+
   // 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
@@ -909,21 +953,19 @@ async function main() {
     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",
-    });
+    // `.cx/inbox/` is the local intake drop zone the watcher polls; under the gitignored
+    // `.cx/` tree the directory must exist on disk but needs no keep file.
+
+    fs.mkdirSync(path.join(target, ".cx", "inbox"), { recursive: true });
+    created.push(".cx/inbox/");
   }
 
   // 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.
+  // capabilities.intake.inbox, scaffold a project-root inbox/ drop zone and seed
+  // the dedup manifest. The whole inbox/ is ignored via host-disposition
+  // IGNORED_PATTERNS (ADR-0027 §1), so raw drops never enter source and no local
+  // keep-file is needed. Existing-structure detection already opted out of
+  // clobbering a user's pipeline above.
 
   if (intakeCap?.inbox && !inboxDecision.skip) {
     const projectInbox = path.join(target, 'inbox');
@@ -931,11 +973,6 @@ async function main() {
       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');
@@ -947,104 +984,170 @@ async function main() {
     }
   }
 
-  // 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.
+  // Gitignore every Construct-generated artifact whose disposition is `ignored`
+  // (ADR-0027 §1): the six adapter dirs, the `.construct/` launcher, `.cx/`
+  // runtime state, and the generated config files all carry machine-specific
+  // absolute paths (MCP server paths, env-resolved tokens) and are recreated by
+  // `construct sync`, so they are never committed. Mirrors Construct's own repo
+  // .gitignore 1:1. Idempotent per-pattern: a pattern already matched exactly,
+  // by its bare/slashed form, or by a broader `*` / `**`, is left untouched.
 
-  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/)');
+  const isToolRepo = isConstructPackageRepo(target);
+
+  if (!isToolRepo) {
+    try {
+      const gitignorePath = path.join(target, '.gitignore');
+      const existing = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
+      const missing = missingIgnorePatterns(existing);
+      if (missing.length > 0) {
+        const prefix = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+        const block = `${prefix}\n# Construct — generated adapters, launcher, and runtime state.\n# Machine-specific, recreated by \`construct sync\`; never source (ADR-0027).\n${missing.join('\n')}\n`;
+        fs.writeFileSync(gitignorePath, existing + block, 'utf8');
+        created.push(existing.length === 0 ? '.gitignore (Construct ignores)' : `.gitignore (+${missing.length} Construct ignore${missing.length === 1 ? '' : 's'})`);
+      }
+    } catch (err) {
+      console.warn(`⚠️  Could not update .gitignore: ${err.message}`);
     }
-  } catch (err) {
-    console.warn(`⚠️  Could not update .gitignore: ${err.message}`);
+  } else if (verbose) {
+    console.log('[init:conflation] inside Construct repository; skipping .gitignore mutation.');
   }
 
-  // Stage .construct/ launcher + sync .claude/ adapters so init produces the
-  // same project shape as a fresh `npm install` of the package as a dep.
+  // Resolve which host adapter sets to write (construct-4xy6). Default: the
+  // hosts detected on this machine, plus any --with-<host>. VS Code reads
+  // .claude/agents natively, so selecting it pulls in claude. Copilot is opt-in
+  // only — never written by detection. --all-hosts writes every set; an empty
+  // selection falls back to the .claude/ baseline so a project is never bare.
 
-  try {
-    let pkgVersion = '';
+  const adapterHosts = await resolveAdapterHosts();
+
+  // Stage .construct/ launcher + sync the selected adapter sets so init produces
+  // the same project shape as a fresh `npm install` of the package as a dep.
+
+  if (!isToolRepo) {
     try {
-      pkgVersion = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf8')).version || '';
-    } catch { /* fall through with empty version */ }
-    const stagingPre = fs.existsSync(path.join(target, '.construct', 'run.mjs'));
-    const claudePre = fs.existsSync(path.join(target, '.claude', 'settings.json'));
-    stageProjectAdapters({
-      projectRoot: target,
-      packageRoot: ROOT_DIR,
-      pkgVersion,
-      log: (msg) => console.log(`[init:stage] ${msg}`),
-    });
-    if (!stagingPre && fs.existsSync(path.join(target, '.construct', 'run.mjs'))) {
-      created.push('.construct/ (launcher staged)');
-    }
-    if (!claudePre && fs.existsSync(path.join(target, '.claude', 'settings.json'))) {
-      created.push('.claude/ (agents + settings)');
-    }
+      let pkgVersion = '';
+      try {
+        pkgVersion = JSON.parse(fs.readFileSync(path.join(ROOT_DIR, 'package.json'), 'utf8')).version || '';
+      } catch { /* fall through with empty version */ }
+      const stagingPre = fs.existsSync(path.join(target, '.construct', 'run.mjs'));
+      const claudePre = fs.existsSync(path.join(target, '.claude', 'settings.json'));
+      stageProjectAdapters({
+        projectRoot: target,
+        packageRoot: ROOT_DIR,
+        pkgVersion,
+        hosts: adapterHosts,
+        log: (msg) => console.log(`[init:stage] ${msg}`),
+      });
+      if (!quiet && adapterHosts) {
+        console.log(`  Adapters: ${adapterHosts.join(', ')} (add more with --with-<host>, or --all-hosts).`);
+      }
+      if (!stagingPre && fs.existsSync(path.join(target, '.construct', 'run.mjs'))) {
+        created.push('.construct/ (launcher staged)');
+      }
+      if (!claudePre && fs.existsSync(path.join(target, '.claude', 'settings.json'))) {
+        created.push('.claude/ (agents + settings)');
+      }
 
-    // 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.
+      // 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}`);
+    } catch (err) {
+      console.warn(`⚠️  Adapter staging failed: ${err.message}`);
+    }
+  } else if (verbose) {
+    console.log('[init:conflation] inside Construct repository; skipping .construct/ launcher staging.');
   }
 
-  // Written once, never re-copied, so user edits survive subsequent inits
-  // and `npm install` rebuilds. Skip-when-exists is the contract.
+  // Cache a host-agnostic project profile at .cx/project-profile.json (gitignored)
+  // so per-host skill filtering has a signal to scope against. Owned by init —
+  // install must not read the cwd (ADR-0027 §3).
+
+  try {
+    const { detectProjectProfile, writeProfile } = await import('./project-profile.mjs');
+    const profile = detectProjectProfile(target);
+    if (profile.tags.length > 0) {
+      writeProfile(profile, target);
+      created.push('.cx/project-profile.json');
+    }
+  } catch { /* project profiling is advisory; init proceeds */ }
+
+  // Tool orientation describes Construct, not the project, so it belongs in the
+  // ignored .cx/ tree rather than the host repo root — never read as project
+  // content, never committed (ADR-0027 §1). Written once; skip-when-exists keeps
+  // user edits across subsequent inits and `npm install` rebuilds.
 
   const guideSrc = path.join(ROOT_DIR, 'templates', 'docs', 'construct_guide.md');
-  const guideDst = path.join(target, 'construct_guide.md');
+  const guideDst = path.join(target, '.cx', 'construct_guide.md');
   if (fs.existsSync(guideSrc) && !fs.existsSync(guideDst)) {
     try {
+      fs.mkdirSync(path.dirname(guideDst), { recursive: true });
       fs.copyFileSync(guideSrc, guideDst);
-      created.push('construct_guide.md');
+      created.push('.cx/construct_guide.md');
     } catch (err) {
-      console.warn(`⚠️  Could not write construct_guide.md: ${err.message}`);
+      console.warn(`⚠️  Could not write .cx/construct_guide.md: ${err.message}`);
     }
   } else if (fs.existsSync(guideDst)) {
-    skipped.push('construct_guide.md');
+    skipped.push('.cx/construct_guide.md');
   }
 
   // Auto-init beads
   const beadsMeta = path.join(target, ".beads", "metadata.json");
-  if (!fs.existsSync(beadsMeta)) {
-    console.log('');
-    console.log('═══════════════════════════════════════════════════════════');
-    console.log('  TASK TRACKING (beads)');
-    console.log('═══════════════════════════════════════════════════════════');
-    console.log('');
-    console.log('Beads is a local-first issue tracker that keeps your work');
-    console.log('organized without depending on external services like Jira.');
-    console.log('');
-    console.log('Features:');
-    console.log('  • Local SQLite database (no cloud required)');
-    console.log('  • Issues sync to git (optional)');
-    console.log('  • Works offline');
+  if (!fs.existsSync(beadsMeta) && !isToolRepo) {
     console.log('');
-    console.log("Initializing beads tracker...");
+    console.log('Initializing the task tracker (beads — local-first, git-synced, works offline)…');
     fs.mkdirSync(path.join(target, ".beads"), { recursive: true });
     try {
-      initializeBeadsTracker(target);
+      const beads = initializeBeadsTracker(target, { commitBootstrap });
       created.push(".beads/ (initialized)");
+      const prefixNote = beads?.prefix ? ` — issues prefixed \`${beads.prefix}-\`` : "";
+      console.log(`  ✓ Task tracker ready${prefixNote}. Run \`bd quickstart\` to start.`);
+      if (beads?.withheldCommit) {
+        console.log("    Bootstrap files left uncommitted (commit them yourself, or re-run with --commit-bootstrap).");
+      }
     } catch (e) {
       console.warn("⚠️  Beads init failed:", e.message);
     }
     console.log('');
   }
-  
+
+  // Wire the project's git hooks to .beads/hooks so Construct's pre-commit
+  // secret-scan and policy gates activate. Owned by init, not install (ADR-0027
+  // §3): install must never mutate the cwd repo. Idempotent — no-op when
+  // .beads/hooks/pre-commit is absent or a non-default custom path is set.
+
+  try {
+    const { ensureGitHooksPath } = await import('./git-hooks-path.mjs');
+    const hooks = ensureGitHooksPath({ cwd: target });
+    if (hooks.status === 'set') {
+      created.push('git core.hooksPath → .beads/hooks');
+      if (!quiet) console.log(`  ✓ ${hooks.message}`);
+    } else if (hooks.status === 'warning' && !quiet) {
+      console.log(`  ⚠️  ${hooks.message}`);
+    }
+  } catch { /* git-hooks wiring is advisory; init proceeds */ }
+
+  // Inject Construct's integration guidance into AGENTS.md and CLAUDE.md as a
+  // versioned, hash-stamped marker block (ADR-0027 §2). Runs after bd init so
+  // the block survives whatever bd wrote, preserves all content outside the
+  // markers, and dedups against a sibling Beads Integration block. Idempotent:
+  // same hash is a no-op, a version/hash bump replaces the block content only.
+
+  try {
+    const { injectIntoAgentFile, CONSTRUCT_INTEGRATION_VERSION } = await import('./agent-instructions/inject.mjs');
+    for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+      const res = injectIntoAgentFile(path.join(target, name), {
+        version: CONSTRUCT_INTEGRATION_VERSION,
+        header: `# ${projectName}\n`,
+      });
+      if (!res.existed) created.push(`${name} (Construct integration)`);
+    }
+  } catch (err) {
+    console.warn(`⚠️  Could not inject agent-instruction block: ${err.message}`);
+  }
+
   // Intake collection — always write intake-config.json with safe defaults
   // so the user can inspect what's watched and edit the file directly. Empty
   // parentDirs is the correct default: the inbox watcher always scans
@@ -1106,7 +1209,7 @@ async function main() {
     if (lanesToScaffold.length > 0) {
       writeIfMissing(
         path.join(target, "docs", "README.md"),
-        buildDocsReadme(projectName)
+        buildDocsReadme(projectName, lanesToScaffold)
       );
 
       for (const laneKey of lanesToScaffold) {
@@ -1244,22 +1347,20 @@ async function main() {
       
       if (!quiet) {
         console.log('\nServices:');
+        let dashboardUrl = null;
         for (const svc of results) {
           if (svc.status === 'started' || svc.status === 'reused') {
             const status = svc.status === 'reused' ? ' (running)' : '';
-            const url = svc.url ? ` ${svc.url}` : '';
-            console.log(`  ${svc.name}${status}${url}`);
+            console.log(`  ${svc.name}${status}${svc.url ? ` ${svc.url}` : ''}`);
+            if (svc.name === 'Dashboard' && svc.url) dashboardUrl = svc.url;
+          } else if (svc.status === 'failed') {
+            console.log(`  ${svc.name} — failed${svc.note ? ` (${svc.note})` : ''}`);
           }
         }
-        
-        // Show Telemetry credentials if running locally
+
         const telemetrySvc = results.find(r => r.name === 'Telemetry' && r.url?.includes('localhost'));
-        if (telemetrySvc) {
-          console.log(`\nTelemetry: ${telemetrySvc.url}`);
-        }
-        
-        const dashboardPort = process.env.DASHBOARD_PORT || '4242';
-        console.log(`\nDashboard: http://127.0.0.1:${dashboardPort}`);
+        if (telemetrySvc) console.log(`\nTelemetry: ${telemetrySvc.url}`);
+        if (dashboardUrl) console.log(`\nDashboard: ${dashboardUrl}  ·  stop services with \`construct stop\``);
       }
     } catch (error) {
       console.error(`Services could not be started: ${error.message}`);