opacacms 0.1.20 → 0.2.0

package/README.md

@@ -1,916 +1,801 @@
-# 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)
+- [✅ Validation](#-validation)
+- [🌍 Globals](#-globals)
+- [🔐 Access Control](#-access-control)
+- [⚓ Hooks](#-hooks)
+- [🔔 Webhooks](#-webhooks)
+- [📌 Versioning](#-versioning)
+- [🧮 Virtual Fields](#-virtual-fields)
+- [👤 Authentication](#-authentication)
+- [📝 Logging](#-logging)
+- [🗄 Database Adapters](#-database-adapters)
+- [🔄 Migrations](#-migrations)
+- [☁️ Storage](#-storage)
+- [🌐 Internationalization (i18n)](#-internationalization-i18n)
+- [🎨 Custom Admin Components](#-custom-admin-components)
+- [🔌 API & SDK](#-the-client-sdk)
+- [🏠 Full-Stack Examples](#-full-stack-examples)
 
 ---
 
-## 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
+├── opacacms.config.ts   ← The heart of your CMS (schema + DB + auth)
+├── migrations/          ← Your DB history
+├── collections/         ← Where your data models live
 │   ├── posts.ts
-│   └── products.ts
-├── globals/             ← your global definitions
-│   └── site-settings.ts
-└── src/
-    └── index.ts         ← runtime entry point
+│   ├── products.ts
+│   └── ...
+├── globals/             ← Singleton documents (settings, etc.)
+│   ├── site-settings.ts
+│   └── ...
+└── 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 { defineConfig } from 'opacacms/config';
 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],
+  globals: [siteSettings],
+  i18n: {
+    locales: ['en', 'pt-BR', 'tr'],
+    defaultLocale: 'en',
+  },
+  auth: {
+    strategies: { emailPassword: true },
+    features: {
+      apiKeys: { enabled: true },
+    },
+  },
+  logger: { level: 'debug' },
 });
 ```
 
-> `defineConfig` validates your configuration at startup and throws a descriptive error if anything is misconfigured.
-
-### Full config options
+### Configuration 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                  |
+| Option           | Type                             | Description                                                       |
+| ---------------- | -------------------------------- | ----------------------------------------------------------------- |
+| `appName`        | `string`                         | Display name shown in the Admin UI sidebar                        |
+| `serverURL`      | `string`                         | The base URL of your server (used for CORS, auth callbacks, etc.) |
+| `secret`         | `string`                         | Secret used for signing tokens and encryption                     |
+| `db`             | `DatabaseAdapter`                | Database adapter (`createSQLiteAdapter`, `createD1Adapter`, etc.) |
+| `collections`    | `Collection[]`                   | Array of collection definitions                                   |
+| `globals`        | `Global[]`                       | Array of global definitions                                       |
+| `i18n`           | `{ locales, defaultLocale }`     | Internationalization config                                       |
+| `auth`           | `AuthConfig`                     | Authentication strategies and features                            |
+| `logger`         | `{ level, disabled? }`           | Logger configuration                                              |
+| `trustedOrigins` | `string[]`                       | Origins allowed for CORS requests                                 |
+| `storages`       | `Record<string, StorageAdapter>` | Named storage adapters for file uploads                           |
+| `api`            | `{ maxLimit? }`                  | API-level settings (e.g., max items per page)                     |
 
 ---
 
-## 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().label('Post Title'),
     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'),
-  ]);
-```
-
-Register in your config:
-
-```typescript
-// opacacms.config.ts
-import { posts } from './collections/posts';
-
-export default defineConfig({
-  collections: [posts.build()],
-});
+    Field.relationship('author').to('_users').single(),
+    Field.select('status')
+      .options([
+        { label: 'Draft', value: 'draft' },
+        { label: 'Published', value: 'published' },
+      ])
+      .defaultValue('draft'),
+    Field.checkbox('featured').label('Featured Post'),
+  ])
+  .access({
+    read: () => true,
+    create: ({ user }) => !!user,
+    update: ({ user }) => user?.role === 'admin',
+    delete: ({ user }) => user?.role === 'admin',
+  })
+  .hooks({
+    beforeCreate: async (data) => {
+      // Mutate data before insertion
+      return { ...data, publishedAt: new Date().toISOString() };
+    },
+    afterCreate: async (doc) => {
+      console.log('New post created:', doc.id);
+    },
+  });
 ```
 
-### 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
-
-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            |
+### Collection Builder Methods
 
-**Query parameters:** `?page=1&limit=10&sort=createdAt:desc&populate=author&locale=pt-BR`
-
-**Filtering:** `GET /api/posts?title[like]=%TypeScript%&_status[equals]=published`
+| Method               | Description                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `.label(name)`       | Sets the display name used in the Admin UI sidebar               |
+| `.icon(name)`        | [Lucide](https://lucide.dev) icon name for the sidebar           |
+| `.fields([...])`     | Defines the data structure for this collection                   |
+| `.access(rules)`     | Collection-level access control                                  |
+| `.hooks(fns)`        | Lifecycle hooks (`beforeCreate`, `afterUpdate`, etc.)            |
+| `.webhooks([...])`   | External webhook notifications                                   |
+| `.admin({...})`      | Advanced Admin UI configuration (`hidden`, `disableAdmin`, etc.) |
+| `.versions(true)`    | Enable document versioning with history                          |
+| `.timestamps({...})` | Customize timestamp field names                                  |
 
 ---
 
-## 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
-
-```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'
+## 🧪 Field Types
+
+We've got everything you need to build powerful schemas:
+
+| Field                  | Usage                                       | Description                                   |
+| ---------------------- | ------------------------------------------- | --------------------------------------------- |
+| `Field.text()`         | `Field.text('title')`                       | Simple string input                           |
+| `Field.number()`       | `Field.number('price')`                     | Numeric input                                 |
+| `Field.richText()`     | `Field.richText('content')`                 | Block-based Lexical editor (Notion style!) 📝 |
+| `Field.relationship()` | `Field.relationship('author').to('_users')` | Links to another collection                   |
+| `Field.file()`         | `Field.file('image')`                       | File/image upload ☁️                          |
+| `Field.blocks()`       | `Field.blocks('layout').blocks([...])`      | Dynamic page builder 🧱                       |
+| `Field.group()`        | `Field.group('meta').fields([...])`         | Nested object group                           |
+| `Field.array()`        | `Field.array('tags').fields([...])`         | Repeatable field group                        |
+| `Field.select()`       | `Field.select('status').options([...])`     | Dropdown picker                               |
+| `Field.checkbox()`     | `Field.checkbox('active')`                  | Boolean toggle                                |
+| `Field.slug()`         | `Field.slug('slug').from('title')`          | Auto-generated URL slug                       |
+| `Field.date()`         | `Field.date('publishedAt')`                 | Date/time picker                              |
+| `Field.virtual()`      | `Field.virtual('fullName').resolve(...)`    | Computed field (not stored)                   |
+| `Field.tabs()`         | `Field.tabs('layout').tabs([...])`          | UI-only grouping for the admin                |
+
+### Common Field Methods
+
+Every field type inherits these chainable methods from the base builder:
+
+```typescript
+Field.text('email')
+  .label('Email Address') // Admin UI label
+  .placeholder('you@example.com') // Input placeholder
+  .required() // Mark as required
+  .unique() // Unique constraint in the DB
+  .localized() // Enable per-locale values (i18n)
+  .defaultValue('hello@world.com') // Default value
+  .validate(z.string().email()) // Custom validation (function or Zod)
+  .access({ readOnly: true }) // Field-level access control
+  .description('Primary email') // Help text below the field
+  .hidden() // Hide from Admin UI
+  .readOnly() // Read-only in Admin UI
+  .admin({ components: { Field: 'my-custom-field' } }); // Custom component
 ```
 
-### 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');
+## ✅ Validation
 
-// hasMany — creates a join table automatically
-Field.relationship('tags').to('tags').many();
+OpacaCMS supports **granular field validation** via the `.validate()` method. You can pass either a **custom function** or a **Zod schema** — they're fully interchangeable.
 
-// Type-safe reference to another Collection builder
-import { products } from './products';
-Field.relationship('related').to(products).many();
-```
+### Custom Function Validation
 
-### Join (virtual inverse relationship)
+Return `true` to pass, or a `string` error message to fail:
 
 ```typescript
-// Lists documents from another collection that reference this one
-Field.join('comments').collection('comments').on('post_id');
+Field.text('username').validate((value) => {
+  if (value === 'admin') return "Username 'admin' is reserved";
+  return true;
+});
 ```
 
-### Group (nested object)
+### Zod Schema Validation
 
-Flattened as `preferences__theme` in the database, returned as `{ preferences: { theme } }` in the API.
+Pass any `z.ZodTypeAny` schema directly. Errors are automatically mapped:
 
 ```typescript
-Field.group('preferences').fields(
-  Field.select('theme').choices(['light', 'dark', 'system']),
-  Field.boolean('notifications').defaultValue(true),
-);
-```
-
-### Blocks (dynamic content sections)
+import { z } from 'zod';
 
-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),
-    ),
+Field.text('cpf').validate(
+  z.string().regex(/^\d{3}\.\d{3}\.\d{3}-\d{2}$/, 'Invalid CPF format'),
 );
-```
-
-### Layout fields (admin only — no database column)
 
-```typescript
-// Side-by-side columns
-Field.row().fields(
-  Field.text('firstName').required(),
-  Field.text('lastName').required(),
+Field.text('password').validate(
+  z
+    .string()
+    .min(8, 'Password must be at least 8 characters')
+    .regex(/[A-Z]/, 'Must contain at least one uppercase letter'),
 );
 
-// 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'),
-  );
+Field.text('email')
+  .required()
+  .validate(z.string().email('Invalid email address'));
 ```
 
-### 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}`,
-  });
-```
+> **💡 Tip:** Zod validation integrates seamlessly with `.required()`. The built-in requirement check runs first, then your Zod schema validates the value shape.
 
 ---
 
-## Globals
+## 🌍 Globals
 
-A **Global** is a singleton document (one row in the database). Perfect for site settings, navigation, or any app-wide configuration.
+Globals are **singleton documents** — perfect for site settings, navigation, footers, and other one-of-a-kind configs.
 
 ```typescript
-// globals/site-settings.ts
 import { Global, Field } from 'opacacms/schema';
 
 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'),
-  ]);
-
-// globals/header.ts
-export const headerSettings = Global.create('header')
-  .label('Header')
-  .icon('Layout')
-  .fields([
-    Field.text('siteTitle').required(),
-    Field.json('navItems').label('Navigation Items'),
+    Field.text('siteName').required(),
+    Field.text('tagline').localized(),
+    Field.file('logo'),
+    Field.group('social').fields([Field.text('twitter'), Field.text('github')]),
   ]);
 ```
 
-Register in your config:
-
-```typescript
-export default defineConfig({
-  globals: [siteSettings.build(), headerSettings.build()],
-});
-```
-
-### 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:**
-
-| Method  | Endpoint                     | Description         |
-| ------- | ---------------------------- | ------------------- |
-| `GET`   | `/api/globals/site-settings` | Read the document   |
-| `PATCH` | `/api/globals/site-settings` | Update the document |
+API: `GET /api/globals/site-settings` and `PUT /api/globals/site-settings`
 
 ---
 
-## Access Control
+## 🔐 Access Control
 
-Access can be defined at the **collection level** and at the **field level**.
+Secure your data with simple functions at both **collection** and **field** levels. 🛡️
 
-### Collection-level access
+### Collection-Level Access
 
 ```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,
-  });
+.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.
+  delete: ({ user }) => user?.role === 'admin',
+  requireApiKey: true,                            // Require API key for programmatic access
+})
 ```
 
-The `access` function receives: `{ req, user, session, apiKey, data, operation }`.
+### Field-Level Access
 
-### Field-level access
+Control visibility and editability per-field:
 
 ```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('internalNotes').access({
+  hidden: ({ user }) => user?.role !== 'admin', // Only admins see this
+  readOnly: ({ operation }) => operation === 'update', // Editable only on create
+  disabled: false,
 });
 ```
 
-### Requiring API keys
+### Role-Based Access Control (RBAC)
+
+Combine `auth` with the `access` property to define granular permissions:
 
 ```typescript
-export const webhooks = Collection.create('webhooks')
-  .access({ requireApiKey: true })
-  .fields([...]);
+access: {
+  roles: {
+    admin: {
+      posts: ['read', 'create', 'update', 'delete'],
+      users: ['read', 'update']
+    },
+    editor: {
+      posts: ['read', 'update']
+    }
+  }
+}
 ```
 
 ---
 
-## 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) => {
-      /* ... */
-    },
-  });
-```
+## ⚓ Hooks
 
-### Webhooks
+Hooks let you run side-effects at key points in the document lifecycle. They receive the document data and can mutate it before persistence.
 
 ```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([...]);
+.hooks({
+  beforeCreate: async (data) => {
+    // Transform or enrich data before saving
+    data.slug = data.title.toLowerCase().replace(/\s+/g, '-');
+    return data;
+  },
+  afterCreate: async (doc) => {
+    // Side-effects after the document is saved
+    await sendWelcomeEmail(doc.email);
+  },
+  beforeUpdate: async (data) => {
+    data.updatedBy = 'system';
+    return data;
+  },
+  afterUpdate: async (doc) => {
+    await invalidateCache(`/posts/${doc.slug}`);
+  },
+  beforeDelete: async (id) => {
+    await archiveDocument(id);
+  },
+  afterDelete: async (id) => {
+    console.log(`Document ${id} deleted`);
+  },
+})
 ```
 
 ---
 
-## Authentication
+## 🔔 Webhooks
 
-OpacaCMS uses [better-auth](https://better-auth.com) under the hood. Auth tables (`_users`, `_sessions`, etc.) are created automatically by migrations.
+Send HTTP notifications to external services when documents change. Webhooks run in the background using `waitUntil` on supported runtimes (Cloudflare Workers, Vercel Edge).
 
 ```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 },
-    },
+Collection.create('orders').webhooks([
+  {
+    url: 'https://hooks.slack.com/services/xxx',
+    events: ['afterCreate', 'afterUpdate'],
+    headers: { Authorization: 'Bearer my-token' },
   },
-});
+  {
+    url: 'https://api.example.com/webhooks/orders',
+    events: ['afterDelete'],
+  },
+]);
 ```
 
-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.
+Supported events: `afterCreate`, `afterUpdate`, `afterDelete`.
 
 ---
 
-## Database Adapters
+## 📌 Versioning
 
-Install only the adapter you need:
+Enable document versioning to keep a full history of changes. Each save creates a snapshot that can be restored later.
 
 ```typescript
-// SQLite (zero config, great for development)
-import { createSQLiteAdapter } from 'opacacms/db/sqlite';
-db: createSQLiteAdapter('local.db');
+Collection.create('posts')
+  .versions(true) // That's it!
+  .fields([...])
+```
 
-// SQLite via better-sqlite3 (synchronous, faster reads)
-import { createBetterSQLiteAdapter } from 'opacacms/db/better-sqlite';
-db: createBetterSQLiteAdapter('local.db');
+### Version API
 
-// Bun's built-in SQLite
-import { createBunSQLiteAdapter } from 'opacacms/db/bun-sqlite';
-db: createBunSQLiteAdapter('local.db');
+| Endpoint                                 | Method | Description                      |
+| ---------------------------------------- | ------ | -------------------------------- |
+| `/api/posts/versions?parentId=xxx`       | `GET`  | List all versions for a document |
+| `/api/posts/versions/:versionId/restore` | `POST` | Restore a specific version       |
 
-// PostgreSQL
-import { createPostgresAdapter } from 'opacacms/db/postgres';
-db: createPostgresAdapter(process.env.DATABASE_URL);
+The admin UI provides a visual "Versions" panel where editors can browse and restore past versions.
 
-// Cloudflare D1
-import { createD1Adapter } from 'opacacms/db/d1';
-db: createD1Adapter(env.DB);
-```
+---
 
-### Push mode (development only)
+## 🧮 Virtual Fields
+
+Virtual fields are **computed at read-time** and never stored in the database. Perfect for derived values, aggregated data, or API mashups.
 
 ```typescript
-db: createPostgresAdapter(process.env.DATABASE_URL, {
-  push: process.env.NODE_ENV !== 'production',
-  pushDestructive: false, // if true, drops stale columns/tables
+Field.virtual('fullName').resolve(async ({ data, user, req }) => {
+  return `${data.firstName} ${data.lastName}`;
 });
 ```
 
+Virtual fields receive the full document `data`, the current `user`, `session`, `apiKey`, and the Hono `req` context.
+
 ---
 
-## Migrations
+## 👤 Authentication
 
-For production, use file-based migrations instead of push mode.
+OpacaCMS features a robust, built-in authentication system powered by [Better Auth](https://better-auth.com). It's secure by default and fully customizable.
 
-### 1. Generate migration files
+### Basic Setup
 
-```bash
-bunx opacacms migrate:create initial-schema
-# → migrations/20260319120000_initial-schema.ts  (Postgres/SQLite)
-# → migrations/20260319120000_initial-schema.sql  (Cloudflare D1)
+```typescript
+auth: {
+  strategies: {
+    emailPassword: true, // Enabled by default
+    magicLink: {
+      enabled: true,
+      sendEmail: async ({ email, url }) => {
+        await sendMyMagicLink(email, url);
+      }
+    }
+  },
+  features: {
+    apiKeys: { enabled: true }, // Programmable access
+    mfa: { enabled: true, issuer: 'My App' } // Two-Factor Auth
+  }
+}
 ```
 
-The generated file has zero external dependencies — no need to install `kysely`:
+### API Key Authentication
 
-```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();
-}
+When `apiKeys` is enabled, you can create API keys with fine-grained collection permissions:
 
-export async function down(db: OpacaMigrationDb): Promise<void> {
-  await db.schema.dropTable('posts').execute();
+```typescript
+// API keys can have per-collection permissions
+{
+  permissions: {
+    posts: ['read', 'create'],
+    users: ['read']
+  }
 }
 ```
 
-### 2. Apply migrations
+Pass the key in your requests:
 
 ```bash
-bunx opacacms migrate
+curl -H "Authorization: Bearer opaca_key_xxx" https://api.mycms.com/api/posts
 ```
 
-### 3. Check status
+---
 
-```bash
-bunx opacacms migrate:status
-```
+## 📝 Logging
 
-### Cloudflare D1
+OpacaCMS includes a configurable global logger that standardizes output across the core system and authentication events.
 
-```bash
-# Apply locally (dev)
-bunx opacacms migrate:d1 --local --binding DB
+```typescript
+logger: {
+  level: 'debug', // 'debug' | 'info' | 'warn' | 'error'
+  disabled: false,
+  disableColors: false
+}
+```
+
+Access the logger in custom middleware:
 
-# Apply to production
-bunx opacacms migrate:d1 --remote --binding DB
+```typescript
+const logger = c.get('logger');
+logger.info('Custom route hit');
 ```
 
 ---
 
-## Storage (File Uploads)
+## 🗄 Database Adapters
 
-Define storage buckets in your config. Reference them by name in `Field.file()`.
+OpacaCMS provides first-class adapters for multiple database engines. All adapters implement the same interface, so switching is as simple as changing one line.
 
-### S3 / AWS
+| Adapter       | Import               | Usage                             |
+| ------------- | -------------------- | --------------------------------- |
+| SQLite (Bun)  | `opacacms/db/sqlite` | `createSQLiteAdapter('local.db')` |
+| Cloudflare D1 | `opacacms/db/d1`     | `createD1Adapter(env.DB)`         |
 
-```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',
-  }),
-}
+## 🔄 Migrations
+
+Migrations keep your database schema in sync with your collections. They're auto-generated from your field definitions.
+
+```bash
+# Create a migration
+bunx opacacms migrate:create initial-schema
+
+# Apply migrations
+bunx opacacms migrate
 ```
 
-### Cloudflare R2
+When using `createBunHandler` or `createCloudflareWorkersHandler`, migrations run automatically on startup via `db.migrate(config.collections)`.
+
+---
+
+## ☁️ Storage
+
+OpacaCMS supports pluggable storage adapters for file uploads. You can define multiple named storages and reference them per-field.
 
 ```typescript
-import { createR2Adapter } from 'opacacms/storage/r2';
+import { createR2Storage } from 'opacacms/storage';
 
 storages: {
-  default: createR2Adapter({
+  default: createR2Storage({
     bucketBinding: env.BUCKET,
-    publicUrl: 'https://assets.example.com',
+    publicUrl: 'https://cdn.example.com',
   }),
-  secure: createR2Adapter({
+  secure: createR2Storage({
     bucketBinding: env.SECURE_BUCKET,
-    publicUrl: 'https://assets.example.com',
+    publicUrl: 'https://secure.example.com',
   }),
 }
 ```
 
-### Local filesystem (development)
+---
 
-```typescript
-import { createLocalAdapter } from 'opacacms/storage/local';
+## 🌐 Internationalization (i18n)
 
-storages: {
-  default: createLocalAdapter({
-    directory: './public/uploads',
-    publicUrl: 'http://localhost:3000/uploads',
-  }),
+Enable field-level localization with a simple config and the `.localized()` method on any field.
+
+```typescript
+// Config
+i18n: {
+  locales: ['en', 'pt-BR', 'tr'],
+  defaultLocale: 'en',
 }
+
+// Field
+Field.text('title').localized()
+Field.richText('content').localized()
 ```
 
----
+### Locale Selection
 
-## Internationalization (i18n)
+Pass the desired locale in your API requests:
 
-```typescript
-export default defineConfig({
-  i18n: {
-    locales: ['en', 'pt-BR', 'es'],
-    defaultLocale: 'pt-BR',
-  },
-});
-```
+```bash
+# Via header
+curl -H "x-opaca-locale: pt-BR" https://api.mycms.com/api/posts
 
-Mark individual fields as localized with `.localized()`:
+# Via query parameter
+curl https://api.mycms.com/api/posts?locale=pt-BR
 
-```typescript
-Field.text('title').localized().required();
-Field.richText('body').localized();
-Field.text('slug'); // not localized — same value across all locales
+# Get all locales
+curl https://api.mycms.com/api/posts?locale=all
 ```
 
-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.
+When writing data, send the locale header and the value will be stored under that locale key automatically. The system handles merging — existing locale values are preserved.
 
 ---
 
-## Custom Admin Components
+## 🎨 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.
+This is where OpacaCMS shines. You can replace any field UI with your own **React** or **Vue** components via Web Components. 💅
 
-### 1. Register a custom field tag
+### 1️⃣ React Components
 
-```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();
-  },
-});
+```tsx
+// MyColorPicker.tsx
+import { defineReactField } from 'opacacms/admin';
+
+const ColorPicker = ({ value, onChange }) => (
+  <input
+    type="color"
+    value={value}
+    onChange={(e) => onChange(e.target.value)}
+  />
+);
+
+defineReactField('my-color-picker', ColorPicker);
 ```
 
-The `props` object your component receives:
+### 2️⃣ Vue Components
 
-| 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 |
+```tsx
+// MyVuePicker.vue
+import { defineVueField } from 'opacacms/admin';
+import { createApp } from 'vue';
+import MyVueComponent from './MyVueComponent.vue';
 
-### 2. Reference in the schema
+defineVueField('my-vue-picker', MyVueComponent, { createApp });
+```
+
+### 3️⃣ Reference in Schema
 
 ```typescript
-Field.text('primaryColor').admin({
+Field.text('color').admin({
   components: {
-    Field: 'my-color-picker', // used in the edit form
-    Cell: 'my-color-cell', // used in the collection list table
+    Field: 'my-color-picker',
   },
 });
 ```
 
-### 3. Load your script
+---
+
+## 🛠 Advanced Admin Configuration
+
+Collections and Fields can be further customized for the Admin UI using the `.admin()` method.
+
+### Collection Admin Options
+
+| Option           | Type       | Description                                                                     |
+| ---------------- | ---------- | ------------------------------------------------------------------------------- |
+| `hidden`         | `boolean`  | If true, hides the collection from the sidebar but keeps it accessible via URL. |
+| `disableAdmin`   | `boolean`  | If true, completely removes the collection from the Admin UI.                   |
+| `useAsTitle`     | `string`   | The field name to use as the title in breadcrumbs and lists.                    |
+| `defaultColumns` | `string[]` | The default fields to show in the collection list table.                        |
 
-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.
+Example:
+
+```typescript
+export const InternalData = Collection.create('internal_data')
+  .admin({
+    hidden: true, // Only accessible via direct link
+  })
+  .fields([...]);
+```
 
 ---
 
-## 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,
+  sort: 'createdAt:desc',
+  // Deep Populate! 🚀
+  populate: {
+    author: true,
+    comments: {
+      populate: {
+        user: true,
+      },
+    },
+  },
 });
-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
+### Filtering & Querying
 
 ```bash
-bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
-```
+# Basic filter
+GET /api/posts?status=published
 
-```typescript
-import { createClient } from 'opacacms/client';
-import type { GeneratedTypes } from './opaca-types';
+# Operator-based filtering
+GET /api/posts?price[gt]=10&price[lt]=100
 
-const cms = createClient<GeneratedTypes>({ baseURL: '...' });
+# Pagination
+GET /api/posts?page=2&limit=20
 
-// IDE autocomplete now knows the exact shape of every collection
-const post = await cms.collections.posts.findOne('123');
-// post.title → string ✓
+# Sorting
+GET /api/posts?sort=createdAt:desc
+
+# Deep populate via REST
+GET /api/posts?populate=author,comments.user
 ```
 
 ---
 
-## Runtime Integrations
+## 🏠 Full-Stack Examples
 
-### Next.js
+### Next.js (App Router)
 
-Create a catch-all API route:
+OpacaCMS integrates with Next.js via the `createNextHandler` which wraps the internal Hono router using `hono/vercel`.
 
-```
-src/app/api/[[...route]]/route.ts
-```
+#### 1. API Route Handler
 
 ```typescript
-// src/app/api/[[...route]]/route.ts
+// app/api/[[...route]]/route.ts
 import { createNextHandler } from 'opacacms/runtimes/next';
-import config from '../../../opacacms.config';
+import config from '@/opacacms.config';
 
-export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } =
+export const { GET, POST, PUT, DELETE, PATCH, OPTIONS } =
   createNextHandler(config);
 ```
 
-```typescript
-// opacacms.config.ts
-import { defineConfig } from 'opacacms';
-import { createPostgresAdapter } from 'opacacms/db/postgres';
+#### 2. Admin UI Page
 
-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:
+The admin interface is delivered as a **Web Component** — just import it in a client page and point it at your server:
 
 ```tsx
-// src/app/admin/[[...all]]/page.tsx
+// app/admin/[[...segments]]/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import 'opacacms/admin/ui/styles/index.scss'; // Admin styles
+
+// Declare the web component for TypeScript
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'opaca-admin': {
+        'server-url'?: string;
+        config?: string;
+      };
+    }
+  }
+}
+
 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>
-  );
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    import('opacacms/admin/webcomponent')
+      .then(() => setLoaded(true))
+      .catch((err) => console.error('Failed to load Opaca Admin', err));
+  }, []);
+
+  if (!loaded) return <div>Loading Admin Interface...</div>;
+
+  return <opaca-admin server-url="http://localhost:3000" />;
 }
 ```
 
+That's it! Your full-stack Next.js app now has a complete CMS admin panel at `/admin` and a REST API at `/api`.
+
+---
+
+### Vue
+
+For Vue, import the pre-built admin bundle and use the web component directly:
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import 'opacacms/admin.css'; // Or the bundled CSS path
+
+const loaded = ref(false);
+
+onMounted(async () => {
+  try {
+    await import('opacacms/admin/webcomponent');
+    loaded.value = true;
+  } catch (err) {
+    console.error('Failed to load Opaca Admin', err);
+  }
+});
+</script>
+
+<template>
+  <div v-if="!loaded">Loading Admin Interface...</div>
+  <opaca-admin v-else server-url="http://localhost:3000" />
+</template>
+```
+
+Your API server can run as a separate Bun or Node.js process using the standalone handler.
+
 ---
 
 ### Cloudflare Workers
 
+OpacaCMS runs natively on Cloudflare Workers with D1 (database) and R2 (storage):
+
 ```typescript
 // src/index.ts
 import { createCloudflareWorkersHandler } from 'opacacms/runtimes/cloudflare-workers';
-import getConfig from './opacacms.config';
+import config from './opacacms.config';
 
-const app = createCloudflareWorkersHandler(getConfig);
+const app = createCloudflareWorkersHandler(config);
 
-// Serve the Admin UI for /admin/* routes
+// Serve the admin SPA
 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>
+    <head>
+      <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>
   `);
 });
@@ -920,144 +805,165 @@ export default app;
 
 ```typescript
 // opacacms.config.ts
-import { defineConfig } from 'opacacms';
+import { defineConfig } from 'opacacms/config';
 import { createD1Adapter } from 'opacacms/db/d1';
-import { createR2Adapter } from 'opacacms/storage/r2';
+import { createR2Storage } from 'opacacms/storage';
 
-// Export as a function to access per-request Cloudflare bindings
 const getConfig = (env: Env, request: Request) =>
   defineConfig({
-    appName: 'My Workers CMS',
+    appName: 'My Edge CMS',
     serverURL: new URL(request.url).origin,
     secret: env.OPACA_SECRET,
-    trustedOrigins: ['https://my-frontend.com'],
     db: createD1Adapter(env.DB),
     storages: {
-      default: createR2Adapter({
+      default: createR2Storage({
         bucketBinding: env.BUCKET,
         publicUrl: new URL(request.url).origin,
       }),
     },
-    auth: {
-      features: { apiKeys: { enabled: true } },
-    },
+    collections: [posts, products],
     i18n: {
       locales: ['en', 'pt-BR'],
-      defaultLocale: 'pt-BR',
+      defaultLocale: 'en',
     },
-    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)
+### Bun (Standalone Server)
 
 ```typescript
-// src/index.ts
 import { createBunHandler } from 'opacacms/runtimes/bun';
 import config from './opacacms.config';
 
-const { init } = createBunHandler(config, { port: 3000 });
-await init();
+const { app, init } = createBunHandler(config, { port: 3000 });
+
+await init(); // Connects DB, runs migrations, starts server
+// 🚀 Listening on http://localhost:3000
 ```
 
 ---
 
-### Node.js
-
-```typescript
-// src/index.ts
-import { createNodeHandler } from 'opacacms/runtimes/node';
-import config from './opacacms.config';
+## Runtime Handlers
 
-const { init } = createNodeHandler(config, { port: 3000 });
-await init();
-```
+| Runtime                  | Import                                 | Handler                                  |
+| ------------------------ | -------------------------------------- | ---------------------------------------- |
+| **Next.js** (App Router) | `opacacms/runtimes/next`               | `createNextHandler(config)`              |
+| **Bun** (Standalone)     | `opacacms/runtimes/bun`                | `createBunHandler(config, opts)`         |
+| **Cloudflare Workers**   | `opacacms/runtimes/cloudflare-workers` | `createCloudflareWorkersHandler(config)` |
+| **Node.js**              | `opacacms/runtimes/node`               | `createNodeHandler(config)`              |
 
 ---
 
-## CLI Reference
+## 🌟 Why OpacaCMS?
 
-The CLI auto-detects your config at `opacacms.config.ts`, `src/opacacms.config.ts`, or `index.ts`.
+- **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.
+- **Zod Validation**: First-class support for Zod schemas on any field.
+- **Version History**: Full document versioning with one-click restore.
+- **Edge-Ready**: Native Cloudflare D1 + R2 support for global deployments.
 
-```bash
-# Scaffold a new project
-bunx opacacms init my-project
+## Ready to build something awesome? [Let's go!](https://opacacms.com) 🎈
 
-# Generate migrations from your current schema
-bunx opacacms migrate:create <name>
+## 🔌 Next-Gen Plugins
 
-# Apply pending migrations (Postgres / SQLite)
-bunx opacacms migrate
+OpacaCMS features a powerful, hook-based plugin system that allows you to extend the backend (schema, API middleware, routes) and the Admin UI (custom views, isolated dashboards) with full type-safety.
+
+### The `definePlugin` Helper
+
+Use `definePlugin` for a type-safe experience and rich metadata support.
 
-# Check which migrations have been applied
-bunx opacacms migrate:status
+```typescript
+// plugins/my-plugin.ts
+import { definePlugin, html } from 'opacacms';
 
-# Apply SQL migrations to Cloudflare D1
-bunx opacacms migrate:d1 --local   # local dev
-bunx opacacms migrate:d1 --remote  # production
+export const myPlugin = () =>
+  definePlugin({
+    name: 'my-plugin',
+    label: 'Custom Dashboard',
+    description: 'A powerful extension for your CMS.',
+    version: '1.0.0',
+    icon: 'Activity',
 
-# Seed the database with fake data
-bunx opacacms seed --count 50
-bunx opacacms seed:assets --count 20
+    // 1. Hook into Global API Requests
+    onRequest: async (c) => {
+      if (c.req.path.startsWith('/api/secret')) {
+        console.log('Intercepted secret request!');
+      }
+    },
 
-# Generate TypeScript types from a running instance
-bunx opacacms generate:types --url http://localhost:3000 --out opaca-types.d.ts
+    // 2. Add API Routes & UI Assets
+    onRouterInit: (app) => {
+      // Serve the UI Registration Script
+      app.get('/api/plugins/my-plugin/setup.js', (c) => {
+        const js = `
+          // Use the simplified window.opaca helper
+          window.opaca.ui.registerAdminRoute({
+            label: "Plugin Dashboard",
+            icon: "Activity",
+            path: "/admin/my-plugin",
+            render: (serverUrl) => \`
+              <iframe 
+                src="\${serverUrl}/api/plugins/my-plugin/view" 
+                style="width:100%; height:calc(100vh - 100px); border:none;"
+              ></iframe>
+            \`
+          });
+        `;
+        return (c.header('Content-Type', 'application/javascript'), c.body(js));
+      });
+
+      // Serve the Isolated HTML View with Hono/HTML
+      app.get('/api/plugins/my-plugin/view', (c) => {
+        return c.html(html`
+          <body
+            style="background: #f6f9fc; padding: 40px; font-family: sans-serif;"
+          >
+            <h1>Modern Plugin UI</h1>
+            <p>Isolated from CMS styles with zero boilerplate.</p>
+          </body>
+        `);
+      });
+    },
 
-# Use a custom config file path
-bunx opacacms migrate:create --config ./path/to/config.ts
+    // 3. Register Assets
+    adminAssets: () => ({
+      scripts: ['/api/plugins/my-plugin/setup.js'],
+    }),
+  });
 ```
 
----
+### Plugin Lifecycle Hooks
 
-## Production Build
+| Hook             | Description                                                                  |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `onInit`         | Runs during CMS startup. Used to inject collections or modify global config. |
+| `onRequest`      | Global middleware called for EVERY API request. Return `false` to block.     |
+| `onRouterInit`   | Called when the API router is being built. Mount custom Hono routes here.    |
+| `onInitComplete` | Fired once all plugins and core modules are fully initialized.               |
+| `onDestroy`      | Cleanup hook for graceful shutdown.                                          |
+| `onExport`       | Hook for SSG (Static Site Generation) plugins to export custom files.        |
 
-### Disable push mode
+### Global Admin Registry (`window.opaca`)
 
-```typescript
-db: createPostgresAdapter(process.env.DATABASE_URL, {
-  push: false, // never auto-alter schema in production
-});
-```
+Plugins can interact with the Admin UI via the `window.opaca` object:
 
-### Required environment variables
+- `window.opaca.ui.registerAdminRoute(item)`: Simplest way to add a new page to the sidebar.
+- `window.opaca.ui.notify(message, type)`: Show a toast notification.
+- `window.opaca.ui.toggleSidebar()`: Programmatically collapse/expand the menu.
 
-```bash
-OPACA_SECRET=<random-32-char-string>    # required
-DATABASE_URL=postgres://...             # for Postgres
-```
+### Registering the Plugin
 
-### Deploy flow
+Add your plugin to the `plugins` array in `opacacms.config.ts`:
 
-```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
+```typescript
+export default defineConfig({
+  // ...
+  plugins: [myPlugin()],
+});
 ```