@kardoe/quickback 0.5.13 → 0.5.15

package/dist/index.js

@@ -10,7 +10,7 @@
  */
 import pc from "picocolors";
 // Version injected at build time by scripts/inject-version.ts
-const CLI_VERSION = "0.5.13";
+const CLI_VERSION = "0.5.15";
 function getPackageVersion() {
     return CLI_VERSION;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kardoe/quickback",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "description": "CLI for Quickback - one-shot backend generator",
   "author": "Paul Stenhouse",
   "license": "MIT",

package/src/skill/SKILL.md

@@ -4,26 +4,40 @@ description: Quickback API engine documentation - use when working with Quickbac
 allowed-tools: Read, Grep, Glob
 ---
 
-# Quickback: Backend Compiler for Secure APIs
+# Quickback
 
-Quickback transforms declarative TypeScript definitions into secure, production-ready APIs. You define your database schema and security rules in a single file using Drizzle ORM — Quickback compiles them into a deployable backend with authentication, role-based permissions, tenant isolation, and field-level security.
+Quickback is two things:
+
+1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
+2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
 
 The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
 
-## How It Works
+## Accessing Documentation
+
+The fastest way to look up detailed docs is via the CLI:
+
+```bash
+quickback docs                    # List all available topics
+quickback docs <topic>            # Show docs for a specific topic
+quickback docs firewall           # Example: firewall docs
+quickback docs cms/record-layouts # Example: CMS record layouts
+```
+
+Full online docs: https://docs.quickback.dev
+
+---
 
-1. **Define** — Schema + security rules in TypeScript using `defineTable()`
-2. **Compile** — Quickback generates API routes, middleware, migrations, and RLS policies
-3. **Deploy** — Standard tooling to Cloudflare Workers, Supabase, or Neon
+# PART 1: THE COMPILER
 
-## Architecture
+The compiler takes your TypeScript definitions and generates API routes, middleware, migrations, typed SDKs, OpenAPI specs, and AI tool definitions.
 
 ```
 ┌─────────────────────────────────────────────────────────┐
 │  YOU DEFINE (in TypeScript)                             │
 │  • Drizzle schema (your data models)                    │
 │  • Security layers (Firewall, Access, Guards, Masking)  │
-│  • Views (column-level projections)                     │
+│  • Views, Validation, Layouts                           │
 │  • Actions (your business operations)                   │
 ├─────────────────────────────────────────────────────────┤
 │  QUICKBACK COMPILES TO                                  │
@@ -35,24 +49,7 @@ The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your o
 └─────────────────────────────────────────────────────────┘
 ```
 
-## Four Security Layers
-
-Every API request passes through four layers in order:
-
-```
-Request → Firewall → Access → Guards → Database → Masking → Response
-```
-
-| Layer | Purpose | Failure |
-|-------|---------|---------|
-| **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
-| **Access** | Role-based CRUD permissions (deny by default) | 403 |
-| **Guards** | Field modification rules (protected/immutable fields) | 400 |
-| **Masking** | PII redaction for unauthorized viewers | — |
-
----
-
-# Project Structure
+## Project Structure
 
 ```
 my-app/
@@ -86,13 +83,9 @@ export default defineConfig({
 
 ## Compile Output and State Artifacts
 
-When a project has a `quickback/` folder and compiles runtime output to project root:
-
-- Runtime code stays in `build.outputDir` (for example `src/`, `wrangler.toml`, `package.json`).
-- Drizzle migration/state artifacts are written to `quickback/drizzle/...`.
-- Security contract report artifacts are written to `quickback/reports/...`.
-
-Treat `quickback/drizzle` as the canonical migration state location for repeated compiles.
+- Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
+- Drizzle migration/state artifacts are written to `quickback/drizzle/...`
+- Security contract reports are written to `quickback/reports/...`
 
 ## Automatic Audit Fields
 
@@ -104,13 +97,13 @@ Quickback automatically injects these fields into every table:
 
 ---
 
-# Feature Definitions (Combined Mode)
+## Feature Definitions (Combined Mode)
 
 Features live in `quickback/features/{name}/` with one file per table using `defineTable()`.
 
 **Important**: Legacy mode (separate schema.ts + resource.ts) is no longer supported.
 
-## Example: todos.ts
+### Example: todos.ts
 
 ```typescript
 import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
@@ -127,10 +120,9 @@ export const todos = sqliteTable("todos", {
 
 export default defineTable(todos, {
   firewall: {
-    organization: {},    // Auto-detects 'organizationId' column
-    owner: {},           // Auto-detects 'userId' column
+    organization: {},
+    owner: {},
   },
-
   crud: {
     list: { access: { roles: ["member", "admin"] } },
     get: { access: { roles: ["member", "admin"] } },
@@ -138,24 +130,29 @@ export default defineTable(todos, {
     update: { access: { roles: ["admin"] } },
     delete: { access: { roles: ["admin"] }, mode: "soft" },
   },
-
   guards: {
     createable: ["title", "description", "completed"],
     updatable: ["title", "description", "completed"],
   },
-
   masking: {
     userId: { type: "redact", show: { roles: ["admin"] } },
   },
+  layouts: {
+    default: {
+      sections: [
+        { label: "Details", columns: 2, fields: ["title", "completed"] },
+        { label: "Audit", collapsed: true, fields: ["userId"] },
+      ],
+    },
+  },
 });
 ```
 
-## Internal/Junction Tables (No API)
+### Internal/Junction Tables (No API)
 
 Tables without a `defineTable()` default export get no API routes:
 
 ```typescript
-// No default export = no API routes generated
 export const roomAmenities = sqliteTable('room_amenities', {
   roomId: text('room_id').notNull(),
   amenityId: text('amenity_id').notNull(),
@@ -164,9 +161,22 @@ export const roomAmenities = sqliteTable('room_amenities', {
 
 ---
 
-# Security Pillars
+## Four Security Layers
+
+Every API request passes through four layers in order:
+
+```
+Request → Firewall → Access → Guards → Database → Masking → Response
+```
+
+| Layer | Purpose | Failure |
+|-------|---------|---------|
+| **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
+| **Access** | Role-based CRUD permissions (deny by default) | 403 |
+| **Guards** | Field modification rules (protected/immutable fields) | 400 |
+| **Masking** | PII redaction for unauthorized viewers | — |
 
-## 1. Firewall — Data Isolation
+### 1. Firewall — Data Isolation
 
 Compiles WHERE clauses to isolate data by ownership. Auto-detects column names.
 
@@ -180,32 +190,25 @@ firewall: {
 }
 ```
 
-### Auto-Detection
-
-Quickback finds columns by convention:
+Auto-detection:
 - `organization` → looks for `organizationId` or `organization_id`
 - `owner` → looks for `userId` or `user_id`
 - `team` → looks for `teamId` or `team_id`
 
-### Column Overrides
+Column overrides:
 
 ```typescript
 firewall: {
   organization: {
-    column: 'tenant_id',        // Instead of 'organizationId'
-    source: 'ctx.tenant.id',    // Instead of 'ctx.activeOrgId'
+    column: 'tenant_id',
+    source: 'ctx.tenant.id',
   },
 }
 ```
 
-### Owner Modes
-
-| Mode | Behavior |
-|------|----------|
-| (default) | Strict — only own records |
-| `optional` | Own records + records with NULL owner (admin pattern) |
+Owner modes: default = strict (only own records), `optional` = own + NULL owner (admin pattern).
 
-## 2. Access — Permission Checks
+### 2. Access — Permission Checks
 
 Role-based and record-based access control. Deny by default.
 
@@ -226,30 +229,11 @@ crud: {
 }
 ```
 
-### Record Conditions
-
-| Operator | Example |
-|----------|---------|
-| `equals` | `{ status: { equals: 'active' } }` |
-| `notEquals` | `{ status: { notEquals: 'archived' } }` |
-| `in` | `{ status: { in: ['active', 'pending'] } }` |
-| `notIn` | `{ status: { notIn: ['deleted'] } }` |
-| `greaterThan` | `{ amount: { greaterThan: 0 } }` |
-| `lessThan` | `{ amount: { lessThan: 10000 } }` |
+Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
 
-### Context Variables
+Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
 
-| Variable | Type | Description |
-|----------|------|-------------|
-| `$ctx.userId` | string | Current user's ID |
-| `$ctx.activeOrgId` | string | Active organization ID |
-| `$ctx.activeTeamId` | string \| null | Active team ID |
-| `$ctx.roles` | string[] | User's roles in active org |
-| `$ctx.isAnonymous` | boolean | Anonymous user flag |
-
-## 3. Guards — Field Protection
-
-Controls which fields can be modified.
+### 3. Guards — Field Protection
 
 ```typescript
 guards: {
@@ -260,130 +244,84 @@ guards: {
 }
 ```
 
-**Compile-time validation**:
-- Field can't be in both `createable` and `protected`
-- Field can't be in both `updatable` and `immutable`
-- All referenced fields must exist in the schema
-
-**System-managed fields** (always protected):
-- `createdAt`, `createdBy` — Set on INSERT
-- `modifiedAt`, `modifiedBy` — Set on INSERT/UPDATE
-- `deletedAt`, `deletedBy` — Set on soft DELETE
+System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
 
-### PUT / Upsert
+PUT/Upsert requires both `generateId: false` and `guards: false`.
 
-PUT is only available when BOTH conditions are met:
-- `generateId: false` in database config
-- `guards: false` (disables field protection)
-
-```typescript
-export default defineTable(external_orders, {
-  guards: false,
-  crud: {
-    put: { access: { roles: ['sync-service'] } },
-    get: {},
-    list: {},
-  },
-});
-```
-
-## 4. Masking — PII Redaction
+### 4. Masking — PII Redaction
 
 ```typescript
 masking: {
-  ssn: {
-    type: 'ssn',                          // *****6789
-    show: { roles: ['admin', 'hr'] },
-  },
-  email: {
-    type: 'email',                        // p***@e******.com
-    show: { roles: ['admin'], or: 'owner' },
-  },
+  ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
+  email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
 }
 ```
 
-### Mask Types
-
-| Type | Output |
-|------|--------|
-| `email` | `p***@e******.com` |
-| `phone` | `******4567` |
-| `ssn` | `*****6789` |
-| `creditCard` | `************1234` |
-| `name` | `J*** D**` |
-| `redact` | `[REDACTED]` |
-| `custom` | Your function |
+Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
 
-### Auto-Detection
-
-The compiler warns if sensitive columns aren't explicitly configured:
-
-| Column Pattern | Default Mask |
-|---------------|-------------|
-| `email` | `email` |
-| `phone`, `mobile`, `fax` | `phone` |
-| `ssn`, `socialsecurity` | `ssn` |
-| `creditcard`, `cc` | `creditCard` |
-| `password`, `secret`, `token` | `redact` |
+Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
 
 ---
 
-# Views — Column-Level Security
+## Views — Column-Level Security
 
-Views are named projections that control which fields are visible based on role.
+Named projections that control which fields are visible based on role.
 
 ```typescript
-export default defineTable(customers, {
-  // ... firewall, guards, etc.
-
-  views: {
-    summary: {
-      fields: ['id', 'name', 'email'],
-      access: { roles: ['member', 'admin'] },
-    },
-    full: {
-      fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
-      access: { roles: ['admin'] },
-    },
+views: {
+  summary: {
+    fields: ['id', 'name', 'email'],
+    access: { roles: ['member', 'admin'] },
   },
-});
+  full: {
+    fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
+    access: { roles: ['admin'] },
+  },
+}
 ```
 
-**Generated endpoints**:
-- `GET /api/v1/customers/views/summary` — returns only id, name, email
-- `GET /api/v1/customers/views/full` — returns all fields (admin only)
+Generated endpoints: `GET /api/v1/{resource}/views/{viewName}`
+
+---
 
-Views support the same query parameters as list (filtering, sorting, pagination). Masking still applies to returned fields.
+## Validation
+
+```typescript
+validation: {
+  name: { minLength: 1, maxLength: 100 },
+  capacity: { min: 1, max: 1000 },
+  roomType: { enum: ['meeting', 'conference', 'breakout'] },
+  email: { email: true },
+  code: { pattern: '^[A-Z]{3}$' },
+}
+```
 
 ---
 
-# Validation
+## CMS Record Layouts
 
-Field-level validation rules compiled into the API:
+Control how fields are grouped on the CMS record detail page.
 
 ```typescript
-export default defineTable(rooms, {
-  // ... other config
-
-  validation: {
-    name: { minLength: 1, maxLength: 100 },
-    capacity: { min: 1, max: 1000 },
-    roomType: { enum: ['meeting', 'conference', 'breakout'] },
-    email: { email: true },
-    website: { url: true },
-    code: { pattern: '^[A-Z]{3}$' },
+layouts: {
+  default: {
+    sections: [
+      { label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
+      { label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
+    ],
   },
-});
+}
 ```
 
+Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
+
 ---
 
-# Actions — Custom Business Logic
+## Actions — Custom Business Logic
 
-Actions are custom API endpoints for business logic beyond CRUD. Defined in a separate `actions.ts` file using `defineActions()`.
+Defined in a separate `actions.ts` file using `defineActions()`.
 
 ```typescript
-// quickback/features/todos/actions.ts
 import { todos } from './todos';
 import { defineActions } from '@quickback/compiler';
 import { z } from 'zod';
@@ -391,73 +329,33 @@ import { z } from 'zod';
 export default defineActions(todos, {
   complete: {
     description: "Mark todo as complete",
-    input: z.object({
-      completedAt: z.string().datetime().optional(),
-    }),
-    guard: {
-      roles: ["member", "admin"],
-      record: { completed: { equals: false } },
-    },
+    input: z.object({ completedAt: z.string().datetime().optional() }),
+    guard: { roles: ["member", "admin"], record: { completed: { equals: false } } },
     execute: async ({ db, record, ctx, input }) => {
-      // Inline handler
       await db.update(todos).set({ completed: true }).where(eq(todos.id, record.id));
       return { success: true };
     },
     sideEffects: "sync",
   },
-
   archive: {
     description: "Archive a todo",
     input: z.object({}),
     guard: { roles: ["admin"] },
-    handler: "./handlers/archive",  // OR: external file handler
+    handler: "./handlers/archive",
   },
 });
 ```
 
-**Generated Route**: `POST /api/v1/todos/:id/complete`
-
-### Record-based vs Standalone Actions
-
-**Record-based** (default) — operates on a specific record via `:id`:
-```typescript
-approve: {
-  description: "Approve an invoice",
-  input: z.object({ notes: z.string().optional() }),
-  guard: { roles: ["admin"] },
-  handler: "./handlers/approve",
-}
-// → POST /api/v1/invoices/:id/approve
-```
-
-**Standalone** — custom endpoint not tied to a record:
-```typescript
-chat: {
-  standalone: true,
-  path: "/chat",
-  method: "POST",
-  responseType: "stream",
-  input: z.object({ message: z.string() }),
-  guard: { roles: ["member"] },
-  handler: "./handlers/chat",
-}
-// → POST /api/v1/todos/chat
-```
-
-### Action Options
+**Record-based** (default): `POST /api/v1/{resource}/:id/{action}`
+**Standalone**: `standalone: true`, custom `path` and `method`
 
-| Option | Values | Description |
-|--------|--------|-------------|
-| `standalone` | `true` | Not tied to a record |
-| `method` | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | HTTP method (default: POST) |
-| `responseType` | `json`, `stream`, `file` | Response format |
-| `sideEffects` | `sync`, `async`, `fire-and-forget` | Execution hint |
+Action options: `standalone`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget)
 
 ---
 
-# API Reference
+## API Reference
 
-## CRUD Operations
+### CRUD Operations
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
@@ -468,276 +366,266 @@ chat: {
 | `DELETE` | `/api/v1/{resource}/:id` | Delete record |
 | `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
 
-## Batch Operations
+### Batch Operations
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `POST` | `/api/v1/{resource}/batch` | Batch create |
-| `PATCH` | `/api/v1/{resource}/batch` | Batch update |
-| `DELETE` | `/api/v1/{resource}/batch` | Batch delete |
-| `PUT` | `/api/v1/{resource}/batch` | Batch upsert (if enabled) |
-
-```json
-// Request
-{ "records": [{ "title": "A" }, { "title": "B" }], "options": { "atomic": false } }
-
-// Response
-{ "success": [/* ... */], "errors": [/* ... */], "meta": { "total": 2, "succeeded": 2, "failed": 0 } }
-```
-
-## Query Parameters
+`POST|PATCH|DELETE|PUT /api/v1/{resource}/batch` with `{ "records": [...], "options": { "atomic": false } }`
 
-### Pagination
+### Query Parameters
 
-| Param | Default | Max |
-|-------|---------|-----|
-| `limit` | 50 | 100 |
-| `offset` | 0 | — |
+| Feature | Syntax |
+|---------|--------|
+| Pagination | `?limit=50&offset=0` (max 100) |
+| Filter | `?status=active`, `?amount.gt=100`, `?status.in=draft,pending` |
+| Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
+| Fields | `?fields=id,name,status` |
+| Total count | `?total=true` |
+| Search | `?search=conference` (OR'd LIKE across text columns) |
 
-### Filtering Operators
+Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
 
-| Operator | Example | SQL |
-|----------|---------|-----|
-| (none) | `?status=active` | `status = 'active'` |
-| `.gt` | `?amount.gt=100` | `amount > 100` |
-| `.gte` | `?amount.gte=100` | `amount >= 100` |
-| `.lt` | `?amount.lt=1000` | `amount < 1000` |
-| `.lte` | `?amount.lte=1000` | `amount <= 1000` |
-| `.ne` | `?status.ne=cancelled` | `status != 'cancelled'` |
-| `.like` | `?title.like=urgent` | `title LIKE '%urgent%'` |
-| `.in` | `?status.in=draft,pending` | `status IN ('draft','pending')` |
+### Response Format
 
-### Sorting (Multi-Sort)
-
-```
-?sort=status,-createdAt         # Multi-sort: status asc, createdAt desc
-?sort=-createdAt                # Single field descending
-?sort=createdAt&order=desc      # Legacy format (still supported)
+```json
+{
+  "data": [{ "id": "...", "title": "Todo 1" }],
+  "pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
+}
 ```
 
-No prefix = ascending, `-` prefix = descending. When commas or `-` detected, `order` param is ignored.
+### Error Responses
 
-### Field Selection
+| Status | Layer | Meaning |
+|--------|-------|---------|
+| `401` | Auth | Invalid/expired session |
+| `403` | Access | Insufficient permissions |
+| `404` | Firewall | Record not found or outside scope |
+| `400` | Guards | Invalid field modification |
 
-```
-?fields=id,name,status          # Return only these columns (LIST + GET routes)
-```
+---
 
-Invalid field names silently ignored. Falls back to all columns if none valid. Views define their own fields — `?fields` doesn't apply to view routes. Masking still applies to selected fields.
+## Database Dialects
 
-### Total Count
+| Stack | Import | Table Function |
+|-------|--------|----------------|
+| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
+| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
+| MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
 
-```
-?total=true                     # Include pagination.total (LIST + VIEW routes)
-```
+---
 
-Opt-in extra `COUNT(*)` query. Returns total matching records across all pages.
+# PART 2: THE QUICKBACK STACK
 
-### Search
+The Quickback Stack is a production-ready backend platform built entirely on Cloudflare's edge infrastructure. It's a Supabase alternative where everything runs on your own Cloudflare account — your data, your infrastructure, global edge performance.
 
 ```
-?search=conference              # Full-text search across text columns (LIST + VIEW routes)
+┌─────────────────────────────────────────────────────────┐
+│  QUICKBACK STACK ON CLOUDFLARE                          │
+│                                                         │
+│  Workers     — API runtime (Hono)                       │
+│  D1          — SQLite database at the edge              │
+│  R2          — S3-compatible file storage                │
+│  KV          — Distributed key-value store              │
+│  Durable Objects — Realtime WebSockets                  │
+│  Queues      — Background job processing                │
+│  Workers AI  — Embeddings & vector search               │
+│  Better Auth — Authentication & organizations           │
+└─────────────────────────────────────────────────────────┘
 ```
 
-OR'd LIKE across all `text()` schema columns (system columns excluded). Combine with filters: `?search=urgent&status=active`.
+## Authentication (Better Auth)
 
-## Response Format
+Built on Better Auth with multi-tenant organization support.
 
-```json
-{
-  "data": [{ "id": "...", "title": "Todo 1" }],
-  "pagination": {
-    "limit": 10,
-    "offset": 0,
-    "count": 2,
-    "total": 42
-  }
+- Email/password, magic links, passkeys, email OTP
+- Three org roles: `owner`, `admin`, `member`
+- Session storage in KV namespace
+- All auth routes at `/auth/v1/*`
+- Extensible via Better Auth plugins
+
+```typescript
+// Config
+providers: {
+  auth: defineAuth("better-auth"),
 }
 ```
 
-`count` = records on this page. `total` = total matching records (only when `?total=true`).
+Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
 
----
+## Database (D1)
+
+SQLite at the edge with zero configuration. Multi-database pattern for independent scaling:
 
-# Webhooks
+| Binding | Purpose |
+|---------|---------|
+| `DB` | Application data (features) |
+| `AUTH_DB` | Auth sessions & users |
+| `FILES_DB` | File metadata |
+| `WEBHOOKS_DB` | Webhook tracking |
 
-## Configuration
+- Drizzle ORM for type-safe queries
+- Auto-generated migrations on compile
+- Application-layer security (firewall, access, guards, masking)
+- Local dev with `.wrangler/state/`
+- Neon Postgres available as alternative
 
 ```typescript
-// quickback.config.ts
 providers: {
   database: defineDatabase("cloudflare-d1", {
     splitDatabases: true,
-    webhooksBinding: "WEBHOOKS_DB",
   }),
 }
 ```
 
-## Inbound Webhooks (Receiving)
+Docs: `quickback docs stack/database/d1` | https://docs.quickback.dev/stack/database/d1
 
-```typescript
-import { onWebhookEvent } from './lib/webhooks';
+## File Storage (R2)
 
-onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
-  const { data, env } = ctx;
-  await createSubscription({ ... });
-});
-```
+S3-compatible object storage with built-in access control.
 
-## Outbound Webhooks (Sending)
+- Two-worker architecture: API worker (upload/manage) + Files worker (serve)
+- Bucket-scoped access policies (public, organization, user)
+- File metadata tracked in `FILES_DB`
+- Soft deletes with org-level tenant isolation
+- API at `/storage/v1/*`
 
-```typescript
-import { emitWebhookEvent } from './lib/webhooks';
+Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
 
-await emitWebhookEvent(
-  'user.created',
-  { id: user.id, email: user.email },
-  { organizationId: orgId },
-  env
-);
-```
+## KV Storage
 
-## Available Events
+Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
 
-| Event | Description |
-|-------|-------------|
-| `user.created/updated/deleted` | User lifecycle |
-| `subscription.created/updated/cancelled/renewed` | Subscription lifecycle |
-| `organization.created/updated/deleted` | Organization lifecycle |
-| `organization.member_added/removed` | Membership changes |
-| `file.uploaded/deleted` | File storage |
+- Use cases: sessions, caching, rate limiting, feature flags
+- Eventually consistent (60 second propagation)
+- TTL/expiration support
 
-**Wildcards**: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
+Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
 
----
+## Realtime (Durable Objects)
 
-# CLI Commands
+WebSocket connections for live updates via organization-scoped Durable Objects.
 
-## Core Commands
+- CRUD event broadcasting (insert, update, delete)
+- Custom broadcasts and event namespaces
+- Role-based filtering and per-role field masking
+- Session token or API key authentication
+- Type-safe with `defineRealtime()` for custom events
+- Endpoint: `/realtime/v1/websocket`
 
-| Command | Description |
-|---------|-------------|
-| `quickback create <template> <name>` | Create project from template |
-| `quickback compile` | Compile definitions to output |
-| `quickback login` | Authenticate for Pro templates |
-| `quickback logout` | Clear stored credentials |
-| `quickback whoami` | Show current auth status |
+Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
 
-## Available Templates
+## Queues (Background Processing)
 
-| Template | Stack | Status |
-|----------|-------|--------|
-| `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
-| `bun` | Bun + SQLite + Better Auth | Free |
-| `turso` | Turso/LibSQL + Better Auth | Pro |
+Cloudflare Queues for reliable async job processing.
 
-## Claude Code Integration
+| Queue | Purpose |
+|-------|---------|
+| `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
+| `WEBHOOKS_QUEUE` | Webhook delivery |
+| Custom queues | Your background jobs |
 
-| Command | Description |
-|---------|-------------|
-| `quickback claude install` | Interactive install of Claude Code skill |
-| `quickback claude install --global` | Install globally |
-| `quickback claude install --local` | Install for current project |
-| `quickback claude update` | Update to latest skill version |
-| `quickback claude remove` | Remove the skill |
-| `quickback claude status` | Show install status |
+- Custom handlers via `defineQueue()` in `services/queues/`
+- Auto-retry up to 3 times, max batch 10, 30s timeout
+- Chaining between queues
 
----
+Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
 
-# Development Workflow
+## Vector & Embeddings (Workers AI)
 
-```bash
-# 1. Create project
-quickback create cloudflare my-app
+Auto-generated embeddings for similarity search and classification.
 
-# 2. Define features in quickback/features/
+- Table-level config via `embeddings` in `defineTable()`
+- Service-level config via `defineEmbedding()`
+- Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
+- Async processing via `EMBEDDINGS_QUEUE`
+- Vector storage in D1 + optional Vectorize index
+- API: `/api/v1/embeddings`
 
-# 3. Compile
-quickback compile
+Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
 
-# 4. Run
-cd dist
-npm install
-npm run db:generate
-npm run dev
-```
-
----
+## Webhooks
 
-# Deployment Targets
+### Inbound (Receiving)
 
-## Cloudflare Stack (Full Edge)
-
-Hono API on Workers, D1 database, Better Auth, R2 file storage, KV, Queues, Durable Objects for realtime.
+Receive events from Stripe, Paddle, GitHub, etc. at `POST /webhooks/v1/inbound/:provider`
 
 ```typescript
-defineConfig({
-  providers: {
-    runtime: defineRuntime("cloudflare"),
-    database: defineDatabase("cloudflare-d1"),
-    auth: defineAuth("better-auth"),
-  },
+import { onWebhookEvent } from './lib/webhooks';
+
+onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
+  const { data, env } = ctx;
+  await createSubscription({ ... });
 });
 ```
 
-## Supabase (RLS Policies)
+### Outbound (Sending)
 
-Compiles Quickback definitions into Row Level Security policies for Postgres-level security.
+Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
 
 ```typescript
-defineConfig({
-  providers: {
-    runtime: defineRuntime("supabase"),
-    database: defineDatabase("supabase"),
-    auth: defineAuth("supabase"),
-  },
-});
+import { emitWebhookEvent } from './lib/webhooks';
+
+await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
 ```
 
-## Neon (Serverless Postgres)
+Event patterns: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
+Endpoint management: `/webhooks/v1/endpoints`
 
-Serverless Postgres with compiled RLS policies and branching support.
+Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
 
 ---
 
-# Error Responses
+# CLI Commands
 
-| Status | Layer | Meaning |
-|--------|-------|---------|
-| `401` | Auth | Invalid/expired session |
-| `403` | Access | Insufficient permissions |
-| `404` | Firewall | Record not found or outside scope |
-| `400` | Guards | Invalid field modification |
-| `429` | Rate limit | Too many requests |
+| Command | Description |
+|---------|-------------|
+| `quickback create <template> <name>` | Create project from template |
+| `quickback compile` | Compile definitions to output |
+| `quickback docs [topic]` | Browse built-in documentation |
+| `quickback login` | Authenticate for Pro templates |
+| `quickback logout` | Clear stored credentials |
+| `quickback whoami` | Show current auth status |
+| `quickback claude install` | Install Claude Code skill |
+| `quickback claude update` | Update to latest skill version |
 
----
+## Available Templates
 
-# Database Dialects
+| Template | Stack | Status |
+|----------|-------|--------|
+| `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
+| `bun` | Bun + SQLite + Better Auth | Free |
+| `turso` | Turso/LibSQL + Better Auth | Pro |
 
-Detect from `quickback.config.ts` and use the correct imports:
+## Development Workflow
 
-| Stack | Import | Table Function |
-|-------|--------|----------------|
-| Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
-| Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
-| MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
+```bash
+quickback create cloudflare my-app   # 1. Create project
+# Define features in quickback/features/
+quickback compile                     # 2. Compile
+cd dist && npm install && npm run dev # 3. Run
+```
 
 ---
 
-# Documentation
-
-Full documentation at https://docs.quickback.dev
-
-- [Quick Start](https://docs.quickback.dev/definitions/quick-start)
-- [Concepts](https://docs.quickback.dev/definitions/concepts)
-- [Database Schema](https://docs.quickback.dev/definitions/database-schema)
-- [CRUD Endpoints](https://docs.quickback.dev/definitions/crud-endpoints)
-- [Views](https://docs.quickback.dev/definitions/views)
-- [Actions](https://docs.quickback.dev/definitions/actions)
-- [Firewall](https://docs.quickback.dev/definitions/firewall)
-- [Access](https://docs.quickback.dev/definitions/access)
-- [Guards](https://docs.quickback.dev/definitions/guards)
-- [Masking](https://docs.quickback.dev/definitions/masking)
-- [CLI Reference](https://docs.quickback.dev/compiler/cli)
-- [Cloudflare Stack](https://docs.quickback.dev/stack/cloudflare)
-- [Quick Reference](https://docs.quickback.dev/stack/reference)
+# Online Documentation
+
+- [Getting Started](https://docs.quickback.dev/compiler/getting-started)
+- [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
+- [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
+- [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
+- [Access](https://docs.quickback.dev/compiler/definitions/access)
+- [Guards](https://docs.quickback.dev/compiler/definitions/guards)
+- [Masking](https://docs.quickback.dev/compiler/definitions/masking)
+- [Views](https://docs.quickback.dev/compiler/definitions/views)
+- [Actions](https://docs.quickback.dev/compiler/definitions/actions)
+- [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
+- [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
+- [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
+- [Stack Overview](https://docs.quickback.dev/stack)
+- [D1 Database](https://docs.quickback.dev/stack/database/d1)
+- [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
+- [Realtime](https://docs.quickback.dev/stack/realtime)
+- [Queues](https://docs.quickback.dev/stack/queues)
+- [Embeddings](https://docs.quickback.dev/stack/vector)
+- [Webhooks](https://docs.quickback.dev/stack/webhooks)
+- [CMS Overview](https://docs.quickback.dev/cms)
+- [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)

package/src/skill/agents/quickback-specialist/AGENT.md

@@ -19,6 +19,7 @@ You deeply understand:
 - **Actions**: Custom endpoints using `defineActions()` with Zod schemas
 - **Views**: Column-level security with named projections
 - **Validation**: Field-level validation rules
+- **Layouts**: CMS record page field grouping with sections, columns, and collapsed state
 
 ## When Invoked
 
@@ -193,10 +194,24 @@ Before finishing, verify:
 - [ ] Masking for any PII fields
 - [ ] Views for different visibility levels (if needed)
 - [ ] Validation rules for constrained fields (if needed)
+- [ ] Layouts for CMS record page field grouping (if needed)
 - [ ] No audit fields in schema (auto-injected)
 - [ ] Using `defineTable()` combined mode (not separate schema.ts + resource.ts)
 - [ ] Actions use `defineActions()` with Zod schemas (not JSON schema)
 
+## Accessing Documentation
+
+When you need to look up Quickback docs, use the CLI — it bundles all docs offline:
+
+```bash
+quickback docs                    # List all available topics
+quickback docs <topic>            # Show docs for a specific topic
+quickback docs firewall           # Example: firewall docs
+quickback docs cms/record-layouts # Example: CMS record layouts
+```
+
+Full online docs: https://docs.quickback.dev
+
 ## Response Style
 
 - Be direct and practical