@tailor-platform/sdk 2.23.0 → 2.25.0

package/docs/github-actions.md

@@ -33,9 +33,11 @@ tailor setup ci tag --name my-app-prod \
   --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.
+After running the command, follow the **Next steps** printed to the terminal:
+run `tailor setup ci env` to get the commands that set the secrets and
+variables each GitHub Environment needs (see
+[Setting secrets and variables](#setting-secrets-and-variables)), then commit
+the generated files.
 
 The generated workflow deploys to whichever workspace its
 `TAILOR_PLATFORM_WORKSPACE_ID` Environment variable points at — it never
@@ -170,10 +172,13 @@ Because the variable is scoped to a GitHub Environment, both the `plan` and
    ```
 
 2. Set the id as the Environment variable (the environment name is your
-   `--environment` value, or the workspace name when omitted):
+   `--environment` value, or the workspace name when omitted).
+   `tailor setup ci env` prints this command together with the other secrets
+   and variables each environment needs (see
+   [Setting secrets and variables](#setting-secrets-and-variables)):
 
    ```bash
-   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env my-app-stg
+   gh variable set TAILOR_PLATFORM_WORKSPACE_ID --env=my-app-stg
    ```
 
 If `TAILOR_PLATFORM_WORKSPACE_ID` is unset, `deploy` fails because the target
@@ -194,6 +199,14 @@ Running a workflow setup subcommand creates or updates:
 The workflow file. The `name:` field is set to `Tailor (<workspace-name>)` so
 you can distinguish multiple workspaces in the Actions UI.
 
+Every checkout in the workflow sets `persist-credentials: false`, so the GitHub
+token is not left in `.git/config` while the job installs and runs your
+project's code. The tag guard step passes the job token only to its
+`git fetch`, and the plan step passes it to its `git fetch` and to the step that
+posts the plan comment on the pull request; neither writes it to `.git/config`.
+If installing your dependencies fetches git repositories
+that require authentication, configure the credentials in your own step.
+
 See [Customizing the generated workflow](#customizing-the-generated-workflow)
 for what you can edit.
 
@@ -204,39 +217,83 @@ top-level keys it writes (`name:`, `on:`, and `permissions:` in a workflow; the
 metadata, inputs, and outputs of a composite action). Do not edit or rename
 them. Everything else is yours, and re-running `setup` keeps it:
 
-- **Your own jobs and steps.** Add them anywhere, without the `tailor-` prefix.
-  A step you add inside a managed job stays right after the managed step it
+- **Your own jobs and steps.** Add them anywhere, with an `id` (if any) that
+  does not start with `tailor-`: the prefix is reserved for the SDK, even in a
+  job of your own. A step you add inside a managed job stays right after the managed step it
   followed. For example, add private registry authentication or a system
   dependency _before_ the managed `tailor-setup` step, and post-install extras
   (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:`.
 - **Runtime settings of managed jobs:** `runs-on`, `timeout-minutes`,
-  `container`, and `env`.
+  `container`, and `env`. On a managed job generated without an
+  `environment:` (such as `tailor-tag-guard` or `tailor-erd-preview`), you can
+  also add one, for example so a step you added there can read that GitHub
+  Environment's secrets. The `environment:` of `tailor-plan`, `tailor-deploy`,
+  and the preview jobs comes from `--environment`, so change it with that
+  option instead.
 - **These inputs of managed steps:** `ignore` on `tailor-generate-check` and
   `tailor-drift-check`, `fail-on-drift` on `tailor-drift-check`,
   `install-command` on `tailor-install`, `node-version-file` on
   `tailor-setup`, `label` on `tailor-plan`, and `user-mapping` on
   `tailor-notify` and on a coordinator's steps that call an app action.
-- **The `run:` command of the `build-site` step** in a composite action.
+- **The `run:` command of the `tailor-build-site` step** in a composite action.
+
+In a preview workflow, the `tailor-preview-deploy` job exposes the per-PR
+workspace as the outputs `workspace-id`, `workspace-name`, and `app-url`, so a
+job of your own can run tests or deploy extra assets against it:
+
+```yaml
+deploy-assets:
+  needs: tailor-preview-deploy
+  runs-on: ubuntu-latest
+  environment: my-app
+  env:
+    TAILOR_PLATFORM_WORKSPACE_ID: ${{ needs.tailor-preview-deploy.outputs.workspace-id }}
+    TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID: ${{ secrets.TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID }}
+    TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET: ${{ secrets.TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET }}
+  steps:
+    # checkout, dependency installation, and your tailor commands
+```
+
+A job that runs `tailor` against the workspace needs the machine-user
+[secrets](#secrets), so it declares the preview target's GitHub Environment
+(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 draft and fork pull requests, and for unlabeled ones with
+`--require-preview-label`.
+
+Likewise, the `tailor-deploy` job of a branch or tag workflow exposes the
+deployed workspace as the outputs `workspace-id` and `app-url` to a job with
+`needs: tailor-deploy`. Reading them does not require the target's GitHub
+Environment; a job that runs `tailor` against the workspace declares it for the
+machine-user secrets, as in the preview example above.
 
 Comments above your own jobs and steps and at the end of the file are kept too.
 Comments inside managed jobs and steps, and edits to the header comment, are
 not kept.
 
 `setup check` reports an edit to a managed part, and re-running `setup` stops
-on it. Revert the edit, or pass `--force` to reset the managed parts to the
-current template; `--force` still keeps your own jobs, steps, and settings.
-A managed job or step you renamed counts as your own, so `--force` adds the
-managed one back next to it; rename it back instead of forcing. To start over
-from a clean template, delete the file and re-run `setup`.
+on it; both name the edited job, step, or top-level key. Revert the edit, or
+pass `--force` to reset the managed parts to the current template; `--force`
+still keeps your own jobs, steps, and settings. A managed step you renamed to
+an id without the `tailor-` prefix counts as your own, so `--force` adds the
+managed one back next to it; rename it back instead of forcing. A managed job
+you renamed still holds the SDK's `tailor-` steps, so `setup check` reports
+them as reserved ids and `setup` stops on them, even with `--force`; rename the
+job back. To start over from a clean template, delete the file and re-run
+`setup`.
 
 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. It also stops when a new template version adds
-a managed job or step whose id you already use; rename yours, or pass `--force`
-to let the managed one replace it.
+steps left inside a removed job.
+
+`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
+not rename or remove it.
 
 Files generated by an older SDK version are compared as a whole, so the first
 re-run after upgrading stops if you edited the file in any way. Re-run once with
@@ -296,7 +353,8 @@ the move.
 
 ## Secrets
 
-The generated workflow reads two secrets:
+The generated workflow requires two secrets (the optional Slack token is listed in
+[Setting secrets and variables](#setting-secrets-and-variables)):
 
 | Secret                                       | Description                |
 | -------------------------------------------- | -------------------------- |
@@ -304,12 +362,8 @@ The generated workflow reads two secrets:
 | `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
-```
+workspace name when omitted); `tailor setup ci env` prints the commands (see
+[Setting secrets and variables](#setting-secrets-and-variables)).
 
 Setting them at the environment level isolates each target's credentials and
 keeps them alongside that environment's `TAILOR_PLATFORM_WORKSPACE_ID`
@@ -317,6 +371,62 @@ variable. You can also set them as repository-level secrets if every target
 shares one machine user, but then any workflow on any branch can read them, so
 the environment's protection rules no longer guard your deploys.
 
+### Setting secrets and variables
+
+`tailor setup ci env` reads `.github/tailor.lock` and prints, for every GitHub
+Environment the generated workflows use, the commands that create the
+environment (only when it does not exist yet) and set its secrets and
+variables. It is read-only, so re-run it whenever you add a target. When the
+`origin` remote points at github.com, the output names that repository, so the
+commands work from any directory; otherwise `gh` resolves the repository from
+the current directory and the Terraform output leaves it as a placeholder.
+
+```bash
+tailor setup ci env                          # gh CLI commands (default)
+tailor setup ci env --format terraform       # Terraform for the integrations/github provider
+tailor setup ci env --environment my-app-stg # only one environment (repeat for several)
+```
+
+The list follows what each generated workflow actually reads:
+
+| Name                                         | Kind     | Targets                 | Required | Where the value comes from                                                                                                                                                                                                           |
+| -------------------------------------------- | -------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | secret   | all                     | yes      | Client ID of the platform machine user CI signs in as; it needs an editor or admin role on the organization or folder that holds the workspace. Contact [Tailor support](https://docs.tailor.tech/administration/support) to get one |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | secret   | all                     | yes      | Client secret of the same platform machine user                                                                                                                                                                                      |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | variable | branch, tag, coordinate | yes      | `id` printed by `tailor workspace create`, or listed by `tailor workspace list`                                                                                                                                                      |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`            | variable | preview                 | yes      | Organization to create the per-PR workspaces in (a machine user cannot create a workspace without one): `organizationId` listed by `tailor organization list`                                                                        |
+| `TAILOR_PLATFORM_FOLDER_ID`                  | variable | preview                 | no       | Folder to create the per-PR workspaces in: `id` listed by `tailor organization folder list -o <organization id>`. When unset they go directly under the organization, which needs the machine user's role on the organization itself |
+| `TAILOR_PLATFORM_FAIL_ON_DRIFT`              | variable | all                     | no       | `true` to fail the drift check when it finds drift                                                                                                                                                                                   |
+| `TAILOR_SLACK_BOT_TOKEN`                     | secret   | branch, tag, coordinate | no       | Bot User OAuth Token (`xoxb-...`) of a Slack app with the `chat:write` scope                                                                                                                                                         |
+| `TAILOR_SLACK_CHANNEL_ID`                    | variable | branch, tag, coordinate | no       | Channel ID (`C...`) from the channel details in Slack; invite the bot to the channel                                                                                                                                                 |
+| `TAILOR_SLACK_USER_MAPPING`                  | variable | branch, tag             | no       | JSON object mapping GitHub usernames to Slack member IDs (for example `{"alice":"U0123456"}`) so notifications mention the actor; read only after you uncomment the `user-mapping` input of the `tailor-notify` step                 |
+
+See [Account management](https://docs.tailor.tech/administration/account-management)
+for how organizations, folders, workspaces, and machine users relate.
+
+Composite actions (`setup ci action`) read nothing themselves; the coordinator
+that calls them does. Set `TAILOR_SLACK_BOT_TOKEN` and `TAILOR_SLACK_CHANNEL_ID`
+together to enable Slack deploy notifications.
+
+The `gh` output creates an environment only when GitHub reports it missing and
+leaves optional entries commented out. Run the commands one at a time: each
+`gh secret set` / `gh variable set` prompts for its value.
+
+The Terraform output takes every value from an input variable (secrets are
+`sensitive`) and creates an optional entry only when its variable is set, so no
+value is written to the output. Terraform still stores the secret values in its
+state in plain text, so keep the state encrypted and access-restricted, or set
+the secrets with the `gh` output instead. Its header lists the steps with the variable
+names for your environments: authenticate the provider, put non-secret values in
+`terraform.tfvars`, pass secrets as `TF_VAR_<name>` environment variables, and
+import each environment and variable that already exists (for example
+`terraform import github_repository_environment.production my-repo:production`)
+before `terraform apply`: creating a variable that already exists fails, while
+secrets are overwritten. The generated environments ignore changes to their
+protection settings (reviewers, wait timer, branch policy), so importing an
+environment keeps the approval gate you configured; remove the `lifecycle` block
+to manage those settings in Terraform instead.
+
 ## GitHub Environments (approval gate)
 
 Both the `plan` and `deploy` jobs are associated with a GitHub Environment — the
@@ -382,9 +492,61 @@ For a monorepo where your SDK app lives in a subdirectory, pass `--dir`:
 tailor setup ci branch --name 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.
+The `working-directory` for SDK commands is set accordingly, and the workflow
+only plans and deploys when that subdirectory changes. The workflow itself
+starts on every pull request and push: a `tailor-changes` job checks whether
+the change touches `apps/backend/**`, and the plan, deploy, and ERD preview jobs
+are skipped when it does not. A skipped job reports success, so you can make
+these checks required in branch protection; a workflow that a `paths` trigger
+filter never started would leave them pending instead. If the `tailor-changes` job
+itself fails (for example, on a GitHub API error), the plan, deploy, and ERD
+preview jobs fail too instead of being skipped, so a required check blocks
+merging and nothing is deployed. Re-run the failed jobs once the cause is gone.
+
+### Deploying several apps together
+
+To deploy several apps to the same workspace from one workflow, repeat `--dir`
+and pass `--name` for the workflow:
+
+```bash
+tailor setup ci branch --name erp --dir apps/erp/backend --dir apps/users/backend
+```
+
+`setup ci branch`, `setup ci tag`, and `setup ci preview` accept repeated
+`--dir`. The workflow plans and deploys every app's `tailor.config.ts` in one
+[multi-config deploy](./cli/application.md#deploy) from the repository root, so
+an app can reference resources of another app with `external: true`. Add
+`@tailor-platform/sdk` to the root `package.json` so the `tailor` CLI resolves
+there; setup stops until it is declared. The generate check runs for each app
+directory, as do seed validation and the migration drift check on branch and tag
+workflows, and a change under any app directory runs the workflow's jobs.
+
+With `--erd-preview`, each TailorDB namespace is previewed from the app that
+owns it. A namespace may be owned by only one app; the others reference it with
+`external: true`.
+
+With more than one app, the preview comment does not link an application URL.
+
+### Running on changes outside the app directories
+
+When the apps depend on code outside their directories, such as a frontend or
+shared packages, add those paths with `--paths` on `setup ci branch` or
+`setup ci preview`. Repeat it for each pattern:
+
+```bash
+tailor setup ci preview --name erp --region asia-northeast \
+  --dir apps/erp/backend --dir apps/users/backend \
+  --paths "apps/*/frontend/**" --paths "modules/**" --paths pnpm-lock.yaml
+```
+
+The patterns are checked after the app directories, in order, and the last
+pattern that matches a changed file decides whether it counts. `*` matches
+within one path segment, `**` matches any number of segments, and a pattern
+starting with `!` excludes matching paths, so it can also exclude files inside
+an app directory, for example `--paths '!apps/erp/backend/**/*.md'`. Other glob
+characters (`?`, `+`, `[ ]`, `{ }`, `( )`, and `\`) are not supported, and
+`setup ci` rejects a pattern that contains them. An app at the repository root already
+runs on every change, so `--paths` is not accepted with `--dir .`.
 
 ## Rollback
 
@@ -453,18 +615,13 @@ tailor setup ci tag --name my-app-prod \
   --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`):
+Then provision each workspace and set its id and the machine-user credentials
+on the matching environment (the staging target's environment defaults to
+`my-app-stg`; production uses `production`). `tailor setup ci env` prints the
+commands for both environments:
 
 ```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
+tailor setup ci env
 ```
 
 Commit both workflow files and `.github/tailor.lock`.
@@ -502,19 +659,21 @@ them. To remove it, delete the file.
 
 Renovate updates the SDK dependency and action pins, but it does not regenerate
 the workflow template. After an SDK update, `tailor setup check` reports a
-template-version warning until you re-run the relevant workflow setup
-subcommand.
+template-version warning until you run
+[`tailor setup update`](#updating-the-generated-workflow).
 
 ## Checking for drift
 
 `tailor setup check` audits the workflows recorded in
 `.github/tailor.lock` against your current config and repository, without
 writing anything. It reports when a workflow file is missing or its SDK-managed
-parts were edited by hand, a
-newer template is available, `tailor.config.ts` is no longer under the recorded
+parts were edited by hand, a job or step of yours uses the reserved `tailor-`
+prefix, a newer template is available, `tailor.config.ts` is no longer under the recorded
 `--dir`, or the repository default branch no longer matches a branch target's
 trigger. It exits non-zero when it finds drift, so you can run it in CI. Each
-finding names a stable rule key for future suppression.
+finding names a stable rule key for future suppression. Run
+[`tailor setup update`](#updating-the-generated-workflow) to regenerate the
+targets it reports.
 
 Workflows generated by `setup ci branch`, `setup ci tag`, `setup ci preview`, and
 `setup ci coordinate` self-audit: each contains a `tailor-drift-check` step that
@@ -529,21 +688,42 @@ Drift findings are advisory by default. Set the repository variable
 `TAILOR_PLATFORM_FAIL_ON_DRIFT` to `true` to make unsuppressed findings fail
 the job. Execution and configuration errors fail regardless of this variable.
 
-Running `check` on your own machine also verifies that
-`TAILOR_PLATFORM_WORKSPACE_ID` is set locally for any branch, tag, or
-coordinate target, since those workflows read it directly. `check` detects on
-its own when it is running in CI (no flag needed) and skips that local-only
-verification there, since the deploy job resolves the Environment variable
-itself at runtime.
+`check` compares only the generated files, `.github/tailor.lock`, and the
+config; it does not read the GitHub Environment secrets and variables, so it
+runs the same on your own machine and in CI. Run `tailor setup ci env` to list
+what each environment needs.
 
 ## Updating the generated workflow
 
-When you upgrade the SDK, re-run the relevant workflow setup subcommand with
-the same flags to pick up template improvements. Your own jobs, steps, and
-settings are kept (see
-[Customizing the generated workflow](#customizing-the-generated-workflow)). If
-you edited a managed part, the command stops; revert the edit or pass `--force`
-to reset it.
+When you upgrade the SDK, run `tailor setup update` from the repository root to
+pick up template improvements:
+
+```bash
+tailor setup update
+```
 
-The `.github/tailor.lock` file records the flags used at generation time,
-so you can check what arguments were used previously.
+It regenerates every workflow and composite action recorded in
+`.github/tailor.lock` with the flags each one was generated with, so you do not
+have to re-type `setup ci branch`, `setup ci tag`, and the rest one by one.
+Your own jobs, steps, and settings are kept (see
+[Customizing the generated workflow](#customizing-the-generated-workflow)). A
+branch that was detected from the repository default branch is detected again,
+and the parts that follow your config — the migration drift check, seed
+validation, static website builds, and ERD preview namespaces — are derived
+from the current `tailor.config.ts`.
+
+A target that cannot be regenerated, for example because you edited a managed
+part, does not stop the others: `update` regenerates the rest, then lists the
+targets it could not update and exits non-zero. Revert the edit, or run
+`tailor setup update --force` to reset the managed parts of every target.
+
+Coordinators generated by an older plugin version did not record how their
+`--action` values were grouped, so `update` lists them instead of guessing
+which apps deploy together. Re-run `tailor setup ci coordinate` once with all
+of its original flags and its original `--action` groups. The message `update`
+prints fills in the recorded flags (`--tag`, `--branch`, `--environment`,
+`--restrict-dispatch`), so you only add the `--action` values. Later updates
+pick the grouping up from the lock.
+
+To change a flag for one target, re-run its `setup ci` subcommand with the new
+flags. `.github/tailor.lock` records them, and later updates reuse them.

package/docs/migration/v3.md

@@ -128,6 +128,52 @@ property, which is the relation's cardinality (e.g. "n-1", "1-1",
 
 </details>
 
+## defineConfig inlineSourcemap / logLevel → buildOptions
+
+**Migration:** Partially automatic
+
+Move the top-level `inlineSourcemap` and `logLevel` of `defineConfig()` into `buildOptions`, which groups the settings that control how functions are bundled. The top-level fields keep working until they are removed in v3; setting the same option in both places is rejected.
+
+Before:
+
+```ts
+export default defineConfig({
+  name: "my-app",
+  inlineSourcemap: false,
+  logLevel: "WARN",
+});
+```
+
+After:
+
+```ts
+export default defineConfig({
+  name: "my-app",
+  buildOptions: {
+    inlineSourcemap: false,
+    logLevel: "WARN",
+  },
+});
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v3, the top-level `inlineSourcemap` and `logLevel` options of
+`defineConfig()` from `@tailor-platform/sdk` are removed in favor of
+`buildOptions.inlineSourcemap` and `buildOptions.logLevel`. For each flagged
+config, move those two properties into a `buildOptions` object (create it if
+it does not exist) without changing their values. When the config is built
+from a variable or a spread, move them in the object that actually defines
+them. If an option is set both at the top level and in `buildOptions`, keep
+the value that the deployed app should use and delete the other; the build
+rejects a config that sets both. Leave `logLevel` options of other tools
+(for example a Vite or Vitest config) unchanged.
+```
+
+</details>
+
 ## String file uploads → explicit encoding
 
 **Migration:** Manual

package/docs/multi-environment.md

@@ -64,7 +64,9 @@ tailor deploy -w <production-workspace-id> --env-file .env.production
 ```typescript
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  buildOptions: {
+    logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
+  },
 });
 ```
 

package/docs/plugin/custom.md

@@ -6,7 +6,7 @@ Create your own plugins by implementing the `Plugin` interface.
 
 ## Requirements
 
-**Plugins must use default export**:
+**Plugins with definition-time hooks must use default export**:
 
 ```typescript
 // plugin.ts
@@ -48,6 +48,9 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
   onExecutorReady?(
     context: ExecutorReadyContext<PluginConfig>,
   ): GeneratorResult | Promise<GeneratorResult>;
+  onDeployed?(
+    context: DeployedContext<PluginConfig>,
+  ): void | DeployedHookResult | Promise<void | DeployedHookResult>;
 }
 ```
 
@@ -254,6 +257,78 @@ onExecutorReady(ctx) {
 },
 ```
 
+### onDeployed
+
+Runs once after every application in the deploy has been applied, including when
+there are no resource changes. Hooks run sequentially in config order, then in
+`definePlugins()` registration order. No `importPath` or table attachment is required.
+
+Use `ctx.application` for the registering application's ID, URL, domain, AI
+Gateway URLs, static websites, and public OAuth client IDs. `ctx.application.id`
+is the `id` from `defineConfig()` and is `undefined` when the config has none.
+`ctx.applications` contains all applications in a multi-config deploy with the
+same fields. OAuth client secrets are never included.
+
+`ctx.configPath` is the absolute path of the registering config. `ctx.workspaceId`
+and `ctx.pluginConfig` identify the deployment workspace and the plugin's options.
+Use `ctx.logger.info`, `warn`, and `success` for diagnostics; they write to stderr
+and preserve deploy's JSON stdout.
+
+```typescript
+import { definePlugins, type Plugin } from "@tailor-platform/sdk";
+
+const deployedInfo: Plugin = {
+  id: "@example/deployed-info",
+  description: "Reports the deployed application URL",
+  onDeployed(ctx) {
+    const url = ctx.application.url;
+    if (!url) return;
+    ctx.logger.success(`Application ready: ${url}`);
+    return { outputs: { url } };
+  },
+};
+
+export const plugins = definePlugins(deployedInfo);
+```
+
+To publish assets, look up the site with `ctx.application.staticWebsites[name]`
+and await its `publish(dir)` with an absolute directory path. Only websites
+declared in the registering config appear there; any other name is `undefined`,
+so check the site before publishing. Websites of other configs are listed under
+`ctx.applications` with their `name` and `url` only, so a plugin can read their
+URLs but cannot publish to them. The result contains `url` and `skippedFiles`; report skipped
+files so users can correct files that could not be uploaded.
+
+To run a shell command such as a build, await `ctx.exec(command, { workingDir, env })`.
+It rejects when the command exits with a non-zero code. By default the command's
+stdout and stderr both go to stderr so `tailor deploy --json` stdout stays parseable;
+pass `output: "capture"` to receive them as `stdout` and `stderr` instead, or
+`output: "ignore"` to discard them. Use `ctx.exec` rather than importing
+`node:child_process` in the plugin: `tailor.config.ts` is also bundled into
+functions that run on the Tailor Platform, such as auth hooks, and a plugin module
+that imports Node.js-only modules makes that bundle fail.
+
+Return JSON-serializable `outputs` to include a result in `deployedHooks` under
+`tailor deploy --json`. Each entry identifies the application and plugin. This
+key is omitted when no hook supplies outputs. `outputs` must be a plain object whose
+values are only strings, finite numbers, booleans, `null`, arrays, and plain objects;
+any other value, such as `undefined`, a function, or a `Date`, fails the hook.
+Output values may be typed with an `interface`. The type checker rejects a
+`Date`, function, `Map`, or other non-JSON value placed directly in `outputs` or in
+an object or array literal, but a `Date` or class instance nested inside an
+interface-typed value is caught only when `tailor deploy` runs the hook.
+
+A failed hook stops later hooks with `DEPLOYED_HOOK_FAILED`. The same error is
+reported when the deployed information passed to hooks cannot be loaded. Platform
+resources have already been applied and are not rolled back. The error lists any hooks
+that did not run, with the application each belongs to. Fix the hook and run `tailor deploy` again; hooks run again even
+if there are no resource changes.
+
+Hooks do not run during dry-run, build-only, or migration test deployments.
+Dry-run lists the pending hooks; with `--json`, they appear under
+`pendingDeployedHooks` as `{ application, pluginId }` entries. Calling `deploy()` from the programmatic CLI
+API runs hooks under the same conditions as `tailor deploy`.
+
 ## Hook Scheduling Rules
 
 Each generation-time hook runs at its own pipeline phase, regardless of what other hooks the same plugin implements: