nest-scramble 1.8.2 → 1.8.4

package/README.md

@@ -1,749 +1,765 @@
-# Nest-Scramble
-
-> Zero-config API Documentation & Postman Generator for NestJS using static analysis
-
-[![npm version](https://badge.fury.io/js/nest-scramble.svg)](https://badge.fury.io/js/nest-scramble)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub stars](https://img.shields.io/github/stars/Eng-MMustafa/nest-scramble.svg)](https://github.com/Eng-MMustafa/nest-scramble)
-[![Author](https://img.shields.io/badge/Author-Mohamed%20Mustafa-blue.svg)](https://github.com/Eng-MMustafa)
-
-## 🚀 Why Nest-Scramble?
-
-As a NestJS developer, I was tired of drowning in `@ApiProperty` decorators just to get basic API documentation. I longed for a zero-config solution where docs just worked without polluting my code. **Nest-Scramble changes that** by using static TypeScript analysis to automatically generate:
-
-- ✅ **OpenAPI 3.0 specifications** from your DTOs
-- ✅ **Interactive Scalar UI documentation** with zero configuration
-- ✅ **Postman collections** with smart mock data
-- ✅ **Live mocking** for rapid prototyping
-
-**Zero configuration. Zero decorators. Just pure TypeScript.**
-
-## 📖 The Story Behind Nest-Scramble
-
-It all started with a vision: API documentation should be effortless. As a developer passionate about clean code and developer experience, I knew there had to be a better way than manual decorators and runtime reflection.
-
-When I switched to NestJS for its powerful architecture and TypeScript-first approach, I was disappointed by the lack of zero-config documentation tools. Hours wasted on `@ApiProperty({ type: String })` instead of building features.
-
-I knew there had to be a better way. Leveraging my expertise in static analysis and Abstract Syntax Trees (AST), I built Nest-Scramble to bring that same developer experience to the Node.js ecosystem. It's not just a tool—it's my mission to make API documentation as effortless as it should be.
-
-## 🏆 Features Gallery
-
-| Feature | Nest-Scramble | Swagger (@nestjs/swagger) |
-|---------|---------------|---------------------------|
-| Analysis Method | Static AST Traversal | Runtime Reflection |
-| Performance Impact | Zero Overhead | Decorator Runtime Cost |
-| Type Accuracy | Full TypeScript Inference | Partial Mapping |
-| Circular References | Auto-Detected & Resolved | Manual Workarounds |
-| Bundle Size | Minimal | Heavy with Decorators |
-| Code Purity | Zero Decorators | Decorator Pollution |
-| Future Compatibility | TypeScript Evolution Ready | Framework Dependent |
-
-## 🧠 The Vision
-
-Nest-Scramble embodies my engineering philosophy: **Clean Code through Automation**. As a developer who values TypeScript's type safety and NestJS's architecture, I believe that documentation should never compromise code quality.
-
-This library represents a paradigm shift—from manual, error-prone decorators to intelligent, compile-time analysis. It's about empowering developers to focus on building features, not fighting frameworks.
-
-## 🔬 How it's Built
-
-Nest-Scramble is engineered using cutting-edge static analysis techniques that traditional tools cannot match:
-
-- **Abstract Syntax Tree (AST) Traversal**: Direct manipulation of TypeScript's AST using `ts-morph` for unparalleled type inference
-- **Zero-Decorator Architecture**: Pure TypeScript classes remain untouched, preserving domain integrity
-- **Compile-Time Intelligence**: All analysis happens at build-time, eliminating runtime performance costs
-- **Circular Reference Mastery**: Advanced algorithms detect and handle complex type relationships automatically
-
-This approach delivers what runtime reflection simply cannot: perfect accuracy, zero overhead, and future-proof compatibility with TypeScript's evolving type system.
-
-## ⚡ Quick Start - Zero Config (2 Steps!)
-
-### Option A: Auto-Injection (Recommended - 30 seconds!)
-
-```bash
-# 1. Install
-npm install nest-scramble
-
-# 2. Auto-inject into your project
-npx nest-scramble init
-
-# 3. Start your app
-npm run start:dev
-
-# 🎉 Done! Visit http://localhost:3000/docs
-```
-
-The `init` command automatically:
-- ✅ Adds the import statement to your `app.module.ts`
-- ✅ Injects `NestScrambleModule.forRoot()` into your imports
-- ✅ Uses smart defaults with zero configuration needed
-
-### Option B: Manual Installation (3 Steps)
-
-#### 1. Install the Package
-
-```bash
-# Using npm
-npm install nest-scramble
-
-# Using yarn
-yarn add nest-scramble
-
-# Using pnpm
-pnpm add nest-scramble
-```
-
-#### 2. Import Module in Your NestJS App
-
-**Zero-Config (Recommended):**
-```typescript
-import { Module } from '@nestjs/common';
-import { NestScrambleModule } from 'nest-scramble';
-
-@Module({
-  imports: [
-    NestScrambleModule.forRoot(), // 🎯 That's it! Zero config needed
-  ],
-})
-export class AppModule {}
-```
-
-**With Custom Options:**
-```typescript
-import { Module } from '@nestjs/common';
-import { NestScrambleModule } from 'nest-scramble';
-
-@Module({
-  imports: [
-    NestScrambleModule.forRoot({
-      sourcePath: 'src',              // Auto-detected by default
-      baseUrl: 'http://localhost:3000', // Auto-detected from PORT env
-      enableMock: true,               // Enabled by default
-      autoExportPostman: false,       // Disabled by default
-      apiTitle: 'My API',             // Auto-detected from package.json
-      apiVersion: '1.0.0',            // Auto-detected from package.json
-    }),
-  ],
-})
-export class AppModule {}
-```
-
-#### 3. Start Your App and Visit Documentation
-
-```bash
-npm run start:dev
-```
-
-You'll see a beautiful dashboard in your terminal:
-
-```
-┌──────────────────────────────────────────────────────────┐
-│  🚀 Nest-Scramble by Mohamed Mustafa is Active!          │
-├──────────────────────────────────────────────────────────┤
-│  📖 Docs: http://localhost:3000/docs                     │
-│  📄 JSON: http://localhost:3000/docs-json                │
-│  🎭 Mock: http://localhost:3000/scramble-mock            │
-│  ✨ Scanning: src                                        │
-│  🎯 Controllers: 5                                       │
-└──────────────────────────────────────────────────────────┘
-```
-
-Then open your browser:
-
-- **📖 Professional API Docs (Modal UI)**: http://localhost:3000/docs
-- **📄 OpenAPI JSON Spec**: http://localhost:3000/docs-json
-- **🎭 Mock Endpoints**: http://localhost:3000/scramble-mock/*
-
-**That's it!** Nest-Scramble automatically:
-- 🔍 Detects your project structure
-- 📂 Finds your controllers
-- 📝 Generates OpenAPI spec
-- 🎨 Serves beautiful documentation
-- 🎭 Provides mock endpoints
-
-## ⚙️ Configuration Options
-
-```typescript
-NestScrambleModule.forRoot({
-  // Documentation path served by the module
-  path: '/docs',                        // default: '/docs'
-
-  // Source directory to scan for controllers
-  sourcePath: 'src',                    // default: 'src'
-
-  // API base URL for OpenAPI spec
-  baseUrl: 'http://localhost:3000',     // default: 'http://localhost:3000'
-
-  // Enable live mocking endpoints under /scramble-mock/*
-  enableMock: true,                     // default: true
-
-  // Auto-export a Postman collection when generating
-  autoExportPostman: true,
-  postmanOutputPath: 'collection.json',
-
-  // API metadata
-  apiTitle: 'My API',                   // API documentation title
-  apiVersion: '1.0.0',                  // API version number
-})
-```
-
-### Configuration Details
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `path` | `string` | `'/docs'` | Documentation route path |
-| `sourcePath` | `string` | `'src'` | Directory where your NestJS controllers are located |
-| `baseUrl` | `string` | `'http://localhost:3000'` | Base URL for your API (used in OpenAPI spec) |
-| `enableMock` | `boolean` | `true` | Enable `/scramble-mock/*` endpoints for testing |
-| `autoExportPostman` | `boolean` | `false` | Automatically generate Postman collection file |
-| `postmanOutputPath` | `string` | `'collection.json'` | Output path for Postman collection |
-| `apiTitle` | `string` | Auto-detected | API documentation title |
-| `apiVersion` | `string` | Auto-detected | API version number |
-
-## 🎭 Live Mocking Guide
-
-Nest-Scramble provides **instant API mocking** without writing controllers:
-
-### How It Works
-1. Define your DTOs and controllers normally
-2. Enable `enableMock: true`
-3. All requests to `/scramble-mock/*` return smart mock data
-
-### Example
-
-**Controller:**
-```typescript
-@Controller('users')
-export class UserController {
-  @Get(':id')
-  getUser(@Param('id') id: number): UserDto {
-    // Your logic here
-  }
-}
-```
-
-**Mock Response:**
-```bash
-GET /scramble-mock/users/123
-# Returns: { "id": 123, "name": "John Doe", "email": "john@example.com" }
-```
-
-**Smart Mocking Examples:**
-- `email` → `faker.internet.email()`
-- `name` → `faker.person.fullName()`
-- `createdAt` → `faker.date.recent()`
-- `posts` → Array of mock posts
-
-![Live mocking demo](mock-demo.gif)
-
-## 🔧 Advanced Usage
-
-### CLI Generation
-
-The Nest-Scramble CLI allows you to generate API documentation without running your NestJS application.
-
-#### Generate OpenAPI Specification
-
-```bash
-# Using npx
-npx nest-scramble generate src
-
-# Using pnpm dlx
-pnpm dlx nest-scramble generate src
-
-# Using yarn dlx
-yarn dlx nest-scramble generate src
-```
-
-#### CLI Options
-
-```bash
-nest-scramble generate <sourcePath> [options]
-
-Options:
-  -o, --output <file>         Output file path (default: "openapi.json")
-  -f, --format <type>         Output format: openapi or postman (default: "openapi")
-  -b, --baseUrl <url>         Base URL for the API (default: "http://localhost:3000")
-  -t, --title <title>         API title (default: "NestJS API")
-  -v, --apiVersion <version>  API version (default: "1.0.0")
-  -h, --help                  Display help for command
-```
-
-#### Examples
-
-**Generate OpenAPI JSON:**
-```bash
-pnpm dlx nest-scramble generate src --output openapi.json
-```
-
-**Generate Postman Collection:**
-```bash
-pnpm dlx nest-scramble generate src --format postman --output collection.json
-```
-
-**Custom API Details:**
-```bash
-pnpm dlx nest-scramble generate src \
-  --output my-api.json \
-  --title "My Awesome API" \
-  --apiVersion "2.0.0" \
-  --baseUrl "https://api.example.com"
-```
-
-**Check Version:**
-```bash
-pnpm dlx nest-scramble --version
-```
-
-### Programmatic API
-
-Use Nest-Scramble programmatically in your Node.js scripts:
-
-```typescript
-import { ScannerService, OpenApiTransformer, PostmanCollectionGenerator } from 'nest-scramble';
-import * as fs from 'fs';
-
-// Scan controllers
-const scanner = new ScannerService();
-const controllers = scanner.scanControllers('src');
-
-// Generate OpenAPI spec
-const transformer = new OpenApiTransformer('http://localhost:3000');
-const openApiSpec = transformer.transform(
-  controllers,
-  'My API',
-  '1.0.0',
-  'http://localhost:3000'
-);
-
-// Save to file
-fs.writeFileSync('openapi.json', JSON.stringify(openApiSpec, null, 2));
-
-// Or generate Postman collection
-const postmanGen = new PostmanCollectionGenerator('http://localhost:3000');
-const collection = postmanGen.generateCollection(controllers);
-fs.writeFileSync('collection.json', JSON.stringify(collection, null, 2));
-```
-
-### CI/CD Integration
-
-Add to your CI/CD pipeline to auto-generate documentation:
-
-```yaml
-# .github/workflows/docs.yml
-name: Generate API Docs
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  generate-docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      - run: npm install
-      - run: npx nest-scramble generate src --output openapi.json
-      - uses: actions/upload-artifact@v3
-        with:
-          name: api-docs
-          path: openapi.json
-```
-
-## 🎨 Documentation UI - Professional API Dashboard
-
-### ✨ Professional Dashboard Design (NEW!)
-
-Nest-Scramble features a **modern, professional API dashboard** where each request is displayed on a separate page with focused documentation and beautiful interactions!
-
-**🚀 Key Features:**
-- **Separate Pages Per Endpoint** - Each request opens in its own modal with dedicated view
-- **Smart Search & Filtering** - Real-time search across all endpoints
-- **Controller Grouping** - Endpoints organized by tags with counters
-- **Gradient Backgrounds** - Dynamic colors based on your brand
-- **Smooth Animations** - Professional transitions and hover effects
-- **Color-Coded HTTP Methods** - Visual distinction for different request types:
-  - GET = Green (`#c6f6d5`)
-  - POST = Blue (`#bee3f8`)
-  - PUT = Orange (`#feebc8`)
-  - PATCH = Purple (`#e9d8fd`)
-  - DELETE = Red (`#fed7d7`)
-- **Professional Typography** - Clean, readable fonts with proper hierarchy
-- **Responsive Design** - Works perfectly on desktop, tablet, and mobile
-- **Modal-Based Navigation** - Clean overlay system for endpoint details
-- **Parameter Documentation** - Clear display of request parameters and types
-- **Response Examples** - Formatted JSON responses with syntax highlighting
-
-### 📐 Single-Request Interface
-
-Each endpoint gets its own dedicated modal view with organized sections:
-
-**Header Section:**
-- Large HTTP method badge with color coding
-- Full endpoint path in monospace font
-- Summary and description of the endpoint
-- Close button with rotation animation
-
-**Information Sections:**
-- **Description** - Clear documentation of what the endpoint does
-- **Parameters** - Detailed breakdown of path, query, and body parameters
-- **Request Body** - JSON schema examples with syntax highlighting
-- **Responses** - All possible response codes with examples
-
-**Interactive Features:**
-- Click any endpoint card to open detailed view
-- Search across all endpoints in real-time
-- Smooth transitions and micro-interactions
-- Click outside modal or press X to close
-- Keyboard-friendly navigation
-
-### 🎨 Professional Design Features
-
-**Current Design System:**
-- **Beautiful Gradient Background** - Purple to blue gradient (`#667eea` to `#764ba2`)
-- **Modal-Based Navigation** - Each endpoint opens in its own modal overlay
-- **Smart Search Functionality** - Real-time filtering of endpoints
-- **Controller Grouping** - Endpoints organized by tags with counters
-- **Responsive Design** - Works perfectly on all devices
-- **Smooth Animations** - Professional transitions and hover effects
-
-### 🎭 UI Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `path` | `string` | `'/docs'` | Documentation route path |
-| `sourcePath` | `string` | `'src'` | Directory where your NestJS controllers are located |
-| `baseUrl` | `string` | `'http://localhost:3000'` | Base URL for your API (used in OpenAPI spec) |
-| `enableMock` | `boolean` | `true` | Enable `/scramble-mock/*` endpoints for testing |
-| `autoExportPostman` | `boolean` | `false` | Automatically generate Postman collection file |
-| `postmanOutputPath` | `string` | `'collection.json'` | Output path for Postman collection |
-| `apiTitle` | `string` | Auto-detected | API documentation title |
-| `apiVersion` | `string` | Auto-detected | API version number |
-
-### 🌟 Interactive Features
-
-When you visit `http://localhost:3000/docs`, you'll experience:
-
-- 🎯 **Modal-Based Navigation** - Each endpoint opens in its own modal
-- 📂 **Smart Grouping** - Endpoints organized by tags with counters
-- 🔍 **Real-Time Search** - Instant filtering as you type
-- 🎨 **Beautiful Gradients** - Professional purple to blue background
-- 📱 **Responsive Design** - Perfect on desktop, tablet, and mobile
-- ✨ **Smooth Animations** - Professional transitions and hover effects
-- 📋 **Parameter Details** - Clear documentation of request parameters
-- 💻 **Code Examples** - Formatted JSON with syntax highlighting
-- 🔄 **Interactive Elements** - Click to explore, search to filter
-
-### 🖥️ Terminal Dashboard
-
-The startup dashboard now features **gradient styling** with ANSI colors:
-
-```
-╔═══════════════════════════════════════════════════════════════╗
-║  ✨ NEST-SCRAMBLE by Mohamed Mustafa                          ║
-║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
-║                                                               ║
-║  ● Documentation                                              ║
-║    → http://localhost:3000/docs                               ║
-║                                                               ║
-║  ● OpenAPI Spec                                               ║
-║    → http://localhost:3000/docs-json                          ║
-║                                                               ║
-║  ● Mock Server                                                ║
-║    → http://localhost:3000/scramble-mock                      ║
-║                                                               ║
-║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
-║  📦 Source Path: src                                          ║
-║  🎯 Controllers: 5                                            ║
-║  🎨 Theme: Futuristic                                         ║
-╚═══════════════════════════════════════════════════════════════╝
-```
-
-### 📚 More UI Documentation
-
-For complete UI customization guide, see:
-- **[UI_FEATURES.md](./UI_FEATURES.md)** - Comprehensive feature documentation
-- **[examples/futuristic-ui-example.ts](./examples/futuristic-ui-example.ts)** - Usage examples
-
-### Available Endpoints
-
-| Endpoint | Description |
-|----------|-------------|
-| `GET /docs` | Professional API documentation with modal-based endpoint pages |
-| `GET /docs-json` | OpenAPI 3.0 JSON specification |
-| `GET /docs/json` | Legacy endpoint (same as above) |
-| `GET /docs/spec` | OpenAPI spec as JSON response |
-
-### Accessing the OpenAPI Spec
-
-You can use the OpenAPI JSON with other tools:
-
-```bash
-# Download the spec
-curl http://localhost:3000/docs-json > openapi.json
-
-# Use with Swagger UI
-docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.json -v $(pwd):/usr/share/nginx/html/openapi.json swaggerapi/swagger-ui
-
-# Import into Postman
-# File > Import > Link > http://localhost:3000/docs-json
-```
-
-## ✅ Supported Features
-
-### Type Analysis
-- ✅ Primitive types (string, number, boolean)
-- ✅ Arrays and nested objects
-- ✅ Union types
-- ✅ Enums
-- ✅ Optional properties
-- ✅ Circular references (auto-detected)
-
-### HTTP Methods
-- ✅ GET, POST, PUT, DELETE, PATCH
-- ✅ Path parameters (@Param)
-- ✅ Query parameters (@Query)
-- ✅ Request bodies (@Body)
-
-### Code Generation
-- ✅ Curl commands
-- ✅ JavaScript Fetch
-- ✅ TypeScript with types
-
-## 🧪 Testing with Demo Controller
-
-The library includes a `DemoController` with complex DTOs:
-
-```typescript
-// Complex DTOs with circular references
-export class UserDto {
-  id: number;
-  name: string;
-  email: string;
-  role: UserRole; // Enum
-  address: AddressDto; // Nested
-  posts: PostDto[]; // Circular reference
-}
-
-export class PostDto {
-  id: number;
-  title: string;
-  content: string;
-  author: UserDto; // Circular reference
-}
-```
-
-Run the demo to verify everything works perfectly.
-
-## 🗺️ Roadmap
-
-- [ ] GraphQL support
-- [ ] Custom mock data providers
-- [ ] Authentication integration
-- [ ] API versioning
-- [ ] Performance optimizations
-- [ ] Plugin system for custom analyzers
-
-## 🔧 Troubleshooting
-
-### Common Issues
-
-#### 1. **"No controllers found" Warning**
-
-If you see this warning on startup:
-```
-[Nest-Scramble] No controllers found in /src. Please check your sourcePath config.
-```
-
-**Solution:**
-- Ensure your `sourcePath` option points to the correct directory containing your controllers
-- Check that your controllers use the `@Controller()` decorator from `@nestjs/common`
-- Verify your project structure matches the configured path
-
-```typescript
-NestScrambleModule.forRoot({
-  sourcePath: 'src', // Make sure this matches your project structure
-})
-```
-
-#### 2. **UI Not Loading / Blank Page at /docs**
-
-**Solution:**
-- Clear your browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
-- Check browser console for errors
-- Verify the `/docs-json` endpoint returns valid JSON
-- Ensure you're using version 1.1.0 or higher: `npm list nest-scramble`
-
-#### 3. **TypeScript Compilation Errors**
-
-If you get errors like `Cannot find module 'nest-scramble'`:
-
-**Solution:**
-```bash
-# Clear node_modules and reinstall
-rm -rf node_modules package-lock.json
-npm install
-
-# Rebuild your project
-npm run build
-```
-
-#### 4. **"Unauthorized" (401) Error on /docs Endpoint**
-
-If you have a Global AuthGuard and get 401 Unauthorized when accessing `/docs` or `/docs-json`:
-
-**Solution:**
-
-Nest-Scramble automatically marks its documentation endpoints as public using `@SetMetadata('isPublic', true)`. However, your AuthGuard needs to respect this metadata.
-
-Update your AuthGuard to check for the `isPublic` metadata:
-
-```typescript
-import { Injectable, ExecutionContext } from '@nestjs/common';
-import { Reflector } from '@nestjs/core';
-import { AuthGuard } from '@nestjs/passport';
-
-@Injectable()
-export class JwtAuthGuard extends AuthGuard('jwt') {
-  constructor(private reflector: Reflector) {
-    super();
-  }
-
-  canActivate(context: ExecutionContext) {
-    // Check if route is marked as public
-    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
-      context.getHandler(),
-      context.getClass(),
-    ]);
-    
-    if (isPublic) {
-      return true; // Allow access to public routes
-    }
-    
-    return super.canActivate(context);
-  }
-}
-```
-
-**Alternative Solution - Exclude /docs path:**
-
-```typescript
-import { Module } from '@nestjs/common';
-import { APP_GUARD } from '@nestjs/core';
-
-@Module({
-  providers: [
-    {
-      provide: APP_GUARD,
-      useClass: JwtAuthGuard,
-    },
-  ],
-})
-export class AppModule {}
-
-// In your AuthGuard:
-canActivate(context: ExecutionContext) {
-  const request = context.switchToHttp().getRequest();
-  
-  // Skip authentication for documentation endpoints
-  if (request.url.startsWith('/docs')) {
-    return true;
-  }
-  
-  return super.canActivate(context);
-}
-```
-
-#### 5. **pnpm Dependency Conflicts**
-
-If using pnpm and getting peer dependency warnings:
-
-**Solution:**
-Nest-Scramble v1.1.0+ properly declares peer dependencies. Update to the latest version:
-```bash
-pnpm update nest-scramble
-```
-
-#### 6. **Controllers Not Being Scanned**
-
-The scanner looks in your **host project's** `src` folder, not the library's folder.
-
-**Diagnostic Steps:**
-1. Check the startup logs - they show exactly where the scanner is looking:
-   ```
-   [Nest-Scramble] Scanning directory: /path/to/your/project/src
-   [Nest-Scramble] Found X controller(s)
-   ```
-
-2. Ensure your controllers are in TypeScript files (`.ts`) not JavaScript (`.js`)
-
-3. Verify your `tsconfig.json` exists in the project root
-
-#### 7. **Mock Endpoints Not Working**
-
-If `/scramble-mock/*` returns 404:
-
-**Solution:**
-- Ensure `enableMock: true` in your configuration
-- The middleware applies to all routes matching `/scramble-mock/*`
-- Example: `http://localhost:3000/scramble-mock/users/123`
-
-#### 8. **OpenAPI Spec is Empty or Incomplete**
-
-**Solution:**
-- Ensure your DTOs are TypeScript classes or interfaces (not plain objects)
-- Check that your controller methods have proper return type annotations
-- Verify decorators are imported from `@nestjs/common`
-
-```typescript
-// ✅ Good - Explicit return type
-@Get(':id')
-getUser(@Param('id') id: string): UserDto {
-  return this.userService.findOne(id);
-}
-
-// ❌ Bad - No return type
-@Get(':id')
-getUser(@Param('id') id: string) {
-  return this.userService.findOne(id);
-}
-```
-
-### Getting Help
-
-If you're still experiencing issues:
-
-1. **Check the logs** - Nest-Scramble provides detailed diagnostic output on startup
-2. **Verify your version** - Run `npm list nest-scramble` (should be 1.1.0+)
-3. **Open an issue** - [GitHub Issues](https://github.com/Eng-MMustafa/nest-scramble/issues)
-
-When reporting issues, please include:
-- Nest-Scramble version
-- NestJS version
-- Package manager (npm/yarn/pnpm)
-- Startup logs
-- Sample controller code
-
-## 🤝 Contributing
-
-We welcome contributions! Please:
-
-1. Fork the repository
-2. Create a feature branch
-3. Add tests for new features
-4. Submit a pull request
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file.
-
-## ‍💻 About the Author
-
-![Mohamed Mustafa](https://via.placeholder.com/150x150?text=Mohamed+Mustafa)
-
-Mohamed Mustafa is a passionate full-stack developer with a deep love for TypeScript and modern web frameworks. His mission is to build tools that enhance developer experience and eliminate repetitive tasks. When he's not crafting open-source libraries, you'll find him exploring new technologies, contributing to the developer community, or sharing insights through technical writing.
-
-- [GitHub](https://github.com/Eng-MMustafa)
-- [LinkedIn](https://www.linkedin.com/in/engmohammedmustafa/)
+# Nest-Scramble
+
+> Zero-config API Documentation & Postman Generator for NestJS using static analysis
+
+[![npm version](https://badge.fury.io/js/nest-scramble.svg)](https://badge.fury.io/js/nest-scramble)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/Eng-MMustafa/nest-scramble.svg)](https://github.com/Eng-MMustafa/nest-scramble)
+[![Author](https://img.shields.io/badge/Author-Mohamed%20Mustafa-blue.svg)](https://github.com/Eng-MMustafa)
+
+## 🚀 Why Nest-Scramble?
+
+As a NestJS developer, I was tired of drowning in `@ApiProperty` decorators just to get basic API documentation. I longed for a zero-config solution where docs just worked without polluting my code. **Nest-Scramble changes that** by using static TypeScript analysis to automatically generate:
+
+- ✅ **OpenAPI 3.0 specifications** from your DTOs
+- ✅ **Interactive Scalar UI documentation** with zero configuration
+- ✅ **Postman collections** with smart mock data
+- ✅ **Live mocking** for rapid prototyping
+
+**Zero configuration. Zero decorators. Just pure TypeScript.**
+
+## 📖 The Story Behind Nest-Scramble
+
+It all started with a vision: API documentation should be effortless. As a developer passionate about clean code and developer experience, I knew there had to be a better way than manual decorators and runtime reflection.
+
+When I switched to NestJS for its powerful architecture and TypeScript-first approach, I was disappointed by the lack of zero-config documentation tools. Hours wasted on `@ApiProperty({ type: String })` instead of building features.
+
+I knew there had to be a better way. Leveraging my expertise in static analysis and Abstract Syntax Trees (AST), I built Nest-Scramble to bring that same developer experience to the Node.js ecosystem. It's not just a tool—it's my mission to make API documentation as effortless as it should be.
+
+## 🏆 Features Gallery
+
+| Feature | Nest-Scramble | Swagger (@nestjs/swagger) |
+|---------|---------------|---------------------------|
+| Analysis Method | Static AST Traversal | Runtime Reflection |
+| Performance Impact | Zero Overhead | Decorator Runtime Cost |
+| Type Accuracy | Full TypeScript Inference | Partial Mapping |
+| Circular References | Auto-Detected & Resolved | Manual Workarounds |
+| Bundle Size | Minimal | Heavy with Decorators |
+| Code Purity | Zero Decorators | Decorator Pollution |
+| Future Compatibility | TypeScript Evolution Ready | Framework Dependent |
+
+## 🧠 The Vision
+
+Nest-Scramble embodies my engineering philosophy: **Clean Code through Automation**. As a developer who values TypeScript's type safety and NestJS's architecture, I believe that documentation should never compromise code quality.
+
+This library represents a paradigm shift—from manual, error-prone decorators to intelligent, compile-time analysis. It's about empowering developers to focus on building features, not fighting frameworks.
+
+## 🔬 How it's Built
+
+Nest-Scramble is engineered using cutting-edge static analysis techniques that traditional tools cannot match:
+
+- **Abstract Syntax Tree (AST) Traversal**: Direct manipulation of TypeScript's AST using `ts-morph` for unparalleled type inference
+- **Zero-Decorator Architecture**: Pure TypeScript classes remain untouched, preserving domain integrity
+- **Compile-Time Intelligence**: All analysis happens at build-time, eliminating runtime performance costs
+- **Circular Reference Mastery**: Advanced algorithms detect and handle complex type relationships automatically
+
+This approach delivers what runtime reflection simply cannot: perfect accuracy, zero overhead, and future-proof compatibility with TypeScript's evolving type system.
+
+## ⚡ Quick Start - Zero Config (2 Steps!)
+
+### Option A: Auto-Injection (Recommended - 30 seconds!)
+
+```bash
+# 1. Install
+npm install nest-scramble
+
+# 2. Auto-inject into your project
+npx nest-scramble init
+
+# 3. Start your app
+npm run start:dev
+
+# 🎉 Done! Visit http://localhost:3000/docs
+```
+
+The `init` command automatically:
+- ✅ Adds the import statement to your `app.module.ts`
+- ✅ Injects `NestScrambleModule.forRoot()` into your imports
+- ✅ Uses smart defaults with zero configuration needed
+
+### Option B: Manual Installation (3 Steps)
+
+#### 1. Install the Package
+
+```bash
+# Using npm
+npm install nest-scramble
+
+# Using yarn
+yarn add nest-scramble
+
+# Using pnpm
+pnpm add nest-scramble
+```
+
+#### 2. Import Module in Your NestJS App
+
+**Zero-Config (Recommended):**
+```typescript
+import { Module } from '@nestjs/common';
+import { NestScrambleModule } from 'nest-scramble';
+
+@Module({
+  imports: [
+    NestScrambleModule.forRoot(), // 🎯 That's it! Zero config needed
+  ],
+})
+export class AppModule {}
+```
+
+**With Custom Options:**
+```typescript
+import { Module } from '@nestjs/common';
+import { NestScrambleModule } from 'nest-scramble';
+
+@Module({
+  imports: [
+    NestScrambleModule.forRoot({
+      sourcePath: 'src',              // Auto-detected by default
+      baseUrl: 'http://localhost:3000', // Auto-detected from PORT env
+      enableMock: true,               // Enabled by default
+      autoExportPostman: false,       // Disabled by default
+      apiTitle: 'My API',             // Auto-detected from package.json
+      apiVersion: '1.0.0',            // Auto-detected from package.json
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+#### 3. Start Your App and Visit Documentation
+
+```bash
+npm run start:dev
+```
+
+You'll see a beautiful dashboard in your terminal:
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  🚀 Nest-Scramble by Mohamed Mustafa is Active!          │
+├──────────────────────────────────────────────────────────┤
+│  📖 Docs: http://localhost:3000/docs                     │
+│  📄 JSON: http://localhost:3000/docs-json                │
+│  🎭 Mock: http://localhost:3000/scramble-mock            │
+│  ✨ Scanning: src                                        │
+│  🎯 Controllers: 5                                       │
+└──────────────────────────────────────────────────────────┘
+```
+
+Then open your browser:
+
+- **📖 Interactive API Docs (Scalar UI)**: http://localhost:3000/docs
+- **📄 OpenAPI JSON Spec**: http://localhost:3000/docs-json
+- **🎭 Mock Endpoints**: http://localhost:3000/scramble-mock/*
+
+**That's it!** Nest-Scramble automatically:
+- 🔍 Detects your project structure
+- 📂 Finds your controllers
+- 📝 Generates OpenAPI spec
+- 🎨 Serves beautiful documentation
+- 🎭 Provides mock endpoints
+
+## ⚙️ Configuration Options
+
+```typescript
+NestScrambleModule.forRoot({
+  // Source directory to scan for controllers
+  sourcePath: 'src',                    // default: 'src'
+
+  // API base URL for OpenAPI spec
+  baseUrl: 'http://localhost:3000',     // default: 'http://localhost:3000'
+
+  // Enable live mocking middleware
+  enableMock: true,                     // default: true
+
+  // Auto-export Postman collection on startup
+  autoExportPostman: false,             // default: false
+
+  // Postman collection output path
+  postmanOutputPath: 'collection.json', // default: 'collection.json'
+})
+```
+
+### Configuration Details
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sourcePath` | `string` | `'src'` | Directory where your NestJS controllers are located |
+| `baseUrl` | `string` | `'http://localhost:3000'` | Base URL for your API (used in OpenAPI spec) |
+| `enableMock` | `boolean` | `true` | Enable `/scramble-mock/*` endpoints for testing |
+| `autoExportPostman` | `boolean` | `false` | Automatically generate Postman collection file |
+| `postmanOutputPath` | `string` | `'collection.json'` | Output path for Postman collection |
+
+## 🎭 Live Mocking Guide
+
+Nest-Scramble provides **instant API mocking** without writing controllers:
+
+### How It Works
+1. Define your DTOs and controllers normally
+2. Enable `enableMock: true`
+3. All requests to `/scramble-mock/*` return smart mock data
+
+### Example
+
+**Controller:**
+```typescript
+@Controller('users')
+export class UserController {
+  @Get(':id')
+  getUser(@Param('id') id: number): UserDto {
+    // Your logic here
+  }
+}
+```
+
+**Mock Response:**
+```bash
+GET /scramble-mock/users/123
+# Returns: { "id": 123, "name": "John Doe", "email": "john@example.com" }
+```
+
+**Smart Mocking Examples:**
+- `email` → `faker.internet.email()`
+- `name` → `faker.person.fullName()`
+- `createdAt` → `faker.date.recent()`
+- `posts` → Array of mock posts
+
+![Live mocking demo](mock-demo.gif)
+
+## 🔧 Advanced Usage
+
+### CLI Generation
+
+The Nest-Scramble CLI allows you to generate API documentation without running your NestJS application.
+
+#### Generate OpenAPI Specification
+
+```bash
+# Using npx
+npx nest-scramble generate src
+
+# Using pnpm dlx
+pnpm dlx nest-scramble generate src
+
+# Using yarn dlx
+yarn dlx nest-scramble generate src
+```
+
+#### CLI Options
+
+```bash
+nest-scramble generate <sourcePath> [options]
+
+Options:
+  -o, --output <file>         Output file path (default: "openapi.json")
+  -f, --format <type>         Output format: openapi or postman (default: "openapi")
+  -b, --baseUrl <url>         Base URL for the API (default: "http://localhost:3000")
+  -t, --title <title>         API title (default: "NestJS API")
+  -v, --apiVersion <version>  API version (default: "1.0.0")
+  -h, --help                  Display help for command
+```
+
+#### Examples
+
+**Generate OpenAPI JSON:**
+```bash
+pnpm dlx nest-scramble generate src --output openapi.json
+```
+
+**Generate Postman Collection:**
+```bash
+pnpm dlx nest-scramble generate src --format postman --output collection.json
+```
+
+**Custom API Details:**
+```bash
+pnpm dlx nest-scramble generate src \
+  --output my-api.json \
+  --title "My Awesome API" \
+  --apiVersion "2.0.0" \
+  --baseUrl "https://api.example.com"
+```
+
+**Check Version:**
+```bash
+pnpm dlx nest-scramble --version
+```
+
+### Programmatic API
+
+Use Nest-Scramble programmatically in your Node.js scripts:
+
+```typescript
+import { ScannerService, OpenApiTransformer, PostmanCollectionGenerator } from 'nest-scramble';
+import * as fs from 'fs';
+
+// Scan controllers
+const scanner = new ScannerService();
+const controllers = scanner.scanControllers('src');
+
+// Generate OpenAPI spec
+const transformer = new OpenApiTransformer('http://localhost:3000');
+const openApiSpec = transformer.transform(
+  controllers,
+  'My API',
+  '1.0.0',
+  'http://localhost:3000'
+);
+
+// Save to file
+fs.writeFileSync('openapi.json', JSON.stringify(openApiSpec, null, 2));
+
+// Or generate Postman collection
+const postmanGen = new PostmanCollectionGenerator('http://localhost:3000');
+const collection = postmanGen.generateCollection(controllers);
+fs.writeFileSync('collection.json', JSON.stringify(collection, null, 2));
+```
+
+### CI/CD Integration
+
+Add to your CI/CD pipeline to auto-generate documentation:
+
+```yaml
+# .github/workflows/docs.yml
+name: Generate API Docs
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  generate-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - run: npm install
+      - run: npx nest-scramble generate src --output openapi.json
+      - uses: actions/upload-artifact@v3
+        with:
+          name: api-docs
+          path: openapi.json
+```
+
+## 🎨 Documentation UI - Professional API Dashboard
+
+### ✨ Elite Dashboard Design (NEW!)
+
+Nest-Scramble features a **professional, high-end API dashboard** inspired by Stripe and Postman, where each request is displayed on a separate page for focused documentation!
+
+**🚀 Key Features:**
+- **Sidebar-Only Navigation** - Fixed 320px sidebar with controller grouping
+- **Single-Request Per Page** - Each endpoint gets its own dedicated view
+- **Three-Column Elite Layout** - Information | Request Editor | Test Panel
+- **Deep Black Background** - Professional `#000000` and `#0B0E14` theme
+- **Cyber-Cyan Accents** - `#00f2ff` for active states and primary actions
+- **Vibrant HTTP Method Badges** - Color-coded with glow effects:
+  - GET = Royal Blue (`#3B82F6`)
+  - POST = Emerald Green (`#10B981`)
+  - PUT = Amber Orange (`#F59E0B`)
+  - PATCH = Violet Purple (`#8B5CF6`)
+  - DELETE = Vibrant Red (`#EF4444`)
+- **Glassmorphism Effects** - Backdrop blur on request/response panels
+- **40px Spacious Padding** - Premium whitespace throughout
+- **Terminal-Style Response** - Black box with green text for API responses
+- **High-Contrast Labels** - Required, Type, and Default badges
+- **Custom Scrollbars** - Gradient cyan-to-purple styling
+- **Plus Jakarta Sans Typography** - Modern, professional font family
+- **Powered by Badge** - Animated branding with pulse effect
+
+### 📐 Three-Column Elite Interface
+
+The dashboard uses a professional three-column layout for each endpoint:
+
+**Column 1 (Left) - Information Panel:**
+- Endpoint title with large, bold typography
+- HTTP method badge with vibrant colors and glow
+- Endpoint description and documentation
+- Clean parameters table with high-contrast labels
+- Type information and required field indicators
+
+**Column 2 (Middle) - Request Body Editor:**
+- Glassmorphism design with backdrop blur
+- Auto-filled mock data examples
+- JSON editor with syntax highlighting
+- Copy-to-clipboard functionality
+- Real-time validation
+
+**Column 3 (Right) - Test Request Panel:**
+- Enhanced glassmorphism with cyan border glow
+- Large "Send Request" button with gradient animation
+- Terminal-style response viewer (black background, green text)
+- Status code indicators
+- Response headers display
+
+### 🎨 Theme Customization
+
+**Futuristic Theme (Default):**
+```typescript
+NestScrambleModule.forRoot({
+  theme: 'futuristic',           // Professional dark dashboard
+  primaryColor: '#00f2ff',       // Cyber-Cyan (default)
+  customDomainIcon: '/logo.png', // Your brand favicon
+  apiTitle: 'My Awesome API',
+})
+```
+
+**Classic Theme:**
+```typescript
+NestScrambleModule.forRoot({
+  theme: 'classic',              // Clean, light, professional
+  primaryColor: '#0066cc',       // Corporate blue
+  apiTitle: 'Enterprise API',
+})
+```
+
+**Custom Color Branding:**
+```typescript
+// One line changes the entire UI color scheme!
+NestScrambleModule.forRoot({
+  primaryColor: '#a855f7',       // Electric Purple
+  // or '#10b981' for Emerald Green
+  // or '#f59e0b' for Amber Orange
+  // or any hex color you want!
+})
+```
+
+### 🎭 UI Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `theme` | `'classic' \| 'futuristic'` | `'futuristic'` | UI theme selection |
+| `primaryColor` | `string` | `'#00f2ff'` | Primary accent color (hex) |
+| `customDomainIcon` | `string` | `''` | Custom favicon URL |
+| `apiTitle` | `string` | Auto-detected | API documentation title |
+| `apiVersion` | `string` | Auto-detected | API version number |
+
+### 🌟 Interactive Features
+
+When you visit `http://localhost:3000/docs`, you'll experience:
+
+- 🎯 **Single-Request Navigation** - Each endpoint on its own dedicated page
+- 📂 **Controller Grouping** - Organized sidebar with uppercase section headers
+- 🎨 **Active State Glow** - Cyber-cyan highlight for selected endpoints
+- 📝 **Auto-generated Examples** - Pre-filled mock data in request editor
+- 🧪 **Live Testing** - Send requests directly from the three-column interface
+- 💻 **Terminal Response** - Black box with green text for authentic feel
+- 🔍 **Quick Search** - Press 'K' to search endpoints instantly
+- 📱 **Responsive Design** - Adapts to mobile, tablet, and desktop
+- ✨ **Animated Branding** - Pulsing "Powered by Nest-Scramble" badge
+- 🎭 **Developer Easter Eggs** - Check your browser console for surprises!
+
+### 🖥️ Terminal Dashboard
+
+The startup dashboard now features **gradient styling** with ANSI colors:
+
+```
+╔═══════════════════════════════════════════════════════════════╗
+║  ✨ NEST-SCRAMBLE by Mohamed Mustafa                          ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║                                                               ║
+║  ● Documentation                                              ║
+║    → http://localhost:3000/docs                               ║
+║                                                               ║
+║  ● OpenAPI Spec                                               ║
+║    → http://localhost:3000/docs-json                          ║
+║                                                               ║
+║  ● Mock Server                                                ║
+║    → http://localhost:3000/scramble-mock                      ║
+║                                                               ║
+║  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ║
+║  📦 Source Path: src                                          ║
+║  🎯 Controllers: 5                                            ║
+║  🎨 Theme: Futuristic                                         ║
+╚═══════════════════════════════════════════════════════════════╝
+```
+
+### 📚 More UI Documentation
+
+For complete UI customization guide, see:
+- **[UI_FEATURES.md](./UI_FEATURES.md)** - Comprehensive feature documentation
+- **[examples/futuristic-ui-example.ts](./examples/futuristic-ui-example.ts)** - Usage examples
+
+### Available Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /docs` | Interactive Scalar UI documentation |
+| `GET /docs-json` | OpenAPI 3.0 JSON specification |
+| `GET /docs/json` | Legacy endpoint (same as above) |
+| `GET /docs/spec` | OpenAPI spec as JSON response |
+
+### Accessing the OpenAPI Spec
+
+You can use the OpenAPI JSON with other tools:
+
+```bash
+# Download the spec
+curl http://localhost:3000/docs-json > openapi.json
+
+# Use with Swagger UI
+docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.json -v $(pwd):/usr/share/nginx/html/openapi.json swaggerapi/swagger-ui
+
+# Import into Postman
+# File > Import > Link > http://localhost:3000/docs-json
+```
+
+## ✅ Supported Features
+
+### Type Analysis
+- ✅ Primitive types (string, number, boolean)
+- ✅ Arrays and nested objects
+- ✅ Union types
+- ✅ Enums
+- ✅ Optional properties
+- ✅ Circular references (auto-detected)
+
+### HTTP Methods
+- ✅ GET, POST, PUT, DELETE, PATCH
+- ✅ Path parameters (@Param)
+- ✅ Query parameters (@Query)
+- ✅ Request bodies (@Body)
+
+### Code Generation
+- ✅ Curl commands
+- ✅ JavaScript Fetch
+- ✅ TypeScript with types
+
+## 🧪 Testing with Demo Controller
+
+The library includes a `DemoController` with complex DTOs:
+
+```typescript
+// Complex DTOs with circular references
+export class UserDto {
+  id: number;
+  name: string;
+  email: string;
+  role: UserRole; // Enum
+  address: AddressDto; // Nested
+  posts: PostDto[]; // Circular reference
+}
+
+export class PostDto {
+  id: number;
+  title: string;
+  content: string;
+  author: UserDto; // Circular reference
+}
+```
+
+Run the demo to verify everything works perfectly.
+
+## 🗺️ Roadmap
+
+- [ ] GraphQL support
+- [ ] Custom mock data providers
+- [ ] Authentication integration
+- [ ] API versioning
+- [ ] Performance optimizations
+- [ ] Plugin system for custom analyzers
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### 1. **"No controllers found" Warning**
+
+If you see this warning on startup:
+```
+[Nest-Scramble] No controllers found in /src. Please check your sourcePath config.
+```
+
+**Solution:**
+- Ensure your `sourcePath` option points to the correct directory containing your controllers
+- Check that your controllers use the `@Controller()` decorator from `@nestjs/common`
+- Verify your project structure matches the configured path
+
+```typescript
+NestScrambleModule.forRoot({
+  sourcePath: 'src', // Make sure this matches your project structure
+})
+```
+
+#### 2. **UI Not Loading / Blank Page at /docs**
+
+**Solution:**
+- Clear your browser cache and hard refresh (Ctrl+Shift+R / Cmd+Shift+R)
+- Check browser console for errors
+- Verify the `/docs-json` endpoint returns valid JSON
+- Ensure you're using version 1.1.0 or higher: `npm list nest-scramble`
+
+#### 3. **TypeScript Compilation Errors**
+
+If you get errors like `Cannot find module 'nest-scramble'`:
+
+**Solution:**
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Rebuild your project
+npm run build
+```
+
+#### 4. **"Unauthorized" (401) Error on /docs Endpoint**
+
+If you have a Global AuthGuard and get 401 Unauthorized when accessing `/docs` or `/docs-json`:
+
+**Solution:**
+
+Nest-Scramble automatically marks its documentation endpoints as public using `@SetMetadata('isPublic', true)`. However, your AuthGuard needs to respect this metadata.
+
+Update your AuthGuard to check for the `isPublic` metadata:
+
+```typescript
+import { Injectable, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  constructor(private reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    // Check if route is marked as public
+    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    
+    if (isPublic) {
+      return true; // Allow access to public routes
+    }
+    
+    return super.canActivate(context);
+  }
+}
+```
+
+**Alternative Solution - Exclude /docs path:**
+
+```typescript
+import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
+
+@Module({
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: JwtAuthGuard,
+    },
+  ],
+})
+export class AppModule {}
+
+// In your AuthGuard:
+canActivate(context: ExecutionContext) {
+  const request = context.switchToHttp().getRequest();
+  
+  // Skip authentication for documentation endpoints
+  if (request.url.startsWith('/docs')) {
+    return true;
+  }
+  
+  return super.canActivate(context);
+}
+```
+
+#### 5. **pnpm Dependency Conflicts**
+
+If using pnpm and getting peer dependency warnings:
+
+**Solution:**
+Nest-Scramble v1.1.0+ properly declares peer dependencies. Update to the latest version:
+```bash
+pnpm update nest-scramble
+```
+
+#### 6. **Controllers Not Being Scanned**
+
+The scanner looks in your **host project's** `src` folder, not the library's folder.
+
+**Diagnostic Steps:**
+1. Check the startup logs - they show exactly where the scanner is looking:
+   ```
+   [Nest-Scramble] Scanning directory: /path/to/your/project/src
+   [Nest-Scramble] Found X controller(s)
+   ```
+
+2. Ensure your controllers are in TypeScript files (`.ts`) not JavaScript (`.js`)
+
+3. Verify your `tsconfig.json` exists in the project root
+
+#### 7. **Mock Endpoints Not Working**
+
+If `/scramble-mock/*` returns 404:
+
+**Solution:**
+- Ensure `enableMock: true` in your configuration
+- The middleware applies to all routes matching `/scramble-mock/*`
+- Example: `http://localhost:3000/scramble-mock/users/123`
+
+#### 8. **OpenAPI Spec is Empty or Incomplete**
+
+**Solution:**
+- Ensure your DTOs are TypeScript classes or interfaces (not plain objects)
+- Check that your controller methods have proper return type annotations
+- Verify decorators are imported from `@nestjs/common`
+
+```typescript
+// ✅ Good - Explicit return type
+@Get(':id')
+getUser(@Param('id') id: string): UserDto {
+  return this.userService.findOne(id);
+}
+
+// ❌ Bad - No return type
+@Get(':id')
+getUser(@Param('id') id: string) {
+  return this.userService.findOne(id);
+}
+```
+
+### Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the logs** - Nest-Scramble provides detailed diagnostic output on startup
+2. **Verify your version** - Run `npm list nest-scramble` (should be 1.1.0+)
+3. **Open an issue** - [GitHub Issues](https://github.com/Eng-MMustafa/nest-scramble/issues)
+
+When reporting issues, please include:
+- Nest-Scramble version
+- NestJS version
+- Package manager (npm/yarn/pnpm)
+- Startup logs
+- Sample controller code
+
+## 🤝 Contributing
+
+We welcome contributions! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new features
+4. Submit a pull request
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## ‍💻 About the Author
+
+![Mohamed Mustafa](https://via.placeholder.com/150x150?text=Mohamed+Mustafa)
+
+Mohamed Mustafa is a passionate full-stack developer with a deep love for TypeScript and modern web frameworks. His mission is to build tools that enhance developer experience and eliminate repetitive tasks. When he's not crafting open-source libraries, you'll find him exploring new technologies, contributing to the developer community, or sharing insights through technical writing.
+
+- [GitHub](https://github.com/Eng-MMustafa)
+- [LinkedIn](https://www.linkedin.com/in/engmohammedmustafa/)