@tailor-platform/sdk 2.0.0-next.5 → 2.0.0-next.7

package/docs/cli/application.md

@@ -38,10 +38,9 @@ tailor generate [options]
 
 **Options**
 
-| Option              | Alias | Description                                    | Required | Default              |
-| ------------------- | ----- | ---------------------------------------------- | -------- | -------------------- |
-| `--config <CONFIG>` | `-c`  | Path to SDK config file                        | No       | `"tailor.config.ts"` |
-| `--watch`           | `-W`  | Watch for type/resolver changes and regenerate | No       | `false`              |
+| Option              | Alias | Description             | Required | Default              |
+| ------------------- | ----- | ----------------------- | -------- | -------------------- |
+| `--config <CONFIG>` | `-c`  | Path to SDK config file | No       | `"tailor.config.ts"` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -57,19 +56,66 @@ tailor deploy [options]
 
 **Options**
 
-| Option                          | Alias | Description                                                                          | Required | Default              | Env                               |
-| ------------------------------- | ----- | ------------------------------------------------------------------------------------ | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
-| `--config <CONFIG>`             | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
-| `--dry-run`                     | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
-| `--no-schema-check`             | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
-| `--no-validate`                 | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
-| `--no-cache`                    | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
-| `--clean-cache`                 | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
+| Option                                  | Alias | Description                                                                          | Required | Default              | Env                               |
+| --------------------------------------- | ----- | ------------------------------------------------------------------------------------ | -------- | -------------------- | --------------------------------- |
+| `--workspace-id <WORKSPACE_ID>`         | `-w`  | Workspace ID                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
+| `--profile <PROFILE>`                   | `-p`  | Workspace profile                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
+| `--config <CONFIG>`                     | `-c`  | Path to SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                                 | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
+| `--create-workspace`                    | -     | Create a workspace when the account has none                                         | No       | -                    | -                                 |
+| `--workspace-name <WORKSPACE_NAME>`     | -     | Name for a workspace created during deploy                                           | No       | -                    | -                                 |
+| `--workspace-region <WORKSPACE_REGION>` | -     | Region for a workspace created during deploy                                         | No       | -                    | -                                 |
+| `--organization-id <ORGANIZATION_ID>`   | -     | Organization ID for a workspace created during deploy                                | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`               | -     | Folder ID for a workspace created during deploy                                      | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--dry-run`                             | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
+| `--no-schema-check`                     | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
+| `--no-validate`                         | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
+| `--no-cache`                            | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
+| `--clean-cache`                         | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Workspace Selection:**
+
+After validating the configuration file, `deploy` resolves a workspace before bundling the
+application. Explicit configuration takes precedence in this order: `--workspace-id`,
+`TAILOR_PLATFORM_WORKSPACE_ID`, and the selected profile. Otherwise, `deploy` reuses the workspace
+previously selected for that configuration from project-local state. Each config file keeps an
+independent selection, including when multiple configs share a directory. An explicit workspace also
+updates this selection. Saved selections are verified against the workspaces currently visible to
+the authenticated user before reuse, and `deploy` warns when it uses one.
+
+When the project has no saved selection, `deploy` discovers the account's workspaces:
+
+- One or more workspaces open a selection prompt in an interactive terminal, with an option to
+  create a new workspace. With one workspace in non-interactive or JSON mode, it is selected
+  automatically. With multiple workspaces, pass `--workspace-id` instead.
+- No workspaces open a guided creation flow in an interactive terminal. The flow asks for a name,
+  fetches the available regions from the Platform, and confirms before creating anything. After
+  creation, the output shows how to reuse the workspace with `--workspace-id` or
+  `TAILOR_PLATFORM_WORKSPACE_ID` from CI or another machine.
+
+In CI and other non-interactive environments, workspace creation must be explicit:
+
+```bash
+tailor-sdk deploy \
+  --create-workspace \
+  --workspace-name example-workspace \
+  --workspace-region us-west
+```
+
+`--create-workspace` only creates when the account has no workspace. If the existing workspace
+matches the requested name, region, organization, and folder, `deploy` reuses it so the same command
+is safe to rerun. If multiple workspaces exist, the flag never creates another one or guesses which
+workspace to use. `--yes` skips deployment confirmation but does not authorize workspace creation.
+
+If a saved workspace has been deleted or is no longer accessible, interactive terminals return to
+workspace selection. Non-interactive environments stop with `WORKSPACE_CONTEXT_STALE` instead of
+silently switching to another workspace. Automatically selected targets are printed with their
+region, organization, and workspace ID.
+
+`--dry-run` never creates a workspace or writes project context. When an account has no workspace,
+create one explicitly before requesting a deployment plan.
+
 **Config File Modification:**
 
 On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.
@@ -84,6 +130,8 @@ tailor deploy --config apps/buyer/tailor.config.ts,apps/supplier/tailor.config.t
 
 When multiple configs are provided, `deploy` creates or updates all configured services first, then updates the applications. This lets one application reference resources owned by another config with `external: true` during the same deploy.
 
+Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).
+
 **Migration Handling:**
 
 When migrations are configured (`db.tailordb.migration` in config), the `deploy` command automatically:

package/docs/cli/function.md

@@ -178,5 +178,5 @@ You can pass either a source file (`.ts`) or a pre-bundled file (`.js`).
 When a `.js` file is provided, detection and bundling are skipped and the file is executed as-is.
 
 > [!WARNING]
-> Workflow job `.trigger()` calls do not work in test-run mode.
-> Triggered jobs are not executed; only the target job's `body` function runs in isolation.
+> Workflow job `.start()` calls do not work in test-run mode.
+> Started jobs are not executed; only the target job's `body` function runs in isolation.

package/docs/cli/tailordb.md

@@ -16,11 +16,10 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                                     | Description                                                               |
-| ------------------------------------------- | ------------------------------------------------------------------------- |
-| [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables.                       |
-| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                                        |
-| [`tailordb erd`](#tailordb-erd)             | Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta) |
+| Command                                     | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables. |
+| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                  |
 
 ### tailordb truncate
 
@@ -232,142 +231,11 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 ### tailordb erd
 
-Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta)
-
-**Usage**
-
-```
-tailor tailordb erd <command>
-```
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Commands**
-
-| Command                                       | Description                                                       |
-| --------------------------------------------- | ----------------------------------------------------------------- |
-| [`tailordb erd export`](#tailordb-erd-export) | Export TailorDB ERD static viewer from local TailorDB schema.     |
-| [`tailordb erd diff`](#tailordb-erd-diff)     | Render TailorDB ERD schema diff HTML from exported ERD viewers.   |
-| [`tailordb erd serve`](#tailordb-erd-serve)   | Generate and serve TailorDB ERD locally with watch reload. (beta) |
-| [`tailordb erd deploy`](#tailordb-erd-deploy) | Deploy ERD static website for TailorDB namespace(s).              |
-
-#### tailordb erd export
-
-Export TailorDB ERD static viewer from local TailorDB schema.
-
-**Usage**
-
-```
-tailor tailordb erd export [options]
-```
-
-**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`  | TailorDB namespace name (optional if only one namespace is defined in config)                  | No       | -                    | -                    |
-| `--output <OUTPUT>`       | `-o`  | Output directory path for TailorDB ERD viewer files (writes to `<outputDir>/<namespace>/dist`) | No       | `".tailor/erd"`      | -                    |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd diff
-
-Render TailorDB ERD schema diff HTML from exported ERD viewers.
-
-**Usage**
-
-```
-tailor tailordb erd diff [options]
-```
-
-**Options**
-
-| Option                        | Alias | Description                                                             | Required | Default |
-| ----------------------------- | ----- | ----------------------------------------------------------------------- | -------- | ------- |
-| `--base-html <BASE_HTML>`     | -     | Base ERD viewer HTML file                                               | No       | -       |
-| `--head-html <HEAD_HTML>`     | -     | Head ERD viewer HTML file                                               | No       | -       |
-| `--namespace <NAMESPACE>`     | `-n`  | TailorDB namespace name (defaults to the provided ERD schema namespace) | No       | -       |
-| `--output <OUTPUT>`           | `-o`  | Output ERD diff HTML file                                               | Yes      | -       |
-| `--output-json <OUTPUT_JSON>` | -     | Optional output JSON file for the computed diff                         | No       | -       |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd serve
-
-Generate and serve TailorDB ERD locally with watch reload. (beta)
-
-**Usage**
-
-```
-tailor tailordb erd serve [options]
-```
-
-**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`  | TailorDB namespace name (uses first namespace in config if not specified) | No       | -                    | -                    |
-| `--port <PORT>`           | -     | Local server port (0 selects a free port)                                 | No       | `0`                  | -                    |
-| `--open`                  | -     | Open the ERD viewer in the default browser                                | No       | `false`              | -                    |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd deploy
-
-Deploy ERD static website for TailorDB namespace(s).
-
-**Usage**
-
-```
-tailor tailordb erd deploy [options]
-```
-
-**Options**
-
-| Option                          | Alias | Description                                                                         | Required | Default              | Env                            |
-| ------------------------------- | ----- | ----------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                        | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                                   | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`             | `-c`  | Path to Tailor config file                                                          | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--namespace <NAMESPACE>`       | `-n`  | TailorDB namespace name (optional - deploys all namespaces with erdSite if omitted) | No       | -                    | -                              |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Notes:**
-
-- ERD commands build from the local TailorDB schema, including plugin-generated TailorDB types.
-- `tailordb erd export` writes a self-contained `index.html` viewer to `<output>/<namespace>/dist`.
-- `tailordb erd diff` compares exported self-contained viewer HTML files and writes a visual ERD viewer that can switch between the current schema and the highlighted diff.
-- `tailordb erd serve` watches the config file and TailorDB type files, then reloads the browser viewer when the rebuilt `index.html` reports a new embedded schema revision.
-- `tailordb erd deploy` still requires `erdSite` in `tailor.config.ts` because it uploads the generated viewer to a configured Static Website.
-
-**Usage Examples:**
+The `tailordb erd` commands (export, diff, serve, deploy) are provided by the `@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin. Install it next to the SDK and keep running `tailor tailordb erd <command>` as before:
 
 ```bash
-# Deploy ERD for all namespaces with erdSite configured
-tailor tailordb erd deploy
-
-# Deploy ERD for a specific namespace
-tailor tailordb erd deploy --namespace myNamespace
-
-# Deploy ERD with JSON output
-tailor tailordb erd deploy --json
+npm install -D @tailor-platform/sdk-plugin-tailordb-erd@next
+tailor tailordb erd export --namespace myNamespace
 ```
 
-**Notes:**
-
-- This command is a beta feature and may introduce breaking changes in future releases
-- Requires `erdSite` to be configured in `tailor.config.ts` for each namespace you want to deploy
-- Example config:
-  ```typescript
-  export default defineConfig({
-    db: {
-      myNamespace: {
-        // ... table definitions
-        erdSite: "my-erd-site-name",
-      },
-    },
-  });
-  ```
+See the plugin's README for the full command reference.

package/docs/cli/workspace.md

@@ -106,6 +106,7 @@ tailor workspace create [options]
 | `--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"` | -                                 |
 
@@ -161,10 +162,11 @@ tailor workspace list [options]
 
 **Options**
 
-| Option            | Alias | Description                                              | Required | Default  |
-| ----------------- | ----- | -------------------------------------------------------- | -------- | -------- |
-| `--order <ORDER>` | -     | Sort order (asc or desc)                                 | No       | `"desc"` |
-| `--limit <LIMIT>` | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        |
+| Option                | Alias | Description                                                      | Required | Default  | Env                       |
+| --------------------- | ----- | ---------------------------------------------------------------- | -------- | -------- | ------------------------- |
+| `--order <ORDER>`     | -     | Sort order (asc or desc)                                         | No       | `"desc"` | -                         |
+| `--limit <LIMIT>`     | `-l`  | Maximum number of items to return (0 or omit: unlimited)         | No       | -        | -                         |
+| `--profile <PROFILE>` | -     | Workspace profile used for authentication and Platform selection | No       | -        | `TAILOR_PLATFORM_PROFILE` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli-reference.md

@@ -28,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
 
@@ -117,7 +120,9 @@ tailor hello world --loud
 ```
 
 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`:
+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
@@ -133,6 +138,9 @@ 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.
 
 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
@@ -195,11 +203,6 @@ Commands for managing TailorDB tables, data, and schema migrations.
 | [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](./cli/tailordb.md#tailordb-erd)                               | Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta)                                                 |
-| [tailordb erd export](./cli/tailordb.md#tailordb-erd-export)                 | Export TailorDB ERD static viewer from local TailorDB schema.                                                             |
-| [tailordb erd diff](./cli/tailordb.md#tailordb-erd-diff)                     | Render TailorDB ERD schema diff HTML from exported ERD viewers.                                                           |
-| [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).                                                                      |
 
 ### [Query Commands](./cli/query.md)
 

package/docs/configuration.md

@@ -82,6 +82,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.

package/docs/github-actions.md

@@ -72,6 +72,14 @@ to pull requests:
 tailor setup -n my-app-stg --erd-preview
 ```
 
+The generated workflow runs `tailor tailordb erd`, which is provided by the
+`@tailor-platform/sdk-plugin-tailordb-erd` CLI plugin — install it as a
+dev-dependency in your project:
+
+```bash
+npm install -D @tailor-platform/sdk-plugin-tailordb-erd@next
+```
+
 The generated workflow builds one self-contained ERD viewer HTML file for each
 owned TailorDB namespace in `tailor.config.ts`. The viewer compares the pull
 request merge result with the base branch, can switch between the current schema

package/docs/migration/v2.md

@@ -350,7 +350,7 @@ Do not change behavior beyond the auth.invoker() removal.
 
 **Migration:** Partially automatic
 
-Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker("name")` there with the bare `"name"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.trigger()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
+Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker("name")` there with the bare `"name"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.start()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
 
 Before:
 
@@ -378,8 +378,8 @@ For each remaining auth.invoker(<expr>) call:
    machine user name string; platform/runtime authInvoker payloads still expect
    the object form.
 2. Rename remaining authInvoker option keys to invoker only for SDK resolver,
-   executor, workflow.trigger(), or startWorkflow() options. Keep platform/runtime
-   payload keys such as tailor.workflow.triggerWorkflow(..., { authInvoker: ... }).
+   executor, workflow.start(), or startWorkflow() options. Keep platform/runtime
+   payload keys such as tailor.workflow.startWorkflow(..., { authInvoker: ... }).
 3. After removing every auth.invoker usage in a file, delete the now-unused auth
    import (keeping it pulls Node-only config modules into runtime bundles); leave
    the import if auth is still referenced elsewhere.
@@ -694,6 +694,73 @@ export const { approval } = createWaitPoints((define) => ({
 }));
 ```
 
+## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/startJobFunction/resumeWorkflowExecution
+
+**Migration:** Partially automatic
+
+Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/startJobFunction/resumeWorkflowExecution names, on both the ambient tailor.workflow global and a workflow value imported from @tailor-platform/sdk/runtime(/workflow). For a renamed triggerWorkflow call, also renames a literal `invoker` option key to `authInvoker` — startWorkflow's options expect the platform shape directly, unlike the removed triggerWorkflow wrapper, which converted invoker to authInvoker internally.
+
+Before:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+await workflow.triggerWorkflow("myWorkflow", { data: "value" });
+```
+
+After:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+await workflow.startWorkflow("myWorkflow", { data: "value" });
+```
+
+A literal invoker option is renamed to authInvoker:
+
+Before:
+
+```ts
+await workflow.triggerWorkflow("myWorkflow", { data: "value" }, { invoker: myInvoker });
+```
+
+After:
+
+```ts
+await workflow.startWorkflow("myWorkflow", { data: "value" }, { authInvoker: myInvoker });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The pre-alignment tailor.workflow names triggerWorkflow, triggerJobFunction, and
+resumeWorkflow are removed from the SDK's type surface in v2; use the canonical
+startWorkflow, startJobFunction, and resumeWorkflowExecution names instead. The
+codemod rewrites direct member-access call sites on the ambient tailor.workflow
+global and on a workflow value imported from @tailor-platform/sdk/runtime or
+@tailor-platform/sdk/runtime/workflow (including aliased imports). It skips a
+file entirely when a local declaration shadows the workflow import or the
+ambient tailor name, to avoid rewriting an unrelated same-named value — review
+those manually.
+
+For a renamed triggerWorkflow call, the codemod also renames a literal invoker
+option key (including shorthand { invoker }) to authInvoker, since startWorkflow
+expects the platform's authInvoker shape directly while triggerWorkflow's removed
+wrapper converted invoker to authInvoker internally.
+
+Also review, and migrate by hand:
+- Destructured references (e.g. const { triggerWorkflow } = workflow) — the
+  codemod only rewrites direct member-access calls.
+- Imported TriggerWorkflowOptions / TriggerJobFunctionOptions types — rename
+  them to StartWorkflowOptions / StartJobFunctionOptions.
+- An invoker option passed via a variable or spread (not a literal object) —
+  the codemod only inspects literal object arguments; rename the invoker key
+  to authInvoker in the options object's own definition.
+```
+
+</details>
+
 ## openDownloadStream → downloadStream
 
 **Migration:** Manual
@@ -787,18 +854,18 @@ string literals.
 
 </details>
 
-## Workflow .trigger() and trigger tests
+## Workflow job start() and start tests
 
 **Migration:** Manual
 
-Workflow job `.trigger()` now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock trigger responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `triggeredJobs`), or use `runWorkflowLocally()` for a full-chain local run.
+Workflow job `.start()` (previously `.trigger()`) now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock start responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `startedJobs`), or use `runWorkflowLocally()` for a full-chain local run.
 
 Tests must mock the workflow runtime instead of running bodies locally:
 
 Before:
 
 ```ts
-const result = await orderJob.trigger({ id });
+const result = await orderJob.start({ id });
 expect(result.status).toBe("done");
 ```
 
@@ -807,7 +874,7 @@ After:
 ```ts
 using wf = mockWorkflow();
 wf.setJobHandler((jobName) => (jobName === "order-job" ? { status: "done" } : null));
-const result = await orderJob.trigger({ id });
+const result = await orderJob.start({ id });
 expect(result.status).toBe("done");
 ```
 
@@ -815,11 +882,57 @@ expect(result.status).toBe("done");
 <summary>Prompt for an AI agent (to perform this migration)</summary>
 
 ```text
-Workflow job .trigger() now uses the platform workflow runtime instead of running
+Workflow job .start() now uses the platform workflow runtime instead of running
 the job body locally. In tests, acquire `using wf = mockWorkflow()` and provide
-trigger responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a
-full-chain local run; an unmocked trigger now throws. Outside tests, treat the
-trigger result as the job output directly (no Promise wrapper to unwrap).
+start responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a
+full-chain local run; an unmocked start now throws. Outside tests, treat the
+start result as the job output directly (no Promise wrapper to unwrap).
+```
+
+</details>
+
+## Workflow.trigger()/WorkflowJob.trigger() → .start()
+
+**Migration:** Manual
+
+Rename `Workflow.trigger()` (returned by `createWorkflow()`) and `WorkflowJob.trigger()` (returned by `createWorkflowJob()`) to `.start()`, aligning the SDK's ergonomic verb with the platform's `start*` RPC vocabulary. No codemod ships for this rename: distinguishing a workflow/job `.trigger()` call from an unrelated object's own `.trigger()` method requires resolving the receiver back to a `createWorkflow`/`createWorkflowJob` result across files, which the SDK's own CLI bundler already does for build-time rewriting. Reusing that logic in a standalone script is a nontrivial lift, and — unlike the bundler, which fails loudly when it cannot rewrite a call — a codemod false positive would silently rewrite an unrelated `.trigger()` call with no error. For the call-site volume this rename typically involves, manual review guided by the prompt below is the safer trade-off.
+
+Before:
+
+```ts
+const inventory = checkInventory.trigger({ orderId: input.orderId });
+const workflowRunId = await orderProcessingWorkflow.trigger(args, { invoker: "manager" });
+```
+
+After:
+
+```ts
+const inventory = checkInventory.start({ orderId: input.orderId });
+const workflowRunId = await orderProcessingWorkflow.start(args, { invoker: "manager" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+In Tailor SDK v2, the ergonomic .trigger() method on a createWorkflow() or
+createWorkflowJob() result is renamed to .start(). This is unrelated to the
+separate tailor.workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow removal
+(see the workflow-trigger-rename codemod) — this rename targets the SDK's own
+ergonomic wrapper, not the low-level platform call.
+
+For each flagged `.trigger(` call in these files:
+1. Confirm the receiver is a workflow or job object — typically a local const
+   assigned from createWorkflow(...)/createWorkflowJob(...), a named import of one,
+   or the default import of a workflow module. Skip receivers that are unrelated
+   objects with their own .trigger() method (state machines, event emitters, etc.).
+2. Rename the call from .trigger(...) to .start(...); the argument list is unchanged.
+3. Update any mock/test code that reads WorkflowJob['trigger'] / Workflow['trigger']
+   as a type, or that mocks the ergonomic method via a wrapper — for example,
+   `wf.job(definition)` / `wf.workflow(definition)` from mockWorkflow() now return a
+   mock of the `.start` method.
+4. Update prose/docs/comments that say "trigger the workflow/job" to "start" only
+   where they describe this SDK verb specifically, not unrelated event terminology.
 ```
 
 </details>
@@ -1031,6 +1144,47 @@ Migration steps for each `.hooks()` call on a `db.type()`:
 
 </details>
 
+## generate --watch flag removed
+
+**Migration:** Manual
+
+Review and remove `tailor generate --watch` / `-W` invocations and the `watch` option on `GenerateOptions`. The flag, its dependency watcher, and the self-restart-on-change logic are removed; `generate` now always performs a single generation pass.
+
+The --watch/-W flag no longer exists; re-run generate after each change:
+
+Before:
+
+```sh
+tailor generate --watch
+```
+
+After:
+
+```sh
+tailor generate
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Tailor SDK v2 removes the `generate --watch` (`-W`) flag along with the
+dependency watcher and self-restart logic that powered it. `tailor generate`
+now always runs a single generation pass and exits.
+
+For each flagged `tailor generate ... --watch` / `-W` invocation (package.json
+scripts, shell scripts, CI configs, or docs), drop the flag and re-run
+`tailor generate` after each change instead. If automatic regeneration on file
+change is still needed, wrap the command with a general-purpose file watcher
+(e.g. `chokidar-cli`, `nodemon`) at the project level.
+
+For programmatic use of `generate()` from `@tailor-platform/sdk/cli`, remove the
+`watch` field from the `GenerateOptions` argument — the function now performs a
+single generation pass and resolves once it completes.
+```
+
+</details>
+
 ## Behavioral changes (no migration required)
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.
@@ -1050,3 +1204,7 @@ The CLI stores human users by their stable subject ID instead of email (email is
 ### Node.js minimum version raised to 22.15.0
 
 v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. No source change is required; ensure your environment runs Node.js 22.15.0+.
+
+### Legacy bundle artifact cleanup removed from deploy
+
+`tailor deploy` no longer deletes on-disk bundle artifacts (`.entry.js` files, workflow-job bundles, and the `hooks-validate-scripts/` directory) left in the SDK output directory (`.tailor` by default) by SDK versions that predate the current in-memory bundling approach. Current bundlers no longer write these files. No source change is required; if such stale files remain from a very old SDK version, delete only those specific files/directories manually — do not delete the output directory itself, since it also holds deploy state (e.g. `secrets-state/`, `*.context.json`) that existing secrets and Auth Connections depend on.