@chappibunny/repolens 0.8.0 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,60 @@
 
 All notable changes to RepoLens will be documented in this file.
 
+## 1.0.0
+
+### 🎉 Stable Release
+
+RepoLens v1.0.0 marks the first stable release with a frozen public API. All CLI commands, configuration schema, and plugin interfaces are now covered by semantic versioning guarantees. See [STABILITY.md](STABILITY.md) for the full contract.
+
+### 🐛 Bug Fixes
+- **Doctor false-success**: `repolens doctor` now correctly exits with code 2 when `runDoctor()` reports failures (previously always printed "validation passed")
+- **Feedback exit code**: `repolens feedback` now exits with code 1 when feedback fails to send (previously exited 0)
+- **Unknown flags**: `repolens --unknown-flag` now prints an error instead of silently running publish
+- **scan.ignore security bypass**: Security validator now checks `scan.ignore` patterns (was incorrectly checking non-existent `scan.exclude`)
+- **Domains type mismatch**: Both validators now expect `domains` as an object (was array in security validator, object in schema validator)
+- **Plugin publisher crash isolation**: Plugin publisher errors are now caught and logged instead of crashing the pipeline
+
+### ✅ Config Stability
+- `configVersion: 1` is now **required** (was optional in schema validator)
+- Added `confluence` config section validation (branches array)
+- Added `ai.temperature` range validation (0–2)
+- Added `ai.max_tokens` range validation (>0)
+- AI config values from `.repolens.yml` are now used as fallbacks when env vars are not set
+
+### 🔧 Improvements
+- Standardized exit codes: `EXIT_SUCCESS=0`, `EXIT_ERROR=1`, `EXIT_VALIDATION=2` as named constants
+- Replaced all `console.log`/`console.warn` in production code with logger utilities
+- Removed stale "v0.4.0" references from CLI help text and migrate command
+- Sentry DSN moved to `REPOLENS_SENTRY_DSN` env var (with backwards-compatible default)
+- Hardcoded email in `init` scaffolding replaced with `your-email@example.com` placeholder
+
+### 📄 Documentation
+- Added [STABILITY.md](STABILITY.md): Complete public API contract (CLI, config schema, plugin interface, exit codes, env vars)
+
+## 0.9.0
+
+### ✨ New Features
+- **Plugin System** (`src/plugins/`): Extensible architecture for custom renderers and publishers
+  - `loader.js`: Resolves and imports plugins from local paths or npm packages
+  - `manager.js`: `PluginManager` class — registry, getters, and lifecycle hook runner
+  - Plugin interface: `register()` → `{ name, version, renderers, publishers, hooks }`
+  - **Custom Renderers**: Plugins can register new document types with `render(context)` functions
+  - **Custom Publishers**: Plugins can register new output targets with `publish(cfg, renderedPages)` functions
+  - **Lifecycle Hooks**: `afterScan`, `afterRender`, `afterPublish` — transform data or trigger side effects
+  - Hooks run in plugin load order; errors are caught per-plugin without breaking the pipeline
+  - Config: `plugins: ["./my-plugin.js", "@org/repolens-plugin-foo"]` in `.repolens.yml`
+  - Config schema updated: `plugins` array validated, custom publisher names accepted
+
+### 🧪 Tests
+- Added 21 new plugin tests + 21 publisher parser tests (163 tests across 14 files)
+
+### 🔧 Output Quality
+- **Notion Publisher**: Full table support (table blocks with `table_row` children), blockquote → callout, dividers, numbered lists, h3 headings, inline rich text (`**bold**`, `*italic*`, `` `code` ``)
+- **Confluence Publisher**: Rewritten as line-by-line parser — proper `<table>` HTML output, blockquotes → info panels, merged `<ul>`/`<ol>` lists, fixed code block HTML entity escaping bug
+- **Renderers**: Tables replace bullet-point lists across all 8 renderers, descriptive prose, removed ASCII banner art
+- **Fallback Generators**: All 6 deterministic fallbacks rewritten with tables, descriptive paragraphs, and module descriptions
+
 ## 0.8.0
 
 ### ✨ New Features

package/README.md

@@ -8,7 +8,7 @@
                         Repository Intelligence CLI
 ```
 
-[![Tests](https://img.shields.io/badge/tests-90%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
+[![Tests](https://img.shields.io/badge/tests-163%20passing-brightgreen)](https://github.com/CHAPIBUNNY/repolens/actions)
 [![Security](https://img.shields.io/badge/security-hardened-blue)](SECURITY.md)
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)](SECURITY.md)
 [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -16,11 +16,11 @@
 
 AI-assisted documentation intelligence system that generates architecture docs for engineers AND readable system docs for stakeholders
 
-**Current Status**: v0.8.0 — Extended Analysis
+**Current Status**: v1.0.0 — Stable Release
 
 RepoLens automatically generates and maintains living architecture documentation by analyzing your repository structure, extracting meaningful insights from your package.json, and creating visual dependency graphs. Run it once, or let it auto-update on every push.
 
-⚠️ **Early Access Notice**: The CLI commands and configuration format may evolve until v1.0. We will provide migration guides for any breaking changes. v1.0 will guarantee stable CLI behavior and config schema.
+The CLI, configuration schema, and plugin interface are **stable** as of v1.0. See [STABILITY.md](STABILITY.md) for the full API contract and semver guarantees.
 
 ---
 
@@ -49,7 +49,7 @@ For Confluence:
 ```bash
 # Edit .env and add:
 CONFLUENCE_URL=https://your-company.atlassian.net/wiki
-CONFLUENCE_EMAIL=trades@rabitaitrades.com
+CONFLUENCE_EMAIL=your-email@example.com
 CONFLUENCE_API_TOKEN=your-token
 CONFLUENCE_SPACE_KEY=DOCS
 ```
@@ -137,6 +137,8 @@ RepoLens automatically detects:
 ✅ **TypeScript Type Graph** - Map interfaces, classes, and type relationships (NEW in v0.8.0)  
 ✅ **Dependency Graph** - Import analysis with circular dependency detection (NEW in v0.8.0)  
 ✅ **Architecture Drift** - Track structural changes against a baseline (NEW in v0.8.0)  
+✅ **Plugin System** - Extend with custom renderers, publishers, and hooks (NEW in v0.9.0)  
+✅ **Stable API** - CLI, config, and plugin interface frozen with semver guarantees (v1.0.0)  
 
 ---
 
@@ -228,7 +230,7 @@ npm link
 Install from a specific version:
 
 ```bash
-npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v0.8.0/chappibunny-repolens-0.8.0.tgz
+npm install https://github.com/CHAPIBUNNY/repolens/releases/download/v1.0.0/chappibunny-repolens-1.0.0.tgz
 ```
 </details>
 
@@ -318,7 +320,7 @@ Maximum visibility: Notion for async collaboration, Confluence for enterprise do
 **3.1: Choose an AI Provider**
 
 RepoLens works with any OpenAI-compatible API:
-- **OpenAI** (gpt-4-turbo-preview, gpt-3.5-turbo)
+- **OpenAI** (gpt-5-mini, gpt-5.4, gpt-5-nano)
 - **Anthropic Claude** (via API gateway)
 - **Azure OpenAI** (enterprise deployments)
 - **Local Models** (Ollama, LM Studio, etc.)
@@ -333,7 +335,7 @@ REPOLENS_AI_API_KEY=sk-xxxxxxxxxxxxx
 
 # Optional: Customize provider
 REPOLENS_AI_BASE_URL=https://api.openai.com/v1
-REPOLENS_AI_MODEL=gpt-4-turbo-preview
+REPOLENS_AI_MODEL=gpt-5-mini
 REPOLENS_AI_TEMPERATURE=0.3
 REPOLENS_AI_MAX_TOKENS=2000
 ```
@@ -356,7 +358,7 @@ features:
   change_impact: true        # Architecture diff with context
 ```
 
-**Cost Estimates** (with gpt-4-turbo-preview):
+**Cost Estimates** (with gpt-5-mini):
 - Small repo (<50 files): $0.10-$0.30 per run
 - Medium repo (50-200 files): $0.30-$0.80 per run
 - Large repo (200+ files): $0.80-$2.00 per run
@@ -428,7 +430,7 @@ If using the Confluence publisher:
 Create `.env` in your project root:
 ```bash
 CONFLUENCE_URL=https://your-company.atlassian.net/wiki
-CONFLUENCE_EMAIL=trades@rabitaitrades.com
+CONFLUENCE_EMAIL=your-email@example.com
 CONFLUENCE_API_TOKEN=your-api-token-here
 CONFLUENCE_SPACE_KEY=DOCS
 CONFLUENCE_PARENT_PAGE_ID=123456789  # Optional
@@ -449,7 +451,7 @@ Add as repository secrets:
 2. Click **"New repository secret"**
 3. Add:
    - Name: `CONFLUENCE_URL`, Value: `https://your-company.atlassian.net/wiki`
-   - Name: `CONFLUENCE_EMAIL`, Value: `trades@rabitaitrades.com`
+   - Name: `CONFLUENCE_EMAIL`, Value: `your-email@example.com`
    - Name: `CONFLUENCE_API_TOKEN`, Value: `your-token`
    - Name: `CONFLUENCE_SPACE_KEY`, Value: `DOCS`
    - Name: `CONFLUENCE_PARENT_PAGE_ID`, Value: `123456789` (optional)
@@ -939,10 +941,11 @@ features:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `configVersion` | number | No | Schema version (current: 1) for future migrations |
+| `configVersion` | number | **Yes** | Schema version (must be `1`) |
 | `project.name` | string | Yes | Project name |
 | `project.docs_title_prefix` | string | No | Prefix for documentation titles (default: project name) |
-| `publishers` | array | Yes | Output targets: `notion`, `confluence`, `markdown` |
+| `publishers` | array | Yes | Output targets: `notion`, `confluence`, `markdown` (+ plugin publishers) |
+| `plugins` | array | No | Plugin paths or npm package names |
 | `notion.branches` | array | No | Branch whitelist for Notion publishing. Supports globs. |
 | `notion.includeBranchInTitle` | boolean | No | Add `[branch-name]` to titles (default: `true`) |
 | `confluence.branches` | array | No | Branch whitelist for Confluence publishing. Supports globs. |
@@ -956,7 +959,11 @@ features:
 | `scan.ignore` | array | Yes | Glob patterns to exclude |
 | `module_roots` | array | No | Root directories for module detection |
 | `outputs.pages` | array | Yes | Documentation pages to generate |
-| `features` | object | No | Experimental feature flags |
+| `features` | object | No | Feature flags (boolean values) |
+| `ai.enabled` | boolean | No | Enable AI-powered documentation |
+| `ai.mode` | string | No | AI mode: `hybrid`, `full`, or `off` |
+| `ai.temperature` | number | No | Generation temperature (0\u20132) |
+| `ai.max_tokens` | number | No | Max tokens per request (>0) |
 
 ---
 
@@ -1070,7 +1077,7 @@ npm test
 - Integration workflows
 - Doctor command validation
 
-**Coverage:** 90 tests passing across 11 test files
+**Coverage:** 163 tests passing across 14 test files
 
 ### Test Package Installation Locally
 
@@ -1081,7 +1088,7 @@ Simulates the full user installation experience:
 npm pack
 
 # Install globally from tarball
-npm install -g chappibunny-repolens-0.8.0.tgz
+npm install -g chappibunny-repolens-1.0.0.tgz
 
 # Verify
 repolens --version
@@ -1135,6 +1142,9 @@ repolens/
 │   │   └── discord.js       # Discord webhook notifications
 │   ├── delivery/
 │   │   └── comment.js       # PR comment delivery
+│   ├── plugins/
+│   │   ├── loader.js        # Plugin resolution and dynamic import
+│   │   └── manager.js       # Plugin registry and lifecycle orchestration
 │   └── utils/
 │       ├── logger.js        # Logging utilities
 │       ├── retry.js         # API retry logic (exponential backoff)
@@ -1146,10 +1156,11 @@ repolens/
 │       ├── telemetry.js     # Opt-in error tracking + performance timers
 │       ├── errors.js        # Enhanced error messages with guidance
 │       └── update-check.js  # Version update notifications
-├── tests/                   # Vitest test suite (121 tests across 12 files)
+├── tests/                   # Vitest test suite (163 tests across 14 files)
 ├── .repolens.yml            # Dogfooding config
 ├── package.json
 ├── CHANGELOG.md
+├── STABILITY.md
 ├── RELEASE.md
 └── ROADMAP.md
 ```
@@ -1163,13 +1174,13 @@ RepoLens uses automated GitHub Actions releases.
 ### Creating a Release
 
 ```bash
-# Patch version (0.8.0 → 0.8.1) - Bug fixes
+# Patch version (1.0.0 → 1.0.1) - Bug fixes
 npm run release:patch
 
-# Minor version (0.8.0 → 0.9.0) - New features
+# Minor version (1.0.0 → 1.1.0) - New features
 npm run release:minor
 
-# Major version (0.8.0 → 1.0.0) - Breaking changes
+# Major version (1.0.0 → 2.0.0) - Breaking changes
 npm run release:major
 
 # Push the tag to trigger workflow
@@ -1189,24 +1200,23 @@ See [RELEASE.md](./RELEASE.md) for detailed workflow.
 
 ## 🤝 Contributing
 
-RepoLens is currently in early access. v1.0 will open for community contributions.
-
 **Ways to help:**
 - **Try it out**: Install and use in your projects
 - **Report issues**: Share bugs, edge cases, or UX friction
 - **Request features**: Tell us what's missing
-- **Share feedback**: What works? What doesn't?
+- **Build plugins**: Extend RepoLens with custom renderers and publishers
+- **Share feedback**: `repolens feedback`
 
 ---
 
-## 🗺️ Roadmap to v1.0
+## 🗺️ Roadmap
 
-**Current Status:** v0.8.0 — Extended Analysis
+**Current Status:** v1.0.0 — Stable Release
 
-### Completed ✅
+### v1.0 — Complete ✅
 
 - [x] CLI commands: `init`, `doctor`, `publish`, `migrate`, `watch`, `feedback`, `version`, `help`
-- [x] Config schema v1 with validation
+- [x] Config schema v1 with validation (frozen)
 - [x] Auto-discovery of `.repolens.yml`
 - [x] Publishers: Notion + Confluence + Markdown
 - [x] Branch-aware publishing with filtering
@@ -1217,7 +1227,7 @@ RepoLens is currently in early access. v1.0 will open for community contribution
 - [x] GitHub Actions automation (publish + release)
 - [x] PR architecture diff comments
 - [x] Performance guardrails (10k warning, 50k limit)
-- [x] Comprehensive test suite (121 tests across 12 files)
+- [x] Comprehensive test suite (163 tests across 14 files)
 - [x] Security hardening (secret detection, injection prevention, fuzzing)
 - [x] Discord notifications with rich embeds
 - [x] Documentation coverage & health scoring
@@ -1234,11 +1244,15 @@ RepoLens is currently in early access. v1.0 will open for community contribution
 - [x] TypeScript type graph analysis (interfaces, classes, relationships)
 - [x] Dependency graph with circular dependency detection
 - [x] Architecture drift detection (baseline comparison)
+- [x] Plugin system for custom renderers and publishers
+- [x] Stability audit: CLI, config schema, and plugin interface frozen
+- [x] [STABILITY.md](STABILITY.md): Public API contract with semver guarantees
 
-### Planned for v1.0 🎯
+### Future
 
-- [ ] Plugin system for custom renderers
 - [ ] Additional publishers (GitHub Wiki, Obsidian)
+- [ ] VS Code extension
+- [ ] GitHub App
 
 See [ROADMAP.md](./ROADMAP.md) for detailed planning.
 

package/RELEASE.md

@@ -22,7 +22,7 @@ RepoLens uses semantic versioning:
 8. Push branch and tag: `git push --follow-tags`
 9. GitHub Actions `release.yml` runs automatically:
    - Security audit (dependency + secrets scanning)
-   - Test suite (90 tests)
+   - Test suite (163 tests)
    - Create GitHub Release with tarball
    - Publish to npm (`npm publish --access public`)
 10. Verify on npm: `npm view @chappibunny/repolens version`

package/package.json

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

package/src/ai/generate-sections.js

@@ -145,127 +145,251 @@ export async function generateDeveloperOnboarding(context) {
 // Fallback generators (deterministic, no AI)
 
 function getFallbackExecutiveSummary(context) {
+  const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose";
+  const languageList = context.techStack.languages.join(", ") || "multiple languages";
+  const domainSummary = context.domains.slice(0, 5).map(d => d.name).join(", ");
+
   return `# Executive Summary
 
-## What this system does
+## What This System Does
+
+${context.project.name} is a ${frameworkList} application built with ${languageList}. The codebase contains **${context.project.modulesDetected} modules** spread across **${context.project.filesScanned} files**, organized into ${context.domains.length} functional domain${context.domains.length === 1 ? "" : "s"}.
 
-${context.project.name} is a ${context.techStack.frameworks.join(", ") || "software"} application with ${context.project.modulesDetected} modules across ${context.project.filesScanned} files.
+${context.project.apiRoutesDetected > 0 ? `The system exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}** and` : "It"} serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}** to end users.
 
-## Main system areas
+## Primary Functional Areas
 
-The codebase is organized into ${context.domains.length} main domains:
+The application is organized around the following business domains:
 
-${context.domains.map(d => `- ${d.name}: ${d.moduleCount} modules`).join("\n")}
+| Domain | Modules | Description |
+|--------|---------|-------------|
+${context.domains.map(d => `| ${d.name} | ${d.moduleCount} | ${d.description || "—"} |`).join("\n")}
 
-## Technology stack
+## Technology Profile
 
-- Frameworks: ${context.techStack.frameworks.join(", ") || "Not detected"}
-- Languages: ${context.techStack.languages.join(", ") || "Not detected"}
-- Build tools: ${context.techStack.buildTools.join(", ") || "Not detected"}
+| Category | Details |
+|----------|---------|
+| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
 
-## Key observations
+## Key Observations
 
-- ${context.project.pagesDetected} pages detected
-- ${context.project.apiRoutesDetected} API routes detected
-- Architecture patterns: ${context.patterns.join(", ") || "Standard patterns"}
+The codebase follows ${context.patterns.length > 0 ? context.patterns.join(", ") : "standard"} architectural patterns. ${domainSummary ? `The core functional areas — ${domainSummary} — account for the majority of the application logic.` : ""}
 
-Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+---
+
+*This summary is generated deterministically from repository structure. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for natural language insights tailored to non-technical readers.*`;
 }
 
 function getFallbackSystemOverview(context) {
+  const sizeLabel = context.project.modulesDetected > 50 ? "large-scale" :
+                    context.project.modulesDetected > 20 ? "medium-sized" : "focused";
+
   return `# System Overview
 
-## Repository snapshot
+## Repository Snapshot
+
+This is a ${sizeLabel} codebase organized into **${context.project.modulesDetected} modules** across **${context.project.filesScanned} files**.
+
+| Metric | Value |
+|--------|-------|
+| Files scanned | ${context.project.filesScanned} |
+| Modules | ${context.project.modulesDetected} |
+| Application pages | ${context.project.pagesDetected} |
+| API endpoints | ${context.project.apiRoutesDetected} |
+
+## Detected Patterns
 
-- Files scanned: ${context.project.filesScanned}
-- Modules: ${context.project.modulesDetected}
-- Pages: ${context.project.pagesDetected}
-- APIs: ${context.project.apiRoutesDetected}
+${context.patterns.length > 0 ? context.patterns.map(p => `- ${p}`).join("\n") : "No specific architectural patterns were detected. This typically means the project uses a straightforward directory-based organization."}
 
-## Technology patterns
+## Dominant Domains
 
-${context.patterns.map(p => `- ${p}`).join("\n")}
+The following domains represent the largest areas of the codebase by file count:
 
-## Dominant domains
+| Rank | Domain | Files |
+|------|--------|-------|
+${context.domains.slice(0, 5).map((d, i) => `| ${i + 1} | ${d.name} | ${d.fileCount} |`).join("\n")}
 
-${context.domains.slice(0, 5).map((d, i) => `${i + 1}. ${d.name} (${d.fileCount} files)`).join("\n")}
+---
 
-Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+*This overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for richer contextual explanations.*`;
 }
 
 function getFallbackBusinessDomains(context) {
   let output = `# Business Domains\n\n`;
+  output += `> This document maps the codebase into business-oriented functional areas. Each domain represents a distinct area of responsibility.\n\n`;
+  output += `**Total domains identified:** ${context.domains.length}\n\n`;
+  output += `---\n\n`;
   
   for (const domain of context.domains) {
-    output += `## Domain: ${domain.name}\n\n`;
-    output += `${domain.description}\n\n`;
-    output += `Modules: ${domain.moduleCount}\n`;
-    output += `Files: ${domain.fileCount}\n\n`;
-    output += `Main modules:\n`;
-    output += domain.topModules.slice(0, 5).map(m => `- ${m}`).join("\n");
-    output += `\n\n`;
+    output += `## ${domain.name}\n\n`;
+    output += `${domain.description || "This domain covers a distinct functional area of the application."}\n\n`;
+    output += `| Metric | Value |\n`;
+    output += `|--------|-------|\n`;
+    output += `| Modules | ${domain.moduleCount} |\n`;
+    output += `| Files | ${domain.fileCount} |\n\n`;
+    if (domain.topModules?.length > 0) {
+      output += `**Key modules:** ${domain.topModules.slice(0, 5).map(m => `\`${m}\``).join(", ")}\n\n`;
+    }
   }
   
-  output += `Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+  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.*`;
   
   return output;
 }
 
 function getFallbackArchitectureOverview(context) {
+  const patternDesc = context.patterns.length > 0
+    ? `The detected architectural patterns are **${context.patterns.join(", ")}**. These patterns shape how data and control flow through the system.`
+    : "No specific architectural patterns were detected. The project appears to follow a straightforward directory-based organization.";
+
   return `# Architecture Overview
 
-## Architecture style
+## Architectural Style
+
+${patternDesc}
+
+## System Layers
 
-Based on detected patterns: ${context.patterns.join(", ")}
+The codebase is organized into ${context.domains.length} functional layers, each encapsulating a distinct area of responsibility:
 
-## Key layers
+| Layer | Description |
+|-------|-------------|
+${context.domains.slice(0, 8).map(d => `| **${d.name}** | ${d.description || "Handles a distinct functional concern"} |`).join("\n")}
 
-${context.domains.slice(0, 5).map(d => `- ${d.name}: ${d.description}`).join("\n")}
+## Technology Stack
 
-## Technology stack
+| Category | Technologies |
+|----------|-------------|
+| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
 
-- Frameworks: ${context.techStack.frameworks.join(", ")}
-- Languages: ${context.techStack.languages.join(", ")}
-- Build tools: ${context.techStack.buildTools.join(", ")}
+## Scale & Complexity
 
-Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+The repository comprises **${context.project.filesScanned} files** organized into **${context.project.modulesDetected} modules**. ${context.project.apiRoutesDetected > 0 ? `It exposes **${context.project.apiRoutesDetected} API endpoint${context.project.apiRoutesDetected === 1 ? "" : "s"}** and` : "It"} serves **${context.project.pagesDetected} application page${context.project.pagesDetected === 1 ? "" : "s"}**.
+
+---
+
+*This architecture overview is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for deeper architectural narratives.*`;
 }
 
 function getFallbackDataFlows(flows) {
   let output = `# Data Flows\n\n`;
+  output += `> Data flows describe how information moves through the system — from external inputs through processing layers to storage or presentation.\n\n`;
+
+  if (!flows || flows.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.*`;
+    return output;
+  }
+
+  output += `**${flows.length} flow${flows.length === 1 ? "" : "s"} detected** in the codebase.\n\n---\n\n`;
   
   for (const flow of flows) {
     output += `## ${flow.name}\n\n`;
     output += `${flow.description}\n\n`;
-    output += `Steps:\n`;
-    output += flow.steps.map((s, i) => `${i + 1}. ${s}`).join("\n");
-    output += `\n\n`;
+    if (flow.steps && flow.steps.length > 0) {
+      output += `| Step | Action |\n`;
+      output += `|------|--------|\n`;
+      output += flow.steps.map((s, i) => `| ${i + 1} | ${s} |`).join("\n");
+      output += `\n\n`;
+    }
+    if (flow.modules && flow.modules.length > 0) {
+      output += `**Involved modules:** ${flow.modules.map(m => `\`${m}\``).join(", ")}\n\n`;
+    }
   }
   
-  output += `Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+  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.*`;
   
   return output;
 }
 
 function getFallbackDeveloperOnboarding(context) {
+  const frameworkList = context.techStack.frameworks.join(", ") || "general-purpose tools";
+  const languageList = context.techStack.languages.join(", ") || "standard languages";
+
   return `# Developer Onboarding
 
-## Start here
+## Welcome
+
+This guide helps new contributors get oriented in the **${context.project.name}** repository. The project is built with ${frameworkList} and ${languageList}, containing **${context.project.modulesDetected} modules** across **${context.project.filesScanned} files**.
+
+## Repository Structure
+
+The top-level directory is organized as follows:
 
-This is a ${context.project.name} repository with ${context.project.modulesDetected} modules.
+| Directory | Purpose |
+|-----------|---------|
+${context.repoRoots.map(root => `| \`${root}\` | ${describeRoot(root)} |`).join("\n")}
 
-## Main folders
+## Technology Stack
 
-${context.repoRoots.map(root => `- ${root}`).join("\n")}
+| Category | Technologies |
+|----------|-------------|
+| Frameworks | ${context.techStack.frameworks.join(", ") || "Not detected"} |
+| Languages | ${context.techStack.languages.join(", ") || "Not detected"} |
+| Build Tools | ${context.techStack.buildTools.join(", ") || "Not detected"} |
 
-## Technology stack
+## Largest Modules
 
-- ${context.techStack.frameworks.join(", ")}
-- ${context.techStack.languages.join(", ")}
+These are the primary modules by file count — good starting points for understanding the system:
 
-## Top modules by size
+| Module | Files | Description |
+|--------|-------|-------------|
+${context.topModules.slice(0, 10).map((m, i) => `| \`${m.key}\` | ${m.fileCount} | ${describeOnboardingModule(m.key)} |`).join("\n")}
 
-${context.topModules.slice(0, 10).map((m, i) => `${i + 1}. ${m.key} (${m.fileCount} files)`).join("\n")}
+## Getting Started
+
+1. Clone the repository and install dependencies
+2. Review the top-level directories above to understand the project layout
+3. Start with the largest modules listed above — they contain the core functionality
+4. Check for a \`README.md\` or \`CONTRIBUTING.md\` file for project-specific setup instructions
+
+---
+
+*This onboarding guide is generated deterministically. Enable AI enhancement (\`REPOLENS_AI_ENABLED=true\`) for a narrative-style guide with tips and common pitfalls.*`;
+}
+
+function describeRoot(root) {
+  const lower = root.toLowerCase().replace(/\/$/, "");
+  if (/^src$|^lib$/.test(lower)) return "Application source code";
+  if (/^test|^__test|^spec/.test(lower)) return "Test suites";
+  if (/^doc/.test(lower)) return "Documentation";
+  if (/^bin$|^scripts?$/.test(lower)) return "CLI entry points and scripts";
+  if (/^config/.test(lower)) return "Configuration files";
+  if (/^public$|^static$|^assets$/.test(lower)) return "Static assets";
+  if (/^dist$|^build$|^out$/.test(lower)) return "Build output";
+  if (/^\.github$/.test(lower)) return "GitHub Actions and workflows";
+  if (/^api$/.test(lower)) return "API definitions";
+  if (/^components?$/.test(lower)) return "Shared UI components";
+  if (/^pages?$|^views?$|^screens?$/.test(lower)) return "Application pages/views";
+  if (/^utils?$|^helpers?$/.test(lower)) return "Utility functions";
+  if (/^services?$/.test(lower)) return "Service layer";
+  if (/^hooks?$/.test(lower)) return "Custom hooks";
+  return "Project files";
+}
 
-Note: AI-enhanced documentation is disabled. Enable with REPOLENS_AI_ENABLED=true for richer insights.`;
+function describeOnboardingModule(key) {
+  const lower = key.toLowerCase();
+  if (/auth/.test(lower)) return "Authentication and authorization logic";
+  if (/api|route|endpoint/.test(lower)) return "API layer and route handlers";
+  if (/component|widget|ui/.test(lower)) return "User interface components";
+  if (/hook/.test(lower)) return "Custom hooks and shared state logic";
+  if (/util|helper|lib/.test(lower)) return "Utility and helper functions";
+  if (/service/.test(lower)) return "Service layer / business logic";
+  if (/model|schema|entity/.test(lower)) return "Data models and schemas";
+  if (/config|setting/.test(lower)) return "Configuration management";
+  if (/test|spec/.test(lower)) return "Test infrastructure";
+  if (/style|css|theme/.test(lower)) return "Styling and theming";
+  if (/page|view|screen/.test(lower)) return "Application pages and views";
+  if (/store|state|redux/.test(lower)) return "State management";
+  if (/middleware/.test(lower)) return "Request/response middleware";
+  if (/database|db|migration/.test(lower)) return "Database layer";
+  if (/render/.test(lower)) return "Rendering and template logic";
+  if (/publish/.test(lower)) return "Publishing and output delivery";
+  if (/scan/.test(lower)) return "File and repository scanning";
+  if (/analyz/.test(lower)) return "Code analysis and inference";
+  return "Core application module";
 }