@tailor-platform/sdk 2.36.0 → 2.38.0

package/docs/cli/application.md

@@ -60,29 +60,29 @@ tailor deploy [options]
 
 **Options**
 
-| Option                                          | Alias | Description                                                                                                            | Required | Default              | Env                               |
-| ----------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>`                 | `-w`  | Workspace ID                                                                                                           | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--profile <PROFILE>`                           | `-p`  | Workspace profile                                                                                                      | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
-| `--config <CONFIG>`                             | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together.                                   | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                                         | `-y`  | Skip confirmation prompts                                                                                              | No       | `false`              | -                                 |
-| `--create-workspace`                            | -     | Create a workspace when the account has none                                                                           | No       | -                    | -                                 |
-| `--workspace-name <WORKSPACE_NAME>`             | -     | Name for a workspace created during deploy                                                                             | No       | -                    | -                                 |
-| `--workspace-region <WORKSPACE_REGION>`         | -     | Region for a workspace created during deploy                                                                           | No       | -                    | -                                 |
-| `--organization-id <ORGANIZATION_ID>`           | -     | Organization ID for a workspace created during deploy                                                                  | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
-| `--folder-id <FOLDER_ID>`                       | -     | Folder ID for a workspace created during deploy                                                                        | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
-| `--dry-run`                                     | `-d`  | Run the command without making any changes                                                                             | No       | -                    | -                                 |
-| `--no-schema-check`                             | -     | Skip schema diff check against migration snapshots                                                                     | No       | -                    | -                                 |
-| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Skip steps of a partially applied multi-step migration that already succeeded (comma-separated namespace/step entries) | No       | -                    | -                                 |
-| `--no-validate`                                 | -     | Skip client-side validation against platform resource constraints                                                      | No       | -                    | -                                 |
-| `--no-cache`                                    | -     | Disable bundle caching for this run                                                                                    | No       | -                    | -                                 |
-| `--clean-cache`                                 | -     | Clean the bundle cache before building                                                                                 | No       | -                    | -                                 |
+| Option                                          | Alias | Description                                                                                                                     | Required | Default              | Env                               |
+| ----------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
+| `--workspace-id <WORKSPACE_ID>`                 | `-w`  | Workspace ID                                                                                                                    | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
+| `--profile <PROFILE>`                           | `-p`  | Workspace profile                                                                                                               | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
+| `--config <CONFIG>`                             | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together.                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`              |
+| `--yes`                                         | `-y`  | Skip confirmation prompts                                                                                                       | No       | `false`              | -                                 |
+| `--create-workspace`                            | -     | Create a workspace when the account has none                                                                                    | No       | -                    | -                                 |
+| `--workspace-name <WORKSPACE_NAME>`             | -     | Name for a workspace created during deploy                                                                                      | No       | -                    | -                                 |
+| `--workspace-region <WORKSPACE_REGION>`         | -     | Region for a workspace created during deploy                                                                                    | No       | -                    | -                                 |
+| `--organization-id <ORGANIZATION_ID>`           | -     | Organization ID for a workspace created during deploy                                                                           | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`                       | -     | Folder ID for a workspace created during deploy                                                                                 | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--dry-run`                                     | `-d`  | Run the command without making any changes                                                                                      | No       | -                    | -                                 |
+| `--no-schema-check`                             | -     | Skip schema diff check against migration snapshots (beta)                                                                       | No       | -                    | -                                 |
+| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Skip steps of a partially applied multi-step migration that already succeeded, as comma-separated namespace/step entries (beta) | No       | -                    | -                                 |
+| `--no-validate`                                 | -     | Skip client-side validation against platform resource constraints                                                               | No       | -                    | -                                 |
+| `--no-cache`                                    | -     | Disable bundle caching for this run                                                                                             | No       | -                    | -                                 |
+| `--clean-cache`                                 | -     | Clean the bundle cache before building                                                                                          | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-Every workspace belongs to an organization; when none is given or set as a default, interactive runs ask for one and non-interactive runs fail. Workspace creation uses the selected user's default organization and folder set by `user update` when neither location is given and TAILOR_PLATFORM_TOKEN is not set. Giving --organization-id or --folder-id replaces both defaults. Organization and folder IDs loaded by --env-file also replace the defaults; command-line options take precedence, and empty env-file values are ignored. With --create-workspace, an existing workspace must match the resolved name, region, organization, and folder to be reused.
+Every workspace belongs to an organization; when none is given or set as a default, interactive runs ask for one and non-interactive runs fail. Workspace creation uses the selected user's default organization and folder set by `user update` when neither location is given and TAILOR_PLATFORM_TOKEN is not set. Giving --organization-id or --folder-id replaces both defaults. TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file, also replace the defaults; command-line options take precedence, and an empty value of either variable is ignored. With --create-workspace, an existing workspace must match the resolved name, region, organization, and folder to be reused.
 
 **JSON result:**
 
@@ -154,7 +154,8 @@ tailor deploy \
 `--create-workspace` only creates when the account has no workspace. If the existing workspace
 matches the requested name, region, organization, and folder, `deploy` reuses it so the same command
 is safe to rerun. If multiple workspaces exist, the flag never creates another one or guesses which
-workspace to use. `--yes` skips deployment confirmation but does not authorize workspace creation.
+workspace to use. `--yes` accepts the deployment confirmations described under Confirmation below
+but does not authorize workspace creation.
 
 If a saved workspace has been deleted or is no longer accessible, interactive terminals return to
 workspace selection. Non-interactive environments stop with `WORKSPACE_CONTEXT_STALE` instead of
@@ -182,20 +183,24 @@ Names that identify a resource across the whole workspace, such as application,
 
 Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).
 
-**Migration Handling:**
+**Migration Handling (Beta):**
 
-When migrations are configured (`db.tailordb.migration` in config), the `deploy` command automatically:
+When migrations are configured (`db.<namespace>.migration` in config), the `deploy` command:
 
-1. Detects pending migration scripts that haven't been executed
-2. Applies schema changes in a safe order (pre-migration → script execution → post-migration)
-3. Runs the pending migration scripts
-4. Updates the migration checkpoint so the same migrations are not re-run
+1. Checks the migration files and the migration state of each namespace (see Schema Check below) three times: while planning, so `--dry-run` reports a failure too; before it applies anything for any config; and again when it applies each config's TailorDB changes. If the migration files, a checkpoint reset, or the tables to delete changed after planning, the deploy stops with `DEPLOY_PLAN_STALE`.
+2. Resets the checkpoints that the plan showed would be reset to `0000` after a re-baseline, clears an in-progress record that an earlier deploy left on a migration it had already committed, and deletes the tables that a committed migration removed but an earlier deploy did not delete.
+3. Applies the changes of namespaces without pending migrations, except deletions. This also takes their tables out of a maintenance mode that an interrupted deploy left.
+4. Puts every namespace with pending migrations into maintenance mode, unless `maintenanceMode` is `false`.
+5. Runs the pending migrations one namespace at a time, in alphabetical order of the namespace names, and in number order within a namespace. Each migration applies its pre-migration schema, runs its `migrate.ts`, applies its post-migration schema, advances the checkpoint, and then deletes the tables and GraphQL permissions it removed.
+6. With `--no-schema-check`, applies the local table definitions that the pending migrations do not include (see [Schema verification](../services/tailordb/migration.md#schema-verification)).
+7. Takes the tables out of maintenance mode, or with `maintenanceMode: "deploy"`, leaves that to the end of the deploy.
+8. Deletes the remaining tables and GraphQL permissions that are no longer in the config.
 
-See [Automatic Migration Execution](../services/tailordb/migration.md#automatic-migration-execution) for details on automatic migration execution.
+See [Automatic Migration Execution](../services/tailordb/migration.md#automatic-migration-execution) for details on automatic migration execution, and [Several configs in one deploy](../services/tailordb/migration.md#several-configs-in-one-deploy) for the state a failed migration leaves the other configs in.
 
 **Concurrent Deploys:**
 
-Deploys that target the same workspace and application from the same project directory are serialized while secrets and auth connections are updated: one deploy proceeds and the other waits for it to finish. A deploy that cannot proceed within 5 minutes fails with an error, which normally means another deploy is still running. If a previous deploy was interrupted, the next deploy recovers automatically within about a minute. Deploys to different workspaces or applications are not affected.
+Deploys that target the same workspace and application from the same project directory are serialized while secrets and auth connections are updated: one deploy proceeds and the other waits for it to finish. A deploy that cannot proceed within 5 minutes fails with an error, which normally means another deploy is still running. If a previous deploy was interrupted, the next deploy recovers automatically within about a minute. If the error persists, stop any `tailor deploy` still running from the project directory, then delete the lock directory that the error names and retry. Deploys to different workspaces or applications are not affected.
 
 **Schema Check:**
 
@@ -206,7 +211,7 @@ By default, `deploy` performs two verification steps:
 
 If remote schema drift is detected, the deploy will fail with an error showing the differences. This helps prevent applying migrations to an inconsistent state.
 
-Use `--no-schema-check` to skip both verifications (not recommended for production).
+Use `--no-schema-check` to skip both verifications (not recommended for production). It does not skip the check that the remote migration checkpoint is in the local migration history: when the deployed checkpoint is ahead of the local migration files or belongs to another migration history, the deploy stops before changing anything. Pull the latest migration files, or move the checkpoint on purpose with `tailor tailordb migration sync`, adding `--force` when the checkpoint belongs to another migration history or has a history label that cannot be read, then deploy again.
 
 **Plan Output:**
 
@@ -239,6 +244,22 @@ tailor deploy --dry-run > plan.txt
 
 In apply mode, the plan is printed to stderr so it does not interfere with piped output.
 
+**Confirmation:**
+
+After printing the plan, `deploy` asks for confirmation before applying when the plan includes any of the following:
+
+- TailorDB migration checkpoints that must be reset before deploying (Beta)
+- Applications recorded as depending on this deploy that are missing from it
+- Resources owned by another application, or tagged with a different application id
+- Existing resources that `tailor` does not manage yet
+- Deletion of TailorDB tables, static websites, AI gateways, OAuth2 clients (including a client type change), Auth connections, Secret Manager vaults, or Secret Manager secrets
+
+Declining cancels the deploy. When the plan includes none of these, `deploy` applies it without asking.
+
+`--yes` accepts these confirmations without asking. In a non-interactive environment or with `--json`, a deploy that needs one of them fails unless `--yes` is passed. `--dry-run` lists them as warnings without asking.
+
+When [`env`](../configuration.md#environment-variables) references the URL of a static website that the same deploy creates, `deploy` first applies static websites and the other resources that cannot reference that URL, then plans the rest again with the real URL and prints that plan as well. It asks again only about what the new plan adds; declining at that point leaves the resources applied first in place.
+
 **JSON Output:**
 
 Pass the global `--json` / `-j` flag to get machine-readable output.
@@ -280,10 +301,23 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 ```json
 {
   "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0, "forcedBySdkVersion": 0 },
-  "status": "applied"
+  "status": "applied",
+  "workspaceId": "ws_abc123",
+  "applications": [
+    {
+      "name": "my-app",
+      "configPath": "/path/to/my-app/tailor.config.ts",
+      "url": "https://my-app.example.com",
+      "domain": "my-app.example.com",
+      "aiGateways": [],
+      "staticWebsites": {}
+    }
+  ]
 }
 ```
 
+Some deploys also add `tailordbMaintenance` or `deployedHooks`, as described under **JSON result** above.
+
 ## remove
 
 Remove all resources managed by the application from the workspace.

package/docs/cli/executor.md

@@ -6,6 +6,8 @@ description: "List and inspect executors, view executor jobs, and trigger execut
 
 Commands for managing executors and executor jobs.
 
+In the human-readable output of `executor jobs --logs` and `executor trigger --logs`, `[PLATFORM]` marks log lines the Platform added. See [`function logs`](./function.md#function-logs) for the `source` that `--json` reports for each log entry.
+
 ## executor
 
 Manage executors

package/docs/cli/function.md

@@ -135,7 +135,9 @@ $ tailor function logs <execution-id> --follow
 
 Each execution includes `errorKind`, which tells you where a failure came from: `USER_RUNTIME` (your code threw while running, or exceeded its time, memory, or CPU limit), `USER_NON_RUNTIME` (your script failed while loading, before your function was called, such as when its top-level code threw), `PLATFORM` (a failure on the Platform side, or the Platform aborting the run because of its own deadline or cancellation), `NONE` (no error), or `UNSPECIFIED` (not recorded, or a kind this CLI version does not recognize). A workflow job waiting on another job also reports `USER_NON_RUNTIME` when that job fails or is canceled. `errorName` and `errorMessage` hold the error's name and message, or `null` when none was recorded. The list table omits `errorMessage`; use `--json` or the execution details to read it.
 
-Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running. The `logs` string joins their messages with newlines.
+Each execution also includes `hasPlatformLogs`, which is `true` when the Platform added log lines of its own to the execution. The flag is best-effort: `false` does not guarantee there are none, so read the `logEntries` of the execution details to be sure. The list table shows a `hasPlatformLogs` column, marking flagged executions with `yes`, only when at least one listed execution is flagged.
+
+Execution details include `logEntries`, the structured log lines (message, severity, timestamp, source) recorded while the function ran. They are available while the execution is still running. `source` is `USER` for your function's own output, `PLATFORM` for a line the Platform added, or `UNSPECIFIED` (not recorded, or a source this CLI version does not recognize); the human-readable output marks Platform lines with `[PLATFORM]`. The `logs` string joins their messages with newlines.
 
 Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. With `--json`, `--follow` waits for completion and then emits the final execution details once.
 

package/docs/cli/notification.md

@@ -0,0 +1,128 @@
+---
+description: "List, read and dismiss the platform notifications sent to you from the tailor CLI."
+---
+
+# Notification Commands
+
+Commands for reading the platform notifications addressed to you: alerts you must act on,
+incidents, maintenance notices and announcements. The inbox is per user, so these commands take a
+profile (for its login) but no workspace. Marking a notification read or dismissing it in the CLI
+also changes it in the Console, which shows the same inbox.
+
+When no subcommand is provided, defaults to `list`.
+
+## notification
+
+Read the platform notifications sent to you.
+
+**Usage**
+
+```
+tailor notification [command]
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Commands**
+
+| Command                                         | Description                              |
+| ----------------------------------------------- | ---------------------------------------- |
+| [`notification list`](#notification-list)       | List the notifications in your inbox.    |
+| [`notification read`](#notification-read)       | Show a notification and mark it as read. |
+| [`notification dismiss`](#notification-dismiss) | Remove a notification from your inbox.   |
+
+### notification dismiss
+
+Remove a notification from your inbox.
+
+**Usage**
+
+```
+tailor notification dismiss [options] <id>
+```
+
+**Arguments**
+
+| Argument | Description     | Required |
+| -------- | --------------- | -------- |
+| `id`     | Notification ID | Yes      |
+
+**Options**
+
+| Option                | Alias | Description       | Required | Default | Env                       |
+| --------------------- | ----- | ----------------- | -------- | ------- | ------------------------- |
+| `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+### notification list
+
+List the notifications in your inbox.
+
+**Usage**
+
+```
+tailor notification list [options]
+```
+
+**Options**
+
+| Option                                      | Alias | Description                                                     | Required | Default  | Env                       |
+| ------------------------------------------- | ----- | --------------------------------------------------------------- | -------- | -------- | ------------------------- |
+| `--order <ORDER>`                           | -     | Sort order (asc or desc)                                        | No       | `"desc"` | -                         |
+| `--limit <LIMIT>`                           | `-l`  | Maximum number of items to return (0: unlimited)                | No       | `50`     | -                         |
+| `--profile <PROFILE>`                       | `-p`  | Workspace profile                                               | No       | -        | `TAILOR_PLATFORM_PROFILE` |
+| `--category <CATEGORY>`                     | -     | Only this category (alert, incident, maintenance, announcement) | No       | -        | -                         |
+| `--severity <SEVERITY>`                     | -     | Only this severity or higher (info, warning, critical)          | No       | -        | -                         |
+| `--unread`                                  | -     | Only unread notifications                                       | No       | `false`  | -                         |
+| `--scope-workspace <SCOPE_WORKSPACE>`       | -     | Only notifications about this workspace ID                      | No       | -        | -                         |
+| `--scope-organization <SCOPE_ORGANIZATION>` | -     | Only notifications about this organization ID                   | No       | -        | -                         |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+### notification read
+
+Show a notification and mark it as read.
+
+**Usage**
+
+```
+tailor notification read [options] <id>
+```
+
+**Arguments**
+
+| Argument | Description                  | Required |
+| -------- | ---------------------------- | -------- |
+| `id`     | Notification ID (repeatable) | Yes      |
+
+**Options**
+
+| Option                | Alias | Description                                      | Required | Default | Env                       |
+| --------------------- | ----- | ------------------------------------------------ | -------- | ------- | ------------------------- |
+| `--no-mark-read`      | -     | Show the notification without marking it as read | No       | `false` | -                         |
+| `--profile <PROFILE>` | `-p`  | Workspace profile                                | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Output (default):**
+
+```
+┌──────────────────────────────────────┬──────────┬──────────────┬─────────────────────────────────┬─────────────┬────────────┐
+│ id                                   │ severity │ category     │ title                           │ arrivedAt   │ readAt     │
+├──────────────────────────────────────┼──────────┼──────────────┼─────────────────────────────────┼─────────────┼────────────┤
+│ 0d2c0f1e-5c2b-4e3a-9c1d-2f6a7b8c9d0e │ warning  │ maintenance  │ Scheduled maintenance on Nov 3  │ 2 hours ago │ unread     │
+│ 1d2c0f1e-5c2b-4e3a-9c1d-2f6a7b8c9d0e │ info     │ announcement │ Platform notifications are live │ 3 days ago  │ 2 days ago │
+└──────────────────────────────────────┴──────────┴──────────────┴─────────────────────────────────┴─────────────┴────────────┘
+```
+
+`tailor notification read <id>` prints the title, the metadata, the body as plain text (it is
+Markdown, shown as written) and the action links, then marks the notification read. Pass
+`--no-mark-read` to only display it. Several IDs can be given at once. If some of them are not
+found, the others are still shown and marked read, and the command then fails naming the missing
+IDs. With a read-only login, the notifications are shown but not marked read, and a warning says
+so.
+
+`tailor notification dismiss <id>` removes a notification from your inbox. This cannot be undone:
+`read` and `list` no longer show it. It needs a profile that is not read-only. Notifications you
+do not dismiss stay until the platform expires or revokes them.

package/docs/cli/tailordb.md

@@ -23,7 +23,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 | Command                                     | Description                                         |
 | ------------------------------------------- | --------------------------------------------------- |
 | [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables. |
-| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                  |
+| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations (beta).           |
 
 ### tailordb truncate
 
@@ -86,7 +86,7 @@ tailor tailordb truncate User Post --yes
 
 ### tailordb migration
 
-Manage TailorDB schema migrations.
+Manage TailorDB schema migrations (beta).
 
 Note: Migration scripts are automatically executed during `tailor deploy`. See [Automatic Migration Execution](../services/tailordb/migration.md#automatic-migration-execution) for details.
 
@@ -98,17 +98,16 @@ tailor tailordb migration <command>
 
 **Commands**
 
-| Command                                                           | Description                                                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
-| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
-| [`tailordb migration resolve`](#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                                                                                                                                                                                  |
-| [`tailordb migration script`](#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.                                                                                                                                                                      |
-| [`tailordb migration set`](#tailordb-migration-set)               | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                                                            |
-| [`tailordb migration status`](#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                                                      |
-| [`tailordb migration sync`](#tailordb-migration-sync)             | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                                                     |
-| [`tailordb migration test`](#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                                                                                                                                                                                       |
-| [`tailordb migration validate`](#tailordb-migration-validate)     | Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found. |
+| Command                                                           | Description                                                                                                                                                    |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                     |
+| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                  |
+| [`tailordb migration resolve`](#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                       |
+| [`tailordb migration script`](#tailordb-migration-script)         | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.           |
+| [`tailordb migration status`](#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                           |
+| [`tailordb migration sync`](#tailordb-migration-sync)             | Sync remote TailorDB schema and checkpoint to a local migration snapshot to recover from schema drift or a checkpoint outside the local history.               |
+| [`tailordb migration test`](#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                            |
+| [`tailordb migration validate`](#tailordb-migration-validate)     | Run the migration and schema-drift checks that 'deploy' runs before changing anything, without deploying, and exit with a non-zero code when issues are found. |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -190,13 +189,15 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Notes**
 
-Use this after a deploy failed partway through a migration whose `migrate.ts` exports `steps`, or after a deploy could not confirm whether the script of a migration ran (`MIGRATION_OUTCOME_UNKNOWN`). The migration stays in progress: when `maintenanceMode` is on in your config, the tables of its namespace stay in maintenance mode, and `sync` and `rebaseline` are refused, while `set` accepts only the number of the in-progress migration. A deploy stops before changing anything while a run it could not confirm is not settled.
+Use this after a deploy failed partway through a migration whose `migrate.ts` exports `steps`, or after a deploy could not confirm whether the script of a migration ran (`MIGRATION_OUTCOME_UNKNOWN`). The migration stays in progress: when `maintenanceMode` is on in your config, the tables of its namespace stay in maintenance mode, and the other migration commands that move the checkpoint are refused. A deploy stops before changing anything while a run it could not confirm is not settled.
 
 - `--rollback` sends the schema of the migration before the failed one. The next deploy runs the failed migration again, from its first step for a script that exports `steps`. Data changes the script already made are not undone.
 - `--complete` sends the schema of the failed migration itself and records it as completed, without running its `migrate.ts` again. Fix the data first (for example with `tailor query`), and make sure no record lacks a value for a field that becomes required.
 
 For a run that a deploy could not confirm, the command reads how the run ended and shows it before asking for confirmation: use `--complete` when it succeeded, and `--rollback` when it failed, was canceled, or did not start. It refuses while the run is still running, and warns when the option you chose does not fit how the run ended.
 
+`--rollback` also settles a migration that no deploy recorded as in progress, but whose pre-migration schema or maintenance mode a deploy left in place, for example because the deploy stopped before recording it. See "Settling a migration that stays in progress" in the TailorDB Migrations guide for when it runs.
+
 Both options remove the in-progress record, take the tables out of maintenance mode, and remove the temporary resources of the failed run, so `deploy` and the other migration commands work again. As with `tailordb migration sync`, the local migration history must reproduce the current table definitions. If sending the schema stops partway, run the command again.
 
 #### tailordb migration script
@@ -231,40 +232,6 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment, and `--with-test` adds only the tests that do not exist yet (writing `db.pglite.ts` if it is missing). `migrate.pglite.test.ts` is scaffolded only when `@electric-sql/pglite` is installed in the project.
 
-#### tailordb migration set
-
-Set migration checkpoint to a specific number.
-
-**Usage**
-
-```
-tailor tailordb migration set [options] <number>
-```
-
-**Arguments**
-
-| Argument | Description                               | Required |
-| -------- | ----------------------------------------- | -------- |
-| `number` | Migration number to set (e.g., 0001 or 1) | Yes      |
-
-**Options**
-
-| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
-| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                              |
-| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist) | No       | -                    | -                              |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Notes**
-
-The migration number must be a 4-digit value (e.g. `0001`) or a bare integer (e.g. `1`) within 0–9999, and must exist in the local migration history; `0` is always accepted as the baseline, provided the local history passes validation. A gapped history is rejected.
-
-Metadata lookup failures (authentication, permission, or network errors) are reported as errors; only a not-yet-deployed namespace is treated as having no checkpoint.
-
 #### tailordb migration status
 
 Show the current migration status for TailorDB namespaces, including applied and pending migrations.
@@ -292,7 +259,7 @@ Local migration files are checked for a valid layout (numbering and required fil
 
 #### tailordb migration sync
 
-Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).
+Sync remote TailorDB schema and checkpoint to a local migration snapshot to recover from schema drift or a checkpoint outside the local history.
 
 **Usage**
 
@@ -308,16 +275,21 @@ tailor tailordb migration sync [options] <number>
 
 **Options**
 
-| Option                          | Alias | Description                                                       | Required | Default              | Env                            |
-| ------------------------------- | ----- | ----------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                      | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                 | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                        | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                         | No       | `false`              | -                              |
-| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist) | No       | -                    | -                              |
+| Option                          | Alias | Description                                                                             | Required | Default              | Env                            |
+| ------------------------------- | ----- | --------------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                            | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                       | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                              | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--yes`                         | `-y`  | Skip confirmation prompts                                                               | No       | `false`              | -                              |
+| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                       | No       | -                    | -                              |
+| `--force`                       | -     | Proceed even when the namespace records a migration history ID other than the local one | No       | `false`              | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+The command refuses to run when the namespace records a migration history ID other than the local one, or one that cannot be read, unless the namespace has neither a checkpoint nor a history ID yet. `--force` overwrites the tables and that history ID with those of the local history, and still asks for confirmation unless `--yes` is given.
+
 #### tailordb migration test
 
 Test pending migrations with seed fixtures or cloned data in a temporary workspace.
@@ -343,19 +315,19 @@ tailor tailordb migration test [options]
 | `--folder-id <FOLDER_ID>`                     | -     | Folder to create the temporary workspace in (default: the source workspace's folder). Requires --organization-id when the source workspace is not in an organization. With --target-workspace-id, must match the target's folder | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
 | `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations                                                                                                                                                                    | No       | -                    | -                                 |
 | `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                                                                                                                                                                               | No       | -                    | -                                 |
-| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep)                                                                                                             | No       | -                    | -                                 |
+| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d (less than 50,000,000 days), so workspace prune --expired can delete it (requires --keep)                                                                                 | No       | -                    | -                                 |
 | `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                                                                                                                                       | No       | -                    | -                                 |
-| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                                                                                                                             | No       | -                    | -                                 |
+| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed, migration, and assertion script execution                                                                                                                                                                 | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Organization and folder IDs loaded by --env-file are used the same way as the options; command-line options take precedence, and empty env-file values are ignored.
+The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Command-line options take precedence over TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file, and an empty value of either variable is ignored.
 
 #### tailordb migration validate
 
-Validate the full migration history, unreviewed generated migration scripts, and schema drift (local tables vs. migration snapshot, remote schema vs. migration checkpoint) without deploying. This includes the migration and schema-drift checks used by 'deploy' and exits with a non-zero code when issues are found.
+Run the migration and schema-drift checks that 'deploy' runs before changing anything, without deploying, and exit with a non-zero code when issues are found.
 
 **Usage**
 
@@ -365,19 +337,24 @@ tailor tailordb migration validate [options]
 
 **Options**
 
-| Option                          | Alias | Description                                                                | Required | Default              | Env                            |
-| ------------------------------- | ----- | -------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                 | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--namespace <NAMESPACE>`       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified)      | No       | -                    | -                              |
-| `--strict`                      | -     | Also fail when a pending migration can drop data without an acknowledgment | No       | `false`              | -                              |
+| Option                                          | Alias | Description                                                                                                                                                 | Required | Default              | Env                            |
+| ----------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>`                 | `-w`  | Workspace ID                                                                                                                                                | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`                           | `-p`  | Workspace profile                                                                                                                                           | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`                             | `-c`  | Path to Tailor config file                                                                                                                                  | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--namespace <NAMESPACE>`                       | `-n`  | Target TailorDB namespace (validates all namespaces if not specified)                                                                                       | No       | -                    | -                              |
+| `--strict`                                      | -     | Also fail when a pending migration can drop data without an acknowledgment                                                                                  | No       | `false`              | -                              |
+| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Also check that 'deploy --migration-skip-steps' can skip these steps of a partially applied multi-step migration, as comma-separated namespace/step entries | No       | -                    | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+Migration scripts are checked across the full migration history, not only the pending migrations that `deploy` checks. Like `deploy`, the command bundles only the pending scripts and checks the machine user that runs them.
+
 **See also:** For migration concepts, configuration, workflow, and troubleshooting, see the [TailorDB Migrations guide](../services/tailordb/migration.md).
 
-### tailordb erd
+### tailordb erd (Beta)
 
 The `tailordb erd` commands (export, diff, serve, deploy) are provided by the `@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin. Install it next to the SDK and keep running `tailor tailordb erd <command>` as before:
 

package/docs/cli/workflow.md

@@ -6,6 +6,8 @@ description: "List and inspect workflows, start and wait for workflow runs, and
 
 Commands for managing workflows and workflow executions.
 
+In the human-readable output of `--logs` on `workflow start`, `workflow wait`, `workflow executions`, and `workflow resume`, `[PLATFORM]` marks log lines the Platform added. See [`function logs`](./function.md#function-logs) for the `source` that `--json` reports for each log entry.
+
 ## workflow
 
 Manage workflows and workflow executions.