@tailor-platform/sdk 2.14.2 → 2.16.0

package/docs/cli/application.md

@@ -118,7 +118,7 @@ create one explicitly before requesting a deployment plan.
 
 **Config File Modification:**
 
-On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.
+On the first local run, `deploy` assigns your application a stable id (a UUID) so the SDK can recognize ownership across renames. Projects that use `tailor setup` get it recorded in `.github/tailor.lock` under `appIds`; other projects get an `id: "<uuid>"` field written into the `defineConfig({...})` call in `tailor.config.ts`. Commit the file that received the id. See [Configuration](../configuration.md#application-settings) for details.
 
 **Multiple Config Deploys:**
 

package/docs/cli/function.md

@@ -83,12 +83,15 @@ tailor function logs [options] [execution-id]
 
 **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`      |
-| `--order <ORDER>`               | -     | Sort order (asc or desc)                         | No       | `"desc"` | -                              |
-| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0: unlimited) | No       | `50`     | -                              |
+| 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`      |
+| `--order <ORDER>`               | -     | Sort order (asc or desc)                                                                     | No       | `"desc"` | -                              |
+| `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0: unlimited)                                             | No       | `50`     | -                              |
+| `--follow`                      | `-f`  | Keep polling a running execution and print new log entries as they arrive (detail mode only) | No       | `false`  | -                              |
+| `--interval <INTERVAL>`         | `-i`  | Polling interval for --follow (e.g., '3s', '500ms', '1m')                                    | No       | `"3s"`   | -                              |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to keep following (e.g., '30s', '10m'); unbounded by default                    | No       | -        | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -118,8 +121,18 @@ $ tailor function logs --json
 $ tailor function logs <execution-id> --json
 ```
 
+**Stream log entries of a running execution until it completes**
+
+```bash
+$ tailor function logs <execution-id> --follow
+```
+
 **Notes**
 
+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, whereas the flat `logs` string is filled in only after completion. The human-readable view shows the structured entries when present and falls back to `logs` otherwise.
+
+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. On environments where no structured entries are returned, `--follow` shows the flat `logs` string once the execution completes. With `--json`, `--follow` waits for completion and then emits the final execution details once.
+
 When viewing a specific execution that failed, the command displays error details with the stack trace mapped back to your original source files (clickable file links and code snippets, matching `function run` output).
 
 Stack traces are mapped only when the execution includes a content hash for the exact build that ran. If the content hash is missing or the build is no longer available, the command falls back to a plain-text error display.

package/docs/cli/tailordb.md

@@ -119,17 +119,17 @@ tailor tailordb migration generate [options]
 
 **Options**
 
-| Option                                | Alias | Description                                                                                                                                                                                     | Required | Default              | Env                  |
-| ------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--yes`                               | `-y`  | Skip confirmation prompts                                                                                                                                                                       | No       | `false`              | -                    |
-| `--config <CONFIG>`                   | `-c`  | Path to Tailor config file                                                                                                                                                                      | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--name <NAME>`                       | `-n`  | Optional description for the migration                                                                                                                                                          | No       | -                    | -                    |
-| `--init`                              | -     | Delete existing migrations and start fresh                                                                                                                                                      | No       | `false`              | -                    |
-| `--data-only`                         | -     | Create a migration with no schema changes whose migration script runs a standalone data transformation                                                                                          | No       | `false`              | -                    |
-| `--namespace <NAMESPACE>`             | -     | Target TailorDB namespace for --data-only (required if multiple namespaces exist)                                                                                                               | No       | -                    | -                    |
-| `--rename <RENAME>`                   | -     | Record a field or table rename instead of remove + add (format: "Table.oldField:newField" or "OldTable:NewTable"; repeatable). Renames require a migration script that copies the data.         | No       | -                    | -                    |
-| `--drop <DROP>`                       | -     | Confirm that a removed field or table is a genuine removal, not a rename (format: "Table.field" or "Table"; repeatable). Required in non-interactive runs for a removal with rename candidates. | No       | -                    | -                    |
-| `--expand-contract <EXPAND_CONTRACT>` | -     | Convert a field type through a temporary field (format: "Table.field"; repeatable). Generates two migrations.                                                                                   | No       | -                    | -                    |
+| Option                                | Alias | Description                                                                                                                                                                                                                                 | Required | Default              | Env                  |
+| ------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
+| `--yes`                               | `-y`  | Skip confirmation prompts                                                                                                                                                                                                                   | No       | `false`              | -                    |
+| `--config <CONFIG>`                   | `-c`  | Path to Tailor config file                                                                                                                                                                                                                  | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
+| `--name <NAME>`                       | `-n`  | Optional description for the migration                                                                                                                                                                                                      | No       | -                    | -                    |
+| `--init`                              | -     | Delete existing migrations and start fresh                                                                                                                                                                                                  | No       | `false`              | -                    |
+| `--data-only`                         | -     | Create a migration with no schema changes whose migration script runs a standalone data transformation                                                                                                                                      | No       | `false`              | -                    |
+| `--namespace <NAMESPACE>`             | -     | Target TailorDB namespace for --data-only (required if multiple namespaces exist)                                                                                                                                                           | No       | -                    | -                    |
+| `--rename <RENAME>`                   | -     | Record a field, table, or nested member rename instead of remove + add (format: "Table.oldField:newField", "OldTable:NewTable", or "Table.field.oldMember:newMember"; repeatable). Renames require a migration script that copies the data. | No       | -                    | -                    |
+| `--drop <DROP>`                       | -     | Confirm that a removed field, table, or nested member is a genuine removal, not a rename (format: "Table.field", "Table", or "Table.field.member"; repeatable). Required in non-interactive runs for a removal with rename candidates.      | No       | -                    | -                    |
+| `--expand-contract <EXPAND_CONTRACT>` | -     | Convert a field type, or a single value into an array, through a temporary field (format: "Table.field"; repeatable). Generates two migrations.                                                                                             | No       | -                    | -                    |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli/workspace.md

@@ -16,15 +16,17 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                                   | Description                                 |
-| ----------------------------------------- | ------------------------------------------- |
-| [`workspace app`](#workspace-app)         | Manage workspace applications               |
-| [`workspace create`](#workspace-create)   | Create a new Tailor Platform workspace.     |
-| [`workspace delete`](#workspace-delete)   | Delete a Tailor Platform workspace.         |
-| [`workspace get`](#workspace-get)         | Show detailed information about a workspace |
-| [`workspace list`](#workspace-list)       | List all Tailor Platform workspaces.        |
-| [`workspace restore`](#workspace-restore) | Restore a deleted workspace                 |
-| [`workspace user`](#workspace-user)       | Manage workspace users                      |
+| Command                                   | Description                                                                                    |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [`workspace app`](#workspace-app)         | Manage workspace applications                                                                  |
+| [`workspace create`](#workspace-create)   | Create a new Tailor Platform workspace.                                                        |
+| [`workspace delete`](#workspace-delete)   | Delete a Tailor Platform workspace.                                                            |
+| [`workspace get`](#workspace-get)         | Show detailed information about a workspace                                                    |
+| [`workspace list`](#workspace-list)       | List all Tailor Platform workspaces.                                                           |
+| [`workspace prune`](#workspace-prune)     | Delete stale temporary workspaces, by name and age or by the expiry each recorded at creation. |
+| [`workspace restore`](#workspace-restore) | Restore a deleted workspace                                                                    |
+| [`workspace ttl`](#workspace-ttl)         | Manage when a workspace becomes prunable.                                                      |
+| [`workspace user`](#workspace-user)       | Manage workspace users                                                                         |
 
 ### workspace app
 
@@ -98,17 +100,18 @@ tailor workspace create [options]
 
 **Options**
 
-| Option                                | Alias | Description                                                                                                 | Required | Default   | Env                               |
-| ------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
-| `--name <NAME>`                       | `-n`  | Workspace name                                                                                              | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (us-west, asia-northeast)                                                                  | 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`       |
-| `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                      | No       | -         | -                                 |
-| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                            | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
-| `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                     | No       | -         | -                                 |
-| `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active. | No       | `"write"` | -                                 |
+| Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
+| ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
+| `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (us-west, asia-northeast)                                                                                                    | 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`       |
+| `--ttl <TTL>`                         | -     | Record on the workspace itself when it becomes prunable, such as 30m, 24h, or 7d. `workspace prune --expired` deletes it once that has passed | No       | -         | -                                 |
+| `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                                                        | No       | -         | -                                 |
+| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                                                              | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
+| `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                                                       | No       | -         | -                                 |
+| `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active.                                   | No       | `"write"` | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -170,6 +173,48 @@ tailor workspace list [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+### workspace prune
+
+Delete stale temporary workspaces, by name and age or by the expiry each recorded at creation.
+
+**Usage**
+
+```
+tailor workspace prune [options]
+```
+
+**Options**
+
+| Option                                  | Alias | Description                                                                                                                                | Required | Default | Env                       |
+| --------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ------------------------- |
+| `--name <NAME>`                         | -     | Select workspaces whose whole name matches this regular expression (repeatable)                                                            | No       | -       | -                         |
+| `--older-than <OLDER_THAN>`             | -     | Minimum age since creation, such as 30m, 24h, or 7d. 0s disables the age check and requires a location. Required unless --expired is given | No       | -       | -                         |
+| `--expired`                             | -     | Select workspaces whose own --ttl expiry has passed, instead of by name and age. Requires --organization-root, --folder-id, or --personal  | No       | `false` | -                         |
+| `--organization-root <ORGANIZATION_ID>` | -     | Consider the workspaces directly under this organization, excluding those in its folders (repeatable)                                      | No       | -       | -                         |
+| `--folder-id <FOLDER_ID>`               | -     | Consider the workspaces in this folder (repeatable)                                                                                        | No       | -       | -                         |
+| `--personal`                            | -     | Consider the workspaces belonging to no organization and no folder                                                                         | No       | `false` | -                         |
+| `--exclude <EXCLUDE>`                   | -     | Keep a workspace with this exact name even when it matches (repeatable)                                                                    | No       | -       | -                         |
+| `--limit <LIMIT>`                       | -     | Abort when more workspaces match than this, without deleting anything. 0 removes the cap                                                   | No       | `20`    | -                         |
+| `--dry-run`                             | -     | List the workspaces that would be deleted without deleting them                                                                            | No       | `false` | -                         |
+| `--profile <PROFILE>`                   | -     | Workspace profile used for authentication and Platform selection                                                                           | No       | -       | `TAILOR_PLATFORM_PROFILE` |
+| `--yes`                                 | `-y`  | Skip confirmation prompts                                                                                                                  | No       | `false` | -                         |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+Use this to reclaim workspaces left behind by CI runs, preview deployments, or interrupted local test runs. A workspace is deleted only when its whole name matches a --name pattern, it was created at least --older-than ago, and it is not excluded, delete-protected, or outside the requested locations. Run with --dry-run first to see what would be deleted.
+
+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.
+
+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.
+
+Safety guards: the command aborts without deleting anything when more workspaces match than --limit allows (--dry-run still lists them all), both --expired and --older-than 0s (no age check) are only accepted together with at least one location option, and a location option that resolves to an empty value (an unset CI secret) is rejected instead of silently widening the sweep -- even when another location is given alongside it. Each workspace is re-read immediately before it is deleted and skipped when it no longer matches the name, location, exclusion, or delete-protection criteria that selected it. Unlike `workspace delete`, a single confirmation covers every listed candidate; pass --yes to skip it in CI. Deleted workspaces can be restored with `workspace restore` for a limited time.
+
+Only workspaces visible to the current login (or the machine user in CI) are considered.
+
 ### workspace restore
 
 Restore a deleted workspace
@@ -189,6 +234,74 @@ tailor workspace restore [options]
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
+### workspace ttl
+
+Manage when a workspace becomes prunable.
+
+**Usage**
+
+```
+tailor workspace ttl [command]
+```
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Commands**
+
+| Command                                       | Description                                                                        |
+| --------------------------------------------- | ---------------------------------------------------------------------------------- |
+| [`workspace ttl set`](#workspace-ttl-set)     | Record when a workspace becomes prunable, replacing any expiry it already records. |
+| [`workspace ttl clear`](#workspace-ttl-clear) | Drop a workspace's recorded prune expiry.                                          |
+
+#### workspace ttl clear
+
+Drop a workspace's recorded prune expiry.
+
+**Usage**
+
+```
+tailor workspace ttl clear [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`      |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+    A workspace recording no expiry is never deleted by `workspace prune --expired`. Clearing an expiry the workspace does not record succeeds without changing anything.
+
+#### workspace ttl set
+
+Record when a workspace becomes prunable, replacing any expiry it already records.
+
+**Usage**
+
+```
+tailor workspace ttl set [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`      |
+| `--ttl <TTL>`                   | -     | Time from now until the workspace becomes prunable, such as 30m, 24h, or 7d | Yes      | -       | -                              |
+
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+
+**Notes**
+
+    The expiry runs from now, not from when the workspace was created, so `--ttl 24h` always leaves a full day regardless of the workspace's age. Use this to give a restored workspace a new expiry, or to record one after `workspace create --ttl` failed to.
+
+    This is not an auto-delete timer: it only makes the workspace eligible for `workspace prune --expired`, which still honors delete protection and its own filters.
+
 ### workspace user
 
 Manage workspace users

package/docs/cli-reference.md

@@ -19,6 +19,12 @@ tailor <command> [options]
 | `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
 | `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |
 
+### Progress and Detailed Logs
+
+`generate` and `deploy` show service progress and failures on stderr. Pass `--verbose`
+to include individual loaded files, plugin table changes, and generated file paths.
+Generation reports completion for each plugin that finishes processing its output files.
+
 ### JSON Output
 
 For commands that return structured results, passing `--json` writes one parseable JSON document
@@ -29,10 +35,68 @@ Commands that only perform side effects and do not define a structured result ma
 even when `--json` is passed.
 
 Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing,
-a command failure under `--json` emits a JSON error envelope to stderr. CLI errors include a stable
-`error.code` and may include structured `error.next` and `error.context` fields for automated
-recovery. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain
-an error object.
+a command failure under `--json` emits a JSON error envelope to stderr. Failures you can act on — an
+invalid or missing option, a resource that does not exist, an invalid configuration, or an unmet
+precondition — carry a stable `error.code` such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`,
+or `MIGRATION_SCRIPT_REQUIRED`. Where a remediation exists, the envelope also includes
+`error.suggestion`, `error.help` (the `--help` invocation for the failing command), `error.next` (a
+runnable command), or `error.context`. `UNEXPECTED_ERROR` marks failures without a dedicated code,
+including SDK-internal errors. Diagnostic lines may precede the error envelope, and stdout is not
+guaranteed to contain an error object.
+
+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,
+the next step opens login help so you can reuse the original browser or machine-user login method. Permission and
+connection failures include guidance in `error.suggestion`; API failures also identify the operation
+and affected resources in `error.context`.
+
+If deployment fails and saving recovery metadata also fails, `DEPLOY_METADATA_RECOVERY_FAILED`
+includes separate `error.context.apply` and `error.context.recovery` errors, each retaining its code
+and available recovery information. Inspect the current resource state before retrying: some writes
+may have completed. `--verbose --json` additionally includes stack traces for both causes.
+
+Generation hook failures use `PLUGIN_GENERATION_FAILED`. The error includes the failed hook
+and each failing plugin's ID and error in `error.context.failures`; successful plugins are
+excluded from that list.
+
+### Verbose Output
+
+Use `--verbose` to include debug diagnostics and error stack traces. `DEBUG=true` or
+`RUNNER_DEBUG=1` also enables verbose output, including stacks in JSON errors. GitHub Actions
+sets `RUNNER_DEBUG=1` when debug logging is enabled, so the same command automatically includes
+these details in a debug run. These settings do not enable JSON output; pass `--json` separately.
+
+Capture the original failure's stderr and exit code before retrying. Argument parsing and failures
+before the CLI starts may produce plain text even with `--json`. A failed deployment may have
+already applied changes, so inspect its output before deciding to run it again.
+
+### GitHub Actions Annotations
+
+When `GITHUB_ACTIONS` is exactly `true`, a command that ends in failure also writes one
+`::error::` workflow command to stderr, so the failure appears as an annotation on the run
+instead of only inside the scrolled log. The annotation repeats what the CLI already prints:
+its `title` is the error code (`AUTH_TOKEN_NOT_FOUND`, `PLUGIN_GENERATION_FAILED`, ...), and its
+body carries the same details, suggestion, and next action. Colors are stripped and newlines are
+encoded, so the annotation is a single line.
+
+Exactly one annotation is written per failed command, and only for the failure that ends it.
+Warnings and individually reported problems stay plain stderr output. The bundled CLI plugins
+(`seed`, `setup`, `tailordb-erd`) annotate their failures the same way. A command that exits
+without reporting through the CLI's error path, such as one relaying a failed remote execution,
+writes no annotation.
+
+Set `TAILOR_GITHUB_ACTIONS_ANNOTATIONS=false` (also `off`, `no`, or `0`) to turn annotations off.
+Passing `--json` also suppresses them, so a workflow step that parses `--json` output gets only the
+error envelope on stderr. The flag is honored even when the command fails during argument parsing,
+before the envelope itself becomes available.
+
+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;
+those messages describe the workflow's own checks, which can fail even when the CLI succeeds.
+
+Annotations do not yet carry `file=`/`line=` source locations, and `generate` and `deploy` do not
+group their per-service progress.
 
 ## Common Options
 
@@ -83,6 +147,7 @@ You can use environment variables to configure workspace and authentication:
 | `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count     |
 | `TAILOR_APPLY_CONCURRENCY`                   | Max concurrent platform RPCs during `apply`/`deploy`. Defaults to 16                                  |
 | `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                           |
+| `TAILOR_GITHUB_ACTIONS_ANNOTATIONS`          | GitHub Actions failure annotations: `on` (default) or `off`                                           |
 | `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                      |
 | `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                            |
 
@@ -265,27 +330,31 @@ Commands for managing organizations and folders.
 
 Commands for managing workspaces and profiles.
 
-| Command                                                           | Description                                                |
-| ----------------------------------------------------------------- | ---------------------------------------------------------- |
-| [workspace](./cli/workspace.md#workspace)                         | Manage Tailor Platform workspaces.                         |
-| [workspace app](./cli/workspace.md#workspace-app)                 | Manage workspace applications                              |
-| [workspace app health](./cli/workspace.md#workspace-app-health)   | Check application schema health                            |
-| [workspace app list](./cli/workspace.md#workspace-app-list)       | List applications in a workspace                           |
-| [workspace create](./cli/workspace.md#workspace-create)           | Create a new Tailor Platform workspace.                    |
-| [workspace delete](./cli/workspace.md#workspace-delete)           | Delete a Tailor Platform workspace.                        |
-| [workspace get](./cli/workspace.md#workspace-get)                 | Show detailed information about a workspace                |
-| [workspace list](./cli/workspace.md#workspace-list)               | List all Tailor Platform workspaces.                       |
-| [workspace restore](./cli/workspace.md#workspace-restore)         | Restore a deleted workspace                                |
-| [workspace user](./cli/workspace.md#workspace-user)               | Manage workspace users                                     |
-| [workspace user invite](./cli/workspace.md#workspace-user-invite) | Invite a user to a workspace                               |
-| [workspace user list](./cli/workspace.md#workspace-user-list)     | List users in a workspace                                  |
-| [workspace user remove](./cli/workspace.md#workspace-user-remove) | Remove a user from a workspace                             |
-| [workspace user update](./cli/workspace.md#workspace-user-update) | Update a user's role in a workspace                        |
-| [profile](./cli/workspace.md#profile)                             | Manage workspace profiles (user + workspace combinations). |
-| [profile create](./cli/workspace.md#profile-create)               | Create a new profile.                                      |
-| [profile delete](./cli/workspace.md#profile-delete)               | Delete a profile.                                          |
-| [profile list](./cli/workspace.md#profile-list)                   | List all profiles.                                         |
-| [profile update](./cli/workspace.md#profile-update)               | Update profile properties.                                 |
+| Command                                                           | Description                                                                                    |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| [workspace](./cli/workspace.md#workspace)                         | Manage Tailor Platform workspaces.                                                             |
+| [workspace app](./cli/workspace.md#workspace-app)                 | Manage workspace applications                                                                  |
+| [workspace app health](./cli/workspace.md#workspace-app-health)   | Check application schema health                                                                |
+| [workspace app list](./cli/workspace.md#workspace-app-list)       | List applications in a workspace                                                               |
+| [workspace create](./cli/workspace.md#workspace-create)           | Create a new Tailor Platform workspace.                                                        |
+| [workspace delete](./cli/workspace.md#workspace-delete)           | Delete a Tailor Platform workspace.                                                            |
+| [workspace get](./cli/workspace.md#workspace-get)                 | Show detailed information about a workspace                                                    |
+| [workspace list](./cli/workspace.md#workspace-list)               | List all Tailor Platform workspaces.                                                           |
+| [workspace prune](./cli/workspace.md#workspace-prune)             | Delete stale temporary workspaces, by name and age or by the expiry each recorded at creation. |
+| [workspace restore](./cli/workspace.md#workspace-restore)         | Restore a deleted workspace                                                                    |
+| [workspace ttl](./cli/workspace.md#workspace-ttl)                 | Manage when a workspace becomes prunable.                                                      |
+| [workspace ttl clear](./cli/workspace.md#workspace-ttl-clear)     | Drop a workspace's recorded prune expiry.                                                      |
+| [workspace ttl set](./cli/workspace.md#workspace-ttl-set)         | Record when a workspace becomes prunable, replacing any expiry it already records.             |
+| [workspace user](./cli/workspace.md#workspace-user)               | Manage workspace users                                                                         |
+| [workspace user invite](./cli/workspace.md#workspace-user-invite) | Invite a user to a workspace                                                                   |
+| [workspace user list](./cli/workspace.md#workspace-user-list)     | List users in a workspace                                                                      |
+| [workspace user remove](./cli/workspace.md#workspace-user-remove) | Remove a user from a workspace                                                                 |
+| [workspace user update](./cli/workspace.md#workspace-user-update) | Update a user's role in a workspace                                                            |
+| [profile](./cli/workspace.md#profile)                             | Manage workspace profiles (user + workspace combinations).                                     |
+| [profile create](./cli/workspace.md#profile-create)               | Create a new profile.                                                                          |
+| [profile delete](./cli/workspace.md#profile-delete)               | Delete a profile.                                                                              |
+| [profile list](./cli/workspace.md#profile-list)                   | List all profiles.                                                                             |
+| [profile update](./cli/workspace.md#profile-update)               | Update profile properties.                                                                     |
 
 ### [Auth Resource Commands](./cli/auth.md)
 

package/docs/configuration.md

@@ -21,19 +21,23 @@ To deploy the same config to multiple workspaces with per-environment values, se
 import { defineConfig } from "@tailor-platform/sdk";
 
 export default defineConfig({
-  // SDK-managed app id — do not edit, except when copying this config to a separate app.
-  // id: "<uuid>" — written here automatically on first run
   name: "my-app",
   cors: ["https://example.com"],
   allowedIpAddresses: ["192.168.1.0/24"],
   disableIntrospection: false,
   logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  metadata: { "erp-kit-version": "v1-2-3" },
 });
 ```
 
 **Name**: Set the application name.
 
-**Id (auto-managed)**: A stable identifier used to recognize resources managed by the SDK across renames. On first `deploy`, the SDK injects an `id: "<uuid>"` field into your `defineConfig({...})` call and commits it to `tailor.config.ts`. Keep it under version control; do not edit it by hand. Delete it only if you want the SDK to assign a new id on the next `deploy` — typically when `tailor.config.ts` was copied from another project and the new application should not share the original's id. Auto-injection requires `defineConfig({...})` to be called with an inline object literal: if the argument is a separate variable (e.g. `defineConfig(config)`), or if `tailor.config.ts` is a wrapper that re-exports `defineConfig` from another file, the SDK cannot inject — add the `id` field manually to the file that contains the actual `defineConfig({...})` object literal.
+**Id (auto-managed)**: A stable identifier used to recognize resources managed by the SDK across renames. The SDK assigns it on the first local `deploy` and keeps it under version control for you; do not edit it by hand.
+
+- Projects that use [`tailor setup`](./github-actions.md#app-id) keep the id in `.github/tailor.lock`, under `appIds`, keyed by the config file's path. `tailor.config.ts` itself carries no id, so a config copied inside the repository gets its own id, and configs that re-export another file work as well.
+- Other projects get an `id: "<uuid>"` field written into the `defineConfig({...})` call. Delete it only if you want the SDK to assign a new id on the next `deploy` — typically when `tailor.config.ts` was copied from another project and the new application should not share the original's id. Writing the field requires `defineConfig({...})` to be called with an inline object literal: if the argument is a separate variable (e.g. `defineConfig(config)`), or if `tailor.config.ts` re-exports a config from another file, add the `id` field manually to the file that contains the actual `defineConfig({...})` object literal.
+
+When a project starts using `tailor setup`, the next local `deploy` or `setup` moves the id from `tailor.config.ts` into the lock and removes it from the config. `AppConfig.id` stays supported: a config `id` that agrees with the lock is accepted (a local `deploy` moves it into the lock; `deploy --dry-run`, `remove`, and CI remind you to remove it), and one that disagrees stops the command so you can decide which value to keep.
 
 **CORS**: Specify CORS settings as an array. You can also include Static Website URL references (e.g. `website.url`) in this array; see [Static Website](./services/staticwebsite.md).
 
@@ -41,6 +45,19 @@ export default defineConfig({
 
 **Disable Introspection**: Disable GraphQL introspection. Default is `false`.
 
+**Metadata**: Extra labels written to the deployed application's metadata on `deploy`, alongside the labels the SDK writes itself. Use it to record information that tooling reads back from the platform, such as the version of a framework the config is generated from. Keys must match `^[a-z][a-z0-9_-]{0,62}$` and must not start with `sdk-`; values must be empty or match the same pattern, so a version like `1.2.3` is written as `v1-2-3`. At most 17 entries can be set:
+
+```typescript
+const erpKitVersion = "1.2.3";
+
+export default defineConfig({
+  name: "my-app",
+  metadata: { "erp-kit-version": `v${erpKitVersion.replace(/\./g, "-")}` },
+});
+```
+
+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.
+
 **Log Level**: 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:
 
 ```typescript

package/docs/github-actions.md

@@ -208,22 +208,54 @@ planned.)
 ### `.github/tailor.lock`
 
 A machine-owned JSON file that tracks which files the SDK manages, the inputs
-they were generated from, and their content hashes. **Commit this file. Never
-edit it by hand.** The SDK uses it to recognize its own files on re-runs and to
-detect hand edits.
-
-### `tailor.config.ts` (id injection)
-
-If your config does not already have an `id` field, `setup` injects one.
-This `id` must be committed alongside the workflow file. In CI, `tailor
-deploy` refuses to inject a new id — if the id were assigned fresh on each CI
-run, every deploy would create a brand-new application and lose ownership of
-previously deployed resources.
+they were generated from, and their content hashes, plus the id of every app in
+the repository (see [App id](#app-id)). **Commit this file.** The SDK uses it to
+recognize its own files on re-runs and to detect hand edits. The only part
+meant for hand editing is `appIds`, and only to re-key an entry after moving an
+app directory or to delete the entry of a removed app.
+
+### App id
+
+Every application has a stable id (a UUID) that the SDK uses to recognize the
+resources it owns across renames. In a repository set up with `tailor setup`,
+the id lives in `.github/tailor.lock` under `appIds`, keyed by the config
+file's repository-relative path:
+
+```jsonc
+{
+  "version": 2,
+  "targets": [/* generated workflows */],
+  "appIds": {
+    "apps/order/tailor.config.ts": "d0a3398a-…",
+    "apps/billing/tailor.config.ts": "7f21c4e0-…",
+  },
+}
+```
 
+`setup` records the id when it generates a workflow, and a local `tailor
+deploy` records one for any config that has none yet. Because the key is the
+config path, renaming the app keeps its id, and copying a config to a new
+directory gives the copy a fresh id instead of the original's. If
+`tailor.config.ts` still has an `id` field from before, `setup` or a local
+`deploy` moves it into the lock and removes it from the config; a config `id`
+that disagrees with the lock stops the command so you can decide which value
+to keep.
+
+In CI, `tailor deploy` never assigns an id — if one were assigned fresh on
+each run, every deploy would create a brand-new application and lose ownership
+of previously deployed resources. A config without a recorded id fails the
+plan job with instructions to run `tailor deploy` locally and commit the lock.
 If your pipeline intentionally deploys a fresh, throwaway application on every
 run (for example an end-to-end test harness that creates and deletes its own
-workspace), set `TAILOR_CI_ALLOW_ID_INJECTION=true` to opt back
-into automatic id injection for that pipeline.
+workspace), set `TAILOR_CI_ALLOW_ID_INJECTION=true` to let CI assign one.
+
+When you move an app directory, its `appIds` entry still points at the old
+path. Locally, `deploy` and `setup` notice the single unmatched entry and ask
+whether the app was moved; answering yes re-keys the entry so the app keeps
+its id. In CI, or when more than one entry is unmatched, the command stops and
+asks you to re-key the entry (or delete entries of removed apps) by hand.
+Re-run the relevant `setup` subcommand as well so the workflow's paths follow
+the move.
 
 ## Secrets
 

package/docs/migration/v3.md

@@ -160,3 +160,41 @@ property, which is the relation's cardinality (e.g. "n-1", "1-1",
 ```
 
 </details>
+
+## String file uploads → explicit encoding
+
+**Migration:** Manual
+
+String inputs to the SDK `file.upload` and generated `uploadFile` require an explicit `encoding` in v3. Add `encoding: "utf8"` to preserve the previous behavior; use `"base64"` only when decoding the input is intended. Byte inputs are unchanged. This migration requires checking the input type and regenerating file helpers, so it provides review guidance instead of rewriting calls automatically.
+
+Before:
+
+```ts
+await file.upload(ns, table, field, id, text, { contentType: "text/plain" });
+```
+
+After:
+
+```ts
+await file.upload(ns, table, field, id, text, { contentType: "text/plain", encoding: "utf8" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Inspect calls to the imported SDK file.upload (including aliases and destructured upload)
+and generated uploadFile helpers, including shared wrappers and option objects.
+For string inputs, add encoding: utf8 to preserve existing text storage behavior.
+Choose encoding: base64 only if decoding is explicitly intended; never infer it from
+the string contents or contentType. Preserve all existing upload options.
+Leave byte-only inputs unchanged. For string | byte unions, supplying encoding: utf8
+preserves behavior because byte input ignores encoding. Narrow shared options types
+so TypeScript can see that encoding is present for strings.
+Run tailor generate to regenerate uploadFile helpers instead of editing generated files.
+The global tailordb.file.upload does not support this encoding option; switch to the
+file import from @tailor-platform/sdk/runtime before using it.
+Do not change unrelated upload APIs or already explicit encodings.
+```
+
+</details>