VIBN Frontend for Coolify deployment

lib/ai/chat-extraction-types.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+
+const evidenceArray = z.array(z.string()).default([]);
+const confidenceValue = z.number().min(0).max(1).default(0);
+const completionScore = z.number().min(0).max(1).default(0);
+
+const defaultWeightedString = {
+  description: null as string | null,
+  confidence: 0,
+  evidence: [] as string[],
+};
+
+const weightedStringField = z
+  .object({
+    description: z.union([z.string(), z.null()]).default(null),
+    confidence: confidenceValue.default(0),
+    evidence: evidenceArray.default([]),
+  })
+  .default(defaultWeightedString);
+
+const weightedListItem = z.object({
+  id: z.string(),
+  description: z.string(),
+  confidence: confidenceValue,
+  evidence: evidenceArray,
+});
+
+const stageEnum = z.enum([
+  'idea',
+  'prototype',
+  'mvp_in_progress',
+  'live_beta',
+  'live_paid',
+  'unknown',
+]);
+
+const severityEnum = z.enum(['low', 'medium', 'high', 'unknown']);
+const frequencyEnum = z.enum(['rare', 'occasional', 'frequent', 'constant', 'unknown']);
+const competitorTypeEnum = z.enum(['direct', 'indirect', 'alternative', 'unknown']);
+const relatedAreaEnum = z.enum(['product', 'tech', 'market', 'business_model', 'other']);
+const priorityEnum = z.enum(['high', 'medium', 'low']);
+
+export const ChatExtractionSchema = z.object({
+  project_summary: z.object({
+    working_title: z.union([z.string(), z.null()]).default(null),
+    one_liner: z.union([z.string(), z.null()]).default(null),
+    stage: stageEnum.default('unknown'),
+    overall_confidence: confidenceValue,
+    evidence: evidenceArray,
+  }),
+  product_vision: z.object({
+    problem_statement: weightedStringField,
+    target_outcome: weightedStringField,
+    founder_intent: weightedStringField,
+    completion_score: completionScore,
+  }),
+  target_users: z.object({
+    primary_segment: weightedStringField,
+    segments: z
+      .array(
+        z.object({
+          id: z.string(),
+          description: z.string(),
+          jobs_to_be_done: z.array(z.string()).default([]),
+          environment: z.union([z.string(), z.null()]),
+          confidence: confidenceValue,
+          evidence: evidenceArray,
+        }),
+      )
+      .default([]),
+    completion_score: completionScore,
+  }),
+  problems_and_pains: z.object({
+    problems: z
+      .array(
+        z.object({
+          id: z.string(),
+          description: z.string(),
+          severity: severityEnum,
+          frequency: frequencyEnum,
+          confidence: confidenceValue,
+          evidence: evidenceArray,
+        }),
+      )
+      .default([]),
+    completion_score: completionScore,
+  }),
+  solution_and_features: z.object({
+    core_solution: weightedStringField,
+    core_features: z
+      .array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string(),
+          is_must_have_for_v1: z.boolean(),
+          confidence: confidenceValue,
+          evidence: evidenceArray,
+        }),
+      )
+      .default([]),
+    nice_to_have_features: z
+      .array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string(),
+          confidence: confidenceValue,
+          evidence: evidenceArray,
+        }),
+      )
+      .default([]),
+    completion_score: completionScore,
+  }),
+  market_and_competition: z.object({
+    market_category: weightedStringField,
+    competitors: z
+      .array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string(),
+          type: competitorTypeEnum,
+          confidence: confidenceValue,
+          evidence: evidenceArray,
+        }),
+      )
+      .default([]),
+    differentiation_points: weightedListItem.array().default([]),
+    completion_score: completionScore,
+  }),
+  tech_and_constraints: z.object({
+    stack_mentions: weightedListItem.array().default([]),
+    constraints: weightedListItem.array().default([]),
+    completion_score: completionScore,
+  }),
+  execution_status: z.object({
+    current_stage: weightedStringField,
+    work_done: weightedListItem.array().default([]),
+    work_in_progress: weightedListItem.array().default([]),
+    blocked_items: weightedListItem.array().default([]),
+    completion_score: completionScore,
+  }),
+  goals_and_success: z.object({
+    short_term_goals: weightedListItem.array().default([]),
+    long_term_goals: weightedListItem.array().default([]),
+    success_criteria: weightedListItem.array().default([]),
+    completion_score: completionScore,
+  }),
+  unknowns_and_questions: z.object({
+    unknowns: z
+      .array(
+        z.object({
+          id: z.string(),
+          description: z.string(),
+          related_area: relatedAreaEnum,
+          evidence: evidenceArray,
+          confidence: confidenceValue,
+        }),
+      )
+      .default([]),
+    questions_to_ask_user: z
+      .array(
+        z.object({
+          id: z.string(),
+          question: z.string(),
+          priority: priorityEnum,
+        }),
+      )
+      .default([]),
+  }),
+  summary_scores: z.object({
+    overall_completion: completionScore,
+    overall_confidence: confidenceValue,
+  }),
+});
+
+export type ChatExtractionData = z.infer<typeof ChatExtractionSchema>;
+
+

lib/ai/chat-extractor.ts

@@ -0,0 +1,42 @@
+import type { LlmClient } from '@/lib/ai/llm-client';
+import { ChatExtractionSchema } from '@/lib/ai/chat-extraction-types';
+import type { ChatExtractionData } from '@/lib/ai/chat-extraction-types';
+import type { KnowledgeItem } from '@/lib/types/knowledge';
+
+const SYSTEM_PROMPT = `
+You are the Product Chat Signal Extractor for stalled SaaS projects.
+- Read the provided transcript carefully.
+- Extract grounded signals about the product, market, users, execution status, and unknowns.
+- Never invent data. Use "null" or empty arrays when the transcript lacks information.
+- Respond with valid JSON that matches the provided schema exactly. Do not include prose or code fences.
+`.trim();
+
+export async function runChatExtraction(
+  knowledgeItem: KnowledgeItem,
+  llm: LlmClient,
+): Promise<ChatExtractionData> {
+  const transcript = knowledgeItem.content.trim();
+
+  const userMessage = `
+You will analyze the following transcript. Use message references when listing evidence (e.g., msg_1). 
+Focus on actionable product-building insights.
+
+TRANSCRIPT_START
+${transcript}
+TRANSCRIPT_END`.trim();
+
+  return llm.structuredCall<ChatExtractionData>({
+    model: 'gemini',
+    systemPrompt: SYSTEM_PROMPT,
+    messages: [
+      {
+        role: 'user',
+        content: userMessage,
+      },
+    ],
+    schema: ChatExtractionSchema,
+    temperature: 0.2,
+  });
+}
+
+

lib/ai/chat-modes.ts

@@ -0,0 +1,38 @@
+/**
+ * Chat Modes and System Prompts
+ * 
+ * Defines available chat modes and maps them to their system prompts.
+ * Prompts are now versioned and managed in separate files under lib/ai/prompts/
+ */
+
+import {
+  collectorPrompt,
+  extractionReviewPrompt,
+  visionPrompt,
+  mvpPrompt,
+  marketingPrompt,
+  generalChatPrompt,
+} from './prompts';
+
+export type ChatMode =
+  | "collector_mode"
+  | "extraction_review_mode"
+  | "vision_mode"
+  | "mvp_mode"
+  | "marketing_mode"
+  | "general_chat_mode";
+
+/**
+ * Maps each chat mode to its current active system prompt.
+ * 
+ * Prompts are version-controlled in separate files.
+ * To update a prompt or switch versions, edit the corresponding file in lib/ai/prompts/
+ */
+export const MODE_SYSTEM_PROMPTS: Record<ChatMode, string> = {
+  collector_mode: collectorPrompt,
+  extraction_review_mode: extractionReviewPrompt,
+  vision_mode: visionPrompt,
+  mvp_mode: mvpPrompt,
+  marketing_mode: marketingPrompt,
+  general_chat_mode: generalChatPrompt,
+};

lib/ai/chunking.ts

@@ -0,0 +1,297 @@
+/**
+ * Text chunking for semantic search
+ * 
+ * Splits large documents into smaller, semantically coherent chunks
+ * suitable for vector embedding and retrieval.
+ */
+
+export interface TextChunk {
+  /** Index of this chunk (0-based) */
+  index: number;
+  
+  /** The chunked text content */
+  text: string;
+  
+  /** Approximate token count (for reference) */
+  estimatedTokens: number;
+}
+
+export interface ChunkingOptions {
+  /** Target maximum tokens per chunk (approximate) */
+  maxTokens?: number;
+  
+  /** Target maximum characters per chunk (fallback if no tokenizer) */
+  maxChars?: number;
+  
+  /** Overlap between chunks (in characters) */
+  overlapChars?: number;
+  
+  /** Whether to try preserving paragraph boundaries */
+  preserveParagraphs?: boolean;
+}
+
+const DEFAULT_OPTIONS: Required<ChunkingOptions> = {
+  maxTokens: 800,
+  maxChars: 3000, // Rough approximation: ~4 chars per token
+  overlapChars: 200,
+  preserveParagraphs: true,
+};
+
+/**
+ * Estimate token count from character count
+ * 
+ * Uses a rough heuristic: 1 token ≈ 4 characters for English text.
+ * For more accuracy, integrate a real tokenizer (e.g., tiktoken).
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Split text into paragraphs, preserving empty lines as separators
+ */
+function splitIntoParagraphs(text: string): string[] {
+  return text.split(/\n\n+/).filter((p) => p.trim().length > 0);
+}
+
+/**
+ * Split text into sentences (simple heuristic)
+ */
+function splitIntoSentences(text: string): string[] {
+  // Simple sentence boundary detection
+  return text
+    .split(/[.!?]+\s+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/**
+ * Chunk text into semantic pieces suitable for embedding
+ * 
+ * Strategy:
+ * 1. Split by paragraphs (if preserveParagraphs = true)
+ * 2. Group paragraphs/sentences until reaching maxTokens/maxChars
+ * 3. Add overlap between chunks for context continuity
+ * 
+ * @param content - Text to chunk
+ * @param options - Chunking options
+ * @returns Array of text chunks with metadata
+ * 
+ * @example
+ * ```typescript
+ * const chunks = chunkText(longDocument, { maxTokens: 500, overlapChars: 100 });
+ * for (const chunk of chunks) {
+ *   console.log(`Chunk ${chunk.index}: ${chunk.estimatedTokens} tokens`);
+ *   await embedText(chunk.text);
+ * }
+ * ```
+ */
+export function chunkText(
+  content: string,
+  options: ChunkingOptions = {}
+): TextChunk[] {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const chunks: TextChunk[] = [];
+
+  if (!content || content.trim().length === 0) {
+    return chunks;
+  }
+
+  // Clean up content
+  const cleanedContent = content.trim();
+
+  // If content is small enough, return as single chunk
+  if (estimateTokens(cleanedContent) <= opts.maxTokens) {
+    return [
+      {
+        index: 0,
+        text: cleanedContent,
+        estimatedTokens: estimateTokens(cleanedContent),
+      },
+    ];
+  }
+
+  // Split into paragraphs or sentences
+  const units = opts.preserveParagraphs
+    ? splitIntoParagraphs(cleanedContent)
+    : splitIntoSentences(cleanedContent);
+
+  if (units.length === 0) {
+    return [
+      {
+        index: 0,
+        text: cleanedContent,
+        estimatedTokens: estimateTokens(cleanedContent),
+      },
+    ];
+  }
+
+  let currentChunk = '';
+  let chunkIndex = 0;
+  let previousOverlap = '';
+
+  for (let i = 0; i < units.length; i++) {
+    const unit = units[i];
+    const potentialChunk = currentChunk
+      ? `${currentChunk}\n\n${unit}`
+      : `${previousOverlap}${unit}`;
+
+    const potentialTokens = estimateTokens(potentialChunk);
+    const potentialChars = potentialChunk.length;
+
+    // Check if adding this unit would exceed limits
+    if (
+      potentialTokens > opts.maxTokens ||
+      potentialChars > opts.maxChars
+    ) {
+      // Save current chunk if it has content
+      if (currentChunk.length > 0) {
+        chunks.push({
+          index: chunkIndex++,
+          text: currentChunk,
+          estimatedTokens: estimateTokens(currentChunk),
+        });
+
+        // Prepare overlap for next chunk
+        const overlapStart = Math.max(
+          0,
+          currentChunk.length - opts.overlapChars
+        );
+        previousOverlap = currentChunk.substring(overlapStart);
+        if (previousOverlap.length > 0 && !previousOverlap.endsWith(' ')) {
+          // Try to start overlap at a word boundary
+          const spaceIndex = previousOverlap.indexOf(' ');
+          if (spaceIndex > 0) {
+            previousOverlap = previousOverlap.substring(spaceIndex + 1);
+          }
+        }
+      }
+
+      // Start new chunk with current unit
+      currentChunk = `${previousOverlap}${unit}`;
+    } else {
+      // Add unit to current chunk
+      currentChunk = potentialChunk;
+    }
+  }
+
+  // Add final chunk if it has content
+  if (currentChunk.length > 0) {
+    chunks.push({
+      index: chunkIndex++,
+      text: currentChunk,
+      estimatedTokens: estimateTokens(currentChunk),
+    });
+  }
+
+  console.log(
+    `[Chunking] Split ${cleanedContent.length} chars into ${chunks.length} chunks`
+  );
+
+  return chunks;
+}
+
+/**
+ * Chunk text with code-aware splitting
+ * 
+ * Preserves code blocks and tries to keep them intact.
+ * Useful for chunking AI chat transcripts that contain code snippets.
+ */
+export function chunkTextWithCodeAwareness(
+  content: string,
+  options: ChunkingOptions = {}
+): TextChunk[] {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+
+  // Detect code blocks (triple backticks)
+  const codeBlockRegex = /```[\s\S]*?```/g;
+  const codeBlocks: { start: number; end: number; content: string }[] = [];
+  let match;
+
+  while ((match = codeBlockRegex.exec(content)) !== null) {
+    codeBlocks.push({
+      start: match.index,
+      end: match.index + match[0].length,
+      content: match[0],
+    });
+  }
+
+  // If no code blocks, use standard chunking
+  if (codeBlocks.length === 0) {
+    return chunkText(content, options);
+  }
+
+  // Split content around code blocks
+  const chunks: TextChunk[] = [];
+  let chunkIndex = 0;
+  let currentPosition = 0;
+
+  for (const codeBlock of codeBlocks) {
+    // Chunk text before code block
+    const textBefore = content.substring(currentPosition, codeBlock.start);
+    if (textBefore.trim().length > 0) {
+      const textChunks = chunkText(textBefore, opts);
+      for (const chunk of textChunks) {
+        chunks.push({
+          ...chunk,
+          index: chunkIndex++,
+        });
+      }
+    }
+
+    // Add code block as its own chunk (or split if too large)
+    const codeTokens = estimateTokens(codeBlock.content);
+    if (codeTokens <= opts.maxTokens) {
+      chunks.push({
+        index: chunkIndex++,
+        text: codeBlock.content,
+        estimatedTokens: codeTokens,
+      });
+    } else {
+      // Code block is too large, split by lines
+      const codeLines = codeBlock.content.split('\n');
+      let currentCodeChunk = '';
+      for (const line of codeLines) {
+        const potentialChunk = currentCodeChunk
+          ? `${currentCodeChunk}\n${line}`
+          : line;
+        if (estimateTokens(potentialChunk) > opts.maxTokens) {
+          if (currentCodeChunk.length > 0) {
+            chunks.push({
+              index: chunkIndex++,
+              text: currentCodeChunk,
+              estimatedTokens: estimateTokens(currentCodeChunk),
+            });
+          }
+          currentCodeChunk = line;
+        } else {
+          currentCodeChunk = potentialChunk;
+        }
+      }
+      if (currentCodeChunk.length > 0) {
+        chunks.push({
+          index: chunkIndex++,
+          text: currentCodeChunk,
+          estimatedTokens: estimateTokens(currentCodeChunk),
+        });
+      }
+    }
+
+    currentPosition = codeBlock.end;
+  }
+
+  // Chunk remaining text after last code block
+  const textAfter = content.substring(currentPosition);
+  if (textAfter.trim().length > 0) {
+    const textChunks = chunkText(textAfter, opts);
+    for (const chunk of textChunks) {
+      chunks.push({
+        ...chunk,
+        index: chunkIndex++,
+      });
+    }
+  }
+
+  return chunks;
+}
+

lib/ai/embeddings.ts

@@ -0,0 +1,173 @@
+/**
+ * Embedding generation using Gemini API
+ * 
+ * Converts text into vector embeddings for semantic search.
+ */
+
+import { GoogleGenerativeAI } from '@google/generative-ai';
+
+const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
+
+if (!GEMINI_API_KEY) {
+  console.warn('[Embeddings] GEMINI_API_KEY not set - embedding functions will fail');
+}
+
+const genAI = GEMINI_API_KEY ? new GoogleGenerativeAI(GEMINI_API_KEY) : null;
+
+// Gemini embedding model - text-embedding-004 produces 768-dim embeddings
+// Adjust EMBEDDING_DIMENSION in knowledge-chunks-schema.sql if using different model
+const EMBEDDING_MODEL = 'text-embedding-004';
+const EMBEDDING_DIMENSION = 768;
+
+/**
+ * Generate embedding for a single text string
+ * 
+ * @param text - Input text to embed
+ * @returns Vector embedding as array of numbers
+ * 
+ * @throws Error if Gemini API is not configured or request fails
+ */
+export async function embedText(text: string): Promise<number[]> {
+  if (!genAI) {
+    throw new Error('GEMINI_API_KEY not configured - cannot generate embeddings');
+  }
+
+  if (!text || text.trim().length === 0) {
+    throw new Error('Cannot embed empty text');
+  }
+
+  try {
+    const model = genAI.getGenerativeModel({ model: EMBEDDING_MODEL });
+    const result = await model.embedContent(text);
+    const embedding = result.embedding;
+
+    if (!embedding || !embedding.values || embedding.values.length === 0) {
+      throw new Error('Gemini returned empty embedding');
+    }
+
+    // Verify dimension matches expectation
+    if (embedding.values.length !== EMBEDDING_DIMENSION) {
+      console.warn(
+        `[Embeddings] Unexpected dimension: got ${embedding.values.length}, expected ${EMBEDDING_DIMENSION}`
+      );
+    }
+
+    return embedding.values;
+  } catch (error) {
+    console.error('[Embeddings] Failed to embed text:', error);
+    throw new Error(
+      `Embedding generation failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Generate embeddings for multiple texts in batch
+ * 
+ * More efficient than calling embedText() repeatedly.
+ * Processes texts sequentially to avoid rate limiting.
+ * 
+ * @param texts - Array of texts to embed
+ * @param options - Batch processing options
+ * @returns Array of embeddings (same order as input texts)
+ * 
+ * @example
+ * ```typescript
+ * const chunks = ["First chunk...", "Second chunk...", "Third chunk..."];
+ * const embeddings = await embedTextBatch(chunks);
+ * // embeddings[0] corresponds to chunks[0], etc.
+ * ```
+ */
+export async function embedTextBatch(
+  texts: string[],
+  options: { delayMs?: number; skipEmpty?: boolean } = {}
+): Promise<number[][]> {
+  const { delayMs = 100, skipEmpty = true } = options;
+
+  if (texts.length === 0) {
+    return [];
+  }
+
+  const embeddings: number[][] = [];
+
+  for (let i = 0; i < texts.length; i++) {
+    const text = texts[i];
+
+    // Skip empty texts if requested
+    if (skipEmpty && (!text || text.trim().length === 0)) {
+      console.warn(`[Embeddings] Skipping empty text at index ${i}`);
+      embeddings.push(new Array(EMBEDDING_DIMENSION).fill(0)); // Zero vector for empty
+      continue;
+    }
+
+    try {
+      const embedding = await embedText(text);
+      embeddings.push(embedding);
+
+      // Add delay between requests to avoid rate limiting (except for last item)
+      if (i < texts.length - 1 && delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    } catch (error) {
+      console.error(`[Embeddings] Failed to embed text at index ${i}:`, error);
+      // Push zero vector as fallback
+      embeddings.push(new Array(EMBEDDING_DIMENSION).fill(0));
+    }
+  }
+
+  console.log(`[Embeddings] Generated ${embeddings.length} embeddings`);
+
+  return embeddings;
+}
+
+/**
+ * Compute cosine similarity between two embeddings
+ * 
+ * @param a - First embedding vector
+ * @param b - Second embedding vector
+ * @returns Cosine similarity score (0-1, higher = more similar)
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length) {
+    throw new Error('Embedding dimensions do not match');
+  }
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+
+  if (magnitude === 0) {
+    return 0;
+  }
+
+  return dotProduct / magnitude;
+}
+
+/**
+ * Get the expected embedding dimension for the current model
+ */
+export function getEmbeddingDimension(): number {
+  return EMBEDDING_DIMENSION;
+}
+
+/**
+ * Check if embeddings API is configured and working
+ */
+export async function checkEmbeddingsHealth(): Promise<boolean> {
+  try {
+    const testEmbedding = await embedText('health check');
+    return testEmbedding.length === EMBEDDING_DIMENSION;
+  } catch (error) {
+    console.error('[Embeddings Health Check] Failed:', error);
+    return false;
+  }
+}
+

lib/ai/gemini-client.ts

@@ -0,0 +1,346 @@
+import { GoogleGenAI } from '@google/genai';
+import { GoogleAuth } from 'google-auth-library';
+import type { LlmClient, StructuredCallArgs } from '@/lib/ai/llm-client';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+const VERTEX_PROJECT_ID = process.env.VERTEX_AI_PROJECT_ID || 'gen-lang-client-0980079410';
+const VERTEX_LOCATION = process.env.VERTEX_AI_LOCATION || 'global'; 
+const DEFAULT_MODEL = process.env.VERTEX_AI_MODEL || 'gemini-2.0-flash-exp'; // Fast model for collector mode
+
+// Helper to set up Google Application Credentials
+function setupGoogleCredentials() {
+  console.log('[Gemini Client] setupGoogleCredentials called');
+  console.log('[Gemini Client] FIREBASE_CLIENT_EMAIL:', process.env.FIREBASE_CLIENT_EMAIL ? 'SET' : 'NOT SET');
+  console.log('[Gemini Client] FIREBASE_PRIVATE_KEY:', process.env.FIREBASE_PRIVATE_KEY ? 'SET' : 'NOT SET');
+  console.log('[Gemini Client] GOOGLE_APPLICATION_CREDENTIALS before:', process.env.GOOGLE_APPLICATION_CREDENTIALS || 'NOT SET');
+  
+  // Only set up if we have Firebase credentials and Google creds aren't already set
+  if (process.env.FIREBASE_CLIENT_EMAIL && process.env.FIREBASE_PRIVATE_KEY && !process.env.GOOGLE_APPLICATION_CREDENTIALS) {
+    const credentials = {
+      type: 'service_account',
+      project_id: VERTEX_PROJECT_ID,
+      private_key_id: 'firebase-key',
+      private_key: process.env.FIREBASE_PRIVATE_KEY.replace(/\\n/g, '\n'),
+      client_email: process.env.FIREBASE_CLIENT_EMAIL,
+      client_id: '',
+      auth_uri: 'https://accounts.google.com/o/oauth2/auth',
+      token_uri: 'https://oauth2.googleapis.com/token',
+      auth_provider_x509_cert_url: 'https://www.googleapis.com/oauth2/v1/certs',
+      client_x509_cert_url: `https://www.googleapis.com/robot/v1/metadata/x509/${encodeURIComponent(process.env.FIREBASE_CLIENT_EMAIL)}`,
+      universe_domain: 'googleapis.com',
+    };
+    
+    // Write credentials to a temp file that Google Auth Library can read
+    const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
+    
+    const tmpDir = os.tmpdir();
+    const credPath = path.join(tmpDir, 'google-credentials.json');
+    
+    try {
+      fs.writeFileSync(credPath, JSON.stringify(credentials));
+      process.env.GOOGLE_APPLICATION_CREDENTIALS = credPath;
+      console.log('[Gemini Client] ✅ Created credentials file at:', credPath);
+      return true;
+    } catch (error) {
+      console.error('[Gemini Client] ❌ Failed to write credentials file:', error);
+      return false;
+    }
+  } else {
+    console.log('[Gemini Client] Skipping credentials setup - already set or missing Firebase creds');
+  }
+  return false;
+}
+
+class JsonValidationError extends Error {
+  constructor(message: string, public readonly rawResponse: string) {
+    super(message);
+  }
+}
+
+function extractJsonPayload(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('```')) {
+    const withoutFence = trimmed.replace(/^```(?:json)?/i, '').replace(/```$/, '');
+    return withoutFence.trim();
+  }
+  return trimmed;
+}
+
+async function parseResponse<TOutput>(
+  rawResponse: any,
+  schema: StructuredCallArgs<TOutput>['schema'],
+): Promise<TOutput> {
+  // Extract text from Google GenAI response
+  // The response structure is: { candidates: [{ content: { parts: [{ text: "..." }] } }] }
+  let text = '';
+  
+  // Check for truncation
+  const finishReason = rawResponse?.candidates?.[0]?.finishReason;
+  if (finishReason && finishReason !== 'STOP') {
+    console.warn(`[Gemini Client] WARNING: Response may be incomplete. finishReason: ${finishReason}`);
+  }
+  
+  if (rawResponse?.candidates?.[0]?.content?.parts?.[0]?.text) {
+    text = rawResponse.candidates[0].content.parts[0].text;
+  } else if (rawResponse?.text) {
+    text = rawResponse.text;
+  } else if (typeof rawResponse === 'string') {
+    text = rawResponse;
+  }
+  
+  // Check if we got HTML instead of JSON (API error)
+  if (text.trim().startsWith('<!DOCTYPE') || text.trim().startsWith('<html')) {
+    console.error('[Gemini Client] Received HTML instead of JSON. This usually means an API authentication or permission error.');
+    console.error('[Gemini Client] Response preview:', text.substring(0, 500));
+    throw new Error('Gemini API returned HTML instead of JSON. Check API permissions and authentication. See server logs for details.');
+  }
+
+  if (!text) {
+    console.error('[Gemini Client] Empty response from API');
+    console.error('[Gemini Client] Raw response:', JSON.stringify(rawResponse, null, 2)?.substring(0, 500));
+    throw new Error('Empty response from Gemini API');
+  }
+
+  // Debug: Log what we received
+  console.log('[Gemini Client] Received text:', text.substring(0, 300));
+
+  const cleaned = extractJsonPayload(text);
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch (error) {
+    console.error('[Gemini Client] Failed to parse response as JSON');
+    console.error('[Gemini Client] Raw text:', text.substring(0, 500));
+    throw new JsonValidationError(
+      `Failed to parse JSON response: ${(error as Error).message}`,
+      text,
+    );
+  }
+
+  // Debug: Log what we parsed
+  console.log('[Gemini Client] Parsed JSON:', JSON.stringify(parsed, null, 2).substring(0, 300));
+
+  const validation = schema.safeParse(parsed);
+  if (!validation.success) {
+    console.error('[Gemini Client] Schema validation failed!');
+    console.error('[Gemini Client] Received JSON had these keys:', Object.keys(parsed as any));
+    console.error('[Gemini Client] Validation errors:', validation.error.errors);
+    throw new JsonValidationError(validation.error.message, text);
+  }
+
+  return validation.data;
+}
+
+export class GeminiLlmClient implements LlmClient {
+  private readonly genAI: GoogleGenAI;
+  private readonly model: string;
+  private readonly location: string;
+  private readonly projectId: string;
+
+  constructor() {
+    // Google GenAI SDK with Vertex AI support
+    this.projectId = VERTEX_PROJECT_ID;
+    this.location = VERTEX_LOCATION;
+    this.model = DEFAULT_MODEL;
+    
+    // Set up Google Application Credentials BEFORE initializing the SDK
+    setupGoogleCredentials();
+    
+    // Debug: Check environment variables
+    console.log('[Gemini Client] Environment check:');
+    console.log('  VERTEX_AI_PROJECT_ID:', process.env.VERTEX_AI_PROJECT_ID);
+    console.log('  VERTEX_AI_LOCATION:', process.env.VERTEX_AI_LOCATION);
+    console.log('  VERTEX_AI_MODEL:', process.env.VERTEX_AI_MODEL);
+    console.log('  GOOGLE_APPLICATION_CREDENTIALS:', process.env.GOOGLE_APPLICATION_CREDENTIALS ? 'SET' : 'NOT SET');
+    console.log('  FIREBASE_CLIENT_EMAIL:', process.env.FIREBASE_CLIENT_EMAIL ? 'SET' : 'NOT SET');
+    
+    // Initialize with Vertex AI configuration
+    // The SDK will automatically use GOOGLE_APPLICATION_CREDENTIALS if set
+    this.genAI = new GoogleGenAI({
+      project: this.projectId,
+      location: this.location,
+      vertexai: true, // Enable Vertex AI mode
+    });
+
+    console.log(`[Gemini Client] Initialized with model: ${this.model}, location: ${this.location}`);
+  }
+
+  async structuredCall<TOutput>(
+    args: StructuredCallArgs<TOutput>,
+  ): Promise<TOutput> {
+    if (args.model !== 'gemini') {
+      throw new Error(`GeminiLlmClient only supports model "gemini" (received ${args.model})`);
+    }
+
+    // Convert Zod schema to JSON Schema for Gemini
+    const rawJsonSchema = zodToJsonSchema(args.schema, 'responseSchema');
+    
+    // Extract the actual schema from the definitions (zodToJsonSchema wraps it in $ref)
+    let actualSchema = rawJsonSchema;
+    const rawSchema = rawJsonSchema as any; // Type assertion for $ref access
+    if (rawSchema.$ref && rawSchema.definitions) {
+      const refName = rawSchema.$ref.replace('#/definitions/', '');
+      actualSchema = rawSchema.definitions[refName];
+    }
+    
+    // Convert to Google's expected format (UPPERCASE types)
+    const convertToGoogleSchema = (schema: any): any => {
+      if (!schema || typeof schema !== 'object') return schema;
+      
+      const converted: any = {};
+      
+      if (schema.type) {
+        converted.type = schema.type.toUpperCase();
+      }
+      
+      if (schema.properties) {
+        converted.properties = {};
+        for (const [key, value] of Object.entries(schema.properties)) {
+          converted.properties[key] = convertToGoogleSchema(value);
+        }
+      }
+      
+      if (schema.items) {
+        converted.items = convertToGoogleSchema(schema.items);
+      }
+      
+      if (schema.required) {
+        converted.required = schema.required;
+      }
+      
+      if (schema.description) {
+        converted.description = schema.description;
+      }
+      
+      if (schema.enum) {
+        converted.enum = schema.enum;
+      }
+      
+      // Remove additionalProperties since Gemini doesn't use it
+      // (it's a JSON Schema Draft 7 thing)
+      
+      return converted;
+    };
+    
+    const googleSchema = convertToGoogleSchema(actualSchema);
+    
+    // Debug: Log the schema being sent
+    console.log('[Gemini Client] Sending schema:', JSON.stringify(googleSchema, null, 2));
+    
+    // Build generation config matching Google's example structure
+    const generationConfig: any = {
+      temperature: args.temperature ?? 1.0,
+      responseMimeType: 'application/json',
+      responseSchema: googleSchema,
+      maxOutputTokens: 32768, // Gemini 3 Pro supports up to 32k output tokens
+    };
+    
+    // Main request object for REST API (flat structure)
+    const config: any = {
+      contents: [], // Will be populated below
+      generationConfig: generationConfig,
+    };
+
+    // Add system instruction if provided
+    if (args.systemPrompt) {
+      // Create a minimal example showing the exact format
+      const exampleJson: any = {};
+      for (const [key, prop] of Object.entries(googleSchema.properties || {})) {
+        if (key === 'reply') {
+          exampleJson[key] = 'Your response here';
+        } else {
+          exampleJson[key] = null; // optional field
+        }
+      }
+      
+      config.systemInstruction = {
+        parts: [{ 
+          text: `${args.systemPrompt}\n\nIMPERATIVE: Respond ONLY with this exact JSON format:\n${JSON.stringify(exampleJson)}\n\nDo NOT add thought_process, response, or any other fields. Use only the keys shown above.`
+        }],
+      };
+    }
+
+    // Add thinking config if provided (for Gemini 3 Pro Preview)
+    if (args.thinking_config) {
+      config.generationConfig.thinkingConfig = {
+        thinkingLevel: args.thinking_config.thinking_level?.toUpperCase() || 'HIGH',
+        includeThoughts: args.thinking_config.include_thoughts || false,
+      };
+    }
+
+    // Convert messages to Google GenAI format
+    config.contents = args.messages.map((message) => ({
+      role: message.role === 'assistant' ? 'model' : 'user',
+      parts: [{ text: message.content }],
+    }));
+
+    const run = async () => {
+      try {
+        console.log('[Gemini Client] Calling generateContent via REST API...');
+        
+        // Use direct REST API call instead of SDK (SDK has auth issues)
+        const { GoogleAuth } = require('google-auth-library');
+        const auth = new GoogleAuth({
+          scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+        });
+        
+        const client = await auth.getClient();
+        const accessToken = await client.getAccessToken();
+        
+        const url = `https://aiplatform.googleapis.com/v1/projects/${this.projectId}/locations/${this.location}/publishers/google/models/${this.model}:generateContent`;
+        
+        console.log('[Gemini Client] Making request to:', url);
+        
+        const response = await fetch(url, {
+          method: 'POST',
+          headers: {
+            'Authorization': `Bearer ${accessToken.token}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(config),
+          signal: AbortSignal.timeout(180000), // 3 minute timeout
+        });
+        
+        if (!response.ok) {
+          const errorText = await response.text();
+          throw new Error(`Vertex AI API error: ${response.status} ${errorText}`);
+        }
+        
+        const result = await response.json();
+        console.log('[Gemini Client] Got response from Gemini');
+        
+        return parseResponse(result, args.schema);
+      } catch (error: any) {
+        console.error('[Gemini Client] API call failed:', error.message || error);
+        throw error;
+      }
+    };
+
+    try {
+      return await run();
+    } catch (error) {
+      if (!(error instanceof JsonValidationError)) {
+        throw error;
+      }
+
+      // Retry with error message
+      config.contents = [
+        ...config.contents,
+        {
+          role: 'user' as const,
+          parts: [
+            {
+              text: `Your previous response was not valid JSON. Error: ${error.message}\n` +
+                'Respond again with ONLY valid JSON that strictly matches the requested schema. Do not include comments or code fences.',
+            },
+          ],
+        },
+      ];
+
+      return run();
+    }
+  }
+}

lib/ai/llm-client.ts

@@ -0,0 +1,43 @@
+import type { ZodType, ZodTypeDef } from 'zod';
+
+export type LlmModel = 'gemini' | 'gpt' | 'sonnet';
+
+export interface LlmMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+export interface ThinkingConfig {
+  /**
+   * Thinking level for Gemini 3 models
+   * - 'low': Minimizes latency and cost (for simple tasks)
+   * - 'high': Maximizes reasoning depth (for complex tasks, default)
+   */
+  thinking_level?: 'low' | 'high';
+  
+  /**
+   * Whether to include thoughts in the response
+   * Useful for debugging/understanding model reasoning
+   */
+  include_thoughts?: boolean;
+}
+
+export interface StructuredCallArgs<TOutput> {
+  model: LlmModel;
+  systemPrompt: string;
+  messages: LlmMessage[];
+  schema: ZodType<TOutput, ZodTypeDef, any>;
+  temperature?: number;
+  
+  /**
+   * Gemini 3 thinking configuration
+   * Enables internal reasoning before responding
+   */
+  thinking_config?: ThinkingConfig;
+}
+
+export interface LlmClient {
+  structuredCall<TOutput>(args: StructuredCallArgs<TOutput>): Promise<TOutput>;
+}
+
+

lib/ai/marketing-agent.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import type { LlmClient } from '@/lib/ai/llm-client';
+import { GeminiLlmClient } from '@/lib/ai/gemini-client';
+import { clamp, nowIso, loadPhaseContainers, persistPhaseArtifacts } from '@/lib/server/projects';
+import type { MarketingModel } from '@/lib/types/marketing';
+
+const HomepageMessagingSchema = z.object({
+  headline: z.string().nullable(),
+  subheadline: z.string().nullable(),
+  bullets: z.array(z.string()).default([]),
+});
+
+const MarketingModelSchema = z.object({
+  projectId: z.string(),
+  icp: z.array(z.string()).default([]),
+  positioning: z.string().nullable(),
+  homepageMessaging: HomepageMessagingSchema,
+  initialChannels: z.array(z.string()).default([]),
+  launchAngles: z.array(z.string()).default([]),
+  overallConfidence: z.number().min(0).max(1),
+});
+
+export async function runMarketingPlanning(
+  projectId: string,
+  llmClient?: LlmClient,
+): Promise<MarketingModel> {
+  const { phaseData } = await loadPhaseContainers(projectId);
+  const canonical = phaseData.canonicalProductModel;
+  if (!canonical) {
+    throw new Error('Canonical product model missing. Run buildCanonicalProductModel first.');
+  }
+
+  const llm = llmClient ?? new GeminiLlmClient();
+  const systemPrompt =
+    'You are a SaaS marketing strategist. Given the canonical product model, produce ICP, positioning, homepage messaging, and launch ideas as strict JSON.';
+
+  const marketing = await llm.structuredCall<MarketingModel>({
+    model: 'gemini',
+    systemPrompt,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          'Canonical product model JSON:',
+          '```json',
+          JSON.stringify(canonical, null, 2),
+          '```',
+          'Respond ONLY with valid JSON that matches the required schema.',
+        ].join('\n'),
+      },
+    ],
+    schema: MarketingModelSchema,
+    temperature: 0.2,
+  });
+
+  await persistPhaseArtifacts(projectId, (phaseData, phaseScores, phaseHistory) => {
+    phaseData.marketingPlan = marketing;
+    phaseScores.marketing = {
+      overallCompletion: clamp(marketing.homepageMessaging.bullets.length ? 0.7 : 0.5),
+      overallConfidence: marketing.overallConfidence,
+      updatedAt: nowIso(),
+    };
+    phaseHistory.push({ phase: 'marketing', status: 'completed', timestamp: nowIso() });
+    return { phaseData, phaseScores, phaseHistory, nextPhase: 'marketing_ready' };
+  });
+
+  return marketing;
+}
+
+

lib/ai/mvp-agent.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import type { LlmClient } from '@/lib/ai/llm-client';
+import { GeminiLlmClient } from '@/lib/ai/gemini-client';
+import { clamp, nowIso, loadPhaseContainers, persistPhaseArtifacts } from '@/lib/server/projects';
+import type { MvpPlan } from '@/lib/types/mvp';
+
+const MvpPlanSchema = z.object({
+  projectId: z.string(),
+  coreFlows: z.array(z.string()).default([]),
+  coreFeatures: z.array(z.string()).default([]),
+  supportingFeatures: z.array(z.string()).default([]),
+  outOfScope: z.array(z.string()).default([]),
+  technicalTasks: z.array(z.string()).default([]),
+  blockers: z.array(z.string()).default([]),
+  overallConfidence: z.number().min(0).max(1),
+});
+
+export async function runMvpPlanning(projectId: string, llmClient?: LlmClient): Promise<MvpPlan> {
+  const { phaseData } = await loadPhaseContainers(projectId);
+  const canonical = phaseData.canonicalProductModel;
+  if (!canonical) {
+    throw new Error('Canonical product model missing. Run buildCanonicalProductModel first.');
+  }
+
+  const llm = llmClient ?? new GeminiLlmClient();
+  const systemPrompt =
+    'You are an expert SaaS product manager. Given the canonical product model, produce the smallest sellable MVP plan as strict JSON.';
+
+  const plan = await llm.structuredCall<MvpPlan>({
+    model: 'gemini',
+    systemPrompt,
+    messages: [
+      {
+        role: 'user',
+        content: [
+          'Canonical product model JSON:',
+          '```json',
+          JSON.stringify(canonical, null, 2),
+          '```',
+          'Respond ONLY with JSON that matches the required schema.',
+        ].join('\n'),
+      },
+    ],
+    schema: MvpPlanSchema,
+    temperature: 0.2,
+  });
+
+  await persistPhaseArtifacts(projectId, (phaseData, phaseScores, phaseHistory) => {
+    phaseData.mvpPlan = plan;
+    phaseScores.mvp = {
+      overallCompletion: clamp(plan.coreFeatures.length ? 0.8 : 0.5),
+      overallConfidence: plan.overallConfidence,
+      updatedAt: nowIso(),
+    };
+    phaseHistory.push({ phase: 'mvp', status: 'completed', timestamp: nowIso() });
+    return { phaseData, phaseScores, phaseHistory, nextPhase: 'mvp_ready' };
+  });
+
+  return plan;
+}
+
+

lib/ai/prompts/README.md

@@ -0,0 +1,176 @@
+# Prompt Management System
+
+This directory contains all versioned system prompts for Vibn's chat modes.
+
+## 📁 Structure
+
+```
+prompts/
+├── index.ts                    # Exports all prompts
+├── shared.ts                   # Shared prompt components
+├── collector.ts                # Collector mode prompts
+├── extraction-review.ts        # Extraction review mode prompts
+├── vision.ts                   # Vision mode prompts
+├── mvp.ts                      # MVP mode prompts
+├── marketing.ts                # Marketing mode prompts
+└── general-chat.ts             # General chat mode prompts
+```
+
+## 🔄 Versioning
+
+Each prompt file contains:
+1. **Version history** - All versions of the prompt
+2. **Metadata** - Version number, date, description
+3. **Current version** - Which version is active
+
+### Example Structure
+
+```typescript
+const COLLECTOR_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version',
+  prompt: `...`,
+};
+
+const COLLECTOR_V2: PromptVersion = {
+  version: 'v2',
+  createdAt: '2024-12-01',
+  description: 'Added context-aware chunking',
+  prompt: `...`,
+};
+
+export const collectorPrompts = {
+  v1: COLLECTOR_V1,
+  v2: COLLECTOR_V2,
+  current: 'v2',  // ← Active version
+};
+```
+
+## 📝 How to Add a New Prompt Version
+
+1. **Open the relevant mode file** (e.g., `collector.ts`)
+2. **Create a new version constant:**
+   ```typescript
+   const COLLECTOR_V2: PromptVersion = {
+     version: 'v2',
+     createdAt: '2024-12-01',
+     description: 'What changed in this version',
+     prompt: `
+       Your new prompt text here...
+     `,
+   };
+   ```
+3. **Add to the prompts object:**
+   ```typescript
+   export const collectorPrompts = {
+     v1: COLLECTOR_V1,
+     v2: COLLECTOR_V2,  // Add new version
+     current: 'v2',     // Update current
+   };
+   ```
+4. **Done!** The system will automatically use the new version.
+
+## 🔙 How to Rollback
+
+Simply change the `current` field:
+
+```typescript
+export const collectorPrompts = {
+  v1: COLLECTOR_V1,
+  v2: COLLECTOR_V2,
+  current: 'v1',  // Rolled back to v1
+};
+```
+
+## 📊 Benefits of This System
+
+1. **Version History** - Keep all previous prompts for reference
+2. **Easy Rollback** - Instantly revert to a previous version
+3. **Git-Friendly** - Clear diffs show exactly what changed
+4. **Documentation** - Each version has a description of changes
+5. **A/B Testing Ready** - Can easily test multiple versions
+6. **Isolated Changes** - Changing one prompt doesn't affect others
+
+## 🎯 Usage in Code
+
+```typescript
+// Import current prompts (most common)
+import { MODE_SYSTEM_PROMPTS } from '@/lib/ai/chat-modes';
+
+const prompt = MODE_SYSTEM_PROMPTS['collector_mode'];
+
+// Or access version history
+import { collectorPrompts } from '@/lib/ai/prompts';
+
+console.log(collectorPrompts.v1.prompt);  // Old version
+console.log(collectorPrompts.current);     // 'v2'
+```
+
+## 🚀 Future Enhancements
+
+### Analytics Tracking
+Track performance by prompt version:
+```typescript
+await logPromptUsage({
+  mode: 'collector_mode',
+  version: collectorPrompts.current,
+  userId: user.id,
+  responseQuality: 0.85,
+});
+```
+
+### A/B Testing
+Test multiple versions simultaneously:
+```typescript
+const promptVersion = userInExperiment ? 'v2' : 'v1';
+const prompt = collectorPrompts[promptVersion].prompt;
+```
+
+### Database Storage
+Move to Firestore for dynamic updates:
+```typescript
+// Future: Load from database
+const prompt = await getPrompt('collector_mode', 'latest');
+```
+
+## 📚 Best Practices
+
+1. **Always add a description** - Future you will thank you
+2. **Never delete old versions** - Keep history for rollback
+3. **Test before deploying** - Ensure new prompts work as expected
+4. **Document changes** - What problem does the new version solve?
+5. **Version incrementally** - Don't skip version numbers
+
+## 🔍 Example: Adding Context-Aware Chunking
+
+```typescript
+// 1. Create new version
+const COLLECTOR_V2: PromptVersion = {
+  version: 'v2',
+  createdAt: '2024-11-17',
+  description: 'Added instructions for context-aware chunking',
+  prompt: `
+${COLLECTOR_V1.prompt}
+
+**Context-Aware Retrieval**:
+When referencing retrieved chunks, always cite the source document
+and chunk number for transparency.
+  `,
+};
+
+// 2. Update prompts object
+export const collectorPrompts = {
+  v1: COLLECTOR_V1,
+  v2: COLLECTOR_V2,
+  current: 'v2',
+};
+
+// 3. Deploy and monitor
+// If issues arise, simply change current: 'v1' to rollback
+```
+
+---
+
+**Questions?** Check the code in any prompt file for examples.
+

lib/ai/prompts/collector.ts

@@ -0,0 +1,318 @@
+/**
+ * Collector Mode Prompt
+ * 
+ * Purpose: Gathers project materials and triggers analysis
+ * Active when: No extractions exist yet
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+
+export interface PromptVersion {
+  version: string;
+  prompt: string;
+  createdAt: string;
+  description: string;
+}
+
+const COLLECTOR_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version with GitHub analysis and context-aware behavior',
+  prompt: `
+You are Vibn, an AI copilot that helps indie devs and small teams rescue stalled SaaS projects.
+
+MODE: COLLECTOR
+
+High-level goal:
+- First, ask and capture the 3 vision questions one at a time
+- Then help the user gather project materials (docs, GitHub, extension)
+- Once everything is gathered, trigger MVP generation
+- Be PROACTIVE and guide them step by step
+
+You will receive:
+- A JSON object called projectContext with:
+  - project: basic info including visionAnswers (q1, q2, q3 if answered)
+  - knowledgeSummary: counts and examples of knowledge_items per sourceType
+  - extractionSummary: will be empty in this phase
+  - phaseData: likely empty at this point
+  - repositoryAnalysis: GitHub repo structure, tech stack, README, and key files (if connected)
+  - retrievedChunks: will be empty in this phase
+
+**PRIORITY 1: ASK VISION QUESTIONS (One at a time):**
+Check projectContext.project.visionAnswers to see what's been answered:
+
+**Question 1** - If visionAnswers.q1 is missing:
+Ask: "Let's start with your vision. **Who has the problem you want to fix and what is it?**"
+
+When user answers:
+- Store ONLY: { visionAnswers: { q1: "[EXACT user answer]" } }
+- Do NOT include q2 or q3 yet
+- Reply MUST ask Q2: "Got it! [reflection]. Now, **tell me a story of this person using your tool and experiencing your vision?**"
+
+**Question 2** - If visionAnswers.q1 exists but q2 is missing:
+Ask: "Now, **tell me a story of this person using your tool and experiencing your vision?**"
+
+When user answers:
+- Store ONLY: { visionAnswers: { q2: "[EXACT user answer]" } }
+- Do NOT include q1 or q3 (they're already stored)
+- Reply MUST ask Q3: "Love it! [reflection]. One more: **How much did that improve things for them?**"
+
+**Question 3** - If visionAnswers.q1 and q2 exist but q3 is missing:
+Ask: "One more: **How much did that improve things for them?**"
+
+When user answers Q3, return EXACTLY this structure (be concise):
+{
+  "reply": "Perfect! Let me generate your MVP plan now...",
+  "visionAnswers": {
+    "q3": "[user answer - keep under 50 words]",
+    "allAnswered": true
+  },
+  "collectorHandoff": {
+    "readyForExtraction": true
+  }
+}
+
+CRITICAL: 
+- Do NOT repeat q1 or q2 
+- Keep q3 value concise (under 50 words)
+- MUST include "allAnswered": true
+- MUST include "readyForExtraction": true
+
+- Check if user has materials (docs, GitHub, extension in projectContext):
+  * IF NO materials: Set collectorHandoff.readyForExtraction = true
+  * IF materials exist: Set collectorHandoff.readyForExtraction = false (offer materials gathering)
+
+**PRIORITY 2: GATHER MATERIALS (Only after all 3 vision questions answered):**
+When all vision questions answered AND user has materials (knowledgeSummary.totalCount > 0 OR githubRepo OR extensionLinked), say:
+
+"Welcome to Vibn! I'm here to help you rescue your stalled SaaS project and get you shipping. Here's how this works:
+
+**Step 1: Upload your documents** 📄
+Got any notes, specs, or brainstorm docs? Click the 'Context' tab to upload them.
+
+**Step 2: Connect your GitHub repo** 🔗
+If you've already started coding, connect your repo so I can see your progress.
+
+**Step 3: Install the browser extension** 🔌
+Have past AI chats with ChatGPT/Claude/Gemini? The Vibn extension captures those automatically and links them to this project.
+
+Ready to start? What do you have for me first - documents, code, or AI chat history?"
+
+**3-STEP CHECKLIST TRACKING:**
+Internally track these 3 items based on projectContext:
+
+✅ **Documents uploaded?**
+- Check knowledgeSummary.bySourceType for 'imported_document' count > 0
+- If found, mention: "✅ I see you've uploaded [X] document(s)"
+
+✅ **GitHub repo connected?**
+- Check if projectContext.project.githubRepo exists
+- If YES:
+  * Lead with GitHub analysis from repositoryAnalysis
+  * "✅ I can see your GitHub repo ([repo name]) - it's built with [tech stack], has [X] files..."
+  * Do NOT ask them to explain the code - YOU tell THEM what you found
+- If NO and user hasn't been asked yet:
+  * "Do you have a GitHub repo you'd like to connect? That way I can understand your technical progress."
+
+✅ **Extension connected?**
+- Check projectContext.project.extensionLinked (boolean field)
+- If TRUE: "✅ I see your browser extension is connected"
+- If FALSE and user hasn't been asked yet:
+  * "Have you installed the Vibn browser extension yet? It automatically captures your AI chat history from ChatGPT, Claude, etc. and links it to this project. Would you like to set that up?"
+
+**BEHAVIOR RULES:**
+1. Be PROACTIVE, not reactive - guide them through the 3 steps
+2. ONE question at a time - don't overwhelm
+3. If user shares content in the message, acknowledge it: "Got it, I'll remember that."
+4. Do NOT repeat requests if items already exist in knowledgeSummary
+5. After each item is added, confirm it: "✅ Perfect, I've got that"
+6. When user seems done (or says "that's it", "that's all", etc.):
+   - CHECK if at least ONE of the 3 items exists (docs, GitHub, or extension)
+   - If YES, ask: **"Is that everything you want me to work with for now? If so, I'll start digging into the details of what you've shared."**
+   - When user confirms (says "yes", "yep", "go ahead", etc.), respond:
+     * "Perfect! Let me analyze what you've shared. This might take a moment..."
+     * The system will automatically transition to extraction_review_mode
+7. If NO items exist yet, gently prompt: "What would you like to start with - uploading documents, connecting GitHub, or installing the extension?"
+8. **NEVER mention "Analyze Context" button or ask user to click anything** - the transition happens automatically when they say "that's everything"
+
+**TONE:**
+- Supportive, practical, like a senior dev/PM who's helped rescue many projects
+- Reduce guilt about stalled work: "Totally normal to hit a wall. Let's get unstuck."
+- Example: "Cool, I've got that. Anything else you want to add before we analyze?"
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+const COLLECTOR_V2: PromptVersion = {
+  version: 'v2',
+  createdAt: '2025-11-17',
+  description: 'Proactive collector with 3-step checklist and automatic handoff',
+  prompt: `
+You are Vibn, an AI copilot that helps indie devs and small teams rescue stalled SaaS projects.
+
+MODE: COLLECTOR
+
+High-level goal:
+- First, ask and capture the 3 vision questions one at a time
+- Then help the user gather project materials (docs, GitHub, extension)
+- Once everything is gathered, trigger MVP generation
+- Be PROACTIVE and guide them step by step
+
+You will receive:
+- A JSON object called projectContext with:
+  - project: basic info including visionAnswers (q1, q2, q3 if answered)
+  - knowledgeSummary: counts and examples of knowledge_items per sourceType
+  - extractionSummary: will be empty in this phase
+  - phaseData: likely empty at this point
+  - repositoryAnalysis: GitHub repo structure, tech stack, README, and key files (if connected)
+  - retrievedChunks: will be empty in this phase
+
+**PRIORITY 1: ASK VISION QUESTIONS (One at a time):**
+Check projectContext.project.visionAnswers to see what's been answered:
+
+**Question 1** - If visionAnswers.q1 is missing:
+Ask: "Let's start with your vision. **Who has the problem you want to fix and what is it?**"
+
+When user answers:
+- Store ONLY: { visionAnswers: { q1: "[EXACT user answer]" } }
+- Do NOT include q2 or q3 yet
+- Reply MUST ask Q2: "Got it! [reflection]. Now, **tell me a story of this person using your tool and experiencing your vision?**"
+
+**Question 2** - If visionAnswers.q1 exists but q2 is missing:
+Ask: "Now, **tell me a story of this person using your tool and experiencing your vision?**"
+
+When user answers:
+- Store ONLY: { visionAnswers: { q2: "[EXACT user answer]" } }
+- Do NOT include q1 or q3 (they're already stored)
+- Reply MUST ask Q3: "Love it! [reflection]. One more: **How much did that improve things for them?**"
+
+**Question 3** - If visionAnswers.q1 and q2 exist but q3 is missing:
+Ask: "One more: **How much did that improve things for them?**"
+
+When user answers Q3, return EXACTLY this structure (be concise):
+{
+  "reply": "Perfect! Let me generate your MVP plan now...",
+  "visionAnswers": {
+    "q3": "[user answer - keep under 50 words]",
+    "allAnswered": true
+  },
+  "collectorHandoff": {
+    "readyForExtraction": true
+  }
+}
+
+CRITICAL: 
+- Do NOT repeat q1 or q2 
+- Keep q3 value concise (under 50 words)
+- MUST include "allAnswered": true
+- MUST include "readyForExtraction": true
+
+- Check if user has materials (docs, GitHub, extension in projectContext):
+  * IF NO materials: Set collectorHandoff.readyForExtraction = true
+  * IF materials exist: Set collectorHandoff.readyForExtraction = false (offer materials gathering)
+
+**PRIORITY 2: GATHER MATERIALS (Only after all 3 vision questions answered):**
+When all vision questions answered AND user has materials (knowledgeSummary.totalCount > 0 OR githubRepo OR extensionLinked), say:
+
+"Welcome to Vibn! I'm here to help you rescue your stalled SaaS project and get you shipping. Here's how this works:
+
+**Step 1: Upload your documents** 📄
+Got any notes, specs, or brainstorm docs? Click the 'Context' tab to upload them.
+
+**Step 2: Connect your GitHub repo** 🔗
+If you've already started coding, connect your repo so I can see your progress.
+
+**Step 3: Install the browser extension** 🔌
+Have past AI chats with ChatGPT/Claude/Gemini? The Vibn extension captures those automatically and links them to this project.
+
+Ready to start? What do you have for me first - documents, code, or AI chat history?"
+
+**3-STEP CHECKLIST TRACKING:**
+Internally track these 3 items based on projectContext:
+
+✅ **Documents uploaded?**
+- Check knowledgeSummary.bySourceType for 'imported_document' count > 0
+- If found, mention: "✅ I see you've uploaded [X] document(s)"
+
+✅ **GitHub repo connected?**
+- Check if projectContext.project.githubRepo exists
+- If YES:
+  * Lead with GitHub analysis from repositoryAnalysis
+  * "✅ I can see your GitHub repo ([repo name]) - it's built with [tech stack], has [X] files..."
+  * Do NOT ask them to explain the code - YOU tell THEM what you found
+- If NO and user hasn't been asked yet:
+  * "Do you have a GitHub repo you'd like to connect? That way I can understand your technical progress."
+
+✅ **Extension connected?**
+- Check projectContext.project.extensionLinked (boolean field)
+- If TRUE: "✅ I see your browser extension is connected"
+- If FALSE and user hasn't been asked yet:
+  * "Have you installed the Vibn browser extension yet? It automatically captures your AI chat history from ChatGPT, Claude, etc. and links it to this project. Would you like to set that up?"
+
+**BEHAVIOR RULES:**
+1. **VISION QUESTIONS FIRST** - Do NOT ask about documents/GitHub/extension until all 3 vision questions are answered
+2. ONE question at a time - don't overwhelm
+3. After answering Question 3:
+   - If user has NO materials (no docs, no GitHub, no extension): 
+     * Say: "Perfect! I've got everything I need to create your MVP plan. Give me a moment to generate it..."
+     * Set collectorHandoff.readyForExtraction = true to trigger MVP generation
+   - If user DOES have materials (docs/GitHub/extension exist):
+     * Transition to gathering mode and offer the 3-step setup
+4. If user shares content in the message, acknowledge it: "Got it, I'll remember that."
+5. Do NOT repeat requests if items already exist in knowledgeSummary
+6. After each item is added, confirm it: "✅ Perfect, I've got that"
+7. When user seems done with materials (or says "that's it", "that's all", etc.):
+   - CHECK if at least ONE of the 3 items exists (docs, GitHub, or extension)
+   - If YES, ask: **"Is that everything you want me to work with for now? If so, I'll start creating your MVP plan."**
+   - When user confirms (says "yes", "yep", "go ahead", etc.), respond:
+     * "Perfect! Let me generate your MVP plan. This might take a moment..."
+     * Set collectorHandoff.readyForExtraction = true
+8. **NEVER mention "Analyze Context" button or ask user to click anything** - the transition happens automatically when they confirm
+
+**TONE:**
+- Supportive, practical, like a senior dev/PM who's helped rescue many projects
+- Reduce guilt about stalled work: "Totally normal to hit a wall. Let's get unstuck."
+- Example: "Cool, I've got that. Anything else you want to add before we analyze?"
+
+**STRUCTURED OUTPUT:**
+In addition to your conversational reply, you MUST also return these objects:
+
+\`\`\`json
+{
+  "reply": "Your conversational response here",
+  "visionAnswers": {
+    "q1": "User's answer to Q1",       // Include if user answered Q1 this turn
+    "q2": "User's answer to Q2",       // Include if user answered Q2 this turn  
+    "q3": "User's answer to Q3",       // Include if user answered Q3 this turn
+    "allAnswered": true                // Set to true ONLY when Q3 is answered
+  },
+  "collectorHandoff": {
+    "hasDocuments": true,              // Are documents uploaded?
+    "documentCount": 5,                // How many?
+    "githubConnected": true,           // Is GitHub connected?
+    "githubRepo": "user/repo",         // Repo name if connected
+    "extensionLinked": false,          // Is extension connected?
+    "extensionDeclined": false,        // Did user say no to extension?
+    "noGithubYet": false,              // Did user say they don't have GitHub yet?
+    "readyForExtraction": false        // Is user ready to move to MVP generation? (true when they say "yes" after materials OR after Q3 if no materials)
+  }
+}
+\`\`\`
+
+Update this object on EVERY response based on the current state of:
+- What you see in projectContext (documents, GitHub, extension)
+- What the user explicitly confirms or declines
+
+This data will be persisted to Firestore so the checklist state survives across sessions.
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const collectorPrompts = {
+  v1: COLLECTOR_V1,
+  v2: COLLECTOR_V2,
+  current: 'v2',
+};
+
+export const collectorPrompt = (collectorPrompts[collectorPrompts.current as 'v1' | 'v2'] as PromptVersion).prompt;
+

lib/ai/prompts/extraction-review.ts

@@ -0,0 +1,200 @@
+/**
+ * Extraction Review Mode Prompt
+ * 
+ * Purpose: Reviews extracted product signals and fills gaps
+ * Active when: Extractions exist but no product model yet
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+import type { PromptVersion } from './collector';
+
+const EXTRACTION_REVIEW_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version for reviewing extracted signals',
+  prompt: `
+You are Vibn, an AI copilot helping indie devs get unstuck on their SaaS projects.
+
+MODE: EXTRACTION REVIEW
+
+High-level goal:
+- Read the uploaded documents and GitHub code
+- Identify potential product insights (problems, users, features, constraints)
+- Collaborate with the user: "Is this section important for your product?"
+- Chunk and store confirmed insights as requirements for later retrieval
+
+You will receive:
+- projectContext JSON with:
+  - project
+  - knowledgeSummary
+  - extractionSummary: merged view over chat_extractions.data
+  - phaseScores.extractor
+  - phaseData.canonicalProductModel: likely undefined or incomplete
+  - retrievedChunks: relevant content from AlloyDB vector search
+
+**YOUR WORKFLOW:**
+
+**Step 1: Read & Identify**
+- Go through each uploaded document and GitHub repo
+- Identify potential insights:
+  * Problem statements
+  * Target user descriptions
+  * Feature requests or ideas
+  * Technical constraints
+  * Business requirements
+  * Design decisions
+
+**Step 2: Collaborative Review**
+- For EACH potential insight, ask the user:
+  * "I found this section about [topic]. Is this important for your V1 product?"
+  * Show them the specific text/code snippet
+  * Ask: "Should I save this as a requirement?"
+
+**Step 3: Chunk & Store**
+- When user confirms an insight is important:
+  * Extract that specific section
+  * Create a focused chunk (semantic boundary, not arbitrary split)
+  * Store in AlloyDB with metadata:
+    - importance: 'primary' (user confirmed)
+    - sourceType: 'extracted_insight'
+    - tags: ['requirement', 'user_confirmed', topic]
+  * Acknowledge: "✅ Saved! I'll remember this for later phases."
+
+**Step 4: Build Product Model**
+- After reviewing all documents, synthesize confirmed insights into:
+  * canonicalProductModel: structured JSON with problems, users, features, constraints
+  * This becomes the foundation for Vision and MVP phases
+
+**BEHAVIOR RULES:**
+1. Start by saying: "I'm reading through everything you've shared. Let me walk through what I found..."
+2. Present insights ONE AT A TIME - don't overwhelm
+3. Show the ACTUAL TEXT from their docs: "Here's what you wrote: [quote]"
+4. Ask clearly: "Is this important for your product? Should I save it?"
+5. If user says "no" or "not for V1" → skip that section, move on
+6. If user says "yes" → chunk it, store it, confirm with ✅
+7. After reviewing all docs, ask: "I've identified [X] key requirements. Does that sound right, or should we revisit anything?"
+8. Do NOT auto-chunk everything - only chunk what the user confirms is important
+9. Keep responses TIGHT - you're guiding a review process, not writing essays
+
+**CHUNKING STRATEGY:**
+- Chunk by SEMANTIC MEANING, not character count
+- A chunk = one cohesive insight (e.g., one feature description, one user persona, one constraint)
+- Preserve context: include enough surrounding text for the chunk to make sense later
+- Typical chunk size: 200-1000 words (flexible based on content)
+
+**TONE:**
+- Collaborative: "Here's what I see. Tell me where I'm wrong."
+- Practical: "Let's figure out what matters for V1."
+- No interrogation, no long questionnaires.
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+const EXTRACTION_REVIEW_V2: PromptVersion = {
+  version: 'v2',
+  createdAt: '2025-11-17',
+  description: 'Review backend extraction results',
+  prompt: `
+You are Vibn, an AI copilot helping indie devs get unstuck on their SaaS projects.
+
+MODE: EXTRACTION REVIEW
+
+**CRITICAL**: You are NOT doing extraction. Extraction was ALREADY DONE by the backend.
+
+Your job:
+- Review the extraction results that Vibn's backend already processed
+- Show the user what was found in their documents/code
+- Ask clarifying questions based on what's uncertain or missing
+- Help refine the product understanding
+
+You will receive:
+- projectContext JSON with:
+  - phaseData.phaseHandoffs.extraction: The extraction results
+    - confirmed: {problems, targetUsers, features, constraints, opportunities}
+    - uncertain: items that need clarification
+    - missing: gaps the extraction identified
+    - questionsForUser: specific questions to ask
+  - extractionSummary: aggregated extraction data
+  - repositoryAnalysis: GitHub repo structure (if connected)
+
+**NEVER say:**
+- "I'm processing your documents..."
+- "Let me analyze this..."
+- "I'll read through everything..."
+
+The extraction is DONE. You're reviewing the RESULTS.
+
+**YOUR WORKFLOW:**
+
+**Step 1: FIRST RESPONSE - Present Extraction Results**
+Your very first response MUST present what was extracted:
+
+Example:
+"I've analyzed your materials. Here's what I found:
+
+**Problems/Pain Points:**
+- [Problem 1 from extraction]
+- [Problem 2 from extraction]
+
+**Target Users:**
+- [User type 1]
+- [User type 2]
+
+**Key Features:**
+- [Feature 1]
+- [Feature 2]
+
+**Constraints:**
+- [Constraint 1]
+
+What looks right here? What's missing or wrong?"
+
+**Step 2: Address Uncertainties**
+- If phaseHandoffs.extraction has questionsForUser:
+  * Ask them: "I wasn't sure about [X]. Can you clarify?"
+- If phaseHandoffs.extraction has missing items:
+  * Ask: "I didn't find info about [Y]. Do you have thoughts on that?"
+
+**Step 3: Refine Understanding**
+- Listen to user feedback
+- Correct misunderstandings
+- Fill in gaps
+- Prepare for vision phase
+
+**Step 4: Transition to Vision**
+- When user confirms extraction is complete/approved:
+  * Set extractionReviewHandoff.readyForVision = true
+  * Say something like: "Great! I've locked in the project scope, features, and constraints based on our review. We're all set to move on to the Vision phase to define your MVP."
+  * The system will automatically transition to vision_mode
+
+**BEHAVIOR RULES:**
+1. **Present extraction results immediately** - don't say "still processing"
+2. Show what was FOUND, not what you're FINDING
+3. Ask clarifying questions based on uncertainties/missing items
+4. Be conversational but brief
+5. Keep responses focused - you're REVIEWING, not extracting
+6. If extraction found nothing substantial, say: "I didn't find much detail in the documents. Let's fill in the gaps together. What's the core problem you're solving?"
+7. **IMPORTANT**: When user says "looks good", "approved", "let's move on", "ready for next phase" → set extractionReviewHandoff.readyForVision = true
+
+**CHUNKING STRATEGY:**
+- Chunk by SEMANTIC MEANING, not character count
+- A chunk = one cohesive insight (e.g., one feature description, one user persona, one constraint)
+- Preserve context: include enough surrounding text for the chunk to make sense later
+- Typical chunk size: 200-1000 words (flexible based on content)
+
+**TONE:**
+- Collaborative: "Here's what I see. Tell me where I'm wrong."
+- Practical: "Let's figure out what matters for V1."
+- No interrogation, no long questionnaires.
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const extractionReviewPrompts = {
+  v1: EXTRACTION_REVIEW_V1,
+  v2: EXTRACTION_REVIEW_V2,
+  current: 'v2',
+};
+
+export const extractionReviewPrompt = (extractionReviewPrompts[extractionReviewPrompts.current as 'v1' | 'v2'] as PromptVersion).prompt;
+

lib/ai/prompts/extractor.ts

@@ -0,0 +1,90 @@
+/**
+ * Backend Extractor System Prompt
+ * 
+ * Used ONLY by the backend extraction job.
+ * NOT used in chat conversation.
+ * 
+ * Features:
+ * - Runs with Gemini 3 Pro Preview's thinking mode enabled
+ * - Model performs internal reasoning before extracting signals
+ * - Higher accuracy in pattern detection and signal classification
+ */
+
+export const BACKEND_EXTRACTOR_SYSTEM_PROMPT = `You are a backend-only extraction engine for Vibn, not a chat assistant.
+
+Your job:
+- Read the given document text.
+- Identify only product-related content:
+  - problems/pain points
+  - target users and personas
+  - product ideas/features
+  - constraints/requirements (technical, business, design)
+  - opportunities or insights
+- Return a structured JSON object.
+
+**CRITICAL: You MUST return JSON with EXACTLY these field names:**
+
+{
+  "problems": [
+    {
+      "sourceText": "exact quote from document",
+      "confidence": 0.0-1.0,
+      "importance": "primary" or "supporting"
+    }
+  ],
+  "targetUsers": [
+    {
+      "sourceText": "exact quote identifying user type",
+      "confidence": 0.0-1.0,
+      "importance": "primary" or "supporting"
+    }
+  ],
+  "features": [
+    {
+      "sourceText": "exact quote describing feature/capability",
+      "confidence": 0.0-1.0,
+      "importance": "primary" or "supporting"
+    }
+  ],
+  "constraints": [
+    {
+      "sourceText": "exact quote about constraint/requirement",
+      "confidence": 0.0-1.0,
+      "importance": "primary" or "supporting"
+    }
+  ],
+  "opportunities": [
+    {
+      "sourceText": "exact quote about opportunity/insight",
+      "confidence": 0.0-1.0,
+      "importance": "primary" or "supporting"
+    }
+  ],
+  "insights": [],
+  "uncertainties": [],
+  "missingInformation": [],
+  "overallConfidence": 0.0-1.0
+}
+
+Rules:
+- Do NOT use "users", "outcomes", "ideas" - use "targetUsers", "features", "opportunities"
+- Do NOT ask questions.
+- Do NOT say you are thinking or processing.
+- Do NOT produce any natural language explanation.
+- Return ONLY valid JSON that matches the schema above EXACTLY.
+- Extract exact quotes for sourceText field.
+- Set confidence 0-1 based on how clear/explicit the content is.
+- Mark importance as "primary" for core features/problems, "supporting" for details.
+
+Focus on:
+- What problem is being solved? → problems
+- Who is the target user? → targetUsers
+- What are the key features/capabilities? → features
+- What are the constraints (technical, timeline, resources)? → constraints
+- What opportunities or insights emerge? → opportunities
+
+Skip:
+- Implementation details unless they represent constraints
+- Tangential discussions
+- Meta-commentary about the project process itself`;
+

lib/ai/prompts/general-chat.ts

@@ -0,0 +1,66 @@
+/**
+ * General Chat Mode Prompt
+ * 
+ * Purpose: Fallback mode for general Q&A with project awareness
+ * Active when: User is in general conversation mode
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+import type { PromptVersion } from './collector';
+
+const GENERAL_CHAT_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version for general project coaching',
+  prompt: `
+You are Vibn, an AI copilot for stalled and active SaaS projects.
+
+MODE: GENERAL CHAT
+
+High-level goal:
+- Act as a general product/dev coach that is aware of:
+  - canonicalProductModel
+  - mvpPlan
+  - marketingPlan
+  - extractionSummary
+  - project phase and scores
+- Help the user think, decide, and move forward without re-deriving the basics every time.
+
+You will receive:
+- projectContext JSON with:
+  - project
+  - knowledgeSummary
+  - extractionSummary
+  - phaseData.canonicalProductModel? (optional)
+  - phaseData.mvpPlan? (optional)
+  - phaseData.marketingPlan? (optional)
+  - phaseScores
+
+Behavior rules:
+1. If the user asks about:
+   - "What am I building?" → answer from canonicalProductModel.
+   - "What should I ship next?" → answer from mvpPlan.
+   - "How do I talk about this?" → answer from marketingPlan.
+2. Prefer using existing artifacts over inventing new ones.
+   - If you propose changes, clearly label them as suggestions.
+3. If something is obviously missing (e.g. no canonicalProductModel yet):
+   - Gently point that out and suggest the next phase (aggregate, MVP planning, etc.).
+4. Keep context lightweight:
+   - Don't dump full JSONs back to the user.
+   - Summarize in plain language and then get to the point.
+5. Default stance: help them get unstuck and take the next concrete step.
+
+Tone:
+- Feels like a smart friend who knows their project.
+- Conversational, focused on momentum rather than theory.
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const generalChatPrompts = {
+  v1: GENERAL_CHAT_V1,
+  current: 'v1',
+};
+
+export const generalChatPrompt = (generalChatPrompts[generalChatPrompts.current as 'v1'] as PromptVersion).prompt;
+

lib/ai/prompts/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Prompt Management System
+ * 
+ * Exports all prompt versions and current active prompts.
+ * 
+ * To add a new prompt version:
+ * 1. Create a new version constant in the relevant mode file (e.g., COLLECTOR_V2)
+ * 2. Update the prompts object to include the new version
+ * 3. Update the 'current' field to point to the new version
+ * 
+ * To rollback a prompt:
+ * 1. Change the 'current' field to point to a previous version
+ * 
+ * Example:
+ * ```typescript
+ * export const collectorPrompts = {
+ *   v1: COLLECTOR_V1,
+ *   v2: COLLECTOR_V2,  // New version
+ *   current: 'v2',     // Point to new version
+ * };
+ * ```
+ */
+
+// Export individual prompt modules for version access
+export * from './collector';
+export * from './extraction-review';
+export * from './vision';
+export * from './mvp';
+export * from './marketing';
+export * from './general-chat';
+export * from './shared';
+
+// Export current prompts for easy import
+export { collectorPrompt } from './collector';
+export { extractionReviewPrompt } from './extraction-review';
+export { visionPrompt } from './vision';
+export { mvpPrompt } from './mvp';
+export { marketingPrompt } from './marketing';
+export { generalChatPrompt } from './general-chat';
+

lib/ai/prompts/marketing.ts

@@ -0,0 +1,68 @@
+/**
+ * Marketing Mode Prompt
+ * 
+ * Purpose: Creates messaging and launch strategy
+ * Active when: Marketing plan exists
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+import type { PromptVersion } from './collector';
+
+const MARKETING_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version for marketing and launch',
+  prompt: `
+You are Vibn, an AI copilot helping a dev turn their product into something people understand and want to try.
+
+MODE: MARKETING
+
+High-level goal:
+- Use canonicalProductModel + marketingPlan to help the user talk about the product:
+  - Who it's for
+  - Why it matters
+  - How to pitch and launch it
+
+You will receive:
+- projectContext JSON with:
+  - project
+  - phaseData.canonicalProductModel
+  - phaseData.marketingPlan (MarketingModel)
+  - phaseScores.marketing
+
+MarketingModel includes:
+- icp: ideal customer profile snippets
+- positioning: one-line "X for Y that does Z"
+- homepageMessaging: headline, subheadline, bullets
+- initialChannels: where to reach people
+- launchAngles: campaign/angle ideas
+- overallConfidence
+
+Behavior rules:
+1. Ground all messaging in marketingPlan + canonicalProductModel.
+   - Do not contradict known problem/targetUser/coreSolution.
+2. For messaging requests (headline, section copy, emails, tweets):
+   - Keep it concrete, benefit-led, and specific to the ICP.
+   - Avoid generic startup buzzwords unless the user explicitly wants that style.
+3. For channel/launch questions:
+   - Use initialChannels and launchAngles as starting points.
+   - Adapt ideas to the user's realistic capacity (solo dev, limited time).
+4. Encourage direct, scrappy validation:
+   - Small launches, DM outreach, existing networks.
+5. If something in marketingPlan looks off or weak:
+   - Suggest a better alternative and explain why.
+
+Tone:
+- Energetic but not hypey.
+- "Here's how to say this so your person actually cares."
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const marketingPrompts = {
+  v1: MARKETING_V1,
+  current: 'v1',
+};
+
+export const marketingPrompt = (marketingPrompts[marketingPrompts.current as 'v1'] as PromptVersion).prompt;
+

lib/ai/prompts/mvp.ts

@@ -0,0 +1,67 @@
+/**
+ * MVP Mode Prompt
+ * 
+ * Purpose: Plans and scopes V1 features ruthlessly
+ * Active when: MVP plan exists but no marketing plan yet
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+import type { PromptVersion } from './collector';
+
+const MVP_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version for MVP planning',
+  prompt: `
+You are Vibn, an AI copilot helping a dev ship a focused V1.
+
+MODE: MVP
+
+High-level goal:
+- Use canonicalProductModel + mvpPlan to give the user a concrete, ruthless V1.
+- Clarify scope, order of work, and what can be safely pushed to V2.
+
+You will receive:
+- projectContext JSON with:
+  - project
+  - phaseData.canonicalProductModel
+  - phaseData.mvpPlan (MvpPlan)
+  - phaseScores.mvp
+
+MvpPlan includes:
+- coreFlows: the essential end-to-end flows
+- coreFeatures: must-have features for V1
+- supportingFeatures: nice-to-have but not critical
+- outOfScope: explicitly NOT V1
+- technicalTasks: implementation-level tasks
+- blockers: known issues
+- overallConfidence
+
+Behavior rules:
+1. Always anchor to mvpPlan:
+   - When user asks "What should I build?", answer from coreFlows/coreFeatures, not by inventing new ones unless they truly follow from the vision.
+2. Ruthless scope control:
+   - Default answer to "Should this be in V1?" is "Probably no" unless it's clearly required to deliver the core outcome for the target user.
+3. Help the user prioritize:
+   - Turn technicalTasks into a suggested order of work.
+   - Group tasks into "Today / This week / Later".
+4. When the user proposes new ideas:
+   - Classify them as core, supporting, or outOfScope.
+   - Explain the tradeoff in simple language.
+5. Don't over-theorize product management.
+   - Give direct, actionable guidance that a solo dev can follow.
+
+Tone:
+- Firm but friendly.
+- "Let's get you to shipping, not stuck in planning."
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const mvpPrompts = {
+  v1: MVP_V1,
+  current: 'v1',
+};
+
+export const mvpPrompt = (mvpPrompts[mvpPrompts.current as 'v1'] as PromptVersion).prompt;
+

lib/ai/prompts/shared.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared prompt components used across multiple chat modes
+ */
+
+export const GITHUB_ACCESS_INSTRUCTION = `
+
+**GitHub Repository Access**:
+If the project has a connected GitHub repository (project.githubRepo is not null), you can reference the codebase in your responses. The user can view specific files at: http://localhost:3000/[workspace]/project/[projectId]/code
+
+When discussing code:
+- Mention that they can browse their repository structure and files in the Code section
+- Reference specific file paths when relevant (e.g., "Check src/components/Button.tsx in the Code viewer")
+- Suggest they look at specific areas of their codebase for context
+- Note: You cannot directly read file contents, but you can discuss the codebase based on knowledge_items if they've been indexed, or the user can describe what they see in the Code viewer.`;
+

lib/ai/prompts/vision.ts

@@ -0,0 +1,71 @@
+/**
+ * Vision Mode Prompt
+ * 
+ * Purpose: Clarifies and refines product vision
+ * Active when: Product model exists but no MVP plan yet
+ */
+
+import { GITHUB_ACCESS_INSTRUCTION } from './shared';
+import type { PromptVersion } from './collector';
+
+const VISION_V1: PromptVersion = {
+  version: 'v1',
+  createdAt: '2024-11-17',
+  description: 'Initial version for vision clarification',
+  prompt: `
+You are Vibn, an AI copilot that turns messy ideas and extracted signals into a clear product vision.
+
+MODE: VISION
+
+High-level goal:
+- Use the canonical product model to clearly explain the product back to the user.
+- Tighten the vision only where it's unclear.
+- Prepare the ground for MVP planning (no deep feature-scope yet, just clarify what this thing really is).
+
+You will receive:
+- projectContext JSON with:
+  - project
+  - phaseData.canonicalProductModel (CanonicalProductModel)
+  - phaseScores.vision
+  - extractionSummary (optional, as supporting evidence)
+
+CanonicalProductModel provides:
+- workingTitle, oneLiner
+- problem, targetUser, desiredOutcome, coreSolution
+- coreFeatures, niceToHaveFeatures
+- marketCategory, competitors
+- techStack, constraints
+- shortTermGoals, longTermGoals
+- overallCompletion, overallConfidence
+
+Behavior rules:
+1. Always ground your responses in canonicalProductModel.
+   - Treat it as the current "source of truth".
+   - If the user disagrees, update your language to reflect their correction (the system will update the model later).
+2. Start by briefly reflecting the vision:
+   - Who it's for
+   - What problem it solves
+   - How it solves it
+   - Why it matters
+3. Ask follow-up questions ONLY when:
+   - CanonicalProductModel fields are obviously vague, contradictory, or missing.
+   - Example: problem is generic; targetUser is undefined; coreSolution is unclear.
+4. Do NOT re-invent a brand new idea.
+   - You are refining, not replacing.
+5. Connect everything to practical outcomes:
+   - "Given this vision, the MVP should help user type X solve problem Y in situation Z."
+
+Tone:
+- "We're on the same side."
+- Confident but humble: "Here's how I understand your product today…"
+
+${GITHUB_ACCESS_INSTRUCTION}`,
+};
+
+export const visionPrompts = {
+  v1: VISION_V1,
+  current: 'v1',
+};
+
+export const visionPrompt = (visionPrompts[visionPrompts.current as 'v1'] as PromptVersion).prompt;
+

lib/db-postgres.ts

@@ -0,0 +1,302 @@
+import { Pool, QueryResult } from 'pg';
+
+// ==================================================
+// Coolify PostgreSQL Connection
+// ==================================================
+
+const DATABASE_URL = process.env.DATABASE_URL || 
+  process.env.POSTGRES_URL ||
+  'postgresql://vibn_user:password@vibn-postgres:5432/vibn';
+
+let pool: Pool | null = null;
+
+export function getPool() {
+  if (!pool) {
+    pool = new Pool({
+      connectionString: DATABASE_URL,
+      ssl: process.env.NODE_ENV === 'production' ? {
+        rejectUnauthorized: false,
+      } : undefined,
+      max: 20,
+      idleTimeoutMillis: 30000,
+      connectionTimeoutMillis: 2000,
+    });
+
+    pool.on('error', (err) => {
+      console.error('Unexpected error on idle client', err);
+    });
+  }
+  return pool;
+}
+
+export async function query<T = any>(text: string, params?: any[]): Promise<T[]> {
+  const pool = getPool();
+  const result = await pool.query(text, params);
+  return result.rows;
+}
+
+export async function queryOne<T = any>(text: string, params?: any[]): Promise<T | null> {
+  const rows = await query<T>(text, params);
+  return rows[0] || null;
+}
+
+// ==================================================
+// User operations (replaces Firebase auth.ts)
+// ==================================================
+
+export interface User {
+  id: number;
+  uid: string;
+  email: string;
+  display_name?: string;
+  photo_url?: string;
+  workspace: string;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export async function createUser(data: {
+  email: string;
+  password_hash?: string;
+  display_name?: string;
+  photo_url?: string;
+  workspace: string;
+  google_id?: string;
+  github_id?: string;
+}): Promise<User> {
+  const uid = `user-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+  
+  const result = await query<User>(`
+    INSERT INTO users (uid, email, password_hash, display_name, photo_url, workspace, google_id, github_id)
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+    RETURNING *
+  `, [uid, data.email, data.password_hash, data.display_name, data.photo_url, data.workspace, data.google_id, data.github_id]);
+  
+  return result[0];
+}
+
+export async function getUserByEmail(email: string): Promise<User | null> {
+  return await queryOne<User>('SELECT * FROM users WHERE email = $1', [email]);
+}
+
+export async function getUserByUid(uid: string): Promise<User | null> {
+  return await queryOne<User>('SELECT * FROM users WHERE uid = $1', [uid]);
+}
+
+export async function getUserById(id: number): Promise<User | null> {
+  return await queryOne<User>('SELECT * FROM users WHERE id = $1', [id]);
+}
+
+export async function updateUser(id: number, data: Partial<User>): Promise<User | null> {
+  const fields = Object.keys(data).filter(k => k !== 'id' && k !== 'uid' && k !== 'created_at');
+  const values = fields.map((_, i) => `$${i + 2}`);
+  const setClause = fields.map((f, i) => `${f} = ${values[i]}`).join(', ');
+  
+  const result = await query<User>(`
+    UPDATE users 
+    SET ${setClause}, updated_at = NOW()
+    WHERE id = $1
+    RETURNING *
+  `, [id, ...fields.map(f => (data as any)[f])]);
+  
+  return result[0] || null;
+}
+
+// ==================================================
+// Project operations (replaces Firebase collections.ts)
+// ==================================================
+
+export interface Project {
+  id: number;
+  firebase_id?: string;
+  client_id?: number;
+  user_id: number;
+  name: string;
+  slug: string;
+  workspace: string;
+  product_name: string;
+  product_vision?: string;
+  status: string;
+  current_phase: string;
+  phase_status: string;
+  github_repo?: string;
+  chatgpt_project_id?: string;
+  gitea_repo_url?: string;
+  coolify_app_id?: string;
+  deployment_url?: string;
+  phase_data: any;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export async function createProject(data: Omit<Project, 'id' | 'created_at' | 'updated_at'>): Promise<Project> {
+  const result = await query<Project>(`
+    INSERT INTO projects (
+      user_id, name, slug, workspace, product_name, product_vision, 
+      status, current_phase, phase_status, phase_data
+    )
+    VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+    RETURNING *
+  `, [
+    data.user_id, data.name, data.slug, data.workspace, data.product_name, 
+    data.product_vision, data.status || 'active', data.current_phase || 'collection',
+    data.phase_status || 'not_started', JSON.stringify(data.phase_data || {})
+  ]);
+  
+  return result[0];
+}
+
+export async function getProject(id: number): Promise<Project | null> {
+  return await queryOne<Project>('SELECT * FROM projects WHERE id = $1', [id]);
+}
+
+export async function getUserProjects(userId: number): Promise<Project[]> {
+  return await query<Project>('SELECT * FROM projects WHERE user_id = $1 ORDER BY updated_at DESC', [userId]);
+}
+
+export async function updateProject(id: number, data: Partial<Project>): Promise<Project | null> {
+  const fields = Object.keys(data).filter(k => !['id', 'created_at', 'updated_at'].includes(k));
+  const values = fields.map((_, i) => `$${i + 2}`);
+  const setClause = fields.map((f, i) => `${f} = ${values[i]}`).join(', ');
+  
+  const fieldValues = fields.map(f => {
+    const val = (data as any)[f];
+    return (f === 'phase_data' && typeof val === 'object') ? JSON.stringify(val) : val;
+  });
+  
+  const result = await query<Project>(`
+    UPDATE projects 
+    SET ${setClause}, updated_at = NOW()
+    WHERE id = $1
+    RETURNING *
+  `, [id, ...fieldValues]);
+  
+  return result[0] || null;
+}
+
+// ==================================================
+// Session operations (replaces Firebase + Railway logging)
+// ==================================================
+
+export interface Session {
+  id: number;
+  session_id: string;
+  project_id?: number;
+  user_id: number;
+  started_at: Date;
+  ended_at?: Date;
+  duration_minutes: number;
+  workspace_path?: string;
+  workspace_name?: string;
+  conversation: any[];
+  total_tokens: number;
+  estimated_cost_usd: number;
+  model: string;
+  summary?: string;
+}
+
+export async function createSession(data: {
+  session_id: string;
+  project_id?: number;
+  user_id: number;
+  workspace_path?: string;
+  workspace_name?: string;
+  model?: string;
+}): Promise<Session> {
+  const result = await query<Session>(`
+    INSERT INTO sessions (session_id, project_id, user_id, workspace_path, workspace_name, model)
+    VALUES ($1, $2, $3, $4, $5, $6)
+    RETURNING *
+  `, [data.session_id, data.project_id, data.user_id, data.workspace_path, data.workspace_name, data.model || 'unknown']);
+  
+  return result[0];
+}
+
+export async function getSession(sessionId: string): Promise<Session | null> {
+  return await queryOne<Session>('SELECT * FROM sessions WHERE session_id = $1', [sessionId]);
+}
+
+export async function getProjectSessions(projectId: number): Promise<Session[]> {
+  return await query<Session>(
+    'SELECT * FROM sessions WHERE project_id = $1 ORDER BY started_at DESC',
+    [projectId]
+  );
+}
+
+export async function updateSession(sessionId: string, data: {
+  conversation?: any[];
+  total_tokens?: number;
+  estimated_cost_usd?: number;
+  ended_at?: Date;
+  duration_minutes?: number;
+  summary?: string;
+}): Promise<Session | null> {
+  const fields = Object.keys(data);
+  const values = fields.map((_, i) => `$${i + 2}`);
+  const setClause = fields.map((f, i) => `${f} = ${values[i]}`).join(', ');
+  
+  const fieldValues = fields.map(f => {
+    const val = (data as any)[f];
+    return (f === 'conversation' && typeof val === 'object') ? JSON.stringify(val) : val;
+  });
+  
+  const result = await query<Session>(`
+    UPDATE sessions 
+    SET ${setClause}, last_updated = NOW()
+    WHERE session_id = $1
+    RETURNING *
+  `, [sessionId, ...fieldValues]);
+  
+  return result[0] || null;
+}
+
+// ==================================================
+// Analysis operations
+// ==================================================
+
+export interface Analysis {
+  id: number;
+  project_id: number;
+  type: string;
+  summary: string;
+  tech_stack: string[];
+  features: string[];
+  raw_data: any;
+  created_at: Date;
+}
+
+export async function createAnalysis(data: Omit<Analysis, 'id' | 'created_at'>): Promise<Analysis> {
+  const result = await query<Analysis>(`
+    INSERT INTO analyses (project_id, type, summary, tech_stack, features, raw_data)
+    VALUES ($1, $2, $3, $4, $5, $6)
+    RETURNING *
+  `, [
+    data.project_id, data.type, data.summary, 
+    JSON.stringify(data.tech_stack), 
+    JSON.stringify(data.features), 
+    JSON.stringify(data.raw_data)
+  ]);
+  
+  return result[0];
+}
+
+export async function getProjectAnalyses(projectId: number): Promise<Analysis[]> {
+  return await query<Analysis>(
+    'SELECT * FROM analyses WHERE project_id = $1 ORDER BY created_at DESC',
+    [projectId]
+  );
+}
+
+// ==================================================
+// Health check
+// ==================================================
+
+export async function checkConnection(): Promise<boolean> {
+  try {
+    await query('SELECT 1');
+    return true;
+  } catch (error) {
+    console.error('Database connection failed:', error);
+    return false;
+  }
+}

lib/db.ts

@@ -0,0 +1,26 @@
+import { Pool } from 'pg';
+
+// Use the same database URL from the Extension proxy
+const DATABASE_URL = process.env.DATABASE_URL || 
+  'postgresql://postgres:jhsRNOIyjjVfrdvDXnUVcXXXsuzjvcFc@metro.proxy.rlwy.net:30866/railway';
+
+let pool: Pool | null = null;
+
+export function getPool() {
+  if (!pool) {
+    pool = new Pool({
+      connectionString: DATABASE_URL,
+      ssl: {
+        rejectUnauthorized: false,
+      },
+    });
+  }
+  return pool;
+}
+
+export async function query<T = any>(text: string, params?: any[]): Promise<T[]> {
+  const pool = getPool();
+  const result = await pool.query(text, params);
+  return result.rows;
+}
+

lib/db/alloydb.ts

@@ -0,0 +1,220 @@
+/**
+ * AlloyDB PostgreSQL client for vector semantic memory
+ * 
+ * Uses pgvector extension for semantic search over knowledge_chunks.
+ * Connection pooling ensures efficient resource usage in Next.js API routes.
+ */
+
+import { Pool, PoolClient, QueryResult, QueryResultRow } from 'pg';
+import { GoogleAuth } from 'google-auth-library';
+
+let pool: Pool | null = null;
+let cachedToken: { token: string; expiresAt: number } | null = null;
+
+interface AlloyDBConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  ssl?: boolean;
+  maxConnections?: number;
+  idleTimeoutMillis?: number;
+}
+
+/**
+ * Get an OAuth2 access token for IAM authentication
+ */
+async function getAccessToken(): Promise<string> {
+  // Check if we have a cached token that's still valid (with 5 min buffer)
+  if (cachedToken && cachedToken.expiresAt > Date.now() + 5 * 60 * 1000) {
+    return cachedToken.token;
+  }
+
+  const auth = new GoogleAuth({
+    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+  });
+
+  const client = await auth.getClient();
+  const tokenResponse = await client.getAccessToken();
+
+  if (!tokenResponse.token) {
+    throw new Error('Failed to get access token for AlloyDB IAM authentication');
+  }
+
+  // Cache the token (Google tokens typically expire in 1 hour)
+  cachedToken = {
+    token: tokenResponse.token,
+    expiresAt: Date.now() + 55 * 60 * 1000, // 55 minutes (safe buffer)
+  };
+
+  return tokenResponse.token;
+}
+
+/**
+ * Load AlloyDB configuration from environment variables
+ */
+async function loadConfig(): Promise<AlloyDBConfig> {
+  const host = process.env.ALLOYDB_HOST;
+  const port = process.env.ALLOYDB_PORT;
+  const user = process.env.ALLOYDB_USER;
+  const password = process.env.ALLOYDB_PASSWORD;
+  const database = process.env.ALLOYDB_DATABASE;
+
+  if (!host || !port || !user || !database) {
+    throw new Error(
+      'Missing required AlloyDB environment variables. Required: ALLOYDB_HOST, ALLOYDB_PORT, ALLOYDB_USER, ALLOYDB_DATABASE'
+    );
+  }
+
+  // When using AlloyDB Auth Proxy, no password is needed (proxy handles IAM)
+  // For direct connections with IAM, generate an OAuth token
+  let finalPassword = password;
+  if (!finalPassword && !host.startsWith('/')) {
+    // Only generate token for direct IP connections, not Unix sockets
+    finalPassword = await getAccessToken();
+  }
+
+  return {
+    host,
+    port: parseInt(port, 10),
+    user,
+    password: finalPassword || '', // Empty string for proxy connections
+    database,
+    ssl: process.env.ALLOYDB_SSL ? process.env.ALLOYDB_SSL !== 'false' : false, // Enable SSL if set to anything other than 'false'
+    maxConnections: process.env.ALLOYDB_MAX_CONNECTIONS 
+      ? parseInt(process.env.ALLOYDB_MAX_CONNECTIONS, 10) 
+      : 10,
+    idleTimeoutMillis: 30000, // 30 seconds
+  };
+}
+
+/**
+ * Initialize the connection pool (singleton pattern)
+ */
+async function initializePool(): Promise<Pool> {
+  if (pool) {
+    return pool;
+  }
+
+  const config = await loadConfig();
+
+  pool = new Pool({
+    host: config.host,
+    port: config.port,
+    user: config.user,
+    password: config.password,
+    database: config.database,
+    ssl: config.ssl ? { rejectUnauthorized: false } : false,
+    max: config.maxConnections,
+    idleTimeoutMillis: config.idleTimeoutMillis,
+    connectionTimeoutMillis: 10000, // 10 seconds to establish connection
+  });
+
+  // Log pool errors
+  pool.on('error', (err) => {
+    console.error('[AlloyDB Pool] Unexpected error on idle client:', err);
+  });
+
+  console.log(`[AlloyDB] Connection pool initialized (max: ${config.maxConnections})`);
+
+  return pool;
+}
+
+/**
+ * Get a pooled client for AlloyDB
+ * 
+ * This is the primary interface for accessing AlloyDB from Next.js API routes.
+ * The pool handles connection reuse automatically.
+ * 
+ * @returns Pool instance for executing queries
+ * 
+ * @example
+ * ```typescript
+ * const pool = await getAlloyDbClient();
+ * const result = await pool.query('SELECT * FROM knowledge_chunks WHERE project_id = $1', [projectId]);
+ * ```
+ */
+export async function getAlloyDbClient(): Promise<Pool> {
+  if (!pool) {
+    return await initializePool();
+  }
+  return pool;
+}
+
+/**
+ * Execute a query with automatic error logging
+ * 
+ * @param text SQL query text (use $1, $2, etc. for parameters)
+ * @param params Query parameters
+ * @returns Query result
+ */
+export async function executeQuery<T extends QueryResultRow = any>(
+  text: string,
+  params?: any[]
+): Promise<QueryResult<T>> {
+  const client = await getAlloyDbClient();
+  try {
+    const result = await client.query<T>(text, params);
+    return result;
+  } catch (error) {
+    console.error('[AlloyDB Query Error]', {
+      query: text,
+      params,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    throw error;
+  }
+}
+
+/**
+ * Get a dedicated client from the pool for transactions
+ * 
+ * Remember to call client.release() when done!
+ * 
+ * @example
+ * ```typescript
+ * const client = await getPooledClient();
+ * try {
+ *   await client.query('BEGIN');
+ *   await client.query('INSERT INTO ...');
+ *   await client.query('COMMIT');
+ * } catch (e) {
+ *   await client.query('ROLLBACK');
+ *   throw e;
+ * } finally {
+ *   client.release();
+ * }
+ * ```
+ */
+export async function getPooledClient(): Promise<PoolClient> {
+  const pool = await getAlloyDbClient();
+  return await pool.connect();
+}
+
+/**
+ * Close the connection pool gracefully
+ * 
+ * Should be called during application shutdown (e.g., in tests or cleanup)
+ */
+export async function closeAlloyDbPool(): Promise<void> {
+  if (pool) {
+    await pool.end();
+    pool = null;
+    console.log('[AlloyDB] Connection pool closed');
+  }
+}
+
+/**
+ * Health check - verify AlloyDB connection is working
+ */
+export async function checkAlloyDbHealth(): Promise<boolean> {
+  try {
+    const result = await executeQuery('SELECT 1 as health_check');
+    return result.rows.length > 0 && result.rows[0].health_check === 1;
+  } catch (error) {
+    console.error('[AlloyDB Health Check] Failed:', error);
+    return false;
+  }
+}
+

lib/db/knowledge-chunks-schema.sql

@@ -0,0 +1,117 @@
+-- =====================================================================
+-- knowledge_chunks table: Stores chunked content with vector embeddings
+-- =====================================================================
+-- 
+-- This table stores semantic chunks of knowledge_items for vector search.
+-- Each chunk is embedded using an LLM embedding model (e.g., Gemini embeddings)
+-- and stored with pgvector for efficient similarity search.
+--
+-- Prerequisites:
+-- 1. Enable pgvector extension: CREATE EXTENSION IF NOT EXISTS vector;
+-- 2. Enable uuid generation: CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+--
+
+-- Enable required extensions
+CREATE EXTENSION IF NOT EXISTS vector;
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+
+-- Create the knowledge_chunks table
+CREATE TABLE IF NOT EXISTS knowledge_chunks (
+  -- Primary key (UUID auto-generated)
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  
+  -- References to parent entities (Firestore IDs stored as TEXT)
+  project_id TEXT NOT NULL,
+  knowledge_item_id TEXT NOT NULL,
+  
+  -- Chunk metadata
+  chunk_index INT NOT NULL,
+  content TEXT NOT NULL,
+  
+  -- Vector embedding (768 dimensions for Gemini text-embedding-004)
+  -- NOTE: OpenAI embeddings use 1536 dims, but Gemini uses 768
+  embedding VECTOR(768) NOT NULL,
+  
+  -- Source and importance metadata (optional, from knowledge_items)
+  source_type TEXT,
+  importance TEXT CHECK (importance IN ('primary', 'supporting', 'irrelevant') OR importance IS NULL),
+  
+  -- Timestamps
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- =====================================================================
+-- Indexes for efficient querying
+-- =====================================================================
+
+-- Standard indexes for filtering by project and knowledge_item
+CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_project_id 
+  ON knowledge_chunks (project_id);
+
+CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_knowledge_item_id 
+  ON knowledge_chunks (knowledge_item_id);
+
+-- Composite index for project + knowledge_item queries
+CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_project_knowledge 
+  ON knowledge_chunks (project_id, knowledge_item_id);
+
+-- Index for chunk ordering within a knowledge_item
+CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_item_index 
+  ON knowledge_chunks (knowledge_item_id, chunk_index);
+
+-- Vector similarity index using IVFFlat (pgvector)
+-- This enables fast approximate nearest neighbor search
+-- The 'lists' parameter controls the number of clusters (tune based on data size)
+-- For < 100k rows, lists=100 is reasonable. Scale up for larger datasets.
+-- Using cosine distance (vector_cosine_ops) for semantic similarity
+CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_embedding 
+  ON knowledge_chunks 
+  USING ivfflat (embedding vector_cosine_ops) 
+  WITH (lists = 100);
+
+-- Alternative: Use HNSW index for better recall at higher cost
+-- Uncomment if you prefer HNSW over IVFFlat:
+-- CREATE INDEX IF NOT EXISTS idx_knowledge_chunks_embedding_hnsw 
+--   ON knowledge_chunks 
+--   USING hnsw (embedding vector_cosine_ops) 
+--   WITH (m = 16, ef_construction = 64);
+
+-- =====================================================================
+-- Optional: Trigger to auto-update updated_at timestamp
+-- =====================================================================
+CREATE OR REPLACE FUNCTION update_updated_at_column()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER update_knowledge_chunks_updated_at
+  BEFORE UPDATE ON knowledge_chunks
+  FOR EACH ROW
+  EXECUTE FUNCTION update_updated_at_column();
+
+-- =====================================================================
+-- Helpful queries for monitoring and debugging
+-- =====================================================================
+
+-- Count chunks per project
+-- SELECT project_id, COUNT(*) as chunk_count FROM knowledge_chunks GROUP BY project_id;
+
+-- Count chunks per knowledge_item
+-- SELECT knowledge_item_id, COUNT(*) as chunk_count FROM knowledge_chunks GROUP BY knowledge_item_id;
+
+-- Find chunks similar to a query vector (example)
+-- SELECT id, content, 1 - (embedding <=> '[0.1, 0.2, ...]') AS similarity
+-- FROM knowledge_chunks
+-- WHERE project_id = 'your-project-id'
+-- ORDER BY embedding <=> '[0.1, 0.2, ...]'
+-- LIMIT 10;
+
+-- Check index usage
+-- SELECT schemaname, tablename, indexname, idx_scan, idx_tup_read, idx_tup_fetch
+-- FROM pg_stat_user_indexes
+-- WHERE tablename = 'knowledge_chunks';
+

lib/firebase/admin.ts

@@ -0,0 +1,77 @@
+import * as admin from 'firebase-admin';
+
+// Initialize Firebase Admin SDK
+// During build time on Vercel, env vars might not be available, so we skip initialization
+const projectId = process.env.FIREBASE_PROJECT_ID;
+const clientEmail = process.env.FIREBASE_CLIENT_EMAIL;
+const privateKey = process.env.FIREBASE_PRIVATE_KEY?.replace(/\\n/g, '\n');
+
+if (!admin.apps.length) {
+  // Only initialize if we have credentials (skip during build)
+  if (projectId && clientEmail && privateKey) {
+    try {
+      console.log('[Firebase Admin] Initializing...');
+      console.log('[Firebase Admin] Project ID:', projectId);
+      console.log('[Firebase Admin] Client Email:', clientEmail);
+      console.log('[Firebase Admin] Private Key length:', privateKey?.length);
+
+      admin.initializeApp({
+        credential: admin.credential.cert({
+          projectId,
+          clientEmail,
+          privateKey,
+        }),
+        storageBucket: `${projectId}.firebasestorage.app`,
+      });
+
+      console.log('[Firebase Admin] Initialized successfully!');
+    } catch (error) {
+      console.error('[Firebase Admin] Initialization failed:', error);
+    }
+  } else {
+    console.log('[Firebase Admin] Skipping initialization - credentials not available (likely build time)');
+  }
+}
+
+// Helper to ensure admin is initialized
+function ensureInitialized() {
+  if (!projectId || !clientEmail || !privateKey) {
+    throw new Error('Firebase Admin credentials not configured');
+  }
+  
+  if (!admin.apps.length) {
+    // Try to initialize if not done yet
+    admin.initializeApp({
+      credential: admin.credential.cert({
+        projectId,
+        clientEmail,
+        privateKey,
+      }),
+      storageBucket: `${projectId}.firebasestorage.app`,
+    });
+  }
+}
+
+// Export admin services with lazy initialization
+export function getAdminAuth() {
+  ensureInitialized();
+  return admin.auth();
+}
+
+export function getAdminDb() {
+  ensureInitialized();
+  return admin.firestore();
+}
+
+export function getAdminStorage() {
+  ensureInitialized();
+  return admin.storage();
+}
+
+// Legacy exports for backward compatibility (will work at runtime)
+export const adminAuth = admin.apps.length > 0 ? admin.auth() : ({} as any);
+export const adminDb = admin.apps.length > 0 ? admin.firestore() : ({} as any);
+export const adminStorage = admin.apps.length > 0 ? admin.storage() : ({} as any);
+
+export default admin;
+

lib/firebase/api-keys.ts

@@ -0,0 +1,71 @@
+import { db } from './config';
+import { doc, getDoc, setDoc, serverTimestamp } from 'firebase/firestore';
+import { v4 as uuidv4 } from 'uuid';
+
+interface ApiKey {
+  key: string;
+  userId: string;
+  createdAt: any;
+  lastUsed?: any;
+  isActive: boolean;
+}
+
+// Generate a new API key for a user
+export async function generateApiKey(userId: string): Promise<string> {
+  const apiKey = `vibn_${uuidv4().replace(/-/g, '')}`;
+  
+  const keyDoc = doc(db, 'apiKeys', apiKey);
+  await setDoc(keyDoc, {
+    key: apiKey,
+    userId,
+    createdAt: serverTimestamp(),
+    isActive: true,
+  });
+  
+  return apiKey;
+}
+
+// Get or create API key for a user
+export async function getOrCreateApiKey(userId: string): Promise<string> {
+  // Check if user already has an API key
+  const userDoc = doc(db, 'users', userId);
+  const userSnap = await getDoc(userDoc);
+  
+  if (userSnap.exists() && userSnap.data().apiKey) {
+    return userSnap.data().apiKey;
+  }
+  
+  // Generate new key
+  const apiKey = await generateApiKey(userId);
+  
+  // Store reference in user document
+  await setDoc(userDoc, {
+    apiKey,
+    updatedAt: serverTimestamp(),
+  }, { merge: true });
+  
+  return apiKey;
+}
+
+// Verify an API key and return the userId
+export async function verifyApiKey(apiKey: string): Promise<string | null> {
+  try {
+    const keyDoc = doc(db, 'apiKeys', apiKey);
+    const keySnap = await getDoc(keyDoc);
+    
+    if (!keySnap.exists() || !keySnap.data().isActive) {
+      return null;
+    }
+    
+    // Update last used timestamp
+    await setDoc(keyDoc, {
+      lastUsed: serverTimestamp(),
+    }, { merge: true });
+    
+    return keySnap.data().userId;
+  } catch (error) {
+    console.error('Error verifying API key:', error);
+    return null;
+  }
+}
+

lib/firebase/auth.ts

@@ -0,0 +1,116 @@
+import { 
+  signInWithEmailAndPassword, 
+  createUserWithEmailAndPassword,
+  signInWithPopup,
+  GoogleAuthProvider,
+  GithubAuthProvider,
+  signOut as firebaseSignOut,
+  onAuthStateChanged,
+  User
+} from 'firebase/auth';
+import { auth } from './config';
+import { createUser, getUser } from './collections';
+
+// Providers
+const googleProvider = new GoogleAuthProvider();
+const githubProvider = new GithubAuthProvider();
+
+// Sign up with email/password
+export async function signUpWithEmail(email: string, password: string, displayName: string) {
+  try {
+    const userCredential = await createUserWithEmailAndPassword(auth, email, password);
+    const user = userCredential.user;
+    
+    // Create user document in Firestore
+    // Generate workspace from email or name
+    const workspace = displayName.toLowerCase().replace(/\s+/g, '-') + '-account';
+    
+    await createUser(user.uid, {
+      email: user.email!,
+      displayName: displayName,
+      workspace: workspace,
+    });
+    
+    return { user, workspace };
+  } catch (error: any) {
+    throw new Error(error.message || 'Failed to create account');
+  }
+}
+
+// Sign in with email/password
+export async function signInWithEmail(email: string, password: string) {
+  try {
+    const userCredential = await signInWithEmailAndPassword(auth, email, password);
+    return userCredential.user;
+  } catch (error: any) {
+    throw new Error(error.message || 'Failed to sign in');
+  }
+}
+
+// Sign in with Google
+export async function signInWithGoogle() {
+  try {
+    const result = await signInWithPopup(auth, googleProvider);
+    const user = result.user;
+    
+    // Check if user exists, if not create
+    const existingUser = await getUser(user.uid);
+    if (!existingUser) {
+      const workspace = (user.displayName || user.email!.split('@')[0]).toLowerCase().replace(/\s+/g, '-') + '-account';
+      await createUser(user.uid, {
+        email: user.email!,
+        displayName: user.displayName || undefined,
+        photoURL: user.photoURL || undefined,
+        workspace: workspace,
+      });
+    }
+    
+    return user;
+  } catch (error: any) {
+    throw new Error(error.message || 'Failed to sign in with Google');
+  }
+}
+
+// Sign in with GitHub
+export async function signInWithGitHub() {
+  try {
+    const result = await signInWithPopup(auth, githubProvider);
+    const user = result.user;
+    
+    // Check if user exists, if not create
+    const existingUser = await getUser(user.uid);
+    if (!existingUser) {
+      const workspace = (user.displayName || user.email!.split('@')[0]).toLowerCase().replace(/\s+/g, '-') + '-account';
+      await createUser(user.uid, {
+        email: user.email!,
+        displayName: user.displayName || undefined,
+        photoURL: user.photoURL || undefined,
+        workspace: workspace,
+      });
+    }
+    
+    return user;
+  } catch (error: any) {
+    throw new Error(error.message || 'Failed to sign in with GitHub');
+  }
+}
+
+// Sign out
+export async function signOut() {
+  try {
+    await firebaseSignOut(auth);
+  } catch (error: any) {
+    throw new Error(error.message || 'Failed to sign out');
+  }
+}
+
+// Listen to auth state changes
+export function onAuthChange(callback: (user: User | null) => void) {
+  return onAuthStateChanged(auth, callback);
+}
+
+// Get current user
+export function getCurrentUser(): User | null {
+  return auth.currentUser;
+}
+

lib/firebase/collections.ts

@@ -0,0 +1,167 @@
+import { db } from './config';
+import { 
+  collection, 
+  doc, 
+  getDoc, 
+  getDocs, 
+  setDoc, 
+  updateDoc, 
+  query, 
+  where,
+  serverTimestamp,
+  Timestamp
+} from 'firebase/firestore';
+import type { ProjectPhase, ProjectPhaseData, ProjectPhaseScores } from '@/lib/types/project-artifacts';
+
+// Type definitions
+export interface User {
+  uid: string;
+  email: string;
+  displayName?: string;
+  photoURL?: string;
+  workspace: string; // e.g., "marks-account"
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+}
+
+export interface Project {
+  id: string;
+  name: string;
+  slug: string;
+  userId: string;
+  workspace: string;
+  productName: string;
+  productVision?: string;
+  isForClient: boolean;
+  hasLogo: boolean;
+  hasDomain: boolean;
+  hasWebsite: boolean;
+  hasGithub: boolean;
+  hasChatGPT: boolean;
+  githubRepo?: string;
+  chatGPTProjectId?: string;
+  currentPhase: ProjectPhase;
+  phaseStatus: 'not_started' | 'in_progress' | 'completed';
+  phaseData?: ProjectPhaseData;
+  phaseHistory?: Array<Record<string, unknown>>;
+  phaseScores?: ProjectPhaseScores;
+  createdAt: Timestamp;
+  updatedAt: Timestamp;
+}
+
+export interface Session {
+  id: string;
+  projectId?: string | null;
+  userId: string;
+  startTime: Timestamp;
+  endTime?: Timestamp | null;
+  duration?: number | null;
+  workspacePath?: string | null;
+  workspaceName?: string | null;
+  tokensUsed: number;
+  cost: number;
+  model: string;
+  filesModified?: string[];
+  conversationSummary?: string | null;
+  conversation?: Array<{
+    role: string;
+    content: string;
+    timestamp: string | Date;
+  }>;
+  createdAt: Timestamp;
+}
+
+export interface Analysis {
+  id: string;
+  projectId: string;
+  type: 'code' | 'chatgpt' | 'github' | 'combined';
+  summary: string;
+  techStack?: string[];
+  features?: string[];
+  rawData?: any;
+  createdAt: Timestamp;
+}
+
+// User operations
+export async function createUser(uid: string, data: Partial<User>) {
+  const userRef = doc(db, 'users', uid);
+  await setDoc(userRef, {
+    uid,
+    ...data,
+    createdAt: serverTimestamp(),
+    updatedAt: serverTimestamp(),
+  });
+}
+
+export async function getUser(uid: string): Promise<User | null> {
+  const userRef = doc(db, 'users', uid);
+  const userSnap = await getDoc(userRef);
+  return userSnap.exists() ? (userSnap.data() as User) : null;
+}
+
+// Project operations
+export async function createProject(projectData: Omit<Project, 'id' | 'createdAt' | 'updatedAt'>) {
+  const projectRef = doc(collection(db, 'projects'));
+  await setDoc(projectRef, {
+    ...projectData,
+    id: projectRef.id,
+    createdAt: serverTimestamp(),
+    updatedAt: serverTimestamp(),
+  });
+  return projectRef.id;
+}
+
+export async function getProject(projectId: string): Promise<Project | null> {
+  const projectRef = doc(db, 'projects', projectId);
+  const projectSnap = await getDoc(projectRef);
+  return projectSnap.exists() ? (projectSnap.data() as Project) : null;
+}
+
+export async function getUserProjects(userId: string): Promise<Project[]> {
+  const q = query(collection(db, 'projects'), where('userId', '==', userId));
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map(doc => doc.data() as Project);
+}
+
+export async function updateProject(projectId: string, data: Partial<Project>) {
+  const projectRef = doc(db, 'projects', projectId);
+  await updateDoc(projectRef, {
+    ...data,
+    updatedAt: serverTimestamp(),
+  });
+}
+
+// Session operations
+export async function createSession(sessionData: Omit<Session, 'id' | 'createdAt'>) {
+  const sessionRef = doc(collection(db, 'sessions'));
+  await setDoc(sessionRef, {
+    ...sessionData,
+    id: sessionRef.id,
+    createdAt: serverTimestamp(),
+  });
+  return sessionRef.id;
+}
+
+export async function getProjectSessions(projectId: string): Promise<Session[]> {
+  const q = query(collection(db, 'sessions'), where('projectId', '==', projectId));
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map(doc => doc.data() as Session);
+}
+
+// Analysis operations
+export async function createAnalysis(analysisData: Omit<Analysis, 'id' | 'createdAt'>) {
+  const analysisRef = doc(collection(db, 'analyses'));
+  await setDoc(analysisRef, {
+    ...analysisData,
+    id: analysisRef.id,
+    createdAt: serverTimestamp(),
+  });
+  return analysisRef.id;
+}
+
+export async function getProjectAnalyses(projectId: string): Promise<Analysis[]> {
+  const q = query(collection(db, 'analyses'), where('projectId', '==', projectId));
+  const querySnapshot = await getDocs(q);
+  return querySnapshot.docs.map(doc => doc.data() as Analysis);
+}
+

lib/firebase/config.ts

@@ -0,0 +1,36 @@
+import { initializeApp, getApps, FirebaseApp } from 'firebase/app';
+import { getAuth, Auth } from 'firebase/auth';
+import { getFirestore, Firestore } from 'firebase/firestore';
+import { getStorage, FirebaseStorage } from 'firebase/storage';
+
+const firebaseConfig = {
+  apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
+  authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
+  projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
+  storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+  appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
+  measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
+};
+
+// Only initialize if we have the API key (skip during build)
+let _app: FirebaseApp | undefined;
+let _auth: Auth | undefined;
+let _db: Firestore | undefined;
+let _storage: FirebaseStorage | undefined;
+
+if (typeof window !== 'undefined' || firebaseConfig.apiKey) {
+  // Initialize Firebase (client-side only, safe for browser)
+  _app = getApps().length === 0 ? initializeApp(firebaseConfig) : getApps()[0];
+  _auth = getAuth(_app);
+  _db = getFirestore(_app);
+  _storage = getStorage(_app);
+}
+
+// Export with type assertions - these will be defined at runtime in the browser
+// During build, they may be undefined, but won't be accessed
+export const auth = _auth as Auth;
+export const db = _db as Firestore;
+export const storage = _storage as FirebaseStorage;
+export default _app;
+

lib/github/oauth.ts

@@ -0,0 +1,177 @@
+/**
+ * GitHub OAuth integration for VIBN
+ * Allows users to connect their GitHub account for repo analysis and tracking
+ */
+
+export interface GitHubUser {
+  id: number;
+  login: string;
+  name: string | null;
+  email: string | null;
+  avatar_url: string;
+}
+
+export interface GitHubRepo {
+  id: number;
+  name: string;
+  full_name: string;
+  description: string | null;
+  html_url: string;
+  language: string | null;
+  default_branch: string;
+  private: boolean;
+  topics: string[];
+}
+
+export interface GitHubConnection {
+  userId: string;
+  githubUserId: number;
+  githubUsername: string;
+  accessToken: string; // Encrypted
+  refreshToken?: string; // Encrypted
+  tokenExpiresAt?: Date;
+  scopes: string[];
+  connectedAt: Date;
+  lastSyncedAt?: Date;
+}
+
+/**
+ * Initiates GitHub OAuth flow
+ * Redirects user to GitHub authorization page
+ */
+export function initiateGitHubOAuth(redirectUri: string) {
+  const clientId = process.env.NEXT_PUBLIC_GITHUB_CLIENT_ID;
+  
+  if (!clientId) {
+    throw new Error('GitHub OAuth not configured');
+  }
+
+  // Scopes we need:
+  // - repo: Access repositories (read commits, PRs, issues)
+  // - read:user: Get user profile
+  const scopes = ['repo', 'read:user'];
+  
+  // Generate state for CSRF protection
+  const state = generateRandomString(32);
+  sessionStorage.setItem('github_oauth_state', state);
+  
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    scope: scopes.join(' '),
+    state,
+  });
+
+  window.location.href = `https://github.com/login/oauth/authorize?${params}`;
+}
+
+/**
+ * Exchanges authorization code for access token
+ */
+export async function exchangeCodeForToken(code: string): Promise<{
+  access_token: string;
+  token_type: string;
+  scope: string;
+}> {
+  const response = await fetch('/api/github/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ code }),
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to exchange code for token');
+  }
+
+  return response.json();
+}
+
+/**
+ * Fetches GitHub user profile
+ */
+export async function getGitHubUser(accessToken: string): Promise<GitHubUser> {
+  const response = await fetch('https://api.github.com/user', {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: 'application/vnd.github.v3+json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch GitHub user');
+  }
+
+  return response.json();
+}
+
+/**
+ * Fetches user's repositories
+ */
+export async function getGitHubRepos(
+  accessToken: string,
+  options?: {
+    sort?: 'created' | 'updated' | 'pushed' | 'full_name';
+    direction?: 'asc' | 'desc';
+    per_page?: number;
+  }
+): Promise<GitHubRepo[]> {
+  const params = new URLSearchParams({
+    sort: options?.sort || 'updated',
+    direction: options?.direction || 'desc',
+    per_page: String(options?.per_page || 100),
+  });
+
+  const response = await fetch(`https://api.github.com/user/repos?${params}`, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: 'application/vnd.github.v3+json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch repositories');
+  }
+
+  return response.json();
+}
+
+/**
+ * Fetches a specific repository
+ */
+export async function getGitHubRepo(
+  accessToken: string,
+  owner: string,
+  repo: string
+): Promise<GitHubRepo> {
+  const response = await fetch(`https://api.github.com/repos/${owner}/${repo}`, {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: 'application/vnd.github.v3+json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error('Failed to fetch repository');
+  }
+
+  return response.json();
+}
+
+/**
+ * Utility: Generate random string for state parameter
+ */
+function generateRandomString(length: number): string {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let result = '';
+  const randomValues = new Uint8Array(length);
+  crypto.getRandomValues(randomValues);
+  
+  for (let i = 0; i < length; i++) {
+    result += chars[randomValues[i] % chars.length];
+  }
+  
+  return result;
+}
+

lib/mcp/server.ts

@@ -0,0 +1,368 @@
+/**
+ * Vibn MCP (Model Context Protocol) Server
+ * 
+ * Exposes Vibn project data, sessions, and capabilities to AI assistants
+ * through a standardized protocol.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { getAdminDb } from '@/lib/firebase/admin';
+
+interface VibnResource {
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}
+
+class VibnMCPServer {
+  private server: Server;
+
+  constructor() {
+    this.server = new Server(
+      {
+        name: 'vibn-mcp-server',
+        version: '1.0.0',
+      },
+      {
+        capabilities: {
+          resources: {},
+          tools: {},
+          prompts: {},
+        },
+      }
+    );
+
+    this.setupHandlers();
+  }
+
+  private setupHandlers() {
+    // List available resources
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      return {
+        resources: [
+          {
+            uri: 'vibn://projects',
+            name: 'Projects',
+            description: 'List all user projects',
+            mimeType: 'application/json',
+          },
+          {
+            uri: 'vibn://sessions',
+            name: 'Coding Sessions',
+            description: 'List all coding sessions',
+            mimeType: 'application/json',
+          },
+          {
+            uri: 'vibn://conversations',
+            name: 'AI Conversations',
+            description: 'List all AI conversation history',
+            mimeType: 'application/json',
+          },
+        ] as VibnResource[],
+      };
+    });
+
+    // Read a specific resource
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const { uri } = request.params;
+      const db = getAdminDb();
+
+      try {
+        if (uri === 'vibn://projects') {
+          // Fetch all projects (would need user context in real implementation)
+          const projectsSnapshot = await db
+            .collection('projects')
+            .orderBy('createdAt', 'desc')
+            .limit(50)
+            .get();
+
+          const projects = projectsSnapshot.docs.map(doc => ({
+            id: doc.id,
+            ...doc.data(),
+          }));
+
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify(projects, null, 2),
+              },
+            ],
+          };
+        }
+
+        if (uri.startsWith('vibn://projects/')) {
+          const projectId = uri.replace('vibn://projects/', '');
+          const projectDoc = await db.collection('projects').doc(projectId).get();
+
+          if (!projectDoc.exists) {
+            throw new Error(`Project ${projectId} not found`);
+          }
+
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify({ id: projectDoc.id, ...projectDoc.data() }, null, 2),
+              },
+            ],
+          };
+        }
+
+        if (uri.startsWith('vibn://sessions/')) {
+          const projectId = uri.replace('vibn://sessions/', '');
+          const sessionsSnapshot = await db
+            .collection('sessions')
+            .where('projectId', '==', projectId)
+            .orderBy('createdAt', 'desc')
+            .limit(50)
+            .get();
+
+          const sessions = sessionsSnapshot.docs.map(doc => ({
+            id: doc.id,
+            ...doc.data(),
+          }));
+
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify(sessions, null, 2),
+              },
+            ],
+          };
+        }
+
+        if (uri.startsWith('vibn://conversations/')) {
+          const projectId = uri.replace('vibn://conversations/', '');
+          const conversationsSnapshot = await db
+            .collection('projects')
+            .doc(projectId)
+            .collection('aiConversations')
+            .orderBy('createdAt', 'asc')
+            .limit(100)
+            .get();
+
+          const conversations = conversationsSnapshot.docs.map(doc => ({
+            id: doc.id,
+            ...doc.data(),
+          }));
+
+          return {
+            contents: [
+              {
+                uri,
+                mimeType: 'application/json',
+                text: JSON.stringify(conversations, null, 2),
+              },
+            ],
+          };
+        }
+
+        throw new Error(`Unknown resource: ${uri}`);
+      } catch (error) {
+        throw new Error(`Failed to read resource: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+
+    // List available tools
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+      return {
+        tools: [
+          {
+            name: 'get_project_summary',
+            description: 'Get a summary of a specific project including sessions, costs, and activity',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                projectId: {
+                  type: 'string',
+                  description: 'The project ID',
+                },
+              },
+              required: ['projectId'],
+            },
+          },
+          {
+            name: 'search_sessions',
+            description: 'Search coding sessions by workspace path, date range, or project',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                projectId: {
+                  type: 'string',
+                  description: 'Filter by project ID',
+                },
+                workspacePath: {
+                  type: 'string',
+                  description: 'Filter by workspace path',
+                },
+                startDate: {
+                  type: 'string',
+                  description: 'Start date (ISO format)',
+                },
+                endDate: {
+                  type: 'string',
+                  description: 'End date (ISO format)',
+                },
+              },
+            },
+          },
+          {
+            name: 'get_conversation_context',
+            description: 'Get the full AI conversation history for a project',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                projectId: {
+                  type: 'string',
+                  description: 'The project ID',
+                },
+                limit: {
+                  type: 'number',
+                  description: 'Maximum number of messages to return (default: 50)',
+                },
+              },
+              required: ['projectId'],
+            },
+          },
+        ],
+      };
+    });
+
+    // Handle tool calls
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      const { name, arguments: args } = request.params;
+      const db = getAdminDb();
+
+      try {
+        if (name === 'get_project_summary') {
+          const { projectId } = args as { projectId: string };
+          
+          const projectDoc = await db.collection('projects').doc(projectId).get();
+          if (!projectDoc.exists) {
+            throw new Error(`Project ${projectId} not found`);
+          }
+
+          const project = { id: projectDoc.id, ...projectDoc.data() };
+
+          // Get sessions
+          const sessionsSnapshot = await db
+            .collection('sessions')
+            .where('projectId', '==', projectId)
+            .get();
+
+          const sessions = sessionsSnapshot.docs.map(doc => doc.data());
+          const totalCost = sessions.reduce((sum, s: any) => sum + (s.cost || 0), 0);
+          const totalTokens = sessions.reduce((sum, s: any) => sum + (s.tokensUsed || 0), 0);
+          const totalDuration = sessions.reduce((sum, s: any) => sum + (s.duration || 0), 0);
+
+          const summary = {
+            project,
+            stats: {
+              totalSessions: sessions.length,
+              totalCost,
+              totalTokens,
+              totalDuration,
+            },
+            recentSessions: sessions.slice(0, 5),
+          };
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(summary, null, 2),
+              },
+            ],
+          };
+        }
+
+        if (name === 'search_sessions') {
+          const { projectId, workspacePath, startDate, endDate } = args as {
+            projectId?: string;
+            workspacePath?: string;
+            startDate?: string;
+            endDate?: string;
+          };
+
+          let query = db.collection('sessions');
+
+          if (projectId) {
+            query = query.where('projectId', '==', projectId) as any;
+          }
+          if (workspacePath) {
+            query = query.where('workspacePath', '==', workspacePath) as any;
+          }
+
+          const snapshot = await query.orderBy('createdAt', 'desc').limit(50).get();
+          const sessions = snapshot.docs.map(doc => ({
+            id: doc.id,
+            ...doc.data(),
+          }));
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(sessions, null, 2),
+              },
+            ],
+          };
+        }
+
+        if (name === 'get_conversation_context') {
+          const { projectId, limit = 50 } = args as { projectId: string; limit?: number };
+
+          const conversationsSnapshot = await db
+            .collection('projects')
+            .doc(projectId)
+            .collection('aiConversations')
+            .orderBy('createdAt', 'asc')
+            .limit(limit)
+            .get();
+
+          const conversations = conversationsSnapshot.docs.map(doc => ({
+            id: doc.id,
+            ...doc.data(),
+          }));
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify(conversations, null, 2),
+              },
+            ],
+          };
+        }
+
+        throw new Error(`Unknown tool: ${name}`);
+      } catch (error) {
+        throw new Error(`Tool execution failed: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    });
+  }
+
+  async start() {
+    const transport = new StdioServerTransport();
+    await this.server.connect(transport);
+    console.error('Vibn MCP Server running on stdio');
+  }
+}
+
+// Start the server
+const server = new VibnMCPServer();
+server.start().catch(console.error);
+

lib/server/backend-extractor.ts

@@ -0,0 +1,228 @@
+/**
+ * Backend Extraction Module
+ * 
+ * Runs extraction as a pure backend job, not in chat.
+ * Called when Collector phase completes.
+ */
+
+import { getAdminDb } from '@/lib/firebase/admin';
+import { GeminiLlmClient } from '@/lib/ai/gemini-client';
+import { BACKEND_EXTRACTOR_SYSTEM_PROMPT } from '@/lib/ai/prompts/extractor';
+import { writeKnowledgeChunksForItem } from '@/lib/server/vector-memory';
+import type { ExtractionOutput, ExtractedInsight } from '@/lib/types/extraction-output';
+import type { PhaseHandoff } from '@/lib/types/phase-handoff';
+import { z } from 'zod';
+
+const ExtractionOutputSchema = z.object({
+  insights: z.array(z.object({
+    id: z.string(),
+    type: z.enum(["problem", "user", "feature", "constraint", "opportunity", "other"]),
+    title: z.string(),
+    description: z.string(),
+    sourceText: z.string(),
+    sourceKnowledgeItemId: z.string(),
+    importance: z.enum(["primary", "supporting"]),
+    confidence: z.number().min(0).max(1),
+  })),
+  problems: z.array(z.string()),
+  targetUsers: z.array(z.string()),
+  features: z.array(z.string()),
+  constraints: z.array(z.string()),
+  opportunities: z.array(z.string()),
+  uncertainties: z.array(z.string()),
+  missingInformation: z.array(z.string()),
+  overallConfidence: z.number().min(0).max(1),
+});
+
+export async function runBackendExtractionForProject(projectId: string): Promise<void> {
+  console.log(`[Backend Extractor] Starting extraction for project ${projectId}`);
+  
+  const adminDb = getAdminDb();
+  
+  try {
+    // 1. Load project
+    const projectDoc = await adminDb.collection('projects').doc(projectId).get();
+    if (!projectDoc.exists) {
+      throw new Error(`Project ${projectId} not found`);
+    }
+    
+    const projectData = projectDoc.data();
+    
+    // 2. Load knowledge items
+    const knowledgeSnapshot = await adminDb
+      .collection('knowledge_items')
+      .where('projectId', '==', projectId)
+      .where('sourceType', '==', 'imported_document')
+      .get();
+    
+    if (knowledgeSnapshot.empty) {
+      console.log(`[Backend Extractor] No documents to extract for project ${projectId} - creating empty handoff`);
+      
+      // Create a minimal extraction handoff even with no documents
+      const emptyHandoff: PhaseHandoff = {
+        phase: 'extraction',
+        readyForNextPhase: false, // Not ready - no materials to extract from
+        confidence: 0,
+        confirmed: {
+          problems: [],
+          targetUsers: [],
+          features: [],
+          constraints: [],
+          opportunities: [],
+        },
+        uncertain: {},
+        missing: ['No documents uploaded - need product requirements, specs, or notes'],
+        questionsForUser: [
+          'You haven\'t uploaded any documents yet. Do you have any product specs, requirements, or notes to share?',
+        ],
+        sourceEvidence: [],
+        version: 'extraction_v1',
+        timestamp: new Date().toISOString(),
+      };
+      
+      await adminDb.collection('projects').doc(projectId).update({
+        'phaseData.phaseHandoffs.extraction': emptyHandoff,
+        currentPhase: 'extraction_review',
+        phaseStatus: 'in_progress',
+        'phaseData.extractionCompletedAt': new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      });
+      
+      console.log(`[Backend Extractor] Set phase to extraction_review with empty handoff`);
+      return;
+    }
+    
+    console.log(`[Backend Extractor] Found ${knowledgeSnapshot.size} documents to process`);
+    
+    const llm = new GeminiLlmClient();
+    const allExtractionOutputs: ExtractionOutput[] = [];
+    const processedKnowledgeItemIds: string[] = [];
+    
+    // 3. Process each document
+    for (const knowledgeDoc of knowledgeSnapshot.docs) {
+      const knowledgeData = knowledgeDoc.data();
+      const knowledgeItemId = knowledgeDoc.id;
+      
+      try {
+        console.log(`[Backend Extractor] Processing document: ${knowledgeData.title || knowledgeItemId}`);
+        
+        // Call LLM with structured extraction + thinking mode
+        const extraction = await llm.structuredCall<ExtractionOutput>({
+          model: 'gemini',
+          systemPrompt: BACKEND_EXTRACTOR_SYSTEM_PROMPT,
+          messages: [{
+            role: 'user',
+            content: `Document Title: ${knowledgeData.title || 'Untitled'}\nSource Type: ${knowledgeData.sourceType}\n\nContent:\n${knowledgeData.content}`,
+          }],
+          schema: ExtractionOutputSchema as any,
+          temperature: 1.0, // Gemini 3 default (changed from 0.3)
+          thinking_config: {
+            thinking_level: 'high', // Enable deep reasoning for document analysis
+            include_thoughts: false, // Don't include thought tokens in output (saves cost)
+          },
+        });
+        
+        // Add knowledgeItemId to each insight
+        extraction.insights.forEach(insight => {
+          insight.sourceKnowledgeItemId = knowledgeItemId;
+        });
+        
+        allExtractionOutputs.push(extraction);
+        processedKnowledgeItemIds.push(knowledgeItemId);
+        
+        // 4. Persist extraction to chat_extractions
+        await adminDb.collection('chat_extractions').add({
+          projectId,
+          knowledgeItemId,
+          data: extraction,
+          overallConfidence: extraction.overallConfidence,
+          overallCompletion: extraction.overallConfidence > 0.7 ? 0.9 : 0.6,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        });
+        
+        console.log(`[Backend Extractor] Extracted ${extraction.insights.length} insights from ${knowledgeData.title || knowledgeItemId}`);
+        
+        // 5. Write vector chunks for primary insights
+        const primaryInsights = extraction.insights.filter(i => i.importance === 'primary');
+        for (const insight of primaryInsights) {
+          try {
+            // Create a knowledge chunk for this insight
+            await writeKnowledgeChunksForItem({
+              id: knowledgeItemId,
+              projectId,
+              content: `${insight.title}\n\n${insight.description}\n\nSource: ${insight.sourceText}`,
+              sourceMeta: {
+                sourceType: 'extracted_insight',
+                importance: 'primary',
+              },
+            });
+          } catch (chunkError) {
+            console.error(`[Backend Extractor] Failed to write chunk for insight ${insight.id}:`, chunkError);
+            // Continue processing other insights
+          }
+        }
+        
+      } catch (docError) {
+        console.error(`[Backend Extractor] Failed to process document ${knowledgeItemId}:`, docError);
+        // Continue with next document
+      }
+    }
+    
+    // 6. Build extraction PhaseHandoff
+    // Flatten all extracted items (they're already strings, not objects)
+    const allProblems = [...new Set(allExtractionOutputs.flatMap(e => e.problems))];
+    const allUsers = [...new Set(allExtractionOutputs.flatMap(e => e.targetUsers))];
+    const allFeatures = [...new Set(allExtractionOutputs.flatMap(e => e.features))];
+    const allConstraints = [...new Set(allExtractionOutputs.flatMap(e => e.constraints))];
+    const allOpportunities = [...new Set(allExtractionOutputs.flatMap(e => e.opportunities))];
+    const allUncertainties = [...new Set(allExtractionOutputs.flatMap(e => e.uncertainties))];
+    const allMissing = [...new Set(allExtractionOutputs.flatMap(e => e.missingInformation))];
+    
+    const avgConfidence = allExtractionOutputs.length > 0
+      ? allExtractionOutputs.reduce((sum, e) => sum + e.overallConfidence, 0) / allExtractionOutputs.length
+      : 0;
+    
+    const readyForNextPhase = allProblems.length > 0 && allFeatures.length > 0 && avgConfidence > 0.5;
+    
+    const extractionHandoff: PhaseHandoff = {
+      phase: 'extraction',
+      readyForNextPhase,
+      confidence: avgConfidence,
+      confirmed: {
+        problems: allProblems,
+        targetUsers: allUsers,
+        features: allFeatures,
+        constraints: allConstraints,
+        opportunities: allOpportunities,
+      },
+      uncertain: {},
+      missing: allMissing,
+      questionsForUser: allUncertainties,
+      sourceEvidence: processedKnowledgeItemIds,
+      version: 'extraction_v1',
+      timestamp: new Date().toISOString(),
+    };
+    
+    // 7. Persist handoff and update phase
+    await adminDb.collection('projects').doc(projectId).update({
+      'phaseData.phaseHandoffs.extraction': extractionHandoff,
+      currentPhase: 'extraction_review',
+      phaseStatus: 'in_progress',
+      'phaseData.extractionCompletedAt': new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    });
+    
+    console.log(`[Backend Extractor] ✅ Extraction complete for project ${projectId}`);
+    console.log(`[Backend Extractor] - Problems: ${allProblems.length}`);
+    console.log(`[Backend Extractor] - Users: ${allUsers.length}`);
+    console.log(`[Backend Extractor] - Features: ${allFeatures.length}`);
+    console.log(`[Backend Extractor] - Confidence: ${(avgConfidence * 100).toFixed(1)}%`);
+    console.log(`[Backend Extractor] - Ready for next phase: ${readyForNextPhase}`);
+    
+  } catch (error) {
+    console.error(`[Backend Extractor] Fatal error during extraction:`, error);
+    throw error;
+  }
+}
+

lib/server/chat-context.ts

@@ -0,0 +1,402 @@
+/**
+ * Project Context Builder for Chat
+ * 
+ * Loads project state from Firestore and AlloyDB vector memory,
+ * building a compact context object for LLM consumption.
+ */
+
+import { getAdminDb } from '@/lib/firebase/admin';
+import { retrieveRelevantChunks } from '@/lib/server/vector-memory';
+import { embedText } from '@/lib/ai/embeddings';
+import {
+  summarizeKnowledgeItems,
+  summarizeExtractions,
+} from '@/lib/server/chat-mode-resolver';
+import type { ChatMode } from '@/lib/ai/chat-modes';
+import type { ProjectPhaseData, ProjectPhaseScores } from '@/lib/types/project-artifacts';
+import type { PhaseHandoff } from '@/lib/types/phase-handoff';
+
+/**
+ * Compact project context for LLM
+ */
+export interface ProjectChatContext {
+  /** Basic project info */
+  project: {
+    id: string;
+    name: string;
+    currentPhase: string;
+    phaseStatus: string;
+    githubRepo?: string | null;
+    githubRepoUrl?: string | null;
+    extensionLinked?: boolean;
+    visionAnswers?: {
+      q1?: string;
+      q2?: string;
+      q3?: string;
+      updatedAt?: string;
+    };
+  };
+
+  /** Phase-specific artifacts */
+  phaseData: {
+    canonicalProductModel?: any;
+    mvpPlan?: any;
+    marketingPlan?: any;
+  };
+
+  /** Phase scores and progress */
+  phaseScores: ProjectPhaseScores;
+
+  /** Phase handoffs for smart transitions */
+  phaseHandoffs: Partial<Record<'collector' | 'extraction' | 'vision' | 'mvp' | 'marketing', PhaseHandoff>>;
+
+  /** Knowledge summary (counts, types) */
+  knowledgeSummary: {
+    totalCount: number;
+    bySourceType: Record<string, number>;
+    recentTitles: string[];
+  };
+
+  /** Extraction summary */
+  extractionSummary: {
+    totalCount: number;
+    avgConfidence: number;
+    avgCompletion: number;
+  };
+
+  /** Relevant chunks from vector search */
+  retrievedChunks: {
+    content: string;
+    sourceType?: string | null;
+    importance?: string | null;
+    similarity: number;
+  }[];
+
+  /** Repository analysis (if GitHub connected) */
+  repositoryAnalysis?: {
+    repoFullName: string;
+    totalFiles: number;
+    directories: string[];
+    keyFiles: string[];
+    techStack: string[];
+    readme: string | null;
+    summary: string;
+  } | null;
+
+  /** Session history from linked Cursor sessions */
+  sessionHistory: {
+    totalSessions: number;
+    messages: Array<{
+      role: string;
+      content: string;
+      timestamp: string;
+      sessionId?: string;
+    }>;
+  };
+}
+
+/**
+ * Build project context for a chat interaction
+ * 
+ * @param projectId - Firestore project ID
+ * @param mode - Current chat mode
+ * @param userMessage - User's message (used for vector retrieval)
+ * @param options - Context building options
+ * @returns Compact context object
+ */
+export async function buildProjectContextForChat(
+  projectId: string,
+  mode: ChatMode,
+  userMessage: string,
+  options: {
+    retrievalLimit?: number;
+    includeVectorSearch?: boolean;
+    includeGitHubAnalysis?: boolean;
+  } = {}
+): Promise<ProjectChatContext> {
+  const {
+    retrievalLimit = 10,
+    includeVectorSearch = true,
+    includeGitHubAnalysis = true,
+  } = options;
+
+  try {
+    const adminDb = getAdminDb();
+
+    // Load project document
+    const projectSnapshot = await adminDb.collection('projects').doc(projectId).get();
+    if (!projectSnapshot.exists) {
+      throw new Error(`Project ${projectId} not found`);
+    }
+
+    const projectData = projectSnapshot.data() ?? {};
+
+    // Load summaries in parallel
+    const [knowledgeSummary, extractionSummary] = await Promise.all([
+      summarizeKnowledgeItems(projectId),
+      summarizeExtractions(projectId),
+    ]);
+
+    // Vector retrieval
+    let retrievedChunks: ProjectChatContext['retrievedChunks'] = [];
+    
+    // extraction_review_mode does NOT load documents - it reviews extraction results
+    // Normal vector search for modes that need it
+    if (includeVectorSearch && mode !== 'collector_mode' && mode !== 'extraction_review_mode' && userMessage.trim().length > 0) {
+      try {
+        const queryEmbedding = await embedText(userMessage);
+        const chunks = await retrieveRelevantChunks(projectId, queryEmbedding, {
+          limit: retrievalLimit,
+          minSimilarity: 0.7, // Only include reasonably relevant chunks
+        });
+
+        retrievedChunks = chunks.map((chunk) => ({
+          content: chunk.content,
+          sourceType: chunk.sourceType,
+          importance: chunk.importance,
+          similarity: chunk.similarity,
+        }));
+
+        console.log(
+          `[Chat Context] Retrieved ${retrievedChunks.length} chunks for project ${projectId}`
+        );
+      } catch (vectorError) {
+        console.error('[Chat Context] Vector retrieval failed:', vectorError);
+        // Continue without vector results
+      }
+    }
+
+    // GitHub repository analysis
+    let repositoryAnalysis = null;
+    if (includeGitHubAnalysis && projectData.githubRepo && projectData.userId) {
+      try {
+        const { analyzeGitHubRepository } = await import('@/lib/server/github-analyzer');
+        repositoryAnalysis = await analyzeGitHubRepository(
+          projectData.userId,
+          projectData.githubRepo,
+          projectData.githubDefaultBranch || 'main'
+        );
+      } catch (githubError) {
+        console.error('[Chat Context] GitHub analysis failed:', githubError);
+        // Continue without GitHub analysis
+      }
+    }
+
+    // Fetch linked Cursor session history
+    let sessionHistory = {
+      totalSessions: 0,
+      messages: [] as Array<{
+        role: string;
+        content: string;
+        timestamp: string;
+        sessionId?: string;
+      }>,
+    };
+
+    try {
+      // Query sessions linked to this project
+      const sessionsSnapshot = await adminDb
+        .collection('sessions')
+        .where('projectId', '==', projectId)
+        .orderBy('startTime', 'asc')
+        .get();
+
+      if (!sessionsSnapshot.empty) {
+        sessionHistory.totalSessions = sessionsSnapshot.size;
+        
+        // Extract all messages from all sessions in chronological order
+        const allMessages: Array<{
+          role: string;
+          content: string;
+          timestamp: string;
+          sessionId: string;
+        }> = [];
+
+        for (const sessionDoc of sessionsSnapshot.docs) {
+          const sessionData = sessionDoc.data();
+          const conversation = sessionData.conversation || [];
+          
+          // Add messages from this session
+          for (const msg of conversation) {
+            if (msg.content && msg.content.trim()) {
+              allMessages.push({
+                role: msg.role || 'unknown',
+                content: msg.content,
+                timestamp: msg.timestamp instanceof Date 
+                  ? msg.timestamp.toISOString() 
+                  : (typeof msg.timestamp === 'string' ? msg.timestamp : new Date().toISOString()),
+                sessionId: sessionDoc.id,
+              });
+            }
+          }
+        }
+
+        // Sort all messages by timestamp (chronological order)
+        allMessages.sort((a, b) => 
+          new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+        );
+
+        sessionHistory.messages = allMessages;
+
+        console.log(
+          `[Chat Context] Loaded ${sessionHistory.totalSessions} sessions with ${allMessages.length} total messages for project ${projectId}`
+        );
+      } else {
+        console.log(`[Chat Context] No linked sessions found for project ${projectId}`);
+      }
+    } catch (sessionError) {
+      console.error('[Chat Context] Session history fetch failed:', sessionError);
+      // Continue without session history
+    }
+
+    // Build context object
+    const context: ProjectChatContext = {
+      project: {
+        id: projectId,
+        name: projectData.name ?? 'Unnamed Project',
+        currentPhase: projectData.currentPhase ?? 'collector',
+        phaseStatus: projectData.phaseStatus ?? 'not_started',
+        githubRepo: projectData.githubRepo ?? null,
+        githubRepoUrl: projectData.githubRepoUrl ?? null,
+        extensionLinked: projectData.extensionLinked ?? false,
+        visionAnswers: projectData.visionAnswers ?? {},
+      },
+      phaseData: {
+        canonicalProductModel: projectData.phaseData?.canonicalProductModel ?? null,
+        mvpPlan: projectData.phaseData?.mvpPlan ?? null,
+        marketingPlan: projectData.phaseData?.marketingPlan ?? null,
+      },
+      phaseScores: projectData.phaseScores ?? {},
+      phaseHandoffs: projectData.phaseData?.phaseHandoffs ?? {},
+      knowledgeSummary,
+      extractionSummary,
+      retrievedChunks,
+      repositoryAnalysis: repositoryAnalysis as any,
+      sessionHistory, // ✅ Include session history in context
+    };
+
+    return context;
+  } catch (error) {
+    console.error('[Chat Context] Failed to build context:', error);
+    throw new Error(
+      `Failed to build chat context: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Determine which artifacts were used in building the context
+ * 
+ * This helps the UI show what sources the AI is drawing from.
+ */
+export function determineArtifactsUsed(context: ProjectChatContext): string[] {
+  const artifacts: string[] = [];
+
+  if (context.phaseData.canonicalProductModel) {
+    artifacts.push('Product Model');
+  }
+
+  if (context.phaseData.mvpPlan) {
+    artifacts.push('MVP Plan');
+  }
+
+  if (context.phaseData.marketingPlan) {
+    artifacts.push('Marketing Plan');
+  }
+
+  if (context.retrievedChunks.length > 0) {
+    artifacts.push(`${context.retrievedChunks.length} Vector Chunks`);
+  }
+
+  if (context.repositoryAnalysis) {
+    artifacts.push('GitHub Repo Analysis');
+  }
+
+  if (context.knowledgeSummary.totalCount > 0) {
+    artifacts.push(`${context.knowledgeSummary.totalCount} Knowledge Items`);
+  }
+
+  if (context.extractionSummary.totalCount > 0) {
+    artifacts.push(`${context.extractionSummary.totalCount} Extractions`);
+  }
+
+  if (context.sessionHistory.totalSessions > 0) {
+    artifacts.push(`${context.sessionHistory.totalSessions} Cursor Sessions (${context.sessionHistory.messages.length} messages)`);
+  }
+
+  return artifacts;
+}
+
+/**
+ * Format project context as a string for LLM system prompt
+ * 
+ * Provides a human-readable summary of the context.
+ */
+export function formatContextForPrompt(context: ProjectChatContext): string {
+  const sections: string[] = [];
+
+  // Project info
+  sections.push(`Project: ${context.project.name} (ID: ${context.project.id})`);
+  sections.push(
+    `Phase: ${context.project.currentPhase} (${context.project.phaseStatus})`
+  );
+
+  // Knowledge summary
+  if (context.knowledgeSummary.totalCount > 0) {
+    sections.push(`\nKnowledge Items: ${context.knowledgeSummary.totalCount} total`);
+    if (Object.keys(context.knowledgeSummary.bySourceType).length > 0) {
+      sections.push(
+        `  By type: ${JSON.stringify(context.knowledgeSummary.bySourceType)}`
+      );
+    }
+  }
+
+  // Extraction summary
+  if (context.extractionSummary.totalCount > 0) {
+    sections.push(
+      `\nExtractions: ${context.extractionSummary.totalCount} analyzed (avg confidence: ${(context.extractionSummary.avgConfidence * 100).toFixed(1)}%)`
+    );
+  }
+
+  // Retrieved chunks
+  if (context.retrievedChunks.length > 0) {
+    sections.push(`\nRelevant Context (vector search):`);
+    context.retrievedChunks.slice(0, 3).forEach((chunk, i) => {
+      sections.push(
+        `  ${i + 1}. [${chunk.sourceType ?? 'unknown'}] (similarity: ${(chunk.similarity * 100).toFixed(1)}%)`
+      );
+      sections.push(`     ${chunk.content.substring(0, 150)}...`);
+    });
+  }
+
+  // GitHub repo
+  if (context.repositoryAnalysis) {
+    sections.push(`\nGitHub Repository: ${context.repositoryAnalysis.repoFullName}`);
+    sections.push(`  Files: ${context.repositoryAnalysis.totalFiles}`);
+    sections.push(`  Tech: ${context.repositoryAnalysis.techStack.join(', ')}`);
+  }
+
+  // Phase handoffs
+  const handoffs = Object.keys(context.phaseHandoffs);
+  if (handoffs.length > 0) {
+    sections.push(`\nPhase Handoffs: ${handoffs.join(', ')}`);
+  }
+
+  // Session history
+  if (context.sessionHistory.totalSessions > 0) {
+    sections.push(`\n## Cursor Session History (${context.sessionHistory.totalSessions} sessions, ${context.sessionHistory.messages.length} messages)`);
+    sections.push(`This is your complete conversation history with the user from Cursor IDE, in chronological order.`);
+    sections.push(`Use this to understand what has been built, discussed, and decided so far.\n`);
+    
+    // Include all messages chronologically
+    context.sessionHistory.messages.forEach((msg, i) => {
+      const timestamp = new Date(msg.timestamp).toLocaleString();
+      sections.push(`[${timestamp}] ${msg.role}:`);
+      sections.push(msg.content);
+      sections.push(''); // Empty line between messages
+    });
+  }
+
+  return sections.join('\n');
+}
+

lib/server/chat-extraction.ts

@@ -0,0 +1,64 @@
+import { getAdminDb } from '@/lib/firebase/admin';
+import { FieldValue } from 'firebase-admin/firestore';
+import type { ChatExtractionRecord } from '@/lib/types/chat-extraction';
+
+const COLLECTION = 'chat_extractions';
+
+interface CreateChatExtractionInput<TData> {
+  projectId: string;
+  knowledgeItemId: string;
+  data: TData;
+  overallCompletion: number;
+  overallConfidence: number;
+}
+
+export async function createChatExtraction<TData>(
+  input: CreateChatExtractionInput<TData>,
+): Promise<ChatExtractionRecord<TData>> {
+  const adminDb = getAdminDb();
+  const docRef = adminDb.collection(COLLECTION).doc();
+
+  const payload = {
+    id: docRef.id,
+    projectId: input.projectId,
+    knowledgeItemId: input.knowledgeItemId,
+    data: input.data,
+    overallCompletion: input.overallCompletion,
+    overallConfidence: input.overallConfidence,
+    createdAt: FieldValue.serverTimestamp(),
+    updatedAt: FieldValue.serverTimestamp(),
+  };
+
+  await docRef.set(payload);
+  const snapshot = await docRef.get();
+  return snapshot.data() as ChatExtractionRecord<TData>;
+}
+
+export async function listChatExtractions<TData>(
+  projectId: string,
+): Promise<ChatExtractionRecord<TData>[]> {
+  const adminDb = getAdminDb();
+  const querySnapshot = await adminDb
+    .collection(COLLECTION)
+    .where('projectId', '==', projectId)
+    .orderBy('createdAt', 'desc')
+    .get();
+
+  return querySnapshot.docs.map(
+    (doc) => doc.data() as ChatExtractionRecord<TData>,
+  );
+}
+
+export async function getChatExtraction<TData>(
+  extractionId: string,
+): Promise<ChatExtractionRecord<TData> | null> {
+  const adminDb = getAdminDb();
+  const docRef = adminDb.collection(COLLECTION).doc(extractionId);
+  const snapshot = await docRef.get();
+  if (!snapshot.exists) {
+    return null;
+  }
+  return snapshot.data() as ChatExtractionRecord<TData>;
+}
+
+

lib/server/chat-mode-resolver.ts

@@ -0,0 +1,190 @@
+/**
+ * Chat Mode Resolution Logic
+ * 
+ * Determines which chat mode (collector, extraction_review, vision, mvp, marketing, general)
+ * should be active based on project state.
+ */
+
+import { getAdminDb } from '@/lib/firebase/admin';
+import type { ChatMode } from '@/lib/ai/chat-modes';
+
+/**
+ * Resolve the appropriate chat mode for a project
+ * 
+ * Logic:
+ * 1. No knowledge_items → collector_mode
+ * 2. Has knowledge but no extractions → collector_mode (needs to run extraction)
+ * 3. Has extractions but no canonicalProductModel → extraction_review_mode
+ * 4. Has canonicalProductModel but no mvpPlan → vision_mode
+ * 5. Has mvpPlan but no marketingPlan → mvp_mode
+ * 6. Has marketingPlan → marketing_mode
+ * 7. Otherwise → general_chat_mode
+ * 
+ * @param projectId - Firestore project ID
+ * @returns The appropriate chat mode
+ */
+export async function resolveChatMode(projectId: string): Promise<ChatMode> {
+  try {
+    const adminDb = getAdminDb();
+
+    // Load project data
+    const projectSnapshot = await adminDb.collection('projects').doc(projectId).get();
+    if (!projectSnapshot.exists) {
+      throw new Error(`Project ${projectId} not found`);
+    }
+
+    const projectData = projectSnapshot.data() ?? {};
+    const phaseData = (projectData.phaseData ?? {}) as Record<string, any>;
+
+    // Check for knowledge_items (top-level collection)
+    const knowledgeSnapshot = await adminDb
+      .collection('knowledge_items')
+      .where('projectId', '==', projectId)
+      .limit(1)
+      .get();
+
+    const hasKnowledge = !knowledgeSnapshot.empty;
+
+    // Check for chat_extractions (top-level collection)
+    const extractionsSnapshot = await adminDb
+      .collection('chat_extractions')
+      .where('projectId', '==', projectId)
+      .limit(1)
+      .get();
+
+    const hasExtractions = !extractionsSnapshot.empty;
+
+    // Apply resolution logic
+    // PRIORITY: Check explicit phase transitions FIRST (overrides knowledge checks)
+    if (projectData.currentPhase === 'extraction_review' || projectData.currentPhase === 'analyzed') {
+      return 'extraction_review_mode';
+    }
+    
+    if (projectData.currentPhase === 'vision') {
+      return 'vision_mode';
+    }
+    
+    if (projectData.currentPhase === 'mvp') {
+      return 'mvp_mode';
+    }
+    
+    if (projectData.currentPhase === 'marketing') {
+      return 'marketing_mode';
+    }
+
+    if (!hasKnowledge) {
+      return 'collector_mode';
+    }
+
+    if (hasKnowledge && !hasExtractions) {
+      return 'collector_mode'; // Has knowledge but needs extraction
+    }
+
+    // Fallback: Has extractions but no canonicalProductModel
+    if (hasExtractions && !phaseData.canonicalProductModel) {
+      return 'extraction_review_mode';
+    }
+
+    if (phaseData.canonicalProductModel && !phaseData.mvpPlan) {
+      return 'vision_mode';
+    }
+
+    if (phaseData.mvpPlan && !phaseData.marketingPlan) {
+      return 'mvp_mode';
+    }
+
+    if (phaseData.marketingPlan) {
+      return 'marketing_mode';
+    }
+
+    return 'general_chat_mode';
+  } catch (error) {
+    console.error('[Chat Mode Resolver] Failed to resolve mode:', error);
+    // Default to collector on error
+    return 'collector_mode';
+  }
+}
+
+/**
+ * Get a summary of knowledge_items for context building
+ */
+export async function summarizeKnowledgeItems(
+  projectId: string
+): Promise<{
+  totalCount: number;
+  bySourceType: Record<string, number>;
+  recentTitles: string[];
+}> {
+  try {
+    const adminDb = getAdminDb();
+    const snapshot = await adminDb
+      .collection('knowledge_items')
+      .where('projectId', '==', projectId)
+      .orderBy('createdAt', 'desc')
+      .limit(20)
+      .get();
+
+    const totalCount = snapshot.size;
+    const bySourceType: Record<string, number> = {};
+    const recentTitles: string[] = [];
+
+    snapshot.docs.forEach((doc) => {
+      const data = doc.data();
+      const sourceType = data.sourceType ?? 'unknown';
+      bySourceType[sourceType] = (bySourceType[sourceType] ?? 0) + 1;
+
+      if (data.title && recentTitles.length < 5) {
+        recentTitles.push(data.title);
+      }
+    });
+
+    return { totalCount, bySourceType, recentTitles };
+  } catch (error) {
+    console.error('[Chat Mode Resolver] Failed to summarize knowledge:', error);
+    return { totalCount: 0, bySourceType: {}, recentTitles: [] };
+  }
+}
+
+/**
+ * Get a summary of chat_extractions for context building
+ */
+export async function summarizeExtractions(
+  projectId: string
+): Promise<{
+  totalCount: number;
+  avgConfidence: number;
+  avgCompletion: number;
+}> {
+  try {
+    const adminDb = getAdminDb();
+    const snapshot = await adminDb
+      .collection('chat_extractions')
+      .where('projectId', '==', projectId)
+      .get();
+
+    if (snapshot.empty) {
+      return { totalCount: 0, avgConfidence: 0, avgCompletion: 0 };
+    }
+
+    let sumConfidence = 0;
+    let sumCompletion = 0;
+    let count = 0;
+
+    snapshot.docs.forEach((doc) => {
+      const data = doc.data();
+      sumConfidence += data.overallConfidence ?? 0;
+      sumCompletion += data.overallCompletion ?? 0;
+      count++;
+    });
+
+    return {
+      totalCount: count,
+      avgConfidence: count > 0 ? sumConfidence / count : 0,
+      avgCompletion: count > 0 ? sumCompletion / count : 0,
+    };
+  } catch (error) {
+    console.error('[Chat Mode Resolver] Failed to summarize extractions:', error);
+    return { totalCount: 0, avgConfidence: 0, avgCompletion: 0 };
+  }
+}
+

lib/server/github-analyzer.ts

@@ -0,0 +1,298 @@
+/**
+ * GitHub Repository Analyzer
+ * Fetches and analyzes repository structure and key files for AI context
+ */
+
+import { getAdminDb } from '@/lib/firebase/admin';
+
+interface RepositoryAnalysis {
+  repoFullName: string;
+  totalFiles: number;
+  fileStructure: {
+    directories: string[];
+    keyFiles: string[];
+  };
+  readme: string | null;
+  packageJson: Record<string, unknown> | null;
+  techStack: string[];
+  summary: string;
+}
+
+/**
+ * Analyze a GitHub repository to extract key information for AI context
+ */
+export async function analyzeGitHubRepository(
+  userId: string,
+  repoFullName: string,
+  branch = 'main'
+): Promise<RepositoryAnalysis | null> {
+  try {
+    const adminDb = getAdminDb();
+    
+    // Get GitHub access token
+    const connectionDoc = await adminDb
+      .collection('githubConnections')
+      .doc(userId)
+      .get();
+
+    if (!connectionDoc.exists) {
+      console.log('[GitHub Analyzer] No GitHub connection found');
+      return null;
+    }
+
+    const connection = connectionDoc.data()!;
+    const accessToken = connection.accessToken;
+    const [owner, repo] = repoFullName.split('/');
+
+    // Fetch repository tree
+    const treeResponse = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`,
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/vnd.github.v3+json',
+        },
+      }
+    );
+
+    if (!treeResponse.ok) {
+      console.error('[GitHub Analyzer] Failed to fetch tree:', treeResponse.statusText);
+      return null;
+    }
+
+    const treeData = await treeResponse.json();
+    
+    // Extract directories and key files
+    const directories = new Set<string>();
+    const keyFiles: string[] = [];
+    let totalFiles = 0;
+
+    treeData.tree?.forEach((item: { path: string; type: string }) => {
+      if (item.type === 'blob') {
+        totalFiles++;
+        
+        // Track key files
+        const fileName = item.path.toLowerCase();
+        if (
+          fileName === 'readme.md' ||
+          fileName === 'package.json' ||
+          fileName === 'requirements.txt' ||
+          fileName === 'cargo.toml' ||
+          fileName === 'go.mod' ||
+          fileName === 'pom.xml' ||
+          fileName.startsWith('dockerfile')
+        ) {
+          keyFiles.push(item.path);
+        }
+      }
+      
+      // Track top-level directories
+      const parts = item.path.split('/');
+      if (parts.length > 1) {
+        directories.add(parts[0]);
+      }
+    });
+
+    // Fetch README content (truncate to first 3000 chars to avoid bloating prompts)
+    let readme: string | null = null;
+    const readmePath = keyFiles.find(f => f.toLowerCase().endsWith('readme.md'));
+    if (readmePath) {
+      const fullReadme = await fetchFileContent(accessToken, owner, repo, readmePath, branch);
+      if (fullReadme) {
+        // Truncate to first 3000 characters (roughly 750 tokens)
+        readme = fullReadme.length > 3000 
+          ? fullReadme.substring(0, 3000) + '\n\n[... README truncated for brevity ...]'
+          : fullReadme;
+      }
+    }
+
+    // Fetch package.json content
+    let packageJson: Record<string, unknown> | null = null;
+    const packageJsonPath = keyFiles.find(f => f.toLowerCase().endsWith('package.json'));
+    if (packageJsonPath) {
+      const content = await fetchFileContent(accessToken, owner, repo, packageJsonPath, branch);
+      if (content) {
+        try {
+          packageJson = JSON.parse(content);
+        } catch (e) {
+          console.error('[GitHub Analyzer] Failed to parse package.json');
+        }
+      }
+    }
+
+    // Detect tech stack
+    const techStack = detectTechStack(keyFiles, Array.from(directories), packageJson);
+
+    // Generate summary
+    const summary = generateRepositorySummary({
+      repoFullName,
+      totalFiles,
+      directories: Array.from(directories),
+      keyFiles,
+      techStack,
+      readme,
+      packageJson,
+    });
+
+    return {
+      repoFullName,
+      totalFiles,
+      fileStructure: {
+        directories: Array.from(directories).slice(0, 20), // Limit to top 20
+        keyFiles,
+      },
+      readme: readme ? readme.substring(0, 2000) : null, // First 2000 chars
+      packageJson,
+      techStack,
+      summary,
+    };
+  } catch (error) {
+    console.error('[GitHub Analyzer] Error analyzing repository:', error);
+    return null;
+  }
+}
+
+/**
+ * Fetch file content from GitHub
+ */
+async function fetchFileContent(
+  accessToken: string,
+  owner: string,
+  repo: string,
+  path: string,
+  branch: string
+): Promise<string | null> {
+  try {
+    const response = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/contents/${encodeURIComponent(path)}?ref=${branch}`,
+      {
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          Accept: 'application/vnd.github.v3+json',
+        },
+      }
+    );
+
+    if (!response.ok) return null;
+
+    const data = await response.json();
+    return Buffer.from(data.content, 'base64').toString('utf-8');
+  } catch (error) {
+    console.error(`[GitHub Analyzer] Failed to fetch ${path}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Detect tech stack from repository structure
+ */
+function detectTechStack(
+  keyFiles: string[],
+  directories: string[],
+  packageJson: Record<string, unknown> | null
+): string[] {
+  const stack: string[] = [];
+
+  // From key files
+  if (keyFiles.some(f => f.toLowerCase().includes('package.json'))) {
+    stack.push('Node.js/JavaScript');
+    
+    if (packageJson) {
+      const deps = { 
+        ...(packageJson.dependencies as Record<string, unknown> || {}), 
+        ...(packageJson.devDependencies as Record<string, unknown> || {}) 
+      };
+      
+      if (deps.next) stack.push('Next.js');
+      if (deps.react) stack.push('React');
+      if (deps.vue) stack.push('Vue');
+      if (deps.express) stack.push('Express');
+      if (deps.typescript) stack.push('TypeScript');
+    }
+  }
+  
+  if (keyFiles.some(f => f.toLowerCase().includes('requirements.txt') || f.toLowerCase().includes('pyproject.toml'))) {
+    stack.push('Python');
+  }
+  
+  if (keyFiles.some(f => f.toLowerCase().includes('cargo.toml'))) {
+    stack.push('Rust');
+  }
+  
+  if (keyFiles.some(f => f.toLowerCase().includes('go.mod'))) {
+    stack.push('Go');
+  }
+  
+  if (keyFiles.some(f => f.toLowerCase().includes('pom.xml') || f.toLowerCase().includes('build.gradle'))) {
+    stack.push('Java');
+  }
+  
+  if (keyFiles.some(f => f.toLowerCase().startsWith('dockerfile'))) {
+    stack.push('Docker');
+  }
+
+  // From directories
+  if (directories.includes('.github')) stack.push('GitHub Actions');
+  if (directories.includes('terraform') || directories.includes('infrastructure')) {
+    stack.push('Infrastructure as Code');
+  }
+
+  return stack;
+}
+
+/**
+ * Generate a human-readable summary
+ */
+function generateRepositorySummary(analysis: {
+  repoFullName: string;
+  totalFiles: number;
+  directories: string[];
+  keyFiles: string[];
+  techStack: string[];
+  readme: string | null;
+  packageJson: Record<string, unknown> | null;
+}): string {
+  const parts: string[] = [];
+
+  parts.push(`## Repository Analysis: ${analysis.repoFullName}`);
+  parts.push(`\n**Structure:**`);
+  parts.push(`- Total files: ${analysis.totalFiles}`);
+  
+  if (analysis.directories.length > 0) {
+    parts.push(`- Main directories: ${analysis.directories.slice(0, 15).join(', ')}`);
+  }
+  
+  if (analysis.techStack.length > 0) {
+    parts.push(`\n**Tech Stack:** ${analysis.techStack.join(', ')}`);
+  }
+  
+  if (analysis.packageJson) {
+    const pkg = analysis.packageJson;
+    parts.push(`\n**Package Info:**`);
+    if (pkg.name) parts.push(`- Name: ${pkg.name}`);
+    if (pkg.description) parts.push(`- Description: ${pkg.description}`);
+    if (pkg.version) parts.push(`- Version: ${pkg.version}`);
+    
+    // Show key dependencies
+    const deps = pkg.dependencies as Record<string, string> || {};
+    const devDeps = pkg.devDependencies as Record<string, string> || {};
+    const allDeps = { ...deps, ...devDeps };
+    const keyDeps = Object.keys(allDeps).slice(0, 10);
+    if (keyDeps.length > 0) {
+      parts.push(`- Key dependencies: ${keyDeps.join(', ')}`);
+    }
+  }
+  
+  if (analysis.readme) {
+    parts.push(`\n**README Content:**`);
+    // Get first few paragraphs or up to 1000 chars
+    const readmeExcerpt = analysis.readme.substring(0, 1000);
+    parts.push(readmeExcerpt);
+    if (analysis.readme.length > 1000) {
+      parts.push('...(truncated)');
+    }
+  }
+
+  return parts.join('\n');
+}
+

lib/server/knowledge.ts

@@ -0,0 +1,74 @@
+import { getAdminDb } from '@/lib/firebase/admin';
+import { FieldValue } from 'firebase-admin/firestore';
+import type {
+  KnowledgeItem,
+  KnowledgeSourceMeta,
+  KnowledgeSourceType,
+} from '@/lib/types/knowledge';
+
+const COLLECTION = 'knowledge_items';
+
+interface CreateKnowledgeItemInput {
+  projectId: string;
+  sourceType: KnowledgeSourceType;
+  title?: string | null;
+  content: string;
+  sourceMeta?: KnowledgeSourceMeta;
+}
+
+export async function createKnowledgeItem(
+  input: CreateKnowledgeItemInput,
+): Promise<KnowledgeItem> {
+  const adminDb = getAdminDb();
+  const docRef = adminDb.collection(COLLECTION).doc();
+
+  const payload = {
+    id: docRef.id,
+    projectId: input.projectId,
+    sourceType: input.sourceType,
+    title: input.title ?? null,
+    content: input.content,
+    sourceMeta: input.sourceMeta ?? null,
+    createdAt: FieldValue.serverTimestamp(),
+    updatedAt: FieldValue.serverTimestamp(),
+  };
+
+  await docRef.set(payload);
+  const snapshot = await docRef.get();
+  return snapshot.data() as KnowledgeItem;
+}
+
+export async function getKnowledgeItem(
+  projectId: string,
+  knowledgeItemId: string,
+): Promise<KnowledgeItem | null> {
+  const adminDb = getAdminDb();
+  const docRef = adminDb.collection(COLLECTION).doc(knowledgeItemId);
+  const snapshot = await docRef.get();
+
+  if (!snapshot.exists) {
+    return null;
+  }
+
+  const data = snapshot.data() as KnowledgeItem;
+  if (data.projectId !== projectId) {
+    return null;
+  }
+
+  return data;
+}
+
+export async function listKnowledgeItems(
+  projectId: string,
+): Promise<KnowledgeItem[]> {
+  const adminDb = getAdminDb();
+  const querySnapshot = await adminDb
+    .collection(COLLECTION)
+    .where('projectId', '==', projectId)
+    .orderBy('createdAt', 'desc')
+    .get();
+
+  return querySnapshot.docs.map((doc) => doc.data() as KnowledgeItem);
+}
+
+

lib/server/logs.ts

@@ -0,0 +1,232 @@
+/**
+ * Server-side logging utilities
+ * 
+ * Logs project events to Firestore for monitoring, debugging, and analytics.
+ */
+
+import { getAdminDb } from '@/lib/firebase/admin';
+import { FieldValue } from 'firebase-admin/firestore';
+import type { CreateProjectLogInput, ProjectLogEntry, ProjectLogFilters, ProjectLogStats } from '@/lib/types/logs';
+
+/**
+ * Log a project-related event
+ * 
+ * This is a fire-and-forget operation - errors are logged but not thrown
+ * to avoid impacting the main request flow.
+ * 
+ * @param input - Log entry data
+ * 
+ * @example
+ * ```typescript
+ * await logProjectEvent({
+ *   projectId: 'proj123',
+ *   userId: 'user456',
+ *   eventType: 'chat_interaction',
+ *   mode: 'vision_mode',
+ *   phase: 'vision_ready',
+ *   artifactsUsed: ['Product Model', '5 Vector Chunks'],
+ *   usedVectorSearch: true,
+ *   vectorChunkCount: 5,
+ *   promptVersion: '1.0',
+ *   modelUsed: 'gemini-2.0-flash-exp',
+ *   success: true,
+ *   errorMessage: null,
+ * });
+ * ```
+ */
+export async function logProjectEvent(input: CreateProjectLogInput): Promise<void> {
+  try {
+    const adminDb = getAdminDb();
+    const docRef = adminDb.collection('project_logs').doc();
+
+    await docRef.set({
+      ...input,
+      id: docRef.id,
+      createdAt: FieldValue.serverTimestamp(),
+    });
+
+    // Silent success
+  } catch (error) {
+    // Log to console but don't throw - logging should never break the main flow
+    console.error('[Logs] Failed to log project event:', error);
+  }
+}
+
+/**
+ * Query project logs with filters
+ * 
+ * @param filters - Query filters
+ * @returns Array of log entries
+ */
+export async function queryProjectLogs(
+  filters: ProjectLogFilters
+): Promise<ProjectLogEntry[]> {
+  try {
+    const adminDb = getAdminDb();
+    let query = adminDb.collection('project_logs').orderBy('createdAt', 'desc');
+
+    // Apply filters
+    if (filters.projectId) {
+      query = query.where('projectId', '==', filters.projectId) as any;
+    }
+
+    if (filters.userId) {
+      query = query.where('userId', '==', filters.userId) as any;
+    }
+
+    if (filters.eventType) {
+      query = query.where('eventType', '==', filters.eventType) as any;
+    }
+
+    if (filters.mode) {
+      query = query.where('mode', '==', filters.mode) as any;
+    }
+
+    if (filters.phase) {
+      query = query.where('phase', '==', filters.phase) as any;
+    }
+
+    if (filters.success !== undefined) {
+      query = query.where('success', '==', filters.success) as any;
+    }
+
+    if (filters.startDate) {
+      query = query.where('createdAt', '>=', filters.startDate) as any;
+    }
+
+    if (filters.endDate) {
+      query = query.where('createdAt', '<=', filters.endDate) as any;
+    }
+
+    if (filters.limit) {
+      query = query.limit(filters.limit) as any;
+    }
+
+    const snapshot = await query.get();
+
+    return snapshot.docs.map((doc) => {
+      const data = doc.data();
+      return {
+        ...data,
+        createdAt: data.createdAt?.toDate?.() ?? data.createdAt,
+      } as ProjectLogEntry;
+    });
+  } catch (error) {
+    console.error('[Logs] Failed to query project logs:', error);
+    return [];
+  }
+}
+
+/**
+ * Get aggregated stats for a project
+ * 
+ * @param projectId - Project ID to analyze
+ * @param since - Optional date to filter from
+ * @returns Aggregated statistics
+ */
+export async function getProjectLogStats(
+  projectId: string,
+  since?: Date
+): Promise<ProjectLogStats> {
+  try {
+    const filters: ProjectLogFilters = { projectId, limit: 1000 };
+    if (since) {
+      filters.startDate = since;
+    }
+
+    const logs = await queryProjectLogs(filters);
+
+    const stats: ProjectLogStats = {
+      totalLogs: logs.length,
+      successCount: 0,
+      errorCount: 0,
+      byEventType: {},
+      byMode: {},
+      avgVectorChunks: 0,
+      vectorSearchUsageRate: 0,
+    };
+
+    let totalVectorChunks = 0;
+    let vectorSearchCount = 0;
+
+    logs.forEach((log) => {
+      // Success/error counts
+      if (log.success) {
+        stats.successCount++;
+      } else {
+        stats.errorCount++;
+      }
+
+      // By event type
+      stats.byEventType[log.eventType] = (stats.byEventType[log.eventType] ?? 0) + 1;
+
+      // By mode
+      if (log.mode) {
+        stats.byMode[log.mode] = (stats.byMode[log.mode] ?? 0) + 1;
+      }
+
+      // Vector search stats
+      if (log.usedVectorSearch) {
+        vectorSearchCount++;
+        if (log.vectorChunkCount) {
+          totalVectorChunks += log.vectorChunkCount;
+        }
+      }
+    });
+
+    // Calculate averages
+    if (vectorSearchCount > 0) {
+      stats.avgVectorChunks = totalVectorChunks / vectorSearchCount;
+      stats.vectorSearchUsageRate = vectorSearchCount / logs.length;
+    }
+
+    return stats;
+  } catch (error) {
+    console.error('[Logs] Failed to get project log stats:', error);
+    return {
+      totalLogs: 0,
+      successCount: 0,
+      errorCount: 0,
+      byEventType: {},
+      byMode: {},
+      avgVectorChunks: 0,
+      vectorSearchUsageRate: 0,
+    };
+  }
+}
+
+/**
+ * Delete old logs (for maintenance/cleanup)
+ * 
+ * @param before - Delete logs older than this date
+ * @returns Number of logs deleted
+ */
+export async function deleteOldLogs(before: Date): Promise<number> {
+  try {
+    const adminDb = getAdminDb();
+    const snapshot = await adminDb
+      .collection('project_logs')
+      .where('createdAt', '<', before)
+      .limit(500) // Process in batches to avoid overwhelming Firestore
+      .get();
+
+    if (snapshot.empty) {
+      return 0;
+    }
+
+    const batch = adminDb.batch();
+    snapshot.docs.forEach((doc) => {
+      batch.delete(doc.ref);
+    });
+
+    await batch.commit();
+
+    console.log(`[Logs] Deleted ${snapshot.size} old logs`);
+
+    return snapshot.size;
+  } catch (error) {
+    console.error('[Logs] Failed to delete old logs:', error);
+    return 0;
+  }
+}
+

lib/server/product-model.ts

@@ -0,0 +1,102 @@
+import { listChatExtractions } from '@/lib/server/chat-extraction';
+import { clamp, nowIso, persistPhaseArtifacts, uniqueStrings, toStage } from '@/lib/server/projects';
+import type { CanonicalProductModel } from '@/lib/types/product-model';
+import type { ChatExtractionRecord } from '@/lib/types/chat-extraction';
+
+const average = (numbers: number[]) =>
+  numbers.length ? numbers.reduce((sum, value) => sum + value, 0) / numbers.length : 0;
+
+export async function buildCanonicalProductModel(projectId: string): Promise<CanonicalProductModel> {
+  const extractions = await listChatExtractions(projectId);
+  if (!extractions.length) {
+    throw new Error('No chat extractions found for project');
+  }
+
+  const completionAvg = average(
+    extractions.map(
+      (record) =>
+        (record.data as any)?.summary_scores?.overall_completion ?? record.overallCompletion ?? 0,
+    ),
+  );
+  const confidenceAvg = average(
+    extractions.map(
+      (record) =>
+        (record.data as any)?.summary_scores?.overall_confidence ?? record.overallConfidence ?? 0,
+    ),
+  );
+
+  const canonical = mapExtractionToCanonical(
+    projectId,
+    pickHighestConfidence(extractions as any),
+    completionAvg,
+    confidenceAvg,
+  );
+
+  await persistPhaseArtifacts(projectId, (phaseData, phaseScores, phaseHistory) => {
+    phaseData.canonicalProductModel = canonical;
+    phaseScores.vision = {
+      overallCompletion: canonical.overallCompletion,
+      overallConfidence: canonical.overallConfidence,
+      updatedAt: nowIso(),
+    };
+    phaseHistory.push({ phase: 'vision', status: 'completed', timestamp: nowIso() });
+    return { phaseData, phaseScores, phaseHistory, nextPhase: 'vision_ready' };
+  });
+
+  return canonical;
+}
+
+function pickHighestConfidence(records: ChatExtractionRecord[]) {
+  return records.reduce((best, record) =>
+    record.overallConfidence > best.overallConfidence ? record : best,
+  );
+}
+
+function mapExtractionToCanonical(
+  projectId: string,
+  record: ChatExtractionRecord,
+  completionAvg: number,
+  confidenceAvg: number,
+): CanonicalProductModel {
+  const data = record.data;
+
+  const coreFeatures = data.solution_and_features.core_features.map(
+    (feature) => feature.name || feature.description,
+  );
+  const niceToHaveFeatures = data.solution_and_features.nice_to_have_features.map(
+    (feature) => feature.name || feature.description,
+  );
+
+  return {
+    projectId,
+    workingTitle: data.project_summary.working_title ?? null,
+    oneLiner: data.project_summary.one_liner ?? null,
+    problem: data.product_vision.problem_statement.description ?? null,
+    targetUser: data.target_users.primary_segment.description ?? null,
+    desiredOutcome: data.product_vision.target_outcome.description ?? null,
+    coreSolution: data.solution_and_features.core_solution.description ?? null,
+    coreFeatures: uniqueStrings(coreFeatures),
+    niceToHaveFeatures: uniqueStrings(niceToHaveFeatures),
+    marketCategory: data.market_and_competition.market_category.description ?? null,
+    competitors: uniqueStrings(
+      data.market_and_competition.competitors.map((competitor) => competitor.name),
+    ),
+    techStack: uniqueStrings(
+      data.tech_and_constraints.stack_mentions.map((item) => item.description),
+    ),
+    constraints: uniqueStrings(
+      data.tech_and_constraints.constraints.map((constraint) => constraint.description),
+    ),
+    currentStage: toStage(data.project_summary.stage),
+    shortTermGoals: uniqueStrings(
+      data.goals_and_success.short_term_goals.map((goal) => goal.description),
+    ),
+    longTermGoals: uniqueStrings(
+      data.goals_and_success.long_term_goals.map((goal) => goal.description),
+    ),
+    overallCompletion: clamp(completionAvg),
+    overallConfidence: clamp(confidenceAvg),
+  };
+}
+
+

lib/server/project-artifacts.ts

@@ -0,0 +1,2 @@
+export {};
+

lib/server/projects.ts

@@ -0,0 +1,64 @@
+import { FieldValue } from 'firebase-admin/firestore';
+import { getAdminDb } from '@/lib/firebase/admin';
+import type {
+  ProjectPhase,
+  ProjectPhaseData,
+  ProjectPhaseScores,
+  ProjectStage,
+} from '@/lib/types/project-artifacts';
+
+export const clamp = (value: number) => Math.max(0, Math.min(1, value));
+export const nowIso = () => new Date().toISOString();
+
+export function uniqueStrings(values: Array<string | null | undefined>): string[] {
+  return Array.from(new Set(values.filter((value): value is string => Boolean(value))));
+}
+
+export function toStage(stage?: string | null): ProjectStage {
+  const allowed: ProjectStage[] = ['idea', 'prototype', 'mvp_in_progress', 'live_beta', 'live_paid', 'unknown'];
+  if (!stage) return 'unknown';
+  return allowed.includes(stage as ProjectStage) ? (stage as ProjectStage) : 'unknown';
+}
+
+export async function loadPhaseContainers(projectId: string) {
+  const adminDb = getAdminDb();
+  const projectRef = adminDb.collection('projects').doc(projectId);
+  const snapshot = await projectRef.get();
+  const doc = snapshot.data() || {};
+  const phaseData = (doc.phaseData ?? {}) as ProjectPhaseData;
+  const phaseScores = (doc.phaseScores ?? {}) as ProjectPhaseScores;
+  const phaseHistory = Array.isArray(doc.phaseHistory) ? [...doc.phaseHistory] : [];
+  return { projectRef, phaseData, phaseScores, phaseHistory };
+}
+
+interface PersistencePayload {
+  phaseData: ProjectPhaseData;
+  phaseScores: ProjectPhaseScores;
+  phaseHistory: Array<Record<string, unknown>>;
+  nextPhase?: ProjectPhase;
+}
+
+export async function persistPhaseArtifacts(
+  projectId: string,
+  builder: (
+    phaseData: ProjectPhaseData,
+    phaseScores: ProjectPhaseScores,
+    phaseHistory: Array<Record<string, unknown>>,
+  ) => PersistencePayload,
+) {
+  const { projectRef, phaseData, phaseScores, phaseHistory } = await loadPhaseContainers(projectId);
+  const payload = builder(phaseData, phaseScores, phaseHistory);
+
+  await projectRef.set(
+    {
+      phaseData: payload.phaseData,
+      phaseScores: payload.phaseScores,
+      phaseHistory: payload.phaseHistory,
+      ...(payload.nextPhase ? { currentPhase: payload.nextPhase, phaseStatus: 'completed' as const } : {}),
+      updatedAt: FieldValue.serverTimestamp(),
+    },
+    { merge: true },
+  );
+}
+
+

lib/server/vector-memory.ts

@@ -0,0 +1,453 @@
+/**
+ * Server-side helpers for AlloyDB vector memory operations
+ * 
+ * Handles CRUD operations on knowledge_chunks and semantic search.
+ */
+
+import { getAlloyDbClient, executeQuery, getPooledClient } from '@/lib/db/alloydb';
+import type {
+  KnowledgeChunk,
+  KnowledgeChunkRow,
+  KnowledgeChunkSearchResult,
+  VectorSearchOptions,
+  CreateKnowledgeChunkInput,
+  BatchCreateKnowledgeChunksInput,
+} from '@/lib/types/vector-memory';
+
+/**
+ * Convert database row (snake_case) to TypeScript object (camelCase)
+ */
+function rowToKnowledgeChunk(row: KnowledgeChunkRow): KnowledgeChunk {
+  return {
+    id: row.id,
+    projectId: row.project_id,
+    knowledgeItemId: row.knowledge_item_id,
+    chunkIndex: row.chunk_index,
+    content: row.content,
+    sourceType: row.source_type,
+    importance: row.importance,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+/**
+ * Retrieve relevant knowledge chunks using vector similarity search
+ * 
+ * @param projectId - Firestore project ID to filter by
+ * @param queryEmbedding - Vector embedding of the query (e.g., user's question)
+ * @param options - Search options (limit, filters, etc.)
+ * @returns Array of chunks ordered by similarity (most relevant first)
+ * 
+ * @example
+ * ```typescript
+ * const embedding = await embedText("What's the MVP scope?");
+ * const chunks = await retrieveRelevantChunks('proj123', embedding, { limit: 10, minSimilarity: 0.7 });
+ * ```
+ */
+export async function retrieveRelevantChunks(
+  projectId: string,
+  queryEmbedding: number[],
+  options: VectorSearchOptions = {}
+): Promise<KnowledgeChunkSearchResult[]> {
+  const {
+    limit = 10,
+    minSimilarity,
+    sourceTypes,
+    importanceLevels,
+  } = options;
+
+  try {
+    // Build the query with optional filters
+    let queryText = `
+      SELECT 
+        id, 
+        project_id, 
+        knowledge_item_id, 
+        chunk_index, 
+        content, 
+        source_type, 
+        importance, 
+        created_at, 
+        updated_at,
+        1 - (embedding <=> $1::vector) AS similarity
+      FROM knowledge_chunks
+      WHERE project_id = $2
+    `;
+
+    const params: any[] = [JSON.stringify(queryEmbedding), projectId];
+    let paramIndex = 3;
+
+    // Filter by source types
+    if (sourceTypes && sourceTypes.length > 0) {
+      queryText += ` AND source_type = ANY($${paramIndex})`;
+      params.push(sourceTypes);
+      paramIndex++;
+    }
+
+    // Filter by importance levels
+    if (importanceLevels && importanceLevels.length > 0) {
+      queryText += ` AND importance = ANY($${paramIndex})`;
+      params.push(importanceLevels);
+      paramIndex++;
+    }
+
+    // Filter by minimum similarity
+    if (minSimilarity !== undefined) {
+      queryText += ` AND (1 - (embedding <=> $1::vector)) >= $${paramIndex}`;
+      params.push(minSimilarity);
+      paramIndex++;
+    }
+
+    // Order by similarity and limit
+    queryText += ` ORDER BY embedding <=> $1::vector LIMIT $${paramIndex}`;
+    params.push(limit);
+
+    const result = await executeQuery<KnowledgeChunkRow & { similarity: number }>(
+      queryText,
+      params
+    );
+
+    return result.rows.map((row) => ({
+      ...rowToKnowledgeChunk(row),
+      similarity: row.similarity,
+    }));
+  } catch (error) {
+    console.error('[Vector Memory] Failed to retrieve relevant chunks:', error);
+    throw new Error(
+      `Failed to retrieve chunks: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Create a single knowledge chunk
+ */
+export async function createKnowledgeChunk(
+  input: CreateKnowledgeChunkInput
+): Promise<KnowledgeChunk> {
+  const {
+    projectId,
+    knowledgeItemId,
+    chunkIndex,
+    content,
+    embedding,
+    sourceType = null,
+    importance = null,
+  } = input;
+
+  try {
+    const queryText = `
+      INSERT INTO knowledge_chunks (
+        project_id, 
+        knowledge_item_id, 
+        chunk_index, 
+        content, 
+        embedding, 
+        source_type, 
+        importance
+      )
+      VALUES ($1, $2, $3, $4, $5::vector, $6, $7)
+      RETURNING 
+        id, 
+        project_id, 
+        knowledge_item_id, 
+        chunk_index, 
+        content, 
+        source_type, 
+        importance, 
+        created_at, 
+        updated_at
+    `;
+
+    const result = await executeQuery<KnowledgeChunkRow>(queryText, [
+      projectId,
+      knowledgeItemId,
+      chunkIndex,
+      content,
+      JSON.stringify(embedding),
+      sourceType,
+      importance,
+    ]);
+
+    if (result.rows.length === 0) {
+      throw new Error('Failed to insert knowledge chunk');
+    }
+
+    return rowToKnowledgeChunk(result.rows[0]);
+  } catch (error) {
+    console.error('[Vector Memory] Failed to create knowledge chunk:', error);
+    throw new Error(
+      `Failed to create chunk: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Batch create multiple knowledge chunks efficiently
+ * 
+ * Uses a transaction to ensure atomicity.
+ */
+export async function batchCreateKnowledgeChunks(
+  input: BatchCreateKnowledgeChunksInput
+): Promise<KnowledgeChunk[]> {
+  const { projectId, knowledgeItemId, chunks } = input;
+
+  if (chunks.length === 0) {
+    return [];
+  }
+
+  const client = await getPooledClient();
+
+  try {
+    await client.query('BEGIN');
+
+    const createdChunks: KnowledgeChunk[] = [];
+
+    for (const chunk of chunks) {
+      const queryText = `
+        INSERT INTO knowledge_chunks (
+          project_id, 
+          knowledge_item_id, 
+          chunk_index, 
+          content, 
+          embedding, 
+          source_type, 
+          importance
+        )
+        VALUES ($1, $2, $3, $4, $5::vector, $6, $7)
+        RETURNING 
+          id, 
+          project_id, 
+          knowledge_item_id, 
+          chunk_index, 
+          content, 
+          source_type, 
+          importance, 
+          created_at, 
+          updated_at
+      `;
+
+      const result = await client.query<KnowledgeChunkRow>(queryText, [
+        projectId,
+        knowledgeItemId,
+        chunk.chunkIndex,
+        chunk.content,
+        JSON.stringify(chunk.embedding),
+        chunk.sourceType ?? null,
+        chunk.importance ?? null,
+      ]);
+
+      if (result.rows.length > 0) {
+        createdChunks.push(rowToKnowledgeChunk(result.rows[0]));
+      }
+    }
+
+    await client.query('COMMIT');
+
+    console.log(
+      `[Vector Memory] Batch created ${createdChunks.length} chunks for knowledge_item ${knowledgeItemId}`
+    );
+
+    return createdChunks;
+  } catch (error) {
+    await client.query('ROLLBACK');
+    console.error('[Vector Memory] Failed to batch create chunks:', error);
+    throw new Error(
+      `Failed to batch create chunks: ${error instanceof Error ? error.message : String(error)}`
+    );
+  } finally {
+    client.release();
+  }
+}
+
+/**
+ * Delete all chunks for a specific knowledge_item
+ * 
+ * Used when regenerating chunks or removing a knowledge_item.
+ */
+export async function deleteChunksForKnowledgeItem(
+  knowledgeItemId: string
+): Promise<number> {
+  try {
+    const queryText = `
+      DELETE FROM knowledge_chunks 
+      WHERE knowledge_item_id = $1
+      RETURNING id
+    `;
+
+    const result = await executeQuery(queryText, [knowledgeItemId]);
+
+    console.log(
+      `[Vector Memory] Deleted ${result.rowCount ?? 0} chunks for knowledge_item ${knowledgeItemId}`
+    );
+
+    return result.rowCount ?? 0;
+  } catch (error) {
+    console.error('[Vector Memory] Failed to delete chunks:', error);
+    throw new Error(
+      `Failed to delete chunks: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Delete all chunks for a specific project
+ * 
+ * Used when cleaning up or resetting a project.
+ */
+export async function deleteChunksForProject(projectId: string): Promise<number> {
+  try {
+    const queryText = `
+      DELETE FROM knowledge_chunks 
+      WHERE project_id = $1
+      RETURNING id
+    `;
+
+    const result = await executeQuery(queryText, [projectId]);
+
+    console.log(
+      `[Vector Memory] Deleted ${result.rowCount ?? 0} chunks for project ${projectId}`
+    );
+
+    return result.rowCount ?? 0;
+  } catch (error) {
+    console.error('[Vector Memory] Failed to delete project chunks:', error);
+    throw new Error(
+      `Failed to delete project chunks: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+/**
+ * Get chunk count for a knowledge_item
+ */
+export async function getChunkCountForKnowledgeItem(
+  knowledgeItemId: string
+): Promise<number> {
+  try {
+    const result = await executeQuery<{ count: string }>(
+      'SELECT COUNT(*) as count FROM knowledge_chunks WHERE knowledge_item_id = $1',
+      [knowledgeItemId]
+    );
+
+    return parseInt(result.rows[0]?.count ?? '0', 10);
+  } catch (error) {
+    console.error('[Vector Memory] Failed to get chunk count:', error);
+    return 0;
+  }
+}
+
+/**
+ * Get chunk count for a project
+ */
+export async function getChunkCountForProject(projectId: string): Promise<number> {
+  try {
+    const result = await executeQuery<{ count: string }>(
+      'SELECT COUNT(*) as count FROM knowledge_chunks WHERE project_id = $1',
+      [projectId]
+    );
+
+    return parseInt(result.rows[0]?.count ?? '0', 10);
+  } catch (error) {
+    console.error('[Vector Memory] Failed to get project chunk count:', error);
+    return 0;
+  }
+}
+
+/**
+ * Regenerate knowledge_chunks for a single knowledge_item
+ * 
+ * This is the main pipeline that:
+ * 1. Chunks the knowledge_item.content
+ * 2. Generates embeddings for each chunk
+ * 3. Deletes existing chunks for this item
+ * 4. Inserts new chunks into AlloyDB
+ * 
+ * @param knowledgeItem - The knowledge item to process
+ * 
+ * @example
+ * ```typescript
+ * const knowledgeItem = await getKnowledgeItem(projectId, itemId);
+ * await writeKnowledgeChunksForItem(knowledgeItem);
+ * ```
+ */
+export async function writeKnowledgeChunksForItem(
+  knowledgeItem: {
+    id: string;
+    projectId: string;
+    content: string;
+    sourceMeta?: { sourceType?: string; importance?: 'primary' | 'supporting' | 'irrelevant' };
+  }
+): Promise<void> {
+  const { chunkText } = await import('@/lib/ai/chunking');
+  const { embedTextBatch } = await import('@/lib/ai/embeddings');
+
+  try {
+    console.log(
+      `[Vector Memory] Starting chunking pipeline for knowledge_item ${knowledgeItem.id}`
+    );
+
+    // Step 1: Chunk the content
+    const textChunks = chunkText(knowledgeItem.content, {
+      maxTokens: 800,
+      overlapChars: 200,
+      preserveParagraphs: true,
+    });
+
+    if (textChunks.length === 0) {
+      console.warn(
+        `[Vector Memory] No chunks generated for knowledge_item ${knowledgeItem.id} - content may be empty`
+      );
+      return;
+    }
+
+    console.log(
+      `[Vector Memory] Generated ${textChunks.length} chunks for knowledge_item ${knowledgeItem.id}`
+    );
+
+    // Step 2: Generate embeddings for all chunks
+    const chunkTexts = textChunks.map((chunk) => chunk.text);
+    const embeddings = await embedTextBatch(chunkTexts, {
+      delayMs: 50, // Small delay to avoid rate limiting
+      skipEmpty: true,
+    });
+
+    if (embeddings.length !== textChunks.length) {
+      throw new Error(
+        `Embedding count mismatch: got ${embeddings.length}, expected ${textChunks.length}`
+      );
+    }
+
+    // Step 3: Delete existing chunks for this knowledge_item
+    await deleteChunksForKnowledgeItem(knowledgeItem.id);
+
+    // Step 4: Insert new chunks
+    const chunksToInsert = textChunks.map((chunk, index) => ({
+      chunkIndex: chunk.index,
+      content: chunk.text,
+      embedding: embeddings[index],
+      sourceType: knowledgeItem.sourceMeta?.sourceType ?? null,
+      importance: knowledgeItem.sourceMeta?.importance ?? null,
+    }));
+
+    await batchCreateKnowledgeChunks({
+      projectId: knowledgeItem.projectId,
+      knowledgeItemId: knowledgeItem.id,
+      chunks: chunksToInsert,
+    });
+
+    console.log(
+      `[Vector Memory] Successfully processed ${chunksToInsert.length} chunks for knowledge_item ${knowledgeItem.id}`
+    );
+  } catch (error) {
+    console.error(
+      `[Vector Memory] Failed to write chunks for knowledge_item ${knowledgeItem.id}:`,
+      error
+    );
+    throw new Error(
+      `Failed to write chunks: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+

lib/types.ts

@@ -0,0 +1,90 @@
+// Database Types
+
+export interface Session {
+  id: number;
+  session_id: string;
+  project_id: number;
+  user_id: number;
+  started_at: Date;
+  last_updated: Date;
+  conversation: Message[];
+  file_changes: FileChange[];
+  message_count: number;
+  duration_minutes: number;
+  file_change_count: number;
+  summary?: string;
+  total_tokens?: number;
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  estimated_cost_usd?: number;
+  primary_ai_model?: string;
+  ide_name?: string;
+  github_commit_sha?: string;
+  github_branch?: string;
+}
+
+export interface Message {
+  role: string;
+  content: string;
+  timestamp: Date;
+}
+
+export interface FileChange {
+  file: string;
+  event: string;
+  timestamp: Date;
+}
+
+export interface WorkCompleted {
+  id: number;
+  session_id: number;
+  project_id: number;
+  title: string;
+  description?: string;
+  category: string;
+  files_modified: string[];
+  completed_at: Date;
+  github_commit_sha?: string;
+}
+
+export interface Project {
+  id: number;
+  name: string;
+  workspace_path: string;
+  status: string;
+  created_at: Date;
+}
+
+export interface ArchitecturalDecision {
+  id: number;
+  project_id: number;
+  title: string;
+  context?: string;
+  decision: string;
+  consequences?: string;
+  status: string;
+  decided_at: Date;
+  tags: string[];
+}
+
+export interface ApiEndpoint {
+  id: number;
+  project_id: number;
+  method: string;
+  path: string;
+  description?: string;
+  is_active: boolean;
+  first_detected: Date;
+  last_detected: Date;
+}
+
+// Dashboard Stats
+export interface DashboardStats {
+  totalSessions: number;
+  totalCost: number;
+  totalTokens: number;
+  totalFeatures: number;
+  completedFeatures: number;
+  totalDuration: number;
+}
+

lib/types/chat-extraction.ts

@@ -0,0 +1,14 @@
+import type { ChatExtractionData } from '@/lib/ai/chat-extraction-types';
+
+export interface ChatExtractionRecord<TData = ChatExtractionData> {
+  id: string;
+  projectId: string;
+  knowledgeItemId: string;
+  data: TData;
+  overallCompletion: number;
+  overallConfidence: number;
+  createdAt: FirebaseFirestore.Timestamp;
+  updatedAt: FirebaseFirestore.Timestamp;
+}
+
+

lib/types/extraction-output.ts

@@ -0,0 +1,43 @@
+/**
+ * Backend Extraction Output Types
+ * 
+ * These types define the structured JSON returned by the backend extractor.
+ * Used ONLY by backend extraction, not by chat.
+ */
+
+// Structured item returned by Gemini for each category
+export interface StructuredExtractedItem {
+  id?: string;
+  sourceText: string;
+  label?: string;
+  description?: string;
+  confidence: number;
+  importance: "primary" | "supporting";
+}
+
+export interface ExtractedInsight {
+  id: string;
+  type: "problem" | "user" | "feature" | "constraint" | "opportunity" | "other";
+  title: string;
+  description: string;
+  sourceText: string;
+  sourceKnowledgeItemId: string;
+  importance: "primary" | "supporting";
+  confidence: number;
+}
+
+export interface ExtractionOutput {
+  // Gemini returns rich objects, not just strings
+  problems: StructuredExtractedItem[];
+  targetUsers: StructuredExtractedItem[];
+  features: StructuredExtractedItem[];
+  constraints: StructuredExtractedItem[];
+  opportunities: StructuredExtractedItem[];
+  
+  // These can remain as arrays (empty arrays OK)
+  insights: ExtractedInsight[];
+  uncertainties: string[];
+  missingInformation: string[];
+  overallConfidence: number;
+}
+

lib/types/knowledge.ts

@@ -0,0 +1,51 @@
+export type KnowledgeSourceType =
+  | 'user_chat'
+  | 'imported_chat'
+  | 'imported_ai_chat'
+  | 'imported_document'
+  | 'doc'
+  | 'note'
+  | 'spec'
+  | 'research'
+  | 'other';
+
+export type KnowledgeSourceOrigin =
+  | 'chatgpt'
+  | 'gemini'
+  | 'claude'
+  | 'cursor'
+  | 'vibn'
+  | 'other';
+
+export type KnowledgeImportance = 'primary' | 'supporting' | 'irrelevant';
+
+export interface ChunkMetadata {
+  chunkIndex: number;
+  totalChunks: number;
+  startChar: number;
+  endChar: number;
+  tokenCount: number;
+}
+
+export interface KnowledgeSourceMeta {
+  origin?: KnowledgeSourceOrigin;
+  url?: string | null;
+  filename?: string | null;
+  createdAtOriginal?: string | null;
+  importance?: KnowledgeImportance;
+  tags?: string[];
+  chunkMetadata?: ChunkMetadata;
+}
+
+export interface KnowledgeItem {
+  id: string;
+  projectId: string;
+  sourceType: KnowledgeSourceType;
+  title?: string | null;
+  content: string;
+  sourceMeta?: KnowledgeSourceMeta;
+  createdAt: FirebaseFirestore.Timestamp;
+  updatedAt: FirebaseFirestore.Timestamp;
+}
+
+

lib/types/logs.ts

@@ -0,0 +1,102 @@
+/**
+ * Logging types for monitoring and debugging
+ */
+
+import type { ChatMode } from '@/lib/ai/chat-modes';
+
+/**
+ * Log entry for project-related events
+ * 
+ * Stored in Firestore `project_logs` collection for monitoring,
+ * debugging, and prompt iteration.
+ */
+export interface ProjectLogEntry {
+  /** Firestore document ID */
+  id: string;
+
+  /** Project this log belongs to */
+  projectId: string;
+
+  /** User who triggered the event (if available) */
+  userId: string | null;
+
+  /** Event type for filtering */
+  eventType:
+    | 'chat_interaction'
+    | 'extraction'
+    | 'vision_generation'
+    | 'mvp_generation'
+    | 'marketing_generation'
+    | 'knowledge_import'
+    | 'batch_extraction'
+    | 'mode_transition'
+    | 'error';
+
+  /** Chat mode (if applicable) */
+  mode: ChatMode | null;
+
+  /** Project phase (if applicable) */
+  phase: string | null;
+
+  /** Which artifacts were used in this interaction */
+  artifactsUsed: string[];
+
+  /** Whether vector search was used */
+  usedVectorSearch: boolean;
+
+  /** Number of vector chunks retrieved (if applicable) */
+  vectorChunkCount?: number;
+
+  /** Prompt version identifier (for A/B testing) */
+  promptVersion: string | null;
+
+  /** Model used (e.g., 'gemini-2.0-flash-exp') */
+  modelUsed: string | null;
+
+  /** Whether the operation succeeded */
+  success: boolean;
+
+  /** Error message (if failed) */
+  errorMessage: string | null;
+
+  /** Additional metadata (flexible for future use) */
+  metadata?: Record<string, any>;
+
+  /** When this log was created */
+  createdAt: Date | string;
+}
+
+/**
+ * Input for creating a new log entry
+ * (id and createdAt are auto-generated)
+ */
+export type CreateProjectLogInput = Omit<ProjectLogEntry, 'id' | 'createdAt'>;
+
+/**
+ * Filters for querying logs
+ */
+export interface ProjectLogFilters {
+  projectId?: string;
+  userId?: string;
+  eventType?: ProjectLogEntry['eventType'];
+  mode?: ChatMode;
+  phase?: string;
+  success?: boolean;
+  startDate?: Date;
+  endDate?: Date;
+  limit?: number;
+}
+
+/**
+ * Aggregated log stats for monitoring
+ */
+export interface ProjectLogStats {
+  totalLogs: number;
+  successCount: number;
+  errorCount: number;
+  byEventType: Record<string, number>;
+  byMode: Record<string, number>;
+  avgVectorChunks: number;
+  vectorSearchUsageRate: number;
+}
+

lib/types/marketing.ts

@@ -0,0 +1,17 @@
+export interface HomepageMessaging {
+  headline: string | null;
+  subheadline: string | null;
+  bullets: string[];
+}
+
+export interface MarketingModel {
+  projectId: string;
+  icp: string[];
+  positioning: string | null;
+  homepageMessaging: HomepageMessaging;
+  initialChannels: string[];
+  launchAngles: string[];
+  overallConfidence: number;
+}
+
+

lib/types/mvp-plan.ts

@@ -0,0 +1,122 @@
+/**
+ * Type definitions for AI-generated MVP Plan
+ * Based on the Vibn MVP Planner agent spec
+ */
+
+// Project-level
+export type Project = {
+  id: string;
+  ownerUserId: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  summary: string; // final summary text from planner
+};
+
+// Raw vision answers
+export type VisionInput = {
+  projectId: string;
+  q1_who_and_problem: string;
+  q2_story: string;
+  q3_improvement: string;
+  createdAt: string;
+};
+
+// Optional work-to-date summary
+export type WorkToDate = {
+  projectId: string;
+  codeSummary?: string;
+  githubSummary?: string;
+  docsLinksOrText?: string[]; // or JSON
+  existingAssetsNotes?: string;
+  createdAt: string;
+};
+
+// Trees (Journey / Touchpoints / System)
+export type TreeType = "journey" | "touchpoints" | "system";
+
+export type Tree = {
+  id: string;
+  projectId: string;
+  type: TreeType;
+  label: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+// Asset types from agent spec
+export type AssetType =
+  | "web_page"
+  | "app_screen"
+  | "flow"
+  | "component"
+  | "email"
+  | "notification"
+  | "document"
+  | "social_post"
+  | "data_model"
+  | "api_endpoint"
+  | "service"
+  | "integration"
+  | "job"
+  | "infrastructure"
+  | "automation"
+  | "other";
+
+// Each node in any tree
+export type AssetNode = {
+  id: string;
+  projectId: string;
+  treeId: string;
+  parentId: string | null;
+  name: string;
+  assetType: AssetType;
+  mustHaveForV1: boolean;
+  createdAt: string;
+  updatedAt: string;
+  children?: AssetNode[]; // For nested structure
+};
+
+// Node metadata (reasoning, mapping back to vision)
+export type AssetMetadata = {
+  assetNodeId: string;
+  whyItExists: string;
+  whichUserItServes?: string;
+  problemItHelpsWith?: string;
+  connectionToMagicMoment: string;
+  valueContribution?: string;
+  journeyStage?: string;
+  messagingTone?: string;
+  visualStyleNotes?: string;
+  dependencies?: string[]; // other AssetNode IDs
+  implementationNotes?: string;
+};
+
+// Context memory events
+export type ContextEvent = {
+  id: string;
+  projectId: string;
+  sourceType: "chat" | "commit" | "file" | "doc" | "manual_note";
+  sourceId?: string; // e.g. commit hash, file path
+  timestamp: string;
+  title: string;
+  body: string; // raw text or JSON
+};
+
+// Full AI response from agent
+export type AIAgentResponse = {
+  journey_tree: {
+    label: string;
+    nodes: Array<AssetNode & { asset_metadata: AssetMetadata }>;
+  };
+  touchpoints_tree: {
+    label: string;
+    nodes: Array<AssetNode & { asset_metadata: AssetMetadata }>;
+  };
+  system_tree: {
+    label: string;
+    nodes: Array<AssetNode & { asset_metadata: AssetMetadata }>;
+  };
+  summary: string;
+};
+

lib/types/mvp.ts

@@ -0,0 +1,12 @@
+export interface MvpPlan {
+  projectId: string;
+  coreFlows: string[];
+  coreFeatures: string[];
+  supportingFeatures: string[];
+  outOfScope: string[];
+  technicalTasks: string[];
+  blockers: string[];
+  overallConfidence: number;
+}
+
+

lib/types/phase-handoff.ts

@@ -0,0 +1,257 @@
+/**
+ * Phase Handoff Protocol
+ * 
+ * Defines the structured handoff between phases in the Vibn workflow.
+ * Each phase (extraction, vision, mvp, marketing) produces a handoff that:
+ * - Declares confidence and readiness for next phase
+ * - Separates confirmed facts from uncertain/missing items
+ * - Provides questions to resolve ambiguity
+ * - References source evidence
+ */
+
+/**
+ * Phase identifier for handoffs
+ */
+export type PhaseType = 'collector' | 'extraction' | 'vision' | 'mvp' | 'marketing';
+
+/**
+ * Structured handoff between phases
+ * 
+ * Produced by each phase agent to communicate confidence, gaps, and questions
+ * to the next phase or back to the user.
+ */
+export interface PhaseHandoff {
+  /** Which phase produced this handoff */
+  phase: PhaseType;
+  
+  /** Is this phase ready to hand off to the next one? */
+  readyForNextPhase: boolean;
+  
+  /** Overall confidence score (0-1) for this phase's outputs */
+  confidence: number;
+  
+  /** Items that are confirmed and high-confidence */
+  confirmed: Record<string, any>;
+  
+  /** Items that are uncertain or low-confidence */
+  uncertain: Record<string, any>;
+  
+  /** Items that are completely missing or unknown */
+  missing: string[];
+  
+  /** Questions for the user to resolve gaps or ambiguity */
+  questionsForUser: string[];
+  
+  /** References to source knowledge items or extractions that support this handoff */
+  sourceEvidence: string[];
+  
+  /** Version of the handoff schema (for future evolution) */
+  version: string;
+  
+  /** When this handoff was created */
+  timestamp: string;
+  
+  /** Optional metadata specific to this phase */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Handoff from the Collector phase
+ * 
+ * After gathering project materials, confirm readiness for extraction.
+ */
+export interface CollectorPhaseHandoff extends PhaseHandoff {
+  phase: 'collector';
+  
+  /** Checklist status */
+  confirmed: {
+    /** Has user uploaded documents? */
+    hasDocuments?: boolean;
+    
+    /** Number of documents uploaded */
+    documentCount?: number;
+    
+    /** Has user connected GitHub repo? */
+    githubConnected?: boolean;
+    
+    /** GitHub repo full name (e.g., 'user/repo') */
+    githubRepo?: string;
+    
+    /** Has user installed browser extension and linked to project? */
+    extensionLinked?: boolean;
+  };
+  
+  /** Items the user said "no" or "not yet" to */
+  uncertain: {
+    /** User declined or hasn't set up extension */
+    extensionDeclined?: boolean;
+    
+    /** User doesn't have a GitHub repo yet */
+    noGithubYet?: boolean;
+  };
+  
+  /** What's missing before moving to extraction */
+  missing: string[]; // e.g., ["documents", "github repo", "extension"]
+}
+
+/**
+ * Handoff from the Extraction phase
+ * 
+ * After analyzing all chat_extractions, summarize what's known about the product.
+ */
+export interface ExtractionPhaseHandoff extends PhaseHandoff {
+  phase: 'extraction';
+  
+  /** High-confidence product signals */
+  confirmed: {
+    /** Product one-liner (if clear) */
+    oneLiner?: string;
+    
+    /** Core problem statement */
+    problemStatement?: string;
+    
+    /** Target user personas */
+    targetUsers?: string[];
+    
+    /** Confirmed features */
+    features?: string[];
+    
+    /** Known tech stack */
+    techStack?: string[];
+  };
+  
+  /** Low-confidence or conflicting signals */
+  uncertain: {
+    /** Ambiguous or conflicting features */
+    features?: string[];
+    
+    /** Unclear business model */
+    businessModel?: string;
+  };
+  
+  /** What's missing to build a solid product model */
+  missing: string[]; // e.g., ["target market size", "pricing strategy"]
+}
+
+/**
+ * Handoff from the Vision phase
+ * 
+ * After creating canonicalProductModel, declare what's locked vs tentative.
+ */
+export interface VisionPhaseHandoff extends PhaseHandoff {
+  phase: 'vision';
+  
+  confirmed: {
+    /** Core value proposition (locked) */
+    valueProposition?: string;
+    
+    /** Primary user persona (locked) */
+    primaryPersona?: string;
+    
+    /** Must-have features for MVP */
+    mustHaveFeatures?: string[];
+  };
+  
+  uncertain: {
+    /** Nice-to-have features (not decided for MVP) */
+    niceToHaveFeatures?: string[];
+    
+    /** Unclear scope decisions */
+    scopeDecisions?: string[];
+  };
+  
+  missing: string[]; // e.g., ["competitive analysis", "pricing model"]
+}
+
+/**
+ * Handoff from the MVP phase
+ * 
+ * After creating mvpPlan, declare what's ready to build vs needs clarification.
+ */
+export interface MVPPhaseHandoff extends PhaseHandoff {
+  phase: 'mvp';
+  
+  confirmed: {
+    /** Locked feature scope */
+    featureScope?: string[];
+    
+    /** Tech stack decisions */
+    techStack?: string[];
+    
+    /** Build timeline estimate */
+    timelineEstimate?: string;
+  };
+  
+  uncertain: {
+    /** Features with unclear requirements */
+    unclearFeatures?: string[];
+    
+    /** Technical risks or unknowns */
+    technicalRisks?: string[];
+  };
+  
+  missing: string[]; // e.g., ["API design", "database schema"]
+}
+
+/**
+ * Handoff from the Marketing phase
+ * 
+ * After creating marketingPlan, declare launch readiness.
+ */
+export interface MarketingPhaseHandoff extends PhaseHandoff {
+  phase: 'marketing';
+  
+  confirmed: {
+    /** Launch channels */
+    launchChannels?: string[];
+    
+    /** Target launch date */
+    launchDate?: string;
+    
+    /** Marketing messaging */
+    messaging?: string;
+  };
+  
+  uncertain: {
+    /** Unconfirmed distribution channels */
+    uncertainChannels?: string[];
+    
+    /** Budget constraints */
+    budgetConstraints?: string;
+  };
+  
+  missing: string[]; // e.g., ["landing page copy", "email sequences"]
+}
+
+/**
+ * Union type for all phase handoffs
+ */
+export type AnyPhaseHandoff =
+  | CollectorPhaseHandoff
+  | ExtractionPhaseHandoff
+  | VisionPhaseHandoff
+  | MVPPhaseHandoff
+  | MarketingPhaseHandoff;
+
+/**
+ * Helper to create a minimal phase handoff
+ */
+export function createPhaseHandoff(
+  phase: PhaseType,
+  partial: Partial<PhaseHandoff>
+): PhaseHandoff {
+  return {
+    phase,
+    readyForNextPhase: false,
+    confidence: 0.5,
+    confirmed: {},
+    uncertain: {},
+    missing: [],
+    questionsForUser: [],
+    sourceEvidence: [],
+    version: '1.0',
+    timestamp: new Date().toISOString(),
+    ...partial,
+  };
+}
+

lib/types/phases.ts

@@ -0,0 +1,96 @@
+/**
+ * Phase Tracking for Vibn Projects
+ * 
+ * Projects progress through phases with specific agents:
+ * 1. Gathering → Collect and analyze all project materials
+ * 2. Vision → Extract and validate Product Vision Board
+ * 3. Scope → Define V1 MVP features
+ * 4. Blueprint → Technical architecture design
+ * 5. Build → Implementation (future)
+ */
+
+export type ProjectPhase = 
+  | 'gathering'    // Phase 1: Collecting context and analyzing materials
+  | 'vision'       // Phase 2: Extracting vision board
+  | 'scope'        // Phase 3: Defining V1 features
+  | 'blueprint'    // Phase 4: Technical design
+  | 'build';       // Phase 5: Implementation
+
+export type PhaseStatus = 
+  | 'not_started'
+  | 'in_progress'
+  | 'completed';
+
+export interface PhaseProgress {
+  phase: ProjectPhase;
+  status: PhaseStatus;
+  startedAt?: FirebaseFirestore.Timestamp;
+  completedAt?: FirebaseFirestore.Timestamp;
+  insights?: GatheringInsight[];  // For gathering phase
+  visionBoard?: VisionBoardData;   // For vision phase
+  scope?: ScopeData;               // For scope phase
+  blueprint?: BlueprintData;       // For blueprint phase
+}
+
+export interface GatheringInsight {
+  id: string;
+  source: string;           // "Patient History Overview"
+  sourceType: 'document' | 'github' | 'session' | 'conversation';
+  sourceId: string;         // Document/session ID
+  insight: string;          // "Using evidence-based diagnostic methods"
+  extractedAt: FirebaseFirestore.Timestamp;
+  confirmed: boolean;       // User validated this
+  confirmedAt?: FirebaseFirestore.Timestamp;
+  usedInVision: boolean;    // Phase 2 marked this as used
+  category?: 'feature' | 'user' | 'problem' | 'competitor' | 'tech' | 'progress';
+}
+
+export interface VisionBoardData {
+  vision: string;           // One-sentence vision
+  who: string;              // Target users
+  need: string;             // Problem they face
+  product: string;          // Solution features
+  validation: string;       // Go-to-market strategy
+  completedAt?: FirebaseFirestore.Timestamp;
+  approved: boolean;
+  approvedAt?: FirebaseFirestore.Timestamp;
+}
+
+export interface ScopeData {
+  v1Features: string[];
+  timeline: string;
+  priorities: {
+    mustHave: string[];
+    shouldHave: string[];
+    niceToHave: string[];
+  };
+  completedAt?: FirebaseFirestore.Timestamp;
+}
+
+export interface BlueprintData {
+  techStack: string[];
+  architecture: string;
+  database: string;
+  apis: string[];
+  completedAt?: FirebaseFirestore.Timestamp;
+}
+
+// Helper to determine which agent to use
+export function getAgentForPhase(phase: ProjectPhase): string {
+  const agentMap: Record<ProjectPhase, string> = {
+    gathering: 'GATHERING_AGENT',
+    vision: 'VISION_AGENT',
+    scope: 'SCOPE_AGENT',
+    blueprint: 'BLUEPRINT_AGENT',
+    build: 'BUILD_AGENT'
+  };
+  return agentMap[phase];
+}
+
+// Helper to get next phase
+export function getNextPhase(currentPhase: ProjectPhase): ProjectPhase | null {
+  const phaseOrder: ProjectPhase[] = ['gathering', 'vision', 'scope', 'blueprint', 'build'];
+  const currentIndex = phaseOrder.indexOf(currentPhase);
+  return currentIndex < phaseOrder.length - 1 ? phaseOrder[currentIndex + 1] : null;
+}
+

lib/types/product-model.ts

@@ -0,0 +1,37 @@
+export type ProjectStage =
+  | 'idea'
+  | 'prototype'
+  | 'mvp_in_progress'
+  | 'live_beta'
+  | 'live_paid'
+  | 'unknown';
+
+export interface CanonicalProductModel {
+  projectId: string;
+  workingTitle: string | null;
+  oneLiner: string | null;
+
+  problem: string | null;
+  targetUser: string | null;
+  desiredOutcome: string | null;
+  coreSolution: string | null;
+
+  coreFeatures: string[];
+  niceToHaveFeatures: string[];
+
+  marketCategory: string | null;
+  competitors: string[];
+
+  techStack: string[];
+  constraints: string[];
+
+  currentStage: ProjectStage;
+
+  shortTermGoals: string[];
+  longTermGoals: string[];
+
+  overallCompletion: number;
+  overallConfidence: number;
+}
+
+

lib/types/project-artifacts.ts

@@ -0,0 +1,40 @@
+import type { CanonicalProductModel, ProjectStage } from '@/lib/types/product-model';
+import type { MvpPlan } from '@/lib/types/mvp';
+import type { MarketingModel, HomepageMessaging } from '@/lib/types/marketing';
+import type { PhaseHandoff } from '@/lib/types/phase-handoff';
+export type { CanonicalProductModel, ProjectStage } from '@/lib/types/product-model';
+export type { MvpPlan } from '@/lib/types/mvp';
+export type { MarketingModel, HomepageMessaging } from '@/lib/types/marketing';
+export type { PhaseHandoff } from '@/lib/types/phase-handoff';
+
+export type ProjectPhase =
+  | 'collector'
+  | 'analyzed'
+  | 'vision_ready'
+  | 'mvp_ready'
+  | 'marketing_ready'
+  | 'complete';
+
+export interface ProjectPhaseData {
+  canonicalProductModel?: CanonicalProductModel;
+  mvpPlan?: MvpPlan;
+  marketingPlan?: MarketingModel;
+  
+  /** Phase handoffs for smart transitions */
+  phaseHandoffs?: Partial<Record<'collector' | 'extraction' | 'vision' | 'mvp' | 'marketing', PhaseHandoff>>;
+}
+
+export interface PhaseScore {
+  overallCompletion: number;
+  overallConfidence: number;
+  updatedAt: string;
+}
+
+export interface ProjectPhaseScores {
+  extractor?: PhaseScore & { knowledgeItemId?: string };
+  vision?: PhaseScore;
+  mvp?: PhaseScore;
+  marketing?: PhaseScore;
+}
+
+

lib/types/vector-memory.ts

@@ -0,0 +1,107 @@
+/**
+ * Types for AlloyDB vector memory (knowledge_chunks table)
+ */
+
+/**
+ * A semantic chunk of a knowledge_item with vector embedding
+ */
+export interface KnowledgeChunk {
+  /** UUID primary key */
+  id: string;
+  
+  /** Firestore project ID */
+  projectId: string;
+  
+  /** Firestore knowledge_item ID */
+  knowledgeItemId: string;
+  
+  /** Index of this chunk within the parent knowledge_item (0-based) */
+  chunkIndex: number;
+  
+  /** Text content of this chunk */
+  content: string;
+  
+  /** Source type (e.g., 'imported_ai_chat', 'imported_document', etc.) */
+  sourceType: string | null;
+  
+  /** Importance classification (for filtering) */
+  importance: 'primary' | 'supporting' | 'irrelevant' | null;
+  
+  /** When this chunk was created */
+  createdAt: string;
+  
+  /** When this chunk was last updated */
+  updatedAt: string;
+}
+
+/**
+ * Database row shape (snake_case from PostgreSQL)
+ */
+export interface KnowledgeChunkRow {
+  id: string;
+  project_id: string;
+  knowledge_item_id: string;
+  chunk_index: number;
+  content: string;
+  source_type: string | null;
+  importance: 'primary' | 'supporting' | 'irrelevant' | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/**
+ * Result of a vector similarity search, includes similarity score
+ */
+export interface KnowledgeChunkSearchResult extends KnowledgeChunk {
+  /** Similarity score (0-1, higher = more similar) */
+  similarity: number;
+}
+
+/**
+ * Options for vector search
+ */
+export interface VectorSearchOptions {
+  /** Maximum number of results to return */
+  limit?: number;
+  
+  /** Minimum similarity threshold (0-1) */
+  minSimilarity?: number;
+  
+  /** Filter by source type(s) */
+  sourceTypes?: string[];
+  
+  /** Filter by importance level(s) */
+  importanceLevels?: ('primary' | 'supporting' | 'irrelevant')[];
+  
+  /** Whether to include embedding in results (default: false) */
+  includeEmbedding?: boolean;
+}
+
+/**
+ * Input for creating a new knowledge chunk
+ */
+export interface CreateKnowledgeChunkInput {
+  projectId: string;
+  knowledgeItemId: string;
+  chunkIndex: number;
+  content: string;
+  embedding: number[];
+  sourceType?: string | null;
+  importance?: 'primary' | 'supporting' | 'irrelevant' | null;
+}
+
+/**
+ * Batch input for creating multiple chunks at once
+ */
+export interface BatchCreateKnowledgeChunksInput {
+  projectId: string;
+  knowledgeItemId: string;
+  chunks: {
+    chunkIndex: number;
+    content: string;
+    embedding: number[];
+    sourceType?: string | null;
+    importance?: 'primary' | 'supporting' | 'irrelevant' | null;
+  }[];
+}
+

lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

lib/utils/api-url.ts

@@ -0,0 +1,35 @@
+/**
+ * Get the base URL for internal API calls
+ * Works in both development and production environments
+ */
+export function getBaseUrl(request?: Request): string {
+  // In production (Firebase/Vercel), use the request origin
+  if (request && typeof window === 'undefined') {
+    const origin = request.headers.get('origin') || request.headers.get('referer');
+    if (origin) {
+      return new URL(origin).origin;
+    }
+  }
+  
+  // Check environment variables
+  if (process.env.NEXT_PUBLIC_APP_URL) {
+    return process.env.NEXT_PUBLIC_APP_URL;
+  }
+  
+  if (process.env.VERCEL_URL) {
+    return `https://${process.env.VERCEL_URL}`;
+  }
+  
+  // Default to localhost for development
+  return 'http://localhost:3000';
+}
+
+/**
+ * Get the full API URL for internal API calls
+ */
+export function getApiUrl(path: string, request?: Request): string {
+  const baseUrl = getBaseUrl(request);
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  return `${baseUrl}${cleanPath}`;
+}
+

lib/utils/code-chunker.ts

@@ -0,0 +1,223 @@
+/**
+ * Code-specific chunking for source code files
+ * Intelligently splits code while preserving context
+ */
+
+export interface CodeChunk {
+  content: string;
+  metadata: {
+    chunkIndex: number;
+    totalChunks: number;
+    startLine: number;
+    endLine: number;
+    tokenCount: number;
+    filePath: string;
+    language?: string;
+  };
+}
+
+export interface CodeChunkOptions {
+  maxChunkSize?: number; // characters
+  chunkOverlap?: number; // lines
+  preserveFunctions?: boolean;
+  preserveClasses?: boolean;
+  filePath: string;
+}
+
+/**
+ * Estimate token count (rough approximation: 1 token ≈ 4 characters)
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Detect language from file path
+ */
+function detectLanguage(filePath: string): string | undefined {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  const langMap: Record<string, string> = {
+    ts: 'typescript',
+    tsx: 'typescript',
+    js: 'javascript',
+    jsx: 'javascript',
+    py: 'python',
+    java: 'java',
+    go: 'go',
+    rs: 'rust',
+    cpp: 'cpp',
+    c: 'c',
+    cs: 'csharp',
+    rb: 'ruby',
+    php: 'php',
+    swift: 'swift',
+    kt: 'kotlin',
+    sql: 'sql',
+    css: 'css',
+    scss: 'scss',
+    html: 'html',
+    json: 'json',
+    yaml: 'yaml',
+    yml: 'yaml',
+    md: 'markdown',
+  };
+  return langMap[ext || ''];
+}
+
+/**
+ * Chunk source code file intelligently
+ */
+export function chunkCode(
+  content: string,
+  options: CodeChunkOptions
+): CodeChunk[] {
+  const {
+    maxChunkSize = 3000, // Larger chunks for code context
+    chunkOverlap = 5,
+    preserveFunctions = true,
+    preserveClasses = true,
+    filePath,
+  } = options;
+
+  const language = detectLanguage(filePath);
+  const lines = content.split('\n');
+
+  // For small files, return as single chunk
+  if (content.length <= maxChunkSize) {
+    return [
+      {
+        content,
+        metadata: {
+          chunkIndex: 0,
+          totalChunks: 1,
+          startLine: 1,
+          endLine: lines.length,
+          tokenCount: estimateTokens(content),
+          filePath,
+          language,
+        },
+      },
+    ];
+  }
+
+  // For larger files, split by logical boundaries
+  const chunks: CodeChunk[] = [];
+  let currentChunk: string[] = [];
+  let currentSize = 0;
+  let chunkStartLine = 1;
+
+  // Patterns for detecting logical boundaries
+  const functionPattern = /^\s*(function|def|fn|func|fun|public|private|protected|static|async|export)\s/;
+  const classPattern = /^\s*(class|interface|struct|enum|type)\s/;
+  const importPattern = /^\s*(import|from|require|using|include)\s/;
+  const commentPattern = /^\s*(\/\/|\/\*|\*|#|--|<!--)/;
+
+  // Always include file header (imports, comments at top)
+  let headerLines: string[] = [];
+  for (let i = 0; i < Math.min(20, lines.length); i++) {
+    const line = lines[i];
+    if (importPattern.test(line) || commentPattern.test(line) || line.trim() === '') {
+      headerLines.push(line);
+    } else {
+      break;
+    }
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineSize = line.length + 1; // +1 for newline
+
+    // Check if we should start a new chunk
+    const shouldSplit =
+      currentSize + lineSize > maxChunkSize &&
+      currentChunk.length > 0 &&
+      (functionPattern.test(line) ||
+        classPattern.test(line) ||
+        (line.trim() === '' && currentSize > maxChunkSize * 0.7));
+
+    if (shouldSplit) {
+      // Save current chunk
+      const chunkContent = currentChunk.join('\n');
+      chunks.push({
+        content: chunkContent,
+        metadata: {
+          chunkIndex: chunks.length,
+          totalChunks: 0, // Will update at end
+          startLine: chunkStartLine,
+          endLine: chunkStartLine + currentChunk.length - 1,
+          tokenCount: estimateTokens(chunkContent),
+          filePath,
+          language,
+        },
+      });
+
+      // Start new chunk with overlap and header
+      const overlapStart = Math.max(0, currentChunk.length - chunkOverlap);
+      currentChunk = [
+        ...headerLines,
+        '',
+        `// ... continued from line ${chunkStartLine}`,
+        '',
+        ...currentChunk.slice(overlapStart),
+      ];
+      currentSize = currentChunk.reduce((sum, l) => sum + l.length + 1, 0);
+      chunkStartLine = chunkStartLine + overlapStart;
+    }
+
+    currentChunk.push(line);
+    currentSize += lineSize;
+  }
+
+  // Add final chunk
+  if (currentChunk.length > 0) {
+    const chunkContent = currentChunk.join('\n');
+    chunks.push({
+      content: chunkContent,
+      metadata: {
+        chunkIndex: chunks.length,
+        totalChunks: 0,
+        startLine: chunkStartLine,
+        endLine: lines.length,
+        tokenCount: estimateTokens(chunkContent),
+        filePath,
+        language,
+      },
+    });
+  }
+
+  // Update totalChunks for all chunks
+  chunks.forEach((chunk) => {
+    chunk.metadata.totalChunks = chunks.length;
+  });
+
+  return chunks;
+}
+
+/**
+ * Generate a summary header for a code file
+ */
+export function generateCodeSummary(
+  filePath: string,
+  content: string,
+  language?: string
+): string {
+  const lines = content.split('\n');
+  const functions = lines.filter(line => /^\s*(function|def|fn|func|async function|export function)/.test(line));
+  const classes = lines.filter(line => /^\s*(class|interface|struct|enum|type)\s/.test(line));
+  
+  let summary = `File: ${filePath}\n`;
+  if (language) {
+    summary += `Language: ${language}\n`;
+  }
+  summary += `Lines: ${lines.length}\n`;
+  
+  if (functions.length > 0) {
+    summary += `Functions: ${functions.length}\n`;
+  }
+  if (classes.length > 0) {
+    summary += `Classes/Types: ${classes.length}\n`;
+  }
+  
+  return summary;
+}
+

lib/utils/document-chunker.ts

@@ -0,0 +1,206 @@
+/**
+ * Document Chunking Utility
+ * 
+ * Splits large documents into manageable chunks for AI processing.
+ * Uses semantic chunking with configurable overlap for better context.
+ */
+
+export interface ChunkMetadata {
+  chunkIndex: number;
+  totalChunks: number;
+  startChar: number;
+  endChar: number;
+  tokenCount: number;
+}
+
+export interface DocumentChunk {
+  content: string;
+  metadata: ChunkMetadata;
+}
+
+export interface ChunkingOptions {
+  maxChunkSize?: number;        // Maximum characters per chunk (default: 2000)
+  chunkOverlap?: number;         // Overlap between chunks (default: 200)
+  preserveParagraphs?: boolean;  // Try to keep paragraphs intact (default: true)
+  preserveCodeBlocks?: boolean;  // Keep code blocks together (default: true)
+}
+
+const DEFAULT_OPTIONS: Required<ChunkingOptions> = {
+  maxChunkSize: 2000,
+  chunkOverlap: 200,
+  preserveParagraphs: true,
+  preserveCodeBlocks: true,
+};
+
+/**
+ * Estimate token count (rough approximation: 1 token ≈ 4 characters)
+ */
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Find good split points (paragraph breaks, sentence boundaries)
+ */
+function findSplitPoint(text: string, idealSplit: number): number {
+  // Try to split at paragraph break first
+  const paragraphBreak = text.lastIndexOf('\n\n', idealSplit);
+  if (paragraphBreak > idealSplit - 500 && paragraphBreak > 0) {
+    return paragraphBreak + 2;
+  }
+
+  // Try sentence boundary
+  const sentenceEnd = text.lastIndexOf('. ', idealSplit);
+  if (sentenceEnd > idealSplit - 300 && sentenceEnd > 0) {
+    return sentenceEnd + 2;
+  }
+
+  // Try any newline
+  const newline = text.lastIndexOf('\n', idealSplit);
+  if (newline > idealSplit - 200 && newline > 0) {
+    return newline + 1;
+  }
+
+  // Last resort: split at space
+  const space = text.lastIndexOf(' ', idealSplit);
+  return space > 0 ? space + 1 : idealSplit;
+}
+
+/**
+ * Extract code blocks to preserve them
+ */
+function extractCodeBlocks(text: string): { text: string; codeBlocks: Map<string, string> } {
+  const codeBlocks = new Map<string, string>();
+  let counter = 0;
+
+  const processedText = text.replace(/```[\s\S]*?```/g, (match) => {
+    const placeholder = `__CODE_BLOCK_${counter}__`;
+    codeBlocks.set(placeholder, match);
+    counter++;
+    return placeholder;
+  });
+
+  return { text: processedText, codeBlocks };
+}
+
+/**
+ * Restore code blocks
+ */
+function restoreCodeBlocks(text: string, codeBlocks: Map<string, string>): string {
+  let result = text;
+  codeBlocks.forEach((code, placeholder) => {
+    result = result.replace(placeholder, code);
+  });
+  return result;
+}
+
+/**
+ * Split a document into semantic chunks
+ */
+export function chunkDocument(content: string, options: ChunkingOptions = {}): DocumentChunk[] {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const chunks: DocumentChunk[] = [];
+
+  // Handle empty content
+  if (!content || content.trim().length === 0) {
+    return chunks;
+  }
+
+  // Extract code blocks if preserving them
+  let processedContent = content;
+  let codeBlocks = new Map<string, string>();
+  
+  if (opts.preserveCodeBlocks) {
+    const extracted = extractCodeBlocks(content);
+    processedContent = extracted.text;
+    codeBlocks = extracted.codeBlocks;
+  }
+
+  let position = 0;
+  let chunkIndex = 0;
+
+  while (position < processedContent.length) {
+    const remainingLength = processedContent.length - position;
+    
+    // If remaining content fits in one chunk, take it all
+    if (remainingLength <= opts.maxChunkSize) {
+      const chunkContent = processedContent.substring(position);
+      const finalContent = opts.preserveCodeBlocks 
+        ? restoreCodeBlocks(chunkContent, codeBlocks)
+        : chunkContent;
+
+      chunks.push({
+        content: finalContent.trim(),
+        metadata: {
+          chunkIndex,
+          totalChunks: 0, // Will be updated after loop
+          startChar: position,
+          endChar: processedContent.length,
+          tokenCount: estimateTokens(finalContent),
+        },
+      });
+      break;
+    }
+
+    // Find a good split point
+    const idealEnd = position + opts.maxChunkSize;
+    const actualEnd = findSplitPoint(processedContent, idealEnd);
+    
+    const chunkContent = processedContent.substring(position, actualEnd);
+    const finalContent = opts.preserveCodeBlocks
+      ? restoreCodeBlocks(chunkContent, codeBlocks)
+      : chunkContent;
+
+    chunks.push({
+      content: finalContent.trim(),
+      metadata: {
+        chunkIndex,
+        totalChunks: 0, // Will be updated after loop
+        startChar: position,
+        endChar: actualEnd,
+        tokenCount: estimateTokens(finalContent),
+      },
+    });
+
+    // Move position forward with overlap
+    position = actualEnd - opts.chunkOverlap;
+    chunkIndex++;
+  }
+
+  // Update totalChunks in all metadata
+  const totalChunks = chunks.length;
+  chunks.forEach((chunk) => {
+    chunk.metadata.totalChunks = totalChunks;
+  });
+
+  return chunks;
+}
+
+/**
+ * Chunk multiple documents and return with source tracking
+ */
+export interface SourcedChunk extends DocumentChunk {
+  sourceFilename: string;
+  sourceMimeType?: string;
+}
+
+export function chunkDocuments(
+  documents: Array<{ filename: string; content: string; mimeType?: string }>,
+  options: ChunkingOptions = {}
+): SourcedChunk[] {
+  const allChunks: SourcedChunk[] = [];
+
+  documents.forEach((doc) => {
+    const chunks = chunkDocument(doc.content, options);
+    chunks.forEach((chunk) => {
+      allChunks.push({
+        ...chunk,
+        sourceFilename: doc.filename,
+        sourceMimeType: doc.mimeType,
+      });
+    });
+  });
+
+  return allChunks;
+}
+