@tailor-platform/sdk 2.22.0 → 2.24.0

package/docs/cli/application.md

@@ -167,12 +167,20 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 - `-` means the resource will be deleted
 - `±` means the resource will be replaced
 
+An update marked `[forced by SDK version]` shows no configuration difference from what is deployed. It is applied again only because resources of this application were last deployed with a different SDK version.
+
 After the detailed list, a summary line is printed:
 
 ```text
 Plan: 5 to create, 3 to update, 1 to delete
 ```
 
+When some updates are forced by the SDK version, the summary line also shows how many:
+
+```text
+Plan: 0 to create, 12 to update (11 forced by SDK version), 0 to delete
+```
+
 Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
 
 ```bash
@@ -189,9 +197,16 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 
 ```json
 {
-  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "summary": { "create": 2, "update": 2, "delete": 0, "replace": 0, "forcedBySdkVersion": 1 },
   "changes": [
-    { "action": "create", "name": "Order", "labels": ["table"], "namespace": "tailordb" }
+    { "action": "create", "name": "Order", "labels": ["table"], "namespace": "tailordb" },
+    {
+      "action": "update",
+      "name": "Customer",
+      "labels": ["table"],
+      "namespace": "tailordb",
+      "forcedBySdkVersion": true
+    }
   ],
   "warnings": [
     { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
@@ -201,15 +216,18 @@ Pass the global `--json` / `-j` flag to get machine-readable output.
 }
 ```
 
-- `summary` — counts of each change type.
-- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `summary` — counts of each change type. `forcedBySdkVersion` counts the updates forced by the SDK version, which are also included in `update`.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`. An update forced by the SDK version also has `forcedBySdkVersion: true`.
 - `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
 - `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
 
 **Apply** (`--json`): writes a JSON object to stdout:
 
 ```json
-{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
+{
+  "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0, "forcedBySdkVersion": 0 },
+  "status": "applied"
+}
 ```
 
 ## remove

package/docs/cli/function.md

@@ -129,9 +129,9 @@ $ tailor function logs <execution-id> --follow
 
 **Notes**
 
-Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running, whereas the flat `logs` string is filled in only after completion. The human-readable view shows the structured entries when present and falls back to `logs` otherwise.
+Execution details include `logEntries`, the structured log lines (message, severity, timestamp) recorded while the function ran. They are available while the execution is still running. The `logs` string joins their messages with newlines.
 
-Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. On environments where no structured entries are returned, `--follow` shows the flat `logs` string once the execution completes. With `--json`, `--follow` waits for completion and then emits the final execution details once.
+Use `--follow` to keep polling a running execution and print new log entries as they arrive until it completes. Polling continues while the execution is suspended at a wait point, and indefinitely unless `--timeout` is set. With `--json`, `--follow` waits for completion and then emits the final execution details once.
 
 When viewing a specific execution that failed, the command displays error details with the stack trace mapped back to your original source files (clickable file links and code snippets, matching `function run` output).
 

package/docs/configuration.md

@@ -25,8 +25,10 @@ export default defineConfig({
   cors: ["https://example.com"],
   allowedIpAddresses: ["192.168.1.0/24"],
   disableIntrospection: false,
-  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
   metadata: { "erp-kit-version": "v1-2-3" },
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 
@@ -58,12 +60,16 @@ export default defineConfig({
 
 Entries are only added or overwritten. An entry removed from the config keeps its last deployed value on the platform, and labels the config does not name are left untouched. Because those retained labels count towards the platform's limit of 20 labels per resource, `deploy` reports the overflow and stops before changing the application when the labels it would leave behind exceed that limit. The labels are written when the application itself is deployed, so a config with no TailorDB, Resolver, IdP, or Auth service has no application to carry them.
 
-**Log Level**: Controls which `console.*` and `logger.*` (from `@tailor-platform/sdk/runtime`) calls are kept when deployment functions are bundled. Supported values are `"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`, and `"SILENT"`. The default is `"DEBUG"` and keeps all calls. `console.log` is treated as a DEBUG-level call (matching the platform's OpenTelemetry severity mapping), so it is dropped at `"INFO"` and above, alongside `console.debug` and `logger.debug`. `logger.setAttributes` has no severity and is never dropped, regardless of `logLevel`. For production deployments, use `"WARN"` to keep warn/error calls while dropping debug, log, and info calls:
+**Build Options**: `buildOptions` groups the settings that control how resolvers, executors, workflow jobs, and other functions are bundled: `logLevel` (below), `inlineSourcemap` (whether bundled functions embed an inline sourcemap for readable error stack traces; default `true`), and `allowedRuntimeGlobals` (see [Node-only globals](#node-only-globals)). The top-level `logLevel` and `inlineSourcemap` fields still work but are deprecated; `tailor upgrade` moves them into `buildOptions`. Setting the same option both at the top level and in `buildOptions` is rejected.
+
+**Log Level** (`buildOptions.logLevel`): 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.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 
@@ -121,6 +127,25 @@ Error [UNRESOLVED_IMPORT]: Could not resolve "@lib/missing" imported from "/path
 
 If the unresolved specifier is a Node.js built-in (e.g. `fs`, `crypto`, `path`), the suggestion explains that it is not available in the Tailor Platform runtime and, where one exists, names a Web-standard replacement (e.g. the Fetch API instead of `http`/`https`).
 
+#### Node-only globals
+
+The Tailor Platform runtime does not define Node-only globals such as `process`, `Buffer`, or `require`. When a bundled resolver, executor, or workflow job references one, the build fails with `FORBIDDEN_RUNTIME_GLOBAL`, naming the global and where it is referenced: the file in your own code, or the installed package (code under `node_modules`). A reference behind a `typeof` check, such as `if (typeof process !== "undefined") { ... }`, is not reported.
+
+You cannot change an installed package's code, and it may reference a global only on a code path your use never reaches. When you have confirmed that, allow the reference with `buildOptions.allowedRuntimeGlobals`, keyed by package name. List the globals to allow, or set `true` to allow all of them, including any the package only starts referencing in a later version. Code in that package that does reach the global throws a `ReferenceError` at runtime:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    allowedRuntimeGlobals: {
+      "@ai-sdk/gateway": ["Buffer"],
+    },
+  },
+});
+```
+
+`buildOptions.allowedRuntimeGlobals` has no effect on your own code. Packages from your own workspace (for example, a pnpm or npm workspace) are bundled from their source directory rather than from `node_modules`, so they count as your own code.
+
 ### 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

@@ -33,9 +33,11 @@ tailor setup ci tag --name my-app-prod \
   --branch main --environment production
 ```
 
-After running the command, follow the **Next steps** printed to the terminal to
-set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
-commit the generated files.
+After running the command, follow the **Next steps** printed to the terminal:
+run `tailor setup ci env` to get the commands that set the secrets and
+variables each GitHub Environment needs (see
+[Setting secrets and variables](#setting-secrets-and-variables)), then commit
+the generated files.
 
 The generated workflow deploys to whichever workspace its
 `TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
@@ -170,10 +172,13 @@ Because the variable is scoped to a GitHub Environment, both the `plan` and
    ```
 
 2. Set the id as the Environment variable (the environment name is your
-   `--environment` value, or the workspace name when omitted):
+   `--environment` value, or the workspace name when omitted).
+   `tailor setup ci env` prints this command together with the other secrets
+   and variables each environment needs (see
+   [Setting secrets and variables](#setting-secrets-and-variables)):
 
    ```bash
-   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env=my-app-stg
    ```
 
 If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
@@ -204,8 +209,9 @@ top-level keys it writes (`name:`, `on:`, and `permissions:` in a workflow; the
 metadata, inputs, and outputs of a composite action). Do not edit or rename
 them. Everything else is yours, and re-running `setup` keeps it:
 
-- **Your own jobs and steps.** Add them anywhere, without the `tailor-` prefix.
-  A step you add inside a managed job stays right after the managed step it
+- **Your own jobs and steps.** Add them anywhere, with an `id` (if any) that
+  does not start with `tailor-`: the prefix is reserved for the SDK, even in a
+  job of your own. A step you add inside a managed job stays right after the managed step it
   followed. For example, add private registry authentication or a system
   dependency _before_ the managed `tailor-setup` step, and post-install extras
   (such as `playwright install`) _after_ it. A job of your own can depend on a
@@ -218,25 +224,63 @@ them. Everything else is yours, and re-running `setup` keeps it:
   `install-command` on `tailor-install`, `node-version-file` on
   `tailor-setup`, `label` on `tailor-plan`, and `user-mapping` on
   `tailor-notify` and on a coordinator's steps that call an app action.
-- **The `run:` command of the `build-site` step** in a composite action.
+- **The `run:` command of the `tailor-build-site` step** in a composite action.
+
+In a preview workflow, the `tailor-preview-deploy` job exposes the per-PR
+workspace as the outputs `workspace-id`, `workspace-name`, and `app-url`, so a
+job of your own can run tests or deploy extra assets against it:
+
+```yaml
+deploy-assets:
+  needs: tailor-preview-deploy
+  runs-on: ubuntu-latest
+  environment: my-app
+  env:
+    TAILOR_PLATFORM_WORKSPACE_ID: ${{ needs.tailor-preview-deploy.outputs.workspace-id }}
+    TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID: ${{ secrets.TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID }}
+    TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET: ${{ secrets.TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET }}
+  steps:
+    # checkout, dependency installation, and your tailor commands
+```
+
+A job that runs `tailor` against the workspace needs the machine-user
+[secrets](#secrets), so it declares the preview target's GitHub Environment
+(the `--environment` value, or the workspace name when omitted) as above. A job
+that only uses `app-url`, such as end-to-end tests, does not.
+
+The job is skipped whenever `tailor-preview-deploy` is skipped: when a pull
+request is closed, for draft and fork pull requests, and for unlabeled ones with
+`--require-preview-label`.
+
+Likewise, the `tailor-deploy` job of a branch or tag workflow exposes the
+deployed workspace as the outputs `workspace-id` and `app-url` to a job with
+`needs: tailor-deploy`. Reading them does not require the target's GitHub
+Environment; a job that runs `tailor` against the workspace declares it for the
+machine-user secrets, as in the preview example above.
 
 Comments above your own jobs and steps and at the end of the file are kept too.
 Comments inside managed jobs and steps, and edits to the header comment, are
 not kept.
 
 `setup check` reports an edit to a managed part, and re-running `setup` stops
-on it. Revert the edit, or pass `--force` to reset the managed parts to the
-current template; `--force` still keeps your own jobs, steps, and settings.
-A managed job or step you renamed counts as your own, so `--force` adds the
-managed one back next to it; rename it back instead of forcing. To start over
-from a clean template, delete the file and re-run `setup`.
+on it; both name the edited job, step, or top-level key. Revert the edit, or
+pass `--force` to reset the managed parts to the current template; `--force`
+still keeps your own jobs, steps, and settings. A managed step you renamed to
+an id without the `tailor-` prefix counts as your own, so `--force` adds the
+managed one back next to it; rename it back instead of forcing. A managed job
+you renamed still holds the SDK's `tailor-` steps, so `setup check` reports
+them as reserved ids and `setup` stops on them, even with `--force`; rename the
+job back. To start over from a clean template, delete the file and re-run
+`setup`.
 
 When a template update removes a managed job that contains steps of yours, or
 a job of yours `needs` a removed job, `setup` stops and names them. Move those
 steps into a job of your own (or update the `needs`) and re-run. `--force` drops
-steps left inside a removed job. It also stops when a new template version adds
-a managed job or step whose id you already use; rename yours, or pass `--force`
-to let the managed one replace it.
+steps left inside a removed job.
+
+`setup check` reports a job or step of yours whose `id` starts with `tailor-`,
+and re-running `setup` stops on it, naming the id. Rename it; `--force` does
+not rename or remove it.
 
 Files generated by an older SDK version are compared as a whole, so the first
 re-run after upgrading stops if you edited the file in any way. Re-run once with
@@ -296,7 +340,8 @@ the move.
 
 ## Secrets
 
-The generated workflow reads two secrets:
+The generated workflow requires two secrets (the optional Slack token is listed in
+[Setting secrets and variables](#setting-secrets-and-variables)):
 
 | Secret                                       | Description                |
 | -------------------------------------------- | -------------------------- |
@@ -304,12 +349,8 @@ The generated workflow reads two secrets:
 | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Machine user client secret |
 
 Set them on the target GitHub Environment (the `--environment` value, or the
-workspace name when omitted) with the GitHub CLI:
-
-```bash
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
-```
+workspace name when omitted); `tailor setup ci env` prints the commands (see
+[Setting secrets and variables](#setting-secrets-and-variables)).
 
 Setting them at the environment level isolates each target's credentials and
 keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
@@ -317,6 +358,62 @@ variable. You can also set them as repository-level secrets if every target
 shares one machine user, but then any workflow on any branch can read them, so
 the environment's protection rules no longer guard your deploys.
 
+### Setting secrets and variables
+
+`tailor setup ci env` reads `.github/tailor.lock` and prints, for every GitHub
+Environment the generated workflows use, the commands that create the
+environment (only when it does not exist yet) and set its secrets and
+variables. It is read-only, so re-run it whenever you add a target. When the
+`origin` remote points at github.com, the output names that repository, so the
+commands work from any directory; otherwise `gh` resolves the repository from
+the current directory and the Terraform output leaves it as a placeholder.
+
+```bash
+tailor setup ci env                          # gh CLI commands (default)
+tailor setup ci env --format terraform       # Terraform for the integrations/github provider
+tailor setup ci env --environment my-app-stg # only one environment (repeat for several)
+```
+
+The list follows what each generated workflow actually reads:
+
+| Name                                         | Kind     | Targets                 | Required | Where the value comes from                                                                                                                                                                                                           |
+| -------------------------------------------- | -------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | secret   | all                     | yes      | Client ID of the platform machine user CI signs in as; it needs an editor or admin role on the organization or folder that holds the workspace. Contact [Tailor support](https://docs.tailor.tech/administration/support) to get one |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | secret   | all                     | yes      | Client secret of the same platform machine user                                                                                                                                                                                      |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | variable | branch, tag, coordinate | yes      | `id` printed by `tailor workspace create`, or listed by `tailor workspace list`                                                                                                                                                      |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`            | variable | preview                 | yes      | Organization to create the per-PR workspaces in (a machine user cannot create a workspace without one): `organizationId` listed by `tailor organization list`                                                                        |
+| `TAILOR_PLATFORM_FOLDER_ID`                  | variable | preview                 | no       | Folder to create the per-PR workspaces in: `id` listed by `tailor organization folder list -o <organization id>`. When unset they go directly under the organization, which needs the machine user's role on the organization itself |
+| `TAILOR_PLATFORM_FAIL_ON_DRIFT`              | variable | all                     | no       | `true` to fail the drift check when it finds drift                                                                                                                                                                                   |
+| `TAILOR_SLACK_BOT_TOKEN`                     | secret   | branch, tag, coordinate | no       | Bot User OAuth Token (`xoxb-...`) of a Slack app with the `chat:write` scope                                                                                                                                                         |
+| `TAILOR_SLACK_CHANNEL_ID`                    | variable | branch, tag, coordinate | no       | Channel ID (`C...`) from the channel details in Slack; invite the bot to the channel                                                                                                                                                 |
+| `TAILOR_SLACK_USER_MAPPING`                  | variable | branch, tag             | no       | JSON object mapping GitHub usernames to Slack member IDs (for example `{"alice":"U0123456"}`) so notifications mention the actor; read only after you uncomment the `user-mapping` input of the `tailor-notify` step                 |
+
+See [Account management](https://docs.tailor.tech/administration/account-management)
+for how organizations, folders, workspaces, and machine users relate.
+
+Composite actions (`setup ci action`) read nothing themselves; the coordinator
+that calls them does. Set `TAILOR_SLACK_BOT_TOKEN` and `TAILOR_SLACK_CHANNEL_ID`
+together to enable Slack deploy notifications.
+
+The `gh` output creates an environment only when GitHub reports it missing and
+leaves optional entries commented out. Run the commands one at a time: each
+`gh secret set` / `gh variable set` prompts for its value.
+
+The Terraform output takes every value from an input variable (secrets are
+`sensitive`) and creates an optional entry only when its variable is set, so no
+value is written to the output. Terraform still stores the secret values in its
+state in plain text, so keep the state encrypted and access-restricted, or set
+the secrets with the `gh` output instead. Its header lists the steps with the variable
+names for your environments: authenticate the provider, put non-secret values in
+`terraform.tfvars`, pass secrets as `TF_VAR_<name>` environment variables, and
+import each environment and variable that already exists (for example
+`terraform import github_repository_environment.production my-repo:production`)
+before `terraform apply`: creating a variable that already exists fails, while
+secrets are overwritten. The generated environments ignore changes to their
+protection settings (reviewers, wait timer, branch policy), so importing an
+environment keeps the approval gate you configured; remove the `lifecycle` block
+to manage those settings in Terraform instead.
+
 ## GitHub Environments (approval gate)
 
 Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
@@ -453,18 +550,13 @@ tailor setup ci tag --name my-app-prod \
   --branch main --environment production
 ```
 
-Then provision each workspace and set its id on the matching environment (the
-staging target's environment defaults to `my-app-stg`; production uses
-`production`):
+Then provision each workspace and set its id and the machine-user credentials
+on the matching environment (the staging target's environment defaults to
+`my-app-stg`; production uses `production`). `tailor setup ci env` prints the
+commands for both environments:
 
 ```bash
-gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
-
-gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env production
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env production
-gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
+tailor setup ci env
 ```
 
 Commit both workflow files and `.github/tailor.lock`.
@@ -502,19 +594,21 @@ them. To remove it, delete the file.
 
 Renovate updates the SDK dependency and action pins, but it does not regenerate
 the workflow template. After an SDK update, `tailor setup check` reports a
-template-version warning until you re-run the relevant workflow setup
-subcommand.
+template-version warning until you run
+[`tailor setup update`](#updating-the-generated-workflow).
 
 ## Checking for drift
 
 `tailor setup check` audits the workflows recorded in
 `.github/tailor.lock` against your current config and repository, without
 writing anything. It reports when a workflow file is missing or its SDK-managed
-parts were edited by hand, a
-newer template is available, `tailor.config.ts` is no longer under the recorded
+parts were edited by hand, a job or step of yours uses the reserved `tailor-`
+prefix, a newer template is available, `tailor.config.ts` is no longer under the recorded
 `--dir`, or the repository default branch no longer matches a branch target's
 trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
-finding names a stable rule key for future suppression.
+finding names a stable rule key for future suppression. Run
+[`tailor setup update`](#updating-the-generated-workflow) to regenerate the
+targets it reports.
 
 Workflows generated by `setup ci branch`, `setup ci tag`, `setup ci preview`, and
 `setup ci coordinate` self-audit: each contains a `tailor-drift-check` step that
@@ -529,21 +623,42 @@ Drift findings are advisory by default. Set the repository variable
 `TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
 the job. Execution and configuration errors fail regardless of this variable.
 
-Running `check` on your own machine also verifies that
-`TAILOR_PLATFORM_WORKSPACE_ID` is set locally for any branch, tag, or
-coordinate target, since those workflows read it directly. `check` detects on
-its own when it is running in CI (no flag needed) and skips that local-only
-verification there, since the deploy job resolves the Environment variable
-itself at runtime.
+`check` compares only the generated files, `.github/tailor.lock`, and the
+config; it does not read the GitHub Environment secrets and variables, so it
+runs the same on your own machine and in CI. Run `tailor setup ci env` to list
+what each environment needs.
 
 ## Updating the generated workflow
 
-When you upgrade the SDK, re-run the relevant workflow setup subcommand with
-the same flags to pick up template improvements. Your own jobs, steps, and
-settings are kept (see
-[Customizing the generated workflow](#customizing-the-generated-workflow)). If
-you edited a managed part, the command stops; revert the edit or pass `--force`
-to reset it.
+When you upgrade the SDK, run `tailor setup update` from the repository root to
+pick up template improvements:
+
+```bash
+tailor setup update
+```
 
-The `.github/tailor.lock` file records the flags used at generation time,
-so you can check what arguments were used previously.
+It regenerates every workflow and composite action recorded in
+`.github/tailor.lock` with the flags each one was generated with, so you do not
+have to re-type `setup ci branch`, `setup ci tag`, and the rest one by one.
+Your own jobs, steps, and settings are kept (see
+[Customizing the generated workflow](#customizing-the-generated-workflow)). A
+branch that was detected from the repository default branch is detected again,
+and the parts that follow your config — the migration drift check, seed
+validation, static website builds, and ERD preview namespaces — are derived
+from the current `tailor.config.ts`.
+
+A target that cannot be regenerated, for example because you edited a managed
+part, does not stop the others: `update` regenerates the rest, then lists the
+targets it could not update and exits non-zero. Revert the edit, or run
+`tailor setup update --force` to reset the managed parts of every target.
+
+Coordinators generated by an older plugin version did not record how their
+`--action` values were grouped, so `update` lists them instead of guessing
+which apps deploy together. Re-run `tailor setup ci coordinate` once with all
+of its original flags and its original `--action` groups. The message `update`
+prints fills in the recorded flags (`--tag`, `--branch`, `--environment`,
+`--restrict-dispatch`), so you only add the `--action` values. Later updates
+pick the grouping up from the lock.
+
+To change a flag for one target, re-run its `setup ci` subcommand with the new
+flags. `.github/tailor.lock` records them, and later updates reuse them.

package/docs/migration/v3.md

@@ -128,6 +128,52 @@ property, which is the relation's cardinality (e.g. "n-1", "1-1",
 
 </details>
 
+## defineConfig inlineSourcemap / logLevel → buildOptions
+
+**Migration:** Partially automatic
+
+Move the top-level `inlineSourcemap` and `logLevel` of `defineConfig()` into `buildOptions`, which groups the settings that control how functions are bundled. The top-level fields keep working until they are removed in v3; setting the same option in both places is rejected.
+
+Before:
+
+```ts
+export default defineConfig({
+  name: "my-app",
+  inlineSourcemap: false,
+  logLevel: "WARN",
+});
+```
+
+After:
+
+```ts
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    inlineSourcemap: false,
+    logLevel: "WARN",
+  },
+});
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v3, the top-level `inlineSourcemap` and `logLevel` options of
+`defineConfig()` from `@tailor-platform/sdk` are removed in favor of
+`buildOptions.inlineSourcemap` and `buildOptions.logLevel`. For each flagged
+config, move those two properties into a `buildOptions` object (create it if
+it does not exist) without changing their values. When the config is built
+from a variable or a spread, move them in the object that actually defines
+them. If an option is set both at the top level and in `buildOptions`, keep
+the value that the deployed app should use and delete the other; the build
+rejects a config that sets both. Leave `logLevel` options of other tools
+(for example a Vite or Vitest config) unchanged.
+```
+
+</details>
+
 ## String file uploads → explicit encoding
 
 **Migration:** Manual

package/docs/multi-environment.md

@@ -64,7 +64,9 @@ tailor deploy -w <production-workspace-id> --env-file .env.production
 ```typescript
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 

package/docs/services/workflow.md

@@ -516,6 +516,9 @@ You can start a workflow execution from a resolver using `workflow.start()`.
 
 - `workflow.start(args, options?)` returns a workflow run ID (`Promise<string>`).
 - To run with machine-user permissions, pass `{ invoker: "<machine-user>" }`. The name is type-narrowed to the machine users defined in your auth config.
+- Import the workflow from its workflow file with a default import (or a namespace import, calling `wf.default.start(...)`), using a relative path or a `tsconfig.json` `paths` alias. The build replaces the `.start()` call with a platform call, so it has to recognize the workflow: export it as the file's default export — either `createWorkflow({ name: "..." })` itself or the result of a helper function that calls `createWorkflow()`.
+- Call `.start()` directly on the imported name (`orderProcessingWorkflow.start(...)`, or `wf.default.start(...)` for a namespace import). If you first assign the workflow to another variable (`const wf = orderProcessingWorkflow; wf.start(...)`) or pass it to a function, the call is neither rewritten nor checked, and fails at runtime.
+- If a `.start()` call is made on an export of a workflow file that the build cannot recognize as a workflow or job defined that way, the build fails. A `.start()` on a workflow imported from anywhere other than a workflow file (for example re-exported from a shared package) cannot be checked, and fails at runtime.
 
 ```typescript
 import { createResolver, t } from "@tailor-platform/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.22.0",
+  "version": "2.24.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -166,8 +166,8 @@
     "@opentelemetry/semantic-conventions": "1.43.0",
     "@oxc-project/types": "0.151.0",
     "@politty/zod": "0.3.0",
-    "@secretlint/core": "13.0.5",
-    "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+    "@secretlint/core": "13.0.6",
+    "@secretlint/secretlint-rule-preset-recommend": "13.0.6",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
     "@toiroakr/lines-db": "0.13.0",
@@ -191,7 +191,7 @@
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
     "pkg-types": "2.3.3",
-    "rolldown": "1.2.9",
+    "rolldown": "1.2.11",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",
     "std-env": "4.2.0",
@@ -208,14 +208,14 @@
     "@tailor-platform/shared": "^0.0.0",
     "@tailor-platform/tailor-proto": "^0.0.1",
     "@types/mime-types": "3.0.1",
-    "@types/node": "24.13.6",
+    "@types/node": "24.19.0",
     "@types/semver": "7.8.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "5.0.1",
     "eslint-plugin-zod": "4.14.2",
     "oxfmt": "0.70.0",
     "oxlint": "1.85.0",
-    "oxlint-tsgolint": "7.0.2002",
+    "oxlint-tsgolint": "7.0.2003",
     "sonda": "0.14.0",
     "tsdown": "0.23.0",
     "typescript": "6.0.3",

package/dist/application-BE4vehXW.mjs

@@ -1 +0,0 @@
-import{n as e,t}from"./application-BzO9ywXQ.mjs";export{t as defineApplication,e as generatePluginFilesIfNeeded};