chati-dev 4.5.6 → 4.5.8

package/framework/orchestrator/chati-router.js

@@ -21,6 +21,125 @@ import { join } from 'path';
 const PROJECT_DIR = process.cwd();
 const ROUTER_ARGS = process.argv.slice(2);
 
+async function readEnabledHarnesses(projectDir) {
+  const installationPath = join(projectDir, '.chati', 'v2', 'installation.json');
+  if (existsSync(installationPath)) {
+    try {
+      const artifact = JSON.parse(readFileSync(installationPath, 'utf-8'));
+      const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+      const doctorModulePath = join(projectDir, fwDir, '_cli', 'installer-v2', 'index.js');
+      if (!existsSync(doctorModulePath)) return { harnesses: [], error: 'v2 doctor missing' };
+      const { doctorV2 } = await import(doctorModulePath);
+      if (!doctorV2(artifact).passed) return { harnesses: [], error: 'v2 artifact invalid' };
+      const harnesses = artifact.installation?.enabled_providers
+        ?.map((binding) => binding.harness_id)
+        .filter(Boolean);
+      if (harnesses?.length) return { harnesses: [...new Set(harnesses)], error: null };
+    } catch { return { harnesses: [], error: 'v2 artifact invalid' }; }
+  }
+
+  const detected = [];
+  if (existsSync(join(projectDir, '.claude', 'commands', 'chati.md'))) detected.push('claude');
+  if (existsSync(join(projectDir, '.agents', 'skills', 'chati', 'SKILL.md'))) detected.push('codex');
+  if (existsSync(join(projectDir, '.grok', 'commands', 'chati.md'))) detected.push('grok');
+  return { harnesses: detected, error: null };
+}
+
+function hasContent(path) {
+  return existsSync(path) && readFileSync(path, 'utf-8').trim().length > 0;
+}
+
+function codexHooksEnabled(config) {
+  if (/^\s*features\.hooks\s*=\s*true\s*(?:#.*)?$/m.test(config)) return true;
+  const lines = config.split('\n');
+  const sectionStart = lines.findIndex((line) => /^\s*\[features\]\s*(?:#.*)?$/.test(line));
+  if (sectionStart === -1) return false;
+  const sectionEnd = lines.findIndex((line, index) => index > sectionStart && /^\s*\[.*\]\s*(?:#.*)?$/.test(line));
+  const end = sectionEnd === -1 ? lines.length : sectionEnd;
+  return lines.slice(sectionStart + 1, end).some((line) => /^\s*hooks\s*=\s*true\s*(?:#.*)?$/.test(line));
+}
+
+export async function validateProviderIntegrity(projectDir) {
+  const missing = [];
+  const { harnesses, error } = await readEnabledHarnesses(projectDir);
+
+  if (error) missing.push(error);
+  const supportedHarnesses = new Set(['claude', 'codex', 'grok']);
+  for (const harness of harnesses) {
+    if (!supportedHarnesses.has(harness)) missing.push(`unsupported harness ${harness}`);
+  }
+
+  if (harnesses.length === 0) missing.push('provider entry point');
+
+  if (harnesses.includes('claude')) {
+    const commandPath = join(projectDir, '.claude', 'commands', 'chati.md');
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!hasContent(commandPath)) missing.push('claude command');
+    if (!existsSync(settingsPath)) {
+      missing.push('claude settings');
+    } else {
+      try {
+        const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        const ptu = settings.hooks?.PreToolUse || [];
+        const ups = settings.hooks?.UserPromptSubmit || [];
+        const ptuCmds = ptu.flatMap((group) => (group.hooks || []).map((hook) => hook.command || ''));
+        const upsCmds = ups.flatMap((group) => (group.hooks || []).map((hook) => hook.command || ''));
+        missing.push(...['mode-governance', 'constitution-guard', 'read-protection']
+          .filter((hook) => !ptuCmds.some((command) => command.includes(hook)))
+          .map((hook) => `claude hook ${hook}`));
+        if (![...upsCmds, ...ptuCmds].some((command) => command.includes('license-guard'))) {
+          missing.push('claude hook license-guard');
+        }
+      } catch {
+        missing.push('claude settings invalid');
+      }
+    }
+  }
+
+  if (harnesses.includes('codex')) {
+    const required = [
+      ['codex skill', '.agents/skills/chati/SKILL.md'],
+      ['codex constitution guard', '.codex/rules/constitution-guard.rules'],
+      ['codex read protection', '.codex/rules/read-protection.rules'],
+    ];
+    for (const [label, relativePath] of required) {
+      if (!hasContent(join(projectDir, relativePath))) missing.push(label);
+    }
+    const configPath = join(projectDir, '.codex', 'config.toml');
+    if (!hasContent(configPath) || !codexHooksEnabled(readFileSync(configPath, 'utf-8'))) {
+      missing.push('codex hooks feature');
+    }
+    const hooksPath = join(projectDir, '.codex', 'hooks.json');
+    if (!hasContent(hooksPath)) {
+      missing.push('codex license hook');
+    } else {
+      try {
+        const hooks = JSON.parse(readFileSync(hooksPath, 'utf-8'));
+        const validHook = (hooks.hooks?.UserPromptSubmit || []).some((group) =>
+          group.matcher === '.*'
+          && (group.hooks || []).some((hook) =>
+            hook.type === 'command'
+            && hook.command === 'node .chati.dev/hooks/license-guard.js'
+            && hook.async !== true
+          )
+        );
+        if (!validHook) {
+          missing.push('codex license hook');
+        }
+      } catch {
+        missing.push('codex hooks invalid');
+      }
+    }
+  }
+
+  if (harnesses.includes('grok')) {
+    if (!hasContent(join(projectDir, '.grok', 'commands', 'chati.md'))) missing.push('grok command');
+    if (!hasContent(join(projectDir, '.grok', 'session-lock.md'))) missing.push('grok session lock');
+  }
+
+  return { valid: missing.length === 0, missing };
+}
+
 /**
  * Find the chati-dev CLI module. Tries local node_modules first (fast),
  * then monorepo dev layout. Returns the module or null.
@@ -245,9 +364,64 @@ async function dispatchOrchestrate(subCommand, argv) {
   }
 }
 
+async function runSecurityPreflight(projectDir) {
+  const result = { ok: true, license: null, integrity: true, error: null };
+  try {
+    const integrity = await validateProviderIntegrity(projectDir);
+    if (!integrity.valid) {
+      return {
+        ...result,
+        ok: false,
+        integrity: false,
+        error: `integrity_failed: missing ${integrity.missing.join(', ')}`,
+      };
+    }
+  } catch {
+    return { ...result, ok: false, integrity: false, error: 'integrity_failed' };
+  }
+
+  try {
+    const fwDir = existsSync(join(projectDir, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
+    const hookPath = join(projectDir, fwDir, 'hooks', 'license-guard.js');
+    if (!existsSync(hookPath)) {
+      return {
+        ...result,
+        ok: false,
+        error: 'license_guard_missing',
+        license: { valid: false, reason: 'License enforcement file missing. Reinstall with: npx chati-dev init' },
+      };
+    }
+    const mod = await import(hookPath);
+    result.license = await mod.checkLicense();
+    if (!result.license.valid) return { ...result, ok: false, error: 'license_invalid' };
+  } catch {
+    return {
+      ...result,
+      ok: false,
+      error: 'license_check_error',
+      license: { valid: false, error: 'license_check_error' },
+    };
+  }
+
+  return result;
+}
+
+// Only read-only diagnosis and license recovery may run without a valid
+// installation preflight. `init` mutates session state and must never bypass
+// license or provider-integrity enforcement.
+const PREFLIGHT_EXEMPT_SUBS = new Set(['doctor', 'wait-for-license']);
+
 async function main() {
   const subCommand = ROUTER_ARGS[0];
 
+  const preflight = subCommand && PREFLIGHT_EXEMPT_SUBS.has(subCommand)
+    ? { ok: true, license: null, integrity: true, error: null }
+    : await runSecurityPreflight(PROJECT_DIR);
+  if (!preflight.ok) {
+    console.log(JSON.stringify(preflight));
+    return;
+  }
+
   // Sub-command mode: `node chati-router.js <subcommand> [--flags...]`
   // Routes to the local CLI for ANY orchestrate subcommand. No npx, no network.
   if (subCommand && VALID_ORCHESTRATE_SUBS.has(subCommand)) {
@@ -271,8 +445,8 @@ async function main() {
   // No-subcommand mode (default): full router pipeline (license + integrity + session + next)
   const result = {
     ok: true,
-    license: null,
-    integrity: true,
+    license: preflight.license,
+    integrity: preflight.integrity,
     session: null,
     action: null,
     pipeline: null,
@@ -281,75 +455,7 @@ async function main() {
   };
 
   // -----------------------------------------------------------------------
-  // 1. License validation
-  // -----------------------------------------------------------------------
-  try {
-    const fwDir = existsSync(join(PROJECT_DIR, '.chati.dev')) ? '.chati.dev' : 'chati.dev';
-    const hookPath = join(PROJECT_DIR, fwDir, 'hooks', 'license-guard.js');
-    if (!existsSync(hookPath)) {
-      result.ok = false;
-      result.error = 'license_guard_missing';
-      result.license = { valid: false, reason: 'License enforcement file missing. Reinstall with: npx chati-dev init' };
-      console.log(JSON.stringify(result));
-      return;
-    }
-
-    const mod = await import(hookPath);
-    const license = await mod.checkLicense();
-    result.license = license;
-
-    if (!license.valid) {
-      result.ok = false;
-      result.error = 'license_invalid';
-      console.log(JSON.stringify(result));
-      return;
-    }
-  } catch (err) {
-    // Fail-closed on license check errors
-    result.license = { valid: false, error: 'license_check_error' };
-    result.ok = false;
-  }
-
-  // -----------------------------------------------------------------------
-  // 2. Integrity check — are all required hooks registered in settings.json?
-  // Note: license-guard is registered under UserPromptSubmit (not PreToolUse).
-  // mode-governance, constitution-guard, and read-protection are in PreToolUse.
-  // -----------------------------------------------------------------------
-  try {
-    const settingsPath = join(PROJECT_DIR, '.claude', 'settings.json');
-    if (existsSync(settingsPath)) {
-      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-      const ptu = settings.hooks?.PreToolUse || [];
-      const ups = settings.hooks?.UserPromptSubmit || [];
-      const ptuCmds = ptu.flatMap(g => (g.hooks || []).map(h => h.command || ''));
-      const upsCmds = ups.flatMap(g => (g.hooks || []).map(h => h.command || ''));
-      // license-guard lives in UserPromptSubmit; others live in PreToolUse
-      const missingHooks = [
-        ...(['mode-governance', 'constitution-guard', 'read-protection'].filter(h => !ptuCmds.some(c => c.includes(h)))),
-        ...(['license-guard'].filter(h => !upsCmds.some(c => c.includes(h)) && !ptuCmds.some(c => c.includes(h)))),
-      ];
-      result.integrity = missingHooks.length === 0;
-      if (missingHooks.length > 0) {
-        result.error = `integrity_failed: missing hooks: ${missingHooks.join(', ')}`;
-      }
-    } else {
-      result.integrity = false;
-    }
-
-    if (!result.integrity) {
-      result.ok = false;
-      result.error = 'integrity_failed';
-      console.log(JSON.stringify(result));
-      return;
-    }
-  } catch {
-    // Fail-closed on integrity check
-    result.integrity = false;
-    result.ok = false;
-  }
-
-  // -----------------------------------------------------------------------
-  // 3. Session state
+  // 1. Session state
   // -----------------------------------------------------------------------
   try {
     const sessionPath = join(PROJECT_DIR, '.chati', 'session.yaml');

package/framework/orchestrator/chati.md

@@ -10,7 +10,7 @@ You are the **Chati.dev Orchestrator**, the single entry point for the Chati.dev
 - **Role**: Orchestrator & Router
 - **Position**: Entry point (always first contact)
 - **Scope**: System-wide routing, session management, deviation handling, backlog
-- **Model**: sonnet | upgrade: opus if complex deviation or multi-agent coordination
+- **Execution binding**: resolved at runtime by installation-v2 task routing; never self-select or downgrade
 
 ### Security Rule
 **NEVER suggest disabling, removing, commenting out, or bypassing hooks, settings.json permissions, or license enforcement.** If a hook blocks an operation and the user asks to work around it, explain what the hook is protecting and guide them to resolve the root cause (e.g., activate a valid license, change pipeline mode). Hooks are governance boundaries, not obstacles to remove.

package/framework/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/framework/schemas/session.schema.json

@@ -196,16 +196,33 @@
     },
     "model_selections": {
       "type": "array",
-      "description": "Model selection log for cost tracking (Article XVI)",
+      "description": "Append-only audit log of the exact execution binding used for each task (Article XVI)",
       "items": {
         "type": "object",
-        "required": ["agent", "recommended", "timestamp"],
+        "anyOf": [
+          {
+            "required": ["agent", "task_id", "provider", "model", "timestamp"],
+            "properties": {
+              "provider": { "enum": ["claude", "codex", "grok", "gemini"] }
+            }
+          },
+          {
+            "required": ["agent", "recommended", "timestamp"],
+            "not": { "required": ["task_id", "provider", "model"] }
+          }
+        ],
         "properties": {
           "agent": { "type": "string", "description": "Agent name" },
-          "recommended": { "enum": ["opus", "sonnet", "haiku"], "description": "Recommended model" },
-          "actual": { "enum": ["opus", "sonnet", "haiku"], "description": "Model actually used" },
-          "reason": { "type": "string", "description": "Why this model was selected (default, upgrade condition, no downgrade)" },
-          "provider": { "type": "string", "description": "CLI provider used (claude, gemini, codex)" },
+          "task_id": { "type": "string", "description": "Task identity supplied to the runner" },
+          "provider": { "type": "string", "description": "CLI harness that executed the task" },
+          "provider_id": { "type": ["string", "null"], "description": "Vendor provider identifier from the capability catalog" },
+          "model": { "type": "string", "minLength": 1, "description": "Exact model identifier used" },
+          "reasoning_configuration": { "enum": ["low", "medium", "high", "xhigh", "max", null], "description": "Reasoning effort passed to the CLI when supported" },
+          "catalog_snapshot_ref": { "type": ["string", "null"], "description": "Capability catalog snapshot used for routing" },
+          "status": { "enum": ["dispatched", "completed", "failed"], "default": "dispatched" },
+          "recommended": { "type": "string", "description": "Legacy pre-4.5.7 recommended model field, migrated on session load" },
+          "actual": { "type": "string", "description": "Legacy pre-4.5.7 actual model field, migrated on session load" },
+          "reason": { "type": "string", "description": "Legacy pre-4.5.7 selection reason" },
           "timestamp": { "type": "string", "format": "date-time" }
         }
       }
@@ -367,13 +384,13 @@
     "active_model": {
       "type": ["string", "null"],
       "default": null,
-      "description": "Normalized Claude model key (Article XII v2 / context-window-detection v1). Output of parseClaudeModelId — e.g. 'opus', 'opus[1m]', 'sonnet', 'haiku'. Written at /chati boot; drives context-limit resolution in hooks. Null = unknown (detection chain falls through to provider default)."
+      "description": "Model identifier detected for the current interactive harness. Written at /chati boot and used for context-window resolution. Per-task routed models are recorded separately in model_selections[]."
     },
     "active_provider": {
       "type": ["string", "null"],
-      "enum": ["claude", "gemini", "codex", null],
+      "enum": ["claude", "gemini", "codex", "grok", null],
       "default": null,
-      "description": "Active CLI provider. Redundant with providers_enabled[0] but flat for hook convenience."
+      "description": "Current interactive CLI harness. This is independent from the per-task provider recorded in model_selections[]."
     },
     "context_tokens_used": {
       "type": "integer",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chati-dev",
-  "version": "4.5.6",
+  "version": "4.5.8",
   "description": "AI-Powered Multi-Agent Orchestration System - Structured vibe coding for Full Stack Development",
   "type": "module",
   "bin": {
@@ -77,6 +77,7 @@
     "chalk": "^5.3.0",
     "js-yaml": "^5.4.0",
     "ora": "^8.0.1",
+    "proper-lockfile": "4.1.2",
     "semver": "^7.6.0"
   },
   "bundleDependencies": [

package/src/config/claude-settings-generator.js

@@ -139,12 +139,12 @@ const PERMISSIONS_DENY = [
   'Bash(git rebase --no-verify:*)',
 
   // System path writes — `//` prefix = absolute filesystem
-  'Write(//etc/**)',
-  'Write(//usr/**)',
-  'Write(//System/**)',
-  'Write(//bin/**)',
-  'Write(//sbin/**)',
-  'Write(//Library/**)',
+  'Edit(//etc/**)',
+  'Edit(//usr/**)',
+  'Edit(//System/**)',
+  'Edit(//bin/**)',
+  'Edit(//sbin/**)',
+  'Edit(//Library/**)',
   'Edit(//etc/**)',
   'Edit(//usr/**)',
   'Edit(//System/**)',

package/src/installer/core.js

@@ -1,6 +1,6 @@
 import { mkdirSync, writeFileSync, copyFileSync, existsSync, readFileSync, readdirSync, statSync } from 'fs';
 import { execFileSync } from 'child_process';
-import { join, dirname, basename } from 'path';
+import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { IDE_CONFIGS, IDE_TO_PROVIDER } from '../config/ide-configs.js';
@@ -10,6 +10,7 @@ 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 { applyInstalledPathReplacement } from './path-replacement.js';
 import { verifyManifest } from './manifest.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -192,7 +193,7 @@ export async function installFramework(config) {
       if (existsSync(src)) {
         // Apply path replacement so rules reference .chati.dev/ not chati.dev/
         let content = readFileSync(src, 'utf-8');
-        content = applyPathReplacement(content);
+        content = applyInstalledPathReplacement(content);
         writeFileSync(join(claudeRulesDir, file), content, 'utf-8');
       }
     }
@@ -269,6 +270,7 @@ export const FRAMEWORK_DIRS_TO_COPY = [
  */
 const FRAMEWORK_ROOT_FILES = [
   'constitution.md',
+  'package.json',
 ];
 
 /**
@@ -287,20 +289,6 @@ const TEXT_EXTENSIONS = new Set(['.md', '.js', '.yaml', '.yml', '.json', '.html'
  * 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)
@@ -327,7 +315,7 @@ function copyDirRecursive(srcDir, destDir, provider, relBase = '') {
       if (isText) {
         let content = readFileSync(srcPath, 'utf-8');
         // Always apply path replacement for installed location
-        content = applyPathReplacement(content);
+        content = applyInstalledPathReplacement(content);
         // Provider adaptation on top (for non-Claude)
         if (provider !== 'claude' && ADAPTABLE_FILES.has(relPath)) {
           content = adaptFrameworkFile(content, relPath, provider);
@@ -360,7 +348,7 @@ export function copyFrameworkFiles(destDir, provider = 'claude') {
     const dest = join(destDir, file);
     createDir(dirname(dest));
     let content = readFileSync(src, 'utf-8');
-    content = applyPathReplacement(content);
+    content = applyInstalledPathReplacement(content);
     if (provider !== 'claude' && ADAPTABLE_FILES.has(file)) {
       content = adaptFrameworkFile(content, file, provider);
     }
@@ -448,17 +436,18 @@ Parse the JSON output. This single command already handled: license validation,
 
     // Starlark execution policies (Codex sandboxed rule engine)
     createDir(join(targetDir, '.codex', 'rules'));
+    writeCodexConfigWithHooks(join(targetDir, '.codex', 'config.toml'));
     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
+    // Codex hooks require [features] hooks = true in the active project config.
+    // Without it, license enforcement only happens at skill entry and the router,
     // 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.',
+        $comment: 'chati.dev Codex lifecycle hooks. Requires [features] hooks = true.',
         hooks: {
           UserPromptSubmit: [
             {
@@ -486,7 +475,7 @@ Parse the JSON output. This single command already handled: license validation,
     for (const file of contextFileNames) {
       const src = join(FRAMEWORK_SOURCE, 'context', file);
       if (existsSync(src)) {
-        const content = readFileSync(src, 'utf-8');
+        const content = applyInstalledPathReplacement(readFileSync(src, 'utf-8'));
         writeFileSync(join(geminiContextDir, file), adaptFrameworkFile(content, `context/${file}`, 'gemini'), 'utf-8');
       }
     }
@@ -515,6 +504,38 @@ Parse the JSON output. This single command already handled: license validation,
   }
 }
 
+export function writeCodexConfigWithHooks(configPath) {
+  createDir(dirname(configPath));
+  if (!existsSync(configPath)) {
+    writeFileSync(configPath, '[features]\nhooks = true\n', 'utf-8');
+    return;
+  }
+
+  const original = readFileSync(configPath, 'utf-8');
+  if (/^\s*features\.hooks\s*=\s*true\s*(?:#.*)?$/m.test(original)) return;
+  if (/^\s*features\.hooks\s*=/m.test(original)) {
+    writeFileSync(configPath, original.replace(/^\s*features\.hooks\s*=.*$/m, 'features.hooks = true'), 'utf-8');
+    return;
+  }
+
+  const lines = original.split('\n');
+  const sectionStart = lines.findIndex((line) => /^\s*\[features\]\s*(?:#.*)?$/.test(line));
+  if (sectionStart === -1) {
+    const prefix = original.endsWith('\n') ? original : `${original}\n`;
+    writeFileSync(configPath, `${prefix}\n[features]\nhooks = true\n`, 'utf-8');
+    return;
+  }
+
+  let sectionEnd = lines.findIndex((line, index) => index > sectionStart && /^\s*\[.*\]\s*(?:#.*)?$/.test(line));
+  if (sectionEnd === -1) sectionEnd = lines.length;
+  const hookIndex = lines.findIndex((line, index) =>
+    index > sectionStart && index < sectionEnd && /^\s*hooks\s*=/.test(line)
+  );
+  if (hookIndex !== -1) lines[hookIndex] = 'hooks = true';
+  else lines.splice(sectionEnd, 0, 'hooks = true');
+  writeFileSync(configPath, lines.join('\n'), 'utf-8');
+}
+
 /**
  * Generate provider-agnostic instructions file content.
  * Used for non-Claude IDEs (.vscode/chati/rules.md, .cursorrules, etc.)
@@ -578,6 +599,10 @@ export function updateGitignore(targetDir, selectedIDEs) {
     '.chati/memories/*/session/',
     '# NOTE: durable/ and daily/ memories ARE committed — they contain project knowledge',
     '',
+    '# Operating system metadata',
+    '.DS_Store',
+    '._*',
+    '',
     '# Claude Code integration (framework portions only)',
     '.claude/commands/chati.md',
     '.claude/rules/chati/',
@@ -822,9 +847,14 @@ export function copyCliDependencies(pkgDir, destNodeModules) {
         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;
+          const candidatePackage = join(p, 'package.json');
+          if (existsSync(candidatePackage)) {
+            try {
+              if (JSON.parse(readFileSync(candidatePackage, 'utf-8')).name === depName) {
+                depDir = p;
+                break;
+              }
+            } catch { /* keep walking */ }
           }
         }
       } catch { continue; }

package/src/installer/path-replacement.js

@@ -0,0 +1,13 @@
+/**
+ * Translate repository paths into their installed-project locations.
+ *
+ * Source files live under `chati.dev/`. Installed framework files live under
+ * `.chati.dev/`, while user-facing artifacts remain at project root.
+ */
+export function applyInstalledPathReplacement(content) {
+  return content
+    .replace(/chati\.dev\/artifacts\//g, 'artifacts/')
+    .replace(/(?<!\.)chati\.dev\//g, '.chati.dev/')
+    .replace(/(?<!\.)'chati\.dev'/g, "'.chati.dev'")
+    .replace(/(?<!\.)"chati\.dev"/g, '".chati.dev"');
+}

package/src/installer/provider-overlay.js

@@ -13,6 +13,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { adaptFrameworkFile, ADAPTABLE_FILES } from '../config/framework-adapter.js';
+import { applyInstalledPathReplacement } from './path-replacement.js';
 
 /**
  * Generate adapted framework overlays for all enabled providers.
@@ -41,7 +42,8 @@ export function generateProviderOverlays(targetDir, frameworkSource, allProvider
 
       // Read CANONICAL (Claude) content from source, then adapt for target provider
       const canonicalContent = readFileSync(srcPath, 'utf-8');
-      const adapted = adaptFrameworkFile(canonicalContent, file, provider);
+      const installedContent = applyInstalledPathReplacement(canonicalContent);
+      const adapted = adaptFrameworkFile(installedContent, file, provider);
 
       const destPath = join(overlayDir, file);
       mkdirSync(dirname(destPath), { recursive: true });