@tailor-platform/sdk 2.15.0 → 2.17.0

package/dist/vitest/mocks/tailordb-pglite.d.mts

@@ -29,10 +29,11 @@ interface CreatedClient {
  * PGlite instances are borrowed, never closed — close them yourself (e.g. in
  * `afterAll`).
  *
- * Create the tables a test needs up front with `CREATE TABLE` statements
- * matching the generated Kysely types. PGlite runs full PostgreSQL while
- * TailorDB supports a subset of it, so a statement passing here can still be
- * rejected by the platform.
+ * Create the tables a test needs up front: run the script `kyselyTypePlugin`
+ * writes when `pgliteSchemaPath` is set, or your own `CREATE TABLE`
+ * statements matching the generated Kysely types. PGlite runs full PostgreSQL
+ * while TailorDB supports a subset of it, so a statement passing here can
+ * still be rejected by the platform.
  *
  * Transactions on a shared instance are serialized: while one is open,
  * queries from other `getDB` instances on the same PGlite instance wait for

package/docs/cli/tailordb.md

@@ -129,7 +129,7 @@ tailor tailordb migration generate [options]
 | `--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 through a temporary field (format: "Table.field"; repeatable). Generates two migrations.                                                                                                                               | 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.
 
@@ -177,19 +177,19 @@ tailor tailordb migration script [options] <number>
 
 **Options**
 
-| Option                    | Alias | Description                                                                                           | Required | Default              | Env                  |
-| ------------------------- | ----- | ----------------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                            | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                                     | No       | -                    | -                    |
-| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason)          | No       | -                    | -                    |
-| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                                      | No       | -                    | -                    |
-| `--with-test`             | -     | Also add a migrate.test.ts unit-test scaffold; when migrate.ts already exists, only the test is added | No       | -                    | -                    |
+| Option                    | Alias | Description                                                                                  | Required | Default              | Env                  |
+| ------------------------- | ----- | -------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
+| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                   | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
+| `--namespace <NAMESPACE>` | `-n`  | Target TailorDB namespace (required if multiple namespaces exist)                            | No       | -                    | -                    |
+| `--no-script`             | -     | Record that this migration intentionally runs without a migration script (requires --reason) | No       | -                    | -                    |
+| `--reason <REASON>`       | -     | Reason why no migration script is needed (used with --no-script)                             | No       | -                    | -                    |
+| `--with-test`             | -     | Also add the migrate.test.ts and migrate.pglite.test.ts scaffolds                            | No       | -                    | -                    |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment.
+When `migrate.ts` already exists, running the command clears a previously recorded `--no-script` acknowledgment, and `--with-test` adds only the tests that do not exist yet (writing `db.pglite.ts` if it is missing). `migrate.pglite.test.ts` is scaffolded only when `@electric-sql/pglite` is installed in the project.
 
 #### tailordb migration set
 

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`                                            |
 
@@ -145,9 +210,13 @@ Resolution rules:
 - **Lookup order:** the project's `node_modules/.bin` (nearest first, walking up from the current
   directory), then your `PATH`. So a plugin installed as a project dev-dependency takes precedence over a
   globally installed one.
-- **Place global flags after the plugin command.** Only the arguments following the plugin name are
-  forwarded; a global flag placed before it (e.g. `tailor --json tailordb erd export`) is consumed by
-  the host CLI and does not reach the plugin. Write `tailor tailordb erd export --json` instead.
+- **Global flags reach the plugin from either side.** `tailor --json tailordb erd export` and
+  `tailor tailordb erd export --json` both forward `--json`, and likewise `--verbose` and the
+  `--env-file` options. A flag typed before the plugin name is consumed by the host CLI first and
+  then forwarded, so when the same flag appears on both sides the later one wins. A flag the host
+  does not define — including one only some commands declare, such as `--profile` — still has to be
+  typed after the plugin's own subcommand. `--help` and `--version` are answered by the host CLI and
+  never dispatch a plugin.
 
 Because resolution is based on `node_modules/.bin` and `PATH`, any package manager that populates
 `node_modules/.bin` works for project-local plugins — npm, pnpm (its content-addressable store is
@@ -265,27 +334,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/plugin/custom.md

@@ -324,6 +324,37 @@ const AuditLog = await getGeneratedTable(configPath, "@example/audit-log", null,
 5. Caches the result to avoid redundant processing
 6. Returns the generated table matching the specified kind
 
+## getExtendedTable Helper
+
+A table that plugins are attached to gains the fields those plugins return in `extends.fields`, but only in the table `tailor generate` registers — the object exported from the table's source file stays as written. `getExtendedTable()` returns the table with every plugin-added field applied, so tooling that reads the table at runtime sees the same fields `tailor generate` does.
+
+```typescript
+import { join } from "node:path";
+import { getExtendedTable } from "@tailor-platform/sdk/plugin";
+import { customer } from "./tailordb/customer";
+
+const configPath = join(import.meta.dirname, "./tailor.config.ts");
+
+const extendedCustomer = await getExtendedTable(configPath, customer);
+extendedCustomer.fields.deletedAt; // added by a plugin attached with .plugin()
+```
+
+**Parameters:**
+
+- `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
+- `sourceTable`: The TailorDB table as exported from its source file
+
+**How it works:**
+
+1. Returns `sourceTable` itself when no plugin is attached to it
+2. Loads and caches the config from the given path
+3. Auto-resolves the namespace from config
+4. Calls each attached plugin's `onTableLoaded()` in the order of the `.plugin()` calls, each seeing the fields the plugins before it added
+5. Caches the result per config path and table
+6. Returns a new table with the added fields; `sourceTable` is not changed
+
+The seed schema files `tailor generate` writes for tables with plugins attached use this helper, so `tailor seed validate` checks plugin-added fields like the table's own.
+
 ## Examples
 
 ### Definition-time Plugin (Soft Delete)
@@ -646,10 +677,11 @@ of whether `.files()` or `.plugin()` was called first. `tailor generate` also re
 collision at runtime, as a backstop for any case a table's static type doesn't otherwise catch.
 
 This only affects the table's static type. The corresponding field exists on the table's
-generated schema, and on the table object's own `fields`, only after `tailor generate` actually
-applies `extends.fields`. Before that, reading an injected field directly off the table
-(`table.fields.status`) returns `undefined`, and `pickFields(["status"])` throws — call these only
-with the table's originally declared fields, not ones a plugin injects.
+generated schema, and on the table `tailor generate` registers, only once `extends.fields` is
+applied; the table object exported from the source file never gains it. Reading an injected field
+directly off that object (`table.fields.status`) returns `undefined`, and `pickFields(["status"])`
+throws — call these only with the table's originally declared fields, or load the table with
+[`getExtendedTable()`](#getextendedtable-helper) first.
 
 To keep the declared type and the runtime implementation in sync, give `Plugin`'s optional third
 type parameter the same shape and use it inside `onTableLoaded`: