@tailor-platform/sdk 2.1.0 → 2.3.0

package/docs/cli/setup.md

@@ -4,7 +4,7 @@ Commands for setting up project infrastructure.
 
 ## setup
 
-Generate CI deploy workflows for your project. (beta)
+Set up repository automation for your project. (beta)
 
 **Usage**
 
@@ -23,6 +23,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 | [`setup preview`](#setup-preview)       | Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).                |
 | [`setup action`](#setup-action)         | Generate a per-app composite action for use with setup coordinate (monorepo multi-app deploys).  |
 | [`setup coordinate`](#setup-coordinate) | Generate a coordinator workflow that orchestrates multiple --action-generated composite actions. |
+| [`setup renovate`](#setup-renovate)     | Generate a Renovate config for Tailor dependency and workflow updates.                           |
 | [`setup check`](#setup-check)           | Audit generated workflows for drift against the current config/repo (read-only).                 |
 | [`setup delete`](#setup-delete)         | Delete managed workflow/action file(s) and their .github/tailor.lock entries.                    |
 
@@ -159,6 +160,18 @@ tailor setup preview [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+### setup renovate
+
+Generate a Renovate config for Tailor dependency and workflow updates.
+
+**Usage**
+
+```
+tailor setup renovate
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
 ### setup tag
 
 Generate a tag-target deploy workflow (tag push triggers deploy).

package/docs/cli/tailordb.md

@@ -94,14 +94,16 @@ tailor tailordb migration <command>
 
 **Commands**
 
-| Command                                                       | Description                                                                                                                                                                                                                                                                            |
-| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`tailordb migration generate`](#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                                                                                                                                                              |
-| [`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 validate`](#tailordb-migration-validate) | Validate the full migration history and detect schema drift (local types 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 types and the previous migration snapshot.                                                                                                                                                                                                |
+| [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                            |
+| [`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 types 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. |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -117,15 +119,44 @@ tailor tailordb migration generate [options]
 
 **Options**
 
-| Option              | Alias | Description                                | Required | Default              | Env                  |
-| ------------------- | ----- | ------------------------------------------ | -------- | -------------------- | -------------------- |
-| `--yes`             | `-y`  | Skip confirmation prompts                  | No       | `false`              | -                    |
-| `--config <CONFIG>` | `-c`  | Path to Tailor config file                 | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--name <NAME>`     | `-n`  | Optional description for the migration     | No       | -                    | -                    |
-| `--init`            | -     | Delete existing migrations and start fresh | No       | `false`              | -                    |
+| Option                                | Alias | Description                                                                                                                                                                                  | Required | Default              | Env                  |
+| ------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
+| `--yes`                               | `-y`  | Skip confirmation prompts                                                                                                                                                                    | No       | `false`              | -                    |
+| `--config <CONFIG>`                   | `-c`  | Path to Tailor config file                                                                                                                                                                   | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
+| `--name <NAME>`                       | `-n`  | Optional description for the migration                                                                                                                                                       | No       | -                    | -                    |
+| `--init`                              | -     | Delete existing migrations and start fresh                                                                                                                                                   | No       | `false`              | -                    |
+| `--rename <RENAME>`                   | -     | Record a field or type rename instead of remove + add (format: "Type.oldField:newField" or "OldType:NewType"; repeatable). Renames require a migration script that copies the data.          | No       | -                    | -                    |
+| `--drop <DROP>`                       | -     | Confirm that a removed field or type is a genuine removal, not a rename (format: "Type.field" or "Type"; repeatable). Required in non-interactive runs for a removal with rename candidates. | No       | -                    | -                    |
+| `--expand-contract <EXPAND_CONTRACT>` | -     | Convert a field type through a temporary field (format: "Type.field"; repeatable). Generates two migrations.                                                                                 | No       | -                    | -                    |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+#### tailordb migration rebaseline
+
+Collapse the full migration history into a new 0000 baseline.
+
+**Usage**
+
+```
+tailor tailordb migration rebaseline [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`           |
+| `--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**
+
+Re-baselining removes migrations after 0000 from the working tree, records a new migration history ID, and resets the connected workspace checkpoint without changing its schema or data. Every environment must already have applied the latest migration before you run this command.
+
 #### 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.
@@ -144,15 +175,20 @@ tailor tailordb migration script [options] <number>
 
 **Options**
 
-| Option                    | Alias | Description                                                                                  | Required | Default              | Env                  |
-| ------------------------- | ----- | -------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                   | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                            | No       | -                    | -                    |
-| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason) | No       | -                    | -                    |
-| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                             | No       | -                    | -                    |
+| Option                    | Alias | Description                                                                                           | Required | Default              | Env                  |
+| ------------------------- | ----- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
+| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
+| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                                     | No       | -                    | -                    |
+| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason)          | No       | -                    | -                    |
+| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                                      | No       | -                    | -                    |
+| `--with-test`             | -     | Also add a migrate.test.ts unit-test scaffold; when migrate.ts already exists, only the test is added | No       | -                    | -                    |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment.
+
 #### tailordb migration set
 
 Set migration checkpoint to a specific number.
@@ -210,7 +246,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Notes**
 
-Metadata lookup failures (authentication, permission, or network errors) are reported per namespace and make the command exit non-zero; only a not-yet-deployed namespace is treated as having no applied migrations.
+Every local migration file is checked for a compatible format version, and deployed migration history IDs must match the local baseline. Compatibility errors, history mismatches, and metadata lookup failures are reported per namespace and make the command exit non-zero; only a not-yet-deployed namespace is treated as having no applied migrations.
 
 #### tailordb migration sync
 
@@ -240,9 +276,40 @@ tailor tailordb migration sync [options] <number>
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+#### tailordb migration test
+
+Test pending migrations with seed fixtures or cloned data in a temporary workspace.
+
+**Usage**
+
+```
+tailor tailordb migration test [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`           |
+| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten      | No       | `false`              | -                              |
+| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                     | No       | `"seed"`             | -                              |
+| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes) | No       | -                    | -                              |
+| `--keep`                                      | -     | Keep the automatically created workspace after the test                | No       | `false`              | -                              |
+| `--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       | -                    | -                              |
+| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed 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. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs.
+
 #### tailordb migration validate
 
-Validate the full migration history and detect schema drift (local types 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.
+Validate the full migration history, unreviewed generated migration scripts, and schema drift (local types 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.
 
 **Usage**
 
@@ -252,12 +319,13 @@ 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       | -                    | -                              |
+| 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`              | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli-reference.md

@@ -200,17 +200,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 types and the previous migration snapshot.                                                                                                                                                              |
-| [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 validate](./cli/tailordb.md#tailordb-migration-validate) | Validate the full migration history and detect schema drift (local types 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.                                                                                                                                                                                                                                                                                       |
+| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local types 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 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 types 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. |
 
 ### [Query Commands](./cli/query.md)
 
@@ -389,13 +391,14 @@ Commands for setting up project infrastructure.
 
 | Command                                             | Description                                                                                      |
 | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| [setup](./cli/setup.md#setup)                       | Generate CI deploy workflows for your project. (beta)                                            |
+| [setup](./cli/setup.md#setup)                       | Set up repository automation for your project. (beta)                                            |
 | [setup action](./cli/setup.md#setup-action)         | Generate a per-app composite action for use with setup coordinate (monorepo multi-app deploys).  |
 | [setup branch](./cli/setup.md#setup-branch)         | Generate a branch-target deploy workflow (push to branch triggers deploy).                       |
 | [setup check](./cli/setup.md#setup-check)           | Audit generated workflows for drift against the current config/repo (read-only).                 |
 | [setup coordinate](./cli/setup.md#setup-coordinate) | Generate a coordinator workflow that orchestrates multiple --action-generated composite actions. |
 | [setup delete](./cli/setup.md#setup-delete)         | Delete managed workflow/action file(s) and their .github/tailor.lock entries.                    |
 | [setup preview](./cli/setup.md#setup-preview)       | Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).                |
+| [setup renovate](./cli/setup.md#setup-renovate)     | Generate a Renovate config for Tailor dependency and workflow updates.                           |
 | [setup tag](./cli/setup.md#setup-tag)               | Generate a tag-target deploy workflow (tag push triggers deploy).                                |
 
 ### [Upgrade Commands](./cli/upgrade.md)

package/docs/configuration.md

@@ -129,7 +129,7 @@ When using external resources:
 - The resource itself is not deployed by this project
 - The resource must be deployed and available before referencing it
 - You can combine external resources with locally-defined resources
-- TailorDB type names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB type names before applying changes
+- TailorDB table names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB table names before applying changes
 - 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
 

package/docs/github-actions.md

@@ -1,7 +1,7 @@
 # GitHub Actions Integration
 
-`tailor setup` generates a GitHub Actions workflow that deploys your
-Tailor Platform application automatically on push or tag.
+`tailor setup` generates GitHub repository automation for your Tailor Platform
+application, including deploy workflows and Renovate configuration.
 
 > **Beta:** This command is under active development. CLI flags, the generated
 > workflow, and the `.github/tailor.lock` schema may change before general
@@ -14,16 +14,13 @@ lives):
 
 ```bash
 # Branch target: deploy to stg on every push to main
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 
 # Tag target: deploy to production when a tag is pushed, with an approval gate
-tailor setup -n my-app-prod \
-  --tag --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --branch main --environment production
 ```
 
-`setup` defaults to the GitHub provider; `--provider github` (`-p github`) is
-accepted but optional, and other providers are not yet supported.
-
 After running the command, follow the **Next steps** printed to the terminal to
 set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
 commit the generated files.
@@ -44,9 +41,9 @@ The branch target fires on pull requests and pushes to the branch you specify
 (defaulting to the repository's default branch when `--branch` is omitted):
 
 ```bash
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 # Equivalent to:
-tailor setup -n my-app-stg --branch main
+tailor setup branch --name my-app-stg --branch main
 ```
 
 What it does:
@@ -69,7 +66,7 @@ Pass `--erd-preview` on a branch target to add TailorDB ERD preview artifacts
 to pull requests:
 
 ```bash
-tailor setup -n my-app-stg --erd-preview
+tailor setup branch --name my-app-stg --erd-preview
 ```
 
 The generated workflow runs `tailor tailordb erd`, which is provided by the
@@ -90,11 +87,10 @@ ERD preview does not use Tailor Platform credentials. Fork pull requests still
 build artifacts, but the comment step is skipped because fork tokens cannot
 write PR comments.
 
-`--erd-preview` is only available for branch targets with the plan job enabled;
-it cannot be combined with `--tag` or `--no-plan`. The namespace list is
-recorded in `.github/tailor.lock`; the pull request workflow compares the
-head and base lock files so newly added or removed namespaces can still produce
-all-added or all-removed viewer artifacts. Re-run `setup` after adding or
+`--erd-preview` is only available for branch targets. The namespace list is
+recorded in `.github/tailor.lock`; the pull request workflow compares the head
+and base lock files so newly added or removed namespaces can still produce
+all-added or all-removed viewer artifacts. Re-run `setup branch` after adding or
 removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
 preview namespaces no longer match the current config.
 
@@ -104,8 +100,8 @@ The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
 pushed:
 
 ```bash
-tailor setup -n my-app-prod \
-  --tag --tag-pattern "v*" --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --tag-pattern "v*" --branch main --environment production
 ```
 
 What it does:
@@ -131,7 +127,7 @@ What it does:
 | Branch | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
 | Tag    | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |
 
-The workspace name (`--workspace-name`, or the config `name` when omitted) must
+The workspace name (`--name`, or the config `name` when omitted) must
 be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
 or end with a hyphen. It is used for the generated file name, the workflow
 `name:`, the plan label, and the default GitHub Environment name; it does not
@@ -174,7 +170,7 @@ environment is planned.)
 
 ## Generated files
 
-Running `setup` creates or updates:
+Running a workflow setup subcommand creates or updates:
 
 ### `.github/workflows/tailor-<workspace-name>.yml`
 
@@ -276,7 +272,7 @@ you can deploy any commit regardless of branch membership.
 For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
 
 ```bash
-tailor setup -n my-app --dir apps/backend
+tailor setup branch --name my-app --dir apps/backend
 ```
 
 The generated workflow adds a `paths` filter on `apps/backend/**` so the
@@ -341,11 +337,11 @@ A typical setup with staging and production:
 
 ```bash
 # Staging: main → stg (deploy on every push to main)
-tailor setup -n my-app-stg
+tailor setup branch --name my-app-stg
 
 # Production: tagged commits → prod, with approval gate and branch guard
-tailor setup -n my-app-prod \
-  --tag --branch main --environment production
+tailor setup tag --name my-app-prod \
+  --branch main --environment production
 ```
 
 Then provision each workspace and set its id on the matching environment (the
@@ -364,6 +360,41 @@ gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
 
 Commit both workflow files and `.github/tailor.lock`.
 
+## Keeping dependencies and actions updated
+
+Run this command once from the repository root to add Renovate configuration:
+
+```bash
+tailor setup renovate
+```
+
+It generates `renovate.json`, which extends Tailor's shared Renovate preset. The
+preset groups `@tailor-platform/*` package updates into one pull request and
+lets Renovate update the SHA-pinned GitHub Actions used by generated workflows.
+Enable Renovate for the repository by following the
+[Renovate onboarding guide](https://docs.renovatebot.com/getting-started/installing-onboarding/),
+then commit the generated file.
+
+If the repository already has Renovate configuration, the command adds
+`github>tailor-inc/renovate-config` to its `extends` array in place instead of
+writing a new file, leaving your other settings untouched. It checks Renovate's
+standard root, `.github`, `.gitlab`, and `.renovaterc` locations, including the
+deprecated `package.json` configuration. When that configuration already extends
+the preset, the command reports that Renovate is set up and changes nothing.
+
+Configuration written in JSON5 or JSONC — with comments or trailing commas —
+cannot be edited without losing those comments, so the command leaves it
+unchanged and asks you to add the preset to its `extends` array yourself.
+
+`renovate.json` is yours to edit — it is not tracked in `.github/tailor.lock`.
+Add your own rules freely; re-running `tailor setup renovate` does not overwrite
+them. To remove it, delete the file.
+
+Renovate updates the SDK dependency and action pins, but it does not regenerate
+the workflow template. After an SDK update, `tailor setup check --ci` reports a
+template-version warning until you re-run the relevant workflow setup
+subcommand.
+
 ## Checking for drift
 
 `tailor setup check` audits the workflows recorded in
@@ -374,12 +405,26 @@ newer template is available, `tailor.config.ts` is no longer under the recorded
 trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
 finding names a stable rule key for future suppression.
 
+Workflows generated by `setup branch`, `setup tag`, `setup preview`, and
+`setup coordinate` self-audit: each contains a `tailor-drift-check` step that
+runs the check in CI. Preview workflows run it alongside each preview deploy,
+so pull requests that deploy no preview (drafts, fork PRs, and unlabeled PRs
+in label-triggered mode) skip the check. A single run audits every target
+recorded in `.github/tailor.lock`, so per-app composite actions generated by
+`setup action` are covered by their coordinator's step and do not carry one of
+their own.
+
+Drift findings are advisory by default. Set the repository variable
+`TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
+the job. Execution and configuration errors fail regardless of this variable.
+
 ## Updating the generated workflow
 
-When you upgrade the SDK, re-run `setup` with the same flags to pick up
-template improvements. If the SDK detects that you have hand-edited a managed
-section, it stops and asks you to use `--force` to overwrite your edits, or to
-move your customizations into your own steps before regenerating.
+When you upgrade the SDK, re-run the relevant workflow setup subcommand with
+the same flags to pick up template improvements. If the SDK detects that you
+have hand-edited a managed section, it stops and asks you to use `--force` to
+overwrite your edits, or to move your customizations into your own steps before
+regenerating.
 
 The `.github/tailor.lock` file records the flags used at generation time,
 so you can check what arguments were used previously.

package/docs/migration/v2.md

@@ -8,6 +8,60 @@ Run the codemods, then finish anything reported as not migrated automatically:
 npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
 ```
 
+## Type-only imports → `import type`
+
+**Migration:** Manual
+
+The v2 CLI runs TypeScript by stripping types from each file in isolation,
+with no cross-file type information. A plain (non-`type`) import of a
+type-only export therefore survives stripping and fails when the module
+loads:
+
+```
+SyntaxError: The requested module './types.ts' does not provide an export named 'Row'
+```
+
+`tailor generate` / `tailor deploy` stop at this error before doing any work.
+Import types with `import type` (or the inline `type` modifier), and
+re-export them with `export type`, in every module the CLI loads. Generated
+Kysely types (`DB`, `Insertable`, `Selectable`, table row types) are almost
+entirely type-only, so v1 projects typically hit this in many files at once.
+Set `"verbatimModuleSyntax": true` in tsconfig.json to catch every violation
+at typecheck; projects scaffolded by v2 `tailor init` enable it by default.
+
+Before:
+
+```ts
+import { DB, getDB } from "./generated/db";
+```
+
+After:
+
+```ts
+import { type DB, getDB } from "./generated/db";
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+In Tailor SDK v2 the CLI loads TypeScript by stripping types from each file
+in isolation, so type-only exports do not exist at runtime and plain imports
+of them fail to load with "does not provide an export named '<name>'".
+Migrate the project so every type-only import and re-export is marked:
+
+1. Add `"verbatimModuleSyntax": true` to compilerOptions in tsconfig.json.
+2. Run `tsc --noEmit` and fix every reported violation: add the `type`
+   modifier to type-only named imports (`import type { Row }` or
+   `import { type Row, marker }`) and change type-only re-exports to
+   `export type { ... }`.
+
+Only add `type` modifiers; do not reorder, remove, or otherwise change
+imports that are used as values.
+```
+
+</details>
+
 ## defineGenerators → definePlugins
 
 **Migration:** Partially automatic
@@ -675,7 +729,7 @@ already pass a plain value unchanged.
 
 **Migration:** Partially automatic
 
-Rename the `defineIdp` option `publishUserEvents` to `publishEvents`, matching the field name TailorDB types, resolvers, and workflows already use.
+Rename the `defineIdp` option `publishUserEvents` to `publishEvents`, matching the field name that TailorDB tables, resolvers, and workflows already use.
 
 Before: