chore(web): improve docs

Author: AmanVarshney01

apps/web/content/docs/bts-config.mdx

@@ -50,5 +50,5 @@ Notes:
 - Values mirror what you selected during project creation
 - The file may be updated when you run `add` (e.g., addons or webDeploy)
 
-See also: [`add` command](/docs/cli/add)
+See also: [`add` command](/docs/cli#add)
 

apps/web/content/docs/cli/add.mdx

@@ -0,0 +1,219 @@
+---
+title: Compatibility Rules
+description: Understanding compatibility rules and restrictions between different CLI options
+---
+
+## Overview
+
+The CLI validates option combinations to ensure generated projects work correctly. Here are the key compatibility rules and restrictions.
+
+## Database & ORM Compatibility
+
+### Required Combinations
+
+| Database | Compatible ORMs | Notes |
+|----------|----------------|-------|
+| `sqlite` | `drizzle`, `prisma` | Lightweight, file-based database |
+| `postgres` | `drizzle`, `prisma` | Advanced relational database |
+| `mysql` | `drizzle`, `prisma` | Traditional relational database |
+| `mongodb` | `mongoose`, `prisma` | Document database, requires specific ORMs |
+| `none` | `none` | No database setup |
+
+### Restrictions
+
+- **MongoDB + Drizzle**: ❌ Not supported - Drizzle doesn't support MongoDB
+- **Database without ORM**: ❌ Not supported - Database requires an ORM for code generation
+- **ORM without Database**: ❌ Not supported - ORM requires a database target
+
+```bash
+# ❌ Invalid - MongoDB with Drizzle
+create-better-t-stack --database mongodb --orm drizzle
+
+# ✅ Valid - MongoDB with Mongoose
+create-better-t-stack --database mongodb --orm mongoose
+```
+
+## Backend & Runtime Compatibility
+
+### Cloudflare Workers Restrictions
+
+Cloudflare Workers has specific compatibility requirements:
+
+| Component | Requirement | Reason |
+|-----------|-------------|--------|
+| Backend | Must be `hono` | Only Hono supports Workers runtime |
+| ORM | Must be `drizzle` or `none` | Workers doesn't support Prisma/Mongoose |
+| Database | Cannot be `mongodb` | MongoDB requires Prisma/Mongoose |
+| Database Setup | Cannot be `docker` | Workers is serverless, no Docker support |
+
+```bash
+# ❌ Invalid - Workers with Express
+create-better-t-stack --runtime workers --backend express
+
+# ✅ Valid - Workers with Hono
+create-better-t-stack --runtime workers --backend hono --database sqlite --orm drizzle --db-setup d1
+```
+
+### Backend Presets
+
+#### Convex Backend
+When using `--backend convex`, the following options are automatically set:
+
+- `--auth false` (Convex handles auth)
+- `--database none` (Convex provides database)
+- `--orm none` (Convex provides data layer)
+- `--api none` (Convex provides API)
+- `--runtime none` (Convex manages runtime)
+- `--db-setup none` (Convex manages hosting)
+- `--examples todo` (Todo example works with Convex)
+
+#### No Backend
+When using `--backend none`, the following options are automatically set:
+
+- `--auth false` (No backend for auth)
+- `--database none` (No backend for database)
+- `--orm none` (No database)
+- `--api none` (No backend for API)
+- `--runtime none` (No backend to run)
+- `--db-setup none` (No database to host)
+- `--examples none` (Examples require backend)
+
+## Frontend & API Compatibility
+
+### API Framework Support
+
+| Frontend | tRPC Support | oRPC Support | Notes |
+|----------|-------------|-------------|-------|
+| `tanstack-router` | ✅ | ✅ | Full support |
+| `react-router` | ✅ | ✅ | Full support |
+| `tanstack-start` | ✅ | ✅ | Full support |
+| `next` | ✅ | ✅ | Full support |
+| `nuxt` | ❌ | ✅ | tRPC not supported |
+| `svelte` | ❌ | ✅ | tRPC not supported |
+| `solid` | ❌ | ✅ | tRPC not supported |
+| Native frameworks | ✅ | ✅ | Full support |
+
+```bash
+# ❌ Invalid - Nuxt with tRPC
+create-better-t-stack --frontend nuxt --api trpc
+
+# ✅ Valid - Nuxt with oRPC
+create-better-t-stack --frontend nuxt --api orpc
+```
+
+### Frontend Restrictions
+
+- **Multiple Web Frontends**: ❌ Only one web framework allowed
+- **Multiple Native Frontends**: ❌ Only one native framework allowed  
+- **Web + Native**: ✅ One web and one native framework allowed
+
+```bash
+# ❌ Invalid - Multiple web frontends
+create-better-t-stack --frontend next tanstack-router
+
+# ✅ Valid - Web + native
+create-better-t-stack --frontend next native-nativewind
+```
+
+## Database Setup Compatibility
+
+### Provider Requirements
+
+| Setup Provider | Required Database | Notes |
+|---------------|------------------|-------|
+| `turso` | `sqlite` | Distributed SQLite |
+| `d1` | `sqlite` | Cloudflare D1 (requires Workers runtime) |
+| `neon` | `postgres` | Serverless PostgreSQL |
+| `supabase` | `postgres` | PostgreSQL with additional features |
+| `prisma-postgres` | `postgres` | Managed PostgreSQL via Prisma |
+| `mongodb-atlas` | `mongodb` | Managed MongoDB |
+| `docker` | `postgres`, `mysql`, `mongodb` | Not compatible with `sqlite` or Workers |
+
+### Special Cases
+
+#### Cloudflare D1
+- Requires `--database sqlite`
+- Requires `--runtime workers`
+- Requires `--backend hono`
+
+#### Docker Setup
+- Cannot be used with `sqlite` (file-based database)
+- Cannot be used with `workers` runtime (serverless environment)
+
+## Addon Compatibility
+
+### PWA Support
+- Requires web frontend
+- Compatible frontends: `tanstack-router`, `react-router`, `next`, `solid`
+- Not compatible with native-only projects
+
+### Tauri (Desktop Apps)
+- Requires web frontend
+- Compatible frontends: `tanstack-router`, `react-router`, `nuxt`, `svelte`, `solid`
+- Cannot be combined with native frameworks
+
+### Web Deployment
+- `--web-deploy workers` requires a web frontend
+- Cannot be used with native-only projects
+
+## Authentication Requirements
+
+Authentication requires:
+- A backend framework (cannot be `none`)
+- A database (cannot be `none`)
+- An ORM (cannot be `none`)
+
+```bash
+# ❌ Invalid - Auth without database
+create-better-t-stack --auth --database none
+
+# ✅ Valid - Auth with full stack
+create-better-t-stack --auth --database postgres --orm drizzle --backend hono
+```
+
+## Example Compatibility
+
+### Todo Example
+- Requires a database when backend is present (except Convex)
+- Cannot be used with `--backend none` and `--database none`
+
+### AI Example  
+- Not compatible with `--backend elysia`
+- Not compatible with `--frontend solid`
+
+## Common Error Messages
+
+### "Mongoose ORM requires MongoDB database"
+```bash
+# Fix by using MongoDB
+create-better-t-stack --database mongodb --orm mongoose
+```
+
+### "Cloudflare Workers runtime is only supported with Hono backend"
+```bash
+# Fix by using Hono
+create-better-t-stack --runtime workers --backend hono
+```
+
+### "Cannot select multiple web frameworks"
+```bash
+# Fix by choosing one web framework
+create-better-t-stack --frontend tanstack-router
+```
+
+### "Authentication requires a database"
+```bash
+# Fix by adding database
+create-better-t-stack --auth --database postgres --orm drizzle
+```
+
+## Validation Strategy
+
+The CLI validates compatibility in this order:
+
+1. **Basic validation**: Required parameters, valid enum values
+2. **Combination validation**: Database + ORM, Backend + Runtime compatibility
+3. **Feature validation**: Auth requirements, addon compatibility
+4. **Example validation**: Example + stack compatibility
+
+Understanding these rules helps you create valid configurations and troubleshoot issues when the CLI reports compatibility errors.