@tailor-platform/sdk 2.26.0 → 2.27.0

package/docs/cli/application.md

@@ -56,22 +56,23 @@ 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`              | -                                 |
-| `--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       | -                    | -                                 |
+| 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       | -                    | -                                 |
+| `--migration-skip-steps <MIGRATION_SKIP_STEPS>` | -     | Skip steps of a partially applied multi-step migration that already succeeded (comma-separated namespace/step entries) | 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.
 **JSON result:**
@@ -93,6 +94,13 @@ tailor deploy --json > deploy-result.json
 jq '.applications[] | {name, url, staticWebsites, auth}' deploy-result.json
 ```
 
+After a successful apply, stdout is exactly one line: the JSON object. A dry-run writes its
+plan as one JSON object. Progress and diagnostics go to stderr, so the output can be captured
+as it is, for example
+`result=$(tailor deploy --json)`. A failed deploy exits non-zero and writes its error as
+JSON to stderr, leaving stdout empty. A deploy plugin that writes to stdout itself makes
+the output unparseable; plugins report through `ctx.logger` and run commands through `ctx.exec`.
+
 Dry-run and build-only deployments do not return deployed application information.
 If resources were applied but loading the JSON result fails, the command reports
 `DEPLOY_RESULT_LOAD_FAILED`; fix the error and run `tailor deploy` again.

package/docs/cli/function.md

@@ -129,6 +129,8 @@ $ tailor function logs <execution-id> --follow
 
 **Notes**
 
+Each execution includes `errorKind`, which tells you where a failure came from: `USER_RUNTIME` (your code threw while running, or exceeded its time, memory, or CPU limit), `USER_NON_RUNTIME` (your script failed while loading, before your function was called, such as when its top-level code threw), `PLATFORM` (a failure on the Platform side, or the Platform aborting the run because of its own deadline or cancellation), `NONE` (no error), or `UNSPECIFIED` (not recorded, or a kind this CLI version does not recognize). A workflow job waiting on another job also reports `USER_NON_RUNTIME` when that job fails or is canceled. `errorName` and `errorMessage` hold the error's name and message, or `null` when none was recorded. The list table omits `errorMessage`; use `--json` or the execution details to read it.
+
 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. With `--json`, `--follow` waits for completion and then emits the final execution details once.

package/docs/cli/workspace.md

@@ -103,7 +103,7 @@ tailor workspace create [options]
 | Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
 | ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
 | `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (us-west, asia-northeast)                                                                                                    | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west)                                                                                                    | Yes      | -         | -                                 |
 | `--delete-protection`                 | `-d`  | Enable delete protection                                                                                                                      | No       | `false`   | -                                 |
 | `--organization-id <ORGANIZATION_ID>` | `-o`  | Organization ID to workspace associate with                                                                                                   | No       | -         | `TAILOR_PLATFORM_ORGANIZATION_ID` |
 | `--folder-id <FOLDER_ID>`             | `-f`  | Folder ID to workspace associate with                                                                                                         | No       | -         | `TAILOR_PLATFORM_FOLDER_ID`       |

package/docs/configuration.md

@@ -77,6 +77,19 @@ This is a bundle-time setting. Changing `TAILOR_APP_LOG_LEVEL` affects newly bun
 
 Only `logger.*` calls made through the SDK's `logger` wrapper (from `@tailor-platform/sdk/runtime` or its `@tailor-platform/sdk/runtime/logger` subpath), or written as `globalThis.tailor.logger.*`, are covered. Other equivalent forms — such as the bare `tailor.logger.*` global or `self.tailor.logger.*` — are not affected by `logLevel`.
 
+**Date Representation** (`defaultDateRepresentation`): Sets the value representation of `t.date()`, `t.datetime()`, and `t.time()` fields that omit `as`. With `"temporal"`, those fields carry `Temporal.PlainDate`, `Temporal.Instant`, and `Temporal.PlainTime` values instead of strings, so a project that uses Temporal everywhere does not have to repeat `as: "temporal"` on every field; with `"date"`, they carry `Date` values, as `as: "date"` gives them. A field's own `as` still wins, including `as: "string"`. Run `tailor generate` after changing the setting so `tailor.d.ts` updates the field types.
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  defaultDateRepresentation: "temporal",
+});
+```
+
+The default applies wherever the SDK parses or serializes `t` fields on your behalf: resolver input and output in deployed functions and in `tailor function run`, `.parse()` and `parseDateFields` inside any bundled function (resolvers, executors, workflow jobs, auth hooks, TailorDB hooks and validators, migration scripts), and the [`tailor-runtime` Vitest environment](./testing.md#loading-secrets-from-config) when `tailorRuntime({ config })` points at the config. It does not apply to `db.*` fields, or to `t` fields parsed outside those places, such as a plain Node.js script or a module that runs while `tailor.config.ts` itself is being loaded; there the fields keep string values. A migration script keeps the representation that was in effect when it was generated, recorded in its `diff.json`, so changing the setting later does not alter migrations a new workspace has yet to run. That record covers the values at run time only; the TypeScript types of `t` fields follow the current `tailor.d.ts` everywhere, so a `t` date field declared inside a migration script should set `as` explicitly to keep its type and its values aligned after the setting changes.
+
+The setting is per `tailor.config.ts`, but the field types are declared through `tailor.d.ts`, which TypeScript merges across every file in a program. If one `tsconfig.json` includes the `tailor.d.ts` of several applications, they must agree on `defaultDateRepresentation`. When they differ, `t.date()`, `t.datetime()`, and `t.time()` called without `as` fail to type-check in that program until the configs are aligned or each application gets its own `tsconfig.json`.
+
 ### Service Configuration
 
 Specify glob patterns to load service files:
@@ -185,11 +198,11 @@ import { defineIdp } from "@tailor-platform/sdk";
 const idp = defineIdp("my-idp", {
   clients: ["my-client"],
   permission: {
-    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
   },
 });
 
@@ -310,7 +323,7 @@ When the SDK deploys application code or runs detected service code with `functi
 | Executor callbacks        | `body: ({ env }) => ...`, `url: ({ env }) => String(env.bar)`, `variables: ({ env }) => ({ enabled: env.baz })`, or similar callback args |
 | Workflow job body         | `body: (input, { env }) => ...`                                                                                                           |
 | Auth before-login hook    | `handler: async ({ env }) => ...`                                                                                                         |
-| TailorDB migration script | `main(trx, { env }: MigrationContext)`                                                                                                    |
+| TailorDB migration script | `main(trx, { env }: MigrationContext)`, or each step's `run(trx, { env })`                                                                |
 | `function run`            | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |
 
 ```typescript

package/docs/github-actions.md

@@ -153,6 +153,10 @@ or end with a hyphen. It is used for the generated file name, the workflow
 select which workspace gets deployed (see
 [Targeting a workspace](#targeting-a-workspace)).
 
+For a preview target, the name can be at most 50 characters: each pull request
+gets its own workspace named `<name>-pr-<number>`, which must fit in 63
+characters.
+
 ## Targeting a workspace
 
 The generated `plan` and `deploy` jobs target a workspace by **id**, read from
@@ -213,9 +217,8 @@ for what you can edit.
 ### Customizing the generated workflow
 
 The SDK owns the jobs and steps whose `id` starts with `tailor-`, and the
-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:
+top-level `name:`, `on:`, and `permissions:`. Do not edit or rename them.
+Everything else is yours, and re-running `setup` keeps 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
@@ -225,19 +228,27 @@ them. Everything else is yours, and re-running `setup` keeps it:
   (such as `playwright install`) _after_ it. A job of your own can depend on a
   managed job with `needs: tailor-deploy`.
 - **Your own top-level keys**, such as a workflow-level `env:` or `defaults:`.
+- **The top-level `concurrency:` of a preview workflow.** The SDK writes a
+  default, and re-running `setup` keeps your edits to it. If you delete it,
+  re-running `setup` adds the default back.
 - **Runtime settings of managed jobs:** `runs-on`, `timeout-minutes`,
-  `container`, and `env`. On a managed job generated without an
-  `environment:` (such as `tailor-tag-guard` or `tailor-erd-preview`), you can
-  also add one, for example so a step you added there can read that GitHub
-  Environment's secrets. The `environment:` of `tailor-plan`, `tailor-deploy`,
-  and the preview jobs comes from `--environment`, so change it with that
-  option instead.
+  `container`, and `env`. If every managed job that re-running `setup` keeps
+  uses the same `runs-on` you set, such as self-hosted runners, a managed job
+  it adds (for example, the ERD preview jobs when you add `--erd-preview`)
+  uses it too; otherwise, set the new job's `runs-on` yourself. On a managed
+  job generated without an `environment:` (such as `tailor-tag-guard` or
+  `tailor-erd-preview`), you can also add one, for example so a step you added
+  there can read that GitHub Environment's secrets. The `environment:` of
+  `tailor-plan`, `tailor-deploy`, and the preview jobs comes from
+  `--environment`, so change it with that option instead.
 - **These inputs of managed steps:** `ignore` on `tailor-generate-check` and
   `tailor-drift-check`, `fail-on-drift` on `tailor-drift-check`,
   `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 `tailor-build-site` step** in a composite action.
+  `tailor-notify`.
+- **Your own jobs in the `needs` of `tailor-result` and
+  `tailor-preview-result`**, so they count toward the workflow's result (see
+  [Requiring the workflow in branch protection](#requiring-the-workflow-in-branch-protection)).
 
 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
@@ -250,7 +261,7 @@ deploy-assets:
   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_ID: ${{ vars.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
@@ -265,6 +276,14 @@ 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`.
 
+Each new preview workflow run for a pull request, such as after a push or when
+the pull request is closed, cancels the run still in progress for it, including
+your jobs, so they do not keep running against a workspace that the new run
+may redeploy or delete. Events on a pull request that stays closed, such as a
+label added after merging, do not cancel anything. A job with `if: always()`
+still runs when its run is cancelled, and the new run waits for it to finish;
+use `if: ${{ !cancelled() }}` instead so it stops with the run.
+
 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
@@ -299,6 +318,48 @@ 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
 `--force` to switch it to this model; your own jobs and steps are kept.
 
+### Requiring the workflow in branch protection
+
+Branch and preview workflows end with a job that reports the result of the
+whole workflow: `tailor-result` in a branch workflow and
+`tailor-preview-result` in a preview workflow. Its check is named after the
+workspace, such as `tailor-result (my-app)`, so each workflow in the repository
+has its own. Require that one check in branch protection instead of listing
+the jobs one by one.
+
+The job runs after every other SDK-managed job of the workflow, even when one
+fails or the run is cancelled. It fails when a job in its `needs` failed or was
+cancelled, and passes when they succeeded or were skipped, for example when the
+preview deploy is skipped for a fork pull request. When a newer run cancels a
+job of an older one, such as the preview deploy of a commit you pushed over,
+the older run's check fails; the newer run reports its own.
+
+To make jobs of your own count, add them to its `needs`. A matrix job is listed
+once by its job id, however many combinations it expands to:
+
+```yaml
+tailor-preview-result:
+  name: tailor-preview-result (my-app)
+  needs:
+    - tailor-preview-deploy
+    - tailor-preview-cleanup
+    - seed
+    - e2e
+```
+
+Re-running `setup` keeps the jobs you add there and updates the `tailor-`
+entries to the jobs the SDK generates. A job skipped because a job it needs
+failed also counts as passing, so list every job of yours whose failure should
+block merging, not only the last one: above, `seed` is listed because `e2e`
+needs it.
+
+With `--require-preview-label`, the preview workflow does not start when a pull
+request is opened, so its check is not reported until the pull request is
+labeled, reopened, or pushed to. A draft pull request skips the preview deploy,
+and marking it ready for review does not start the workflow, so the check that
+passed while it was a draft stays until the next push. Tag workflows have no
+such job: they run on tags, not on pull requests.
+
 ### `.github/tailor.lock`
 
 A machine-owned JSON file that tracks which files the SDK manages, the inputs
@@ -353,23 +414,33 @@ the move.
 
 ## Secrets
 
-The generated workflow requires two secrets (the optional Slack token is listed in
+The generated workflow requires one secret (the optional Slack token is listed in
 [Setting secrets and variables](#setting-secrets-and-variables)):
 
 | Secret                                       | Description                |
 | -------------------------------------------- | -------------------------- |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Machine user client ID     |
 | `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); `tailor setup ci env` prints the commands (see
+The machine user client ID is a variable, not a secret: it cannot authenticate
+without the client secret. The generated workflow reads
+`vars.TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` and falls back to
+`secrets.TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`, so a repository that already
+stores the client ID as a secret keeps working unchanged. Storing the client ID
+as a secret is deprecated, and the fallback will be removed in a future release,
+so move it to a variable (`gh variable set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`)
+and delete the secret.
+
+Set the client secret as a secret and the client ID as a variable on the target
+GitHub Environment (the `--environment` value, or the 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`
-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.
+variable. You can also set the client secret as a repository-level secret and the
+client ID as a repository-level variable 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
 
@@ -389,24 +460,23 @@ tailor setup ci env --environment my-app-stg # only one environment (repeat for
 
 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                 |
+| Name                                         | Kind     | Targets     | Required | Where the value comes from                                                                                                                                                                                                                                                                                                                                                                 |
+| -------------------------------------------- | -------- | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | variable | all         | yes      | Client ID of the platform machine user CI signs in as (an existing secret of the same name still works as a deprecated fallback); it needs an editor or admin role on the organization or folder that holds the workspace. An organization or folder admin creates one in the Tailor Console and grants it a role; without the required permission you cannot view or create machine users |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | secret   | all         | yes      | Client secret of the same platform machine user                                                                                                                                                                                                                                                                                                                                            |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | variable | branch, tag | 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 | no       | Bot User OAuth Token (`xoxb-...`) of a Slack app with the `chat:write` scope                                                                                                                                                                                                                                                                                                               |
+| `TAILOR_SLACK_CHANNEL_ID`                    | variable | branch, tag | 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.
+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
@@ -463,8 +533,7 @@ dispatches, so you can deploy any commit regardless of branch membership.
 
 ### Restricting manual deploys
 
-Pass `--restrict-dispatch` to `setup ci branch`, `setup ci tag`, or
-`setup ci coordinate` to limit what a manual dispatch with `dry-run` off can
+Pass `--restrict-dispatch` to `setup ci branch` or `setup ci tag` to limit what a manual dispatch with `dry-run` off can
 deploy:
 
 - **Branch target:** only the target branch. Dispatching another branch skips
@@ -493,12 +562,14 @@ tailor setup ci branch --name my-app --dir apps/backend
 ```
 
 The `working-directory` for SDK commands is set accordingly, and the workflow
-only plans and deploys when that subdirectory changes. The workflow itself
-starts on every pull request and push: a `tailor-changes` job checks whether
-the change touches `apps/backend/**`, and the plan, deploy, and ERD preview jobs
-are skipped when it does not. A skipped job reports success, so you can make
-these checks required in branch protection; a workflow that a `paths` trigger
-filter never started would leave them pending instead. If the `tailor-changes` job
+only plans and deploys when that subdirectory or the generated workflow file
+changes. The workflow itself starts on every pull request and push: a
+`tailor-changes` job checks whether the change touches `apps/backend/**` or the
+generated workflow file itself, and the plan, deploy, and ERD preview jobs are
+skipped when it does not. A skipped job reports success, so you can require the
+workflow's [result check](#requiring-the-workflow-in-branch-protection) in
+branch protection; a workflow that a `paths` trigger filter never started would
+leave it pending instead. If the `tailor-changes` job
 itself fails (for example, on a GitHub API error), the plan, deploy, and ERD
 preview jobs fail too instead of being skipped, so a required check blocks
 merging and nothing is deployed. Re-run the failed jobs once the cause is gone.
@@ -539,8 +610,13 @@ tailor setup ci preview --name erp --region asia-northeast \
   --paths "apps/*/frontend/**" --paths "modules/**" --paths pnpm-lock.yaml
 ```
 
-The patterns are checked after the app directories, in order, and the last
-pattern that matches a changed file decides whether it counts. `*` matches
+The patterns are checked after the app directories and the generated workflow
+file, in order, and the last pattern that matches a changed file decides whether
+it counts. A change to the workflow file alone runs the generated plan, deploy,
+and preview jobs, and with them any job of yours that needs them, in the pull
+request or push that makes the change; to skip the jobs for such a change,
+exclude the file, for example `--paths '!.github/workflows/tailor-erp.yml'`
+(`tailor-erp-preview.yml` for the preview workflow). `*` matches
 within one path segment, `**` matches any number of segments, and a pattern
 starting with `!` excludes matching paths, so it can also exclude files inside
 an app directory, for example `--paths '!apps/erp/backend/**/*.md'`. Other glob
@@ -675,14 +751,12 @@ 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
+Workflows generated by `setup ci branch`, `setup ci tag`, and `setup ci preview`
+self-audit: each contains a `tailor-drift-check` step that
 runs the check in CI. Preview workflows run it alongside each preview deploy,
 so pull requests that deploy no preview (drafts, fork PRs, and unlabeled PRs
 in label-triggered mode) skip the check. A single run audits every target
-recorded in `.github/tailor.lock`, so per-app composite actions generated by
-`setup ci action` are covered by their coordinator's step and do not carry one
-of their own.
+recorded in `.github/tailor.lock`.
 
 Drift findings are advisory by default. Set the repository variable
 `TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
@@ -702,14 +776,14 @@ pick up template improvements:
 tailor setup update
 ```
 
-It regenerates every workflow and composite action recorded in
+It regenerates every workflow 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
+validation, 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
@@ -717,13 +791,5 @@ 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/plugin/custom.md

@@ -272,7 +272,8 @@ same fields. OAuth client secrets are never included.
 `ctx.configPath` is the absolute path of the registering config. `ctx.workspaceId`
 and `ctx.pluginConfig` identify the deployment workspace and the plugin's options.
 Use `ctx.logger.info`, `warn`, and `success` for diagnostics; they write to stderr
-and preserve deploy's JSON stdout.
+and preserve deploy's JSON stdout. A hook that writes to stdout itself, such as
+with `console.log`, makes `tailor deploy --json` output unparseable.
 
 ```typescript
 import { definePlugins, type Plugin } from "@tailor-platform/sdk";

package/docs/services/auth.md

@@ -526,6 +526,26 @@ hooks: {
 }
 ```
 
+### Password age claim
+
+For a user with a Built-in IdP password, `claims.password_updated_at` holds when the password was last set, in seconds since the Unix epoch. It is `undefined` for users without a password. Throw from the handler to reject a sign-in whose password is older than your policy allows.
+
+```typescript
+const MAX_PASSWORD_AGE_SECONDS = 90 * 24 * 60 * 60;
+
+hooks: {
+  beforeLogin: {
+    handler: async ({ claims }) => {
+      const updatedAt = claims.password_updated_at;
+      if (updatedAt !== undefined && Date.now() / 1000 - updatedAt > MAX_PASSWORD_AGE_SECONDS) {
+        throw new Error("Password expired");
+      }
+    },
+    invoker: "hook-invoker",
+  },
+}
+```
+
 ## CLI Commands
 
 Manage Auth resources using the CLI:

package/docs/services/executor.md

@@ -278,7 +278,7 @@ Executor callbacks receive the trigger args, including `env` from `defineConfig(
 
 ### Job Function Operation
 
-For long-running operations, use `jobFunction` which runs asynchronously and supports extended execution times. See [Job Function Operation](https://docs.tailor.tech/guides/executor/job-function-operation) for details.
+For work that needs more than the 60-second `function` limit, use `jobFunction`, which can run for up to 5 minutes. See [Job Function Operation](https://docs.tailor.tech/guides/executor/job-function-operation) for details.
 
 ```typescript
 import { createExecutor, scheduleTrigger } from "@tailor-platform/sdk";
@@ -292,7 +292,7 @@ export default createExecutor({
     kind: "jobFunction",
     body: async () => {
       const db = getDB("tailordb");
-      // Long-running report generation logic
+      // Report generation logic (runs up to 5 minutes)
       const records = await db.selectFrom("Order").selectAll().execute();
       // Process records...
     },

package/docs/services/idp.md

@@ -105,6 +105,9 @@ defineIdp("my-idp", {
 
 **Operators:** `"="`, `"!="`, `"in"`, `"not in"`
 
+> [!WARNING]
+> A policy of `[{ user: "_loggedIn" }, "=", true]` permits every authenticated user to run the operation against any IdP user. For `read` and `update` this exposes and lets them change other users' login information (such as email addresses), and for `sendPasswordResetEmail` it lets them send reset emails to anyone. Use it only when every user who can sign in to the project is trusted. For an IdP used by external users (such as business partners), restrict each operation to an administrator role as shown above.
+
 **Helper:** `unsafeAllowAllIdPPermission` grants full access without conditions. Intended only for development and testing.
 
 ```typescript
@@ -161,6 +164,8 @@ defineIdp("my-idp", {
 - `passwordMinLength` - Minimum password length. Must be between 6 and 30. Default `6`.
 - `passwordMaxLength` - Maximum password length. Must be between 6 and 4096. Default `4096`.
 
+**Password expiration:** the IdP does not expire passwords on its own, but it records when each user's password was last set so you can enforce your own policy. The `User` records returned by `idp.Client` expose it as `passwordUpdatedAt` (an ISO 8601 string, or `null` for users without a password), for example to find expired passwords in a scheduled executor. To block sign-in with an expired password, read `claims.password_updated_at` in the Auth `beforeLogin` hook (see [Auth](./auth.md#password-age-claim)).
+
 **Email domains and social login:**
 
 - `allowedEmailDomains` - Restrict registration to these email domains. Each entry is a hostname (`example.com`), matched exactly and case-insensitively, so `example.com` does not cover `sub.example.com`. Up to 100 entries.
@@ -189,7 +194,7 @@ defineIdp("my-idp", {
     read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
     update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
     delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
-    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
     unenrollMfa: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
   },
 });

package/docs/services/resolver.md

@@ -141,7 +141,7 @@ GraphQL still accepts and returns `YYYY-MM-DD` strings. The SDK converts input t
 
 This option also works in nested objects and with `array: true` or `optional: true`. Input must be a valid calendar date, and output must be a valid `Date` with a 4-digit UTC year (0000-9999). Both deployed resolvers and `tailor function run` perform these conversions.
 
-A resolver bundle only includes the conversion code for the representations (`as: "date"` or `as: "temporal"`) its `input` and `output` use. To parse other values with such fields inside `body`, for example an external API response, use `parseDateFields` instead of `.parse()`. It takes the same arguments and returns the same result as `.parse()`. Calling `.parse()` on a field whose representation the bundle leaves out throws an error that points to `parseDateFields`.
+A resolver bundle only includes the conversion code for the representations (`as: "date"` or `as: "temporal"`) its `input` and `output` use; with [`defaultDateRepresentation: "temporal"`](../configuration.md#application-settings), the Temporal conversion is always included. To parse other values with such fields inside `body`, for example an external API response, use `parseDateFields` instead of `.parse()`. It takes the same arguments and returns the same result as `.parse()`. Calling `.parse()` on a field whose representation the bundle leaves out throws an error that points to `parseDateFields`.
 
 ```typescript
 import { parseDateFields } from "@tailor-platform/sdk/runtime";
@@ -204,6 +204,8 @@ createResolver({
 
 All three field types support `array`, `optional`, nested objects, and input validators with the selected representation. Both deployed resolvers and `tailor function run` convert input and output. Executors using `resolverExecutedTrigger` receive date, datetime, and time results as strings.
 
+To use Temporal values without writing `as: "temporal"` on every field, set [`defaultDateRepresentation: "temporal"`](../configuration.md#application-settings) in `defineConfig()`. Fields that omit `as` then use `Temporal.PlainDate`, `Temporal.Instant`, and `Temporal.PlainTime`, and `as: "string"` opts a single field back to strings. `defaultDateRepresentation: "date"` does the same for `Date` values. Run `tailor generate` after changing the setting so `tailor.d.ts` updates the field types.
+
 The SDK supplies Temporal types, so existing projects can use `as: "temporal"` without changing `compilerOptions.lib`. To construct values or name their types, import `Temporal` from the SDK:
 
 ```typescript

package/docs/services/staticwebsite.md

@@ -145,11 +145,11 @@ const website = defineStaticWebSite("my-frontend", {
 const idp = defineIdp("my-idp", {
   clients: ["default-client"],
   permission: {
-    create: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    read: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    update: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    delete: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
-    sendPasswordResetEmail: [{ conditions: [[{ user: "_loggedIn" }, "=", true]], permit: true }],
+    create: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    read: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    update: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    delete: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
+    sendPasswordResetEmail: [{ conditions: [[{ user: "role" }, "=", "ADMIN"]], permit: true }],
   },
 });