@tailor-platform/sdk 2.29.2 → 2.32.0

package/dist/{telemetry-DpkFGBmu.mjs → telemetry-nqOtDWNO.mjs}

@@ -1 +1 @@
-export{t as initTelemetry,n as shutdownTelemetry}from"./telemetry-Xk7J829P.mjs";
+export{t as initTelemetry,n as shutdownTelemetry}from"./telemetry-DfT2UfI4.mjs";

package/docs/ai.md

@@ -0,0 +1,92 @@
+---
+description: "Make choice, boolean, and ordered score decisions from application state through AI Gateway with the System One client from @tailor-platform/sdk/ai."
+---
+
+# System One
+
+System One makes semantic decisions from application state, a question, and a fixed answer space. It returns the selected answer and its probability without requiring prompt construction or structured-output parsing.
+
+Create a client with the URL the platform assigns to your deployed [AI Gateway](services/aigateway.md). Inside a Tailor Function, `aigateway.get()` returns it as `url`. Omit `token`; the platform authenticates the request:
+
+```typescript
+import { createSystemOne } from "@tailor-platform/sdk/ai";
+import { aigateway } from "@tailor-platform/sdk/runtime";
+
+const { url } = await aigateway.get("my-aigateway");
+const systemOne = createSystemOne({ baseURL: url });
+```
+
+External clients pass the same URL, which `tailor show` lists, directly with an access token issued by the AI Gateway's auth namespace:
+
+```typescript
+import { createSystemOne } from "@tailor-platform/sdk/ai";
+
+const systemOne = createSystemOne({
+  baseURL: "https://my-aigateway-{WORKSPACE_HASH}.ai.erp.dev",
+  token: accessToken,
+});
+```
+
+## Choice decisions
+
+Use `choice()` to select one value from an answer space. Literal types are inferred without `as const`:
+
+```typescript
+const result = await systemOne.choice({
+  state: { ticket, customer },
+  question: "Which department should handle this ticket?",
+  choices: ["billing", "sales", "support"],
+});
+
+// result.value: "billing" | "sales" | "support"
+// result.probabilities: Record<"billing" | "sales" | "support", number>
+```
+
+## Boolean decisions
+
+Use `boolean()` for a binary decision. `value` is `true` when the probability of "yes" is at least `0.5`, and `probability` is the probability of the selected answer:
+
+```typescript
+const result = await systemOne.boolean({
+  state: invoice,
+  question: "Is this invoice a duplicate?",
+});
+
+if (result.value && result.probability > 0.95) {
+  // Apply the appropriate business rule.
+}
+```
+
+## Ordered scores
+
+Use `score()` when the answer space has a meaningful order. Levels are ordered from lowest to highest, and `value` is the level with the highest probability:
+
+```typescript
+const result = await systemOne.score({
+  state: transaction,
+  question: "Assess the risk of this transaction.",
+  levels: ["low", "medium", "high"],
+});
+```
+
+## Models
+
+Decisions use `jev-1.13.0` unless a call passes `model`. `jev-latest` always points to the newest model, so its probabilities can shift when a new model is released. Use it only when your logic does not compare probabilities against fixed thresholds:
+
+```typescript
+const result = await systemOne.boolean({
+  state: invoice,
+  question: "Is this invoice a duplicate?",
+  model: "jev-latest",
+});
+```
+
+## Errors
+
+Failures throw `SystemOneError` with a provider-independent `code`. Applications can handle stable codes such as `UNAUTHORIZED`, `RATE_LIMITED`, `PROVIDER_TIMEOUT`, and `PROVIDER_UNAVAILABLE` without depending on a model provider.
+
+A decision waits until AI Gateway responds. To fail with `PROVIDER_TIMEOUT` instead, pass `timeoutMs`:
+
+```typescript
+const systemOne = createSystemOne({ baseURL: url, timeoutMs: 10_000 });
+```

package/docs/cli/application.md

@@ -1,3 +1,7 @@
+---
+description: "Create, generate, deploy, inspect, and remove the application defined in tailor.config.ts, and call Tailor Platform APIs directly with tailor api."
+---
+
 # Application Commands
 
 Commands for managing Tailor Platform applications. These commands work with `tailor.config.ts`.

package/docs/cli/auth.md

@@ -1,3 +1,7 @@
+---
+description: "Manage Auth service resources from the tailor CLI: authorize and revoke auth connections, get machine user tokens, and inspect OAuth2 clients."
+---
+
 # Auth Resource Commands
 
 Commands for managing Auth service resources (auth connections, machine users, and OAuth2 clients).

package/docs/cli/completion.md

@@ -1,3 +1,7 @@
+---
+description: "Generate shell completion scripts for the tailor CLI in bash, zsh, and fish."
+---
+
 # Completion
 
 ## completion

package/docs/cli/crashreport.md

@@ -1,3 +1,7 @@
+---
+description: "List local crash report files and submit crash reports to help improve the Tailor Platform SDK."
+---
+
 # Crash Report Commands
 
 Commands for managing crash reports.

package/docs/cli/data.md

@@ -1,3 +1,7 @@
+---
+description: "Clone application data from one workspace to another and inspect asynchronous data operations with the tailor CLI."
+---
+
 # Data Commands
 
 Commands for managing application data across workspaces.

package/docs/cli/executor.md

@@ -1,3 +1,7 @@
+---
+description: "List and inspect executors, view executor jobs, and trigger executors manually with the tailor CLI."
+---
+
 # Executor Commands
 
 Commands for managing executors and executor jobs.

package/docs/cli/function.md

@@ -1,3 +1,7 @@
+---
+description: "Inspect function registries, view function execution logs, and run one-off functions on the Tailor Platform without deploying."
+---
+
 # Function Commands
 
 Commands for managing function registries and viewing function execution logs.

package/docs/cli/organization.md

@@ -1,3 +1,7 @@
+---
+description: "View and update organizations, and manage and display organization folder hierarchies with the tailor CLI."
+---
+
 ## organization
 
 Manage Tailor Platform organizations.

package/docs/cli/plugin.md

@@ -1,3 +1,7 @@
+---
+description: "Discover and list tailor CLI plugins, the external tailor-<name> executables found on your PATH or in node_modules/.bin."
+---
+
 ## plugin
 
 Manage and inspect CLI plugins (beta).

package/docs/cli/query.md

@@ -1,3 +1,7 @@
+---
+description: "Run ad-hoc SQL or GraphQL queries from the tailor CLI, or explore data interactively in the query REPL."
+---
+
 ## query
 
 Run SQL/GraphQL query.

package/docs/cli/secret.md

@@ -1,3 +1,7 @@
+---
+description: "Create and manage Secret Manager vaults and secrets from the tailor CLI."
+---
+
 # Secret Commands
 
 Commands for managing Secret Manager vaults and secrets.

package/docs/cli/skills.md

@@ -1,3 +1,7 @@
+---
+description: "Install, sync, list, and remove Tailor SDK agent skills for AI coding assistants."
+---
+
 ## skills
 
 Manage Tailor SDK agent skills.

package/docs/cli/staticwebsite.md

@@ -1,3 +1,7 @@
+---
+description: "Deploy static website files and manage static websites with the tailor CLI."
+---
+
 # Static Website Commands
 
 Commands for managing and deploying static websites.

package/docs/cli/tailordb.md

@@ -1,3 +1,7 @@
+---
+description: "Truncate TailorDB table data and generate, test, validate, and apply TailorDB schema migrations with the tailor CLI."
+---
+
 # TailorDB Commands
 
 Commands for managing TailorDB tables, data, and schema migrations.
@@ -324,26 +328,28 @@ tailor tailordb migration test [options]
 
 **Options**
 
-| Option                                        | Alias | Description                                                                                                          | Required | Default              | Env                            |
-| --------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------- | -------- | -------------------- | ------------------------------ |
-| `--workspace-id <WORKSPACE_ID>`               | `-w`  | Workspace ID                                                                                                         | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
-| `--profile <PROFILE>`                         | `-p`  | Workspace profile                                                                                                    | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
-| `--config <CONFIG>`                           | `-c`  | Path to Tailor config file                                                                                           | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
-| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten                                                    | No       | `false`              | -                              |
-| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                                                                   | No       | `"seed"`             | -                              |
-| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes)                                               | No       | -                    | -                              |
-| `--keep`                                      | -     | Keep the automatically created workspace after the test                                                              | No       | `false`              | -                              |
-| `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations                                                        | No       | -                    | -                              |
-| `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                                                                   | No       | -                    | -                              |
-| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep) | No       | -                    | -                              |
-| `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                           | No       | -                    | -                              |
-| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                 | 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 Tailor config file                                                                                                                                                                                                       | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`              |
+| `--yes`                                       | `-y`  | Acknowledge that a designated target workspace may be overwritten                                                                                                                                                                | No       | `false`              | -                                 |
+| `--data <DATA>`                               | -     | Data source for the migration test (seed or clone)                                                                                                                                                                               | No       | `"seed"`             | -                                 |
+| `--target-workspace-id <TARGET_WORKSPACE_ID>` | -     | Existing throwaway workspace to retain after the test (requires --yes)                                                                                                                                                           | No       | -                    | -                                 |
+| `--keep`                                      | -     | Keep the automatically created workspace after the test                                                                                                                                                                          | No       | `false`              | -                                 |
+| `--organization-id <ORGANIZATION_ID>`         | -     | Organization to create the temporary workspace in, at its root unless --folder-id is given (default: the source workspace's organization and folder). With --target-workspace-id, must match the target's organization           | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`                     | -     | Folder to create the temporary workspace in (default: the source workspace's folder). Requires --organization-id when the source workspace is not in an organization. With --target-workspace-id, must match the target's folder | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--assert <ASSERT>`                           | -     | Path to a TypeScript assertion script to run after migrations                                                                                                                                                                    | No       | -                    | -                                 |
+| `--assert-namespace <ASSERT_NAMESPACE>`       | -     | TailorDB namespace exposed to the assertion script                                                                                                                                                                               | No       | -                    | -                                 |
+| `--keep-ttl <KEEP_TTL>`                       | -     | Record an expiry on the kept workspace, e.g. 24h or 7d, so workspace prune --expired can delete it (requires --keep)                                                                                                             | No       | -                    | -                                 |
+| `--clone-timeout <CLONE_TIMEOUT>`             | -     | How long to wait for the clone to finish with --data clone, e.g. 30s or 10m (default: 30m)                                                                                                                                       | No       | -                    | -                                 |
+| `--machine-user <MACHINE_USER>`               | -     | Machine user for seed and assertion script execution                                                                                                                                                                             | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Notes**
 
-The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed.
+The source workspace is read-only. Without --target-workspace-id, the command creates a workspace in the source workspace's region and deletes it after success or failure; pass --keep to retain it for inspection. Right after creating the workspace it records a 24h expiry (unless --keep is given without --keep-ttl), so if the run is interrupted before the command can delete the workspace, workspace prune --expired removes it later. A designated target is retained and requires --yes. Clone mode copies TailorDB records only; it does not copy IdP users or file blobs. With --keep-ttl, the kept workspace records an expiry; it is not deleted automatically, but workspace prune --expired removes it once the expiry has passed. Organization and folder IDs loaded by --env-file are used the same way as the options; command-line options take precedence, and empty env-file values are ignored.
 
 #### tailordb migration validate
 

package/docs/cli/upgrade.md

@@ -1,3 +1,7 @@
+---
+description: "Upgrade your project to a new SDK version by running codemods that update your code for breaking changes."
+---
+
 ## upgrade
 
 Run codemods to upgrade your project to a newer SDK version.

package/docs/cli/user.md

@@ -1,3 +1,7 @@
+---
+description: "Log in and out of the Tailor Platform, check authentication status, print access tokens, switch users, and manage personal access tokens."
+---
+
 # User & Auth Commands
 
 Commands for authentication and user management.

package/docs/cli/workflow.md

@@ -1,3 +1,7 @@
+---
+description: "List and inspect workflows, start and wait for workflow runs, and view and resume workflow executions with the tailor CLI."
+---
+
 # Workflow Commands
 
 Commands for managing workflows and workflow executions.

package/docs/cli/workspace.md

@@ -1,3 +1,7 @@
+---
+description: "Create, inspect, and delete workspaces, manage workspace users, apps, and expiry, and manage CLI profiles that pair a user with a workspace."
+---
+
 # Workspace Commands
 
 Commands for managing workspaces and profiles.
@@ -103,7 +107,7 @@ tailor workspace create [options]
 | Option                                | Alias | Description                                                                                                                                   | Required | Default   | Env                               |
 | ------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- | --------------------------------- |
 | `--name <NAME>`                       | `-n`  | Workspace name                                                                                                                                | Yes      | -         | -                                 |
-| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west)                                                                                                    | Yes      | -         | -                                 |
+| `--region <REGION>`                   | `-r`  | Workspace region (asia-northeast, us-west, europe-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/cli-reference.md

@@ -1,3 +1,7 @@
+---
+description: "Reference for the tailor CLI, including usage, global options, JSON output, workspace selection, and an index of every command."
+---
+
 # tailor
 
 Tailor Platform SDK - The SDK to work with Tailor Platform

package/docs/configuration.md

@@ -1,3 +1,7 @@
+---
+description: "Configure your application in tailor.config.ts, including application settings, services, bundling, auth, static websites, secrets, environment variables, workflows, and plugins."
+---
+
 # Configuration
 
 The SDK uses TypeScript for configuration files. By default, it uses `tailor.config.ts` in the project root. You can specify a different path using the `--config` option.

package/docs/data-clone.md

@@ -1,3 +1,7 @@
+---
+description: "Copy the TailorDB records, files, and IdP users of an application from one workspace to another with tailor data clone, and rehearse migrations against cloned data."
+---
+
 # Cloning Application Data
 
 `tailor data clone` copies the data of an application from one workspace to another, for example to fill a staging workspace with production records before testing a release against them. It copies the records of every TailorDB namespace registered in the application, and optionally TailorDB file content and IdP users.

package/docs/github-actions.md

@@ -1,3 +1,7 @@
+---
+description: "Generate GitHub Actions deploy workflows and Renovate configuration for your app with tailor setup, including approval gates, secrets, monorepos, and rollback."
+---
+
 # GitHub Actions Integration
 
 `tailor setup` generates GitHub repository automation for your Tailor Platform
@@ -113,6 +117,92 @@ all-added or all-removed viewer artifacts. Re-run `setup ci branch` after adding
 removing TailorDB namespaces. `setup check` reports drift when the recorded ERD
 preview namespaces no longer match the current config.
 
+#### Migration test on a labeled pull request
+
+Pass `--migration-test` on a branch target to add a job that runs
+[`tailor tailordb migration test`](./cli/tailordb.md) against a pull request on
+demand. It is opt-in and requires a config with TailorDB migrations.
+
+```bash
+tailor setup ci branch --name my-app-stg --migration-test
+```
+
+The job runs only when someone adds the `tailor:migration-test` label to a pull
+request from the same repository (change the label with
+`--migration-test-label`). It runs the pending migrations in a temporary
+workspace created next to the source workspace, writes the `--json` result to
+the job summary, and removes the label as its last step, whether the test
+succeeded, failed, or was cancelled while running. To run it again, add the label
+again. If a run is cancelled before the job starts (for example, a reviewer
+rejects the environment's approval), the label stays on the pull request: remove
+it and add it again.
+Anyone who can label pull requests in your repository can start the job, and
+each run creates and deletes a workspace. Runs for one pull request never
+cancel each other.
+
+The generated workflow also lists `labeled` in its `pull_request` types. The
+plan and ERD preview jobs skip label events, so adding an unrelated label does
+not re-run them.
+
+Runs started by a label report their result job as `tailor-result (<name>) [label]`
+instead of `tailor-result (<name>)`. A label event therefore never replaces the
+result of the check you require for branch protection. The migration test result
+appears only under the `[label]` name, so it does not block merging through the
+check you require.
+
+The job clones the source workspace's TailorDB records and passes
+`--clone-timeout 30m`, which bounds only the wait for the data clone. If the clone takes longer, the command
+fails with the clone's operation ID in the error and removes its temporary
+workspace, while the clone itself keeps running on the platform.
+
+The migration test step is limited to 50 minutes and the job to 60, so the label
+is still removed when the step times out. A step that is stopped at its limit
+(or a job cancelled at the job limit) gives the command no chance to clean up:
+delete the leftover temporary workspace with `tailor workspace delete`.
+
+##### Choosing the source workspace
+
+`migration test` reads the source workspace (it is not modified), builds a
+temporary workspace from it in the same organization and folder, and deletes
+that workspace afterwards. Because the machine user creates and deletes that
+workspace, it needs an editor or admin role on the organization or folder that
+holds the source workspace; a viewer role is not enough. The clone also needs the
+same role on the source side. The clone copies TailorDB records only: IdP users
+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
+  `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.
+- **Source is a different workspace, such as production.** Pass
+  `--migration-test-environment <env>`. The job then uses that GitHub
+  Environment and reads the source workspace from its
+  `TAILOR_PLATFORM_MIGRATION_TEST_SOURCE_WORKSPACE_ID` variable, together with the
+  machine-user secrets set on that same environment. Give this environment a
+  machine user whose role you are willing to hold on the source workspace's
+  organization or folder, since it needs the editor-or-admin role described
+  above. Pending migrations run from the source workspace's migration number up
+  to the latest, so a source that is behind the deploy target replays more
+  migrations, which is closer to what a production deploy will do.
+
+A job can declare only one GitHub Environment, and a repository secret or
+variable is read from that environment, which is why a different source needs its
+own environment. `tailor setup ci env` prints what each environment needs,
+including the dedicated one. Keep the dedicated environment separate from your
+production deploy environment: a pull request job runs on the pull request merge
+ref (`refs/pull/<number>/merge`), so if an environment restricts which branches
+may deploy or requires reviewers, check how that affects the pull request job
+before pointing the migration test at it. A required-reviewers rule makes the
+job wait for approval before it can read the environment's secrets. The job runs
+the pull request's own code with that environment's credentials, so add one when
+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.
+
 ### Tag target (recommended for production)
 
 The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
@@ -497,17 +587,18 @@ tailor setup ci env --check                  # check what is registered in GitHu
 
 The list follows what each generated workflow actually reads:
 
-| 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                                                                                                                                                                       |
+| 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_MIGRATION_TEST_SOURCE_WORKSPACE_ID` | variable | branch (migration test environment) | yes      | ID of the workspace the migration test starts from, set on the environment passed to `--migration-test-environment`; it is only read to build the temporary workspace. Needs the machine user's editor or admin role on that workspace's organization or folder                                                                                                                            |
+| `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.
@@ -639,6 +730,12 @@ and apply the data after deploy.
 | branch, tag | `tailor seed apply --upsert`         | The fields of each committed seed row are written; other rows are kept        |
 | preview     | `tailor seed apply --truncate --yes` | The preview workspace is emptied, IdP users included, and seeded from scratch |
 
+The seed steps read the optional `SEED_USER_PASSWORD` secret of the GitHub
+Environment and pass it to `tailor seed`, which uses it as the password of `_User`
+rows that have none. Set it with `tailor setup ci env`. Validation on pull
+requests gets a fixed placeholder instead of the secret, since it only checks that
+a password exists.
+
 Setup stops unless the config uses `seedPlugin` with `machineUserName`, which
 names the machine user that seeds, and an existing `<distPath>/data/` directory.
 Every `--seed-dataset` must name an entry of

package/docs/migration/v2.md

@@ -1,3 +1,7 @@
+---
+description: "Upgrade your project to Tailor Platform SDK v2 by running the codemods and finishing the changes they report as not migrated automatically."
+---
+
 # Migrating to v2
 
 <!-- Generated from the sdk-codemod registry. Run `pnpm codemod:docs:update` and edit `packages/sdk-codemod/src/registry.ts` instead of this file. -->

package/docs/multi-environment.md

@@ -1,3 +1,7 @@
+---
+description: "Deploy one tailor.config.ts to development, staging, and production workspaces, and vary configuration values, secrets, and seed data per environment."
+---
+
 # Multi-Environment Configuration
 
 A project typically runs in more than one environment — for example, each developer's own workspace, a staging workspace, and a production workspace. The SDK has no separate "environment" concept: an environment is a workspace you deploy to, and all environments share the same `tailor.config.ts`. This guide shows how to switch the deployment target and how to vary configuration values per environment.

package/docs/plugin/custom.md

@@ -1,3 +1,7 @@
+---
+description: "Build your own SDK plugin by implementing the Plugin interface and its definition-time and generation-time hooks."
+---
+
 # Custom Plugins (Beta)
 
 > **Beta Feature**: The custom plugin API is in beta and may change in future releases.

package/docs/plugin/frontend.md

@@ -1,3 +1,7 @@
+---
+description: "Build your frontend and upload it to a Static Website on every tailor deploy, with deployed URLs and OAuth client IDs passed in as build variables."
+---
+
 # Frontend Plugin
 
 `frontendPlugin` builds frontend assets and uploads them to Static Websites after

package/docs/plugin/index.md

@@ -1,3 +1,7 @@
+---
+description: "Extend TailorDB tables with plugins that generate additional tables, executors, and files, and learn how to register, attach, and configure them."
+---
+
 # Plugins (Beta)
 
 > **Beta Feature**: The plugin system is currently in beta. APIs may change in future releases.

package/docs/quickstart.md

@@ -1,3 +1,7 @@
+---
+description: "Create an example app with the Tailor Platform SDK, set up a workspace, and deploy it in a few commands."
+---
+
 # Quickstart
 
 ## Getting Started

package/docs/runtime.md

@@ -1,3 +1,7 @@
+---
+description: "Call Tailor Platform runtime APIs such as secrets, IdP, workflows, file uploads, AI Gateway, and logging from your functions with typed imports from @tailor-platform/sdk/runtime."
+---
+
 # Runtime API
 
 `@tailor-platform/sdk/runtime` provides typed wrappers for the `tailor.*` and `tailordb.file` APIs that the Tailor Platform Function runtime injects into the global scope at execution time. The wrappers are thin and delegate to the platform-provided globals; they exist so that you can:

package/docs/services/aigateway.md

@@ -1,3 +1,7 @@
+---
+description: "Define AI Gateways that give your app one OpenAI-compatible endpoint for multiple LLMs, with workspace authentication and platform-managed credentials."
+---
+
 # AI Gateway
 
 AI Gateway provides a unified endpoint for accessing a range of large language models through a single OpenAI-compatible API, with platform-managed credentials and workspace-scoped authentication.

package/docs/services/auth.md

@@ -1,3 +1,7 @@
+---
+description: "Configure authentication and authorization with defineAuth, including user profiles, machine users, OAuth 2.0 clients, identity providers, auth connections, and before-login hooks."
+---
+
 # Auth
 
 Auth is a service for configuring authentication and authorization in your Tailor Platform application.

package/docs/services/executor.md

@@ -1,3 +1,7 @@
+---
+description: "Create executors that run functions, webhooks, GraphQL operations, or workflows in response to record changes, schedules, incoming webhooks, and resolver events."
+---
+
 # Executor
 
 Executors are event-driven handlers that automatically trigger in response to data changes, schedules, or external events.

package/docs/services/http-adapter.md

@@ -1,3 +1,7 @@
+---
+description: "Expose REST-style HTTP endpoints that translate each request into a GraphQL operation and shape the response for HTTP clients."
+---
+
 # HTTP Adapter
 
 HTTP adapters expose REST-style HTTP endpoints on your application by translating each request into a GraphQL query and (optionally) reshaping the GraphQL response back into an HTTP response.

package/docs/services/idp.md

@@ -1,3 +1,7 @@
+---
+description: "Set up the built-in identity provider with defineIdp to register and authenticate users and manage OAuth clients for your Auth service."
+---
+
 # IdP (Identity Provider)
 
 IdP is a built-in identity provider service for managing user authentication.