@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.10

package/docs/services/http-adapter.md

@@ -7,7 +7,7 @@ HTTP adapters expose REST-style HTTP endpoints on your application by translatin
 Each HTTP adapter is a single file that declares:
 
 - A `pathPattern` (which methods it handles is derived from the `input` keys)
-- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`)
+- An `input` object keyed by lowercase HTTP method (`get`, `post`, `put`, `patch`, `delete`) — each value is a function that converts an incoming HTTP request into a GraphQL request (`query`, `variables`, `operationName`). `query` can be a GraphQL string or a generated `TypedDocumentNode`.
 - An optional `output` function — **shared across all methods** — that converts the GraphQL response into an HTTP response (`statusCode`, `headers`, `body`)
 
 Adapters are deployed together with your application. When a request arrives under the `/api/` prefix and matches an adapter, the handler for the request method runs server-side.
@@ -74,6 +74,21 @@ A request to `GET /api/users/abc-123` invokes the `get` handler, runs the result
 
 If `output` is omitted, the raw GraphQL response is returned as JSON.
 
+### Typed GraphQL Documents
+
+`input` handlers can return generated `TypedDocumentNode` values instead of query strings. The SDK uses the document's variables type for `variables`, and passes the document's result type to `output` as `resp.data`.
+
+```typescript
+import { GetUserDocument } from "../generated/graphql";
+
+get: (req) => ({
+  query: GetUserDocument,
+  variables: { id: req.path.split("/")[2] ?? "" },
+});
+```
+
+When multiple methods return different typed documents, `resp.data` is the union of those result types because `output` is shared across the adapter. If a method returns a plain string query, its result type is `unknown`. When extracting an input handler and annotating it separately, pass the document type to `HttpAdapterInputFn` so required variables stay typed.
+
 ### Optional fields
 
 Beyond `name`, `pathPattern`, `input`, and `output`, two optional fields control deploy-time behavior:

package/docs/services/idp.md

@@ -86,7 +86,8 @@ defineIdp("my-idp", {
 - `read` - Controls who can read IdP users
 - `update` - Controls who can update IdP users
 - `delete` - Controls who can delete IdP users
-- `sendPasswordResetEmail` - Controls who can send password reset emails. The examples above disable this operation; to enable it, use a permission such as `[{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }]`.
+- `sendPasswordResetEmail` - Controls who can send password reset emails. Required unless `userAuthPolicy.disablePasswordAuth` is `true` or `gqlOperations.sendPasswordResetEmail` is `false` (the password-reset flow has no meaning when password authentication is off or the operation is disabled). Set `[{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }]` to allow, or `[]` to deny.
+- `unenrollMfa` - Controls who can remove an enrolled MFA factor from a user. Required when `userAuthPolicy.enableMfa` is `true` unless `gqlOperations.unenrollMfa` is `false`; omit otherwise. Typically restricted to administrators.
 
 **Policy fields:** each entry in an operation's policy array supports:
 
@@ -166,6 +167,37 @@ defineIdp("my-idp", {
 - `allowGoogleOauth` - Enable the "Sign in with Google" button. Default `false`.
 - `allowMicrosoftOauth` - Enable the "Sign in with Microsoft" button. Default `false`.
 
+**MFA (TOTP):**
+
+```typescript
+import { defineIdp, defineStaticWebSite } from "@tailor-platform/sdk";
+
+const website = defineStaticWebSite("my-frontend", { description: "App frontend" });
+
+defineIdp("my-idp", {
+  clients: ["my-client"],
+  userAuthPolicy: {
+    enableMfa: true,
+    requireMfa: false,
+    allowedReturnOrigins: [website.url, "https://admin.example.com"],
+    mfaIssuer: "My App",
+  },
+  permission: {
+    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    unenrollMfa: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+  },
+});
+```
+
+- `enableMfa` - Make TOTP MFA available for users in this namespace. Default `false`. When enabled, users can register an authenticator app (Google Authenticator, 1Password, etc.) from the IdP self-service page.
+- `requireMfa` - Force password-authenticated users to enroll and pass an MFA challenge on each sign-in. Default `false`. Social sign-in (`allowGoogleOauth` / `allowMicrosoftOauth`) is not affected; the upstream provider's MFA covers those sessions.
+- `allowedReturnOrigins` - Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at apply time. Required when `enableMfa` is `true`.
+- `mfaIssuer` - Label shown next to the user account in authenticator apps when TOTP is enrolled. Up to 64 characters. Falls back to `"Tailor Platform IdP"` when empty.
+
 **Constraints:** the following combinations are rejected at parse time.
 
 - `passwordMinLength` must be less than or equal to `passwordMaxLength`.
@@ -173,6 +205,23 @@ defineIdp("my-idp", {
 - `allowGoogleOauth` requires a non-empty `allowedEmailDomains`.
 - `allowMicrosoftOauth` requires both a non-empty `allowedEmailDomains` and `disablePasswordAuth: true`.
 - `disablePasswordAuth` requires `allowGoogleOauth` or `allowMicrosoftOauth`, and cannot be combined with `allowSelfPasswordReset`.
+- `requireMfa: true` requires `enableMfa: true`.
+- `enableMfa: true` requires at least one entry in `allowedReturnOrigins`.
+- `enableMfa: true` requires `permission` to be defined and to include an explicit `unenrollMfa` policy (an empty array `[]` to deny is fine), unless `gqlOperations.unenrollMfa` is `false` (or `gqlOperations: "query"`, which normalizes to the same), in which case the operation is turned off and the policy may be omitted.
+
+**Runtime API:** function code can inspect and revoke a user's enrolled factor through `idp.Client`. The `User` records returned by `user`, `userByName`, `users`, `createUser`, and `updateUser` expose `mfaEnrolled` (boolean) and `mfaFactorIds` (string array), and `client.unenrollMfa({ userId, mfaFactorId })` removes a single factor. The factor ID to pass back is one of the entries in `user.mfaFactorIds`. Calling `unenrollMfa` requires the `unenrollMfa` permission above.
+
+```typescript
+import { idp } from "@tailor-platform/sdk/runtime";
+
+const client = new idp.Client({ namespace: "my-idp" });
+const user = await client.user("user-id");
+if (user.mfaEnrolled) {
+  for (const factorId of user.mfaFactorIds) {
+    await client.unenrollMfa({ userId: user.id, mfaFactorId: factorId });
+  }
+}
+```
 
 ### gqlOperations
 
@@ -187,6 +236,8 @@ defineIdp("my-idp", {
     update: true,
     delete: false,
     sendPasswordResetEmail: false,
+    requestMfaSettingsUrl: false,
+    unenrollMfa: false,
   },
 });
 ```
@@ -198,8 +249,10 @@ defineIdp("my-idp", {
 - `update` - The `_updateUser` mutation.
 - `delete` - The `_deleteUser` mutation.
 - `sendPasswordResetEmail` - The `_sendPasswordResetEmail` mutation.
+- `requestMfaSettingsUrl` - The `_requestMfaSettingsUrl` query that issues a self-service URL for MFA settings.
+- `unenrollMfa` - The `_unenrollMfa` mutation that removes a user's enrolled MFA factor. When set to `false`, `permission.unenrollMfa` may be omitted even with `userAuthPolicy.enableMfa: true`.
 
-**Shortcut:** pass the string `"query"` to expose a read-only IdP. It enables `read` and disables every mutation.
+**Shortcut:** pass the string `"query"` to expose a read-only IdP. It enables the queries (`read`, `requestMfaSettingsUrl`) and disables every mutation.
 
 ```typescript
 defineIdp("my-idp", {

package/docs/services/resolver.md

@@ -108,7 +108,7 @@ Define input/output schemas using methods of `t` object. Basic usage and support
 You can reuse fields defined with `db` object, but note that unsupported options will be ignored:
 
 ```typescript
-const user = db.type("User", {
+const user = db.table("User", {
   name: db.string().unique(),
   age: db.int(),
 });
@@ -208,7 +208,7 @@ Validation functions receive:
 
 - `value` - The field value being validated
 - `data` - The entire input object
-- `user` - The user performing the operation
+- `invoker` - The principal performing the operation
 
 You can specify validation as:
 
@@ -234,8 +234,8 @@ Validation runs automatically before the `body` function executes. When validati
 Define actual resolver logic in the `body` function. Function arguments include:
 
 - `input` - Input data from GraphQL request
-- `user` - The user who called this resolver; unaffected by `authInvoker`
-- `invoker` - The principal running this function; equals `user` by default, or the machine user set by `authInvoker`. `null` for anonymous calls.
+- `caller` - The user or machine user who called this resolver; unaffected by `invoker`. `null` for anonymous calls.
+- `invoker` - The principal running this function; equals `caller` by default, or the machine user configured through the resolver `invoker` option. `null` for anonymous calls.
 - `env` - Environment variables declared in `tailor.config.ts`
 
 ### Using Kysely for Database Access
@@ -306,7 +306,7 @@ createResolver({
 
 - When `publishEvents: true`, resolver execution events are published
 - When not specified, it is **automatically set to `true`** if an executor uses this resolver with `resolverExecutedTrigger`
-- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor-sdk deploy`
+- When explicitly set to `false` while an executor uses this resolver, an error is thrown during `tailor deploy`
 
 **Use cases:**
 
@@ -350,9 +350,63 @@ createResolver({
    });
    ```
 
+## Permissions
+
+### Access Requirement (`permission`)
+
+By default, a resolver with no in-body check is reachable by an anonymous (unauthenticated) caller. Set `permission` to reject callers that don't match a condition, evaluated before `body` runs:
+
+```typescript
+import { createResolver, t } from "@tailor-platform/sdk";
+
+export default createResolver({
+  name: "getMyOrders",
+  operation: "query",
+  permission: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+  output: t.object({ count: t.int() }),
+  body: async (context) => {
+    // context.user is guaranteed to be an authenticated caller here
+    return { count: 0 };
+  },
+});
+```
+
+`permission` uses the same `conditions`/`permit` notation as TailorDB's `.permission()` — an array of policies, restricted to `user` operands (a resolver has no associated record to compare against) with equality (`=`/`!=`) comparisons:
+
+- `{ user: "_loggedIn" }` — whether the caller is authenticated
+- `{ user: "id" }` — the caller's user ID
+- `{ user: "someAttribute" }` — any string or boolean attribute enabled in `auth.userProfile.attributes` (or `auth.machineUserAttributes` for machine users); array attributes aren't supported, since conditions only compare against a single string/boolean value
+
+Multiple conditions within the same policy's `conditions` array are combined with AND. `permit` is required, with no implicit default. At least one `permit: true` policy is required: `permission` is an allow-list, denied by default and granted only by a matching `permit: true` policy. This lets you express different eligibility paths, e.g. allowing machine-user callers unconditionally while gating regular users behind a role check:
+
+```typescript
+permission: [
+  { conditions: [[{ user: "isServiceAccount" }, "=", true]], permit: true },
+  { conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true },
+],
+```
+
+A `permit: false` policy always denies matching callers, even ones another policy would otherwise allow. Combine it with a `permit: true` policy to carve out an explicit exception, e.g. granting access broadly but rejecting one banned role:
+
+```typescript
+permission: [
+  { conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true },
+  { conditions: [[{ user: "role" }, "=", "BANNED"]], permit: false },
+],
+```
+
+A policy array made up of only `permit: false` policies is rejected: since none of its conditions apply to a caller presenting no user attributes at all, it wouldn't actually keep anyone out who's willing to drop their credentials, so it can't stand in for an allow-list.
+
+Besides a policy array, `permission` also accepts:
+
+- `"allowAnonymous"` — explicitly documents that anonymous callers are allowed. Behaves the same as omitting `permission`, but records the decision so it isn't mistaken for an oversight.
+- Omitted (default) — unchanged: anonymous callers can still reach the resolver.
+
+This check is based on `context.user`, the original caller, so it still applies even when `authInvoker` swaps in a machine user for database access.
+
 ## Authentication
 
-Specify an `authInvoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
+Specify an `invoker` to execute the resolver with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names you defined in your auth config:
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";
@@ -365,10 +419,10 @@ export default createResolver({
     // Executes as "batch-processor" machine user
     return { result: "ok" };
   },
-  authInvoker: "batch-processor",
+  invoker: "batch-processor",
 });
 ```
 
 The machine user name is looked up in the auth service configured on your app (`machineUsers` in `defineAuth`). The namespace is resolved automatically — no need to import `auth` from `tailor.config.ts` in resolver files.
 
-**Note:** `authInvoker` controls the permissions for database operations and other platform actions. The `user` object passed to `body` still reflects the original caller, while `invoker` reflects the principal actually running the body.
+**Note:** The `invoker` option controls the permissions for database operations and other platform actions. The `caller` object passed to `body` still reflects the original caller, while the `invoker` body field reflects the principal actually running the body.

package/docs/services/secret.md

@@ -34,11 +34,11 @@ Secrets are key-value pairs stored within a vault. Secret values are encrypted a
 
 ## Managing Secrets
 
-There are two ways to manage secrets: declaratively via `defineSecretManager()` in `tailor.config.ts`, or imperatively via the [CLI](#cli-management). Management is scoped per vault — **do not mix both approaches for the same vault**. When a vault is defined in config, the config becomes the source of truth: any secrets in that vault not present in the config will be deleted on `tailor-sdk deploy`.
+There are two ways to manage secrets: declaratively via `defineSecretManager()` in `tailor.config.ts`, or imperatively via the [CLI](#cli-management). Management is scoped per vault — **do not mix both approaches for the same vault**. When a vault is defined in config, the config becomes the source of truth: any secrets in that vault not present in the config will be deleted on `tailor deploy`.
 
 ### Declarative Configuration
 
-Define your secrets in `tailor.config.ts` using `defineSecretManager()`. Each key is a vault name, and its value is a record of secret names to their values. These values are deployed to each vault on `tailor-sdk deploy`.
+Define your secrets in `tailor.config.ts` using `defineSecretManager()`. Each key is a vault name, and its value is a record of secret names to their values. These values are deployed to each vault on `tailor deploy`.
 
 Since secret values should not be committed to source control, use environment variables:
 
@@ -87,7 +87,7 @@ When `ignoreNullishValues: true`:
 - Skipped secrets are shown in the deploy output for visibility
 - Secrets removed from the config entirely are still deleted (orphan cleanup)
 
-This allows you to set secret values once (e.g., via local `tailor-sdk deploy` or the CLI) and then deploy from CI without needing the actual values in CI environment variables.
+This allows you to set secret values once (e.g., via local `tailor deploy` or the CLI) and then deploy from CI without needing the actual values in CI environment variables.
 
 ## Using Secrets
 
@@ -175,25 +175,25 @@ At runtime, these references are replaced with the actual secret values.
 
 Use the CLI to manage vaults that are **not** defined in `defineSecretManager()`. If you attempt to modify a vault that is managed by the config, the CLI will show a warning and ask for confirmation. Once confirmed, the CLI releases the vault's ownership label so it is no longer managed by config.
 
-After ownership is released, the next `tailor-sdk deploy` will treat the vault as an unmanaged resource and prompt for confirmation before taking any action on it.
+After ownership is released, the next `tailor deploy` will treat the vault as an unmanaged resource and prompt for confirmation before taking any action on it.
 
 ### Create a Vault
 
 ```bash
-tailor-sdk secret vault create --name api-keys
+tailor secret vault create --name api-keys
 ```
 
 ### Add Secrets
 
 ```bash
 # Create a secret
-tailor-sdk secret create \
+tailor secret create \
   --vault-name api-keys \
   --name stripe-secret-key \
   --value sk_live_xxxxx
 
 # Update a secret
-tailor-sdk secret update \
+tailor secret update \
   --vault-name api-keys \
   --name stripe-secret-key \
   --value sk_live_yyyyy
@@ -203,20 +203,20 @@ tailor-sdk secret update \
 
 ```bash
 # List vaults
-tailor-sdk secret vault list
+tailor secret vault list
 
 # List secrets in a vault (values are hidden)
-tailor-sdk secret list --vault-name api-keys
+tailor secret list --vault-name api-keys
 ```
 
 ### Delete Secrets
 
 ```bash
 # Delete a secret
-tailor-sdk secret delete --vault-name api-keys --name old-key --yes
+tailor secret delete --vault-name api-keys --name old-key --yes
 
 # Delete a vault (must be empty)
-tailor-sdk secret vault delete --name old-vault --yes
+tailor secret vault delete --name old-vault --yes
 ```
 
 See [Secret CLI Commands](../cli/secret.md) for full documentation.

package/docs/services/staticwebsite.md

@@ -72,7 +72,7 @@ defineStaticWebSite("my-website", {
 });
 ```
 
-After deploying, use `tailor-sdk staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.
+After deploying, use `tailor staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.
 
 A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment).
 
@@ -124,8 +124,14 @@ const website = defineStaticWebSite("my-frontend", {
 });
 
 const idp = defineIdp("my-idp", {
-  authorization: "loggedIn",
   clients: ["default-client"],
+  permission: {
+    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+  },
 });
 
 const auth = defineAuth("my-auth", {

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,20 @@ 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.
+
+### Breaking changes without a script
+
+Breaking changes require `migrate.ts`. If it is missing at deploy time (for example, the generated script was deleted), `tailor-sdk deploy` fails before applying the migration or anything after it. When there is genuinely nothing to migrate — say, the affected type holds no data yet — record an explicit acknowledgment instead of keeping an empty script:
+
+```bash
+tailor-sdk tailordb migration script 0002 --no-script --reason "no data yet, safe to skip"
+```
+
+This stores the reason in `migrations/0002/diff.json` (commit the change). The next `tailor-sdk deploy` applies the schema change as usual, skips only the script step, and logs the recorded reason. The command refuses to record a skip while `migrate.ts` exists — delete the script first. If `migrate.ts` is added back later, the script takes precedence over the acknowledgment and runs.
 
 ## Configuration
 
@@ -220,10 +230,13 @@ The `env` values are injected at bundle time (the same mechanism as resolvers/ex
 | Remove field                   | No        | Optional          | Warning tier — no script is auto-generated, but you can add one with `tailordb migration script` to preserve data before the field is dropped. The field stays readable from `migrate.ts` during Pre-migration and is dropped in Post-migration. |
 | Change optional → required     | Yes       | Yes               | Script sets defaults for null values                                                                                                                                                                                                             |
 | Change required → optional     | No        | No                | Schema change only                                                                                                                                                                                                                               |
-| Add index                      | No        | No                | Schema change only                                                                                                                                                                                                                               |
-| Remove index                   | No        | No                | Schema change only                                                                                                                                                                                                                               |
+| Add index (non-unique)         | No        | No                | Schema change only                                                                                                                                                                                                                               |
+| Add unique index               | Yes       | Yes               | Script must resolve duplicate value combinations across the index fields                                                                                                                                                                         |
+| Change unique index fields     | Yes       | Yes               | Treated like adding a new unique constraint over the new field set                                                                                                                                                                               |
+| Remove index                   | No        | No                | Schema change only (removing the unique constraint from an index is also non-breaking)                                                                                                                                                           |
 | Add unique constraint          | Yes       | Yes               | Script must resolve duplicate values                                                                                                                                                                                                             |
 | Remove unique constraint       | No        | No                | Schema change only                                                                                                                                                                                                                               |
+| Change decimal scale           | Yes       | Yes               | Auto-generated script re-saves existing rows under the new scale. Decreasing scale rounds values half-up and can lose precision. If the same change adds a unique constraint, duplicate handling runs after re-saving.                           |
 | Add enum value                 | No        | No                | Schema change only                                                                                                                                                                                                                               |
 | Remove enum value              | Yes       | Yes               | Script migrates records with removed values                                                                                                                                                                                                      |
 | Add type                       | No        | No                | Schema change only                                                                                                                                                                                                                               |
@@ -245,14 +258,14 @@ 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
 
 For each pending migration:
 
-1. **Pre-migration**: Type changes that would be breaking are applied in a relaxed form first. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the type so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). Non-breaking changes that are part of the same migration are also applied here.
-2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) but is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
+1. **Pre-migration**: Type changes that would be breaking are applied in a relaxed form first. Newly-required fields are added as optional; fields whose `optional → required` transition is breaking are temporarily kept optional. Fields that are being removed in this migration are temporarily kept on the type so that `migrate.ts` can still read them (for example, to `innerJoin` through a foreign key that is about to be dropped). Breaking type-level index changes are relaxed the same way: a newly-added unique index is withheld, and an index gaining a unique constraint (or a unique index changing its field set) keeps its previous definition, so `migrate.ts` can resolve duplicates first. Non-breaking changes that are part of the same migration are also applied here.
+2. **Script execution**: If `migrate.ts` exists on disk for this migration, it is bundled and sent to the platform via the script execution API and runs as the configured machine user inside a transaction. The script is hard-required for breaking changes (`diff.requiresMigrationScript`) — deploy fails if the file is missing, unless a `--no-script` acknowledgment was recorded (see [Breaking changes without a script](#breaking-changes-without-a-script)). It is also executed when present for warning-tier diffs — see [Warnings and optional migration scripts](#warnings-and-optional-migration-scripts).
 3. **Post-migration**: Required constraints are enforced; field and type deletions are applied (the columns/tables are physically dropped here); the `sdk-migration` label is bumped to this migration's number.
 
 This split is what allows existing rows to be backfilled before the database starts rejecting nulls, and what lets `migrate.ts` traverse foreign-key fields that the same migration removes.
@@ -275,10 +288,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 +312,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 +329,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 +340,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 +355,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 +363,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 +382,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 +411,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 +454,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,10 +486,10 @@ 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
 
 **Cause:** `diff.requiresMigrationScript` is true but `migrate.ts` is missing from the migration directory.
 
-**Resolution:** Either re-run `migration generate` (it skips already-generated diffs but will fill in a missing script), or restore the file from version control.
+**Resolution:** Restore the file from version control, or create it with `tailor-sdk tailordb migration script <N> --namespace <namespace>`. If the migration intentionally needs no data transformation, record that decision with `tailor-sdk tailordb migration script <N> --namespace <namespace> --no-script --reason "<why no data migration is needed>"` instead.