@tailor-platform/sdk 1.62.0 → 2.0.0-next.0

package/docs/cli/auth.md

@@ -350,7 +350,7 @@ Get an access token for a machine user.
 **Usage**
 
 ```
-tailor-sdk machineuser token [options] <name>
+tailor-sdk machineuser token [options] [name]
 ```
 
 <!-- politty:command:machineuser token:usage:end -->
@@ -359,9 +359,9 @@ tailor-sdk machineuser token [options] <name>
 
 **Arguments**
 
-| Argument | Description       | Required |
-| -------- | ----------------- | -------- |
-| `name`   | Machine user name | Yes      |
+| Argument | Description                                                                 | Required |
+| -------- | --------------------------------------------------------------------------- | -------- |
+| `name`   | Machine user name. Falls back to the active profile's default machine user. | No       |
 
 <!-- politty:command:machineuser token:arguments:end -->
 

package/docs/cli/function.md

@@ -245,14 +245,14 @@ tailor-sdk function test-run [options] <file>
 
 **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`           |
-| `--name <NAME>`                 | `-n`  | Workflow job name to run (matches the `name` field of createWorkflowJob) | No       | -                    | -                                   |
-| `--arg <ARG>`                   | `-a`  | JSON argument to pass to the function                                    | No       | -                    | -                                   |
-| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for authentication                                     | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
-| `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                  | No       | `"tailor.config.ts"` | -                                   |
+| 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`           |
+| `--name <NAME>`                 | `-n`  | Workflow job name to run (matches the `name` field of createWorkflowJob)                       | No       | -                    | -                                   |
+| `--arg <ARG>`                   | `-a`  | JSON argument to pass to the function                                                          | No       | -                    | -                                   |
+| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for authentication. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
+| `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                                        | No       | `"tailor.config.ts"` | -                                   |
 
 <!-- politty:command:function test-run:options:end -->
 <!-- politty:command:function test-run:examples:start -->

package/docs/cli/query.md

@@ -33,7 +33,7 @@ tailor-sdk query [options]
 | `--query <QUERY>`               | `-q`  | Query string to execute directly; omit to start REPL mode                                            | No       | -                    | -                                   |
 | `--file <FILE>`                 | `-f`  | Read query string from file; omit to start REPL mode                                                 | No       | -                    | -                                   |
 | `--edit`                        | -     | Open a temporary file in your editor; omit to start REPL mode                                        | No       | `false`              | -                                   |
-| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for query execution                                                                | Yes      | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
+| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for query execution. Falls back to the active profile's default machine user.      | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
 | `--newline-on-enter`            | -     | REPL: when true, Enter inserts a newline and Shift+Enter submits. Use --no-newline-on-enter to swap. | No       | -                    | -                                   |
 
 <!-- politty:command:query:options:end -->

package/docs/cli/setup.md

@@ -28,9 +28,9 @@ tailor-sdk setup [command]
 
 **Commands**
 
-| Command                         | Description                                             |
-| ------------------------------- | ------------------------------------------------------- |
-| [`setup github`](#setup-github) | Generate GitHub Actions workflow for deployment. (beta) |
+| Command                         | Description                                       |
+| ------------------------------- | ------------------------------------------------- |
+| [`setup github`](#setup-github) | Generate a GitHub Actions deploy workflow. (beta) |
 
 <!-- politty:command:setup:subcommands:end -->
 
@@ -47,7 +47,7 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 <!-- politty:command:setup github:description:start -->
 
-Generate GitHub Actions workflow for deployment. (beta)
+Generate a GitHub Actions deploy workflow. (beta)
 
 <!-- politty:command:setup github:description:end -->
 
@@ -65,14 +65,16 @@ tailor-sdk setup github [options]
 
 **Options**
 
-| Option                                  | Alias | Description                         | Required | Default |
-| --------------------------------------- | ----- | ----------------------------------- | -------- | ------- |
-| `--workspace-name <WORKSPACE_NAME>`     | `-n`  | Workspace name                      | Yes      | -       |
-| `--workspace-region <WORKSPACE_REGION>` | `-r`  | Workspace region                    | Yes      | -       |
-| `--organization-id <ORGANIZATION_ID>`   | `-o`  | Organization ID                     | Yes      | -       |
-| `--folder-id <FOLDER_ID>`               | `-f`  | Folder ID                           | Yes      | -       |
-| `--dir <DIR>`                           | `-d`  | App directory (for monorepo setups) | No       | `"."`   |
-| `--with-plan`                           | `-p`  | Include plan job for PR previews    | No       | `false` |
+| Option                              | Alias | Description                                                                                                                                       | Required | Default |
+| ----------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `--workspace-name <WORKSPACE_NAME>` | `-n`  | Workspace name (defaults to the config 'name')                                                                                                    | No       | -       |
+| `--branch <BRANCH>`                 | -     | Branch target: deploy trigger branch (defaults to the detected default branch). Tag target: tag-reachability guard branch (no guard when omitted) | No       | -       |
+| `--tag`                             | -     | Generate a tag target (deploy on tag push)                                                                                                        | No       | `false` |
+| `--tag-pattern <TAG_PATTERN>`       | -     | Tag glob to match (requires --tag; defaults to v\*)                                                                                               | No       | -       |
+| `--environment <ENVIRONMENT>`       | -     | GitHub Environment for the plan/deploy jobs (defaults to the workspace name)                                                                      | No       | -       |
+| `--no-plan`                         | -     | Disable the plan job for a branch target (cannot be combined with --tag)                                                                          | No       | `false` |
+| `--dir <DIR>`                       | `-d`  | App directory (for monorepo setups)                                                                                                               | No       | `"."`   |
+| `--force`                           | -     | Discard hand edits / take over unmanaged files and regenerate                                                                                     | No       | `false` |
 
 <!-- politty:command:setup github:options:end -->
 
@@ -81,3 +83,7 @@ tailor-sdk setup github [options]
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 <!-- politty:command:setup github:global-options-link:end -->
+
+## Further reading
+
+- [GitHub Actions Integration](../github-actions.md) — usage guide: targets, generated files, secrets, approval gates, and rollback.

package/docs/cli/workflow.md

@@ -167,16 +167,16 @@ tailor-sdk workflow start [options] <name>
 
 **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                                        | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH`   |
-| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name                                              | Yes      | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
-| `--arg <ARG>`                   | `-a`  | Workflow argument (JSON string)                                | No       | -                    | -                                   |
-| `--wait`                        | `-W`  | Wait for execution to complete                                 | No       | `false`              | -                                   |
-| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m') | No       | `"3s"`               | -                                   |
-| `--logs`                        | `-l`  | Display job execution logs after completion (requires --wait)  | No       | `false`              | -                                   |
+| 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                                                     | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH`   |
+| `--machine-user <MACHINE_USER>` | `-m`  | Machine user name. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
+| `--arg <ARG>`                   | `-a`  | Workflow argument (JSON string)                                             | No       | -                    | -                                   |
+| `--wait`                        | `-W`  | Wait for execution to complete                                              | No       | `false`              | -                                   |
+| `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')              | No       | `"3s"`               | -                                   |
+| `--logs`                        | `-l`  | Display job execution logs after completion (requires --wait)               | No       | `false`              | -                                   |
 
 <!-- politty:command:workflow start:options:end -->
 

package/docs/cli/workspace.md

@@ -241,11 +241,13 @@ tailor-sdk profile create [options] <name>
 
 **Options**
 
-| Option                          | Alias | Description                                                                       | Required | Default   |
-| ------------------------------- | ----- | --------------------------------------------------------------------------------- | -------- | --------- |
-| `--user <USER>`                 | `-u`  | User email                                                                        | Yes      | -         |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                                      | Yes      | -         |
-| `--permission <PERMISSION>`     | -     | Profile permission. 'read' blocks all write commands while the profile is active. | No       | `"write"` |
+| Option                                            | Alias | Description                                                                                                                            | Required | Default   |
+| ------------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------- |
+| `--user <USER>`                                   | `-u`  | User email                                                                                                                             | Yes      | -         |
+| `--workspace-id <WORKSPACE_ID>`                   | `-w`  | Workspace ID                                                                                                                           | Yes      | -         |
+| `--permission <PERMISSION>`                       | -     | Profile permission. 'read' blocks all write commands while the profile is active.                                                      | No       | `"write"` |
+| `--machine-user <MACHINE_USER>`                   | `-m`  | Default machine user name for application-data commands (query, workflow start, function test-run, machineuser token).                 | No       | -         |
+| `--machine-user-override <MACHINE_USER_OVERRIDE>` | -     | Whether the command line or TAILOR_PLATFORM_MACHINE_USER_NAME may override the profile's machine user. 'deny' requires --machine-user. | No       | -         |
 
 <!-- politty:command:profile create:options:end -->
 
@@ -320,11 +322,13 @@ tailor-sdk profile update [options] <name>
 
 **Options**
 
-| Option                          | Alias | Description                                                                          | Required | Default |
-| ------------------------------- | ----- | ------------------------------------------------------------------------------------ | -------- | ------- |
-| `--user <USER>`                 | `-u`  | New user email                                                                       | No       | -       |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | New workspace ID                                                                     | No       | -       |
-| `--permission <PERMISSION>`     | -     | Profile permission. 'read' blocks all write commands; 'write' lifts the restriction. | No       | -       |
+| Option                                            | Alias | Description                                                                                                                                                           | Required | Default |
+| ------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `--user <USER>`                                   | `-u`  | New user email                                                                                                                                                        | No       | -       |
+| `--workspace-id <WORKSPACE_ID>`                   | `-w`  | New workspace ID                                                                                                                                                      | No       | -       |
+| `--permission <PERMISSION>`                       | -     | Profile permission. 'read' blocks all write commands; 'write' lifts the restriction.                                                                                  | No       | -       |
+| `--machine-user <MACHINE_USER>`                   | `-m`  | Default machine user name for application-data commands (query, workflow start, function test-run, machineuser token). Pass an empty string to clear.                 | No       | -       |
+| `--machine-user-override <MACHINE_USER_OVERRIDE>` | -     | Whether the command line or TAILOR_PLATFORM_MACHINE_USER_NAME may override the profile's machine user. 'deny' requires --machine-user; 'allow' lifts the restriction. | No       | -       |
 
 <!-- politty:command:profile update:options:end -->
 

package/docs/cli-reference.md

@@ -77,7 +77,7 @@ You can use environment variables to configure workspace and authentication:
 | `TAILOR_PLATFORM_SDK_DTS_PATH`               | Output path for generated `tailor.d.ts` type definition file                                      |
 | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                              |
 | `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                          |
-| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run`                      |
+| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run`, `machineuser token` |
 | `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count |
 | `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                       |
 | `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                  |
@@ -287,9 +287,9 @@ Commands for managing crash reports.
 
 Commands for setting up project infrastructure.
 
-| Command                                     | Description                                             |
-| ------------------------------------------- | ------------------------------------------------------- |
-| [setup github](./cli/setup.md#setup-github) | Generate GitHub Actions workflow for deployment. (beta) |
+| Command                                     | Description                                       |
+| ------------------------------------------- | ------------------------------------------------- |
+| [setup github](./cli/setup.md#setup-github) | Generate a GitHub Actions deploy workflow. (beta) |
 
 ### [Upgrade Commands](./cli/upgrade.md)
 

package/docs/github-actions.md

@@ -0,0 +1,337 @@
+# GitHub Actions Integration
+
+`tailor-sdk setup github` generates a GitHub Actions workflow that deploys your
+Tailor Platform application automatically on push or tag.
+
+> **Beta:** This command is under active development. CLI flags, the generated
+> workflow, and the `.github/tailor-sdk.lock` schema may change before general
+> availability.
+
+## Quick start
+
+Run the command from the root of your SDK project (where `tailor.config.ts`
+lives):
+
+```bash
+# Branch target: deploy to stg on every push to main
+tailor-sdk setup github -n my-app-stg
+
+# Tag target: deploy to production when a tag is pushed, with an approval gate
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+After running the command, follow the **Next steps** printed to the terminal to
+set the required secrets, set the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and
+commit the generated files.
+
+The generated workflow deploys to whichever workspace its
+`TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
+creates or renames a workspace. Provision the workspace and set that variable
+before the first deploy (see [Targeting a workspace](#targeting-a-workspace)).
+
+## Targets
+
+A _target_ is one workflow file that handles one deployment destination.
+Run `setup github` once per target.
+
+### Branch target (recommended for staging)
+
+The branch target fires on pull requests and pushes to the branch you specify
+(defaulting to the repository's default branch when `--branch` is omitted):
+
+```bash
+tailor-sdk setup github -n my-app-stg
+# Equivalent to:
+tailor-sdk setup github -n my-app-stg --branch main
+```
+
+What it does:
+
+- On **pull request**: runs `generate`, checks that generated files are
+  committed (`generate-check`), and posts a deployment plan as a PR comment.
+  (The plan and deploy jobs are independent; pull requests run plan only.)
+- On **push to the branch**: deploys. The deploy action runs `generate` and
+  applies the config; it does not re-run the PR plan.
+- On **`workflow_dispatch`** with `dry-run: true`: runs plan only (useful for
+  rollback verification — see [Rollback](#rollback)). With `dry-run: false`
+  (default) it deploys, like a push.
+
+Fork pull requests cannot read repository secrets. For forks, the plan step is
+automatically skipped; `generate-check` and other non-secret checks still run.
+
+### Tag target (recommended for production)
+
+The tag target fires when a tag matching `--tag-pattern` (default `v*`) is
+pushed:
+
+```bash
+tailor-sdk setup github -n my-app-prod \
+  --tag --tag-pattern "v*" --branch main --environment production
+```
+
+What it does:
+
+- **`tailor-tag-guard`** (generated when `--branch` is supplied): checks that
+  the tagged commit is reachable from `main`. A tag on an unrelated commit is
+  silently skipped, not an error.
+- **`tailor-plan`**: runs `generate`, `generate-check`, and posts a plan
+  summary to the Actions step summary (no PR comment, because there is no PR).
+- **`tailor-deploy`**: waits for `tailor-plan`, then deploys. If the target
+  environment has required reviewers configured, GitHub requires their approval
+  before the deploy job starts.
+- On **`workflow_dispatch`**: the `tailor-tag-guard` result is ignored — the
+  plan job runs regardless of branch reachability (useful for rolling back to
+  any tag). `dry-run: true` stops before the deploy job.
+
+### Choosing `--branch` for the tag target
+
+`--branch` has two different roles depending on the target kind:
+
+| Target | Role of `--branch`                                                                             |
+| ------ | ---------------------------------------------------------------------------------------------- |
+| Branch | The branch that triggers the workflow (push + PR base). Defaults to the repo's default branch. |
+| Tag    | The branch whose history the tag must be reachable from. Omit to disable the guard entirely.   |
+
+The workspace name (`--workspace-name`, or the config `name` when omitted) must
+be 3–63 characters of lowercase letters, numbers, and hyphens, and cannot start
+or end with a hyphen. It is used for the generated file name, the workflow
+`name:`, the plan label, and the default GitHub Environment name; it does not
+select which workspace gets deployed (see
+[Targeting a workspace](#targeting-a-workspace)).
+
+## Targeting a workspace
+
+The generated `plan` and `deploy` jobs target a workspace by **id**, read from
+the `TAILOR_PLATFORM_WORKSPACE_ID` GitHub Environment variable. They never
+resolve a workspace by name and never create one. Set this variable per
+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.
+
+1. Provision the workspace (once per environment) and obtain its id. For now
+   this is a manual step:
+
+   ```bash
+   tailor-sdk workspace create   # copy the printed workspace id
+   ```
+
+2. Set the id as the Environment variable (the environment name is your
+   `--environment` value, or the workspace name when omitted):
+
+   ```bash
+   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+   ```
+
+If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
+workspace is not provisioned, and `plan` reports that the workspace is not
+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.)
+
+## Generated files
+
+Running `setup github` creates or updates:
+
+### `.github/workflows/tailor-<workspace-name>.yml`
+
+The workflow file. The `name:` field is set to `Tailor (<workspace-name>)` so
+you can distinguish multiple workspaces in the Actions UI.
+
+Jobs and steps whose `id` starts with `tailor-` are managed by the SDK. Do not
+edit or rename them — the SDK tracks them by id.
+
+You can add your own jobs and steps around the managed ones. To add
+project-specific setup (such as private registry authentication or a system
+dependency), add a step _before_ the managed setup steps. For post-install
+extras (such as `playwright install`), add a step _after_ them.
+
+Note that re-running `setup github` currently regenerates the whole file: if
+the file differs from what the SDK last wrote — whether you edited a managed
+step or added your own — the command stops and reports the conflict. Pass
+`--force` to discard your edits and regenerate from the current template, then
+re-apply your own steps. (Preserving user-added steps across regeneration is
+planned.)
+
+### `.github/tailor-sdk.lock`
+
+A machine-owned JSON file that tracks which files the SDK manages, the inputs
+they were generated from, and their content hashes. **Commit this file. Never
+edit it by hand.** The SDK uses it to recognize its own files on re-runs and to
+detect hand edits.
+
+### `tailor.config.ts` (id injection)
+
+If your config does not already have an `id` field, `setup github` injects one.
+This `id` must be committed alongside the workflow file. In CI, `tailor-sdk
+deploy` refuses to inject a new id — if the id were assigned fresh on each CI
+run, every deploy would create a brand-new application and lose ownership of
+previously deployed resources.
+
+If your pipeline intentionally deploys a fresh, throwaway application on every
+run (for example an end-to-end test harness that creates and deletes its own
+workspace), set `TAILOR_PLATFORM_SDK_ALLOW_CI_ID_INJECTION=true` to opt back
+into automatic id injection for that pipeline.
+
+## Secrets
+
+The generated workflow reads two secrets:
+
+| 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) with the GitHub CLI:
+
+```bash
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
+```
+
+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.
+
+## GitHub Environments (approval gate)
+
+Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
+`--environment` value, or the workspace name when omitted. The environment holds
+that target's `TAILOR_PLATFORM_WORKSPACE_ID` variable and machine-user secrets,
+and lets you:
+
+- **Require reviewer approval** before the jobs run (suitable for production).
+- **Scope secrets and the workspace-id variable** to specific environments so
+  staging and production deploy to separate workspaces with separate machine
+  users.
+
+To configure the environment, go to your repository's **Settings → Environments**
+and create an environment whose name matches the target's environment. Add
+required reviewers, the `TAILOR_PLATFORM_WORKSPACE_ID` variable, and the
+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.)
+
+## Manual runs and dry-run
+
+You can trigger the workflow manually from **Actions → Run workflow**. The
+`dry-run` input (boolean, default `false`) runs the plan job without
+deploying. Use this to preview what would change before executing a rollback
+or an out-of-band deploy. With `dry-run` off, a branch-target dispatch goes
+straight to deploy (like a push), while a tag-target dispatch runs plan first
+and then deploys.
+
+For tag targets, you can select any branch or tag when dispatching manually. The tag-guard check is skipped for manual dispatches, so
+you can deploy any commit regardless of branch membership.
+
+## Monorepo setup
+
+For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
+
+```bash
+tailor-sdk setup github -n my-app --dir apps/backend
+```
+
+The generated workflow adds a `paths` filter on `apps/backend/**` so the
+workflow only runs when that subdirectory changes. The `working-directory` for
+SDK commands is set accordingly.
+
+## Rollback
+
+`tailor-sdk deploy` is declarative: redeploying a past configuration returns
+the platform to that state. The recommended rollback approaches are:
+
+### Option 1 — Revert the commit (branch target)
+
+```bash
+git revert <commit-sha>
+git push
+```
+
+The push triggers the deploy job, which applies the reverted configuration. To
+preview the diff first, open the revert as a pull request (the plan job comments
+the diff) or use a `dry-run: true` manual dispatch before merging.
+
+### Option 2 — Advance the tag (tag target)
+
+Move the production tag to an earlier commit:
+
+```bash
+git tag -f v1.2.3 <earlier-commit-sha>
+git push --force-with-lease origin v1.2.3
+```
+
+Or create a new tag that points to the earlier commit:
+
+```bash
+git tag v1.2.4 <earlier-commit-sha>
+git push origin v1.2.4
+```
+
+### Option 3 — Manual dispatch with dry-run verification
+
+1. Go to **Actions → `Tailor (<workspace-name>)` → Run workflow**.
+2. Enter the tag or ref you want to redeploy.
+3. Set `dry-run` to `true` and run. Inspect the plan output.
+4. Run again with `dry-run` set to `false`.
+
+For tag targets, the tag-guard step is bypassed on manual dispatch, so you can
+dispatch from any ref. Environment approval (if configured) applies as usual.
+
+### Rollback limitations
+
+- **Schema and data are not rolled back.** If the older config expects a schema
+  state that no longer exists, the plan may show errors. In that case, review
+  the diff carefully before proceeding.
+- **Seed data** is not part of the deployment pipeline and is unaffected by
+  rollbacks.
+- **Static websites** are not yet integrated into the generated pipeline.
+  Static asset rollbacks must be performed manually.
+
+## Multi-environment example
+
+A typical setup with staging and production:
+
+```bash
+# Staging: main → stg (deploy on every push to main)
+tailor-sdk setup github -n my-app-stg
+
+# Production: tagged commits → prod, with approval gate and branch guard
+tailor-sdk setup github -n my-app-prod \
+  --tag --branch main --environment production
+```
+
+Then provision each workspace and set its id on the matching environment (the
+staging target's environment defaults to `my-app-stg`; production uses
+`production`):
+
+```bash
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env my-app-stg
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env my-app-stg
+
+gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID --env production
+gh secret set TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET --env production
+```
+
+Commit both workflow files and `.github/tailor-sdk.lock`.
+
+## Updating the generated workflow
+
+When you upgrade the SDK, re-run `setup github` with the same flags to pick up
+template improvements. If the SDK detects that you have hand-edited a managed
+section, it stops and asks you to use `--force` to overwrite your edits, or to
+move your customizations into your own steps before regenerating.
+
+The `.github/tailor-sdk.lock` file records the flags used at generation time,
+so you can check what arguments were used previously.