@tailor-platform/sdk 2.0.0-next.0 → 2.0.0-next.10

package/docs/cli-reference.md

@@ -1,26 +1,23 @@
-# tailor-sdk
+# tailor
 
 Tailor Platform SDK - The SDK to work with Tailor Platform
 
 ## Usage
 
 ```bash
-tailor-sdk <command> [options]
+tailor <command> [options]
 ```
 
 ## Global Options
 
-<!-- politty:global-options:start -->
-
 <a id="global-options"></a>
-| Option | Alias | Description | Required | Default |
-|--------|-------|-------------|----------|---------|
-| `--env-file <ENV_FILE>` | `-e` | Path to the environment file (error if not found) | No | - |
-| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | - | Path to the environment file (ignored if not found) | No | - |
-| `--verbose` | - | Enable verbose logging | No | `false` |
-| `--json` | `-j` | Output as JSON | No | `false` |
 
-<!-- politty:global-options:end -->
+| Option                                      | Alias | Description                                         | Required | Default |
+| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- |
+| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       |
+| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       |
+| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
+| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |
 
 ### JSON Output
 
@@ -31,8 +28,11 @@ human-readable text or empty stdout.
 Commands that only perform side effects and do not define a structured result may leave stdout empty
 even when `--json` is passed.
 
-Errors, warnings, progress, and diagnostic messages are written to stderr. On failure, check the
-non-zero exit code and read stderr; stdout is not guaranteed to contain a JSON error object.
+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.
 
 ## Common Options
 
@@ -42,7 +42,7 @@ The following options are available for most commands:
 | ---------------- | ----- | -------------------------------------- |
 | `--workspace-id` | `-w`  | Workspace ID (for deployment commands) |
 | `--profile`      | `-p`  | Workspace profile                      |
-| `--config`       | `-c`  | Path to SDK config file                |
+| `--config`       | `-c`  | Path to Tailor config file             |
 | `--yes`          | `-y`  | Skip confirmation prompts              |
 
 ### Environment File Loading
@@ -55,42 +55,46 @@ Both `--env-file` and `--env-file-if-exists` can be specified multiple times and
 
 ```bash
 # Load .env (required) and .env.local (optional, if exists)
-tailor-sdk deploy --env-file .env --env-file-if-exists .env.local
+tailor deploy --env-file .env --env-file-if-exists .env.local
 
 # Load multiple files
-tailor-sdk deploy --env-file .env --env-file .env.production
+tailor deploy --env-file .env --env-file .env.production
 ```
 
 ## Environment Variables
 
 You can use environment variables to configure workspace and authentication:
 
-| Variable                                     | Description                                                                                       |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                              |
-| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                         |
-| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                     |
-| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                     |
-| `TAILOR_TOKEN`                               | **Deprecated.** Use `TAILOR_PLATFORM_TOKEN` instead                                               |
-| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                            |
-| `TAILOR_PLATFORM_SDK_CONFIG_PATH`            | Path to SDK config file                                                                           |
-| `TAILOR_PLATFORM_SDK_DTS_PATH`               | Output path for generated `tailor.d.ts` type definition file                                      |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                              |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                          |
-| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run`, `machineuser token` |
-| `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count |
-| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                       |
-| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                  |
-| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                        |
+| Variable                                     | Description                                                                                           |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                                  |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                             |
+| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                         |
+| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                         |
+| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                                |
+| `TAILOR_CONFIG_PATH`                         | Path to Tailor config file                                                                            |
+| `TAILOR_DTS_PATH`                            | Output path for generated `tailor.d.ts` type definition file                                          |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                                  |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                              |
+| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run`, `machineuser token`     |
+| `TAILOR_PLATFORM_URL`                        | Platform API base URL. Saved into profiles created with `profile create --platform-url`               |
+| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID`           | OAuth2 client ID for user login. Saved into profiles created with `profile create --oauth2-client-id` |
+| `TAILOR_PLATFORM_CONSOLE_URL`                | Console base URL. Saved into profiles created with `profile create --console-url`                     |
+| `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_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                      |
+| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                            |
 
 ### Authentication Token Priority
 
 Token resolution follows this priority order:
 
 1. `TAILOR_PLATFORM_TOKEN` environment variable
-2. `TAILOR_TOKEN` environment variable (deprecated)
-3. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`
-4. Current user from platform config (`~/.config/tailor-platform/config.yaml`)
+2. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`
+3. Current user from platform config (`~/.config/tailor-platform/config.yaml`)
+
+Config-backed login tokens are scoped to the Platform API URL. Profiles with `--platform-url` use the token saved for that URL, so switching profiles can also switch between Platform API environments.
 
 ### Workspace ID Priority
 
@@ -100,9 +104,81 @@ Workspace ID resolution follows this priority order:
 2. `TAILOR_PLATFORM_WORKSPACE_ID` environment variable
 3. Profile specified via `--profile` option or `TAILOR_PLATFORM_PROFILE`
 
-## Commands
+## CLI Plugins
+
+> [!WARNING]
+> CLI plugins are a **beta** feature. The dispatch behavior and the set of injected environment
+> variables may change in a future release.
+
+You can extend the CLI with external plugins, similar to `gh` extensions. When you run a command that
+is not a built-in, the CLI looks for an executable named `tailor-<name>` and runs it, forwarding the
+remaining arguments:
+
+```bash
+# Runs the `tailor-hello` executable with: world --loud
+tailor hello world --loud
+```
+
+This is how the `@tailor-platform/sdk-plugin-seed` package provides the `seed` commands:
+
+```bash
+# Runs `tailor-seed` with: apply
+tailor seed apply
+```
+
+This also works under a built-in command group. The command path is joined with hyphens, so a plugin
+nested under `tailordb` is named `tailor-tailordb-erd`. This is how the
+`@tailor-platform/sdk-plugin-tailordb-erd`
+package provides the `tailordb erd` commands:
+
+```bash
+# Runs `tailor-tailordb-erd` with: export
+tailor tailordb erd export
+```
 
-<!-- politty:index:docs/cli-reference.md:start -->
+Resolution rules:
+
+- **Built-ins always win.** A plugin is only used when no built-in command matches.
+- **A command that takes its own arguments is never replaced.** Plugin dispatch applies only to command
+  _groups_ (commands that just route to subcommands). A command that performs its own action — including
+  one that accepts a positional argument — always runs itself, so a plugin can never shadow an argument value.
+- **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.
+
+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
+transparent here), Bun, and Yarn Classic. The exception is **Yarn Plug'n'Play**, which does not create a
+`node_modules` directory: install such plugins globally so they resolve via `PATH`, or use Yarn's
+`nodeLinker: node-modules` setting.
+
+Run `tailor plugin list` to see which plugins are discovered and where they resolve from.
+
+### Context passed to plugins
+
+Before running a plugin, the CLI injects the current Tailor Platform context as environment variables so
+the plugin does not need to re-implement authentication or re-resolve the active workspace:
+
+| Variable                           | Description                                                              |
+| ---------------------------------- | ------------------------------------------------------------------------ |
+| `TAILOR_PLATFORM_TOKEN`            | A valid access token (refreshed if needed). Omitted when not logged in.  |
+| `TAILOR_PLATFORM_URL`              | The Tailor Platform endpoint in effect                                   |
+| `TAILOR_PLATFORM_OAUTH2_CLIENT_ID` | The OAuth2 client ID in effect, for plugins that run their own auth flow |
+| `TAILOR_PLATFORM_WORKSPACE_ID`     | The resolved workspace ID, when one can be determined                    |
+| `TAILOR_PLATFORM_USER`             | The active user (email when known), when logged in                       |
+| `TAILOR_CONFIG_PATH`               | Path to the resolved Tailor config file, when found                      |
+| `TAILOR_VERSION`                   | The `tailor` version that invoked the plugin                             |
+| `TAILOR_BIN`                       | Path to the `tailor` executable, for calling back into the CLI           |
+
+The token, workspace ID, and user are best-effort: whatever the current context can resolve is injected,
+and auth-free plugins still run when you are not logged in. A long-running plugin (or one started on its
+own) can obtain a fresh token at any time with `tailor auth token`, which prints a valid access token to
+stdout, refreshing it first if it has expired.
+
+## Commands
 
 ### [Application Commands](./cli/application.md)
 
@@ -116,24 +192,24 @@ Commands for managing Tailor Platform applications (work with `tailor.config.ts`
 | [remove](./cli/application.md#remove)           | Remove all resources managed by the application from the workspace. |
 | [show](./cli/application.md#show)               | Show information about the deployed application.                    |
 | [open](./cli/application.md#open)               | Open Tailor Platform Console.                                       |
-| [api list](./cli/application.md#api-list)       | List all invocable OperatorService methods.                         |
+| [api](./cli/application.md#api)                 | Call Tailor Platform API endpoints directly.                        |
 | [api inspect](./cli/application.md#api-inspect) | Print the input message tree of an OperatorService endpoint.        |
+| [api list](./cli/application.md#api-list)       | List all invocable OperatorService methods.                         |
 
 ### [TailorDB Commands](./cli/tailordb.md)
 
 Commands for managing TailorDB tables, data, and schema migrations.
 
-| Command                                                                      | Description                                                                                                               |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                     | Truncate (delete all records from) TailorDB tables.                                                                       |
-| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot. |
-| [tailordb migration script](./cli/tailordb.md#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory.                                          |
-| [tailordb migration set](./cli/tailordb.md#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                            |
-| [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                      |
-| [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                     |
-| [tailordb erd export](./cli/tailordb.md#tailordb-erd-export)                 | Export TailorDB ERD static viewer from local TailorDB schema.                                                             |
-| [tailordb erd serve](./cli/tailordb.md#tailordb-erd-serve)                   | Generate and serve TailorDB ERD locally with watch reload. (beta)                                                         |
-| [tailordb erd deploy](./cli/tailordb.md#tailordb-erd-deploy)                 | Deploy ERD static website for TailorDB namespace(s).                                                                      |
+| Command                                                                      | Description                                                                                                                                          |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [tailordb](./cli/tailordb.md#tailordb)                                       | Manage TailorDB tables and data.                                                                                                                     |
+| [tailordb truncate](./cli/tailordb.md#tailordb-truncate)                     | Truncate (delete all records from) TailorDB tables.                                                                                                  |
+| [tailordb migration](./cli/tailordb.md#tailordb-migration)                   | Manage TailorDB schema migrations.                                                                                                                   |
+| [tailordb migration generate](./cli/tailordb.md#tailordb-migration-generate) | Generate migration files by detecting schema differences between current local types and the previous migration snapshot.                            |
+| [tailordb migration script](./cli/tailordb.md#tailordb-migration-script)     | Add a migration script (migrate.ts) template to an existing migration directory, or record with --no-script that a migration intentionally has none. |
+| [tailordb migration set](./cli/tailordb.md#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                                                       |
+| [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                                                 |
+| [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                                                |
 
 ### [Query Commands](./cli/query.md)
 
@@ -147,17 +223,21 @@ Run ad-hoc SQL/GraphQL queries or enter the interactive REPL.
 
 Commands for authentication and user management.
 
-| Command                                          | Description                                           |
-| ------------------------------------------------ | ----------------------------------------------------- |
-| [login](./cli/user.md#login)                     | Login to Tailor Platform.                             |
-| [logout](./cli/user.md#logout)                   | Logout from Tailor Platform.                          |
-| [user current](./cli/user.md#user-current)       | Show current user.                                    |
-| [user list](./cli/user.md#user-list)             | List all users.                                       |
-| [user switch](./cli/user.md#user-switch)         | Set current user.                                     |
-| [user pat list](./cli/user.md#user-pat-list)     | List all personal access tokens.                      |
-| [user pat create](./cli/user.md#user-pat-create) | Create a new personal access token.                   |
-| [user pat delete](./cli/user.md#user-pat-delete) | Delete a personal access token.                       |
-| [user pat update](./cli/user.md#user-pat-update) | Update a personal access token (delete and recreate). |
+| Command                                          | Description                                                                           |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [login](./cli/user.md#login)                     | Login to Tailor Platform.                                                             |
+| [logout](./cli/user.md#logout)                   | Logout from Tailor Platform.                                                          |
+| [auth](./cli/user.md#auth)                       | Authentication helpers for scripts and plugins.                                       |
+| [auth token](./cli/user.md#auth-token)           | Print a valid Tailor Platform access token to stdout, refreshing it first if expired. |
+| [user](./cli/user.md#user)                       | Manage Tailor Platform users.                                                         |
+| [user current](./cli/user.md#user-current)       | Show current user.                                                                    |
+| [user list](./cli/user.md#user-list)             | List all users.                                                                       |
+| [user pat](./cli/user.md#user-pat)               | Manage personal access tokens.                                                        |
+| [user pat create](./cli/user.md#user-pat-create) | Create a new personal access token.                                                   |
+| [user pat delete](./cli/user.md#user-pat-delete) | Delete a personal access token.                                                       |
+| [user pat list](./cli/user.md#user-pat-list)     | List all personal access tokens.                                                      |
+| [user pat update](./cli/user.md#user-pat-update) | Update a personal access token (delete and recreate).                                 |
+| [user switch](./cli/user.md#user-switch)         | Set current user.                                                                     |
 
 ### [Organization Commands](./cli/organization.md)
 
@@ -165,6 +245,8 @@ Commands for managing organizations and folders.
 
 | Command                                                                        | Description                                      |
 | ------------------------------------------------------------------------------ | ------------------------------------------------ |
+| [organization](./cli/organization.md#organization)                             | Manage Tailor Platform organizations.            |
+| [organization folder](./cli/organization.md#organization-folder)               | Manage organization folders.                     |
 | [organization folder create](./cli/organization.md#organization-folder-create) | Create a new folder in an organization.          |
 | [organization folder delete](./cli/organization.md#organization-folder-delete) | Delete a folder from an organization.            |
 | [organization folder get](./cli/organization.md#organization-folder-get)       | Show detailed information about a folder.        |
@@ -179,23 +261,27 @@ Commands for managing organizations and folders.
 
 Commands for managing workspaces and profiles.
 
-| Command                                                           | Description                                 |
-| ----------------------------------------------------------------- | ------------------------------------------- |
-| [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 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 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 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.                                 |
 
 ### [Auth Resource Commands](./cli/auth.md)
 
@@ -203,13 +289,16 @@ Commands for managing Auth service resources.
 
 | Command                                                            | Description                                                                           |
 | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [authconnection](./cli/auth.md#authconnection)                     | Manage auth connections.                                                              |
 | [authconnection authorize](./cli/auth.md#authconnection-authorize) | Authorize an auth connection via OAuth2 flow.                                         |
+| [authconnection delete](./cli/auth.md#authconnection-delete)       | Delete an auth connection entirely.                                                   |
 | [authconnection list](./cli/auth.md#authconnection-list)           | List all auth connections.                                                            |
 | [authconnection open](./cli/auth.md#authconnection-open)           | Open the auth connections page in the Tailor Platform Console.                        |
 | [authconnection revoke](./cli/auth.md#authconnection-revoke)       | Revoke an auth connection's tokens (keeps the connection; use 'delete' to remove it). |
-| [authconnection delete](./cli/auth.md#authconnection-delete)       | Delete an auth connection entirely.                                                   |
+| [machineuser](./cli/auth.md#machineuser)                           | Manage machine users in your Tailor Platform application.                             |
 | [machineuser list](./cli/auth.md#machineuser-list)                 | List all machine users in the application.                                            |
 | [machineuser token](./cli/auth.md#machineuser-token)               | Get an access token for a machine user.                                               |
+| [oauth2client](./cli/auth.md#oauth2client)                         | Manage OAuth2 clients in your Tailor Platform application.                            |
 | [oauth2client list](./cli/auth.md#oauth2client-list)               | List all OAuth2 clients in the application.                                           |
 | [oauth2client get](./cli/auth.md#oauth2client-get)                 | Get OAuth2 client credentials (including client secret).                              |
 
@@ -219,9 +308,11 @@ Commands for managing workflows and executions.
 
 | Command                                                      | Description                                    |
 | ------------------------------------------------------------ | ---------------------------------------------- |
+| [workflow](./cli/workflow.md#workflow)                       | Manage workflows and workflow executions.      |
 | [workflow list](./cli/workflow.md#workflow-list)             | List all workflows in the workspace.           |
 | [workflow get](./cli/workflow.md#workflow-get)               | Get workflow details.                          |
 | [workflow start](./cli/workflow.md#workflow-start)           | Start a workflow execution.                    |
+| [workflow wait](./cli/workflow.md#workflow-wait)             | Wait for a workflow execution.                 |
 | [workflow executions](./cli/workflow.md#workflow-executions) | List or get workflow executions.               |
 | [workflow resume](./cli/workflow.md#workflow-resume)         | Resume a failed or pending workflow execution. |
 
@@ -231,6 +322,7 @@ Commands for managing function registries and viewing function execution logs.
 
 | Command                                                  | Description                                                     |
 | -------------------------------------------------------- | --------------------------------------------------------------- |
+| [function](./cli/function.md#function)                   | Manage functions                                                |
 | [function get](./cli/function.md#function-get)           | Get a function registry by name                                 |
 | [function list](./cli/function.md#function-list)         | List function registries in a workspace                         |
 | [function logs](./cli/function.md#function-logs)         | List or get function execution logs.                            |
@@ -242,10 +334,12 @@ Commands for managing executors and executor jobs.
 
 | Command                                                          | Description                                   |
 | ---------------------------------------------------------------- | --------------------------------------------- |
-| [executor trigger](./cli/executor.md#executor-trigger)           | Trigger an executor manually.                 |
-| [executor jobs](./cli/executor.md#executor-jobs)                 | List or get executor jobs.                    |
+| [executor](./cli/executor.md#executor)                           | Manage executors                              |
 | [executor list](./cli/executor.md#executor-list)                 | List all executors                            |
 | [executor get](./cli/executor.md#executor-get)                   | Get executor details                          |
+| [executor jobs](./cli/executor.md#executor-jobs)                 | List or get executor jobs.                    |
+| [executor trigger](./cli/executor.md#executor-trigger)           | Trigger an executor manually.                 |
+| [executor webhook](./cli/executor.md#executor-webhook)           | Manage executor webhooks                      |
 | [executor webhook list](./cli/executor.md#executor-webhook-list) | List executors with incoming webhook triggers |
 
 ### [Secret Commands](./cli/secret.md)
@@ -254,13 +348,15 @@ Commands for managing secrets and vaults.
 
 | Command                                                    | Description                                      |
 | ---------------------------------------------------------- | ------------------------------------------------ |
+| [secret](./cli/secret.md#secret)                           | Manage Secret Manager vaults and secrets.        |
+| [secret create](./cli/secret.md#secret-create)             | Create a secret in a vault.                      |
+| [secret delete](./cli/secret.md#secret-delete)             | Delete a secret in a vault.                      |
+| [secret list](./cli/secret.md#secret-list)                 | List all secrets in a vault.                     |
+| [secret update](./cli/secret.md#secret-update)             | Update a secret in a vault.                      |
+| [secret vault](./cli/secret.md#secret-vault)               | Manage Secret Manager vaults.                    |
 | [secret vault create](./cli/secret.md#secret-vault-create) | Create a new Secret Manager vault.               |
 | [secret vault delete](./cli/secret.md#secret-vault-delete) | Delete a Secret Manager vault.                   |
 | [secret vault list](./cli/secret.md#secret-vault-list)     | List all Secret Manager vaults in the workspace. |
-| [secret create](./cli/secret.md#secret-create)             | Create a secret in a vault.                      |
-| [secret update](./cli/secret.md#secret-update)             | Update a secret in a vault.                      |
-| [secret list](./cli/secret.md#secret-list)                 | List all secrets in a vault.                     |
-| [secret delete](./cli/secret.md#secret-delete)             | Delete a secret in a vault.                      |
 
 ### [Static Website Commands](./cli/staticwebsite.md)
 
@@ -268,10 +364,12 @@ Commands for managing and deploying static websites.
 
 | Command                                                                       | Description                                           |
 | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| [staticwebsite](./cli/staticwebsite.md#staticwebsite)                         | Manage static websites in your workspace.             |
 | [staticwebsite deploy](./cli/staticwebsite.md#staticwebsite-deploy)           | Deploy a static website from a local build directory. |
-| [staticwebsite domain list](./cli/staticwebsite.md#staticwebsite-domain-list) | List custom domains for a static website.             |
-| [staticwebsite domain get](./cli/staticwebsite.md#staticwebsite-domain-get)   | Get details of a custom domain.                       |
 | [staticwebsite list](./cli/staticwebsite.md#staticwebsite-list)               | List all static websites in a workspace.              |
+| [staticwebsite domain](./cli/staticwebsite.md#staticwebsite-domain)           | Manage custom domains for static websites.            |
+| [staticwebsite domain get](./cli/staticwebsite.md#staticwebsite-domain-get)   | Get details of a custom domain.                       |
+| [staticwebsite domain list](./cli/staticwebsite.md#staticwebsite-domain-list) | List custom domains for a static website.             |
 | [staticwebsite get](./cli/staticwebsite.md#staticwebsite-get)                 | Get details of a specific static website.             |
 
 ### [Crash Report Commands](./cli/crashreport.md)
@@ -280,6 +378,7 @@ Commands for managing crash reports.
 
 | Command                                                   | Description                                    |
 | --------------------------------------------------------- | ---------------------------------------------- |
+| [crashreport](./cli/crashreport.md#crashreport)           | Manage crash reports.                          |
 | [crashreport list](./cli/crashreport.md#crashreport-list) | List local crash report files.                 |
 | [crashreport send](./cli/crashreport.md#crashreport-send) | Submit a crash report to help improve the SDK. |
 
@@ -287,9 +386,16 @@ Commands for managing crash reports.
 
 Commands for setting up project infrastructure.
 
-| Command                                     | Description                                       |
-| ------------------------------------------- | ------------------------------------------------- |
-| [setup github](./cli/setup.md#setup-github) | Generate a GitHub Actions deploy workflow. (beta) |
+| Command                                             | Description                                                                                      |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| [setup](./cli/setup.md#setup)                       | Generate CI deploy workflows for your project. (beta)                                            |
+| [setup action](./cli/setup.md#setup-action)         | Generate a per-app composite action for use with setup coordinate (monorepo multi-app deploys).  |
+| [setup branch](./cli/setup.md#setup-branch)         | Generate a branch-target deploy workflow (push to branch triggers deploy).                       |
+| [setup check](./cli/setup.md#setup-check)           | Audit generated workflows for drift against the current config/repo (read-only).                 |
+| [setup coordinate](./cli/setup.md#setup-coordinate) | Generate a coordinator workflow that orchestrates multiple --action-generated composite actions. |
+| [setup delete](./cli/setup.md#setup-delete)         | Delete managed workflow/action file(s) and their .github/tailor.lock entries.                    |
+| [setup preview](./cli/setup.md#setup-preview)       | Generate a preview workflow (PR open/sync triggers deploy to a per-PR workspace).                |
+| [setup tag](./cli/setup.md#setup-tag)               | Generate a tag-target deploy workflow (tag push triggers deploy).                                |
 
 ### [Upgrade Commands](./cli/upgrade.md)
 
@@ -301,11 +407,24 @@ Commands for upgrading SDK versions with automated code migration.
 
 ### [Skills Commands](./cli/skills.md)
 
-Commands for installing Tailor SDK agent skills.
+Commands for managing Tailor SDK agent skills.
+
+| Command                                        | Description                                   |
+| ---------------------------------------------- | --------------------------------------------- |
+| [skills](./cli/skills.md#skills)               | Manage Tailor SDK agent skills.               |
+| [skills add](./cli/skills.md#skills-add)       | Install Tailor SDK agent skills.              |
+| [skills list](./cli/skills.md#skills-list)     | List Tailor SDK agent skills.                 |
+| [skills remove](./cli/skills.md#skills-remove) | Remove installed Tailor SDK agent skills.     |
+| [skills sync](./cli/skills.md#skills-sync)     | Remove and reinstall Tailor SDK agent skills. |
+
+### [Plugin Commands](./cli/plugin.md)
 
-| Command                                          | Description                                                        |
-| ------------------------------------------------ | ------------------------------------------------------------------ |
-| [skills install](./cli/skills.md#skills-install) | Install the tailor-sdk agent skill from the installed SDK package. |
+Discover and inspect CLI plugins (external `tailor-<name>` executables).
+
+| Command                                    | Description                                                                              |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
+| [plugin](./cli/plugin.md#plugin)           | Manage and inspect CLI plugins (beta).                                                   |
+| [plugin list](./cli/plugin.md#plugin-list) | List discovered plugins (executables named `<cli>-<name>` on PATH or node_modules/.bin). |
 
 ### [Completion](./cli/completion.md)
 
@@ -314,5 +433,3 @@ Generate shell completion scripts for bash, zsh, and fish.
 | Command                                      | Description                      |
 | -------------------------------------------- | -------------------------------- |
 | [completion](./cli/completion.md#completion) | Generate shell completion script |
-
-<!-- politty:index:docs/cli-reference.md:end -->

package/docs/configuration.md

@@ -27,7 +27,7 @@ export default defineConfig({
   cors: ["https://example.com"],
   allowedIpAddresses: ["192.168.1.0/24"],
   disableIntrospection: false,
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 
@@ -41,16 +41,18 @@ export default defineConfig({
 
 **Disable Introspection**: Disable GraphQL introspection. Default is `false`.
 
-**Log Level**: Controls which `console.*` calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all console 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. For production deployments, use `"WARN"` to keep `console.warn` and `console.error` while dropping debug, log, and info calls:
+**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
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 
-This is a bundle-time setting. Changing `LOG_LEVEL` affects newly bundled deployments; already deployed functions must be redeployed.
+This is a bundle-time setting. Changing `TAILOR_APP_LOG_LEVEL` affects newly bundled deployments; already deployed functions must be redeployed.
+
+Only `logger.*` calls made through the SDK's `logger` wrapper (from `@tailor-platform/sdk/runtime` or its `@tailor-platform/sdk/runtime/logger` subpath), or written as `globalThis.tailor.logger.*`, are covered. Other equivalent forms — such as the bare `tailor.logger.*` global or `self.tailor.logger.*` — are not affected by `logLevel`.
 
 ### Service Configuration
 
@@ -82,6 +84,8 @@ export default defineConfig({
 
 **ignores**: Glob patterns to exclude files. Optional. By default, `**/*.test.ts` and `**/*.spec.ts` are automatically ignored. If you explicitly specify `ignores`, the default patterns will not be applied. Use `ignores: []` to include all files including test files.
 
+**Pattern resolution**: `files` and `ignores` patterns are resolved relative to the directory of the `tailor.config.ts` file that declares them, not the directory you run the command from. This matters when deploying [multiple configs](./cli/application.md#deploy) together — each config's patterns only match files under its own directory. If a config's _relative_ patterns match nothing under its own directory, the SDK falls back to resolving them from the directory you ran the command from and logs a warning (this fallback doesn't apply to already-absolute patterns, since their resolution can't change). Update such patterns to be relative to the config's own directory — this fallback will be removed in v2.
+
 ### External Resources
 
 You can reference resources managed by Terraform or other SDK projects to include them in your application's subgraph. External resources are not deployed by this project but can be used for shared access across multiple applications.
@@ -108,7 +112,7 @@ When using external resources:
 - The resource must be deployed and available before referencing it
 - You can combine external resources with locally-defined resources
 - TailorDB type names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB type names before applying changes
-- Destructive operations like `tailordb truncate` (and `seedPlugin`'s `seed:reset`) automatically exclude external resources to prevent accidental data loss in shared resources
+- Destructive operations like `tailordb truncate` (and `tailor seed apply --truncate`) automatically exclude external resources to prevent accidental data loss in shared resources
 
 ### Built-in IdP
 
@@ -118,8 +122,14 @@ Configure the Built-in IdP service using `defineIdp()`. See [IdP](./services/idp
 import { defineIdp } from "@tailor-platform/sdk";
 
 const idp = defineIdp("my-idp", {
-  authorization: "loggedIn",
   clients: ["my-client"],
+  permission: {
+    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+  },
 });
 
 export default defineConfig({
@@ -280,6 +290,30 @@ export default defineConfig({
 
 **ignores**: Glob patterns to exclude files. Optional.
 
+### Workflow Execution Policies
+
+Register workspace-scoped execution policies that workflow job functions reference at runtime for per-key concurrency control. See [Execution Policies](./services/workflow.md#execution-policies) in the Workflow guide for the declaration API.
+
+```typescript
+import { defineWorkflowExecutionPolicies } from "@tailor-platform/sdk";
+
+const executionPolicies = defineWorkflowExecutionPolicies((define) => ({
+  premium: define({ concurrencyPolicy: { maxConcurrentExecutions: 5 } }),
+  tenantApi: define({
+    name: "tenant-api",
+    matchType: "prefix",
+    concurrencyPolicy: { maxConcurrentExecutions: 3 },
+  }),
+}));
+
+export default defineConfig({
+  workflow: {
+    files: ["workflows/**/*.ts"],
+    executionPolicies,
+  },
+});
+```
+
 ### Plugins
 
 Configure plugins using `definePlugins()`. Plugins must be exported as a named export.
@@ -294,5 +328,3 @@ export const plugins = definePlugins(
   enumConstantsPlugin({ distPath: "./generated/enums.ts" }),
 );
 ```
-
-See [Generators](./generator/index.md) for legacy `defineGenerators()` documentation.