@abloatai/ablo 0.5.1 → 0.7.0

package/docs/api.md

@@ -11,67 +11,59 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  tasks: model({
-    title: z.string(),
-    status: z.enum(['todo', 'doing', 'done']),
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
   }),
 });
 
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 await ablo.ready();
-const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
-if (!task) throw new Error('Task not found');
+const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+if (!report) throw new Error('Row not found');
 
-await ablo.tasks.update('task_123', { status: 'done' }, { wait: 'confirmed' });
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
 ```
 
 ## Model Methods
 
-Each schema model becomes a typed resource on the client:
+Each schema model becomes a typed model on the client:
 
-- `ablo.tasks.load({ where })` hydrates rows asynchronously.
-- `ablo.tasks.retrieve(id)` reads one already-loaded row synchronously.
-- `ablo.tasks.create(data)` creates a row.
-- `ablo.tasks.update(id, data, options?)` updates a row.
-- `ablo.tasks.delete(id, options?)` deletes a row.
+- `ablo.weatherReports.load({ where })` hydrates rows asynchronously.
+- `ablo.weatherReports.retrieve(id)` reads one already-loaded row synchronously.
+- `ablo.weatherReports.create(data)` creates a row.
+- `ablo.weatherReports.update(id, data, options?)` updates a row.
+- `ablo.weatherReports.delete(id, options?)` deletes a row.
 
-`load` and `retrieve` are not aliases. Use `load` when the row may not be in the
-local pool yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
-local read.
+`load` and `retrieve` are not aliases. Use `load` when the row may not be loaded
+yet. Use `retrieve` after `ready()` or `load()` when you want a cheap
+synchronous read.
 
 | Method | Returns | Use when |
 |---|---|---|
 | `load({ where })` | `Promise<T[]>` | You need to hydrate rows from local store and server. |
-| `retrieve(id)` | `T \| undefined` | You already loaded the row and want a synchronous local read. |
-| `list(options?)` | `T[]` | You want a synchronous local list. |
-| `count(options?)` | `number` | You want a synchronous local count. |
+| `retrieve(id)` | `T \| undefined` | You already loaded the row and want a synchronous read. |
+| `list(options?)` | `T[]` | You want a synchronous list of loaded rows. |
+| `count(options?)` | `number` | You want a synchronous count of loaded rows. |
 | `create(data, options?)` | `Promise<T>` | You want to create through the schema model. |
 | `update(id, data, options?)` | `Promise<T>` | You want to update through the schema model. |
 | `delete(id, options?)` | `Promise<void>` | You want to delete through the schema model. |
 
-`list` and `count` read the local pool. They default to live rows and accept:
-
-```ts
-const activeDoneTasks = ablo.tasks.list({
-  where: { status: 'done' },
-  filter: (task) => !task.title.startsWith('[archived]'),
-  orderBy: { updatedAt: 'desc' },
-  limit: 20,
-  scope: 'live', // 'live' | 'archived' | 'all'
-});
-```
+`load`, `create`, `update`, and `delete` are the main path — they go through the
+server. `retrieve` / `list` / `count` are **synchronous reads** off the rows a
+session has already loaded, so a cheap re-read needs no round-trip.
 
 ## Protected Writes
 
 Use `snapshot` when a write should reject if the row changed mid-flight:
 
 ```ts
-const snap = ablo.snapshot({ tasks: 'task_123' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
 );
 ```
@@ -82,62 +74,43 @@ Protected write options:
 |---|---|
 | `readAt` | The state cursor the write was based on. |
 | `onStale` | Stale-state policy. Prefer `reject` for agent writes. |
-| `intent` | Active work claim associated with the write. |
 | `wait` | `queued` resolves after local queueing; `confirmed` waits for server acceptance. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time to wait for the write call. |
 
-## Advanced Resource API
-
-Use `resource(name)` only when you intentionally need the raw protocol shape:
-generic server runtimes, MCP routes, batch tools, or code that has no schema.
-
-```ts
-const tasks = ablo.resource<{ status: string }>('tasks');
-
-const { data, stamp, intents } = await tasks.retrieve('task_123', {
-  ifBusy: 'return',
-});
-```
-
-`stamp` is the state watermark. Pass it as `readAt` to reject stale writes.
+## Claims
 
-`intents` lists active work on the target. Set `ifBusy: 'wait'` to wait for
-that work to clear, or `ifBusy: 'fail'` to throw `AbloBusyError`.
+A claim tells humans and agents who is working on a target before the write
+lands. One self-describing object carries the lifecycle in a single `status`
+field. It lives on the coordination plane: ephemeral, TTL'd, broadcast to peers
+in real time, and never persisted as a row.
 
-## Intent
+Coordinate one through flat verbs on the model, beside `create`/`update`/`retrieve`:
+`ablo.<model>.claim(id, ...)` to claim a row, `ablo.<model>.claimState(id)` to read
+who holds it (synchronous; never blocks), and `ablo.<model>.release(id)` to release
+early. Claims are **advisory** — they serialize on contention rather than locking.
 
-Intent is the coordination object — it tells humans and agents who is working on
-a target before the write lands. Like Stripe's `PaymentIntent`, one
-self-describing object carries the whole lifecycle in a single `status` field.
-It lives on the **coordination plane**: ephemeral, TTL'd, broadcast to peers in
-real time, and never persisted as a row.
-
-Read or open one through the model accessor — `ablo.<model>.intent(id)` — which
-sits beside `create`/`update`/`retrieve` and returns a handle **synchronously**,
-so you can inspect who holds a target without awaiting.
-
-### The Intent object
+### The Claim State Object
 
 | Field | Type | Description |
 |---|---|---|
-| `object` | `'intent'` | String representing the object's type. Always `'intent'`. |
-| `id` | string | Unique identifier for the intent. |
+| `object` | `'claim'` | String representing the object's type. |
+| `id` | string | Unique identifier for the claim. |
 | `status` | `'active' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. |
 | `target` | `{ type, id, field? }` | What is being coordinated. |
 | `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
-| `heldBy` | string | Participant id holding the intent. |
+| `heldBy` | string | Participant id holding the claim. |
 | `participantKind` | `'human' \| 'agent'` | Whether a human session or an agent holds it. |
 | `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
 
 ```json
 {
-  "object": "intent",
-  "id": "int_3MtwBwLkdIwHu7ix",
+  "object": "claim",
+  "id": "claim_3MtwBwLkdIwHu7ix",
   "status": "active",
-  "target": { "type": "tasks", "id": "task_123", "field": "status" },
+  "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
   "action": "editing",
-  "heldBy": "agent:task-writer",
+  "heldBy": "agent:report-writer",
   "participantKind": "agent",
   "expiresAt": "1716580000000"
 }
@@ -146,128 +119,54 @@ so you can inspect who holds a target without awaiting.
 ### Lifecycle
 
 ```
-            claim()                    update() lands
+            claim(id)                  update(id) lands
   (free) ───────────▶ active ───────────────────────▶ committed
                         │
             ┌───────────┴───────────┐
             ▼                       ▼
         canceled                 expired
-     (finish w/o write)       (TTL; holder died)
+   (release w/o write)        (TTL; holder died)
 ```
 
-A target is free when `ablo.<model>.intent(id).current` is `null`. Terminal
-states drop out of the live stream — a present intent is, by definition,
-`active`.
+A target is free when `ablo.<model>.claimState(id)` is `null`. Terminal
+states drop out of the live stream, so a present claim is active.
 
 ### Reading and claiming
 
-```ts
-const task = ablo.tasks.intent('task_123');
+`claimState(id)` is the read side for observers: synchronous, never blocks, and
+returns the live claim state object (or `null`). `claim(id, ...)` is the write side:
+it claims the row and returns the row. Because the claim is **advisory**, if
+someone else already holds the row, `claim` waits for them to finish, then
+re-reads the row before handing it back — so you always proceed from fresh state.
+Default reads stay open; server/model reads can opt into `ifClaimed: 'wait'` or
+`ifClaimed: 'fail'` when they should not read through active work.
 
-// Read side — who is working on this target right now?
-if (task.current) {
-  task.current.heldBy; // 'agent:task-writer'
-  task.current.action; // 'editing'
-  await task.whenFree(); // wait until they finish, then continue
+```ts
+const claim = ablo.weatherReports.claimState('report_stockholm');
+if (claim) {
+  claim.heldBy;
+  claim.action;
 }
 
-// Write side — claim, write, auto-release in one flow.
-await task.claim({ action: 'editing', field: 'status', ttl: '2m' });
-const updated = await task.update({ status: 'done' });
-updated.status; // 'done'
-```
-
-`task.update(...)` carries the same stale-check as a plain update: it rejects
-with `AbloStaleContextError` if the row advanced past your claim point, so you
-re-read before retrying. The intent releases automatically when `update`
-resolves; call `task.finish()` if the work ends without a write.
-
-`task.whenFree({ timeout })` waits until the target is free. Pass `timeout` only
-when your product needs an upper bound.
-
-### Cross-resource coordination
-
-For lower-level coordination that isn't scoped to a single model row, the
-top-level `ablo.intents` resource (`create`, `list`, `waitFor`) remains
-available. Most callers should prefer `ablo.<model>.intent(id)`.
-
-## Advanced Commit API
-
-Most callers use `ablo.<model>.update(...)` or `resource.update(...)`. For atomic
-batches or custom runtimes, use `commits.create`.
-
-```ts
-await ablo.commits.create({
-  wait: 'confirmed',
-  operations: [
-    {
-      action: 'update',
-      resource: 'tasks',
-      id: 'task_123',
-      data: { status: 'done' },
-      readAt: stamp,
-      onStale: 'reject',
-    },
-  ],
-});
+const updated = await ablo.weatherReports.claim(
+  'report_stockholm',
+  async (report) => ablo.weatherReports.update(report.id, { status: 'ready' }),
+  { action: 'editing', ttl: '2m' },
+);
 ```
 
-Every state change becomes a commit. Commits check authorization, stale state,
-intent conflicts, and idempotency.
+Writes go through the normal flat `ablo.<model>.update(id, data)`. While you hold
+a claim on `id`, that `update` is automatically stale-guarded: it rejects with
+`AbloStaleContextError` if the row advanced past your claim point, so you re-read
+before retrying. The callback form releases automatically when the callback
+returns or throws, or call `ablo.weatherReports.release(id)` if you claimed manually and
+need to release early.
 
 ## Agent
 
 Most agents should import the same schema as the app and call
-`ablo.<model>.load(...)` plus `ablo.<model>.update(...)`. The schema-less
-`agent.run(...)` wrapper exists for advanced server workers that cannot import
-the app schema; it creates the capability and task internally and returns
-`done`, `failed`, or `cancelled`.
-
-## Data Source
-
-Use `dataSource(...)` only when the customer's app database remains canonical
-and Ablo should call a signed endpoint instead of storing customer rows itself.
-
-```ts
-import { dataSource } from '@abloatai/ablo';
-import { schema } from './ablo.schema';
-
-export const POST = dataSource({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
-  async commit({ operations, clientTxId, context }) {
-    // Write operations to the customer's database transaction.
-    return { rows: [] };
-  },
-});
-```
-
-The SDK still uses `ablo.<model>.update(...)`. The Data Source endpoint is a
-server-to-server storage adapter. See [Connect Your Database](./data-sources.md).
-
-## Capability
-
-Capabilities are the lower-level permission boundary. Most apps should let
-`agent.run(...)` create and revoke them.
-
-```ts
-const capability = await api.capabilities.create({
-  participantKind: 'agent',
-  participantId: 'agent:task-writer',
-  // Strings derive from the schema's `identityRoles` templates
-  // (see integration-guide.md §1) or a model's `syncGroupFormat`.
-  syncGroups: ['org:acme', 'user:agent:task-writer'],
-  operations: ['tasks.retrieve', 'tasks.update'],
-  lease: '10m',
-});
-```
-
-Use `lease` as a crash cleanup window. Normal agent runs still close when the
-handler returns, fails, or is cancelled.
-
-For the design rationale — why capabilities instead of static API keys,
-why the lease + signature + revocation triple, and how this maps to AWS
-STS / Vault / Auth0 Token Vault — see [Capabilities](./capabilities.md#why-capabilities-not-api-keys).
+`ablo.<model>.load(...)`, `ablo.<model>.claim(...)`, and
+`ablo.<model>.update(...)`.
 
 ## Errors
 
@@ -283,6 +182,6 @@ All SDK errors extend `AbloError` and expose a stable `type` string.
 | `AbloValidationError` | Invalid input. |
 | `AbloServerError` | Server-side 5xx. |
 | `AbloStaleContextError` | `readAt` no longer matches current state. |
-| `AbloBusyError` | Active intent conflict or busy wait timeout. |
+| `AbloClaimedError` | Active claim conflict or claim wait timeout. |
 
 See [Client Behavior](./client-behavior.md) for retry and timeout guidance.

package/docs/audit.md

@@ -12,11 +12,11 @@ tamper-evident, queryable, exportable.
   actorId:              string,
   onBehalfOfKind:       'user' | 'agent' | 'system' | null,
   onBehalfOfId:         string | null,
-  capabilityId:         string | null,
-  capabilityLabel:      string | null,
+  credentialId:         string | null,
+  credentialLabel:      string | null,
   delegationChainRoot:  string | null,    // always points at a human
-  causedByTaskId:       string | null,
-  actionType:           string,           // e.g. 'task.update'
+  causedByRunId:        string | null,
+  actionType:           string,           // e.g. 'weatherReport.update'
   modelName:            string | null,    // e.g. 'claude-opus-4-7'
   diffSummary:          unknown,
   // tamper-evident
@@ -37,7 +37,7 @@ a thing in this system; every chain starts with a person.
 ```bash
 curl https://<your-app>/api/orgs/<slug>/audit/verify-chain?\
   principalKind=agent\
-  &principalId=task-writer-v3
+  &principalId=weather-agent-v3
 ```
 
 Returns either:

package/docs/cli.md

@@ -0,0 +1,212 @@
+# CLI
+
+The `ablo` CLI gets you from an empty project to live-syncing data: scaffold a
+schema, authenticate, push the schema, and watch it sync. Your
+`defineSchema(...)` is the single source of truth — the CLI and the hosted
+server lower it to **the same SQL** through one engine
+(`generateProvisionPlan` / `generateMigrationPlan` in `@abloatai/ablo/schema`).
+
+```bash
+npx ablo init      # scaffold ablo/schema.ts + client
+npx ablo login     # authorize in the browser
+npx ablo dev       # push schema to the test sandbox + watch
+```
+
+## Authenticate
+
+`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`.
+
+| Command | What it does |
+| --- | --- |
+| `ablo login` | Authorize in the browser; provisions + stores a test and a live key. |
+| `ablo logout` | Remove the stored keys. |
+| `ablo status` | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo mode [test\|live]` | Switch the active mode. 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.
+
+## Test vs live
+
+Like Stripe, every account has a **test** mode and a **live** mode, and a key
+belongs to one of them. Test keys are bound to an isolated sandbox: their reads
+and writes never touch live data. Switch with `ablo mode`; `ablo dev` is always
+test mode by design.
+
+The schema, however, is **shared** across the org — pushing a schema (from
+either mode) defines the same models test and live see; only the rows differ.
+
+## Commands
+
+| Command | What it does | Flags |
+| --- | --- | --- |
+| `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 [test\|live]` | Switch active mode. | — |
+| `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 test\|live` |
+| `ablo schema 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` |
+| `ablo pull` | **BYO** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`). | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force` |
+| `ablo check` | **BYO** — verify your *existing* tables fit the schema (read-only, no DDL). | `--schema <path>`, `--export <name>`, `--app-schema <name>` |
+| `ablo generate` | Emit TypeScript types from the schema. | `--out <path>`, `--schema`, `--export` |
+
+## `ablo dev`
+
+The development loop. It pushes `ablo/schema.ts` to your **test sandbox**,
+prints the env line your app needs, then watches the file and re-pushes on every
+save (300 ms debounce). It refuses live keys so a tight save loop can never
+churn production data.
+
+```bash
+npx ablo dev             # push + watch
+npx ablo dev --no-watch  # push once and exit
+```
+
+## `ablo logs`
+
+Tail commit activity, like `stripe logs tail`. Scope comes from the key — a test
+key streams only its sandbox's writes, a live key the org's — so you never pass
+an org. Follows by default; `--no-follow` prints recent and exits.
+
+```bash
+npx ablo logs                      # last 50, then stream
+npx ablo logs -n 100 --model task  # backfill 100, one model
+npx ablo logs --since 15m --json   # last 15m as NDJSON, then stream
+```
+
+Each line is `time · op · model · id · actor`. `--json` emits one event per line
+(NDJSON) for piping to `jq` or an agent.
+
+## `ablo pull`
+
+Generate `defineSchema(...)` from the tables you already have — the inverse of
+provisioning, and read-only (like `prisma db pull`). It introspects
+`DATABASE_URL`, emits a model per adoptable table (one that has `id` +
+`organization_id`), maps Postgres types back to Zod, and writes `ablo/schema.ts`.
+
+```bash
+DATABASE_URL=postgres://… npx ablo pull
+```
+
+It never touches the database, and won't overwrite an existing schema without
+`--force`. Introspection is lossy — enum members, JSON shape, relations, and
+defaults can't be recovered from columns — so treat the output as a starting
+point: review it, then run `ablo check`.
+
+## `ablo check`
+
+The BYO front door. Instead of migrating (DDL on your database), Ablo *adopts*
+the tables you already have: `ablo check` introspects `DATABASE_URL`, compares it
+to your `defineSchema(...)`, and reports — per model — whether the table is
+adoptable. It never writes or alters anything.
+
+A table is adoptable when it has a primary key `id` and (for org-scoped models)
+an `organization_id` column — the tenancy marker the engine isolates on. Every
+other table in your database is ignored.
+
+**Why `organization_id`?** It's the one column that makes a table safe to
+multiplayer-sync. Row-level security scopes every read and write by it (org A
+can't see org B's rows), and the engine routes realtime deltas by `org:<id>`. A
+table without a tenancy key has no isolation boundary, so Ablo excludes it
+**by default** rather than risk exposing it across tenants. If your tenancy
+column has a different name, keep that table behind a
+[Data Source endpoint](/data-sources) for now.
+
+```bash
+DATABASE_URL=postgres://… npx ablo check
+```
+
+```text
+  ✓ tasks     → tasks (id, organization_id ok)
+  ✗ projects  → projects
+      • missing "organization_id" — add it, or move this model behind a Data Source
+  2 models · 1 ok · 1 error
+  12 other tables in your database — ignored by Ablo
+```
+
+If a table can't carry `organization_id` (or has business logic Ablo shouldn't
+bypass), keep it behind a [Data Source endpoint](/data-sources) rather than
+reshaping it. `ablo check` is read-only; it never proposes a migration.
+
+## `migrate` vs `schema push`
+
+Two front doors to the same engine. Use `migrate` when your app owns the
+database (it applies to `DATABASE_URL`); use `schema push` (and `dev`) on the
+hosted path (the server applies to Ablo-managed Postgres and version-gates
+connecting clients).
+
+```bash
+ablo migrate --dry-run            # preview the exact SQL
+ablo migrate                      # apply to DATABASE_URL
+ablo migrate --output schema.sql  # write SQL to a file
+```
+
+## Zod → Postgres type mapping
+
+The one type map, shared by both paths (there is no second mapping):
+
+| Zod | Postgres |
+| --- | --- |
+| `z.string()` | `TEXT` |
+| `z.number()` | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.boolean()` | `BOOLEAN` |
+| `z.date()` | `TIMESTAMPTZ` |
+| `z.enum([...])` | `TEXT` + a `CHECK (col IN (...))` constraint |
+| `z.object` / `z.array` / `z.record` / `z.union` / `z.custom` | `JSONB` |
+| `.optional()` / `.nullable()` | nullable column |
+
+Each table also gets the platform columns (`id`, `organization_id`,
+`created_by`, `created_at`, `updated_at`), an `organization_id` index, and
+row-level security keyed on `current_setting('app.current_org_id')` for tenant
+isolation.
+
+`.default(...)` is **not** emitted as a SQL column default — Zod applies the
+default at write time (`create`), in one place, so a DB default and a schema
+default can't drift.
+
+## Structured errors
+
+A failed migration aborts the whole transaction (nothing partial lands) and
+reports the same `migration_failed` shape on both paths — naming the statement
+that broke and the Postgres SQLSTATE, not just "migration failed".
+
+`ablo migrate` (local) logs it:
+
+```txt
+[migrate] migration plan failed {
+  code: 'migration_failed',
+  failedStatement: 'ALTER TABLE "public"."tasks" RENAME COLUMN a TO b;',
+  failedStatementIndex: 4,
+  pgCode: '42P01',
+  durationMs: 133
+}
+```
+
+`ablo schema push` (hosted) returns the canonical error envelope (HTTP 500),
+which the SDK reconstructs as a typed `AbloServerError`:
+
+```json
+{
+  "type": "AbloServerError",
+  "code": "migration_failed",
+  "message": "schema migration failed: relation \"...\" does not exist",
+  "doc_url": "https://docs.abloatai.com/errors#migration_failed",
+  "failedStatement": "ALTER TABLE ... RENAME COLUMN a TO b;",
+  "pgCode": "42P01"
+}
+```
+
+The pushed artifact is recorded `failed` and is never activated, so a broken
+migration can't leave clients gated against tables that don't match.
+
+## Environment
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `ABLO_API_KEY` | Authenticate without `ablo login` (CI). Always overrides the stored key. | — |
+| `ABLO_API_URL` | Control-plane / API host (`schema push`, `dev`, `status`). | `https://api.abloatai.com` |
+| `ABLO_AUTH_URL` | Dashboard origin for `ablo login`'s device flow. | `https://abloatai.com` |
+| `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives. | `~/.config/ablo` |