@tailor-platform/sdk 2.26.0 → 2.28.0

package/docs/cli/application.md

@@ -56,24 +56,30 @@ tailor deploy [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 SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                                 | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
-| `--create-workspace`                    | -     | Create a workspace when the account has none                                         | No       | -                    | -                                 |
-| `--workspace-name <WORKSPACE_NAME>`     | -     | Name for a workspace created during deploy                                           | No       | -                    | -                                 |
-| `--workspace-region <WORKSPACE_REGION>` | -     | Region for a workspace created during deploy                                         | No       | -                    | -                                 |
-| `--organization-id <ORGANIZATION_ID>`   | -     | Organization ID for a workspace created during deploy                                | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
-| `--folder-id <FOLDER_ID>`               | -     | Folder ID for a workspace created during deploy                                      | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
-| `--dry-run`                             | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
-| `--no-schema-check`                     | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
-| `--no-validate`                         | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
-| `--no-cache`                            | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
-| `--clean-cache`                         | -     | Clean the bundle cache before building                                               | 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 SDK config file. Use comma-separated paths to deploy multiple apps together.                                   | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                                         | `-y`  | Skip confirmation prompts                                                                                              | No       | `false`              | -                                 |
+| `--create-workspace`                            | -     | Create a workspace when the account has none                                                                           | No       | -                    | -                                 |
+| `--workspace-name <WORKSPACE_NAME>`             | -     | Name for a workspace created during deploy                                                                             | No       | -                    | -                                 |
+| `--workspace-region <WORKSPACE_REGION>`         | -     | Region for a workspace created during deploy                                                                           | No       | -                    | -                                 |
+| `--organization-id <ORGANIZATION_ID>`           | -     | Organization ID for a workspace created during deploy                                                                  | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`                       | -     | Folder ID for a workspace created during deploy                                                                        | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--dry-run`                                     | `-d`  | Run the command without making any changes                                                                             | No       | -                    | -                                 |
+| `--no-schema-check`                             | -     | Skip schema diff check against migration snapshots                                                                     | No       | -                    | -                                 |
+| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Skip steps of a partially applied multi-step migration that already succeeded (comma-separated namespace/step entries) | No       | -                    | -                                 |
+| `--no-validate`                                 | -     | Skip client-side validation against platform resource constraints                                                      | No       | -                    | -                                 |
+| `--no-cache`                                    | -     | Disable bundle caching for this run                                                                                    | No       | -                    | -                                 |
+| `--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"`,
@@ -88,11 +94,26 @@ 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
 ```
 
+After a successful apply, stdout is exactly one line: the JSON object. A dry-run writes its
+plan as one JSON object. Progress and diagnostics go to stderr, so the output can be captured
+as it is, for example
+`result=$(tailor deploy --json)`. A failed deploy exits non-zero and writes its error as
+JSON to stderr, leaving stdout empty. A deploy plugin that writes to stdout itself makes
+the output unparseable; plugins report through `ctx.logger` and run commands through `ctx.exec`.
+
 Dry-run and build-only deployments do not return deployed application information.
 If resources were applied but loading the JSON result fails, the command reports
 `DEPLOY_RESULT_LOAD_FAILED`; fix the error and run `tailor deploy` again.

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/function.md

@@ -129,6 +129,8 @@ $ tailor function logs <execution-id> --follow
 
 **Notes**
 
+Each execution includes `errorKind`, which tells you where a failure came from: `USER_RUNTIME` (your code threw while running, or exceeded its time, memory, or CPU limit), `USER_NON_RUNTIME` (your script failed while loading, before your function was called, such as when its top-level code threw), `PLATFORM` (a failure on the Platform side, or the Platform aborting the run because of its own deadline or cancellation), `NONE` (no error), or `UNSPECIFIED` (not recorded, or a kind this CLI version does not recognize). A workflow job waiting on another job also reports `USER_NON_RUNTIME` when that job fails or is canceled. `errorName` and `errorMessage` hold the error's name and message, or `null` when none was recorded. The list table omits `errorMessage`; use `--json` or the execution details to read it.
+
 Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running. The `logs` string joins their messages with newlines.
 
 Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. With `--json`, `--follow` waits for completion and then emits the final execution details once.

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

@@ -103,7 +103,7 @@ tailor workspace create [options]
 | Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
 | ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
 | `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (us-west, asia-northeast)                                                                                                    | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west)                                                                                                    | Yes      | -         | -                                 |
 | `--delete-protection`                 | `-d`  | Enable delete protection                                                                                                                      | No       | `false`   | -                                 |
 | `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                                                   | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
 | `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                                                         | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |
@@ -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

@@ -77,6 +77,28 @@ This is a bundle-time setting. Changing `TAILOR_APP_LOG_LEVEL` affects newly bun
 
 Only `logger.*` calls made through the SDK's `logger` wrapper (from `@tailor-platform/sdk/runtime` or its `@tailor-platform/sdk/runtime/logger` subpath), or written as `globalThis.tailor.logger.*`, are covered. Other equivalent forms — such as the bare `tailor.logger.*` global or `self.tailor.logger.*` — are not affected by `logLevel`.
 
+**Date Representation** (`defaultDateRepresentation`): Sets the value representation of `t.date()`, `t.datetime()`, and `t.time()` fields that omit `as`. With `"temporal"`, those fields carry `Temporal.PlainDate`, `Temporal.Instant`, and `Temporal.PlainTime` values instead of strings, so a project that uses Temporal everywhere does not have to repeat `as: "temporal"` on every field; with `"date"`, they carry `Date` values, as `as: "date"` gives them. A field's own `as` still wins, including `as: "string"`. Run `tailor generate` after changing the setting so `tailor.d.ts` updates the field types.
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  defaultDateRepresentation: "temporal",
+});
+```
+
+The default applies wherever the SDK parses or serializes `t` fields on your behalf: resolver input and output in deployed functions and in `tailor function run`, `.parse()` and `parseDateFields` inside any bundled function (resolvers, executors, workflow jobs, auth hooks, TailorDB hooks and validators, migration scripts), and the [`tailor-runtime` Vitest environment](./testing.md#loading-secrets-from-config) when `tailorRuntime({ config })` points at the config. It does not apply to `db.*` fields, or to `t` fields parsed outside those places, such as a plain Node.js script or a module that runs while `tailor.config.ts` itself is being loaded; there the fields keep string values. A migration script keeps the representation that was in effect when it was generated, recorded in its `diff.json`, so changing the setting later does not alter migrations a new workspace has yet to run. That record covers the values at run time only; the TypeScript types of `t` fields follow the current `tailor.d.ts` everywhere, so a `t` date field declared inside a migration script should set `as` explicitly to keep its type and its values aligned after the setting changes.
+
+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:
@@ -185,11 +207,11 @@ import { defineIdp } from "@tailor-platform/sdk";
 const idp = defineIdp("my-idp", {
   clients: ["my-client"],
   permission: {
-    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
   },
 });
 
@@ -310,7 +332,7 @@ When the SDK deploys application code or runs detected service code with `functi
 | Executor callbacks        | `body: ({ env }) => ...`, `url: ({ env }) => String(env.bar)`, `variables: ({ env }) => ({ enabled: env.baz })`, or similar callback args |
 | Workflow job body         | `body: (input, { env }) => ...`                                                                                                           |
 | Auth before-login hook    | `handler: async ({ env }) => ...`                                                                                                         |
-| TailorDB migration script | `main(trx, { env }: MigrationContext)`                                                                                                    |
+| TailorDB migration script | `main(trx, { env }: MigrationContext)`, or each step's `run(trx, { env })`                                                                |
 | `function run`            | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |
 
 ```typescript