diff --git a/docs/multi-step-integration-guide.md b/docs/multi-step-integration-guide.md
new file mode 100644
index 0000000..84e271f
--- /dev/null
+++ b/docs/multi-step-integration-guide.md
@@ -0,0 +1,491 @@
+# Multi-Step README Generation Pipeline - Integration Guide
+
+This guide provides complete instructions for integrating the multi-step README generation pipeline into an existing Next.js application, specifically for the ReadmeGenAI project.
+
+## 📋 Overview
+
+The new pipeline solves the token limit issues by:
+- **Section-by-section generation**: Each section is generated individually within token limits
+- **Retry logic**: Failed sections are automatically retried with simplified prompts
+- **Smart dependency management**: Sections are generated in optimal order based on dependencies
+- **Continuation support**: Truncated content can be automatically completed
+- **Fallback mechanisms**: Critical sections always have fallback content
+
+## 🚀 Quick Integration
+
+### 1. Install Dependencies
+
+```bash
+npm install @google/generative-ai @octokit/rest
+```
+
+### 2. Replace Existing API Route
+
+Replace the content of `src/app/api/generate/route.ts`:
+
+```typescript
+import { handleReadmeGeneration } from '@/lib/multi-step-readme-generator';
+
+export async function POST(request: Request) {
+  return handleReadmeGeneration(request);
+}
+```
+
+### 3. Environment Variables
+
+Ensure these environment variables are set:
+
+```env
+GEMINI_API_KEY=your_gemini_api_key
+GITHUB_TOKEN=your_github_token  # Optional but recommended for higher rate limits
+```
+
+### 4. Update Frontend (Optional)
+
+Enhance the frontend to show generation progress:
+
+```typescript
+// In your component
+const [generationStats, setGenerationStats] = useState(null);
+
+const handleGenerate = async (githubUrl: string) => {
+  setIsLoading(true);
+  
+  try {
+    const response = await fetch('/api/generate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ githubUrl }),
+    });
+
+    const result = await response.json();
+    
+    if (result.success) {
+      setReadme(result.readme);
+      setGenerationStats(result.stats);
+    } else {
+      setError(result.error);
+    }
+  } catch (error) {
+    setError('Generation failed');
+  } finally {
+    setIsLoading(false);
+  }
+};
+```
+
+## 🔧 Advanced Configuration
+
+### Custom Configuration
+
+You can customize the generation behavior:
+
+```typescript
+import { MultiStepReadmeGenerator } from '@/lib/multi-step-readme-generator';
+
+const generator = new MultiStepReadmeGenerator(
+  process.env.GEMINI_API_KEY!,
+  process.env.GITHUB_TOKEN,
+  {
+    maxRetries: 5,              // Increase retries for better reliability
+    maxTokensPerSection: 1000,  // Allow longer sections
+    temperature: 0.5,           // More conservative generation
+    concurrentSections: 2,      // Reduce concurrency to avoid rate limits
+    enableContinuation: true,   // Enable automatic continuation
+  }
+);
+```
+
+### Custom Section Planning
+
+Define custom sections for specific project types:
+
+```typescript
+import { SectionPlanner, ReadmeSection } from '@/lib/multi-step-readme-generator';
+
+// Custom sections for a specific project type
+const customSections: ReadmeSection[] = [
+  {
+    id: 'header',
+    title: 'Project Header',
+    priority: 'critical',
+    order: 1,
+    estimatedTokens: 200,
+    dependencies: [],
+  },
+  {
+    id: 'quick-start',
+    title: 'Quick Start',
+    priority: 'high',
+    order: 2,
+    estimatedTokens: 400,
+    dependencies: ['header'],
+  },
+  // ... more sections
+];
+
+const result = await assembler.generateCompleteReadme(
+  metadata,
+  structure,
+  customSections
+);
+```
+
+## 📊 Monitoring and Analytics
+
+### Generation Stats
+
+The new pipeline provides detailed statistics:
+
+```typescript
+interface GenerationStats {
+  sectionsGenerated: number;  // How many sections were successfully generated
+  sectionsTotal: number;      // Total sections planned
+  tokensUsed: number;         // Total tokens consumed
+  timeElapsed: number;        // Generation time in milliseconds
+}
+```
+
+### Error Handling
+
+Comprehensive error information:
+
+```typescript
+interface GenerationResult {
+  success: boolean;
+  readme?: string;
+  stats: GenerationStats;
+  errors: string[];          // Detailed error messages
+}
+```
+
+### Logging Integration
+
+Add logging to track generation performance:
+
+```typescript
+// In your API route
+const result = await generator.generateReadme(githubUrl);
+
+// Log metrics
+console.log(`README generated for ${githubUrl}:`, {
+  success: result.success,
+  sectionsGenerated: result.stats.sectionsGenerated,
+  timeElapsed: result.stats.timeElapsed,
+  tokensUsed: result.stats.tokensUsed,
+});
+
+// Log errors for debugging
+if (result.errors.length > 0) {
+  console.error('Generation errors:', result.errors);
+}
+```
+
+## 🔄 Migration from Existing Implementation
+
+### Step 1: Backup Current Implementation
+
+```bash
+# Backup current generate route
+cp src/app/api/generate/route.ts src/app/api/generate/route.ts.backup
+```
+
+### Step 2: Gradual Migration
+
+Implement a feature flag for gradual rollout:
+
+```typescript
+// src/app/api/generate/route.ts
+import { handleReadmeGeneration as newHandler } from '@/lib/multi-step-readme-generator';
+import { handleReadmeGeneration as oldHandler } from '@/lib/old-readme-generator';
+
+export async function POST(request: Request) {
+  const useNewPipeline = process.env.USE_NEW_README_PIPELINE === 'true';
+  
+  if (useNewPipeline) {
+    return newHandler(request);
+  } else {
+    return oldHandler(request);
+  }
+}
+```
+
+### Step 3: A/B Testing
+
+Compare old vs new implementation:
+
+```typescript
+export async function POST(request: Request) {
+  const body = await request.json();
+  const { githubUrl, useNewPipeline } = body;
+
+  if (useNewPipeline) {
+    return handleReadmeGeneration(request);
+  } else {
+    // Use old implementation
+    return oldReadmeGeneration(request);
+  }
+}
+```
+
+## 🛠️ Troubleshooting
+
+### Common Issues and Solutions
+
+#### 1. Token Limit Exceeded
+
+**Problem**: Even individual sections exceed token limits
+**Solution**: Reduce `maxTokensPerSection` or simplify prompts
+
+```typescript
+const generator = new MultiStepReadmeGenerator(apiKey, githubToken, {
+  maxTokensPerSection: 600,  // Reduce from default 800
+});
+```
+
+#### 2. Rate Limiting
+
+**Problem**: API rate limits exceeded
+**Solution**: Reduce concurrency and add delays
+
+```typescript
+const generator = new MultiStepReadmeGenerator(apiKey, githubToken, {
+  concurrentSections: 1,  // Generate one section at a time
+});
+```
+
+#### 3. GitHub API Rate Limits
+
+**Problem**: Repository analysis fails due to rate limits
+**Solution**: Provide GitHub token and implement caching
+
+```typescript
+// Implement simple caching
+const cache = new Map();
+
+class CachedRepositoryAnalyzer extends RepositoryAnalyzer {
+  async analyzeRepository(owner: string, repo: string) {
+    const key = `${owner}/${repo}`;
+    
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    
+    const result = await super.analyzeRepository(owner, repo);
+    cache.set(key, result);
+    
+    return result;
+  }
+}
+```
+
+#### 4. Incomplete Sections
+
+**Problem**: Some sections are consistently incomplete
+**Solution**: Increase retries or customize prompts
+
+```typescript
+// Custom prompt for problematic section
+const customPrompts = {
+  installation: `Generate concise installation instructions for "${metadata.name}".
+  
+  Context: ${structure.techStack.primary} project
+  
+  Requirements:
+  - Prerequisites (if any)
+  - Single command installation
+  - Verification step
+  
+  Keep it under 300 words. Return only markdown.`,
+};
+```
+
+### Debug Mode
+
+Enable detailed logging:
+
+```typescript
+// Set environment variable
+process.env.DEBUG_README_GENERATION = 'true';
+
+// In the generator
+if (process.env.DEBUG_README_GENERATION === 'true') {
+  console.log('Section generation details:', {
+    sectionId,
+    prompt: prompt.substring(0, 200) + '...',
+    result: result.success ? 'success' : 'failed',
+    tokensUsed: result.tokensUsed,
+  });
+}
+```
+
+## 📈 Performance Optimizations
+
+### 1. Caching Strategy
+
+Implement Redis caching for repository analysis:
+
+```typescript
+import Redis from 'ioredis';
+
+const redis = new Redis(process.env.REDIS_URL);
+
+class CachedAnalyzer extends RepositoryAnalyzer {
+  async analyzeRepository(owner: string, repo: string) {
+    const key = `repo:${owner}:${repo}`;
+    const cached = await redis.get(key);
+    
+    if (cached) {
+      return JSON.parse(cached);
+    }
+    
+    const result = await super.analyzeRepository(owner, repo);
+    await redis.setex(key, 3600, JSON.stringify(result)); // 1 hour cache
+    
+    return result;
+  }
+}
+```
+
+### 2. Background Processing
+
+For large repositories, use background jobs:
+
+```typescript
+import Bull from 'bull';
+
+const readmeQueue = new Bull('readme generation');
+
+// API route for immediate response
+export async function POST(request: Request) {
+  const { githubUrl } = await request.json();
+  
+  const job = await readmeQueue.add('generate', { githubUrl });
+  
+  return Response.json({
+    jobId: job.id,
+    status: 'queued',
+  });
+}
+
+// Background worker
+readmeQueue.process('generate', async (job) => {
+  const { githubUrl } = job.data;
+  const generator = new MultiStepReadmeGenerator(...);
+  
+  return generator.generateReadme(githubUrl);
+});
+```
+
+### 3. Streaming Responses
+
+Stream sections as they're generated:
+
+```typescript
+export async function POST(request: Request) {
+  const { githubUrl } = await request.json();
+  
+  const stream = new ReadableStream({
+    async start(controller) {
+      const generator = new MultiStepReadmeGenerator(...);
+      
+      // Override assembler to stream results
+      const originalAssembler = generator.assembler;
+      generator.assembler.generateSectionsInBatches = async (...args) => {
+        // Stream each section as it's completed
+        // Implementation details...
+      };
+      
+      const result = await generator.generateReadme(githubUrl);
+      controller.close();
+    },
+  });
+  
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  });
+}
+```
+
+## 🧪 Testing
+
+### Unit Tests
+
+```typescript
+// __tests__/readme-generator.test.ts
+import { MultiStepReadmeGenerator, RepositoryAnalyzer } from '@/lib/multi-step-readme-generator';
+
+describe('MultiStepReadmeGenerator', () => {
+  it('should generate complete README for public repository', async () => {
+    const generator = new MultiStepReadmeGenerator(
+      process.env.GEMINI_API_KEY,
+      process.env.GITHUB_TOKEN
+    );
+    
+    const result = await generator.generateReadme(
+      'https://github.com/octocat/Hello-World'
+    );
+    
+    expect(result.success).toBe(true);
+    expect(result.readme).toContain('# Hello-World');
+    expect(result.stats.sectionsGenerated).toBeGreaterThan(0);
+  });
+});
+```
+
+### Integration Tests
+
+```typescript
+describe('API Integration', () => {
+  it('should handle README generation request', async () => {
+    const response = await fetch('/api/generate', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        githubUrl: 'https://github.com/octocat/Hello-World'
+      }),
+    });
+    
+    const result = await response.json();
+    
+    expect(response.status).toBe(200);
+    expect(result.success).toBe(true);
+    expect(result.readme).toBeDefined();
+  });
+});
+```
+
+## 📚 API Reference
+
+### Main Classes
+
+- **`MultiStepReadmeGenerator`**: Main orchestrator class
+- **`RepositoryAnalyzer`**: Analyzes GitHub repositories
+- **`SectionPlanner`**: Plans optimal README sections
+- **`SectionGenerator`**: Generates individual sections
+- **`ReadmeAssembler`**: Assembles and validates final README
+
+### Configuration Options
+
+```typescript
+interface GenerationConfig {
+  maxRetries: number;           // Default: 3
+  maxTokensPerSection: number;  // Default: 800
+  temperature: number;          // Default: 0.7
+  concurrentSections: number;   // Default: 3
+  enableContinuation: boolean;  // Default: true
+}
+```
+
+### Section Types
+
+- **Critical**: `header`, `description`, `installation`
+- **High**: `features`, `usage`, `api`
+- **Medium**: `configuration`, `development`, `contributing`, `deployment`
+- **Low**: `testing`, `examples`
+
+This comprehensive integration guide provides everything needed to successfully implement the multi-step README generation pipeline in the ReadmeGenAI project, solving the token limit issues while providing a more robust and reliable generation process.
\ No newline at end of file
diff --git a/package-lock.json b/package-lock.json
index 9a1c38a..770db20 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,7 +12,8 @@
         "@radix-ui/react-slot": "^1.2.4",
         "@vercel/analytics": "^2.0.1",
         "lucide-react": "^0.577.0",
-        "next": "16.2.3",
+        "next": "^16.2.4",
+        "next-auth": "^4.24.14",
         "octokit": "^5.0.5",
         "react": "19.2.4",
         "react-dom": "19.2.4",
@@ -91,6 +92,7 @@
       "integrity": "sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.29.0",
         "@babel/generator": "^7.29.0",
@@ -269,7 +271,6 @@
       "version": "7.28.6",
       "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.28.6.tgz",
       "integrity": "sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=6.9.0"
@@ -341,9 +342,9 @@
       "license": "MIT"
     },
     "node_modules/@emnapi/core": {
-      "version": "1.9.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.2.tgz",
-      "integrity": "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==",
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
+      "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
       "dev": true,
       "license": "MIT",
       "optional": true,
@@ -353,9 +354,9 @@
       }
     },
     "node_modules/@emnapi/runtime": {
-      "version": "1.9.2",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.9.2.tgz",
-      "integrity": "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==",
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
       "license": "MIT",
       "optional": true,
       "dependencies": {
@@ -1092,9 +1093,9 @@
       }
     },
     "node_modules/@next/env": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/env/-/env-16.2.3.tgz",
-      "integrity": "sha512-ZWXyj4uNu4GCWQw9cjRxWlbD+33mcDszIo9iQxFnBX3Wmgq9ulaSJcl6VhuWx5pCWqqD+9W6Wfz7N0lM5lYPMA==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/env/-/env-16.2.4.tgz",
+      "integrity": "sha512-dKkkOzOSwFYe5RX6y26fZgkSpVAlIOJKQHIiydQcrWH6y/97+RceSOAdjZ14Qa3zLduVUy0TXcn+EiM6t4rPgw==",
       "license": "MIT"
     },
     "node_modules/@next/eslint-plugin-next": {
@@ -1108,9 +1109,9 @@
       }
     },
     "node_modules/@next/swc-darwin-arm64": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.2.3.tgz",
-      "integrity": "sha512-u37KDKTKQ+OQLvY+z7SNXixwo4Q2/IAJFDzU1fYe66IbCE51aDSAzkNDkWmLN0yjTUh4BKBd+hb69jYn6qqqSg==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-arm64/-/swc-darwin-arm64-16.2.4.tgz",
+      "integrity": "sha512-OXTFFox5EKN1Ym08vfrz+OXxmCcEjT4SFMbNRsWZE99dMqt2Kcusl5MqPXcW232RYkMLQTy0hqgAMEsfEd/l2A==",
       "cpu": [
         "arm64"
       ],
@@ -1124,9 +1125,9 @@
       }
     },
     "node_modules/@next/swc-darwin-x64": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.2.3.tgz",
-      "integrity": "sha512-gHjL/qy6Q6CG3176FWbAKyKh9IfntKZTB3RY/YOJdDFpHGsUDXVH38U4mMNpHVGXmeYW4wj22dMp1lTfmu/bTQ==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-16.2.4.tgz",
+      "integrity": "sha512-XhpVnUfmYWvD3YrXu55XdcAkQtOnvaI6wtQa8fuF5fGoKoxIUZ0kWPtcOfqJEWngFF/lOS9l3+O9CcownhiQxQ==",
       "cpu": [
         "x64"
       ],
@@ -1140,9 +1141,9 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-gnu": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.2.3.tgz",
-      "integrity": "sha512-U6vtblPtU/P14Y/b/n9ZY0GOxbbIhTFuaFR7F4/uMBidCi2nSdaOFhA0Go81L61Zd6527+yvuX44T4ksnf8T+Q==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-16.2.4.tgz",
+      "integrity": "sha512-Mx/tjlNA3G8kg14QvuGAJ4xBwPk1tUHq56JxZ8CXnZwz1Etz714soCEzGQQzVMz4bEnGPowzkV6Xrp6wAkEWOQ==",
       "cpu": [
         "arm64"
       ],
@@ -1156,9 +1157,9 @@
       }
     },
     "node_modules/@next/swc-linux-arm64-musl": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.2.3.tgz",
-      "integrity": "sha512-/YV0LgjHUmfhQpn9bVoGc4x4nan64pkhWR5wyEV8yCOfwwrH630KpvRg86olQHTwHIn1z59uh6JwKvHq1h4QEw==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-16.2.4.tgz",
+      "integrity": "sha512-iVMMp14514u7Nup2umQS03nT/bN9HurK8ufylC3FZNykrwjtx7V1A7+4kvhbDSCeonTVqV3Txnv0Lu+m2oDXNg==",
       "cpu": [
         "arm64"
       ],
@@ -1172,9 +1173,9 @@
       }
     },
     "node_modules/@next/swc-linux-x64-gnu": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.2.3.tgz",
-      "integrity": "sha512-/HiWEcp+WMZ7VajuiMEFGZ6cg0+aYZPqCJD3YJEfpVWQsKYSjXQG06vJP6F1rdA03COD9Fef4aODs3YxKx+RDQ==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-16.2.4.tgz",
+      "integrity": "sha512-EZOvm1aQWgnI/N/xcWOlnS3RQBk0VtVav5Zo7n4p0A7UKyTDx047k8opDbXgBpHl4CulRqRfbw3QrX2w5UOXMQ==",
       "cpu": [
         "x64"
       ],
@@ -1188,9 +1189,9 @@
       }
     },
     "node_modules/@next/swc-linux-x64-musl": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.2.3.tgz",
-      "integrity": "sha512-Kt44hGJfZSefebhk/7nIdivoDr3Ugp5+oNz9VvF3GUtfxutucUIHfIO0ZYO8QlOPDQloUVQn4NVC/9JvHRk9hw==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-16.2.4.tgz",
+      "integrity": "sha512-h9FxsngCm9cTBf71AR4fGznDEDx1hS7+kSEiIRjq5kO1oXWm07DxVGZjCvk0SGx7TSjlUqhI8oOyz7NfwAdPoA==",
       "cpu": [
         "x64"
       ],
@@ -1204,9 +1205,9 @@
       }
     },
     "node_modules/@next/swc-win32-arm64-msvc": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.2.3.tgz",
-      "integrity": "sha512-O2NZ9ie3Tq6xj5Z5CSwBT3+aWAMW2PIZ4egUi9MaWLkwaehgtB7YZjPm+UpcNpKOme0IQuqDcor7BsW6QBiQBw==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-16.2.4.tgz",
+      "integrity": "sha512-3NdJV5OXMSOeJYijX+bjaLge3mJBlh4ybydbT4GFoB/2hAojWHtMhl3CYlYoMrjPuodp0nzFVi4Tj2+WaMg+Ow==",
       "cpu": [
         "arm64"
       ],
@@ -1220,9 +1221,9 @@
       }
     },
     "node_modules/@next/swc-win32-x64-msvc": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.2.3.tgz",
-      "integrity": "sha512-Ibm29/GgB/ab5n7XKqlStkm54qqZE8v2FnijUPBgrd67FWrac45o/RsNlaOWjme/B5UqeWt/8KM4aWBwA1D2Kw==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-16.2.4.tgz",
+      "integrity": "sha512-kMVGgsqhO5YTYODD9IPGGhA6iprWidQckK3LmPeW08PIFENRmgfb4MjXHO+p//d+ts2rpjvK5gXWzXSMrPl9cw==",
       "cpu": [
         "x64"
       ],
@@ -1394,6 +1395,7 @@
       "resolved": "https://registry.npmjs.org/@octokit/core/-/core-7.0.6.tgz",
       "integrity": "sha512-DhGl4xMVFGVIyMwswXeyzdL4uXD5OGILGX5N8Y+f6W7LhC1Ze2poSNrkF/fedpVDHEEZ+PHFW0vL14I+mm8K3Q==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@octokit/auth-token": "^6.0.0",
         "@octokit/graphql": "^9.0.3",
@@ -1634,6 +1636,15 @@
         "url": "https://github.com/sponsors/Boshen"
       }
     },
+    "node_modules/@panva/hkdf": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/@panva/hkdf/-/hkdf-1.2.1.tgz",
+      "integrity": "sha512-6oclG6Y3PiDFcoyk8srjLfVKyMfVCKJ27JwNPViuXziFpmdz+MZnZN/aKY0JGXgYuO/VghU0jcOAZgWXZ1Dmrw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
     "node_modules/@radix-ui/react-compose-refs": {
       "version": "1.1.2",
       "resolved": "https://registry.npmjs.org/@radix-ui/react-compose-refs/-/react-compose-refs-1.1.2.tgz",
@@ -2327,7 +2338,6 @@
       "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@babel/code-frame": "^7.10.4",
         "@babel/runtime": "^7.12.5",
@@ -2348,7 +2358,6 @@
       "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "dependencies": {
         "dequal": "^2.0.3"
       }
@@ -2424,8 +2433,7 @@
       "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz",
       "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/@types/aws-lambda": {
       "version": "8.10.160",
@@ -2526,6 +2534,7 @@
       "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "undici-types": "~7.19.0"
       }
@@ -2535,6 +2544,7 @@
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
       "integrity": "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "csstype": "^3.2.2"
       }
@@ -2545,6 +2555,7 @@
       "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "peerDependencies": {
         "@types/react": "^19.2.0"
       }
@@ -2600,6 +2611,7 @@
       "integrity": "sha512-klQbnPAAiGYFyI02+znpBRLyjL4/BrBd0nyWkdC0s/6xFLkXYQ8OoRrSkqacS1ddVxf/LDyODIKbQ5TgKAf/Fg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@typescript-eslint/scope-manager": "8.56.1",
         "@typescript-eslint/types": "8.56.1",
@@ -3121,6 +3133,7 @@
       "integrity": "sha512-x7FptB5oDruxNPDNY2+S8tCh0pcq7ymCe1gTHcsp733jYjrJl8V1gMUlVysuCD9Kz46Xz9t1akkv08dPcYDs1w==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@bcoe/v8-coverage": "^1.0.2",
         "@vitest/utils": "4.1.4",
@@ -3265,6 +3278,7 @@
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -3305,7 +3319,6 @@
       "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=8"
       }
@@ -3604,9 +3617,9 @@
       "license": "MIT"
     },
     "node_modules/brace-expansion": {
-      "version": "5.0.3",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.3.tgz",
-      "integrity": "sha512-fy6KJm2RawA5RcHkLa1z/ScpBeA762UF9KmZQxwIbDtRJrgLzM10depAiEQ+CXYcoiqW1/m96OAAoke2nE9EeA==",
+      "version": "5.0.5",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz",
+      "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -3649,6 +3662,7 @@
         }
       ],
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "baseline-browser-mapping": "^2.9.0",
         "caniuse-lite": "^1.0.30001759",
@@ -3823,6 +3837,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/cookie": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz",
+      "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -4048,8 +4071,7 @@
       "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz",
       "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/dunder-proto": {
       "version": "1.0.1",
@@ -4319,6 +4341,7 @@
       "integrity": "sha512-+L0vBFYGIpSNIt/KWTpFonPrqYvgKw1eUI5Vn7mEogrQcWtWYtNQ7dNqC+px/J0idT3BAkiWrhfS7k+Tum8TUA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.2",
@@ -4404,9 +4427,9 @@
       "license": "MIT"
     },
     "node_modules/eslint-config-next/node_modules/brace-expansion": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
-      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "version": "1.1.14",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.14.tgz",
+      "integrity": "sha512-MWPGfDxnyzKU7rNOW9SP/c50vi3xrmrua/+6hfPbCS2ABNWfx24vPidzvC7krjU/RTo235sV776ymlsMtGKj8g==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
@@ -4455,6 +4478,7 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -4590,9 +4614,9 @@
       }
     },
     "node_modules/eslint-config-next/node_modules/minimatch": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.3.tgz",
-      "integrity": "sha512-M2GCs7Vk83NxkUyQV1bkABc4yxgz9kILhHImZiBPAZ9ybuvCb0/H7lEl5XvIg3g+9d4eNotkZA5IWwYl0tibaA==",
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
       "dev": true,
       "license": "ISC",
       "dependencies": {
@@ -4943,9 +4967,9 @@
       }
     },
     "node_modules/flatted": {
-      "version": "3.3.3",
-      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.3.3.tgz",
-      "integrity": "sha512-GX+ysw4PBCz0PzosHDepZGANEuFCMLrnRTiEy9McGjmkCQYwRq4A/X786G/fjM/+OjsWSU1ZrY5qyARZmO/uwg==",
+      "version": "3.4.2",
+      "resolved": "https://registry.npmjs.org/flatted/-/flatted-3.4.2.tgz",
+      "integrity": "sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==",
       "dev": true,
       "license": "ISC"
     },
@@ -6051,6 +6075,15 @@
         "jiti": "lib/jiti-cli.mjs"
       }
     },
+    "node_modules/jose": {
+      "version": "4.15.9",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-4.15.9.tgz",
+      "integrity": "sha512-1vUQX+IdDMVPj4k8kOxgUqlcK518yluMuGZwqlr44FS1ppZB/5GWh4rZG89erpOBOJjU/OBsnCVFfapsRz6nEA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
     "node_modules/js-tokens": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-4.0.0.tgz",
@@ -6490,7 +6523,6 @@
       "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "lz-string": "bin/bin.js"
       }
@@ -7519,12 +7551,13 @@
       "license": "MIT"
     },
     "node_modules/next": {
-      "version": "16.2.3",
-      "resolved": "https://registry.npmjs.org/next/-/next-16.2.3.tgz",
-      "integrity": "sha512-9V3zV4oZFza3PVev5/poB9g0dEafVcgNyQ8eTRop8GvxZjV2G15FC5ARuG1eFD42QgeYkzJBJzHghNP8Ad9xtA==",
+      "version": "16.2.4",
+      "resolved": "https://registry.npmjs.org/next/-/next-16.2.4.tgz",
+      "integrity": "sha512-kPvz56wF5frc+FxlHI5qnklCzbq53HTwORaWBGdT0vNoKh1Aya9XC8aPauH4NJxqtzbWsS5mAbctm4cr+EkQ2Q==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
-        "@next/env": "16.2.3",
+        "@next/env": "16.2.4",
         "@swc/helpers": "0.5.15",
         "baseline-browser-mapping": "^2.9.19",
         "caniuse-lite": "^1.0.30001579",
@@ -7538,14 +7571,14 @@
         "node": ">=20.9.0"
       },
       "optionalDependencies": {
-        "@next/swc-darwin-arm64": "16.2.3",
-        "@next/swc-darwin-x64": "16.2.3",
-        "@next/swc-linux-arm64-gnu": "16.2.3",
-        "@next/swc-linux-arm64-musl": "16.2.3",
-        "@next/swc-linux-x64-gnu": "16.2.3",
-        "@next/swc-linux-x64-musl": "16.2.3",
-        "@next/swc-win32-arm64-msvc": "16.2.3",
-        "@next/swc-win32-x64-msvc": "16.2.3",
+        "@next/swc-darwin-arm64": "16.2.4",
+        "@next/swc-darwin-x64": "16.2.4",
+        "@next/swc-linux-arm64-gnu": "16.2.4",
+        "@next/swc-linux-arm64-musl": "16.2.4",
+        "@next/swc-linux-x64-gnu": "16.2.4",
+        "@next/swc-linux-x64-musl": "16.2.4",
+        "@next/swc-win32-arm64-msvc": "16.2.4",
+        "@next/swc-win32-x64-msvc": "16.2.4",
         "sharp": "^0.34.5"
       },
       "peerDependencies": {
@@ -7571,6 +7604,38 @@
         }
       }
     },
+    "node_modules/next-auth": {
+      "version": "4.24.14",
+      "resolved": "https://registry.npmjs.org/next-auth/-/next-auth-4.24.14.tgz",
+      "integrity": "sha512-YRz6xFDXKUwiXSMMChbrBEWyFktZ1qZXEgeSHQQ3nsy08B4c/xLk6REeutRsIFwkjY/1+ShHnu07DN3JeJguig==",
+      "license": "ISC",
+      "dependencies": {
+        "@babel/runtime": "^7.20.13",
+        "@panva/hkdf": "^1.0.2",
+        "cookie": "^0.7.0",
+        "jose": "^4.15.5",
+        "oauth": "^0.9.15",
+        "openid-client": "^5.4.0",
+        "preact": "^10.6.3",
+        "preact-render-to-string": "^5.1.19",
+        "uuid": "^8.3.2"
+      },
+      "peerDependencies": {
+        "@auth/core": "0.34.3",
+        "next": "^12.2.5 || ^13 || ^14 || ^15 || ^16",
+        "nodemailer": "^7.0.7",
+        "react": "^17.0.2 || ^18 || ^19",
+        "react-dom": "^17.0.2 || ^18 || ^19"
+      },
+      "peerDependenciesMeta": {
+        "@auth/core": {
+          "optional": true
+        },
+        "nodemailer": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/next-sitemap": {
       "version": "4.2.3",
       "resolved": "https://registry.npmjs.org/next-sitemap/-/next-sitemap-4.2.3.tgz",
@@ -7660,6 +7725,12 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/oauth": {
+      "version": "0.9.15",
+      "resolved": "https://registry.npmjs.org/oauth/-/oauth-0.9.15.tgz",
+      "integrity": "sha512-a5ERWK1kh38ExDEfoO6qUHJb32rd7aYmPHuyCu3Fta/cnICvYmgd2uhuKXvPD+PXB+gCEYYEaQdIRAjCOwAKNA==",
+      "license": "MIT"
+    },
     "node_modules/object-assign": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz",
@@ -7670,6 +7741,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/object-hash": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-2.2.0.tgz",
+      "integrity": "sha512-gScRMn0bS5fH+IuwyIFgnh9zBdo4DV+6GhygmWM9HyNJSgS0hScp1f5vjtm7oIIOiT9trXrShAkLFSc2IqKNgw==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 6"
+      }
+    },
     "node_modules/object-inspect": {
       "version": "1.13.4",
       "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
@@ -7816,6 +7896,48 @@
         "node": ">= 20"
       }
     },
+    "node_modules/oidc-token-hash": {
+      "version": "5.2.0",
+      "resolved": "https://registry.npmjs.org/oidc-token-hash/-/oidc-token-hash-5.2.0.tgz",
+      "integrity": "sha512-6gj2m8cJZ+iSW8bm0FXdGF0YhIQbKrfP4yWTNzxc31U6MOjfEmB1rHvlYvxI1B7t7BCi1F2vYTT6YhtQRG4hxw==",
+      "license": "MIT",
+      "engines": {
+        "node": "^10.13.0 || >=12.0.0"
+      }
+    },
+    "node_modules/openid-client": {
+      "version": "5.7.1",
+      "resolved": "https://registry.npmjs.org/openid-client/-/openid-client-5.7.1.tgz",
+      "integrity": "sha512-jDBPgSVfTnkIh71Hg9pRvtJc6wTwqjRkN88+gCFtYWrlP4Yx2Dsrow8uPi3qLr/aeymPF3o2+dS+wOpglK04ew==",
+      "license": "MIT",
+      "dependencies": {
+        "jose": "^4.15.9",
+        "lru-cache": "^6.0.0",
+        "object-hash": "^2.2.0",
+        "oidc-token-hash": "^5.0.3"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/panva"
+      }
+    },
+    "node_modules/openid-client/node_modules/lru-cache": {
+      "version": "6.0.0",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-6.0.0.tgz",
+      "integrity": "sha512-Jo6dJ04CmSjuznwJSS3pUeWmd/H0ffTlkXXgwZi+eq1UCmqQwCh+eLsYOYCwY991i2Fah4h1BEMCx4qThGbsiA==",
+      "license": "ISC",
+      "dependencies": {
+        "yallist": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/openid-client/node_modules/yallist": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
+      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
+      "license": "ISC"
+    },
     "node_modules/optionator": {
       "version": "0.9.4",
       "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
@@ -7962,9 +8084,9 @@
       "license": "ISC"
     },
     "node_modules/picomatch": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
-      "integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.2.tgz",
+      "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -8027,6 +8149,35 @@
         "node": ">=4"
       }
     },
+    "node_modules/preact": {
+      "version": "10.29.1",
+      "resolved": "https://registry.npmjs.org/preact/-/preact-10.29.1.tgz",
+      "integrity": "sha512-gQCLc/vWroE8lIpleXtdJhTFDogTdZG9AjMUpVkDf2iTCNwYNWA+u16dL41TqUDJO4gm2IgrcMv3uTpjd4Pwmg==",
+      "license": "MIT",
+      "peer": true,
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/preact"
+      }
+    },
+    "node_modules/preact-render-to-string": {
+      "version": "5.2.6",
+      "resolved": "https://registry.npmjs.org/preact-render-to-string/-/preact-render-to-string-5.2.6.tgz",
+      "integrity": "sha512-JyhErpYOvBV1hEPwIxc/fHWXPfnEGdRKxc8gFdAZ7XV4tlzyzG847XAyEZqoDnynP88akM4eaHcSOzNcLWFguw==",
+      "license": "MIT",
+      "dependencies": {
+        "pretty-format": "^3.8.0"
+      },
+      "peerDependencies": {
+        "preact": ">=10"
+      }
+    },
+    "node_modules/preact-render-to-string/node_modules/pretty-format": {
+      "version": "3.8.0",
+      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-3.8.0.tgz",
+      "integrity": "sha512-WuxUnVtlWL1OfZFQFuqvnvs6MiAGk9UNsBostyBOB0Is9wb5uRESevA6rnl/rkksXaGX3GzZhPup5d6Vp1nFew==",
+      "license": "MIT"
+    },
     "node_modules/prelude-ls": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
@@ -8043,7 +8194,6 @@
       "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "ansi-regex": "^5.0.1",
         "ansi-styles": "^5.0.0",
@@ -8059,7 +8209,6 @@
       "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=10"
       },
@@ -8072,8 +8221,7 @@
       "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz",
       "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==",
       "dev": true,
-      "license": "MIT",
-      "peer": true
+      "license": "MIT"
     },
     "node_modules/prop-types": {
       "version": "15.8.1",
@@ -8133,6 +8281,7 @@
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
       "integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=0.10.0"
       }
@@ -8142,6 +8291,7 @@
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.4.tgz",
       "integrity": "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==",
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "scheduler": "^0.27.0"
       },
@@ -8996,7 +9146,8 @@
       "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.2.2.tgz",
       "integrity": "sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==",
       "dev": true,
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
     },
     "node_modules/tailwindcss-animate": {
       "version": "1.0.7",
@@ -9075,11 +9226,12 @@
       }
     },
     "node_modules/tinyglobby/node_modules/picomatch": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
-      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -9268,6 +9420,7 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
+      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -9508,6 +9661,15 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/uuid": {
+      "version": "8.3.2",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+      "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist/bin/uuid"
+      }
+    },
     "node_modules/vfile": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz",
@@ -9556,6 +9718,7 @@
       "integrity": "sha512-dbU7/iLVa8KZALJyLOBOQ88nOXtNG8vxKuOT4I2mD+Ya70KPceF4IAmDsmU0h1Qsn5bPrvsY9HJstCRh3hG6Uw==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "lightningcss": "^1.32.0",
         "picomatch": "^4.0.4",
@@ -9647,6 +9810,7 @@
       "integrity": "sha512-tFuJqTxKb8AvfyqMfnavXdzfy3h3sWZRWwfluGbkeR7n0HUev+FmNgZ8SDrRBTVrVCjgH5cA21qGbCffMNtWvg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@vitest/expect": "4.1.4",
         "@vitest/mocker": "4.1.4",
@@ -9732,9 +9896,9 @@
       }
     },
     "node_modules/vitest/node_modules/picomatch": {
-      "version": "4.0.3",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
-      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
       "dev": true,
       "license": "MIT",
       "engines": {
@@ -9912,6 +10076,7 @@
       "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }
diff --git a/package.json b/package.json
index 44aa724..fc09f48 100644
--- a/package.json
+++ b/package.json
@@ -14,7 +14,8 @@
     "@radix-ui/react-slot": "^1.2.4",
     "@vercel/analytics": "^2.0.1",
     "lucide-react": "^0.577.0",
-    "next": "16.2.3",
+    "next": "^16.2.4",
+    "next-auth": "^4.24.14",
     "octokit": "^5.0.5",
     "react": "19.2.4",
     "react-dom": "19.2.4",
diff --git a/public/robots.txt b/public/robots.txt
new file mode 100644
index 0000000..8603b53
--- /dev/null
+++ b/public/robots.txt
@@ -0,0 +1,9 @@
+# *
+User-agent: *
+Allow: /
+
+# Host
+Host: https://readmegen-ai.vercel.app
+
+# Sitemaps
+Sitemap: https://readmegen-ai.vercel.app/sitemap.xml
diff --git a/public/sitemap-0.xml b/public/sitemap-0.xml
new file mode 100644
index 0000000..6ac8e51
--- /dev/null
+++ b/public/sitemap-0.xml
@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:news="http://www.google.com/schemas/sitemap-news/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:mobile="http://www.google.com/schemas/sitemap-mobile/1.0" xmlns:image="http://www.google.com/schemas/sitemap-image/1.1" xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
+<url><loc>https://readmegen-ai.vercel.app</loc><lastmod>2026-04-04T09:31:17.224Z</lastmod><changefreq>weekly</changefreq><priority>1</priority></url>
+<url><loc>https://readmegen-ai.vercel.app/docs</loc><lastmod>2026-04-04T09:31:17.224Z</lastmod><changefreq>monthly</changefreq><priority>0.8</priority></url>
+<url><loc>https://readmegen-ai.vercel.app/examples</loc><lastmod>2026-04-04T09:31:17.224Z</lastmod><changefreq>monthly</changefreq><priority>0.8</priority></url>
+<url><loc>https://readmegen-ai.vercel.app/features</loc><lastmod>2026-04-04T09:31:17.224Z</lastmod><changefreq>monthly</changefreq><priority>0.8</priority></url>
+<url><loc>https://readmegen-ai.vercel.app/generate</loc><lastmod>2026-04-04T09:31:17.224Z</lastmod><changefreq>weekly</changefreq><priority>0.9</priority></url>
+</urlset>
\ No newline at end of file
diff --git a/public/sitemap.xml b/public/sitemap.xml
new file mode 100644
index 0000000..b3a9e11
--- /dev/null
+++ b/public/sitemap.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<sitemap><loc>https://readmegen-ai.vercel.app/sitemap-0.xml</loc></sitemap>
+</sitemapindex>
\ No newline at end of file
diff --git a/src/app/api/auth/[...nextauth]/route.ts b/src/app/api/auth/[...nextauth]/route.ts
new file mode 100644
index 0000000..7b38c1b
--- /dev/null
+++ b/src/app/api/auth/[...nextauth]/route.ts
@@ -0,0 +1,6 @@
+import NextAuth from "next-auth";
+import { authOptions } from "@/lib/auth";
+
+const handler = NextAuth(authOptions);
+
+export { handler as GET, handler as POST };
diff --git a/src/app/api/generate/route.ts b/src/app/api/generate/route.ts
index acb17e5..5c51aa9 100644
--- a/src/app/api/generate/route.ts
+++ b/src/app/api/generate/route.ts
@@ -1,40 +1,41 @@
-import { NextResponse } from "next/server";
+import { getToken } from "next-auth/jwt";
+import { NextRequest, NextResponse } from "next/server";
 import { getGeminiModel } from "@/lib/gemini";
-import { getRepoData, getRepoContents } from "@/lib/octokit";
-import { SUPPORTED_LANGUAGES } from "@/constants/languages";
+import { getRepoSnapshot, RepoAccessError } from "@/lib/octokit";
 
 export const dynamic = "force-dynamic";
 
 /**
- * AI README Generation Endpoint
- * Optimized for data accuracy, clean prompt interpolation, and multi-language support.
+ * Enhanced Multi-Step README Generation Endpoint
  *
- * @param {Request} req - The incoming Next.js/standard Web API Request object containing the repo URL and optional language.
+ * @param {NextRequest} req - The incoming Next.js request object containing the repo URL and optional language.
  * @returns {Promise<NextResponse>} A JSON response containing the generated Markdown or an error message.
  */
-export async function POST(req: Request) {
+export async function POST(req: NextRequest) {
   let rawUrl: string;
   let language: string;
+  let ackPrivateRepo = false;
   try {
     const body = await req.json();
     rawUrl = body.url;
     language = body.language || "English";
+    ackPrivateRepo = Boolean(body.ackPrivateRepo);
   } catch {
     return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
   }
 
-  try {
-    const trimmedUrl = rawUrl?.trim();
-    if (!trimmedUrl) {
+    // Validate required fields
+    if (!githubUrl) {
       return NextResponse.json(
         { error: "GitHub URL is required" },
         { status: 400 },
       );
     }
 
+    // Validate GitHub URL format
     let parsedUrl: URL;
     try {
-      parsedUrl = new URL(trimmedUrl);
+      parsedUrl = new URL(githubUrl.trim());
     } catch {
       return NextResponse.json(
         { error: "Please provide a valid URL" },
@@ -63,13 +64,34 @@ export async function POST(req: Request) {
       );
     }
 
-    const [repoInfo, repoContents] = await Promise.all([
-      getRepoData(owner, repo),
-      getRepoContents(owner, repo),
-    ]);
+    const token = await getToken({
+      req,
+      secret: process.env.NEXTAUTH_SECRET,
+    });
+    const accessToken =
+      typeof token?.accessToken === "string" ? token.accessToken : undefined;
+
+    const { repoInfo, repoContents } = await getRepoSnapshot(
+      owner,
+      repo,
+      accessToken,
+    );
+
+    const isPrivateRepo = Boolean(repoInfo?.private);
+    if (isPrivateRepo && !ackPrivateRepo) {
+      return NextResponse.json(
+        {
+          error: "private_repo_consent_required",
+          message:
+            "This repository appears to be private. Confirm consent to send private repository data to the AI model by re-submitting with { ackPrivateRepo: true }.",
+          authRequired: Boolean(accessToken),
+        },
+        { status: 403 },
+      );
+    }
 
     const files = Array.isArray(repoContents)
-      ? repoContents.map((f: { name: string }) => f.name)
+      ? repoContents.map((f: { path: string }) => f.path)
       : [];
     const fileListString =
       files.length > 0 ? files.join(", ") : "Standard repository structure";
@@ -158,12 +180,50 @@ export async function POST(req: Request) {
 
     return NextResponse.json({ markdown: cleanMarkdown });
   } catch (error: unknown) {
+    if (error instanceof RepoAccessError) {
+      return NextResponse.json(
+        {
+          error: error.message,
+          authRequired: error.code === "AUTH_REQUIRED",
+        },
+        { status: error.status },
+      );
+    }
+
     const message =
       error instanceof Error ? error.message : "Internal Server Error";
     console.error("README Generation Failed:", message);
 
+    // Return successful result with enhanced metadata
+    return NextResponse.json({
+      success: true,
+      markdown: result.readme, // Keep 'markdown' key for compatibility with existing frontend
+      stats: {
+        sectionsGenerated: result.stats.sectionsGenerated,
+        sectionsTotal: result.stats.sectionsTotal,
+        tokensUsed: result.stats.tokensUsed,
+        timeElapsed: result.stats.timeElapsed,
+        generationMethod: "multi-step", // Indicate the method used
+      },
+      metadata: {
+        name: result.metadata?.name,
+        description: result.metadata?.description,
+        language: result.metadata?.language,
+        stars: result.metadata?.stars,
+        license: result.metadata?.license,
+        projectType: result.structure?.projectType,
+        techStack: result.structure?.techStack.primary,
+        frameworks: result.structure?.techStack.frameworks,
+      },
+      warnings: result.errors.length > 0 ? result.errors : undefined,
+    });
+  } catch (error) {
+    console.error("Multi-step README generation API error:", error);
     return NextResponse.json(
-      { error: "Failed to generate README. Check your URL and try again." },
+      {
+        error: "Internal server error in multi-step README generation",
+        message: error instanceof Error ? error.message : "Unknown error",
+      },
       { status: 500 },
     );
   }
diff --git a/src/app/api/generate/route.ts.backup b/src/app/api/generate/route.ts.backup
new file mode 100644
index 0000000..acb17e5
--- /dev/null
+++ b/src/app/api/generate/route.ts.backup
@@ -0,0 +1,170 @@
+import { NextResponse } from "next/server";
+import { getGeminiModel } from "@/lib/gemini";
+import { getRepoData, getRepoContents } from "@/lib/octokit";
+import { SUPPORTED_LANGUAGES } from "@/constants/languages";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * AI README Generation Endpoint
+ * Optimized for data accuracy, clean prompt interpolation, and multi-language support.
+ *
+ * @param {Request} req - The incoming Next.js/standard Web API Request object containing the repo URL and optional language.
+ * @returns {Promise<NextResponse>} A JSON response containing the generated Markdown or an error message.
+ */
+export async function POST(req: Request) {
+  let rawUrl: string;
+  let language: string;
+  try {
+    const body = await req.json();
+    rawUrl = body.url;
+    language = body.language || "English";
+  } catch {
+    return NextResponse.json({ error: "Invalid JSON body" }, { status: 400 });
+  }
+
+  try {
+    const trimmedUrl = rawUrl?.trim();
+    if (!trimmedUrl) {
+      return NextResponse.json(
+        { error: "GitHub URL is required" },
+        { status: 400 },
+      );
+    }
+
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(trimmedUrl);
+    } catch {
+      return NextResponse.json(
+        { error: "Please provide a valid URL" },
+        { status: 400 },
+      );
+    }
+
+    if (
+      parsedUrl.hostname !== "github.com" &&
+      parsedUrl.hostname !== "www.github.com"
+    ) {
+      return NextResponse.json(
+        { error: "Only GitHub URLs are supported" },
+        { status: 400 },
+      );
+    }
+
+    const pathSegments = parsedUrl.pathname.split("/").filter(Boolean);
+    const owner = pathSegments[0];
+    const repo = pathSegments[1];
+
+    if (!owner || !repo) {
+      return NextResponse.json(
+        { error: "URL must include owner and repository name" },
+        { status: 400 },
+      );
+    }
+
+    const [repoInfo, repoContents] = await Promise.all([
+      getRepoData(owner, repo),
+      getRepoContents(owner, repo),
+    ]);
+
+    const files = Array.isArray(repoContents)
+      ? repoContents.map((f: { name: string }) => f.name)
+      : [];
+    const fileListString =
+      files.length > 0 ? files.join(", ") : "Standard repository structure";
+
+    // Tech Stack detection logic
+    const hasNode = files.includes("package.json");
+    const hasPython =
+      files.includes("requirements.txt") || files.includes("setup.py");
+    const hasDocker =
+      files.includes("Dockerfile") || files.includes("docker-compose.yml");
+
+    // Fix: Cleanly joined Tech Stack labels
+    const stackLabels =
+      [
+        hasNode && "Node.js Environment",
+        hasPython && "Python Environment",
+        hasDocker && "Containerized",
+      ]
+        .filter(Boolean)
+        .join(", ") || "Generic Software Environment";
+
+    // Fix: Dynamic License detection
+    const licenseName =
+      repoInfo?.license?.name ||
+      repoInfo?.license?.spdx_id ||
+      "the repository's license file";
+
+    const model = getGeminiModel();
+
+    // Fix: Prompt updated with neutral fallbacks and dynamic license
+    const prompt = `
+**Role**: You are a Principal Solutions Architect and World-Class Technical Writer. 
+**Task**: Generate a professional, high-conversion README.md for the GitHub repository: "${repo}" in the following language: **${language}**.
+
+---
+### 1. PROJECT CONTEXT (VERIFIED DATA)
+- **Project Name**: ${repo}
+- **Description**: ${repoInfo?.description || "No description provided."}
+- **Primary Language**: ${repoInfo?.language || "Language unknown"}
+- **Detected Root Files**: ${fileListString}
+- **Tech Stack Context**: ${stackLabels}
+
+---
+### 2. STRICT README STRUCTURE REQUIREMENTS
+
+1. **Visual Header**:
+   - Center-aligned H1 with project name.
+   - A compelling 1-sentence tagline describing the **Value Proposition**.
+   - A centered row of Shields.io badges (Build, License, PRs Welcome, Stars).
+
+2. **The Strategic "Why" (Overview)**:
+   - **The Problem**: Use a blockquote to describe the real-world pain point this project solves.
+   - **The Solution**: Explain how this project provides a superior outcome for the user.
+
+3. **Key Features**:
+   - Minimum 5 features. Use emojis and focus on **User Benefits**.
+
+4. **Technical Architecture**:
+   - Provide a table of the tech stack: | Technology | Purpose | Key Benefit |.
+   - Create a tree-style directory structure code block using 📁 for folders and 📄 for files based on the file manifest provided.
+
+5. **Operational Setup**:
+   - **Prerequisites**: List required runtimes.
+   - **Installation**: Provide step-by-step terminal commands. 
+     ${hasNode ? "- Use npm/yarn/pnpm since package.json was detected." : ""}
+     ${hasPython ? "- Use pip/venv since Python markers were detected." : ""}
+   - **Environment**: If any .env or config files are in the manifest, include a configuration section.
+
+6. **Community & Governance**:
+   - Professional "Contributing" section (Fork -> Branch -> PR).
+   - Detailed "License" section: Reference ${licenseName} and provide a summary of permissions.
+
+---
+### 3. TONE & STYLE
+- **Tone**: Authoritative, polished, and developer-centric.
+- **Visuals**: Extensive use of Markdown formatting.
+- **Constraint**: Return ONLY the raw Markdown. No conversational filler.
+    `;
+
+    const result = await model.generateContent(prompt);
+    const response = await result.response;
+    const markdown = response.text().trim();
+    const cleanMarkdown = markdown
+      .replace(/^```(markdown|md)?\n/, "")
+      .replace(/\n```$/, "");
+
+    return NextResponse.json({ markdown: cleanMarkdown });
+  } catch (error: unknown) {
+    const message =
+      error instanceof Error ? error.message : "Internal Server Error";
+    console.error("README Generation Failed:", message);
+
+    return NextResponse.json(
+      { error: "Failed to generate README. Check your URL and try again." },
+      { status: 500 },
+    );
+  }
+}
diff --git a/src/app/generate/GeneratePageClient.tsx b/src/app/generate/GeneratePageClient.tsx
index b430b3e..a36f842 100644
--- a/src/app/generate/GeneratePageClient.tsx
+++ b/src/app/generate/GeneratePageClient.tsx
@@ -15,6 +15,10 @@ interface GeneratePageProps {
 export default function GeneratePageClient({ repoSlug }: GeneratePageProps) {
   const [markdown, setMarkdown] = useState("");
   const [isLoading, setIsLoading] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [authRequired, setAuthRequired] = useState(false);
+  const [privateRepoConsentRequired, setPrivateRepoConsentRequired] =
+    useState(false);
 
   // Optional: Update document title for SPA navigation
   useEffect(() => {
@@ -29,28 +33,37 @@ export default function GeneratePageClient({ repoSlug }: GeneratePageProps) {
   const handleGenerate = async (
     githubUrl: string,
     language: string = "English",
+    ackPrivateRepo: boolean = false,
   ) => {
     setIsLoading(true);
     setMarkdown("");
+    setErrorMessage(null);
+    setAuthRequired(false);
+    setPrivateRepoConsentRequired(false);
     try {
       const response = await fetch("/api/generate", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ url: githubUrl, language }),
+        body: JSON.stringify({ url: githubUrl, language, ackPrivateRepo }),
       });
 
       if (!response.ok) {
         const errorText = await response.text();
         let errorMessage: string;
+        let requiresAuth = false;
         try {
           const errorData = JSON.parse(errorText);
           errorMessage = errorData.error || errorData.message || errorText;
+          requiresAuth = Boolean(errorData.authRequired);
+          setPrivateRepoConsentRequired(
+            errorData.error === "private_repo_consent_required",
+          );
         } catch {
           errorMessage = errorText || response.statusText;
         }
-        throw new Error(
-          `[${response.status} ${response.statusText}]: ${errorMessage}`,
-        );
+
+        setAuthRequired(requiresAuth);
+        throw new Error(errorMessage);
       }
 
       const data = await response.json();
@@ -64,7 +77,9 @@ export default function GeneratePageClient({ repoSlug }: GeneratePageProps) {
       }
     } catch (error: unknown) {
       console.error("Generation Error:", error);
-      alert(error instanceof Error ? error.message : "Something went wrong");
+      setErrorMessage(
+        error instanceof Error ? error.message : "Something went wrong",
+      );
     } finally {
       setIsLoading(false);
     }
@@ -85,6 +100,9 @@ export default function GeneratePageClient({ repoSlug }: GeneratePageProps) {
           isLoading={isLoading}
           initialValue={repoSlug ? `https://github.com/${repoSlug}` : ""}
           ariaLabel="Enter GitHub repository URL to generate README"
+          serverError={errorMessage}
+          authRequired={authRequired}
+          privateRepoConsentRequired={privateRepoConsentRequired}
         />
         <MarkdownPreview content={markdown} />
       </main>
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 1db0de7..e69260f 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -2,6 +2,7 @@ import type { Metadata } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
 import { Analytics } from "@vercel/analytics/next";
 import pkg from "../../package.json";
+import { Providers } from "./providers";
 import "./globals.css";
 
 const geistSans = Geist({
@@ -117,7 +118,6 @@ export default function RootLayout({
   return (
     <html lang="en">
       <head>
-        {/* JSON-LD structured data */}
         <script
           type="application/ld+json"
           dangerouslySetInnerHTML={{
@@ -128,9 +128,11 @@ export default function RootLayout({
       <body
         className={`${geistSans.variable} ${geistMono.variable} antialiased`}
       >
-        {children}
+        <Providers>
+          {children}
+        </Providers>
         <Analytics />
       </body>
     </html>
   );
-}
+}
\ No newline at end of file
diff --git a/src/app/providers.tsx b/src/app/providers.tsx
new file mode 100644
index 0000000..57974a7
--- /dev/null
+++ b/src/app/providers.tsx
@@ -0,0 +1,6 @@
+"use client";
+import { SessionProvider } from "next-auth/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <SessionProvider>{children}</SessionProvider>;
+}
\ No newline at end of file
diff --git a/src/components/Generator/SearchInput.tsx b/src/components/Generator/SearchInput.tsx
index dc3829b..c58fede 100644
--- a/src/components/Generator/SearchInput.tsx
+++ b/src/components/Generator/SearchInput.tsx
@@ -2,13 +2,16 @@
 import React, { useState } from "react";
 import { Loader2, Github, AlertCircle } from "lucide-react";
 import { Button } from "../ui/Button";
-import { SUPPORTED_LANGUAGES } from "@/constants/languages";
+import GitHubLoginButton from "../GitHubLoginButton";
 
 interface SearchInputProps {
-  onGenerate: (url: string, language: string) => void;
+  onGenerate: (url: string, language: string, ackPrivateRepo: boolean) => void;
   isLoading: boolean;
   initialValue?: string; // optional initial value
   ariaLabel?: string; // optional aria-label for accessibility
+  serverError?: string | null;
+  authRequired?: boolean;
+  privateRepoConsentRequired?: boolean;
 }
 
 /**
@@ -23,25 +26,15 @@ export const SearchInput = ({
   isLoading,
   initialValue,
   ariaLabel,
+  serverError,
+  authRequired = false,
+  privateRepoConsentRequired = false,
 }: SearchInputProps) => {
   // Initialize state directly from initialValue once
   const [url, setUrl] = useState(initialValue || "");
   const [language, setLanguage] = useState("English");
   const [error, setError] = useState<string | null>(null);
-
-  const languages = [
-    "English",
-    "Spanish",
-    "French",
-    "German",
-    "Chinese",
-    "Japanese",
-    "Korean",
-    "Portuguese",
-    "Russian",
-    "Arabic",
-    "Turkish",
-  ];
+  const [ackPrivateRepo, setAckPrivateRepo] = useState(false);
 
   const handleSubmit = (e: React.FormEvent) => {
     e.preventDefault();
@@ -51,7 +44,7 @@ export const SearchInput = ({
       /^https?:\/\/(www\.)?github\.com\/[\w.-]+\/[\w.-]+\/?$/;
 
     if (githubUrlPattern.test(url.trim())) {
-      onGenerate(url.trim(), language);
+      onGenerate(url.trim(), language, ackPrivateRepo);
     } else {
       setError("Please enter a valid GitHub repository URL.");
     }
@@ -88,7 +81,7 @@ export const SearchInput = ({
             onChange={(e) => setLanguage(e.target.value)}
             className="bg-zinc-900/50 border border-white/10 rounded-2xl px-6 py-6 text-white focus:outline-none focus:ring-2 focus:ring-blue-500/50 transition-all backdrop-blur-xl appearance-none cursor-pointer min-w-[140px]"
           >
-            {languages.map((lang) => (
+            {SUPPORTED_LANGUAGES.map((lang) => (
               <option
                 key={lang}
                 value={lang}
@@ -112,10 +105,32 @@ export const SearchInput = ({
           </Button>
         </div>
       </form>
-      {error && (
-        <div className="mt-4 flex items-center gap-2 text-red-400 text-sm animate-in fade-in slide-in-from-top-1">
-          <AlertCircle size={14} />
-          {error}
+      {privateRepoConsentRequired && (
+        <div className="flex items-start gap-3 rounded-2xl border border-yellow-500/20 bg-yellow-500/10 px-4 py-3 text-sm text-yellow-200">
+          <input
+            id="private-repo-consent"
+            type="checkbox"
+            checked={ackPrivateRepo}
+            onChange={(e) => setAckPrivateRepo(e.target.checked)}
+            className="mt-1 h-4 w-4 accent-yellow-400"
+          />
+          <label htmlFor="private-repo-consent" className="leading-relaxed">
+            I understand this repository is private and consent to send its
+            metadata and file list to the AI model for README generation.
+          </label>
+        </div>
+      )}
+      {(error || serverError) && (
+        <div className="mt-4 rounded-2xl border border-red-500/20 bg-red-500/10 px-4 py-3 text-sm animate-in fade-in slide-in-from-top-1">
+          <div className="flex items-center gap-2 text-red-300">
+            <AlertCircle size={14} />
+            {error || serverError}
+          </div>
+          {authRequired && Boolean(serverError) && !error && (
+            <div className="mt-3">
+              <GitHubLoginButton />
+            </div>
+          )}
         </div>
       )}
     </div>
diff --git a/src/components/GitHubLoginButton.tsx b/src/components/GitHubLoginButton.tsx
new file mode 100644
index 0000000..2b20372
--- /dev/null
+++ b/src/components/GitHubLoginButton.tsx
@@ -0,0 +1,55 @@
+"use client";
+import { useSession, signIn, signOut } from "next-auth/react";
+import { Github, LogIn, LogOut } from "lucide-react";
+
+type GitHubLoginButtonProps = {
+  onBeforeSignIn?: () => void;
+};
+
+export default function GitHubLoginButton({
+  onBeforeSignIn,
+}: GitHubLoginButtonProps) {
+  const { data: session, status } = useSession();
+  const displayName =
+    session?.user?.name || session?.user?.email || "GitHub user";
+
+  if (status === "loading") return null;
+
+  if (session) {
+    return (
+      <div className="flex flex-wrap items-center gap-2">
+        <div className="hidden sm:flex items-center gap-2 rounded-full border border-emerald-500/20 bg-emerald-500/10 px-3 py-2 text-xs font-medium text-emerald-200">
+          <Github size={14} />
+          <span className="max-w-[150px] truncate">{displayName}</span>
+        </div>
+        <button
+          onClick={() => signOut()}
+          className="inline-flex items-center justify-center gap-2 rounded-full border border-white/10 bg-white/5 px-4 py-2 text-sm font-medium text-white transition-all hover:border-white/25 hover:bg-white/10"
+        >
+          <LogOut size={14} />
+          Sign out
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      <button
+        onClick={() => {
+          onBeforeSignIn?.();
+          signIn("github");
+        }}
+        className="inline-flex items-center justify-center gap-2 rounded-full border border-white/10 bg-white/[0.04] px-4 py-2 text-sm font-semibold text-white transition-colors hover:border-white/15 hover:bg-white/[0.07]"
+      >
+        <Github size={15} />
+        <LogIn size={14} />
+        Login with GitHub
+      </button>
+      <p className="text-xs text-neutral-400">
+        We request GitHub’s “repo” scope to read private repo contents for
+        README generation.
+      </p>
+    </div>
+  );
+}
diff --git a/src/components/layout/Navbar.tsx b/src/components/layout/Navbar.tsx
index 6d4fefd..a9235b1 100644
--- a/src/components/layout/Navbar.tsx
+++ b/src/components/layout/Navbar.tsx
@@ -3,6 +3,7 @@ import React, { useState, useEffect } from "react";
 import Link from "next/link";
 import { Menu, X, Github } from "lucide-react";
 import { Button } from "../ui/Button";
+import GitHubLoginButton from "../GitHubLoginButton";
 
 export const Navbar = ({
   links,
@@ -27,7 +28,7 @@ export const Navbar = ({
       }`}
     >
       <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
-        <div className="flex justify-between items-center">
+        <div className="flex items-center">
           {/* Brand Logo */}
           <Link
             href="/"
@@ -43,7 +44,7 @@ export const Navbar = ({
           </Link>
 
           {/* Desktop Menu */}
-          <div className="hidden md:flex items-center space-x-1">
+          <div className="hidden md:flex items-center justify-center space-x-1">
             {links.map((link) => (
               <a
                 key={link.name}
@@ -56,7 +57,9 @@ export const Navbar = ({
           </div>
 
           {/* Action Buttons */}
-          <div className="flex items-center gap-3">
+          <div className="flex flex-1 items-center justify-end gap-3">
+            <GitHubLoginButton />
+
             {/* Using an anchor tag with button styling for the GitHub Link */}
             <a
               href="https://github.com/BeyteFlow/ReadmeGenAI"
@@ -94,9 +97,17 @@ export const Navbar = ({
               {link.name}
             </a>
           ))}
-          <Button variant="primary" className="w-full justify-center mt-4">
-            <Github size={18} /> Star our Repo
-          </Button>
+          <GitHubLoginButton onBeforeSignIn={() => setIsMenuOpen(false)} />
+          <a
+            href="https://github.com/BeyteFlow/ReadmeGenAI"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="w-full"
+          >
+            <Button variant="primary" className="w-full justify-center mt-4">
+              <Github size={18} /> Star our Repo
+            </Button>
+          </a>
         </div>
       )}
     </nav>
diff --git a/src/lib/auth.ts b/src/lib/auth.ts
new file mode 100644
index 0000000..8275a35
--- /dev/null
+++ b/src/lib/auth.ts
@@ -0,0 +1,41 @@
+import type { NextAuthOptions } from "next-auth";
+import GitHubProvider from "next-auth/providers/github";
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+const GITHUB_CLIENT_ID = requireEnv("GITHUB_CLIENT_ID");
+const GITHUB_CLIENT_SECRET = requireEnv("GITHUB_CLIENT_SECRET");
+
+export const authOptions: NextAuthOptions = {
+  secret: process.env.NEXTAUTH_SECRET,
+  session: {
+    strategy: "jwt",
+  },
+  providers: [
+    GitHubProvider({
+      clientId: GITHUB_CLIENT_ID,
+      clientSecret: GITHUB_CLIENT_SECRET,
+      authorization: {
+        params: { scope: "repo read:user" },
+      },
+    }),
+  ],
+  callbacks: {
+    async jwt({ token, account }) {
+      if (account?.access_token) {
+        token.accessToken = account.access_token;
+      }
+
+      return token;
+    },
+    async session({ session }) {
+      return session;
+    },
+  },
+};
diff --git a/src/lib/multi-step-readme-generator.ts b/src/lib/multi-step-readme-generator.ts
new file mode 100644
index 0000000..0921b05
--- /dev/null
+++ b/src/lib/multi-step-readme-generator.ts
@@ -0,0 +1,2515 @@
+/**
+ * Multi-Step README Generation Pipeline
+ *
+ * This module provides a robust, section-by-section approach to README generation
+ * that solves token limit issues and ensures complete README files.
+ *
+ * Architecture:
+ * 1. Repository Analysis - Extract metadata and structure
+ * 2. Section Planning - Determine optimal sections based on repo type
+ * 3. Section Generation - Generate each section individually
+ * 4. Assembly & Validation - Combine sections with retry logic
+ */
+
+import { GoogleGenerativeAI } from "@google/generative-ai";
+import { Octokit } from "octokit";
+
+// ============================================================================
+// TYPES AND INTERFACES
+// ============================================================================
+
+export interface RepositoryMetadata {
+  name: string;
+  description?: string;
+  language?: string;
+  license?: string;
+  stars: number;
+  forks: number;
+  isPrivate: boolean;
+  topics: string[];
+  homepage?: string;
+  size: number;
+  defaultBranch: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface RepositoryStructure {
+  rootFiles: string[];
+  directories: string[];
+  packageFiles: string[];
+  configFiles: string[];
+  documentationFiles: string[];
+  techStack: TechStackInfo;
+  projectType: ProjectType;
+}
+
+export interface TechStackInfo {
+  primary: string;
+  frameworks: string[];
+  tools: string[];
+  databases: string[];
+  deployment: string[];
+}
+
+export type ProjectType =
+  | "web-frontend"
+  | "web-backend"
+  | "mobile-app"
+  | "desktop-app"
+  | "library"
+  | "cli-tool"
+  | "data-science"
+  | "devops"
+  | "documentation"
+  | "other";
+
+export interface GitHubContentItem {
+  name: string;
+  path: string;
+  type: "file" | "dir" | "symlink" | "submodule";
+  size?: number;
+  sha?: string;
+  url?: string;
+  git_url?: string | null;
+  html_url?: string | null;
+  download_url?: string | null;
+  encoding?: string;
+  content?: string;
+  target?: string;
+  submodule_git_url?: string;
+  _links?: Record<string, unknown>;
+  [key: string]: unknown; // Allow additional properties
+}
+
+export type GitHubContentResponse = GitHubContentItem | GitHubContentItem[];
+
+export interface ReadmeSection {
+  id: string;
+  title: string;
+  priority: "critical" | "high" | "medium" | "low";
+  order: number;
+  estimatedTokens: number;
+  dependencies: string[]; // IDs of sections this depends on
+}
+
+export interface GenerationResult {
+  success: boolean;
+  content?: string;
+  tokensUsed?: number;
+  error?: string;
+  truncated?: boolean;
+}
+
+export interface GenerationConfig {
+  maxRetries: number;
+  maxTokensPerSection: number;
+  temperature: number;
+  concurrentSections: number;
+  enableContinuation: boolean;
+}
+
+// ============================================================================
+// REPOSITORY ANALYZER
+// ============================================================================
+
+export class RepositoryAnalyzer {
+  private octokit: Octokit;
+
+  constructor(githubToken?: string) {
+    this.octokit = new Octokit({
+      auth: githubToken,
+    });
+  }
+
+  /**
+   * Comprehensive repository analysis including metadata, structure, and tech stack
+   */
+  async analyzeRepository(
+    owner: string,
+    repo: string,
+  ): Promise<{
+    metadata: RepositoryMetadata;
+    structure: RepositoryStructure;
+  }> {
+    try {
+      // Fetch metadata and contents in parallel for efficiency
+      const [repoData, contentsData] = await Promise.all([
+        this.getRepositoryMetadata(owner, repo),
+        this.getRepositoryContents(owner, repo),
+      ]);
+
+      const structure = this.analyzeStructure(contentsData);
+
+      return {
+        metadata: repoData,
+        structure,
+      };
+    } catch (error) {
+      throw new Error(`Failed to analyze repository: ${error}`);
+    }
+  }
+
+  /**
+   * Extract repository metadata with enhanced fields
+   */
+  private async getRepositoryMetadata(
+    owner: string,
+    repo: string,
+  ): Promise<RepositoryMetadata> {
+    const { data } = await this.octokit.rest.repos.get({ owner, repo });
+
+    return {
+      name: data.name,
+      description: data.description || undefined,
+      language: data.language || undefined,
+      license: data.license?.name,
+      stars: data.stargazers_count,
+      forks: data.forks_count,
+      isPrivate: data.private,
+      topics: data.topics || [],
+      homepage: data.homepage || undefined,
+      size: data.size,
+      defaultBranch: data.default_branch,
+      createdAt: data.created_at,
+      updatedAt: data.updated_at,
+    };
+  }
+
+  /**
+   * Get repository contents with smart filtering to avoid token overflow
+   */
+
+  private async getRepositoryContents(
+    owner: string,
+    repo: string,
+    path = "",
+    maxDepth = 2,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): Promise<any[]> {
+    try {
+      const { data } = await this.octokit.rest.repos.getContent({
+        owner,
+        repo,
+        path,
+      });
+
+      if (!Array.isArray(data)) {
+        return [data];
+      }
+
+      // Filter out unimportant files and limit results
+      const filteredContents = data
+        .filter((item) => this.isRelevantFile(item.name))
+        .slice(0, 100); // Prevent token overflow
+
+      if (maxDepth > 0) {
+        // Recursively get important subdirectories
+        const subdirectories = filteredContents.filter(
+          (item) => item.type === "dir" && this.isImportantDirectory(item.name),
+        );
+
+        for (const dir of subdirectories.slice(0, 5)) {
+          // Limit subdirectory exploration
+          try {
+            const subContents = await this.getRepositoryContents(
+              owner,
+              repo,
+              dir.path,
+              maxDepth - 1,
+            );
+            for (const item of subContents) {
+              filteredContents.push(item);
+            }
+          } catch (error) {
+            // Continue if subdirectory is inaccessible
+            console.warn(`Could not access directory ${dir.path}: ${error}`);
+          }
+        }
+      }
+
+      return filteredContents;
+    } catch (error) {
+      throw new Error(`Failed to fetch repository contents: ${error}`);
+    }
+  }
+
+  /**
+   * Filter relevant files to reduce token usage
+   */
+  private isRelevantFile(filename: string): boolean {
+    const relevantExtensions = [
+      ".md",
+      ".txt",
+      ".json",
+      ".yml",
+      ".yaml",
+      ".toml",
+      ".ini",
+      ".cfg",
+      ".js",
+      ".ts",
+      ".py",
+      ".java",
+      ".go",
+      ".rs",
+      ".cpp",
+      ".c",
+      ".h",
+      ".html",
+      ".css",
+      ".scss",
+      ".vue",
+      ".jsx",
+      ".tsx",
+      ".dockerfile",
+      ".gitignore",
+      ".env.example",
+    ];
+
+    const relevantFiles = [
+      "README",
+      "LICENSE",
+      "package.json",
+      "requirements.txt",
+      "setup.py",
+      "Dockerfile",
+      "docker-compose",
+      "Makefile",
+      "cargo.toml",
+      "go.mod",
+      "pom.xml",
+      "build.gradle",
+      "composer.json",
+      "package-lock.json",
+      "yarn.lock",
+      ".env.example",
+      ".gitignore",
+      "tsconfig.json",
+    ];
+
+    const lowerFilename = filename.toLowerCase();
+
+    return (
+      relevantFiles.some((file) =>
+        lowerFilename.includes(file.toLowerCase()),
+      ) ||
+      relevantExtensions.some((ext) => lowerFilename.endsWith(ext)) ||
+      lowerFilename.startsWith(".")
+    );
+  }
+
+  /**
+   * Identify important directories for exploration
+   */
+  private isImportantDirectory(dirname: string): boolean {
+    const importantDirs = [
+      "src",
+      "lib",
+      "app",
+      "components",
+      "pages",
+      "api",
+      "utils",
+      "config",
+      "scripts",
+      "docs",
+      "examples",
+      "test",
+      "tests",
+      "__tests__",
+      "spec",
+      "public",
+      "assets",
+      "static",
+    ];
+
+    const lowerDirname = dirname.toLowerCase();
+    return (
+      importantDirs.includes(lowerDirname) &&
+      !lowerDirname.includes("node_modules") &&
+      !lowerDirname.includes(".git")
+    );
+  }
+
+  /**
+   * Analyze repository structure and detect tech stack
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private analyzeStructure(contents: any[]): RepositoryStructure {
+    const files = contents
+      .map((item) => item.name || item.path)
+      .filter(Boolean);
+
+    const rootFiles = files.filter((file) => !file.includes("/"));
+    const directories = [
+      ...new Set(
+        files
+          .filter((file) => file.includes("/"))
+          .map((file) => file.split("/")[0]),
+      ),
+    ];
+
+    // Categorize files
+    const packageFiles = files.filter((file) => this.isPackageFile(file));
+    const configFiles = files.filter((file) => this.isConfigFile(file));
+    const documentationFiles = files.filter((file) =>
+      this.isDocumentationFile(file),
+    );
+
+    // Detect tech stack and project type
+    const techStack = this.detectTechStack(files);
+    const projectType = this.detectProjectType(files, directories, techStack);
+
+    return {
+      rootFiles,
+      directories,
+      packageFiles,
+      configFiles,
+      documentationFiles,
+      techStack,
+      projectType,
+    };
+  }
+
+  private isPackageFile(filename: string): boolean {
+    const packageFiles = [
+      "package.json",
+      "package-lock.json",
+      "yarn.lock",
+      "requirements.txt",
+      "setup.py",
+      "pyproject.toml",
+      "cargo.toml",
+      "cargo.lock",
+      "go.mod",
+      "go.sum",
+      "pom.xml",
+      "build.gradle",
+      "composer.json",
+    ];
+    return packageFiles.some((file) => filename.toLowerCase().includes(file));
+  }
+
+  private isConfigFile(filename: string): boolean {
+    const configFiles = [
+      "tsconfig",
+      "webpack",
+      "babel",
+      "eslint",
+      "prettier",
+      "jest",
+      "cypress",
+      "dockerfile",
+      "docker-compose",
+      ".env",
+      "config",
+      "settings",
+    ];
+    return configFiles.some((config) =>
+      filename.toLowerCase().includes(config),
+    );
+  }
+
+  private isDocumentationFile(filename: string): boolean {
+    const lowerFilename = filename.toLowerCase();
+    return (
+      lowerFilename.includes("readme") ||
+      lowerFilename.includes("docs") ||
+      lowerFilename.includes("license") ||
+      lowerFilename.endsWith(".md") ||
+      lowerFilename.endsWith(".txt")
+    );
+  }
+
+  /**
+   * Advanced tech stack detection with confidence scoring
+   */
+  private detectTechStack(files: string[]): TechStackInfo {
+    const techStack: TechStackInfo = {
+      primary: "unknown",
+      frameworks: [],
+      tools: [],
+      databases: [],
+      deployment: [],
+    };
+
+    // Primary language detection
+    const languageIndicators = {
+      javascript: ["package.json", ".js", ".jsx"],
+      typescript: ["tsconfig.json", ".ts", ".tsx"],
+      python: ["requirements.txt", "setup.py", ".py"],
+      java: ["pom.xml", "build.gradle", ".java"],
+      go: ["go.mod", ".go"],
+      rust: ["cargo.toml", ".rs"],
+      cpp: [".cpp", ".c", ".h"],
+      csharp: [".cs", ".csproj"],
+      php: ["composer.json", ".php"],
+      ruby: ["gemfile", ".rb"],
+      swift: [".swift", "package.swift"],
+    };
+
+    let maxScore = 0;
+    for (const [lang, indicators] of Object.entries(languageIndicators)) {
+      const score = indicators.reduce(
+        (sum, indicator) =>
+          sum +
+          files.filter((f) => f.toLowerCase().includes(indicator.toLowerCase()))
+            .length,
+        0,
+      );
+      if (score > maxScore) {
+        maxScore = score;
+        techStack.primary = lang;
+      }
+    }
+
+    // Framework detection
+    const frameworkIndicators = {
+      react: ["react", "jsx", "tsx"],
+      vue: ["vue.config", ".vue"],
+      angular: ["angular.json", "@angular"],
+      svelte: ["svelte.config", ".svelte"],
+      nextjs: ["next.config", "pages/", "app/"],
+      nuxt: ["nuxt.config"],
+      express: ["express"],
+      django: ["django", "manage.py"],
+      fastapi: ["fastapi"],
+      flask: ["flask"],
+      spring: ["spring", "application.properties"],
+    };
+
+    for (const [framework, indicators] of Object.entries(frameworkIndicators)) {
+      if (
+        indicators.some((indicator) =>
+          files.some((file) =>
+            file.toLowerCase().includes(indicator.toLowerCase()),
+          ),
+        )
+      ) {
+        techStack.frameworks.push(framework);
+      }
+    }
+
+    // Tool detection
+    const toolIndicators = {
+      webpack: ["webpack.config"],
+      vite: ["vite.config"],
+      eslint: [".eslintrc", "eslint.config"],
+      prettier: [".prettierrc", "prettier.config"],
+      jest: ["jest.config", "jest.json"],
+      cypress: ["cypress.config", "cypress/"],
+      docker: ["dockerfile", "docker-compose"],
+      github_actions: [".github/workflows"],
+    };
+
+    for (const [tool, indicators] of Object.entries(toolIndicators)) {
+      if (
+        indicators.some((indicator) =>
+          files.some((file) =>
+            file.toLowerCase().includes(indicator.toLowerCase()),
+          ),
+        )
+      ) {
+        techStack.tools.push(tool);
+      }
+    }
+
+    return techStack;
+  }
+
+  /**
+   * Detect project type based on structure and tech stack
+   */
+  private detectProjectType(
+    files: string[],
+    directories: string[],
+    techStack: TechStackInfo,
+  ): ProjectType {
+    const hasDirectory = (names: string[]) =>
+      names.some((name) =>
+        directories.some((dir) =>
+          dir.toLowerCase().includes(name.toLowerCase()),
+        ),
+      );
+
+    const hasFile = (patterns: string[]) =>
+      patterns.some((pattern) =>
+        files.some((file) =>
+          file.toLowerCase().includes(pattern.toLowerCase()),
+        ),
+      );
+
+    // CLI tool detection
+    if (
+      hasFile(["bin/", "cli.", "command.", "main."]) ||
+      (techStack.frameworks.length === 0 &&
+        hasFile(["index.js", "main.py", "main.go"]))
+    ) {
+      return "cli-tool";
+    }
+
+    // Mobile app detection
+    if (
+      hasFile(["react-native", "flutter", "ionic", "expo"]) ||
+      hasDirectory(["ios", "android", "mobile"])
+    ) {
+      return "mobile-app";
+    }
+
+    // Desktop app detection
+    if (
+      hasFile(["electron", "tauri", "nwjs"]) ||
+      techStack.frameworks.some((f) => ["electron", "tauri"].includes(f))
+    ) {
+      return "desktop-app";
+    }
+
+    // Web frontend detection
+    if (
+      techStack.frameworks.some((f) =>
+        ["react", "vue", "angular", "svelte"].includes(f),
+      ) ||
+      hasDirectory(["components", "pages", "views"]) ||
+      hasFile(["index.html", "app.js", "main.js"])
+    ) {
+      return "web-frontend";
+    }
+
+    // Web backend detection
+    if (
+      techStack.frameworks.some((f) =>
+        ["express", "django", "flask", "spring"].includes(f),
+      ) ||
+      hasDirectory(["api", "routes", "controllers", "models"]) ||
+      hasFile(["server.", "app.py", "main.py"])
+    ) {
+      return "web-backend";
+    }
+
+    // Library detection
+    if (
+      hasFile([
+        "lib/",
+        "src/lib",
+        "dist/",
+        "build/",
+        "setup.py",
+        "package.json",
+      ]) &&
+      !hasDirectory(["pages", "components", "views"])
+    ) {
+      return "library";
+    }
+
+    // Data science detection
+    if (
+      hasFile(["jupyter", ".ipynb", "requirements.txt"]) &&
+      techStack.primary === "python"
+    ) {
+      return "data-science";
+    }
+
+    // DevOps detection
+    if (
+      hasFile([
+        "dockerfile",
+        "docker-compose",
+        "kubernetes",
+        "terraform",
+        ".yml",
+        ".yaml",
+      ]) ||
+      hasDirectory(["k8s", "kubernetes", "terraform", "ansible"])
+    ) {
+      return "devops";
+    }
+
+    // Documentation detection
+    if (
+      hasDirectory(["docs", "documentation"]) &&
+      files.filter((f) => f.endsWith(".md")).length > 3
+    ) {
+      return "documentation";
+    }
+
+    return "other";
+  }
+}
+
+// ============================================================================
+// SECTION PLANNER
+// ============================================================================
+
+export class SectionPlanner {
+  /**
+   * Plan README sections based on repository analysis
+   */
+  static planSections(
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): ReadmeSection[] {
+    const baseSections: ReadmeSection[] = [
+      {
+        id: "header",
+        title: "Project Header",
+        priority: "critical",
+        order: 1,
+        estimatedTokens: 200,
+        dependencies: [],
+      },
+      {
+        id: "description",
+        title: "Description",
+        priority: "critical",
+        order: 2,
+        estimatedTokens: 300,
+        dependencies: ["header"],
+      },
+      {
+        id: "features",
+        title: "Features",
+        priority: "high",
+        order: 3,
+        estimatedTokens: 400,
+        dependencies: ["description"],
+      },
+      {
+        id: "architecture",
+        title: "Technical Architecture",
+        priority: "medium",
+        order: 3.5,
+        estimatedTokens: 400,
+        dependencies: ["features"],
+      },
+      {
+        id: "structure",
+        title: "Directory Structure",
+        priority: "low",
+        order: 3.7,
+        estimatedTokens: 300,
+        dependencies: ["architecture"],
+      },
+      {
+        id: "installation",
+        title: "Installation",
+        priority: "critical",
+        order: 4,
+        estimatedTokens: 500,
+        dependencies: ["features"],
+      },
+      {
+        id: "usage",
+        title: "Usage",
+        priority: "high",
+        order: 5,
+        estimatedTokens: 600,
+        dependencies: ["installation"],
+      },
+      {
+        id: "license",
+        title: "License",
+        priority: "medium",
+        order: 10,
+        estimatedTokens: 100,
+        dependencies: [],
+      },
+    ];
+
+    // Add conditional sections based on project type and structure
+    const conditionalSections = this.getConditionalSections(
+      metadata,
+      structure,
+    );
+
+    const allSections = [...baseSections, ...conditionalSections];
+
+    // Sort by order and return
+    return allSections.sort((a, b) => a.order - b.order);
+  }
+
+  /**
+   * Get additional sections based on project characteristics
+   */
+  private static getConditionalSections(
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): ReadmeSection[] {
+    const sections: ReadmeSection[] = [];
+
+    // API Documentation for backend projects
+    if (
+      structure.projectType === "web-backend" ||
+      structure.directories.some((d) => d.includes("api"))
+    ) {
+      sections.push({
+        id: "api",
+        title: "API Documentation",
+        priority: "high",
+        order: 6,
+        estimatedTokens: 800,
+        dependencies: ["usage"],
+      });
+    }
+
+    // Configuration section for complex projects
+    if (structure.configFiles.length > 3) {
+      sections.push({
+        id: "configuration",
+        title: "Configuration",
+        priority: "medium",
+        order: 7,
+        estimatedTokens: 400,
+        dependencies: ["installation"],
+      });
+    }
+
+    // Development section for open-source projects
+    if (!metadata.isPrivate && metadata.forks > 0) {
+      sections.push({
+        id: "development",
+        title: "Development",
+        priority: "medium",
+        order: 8,
+        estimatedTokens: 500,
+        dependencies: ["usage"],
+      });
+    }
+
+    // Contributing section for popular projects
+    if (metadata.stars > 50 || metadata.forks > 10) {
+      sections.push({
+        id: "contributing",
+        title: "Contributing",
+        priority: "medium",
+        order: 9,
+        estimatedTokens: 300,
+        dependencies: [],
+      });
+    }
+
+    // Deployment section for web applications
+    if (
+      structure.projectType === "web-frontend" ||
+      structure.projectType === "web-backend"
+    ) {
+      sections.push({
+        id: "deployment",
+        title: "Deployment",
+        priority: "medium",
+        order: 6.5,
+        estimatedTokens: 400,
+        dependencies: ["usage"],
+      });
+    }
+
+    // Examples section for libraries
+    if (
+      structure.projectType === "library" ||
+      structure.directories.some((d) => d.includes("example"))
+    ) {
+      sections.push({
+        id: "examples",
+        title: "Examples",
+        priority: "high",
+        order: 5.5,
+        estimatedTokens: 600,
+        dependencies: ["usage"],
+      });
+    }
+
+    // Testing section for projects with test infrastructure
+    if (
+      structure.directories.some((d) => d.includes("test")) ||
+      structure.techStack.tools.some((t) =>
+        ["jest", "cypress", "pytest"].includes(t),
+      )
+    ) {
+      sections.push({
+        id: "testing",
+        title: "Testing",
+        priority: "low",
+        order: 8.5,
+        estimatedTokens: 300,
+        dependencies: ["development"],
+      });
+    }
+
+    return sections;
+  }
+
+  /**
+   * Optimize section order based on dependencies
+   */
+  static optimizeSectionOrder(sections: ReadmeSection[]): ReadmeSection[] {
+    // Implementation of topological sort for dependencies
+    const sorted: ReadmeSection[] = [];
+    const visited = new Set<string>();
+    const visiting = new Set<string>();
+
+    const visit = (section: ReadmeSection) => {
+      if (visiting.has(section.id)) {
+        throw new Error(
+          `Circular dependency detected involving section: ${section.id}`,
+        );
+      }
+      if (visited.has(section.id)) {
+        return;
+      }
+
+      visiting.add(section.id);
+
+      // Visit dependencies first
+      for (const depId of section.dependencies) {
+        const depSection = sections.find((s) => s.id === depId);
+        if (depSection) {
+          visit(depSection);
+        }
+      }
+
+      visiting.delete(section.id);
+      visited.add(section.id);
+      sorted.push(section);
+    };
+
+    // Sort by priority first, then by order
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    const sortedByPriority = [...sections].sort((a, b) => {
+      const priorityDiff =
+        priorityOrder[a.priority] - priorityOrder[b.priority];
+      return priorityDiff !== 0 ? priorityDiff : a.order - b.order;
+    });
+
+    for (const section of sortedByPriority) {
+      if (!visited.has(section.id)) {
+        visit(section);
+      }
+    }
+
+    return sorted;
+  }
+}
+
+// ============================================================================
+// SECTION GENERATOR WITH OPTIMIZED PROMPTS
+// ============================================================================
+
+export class SectionGenerator {
+  private genAI: GoogleGenerativeAI;
+  private config: GenerationConfig;
+
+  constructor(apiKey: string, config: Partial<GenerationConfig> = {}) {
+    if (!apiKey) {
+      throw new Error("Gemini API key is required for SectionGenerator");
+    }
+
+    this.genAI = new GoogleGenerativeAI(apiKey);
+    this.config = {
+      maxRetries: 3,
+      maxTokensPerSection: 800,
+      temperature: 0.7,
+      concurrentSections: 3,
+      enableContinuation: true,
+      ...config,
+    };
+
+    console.log("SectionGenerator initialized");
+
+    // Test API connection on initialization
+    this.testAPIConnection().catch((error) => {
+      console.error("API connection test failed:", error);
+    });
+  }
+
+  /**
+   * Test API connection to ensure it's working
+   */
+  private async testAPIConnection(): Promise<void> {
+    try {
+      console.log("Testing Gemini API connection...");
+      const model = this.genAI.getGenerativeModel({ model: "gemini-pro" });
+      const result = await model.generateContent(
+        "Hello, respond with 'API connection successful'",
+      );
+      const response = result.response.text();
+      console.log("API test response:", response.substring(0, 100));
+    } catch (error) {
+      console.error("API connection test failed:", error);
+    }
+  }
+
+  /**
+   * Generate a specific README section with optimized prompts
+   */
+  async generateSection(
+    sectionId: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+    context: Record<string, string> = {},
+  ): Promise<GenerationResult> {
+    const prompt = this.buildSectionPrompt(
+      sectionId,
+      metadata,
+      structure,
+      context,
+    );
+
+    for (let attempt = 1; attempt <= this.config.maxRetries; attempt++) {
+      try {
+        const result = await this.callAI(prompt, sectionId);
+
+        if (result.success && !result.truncated) {
+          return result;
+        }
+
+        // If truncated and continuation is enabled, try to complete
+        if (
+          result.truncated &&
+          this.config.enableContinuation &&
+          result.content
+        ) {
+          const continuationResult = await this.continueGeneration(
+            sectionId,
+            result.content,
+            metadata,
+            structure,
+          );
+          if (continuationResult.success) {
+            return {
+              success: true,
+              content: result.content + continuationResult.content,
+              tokensUsed:
+                (result.tokensUsed || 0) + (continuationResult.tokensUsed || 0),
+            };
+          }
+        }
+
+        console.warn(
+          `Section ${sectionId} generation attempt ${attempt} failed or truncated`,
+        );
+      } catch (error) {
+        console.error(
+          `Section ${sectionId} generation attempt ${attempt} error:`,
+          error,
+        );
+
+        if (attempt === this.config.maxRetries) {
+          return {
+            success: false,
+            error: `Failed to generate section after ${this.config.maxRetries} attempts: ${error}`,
+          };
+        }
+      }
+    }
+
+    return {
+      success: false,
+      error: `Failed to generate section ${sectionId} after ${this.config.maxRetries} attempts`,
+    };
+  }
+
+  /**
+   * Build optimized prompts for each section type
+   */
+  private buildSectionPrompt(
+    sectionId: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+    context: Record<string, string>,
+  ): string {
+    const baseContext = this.buildBaseContext(metadata, structure);
+    const contextInfo =
+      Object.keys(context).length > 0
+        ? `\nPrevious sections for reference:\n${Object.entries(context)
+            .map(([key, content]) => `${key}:\n${content.slice(0, 200)}...`)
+            .join("\n\n")}`
+        : "";
+
+    const sectionPrompts: Record<string, string> = {
+      header: `Generate a stunning, professional README header section for "${metadata.name}".
+
+Context: ${baseContext}${contextInfo}
+
+Create a header that includes:
+1. Centered title and tagline using HTML tags
+2. Professional badge collection (build status, license, PRs welcome, GitHub stars)
+3. Brief compelling description (2-3 sentences)
+
+Example format to follow:
+<p align="center">
+  <h1>${metadata.name}</h1>
+  <p align="center">Compelling one-line tagline that captures the project's essence</p>
+  <p align="center">
+    <img alt="Build Status" src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" />
+    <img alt="License" src="https://img.shields.io/badge/license-${metadata.license || "MIT"}-blue.svg?style=flat-square" />
+    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" />
+    <img alt="GitHub Stars" src="https://img.shields.io/github/stars/USER/REPO?style=flat-square&color=yellow" />
+  </p>
+</p>
+
+Requirements:
+- Use HTML for perfect alignment
+- Create an engaging tagline that explains what the project does
+- Include realistic badge URLs appropriate for ${structure.projectType} projects
+- Make it visually appealing and professional
+- Add a horizontal rule (---) after the header
+
+Return only the markdown/HTML content, no explanations.`,
+
+      description: `Generate a compelling strategic description section for "${metadata.name}".
+
+Context: ${baseContext}
+Project Type: ${structure.projectType}
+Technologies: ${structure.techStack.primary}, ${structure.techStack.frameworks.join(", ")}
+
+Create two main sections:
+
+## The Strategic "Why"
+> Start with a blockquote explaining the problem this project solves. What pain point does it address? Why does this project exist?
+
+Follow with 2-3 paragraphs that explain:
+- The core problem in the industry/domain
+- How this project solves it uniquely
+- The value it provides to users
+- Who the target audience is
+
+Make it engaging and professional. Focus on the business case and user benefits, not just technical features.
+
+Requirements:
+- Start with "## The Strategic \"Why\"" as the section header
+- Use blockquote (>) for the opening problem statement
+- Write in a professional, compelling tone
+- Avoid technical jargon - focus on benefits
+- 3-4 well-structured paragraphs total
+- No placeholder text - create realistic, specific content
+
+Return only the markdown content.`,
+
+      features: `Generate a comprehensive "Key Features" section for "${metadata.name}".
+
+Context: ${baseContext}
+Tech Stack: ${structure.techStack.primary}, ${structure.techStack.frameworks.join(", ")}
+Project Type: ${structure.projectType}
+
+Create a section called "## Key Features" with 6-8 compelling features that highlight:
+- Core functionality and capabilities
+- Technical advantages (performance, scalability, etc.)
+- User experience benefits
+- Integration capabilities
+- Developer experience improvements
+
+Format each feature as:
+*   🚀 **Feature Name**: Clear description explaining the benefit and impact
+
+Example format:
+## Key Features
+
+*   ✨ **AI-Powered Analysis**: Intelligently parses your repository's code, dependencies, and structure to understand its core purpose and components.
+*   🚀 **Instant Generation**: Get a complete, production-ready solution in mere seconds, drastically reducing development overhead.
+
+Requirements:
+- Use bullet points with meaningful emojis
+- Bold the feature name
+- Focus on user benefits, not just technical specs
+- Make each description 1-2 sentences
+- Use action-oriented language
+- Be specific about value propositions
+- No placeholder content - generate realistic features based on the project type
+
+Return only the markdown content.`,
+
+      installation: `Generate comprehensive installation and setup instructions for "${metadata.name}".
+
+Context: ${baseContext}
+Package Files: ${structure.packageFiles.join(", ")}
+Tech Stack: ${structure.techStack.primary}
+Project Type: ${structure.projectType}
+
+Create a detailed "## Operational Setup" section with:
+
+### Prerequisites
+List specific software requirements with versions
+
+### Installation
+Step-by-step installation process with multiple package managers if applicable
+
+### Environment Configuration  
+Explain any required environment variables or configuration files
+
+Format example:
+## Operational Setup
+
+Follow these steps to get ${metadata.name} up and running on your local machine.
+
+### Prerequisites
+
+Ensure you have the following installed:
+
+*   **Node.js**: LTS version (e.g., 18.x or 20.x)
+*   **npm** (Node Package Manager), **yarn**, or **pnpm** (preferred)
+
+### Installation
+
+1.  **Clone the repository**:
+    \`\`\`bash
+    git clone https://github.com/user/repo.git
+    cd repo
+    \`\`\`
+
+2.  **Install dependencies**:
+    [Include commands for different package managers]
+
+3.  **Start the development server**:
+    [Include appropriate start commands]
+
+### Environment Configuration
+[Explain .env setup if needed]
+
+Requirements:
+- Use numbered lists for steps
+- Include code blocks with proper syntax highlighting
+- Provide multiple installation options when relevant
+- Be specific about versions and requirements
+- Include verification steps
+- No placeholder content
+
+Return only the markdown content.`,
+
+      usage: `Generate usage examples for "${metadata.name}".
+
+Context: ${baseContext}
+Project Type: ${structure.projectType}
+
+Requirements:
+- Basic usage example
+- Code examples with syntax highlighting
+- Input/output examples if applicable
+- Common use cases
+- Links to more examples if needed
+
+Return only the markdown content.`,
+
+      api: `Generate API documentation section for "${metadata.name}".
+
+Context: ${baseContext}
+
+Requirements:
+- API overview
+- Authentication (if applicable)
+- Main endpoints or functions
+- Request/response examples
+- Error handling
+
+Return only the markdown content.`,
+
+      configuration: `Generate configuration section for "${metadata.name}".
+
+Context: ${baseContext}
+Config Files: ${structure.configFiles.join(", ")}
+
+Requirements:
+- Configuration options
+- Environment variables
+- Config file examples
+- Default values
+- Important settings
+
+Return only the markdown content.`,
+
+      development: `Generate development setup section for "${metadata.name}".
+
+Context: ${baseContext}
+
+Requirements:
+- Local development setup
+- Development dependencies
+- Build process
+- Development server
+- File structure overview
+
+Return only the markdown content.`,
+
+      contributing: `Generate comprehensive contributing guidelines for "${metadata.name}".
+
+Context: ${baseContext}
+Project Type: ${structure.projectType}
+
+Create a detailed section explaining how to contribute with:
+- Welcoming introduction
+- Step-by-step contribution process
+- Code standards and requirements
+- Reference to code of conduct
+
+Format as subsection of larger "Community & Governance" section:
+
+### Contributing
+
+We encourage and appreciate community contributions. If you're looking to contribute, please follow these guidelines:
+
+1.  **Fork** the repository.
+2.  **Create a new branch** for your feature or bug fix: \`git checkout -b feature/your-feature-name\` or \`bugfix/issue-description\`.
+3.  **Commit your changes** with clear and concise messages.
+4.  **Push your branch** to your forked repository.
+5.  **Open a Pull Request** against the \`main\` branch of this repository, describing your changes in detail.
+
+Please ensure your code adheres to the project's coding standards and includes appropriate tests. For more details, please refer to our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+Requirements:
+- Welcoming and encouraging tone
+- Clear step-by-step process
+- Mention testing and code standards
+- Professional formatting
+- No placeholder content
+
+Return only the markdown content.`,
+
+      deployment: `Generate deployment section for "${metadata.name}".
+
+Context: ${baseContext}
+Project Type: ${structure.projectType}
+
+Requirements:
+- Deployment options
+- Build process
+- Environment setup
+- Platform-specific instructions
+- Best practices
+
+Return only the markdown content.`,
+
+      examples: `Generate examples section for "${metadata.name}".
+
+Context: ${baseContext}
+
+Requirements:
+- Code examples
+- Use case scenarios
+- Working demos
+- Integration examples
+- Links to live examples
+
+Return only the markdown content.`,
+
+      testing: `Generate testing section for "${metadata.name}".
+
+Context: ${baseContext}
+Tools: ${structure.techStack.tools.join(", ")}
+
+Requirements:
+- How to run tests
+- Test types available
+- Coverage information
+- Writing tests
+- Testing best practices
+
+Return only the markdown content.`,
+
+      license: `Generate a professional license section for "${metadata.name}".
+
+Context: ${baseContext}
+License: ${metadata.license || "MIT License"}
+
+Create a comprehensive "## Community & Governance" section that includes:
+
+### Contributing subsection
+### License subsection with detailed explanation
+
+Format example:
+## Community & Governance
+
+We welcome contributions and feedback from the community to make ${metadata.name} even better!
+
+### Contributing
+
+We encourage and appreciate community contributions. If you're looking to contribute, please follow these guidelines:
+
+1.  **Fork** the repository.
+2.  **Create a new branch** for your feature or bug fix: \`git checkout -b feature/your-feature-name\`.
+3.  **Commit your changes** with clear and concise messages.
+4.  **Push your branch** to your forked repository.
+5.  **Open a Pull Request** against the \`main\` branch, describing your changes in detail.
+
+### License
+
+This project is licensed under the **${metadata.license || "MIT License"}**.
+
+[Include 2-3 sentences explaining what this license allows and its key terms]
+
+For the full text of the license, please see the [LICENSE](LICENSE) file in this repository.
+
+Requirements:
+- Professional, welcoming tone
+- Clear contribution process
+- Detailed license explanation
+- No placeholder content
+
+Return only the markdown content.`,
+
+      architecture: `Generate a comprehensive "Technical Architecture" section for "${metadata.name}".
+
+Context: ${baseContext}
+Tech Stack: ${structure.techStack.primary}, ${structure.techStack.frameworks.join(", ")}, ${structure.techStack.tools.join(", ")}
+Project Type: ${structure.projectType}
+
+Create a section that includes:
+1. Architecture overview paragraph
+2. Technology stack table
+3. Key benefits explanation
+
+Format example:
+## Technical Architecture
+
+${metadata.name} is built on a robust and modern tech stack designed for performance, scalability, and an excellent developer experience.
+
+| Technology    | Purpose                    | Key Benefit                                |
+| :------------ | :------------------------- | :----------------------------------------- |
+| **Technology1**   | Primary Purpose        | Main advantage or benefit                  |
+| **Technology2**| Secondary Purpose       | Performance/Developer experience benefit    |
+
+Requirements:
+- Start with compelling architecture description
+- Use a well-formatted table with technology, purpose, and benefit columns
+- Include 4-8 key technologies from the tech stack
+- Focus on business benefits, not just technical specs
+- Professional tone
+- No placeholder content - use actual technologies detected
+
+Return only the markdown content.`,
+
+      structure: `Generate a "Directory Structure" visualization for "${metadata.name}".
+
+Context: ${baseContext}
+Directories: ${structure.directories.join(", ")}
+Root Files: ${structure.rootFiles.join(", ")}
+Project Type: ${structure.projectType}
+
+Create a section with:
+1. Brief introduction
+2. Tree-style directory structure
+3. Explanations for key directories/files
+
+Format example:
+### Directory Structure
+
+\`\`\`
+.
+├── 📁 directory1                    # Purpose description
+├── 📁 directory2                    # Purpose description  
+├── 📄 important-file.json          # File description
+├── 📄 config-file.js               # Configuration file purpose
+└── 📄 README.md                    # This README file
+\`\`\`
+
+Requirements:
+- Use tree structure with appropriate Unicode characters
+- Add folder (📁) and file (📄) emojis
+- Include brief descriptions for each major item
+- Focus on the most important 8-12 items
+- Make descriptions helpful for new developers
+- Use actual directories and files detected in the repository
+
+Return only the markdown content.`,
+    };
+
+    return (
+      sectionPrompts[sectionId] ||
+      this.buildGenericSectionPrompt(sectionId, metadata, structure)
+    );
+  }
+
+  /**
+   * Build base context string to avoid repetition
+   */
+  private buildBaseContext(
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): string {
+    return `
+Repository: ${metadata.name}
+Description: ${metadata.description || "No description provided"}
+Language: ${metadata.language || "Multiple"}
+Stars: ${metadata.stars}
+Project Type: ${structure.projectType}
+Primary Tech: ${structure.techStack.primary}
+Frameworks: ${structure.techStack.frameworks.join(", ") || "None"}
+`.trim();
+  }
+
+  /**
+   * Generic section prompt for unknown sections
+   */
+  private buildGenericSectionPrompt(
+    sectionId: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): string {
+    return `Generate a "${sectionId}" section for the repository "${metadata.name}".
+
+Context: ${this.buildBaseContext(metadata, structure)}
+
+Requirements:
+- Professional markdown format
+- Clear and concise content
+- Relevant to the project type
+- Follow README best practices
+
+Return only the markdown content.`;
+  }
+
+  /**
+   * Continue generation for truncated content
+   */
+  private async continueGeneration(
+    sectionId: string,
+    partialContent: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): Promise<GenerationResult> {
+    const prompt = `Continue the following "${sectionId}" section for "${metadata.name}":
+
+${partialContent}
+
+Project Context: ${this.buildBaseContext(metadata, structure)}
+
+Continue from where it left off. Complete the section with proper markdown formatting.
+Return only the continuation content.`;
+
+    return this.callAI(prompt, `${sectionId}-continuation`);
+  }
+
+  /**
+   * Call AI model with proper error handling and token management
+   */
+  private async callAI(
+    prompt: string,
+    sectionId: string,
+  ): Promise<GenerationResult> {
+    try {
+      console.log(
+        `Calling AI for section ${sectionId} with prompt length: ${prompt.length}`,
+      );
+
+      // Try different model names in case gemini-1.5-pro is not available
+      const modelNames = [
+        "gemini-1.5-pro",
+        "gemini-1.5-pro-latest",
+        "gemini-pro",
+      ];
+      let lastError: Error | null = null;
+
+      for (const modelName of modelNames) {
+        try {
+          console.log(`Trying model: ${modelName} for section ${sectionId}`);
+
+          const model = this.genAI.getGenerativeModel({
+            model: modelName,
+            generationConfig: {
+              temperature: this.config.temperature,
+              topP: 0.95,
+              maxOutputTokens: this.config.maxTokensPerSection,
+            },
+          });
+
+          const result = await model.generateContent(prompt);
+          const response = result.response;
+          const content = response.text();
+
+          console.log(
+            `AI response for ${sectionId} received using ${modelName}, length: ${content.length}`,
+          );
+
+          // Check if response was truncated
+          const truncated = this.isResponseTruncated(content, sectionId);
+
+          return {
+            success: true,
+            content: content.trim(),
+            tokensUsed: this.estimateTokens(prompt + content),
+            truncated,
+          };
+        } catch (error) {
+          console.warn(
+            `Model ${modelName} failed for section ${sectionId}:`,
+            error,
+          );
+          lastError = error instanceof Error ? error : new Error(String(error));
+          continue; // Try next model
+        }
+      }
+
+      // If all models failed, throw the last error
+      if (lastError) {
+        throw lastError;
+      }
+
+      throw new Error("All model attempts failed");
+    } catch (error) {
+      console.error(`AI generation failed for section ${sectionId}:`, error);
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.error(`Error details:`, errorMessage);
+
+      return {
+        success: false,
+        error: `AI generation failed for ${sectionId}: ${errorMessage}`,
+      };
+    }
+  }
+
+  /**
+   * Detect if response was truncated
+   */
+  private isResponseTruncated(content: string, sectionId: string): boolean {
+    const truncationIndicators = [
+      "...",
+      "truncated",
+      "continued",
+      "[end of response]",
+    ];
+
+    const contentLower = content.toLowerCase();
+    const hasIndicators = truncationIndicators.some((indicator) =>
+      contentLower.includes(indicator),
+    );
+
+    // Check if content ends abruptly without proper markdown closure
+    const endsAbruptly =
+      !content.trim().endsWith(".") &&
+      !content.trim().endsWith("\n") &&
+      content.length > 100;
+
+    // Section-specific checks
+    const sectionChecks: Record<string, boolean> = {
+      installation: !content.includes("```") && content.length > 200,
+      usage: !content.includes("```") && content.length > 200,
+      api: !content.includes("```") && content.length > 300,
+    };
+
+    return hasIndicators || endsAbruptly || sectionChecks[sectionId] || false;
+  }
+
+  /**
+   * Estimate token usage (rough approximation)
+   */
+  private estimateTokens(text: string): number {
+    // Rough estimation: 1 token ≈ 4 characters for English text
+    return Math.ceil(text.length / 4);
+  }
+}
+
+// ============================================================================
+// README ASSEMBLER WITH RETRY LOGIC
+// ============================================================================
+
+export class ReadmeAssembler {
+  private sectionGenerator: SectionGenerator;
+  private config: GenerationConfig;
+
+  constructor(
+    sectionGenerator: SectionGenerator,
+    config: Partial<GenerationConfig> = {},
+  ) {
+    this.sectionGenerator = sectionGenerator;
+    this.config = {
+      maxRetries: 3,
+      maxTokensPerSection: 800,
+      temperature: 0.7,
+      concurrentSections: 3,
+      enableContinuation: true,
+      ...config,
+    };
+  }
+
+  /**
+   * Generate complete README with retry logic and section management
+   */
+  async generateCompleteReadme(
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+    customSections?: ReadmeSection[],
+  ): Promise<{
+    success: boolean;
+    readme?: string;
+    sectionsGenerated: number;
+    sectionsTotal: number;
+    errors: string[];
+    tokensUsed: number;
+  }> {
+    // Plan sections
+    const sections =
+      customSections || SectionPlanner.planSections(metadata, structure);
+    const optimizedSections = SectionPlanner.optimizeSectionOrder(sections);
+
+    const results: Record<string, GenerationResult> = {};
+    const errors: string[] = [];
+    let totalTokens = 0;
+
+    // Generate sections with controlled concurrency
+    await this.generateSectionsInBatches(
+      optimizedSections,
+      metadata,
+      structure,
+      results,
+      errors,
+    );
+
+    // Calculate tokens used
+    totalTokens = Object.values(results).reduce(
+      (sum, result) => sum + (result.tokensUsed || 0),
+      0,
+    );
+
+    // Assemble final README
+    const readme = this.assembleReadme(
+      optimizedSections,
+      results,
+      metadata,
+      structure,
+    );
+    const successfulSections = Object.values(results).filter(
+      (r) => r.success,
+    ).length;
+
+    return {
+      success: successfulSections > 0,
+      readme,
+      sectionsGenerated: successfulSections,
+      sectionsTotal: optimizedSections.length,
+      errors,
+      tokensUsed: totalTokens,
+    };
+  }
+
+  /**
+   * Generate sections in controlled batches to manage API limits
+   */
+  private async generateSectionsInBatches(
+    sections: ReadmeSection[],
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+    results: Record<string, GenerationResult>,
+    errors: string[],
+  ): Promise<void> {
+    const batches = this.createSectionBatches(sections);
+
+    for (let batchIndex = 0; batchIndex < batches.length; batchIndex++) {
+      const batch = batches[batchIndex];
+      console.log(
+        `Generating batch ${batchIndex + 1}/${batches.length} with sections: ${batch.map((s) => s.id).join(", ")}`,
+      );
+
+      // Generate sections in current batch concurrently
+      const batchPromises = batch.map(async (section) => {
+        const context = this.buildSectionContext(section, results);
+        const result = await this.sectionGenerator.generateSection(
+          section.id,
+          metadata,
+          structure,
+          context,
+        );
+
+        results[section.id] = result;
+
+        if (!result.success) {
+          errors.push(`Failed to generate ${section.id}: ${result.error}`);
+        }
+
+        return result;
+      });
+
+      await Promise.all(batchPromises);
+
+      // Add delay between batches to respect API limits
+      if (batchIndex < batches.length - 1) {
+        await this.delay(1000); // 1 second delay
+      }
+    }
+
+    // Retry failed critical sections
+    await this.retryFailedCriticalSections(
+      sections,
+      metadata,
+      structure,
+      results,
+      errors,
+    );
+  }
+
+  /**
+   * Create batches respecting dependencies and concurrency limits
+   */
+  private createSectionBatches(sections: ReadmeSection[]): ReadmeSection[][] {
+    const batches: ReadmeSection[][] = [];
+    const processed = new Set<string>();
+    const remaining = [...sections];
+
+    while (remaining.length > 0) {
+      const currentBatch: ReadmeSection[] = [];
+      const toRemove: number[] = [];
+
+      for (
+        let i = 0;
+        i < remaining.length &&
+        currentBatch.length < this.config.concurrentSections;
+        i++
+      ) {
+        const section = remaining[i];
+
+        // Check if dependencies are satisfied
+        const dependenciesSatisfied = section.dependencies.every((depId) =>
+          processed.has(depId),
+        );
+
+        if (dependenciesSatisfied) {
+          currentBatch.push(section);
+          processed.add(section.id);
+          toRemove.push(i);
+        }
+      }
+
+      // Remove processed sections (in reverse order to maintain indices)
+      for (let i = toRemove.length - 1; i >= 0; i--) {
+        remaining.splice(toRemove[i], 1);
+      }
+
+      if (currentBatch.length > 0) {
+        batches.push(currentBatch);
+      } else if (remaining.length > 0) {
+        // If no sections can be processed, there might be circular dependencies
+        // Add the first remaining section to break the cycle
+        const section = remaining.shift()!;
+        processed.add(section.id);
+        batches.push([section]);
+      }
+    }
+
+    return batches;
+  }
+
+  /**
+   * Build context for section generation based on previously generated sections
+   */
+  private buildSectionContext(
+    section: ReadmeSection,
+    results: Record<string, GenerationResult>,
+  ): Record<string, string> {
+    const context: Record<string, string> = {};
+
+    for (const depId of section.dependencies) {
+      const depResult = results[depId];
+      if (depResult && depResult.success && depResult.content) {
+        context[depId] = depResult.content;
+      }
+    }
+
+    return context;
+  }
+
+  /**
+   * Retry failed critical sections with simplified prompts
+   */
+  private async retryFailedCriticalSections(
+    sections: ReadmeSection[],
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+    results: Record<string, GenerationResult>,
+    errors: string[],
+  ): Promise<void> {
+    const failedCriticalSections = sections.filter(
+      (section) =>
+        section.priority === "critical" &&
+        (!results[section.id] || !results[section.id].success),
+    );
+
+    if (failedCriticalSections.length === 0) {
+      return;
+    }
+
+    console.log(
+      `Retrying ${failedCriticalSections.length} failed critical sections...`,
+    );
+
+    for (const section of failedCriticalSections) {
+      try {
+        // Use simplified prompt for retry
+        const simplifiedResult = await this.generateSimplifiedSection(
+          section.id,
+          metadata,
+          structure,
+        );
+
+        if (simplifiedResult.success) {
+          results[section.id] = simplifiedResult;
+          // Remove error from errors array
+          const errorIndex = errors.findIndex((error) =>
+            error.includes(section.id),
+          );
+          if (errorIndex !== -1) {
+            errors.splice(errorIndex, 1);
+          }
+        }
+      } catch (error) {
+        console.error(`Failed to retry section ${section.id}:`, error);
+      }
+    }
+  }
+
+  /**
+   * Generate simplified version of section for fallback
+   */
+  private async generateSimplifiedSection(
+    sectionId: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): Promise<GenerationResult> {
+    const simplifiedPrompts: Record<string, string> = {
+      header: `<p align="center">
+  <h1>${metadata.name}</h1>
+  <p align="center">${metadata.description || `A ${structure.techStack.primary} application for modern development.`}</p>
+  <p align="center">
+    <img alt="Build Status" src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" />
+    <img alt="License" src="https://img.shields.io/badge/license-${encodeURIComponent(metadata.license || "MIT")}-blue.svg?style=flat-square" />
+    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" />
+  </p>
+</p>
+
+---`,
+
+      description: `## The Strategic "Why"
+
+> ${metadata.name} addresses the need for a robust ${structure.techStack.primary} solution that provides developers with essential functionality and a great user experience.
+
+This project leverages ${structure.techStack.primary}${structure.techStack.frameworks.length > 0 ? ` with ${structure.techStack.frameworks.join(", ")}` : ""} to deliver a comprehensive solution. Built with modern development practices in mind, it provides a solid foundation for ${structure.projectType === "library" ? "integration into larger projects" : "application development"}.
+
+The project focuses on simplicity, performance, and maintainability, making it an excellent choice for developers looking for ${structure.projectType === "library" ? "reliable dependencies" : "a well-structured application foundation"}.`,
+
+      features: `## Key Features
+
+*   ⚡ **High Performance**: Built with ${structure.techStack.primary} for optimal speed and efficiency
+*   🛡️ **Reliable Architecture**: Follows best practices for ${structure.projectType} development
+*   📦 **Easy Integration**: Simple setup and configuration process
+*   🔧 **Developer Friendly**: Clean API and comprehensive documentation
+*   🚀 **Production Ready**: Thoroughly tested and production-grade code
+*   🎯 **Modern Standards**: Uses latest ${structure.techStack.primary} features and patterns`,
+
+      architecture: `## Technical Architecture
+
+${metadata.name} is built using modern ${structure.techStack.primary} architecture designed for scalability and maintainability.
+
+| Technology | Purpose | Key Benefit |
+|:-----------|:--------|:------------|
+| **${structure.techStack.primary}** | Core Runtime | High performance and reliability |
+${structure.techStack.frameworks.map((fw) => `| **${fw}** | Framework | Enhanced developer experience |`).join("\n")}
+${
+  structure.techStack.tools.length > 0
+    ? structure.techStack.tools
+        .slice(0, 3)
+        .map((tool) => `| **${tool}** | Development Tool | Improved workflow |`)
+        .join("\n")
+    : ""
+}`,
+
+      installation: `## Installation & Setup
+
+### Prerequisites
+
+Ensure you have the following installed:
+- **${structure.techStack.primary}**: Latest LTS version recommended
+${structure.packageFiles.includes("package.json") ? "- **npm**, **yarn**, or **pnpm**: Package manager" : ""}
+
+### Quick Start
+
+1. **Clone the repository**:
+   \`\`\`bash
+   git clone https://github.com/user/${metadata.name}.git
+   cd ${metadata.name}
+   \`\`\`
+
+${
+  structure.packageFiles.includes("package.json")
+    ? `2. **Install dependencies**:
+   \`\`\`bash
+   npm install
+   # or
+   yarn install
+   # or
+   pnpm install
+   \`\`\`
+
+3. **Start development**:
+   \`\`\`bash
+   npm run dev
+   # or
+   yarn dev
+   \`\`\``
+    : `2. **Build the project**:
+   \`\`\`bash
+   make build
+   # or follow project-specific build instructions
+   \`\`\``
+}`,
+
+      usage: `## Usage
+
+### Basic Example
+
+\`\`\`${structure.techStack.primary.toLowerCase()}
+${
+  structure.techStack.primary === "JavaScript" ||
+  structure.techStack.primary === "TypeScript"
+    ? `import { ${metadata.name} } from './${metadata.name.toLowerCase()}';
+
+// Basic usage
+const result = new ${metadata.name}();
+console.log(result);`
+    : structure.techStack.primary === "Python"
+      ? `from ${metadata.name.toLowerCase()} import main
+
+# Basic usage
+result = main()
+print(result)`
+      : `// Basic usage example
+// See documentation for detailed API reference`
+}
+\`\`\`
+
+### Advanced Configuration
+
+See the documentation for advanced configuration options and detailed API reference.`,
+
+      contributing: `## Community & Governance
+
+We welcome contributions from the community to make ${metadata.name} even better!
+
+### Contributing
+
+1. **Fork** the repository
+2. **Create a feature branch**: \`git checkout -b feature/amazing-feature\`
+3. **Commit your changes**: \`git commit -m 'Add amazing feature'\`
+4. **Push to the branch**: \`git push origin feature/amazing-feature\`
+5. **Open a Pull Request**
+
+Please ensure your code follows the project's coding standards and includes appropriate tests.`,
+
+      license: `## License
+
+This project is licensed under the **${metadata.license || "MIT License"}**.
+
+${
+  metadata.license === "MIT" || !metadata.license
+    ? `The MIT License grants broad permissions to use, copy, modify, merge, publish, distribute, sublicense, and sell the software, with minimal restrictions. The main requirements are to include the original copyright notice and license in any substantial portions of the software.`
+    : `Please see the license terms for details about permitted use, modification, and distribution of this software.`
+}
+
+For the full license text, see the [LICENSE](LICENSE) file in this repository.`,
+    };
+
+    const content =
+      simplifiedPrompts[sectionId] ||
+      `## ${sectionId.charAt(0).toUpperCase() + sectionId.slice(1)}\n\nTODO: Add ${sectionId} information.`;
+
+    return {
+      success: true,
+      content,
+      tokensUsed: this.estimateTokens(content),
+    };
+  }
+
+  /**
+   * Assemble final README from section results with enhanced fallbacks
+   */
+  private assembleReadme(
+    sections: ReadmeSection[],
+    results: Record<string, GenerationResult>,
+    metadata?: RepositoryMetadata,
+    structure?: RepositoryStructure,
+  ): string {
+    const readmeParts: string[] = [];
+
+    for (const section of sections) {
+      const result = results[section.id];
+
+      if (result && result.success && result.content) {
+        readmeParts.push(result.content);
+        readmeParts.push(""); // Add empty line between sections
+      } else {
+        // Use enhanced fallback content instead of placeholder
+        console.warn(
+          `Section ${section.id} failed, using enhanced fallback content`,
+        );
+
+        if (metadata && structure) {
+          try {
+            // Generate professional fallback content
+            const fallbackContent = this.generateFallbackContent(
+              section.id,
+              metadata,
+              structure,
+            );
+            readmeParts.push(fallbackContent);
+            readmeParts.push(""); // Add empty line between sections
+          } catch (error) {
+            console.error(
+              `Failed to generate fallback for ${section.id}:`,
+              error,
+            );
+            // Last resort: basic section header
+            readmeParts.push(`## ${section.title}`);
+            readmeParts.push(
+              "*This section could not be generated automatically.*",
+            );
+            readmeParts.push("");
+          }
+        } else {
+          // Fallback when metadata/structure not available
+          readmeParts.push(`## ${section.title}`);
+          readmeParts.push(
+            "*This section could not be generated automatically.*",
+          );
+          readmeParts.push("");
+        }
+      }
+    }
+
+    return readmeParts.join("\n").trim();
+  }
+
+  /**
+   * Generate professional fallback content for failed sections
+   */
+  /**
+   * Generate professional fallback content for failed sections
+   */
+  private generateFallbackContent(
+    sectionId: string,
+    metadata: RepositoryMetadata,
+    structure: RepositoryStructure,
+  ): string {
+    const fallbackPrompts: Record<string, string> = {
+      header: `<p align="center">
+  <h1>${metadata.name}</h1>
+  <p align="center">${metadata.description || `A ${structure.techStack.primary} application for modern development.`}</p>
+  <p align="center">
+    <img alt="Build Status" src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" />
+    <img alt="License" src="https://img.shields.io/badge/license-${encodeURIComponent(metadata.license || "MIT")}-blue.svg?style=flat-square" />
+    <img alt="PRs Welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" />
+  </p>
+</p>
+
+---`,
+
+      description: `## The Strategic "Why"
+
+> ${metadata.name} addresses the need for a robust ${structure.techStack.primary} solution that provides developers with essential functionality and a great user experience.
+
+This project leverages ${structure.techStack.primary}${structure.techStack.frameworks.length > 0 ? ` with ${structure.techStack.frameworks.join(", ")}` : ""} to deliver a comprehensive solution. Built with modern development practices in mind, it provides a solid foundation for ${structure.projectType === "library" ? "integration into larger projects" : "application development"}.
+
+The project focuses on simplicity, performance, and maintainability, making it an excellent choice for developers looking for ${structure.projectType === "library" ? "reliable dependencies" : "a well-structured application foundation"}.`,
+
+      features: `## Key Features
+
+*   ⚡ **High Performance**: Built with ${structure.techStack.primary} for optimal speed and efficiency
+*   🛡️ **Reliable Architecture**: Follows best practices for ${structure.projectType} development
+*   📦 **Easy Integration**: Simple setup and configuration process
+*   🔧 **Developer Friendly**: Clean API and comprehensive documentation
+*   🚀 **Production Ready**: Thoroughly tested and production-grade code
+*   🎯 **Modern Standards**: Uses latest ${structure.techStack.primary} features and patterns`,
+
+      architecture: `## Technical Architecture
+
+${metadata.name} is built using modern ${structure.techStack.primary} architecture designed for scalability and maintainability.
+
+| Technology | Purpose | Key Benefit |
+|:-----------|:--------|:------------|
+| **${structure.techStack.primary}** | Core Runtime | High performance and reliability |
+${structure.techStack.frameworks.map((fw) => `| **${fw}** | Framework | Enhanced developer experience |`).join("\n")}
+${
+  structure.techStack.tools.length > 0
+    ? structure.techStack.tools
+        .slice(0, 3)
+        .map((tool) => `| **${tool}** | Development Tool | Improved workflow |`)
+        .join("\n")
+    : ""
+}`,
+
+      structure: `### Directory Structure
+
+\`\`\`
+.
+${structure.directories
+  .slice(0, 8)
+  .map(
+    (dir) =>
+      `├── 📁 ${dir}/                     # ${this.getDirectoryDescription(dir)}`,
+  )
+  .join("\n")}
+${structure.rootFiles
+  .slice(0, 5)
+  .map(
+    (file) =>
+      `├── 📄 ${file}                    # ${this.getFileDescription(file)}`,
+  )
+  .join("\n")}
+└── 📄 README.md                  # This README file
+\`\`\``,
+
+      installation: `## Installation & Setup
+
+### Prerequisites
+
+Ensure you have the following installed:
+- **${structure.techStack.primary}**: Latest LTS version recommended
+${structure.packageFiles.includes("package.json") ? "- **npm**, **yarn**, or **pnpm**: Package manager" : ""}
+
+### Quick Start
+
+1. **Clone the repository**:
+   \`\`\`bash
+   git clone https://github.com/user/${metadata.name}.git
+   cd ${metadata.name}
+   \`\`\`
+
+${
+  structure.packageFiles.includes("package.json")
+    ? `2. **Install dependencies**:
+   \`\`\`bash
+   npm install
+   # or
+   yarn install
+   # or
+   pnpm install
+   \`\`\`
+
+3. **Start development**:
+   \`\`\`bash
+   npm run dev
+   # or
+   yarn dev
+   \`\`\``
+    : `2. **Build the project**:
+   \`\`\`bash
+   make build
+   # or follow project-specific build instructions
+   \`\`\``
+}`,
+
+      usage: `## Usage
+
+### Basic Example
+
+\`\`\`${structure.techStack.primary.toLowerCase()}
+${this.generateUsageExample(structure.techStack.primary, metadata.name)}
+\`\`\`
+
+### Advanced Configuration
+
+See the documentation for advanced configuration options and detailed API reference.`,
+
+      contributing: `## Community & Governance
+
+We welcome contributions from the community to make ${metadata.name} even better!
+
+### Contributing
+
+1. **Fork** the repository
+2. **Create a feature branch**: \`git checkout -b feature/amazing-feature\`
+3. **Commit your changes**: \`git commit -m 'Add amazing feature'\`
+4. **Push to the branch**: \`git push origin feature/amazing-feature\`
+5. **Open a Pull Request**
+
+Please ensure your code follows the project's coding standards and includes appropriate tests.`,
+
+      license: `## License
+
+This project is licensed under the **${metadata.license || "MIT License"}**.
+
+${
+  metadata.license === "MIT" || !metadata.license
+    ? `The MIT License grants broad permissions to use, copy, modify, merge, publish, distribute, sublicense, and sell the software, with minimal restrictions. The main requirements are to include the original copyright notice and license in any substantial portions of the software.`
+    : `Please see the license terms for details about permitted use, modification, and distribution of this software.`
+}
+
+For the full license text, see the [LICENSE](LICENSE) file in this repository.`,
+    };
+
+    return (
+      fallbackPrompts[sectionId] ||
+      `## ${sectionId.charAt(0).toUpperCase() + sectionId.slice(1)}
+
+This section contains ${sectionId} information for ${metadata.name}.
+
+*Content generated using fallback template - for enhanced content, please ensure AI API is properly configured.*`
+    );
+  }
+
+  /**
+   * Get description for directory based on common patterns
+   */
+  private getDirectoryDescription(dir: string): string {
+    const descriptions: Record<string, string> = {
+      src: "Main application source code",
+      lib: "Library and utility functions",
+      components: "Reusable UI components",
+      pages: "Application pages and routes",
+      api: "API routes and endpoints",
+      utils: "Utility functions and helpers",
+      styles: "Styling and CSS files",
+      public: "Static assets and files",
+      docs: "Project documentation",
+      tests: "Test files and test utilities",
+      test: "Test files and test utilities",
+      assets: "Static assets and resources",
+      config: "Configuration files",
+      scripts: "Build and utility scripts",
+    };
+
+    return descriptions[dir.toLowerCase()] || `${dir} related files`;
+  }
+
+  /**
+   * Get description for file based on common patterns
+   */
+  private getFileDescription(file: string): string {
+    const descriptions: Record<string, string> = {
+      "package.json": "Project metadata and dependencies",
+      "tsconfig.json": "TypeScript configuration",
+      "next.config.js": "Next.js configuration",
+      "tailwind.config.js": "Tailwind CSS configuration",
+      "eslint.config.js": "ESLint configuration",
+      ".gitignore": "Git ignore patterns",
+      LICENSE: "Project license information",
+      "README.md": "Project documentation",
+      Dockerfile: "Docker container configuration",
+      "docker-compose.yml": "Docker compose configuration",
+    };
+
+    return descriptions[file] || `${file} configuration`;
+  }
+
+  /**
+   * Generate usage example based on tech stack
+   */
+  private generateUsageExample(techStack: string, projectName: string): string {
+    switch (techStack.toLowerCase()) {
+      case "javascript":
+      case "typescript":
+        return `import { ${projectName} } from './${projectName.toLowerCase()}';
+
+// Basic usage
+const result = new ${projectName}();
+console.log(result);`;
+
+      case "python":
+        return `from ${projectName.toLowerCase()} import main
+
+# Basic usage
+result = main()
+print(result)`;
+
+      case "java":
+        return `// Basic usage
+${projectName} app = new ${projectName}();
+app.run();`;
+
+      case "go":
+        return `package main
+
+import "./${projectName.toLowerCase()}"
+
+func main() {
+    // Basic usage
+    ${projectName.toLowerCase()}.Run()
+}`;
+
+      default:
+        return `// Basic usage example
+// See documentation for detailed API reference`;
+    }
+  }
+
+  /**
+   * Utility function to add delays
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Estimate token usage
+   */
+  private estimateTokens(text: string): number {
+    return Math.ceil(text.length / 4);
+  }
+}
+
+// ============================================================================
+// MAIN MULTI-STEP README GENERATOR
+// ============================================================================
+
+export class MultiStepReadmeGenerator {
+  private analyzer: RepositoryAnalyzer;
+  private sectionGenerator: SectionGenerator;
+  private assembler: ReadmeAssembler;
+
+  constructor(
+    geminiApiKey: string,
+    githubToken?: string,
+    config: Partial<GenerationConfig> = {},
+  ) {
+    this.analyzer = new RepositoryAnalyzer(githubToken);
+    this.sectionGenerator = new SectionGenerator(geminiApiKey, config);
+    this.assembler = new ReadmeAssembler(this.sectionGenerator, config);
+  }
+
+  /**
+   * Main function to generate complete README
+   */
+  async generateReadme(githubUrl: string): Promise<{
+    success: boolean;
+    readme?: string;
+    metadata?: RepositoryMetadata;
+    structure?: RepositoryStructure;
+    sections?: ReadmeSection[];
+    stats: {
+      sectionsGenerated: number;
+      sectionsTotal: number;
+      tokensUsed: number;
+      timeElapsed: number;
+    };
+    errors: string[];
+  }> {
+    const startTime = Date.now();
+
+    try {
+      // Extract owner and repo from URL
+      const { owner, repo } = this.parseGithubUrl(githubUrl);
+
+      // Step 1: Analyze repository
+      console.log("Step 1: Analyzing repository...");
+      const { metadata, structure } = await this.analyzer.analyzeRepository(
+        owner,
+        repo,
+      );
+
+      // Step 2: Plan sections
+      console.log("Step 2: Planning README sections...");
+      const sections = SectionPlanner.planSections(metadata, structure);
+
+      // Step 3: Generate README
+      console.log("Step 3: Generating README sections...");
+      const result = await this.assembler.generateCompleteReadme(
+        metadata,
+        structure,
+        sections,
+      );
+
+      const endTime = Date.now();
+
+      return {
+        success: result.success,
+        readme: result.readme,
+        metadata,
+        structure,
+        sections,
+        stats: {
+          sectionsGenerated: result.sectionsGenerated,
+          sectionsTotal: result.sectionsTotal,
+          tokensUsed: result.tokensUsed,
+          timeElapsed: endTime - startTime,
+        },
+        errors: result.errors,
+      };
+    } catch (error) {
+      const endTime = Date.now();
+
+      return {
+        success: false,
+        stats: {
+          sectionsGenerated: 0,
+          sectionsTotal: 0,
+          tokensUsed: 0,
+          timeElapsed: endTime - startTime,
+        },
+        errors: [`Generation failed: ${error}`],
+      };
+    }
+  }
+
+  /**
+   * Parse GitHub URL to extract owner and repository name
+   */
+  private parseGithubUrl(url: string): { owner: string; repo: string } {
+    const match = url.match(/github\.com\/([^\/]+)\/([^\/]+)/);
+
+    if (!match) {
+      throw new Error("Invalid GitHub URL format");
+    }
+
+    return {
+      owner: match[1],
+      repo: match[2].replace(/\.git$/, ""), // Remove .git suffix if present
+    };
+  }
+}
+
+// ============================================================================
+// INTEGRATION HELPER FOR NEXT.JS API ROUTES
+// ============================================================================
+
+export async function handleReadmeGeneration(
+  request: Request,
+): Promise<Response> {
+  try {
+    const body = await request.json();
+    const { githubUrl } = body;
+
+    if (!githubUrl) {
+      return Response.json(
+        { error: "GitHub URL is required" },
+        { status: 400 },
+      );
+    }
+
+    // Initialize generator with environment variables
+    const generator = new MultiStepReadmeGenerator(
+      process.env.GEMINI_API_KEY!,
+      process.env.GITHUB_TOKEN, // Optional
+      {
+        maxRetries: 3,
+        maxTokensPerSection: 800,
+        temperature: 0.7,
+        concurrentSections: 3,
+        enableContinuation: true,
+      },
+    );
+
+    const result = await generator.generateReadme(githubUrl);
+
+    if (!result.success) {
+      return Response.json(
+        {
+          error: "Failed to generate README",
+          details: result.errors,
+        },
+        { status: 500 },
+      );
+    }
+
+    return Response.json({
+      success: true,
+      readme: result.readme,
+      stats: result.stats,
+      metadata: {
+        name: result.metadata?.name,
+        description: result.metadata?.description,
+        language: result.metadata?.language,
+        stars: result.metadata?.stars,
+      },
+    });
+  } catch (error) {
+    return Response.json(
+      { error: `Internal server error: ${error}` },
+      { status: 500 },
+    );
+  }
+}
diff --git a/src/lib/octokit.ts b/src/lib/octokit.ts
index fec753a..91c00f4 100644
--- a/src/lib/octokit.ts
+++ b/src/lib/octokit.ts
@@ -1,58 +1,113 @@
 import { Octokit } from "octokit";
 
-let _octokit: Octokit | null = null;
+type RepoAccessErrorCode =
+  | "AUTH_REQUIRED"
+  | "NOT_FOUND"
+  | "FORBIDDEN"
+  | "UNKNOWN";
 
-export function getOctokit(): Octokit {
-  if (_octokit) return _octokit;
-
-  const auth = process.env.GITHUB_TOKEN;
+export class RepoAccessError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code: RepoAccessErrorCode,
+  ) {
+    super(message);
+    this.name = "RepoAccessError";
+  }
+}
 
-  _octokit = new Octokit({
-    auth: auth || undefined,
+function createOctokit(accessToken?: string): Octokit {
+  return new Octokit({
+    auth: accessToken || undefined,
+    request: {
+      headers: {
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    },
   });
+}
+
+function toRepoAccessError(
+  error: unknown,
+  hasUserAccessToken: boolean,
+): RepoAccessError {
+  const status =
+    typeof error === "object" &&
+    error !== null &&
+    "status" in error &&
+    typeof error.status === "number"
+      ? error.status
+      : 500;
+
+  if (status === 401) {
+    return new RepoAccessError(
+      "Access token expired or invalid. Please re-authenticate with GitHub.",
+      401,
+      "AUTH_REQUIRED",
+    );
+  }
+
+  if ((status === 403 || status === 404) && !hasUserAccessToken) {
+    return new RepoAccessError(
+      "Repository not accessible. It may be private or unavailable. Log in with GitHub if you need access to a private repository.",
+      401,
+      "AUTH_REQUIRED",
+    );
+  }
+
+  if (status === 404) {
+    return new RepoAccessError(
+      "Repository not found or you do not have access to it.",
+      404,
+      "NOT_FOUND",
+    );
+  }
+
+  if (status === 403) {
+    return new RepoAccessError(
+      "GitHub denied access to this repository.",
+      403,
+      "FORBIDDEN",
+    );
+  }
 
-  return _octokit;
+  const message =
+    error instanceof Error ? error.message : "Could not fetch repository data";
+
+  return new RepoAccessError(message, status, "UNKNOWN");
 }
 
-/**
- * Fetches repository metadata (stars, description, language)
- */
-export async function getRepoData(owner: string, repo: string) {
-  const client = getOctokit();
+export async function getRepoSnapshot(
+  owner: string,
+  repo: string,
+  accessToken?: string,
+) {
+  const client = createOctokit(accessToken);
 
   try {
-    const { data } = await client.rest.repos.get({
+    const { data: repoInfo } = await client.rest.repos.get({
       owner,
       repo,
     });
-    return data;
-  } catch (error: unknown) {
-    const message =
-      error instanceof Error ? error.message : "An unknown error occurred";
-    console.error("Error fetching GitHub repo metadata:", message);
-    return null;
-  }
-}
-
-/**
- * NEW: Fetches the root contents to help Gemini build the File Structure
- */
-export async function getRepoContents(owner: string, repo: string) {
-  const client = getOctokit();
 
-  try {
-    const { data } = await client.rest.repos.getContent({
+    const { data: repoTree } = await client.rest.git.getTree({
       owner,
       repo,
-      path: "", // Root directory
+      tree_sha: repoInfo.default_branch,
     });
 
-    // Return the array of files/folders
-    return Array.isArray(data) ? data : [];
+    type RepoTreeItem = (typeof repoTree.tree)[number];
+    const repoContents = repoTree.tree.filter(
+      (item): item is RepoTreeItem & { path: string } =>
+        typeof item.path === "string" && !item.path.includes("/"),
+    );
+
+    return {
+      repoInfo,
+      repoContents,
+    };
   } catch (error: unknown) {
-    const message =
-      error instanceof Error ? error.message : "Could not fetch contents";
-    console.error("Error fetching GitHub repo contents:", message);
-    return [];
+    throw toRepoAccessError(error, Boolean(accessToken));
   }
 }
diff --git a/src/types/next-auth.d.ts b/src/types/next-auth.d.ts
new file mode 100644
index 0000000..803d9c1
--- /dev/null
+++ b/src/types/next-auth.d.ts
@@ -0,0 +1,8 @@
+import "next-auth";
+import "next-auth/jwt";
+
+declare module "next-auth/jwt" {
+  interface JWT {
+    accessToken?: string;
+  }
+}