@rebasepro/agent-skills 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/agent-skills",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "Bundled AI agent skills for Rebase",
   "type": "module",

package/skills/rebase-admin/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rebase-admin
-description: Guide for navigating the Rebase admin CMS, opening entities in side drawers, building URLs, embedding collection panels, using the collection registry, and programmatic navigation. Use this skill when an agent or user needs to navigate to a collection view, open an entity in the side panel/drawer, build admin URLs, embed a collection inside a custom page, use the entity selection dialog, or access CMS-specific controllers.
+description: Guide for navigating the Rebase admin CMS, opening entities in side drawers, building URLs, embedding collection panels, using the collection registry, and programmatic navigation. Use this skill when an agent or user needs to navigate to a collection view, open a entity in the side panel/drawer, build admin URLs, embed a collection inside a custom page, use the entity selection dialog, or access CMS-specific controllers.
 ---
 
 # Rebase Admin (`@rebasepro/admin`)
@@ -13,12 +13,12 @@ The `@rebasepro/admin` package provides the CMS layer for Rebase. It handles col
 
 | Task | Hook / Component | Package |
 |------|-----------------|---------|
-| Open entity in side drawer | `useSideEntityController()` | `@rebasepro/admin` |
+| Open entity in side drawer | `useSidePanel()` | `@rebasepro/admin` |
 | Navigate to a collection view | `useUrlController()` | `@rebasepro/admin` |
 | Look up a collection by slug | `useCollectionRegistryController()` | `@rebasepro/admin` |
 | Embed a collection in a custom page | `<CollectionPanel>` | `@rebasepro/admin` |
 | Add custom top-level views | `<RebaseCMS views={[...]}>` | `@rebasepro/admin` |
-| Open an entity selection dialog | `useEntitySelectionDialog()` | `@rebasepro/admin` |
+| Open a entity selection dialog | `useSelectionDialog()` | `@rebasepro/admin` |
 | Open a custom side dialog | `useSideDialogsController()` | `@rebasepro/admin` |
 | Set breadcrumbs | `useBreadcrumbsController()` | `@rebasepro/admin` |
 | Access full CMS context | `useCMSContext()` | `@rebasepro/admin` |
@@ -28,16 +28,16 @@ The `@rebasepro/admin` package provides the CMS layer for Rebase. It handles col
 
 ## 1. Opening Entities in the Side Drawer
 
-Use `useSideEntityController()` to open, replace, or close entity side panels (the sliding drawer that shows entity forms).
+Use `useSidePanel()` to open, replace, or close entity side panels (the sliding drawer that shows entity forms).
 
 ```typescript
-import { useSideEntityController } from "@rebasepro/admin";
+import { useSidePanel } from "@rebasepro/admin";
 ```
 
-### SideEntityController Interface
+### SidePanelController Interface
 
 ```typescript
-interface SideEntityController {
+interface SidePanelController {
     /** Close the last (topmost) panel */
     close: () => void;
 
@@ -69,7 +69,7 @@ interface EntitySidePanelProps<M extends Record<string, unknown> = Record<string
     width?: number | string;
 
     /** Explicit collection config (auto-resolved from navigation if omitted) */
-    collection?: EntityCollection<M>;
+    collection?: CollectionConfig<M>;
 
     /** Whether to update the browser URL when opening (default: true) */
     updateUrl?: boolean;
@@ -98,7 +98,7 @@ interface EntitySidePanelProps<M extends Record<string, unknown> = Record<string
 
 **Open an existing entity for editing:**
 ```tsx
-const sideEntityController = useSideEntityController();
+const sideEntityController = useSidePanel();
 
 // Open the product with ID "abc123" in the side drawer
 sideEntityController.open({
@@ -236,10 +236,10 @@ import { useCollectionRegistryController } from "@rebasepro/admin";
 ```typescript
 type CollectionRegistryController<
     DB = Record<string, unknown>,
-    EC extends EntityCollection = EntityCollection
+    EC extends CollectionConfig = CollectionConfig
 > = {
     /** All registered collections */
-    collections?: EntityCollection[];
+    collections?: CollectionConfig[];
 
     /** Whether the registry is ready */
     initialised: boolean;
@@ -321,7 +321,7 @@ type CollectionPanelProps = {
     className?: string;
 
     /** Additional collection-level overrides */
-    collectionOverrides?: Partial<EntityCollection>;
+    collectionOverrides?: Partial<CollectionConfig>;
 };
 ```
 
@@ -356,17 +356,17 @@ type CollectionPanelProps = {
 
 ## 5. Entity Selection Dialog
 
-Use `useEntitySelectionDialog()` to open a side dialog for selecting entities (same mechanism used by reference fields).
+Use `useSelectionDialog()` to open a side dialog for selecting entities (same mechanism used by reference fields).
 
 ```typescript
-import { useEntitySelectionDialog } from "@rebasepro/admin";
+import { useSelectionDialog } from "@rebasepro/admin";
 ```
 
 ### Usage
 
 ```tsx
 function MyComponent() {
-    const { open, close } = useEntitySelectionDialog<Product>({
+    const { open, close } = useSelectionDialog<Product>({
         path: "products",
         onSingleEntitySelected: (entity) => {
             console.log("Selected:", entity.id);
@@ -378,7 +378,7 @@ function MyComponent() {
 }
 ```
 
-The hook accepts all `EntitySelectionProps` except `path` (which you pass separately), plus an `onClose` callback.
+The hook accepts all `SelectionProps` except `path` (which you pass separately), plus an `onClose` callback.
 
 ---
 
@@ -545,7 +545,7 @@ import { useCMSContext } from "@rebasepro/admin";
 
 ```typescript
 type CMSContext = RebaseContext & {
-    sideEntityController: SideEntityController;
+    sideEntityController: SidePanelController;
     sideDialogsController: SideDialogsController;
     urlController: UrlController;
     navigationStateController: NavigationStateController;
@@ -572,14 +572,14 @@ context.data;           // DataSource from RebaseContext
 
 ## 10. Common Patterns
 
-### Navigate to a collection and open an entity
+### Navigate to a collection and open a entity
 
 ```tsx
-import { useUrlController, useSideEntityController } from "@rebasepro/admin";
+import { useUrlController, useSidePanel } from "@rebasepro/admin";
 
 function navigateAndOpen() {
     const urlController = useUrlController();
-    const sideEntityController = useSideEntityController();
+    const sideEntityController = useSidePanel();
 
     // First navigate to the collection
     urlController.navigate(urlController.buildUrlCollectionPath("products"));
@@ -595,10 +595,10 @@ function navigateAndOpen() {
 ### Open entity from a custom view without navigating
 
 ```tsx
-import { useSideEntityController } from "@rebasepro/admin";
+import { useSidePanel } from "@rebasepro/admin";
 
 function MyCustomView() {
-    const sideEntityController = useSideEntityController();
+    const sideEntityController = useSidePanel();
 
     return (
         <button onClick={() => sideEntityController.open({
@@ -615,10 +615,10 @@ function MyCustomView() {
 ### Programmatic entity creation from a custom view
 
 ```tsx
-import { useSideEntityController } from "@rebasepro/admin";
+import { useSidePanel } from "@rebasepro/admin";
 
 function CreateButton() {
-    const sideEntity = useSideEntityController();
+    const sideEntity = useSidePanel();
 
     return (
         <button onClick={() => sideEntity.open({
@@ -754,10 +754,10 @@ The admin package exports the following components (from `@rebasepro/admin`):
 | `RebaseCMS` | Declarative CMS config (collections, views, editor) — renders nothing |
 | `RebaseShell` | App shell (drawer, nav, routes, layout) — renders the actual UI |
 | `CollectionPanel` | Embed a collection view inside custom pages |
-| `EntityCollectionView` | The collection view component |
-| `EntityView` | Entity detail/edit view |
+| `DataCollectionView` | The collection view component |
+| `EntityCustomView` | Entity detail/edit view |
 | `EntityPreview` | Reference/relation preview chip |
-| `EntityCard` | Card representation of an entity |
+| `EntityCard` | Card representation of a entity |
 | `SideDialogs` | Side dialog container |
 | `SideEntityProvider` | Context provider for side entity controller |
 | `EntitySelectionTable` | Table for selecting entities |
@@ -773,16 +773,16 @@ The admin package exports the following components (from `@rebasepro/admin`):
 
 | Hook | Description |
 |------|-------------|
-| `useSideEntityController()` | Open/close entity side panels |
+| `useSidePanel()` | Open/close entity side panels |
 | `useSideDialogsController()` | Open/close generic side dialogs |
 | `useUrlController()` | Build URLs and navigate |
 | `useNavigationStateController()` | Access navigation state |
 | `useCollectionRegistryController()` | Look up collections by slug |
 | `useBreadcrumbsController()` | Read/set breadcrumbs |
 | `useCMSContext()` | Full CMS context (core + CMS controllers) |
-| `useEntitySelectionDialog()` | Open entity selection dialog |
+| `useSelectionDialog()` | Open entity selection dialog |
 | `useSelectionController()` | Multi-select controller |
-| `useEntityHistory()` | Entity version history |
+| `useHistory()` | Entity version history |
 | `useApp()` | App-level utilities |
 
 ## Exported Utilities
@@ -796,8 +796,8 @@ The admin package exports the following components (from `@rebasepro/admin`):
 | `getLastSegment(path)` | Get last path segment |
 | `getCollectionBySlugWithin(collections, slug)` | Find collection in array |
 | `mergeEntityActions(...)` | Merge entity action arrays |
-| `resolveEntityAction(...)` | Resolve an entity action |
-| `resolveEntityView(...)` | Resolve an entity view |
+| `resolveEntityAction(...)` | Resolve a entity action |
+| `resolveEntityView(...)` | Resolve a entity view |
 | `isReferenceProperty(prop)` | Check if property is a reference |
 | `isRelationProperty(prop)` | Check if property is a relation |
 | `getIconForProperty(prop)` | Get icon for a property type |

package/skills/rebase-api/SKILL.md

@@ -43,8 +43,8 @@ All data routes are mounted under `/api/data/`. Other route categories:
 | `GET` | `/api/data/{slug}/count` | Count matching entities (with optional filters) | `200` |
 | `GET` | `/api/data/{slug}/:id` | Get a single entity by ID | `200` |
 | `POST` | `/api/data/{slug}` | Create a new entity | `201` |
-| `PUT` | `/api/data/{slug}/:id` | Update an entity | `200` |
-| `DELETE` | `/api/data/{slug}/:id` | Delete an entity | `204` |
+| `PUT` | `/api/data/{slug}/:id` | Update a entity | `200` |
+| `DELETE` | `/api/data/{slug}/:id` | Delete a entity | `204` |
 
 ### Subcollection Routes
 
@@ -405,7 +405,7 @@ curl -H "Authorization: Bearer $TOKEN" \
   "https://example.com/api/data/products?status=eq.active&price=gte.50&orderBy=created_at:desc&limit=10&offset=0&include=category"
 ```
 
-### Create an entity
+### Create a entity
 
 ```bash
 curl -X POST \
@@ -415,7 +415,7 @@ curl -X POST \
   "https://example.com/api/data/products"
 ```
 
-### Update an entity
+### Update a entity
 
 ```bash
 curl -X PUT \
@@ -425,7 +425,7 @@ curl -X PUT \
   "https://example.com/api/data/products/uuid-123"
 ```
 
-### Delete an entity
+### Delete a entity
 
 ```bash
 curl -X DELETE \
@@ -655,7 +655,7 @@ GET /api/collections
 | `pagination.maxLimit` | `number` | `100` | Maximum allowed page size |
 | `cors.origin` | `string \| string[] \| boolean` | — | CORS origin configuration |
 | `cors.credentials` | `boolean` | `false` | Allow credentials in CORS |
-| `collections` | `EntityCollection[]` | `[]` | Collections to generate APIs for |
+| `collections` | `CollectionConfig[]` | `[]` | Collections to generate APIs for |
 | `collectionsDir` | `string` | — | Directory to auto-discover collections |
 
 ## References

package/skills/rebase-auth/SKILL.md

@@ -39,12 +39,13 @@ Authentication is configured via the `auth` property of `initializeRebaseBackend
 
 | Property | Type | Default | Description |
 |---|---|---|---|
-| `collection` | `EntityCollection` | Built-in users collection | The collection used for auth user storage. Import `defaultUsersCollection` from `@rebasepro/common` or pass a custom collection with required auth fields. |
+| `collection` | `CollectionConfig` | Built-in users collection | The collection used for auth user storage. Import `defaultUsersCollection` from `@rebasepro/common` or pass a custom collection with required auth fields. |
 | `jwtSecret` | `string` | — | **Required.** Secret for signing JWT access tokens. |
 | `accessExpiresIn` | `string` | `"1h"` | Access token lifetime (e.g. `"15m"`, `"2h"`). |
 | `refreshExpiresIn` | `string` | `"30d"` | Refresh token lifetime. |
 | `requireAuth` | `boolean` | `true` | When `true`, data routes return 401 for unauthenticated requests. Set to `false` to rely entirely on Postgres RLS. |
 | `allowRegistration` | `boolean` | `false` | Enable self-service registration via `POST /auth/register`. |
+| `allowUserLookup` | `boolean` | `false` | Expose `POST /auth/find-user` — an authenticated email→minimal-profile lookup (`uid`/`displayName`/`photoURL` only) for invite flows. Enables user enumeration by signed-in users, so it's off by default. See [Inviting by email](#inviting-teammates-by-email). |
 | `serviceKey` | `string` | — | Static secret for server-to-server auth. Must be ≥ 32 characters. Requests with `Authorization: Bearer <serviceKey>` get admin access. |
 | `defaultRole` | `string` | — | Role ID assigned to new users (except the first user, who always gets `"admin"`). **Must NOT be `"admin"`** — throws a security error at startup. |
 | `providers` | `OAuthProvider<unknown>[]` | `[]` | **Canonical** OAuth provider array. Use `create*Provider` factories or pass custom providers. Named shorthand fields below are merged into this array at startup. |
@@ -107,9 +108,9 @@ await initializeRebaseBackend({
 Instead of relying solely on the default database auth rules, you can mark any Postgres collection (such as `users.ts` or a custom `members.ts` collection) as the authentication collection. This is configured via the `auth` property on the collection itself:
 
 ```typescript
-import { PostgresCollection } from "@rebasepro/types";
+import { PostgresCollectionConfig } from "@rebasepro/types";
 
-const membersCollection: PostgresCollection = {
+const membersCollection: PostgresCollectionConfig = {
   name: "Members",
   slug: "members",
   table: "members",
@@ -154,6 +155,27 @@ When custom hooks (`onCreateUser`, `onResetPassword`) are called, they receive a
 
 > **IMPORTANT FOR AGENTS:** The very first user registered (via `POST /auth/register` or OAuth) is automatically promoted to `"admin"`. This prevents the chicken-and-egg problem. All subsequent users receive the `defaultRole`.
 
+### Inviting teammates by email
+
+Invite flows must turn an email into a user id, but the `users` collection is
+RLS-protected from the client. **Do not** hand-roll an admin server function for
+this — enable `allowUserLookup` and use the built-in primitive:
+
+```typescript
+// backend: initializeRebaseBackend({ auth: { allowUserLookup: true } })
+
+// client:
+const profile = await rebase.auth.findUserByEmail("teammate@example.com");
+// → { uid, displayName, photoURL } | null   (never email/roles/metadata)
+if (profile) {
+    await rebase.data.team_members.create({ team_id, user_id: profile.uid });
+}
+```
+
+The `find-user` endpoint is authenticated-only and returns just the minimal
+public profile. It is off by default because it enables user enumeration by any
+signed-in user.
+
 ---
 
 ## OAuth Providers
@@ -859,7 +881,7 @@ API keys use a service identity for RLS scoping: `uid: "api-key:{id}"`, `roles:
 
 ### Reserved System Identities
 
-The auth middleware assigns these reserved identities automatically. They are visible in `context.user` (Entity Callbacks / DataHooks) and `c.get("user")` (custom functions):
+The auth middleware assigns these reserved identities automatically. They are visible in `context.user` (Collection Callbacks / DataHooks) and `c.get("user")` (custom functions):
 
 | Auth Method | `userId` | `roles` | When It Occurs |
 |---|---|---|---|
@@ -870,7 +892,7 @@ The auth middleware assigns these reserved identities automatically. They are vi
 | Anonymous | `"anon"` | `["anon"]` | Unauthenticated when `requireAuth: false` |
 | No token + `requireAuth: true` | — | — | **Rejected (401)** |
 
-> **IMPORTANT FOR AGENTS:** Server-side `rebase.data` (the singleton used in cron jobs, custom functions, and webhooks) is built with `createRebaseClient({ token: serviceKey })`. It round-trips through the REST API, so all middleware, DataHooks, and Entity Callbacks fire with `userId: "service"`, `roles: ["admin"]`. This lets developers distinguish server-internal reads from end-user reads in callbacks.
+> **IMPORTANT FOR AGENTS:** Server-side `rebase.data` (the singleton used in cron jobs, custom functions, and webhooks) is built with `createRebaseClient({ token: serviceKey })`. It round-trips through the REST API, so all middleware, DataHooks, and Collection Callbacks fire with `userId: "service"`, `roles: ["admin"]`. This lets developers distinguish server-internal reads from end-user reads in callbacks.
 
 ---
 
@@ -1092,7 +1114,7 @@ Admin user and role management is handled via dedicated admin routes (mounted un
 
 ## Backend Hooks
 
-Backend hooks intercept data at the **API boundary** (after DB operations, before API responses). They are separate from auth hooks and collection-level `EntityCallbacks`.
+Backend hooks intercept data at the **API boundary** (after DB operations, before API responses). They are separate from auth hooks and collection-level `CollectionCallbacks`.
 
 ### BackendHooks Interface
 
@@ -1256,7 +1278,7 @@ When a request includes `Authorization: Bearer <serviceKey>`:
 - Comparison is done with constant-time comparison to prevent timing attacks.
 - Must be ≥ 32 characters (validated at startup).
 
-> **TIP:** In Entity Callbacks and DataHooks, server-side `rebase.data` calls appear as `userId: "service"`, `roles: ["admin"]`. Use this to skip masking, bypass rate limits, or grant elevated access in your callback logic.
+> **TIP:** In Collection Callbacks and DataHooks, server-side `rebase.data` calls appear as `userId: "service"`, `roles: ["admin"]`. Use this to skip masking, bypass rate limits, or grant elevated access in your callback logic.
 
 ### Token Rotation
 

package/skills/rebase-backend-postgres/SKILL.md

@@ -69,7 +69,7 @@ rebase db migrate
 |---------|---------|
 | `@rebasepro/server-core` | Hono server coordinator, API generation, auth, storage, env validation |
 | `@rebasepro/server-postgresql` | PostgreSQL bootstrapper, data driver, connection helpers, realtime (LISTEN/NOTIFY) |
-| `@rebasepro/types` | Shared TypeScript type definitions (`PostgresCollection`, etc.) |
+| `@rebasepro/types` | Shared TypeScript type definitions (`PostgresCollectionConfig`, etc.) |
 
 ## Connection Functions
 
@@ -339,7 +339,7 @@ The `initializeRebaseBackend()` coordinator calls bootstrapper methods in this o
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `collection` | `EntityCollection` | Built-in `rebase.users` | Auth users collection |
+| `collection` | `CollectionConfig` | Built-in `rebase.users` | Auth users collection |
 | `jwtSecret` | `string` | Auto-generated in dev | JWT signing secret (≥32 chars) |
 | `accessExpiresIn` | `string` | `"1h"` | Access token TTL |
 | `refreshExpiresIn` | `string` | `"30d"` | Refresh token TTL |
@@ -514,7 +514,7 @@ const backend = await initializeRebaseBackend({
 
 When enabled:
 - The bootstrapper auto-creates a `rebase.entity_history` table
-- Every `INSERT`, `UPDATE`, `DELETE` is recorded with before/after snapshots
+- Every `INSERT`, `UPDATE`, `DELETE` is recorded with before/after entities
 - History is queryable via the `/:slug/:entityId/history` REST endpoint
 
 ## Health Check

package/skills/rebase-basics/SKILL.md

@@ -125,7 +125,7 @@ rebase/
 | `@rebasepro/server-postgresql` | PostgreSQL bootstrapper and Drizzle ORM data driver | Backend setup when using PostgreSQL |
 | `@rebasepro/server-mongodb` | MongoDB bootstrapper and data driver | Backend setup when using MongoDB |
 | `@rebasepro/core` | Core framework, types, hooks, and React components | Frontend — React integration, hooks, providers |
-| `@rebasepro/types` | Shared TypeScript type definitions (`PostgresCollection`, `EntityCollection`, `RebaseClient`, etc.) | Type imports across all packages |
+| `@rebasepro/types` | Shared TypeScript type definitions (`PostgresCollectionConfig`, `CollectionConfig`, `RebaseClient`, etc.) | Type imports across all packages |
 | `@rebasepro/ui` | Standalone component library (Tailwind CSS v4 + Radix) | Building custom views in Studio or standalone UI |
 | `@rebasepro/admin` | CMS frontend application | The Studio admin panel frontend |
 | `@rebasepro/studio` | Admin panel, collection editor, visual schema editor | Studio-specific features and customization |
@@ -434,7 +434,7 @@ import { initializeRebaseBackend, RebaseBackendConfig } from "@rebasepro/server-
 |----------|------|---------|-------------|
 | `server` | `Server` (Node `http.Server`) | — | **Required.** The HTTP server instance |
 | `app` | `Hono<HonoEnv>` | — | **Required.** The Hono application instance |
-| `collections` | `EntityCollection[]` | `[]` | Inline collection definitions |
+| `collections` | `CollectionConfig[]` | `[]` | Inline collection definitions |
 | `collectionsDir` | `string` | — | Directory to auto-discover collection files (used if `collections` is empty) |
 | `basePath` | `string` | `"/api"` | Base path for all API routes |
 | `database` | `DatabaseAdapter` | — | Database adapter (takes precedence over `bootstrappers`) |
@@ -459,7 +459,7 @@ import { initializeRebaseBackend, RebaseBackendConfig } from "@rebasepro/server-
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `collection` | `EntityCollection` | `defaultUsersCollection` | The collection used for auth users |
+| `collection` | `CollectionConfig` | `defaultUsersCollection` | The collection used for auth users |
 | `jwtSecret` | `string` | — | JWT signing secret (≥32 chars) |
 | `accessExpiresIn` | `string` | `"1h"` | Access token TTL |
 | `refreshExpiresIn` | `string` | `"30d"` | Refresh token TTL |
@@ -654,7 +654,7 @@ The Rebase MCP server provides these tools for AI agents. Use the MCP tool calli
 | `rebase_schema_generate` | Generate Drizzle schema from collection definitions. Run after adding or modifying collection files | — |
 | `rebase_schema_introspect` | Introspect the live database and generate Rebase collection definitions from existing tables | — |
 | `rebase_db_push` | Apply the current Drizzle schema directly to the database (development shortcut, skips migration files) | — |
-| `rebase_db_generate` | Generate SQL migration files from schema changes (compares current Drizzle schema against the last snapshot) | — |
+| `rebase_db_generate` | Generate SQL migration files from schema changes (compares current Drizzle schema against the last entity) | — |
 | `rebase_db_migrate` | Run all pending SQL migrations against the database | — |
 
 ### SDK