diff --git a/.roo/rules-docs-extractor/1_extraction_workflow.xml b/.roo/rules-docs-extractor/1_extraction_workflow.xml
new file mode 100644
index 0000000000..6cac8da27a
--- /dev/null
+++ b/.roo/rules-docs-extractor/1_extraction_workflow.xml
@@ -0,0 +1,238 @@
+
+
+ The Docs Extractor mode performs comprehensive analysis of features and components
+ to generate multi-audience documentation. It extracts technical details, business logic,
+ user workflows, and all related information to create documentation suitable for
+ end-users, developers, administrators, and stakeholders.
+
+
+
+
+ Understand Documentation Request
+
+ Parse the user's request to identify the feature or component.
+ Determine if the user has provided a documentation section for review or is requesting new documentation.
+ Default to user-friendly documentation unless technical docs are specifically requested.
+ Focus on practical benefits and real-world usage.
+ Note any specific aspects the user wants emphasized.
+
+ The user will specify what they want documented in their initial message. The workflow branches based on whether a review is requested or new documentation is to be generated.
+
+
+
+ Initial Feature Discovery
+
+ Use semantic search to find all related code
+ Identify entry points and main components
+ Map high-level architecture
+
+
+[feature name] implementation main entry point
+
+ ]]>
+
+
+
+
+
+ Technical Implementation Analysis
+
+
+ Analyze source code structure
+
+ - Identify classes, functions, and modules
+ - Extract method signatures and parameters
+ - Document return types and data structures
+ - Map inheritance and composition relationships
+
+
+
+ Extract API specifications
+
+ - REST endpoints with methods and parameters
+ - GraphQL schemas and resolvers
+ - WebSocket events and handlers
+ - RPC interfaces and protocols
+
+
+
+ Document configuration options
+
+ - Environment variables
+ - Configuration files and schemas
+ - Feature flags and toggles
+ - Runtime parameters
+
+
+
+
+
+
+ Business Logic and Workflow Extraction
+
+
+ Map user workflows
+
+ - User journey through the feature
+ - Decision points and branching logic
+ - State transitions and lifecycle
+ - User roles and permissions
+
+
+
+ Document business rules
+
+ - Validation logic and constraints
+ - Calculation formulas and algorithms
+ - Business process implementations
+ - Compliance and regulatory requirements
+
+
+
+ Identify use cases
+
+ - Primary use cases and scenarios
+ - Edge cases and special conditions
+ - Error scenarios and recovery
+ - Performance considerations
+
+
+
+
+
+
+ Dependencies and Integration Analysis
+
+
+ Map external dependencies
+
+ - Third-party libraries and versions
+ - External services and APIs
+ - Database connections and schemas
+ - Message queues and event systems
+
+
+
+ Document integration points
+
+ - Incoming webhooks and callbacks
+ - Outgoing API calls
+ - Event publishers and subscribers
+ - Shared data stores and caches
+
+
+
+ Analyze data flow
+
+ - Input data sources and formats
+ - Data transformations and mappings
+ - Output formats and destinations
+ - Data retention and lifecycle
+
+
+
+
+
+
+ Quality and Testing Analysis
+
+
+ Assess test coverage
+
+ - Unit test coverage and quality
+ - Integration test scenarios
+ - End-to-end test flows
+ - Performance test results
+
+
+
+ Document error handling
+
+ - Error types and codes
+ - Exception handling strategies
+ - Fallback mechanisms
+ - Recovery procedures
+
+
+
+ Identify quality metrics
+
+ - Code complexity metrics
+ - Performance benchmarks
+ - Security vulnerability assessments
+ - Maintainability indices
+
+
+
+
+
+
+ Security and Compliance Analysis
+
+
+ Document security measures
+
+ - Authentication mechanisms
+ - Authorization and access control
+ - Data encryption methods
+ - Security headers and policies
+
+
+
+ Identify vulnerabilities
+
+ - Known security issues
+ - Potential attack vectors
+ - Mitigation strategies
+ - Security best practices
+
+
+
+ Compliance requirements
+
+ - Regulatory compliance (GDPR, HIPAA, etc.)
+ - Industry standards adherence
+ - Audit trail requirements
+ - Data privacy considerations
+
+
+
+
+
+
+
+ This phase has two paths: Reviewing existing docs or Generating new docs. The path taken is determined in the initialization phase.
+
+ Path 1: Review and Recommend Improvements
+ This path is followed if the user provided a documentation section for review.
+
+ Compare the provided documentation against the analysis of the codebase.
+ Identify inaccuracies (technical, logical), omissions, and areas for improvement.
+ Categorize inaccuracies by severity (e.g., Critical, Major, Minor, Suggestion).
+ Formulate a structured recommendation in the chat, suitable for being copied to the docs team.
+ Do not write any files or make changes yourself.
+ The final output in the chat should ONLY be the structured recommendation, without any preceding conversational text.
+
+
+
+ Path 2: Generate New Documentation
+ This path is followed if the user requested new documentation.
+
+ Choose a documentation style (e.g., user-focused or comprehensive) from `2_documentation_patterns.xml`.
+ Structure the documentation with clear sections, examples, and user-friendly elements.
+ Create a `DOCS-TEMP-[feature].md` file with the generated content.
+ Use a conversational tone and practical examples from `7_user_friendly_examples.xml`.
+
+
+
+
+
+ All code paths have been analyzed
+ Business logic is fully documented
+ Integration points are mapped
+ Security considerations are addressed
+ Documentation serves all target audiences
+ Metadata and cross-references are complete
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/2_documentation_patterns.xml b/.roo/rules-docs-extractor/2_documentation_patterns.xml
new file mode 100644
index 0000000000..32fc236feb
--- /dev/null
+++ b/.roo/rules-docs-extractor/2_documentation_patterns.xml
@@ -0,0 +1,419 @@
+
+
+ Standard patterns and templates for structuring extracted documentation
+ to serve end-users with clear, practical information.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Between major sections
+ ---
+ Improve readability and scanning
+
+
+
+
+
+
+
+ Show real tool output or interface elements
+ Use actual file paths and settings names
+ Include common error messages and solutions
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Step-by-step tutorials with screenshots
+ Common use case examples
+ Troubleshooting guides for user errors
+ Feature benefits and value propositions
+
+
+ Use simple, non-technical language
+ Include visual aids and examples
+ Focus on outcomes rather than implementation
+ Provide clear action steps
+
+
+
+
+
+ Code examples and snippets
+ API specifications and contracts
+ Integration patterns and best practices
+ Performance optimization techniques
+
+
+ Use precise technical terminology
+ Include code samples in multiple languages
+ Document edge cases and limitations
+ Provide debugging and testing guidance
+
+
+
+
+
+ Deployment and configuration procedures
+ Monitoring and maintenance tasks
+ Security hardening guidelines
+ Backup and disaster recovery
+
+
+ Focus on operational aspects
+ Include command-line examples
+ Document automation opportunities
+ Emphasize security and compliance
+
+
+
+
+
+ Business value and ROI
+ Feature capabilities and limitations
+ Competitive advantages
+ Risk assessment and mitigation
+
+
+ Use business-oriented language
+ Include metrics and KPIs
+ Focus on strategic benefits
+ Provide executive summaries
+
+
+
+
+
+
+
+
+
+
+ ⚠️ **Deprecation Notice**
+>
+> This feature/method is deprecated as of version [X.Y.Z].
+> - **Deprecated**: [date]
+> - **Removal Target**: [version/date]
+> - **Migration Path**: [See migration guide](#migration)
+> - **Replacement**: [new feature/method]
+ ]]>
+
+
+
+ 🔒 **Security Consideration**
+>
+> [Description of security concern]
+> - **Risk Level**: [High/Medium/Low]
+> - **Affected Versions**: [versions]
+> - **Mitigation**: [steps to address]
+> - **References**: [CVE/advisory links]
+ ]]>
+
+
+
+ ⚡ **Performance Impact**
+>
+> [Description of performance consideration]
+> - **Impact**: [metrics/benchmarks]
+> - **Optimization**: [recommended approach]
+> - **Trade-offs**: [considerations]
+ ]]>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ [Link Text](#section-anchor)
+ [See Configuration Guide](#configuration)
+
+
+
+ [Link Text](https://external.url)
+ [Official Documentation](https://docs.example.com)
+
+
+
+ 📌 **Related Features**
+> - [Feature A](../feature-a/README.md): [How it relates]
+> - [Feature B](../feature-b/README.md): [How it relates]
+ ]]>
+
+
+
+ 👉 **See Also**
+> - [Related Topic 1](#anchor1)
+> - [Related Topic 2](#anchor2)
+> - [External Resource](https://example.com)
+ ]]>
+
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/3_analysis_techniques.xml b/.roo/rules-docs-extractor/3_analysis_techniques.xml
new file mode 100644
index 0000000000..149b554599
--- /dev/null
+++ b/.roo/rules-docs-extractor/3_analysis_techniques.xml
@@ -0,0 +1,410 @@
+
+
+ Comprehensive techniques for analyzing code and extracting documentation-worthy
+ information from various aspects of a codebase.
+
+
+
+
+
+ Identify and analyze main entry points to understand feature flow
+
+
+ Search for main functions, controllers, or route handlers
+ Trace execution flow from entry to exit
+ Map decision branches and conditionals
+ Document input validation and preprocessing
+
+
+
+main function app.listen server.start router controller handler
+
+
+
+
+src/controllers/feature.controller.ts
+
+
+
+
+src
+(app\.(get|post|put|delete)|@(Get|Post|Put|Delete)|router\.(get|post|put|delete))
+
+ ]]>
+
+
+
+
+ Extract API specifications from code implementations
+
+
+
+
+
+ - HTTP method
+ - Route path
+ - Path parameters
+ - Query parameters
+ - Request body schema
+ - Response schemas
+ - Status codes
+
+
+
+
+
+ - Schema types
+ - Resolvers
+ - Input types
+ - Return types
+ - Field arguments
+
+
+
+
+
+
+
+ Map all dependencies and integration points
+
+
+ Import statements and require calls
+ Package.json dependencies
+ External API calls
+ Database connections
+ Message queue integrations
+ File system operations
+
+
+
+src
+^import\s+.*from\s+['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)
+
+
+
+
+package.json
+
+
+
+
+src
+(fetch|axios|http\.request|request\(|\.get\(|\.post\()
+
+ ]]>
+
+
+
+
+ Extract data models, schemas, and type definitions
+
+
+
+
+ - interface definitions
+ - type aliases
+ - class declarations
+ - enum definitions
+
+
+
+
+ - Schema definitions
+ - Migration files
+ - Model definitions (ORM)
+ - SQL CREATE statements
+
+
+
+
+ - JSON Schema
+ - Joi/Yup schemas
+ - Validation decorators
+ - Custom validators
+
+
+
+
+
+src
+^export\s+(interface|type|class|enum)\s+(\w+)
+
+
+
+
+src/models
+@(Entity|Table|Model)|class\s+\w+\s+extends\s+(Model|BaseEntity)
+
+ ]]>
+
+
+
+
+ Identify and document business rules and logic
+
+
+ Complex conditional statements
+ Calculation functions
+ Validation rules
+ State machines
+ Business-specific constants
+ Domain-specific algorithms
+
+
+ Why the logic exists (business requirement)
+ When the logic applies (conditions)
+ What the logic does (transformation)
+ Edge cases and exceptions
+ Business impact of changes
+
+
+
+
+
+ Document error handling strategies and recovery mechanisms
+
+
+ Try-catch blocks and error boundaries
+ Custom error classes and types
+ Error codes and messages
+ Logging strategies
+ Fallback mechanisms
+ Retry logic
+ Circuit breakers
+
+
+
+src
+try\s*{|catch\s*\(|throw\s+new|class\s+\w*Error\s+extends
+
+
+
+
+src
+ERROR_|_ERROR|ErrorCode|errorCode
+
+ ]]>
+
+
+
+
+ Identify security measures and potential vulnerabilities
+
+
+
+
+ - JWT implementation
+ - Session management
+ - OAuth flows
+ - API key handling
+
+
+
+
+ - Role-based access control
+ - Permission checks
+ - Resource ownership validation
+ - Access control lists
+
+
+
+
+ - Encryption usage
+ - Hashing algorithms
+ - Sensitive data handling
+ - PII protection
+
+
+
+
+ - Input sanitization
+ - SQL injection prevention
+ - XSS protection
+ - CSRF tokens
+
+
+
+
+
+
+
+ Identify performance characteristics and optimization opportunities
+
+
+ Database query patterns (N+1 queries)
+ Caching strategies
+ Async/await usage
+ Batch processing
+ Resource pooling
+ Memory management
+ Algorithm complexity
+
+
+ Time complexity of algorithms
+ Space complexity
+ Database query counts
+ API response times
+ Memory usage patterns
+ Concurrent request handling
+
+
+
+
+
+ Analyze test coverage and quality
+
+
+
+ __tests__, *.test.ts, *.spec.ts
+ Function-level coverage
+
+
+ integration/, e2e/
+ Feature workflow coverage
+
+
+ api-tests/, *.api.test.ts
+ Endpoint coverage
+
+
+
+
+src
+\.(test|spec)\.(ts|js|tsx|jsx)$
+*.test.ts
+
+
+
+
+src
+(describe|it|test)\s*\(\s*['"`]([^'"`]+)['"`]
+
+ ]]>
+
+
+
+
+ Extract all configuration options and their impacts
+
+
+ Environment variables (.env files)
+ Configuration files (config.json, settings.yml)
+ Command-line arguments
+ Feature flags
+ Build-time constants
+
+
+ Default values
+ Valid value ranges
+ Impact on behavior
+ Dependencies between configs
+ Security implications
+
+
+
+
+
+
+
+ Map complete user workflows through the feature
+
+
+ Identify user entry points (UI, API, CLI)
+ Trace user actions through the system
+ Document decision points and branches
+ Map data transformations at each step
+ Identify exit points and outcomes
+
+
+ User flow diagrams
+ Step-by-step procedures
+ Decision trees
+ State transition diagrams
+
+
+
+
+
+ Document how the feature integrates with other systems
+
+
+ Synchronous API calls
+ Asynchronous messaging
+ Event-driven interactions
+ Batch processing
+ Real-time streaming
+
+
+ Integration protocols and formats
+ Authentication mechanisms
+ Error handling and retries
+ Data transformation requirements
+ SLA and performance expectations
+
+
+
+
+
+
+
+ Package.json engines field
+ README compatibility sections
+ Migration guides
+ Breaking change documentation
+
+
+
+.
+"engines":|"peerDependencies":|requires?\s+\w+\s+version|compatible\s+with
+
+ ]]>
+
+
+
+
+ @deprecated annotations
+ TODO: deprecate comments
+ Legacy code markers
+ Migration warnings
+
+
+ Deprecation date
+ Removal timeline
+ Migration path
+ Alternative solutions
+
+
+
+
+
+
+
+ All public APIs documented
+ Examples provided for complex features
+ Error scenarios covered
+ Configuration options explained
+ Security considerations addressed
+
+
+
+
+
+ Cyclomatic complexity
+ Code duplication
+ Test coverage percentage
+ Documentation coverage
+ Technical debt indicators
+
+
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/4_tool_usage_guide.xml b/.roo/rules-docs-extractor/4_tool_usage_guide.xml
new file mode 100644
index 0000000000..a94fdfc0d8
--- /dev/null
+++ b/.roo/rules-docs-extractor/4_tool_usage_guide.xml
@@ -0,0 +1,398 @@
+
+
+ Specific guidance on using tools effectively for comprehensive documentation extraction,
+ with emphasis on gathering complete information across all aspects of a feature.
+
+
+
+
+ codebase_search
+ Initial discovery of feature-related code
+
+
+ Finding feature entry points
+
+authentication login user session JWT token
+
+ ]]>
+
+
+ Locating business logic
+
+calculate pricing discount tax invoice billing
+
+ ]]>
+
+
+ Finding configuration
+
+config settings environment variables .env process.env
+
+ ]]>
+
+
+
+
+
+ list_code_definition_names
+ Understanding code structure and organization
+
+ Use on directories containing core feature logic
+ Analyze both implementation and test directories
+ Look for patterns in naming conventions
+
+
+src/features/authentication
+
+ ]]>
+
+
+
+ read_file
+ Deep analysis of specific implementations
+
+ Read main feature files first
+ Follow imports to understand dependencies
+ Read test files to understand expected behavior
+ Examine configuration and type definition files
+
+
+
+
+ src/controllers/auth.controller.ts
+
+
+ src/services/auth.service.ts
+
+
+ src/models/user.model.ts
+
+
+ src/types/auth.types.ts
+
+
+ src/__tests__/auth.test.ts
+
+
+
+ ]]>
+
+
+
+ search_files
+ Finding specific patterns and implementations
+
+
+ Find all API endpoints
+
+src
+@(Get|Post|Put|Delete|Patch)\(['"]([^'"]+)['"]|router\.(get|post|put|delete|patch)\(['"]([^'"]+)['"]
+
+ ]]>
+
+
+ Find error handling patterns
+
+src
+throw new \w+Error|catch \(|\.catch\(|try \{
+
+ ]]>
+
+
+ Find configuration usage
+
+src
+process\.env\.\w+|config\.get\(['"]([^'"]+)['"]|getConfig\(\)
+
+ ]]>
+
+
+
+
+
+
+
+ Create the final documentation file when generating new documentation from scratch.
+ This tool is NOT used when reviewing a user-provided document section. In that scenario, feedback is provided directly in the chat.
+ DOCS-TEMP-[feature-name].md
+
+ Use descriptive feature names in filename
+ Include table of contents with anchors
+ Use consistent markdown formatting
+ Include code examples with syntax highlighting
+
+
+DOCS-TEMP-authentication-system.md
+
+# Authentication System Documentation
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Architecture](#architecture)
+...
+
+## Overview
+The authentication system provides secure user authentication using JWT tokens...
+
+...
+
+ ]]>
+
+
+
+ Clarify requirements when multiple interpretations exist
+
+ Multiple features with similar names exist
+ Documentation depth needs clarification
+ Target audience priorities need definition
+
+
+
+Which aspects of the authentication system should I focus on?
+
+Complete authentication flow including JWT tokens, session management, and OAuth integration
+Only the JWT token implementation and validation
+OAuth2 integration with external providers
+Password reset and account recovery workflows
+
+
+ ]]>
+
+What level of technical detail should the documentation include?
+
+High-level overview suitable for all audiences
+Detailed technical implementation for developers
+API reference with code examples
+Complete coverage for all audience types
+
+
+ ]]>
+
+
+
+
+
+
+
+ Systematic approach to finding all files related to a feature
+
+
+
+ Start with semantic search
+
+feature implementation main logic core functionality
+
+ ]]>
+
+
+ List directory structure
+
+src/features
+true
+
+ ]]>
+
+
+ Find related tests
+
+src
+describe\(['"].*Feature.*['"]|test\(['"].*feature.*['"]
+*.test.ts
+
+ ]]>
+
+
+ Locate configuration files
+
+.
+feature.*config|settings.*feature
+*.json
+
+ ]]>
+
+
+
+
+
+
+ Follow import chains to understand all dependencies
+
+
+ Read main feature file
+ Extract all imports
+ Read each imported file
+ Recursively analyze their imports
+ Build dependency graph
+
+
+
+src/feature
+import\s+(?:{[^}]+}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]
+
+
+
+
+src/feature
+require\(['"]([^'"]+)['"]\)
+
+ ]]>
+
+
+
+
+ Extract complete API documentation from code
+
+
+ Route definitions
+ Request/response schemas
+ Authentication requirements
+ Rate limiting rules
+ Error responses
+
+
+
+ Find all route files
+ Extract route definitions
+ Find associated controllers
+ Analyze request validation
+ Document response formats
+
+
+
+
+
+
+ Use tests to understand expected behavior
+
+
+ Tests show real usage examples
+ Test descriptions explain functionality
+ Edge cases are often tested
+ Expected outputs are documented
+
+
+
+__tests__
+(describe|it|test)\(['"]([^'"]+)['"]
+
+
+
+
+__tests__/feature.test.ts
+
+ ]]>
+
+
+
+
+
+
+ .env.example
+ config/*.json
+ src/config/*
+ README.md (configuration section)
+
+
+
+
+
+
+ Custom error classes
+ Error code constants
+ Error message templates
+ HTTP status codes
+
+
+src
+class\s+\w*Error\s+extends|new Error\(|throw new|ERROR_CODE|HTTP_STATUS
+
+ ]]>
+
+
+
+
+ Authentication methods
+ Authorization rules
+ Data encryption
+ Input validation
+ Rate limiting
+
+
+src
+@Authorized|requireAuth|checkPermission|encrypt|decrypt|sanitize|validate|rateLimit
+
+ ]]>
+
+
+
+
+
+ Organize output for easy navigation
+
+ - Clear hierarchy with numbered sections
+ - Consistent heading levels
+ - Table of contents with links
+ - Cross-references between sections
+
+
+
+
+ Include relevant code examples
+
+ - Use syntax highlighting
+ - Show both request and response
+ - Include error cases
+ - Provide language-specific examples
+
+
+
+
+ Suggest where diagrams would help
+
+ - Architecture diagrams
+ - Sequence diagrams
+ - Data flow diagrams
+ - State machines
+
+
+
+
+ Always include important metadata
+
+ - Version compatibility
+ - Last updated date
+ - Feature status (stable/beta/deprecated)
+ - Performance characteristics
+ - Security considerations
+
+
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/5_complete_extraction_examples.xml b/.roo/rules-docs-extractor/5_complete_extraction_examples.xml
new file mode 100644
index 0000000000..6248a9587f
--- /dev/null
+++ b/.roo/rules-docs-extractor/5_complete_extraction_examples.xml
@@ -0,0 +1,943 @@
+
+
+ Complete examples demonstrating the full documentation extraction workflow
+ for different types of features and components.
+
+
+
+
+ Extract comprehensive documentation for a JWT-based authentication system
+ including login, logout, token refresh, and role-based access control.
+
+
+
+
+ Initial feature discovery
+
+authentication JWT login logout token refresh auth middleware
+
+ ]]>
+
+ - Auth controller files
+ - JWT service implementations
+ - Middleware functions
+ - User model with auth fields
+ - Auth route definitions
+
+
+
+
+ Analyze authentication structure
+
+src/auth
+
+ ]]>
+
+ - Identify main classes and functions
+ - Map authentication flow
+ - Find token generation/validation logic
+
+
+
+
+ Read core implementation files
+
+
+
+ src/auth/auth.controller.ts
+
+
+ src/auth/auth.service.ts
+
+
+ src/auth/jwt.strategy.ts
+
+
+ src/auth/auth.guard.ts
+
+
+ src/models/user.model.ts
+
+
+
+ ]]>
+
+
+
+ Extract API endpoints
+
+src/auth
+@(Post|Get)\(['"]\/auth\/[^'"]+['"]|router\.(post|get)\(['"]\/auth\/[^'"]+['"]
+
+ ]]>
+
+ - POST /auth/login
+ - POST /auth/logout
+ - POST /auth/refresh
+ - GET /auth/profile
+ - POST /auth/register
+
+
+
+
+ Document configuration
+
+src
+JWT_SECRET|JWT_EXPIRATION|AUTH_.*|process\.env\.\w*AUTH\w*
+
+ ]]>
+
+
+
+ Analyze security measures
+
+src/auth
+bcrypt|hash|salt|encrypt|sanitize|validate|@IsEmail|@MinLength
+
+ ]]>
+
+
+
+ Generate documentation
+
+DOCS-TEMP-authentication-system.md
+
+# Authentication System Documentation
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Quick Start](#quick-start)
+3. [Architecture](#architecture)
+4. [API Reference](#api-reference)
+5. [Configuration](#configuration)
+6. [Security](#security)
+7. [User Guide](#user-guide)
+8. [Developer Guide](#developer-guide)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+### Purpose
+The authentication system provides secure user authentication using JWT (JSON Web Tokens) with support for:
+- User registration and login
+- Token-based authentication
+- Refresh token rotation
+- Role-based access control (RBAC)
+- Session management
+- Password reset functionality
+
+### Key Features
+- **JWT Authentication**: Stateless authentication using signed tokens
+- **Refresh Tokens**: Long-lived tokens for seamless user experience
+- **Role-Based Access**: Fine-grained permission control
+- **Security**: bcrypt password hashing, rate limiting, CSRF protection
+- **Multi-device Support**: Token management across devices
+
+### Version Information
+- **Current Version**: 2.1.0
+- **Minimum Node.js**: 14.0.0
+- **Dependencies**:
+ - jsonwebtoken: ^9.0.0
+ - bcrypt: ^5.1.0
+ - passport: ^0.6.0
+
+---
+
+## Quick Start
+
+### For Users
+1. Register a new account:
+ ```bash
+ POST /api/auth/register
+ {
+ "email": "user@example.com",
+ "password": "SecurePassword123!",
+ "name": "John Doe"
+ }
+ ```
+
+2. Login to receive tokens:
+ ```bash
+ POST /api/auth/login
+ {
+ "email": "user@example.com",
+ "password": "SecurePassword123!"
+ }
+ ```
+
+3. Use the access token in subsequent requests:
+ ```bash
+ Authorization: Bearer
+ ```
+
+### For Developers
+```typescript
+// Import authentication module
+import { AuthModule } from './auth/auth.module';
+
+// Configure in app module
+@Module({
+ imports: [
+ AuthModule.forRoot({
+ jwtSecret: process.env.JWT_SECRET,
+ jwtExpiration: '15m',
+ refreshExpiration: '7d'
+ })
+ ]
+})
+export class AppModule {}
+```
+
+---
+
+## Architecture
+
+### System Overview
+```
+┌─────────────┐ ┌──────────────┐ ┌─────────────┐
+│ Client │────▶│ Auth Guard │────▶│ Service │
+└─────────────┘ └──────────────┘ └─────────────┘
+ │ │
+ ▼ ▼
+ ┌──────────────┐ ┌─────────────┐
+ │ JWT Strategy │ │ Database │
+ └──────────────┘ └─────────────┘
+```
+
+### Components
+- **AuthController**: Handles HTTP requests for authentication endpoints
+- **AuthService**: Core authentication logic and token management
+- **JwtStrategy**: Passport strategy for JWT validation
+- **AuthGuard**: Route protection middleware
+- **UserService**: User management and database operations
+
+### Token Flow
+1. User provides credentials
+2. System validates credentials against database
+3. Generate access token (short-lived) and refresh token (long-lived)
+4. Client stores tokens securely
+5. Access token used for API requests
+6. Refresh token used to obtain new access token
+
+---
+
+## API Reference
+
+### Authentication Endpoints
+
+#### `POST /api/auth/register`
+Register a new user account.
+
+**Request Body**:
+```json
+{
+ "email": "string (required)",
+ "password": "string (required, min 8 chars)",
+ "name": "string (required)",
+ "role": "string (optional, default: 'user')"
+}
+```
+
+**Response** (201 Created):
+```json
+{
+ "user": {
+ "id": "uuid",
+ "email": "user@example.com",
+ "name": "John Doe",
+ "role": "user",
+ "createdAt": "2024-01-01T00:00:00Z"
+ },
+ "tokens": {
+ "accessToken": "jwt_token",
+ "refreshToken": "refresh_token",
+ "expiresIn": 900
+ }
+}
+```
+
+**Error Responses**:
+- `400 Bad Request`: Invalid input data
+- `409 Conflict`: Email already exists
+
+#### `POST /api/auth/login`
+Authenticate user and receive tokens.
+
+**Request Body**:
+```json
+{
+ "email": "string (required)",
+ "password": "string (required)"
+}
+```
+
+**Response** (200 OK):
+```json
+{
+ "user": {
+ "id": "uuid",
+ "email": "user@example.com",
+ "name": "John Doe",
+ "role": "user"
+ },
+ "tokens": {
+ "accessToken": "jwt_token",
+ "refreshToken": "refresh_token",
+ "expiresIn": 900
+ }
+}
+```
+
+**Error Responses**:
+- `401 Unauthorized`: Invalid credentials
+- `429 Too Many Requests`: Rate limit exceeded
+
+#### `POST /api/auth/refresh`
+Refresh access token using refresh token.
+
+**Request Body**:
+```json
+{
+ "refreshToken": "string (required)"
+}
+```
+
+**Response** (200 OK):
+```json
+{
+ "accessToken": "new_jwt_token",
+ "expiresIn": 900
+}
+```
+
+#### `POST /api/auth/logout`
+Invalidate refresh token.
+
+**Headers**:
+- `Authorization: Bearer `
+
+**Request Body**:
+```json
+{
+ "refreshToken": "string (required)"
+}
+```
+
+**Response** (200 OK):
+```json
+{
+ "message": "Logged out successfully"
+}
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `JWT_SECRET` | string | - | Secret key for signing JWT tokens (required) |
+| `JWT_EXPIRATION` | string | '15m' | Access token expiration time |
+| `REFRESH_TOKEN_EXPIRATION` | string | '7d' | Refresh token expiration time |
+| `BCRYPT_ROUNDS` | number | 10 | Number of bcrypt hashing rounds |
+| `AUTH_RATE_LIMIT` | number | 5 | Max login attempts per minute |
+| `ENABLE_2FA` | boolean | false | Enable two-factor authentication |
+
+### Configuration File (auth.config.ts)
+```typescript
+export const authConfig = {
+ jwt: {
+ secret: process.env.JWT_SECRET,
+ signOptions: {
+ expiresIn: process.env.JWT_EXPIRATION || '15m',
+ issuer: 'your-app-name',
+ audience: 'your-app-users'
+ }
+ },
+ bcrypt: {
+ rounds: parseInt(process.env.BCRYPT_ROUNDS || '10')
+ },
+ session: {
+ maxDevices: 5,
+ inactivityTimeout: '30d'
+ }
+};
+```
+
+---
+
+## Security
+
+### Authentication Flow
+1. **Password Storage**: Passwords hashed using bcrypt with configurable rounds
+2. **Token Security**: JWT tokens signed with RS256 algorithm
+3. **Refresh Token Rotation**: New refresh token issued on each refresh
+4. **Rate Limiting**: Prevents brute force attacks on login endpoint
+
+### Security Best Practices
+- Store tokens securely (httpOnly cookies recommended)
+- Implement CSRF protection for cookie-based auth
+- Use HTTPS in production
+- Rotate JWT secrets periodically
+- Implement account lockout after failed attempts
+- Enable 2FA for sensitive accounts
+
+### Common Vulnerabilities Addressed
+- **SQL Injection**: Parameterized queries
+- **XSS**: Input sanitization and validation
+- **CSRF**: Token validation
+- **Brute Force**: Rate limiting and account lockout
+- **Token Hijacking**: Short expiration times and refresh rotation
+
+---
+
+## User Guide
+
+### Registration Process
+1. Navigate to registration page
+2. Enter email, password, and name
+3. Verify email (if enabled)
+4. Login with credentials
+
+### Managing Sessions
+- View active sessions in account settings
+- Revoke sessions from other devices
+- Set session timeout preferences
+
+### Password Management
+- Change password from profile settings
+- Reset forgotten password via email
+- Password requirements:
+ - Minimum 8 characters
+ - At least one uppercase letter
+ - At least one number
+ - At least one special character
+
+---
+
+## Developer Guide
+
+### Protecting Routes
+```typescript
+// Use AuthGuard decorator
+@UseGuards(AuthGuard('jwt'))
+@Get('protected')
+async getProtectedData() {
+ return { data: 'This is protected' };
+}
+
+// Role-based protection
+@UseGuards(AuthGuard('jwt'), RolesGuard)
+@Roles('admin')
+@Get('admin')
+async getAdminData() {
+ return { data: 'Admin only' };
+}
+```
+
+### Custom Authentication Logic
+```typescript
+// Extend AuthService
+export class CustomAuthService extends AuthService {
+ async validateUser(email: string, password: string): Promise {
+ // Add custom validation logic
+ const user = await super.validateUser(email, password);
+
+ // Additional checks
+ if (user.suspended) {
+ throw new UnauthorizedException('Account suspended');
+ }
+
+ return user;
+ }
+}
+```
+
+### Testing Authentication
+```typescript
+describe('AuthController', () => {
+ it('should login user', async () => {
+ const response = await request(app.getHttpServer())
+ .post('/auth/login')
+ .send({
+ email: 'test@example.com',
+ password: 'TestPass123!'
+ })
+ .expect(200);
+
+ expect(response.body).toHaveProperty('tokens.accessToken');
+ });
+});
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### Invalid Token Error
+**Problem**: "JsonWebTokenError: invalid token"
+**Solutions**:
+- Verify token format (Bearer prefix)
+- Check token expiration
+- Ensure JWT_SECRET matches
+
+#### Login Rate Limit
+**Problem**: "429 Too Many Requests"
+**Solutions**:
+- Wait for rate limit window to reset
+- Check AUTH_RATE_LIMIT configuration
+- Implement exponential backoff
+
+#### CORS Issues
+**Problem**: "Access blocked by CORS policy"
+**Solutions**:
+- Configure CORS middleware
+- Add origin to allowed list
+- Check preflight requests
+
+### Debug Mode
+Enable debug logging:
+```bash
+DEBUG=auth:* npm start
+```
+
+### Support
+- GitHub Issues: [github.com/yourapp/issues](https://github.com/yourapp/issues)
+- Documentation: [docs.yourapp.com/auth](https://docs.yourapp.com/auth)
+- Email: support@yourapp.com
+
+---
+
+## Changelog
+
+### v2.1.0 (2024-01-15)
+- Added refresh token rotation
+- Improved rate limiting
+- Fixed security vulnerability in password reset
+
+### v2.0.0 (2023-12-01)
+- Breaking: Changed token format
+- Added 2FA support
+- Improved session management
+
+### Migration Guide (v1.x to v2.x)
+1. Update JWT_SECRET format
+2. Run token migration script
+3. Update client-side token handling
+
+---
+
+## References
+- [JWT.io](https://jwt.io) - JWT Documentation
+- [OWASP Authentication Guide](https://owasp.org/www-project-cheat-sheets/cheatsheets/Authentication_Cheat_Sheet)
+- [Passport.js Documentation](http://www.passportjs.org/docs/)
+
+450
+
+ ]]>
+
+
+
+
+ Start with semantic search to find all related files
+ Read multiple files together for context
+ Extract API documentation from route definitions
+ Use tests to understand expected behavior
+ Document security measures comprehensively
+ Include troubleshooting based on common errors
+
+
+
+
+
+ Extract documentation for database models, relationships, migrations,
+ and data access patterns.
+
+
+
+
+ Find database-related files
+
+database schema model entity migration table column relationship
+
+ ]]>
+
+
+
+ Analyze model definitions
+
+src/models
+@(Entity|Table|Model)|class\s+\w+\s+extends\s+(Model|BaseEntity)
+
+ ]]>
+
+
+
+ Extract relationships
+
+src/models
+@(OneToMany|ManyToOne|OneToOne|ManyToMany|BelongsTo|HasMany)
+
+ ]]>
+
+
+
+ Document migrations
+
+migrations
+true
+
+ ]]>
+
+
+
+ Generate schema documentation
+
+
+
+
+
+
+
+ Extract comprehensive API documentation including all endpoints,
+ request/response formats, authentication, and examples.
+
+
+
+
+ Find all API routes
+
+src
+(app|router)\.(get|post|put|patch|delete|all)\s*\(\s*['"`]([^'"`]+)['"`]
+
+ ]]>
+
+
+
+ Extract request validation
+
+src
+@(Body|Query|Param|Headers)\(|joi\.object|yup\.object|zod\.object
+
+ ]]>
+
+
+
+ Find response schemas
+
+src
+@ApiResponse|swagger|openapi|response\.json\(|res\.send\(
+
+ ]]>
+
+
+
+ Document authentication requirements
+
+src
+@(UseGuards|Authorized|Public)|passport\.authenticate|requireAuth
+
+ ]]>
+
+
+
+ Generate OpenAPI/Swagger documentation
+
+ - OpenAPI 3.0 specification
+ - Postman collection
+ - API client examples
+ - cURL commands
+ - SDK usage examples
+
+
+
+
+
+
+
+ Document React/Vue/Angular components including props, events,
+ slots, styling, and usage examples.
+
+
+
+
+ Find component files
+
+src/components
+export\s+(default\s+)?(function|class|const)\s+\w+|@Component
+*.tsx
+
+ ]]>
+
+
+
+ Extract component props/inputs
+
+src/components
+interface\s+\w+Props|type\s+\w+Props|@Input\(\)|props:\s*{
+
+ ]]>
+
+
+
+ Find component usage examples
+
+src
+
+
+ ]]>
+
+
+
+ Document styling and themes
+
+src/components
+styled\.|makeStyles|@apply|className=|style=
+
+ ]]>
+
+
+
+ Extract Storybook stories
+
+src
+export\s+default\s+{.*title:|\.stories\.
+*.stories.tsx
+
+ ]]>
+
+
+
+ Generate component documentation
+
+
+
+
+
+
+
+ Document all configuration options, environment variables,
+ feature flags, and their impacts on system behavior.
+
+
+
+
+ Find configuration files
+
+.
+false
+
+ ]]>
+
+ - .env.example
+ - config/
+ - settings.json
+ - app.config.ts
+
+
+
+
+ Extract environment variables
+
+.
+process\.env\.(\w+)|getenv\(['"](\w+)['"]\)
+
+ ]]>
+
+
+
+ Find feature flags
+
+src
+feature\.|featureFlag|isEnabled\(['"]|flags\.
+
+ ]]>
+
+
+
+ Document configuration impacts
+
+ - How each config affects behavior
+ - Dependencies between configs
+ - Performance implications
+ - Security considerations
+ - Default values and overrides
+
+
+
+
+ Generate configuration guide
+
+
+
+
+
+
+ Review a user-provided documentation section for accuracy against the codebase
+ and provide recommendations for improvement in the chat.
+
+
+
+ User provides documentation for review
+
+ "Here's our current draft for the JWT_SECRET setting. Can you check it for accuracy? 'The `JWT_SECRET` is an optional key for enhancing security.'"
+
+
+
+ Analyze relevant code
+
+JWT_SECRET configuration implementation
+
+ ]]>
+
+ - Code where `JWT_SECRET` is read (e.g., `process.env.JWT_SECRET`)
+ - Logic that fails if the secret is missing
+ - Default values or error handling related to the secret
+
+
+
+ Formulate and provide feedback in chat
+
+
+I have reviewed the documentation section provided for the `JWT_SECRET` setting. Here are my recommendations for improvement:
+
+**Overall Assessment**: The current draft is critically inaccurate and could lead to security vulnerabilities if followed.
+
+**Recommendations for Improvement**:
+
+* **Critical Inaccuracy**:
+ * The documentation states that `JWT_SECRET` is optional. However, the application will fail to start if it is not provided. It is a **required** setting for the application to function securely.
+ * **Suggestion**: "The `JWT_SECRET` is a **required** environment variable used to sign and verify JSON Web Tokens. The application will not run without it."
+
+This feedback can be copied and pasted for your documentation team.
+
+
+ ]]>
+ No file is written. The feedback is provided directly to the user in the chat interface.
+
+
+
+
+
+
+ Ensure all aspects are documented
+
+ - Technical implementation details
+ - Business logic and rules
+ - User workflows and journeys
+ - API specifications
+ - Configuration options
+ - Security measures
+ - Performance characteristics
+ - Error handling
+ - Testing strategies
+ - Deployment procedures
+
+
+
+
+ Tailor content for different readers
+
+
+ Focus on how-to guides and troubleshooting
+
+
+ Include code examples and technical details
+
+
+ Emphasize configuration and maintenance
+
+
+ Highlight business value and metrics
+
+
+
+
+
+ Create documentation that's easy to update
+
+ Use clear section headers
+ Include version information
+ Add last-updated timestamps
+ Cross-reference related sections
+ Provide migration guides
+
+
+
+
+ Include practical examples throughout
+
+ Code snippets with syntax highlighting
+ API request/response pairs
+ Configuration examples
+ Command-line usage
+ Error scenarios and solutions
+
+
+
+
+
+
+ - Table of contents with working links
+ - All sections properly formatted
+ - Code examples are syntactically correct
+ - No placeholder text remaining
+ - Version information included
+ - Cross-references are valid
+ - Metadata is complete
+ - File follows naming convention
+
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/6_communication_guidelines.xml b/.roo/rules-docs-extractor/6_communication_guidelines.xml
new file mode 100644
index 0000000000..aed30f4094
--- /dev/null
+++ b/.roo/rules-docs-extractor/6_communication_guidelines.xml
@@ -0,0 +1,323 @@
+
+
+ Guidelines for communicating with users and formatting documentation output
+ during the extraction process.
+
+
+
+
+ Users will specify what they want documented in their initial message
+ Start working immediately based on their request
+ Only ask for clarification if genuinely ambiguous
+
+
+
+
+ Multiple features with identical names found
+ Request is genuinely ambiguous (rare)
+ User explicitly asks for options
+
+
+
+I found multiple authentication systems. Which one should I document?
+
+JWT-based authentication system (src/auth/jwt/*)
+OAuth2 integration (src/auth/oauth/*)
+Basic authentication middleware (src/middleware/basic-auth.ts)
+All authentication features comprehensively
+
+
+ ]]>
+
+
+
+
+ Starting major analysis phase
+ Completed significant extraction
+ Found unexpected complexity
+ Discovered related features
+
+
+
+
+ Analyzing [component/feature]...
+ - Found [X] files related to [feature]
+ - Identified [Y] API endpoints
+ - Discovered [Z] configuration options
+
+
+
+
+
+
+
+ Alert user to potential security concerns found during analysis
+
+
+ Note deprecated features that need migration documentation
+
+
+ Highlight areas where code lacks inline documentation
+
+
+ Warn about intricate dependency chains affecting the feature
+
+
+
+
+
+
+
+
+
+
+
+ Use # for main title only
+ Use ## for major sections
+ Use ### for subsections
+ Use #### sparingly for minor subsections
+ Never skip heading levels
+
+
+
+ Always specify language for syntax highlighting
+ Use appropriate language identifiers (typescript, javascript, json, yaml, bash)
+ Include file paths as comments when relevant
+ {
+ // Implementation
+ }
+}
+```
+ ]]>
+
+
+
+ Use tables for structured data like configurations
+ Include headers with proper alignment
+ Keep cell content concise
+
+
+
+
+ Use bullet points for unordered lists
+ Use numbers for sequential steps
+ Nest lists with proper indentation
+ Keep list items parallel in structure
+
+
+
+
+
+ [Link text](#section-anchor)
+ Use lowercase, hyphenated anchors
+ Test all internal links
+
+
+
+ [Link text](https://example.com)
+ Use HTTPS when available
+ Link to official documentation
+
+
+
+ `path/to/file.ts`
+ Use relative paths from project root
+ Use backticks for inline file references
+
+
+
+
+
+
+ > ⚠️ **Warning**: [message]
+ Security concerns, breaking changes, deprecations
+
+
+ > 📝 **Note**: [message]
+ Important information, clarifications
+
+
+ > 💡 **Tip**: [message]
+ Best practices, optimization suggestions
+
+
+
+
+
+
+
+
+
+
+
+ Be conversational and approachable
+ Use active voice and "you" to address the reader
+ Lead with benefits, not features
+ Use concrete examples and scenarios
+ Keep paragraphs short and scannable
+ Avoid unnecessary technical details
+
+
+
+ Write as if explaining to a colleague who isn't technical
+ Use analogies and comparisons to familiar concepts
+ Focus on "what" and "why" before "how"
+ Include practical examples users can relate to
+ Address common concerns and questions directly
+
+
+
+
+ Friendly, helpful, encouraging
+ Plain language, minimal jargon
+ Real-world scenarios, before/after comparisons
+ Problem → Solution → Benefits → How to use
+
+
+
+ Technical when needed, but still approachable
+ Use standard programming terminology
+ Include code snippets and implementation details
+
+
+
+ Friendly, instructional, step-by-step
+ Avoid technical jargon, explain concepts simply
+ Use screenshots and real-world scenarios
+
+
+
+ Professional, operational focus
+ Use IT/DevOps terminology
+ Include command-line examples and configurations
+
+
+
+ Business-oriented, value-focused
+ Use business terminology, avoid implementation details
+ Include metrics, ROI, and business benefits
+
+
+
+
+
+
+ Summary of what was documented
+ Key findings or insights
+ File location and name
+ Suggestions for next steps (if applicable)
+
+
+
+
+
+
+
+
+
+
+ I couldn't find a feature matching "[feature name]". Here are some similar features I found:
+ - [List similar features]
+ Would you like me to document one of these instead?
+
+
+
+
+
+ The code for [feature] has limited inline documentation. I'll extract what I can from:
+ - Code structure and naming
+ - Test files
+ - Related documentation
+ - Usage patterns
+
+
+
+
+
+ This feature is quite complex with [X] components. Would you like me to:
+ - Document everything comprehensively (may result in a large document)
+ - Focus on the core functionality
+ - Split into multiple documentation files
+
+
+
+
+
+
+
+ All sections have content (no placeholders)
+ Code examples are syntactically correct
+ Links and cross-references work
+ Tables are properly formatted
+ Version information is included
+ File naming follows convention
+
+
+
\ No newline at end of file
diff --git a/.roo/rules-docs-extractor/7_user_friendly_examples.xml b/.roo/rules-docs-extractor/7_user_friendly_examples.xml
new file mode 100644
index 0000000000..9de359a62a
--- /dev/null
+++ b/.roo/rules-docs-extractor/7_user_friendly_examples.xml
@@ -0,0 +1,254 @@
+
+
+ Examples and patterns for creating documentation that prioritizes user experience
+ and practical understanding over technical completeness.
+
+
+
+
+ The concurrent file read feature uses parallel processing to read multiple files.
+ Read multiple files at once, saving time and reducing interruptions.
+
+
+
+ This feature improves efficiency.
+ Instead of approving 10 file reads one by one, approve them all at once and get your answer faster.
+
+
+
+ The feature uses a thread pool with configurable concurrency limits to process file I/O operations.
+ Roo can read up to 100 files at once (you can change this limit in settings).
+
+
+
+ Users must configure the concurrent file read limit parameter.
+ You can adjust how many files Roo reads at once in the settings.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ The system imposes a hard limit of 100 concurrent operations.
+ Roo can handle up to 100 files at once - more than enough for most projects!
+
+
+
+ Error: Maximum concurrency threshold exceeded.
+ Oops! That's too many files at once. Try lowering the file limit in settings.
+
+
+
+ Reduces API call overhead through request batching.
+ Get answers faster by reading all the files Roo needs in one go.
+
+
+
+
+
+ Error messages: ⚠️
+ Tips: 💡
+ Important notes: 📝
+ Security: 🔒
+
+
+
+ For emphasis on key points
+ For settings names, file paths, or commands
+ For important callouts or warnings
+
+
+
+
+
+ Concurrent File Reads Documentation
+
+
+
+
+ - Does it start with benefits, not features?
+ - Are technical terms explained or avoided?
+ - Does it use "you" to address the reader?
+ - Are there practical examples or scenarios?
+ - Is the tone conversational and friendly?
+ - Are sections short and scannable?
+ - Does it answer common user questions?
+ - Is help easily accessible?
+
+
\ No newline at end of file
diff --git a/.roomodes b/.roomodes
index 8ed5d99084..584afe105a 100644
--- a/.roomodes
+++ b/.roomodes
@@ -198,3 +198,18 @@ customModes:
- mcp
- command
source: project
+
+ - slug: docs-extractor
+ name: 📚 Docs Extractor
+ roleDefinition: >-
+ You are Roo, a comprehensive documentation extraction specialist focused on analyzing and documenting all technical and non-technical information about features and components within codebases.
+ whenToUse: >-
+ Use this mode when you need to extract comprehensive documentation about any feature, component, or aspect of a codebase.
+ groups:
+ - read
+ - - edit
+ - fileRegex: (DOCS-TEMP-.*\.md$|\.roo/docs-extractor/.*\.md$)
+ description: Temporary documentation extraction files only
+ - command
+ - mcp
+