@tailor-platform/sdk 2.37.0 → 2.39.0

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
 
@@ -61,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,
@@ -103,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
@@ -174,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)
@@ -187,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
 
@@ -271,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.
 
@@ -328,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 (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 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 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)     | 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)
 
@@ -532,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

@@ -265,6 +265,34 @@ When using external resources:
 - Destructive operations like `tailordb truncate` (and `tailor seed apply --truncate`) automatically exclude external resources to prevent accidental data loss in shared resources
 - Subscribing an executor to an external resource's events requires the config that owns the resource in the same `deploy`. Publishing is then enabled automatically, and `deploy` records the dependency so a later deploy without that config asks for confirmation instead of silently turning publishing off
 
+#### Referencing another app's Auth with `asExternal()`
+
+When the other app is in the same repository, import its `defineAuth` result and call `asExternal()` instead of writing the name by hand.
+
+```typescript
+// core/auth.ts
+export const auth = defineAuth("core-auth", {
+  machineUsers: { portal: { attributes: { role: "STAFF" } } },
+  // ...
+});
+```
+
+```typescript
+// portal/tailor.config.ts
+import { auth as coreAuth } from "../core/auth";
+
+export default defineConfig({
+  name: "portal",
+  auth: coreAuth.asExternal(),
+});
+```
+
+- The reference follows renames of the Auth service and of its machine users.
+- The machine user names reach the generated `tailor.d.ts`, so a misspelled `invoker` is a type error in the referencing app, including when it is written as an expression such as `flag ? "portal" : "other"`.
+- Only the name and the machine users are taken over. Hooks, OAuth2 clients, and the rest of the definition stay with the app that owns the Auth service, so this project does not deploy them a second time.
+- Put the `defineAuth` call in its own file, as above. Importing the other app's `tailor.config.ts` also runs the rest of that file.
+- An Auth service defined in another repository cannot be imported. Reference it with `{ name: "...", external: true }`; `invoker` then accepts any string.
+
 ### Built-in IdP
 
 Configure the Built-in IdP service using `defineIdp()`. See [IdP](./services/idp.md) for full documentation.