@tailor-platform/sdk 2.0.0-next.9 → 2.0.1

package/docs/migration/v2.md

@@ -97,7 +97,7 @@ npx tailor-sdk-skills
 After:
 
 ```sh
-tailor skills add
+npx @tailor-platform/sdk skills add
 ```
 
 <details>
@@ -107,7 +107,10 @@ tailor skills add
 The standalone tailor-sdk-skills binary is removed in v2; call the skills add
 subcommand on the main tailor CLI instead. Replace any remaining
 tailor-sdk-skills invocations the codemod did not rewrite with
-`tailor skills add`.
+`tailor skills add`, or `npx @tailor-platform/sdk skills add` when the
+invocation runs through a package runner (npx, bunx, pnpm/yarn dlx, npm exec)
+— those resolve a package name, and `npx tailor` reaches an unrelated
+`tailor` package on npm.
 ```
 
 </details>
@@ -668,6 +671,70 @@ already pass a plain value unchanged.
 
 </details>
 
+## defineIdp publishUserEvents → publishEvents
+
+**Migration:** Partially automatic
+
+Rename the `defineIdp` option `publishUserEvents` to `publishEvents`, matching the field name TailorDB types, resolvers, and workflows already use.
+
+Before:
+
+```ts
+import { defineIdp } from "@tailor-platform/sdk";
+
+export const idp = defineIdp("my-idp", {
+  clients: ["my-client"],
+  publishUserEvents: true,
+});
+```
+
+After:
+
+```ts
+import { defineIdp } from "@tailor-platform/sdk";
+
+export const idp = defineIdp("my-idp", {
+  clients: ["my-client"],
+  publishEvents: true,
+});
+```
+
+A shorthand option keeps reading the same local:
+
+Before:
+
+```ts
+defineIdp("my-idp", { clients, publishUserEvents });
+```
+
+After:
+
+```ts
+defineIdp("my-idp", { clients, publishEvents: publishUserEvents });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2, the IdP option `publishUserEvents` is renamed to
+`publishEvents`, so all four services that publish events use one field name.
+The codemod rewrites the option key on `defineIdp` calls whose callee resolves
+to the SDK export, including aliased and namespace imports, and rewrites a
+shorthand `{ publishUserEvents }` to `{ publishEvents: publishUserEvents }` so
+it keeps reading the same local.
+
+Also review, and migrate by hand:
+- An options object built in a variable or spread into the call — the codemod
+  only rewrites object literals passed directly to `defineIdp`.
+- A computed key (e.g. `[key]: value`) that resolves to `publishUserEvents`.
+- Type annotations or interfaces that declare the option themselves.
+- A file where a local declaration shadows the `defineIdp` import; the codemod
+  skips it because the call may not be the SDK export.
+```
+
+</details>
+
 ## defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints
 
 **Migration:** Partially automatic
@@ -694,11 +761,11 @@ export const { approval } = createWaitPoints((define) => ({
 }));
 ```
 
-## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/startJobFunction/resumeWorkflowExecution
+## workflow.triggerWorkflow/triggerJobFunction/resumeWorkflow → startWorkflow/execJobFunction/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.
+Rename tailor.workflow call sites from the pre-alignment triggerWorkflow/triggerJobFunction/resumeWorkflow names to the canonical startWorkflow/execJobFunction/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:
 
@@ -736,7 +803,7 @@ await workflow.startWorkflow("myWorkflow", { data: "value" }, { authInvoker: myI
 ```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
+startWorkflow, execJobFunction, 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
@@ -753,7 +820,7 @@ 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.
+  them to StartWorkflowOptions / ExecJobFunctionOptions.
 - 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.
@@ -761,6 +828,52 @@ Also review, and migrate by hand:
 
 </details>
 
+## workflow.startJobFunction → execJobFunction
+
+**Migration:** Partially automatic
+
+`tailor.workflow.startJobFunction` and the `StartJobFunctionOptions` type are removed in v2. Use the canonical `execJobFunction` / `ExecJobFunctionOptions`: `Exec*` blocks and returns the job's result, while `Start*` returns only an execution ID. The codemod rewrites member-access call sites on the ambient `tailor.workflow` global and on a `workflow` value imported from @tailor-platform/sdk/runtime(/workflow), and renames `StartJobFunctionOptions` imports along with the type references that resolve to them.
+
+Before:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+const result = workflow.startJobFunction("myJob", { data: "value" });
+```
+
+After:
+
+```ts
+import { workflow } from "@tailor-platform/sdk/runtime";
+
+const result = workflow.execJobFunction("myJob", { data: "value" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+startJobFunction is removed from the SDK's workflow runtime surface in v2;
+execJobFunction is the canonical name for a blocking job call that returns the
+job's result. The codemod rewrites direct member-access calls 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), and renames the StartJobFunctionOptions type. 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.
+
+Also review, and migrate by hand:
+- Destructured references (e.g. const { startJobFunction } = workflow) — the
+  codemod only rewrites direct member-access calls.
+- mockWorkflow().startJobFunction in tests — assert on the execJobFunction vi.fn
+  instead; the alias was the same mock function.
+- A file that already imports ExecJobFunctionOptions alongside the removed type —
+  rename the remaining references by hand and drop the duplicate specifier.
+```
+
+</details>
+
 ## openDownloadStream → downloadStream
 
 **Migration:** Manual
@@ -941,7 +1054,7 @@ For each flagged `.trigger(` call in these files:
 
 **Migration:** Partially automatic
 
-Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod.
+Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod. If your CI workflows were generated by `tailor setup`, re-run `tailor setup` afterwards so they pin tailor-platform/actions v2 — the v1 actions invoke the removed `tailor-sdk` bin.
 
 Before:
 
@@ -1253,9 +1366,9 @@ single generation pass and resolves once it completes.
 
 ## Generated seed exec.mjs → tailor seed CLI plugin
 
-**Migration:** Manual
+**Migration:** Partially automatic
 
-`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments).
+`seedPlugin` no longer generates the `exec.mjs` seed runner. Seeding and validation move to the `tailor seed` commands provided by the `@tailor-platform/sdk-plugin-seed` CLI plugin: install it as a devDependency, replace `node <distPath>/exec.mjs` invocations with `tailor seed apply` and `node <distPath>/exec.mjs validate` with `tailor seed validate`, and delete the stale generated `<distPath>/exec.mjs` file. Seed data and schema generation (`data/*.jsonl`, `data/*.schema.ts`) is unchanged, and the `tailor seed apply` options mirror the old script (`--machine-user`, `--namespace`, `--skip-idp`, `--truncate`, `--yes`, type-name arguments), plus a new `--upsert` flag to update existing rows instead of failing on duplicate ids.
 
 Before:
 
@@ -1272,7 +1385,7 @@ After:
 ```
 
 <details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
 
 ```text
 seedPlugin no longer generates the exec.mjs seed runner in v2. The tailor seed
@@ -1282,11 +1395,194 @@ CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:
   @tailor-platform/sdk.
 - Replace `node <distPath>/exec.mjs [options] [types...]` invocations with
   `tailor seed apply [options] [types...]` (same options: --machine-user/-m,
-  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments).
+  --namespace/-n, --skip-idp, --truncate, --yes, and type-name arguments,
+  plus a new --upsert flag to update existing rows instead of failing on
+  duplicate ids).
 - Replace `node <distPath>/exec.mjs validate [path]` with
   `tailor seed validate [path]`.
+- Rewrite `fork("<distPath>/exec.mjs", ...)` call sites (test setup files
+  typically fork the runner and await a hand-rolled Promise around
+  `child.on("close", ...)`). The plugin is a CLI-dispatched binary rather
+  than a forkable JS module, so call it synchronously instead —
+  `execSync("npx @tailor-platform/sdk seed apply", { env, stdio: "inherit" })` — keeping
+  the original `env` and `stdio` forwarding, and unwind the surrounding
+  Promise wrapper (drop the now-unused `await`, and the `async` keyword when
+  nothing else in the function awaits). Note that `execSync` throws on a
+  nonzero exit, replacing the wrapper's explicit reject.
 - Delete the stale generated `<distPath>/exec.mjs` file; keep the data/
-  directory (JSONL data and generated schemas) as-is.
+  directory (JSONL data and generated schemas) as-is. Nothing removes it
+  automatically, and a leftover runner keeps working while no longer being
+  regenerated.
+```
+
+</details>
+
+## @tailor-platform/sdk/test global mocks → @tailor-platform/sdk/vitest
+
+**Migration:** Manual
+
+The global platform mocks exported from `@tailor-platform/sdk/test` (`setupTailordbMock`, `setupWorkflowMock`, `setupWaitPointMock`, `setupInvokerMock`, `setupTailorErrorsMock`) and the bundled-output helper `createImportMain` are removed in v2. Use the `tailor-runtime` environment from `@tailor-platform/sdk/vitest` together with `mockTailordb` / `mockWorkflow`: the environment injects `TailorErrors` for you, `setWaitHandler` / `setResolveHandler` replace the wait-point stubs, and the invoker is driven through `globalThis.tailor.context.getInvoker` (or passed directly to `.body()` when testing the TypeScript source). No codemod ships for this migration: it replaces per-test global stubs with a Vitest environment plus disposable mocks, which changes the Vitest config, the setup shape, and the assertions of every affected test. The other `@tailor-platform/sdk/test` exports (`createTailorDBHook`, `createStandardSchema`, `unauthenticatedTailorUser`) are unchanged.
+
+Job mocks move from a global stub to a disposable mock:
+
+Before:
+
+```ts
+import { setupWorkflowMock } from "@tailor-platform/sdk/test";
+
+const { startedJobs } = setupWorkflowMock(() => ({ ok: true }));
+```
+
+After:
+
+```ts
+import { mockWorkflow } from "@tailor-platform/sdk/vitest";
+
+using wf = mockWorkflow();
+wf.setJobHandler(() => ({ ok: true }));
+// wf.startedJobs replaces the returned startedJobs array
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The global platform mocks from @tailor-platform/sdk/test are removed in v2.
+Migrate each affected test to the tailor-runtime Vitest environment:
+
+1. Add the environment for the test files that need platform globals — set
+   environment: "tailor-runtime" in the Vitest project config, or add the
+   // @vitest-environment tailor-runtime docblock to the file. The environment
+   ships in @tailor-platform/sdk/vitest and installs TailorErrors and the base
+   tailor/tailordb globals, so setupTailorErrorsMock has no replacement — delete it.
+2. Replace setupTailordbMock(resolver) with using db = mockTailordb() and
+   configure query results on that mock; read its recorded calls instead of the
+   returned executedQueries / createdClients arrays.
+3. Replace setupWorkflowMock(handler) with using wf = mockWorkflow() plus
+   wf.setJobHandler(handler) (or wf.enqueueResult(...) for order-based results),
+   and read wf.startedJobs.
+4. Replace setupWaitPointMock({ onWait, onResolve }) with the same mockWorkflow()
+   handle: wf.setWaitHandler / wf.setResolveHandler, asserting on wf.waitCalls /
+   wf.resolveCalls.
+5. Replace setupInvokerMock(invoker) with
+   vi.spyOn(globalThis.tailor.context, "getInvoker").mockReturnValue(raw) for a
+   bundled test, or pass invoker directly to .body() when unit-testing a
+   resolver/executor/workflow job against the TypeScript source.
+6. Drop createImportMain and the tests that import bundled output through it.
+   Bundling integrity is the SDK's responsibility: unit-test the TypeScript
+   source and cover deployed behavior with E2E tests instead.
+
+See the SDK testing guide for the full environment setup.
+```
+
+</details>
+
+## Programmatic CLI name options → workflow/executor definitions
+
+**Migration:** Manual
+
+The name-keyed option types exported from `@tailor-platform/sdk/cli` — `GetWorkflowOptions`, `StartWorkflowOptions`, `ListWorkflowExecutionsOptions`, `GetExecutorOptions`, `TriggerExecutorOptions`, `ListExecutorJobsOptions`, `GetExecutorJobOptions`, `WatchExecutorJobOptions` — are removed in v2, together with the function overloads that accepted them. Pass the workflow or executor definition itself instead: `{ workflow: myWorkflow, invoker: "admin" }` / `{ executor: myExecutor }`, matching the `*TypedOptions` shape that types `arg` and `payload` from the definition. No codemod ships for this migration: rewriting a name string into a definition requires importing the module that defines the workflow or executor, which a source-local transform cannot resolve.
+
+Before:
+
+```ts
+import { startWorkflow } from "@tailor-platform/sdk/cli";
+
+const { executionId } = await startWorkflow({ name: "user-sync", machineUser: "admin" });
+```
+
+After:
+
+```ts
+import { startWorkflow } from "@tailor-platform/sdk/cli";
+import userSync from "./workflows/userSync";
+
+const { executionId } = await startWorkflow({ workflow: userSync, invoker: "admin" });
+```
+
+Executor commands take the executor definition:
+
+Before:
+
+```ts
+const result = await watchExecutorJob({ executorName: "daily-sync", jobId });
+```
+
+After:
+
+```ts
+const result = await watchExecutorJob({ executor: dailySync, jobId });
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The programmatic CLI functions in @tailor-platform/sdk/cli no longer accept a
+workflow or executor name; they take the definition object instead. For each
+flagged call site:
+
+1. Import the workflow or executor definition — the module whose default export
+   is createWorkflow(...) or whose export is createExecutor(...) with that name.
+2. Replace name: "my-workflow" with workflow: myWorkflow, and
+   executorName: "my-executor" with executor: myExecutor. For
+   listWorkflowExecutions, workflowName becomes workflow.
+3. startWorkflow's machine user moves from machineUser to the required
+   invoker, typed against the machine users declared in tailor.config.ts.
+4. Replace imported option types with the *TypedOptions equivalent
+   (e.g. GetWorkflowOptions → GetWorkflowTypedOptions<typeof myWorkflow>).
+   Note that arg (startWorkflow) and payload (triggerExecutor) are now typed
+   from the definition, so a mistyped argument becomes a type error.
+
+When the name is only known at runtime (read from argv or an environment
+variable), the CLI command itself — `tailor workflow start <name>` /
+`tailor executor trigger <name>` — remains the name-keyed entry point.
+```
+
+</details>
+
+## tailor.d.ts Env uses value types instead of literal values
+
+**Migration:** Manual
+
+The `Env` interface in `tailor.d.ts` is generated from the type of each `defineConfig({ env })` value (`string`, `number`, or `boolean`) instead of the value itself, so the generated file no longer carries whatever the config resolved to when it was generated. Keys that aren't valid TypeScript identifiers are quoted, which previously produced a file that failed to parse. Run `tailor generate` to refresh the file, then widen any code that depended on the old literal types. If a `tailor.d.ts` you already committed contains a sensitive value, treat that value as exposed and rotate it; keep secrets in Secret Manager rather than `env`.
+
+An env value can no longer stand in for a literal union; narrow it explicitly:
+
+Before:
+
+```ts
+const stage: "production" | "staging" = env.STAGE;
+```
+
+After:
+
+```ts
+const stage = env.STAGE === "staging" ? "staging" : "production";
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Tailor SDK v2 generates the `Env` interface in `tailor.d.ts` from the type of
+each `defineConfig({ env })` value (`string`, `number`, `boolean`) instead of
+the resolved value, so `Env` properties no longer carry literal types.
+
+Run `tailor generate` first to refresh `tailor.d.ts`, then review the places
+that depended on the old literal types:
+
+- An env value assigned or passed where a literal union is required, e.g.
+  `const stage: "production" | "staging" = env.STAGE`. Narrow it with a
+  comparison or a validation helper instead of relying on the declared type.
+- A generic argument, conditional type, or template-literal type parameterized
+  by an env value.
+- `as const` / `satisfies` assertions that assumed one specific literal.
+
+Plain comparisons (`env.STAGE === "production"`) and arithmetic on numeric env
+values keep working and need no change. Do not restore the old behavior by
+editing `tailor.d.ts`: it is generated and will be overwritten, and embedding
+env values there is what leaked configured secrets into version control.
 ```
 
 </details>
@@ -1295,6 +1591,10 @@ CLI plugin (@tailor-platform/sdk-plugin-seed) replaces it:
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.
 
+### publishEvents recomputed from the executors in each deploy
+
+An unset `publishEvents` is recomputed on every `deploy` from the executors taking part in the run, in both directions: adding a subscribing trigger turns publishing on, and removing the last one turns it back off. Previously a workflow or job kept publishing once it had been enabled, so a workflow whose subscribing trigger is already gone stops publishing on the next `deploy` — declare `publishEvents: true` on it if something outside this project consumes those events. `deploy` also stops instead of applying when a subscription cannot be satisfied: when a trigger names a resource no config in the run declares, when a workflow or job combines `publishEvents: false` with a subscribing trigger, and when a config that resolves without an `id` subscribes across configs. Each of those errors names the resource and both ways to resolve it.
+
 ### CLI tokens stored in the OS keyring
 
 CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.

package/docs/quickstart.md

@@ -33,13 +33,13 @@ cd example-app
 Before deploying your app, you need to create a workspace:
 
 ```bash
-npx tailor login
-npx tailor workspace create --name <workspace-name> --region <workspace-region>
-npx tailor workspace list
+npx @tailor-platform/sdk login
+npx @tailor-platform/sdk workspace create --name <workspace-name> --region <workspace-region>
+npx @tailor-platform/sdk workspace list
 
 # Or with Bun:
-# bunx tailor login
-# bunx tailor workspace create --name <workspace-name> --region <workspace-region>
+# bun tailor login
+# bun tailor workspace create --name <workspace-name> --region <workspace-region>
 
 # OR
 # Create a new workspace using Tailor Platform Console

package/docs/runtime.md

@@ -20,6 +20,7 @@ import {
   context,
   file,
   aigateway,
+  logger,
 } from "@tailor-platform/sdk/runtime";
 
 const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
@@ -38,6 +39,8 @@ const invoker = context.getInvoker();
 const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
 
 const { url } = await aigateway.get("my-aigateway");
+
+logger.info("order processed", { orderId: "o-1", total: 99.5 });
 ```
 
 ## Subpath imports
@@ -81,10 +84,11 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
 - `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
 - `idp` — IdP user management (`new Client({ namespace })`)
-- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `startJobFunction`, `wait`, `resolve`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
 - `aigateway` — AI Gateway URL resolution (`get`)
+- `logger` — structured logging with severity and attributes; the message is written to standard output, the full entry with its attributes is exported over OpenTelemetry where the attributes are queryable (`debug`, `info`, `warn`, `error`, `setAttributes`)
 
 ## Testing
 

package/docs/services/executor.md

@@ -136,9 +136,9 @@ When the project defines multiple IdPs, pass `idp` to target a specific one. The
 idpUserCreatedTrigger({ idp: "my-idp" });
 ```
 
-Omitting `idp` is allowed only when the project has exactly one IdP; otherwise `apply` fails with an error listing the configured IdPs.
+Omitting `idp` is allowed only when the project has exactly one IdP; otherwise `deploy` fails with an error listing the configured IdPs.
 
-These triggers require the IdP to publish user lifecycle events. The SDK enables `publishUserEvents` automatically during `apply` on each IdP that is targeted by an `idpUser` trigger; set the value explicitly on `defineIdp()` to override. See [IdP service - publishUserEvents](./idp.md#publishuserevents).
+These triggers require the IdP to publish user lifecycle events. `deploy` enables `publishEvents` automatically on each IdP targeted by an `idpUser` trigger taking part in the same run, and turns it back off once no such trigger remains; set the value explicitly on `defineIdp()` to pin it. See [IdP service - publishEvents](./idp.md#publishevents).
 
 ### Auth Access Token Triggers
 
@@ -152,6 +152,37 @@ Fire on auth access token lifecycle events:
 authAccessTokenIssuedTrigger();
 ```
 
+### Workflow Execution Triggers
+
+Fire when a workflow execution changes state. Use the single-event helpers or `workflowExecutionTrigger()` for multiple events:
+
+```typescript
+import { createExecutor, workflowExecutionTrigger } from "@tailor-platform/sdk";
+import orderWorkflow from "../workflows/order";
+
+export default createExecutor({
+  name: "order-workflow-finished",
+  trigger: workflowExecutionTrigger({
+    workflow: orderWorkflow,
+    events: ["completed", "retried"],
+  }),
+  operation: {
+    kind: "function",
+    body: async (args) => {
+      if (args.event === "completed" && !args.success) {
+        console.error(args.error);
+      }
+    },
+  },
+});
+```
+
+The available workflow events are `started`, `completed`, `retried`, `resumed`, `wait_started`, and `wait_resolved`. To observe job-level events, use `workflowJobExecutionStartedTrigger()`, `workflowJobExecutionCompletedTrigger()`, `workflowJobExecutionWaitStartedTrigger()`, `workflowJobExecutionWaitResolvedTrigger()`, or `workflowJobExecutionTrigger()`.
+
+`completed` events include `success`; when it is `false`, `error` contains the failure message. A job released from a wait point emits `wait_resolved` instead of `completed`.
+
+These triggers require the workflow to publish execution events. `deploy` enables `publishEvents` automatically on each targeted workflow, and on every job of a workflow targeted by a `workflowJobExecution*` trigger, and turns it back off once no such trigger remains; set the value explicitly to pin it. See [Workflow service - Execution Events](./workflow.md#execution-events).
+
 ### Multi-Event Triggers
 
 Handle multiple event types in a single executor using multi-event trigger factories. These accept an `events` array of short event names:
@@ -200,7 +231,14 @@ idpUserTrigger({ events: ["created", "deleted"], idp: "my-idp" });
 authAccessTokenTrigger({ events: ["issued", "revoked"] });
 ```
 
-The `event` field on args matches the short event name (e.g., `"created"`, `"updated"`, `"deleted"`, `"issued"`, `"refreshed"`, `"revoked"`), enabling type narrowing. The `rawEvent` field contains the full event type string (e.g., `"tailordb.type_record.created"`).
+#### `workflowExecutionTrigger()` and `workflowJobExecutionTrigger()`
+
+```typescript
+workflowExecutionTrigger({ workflow: orderWorkflow, events: ["started", "completed"] });
+workflowJobExecutionTrigger({ workflow: orderWorkflow, events: ["started", "wait_resolved"] });
+```
+
+The `event` field on args matches the short event name, enabling type narrowing. Record triggers use names such as `"created"`, auth token triggers use `"issued"`, and workflow triggers use `"started"`, `"completed"`, and `"wait_resolved"`. The `rawEvent` field contains the full event type string (e.g., `"tailordb.type_record.created"`).
 
 ## Operation Types
 
@@ -554,3 +592,45 @@ interface AuthAccessTokenContext {
   userId: string; // The user associated with the token
 }
 ```
+
+### Workflow Execution Event Payload
+
+Workflow execution triggers receive execution context:
+
+```typescript
+interface WorkflowExecutionContext {
+  workspaceId: string; // Workspace identifier
+  env: TailorEnv; // Environment variables from tailor.config.ts
+  actor: TailorActor | null; // Principal that triggered the workflow
+  workflowId: string; // Workflow resource ID
+  workflowName: string; // Workflow name
+  workflowExecutionId: string; // Workflow execution ID
+  event: "started" | "completed" | "retried" | "resumed" | "wait_started" | "wait_resolved";
+  rawEvent: string; // Full event type
+}
+```
+
+Completed events narrow on `success`. Failed executions include `error`; retried executions include `retryCount` and `retryAfter`.
+
+```typescript
+body: async (args) => {
+  if (args.event === "completed" && !args.success) {
+    console.error(args.error);
+  }
+};
+```
+
+### Workflow Job Execution Event Payload
+
+Workflow job execution triggers include every `WorkflowExecutionContext` field above, plus job-specific fields:
+
+```typescript
+interface WorkflowJobExecutionContext {
+  workflowJobExecutionId: string; // Job execution ID
+  jobFunctionName: string; // Name passed to createWorkflowJob
+  event: "started" | "completed" | "wait_started" | "wait_resolved";
+  rawEvent: string; // Full event type
+}
+```
+
+`wait_started` events include `waitKey`, plus JSON-serialized `waitPayload` when the wait point recorded one; `wait_resolved` events include `waitKey`.

package/docs/services/idp.md

@@ -195,7 +195,7 @@ defineIdp("my-idp", {
 
 - `enableMfa` - Make TOTP MFA available for users in this namespace. Default `false`. When enabled, users can register an authenticator app (Google Authenticator, 1Password, etc.) from the IdP self-service page.
 - `requireMfa` - Force password-authenticated users to enroll and pass an MFA challenge on each sign-in. Default `false`. Social sign-in (`allowGoogleOauth` / `allowMicrosoftOauth`) is not affected; the upstream provider's MFA covers those sessions.
-- `allowedReturnOrigins` - Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at apply time. Required when `enableMfa` is `true`.
+- `allowedReturnOrigins` - Origins the IdP self-service pages (such as `/mfa/settings`) are allowed to redirect back to. Each entry is either a literal origin (`https://app.example.com`, scheme + host + optional port, no path/query/fragment) or a static-website placeholder `<name>:url` (e.g. `website.url`) that the CLI resolves to the deployed website's URL at deployment time. Required when `enableMfa` is `true`.
 - `mfaIssuer` - Label shown next to the user account in authenticator apps when TOTP is enrolled. Up to 64 characters. Falls back to `"Tailor Platform IdP"` when empty.
 
 **Constraints:** the following combinations are rejected at parse time.
@@ -319,21 +319,23 @@ defineIdp("my-idp", {
 
 **Values:** `"en"` or `"ja"`.
 
-### publishUserEvents
+### publishEvents
 
 Publish IdP user lifecycle events (`idp.user.created`, `idp.user.updated`, `idp.user.deleted`). These events are consumed by executors that use `idpUserCreatedTrigger`, `idpUserUpdatedTrigger`, `idpUserDeletedTrigger`, or `idpUserTrigger`.
 
 ```typescript
 defineIdp("my-idp", {
   clients: ["my-client"],
-  publishUserEvents: true,
+  publishEvents: true,
 });
 ```
 
-**Auto-configuration:** When `publishUserEvents` is omitted, the SDK enables it automatically during `apply` for each IdP that is targeted by an executor's `idpUser` trigger. Targeting is per-IdP: an executor specifies which IdP it subscribes to via the trigger's `idp` option (required in multi-IdP projects). Set the value explicitly to override:
+**Auto-configuration:** When `publishEvents` is omitted, `deploy` sets it from the executors taking part in the same run: `true` while one of their `idpUser` triggers targets this IdP, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`. Targeting is per-IdP: an executor specifies which IdP it subscribes to via the trigger's `idp` option (required in multi-IdP projects). Set the value explicitly to override:
 
-- `publishUserEvents: true`: always publish events.
-- `publishUserEvents: false`: never publish events. `apply` rejects this with an error if any executor's `idpUser` trigger targets this IdP — either remove `publishUserEvents: false` or remove the matching trigger.
+- `publishEvents: true`: always publish events.
+- `publishEvents: false`: never publish events. `deploy` rejects this with an error if an `idpUser` trigger taking part in the same run targets this IdP — either remove `publishEvents: false` or remove the matching trigger.
+
+**Sharing an IdP across configs:** an executor in another config auto-enables publishing the same way, as long as both configs take part in the same `deploy` (`--config a,b`). `deploy` records that dependency, so deploying the owning config alone later asks for confirmation instead of silently turning publishing off — it fails outright in a non-interactive environment. Set `publishEvents: true` on the IdP to keep it on regardless of which configs take part.
 
 ## Using idp.provider()