@abloatai/ablo 0.11.2 → 0.13.0

package/AGENTS.md

@@ -31,7 +31,7 @@ Every model verb takes ONE options object. The common loop:
 
 1. **Read** the row — `await ablo.<model>.retrieve({ id })` (async; from the server) or `await ablo.<model>.list({ where })` for many. In React render, read synchronously with `useAblo((a) => a.<model>.get(id))`.
 2. **See who's active** (optional) — `ablo.<model>.claim.state({ id })` (synchronous; never blocks).
-3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, action?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
+3. **Claim** the row before changing it — `await using claim = await ablo.<model>.claim({ id, reason?, ttl? })`. If someone else holds it, this waits for them, then gives you the fresh row on `claim.data`. The claim auto-releases when it goes out of scope (`await using`).
 4. **Write** — `await ablo.<model>.update({ id: claim.data.id, data })`. Because you hold the claim, the write is rejected if the row changed underneath you.
 
 Keep coding assistants on this schema-backed path.
@@ -59,7 +59,7 @@ if (!report) throw new Error('Report not found');
 // row before resolving. Auto-released at the end of this scope (`await using`).
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'forecasting',
+  reason: 'forecasting',
   ttl: '2m',
 });
 const claimed = claim.data;

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.13.0
+
+### Minor Changes
+
+- Schema authoring: split model routing into two orthogonal axes — `policy` (row access) and `groups` (sync-group routing).
+
+  **Breaking (schema authoring).** The flat, collision-prone model options are replaced by two namespaced ones:
+  - **`policy`** — row-access / tenant isolation (named after Postgres/Supabase RLS policies: the rule that scopes which rows a tenant may read). A discriminated union on `by` replaces the old `orgScoped` / `scopedVia` / `orgColumn` trio:
+    - `{ by: 'column' }` — row-local tenancy column (the default when omitted; column name still overridable).
+    - `{ by: 'parent', fk, parent }` — inherit tenancy through a foreign key when the table has no tenancy column of its own (e.g. `slide_layers` → `slides`).
+    - Type `TenancyInput` is renamed `PolicyInput`; `policyInputSchema` / `resolvePolicy` are now exported.
+  - **`groups: { root, grants, roles }`** — which delta channels a row fans into (orthogonal to `policy`, which governs read access). One namespaced object replaces the old flat `scope` / `grants` / `entityRoles`:
+    - `root` (was `scope`) — mark a model a scope root; its records form the group `<kind>:<id>`. Renamed so it no longer collides with the old `scopedVia` tenancy sugar or the inner `grants.scope` relation name.
+    - `grants` — a membership edge granting an identity access to a scope root.
+    - `roles` (was `entityRoles`) — explicit non-relational record→group roles; accepts one role or an array.
+    - `groupsInputSchema` / `GroupsInput` are now exported.
+
+  **CLI.** `config.json` now stores per-project profile key pairs (`profiles: Record<string, ProfileKeys>`) instead of a single top-level pair; older flat layouts are folded into the active profile automatically on read, so existing logins keep working. `login` / `projects` updated to the profile model.
+
+## 0.12.0
+
+### Minor Changes
+
+- Canonicalize the claim API to one vocabulary, plus DX fixes (breaking).
+  - BREAKING: claim phase field `action` → `reason` on every claim surface
+    (`Claim`, `ClaimHandle`, `ClaimCreateOptions`, `ModelClaim`, ...). The wire
+    is unchanged (still `action`, healed on read) — no server redeploy needed.
+  - BREAKING: claim contention flag `wait` → `queue` (one word everywhere).
+  - BREAKING: React hook `useParticipant` → `useWatch` (aligns with `ablo.<model>.watch`).
+  - `ClaimDeclaration.ttlSeconds` is now `number` (was a `Duration`).
+  - Docs: `retrieve` HTTP envelope (`.data`/`.stamp`) called out; `syncGroups`
+    reworded (provisional, not deprecated); `orgScoped` cross-tenant security
+    warning; React error strings point at `<AbloProvider>`.
+
 ## 0.11.2
 
 ### Patch Changes

package/README.md

@@ -274,7 +274,7 @@ ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 
 {
-  await using claim = await ablo.weatherReports.claim({ id, wait: false });
+  await using claim = await ablo.weatherReports.claim({ id, queue: false });
   /* do the held work */
 }
 
@@ -285,11 +285,11 @@ ablo.weatherReports.claim.queue({ id: 'report_stockholm' });
 ```
 
 `claim.state` returns the holder (or `null`); `claim.queue` returns the line waiting
-behind it. `wait: false` skips rather than waiting when the row is held;
+behind it. `queue: false` skips rather than waiting when the row is held;
 `maxQueueDepth: 2` bails when two or more are already ahead.
 
 Default reads keep working while a row is claimed. Server reads that need claimed
-semantics can opt in with `ifClaimed: 'return' | 'wait' | 'fail'`.
+semantics can opt in with `ifClaimed: 'return' | 'fail'`.
 
 Even an unclaimed write can't land on stale reasoning — the commit is guarded:
 

package/dist/ai-sdk/claim-broadcast.d.ts

@@ -58,10 +58,11 @@ export interface ClaimBroadcastMiddlewareOptions<R extends SchemaRecord = Schema
     /** Target entity. Null skips the broadcast (purely conversational). */
     readonly target: ClaimTarget | null;
     /**
-     * Action verb describing what the agent is doing. Convention:
-     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`.
+     * Human-readable phase describing what the agent is doing. Convention:
+     * `'edit'`, `'read'`, `'review'`, `'generate'`. Default `'edit'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Surfaces to other agents through `ActiveClaim.description`.

package/dist/ai-sdk/claim-broadcast.js

@@ -29,7 +29,7 @@
  */
 export function claimBroadcastMiddleware(options) {
     const { agent, target } = options;
-    const action = options.action ?? 'edit';
+    const reason = options.reason ?? 'edit';
     const description = options.description;
     const openClaim = () => {
         if (!agent || !target)
@@ -42,7 +42,7 @@ export function claimBroadcastMiddleware(options) {
             field: target.field,
             meta: target.meta,
         }, {
-            reason: action,
+            reason,
             description,
             ttl: target.estimatedMs ?? 60_000,
         });

package/dist/ai-sdk/wrap.d.ts

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -40,10 +40,11 @@ export interface WrapWithMultiplayerOptions {
     /** Target entity. Null = pass-through wrap. */
     readonly target: ClaimTarget | null;
     /**
-     * Optional action verb for the broadcast. Default `'edit'`.
-     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`.
+     * Optional human-readable phase for the broadcast. Default `'edit'`.
+     * Convention: `'edit'`, `'read'`, `'review'`, `'generate'`. The same
+     * `reason` field used on every claim surface.
      */
-    readonly action?: string;
+    readonly reason?: string;
     /**
      * Peer-visible explanation of the specific work this model call is about to
      * perform. Other agents receive it in their coordination context.

package/dist/ai-sdk/wrap.js

@@ -14,7 +14,7 @@
  *   model: anthropic('claude-opus-4-7'),
  *   agent,
  *   target: { entityType: 'SlideDeck', entityId: 'deck-abc' },
- *   action: 'renaming',
+ *   reason: 'renaming',
  *   description: 'Renaming the deck title to match the project brief.',
  * });
  *
@@ -31,12 +31,12 @@ import { wrapLanguageModel } from 'ai';
 import { claimBroadcastMiddleware, } from './claim-broadcast.js';
 import { coordinationContextMiddleware } from './coordination-context.js';
 export function wrapWithMultiplayer(options) {
-    const { model, agent, target, action, description, excludeClaimIds, extraMiddleware } = options;
+    const { model, agent, target, reason, description, excludeClaimIds, extraMiddleware } = options;
     return wrapLanguageModel({
         model,
         middleware: [
             coordinationContextMiddleware({ agent, target, excludeClaimIds }),
-            claimBroadcastMiddleware({ agent, target, action, description }),
+            claimBroadcastMiddleware({ agent, target, reason, description }),
             ...(extraMiddleware ?? []),
         ],
     });

package/dist/cli.cjs

@@ -277023,6 +277023,7 @@ var roleSchema = import_zod2.z.object({
   kind: import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'kind must be a lowercase identifier, e.g. "deck"'),
   source: roleSourceSchema
 });
+var entityRoleSchema = roleSchema;
 var scopeSchema = import_zod2.z.union([
   import_zod2.z.boolean(),
   import_zod2.z.string().regex(/^[a-z][a-z0-9_]*$/, 'scope kind must be a lowercase identifier, e.g. "dataroom"')
@@ -277031,6 +277032,11 @@ var grantsRefSchema = import_zod2.z.object({
   subject: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.subject must name a relation"),
   scope: import_zod2.z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "grants.scope must name a relation")
 });
+var groupsInputSchema = import_zod2.z.object({
+  root: scopeSchema.optional(),
+  grants: grantsRefSchema.optional(),
+  roles: import_zod2.z.union([entityRoleSchema, import_zod2.z.array(entityRoleSchema)]).optional()
+});
 
 // src/coordination/schema.ts
 var targetRangeSchema = import_zod3.z.object({
@@ -277121,7 +277127,9 @@ var modelClaimSchema = import_zod3.z.object({
   id: import_zod3.z.string(),
   actor: import_zod3.z.string(),
   participantKind: wireParticipantKindSchema,
-  action: import_zod3.z.string(),
+  /** Human-readable phase (`'editing'`). The public SDK field; the WS/HTTP
+   *  wire carries the same value as `action` (healed on read). */
+  reason: import_zod3.z.string(),
   description: import_zod3.z.string().optional(),
   field: import_zod3.z.string().optional(),
   status: import_zod3.z.enum(["active", "queued"]).optional(),
@@ -279644,6 +279652,7 @@ init_cjs_shims();
 var import_os2 = require("os");
 var import_path2 = require("path");
 var import_fs3 = require("fs");
+var DEFAULT_PROFILE = "default";
 function configDir() {
   if (process.env.ABLO_CONFIG_DIR) return process.env.ABLO_CONFIG_DIR;
   const xdg = process.env.XDG_CONFIG_HOME;
@@ -279655,12 +279664,32 @@ function configPath() {
 function credentialsPath() {
   return (0, import_path2.join)(configDir(), "credentials.json");
 }
+function activeProfileName(cfg) {
+  return cfg.activeProject?.slug ?? DEFAULT_PROFILE;
+}
 function asKeyEntry(value) {
   if (value && typeof value === "object" && typeof value.apiKey === "string") {
     return value;
   }
   return void 0;
 }
+function asProfileKeys(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const v = value;
+  const sandbox = asKeyEntry(v.sandbox);
+  const production = asKeyEntry(v.production);
+  if (!sandbox && !production) return void 0;
+  return { ...sandbox ? { sandbox } : {}, ...production ? { production } : {} };
+}
+function asProfileMap(value) {
+  if (!value || typeof value !== "object") return {};
+  const out = {};
+  for (const [name, v] of Object.entries(value)) {
+    const keys = asProfileKeys(v);
+    if (keys) out[name] = keys;
+  }
+  return out;
+}
 function readJson(path) {
   if (!(0, import_fs3.existsSync)(path)) return null;
   try {
@@ -279681,7 +279710,7 @@ function normalizeStoredMode(value) {
   if (value === "sandbox" || value === "production") return value;
   return void 0;
 }
-function extractEntries(obj) {
+function extractLegacyEntries(obj) {
   const sandbox = asKeyEntry(obj.sandbox);
   const production = asKeyEntry(obj.production);
   if (sandbox || production) {
@@ -279690,24 +279719,33 @@ function extractEntries(obj) {
   const flat = asKeyEntry(obj);
   return flat ? { sandbox: flat } : {};
 }
+function hasKey(keys) {
+  return !!(keys?.sandbox || keys?.production);
+}
 function readConfig() {
   const cfgObj = readJson(configPath());
   const credObj = readJson(credentialsPath());
   const mode2 = normalizeStoredMode(cfgObj?.mode) ?? normalizeStoredMode(credObj?.mode);
   const activeProject = asActiveProject(cfgObj?.activeProject);
-  const cfgEntries = cfgObj ? extractEntries(cfgObj) : {};
-  const entries = {
-    ...cfgEntries,
-    ...credObj ? extractEntries(credObj) : {}
-    // credentials file wins
+  const activeName = activeProject?.slug ?? DEFAULT_PROFILE;
+  const profiles = {
+    ...asProfileMap(credObj?.profiles),
+    ...asProfileMap(cfgObj?.profiles)
   };
-  if (!mode2 && !entries.sandbox && !entries.production) return null;
+  const legacyCfg = cfgObj ? extractLegacyEntries(cfgObj) : {};
+  const legacyCred = credObj ? extractLegacyEntries(credObj) : {};
+  const legacy = { ...legacyCfg, ...legacyCred };
+  const migratedLegacy = hasKey(legacy) && !hasKey(profiles[activeName]);
+  if (migratedLegacy) profiles[activeName] = legacy;
+  const anyKey = Object.values(profiles).some(hasKey);
+  if (!mode2 && !anyKey) return null;
   const config = {
     mode: mode2 ?? "sandbox",
     ...activeProject ? { activeProject } : {},
-    ...entries
+    profiles
   };
-  if (cfgEntries.sandbox || cfgEntries.production) writeConfig(config);
+  const secretsInConfig = hasKey(legacyCfg);
+  if (secretsInConfig || migratedLegacy) writeConfig(config);
   return config;
 }
 function writeConfig(cfg) {
@@ -279723,16 +279761,34 @@ function writeConfig(cfg) {
 `,
     { mode: 384 }
   );
-  const credentials = {
-    ...cfg.sandbox ? { sandbox: cfg.sandbox } : {},
-    ...cfg.production ? { production: cfg.production } : {}
-  };
-  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify(credentials, null, 2)}
+  const profiles = {};
+  for (const [name, keys] of Object.entries(cfg.profiles)) {
+    if (!hasKey(keys)) continue;
+    profiles[name] = {
+      ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+      ...keys.production ? { production: keys.production } : {}
+    };
+  }
+  (0, import_fs3.writeFileSync)(credentialsPath(), `${JSON.stringify({ profiles }, null, 2)}
 `, { mode: 384 });
   return credentialsPath();
 }
+function emptyConfig(mode2 = "sandbox") {
+  return { mode: mode2, profiles: {} };
+}
+function setProfileKeys(profileName, keys, opts) {
+  const cfg = readConfig() ?? emptyConfig(opts.mode);
+  cfg.mode = opts.mode;
+  cfg.profiles[profileName] = {
+    ...keys.sandbox ? { sandbox: keys.sandbox } : {},
+    ...keys.production ? { production: keys.production } : {}
+  };
+  if (opts.activeProject) cfg.activeProject = opts.activeProject;
+  else delete cfg.activeProject;
+  return writeConfig(cfg);
+}
 function setMode(mode2) {
-  const cfg = readConfig() ?? { mode: mode2 };
+  const cfg = readConfig() ?? emptyConfig(mode2);
   cfg.mode = mode2;
   return writeConfig(cfg);
 }
@@ -279743,13 +279799,15 @@ function getActiveProject() {
   return readConfig()?.activeProject;
 }
 function setActiveProject(project) {
-  const cfg = readConfig() ?? { mode: "sandbox" };
+  const cfg = readConfig() ?? emptyConfig("sandbox");
   if (project) cfg.activeProject = project;
   else delete cfg.activeProject;
   return writeConfig(cfg);
 }
 function getKeyEntry(mode2) {
-  return readConfig()?.[mode2];
+  const cfg = readConfig();
+  if (!cfg) return void 0;
+  return cfg.profiles[activeProfileName(cfg)]?.[mode2];
 }
 function modeFromKey(key) {
   if (/^(sk|rk)_test_/.test(key)) return "sandbox";
@@ -279773,11 +279831,21 @@ function resolveApiKey(modeOverride) {
   if (process.env.ABLO_API_KEY) return process.env.ABLO_API_KEY;
   const cfg = readConfig();
   if (!cfg) return void 0;
-  const entry = cfg[modeOverride ?? cfg.mode];
+  const entry = cfg.profiles[activeProfileName(cfg)]?.[modeOverride ?? cfg.mode];
   if (!entry) return void 0;
   if (entry.expiresAt && Date.parse(entry.expiresAt) <= Date.now()) return void 0;
   return entry.apiKey;
 }
+function guardActiveProjectKey() {
+  if (process.env.ABLO_API_KEY) {
+    return { ok: true, activeProfile: DEFAULT_PROFILE, available: [] };
+  }
+  const cfg = readConfig();
+  const activeProfile = cfg ? activeProfileName(cfg) : DEFAULT_PROFILE;
+  const profiles = cfg?.profiles ?? {};
+  const available = Object.entries(profiles).filter(([, keys]) => hasKey(keys)).map(([name]) => name);
+  return { ok: hasKey(profiles[activeProfile]), activeProfile, available };
+}
 function resolvePushPlan() {
   const envKey = process.env.ABLO_API_KEY;
   if (envKey) return { flow: modeFromKey(envKey) ?? getMode(), apiKey: envKey, source: "env" };
@@ -280423,8 +280491,19 @@ function openBrowser(url) {
   } catch {
   }
 }
-async function deviceLogin() {
+function parseProjectFlag(argv) {
+  const i = argv.indexOf("--project");
+  if (i >= 0) {
+    const slug = argv[i + 1];
+    if (slug && !slug.startsWith("-")) return slug;
+  }
+  const eq = argv.find((a) => a.startsWith("--project="));
+  return eq ? eq.slice("--project=".length) || void 0 : void 0;
+}
+async function deviceLogin(argv) {
   Ie(`${brand("ablo")} login`);
+  const requested = parseProjectFlag(argv) ?? getActiveProject()?.slug;
+  const targetProject = requested === DEFAULT_PROFILE ? void 0 : requested;
   const interactive = Boolean(process.stdout.isTTY && process.stdin.isTTY);
   let account = "login";
   if (interactive) {
@@ -280502,13 +280581,19 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     s.stop("Timed out waiting for approval.");
     process.exit(1);
   }
-  s.message("Provisioning a sandbox key\u2026");
+  s.message(
+    targetProject ? `Provisioning keys for ${targetProject}\u2026` : "Provisioning a sandbox key\u2026"
+  );
   const provRes = await fetch(`${AUTH_URL}/api/cli/provision-key`, {
     method: "POST",
     headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
-    // Pass the device_code so the server can scope the minted keys to the
-    // project the user picked at /cli (login project picker). Harmless if none.
-    body: JSON.stringify({ device_code: code.device_code })
+    // Scope the minted keys to the chosen project (`--project`/active), with
+    // the device_code as a legacy fallback for the /cli picker. Both harmless
+    // if absent → org-default keys.
+    body: JSON.stringify({
+      device_code: code.device_code,
+      ...targetProject ? { project_slug: targetProject } : {}
+    })
   }).catch(() => null);
   if (!provRes || !provRes.ok) {
     s.stop("Could not provision a key.");
@@ -280526,16 +280611,23 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     ...prov.organizationId ? { organizationId: prov.organizationId } : {},
     ...k3.expiresAt ? { expiresAt: k3.expiresAt } : {}
   });
-  const path = writeConfig({
-    mode: "sandbox",
-    sandbox: entry(prov.test),
-    ...prov.live ? { production: entry(prov.live) } : {}
-  });
+  const profileName = prov.project?.slug ?? DEFAULT_PROFILE;
+  const path = setProfileKeys(
+    profileName,
+    {
+      sandbox: entry(prov.test),
+      ...prov.live ? { production: entry(prov.live) } : {}
+    },
+    { mode: "sandbox", activeProject: prov.project ?? void 0 }
+  );
   s.stop(`Saved keys to ${path}`);
-  Se(`${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`);
+  const where = prov.project ? ` ${import_picocolors7.default.dim(`(project ${prov.project.slug})`)}` : "";
+  Se(
+    `${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}${where}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`
+  );
 }
-async function login() {
-  await deviceLogin();
+async function login(argv = []) {
+  await deviceLogin(argv);
 }
 function logout() {
   const removed = clearCredential();
@@ -280788,11 +280880,13 @@ async function projects(argv) {
       setActiveProject({ id: target.id, slug: target.slug });
       console.log(`  ${import_picocolors9.default.green("\u2713")} now targeting project ${import_picocolors9.default.bold(target.slug)} ${import_picocolors9.default.dim(`(${target.id})`)}`);
     }
-    console.log(
-      import_picocolors9.default.dim(
-        "  Note: a key\u2019s project scope is fixed at mint \u2014 switch keys (or mint one for this project) to act in it."
-      )
-    );
+    const guard = guardActiveProjectKey();
+    if (!guard.ok) {
+      const loginCmd = guard.activeProfile === DEFAULT_PROFILE ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.log(
+        import_picocolors9.default.dim(`  No key stored for this project yet \u2014 run ${import_picocolors9.default.bold(loginCmd)} to mint one.`)
+      );
+    }
     return;
   }
   console.error(
@@ -281368,7 +281462,7 @@ function spreadOpts(optsArg) {
   }
   return `, ...${optsArg.getText()}`;
 }
-function hasKey(obj, key) {
+function hasKey2(obj, key) {
   return obj.getProperties().some(
     (p2) => (import_ts_morph.Node.isPropertyAssignment(p2) || import_ts_morph.Node.isShorthandPropertyAssignment(p2)) && p2.getName() === key
   );
@@ -281381,7 +281475,7 @@ function verbRewrite(call, verb) {
   const first = args[0];
   const calleeText = call.getExpression().getText();
   if (verb === "create") {
-    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey(first, "data")) return null;
+    if (import_ts_morph.Node.isObjectLiteralExpression(first) && hasKey2(first, "data")) return null;
     return `${calleeText}({ data: ${first.getText()}${spreadOpts(args[1])} })`;
   }
   if (import_ts_morph.Node.isObjectLiteralExpression(first)) return null;
@@ -282210,7 +282304,7 @@ async function main() {
   if (command === "init") {
     await init(process.argv.slice(3));
   } else if (command === "login") {
-    await login();
+    await login(process.argv.slice(3));
   } else if (command === "logout") {
     logout();
   } else if (command === "mode") {
@@ -282249,6 +282343,22 @@ async function main() {
     const rest = process.argv.slice(3);
     const advanced = rest.some((a) => ["--force", "--rename", "--backfill", "--url"].includes(a));
     const watching = rest.includes("--watch");
+    const guard = guardActiveProjectKey();
+    if (!guard.ok && guard.available.length > 0 && !rest.includes("--url")) {
+      console.error(
+        `  ${import_picocolors18.default.yellow("\u26A0")} active project ${import_picocolors18.default.bold(guard.activeProfile)} has no stored key ${import_picocolors18.default.dim(
+          `(you have keys for: ${guard.available.join(", ")})`
+        )}`
+      );
+      const loginCmd = guard.activeProfile === "default" ? "ablo login" : `ablo login --project ${guard.activeProfile}`;
+      console.error(
+        import_picocolors18.default.dim(
+          `    Mint one with ${import_picocolors18.default.bold(loginCmd)}, or switch with ${import_picocolors18.default.bold("ablo projects use <slug>")}.`
+        )
+      );
+      process.exitCode = 1;
+      return;
+    }
     const plan = resolvePushPlan();
     if (advanced || plan.flow === "production" && !watching) {
       await push(rest);
@@ -282273,11 +282383,12 @@ async function main() {
     console.log(`                  [--auth apikey] [--storage direct|endpoint] [--project <slug>] [--no-project]`);
     console.log(`                  [--no-agent] [--no-pull] [--no-install] [--no-login]`);
     console.log(`    npx ablo login                         Authorize in your browser (provisions sandbox + production keys)`);
+    console.log(`    npx ablo login --project <slug>        Same, scoped to a project (mints its keys, makes it active)`);
     console.log(`    npx ablo logout                        Remove the stored API key`);
     console.log(`    npx ablo mode [sandbox|production]     Switch active environment, like Stripe`);
     console.log(`    npx ablo projects list                 List the org's projects (default + your own)`);
     console.log(`    npx ablo projects create <slug>        Create a project (its keys/schema/data are isolated)`);
-    console.log(`    npx ablo projects use <slug|default>   Set the active project for new key mints`);
+    console.log(`    npx ablo projects use <slug|default>   Switch the active project (run login --project to mint its keys)`);
     console.log(`    npx ablo status                        Show org, mode, keys, and server health`);
     console.log(`    npx ablo status --json                 Same, machine-readable (mode, key prefix, org id, api host)`);
     console.log(`    npx ablo logs [-n N] [--since 15m]     Tail commit activity (follows; --no-follow to exit)`);

package/dist/client/Ablo.d.ts

@@ -332,8 +332,14 @@ export interface InternalAbloOptions<S extends SchemaRecord = SchemaRecord> {
      */
     configOverrides?: Partial<SyncEngineConfig>;
     /**
-     * @deprecated Server derives sync groups from the apiKey's scope.
-     * Required today as a runtime holdover; removed once Phase 3 ships.
+     * Sync groups (entity scopes) this client subscribes to. **Provisional, not
+     * deprecated** — pick the right lane: normally the server derives these from
+     * the apiKey's scope, but passing them is still REQUIRED today in any config
+     * where the key doesn't resolve them (omitting yields a `degenerate
+     * syncGroups` warning and a zero-fan-out client). Keep passing it explicitly
+     * until the server-derived path ships in Phase 3, at which point it becomes a
+     * true no-op and is removed. Build values with `syncGroup(kind, id)` from
+     * `@abloatai/ablo/schema`.
      */
     syncGroups?: string[];
     /**
@@ -388,7 +394,9 @@ export interface ModelReadOptions extends ClaimedOptions {
 }
 export interface ClaimCreateOptions {
     readonly target: ModelTarget;
-    readonly action: string;
+    /** Human-readable phase shown to peers — `'editing'`, `'writing'`. The same
+     *  word on every claim surface; serialized on the wire as `action`. */
+    readonly reason: string;
     readonly ttl?: Duration;
     /**
      * Join the server's fair FIFO queue when the target is already claimed,
@@ -490,6 +498,20 @@ export interface HttpClaimApi<T> {
     reorder(params: ClaimReorderParams<T>): Promise<void>;
 }
 export interface ModelClient<T = Record<string, unknown>> {
+    /**
+     * Single-row read over HTTP. **Returns an envelope, not the bare row** — the
+     * row is on `.data`, alongside the `.stamp` watermark (for stale-context
+     * guards on the following write) and any active `.claims`. A stateless HTTP
+     * client can't synthesize the watermark from a local snapshot, so the
+     * envelope is load-bearing here (the WebSocket client's `retrieve` returns
+     * `T | undefined` because it reads from the hydrated pool).
+     *
+     * ```ts
+     * const deal = await ablo.deals.retrieve({ id });
+     * deal.data?.recommendation;   // ← the row is on .data
+     * deal.stamp;                  // watermark — pass to the next write's readAt
+     * ```
+     */
     retrieve(params: ModelReadOptions & {
         readonly id: string;
     }): Promise<ModelRead<T>>;

package/dist/client/Ablo.js

@@ -1124,7 +1124,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.reason,
+            reason: claim.reason,
             ...(description ? { description } : {}),
             field: claim.target.field,
             status: 'active',
@@ -1144,7 +1144,7 @@ export function Ablo(options) {
             id: claim.id,
             actor: claim.heldBy,
             participantKind: claim.participantKind,
-            action: claim.action,
+            reason: claim.reason,
             ...(claim.description ? { description: claim.description } : {}),
             field: claim.target.field,
             status: 'queued',
@@ -1246,7 +1246,7 @@ export function Ablo(options) {
         return {
             object: 'claim',
             claimId: claim.claimId,
-            action: claim.action,
+            reason: claim.reason,
             target: claim.target,
             waited,
             release,
@@ -1265,7 +1265,7 @@ export function Ablo(options) {
                 field: claimOptions.target.field,
                 meta: claimOptions.target.meta,
             }, {
-                reason: claimOptions.action,
+                reason: claimOptions.reason,
                 ttl: claimOptions.ttl,
                 queue: claimOptions.queue,
             });
@@ -1348,7 +1348,7 @@ export function Ablo(options) {
                         ...(held.target.field ? { field: held.target.field } : {}),
                         ...(held.target.meta ? { meta: held.target.meta } : {}),
                     },
-                    action: held.action,
+                    reason: held.reason,
                     heldBy: held.actor,
                     participantKind: held.participantKind,
                     expiresAt: held.expiresAt,