codesummary 1.1.1 → 1.2.0

package/features.md

@@ -1,502 +1,418 @@
-# CodeSummary – Detailed Features and Functional Specification
-
-## 1. Overview
-
-**CodeSummary** is a **Node.js-based, cross-platform CLI tool** (distributed via **npm**) that automatically scans a project's source code and generates a **clean, professional PDF document** containing:
-
-- **Complete project file structure** with hierarchical organization
-- **Full source code content** for all selected files (no truncation)
-- **Intelligent file type detection** and user-selectable filtering
-- **Clean, readable formatting** optimized for code documentation
-
-Its primary goal is to **simplify code reviews, audits, and archival snapshots**, enabling teams and individuals to produce **self-contained, complete documentation** of their codebases with minimal setup.
-
-> **Repository**: [https://github.com/skamoll/CodeSummary](https://github.com/skamoll/CodeSummary)  
-> **npm Package Name**: `codesummary`
-
----
-
-### 1.1 Target Audience
-
-- **Developers** needing quick overviews of large projects with complete content
-- **Auditors/Consultants** requiring traceable documentation snapshots without size limits
-- **Educators/Students** preparing comprehensive code handovers or learning materials
-- **Teams** performing thorough code reviews or compliance checks
-- **Project Managers** creating complete project documentation for stakeholders
-
----
-
-### 1.2 Core Objectives
-
-1. **Complete automated documentation** — includes ALL file content without truncation
-2. **Cross-platform reliability** — identical behavior on Windows, macOS, and Linux
-3. **Advanced configurability** — user-defined filters, styles, and output preferences
-4. **Unlimited scalability** — handles projects of any size with efficient streaming
-5. **Intelligent safe defaults** — avoids binaries and unwanted files with smart filtering
-6. **Professional output** — clean, readable PDFs suitable for all professional contexts
-7. **Smart conflict handling** — automatic timestamped filenames when files are in use
-
----
-
-### 1.3 Key Differentiators
-
-- **No content limits** — processes files of any size completely
-- **Smart file conflict resolution** — automatic timestamped fallbacks
-- **Terminal compatibility** — works with all terminal types across platforms
-- **Whitelist-driven filtering** with extensive language support
-- **Interactive first-run setup** with persistent global configuration
-- **Memory-efficient streaming** for optimal performance on large projects
-- **Non-destructive scanning** with comprehensive error handling
-- **Fully offline operation** with no external dependencies
-
----
-
-### 1.4 Technology Stack
-
-- **Node.js** ≥ 18 (for native ES modules and modern APIs)
-- **PDFKit** for professional PDF generation with streaming support
-- **Inquirer.js** for interactive command-line prompts
-- **Chalk** for cross-platform terminal styling
-- **Ora** for progress indicators and status updates
-- **fs-extra** for enhanced file system operations
-
----
-
-## 2. Functional Requirements
-
-### 2.1 Command-Line Interface
-
-#### 2.1.1 Primary Commands
-
-| Command | Description | Example |
-|---------|-------------|---------|
-| `codesummary` | Scan current directory and generate PDF | `codesummary` |
-| `codesummary config` | Launch interactive configuration editor | `codesummary config` |
-| `codesummary --show-config` | Display current configuration settings | `codesummary --show-config` |
-| `codesummary --reset-config` | Reset to defaults and run setup wizard | `codesummary --reset-config` |
-| `codesummary --help` | Show comprehensive help information | `codesummary --help` |
-
-#### 2.1.2 Command-Line Options
-
-| Option | Short | Description | Example |
-|--------|-------|-------------|---------|
-| `--output` | `-o` | Override output directory | `codesummary -o ./docs` |
-| `--show-config` | - | Display current configuration | `codesummary --show-config` |
-| `--reset-config` | - | Reset configuration to defaults | `codesummary --reset-config` |
-| `--help` | `-h` | Show help message | `codesummary -h` |
-
-#### 2.1.3 Interactive Workflow
-
-1. **First-Run Setup**
-   - Detects missing configuration automatically
-   - Launches interactive setup wizard
-   - Configures output mode (relative/fixed path)
-   - Creates output directory if needed
-   - Saves persistent global configuration
-
-2. **Directory Scanning**
-   - Recursively scans current working directory
-   - Applies whitelist filtering for file extensions
-   - Excludes common build/dependency directories
-   - Shows comprehensive scan summary with statistics
-
-3. **Extension Selection**
-   - Presents detected file types in checkbox format
-   - Shows file counts for each extension
-   - Allows selective inclusion/exclusion
-   - Pre-selects all detected extensions by default
-
-4. **PDF Generation**
-   - Processes all selected files completely (no truncation)
-   - Shows progress indicators for large files
-   - Handles file conflicts with timestamped names
-   - Generates clean, professional PDF output
-
----
-
-### 2.2 Configuration Management
-
-#### 2.2.1 Global Configuration Storage
-
-**Storage Locations:**
-- **Linux/macOS**: `~/.codesummary/config.json`
-- **Windows**: `%APPDATA%\\CodeSummary\\config.json`
-
-#### 2.2.2 Configuration Structure
-
-```json
-{
-  \"output\": {
-    \"mode\": \"fixed\" | \"relative\",
-    \"fixedPath\": \"string (absolute path)\"
-  },
-  \"allowedExtensions\": [\"array of file extensions\"],
-  \"excludeDirs\": [\"array of directory names to exclude\"],
-  \"styles\": {
-    \"colors\": {
-      \"title\": \"#333353\",
-      \"section\": \"#00FFB9\",
-      \"text\": \"#333333\",
-      \"error\": \"#FF4D4D\",
-      \"footer\": \"#666666\"
-    },
-    \"layout\": {
-      \"marginLeft\": 40,
-      \"marginTop\": 40,
-      \"marginRight\": 40,
-      \"footerHeight\": 20
-    }
-  },
-  \"settings\": {
-    \"documentTitle\": \"Project Code Summary\",
-    \"maxFilesBeforePrompt\": 500
-  }
-}
-```
-
-#### 2.2.3 Configuration Features
-
-- **Cross-platform path handling** with automatic normalization
-- **Validation system** prevents invalid configurations
-- **Interactive editor** for all configuration sections
-- **Automatic backup and recovery** for corrupted configurations
-- **Reset functionality** to restore defaults
-
----
-
-### 2.3 File System Scanning
-
-#### 2.3.1 Scanning Algorithm
-
-1. **Recursive Directory Traversal**
-   - Starts from current working directory
-   - Follows symbolic links safely
-   - Respects file system permissions
-   - Handles large directory structures efficiently
-
-2. **Filtering Logic**
-   - **Whitelist approach**: Only processes explicitly allowed extensions
-   - **Directory exclusions**: Skips common build/dependency directories
-   - **Hidden file handling**: Includes important dot files (.gitignore, .env.example)
-   - **Binary detection**: Automatically skips binary files
-
-3. **Error Handling**
-   - Graceful handling of permission denied errors
-   - Continues scanning despite individual file failures
-   - Logs warnings for inaccessible files
-   - Provides detailed error context
-
-#### 2.3.2 Supported File Extensions
-
-**Programming Languages:**
-- JavaScript: `.js`, `.jsx`, `.mjs`
-- TypeScript: `.ts`, `.tsx`, `.d.ts`
-- Python: `.py`, `.pyw`, `.pyx`
-- Java: `.java`
-- C/C++: `.c`, `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp`
-- C#: `.cs`
-- Go: `.go`
-- Rust: `.rs`
-- Swift: `.swift`
-- Kotlin: `.kt`, `.kts`
-- Scala: `.scala`
-- PHP: `.php`, `.phtml`
-- Ruby: `.rb`, `.rbw`
-
-**Web Technologies:**
-- HTML: `.html`, `.htm`
-- CSS: `.css`, `.scss`, `.sass`, `.less`
-- Vue.js: `.vue`
-- Svelte: `.svelte`
-
-**Data & Configuration:**
-- JSON: `.json`, `.jsonc`
-- XML: `.xml`, `.xsd`, `.xsl`
-- YAML: `.yaml`, `.yml`
-- TOML: `.toml`
-- SQL: `.sql`
-- GraphQL: `.graphql`, `.gql`
-
-**Scripts & Shell:**
-- Shell: `.sh`, `.bash`, `.zsh`
-- Batch: `.bat`, `.cmd`
-- PowerShell: `.ps1`, `.psm1`
-
-**Documentation:**
-- Markdown: `.md`, `.markdown`
-- Text: `.txt`
-- Dockerfile: `.dockerfile`
-
-#### 2.3.3 Directory Exclusions
-
-**Default Excluded Directories:**
-- `node_modules` (Node.js dependencies)
-- `.git` (Git version control)
-- `.vscode` (VS Code settings)
-- `dist`, `build` (Build outputs)
-- `coverage` (Test coverage reports)
-- `out` (Output directories)
-- `__pycache__` (Python cache)
-- `.next` (Next.js build)
-- `.nuxt` (Nuxt.js build)
-- `vendor` (Dependency directories)
-- `.cache` (Cache directories)
-
----
-
-### 2.4 PDF Generation
-
-#### 2.4.1 Document Structure
-
-**1. Project Overview Section**
-- Document title (configurable)
-- Project name (derived from directory)
-- Generation timestamp
-- List of included file types with descriptions
-- Clean, professional formatting
-
-**2. File Structure Section**
-- Complete hierarchical file listing
-- Organized by relative paths from project root
-- Sorted alphabetically for easy navigation
-- Monospace font for proper alignment
-
-**3. File Content Section**
-- **Complete source code** for each selected file
-- **No truncation or size limits**
-- Proper monospace formatting for code readability
-- File headers with clear identification
-- Natural page breaks when needed
-- Error handling for unreadable files
-
-#### 2.4.2 PDF Specifications
-
-**Format & Layout:**
-- **Paper size**: A4 (595 × 842 points)
-- **Margins**: 40pt on all sides for optimal content area
-- **Fonts**: 
-  - Headers: Helvetica Bold
-  - Body text: Helvetica
-  - Code content: Courier (monospace)
-- **Colors**: Professional color scheme with high contrast
-
-**Advanced Features:**
-- **Streaming generation** for memory efficiency
-- **Automatic page breaks** handled by PDFKit
-- **Smart file conflict handling** with timestamped names
-- **Progress indicators** for large file processing
-- **Error recovery** with graceful failure handling
-
-#### 2.4.3 File Naming Convention
-
-**Standard naming:**
-```
-PROJECTNAME_code.pdf
-```
-
-**Conflict resolution (when file is in use):**
-```
-PROJECTNAME_code_YYYYMMDD_HHMMSS.pdf
-```
-
-**Example:**
-```
-MYPROJECT_code.pdf                    # Standard
-MYPROJECT_code_20250729_141602.pdf   # Timestamped fallback
-```
-
----
-
-### 2.5 Cross-Platform Compatibility
-
-#### 2.5.1 Operating System Support
-
-- **Windows** (10, 11, Server 2019+)
-- **macOS** (10.15+, including Apple Silicon)
-- **Linux** (Ubuntu 18.04+, CentOS 7+, other major distributions)
-
-#### 2.5.2 Terminal Compatibility
-
-- **Universal ASCII output** - no special Unicode characters
-- **Color support detection** with graceful fallbacks
-- **All terminal types supported** (cmd, PowerShell, bash, zsh, fish)
-- **Screen reader compatible** output format
-
-#### 2.5.3 Path Handling
-
-- **Automatic path normalization** across platforms
-- **Unicode filename support** for international characters
-- **Long path support** on Windows (>260 characters)
-- **Case sensitivity handling** appropriate to each platform
-
----
-
-### 2.6 Performance & Scalability
-
-#### 2.6.1 Memory Management
-
-- **Streaming file processing** to minimize memory usage
-- **Efficient PDF generation** with incremental building
-- **Garbage collection optimization** for large projects
-- **Memory usage monitoring** with warnings for extreme cases
-
-#### 2.6.2 Large Project Handling
-
-- **No file size limits** - processes files of any size completely
-- **Progress indicators** for files with >1000 lines
-- **Configurable warning thresholds** (default: 500 files)
-- **User confirmation** for very large projects
-- **Streaming architecture** prevents memory overflow
-
-#### 2.6.3 Performance Optimizations
-
-- **Parallel file scanning** where safe
-- **Efficient binary detection** to skip non-text files quickly
-- **Smart caching** of file metadata
-- **Optimized PDF rendering** with minimal memory footprint
-
----
-
-### 2.7 Error Handling & Validation
-
-#### 2.7.1 Input Validation
-
-- **Path validation** with security checks
-- **Configuration validation** with schema enforcement
-- **File extension validation** with normalization
-- **Permission checking** before operations
-
-#### 2.7.2 Error Recovery
-
-- **Graceful degradation** when files are inaccessible
-- **Automatic retry** for transient failures
-- **Detailed error logging** with context information
-- **User-friendly error messages** with suggested solutions
-
-#### 2.7.3 File Conflict Handling
-
-- **Automatic detection** of files in use
-- **Timestamped filename generation** for conflicts
-- **User notification** of filename changes
-- **Fallback mechanisms** for write failures
-
----
-
-## 3. Technical Architecture
-
-### 3.1 Module Structure
-
-```
-src/
-├── cli.js              # Command-line interface and user interaction
-├── configManager.js    # Global configuration management
-├── scanner.js          # File system scanning and filtering
-├── pdfGenerator.js     # PDF creation and formatting
-└── errorHandler.js     # Comprehensive error handling
-```
-
-### 3.2 Key Design Patterns
-
-- **Modular architecture** with clear separation of concerns
-- **Event-driven processing** for scalable file handling
-- **Stream-based operations** for memory efficiency
-- **Functional programming principles** where appropriate
-- **Comprehensive error boundaries** with graceful recovery
-
-### 3.3 Dependencies
-
-**Core Dependencies:**
-- `pdfkit` - Professional PDF generation
-- `inquirer` - Interactive command-line prompts
-- `chalk` - Cross-platform terminal styling
-- `ora` - Progress indicators and spinners
-- `fs-extra` - Enhanced file system operations
-
-**Development Dependencies:**
-- Modern ES modules (Node.js 18+)
-- Native Promise-based APIs
-- Cross-platform path handling
-- Unicode and internationalization support
-
----
-
-## 4. Quality Assurance
-
-### 4.1 Testing Strategy
-
-- **Cross-platform testing** on Windows, macOS, and Linux
-- **Large project stress testing** with thousands of files
-- **Memory usage profiling** for optimization
-- **Terminal compatibility verification** across different environments
-- **File conflict scenario testing** with various edge cases
-
-### 4.2 Security Considerations
-
-- **Path traversal prevention** with input validation
-- **Permission-based access control** respecting system security
-- **No external network dependencies** for complete offline operation
-- **Safe file handling** with proper error boundaries
-- **Configuration validation** to prevent malicious settings
-
-### 4.3 Documentation Standards
-
-- **Comprehensive README** with usage examples
-- **Detailed feature specification** (this document)
-- **Inline code documentation** with JSDoc standards
-- **Error message clarity** with actionable guidance
-- **Contributing guidelines** for open-source collaboration
-
----
-
-## 5. Future Enhancements
-
-### 5.1 Planned Features
-
-- **Syntax highlighting** in PDF output for better code readability
-- **Clickable table of contents** with bookmarks for navigation
-- **Multiple output formats** (HTML, JSON, Markdown)
-- **Project metrics and statistics** (line counts, complexity analysis)
-- **CI/CD integration mode** for automated documentation pipelines
-- **Custom PDF themes** and styling options
-- **Plugin system** for custom file processors
-
-### 5.2 Advanced Capabilities
-
-- **Incremental updates** for changed files only
-- **Git integration** for commit-specific documentation
-- **Code annotation** system for additional context
-- **Multi-language support** for international users
-- **Web-based configuration** interface for easier setup
-- **Integration APIs** for third-party tools
-
----
-
-## 6. Success Metrics
-
-### 6.1 Performance Targets
-
-- **Scan speed**: >1000 files per second on modern hardware
-- **Memory usage**: <200MB for projects with 10,000+ files
-- **PDF generation**: <30 seconds for typical projects (100 files)
-- **Cross-platform consistency**: 100% feature parity across platforms
-
-### 6.2 Quality Targets
-
-- **Zero data loss**: All file content included without truncation
-- **Error rate**: <0.1% failure rate on valid projects
-- **User satisfaction**: Clear, actionable error messages for all failure cases
-- **Compatibility**: Works on 99%+ of supported platform/terminal combinations
-
----
-
-## 7. Conclusion
-
-CodeSummary represents a comprehensive solution for automated code documentation, combining professional-grade PDF output with intelligent file processing and cross-platform compatibility. Its focus on complete content inclusion, smart conflict handling, and terminal compatibility makes it suitable for both individual developers and enterprise environments.
-
-The tool's architecture supports unlimited scalability while maintaining efficient resource usage, ensuring it can handle projects of any size. With its extensive language support and intelligent filtering, CodeSummary serves as a valuable tool for code reviews, audits, documentation, and archival purposes.
-
----
-
-**Document Version**: 2.0  
-**Last Updated**: January 2025  
-**Status**: Implementation Complete - Ready for Release
+# CodeSummary – Detailed Features and Functional Specification
+
+## 1. Overview
+
+**CodeSummary** is a **Node.js-based, cross-platform CLI tool** (distributed via **npm**) that automatically scans a project's source code and generates output in three formats:
+
+- **PDF**: clean, professional A4 documentation for code reviews, audits, and archival snapshots
+- **RAG JSON**: structured output with semantic chunks, byte offsets, and token estimates — built for vector databases and programmatic LLM integration
+- **LLM Markdown**: a single token-optimised Markdown file for pasting directly into any chat-based LLM (any LLM chat interface)
+
+> **Repository**: [https://github.com/skamoll/CodeSummary](https://github.com/skamoll/CodeSummary)
+> **npm Package Name**: `codesummary`
+
+---
+
+### 1.1 Target Audience
+
+- **Developers** who need quick, complete overviews of large projects
+- **Auditors / Consultants** requiring traceable documentation snapshots
+- **Educators / Students** preparing comprehensive code handovers
+- **AI Engineers** building RAG pipelines or feeding code into vector databases
+- **Anyone** who wants to work with their codebase inside a chat-based LLM efficiently
+
+---
+
+### 1.2 Core Objectives
+
+1. **Three output modes** — PDF for humans, RAG JSON for machines, LLM Markdown for chat
+2. **Cross-platform reliability** — identical behaviour on Windows, macOS, and Linux
+3. **Lossless content optimisation** — reduce token count without altering code meaning
+4. **Smart config migration** — new defaults merge into existing config without data loss
+5. **Versioned output** — `-v1`, `-v2` suffixes prevent overwrites and timestamp clutter
+6. **Non-interactive operation** — `--no-interactive` for CI/CD pipelines
+
+---
+
+### 1.3 Technology Stack
+
+- **Node.js** ≥ 18 (native ES modules)
+- **PDFKit** for PDF generation with streaming support
+- **Inquirer.js** for interactive prompts
+- **Chalk** for terminal styling
+- **Ora** for progress indicators
+- **fs-extra** for enhanced file system operations
+- **js-yaml** for YAML config loading
+- **ajv** for JSON schema validation
+
+---
+
+## 2. Functional Requirements
+
+### 2.1 Command-Line Interface
+
+#### 2.1.1 Primary Commands
+
+| Command | Description |
+|---------|-------------|
+| `codesummary` | Scan current directory, generate PDF |
+| `codesummary --format rag` | Generate RAG-optimised JSON |
+| `codesummary --format llm` | Generate LLM-optimised Markdown |
+| `codesummary --format both` | Generate PDF + RAG JSON (single scan) |
+| `codesummary config` | Launch interactive configuration editor |
+| `codesummary --show-config` | Display current configuration |
+| `codesummary --reset-config` | Reset to defaults and run setup wizard |
+| `codesummary --help` | Show help |
+| `codesummary --version` | Show version |
+
+#### 2.1.2 Command-Line Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--format <format>` | `-f` | `pdf` (default), `rag`, `llm`, or `both` |
+| `--output <path>` | `-o` | Override output directory for this run |
+| `--no-interactive` | | Skip all prompts; auto-select all extensions |
+| `--show-config` | | Display current configuration |
+| `--reset-config` | | Reset configuration to defaults |
+| `--help` | `-h` | Show help message |
+| `--version` | `-v` | Show version |
+
+#### 2.1.3 Interactive Workflow
+
+1. **First-run setup** — detects missing config, launches setup wizard, creates output directory
+2. **Directory scanning** — recursive scan with whitelist filtering and exclusion rules
+3. **Extension selection** — checkbox prompt with file counts; skipped with `--no-interactive`
+4. **Generation** — selected format(s) generated, versioned filenames used if target exists
+
+---
+
+### 2.2 Output Formats
+
+#### 2.2.1 PDF (`--format pdf`)
+
+Generates a professional A4 PDF with three sections:
+
+1. **Project overview**: title, project name, timestamp, included file types
+2. **File structure**: sorted complete file listing
+3. **File content**: full source of every selected file, monospace font, no truncation
+
+File naming: `PROJECTNAME_code.pdf` → `PROJECTNAME_code-v1.pdf` → `PROJECTNAME_code-v2.pdf` ...
+
+#### 2.2.2 RAG JSON (`--format rag`)
+
+Generates a structured JSON file built for embedding and retrieval in AI/ML pipelines.
+
+**When to use RAG:**
+- Loading code into a vector database (Pinecone, Qdrant, Chroma, etc.)
+- Building a retrieval-augmented generation pipeline
+- Programmatic LLM integration where you control chunking and retrieval
+- Rapid chunk seeking via byte offsets without re-parsing the full JSON
+
+**JSON structure:**
+```json
+{
+  "metadata": { "projectName": "...", "generatedAt": "...", "version": "..." },
+  "files": [
+    {
+      "id": "abc123",
+      "path": "src/component.js",
+      "language": "JavaScript",
+      "hash": "sha256-...",
+      "chunks": [
+        {
+          "id": "chunk_abc123_0",
+          "content": "function myFn() { ... }",
+          "tokenEstimate": 45,
+          "lineStart": 1,
+          "lineEnd": 15,
+          "chunkingMethod": "semantic-function",
+          "context": "function_myFn",
+          "imports": ["react"],
+          "calls": ["useState"]
+        }
+      ]
+    }
+  ],
+  "index": {
+    "chunkOffsets": {
+      "chunk_abc123_0": { "contentStart": 12123, "contentEnd": 12356 }
+    },
+    "statistics": { "processingTimeMs": 245, "chunksWithValidOffsets": 387 }
+  }
+}
+```
+
+**Key RAG features:**
+- Semantic chunking by function, class, or logical block
+- Byte-accurate content offsets for fast random access
+- SHA-256 file hashes for deduplication
+- Language-aware token estimation (±20% accuracy)
+- Import and call graph extraction
+- YAML-configurable via `raggen.config.yaml`
+
+File naming: `PROJECTNAME_rag.json` → `PROJECTNAME_rag-v1.json` → ...
+
+#### 2.2.3 LLM Markdown (`--format llm`)
+
+Generates a single Markdown file optimised for direct consumption by chat-based LLMs.
+
+**When to use LLM Markdown:**
+- Asking any LLM chat interface to review or explain your codebase
+- One-off questions that don't justify setting up a RAG pipeline
+- Sharing project context in a conversation without a file upload feature
+
+**File structure:**
+```markdown
+# ProjectName — Code Summary
+
+**Generated:** 2026-04-05 | **Files:** 42 | **Total size:** 1.2 MB
+
+---
+
+## File Tree
+
+```
+  src/cli.js
+  src/scanner.js
+  ...
+```
+
+---
+
+## src/cli.js
+
+```js
+// full file content
+```
+```
+
+**Lossless optimisations applied automatically:**
+
+| Optimisation | Applies to | Notes |
+|---|---|---|
+| Normalise line endings (`\r\n` → `\n`) | All files | Safe for all languages |
+| Strip trailing whitespace per line | All files | Never has semantic meaning |
+| Remove leading/trailing blank lines | All files | Per-file trimming |
+| Compact JSON | `.json` files | Re-serialise without indentation |
+| Max 2 consecutive blank lines | `.md` / `.mdx` | Preserves paragraph semantics |
+| Max 1 consecutive blank line | All other files | Removes relleno without touching indentation |
+
+**What is never modified:**
+- Indentation (critical for Python, YAML, Makefiles)
+- Multiple spaces within a line (may be in string literals)
+- Comments
+- Code logic
+
+File naming: `PROJECTNAME_llm.md` → `PROJECTNAME_llm-v1.md` → ...
+
+#### 2.2.4 Both (`--format both`)
+
+Runs PDF and RAG generation in sequence using a single scan pass. Uses continue-on-error: if one format fails, the other still completes. Exit code 1 if either failed.
+
+---
+
+### 2.3 Configuration Management
+
+#### 2.3.1 Storage Locations
+
+- **Linux/macOS**: `~/.codesummary/config.json`
+- **Windows**: `%APPDATA%\CodeSummary\config.json`
+
+#### 2.3.2 Configuration Structure
+
+```json
+{
+  "configVersion": "1.1.0",
+  "output": {
+    "mode": "fixed | relative",
+    "fixedPath": "absolute path"
+  },
+  "allowedExtensions": ["array of extensions"],
+  "excludeDirs": ["array of directory names"],
+  "excludeFiles": ["array of glob patterns"],
+  "styles": { "colors": {}, "layout": {}, "fonts": {} },
+  "settings": {
+    "documentTitle": "Project Code Summary",
+    "maxFilesBeforePrompt": 500
+  }
+}
+```
+
+#### 2.3.3 Smart Migration
+
+On every run, new defaults are merged into the existing config using `smartMergeArrays`:
+- Items already present are kept in place
+- New items are appended at the end
+- User removals are respected (removed items are not re-added)
+- Changes are saved automatically and the user is notified
+
+#### 2.3.4 Interactive Editor
+
+Sections available via `codesummary config`:
+- Output settings (mode, fixed path)
+- Allowed extensions
+- Excluded directories
+- Excluded file patterns
+- General settings (document title, file warning threshold)
+
+---
+
+### 2.4 File System Scanning
+
+#### 2.4.1 Algorithm
+
+1. Recursive directory traversal from `process.cwd()`
+2. Whitelist filtering by allowed extensions
+3. Directory exclusion by exact name match + built-in common-skip list
+4. File exclusion by glob pattern matching
+5. Symlink detection (skipped to avoid loops)
+6. File size limit: 100 MB per file
+7. Duplicate detection via absolute path tracking
+
+#### 2.4.2 Supported Extensions (defaults)
+
+**Web & JavaScript ecosystem:**
+`.js`, `.jsx`, `.ts`, `.tsx`, `.vue`, `.svelte`, `.astro`, `.mdx`
+
+**Backend languages:**
+`.py`, `.java`, `.cs`, `.cpp`, `.c`, `.h`, `.go`, `.rs`, `.swift`, `.kt`, `.scala`, `.rb`, `.php`, `.dart`, `.lua`, `.r`, `.ex`, `.exs`, `.pl`
+
+**Web & markup:**
+`.html`, `.css`, `.scss`, `.xml`
+
+**Data & config:**
+`.json`, `.yaml`, `.yml`, `.toml`, `.ini`, `.properties`, `.tf`, `.tfvars`, `.env`, `.local`, `.cfg`, `.conf`
+
+**Schema & query:**
+`.sql`, `.graphql`, `.gql`, `.proto`, `.prisma`
+
+**Scripts:**
+`.sh`, `.bat`, `.ps1`, `.mk`, `.cmake`
+
+**Documentation:**
+`.md`, `.mdx`, `.txt`
+
+**Specialised:**
+`.ino` (Arduino), `.j2` (Jinja2), `.service`, `.timer` (systemd), `.crt` (certificates), `.csv`, `.tsv`
+
+#### 2.4.3 Default Excluded Directories
+
+Build output: `dist`, `build`, `out`, `target`
+Dependencies: `node_modules`, `vendor`, `bower_components`
+Caches: `.cache`, `.turbo`, `.gradle`, `.yarn`, `.pnpm-store`, `.pytest_cache`, `.mypy_cache`, `.tox`, `htmlcov`
+IDE: `.git`, `.vscode`, `.idea`
+Framework: `.next`, `.nuxt`, `.angular`, `.svelte-kit`, `.expo`, `.dart_tool`, `storybook-static`
+Python: `__pycache__`, `venv`, `.venv`
+Infrastructure: `.terraform`
+
+#### 2.4.4 Default Excluded File Patterns
+
+Lock files: `*-lock.json`, `*.lock`, `composer.lock`, `Pipfile.lock`, `*-lock.yaml`
+Minified: `*.min.js`, `*.min.css`, `*.map`
+Compiled: `*.pyc`, `*.pyo`, `*.class`
+Temporary: `*.log`, `*.tmp`, `*.temp`, `*.swp`, `*.bak`, `*.orig`
+OS metadata: `.DS_Store`, `Thumbs.db`, `desktop.ini`, `ehthumbs.db`
+
+---
+
+### 2.5 Versioned Output Files
+
+When a target file already exists, a `-vN` suffix is added instead of overwriting:
+
+```
+PROJECTNAME_llm.md       ← exists
+PROJECTNAME_llm-v1.md    ← created
+                         ← next run: v1 exists
+PROJECTNAME_llm-v2.md    ← created
+```
+
+Applies to all three formats. Existing `-vN` suffixes are stripped before re-versioning to avoid `name-v1-v1.md`.
+
+---
+
+### 2.6 Non-Interactive Mode
+
+`--no-interactive` (or non-TTY stdin) skips:
+- Extension selection checkbox → all detected extensions selected
+- File count confirmation prompt → proceeds automatically
+
+Designed for use in CI/CD pipelines and scripted environments.
+
+---
+
+### 2.7 Error Handling
+
+- **Path traversal prevention**: blocks `..`, null bytes, and Windows reserved names
+- **Non-ASCII path support**: Unicode characters in paths (e.g. `C:\Users\Andrés\...`) are preserved correctly
+- **Graceful scan errors**: permission denied and missing files are logged but don't abort the scan
+- **PDF stream errors**: file-in-use (EBUSY/EACCES) triggers versioned filename fallback
+- **LLM/RAG errors**: unreadable files emit a warning block in output instead of crashing
+- **`--format both` failures**: continue-on-error; both outputs attempted, all errors reported together
+
+---
+
+## 3. Technical Architecture
+
+### 3.1 Module Structure
+
+```
+src/
+├── cli.js              # Argument parsing, orchestration, user interaction
+├── scanner.js          # Recursive directory scanning and filtering
+├── pdfGenerator.js     # PDF generation (PDFKit, streaming)
+├── ragGenerator.js     # RAG JSON generation with semantic chunking
+├── llmGenerator.js     # LLM Markdown generation with content optimisations
+├── configManager.js    # Global config load, save, migrate, edit
+├── ragConfig.js        # RAG-specific config (YAML loading, defaults)
+├── errorHandler.js     # Path validation, sanitisation, global error handlers
+└── utils.js            # Shared: formatFileSize, getExtensionDescription,
+                        #         matchesGlobPattern, resolveVersionedPath
+```
+
+### 3.2 Data Flow
+
+```
+bin/codesummary.js
+  └─ src/index.js          (bootstrap)
+        └─ src/cli.js       (parse args → executeMainFlow)
+              ├─ scanner.js  (scan → filesByExtension)
+              ├─ pdfGenerator.js    (format: pdf)
+              ├─ ragGenerator.js    (format: rag)  ← uses ragConfig.js
+              └─ llmGenerator.js   (format: llm)
+```
+
+### 3.3 Key Design Decisions
+
+- **ESM modules** throughout (`"type": "module"`)
+- **No singleton exports** — all modules export classes, instantiated at call site
+- **Shared utilities** in `utils.js` — single source of truth, no duplication
+- **Streaming writes** for PDF and LLM output — memory-efficient on large projects
+- **Static imports** only — dynamic `import()` avoided for consistency
+
+---
+
+## 4. Security
+
+- Path traversal (`..`) blocked via pattern matching before any file operation
+- User-supplied paths sanitised: control characters and injection sequences removed
+- Unicode characters in paths preserved (non-ASCII allowed)
+- Windows reserved device names (CON, NUL, COM1, etc.) rejected
+- No external network calls at runtime — fully offline operation
+- Config validated against schema before use; corrupt config prompts reset
+
+---
+
+## 5. Future Enhancements
+
+- `--format all`: PDF + RAG + LLM in a single pass
+- Syntax highlighting in PDF output
+- Clickable table of contents with bookmarks in PDF
+- Git integration: document only changed files since last commit
+- CI/CD plugin for automated documentation on push
+- Custom PDF themes and styling
+
+---
+
+**Document Version**: 3.0
+**Last Updated**: 2026-04-05
+**Status**: Implementation Complete