@abloatai/ablo 0.50.0 → 0.52.0

package/docs/groups.md

@@ -45,17 +45,17 @@ questions. Pick by the question you have.
 
 ```ts
 // A screen that stays current.
-ablo.documents.onChange((docs) => render(docs));
+ablo.records.onChange((docs) => render(docs));
 
 // Who else is in here, and what are they holding.
-await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
+await using room = await ablo.records.join(documentIds, { ttl: '5m' });
 room.peers;
 
 // Stop this write if the thing I read moved while I composed it.
 await ablo.blocks.update({ id, data, reads: [{ group: 'workspace:abc', readAt, onStale: 'notify' }] });
 
 // Tell me later if this moves, even though I am not writing now.
-await ablo.documents.track({ id: 's-1' });
+await ablo.records.track({ id: 's-1' });
 ```
 
 | Question | Channel | Arrives |
@@ -139,7 +139,7 @@ reaches `C`.
 The direction matters. The signal flows forward, A to B to C, and each hop is a
 real write an actor chose to make. The engine supplies the edges (group
 membership) and a stale signal on each edge (the premise check); the actors are
-the runtime that walks them. It is closer to a spreadsheet an analyst
+the runtime that walks them. It is closer to a dataset an analyst
 recalculates cell by cell than to a reactive engine that recomputes the whole
 column for you.
 
@@ -206,7 +206,7 @@ you, arriving on the write you were going to make anyway.
 
 ```ts
 // Register interest and walk away — no write required.
-await ablo.documents.track({ id: 's-1' });
+await ablo.records.track({ id: 's-1' });
 
 // …minutes of other work later, on your next commit…
 const res = await ablo.blocks.update({ id: 'block-C', data: { text: revised } });
@@ -223,7 +223,7 @@ You can also register a track as part of a write you are already making, the
 persisted companion to `reads`:
 
 ```ts
-await ablo.documents.update({
+await ablo.records.update({
   id: 's-1',
   data: { title: revised },
   reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
@@ -242,8 +242,8 @@ A track says what a moved belief should do to your **next write**. Same enum the
 `reads` premise carries, minus the one mode that cannot apply:
 
 ```ts
-await ablo.documents.track({ id: 's-1' });                        // notify (default)
-await ablo.documents.track({ id: 's-1', onStale: 'reject' });     // gate
+await ablo.records.track({ id: 's-1' });                        // notify (default)
+await ablo.records.track({ id: 's-1', onStale: 'reject' });     // gate
 ```
 
 - **`notify`** — the change rides your next receipt and the commit proceeds. You
@@ -263,12 +263,12 @@ re-read, then re-register the track to say so:
 
 ```ts
 try {
-  await ablo.tasks.update({ id, data });
+  await ablo.records.update({ id, data });
 } catch (err) {
   if (err.code === 'stale_context') {
-    const fresh = await ablo.documents.get({ id: 's-1' });   // read
-    await ablo.documents.track({ id: 's-1', onStale: 'reject' }); // acknowledge
-    await ablo.tasks.update({ id, data: reconsider(fresh) });     // now it lands
+    const fresh = await ablo.records.get({ id: 's-1' });   // read
+    await ablo.records.track({ id: 's-1', onStale: 'reject' }); // acknowledge
+    await ablo.records.update({ id, data: reconsider(fresh) });     // now it lands
   }
 }
 ```

package/docs/how-it-works.md

@@ -7,10 +7,10 @@ whole model — everything below explains what it means and how to use it.
 
 ```ts
 // You call Ablo. Ablo lands the change in your database and confirms it.
-await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
+await ablo.records.update({ id: 'record_42', data: { status: 'done' } });
 
 // Reads come back live, kept current from your database.
-const task = ablo.tasks.local.get('task_42');
+const record = ablo.records.local.get('record_42');
 ```
 
 ## The mental model: read this once
@@ -90,17 +90,17 @@ export const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 // 5. Write through Ablo. Local state changes immediately; await blocks until
 //    the authoritative feed proves the row is there.
-await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
+await ablo.records.update({ id: 'record_42', data: { status: 'done' } });
 
 // 6. Read — live, no fetch loop.
-const task = ablo.tasks.local.get('task_42');
+const record = ablo.records.local.get('record_42');
 
 // 7. Coordinate when more than one actor can touch a row. Hold a claim and Ablo
 //    serializes writes on that key against everyone else; read after claiming,
 //    then write. The lease releases automatically at the end of the scope.
-await using _hold = await ablo.tasks.claim('task_42');
-const latest = ablo.tasks.local.get('task_42'); // read after claiming, not from memory
-await ablo.tasks.update({ id: 'task_42', data: { status: 'done' } });
+await using _hold = await ablo.records.claim('record_42');
+const latest = ablo.records.local.get('record_42'); // read after claiming, not from memory
+await ablo.records.update({ id: 'record_42', data: { status: 'done' } });
 ```
 
 For the setup details, see [Connect Your Database](./data-sources.md). For the

package/docs/idempotency.md

@@ -10,10 +10,10 @@ retry safe automatically. It cannot make a retry across a process restart safe,
 process generates a new key — so for anything that must survive a crash, supply your own.
 
 ```ts
-await ablo.tasks.update({
-  id: taskId,
+await ablo.records.update({
+  id: recordId,
   data: { status: 'done' },
-  idempotencyKey: `task:${taskId}:mark-done:v1`,
+  idempotencyKey: `record:${recordId}:mark-done:v1`,
 });
 ```
 
@@ -22,7 +22,7 @@ await ablo.tasks.update({
 **Derive the key from the business event, not from the attempt.** A key built from
 `crypto.randomUUID()` at the call site is regenerated on every retry, so it protects nothing — each
 attempt looks like a new intention and the write lands twice. A key built from the thing that
-happened (`task:42:mark-done:v1`) is identical on every retry by construction, which is the whole
+happened (`record:42:mark-done:v1`) is identical on every retry by construction, which is the whole
 point.
 
 The same rule stated as its failure: never derive a key from a timestamp, an attempt counter, or a

package/docs/identity.md

@@ -38,7 +38,7 @@ scoped operation throws `CapabilityError`; compare its
 
 ```ts
 try {
-  await ablo.tasks.update({ id, data: { status: 'done' } });
+  await ablo.records.update({ id, data: { status: 'done' } });
 } catch (error) {
   if (error instanceof CapabilityError) {
     console.error('missing grant', error.requiredCapability);
@@ -53,7 +53,7 @@ typed grant:
 ```ts
 const session = await control.sessions.create({
   agent: { id: agentId },
-  can: { tasks: ['read', 'update'] },
+  can: { records: ['read', 'update'] },
   syncGroups: [syncGroup('workspace', workspaceId)],
 });
 ```
@@ -106,7 +106,7 @@ export const schema = defineSchema(
     ),
     // A child: it has no group of its own; it inherits its workspace's group via the
     // `parent` edge. A write to a document reaches everyone viewing the workspace.
-    documents: model(
+    records: model(
       { workspaceId: z.string() },
       { relations: { workspace: relation.belongsTo('workspaces', 'workspaceId', { parent: true }) } },
     ),
@@ -158,7 +158,7 @@ things:
 - **Membership groups:** named after *who you are*: `org:{id}`, `team:{id}`,
   `user:{id}`. Produced from **identity** (`identityRoles`, Half 1). They're
   standing and durable — they don't change as you work.
-- **Entity groups:** named after *a thing*: `dataroom:{id}`, `workspace:{id}`,
+- **Entity groups:** named after *a thing*: `archive:{id}`, `workspace:{id}`,
   `document:{id}`. Produced from a **row's id** (a model's entity scope, Half 2).
   They're granular — one per record — and any participant can be pointed at a
   specific set of them.
@@ -171,7 +171,7 @@ they are, so you declare them once in the schema.
 | | Subscribed by | Declared where | Gets |
 | --- | --- | --- | --- |
 | **Human** | *who they are*: membership | **the schema** (`identityRoles`): a rule, written once | every `org` / `team` / `user` group their identity implies: their whole standing world |
-| **Agent** | *what it's been given*: entities | **code, at the spawn site**: chosen per run | a handful of entity groups: the dataroom it's in, the documents it has read: never beyond what its user's membership could reach |
+| **Agent** | *what it's been given*: entities | **code, at the spawn site**: chosen per run | a handful of entity groups: the archive it's in, the documents it has read: never beyond what its user's membership could reach |
 
 > **One line:** humans subscribe by who they are; agents subscribe by what
 > they've been given.
@@ -210,25 +210,24 @@ The default is simple: your schema lives in a **project**, you push it once, and
 every session you mint resolves against it. Your end-users **don't have Ablo
 accounts** — your server's `sk_` mints an `ek_` per user, and by default that
 session lands in your project's own org. All your users share one schema, one
-data tenant, isolated from each other by sync-groups. That's the whole story for
-most apps.
+data tenant, and receive targeted realtime changes through sync-groups. Model
+`policy` declarations govern which rows they may read; sync-groups are delivery
+routing, not read authorization. That's the whole story for most apps.
 
 **Add-on — org-per-customer isolation.** If you need each customer to be its own
 hard tenant (separate row-level isolation, optionally a separate database) you'd
-otherwise have to re-push your schema into every customer's org. Instead, keep one
-project as the home of your schema and point each customer's session's *schema*
-at it while its *data* stays in the customer's org:
+otherwise have to re-push your schema into every customer's org. Instead, keep
+one project as the home of your schema. A cross-organization mint automatically
+uses the owning key's project for the session's *schema* while its *data*
+stays in the customer's org:
 
 ```ts
-await mintUserSessionKey({
-  apiKey: platformKey,   // sk_ with the `ephemeral:mint-any-org` scope
-  userId,
-  organizationId,                  // DATA → this customer's org (RLS-isolated tenant)
-  schemaProject: {                 // SCHEMA → the project that owns your schema
-    organizationId: schemaOwnerOrgId,
-    projectId: schemaProjectId,
-  },
-  operations: ['task.read', 'task.update'],
+const server = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+await server.sessions.create({
+  user: { id: userId },
+  organizationId, // DATA → this customer's RLS-isolated organization
+  can: { records: ['read', 'update'] },
   ttlSeconds: 3600,
 });
 ```
@@ -236,15 +235,23 @@ await mintUserSessionKey({
 Server-side, the model **shape** loads from your schema project but column
 enrichment and the tenant connection still target `organizationId` — so the
 shared schema only *describes* the shape; the data plane stays the customer's and
-can't cross-leak. Omit these fields for the default above. Requires a platform
-`sk_` with `ephemeral:mint-any-org`.
+can't cross-leak. `schemaProject: { organizationId, projectId }` remains
+available as an explicit override for migrations or advanced routing. Omit
+`organizationId` for the single-organization default above. Requires a dedicated
+`sk_` with `ephemeral:mint-any-org`; see
+[Customer Organizations](./customer-organizations.md).
 
 ## The two halves of scoping
 
-Scoping is two declarations that meet in the middle. One describes the
+Delivery scoping is two declarations that meet in the middle. One describes the
 **participant** (what may I subscribe to?), the other describes each **row**
-(which group does this row belong to?). A participant sees a row **iff** the
-row's sync group is in the participant's allowed set.
+(which group does this row belong to?). A participant receives a row's realtime
+changes when the row's sync groups intersect the participant's allowed set.
+
+That intersection does not itself authorize an HTTP read. A model's `policy`
+governs read access. Treat sync-groups as change routing and `policy` (plus the
+organization boundary beneath it) as authorization; declaring one never
+silently creates the other.
 
 ### Half 1 (`identityRoles`): identity → allowed groups
 
@@ -296,7 +303,7 @@ declarations, in order of how often you reach for them:
 **`groups.root` — this model is a scope root.** Its rows form a group of their
 own. The kind comes from the model's `typename` by default, or pass a string to
 set it explicitly (use the string form when the wire kind differs from the
-typename, e.g. typename `SlideDeck` but group `workspace:<id>`):
+typename, e.g. typename `EntryCollection` but group `workspace:<id>`):
 
 ```ts
 workspaces: model({ title: z.string() }, { groups: { root: 'workspace' } });
@@ -311,24 +318,24 @@ viewing the root. A *reference* (a provenance/template pointer, not ownership)
 must **not** be marked `parent`, or the row would leak into an unrelated scope:
 
 ```ts
-documents: model(
-  { workspaceId: z.string(), sourceSlideId: z.string().optional() },
+records: model(
+  { workspaceId: z.string(), sourceEntryId: z.string().optional() },
   {
     // default policy: row-local organization_id
     relations: {
       workspace: relation.belongsTo('workspaces', 'workspaceId', { parent: true }),  // ownership → inherit workspace:<id>
-      sourceSlide: relation.belongsTo('documents', 'sourceSlideId'),     // reference → NOT routed
+      sourceEntry: relation.belongsTo('documents', 'sourceEntryId'),     // reference → NOT routed
     },
   },
 );
 ```
 
 > **Declare the parent edge — don't infer it.** Optionality is not a proxy for
-> ownership: many `parent` FKs are optional (a root folder, an inbox task), and
+> ownership: many `parent` FKs are optional (a root folder, an inbox record), and
 > some required FKs are mere references. Containment is a fact only you know, so
 > it's declared, exactly as it is in OpenFGA/Zanzibar.
 
-**`groups.grants` — a membership edge.** On a join model (e.g. `dataroomMember`),
+**`groups.grants` — a membership edge.** On a join model (e.g. `archiveMember`),
 it says "this row grants a *subject* access to a *scope root*." Both are relation
 names on the model. The server resolves it at connect time — for user `U`, it
 finds the scope-root groups `U` is a member of and adds them to `U`'s allowed
@@ -336,12 +343,12 @@ set (Linear's `/sync/user_sync_groups`). Use this for sub-org sharing; plain
 org membership is already covered by the `org:` identity role.
 
 ```ts
-dataroomMember: model(
-  { userId: z.string(), dataroomId: z.string() },
+archiveMember: model(
+  { userId: z.string(), archiveId: z.string() },
   {
     relations: {
       member: relation.belongsTo('users', 'userId'),
-      room: relation.belongsTo('datarooms', 'dataroomId'),
+      room: relation.belongsTo('archives', 'archiveId'),
     },
     groups: { grants: { subject: 'member', scope: 'room' } },
   },
@@ -485,7 +492,7 @@ an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
-documents: model({ /* … */ }, { groups: { root: 'document' } }),
+records: model({ /* … */ }, { groups: { root: 'document' } }),
 workspaces:     model({ /* … */ }, { groups: { root: 'workspace' } }),
 ```
 
@@ -499,7 +506,7 @@ subset of what its user could see:
 const session = await server.sessions.create({
   agent: { id: agentId },
   can: { Document: ['read', 'update'], Workspace: ['read', 'update'] },
-  syncGroups: [syncGroup('document', documentId), syncGroup('workspace', workspaceId)],
+  syncGroups: [syncGroup('document', recordId), syncGroup('workspace', workspaceId)],
 });
 // identity (the ceiling) is inherited from the triggering user via your
 // session-mint logic; the agent runtime connects with the minted token.
@@ -526,7 +533,7 @@ than needing a separate agent permission system:
 - **Inherit the user, and no more:** the OAuth
   [on-behalf-of](https://workos.com/blog/oauth-on-behalf-of-ai-agents) model: the
   agent's reach is tied to the consenting user, never the org.
-- **Least privilege, just-in-time:** scoped to the task's entities, not standing
+- **Least privilege, just-in-time:** scoped to the record's entities, not standing
   org-wide access (the over-privilege pattern
   [OWASP's NHI Top 10](https://www.token.security/assets/the-ultimate-non-human-identity-security-guide)
   flags as the dominant agent risk).
@@ -557,8 +564,8 @@ an agent pointed at the entities it's working on. You **never hand-write**
      agent: { id: agentId },
      can: { Workspace: ['read', 'update'], Document: ['read'] },
      syncGroups: [
-       syncGroup('workspace', deckA),
-       syncGroup('workspace', deckB),
+       syncGroup('workspace', collectionA),
+       syncGroup('workspace', collectionB),
        syncGroup('document', docId),
      ],
    });

package/docs/index.md

@@ -155,6 +155,7 @@ default caller, not a special one.
 - [Projects](./projects.md) — one organization, many apps; each with its own schema, planes, and keys.
 - [API Keys](./api-keys.md) — the credential that carries an agent's identity and its scopes.
 - [Sessions](./sessions.md) — short-lived scoped credentials your backend mints.
+- [Customer Organizations](./customer-organizations.md) — serve many isolated customer organizations from one schema and backend.
 - [Audit Log](./audit.md) — trace any confirmed write back to the person behind it.
 - [Operating on Your Database](./operating-on-your-database.md) — which actions run freely, which to verify first, and which belong to a human.
 - [Session Settings](./session-settings.md) — point your row-level-security policies at Ablo's writes, by naming the settings they already read.
@@ -163,7 +164,7 @@ default caller, not a special one.
 
 - [Quickstart](./quickstart.md) — make your first coordinated write.
 - [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
-- [Integrations](./integrations.md) — long-running tasks, ingestion, and other application-edge runtimes.
+- [Integrations](./integrations.md) — long-running records, ingestion, and other application-edge runtimes.
 - [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
 - [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
 - [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.

package/docs/integration-guide.md

@@ -215,7 +215,7 @@ export async function POST() {
   const session = await auth(); // your own auth — returns the signed-in user
   const { token, expiresAt } = await sync.sessions.create({
     user: { id: session.userId },
-    can: { tasks: ['read', 'update'] },
+    can: { records: ['read', 'update'] },
   });
   return Response.json(
     credentialEndpointSuccessSchema.parse({

package/docs/integrations/inngest.md

@@ -1,6 +1,6 @@
-# Inngest for long-running tasks
+# Inngest for long-running records
 
-> Run event-driven, retryable agent tasks with Inngest while Ablo makes each
+> Run event-driven, retryable agent records with Inngest while Ablo makes each
 > shared-state effect typed, idempotent, and authoritative.
 
 Inngest and Ablo solve different parts of a durable agent system:

package/docs/integrations/temporal.md

@@ -1,6 +1,6 @@
-# Temporal for long-running tasks
+# Temporal for long-running records
 
-> Run long-lived, retryable agent tasks with Temporal while Ablo makes each
+> Run long-lived, retryable agent records with Temporal while Ablo makes each
 > shared-state effect typed, idempotent, and authoritative.
 
 Temporal and Ablo solve different parts of a durable agent system:
@@ -10,7 +10,7 @@ Temporal and Ablo solve different parts of a durable agent system:
 | Workflow history, replay, timers, retries, cancellation | Temporal |
 | Provider, messages, tools, approval, model loop | AI SDK |
 | Typed reads and writes, idempotency, claims, confirmation | Ablo |
-| Workflow names, task queues, retry policy, business behavior | Your application |
+| Workflow names, record queues, retry policy, business behavior | Your application |
 
 The short version is:
 

package/docs/integrations.md

@@ -13,8 +13,8 @@ into authoritative application state.
 
 | Category | Integration | Status | Use it for |
 |---|---|---|---|
-| Long-running tasks | [Temporal](./integrations/temporal.md) | Available | Durable Workflows, Activity retries, timers, cancellation, and durable AI SDK calls |
-| Long-running tasks | [Inngest](./integrations/inngest.md) | Available | Event-driven durable functions, retriable steps, flow control, and checkpointed AI SDK calls |
+| Long-running records | [Temporal](./integrations/temporal.md) | Available | Durable Workflows, Activity retries, timers, cancellation, and durable AI SDK calls |
+| Long-running records | [Inngest](./integrations/inngest.md) | Available | Event-driven durable functions, retriable steps, flow control, and checkpointed AI SDK calls |
 | Data ingestion | Connector runtimes | Planned | Bringing external data into Ablo-backed models without creating a second write authority |
 
 An integration gets its own guide when there is runnable application code and
@@ -22,7 +22,7 @@ the boundary has been tested. A dedicated package comes later still: only
 repeated production integrations that reveal substantial reusable behavior
 justify adding another public runtime dependency.
 
-## Long-running tasks
+## Long-running records
 
 Use [Temporal](./integrations/temporal.md) when work must survive process
 failure, retry Activities, wait on timers, or preserve a durable model loop.

package/docs/react.md

@@ -201,9 +201,9 @@ write interest in it.
 
 import { useJoin } from '@abloatai/ablo/react';
 
-export function DeckPresence({ workspaceId }: { workspaceId: string }) {
+export function CollectionPresence({ workspaceId }: { workspaceId: string }) {
   const { peers, claims, status } = useJoin({
-    scope: { slideDecks: workspaceId },
+    scope: { entryCollections: workspaceId },
     claim: true,   // I intend to write — pin the scope + let peers observe the claim
     hydrate: true, // backfill the workspace's current rows if not already loaded
   });
@@ -217,7 +217,7 @@ Options (`UseJoinOptions`):
 
 | Option | Default | Effect |
 | --- | --- | --- |
-| `scope` |: | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
+| `scope` |: | Model-form scope (`{ entryCollections: id }`), resolved through the schema. Omit for engine-wide. |
 | `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant: leave `false` for read-only. |
 | `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
 | `ttlSeconds` |: | Lease TTL for the scope claim. |
@@ -241,7 +241,7 @@ connection is subscribed to.
 import { usePeers } from '@abloatai/ablo/react';
 
 export function CursorBroadcaster({ workspaceId }: { workspaceId: string }) {
-  const peers = usePeers({ slideDecks: workspaceId });
+  const peers = usePeers({ entryCollections: workspaceId });
   const alone = !peers.some((p) => p.participantKind === 'user');
   // suppress live-cursor broadcasts while alone
 }

package/docs/sessions.md

@@ -13,13 +13,13 @@ One resource mints both:
 // A logged-in person's browser session — only the operations this UI needs.
 const userSession = await ablo.sessions.create({
   user: { id: currentUser.id },
-  can: { tasks: ['read', 'update'], workspaces: ['read'] },
+  can: { records: ['read', 'update'], workspaces: ['read'] },
 });
 
 // Recommended agent path — returns a ready, scoped client.
 const agent = await ablo.agents.create({
-  name: 'task-writer',
-  can: { tasks: ['read', 'update'], workspaces: ['read'] },
+  name: 'record-writer',
+  can: { records: ['read', 'update'], workspaces: ['read'] },
 });
 ```
 
@@ -51,7 +51,7 @@ import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
 
 const { token, expiresAt } = await ablo.sessions.create({
   user: { id: currentUser.id },   // who the session acts as
-  can: { tasks: ['read', 'update'] },
+  can: { records: ['read', 'update'] },
   // syncGroups: [...],           // optional; defaults to the user's org + user
 });
 return Response.json(
@@ -104,18 +104,18 @@ error, not a silent over-grant:
 
 ```ts
 const agent = await ablo.agents.create({
-  name: 'task-writer',
-  can: { tasks: ['update'] },  // typed off the schema — no magic strings
+  name: 'record-writer',
+  can: { records: ['update'] },  // typed off the schema — no magic strings
   ttlSeconds: 600,
 });
 
-await agent.tasks.update({ id, data });
+await agent.records.update({ id, data });
 await agent.dispose();
 ```
 
 The returned client refreshes its own short-lived credential. A write grant
 automatically includes the corresponding read, so
-`can: { tasks: ['update'] }` is enforced as `task.update` plus `task.read`.
+`can: { records: ['update'] }` is enforced as `record.update` plus `record.read`.
 Operations are `'read' | 'create' | 'update' | 'delete'`.
 
 For a reusable grant, use TypeScript's `satisfies`. It checks the object against
@@ -126,14 +126,14 @@ second permission model:
 import type { CapabilityGrant } from '@abloatai/ablo/auth';
 import { schema } from './ablo.schema';
 
-const taskWriterCan = {
-  tasks: ['update'],
+const recordWriterCan = {
+  records: ['update'],
 } satisfies CapabilityGrant<typeof schema>;
 
-const agent = await ablo.agents.create({ can: taskWriterCan });
+const agent = await ablo.agents.create({ can: recordWriterCan });
 ```
 
-`documents` instead of `tasks`, or `'write'` instead of `'update'`, is a compile
+`documents` instead of `records`, or `'write'` instead of `'update'`, is a compile
 error. At runtime the SDK parses the same grant with the schema-bound Zod
 contract before minting, and the server validates it again against the active
 pushed schema.
@@ -154,6 +154,8 @@ for the actor.
 |---|---|---|
 | `user` / `agent` | both | The actor. `id` becomes the token's `participantId`. Pass exactly one. |
 | `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
+| `organizationId` | user | Mint into a customer organization instead of the key's own. Requires `ephemeral:mint-any-org`. |
+| `schemaProject` | user | Override the schema project for a cross-org mint. Usually omitted because the owning key's project is the default. |
 | `syncGroups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
 | `userMeta` | both | Opaque identity blob echoed back to the client. |
@@ -217,7 +219,7 @@ errors.
 
 A user session carries the user's **base** sync-groups (`org:`/`user:`/`team:`),
 derived from the identity you minted it for. **Dynamic, relation-driven
-membership** (e.g. a `dataroom:<id>` the user was just added to) is resolved
+membership** (e.g. a `archive:<id>` the user was just added to) is resolved
 **server-side at connect** and unioned on top — so scope stays live, not frozen
 at mint time. Pass `syncGroups` only when you want to *narrow* below the default.
 
@@ -243,25 +245,40 @@ Some apps need each customer to be its **own** tenant — a hard data boundary
 scoping. The law-firm shape (Legora): every firm is its own org, many users
 inside it.
 
+Choose the boundary before minting sessions:
+
+| Customer model | Isolation guarantee | Use when |
+|---|---|---|
+| One Ablo organization, customer scope roots | Every model's declared `policy` | Cross-customer access is intentional or every model explicitly partitions by the customer root |
+| One Ablo organization per customer | Structural organization filtering and RLS on every row | Customers must be isolated even when a model has no customer policy |
+
+Sync-group routing controls which changes are delivered; it does not grant or
+deny reads. Do not use scope roots as a tenant security boundary unless every
+model declares the matching policy. If that invariant is difficult to audit,
+use one organization per customer.
+
+For the complete key, backend-route, browser, lifecycle, and troubleshooting
+flow, see [Customer Organizations](./customer-organizations.md).
+
 The problem that creates: if each customer is a separate org, a naïve setup would
 make you re-push your schema into every new customer's org. You don't have to.
-Keep **one** project as the home of your schema, and point each customer's
-session's *schema* at it while its *data* stays in the customer's own org:
+Keep **one** project as the home of your schema. When its key mints into another
+organization, Ablo automatically resolves the session's *schema* from that key's
+project while its *data* stays in the customer's own org:
 
 ```ts
-const { token } = await mintUserSessionKey({
-  apiKey: process.env.ABLO_PLATFORM_KEY, // sk_ with the ephemeral:mint-any-org scope
-  userId,
-  organizationId,                  // DATA → this customer's org (its own isolated tenant)
-  schemaProject: {                 // SCHEMA → the project that owns your schema
-    organizationId: schemaOwnerOrgId,
-    projectId: schemaProjectId,
-  },
-  operations: ['task.read', 'task.update'],
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_PLATFORM_KEY });
+const { token } = await ablo.sessions.create({
+  user: { id: userId },
+  organizationId, // DATA → this customer's isolated org
+  can: { records: ['read', 'update'] },
   ttlSeconds: 3600,
 });
 ```
 
+For migrations or advanced routing, `sessions.create` also accepts an explicit
+`schemaProject: { organizationId, projectId }` override.
+
 Server-side the split is clean: the model **shape** loads from your schema
 project, but column enrichment and the tenant connection target the customer's
 `organizationId` — so the shared schema only *describes* the shape; the data
@@ -269,10 +286,10 @@ plane (connection + row-level isolation) stays the customer's. A shared schema
 can't leak data across orgs.
 
 <Note>
-This requires a platform `sk_` carrying the `ephemeral:mint-any-org` scope —
-only a trusted first-party key can mint a session into another org and bind its
-schema to your project. Omit these fields and you get the default above: one
-project, one schema, all your users.
+This requires a dedicated `sk_` carrying the `ephemeral:mint-any-org` scope —
+only a trusted cross-organization key can mint a session into another org. Omit
+`organizationId` and you get the default above: one project, one schema, all
+your users in the key's own organization.
 </Note>
 
 ## Security

package/docs/webhooks.md

@@ -39,7 +39,7 @@ Every delivery is a batch of events. Each event:
 
 | field | meaning |
 |---|---|
-| `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `task.updated` |
+| `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `record.updated` |
 | `model` | the model name exactly as declared in your schema: the table to write |
 | `objectId` | the changed row's id |
 | `data` | the post-change row, or `null` on delete |
@@ -127,7 +127,7 @@ Scope which models fire and label the endpoint at creation with `--events` and
 
 ```bash
 npx ablo webhooks create https://yourapp.com/api/ablo/[...all] \
-  --events task,project --description "prod mirror"
+  --events record,project --description "prod mirror"
 ```
 
 Manage and inspect endpoints:

package/examples/README.md

@@ -30,13 +30,13 @@ For read-reason-write work, pass the exact returned rows that informed the
 decision. Their watermarks stay opaque:
 
 ```ts
-const task = await ablo.tasks.get({ id: taskId });
+const record = await ablo.records.get({ id: recordId });
 const policy = await ablo.policies.get({ id: policyId });
-const result = await model({ task, policy });
-await ablo.tasks.update({
-  id: task.id,
+const result = await model({ record, policy });
+await ablo.records.update({
+  id: record.id,
   data: result,
-  reads: [task, policy],
+  reads: [record, policy],
 });
 ```
 
@@ -61,7 +61,7 @@ root and a bare `quickstart.ts` won't be found.
 ```bash
 cd packages/ablo
 ABLO_API_KEY=sk_... npx tsx examples/quickstart.ts
-ABLO_API_KEY=sk_... TASK_ID=task_... npx tsx examples/agent-turn.ts
+ABLO_API_KEY=sk_... RECORD_ID=record_... npx tsx examples/agent-turn.ts
 ABLO_API_KEY=sk_... JOB_ID=job_... npx tsx examples/expensive-agent-turn.ts
 ```