@tailor-platform/sdk 2.36.0 → 2.38.0

package/docs/cli/workspace.md

@@ -104,18 +104,18 @@ tailor workspace create [options]
 
 **Options**
 
-| Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
-| ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
-| `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west, europe-west)                                                                                       | Yes      | -         | -                                 |
-| `--delete-protection`                 | `-d`  | Enable delete protection                                                                                                                      | No       | `false`   | -                                 |
-| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                                                   | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
-| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                                                         | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |
-| `--ttl <TTL>`                         | -     | Record on the workspace itself when it becomes prunable, such as 30m, 24h, or 7d. `workspace prune --expired` deletes it once that has passed | No       | -         | -                                 |
-| `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                                                        | No       | -         | -                                 |
-| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                                                              | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
-| `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                                                       | No       | -         | -                                 |
-| `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active.                                   | No       | `"write"` | -                                 |
+| Option                                | Alias | Description                                                                                                                                                               | Required | Default   | Env                               |
+| ------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
+| `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                                            | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west, europe-west)                                                                                                                   | Yes      | -         | -                                 |
+| `--delete-protection`                 | `-d`  | Enable delete protection                                                                                                                                                  | No       | `false`   | -                                 |
+| `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                                                                               | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                                                                                     | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--ttl <TTL>`                         | -     | Record on the workspace itself when it becomes prunable, such as 30m, 24h, or 7d (less than 50,000,000 days). `workspace prune --expired` deletes it once that has passed | No       | -         | -                                 |
+| `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                                                                                    | No       | -         | -                                 |
+| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                                                                                          | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
+| `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                                                                                   | No       | -         | -                                 |
+| `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active.                                                               | No       | `"write"` | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -123,7 +123,9 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 Every workspace belongs to an organization. Without --organization-id and --folder-id, on the command line or through TAILOR_PLATFORM_ORGANIZATION_ID / TAILOR_PLATFORM_FOLDER_ID, the workspace is created in the default organization and folder that the logged-in user set with `user update`, unless TAILOR_PLATFORM_TOKEN is set. When none of these gives an organization, the command fails. Giving either option replaces both defaults, and --folder-id requires --organization-id.
 
-TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID are also read from --env-file. Command-line options take precedence over the corresponding environment variables. Empty values in the env file are treated as not given.
+Command-line options take precedence over TAILOR_PLATFORM_ORGANIZATION_ID and TAILOR_PLATFORM_FOLDER_ID, including values loaded by --env-file. An empty value of either variable is treated as not given.
+
+When --ttl is given but the expiry cannot be confirmed, the command still prints the created workspace, then fails with WORKSPACE_TTL_WRITE_FAILED. With --json, the printed `ttl.state` is then `unconfirmed` instead of `written`, so a script can read the workspace ID and record the expiry again with `workspace ttl set`.
 
 ### workspace delete
 
@@ -300,11 +302,11 @@ tailor workspace ttl set [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`      |
-| `--ttl <TTL>`                   | -     | Time from now until the workspace becomes prunable, such as 30m, 24h, or 7d | Yes      | -       | -                              |
+| 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`      |
+| `--ttl <TTL>`                   | -     | Time from now until the workspace becomes prunable, such as 30m, 24h, or 7d (less than 50,000,000 days) | Yes      | -       | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli-reference.md

@@ -16,12 +16,12 @@ tailor <command> [options]
 
 <a id="global-options"></a>
 
-| Option                                      | Alias | Description                                         | Required | Default | Env                  |
-| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- | -------------------- |
-| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       | -                    |
-| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       | -                    |
-| `--verbose` / `--no-verbose`                | -     | Enable verbose logging                              | No       | `false` | -                    |
-| `--json` / `--no-json`                      | `-j`  | Output as JSON                                      | No       | `false` | `TAILOR_JSON_OUTPUT` |
+| Option                                      | Alias | Description                                                    | Required | Default | Env                  |
+| ------------------------------------------- | ----- | -------------------------------------------------------------- | -------- | ------- | -------------------- |
+| `--env-file <ENV_FILE>`                     | `-e`  | Path to an environment file, repeatable (error if not found)   | No       | -       | -                    |
+| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to an environment file, repeatable (ignored if not found) | No       | -       | -                    |
+| `--verbose` / `--no-verbose`                | -     | Enable verbose logging                                         | No       | `false` | -                    |
+| `--json` / `--no-json`                      | `-j`  | Output as JSON                                                 | No       | `false` | `TAILOR_JSON_OUTPUT` |
 
 ### Progress and Detailed Logs
 
@@ -52,7 +52,8 @@ flag always wins, so `--json=false` forces table output even when the variable i
 `true`, `True`, `TRUE`, `t`, `T`, and `1` enable JSON; `false`, `False`, `FALSE`, `f`, `F`, and `0`
 keep table output. Other values are rejected. JSON mode also disables interactive prompts, so set the
 variable per invocation or per job rather than exporting it from a shell profile; a command that
-needed a prompt names what selected JSON when it refuses.
+needed a prompt names what selected JSON when it refuses. In JSON mode, pass `--yes` to commands that
+ask for confirmation, and pass the options that a command would otherwise prompt for.
 
 When an AI coding agent such as Claude Code, Codex, Cursor, or Gemini CLI runs the CLI, every
 command defaults to JSON as if `TAILOR_JSON_OUTPUT=true` were set, and `--help` starts with a short
@@ -60,16 +61,17 @@ guide for the agent. The CLI recognizes an agent by the environment variables it
 commands it runs; a non-blank `AI_AGENT` also counts as one. An explicit `--json` or
 `TAILOR_JSON_OUTPUT` still wins, so `--json=false` or `TAILOR_JSON_OUTPUT=false` keeps table output
 under an agent, and setting `POLITTY_NO_AGENT` to any non-empty value, such as `1`, turns agent
-detection off. Set these variables in the environment itself: values loaded with `--env-file` do not
-change the default. CLI plugins keep table output under an agent unless they receive `--json` or
-`TAILOR_JSON_OUTPUT`, and their `--help` does not include the guide.
+detection off. Set `AI_AGENT` and `POLITTY_NO_AGENT` in the environment itself: values loaded with
+`--env-file` do not change agent detection. CLI plugins keep table output under an agent unless they
+receive `--json` or `TAILOR_JSON_OUTPUT`, and their `--help` does not include the guide.
 
 Errors, warnings, progress, and diagnostic messages are written to stderr. A command failure under
 `--json` or `TAILOR_JSON_OUTPUT` emits a JSON error envelope to stderr, including a failure while
 parsing arguments: an unknown option or subcommand, or an option value that fails validation, is
 reported as `INVALID_ARGUMENTS`. Failures you can act on — an invalid or missing option, a resource
 that does not exist, an invalid configuration, or an unmet precondition — carry a stable `error.code`
-such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`, or `MIGRATION_SCRIPT_REQUIRED`. Where a
+such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`, or `MIGRATION_SCRIPT_REQUIRED`
+([Migration Error Codes](#migration-error-codes-beta) lists the codes for migrations). Where a
 remediation exists, the envelope also includes
 `error.suggestion`, `error.help` (the `--help` invocation for the failing command), `error.next` (a
 runnable command), or `error.context`. `UNEXPECTED_ERROR` marks failures without a dedicated code,
@@ -102,6 +104,172 @@ Generation hook failures use `PLUGIN_GENERATION_FAILED`. The error includes the
 and each failing plugin's ID and error in `error.context.failures`; successful plugins are
 excluded from that list.
 
+#### Migration Error Codes (Beta)
+
+`tailor deploy` and the `tailor tailordb migration` commands report these codes when migration
+files, the migration state of a namespace, or a migration run stops them. Each entry says what
+happened; the next step, where one exists, is in `error.suggestion` and `error.next`. `tailor
+tailordb migration test` deploys the pending migrations to a test workspace, so it can also report
+the `tailor deploy` codes. See [TailorDB Migrations](./services/tailordb/migration.md) for the terms
+used here.
+
+Migration files, reported by `tailor deploy` and by the `tailor tailordb migration` commands that
+read them:
+
+- `MIGRATION_DIRECTORY_CONFLICT`: two or more namespaces use the same migrations directory.
+- `MIGRATION_FILES_INVALID`: a migrations directory has no `0000/schema.json`, a gap or a duplicate
+  in its numbering, or a migration without `diff.json`.
+- `MIGRATION_FILE_INVALID`: a `schema.json` or `diff.json` is not valid JSON or does not have the
+  expected structure.
+- `MIGRATION_FILE_VERSION_UNSUPPORTED`: a migration file uses a format version that this SDK version
+  does not support.
+
+`tailor deploy`, checked while planning, so `--dry-run` reports them too:
+
+- `MIGRATION_SCHEMA_CHECK_FAILED`: the local table definitions have changes that no migration file
+  records.
+- `MIGRATION_REMOTE_DRIFT`: the workspace's tables differ from the schema of the migration that its
+  checkpoint records.
+- `MIGRATION_CHECKPOINT_UNKNOWN`: the workspace's checkpoint is not in the local migration history:
+  it is past the latest local migration, or it belongs to another migration history.
+- `MIGRATION_SCRIPT_REQUIRED`: a pending migration requires a `migrate.ts`, and it has neither one
+  nor a recorded `--no-script` acknowledgment.
+- `MIGRATION_SCRIPT_SKIP_CONFLICT`: a pending migration has both a `migrate.ts` and a recorded
+  `--no-script` acknowledgment.
+- `MIGRATION_SCRIPT_REVIEW_REQUIRED`: a pending migration's `migrate.ts` still has a `TODO()` call
+  or review marker that the generated script left.
+- `MIGRATION_SCRIPT_INVALID`: a pending migration's `migrate.ts` cannot be parsed, or its exports or
+  `steps` are not valid.
+- `MIGRATION_SCRIPT_BUNDLE_FAILED`: a pending migration's `migrate.ts` could not be bundled.
+- `AUTH_CONFIG_REQUIRED`: a pending migration has a `migrate.ts`, but the config defines no auth to
+  run it.
+- `MACHINE_USER_REQUIRED`: a pending migration has a `migrate.ts`, but no machine user is selected
+  to run the scripts of its namespace.
+- `MACHINE_USER_NOT_FOUND`: the machine user selected to run a pending migration's `migrate.ts` is
+  not defined in auth.
+- `MIGRATION_OUTCOME_UNSETTLED`: an earlier deploy could not confirm whether a migration's script
+  ran, and the migration has not been settled since.
+- `MIGRATION_IN_PROGRESS_INVALID`: the migration recorded as in progress cannot be read, is not the
+  next pending migration, or no longer exports `steps` although some of its steps ran.
+- `MIGRATION_IN_PROGRESS_CONFLICT`: a namespace whose checkpoint the deploy would reset to `0000`
+  has a migration in progress.
+- `MIGRATION_SKIP_STEPS_FORMAT_INVALID`: a `--migration-skip-steps` entry is not in the form
+  `<namespace>/<step>`.
+- `MIGRATION_SKIP_STEPS_INVALID`: a `--migration-skip-steps` entry names a namespace that no
+  deployed config defines or that has no partially applied migration, or a step that is not in the
+  migration, that has no earlier run, or that did not succeed in the earlier run.
+- `MIGRATION_SKIP_STEPS_UNVERIFIED`: the step results of the earlier run could not be read, so the
+  steps passed to `--migration-skip-steps` could not be checked.
+
+`tailor deploy`, while applying:
+
+- `DEPLOY_PLAN_STALE`: the migration files, a checkpoint reset, or the tables to delete changed
+  after the deploy was planned. `tailor tailordb migration test` reports it when the migration
+  files changed after it planned its deploy.
+- `MIGRATION_HISTORY_INVALID`: the schema before a pending migration could not be rebuilt from the
+  migration files.
+- `MIGRATION_CHECKPOINT_CONFLICT`: a namespace's checkpoint or migration history changed while the
+  deploy ran, for example because another deploy moved it.
+- `MIGRATION_CHECKPOINT_UNVERIFIED`: the deploy could not read a namespace's checkpoint to confirm
+  that it had not changed.
+- `MIGRATION_FAILED`: a migration's script failed, and the deploy rolled the migration back to the
+  previous checkpoint.
+- `MIGRATION_ROLLED_BACK`: a migration whose `migrate.ts` exports `steps` and
+  `onFailure = "rollback"` failed, and the deploy rolled it back to the previous checkpoint.
+- `MIGRATION_PARTIALLY_APPLIED`: a migration stopped partway and stays in progress: a `steps`
+  migration failed after some of its steps may have been applied, or the deploy could not clear
+  the in-progress record of a failed migration, so its schema was not rolled back.
+- `MIGRATION_OUTCOME_UNKNOWN`: the deploy could not confirm whether a migration's script started or
+  finished, or whether an earlier run of the script is still running.
+- `MIGRATION_LOCAL_DEFINITIONS_FAILED`: with `--no-schema-check`, a local table definition that the
+  pending migrations do not include could not be applied after the migrations completed.
+- `MIGRATION_RESTORE_FAILED`: the settings of some tables, such as their maintenance mode, could not
+  be restored after the migrations. When a migration had already failed, the deploy reports that
+  failure instead and puts this error in its `error.context.restoration`.
+
+`tailor tailordb migration` commands:
+
+- `MIGRATION_CONFIG_NOT_FOUND`: no TailorDB namespace in the config has `migration` configured.
+- `MIGRATION_VALIDATION_FAILED`: `validate` found a problem in at least one namespace. Its result
+  lists the problems of each namespace, including the migration file and deploy checks above.
+- `MIGRATION_STATUS_FAILED`: `status` could not report at least one namespace, for example because
+  its migration files are invalid, its migration history differs from the workspace's, or its
+  checkpoint is past the latest local migration.
+- `MIGRATION_IN_PROGRESS`: `rebaseline`, `sync`, or `test` found a migration in progress in the
+  namespace: partially applied steps, a script run that is not settled, or an in-progress record
+  that cannot be read.
+- `MIGRATION_HISTORY_MISMATCH`: replaying the local migration files does not reproduce the current
+  local table definitions (`rebaseline`, `sync`, `resolve`).
+- `MIGRATION_BASELINE_NOT_FOUND`: the namespace has no `0000` migration to rebuild its schema from.
+- `MIGRATION_HISTORY_NOT_FOUND`: `rebaseline` found no migrations for the namespace.
+- `MIGRATION_NAMESPACE_NOT_DEPLOYED`: the namespace does not exist in the workspace (`sync`,
+  `resolve`).
+- `MIGRATION_NOT_FOUND`: the migration that `sync` was given, or that `resolve` would return the
+  namespace to, is not in the local migration files.
+- `MIGRATION_SYNC_HISTORY_MISMATCH`: the namespace records a different migration history ID, or one
+  that cannot be read, and `sync` was run without `--force`.
+- `MIGRATION_SYNC_CANCELLED`: the `sync` confirmation was declined.
+- `MIGRATION_RESOLVE_DIRECTION_REQUIRED`: `resolve` was given neither or both of `--rollback` and
+  `--complete`.
+- `MIGRATION_RESOLVE_NO_IN_PROGRESS`: `resolve` found nothing to settle: no migration is in
+  progress in the namespace, and with `--rollback`, no interrupted deploy left the pre-migration
+  schema of a migration either.
+- `MIGRATION_RESOLVE_RECORD_UNREADABLE`: the namespace's in-progress record cannot be read.
+- `MIGRATION_RESOLVE_RECORD_INVALID`: the migration recorded as in progress is not the one after
+  the checkpoint.
+- `MIGRATION_RESOLVE_HISTORY_MISMATCH`: the namespace records a different migration history ID from
+  the local migration files.
+- `MIGRATION_EXECUTION_ACTIVE`: the script run of the migration that `resolve` would settle is still
+  running.
+- `MIGRATION_RESOLVE_STATE_CHANGED`: the namespace's checkpoint, migration history, or in-progress
+  record changed while `resolve` was running.
+- `MIGRATION_RESOLVE_CANCELLED`: the `resolve` confirmation was declined.
+- `REBASELINE_CHECKPOINT_BEHIND`: the workspace's checkpoint is not the latest local migration.
+- `REBASELINE_REMOTE_HISTORY_INVALID`: the workspace's migration history ID cannot be read.
+- `REBASELINE_REMOTE_HISTORY_MISMATCH`: the workspace records a different migration history ID from
+  the local migration files.
+- `REBASELINE_REMOTE_SCHEMA_MISMATCH`: the workspace's tables do not match the latest migration.
+- `REBASELINE_STATE_CHANGED`: the workspace's migration history ID, the migration files, or the
+  local table or config files changed while `rebaseline` waited for confirmation.
+- `REBASELINE_CANCELLED`: the `rebaseline` confirmation was declined.
+- `REBASELINE_CHECKPOINT_UPDATE_FAILED`: the local migration history was replaced, but resetting
+  the workspace's checkpoint to `0000` failed.
+- `MIGRATION_TEST_OPTIONS_INVALID`: the options of `test` conflict, for example `--keep-ttl`
+  without `--keep`, or `--organization-id` or `--folder-id` does not match the target workspace.
+- `MIGRATION_TEST_TARGET_INVALID`: the target workspace is the source workspace.
+- `MIGRATION_TEST_REGION_MISMATCH`: with `--data clone`, the target workspace is in a different
+  region from the source.
+- `MIGRATION_TEST_ASSERT_NAMESPACE_REQUIRED`: `--assert` was given, the pending migrations span
+  several namespaces, and `--assert-namespace` was not given.
+- `MIGRATION_TEST_NO_PENDING_MIGRATIONS`: the source workspace has no pending migration, or the
+  `--assert-namespace` has none.
+- `MIGRATION_TEST_SOURCE_CHECKPOINT_MISSING`: a namespace has not been deployed to the source
+  workspace.
+- `MIGRATION_TEST_SOURCE_INVALID`: a source namespace's tables do not match its checkpoint, or,
+  without a checkpoint, do not match `0000`.
+- `MIGRATION_TEST_SOURCE_AHEAD`: a source namespace's checkpoint is past the latest local migration.
+- `MIGRATION_TEST_SOURCE_REPAIR_PENDING`: a source namespace's checkpoint is waiting for the reset
+  to `0000` that a deploy applies after a re-baseline.
+- `MIGRATION_TEST_SOURCE_CLEANUP_PENDING`: a source namespace still has tables that the migration
+  at its checkpoint removed.
+- `MIGRATION_TEST_SOURCE_CHANGED`: with `--data clone`, the source workspace changed between
+  preparing the test and cloning its data.
+- `MIGRATION_TEST_SNAPSHOT_NOT_FOUND`: the schema of the latest migration could not be rebuilt from
+  the migration files.
+- `MIGRATION_TEST_SNAPSHOT_INVALID`: the migration schemas to deploy to the target name a namespace
+  that is not in the config, or define the same table name in two namespaces.
+- `MIGRATION_TEST_CLONE_UNAVAILABLE`: data cloning is not enabled on the Platform.
+- `MIGRATION_TEST_CLONE_FAILED`: cloning the source data failed.
+- `MIGRATION_TEST_CLONE_TIMEOUT`: cloning the source data did not finish within `--clone-timeout`.
+- `MIGRATION_TEST_SEED_FAILED`: the seed script failed.
+- `MIGRATION_TEST_ASSERTION_FAILED`: the assertion script failed.
+- `MIGRATION_TEST_WORKSPACE_CLEANUP_FAILED`: the test passed, but deleting its temporary workspace
+  failed.
+
+Codes of `tailor tailordb migration generate` and `tailor tailordb migration script`, and other
+codes for options or arguments that cannot be used, such as a namespace or migration number that
+does not exist, are not listed; their messages name the cause.
+
 ### Verbose Output
 
 Use `--verbose` to include debug diagnostics and error stack traces. `DEBUG=true` or
@@ -173,6 +341,7 @@ Both `--env-file` and `--env-file-if-exists` can be specified multiple times and
 - Variables already set in the environment are **not** overwritten
 - Later files override earlier files
 - `--env-file` files are loaded first, then `--env-file-if-exists` files
+- Loaded values fill options backed by an environment variable, such as `--config` from `TAILOR_CONFIG_PATH`
 
 ```bash
 # Load .env (required) and .env.local (optional, if exists)
@@ -186,27 +355,28 @@ tailor deploy --env-file .env --env-file .env.production
 
 You can use environment variables to configure workspace and authentication:
 
-| Variable                                     | Description                                                                                           |
-| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                                  |
-| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                             |
-| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                         |
-| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                         |
-| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                                |
-| `TAILOR_CONFIG_PATH`                         | Path to Tailor config file                                                                            |
-| `TAILOR_DTS_PATH`                            | Output path for generated `tailor.d.ts` type definition file                                          |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                                  |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                              |
-| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function run`, `machineuser token`          |
-| `TAILOR_PLATFORM_URL`                        | Platform API base URL. Saved into profiles created with `profile create --platform-url`               |
-| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID`           | OAuth2 client ID for user login. Saved into profiles created with `profile create --oauth2-client-id` |
-| `TAILOR_PLATFORM_CONSOLE_URL`                | Console base URL. Saved into profiles created with `profile create --console-url`                     |
-| `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count     |
-| `TAILOR_APPLY_CONCURRENCY`                   | Max concurrent platform RPCs during `apply`/`deploy`. Defaults to 16                                  |
-| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                           |
-| `TAILOR_GITHUB_ACTIONS_ANNOTATIONS`          | GitHub Actions failure annotations: `on` (default) or `off`                                           |
-| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                      |
-| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                            |
+| Variable                                     | Description                                                                                                      |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                                             |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                                        |
+| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                                    |
+| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                                    |
+| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                                           |
+| `TAILOR_CONFIG_PATH`                         | Path to Tailor config file                                                                                       |
+| `TAILOR_DTS_PATH`                            | Output path for generated `tailor.d.ts` type definition file                                                     |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                                             |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                                         |
+| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function run`, `machineuser token`                     |
+| `TAILOR_PLATFORM_URL`                        | Platform API base URL. Saved into profiles created with `profile create --platform-url`                          |
+| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID`           | OAuth2 client ID for user login. Saved into profiles created with `profile create --oauth2-client-id`            |
+| `TAILOR_PLATFORM_CONSOLE_URL`                | Console base URL. Saved into profiles created with `profile create --console-url`                                |
+| `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count                |
+| `TAILOR_APPLY_CONCURRENCY`                   | Max concurrent platform RPCs during `apply`/`deploy`. Defaults to 16                                             |
+| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                                      |
+| `TAILOR_GITHUB_ACTIONS_ANNOTATIONS`          | GitHub Actions failure annotations: `on` (default) or `off`                                                      |
+| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                                 |
+| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                                       |
+| `TAILOR_NOTIFICATION_BANNER`                 | Unread WARNING/CRITICAL notifications listed after a command in an interactive terminal: `on` (default) or `off` |
 
 ### Authentication Token Priority
 
@@ -226,7 +396,7 @@ Workspace ID resolution follows this priority order:
 2. `TAILOR_PLATFORM_WORKSPACE_ID` environment variable
 3. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`
 
-## CLI Plugins
+## CLI Plugins (Beta)
 
 > [!WARNING]
 > CLI plugins are a **beta** feature. The dispatch behavior and the set of injected environment
@@ -270,9 +440,10 @@ Resolution rules:
 - **Global flags reach the plugin from either side.** `tailor --json tailordb erd export` and
   `tailor tailordb erd export --json` both forward `--json`, and likewise `--verbose` and the
   `--env-file` options. A flag typed before the plugin name is consumed by the host CLI first and
-  then forwarded, so when the same flag appears on both sides the later one wins. A flag the host
-  does not define — including one only some commands declare, such as `--profile` — still has to be
-  typed after the plugin's own subcommand. `--help` and `--version` are answered by the host CLI and
+  then forwarded, so when the same flag appears on both sides the later one wins; every
+  `--env-file` and `--env-file-if-exists` still loads. A flag the host does not define — including
+  one only some commands declare, such as `--profile` — still has to be typed after the plugin's own
+  subcommand. `--help` and `--version` are answered by the host CLI and
   never dispatch a plugin. Setting `TAILOR_JSON_OUTPUT=true` also works, which plugins inherit from
   the environment.
 
@@ -327,20 +498,19 @@ Commands for managing Tailor Platform applications (work with `tailor.config.ts`
 
 Commands for managing TailorDB tables, data, and schema migrations.
 
-| Command                                                                          | Description                                                                                                                                                                                                                                                                                                               |
-| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [tailordb](./cli/tailordb.md#tailordb)                                           | Manage TailorDB tables and data.                                                                                                                                                                                                                                                                                          |
-| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                         | Truncate (delete all records from) TailorDB tables.                                                                                                                                                                                                                                                                       |
-| [tailordb migration](./cli/tailordb.md#tailordb-migration)                       | Manage TailorDB schema migrations.                                                                                                                                                                                                                                                                                        |
-| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
-| [tailordb migration rebaseline](./cli/tailordb.md#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
-| [tailordb migration resolve](./cli/tailordb.md#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                                                                                                                                                                                  |
-| [tailordb migration script](./cli/tailordb.md#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](./cli/tailordb.md#tailordb-migration-set)               | Set migration checkpoint to a specific number.                                                                                                                                                                                                                                                                            |
-| [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                                                                                                                                                                                      |
-| [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)             | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                                                                                                                                                                                     |
-| [tailordb migration test](./cli/tailordb.md#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                                                                                                                                                                                       |
-| [tailordb migration validate](./cli/tailordb.md#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](./cli/tailordb.md#tailordb)                                           | Manage TailorDB tables and data.                                                                                                                               |
+| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                         | Truncate (delete all records from) TailorDB tables.                                                                                                            |
+| [tailordb migration](./cli/tailordb.md#tailordb-migration)                       | Manage TailorDB schema migrations (beta).                                                                                                                      |
+| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                     |
+| [tailordb migration rebaseline](./cli/tailordb.md#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                  |
+| [tailordb migration resolve](./cli/tailordb.md#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied, or whose run a deploy could not confirm.                                                       |
+| [tailordb migration script](./cli/tailordb.md#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](./cli/tailordb.md#tailordb-migration-status)         | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                           |
+| [tailordb migration sync](./cli/tailordb.md#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](./cli/tailordb.md#tailordb-migration-test)             | Test pending migrations with seed fixtures or cloned data in a temporary workspace.                                                                            |
+| [tailordb migration validate](./cli/tailordb.md#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. |
 
 ### [Data Commands](./cli/data.md)
 
@@ -531,6 +701,17 @@ Commands for managing crash reports.
 | [crashreport list](./cli/crashreport.md#crashreport-list) | List local crash report files.                 |
 | [crashreport send](./cli/crashreport.md#crashreport-send) | Submit a crash report to help improve the SDK. |
 
+### [Notification Commands](./cli/notification.md)
+
+Commands for reading platform notifications.
+
+| Command                                                            | Description                                  |
+| ------------------------------------------------------------------ | -------------------------------------------- |
+| [notification](./cli/notification.md#notification)                 | Read the platform notifications sent to you. |
+| [notification dismiss](./cli/notification.md#notification-dismiss) | Remove a notification from your inbox.       |
+| [notification list](./cli/notification.md#notification-list)       | List the notifications in your inbox.        |
+| [notification read](./cli/notification.md#notification-read)       | Show a notification and mark it as read.     |
+
 ### [Upgrade Commands](./cli/upgrade.md)
 
 Commands for upgrading SDK versions with automated code migration.

package/docs/configuration.md

@@ -118,7 +118,7 @@ The default applies wherever the SDK parses or serializes `t` fields on your beh
 
 The setting is per `tailor.config.ts`, but the field types are declared through `tailor.d.ts`, which TypeScript merges across every file in a program. If one `tsconfig.json` includes the `tailor.d.ts` of several applications, they must agree on `defaultDateRepresentation`. When they differ, `t.date()`, `t.datetime()`, and `t.time()` called without `as` fail to type-check in that program until the configs are aligned or each application gets its own `tsconfig.json`.
 
-**Maintenance Mode** (`maintenanceMode`): Whether `deploy` restricts the TailorDB namespaces it migrates while it applies pending migrations: `"migration"` (the default) restricts them until the migrations complete, `"deploy"` until the whole deploy completes, and `false` does not restrict them. See [Maintenance mode](./services/tailordb/migration.md#maintenance-mode) for what is restricted and what concurrent requests can observe without it.
+**Maintenance Mode** (`maintenanceMode`, Beta): Whether `deploy` restricts the TailorDB namespaces it migrates while it applies pending migrations: `"migration"` (the default) restricts them until the migrations complete, `"deploy"` until the whole deploy completes, and `false` does not restrict them. See [Maintenance mode](./services/tailordb/migration.md#maintenance-mode) for what is restricted and what concurrent requests can observe without it.
 
 ```typescript
 export default defineConfig({
@@ -516,7 +516,7 @@ export default defineConfig({
 });
 ```
 
-### Plugins
+### Plugins (Beta)
 
 Configure plugins using `definePlugins()`, exported as `export const plugins`.
 

package/docs/data-clone.md

@@ -70,6 +70,6 @@ tailor data operation get --from <source-workspace-id> --to <target-workspace-id
 
 With `--json`, `data clone` reports `status: "completed"` once the clone has finished, or `status: "started"` with `--no-wait`.
 
-## Rehearsing migrations with cloned data
+## Rehearsing migrations with cloned data (Beta)
 
 To test pending TailorDB migrations against a copy of real records, use `tailor tailordb migration test --data clone` instead of cloning by hand. It creates a temporary workspace, deploys the pre-migration schema, clones the records, and runs the pending migrations. That command copies TailorDB records only; see [Clone mode](./services/tailordb/migration.md#clone-mode).