@abloatai/ablo 0.11.2 → 0.13.0

package/dist/schema/tenancy.js

@@ -1,22 +1,36 @@
 /**
  * Tenancy — the single source of truth for how a model's rows are scoped to a
- * tenant. This replaces three scattered mechanisms (a hardcoded
- * `organization_id` literal, an `orgScoped` boolean, and a `scopedVia` ref) with
- * one Zod discriminated union, resolved in one place and consumed everywhere
- * (provision/RLS, introspection, runtime, CLI).
+ * tenant. There are exactly two layers here, and keeping them separate is the
+ * whole point:
  *
- * Why a union: every consumer used to re-derive "how is this table scoped?" from
- * a flag plus a literal — a missed branch was a silent cross-tenant scoping bug.
- * A discriminated union makes the `switch` exhaustive, so the type system holds
- * the isolation boundary, and the physical column name lives in exactly one
- * place (the `column` variant) instead of being hardcoded across the codebase.
+ *   1. The CANONICAL form — {@link Tenancy}, a Zod discriminated union. This is
+ *      what every consumer (provision/RLS, introspection, runtime, CLI) reads
+ *      and what crosses the wire in `ModelJSON`. One shape, exhaustively
+ *      switchable, so the type system holds the isolation boundary.
+ *   2. The AUTHORING form — {@link PolicyInput}, the `policy: { by }` option a
+ *      schema author writes. The name follows Postgres/Supabase RLS vocabulary:
+ *      a `policy` is the rule that decides which rows a tenant may read.
+ *      {@link resolvePolicy} maps it to the canonical {@link Tenancy} at
+ *      `model()`-build time (much as Supabase's `create policy` compiles to a
+ *      `pg_policy` row), so the authoring vocabulary never reaches the wire or
+ *      any consumer.
+ *
+ * Why one authoring option (`policy`) instead of the old
+ * `orgScoped`/`scopedVia`/`orgColumn` trio: those three were synonyms for one
+ * decision ("how is this row scoped?"), and the most dangerous of them
+ * (`orgScoped: false`) silently exposed a whole table cross-tenant. Collapsing
+ * them into a single discriminated union makes the opt-out (`{ by: 'none' }`) a
+ * loud, deliberate branch instead of a falsy flag — one concept, one name.
  */
 import { z } from 'zod';
 /** Default physical tenancy column. The ONLY place this literal is canonical. */
 export const DEFAULT_ORG_COLUMN = 'organization_id';
 /**
  * Scope a table's rows through a parent table (for rows that carry no tenancy
- * column of their own — e.g. `slide_layers` → slide → deck → org).
+ * column of their own — e.g. `slide_layers` → slide → deck → org). This is the
+ * CANONICAL `parent` payload; authors write the friendlier {@link PolicyInput}
+ * `{ by: 'parent', fk, parent }` shape, normalized into this by
+ * {@link resolvePolicy}.
  */
 export const scopedViaRefSchema = z.object({
     /** Column on THIS table pointing at the parent (e.g. `'team_id'`). */
@@ -28,7 +42,7 @@ export const scopedViaRefSchema = z.object({
     /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
     parentOrgColumn: z.string().min(1).optional(),
 });
-/** How a model's rows are scoped to a tenant. */
+/** How a model's rows are scoped to a tenant — the CANONICAL, wire-facing form. */
 export const tenancySchema = z.discriminatedUnion('kind', [
     /** Row-local tenancy column (default name `organization_id`, overridable). */
     z.object({ kind: z.literal('column'), column: z.string().min(1) }),
@@ -38,19 +52,75 @@ export const tenancySchema = z.discriminatedUnion('kind', [
     z.object({ kind: z.literal('none') }),
 ]);
 /**
- * Normalize authoring sugar into the one canonical {@link Tenancy}. Called once,
- * at model-build, so `ModelDef`/`ModelJSON` and every consumer see only
- * `tenancy`. Precedence: explicit `tenancy` → `scopedVia` → `orgScoped:false` →
- * column (default or `orgColumn`).
+ * The AUTHORING form of tenancy — what a schema author writes as the model's
+ * `policy` option (Postgres/Supabase RLS vocabulary: a policy is the rule that
+ * scopes which rows a tenant may read). A Zod discriminated union on `by`, so
+ * the three branches are mutually exclusive and the dangerous opt-out
+ * (`{ by: 'none' }`) is an explicit, named choice rather than a falsy flag.
+ *
+ * - `{ by: 'column' }`            — row-local tenancy column (the default).
+ *   `column` overrides the name (default {@link DEFAULT_ORG_COLUMN}).
+ * - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when
+ *   this table has no tenancy column of its own. `parentKey` (default `'id'`)
+ *   and `parentTenantColumn` (default {@link DEFAULT_ORG_COLUMN}) are overrides.
+ * - `{ by: 'none' }`             — genuinely global / reference data. ⚠ Makes
+ *   the whole table readable cross-tenant — only correct for tenant-less tables.
+ */
+export const policyInputSchema = z.discriminatedUnion('by', [
+    z.object({
+        by: z.literal('column'),
+        /** Override the physical tenancy column name. Default {@link DEFAULT_ORG_COLUMN}. */
+        column: z.string().min(1).optional(),
+    }),
+    z.object({
+        by: z.literal('parent'),
+        /** Column on THIS table pointing at the parent (e.g. `'slideId'`). */
+        fk: z.string().min(1),
+        /** Parent table name (e.g. `'slides'`). */
+        parent: z.string().min(1),
+        /** Column on the parent that `fk` references. Default `'id'`. */
+        parentKey: z.string().min(1).optional(),
+        /** Column on the parent holding the tenant id. Default {@link DEFAULT_ORG_COLUMN}. */
+        parentTenantColumn: z.string().min(1).optional(),
+    }),
+    z.object({ by: z.literal('none') }),
+]);
+/**
+ * Normalize the authoring {@link PolicyInput} into the one canonical
+ * {@link Tenancy}. Called once, at `model()`-build, so `ModelDef`/`ModelJSON`
+ * and every consumer see only the canonical union. Omitting `policy` defaults
+ * to a row-local `organization_id` column.
+ */
+export function resolvePolicy(input) {
+    if (!input)
+        return { kind: 'column', column: DEFAULT_ORG_COLUMN };
+    switch (input.by) {
+        case 'column':
+            return { kind: 'column', column: input.column ?? DEFAULT_ORG_COLUMN };
+        case 'parent':
+            return {
+                kind: 'parent',
+                via: {
+                    localKey: input.fk,
+                    parentTable: input.parent,
+                    parentKey: input.parentKey,
+                    parentOrgColumn: input.parentTenantColumn,
+                },
+            };
+        case 'none':
+            return { kind: 'none' };
+    }
+}
+/**
+ * Read the canonical {@link Tenancy} off an already-built model def (or parsed
+ * `ModelJSON`), defaulting to a row-local `organization_id` column when absent.
+ *
+ * This is the READ-side helper — consumers (provision/RLS, membership resolver,
+ * DDL, CLI) call it to get a model's tenancy without re-deriving the default in
+ * each place. It is NOT the authoring normalizer; that's {@link resolveIsolation}.
  */
-export function resolveTenancy(input) {
-    if (input.tenancy)
-        return input.tenancy;
-    if (input.scopedVia)
-        return { kind: 'parent', via: input.scopedVia };
-    if (input.orgScoped === false)
-        return { kind: 'none' };
-    return { kind: 'column', column: input.orgColumn ?? DEFAULT_ORG_COLUMN };
+export function resolveTenancy(def) {
+    return def.tenancy ?? { kind: 'column', column: DEFAULT_ORG_COLUMN };
 }
 /** The physical tenancy column for a column-scoped model, else `null`. */
 export function tenancyColumn(t) {

package/dist/server/commit.d.ts

@@ -58,11 +58,16 @@ export interface CommitContext {
      */
     onBehalfOf?: ParticipantRef | null;
     /**
-     * FK to AgentCapabilityRoot.capabilityId. Non-null for agent / system commits
-     * authorized by a Biscuit; null for human-direct commits. Embedded in every
-     * delta so the audit chain "delta → capability → human" is one FK hop.
+     * Scoped credential id. Non-null for agent / system commits when the
+     * authorizing credential is known; null for human-direct commits.
      */
     capabilityId?: string | null;
+    /**
+     * Human user id at the root of the delegated authority chain. Stored directly
+     * on `sync_deltas` so audit triggers never need to join mutable credential
+     * tables while appending the hash chain.
+     */
+    delegationChainRootUserId?: string | null;
     /**
      * ApiKey row id when the caller authenticated with an API key. Used by the
      * idempotency cache and usage attribution. Null for session / capability

package/dist/sync/createClaimStream.js

@@ -192,7 +192,8 @@ export function createClaimStream(config, transport = null) {
                 entityId: claim.entityId,
                 path: claim.path,
                 range: claim.range,
-                action: claim.action,
+                // Wire field stays `action` (coordination schema); source is `reason`.
+                action: claim.reason,
                 field: claim.field,
                 meta: claim.meta,
                 estimatedMs: claim.estimatedMs,
@@ -244,7 +245,7 @@ export function createClaimStream(config, transport = null) {
             range: args.range,
             field: args.field,
             meta: args.meta,
-            action: args.action,
+            reason: args.reason,
             estimatedMs,
             queue: args.queue,
         };
@@ -261,7 +262,7 @@ export function createClaimStream(config, transport = null) {
         return {
             object: 'claim',
             claimId,
-            action: args.action,
+            reason: args.reason,
             target: {
                 model: args.entityType,
                 id: args.entityId,
@@ -294,7 +295,7 @@ export function createClaimStream(config, transport = null) {
                 range: resolved.range,
                 field: resolved.field,
                 meta: withDescription(resolved.meta, opts?.description),
-                action: opts?.reason ?? 'editing',
+                reason: opts?.reason ?? 'editing',
                 ttl: opts?.ttl,
                 queue: opts?.queue,
             });

package/dist/sync/participants.js

@@ -221,7 +221,7 @@ function createJoinedParticipant(args) {
         return {
             object: 'claim',
             claimId: handle.claimId,
-            action: handle.action,
+            reason: handle.reason,
             target: handle.target,
             async release() {
                 ownHandles.delete(handle);

package/dist/types/streams.d.ts

@@ -360,7 +360,7 @@ export interface ClaimStream {
     /**
      * Reactive view of the wait queue on one target — the FIFO line of
      * `status: 'queued'` claims behind the current holder, each with its
-     * `action`, `heldBy`, and `position`. Synced from the server's per-entity
+     * `reason`, `heldBy`, and `position`. Synced from the server's per-entity
      * `claim_queue` frame; empty when no one's waiting. Pair with
      * `subscribe(...)` for change notifications.
      */
@@ -457,10 +457,12 @@ export interface ClaimDeclaration {
     /** Human-readable reason — "rewriting title" / "restyling chart". */
     readonly reason: string;
     /**
-     * Expiry — auto-revoke if the participant doesn't finish in time.
-     * Number = seconds (back-compat); string = duration (`'3m'`).
+     * Seconds remaining until the server auto-expires this claim. An OUTPUT
+     * field carrying a concrete countdown, so it's a plain `number` — distinct
+     * from the input `ttl: Duration` (`'3m'`) you pass when announcing. Computed
+     * from `expiresAt - now`.
      */
-    readonly ttlSeconds?: Duration;
+    readonly ttlSeconds?: number;
 }
 /**
  * Handle returned from `announce(...)` / `analyzing(...)` / etc.
@@ -507,7 +509,13 @@ export interface ClaimHandle<T = Record<string, unknown>> extends AsyncDisposabl
         readonly range?: TargetRange;
         readonly meta?: Record<string, unknown>;
     };
-    readonly action: string;
+    /**
+     * The human-readable phase this claim represents — `'editing'`, `'writing'`,
+     * `'forecasting'`. The SAME word on every claim surface (inputs and outputs);
+     * distinct from the CRUD operation (`CommitOperationInput.action`). Defaults
+     * to `'editing'`. Serialized on the wire as `action`.
+     */
+    readonly reason: string;
     readonly description?: string;
     /** Row snapshot — populated by `ablo.<model>.claim`; absent on low-level leases. */
     readonly data?: T;
@@ -565,8 +573,10 @@ export interface Claim {
     readonly status: ClaimStatus;
     /** What is being coordinated. */
     readonly target: EntityRef;
-    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. */
-    readonly action: string;
+    /** Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. The same
+     *  field on every claim surface; distinct from the CRUD operation. Serialized
+     *  on the wire as `action`. */
+    readonly reason: string;
     /** Peer-visible explanation of the work being performed. */
     readonly description?: string;
     /** Participant holding it. */

package/docs/api.md

@@ -180,7 +180,7 @@ if (claim) {
 
 const handle = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'editing',
+  reason: 'editing',
   ttl: '2m',
 });
 await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });

package/docs/cli.md

@@ -24,18 +24,23 @@ direct-connector commands are tagged **Direct Postgres**.
 
 `ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
 **log in** or **create an account** and approve, and the CLI provisions a
-**test + live key pair** (90-day, restricted) and stores them locally. This
-mirrors `stripe login`.
+**test + live key pair** (90-day) and stores them locally. The test key is a
+sandbox `sk_test_` key; the live key is a restricted `rk_live_` key (read-only
+observation — `logs`, `status`), so a stolen config can't write to production.
+This mirrors `stripe login`.
 
 | Command                  | What it does                                                               |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
+| `ablo login --project <slug>` | Same, but scope (and mint) the pair to a project, and make it active. |
 | `ablo logout`            | Remove the stored keys.                                                    |
 | `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
 | `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
-Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
-log in — set `ABLO_API_KEY`, which always overrides the stored key.
+Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project
+then environment; the non-secret `config.json` holds only the active mode and
+project. In **CI**, don't log in — set `ABLO_API_KEY`, which always overrides
+the stored key.
 
 ## Test vs live
 
@@ -47,6 +52,39 @@ the sandbox by design.
 The schema, however, is **shared** across the org — pushing a schema (from
 either environment) defines the same models sandbox and production see; only the rows differ.
 
+## Projects
+
+An org can have multiple **projects**, each with its own isolated keys, schema,
+and data. Keys are scoped to a project **at mint** and never re-scoped, so the
+CLI keeps a separate credential profile per project — Stripe's
+`login --project-name` model. The active project (set with `projects use`)
+selects which profile every command authenticates with.
+
+| Command                       | What it does                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `ablo projects list`          | List the org's projects (marks the active one and the org-default).                |
+| `ablo projects create <slug>` | Create a project (`--name "Display Name"`). Its keys/schema/data are isolated.     |
+| `ablo projects use <slug>`    | Switch the active project. `ablo projects use default` returns to the org-default. |
+| `ablo login --project <slug>` | Mint and store a key pair for a project, and make it active.                       |
+
+Because keys are fixed to a project, `projects use` only changes which profile
+is active — it never re-scopes an existing key. Switch to a project you haven't
+logged into yet and the CLI tells you to mint one:
+
+```bash
+npx ablo projects use war-room
+#   ✓ now targeting project war-room (prj_…)
+#   No key stored for this project yet — run `ablo login --project war-room` to mint one.
+
+npx ablo login --project war-room   # mints + stores its key pair, keeps it active
+```
+
+If you run a project-scoped command (`push`, `dev`) while the active project has
+no key — but other projects do — the CLI **refuses** rather than silently
+deploying with the wrong project's credential, and names the fix
+(`ablo login --project <slug>`). In CI, an explicit `ABLO_API_KEY` bypasses
+profiles entirely: it acts in whatever project it was minted for.
+
 ## Commands
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
@@ -54,6 +92,7 @@ either environment) defines the same models sandbox and production see; only the
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
 | `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
 | `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |

package/docs/client-behavior.md

@@ -146,7 +146,7 @@ the latest row, then hands you the fresh row — so you can't overwrite a change
 see. Options on the claim:
 
 - default `claim` waits in the fair queue and re-reads before handing you the row;
-- `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
+- `{ queue: false }` rejects with `AbloClaimedError` instead of queuing;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
@@ -166,7 +166,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloValidationError` | Invalid input or unsupported request shape. |
 | `AbloServerError` | Server-side 5xx. Retry with backoff if the operation is idempotent. |
 | `AbloStaleContextError` | Write was based on stale `readAt` state. Re-read and retry. |
-| `AbloClaimedError` | An active claim conflicted with `{ wait: false }`, the queue was too deep, or a claim wait timed out. |
+| `AbloClaimedError` | An active claim conflicted with `{ queue: false }`, the queue was too deep, or a claim wait timed out. |
 
 ```ts
 import { AbloClaimedError } from '@abloatai/ablo';

package/docs/coordination.md

@@ -280,7 +280,7 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', action: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', reason: 'reviewing' });
 const report = claim.data;
 try {
   const ok = await reviewExternally(report);

package/docs/examples/agent-human.md

@@ -47,14 +47,14 @@ export async function markReady(reportId: string) {
   if (!report) return { status: 'not_found' };
 
   try {
-    // wait: false → don't queue behind a current holder. If a human already
+    // queue: false → don't queue behind a current holder. If a human already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
-    // agent yields instead of waiting. Omit it, or pass wait: true, to queue
-    // behind them. action → the label observers see while we work.
+    // agent yields instead of waiting. Omit it, or pass queue: true, to queue
+    // behind them. reason → the label observers see while we work.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      wait: false,
-      action: 'marking_ready',
+      queue: false,
+      reason: 'marking_ready',
     });
     const claimed = claim.data;
 
@@ -120,7 +120,7 @@ export function ReportRow({ report: serverReport }: Props) {
 - The claim is visible to everyone: the UI reads it synchronously with
   `claim.state({ id })`, and it also arrives over the live stream.
 - `claim({ id })` makes writers take turns instead of racing — with
-  `wait: false`, the agent simply yields when a human already holds the row.
+  `queue: false`, the agent simply yields when a human already holds the row.
 - The `update` made while the claim is held is stale-checked automatically, so a human's
   edit landing mid-run rejects the agent's write with a typed
   `AbloStaleContextError` instead of overwriting it.

package/docs/examples/ai-sdk-tool.md

@@ -43,7 +43,7 @@ const updateReport = tool({
     // The claim is released automatically when it goes out of scope.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      action: 'editing',
+      reason: 'editing',
       ttl: '2m',
     });
     const claimed = claim.data;

package/docs/examples/existing-python-backend.md

@@ -37,10 +37,8 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   weatherReports: model({
-    id: z.string(),
     location: z.string(),
     status: z.enum(['pending', 'ready']),
-    updatedAt: z.string(),
   }),
 });
 ```

package/docs/examples/nextjs.md

@@ -57,8 +57,8 @@ import { ablo } from '@/lib/ablo';
 export async function markReady(id: string) {
   await using claim = await ablo.weatherReports.claim({
     id,
-    wait: false,
-    action: 'marking_ready',
+    queue: false,
+    reason: 'marking_ready',
   });
   const claimed = claim.data;
 

package/docs/examples/scoped-agent.md

@@ -19,18 +19,18 @@ import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A deck's rows form the group `deck:<id>` (the kind comes from `scope`).
+    // A deck's rows form the group `deck:<id>` (the kind comes from `groups.root`).
     decks: model(
       { title: z.string() },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A slide has no group of its own. It inherits its deck's group via the
     // `parent` edge, so a slide write reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string(), body: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {

package/docs/examples/server-agent.md

@@ -38,8 +38,8 @@ export async function completeReport(reportId: string) {
 
   await using claim = await ablo.weatherReports.claim({
     id: reportId,
-    wait: false,
-    action: 'completing',
+    queue: false,
+    reason: 'completing',
   });
   const claimed = claim.data;
 
@@ -60,9 +60,9 @@ the server has accepted it.
 
 The two options on the claim:
 
-- `wait: false` — skip this record if another claim is already in progress,
+- `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. (The default queues.)
-- `action: 'completing'` — a human-readable label for what your worker is doing,
+- `reason: 'completing'` — a human-readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
 Because the worker uses the same schema and `claim()` as the UI, its writes sync

package/docs/identity.md

@@ -47,18 +47,20 @@ import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A scope root: its rows form the group `deck:<id>` (kind from `scope`).
+    // A scope root: its rows form the group `deck:<id>` (kind from `groups.root`).
+    // Tenant isolation defaults to a row-local `organization_id` column, so no
+    // `policy` is needed here.
     decks: model(
       { title: z.string(), status: z.enum(['draft', 'published']) },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A child: it has no group of its own; it inherits its deck's group via the
     // `parent` edge. A write to a slide reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {
@@ -208,13 +210,13 @@ You never write a sync-group string for a row. You declare a model's *place* in
 the entity graph and the engine derives the groups its rows fan out on. Three
 declarations, in order of how often you reach for them:
 
-**`scope` — 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 `deck:<id>`):
+**`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 `deck:<id>`):
 
 ```ts
-decks: model({ title: z.string() }, {}, { orgScoped: true, scope: 'deck' });
+decks: model({ title: z.string() }, {}, { groups: { root: 'deck' } });
 // a deck row → group `deck:<id>`
 ```
 
@@ -232,7 +234,7 @@ slides: model(
     deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
     sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
   },
-  { orgScoped: true },
+  {},  // default policy: row-local organization_id
 );
 ```
 
@@ -241,8 +243,8 @@ slides: model(
 > some required FKs are mere references. Containment is a fact only you know, so
 > it's declared, exactly as it is in OpenFGA/Zanzibar.
 
-**`grants` — a membership edge.** On a join model (e.g. `dataroomMember`), it
-says "this row grants a *subject* access to a *scope root*." Both are relation
+**`groups.grants` — a membership edge.** On a join model (e.g. `dataroomMember`),
+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
 set (Linear's `/sync/user_sync_groups`). Use this for sub-org sharing; plain
@@ -255,15 +257,19 @@ dataroomMember: model(
     member: relation.belongsTo('users', 'userId'),
     room: relation.belongsTo('datarooms', 'dataroomId'),
   },
-  { orgScoped: true, grants: { subject: 'member', scope: 'room' } },
+  { groups: { grants: { subject: 'member', scope: 'room' } } },
 );
 ```
 
 For the rare group keyed on a plain field rather than a relation (per-recipient
-inbox fan-out, say), there's an `entityRoles: [entityRole({ kind, source })]`
+inbox fan-out, say), there's a `groups: { roles: [entityRole({ kind, source })] }`
 escape hatch. For rows that inherit *tenancy* (not a sync group) through a
-foreign key without carrying `organization_id`, use `scopedVia` rather than
-`orgScoped: false` — the latter exposes the whole table cross-tenant. See
+foreign key without carrying `organization_id`, use `policy: { by: 'parent', fk,
+parent }` rather than opting out of isolation. The old `orgScoped: false`
+exposed the whole table cross-tenant, so `validate_schema` rejects the removed
+options as `tenancy-option-removed` errors and steers you to `policy: { by:
+'parent' }` (FK inheritance) or, for genuinely global reference data, the
+explicit `policy: { by: 'none' }`. See
 `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## How identity reaches Ablo — the proxy model
@@ -393,8 +399,8 @@ 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({ /* … */ }, {}, { orgScoped: true, scope: 'document' }),
-decks:     model({ /* … */ }, {}, { orgScoped: true, scope: 'deck' }),
+documents: model({ /* … */ }, {}, { groups: { root: 'document' } }),
+decks:     model({ /* … */ }, {}, { groups: { root: 'deck' } }),
 ```
 
 Then a run subscribes only to the entity groups for the rows it works on — a
@@ -484,9 +490,10 @@ an agent pointed at the entities it's working on. You **never hand-write**
    (it returns a participant handle with `.peers`). See
    [Coordination](./coordination.md).
 
-> **`scope` is the schema model option, not a client setting.** `scope: 'deck'`
-> in `model(...)` declares a scope root ([Half 2](#half-2--per-model-scope-row--group)) —
-> it names the group (`deck:<id>`) that the mechanisms above then subscribe to.
+> **`groups.root` is the schema model option, not a client setting.**
+> `groups: { root: 'deck' }` in `model(...)` declares a scope root
+> ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
+> (`deck:<id>`) that the mechanisms above then subscribe to.
 > There is no `Ablo({ scope })` constructor option. The lifecycle filter on
 > [`list()`](./api.md#model-methods) is a separate axis named **`state`**
 > (`'live' | 'archived' | 'all'`, GitHub's open/closed/all), precisely so it

package/docs/index.md

@@ -99,4 +99,3 @@ Three things stay true no matter how you use Ablo:
 - [README](../README.md) — product overview and first example.
 - [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
 - [Changelog](../CHANGELOG.md) — what shipped recently.
-- [Roadmap](./roadmap.md) — what's planned next.