From d1dc95756195e16b4f9bf9509ff7f1c0f2173acf Mon Sep 17 00:00:00 2001
From: Carlos Ricardo Ziegler <38855507+CarlosZiegler@users.noreply.github.com>
Date: Sat, 21 Feb 2026 12:33:38 +0100
Subject: [PATCH 1/2] docs: map existing codebase

---
 .planning/codebase/ARCHITECTURE.md | 272 ++++++++++++++++++++
 .planning/codebase/CONCERNS.md     | 267 ++++++++++++++++++++
 .planning/codebase/CONVENTIONS.md  | 243 ++++++++++++++++++
 .planning/codebase/INTEGRATIONS.md | 223 +++++++++++++++++
 .planning/codebase/STACK.md        | 221 ++++++++++++++++
 .planning/codebase/STRUCTURE.md    | 374 +++++++++++++++++++++++++++
 .planning/codebase/TESTING.md      | 390 +++++++++++++++++++++++++++++
 7 files changed, 1990 insertions(+)
 create mode 100644 .planning/codebase/ARCHITECTURE.md
 create mode 100644 .planning/codebase/CONCERNS.md
 create mode 100644 .planning/codebase/CONVENTIONS.md
 create mode 100644 .planning/codebase/INTEGRATIONS.md
 create mode 100644 .planning/codebase/STACK.md
 create mode 100644 .planning/codebase/STRUCTURE.md
 create mode 100644 .planning/codebase/TESTING.md

diff --git a/.planning/codebase/ARCHITECTURE.md b/.planning/codebase/ARCHITECTURE.md
new file mode 100644
index 0000000..afd61e4
--- /dev/null
+++ b/.planning/codebase/ARCHITECTURE.md
@@ -0,0 +1,272 @@
+# Architecture
+
+**Analysis Date:** 2026-02-21
+
+## Pattern Overview
+
+**Overall:** Full-stack TypeScript application using a client-server architecture with type-safe RPC communication. TanStack Start (meta-framework built on Vite) provides file-based routing with SSR capabilities. Data flows through a centralized oRPC (Open RPC) router that bridges frontend queries/mutations to backend handlers.
+
+**Key Characteristics:**
+- Isomorphic client creation with server-side and client-side implementations
+- React Query for client-side caching and async state management
+- oRPC for type-safe, schema-validated RPC with middleware chain
+- Postgres Row-Level Security (RLS) at database level for data isolation
+- Modular feature-based organization with co-located logic
+- Better-Auth for authentication with multi-provider support and role-based access control
+
+## Layers
+
+**Client Layer (React UI):**
+- Location: `src/routes/`, `src/features/`, `src/components/`
+- Purpose: Render UI, manage client state with React Query, trigger mutations/queries
+- Contains: Route components, feature UI, reusable components
+- Depends on: oRPC client, React Query, Jotai (atomic state), i18n
+- Used by: End users via browser
+
+**API Gateway / RPC Handler Layer:**
+- Location: `src/routes/api/rpc.$.ts`
+- Purpose: Accept HTTP RPC requests, route to appropriate handler, return responses
+- Contains: Elysia HTTP server, oRPC RPCHandler middleware, CORS/error handling
+- Depends on: oRPC server, Elysia framework
+- Used by: Client layer RPC calls
+
+**Business Logic / oRPC Router Layer:**
+- Location: `src/orpc/routes/`, `src/orpc/orpc-server.ts`, `src/orpc/index.ts`
+- Purpose: Define RPC procedures with input validation, access control, execution logic
+- Contains: Router definitions, procedure handlers, middleware (auth, RLS, timing/error)
+- Depends on: Database layer, auth service, storage service
+- Used by: API gateway, client via type-safe oRPC client
+
+**Authentication & Authorization Layer:**
+- Location: `src/lib/auth/auth.ts`, `src/lib/auth/auth-client.ts`, `src/lib/auth/permissions.ts`
+- Purpose: Session management, credential verification, role-based access control
+- Contains: Better-Auth configuration, RBAC rules, passkey/2FA/magic-link plugins
+- Depends on: Database (user/session/organization schema), Stripe (payment provider)
+- Used by: oRPC context, protected procedures, UI guards
+
+**Data Access Layer (Database):**
+- Location: `src/lib/db/`, `src/lib/db/schema/`
+- Purpose: ORM interface to PostgreSQL, schema definition, RLS policy application
+- Contains: Drizzle ORM schema, migrations, RLS context helper (`withRls`)
+- Depends on: PostgreSQL instance, Postgres RLS policies
+- Used by: oRPC handlers, storage service
+
+**Support Services:**
+- **Storage:** `src/lib/storage/` — S3-compatible file uploads with metadata tracking
+- **Stripe:** `src/lib/stripe/` — Payment processing, subscription management, plan definitions
+- **i18n:** `src/lib/intl/` — Multi-language support with server-side language detection
+- **Validations:** `src/lib/validations/` — Zod schemas for form/input validation
+
+## Data Flow
+
+**Standard Query (Read) Flow:**
+
+1. **Client:** `useQuery(orpc.profile.get.queryOptions({ input }))`
+2. **React Query:** Checks cache; if stale/missing, triggers fetch
+3. **oRPC Client:** Serializes input, sends POST to `/api/rpc`
+4. **API Gateway:** Routes to `RPCHandler.handle()`, extracts auth from cookies
+5. **oRPC Server:** Deserializes, runs middleware chain:
+   - `createORPCContext()` extracts session from headers
+   - `protectedProcedure` middleware checks `session.user` exists
+   - `protectedRlsProcedure` calls `withRls()` to set Postgres RLS context
+6. **Handler:** Executes with validated input + context
+7. **Database:** Postgres RLS policies filter rows based on `request.user_id` / `request.org_id`
+8. **Return:** Handler returns typed response
+9. **Client:** React Query caches, re-renders with new data
+
+**Standard Mutation (Write) Flow:**
+
+1. **Client:** `useMutation(orpc.profile.update.mutationOptions({ onSuccess: () => invalidate }))`
+2. **Form:** User submits form with validation (React Hook Form + Zod)
+3. **Mutation Handler:** Calls RPC procedure, catches errors
+4. **API Gateway → oRPC Server:** Same as queries (middleware chain applies)
+5. **Handler:** Validates input schema, updates database within `withRls()` transaction
+6. **Cache Invalidation:** `onSuccess` callback calls `queryClient.invalidateQueries({ queryKey: ... })`
+7. **Client:** React Query re-fetches data, UI updates
+
+**Authentication Flow:**
+
+1. **Initial Load:** `__root.tsx` calls `context.queryClient.prefetchQuery(authQueryOptions())`
+2. **Auth Query:** Calls Better-Auth API (`/api/auth/getSession`), stores session in React Query
+3. **Protected Routes:** `beforeLoad` checks session; redirects to `/sign-in` if null
+4. **Sign-In:** User submits credentials to `authClient.signIn.email()` or `signIn.social()`
+5. **Better-Auth Handler:** Validates, creates session, sets auth cookie (httpOnly)
+6. **Route Guard:** 401 responses auto-redirect via router's `queryCache.onError` handler
+7. **Logout:** `authClient.signOut()` clears session, invalidates auth query
+
+**State Management:**
+
+**Server State (oRPC + React Query):**
+- All server data managed via React Query caching layer
+- Queries prefetch on route navigation (TanStack Router `intent` preload strategy)
+- Stale time: 2 minutes default; mutations invalidate specific keys
+- Example: `useQuery(orpc.profile.get.queryOptions())` → cached for 2 min
+
+**Client State (Jotai atoms + React Hook Form):**
+- UI state (modals, tabs, filters) via Jotai atoms
+- Form state via React Hook Form `useForm()` + `useFieldArray()` for arrays
+- Global theme state via Next Themes provider
+
+**Session State:**
+- Stored in React Query: `authQueryOptions().queryKey`
+- Available in all routes via `RootContext.session`
+- Persisted server-side via Better-Auth session cookie
+
+## Key Abstractions
+
+**oRPC Router Abstraction:**
+- Purpose: Type-safe RPC boundary between client and server
+- Examples: `src/orpc/routes/profile.ts`, `src/orpc/routes/organization.ts`, `src/orpc/routes/chat.ts`
+- Pattern: Each router exports a sub-router with `orpc.router({ procedure1, procedure2, ... })`
+- Input/output validated via Zod schemas; errors caught by middleware
+
+**RLS (Row-Level Security) Transaction:**
+- Purpose: Automatically filter database queries by user/organization
+- Examples: `src/lib/db/secure-client.ts`, `src/orpc/orpc-server.ts`
+- Pattern: `context.rls(async (db) => { /* db queries auto-filtered */ })`
+- Implementation: Sets Postgres session vars `request.user_id` and `request.org_id`
+
+**Feature Module Pattern:**
+- Purpose: Co-locate UI, logic, types, queries, mutations for a domain
+- Examples: `src/features/organizations/`, `src/features/settings/`, `src/features/subscription/`
+- Structure: Each feature folder contains:
+  - Components: `*.tsx` (UI)
+  - Types: `*.types.ts` (TypeScript types)
+  - Queries: `*.factory.queries.ts` (React Query options)
+  - Mutations: `*.factory.mutations.ts` (React Query mutations)
+  - Utils: `*.utils.ts` (helpers)
+  - Hooks: `use-*.ts` (custom React hooks)
+
+**Procedure Middleware Chain:**
+- Purpose: Progressively restrict access and provide context
+- Pattern:
+  ```
+  publicProcedure → protectedProcedure → protectedRlsProcedure
+  ```
+- `publicProcedure`: No auth required
+- `protectedProcedure`: Requires `session.user`; context includes `session`, `db`, `auth`
+- `protectedRlsProcedure`: Additionally wraps queries in `withRls()` for Postgres RLS
+
+**Component Variants with CVA:**
+- Purpose: Style components with type-safe variant props
+- Examples: `src/components/ui/button.tsx`, `src/components/ui/card.tsx`
+- Pattern: `cva()` defines base + variant styles; components merge with `cn()`
+- Used by: All shadcn-based UI components
+
+## Entry Points
+
+**Client Entry:**
+- Location: `src/client.tsx`
+- Triggers: Vite hydration on page load
+- Responsibilities: Hydrate React app from server-rendered HTML, attach event listeners
+
+**Server Entry:**
+- Location: `src/server.ts`
+- Triggers: On HTTP request
+- Responsibilities: Render React to HTML, handle SSR, return response
+
+**Root Route (Layout):**
+- Location: `src/routes/__root.tsx`
+- Triggers: On any route load
+- Responsibilities:
+  - Prefetch session via `authQueryOptions()`
+  - Setup i18n language
+  - Provide `ThemeProvider`, `I18nextProvider`, `Toaster`
+  - Define global `<head>`, `<link>` tags
+  - Render route tree via `<RootOutlet />`
+
+**RPC API Entry:**
+- Location: `src/routes/api/rpc.$.ts`
+- Triggers: On POST/GET to `/api/rpc/*`
+- Responsibilities: Create Elysia app with oRPC handler, route requests, handle CORS
+
+**Auth API Entry:**
+- Location: `src/routes/api/auth/$.ts`
+- Triggers: On request to `/api/auth/*`
+- Responsibilities: Delegate to Better-Auth handler, manage sessions/tokens
+
+**Protected Route Example:**
+- Location: `src/routes/(dashboard)/overview/index.tsx`
+- Pattern:
+  ```tsx
+  export const Route = createFileRoute('/(dashboard)/overview/')({
+    beforeLoad: async ({ context }) => {
+      const session = await context.queryClient.ensureQueryData(authQueryOptions())
+      if (!session?.user) throw redirect({ to: '/sign-in' })
+    }
+  })
+  ```
+
+## Error Handling
+
+**Strategy:** Multi-level error containment with graceful user messaging
+
+**Patterns:**
+
+**Validation Errors:**
+- Zod schema validates input at oRPC procedure boundary
+- `protectedProcedure` middleware catches and converts to `INPUT_VALIDATION_FAILED` error
+- Client receives flattened errors: `{ fieldName: [message1, message2] }`
+- Form displays field-level errors via `FieldError` component
+
+**RPC/Network Errors:**
+- Client-side fetch interceptor catches network errors
+- `queryCache.onError` middleware detects 401s, clears session, redirects to `/sign-in`
+- Other errors surface as toast notifications: `toast.error(error.message)`
+
+**Async Errors in Mutations:**
+- Mutation handler catches errors in `onError` callback
+- Throws to React Query, which displays via toast
+- Example: `onError: (e) => toast.error(e.message)`
+
+**Unhandled Errors:**
+- Global error boundary at root route: `DefaultCatchBoundary`
+- Location: `src/components/error-boundary.tsx`
+- Displays error message, stack trace (dev only), retry/back buttons
+- User can copy error details for bug reports
+
+**Database/RLS Errors:**
+- Postgres RLS policy violations raise `permission denied` errors
+- Caught by oRPC error middleware, converted to `FORBIDDEN` or `UNAUTHORIZED`
+- Client receives typed error; UI displays appropriate message
+
+## Cross-Cutting Concerns
+
+**Logging:**
+- Server: Pino logger configured in `src/lib/auth/auth.ts`, logs Stripe webhooks, RPC timing (dev only)
+- Client: Console errors logged to Sentry (integration available but not configured)
+- Pattern: Use `console.info()` for timing (dev), `toast.error()` for user-facing errors
+
+**Validation:**
+- Input: Zod schemas at oRPC procedure level and form level (React Hook Form)
+- Output: oRPC validates response against handler's return type (type-safe)
+- Pattern: Define once in `src/lib/validations/`, reuse in procedures and forms
+
+**Authentication:**
+- Session checked at:
+  1. Route level: `beforeLoad` redirects if no session
+  2. Procedure level: `protectedProcedure` throws `UNAUTHORIZED` if no `session.user`
+  3. Database level: RLS policies filter rows by `request.user_id`
+- Roles checked via `@/lib/auth/permissions` utilities (e.g., `isOwner(user, org)`)
+
+**File Storage:**
+- S3-compatible uploads via `src/lib/storage/`
+- File metadata (userId, purpose, fileName) tracked in Drizzle schema
+- Presigned URLs generated for secure access
+- Example: Avatar upload in `src/orpc/routes/profile.ts` deletes old file, uploads new one
+
+**Internationalization:**
+- Server detects language from headers in `setSSRLanguage()`
+- Client-side i18next initialized with fallback locale
+- All user-facing strings wrapped in `t()` function
+- Translations in `src/lib/intl/locales/`
+
+**Theme Management:**
+- Next Themes provider in root layout
+- CSS custom properties (OKLCH) in `src/app.css`
+- Dark/light mode toggled via `.dark` class on `<html>`
+- Token-based styling (no hardcoded colors)
+
+---
+
+*Architecture analysis: 2026-02-21*
diff --git a/.planning/codebase/CONCERNS.md b/.planning/codebase/CONCERNS.md
new file mode 100644
index 0000000..0aeab91
--- /dev/null
+++ b/.planning/codebase/CONCERNS.md
@@ -0,0 +1,267 @@
+# Codebase Concerns
+
+**Analysis Date:** 2026-02-21
+
+## Tech Debt
+
+**Email Template Implementation:**
+- Issue: Verify email template uses plain React Email components instead of proper template structure
+- Files: `apps/start-template/src/components/emails/verify-email.tsx`
+- Impact: Email formatting is minimal; lacks proper branding, styling consistency, and may not render well across email clients
+- Fix approach: Replace plain `<Text>` and `<Button>` with structured email components using React Email's layout system, add proper styling with inline CSS, test across major email clients
+
+**Pagination Backend Mismatch:**
+- Issue: Frontend counts invitations client-side without backend returning total count, causing pagination inconsistency
+- Files: `apps/start-template/src/routes/(dashboard)/organizations/invitations/index.tsx` (line 71)
+- Impact: Pagination logic relies on array length instead of server-returned total; will break when backend implements server-side pagination or filtering
+- Fix approach: Update backend oRPC endpoint to return `{ data: Invitation[], total: number }` structure, update frontend to use `total` from response
+
+**Schema Validation Gaps:**
+- Issue: Chat route accepts `z.any()` for messages validation instead of properly typed schema
+- Files: `apps/start-template/src/orpc/routes/chat.ts` (line 30)
+- Impact: No runtime validation of message structure; can store malformed data; unclear what fields are required
+- Fix approach: Create strict Zod schema for message objects with proper typing for all message variants (text, code, etc.)
+
+**Unsafe HTML Rendering:**
+- Issue: Dynamic CSS generation using `dangerouslySetInnerHTML` in chart and schema display components
+- Files:
+  - `apps/start-template/src/components/ui/chart.tsx` (line 83)
+  - `apps/start-template/src/components/ai-elements/schema-display.tsx`
+- Impact: Potential XSS vulnerability if config keys or paths aren't sanitized; CSS injection possible
+- Fix approach: Use CSS-in-JS (Tailwind classes or styled components) instead of dynamic string generation; if inline styles are required, sanitize input values
+
+## Known Bugs
+
+**Invitations Total Count:**
+- Symptoms: Pagination indicator shows wrong total count on organizations invitations page
+- Files: `apps/start-template/src/routes/(dashboard)/organizations/invitations/index.tsx`
+- Trigger: Visit `/organizations/invitations/` with multiple pending invitations
+- Workaround: None - pagination will show incorrect count but items display correctly
+
+## Security Considerations
+
+**Optional AI API Keys:**
+- Risk: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY` marked as optional in environment validation but used without fallback
+- Files: `apps/start-template/src/lib/env.server.ts`
+- Current mitigation: Runtime validation via Zod
+- Recommendations:
+  - Document which API keys are required vs. optional
+  - Add runtime checks in chat route before attempting to use unprovided APIs
+  - Return clear error messages if user selects a model without corresponding API key configured
+
+**Email OTP Delivery:**
+- Risk: Email-based authentication relies on Resend service; no fallback mechanism
+- Files: `apps/start-template/src/lib/auth/auth.ts`, `apps/start-template/src/lib/resend.ts`
+- Current mitigation: Environment variable validation
+- Recommendations:
+  - Add retry logic with exponential backoff for failed email sends
+  - Log failed OTP sends for debugging
+  - Consider fallback SMS delivery or alternative channels
+
+**Stripe Configuration Errors:**
+- Risk: Stripe plugin throws on missing configuration but doesn't validate webhook signature properly
+- Files: `apps/start-template/src/lib/auth/auth.ts` (lines 64-67)
+- Current mitigation: Error thrown at initialization
+- Recommendations:
+  - Validate webhook signature in all stripe event handlers
+  - Add idempotency checks for webhook handlers (duplicate deliveries)
+  - Implement webhook event logging for audit trail
+
+## Performance Bottlenecks
+
+**Large Prompt Input Component:**
+- Problem: `prompt-input.tsx` is 1337 lines, likely containing multiple concerns
+- Files: `apps/start-template/src/components/ai-elements/prompt-input.tsx`
+- Cause: Monolithic component handling file attachments, command autocomplete, clipboard events, and multiple UI states in single file
+- Improvement path:
+  - Extract attachment handling into separate hook (`usePromptAttachments`)
+  - Extract command logic into separate component (`PromptCommand`)
+  - Extract textarea logic into separate component or hook
+  - Consider extracting keyboard handlers into custom hook
+
+**Complex Chat Route:**
+- Problem: Chat index route is 457 lines managing message streaming, model selection, web search toggle, and multiple UI rendering branches
+- Files: `apps/start-template/src/routes/(dashboard)/chat/index.tsx`
+- Cause: Business logic mixed with UI rendering; conditional rendering for multiple message part types
+- Improvement path:
+  - Extract message rendering into separate component file
+  - Extract model selector logic into custom hook
+  - Use `<Suspense>` boundaries for lazy message parts
+  - Consider extracting search UI into separate component
+
+**Data Grid Enhanced Component:**
+- Problem: `data-grid-enhanced.tsx` is 749 lines with inline type definitions and complex DOM tree
+- Files: `apps/start-template/src/components/ui/data-grid-enhanced.tsx`
+- Cause: Wrapper around React Table with custom styling and layout
+- Improvement path:
+  - Extract column header rendering logic
+  - Extract pagination control into separate component
+  - Extract toolbar into separate component
+  - Consider using composition pattern instead of single monolithic component
+
+**Sidebar Component Complexity:**
+- Problem: `sidebar.tsx` is 725 lines with many nested conditionals
+- Files: `apps/start-template/src/components/ui/sidebar.tsx`
+- Cause: Base UI primitive with full feature set including collision detection, responsive behavior
+- Improvement path: Acceptable as base UI component - monitor if it grows further; consider extracting sidebar menu logic into separate component
+
+## Fragile Areas
+
+**RLS (Row-Level Security) Policies:**
+- Files: `apps/start-template/src/lib/db/rls.test.ts`
+- Why fragile: PostgreSQL RLS policies must be kept in sync with application authorization logic; manual SQL configuration prone to inconsistency
+- Safe modification:
+  - Always update both schema policy AND test cases
+  - Test with non-superuser connection to verify policies work
+  - Run full RLS test suite before deployment
+- Test coverage: RLS policies have dedicated test file; good coverage for auth, organization, and storage tables
+
+**Better-Auth Plugin Chain:**
+- Files: `apps/start-template/src/lib/auth/auth.ts`
+- Why fragile: Multiple plugins (stripe, passkey, organization, 2FA, magic link) with interdependencies; plugin order matters
+- Safe modification:
+  - Document plugin dependencies and initialization order
+  - Test authentication flows after any plugin changes
+  - Verify Stripe webhook events still fire correctly after updates
+- Test coverage: Auth has permission tests but not full auth flow tests
+
+**oRPC Middleware Chain:**
+- Files: `apps/start-template/src/orpc/orpc-server.ts`
+- Why fragile: `publicProcedure → protectedProcedure → protectedRlsProcedure` chain; middleware order critical for security
+- Safe modification:
+  - Never reorder middleware without testing authorization
+  - Verify RLS context is set before data queries
+  - Test with both authenticated and unauthenticated requests
+- Test coverage: Permission and RLS tests exist; missing integration tests for oRPC routes
+
+**Chat State Management:**
+- Files: `apps/start-template/src/routes/(dashboard)/chat/index.tsx`
+- Why fragile: Uses `useChat()` from AI SDK with manual state management for selectedModel, useWebSearch, attachments
+- Safe modification:
+  - Document state synchronization between useChat and local state
+  - Test message persistence when switching models
+  - Verify attachments are preserved during streaming
+- Test coverage: No tests for chat functionality; high risk area for regressions
+
+## Scaling Limits
+
+**Database Invitations Pagination:**
+- Current capacity: All invitations loaded into memory client-side
+- Limit: Will degrade when users have >1000 invitations (memory, rendering slowdown)
+- Scaling path:
+  - Implement server-side pagination in `userInvitationsOptions()` query
+  - Return `{ data: Invitation[], total: number }` from backend
+  - Update frontend to use pagination state
+  - Add indices on `invitations.userId, invitations.status` for query optimization
+
+**AI Chat History Storage:**
+- Current capacity: All messages stored as JSON array in single `chat.messages` column
+- Limit: Large conversations (>10k messages) will cause slow queries and memory issues
+- Scaling path:
+  - Create separate `chat_messages` table with indexed `chatId` FK
+  - Migrate existing data from JSON array to normalized table
+  - Implement pagination/cursor-based loading for messages
+  - Add archival strategy for old conversations
+
+**Sidebar Route Generation:**
+- Current capacity: RouteTree generated at build time; static at runtime
+- Limit: Dynamic route creation not supported; new routes require rebuild
+- Scaling path: If dynamic routing needed, consider route configuration file instead of code generation
+
+## Dependencies at Risk
+
+**Nitro (Pre-Release Version):**
+- Risk: `nitro@3.0.1-alpha.2` is alpha version; breaking changes possible in minor updates
+- Impact: Production deployments may break on dependency updates
+- Migration plan:
+  - Pin to specific alpha version; don't use `^` or `~`
+  - Monitor Nitro releases for stable v3.0.0
+  - Test thoroughly before upgrading
+  - Consider alternative: Elysia is already used for server runtime
+
+**Vite Overrides:**
+- Risk: `package.json` overrides `vite` to `8.0.0-beta.15` which is pre-release
+- Impact: Build tool instability; potential breaking changes
+- Migration plan:
+  - Upgrade to stable Vite 8.0.0 when available
+  - Test build output thoroughly
+  - Remove override from package.json
+
+**React 19 (New):**
+- Risk: React 19.2.4 is recent; ecosystem integration may lag
+- Impact: Third-party libraries may not be fully compatible; refs as props is new paradigm
+- Migration plan:
+  - Audit dependencies for React 19 compatibility
+  - Test form libraries, UI components thoroughly
+  - Monitor third-party library releases for React 19 support
+
+**oRPC (Actively Developed):**
+- Risk: oRPC 1.13.5 is rapidly evolving; API surface may change
+- Impact: Major version updates could require refactoring
+- Migration plan:
+  - Pin to specific version; don't use `^`
+  - Read CHANGELOG before updating
+  - Run full integration test suite after updates
+
+## Missing Critical Features
+
+**Offline Support:**
+- Problem: No service worker or offline capability for chat functionality
+- Blocks: Chat messages lost if network disconnects; no draft preservation
+- Priority: Medium - affects usability but not core feature
+
+**Audit Logging:**
+- Problem: No audit trail for sensitive operations (organization changes, permission updates, Stripe events)
+- Blocks: Compliance audits, security incident investigation
+- Priority: High - required for production deployment with sensitive data
+
+**Rate Limiting:**
+- Problem: Upstash Redis imported but not integrated into oRPC routes
+- Blocks: API abuse protection; chat spam prevention
+- Priority: High - production security requirement
+
+**Data Export:**
+- Problem: No way for users to export their data (GDPR requirement)
+- Blocks: GDPR/regulatory compliance
+- Priority: Critical - legal requirement for EU users
+
+**Conversation Search:**
+- Problem: Chat history not searchable; all messages must be loaded
+- Blocks: Finding past conversations at scale
+- Priority: Medium - usability for power users
+
+## Test Coverage Gaps
+
+**UI Components:**
+- What's not tested: All AI elements (Message, CodeBlock, StackTrace, etc.), data grid components, form components
+- Files: `apps/start-template/src/components/ai-elements/*`, `apps/start-template/src/components/ui/*`
+- Risk: Visual regressions, accessibility issues, event handler bugs go undetected
+- Priority: High - 57+ UI components with no tests
+
+**Features Module:**
+- What's not tested: Organizations CRUD, invitations flow, settings updates, subscription management
+- Files: `apps/start-template/src/features/organizations/*`, `apps/start-template/src/features/settings/*`, `apps/start-template/src/features/payment/*`
+- Risk: Business logic bugs in user-facing features
+- Priority: High - core app functionality
+
+**oRPC Endpoints:**
+- What's not tested: Chat save/read/list, storage operations, dashboard queries
+- Files: `apps/start-template/src/orpc/routes/chat.ts`, `apps/start-template/src/orpc/routes/storage.ts`, `apps/start-template/src/orpc/routes/dashboard.ts`
+- Risk: Data corruption, authorization bypasses, null reference errors in server code
+- Priority: High - backend data operations
+
+**Email System:**
+- What's not tested: Email templates render correctly, SMTP delivery, OTP generation
+- Files: `apps/start-template/src/components/emails/*`, `apps/start-template/src/lib/auth/email-helpers.ts`
+- Risk: Users don't receive emails, templating errors, broken verification links
+- Priority: Medium - affects user experience but not core chat functionality
+
+**Routes and Navigation:**
+- What's not tested: Route guards, protected route access, redirect logic
+- Files: `apps/start-template/src/routes/**/*`, `apps/start-template/src/router.tsx`
+- Risk: Unauthorized access, incorrect redirects, broken deep links
+- Priority: Medium - security and navigation critical
+
+---
+
+*Concerns audit: 2026-02-21*
diff --git a/.planning/codebase/CONVENTIONS.md b/.planning/codebase/CONVENTIONS.md
new file mode 100644
index 0000000..7c5eb9b
--- /dev/null
+++ b/.planning/codebase/CONVENTIONS.md
@@ -0,0 +1,243 @@
+# Coding Conventions
+
+**Analysis Date:** 2026-02-21
+
+## Naming Patterns
+
+**Files:**
+- Feature files follow pattern `<feature>.<scope>.<type>.tsx` (e.g., `organizations.create-dialog.tsx`, `settings.page.section.profile.tsx`)
+- UI component files: `kebab-case.tsx` (e.g., `button.tsx`, `data-grid-enhanced.tsx`, `field-label.tsx`)
+- Utility/helper files: `kebab-case.ts` (e.g., `plan.utils.ts`, `super-admin.ts`)
+- Type definition files: `<feature>.types.ts` (e.g., `organizations.types.ts`)
+- Test directories: `__tests__/` (co-located with source)
+- Test files: `<name>.test.ts` or `<name>.test.tsx`
+
+**Functions:**
+- Use camelCase for all functions: `canAssignRole()`, `getPlanDisplayName()`, `getUserPlanName()`
+- Prefix permission functions with verb: `can*` for checks (`canDeleteOrganization()`), `get*` for retrieval (`getAssignableRoles()`)
+- Factory functions: `*Options()` for React Query mutationOptions/queryOptions (e.g., `createOrganizationOptions()`, `resendInvitationOptions()`)
+- Exported components: PascalCase with function declaration (e.g., `export function OrganizationCreateDialog()`)
+
+**Variables:**
+- Use camelCase: `currentUserRole`, `organizationId`, `invitationId`, `createOrganizationMutation`
+- Constants with enums/readonly: PascalCase or camelCase depending on usage
+- Avoid `var`, use `const` by default, `let` only when reassignment needed
+- Boolean predicates: `is*`, `can*`, `has*` (e.g., `isFreePlan()`, `canManageOrganization()`, `hasPermission()`)
+
+**Types:**
+- Type names: PascalCase (e.g., `OrganizationRole`, `OrganizationMember`, `RawOrganizationMember`)
+- Generic types: PascalCase (e.g., `TFunction`)
+- Use `type` keyword for type definitions, `interface` only for extensibility
+- Export types with `export type` statement, not via barrel exports
+
+## Code Style
+
+**Formatting:**
+- Prettier (^3.8.1) with default config inherited from package root
+- Line length: no hard limit, readability-focused
+- Quotes: double quotes (`"`) for strings and imports
+- Semicolons: required at statement ends
+- Indentation: 2 spaces
+
+**Linting:**
+- Biome (2.4.4) via Ultracite (7.2.3)
+- Config: `biome.jsonc` extends `ultracite/biome/core`, `ultracite/biome/react`, `ultracite/biome/remix`
+- Rule override: `style.useConsistentTypeDefinitions` is `off` (allows both `type` and `interface`)
+- Enforced by CI: run `bun run check` to validate
+- Auto-fix via: `bun run fix` (ultracite fix)
+- Key rules enforced:
+  - No `console`, `debugger`, `alert` in production code
+  - No `any` type (use `unknown` if needed)
+  - No `var` declarations
+  - No default exports (named exports only)
+  - Use `for...of` over `.forEach()`
+  - `===` and `!==` only (no loose equality)
+  - Semantic HTML and ARIA for accessibility
+
+## Import Organization
+
+**Order (strict):**
+1. External dependencies (React, third-party libraries): `import React from "react"`
+2. Type imports: `import type { ClassValue } from "clsx"`
+3. Internal absolute imports: `import { cn } from "@/lib/utils"`
+4. Relative imports (if any, avoid): `import { localHelper } from "./helpers"`
+
+**Example:**
+```typescript
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { Building2Icon } from "lucide-react";
+import { Controller, FormProvider, useForm } from "react-hook-form";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+import { Button } from "@/components/ui/button";
+import { Dialog } from "@/components/ui/dialog";
+import { createOrganizationOptions } from "@/features/organizations/organizations.factory.mutations";
+import type { OrganizationFormData } from "@/features/organizations/organizations.utils";
+```
+
+**Path Aliases:**
+- `@/*` → `./src/*` (absolute imports only, no relative paths)
+- Always use path aliases, never deep relative imports like `../../../lib/`
+
+**Import Type:**
+- Use `import type { TypeName }` for types, separate from value imports
+- Always explicitly mark types when re-exporting
+
+## Error Handling
+
+**Patterns:**
+- Zod for schema validation: use `safeParse()` to return `{ success: boolean, data?, error? }`
+- React Query: throw errors in mutation functions to be caught by error handlers
+- Better Auth errors: check `result.error` and throw as Error: `if (result.error) throw new Error(result.error.message)`
+- UI notifications: surface errors via toast (`sonner`), never `console.log()` errors
+- Permission checks: return boolean from permission functions, throw in protected routes via `beforeLoad`
+- Field-level errors: use React Hook Form's `fieldState.error` with `<FieldError>` component
+
+**Error Messages:**
+- All user-facing error messages use i18n keys: `t("ORG_CREATE_FAILED")`, `t("COMMON_UNKNOWN_ERROR")`
+- Combine with specific error detail when available: `` t("KEY") + (error.message || "") ``
+
+## Logging
+
+**Framework:** No centralized logging library; use `console` in development only.
+
+**Patterns:**
+- NO console logs in production code (Biome enforces via linter)
+- Errors surface via toast notifications, not logs
+- Server-side: Pino logger available for backend (`pino` package installed but not heavily used)
+- Query errors: caught by React Query error handlers, display in UI
+- Validation errors: show in form fields, not console
+
+## Comments
+
+**When to Comment:**
+- JSDoc for exported functions, especially permission/validation helpers
+- Inline comments for non-obvious business logic (e.g., permission matrices)
+- No comments for self-documenting code (variable names explain intent)
+
+**JSDoc/TSDoc:**
+```typescript
+/**
+ * Check if user can manage organization (update settings)
+ * Owner and Admin can manage
+ */
+export function canManageOrganization(role: OrganizationRole): boolean {
+  return role === "owner" || role === "admin";
+}
+```
+
+**Comment Style:**
+- Block comments: `/* ... */` for multi-line explanations
+- Inline comments: `// ...` for single lines
+- Avoid over-commenting; prefer clear naming
+
+## Function Design
+
+**Size:**
+- Keep functions focused on single responsibility
+- Permission check functions: typically 2-5 lines
+- Mutation/query factory functions: 5-15 lines
+- Component functions: 50-150 lines (split into sub-components if larger)
+
+**Parameters:**
+- Prefer single parameter objects for functions with 2+ params
+- Type each parameter explicitly
+- Use optional chaining and nullish coalescing where needed
+
+**Return Values:**
+- Be explicit about what a function returns
+- Use `void` for functions with side effects only
+- Use type unions carefully: `string | undefined` over `string | null | undefined`
+- Permission functions return `boolean`
+- Mutation/query options return factory-created options objects
+
+## Module Design
+
+**Exports:**
+- Named exports only, no default exports
+- Export as many named items as needed; don't force barrel files
+- Co-locate related exports: types with functions, utilities with helpers
+
+**Barrel Files:**
+- Use index files (`index.ts`) for grouping related exports
+- Pattern: `export { Component1, Component2 } from "./component1"`
+- Keep barrel files minimal, list all exports explicitly
+
+**Example from codebase (`organizations.factory.mutations.ts`):**
+```typescript
+export const cancelInvitationOptions = () =>
+  mutationOptions({ mutationFn: async (invitationId: string) => { ... } });
+
+export const resendInvitationOptions = () =>
+  mutationOptions({ mutationFn: async (input: ResendInvitationInput) => { ... } });
+```
+
+## Component Conventions (UI & Features)
+
+**File Naming:**
+- UI: `button.tsx`, `input.tsx`, `field-label.tsx`
+- Feature modules: `organizations.create-dialog.tsx`, `settings.page.section.profile.tsx`
+
+**Named Exports Only:**
+```typescript
+export function Button({ className, variant, size, ...props }: Props) {
+  return <button className={cn(...)} {...props} />
+}
+
+export { Button, buttonVariants }
+```
+
+**Props Pattern:**
+- Define explicit Props interface/type
+- Use `React.ComponentProps<"element">` for native elements
+- Spread `...props` last after named props
+- Always merge classes with `cn()` from `@/lib/utils`
+
+**Class Merging:**
+```typescript
+const buttonVariants = cva("base-classes", {
+  variants: { /* ... */ },
+  defaultVariants: { /* ... */ },
+})
+
+function Button({ className, variant, size, ...props }: Props & VariantProps<typeof buttonVariants>) {
+  return <button className={cn(buttonVariants({ variant, size, className }))} {...props} />
+}
+```
+
+**data-slot Attribute (Required):**
+```typescript
+export function Button({ className, ...props }: Props) {
+  return <button className={cn(...)} data-slot="button" {...props} />
+}
+```
+
+**Client Directive:**
+```typescript
+"use client"
+
+export function DialogContent() { /* ... */ }
+```
+
+## TypeScript Rules
+
+- Strict mode enabled (`tsconfig.json`)
+- No implicit `any` (Biome enforces)
+- Prefer `unknown` over `any` if must accept anything
+- Use `satisfies` operator for const assertions: `const colors = { ... } satisfies Record<string, string>`
+- Avoid type assertions unless absolutely necessary
+- Use discriminated unions for complex type logic
+
+## React 19 Conventions
+
+- Use function components (no class components)
+- Ref as prop: no `React.forwardRef` needed, just accept `ref` prop
+- `key` prop: use stable IDs, not array indices (Biome enforces)
+- Hooks: use standard rules (only in components/hooks, not conditional)
+- `use client` directive: add at top of client components
+
+---
+
+*Convention analysis: 2026-02-21*
diff --git a/.planning/codebase/INTEGRATIONS.md b/.planning/codebase/INTEGRATIONS.md
new file mode 100644
index 0000000..6e4a5a3
--- /dev/null
+++ b/.planning/codebase/INTEGRATIONS.md
@@ -0,0 +1,223 @@
+# External Integrations
+
+**Analysis Date:** 2026-02-21
+
+## APIs & External Services
+
+**AI Models:**
+- OpenAI - GPT-4o, GPT-4o-mini models for chat
+  - SDK/Client: `@ai-sdk/openai` (via unified AI SDK)
+  - Auth: `OPENAI_API_KEY` (environment variable)
+  - Usage: `src/routes/api/chat/index.ts` - Multi-provider chat endpoint
+
+- Anthropic - Claude models (default: claude-3-5-haiku-latest)
+  - SDK/Client: `@ai-sdk/anthropic` (via unified AI SDK)
+  - Auth: `ANTHROPIC_API_KEY`
+  - Usage: `src/routes/api/chat/index.ts` - Supports all Claude variants
+
+- Google - Gemini models (2.0-flash)
+  - SDK/Client: `@ai-sdk/google` (via unified AI SDK)
+  - Auth: `GOOGLE_GENERATIVE_AI_API_KEY`
+  - Usage: `src/routes/api/chat/index.ts` - Stream-based chat responses
+
+**Payment Processing:**
+- Stripe - Payment gateway and subscriptions
+  - SDK/Client: `stripe` (JS SDK) + `@better-auth/stripe` (plugin)
+  - Auth: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`
+  - Config: `src/lib/stripe/plans.config.ts` - Plan definitions with Stripe price IDs
+  - Integration: Better-Auth plugin at `src/lib/auth/auth.ts` (lines 63-96)
+  - Features: Subscription management, webhook events, checkout sessions
+  - Plans: Free, Starter ($9/mo), Pro ($29/mo, highlighted), Enterprise ($99/mo)
+  - API Version: 2025-12-15.clover
+  - Webhook Events Handled:
+    - `checkout.session.completed` - Checkout success
+    - `customer.subscription.updated` - Subscription changes
+    - `customer.subscription.deleted` - Subscription cancellation
+  - Usage: `src/features/payment/stripe/`, `src/features/subscription/`
+
+**Email Service:**
+- Resend - Transactional email delivery
+  - SDK/Client: `resend` (Resend SDK)
+  - Auth: `RESEND_API_KEY`
+  - From Email: `RESEND_FROM_EMAIL` (optional, defaults to noreply@example.com)
+  - Integration: `src/lib/resend.ts` - Email sending with React Email templates
+  - Features: HTML + plain text rendering via `@react-email/render`
+  - Email Templates: `src/components/emails/` - Verification, password reset, magic link, OTP, subscription notifications
+  - Usage: Better-Auth email hooks at `src/lib/auth/email-helpers.ts`
+
+## Data Storage
+
+**Databases:**
+- PostgreSQL (primary)
+  - Connection: `DATABASE_URL` (environment variable)
+  - Client: Drizzle ORM with Bun's native S3Client for SQL execution
+  - Dialect: `postgresql`
+  - ORM: `drizzle-orm` 0.45.1 + `drizzle-zod` for validation
+  - Schema Location: `src/lib/db/schema/`
+    - `auth.ts` - User, session, account, verification token tables (Better-Auth schema)
+    - `chat.ts` - Chat history and messages
+    - `storage.ts` - File metadata and storage references
+  - Migrations: Managed via Drizzle Kit (`src/lib/db/migrations/`)
+  - Row-Level Security (RLS): Postgres RLS policies via `withRls()` middleware at `src/orpc/routes/`
+  - Commands: `bun run db:push`, `bun run db:generate`, `bun run db:studio`
+
+**File Storage:**
+- S3-Compatible Services (configurable)
+  - Provider: `STORAGE_PROVIDER` (enum: s3, cloudflare-r2, seaweedfs, digitalocean-spaces, google-cloud-storage, supabase-storage)
+  - Default: AWS S3
+  - Client: Bun's native `S3Client`
+  - Config Variables:
+    - `S3_ACCESS_KEY_ID` - Access key for S3-compatible service
+    - `S3_SECRET_ACCESS_KEY` - Secret key
+    - `S3_BUCKET` - Bucket name (auto-lowercased)
+    - `S3_REGION` - Region (default: us-east-1)
+    - `S3_ENDPOINT` - Custom endpoint (optional, for non-AWS services)
+  - Implementation: `src/lib/storage/index.ts` - Upload, download, delete, presign, list operations
+  - Features: Presigned URLs (default 24h expiry), retry with backoff, file validation
+  - Database: File metadata tracked in `storage` table at `src/lib/db/schema/storage.ts`
+  - Endpoints: `src/routes/api/storage/$.ts` - REST API for file operations
+  - Usage: Profile avatars, document uploads via `src/orpc/routes/storage.ts`
+
+**Caching & Rate Limiting:**
+- Upstash Redis (optional)
+  - Connection: `REDIS_URL` (optional environment variable)
+  - Client: `@upstash/redis` 1.36.2
+  - Rate Limiting: `@upstash/ratelimit` 2.0.8
+  - Usage: Resumable chat streams and rate limit checks
+  - Note: Only activated if `REDIS_URL` is set
+
+## Authentication & Identity
+
+**Auth Provider:**
+- Better-Auth 1.4.18 (custom implementation)
+  - Server Config: `src/lib/auth/auth.ts` - Full implementation with plugins
+  - Client: `src/lib/auth/auth-client.ts` - Client-side API wrapper
+  - Session Verification: `BETTER_AUTH_SECRET` (environment variable)
+  - Base URL: `BETTER_AUTH_BASE_URL` (default: http://localhost:3000)
+  - Trusted Origins: `BETTER_AUTH_TRUSTED_ORIGINS` (optional, CORS control)
+  - Database Adapter: Drizzle ORM adapter (`better-auth/adapters/drizzle`)
+  - Schema Location: `src/lib/db/schema/auth.ts` (auto-generated via `auth:generate` command)
+
+**Auth Plugins Enabled:**
+- **Organization** - Multi-organization support with invitations and roles
+- **2FA** - Two-factor authentication (TOTP)
+- **Email OTP** - One-time password via email
+- **Passkeys** - WebAuthn passkey authentication (`@better-auth/passkey`)
+  - Requires Reflect.getMetadata polyfill (added in `vite.config.ts` lines 14-42)
+- **Magic Link** - Passwordless email link authentication
+- **Last Login Method** - Track user's last login method
+- **Admin** - Admin role and access control
+- **Stripe** - Automatic customer creation on signup, subscription management
+
+**Social & OAuth:**
+- Email-based auth (verification via Resend)
+- Magic link sign-in (via Resend)
+- Passkey authentication (WebAuthn)
+- No third-party OAuth detected (social providers not configured)
+
+**Roles & Permissions:**
+- Default Roles: `user`, `admin`, `owner`, `super_admin`
+- Implementation: `src/lib/auth/permissions.ts` - Access control via Better-Auth plugins
+- RBAC: Built on Better-Auth access control API
+- Usage: Enforced in oRPC protected procedures
+
+## Monitoring & Observability
+
+**Error Tracking:**
+- Not detected - No Sentry/LogRocket integration
+
+**Logs:**
+- Pino 10.3.1 - Structured JSON logging at `src/lib/auth/auth.ts`
+  - Level: info
+  - Stripe webhook events logged with metadata: event type, ID, timestamp, subscription details
+- Console: Application uses toast notifications (sonner) for user-facing errors
+- No console logging in production code (enforced by Biome linter)
+
+**Analytics:**
+- @vercel/analytics 1.6.1 - Web vitals tracking (Vercel-hosted only)
+
+**Observability Tools:**
+- @tanstack/devtools-vite - TanStack devtools for debugging
+- @tanstack/react-devtools - React devtools for client inspection
+- @tanstack/react-query-devtools - React Query inspection
+- @tanstack/react-router-devtools - Router debugging
+- drizzle-kit studio (`bun run db:studio`) - Database GUI
+- Vitest UI (`bun run test:ui`) - Test debugging UI
+
+## CI/CD & Deployment
+
+**Hosting:**
+- Vercel (native support)
+  - Configured in `vite.config.ts` lines 93-98 - Nitro Vercel preset with Bun 1.x runtime
+  - Automatic deployment from git pushes
+  - Production URL: `VERCEL_PROJECT_PRODUCTION_URL` (environment variable)
+  - Preview URLs: `VERCEL_URL`, `VERCEL_BRANCH_URL`
+
+**CI Pipeline:**
+- Not detected in repository - No GitHub Actions workflows configured
+
+**Build & Deployment:**
+- Bun as build runtime
+- Vite for bundling
+- Nitro for serverless functions
+- Docker support: `docker:build`, `docker:run` commands in package.json
+- S3 upload: `bun run upload:s3` command available
+
+## Environment Configuration
+
+**Required env vars (server-side):**
+```
+DATABASE_URL              # PostgreSQL connection string
+RESEND_API_KEY           # Email service API key
+BETTER_AUTH_SECRET       # Session encryption secret
+STRIPE_SECRET_KEY        # Stripe API secret (optional if payments disabled)
+STRIPE_WEBHOOK_SECRET    # Stripe webhook signing secret (optional)
+S3_ACCESS_KEY_ID         # Storage provider access key
+S3_SECRET_ACCESS_KEY     # Storage provider secret key
+S3_BUCKET                # Storage bucket name
+```
+
+**Optional env vars:**
+```
+ANTHROPIC_API_KEY        # Claude API key
+OPENAI_API_KEY          # OpenAI API key
+GOOGLE_GENERATIVE_AI_API_KEY  # Gemini API key
+REDIS_URL               # Redis connection (for rate limiting)
+S3_REGION               # S3 region (default: us-east-1)
+S3_ENDPOINT             # Custom S3 endpoint (for non-AWS)
+STORAGE_PROVIDER        # Storage type (default: s3)
+RESEND_FROM_EMAIL       # Custom from email
+BETTER_AUTH_BASE_URL    # Auth base URL (default: http://localhost:3000)
+BETTER_AUTH_TRUSTED_ORIGINS  # CORS trusted origins
+DRIZZLE_QUERY_LOGGER_ENABLED  # Enable query logging
+VERCEL_*                # Vercel deployment environment variables
+```
+
+**Secrets location:**
+- `.env` file (local development, not committed)
+- Environment variables in deployment platform (Vercel)
+- No .env.example file detected
+
+## Webhooks & Callbacks
+
+**Incoming:**
+- **Stripe Webhooks** - `src/lib/auth/auth.ts` (lines 76-92)
+  - Endpoint: Integrated into Better-Auth Stripe plugin
+  - Events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted
+  - Verification: HMAC signature verification via `STRIPE_WEBHOOK_SECRET`
+  - Handler: `onEvent` callback logs and processes subscription events
+
+- **Chat API** - `src/routes/api/chat/index.ts`
+  - POST `/api/chat/` - Streaming text responses from AI models
+  - Request body: messages, provider (openai/anthropic/gemini), model ID
+  - Response: Server-sent events (SSE) for streamed AI responses
+  - Auth: Session verification required
+
+**Outgoing:**
+- **Email Webhooks** - Not configured (Resend handles bounce/complaint tracking server-side)
+- **Stripe Customer Webhooks** - Automatically created for subscription events
+- No custom webhook implementations detected
+
+---
+
+*Integration audit: 2026-02-21*
diff --git a/.planning/codebase/STACK.md b/.planning/codebase/STACK.md
new file mode 100644
index 0000000..b97e805
--- /dev/null
+++ b/.planning/codebase/STACK.md
@@ -0,0 +1,221 @@
+# Technology Stack
+
+**Analysis Date:** 2026-02-21
+
+## Languages
+
+**Primary:**
+- TypeScript 5.9.3 - All source code, shared across apps and packages
+- JavaScript/JSX - React components with TypeScript extension (.tsx)
+
+**Secondary:**
+- SQL - PostgreSQL database queries via Drizzle ORM
+- CSS - Tailwind CSS v4 for styling
+
+## Runtime
+
+**Environment:**
+- Bun 1.3.4 - Package manager and JavaScript runtime (monorepo uses Bun workspaces)
+- Node.js >= 18 - Fallback runtime option
+
+**Package Manager:**
+- Bun 1.3.4 - Primary package manager for all development
+- Lockfile: Implicit (Bun manages lock files internally)
+
+## Frameworks
+
+**Core Frontend:**
+- React 19.2.4 - UI framework with functional components
+- TanStack React Start 1.161.3 - Full-stack React framework with file-based routing
+- TanStack React Router 1.161.3 - File-based routing system
+- Vite 7.3.1 - Build tool and dev server
+
+**Core Backend:**
+- Elysia 1.4.25 - Bun-native HTTP server framework
+- Nitro 3.0.1-alpha.2 - Universal server engine for serverless deployment
+
+**API & RPC:**
+- oRPC 1.13.5 - Type-safe RPC framework (full stack)
+  - Includes: `@orpc/server`, `@orpc/client`, `@orpc/react`, `@orpc/zod`, `@orpc/tanstack-query`
+- Better-Auth 1.4.18 - Authentication framework with plugins
+  - Plugins: passkey, stripe, organization, admin, 2FA, email-OTP, last-login-method
+
+**Data Management:**
+- React Query 5.90.21 - Async state management (via `@tanstack/react-query`)
+- Drizzle ORM 0.45.1 - Type-safe SQL ORM for PostgreSQL
+- Drizzle-Zod 0.8.3 - Schema validation bridge between Drizzle and Zod
+
+**AI Integration:**
+- AI SDK 6.0.97 - Unified interface for AI models (`ai` package)
+- `@ai-sdk/anthropic` 3.0.46 - Anthropic Claude models
+- `@ai-sdk/openai` 3.0.30 - OpenAI GPT models
+- `@ai-sdk/google` 3.0.30 - Google Gemini models
+- `@ai-sdk/react` 3.0.99 - React hooks for AI SDK
+
+**Testing:**
+- Vitest 4.0.18 - Unit/integration test runner
+- @vitest/ui 4.0.18 - Visual test UI
+- @vitest/coverage-v8 4.0.18 - Code coverage reporting
+- @testing-library/react 16.3.2 - Component testing utilities
+
+**Build & Dev Tools:**
+- Turbo 2.8.10 - Monorepo build orchestrator
+- Tailwind CSS 4.2.0 - Utility-first CSS framework with vite plugin
+- Biome 2.4.4 - Linter, formatter, and code quality tool
+- PostCSS 8.5.6 - CSS transformation pipeline
+
+**Forms & Validation:**
+- React Hook Form 7.71.2 - Form state management
+- @hookform/resolvers 5.2.2 - Validation framework integration
+- Zod 4.3.6 - TypeScript-first schema validation
+
+## Key Dependencies
+
+**Critical:**
+- `@tanstack/react-start` 1.161.3 - Full-stack framework, core abstraction layer
+- `@tanstack/react-router` 1.161.3 - Routing system replacing Next.js
+- `@tanstack/react-query` 5.90.21 - Server state sync, essential for data flow
+- Drizzle ORM 0.45.1 - Database abstraction, type-safe SQL
+- Better-Auth 1.4.18 - Authentication system with multi-plugin architecture
+- AI SDK (all providers) - Multi-provider LLM abstraction
+
+**UI Components:**
+- @base-ui/react 1.2.0 - Unstyled accessible primitives (replaces shadcn base)
+- radix-ui 1.4.3 - Accessible component primitives
+- lucide-react 0.575.0 - Icon library (primary)
+- @tabler/icons-react 3.37.1 - Secondary icon library
+- @remixicon/react 4.9.0 - Tertiary icon library
+- framer-motion 12.34.3 - Animation library
+- motion 12.34.3 - Motion components library
+- sonner 2.0.7 - Toast notification system
+- cmdk 1.1.1 - Command palette/menu component
+- embla-carousel-react 8.6.0 - Carousel component
+- vaul 1.1.2 - Dialog/drawer primitives
+
+**Data Visualization & Tables:**
+- @tanstack/react-table 8.21.3 - Headless table library
+- recharts 3.7.0 - React charting library
+- @xyflow/react 12.10.1 - Node-based workflow diagram library
+
+**Payment & Subscription:**
+- stripe 20.3.1 - Stripe API client (JavaScript SDK)
+- @better-auth/stripe 1.4.18 - Better-Auth Stripe integration plugin
+
+**Email & Messaging:**
+- resend 6.9.2 - Email API client
+- @react-email/components 1.0.8 - React email template components
+- @react-email/render 2.0.4 - Email template rendering
+
+**File Storage:**
+- S3Client via Bun (native) - S3-compatible object storage
+- Supports: AWS S3, Cloudflare R2, Seaweedfs, DigitalOcean Spaces, Google Cloud Storage, Supabase Storage
+
+**Internationalization (i18n):**
+- i18next 25.8.13 - i18n framework
+- react-i18next 16.5.4 - React bindings
+- i18next-browser-languagedetector 8.2.1 - Language auto-detection
+- i18next-resources-to-backend 1.2.1 - Backend resource loading
+
+**State Management:**
+- jotai 2.18.0 - Atomic state management (minimal alternative to Zustand)
+
+**Utilities:**
+- class-variance-authority 0.7.1 - CSS variant management
+- clsx 2.1.1 - Conditional CSS class builder
+- tailwind-merge 3.5.0 - Tailwind class conflict resolution
+- date-fns 4.1.0 - Date manipulation
+- nanoid 5.1.6 - Unique ID generation
+- uuid 13.0.0 - UUID generation
+- @paralleldrive/cuid2 3.3.0 - Collision-resistant IDs
+- pino 10.3.1 - Structured JSON logger
+- shiki 3.22.0 - Syntax highlighter
+- streamdown 2.3.0 - Markdown streaming parser
+- @streamdown/code 1.0.3 - Code block rendering
+- @streamdown/math 1.0.2 - Math expression rendering
+- @streamdown/mermaid 1.0.2 - Mermaid diagram rendering
+- @streamdown/cjk 1.0.2 - CJK text handling
+- @json-render/core 0.8.0 - JSON rendering core
+- @json-render/react 0.8.0 - JSON rendering for React
+- react-jsx-parser 2.4.1 - Dynamic JSX parsing
+
+**Drag & Drop:**
+- @dnd-kit/core 6.3.1 - Headless drag-and-drop library
+- @dnd-kit/sortable 10.0.0 - Sortable preset
+- @dnd-kit/modifiers 9.0.0 - Modifiers for movement constraints
+- @dnd-kit/utilities 3.2.2 - Utility functions
+
+**Authentication Extras:**
+- @better-auth/passkey 1.4.18 - WebAuthn passkey plugin
+- input-otp 1.4.2 - OTP input component
+
+**Rate Limiting & Caching:**
+- @upstash/ratelimit 2.0.8 - Serverless rate limiting
+- @upstash/redis 1.36.2 - Redis client for Upstash
+
+**Monitoring & Analytics:**
+- @vercel/analytics 1.6.1 - Web vitals and analytics
+- @vercel/mcp-adapter 0.3.2 - Model Context Protocol adapter
+
+**Environment & Configuration:**
+- @t3-oss/env-core 0.13.10 - Type-safe environment variable validation
+- dotenv 17.3.1 - .env file loading
+- dotenv-cli 11.0.0 - CLI for dotenv
+- tsx 4.21.0 - TypeScript execution wrapper
+
+**CLI & Scaffolding:**
+- @clack/prompts 1.0.1 - Terminal prompt utilities
+- giget 3.1.2 - Git repo template downloader
+- picocolors 1.1.1 - Terminal color library
+
+**Dev Quality:**
+- Prettier 3.8.1 - Code formatter
+- Husky 9.1.7 - Git hooks framework
+- ultracite 7.2.3 - Linter and code quality tool
+- Biome 2.4.4 - Linter/formatter (alternative to ESLint/Prettier)
+
+## Configuration
+
+**Environment:**
+- `.env` file (not committed) - Server-side secrets and configuration
+- `src/lib/env.server.ts` - Zod schema for environment validation with type safety
+- Key variables: `DATABASE_URL`, `BETTER_AUTH_SECRET`, `STRIPE_SECRET_KEY`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_GENERATIVE_AI_API_KEY`, `RESEND_API_KEY`, S3 credentials, `REDIS_URL`
+
+**Build:**
+- `vite.config.ts` at `apps/start-template/` - Vite build configuration
+  - Uses TanStack Start plugin for SSR
+  - Tailwind CSS via Vite plugin
+  - PostgreSQL support via `vite-plugin-db`
+  - Nitro for serverless
+  - Reflect.getMetadata polyfill for passkey support
+- `drizzle.config.ts` - Database migration configuration
+- `tsconfig.json` - TypeScript strict mode, path aliases (`@/*` → `./src/*`)
+- `.npmrc` - npm registry configuration (exists but empty - Bun native)
+- Turbo monorepo config in root `package.json`
+
+**Linting & Formatting:**
+- Biome 2.4.4 - Primary linter/formatter (via `ultracite` wrapper)
+- Prettier 3.8.1 - Secondary formatter option
+- ESLint - Not detected (Biome replaces it)
+
+## Platform Requirements
+
+**Development:**
+- Bun >= 1.0.0 (primary)
+- Node.js >= 18 (fallback)
+- PostgreSQL database
+- S3-compatible storage (local, AWS, Cloudflare, etc.)
+- Stripe account (for payment features)
+- Resend account (for email)
+- API keys for AI providers (OpenAI, Anthropic, Google)
+
+**Production:**
+- Deployment target: Vercel (native support via Nitro + TanStack Start)
+- PostgreSQL database (required)
+- Object storage provider (S3, R2, Supabase, etc.)
+- Email service (Resend)
+- Payment processor (Stripe)
+- Redis (optional, for rate limiting and resumable streams)
+
+---
+
+*Stack analysis: 2026-02-21*
diff --git a/.planning/codebase/STRUCTURE.md b/.planning/codebase/STRUCTURE.md
new file mode 100644
index 0000000..907922b
--- /dev/null
+++ b/.planning/codebase/STRUCTURE.md
@@ -0,0 +1,374 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-02-21
+
+## Directory Layout
+
+```
+apps/start-template/
+├── src/
+│   ├── routes/                      # File-based routing (TanStack Router)
+│   │   ├── __root.tsx              # Root layout, global providers
+│   │   ├── index.tsx               # Landing page
+│   │   ├── (auth)/                 # Layout group: sign-in, sign-up, password reset
+│   │   ├── (dashboard)/            # Protected layout group: chat, organizations, settings
+│   │   ├── api/                    # Backend API routes
+│   │   │   ├── rpc.$.ts           # oRPC gateway (main backend handler)
+│   │   │   ├── auth/$.ts          # Better-Auth handler
+│   │   │   ├── chat/              # Streaming AI chat endpoints
+│   │   │   └── storage/$.ts       # File storage endpoints
+│   │   ├── pricing.tsx, privacy.tsx, terms.tsx
+│   │   └── routeTree.gen.ts        # Auto-generated (TanStack Router)
+│   │
+│   ├── features/                    # Feature modules (co-located logic)
+│   │   ├── organizations/           # Org management (components, queries, mutations, types)
+│   │   ├── settings/                # User settings (profile, security, billing, appearance)
+│   │   ├── subscription/            # Stripe subscription UI
+│   │   ├── payment/                 # Payment/checkout features
+│   │   ├── landing/                 # Landing page components & data
+│   │   └── command-search/          # Command palette / search UI
+│   │
+│   ├── components/                  # Reusable UI components
+│   │   ├── ui/                      # Base UI primitives (~57 shadcn/Base UI components)
+│   │   │   ├── button.tsx
+│   │   │   ├── dialog.tsx
+│   │   │   ├── data-grid-enhanced.tsx  # Advanced table component
+│   │   │   └── ...
+│   │   ├── ai-elements/             # AI SDK UI components
+│   │   ├── emails/                  # React Email templates
+│   │   ├── guards/                  # Permission-based route guards
+│   │   ├── error-boundary.tsx       # Global error handling
+│   │   ├── not-found.tsx            # 404 page
+│   │   ├── theme-provider.tsx       # Next Themes
+│   │   └── __tests__/               # Component tests
+│   │
+│   ├── lib/                         # Core libraries & services
+│   │   ├── auth/                    # Authentication & RBAC
+│   │   │   ├── auth.ts             # Better-Auth configuration
+│   │   │   ├── auth-client.ts      # Client-side auth SDK
+│   │   │   ├── permissions.ts      # RBAC rules
+│   │   │   ├── queries.ts          # Auth React Query options
+│   │   │   ├── email-helpers.ts    # Email sending utilities
+│   │   │   ├── email-config.ts     # Email template config
+│   │   │   └── __tests__/          # Auth tests
+│   │   │
+│   │   ├── db/                      # Database layer (Drizzle + Postgres)
+│   │   │   ├── index.ts            # Drizzle client initialization
+│   │   │   ├── secure-client.ts    # RLS context helper (withRls)
+│   │   │   ├── rls.ts              # RLS policy setup
+│   │   │   ├── rls.test.ts         # RLS policy tests
+│   │   │   ├── db.utils.ts         # Database utilities
+│   │   │   ├── schema/             # Drizzle ORM schema definitions
+│   │   │   │   ├── auth.ts         # User, session, account (Better-Auth)
+│   │   │   │   ├── storage.ts      # File metadata
+│   │   │   │   ├── index.ts        # Schema exports
+│   │   │   │   └── ...
+│   │   │   └── migrations/         # Drizzle migration files
+│   │   │
+│   │   ├── storage/                 # File storage service
+│   │   │   └── s3.ts               # S3-compatible upload/download
+│   │   │
+│   │   ├── stripe/                  # Stripe payment integration
+│   │   │   ├── plans.config.ts     # Stripe plan definitions
+│   │   │   ├── plan.utils.ts       # Plan lookup utilities
+│   │   │   └── stripe-client.ts    # Stripe SDK client
+│   │   │
+│   │   ├── payment/                 # Payment utilities
+│   │   │   └── __tests__/          # Payment tests
+│   │   │
+│   │   ├── intl/                    # Internationalization
+│   │   │   ├── i18n.ts             # i18next configuration
+│   │   │   └── locales/            # Translation files
+│   │   │
+│   │   ├── validations/             # Zod validation schemas
+│   │   │   ├── *.ts                # Form validation schemas
+│   │   │   └── __tests__/          # Validation tests
+│   │   │
+│   │   ├── config/                  # Configuration
+│   │   │   └── app.config.ts       # App-level constants
+│   │   │
+│   │   ├── chat/                    # AI chat utilities
+│   │   ├── env.server.ts            # Server env vars validation
+│   │   ├── env.client.ts            # Client env vars validation
+│   │   ├── date-utils.ts            # Date formatting
+│   │   ├── device-utils.ts          # Device detection
+│   │   ├── cookie-consent.ts        # Cookie consent
+│   │   ├── flags.ts                 # Feature flags
+│   │   ├── resend.ts                # Email provider
+│   │   └── __tests__/               # Lib unit tests
+│   │
+│   ├── orpc/                        # Type-safe RPC layer
+│   │   ├── orpc-server.ts          # Server config & middleware
+│   │   ├── orpc-client.ts          # Client config & initialization
+│   │   ├── index.ts                # Router composition
+│   │   └── routes/                 # RPC procedure definitions
+│   │       ├── profile.ts          # User profile queries/mutations
+│   │       ├── organization.ts     # Organization management
+│   │       ├── dashboard.ts        # Dashboard data
+│   │       ├── storage.ts          # File operations
+│   │       └── chat.ts             # AI chat
+│   │
+│   ├── hooks/                       # Custom React hooks
+│   │   ├── use-*.ts                # Hook definitions
+│   │   └── __tests__/              # Hook tests
+│   │
+│   ├── utils/                       # Utility functions
+│   │   ├── seo.ts                  # SEO helpers
+│   │   └── *.ts                    # Other utilities
+│   │
+│   ├── providers/                   # React Context providers
+│   │   ├── subscription-provider.tsx
+│   │   └── ...
+│   │
+│   ├── app.css                      # Global styles & design tokens
+│   ├── client.tsx                   # Client entry point
+│   ├── server.ts                    # Server entry point
+│   └── router.tsx                   # Router configuration
+│
+├── public/                          # Static assets
+│   ├── images/
+│   ├── favicon*
+│   └── site.webmanifest
+│
+├── scripts/                         # Utility scripts
+│   ├── start-docker.sh
+│   ├── redis.sh
+│   ├── upload-to-s3.ts
+│   └── ...
+│
+├── .planning/                       # Planning & analysis docs
+│   └── codebase/                   # Generated codebase docs
+│
+├── package.json                     # App dependencies
+├── vite.config.ts                   # Vite build config
+├── vitest.config.ts                 # Test config
+├── drizzle.config.ts                # Drizzle ORM config
+├── tailwind.config.ts               # Tailwind CSS v4 config
+├── biome.json                       # Code formatter/linter
+└── tsconfig.json                    # TypeScript config
+```
+
+## Directory Purposes
+
+**routes/:**
+- Purpose: File-based routing tree (TanStack Router auto-generates from file structure)
+- Contains: Page components, layout groups, API routes
+- Key files: `__root.tsx` (root layout), `(dashboard)/layout.tsx` (protected layout), `api/rpc.$.ts` (main RPC handler)
+- Import: `src/routes/` → auto-compiled to `src/routeTree.gen.ts`
+
+**features/:**
+- Purpose: Domain-specific feature modules with co-located UI and logic
+- Contains: Components, hooks, mutations, queries, types
+- Pattern: Each folder is self-contained; imports from `src/lib/` and `src/components/`
+- Example: `src/features/organizations/` has all org-related UI and API calls
+
+**components/ui/:**
+- Purpose: Reusable, unstyled UI primitives (shadcn/Base UI)
+- Contains: ~57 components (Button, Card, Input, Dialog, etc.)
+- Pattern: Named exports only; use CVA for variants
+- Convention: Each file is one component with sub-components as named exports
+
+**lib/auth/:**
+- Purpose: Authentication and authorization
+- Contains: Better-Auth config, session management, RBAC
+- Key files: `auth.ts` (server config), `auth-client.ts` (client SDK), `permissions.ts` (role checks)
+- Exports: `authClient` for client calls, `auth` for server, permission functions
+
+**lib/db/:**
+- Purpose: Database access and schema
+- Contains: Drizzle ORM client, schema definitions, migrations, RLS helpers
+- Key files: `secure-client.ts` (RLS wrapper), `rls.test.ts` (policy tests), `schema/` (table definitions)
+- Critical: Always use `protectedRlsProcedure` for org/user-scoped data
+
+**lib/storage/:**
+- Purpose: File upload/download management
+- Contains: S3 client, upload logic, URL generation
+- Pattern: Abstracted S3 API; supports any S3-compatible provider
+
+**orpc/routes/:**
+- Purpose: Backend RPC procedure definitions
+- Contains: Handlers for queries and mutations, input validation, business logic
+- Key files: One file per domain (profile.ts, organization.ts, etc.)
+- Pattern: Export sub-routers; compose in `src/orpc/index.ts`
+
+## Key File Locations
+
+**Entry Points:**
+- `src/client.tsx`: Client hydration entry
+- `src/server.ts`: Server request handler
+- `src/router.tsx`: Router configuration & React Query setup
+- `src/routes/__root.tsx`: Root layout, global providers
+
+**Configuration:**
+- `src/lib/auth/auth.ts`: Better-Auth config
+- `src/lib/env.server.ts`: Server environment variables
+- `src/lib/env.client.ts`: Client environment variables
+- `src/lib/stripe/plans.config.ts`: Stripe plans
+- `src/lib/intl/i18n.ts`: i18n configuration
+
+**Core Logic:**
+- `src/orpc/orpc-server.ts`: oRPC context, middleware
+- `src/orpc/routes/`: Domain-specific procedures (profile, organization, etc.)
+- `src/lib/db/schema/`: Drizzle table definitions
+- `src/lib/auth/permissions.ts`: RBAC rules
+
+**Testing:**
+- `src/lib/__tests__/`: Utilities, helpers
+- `src/lib/auth/__tests__/`: Permission tests
+- `src/lib/db/rls.test.ts`: RLS policy tests
+- `src/lib/payment/__tests__/`: Payment logic tests
+- `src/lib/validations/__tests__/`: Schema validation tests
+- `src/components/__tests__/`: Component tests
+
+## Naming Conventions
+
+**Files:**
+- Route files: `index.tsx` or `[param].tsx`
+- Feature files: `<feature>.<scope>.<type>.tsx` (e.g., `organizations.members-table.tsx`)
+- UI primitives: `kebab-case.tsx` (e.g., `button.tsx`, `data-grid-enhanced.tsx`)
+- Hooks: `use-<name>.ts` (e.g., `use-organization-permissions.ts`)
+- Utilities: `<name>-utils.ts` or `<name>.ts`
+- Tests: `*.test.ts` or `*.spec.ts`
+- Factories/Query options: `<feature>.factory.queries.ts`, `<feature>.factory.mutations.ts`
+
+**Directories:**
+- Feature folders: PascalCase or lowercase plural (e.g., `organizations`, `settings`)
+- Layout groups: Parenthesized (e.g., `(auth)`, `(dashboard)`)
+- Sub-routes: Lowercase with hyphens (e.g., `/two-factor`, `/reset-password`)
+- API routes: `api/<domain>/<endpoint>`
+
+**Components:**
+- Named exports: `export { Button }`
+- Sub-components: `Button.Group`, `Button.Icon` (nested exports)
+- Props type: `ButtonProps` (or `<Component>Props`)
+- Styled wrapper: No separate styled files; styles inline with CVA
+
+**Database:**
+- Tables: `camelCase` in code, `snake_case` in SQL (Drizzle auto-converts)
+- Columns: `camelCase` (e.g., `createdAt`, `updatedAt`, `userId`)
+- Constraints: Foreign keys reference singular table name (e.g., `userId` → `user` table)
+
+**API/oRPC:**
+- Procedure names: `camelCase` (e.g., `profile.update`, `organization.listMembers`)
+- Input schemas: Exported as `<Procedure>Input` (e.g., `ProfileUpdateInput`)
+- Output schemas: Exported as `<Procedure>Output` (e.g., `ProfileUpdateOutput`)
+
+## Where to Add New Code
+
+**New Feature (Domain Module):**
+- Primary code:
+  - `src/features/<feature>/` — Create folder
+  - `src/features/<feature>/<feature>.components.tsx` — Feature UI
+  - `src/features/<feature>/<feature>.types.ts` — Types
+  - `src/features/<feature>/<feature>.factory.queries.ts` — React Query options
+  - `src/features/<feature>/<feature>.factory.mutations.ts` — Mutations
+- Backend:
+  - `src/orpc/routes/<feature>.ts` — oRPC procedures
+  - `src/lib/db/schema/<feature>.ts` — Drizzle tables (if needed)
+- Tests:
+  - `src/features/<feature>/__tests__/` — Feature tests
+  - `src/orpc/routes/<feature>.test.ts` — RPC tests (if complex logic)
+
+**New Page/Route:**
+- Location: `src/routes/<segment>/index.tsx` or `src/routes/<segment>/[param].tsx`
+- Add to layout group if protected: `src/routes/(dashboard)/<segment>/index.tsx`
+- If dynamic: `src/routes/(dashboard)/<segment>/$paramId.tsx`
+
+**New UI Component:**
+- If primitive (reusable): `src/components/ui/<name>.tsx`
+- If feature-specific: `src/features/<feature>/<feature>.<scope>.tsx`
+- Follow CVA pattern: Define variants, export component + variants
+
+**New Utility/Helper:**
+- Generic utilities: `src/utils/<name>.ts`
+- Domain-specific: `src/lib/<domain>/<name>.ts`
+- Format: Named exports, side-effect free
+
+**New API/RPC Procedure:**
+- Location: `src/orpc/routes/<domain>.ts`
+- Add to appropriate router file or create new one
+- Include Zod schema for input/output
+- Use `protectedProcedure` or `protectedRlsProcedure` as needed
+
+**New Database Table:**
+- Location: `src/lib/db/schema/<domain>.ts` or expand existing schema file
+- Use Drizzle `pgTable()` API
+- Include timestamps: `createdAt`, `updatedAt`
+- Add foreign keys and constraints
+- Create migration: `bun run db:generate`
+
+## Special Directories
+
+**src/routes/api/:**
+- Purpose: Backend API endpoints
+- Generated: No (manually created)
+- Committed: Yes
+- Special files:
+  - `rpc.$.ts` — Main oRPC gateway; all RPC calls route here
+  - `auth/$.ts` — Better-Auth session handler
+  - `chat/index.ts` — Streaming AI chat (Server-Sent Events)
+  - `storage/$.ts` — File upload/download proxy
+
+**src/lib/db/migrations/:**
+- Purpose: Drizzle migration history
+- Generated: Yes (`bun run db:generate` creates new migrations)
+- Committed: Yes (track all schema changes)
+- Manual: Do NOT edit migration files; modify `schema/` files instead
+
+**src/.planning/codebase/:**
+- Purpose: Generated codebase analysis documents
+- Generated: Yes (by `/gsd:map-codebase`)
+- Committed: Yes
+- Contains: ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, STACK.md, INTEGRATIONS.md, CONCERNS.md
+
+**src/components/ui/:**
+- Purpose: Reusable primitives
+- Generated: Yes (some via `shadcn` CLI, but managed in codebase)
+- Committed: Yes
+- Pattern: Run `bun run add-ui-components` to add new shadcn components
+
+**public/:**
+- Purpose: Static assets served at `/`
+- Generated: No
+- Committed: Yes (except large binary assets)
+- Examples: Images, favicons, manifests
+
+## Import Patterns
+
+**Path Aliases:**
+```typescript
+// CORRECT: Use @ alias for all imports from src/
+import { Button } from '@/components/ui/button'
+import { useProfile } from '@/hooks/use-profile'
+import { db } from '@/lib/db'
+
+// WRONG: Avoid relative imports
+import { Button } from '../../../components/ui/button'
+```
+
+**Type Imports:**
+```typescript
+// CORRECT: Use import type for types only
+import type { User } from '@/lib/auth/auth'
+import { authClient } from '@/lib/auth/auth-client'
+
+// WRONG: Mixed imports (splits compilation)
+import { authClient, type Session } from '@/lib/auth/auth-client'
+```
+
+**Feature/Module Organization:**
+```typescript
+// From components/ui/:
+import { Button, Card, CardContent } from '@/components/ui/card'
+
+// From features/:
+import { OrganizationForm } from '@/features/organizations/organizations.create-dialog'
+
+// From lib/:
+import { authClient } from '@/lib/auth/auth-client'
+import { db } from '@/lib/db'
+```
+
+---
+
+*Structure analysis: 2026-02-21*
diff --git a/.planning/codebase/TESTING.md b/.planning/codebase/TESTING.md
new file mode 100644
index 0000000..ed2c4a0
--- /dev/null
+++ b/.planning/codebase/TESTING.md
@@ -0,0 +1,390 @@
+# Testing Patterns
+
+**Analysis Date:** 2026-02-21
+
+## Test Framework
+
+**Runner:**
+- Vitest (^4.0.18) - modern Vite-native test runner
+- Config: `apps/start-template/vitest.config.ts`
+- Environment: jsdom (browser-like testing)
+- Globals: enabled (no need to import `describe`, `it`, `expect`)
+
+**Assertion Library:**
+- Built-in Vitest assertions (extends Chai): `expect()`
+
+**Setup:**
+- Setup file: `vitest.setup.ts` runs before tests
+- Includes `@testing-library/jest-dom` matchers
+- Auto-cleanup via `afterEach(() => cleanup())`
+- Global i18next mock (returns translation keys as-is)
+
+**Run Commands:**
+```bash
+bun run test              # Run all tests
+bun run test:watch       # Watch mode
+bun run test:ui          # Interactive UI
+bun run test:coverage    # Generate coverage report
+```
+
+## Test File Organization
+
+**Location:**
+- Co-located with source in `__tests__/` subdirectories
+- `src/lib/__tests__/` for utility tests
+- `src/lib/auth/__tests__/` for auth/permission tests
+- `src/lib/payment/__tests__/` for payment logic tests
+- `src/lib/validations/__tests__/` for validation schema tests
+- `src/components/__tests__/` for component tests
+- `src/hooks/__tests__/` for hook tests
+
+**Naming:**
+- Files: `<name>.test.ts` for utilities, `<name>.test.tsx` for components
+- Pattern: matches source file name but in `__tests__/` subdirectory
+- Example: `src/lib/utils.ts` → `src/lib/__tests__/utils.test.ts`
+
+**Structure:**
+```
+src/
+├── lib/
+│   ├── utils.ts
+│   └── __tests__/
+│       └── utils.test.ts
+├── lib/auth/
+│   ├── permissions.ts
+│   └── __tests__/
+│       └── permissions.test.ts
+└── components/
+    ├── cookie-consent.tsx
+    └── __tests__/
+        └── cookie-consent.test.tsx
+```
+
+## Test Structure
+
+**Suite Organization:**
+```typescript
+import { describe, expect, it } from "vitest";
+
+import { cn, nanoid, uuid } from "@/lib/utils";
+
+describe("cn utility", () => {
+  it("merges class names correctly", () => {
+    expect(cn("foo", "bar")).toBe("foo bar");
+  });
+
+  it("handles conditional classes", () => {
+    expect(cn("foo", false, "baz")).toBe("foo baz");
+  });
+});
+
+describe("nanoid utility", () => {
+  it("generates unique IDs", () => {
+    const id1 = nanoid();
+    const id2 = nanoid();
+    expect(id1).not.toBe(id2);
+  });
+});
+```
+
+**Patterns:**
+
+- One `describe` block per function/feature
+- One `it` block per specific behavior
+- Clear test names describe "what should happen": "merges class names correctly", "generates unique IDs"
+- Arrange-Act-Assert pattern (implicit in test structure)
+
+**Setup/Teardown:**
+```typescript
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+describe("ConsentAwareAnalytics", () => {
+  beforeEach(() => {
+    useCookieConsentOptionalMock.mockReset(); // Reset mocks between tests
+  });
+
+  it("does not render analytics when consent is not granted", () => {
+    // ... test
+  });
+});
+```
+
+## Mocking
+
+**Framework:** Vitest's built-in mocking with `vi.mock()` and `vi.fn()`
+
+**Mocking Module Dependencies:**
+```typescript
+const { useCookieConsentOptionalMock } = vi.hoisted(() => ({
+  useCookieConsentOptionalMock: vi.fn(),
+}));
+
+vi.mock("@/lib/cookie-consent-context", () => ({
+  useCookieConsentOptional: useCookieConsentOptionalMock,
+}));
+
+vi.mock("@vercel/analytics/react", () => ({
+  Analytics: () => <div data-testid="vercel-analytics" />,
+}));
+```
+
+**Mocking Custom Functions:**
+```typescript
+const mockT = vi.fn((key: string) => key) as unknown as TFunction;
+
+// Use in test
+const result = getPlanDisplayName("free", mockT);
+expect(result).toBe("PLAN_FREE");
+```
+
+**Mock Setup in vitest.setup.ts:**
+```typescript
+vi.mock("i18next", () => ({
+  default: {
+    t: (key: string) => key,
+    changeLanguage: vi.fn(),
+    language: "en",
+    init: vi.fn(),
+  },
+}));
+```
+
+**What to Mock:**
+- External API calls and HTTP requests
+- i18n (`i18next`) - mock returns translation keys as-is
+- Context providers that depend on external state
+- Analytics/third-party libraries with side effects
+- File system operations (never actually read/write files in tests)
+
+**What NOT to Mock:**
+- Business logic functions (test their actual behavior)
+- Validation functions - test real Zod schemas
+- Permission check functions - test actual rules
+- Pure utility functions - test real implementations
+- Database models/ORM - use test fixtures instead
+
+## Fixtures and Factories
+
+**Test Data:**
+- Use simple inline objects for small test data
+- No factory pattern yet; keep fixtures minimal
+
+**Example - Validation Tests (use `safeParse`):**
+```typescript
+describe("sign in validation behavior", () => {
+  it("rejects invalid email format", () => {
+    const result = signInSchema.safeParse({
+      email: "invalid-email",
+      password: "Password1",
+      rememberMe: false,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts valid credentials", () => {
+    const result = signInSchema.safeParse({
+      email: "test@example.com",
+      password: "Password123",
+      rememberMe: false,
+    });
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+**Location:**
+- Keep test data inline in test files
+- Use factories only for complex object hierarchies
+- Define types separately in `__tests__/` directory if reused
+
+## Coverage
+
+**Requirements:** No strict coverage targets enforced; optional measurement
+
+**View Coverage:**
+```bash
+bun run test:coverage
+```
+
+**Config (`vitest.config.ts`):**
+```typescript
+coverage: {
+  provider: "v8",
+  reporter: ["text", "json", "html"],
+  exclude: [
+    "node_modules/",
+    "src/**/__tests__/**",
+    "src/**/*.spec.ts",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.ts",
+    "src/**/*.test.tsx",
+    "dist/",
+    ".output/",
+    "coverage/",
+  ],
+}
+```
+
+## Test Types
+
+**Unit Tests (Primary):**
+- Test pure functions and business logic
+- Test utility functions: `cn()`, `nanoid()`, `uuid()`
+- Test permission/role functions: `canAssignRole()`, `canManageOrganization()`
+- Test validation schemas with Zod
+- Scope: single function or tightly-coupled module
+- Example: `src/lib/__tests__/utils.test.ts` (66 lines, 5 test suites)
+
+**Integration Tests:**
+- Test how modules interact
+- Test React components with rendering
+- Test form submissions and state updates
+- Use `@testing-library/react` with `render()` and `screen` queries
+- Example: `src/components/__tests__/cookie-consent.test.tsx` - tests component renders based on mock context
+
+**E2E Tests:**
+- Not currently used in this codebase
+- Would test full user flows (auth, org creation, etc.)
+- Framework: Playwright or Cypress (not configured)
+
+## Common Patterns
+
+**Behavior-Focused Tests:**
+Focus on WHAT code does, not HOW it does it. Test outcomes and side effects.
+
+Example - Permission Logic:
+```typescript
+describe("role assignment behavior", () => {
+  it("owner can assign any role", () => {
+    expect(canAssignRole("owner", "owner")).toBe(true);
+    expect(canAssignRole("owner", "admin")).toBe(true);
+    expect(canAssignRole("owner", "user")).toBe(true);
+  });
+
+  it("admin can assign user and admin roles", () => {
+    expect(canAssignRole("admin", "admin")).toBe(true);
+    expect(canAssignRole("admin", "user")).toBe(true);
+    expect(canAssignRole("admin", "owner")).toBe(false);
+  });
+});
+```
+
+Tests describe business rules (owner can assign anything), not implementation details.
+
+**Schema Validation Testing:**
+```typescript
+describe("sign up validation behavior", () => {
+  it("rejects password without lowercase letter", () => {
+    const result = signUpSchema.safeParse({
+      name: "John Doe",
+      email: "test@example.com",
+      password: "PASSWORD123",
+      confirmPassword: "PASSWORD123",
+      acceptTerms: true,
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts valid registration", () => {
+    const result = signUpSchema.safeParse({
+      name: "John Doe",
+      email: "test@example.com",
+      password: "Password123",
+      confirmPassword: "Password123",
+      acceptTerms: true,
+    });
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+Pattern: Test edge cases and business rules, not all permutations.
+
+**Component Testing:**
+```typescript
+describe("ConsentAwareAnalytics", () => {
+  beforeEach(() => {
+    useCookieConsentOptionalMock.mockReset();
+  });
+
+  it("does not render analytics when consent is not granted", () => {
+    useCookieConsentOptionalMock.mockReturnValue({
+      canLoadAnalytics: false,
+    });
+
+    render(<ConsentAwareAnalytics />);
+
+    expect(screen.queryByTestId("vercel-analytics")).not.toBeInTheDocument();
+  });
+
+  it("renders analytics after consent opt-in", () => {
+    useCookieConsentOptionalMock.mockReturnValue({
+      canLoadAnalytics: true,
+    });
+
+    render(<ConsentAwareAnalytics />);
+
+    expect(screen.getByTestId("vercel-analytics")).toBeInTheDocument();
+  });
+});
+```
+
+Pattern: Mock context, render component, assert DOM output. Tests user-visible behavior.
+
+**Async Testing:**
+All Vitest async patterns work naturally:
+
+```typescript
+it("generates unique IDs", async () => {
+  const id1 = nanoid();
+  const id2 = nanoid();
+  expect(id1).not.toBe(id2);
+});
+```
+
+(Note: above example is synchronous, but async syntax is supported)
+
+**Error/Edge Case Testing:**
+```typescript
+describe("plan lookup behavior", () => {
+  const plans = [
+    { name: "free", price: 0 },
+    { name: "pro", price: 10 },
+    { name: "enterprise", price: 100 },
+  ];
+
+  it("returns undefined for non-existent plan", () => {
+    const result = findPlanByName(plans, "platinum");
+    expect(result).toBeUndefined();
+  });
+
+  it("returns undefined for undefined plan name", () => {
+    const result = findPlanByName(plans, undefined);
+    expect(result).toBeUndefined();
+  });
+});
+```
+
+Test both success and failure paths, null/undefined cases.
+
+## Testing Best Practices
+
+**Do:**
+- Test business rules and policies (permission matrix, validation rules)
+- Test edge cases (empty strings, null, undefined, boundary values)
+- Test what code does, not how it does it
+- Use descriptive test names: "owner can assign any role" not "test assignRole"
+- Keep tests focused and isolated (no test interdependencies)
+- Mock external dependencies, test internal logic
+
+**Don't:**
+- Test implementation details (private functions, specific algorithm)
+- Test CSS classes or DOM structure (unless critical to functionality)
+- Test trivial getters/setters with no logic
+- Import from test files in production code
+- Create interdependent tests (test B depends on test A)
+- Test dependencies' behavior; assume they work
+
+---
+
+*Testing analysis: 2026-02-21*

From c09b9dfa5521e8284ecf81bc3197ac38be2798e3 Mon Sep 17 00:00:00 2001
From: Carlos Ricardo Ziegler <38855507+CarlosZiegler@users.noreply.github.com>
Date: Sat, 21 Feb 2026 19:34:50 +0100
Subject: [PATCH 2/2] feat: add speech-to-text transcription with OpenAI
 Whisper

Add voice input support to AI Chat using dual-mode approach:
- Chrome: Web Speech API (real-time, no backend)
- Firefox/Safari: MediaRecorder + OpenAI Whisper via /api/transcribe endpoint

Also adds dev server configs (.claude/launch.json), removes broken
device-utils test, and documents speech input in README.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/launch.json                           |  29 ++
 apps/start-template/README.md                 |  33 +-
 .../src/lib/__tests__/device-utils.test.ts    |  92 ------
 apps/start-template/src/routeTree.gen.ts      |  21 ++
 .../src/routes/(dashboard)/chat/index.tsx     |  19 ++
 .../src/routes/api/transcribe/index.ts        |  55 ++++
 bun.lock                                      | 306 +++++++++---------
 7 files changed, 309 insertions(+), 246 deletions(-)
 create mode 100644 .claude/launch.json
 delete mode 100644 apps/start-template/src/lib/__tests__/device-utils.test.ts
 create mode 100644 apps/start-template/src/routes/api/transcribe/index.ts

diff --git a/.claude/launch.json b/.claude/launch.json
new file mode 100644
index 0000000..0e8c197
--- /dev/null
+++ b/.claude/launch.json
@@ -0,0 +1,29 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "start-template",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "--cwd", "apps/start-template", "dev"],
+      "port": 3000
+    },
+    {
+      "name": "email-dev",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "--cwd", "apps/start-template", "email:dev"],
+      "port": 5555
+    },
+    {
+      "name": "db-studio",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "--cwd", "apps/start-template", "db:studio"],
+      "port": 4983
+    },
+    {
+      "name": "vitest-ui",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "--cwd", "apps/start-template", "test:ui"],
+      "port": 51204
+    }
+  ]
+}
diff --git a/apps/start-template/README.md b/apps/start-template/README.md
index 11b3ffb..7b9b811 100644
--- a/apps/start-template/README.md
+++ b/apps/start-template/README.md
@@ -56,7 +56,7 @@ flowchart TD
 
 ## Features
 
-- **AI Chat**: Streaming chat interface with AI SDK, multi-provider support
+- **AI Chat**: Streaming chat interface with AI SDK, multi-provider support, voice input (speech-to-text)
 - **Organizations**: Create/edit, slug check, logo; invite/accept; role-based permissions (owner/admin/member)
 - **Security**: 2FA (TOTP), Passkeys (WebAuthn), sessions view, email verification, change password
 - **Profile**: Avatar upload/remove; name/email update
@@ -155,6 +155,37 @@ Role-based access control via Better Auth:
 </PermissionGuard>
 ```
 
+## Speech Input (Voice-to-Text)
+
+The AI Chat includes a speech input button that converts voice to text using a dual-mode approach for cross-browser support.
+
+**How it works:**
+
+| Browser | Mode | Backend Required |
+|---------|------|------------------|
+| Chrome | Web Speech API (real-time) | No |
+| Firefox, Safari | MediaRecorder + OpenAI Whisper | Yes |
+
+- **Chrome**: Uses the native Web Speech API for real-time transcription directly in the browser — no server calls needed.
+- **Firefox/Safari**: Records audio via MediaRecorder, sends the audio blob to `POST /api/transcribe`, which transcribes it using OpenAI Whisper (`whisper-1`) via the AI SDK's `experimental_transcribe()`.
+
+**API Endpoint:**
+
+```
+POST /api/transcribe
+Content-Type: multipart/form-data
+
+Body: FormData with "audio" field (Blob)
+Response: { "text": "transcribed text" }
+```
+
+Requires authentication (uses the same session as the chat). Returns `401` if not authenticated, `400` if no audio file is provided.
+
+**Requirements:**
+- `OPENAI_API_KEY` environment variable must be set (also used by AI Chat)
+
+**Component:** `SpeechInput` from `src/components/ai-elements/speech-input.tsx` — handles mode detection, recording UI, and callback wiring automatically.
+
 ## Storage
 
 Supports any S3-compatible provider. See provider-specific setup:
diff --git a/apps/start-template/src/lib/__tests__/device-utils.test.ts b/apps/start-template/src/lib/__tests__/device-utils.test.ts
deleted file mode 100644
index c385638..0000000
--- a/apps/start-template/src/lib/__tests__/device-utils.test.ts
+++ /dev/null
@@ -1,92 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  type DeviceType,
-  getDeviceIcon,
-  getDeviceIconFromUserAgent,
-  getDeviceInfo,
-  getDeviceType,
-} from "@/lib/device-utils";
-
-describe("getDeviceIcon", () => {
-  it("returns PhoneIcon for mobile", () => {
-    const icon = getDeviceIcon("mobile");
-    expect(icon).toBeDefined();
-  });
-
-  it("returns Tablet for tablet", () => {
-    const icon = getDeviceIcon("tablet");
-    expect(icon).toBeDefined();
-  });
-
-  it("returns Laptop for desktop", () => {
-    const icon = getDeviceIcon("desktop");
-    expect(icon).toBeDefined();
-  });
-});
-
-describe("getDeviceIconFromUserAgent", () => {
-  it("returns PhoneIcon for mobile user agent", () => {
-    const icon = getDeviceIconFromUserAgent(
-      "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)"
-    );
-    expect(icon).toBeDefined();
-  });
-
-  it("returns Laptop for desktop user agent", () => {
-    const icon = getDeviceIconFromUserAgent(
-      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
-    );
-    expect(icon).toBeDefined();
-  });
-
-  it("returns Monitor for undefined user agent", () => {
-    const icon = getDeviceIconFromUserAgent();
-    expect(icon).toBeDefined();
-  });
-});
-
-describe("getDeviceInfo", () => {
-  it("parses user agent correctly", () => {
-    const info = getDeviceInfo(
-      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
-    );
-    expect(info).toContain("macOS");
-  });
-
-  it("returns fallback for undefined user agent", () => {
-    const info = getDeviceInfo();
-    expect(info).toBe("Unknown device");
-  });
-
-  it("returns custom fallback", () => {
-    const info = getDeviceInfo(undefined, "Custom device");
-    expect(info).toBe("Custom device");
-  });
-});
-
-describe("getDeviceType", () => {
-  it("returns mobile for mobile user agent", () => {
-    const type = getDeviceType(
-      "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)"
-    );
-    expect(type).toBe<DeviceType>("mobile");
-  });
-
-  it("returns tablet for tablet user agent", () => {
-    const type = getDeviceType("Mozilla/5.0 (iPad; CPU OS 14_0 like Mac OS X)");
-    expect(type).toBe<DeviceType>("tablet");
-  });
-
-  it("returns desktop for desktop user agent", () => {
-    const type = getDeviceType(
-      "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
-    );
-    expect(type).toBe<DeviceType>("desktop");
-  });
-
-  it("returns desktop for undefined user agent", () => {
-    const type = getDeviceType();
-    expect(type).toBe<DeviceType>("desktop");
-  });
-});
diff --git a/apps/start-template/src/routeTree.gen.ts b/apps/start-template/src/routeTree.gen.ts
index 765dd42..6edbbe8 100644
--- a/apps/start-template/src/routeTree.gen.ts
+++ b/apps/start-template/src/routeTree.gen.ts
@@ -21,6 +21,7 @@ import { Route as authResetPasswordRouteImport } from './routes/(auth)/reset-pas
 import { Route as authMagicLinkRouteImport } from './routes/(auth)/magic-link'
 import { Route as authForgotPasswordRouteImport } from './routes/(auth)/forgot-password'
 import { Route as dashboardSettingsLayoutRouteImport } from './routes/(dashboard)/settings/layout'
+import { Route as ApiTranscribeIndexRouteImport } from './routes/api/transcribe/index'
 import { Route as ApiChatIndexRouteImport } from './routes/api/chat/index'
 import { Route as dashboardSettingsIndexRouteImport } from './routes/(dashboard)/settings/index'
 import { Route as dashboardOverviewIndexRouteImport } from './routes/(dashboard)/overview/index'
@@ -96,6 +97,11 @@ const dashboardSettingsLayoutRoute = dashboardSettingsLayoutRouteImport.update({
   path: '/settings',
   getParentRoute: () => dashboardLayoutRoute,
 } as any)
+const ApiTranscribeIndexRoute = ApiTranscribeIndexRouteImport.update({
+  id: '/api/transcribe/',
+  path: '/api/transcribe/',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const ApiChatIndexRoute = ApiChatIndexRouteImport.update({
   id: '/api/chat/',
   path: '/api/chat/',
@@ -209,6 +215,7 @@ export interface FileRoutesByFullPath {
   '/overview/': typeof dashboardOverviewIndexRoute
   '/settings/': typeof dashboardSettingsIndexRoute
   '/api/chat/': typeof ApiChatIndexRoute
+  '/api/transcribe/': typeof ApiTranscribeIndexRoute
   '/organizations/invitations/': typeof dashboardOrganizationsInvitationsIndexRoute
 }
 export interface FileRoutesByTo {
@@ -236,6 +243,7 @@ export interface FileRoutesByTo {
   '/overview': typeof dashboardOverviewIndexRoute
   '/settings': typeof dashboardSettingsIndexRoute
   '/api/chat': typeof ApiChatIndexRoute
+  '/api/transcribe': typeof ApiTranscribeIndexRoute
   '/organizations/invitations': typeof dashboardOrganizationsInvitationsIndexRoute
 }
 export interface FileRoutesById {
@@ -267,6 +275,7 @@ export interface FileRoutesById {
   '/(dashboard)/overview/': typeof dashboardOverviewIndexRoute
   '/(dashboard)/settings/': typeof dashboardSettingsIndexRoute
   '/api/chat/': typeof ApiChatIndexRoute
+  '/api/transcribe/': typeof ApiTranscribeIndexRoute
   '/(dashboard)/organizations/invitations/': typeof dashboardOrganizationsInvitationsIndexRoute
 }
 export interface FileRouteTypes {
@@ -297,6 +306,7 @@ export interface FileRouteTypes {
     | '/overview/'
     | '/settings/'
     | '/api/chat/'
+    | '/api/transcribe/'
     | '/organizations/invitations/'
   fileRoutesByTo: FileRoutesByTo
   to:
@@ -324,6 +334,7 @@ export interface FileRouteTypes {
     | '/overview'
     | '/settings'
     | '/api/chat'
+    | '/api/transcribe'
     | '/organizations/invitations'
   id:
     | '__root__'
@@ -354,6 +365,7 @@ export interface FileRouteTypes {
     | '/(dashboard)/overview/'
     | '/(dashboard)/settings/'
     | '/api/chat/'
+    | '/api/transcribe/'
     | '/(dashboard)/organizations/invitations/'
   fileRoutesById: FileRoutesById
 }
@@ -369,6 +381,7 @@ export interface RootRouteChildren {
   ApiRpcSplatRoute: typeof ApiRpcSplatRoute
   ApiStorageSplatRoute: typeof ApiStorageSplatRoute
   ApiChatIndexRoute: typeof ApiChatIndexRoute
+  ApiTranscribeIndexRoute: typeof ApiTranscribeIndexRoute
 }
 
 declare module '@tanstack/react-router' {
@@ -457,6 +470,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof dashboardSettingsLayoutRouteImport
       parentRoute: typeof dashboardLayoutRoute
     }
+    '/api/transcribe/': {
+      id: '/api/transcribe/'
+      path: '/api/transcribe'
+      fullPath: '/api/transcribe/'
+      preLoaderRoute: typeof ApiTranscribeIndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/api/chat/': {
       id: '/api/chat/'
       path: '/api/chat'
@@ -651,6 +671,7 @@ const rootRouteChildren: RootRouteChildren = {
   ApiRpcSplatRoute: ApiRpcSplatRoute,
   ApiStorageSplatRoute: ApiStorageSplatRoute,
   ApiChatIndexRoute: ApiChatIndexRoute,
+  ApiTranscribeIndexRoute: ApiTranscribeIndexRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)
diff --git a/apps/start-template/src/routes/(dashboard)/chat/index.tsx b/apps/start-template/src/routes/(dashboard)/chat/index.tsx
index 1d4ff11..32cbac9 100644
--- a/apps/start-template/src/routes/(dashboard)/chat/index.tsx
+++ b/apps/start-template/src/routes/(dashboard)/chat/index.tsx
@@ -229,6 +229,24 @@ function RouteComponent() {
     setText((prev) => (prev ? `${prev} ${transcript}` : transcript));
   }, []);
 
+  const handleAudioRecorded = useCallback(async (audioBlob: Blob) => {
+    const formData = new FormData();
+    formData.append("audio", audioBlob, "recording.webm");
+
+    const response = await fetch("/api/transcribe", {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(error.error || "Transcription failed");
+    }
+
+    const data = await response.json();
+    return data.text as string;
+  }, []);
+
   const handleTextChange = useCallback(
     (event: React.ChangeEvent<HTMLTextAreaElement>) => {
       setText(event.target.value);
@@ -375,6 +393,7 @@ function RouteComponent() {
                 </PromptInputActionMenu>
                 <SpeechInput
                   className="shrink-0"
+                  onAudioRecorded={handleAudioRecorded}
                   onTranscriptionChange={handleTranscriptionChange}
                   size="icon-sm"
                   variant="ghost"
diff --git a/apps/start-template/src/routes/api/transcribe/index.ts b/apps/start-template/src/routes/api/transcribe/index.ts
new file mode 100644
index 0000000..6713cef
--- /dev/null
+++ b/apps/start-template/src/routes/api/transcribe/index.ts
@@ -0,0 +1,55 @@
+import { openai } from "@ai-sdk/openai";
+import { experimental_transcribe as transcribe } from "ai";
+import { createFileRoute } from "@tanstack/react-router";
+
+import { auth } from "@/lib/auth/auth";
+
+export const Route = createFileRoute("/api/transcribe/")({
+  server: {
+    handlers: {
+      POST: async ({ request }: { request: Request }) => {
+        try {
+          const [session, formData] = await Promise.all([
+            auth.api.getSession({ headers: request.headers }),
+            request.formData(),
+          ]);
+
+          if (!session?.user) {
+            return new Response("Unauthorized", { status: 401 });
+          }
+
+          const audioFile = formData.get("audio");
+
+          if (!audioFile || !(audioFile instanceof Blob)) {
+            return new Response(
+              JSON.stringify({ error: "No audio file provided" }),
+              {
+                status: 400,
+                headers: { "Content-Type": "application/json" },
+              },
+            );
+          }
+
+          const audioData = new Uint8Array(await audioFile.arrayBuffer());
+
+          const result = await transcribe({
+            model: openai.transcription("whisper-1"),
+            audio: audioData,
+          });
+
+          return new Response(JSON.stringify({ text: result.text }), {
+            headers: { "Content-Type": "application/json" },
+          });
+        } catch (error: unknown) {
+          console.error("Transcription error:", error);
+          const message =
+            error instanceof Error ? error.message : "Transcription failed";
+          return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: { "Content-Type": "application/json" },
+          });
+        }
+      },
+    },
+  },
+});
diff --git a/bun.lock b/bun.lock
index 46c7c28..44612d5 100644
--- a/bun.lock
+++ b/bun.lock
@@ -14,161 +14,161 @@
       "name": "start-kit",
       "version": "1.0.0",
       "dependencies": {
-        "@ai-sdk/anthropic": "latest",
-        "@ai-sdk/google": "latest",
-        "@ai-sdk/openai": "latest",
-        "@ai-sdk/react": "latest",
-        "@base-ui/react": "latest",
-        "@better-auth/passkey": "latest",
-        "@better-auth/stripe": "latest",
-        "@clack/prompts": "latest",
-        "@dnd-kit/core": "latest",
-        "@dnd-kit/modifiers": "latest",
-        "@dnd-kit/sortable": "latest",
-        "@dnd-kit/utilities": "latest",
-        "@fontsource-variable/inter": "latest",
-        "@hookform/resolvers": "latest",
-        "@json-render/core": "latest",
-        "@json-render/react": "latest",
-        "@orpc/client": "latest",
-        "@orpc/json-schema": "latest",
-        "@orpc/openapi": "latest",
-        "@orpc/react": "latest",
-        "@orpc/server": "latest",
-        "@orpc/tanstack-query": "latest",
-        "@orpc/zod": "latest",
-        "@paralleldrive/cuid2": "latest",
-        "@radix-ui/react-use-controllable-state": "latest",
-        "@react-email/components": "latest",
-        "@react-email/render": "latest",
-        "@remixicon/react": "latest",
-        "@rive-app/react-webgl2": "latest",
-        "@streamdown/cjk": "latest",
-        "@streamdown/code": "latest",
-        "@streamdown/math": "latest",
-        "@streamdown/mermaid": "latest",
-        "@t3-oss/env-core": "latest",
-        "@tabler/icons-react": "latest",
-        "@tanstack/db": "latest",
-        "@tanstack/devtools-vite": "latest",
-        "@tanstack/query-core": "latest",
-        "@tanstack/query-db-collection": "latest",
-        "@tanstack/react-db": "latest",
-        "@tanstack/react-devtools": "latest",
-        "@tanstack/react-pacer": "latest",
-        "@tanstack/react-query": "latest",
-        "@tanstack/react-query-devtools": "latest",
-        "@tanstack/react-router": "latest",
-        "@tanstack/react-router-devtools": "latest",
-        "@tanstack/react-router-ssr-query": "latest",
-        "@tanstack/react-start": "latest",
-        "@tanstack/react-table": "latest",
-        "@tanstack/zod-adapter": "latest",
-        "@upstash/ratelimit": "latest",
-        "@upstash/redis": "latest",
-        "@vercel/analytics": "latest",
-        "@vercel/mcp-adapter": "latest",
-        "@vitejs/devtools": "latest",
-        "@xyflow/react": "latest",
-        "ai": "latest",
-        "ansi-to-react": "latest",
-        "better-auth": "latest",
-        "class-variance-authority": "latest",
-        "clsx": "latest",
-        "cmdk": "latest",
-        "date-fns": "latest",
-        "dotenv": "latest",
-        "drizzle-orm": "latest",
-        "drizzle-zod": "latest",
-        "elysia": "latest",
-        "embla-carousel-autoplay": "latest",
-        "embla-carousel-react": "latest",
-        "flags": "latest",
-        "framer-motion": "latest",
-        "glob": "latest",
-        "i18next": "latest",
-        "i18next-browser-languagedetector": "latest",
-        "i18next-resources-to-backend": "latest",
-        "input-otp": "latest",
-        "jotai": "latest",
-        "lucide-react": "latest",
-        "mcp-handler": "latest",
-        "media-chrome": "latest",
-        "motion": "latest",
-        "nanoid": "latest",
-        "next-themes": "latest",
-        "nitro": "latest",
-        "pg": "latest",
-        "picocolors": "latest",
-        "pino": "latest",
-        "radix-ui": "latest",
-        "react": "latest",
-        "react-day-picker": "latest",
-        "react-dom": "latest",
-        "react-dropzone": "latest",
-        "react-hook-form": "latest",
-        "react-i18next": "latest",
-        "react-jsx-parser": "latest",
-        "react-qr-code": "latest",
-        "react-resizable-panels": "latest",
-        "react-syntax-highlighter": "latest",
-        "recharts": "latest",
-        "resend": "latest",
-        "resumable-stream": "latest",
-        "shiki": "latest",
-        "simple-icons": "latest",
-        "sonner": "latest",
-        "streamdown": "latest",
-        "stripe": "latest",
-        "tokenlens": "latest",
-        "ua-parser-js": "latest",
-        "use-stick-to-bottom": "latest",
-        "uuid": "latest",
-        "vaul": "latest",
-        "vite-plugin-db": "latest",
-        "zod": "latest",
+        "@ai-sdk/anthropic": "^3.0.46",
+        "@ai-sdk/google": "^3.0.30",
+        "@ai-sdk/openai": "^3.0.30",
+        "@ai-sdk/react": "^3.0.99",
+        "@base-ui/react": "^1.2.0",
+        "@better-auth/passkey": "1.4.18",
+        "@better-auth/stripe": "1.4.18",
+        "@clack/prompts": "^1.0.1",
+        "@dnd-kit/core": "6.3.1",
+        "@dnd-kit/modifiers": "9.0.0",
+        "@dnd-kit/sortable": "10.0.0",
+        "@dnd-kit/utilities": "3.2.2",
+        "@fontsource-variable/inter": "^5.2.8",
+        "@hookform/resolvers": "5.2.2",
+        "@json-render/core": "^0.8.0",
+        "@json-render/react": "^0.8.0",
+        "@orpc/client": "1.13.5",
+        "@orpc/json-schema": "1.13.5",
+        "@orpc/openapi": "1.13.5",
+        "@orpc/react": "1.13.5",
+        "@orpc/server": "1.13.5",
+        "@orpc/tanstack-query": "1.13.5",
+        "@orpc/zod": "1.13.5",
+        "@paralleldrive/cuid2": "^3.3.0",
+        "@radix-ui/react-use-controllable-state": "^1.2.2",
+        "@react-email/components": "1.0.8",
+        "@react-email/render": "2.0.4",
+        "@remixicon/react": "4.9.0",
+        "@rive-app/react-webgl2": "^4.27.0",
+        "@streamdown/cjk": "^1.0.2",
+        "@streamdown/code": "^1.0.3",
+        "@streamdown/math": "^1.0.2",
+        "@streamdown/mermaid": "^1.0.2",
+        "@t3-oss/env-core": "0.13.10",
+        "@tabler/icons-react": "3.37.1",
+        "@tanstack/db": "0.5.28",
+        "@tanstack/devtools-vite": "0.5.1",
+        "@tanstack/query-core": "5.90.20",
+        "@tanstack/query-db-collection": "1.0.25",
+        "@tanstack/react-db": "0.1.72",
+        "@tanstack/react-devtools": "^0.9.6",
+        "@tanstack/react-pacer": "^0.20.0",
+        "@tanstack/react-query": "5.90.21",
+        "@tanstack/react-query-devtools": "5.91.3",
+        "@tanstack/react-router": "1.161.3",
+        "@tanstack/react-router-devtools": "1.161.3",
+        "@tanstack/react-router-ssr-query": "1.161.3",
+        "@tanstack/react-start": "1.161.3",
+        "@tanstack/react-table": "8.21.3",
+        "@tanstack/zod-adapter": "1.161.3",
+        "@upstash/ratelimit": "2.0.8",
+        "@upstash/redis": "1.36.2",
+        "@vercel/analytics": "^1.6.1",
+        "@vercel/mcp-adapter": "0.3.2",
+        "@vitejs/devtools": "0.0.0-alpha.32",
+        "@xyflow/react": "^12.10.1",
+        "ai": "^6.0.97",
+        "ansi-to-react": "^6.2.6",
+        "better-auth": "1.4.18",
+        "class-variance-authority": "0.7.1",
+        "clsx": "2.1.1",
+        "cmdk": "^1.1.1",
+        "date-fns": "^4.1.0",
+        "dotenv": "17.3.1",
+        "drizzle-orm": "0.45.1",
+        "drizzle-zod": "0.8.3",
+        "elysia": "^1.4.25",
+        "embla-carousel-autoplay": "8.6.0",
+        "embla-carousel-react": "^8.6.0",
+        "flags": "4.0.3",
+        "framer-motion": "^12.34.3",
+        "glob": "^13.0.6",
+        "i18next": "25.8.13",
+        "i18next-browser-languagedetector": "8.2.1",
+        "i18next-resources-to-backend": "1.2.1",
+        "input-otp": "^1.4.2",
+        "jotai": "2.18.0",
+        "lucide-react": "^0.575.0",
+        "mcp-handler": "1.0.7",
+        "media-chrome": "^4.18.0",
+        "motion": "^12.34.3",
+        "nanoid": "^5.1.6",
+        "next-themes": "^0.4.6",
+        "nitro": "3.0.1-alpha.2",
+        "pg": "8.18.0",
+        "picocolors": "^1.1.1",
+        "pino": "^10.3.1",
+        "radix-ui": "1.4.3",
+        "react": "19.2.4",
+        "react-day-picker": "^9.13.2",
+        "react-dom": "19.2.4",
+        "react-dropzone": "15.0.0",
+        "react-hook-form": "7.71.2",
+        "react-i18next": "16.5.4",
+        "react-jsx-parser": "^2.4.1",
+        "react-qr-code": "2.0.18",
+        "react-resizable-panels": "^4.6.4",
+        "react-syntax-highlighter": "16.1.0",
+        "recharts": "3.7.0",
+        "resend": "6.9.2",
+        "resumable-stream": "^2.2.10",
+        "shiki": "^3.22.0",
+        "simple-icons": "^16.9.0",
+        "sonner": "^2.0.7",
+        "streamdown": "^2.3.0",
+        "stripe": "20.3.1",
+        "tokenlens": "^1.3.1",
+        "ua-parser-js": "2.0.9",
+        "use-stick-to-bottom": "^1.1.3",
+        "uuid": "13.0.0",
+        "vaul": "^1.1.2",
+        "vite-plugin-db": "0.7.0",
+        "zod": "4.3.6",
       },
       "devDependencies": {
-        "@biomejs/biome": "latest",
-        "@rollup/plugin-babel": "latest",
-        "@rollup/plugin-commonjs": "latest",
-        "@rollup/plugin-terser": "latest",
-        "@tailwindcss/postcss": "latest",
-        "@tailwindcss/vite": "latest",
-        "@testing-library/jest-dom": "latest",
-        "@testing-library/react": "latest",
-        "@testing-library/user-event": "latest",
-        "@types/bun": "latest",
-        "@types/node": "latest",
-        "@types/pg": "latest",
-        "@types/react": "latest",
-        "@types/react-dom": "latest",
-        "@types/react-syntax-highlighter": "latest",
-        "@vitejs/plugin-react": "latest",
-        "@vitest/coverage-v8": "latest",
-        "@vitest/ui": "latest",
-        "autoprefixer": "latest",
-        "babel-plugin-react-compiler": "latest",
-        "dotenv-cli": "latest",
-        "drizzle-kit": "latest",
-        "drizzle-query-logger": "latest",
-        "husky": "latest",
-        "jsdom": "latest",
-        "postcss": "latest",
-        "react-email": "latest",
-        "rollup-plugin-polyfill-node": "latest",
-        "rollup-plugin-postcss": "latest",
-        "shadcn": "latest",
-        "tailwind-merge": "latest",
-        "tailwindcss": "latest",
-        "tailwindcss-animate": "latest",
-        "tsx": "latest",
-        "tw-animate-css": "latest",
-        "typescript": "latest",
-        "ultracite": "latest",
-        "vite": "latest",
-        "vite-tsconfig-paths": "latest",
-        "vitest": "latest",
+        "@biomejs/biome": "2.4.4",
+        "@rollup/plugin-babel": "6.1.0",
+        "@rollup/plugin-commonjs": "29.0.0",
+        "@rollup/plugin-terser": "0.4.4",
+        "@tailwindcss/postcss": "4.2.0",
+        "@tailwindcss/vite": "4.2.0",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/bun": "^1.3.9",
+        "@types/node": "25.3.0",
+        "@types/pg": "8.16.0",
+        "@types/react": "19.2.14",
+        "@types/react-dom": "19.2.3",
+        "@types/react-syntax-highlighter": "15.5.13",
+        "@vitejs/plugin-react": "5.1.4",
+        "@vitest/coverage-v8": "^4.0.18",
+        "@vitest/ui": "^4.0.18",
+        "autoprefixer": "10.4.24",
+        "babel-plugin-react-compiler": "1.0.0",
+        "dotenv-cli": "^11.0.0",
+        "drizzle-kit": "0.31.9",
+        "drizzle-query-logger": "^1.1.2",
+        "husky": "9.1.7",
+        "jsdom": "^28.1.0",
+        "postcss": "8.5.6",
+        "react-email": "5.2.8",
+        "rollup-plugin-polyfill-node": "0.13.0",
+        "rollup-plugin-postcss": "4.0.2",
+        "shadcn": "3.8.5",
+        "tailwind-merge": "3.5.0",
+        "tailwindcss": "4.2.0",
+        "tailwindcss-animate": "1.0.7",
+        "tsx": "4.21.0",
+        "tw-animate-css": "1.4.0",
+        "typescript": "5.9.3",
+        "ultracite": "7.2.3",
+        "vite": "7.3.1",
+        "vite-tsconfig-paths": "6.1.1",
+        "vitest": "^4.0.18",
       },
     },
     "packages/cli": {