chati-dev 4.2.2 → 4.3.1

package/src/autonomy/build-state.js

@@ -8,7 +8,7 @@
  * Constitution Article XVII — Execution Mode Governance.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
 import { join, dirname } from 'path';
 
 // ---------------------------------------------------------------------------
@@ -281,7 +281,6 @@ export function getProgress(state) {
 export function clearBuildState(projectDir) {
   const statePath = join(projectDir, BUILD_STATE_FILE);
   if (existsSync(statePath)) {
-    const { unlinkSync } = require('fs');
     unlinkSync(statePath);
   }
 }

package/src/autonomy/progress-reporter.js

@@ -160,7 +160,7 @@ export function calculateCompletion(pipelineState) {
 function getStageAgents(stage) {
   const stages = {
     DISCOVER: ['greenfield-wu', 'brownfield-wu', 'brief'],
-    PLAN: ['detail', 'architect', 'ux', 'phases', 'tasks', 'qa-planning'],
+    PLAN: ['detail', 'architect', 'ux', 'phases', 'tasks'], // qa-planning runs inside Planning Team; score synced via team dissolution
     BUILD: ['dev', 'qa-implementation'],
     DEPLOY: ['devops'],
   };

package/src/config/agent-customizer.js

@@ -10,13 +10,21 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Directory relative to project root where customization files are stored. */
-const CUSTOMIZE_DIR = 'chati.dev/customize';
+/**
+ * Get the customize directory for a given project.
+ * Supports both .chati.dev/ and chati.dev/ structures.
+ * @param {string} projectDir
+ * @returns {string} Relative path from project root
+ */
+function getCustomizeDir(projectDir) {
+  return `${resolveFrameworkDir(projectDir)}/customize`;
+}
 
 /** Valid override fields that customizations can set. */
 export const VALID_OVERRIDE_FIELDS = [
@@ -57,7 +65,7 @@ export function loadCustomization(projectDir, agentName) {
     return { found: false, overrides: {} };
   }
 
-  const customizePath = join(projectDir, CUSTOMIZE_DIR, `${agentName}.yaml`);
+  const customizePath = join(projectDir, getCustomizeDir(projectDir), `${agentName}.yaml`);
 
   if (!existsSync(customizePath)) {
     return { found: false, overrides: {} };

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

@@ -1,14 +1,14 @@
 /**
  * Claude Code settings.json generator.
  *
- * Produces .claude/settings.json content that wires the 10 chati.dev hooks
+ * Produces .claude/settings.json content that wires the 14 chati.dev hooks
  * into Claude Code's hook system and applies a baseline permission policy.
  *
  * Background: prior to v4.2.2, the installer wrote hooks to
- * chati.dev/hooks/settings.json — but Claude Code reads .claude/settings.json,
+ * .chati.dev/hooks/settings.json — but Claude Code reads .claude/settings.json,
  * not the framework's bundled file. As a result, every hook was dormant for
  * every Claude Code user since the project started. This generator is the fix:
- * it produces the file Claude Code actually loads, registers all 10 hooks at
+ * it produces the file Claude Code actually loads, registers all 14 hooks at
  * the canonical events, and applies a generic permission policy modeled on
  * production Claude Code setups.
  *
@@ -20,16 +20,23 @@
 
 /**
  * Hook registration map. Each entry is one hook script and the events it
- * should fire on. Source of truth lives in chati.dev/hooks/.
+ * should fire on. Source of truth lives in .chati.dev/hooks/.
  */
 const HOOK_REGISTRY = [
   // UserPromptSubmit — fires on every user message turn.
-  // license-guard MUST be first so license check runs before any other work.
-  { name: 'license-guard',     event: 'UserPromptSubmit', matcher: '.*' },
+  // NOTE: license-guard is NOT here. UserPromptSubmit blocks are SILENT (prompt
+  // is dropped, no message shown to user). License enforcement is done via:
+  //   1. Slash command STEP 0 (visible — Claude runs checkLicense() via Bash)
+  //   2. PreToolUse catch-all below (backup — Claude sees deny reason, reports it)
   { name: 'prism-engine',      event: 'UserPromptSubmit', matcher: '.*' },
   { name: 'model-governance',  event: 'UserPromptSubmit', matcher: '.*' },
 
   // PreToolUse — fires before each tool call. Matcher targets specific tools.
+  // license-guard is first on catch-all ".*" — blocks ALL tool calls when
+  // license is expired. Claude sees the deny reason and can report it to user.
+  // This is the backup defense: even if someone bypasses the slash command,
+  // no tool call succeeds with an expired license.
+  { name: 'license-guard',     event: 'PreToolUse', matcher: '.*' },
   { name: 'read-protection',   event: 'PreToolUse', matcher: 'Read' },
   { name: 'constitution-guard',event: 'PreToolUse', matcher: 'Bash|Write|Edit' },
   { name: 'mode-governance',   event: 'PreToolUse', matcher: 'Write|Edit' },
@@ -37,6 +44,16 @@ const HOOK_REGISTRY = [
   { name: 'undercover-guard',  event: 'PreToolUse', matcher: 'Write|Edit|Bash' },
   { name: 'team-quality-gate', event: 'PreToolUse', matcher: 'Write|Edit' },
 
+  // PostToolUse — fires after each tool call. Used to auto-advance the pipeline
+  // when an agent finishes writing its handoff. Hook inspects the written path
+  // and triggers `chati-router.js advance` if it matches an agent handoff file.
+  { name: 'advance-trigger',   event: 'PostToolUse', matcher: 'Write' },
+  { name: 'reference-trigger', event: 'PostToolUse', matcher: 'Write' },
+  { name: 'brief-validator',   event: 'PostToolUse', matcher: 'Write' },
+  // Autonomous-completion v1 (ADR-AUTO-06): spawns visual-qa.js on
+  // dev-handoff write so the next /chati turn already has report.json.
+  { name: 'post-dev',          event: 'PostToolUse', matcher: 'Write' },
+
   // PreCompact — fires before context compaction (observational).
   { name: 'session-digest',    event: 'PreCompact', matcher: '' },
 ];
@@ -64,6 +81,9 @@ const PERMISSIONS_ALLOW = [
   'EnterPlanMode',
   'ExitPlanMode',
   'KillShell',
+  'Bash(npx playwright:*)',
+  'Bash(node .chati.dev/scripts/*)',
+  'Bash(node chati.dev/scripts/*)',
 ];
 
 /**
@@ -164,7 +184,7 @@ function buildHooksObject() {
     }
     matcherGroups.get(entry.matcher).push({
       type: 'command',
-      command: `node chati.dev/hooks/${entry.name}.js`,
+      command: `node .chati.dev/hooks/${entry.name}.js`,
     });
   }
 

package/src/config/context-file-generator.js

@@ -13,6 +13,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { getEnabledNonClaudeProviders } from '../utils/config-parser.js';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 // ---------------------------------------------------------------------------
 // Replacement Maps
@@ -48,23 +49,34 @@ const CODEX_STRIP_PATTERNS = [
 ];
 
 /**
- * Text replacements for Codex CLI context file.
- * Note: Codex has no commands/ or rules/ directories — references point to chati.dev/.
+ * Build text replacements for Codex CLI context file.
+ * Note: Codex has no commands/ or rules/ directories — references point to the framework dir.
+ *
+ * @param {string} [frameworkDir='chati.dev'] - Resolved framework directory name (e.g. 'chati.dev' or '.chati.dev')
+ * @returns {Array<[string, string]>} Replacement pairs
  */
-const CODEX_REPLACEMENTS = [
-  ['Claude Code', 'Codex CLI'],
-  ['claude code', 'Codex CLI'],
-  ['CLAUDE.md', 'AGENTS.md'],
-  ['Claude.md', 'AGENTS.md'],
-  ['.claude/commands/', 'chati.dev/orchestrator/'],
-  ['.claude/rules/chati/', 'chati.dev/context/'],
-  ['.claude/rules/', 'chati.dev/context/'],
-  ['.claude/mcp.json', '.codex/config.toml'],
-  ['claude --print', 'codex exec'],
-  ['claude -p', 'codex exec'],
-  ['CLAUDE.local.md', 'AGENTS.override.md'],
-  ['/chati', '$chati'],
-];
+function buildCodexReplacements(frameworkDir = 'chati.dev') {
+  return [
+    ['Claude Code', 'Codex CLI'],
+    ['claude code', 'Codex CLI'],
+    ['CLAUDE.md', 'AGENTS.md'],
+    ['Claude.md', 'AGENTS.md'],
+    ['.claude/commands/', `${frameworkDir}/orchestrator/`],
+    ['.claude/rules/chati/', `${frameworkDir}/context/`],
+    ['.claude/rules/', `${frameworkDir}/context/`],
+    ['.claude/mcp.json', '.codex/config.toml'],
+    ['claude --print', 'codex exec'],
+    ['claude -p', 'codex exec'],
+    ['CLAUDE.local.md', 'AGENTS.override.md'],
+    ['/chati', '$chati'],
+  ];
+}
+
+/**
+ * Text replacements for Codex CLI context file (legacy constant using default 'chati.dev/' prefix).
+ * @deprecated Use buildCodexReplacements(frameworkDir) for correct path resolution.
+ */
+const CODEX_REPLACEMENTS = buildCodexReplacements();
 
 // ---------------------------------------------------------------------------
 // Generators
@@ -122,10 +134,12 @@ export function generateGeminiMd(content) {
  *
  * @param {string} content - Raw CLAUDE.md content
  * @param {object} [contextFiles] - Optional inline context { root, governance, protocols, quality }
+ * @param {string} [frameworkDir='chati.dev'] - Resolved framework directory name
  * @returns {string} Adapted content for AGENTS.md
  */
-export function generateAgentsMd(content, contextFiles = null) {
+export function generateAgentsMd(content, contextFiles = null, frameworkDir = 'chati.dev') {
   let result = content;
+  const replacements = buildCodexReplacements(frameworkDir);
 
   // Strip hook-related sections (Codex has no hooks support)
   for (const pattern of CODEX_STRIP_PATTERNS) {
@@ -133,7 +147,7 @@ export function generateAgentsMd(content, contextFiles = null) {
   }
 
   // Apply text replacements
-  for (const [search, replace] of CODEX_REPLACEMENTS) {
+  for (const [search, replace] of replacements) {
     result = result.replaceAll(search, replace);
   }
 
@@ -155,7 +169,7 @@ export function generateAgentsMd(content, contextFiles = null) {
       if (fileContent) {
         // Adapt context for Codex (replace Claude-specific refs)
         let adapted = fileContent;
-        for (const [search, replace] of CODEX_REPLACEMENTS) {
+        for (const [search, replace] of replacements) {
           adapted = adapted.replaceAll(search, replace);
         }
         sections.push(adapted.trim());
@@ -213,6 +227,9 @@ export function generateContextFiles(projectDir, baseContent = null) {
   // Read context files for inline injection (Codex)
   const contextFiles = readContextFilesFromDisk(projectDir);
 
+  // Resolve framework directory for dynamic path generation
+  const fwDir = resolveFrameworkDir(projectDir);
+
   // Provider-to-generator mapping
   const generators = {
     gemini: {
@@ -221,7 +238,7 @@ export function generateContextFiles(projectDir, baseContent = null) {
     },
     codex: {
       filename: 'AGENTS.md',
-      generate: (content) => generateAgentsMd(content, contextFiles),
+      generate: (content) => generateAgentsMd(content, contextFiles, fwDir),
     },
   };
 
@@ -247,7 +264,10 @@ export function generateContextFiles(projectDir, baseContent = null) {
  * @returns {object|null} { root, governance, protocols, quality } or null
  */
 function readContextFilesFromDisk(projectDir) {
-  const contextDir = join(projectDir, 'chati.dev', 'context');
+  // Support both new (.chati.dev/) and legacy (chati.dev/) structures
+  const newDir = join(projectDir, '.chati.dev', 'context');
+  const legacyDir = join(projectDir, 'chati.dev', 'context');
+  const contextDir = existsSync(newDir) ? newDir : legacyDir;
   if (!existsSync(contextDir)) return null;
 
   const files = {};

package/src/config/framework-adapter.js

@@ -31,6 +31,7 @@ export const ADAPTABLE_FILES = new Set([
   'agents/plan/tasks.md',
   'agents/quality/qa-planning.md',
   'agents/quality/qa-implementation.md',
+  'agents/quality/qa-visual.md',
   'agents/build/dev.md',
   'agents/deploy/devops.md',
   'context/governance.md',

package/src/config/gemini-hooks-generator.js

@@ -34,6 +34,7 @@ export const HOOK_MAP = {
   'session-digest': { event: 'PreCompress', description: 'Save session state before context compression' },
   'undercover-guard': { event: 'BeforeTool', description: 'Advisory: sanitize internal framework references from deliverables' },
   'style-guard': { event: 'BeforeTool', description: 'Advisory: enforce em-dash and emoji standards' },
+  'team-quality-gate': { event: 'BeforeTool', description: 'Validate team task completion and quality scores before handoff (Article XXI)' },
 };
 
 // ---------------------------------------------------------------------------
@@ -57,6 +58,16 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = join(__filename, '..');
 const projectRoot = join(__dirname, '..', '..');
+
+/**
+ * Resolve framework directory (supports .chati.dev/ and legacy chati.dev/).
+ * @param {string} cwd - Project root directory
+ */
+function resolveFrameworkDir(cwd) {
+  const newPath = join(cwd, '.chati.dev');
+  if (existsSync(newPath)) return '.chati.dev';
+  return 'chati.dev';
+}
 `;
 
 /**
@@ -86,7 +97,7 @@ async function main() {
     }
 
     // Delegate to shared PRISM engine logic
-    const hookPath = join(cwd, 'chati.dev', 'hooks', 'prism-engine.js');
+    const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'prism-engine.js');
     if (existsSync(hookPath)) {
       const mod = await import(hookPath);
       if (typeof mod.buildPrismContext === 'function') {
@@ -141,7 +152,7 @@ async function main() {
 
     if (agent) {
       // Delegate to shared model governance logic
-      const hookPath = join(cwd, 'chati.dev', 'hooks', 'model-governance.js');
+      const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'model-governance.js');
       if (existsSync(hookPath)) {
         const mod = await import(hookPath);
         if (typeof mod.getRecommendedModel === 'function') {
@@ -175,8 +186,9 @@ function generateModeGovernance() {
  * Blocks write operations outside current mode scope.
  * Constitution Article XI enforcement.
  */
+const fwDir = existsSync(join(process.cwd(), '.chati.dev')) ? '.chati.dev' : 'chati.dev';
 const MODE_SCOPES = {
-  planning: { allowed: ['chati.dev/', '.chati/', 'chati.dev/artifacts/'] },
+  planning: { allowed: [fwDir + '/', '.chati/', 'artifacts/'] },
   build: { allowed: ['*'] },
   deploy: { allowed: ['*'] },
 };
@@ -447,7 +459,7 @@ async function main() {
     const cwd = event.cwd || process.cwd();
 
     // Delegate to shared session digest logic
-    const hookPath = join(cwd, 'chati.dev', 'hooks', 'session-digest.js');
+    const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'session-digest.js');
     if (existsSync(hookPath)) {
       const mod = await import(hookPath);
       if (typeof mod.saveDigest === 'function') {
@@ -495,7 +507,7 @@ async function main() {
     }
 
     // Delegate to shared undercover guard logic
-    const hookPath = join(cwd, 'chati.dev', 'hooks', 'undercover-guard.js');
+    const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'undercover-guard.js');
     if (!existsSync(hookPath)) {
       console.log(JSON.stringify({}));
       return;
@@ -565,7 +577,7 @@ async function main() {
     }
 
     // Delegate to shared style guard logic
-    const hookPath = join(cwd, 'chati.dev', 'hooks', 'style-guard.js');
+    const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'style-guard.js');
     if (!existsSync(hookPath)) {
       console.log(JSON.stringify({}));
       return;
@@ -648,7 +660,7 @@ async function main() {
     const cwd = event.cwd || process.cwd();
 
     // Delegate to canonical license check
-    const hookPath = join(cwd, 'chati.dev', 'hooks', 'license-guard.js');
+    const hookPath = join(cwd, resolveFrameworkDir(cwd), 'hooks', 'license-guard.js');
     if (!existsSync(hookPath)) {
       // No canonical hook present — fail open
       console.log(JSON.stringify({}));

package/src/config/mcp-configs.js

@@ -42,6 +42,7 @@ export const AGENT_MCP_DEPS = {
   'qa-planning':       { required: [],            optional: [] },
   dev:                 { required: ['context7'],  optional: ['browser'] },
   'qa-implementation': { required: [],            optional: ['browser'] },
+  'qa-visual':         { required: [],            optional: ['browser'] },
   devops:              { required: [],            optional: [] },
 };
 

package/src/context/layers/l1-global.js

@@ -6,6 +6,7 @@
  */
 
 import { loadGlobalDomain, extractRules } from '../domain-loader.js';
+import { resolveFrameworkDir } from '../../utils/framework-dir.js';
 
 // Maps session states to governance modes for domain lookup
 const STATE_TO_GOVERNANCE_MODE = {
@@ -40,7 +41,7 @@ export function processL1(ctx) {
     rules,
     mode: sessionMode,
     modeRules: {
-      writeScope: modeRules.writeScope || 'chati.dev/',
+      writeScope: modeRules.writeScope || resolveFrameworkDir(ctx.projectDir || process.cwd()) + '/',
       allowedActions: modeRules.allowedActions || [],
       blockedActions: modeRules.blockedActions || [],
     },

package/src/dashboard/data-reader.js

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
 /**
  * Read all dashboard data from project directory
@@ -31,7 +32,7 @@ export async function readDashboardData(targetDir) {
   }
 
   // Read config.yaml
-  const configPath = join(targetDir, 'chati.dev', 'config.yaml');
+  const configPath = join(targetDir, resolveFrameworkDir(targetDir), 'config.yaml');
   if (existsSync(configPath)) {
     try {
       data.config = yaml.load(readFileSync(configPath, 'utf-8'));
@@ -59,7 +60,7 @@ export async function readDashboardData(targetDir) {
   }
 
   // Read task progress from artifacts
-  const tasksDir = join(targetDir, 'chati.dev', 'artifacts', '6-Tasks');
+  const tasksDir = join(targetDir, 'artifacts', '6-Tasks');
   if (existsSync(tasksDir)) {
     try {
       const files = readdirSync(tasksDir).filter(f => f.endsWith('.yaml') || f.endsWith('.md'));
@@ -70,7 +71,7 @@ export async function readDashboardData(targetDir) {
   }
 
   // Read gotchas
-  const gotchasPath = join(targetDir, 'chati.dev', 'intelligence', 'gotchas.yaml');
+  const gotchasPath = join(targetDir, resolveFrameworkDir(targetDir), 'intelligence', 'gotchas.yaml');
   if (existsSync(gotchasPath)) {
     try {
       const gotchasData = yaml.load(readFileSync(gotchasPath, 'utf-8'));

package/src/dashboard/layout.js

@@ -62,7 +62,8 @@ export function buildProjectInfo(data) {
   const name = project.name || 'unknown';
   const type = project.type === 'brownfield' ? 'Brownfield' : 'Greenfield';
   const state = formatState(project.state);
-  const mode = formatMode(session.execution_mode);
+  const rawMode = session.execution_mode;
+  const mode = formatMode(rawMode && typeof rawMode === 'object' ? rawMode.mode : rawMode);
   const lang = session.language || 'en';
   // Show the provider-specific IDE (last in the list) rather than always claude-code
   const ides = session.ides || [];

package/src/decision/analyzer.js

@@ -8,6 +8,8 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { flattenEntitiesFromRegistry } from '../utils/flatten-entities.js';
 
 /**
  * Analyze impact of changing an entity.
@@ -38,12 +40,12 @@ export function analyzeImpact(projectDir, entityPath) {
   }
 
   // Load entity details
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
   const registry = existsSync(registryPath)
     ? yaml.load(readFileSync(registryPath, 'utf8'))
     : { entities: {} };
 
-  const allEntities = flattenEntities(registry);
+  const allEntities = flattenEntitiesFromRegistry(registry);
   const entityMap = new Map(allEntities.map(e => [e.path, e]));
 
   const affectedEntities = affectedPaths.map(path => {
@@ -68,7 +70,7 @@ export function analyzeImpact(projectDir, entityPath) {
  * @returns {Map<string, string[]>} Map of entityPath -> [dependentPaths]
  */
 export function buildDependencyGraph(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
   const graph = new Map();
 
   if (!existsSync(registryPath)) {
@@ -76,7 +78,7 @@ export function buildDependencyGraph(projectDir) {
   }
 
   const registry = yaml.load(readFileSync(registryPath, 'utf8'));
-  const entities = flattenEntities(registry);
+  const entities = flattenEntitiesFromRegistry(registry);
 
   // Initialize graph with all entities
   entities.forEach(entity => {
@@ -287,29 +289,3 @@ function tokenize(text) {
     .filter(w => w.length > 2 && !stopwords.has(w));
 }
 
-/**
- * Flatten entity registry into array of entities.
- * @private
- * @param {object} registry
- * @returns {object[]}
- */
-function flattenEntities(registry) {
-  const entities = [];
-
-  if (!registry.entities) {
-    return entities;
-  }
-
-  Object.entries(registry.entities).forEach(([type, typeEntities]) => {
-    if (Array.isArray(typeEntities)) {
-      typeEntities.forEach(entity => {
-        entities.push({
-          ...entity,
-          type
-        });
-      });
-    }
-  });
-
-  return entities;
-}

package/src/decision/engine.js

@@ -12,6 +12,8 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
+import { flattenEntitiesFromRegistry } from '../utils/flatten-entities.js';
 
 /**
  * Analyze a request against existing entities and recommend action.
@@ -22,7 +24,7 @@ import yaml from 'js-yaml';
  * @returns {{ recommendation: 'REUSE'|'ADAPT'|'CREATE', score: number, matches: object[], reasoning: string }}
  */
 export function analyzeRequest(projectDir, request) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
 
   if (!existsSync(registryPath)) {
     return {
@@ -34,7 +36,7 @@ export function analyzeRequest(projectDir, request) {
   }
 
   const registry = yaml.load(readFileSync(registryPath, 'utf8'));
-  const entities = flattenEntities(registry);
+  const entities = flattenEntitiesFromRegistry(registry);
 
   // Calculate similarity scores for all entities
   const scoredMatches = entities
@@ -246,29 +248,3 @@ export function getEngineStats(projectDir) {
   return stats;
 }
 
-/**
- * Flatten entity registry into array of entities.
- * @private
- * @param {object} registry
- * @returns {object[]}
- */
-function flattenEntities(registry) {
-  const entities = [];
-
-  if (!registry.entities) {
-    return entities;
-  }
-
-  Object.entries(registry.entities).forEach(([type, typeEntities]) => {
-    if (Array.isArray(typeEntities)) {
-      typeEntities.forEach(entity => {
-        entities.push({
-          ...entity,
-          type
-        });
-      });
-    }
-  });
-
-  return entities;
-}

package/src/decision/registry-healer.js

@@ -8,6 +8,7 @@
 import { readFileSync, writeFileSync, existsSync, statSync, copyFileSync, mkdirSync } from 'fs';
 import { join, isAbsolute } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 import { detectNewEntities, detectRemovedEntities, generateEntityMeta } from './registry-updater.js';
 
 /**
@@ -16,7 +17,7 @@ import { detectNewEntities, detectRemovedEntities, generateEntityMeta } from './
  * @returns {{ registry: object|null, registryPath: string }}
  */
 function loadRegistry(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
   if (!existsSync(registryPath)) {
     return { registry: null, registryPath };
   }
@@ -347,7 +348,7 @@ export function detectCountMismatch(projectDir, preloaded) {
  * @returns {{ applied: number, backup: string }}
  */
 export function applyFixes(projectDir, fixes) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
 
   if (!existsSync(registryPath)) {
     return { applied: 0, backup: null };

package/src/decision/registry-updater.js

@@ -8,17 +8,26 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'fs';
 import { join, basename, relative } from 'path';
 import yaml from 'js-yaml';
+import { resolveFrameworkDir } from '../utils/framework-dir.js';
 
-// Known directories to scan
-const KNOWN_DIRS = [
-  { path: 'chati.dev/agents', type: 'agent' },
-  { path: 'chati.dev/tasks', type: 'task' },
-  { path: 'chati.dev/schemas', type: 'schema' },
-  { path: 'chati.dev/domains', type: 'domain' },
-  { path: 'chati.dev/hooks', type: 'hook' },
-  { path: 'chati.dev/workflows', type: 'workflow' },
-  { path: 'chati.dev/templates', type: 'template' }
-];
+/**
+ * Build KNOWN_DIRS using resolveFrameworkDir so paths are correct
+ * for both chati.dev/ and .chati.dev/ installations.
+ * @param {string} projectDir
+ * @returns {{ path: string, type: string }[]}
+ */
+function buildKnownDirs(projectDir) {
+  const fw = resolveFrameworkDir(projectDir);
+  return [
+    { path: `${fw}/agents`, type: 'agent' },
+    { path: `${fw}/tasks`, type: 'task' },
+    { path: `${fw}/schemas`, type: 'schema' },
+    { path: `${fw}/domains`, type: 'domain' },
+    { path: `${fw}/hooks`, type: 'hook' },
+    { path: `${fw}/workflows`, type: 'workflow' },
+    { path: `${fw}/templates`, type: 'template' },
+  ];
+}
 
 /**
  * Scan project for new/changed files and update registry.
@@ -28,7 +37,7 @@ const KNOWN_DIRS = [
  */
 export function updateRegistry(projectDir, options = {}) {
   const { dryRun = false } = options;
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
 
   let registry = {
     metadata: {
@@ -157,7 +166,7 @@ export function updateRegistry(projectDir, options = {}) {
  * @returns {object[]} New entity candidates
  */
 export function detectNewEntities(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
   const existingPaths = new Set();
 
   if (existsSync(registryPath)) {
@@ -175,7 +184,7 @@ export function detectNewEntities(projectDir) {
 
   const newEntities = [];
 
-  KNOWN_DIRS.forEach(({ path: dirPath, type }) => {
+  buildKnownDirs(projectDir).forEach(({ path: dirPath, type }) => {
     const fullPath = join(projectDir, dirPath);
     if (!existsSync(fullPath)) {
       return;
@@ -204,7 +213,7 @@ export function detectNewEntities(projectDir) {
  * @returns {object[]} Removed entity candidates
  */
 export function detectRemovedEntities(projectDir) {
-  const registryPath = join(projectDir, 'chati.dev', 'entity-registry.yaml');
+  const registryPath = join(projectDir, resolveFrameworkDir(projectDir), 'entity-registry.yaml');
   if (!existsSync(registryPath)) {
     return [];
   }