chati-dev 4.2.1 → 4.3.0

package/src/installer/core.js

@@ -1,11 +1,13 @@
-import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync, readdirSync } from 'fs';
-import { join, dirname } from 'path';
+import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join, dirname, basename } from 'path';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
 import { generateClaudeMCPConfig } from '../config/mcp-configs.js';
 import { generateSessionYaml, generateConfigYaml, generateClaudeMd, generateClaudeLocalMd, generateCodexSkill, generateGeminiRouter, generateGeminiSessionLock, generateAgentsOverrideMd, generateCodexConstitutionGuardRules, generateCodexReadProtectionRules } from './templates.js';
 import { generateContextFiles } from '../config/context-file-generator.js';
 import { adaptFrameworkFile, ADAPTABLE_FILES } from '../config/framework-adapter.js';
+import { generateClaudeSettings } from '../config/claude-settings-generator.js';
 import { generateProviderOverlays } from './provider-overlay.js';
 import { verifyManifest } from './manifest.js';
 
@@ -21,7 +23,15 @@ const FRAMEWORK_SOURCE = existsSync(BUNDLED_SOURCE) ? BUNDLED_SOURCE : MONOREPO_
  * Install Chati.dev framework into target directory
  */
 export async function installFramework(config) {
-  const { targetDir, projectType, language, selectedIDEs, selectedMCPs, projectName, version, llmProvider, allProviders } = config;
+  const { targetDir, projectType, language, selectedIDEs, selectedMCPs, projectName, llmProvider, allProviders } = config;
+  // Always derive version from package.json (single source of truth)
+  let { version } = config;
+  if (!version) {
+    try {
+      const pkgPath = join(__dirname, '..', '..', 'package.json');
+      version = JSON.parse(readFileSync(pkgPath, 'utf-8')).version;
+    } catch { version = 'unknown'; }
+  }
 
   // 0. Verify framework signature (supply chain protection)
   const manifestPath = join(FRAMEWORK_SOURCE, 'manifest.json');
@@ -39,17 +49,36 @@ export async function installFramework(config) {
 
   // 1. Create .chati/ session directory
   createDir(join(targetDir, '.chati'));
-  writeFileSync(
-    join(targetDir, '.chati', 'session.yaml'),
-    generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, llmProvider, allProviders }),
-    'utf-8'
-  );
+  const sessionPath = join(targetDir, '.chati', 'session.yaml');
+  // Preserve existing session.yaml on reinstall/recovery (don't destroy pipeline state).
+  // Only write fresh session if one does not exist.
+  if (!existsSync(sessionPath)) {
+    writeFileSync(
+      sessionPath,
+      generateSessionYaml({ projectName, projectType, language, selectedIDEs, selectedMCPs, llmProvider, allProviders }),
+      'utf-8'
+    );
+  }
 
-  // 2. Create chati.dev/ framework directory (copy from source)
-  const frameworkDir = join(targetDir, 'chati.dev');
+  // 2. Create .chati.dev/ framework directory (hidden — dot prefix)
+  // The source is chati.dev/ in the monorepo; installed as .chati.dev/ in user projects.
+  // Text replacement during copy handles all internal path references.
+  const frameworkDir = join(targetDir, '.chati.dev');
   createDir(frameworkDir);
 
-  // Copy framework structure
+  // 2b. Create artifacts/ at PROJECT ROOT (visible to user — this is their output)
+  const artifactsDir = join(targetDir, 'artifacts');
+  const artifactDirs = [
+    '0-WU', '1-Brief', '2-PRD',
+    '3-Architecture', '4-UX', '5-Phases',
+    '6-Tasks', '7-QA-Planning', '8-QA-Visual', '9-QA-Implementation', '10-Deploy',
+    'handoffs', 'decisions',
+  ];
+  for (const dir of artifactDirs) {
+    createDir(join(artifactsDir, dir));
+  }
+
+  // Copy framework structure (everything EXCEPT artifacts, which live at root)
   const frameworkDirs = [
     'orchestrator',
     'agents/discover', 'agents/plan', 'agents/quality', 'agents/build', 'agents/deploy',
@@ -57,10 +86,6 @@ export async function installFramework(config) {
     'schemas', 'frameworks', 'intelligence', 'patterns',
     'hooks', 'domains', 'domains/agents', 'domains/workflows',
     'i18n', 'migrations', 'data', 'context',
-    'artifacts/0-WU', 'artifacts/1-Brief', 'artifacts/2-PRD',
-    'artifacts/3-Architecture', 'artifacts/4-UX', 'artifacts/5-Phases',
-    'artifacts/6-Tasks', 'artifacts/7-QA-Planning', 'artifacts/9-QA-Implementation', 'artifacts/10-Deploy',
-    'artifacts/handoffs', 'artifacts/decisions',
   ];
 
   for (const dir of frameworkDirs) {
@@ -81,6 +106,7 @@ export async function installFramework(config) {
     'tasks/durable', 'tasks/daily',
     'qa-planning/durable', 'qa-planning/daily',
     'qa-implementation/durable', 'qa-implementation/daily',
+    'qa-visual/durable', 'qa-visual/daily',
     'dev/durable', 'dev/daily',
     'devops/durable', 'devops/daily',
   ];
@@ -96,6 +122,31 @@ export async function installFramework(config) {
     generateProviderOverlays(targetDir, FRAMEWORK_SOURCE, llmProvider || 'claude', allProviders);
   }
 
+  // Bundle the CLI source into the framework dir so chati-router.js can run
+  // commands locally without depending on `npx chati-dev` (which fetches from
+  // the npm registry — version drift causes inconsistent behavior).
+  // Result: every install is self-contained; no network/cache dependency at runtime.
+  copyCliSource(
+    join(__dirname, '..'),                         // packages/chati-dev/src/
+    join(frameworkDir, '_cli')                     // .chati.dev/_cli/
+  );
+
+  // The bundled CLI imports ../../framework/hooks/model-governance.js relative
+  // to _cli/terminal/prompt-builder.js. Starting at .chati.dev/_cli/terminal/,
+  // `../../` resolves to .chati.dev/ — so the hooks copy must land at
+  // .chati.dev/framework/hooks/ to satisfy the import path.
+  copyDirVerbatim(
+    join(__dirname, '..', '..', 'framework', 'hooks'),
+    join(frameworkDir, 'framework', 'hooks')
+  );
+
+  // Also bundle production deps so the CLI can import js-yaml/chalk/etc. at runtime
+  // without relying on a node_modules tree in the user's project.
+  copyCliDependencies(
+    join(__dirname, '..', '..'),                    // packages/chati-dev/
+    join(frameworkDir, '_cli', 'node_modules')      // .chati.dev/_cli/node_modules/
+  );
+
   // Write config.yaml
   writeFileSync(
     join(frameworkDir, 'config.yaml'),
@@ -109,8 +160,8 @@ export async function installFramework(config) {
     const ideProvider = IDE_TO_PROVIDER[ideKey];
     const isSecondary = ideProvider && ideProvider !== primary && allProviders && allProviders.length > 1;
     const orchestratorPath = isSecondary
-      ? `chati.dev/.adapted/${ideProvider}/orchestrator/chati.md`
-      : 'chati.dev/orchestrator/chati.md';
+      ? `.chati.dev/.adapted/${ideProvider}/orchestrator/chati.md`
+      : '.chati.dev/orchestrator/chati.md';
     await configureIDE(targetDir, ideKey, selectedMCPs, { orchestratorPath, isSecondary, providerName: ideProvider });
   }
 
@@ -128,11 +179,22 @@ export async function installFramework(config) {
     for (const file of contextFiles) {
       const src = join(FRAMEWORK_SOURCE, 'context', file);
       if (existsSync(src)) {
-        copyFileSync(src, join(claudeRulesDir, file));
+        // Apply path replacement so rules reference .chati.dev/ not chati.dev/
+        let content = readFileSync(src, 'utf-8');
+        content = applyPathReplacement(content);
+        writeFileSync(join(claudeRulesDir, file), content, 'utf-8');
       }
     }
 
-    writeFileSync(join(targetDir, 'CLAUDE.md'), baseContent, 'utf-8');
+    // Preserve existing CLAUDE.md on reinstall — user or magic-docs may have
+    // edited it. Section-aware merge if exists; fresh write if not.
+    const claudeMdPath = join(targetDir, 'CLAUDE.md');
+    if (existsSync(claudeMdPath)) {
+      const existingClaudeMd = readFileSync(claudeMdPath, 'utf-8');
+      writeFileSync(claudeMdPath, mergeClaudeMd(existingClaudeMd, baseContent), 'utf-8');
+    } else {
+      writeFileSync(claudeMdPath, baseContent, 'utf-8');
+    }
     writeFileSync(join(targetDir, 'CLAUDE.local.md'), generateClaudeLocalMd(), 'utf-8');
   }
 
@@ -171,6 +233,8 @@ const FRAMEWORK_DIRS_TO_COPY = [
   'context',
   'tasks',
   'presets',
+  'scripts',
+  'scaffold',
 ];
 
 /**
@@ -181,8 +245,39 @@ const FRAMEWORK_ROOT_FILES = [
 ];
 
 /**
- * Recursively copy a directory from source to destination, applying provider
- * adaptation for files listed in ADAPTABLE_FILES when the provider is not Claude.
+ * Text file extensions that get path replacement during copy.
+ * Binary files (.png, .woff2, etc.) are copied without modification.
+ */
+const TEXT_EXTENSIONS = new Set(['.md', '.js', '.yaml', '.yml', '.json', '.html', '.toml', '.txt', '.rules']);
+
+/**
+ * Apply installed-path replacement to file content.
+ *
+ * Source uses `chati.dev/` everywhere. Installed project uses:
+ * - `.chati.dev/` for framework files (hidden)
+ * - `artifacts/` at project root for user-visible output
+ *
+ * Order matters: replace `chati.dev/artifacts/` FIRST (→ `artifacts/`),
+ * then `chati.dev/` (→ `.chati.dev/`). Reversing would produce `.chati.dev/artifacts/`.
+ */
+function applyPathReplacement(content) {
+  return content
+    // Step 1: artifacts at root (must be before generic replace)
+    .replace(/chati\.dev\/artifacts\//g, 'artifacts/')
+    // Step 2: path strings with slash — but NOT if already prefixed with dot
+    // (negative lookbehind for any char that would create `.chati.dev` already)
+    .replace(/(?<!\.)chati\.dev\//g, '.chati.dev/')
+    // Step 3: quoted dir name in JS join() calls (WITHOUT slash)
+    // Only match 'chati.dev' (the DIRECTORY, with dot) not 'chati-dev' (the NPM PACKAGE, with dash)
+    // Also: avoid double-prefixing if already '.chati.dev' in source
+    .replace(/(?<!\.)'chati\.dev'/g, "'.chati.dev'")
+    .replace(/(?<!\.)"chati\.dev"/g, '".chati.dev"');
+}
+
+/**
+ * Recursively copy a directory from source to destination, applying:
+ * 1. Path replacement (chati.dev/ → .chati.dev/, artifacts/ at root)
+ * 2. Provider adaptation for non-Claude providers
  */
 function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
   if (!existsSync(srcDir)) return;
@@ -195,14 +290,24 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
     const relPath = relBase ? join(relBase, entry.name) : entry.name;
 
     if (entry.isDirectory()) {
+      // Skip artifacts/ — those live at project root, not inside .chati.dev/
+      if (entry.name === 'artifacts') continue;
       copyDirRecursive(srcPath, destPath, provider, relPath);
     } else if (entry.isFile()) {
-      if (provider !== 'claude' && ADAPTABLE_FILES.has(relPath)) {
-        // Non-Claude provider: read, adapt, write
-        const content = readFileSync(srcPath, 'utf-8');
-        writeFileSync(destPath, adaptFrameworkFile(content, relPath, provider), 'utf-8');
+      const ext = entry.name.includes('.') ? '.' + entry.name.split('.').pop() : '';
+      const isText = TEXT_EXTENSIONS.has(ext);
+
+      if (isText) {
+        let content = readFileSync(srcPath, 'utf-8');
+        // Always apply path replacement for installed location
+        content = applyPathReplacement(content);
+        // Provider adaptation on top (for non-Claude)
+        if (provider !== 'claude' && ADAPTABLE_FILES.has(relPath)) {
+          content = adaptFrameworkFile(content, relPath, provider);
+        }
+        writeFileSync(destPath, content, 'utf-8');
       } else {
-        // Claude or non-adaptable: direct copy
+        // Binary file: direct copy
         copyFileSync(srcPath, destPath);
       }
     }
@@ -221,18 +326,18 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
 export function copyFrameworkFiles(destDir, provider = 'claude') {
   if (!existsSync(FRAMEWORK_SOURCE)) return;
 
-  // Copy loose root files
+  // Copy loose root files (with path replacement)
   for (const file of FRAMEWORK_ROOT_FILES) {
     const src = join(FRAMEWORK_SOURCE, file);
     if (!existsSync(src)) continue;
     const dest = join(destDir, file);
     createDir(dirname(dest));
+    let content = readFileSync(src, 'utf-8');
+    content = applyPathReplacement(content);
     if (provider !== 'claude' && ADAPTABLE_FILES.has(file)) {
-      const content = readFileSync(src, 'utf-8');
-      writeFileSync(dest, adaptFrameworkFile(content, file, provider), 'utf-8');
-    } else {
-      copyFileSync(src, dest);
+      content = adaptFrameworkFile(content, file, provider);
     }
+    writeFileSync(dest, content, 'utf-8');
   }
 
   // Copy each framework directory recursively
@@ -256,40 +361,47 @@ async function configureIDE(targetDir, ideKey, selectedMCPs, options = {}) {
 
   if (ideKey === 'claude-code') {
     // Thin router
-    const routerContent = `# /chati — Thin Router
-
-## CRITICAL — Language Override
+    const routerContent = `# /chati — Deterministic Router
 
-Read \`.chati/session.yaml\` field \`language\` BEFORE anything else.
-ALL responses MUST be in this language. This overrides any global IDE language setting.
+## STEP 0 — Run the deterministic pipeline router (MUST be first)
 
-| Value | Language |
-|-------|----------|
-| \`en\`  | English |
-| \`pt\`  | Portugues |
-| \`es\`  | Espanol |
-| \`fr\`  | Francais |
+Run via Bash:
+\`\`\`
+node .chati.dev/orchestrator/chati-router.js
+\`\`\`
 
-If session.yaml does not exist or has no language field, default to English.
+Parse the JSON output. This single command already handled: license validation, integrity check, session state, pipeline routing, and team registration (if needed). You do NOT need to run any of these separately.
 
----
+### If \`ok\` is false:
 
-## Load
+| \`error\` value | What to tell the user |
+|---|---|
+| \`license_invalid\` | Display \`license.reason\` as a friendly message. STOP. |
+| \`license_guard_missing\` | "License enforcement is missing. Reinstall with: npx chati-dev init". STOP. |
+| \`integrity_failed\` | "License enforcement was tampered with. Reinstall with: npx chati-dev init". STOP. |
+| anything else | Display error. STOP. |
 
-Read and execute the full orchestrator at \`${orchestratorPath || 'chati.dev/orchestrator/chati.md'}\`.
+### If \`ok\` is true:
 
-Pass through all context: session state, handoffs, artifacts, and user input.
+1. Use \`session.language\` for ALL responses (pt = Português, en = English, es = Español, fr = Français).
+2. Read the full orchestrator at \`${orchestratorPath || '.chati.dev/orchestrator/chati.md'}\`.
+3. The \`action\` field tells you what to do. Go to the matching "Action:" section in the orchestrator.
+4. **If \`action\` is \`spawn_team\`**: the team is ALREADY registered (Step 1 already ran as code). The \`team\` object contains \`team_id\`, \`task_list_path\`, \`mailbox_path\`, \`members\`. Go directly to "Action: Spawn Team" Step 2 and use these values in the agent prompts. DO NOT run \`orchestrate spawn-team\` again — it already ran.
+5. **If \`action\` is \`setup\`**: this is a new project. Follow "Action: Setup".
+6. For any other action: follow the matching section in the orchestrator.
 
-**Context to pass:**
-- \`.chati/session.yaml\` (session state — includes language)
-- \`CLAUDE.local.md\` (runtime state — session lock, current agent)
-- \`chati.dev/artifacts/handoffs/\` (latest handoff)
-- \`chati.dev/config.yaml\` (version info)
+**The \`pipeline\` object contains the full JSON from \`orchestrate next\`.** Use its fields (agent_file, spawn_command, handoff_status, etc.) as documented in the orchestrator.
 
 **User input:** $ARGUMENTS
 `;
     writeFileSync(join(targetDir, '.claude', 'commands', 'chati.md'), routerContent, 'utf-8');
 
+    // .claude/settings.json — wires the 10 chati.dev hooks into Claude Code's
+    // hook system and applies a baseline permission policy. THIS IS THE FILE
+    // CLAUDE CODE READS — without it, every hook in chati.dev/hooks/ is dormant.
+    // (Pre-v4.2.2 bug: this file was never written, hooks never ran.)
+    writeClaudeSettingsWithMerge(join(targetDir, '.claude', 'settings.json'));
+
     // MCP config
     if (selectedMCPs.length > 0) {
       const mcpConfig = generateClaudeMCPConfig(selectedMCPs);
@@ -307,10 +419,35 @@ Pass through all context: session state, handoffs, artifacts, and user input.
     // Session lock override file (equivalent to CLAUDE.local.md)
     writeFileSync(join(targetDir, 'AGENTS.override.md'), generateAgentsOverrideMd(), 'utf-8');
 
-    // Starlark execution policies (equivalent to Claude hooks for constitution guard + read protection)
+    // Starlark execution policies (Codex sandboxed rule engine)
     createDir(join(targetDir, '.codex', 'rules'));
     writeFileSync(join(targetDir, '.codex', 'rules', 'constitution-guard.rules'), generateCodexConstitutionGuardRules(), 'utf-8');
     writeFileSync(join(targetDir, '.codex', 'rules', 'read-protection.rules'), generateCodexReadProtectionRules(), 'utf-8');
+
+    // .codex/hooks.json — license-guard wired to UserPromptSubmit (per-turn enforcement).
+    // Codex hooks.json is experimental (requires [features] codex_hooks = true in
+    // codex config). Without it, license enforcement only happens at slash command
+    // entry — a long-running terminal session would not be re-validated.
+    writeFileSync(
+      join(targetDir, '.codex', 'hooks.json'),
+      JSON.stringify({
+        $comment: 'chati.dev v4.2.2 — experimental Codex hooks. Requires [features] codex_hooks = true.',
+        hooks: {
+          UserPromptSubmit: [
+            {
+              matcher: '.*',
+              hooks: [
+                {
+                  type: 'command',
+                  command: 'node .chati.dev/hooks/license-guard.js',
+                },
+              ],
+            },
+          ],
+        },
+      }, null, 2) + '\n',
+      'utf-8'
+    );
   } else if (ideKey === 'gemini-cli') {
     // Gemini CLI: TOML command file (native format for /chati command)
     writeFileSync(join(targetDir, '.gemini', 'commands', 'chati.toml'), generateGeminiRouter({ orchestratorPath }), 'utf-8');
@@ -357,32 +494,31 @@ function generateProviderInstructions(providerName) {
 # This file configures ${providerName} to work with Chati.dev
 
 ## System Location
-All system content is in the \`chati.dev/\` directory.
+All system content is in the \`.chati.dev/\` directory (hidden). User artifacts are in \`artifacts/\`.
 
 ## Session State
 Runtime session state is in \`.chati/session.yaml\` (IDE-agnostic).
 
 ## Getting Started
-The orchestrator is at \`chati.dev/orchestrator/chati.md\`.
-Read it to understand routing, session management, and agent activation.
+The orchestrator is at \`.chati.dev/orchestrator/chati.md\`.
 
 ## Constitution
-Governance rules are in \`chati.dev/constitution.md\` (19 Articles).
+Governance rules are in \`.chati.dev/constitution.md\`.
 
 ## Pipeline
 \`\`\`
 DISCOVER: WU -> Brief
-PLAN:     Detail -> Architect -> UX -> Phases -> Tasks -> QA-Planning
-BUILD:    Dev -> QA-Implementation
+PLAN:     [Planning Team: Detail + Architect + UX + QA-Planning] -> Phases -> Tasks
+BUILD:    [Build Team: Dev + QA-Implementation] -> QA-Visual
 DEPLOY:   DevOps
 \`\`\`
 
 ## Agents
-- DISCOVER: chati.dev/agents/discover/ (3 agents)
-- PLAN: chati.dev/agents/plan/ (5 agents)
-- Quality: chati.dev/agents/quality/ (2 agents)
-- BUILD: chati.dev/agents/build/ (1 agent)
-- DEPLOY: chati.dev/agents/deploy/ (1 agent)
+- DISCOVER: .chati.dev/agents/discover/
+- PLAN: .chati.dev/agents/plan/
+- Quality: .chati.dev/agents/quality/
+- BUILD: .chati.dev/agents/build/
+- DEPLOY: .chati.dev/agents/deploy/
 `;
 }
 
@@ -390,36 +526,165 @@ DEPLOY:   DevOps
  * Append chati.dev runtime entries to .gitignore.
  * Session lock files are runtime-only and should never be committed.
  */
-function updateGitignore(targetDir, selectedIDEs) {
-  const entries = [
+export function updateGitignore(targetDir, selectedIDEs) {
+  const START_MARKER = '# BEGIN Chati.dev — do not edit between markers';
+  const END_MARKER = '# END Chati.dev';
+  // Legacy marker from pre-4.3.0 installs — detected for migration
+  const LEGACY_MARKER = '# Chati.dev runtime files';
+
+  const block = [
+    START_MARKER,
+    '# Framework files — generated by chati-dev, not part of your project.',
+    '# Do NOT remove these entries. If a framework file is already in git history,',
+    '# run: git rm -r --cached <path>  after upgrading.',
+    '',
+    '# Framework (all code, prompts, hooks, orchestrator, data)',
+    '.chati.dev/',
     '',
-    '# Chati.dev runtime files (session lock — not committed)',
+    '# Runtime state (session, teams, timeline, transient memories)',
+    '.chati/session.yaml',
+    '.chati/teams/',
+    '.chati/timeline.json',
     '.chati/memories/*/session/',
+    '# NOTE: durable/ and daily/ memories ARE committed — they contain project knowledge',
+    '',
+    '# Claude Code integration (framework portions only)',
+    '.claude/commands/chati.md',
+    '.claude/rules/chati/',
+    '.claude/settings.local.json',
+    '# NOTE: .claude/settings.json IS committed — it is shared team config (hooks, MCPs)',
+    '',
+    '# Session locks (runtime, per-machine)',
+    'CLAUDE.local.md',
+    '.gemini/session-lock.md',
+    'AGENTS.override.md',
   ];
 
-  if (selectedIDEs.includes('claude-code')) {
-    entries.push('CLAUDE.local.md');
-  }
   if (selectedIDEs.includes('gemini-cli')) {
-    entries.push('.gemini/session-lock.md');
+    block.push(
+      '',
+      '# Gemini provider framework files',
+      '.gemini/commands/',
+      '.gemini/context/',
+      '.gemini/hooks/',
+      '.gemini/settings.json',
+    );
   }
+
   if (selectedIDEs.includes('codex-cli')) {
-    entries.push('AGENTS.override.md');
+    block.push(
+      '',
+      '# Codex provider framework files',
+      '.codex/',
+      '.agents/skills/chati/',
+    );
   }
 
-  entries.push('');
+  block.push('', END_MARKER);
 
+  const newBlock = block.join('\n');
   const gitignorePath = join(targetDir, '.gitignore');
-  const marker = '# Chati.dev runtime files';
 
-  if (existsSync(gitignorePath)) {
-    const existing = readFileSync(gitignorePath, 'utf-8');
-    // Don't duplicate if already present
-    if (existing.includes(marker)) return;
-    writeFileSync(gitignorePath, existing.trimEnd() + '\n' + entries.join('\n'), 'utf-8');
-  } else {
-    writeFileSync(gitignorePath, entries.join('\n'), 'utf-8');
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, newBlock + '\n', 'utf-8');
+    return;
+  }
+
+  let existing = readFileSync(gitignorePath, 'utf-8');
+
+  // Strip new-style block if present (idempotency)
+  const newStartIdx = existing.indexOf(START_MARKER);
+  const newEndIdx = existing.indexOf(END_MARKER);
+  if (newStartIdx !== -1 && newEndIdx !== -1) {
+    existing = existing.slice(0, newStartIdx) + existing.slice(newEndIdx + END_MARKER.length);
+    existing = existing.replace(/\n{3,}/g, '\n\n').trimEnd();
+  }
+
+  // Strip legacy block if present (pre-4.3.0)
+  if (existing.includes(LEGACY_MARKER)) {
+    const lines = existing.split('\n');
+    const legacyIdx = lines.findIndex(l => l.includes(LEGACY_MARKER));
+    if (legacyIdx !== -1) {
+      // Remove legacy marker line + the short known-legacy entries that followed
+      const legacyEntries = new Set([
+        '.chati/memories/*/session/',
+        'CLAUDE.local.md',
+        '.gemini/session-lock.md',
+        'AGENTS.override.md',
+        '',
+      ]);
+      let endIdx = legacyIdx + 1;
+      while (endIdx < lines.length && legacyEntries.has(lines[endIdx].trim())) endIdx++;
+      lines.splice(legacyIdx, endIdx - legacyIdx);
+      existing = lines.join('\n').trimEnd();
+    }
+  }
+
+  writeFileSync(gitignorePath, existing.trimEnd() + '\n\n' + newBlock + '\n', 'utf-8');
+}
+
+/**
+ * Section-aware merge for CLAUDE.md: preserves user-authored sections and
+ * framework-managed sections (those with markers). Framework sections are
+ * re-rendered from the fresh template; everything else is kept as-is.
+ */
+function mergeClaudeMd(existing, fresh) {
+  // Framework-managed sections — these come from the install template AND from
+  // magic-docs runtime updates. Replace these from fresh template; preserve all others.
+  const frameworkSections = [
+    // Install template (templates.js generateClaudeMd)
+    '## Project Context',
+    '## Chati.dev',
+    // Magic-docs runtime sections (when project starts)
+    '## Current State',
+    '## Session Lock',
+    '## Recent Decisions',
+    '## Framework',
+    '## How to Resume',
+  ];
+
+  // If existing has no framework sections at all, user has a custom CLAUDE.md;
+  // just append the framework template separator + fresh template below.
+  const hasAnyFwSection = frameworkSections.some(h => existing.includes(h));
+  if (!hasAnyFwSection) {
+    return existing.trimEnd() + '\n\n<!-- Chati.dev framework context (auto-managed) -->\n\n' + fresh;
+  }
+
+  // Otherwise, do section-level replacement — for each framework section in fresh,
+  // replace the corresponding section in existing (or append if missing).
+  let merged = existing;
+  for (const header of frameworkSections) {
+    const freshSection = extractSection(fresh, header);
+    if (!freshSection) continue;
+    if (merged.includes(header)) {
+      merged = replaceSection(merged, header, freshSection);
+    } else {
+      merged = merged.trimEnd() + '\n\n' + freshSection;
+    }
   }
+  return merged;
+}
+
+function extractSection(content, header) {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex(l => l.trim() === header);
+  if (startIdx === -1) return null;
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length && !lines[endIdx].match(/^##\s/)) endIdx++;
+  return lines.slice(startIdx, endIdx).join('\n');
+}
+
+function replaceSection(content, header, newSection) {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex(l => l.trim() === header);
+  if (startIdx === -1) return content;
+  let endIdx = startIdx + 1;
+  while (endIdx < lines.length && !lines[endIdx].match(/^##\s/)) endIdx++;
+  return [
+    ...lines.slice(0, startIdx),
+    newSection,
+    ...lines.slice(endIdx),
+  ].join('\n');
 }
 
 /**
@@ -430,3 +695,214 @@ function createDir(dir) {
     mkdirSync(dir, { recursive: true });
   }
 }
+
+/**
+ * Recursively copy CLI source (excluding tests, node_modules, hidden files).
+ * Used to bundle the CLI source into the user's .chati.dev/_cli/ folder so
+ * the framework runs self-contained (no `npx chati-dev` dependency).
+ */
+function copyCliSource(srcDir, destDir) {
+  if (!existsSync(srcDir)) return;
+  createDir(destDir);
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    if (entry.startsWith('.')) continue;
+    if (entry === 'node_modules' || entry === 'test' || entry === 'tests') continue;
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+    let stat;
+    try { stat = statSync(srcPath); } catch { continue; }
+    if (stat.isDirectory()) {
+      copyCliSource(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Recursively copy a directory verbatim (used for bundling node_modules trees).
+ */
+function copyDirVerbatim(srcDir, destDir) {
+  if (!existsSync(srcDir)) return;
+  createDir(destDir);
+  for (const entry of readdirSync(srcDir)) {
+    const srcPath = join(srcDir, entry);
+    const destPath = join(destDir, entry);
+    let stat;
+    try { stat = statSync(srcPath); } catch { continue; }
+    if (stat.isDirectory()) {
+      copyDirVerbatim(srcPath, destPath);
+    } else {
+      try { copyFileSync(srcPath, destPath); } catch { /* skip unreadable */ }
+    }
+  }
+}
+
+/**
+ * Bundle chati-dev's production dependencies into .chati.dev/_cli/node_modules/
+ * so the bundled CLI can import js-yaml, chalk, etc. without relying on a
+ * project-level node_modules tree.
+ *
+ * Uses createRequire to resolve each dep from the installed chati-dev package,
+ * which works whether the package is hoisted or nested in the user's
+ * node_modules (npx cache, npm install, etc.).
+ */
+function copyCliDependencies(pkgDir, destNodeModules) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf-8'));
+  } catch { return; }
+  const deps = [
+    ...Object.keys(pkg.dependencies || {}),
+    ...Object.keys(pkg.optionalDependencies || {}),
+  ];
+  if (deps.length === 0) return;
+
+  // Resolve each dep from the package.json location (works for hoisted + nested layouts).
+  // eslint-disable-next-line no-undef
+  const require = createRequire(join(pkgDir, 'package.json'));
+  createDir(destNodeModules);
+
+  const visited = new Set();
+  const queue = [...deps];
+
+  while (queue.length > 0) {
+    const depName = queue.shift();
+    if (visited.has(depName)) continue;
+    visited.add(depName);
+
+    let depDir;
+    try {
+      // Try direct package.json resolve first (fast path)
+      depDir = dirname(require.resolve(`${depName}/package.json`));
+    } catch {
+      // Fallback: resolve the main entry then walk up to find package root.
+      // Needed for packages with strict "exports" (chalk, ora, etc.).
+      try {
+        let p = require.resolve(depName);
+        while (p && p !== dirname(p)) {
+          p = dirname(p);
+          if (existsSync(join(p, 'package.json')) && basename(p) === depName.split('/').pop()) {
+            depDir = p;
+            break;
+          }
+        }
+      } catch { continue; }
+      if (!depDir) continue;
+    }
+    const depPkgJsonPath = join(depDir, 'package.json');
+    copyDirVerbatim(depDir, join(destNodeModules, depName));
+
+    // Include transitive deps
+    try {
+      const depPkg = JSON.parse(readFileSync(depPkgJsonPath, 'utf-8'));
+      for (const t of Object.keys(depPkg.dependencies || {})) {
+        if (!visited.has(t)) queue.push(t);
+      }
+    } catch { /* continue */ }
+  }
+}
+
+/**
+ * Write .claude/settings.json with safe merge against existing user content.
+ *
+ * If the file does not exist: write fresh chati settings.
+ * If the file exists and is valid JSON: merge — chati hooks/permissions are
+ * UNIONED into existing values rather than replacing them. User customizations
+ * (env, statusLine, plugins, language, alwaysThinkingEnabled, etc.) are preserved.
+ * If the file exists but is malformed: leave it alone, log a warning. We will
+ * not silently destroy user data.
+ */
+function writeClaudeSettingsWithMerge(settingsPath) {
+  createDir(dirname(settingsPath));
+  const fresh = JSON.parse(generateClaudeSettings());
+
+  if (!existsSync(settingsPath)) {
+    writeFileSync(settingsPath, JSON.stringify(fresh, null, 2) + '\n', 'utf-8');
+    return;
+  }
+
+  let existing;
+  try {
+    existing = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch (err) {
+    process.stderr.write(`[chati] WARNING: .claude/settings.json exists but is not valid JSON (${err.message}). Skipping merge — chati hooks will NOT be wired. Fix the file and re-run install.\n`);
+    return;
+  }
+
+  const merged = mergeClaudeSettings(existing, fresh);
+  writeFileSync(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Merge two Claude Code settings.json objects.
+ *
+ * - permissions.allow / permissions.deny: array union (de-duplicated)
+ * - permissions.defaultMode: keep existing if set, else use fresh
+ * - hooks: per-event union — chati hook commands are appended to existing
+ *   matcher groups; user's hooks for the same events are preserved
+ * - $schema: prefer fresh (always our canonical URL)
+ * - all other top-level keys (env, statusLine, plugins, language, etc.):
+ *   keep existing untouched
+ */
+export function mergeClaudeSettings(existing, fresh) {
+  const merged = { ...existing };
+
+  // $schema — chati's canonical URL wins
+  if (fresh.$schema) merged.$schema = fresh.$schema;
+
+  // permissions
+  const existingPerms = existing.permissions || {};
+  const freshPerms = fresh.permissions || {};
+  merged.permissions = {
+    ...existingPerms,
+    allow: unionArrays(existingPerms.allow, freshPerms.allow),
+    deny: unionArrays(existingPerms.deny, freshPerms.deny),
+    defaultMode: existingPerms.defaultMode || freshPerms.defaultMode || 'default',
+  };
+
+  // hooks — per-event merge
+  const existingHooks = existing.hooks || {};
+  const freshHooks = fresh.hooks || {};
+  merged.hooks = { ...existingHooks };
+
+  for (const [eventName, freshGroups] of Object.entries(freshHooks)) {
+    const existingGroups = existingHooks[eventName] || [];
+    // Append fresh groups; we don't dedup at the group level (different
+    // matchers are different groups). Within a single fresh group, the
+    // hook commands are unique to chati so duplication risk is minimal.
+    // To be safe, dedup by command string across the merged event.
+    const seen = new Set();
+    const collected = [];
+    for (const group of [...existingGroups, ...freshGroups]) {
+      const dedupedHooks = (group.hooks || []).filter(h => {
+        const key = `${group.matcher || ''}|${h.command}`;
+        if (seen.has(key)) return false;
+        seen.add(key);
+        return true;
+      });
+      if (dedupedHooks.length > 0) {
+        collected.push({
+          ...(group.matcher !== undefined ? { matcher: group.matcher } : {}),
+          hooks: dedupedHooks,
+        });
+      }
+    }
+    merged.hooks[eventName] = collected;
+  }
+
+  return merged;
+}
+
+function unionArrays(a, b) {
+  const out = [];
+  const seen = new Set();
+  for (const item of [...(a || []), ...(b || [])]) {
+    if (!seen.has(item)) {
+      seen.add(item);
+      out.push(item);
+    }
+  }
+  return out;
+}