@tailor-platform/sdk 2.27.0 → 2.28.0

package/docs/cli/application.md

@@ -75,6 +75,11 @@ tailor deploy [options]
 | `--clean-cache`                                 | -     | Clean the bundle cache before building                                                                                 | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+Workspace creation uses the selected user's default organization and folder set by `user update` when neither location is given and TAILOR_PLATFORM_TOKEN is not set. Giving --organization-id or --folder-id replaces both defaults. Organization and folder IDs loaded by --env-file also replace the defaults; command-line options take precedence, and empty env-file values are ignored. With --create-workspace, an existing workspace must match the resolved name, region, organization, and folder to be reused.
+
 **JSON result:**
 
 After a successful `tailor deploy --json`, stdout includes `status: "applied"`,
@@ -89,6 +94,14 @@ is registered or no resources changed.
 Plugins that return outputs add entries under `deployedHooks`. For example, the
 frontend plugin provides upload results in `deployedHooks[].outputs.frontends`.
 
+When the deploy applied TailorDB migrations with maintenance mode enabled, `tailordbMaintenance` has one entry per
+application whose migrations ran: its `application` name, `namespaces`, `maintenanceMs` (how
+long their tables were in maintenance mode, equal to the sum of `phases`), `phases` in milliseconds
+(`restrict`, `preMigration`, `jobSetup`, `waitingToStart`, `running`, `waitingOrRunning`,
+`jobCleanup`, `postMigration`, `remainingDeploy`, `restore`), and `migrations` with each script's `namespace`,
+`migrationNumber`, `startObserved`, `waitingToStartMs`, `runningMs`, and `waitingOrRunningMs`. See
+[Time spent in maintenance mode](../services/tailordb-migration.md#time-spent-in-maintenance-mode).
+
 ```sh
 tailor deploy --json > deploy-result.json
 jq '.applications[] | {name, url, staticWebsites, auth}' deploy-result.json

package/docs/cli/data.md

@@ -0,0 +1,105 @@
+# Data Commands
+
+Commands for managing application data across workspaces.
+
+## data
+
+Manage application data across workspaces.
+
+**Usage**
+
+```
+tailor data <command>
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Commands**
+
+| Command                             | Description                                                                                                      |
+| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| [`data clone`](#data-clone)         | Clone the data of an application (TailorDB namespaces registered in its subgraph) from one workspace to another. |
+| [`data operation`](#data-operation) | Inspect asynchronous application data operations.                                                                |
+
+### data clone
+
+Clone the data of an application (TailorDB namespaces registered in its subgraph) from one workspace to another.
+
+**Usage**
+
+```
+tailor data clone [options]
+```
+
+**Options**
+
+| Option                | Alias | Description                                                                                              | Required | Default              | Env                       |
+| --------------------- | ----- | -------------------------------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------- |
+| `--yes`               | `-y`  | Skip confirmation prompts                                                                                | No       | `false`              | -                         |
+| `--profile <PROFILE>` | `-p`  | Workspace profile                                                                                        | No       | -                    | `TAILOR_PLATFORM_PROFILE` |
+| `--from <FROM>`       | -     | Workspace ID to copy data from                                                                           | Yes      | -                    | -                         |
+| `--to <TO>`           | -     | Workspace ID to copy data to                                                                             | Yes      | -                    | -                         |
+| `--name <NAME>`       | `-n`  | Application name, the same in the source and the target workspace (default: the name in the config file) | No       | -                    | -                         |
+| `--config <CONFIG>`   | `-c`  | Path to Tailor config file                                                                               | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`      |
+| `--copy-files`        | -     | Also copy TailorDB file content                                                                          | No       | `false`              | -                         |
+| `--copy-idp-users`    | -     | Also copy IdP users, including their passwords                                                           | No       | `false`              | -                         |
+| `--no-wait`           | -     | Start the clone and exit without waiting for it to finish                                                | No       | `false`              | -                         |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+The platform rejects the clone with a failed precondition unless all of the following hold:
+
+- The source and target workspaces are in the same region.
+- The target workspace has the same namespaces as the source.
+- The TailorDB schema of the target matches the source, so deploy the same version to the target first.
+- The target is empty for every namespace and copy type in scope (TailorDB records, plus files and IdP users when `--copy-files` / `--copy-idp-users` are given).
+
+The command waits until the clone finishes. Pressing Ctrl+C or passing --no-wait does not stop the clone, which keeps running on the platform. Use `tailor data operation get --wait` with the operation ID printed at the start to keep waiting, or without --wait to check the status once.
+
+With --json, the result carries `status`: `completed` once the clone has finished, or `started` with --no-wait.
+
+### data operation
+
+Inspect asynchronous application data operations.
+
+**Usage**
+
+```
+tailor data operation <command>
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Commands**
+
+| Command                                     | Description                                                |
+| ------------------------------------------- | ---------------------------------------------------------- |
+| [`data operation get`](#data-operation-get) | Show the status of a data clone, or wait for it to finish. |
+
+#### data operation get
+
+Show the status of a data clone, or wait for it to finish.
+
+**Usage**
+
+```
+tailor data operation get [options]
+```
+
+**Options**
+
+| Option                          | Alias | Description                                 | Required | Default | Env                       |
+| ------------------------------- | ----- | ------------------------------------------- | -------- | ------- | ------------------------- |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                           | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+| `--from <FROM>`                 | -     | Workspace ID to copy data from              | Yes      | -       | -                         |
+| `--to <TO>`                     | -     | Workspace ID to copy data to                | Yes      | -       | -                         |
+| `--operation-id <OPERATION_ID>` | -     | Operation ID printed when the clone started | Yes      | -       | -                         |
+| `--wait`                        | -     | Wait until the clone completes or fails     | No       | `false` | -                         |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+Without --wait, the command prints the current status once and exits. With --wait, it waits until the clone completes or fails, and exits with an error if it fails. Pressing Ctrl+C stops waiting; the clone keeps running on the platform.

package/docs/cli/secret.md

@@ -154,9 +154,9 @@ tailor secret vault create [options] <name>
 
 **Arguments**
 
-| Argument | Description | Required |
-| -------- | ----------- | -------- |
-| `name`   | Vault name  | Yes      |
+| Argument                | Description | Required |
+| ----------------------- | ----------- | -------- |
+| `name`, `--name <NAME>` | Vault name  | Yes      |
 
 **Options**
 
@@ -179,9 +179,9 @@ tailor secret vault delete [options] <name>
 
 **Arguments**
 
-| Argument | Description | Required |
-| -------- | ----------- | -------- |
-| `name`   | Vault name  | Yes      |
+| Argument                | Description | Required |
+| ----------------------- | ----------- | -------- |
+| `name`, `--name <NAME>` | Vault name  | Yes      |
 
 **Options**
 

package/docs/cli/tailordb.md

@@ -33,9 +33,9 @@ tailor tailordb truncate [options] [tables]
 
 **Arguments**
 
-| Argument | Description             | Required |
-| -------- | ----------------------- | -------- |
-| `tables` | Table names to truncate | No       |
+| Argument                      | Description             | Required |
+| ----------------------------- | ----------------------- | -------- |
+| `tables`, `--tables <TABLES>` | Table names to truncate | No       |
 
 **Options**
 
@@ -290,24 +290,26 @@ 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       | -                    | -                              |
+| 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       | -                    | -                              |
+| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep) | No       | -                    | -                              |
+| `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                           | No       | -                    | -                              |
+| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                 | No       | -                    | -                              |
 
 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.
+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. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed.
 
 #### tailordb migration validate
 

package/docs/cli/user.md

@@ -28,7 +28,7 @@ _no options_
 
 | Option                            | Alias | Description                       | Required | Default | Env                                          |
 | --------------------------------- | ----- | --------------------------------- | -------- | ------- | -------------------------------------------- |
-| `--machine-user <MACHINE_USER>`   | -     | Login as a platform machine user. | Yes      | -       | -                                            |
+| `--machine-user`                  | -     | Login as a platform machine user. | Yes      | -       | -                                            |
 | `--client-id <CLIENT_ID>`         | -     | Client ID                         | Yes      | -       | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     |
 | `--client-secret <CLIENT_SECRET>` | -     | Client secret                     | No       | -       | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` |
 
@@ -121,12 +121,13 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                         | Description                    |
-| ------------------------------- | ------------------------------ |
-| [`user current`](#user-current) | Show current user.             |
-| [`user list`](#user-list)       | List all users.                |
-| [`user switch`](#user-switch)   | Set current user.              |
-| [`user pat`](#user-pat)         | Manage personal access tokens. |
+| Command                         | Description                                                                |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| [`user current`](#user-current) | Show current user.                                                         |
+| [`user list`](#user-list)       | List all users.                                                            |
+| [`user switch`](#user-switch)   | Set current user.                                                          |
+| [`user update`](#user-update)   | Set the current user's default organization and folder for new workspaces. |
+| [`user pat`](#user-pat)         | Manage personal access tokens.                                             |
 
 ### user current
 
@@ -302,6 +303,35 @@ tailor user switch [options] <user>
 | `--profile <PROFILE>` | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+### user update
+
+Set the current user's default organization and folder for new workspaces.
+
+**Usage**
+
+```
+tailor user update [options]
+```
+
+**Options**
+
+| Option                                                | Alias | Description                                                                                                      | Required | Default | Env                       |
+| ----------------------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------- |
+| `--default-organization-id <DEFAULT_ORGANIZATION_ID>` | `-o`  | Organization that `workspace create` uses when no location is given. Pass an empty string to clear the defaults. | No       | -       | -                         |
+| `--default-folder-id <DEFAULT_FOLDER_ID>`             | `-f`  | Folder in the default organization that `workspace create` uses (requires --default-organization-id)             | No       | -       | -                         |
+| `--profile <PROFILE>`                                 | `-p`  | Workspace profile                                                                                                | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+`workspace create`, workspace creation during `deploy`, and the programmatic `createWorkspace()` use the default folder, or directly use the default organization when no folder is set. Giving either an organization or a folder replaces both defaults for that run. For the CLI, use --organization-id or --folder-id, or TAILOR_PLATFORM_ORGANIZATION_ID / TAILOR_PLATFORM_FOLDER_ID. The defaults are not used while TAILOR_PLATFORM_TOKEN is set, because that token does not belong to a user logged in here.
+
+Each run replaces both defaults: --default-organization-id alone clears the default folder, --default-folder-id is accepted only together with --default-organization-id, and --default-organization-id "" clears both. The IDs are not checked against the Platform here; `workspace create` and `deploy` point back to them when the Platform cannot find them or denies access to them.
+
+The defaults belong to this user's login on the selected platform, so `logout` removes them, and older SDK versions drop them when they rewrite the CLI config file.
+
 When no subcommand is provided, defaults to `list`.
 
 **Output (default):**

package/docs/cli/workspace.md

@@ -115,6 +115,12 @@ tailor workspace create [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+**Notes**
+
+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. 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.
+
 ### workspace delete
 
 Delete a Tailor Platform workspace.
@@ -207,7 +213,9 @@ Use this to reclaim workspaces left behind by CI runs, preview deployments, or i
 
 With --expired the workspaces select themselves instead: each one is deleted only once the --ttl expiry it recorded at creation has passed, so callers need no --name or --older-than. A workspace that records no expiry is never deleted this way, and neither is one whose recorded expiry cannot be read. Because that expiry is recorded on the workspace rather than derived from its name, anything able to write the workspace's metadata can bring its deletion forward -- and writing a workspace's metadata is a lesser permission than deleting it. --expired therefore requires at least one location, and --name still applies on top.
 
-Every workspace lives in exactly one location, and the location options name them explicitly: --organization-root selects the workspaces directly under an organization and none inside its folders, --folder-id selects the workspaces in one folder, and --personal selects the workspaces belonging to no organization and no folder. Each option can be given more than once, they combine as a union, and none of them is read from the environment -- a sweep covers exactly the locations spelled out on the command line. Selecting --personal is a deliberate choice to accept, for every organization-less workspace visible to this login, the expiry that anyone able to write a workspace's metadata may have recorded. Without any location option, a --name / --older-than sweep considers every visible workspace.
+Every workspace lives in exactly one location, and the location options name them explicitly: --organization-root selects the workspaces directly under an organization and none inside its folders, --folder-id selects the workspaces in one folder, and --personal selects the workspaces belonging to no organization and no folder. Each option can be given more than once, they combine as a union, and none of them is read from the environment or from the default organization/folder set by `user update` -- a sweep covers exactly the locations spelled out on the command line. Selecting --personal is a deliberate choice to accept, for every organization-less workspace visible to this login, the expiry that anyone able to write a workspace's metadata may have recorded. Without any location option, a --name / --older-than sweep considers every visible workspace.
+
+Without a location option, prune warns before listing workspaces that every workspace visible to this login is a candidate for the name and age filters, even with --yes or --dry-run. The default organization/folder set by `tailor user update` is not used.
 
 Restoring a workspace does not clear its recorded expiry, so a workspace restored after expiring is deleted again by the next --expired run. Restore it, then run `workspace ttl set` or `workspace ttl clear` before the next run — or keep it out of that run with --exclude.
 

package/docs/cli-reference.md

@@ -50,6 +50,16 @@ keep table output. Other values are rejected. JSON mode also disables interactiv
 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.
 
+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
+guide for the agent. The CLI recognizes an agent by the environment variables it sets for the
+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.
+
 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
@@ -107,9 +117,9 @@ without reporting through the CLI's error path, such as one relaying a failed re
 writes no annotation.
 
 Set `TAILOR_GITHUB_ACTIONS_ANNOTATIONS=false` (also `off`, `no`, or `0`) to turn annotations off.
-Passing `--json` or setting `TAILOR_JSON_OUTPUT` also suppresses them, so a workflow step that parses
-JSON output gets only the error envelope on stderr, even when the command fails during argument
-parsing.
+Passing `--json`, setting `TAILOR_JSON_OUTPUT`, or the JSON default under an AI coding agent also
+suppresses them, so a workflow step that parses JSON output gets only the error envelope on stderr,
+even when the command fails during argument parsing.
 
 An annotation does not by itself fail a step: the step still fails on the CLI's exit code, which
 is unchanged. Workflows that already echo their own `::error::` around the CLI keep working;
@@ -314,6 +324,17 @@ Commands for managing TailorDB tables, data, and schema migrations.
 | [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. |
 
+### [Data Commands](./cli/data.md)
+
+Commands for managing application data across workspaces.
+
+| Command                                                | Description                                                                                                      |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| [data](./cli/data.md#data)                             | Manage application data across workspaces.                                                                       |
+| [data clone](./cli/data.md#data-clone)                 | Clone the data of an application (TailorDB namespaces registered in its subgraph) from one workspace to another. |
+| [data operation](./cli/data.md#data-operation)         | Inspect asynchronous application data operations.                                                                |
+| [data operation get](./cli/data.md#data-operation-get) | Show the status of a data clone, or wait for it to finish.                                                       |
+
 ### [Query Commands](./cli/query.md)
 
 Run ad-hoc SQL/GraphQL queries or enter the interactive REPL.
@@ -342,6 +363,7 @@ Commands for authentication and user management.
 | [user pat list](./cli/user.md#user-pat-list)     | List all personal access tokens.                                                      |
 | [user pat update](./cli/user.md#user-pat-update) | Update a personal access token (delete and recreate).                                 |
 | [user switch](./cli/user.md#user-switch)         | Set current user.                                                                     |
+| [user update](./cli/user.md#user-update)         | Set the current user's default organization and folder for new workspaces.            |
 
 ### [Organization Commands](./cli/organization.md)
 

package/docs/configuration.md

@@ -90,6 +90,15 @@ 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.
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  maintenanceMode: "migration",
+});
+```
+
 ### Service Configuration
 
 Specify glob patterns to load service files:

package/docs/github-actions.md

@@ -194,6 +194,26 @@ the `plan` job as well as `deploy`, because `plan` must enter the environment to
 read the variable. (A token-based read that lets `plan` run without entering the
 environment is planned.)
 
+## Package manager
+
+The generated workflow sets up your package manager, installs dependencies with
+it, and runs `tailor` through it. `setup ci` detects the package manager from the
+lockfile at the repository root (`pnpm-lock.yaml`, `yarn.lock`, `bun.lock`,
+`bun.lockb`, `package-lock.json`, or `npm-shrinkwrap.json`), or, when there is
+none, from the `packageManager` or `devEngines.packageManager` field of the root
+`package.json`. When neither names one, `setup ci` stops instead of guessing.
+
+Pass `--package-manager` (`pnpm`, `npm`, `yarn`, or `bun`) to choose it
+yourself, for example to generate the workflow before the lockfile exists:
+
+```bash
+tailor setup ci branch --name my-app-stg --package-manager pnpm
+```
+
+The workflow installs dependencies at the repository root, so commit the
+lockfile there before it runs. `tailor setup update` keeps a package manager
+chosen with `--package-manager` and detects it again otherwise.
+
 ## Generated files
 
 Running a workflow setup subcommand creates or updates:
@@ -553,6 +573,67 @@ plan job also enters the environment, allow `refs/pull/*/merge` as well so pull
 request plans keep running, and note that dry runs from other branches are then
 rejected too.
 
+## Seeding the workspace after deploy
+
+Pass `--seed` to `setup ci branch`, `setup ci tag`, or `setup ci preview` to seed
+the workspace with `tailor seed apply` right after each deploy. Add
+`--seed-dataset <name>` (repeatable, implies `--seed`) to apply
+[datasets](https://github.com/tailor-platform/sdk/tree/main/packages/sdk-plugin-seed#datasets)
+on top of the base seed data:
+
+```bash
+tailor setup ci branch --seed-dataset stg
+tailor setup ci preview --region us-west --seed-dataset preview
+```
+
+The deploy job gains a `tailor-seed` step after the deploy step. Branch targets
+validate seed data before deploy and also in the PR or dry-run plan job; tag
+targets validate it in the plan job before deploy. Both use
+`tailor seed validate --upsert` with the selected datasets to check the `id`
+and required fields that `seed apply --upsert` needs. Preview targets validate
+and apply the data after deploy.
+
+| Target      | Seeds with                           | Effect                                                                        |
+| ----------- | ------------------------------------ | ----------------------------------------------------------------------------- |
+| branch, tag | `tailor seed apply --upsert`         | The fields of each committed seed row are written; other rows are kept        |
+| preview     | `tailor seed apply --truncate --yes` | The preview workspace is emptied, IdP users included, and seeded from scratch |
+
+Setup stops unless the config uses `seedPlugin` with `machineUserName`, which
+names the machine user that seeds, and an existing `<distPath>/data/` directory.
+Every `--seed-dataset` must name an entry of
+the `seedPlugin` `datasets` option or a directory under `<distPath>/data/`.
+Commit the dataset directories the workflow seeds: a gitignored dataset such as
+a per-developer `local/` is not in the CI checkout.
+Install `@tailor-platform/sdk-plugin-seed` so the `tailor seed` commands resolve
+in CI. For branch and tag targets, use a version that supports
+`tailor seed validate --upsert`; update the setup and seed plugins together.
+Give every TailorDB seed row an `id` and
+every field its table requires: `--upsert` matches rows by id, so run
+`tailor seed fill` and commit the result.
+Seeding is available for a target that deploys one app.
+
+Before enabling it, note that:
+
+- Every branch or tag deploy writes the fields of the committed seed rows over
+  the workspace, `_User` rows and their passwords included, so an edit to one of
+  those fields in the workspace is undone. Each row is updated like any other update: update hooks
+  and validation run, `updatedAt` changes, and executors with
+  `recordUpdatedTrigger` fire once per seeded row on every deploy.
+- Every preview deploy deletes the data reviewers added to the preview
+  workspace. That is every push, and with `--require-preview-label` also every
+  label added to the pull request, since each one redeploys the preview.
+- A seed failure fails the deploy job and its notification, although the deploy
+  itself went through.
+- The step shares the deploy job's timeout. IdP users take about a second each.
+- Steps you added after the deploy step stay right after it, so they run before
+  `tailor-seed`. Move a step below `tailor-seed` when it needs the seeded data,
+  and move it again if you regenerate without `--seed` and then with it.
+- `tailor-seed` is an SDK-managed step. To seed another way (a different mode,
+  `--skip-idp`, a condition), leave `--seed` off and add your own step.
+
+Re-run `setup ci` with the flags each time you regenerate the workflow; `setup
+update` keeps them.
+
 ## Monorepo setup
 
 For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
@@ -673,8 +754,9 @@ a branch target deploys only its target branch, so use Option 1 there.
 - **Schema and data are not rolled back.** If the older config expects a schema
   state that no longer exists, the plan may show errors. In that case, review
   the diff carefully before proceeding.
-- **Seed data** is not part of the deployment pipeline and is unaffected by
-  rollbacks.
+- **Seed data** is not rolled back. Without `--seed`, the pipeline does not
+  touch it; with `--seed`, deploying an older commit seeds the rows committed
+  there on top of the current data.
 - **Static websites** are not yet integrated into the generated pipeline.
   Static asset rollbacks must be performed manually.
 
@@ -781,10 +863,11 @@ It regenerates every workflow recorded in
 have to re-type `setup ci branch`, `setup ci tag`, and the rest one by one.
 Your own jobs, steps, and settings are kept (see
 [Customizing the generated workflow](#customizing-the-generated-workflow)). A
-branch that was detected from the repository default branch is detected again,
-and the parts that follow your config — the migration drift check, seed
-validation, and ERD preview namespaces — are derived
-from the current `tailor.config.ts`.
+branch that was detected from the repository default branch and a
+[package manager](#package-manager) that was detected from the repository root
+are detected again, and the parts that follow your config — the migration drift
+check, seed validation, and ERD preview namespaces — are derived from the
+current `tailor.config.ts`.
 
 A target that cannot be regenerated, for example because you edited a managed
 part, does not stop the others: `update` regenerates the rest, then lists the

package/docs/multi-environment.md

@@ -96,3 +96,27 @@ defineStaticWebSite("my-website", {
   customDomains: process.env.APP_ENV === "production" ? ["app.example.com"] : undefined,
 });
 ```
+
+## Seed data per environment and per scenario
+
+`seedPlugin` seeds every environment from the JSONL files in `<distPath>/data/`. Rows that only some environments or scenarios need go into **datasets** — directories under `<distPath>/data/` that hold JSONL files for some of the tables — and are applied on top of the base seed data with `tailor seed apply --dataset <name>`:
+
+```
+seed/data/
+  *.schema.ts, *.jsonl     # base seed data, applied everywhere
+  cogs/Item.jsonl          # scenario: rows only a costing demo needs
+  dev/Account.jsonl        # environment: the dev variant of a table
+  stg/Account.jsonl        # environment: the staging variant of the same table
+  local/_User.jsonl        # per developer, gitignored
+```
+
+A table whose rows differ per environment lives only in the per-environment datasets, since a row may be defined in only one of the selected files. Name the combinations each environment uses in the `datasets` option of `seedPlugin`, so a deploy pipeline runs `tailor seed apply --dataset preview` instead of repeating the list:
+
+```typescript
+seedPlugin({
+  distPath: "./seed",
+  datasets: { preview: ["cogs", "dev"] },
+});
+```
+
+The `tailor seed` commands come from the `@tailor-platform/sdk-plugin-seed` CLI plugin; see its [Datasets](https://github.com/tailor-platform/sdk/tree/main/packages/sdk-plugin-seed#datasets) guide for validating, filling, and dumping datasets.

package/docs/services/idp.md

@@ -106,7 +106,7 @@ defineIdp("my-idp", {
 **Operators:** `"="`, `"!="`, `"in"`, `"not in"`
 
 > [!WARNING]
-> A policy of `[{ user: "_loggedIn" }, "=", true]` permits every authenticated user to run the operation against any IdP user. For `read` and `update` this exposes and lets them change other users' login information (such as email addresses), and for `sendPasswordResetEmail` it lets them send reset emails to anyone. Use it only when every user who can sign in to the project is trusted. For an IdP used by external users (such as business partners), restrict each operation to an administrator role as shown above.
+> A policy of `[{ user: "_loggedIn" }, "=", true]` permits every authenticated user to run the operation against any IdP user. For `read` and `update` this exposes and lets them change other users' login information (such as email addresses), and for `sendPasswordResetEmail` it lets them send reset emails to anyone. Use it only when every user who can sign in to the project is trusted. For an IdP used by external users (such as business partners), restrict each operation to an administrator role as shown above. `tailor deploy` warns about each rule whose only condition is `_loggedIn`.
 
 **Helper:** `unsafeAllowAllIdPPermission` grants full access without conditions. Intended only for development and testing.