opacacms 0.1.20 → 0.1.21

package/README.md

@@ -1,1063 +1,227 @@
-# OpacaCMS
+# 🚀 OpacaCMS
 
-> An experimental, runtime-agnostic headless CMS built with TypeScript. Define your schema, access control, and business logic directly in code — no visual builders, no lock-in.
+> **The Headless CMS that doesn't get in your way.** Define your schema, access control, and logic directly in TypeScript. No visual builders, no proprietary formats, no lock-in. Just code. 💻
 
-OpacaCMS runs natively on **Node.js, Bun, Cloudflare Workers, and Next.js** using [Hono](https://hono.dev) for routing. The schema you define becomes both your database tables and your REST API, automatically.
+OpacaCMS is a runtime-agnostic powerhouse that runs anywhere: **Node.js, Bun, Cloudflare Workers, and Next.js**. Powered by [Hono](https://hono.dev), it turns your schema into database tables and a high-performance REST API instantly. ⚡️
 
 ---
 
-## Table of Contents
-
-- [Getting Started](#getting-started)
-- [Project Structure](#project-structure)
-- [Configuration](#configuration)
-- [Collections](#collections)
-- [Field Types](#field-types)
-- [Globals](#globals)
-- [Access Control](#access-control)
-- [Hooks](#hooks)
-- [Authentication](#authentication)
-- [Database Adapters](#database-adapters)
-- [Migrations](#migrations)
-- [Storage (File Uploads)](#storage-file-uploads)
-- [Internationalization (i18n)](#internationalization-i18n)
-- [Custom Admin Components](#custom-admin-components)
-- [The Client SDK](#the-client-sdk)
-- [Runtime Integrations](#runtime-integrations)
-- [CLI Reference](#cli-reference)
-- [Production Build](#production-build)
+## 🧭 Quick Menu
+
+- [✨ Getting Started](#-getting-started)
+- [🏗 Project Structure](#-project-structure)
+- [⚙️ Configuration](#-configuration)
+- [📦 Collections](#-collections)
+- [🧪 Field Types](#-field-types)
+- [🌍 Globals](#-globals)
+- [🔐 Access Control](#-access-control)
+- [⚓ Hooks](#-hooks)
+- [👤 Authentication](#-authentication)
+- [🗄 Database Adapters](#-database-adapters)
+- [🔄 Migrations](#-migrations)
+- [☁️ Storage](#-storage)
+- [🌐 i18n](#-internationalization-i18n)
+- [🎨 Custom Components](#-custom-admin-components)
+- [🔌 API & SDK](#-the-client-sdk)
 
 ---
 
-## Getting Started
+## ✨ Getting Started
 
-**Requirements:** [Bun](https://bun.sh) (recommended) or Node.js 18+.
+You'll need [Bun](https://bun.sh) (highly recommended) or Node.js 18+.
 
 ```bash
-# Scaffold a new project
-bunx opacacms init my-cms
+# Kickstart a new project
+bunx opacacms init my-awesome-cms
 
-cd my-cms
+cd my-awesome-cms
 bun install
 bun dev
 ```
 
-To add OpacaCMS to an **existing** project:
-
-```bash
-bun add opacacms
-```
+Adding to an existing project? Easy: `bun add opacacms` 📦
 
 ---
 
-## Project Structure
+## 🏗 Project Structure
 
-```
+```text
 my-cms/
-├── opacacms.config.ts   ← schema + database + auth configuration
-├── migrations/          ← generated migration files
-├── opaca-types.d.ts     ← generated TypeScript types (optional)
-├── collections/         ← your collection definitions
-│   ├── posts.ts
-│   └── products.ts
-├── globals/             ← your global definitions
-│   └── site-settings.ts
-└── src/
-    └── index.ts         ← runtime entry point
+├── opacacms.config.ts   ← The heart of your CMS (schema + DB + auth)
+├── migrations/          ← Your DB history
+├── collections/         ← Where your data models live
+├── globals/             ← Singleton documents (settings, etc.)
+└── src/                 ← Your app logic
 ```
 
 ---
 
-## Configuration
+## ⚙️ Configuration
 
-Everything is defined in `opacacms.config.ts` and exported as the **default export**.
+Your `opacacms.config.ts` is the single source of truth. Export its configuration as the **default export**.
 
 ```typescript
-// opacacms.config.ts
 import { defineConfig } from 'opacacms';
 import { createSQLiteAdapter } from 'opacacms/db/sqlite';
 import { posts } from './collections/posts';
-import { siteSettings } from './globals/site-settings';
 
 export default defineConfig({
-  appName: 'My Blog',
+  appName: 'My Shiny Blog 💫',
   serverURL: 'http://localhost:3000',
-  secret: process.env.OPACA_SECRET,
   db: createSQLiteAdapter('local.db'),
-  collections: [posts.build()],
-  globals: [siteSettings.build()],
+  collections: [posts], // No need to call .build() anymore! ✌️
 });
 ```
 
-> `defineConfig` validates your configuration at startup and throws a descriptive error if anything is misconfigured.
-
-### Full config options
-
-| Option           | Type                             | Description                                   |
-| ---------------- | -------------------------------- | --------------------------------------------- |
-| `appName`        | `string`                         | Displayed in the admin UI                     |
-| `serverURL`      | `string`                         | The public URL of your application            |
-| `secret`         | `string`                         | Signs auth tokens — use an env variable       |
-| `db`             | `DatabaseAdapter`                | Required. Your database adapter               |
-| `collections`    | `Collection[]`                   | Your data schemas (call `.build()` on each)   |
-| `globals`        | `Global[]`                       | Singleton documents (call `.build()` on each) |
-| `storages`       | `Record<string, StorageAdapter>` | Named file storage buckets                    |
-| `auth`           | `OpacaAuthConfig`                | Auth strategies & features                    |
-| `api`            | `ApiConfig`                      | Rate limiting, max pagination limit           |
-| `i18n`           | `{ locales, defaultLocale }`     | Localization                                  |
-| `trustedOrigins` | `string[]`                       | For CORS and cookie security                  |
-
 ---
 
-## Collections
+## 📦 Collections
 
-A **Collection** maps directly to a database table and generates a full REST API automatically. Collections are defined using the **Collection Builder** from `opacacms/schema`.
+A **Collection** is a database table + a REST API. Pure magic. ✨
 
 ```typescript
 // collections/posts.ts
 import { Collection, Field } from 'opacacms/schema';
 
-export const posts = Collection.create('posts') // slug → /api/posts
+export const posts = Collection.create('posts')
   .label('Blog Posts')
   .icon('FileText')
-  .useAsTitle('title')
-  .versions({ drafts: true, maxRevisions: 10 })
-  .admin({
-    defaultColumns: ['title', 'slug', '_status', 'createdAt'],
-    views: [
-      { name: 'Published', filter: { _status: { equals: 'published' } } },
-      { name: 'Drafts', filter: { _status: { equals: 'draft' } } },
-    ],
-  })
   .fields([
-    Field.text('title').localized().required(),
+    Field.text('title').required(),
     Field.slug('slug').from('title').unique(),
     Field.richText('content').localized(),
-    Field.relationship('author').to('_users').single().displayField('name'),
-    Field.select('category')
-      .choices(['News', 'Tutorial', 'Review'])
-      .defaultValue('News'),
-    Field.date('publishedAt').label('Published At'),
+    Field.relationship('author').to('_users').single(),
   ]);
 ```
 
-Register in your config:
-
-```typescript
-// opacacms.config.ts
-import { posts } from './collections/posts';
-
-export default defineConfig({
-  collections: [posts.build()],
-});
-```
-
-### Collection Builder — all methods
-
-| Method                    | Description                                     |
-| ------------------------- | ----------------------------------------------- |
-| `Collection.create(slug)` | Start a new collection                          |
-| `.label(string)`          | Display name in the admin UI                    |
-| `.icon(IconName)`         | Lucide icon for the sidebar                     |
-| `.useAsTitle(fieldName)`  | Which field acts as the document title          |
-| `.timestamps(bool)`       | Add `createdAt` / `updatedAt` (default: `true`) |
-| `.fields([...])`          | Define fields — see [Field Types](#field-types) |
-| `.access(rules)`          | Collection-level access control                 |
-| `.versions(opts)`         | Enable drafts & revisions                       |
-| `.webhooks([...])`        | Outbound HTTP callbacks on lifecycle events     |
-| `.admin(opts)`            | Admin UI settings (columns, views, etc.)        |
-| `.virtual(name, opts)`    | Add a computed field (not stored in DB)         |
-| `.computed(name, opts)`   | Alias for `.virtual()`                          |
-| `.build()`                | Compile to the raw config object                |
-
-### Auto-generated API
+### 🛠 Builder Methods
 
-For a collection with slug `posts`:
-
-| Method   | Endpoint         | Description                |
-| -------- | ---------------- | -------------------------- |
-| `GET`    | `/api/posts`     | List documents (paginated) |
-| `GET`    | `/api/posts/:id` | Get single document        |
-| `POST`   | `/api/posts`     | Create document            |
-| `PATCH`  | `/api/posts/:id` | Update document            |
-| `DELETE` | `/api/posts/:id` | Delete document            |
-
-**Query parameters:** `?page=1&limit=10&sort=createdAt:desc&populate=author&locale=pt-BR`
-
-**Filtering:** `GET /api/posts?title[like]=%TypeScript%&_status[equals]=published`
+- `.label(name)`: Title in Sidebar.
+- `.icon(name)`: Lucide icon name.
+- `.fields([...])`: Your data structure.
+- `.access(rules)`: Who can do what.
+- `.hooks(fns)`: Lifecycle side-effects.
 
 ---
 
-## Field Types
-
-All fields are constructed with `Field` from `opacacms/schema`. Every field starts with `Field.<type>(name)` and supports a fluent modifier chain.
-
-### Common modifiers — available on all fields
+## 🧪 Field Types
 
-```typescript
-Field.text('title')
-  .label('Article Title')
-  .required() // NOT NULL
-  .unique() // UNIQUE constraint
-  .localized() // stored per-locale
-  .defaultValue('Untitled')
-  .readOnly() // non-editable in admin
-  .hidden() // hidden from admin UI
-  .placeholder('Enter title…')
-  .admin({ description: 'The article title', width: '50%' })
-  .validate((val) => val.length > 3 || 'Too short');
-```
-
-### Primitives
-
-```typescript
-Field.text('title').required();
-Field.textarea('bio').placeholder('Tell us about yourself…');
-Field.number('price').min(0).max(99999).defaultValue(0);
-Field.boolean('active').defaultValue(true).label('Is Active?');
-Field.date('publishedAt');
-Field.json('metadata');
-```
-
-### Slug
-
-```typescript
-Field.slug('slug').from('title').unique();
-// 'My Article' → 'my-article'
-```
-
-### Select & Radio
-
-```typescript
-Field.select('status').choices(['draft', 'published', 'archived']);
-
-Field.select('role').choices([
-  { label: 'Admin', value: 'admin' },
-  { label: 'Editor', value: 'editor' },
-  { label: 'Viewer', value: 'viewer' },
-]);
-
-Field.radio('tier').choices([
-  { label: 'Free', value: 'free' },
-  { label: 'Pro', value: 'pro' },
-  { label: 'Enterprise', value: 'enterprise' },
-]);
-```
-
-### Rich Text
-
-```typescript
-Field.richText('body').localized();
-// defaultMode: 'notion' (block-based) | 'simple' (toolbar)
-```
-
-### File Upload
-
-```typescript
-Field.file('avatar')
-  .bucket('default') // key in config.storages
-  .allowedmime_types(['image/jpeg', 'image/png', 'image/webp'])
-  .maxSize(5 * 1024 * 1024); // 5 MB
-```
-
-The uploaded file URL is stored inline in the document:
-
-```json
-{
-  "avatar": {
-    "url": "https://cdn.example.com/photo.jpg",
-    "filename": "photo.jpg",
-    "mime_type": "image/jpeg",
-    "filesize": 204800
-  }
-}
-```
-
-### Relationship
-
-```typescript
-// Single reference
-Field.relationship('author').to('_users').single().displayField('name');
-
-// hasMany — creates a join table automatically
-Field.relationship('tags').to('tags').many();
-
-// Type-safe reference to another Collection builder
-import { products } from './products';
-Field.relationship('related').to(products).many();
-```
-
-### Join (virtual inverse relationship)
-
-```typescript
-// Lists documents from another collection that reference this one
-Field.join('comments').collection('comments').on('post_id');
-```
-
-### Group (nested object)
-
-Flattened as `preferences__theme` in the database, returned as `{ preferences: { theme } }` in the API.
-
-```typescript
-Field.group('preferences').fields(
-  Field.select('theme').choices(['light', 'dark', 'system']),
-  Field.boolean('notifications').defaultValue(true),
-);
-```
-
-### Blocks (dynamic content sections)
-
-Each block type gets its own table. The API returns them as a single ordered array.
-
-```typescript
-Field.blocks('content').blocks(
-  Field.block('hero')
-    .label('Hero Section')
-    .fields(
-      Field.text('headline').required(),
-      Field.text('subheadline'),
-      Field.text('ctaLabel'),
-      Field.text('ctaLink'),
-    ),
-  Field.block('featureGrid')
-    .label('Feature Grid')
-    .fields(
-      Field.text('sectionTitle'),
-      Field.number('columns').defaultValue(3),
-    ),
-);
-```
-
-### Layout fields (admin only — no database column)
-
-```typescript
-// Side-by-side columns
-Field.row().fields(
-  Field.text('firstName').required(),
-  Field.text('lastName').required(),
-);
-
-// Tabbed sections
-Field.tabs()
-  .tab('Content', Field.text('title').required(), Field.textarea('description'))
-  .tab('SEO', Field.text('metaTitle'), Field.textarea('metaDescription'));
-
-// Collapsible section
-Field.collapsible()
-  .label('SEO Metadata')
-  .initiallyCollapsed()
-  .fields(
-    Field.text('metaTitle'),
-    Field.textarea('metaDescription'),
-    Field.text('canonicalUrl'),
-  );
-```
+We've got everything you need to build powerful schemas:
 
-### Virtual / Computed
-
-Computed at request time — never written to the database:
-
-```typescript
-export const users = Collection.create('users')
-  .fields([
-    Field.text('firstName').required(),
-    Field.text('lastName').required(),
-  ])
-  .virtual('fullName', {
-    label: 'Full Name',
-    returnType: 'string',
-    resolve: ({ data }) => `${data.firstName} ${data.lastName}`,
-  });
-```
+- `Field.text()`: Simple strings.
+- `Field.richText()`: Block-based editor (Notion style!). 📝
+- `Field.relationship()`: Connect your data.
+- `Field.file()`: Simple uploads. ☁️
+- `Field.blocks()`: Dynamic page builders. 🧱
+- `Field.group()`: Nested objects.
+- `Field.select()` / `Field.checkbox()`: Pickers.
 
 ---
 
-## Globals
+## 🎨 Custom Admin Components
 
-A **Global** is a singleton document (one row in the database). Perfect for site settings, navigation, or any app-wide configuration.
+This is where OpacaCMS shines. You can replace any field UI with your own **React** or **Vue** components. 💅
 
-```typescript
-// globals/site-settings.ts
-import { Global, Field } from 'opacacms/schema';
+### 1️⃣ React components
 
-export const siteSettings = Global.create('site-settings')
-  .label('Site Settings')
-  .icon('Settings')
-  .fields([
-    Field.text('siteName').required().defaultValue('My Site'),
-    Field.text('email').required(),
-    Field.text('phone'),
-  ]);
+Just use our `defineReactField` helper!
 
-// globals/header.ts
-export const headerSettings = Global.create('header')
-  .label('Header')
-  .icon('Layout')
-  .fields([
-    Field.text('siteTitle').required(),
-    Field.json('navItems').label('Navigation Items'),
-  ]);
-```
-
-Register in your config:
+```tsx
+// MyColorPicker.tsx
+import { defineReactField } from 'opacacms/admin';
+
+const ColorPicker = ({ value, onChange }) => (
+  <input
+    type="color"
+    value={value}
+    onChange={(e) => onChange(e.target.value)}
+  />
+);
 
-```typescript
-export default defineConfig({
-  globals: [siteSettings.build(), headerSettings.build()],
-});
+defineReactField('my-color-picker', ColorPicker);
 ```
 
-### Global Builder — all methods
-
-| Method                   | Description                                           |
-| ------------------------ | ----------------------------------------------------- |
-| `Global.create(slug)`    | Start a new global                                    |
-| `.label(string)`         | Admin display name                                    |
-| `.icon(IconName)`        | Lucide icon                                           |
-| `.timestamps(bool/opts)` | Enable/disable or rename timestamps (default: `true`) |
-| `.fields([...])`         | Field definitions                                     |
-| `.access(rules)`         | Who can read / update this global                     |
-| `.virtual(name, opts)`   | Add a computed field                                  |
-| `.build()`               | Compile to the raw config object                      |
-
-**API endpoints:**
+### 2️⃣ Vue components
 
-| Method  | Endpoint                     | Description         |
-| ------- | ---------------------------- | ------------------- |
-| `GET`   | `/api/globals/site-settings` | Read the document   |
-| `PATCH` | `/api/globals/site-settings` | Update the document |
+Same thing, just pass your `createApp` function!
 
----
-
-## Access Control
-
-Access can be defined at the **collection level** and at the **field level**.
-
-### Collection-level access
+```tsx
+// MyVuePicker.vue
+import { defineVueField } from 'opacacms/admin';
+import { createApp } from 'vue';
+import MyVueComponent from './MyVueComponent.vue';
 
-```typescript
-export const orders = Collection.create('orders')
-  .fields([...])
-  .access({
-    read:   ({ user }) => !!user,
-    create: ({ user }) => user?.role === 'admin',
-    update: ({ user, data }) => user?.id === data?.userId,
-    delete: false,
-  });
+defineVueField('my-vue-picker', MyVueComponent, { createApp });
 ```
 
-The `access` function receives: `{ req, user, session, apiKey, data, operation }`.
-
-### Field-level access
+### 3️⃣ Reference in Schema
 
 ```typescript
-Field.number('creditScore').access({
-  readOnly: ({ user }) => user?.role !== 'admin',
-});
-
-Field.textarea('internalNotes').access({
-  hidden: ({ user }) => user?.role !== 'admin', // stripped from API responses
+Field.text('color').admin({
+  components: {
+    Field: 'my-color-picker',
+  },
 });
 ```
 
-### Requiring API keys
-
-```typescript
-export const webhooks = Collection.create('webhooks')
-  .access({ requireApiKey: true })
-  .fields([...]);
-```
-
----
-
-## Hooks
-
-Run async logic during a document's lifecycle. Hooks can transform data before it is written or trigger side effects after.
-
-```typescript
-export const posts = Collection.create('posts')
-  .fields([
-    Field.text('title').required(),
-    Field.slug('slug').from('title').unique(),
-    Field.number('views'),
-  ])
-  .hooks({
-    beforeCreate: async (data) => {
-      data.views = 0;
-      return data;
-    },
-    afterCreate: async (doc) => {
-      await notifySlack(`New post: ${doc.title}`);
-    },
-    beforeUpdate: async (data) => data,
-    afterUpdate: async (doc) => {
-      /* ... */
-    },
-    beforeDelete: async (id) => {
-      /* ... */
-    },
-    afterDelete: async (id) => {
-      /* ... */
-    },
-  });
-```
-
-### Webhooks
-
-```typescript
-export const products = Collection.create('products')
-  .webhooks([
-    {
-      events: ['afterCreate', 'afterUpdate', 'afterDelete'],
-      url: 'https://api.example.com/webhooks/cms',
-      headers: { 'X-Secret': process.env.WEBHOOK_SECRET! },
-    },
-  ])
-  .fields([...]);
-```
-
 ---
 
-## Authentication
+## 🔐 Access Control
 
-OpacaCMS uses [better-auth](https://better-auth.com) under the hood. Auth tables (`_users`, `_sessions`, etc.) are created automatically by migrations.
+Secure your data with simple functions. 🛡️
 
 ```typescript
-export default defineConfig({
-  auth: {
-    strategies: {
-      emailPassword: true,
-      magicLink: {
-        enabled: true,
-        sendEmail: async ({ email, url }) => {
-          await sendTransactionalEmail({ to: email, loginUrl: url });
-        },
-      },
-    },
-    socialProviders: {
-      github: {
-        clientId: process.env.GITHUB_CLIENT_ID!,
-        clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      },
-    },
-    features: {
-      apiKeys: { enabled: true },
-    },
-  },
-});
+.access({
+  read: ({ user }) => !!user, // Logged in? You're good.
+  create: ({ user }) => user?.role === 'admin', // Only admins please!
+  update: ({ data, user }) => data.ownerId === user.id, // Only your own stuff.
+})
 ```
 
-Auth endpoints are at `/api/auth/*`. The Admin UI provides a built-in login page.
-
-### API Keys
-
-When `apiKeys` is enabled, clients can authenticate using `Authorization: Bearer <key>` instead of cookies — useful for server-to-server calls and webhooks.
-
 ---
 
-## Database Adapters
-
-Install only the adapter you need:
-
-```typescript
-// SQLite (zero config, great for development)
-import { createSQLiteAdapter } from 'opacacms/db/sqlite';
-db: createSQLiteAdapter('local.db');
-
-// SQLite via better-sqlite3 (synchronous, faster reads)
-import { createBetterSQLiteAdapter } from 'opacacms/db/better-sqlite';
-db: createBetterSQLiteAdapter('local.db');
-
-// Bun's built-in SQLite
-import { createBunSQLiteAdapter } from 'opacacms/db/bun-sqlite';
-db: createBunSQLiteAdapter('local.db');
-
-// PostgreSQL
-import { createPostgresAdapter } from 'opacacms/db/postgres';
-db: createPostgresAdapter(process.env.DATABASE_URL);
+## 👤 Authentication
 
-// Cloudflare D1
-import { createD1Adapter } from 'opacacms/db/d1';
-db: createD1Adapter(env.DB);
-```
-
-### Push mode (development only)
-
-```typescript
-db: createPostgresAdapter(process.env.DATABASE_URL, {
-  push: process.env.NODE_ENV !== 'production',
-  pushDestructive: false, // if true, drops stale columns/tables
-});
-```
+OpacaCMS uses [better-auth](https://better-auth.com) under the hood. It handles the heavy lifting so you don't have to. 🔒
 
 ---
 
-## Migrations
-
-For production, use file-based migrations instead of push mode.
+## 🔄 Migrations
 
-### 1. Generate migration files
+Go from development to production safely.
 
 ```bash
+# Create a migration
 bunx opacacms migrate:create initial-schema
-# → migrations/20260319120000_initial-schema.ts  (Postgres/SQLite)
-# → migrations/20260319120000_initial-schema.sql  (Cloudflare D1)
-```
 
-The generated file has zero external dependencies — no need to install `kysely`:
-
-```typescript
-// migrations/20260319120000_initial-schema.ts
-import type { OpacaMigrationDb } from 'opacacms/db';
-
-export async function up(db: OpacaMigrationDb): Promise<void> {
-  await db.schema
-    .createTable('posts')
-    .addColumn('id', 'text', (col) => col.primaryKey())
-    .addColumn('title', 'text', (col) => col.notNull())
-    .addColumn('slug', 'text', (col) => col.unique())
-    .addColumn('created_at', 'text', (col) =>
-      col.defaultTo('CURRENT_TIMESTAMP'),
-    )
-    .addColumn('updated_at', 'text', (col) =>
-      col.defaultTo('CURRENT_TIMESTAMP'),
-    )
-    .execute();
-}
-
-export async function down(db: OpacaMigrationDb): Promise<void> {
-  await db.schema.dropTable('posts').execute();
-}
-```
-
-### 2. Apply migrations
-
-```bash
+# Apply it
 bunx opacacms migrate
 ```
 
-### 3. Check status
-
-```bash
-bunx opacacms migrate:status
-```
-
-### Cloudflare D1
-
-```bash
-# Apply locally (dev)
-bunx opacacms migrate:d1 --local --binding DB
-
-# Apply to production
-bunx opacacms migrate:d1 --remote --binding DB
-```
-
----
-
-## Storage (File Uploads)
-
-Define storage buckets in your config. Reference them by name in `Field.file()`.
-
-### S3 / AWS
-
-```typescript
-import { createS3Adapter } from 'opacacms/storage/s3';
-
-storages: {
-  default: createS3Adapter({
-    region: process.env.AWS_REGION!,
-    bucket: process.env.S3_BUCKET!,
-    credentials: {
-      accessKeyId:     process.env.AWS_ACCESS_KEY_ID!,
-      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
-    },
-    publicUrl: 'https://cdn.example.com',
-  }),
-}
-```
-
-### Cloudflare R2
-
-```typescript
-import { createR2Adapter } from 'opacacms/storage/r2';
-
-storages: {
-  default: createR2Adapter({
-    bucketBinding: env.BUCKET,
-    publicUrl: 'https://assets.example.com',
-  }),
-  secure: createR2Adapter({
-    bucketBinding: env.SECURE_BUCKET,
-    publicUrl: 'https://assets.example.com',
-  }),
-}
-```
-
-### Local filesystem (development)
-
-```typescript
-import { createLocalAdapter } from 'opacacms/storage/local';
-
-storages: {
-  default: createLocalAdapter({
-    directory: './public/uploads',
-    publicUrl: 'http://localhost:3000/uploads',
-  }),
-}
-```
-
----
-
-## Internationalization (i18n)
-
-```typescript
-export default defineConfig({
-  i18n: {
-    locales: ['en', 'pt-BR', 'es'],
-    defaultLocale: 'pt-BR',
-  },
-});
-```
-
-Mark individual fields as localized with `.localized()`:
-
-```typescript
-Field.text('title').localized().required();
-Field.richText('body').localized();
-Field.text('slug'); // not localized — same value across all locales
-```
-
-The API resolves the locale from the `x-opaca-locale` header or `?locale=` query param, falling back to `defaultLocale`. Pass `?locale=all` to get all locales at once.
-
----
-
-## Custom Admin Components
-
-You can replace any field's input or table cell with your own component. This works with **any framework** — React, Vue, Vanilla JS — by implementing the `defineCustomField` adapter.
-
-### 1. Register a custom field tag
-
-```typescript
-// src/admin/my-components.ts
-import { defineCustomField } from 'opacacms/admin';
-import { createRoot } from 'react-dom/client';
-import MyColorPicker from './MyColorPicker';
-
-defineCustomField('my-color-picker', {
-  mount(container, props) {
-    (container as any)._root = createRoot(container);
-    (container as any)._root.render(<MyColorPicker {...props} />);
-  },
-  update(container, props) {
-    (container as any)._root.render(<MyColorPicker {...props} />);
-  },
-  unmount(container) {
-    (container as any)._root.unmount();
-  },
-});
-```
-
-The `props` object your component receives:
-
-| Prop          | Type            | Description                                 |
-| ------------- | --------------- | ------------------------------------------- |
-| `value`       | `any`           | Current field value                         |
-| `onChange`    | `(val) => void` | Call to update the value                    |
-| `fieldConfig` | `object`        | The field's schema definition               |
-| `disabled`    | `boolean`       | True if access control disabled the field   |
-| `readOnly`    | `boolean`       | True if access control made it read-only    |
-| `error`       | `string?`       | Validation error message                    |
-| `parentData`  | `object?`       | All other field values in the same document |
-
-### 2. Reference in the schema
-
-```typescript
-Field.text('primaryColor').admin({
-  components: {
-    Field: 'my-color-picker', // used in the edit form
-    Cell: 'my-color-cell', // used in the collection list table
-  },
-});
-```
-
-### 3. Load your script
-
-Your custom component script must be loaded in the browser before the admin UI mounts. For Cloudflare Workers, serve the file as a static asset and include it as a `<script>` tag in the admin HTML page. For Next.js, import it in your admin layout.
-
 ---
 
-## The Client SDK
+## 🔌 The Client SDK
 
-Use the typed client to query your CMS from any frontend:
+Query your CMS like a pro with full type-safety. ⚡️
 
 ```typescript
 import { createClient } from 'opacacms/client';
 
-const cms = createClient({ baseURL: 'https://my-cms.example.com' });
+const cms = createClient({ baseURL: 'https://api.mycms.com' });
 
-// List with filtering and pagination
-const result = await cms.collections.posts.find({
-  '_status[equals]': 'published',
+const posts = await cms.collections.posts.find({
   limit: 10,
-  page: 1,
-});
-console.log(result.docs); // array of documents
-console.log(result.totalPages);
-
-// Single document
-const post = await cms.collections.posts.findOne('abc-123');
-
-// Create / Update / Delete
-const newPost = await cms.collections.posts.create({ title: 'Hello' });
-await cms.collections.posts.update('abc-123', { title: 'Updated' });
-await cms.collections.posts.delete('abc-123');
-
-// Globals
-const settings = await cms.globals['site-settings'].get();
-await cms.globals['site-settings'].update({ siteName: 'New Name' });
-```
-
-### Typed client with generated types
-
-```bash
-bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
-```
-
-```typescript
-import { createClient } from 'opacacms/client';
-import type { GeneratedTypes } from './opaca-types';
-
-const cms = createClient<GeneratedTypes>({ baseURL: '...' });
-
-// IDE autocomplete now knows the exact shape of every collection
-const post = await cms.collections.posts.findOne('123');
-// post.title → string ✓
-```
-
----
-
-## Runtime Integrations
-
-### Next.js
-
-Create a catch-all API route:
-
-```
-src/app/api/[[...route]]/route.ts
-```
-
-```typescript
-// src/app/api/[[...route]]/route.ts
-import { createNextHandler } from 'opacacms/runtimes/next';
-import config from '../../../opacacms.config';
-
-export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } =
-  createNextHandler(config);
-```
-
-```typescript
-// opacacms.config.ts
-import { defineConfig } from 'opacacms';
-import { createPostgresAdapter } from 'opacacms/db/postgres';
-
-export default defineConfig({
-  appName: 'My Next.js CMS',
-  serverURL: process.env.NEXT_PUBLIC_API_URL!,
-  secret: process.env.OPACA_SECRET!,
-  db: createPostgresAdapter(process.env.DATABASE_URL!),
-  collections: [
-    /* posts.build(), ... */
-  ],
-});
-```
-
-Serve the Admin UI from a Next.js page:
-
-```tsx
-// src/app/admin/[[...all]]/page.tsx
-export default function AdminPage() {
-  return (
-    <html>
-      <body>
-        <opaca-admin server-url={process.env.NEXT_PUBLIC_API_URL} />
-        <script type="module" src="/opacacms/webcomponent.js" />
-      </body>
-    </html>
-  );
-}
-```
-
----
-
-### Cloudflare Workers
-
-```typescript
-// src/index.ts
-import { createCloudflareWorkersHandler } from 'opacacms/runtimes/cloudflare-workers';
-import getConfig from './opacacms.config';
-
-const app = createCloudflareWorkersHandler(getConfig);
-
-// Serve the Admin UI for /admin/* routes
-app.get('/admin*', (c) => {
-  return c.html(`
-    <!DOCTYPE html>
-    <html>
-      <head>
-        <title>Admin</title>
-        <link rel="stylesheet" href="/admin.css">
-      </head>
-      <body>
-        <opaca-admin server-url="${new URL(c.req.url).origin}"></opaca-admin>
-        <script type="module" src="/webcomponent.js"></script>
-      </body>
-    </html>
-  `);
+  sort: 'createdAt:desc',
 });
-
-export default app;
-```
-
-```typescript
-// opacacms.config.ts
-import { defineConfig } from 'opacacms';
-import { createD1Adapter } from 'opacacms/db/d1';
-import { createR2Adapter } from 'opacacms/storage/r2';
-
-// Export as a function to access per-request Cloudflare bindings
-const getConfig = (env: Env, request: Request) =>
-  defineConfig({
-    appName: 'My Workers CMS',
-    serverURL: new URL(request.url).origin,
-    secret: env.OPACA_SECRET,
-    trustedOrigins: ['https://my-frontend.com'],
-    db: createD1Adapter(env.DB),
-    storages: {
-      default: createR2Adapter({
-        bucketBinding: env.BUCKET,
-        publicUrl: new URL(request.url).origin,
-      }),
-    },
-    auth: {
-      features: { apiKeys: { enabled: true } },
-    },
-    i18n: {
-      locales: ['en', 'pt-BR'],
-      defaultLocale: 'pt-BR',
-    },
-    collections: [
-      /* posts.build(), ... */
-    ],
-    globals: [
-      /* siteSettings.build(), ... */
-    ],
-  });
-
-export default getConfig;
-```
-
-```jsonc
-// wrangler.jsonc
-{
-  "name": "my-cms",
-  "compatibility_date": "2024-09-23",
-  "d1_databases": [
-    { "binding": "DB", "database_name": "my-cms-db", "database_id": "..." },
-  ],
-  "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "my-cms-assets" }],
-}
-```
-
----
-
-### Bun (standalone)
-
-```typescript
-// src/index.ts
-import { createBunHandler } from 'opacacms/runtimes/bun';
-import config from './opacacms.config';
-
-const { init } = createBunHandler(config, { port: 3000 });
-await init();
-```
-
----
-
-### Node.js
-
-```typescript
-// src/index.ts
-import { createNodeHandler } from 'opacacms/runtimes/node';
-import config from './opacacms.config';
-
-const { init } = createNodeHandler(config, { port: 3000 });
-await init();
-```
-
----
-
-## CLI Reference
-
-The CLI auto-detects your config at `opacacms.config.ts`, `src/opacacms.config.ts`, or `index.ts`.
-
-```bash
-# Scaffold a new project
-bunx opacacms init my-project
-
-# Generate migrations from your current schema
-bunx opacacms migrate:create <name>
-
-# Apply pending migrations (Postgres / SQLite)
-bunx opacacms migrate
-
-# Check which migrations have been applied
-bunx opacacms migrate:status
-
-# Apply SQL migrations to Cloudflare D1
-bunx opacacms migrate:d1 --local   # local dev
-bunx opacacms migrate:d1 --remote  # production
-
-# Seed the database with fake data
-bunx opacacms seed --count 50
-bunx opacacms seed:assets --count 20
-
-# Generate TypeScript types from a running instance
-bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
-
-# Use a custom config file path
-bunx opacacms migrate:create --config ./path/to/config.ts
 ```
 
 ---
 
-## Production Build
+## 🌟 Why OpacaCMS?
 
-### Disable push mode
+- **Blazing Fast**: Built on Hono & Bun. 🚀
+- **Truly Decoupled**: Your data is yours. No hidden SaaS lock-in.
+- **Developer First**: Everything is a typed API. 👩‍💻
+- **Deploy Anywhere**: Vercel, Cloudflare, Fly.io, or your own VPS.
 
-```typescript
-db: createPostgresAdapter(process.env.DATABASE_URL, {
-  push: false, // never auto-alter schema in production
-});
-```
-
-### Required environment variables
-
-```bash
-OPACA_SECRET=<random-32-char-string>    # required
-DATABASE_URL=postgres://...             # for Postgres
-```
-
-### Deploy flow
-
-```bash
-# Generate + apply migrations
-bunx opacacms migrate:create latest
-bunx opacacms migrate            # Postgres / SQLite
-# or
-bunx opacacms migrate:d1 --remote  # Cloudflare D1
-
-# Start the server
-node dist/index.js
-# or
-wrangler deploy
-```
+Ready to build something awesome? [Let's go!](https://opacacms.com) 🎈