@chappibunny/repolens 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 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

package/README.md

@@ -148,16 +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 uninstall` | Remove all RepoLens files (config, docs, workflow) |
-| `repolens uninstall --force` | Remove without confirmation prompt |
-| `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`.
 
 ---
 
@@ -255,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.1",
+  "version": "1.9.0",
   "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

@@ -21,7 +21,7 @@ import { upsertPrComment } from "./delivery/comment.js";
 import { runInit } from "./init.js";
 import { runMigrate } from "./migrate.js";
 import { runWatch } from "./watch.js";
-import { info, error, warn } from "./utils/logger.js";
+import { info, error, warn, fmt } from "./utils/logger.js";
 import { formatError } from "./utils/errors.js";
 import { checkForUpdates } from "./utils/update-check.js";
 import { generateDocumentSet } from "./docs/generate-doc-set.js";
@@ -338,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 {
@@ -472,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");
@@ -495,10 +519,26 @@ 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 ${fmt.boldGreen("GitHub Models (FREE)")}`);
+        info("   To keep AI enabled permanently, run: repolens init --interactive");
+      } else if (!cfg.ai?.enabled && process.env.REPOLENS_AI_ENABLED !== "true") {
+        info(`\n${fmt.cyan("┌──────────────────────────────────────────────────────────────────┐")}`);
+        info(`${fmt.cyan("│")} ${fmt.boldYellow("✨ Unlock AI-Enhanced Documentation")}                             ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("├──────────────────────────────────────────────────────────────────┤")}`);
+        info(`${fmt.cyan("│")} Your docs are missing these AI-powered sections:                ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Executive Summary — plain language overview for leadership   ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Business Domains — what the system does for stakeholders    ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Architecture Overview — deeper narrative for architects     ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Data Flows — how information moves through your system      ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.yellow("•")} Developer Onboarding — getting started guide for new hires  ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}                                                                  ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")} ${fmt.boldGreen("🆓 Enable for FREE with GitHub Models:")}                          ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.green("export GITHUB_TOKEN=<your-token>")}                            ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}   ${fmt.green("repolens demo")}                                               ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")}                                                                  ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("│")} Or run: ${fmt.brightCyan("repolens init --interactive")} → select GitHub Models      ${fmt.cyan("│")}`);
+        info(`${fmt.cyan("└──────────────────────────────────────────────────────────────────┘")}`);
       }
       
       printPerformanceSummary();
@@ -575,10 +615,12 @@ async function main() {
         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 rl.question(`\nRemove ${found.length} item${found.length === 1 ? "" : "s"}? This cannot be undone. (y/N): `);
+        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.trim().toLowerCase() !== "y") {
+        if (!answer || answer.trim().toLowerCase() !== "y") {
           info("Uninstall cancelled.");
           await closeTelemetry();
           return;

package/src/core/scan.js

@@ -136,7 +136,70 @@ function routePathFromFile(file) {
   return file;
 }
 
-async function extractRepoMetadata(repoRoot) {
+/**
+ * Detect languages from file extensions
+ */
+function detectLanguagesFromFiles(files) {
+  const languages = new Set();
+  
+  // Extension to language mapping
+  const extensionMap = {
+    // JavaScript/TypeScript
+    ".js": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".jsx": "JavaScript",
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    // Python
+    ".py": "Python",
+    ".pyw": "Python",
+    ".pyi": "Python",
+    // Go
+    ".go": "Go",
+    // Rust
+    ".rs": "Rust",
+    // Java
+    ".java": "Java",
+    // C/C++
+    ".c": "C",
+    ".h": "C",
+    ".cpp": "C++",
+    ".hpp": "C++",
+    ".cc": "C++",
+    ".cxx": "C++",
+    // C#
+    ".cs": "C#",
+    // Ruby
+    ".rb": "Ruby",
+    // PHP
+    ".php": "PHP",
+    // Swift
+    ".swift": "Swift",
+    // Kotlin
+    ".kt": "Kotlin",
+    ".kts": "Kotlin",
+    // Scala
+    ".scala": "Scala",
+    // Shell
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    // SQL
+    ".sql": "SQL",
+  };
+
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    if (extensionMap[ext]) {
+      languages.add(extensionMap[ext]);
+    }
+  }
+
+  return languages;
+}
+
+async function extractRepoMetadata(repoRoot, files = []) {
   const metadata = {
     hasPackageJson: false,
     frameworks: [],
@@ -191,12 +254,9 @@ async function extractRepoMetadata(repoRoot) {
     if (allDeps["swc"] || allDeps["@swc/core"]) metadata.buildTools.push("SWC");
     if (allDeps["parcel"]) metadata.buildTools.push("Parcel");
 
-    // Detect languages
+    // Detect TypeScript from dependencies (supplements file detection)
     if (allDeps["typescript"]) metadata.languages.add("TypeScript");
 
-    // Infer JavaScript if package.json exists (any npm project uses JS/Node)
-    metadata.languages.add("JavaScript");
-
     // Detect Node.js runtime indicators
     const hasNodeEngines = pkg.engines && pkg.engines.node;
     const hasBin = pkg.bin != null;
@@ -210,6 +270,82 @@ async function extractRepoMetadata(repoRoot) {
     // No package.json or invalid JSON
   }
 
+  // Detect Python frameworks and tools
+  try {
+    // Check for pyproject.toml (modern Python)
+    const pyprojectPath = path.join(repoRoot, "pyproject.toml");
+    const pyprojectContent = await fs.readFile(pyprojectPath, "utf8");
+    metadata.languages.add("Python");
+    
+    // Detect Python frameworks from pyproject.toml
+    if (/django/i.test(pyprojectContent)) metadata.frameworks.push("Django");
+    if (/fastapi/i.test(pyprojectContent)) metadata.frameworks.push("FastAPI");
+    if (/flask/i.test(pyprojectContent)) metadata.frameworks.push("Flask");
+    if (/pytest/i.test(pyprojectContent)) metadata.testFrameworks.push("pytest");
+    if (/poetry/i.test(pyprojectContent)) metadata.buildTools.push("Poetry");
+  } catch {
+    // No pyproject.toml
+  }
+
+  try {
+    // Check for requirements.txt
+    const reqPath = path.join(repoRoot, "requirements.txt");
+    const reqContent = await fs.readFile(reqPath, "utf8");
+    metadata.languages.add("Python");
+    
+    if (/django/i.test(reqContent)) metadata.frameworks.push("Django");
+    if (/fastapi/i.test(reqContent)) metadata.frameworks.push("FastAPI");
+    if (/flask/i.test(reqContent)) metadata.frameworks.push("Flask");
+    if (/pytest/i.test(reqContent)) metadata.testFrameworks.push("pytest");
+  } catch {
+    // No requirements.txt
+  }
+
+  try {
+    // Check for setup.py (legacy Python)
+    await fs.access(path.join(repoRoot, "setup.py"));
+    metadata.languages.add("Python");
+  } catch {
+    // No setup.py
+  }
+
+  // Detect Go modules
+  try {
+    const goModPath = path.join(repoRoot, "go.mod");
+    const goModContent = await fs.readFile(goModPath, "utf8");
+    metadata.languages.add("Go");
+    
+    if (/gin-gonic/i.test(goModContent)) metadata.frameworks.push("Gin");
+    if (/echo/i.test(goModContent)) metadata.frameworks.push("Echo");
+    if (/fiber/i.test(goModContent)) metadata.frameworks.push("Fiber");
+  } catch {
+    // No go.mod
+  }
+
+  // Detect Rust via Cargo.toml
+  try {
+    const cargoPath = path.join(repoRoot, "Cargo.toml");
+    const cargoContent = await fs.readFile(cargoPath, "utf8");
+    metadata.languages.add("Rust");
+    
+    if (/actix/i.test(cargoContent)) metadata.frameworks.push("Actix");
+    if (/rocket/i.test(cargoContent)) metadata.frameworks.push("Rocket");
+    if (/tokio/i.test(cargoContent)) metadata.frameworks.push("Tokio");
+  } catch {
+    // No Cargo.toml
+  }
+
+  // Merge languages detected from file extensions
+  const fileLanguages = detectLanguagesFromFiles(files);
+  for (const lang of fileLanguages) {
+    metadata.languages.add(lang);
+  }
+
+  // De-duplicate frameworks (in case detected from multiple sources)
+  metadata.frameworks = [...new Set(metadata.frameworks)];
+  metadata.testFrameworks = [...new Set(metadata.testFrameworks)];
+  metadata.buildTools = [...new Set(metadata.buildTools)];
+
   return metadata;
 }
 
@@ -435,8 +571,8 @@ export async function scanRepo(cfg) {
     }
   }
 
-  // Extract repository metadata
-  const metadata = await extractRepoMetadata(repoRoot);
+  // Extract repository metadata (pass files for language detection)
+  const metadata = await extractRepoMetadata(repoRoot, files);
 
   // Detect external API integrations
   const externalApis = await detectExternalApis(files, repoRoot);

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`);
   }
 }

package/src/utils/logger.js

@@ -3,6 +3,53 @@ import { sanitizeSecrets } from "./secrets.js";
 const isVerbose = process.argv.includes("--verbose");
 const isTest = process.env.NODE_ENV === "test";
 
+// Terminal color support detection
+const supportsColor = !process.env.NO_COLOR && 
+  (process.env.FORCE_COLOR || 
+   (process.stdout.isTTY && process.env.TERM !== "dumb"));
+
+// ANSI color codes
+const colors = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  cyan: "\x1b[36m",
+  magenta: "\x1b[35m",
+  brightGreen: "\x1b[92m",
+  brightCyan: "\x1b[96m",
+  brightYellow: "\x1b[93m",
+};
+
+/**
+ * Apply color formatting to text (respects NO_COLOR)
+ */
+export function colorize(text, ...styles) {
+  if (!supportsColor) return text;
+  const codes = styles.map(s => colors[s] || "").join("");
+  return `${codes}${text}${colors.reset}`;
+}
+
+/**
+ * Shorthand color helpers
+ */
+export const fmt = {
+  bold: (text) => colorize(text, "bold"),
+  green: (text) => colorize(text, "green"),
+  brightGreen: (text) => colorize(text, "brightGreen"),
+  cyan: (text) => colorize(text, "cyan"),
+  brightCyan: (text) => colorize(text, "brightCyan"),
+  yellow: (text) => colorize(text, "yellow"),
+  brightYellow: (text) => colorize(text, "brightYellow"),
+  magenta: (text) => colorize(text, "magenta"),
+  dim: (text) => colorize(text, "dim"),
+  // Combined styles
+  boldGreen: (text) => colorize(text, "bold", "brightGreen"),
+  boldCyan: (text) => colorize(text, "bold", "brightCyan"),
+  boldYellow: (text) => colorize(text, "bold", "brightYellow"),
+};
+
 /**
  * Sanitize arguments for logging
  */