fix: improve tech detection accuracy and add code examples to ARCHITECTURE.md

- Fix false positives in framework detection by removing regex-based file path matching
  for Express, React, Flask (they now use dependency-based detection via deps.ts)
- Add detectFrameworksFromDeps() and mergeFrameworksFromDeps() to accurately detect
  frameworks from package.json/requirements.txt/Cargo.toml dependencies
- Add support for code examples in ARCHITECTURE.md via codeExamples array
- Update agent prompt to request 2-4 code examples with explanations
- Add CodeExampleSchema to Zod validation
- Fix edge cases in generator output (empty arrays causing broken markdown tables)
- Add comprehensive tests for new framework detection functions
- Update configPatterns to include more frameworks detected via config files
  (Astro, Remix, SvelteKit, Vite, Webpack, etc.)

Tests: 205 passing

Author: Arthur742Ramos

src/agent.ts

@@ -128,6 +128,7 @@ Return a JSON object with this exact structure. Include "sources" arrays citing
     "components": [{"name": "", "description": "", "directory": ""}],
     "dataFlow": "",
     "keyAbstractions": [{"name": "", "description": ""}],
+    "codeExamples": [{"title": "", "file": "", "code": "", "explanation": ""}],
     "sources": []
   },
   "firstTasks": [
@@ -155,6 +156,7 @@ Target audience: ${options.audience}
 
 Provide at least 8-10 first tasks of varying difficulty. Be specific about file paths.
 Set runbook.applicable = false for libraries/tools that aren't deployed as services.
+Include 2-4 codeExamples showing key patterns/usage (short snippets of 5-15 lines with explanations).
 
 REMEMBER: Limit tool calls. After reading key files, produce output immediately. Don't over-research.`;
 }

src/generator.ts

@@ -195,6 +195,49 @@ export function generateArchitecture(facts: RepoFacts): string {
     ?.map((a) => `- **${a.name}**: ${a.description}`)
     .join("\n") || "_None documented_";
 
+  // Generate code examples section
+  let codeExamplesSection = "";
+  if (facts.architecture.codeExamples && facts.architecture.codeExamples.length > 0) {
+    const examples = facts.architecture.codeExamples
+      .map((ex) => {
+        // Detect language from file extension
+        const ext = ex.file.split('.').pop() || '';
+        const langMap: Record<string, string> = {
+          ts: "typescript",
+          tsx: "typescript",
+          js: "javascript",
+          jsx: "javascript",
+          py: "python",
+          go: "go",
+          rs: "rust",
+          java: "java",
+          rb: "ruby",
+          php: "php",
+          cs: "csharp",
+          cpp: "cpp",
+          c: "c",
+        };
+        const lang = langMap[ext] || ext;
+        
+        return `### ${ex.title}
+
+**File:** \`${ex.file}\`
+
+\`\`\`${lang}
+${ex.code}
+\`\`\`
+
+${ex.explanation}`;
+      })
+      .join("\n\n");
+    
+    codeExamplesSection = `## Code Examples
+
+${examples}
+
+`;
+  }
+
   // Generate Mermaid diagram
   const mermaidDiagram = generateMermaidDiagram(facts);
 
@@ -215,7 +258,7 @@ ${mermaidDiagram}
 
 ${components}
 
-## Data Flow
+${codeExamplesSection}## Data Flow
 
 ${facts.architecture.dataFlow || "_Data flow not documented_"}
 
@@ -227,7 +270,9 @@ ${abstractions}
 
 | Path | Type | Description |
 |------|------|-------------|
-${facts.structure.entrypoints.map((e) => `| \`${e.path}\` | ${e.type} | ${e.description || "-"} |`).join("\n")}
+${facts.structure.entrypoints.length > 0
+  ? facts.structure.entrypoints.map((e) => `| \`${e.path}\` | ${e.type} | ${e.description || "-"} |`).join("\n")
+  : "| _None detected_ | - | - |"}
 
 ## Where to Change What
 
@@ -305,13 +350,17 @@ ${dirs}
 
 | Directory | Purpose |
 |-----------|---------|
-${facts.structure.testDirs.map((d) => `| \`${d}\` | Test files |`).join("\n")}
+${facts.structure.testDirs.length > 0 
+  ? facts.structure.testDirs.map((d) => `| \`${d}\` | Test files |`).join("\n")
+  : "| _None detected_ | - |"}
 
 ## CI/CD
 
 | Workflow | Triggers |
 |----------|----------|
-${facts.ci.workflows.map((w) => `| \`${w.file}\` | ${w.triggers.join(", ")} |`).join("\n")}
+${facts.ci.workflows.length > 0
+  ? facts.ci.workflows.map((w) => `| \`${w.file}\` | ${w.triggers.join(", ") || "-"} |`).join("\n")
+  : "| _None detected_ | - |"}
 
 ## Reading Order for New Contributors
 

src/index.ts

@@ -19,7 +19,7 @@ import chalk from "chalk";
 import { mkdir, writeFile, rm, readFile } from "fs/promises";
 import { join, basename } from "path";
 
-import { parseGitHubUrl, cloneRepo, scanRepo } from "./ingest.js";
+import { parseGitHubUrl, cloneRepo, scanRepo, mergeFrameworksFromDeps } from "./ingest.js";
 import { analyzeRepo, AnalysisStats } from "./agent.js";
 import { ProgressTracker } from "./progress.js";
 import { extractDependencies, generateDependencyDocs } from "./deps.js";
@@ -186,6 +186,15 @@ async function run(repoUrl: string, options: BootcampOptions): Promise<void> {
     // Extract dependencies
     const deps = await extractDependencies(repoPath);
 
+    // Merge frameworks detected from dependencies into stack info
+    if (deps) {
+      const allDepNames = [
+        ...deps.runtime.map(d => d.name),
+        ...deps.dev.map(d => d.name),
+      ];
+      mergeFrameworksFromDeps(scanResult.stack, allDepNames);
+    }
+    
     // Analyze security (read package.json for deps check)
     let packageJson: Record<string, unknown> | undefined;
     try {

src/ingest.ts

@@ -172,16 +172,25 @@ function detectStack(files: FileInfo[]): StackInfo {
   }
 
   // Framework/build system detection from config files
+  // NOTE: Frameworks like React, Express, Flask are NOT detected by file path patterns
+  // as that causes false positives. They should be detected via dependency analysis (deps.ts).
+  // Only config files that definitively indicate framework usage are listed here.
   const configPatterns: Record<string, { file: RegExp | string; type: "framework" | "build" | "pm" }> = {
     "Next.js": { file: "next.config.js", type: "framework" },
     "Next.js (mjs)": { file: "next.config.mjs", type: "framework" },
-    React: { file: /react/, type: "framework" },
+    "Next.js (ts)": { file: "next.config.ts", type: "framework" },
     Vue: { file: "vue.config.js", type: "framework" },
+    "Nuxt.js": { file: "nuxt.config.js", type: "framework" },
+    "Nuxt.js (ts)": { file: "nuxt.config.ts", type: "framework" },
     Angular: { file: "angular.json", type: "framework" },
-    Express: { file: /express/, type: "framework" },
     Django: { file: "manage.py", type: "framework" },
-    Flask: { file: /flask/, type: "framework" },
     Rails: { file: "Gemfile", type: "framework" },
+    Astro: { file: "astro.config.mjs", type: "framework" },
+    "Astro (ts)": { file: "astro.config.ts", type: "framework" },
+    Remix: { file: "remix.config.js", type: "framework" },
+    SvelteKit: { file: "svelte.config.js", type: "framework" },
+    Vite: { file: "vite.config.ts", type: "build" },
+    "Vite (js)": { file: "vite.config.js", type: "build" },
     npm: { file: "package-lock.json", type: "pm" },
     yarn: { file: "yarn.lock", type: "pm" },
     pnpm: { file: "pnpm-lock.yaml", type: "pm" },
@@ -191,6 +200,7 @@ function detectStack(files: FileInfo[]): StackInfo {
     cargo: { file: "Cargo.toml", type: "build" },
     maven: { file: "pom.xml", type: "build" },
     gradle: { file: "build.gradle", type: "build" },
+    "gradle (kts)": { file: "build.gradle.kts", type: "build" },
     make: { file: "Makefile", type: "build" },
     Lake: { file: "lakefile.toml", type: "build" },
     "Lake (lean)": { file: "lakefile.lean", type: "build" },
@@ -200,6 +210,10 @@ function detectStack(files: FileInfo[]): StackInfo {
     sbt: { file: "build.sbt", type: "build" },
     CMake: { file: "CMakeLists.txt", type: "build" },
     zig: { file: "build.zig", type: "build" },
+    Webpack: { file: "webpack.config.js", type: "build" },
+    Rollup: { file: "rollup.config.js", type: "build" },
+    esbuild: { file: "esbuild.config.js", type: "build" },
+    tsup: { file: "tsup.config.ts", type: "build" },
   };
 
   for (const [name, { file, type }] of Object.entries(configPatterns)) {
@@ -209,12 +223,14 @@ function detectStack(files: FileInfo[]): StackInfo {
         : filePaths.some((p) => file.test(p));
 
     if (matches) {
-      if (type === "framework" && !stack.frameworks.includes(name.replace(" (mjs)", ""))) {
-        stack.frameworks.push(name.replace(" (mjs)", ""));
+      // Normalize framework names by removing variant suffixes like (mjs), (ts), etc.
+      const normalizedName = name.replace(/\s*\([^)]+\)$/, "");
+      if (type === "framework" && !stack.frameworks.includes(normalizedName)) {
+        stack.frameworks.push(normalizedName);
       } else if (type === "build" && !stack.buildSystem) {
-        stack.buildSystem = name;
+        stack.buildSystem = normalizedName;
       } else if (type === "pm" && !stack.packageManager) {
-        stack.packageManager = name;
+        stack.packageManager = normalizedName;
       }
     }
   }
@@ -541,3 +557,96 @@ export function listFilesByPattern(files: FileInfo[], pattern: string): string[]
   const regex = new RegExp(`^${regexPattern}$`);
   return files.filter((f) => !f.isDirectory && regex.test(f.path)).map((f) => f.path);
 }
+
+/**
+ * Known frameworks that can be detected from dependencies
+ * Maps dependency name to display name
+ */
+const DEPENDENCY_FRAMEWORKS: Record<string, string> = {
+  // JavaScript/TypeScript frameworks
+  "react": "React",
+  "react-dom": "React",
+  "vue": "Vue",
+  "angular": "Angular",
+  "@angular/core": "Angular",
+  "svelte": "Svelte",
+  "solid-js": "Solid",
+  "preact": "Preact",
+  "express": "Express",
+  "fastify": "Fastify",
+  "hono": "Hono",
+  "koa": "Koa",
+  "hapi": "Hapi",
+  "@hapi/hapi": "Hapi",
+  "nest": "NestJS",
+  "@nestjs/core": "NestJS",
+  "next": "Next.js",
+  "gatsby": "Gatsby",
+  "nuxt": "Nuxt.js",
+  "remix": "Remix",
+  "@remix-run/node": "Remix",
+  "astro": "Astro",
+  "electron": "Electron",
+  // Python frameworks
+  "flask": "Flask",
+  "django": "Django",
+  "fastapi": "FastAPI",
+  "tornado": "Tornado",
+  "pyramid": "Pyramid",
+  "bottle": "Bottle",
+  // Go frameworks (from go.mod require)
+  "github.com/gin-gonic/gin": "Gin",
+  "github.com/gorilla/mux": "Gorilla Mux",
+  "github.com/labstack/echo": "Echo",
+  "github.com/gofiber/fiber": "Fiber",
+  // Ruby frameworks
+  "rails": "Rails",
+  "sinatra": "Sinatra",
+  // Rust frameworks
+  "actix-web": "Actix Web",
+  "rocket": "Rocket",
+  "axum": "Axum",
+};
+
+/**
+ * Detect frameworks from dependency list
+ * This is more accurate than file path matching
+ */
+export function detectFrameworksFromDeps(depNames: string[]): string[] {
+  const frameworks = new Set<string>();
+  
+  for (const dep of depNames) {
+    const normalized = dep.toLowerCase();
+    if (DEPENDENCY_FRAMEWORKS[normalized]) {
+      frameworks.add(DEPENDENCY_FRAMEWORKS[normalized]);
+    }
+    // Also check the full dep name (for Go modules, etc.)
+    if (DEPENDENCY_FRAMEWORKS[dep]) {
+      frameworks.add(DEPENDENCY_FRAMEWORKS[dep]);
+    }
+  }
+  
+  return Array.from(frameworks);
+}
+
+/**
+ * Merge frameworks detected from dependencies into stack info
+ * Should be called after extractDependencies() in the main flow
+ */
+export function mergeFrameworksFromDeps(
+  stack: StackInfo,
+  depNames: string[]
+): StackInfo {
+  const depFrameworks = detectFrameworksFromDeps(depNames);
+  const existingNormalized = new Set(
+    stack.frameworks.map(f => f.toLowerCase())
+  );
+  
+  for (const framework of depFrameworks) {
+    if (!existingNormalized.has(framework.toLowerCase())) {
+      stack.frameworks.push(framework);
+    }
+  }
+  
+  return stack;
+}

src/schema.ts

@@ -97,12 +97,21 @@ const KeyAbstractionSchema = z.object({
   description: z.string(),
 });
 
+// Code example schema
+const CodeExampleSchema = z.object({
+  title: z.string(),
+  file: z.string(),
+  code: z.string(),
+  explanation: z.string(),
+});
+
 // Architecture schema
 const ArchitectureSchema = z.object({
   overview: z.string().default(""),
   components: z.array(ComponentSchema).default([]),
   dataFlow: z.string().optional(),
   keyAbstractions: z.array(KeyAbstractionSchema).optional(),
+  codeExamples: z.array(CodeExampleSchema).optional(),
   sources: z.array(z.string()).optional(),
 });
 

src/types.ts

@@ -189,6 +189,7 @@ export interface RepoFacts {
     components: { name: string; description: string; directory: string }[];
     dataFlow?: string;
     keyAbstractions?: { name: string; description: string }[];
+    codeExamples?: { title: string; file: string; code: string; explanation: string }[];
     sources?: string[];
   };
   firstTasks: FirstTask[];