chati-dev 4.2.2 → 4.3.0

package/src/terminal/prompt-builder.js

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import { runPrism } from '../context/engine.js';
 import { loadHandoff, formatHandoff } from '../tasks/handoff.js';
 import { getWriteScope } from './isolation.js';
@@ -24,23 +25,41 @@ import { PROVIDER_LIMITS as PROVIDER_TOKEN_LIMITS } from '../utils/provider-limi
 import { AGENT_MODELS } from '../../framework/hooks/model-governance.js';
 
 /**
- * Map of agent names to their definition file paths (relative to project root).
+ * Agent definition file paths relative to framework directory.
+ * Used internally — callers should use getAgentFile(agent, projectDir).
+ * @private
  */
-export const AGENT_FILE_MAP = {
-  'greenfield-wu': 'chati.dev/agents/discover/greenfield-wu.md',
-  'brownfield-wu': 'chati.dev/agents/discover/brownfield-wu.md',
-  brief: 'chati.dev/agents/discover/brief.md',
-  detail: 'chati.dev/agents/plan/detail.md',
-  architect: 'chati.dev/agents/plan/architect.md',
-  ux: 'chati.dev/agents/plan/ux.md',
-  phases: 'chati.dev/agents/plan/phases.md',
-  tasks: 'chati.dev/agents/plan/tasks.md',
-  'qa-planning': 'chati.dev/agents/quality/qa-planning.md',
-  dev: 'chati.dev/agents/build/dev.md',
-  'qa-implementation': 'chati.dev/agents/quality/qa-implementation.md',
-  devops: 'chati.dev/agents/deploy/devops.md',
+const AGENT_FILE_PATHS = {
+  'greenfield-wu': 'agents/discover/greenfield-wu.md',
+  'brownfield-wu': 'agents/discover/brownfield-wu.md',
+  brief: 'agents/discover/brief.md',
+  detail: 'agents/plan/detail.md',
+  architect: 'agents/plan/architect.md',
+  ux: 'agents/plan/ux.md',
+  phases: 'agents/plan/phases.md',
+  tasks: 'agents/plan/tasks.md',
+  'qa-planning': 'agents/quality/qa-planning.md',
+  dev: 'agents/build/dev.md',
+  'qa-implementation': 'agents/quality/qa-implementation.md',
+  'qa-visual': 'agents/quality/qa-visual.md',
+  devops: 'agents/deploy/devops.md',
 };
 
+/**
+ * Resolve an agent's definition file path relative to the project root.
+ * Handles both .chati.dev/ (new) and chati.dev/ (legacy) structures.
+ *
+ * @param {string} agentName - Agent name (e.g. 'detail')
+ * @param {string} projectDir - Project root directory
+ * @returns {string|null} Relative path from project root, or null if unknown
+ */
+export function getAgentFile(agentName, projectDir) {
+  const rel = AGENT_FILE_PATHS[agentName];
+  if (!rel) return null;
+  return `${resolveFrameworkDir(projectDir)}/${rel}`;
+}
+
+
 /**
  * 3-Tier Tool Mesh — Token-aware tool loading profiles per agent.
  *
@@ -63,6 +82,7 @@ export const TOOL_PROFILES = {
   'qa-planning': { T1: ['Read', 'Glob', 'Grep'], T2: [], T3: [] },
   dev:       { T1: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], T2: ['WebSearch', 'WebFetch', 'Task'], T3: ['playwright'] },
   'qa-implementation': { T1: ['Read', 'Bash', 'Glob', 'Grep'], T2: ['Task'], T3: [] },
+  'qa-visual': { T1: ['Read', 'Bash', 'Glob', 'Grep'], T2: ['Write'], T3: [] },
   devops:    { T1: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], T2: ['WebSearch'], T3: ['docker'] },
 };
 
@@ -220,7 +240,7 @@ export function buildAgentPrompt(config) {
  * Spawned terminals always start FRESH (remainingPercent: 100).
  */
 function buildPrismSection(config) {
-  const domainsDir = join(config.projectDir, 'chati.dev', 'domains');
+  const domainsDir = join(config.projectDir, resolveFrameworkDir(config.projectDir), 'domains');
 
   if (!existsSync(domainsDir)) {
     return { xml: null, layerCount: 0 };
@@ -262,17 +282,14 @@ function buildPrismSection(config) {
  * For non-primary providers, resolves via overlay directory.
  */
 function loadAgentDefinition(agent, projectDir, provider = null) {
-  const relativePath = AGENT_FILE_MAP[agent];
-  if (!relativePath) return null;
-
-  // Strip 'chati.dev/' prefix for overlay resolution
-  const relToFramework = relativePath.replace(/^chati\.dev\//, '');
+  const relToFramework = AGENT_FILE_PATHS[agent];
+  if (!relToFramework) return null;
 
   let fullPath;
   if (provider && provider !== 'claude') {
     fullPath = resolveOverlayPath(projectDir, relToFramework, provider);
   } else {
-    fullPath = join(projectDir, relativePath);
+    fullPath = join(projectDir, resolveFrameworkDir(projectDir), relToFramework);
   }
 
   if (!existsSync(fullPath)) return null;
@@ -317,7 +334,7 @@ function buildHandoffSection(config) {
  * respected by the spawned Claude process.
  */
 function buildWriteScopeSection(config) {
-  const scope = config.writeScope || getWriteScope(config.agent);
+  const scope = config.writeScope || getWriteScope(config.agent, config.projectDir);
 
   if (scope.length === 0) {
     return (
@@ -502,9 +519,9 @@ export function loadPreset(stack, projectDir) {
     return { loaded: false, preset: null, stack: stack || '' };
   }
 
-  // Check both deployed (chati.dev/presets/) and package (framework/presets/) locations
+  // Check both deployed (chati.dev/presets/ or .chati.dev/presets/) and package (framework/presets/) locations
   const locations = [
-    join(projectDir, 'chati.dev', 'presets'),
+    join(projectDir, resolveFrameworkDir(projectDir), 'presets'),
     join(projectDir, 'framework', 'presets'),
   ];
 
@@ -535,7 +552,7 @@ export function detectPreset(projectDir) {
 
   // Check both deployed and package locations
   const locations = [
-    join(projectDir, 'chati.dev', 'presets'),
+    join(projectDir, resolveFrameworkDir(projectDir), 'presets'),
     join(projectDir, 'framework', 'presets'),
   ];
 

package/src/terminal/run-parallel.js

@@ -210,7 +210,7 @@ async function main() {
     summary: r.handoff?.summary || '',
   }));
 
-  const merged = mergeHandoffs(mergeInput);
+  const merged = mergeHandoffs(mergeInput, projectDir);
   const nextAgent = determineNextAgent(agents);
   const consolidated = buildConsolidatedHandoff(merged, nextAgent);
 

package/src/terminal/run-team.js

@@ -36,13 +36,13 @@ import {
 // ---------------------------------------------------------------------------
 
 const TEAM_MEMBERS = {
-  planning: ['detail', 'architect', 'ux'],
+  planning: ['detail', 'architect', 'ux', 'qa-planning'],
   build: ['dev', 'qa-implementation'],
 };
 
 // Task IDs match the Shared Task List template (team-planning-tasks.yaml / team-build-tasks.yaml)
 const TEAM_TASK_IDS = {
-  planning: ['TT-PLN-001', 'TT-PLN-002', 'TT-PLN-003'],
+  planning: ['TT-PLN-001', 'TT-PLN-002', 'TT-PLN-003', 'TT-PLN-005'],
   build: ['TT-BLD-001-DEV', 'TT-BLD-001-QA'],
 };
 
@@ -276,7 +276,7 @@ async function main() {
     summary: r.handoff?.summary || '',
   }));
 
-  const merged = mergeHandoffs(mergeInput);
+  const merged = mergeHandoffs(mergeInput, projectDir);
   const nextAgent = determineNextAgent(teamType);
   const consolidated = buildConsolidatedHandoff(merged, nextAgent);
 

package/src/terminal/team-task-list.js

@@ -8,11 +8,35 @@
  * when multiple team members update concurrently.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
-import { join, dirname } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, realpathSync } from 'fs';
+import { join, dirname, resolve, relative } from 'path';
 import yaml from 'js-yaml';
 import { withLock } from '../utils/file-lock.js';
 
+// ---------------------------------------------------------------------------
+// Path Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Assert that a target path is within .chati/teams/ to prevent path traversal.
+ * @param {string} targetPath - Absolute or relative path to validate
+ * @param {string} projectDir - Project root directory
+ * @throws {Error} If targetPath resolves outside .chati/teams/
+ */
+function assertWithinTeamsDir(targetPath, projectDir) {
+  const teamsRoot = resolve(projectDir, '.chati', 'teams');
+  // Resolve symlinks so a symlink inside teams/ pointing outside (e.g., /etc/passwd)
+  // cannot bypass the boundary check. Fall back to plain resolve() if file doesn't exist
+  // yet (which is normal — we're about to create it).
+  const safeRealpath = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+  const realTeamsRoot = safeRealpath(teamsRoot);
+  const absPath = safeRealpath(targetPath);
+  const rel = relative(realTeamsRoot, absPath);
+  if (rel.startsWith('..') || rel.startsWith('/')) {
+    throw new Error(`Path ${targetPath} is outside .chati/teams/ — refusing write`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Task List Management
 // ---------------------------------------------------------------------------
@@ -25,6 +49,9 @@ import { withLock } from '../utils/file-lock.js';
  * @returns {{ created: boolean, path: string }}
  */
 export function initTaskList(destPath, templatePath, overrides = {}) {
+  // Derive projectDir: destPath is <projectDir>/.chati/teams/<teamId>/<file>
+  const projectDir = resolve(destPath, '..', '..', '..', '..');
+  assertWithinTeamsDir(destPath, projectDir);
   mkdirSync(dirname(destPath), { recursive: true });
 
   if (!existsSync(templatePath)) {
@@ -61,6 +88,9 @@ export function readTaskList(path) {
  * @returns {Promise<{ updated: boolean, task: object|null }>}
  */
 export async function updateTaskStatus(path, taskId, updates) {
+  // Derive projectDir: path is <projectDir>/.chati/teams/<teamId>/<file>
+  const projectDir = resolve(path, '..', '..', '..', '..');
+  assertWithinTeamsDir(path, projectDir);
   return withLock(path, () => {
     const taskList = readTaskList(path);
     if (!taskList || !taskList.tasks) return { updated: false, task: null };
@@ -68,6 +98,8 @@ export async function updateTaskStatus(path, taskId, updates) {
     const task = taskList.tasks.find(t => t.id === taskId);
     if (!task) return { updated: false, task: null };
 
+    // Normalize 'completed' → 'done' (CLI uses 'completed', team YAML uses 'done')
+    if (updates.status === 'completed') updates.status = 'done';
     Object.assign(task, updates, { last_updated: new Date().toISOString() });
     if (updates.status === 'done' && !task.completed_at) {
       task.completed_at = new Date().toISOString();
@@ -93,6 +125,10 @@ export function getTeamProgress(path) {
   const tasks = taskList.tasks;
   const memberProgress = {};
 
+  // Normalize: both 'done' and 'completed' indicate task completion.
+  // CLI uses AGENT_STATUS.COMPLETED = 'completed'; team task YAML traditionally uses 'done'.
+  const isDone = (status) => status === 'done' || status === 'completed';
+
   for (const task of tasks) {
     const assignee = task.assigned_to;
     if (!assignee) continue;
@@ -100,7 +136,7 @@ export function getTeamProgress(path) {
       memberProgress[assignee] = { status: 'pending', score: null, tasks: 0, completed: 0 };
     }
     memberProgress[assignee].tasks++;
-    if (task.status === 'done') {
+    if (isDone(task.status)) {
       memberProgress[assignee].completed++;
       memberProgress[assignee].score = task.score;
     } else if (task.status === 'in_progress') {
@@ -119,7 +155,7 @@ export function getTeamProgress(path) {
 
   return {
     total: tasks.length,
-    done: tasks.filter(t => t.status === 'done').length,
+    done: tasks.filter(t => isDone(t.status)).length,
     pending: tasks.filter(t => t.status === 'pending').length,
     blocked: tasks.filter(t => t.status === 'blocked').length,
     inProgress: tasks.filter(t => t.status === 'in_progress').length,
@@ -142,6 +178,9 @@ export function getTeamProgress(path) {
  * @returns {{ written: boolean, path: string }}
  */
 export function writeMailboxMessage(mailboxDir, from, to, type, payload) {
+  // Derive projectDir: mailboxDir is <projectDir>/.chati/teams/<teamId>/mailbox
+  const projectDir = resolve(mailboxDir, '..', '..', '..', '..');
+  assertWithinTeamsDir(mailboxDir, projectDir);
   mkdirSync(mailboxDir, { recursive: true });
 
   const timestamp = Date.now();

package/src/upgrade/backup.js

@@ -1,12 +1,13 @@
 import { existsSync, mkdirSync, cpSync, rmSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**
  * Create backup of chati.dev/ directory before upgrade
  * Backup location: chati.dev/.backup-v{version}/
  */
 export function createBackup(targetDir, currentVersion) {
-  const frameworkDir = join(targetDir, 'chati.dev');
+  const frameworkDir = join(targetDir, resolveFrameworkDir(targetDir));
   const backupDir = join(frameworkDir, `.backup-v${currentVersion}`);
 
   if (existsSync(backupDir)) {
@@ -60,7 +61,7 @@ export function createBackup(targetDir, currentVersion) {
  * Restore from backup (rollback)
  */
 export function restoreFromBackup(targetDir, version) {
-  const frameworkDir = join(targetDir, 'chati.dev');
+  const frameworkDir = join(targetDir, resolveFrameworkDir(targetDir));
   const backupDir = join(frameworkDir, `.backup-v${version}`);
 
   if (!existsSync(backupDir)) {

package/src/upgrade/checker.js

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import yaml from 'js-yaml';
 import semver from 'semver';
 
@@ -7,7 +8,7 @@ import semver from 'semver';
  * Read current installed version from config.yaml
  */
 export function getCurrentVersion(targetDir) {
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
   if (!existsSync(configPath)) return null;
 
   try {
@@ -74,7 +75,7 @@ function getChangelog(fromVersion, toVersion) {
  * Update config.yaml with the new version after successful upgrade
  */
 export function updateConfigVersion(targetDir, newVersion) {
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
   if (!existsSync(configPath)) return false;
 
   try {

package/src/upgrade/migrator.js

@@ -1,14 +1,37 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import yaml from 'js-yaml';
 import semver from 'semver';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Bundled framework source — always contains the latest migrations from the CLI package
+const BUNDLED_MIGRATIONS = join(__dirname, '..', '..', 'framework', 'migrations');
+const MONOREPO_MIGRATIONS = join(__dirname, '..', '..', '..', '..', 'chati.dev', 'migrations');
+
 /**
- * Find applicable migrations between two versions
+ * Find applicable migrations between two versions.
+ *
+ * Reads from the BUNDLED framework (shipped with the CLI package), NOT from
+ * the installed copy. This is critical because on upgrade, the installed
+ * framework still holds the OLD migrations — new ones aren't copied until
+ * after migrations run. Without this, new migrations would never execute on
+ * the first upgrade to the version that introduced them.
  */
 export function findMigrations(targetDir, fromVersion, toVersion) {
-  const migrationsDir = join(targetDir, 'chati.dev', 'migrations');
-  if (!existsSync(migrationsDir)) return [];
+  // Prefer bundled (npm package) source; fall back to monorepo dev layout;
+  // last resort, the already-installed copy (legacy behavior).
+  let migrationsDir = null;
+  if (existsSync(BUNDLED_MIGRATIONS)) {
+    migrationsDir = BUNDLED_MIGRATIONS;
+  } else if (existsSync(MONOREPO_MIGRATIONS)) {
+    migrationsDir = MONOREPO_MIGRATIONS;
+  } else {
+    const installedDir = join(targetDir, resolveFrameworkDir(targetDir), 'migrations');
+    if (existsSync(installedDir)) migrationsDir = installedDir;
+  }
+  if (!migrationsDir) return [];
 
   const files = readdirSync(migrationsDir)
     .filter(f => f.endsWith('.yaml'))
@@ -52,7 +75,7 @@ export function findMigrations(targetDir, fromVersion, toVersion) {
 /**
  * Execute a single migration step
  */
-function executeMigrationStep(targetDir, step) {
+async function executeMigrationStep(targetDir, step) {
   switch (step.type) {
     case 'create_directory': {
       const dir = join(targetDir, step.path);
@@ -117,6 +140,41 @@ function executeMigrationStep(targetDir, step) {
       break;
     }
 
+    case 'update_gitignore': {
+      // Delegates to installer's updateGitignore via a dynamic import to keep
+      // concerns separated. The selectedIDEs come from the installed config.
+      // Best-effort: if anything fails, we skip silently so migration doesn't break.
+      try {
+        const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
+        let selectedIDEs = ['claude-code'];
+        if (existsSync(configPath)) {
+          const cfg = yaml.load(readFileSync(configPath, 'utf-8')) || {};
+          if (Array.isArray(cfg.ides)) selectedIDEs = cfg.ides;
+        }
+        // Inline call (avoid circular import with core.js in tests).
+        // We replicate the updateGitignore logic here is not ideal, so instead
+        // call through a dedicated helper: core.js exports updateGitignore.
+        const core = await import('../installer/core.js');
+        if (typeof core.updateGitignore === 'function') {
+          core.updateGitignore(targetDir, selectedIDEs);
+        }
+      } catch { /* expected: skip if installer helper not available */ }
+      break;
+    }
+
+    case 'warn_tracked_files': {
+      // Non-blocking warning — detects already-tracked framework files.
+      try {
+        const { detectTrackedFrameworkFiles } = await import('./tracked-files-detector.js');
+        const { renderTrackedFilesWarning } = await import('./user-messages.js');
+        const tracked = detectTrackedFrameworkFiles(targetDir);
+        if (tracked.length > 0) {
+          process.stdout.write(renderTrackedFilesWarning(tracked));
+        }
+      } catch { /* expected: skip if git unavailable */ }
+      break;
+    }
+
     default:
       // Unknown step type - skip
       break;
@@ -138,7 +196,7 @@ export async function runMigrations(targetDir, fromVersion, toVersion) {
   for (const migration of migrations) {
     try {
       for (const step of migration.steps) {
-        executeMigrationStep(targetDir, step);
+        await executeMigrationStep(targetDir, step);
       }
       results.push({ file: migration.file, success: true });
     } catch (err) {
@@ -147,7 +205,7 @@ export async function runMigrations(targetDir, fromVersion, toVersion) {
       // Attempt rollback for this migration
       try {
         for (const step of migration.rollback) {
-          executeMigrationStep(targetDir, step);
+          await executeMigrationStep(targetDir, step);
         }
       } catch (rollbackErr) {
         console.error('[chati] migration rollback failed:', rollbackErr?.message);

package/src/upgrade/tracked-files-detector.js

@@ -0,0 +1,86 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Framework file patterns that should never be committed to git.
+ * Each entry is a path (relative to targetDir) that git ls-files will check.
+ */
+const FRAMEWORK_PATTERNS = [
+  '.chati.dev/',
+  '.chati/session.yaml',
+  '.chati/teams/',
+  '.chati/timeline.json',
+  '.chati/memories/shared/session/',
+  '.chati/memories/shared/gotchas.json',
+  '.chati/memories/shared/error-log.json',
+  '.claude/commands/chati.md',
+  '.claude/rules/chati/',
+  '.claude/settings.local.json',
+  'CLAUDE.local.md',
+  '.gemini/session-lock.md',
+  'AGENTS.override.md',
+  '.gemini/commands/',
+  '.gemini/context/',
+  '.gemini/hooks/',
+  '.gemini/settings.json',
+  '.codex/',
+  '.agents/skills/chati/',
+];
+
+/**
+ * Check whether targetDir is a git repository by verifying .git/ exists.
+ * @param {string} targetDir
+ * @returns {boolean}
+ */
+function isGitRepo(targetDir) {
+  return existsSync(join(targetDir, '.git'));
+}
+
+/**
+ * Detect which framework-owned paths are currently tracked by git.
+ * Does NOT modify git state — read-only operation.
+ *
+ * @param {string} targetDir - absolute path to the project root
+ * @returns {string[]} array of tracked framework file paths (relative to targetDir)
+ */
+export function detectTrackedFrameworkFiles(targetDir) {
+  if (!isGitRepo(targetDir)) {
+    return [];
+  }
+
+  const tracked = [];
+
+  for (const pattern of FRAMEWORK_PATTERNS) {
+    try {
+      const result = execSync(`git ls-files -- "${pattern}"`, {
+        cwd: targetDir,
+        stdio: ['ignore', 'pipe', 'ignore'],
+        timeout: 5000,
+      })
+        .toString()
+        .trim();
+
+      if (result.length > 0) {
+        tracked.push(pattern);
+      }
+    } catch {
+      // git ls-files failure means path is not tracked — skip
+    }
+  }
+
+  // Deduplicate in case patterns overlap
+  return [...new Set(tracked)];
+}
+
+/**
+ * Build the list of `git rm -r --cached <path>` commands for untracking.
+ * Deduplicates entries and returns one command string per path.
+ *
+ * @param {string[]} files - array of tracked framework paths
+ * @returns {string[]} array of git rm commands
+ */
+export function formatUntrackCommands(files) {
+  const unique = [...new Set(files)];
+  return unique.map(f => `git rm -r --cached "${f}"`);
+}

package/src/upgrade/user-messages.js

@@ -0,0 +1,94 @@
+import { formatUntrackCommands } from './tracked-files-detector.js';
+
+/**
+ * Render a plain-text warning when framework files are tracked by git.
+ *
+ * Non-blocking — the caller must decide whether to halt the upgrade.
+ * No ANSI color codes: output is suitable for piping and log files.
+ *
+ * @param {string[]} files - tracked framework paths detected by detectTrackedFrameworkFiles()
+ * @returns {string} warning text ready to print to stdout/stderr
+ */
+export function renderTrackedFilesWarning(files) {
+  if (!files || files.length === 0) return '';
+
+  const bullet = files.map(f => `  - ${f}`).join('\n');
+  const commands = formatUntrackCommands(files);
+  const cmdBlock = commands.join(' \\\n    ');
+
+  return [
+    '',
+    '================================================================',
+    'WARNING: Chati framework files are tracked by git',
+    '================================================================',
+    '',
+    'The following Chati-owned paths are currently committed to git:',
+    '',
+    bullet,
+    '',
+    'Why this matters:',
+    '  - Framework internals (agents, hooks, session state) are not',
+    '    project source code and should not be versioned alongside it.',
+    '  - Committing them risks leaking internal IP and stale runtime',
+    '    state (session locks, memory caches, team mailboxes) to',
+    '    remote repositories or collaborators.',
+    '  - Backup directories inside .chati.dev/ can be multi-megabyte',
+    '    and will bloat your git history permanently.',
+    '',
+    'What to do:',
+    '  Run the commands below to stop tracking these paths.',
+    '  The files remain on disk — only git tracking is removed.',
+    '',
+    '  ' + cmdBlock,
+    '  git commit -m "chore: untrack Chati framework files from git"',
+    '',
+    'You can run these commands now or after the upgrade completes.',
+    'The upgrade will continue regardless.',
+    '================================================================',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Render a banner shown at the start of `chati upgrade`.
+ *
+ * @param {string} fromVersion - current installed version (e.g. "4.2.3")
+ * @param {string} toVersion   - target version (e.g. "4.3.0")
+ * @returns {string}
+ */
+export function renderUpgradeBanner(fromVersion, toVersion) {
+  return [
+    '',
+    '================================================================',
+    `Chati.dev Upgrade: v${fromVersion} -> v${toVersion}`,
+    '================================================================',
+    '',
+    'Steps: backup -> migrations -> sync files -> validate -> done',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Render a success message shown after a completed upgrade.
+ *
+ * @param {string} fromVersion - version upgraded from
+ * @param {string} toVersion   - version upgraded to
+ * @returns {string}
+ */
+export function renderUpgradeSuccess(fromVersion, toVersion) {
+  return [
+    '',
+    '================================================================',
+    `Chati.dev successfully upgraded: v${fromVersion} -> v${toVersion}`,
+    '================================================================',
+    '',
+    'Next steps:',
+    '  1. Review any warnings printed above.',
+    '  2. If framework files were tracked by git, run the provided',
+    '     git rm --cached commands and commit the result.',
+    '  3. Type /chati in your project to resume where you left off.',
+    '',
+    'Release notes: https://github.com/chati-dev/chati.dev/releases',
+    '',
+  ].join('\n');
+}

package/src/utils/config-parser.js

@@ -8,6 +8,7 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from './framework-dir.js';
 
 /**
  * Parse provider configuration from config.yaml.
@@ -16,7 +17,7 @@ import { join } from 'path';
  * @returns {{ primary: string, enabled: string[], raw: string|null }}
  */
 export function parseProviderConfig(projectDir) {
-  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
   if (!existsSync(configPath)) {
     return { primary: 'claude', enabled: ['claude'], raw: null };
   }

package/src/utils/feature-flags.js

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
+import { resolveFrameworkDir } from './framework-dir.js';
 
 /**
  * All known feature flags with their default values.
@@ -49,7 +50,7 @@ export function isFeatureEnabled(projectDir, featureName) {
  * @returns {Record<string, boolean>} Map of feature name to enabled status
  */
 export function getEnabledFeatures(projectDir) {
-  const configPath = join(projectDir, 'chati.dev', 'config.yaml');
+  const configPath = join(projectDir, resolveFrameworkDir(projectDir), 'config.yaml');
   if (!existsSync(configPath)) {
     return { ...DEFAULTS };
   }