@tailor-platform/sdk 2.0.0-next.4 → 2.0.0-next.6

package/docs/cli/application.md

@@ -38,10 +38,9 @@ tailor generate [options]
 
 **Options**
 
-| Option              | Alias | Description                                    | Required | Default              |
-| ------------------- | ----- | ---------------------------------------------- | -------- | -------------------- |
-| `--config <CONFIG>` | `-c`  | Path to SDK config file                        | No       | `"tailor.config.ts"` |
-| `--watch`           | `-W`  | Watch for type/resolver changes and regenerate | No       | `false`              |
+| Option              | Alias | Description             | Required | Default              |
+| ------------------- | ----- | ----------------------- | -------- | -------------------- |
+| `--config <CONFIG>` | `-c`  | Path to SDK config file | No       | `"tailor.config.ts"` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
@@ -57,19 +56,66 @@ tailor deploy [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 SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                         | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
-| `--dry-run`                     | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
-| `--no-schema-check`             | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
-| `--no-validate`                 | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
-| `--no-cache`                    | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
-| `--clean-cache`                 | -     | Clean the bundle cache before building                                               | 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 SDK config file. Use comma-separated paths to deploy multiple apps together. | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                                 | `-y`  | Skip confirmation prompts                                                            | No       | `false`              | -                                 |
+| `--create-workspace`                    | -     | Create a workspace when the account has none                                         | No       | -                    | -                                 |
+| `--workspace-name <WORKSPACE_NAME>`     | -     | Name for a workspace created during deploy                                           | No       | -                    | -                                 |
+| `--workspace-region <WORKSPACE_REGION>` | -     | Region for a workspace created during deploy                                         | No       | -                    | -                                 |
+| `--organization-id <ORGANIZATION_ID>`   | -     | Organization ID for a workspace created during deploy                                | No       | -                    | `TAILOR_PLATFORM_ORGANIZATION_ID` |
+| `--folder-id <FOLDER_ID>`               | -     | Folder ID for a workspace created during deploy                                      | No       | -                    | `TAILOR_PLATFORM_FOLDER_ID`       |
+| `--dry-run`                             | `-d`  | Run the command without making any changes                                           | No       | -                    | -                                 |
+| `--no-schema-check`                     | -     | Skip schema diff check against migration snapshots                                   | No       | -                    | -                                 |
+| `--no-validate`                         | -     | Skip client-side validation against platform resource constraints                    | No       | -                    | -                                 |
+| `--no-cache`                            | -     | Disable bundle caching for this run                                                  | No       | -                    | -                                 |
+| `--clean-cache`                         | -     | Clean the bundle cache before building                                               | No       | -                    | -                                 |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Workspace Selection:**
+
+After validating the configuration file, `deploy` resolves a workspace before bundling the
+application. Explicit configuration takes precedence in this order: `--workspace-id`,
+`TAILOR_PLATFORM_WORKSPACE_ID`, and the selected profile. Otherwise, `deploy` reuses the workspace
+previously selected for that configuration from project-local state. Each config file keeps an
+independent selection, including when multiple configs share a directory. An explicit workspace also
+updates this selection. Saved selections are verified against the workspaces currently visible to
+the authenticated user before reuse, and `deploy` warns when it uses one.
+
+When the project has no saved selection, `deploy` discovers the account's workspaces:
+
+- One or more workspaces open a selection prompt in an interactive terminal, with an option to
+  create a new workspace. With one workspace in non-interactive or JSON mode, it is selected
+  automatically. With multiple workspaces, pass `--workspace-id` instead.
+- No workspaces open a guided creation flow in an interactive terminal. The flow asks for a name,
+  fetches the available regions from the Platform, and confirms before creating anything. After
+  creation, the output shows how to reuse the workspace with `--workspace-id` or
+  `TAILOR_PLATFORM_WORKSPACE_ID` from CI or another machine.
+
+In CI and other non-interactive environments, workspace creation must be explicit:
+
+```bash
+tailor-sdk deploy \
+  --create-workspace \
+  --workspace-name example-workspace \
+  --workspace-region us-west
+```
+
+`--create-workspace` only creates when the account has no workspace. If the existing workspace
+matches the requested name, region, organization, and folder, `deploy` reuses it so the same command
+is safe to rerun. If multiple workspaces exist, the flag never creates another one or guesses which
+workspace to use. `--yes` skips deployment confirmation but does not authorize workspace creation.
+
+If a saved workspace has been deleted or is no longer accessible, interactive terminals return to
+workspace selection. Non-interactive environments stop with `WORKSPACE_CONTEXT_STALE` instead of
+silently switching to another workspace. Automatically selected targets are printed with their
+region, organization, and workspace ID.
+
+`--dry-run` never creates a workspace or writes project context. When an account has no workspace,
+create one explicitly before requesting a deployment plan.
+
 **Config File Modification:**
 
 On first run, `deploy` automatically injects a stable `id: "<uuid>"` field into your `defineConfig({...})` call in `tailor.config.ts`. This UUID is used to track your application across renames so the SDK can recognize ownership across renames. Commit the generated id to version control. See [Configuration](../configuration.md#application-settings) for details.

package/docs/cli/setup.md

@@ -174,7 +174,7 @@ tailor setup tag [options]
 | Option                        | Alias | Description                                                                  | Required | Default |
 | ----------------------------- | ----- | ---------------------------------------------------------------------------- | -------- | ------- |
 | `--name <NAME>`               | `-n`  | Name (defaults to the config 'name')                                         | No       | -       |
-| `--tag-pattern <TAG_PATTERN>` | -     | Tag glob to match (defaults to v\*)                                          | No       | `"v*"`  |
+| `--tag-pattern <TAG_PATTERN>` | -     | Tag glob to match (defaults to v*)                                           | No       | `"v*"`  |
 | `--branch <BRANCH>`           | -     | Tag-reachability guard branch (no guard when omitted)                        | No       | -       |
 | `--environment <ENVIRONMENT>` | -     | GitHub Environment for the plan/deploy jobs (defaults to the workspace name) | No       | -       |
 | `--dir <DIR>`                 | `-d`  | App directory (for monorepo setups)                                          | No       | `"."`   |

package/docs/cli/tailordb.md

@@ -16,11 +16,10 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 **Commands**
 
-| Command                                     | Description                                                               |
-| ------------------------------------------- | ------------------------------------------------------------------------- |
-| [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables.                       |
-| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                                        |
-| [`tailordb erd`](#tailordb-erd)             | Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta) |
+| Command                                     | Description                                         |
+| ------------------------------------------- | --------------------------------------------------- |
+| [`tailordb truncate`](#tailordb-truncate)   | Truncate (delete all records from) TailorDB tables. |
+| [`tailordb migration`](#tailordb-migration) | Manage TailorDB schema migrations.                  |
 
 ### tailordb truncate
 
@@ -232,142 +231,11 @@ See [Global Options](../cli-reference.md#global-options) for options available t
 
 ### tailordb erd
 
-Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta)
-
-**Usage**
-
-```
-tailor tailordb erd <command>
-```
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Commands**
-
-| Command                                       | Description                                                       |
-| --------------------------------------------- | ----------------------------------------------------------------- |
-| [`tailordb erd export`](#tailordb-erd-export) | Export TailorDB ERD static viewer from local TailorDB schema.     |
-| [`tailordb erd diff`](#tailordb-erd-diff)     | Render TailorDB ERD schema diff HTML from exported ERD viewers.   |
-| [`tailordb erd serve`](#tailordb-erd-serve)   | Generate and serve TailorDB ERD locally with watch reload. (beta) |
-| [`tailordb erd deploy`](#tailordb-erd-deploy) | Deploy ERD static website for TailorDB namespace(s).              |
-
-#### tailordb erd export
-
-Export TailorDB ERD static viewer from local TailorDB schema.
-
-**Usage**
-
-```
-tailor tailordb erd export [options]
-```
-
-**Options**
-
-| Option                    | Alias | Description                                                                                    | Required | Default              | Env                  |
-| ------------------------- | ----- | ---------------------------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                                     | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--namespace <NAMESPACE>` | `-n`  | TailorDB namespace name (optional if only one namespace is defined in config)                  | No       | -                    | -                    |
-| `--output <OUTPUT>`       | `-o`  | Output directory path for TailorDB ERD viewer files (writes to `<outputDir>/<namespace>/dist`) | No       | `".tailor/erd"`      | -                    |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd diff
-
-Render TailorDB ERD schema diff HTML from exported ERD viewers.
-
-**Usage**
-
-```
-tailor tailordb erd diff [options]
-```
-
-**Options**
-
-| Option                        | Alias | Description                                                             | Required | Default |
-| ----------------------------- | ----- | ----------------------------------------------------------------------- | -------- | ------- |
-| `--base-html <BASE_HTML>`     | -     | Base ERD viewer HTML file                                               | No       | -       |
-| `--head-html <HEAD_HTML>`     | -     | Head ERD viewer HTML file                                               | No       | -       |
-| `--namespace <NAMESPACE>`     | `-n`  | TailorDB namespace name (defaults to the provided ERD schema namespace) | No       | -       |
-| `--output <OUTPUT>`           | `-o`  | Output ERD diff HTML file                                               | Yes      | -       |
-| `--output-json <OUTPUT_JSON>` | -     | Optional output JSON file for the computed diff                         | No       | -       |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd serve
-
-Generate and serve TailorDB ERD locally with watch reload. (beta)
-
-**Usage**
-
-```
-tailor tailordb erd serve [options]
-```
-
-**Options**
-
-| Option                    | Alias | Description                                                               | Required | Default              | Env                  |
-| ------------------------- | ----- | ------------------------------------------------------------------------- | -------- | -------------------- | -------------------- |
-| `--config <CONFIG>`       | `-c`  | Path to Tailor config file                                                | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH` |
-| `--namespace <NAMESPACE>` | `-n`  | TailorDB namespace name (uses first namespace in config if not specified) | No       | -                    | -                    |
-| `--port <PORT>`           | -     | Local server port (0 selects a free port)                                 | No       | `0`                  | -                    |
-| `--open`                  | -     | Open the ERD viewer in the default browser                                | No       | `false`              | -                    |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-#### tailordb erd deploy
-
-Deploy ERD static website for TailorDB namespace(s).
-
-**Usage**
-
-```
-tailor tailordb erd deploy [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`           |
-| `--namespace <NAMESPACE>`       | `-n`  | TailorDB namespace name (optional - deploys all namespaces with erdSite if omitted) | No       | -                    | -                              |
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-**Notes:**
-
-- ERD commands build from the local TailorDB schema, including plugin-generated TailorDB types.
-- `tailordb erd export` writes a self-contained `index.html` viewer to `<output>/<namespace>/dist`.
-- `tailordb erd diff` compares exported self-contained viewer HTML files and writes a visual ERD viewer that can switch between the current schema and the highlighted diff.
-- `tailordb erd serve` watches the config file and TailorDB type files, then reloads the browser viewer when the rebuilt `index.html` reports a new embedded schema revision.
-- `tailordb erd deploy` still requires `erdSite` in `tailor.config.ts` because it uploads the generated viewer to a configured Static Website.
-
-**Usage Examples:**
+The `tailordb erd` commands (export, diff, serve, deploy) are provided by the `@tailor-platform/sdk-tailordb-erd-plugin` CLI plugin. Install it next to the SDK and keep running `tailor tailordb erd <command>` as before:
 
 ```bash
-# Deploy ERD for all namespaces with erdSite configured
-tailor tailordb erd deploy
-
-# Deploy ERD for a specific namespace
-tailor tailordb erd deploy --namespace myNamespace
-
-# Deploy ERD with JSON output
-tailor tailordb erd deploy --json
+npm install -D @tailor-platform/sdk-tailordb-erd-plugin@next
+tailor tailordb erd export --namespace myNamespace
 ```
 
-**Notes:**
-
-- This command is a beta feature and may introduce breaking changes in future releases
-- Requires `erdSite` to be configured in `tailor.config.ts` for each namespace you want to deploy
-- Example config:
-  ```typescript
-  export default defineConfig({
-    db: {
-      myNamespace: {
-        // ... table definitions
-        erdSite: "my-erd-site-name",
-      },
-    },
-  });
-  ```
+See the plugin's README for the full command reference.

package/docs/cli/workspace.md

@@ -106,6 +106,7 @@ tailor workspace create [options]
 | `--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`       |
 | `--profile-name <PROFILE_NAME>`       | `-p`  | Profile name to create                                                                                      | No       | -         | -                                 |
+| `--profile <PROFILE>`                 | -     | Workspace profile used for authentication and Platform selection                                            | No       | -         | `TAILOR_PLATFORM_PROFILE`         |
 | `--profile-user <PROFILE_USER>`       | -     | User email address or machine user client ID for the profile (defaults to current user)                     | No       | -         | -                                 |
 | `--permission <PERMISSION>`           | -     | Profile permission (requires --profile-name). 'read' blocks all write commands while the profile is active. | No       | `"write"` | -                                 |
 
@@ -161,10 +162,11 @@ tailor workspace list [options]
 
 **Options**
 
-| Option            | Alias | Description                                              | Required | Default  |
-| ----------------- | ----- | -------------------------------------------------------- | -------- | -------- |
-| `--order <ORDER>` | -     | Sort order (asc or desc)                                 | No       | `"desc"` |
-| `--limit <LIMIT>` | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        |
+| Option                | Alias | Description                                                      | Required | Default  | Env                       |
+| --------------------- | ----- | ---------------------------------------------------------------- | -------- | -------- | ------------------------- |
+| `--order <ORDER>`     | -     | Sort order (asc or desc)                                         | No       | `"desc"` | -                         |
+| `--limit <LIMIT>`     | `-l`  | Maximum number of items to return (0 or omit: unlimited)         | No       | -        | -                         |
+| `--profile <PROFILE>` | -     | Workspace profile used for authentication and Platform selection | No       | -        | `TAILOR_PLATFORM_PROFILE` |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 

package/docs/cli-reference.md

@@ -11,12 +11,13 @@ tailor <command> [options]
 ## Global Options
 
 <a id="global-options"></a>
-| Option | Alias | Description | Required | Default |
-|--------|-------|-------------|----------|---------|
-| `--env-file <ENV_FILE>` | `-e` | Path to the environment file (error if not found) | No | - |
-| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | - | Path to the environment file (ignored if not found) | No | - |
-| `--verbose` | - | Enable verbose logging | No | `false` |
-| `--json` | `-j` | Output as JSON | No | `false` |
+
+| Option                                      | Alias | Description                                         | Required | Default |
+| ------------------------------------------- | ----- | --------------------------------------------------- | -------- | ------- |
+| `--env-file <ENV_FILE>`                     | `-e`  | Path to the environment file (error if not found)   | No       | -       |
+| `--env-file-if-exists <ENV_FILE_IF_EXISTS>` | -     | Path to the environment file (ignored if not found) | No       | -       |
+| `--verbose`                                 | -     | Enable verbose logging                              | No       | `false` |
+| `--json`                                    | `-j`  | Output as JSON                                      | No       | `false` |
 
 ### JSON Output
 
@@ -27,8 +28,11 @@ human-readable text or empty stdout.
 Commands that only perform side effects and do not define a structured result may leave stdout empty
 even when `--json` is passed.
 
-Errors, warnings, progress, and diagnostic messages are written to stderr. On failure, check the
-non-zero exit code and read stderr; stdout is not guaranteed to contain a JSON error object.
+Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing,
+a command failure under `--json` emits a JSON error envelope to stderr. CLI errors include a stable
+`error.code` and may include structured `error.next` and `error.context` fields for automated
+recovery. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain
+an error object.
 
 ## Common Options
 
@@ -116,7 +120,9 @@ tailor hello world --loud
 ```
 
 This also works under a built-in command group. The command path is joined with hyphens, so a plugin
-nested under `tailordb` is named `tailor-tailordb-erd`:
+nested under `tailordb` is named `tailor-tailordb-erd`. This is how the
+`@tailor-platform/sdk-tailordb-erd-plugin`
+package provides the `tailordb erd` commands:
 
 ```bash
 # Runs `tailor-tailordb-erd` with: export
@@ -132,6 +138,9 @@ Resolution rules:
 - **Lookup order:** the project's `node_modules/.bin` (nearest first, walking up from the current
   directory), then your `PATH`. So a plugin installed as a project dev-dependency takes precedence over a
   globally installed one.
+- **Place global flags after the plugin command.** Only the arguments following the plugin name are
+  forwarded; a global flag placed before it (e.g. `tailor --json tailordb erd export`) is consumed by
+  the host CLI and does not reach the plugin. Write `tailor tailordb erd export --json` instead.
 
 Because resolution is based on `node_modules/.bin` and `PATH`, any package manager that populates
 `node_modules/.bin` works for project-local plugins — npm, pnpm (its content-addressable store is
@@ -194,11 +203,6 @@ Commands for managing TailorDB tables, data, and schema migrations.
 | [tailordb migration set](./cli/tailordb.md#tailordb-migration-set)           | Set migration checkpoint to a specific number.                                                                            |
 | [tailordb migration status](./cli/tailordb.md#tailordb-migration-status)     | Show the current migration status for TailorDB namespaces, including applied and pending migrations.                      |
 | [tailordb migration sync](./cli/tailordb.md#tailordb-migration-sync)         | Sync remote TailorDB schema to a specific migration snapshot (recovery from --no-schema-check drift).                     |
-| [tailordb erd](./cli/tailordb.md#tailordb-erd)                               | Generate TailorDB ERD viewer artifacts from local TailorDB schema. (beta)                                                 |
-| [tailordb erd export](./cli/tailordb.md#tailordb-erd-export)                 | Export TailorDB ERD static viewer from local TailorDB schema.                                                             |
-| [tailordb erd diff](./cli/tailordb.md#tailordb-erd-diff)                     | Render TailorDB ERD schema diff HTML from exported ERD viewers.                                                           |
-| [tailordb erd serve](./cli/tailordb.md#tailordb-erd-serve)                   | Generate and serve TailorDB ERD locally with watch reload. (beta)                                                         |
-| [tailordb erd deploy](./cli/tailordb.md#tailordb-erd-deploy)                 | Deploy ERD static website for TailorDB namespace(s).                                                                      |
 
 ### [Query Commands](./cli/query.md)
 

package/docs/github-actions.md

@@ -72,6 +72,14 @@ to pull requests:
 tailor setup -n my-app-stg --erd-preview
 ```
 
+The generated workflow runs `tailor tailordb erd`, which is provided by the
+`@tailor-platform/sdk-tailordb-erd-plugin` CLI plugin — install it as a
+dev-dependency in your project:
+
+```bash
+npm install -D @tailor-platform/sdk-tailordb-erd-plugin@next
+```
+
 The generated workflow builds one self-contained ERD viewer HTML file for each
 owned TailorDB namespace in `tailor.config.ts`. The viewer compares the pull
 request merge result with the base branch, can switch between the current schema

package/docs/migration/v2.md

@@ -582,6 +582,54 @@ calls to db.table. Leave unrelated local objects with a .type() method unchanged
 
 </details>
 
+## TailorDB forward relation names derive from field names
+
+**Migration:** Partially automatic
+
+Review TailorDB relations that omit `toward.as`. Their forward GraphQL field names now derive from the relation field name with a trailing `ID`, `Id`, or `id` removed, instead of from the target table name.
+
+Preserve the v1 GraphQL field name by making it explicit:
+
+Before:
+
+```ts
+ownerId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user },
+}),
+```
+
+After:
+
+```ts
+ownerId: db.uuid().relation({
+  type: "n-1",
+  toward: { type: user, as: "user" },
+}),
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Tailor SDK v2 derives a default forward GraphQL relation name from the source
+field name by removing a trailing ID, Id, or id. V1 derived it from the target
+table name. Review each reported non-self relation that omits toward.as.
+
+If consumers must keep using the v1 GraphQL field name, inspect the v1 schema and
+copy that exact field name into toward.as. Otherwise, update GraphQL operations
+and consumer code to use the new field-based name. No change is needed when the old
+and new names are identical. Relations with a guaranteed non-empty toward.as,
+self-relations, and keyOnly relations are unchanged. For an empty or dynamic
+toward.as, determine whether its runtime value can be falsy; if so, treat the
+relation as using the default name.
+
+A relation field without a trailing ID, Id, or id would default to its own scalar
+field name and therefore conflict. Give that relation an explicit toward.as.
+```
+
+</details>
+
 ## executeScript arg JSON.stringify → value
 
 **Migration:** Partially automatic
@@ -825,6 +873,205 @@ After:
 .tailor/
 ```
 
+## ValidateFn simplification and type-level validate
+
+**Migration:** Manual
+
+Field-level `ValidateFn` is simplified from `(args: { value, data, invoker }) => boolean` to `(args: { value }) => string | void` — the function now returns the error message directly instead of a separate `[fn, message]` tuple. The `ValidateConfig` tuple form and `Validators<F>` record syntax on `db.type().validate()` are removed. Type-level validation uses `db.type().validate((args, issues) => void)` with `{ newRecord, oldRecord, invoker }` args and an `issues(field, message)` callback for cross-field rules.
+
+Field-level validate: return an error message string instead of a boolean (tuple form removed):
+
+Before:
+
+```ts
+.validate(
+  [({ value }) => value.length > 5, "Name must be longer than 5 characters"],
+)
+```
+
+After:
+
+```ts
+.validate(({ value }) =>
+  value.length <= 5 ? "Name must be longer than 5 characters" : undefined,
+)
+```
+
+Type-level validate: per-field record syntax replaced by a single function with `issues()` callback:
+
+Before:
+
+```ts
+.validate({
+  name: [({ value }) => value.length > 5, "Name must be longer than 5"],
+})
+```
+
+After:
+
+```ts
+.validate(({ newRecord }, issues) => {
+  if (newRecord.name && newRecord.name.length <= 5) {
+    issues("name", "Name must be longer than 5");
+  }
+})
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The v2 SDK simplifies field validation and introduces type-level validation.
+
+Field-level `.validate()` changes:
+- Signature: `(args: { value, data, invoker }) => boolean` → `(args: { value }) => string | void`
+- The function now returns the error message string directly (or undefined/void to pass)
+  instead of returning a boolean with the message in a separate tuple.
+- The `[fn, errorMessage]` tuple form (`ValidateConfig`) is removed.
+- `data` and `invoker` are no longer available in field-level validators.
+  Use type-level `.validate()` for cross-field or invoker-dependent rules.
+
+Type-level `.validate()` on `db.type()` changes:
+- Old: `.validate({ fieldName: fn | [fn, msg] | fn[] })` (per-field record, `Validators<F>` type)
+- New: `.validate((args, issues) => void)` (single function, `TypeValidateFn<F>` type)
+- Args: `{ newRecord, oldRecord, invoker }` — `newRecord` is the record after hooks run
+- Call `issues(field, message)` to report validation errors; `field` supports dotted paths
+- Move per-field validators that need `data`/`invoker` to the type-level function
+
+For each remaining `ValidateConfig`, `Validators<`, or old-signature `.validate()` usage:
+1. Rewrite field-level validators to return the error string directly
+2. Move cross-field / invoker-dependent validators to the type-level function
+3. Remove unused `ValidateConfig` / `Validators` type imports
+```
+
+</details>
+
+## TailorDB hook redesign: field-level args and type-level hooks
+
+**Migration:** Manual
+
+Field-level `HookFn` args change from `{ value, data, invoker }` to create `{ input, invoker, now }` / update `{ input, oldValue, invoker, now }` — `value` is renamed to `input`, matching the `input` arg on type-level hooks (same pre-hook data, narrowed to one field); `data` (the full record) is removed; `oldValue` (previous field value) is added for update hooks only; `now` (operation timestamp) is shared across all hooks. Type-level hooks on `db.type().hooks()` change from per-field mapping `{ fieldName: { create, update } }` (`Hooks<F>`) to a single `{ create, update }` object (`TypeHook<F>`) — create hooks take `{ input, invoker, now }`, update hooks take `{ input, oldRecord, invoker, now }` (oldRecord is always non-null). Both return partial field overrides.
+
+Field-level hooks: `value` renamed to `input`, `data` replaced by `oldValue` and `now`; use `now` instead of `new Date()`:
+
+Before:
+
+```ts
+db.datetime().hooks({
+  create: ({ value }) => value ?? new Date(),
+  update: () => new Date(),
+})
+```
+
+After:
+
+```ts
+db.datetime().hooks({
+  create: ({ input, now }) => input ?? now,
+  update: ({ now }) => now,
+})
+```
+
+Type-level hooks: per-field mapping replaced by single create/update functions:
+
+Before:
+
+```ts
+.hooks({
+  fullAddress: {
+    create: ({ data }) => `${data.postalCode} ${data.address}`,
+    update: ({ data }) => `${data.postalCode} ${data.address}`,
+  },
+})
+```
+
+After:
+
+```ts
+.hooks({
+  create: ({ input }) => ({
+    fullAddress: `${input.postalCode} ${input.address}`,
+  }),
+  update: ({ input }) => ({
+    fullAddress: `${input.postalCode} ${input.address}`,
+  }),
+})
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The v2 SDK redesigns TailorDB hooks at both field and type levels.
+
+Field-level `.hooks()` on individual fields:
+- Create args: `{ value, data, invoker }` → `{ input, invoker, now }` (no `oldValue`)
+- Update args: `{ value, data, invoker }` → `{ input, oldValue, invoker, now }`
+- `value` is renamed to `input`, matching the type-level hook's `input` arg — both are
+  the same pre-hook data, at different granularity
+- `data` (full record) is removed; update hooks get `oldValue` (previous field value) instead
+- `now` provides the operation timestamp — use `now` instead of `new Date()`
+- If a field-level hook needs the full record (other fields), move it to a type-level hook
+
+Type-level `.hooks()` on `db.type()`:
+- Old: `.hooks({ fieldName: { create: fn, update: fn } })` (per-field mapping, `Hooks<F>` type)
+- New: `.hooks({ create: fn, update: fn })` (single object, `TypeHook<F>` type)
+- Each function: `({ input, oldRecord, invoker, now }) => ({ fieldName: value, ... })`
+- `input` is the pre-hook input (may have nullish values for optional/defaulted fields)
+- Create hooks do not receive `oldRecord`; update hooks receive `oldRecord` (always non-null)
+- Return an object with only the fields to override; unmentioned fields are unchanged
+
+Migration steps for each `.hooks()` call on a `db.type()`:
+1. If the old per-field hooks only use `value`/`invoker` and don't reference `data`,
+   convert them to field-level hooks with the new args (`value` → `input`, plus `oldValue`, `now`)
+2. If the old hooks reference `data` (cross-field access), convert to a type-level hook
+   using `input`/`oldRecord`
+3. Remove unused `Hooks<F>` / `HookFn<>` type imports
+```
+
+</details>
+
+## generate --watch flag removed
+
+**Migration:** Manual
+
+Review and remove `tailor generate --watch` / `-W` invocations and the `watch` option on `GenerateOptions`. The flag, its dependency watcher, and the self-restart-on-change logic are removed; `generate` now always performs a single generation pass.
+
+The --watch/-W flag no longer exists; re-run generate after each change:
+
+Before:
+
+```sh
+tailor generate --watch
+```
+
+After:
+
+```sh
+tailor generate
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Tailor SDK v2 removes the `generate --watch` (`-W`) flag along with the
+dependency watcher and self-restart logic that powered it. `tailor generate`
+now always runs a single generation pass and exits.
+
+For each flagged `tailor generate ... --watch` / `-W` invocation (package.json
+scripts, shell scripts, CI configs, or docs), drop the flag and re-run
+`tailor generate` after each change instead. If automatic regeneration on file
+change is still needed, wrap the command with a general-purpose file watcher
+(e.g. `chokidar-cli`, `nodemon`) at the project level.
+
+For programmatic use of `generate()` from `@tailor-platform/sdk/cli`, remove the
+`watch` field from the `GenerateOptions` argument — the function now performs a
+single generation pass and resolves once it completes.
+```
+
+</details>
+
 ## Behavioral changes (no migration required)
 
 These v2 changes alter runtime or CLI behavior; no source change is needed.