@tailor-platform/sdk 2.37.0 → 2.39.0

package/docs/github-actions.md

@@ -173,8 +173,8 @@ and file blobs are not copied.
 
 Two setups are supported:
 
-- **Source is the plan/deploy workspace (default).** The job uses the same GitHub
-  Environment as the plan and deploy jobs, so it reads the same
+- **Source is the deploy workspace (default).** The job uses the same GitHub
+  Environment as the deploy job, so it reads the same
   `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets. Nothing
   extra to configure. If that workspace holds too little data to be a useful
   test, point the job at a workspace that does with the next setup.
@@ -204,6 +204,51 @@ the source workspace holds production data.
 Fork pull requests cannot read secrets, so the job is skipped for them.
 `--migration-test` is not available together with several `--dir` values.
 
+#### Running the plan job in its own environment
+
+The plan job runs on pull requests, and a pull request from a branch of the same
+repository can change the workflow it runs, so its code can read every secret
+and variable of the environment the plan job enters. When plan and deploy share
+one environment, that includes the deploy machine user. Pass
+`--split-plan-environment` on a branch target to run the plan job in an
+environment of its own:
+
+```bash
+tailor setup ci branch --name my-app-stg --split-plan-environment
+```
+
+The plan job then enters an environment named after the deploy environment with
+`-plan` appended (`my-app-stg-plan` here). The deploy job, and the migration test job unless you
+pass `--migration-test-environment`, stay in the deploy environment. Set these
+on the plan environment:
+
+- `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` and
+  `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` of a machine user of its own. The
+  plan only reads, so a viewer role on the organization or folder that holds the
+  workspace is enough. Set them on the plan environment itself: otherwise the job
+  reads the ones set on the repository or organization, and
+  `tailor setup ci env --check` reports them as missing.
+- `TAILOR_PLATFORM_WORKSPACE_ID`, the same workspace the deploy environment
+  deploys to.
+
+Keep the deploy machine user off the plan environment. `tailor setup ci env`
+lists what each of the two environments needs.
+
+The flag alone does not keep the deploy credentials from a pull request, which
+can point the plan job back at the deploy environment. Under **Settings →
+Environments**, limit the deploy environment's **Deployment branches and tags**
+to the target branch, so that GitHub refuses a pull request job in it. With that
+limit in place:
+
+- The migration test job also runs on pull requests, so give it its own
+  environment with `--migration-test-environment` (see
+  [Choosing the source workspace](#choosing-the-source-workspace)).
+- The jobs of a preview target run on pull requests too, so pass
+  `setup ci preview` an `--environment` other than the limited one.
+
+`setup update` keeps the flag, but re-running `setup ci branch` does not carry it
+over: pass it each time, or the plan job moves back into the deploy environment.
+
 ### Tag target (recommended for production)
 
 The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
@@ -259,14 +304,53 @@ that workspace when the pull request is closed:
 tailor setup ci preview --name my-app --region asia-northeast
 ```
 
-Fork pull requests are skipped. Every other pull request gets a preview, draft
-pull requests included. `--require` narrows that to one of:
+It writes two workflows. `tailor-my-app-preview.yml` deploys the pull request
+when it is opened or pushed to, and `tailor-my-app-preview-cleanup.yml` deletes
+the workspace when the pull request is closed. The cleanup workflow starts on
+`pull_request_target`, which GitHub also triggers for a pull request with merge
+conflicts, where workflows on `pull_request` do not start. A
+`pull_request_target` workflow can read the repository's secrets whoever opened
+the pull request, so GitHub runs it from the default branch: the workflow file
+and the code it checks out are the default branch's, never the pull request's.
+Therefore:
+
+- The cleanup workflow runs only once it is on the default branch, and it
+  installs dependencies and runs `tailor` from the default branch's checkout.
+  If the preview target deploys pull requests into another branch
+  (`--branch`), commit the cleanup workflow, the lockfile, and the app's
+  `tailor.config.ts` to the default branch too.
+- If the target's GitHub Environment restricts which branches can deploy,
+  allow the default branch: GitHub checks the cleanup job against it, and the
+  deploy job against the pull request's merge ref.
+
+When `tailor setup update` regenerates a preview workflow generated before the
+cleanup workflow existed, it moves the `tailor-preview-cleanup` job into the
+cleanup workflow, together with the steps and settings you added to it, and
+copies the top-level `env`, `defaults`, and `concurrency` of the preview
+workflow into the cleanup workflow. Your steps then run from the default branch
+as described above. A job of yours in the preview workflow that runs when the
+pull request is closed no longer runs, because that workflow no longer starts
+then; move it into the cleanup workflow. `setup` warns about each job of yours
+in the preview workflow whose `if` contains an `== 'closed'` comparison.
+
+#### Pull requests that get a preview
+
+Fork pull requests are skipped, and so are events on a closed pull request,
+such as a label added after merging. Every other pull request gets a preview,
+draft pull requests included. `--require` narrows that to one of:
 
 - `--require ready` skips draft pull requests. The preview is deployed when the
   draft is marked ready for review.
 - `--require label` deploys only pull requests labeled `tailor:preview`. A
   labeled draft deploys too, because the label asks for the preview.
 
+With app directories other than the repository root (`--dir`), a pull request
+gets no preview either when none of its changed files counts. A file counts
+when it is under an app directory, is the generated workflow file, or matches a
+`--paths` pattern, and the last pattern that matches it does not start with `!`
+(see
+[Running on changes outside the app directories](#running-on-changes-outside-the-app-directories)).
+
 When `tailor setup update` regenerates a preview target generated before
 `--require` existed, it reads the target as `--require ready`, or as
 `--require label` if it required the label. The first keeps skipping drafts; the
@@ -288,7 +372,8 @@ tailor setup ci autofix --dir apps/erp --dir apps/users  # run tailor generate i
 It writes `.github/workflows/tailor-autofix.yml`, which runs `tailor generate`
 on every pull request and, when that changes files, commits them to the pull
 request branch as `chore: run tailor generate`. Only the changes
-`tailor generate` makes are committed: files that earlier steps leave in the
+`tailor generate` makes, and with `--codemod deterministic` those of
+`tailor upgrade`, are committed: files that earlier steps leave in the
 checkout, such as an `.npmrc`, are not. The deploy workflows keep their check,
 which fails on the commit that needed the fix and passes on the fix commit.
 
@@ -313,9 +398,10 @@ right away.
 - **A branch that moved on:** if someone pushes to the branch while the
   workflow runs, it does not commit; the run for the new commit regenerates the
   files.
-- **Output that keeps changing:** if `tailor generate` changes files again
-  right after the fix commit, the workflow fails instead of committing again.
-  Check that running it twice in a row changes nothing.
+- **Output that keeps changing:** if `tailor generate` (or, with
+  `--codemod deterministic`, `tailor upgrade`) changes files again right after
+  the fix commit, the workflow fails instead of committing again. Check that
+  running it twice in a row changes nothing.
 - **Approval rules:** the fix commit becomes the most recent push to the pull
   request, and a bot pushed it. A branch protection rule that requires the most
   recent push to be approved by someone other than its pusher is then satisfied
@@ -340,6 +426,60 @@ right away.
 To stop committing, delete the workflow with
 `tailor setup delete .github/workflows/tailor-autofix.yml`.
 
+### Applying codemods on SDK upgrades
+
+A pull request that upgrades `@tailor-platform/sdk`, such as one from Renovate,
+may need the codemods that [`tailor upgrade`](./cli/upgrade.md) runs. Pass
+`--codemod` to have the autofix workflow handle them; without it, the
+workflow runs only `tailor generate`:
+
+```bash
+tailor setup ci autofix --codemod error          # fail the pull request until they are applied
+tailor setup ci autofix --codemod deterministic  # commit what they rewrite
+```
+
+| `--codemod`     | On a pull request that upgrades the SDK                                                                                  | Check fails |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `warn`          | Runs `tailor upgrade --dry-run` and reports the files it would rewrite and the changes it leaves for review, as warnings | No          |
+| `error`         | Reports the same as errors, and fails the `tailor-codemod-result` job                                                    | Yes         |
+| `deterministic` | Commits what `tailor upgrade` rewrites together with what `tailor generate` changes, and reports the rest as warnings    | No          |
+
+- **Which upgrade:** for each `--dir`, the workflow upgrades from the SDK
+  version that the lockfile at the repository root resolves on the pull
+  request's base branch to the version the pull request installs. When the
+  base branch has no lockfile of that name, such as when the pull request
+  switches package managers, it upgrades from 2.37.0, the oldest version
+  `tailor setup ci autofix` supports. A pull request that keeps the version,
+  or keeps the SDK linked from a workspace (such as with `workspace:*`), runs
+  no codemod.
+- **Reports:** the files left for you get annotations, and the job summary
+  lists every file, with the migration prompt of each change left for review.
+  Hand the prompt to an AI coding assistant, or follow it yourself.
+- **Required check:** with `error`, require the `tailor-codemod-result` check
+  to block the merge. The workflow still commits what `tailor generate`
+  changes. `tailor-codemod-result` also fails when the `tailor-autofix` job
+  fails or is cancelled, and is skipped, which counts as passing, when that
+  job succeeds with nothing left.
+- **Reviews keep matching:** a change left for review is found by the code it
+  touches, and some codemods ask for a review of the whole app, so a review
+  can still be reported after you finish the migration. With `error`, such a
+  pull request keeps failing until the base branch has the new version.
+- **Workflow files:** GitHub refuses a change to `.github/workflows` from the
+  workflow token or from an App without the Workflows permission, so
+  `deterministic` leaves those files out of the fix commit and reports them.
+  Run `tailor upgrade --from <base version>` and commit them yourself.
+- **Warnings** that `tailor upgrade` prints for code that may still need a
+  manual migration stay warnings with every value.
+- **Lockfile:** bun needs the text `bun.lock`, not `bun.lockb`. A `yarn.lock`
+  does not record which app uses which version, so when the base branch has
+  several SDK versions and the pull request changes them, the workflow fails and
+  you run `tailor upgrade` yourself. Yarn 1 leaves workspace packages out of
+  `yarn.lock`, so the workflow also fails for an app that takes the SDK from a
+  workspace there.
+- **Skipped pull requests:** fork and Dependabot pull requests skip the whole
+  workflow (except fork pull requests with `autofix-ci`), so `error` does not
+  check them, and a skipped check counts as passing.
+
 ## Targeting a workspace
 
 The generated `plan` and `deploy` jobs target a workspace by **id**, read from
@@ -349,7 +489,9 @@ environment before the first deploy.
 
 Because the variable is scoped to a GitHub Environment, both the `plan` and
 `deploy` jobs declare `environment:` so the value resolves. When you omit
-`--environment`, the environment name defaults to the workspace name.
+`--environment`, the environment name defaults to the workspace name. With
+`--split-plan-environment`, set the variable on the plan environment as well (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 1. Provision the workspace (once per environment) and obtain its id. For now
    this is a manual step:
@@ -374,8 +516,9 @@ provisioned yet instead of running a dry-run.
 
 If the target environment has required reviewers, that approval gate applies to
 the `plan` job as well as `deploy`, because `plan` must enter the environment to
-read the variable. (A token-based read that lets `plan` run without entering the
-environment is planned.)
+read the variable, unless a branch target runs `plan` in its own environment with
+`--split-plan-environment`. (A token-based read that lets `plan` run without
+entering the environment is planned.)
 
 ## Package manager
 
@@ -437,9 +580,9 @@ 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.
+- **The top-level `concurrency:` of the preview and cleanup workflows.** 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`. If every managed job that re-running `setup` keeps
   uses the same `runs-on` you set, such as self-hosted runners, a managed job
@@ -481,9 +624,8 @@ A job that runs `tailor` against the workspace needs the machine-user
 (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 fork pull requests, for draft pull requests with
-`--require ready`, and for unlabeled ones with `--require label`.
+The job is skipped whenever `tailor-preview-deploy` is skipped (see
+[Pull requests that get a preview](#pull-requests-that-get-a-preview)).
 
 A preview workspace expires 7 days (`ttl: 7d` on `tailor-preview-deploy`) after
 the last push to its pull request. When a pull request is closed,
@@ -496,13 +638,32 @@ open; the next push creates a fresh one. Change `ttl` to keep previews longer or
 shorter. Workflows generated before this was added get these settings the next
 time you run `tailor setup update`.
 
-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.
+A preview workspace last deployed before `ttl` was added to its workflow records
+no expiry, so this sweep never deletes it. To find such leftovers, list the
+preview workspaces created more than 7 days ago:
+
+```bash
+tailor workspace prune --name 'my-app-pr-[0-9]+' --older-than 7d \
+  --folder-id <folder id> --limit 0 --dry-run
+```
+
+Pass `--organization-root <organization id>` instead of `--folder-id` when
+`TAILOR_PLATFORM_FOLDER_ID` is unset. The list can include the previews of pull
+requests that are still open: keep each of them with
+`--exclude my-app-pr-<number>`, then run the command again without `--dry-run`.
+
+Each new preview workflow run for a pull request, such as after a push, 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. Closing the pull
+request cancels it too, because the cleanup workflow runs in the same
+concurrency group. If you change the group in one of the two workflows, change
+it in the other, and build it only from values that are the same in both, such
+as `github.event.pull_request.number`: `github.ref`, `github.workflow`, and
+`github.event_name` differ between them, and `github.ref` is the default branch
+for every pull request in the cleanup workflow. 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
@@ -528,7 +689,9 @@ job back. To start over from a clean template, delete the file and re-run
 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.
+steps left inside a removed job. The `tailor-preview-cleanup` job, which moved
+into its own workflow, keeps your steps instead (see
+[Preview target](#preview-target-per-pull-request-workspace)).
 
 `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
@@ -562,7 +725,6 @@ tailor-preview-result:
   name: tailor-preview-result (my-app)
   needs:
     - tailor-preview-deploy
-    - tailor-preview-cleanup
     - seed
     - e2e
 ```
@@ -660,7 +822,13 @@ keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
 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.
+protection rules no longer guard your deploys, and `tailor setup ci env --check`
+warns about the client secret (see
+[Checking what is registered](#checking-what-is-registered)). To share one machine
+user and keep that protection, set the same client secret on each environment
+instead. The plan environment of `--split-plan-environment` is the exception: give
+it a machine user of its own (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ### Setting secrets and variables
 
@@ -704,6 +872,16 @@ The autofix workflow uses no GitHub Environment, so its two entries are set on
 the repository; the output lists them under the repository instead of an
 environment.
 
+A branch target generated with `--split-plan-environment` reads from two
+environments. The plan environment needs its own
+`TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` and
+`TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET`, for which a viewer role is enough,
+and `TAILOR_PLATFORM_WORKSPACE_ID`; of the optional entries, only the plan job's
+`TAILOR_PLATFORM_FAIL_ON_DRIFT` and `SEED_USER_PASSWORD` apply to it. A manual dry
+run reads `SEED_USER_PASSWORD` from there, and pull requests can read it too, like
+everything on that environment. The deploy environment needs the rest, without
+`TAILOR_PLATFORM_FAIL_ON_DRIFT`.
+
 See [Account management](https://docs.tailor.tech/administration/account-management)
 for how organizations, folders, workspaces, and machine users relate.
 
@@ -735,13 +913,29 @@ to manage those settings in Terraform instead.
 environment and for the repository entries of the autofix workflow, which of
 these entries are registered. It fails when a required
 entry is missing, reports missing optional entries without failing, and prints
-the `gh` commands that set only the missing entries, with where each value comes
-from. It changes nothing, and it checks names only, since GitHub never returns
-secret values.
+the `gh` commands that set the missing entries, with where each value comes
+from, and that move the client secret onto its environment (see below). It
+changes nothing, and it checks names only, since GitHub never returns secret
+values.
 
 - An entry set on the repository, or on the organization and shared with the
   repository, counts as registered, because the workflow reads it from there when
   the environment does not set it. The report says where each entry was found.
+- `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` set on the repository or the
+  organization is reported with ⚠, even when the environment also sets it: any
+  workflow on any branch can read it there, so the environment's protection rules
+  do not guard it. The check still passes. The printed commands set it on the
+  environment, with the value you set on the repository or organization, and list
+  a commented-out `gh secret delete` for the repository copy: run it once every
+  environment and workflow that reads that secret has its own. An organization
+  owner has to stop sharing an organization secret with the repository. The
+  warning stops once the client secret is set only on the environments; when
+  every target shares one machine user, set the same client secret on each of
+  them.
+- On the plan environment of `--split-plan-environment`, the machine user's
+  client ID and client secret count only when set on that environment, since
+  the plan job would otherwise sign in as the machine user set on the repository
+  or organization.
 - An entry registered as the other kind, such as `TAILOR_PLATFORM_WORKSPACE_ID`
   set as a secret, is reported as missing, because the workflow does not read it.
   `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID` set as a secret still counts, with a
@@ -773,7 +967,10 @@ environment-scoped secrets there.
 
 Required reviewers gate the `plan` job as well, because `plan` must enter the
 environment to read `TAILOR_PLATFORM_WORKSPACE_ID`. (A token-based read that
-lets `plan` run without entering the environment is planned.)
+lets `plan` run without entering the environment is planned.) On a branch target,
+`--split-plan-environment` moves `plan` into an environment of its own, whose
+settings then apply to it instead (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ## Manual runs and dry-run
 
@@ -808,7 +1005,11 @@ can deploy, configure **Deployment branches and tags** on the target's GitHub
 Environment and keep the machine-user secrets on that environment. Because the
 plan job also enters the environment, allow `refs/pull/*/merge` as well so pull
 request plans keep running, and note that dry runs from other branches are then
-rejected too.
+rejected too. On a branch target, `--split-plan-environment` moves the plan job,
+dry runs included, into an environment of its own instead, so the deploy
+environment can allow the target branch alone once the migration test job, if
+any, has its own environment as well (see
+[Running the plan job in its own environment](#running-the-plan-job-in-its-own-environment)).
 
 ## Seeding the workspace after deploy
 
@@ -863,8 +1064,10 @@ Before enabling it, note that:
   and validation run, `updatedAt` changes, and executors with
   `recordUpdatedTrigger` fire once per seeded row on every deploy.
 - Every preview deploy deletes the data reviewers added to the preview
-  workspace. That is every push, and with `--require label` also every
-  label added to the pull request, since each one redeploys the preview.
+  workspace. That is every push to a pull request that
+  [gets a preview](#pull-requests-that-get-a-preview), and with
+  `--require label` also every label added to it, since each one redeploys the
+  preview.
 - A seed failure fails the deploy job and its notification, although the deploy
   itself went through.
 - The step shares the deploy job's timeout. IdP users take about a second each.
@@ -1126,10 +1329,10 @@ workflows it reports.
 
 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 with `--require ready`, fork
-PRs, and unlabeled PRs with `--require label`) skip the check. A single run audits every workflow
-recorded in `.github/tailor.lock`.
+runs the check in CI. Preview workflows run it in `tailor-preview-deploy`, so
+the check is skipped whenever that job is (see
+[Pull requests that get a preview](#pull-requests-that-get-a-preview)). A single
+run audits every workflow 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

package/docs/migration/v2.md

@@ -1612,7 +1612,7 @@ See the SDK testing guide for the full environment setup.
 
 **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.
+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` from the definition and accepts `payload` only for an executor with an incoming webhook trigger. 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:
 
@@ -1662,8 +1662,10 @@ flagged call site:
    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.
+   Note that arg (startWorkflow) is now typed from the definition, so a
+   mistyped argument becomes a type error. Passing payload to
+   triggerExecutor is a type error unless the executor has an incoming
+   webhook trigger.
 
 When the name is only known at runtime (read from argv or an environment
 variable), the CLI command itself — `tailor workflow start <name>` /

package/docs/services/auth.md

@@ -26,6 +26,7 @@ Configure Auth service using `defineAuth()`:
 
 - **One auth per application**: Each application can have exactly one Auth service
 - **Configuration location**: Define in `tailor.config.ts` using `defineAuth()` and reference directly in the config's `auth` field
+- **Referencing another app's auth**: When another app in the same repository defines the auth, reference it with `asExternal()`. See [Referencing another app's Auth with `asExternal()`](../configuration.md#referencing-another-apps-auth-with-asexternal)
 - **`userProfile` and `machineUserAttributes` are mutually exclusive**: Specifying both fails at deploy/generate time with ``Specify either `userProfile` or `machineUserAttributes`, not both.``
 
 ```typescript
@@ -314,6 +315,10 @@ export default createResolver({
 
 Type narrowing is provided by the generated `tailor.d.ts` (the `MachineUserNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new machine users to refresh it.
 
+`tailor deploy` checks the string `invoker` of every resolver and executor against the machine users of the Auth service it resolves to, and stops with `INVOKER_MACHINE_USER_NOT_FOUND` when the name does not exist. The `invoker` passed to `workflow.start()` is not checked at deploy time. When a config deployed in the same run defines the Auth service, the machine users it lists are the ones checked, because deploy removes the machine users it no longer lists. When the Auth service is only referenced as external, the machine users that exist in the workspace are checked.
+
+When the Auth service is an external one (`auth: { name: "...", external: true }`), the machine users are not in your config, so `tailor.d.ts` cannot narrow the invoker type and any string passes type checking. For resolvers and executors, the deploy-time check is what catches a misspelled name in that case.
+
 ## OAuth 2.0 Clients
 
 Configure OAuth 2.0 clients for third-party applications:

package/docs/services/executor.md

@@ -543,6 +543,8 @@ export default createExecutor({
 
 The webhook URL is public, so verify the signature over the unparsed request body before trusting `body`. `rawBody` is delivered base64-encoded; decode it to the original bytes before computing the signature.
 
+When an executor is triggered manually with [`tailor executor trigger`](../cli/executor.md#executor-trigger) or `triggerExecutor` from `@tailor-platform/sdk/cli`, it receives empty `headers`, even when `--header` is given, and no `rawBody`. To test an executor that reads headers or verifies a signature, send a request to its webhook URL, which [`tailor executor webhook list`](../cli/executor.md#executor-webhook-list) shows.
+
 **With custom response:**
 
 ```typescript

package/docs/services/tailordb/index.md

@@ -226,7 +226,9 @@ const user = db.table("User", {
 });
 ```
 
-A relation can also be set on a field inside `db.object()`. The inner field gets the foreign key constraint only: no index, no unique constraint, and no forward or backward relationship, as with `type: "keyOnly"`.
+A `keyOnly` relation does not make the field unique; add `.unique()` to the field to make it unique.
+
+A relation can also be set on a field inside `db.object()`, where it adds only the foreign key constraint to the inner field, and `.unique()` and `.index()` set on that field work as described in [Index / Unique](#index--unique).
 
 ```typescript
 const order = db.table("Order", {
@@ -477,6 +479,8 @@ db.string().serial({
 });
 ```
 
+`format` holds exactly one of `%d` (decimal), `%o` (octal), `%x` (lowercase hexadecimal), or `%X` (uppercase hexadecimal), optionally with a width: `%5d` pads with spaces and `%05d` with zeros, to at least 5 characters. Write a literal `%` as `%%`. The format is at most 32 characters.
+
 A serial field cannot be used inside a `db.object()` field.
 
 > **Preview:** The `gapless` option is a preview feature. Its behavior and configuration may change before general availability.
@@ -571,7 +575,7 @@ db.table("User", {
 - When not specified, `deploy` sets it from the executors taking part in the same run: `true` while one of them uses this table with `recordCreatedTrigger`, `recordUpdatedTrigger`, or `recordDeletedTrigger`, and `false` once none does. Removing the last such trigger turns publishing back off on the next `deploy`
 - When explicitly set to `false` while an executor taking part in the same run uses this table, `deploy` fails
 - An executor declared with `disabled: true` never runs, so it does not count as using the table
-- While a `deploy` applies pending migrations with [maintenance mode](./migration.md#maintenance-mode) on, every table in the migrating namespace is restricted: the GraphQL create, update, and delete operations and bulk upsert are disabled, and the table's `read` setting is not switched off for the migration (a table the migration creates uses its configured setting), so nothing writes an intermediate schema and readable tables are not shut down. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. With `maintenanceMode: false`, these restrictions are not applied. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified; the deploy then reports the namespace whose tables stay restricted and points to `tailor tailordb migration status --namespace <namespace>`. When a failed migration or a failed restoration leaves tables restricted, the deploy lists their names, and deploying again releases them once the migration completes. A table that a failed rollback could not delete or revert is the exception: the deploy also lists it, but the next deploy stops with remote schema drift until you delete or repair that table by hand. A table left behind by a failed post-checkpoint deletion also remains read-only for manual recovery, and the deploy does not list it by name
+- While a `deploy` applies pending migrations with [maintenance mode](./migration.md#maintenance-mode) on, every table in the migrating namespace is restricted: the GraphQL create, update, and delete operations and bulk upsert are disabled, and the table's `read` setting is not switched off for the migration (a table the migration creates uses its configured setting), so nothing writes an intermediate schema and readable tables are not shut down. Record event publishing is also switched off so a migration script's writes do not reach executors from the previous deploy. With `maintenanceMode: false`, these restrictions are not applied. After success, the configured settings take effect. If a later migration fails, settings from the last confirmed checkpoint are restored; an uncommitted migration restores existing tables' prior settings and leaves its newly created tables restricted until a successful retry. A table that already refuses create, update, delete, and bulk upsert and publishes no record events is left as it is. Restoration is skipped if the checkpoint number or migration history changed concurrently, or if checkpoint ownership cannot be verified; the deploy then reports the namespace whose tables stay restricted and points to `tailor tailordb migration status --namespace <namespace>`. When a failed migration or a failed restoration leaves tables restricted, the deploy lists their names, and deploying again releases them once the migration completes. A table that a failed rollback could not delete or revert is also listed: when it still has the migration's pre-migration schema, deploying again runs the migration again; otherwise the next deploy stops with remote schema drift until you delete or repair that table by hand. A table left behind by a failed post-checkpoint deletion also remains read-only, and the deploy does not list it by name; the next deploy deletes it
 
 **Use cases:**