fauxbase 0.1.1 → 0.4.0

package/README.md

@@ -2,624 +2,298 @@
 
 **Start with fake. Ship with real. Change nothing.**
 
-A frontend data layer that simulates your backend — entities, services, business logic, 13 query operators, auth, role-based access — all running in the browser. When your backend is ready, swap one config line.
+Fauxbase is a frontend data layer that simulates your backend during development, then connects to your real API without changing your components.
 
 ```
-npm install @fauxbase/core
+npm install fauxbase
 ```
 
 ---
 
-## The Problem
-
-Every frontend project does this:
-
-```
-1. Backend not ready       → hardcode mock data in components
-2. Mock data grows         → copy-paste, no structure, spaghetti
-3. Need filtering/search   → hack together Array.filter()
-4. Need pagination         → hack together Array.slice()
-5. Need auth               → fake login with useState
-6. Backend arrives         → REWRITE all data fetching
-7. Partial backend         → half mock, half real, chaos
-8. Migration bugs          → deadline missed
-```
-
-Existing tools don't solve this:
-
-| Tool | What it does | The gap |
-|------|-------------|---------|
-| **MSW** | Intercepts HTTP at network level | You mock the *transport*, not the *data layer*. No query engine, no auth simulation. |
-| **json-server** | Fake REST from a JSON file | No query operators, no auth, no hooks, separate process. |
-| **MirageJS** | In-browser mock server | No typed entities, limited query operators, no auth sim, largely abandoned. |
-| **Zustand/Redux** | State management | Just state — no CRUD contract, no query engine, no migration path. |
-
-**Fauxbase fills the gap**: a structured, type-safe data layer with query capabilities and auth that runs locally during development and transparently switches to your real backend.
-
----
-
-## Architecture
-
-```mermaid
-graph TB
-    subgraph "Your React App"
-        C[Components]
-    end
-
-    subgraph "Fauxbase"
-        S[Service Layer<br/>hooks, validation, CRUD]
-        QE[QueryEngine<br/>13 operators, sort, paginate]
-
-        subgraph "Driver Abstraction"
-            LD[LocalDriver<br/>memory / localStorage / indexedDB]
-            HD[HttpDriver<br/>fetch + preset]
-        end
-    end
-
-    subgraph "Storage"
-        MEM[(Memory)]
-        LS[(localStorage)]
-        API[(REST API)]
-    end
-
-    C -->|fb.product.list, create, ...| S
-    S --> LD
-    S --> HD
-    LD --> QE
-    LD --> MEM
-    LD --> LS
-    HD -->|preset translates| API
-
-    style C fill:#61dafb,color:#000
-    style S fill:#f5c842,color:#000
-    style QE fill:#f5c842,color:#000
-    style LD fill:#4caf50,color:#fff
-    style HD fill:#2196f3,color:#fff
-```
-
-**Key insight**: Components always talk to the Service layer. The Service delegates to a Driver. The Driver is swappable. Your components never know whether they're hitting localStorage or a REST API.
-
----
+## 15-Second Example
 
-## Quick Start
+Define your data:
 
-### 1. Define your entities
-
-```typescript
-import { Entity, field, relation, computed } from '@fauxbase/core';
-
-export class Product extends Entity {
-  @field({ required: true })          name!: string;
-  @field({ required: true, min: 0 })  price!: number;
-  @field({ default: 0 })              stock!: number;
-  @field({ default: true })           isActive!: boolean;
-
-  @relation('category')               categoryId!: string;
-
-  @computed(p => p.stock > 0 && p.isActive)
-  available!: boolean;
+```ts
+class Product extends Entity {
+  @field({ required: true })  name!: string;
+  @field({ min: 0 })          price!: number;
+  @field({ default: 0 })      stock!: number;
 }
 ```
 
-The `Entity` base class gives you these fields automatically:
+Use it:
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `id` | `string` | Auto-generated UUID |
-| `createdAt` | `string` | ISO timestamp, set on create |
-| `updatedAt` | `string` | ISO timestamp, updated on every change |
-| `createdById` | `string?` | User who created (when auth active) |
-| `createdByName` | `string?` | Display name of creator |
-| `updatedById` | `string?` | User who last updated |
-| `updatedByName` | `string?` | Display name of updater |
-| `deletedAt` | `string?` | Soft delete timestamp (null = not deleted) |
-| `version` | `number` | Auto-incremented on every update |
+```ts
+const fb = createClient({
+  services: { product: ProductService },
+  seeds: [seed(Product, [
+    { name: 'Hair Clay', price: 185000, stock: 50 },
+    { name: 'Beard Oil', price: 125000, stock: 30 },
+  ])],
+});
 
-### 2. Define services with business logic
+// Filter, sort, paginate — all work locally
+const result = await fb.product.list({
+  filter: { price__gte: 100000 },
+  sort: { field: 'price', direction: 'desc' },
+  page: 1, size: 20,
+});
+```
 
-```typescript
-import { Service, beforeCreate, beforeUpdate } from '@fauxbase/core';
-import { Product } from './entities/product';
+That's it.
 
-export class ProductService extends Service<Product> {
-  entity = Product;
-  endpoint = '/products';
+- Works locally with fake data
+- Switch to real backend later
+- No component changes
 
-  @beforeCreate()
-  ensureUniqueName(data: Partial<Product>, existing: Product[]) {
-    if (existing.some(p => p.name === data.name)) {
-      throw new ConflictError(`Product "${data.name}" already exists`);
-    }
-  }
+---
 
-  @beforeUpdate()
-  preventNegativeStock(_id: string, data: Partial<Product>) {
-    if (data.stock !== undefined && data.stock < 0) {
-      throw new ValidationError('Stock cannot be negative');
-    }
-  }
+## How It Works
 
-  // Custom methods — available on both drivers
-  async getByCategory(categoryId: string, page = 1) {
-    return this.list({
-      filter: { categoryId, isActive: true },
-      sort: { field: 'name', direction: 'asc' },
-      page, size: 20,
-    });
-  }
-}
 ```
-
-Services give you:
-
-| Method | Description |
-|--------|-------------|
-| `list(query)` | Filtered, sorted, paginated list |
-| `get(id)` | Get by ID |
-| `create(data)` | Create with hooks + validation |
-| `update(id, data)` | Update with hooks |
-| `delete(id)` | Soft delete |
-| `count(filter?)` | Count matching records |
-| `bulk.create([])` | Batch insert |
-| `bulk.update([])` | Batch update |
-| `bulk.delete([])` | Batch delete |
-
-### 3. Define seed data
-
-```typescript
-import { seed } from '@fauxbase/core';
-import { Product } from './entities/product';
-
-export const productSeed = seed(Product, [
-  { name: 'Hair Clay', price: 185000, categoryId: 'seed:category:0', stock: 50 },
-  { name: 'Beard Oil', price: 125000, categoryId: 'seed:category:1', stock: 30 },
-]);
+  Development                     Production
+
+  Your App                        Your App
+     ↓                               ↓
+  Fauxbase                        Fauxbase
+     ↓                               ↓
+  Local Driver                    HTTP Driver
+  (memory / localStorage)            ↓
+                                  Your Backend API
 ```
 
-### 4. Create the client
-
-```typescript
-import { createClient } from '@fauxbase/core';
+Components always talk to Fauxbase. Fauxbase talks to a driver. The driver is swappable. Your components never know whether they're hitting localStorage or a REST API.
 
-export const fb = createClient({
-  driver: import.meta.env.VITE_API_URL
-    ? { type: 'http', baseUrl: import.meta.env.VITE_API_URL, preset: 'lightwind' }
-    : { type: 'local', persist: 'localStorage' },
+---
 
-  services: {
-    product: ProductService,
-    category: CategoryService,
-    order: OrderService,
-  },
+## The Problem
 
-  seeds: [categorySeed, productSeed],
-});
+Every frontend project does this:
 
-// Type-safe:
-// fb.product.list(...)       → ProductService
-// fb.category.get(...)       → CategoryService
-// fb.product.getByCategory() → custom method, fully typed
 ```
-
-### 5. Use it
-
-```typescript
-// List with filtering
-const result = await fb.product.list({
-  filter: { price__gte: 100000, name__contains: 'hair' },
-  sort: { field: 'price', direction: 'desc' },
-  page: 1,
-  size: 20,
-});
-
-// Create
-const { data } = await fb.product.create({
-  name: 'New Product',
-  price: 150000,
-  categoryId: 'seed:category:0',
-});
-
-// Update
-await fb.product.update(data.id, { stock: 100 });
-
-// Delete (soft)
-await fb.product.delete(data.id);
+Step 1: Backend not ready         → hardcode mock data
+Step 2: Mock data grows           → copy-paste everywhere
+Step 3: Need filtering            → hack together Array.filter()
+Step 4: Need pagination           → hack together Array.slice()
+Step 5: Need auth                 → fake login with useState
+Step 6: Backend arrives           → rewrite everything
 ```
 
----
-
-## Query Engine — 13 Operators
-
-Every filter operator works identically on the local driver (in-memory) and the HTTP driver (translated to URL params).
-
-```typescript
-const result = await fb.product.list({
-  filter: {
-    price__gte: 100000,                  // price >= 100000
-    name__contains: 'pomade',            // case-insensitive substring
-    categoryId__in: ['cat-1', 'cat-2'],  // value in list
-    stock__between: [10, 100],           // 10 <= stock <= 100
-    isActive: true,                      // exact match (eq implied)
-    description__isnull: false,          // is not null
-  },
-  sort: { field: 'price', direction: 'desc' },
-  page: 1,
-  size: 20,
-});
-```
+Existing tools don't solve this:
 
-### All operators
-
-| Operator | Syntax | Description | Example |
-|----------|--------|-------------|---------|
-| `eq` | `field` or `field__eq` | Exact match | `{ isActive: true }` |
-| `ne` | `field__ne` | Not equal | `{ status__ne: 'deleted' }` |
-| `gt` | `field__gt` | Greater than | `{ price__gt: 100 }` |
-| `gte` | `field__gte` | Greater than or equal | `{ price__gte: 100 }` |
-| `lt` | `field__lt` | Less than | `{ stock__lt: 10 }` |
-| `lte` | `field__lte` | Less than or equal | `{ stock__lte: 100 }` |
-| `like` | `field__like` | Case-insensitive substring | `{ name__like: 'hair' }` |
-| `contains` | `field__contains` | Same as `like` | `{ name__contains: 'hair' }` |
-| `startswith` | `field__startswith` | Case-insensitive prefix | `{ name__startswith: 'ha' }` |
-| `endswith` | `field__endswith` | Case-insensitive suffix | `{ email__endswith: '@gmail.com' }` |
-| `between` | `field__between` | Inclusive range | `{ price__between: [100, 500] }` |
-| `in` | `field__in` | Value in list | `{ status__in: ['active', 'pending'] }` |
-| `isnull` | `field__isnull` | Null/undefined check | `{ deletedAt__isnull: true }` |
-
-### How queries flow
-
-```mermaid
-flowchart LR
-    subgraph "Input"
-        Q["{ filter: { price__gte: 100 },<br/>sort: { field: 'name', direction: 'asc' },<br/>page: 1, size: 20 }"]
-    end
-
-    subgraph "QueryEngine"
-        F[Filter<br/>13 operators]
-        S[Sort<br/>asc/desc, null-safe]
-        P[Paginate<br/>slice + meta]
-    end
-
-    subgraph "Output"
-        R["{ items: [...],<br/>meta: { page, size,<br/>totalItems, totalPages } }"]
-    end
-
-    Q --> F --> S --> P --> R
-```
+| Tool | What it does | The gap |
+|------|-------------|---------|
+| **MSW** | Intercepts HTTP | No query engine, no auth, mocks transport not data |
+| **json-server** | Fake REST from JSON | No query operators, no hooks, separate process |
+| **MirageJS** | In-browser server | Limited operators, no typed entities, largely abandoned |
+| **Zustand/Redux** | State management | No CRUD contract, no query engine, no migration path |
 
-Soft-deleted records (where `deletedAt` is set) are automatically excluded before any filtering.
+**Fauxbase removes the rewrite.**
 
 ---
 
-## Drivers
+## The Key Idea
 
-### Local Driver (development)
+Fauxbase runs your backend contract in the browser.
 
-Runs entirely in the browser. No server needed.
+Entities define your data model. Services define business logic. A query engine handles filtering, sorting, and pagination.
 
-```typescript
-driver: { type: 'local', persist: 'memory' }        // volatile, fastest
-driver: { type: 'local', persist: 'localStorage' }   // persists across refresh
-```
+During development, it runs locally. When your backend is ready, it forwards the same calls to your API.
 
-| Store | Persists? | Limit | Best for |
-|-------|-----------|-------|----------|
-| `memory` | No | RAM | Unit tests, throwaway demos |
-| `localStorage` | Yes | ~5MB | Default, small-medium datasets |
+---
 
-### HTTP Driver (production)
+## Core Features
 
-Translates Fauxbase calls to fetch requests. Uses **presets** to speak your backend's language.
+- Entity system with decorators (`@field`, `@relation`, `@computed`)
+- Service layer with lifecycle hooks (`@beforeCreate`, `@afterUpdate`, ...)
+- 13 query operators (`eq`, `gte`, `contains`, `between`, `in`, ...)
+- Seed data with deterministic IDs
+- Local driver (memory / localStorage)
+- HTTP driver for real backends
+- Hybrid mode for gradual migration
+- Backend presets (Spring Boot, NestJS, Laravel, Django, Rails, ...)
+- Zero runtime dependencies (~8KB gzipped)
 
-```typescript
-driver: {
-  type: 'http',
-  baseUrl: 'https://api.example.com',
-  preset: 'lightwind',
-}
-```
+---
 
-### Hybrid Driver (gradual migration)
+## Hybrid Mode
 
-When your backend is partially ready — migrate one service at a time:
+This is the killer feature. Migrate one service at a time:
 
-```typescript
+```ts
 const fb = createClient({
-  driver: { type: 'local' },  // default for all
+  driver: { type: 'local' },
 
   overrides: {
-    product: { driver: { type: 'http', baseUrl: 'https://api.example.com', preset: 'lightwind' } },
-    // category, order → still local
+    product: { driver: { type: 'http', baseUrl: '/api', preset: 'spring-boot' } },
   },
 });
 ```
 
-### Driver flow
+Products use the real API. Everything else stays local. Migrate at your own pace.
 
-```mermaid
-flowchart TB
-    C[Component<br/>fb.product.list]
+---
 
-    subgraph "Local Driver"
-        LS[(Storage<br/>memory/localStorage)]
-        QE1[QueryEngine<br/>in-memory processing]
-    end
+## AI Prototypes → Production
 
-    subgraph "HTTP Driver"
-        PR[Preset<br/>serialize/parse]
-        FE[fetch<br/>GET /products?...]
-        API[(REST API)]
-    end
+Many AI-generated prototypes hardcode arrays:
 
-    C -->|dev| LS --> QE1 --> R1[Normalized Response]
-    C -->|prod| PR --> FE --> API --> PR --> R2[Normalized Response]
+```ts
+const products = [
+  { name: 'Hair Clay', price: 185000 },
+  { name: 'Beard Oil', price: 125000 },
+];
 ```
 
-Components always get the same normalized response shape, regardless of driver.
+When the prototype becomes real, engineers must rewrite the data layer.
 
----
+Fauxbase lets prototypes start with a real data contract:
 
-## Backend Presets
-
-A preset tells the HTTP driver how to talk to your backend — how to serialize queries, parse responses, and handle auth.
-
-### Built-in presets
+```
+Claude / Cursor prototype
+         ↓
+Fauxbase local driver (works immediately)
+         ↓
+Real backend later (no rewrite)
+```
 
-| Preset | Framework | Filter Style | Auth |
-|--------|-----------|-------------|------|
-| `lightwind` | Lightwind (Quarkus) | `?price__gte=100` | `/auth/login` |
-| `spring-boot` | Spring Boot | `?price.gte=100` | `/api/auth/signin` |
-| `nestjs` | NestJS | `?filter.price.$gte=100` | `/auth/login` |
-| `laravel` | Laravel | `?filter[price_gte]=100` | `/api/login` |
-| `django` | Django REST Framework | `?price__gte=100` | `/api/token/` |
-| `express` | Express.js | `?price__gte=100` | `/auth/login` |
-| `fastapi` | FastAPI | `?price__gte=100` | `/api/auth/token` |
-| `rails` | Ruby on Rails | `?q[price_gteq]=100` | `/api/login` |
-| `go-gin` | Go (Gin) | `?price__gte=100` | `/api/auth/login` |
+---
 
-### Custom presets
+## Query Engine — 13 Operators
 
-```typescript
-import { definePreset } from '@fauxbase/core';
+Every operator works identically on local and HTTP drivers.
 
-const fb = createClient({
-  driver: {
-    type: 'http',
-    baseUrl: 'https://api.myapp.com',
-    preset: definePreset({
-      name: 'my-backend',
-      response: {
-        single: (raw) => ({ data: raw.result }),
-        list: (raw) => ({
-          items: raw.results,
-          meta: {
-            page: raw.page,
-            size: raw.per_page,
-            totalItems: raw.total,
-            totalPages: raw.pages,
-          },
-        }),
-      },
-      query: {
-        filterStyle: 'django',
-        pageParam: 'page',
-        sizeParam: 'per_page',
-      },
-      auth: {
-        loginUrl: '/api/v1/login',
-        tokenField: 'access_token',
-      },
-    }),
+```ts
+const result = await fb.product.list({
+  filter: {
+    price__gte: 100000,
+    name__contains: 'pomade',
+    categoryId__in: ['cat-1', 'cat-2'],
+    stock__between: [10, 100],
+    isActive: true,
   },
+  sort: { field: 'price', direction: 'desc' },
+  page: 1,
+  size: 20,
 });
 ```
 
-### How presets work
-
-```mermaid
-sequenceDiagram
-    participant Component
-    participant Service
-    participant HttpDriver
-    participant Preset
-    participant Backend
-
-    Component->>Service: fb.product.list({ filter: { price__gte: 100 } })
-    Service->>HttpDriver: list("product", query)
-    HttpDriver->>Preset: serialize query
-    Preset-->>HttpDriver: GET /products?price__gte=100&page=1&size=20
-    HttpDriver->>Backend: fetch(url, { headers: { Authorization } })
-    Backend-->>HttpDriver: { code: 200, data: { items, meta } }
-    HttpDriver->>Preset: parse response
-    Preset-->>HttpDriver: { items: [...], meta: { page, size, totalItems, totalPages } }
-    HttpDriver-->>Service: normalized PagedResponse
-    Service-->>Component: same shape as local driver
-```
+| Operator | Syntax | Example |
+|----------|--------|---------|
+| `eq` | `field` or `field__eq` | `{ isActive: true }` |
+| `ne` | `field__ne` | `{ status__ne: 'deleted' }` |
+| `gt` | `field__gt` | `{ price__gt: 100 }` |
+| `gte` | `field__gte` | `{ price__gte: 100 }` |
+| `lt` | `field__lt` | `{ stock__lt: 10 }` |
+| `lte` | `field__lte` | `{ stock__lte: 100 }` |
+| `like` | `field__like` | `{ name__like: 'hair' }` |
+| `contains` | `field__contains` | `{ name__contains: 'hair' }` |
+| `startswith` | `field__startswith` | `{ name__startswith: 'ha' }` |
+| `endswith` | `field__endswith` | `{ email__endswith: '@gmail.com' }` |
+| `between` | `field__between` | `{ price__between: [100, 500] }` |
+| `in` | `field__in` | `{ status__in: ['active', 'pending'] }` |
+| `isnull` | `field__isnull` | `{ deletedAt__isnull: true }` |
 
 ---
 
-## Seeding Strategy
-
-Seed data and runtime data are tracked separately.
-
-```mermaid
-stateDiagram-v2
-    [*] --> FirstLoad : App starts
-    FirstLoad --> HasData : Seeds applied
+## Services & Hooks
 
-    HasData --> HasData : Reloads (seeds unchanged)
-    note right of HasData : Seeds SKIPPED, data preserved
-
-    HasData --> SeedChanged : Reloads (seeds modified)
-    SeedChanged --> HasData : Upsert seed records
+```ts
+class ProductService extends Service<Product> {
+  entity = Product;
+  endpoint = '/products';
 
-    HasData --> ResetSeeds : Reset Seeds
-    ResetSeeds --> HasData : Wipe + re-seed
+  @beforeCreate()
+  ensureUniqueName(data: Partial<Product>, existing: Product[]) {
+    if (existing.some(p => p.name === data.name)) {
+      throw new ConflictError(`Product "${data.name}" already exists`);
+    }
+  }
 
-    HasData --> RefreshSeeds : Refresh Seeds
-    RefreshSeeds --> HasData : Re-seed only
+  async getByCategory(categoryId: string) {
+    return this.list({
+      filter: { categoryId, isActive: true },
+      sort: { field: 'name', direction: 'asc' },
+    });
+  }
+}
 ```
 
-**How it works:**
-
-- Seed records get deterministic IDs: `seed:product:0`, `seed:product:1`, ...
-- Runtime records (created during development) get normal UUIDs: `a3f1b2c4-...`
-- Fauxbase tracks a `_seedVersion` hash — if your seed definitions change, only seed records are re-applied
-- Runtime records are never touched during re-seeding
-- On HTTP driver, seeding is disabled entirely — the backend owns the data
+Every service gets: `list`, `get`, `create`, `update`, `delete`, `count`, `bulk.create`, `bulk.update`, `bulk.delete`.
 
 ---
 
-## Response Format
+## Seeding
 
-All operations return a normalized format. Components always see the same shape regardless of driver.
+Seed data has deterministic IDs. Runtime data has UUIDs. They never collide.
 
-```typescript
-// Single item (get, create, update)
-interface ApiResponse<T> {
-  data: T;
-}
-
-// List (list)
-interface PagedResponse<T> {
-  items: T[];
-  meta: {
-    page: number;
-    size: number;
-    totalItems: number;
-    totalPages: number;
-  };
-}
-
-// Errors (thrown as exceptions)
-class NotFoundError    // code: 'NOT_FOUND'
-class ConflictError    // code: 'CONFLICT'
-class ValidationError  // code: 'VALIDATION', details: { field: message }
-class ForbiddenError   // code: 'FORBIDDEN'
+```ts
+const productSeed = seed(Product, [
+  { name: 'Hair Clay', price: 185000, stock: 50 },   // → seed:product:0
+  { name: 'Beard Oil', price: 125000, stock: 30 },   // → seed:product:1
+]);
 ```
 
----
-
-## Decorators
+- Seeds auto-apply on first load
+- Fauxbase tracks a version hash — if seeds change, only seed records are re-applied
+- Runtime records are never touched during re-seeding
+- On HTTP driver, seeding is disabled — the backend owns the data
 
-### Entity decorators
+---
 
-| Decorator | Purpose | Example |
-|-----------|---------|---------|
-| `@field(options?)` | Mark entity field with validation | `@field({ required: true, min: 0 })` |
-| `@relation(entity)` | Foreign key relation | `@relation('category')` |
-| `@computed(fn)` | Derived value, recalculated on access | `@computed(p => p.stock > 0)` |
+## Backend Presets
 
-### Service hook decorators
+Works with any REST backend. Presets tell the HTTP driver how to serialize queries and parse responses.
 
-| Decorator | Signature | Purpose |
-|-----------|-----------|---------|
-| `@beforeCreate()` | `(data, existingItems) => void` | Validate/mutate before create |
-| `@beforeUpdate()` | `(id, data) => void` | Validate/mutate before update |
-| `@afterCreate()` | `(entity) => void` | Side effects after create |
-| `@afterUpdate()` | `(entity) => void` | Side effects after update |
+| Preset | Framework | Filter Style |
+|--------|-----------|-------------|
+| `lightwind` | Lightwind (Quarkus) | `?price__gte=100` |
+| `spring-boot` | Spring Boot | `?price.gte=100` |
+| `nestjs` | NestJS | `?filter.price.$gte=100` |
+| `laravel` | Laravel | `?filter[price_gte]=100` |
+| `django` | Django REST Framework | `?price__gte=100` |
+| `express` | Express.js | `?price__gte=100` |
+| `fastapi` | FastAPI | `?price__gte=100` |
+| `rails` | Ruby on Rails | `?q[price_gteq]=100` |
+| `go-gin` | Go (Gin) | `?price__gte=100` |
 
-Hooks can throw errors to abort operations:
-
-```typescript
-@beforeCreate()
-ensureUnique(data: Partial<Product>, existing: Product[]) {
-  if (existing.some(p => p.name === data.name)) {
-    throw new ConflictError('Name must be unique');
-  }
-}
-```
+Custom presets supported via `definePreset()`.
 
 ---
 
-## The Migration Timeline
-
-```mermaid
-gantt
-    title Frontend Development with Fauxbase
-    dateFormat  YYYY-MM-DD
-    axisFormat  Week %W
-
-    section Setup
-    Install Fauxbase + define entities/services    :a1, 2024-01-01, 1d
-    Define seed data                               :a2, after a1, 1d
-
-    section Build (no backend)
-    Build full UI with local driver                :b1, after a2, 28d
-    CRUD, filtering, pagination, auth — all work   :b2, after a2, 28d
-
-    section Migrate (backend arrives)
-    Products API ready → hybrid mode               :c1, after b1, 7d
-    All APIs ready → full HTTP driver              :c2, after c1, 7d
-    Remove local driver config                     :c3, after c2, 1d
-```
+## Migration Timeline
 
 ```
-Week 1:    npm install @fauxbase/core
-           Define entities, services, seeds
-           Build UI with local driver — everything works
+Week 1     Install Fauxbase, define entities/services/seeds.
+           Build UI with local driver. Everything works.
 
-Week 2-4:  Building features at full speed
-           No blocking on backend, no mock data spaghetti
+Week 2-4   Build features at full speed.
+           No blocking on backend. No mock data spaghetti.
 
-Week 5:    "Products API is ready"
-           → switch products to HTTP driver (hybrid mode)
-           → zero component changes
+Week 5     "Products API is ready"
+           → Switch products to HTTP driver (hybrid mode)
+           → Zero component changes
 
-Week 6:    "All APIs ready"
-           → set VITE_API_URL globally
-           → done
+Week 6     "All APIs ready"
+           → Set VITE_API_URL → done
 ```
 
 ---
 
-## Project Structure
-
-Recommended structure in your app:
-
-```
-src/
-├── fauxbase/
-│   ├── entities/
-│   │   ├── product.ts        ← class Product extends Entity
-│   │   ├── category.ts
-│   │   └── user.ts
-│   ├── services/
-│   │   ├── product.ts        ← class ProductService extends Service<Product>
-│   │   ├── category.ts
-│   │   └── user.ts
-│   ├── seeds/
-│   │   ├── product.ts        ← seed(Product, [...])
-│   │   └── category.ts
-│   └── index.ts              ← createClient({ ... })
-├── components/
-│   └── ProductList.tsx        ← fb.product.list({ ... })
-└── main.tsx
-```
-
----
+## Who This Is For
 
-## Technical Details
-
-| Aspect | Detail |
-|--------|--------|
-| **Package** | `@fauxbase/core` (~8KB gzipped) |
-| **Runtime deps** | Zero |
-| **TypeScript** | First-class, full type inference |
-| **Decorators** | `experimentalDecorators` (legacy TS decorators) |
-| **Query operators** | 13: eq, ne, gt, gte, lt, lte, like, contains, startswith, endswith, between, in, isnull |
-| **Storage** | memory, localStorage (indexedDB planned) |
-| **Auth** | Planned (Phase 2) |
-| **Presets** | lightwind, spring-boot, nestjs, laravel, express, django, fastapi, rails, go-gin, custom |
-| **Build** | tsup (ESM + CJS + DTS) |
-| **Tests** | vitest, 140+ tests, 97%+ coverage |
+- Frontend teams waiting for backend APIs
+- Solo devs building full-stack apps
+- Prototypers using AI coding tools
+- Teams building UI before backend is ready
 
 ---
 
 ## Roadmap
 
 - [x] **v0.1** — Core: Entity, Service, QueryEngine, LocalDriver, Seeds
-- [ ] **v0.2** — React hooks (`useList`, `useGet`, `useMutation`, `useAuth`) + Auth simulation
+- [ ] **v0.2** — React hooks (`useList`, `useGet`, `useMutation`) + Auth simulation
 - [ ] **v0.3** — HTTP Driver + Backend Presets + DevTools
 - [ ] **v0.4** — IndexedDB, CLI (`npx fauxbase init`), Vue/Svelte adapters