@rebasepro/agent-skills 0.7.0 → 0.9.0

package/skills/rebase-security/SKILL.md

@@ -17,7 +17,7 @@ Rebase implements a **multi-layered, defense-in-depth** security architecture. S
 - [Layer 2: API Key Permission Guard](#layer-2-api-key-permission-guard)
 - [Layer 3: DataHooks (API Boundary)](#layer-3-datahooks-api-boundary)
 - [Layer 4: Scoped DataDriver](#layer-4-scoped-datadriver)
-- [Layer 5: Entity Callbacks](#layer-5-entity-callbacks)
+- [Layer 5: Collection Callbacks](#layer-5-collection-callbacks)
 - [Fail-Closed Design](#fail-closed-design)
 - [Securing Without Database RLS](#securing-without-database-rls)
 - [Common Security Patterns](#common-security-patterns)
@@ -61,7 +61,7 @@ Every request — REST, GraphQL, and WebSocket — passes through **5 security l
 └──────────────┬───────────────────────────────────────┘
                │
 ┌──────────────▼───────────────────────────────────────┐
-│  Layer 5: Entity Callbacks (Per-Collection)          │
+│  Layer 5: Collection Callbacks (Per-Collection)      │
 │  beforeSave / afterRead / beforeDelete               │
 │  Per-collection hooks inside the DataDriver          │
 └──────────────────────────────────────────────────────┘
@@ -77,12 +77,12 @@ All three protocols share the same security middleware stack:
 
 ### REST
 ```
-HTTP Request → Auth Middleware → API Key Guard → DataHooks → Scoped Driver → Entity Callbacks → Response
+HTTP Request → Auth Middleware → API Key Guard → DataHooks → Scoped Driver → Collection Callbacks → Response
 ```
 
 ### GraphQL
 ```
-GraphQL Request → Auth Middleware → API Key Guard → Scoped Driver → Entity Callbacks → Response
+GraphQL Request → Auth Middleware → API Key Guard → Scoped Driver → Collection Callbacks → Response
 ```
 GraphQL shares the same Hono middleware chain as REST. Resolvers extract the scoped driver from context and throw if unavailable.
 
@@ -136,6 +136,14 @@ export async function scopeDataDriver(
 | Anonymous (`requireAuth: false`) | `"anon"` | `["anon"]` | RLS with anonymous identity |
 | No token + `requireAuth: true` | — | — | **Rejected (401)** |
 
+> **IMPORTANT FOR AGENTS:** These are **reserved system identity values** that the middleware injects automatically. When writing DataHooks or Collection Callbacks, developers should use these identities to gate behavior:
+> - `uid: "service"` + `roles: ["admin"]` — Server-side `rebase.data` calls (cron jobs, custom functions using `rebase.data`, webhooks). These go through the full middleware pipeline authenticated with the service key.
+> - `uid: "anon"` + `roles: ["anon"]` — Unauthenticated requests when `requireAuth: false`. **Note:** for anonymous REST requests, `context.user` in Collection Callbacks may be `undefined`; only the DataDriver is scoped with the anon identity. For WebSocket connections, a full `User` object with `uid: "anon"` is provided.
+> - `uid: "api-key:{id}"` + `roles: ["service"]` (or `["admin", "service"]`) — API key requests.
+> - Real user IDs and roles for JWT-authenticated requests.
+>
+> **Key insight:** `rebase.data` (the server-side singleton) is NOT a raw admin driver — it round-trips through the REST API using the service key, so all DataHooks and Collection Callbacks fire with `uid: "service"`, `roles: ["admin"]`. This means callbacks can distinguish server-internal reads from end-user reads by checking `context.user?.roles?.includes("admin")`.
+
 ---
 
 ## Layer 2: API Key Permission Guard
@@ -239,9 +247,9 @@ interface BackendHookContext {
 
 ### Execution Order
 
-DataHooks run **after** per-collection `EntityCallbacks` (which execute inside the DataDriver, closer to the database) and **before** the API response is sent to the client. This gives you two opportunities to enforce security:
+DataHooks run **after** per-collection `CollectionCallbacks` (which execute inside the DataDriver, closer to the database) and **before** the API response is sent to the client. This gives you two opportunities to enforce security:
 
-1. **EntityCallbacks** — per-collection, inside the driver
+1. **CollectionCallbacks** — per-collection, inside the driver
 2. **DataHooks** — cross-cutting, at the API boundary
 
 ---
@@ -263,12 +271,12 @@ PostgreSQL RLS policies use `auth.uid()`, `auth.roles()`, and `auth.jwt()` to re
 
 ---
 
-## Layer 5: Entity Callbacks
+## Layer 5: Collection Callbacks
 
-Entity callbacks are per-collection lifecycle hooks that run **inside** the DataDriver, close to the database. They provide collection-specific security enforcement:
+Collection callbacks are per-collection lifecycle hooks that run **inside** the DataDriver, close to the database. They provide collection-specific security enforcement:
 
 ```typescript
-const ordersCollection: PostgresCollection = {
+const ordersCollection: PostgresCollectionConfig = {
     name: "Orders",
     slug: "orders",
     table: "orders",
@@ -281,9 +289,9 @@ const ordersCollection: PostgresCollection = {
             }
             return values;
         },
-        beforeDelete: async ({ entity, context }) => {
+        beforeDelete: async ({ row, context }) => {
             // Prevent deletion of fulfilled orders
-            if (entity.values.status === "fulfilled") {
+            if (row.status === "fulfilled") {
                 throw new Error("Cannot delete fulfilled orders");
             }
         },
@@ -292,7 +300,7 @@ const ordersCollection: PostgresCollection = {
 };
 ```
 
-For full documentation on entity callbacks, see the `rebase-collections` skill.
+For full documentation on collection callbacks, see the `rebase-collections` skill.
 
 ---
 
@@ -319,7 +327,7 @@ Rebase follows a **fail-closed** security model throughout the stack:
 
 ## Securing Without Database RLS
 
-If you cannot modify database-level RLS policies — or your database doesn't support them — use **DataHooks** and **Entity Callbacks** to enforce security entirely at the application level.
+If you cannot modify database-level RLS policies — or your database doesn't support them — use **DataHooks** and **Collection Callbacks** to enforce security entirely at the application level.
 
 ### Strategy: DataHooks as Your Security Layer
 
@@ -376,7 +384,7 @@ const hooks: BackendHooks = {
 
             if (!user.roles.includes("admin")) {
                 // For non-admins, you may need to fetch the entity first
-                // to verify ownership. Use Entity Callbacks for this pattern
+                // to verify ownership. Use Collection Callbacks for this pattern
                 // since they receive the full entity.
                 throw ApiError.forbidden("Only admins can delete records");
             }
@@ -385,40 +393,40 @@ const hooks: BackendHooks = {
 };
 ```
 
-### Strategy: Entity Callbacks for Ownership Checks
+### Strategy: Collection Callbacks for Ownership Checks
 
-Entity Callbacks receive the full entity data, making them ideal for ownership verification on deletes and updates:
+Collection Callbacks receive the full entity data, making them ideal for ownership verification on deletes and updates:
 
 ```typescript
-const ordersCollection: PostgresCollection = {
+const ordersCollection: PostgresCollectionConfig = {
     name: "Orders",
     slug: "orders",
     table: "orders",
     callbacks: {
-        beforeSave: async ({ values, entityId, context, previousValues }) => {
+        beforeSave: async ({ values, id, context, previousValues }) => {
             const user = context.user;
             if (!user) throw new Error("Unauthorized");
 
             // On update, verify the current user owns this order
-            if (entityId && previousValues) {
+            if (id && previousValues) {
                 if (previousValues.user_id !== user.uid && !user.roles?.includes("admin")) {
                     throw new Error("You can only edit your own orders");
                 }
             }
 
             // On create, stamp ownership
-            if (!entityId) {
+            if (!id) {
                 values.user_id = user.uid;
             }
 
             return values;
         },
 
-        beforeDelete: async ({ entity, context }) => {
+        beforeDelete: async ({ row, context }) => {
             const user = context.user;
             if (!user) throw new Error("Unauthorized");
 
-            if (entity.values.user_id !== user.uid && !user.roles?.includes("admin")) {
+            if (row.user_id !== user.uid && !user.roles?.includes("admin")) {
                 throw new Error("You can only delete your own orders");
             }
         },
@@ -429,15 +437,15 @@ const ordersCollection: PostgresCollection = {
 
 ### Combining Both Layers
 
-For maximum security, use both DataHooks and Entity Callbacks together:
+For maximum security, use both DataHooks and Collection Callbacks together:
 
 | Concern | Best Layer | Why |
 |---|---|---|
 | Cross-cutting read filtering | DataHooks `afterRead` | Applies to ALL collections in one place |
 | Cross-cutting write validation | DataHooks `beforeSave` | Single enforcement point for all writes |
 | PII masking / field redaction | DataHooks `afterRead` | Cross-cutting, role-based |
-| Ownership checks on writes/deletes | Entity Callbacks | Has access to the full entity for comparison |
-| Business rule validation | Entity Callbacks | Collection-specific, typed values |
+| Ownership checks on writes/deletes | Collection Callbacks | Has access to the full entity for comparison |
+| Business rule validation | Collection Callbacks | Collection-specific, typed values |
 | Audit logging | DataHooks `afterSave` / `afterDelete` | Cross-cutting, fire-and-forget |
 
 ---
@@ -495,13 +503,44 @@ const hooks: BackendHooks = {
         },
 
         beforeDelete(slug, entityId, ctx) {
-            // Tenant isolation on deletes is best handled in Entity Callbacks
+            // Tenant isolation on deletes is best handled in Collection Callbacks
             // where you have access to the entity's tenant_id
         },
     },
 };
 ```
 
+### Membership-Scoped Access (RLS, no N+1)
+
+When membership lives in a **join collection** (e.g. `team_members`), prefer the
+first-class `policy.existsIn` predicate over a per-row `afterRead` lookup. It is
+enforced by Postgres RLS in a single correlated `EXISTS` subquery — no N+1, and
+it cannot be bypassed by a client that skips the SDK.
+
+```typescript
+import { policy } from "@rebasepro/types";
+
+// config/collections/documents.ts — only members of the doc's team can read it:
+securityRules: [
+    {
+        operation: "select",
+        condition: policy.existsIn({
+            collection: "team_members",
+            where: policy.and(
+                policy.compare(policy.field("team_id"), "eq", policy.outerField("team_id")),
+                policy.compare(policy.field("user_id"), "eq", policy.authUid()),
+            ),
+        }),
+    },
+]
+```
+
+Inside `where`: `policy.field(...)` = a column of the joined collection
+(`team_members`); `policy.outerField(...)` = a column of the row being checked
+(`documents`); `policy.authUid()` = the caller. Reach for the `afterRead`
+approach above only when access depends on data RLS can't see (e.g. an external
+service). Run `rebase db push` after editing the collection to apply the policy.
+
 ### Role-Based Collection Access
 
 ```typescript
@@ -585,7 +624,7 @@ Use this checklist when setting up security for a Rebase project:
 - [ ] **Default role is NOT admin** — `auth.defaultRole` must never be `"admin"` (startup error)
 - [ ] **DataHooks enforce access control** — If not using database RLS, `hooks.data` enforces read/write/delete permissions
 - [ ] **Sensitive fields are masked** — `afterRead` masks PII for non-admin users
-- [ ] **Ownership is enforced** — `beforeSave` stamps `user_id` on creation; Entity Callbacks verify ownership on update/delete
+- [ ] **Ownership is enforced** — `beforeSave` stamps `user_id` on creation; Collection Callbacks verify ownership on update/delete
 - [ ] **API keys are scoped** — API keys have minimal permissions (specific collections + operations)
 - [ ] **API keys are never client-side** — API keys bypass RLS; only use server-side
 - [ ] **CORS is configured** — Restrict origins in production
@@ -602,5 +641,6 @@ Use this checklist when setting up security for a Rebase project:
 - **REST API Generator**: `packages/server-core/src/api/rest/api-generator.ts` — DataHooks integration
 - **Backend Hooks Types**: `packages/types/src/types/backend_hooks.ts` — `DataHooks`, `BackendHooks` interfaces
 - **Backend Init**: `packages/server-core/src/init.ts` — `hooks` config property
-- **Entity Callbacks**: See `rebase-collections` skill → Entity Callbacks section
+- **Reserved Identity Values**: See Identity Types table above — `"service"`, `"anon"`, `"api-key:{id}"` are system-assigned identities in `context.user` / `ctx.requestUser`
+- **Collection Callbacks**: See `rebase-collections` skill → Collection Callbacks section
 - **Auth Configuration**: See `rebase-auth` skill → Server-Side Configuration section

package/skills/rebase-storage/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: rebase-storage
-description: Guide for setting up and using file storage in Rebase. Use this skill when the user needs to configure S3 or local file storage, handle file uploads, TUS resumable uploads, image transformations, or integrate the media manager.
+description: Guide for setting up and using file storage in Rebase. Use this skill when the user needs to configure S3, Google Cloud Storage (GCS), or local file storage, handle file uploads, TUS resumable uploads, image transformations, multi-backend frontend storage sources, or integrate the media manager.
 ---
 
 # Rebase Storage
 
-Rebase provides built-in file storage with support for local filesystem and S3-compatible services, TUS v1.0.0 resumable uploads, on-the-fly image transformation, and a multi-backend registry.
+Rebase provides built-in file storage with support for local filesystem, S3-compatible services, and Google Cloud Storage (GCS), TUS v1.0.0 resumable uploads, on-the-fly image transformation, a multi-backend registry, and frontend storage sources.
 
 > **IMPORTANT FOR AGENTS:** Always read the `rebase-basics` skill first before using this skill. Storage requires a running Rebase backend with `initializeRebaseBackend()`.
 
@@ -15,7 +15,7 @@ The `storage` option in `initializeRebaseBackend()` accepts three forms:
 
 | Form | Type | Description |
 |------|------|-------------|
-| Single config | `BackendStorageConfig` | `{ type: 'local' | 's3', ... }` — creates a single `(default)` backend |
+| Single config | `BackendStorageConfig` | `{ type: 'local' | 's3' | 'gcs', ... }` — creates a single `(default)` backend |
 | Single controller | `StorageController` | A custom controller instance — registered as `(default)` |
 | Multi-backend map | `Record<string, BackendStorageConfig \| StorageController>` | Named backends, first becomes `(default)` if no `(default)` key |
 
@@ -44,6 +44,19 @@ The `storage` option in `initializeRebaseBackend()` accepts three forms:
 | `allowedMimeTypes` | `string[]` | `undefined` (all allowed) | Restrict uploads to these MIME types |
 | `signedUrlExpiration` | `number` | `3600` | Signed URL expiry in seconds |
 
+### GCSStorageConfig
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `"gcs"` | — | **Required.** Must be `"gcs"` |
+| `bucket` | `string` | — | **Required.** GCS bucket name |
+| `projectId` | `string` | `undefined` | Google Cloud project ID (auto-detected from credentials if omitted) |
+| `maxFileSize` | `number` | `52428800` (50 MB) | Maximum file size in bytes |
+| `allowedMimeTypes` | `string[]` | `undefined` (all allowed) | Restrict uploads to these MIME types |
+| `signedUrlExpiration` | `number` | `3600` | Signed URL expiry in seconds |
+
+> **IMPORTANT FOR AGENTS:** GCS requires `@google-cloud/storage` as a peer dependency. Install it: `pnpm add @google-cloud/storage`. Authentication uses Application Default Credentials — set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to point to a service account key file, or rely on the default credentials when running on GCP.
+
 ### StorageRoutesConfig
 
 These options are set internally when mounting routes but are derived from the backend config:
@@ -93,7 +106,7 @@ Local storage includes **path traversal protection** — any resolved path that
 
 ### S3-Compatible Storage
 
-Works with AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, Hetzner Object Storage, Backblaze B2, and any S3-compatible service. GCS also works via its S3-compatible interoperability API.
+Works with AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, Hetzner Object Storage, Backblaze B2, and any S3-compatible service.
 
 ```typescript
 const backend = await initializeRebaseBackend({
@@ -118,6 +131,28 @@ The S3 controller:
 - Supports `s3://` and `gs://` URL schemes in key parameters for backward compatibility
 - Flattens nested metadata to string values (S3 requirement)
 
+### Google Cloud Storage (GCS)
+Native Google Cloud Storage support via the `@google-cloud/storage` SDK. This is the preferred approach for GCS — no S3 interop layer needed. (Also works with Firebase Storage buckets, which are GCS buckets under the hood).
+
+```typescript
+const backend = await initializeRebaseBackend({
+    server, app,
+    bootstrappers: [/* ... */],
+    storage: {
+        type: "gcs",
+        bucket: process.env.GCS_BUCKET!,
+        projectId: process.env.GCS_PROJECT_ID, // optional, auto-detected on GCP
+    },
+});
+```
+
+The GCS controller:
+- Uses `@google-cloud/storage` natively (no S3 interop overhead)
+- Authenticates via Application Default Credentials (`GOOGLE_APPLICATION_CREDENTIALS`)
+- Maps the logical bucket name `"default"` to the configured GCS bucket
+- Supports `gs://` URL scheme in key parameters
+- Generates signed URLs using GCS's native signed URL mechanism
+
 ### Multiple Storage Backends
 
 Rebase supports multiple storage backends simultaneously via the `StorageRegistry`:
@@ -138,7 +173,7 @@ const backend = await initializeRebaseBackend({
 });
 ```
 
-> **IMPORTANT FOR AGENTS:** If no `"(default)"` key is provided, the first entry is automatically registered as the default (with a console warning). The REST API routes always use the default controller. Use `storageRegistry.get("media")` or `storageRegistry.getOrDefault("media")` to access named backends programmatically.
+> **IMPORTANT FOR AGENTS:** If no `"(default)"` key is provided, the first entry is automatically registered as the default (with a console warning). The REST API routes use the default controller unless a `?storageId=<key>` query parameter is provided (see [REST API Endpoints](#rest-api-endpoints)). Use `storageRegistry.get("media")` or `storageRegistry.getOrDefault("media")` to access named backends programmatically.
 
 ### StorageRegistry API
 
@@ -156,7 +191,7 @@ The `StorageRegistry` interface:
 
 ### Custom Storage Providers
 
-Implement the `StorageController` interface for unsupported providers (Azure Blob, native GCS SDK, etc.):
+GCS is now built-in (see [Google Cloud Storage (GCS)](#google-cloud-storage-gcs)). Implement the `StorageController` interface for other unsupported providers (Azure Blob, etc.):
 
 ```typescript
 interface StorageController {
@@ -185,7 +220,7 @@ The backend validates storage-related environment variables via a Zod schema:
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `STORAGE_TYPE` | `"local" \| "s3"` | `"local"` | Storage provider type |
+| `STORAGE_TYPE` | `"local" \| "s3" \| "gcs"` | `"local"` | Storage provider type |
 | `STORAGE_PATH` | `string` | `"./uploads"` | Base path for local storage / TUS temp directory |
 | `FORCE_LOCAL_STORAGE` | `"true" \| "false"` | `false` | Suppress the production warning for local storage |
 | `S3_BUCKET` | `string` | — | S3 bucket name |
@@ -194,8 +229,12 @@ The backend validates storage-related environment variables via a Zod schema:
 | `S3_SECRET_ACCESS_KEY` | `string` | — | S3 secret access key |
 | `S3_ENDPOINT` | `string` (URL) | — | Custom S3-compatible endpoint |
 | `S3_FORCE_PATH_STYLE` | `"true" \| "false"` | — | Enable path-style URLs |
+| `GCS_BUCKET` | `string` | — | GCS bucket name |
+| `GCS_PROJECT_ID` | `string` | — | Google Cloud project ID (auto-detected on GCP) |
+| `GOOGLE_APPLICATION_CREDENTIALS` | `string` (path) | — | Path to GCP service account key JSON file |
 
 ```env
+# S3 example
 STORAGE_TYPE=s3
 S3_BUCKET=my-bucket
 S3_REGION=us-east-1
@@ -203,12 +242,35 @@ S3_ACCESS_KEY_ID=AKIA...
 S3_SECRET_ACCESS_KEY=...
 S3_ENDPOINT=https://minio.example.com    # Optional: for MinIO, R2, etc.
 S3_FORCE_PATH_STYLE=true                 # Optional: for MinIO
+
+# GCS example
+STORAGE_TYPE=gcs
+GCS_BUCKET=my-gcs-bucket
+GCS_PROJECT_ID=my-gcp-project             # Optional: auto-detected on GCP
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
 ```
 
 ## REST API Endpoints
 
 All storage routes are mounted at `/api/storage` by default. Write operations require authentication when `requireAuth` is `true` (the default). Read operations also require authentication unless `publicRead` is `true`.
 
+### Multi-Backend Routing (`storageId`)
+
+All storage endpoints accept a `?storageId=<key>` query parameter that routes the request to a specific named backend in the `StorageRegistry`. For multipart uploads (`POST /api/storage/upload`), the `storageId` can also be sent as a form field.
+
+If `storageId` is omitted, the request is routed to the `(default)` backend.
+
+```
+# Upload to the "media" backend
+POST /api/storage/upload?storageId=media
+
+# Download from the "media" backend
+GET /api/storage/file/images/photo.jpg?storageId=media
+
+# List files in the "media" backend
+GET /api/storage/list?prefix=images/&storageId=media
+```
+
 ### Standard Endpoints
 
 | Method | Endpoint | Auth | Description |
@@ -241,6 +303,7 @@ Upload a file via `multipart/form-data`.
 | `file` | `File` | Yes | The file to upload |
 | `key` | `string` | No | Storage key/path. Falls back to original filename, then `"unnamed"` |
 | `bucket` | `string` | No | Target bucket name |
+| `storageId` | `string` | No | Route to a named backend (alternative to `?storageId` query param) |
 | `metadata_*` | `string` | No | Custom metadata keys prefixed with `metadata_` |
 
 **Response** (201):
@@ -562,6 +625,24 @@ Transformed responses include `Cache-Control: public, max-age=31536000, immutabl
 
 The `@rebasepro/client` package provides a `StorageSource` interface via `createStorage(transport)`. These methods are available on `client.storage` (or through the React/Studio hooks).
 
+All SDK methods accept an optional `storageId` parameter (passed as a query parameter) to route the request to a specific named backend:
+
+```typescript
+// Upload to a specific backend
+const result = await client.storage.putObject({
+    file: myFile,
+    key: "products/images/photo.jpg",
+    storageId: "media",   // routes to the "media" backend
+});
+
+// Get signed URL from a specific backend
+const config = await client.storage.getSignedUrl(
+    "products/images/photo.jpg",
+    "default",     // bucket
+    { storageId: "media" }
+);
+```
+
 ### putObject
 
 Upload a file.
@@ -591,12 +672,15 @@ const config = await client.storage.getSignedUrl(
 if (config.fileNotFound) {
     console.log("File does not exist");
 } else {
-    console.log(config.url);       // Full URL with auth token appended
+    console.log(config.url);       // Private: short-lived scoped token appended. Public: clean permanent URL.
     console.log(config.metadata);  // { bucket, fullPath, name, size, contentType, customMetadata }
 }
 ```
 
-The URL is constructed as `{baseUrl}/api/storage/file/{path}?token={accessToken}`.
+**URL model — never contains the access token:**
+
+- **Private files** → `{baseUrl}/api/storage/file/{path}?token={scopedDownloadToken}`. The token is a **short-lived, path-scoped** download token (default 5 min), signed by the server and valid only for that object — never the caller's full access JWT. Because it expires, **do not persist a private URL**: store the file **path** and call `getSignedUrl()` again at render time.
+- **Public files** → `{baseUrl}/api/storage/file/{path}` with **no token**. A file is public when it lives under the `public/` prefix — set `storage: { public: true }` on the property, or pass `public: true` to `putObject`. Public URLs are **stable, permanent, and CDN-cacheable**, so they are safe to store in a database and hotlink. For public paths, `getSignedUrl()` returns the URL immediately with no server round-trip.
 
 Protocol prefixes (`local://`, `s3://`) are automatically stripped from the key.
 
@@ -652,9 +736,9 @@ console.log(result.nextPageToken); // for next page, or undefined
 Define file upload fields in your collections using the `storage` option on string properties:
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const productsCollection: PostgresCollection = {
+const productsCollection: PostgresCollectionConfig = {
     name: "Products",
     table: "products",
     properties: {
@@ -662,7 +746,8 @@ const productsCollection: PostgresCollection = {
             name: "Product Image",
             type: "string",
             storage: {
-                storagePath: "products/images",
+                storageSource: "external-source",
+                storagePath: "products/{entityId}",
                 acceptedFiles: ["image/*"],
                 maxSize: 5 * 1024 * 1024, // 5MB
             }
@@ -673,6 +758,7 @@ const productsCollection: PostgresCollection = {
             of: {
                 type: "string",
                 storage: {
+                    storageSource: "media",              // routes to the "media" backend
                     storagePath: "products/documents",
                     acceptedFiles: ["application/pdf", "application/msword"],
                 }
@@ -682,6 +768,88 @@ const productsCollection: PostgresCollection = {
 };
 ```
 
+The `storageSource` field maps to a named backend registered in the `StorageRegistry` (server-side) or in the `storageSources` prop (client-side). When omitted, the `(default)` backend is used.
+
+### StorageConfig Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `storageSource` | `string` | Named backend to route uploads to (optional, defaults to `(default)`) |
+| `storagePath` | `string` | Path template for uploaded files. Supports `{entityId}` placeholder |
+| `acceptedFiles` | `string[]` | Accepted MIME types or globs (e.g., `["image/*"]`) |
+| `maxSize` | `number` | Maximum file size in bytes |
+| `public` | `boolean` | Store files under the `public/` prefix and serve them via stable, token-less, permanent, CDN-cacheable URLs (safe to persist/hotlink). Defaults to `false` (private, short-lived signed URLs). |
+
+## Frontend Storage Sources
+
+The `<Rebase>` component accepts a `storageSources` prop to register client-side storage sources, following the same pattern as `dataSources` for databases. This enables **direct** (client-to-provider) file operations, bypassing the Rebase backend.
+
+### Registering Storage Sources
+
+```tsx
+import type { RebaseStorageSource } from "@rebasepro/core";
+import { myExternalStorageSource } from "./my-external-storage";
+
+<Rebase
+    client={rebaseClient}
+    storageSources={[
+        {
+            key: "external",
+            engine: "external",
+            transport: "direct",
+            source: myExternalStorageSource,
+        },
+        {
+            key: "media",
+            engine: "s3",
+            transport: "server",   // proxied through the Rebase backend
+            label: "Media Storage",
+        },
+    ]}
+>
+    {children}
+</Rebase>
+```
+
+### StorageSourceDefinition
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `string` | **Required.** Unique identifier for this storage source |
+| `engine` | `string` | **Required.** Storage engine type (e.g., `"firebase"`, `"s3"`, `"gcs"`, `"local"`) |
+| `transport` | `"server" \| "direct"` | **Required.** `"server"` routes through the backend; `"direct"` talks to the provider from the client |
+| `source` | `StorageSource` | The client-side `StorageSource` implementation (required when `transport` is `"direct"`) |
+| `label` | `string` | Optional human-readable label for the UI |
+
+### StorageSourcesContext
+
+Registered storage sources are exposed to the component tree via `StorageSourcesContext`, mirroring the `DataSourcesContext` pattern:
+
+```typescript
+import { useStorageSources } from "@rebasepro/core";
+
+function MyUploadComponent() {
+    const storageSources = useStorageSources();
+
+    // Get a specific source
+    const externalSource = storageSources.find(s => s.key === "external");
+
+    // Use it for direct uploads
+    if (externalSource?.source) {
+        await externalSource.source.putObject({ file, key: "photos/image.jpg" });
+    }
+}
+```
+
+### Direct vs Server Transport
+
+| Transport | Description | Use Case |
+|-----------|-------------|----------|
+| `"server"` | File operations are proxied through the Rebase backend REST API | S3, GCS, or local backends managed by the server |
+| `"direct"` | File operations go directly from the client to the storage provider | External cloud storage, or any provider with client-side SDKs |
+
+> **IMPORTANT FOR AGENTS:** Direct transport sources must provide a `source` property implementing the `StorageSource` interface. Server transport sources use the built-in SDK transport and only need `key` and `engine`.
+
 ## Storage Browser (Studio)
 
 The `@rebasepro/studio` package includes a built-in `StorageView` component:

package/skills/rebase-studio/SKILL.md

@@ -256,8 +256,8 @@ These components can be overridden globally on `<Rebase>` (which acts as a fallb
 `<RebaseCMS>` accepts the full `RebaseCMSConfig`:
 
 ```typescript
-interface RebaseCMSConfig<EC extends EntityCollection = EntityCollection> {
-    collections?: EC[] | EntityCollectionsBuilder<EC>;
+interface RebaseCMSConfig<EC extends CollectionConfig = CollectionConfig> {
+    collections?: EC[] | CollectionConfigsBuilder<EC>;
     views?: AppView[] | AppViewsBuilder;
     homePage?: ReactNode;
     entityViews?: EntityCustomView[];
@@ -464,7 +464,7 @@ type CollectionPanelProps = {
     updateUrl?: boolean;                    // Sync filter/sort with URL (default: false)
     openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
     className?: string;                     // Container CSS class
-    collectionOverrides?: Partial<EntityCollection>; // Additional overrides
+    collectionOverrides?: Partial<CollectionConfig>; // Additional overrides
 };
 ```
 
@@ -512,7 +512,7 @@ The Studio Bridge provides CMS capabilities to Studio components. When CMS is pr
 ```typescript
 interface StudioBridge {
     collectionRegistry: CollectionRegistryController;
-    sideEntityController: SideEntityController;
+    sideEntityController: SidePanelController;
     urlController: UrlController;
     navigationState: NavigationStateController;
     breadcrumbs: BreadcrumbsController;
@@ -524,7 +524,7 @@ interface StudioBridge {
 | Hook | Return Type | Description |
 |------|-------------|-------------|
 | `useStudioCollectionRegistry()` | `CollectionRegistryController` | Access registered collections from Studio |
-| `useStudioSideEntityController()` | `SideEntityController` | Open/close entity side panels from Studio |
+| `useStudioSidePanelController()` | `SidePanelController` | Open/close entity side panels from Studio |
 | `useStudioUrlController()` | `UrlController` | Build URLs and navigate from Studio |
 | `useStudioNavigationState()` | `NavigationStateController` | Access navigation state from Studio |
 | `useStudioBreadcrumbs()` | `BreadcrumbsController` | Set breadcrumbs from Studio tools |
@@ -534,7 +534,7 @@ All bridge hooks are exported from `@rebasepro/studio` (re-exported from `@rebas
 ```typescript
 import {
     useStudioCollectionRegistry,
-    useStudioSideEntityController,
+    useStudioSidePanelController,
     useStudioUrlController,
     useStudioNavigationState,
     useStudioBreadcrumbs
@@ -567,7 +567,7 @@ import { StudioBridgeProvider } from "@rebasepro/studio";
 
 <StudioBridgeProvider value={{
     collectionRegistry: useCollectionRegistryController(),
-    sideEntityController: useSideEntityController(),
+    sideEntityController: useSidePanel(),
     urlController: useUrlController(),
     navigationState: useNavigationStateController(),
     breadcrumbs: useBreadcrumbsController(),
@@ -610,7 +610,7 @@ These hooks are exported from `@rebasepro/core` and available inside any `<Rebas
 
 | Hook | Package | Description |
 |------|---------|-------------|
-| `useSideEntityController()` | `@rebasepro/admin` | Open/close entity side panels |
+| `useSidePanel()` | `@rebasepro/admin` | Open/close entity side panels |
 | `useNavigationStateController()` | `@rebasepro/admin` | Navigate between views |
 | `useUrlController()` | `@rebasepro/admin` | Build URLs and navigate |
 | `useBreadcrumbsController()` | `@rebasepro/admin` | Set breadcrumbs |