@tailor-platform/sdk 2.0.0-next.2 → 2.0.0-next.4

package/docs/services/tailordb-migration.md

@@ -12,7 +12,7 @@ For the CLI command reference, see [`tailordb migration`](../cli/tailordb.md#tai
 
 - **Local snapshot–based diff detection** — each migration is generated by diffing your current type definitions against the previous snapshot stored in `migrations/<NNNN>/`.
 - **Transaction-wrapped data migrations** — each `migrate.ts` script runs inside a database transaction on the platform; if the script throws, all changes in that migration roll back.
-- **Automatic execution during `apply`** — `tailor-sdk deploy` detects pending migrations, runs the two-stage type update (pre-migration → script → post-migration), and updates the migration checkpoint label.
+- **Automatic execution during `apply`** — `tailor deploy` detects pending migrations, runs the two-stage type update (pre-migration → script → post-migration), and updates the migration checkpoint label.
 - **Type-safe scripts** — the generated `db.ts` provides Kysely types that reflect the schema state **before** the migration runs, so transformations are written against the actual data shape.
 
 **Files in `migrations/`**
@@ -42,24 +42,24 @@ When you start with no `migrations/` directory:
 2. Define your initial types in `tailordb/`.
 3. Generate the initial migration:
    ```bash
-   tailor-sdk tailordb migration generate
+   tailor tailordb migration generate
    ```
    This creates `migrations/0000/schema.json` from your current types.
-4. Run `tailor-sdk deploy`. The migration label is set to `0000` on the deployed namespace.
+4. Run `tailor deploy`. The migration label is set to `0000` on the deployed namespace.
 
 ### Adding migrations to an existing project
 
 If you already have a deployed workspace whose schema matches your local type definitions:
 
 1. Add the `migration` block to `tailor.config.ts`.
-2. Run `tailor-sdk tailordb migration generate` to create `0000/schema.json` from current local types.
-3. Run `tailor-sdk deploy`. Because remote schema already matches, no script runs; only the migration label is set.
+2. Run `tailor tailordb migration generate` to create `0000/schema.json` from current local types.
+3. Run `tailor deploy`. Because remote schema already matches, no script runs; only the migration label is set.
 
 If your local types and remote schema have **diverged**, reconcile them before introducing migrations — either update local types to match remote, or accept that the first non-`0000` migration will reflect that gap.
 
 ### Resetting
 
-`tailor-sdk tailordb migration generate --init` deletes the existing `migrations/` directory and starts over from `0000`. Use this only on projects that are not yet deployed, or when you have decided to re-baseline (the next `apply` will see all migrations as new and require coordination — see [Resetting a deployed project](#resetting-a-deployed-project)).
+`tailor tailordb migration generate --init` deletes the existing `migrations/` directory and starts over from `0000`. Use this only on projects that are not yet deployed, or when you have decided to re-baseline (the next `apply` will see all migrations as new and require coordination — see [Resetting a deployed project](#resetting-a-deployed-project)).
 
 ## Migration Workflow
 
@@ -69,7 +69,7 @@ A typical change cycle:
 
    ```typescript
    // tailordb/user.ts
-   export const user = db.type("User", {
+   export const user = db.table("User", {
      name: db.string(),
      email: db.string(), // ← new required field
      ...db.fields.timestamps(),
@@ -79,7 +79,7 @@ A typical change cycle:
 2. **Generate the migration.**
 
    ```bash
-   tailor-sdk tailordb migration generate --name "add email to user"
+   tailor tailordb migration generate --name "add email to user"
    ```
 
    Output:
@@ -109,7 +109,7 @@ A typical change cycle:
 
 4. **Apply.**
    ```bash
-   tailor-sdk deploy
+   tailor deploy
    ```
    The pre-migration phase relaxes the new field to optional, the script runs and populates values, then the post-migration phase enforces `required: true`.
 
@@ -126,10 +126,10 @@ Warning: data loss possible:
 No `migrate.ts` is generated automatically because the schema change itself is non-breaking, but the existing data is dropped during the post-migration phase. If you need to preserve or transform that data first (for example, copy a column into another table before it disappears), add a script with:
 
 ```bash
-tailor-sdk tailordb migration script 0002
+tailor tailordb migration script 0002
 ```
 
-This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json`. The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the type until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor-sdk deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
+This writes `migrations/0002/migrate.ts` and `migrations/0002/db.ts` next to the existing `diff.json`. The removed field stays readable inside `migrate.ts` because the pre-migration phase keeps it on the type until the script finishes (see [Per-migration phases](#per-migration-phases)). The next `tailor deploy` runs the script automatically — `migrate.ts` is executed whenever the file exists on disk, regardless of whether the diff itself required it.
 
 ## Configuration
 
@@ -245,7 +245,7 @@ The same pattern works for switching between scalar and array.
 
 ## Automatic Migration Execution
 
-When you run `tailor-sdk deploy`, the SDK detects pending migrations (anything past the current `sdk-migration` label on the deployed namespace) and runs them in order before continuing with the rest of the apply.
+When you run `tailor deploy`, the SDK detects pending migrations (anything past the current `sdk-migration` label on the deployed namespace) and runs them in order before continuing with the rest of the apply.
 
 ### Per-migration phases
 
@@ -275,10 +275,12 @@ Namespace: tailordb
     - Field 'email': required: remote=false, expected=true
 ```
 
+The error also points you at `migration status`, `migration generate`, `migration sync`, and `migration set` — see [Remote schema drift detected](#remote-schema-drift-detected) for which one applies.
+
 To bypass both checks (not recommended outside of recovery scenarios):
 
 ```bash
-tailor-sdk deploy --no-schema-check
+tailor deploy --no-schema-check
 ```
 
 ### Example output
@@ -297,7 +299,7 @@ tailor-sdk deploy --no-schema-check
 
 ## `migration set` Semantics
 
-`tailor-sdk tailordb migration set <N>` updates the `sdk-migration` label on the deployed namespace's metadata. **It does not modify any data or schema.** It only changes which migrations the next `apply` will consider pending.
+`tailor tailordb migration set <N>` updates the `sdk-migration` label on the deployed namespace's metadata. **It does not modify any data or schema.** It only changes which migrations the next `apply` will consider pending.
 
 | Movement                         | Effect on next `apply`                                                    | Effect on data                                                |
 | -------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------- |
@@ -314,7 +316,7 @@ Use cases:
 
 ## `migration sync` Semantics
 
-`tailor-sdk tailordb migration sync <N>` reconstructs the schema snapshot at migration `N` from the working tree's migration history and **overwrites the remote schema to match it**, then sets the `sdk-migration` label to `N`. Unlike `migration set`, it changes the remote schema as well as the bookkeeping. Like `set`, it never runs `migrate.ts` scripts itself — it only changes what the next `apply` considers pending:
+`tailor tailordb migration sync <N>` reconstructs the schema snapshot at migration `N` from the working tree's migration history and **overwrites the remote schema to match it**, then sets the `sdk-migration` label to `N`. Unlike `migration set`, it changes the remote schema as well as the bookkeeping. Like `set`, it never runs `migrate.ts` scripts itself — it only changes what the next `apply` considers pending:
 
 | Movement                         | Effect on next `apply`                                                                    | Effect on data                                                                                             |
 | -------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
@@ -325,7 +327,7 @@ Before anything is sent to the remote, `sync` verifies that replaying the full m
 
 Because syncing backward causes already-applied scripts to re-execute on the next deploy, **write `migrate.ts` scripts to be idempotent** (see [Performance and Large Tables](#performance-and-large-tables) for resumable `where` clauses).
 
-The main use case is recovering from drift after a `deploy --no-schema-check` from an older revision: instead of checking out that revision, run `migration sync <N>` to restore the remote to a known snapshot, then `tailor-sdk deploy` to apply the remaining migrations from the working tree.
+The main use case is recovering from drift after a `deploy --no-schema-check` from an older revision: instead of checking out that revision, run `migration sync <N>` to restore the remote to a known snapshot, then `tailor deploy` to apply the remaining migrations from the working tree.
 
 ## Team Workflow and CI/CD
 
@@ -340,7 +342,7 @@ Migration numbers are assigned sequentially, so two developers branching off the
 ### CI / CD
 
 - For non-interactive environments, pass `--yes` to `migration generate` and `--yes` to `apply`. `apply` runs migrations automatically when the `migrations/` directory is configured.
-- Run `tailor-sdk tailordb migration status` in CI to detect "developer forgot to commit a migration" situations early. The exit code is non-zero only on errors, so check the output.
+- Run `tailor tailordb migration status` in CI to detect "developer forgot to commit a migration" situations early. The exit code is non-zero only on errors, so check the output.
 - Avoid running migrations in parallel against the same workspace — there is no locking. Serialize deploys per environment.
 
 ### Resetting a deployed project
@@ -348,8 +350,8 @@ Migration numbers are assigned sequentially, so two developers branching off the
 `migration generate --init` is destructive locally but does not touch the deployed workspace. Re-baselining a deployed project requires:
 
 1. Run `migration generate --init` to start over from `0000`.
-2. Run `tailor-sdk tailordb migration set 0` against the deployed namespace.
-3. Run `tailor-sdk deploy` — the new `0000` becomes the baseline.
+2. Run `tailor tailordb migration set 0` against the deployed namespace.
+3. Run `tailor deploy` — the new `0000` becomes the baseline.
 
 Coordinate this with your team because everyone else's local migrations will be invalidated.
 
@@ -367,7 +369,7 @@ After a failure:
 
 1. Read the `Logs:` block in the apply output to find the cause.
 2. Fix `migrate.ts` (or the data it depends on).
-3. Re-run `tailor-sdk deploy`. The same migration runs again because its label was never bumped, and the prior-checkpoint schema is a clean baseline to retry against.
+3. Re-run `tailor deploy`. The same migration runs again because its label was never bumped, and the prior-checkpoint schema is a clean baseline to retry against.
 
 If a migration **succeeds in script** but the **post-migration phase** fails (rare; usually a constraint violation the script should have prevented), the pre-migration changes are **not** rolled back: the script's data changes are already committed and the post-migration phase may have dropped removed columns or types, which cannot be reverted without data loss. Investigate, fix, and re-run.
 
@@ -396,7 +398,7 @@ The machine user needs read/write access to every type the migration script touc
 
 If you see `No machine user available for migration execution`, either:
 
-- Add `machineUsers: { ... }` to your auth config and `tailor-sdk deploy` it, or
+- Add `machineUsers: { ... }` to your auth config and `tailor deploy` it, or
 - Set `migration.machineUser` to an existing machine user name in the db config.
 
 ## Multi-Namespace Coordination
@@ -439,7 +441,7 @@ For genuinely different schemas across environments, prefer separate workspaces
 
 **Resolution:**
 
-1. `tailor-sdk tailordb migration status` to see local vs remote.
+1. `tailor tailordb migration status` to see local vs remote.
 2. Compare with teammates — has someone applied different migrations?
 3. If remote was changed manually, decide whether to update local migrations to match or to use `migration set <N>` to align bookkeeping.
 4. To force the remote schema back to a known snapshot, use `migration sync <N>` (see [`migration sync` Semantics](#migration-sync-semantics)).
@@ -471,7 +473,7 @@ For genuinely different schemas across environments, prefer separate workspaces
 
 **Cause:** Runtime error in your `migrate.ts`, a permission error from the machine user, or a constraint violation when post-migration tightens types.
 
-**Resolution:** Read the `Logs:` block. Fix the script or the data assumption it relies on, and re-run `tailor-sdk deploy`. The label is not bumped on failure, so the same migration retries.
+**Resolution:** Read the `Logs:` block. Fix the script or the data assumption it relies on, and re-run `tailor deploy`. The label is not bumped on failure, so the same migration retries.
 
 ### `migrate.ts` not found for a migration that needs one
 

package/docs/services/tailordb.md

@@ -29,7 +29,7 @@ Define TailorDB Types in files matching glob patterns specified in `tailor.confi
 import { db } from "@tailor-platform/sdk";
 
 // Export both value and type
-export const user = db.type("User", {
+export const user = db.table("User", {
   name: db.string(),
   email: db.string().unique(),
   age: db.int(),
@@ -38,7 +38,7 @@ export const user = db.type("User", {
 export type user = typeof user;
 
 // You can define multiple types in the same file
-export const role = db.type("Role", {
+export const role = db.table("Role", {
   name: db.string().unique(),
 });
 export type role = typeof role;
@@ -47,7 +47,7 @@ export type role = typeof role;
 Specify plural form by passing an array as first argument:
 
 ```typescript
-db.type(["User", "UserList"], {
+db.table(["User", "UserList"], {
   name: db.string(),
 });
 ```
@@ -55,7 +55,7 @@ db.type(["User", "UserList"], {
 Pass a description as second argument:
 
 ```typescript
-db.type("User", "User in the system", {
+db.table("User", "User in the system", {
   name: db.string(),
 });
 ```
@@ -174,11 +174,11 @@ db.string().unique();
 Add a relation to field with automatic index and foreign key constraint:
 
 ```typescript
-const role = db.type("Role", {
+const role = db.table("Role", {
   name: db.string(),
 });
 
-const user = db.type("User", {
+const user = db.table("User", {
   name: db.string(),
   roleId: db.uuid().relation({
     type: "n-1",
@@ -190,7 +190,7 @@ const user = db.type("User", {
 For one-to-one relations, use `type: "1-1"`:
 
 ```typescript
-const userProfile = db.type("UserProfile", {
+const userProfile = db.table("UserProfile", {
   userId: db.uuid().relation({
     type: "1-1",
     toward: { type: user },
@@ -202,7 +202,7 @@ const userProfile = db.type("UserProfile", {
 For foreign key constraint without creating a relation, use `type: "keyOnly"`:
 
 ```typescript
-const user = db.type("User", {
+const user = db.table("User", {
   roleId: db.uuid().relation({
     type: "keyOnly",
     toward: { type: role },
@@ -213,11 +213,11 @@ const user = db.type("User", {
 Create relations against different fields using `toward.key`:
 
 ```typescript
-const user = db.type("User", {
+const user = db.table("User", {
   email: db.string().unique(),
 });
 
-const userProfile = db.type("UserProfile", {
+const userProfile = db.table("UserProfile", {
   userEmail: db.string().relation({
     type: "1-1",
     toward: { type: user, key: "email" },
@@ -228,7 +228,7 @@ const userProfile = db.type("UserProfile", {
 Customize relation names using `toward.as` / `backward` options:
 
 ```typescript
-const userProfile = db.type("UserProfile", {
+const userProfile = db.table("UserProfile", {
   userId: db.uuid().relation({
     type: "1-1",
     toward: { type: user, as: "base" },
@@ -254,6 +254,29 @@ type User {
 - `toward.as` - Customizes the field name for accessing the related type from this type
 - `backward` - Customizes the field name for accessing this type from the related type
 
+Relation names share the same GraphQL field namespace as fields, files, and other relations on
+the type. The SDK rejects duplicate or empty relation names. Use `toward.as` when multiple fields
+on the same type point to the same target type, because their default forward names are derived
+from the target type name:
+
+```typescript
+const post = db.table("Post", {
+  authorID: db.uuid().relation({
+    type: "n-1",
+    toward: { type: user, as: "author" },
+    backward: "authoredPosts",
+  }),
+  reviewerID: db.uuid().relation({
+    type: "n-1",
+    toward: { type: user, as: "reviewer" },
+    backward: "reviewedPosts",
+  }),
+});
+```
+
+Use `toward.as` or `backward` when a generated relation name would conflict with an existing
+field, files entry, or relation on the same type.
+
 ### Hooks
 
 Add hooks to execute functions during data creation or update. Hooks receive three arguments:
@@ -277,11 +300,11 @@ db.string().hooks({
 
 #### Type-level Hooks
 
-Set hooks for multiple fields at once using `db.type().hooks()`:
+Set hooks for multiple fields at once using `db.table().hooks()`:
 
 ```typescript
 export const customer = db
-  .type("Customer", {
+  .table("Customer", {
     firstName: db.string(),
     lastName: db.string(),
     fullName: db.string(),
@@ -299,7 +322,7 @@ export const customer = db
 ```typescript
 // Compile error - cannot set hooks on the same field twice
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string().hooks({ create: ({ data }) => data.firstName }), // Field-level
   })
   .hooks({
@@ -308,7 +331,7 @@ export const user = db
 
 // OK - set hooks on different fields
 export const user = db
-  .type("User", {
+  .table("User", {
     firstName: db.string().hooks({ create: () => "John" }), // Field-level on firstName
     lastName: db.string(),
   })
@@ -340,11 +363,11 @@ db.string().validate(
 
 #### Type-level Validation
 
-Set validators for multiple fields at once using `db.type().validate()`:
+Set validators for multiple fields at once using `db.table().validate()`:
 
 ```typescript
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string(),
     email: db.string(),
   })
@@ -362,7 +385,7 @@ export const user = db
 ```typescript
 // Compile error - cannot set validation on the same field twice
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string().validate(({ value }) => value.length > 0), // Field-level
   })
   .validate({
@@ -371,7 +394,7 @@ export const user = db
 
 // OK - set validation on different fields
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string().validate(({ value }) => value.length > 0), // Field-level on name
     email: db.string(),
   })
@@ -403,7 +426,7 @@ db.string().serial({
 ### Common Fields
 
 ```typescript
-export const user = db.type("User", {
+export const user = db.table("User", {
   name: db.string(),
   ...db.fields.timestamps(),
 });
@@ -416,7 +439,7 @@ export const user = db.type("User", {
 ### Composite Indexes
 
 ```typescript
-db.type("User", {
+db.table("User", {
   firstName: db.string(),
   lastName: db.string(),
 }).indexes({
@@ -429,7 +452,7 @@ db.type("User", {
 ### File Fields
 
 ```typescript
-db.type("User", {
+db.table("User", {
   name: db.string(),
 }).files({
   avatar: "profile image",
@@ -439,7 +462,7 @@ db.type("User", {
 ### Features
 
 ```typescript
-db.type("User", {
+db.table("User", {
   name: db.string(),
 }).features({
   aggregation: true,
@@ -452,7 +475,7 @@ db.type("User", {
 Enable event publishing for a type to trigger executors on record changes:
 
 ```typescript
-db.type("User", {
+db.table("User", {
   name: db.string(),
 }).features({
   publishEvents: true,
@@ -463,7 +486,7 @@ db.type("User", {
 
 - When `publishEvents: true`, record creation/update/deletion events are published
 - When not specified, it is **automatically set to `true`** if an executor uses this type with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`
-- When explicitly set to `false` while an executor uses this type, an error is thrown during `tailor-sdk deploy`
+- When explicitly set to `false` while an executor uses this type, an error is thrown during `tailor deploy`
 
 **Use cases:**
 
@@ -471,7 +494,7 @@ db.type("User", {
 
    ```typescript
    // publishEvents is automatically enabled because an executor uses this type
-   export const order = db.type("Order", {
+   export const order = db.table("Order", {
      status: db.string(),
    });
 
@@ -485,7 +508,7 @@ db.type("User", {
 2. **Manual enable**: Enable event publishing for external consumers or debugging
 
    ```typescript
-   db.type("AuditLog", {
+   db.table("AuditLog", {
      action: db.string(),
    }).features({
      publishEvents: true, // Enable even without executor triggers
@@ -495,7 +518,7 @@ db.type("User", {
 3. **Explicit disable**: Disable event publishing for a type that doesn't need it (error if executor uses it)
 
    ```typescript
-   db.type("TempData", {
+   db.table("TempData", {
      data: db.string(),
    }).features({
      publishEvents: false, // Explicitly disable
@@ -511,7 +534,7 @@ Extract subsets of fields from a `TailorDBType` for reuse in resolvers, executor
 Select specific fields and optionally modify their properties:
 
 ```typescript
-const user = db.type("User", {
+const user = db.table("User", {
   id: db.uuid(),
   name: db.string(),
   email: db.string().unique(),
@@ -581,7 +604,7 @@ Configure Permission and GQLPermission. For details, see the [TailorDB Permissio
 **Important**: Following the secure-by-default principle, all operations are denied if permissions are not configured. You must explicitly grant permissions for each operation (create, read, update, delete).
 
 ```typescript
-db.type("User", {
+db.table("User", {
   name: db.string(),
   role: db.enum(["admin", "user"]).index(),
 })
@@ -611,7 +634,7 @@ import {
   unsafeAllowAllGqlPermission,
 } from "@tailor-platform/sdk";
 
-db.type("User", {
+db.table("User", {
   name: db.string(),
 })
   .permission(unsafeAllowAllTypePermission)
@@ -622,6 +645,6 @@ db.type("User", {
 
 ## Migrations
 
-When you change a TailorDB type definition, the SDK can generate a migration that captures the diff and, for breaking changes, runs a data transformation script during `tailor-sdk deploy`. See the [TailorDB Migrations guide](./tailordb-migration.md) for the full workflow, configuration, supported change types, team coordination, and troubleshooting.
+When you change a TailorDB type definition, the SDK can generate a migration that captures the diff and, for breaking changes, runs a data transformation script during `tailor deploy`. See the [TailorDB Migrations guide](./tailordb-migration.md) for the full workflow, configuration, supported change types, team coordination, and troubleshooting.
 
 For the CLI command reference, see [`tailordb migration`](../cli/tailordb.md#tailordb-migration).

package/docs/services/workflow.md

@@ -207,23 +207,23 @@ Wait points allow a workflow job to suspend execution and wait for an external s
 
 ### Defining Wait Points
 
-Use `defineWaitPoint` to declare a single typed wait point:
+Use `createWaitPoint` to create a single typed wait point:
 
 ```typescript
-import { defineWaitPoint } from "@tailor-platform/sdk";
+import { createWaitPoint } from "@tailor-platform/sdk";
 
-export const approval = defineWaitPoint<
+export const approval = createWaitPoint<
   { message: string; requestId: string },
   { approved: boolean }
 >("approval");
 ```
 
-For multiple wait points, use `defineWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:
+For multiple wait points, use `createWaitPoints` with a builder callback. Property names become wait point keys, and JSDoc on each property is preserved in IDE autocompletion:
 
 ```typescript
-import { defineWaitPoints } from "@tailor-platform/sdk";
+import { createWaitPoints } from "@tailor-platform/sdk";
 
-export const waitPoints = defineWaitPoints((define) => ({
+export const waitPoints = createWaitPoints((define) => ({
   /** Manager approval step */
   managerApproval: define<{ amount: number }, { approved: boolean }>(),
   /** Finance review step */
@@ -245,9 +245,9 @@ Both must be JsonValue-compatible (plain objects/arrays; no class instances or f
 Call `.wait()` inside a workflow job body to suspend execution:
 
 ```typescript
-import { createWorkflow, createWorkflowJob, defineWaitPoint } from "@tailor-platform/sdk";
+import { createWaitPoint, createWorkflow, createWorkflowJob } from "@tailor-platform/sdk";
 
-export const approval = defineWaitPoint<
+export const approval = createWaitPoint<
   { message: string; requestId: string },
   { approved: boolean }
 >("approval");
@@ -351,6 +351,84 @@ export default createWorkflow({
 });
 ```
 
+## Execution Policies
+
+Execution policies apply a per-key concurrency cap to workflow job function dispatches. Declare them at the workspace level and pass a matching key when triggering a job; the platform serializes dispatches that resolve to the same key and suspends any that would exceed the cap until slots free up.
+
+### Declaring Policies
+
+Use `defineWorkflowExecutionPolicies` with a builder callback. Property names supply the workspace-unique name and default key prefix verbatim, matching the mental model of `defineWaitPoints`. Override `name` or `key` in the body when the property identifier is not valid execution policy grammar or the key prefix needs to differ. Set `matchType: "prefix"` to register the prefix as a wildcard that matches every dispatch key starting with it (the default, `"exact"`, matches only a dispatch key equal to it).
+
+```typescript
+import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";
+
+export const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
+  /** Shared cap across every "premium" worker dispatch. */
+  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
+  /** Per-tenant cap: one pool per resolved tenant key. */
+  tenantApi: define({
+    name: "tenant-api",
+    matchType: "prefix",
+    concurrencyPolicy: { maxConcurrentExecutions: 3 },
+  }),
+}));
+```
+
+For a single policy, use `defineWorkflowExecutionPolicy(name, def?)`; the key prefix defaults to `name` when `key` is omitted.
+
+`concurrencyPolicy` is optional; when omitted, the policy registers the key as valid without a user-defined limit (platform safety nets still apply).
+
+Register the policies on your config so the SDK creates them on the workspace during deploy:
+
+```typescript
+// tailor.config.ts
+import { defineConfig } from "@tailor-platform/sdk";
+import { executionPolicies } from "./workflows/policies";
+
+export default defineConfig({
+  workflow: {
+    files: ["workflows/**/*.ts"],
+    executionPolicies,
+  },
+});
+```
+
+### Key Grammar
+
+`key` accepts `[a-z0-9_:.-]` and must start with `[a-z0-9]`. An exact key must also end with `[a-z0-9]`; a wildcard prefix (`matchType: "prefix"`) may end with any of those characters, since the platform appends a trailing `*` after it. The platform-registered key — including that trailing `*` when wildcarded — is 2 to 64 characters long, so a wildcard prefix must be at most 63 characters. `foo:bar` is a valid exact key; `tenant-api` with `matchType: "prefix"` registers `tenant-api*` as a wildcard prefix.
+
+An exact-key policy applies to dispatches whose runtime key equals the policy key. A wildcard policy applies to every dispatch whose runtime key begins with the prefix; each concrete resolved key gets its own independent pool of the declared size (a `cap = 3` wildcard yields three concurrent dispatches per resolved key, not three across every match). The longest matching prefix wins when a dispatch could match more than one wildcard.
+
+### Referencing a Policy from a Workflow
+
+Pass the runtime key through the `executionPolicyKey` option on `job.trigger()` or `tailor.workflow.triggerJobFunction()`. For exact-key policies, use `<policy>.key` directly — it's typed so only a value that came from a declared policy can be passed. For wildcard policies (`matchType: "prefix"`), there is no `<policy>.key` — call `<policy>.keyFor(suffix)` to build the concrete key. `keyFor` joins the prefix and suffix with `.` by default; override it with `separator` — the second argument to `defineWorkflowExecutionPolicies` (applies to every policy in the group), or a `def` field on a single `defineWorkflowExecutionPolicy`.
+
+```typescript
+import { createWorkflowJob } from "@tailor-platform/sdk";
+import { executionPolicies } from "./policies";
+import { sendNotification } from "./jobs/send-notification";
+import { fetchTenant } from "./jobs/fetch-tenant";
+
+export const mainJob = createWorkflowJob({
+  name: "main-job",
+  body: async (input: { tenantId: string }) => {
+    // Exact key policy: pass .key directly.
+    await sendNotification.trigger(
+      { message: "Order processed" },
+      { executionPolicyKey: executionPolicies.premium.key },
+    );
+
+    // Wildcard policy: build the concrete key with keyFor().
+    await fetchTenant.trigger(
+      { tenantId: input.tenantId },
+      { executionPolicyKey: executionPolicies.tenantApi.keyFor(input.tenantId) },
+    );
+  },
+});
+```
+
+The same `executionPolicyKey` option is available on `tailor.workflow.triggerJobFunction(name, args, options)` for jobs invoked by name.
+
 ## Triggering a Workflow from a Resolver
 
 You can start a workflow execution from a resolver using `workflow.trigger()`.
@@ -406,22 +484,22 @@ Manage workflows using the CLI:
 
 ```bash
 # List workflows
-tailor-sdk workflow list
+tailor workflow list
 
 # Get workflow details
-tailor-sdk workflow get <name>
+tailor workflow get <name>
 
 # Start a workflow
-tailor-sdk workflow start <name> -m <machine-user> -a '{"key": "value"}'
+tailor workflow start <name> -m <machine-user> -a '{"key": "value"}'
 
 # List executions
-tailor-sdk workflow executions
+tailor workflow executions
 
 # Get execution details with logs
-tailor-sdk workflow executions <execution-id> --logs
+tailor workflow executions <execution-id> --logs
 
 # Resume a failed execution
-tailor-sdk workflow resume <execution-id>
+tailor workflow resume <execution-id>
 ```
 
 See [Workflow CLI Commands](../cli/workflow.md) for full documentation.