aibridge-context 1.1.0 → 1.3.0

package/README.md

@@ -4,6 +4,12 @@
 
 Think of it as Git for AI context.
 
+## ⚠️ Public AI Access Warning
+
+When GitHub sync is enabled, your project context becomes publicly accessible via a URL.
+
+Do NOT use this tool with sensitive data.
+
 ## Quick Start
 
 ```bash
@@ -12,6 +18,14 @@ npx aibridge-context link-github
 npx aibridge-context start
 ```
 
+## How It Works
+
+1. Tracks project changes
+2. Generates structured AI context
+3. Syncs to GitHub (optional)
+4. Creates a public URL
+5. AI tools read this URL for context
+
 ## Usage
 
 This package exposes a CLI command:
@@ -60,7 +74,7 @@ If published to npm, the package exposes the `aibridge` binary.
 
 `ai-context` is supported as a legacy alias.
 
-## Use With AI
+## Using With AI
 
 After enabling GitHub sync, use:
 
@@ -70,6 +84,13 @@ https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json
 
 This URL always returns the latest project state.
 
+Paste this into any AI:
+
+```text
+Use this as source of truth:
+https://raw.githubusercontent.com/<user>/<repo>/main/.ai-context/state.json
+```
+
 You can also share:
 
 ```text
@@ -155,7 +176,10 @@ Default configuration:
   "gitSync": {
     "enabled": false,
     "push": true,
-    "commitMessage": "auto: update AI context"
+    "commitMessage": "auto: update AI context",
+    "remote": "origin",
+    "branch": "main",
+    "repoUrl": ""
   }
 }
 ```

package/bin/cli.js

@@ -34,7 +34,12 @@ async function run() {
 
   try {
     if (command === 'init') {
-      await initProject(projectRoot, { logger });
+      await initProject(projectRoot, {
+        logger,
+        requestPublicSyncConsent: true,
+        promptForPublicSyncConsent: () =>
+          promptYesNo('[aibridge] Do you want to enable GitHub sync and public AI access? (y/n) ')
+      });
       return;
     }
 
@@ -59,6 +64,19 @@ async function run() {
 
     if (command === 'link-github') {
       await initProject(projectRoot, { logger });
+      logger.warn('You are about to connect a GitHub repository.');
+      logger.info('This will:');
+      logger.info('* Push .ai-context to GitHub');
+      logger.info('* Make project context publicly accessible');
+      logger.info('* Allow AI systems to read your project state');
+
+      const shouldContinue = await promptYesNo('[aibridge] Continue? (y/n) ');
+
+      if (!shouldContinue) {
+        logger.info('GitHub linking cancelled. Public sync remains unchanged.');
+        return;
+      }
+
       const repoUrl = process.argv[3] || (await promptForRepoUrl());
 
       if (!repoUrl) {
@@ -88,11 +106,23 @@ async function run() {
     if (command === 'start') {
       await initProject(projectRoot, { logger });
       const config = await loadRuntimeConfig(projectRoot);
+      const port = Number(process.env.AI_CONTEXT_PORT || config.port || 3333);
+      logger.info('Watching project for changes...');
       const serverHandle = await startServer({
         projectRoot,
-        port: Number(process.env.AI_CONTEXT_PORT || config.port || 3333),
+        port,
         logger
       });
+      logger.info(`Local server: http://localhost:${port}`);
+
+      if (config.gitSync.enabled) {
+        logger.info('Auto-sync to GitHub is ENABLED');
+        logger.warn('Changes will be publicly available to AI');
+      } else {
+        logger.info('GitHub sync is DISABLED');
+        logger.info('Data is only available locally');
+      }
+
       const watcherHandle = await startWatcher(projectRoot, { logger });
 
       const shutdown = async (signal) => {
@@ -131,17 +161,14 @@ async function run() {
 function printHelp() {
   console.log(`aibridge-context
 
-Usage:
-  aibridge init
-  aibridge link-github
-  aibridge start
-  aibridge update
-
 Commands:
-  init    Create .ai-context and initialize AI context files
-  link-github  Connect a GitHub remote and enable public AI sync
-  start   Start the watcher and local server on port 3333
-  update  Trigger a manual state update
+  init           Initialize AI context (with optional public sync)
+  link-github    Connect GitHub for public AI access
+  start          Start watcher and server
+  update         Manually update context
+
+Description:
+  This tool creates an AI-readable version of your project and can expose it via a public URL for AI tools.
 `);
 }
 
@@ -152,11 +179,29 @@ async function promptForRepoUrl() {
   });
 
   try {
-    const response = await rl.question('GitHub repository URL: ');
+    const response = await rl.question('[aibridge] GitHub repository URL: ');
     return response.trim();
   } finally {
     rl.close();
   }
 }
 
+async function promptYesNo(question) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    return false;
+  }
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    const response = await rl.question(question);
+    return response.trim().toLowerCase() === 'y';
+  } finally {
+    rl.close();
+  }
+}
+
 run();

package/core/gitSync.js

@@ -74,6 +74,13 @@ async function hasStagedContextChanges(projectRoot) {
   }
 }
 
+function formatGitError(error) {
+  const stderr = typeof error.stderr === 'string' ? error.stderr.trim() : '';
+  const stdout = typeof error.stdout === 'string' ? error.stdout.trim() : '';
+  const message = stderr || stdout || error.message || 'Unknown git error.';
+  return message.split('\n')[0];
+}
+
 async function ensureGitInitialized(projectRoot, logger) {
   const repositoryReady = await isGitRepository(projectRoot);
 
@@ -93,6 +100,7 @@ async function ensureGitInitialized(projectRoot, logger) {
         throw error;
       }
     }
+
     await ensureMainBranch(projectRoot);
 
     if (logger) {
@@ -104,7 +112,7 @@ async function ensureGitInitialized(projectRoot, logger) {
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`Git initialization failed gracefully: ${error.message}`);
+      logger.warn(`Git initialization failed gracefully: ${formatGitError(error)}`);
     }
 
     return {
@@ -156,7 +164,7 @@ function logMissingRemoteInstructions(logger) {
     return;
   }
 
-  logger.warn('No GitHub remote detected.');
+  logger.warn('GitHub remote not found.');
   logger.info('Run:');
   logger.info('git remote add origin <repo-url>');
   logger.info('git push -u origin main');
@@ -167,10 +175,15 @@ function logPublicAiEndpoints(logger, urls) {
     return;
   }
 
-  logger.info('Public AI endpoint:');
+  logger.info('\u2705 AI Context Synced Successfully');
+  logger.info('\u{1F310} Public AI Endpoint:');
   logger.info(urls.stateUrl);
-  logger.info('Use this with AI:');
+  logger.info('\u{1F9E0} AI Instructions Endpoint:');
   logger.info(urls.brainUrl);
+  logger.warn('\u26A0\uFE0F IMPORTANT:');
+  logger.warn('This data is PUBLIC. Anyone with this link can access it.');
+  logger.info('\u{1F916} To use with AI:');
+  logger.info('"Use this URL as the source of truth for my project."');
 }
 
 async function linkGithubRepository(projectRoot, repoUrl, logger) {
@@ -189,16 +202,13 @@ async function linkGithubRepository(projectRoot, repoUrl, logger) {
     await ensureMainBranch(projectRoot);
     await runGit(projectRoot, ['push', '-u', 'origin', 'main']);
 
-    const urls = buildPublicAiUrls(normalizedRepoUrl, 'main');
-    logPublicAiEndpoints(logger, urls);
-
     return {
       ok: true,
-      urls
+      urls: buildPublicAiUrls(normalizedRepoUrl, 'main')
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`GitHub link failed gracefully: ${error.message}`);
+      logger.warn(`GitHub link failed gracefully: ${formatGitError(error)}`);
     }
 
     return {
@@ -211,7 +221,7 @@ async function linkGithubRepository(projectRoot, repoUrl, logger) {
 async function syncContextToGit(projectRoot, config, logger) {
   const settings = Object.assign(
     {
-      enabled: true,
+      enabled: false,
       push: true,
       commitMessage: 'auto: update AI context',
       remote: 'origin',
@@ -285,11 +295,6 @@ async function syncContextToGit(projectRoot, config, logger) {
     }
 
     const urls = buildPublicAiUrls(remoteUrl, branchName);
-
-    if (logger) {
-      logger.info('Synced .ai-context changes to git.');
-    }
-
     logPublicAiEndpoints(logger, urls);
 
     return {
@@ -299,7 +304,7 @@ async function syncContextToGit(projectRoot, config, logger) {
     };
   } catch (error) {
     if (logger) {
-      logger.warn(`Git sync failed gracefully: ${error.message}`);
+      logger.warn(`Git sync failed gracefully: ${formatGitError(error)}`);
     }
 
     return {

package/core/init.js

@@ -18,7 +18,15 @@ const {
 const { ensureGitInitialized } = require('./gitSync');
 
 async function initProject(projectRoot, options) {
-  const settings = Object.assign({ logger: null, force: false }, options);
+  const settings = Object.assign(
+    {
+      logger: null,
+      force: false,
+      requestPublicSyncConsent: false,
+      promptForPublicSyncConsent: null
+    },
+    options
+  );
   const logger = settings.logger;
   const contextDir = await ensureContextDirectory(projectRoot);
   const paths = getContextPaths(projectRoot);
@@ -36,6 +44,7 @@ async function initProject(projectRoot, options) {
   const existingChangelog = await readJsonFile(paths.changelogFile, null);
   const templateState = JSON.parse(stateTemplate);
   const templateChangelog = JSON.parse(changelogTemplate);
+  let enableGitSync = false;
 
   const initialState = Object.assign({}, templateState, existingState || createDefaultState(projectRoot), {
     project: metadata.project,
@@ -62,18 +71,18 @@ async function initProject(projectRoot, options) {
     await writeTextAtomic(paths.contextFile, initialContext);
   }
 
-  await updateRuntimeConfig(
-    projectRoot,
-    existingConfig
-      ? null
-      : {
-          gitSync: {
-            enabled: true,
-            push: true,
-            commitMessage: 'auto: update AI context'
-          }
-        }
-  );
+  if (!existingConfig && settings.requestPublicSyncConsent) {
+    enableGitSync = await requestPublicSyncConsent(
+      logger,
+      settings.promptForPublicSyncConsent
+    );
+  }
+
+  await updateRuntimeConfig(projectRoot, existingConfig ? null : {
+    gitSync: {
+      enabled: enableGitSync
+    }
+  });
 
   await ensureGitInitialized(projectRoot, logger);
 
@@ -87,6 +96,29 @@ async function initProject(projectRoot, options) {
   };
 }
 
+async function requestPublicSyncConsent(logger, promptForPublicSyncConsent) {
+  if (logger) {
+    logger.warn('This tool can make parts of your project publicly accessible for AI tools.');
+    logger.info('It will:');
+    logger.info('* Track project changes');
+    logger.info('* Generate AI-readable context');
+    logger.info('* Optionally sync to GitHub');
+    logger.info('* Create a PUBLIC URL accessible by AI systems');
+    logger.warn('WARNING:');
+    logger.warn('Anyone with the URL can read this data.');
+  }
+
+  if (typeof promptForPublicSyncConsent !== 'function') {
+    if (logger) {
+      logger.info('GitHub sync will remain disabled until you explicitly enable it.');
+    }
+
+    return false;
+  }
+
+  return Boolean(await promptForPublicSyncConsent());
+}
+
 async function fileExists(filePath) {
   try {
     await fsp.access(filePath);

package/core/stateManager.js

@@ -5,14 +5,16 @@ const fsp = require('fs/promises');
 const path = require('path');
 
 const CONTEXT_DIR_NAME = '.ai-context';
-const MAX_RECENT_UPDATES = 50;
-const MAX_CHANGELOG_ENTRIES = 200;
+const MAX_RECENT_UPDATES = 8;
+const MAX_CHANGELOG_ENTRIES = 50;
+const IMPORTANT_DIRECTORIES = ['core/', 'server/', 'bin/'];
+const IMPORTANT_EXTENSIONS = new Set(['.js', '.ts', '.py']);
 
 const DEFAULT_CONFIG = {
   port: 3333,
   debounceMs: 600,
   gitSync: {
-    enabled: true,
+    enabled: false,
     push: true,
     commitMessage: 'auto: update AI context',
     remote: 'origin',
@@ -59,10 +61,14 @@ function isObject(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',
-    stackLabel: 'Node.js project',
+    techStack: Object.assign({}, techStack, {
+      package_manager: packageManager
+    }),
+    stackLabel: buildStackLabel(techStack),
     packageManager
   };
 
@@ -73,53 +79,134 @@ function detectProjectMetadata(projectRoot) {
   try {
     const rawPackage = fs.readFileSync(packageJsonPath, 'utf8');
     const parsedPackage = JSON.parse(rawPackage);
-    const dependencies = Object.assign(
-      {},
-      parsedPackage.dependencies || {},
-      parsedPackage.devDependencies || {}
-    );
 
     metadata.project = parsedPackage.name || metadata.project;
     metadata.version = parsedPackage.version || metadata.version;
-    metadata.stackLabel = describeStack(dependencies);
-    metadata.packageManager = packageManager;
   } catch (error) {
-    metadata.stackLabel = 'Node.js project';
+    metadata.stackLabel = buildStackLabel(metadata.techStack);
   }
 
   return metadata;
 }
 
-function detectPackageManager(projectRoot) {
-  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
-    return 'pnpm';
+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 = {};
+
+  if (hasPackageJson) {
+    try {
+      const rawPackage = fs.readFileSync(packageJsonPath, 'utf8');
+      const parsedPackage = JSON.parse(rawPackage);
+      dependencies = Object.assign(
+        {},
+        parsedPackage.dependencies || {},
+        parsedPackage.devDependencies || {}
+      );
+    } catch (error) {
+      dependencies = {};
+    }
   }
 
-  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) {
-    return 'yarn';
+  let language = '';
+  let runtime = '';
+
+  if (hasPackageJson || hasAnyFileExtension(projectRoot, ['.js', '.ts', '.mjs', '.cjs'])) {
+    language = 'Node.js';
+    runtime = 'Node.js';
+  } else if (hasPythonMarker || hasAnyFileExtension(projectRoot, ['.py'])) {
+    language = 'Python';
+    runtime = 'Python';
   }
 
-  return 'npm';
+  return {
+    language,
+    framework: detectFramework(dependencies),
+    runtime,
+    package_manager: detectPackageManager(projectRoot)
+  };
 }
 
-function describeStack(dependencies) {
+function detectFramework(dependencies) {
   if (dependencies.next) {
-    return 'Node.js + Next.js';
+    return 'Next.js';
   }
 
   if (dependencies.react) {
-    return 'Node.js + React';
+    return 'React';
   }
 
   if (dependencies.express) {
-    return 'Node.js + Express';
+    return 'Express';
+  }
+
+  return '';
+}
+
+function buildStackLabel(techStack) {
+  const parts = [techStack.language, techStack.framework].filter(Boolean);
+  return parts.length > 0 ? parts.join(' + ') : 'Project';
+}
+
+function hasAnyFileExtension(projectRoot, extensions) {
+  return scanProjectFiles(projectRoot, 2).some((filePath) =>
+    extensions.includes(path.extname(filePath).toLowerCase())
+  );
+}
+
+function scanProjectFiles(projectRoot, maxDepth) {
+  const results = [];
+
+  function visit(currentDir, depth) {
+    if (depth > maxDepth) {
+      return;
+    }
+
+    let entries = [];
+
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (error) {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+      const relativePath = normalizeProjectPath(path.relative(projectRoot, fullPath));
+
+      if (entry.isDirectory()) {
+        if (shouldIgnoreProjectFile(relativePath)) {
+          continue;
+        }
+
+        visit(fullPath, depth + 1);
+        continue;
+      }
+
+      if (!shouldIgnoreProjectFile(relativePath)) {
+        results.push(relativePath);
+      }
+    }
   }
 
-  if (dependencies.typescript) {
-    return 'Node.js + TypeScript';
+  visit(projectRoot, 0);
+  return results;
+}
+
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) {
+    return 'yarn';
   }
 
-  return 'Node.js project';
+  return 'npm';
 }
 
 async function ensureContextDirectory(projectRoot) {
@@ -150,19 +237,26 @@ async function writeTextAtomic(filePath, content) {
 
 function createDefaultState(projectRoot) {
   const metadata = detectProjectMetadata(projectRoot);
-
-  return {
+  const keyFeatures = deriveKeyFeatures(projectRoot);
+  const knownIssues = deriveKnownIssues(projectRoot, metadata.techStack);
+  const currentStage = determineCurrentStage(keyFeatures);
+  const state = {
     project: metadata.project,
     version: metadata.version,
     last_updated: new Date(0).toISOString(),
-    stats: {
-      files_changed: 0,
-      last_file: ''
-    },
+    ai_summary: '',
+    tech_stack: metadata.techStack,
+    current_stage: currentStage,
     recent_updates: [],
-    features: [],
+    key_features: keyFeatures,
+    known_issues: knownIssues,
     next_steps: []
   };
+
+  state.ai_summary = generateAiSummary(state);
+  state.next_steps = generateNextSteps(state);
+
+  return state;
 }
 
 function createDefaultChangelog() {
@@ -204,62 +298,575 @@ async function updateProjectState(projectRoot, changeEvent, options) {
   );
   const logger = settings.logger;
   const contextPaths = getContextPaths(projectRoot);
-  const state = await readJsonFile(contextPaths.stateFile, createDefaultState(projectRoot));
-  const changelog = await readJsonFile(contextPaths.changelogFile, createDefaultChangelog());
+  const metadata = detectProjectMetadata(projectRoot);
+  const existingState = await readJsonFile(contextPaths.stateFile, createDefaultState(projectRoot));
+  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 interpretedEvents = meaningfulEvents
+    .map((event) => interpretChange(event))
+    .filter(Boolean);
+  const previousRecentUpdates = normalizeStoredUpdates(existingState.recent_updates);
+  const previousHistoryEntries = normalizeStoredHistoryEntries(existingChangelog.entries);
+  const recentUpdates = dedupeRecentUpdates(
+    interpretedEvents.map(toStateUpdate).concat(previousRecentUpdates)
+  ).slice(0, MAX_RECENT_UPDATES);
+  const historyEntries = dedupeHistoryEntries(
+    interpretedEvents.concat(previousHistoryEntries)
+  ).slice(0, MAX_CHANGELOG_ENTRIES);
+  const keyFeatures = deriveKeyFeatures(projectRoot);
+  const knownIssues = deriveKnownIssues(projectRoot, metadata.techStack);
+  const nextState = {
+    project: metadata.project,
+    version: metadata.version,
+    last_updated: timestamp,
+    ai_summary: '',
+    tech_stack: metadata.techStack,
+    current_stage: determineCurrentStage(keyFeatures),
+    recent_updates: recentUpdates,
+    key_features: keyFeatures,
+    known_issues: knownIssues,
+    next_steps: []
+  };
+
+  nextState.ai_summary = generateAiSummary(nextState);
+  nextState.next_steps = generateNextSteps(nextState);
+
+  await writeJsonAtomic(contextPaths.stateFile, nextState);
+  await writeJsonAtomic(contextPaths.changelogFile, { entries: historyEntries });
 
-  if (validEvents.length === 0) {
-    return state;
+  if (logger) {
+    logger.debug(`Updated AI context with ${interpretedEvents.length} meaningful change(s).`);
   }
 
-  const latestEvent = validEvents[validEvents.length - 1];
-  const timestamp = latestEvent.timestamp || new Date().toISOString();
-  const recentUpdates = Array.isArray(state.recent_updates) ? state.recent_updates.slice() : [];
-  const changelogEntries = Array.isArray(changelog.entries) ? changelog.entries.slice() : [];
+  if (typeof settings.syncCallback === 'function') {
+    await settings.syncCallback();
+  }
 
-  for (const event of validEvents) {
-    const normalizedEvent = {
-      timestamp: event.timestamp || timestamp,
-      action: event.action || 'updated',
-      file: event.file || ''
-    };
+  return nextState;
+}
 
-    recentUpdates.push(normalizedEvent);
-    changelogEntries.push(normalizedEvent);
+function determineUpdateTimestamp(events) {
+  if (!Array.isArray(events) || events.length === 0) {
+    return new Date().toISOString();
   }
 
-  const nextState = {
-    project: state.project || createDefaultState(projectRoot).project,
-    version: state.version || createDefaultState(projectRoot).version,
-    last_updated: timestamp,
-    stats: {
-      files_changed: (state.stats && typeof state.stats.files_changed === 'number'
-        ? state.stats.files_changed
-        : 0) + validEvents.length,
-      last_file: latestEvent.file || ''
-    },
-    recent_updates: recentUpdates.slice(-MAX_RECENT_UPDATES),
-    features: Array.isArray(state.features) ? state.features : [],
-    next_steps: Array.isArray(state.next_steps) ? state.next_steps : []
+  const latestEvent = events[events.length - 1];
+  return latestEvent.timestamp || new Date().toISOString();
+}
+
+function normalizeProjectPath(filePath) {
+  return String(filePath || '').split(path.sep).join('/').replace(/^\.\/+/, '');
+}
+
+function shouldIgnoreProjectFile(filePath) {
+  const normalizedPath = normalizeProjectPath(filePath).toLowerCase();
+
+  if (!normalizedPath) {
+    return false;
+  }
+
+  const segments = normalizedPath.split('/');
+  const baseName = segments[segments.length - 1];
+
+  if (
+    segments.includes('node_modules') ||
+    segments.includes('.git') ||
+    segments.includes('.ai-context') ||
+    segments.includes('dist') ||
+    segments.includes('build')
+  ) {
+    return true;
+  }
+
+  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();
+  const baseName = path.basename(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(baseName))) {
+    score += 2;
+  }
+
+  if (lowerPath === 'package.json') {
+    score += 2;
+  }
+
+  if (lowerPath === 'readme.md') {
+    score += 1;
+  }
+
+  return score;
+}
+
+function isMeaningfulEvent(event) {
+  if (!event || !event.file) {
+    return false;
+  }
+
+  return scoreEvent(event.file) >= 2;
+}
+
+function collapseEventsByFile(events) {
+  const collapsedEvents = new Map();
+
+  for (const event of events) {
+    const normalizedFile = normalizeProjectPath(event.file).toLowerCase();
+    collapsedEvents.set(
+      normalizedFile,
+      Object.assign({}, event, {
+        file: normalizeProjectPath(event.file)
+      })
+    );
+  }
+
+  return Array.from(collapsedEvents.values());
+}
+
+function interpretChange(event) {
+  const filePath = normalizeProjectPath(event.file);
+  const area = classifyChangeArea(filePath);
+  const subject = describeChangeSubject(filePath, area);
+  const type = mapActionToType(event.action);
+  const title = `${mapActionToVerb(event.action)} ${subject}`;
+
+  return {
+    timestamp: event.timestamp || new Date().toISOString(),
+    file: filePath,
+    title,
+    type,
+    impact: describeImpact(area, subject, event.action)
   };
+}
+
+function classifyChangeArea(filePath) {
+  const lowerPath = filePath.toLowerCase();
+
+  if (lowerPath === 'package.json') {
+    return 'dependencies';
+  }
+
+  if (lowerPath === 'readme.md') {
+    return 'documentation';
+  }
+
+  if (lowerPath.startsWith('core/')) {
+    return 'logic';
+  }
+
+  if (lowerPath.startsWith('server/')) {
+    return 'backend';
+  }
+
+  if (lowerPath.startsWith('bin/')) {
+    return 'CLI';
+  }
+
+  if (lowerPath.startsWith('templates/')) {
+    return 'templates';
+  }
+
+  return 'project';
+}
+
+function describeChangeSubject(filePath, area) {
+  const lowerPath = filePath.toLowerCase();
+  const baseName = path.basename(filePath);
+
+  if (lowerPath === 'package.json') {
+    return 'dependency configuration';
+  }
+
+  if (lowerPath === 'readme.md') {
+    return 'documentation';
+  }
+
+  if (lowerPath === 'core/gitsync.js') {
+    return 'GitHub sync logic';
+  }
+
+  if (lowerPath === 'core/statemanager.js') {
+    return 'state intelligence logic';
+  }
+
+  if (lowerPath === 'core/watcher.js') {
+    return 'watcher logic';
+  }
+
+  if (lowerPath === 'core/init.js') {
+    return 'initialization flow';
+  }
+
+  if (lowerPath === 'server/server.js') {
+    return 'backend server';
+  }
+
+  if (lowerPath === 'server/routes.js') {
+    return 'backend routes';
+  }
+
+  if (lowerPath === 'bin/cli.js') {
+    return 'CLI workflow';
+  }
+
+  if (area === 'templates') {
+    return `${humanizeFileName(baseName)} template`;
+  }
+
+  if (area === 'logic') {
+    return `${humanizeFileName(baseName)} logic`;
+  }
+
+  if (area === 'backend') {
+    return `${humanizeFileName(baseName)} backend`;
+  }
+
+  if (area === 'CLI') {
+    return 'CLI workflow';
+  }
+
+  return humanizeFileName(baseName);
+}
+
+function humanizeFileName(fileName) {
+  return fileName
+    .replace(path.extname(fileName), '')
+    .replace(/[-_.]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function mapActionToType(action) {
+  if (action === 'add') {
+    return 'feature';
+  }
+
+  if (action === 'delete') {
+    return 'removal';
+  }
+
+  return 'improvement';
+}
+
+function mapActionToVerb(action) {
+  if (action === 'add') {
+    return 'Added';
+  }
+
+  if (action === 'delete') {
+    return 'Removed';
+  }
+
+  return 'Updated';
+}
+
+function describeImpact(area, subject, action) {
+  if (action === 'delete') {
+    return `Removes ${subject.toLowerCase()} from the project workflow.`;
+  }
+
+  if (subject === 'GitHub sync logic') {
+    return 'Improves reliability of context syncing.';
+  }
+
+  if (subject === 'state intelligence logic') {
+    return 'Improves the quality of AI-readable project state.';
+  }
+
+  if (subject === 'watcher logic') {
+    return 'Improves how meaningful project changes are detected.';
+  }
+
+  if (area === 'backend') {
+    return 'Improves local AI context delivery.';
+  }
+
+  if (area === 'CLI') {
+    return 'Improves command-line workflow clarity and usability.';
+  }
+
+  if (area === 'documentation') {
+    return 'Improves onboarding and usage clarity.';
+  }
+
+  if (area === 'dependencies') {
+    return 'Updates package behavior and dependency management.';
+  }
+
+  if (area === 'templates') {
+    return 'Improves generated AI context defaults.';
+  }
+
+  return 'Improves core project intelligence and automation.';
+}
+
+function normalizeStoredUpdates(updates) {
+  if (!Array.isArray(updates)) {
+    return [];
+  }
+
+  return dedupeRecentUpdates(
+    updates
+      .map((update) => normalizeStoredUpdate(update))
+      .filter(Boolean)
+  );
+}
+
+function normalizeStoredUpdate(update) {
+  if (!update) {
+    return null;
+  }
+
+  if (update.title && update.type && update.impact) {
+    return {
+      title: update.title,
+      type: update.type,
+      impact: update.impact
+    };
+  }
+
+  if (update.file && update.action && isMeaningfulEvent(update)) {
+    return toStateUpdate(interpretChange(update));
+  }
+
+  return null;
+}
+
+function normalizeStoredHistoryEntries(entries) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+
+  return dedupeHistoryEntries(
+    entries
+      .map((entry) => normalizeStoredHistoryEntry(entry))
+      .filter(Boolean)
+  );
+}
+
+function normalizeStoredHistoryEntry(entry) {
+  if (!entry) {
+    return null;
+  }
+
+  if (entry.title && entry.type && entry.impact) {
+    return {
+      timestamp: entry.timestamp || new Date(0).toISOString(),
+      file: normalizeProjectPath(entry.file || ''),
+      title: entry.title,
+      type: entry.type,
+      impact: entry.impact
+    };
+  }
+
+  if (entry.file && entry.action && isMeaningfulEvent(entry)) {
+    return interpretChange(entry);
+  }
+
+  return null;
+}
 
-  const nextChangelog = {
-    entries: changelogEntries.slice(-MAX_CHANGELOG_ENTRIES)
+function toStateUpdate(update) {
+  return {
+    title: update.title,
+    type: update.type,
+    impact: update.impact
   };
+}
 
-  await writeJsonAtomic(contextPaths.stateFile, nextState);
-  await writeJsonAtomic(contextPaths.changelogFile, nextChangelog);
+function dedupeRecentUpdates(updates) {
+  const seenUpdates = new Set();
+  const result = [];
 
-  if (logger) {
-    logger.debug(`Updated AI context for ${validEvents.length} change(s).`);
+  for (const update of updates) {
+    const key = `${update.title}::${update.type}::${update.impact}`;
+
+    if (seenUpdates.has(key)) {
+      continue;
+    }
+
+    seenUpdates.add(key);
+    result.push(update);
   }
 
-  if (typeof settings.syncCallback === 'function') {
-    await settings.syncCallback();
+  return result;
+}
+
+function dedupeHistoryEntries(entries) {
+  const seenEntries = new Set();
+  const result = [];
+
+  for (const entry of entries) {
+    const key = `${entry.title}::${entry.type}::${entry.file}`;
+
+    if (seenEntries.has(key)) {
+      continue;
+    }
+
+    seenEntries.add(key);
+    result.push(entry);
   }
 
-  return nextState;
+  return result;
+}
+
+function deriveKeyFeatures(projectRoot) {
+  const features = [];
+
+  if (fs.existsSync(path.join(projectRoot, 'bin', 'cli.js'))) {
+    features.push('CLI commands for initializing, linking, starting, and updating AI context');
+  }
+
+  if (fs.existsSync(path.join(projectRoot, 'core', 'watcher.js'))) {
+    features.push('Noise-filtered watcher that turns file changes into meaningful project updates');
+  }
+
+  if (
+    fs.existsSync(path.join(projectRoot, 'server', 'server.js')) &&
+    fs.existsSync(path.join(projectRoot, 'server', 'routes.js'))
+  ) {
+    features.push('Local Express server for AI-readable context endpoints');
+  }
+
+  if (fs.existsSync(path.join(projectRoot, 'core', 'gitSync.js'))) {
+    features.push('Optional GitHub sync for publishing public AI-readable context');
+  }
+
+  if (fs.existsSync(path.join(projectRoot, 'core', 'stateManager.js'))) {
+    features.push('Intelligent state engine that summarizes project evolution for AI tools');
+  }
+
+  return features;
+}
+
+function deriveKnownIssues(projectRoot, techStack) {
+  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.');
+  }
+
+  return knownIssues;
+}
+
+function hasTestIndicators(projectRoot) {
+  const testPaths = [
+    'test',
+    'tests',
+    '__tests__',
+    'vitest.config.js',
+    'jest.config.js',
+    'jest.config.cjs',
+    'jest.config.mjs'
+  ];
+
+  return testPaths.some((relativePath) => fs.existsSync(path.join(projectRoot, relativePath)));
+}
+
+function determineCurrentStage(keyFeatures) {
+  const hasCli = keyFeatures.some((feature) => feature.includes('CLI commands'));
+  const hasSync = keyFeatures.some((feature) => feature.includes('GitHub sync'));
+  const hasServer = keyFeatures.some((feature) => feature.includes('Express server'));
+  const hasWatcher = keyFeatures.some((feature) => feature.includes('watcher'));
+  const hasIntelligence = keyFeatures.some((feature) => feature.includes('Intelligent state engine'));
+
+  if (hasCli && hasSync && hasServer && hasWatcher && hasIntelligence) {
+    return 'Production-ready';
+  }
+
+  if (hasCli && hasSync) {
+    return 'Functional prototype';
+  }
+
+  return 'Early development';
+}
+
+function generateAiSummary(state) {
+  const language = state.tech_stack.language || 'Project';
+  const hasServer = state.key_features.some((feature) => feature.includes('Express server'));
+  const hasSync = state.key_features.some((feature) => feature.includes('GitHub sync'));
+  const clauses = ['tracks meaningful project evolution', 'generates structured AI-readable context'];
+
+  if (hasServer) {
+    clauses.push('serves project context locally through Express');
+  }
+
+  if (hasSync) {
+    clauses.push('can publish public AI-readable context through optional GitHub sync');
+  }
+
+  return `AI-powered ${language} CLI that ${clauses.join(', ')}.`;
+}
+
+function generateNextSteps(state) {
+  const nextSteps = [];
+
+  if (state.key_features.length === 0) {
+    nextSteps.push('Define core features for the AI context workflow.');
+  }
+
+  if (state.known_issues.includes('No automated test suite is detected yet.')) {
+    nextSteps.push('Add automated tests for the state engine, watcher, and GitHub sync flows.');
+  }
+
+  if (state.current_stage === 'Early development') {
+    nextSteps.push('Implement the next core workflow milestone and document how AI should use it.');
+  }
+
+  if (state.current_stage === 'Functional prototype') {
+    nextSteps.push('Harden the current feature set with tests and release validation.');
+  }
+
+  if (!state.tech_stack.framework) {
+    nextSteps.push('Document the intended framework or extend stack detection for this project.');
+  }
+
+  if (state.recent_updates.length === 0) {
+    nextSteps.push('Capture the first meaningful project milestone to seed AI context history.');
+  }
+
+  return Array.from(new Set(nextSteps)).slice(0, 4);
 }
 
 function createDebouncedStateUpdater(projectRoot, options) {
@@ -331,9 +938,12 @@ module.exports = {
   detectProjectMetadata,
   ensureContextDirectory,
   getContextPaths,
+  interpretChange,
   loadRuntimeConfig,
   readJsonFile,
   renderTemplate,
+  scoreEvent,
+  shouldIgnoreProjectFile,
   updateRuntimeConfig,
   updateProjectState,
   writeJsonAtomic,

package/core/watcher.js

@@ -7,6 +7,8 @@ const { syncContextToGit } = require('./gitSync');
 const {
   createDebouncedStateUpdater,
   loadRuntimeConfig,
+  scoreEvent,
+  shouldIgnoreProjectFile,
   updateProjectState
 } = require('./stateManager');
 
@@ -18,8 +20,7 @@ async function startWatcher(projectRoot, options) {
   const settings = Object.assign({ logger: null }, options);
   const logger = settings.logger;
   const config = await loadRuntimeConfig(projectRoot);
-  const syncCallback = async () =>
-    syncContextToGit(projectRoot, config.gitSync, logger);
+  const syncCallback = async () => syncContextToGit(projectRoot, config.gitSync, logger);
   const debouncedUpdater = createDebouncedStateUpdater(projectRoot, {
     debounceMs: config.debounceMs,
     logger,
@@ -27,11 +28,10 @@ async function startWatcher(projectRoot, options) {
   });
 
   const watcher = chokidar.watch(projectRoot, {
-    ignored: [
-      /(^|[\\/])\.git([\\/]|$)/,
-      /(^|[\\/])node_modules([\\/]|$)/,
-      /(^|[\\/])\.ai-context([\\/]|$)/
-    ],
+    ignored(filePath) {
+      const normalizedPath = normalizeFilePath(projectRoot, filePath);
+      return shouldIgnoreProjectFile(normalizedPath);
+    },
     ignoreInitial: true,
     persistent: true
   });
@@ -39,12 +39,12 @@ async function startWatcher(projectRoot, options) {
   function handleEvent(action, filePath) {
     const normalizedPath = normalizeFilePath(projectRoot, filePath);
 
-    if (!normalizedPath || normalizedPath.startsWith('.ai-context/')) {
+    if (!normalizedPath || shouldIgnoreProjectFile(normalizedPath) || scoreEvent(normalizedPath) < 2) {
       return;
     }
 
     if (logger) {
-      logger.info(`${action} ${normalizedPath}`);
+      logger.debug(`Queued meaningful ${action} for ${normalizedPath}`);
     }
 
     debouncedUpdater.enqueue({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aibridge-context",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Zero-config CLI and library for generating AI-readable project context, serving it locally, and syncing it with git.",
   "main": "./index.js",
   "bin": {

package/server/server.js

@@ -22,10 +22,6 @@ async function startServer(options) {
     instance.on('error', reject);
   });
 
-  if (settings.logger) {
-    settings.logger.info(`AI context server is running on http://localhost:${settings.port}`);
-  }
-
   return {
     app,
     server,

package/templates/state.template.json

@@ -2,11 +2,16 @@
   "project": "",
   "version": "",
   "last_updated": "1970-01-01T00:00:00.000Z",
-  "stats": {
-    "files_changed": 0,
-    "last_file": ""
+  "ai_summary": "",
+  "tech_stack": {
+    "language": "",
+    "framework": "",
+    "runtime": "",
+    "package_manager": ""
   },
+  "current_stage": "",
   "recent_updates": [],
-  "features": [],
+  "key_features": [],
+  "known_issues": [],
   "next_steps": []
 }