@rebasepro/agent-skills 0.7.0 → 0.9.0

package/skills/rebase-collections/SKILL.md

@@ -11,7 +11,7 @@ Rebase collections are the core building blocks of your data model. They define
 
 ### Collections
 
-A collection is defined as a TypeScript object implementing the `PostgresCollection` interface from `@rebasepro/types`. Each collection maps to a database table (via the `table` property) and generates:
+A collection is defined as a TypeScript object implementing the `PostgresCollectionConfig` interface from `@rebasepro/types`. Each collection maps to a database table (via the `table` property) and generates:
 - Full CRUD REST endpoints at `/api/data/{slug}`
 - Optional GraphQL queries and mutations
 - Admin panel views (table, forms, cards, kanban, list)
@@ -44,7 +44,7 @@ Properties define the fields of your collection. Rebase supports these built-in
 | Junction tables | Yes (many-to-many) | No |
 | Multi-hop joins | Yes (`joinPath`) | No |
 | Inverse lookups | Yes (`direction: "inverse"`) | No |
-| Where to use | **PostgresCollection** | FirebaseCollection or legacy |
+| Where to use | **PostgresCollectionConfig** | FirebaseCollectionConfig or legacy |
 | Stored value | FK column(s) managed by framework | `{ id, path }` object or string |
 
 **Use `relation` for all new Postgres collections.** The `reference` type exists for backward compatibility with Firestore-style collections.
@@ -58,9 +58,9 @@ Collections are defined as standalone TypeScript files under `config/collections
 ## Defining a Collection
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const productsCollection: PostgresCollection = {
+const productsCollection: PostgresCollectionConfig = {
     name: "Products",
     singularName: "Product",
     slug: "products",
@@ -178,10 +178,10 @@ export default productsCollection;
 | `additionalFields` | `AdditionalFieldDelegate[]` | — | Virtual computed columns for views |
 | `entityActions` | `EntityAction[]` | — | Custom action buttons (see Entity Actions section) |
 | `Actions` | `ComponentRef[]` | — | Custom toolbar action components |
-| `callbacks` | `EntityCallbacks<M, USER>` | — | Lifecycle hooks (see Entity Callbacks section) |
+| `callbacks` | `CollectionCallbacks<M, USER>` | — | Lifecycle hooks (see Collection Callbacks section) |
 | `relations` | `Relation[]` | — | Explicit relation definitions (usually auto-extracted from properties) |
 | `securityRules` | `SecurityRule[]` | — | Row Level Security policies |
-| `childCollections` | `() => EntityCollection[]` | — | Nested child collections (populated automatically) |
+| `childCollections` | `() => CollectionConfig[]` | — | Nested child collections (populated automatically) |
 | `overrides` | `EntityOverrides` | — | Override data source or storage source |
 | `ownerId` | `string` | — | Owner user ID (for plugins/custom code) |
 | `auth` | `boolean | AuthCollectionConfig` | — | Mark collection as authentication collection (user management, reset password, etc.) |
@@ -367,6 +367,23 @@ avatar: {
 | `postProcess` | `(pathOrUrl) => Promise<string>` | — | Transform saved path/URL after upload |
 | `includeBucketUrl` | `boolean` | `false` | Include bucket URL in saved path |
 | `storeUrl` | `boolean` | `false` | Save download URL instead of storage path |
+| `storageSource` | `string` | `undefined` (default backend) | Named storage source key — routes uploads to a specific backend registered in the backend `storage` map or in `storageSources` on `<Rebase>`. Must match a `StorageSourceDefinition.key`. |
+
+#### Per-Property Backend Binding
+
+When using multiple storage backends, use `storageSource` to route a specific property's uploads to a named backend:
+
+```typescript
+// Route this property's uploads to Firebase Storage
+image: {
+    type: "string",
+    storage: {
+        storageSource: "firebase",
+        storagePath: "products/{entityId}",
+        acceptedFiles: ["image/*"],
+    }
+}
+```
 
 ### ImageResize Options
 
@@ -693,10 +710,10 @@ Relations are defined **directly on the property** using `type: "relation"`. The
 ### Many-to-One (Owning)
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 import authorsCollection from "./authors";
 
-const postsCollection: PostgresCollection = {
+const postsCollection: PostgresCollectionConfig = {
     name: "Posts",
     slug: "posts",
     table: "posts",
@@ -745,7 +762,7 @@ comments: {
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `target` | `string \| (() => EntityCollection \| string)` | — | Target collection (use a function for lazy resolution to avoid circular imports) |
+| `target` | `string \| (() => CollectionConfig \| string)` | — | Target collection (use a function for lazy resolution to avoid circular imports) |
 | `cardinality` | `"one" \| "many"` | `"one"` | Whether this references one or many records |
 | `direction` | `"owning" \| "inverse"` | `"owning"` | Which side owns the FK or junction table |
 | `localKey` | `string` | auto-inferred | Column on THIS table storing the FK (e.g. `"author_id"`) |
@@ -756,7 +773,7 @@ comments: {
 | `inverseRelationName` | `string` | — | Name of the corresponding relation on the target collection |
 | `onDelete` | `OnAction` | — | Cascade rule on delete |
 | `onUpdate` | `OnAction` | — | Cascade rule on update |
-| `overrides` | `Partial<EntityCollection>` | — | Override target collection config when rendered as subcollection tab |
+| `overrides` | `Partial<CollectionConfig>` | — | Override target collection config when rendered as subcollection tab |
 | `fixedFilter` | `FilterValues` | — | Filter applied when selecting related entities |
 | `includeId` | `boolean` | `true` | Show entity ID in the reference preview |
 | `includeEntityLink` | `boolean` | `true` | Show link to open the related entity |
@@ -847,13 +864,13 @@ customer: {
 
 > **See full documentation:** [Relations](https://rebase.pro/docs/collections/relations)
 
-## Entity Callbacks (Lifecycle Hooks)
+## Collection Callbacks (Lifecycle Hooks)
 
 > **IMPORTANT FOR AGENTS**: Collections support **lifecycle callbacks** that let you run custom logic when entities are created, updated, read, or deleted. Use these to **sync data between collections**, transform data, validate business rules, or trigger side effects. **Do NOT use raw SQL triggers, cron jobs, or external scripts** when a callback can solve the problem.
 
 ### Generic Type Parameters
 
-`EntityCallbacks<M, USER>` accepts two generic type parameters:
+`CollectionCallbacks<M, USER>` accepts two generic type parameters:
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
@@ -861,7 +878,7 @@ customer: {
 | `USER` | `User` | User type — extends the base `User` type with custom fields |
 
 ```typescript
-import { PostgresCollection, EntityCallbacks } from "@rebasepro/types";
+import { PostgresCollectionConfig, CollectionCallbacks } from "@rebasepro/types";
 
 interface Product {
     name: string;
@@ -870,7 +887,7 @@ interface Product {
     status: string;
 }
 
-const callbacks: EntityCallbacks<Product> = {
+const callbacks: CollectionCallbacks<Product> = {
     beforeSave: async ({ values, status }) => {
         // `values` is typed as Partial<Product>
         if (values.name) {
@@ -892,12 +909,36 @@ All callbacks receive a `context` property of type `RebaseCallContext<USER>`. Th
 | `context.storageSource` | `StorageSource` | File storage operations |
 | `context.user` | `USER \| undefined` | Authenticated user (set by backend in server-side callbacks) |
 
+### Reserved `context.user` Values
+
+The `context.user` object is populated by the auth middleware. In server-side callbacks, it contains one of these reserved identities:
+
+| Caller | `context.user.uid` | `context.user.roles` |
+|---|---|---|
+| JWT-authenticated end-user | Real user ID (e.g. `"abc123"`) | Their assigned roles (e.g. `["viewer"]`) |
+| Server-side `rebase.data` (cron jobs, custom functions) | `"service"` | `["admin"]` |
+| API key (default) | `"api-key:{id}"` | `["service"]` |
+| API key (admin) | `"api-key:{id}"` | `["admin", "service"]` |
+| Anonymous (no auth, `requireAuth: false`) | `"anon"` | `["anon"]` |
+| Anonymous REST (no token) | `undefined` | N/A — `context.user` is not set; only the DataDriver is scoped |
+
+> **IMPORTANT FOR AGENTS:** `rebase.data` calls (used in cron jobs, afterSave side-effects, custom functions) go through the full middleware pipeline with the service key, so callbacks see `uid: "service"`, `roles: ["admin"]`. Use this to gate behavior — e.g., skip PII masking for admin/service reads:
+>
+> ```typescript
+> afterRead: async ({ row, context }) => {
+>     // Server-side reads (cron jobs, admin) see real values
+>     if (context.user?.roles?.includes("admin")) return row;
+>     // End-user reads get masked values
+>     return { ...row, email: "***@***.***" };
+> }
+> ```
+
 > **WARNING FOR AGENTS:** Do NOT confuse `RebaseCallContext` (available in callbacks, both client & server) with `RebaseContext` (full context available only on the frontend, includes `authController`, `snackbarController`, `sideEntityController`, etc.). Entity callbacks always receive `RebaseCallContext`.
 
 ### Callback Example
 
 ```typescript
-const jobSubmissionsCollection: PostgresCollection = {
+const jobSubmissionsCollection: PostgresCollectionConfig = {
     name: "Job Submissions",
     slug: "job_submissions",
     table: "job_submissions",
@@ -914,38 +955,35 @@ const jobSubmissionsCollection: PostgresCollection = {
         },
 
         // Runs AFTER saving — trigger side effects, sync other collections
-        afterSave: async ({ values, entityId, previousValues, context }) => {
+        afterSave: async ({ values, id, previousValues, context }) => {
             if (values.status === "approved" && previousValues?.status !== "approved") {
                 await context.data.jobs.create({
                     title: values.title,
                     description: values.description,
                     company_id: values.company_id,
                     status: "published",
-                    source_submission_id: entityId,
+                    source_submission_id: id,
                 });
             }
         },
 
         // Runs BEFORE deleting — block or validate
-        beforeDelete: async ({ entity }) => {
-            if (entity.values.status === "published") {
+        beforeDelete: async ({ row }) => {
+            if (row.status === "published") {
                 throw new Error("Cannot delete published submissions");
             }
         },
 
         // Runs AFTER deleting — cleanup related data
-        afterDelete: async ({ entityId, context }) => {
-            console.log(`Submission ${entityId} deleted`);
+        afterDelete: async ({ id, context }) => {
+            console.log(`Submission ${id} deleted`);
         },
 
         // Runs AFTER reading — transform for display
-        afterRead: async ({ entity }) => {
+        afterRead: async ({ row }) => {
             return {
-                ...entity,
-                values: {
-                    ...entity.values,
-                    displayName: `${entity.values.title} (${entity.values.company_name})`
-                }
+                ...row,
+                displayName: `${row.title} (${row.company_name})`
             };
         }
     },
@@ -960,7 +998,7 @@ const jobSubmissionsCollection: PostgresCollection = {
 | `beforeSave` | Before write to DB (after validation) | Modified `values` (`Partial<EntityValues<M>>`) | Yes (throw to block) |
 | `afterSave` | After successful write | `void` | No |
 | `afterSaveError` | After a failed write | `void` | No |
-| `afterRead` | After reading from DB | Modified `entity` (`Entity<M>`) | No |
+| `afterRead` | After reading from DB | Modified row (`Record<string, unknown>`) | No |
 | `beforeDelete` | Before deletion | `void \| boolean` | Yes (throw to block) |
 | `afterDelete` | After successful deletion | `void` | No |
 
@@ -971,10 +1009,10 @@ const jobSubmissionsCollection: PostgresCollection = {
 | Prop | Type | Description |
 |------|------|-------------|
 | `values` | `Partial<EntityValues<M>>` | Entity values being saved |
-| `entityId` | `string \| number` (optional in `beforeSave`) | Entity ID (`undefined` for new entities in `beforeSave`) |
+| `id` | `string \| number` (optional in `beforeSave`) | Entity ID (`undefined` for new entities in `beforeSave`) |
 | `previousValues` | `Partial<EntityValues<M>> \| undefined` | Previous values (for updates) |
 | `status` | `EntityStatus` | `"new"`, `"existing"`, or `"copy"` |
-| `collection` | `EntityCollection<M>` | The collection definition |
+| `collection` | `CollectionConfig<M>` | The collection definition |
 | `path` | `string` | Collection path |
 | `context` | `RebaseCallContext<USER>` | Context with `client`, `data`, `storageSource`, `user` |
 
@@ -982,8 +1020,8 @@ const jobSubmissionsCollection: PostgresCollection = {
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `entity` | `Entity<M>` | The fetched entity |
-| `collection` | `EntityCollection<M>` | The collection definition |
+| `row` | `Record<string, unknown>` | The fetched row (flat — `{ id, ...columns }`) |
+| `collection` | `CollectionConfig<M>` | The collection definition |
 | `path` | `string` | Collection path |
 | `context` | `RebaseCallContext<USER>` | Context |
 
@@ -991,9 +1029,9 @@ const jobSubmissionsCollection: PostgresCollection = {
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `entity` | `Entity<M>` | The entity being deleted |
-| `entityId` | `string \| number` | Entity ID |
-| `collection` | `EntityCollection<M>` | The collection definition |
+| `row` | `Record<string, unknown>` | The row being deleted (flat — `{ id, ...columns }`) |
+| `id` | `string \| number` | Entity ID |
+| `collection` | `CollectionConfig<M>` | The collection definition |
 | `path` | `string` | Collection path |
 | `context` | `RebaseCallContext<USER>` | Context |
 
@@ -1027,7 +1065,7 @@ title: {
 - **Cascade operations** — Use `afterDelete` to clean up related records in other collections
 - **Data enrichment** — Use `afterRead` to add computed/virtual fields for display
 
-> **See full documentation:** [Entity Callbacks](https://rebase.pro/docs/collections/callbacks)
+> **See full documentation:** [Collection Callbacks](https://rebase.pro/docs/collections/callbacks)
 
 ## Entity Actions (Custom UI Buttons)
 
@@ -1036,7 +1074,7 @@ title: {
 Add an `entityActions` array to any collection definition:
 
 ```typescript
-const jobSubmissionsCollection: PostgresCollection = {
+const jobSubmissionsCollection: PostgresCollectionConfig = {
     name: "Job Submissions",
     slug: "job_submissions",
     table: "job_submissions",
@@ -1093,13 +1131,13 @@ The `onClick` and `isEnabled` handlers receive:
 | `entity` | `Entity<M> \| undefined` | The current entity |
 | `context` | `RebaseContext<USER>` | Full context (includes `snackbarController`, `authController`, etc.) |
 | `path` | `string \| undefined` | Collection path |
-| `collection` | `EntityCollection<M> \| undefined` | Collection definition |
+| `collection` | `CollectionConfig<M> \| undefined` | Collection definition |
 | `formContext` | `FormContext \| undefined` | Form state (when called from a form) |
-| `sideEntityController` | `SideEntityController \| undefined` | Side panel control |
+| `sideEntityController` | `SidePanelController \| undefined` | Side panel control |
 | `selectionController` | `SelectionController \| undefined` | Multi-select state (collection view) |
 | `view` | `"collection" \| "form"` | Where the action was triggered |
 | `openEntityMode` | `"side_panel" \| "full_screen" \| "split" \| "dialog"` | How the entity form is opened |
-| `highlightEntity` | `(entity) => void` | Highlight an entity row |
+| `highlightEntity` | `(entity) => void` | Highlight a entity row |
 | `unhighlightEntity` | `(entity) => void` | Remove highlight |
 | `navigateBack` | `() => void` | Navigate back (e.g., after deleting) |
 | `onCollectionChange` | `() => void` | Refresh the collection view |
@@ -1126,7 +1164,7 @@ const entityViews = [
 <RebaseCMS collections={collections} entityViews={entityViews}/>
 
 // Per-collection reference in collection definition
-const postsCollection: PostgresCollection = {
+const postsCollection: PostgresCollectionConfig = {
     name: "Posts",
     slug: "posts",
     table: "posts",
@@ -1175,9 +1213,9 @@ You can override built-in UI components for a specific collection by adding a `c
 Only collection-scoped components can be overridden here. App-level components (such as `Shell.AppBar` or `HomePage`) must be overridden globally at the `<Rebase>` root.
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const productsCollection: PostgresCollection = {
+const productsCollection: PostgresCollectionConfig = {
     name: "Products",
     slug: "products",
     table: "products",
@@ -1223,9 +1261,9 @@ You can mark a collection as an authentication collection by setting the `auth`
 This is the collection used for user credentials, password hashing, and user management. Rebase auto-injects required auth actions (like resetting passwords) and routes them through this config.
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const customUsersCollection: PostgresCollection = {
+const customUsersCollection: PostgresCollectionConfig = {
     name: "Members",
     slug: "members",
     table: "members",
@@ -1289,7 +1327,7 @@ location: {
 Collections support **Row Level Security** via the `securityRules` array. This generates PostgreSQL RLS policies:
 
 ```typescript
-const postsCollection: PostgresCollection = {
+const postsCollection: PostgresCollectionConfig = {
     name: "Posts",
     slug: "posts",
     table: "posts",

package/skills/rebase-cron-jobs/SKILL.md

@@ -230,6 +230,11 @@ interface CronJobContext {
 | `log` | `(...args: unknown[]) => void` | Logger whose output is captured in `CronJobLogEntry.logs`. Use like `console.log`. |
 | `client` | `RebaseClient` | Admin-level client for CRUD, auth, storage, and any SDK operation. |
 
+> **IMPORTANT FOR AGENTS:** `ctx.client` authenticates as the **service identity** (`userId: "service"`, `roles: ["admin"]`). All data operations through `ctx.client` go through the full REST middleware pipeline (including DataHooks and Collection Callbacks). This means:
+> - Collection Callbacks will see `context.user.uid === "service"` and `context.user.roles` containing `"admin"`
+> - If your callbacks implement PII masking or role-based filtering, they should check for admin/service roles and skip masking for server-internal reads
+> - The service identity bypasses RLS policies
+
 ### Using `ctx.client`
 
 `ctx.client` is the same `RebaseClient` returned by `createRebaseClient()`. It supports all SDK operations:

package/skills/rebase-custom-functions/SKILL.md

@@ -118,6 +118,27 @@ app.get("/", async (c) => {
 export default app;
 ```
 
+### Reserved Identity Values in `c.get("user")`
+
+The `user` object set by the auth middleware uses reserved values for system identities:
+
+| Auth Method | `user.userId` | `user.roles` |
+|---|---|---|
+| JWT (end-user) | Real user ID | User's assigned roles |
+| Service Key | `"service"` | `["admin"]` |
+| API Key (default) | `"api-key:{id}"` | `["service"]` |
+| API Key (admin) | `"api-key:{id}"` | `["admin", "service"]` |
+| Anonymous | `"anon"` | `["anon"]` |
+
+> **TIP:** Use these to differentiate internal vs. external callers in your custom functions:
+> ```typescript
+> app.get("/sensitive-data", async (c) => {
+>     const user = c.get("user");
+>     const isInternal = user?.userId === "service" || user?.roles?.includes("admin");
+>     // Return full or masked data based on identity
+> });
+> ```
+
 ## Invoking Functions from the Frontend
 
 > **CRITICAL FOR AGENTS**: When calling custom backend functions from the frontend, **ALWAYS** use `client.functions.invoke()`. **NEVER** use raw `fetch()`, manually construct URLs, or manually extract auth tokens from `localStorage`. The SDK handles all of this automatically.

package/skills/rebase-deployment/SKILL.md

@@ -367,7 +367,7 @@ All variables recognized by the base `rebaseEnvSchema`:
 | `DB_POOL_CONNECT_TIMEOUT` | `string` → `number` | No | `"10000"` → `10000` | Connection timeout (ms) |
 | `DATABASE_DIRECT_URL` | `string` (URL) | No | — | Direct database URL (bypasses pooler) |
 | `DATABASE_READ_URL` | `string` (URL) | No | — | Read replica database URL |
-| `STORAGE_TYPE` | `enum` | No | `"local"` | `"local"` or `"s3"` |
+| `STORAGE_TYPE` | `enum` | No | `"local"` | `"local"`, `"s3"`, or `"gcs"` |
 | `STORAGE_PATH` | `string` | No | — | Local file storage directory |
 | `FORCE_LOCAL_STORAGE` | `optionalBoolString` | No | `undefined` → `false` | Suppress local-storage-in-production warning |
 | `S3_BUCKET` | `string` | If S3 | — | S3 bucket name |
@@ -376,6 +376,9 @@ All variables recognized by the base `rebaseEnvSchema`:
 | `S3_SECRET_ACCESS_KEY` | `string` | If S3 | — | S3 secret key |
 | `S3_ENDPOINT` | `string` (URL) | No | — | Custom S3 endpoint (MinIO, R2) |
 | `S3_FORCE_PATH_STYLE` | `optionalBoolString` | No | `undefined` → `false` | Use path-style S3 URLs (required for MinIO) |
+| `GCS_BUCKET` | `string` | If GCS | — | Google Cloud Storage bucket name |
+| `GCS_PROJECT_ID` | `string` | If GCS | — | GCP project ID for GCS |
+| `GOOGLE_APPLICATION_CREDENTIALS` | `string` | If GCS (non-GCP) | — | Path to GCP service account JSON key file (not needed on GCP with default credentials) |
 
 ### Zod Type Helpers
 
@@ -573,7 +576,13 @@ Internet → Cloud Run (HTTPS, auto-scaling) → Cloud SQL PostgreSQL
      --allow-unauthenticated
    ```
 4. **Custom Domain** — Map a custom domain in Cloud Run settings. Cloud Run provides HTTPS automatically.
-5. **File Storage** — Use `STORAGE_TYPE=s3` with a GCS bucket via the S3-compatible interop endpoint, or use a dedicated S3 provider like Cloudflare R2.
+5. **File Storage** — Use native GCS support with `STORAGE_TYPE=gcs`:
+   ```bash
+   STORAGE_TYPE=gcs
+   GCS_BUCKET=your-rebase-uploads
+   GCS_PROJECT_ID=your-gcp-project-id
+   ```
+   On Cloud Run, the default service account credentials are used automatically — no key file needed. Alternatively, you can fall back to `STORAGE_TYPE=s3` with the GCS S3-compatible interop endpoint.
 
 ### Cloud SQL Auth Proxy (Connection String)
 
@@ -762,7 +771,7 @@ Schedule automated PostgreSQL backups via cron on the host:
 0 3 * * * root docker compose -f /path/to/docker-compose.yml exec -T db pg_dump -U rebase rebase | gzip > /backups/rebase-$(date +\%Y\%m\%d).sql.gz
 ```
 
-> **TIP:** Hetzner also offers managed snapshots (server-level) and the option to attach a Hetzner Volume for data that survives server rebuilds. For production, strongly consider both.
+> **TIP:** Hetzner also offers managed entities (server-level) and the option to attach a Hetzner Volume for data that survives server rebuilds. For production, strongly consider both.
 
 ---
 

package/skills/rebase-email/SKILL.md

@@ -408,7 +408,7 @@ auth: {
 
 ## `rebase.email` Singleton
 
-When email is configured, the email service is automatically attached to the `rebase` server-side singleton as `rebase.email`. This allows sending emails programmatically from custom functions, cron jobs, and entity callbacks.
+When email is configured, the email service is automatically attached to the `rebase` server-side singleton as `rebase.email`. This allows sending emails programmatically from custom functions, cron jobs, and collection callbacks.
 
 ```typescript
 import { rebase } from "@rebasepro/server-core";

package/skills/rebase-entity-history/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: rebase-entity-history
-description: Guide for tracking and reverting entity changes with Rebase's built-in history/audit-log system. Use this skill when the user needs entity versioning, change tracking, audit logs, reverting to previous versions, or understanding how history snapshots work.
+description: Guide for tracking and reverting entity changes with Rebase's built-in history/audit-log system. Use this skill when the user needs entity versioning, change tracking, audit logs, reverting to previous versions, or understanding how history entities work.
 ---
 
 # Rebase Entity History
 
-Rebase includes a built-in entity history system that records snapshots of every create, update, and delete operation. History entries are stored in a dedicated PostgreSQL table and exposed via REST API endpoints. The Studio admin panel provides a visual history tab with one-click revert.
+Rebase includes a built-in entity history system that records entities of every create, update, and delete operation. History entries are stored in a dedicated PostgreSQL table and exposed via REST API endpoints. The Studio admin panel provides a visual history tab with one-click revert.
 
 > **IMPORTANT FOR AGENTS:** Entity history requires **two** things to be enabled: (1) the global `history` flag in the backend config, AND (2) `history: true` on each individual collection. If either is missing, no history is recorded for that collection.
 
@@ -49,9 +49,9 @@ history: { retention: 30 },
 On each collection that should be tracked, set `history: true`:
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const productsCollection: PostgresCollection = {
+const productsCollection: PostgresCollectionConfig = {
     slug: "products",
     name: "Products",
     table: "products",
@@ -100,7 +100,7 @@ Each history entry has the following structure:
 | `entity_id` | `string` | The ID of the entity this entry belongs to |
 | `action` | `"create" \| "update" \| "delete"` | What operation was performed |
 | `changed_fields` | `string[] \| null` | Array of field names that changed (only for updates) |
-| `values` | `Record<string, unknown> \| null` | Full entity values snapshot at the time of the change |
+| `values` | `Record<string, unknown> \| null` | Full entity values entity at the time of the change |
 | `previous_values` | `Record<string, unknown> \| null` | Previous entity values (only for updates) |
 | `updated_by` | `string \| null` | UID of the user who made the change |
 | `updated_at` | `string` (ISO 8601) | Timestamp of when the change was recorded |
@@ -292,7 +292,7 @@ CREATE TABLE IF NOT EXISTS rebase.entity_history (
     entity_id TEXT NOT NULL,
     action TEXT NOT NULL,          -- 'create', 'update', or 'delete'
     changed_fields TEXT[],         -- array of changed field names (updates only)
-    "values" JSONB,               -- full entity values snapshot
+    "values" JSONB,               -- full entity values entity
     previous_values JSONB,        -- previous values (updates only)
     updated_by TEXT,              -- user UID who made the change
     updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
@@ -310,7 +310,7 @@ CREATE INDEX IF NOT EXISTS idx_history_time
 
 ### Storage Characteristics
 
-- **Values are stored as JSONB** — full snapshots, not diffs. This makes revert simple and reliable but uses more storage.
+- **Values are stored as JSONB** — full entities, not diffs. This makes revert simple and reliable but uses more storage.
 - **All collections share one table** — the `table_name` column distinguishes between collections.
 - **Entity IDs are stored as text** — regardless of the original column type.
 - **Indexes** cover `(table_name, entity_id)` and `(table_name, entity_id, updated_at DESC)` for fast per-entity lookups.
@@ -382,7 +382,7 @@ No additional configuration is needed — the History tab appears automatically
 
 There is currently **no dedicated client SDK method** for entity history. History is accessed via the REST API directly (as shown in the endpoints section above).
 
-The Studio admin panel uses an internal `useEntityHistory` React hook that:
+The Studio admin panel uses an internal `useHistory` React hook that:
 - Fetches history from `GET /api/data/:slug/:entityId/history`
 - Supports pagination via offset-based loading
 - Provides a `revert()` function that calls `POST /api/data/:slug/:entityId/history/:historyId/revert`
@@ -462,7 +462,7 @@ console.log(`Server running at http://localhost:${env.PORT}`);
 
 ### Storage Growth
 
-- Each history entry stores **full JSONB snapshots** of both current and previous values. For entities with large text fields or complex nested structures, this can grow quickly.
+- Each history entry stores **full JSONB entities** of both current and previous values. For entities with large text fields or complex nested structures, this can grow quickly.
 - Default retention limits: **200 entries per entity** and **90 days TTL**. Adjust these based on your use case.
 - All collections share the single `rebase.entity_history` table — monitor its size with:
 

package/skills/rebase-realtime/SKILL.md

@@ -341,11 +341,11 @@ ws.onmessage = (event) => {
 | `broadcast` | `{ channel, event, payload }` | Send a message to channel members |
 | `presence_track` | `{ channel, state }` | Track presence with custom state (auto-joins channel) |
 | `presence_untrack` | `{ channel }` | Stop tracking presence |
-| `presence_state` | `{ channel }` | Request full presence snapshot |
+| `presence_state` | `{ channel }` | Request full presence entity |
 | `FETCH_COLLECTION` | `FetchCollectionProps` | One-shot collection fetch (request/response) |
 | `FETCH_ENTITY` | `FetchEntityProps` | One-shot entity fetch |
-| `SAVE_ENTITY` | `SaveEntityProps` | Create or update an entity |
-| `DELETE_ENTITY` | `DeleteEntityProps` | Delete an entity |
+| `SAVE_ENTITY` | `SaveEntityProps` | Create or update a entity |
+| `DELETE_ENTITY` | `DeleteEntityProps` | Delete a entity |
 | `COUNT_ENTITIES` | `FetchCollectionProps` | Count entities matching criteria |
 | `CHECK_UNIQUE_FIELD` | `{ path, name, value, entityId?, collection? }` | Check field uniqueness |
 
@@ -359,7 +359,7 @@ ws.onmessage = (event) => {
 | `entity_update` | `{ subscriptionId, entity }` | Single entity data (entity or `null` if deleted) |
 | `collection_entity_patch` | `{ subscriptionId, entityId, entity }` | Instant single-entity patch for a collection subscription |
 | `broadcast` | `{ channel, event, payload }` | Broadcast from another channel member |
-| `presence_state` | `{ channel, presences }` | Full presence snapshot |
+| `presence_state` | `{ channel, presences }` | Full presence entity |
 | `presence_diff` | `{ channel, joins, leaves }` | Incremental presence update |
 | `ERROR` | `{ requestId?, payload: { error: { message, code } } }` | General error |
 | `FETCH_COLLECTION_SUCCESS` | `{ requestId, payload: { entities } }` | Response to FETCH_COLLECTION |
@@ -687,7 +687,7 @@ If 10 entities change within 300ms, only **one** database query is executed for
 
 ## Nested Relation Updates
 
-The realtime engine handles nested relation paths (e.g., `"posts/70/tags"`). When an entity changes at a nested path:
+The realtime engine handles nested relation paths (e.g., `"posts/70/tags"`). When a entity changes at a nested path:
 
 1. The exact path is notified (`"posts/70/tags"`).
 2. All parent paths are also notified (`"posts"`, `"posts/70"`).

package/skills/rebase-sdk/SKILL.md

@@ -437,6 +437,29 @@ const { items, nextPageToken } = await rebase.storage.listObjects('prefix/', {
 });
 ```
 
+### Multi-Backend Storage
+
+`rebase.storage` accesses the **default** storage source. For multi-backend setups (e.g. S3 + GCS/Firebase), collection properties can specify `storage.storageSource` in their schema to route uploads to a named backend.
+
+On the frontend, register direct storage sources via the `storageSources` prop on `<Rebase>`:
+
+```tsx
+import { getStorage } from "firebase/storage";
+
+const firebaseStorageSource = getStorage(firebaseApp);
+
+<Rebase
+    client={rebaseClient}
+    storageSources={[
+        { key: "firebase", engine: "firebase", transport: "direct", source: firebaseStorageSource }
+    ]}
+>
+    {children}
+</Rebase>
+```
+
+The system resolves the correct source per-property via `StorageSourcesContext` (mirroring `DataSourcesContext`). Properties bound to a `direct` storage source bypass the Rebase backend and upload/download directly to the provider (e.g. Firebase Storage), while `server` sources route through the Rebase API with a `?storageId` query parameter for backend routing.
+
 ## Custom Functions
 
 Invoke custom server-side functions defined in the backend: