@rebasepro/agent-skills 0.9.1-canary.ff338b5 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebasepro/agent-skills",
-  "version": "0.9.1-canary.ff338b5",
+  "version": "0.10.0",
   "private": false,
   "description": "Bundled AI agent skills for Rebase",
   "type": "module",

package/skills/rebase-auth/SKILL.md

@@ -219,11 +219,48 @@ Twitter uses OAuth 2.0 with PKCE. The client must send `codeVerifier` alongside
 
 ### OAuth Account Linking
 
-When an OAuth user signs in:
-1. If an identity record exists for `(providerId, provider)` → log in that user.
-2. If no identity exists but a user with the same email exists → **link** the provider to the existing account.
+When an OAuth user signs in via `POST /api/auth/{provider}`:
+
+1. If an identity record exists for `(provider, providerId)` → log in that user. The email is not consulted.
+2. If no identity exists but a user with the same email exists:
+   - **The provider asserted `emailVerified: true`** → **link** the provider to the existing account and log in as that user. One account, two sign-in methods.
+   - **The provider did NOT verify the email** → reject with `403 EMAIL_NOT_VERIFIED`. Nothing is created or modified.
 3. If neither exists → create a new user, link the identity, assign `defaultRole`.
 
+> **IMPORTANT FOR AGENTS:** A second account is **never** silently created for
+> an email that already exists. If asked "does signing in with Google create a
+> duplicate user?", the answer is no — it either links (verified) or errors
+> (unverified). This is **not configurable**; there is deliberately no option to
+> auto-link on unverified emails, because that would let anyone who can make a
+> provider emit an address they don't own take over the matching account.
+> Google always asserts `email_verified` for real Google accounts, so linking
+> is the normal path for Google sign-in.
+
+### Linking a Provider to a Signed-In Account
+
+`POST /api/auth/link/{provider}` attaches a provider identity to the **already
+authenticated** account (requires `Authorization: Bearer <token>`). The body is
+the same payload the provider's sign-in route takes, e.g. `{ idToken }`.
+
+This is the escape hatch from an `EMAIL_NOT_VERIFIED` rejection, and the way to
+attach a provider whose email differs from the account's.
+
+Unlike sign-in, linking here does **not** require a verified email and does not
+require the emails to match — on sign-in the provider's email is the only
+evidence tying the identity to an account, whereas here the caller has already
+proven ownership by holding a valid session.
+
+- `409 IDENTITY_ALREADY_LINKED` if that provider identity belongs to another user.
+- Idempotent (`alreadyLinked: true`) if already linked to the caller.
+
+### Adding a Password to a Provider-Only Account
+
+A user who signed up via OAuth has no `passwordHash`:
+
+- `POST /auth/register` with the same email → `409 EMAIL_EXISTS`.
+- `POST /auth/change-password` → `400 INVALID_ACCOUNT` (no existing password to verify).
+- **`forgot-password` → `reset-password` is the supported path.** It re-proves ownership of the address by email, after which the account has both sign-in methods.
+
 ### Custom OAuth Provider
 
 You can register any OAuth provider by implementing the `OAuthProvider<T>` interface:
@@ -659,6 +696,7 @@ All auth endpoints are mounted under `/api/auth`. Admin endpoints are under `/ap
 | `PATCH` | `/auth/me` | Required | Update profile. Body: `{ displayName?, photoURL? }`. |
 | `POST` | `/auth/change-password` | Required | Change password. Body: `{ oldPassword, newPassword }`. Invalidates all sessions. |
 | `POST` | `/auth/send-verification` | Required | Send email verification link. Requires email service. |
+| `POST` | `/auth/link/{provider}` | Required | Link an OAuth provider to the current account. Body: the provider's sign-in payload (e.g. `{ idToken }`). `409 IDENTITY_ALREADY_LINKED` if it belongs to another user. |
 | `GET` | `/auth/sessions` | Required | List active sessions (refresh tokens). |
 | `DELETE` | `/auth/sessions` | Required | Revoke all sessions (remote logout). |
 | `DELETE` | `/auth/sessions/:id` | Required | Revoke a specific session. |

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

@@ -95,7 +95,7 @@ const { db, pool, connectionString } = createPostgresDatabaseConnection(
 
 **Signature:**
 
-```typescript
+```typescript no-verify
 function createPostgresDatabaseConnection(
     connectionString: string,
     schema?: Record<string, unknown>,
@@ -120,7 +120,7 @@ const readResources = createReadReplicaConnection(
 
 **Signature:**
 
-```typescript
+```typescript no-verify
 function createReadReplicaConnection(
     connectionString: string,
     schema?: Record<string, unknown>,
@@ -145,7 +145,7 @@ const directResources = createDirectDatabaseConnection(
 
 **Signature:**
 
-```typescript
+```typescript no-verify
 function createDirectDatabaseConnection(
     connectionString: string,
     schema?: Record<string, unknown>,
@@ -387,7 +387,8 @@ export const env = loadEnv();
 
 ```typescript
 import dotenv from "dotenv";
-import { loadEnv, z } from "@rebasepro/server";
+import { loadEnv } from "@rebasepro/server";
+import { z } from "zod";
 
 dotenv.config({ path: "../../.env" });
 

package/skills/rebase-collections/SKILL.md

@@ -495,7 +495,7 @@ validation: {
 
 Maps store nested objects as `JSONB` in PostgreSQL. They can define their own inner properties schema.
 
-```typescript
+```typescript no-verify
 address: {
     name: "Address",
     type: "map",
@@ -663,7 +663,7 @@ Every property supports a `validation` object with these common options:
 
 Use the `enum` property on `string` or `number` types to define picklist options:
 
-```typescript
+```typescript no-verify
 status: {
     name: "Status",
     type: "string",
@@ -687,7 +687,7 @@ Each `EnumValueConfig` entry supports:
 
 `EnumValues` can also be a `Record<string, string | EnumValueConfig>` for simpler definitions:
 
-```typescript
+```typescript no-verify
 enum: {
     draft: "Draft",
     published: { label: "Published", color: "green" }

package/skills/rebase-deployment/SKILL.md

@@ -348,7 +348,8 @@ Use the `extend` option to add your own typed env variables on top of the base R
 
 ```typescript
 import dotenv from "dotenv";
-import { loadEnv, z } from "@rebasepro/server";
+import { loadEnv } from "@rebasepro/server";
+import { z } from "zod";
 
 dotenv.config({ path: "../../.env" });
 

package/skills/rebase-design-language/SKILL.md

@@ -202,7 +202,7 @@ The typography scale is compact and uses semibold weights for headings — desig
 
 ### Typography Anti-Patterns
 
-```tsx
+```tsx no-verify
 // ❌ NEVER: Gradient text on headings
 <Typography className="bg-gradient-to-r from-violet-600 to-cyan-500 bg-clip-text text-transparent">
 
@@ -270,7 +270,7 @@ The `Card` component from `@rebasepro/ui` automatically applies `cardMixin` and,
 // cardClickableMixin = "hover:bg-surface-50 dark:hover:bg-surface-800 cursor-pointer transition-colors duration-150"
 ```
 
-```tsx
+```tsx no-verify
 // ✅ CORRECT: Using Card component
 <Card className="p-4">
     <Typography variant="subtitle1">Title</Typography>
@@ -407,7 +407,7 @@ The `Button` component accepts these variants and colors. Buttons use `rounded-l
 
 ### Button Anti-Patterns
 
-```tsx
+```tsx no-verify
 // ❌ NEVER: Casting variant to bypass types
 <Button variant={"standard" as any}>
 
@@ -432,7 +432,7 @@ The `Button` component accepts these variants and colors. Buttons use `rounded-l
 
 ### Use the `Alert` Component
 
-```tsx
+```tsx no-verify
 // ✅ CORRECT
 <Alert color="success" size="small">Lead captured successfully!</Alert>
 <Alert color="error">Could not load dashboard statistics.</Alert>
@@ -508,7 +508,7 @@ When displaying numeric KPIs, use plain muted icons (matching NavigationCard)
 
 ### Metric Card Anti-Patterns
 
-```tsx
+```tsx no-verify
 // ❌ NEVER: Gradient icon backgrounds
 <div className="p-4 bg-gradient-to-br from-blue-500 to-indigo-600 text-white rounded-2xl shadow-lg shadow-blue-500/20">
 
@@ -555,7 +555,7 @@ For larger content sections (like a table, form, or embedded panel), use `Paper`
 
 ### Panel Anti-Patterns
 
-```tsx
+```tsx no-verify
 // ❌ WRONG: Custom panel styling
 <div className="p-6 rounded-2xl border bg-white dark:bg-surface-900/50 backdrop-blur-md shadow-sm">
 

package/skills/rebase-email/SKILL.md

@@ -217,7 +217,7 @@ import {
 
 #### getPasswordResetTemplate
 
-```typescript
+```typescript no-verify
 function getPasswordResetTemplate(
     resetUrl: string,
     user: { email: string; displayName?: string | null },
@@ -229,7 +229,7 @@ The template includes a "Reset Password" button linking to `resetUrl`, a plain-t
 
 #### getEmailVerificationTemplate
 
-```typescript
+```typescript no-verify
 function getEmailVerificationTemplate(
     verifyUrl: string,
     user: { email: string; displayName?: string | null },
@@ -241,7 +241,7 @@ The template includes a "Verify Email Address" button linking to `verifyUrl`.
 
 #### getUserInvitationTemplate
 
-```typescript
+```typescript no-verify
 function getUserInvitationTemplate(
     setPasswordUrl: string,
     user: { email: string; displayName?: string | null },
@@ -253,7 +253,7 @@ Sent when an admin creates a user via `POST /api/admin/users` without specifying
 
 #### getWelcomeEmailTemplate
 
-```typescript
+```typescript no-verify
 function getWelcomeEmailTemplate(
     user: { email: string; displayName?: string | null },
     appName?: string,   // default: "Rebase"

package/skills/rebase-realtime/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: rebase-realtime
-description: Guide for the Rebase WebSocket realtime engine. Use this skill when the user needs real-time data synchronization, broadcast channels, presence tracking, table change broadcasts, or live updates in their application.
+description: Guide for the Rebase WebSocket realtime engine. Use this skill when the user needs real-time data synchronization, broadcast channels, presence tracking, channel message history and reconnect catch-up (collaborative/op-based editing), table change broadcasts, or live updates in their application.
 ---
 
 # Rebase Realtime Engine
 
-Rebase includes a built-in WebSocket-based realtime engine that broadcasts database changes, supports broadcast channels for arbitrary client-to-client messaging, and provides presence tracking for online status.
+Rebase includes a built-in WebSocket-based realtime engine that broadcasts database changes, supports broadcast channels for arbitrary client-to-client messaging (optionally with replayable message history), and provides presence tracking for online status.
 
 > **IMPORTANT FOR AGENTS:** The WebSocket protocol uses specific message types that differ from typical pub/sub patterns. Read the **Message Types** section carefully before generating any WebSocket code. Do NOT invent message type names — use only the types documented here.
 
@@ -68,8 +68,8 @@ Pass `FindParams` as the first argument to filter the subscription:
 ```typescript
 const unsubscribe = client.data.products.listen(
     {
-        where: { status: "published" },
-        orderBy: "created_at:desc",
+        where: { status: ["==", "published"] },
+        orderBy: ["created_at", "desc"],
         limit: 50,
     },
     (response) => {
@@ -120,7 +120,7 @@ const unsubscribe = client.data.products.listenById(
 
 ### `listenById()` Signature
 
-```typescript
+```typescript no-verify
 listenById(
     id: string | number,
     onUpdate: (entity: Entity<M> | undefined) => void,
@@ -148,7 +148,7 @@ In React, use `useEffect` cleanup:
 ```tsx
 useEffect(() => {
     const unsubscribe = client.data.products.listen(
-        { where: { active: true } },
+        { where: { active: ["==", true] } },
         (response) => setProducts(response.data)
     );
     return () => unsubscribe();
@@ -342,6 +342,7 @@ ws.onmessage = (event) => {
 | `presence_track` | `{ channel, state }` | Track presence with custom state (auto-joins channel) |
 | `presence_untrack` | `{ channel }` | Stop tracking presence |
 | `presence_state` | `{ channel }` | Request full presence entity |
+| `channel_history` | `{ channel, sinceSeq?, limit? }` | Request retained messages after `sinceSeq` (retained channels only) |
 | `FETCH_COLLECTION` | `FetchCollectionProps` | One-shot collection fetch (request/response) |
 | `FETCH_ENTITY` | `FetchEntityProps` | One-shot entity fetch |
 | `SAVE_ENTITY` | `SaveEntityProps` | Create or update a entity |
@@ -358,9 +359,10 @@ ws.onmessage = (event) => {
 | `collection_update` | `{ subscriptionId, entities }` | Full collection data (authoritative refetch) |
 | `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 |
+| `broadcast` | `{ channel, event, payload, seq? }` | Broadcast from another channel member. `seq` is present only on retained channels |
 | `presence_state` | `{ channel, presences }` | Full presence entity |
 | `presence_diff` | `{ channel, joins, leaves }` | Incremental presence update |
+| `channel_history` | `{ channel, messages, retained, latestSeq? }` | Retained messages a client missed. `retained: false` means the channel keeps no history |
 | `ERROR` | `{ requestId?, payload: { error: { message, code } } }` | General error |
 | `FETCH_COLLECTION_SUCCESS` | `{ requestId, payload: { entities } }` | Response to FETCH_COLLECTION |
 | `FETCH_ENTITY_SUCCESS` | `{ requestId, payload: { entity } }` | Response to FETCH_ENTITY |
@@ -449,6 +451,63 @@ ws.send(JSON.stringify({
 
 When a client disconnects, they are automatically removed from all channels.
 
+## Channel History and Catch-Up
+
+By default a broadcast reaches currently-connected members and is then gone — correct for cursors and notifications, and it costs nothing. A channel can instead be configured to **retain** its messages, so a reconnecting client catches up on what it missed rather than resyncing. This is what makes channels usable for operation streams (collaborative editing).
+
+> **IMPORTANT FOR AGENTS:** Retention is configured on the **server** and cannot be requested by a client. `{ history: true }` on the client only asks the SDK to *use* history for a channel the server already retains. If the user reports "history isn't working", check the server config first — the symptom of a missing rule is `retained: false`, not an error.
+
+### Server config (required)
+
+```typescript
+createPostgresAdapter({
+    connection: db,
+    schema: { tables, enums, relations },
+    realtime: {
+        channels: [
+            // Most specific first — first match wins.
+            { match: "doc:*", limit: 500, ttl: "24h" }
+        ]
+    }
+})
+```
+
+`match` is an exact channel name or a trailing-`*` prefix — **not** a general glob (`"doc:*:live"` matches nothing). A rule needs at least one of `limit` or `ttl`, or it is ignored and logged; unbounded retention is refused rather than honoured.
+
+`ttl` accepts `"30s"`, `"15m"`, `"24h"`, `"7d"`, or a millisecond number. An unparseable value is ignored with a warning rather than guessed at.
+
+### Client usage
+
+```typescript
+const channel = client.realtime.channel("doc:42", { history: true });
+
+// Replayed messages arrive through the SAME handler, in order.
+channel.onBroadcast("op", (payload) => applyOperation(payload));
+await channel.join();
+```
+
+The SDK requests catch-up on `join()` and after every reconnect, resuming from the highest `seq` it has delivered. Explicit fetch:
+
+```typescript
+const { messages, retained, latestSeq } = await channel.history({ sinceSeq, limit });
+console.log(channel.sequence); // highest seq delivered so far
+```
+
+### Behaviour worth knowing
+
+- **`seq` is per-channel, dense and increasing.** It appears on `BroadcastEvent.seq` only for retained channels; ephemeral broadcasts have no `seq`.
+- **`replayed: true`** marks a message delivered by catch-up rather than live. Handlers usually ignore it.
+- **Replays overlap, and duplicates are dropped by the SDK.** Anything at or below the last delivered sequence is discarded, so handlers never see a message twice.
+- **Your own messages are not filtered out of a replay.** A reconnect assigns a new client id, so filtering by sender would fail in exactly the case catch-up exists for. Operations must be idempotent.
+- **A message that cannot be persisted is not delivered**, and the sender gets a `CHANNEL_HISTORY_WRITE_FAILED` error. Delivering it would leave a gap no replay could repair.
+- **Live messages are held back during catch-up** so ordering holds, bounded by a 10s timeout.
+
+### Storage
+
+Two tables in the `rebase` schema, created on startup only when a rule exists: `rebase.channel_messages` (keyed `(channel, seq)`) and `rebase.channel_cursors`. Pruning removes messages only — cursors are kept forever, because restarting a sequence would change what a client's saved resume point means.
+
+> **Security:** history has the same access model as the channel. Anyone who may join may replay what was said before they arrived. Enabling retention on a publicly-joinable channel makes its past readable to any visitor.
+
 ## Presence Tracking
 
 Presence tracks which users are currently online in a channel, with custom state per user.

package/skills/rebase-sdk/SKILL.md

@@ -150,7 +150,7 @@ await rebase.data.posts.delete('post-123');
 
 // Count
 const total = await rebase.data.posts.count({
-    where: { status: 'eq.published' },
+    where: { status: ['==', 'published'] },
 });
 ```
 
@@ -177,31 +177,39 @@ Pass a params object directly to `.find()`:
 const result = await rebase.data.posts.find({
     limit: 20,
     offset: 0,
-    orderBy: 'createdAt:desc',
+    orderBy: ['createdAt', 'desc'],
     searchString: 'search term',
     include: ['tags', 'author'],   // or ['*'] for all relations
     where: {
-        status: 'eq.published',
-        price: 'gte.100',
-        category: 'in.(electronics,books)',
+        status: ['==', 'published'],
+        price: ['>=', 100],
+        category: ['in', ['electronics', 'books']],
     },
 });
 ```
 
-### Filter Operators (String Syntax)
+### Filter Operators (Tuple Syntax)
+
+Every filter is a `[operator, value]` tuple. The bare-string and
+`'eq.published'` wire formats are **not** part of the public API: they are
+`WireFilterValues`, marked `@internal`, and `serializeFilter` passes such a
+string straight through to PostgREST unchanged — so an operator-less value
+silently produces a malformed query rather than an error.
 
 | Operator | Description | Example |
 |----------|-------------|---------|
-| `eq` | Equal | `'eq.published'` |
-| `neq` | Not equal | `'neq.draft'` |
-| `gt` | Greater than | `'gt.100'` |
-| `gte` | Greater than or equal | `'gte.100'` |
-| `lt` | Less than | `'lt.50'` |
-| `lte` | Less than or equal | `'lte.50'` |
-| `in` | In list | `'in.(electronics,books)'` |
-| `nin` | Not in list | `'nin.(archived,deleted)'` |
-| `cs` | Array contains | `'cs.tag1'` |
-| `csa` | Array contains any | `'csa.(tag1,tag2)'` |
+| `==` | Equal | `['==', 'published']` |
+| `!=` | Not equal | `['!=', 'draft']` |
+| `>` | Greater than | `['>', 100]` |
+| `>=` | Greater than or equal | `['>=', 100]` |
+| `<` | Less than | `['<', 50]` |
+| `<=` | Less than or equal | `['<=', 50]` |
+| `in` | In list | `['in', ['electronics', 'books']]` |
+| `not-in` | Not in list | `['not-in', ['archived', 'deleted']]` |
+| `array-contains` | Array contains | `['array-contains', 'tag1']` |
+| `array-contains-any` | Array contains any | `['array-contains-any', ['tag1', 'tag2']]` |
+| `like` / `ilike` | Pattern match (SQL wildcards) | `['ilike', '%john%']` |
+| `is-null` / `is-not-null` | Null checks (value ignored) | `['is-null', null]` |
 
 ### Approach 2: Fluent QueryBuilder
 
@@ -352,7 +360,7 @@ unsubscribe();
 ```typescript
 // Via CollectionClient
 const unsubscribe = rebase.data.posts.listen(
-    { where: { status: 'published' }, limit: 50 },
+    { where: { status: ['==', 'published'] }, limit: 50 },
     (response) => {
         // response: FindResponse with updated data
         console.log('Updated posts:', response.data);

package/skills/rebase-security/SKILL.md

@@ -316,7 +316,7 @@ For full documentation on collection callbacks, see the `rebase-collections` ski
 Rebase follows a **fail-closed** security model throughout the stack:
 
 1. **Scoped driver or nothing** — The REST API's `getScopedDriver()` throws if no scoped driver is available. It **never** falls back to the unscoped driver:
-   ```typescript
+   ```typescript no-verify
    private getScopedDriver(c): DataDriver {
        const driver = c.get("driver") as DataDriver | undefined;
        if (!driver) throw ApiError.internal("Scoped driver not available");

package/skills/rebase-storage/SKILL.md

@@ -332,7 +332,7 @@ STORAGE_GCS_BUCKET=my-bucket
 ```
 
 ❌ **Anti-pattern (never do this in app/backend code):**
-```typescript
+```typescript no-verify
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";   // ❌
 const s3 = new S3Client({ region, endpoint });                     // ❌ hardcodes S3
 await s3.send(new PutObjectCommand({ Bucket, Key, Body }));        // ❌ bypasses rebase.storage

package/skills/rebase-ui-components/SKILL.md

@@ -31,7 +31,7 @@ The package exports five modules:
 export * from "./components";  // All UI components
 export * from "./styles";      // Tailwind style mixin strings
 export * from "./util";        // cls(), debounce(), chip_colors, keyToIconComponent
-export * from "./icons";       // Icon component, iconSize, lucideIcons map, icon_keys, cool_icon_keys
+export * from "./icons";       // Icon component, iconSize, lucideIcons map, iconKeys, cool_icon_keys
 export * from "./hooks";       // React hooks
 ```
 
@@ -1149,13 +1149,13 @@ const IconComponent = lucideIcons["Database"]; // LucideIcon component
 <IconComponent size={24} />
 ```
 
-### `icon_keys` and `cool_icon_keys`
+### `iconKeys` and `cool_icon_keys`
 
-- **`icon_keys`** — Array of ~1900+ all available Lucide icon name strings.
+- **`iconKeys`** — Array of ~1900+ all available Lucide icon name strings.
 - **`cool_icon_keys`** — Curated subset of ~50 visually distinctive icon names for icon pickers.
 
 ```tsx
-import { icon_keys, coolIconKeys, lucideIcons } from "@rebasepro/ui";
+import { iconKeys, coolIconKeys, lucideIcons } from "@rebasepro/ui";
 ```
 
 ### `keyToIconComponent(key: string): string`
@@ -1265,7 +1265,7 @@ debouncedSearch.clear(); // Cancel pending call
 Deterministic 32-bit hash of a string. Returns a positive integer.
 
 ```tsx
-import { hashString } from "@rebasepro/ui";
+import { hashString } from "@rebasepro/utils";
 hashString("my-entity-id"); // e.g. 1234567
 ```
 
@@ -1280,7 +1280,7 @@ import {
 ```
 
 **`ChipColorScheme`** type:
-```ts
+```ts no-verify
 {
     color: string;      // Light mode background hex
     text: string;       // Light mode text hex