@tailor-platform/sdk 2.30.0 → 2.33.0

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/tailordb.md

@@ -328,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/workspace.md

@@ -107,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/github-actions.md

@@ -117,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
@@ -501,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.

package/docs/plugin/custom.md

@@ -90,6 +90,40 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
 | `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
 | `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |
 
+Resolvers returned by `onTableLoaded` or `onNamespaceLoaded` are loaded, bundled, and deployed to
+the resolver namespace (a `resolver` key in your config) with the same name as the hook's TailorDB
+namespace (a `db` key). These are separate namespaces that only share the name: with
+`db: { main: ... }` and `resolver: { billing: ... }`, generated resolvers go to a `main` resolver
+namespace, not `billing`. If you configure a resolver namespace with that name, generated resolvers
+join its configured files and use its `defaultPermission`. Otherwise, a resolver namespace is created
+automatically. Configure `defaultPermission` to restrict access; without it, generated resolvers are
+accessible to anonymous callers, like regular resolvers with no permission declared. Generating into
+an external resolver namespace or duplicating a resolver name within a namespace fails the build.
+
+For example, a namespace hook can return a query using `t` field builders:
+
+```typescript
+onNamespaceLoaded() {
+  return {
+    resolvers: [{
+      name: "greet",
+      operation: "query",
+      inputFields: { name: t.string() },
+      outputFields: { message: t.string() },
+      body: 'return { message: `Hello, ${context.input.name}!` };',
+    }],
+  };
+}
+```
+
+The `body` string contains JavaScript statements with access to `context.input`, `context.caller`,
+`context.invoker`, and `context.env`. It can use `await` and platform globals, but cannot capture
+plugin-local variables. Embed configuration values as literals with `JSON.stringify` when building
+the string. Field validators must also be self-contained: they can use their arguments and standard
+JavaScript globals, and references to other names are rejected during generation. Input validation and date conversion follow the same rules as regular
+resolvers. Invalid field definitions or JavaScript syntax fail the build with the plugin and namespace
+identified in the error.
+
 Tables in `tables` are validated as complete TailorDB table definitions before registration.
 Fields in `extends.fields` are validated as part of the resulting source table. You can return a
 table builder directly or a structural copy such as `{ ...db.table(...) }`; a copy is accepted as

package/docs/plugin/index.md

@@ -102,6 +102,7 @@ export const plugins = definePlugins(
 Plugins can generate:
 
 - **Tables**: Additional TailorDB tables (e.g., `CustomerHistory`, `Deleted_Customer`)
+- **Resolvers**: Queries and mutations
 - **Executors**: Event handlers triggered by record changes
 - **Field Extensions**: Additional fields added to the source table
 - **Output Files**: TypeScript code and other files via generation-time hooks

package/docs/services/staticwebsite.md

@@ -78,7 +78,37 @@ defineStaticWebSite("my-website", {
 
 After deploying, use `tailor staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.
 
-A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment).
+A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment). To hand a domain to another site or workspace without taking it offline, see [Moving a domain](#moving-a-domain).
+
+### Moving a domain
+
+A domain already serving traffic can be moved to another static website — in this workspace or another one — without downtime, without reissuing its certificate and without changing DNS. The site that currently holds the domain offers it; the receiving site accepts by listing the domain normally.
+
+On the side giving the domain up, replace the plain entry with the destination:
+
+```typescript
+defineStaticWebSite("my-website", {
+  customDomains: [{ domain: "app.example.com", transferTo: { workspaceId: "..." } }],
+});
+```
+
+Deploying opens the offer. On the receiving side, list the domain as usual and deploy:
+
+```typescript
+defineStaticWebSite("new-website", {
+  customDomains: ["app.example.com"],
+});
+```
+
+That deploy completes the move. The next plan on the giving side reports that the domain moved, and the entry should then be deleted — it describes a move that already happened, not ongoing state.
+
+The two deploys must be separate runs, even when both sites live in the same workspace: the receiving side cannot accept an offer that the same run is still opening, and `tailor deploy` says so rather than failing partway.
+
+These rules apply while an offer is open:
+
+- An offer expires after 7 days. Deploying the entry again after that opens a fresh offer.
+- Neither the domain nor the static website holding it can be removed. Change the entry back to a plain string and deploy to withdraw the offer first; `tailor deploy` and `tailor remove` both refuse before changing anything.
+- An offer takes a moment to become ready. Until it is, the receiving side cannot accept it and its deploy is refused; the giving side's plan says so.
 
 ## Type-safe URL References