@chappibunny/repolens 1.8.0 → 1.8.2

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.8.2
+
+### 🐛 Bug Fixes
+
+- **Uninstall crash fixed**: `repolens uninstall` crashed with `Cannot read properties of undefined (reading 'trim')` when run via `npx`. The readline prompt used the callback-based `node:readline` API incorrectly with `await`. Fixed by wrapping in a proper Promise with null guard.
+
+### ✨ AI Auto-Detection
+
+- **GITHUB_TOKEN auto-enables AI**: `demo`, `publish`, and `init` commands now detect `GITHUB_TOKEN` in the environment and automatically enable AI-enhanced docs via GitHub Models (free). No manual configuration needed.
+- **Workflow template enables AI by default**: The generated `.github/workflows/repolens.yml` now has `REPOLENS_AI_ENABLED`, `REPOLENS_AI_PROVIDER`, and `GITHUB_TOKEN` enabled (not commented out) since GitHub Models is free.
+- **Init auto-configures AI**: Non-interactive `repolens init` writes `ai.enabled: true` and `ai.provider: github` to `.repolens.yml` when `GITHUB_TOKEN` is detected.
+- **Better AI messaging**: Demo and publish commands show prominent status about AI mode (enabled/deterministic) with specific guidance on what AI adds.
+- **Sharper deterministic upsell**: All 6 fallback document types now explain exactly what AI adds (e.g., "adds plain-language explanations, strategic recommendations, and risk assessments") and mention `GITHUB_TOKEN` auto-detection.
+
+### 📖 Documentation
+
+- **Scoped package name everywhere**: All user-facing docs now use `npx @chappibunny/repolens` instead of bare `repolens`. Added warning about the squatted `repolens@0.0.1` placeholder package on npm.
+- Updated: README.md (commands table + warning), TROUBLESHOOTING.md, MIGRATION.md (6 instances), KNOWN_ISSUES.md (2 instances), bug report template.
+
+## 1.8.1
+
+### 📖 Documentation Refresh
+
+- **README overhaul**: Updated test badge (379 passing), version reference (v1.8.1), document count (15 types), expanded audience table to include all 15 documents (GraphQL Schema, TypeScript Type Graph, Dependency Graph, Architecture Drift), added `uninstall` and `uninstall --force` to commands table.
+- **DEVELOPMENT.md**: Updated test coverage (379 across 22 files), expanded test suite description to cover all test categories, fixed tarball version in install example.
+- **CLI version test**: Now reads version from `package.json` dynamically instead of hardcoding — won't break on future version bumps.
+
 ## 1.8.0
 
 ### ✨ GitHub Models — First-Class AI Provider
@@ -11,6 +38,7 @@ All notable changes to RepoLens will be documented in this file.
 - **Config-driven AI settings**: `ai.enabled`, `ai.provider`, `ai.model`, `ai.temperature`, and `ai.base_url` in `.repolens.yml` are now fully respected at runtime (env vars still take precedence). Previously these config values were ignored.
 - **Init wizard fixes**: Provider selection now uses correct runtime values (`github`, `openai_compatible`, `anthropic`, `google`) instead of mismatched labels. The wizard now emits `ai.provider` to the generated YAML. Added `github_wiki` to publisher choices.
 - **Demo AI upsell**: `repolens demo` now shows a hint about GitHub Models (free) when AI is not enabled, guiding users to `repolens init --interactive`.
+- **Uninstall command**: `repolens uninstall` removes all RepoLens-generated files (`.repolens/`, `.repolens.yml`, workflow, `.env.example`, `README.repolens.md`) with confirmation prompt and `--force` flag.
 - **Doctor validation**: `repolens doctor` now checks for `GITHUB_TOKEN` when provider is `github`, and `REPOLENS_AI_API_KEY` for other providers.
 
 ### 📖 Documentation
@@ -21,8 +49,8 @@ All notable changes to RepoLens will be documented in this file.
 
 ### 🧪 Tests
 
-- 24 new tests: provider config fallbacks, `isAIEnabled` with config, `getAIConfig` with config, GitHub Models defaults, init wizard content, doctor env validation
-- **374 tests passing** across 22 test files
+- 29 new tests: provider config fallbacks, `isAIEnabled` with config, `getAIConfig` with config, GitHub Models defaults, init wizard content, doctor env validation, uninstall command (5 scenarios)
+- **379 tests passing** across 22 test files
 
 ## 1.7.1
 

package/README.md

@@ -10,14 +10,14 @@
 
 [![npm version](https://img.shields.io/npm/v/@chappibunny/repolens)](https://www.npmjs.com/package/@chappibunny/repolens)
 [![VS Code Extension](https://img.shields.io/visual-studio-marketplace/v/CHAPIBUNNY.repolens-architecture?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=CHAPIBUNNY.repolens-architecture)
-[![Tests](https://img.shields.io/badge/tests-185%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
+[![Tests](https://img.shields.io/badge/tests-379%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
 **Your architecture docs are already outdated.** RepoLens fixes that.
 
 RepoLens scans your repository, generates living architecture documentation, and publishes it to Notion, Confluence, GitHub Wiki, or Markdown — automatically on every push. Engineers get technical docs. Stakeholders get readable system overviews. Nobody writes a word.
 
-> Stable as of v1.0 — [API guarantees](STABILITY.md) · [Security hardened](SECURITY.md) · v1.5.0
+> Stable as of v1.0 — [API guarantees](STABILITY.md) · [Security hardened](SECURITY.md) · v1.8.1
 
 ---
 
@@ -75,13 +75,13 @@ Run `npx @chappibunny/repolens migrate` to automatically update your workflow fi
 
 ## 📋 What It Generates
 
-**11 document types** for three audiences — no manual writing required:
+**15 document types** for three audiences — no manual writing required:
 
 | Audience | Documents |
 |---|---|
 | **Stakeholders** (founders, PMs, ops) | Executive Summary · Business Domains · Data Flows |
-| **Everyone** | System Overview · Developer Onboarding · Change Impact |
-| **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map |
+| **Everyone** | System Overview · Developer Onboarding · Change Impact · Architecture Drift |
+| **Engineers** | Architecture Overview · Module Catalog · API Surface · Route Map · System Map · GraphQL Schema · TypeScript Type Graph · Dependency Graph |
 
 **Two modes:** Deterministic (free, fast, always works) or AI-Enhanced (optional — GitHub Models, OpenAI, Anthropic, Google, Azure, Ollama).
 
@@ -148,14 +148,19 @@ Step-by-step setup for publishers, AI features, Notion, Confluence, GitHub Wiki,
 
 | Command | Description |
 |---|---|
-| `repolens init` | Scaffold config + GitHub Actions workflow |
-| `repolens init --interactive` | Step-by-step configuration wizard |
-| `repolens publish` | Scan, generate, and publish documentation |
-| `repolens demo` | Quick local preview — no API keys needed |
-| `repolens doctor` | Validate your setup |
-| `repolens watch` | Auto-regenerate docs on file changes |
-| `repolens migrate` | Upgrade from v0.3.0 workflows ([details](MIGRATION.md)) |
-| `repolens feedback` | Send feedback to the team |
+| `npx @chappibunny/repolens init` | Scaffold config + GitHub Actions workflow |
+| `npx @chappibunny/repolens init --interactive` | Step-by-step configuration wizard |
+| `npx @chappibunny/repolens publish` | Scan, generate, and publish documentation |
+| `npx @chappibunny/repolens demo` | Quick local preview — no API keys needed |
+| `npx @chappibunny/repolens doctor` | Validate your setup |
+| `npx @chappibunny/repolens watch` | Auto-regenerate docs on file changes |
+| `npx @chappibunny/repolens migrate` | Upgrade from v0.3.0 workflows ([details](MIGRATION.md)) |
+| `npx @chappibunny/repolens uninstall` | Remove all RepoLens files (config, docs, workflow) |
+| `npx @chappibunny/repolens uninstall --force` | Remove without confirmation prompt |
+| `npx @chappibunny/repolens feedback` | Send feedback to the team |
+
+> **Note:** If you installed globally with `npm install -g @chappibunny/repolens`, you can use the shorter `repolens <command>` form.
+> **Warning:** Do not run bare `npx repolens` — there is an unrelated `repolens@0.0.1` placeholder package on npm. Always use the scoped name `@chappibunny/repolens`.
 
 ---
 
@@ -237,7 +242,7 @@ When you open a pull request, RepoLens posts:
 | [Configuration](CONFIGURATION.md) | Complete `.repolens.yml` schema and examples |
 | [Environment Variables](ENVIRONMENT.md) | All env vars by publisher and feature |
 | [Architecture](ARCHITECTURE.md) | Pipeline diagram, project structure |
-| [Development](DEVELOPMENT.md) | Setup, tests (185 across 15 files), release process |
+| [Development](DEVELOPMENT.md) | Setup, tests (379 across 22 files), release process |
 | [Security](SECURITY.md) | Threat model, secret detection, validation layers |
 | [Telemetry](TELEMETRY.md) | Opt-in privacy-first usage analytics |
 | [Troubleshooting](TROUBLESHOOTING.md) | Common issues and fixes |
@@ -253,7 +258,7 @@ When you open a pull request, RepoLens posts:
 - **Report issues**: Share bugs, edge cases, or UX friction
 - **Request features**: Tell us what's missing
 - **Build plugins**: Extend RepoLens with custom renderers and publishers
-- **Share feedback**: `repolens feedback`
+- **Share feedback**: `npx @chappibunny/repolens feedback`
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chappibunny/repolens",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "AI-assisted documentation intelligence system for technical and non-technical audiences",
   "license": "MIT",
   "type": "module",

package/src/ai/generate-sections.js

@@ -245,7 +245,7 @@ The codebase follows ${context.patterns.length > 0 ? context.patterns.join(", ")
 
 ---
 
-*This summary is generated deterministically from repository structure. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language insights tailored to non-technical readers.*`;
+*This summary was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI-enhanced summaries via GitHub Models (free) \u2014 adds plain-language explanations for non-technical readers, strategic recommendations, and risk assessments.*`;
 
   return output;
 }
@@ -353,7 +353,7 @@ ${context.domains.slice(0, 5).map((d, i) => `| ${i + 1} | ${d.name} | ${d.fileCo
 
   output += `---
 
-*This overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for richer contextual explanations.*`;
+*This overview was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds narrative context, architectural rationale, and technology trade-off analysis.*`;
 
   return output;
 }
@@ -412,7 +412,7 @@ function getFallbackBusinessDomains(context, enrichment = {}) {
     output += "\n";
   }
   
-  output += `---\n\n*Domain mapping is based on directory naming conventions. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language descriptions aimed at non-technical stakeholders.*`;
+  output += `---\n\n*Domain mapping is based on directory naming conventions. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds business-language descriptions, stakeholder impact analysis, and cross-domain relationship narratives.*`;
   
   return output;
 }
@@ -533,7 +533,7 @@ The repository comprises **${context.project.filesScanned} files** organized int
 
   output += `---
 
-*This architecture overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for deeper architectural narratives.*`;
+*This architecture overview was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds architectural narratives, design rationale, scalability analysis, and refactoring recommendations.*`;
 
   return output;
 }
@@ -559,7 +559,7 @@ function getFallbackDataFlows(flows, context, enrichment = {}) {
 
   if (allFlows.length === 0) {
     output += `No data flows were detected. This typically means the system uses straightforward request–response patterns without distinct multi-step pipelines.\n\n`;
-    output += `---\n\n*Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for heuristic-based flow descriptions.*`;
+    output += `---\n\n*Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 AI can infer data flows from import patterns even when heuristics find none.*`;
     return output;
   }
 
@@ -603,7 +603,7 @@ function getFallbackDataFlows(flows, context, enrichment = {}) {
     }
   }
   
-  output += `---\n\n*Flow detection is based on naming conventions and import patterns. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language flow narratives.*`;
+  output += `---\n\n*Flow detection is based on naming conventions and import patterns. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds end-to-end flow narratives, failure mode analysis, and data transformation descriptions.*`;
   
   return output;
 }
@@ -715,7 +715,7 @@ ${context.topModules.slice(0, 10).map(m => `| \`${m.key}\` | ${m.fileCount} | ${
 
   output += `\n\n---
 
-*This onboarding guide is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for a narrative-style guide with tips and common pitfalls.*`;
+*This onboarding guide was generated from repository structure analysis. Set \`GITHUB_TOKEN\` to auto-enable AI via GitHub Models (free) \u2014 adds narrative walkthroughs, common pitfalls, debugging tips, and contribution guidelines.*`;
 
   return output;
 }

package/src/cli.js

@@ -145,6 +145,7 @@ Commands:
   publish     Scan, render, and publish documentation
   demo        Generate local docs without API keys (quick preview)
   watch       Watch for file changes and regenerate docs
+  uninstall   Remove all RepoLens-generated files from your repository
   feedback    Send feedback to the RepoLens team
   version     Print the current RepoLens version
 
@@ -169,6 +170,8 @@ Examples:
   repolens publish --config /path/.repolens.yml # Explicit config path
   repolens demo                                  # Quick local preview (no API keys)
   repolens watch                                # Watch mode (Markdown only)
+  repolens uninstall                             # Remove all RepoLens files
+  repolens uninstall --target /tmp/my-repo       # Uninstall from specific repo
   repolens --version
 `);
 }
@@ -335,6 +338,14 @@ async function main() {
       process.exit(EXIT_VALIDATION);
     }
 
+    // Auto-detect GITHUB_TOKEN and enable AI with GitHub Models (free)
+    if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true" && process.env.GITHUB_TOKEN) {
+      info("✨ GITHUB_TOKEN detected — enabling AI-enhanced docs via GitHub Models (free)");
+      cfg.ai = { enabled: true, provider: "github" };
+      process.env.REPOLENS_AI_ENABLED = "true";
+      process.env.REPOLENS_AI_PROVIDER = "github";
+    }
+
     // Load plugins
     let pluginManager;
     try {
@@ -469,6 +480,22 @@ async function main() {
       };
     }
     
+    // Auto-detect GITHUB_TOKEN and enable AI with GitHub Models (free)
+    const aiAlreadyConfigured = cfg.ai?.enabled || process.env.REPOLENS_AI_ENABLED === "true";
+    let aiAutoEnabled = false;
+    if (!aiAlreadyConfigured && process.env.GITHUB_TOKEN) {
+      info("\n✨ GITHUB_TOKEN detected — enabling AI-enhanced docs via GitHub Models (free)");
+      cfg.ai = { enabled: true, provider: "github" };
+      process.env.REPOLENS_AI_ENABLED = "true";
+      process.env.REPOLENS_AI_PROVIDER = "github";
+      aiAutoEnabled = true;
+    } else if (aiAlreadyConfigured) {
+      info("\n🤖 AI-enhanced documentation enabled");
+    } else {
+      info("\n📄 Running in deterministic mode (no GITHUB_TOKEN detected)");
+      info("   Set GITHUB_TOKEN to auto-enable free AI-enhanced docs via GitHub Models");
+    }
+    
     try {
       info("Scanning repository...");
       const scanTimer = startTimer("scan");
@@ -492,10 +519,24 @@ async function main() {
       info("Browse your docs: open the .repolens/ directory");
       info("\nTo publish to Notion, Confluence, or GitHub Wiki, run: repolens publish");
       
-      // Upsell AI enhancement when not already enabled
-      if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true") {
-        info("\n💡 Want richer, AI-enhanced docs? Run: repolens init --interactive");
-        info("   Select GitHub Models (free) — uses your existing GITHUB_TOKEN, no extra keys needed.");
+      if (aiAutoEnabled) {
+        info("\n🤖 AI-enhanced docs were generated using GitHub Models (free tier)");
+        info("   To keep AI enabled permanently, run: repolens init --interactive");
+      } else if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true") {
+        info("\n─────────────────────────────────────────────────────────────────");
+        info("💡 Your docs are missing AI-enhanced sections:");
+        info("   • Executive Summary — plain language overview for leadership");
+        info("   • Business Domains — what the system does for stakeholders");
+        info("   • Architecture Overview — deeper narrative for architects");
+        info("   • Data Flows — how information moves through your system");
+        info("   • Developer Onboarding — getting started guide for new hires");
+        info("");
+        info("   To enable for FREE with GitHub Models:");
+        info("     export GITHUB_TOKEN=<your-token>");
+        info("     repolens demo");
+        info("");
+        info("   Or run: repolens init --interactive → select GitHub Models");
+        info("─────────────────────────────────────────────────────────────────");
       }
       
       printPerformanceSummary();
@@ -521,6 +562,98 @@ async function main() {
     return;
   }
 
+  if (command === "uninstall") {
+    await printBanner();
+    
+    const targetDir = getArg("--target") || process.cwd();
+    const forceFlag = process.argv.includes("--force");
+    
+    info("Scanning for RepoLens files...\n");
+    
+    // All files/directories that RepoLens creates
+    const candidates = [
+      { path: path.join(targetDir, ".repolens"),                    type: "dir",  label: ".repolens/",                     source: "demo/publish" },
+      { path: path.join(targetDir, ".repolens.yml"),                type: "file", label: ".repolens.yml",                  source: "init" },
+      { path: path.join(targetDir, ".github", "workflows", "repolens.yml"), type: "file", label: ".github/workflows/repolens.yml", source: "init" },
+      { path: path.join(targetDir, ".env.example"),                 type: "file", label: ".env.example",                   source: "init" },
+      { path: path.join(targetDir, "README.repolens.md"),           type: "file", label: "README.repolens.md",             source: "init" },
+    ];
+    
+    // Check which files exist
+    const found = [];
+    for (const item of candidates) {
+      try {
+        const stat = await fs.stat(item.path);
+        if ((item.type === "dir" && stat.isDirectory()) || (item.type === "file" && stat.isFile())) {
+          found.push(item);
+        }
+      } catch {
+        // File doesn't exist — skip
+      }
+    }
+    
+    if (found.length === 0) {
+      info("No RepoLens files found. Nothing to remove.");
+      await closeTelemetry();
+      return;
+    }
+    
+    info("Found the following RepoLens files:\n");
+    for (const item of found) {
+      const icon = item.type === "dir" ? "📁" : "📄";
+      info(`  ${icon} ${item.label}  (created by ${item.source})`);
+    }
+    
+    // Confirm unless --force
+    if (!forceFlag) {
+      const isCI = process.env.CI || process.env.GITHUB_ACTIONS;
+      const isTest = process.env.NODE_ENV === "test" || process.env.VITEST;
+      
+      if (isCI || isTest) {
+        info("\nCI/test environment detected — skipping confirmation (use --force to suppress this message).");
+      } else {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const answer = await new Promise((resolve) => {
+          rl.question(`\nRemove ${found.length} item${found.length === 1 ? "" : "s"}? This cannot be undone. (y/N): `, resolve);
+        });
+        rl.close();
+        
+        if (!answer || answer.trim().toLowerCase() !== "y") {
+          info("Uninstall cancelled.");
+          await closeTelemetry();
+          return;
+        }
+      }
+    }
+    
+    // Remove files
+    let removed = 0;
+    for (const item of found) {
+      try {
+        if (item.type === "dir") {
+          await fs.rm(item.path, { recursive: true, force: true });
+        } else {
+          await fs.unlink(item.path);
+        }
+        info(`  ✓ Removed ${item.label}`);
+        removed++;
+      } catch (err) {
+        error(`  ✗ Failed to remove ${item.label}: ${err.message}`);
+      }
+    }
+    
+    info(`\n✓ Removed ${removed}/${found.length} RepoLens file${found.length === 1 ? "" : "s"}.`);
+    
+    if (removed > 0) {
+      info("\nTo reinstall, run: repolens init");
+      info("To uninstall the npm package: npm uninstall @chappibunny/repolens");
+    }
+    
+    trackUsage("uninstall", "success", { removed, total: found.length });
+    await closeTelemetry();
+    return;
+  }
+
   if (command === "feedback") {
     await printBanner();
     info("Send feedback to the RepoLens team");
@@ -567,7 +700,7 @@ async function main() {
   }
 
   error(`Unknown command: ${command}`);
-  error("Available commands: init, doctor, migrate, publish, demo, watch, feedback, version, help");
+  error("Available commands: init, doctor, migrate, publish, demo, watch, uninstall, feedback, version, help");
   process.exit(EXIT_ERROR);
 }
 

package/src/init.js

@@ -89,10 +89,10 @@ jobs:
           CONFLUENCE_API_TOKEN: \${{ secrets.CONFLUENCE_API_TOKEN }}
           CONFLUENCE_SPACE_KEY: \${{ secrets.CONFLUENCE_SPACE_KEY }}
           CONFLUENCE_PARENT_PAGE_ID: \${{ secrets.CONFLUENCE_PARENT_PAGE_ID }}
-          # Uncomment to enable free AI-enhanced docs via GitHub Models:
-          # REPOLENS_AI_ENABLED: true
-          # REPOLENS_AI_PROVIDER: github
-          # GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          # AI-enhanced docs via GitHub Models (free)
+          REPOLENS_AI_ENABLED: true
+          REPOLENS_AI_PROVIDER: github
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
         run: npx @chappibunny/repolens@latest publish
 `;
 
@@ -324,9 +324,10 @@ function buildIgnorePatterns() {
   ];
 }
 
-function buildRepoLensConfig(projectName, detectedRoots) {
+function buildRepoLensConfig(projectName, detectedRoots, options = {}) {
   const includePatterns = buildIncludePatterns(detectedRoots);
   const ignorePatterns = buildIgnorePatterns();
+  const enableAI = options.enableAI || false;
 
   const lines = [
     `configVersion: 1`,
@@ -358,10 +359,35 @@ function buildRepoLensConfig(projectName, detectedRoots) {
     `#   owner: "your-username"`,
     `#   repo: "your-repo-name"`,
     ``,
-    `scan:`,
-    `  include:`
   ];
 
+  // AI configuration
+  if (enableAI) {
+    lines.push(`# AI-enhanced documentation (auto-detected GITHUB_TOKEN)`);
+    lines.push(`ai:`);
+    lines.push(`  enabled: true`);
+    lines.push(`  provider: github`);
+    lines.push(``);
+    lines.push(`features:`);
+    lines.push(`  executive_summary: true`);
+    lines.push(`  business_domains: true`);
+    lines.push(`  architecture_overview: true`);
+    lines.push(`  data_flows: true`);
+    lines.push(`  developer_onboarding: true`);
+    lines.push(`  change_impact: true`);
+    lines.push(``);
+  } else {
+    lines.push(`# AI-enhanced documentation (free via GitHub Models)`);
+    lines.push(`# Uncomment to enable — or set GITHUB_TOKEN and it auto-activates:`);
+    lines.push(`# ai:`);
+    lines.push(`#   enabled: true`);
+    lines.push(`#   provider: github`);
+    lines.push(``);
+  }
+
+  lines.push(`scan:`);
+  lines.push(`  include:`);
+
   if (includePatterns.length) {
     for (const pattern of includePatterns) {
       lines.push(`    - "${pattern}"`);
@@ -725,9 +751,12 @@ export async function runInit(targetDir = process.cwd(), options = {}) {
 
   const projectName = wizardAnswers?.projectName || detectProjectName(repoRoot);
   const detectedRoots = wizardAnswers ? [] : await detectRepoStructure(repoRoot);
+
+  // Auto-detect GITHUB_TOKEN for AI enablement
+  const hasGitHubToken = !!process.env.GITHUB_TOKEN;
   const configContent = wizardAnswers
     ? buildWizardConfig(wizardAnswers)
-    : buildRepoLensConfig(projectName, detectedRoots);
+    : buildRepoLensConfig(projectName, detectedRoots, { enableAI: hasGitHubToken });
 
   info(`Detected project name: ${projectName}`);
 
@@ -786,8 +815,11 @@ NOTION_VERSION=2022-06-28
   }
 
   info("\n✨ RepoLens initialization complete!\n");
-  
-  if (notionCredentials) {
+    if (hasGitHubToken && !wizardAnswers) {
+    info("🤖 Detected GITHUB_TOKEN — AI-enhanced docs enabled via GitHub Models (free)");
+    info("   Your workflow and config are pre-configured. No extra setup needed.\n");
+  }
+    if (notionCredentials) {
     info("🎉 Notion publishing is ready!");
     info("   Your credentials are stored in .env (gitignored)\n");
     info("Next steps:");
@@ -812,16 +844,18 @@ NOTION_VERSION=2022-06-28
     info("  2. To enable Notion publishing:");
     info("     - Copy .env.example to .env and add your credentials, OR");
     info("     - Add GitHub secrets: NOTION_TOKEN, NOTION_PARENT_PAGE_ID");
-    info("  3. (Optional) Enable AI features:");
-    info("     ── FREE: GitHub Models (recommended for GitHub Actions) ──");
-    info("     REPOLENS_AI_ENABLED=true");
-    info("     REPOLENS_AI_PROVIDER=github");
-    info("     (Uses your GITHUB_TOKEN automatically — no API key signup needed)");
-    info("     ── Or: OpenAI / Anthropic / Google ──");
-    info("     REPOLENS_AI_ENABLED=true");
-    info("     REPOLENS_AI_API_KEY=sk-...");
-    info("     See: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");
-    info("  4. Run 'npx @chappibunny/repolens publish' to test locally");
-    info("  5. Commit the generated files");
+    if (!hasGitHubToken) {
+      info("  3. (Optional) Enable AI features:");
+      info("     \u2500\u2500 FREE: GitHub Models (recommended for GitHub Actions) \u2500\u2500");
+      info("     REPOLENS_AI_ENABLED=true");
+      info("     REPOLENS_AI_PROVIDER=github");
+      info("     (Uses your GITHUB_TOKEN automatically \u2014 no API key signup needed)");
+      info("     \u2500\u2500 Or: OpenAI / Anthropic / Google \u2500\u2500");
+      info("     REPOLENS_AI_ENABLED=true");
+      info("     REPOLENS_AI_API_KEY=sk-...");
+      info("     See: https://github.com/CHAPIBUNNY/repolens/blob/main/AI.md");
+    }
+    info(`  ${hasGitHubToken ? "3" : "4"}. Run 'npx @chappibunny/repolens publish' to test locally`);
+    info(`  ${hasGitHubToken ? "4" : "5"}. Commit the generated files`);
   }
 }