aibridge-context 1.4.1 → 1.5.2

package/core/stateManager.js

@@ -8,108 +8,54 @@ const CONTEXT_DIR_NAME = '.ai-context';
 const MAX_RECENT_UPDATES = 5;
 const MAX_CHANGELOG_ENTRIES = 50;
 const MAX_KEY_FEATURES = 6;
-const IMPORTANT_DIRECTORIES = ['core/', 'server/', 'bin/'];
+const MAX_IMPLEMENTATION_DETAILS = 8;
+const IMPORTANT_DIRECTORIES = ['core/', 'server/', 'bin/', 'src/', 'routes/', 'controllers/', 'services/'];
 const IMPORTANT_EXTENSIONS = new Set(['.js', '.ts', '.py']);
-const LOW_VALUE_FEATURE_KEYS = new Set([
-  'documentation',
-  'package_configuration',
-  'context_templates',
-  'project_workflow'
+const IGNORED_DIRECTORY_NAMES = new Set([
+  'node_modules',
+  '.git',
+  '.ai-context',
+  'dist',
+  'build',
+  'coverage',
+  '.tmp',
+  'logs'
 ]);
-
-async function safeWriteJSON(filePath, data) {
-  const fs = require("fs");
-  const path = require("path");
-
-  const tmpPath = filePath + ".tmp";
-
-  try {
-    // ensure directory exists
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-
-    // write temp file
-    await fs.promises.writeFile(tmpPath, data, "utf-8");
-
-    // rename only if tmp exists
-    if (fs.existsSync(tmpPath)) {
-      await fs.promises.rename(tmpPath, filePath);
-    } else {
-      await fs.promises.writeFile(filePath, data, "utf-8");
-    }
-  } catch (err) {
-    console.error("[aibridge] Write fallback triggered:", err.message);
-
-    try {
-      await fs.promises.writeFile(filePath, data, "utf-8");
-    } catch (e) {
-      console.error("[aibridge] Failed to write state file:", e.message);
-    }
-  }
-}
-
+const ANALYSIS_ROOT_FILES = [
+  'package.json',
+  'app.js',
+  'app.ts',
+  'index.js',
+  'index.ts',
+  'main.py',
+  'requirements.txt',
+  'tsconfig.json'
+];
+const ANALYSIS_DIRECTORIES = [
+  'routes',
+  'server',
+  'controllers',
+  'services',
+  'middleware',
+  'config',
+  'src',
+  'core',
+  'bin'
+];
 const FEATURE_CATALOG = {
-  cli_workflow: {
-    name: 'CLI workflow for initializing, updating, and linking AI context',
-    subject: 'CLI workflow',
-    projectType: 'CLI tool'
-  },
-  github_sync: {
-    name: 'Public GitHub sync for AI-readable project context',
-    subject: 'GitHub sync system',
-    projectType: 'CLI tool'
-  },
-  project_intelligence: {
-    name: 'Project intelligence engine that turns development activity into AI-readable state',
-    subject: 'project intelligence engine',
-    projectType: 'project intelligence engine'
-  },
-  change_tracking: {
-    name: 'Meaningful change tracking that filters noise from project activity',
-    subject: 'change tracking engine',
-    projectType: 'change tracking engine'
-  },
-  local_context_server: {
-    name: 'Local server for AI-readable project context endpoints',
-    subject: 'AI context delivery service',
-    projectType: 'context delivery service'
-  },
-  context_delivery_system: {
-    name: 'Unified context delivery system connecting project intelligence and serving layers',
-    subject: 'AI context delivery system',
-    projectType: 'AI context system'
-  },
-  cli_orchestration: {
-    name: 'Command workflow that connects project intelligence with developer actions',
-    subject: 'CLI workflow',
-    projectType: 'CLI tool'
-  },
-  project_setup: {
-    name: 'Guided setup flow for safe AI context initialization',
-    subject: 'project setup flow',
-    projectType: 'CLI tool'
-  },
-  documentation: {
-    name: 'Developer guidance for adopting the AI context workflow',
-    subject: 'developer guidance',
-    projectType: 'project'
-  },
-  package_configuration: {
-    name: 'Package configuration for distributing the AI context CLI',
-    subject: 'package configuration',
-    projectType: 'package'
-  },
-  context_templates: {
-    name: 'Generated templates for bootstrapping AI-readable project context',
-    subject: 'generated AI context templates',
-    projectType: 'template set'
-  },
-  project_workflow: {
-    name: 'Core project workflow for maintaining AI-readable project state',
-    subject: 'project workflow',
-    projectType: 'project'
-  }
+  ai_context_generation: 'AI-readable project context generation',
+  cli_automation: 'Command-line workflow for project setup and automation',
+  change_tracking: 'Automatic change tracking with noise filtering',
+  public_sync: 'Optional GitHub sync for publishing project context',
+  local_context_server: 'HTTP endpoints for accessing current project context',
+  rest_api: 'REST-style API surface',
+  auth: 'Authenticated workflows secured with JWT',
+  persistence: 'MongoDB-backed data persistence',
+  realtime: 'Real-time communication channel',
+  external_api: 'External service integration',
+  middleware: 'Middleware-driven request processing',
+  config_management: 'Centralized project configuration management'
 };
-
 const DEFAULT_CONFIG = {
   port: 3333,
   debounceMs: 600,
@@ -123,8 +69,13 @@ const DEFAULT_CONFIG = {
   }
 };
 
+function resolveProjectRoot(projectRoot) {
+  return path.resolve(projectRoot || process.cwd());
+}
+
 function getContextPaths(projectRoot) {
-  const contextDir = path.join(projectRoot, CONTEXT_DIR_NAME);
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const contextDir = path.join(resolvedRoot, CONTEXT_DIR_NAME);
 
   return {
     contextDir,
@@ -158,67 +109,72 @@ function isObject(value) {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
-function detectProjectMetadata(projectRoot) {
-  const packageJsonPath = path.join(projectRoot, 'package.json');
-  const packageManager = detectPackageManager(projectRoot);
-  const techStack = detectTechStack(projectRoot);
-  const metadata = {
-    project: path.basename(projectRoot),
-    version: '0.1.0',
-    techStack: Object.assign({}, techStack, {
-      package_manager: packageManager
-    }),
-    stackLabel: buildStackLabel(techStack),
-    packageManager
-  };
+function normalizeProjectPath(filePath) {
+  return String(filePath || '').split(path.sep).join('/').replace(/^\.\/+/, '');
+}
+
+function isInsideProjectRoot(projectRoot, targetPath) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const resolvedTarget = path.resolve(targetPath);
+  const relativePath = path.relative(resolvedRoot, resolvedTarget);
+
+  return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function getRootPackageJsonPath(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  return path.join(resolvedRoot, 'package.json');
+}
+
+function readRootPackageJson(projectRoot) {
+  const packageJsonPath = getRootPackageJsonPath(projectRoot);
 
   if (!fs.existsSync(packageJsonPath)) {
-    return metadata;
+    return null;
   }
 
   try {
-    const rawPackage = fs.readFileSync(packageJsonPath, 'utf8');
-    const parsedPackage = JSON.parse(rawPackage);
-
-    metadata.project = parsedPackage.name || metadata.project;
-    metadata.version = parsedPackage.version || metadata.version;
+    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
   } catch (error) {
-    metadata.stackLabel = buildStackLabel(metadata.techStack);
+    return null;
   }
-
-  return metadata;
 }
 
-function detectTechStack(projectRoot) {
-  const packageJsonPath = path.join(projectRoot, 'package.json');
-  const pythonMarkers = ['pyproject.toml', 'requirements.txt', 'setup.py'];
-  const hasPackageJson = fs.existsSync(packageJsonPath);
-  const hasPythonMarker = pythonMarkers.some((marker) =>
-    fs.existsSync(path.join(projectRoot, marker))
-  );
-  let dependencies = {};
+function detectProjectMetadata(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const packageJson = readRootPackageJson(resolvedRoot);
+  const techStack = detectTechStack(resolvedRoot, packageJson);
+  const packageManager = detectPackageManager(resolvedRoot);
 
-  if (hasPackageJson) {
-    try {
-      const rawPackage = fs.readFileSync(packageJsonPath, 'utf8');
-      const parsedPackage = JSON.parse(rawPackage);
-      dependencies = Object.assign(
-        {},
-        parsedPackage.dependencies || {},
-        parsedPackage.devDependencies || {}
-      );
-    } catch (error) {
-      dependencies = {};
-    }
-  }
+  return {
+    project: packageJson && packageJson.name ? packageJson.name : path.basename(resolvedRoot),
+    version: packageJson && packageJson.version ? packageJson.version : '0.1.0',
+    techStack: Object.assign({}, techStack, {
+      package_manager: packageManager
+    }),
+    stackLabel: buildStackLabel(techStack),
+    packageManager
+  };
+}
 
+function detectTechStack(projectRoot, packageJson) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const rootPackage = packageJson || readRootPackageJson(resolvedRoot);
+  const dependencies = Object.assign(
+    {},
+    (rootPackage && rootPackage.dependencies) || {},
+    (rootPackage && rootPackage.devDependencies) || {}
+  );
+  const hasPythonMarker = ['pyproject.toml', 'requirements.txt', 'setup.py'].some((marker) =>
+    fs.existsSync(path.join(resolvedRoot, marker))
+  );
   let language = '';
   let runtime = '';
 
-  if (hasPackageJson || hasAnyFileExtension(projectRoot, ['.js', '.ts', '.mjs', '.cjs'])) {
+  if (rootPackage || hasAnyFileExtension(resolvedRoot, ['.js', '.ts', '.mjs', '.cjs'])) {
     language = 'Node.js';
     runtime = 'Node.js';
-  } else if (hasPythonMarker || hasAnyFileExtension(projectRoot, ['.py'])) {
+  } else if (hasPythonMarker || hasAnyFileExtension(resolvedRoot, ['.py'])) {
     language = 'Python';
     runtime = 'Python';
   }
@@ -227,7 +183,7 @@ function detectTechStack(projectRoot) {
     language,
     framework: detectFramework(dependencies),
     runtime,
-    package_manager: detectPackageManager(projectRoot)
+    package_manager: detectPackageManager(resolvedRoot)
   };
 }
 
@@ -244,6 +200,14 @@ function detectFramework(dependencies) {
     return 'Express';
   }
 
+  if (dependencies.fastify) {
+    return 'Fastify';
+  }
+
+  if (dependencies.koa) {
+    return 'Koa';
+  }
+
   return '';
 }
 
@@ -258,11 +222,30 @@ function hasAnyFileExtension(projectRoot, extensions) {
   );
 }
 
-function scanProjectFiles(projectRoot, maxDepth) {
+function detectPackageManager(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+
+  if (fs.existsSync(path.join(resolvedRoot, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+
+  if (fs.existsSync(path.join(resolvedRoot, 'yarn.lock'))) {
+    return 'yarn';
+  }
+
+  return 'npm';
+}
+
+function scanProjectFiles(projectRoot, maxDepth, options) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const settings = Object.assign({ includeDirectories: null }, options);
+  const includeDirectories = settings.includeDirectories
+    ? new Set(settings.includeDirectories.map((entry) => normalizeProjectPath(entry).toLowerCase()))
+    : null;
   const results = [];
 
   function visit(currentDir, depth) {
-    if (depth > maxDepth) {
+    if (depth > maxDepth || !isInsideProjectRoot(resolvedRoot, currentDir)) {
       return;
     }
 
@@ -276,13 +259,22 @@ function scanProjectFiles(projectRoot, maxDepth) {
 
     for (const entry of entries) {
       const fullPath = path.join(currentDir, entry.name);
-      const relativePath = normalizeProjectPath(path.relative(projectRoot, fullPath));
+
+      if (!isInsideProjectRoot(resolvedRoot, fullPath)) {
+        continue;
+      }
+
+      const relativePath = normalizeProjectPath(path.relative(resolvedRoot, fullPath));
 
       if (entry.isDirectory()) {
         if (shouldIgnoreProjectFile(relativePath)) {
           continue;
         }
 
+        if (includeDirectories && depth === 0 && !includeDirectories.has(relativePath.toLowerCase())) {
+          continue;
+        }
+
         visit(fullPath, depth + 1);
         continue;
       }
@@ -293,20 +285,71 @@ function scanProjectFiles(projectRoot, maxDepth) {
     }
   }
 
-  visit(projectRoot, 0);
+  visit(resolvedRoot, 0);
   return results;
 }
 
-function detectPackageManager(projectRoot) {
-  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
-    return 'pnpm';
+function shouldIgnoreProjectFile(filePath) {
+  const normalizedPath = normalizeProjectPath(filePath).toLowerCase();
+
+  if (!normalizedPath) {
+    return false;
   }
 
-  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) {
-    return 'yarn';
+  const segments = normalizedPath.split('/').filter(Boolean);
+  const baseName = segments[segments.length - 1] || '';
+
+  if (segments.some((segment) => IGNORED_DIRECTORY_NAMES.has(segment))) {
+    return true;
   }
 
-  return 'npm';
+  if (baseName.startsWith('.start')) {
+    return true;
+  }
+
+  if (
+    baseName.endsWith('.log') ||
+    baseName.endsWith('.tmp') ||
+    baseName.endsWith('.lock') ||
+    baseName === 'package-lock.json' ||
+    baseName === 'yarn.lock' ||
+    baseName === 'pnpm-lock.yaml' ||
+    /^tmp[._-]/i.test(baseName) ||
+    /^temp[._-]/i.test(baseName) ||
+    /^debug[._-]/i.test(baseName)
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+function scoreEvent(filePath) {
+  const normalizedPath = normalizeProjectPath(filePath);
+  const lowerPath = normalizedPath.toLowerCase();
+  let score = 0;
+
+  if (shouldIgnoreProjectFile(normalizedPath)) {
+    return -5;
+  }
+
+  if (IMPORTANT_DIRECTORIES.some((directory) => lowerPath.startsWith(directory))) {
+    score += 3;
+  }
+
+  if (IMPORTANT_EXTENSIONS.has(path.extname(lowerPath))) {
+    score += 2;
+  }
+
+  if (lowerPath === 'package.json') {
+    score += 2;
+  }
+
+  if (lowerPath === 'readme.md') {
+    score += 1;
+  }
+
+  return score;
 }
 
 async function ensureContextDirectory(projectRoot) {
@@ -330,204 +373,549 @@ async function writeJsonAtomic(filePath, value) {
 }
 
 async function writeTextAtomic(filePath, content) {
-  await safeWriteJSON(filePath, content);
+  const tempFilePath = `${filePath}.tmp`;
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(tempFilePath, content, 'utf8');
+  await fsp.rename(tempFilePath, filePath);
+}
+
+function renderTemplate(template, variables) {
+  return Object.entries(variables).reduce((accumulator, [key, value]) => {
+    const safeValue = value == null ? '' : String(value);
+    return accumulator.split(`{{${key}}}`).join(safeValue);
+  }, template);
+}
+
+function createDefaultChangelog() {
+  return {
+    entries: []
+  };
 }
 
 function createDefaultState(projectRoot) {
   const metadata = detectProjectMetadata(projectRoot);
+  const bootstrap = bootstrapProjectAnalysis(projectRoot);
   const state = {
     project: metadata.project,
     version: metadata.version,
     last_updated: new Date(0).toISOString(),
     ai_summary: '',
-    tech_stack: metadata.techStack,
-    current_stage: 'Early development',
+    tech_stack: bootstrap.techStack,
+    architecture_patterns: bootstrap.architecturePatterns,
+    implementation_details: bootstrap.implementationDetails,
+    current_stage: determineCurrentStage(bootstrap.keyFeatures, [], bootstrap.implementationDetails),
     recent_updates: [],
-    key_features: [],
-    known_issues: deriveKnownIssues(projectRoot, metadata.techStack, []),
+    key_features: bootstrap.keyFeatures,
+    known_issues: deriveKnownIssues(projectRoot, bootstrap),
     next_steps: []
   };
 
-  state.ai_summary = generateAiSummary(state, []);
-  state.next_steps = generateNextSteps(state, []);
+  state.ai_summary = generateAiSummary(state, bootstrap);
+  state.next_steps = generateNextSteps(state, bootstrap, []);
 
   return state;
 }
 
-function createDefaultChangelog() {
-  return {
-    entries: []
-  };
-}
+function mergePreferredArray(preferredValue, fallbackValue) {
+  if (Array.isArray(preferredValue) && preferredValue.length > 0) {
+    return preferredValue;
+  }
 
-function renderTemplate(template, variables) {
-  return Object.entries(variables).reduce((accumulator, [key, value]) => {
-    const safeValue = value == null ? '' : String(value);
-    return accumulator.split(`{{${key}}}`).join(safeValue);
-  }, template);
-}
+  if (Array.isArray(fallbackValue) && fallbackValue.length > 0) {
+    return fallbackValue;
+  }
 
-async function loadRuntimeConfig(projectRoot) {
-  const { configFile } = getContextPaths(projectRoot);
-  const userConfig = await readJsonFile(configFile, {});
-  return deepMerge(DEFAULT_CONFIG, userConfig);
+  return [];
 }
 
-async function updateRuntimeConfig(projectRoot, updates) {
-  const { configFile } = getContextPaths(projectRoot);
-  const currentConfig = await readJsonFile(configFile, {});
-  const mergedCurrentConfig = deepMerge(DEFAULT_CONFIG, currentConfig);
-  const nextConfig = deepMerge(mergedCurrentConfig, updates || {});
+function mergePreferredObject(preferredValue, fallbackValue) {
+  const preferredObject = isObject(preferredValue) ? preferredValue : {};
+  const fallbackObject = isObject(fallbackValue) ? fallbackValue : {};
 
-  await writeJsonAtomic(configFile, nextConfig);
-  return nextConfig;
+  return Object.assign({}, fallbackObject, preferredObject);
 }
 
-async function updateProjectState(projectRoot, changeEvent, options) {
-  const settings = Object.assign(
+function composeStateFromAnalysis(existingState, metadata, bootstrap, overrides) {
+  const baseState = isObject(existingState) ? existingState : {};
+  const nextState = Object.assign(
     {
-      logger: null,
-      syncCallback: null
+      project: metadata.project,
+      version: metadata.version,
+      last_updated: baseState.last_updated || new Date(0).toISOString(),
+      ai_summary: '',
+      tech_stack: mergePreferredObject(bootstrap.techStack, baseState.tech_stack),
+      architecture_patterns: mergePreferredArray(
+        bootstrap.architecturePatterns,
+        baseState.architecture_patterns
+      ),
+      implementation_details: mergePreferredArray(
+        bootstrap.implementationDetails,
+        baseState.implementation_details
+      ),
+      current_stage: '',
+      recent_updates: Array.isArray(baseState.recent_updates) ? baseState.recent_updates : [],
+      key_features: mergePreferredArray(bootstrap.keyFeatures, baseState.key_features),
+      known_issues: [],
+      next_steps: []
     },
-    options
-  );
-  const logger = settings.logger;
-  const contextPaths = getContextPaths(projectRoot);
-  const metadata = detectProjectMetadata(projectRoot);
-  const existingState = await readJsonFile(contextPaths.stateFile, createDefaultState(projectRoot));
-  const existingChangelog = await readJsonFile(
-    contextPaths.changelogFile,
-    createDefaultChangelog()
+    overrides || {}
   );
-  const normalizedEvents = Array.isArray(changeEvent) ? changeEvent : [changeEvent];
-  const validEvents = normalizedEvents.filter(Boolean);
-  const timestamp = determineUpdateTimestamp(validEvents);
-  const meaningfulEvents = collapseEventsByFile(
-    validEvents.filter((event) => isMeaningfulEvent(event))
+
+  return nextState;
+}
+
+function bootstrapProjectAnalysis(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const metadata = detectProjectMetadata(resolvedRoot);
+  const rootPackage = readRootPackageJson(resolvedRoot);
+  const techStack = metadata.techStack;
+  const analysisInputs = collectAnalysisInputs(resolvedRoot);
+  const implementationSignals = detectImplementationSignals(analysisInputs, rootPackage, techStack);
+  const architecturePatterns = buildArchitecturePatterns(
+    implementationSignals,
+    analysisInputs,
+    techStack,
+    rootPackage
   );
-  const groupedUpdates = groupEventsByIntent(meaningfulEvents);
-  const capabilityHistory = buildProjectCapabilityHistory(projectRoot);
-  const previousHistoryEntries = normalizeStoredHistoryEntries(existingChangelog.entries);
-  const historyEntries = dedupeHistoryEntries(
-    groupedUpdates.concat(previousHistoryEntries, capabilityHistory)
-  ).slice(0, MAX_CHANGELOG_ENTRIES);
-  const recentUpdates = historyEntries
-    .filter((entry) => entry.source !== 'project_snapshot')
-    .slice(0, MAX_RECENT_UPDATES)
-    .map(toStateUpdate);
-  const keyFeatures = promoteFeatures(historyEntries);
-  const knownIssues = deriveKnownIssues(projectRoot, metadata.techStack, keyFeatures);
-  const nextState = {
-    project: metadata.project,
-    version: metadata.version,
-    last_updated: timestamp,
-    ai_summary: '',
-    tech_stack: metadata.techStack,
-    current_stage: determineCurrentStage(keyFeatures, historyEntries),
-    recent_updates: recentUpdates,
-    key_features: keyFeatures,
-    known_issues: knownIssues,
-    next_steps: []
+  const implementationDetails = buildImplementationDetails(implementationSignals, techStack);
+  const keyFeatures = buildKeyFeatures(implementationSignals, techStack);
+  const projectType = determineProjectType(implementationSignals, techStack, rootPackage);
+
+  return {
+    projectType,
+    techStack,
+    architecturePatterns,
+    implementationDetails,
+    keyFeatures,
+    signals: implementationSignals
   };
+}
 
-  nextState.ai_summary = generateAiSummary(nextState, historyEntries);
-  nextState.next_steps = generateNextSteps(nextState, historyEntries);
+function collectAnalysisInputs(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const selectedFiles = new Set();
 
-  await writeJsonAtomic(contextPaths.stateFile, nextState);
-  await writeJsonAtomic(contextPaths.changelogFile, { entries: historyEntries });
+  for (const relativeFile of ANALYSIS_ROOT_FILES) {
+    const absoluteFile = path.join(resolvedRoot, relativeFile);
 
-  if (logger) {
-    logger.debug(`Updated AI context with ${groupedUpdates.length} grouped project intent(s).`);
+    if (fs.existsSync(absoluteFile) && isInsideProjectRoot(resolvedRoot, absoluteFile)) {
+      selectedFiles.add(relativeFile);
+    }
   }
 
-  if (typeof settings.syncCallback === 'function') {
-    await settings.syncCallback();
+  const discoveredFiles = scanProjectFiles(resolvedRoot, 4, {
+    includeDirectories: ANALYSIS_DIRECTORIES
+  });
+
+  for (const relativeFile of discoveredFiles) {
+    selectedFiles.add(relativeFile);
   }
 
-  return nextState;
+  return Array.from(selectedFiles)
+    .sort()
+    .map((relativeFile) => {
+      const absoluteFile = path.join(resolvedRoot, relativeFile);
+
+      try {
+        const content = fs.readFileSync(absoluteFile, 'utf8');
+        return {
+          path: relativeFile,
+          content: content.slice(0, 50000)
+        };
+      } catch (error) {
+        return null;
+      }
+    })
+    .filter(Boolean);
 }
 
-function determineUpdateTimestamp(events) {
-  if (!Array.isArray(events) || events.length === 0) {
-    return new Date().toISOString();
-  }
+function detectImplementationSignals(analysisInputs, rootPackage, techStack) {
+  const dependencyNames = new Set([
+    ...Object.keys((rootPackage && rootPackage.dependencies) || {}),
+    ...Object.keys((rootPackage && rootPackage.devDependencies) || {})
+  ]);
+  const runtimeInputs = analysisInputs.filter((input) => isRuntimeImplementationFile(input.path));
+  const automationInputs = analysisInputs.filter((input) => isAutomationImplementationFile(input.path));
+  const runtimeContent = runtimeInputs.map((input) => input.content).join('\n');
+  const automationContent = automationInputs.map((input) => input.content).join('\n');
+  const allContent = analysisInputs.map((input) => input.content).join('\n');
+  const hasDirectory = (directoryName) =>
+    analysisInputs.some((input) => normalizeProjectPath(input.path).startsWith(`${directoryName}/`));
+  const hasRuntimePattern = (pattern) => pattern.test(runtimeContent);
+  const hasAutomationPattern = (pattern) => pattern.test(automationContent);
+  const hasAnyPattern = (pattern) => pattern.test(allContent);
 
-  const latestEvent = events[events.length - 1];
-  return latestEvent.timestamp || new Date().toISOString();
+  return {
+    hasPackageJson: Boolean(rootPackage),
+    hasCliEntry:
+      Boolean(rootPackage && rootPackage.bin && Object.keys(rootPackage.bin).length > 0) ||
+      hasAutomationPattern(/^#!\/usr\/bin\/env node/m) ||
+      hasAutomationPattern(/\bprocess\.argv\b/),
+    hasExpress:
+      dependencyNames.has('express') ||
+      hasRuntimePattern(/\brequire\(['"]express['"]\)/) ||
+      hasRuntimePattern(/\bfrom ['"]express['"]/) ||
+      hasRuntimePattern(/\bexpress\(\)/),
+    hasNext: dependencyNames.has('next'),
+    hasReact: dependencyNames.has('react'),
+    hasFastify: dependencyNames.has('fastify'),
+    hasKoa: dependencyNames.has('koa'),
+    hasRestRoutes: hasRuntimePattern(/\b(router|app)\.(get|post|put|patch|delete)\s*\(/),
+    hasMiddleware: hasRuntimePattern(/\bapp\.use\s*\(/) || hasDirectory('middleware'),
+    hasJwt:
+      dependencyNames.has('jsonwebtoken') ||
+      hasRuntimePattern(/\bjwt\.(sign|verify)\s*\(/) ||
+      hasRuntimePattern(/\brequire\(['"]jsonwebtoken['"]\)/),
+    hasMongoose:
+      dependencyNames.has('mongoose') ||
+      hasRuntimePattern(/\bmongoose\.connect\s*\(/) ||
+      hasRuntimePattern(/\brequire\(['"]mongoose['"]\)/),
+    hasSocketIO:
+      dependencyNames.has('socket.io') ||
+      hasRuntimePattern(/\bsocket\.io\b/) ||
+      hasRuntimePattern(/\brequire\(['"]socket\.io['"]\)/),
+    hasAxiosOrFetch:
+      dependencyNames.has('axios') ||
+      hasRuntimePattern(/\baxios\./) ||
+      hasRuntimePattern(/\bfetch\s*\(/),
+    hasWatcher:
+      dependencyNames.has('chokidar') ||
+      hasAutomationPattern(/\bchokidar\.watch\s*\(/) ||
+      hasAutomationPattern(/\bfs\.watch\s*\(/),
+    hasGitAutomation:
+      hasAutomationPattern(/\bgit\s+(add|commit|push)\b/) ||
+      hasAutomationPattern(/\b(syncContextToGit|linkGithubRepository)\b/),
+    hasAiContextArtifacts:
+      hasAutomationPattern(/\bstate\.json\b/) ||
+      hasAutomationPattern(/\bbrain\.txt\b/) ||
+      hasAutomationPattern(/\bcontext\.md\b/) ||
+      hasAutomationPattern(/\bchangelog\.json\b/),
+    hasControllers: hasDirectory('controllers'),
+    hasServices: hasDirectory('services'),
+    hasRoutes: hasDirectory('routes'),
+    hasServerDirectory: hasDirectory('server'),
+    hasConfigDirectory: hasDirectory('config'),
+    hasTypeScriptConfig: analysisInputs.some((input) => input.path === 'tsconfig.json'),
+    hasPythonRequirements: analysisInputs.some((input) => input.path === 'requirements.txt'),
+    hasNodeRuntime: techStack.language === 'Node.js',
+    hasPythonRuntime: techStack.language === 'Python',
+    hasApplicationEntries: runtimeInputs.length > 0,
+    hasAnyContent: hasAnyPattern(/\S/)
+  };
 }
 
-function normalizeProjectPath(filePath) {
-  return String(filePath || '').split(path.sep).join('/').replace(/^\.\/+/, '');
+function isRuntimeImplementationFile(relativePath) {
+  const normalizedPath = normalizeProjectPath(relativePath).toLowerCase();
+
+  return (
+    normalizedPath.startsWith('routes/') ||
+    normalizedPath.startsWith('server/') ||
+    normalizedPath.startsWith('controllers/') ||
+    normalizedPath.startsWith('services/') ||
+    normalizedPath.startsWith('middleware/') ||
+    normalizedPath.startsWith('config/') ||
+    normalizedPath.startsWith('src/') ||
+    normalizedPath === 'app.js' ||
+    normalizedPath === 'app.ts' ||
+    normalizedPath === 'index.js' ||
+    normalizedPath === 'index.ts' ||
+    normalizedPath === 'main.py'
+  );
 }
 
-function shouldIgnoreProjectFile(filePath) {
-  const normalizedPath = normalizeProjectPath(filePath).toLowerCase();
+function isAutomationImplementationFile(relativePath) {
+  const normalizedPath = normalizeProjectPath(relativePath).toLowerCase();
 
-  if (!normalizedPath) {
-    return false;
+  return (
+    normalizedPath.startsWith('core/') ||
+    normalizedPath.startsWith('bin/') ||
+    normalizedPath === 'package.json' ||
+    normalizedPath === 'index.js' ||
+    normalizedPath === 'index.ts'
+  );
+}
+
+function buildArchitecturePatterns(signals, analysisInputs, techStack, rootPackage) {
+  const patterns = [];
+
+  if (signals.hasCliEntry) {
+    patterns.push('Command-line automation workflow');
   }
 
-  const segments = normalizedPath.split('/');
-  const baseName = segments[segments.length - 1];
+  if (signals.hasWatcher) {
+    patterns.push('Event-driven file watching pipeline');
+  }
 
-  if (
-    segments.includes('node_modules') ||
-    segments.includes('.git') ||
-    segments.includes('.ai-context') ||
-    segments.includes('dist') ||
-    segments.includes('build')
-  ) {
-    return true;
+  if (signals.hasExpress && signals.hasRestRoutes) {
+    patterns.push('REST API architecture');
   }
 
-  if (baseName.startsWith('.start')) {
-    return true;
+  if (signals.hasMiddleware) {
+    patterns.push('Middleware-driven request pipeline');
+  }
+
+  if (signals.hasControllers && signals.hasServices) {
+    patterns.push('Layered controller-service architecture');
+  }
+
+  if (signals.hasServerDirectory && signals.hasRoutes) {
+    patterns.push('Separated server bootstrap and route handling');
+  }
+
+  if (signals.hasConfigDirectory) {
+    patterns.push('Centralized configuration layer');
+  }
+
+  if (signals.hasSocketIO) {
+    patterns.push('Real-time event architecture');
+  }
+
+  if (signals.hasNext) {
+    patterns.push('Framework-driven web application structure');
+  } else if (signals.hasReact) {
+    patterns.push('Component-based frontend architecture');
   }
 
   if (
-    baseName.endsWith('.log') ||
-    baseName.endsWith('.tmp') ||
-    baseName.endsWith('.lock') ||
-    baseName === 'package-lock.json' ||
-    baseName === 'yarn.lock' ||
-    baseName === 'pnpm-lock.yaml' ||
-    /^tmp[._-]/i.test(baseName) ||
-    /^temp[._-]/i.test(baseName) ||
-    /^debug[._-]/i.test(baseName)
+    signals.hasAiContextArtifacts &&
+    signals.hasExpress &&
+    analysisInputs.some((input) => /\bstate\.json\b|\bbrain\.txt\b|\bcontext\.md\b/.test(input.content))
   ) {
-    return true;
+    patterns.push('Structured AI context delivery workflow');
   }
 
-  return false;
+  if (rootPackage && Array.isArray(rootPackage.keywords) && rootPackage.keywords.includes('cli')) {
+    patterns.push('Package-distributed CLI architecture');
+  }
+
+  return uniqueNonEmpty(patterns).slice(0, 6);
 }
 
-function scoreEvent(filePath) {
-  const normalizedPath = normalizeProjectPath(filePath);
-  const lowerPath = normalizedPath.toLowerCase();
-  const baseName = path.basename(normalizedPath).toLowerCase();
-  let score = 0;
+function buildImplementationDetails(signals, techStack) {
+  const details = [];
 
-  if (shouldIgnoreProjectFile(normalizedPath)) {
-    return -5;
+  if (signals.hasJwt) {
+    details.push('JWT-based authentication system');
   }
 
-  if (IMPORTANT_DIRECTORIES.some((directory) => lowerPath.startsWith(directory))) {
-    score += 3;
-  }
+  if (signals.hasMongoose) {
+    details.push('MongoDB integration through Mongoose ORM');
+  }
+
+  if (signals.hasExpress && signals.hasRestRoutes) {
+    details.push('REST API architecture using Express routing');
+  }
+
+  if (signals.hasMiddleware) {
+    details.push('Express middleware pipeline for request handling');
+  }
+
+  if (signals.hasSocketIO) {
+    details.push('Socket.IO-based real-time communication');
+  }
+
+  if (signals.hasAxiosOrFetch) {
+    details.push('External API integration for outbound service calls');
+  }
+
+  if (signals.hasWatcher) {
+    details.push('File system monitoring for automatic project state updates');
+  }
+
+  if (signals.hasAiContextArtifacts) {
+    details.push('Structured AI context generation across JSON, Markdown, and instruction files');
+  }
+
+  if (signals.hasGitAutomation) {
+    details.push('Git-backed synchronization workflow for publishing project state');
+  }
+
+  if (signals.hasCliEntry && techStack.language === 'Node.js') {
+    details.push('Node.js CLI entrypoint for developer-facing automation');
+  }
+
+  return uniqueNonEmpty(details).slice(0, MAX_IMPLEMENTATION_DETAILS);
+}
+
+function buildKeyFeatures(signals, techStack) {
+  const features = [];
+
+  if (signals.hasAiContextArtifacts) {
+    features.push(FEATURE_CATALOG.ai_context_generation);
+  }
+
+  if (signals.hasCliEntry) {
+    features.push(FEATURE_CATALOG.cli_automation);
+  }
+
+  if (signals.hasWatcher) {
+    features.push(FEATURE_CATALOG.change_tracking);
+  }
+
+  if (signals.hasGitAutomation) {
+    features.push(FEATURE_CATALOG.public_sync);
+  }
+
+  if (signals.hasExpress && signals.hasAiContextArtifacts) {
+    features.push(FEATURE_CATALOG.local_context_server);
+  } else if (signals.hasExpress && signals.hasRestRoutes) {
+    features.push(FEATURE_CATALOG.rest_api);
+  }
+
+  if (signals.hasJwt) {
+    features.push(FEATURE_CATALOG.auth);
+  }
+
+  if (signals.hasMongoose) {
+    features.push(FEATURE_CATALOG.persistence);
+  }
+
+  if (signals.hasSocketIO) {
+    features.push(FEATURE_CATALOG.realtime);
+  }
+
+  if (signals.hasAxiosOrFetch) {
+    features.push(FEATURE_CATALOG.external_api);
+  }
+
+  if (signals.hasMiddleware) {
+    features.push(FEATURE_CATALOG.middleware);
+  }
+
+  if (signals.hasConfigDirectory) {
+    features.push(FEATURE_CATALOG.config_management);
+  }
+
+  if (features.length === 0 && techStack.language) {
+    features.push(`${techStack.language} project structure with detectable application entry points`);
+  }
+
+  return uniqueNonEmpty(features).slice(0, MAX_KEY_FEATURES);
+}
+
+function determineProjectType(signals, techStack, rootPackage) {
+  if (signals.hasNext) {
+    return 'Next.js application';
+  }
+
+  if (signals.hasCliEntry && signals.hasAiContextArtifacts) {
+    return 'CLI tool';
+  }
+
+  if (signals.hasExpress && signals.hasRestRoutes) {
+    return 'backend API platform';
+  }
+
+  if (signals.hasReact) {
+    return 'frontend application';
+  }
+
+  if (signals.hasPythonRuntime) {
+    return 'Python application';
+  }
+
+  if (rootPackage && rootPackage.bin) {
+    return 'CLI tool';
+  }
+
+  if (techStack.language === 'Node.js') {
+    return 'Node.js application';
+  }
+
+  return 'software project';
+}
+
+async function loadRuntimeConfig(projectRoot) {
+  const { configFile } = getContextPaths(projectRoot);
+  const userConfig = await readJsonFile(configFile, {});
+  return deepMerge(DEFAULT_CONFIG, userConfig);
+}
+
+async function updateRuntimeConfig(projectRoot, updates) {
+  const { configFile } = getContextPaths(projectRoot);
+  const currentConfig = await readJsonFile(configFile, {});
+  const mergedCurrentConfig = deepMerge(DEFAULT_CONFIG, currentConfig);
+  const nextConfig = deepMerge(mergedCurrentConfig, updates || {});
+
+  await writeJsonAtomic(configFile, nextConfig);
+  return nextConfig;
+}
+
+async function updateProjectState(projectRoot, changeEvent, options) {
+  const settings = Object.assign(
+    {
+      logger: null,
+      syncCallback: null
+    },
+    options
+  );
+  const logger = settings.logger;
+  const resolvedRoot = resolveProjectRoot(projectRoot);
+  const contextPaths = getContextPaths(resolvedRoot);
+  const metadata = detectProjectMetadata(resolvedRoot);
+  const bootstrap = bootstrapProjectAnalysis(resolvedRoot);
+  const existingState = await readJsonFile(contextPaths.stateFile, createDefaultState(resolvedRoot));
+  const existingChangelog = await readJsonFile(
+    contextPaths.changelogFile,
+    createDefaultChangelog()
+  );
+  const normalizedEvents = Array.isArray(changeEvent) ? changeEvent : [changeEvent];
+  const validEvents = normalizedEvents.filter(Boolean);
+  const timestamp = determineUpdateTimestamp(validEvents);
+  const meaningfulEvents = collapseEventsByFile(validEvents.filter((event) => isMeaningfulEvent(event)));
+  const groupedUpdates = groupEventsByIntent(meaningfulEvents, bootstrap);
+  const previousHistoryEntries = normalizeStoredHistoryEntries(existingChangelog.entries);
+  const historyEntries = dedupeHistoryEntries(groupedUpdates.concat(previousHistoryEntries))
+    .slice(0, MAX_CHANGELOG_ENTRIES);
+  const promotedFeatures = promoteFeatures(historyEntries);
+  const keyFeatures = mergeKeyFeatures(bootstrap.keyFeatures, promotedFeatures);
+  const recentUpdates = groupedUpdates.length > 0
+    ? dedupeRecentUpdates(groupedUpdates.map(toStateUpdate).concat(normalizeStoredUpdates(existingState.recent_updates)))
+        .slice(0, MAX_RECENT_UPDATES)
+    : normalizeStoredUpdates(existingState.recent_updates).slice(0, MAX_RECENT_UPDATES);
+  const mergedArchitecturePatterns = mergePreferredArray(
+    bootstrap.architecturePatterns,
+    existingState.architecture_patterns
+  );
+  const mergedImplementationDetails = mergePreferredArray(
+    bootstrap.implementationDetails,
+    existingState.implementation_details
+  );
+  const nextState = composeStateFromAnalysis(existingState, metadata, bootstrap, {
+    last_updated: timestamp,
+    tech_stack: mergePreferredObject(bootstrap.techStack, existingState.tech_stack),
+    architecture_patterns: mergedArchitecturePatterns,
+    implementation_details: mergedImplementationDetails,
+    current_stage: determineCurrentStage(
+      keyFeatures,
+      historyEntries,
+      mergedImplementationDetails
+    ),
+    recent_updates: recentUpdates,
+    key_features: keyFeatures,
+    known_issues: deriveKnownIssues(resolvedRoot, Object.assign({}, bootstrap, {
+      architecturePatterns: mergedArchitecturePatterns,
+      implementationDetails: mergedImplementationDetails,
+      keyFeatures
+    })),
+    next_steps: []
+  });
+
+  nextState.ai_summary = generateAiSummary(nextState, bootstrap);
+  nextState.next_steps = generateNextSteps(nextState, bootstrap, historyEntries);
 
-  if (IMPORTANT_EXTENSIONS.has(path.extname(baseName))) {
-    score += 2;
-  }
+  await writeJsonAtomic(contextPaths.stateFile, nextState);
+  await writeJsonAtomic(contextPaths.changelogFile, { entries: historyEntries });
 
-  if (lowerPath === 'package.json') {
-    score += 2;
+  if (logger) {
+    logger.debug(`Updated AI context with ${groupedUpdates.length} grouped project intent(s).`);
   }
 
-  if (lowerPath === 'readme.md') {
-    score += 1;
+  if (typeof settings.syncCallback === 'function') {
+    await settings.syncCallback();
   }
 
-  return score;
+  return nextState;
 }
 
 function isMeaningfulEvent(event) {
@@ -554,365 +942,225 @@ function collapseEventsByFile(events) {
   return Array.from(collapsedEvents.values());
 }
 
+function determineUpdateTimestamp(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return new Date().toISOString();
+  }
+
+  const latestEvent = events[events.length - 1];
+  return latestEvent.timestamp || new Date().toISOString();
+}
+
 function classifyChangeArea(filePath) {
-  const lowerPath = filePath.toLowerCase();
+  const lowerPath = normalizeProjectPath(filePath).toLowerCase();
 
   if (lowerPath === 'package.json') {
-    return 'dependencies';
+    return 'configuration';
   }
 
   if (lowerPath === 'readme.md') {
     return 'documentation';
   }
 
-  if (lowerPath.startsWith('core/')) {
-    return 'logic';
+  if (lowerPath.startsWith('bin/')) {
+    return 'cli';
   }
 
-  if (lowerPath.startsWith('server/')) {
+  if (lowerPath.startsWith('server/') || lowerPath.startsWith('routes/')) {
     return 'backend';
   }
 
-  if (lowerPath.startsWith('bin/')) {
-    return 'cli';
+  if (
+    lowerPath.startsWith('controllers/') ||
+    lowerPath.startsWith('services/') ||
+    lowerPath.startsWith('middleware/') ||
+    lowerPath.startsWith('config/')
+  ) {
+    return 'application';
   }
 
-  if (lowerPath.startsWith('templates/')) {
-    return 'templates';
+  if (lowerPath.startsWith('core/') || lowerPath.startsWith('src/')) {
+    return 'logic';
   }
 
   return 'project';
 }
 
-function describeRootDirectory(filePath) {
-  const normalizedPath = normalizeProjectPath(filePath);
-  const segments = normalizedPath.split('/');
-
-  if (segments.length === 1) {
-    return segments[0] || 'project';
-  }
-
-  return segments[0] || 'project';
-}
-
-function detectIntentTheme(filePath, area) {
-  const lowerPath = filePath.toLowerCase();
+function detectEventFeatureKey(filePath, bootstrap) {
+  const lowerPath = normalizeProjectPath(filePath).toLowerCase();
+  const signals = bootstrap.signals;
 
   if (lowerPath === 'package.json') {
-    return 'package_configuration';
-  }
+    if (signals.hasGitAutomation) {
+      return 'public_sync';
+    }
 
-  if (lowerPath === 'readme.md') {
-    return 'documentation';
+    if (signals.hasCliEntry) {
+      return 'cli_automation';
+    }
+
+    return 'config_management';
   }
 
   if (lowerPath.startsWith('bin/')) {
-    return 'cli_workflow';
+    return 'cli_automation';
   }
 
-  if (lowerPath.startsWith('server/')) {
-    return 'local_context_server';
-  }
+  if (lowerPath.startsWith('server/') || lowerPath.startsWith('routes/')) {
+    if (signals.hasAiContextArtifacts) {
+      return 'local_context_server';
+    }
 
-  if (lowerPath.startsWith('templates/')) {
-    return 'context_templates';
+    return 'rest_api';
   }
 
   if (lowerPath.includes('gitsync') || lowerPath.includes('sync')) {
-    return 'github_sync';
+    return 'public_sync';
   }
 
-  if (lowerPath.includes('watcher') || lowerPath.includes('watch')) {
+  if (lowerPath.includes('watch')) {
     return 'change_tracking';
   }
 
   if (lowerPath.includes('state') || lowerPath.includes('context')) {
-    return 'project_intelligence';
+    return 'ai_context_generation';
   }
 
-  if (lowerPath.includes('init')) {
-    return 'project_setup';
+  if (lowerPath.includes('auth') || lowerPath.includes('jwt')) {
+    return 'auth';
   }
 
-  if (area === 'logic') {
-    return 'project_intelligence';
+  if (lowerPath.includes('service') || lowerPath.includes('controller')) {
+    return signals.hasAxiosOrFetch ? 'external_api' : 'rest_api';
   }
 
-  return 'project_workflow';
-}
-
-function createEventDescriptor(event) {
-  const normalizedPath = normalizeProjectPath(event.file);
-
-  return {
-    timestamp: event.timestamp || new Date().toISOString(),
-    action: event.action || 'change',
-    file: normalizedPath,
-    area: classifyChangeArea(normalizedPath),
-    rootDirectory: describeRootDirectory(normalizedPath),
-    theme: detectIntentTheme(normalizedPath, classifyChangeArea(normalizedPath))
-  };
+  return 'ai_context_generation';
 }
 
-function groupEventsByIntent(events) {
+function groupEventsByIntent(events, bootstrap) {
   if (!Array.isArray(events) || events.length === 0) {
     return [];
   }
 
-  const groupedByArea = new Map();
+  const buckets = new Map();
 
   for (const event of events) {
-    const descriptor = createEventDescriptor(event);
-    const groupKey = `${descriptor.area}:${descriptor.rootDirectory}`;
-
-    if (!groupedByArea.has(groupKey)) {
-      groupedByArea.set(groupKey, {
-        area: descriptor.area,
-        rootDirectory: descriptor.rootDirectory,
-        events: []
-      });
+    const area = classifyChangeArea(event.file);
+    const featureKey = detectEventFeatureKey(event.file, bootstrap);
+    const key = `${area}:${featureKey}`;
+
+    if (!buckets.has(key)) {
+      buckets.set(key, []);
     }
 
-    groupedByArea.get(groupKey).events.push(descriptor);
+    buckets.get(key).push(
+      Object.assign({}, event, {
+        area,
+        featureKey
+      })
+    );
   }
 
-  const mergedGroups = mergeCrossAreaIntentGroups(Array.from(groupedByArea.values()));
-
-  return mergedGroups
+  return Array.from(buckets.values())
     .map((group) => interpretIntentGroup(group))
     .filter(Boolean)
     .sort((left, right) => new Date(right.timestamp) - new Date(left.timestamp));
 }
 
-function buildProjectCapabilityHistory(projectRoot) {
-  const snapshotTimestamp = new Date(0).toISOString();
-  const projectFiles = scanProjectFiles(projectRoot, 2).filter((filePath) => scoreEvent(filePath) >= 2);
-
-  if (projectFiles.length === 0) {
-    return [];
-  }
-
-  const capabilityBuckets = new Map();
-
-  for (const filePath of projectFiles) {
-    const area = classifyChangeArea(filePath);
-    const featureKey = detectIntentTheme(filePath, area);
-
-    if (!capabilityBuckets.has(featureKey)) {
-      capabilityBuckets.set(featureKey, []);
-    }
-
-    capabilityBuckets.get(featureKey).push(filePath);
-  }
-
-  return Array.from(capabilityBuckets.entries())
-    .map(([featureKey, files]) => createCapabilitySnapshotEntry(featureKey, files.length, snapshotTimestamp))
-    .filter(Boolean);
-}
-
-function mergeCrossAreaIntentGroups(groups) {
-  if (groups.length < 2) {
-    return groups;
-  }
-
-  const logicGroup = groups.find((group) => group.area === 'logic');
-  const backendGroup = groups.find((group) => group.area === 'backend');
-  const cliGroup = groups.find((group) => group.area === 'cli');
-
-  if (logicGroup && backendGroup && groups.length <= 3) {
-    return mergeSelectedGroups(groups, [logicGroup, backendGroup], 'system');
-  }
-
-  if (logicGroup && cliGroup && groups.length <= 3) {
-    return mergeSelectedGroups(groups, [logicGroup, cliGroup], 'cli_system');
-  }
-
-  return groups;
-}
-
-function mergeSelectedGroups(groups, groupsToMerge, mergedArea) {
-  const mergeSet = new Set(groupsToMerge);
-  const remainingGroups = groups.filter((group) => !mergeSet.has(group));
-  const mergedGroup = {
-    area: mergedArea,
-    rootDirectory: mergedArea,
-    events: groupsToMerge.flatMap((group) => group.events)
-  };
-
-  remainingGroups.push(mergedGroup);
-  return remainingGroups;
-}
-
 function interpretIntentGroup(group) {
-  if (!group || !Array.isArray(group.events) || group.events.length === 0) {
-    return null;
-  }
-
-  const latestTimestamp = group.events.reduce((latest, event) => {
+  const latestTimestamp = group.reduce((latest, event) => {
     return new Date(event.timestamp) > new Date(latest) ? event.timestamp : latest;
-  }, group.events[0].timestamp);
-  const featureKey = determineFeatureKey(group);
-  const featureMeta = getFeatureMeta(featureKey);
+  }, group[0].timestamp || new Date().toISOString());
+  const featureKey = group[0].featureKey;
+  const area = group[0].area;
   const type = determineGroupedUpdateType(group);
-  const subject = describeIntentSubject(group, featureMeta.subject);
+  const subject = describeIntentSubject(featureKey);
 
   return {
     timestamp: latestTimestamp,
-    scope: describeIntentScope(group),
+    scope: area,
     title: buildIntentTitle(type, subject),
     type,
-    impact: describeIntentImpact(type, featureKey, subject),
+    impact: describeIntentImpact(type, featureKey),
     feature_key: featureKey,
-    feature_name: featureMeta.name,
-    source: 'event'
-  };
-}
-
-function determineFeatureKey(group) {
-  const areas = new Set(group.events.map((event) => event.area));
-
-  if (group.area === 'system' || (areas.has('logic') && areas.has('backend'))) {
-    return 'context_delivery_system';
-  }
-
-  if (group.area === 'cli_system' || (areas.has('logic') && areas.has('cli'))) {
-    return 'cli_orchestration';
-  }
-
-  const themeCounts = new Map();
-
-  for (const event of group.events) {
-    themeCounts.set(event.theme, (themeCounts.get(event.theme) || 0) + 1);
-  }
-
-  return Array.from(themeCounts.entries()).sort((left, right) => {
-    if (right[1] !== left[1]) {
-      return right[1] - left[1];
-    }
-
-    return getFeaturePriority(right[0]) - getFeaturePriority(left[0]);
-  })[0][0];
-}
-
-function getFeatureMeta(featureKey) {
-  return FEATURE_CATALOG[featureKey] || FEATURE_CATALOG.project_workflow;
-}
-
-function getFeaturePriority(featureKey) {
-  const priorities = {
-    project_intelligence: 7,
-    github_sync: 6,
-    local_context_server: 5,
-    change_tracking: 4,
-    cli_workflow: 3,
-    project_setup: 2,
-    project_workflow: 1
+    feature_name: FEATURE_CATALOG[featureKey] || subject
   };
-
-  return priorities[featureKey] || 0;
 }
 
 function determineGroupedUpdateType(group) {
-  const actions = new Set(group.events.map((event) => event.action));
-  const fileCount = group.events.length;
+  const hasAdd = group.some((event) => event.action === 'add');
+  const hasDelete = group.some((event) => event.action === 'delete');
 
-  if (actions.has('add')) {
+  if (hasAdd) {
     return 'feature';
   }
 
-  if (hasFixSignals(group.events)) {
+  if (hasDelete) {
     return 'fix';
   }
 
-  if (fileCount > 2 || group.area === 'system' || group.area === 'cli_system') {
+  if (group.length > 2) {
     return 'refactor';
   }
 
   return 'improvement';
 }
 
-function hasFixSignals(events) {
-  return events.some((event) =>
-    /(fix|bug|error|guard|validate|sanitize|safe|stabilize)/i.test(event.file)
-  );
-}
-
-function describeIntentSubject(group, fallbackSubject) {
-  const areas = new Set(group.events.map((event) => event.area));
-
-  if (group.area === 'system' || (areas.has('logic') && areas.has('backend'))) {
-    return 'AI context delivery system';
-  }
-
-  if (group.area === 'cli_system' || (areas.has('logic') && areas.has('cli'))) {
-    return 'CLI workflow';
-  }
-
-  if (group.area === 'backend' && group.events.length > 1) {
-    return 'AI context delivery service';
-  }
-
-  return fallbackSubject || 'project workflow';
-}
-
-function describeIntentScope(group) {
-  if (group.area === 'system') {
-    return 'system';
-  }
-
-  if (group.area === 'cli_system') {
-    return 'CLI';
-  }
+function describeIntentSubject(featureKey) {
+  const subjectMap = {
+    ai_context_generation: 'AI context generation workflow',
+    cli_automation: 'CLI automation workflow',
+    change_tracking: 'change tracking workflow',
+    public_sync: 'GitHub sync workflow',
+    local_context_server: 'context delivery service',
+    rest_api: 'API architecture',
+    auth: 'authentication workflow',
+    persistence: 'data persistence layer',
+    realtime: 'real-time communication layer',
+    external_api: 'external integration workflow',
+    middleware: 'request processing workflow',
+    config_management: 'project configuration workflow'
+  };
 
-  return group.area;
+  return subjectMap[featureKey] || 'project workflow';
 }
 
 function buildIntentTitle(type, subject) {
   const verbs = {
     feature: 'Expanded',
     improvement: 'Improved',
-    refactor: 'Refactored',
+    refactor: 'Refined',
     fix: 'Stabilized'
   };
 
   return `${verbs[type] || 'Improved'} ${subject}`;
 }
 
-function describeIntentImpact(type, featureKey, subject) {
-  const impactByFeature = {
-    cli_workflow: 'Improves how developers initialize and manage AI context from the command line.',
-    github_sync: 'Improves reliability of publishing AI-readable project context to GitHub.',
-    project_intelligence: 'Improves how project progress is summarized for AI systems.',
-    change_tracking: 'Improves how meaningful project evolution is detected without noise.',
-    local_context_server: 'Improves how AI tools consume project context through local endpoints.',
-    context_delivery_system: 'Improves reliability and structure of the end-to-end AI context delivery system.',
-    cli_orchestration: 'Improves how CLI actions drive the project intelligence workflow.',
-    project_setup: 'Improves first-run setup and configuration clarity for teams adopting AI context.',
-    documentation: 'Improves onboarding and usage clarity for developers and AI collaborators.',
-    package_configuration: 'Improves package installation and distribution behavior.',
-    context_templates: 'Improves the default AI context generated for new projects.',
-    project_workflow: 'Improves the overall project workflow for maintaining AI-readable context.'
+function describeIntentImpact(type, featureKey) {
+  const impactMap = {
+    ai_context_generation: 'Improves the quality of generated AI-readable project context.',
+    cli_automation: 'Improves how developers control the project workflow from the command line.',
+    change_tracking: 'Improves how meaningful project changes are detected without noise.',
+    public_sync: 'Improves how project state is published for external AI consumption.',
+    local_context_server: 'Improves how current project context is delivered over HTTP endpoints.',
+    rest_api: 'Improves the structure and clarity of the project API surface.',
+    auth: 'Improves authentication reliability and access control.',
+    persistence: 'Improves how project data is persisted and retrieved.',
+    realtime: 'Improves real-time communication behavior.',
+    external_api: 'Improves outbound integration reliability.',
+    middleware: 'Improves request handling and middleware orchestration.',
+    config_management: 'Improves project configuration and packaging reliability.'
   };
 
-  if (type === 'feature') {
-    return impactByFeature[featureKey]
-      .replace(/^Improves /, 'Adds ')
-      .replace(/^Improves how /, 'Adds ')
-      .replace(/^Improves reliability of /, 'Adds ')
-      .replace(/^Improves first-run setup and configuration clarity for teams adopting /, 'Adds ')
-      .replace(/^Improves the default AI context generated for /, 'Adds ')
-      .replace(/^Improves the overall project workflow for maintaining /, 'Adds ');
-  }
-
   if (type === 'fix') {
-    return `Resolves reliability issues in the ${subject.toLowerCase()}.`;
+    return impactMap[featureKey].replace(/^Improves /, 'Resolves issues in ');
   }
 
-  return impactByFeature[featureKey] || 'Improves the overall project workflow for maintaining AI-readable context.';
-}
+  if (type === 'feature') {
+    return impactMap[featureKey].replace(/^Improves /, 'Adds ');
+  }
 
-function interpretChange(event) {
-  return groupEventsByIntent([event])[0] || null;
+  return impactMap[featureKey] || 'Improves the overall project workflow.';
 }
 
 function normalizeStoredUpdates(updates) {
@@ -920,7 +1168,11 @@ function normalizeStoredUpdates(updates) {
     return [];
   }
 
-  return dedupeRecentUpdates(updates.map((update) => normalizeStoredUpdate(update)).filter(Boolean));
+  return dedupeRecentUpdates(
+    updates
+      .map((update) => normalizeStoredUpdate(update))
+      .filter(Boolean)
+  );
 }
 
 function normalizeStoredUpdate(update) {
@@ -936,10 +1188,6 @@ function normalizeStoredUpdate(update) {
     };
   }
 
-  if (update.file && update.action && isMeaningfulEvent(update)) {
-    return toStateUpdate(interpretChange(update));
-  }
-
   return null;
 }
 
@@ -961,118 +1209,71 @@ function normalizeStoredHistoryEntry(entry) {
   }
 
   if (entry.title && entry.type && entry.impact) {
-    const inferredFeature = inferFeatureFromEntry(entry);
-    const featureKey = entry.feature_key || inferredFeature.featureKey;
-    const normalizedType = normalizeUpdateType(entry.type);
-    const subject = describeCanonicalSubject(featureKey);
-
     return {
       timestamp: entry.timestamp || new Date(0).toISOString(),
-      scope: entry.scope || inferredFeature.scope,
-      title: buildIntentTitle(normalizedType, subject),
-      type: normalizedType,
-      impact: describeIntentImpact(normalizedType, featureKey, subject),
-      feature_key: featureKey,
-      feature_name: entry.feature_name || getFeatureMeta(featureKey).name,
-      source: entry.source || 'history'
+      scope: entry.scope || 'project',
+      title: entry.title,
+      type: normalizeUpdateType(entry.type),
+      impact: entry.impact,
+      feature_key: entry.feature_key || inferFeatureKeyFromText(entry.title, entry.impact),
+      feature_name: entry.feature_name || FEATURE_CATALOG[inferFeatureKeyFromText(entry.title, entry.impact)] || 'Project capability'
     };
   }
 
-  if (entry.file && entry.action && isMeaningfulEvent(entry)) {
-    return interpretChange(entry);
-  }
-
   return null;
 }
 
-function inferFeatureFromEntry(entry) {
-  const combinedText = `${entry.title || ''} ${entry.impact || ''}`.toLowerCase();
+function inferFeatureKeyFromText(title, impact) {
+  const combinedText = `${title || ''} ${impact || ''}`.toLowerCase();
 
-  if (combinedText.includes('github') || combinedText.includes('sync')) {
-    return {
-      featureKey: 'github_sync',
-      featureName: getFeatureMeta('github_sync').name,
-      scope: 'logic'
-    };
+  if (combinedText.includes('jwt') || combinedText.includes('auth')) {
+    return 'auth';
   }
 
-  if (combinedText.includes('state') || combinedText.includes('intelligence')) {
-    return {
-      featureKey: 'project_intelligence',
-      featureName: getFeatureMeta('project_intelligence').name,
-      scope: 'logic'
-    };
+  if (combinedText.includes('mongo') || combinedText.includes('mongoose') || combinedText.includes('persist')) {
+    return 'persistence';
   }
 
-  if (combinedText.includes('watch') || combinedText.includes('change tracking')) {
-    return {
-      featureKey: 'change_tracking',
-      featureName: getFeatureMeta('change_tracking').name,
-      scope: 'logic'
-    };
+  if (combinedText.includes('real-time') || combinedText.includes('socket')) {
+    return 'realtime';
   }
 
-  if (
-    combinedText.includes('server') ||
-    combinedText.includes('backend') ||
-    combinedText.includes('endpoint') ||
-    combinedText.includes('delivery')
-  ) {
-    return {
-      featureKey: 'local_context_server',
-      featureName: getFeatureMeta('local_context_server').name,
-      scope: 'backend'
-    };
+  if (combinedText.includes('api') || combinedText.includes('route')) {
+    return 'rest_api';
   }
 
-  if (combinedText.includes('cli') || combinedText.includes('command line')) {
-    return {
-      featureKey: 'cli_workflow',
-      featureName: getFeatureMeta('cli_workflow').name,
-      scope: 'cli'
-    };
+  if (combinedText.includes('git') || combinedText.includes('publish') || combinedText.includes('sync')) {
+    return 'public_sync';
   }
 
-  if (combinedText.includes('documentation') || combinedText.includes('onboarding')) {
-    return {
-      featureKey: 'documentation',
-      featureName: getFeatureMeta('documentation').name,
-      scope: 'documentation'
-    };
+  if (combinedText.includes('watch') || combinedText.includes('change')) {
+    return 'change_tracking';
   }
 
-  if (combinedText.includes('package') || combinedText.includes('dependency')) {
-    return {
-      featureKey: 'package_configuration',
-      featureName: getFeatureMeta('package_configuration').name,
-      scope: 'dependencies'
-    };
+  if (combinedText.includes('command line') || combinedText.includes('cli')) {
+    return 'cli_automation';
   }
 
-  return {
-    featureKey: 'project_workflow',
-    featureName: getFeatureMeta('project_workflow').name,
-    scope: 'project'
-  };
+  if (combinedText.includes('http') || combinedText.includes('context delivery')) {
+    return 'local_context_server';
+  }
+
+  return 'ai_context_generation';
 }
 
 function normalizeUpdateType(type) {
-  if (type === 'removal') {
-    return 'refactor';
-  }
-
   if (type === 'feature' || type === 'improvement' || type === 'refactor' || type === 'fix') {
     return type;
   }
 
+  if (type === 'removal') {
+    return 'fix';
+  }
+
   return 'improvement';
 }
 
 function toStateUpdate(update) {
-  if (!update) {
-    return null;
-  }
-
   return {
     title: update.title,
     type: normalizeUpdateType(update.type),
@@ -1081,17 +1282,17 @@ function toStateUpdate(update) {
 }
 
 function dedupeRecentUpdates(updates) {
-  const seenUpdates = new Set();
+  const seen = new Set();
   const result = [];
 
   for (const update of updates.filter(Boolean)) {
     const key = `${update.title}::${update.type}::${update.impact}`;
 
-    if (seenUpdates.has(key)) {
+    if (seen.has(key)) {
       continue;
     }
 
-    seenUpdates.add(key);
+    seen.add(key);
     result.push(update);
   }
 
@@ -1099,190 +1300,81 @@ function dedupeRecentUpdates(updates) {
 }
 
 function dedupeHistoryEntries(entries) {
-  const seenEntries = new Set();
+  const seen = new Set();
   const result = [];
 
   for (const entry of entries.filter(Boolean)) {
     const key = `${entry.title}::${entry.type}::${entry.feature_key}`;
 
-    if (seenEntries.has(key)) {
+    if (seen.has(key)) {
       continue;
     }
 
-    seenEntries.add(key);
+    seen.add(key);
     result.push(entry);
   }
 
   return result.sort((left, right) => new Date(right.timestamp) - new Date(left.timestamp));
 }
 
-function promoteFeatures(history) {
-  if (!Array.isArray(history) || history.length === 0) {
+function promoteFeatures(historyEntries) {
+  if (!Array.isArray(historyEntries) || historyEntries.length === 0) {
     return [];
   }
 
-  const featureStats = new Map();
-
-  for (const entry of history) {
-    const featureKey = entry.feature_key || inferFeatureFromEntry(entry).featureKey;
-    const featureMeta = getFeatureMeta(featureKey);
-    const existing = featureStats.get(featureKey) || {
-      featureKey,
-      featureName: featureMeta.name,
-      count: 0,
-      score: 0,
-      lastTimestamp: new Date(0).toISOString()
-    };
-
-    existing.count += 1;
-    existing.score += scoreFeatureEntry(entry);
-    if (new Date(entry.timestamp) > new Date(existing.lastTimestamp)) {
-      existing.lastTimestamp = entry.timestamp;
-    }
-
-    featureStats.set(featureKey, existing);
-  }
-
-  const rankedFeatures = Array.from(featureStats.values()).sort((left, right) => {
-    if (right.count !== left.count) {
-      return right.count - left.count;
-    }
-
-    if (right.score !== left.score) {
-      return right.score - left.score;
-    }
-
-    if (getFeaturePriority(right.featureKey) !== getFeaturePriority(left.featureKey)) {
-      return getFeaturePriority(right.featureKey) - getFeaturePriority(left.featureKey);
-    }
-
-    return new Date(right.lastTimestamp) - new Date(left.lastTimestamp);
-  });
-
-  const promoted = [];
-  const seenFeatureNames = new Set();
-
-  for (const feature of rankedFeatures.filter((item) => item.count >= 3)) {
-    if (LOW_VALUE_FEATURE_KEYS.has(feature.featureKey)) {
-      continue;
-    }
-
-    promoted.push(feature.featureName);
-    seenFeatureNames.add(feature.featureName);
-  }
-
-  for (const feature of rankedFeatures) {
-    if (promoted.length >= MAX_KEY_FEATURES) {
-      break;
-    }
-
-    if (LOW_VALUE_FEATURE_KEYS.has(feature.featureKey)) {
-      continue;
-    }
-
-    if (seenFeatureNames.has(feature.featureName)) {
-      continue;
-    }
-
-    promoted.push(feature.featureName);
-    seenFeatureNames.add(feature.featureName);
-  }
+  const scores = new Map();
 
-  for (const feature of rankedFeatures) {
-    if (promoted.length >= MAX_KEY_FEATURES) {
-      break;
-    }
+  for (const entry of historyEntries) {
+    const featureName = entry.feature_name || FEATURE_CATALOG[entry.feature_key];
 
-    if (seenFeatureNames.has(feature.featureName)) {
+    if (!featureName) {
       continue;
     }
 
-    promoted.push(feature.featureName);
-    seenFeatureNames.add(feature.featureName);
+    scores.set(featureName, (scores.get(featureName) || 0) + scoreHistoryEntry(entry));
   }
 
-  return promoted.slice(0, MAX_KEY_FEATURES);
+  return Array.from(scores.entries())
+    .sort((left, right) => right[1] - left[1])
+    .map(([featureName]) => featureName)
+    .slice(0, MAX_KEY_FEATURES);
 }
 
-function scoreFeatureEntry(entry) {
-  const typeWeights = {
+function scoreHistoryEntry(entry) {
+  const weights = {
     feature: 4,
     refactor: 3,
     improvement: 2,
     fix: 2
   };
 
-  return typeWeights[normalizeUpdateType(entry.type)] || 1;
-}
-
-function describeCanonicalSubject(featureKey) {
-  return getFeatureMeta(featureKey).subject;
-}
-
-function createCapabilitySnapshotEntry(featureKey, fileCount, timestamp) {
-  const subject = describeCanonicalSubject(featureKey);
-  const type = fileCount > 2 ? 'refactor' : 'improvement';
-
-  return {
-    timestamp,
-    scope: inferScopeFromFeature(featureKey),
-    title: buildIntentTitle(type, subject),
-    type,
-    impact: describeIntentImpact(type, featureKey, subject),
-    feature_key: featureKey,
-    feature_name: getFeatureMeta(featureKey).name,
-    source: 'project_snapshot'
-  };
+  return weights[normalizeUpdateType(entry.type)] || 1;
 }
 
-function inferScopeFromFeature(featureKey) {
-  if (
-    featureKey === 'github_sync' ||
-    featureKey === 'project_intelligence' ||
-    featureKey === 'change_tracking' ||
-    featureKey === 'project_setup'
-  ) {
-    return 'logic';
-  }
-
-  if (featureKey === 'cli_workflow' || featureKey === 'cli_orchestration') {
-    return 'cli';
-  }
-
-  if (featureKey === 'local_context_server' || featureKey === 'context_delivery_system') {
-    return 'backend';
-  }
-
-  if (featureKey === 'package_configuration') {
-    return 'dependencies';
-  }
-
-  if (featureKey === 'documentation') {
-    return 'documentation';
-  }
-
-  return 'project';
+function mergeKeyFeatures(primaryFeatures, promotedFeatures) {
+  return uniqueNonEmpty([].concat(primaryFeatures || [], promotedFeatures || [])).slice(0, MAX_KEY_FEATURES);
 }
 
-function deriveKnownIssues(projectRoot, techStack, keyFeatures) {
+function deriveKnownIssues(projectRoot, bootstrap) {
   const knownIssues = [];
 
   if (!hasTestIndicators(projectRoot)) {
     knownIssues.push('No automated test suite is detected yet.');
   }
 
-  if (!techStack.framework) {
-    knownIssues.push('No common application framework dependency is currently detected.');
+  if (bootstrap.implementationDetails.length === 0) {
+    knownIssues.push('Project structure exposes limited implementation signals, so deeper architecture details may still be missing.');
   }
 
-  if (keyFeatures.length < 2) {
-    knownIssues.push('Project intelligence history is still sparse, so AI context may omit mature capabilities.');
+  if (!bootstrap.techStack.framework && bootstrap.techStack.language === 'Node.js') {
+    knownIssues.push('No common Node.js application framework dependency is currently detected.');
   }
 
   return knownIssues;
 }
 
 function hasTestIndicators(projectRoot) {
+  const resolvedRoot = resolveProjectRoot(projectRoot);
   const testPaths = [
     'test',
     'tests',
@@ -1293,11 +1385,11 @@ function hasTestIndicators(projectRoot) {
     'jest.config.mjs'
   ];
 
-  return testPaths.some((relativePath) => fs.existsSync(path.join(projectRoot, relativePath)));
+  return testPaths.some((relativePath) => fs.existsSync(path.join(resolvedRoot, relativePath)));
 }
 
-function determineCurrentStage(keyFeatures, historyEntries) {
-  if (keyFeatures.length >= 4 && historyEntries.length >= 4) {
+function determineCurrentStage(keyFeatures, historyEntries, implementationDetails) {
+  if (keyFeatures.length >= 4 && implementationDetails.length >= 3) {
     return 'Production-ready';
   }
 
@@ -1308,86 +1400,69 @@ function determineCurrentStage(keyFeatures, historyEntries) {
   return 'Early development';
 }
 
-function generateAiSummary(state, historyEntries) {
-  const featureSignals = collectFeatureSignals(historyEntries, state.key_features);
-  const projectType = featureSignals.has('cli_workflow') || featureSignals.has('cli_orchestration')
-    ? 'CLI tool'
-    : 'project system';
-  let coreCapability = 'maintains an AI-readable view of project progress';
-  let uniqueValue = 'so AI collaborators can understand the current project state immediately';
+function generateAiSummary(state, bootstrap) {
+  const features = state.key_features || [];
+  const details = bootstrap.implementationDetails || [];
+  const projectType = bootstrap.projectType || 'software project';
+  const normalizedType = projectType === 'backend API platform'
+    ? 'Backend API platform'
+    : capitalize(projectType);
 
-  if (featureSignals.has('project_intelligence') && featureSignals.has('change_tracking')) {
-    coreCapability = 'turns meaningful project activity into AI-readable context';
-  } else if (featureSignals.has('project_intelligence')) {
-    coreCapability = 'converts development work into AI-readable project state';
-  } else if (featureSignals.has('local_context_server')) {
-    coreCapability = 'delivers AI-readable project context through clear endpoints';
+  if (details.some((detail) => detail.includes('JWT')) && details.some((detail) => detail.includes('MongoDB'))) {
+    return `${normalizedType} with JWT authentication and MongoDB-backed application logic.`;
   }
 
   if (
-    featureSignals.has('github_sync') ||
-    featureSignals.has('context_delivery_system') ||
-    featureSignals.has('cli_orchestration')
+    features.includes(FEATURE_CATALOG.ai_context_generation) &&
+    features.includes(FEATURE_CATALOG.public_sync)
   ) {
-    uniqueValue = 'and enables public AI collaboration through GitHub-synced context endpoints';
-  } else if (featureSignals.has('local_context_server')) {
-    uniqueValue = 'and keeps current context available through local AI endpoints';
+    return `${normalizedType} that generates AI-readable project context, tracks meaningful changes, and can publish public project state through GitHub.`;
   }
 
-  return `${capitalize(projectType)} that ${coreCapability} ${uniqueValue}.`;
-}
-
-function collectFeatureSignals(historyEntries, keyFeatures) {
-  const featureSignals = new Set();
+  if (
+    features.includes(FEATURE_CATALOG.rest_api) &&
+    details.some((detail) => detail.includes('Express'))
+  ) {
+    return `${normalizedType} with RESTful request handling and structured server-side workflow orchestration.`;
+  }
 
-  for (const entry of historyEntries) {
-    if (entry.feature_key) {
-      featureSignals.add(entry.feature_key);
-    }
+  if (features.length >= 2) {
+    return `${normalizedType} focused on ${features.slice(0, 2).join(' and ').toLowerCase()}.`;
   }
 
-  for (const featureName of keyFeatures || []) {
-    for (const [featureKey, featureMeta] of Object.entries(FEATURE_CATALOG)) {
-      if (featureMeta.name === featureName) {
-        featureSignals.add(featureKey);
-      }
-    }
+  if (details.length > 0) {
+    return `${normalizedType} built around ${details[0].toLowerCase()}.`;
   }
 
-  return featureSignals;
+  return `${normalizedType} with detectable project structure and implementation patterns.`;
 }
 
-function generateNextSteps(state, historyEntries) {
+function generateNextSteps(state, bootstrap, historyEntries) {
   const nextSteps = [];
-  const featureSignals = collectFeatureSignals(historyEntries, state.key_features);
-
-  if (state.key_features.length === 0) {
-    nextSteps.push('Capture a few meaningful project milestones so stable AI-visible features can emerge from real development history.');
-  }
 
   if (state.known_issues.includes('No automated test suite is detected yet.')) {
-    nextSteps.push('Add automated tests for the intelligence engine, watcher, and GitHub sync workflow.');
-  }
-
-  if (!featureSignals.has('project_intelligence')) {
-    nextSteps.push('Strengthen the intelligence engine so more project-level capabilities are captured automatically.');
+    nextSteps.push('Add automated tests that cover the main application flow and critical integration points.');
   }
 
-  if (!featureSignals.has('local_context_server')) {
-    nextSteps.push('Expand context delivery coverage so AI consumers can reliably read current project state.');
+  if (bootstrap.implementationDetails.length < 2) {
+    nextSteps.push('Strengthen the project structure so major implementation patterns are easier to detect automatically.');
   }
 
-  if (!featureSignals.has('github_sync')) {
-    nextSteps.push('Validate public sync behavior so AI tools can safely consume the latest project context from GitHub.');
+  if (historyEntries.length === 0) {
+    nextSteps.push('Capture the next meaningful project update so recent evolution is reflected alongside the bootstrap analysis.');
   }
 
   if (state.current_stage === 'Early development') {
-    nextSteps.push('Ship the next core workflow milestone to turn the project into a functional prototype.');
+    nextSteps.push('Ship the next core capability to move the project from initial structure into a functional prototype.');
   }
 
   return Array.from(new Set(nextSteps)).slice(0, 4);
 }
 
+function uniqueNonEmpty(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
 function capitalize(value) {
   if (!value) {
     return '';
@@ -1459,6 +1534,7 @@ function createDebouncedStateUpdater(projectRoot, options) {
 module.exports = {
   CONTEXT_DIR_NAME,
   DEFAULT_CONFIG,
+  bootstrapProjectAnalysis,
   createDebouncedStateUpdater,
   createDefaultChangelog,
   createDefaultState,
@@ -1466,7 +1542,6 @@ module.exports = {
   ensureContextDirectory,
   getContextPaths,
   groupEventsByIntent,
-  interpretChange,
   loadRuntimeConfig,
   promoteFeatures,
   readJsonFile,
@@ -1477,4 +1552,4 @@ module.exports = {
   updateProjectState,
   writeJsonAtomic,
   writeTextAtomic
-};
+};