@tailor-platform/sdk 2.27.0 → 2.29.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
@@ -161,6 +174,8 @@ tailor deploy --config apps/buyer/tailor.config.ts,apps/supplier/tailor.config.t
 
 When multiple configs are provided, `deploy` creates or updates all configured services first, then updates the applications. This lets one application reference resources owned by another config with `external: true` during the same deploy.
 
+Names that identify a resource across the whole workspace, such as application, executor, workflow, and static website names and service namespaces, must be unique across all configs in one deploy. Otherwise, `deploy` fails before planning any changes and lists every duplicate with the config files that define it.
+
 Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).
 
 **Migration Handling:**
@@ -240,10 +255,12 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
     }
   ],
   "warnings": [
-    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
-    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
+    { "type": "unmanaged", "resourceType": "staticwebsite", "name": "legacy-site" },
+    { "type": "skippedSecret", "resourceType": "secret.secret", "name": "my-vault/DB_PASSWORD" }
   ],
-  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
+  "conflicts": [
+    { "resourceType": "tailordb.service", "name": "tailordb", "currentOwner": "other-app" }
+  ]
 }
 ```
 
@@ -251,6 +268,7 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 - `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`. An update forced by the SDK version also has `forcedBySdkVersion: true`.
 - `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
 - `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
+- `resourceType` in `warnings` and `conflicts` is a stable identifier of the resource kind, such as `executor`, `tailordb.service`, or `secret.secret`. The human-readable plan shows a display name instead.
 
 **Apply** (`--json`): writes a JSON object to stdout:
 

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**
 
@@ -98,6 +98,7 @@ tailor tailordb migration <command>
 | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [`tailordb migration generate`](#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
 | [`tailordb migration rebaseline`](#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
+| [`tailordb migration resolve`](#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied.                                                                                                                                                                                                                                                           |
 | [`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.                                                                                                                                                                                                                      |
@@ -159,6 +160,39 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 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 resolve
+
+Settle a migration that a failed deploy left partially applied.
+
+**Usage**
+
+```
+tailor tailordb migration resolve [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`              | -                              |
+| `--rollback`                    | -     | Return the namespace to the schema before the in-progress migration    | No       | `false`              | -                              |
+| `--complete`                    | -     | Apply the schema of the in-progress migration and mark it as completed | 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**
+
+Use this after a deploy failed partway through a migration whose `migrate.ts` exports `steps`. The failed migration stays in progress: when `maintenanceMode` is on in your config, the tables of its namespace stay in maintenance mode, and `sync` and `rebaseline` are refused, while `set` accepts only the number of the in-progress migration.
+
+- `--rollback` sends the schema of the migration before the failed one. The next deploy runs the failed migration again from its first step. Data changes made by steps that already completed are not undone.
+- `--complete` sends the schema of the failed migration itself and records it as completed, without running its `migrate.ts` again. Fix the data first (for example with `tailor query`), and make sure no record lacks a value for a field that becomes required.
+
+Both options remove the in-progress record, take the tables out of maintenance mode, and remove the temporary resources of the failed run, so `deploy` and the other migration commands work again. As with `tailordb migration sync`, the local migration history must reproduce the current table definitions. If sending the schema stops partway, run the command again.
+
 #### tailordb migration script
 
 Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none.
@@ -290,24 +324,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
@@ -62,6 +72,16 @@ runnable command), or `error.context`. `UNEXPECTED_ERROR` marks failures without
 including SDK-internal errors. Diagnostic lines may precede the error envelope, and stdout is not
 guaranteed to contain an error object.
 
+The exit code separates a mistyped command from a failed one without parsing output: `0` on success,
+`2` when the CLI rejects the command line itself, such as an unknown option or subcommand, an
+unexpected argument, or an option value that fails validation (including one set through its
+environment variable), and `1` for other failures, including checks a command makes after reading
+its arguments. A command that only warns about an unknown option or an extra argument keeps
+running. Cancelling an interactive prompt exits with `130`, and a CLI plugin exits with its own
+code. A command group run without a subcommand, such as `tailor` or `tailor tailordb`, can exit
+with `0` after printing its help or a warning even when an option is unknown or its value is
+invalid, so name the subcommand to rely on `2`.
+
 Authentication failures distinguish missing credentials (`AUTH_TOKEN_NOT_FOUND`), a missing saved
 user (`AUTH_USER_NOT_FOUND`), an expired token (`AUTH_TOKEN_EXPIRED`), and a failed token refresh
 (`AUTH_TOKEN_REFRESH_FAILED`). Login recovery preserves the selected profile. For saved identities,
@@ -107,9 +127,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;
@@ -307,6 +327,7 @@ Commands for managing TailorDB tables, data, and schema migrations.
 | [tailordb migration](./cli/tailordb.md#tailordb-migration)                       | Manage TailorDB schema migrations.                                                                                                                                                                                                                                                                                        |
 | [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate)     | Generate migration files by detecting schema differences between current local tables and the previous migration snapshot.                                                                                                                                                                                                |
 | [tailordb migration rebaseline](./cli/tailordb.md#tailordb-migration-rebaseline) | Collapse the full migration history into a new 0000 baseline.                                                                                                                                                                                                                                                             |
+| [tailordb migration resolve](./cli/tailordb.md#tailordb-migration-resolve)       | Settle a migration that a failed deploy left partially applied.                                                                                                                                                                                                                                                           |
 | [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.                                                                                                                                                                                                                      |
@@ -314,6 +335,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 +374,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

@@ -60,7 +60,20 @@ export default defineConfig({
 
 Entries are only added or overwritten. An entry removed from the config keeps its last deployed value on the platform, and labels the config does not name are left untouched. Because those retained labels count towards the platform's limit of 20 labels per resource, `deploy` reports the overflow and stops before changing the application when the labels it would leave behind exceed that limit. The labels are written when the application itself is deployed, so a config with no TailorDB, Resolver, IdP, or Auth service has no application to carry them.
 
-**Build Options**: `buildOptions` groups the settings that control how resolvers, executors, workflow jobs, and other functions are bundled: `logLevel` (below), `inlineSourcemap` (whether bundled functions embed an inline sourcemap for readable error stack traces; default `true`), and `allowedRuntimeGlobals` (see [Node-only globals](#node-only-globals)). The top-level `logLevel` and `inlineSourcemap` fields still work but are deprecated; `tailor upgrade` moves them into `buildOptions`. Setting the same option both at the top level and in `buildOptions` is rejected.
+**Build Options**: `buildOptions` groups the settings that control how resolvers, executors, workflow jobs, and other functions are bundled: `logLevel` (below), `inlineSourcemap` (whether bundled functions embed an inline sourcemap for readable error stack traces; default `true`), `inlineSourcemapDependencySources` (below), `allowedRuntimeGlobals` (see [Node-only globals](#node-only-globals)), and `treeshake` (see [Removing unused code](#removing-unused-code)). The top-level `logLevel` and `inlineSourcemap` fields still work but are deprecated; `tailor upgrade` moves them into `buildOptions`. Setting the same option both at the top level and in `buildOptions` is rejected.
+
+**Sourcemap Sources** (`buildOptions.inlineSourcemapDependencySources`): Whether the inline sourcemap embeds the source text of installed packages, that is, everything under `node_modules`. The default is `false`: only your own source files are embedded, which makes bundled functions much smaller. Error positions in stack traces resolve to the original files and lines either way. With the default, `tailor function run` and `tailor function logs` show the code snippet for a frame inside an installed package from the package's file on your machine, so the snippet is missing when that file is not installed locally (for `tailor function logs`, run it from the project directory you deployed from). Set it to `true` to embed the source text of installed packages as well, or to a list of package names such as `["kysely", "@scope/lib"]` to embed only those packages. A listed package's own dependencies are not embedded unless they are listed too. It has no effect when `inlineSourcemap` is `false`.
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    inlineSourcemapDependencySources: true,
+  },
+});
+```
+
+This is a bundle-time setting. It affects newly bundled deployments; already deployed functions keep the sourcemap they were deployed with until they are redeployed.
 
 **Log Level** (`buildOptions.logLevel`): Controls which `console.*` and `logger.*` (from `@tailor-platform/sdk/runtime`) calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all calls. `console.log` is treated as a DEBUG-level call (matching the platform's OpenTelemetry severity mapping), so it is dropped at `"INFO"` and above, alongside `console.debug` and `logger.debug`. `logger.setAttributes` has no severity and is never dropped, regardless of `logLevel`. For production deployments, use `"WARN"` to keep warn/error calls while dropping debug, log, and info calls:
 
@@ -90,6 +103,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:
@@ -159,6 +181,44 @@ export default defineConfig({
 
 `buildOptions.allowedRuntimeGlobals` has no effect on your own code. Packages from your own workspace (for example, a pnpm or npm workspace) are bundled from their source directory rather than from `node_modules`, so they count as your own code.
 
+#### Removing unused code
+
+Bundling leaves out code a function never reaches. By default, reading a property such as `shared.db.company` counts as something that may have an effect, so a call like `createService({ db: { company: shared.db.company } })` stays in the bundle even when nothing uses its result, together with every module it imports. When a bundle is larger than expected because of modules the function does not use, set `buildOptions.treeshake.propertyReadSideEffects` to `false`:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    treeshake: { propertyReadSideEffects: false },
+  },
+});
+```
+
+With `false`, a property read whose result is unused is removed, and so is a call that only exists to receive such a read. This also removes a read that exists only for its effect: a getter that initializes something when it is read, or a statement such as `settings.db.url;` that throws when `settings.db` is missing. Keep the default if your code or an installed package relies on a read like that.
+
+`treeshake` has four switches that control how unused code is removed from bundles. The values below are the SDK's defaults, which are tuned for the Tailor Platform runtime and rarely need changing. Most switches ask whether something has side effects, so `true` keeps it, while `annotations` asks whether to honor annotations, so `true` removes more:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    treeshake: {
+      // true: keep an imported module even when none of its exports is used, so code
+      // that runs on import (such as registering something on `globalThis`) stays.
+      moduleSideEffects: false,
+      // true: honor `@__PURE__` and `@__NO_SIDE_EFFECTS__` comment annotations.
+      annotations: true,
+      // true: keep a read of a global the bundle does not define even when its result is unused.
+      unknownGlobalSideEffects: false,
+      // true: keep a property read (`shared.db.company`) even when its result is unused.
+      propertyReadSideEffects: true,
+    },
+  },
+});
+```
+
+The settings apply to resolvers, executors, workflow jobs, auth hooks, HTTP adapters, and `tailor function run`; other bundles are not affected. They are bundle-time settings, so already deployed functions must be redeployed to pick up a change.
+
 ### External Resources
 
 You can reference resources managed by Terraform or other SDK projects to include them in your application's subgraph. External resources are not deployed by this project but can be used for shared access across multiple applications.
@@ -445,8 +505,8 @@ Configure plugins using `definePlugins()`, exported as `export const plugins`.
 
 ```typescript
 import { definePlugins } from "@tailor-platform/sdk";
-import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
 import { enumConstantsPlugin } from "@tailor-platform/sdk/plugin/enum-constants";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
 
 export const plugins = definePlugins(
   kyselyTypePlugin({ distPath: "./generated/tailordb.ts" }),