@tailor-platform/sdk 2.4.0 → 2.5.0

package/docs/plugin/custom.md

@@ -18,22 +18,22 @@ const myPlugin: Plugin = {
 export default myPlugin; // Required: must be default export
 ```
 
-This is required so that other plugins and generation-time hooks can use plugin-generated TailorDB tables via `getGeneratedType()`.
+This is required so that other plugins and generation-time hooks can use plugin-generated TailorDB tables via `getGeneratedTable()`.
 
 ## Plugin Interface
 
 ```typescript
-interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
+interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
   readonly id: string;
   readonly description: string;
   readonly importPath?: string;
-  readonly typeConfigRequired?: boolean | ((pluginConfig?: PluginConfig) => boolean);
+  readonly tableConfigRequired?: boolean | ((pluginConfig?: PluginConfig) => boolean);
   readonly pluginConfig?: PluginConfig;
 
   // Definition-time hooks
-  onTypeLoaded?(
-    context: PluginProcessContext<TypeConfig, PluginConfig>,
-  ): TypePluginOutput | Promise<TypePluginOutput>;
+  onTableLoaded?(
+    context: PluginTableProcessContext<TableConfig, PluginConfig>,
+  ): TablePluginOutput | Promise<TablePluginOutput>;
   onNamespaceLoaded?(
     context: PluginNamespaceProcessContext<PluginConfig>,
   ): PluginOutput | Promise<PluginOutput>;
@@ -51,34 +51,34 @@ interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
 }
 ```
 
-| Property             | Required                         | Description                                                                                      |
-| -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `id`                 | Yes                              | Unique plugin identifier (e.g., `"@my-company/soft-delete"`)                                     |
-| `description`        | Yes                              | Human-readable description                                                                       |
-| `importPath`         | When using definition-time hooks | Path resolvable from `tailor.config.ts` directory. Used for import statements in generated code. |
-| `typeConfigRequired` | No                               | Whether per-table config is required when attaching via `.plugin()`. Default: optional.          |
-| `pluginConfig`       | No                               | Plugin-level config passed via `definePlugins()`. Set via factory function.                      |
+| Property              | Required                         | Description                                                                                      |
+| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `id`                  | Yes                              | Unique plugin identifier (e.g., `"@my-company/soft-delete"`)                                     |
+| `description`         | Yes                              | Human-readable description                                                                       |
+| `importPath`          | When using definition-time hooks | Path resolvable from `tailor.config.ts` directory. Used for import statements in generated code. |
+| `tableConfigRequired` | No                               | Whether per-table config is required when attaching via `.plugin()`. Default: optional.          |
+| `pluginConfig`        | No                               | Plugin-level config passed via `definePlugins()`. Set via factory function.                      |
 
 ## Hook Reference
 
-### onTypeLoaded
+### onTableLoaded
 
 **Trigger**: Called once for each TailorDB table that has `.plugin({ pluginId: config })` attached.
 
-**Context** (`PluginProcessContext`):
+**Context** (`PluginTableProcessContext`):
 
 | Field          | Type              | Description                                |
 | -------------- | ----------------- | ------------------------------------------ |
-| `type`         | `TailorAnyDBType` | The TailorDB table being processed         |
-| `typeConfig`   | `TypeConfig`      | Per-table config from `.plugin()`          |
+| `table`        | `TailorAnyDBType` | The TailorDB table being processed         |
+| `tableConfig`  | `TableConfig`     | Per-table config from `.plugin()`          |
 | `pluginConfig` | `PluginConfig`    | Plugin-level config from `definePlugins()` |
 | `namespace`    | `string`          | Namespace of the TailorDB table            |
 
-**Returns** (`TypePluginOutput`):
+**Returns** (`TablePluginOutput`):
 
 | Field       | Type                                            | Description                                            |
 | ----------- | ----------------------------------------------- | ------------------------------------------------------ |
-| `types`     | `Record<string, TailorAnyDBType>`               | Additional TailorDB tables to generate (keyed by kind) |
+| `tables`    | `Record<string, TailorAnyDBType>`               | Additional TailorDB tables to generate (keyed by kind) |
 | `resolvers` | `PluginGeneratedResolver[]`                     | Additional resolvers to generate                       |
 | `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
 | `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |
@@ -90,12 +90,12 @@ interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
 - Generate executors triggered by record events on the source table
 
 ```typescript
-onTypeLoaded(context) {
-  const { type, typeConfig, namespace } = context;
+onTableLoaded(context) {
+  const { table, tableConfig, namespace } = context;
   return {
-    types: { archive: db.table(`Deleted_${type.name}`, { ... }) },
+    tables: { archive: db.table(`Deleted_${table.name}`, { ... }) },
     extends: { fields: { deletedAt: db.datetime({ optional: true }) } },
-    executors: [{ name: `${type.name}-on-delete`, resolve: async () => await import("./on-delete"), context: { sourceType: type, namespace } }],
+    executors: [{ name: `${table.name}-on-delete`, resolve: async () => await import("./on-delete"), context: { sourceTable: table, namespace } }],
   };
 },
 ```
@@ -113,7 +113,7 @@ onTypeLoaded(context) {
 
 **Returns** (`PluginOutput`):
 
-Same as `TypePluginOutput` but without `extends` (namespace plugins cannot extend a source table).
+Same as `TablePluginOutput` but without `extends` (namespace plugins cannot extend a source table).
 
 **Use cases**:
 
@@ -122,7 +122,7 @@ Same as `TypePluginOutput` but without `extends` (namespace plugins cannot exten
 ```typescript
 onNamespaceLoaded(context) {
   return {
-    types: { auditLog: db.table("AuditLog", { action: db.string(), ... }) },
+    tables: { auditLog: db.table("AuditLog", { action: db.string(), ... }) },
   };
 },
 ```
@@ -146,7 +146,7 @@ onNamespaceLoaded(context) {
 | Field               | Type                                       | Description                           |
 | ------------------- | ------------------------------------------ | ------------------------------------- |
 | `namespace`         | `string`                                   | Namespace name                        |
-| `types`             | `Record<string, TailorDBType>`             | All finalized tables in the namespace |
+| `tables`            | `Record<string, TailorDBType>`             | All finalized tables in the namespace |
 | `sourceInfo`        | `ReadonlyMap<string, TypeSourceInfoEntry>` | Source file info for each table       |
 | `pluginAttachments` | `ReadonlyMap<string, PluginAttachment[]>`  | Plugin configs attached to each table |
 
@@ -165,11 +165,11 @@ onNamespaceLoaded(context) {
 
 ```typescript
 onTailorDBReady(ctx) {
-  const allTypes = ctx.tailordb.flatMap((ns) =>
-    Object.values(ns.types).map((t) => t.name),
+  const allTables = ctx.tailordb.flatMap((ns) =>
+    Object.values(ns.tables).map((table) => table.name),
   );
   return {
-    files: [{ path: `${ctx.baseDir}/types.ts`, content: `export const types = ${JSON.stringify(allTypes)};\n` }],
+    files: [{ path: `${ctx.baseDir}/tables.ts`, content: `export const tables = ${JSON.stringify(allTables)};\n` }],
   };
 },
 ```
@@ -233,7 +233,7 @@ All fields from `ResolverReadyContext`, plus:
 ```typescript
 onExecutorReady(ctx) {
   const summary = {
-    types: ctx.tailordb.flatMap((ns) => Object.keys(ns.types)),
+    tables: ctx.tailordb.flatMap((ns) => Object.keys(ns.tables)),
     resolvers: ctx.resolvers.flatMap((ns) => Object.keys(ns.resolvers)),
     executors: Object.keys(ctx.executors),
   };
@@ -262,8 +262,8 @@ All context and result types are exported from `@tailor-platform/sdk`:
 ```typescript
 import type {
   Plugin,
-  PluginProcessContext,
-  TypePluginOutput,
+  PluginTableProcessContext,
+  TablePluginOutput,
   PluginOutput,
   TailorDBReadyContext,
   ResolverReadyContext,
@@ -274,34 +274,34 @@ import type {
 } from "@tailor-platform/sdk";
 ```
 
-## getGeneratedType Helper
+## getGeneratedTable Helper
 
-The SDK provides an async `getGeneratedType()` helper function to retrieve plugin-generated TailorDB tables. This enables plugins and other tools to work with tables generated by plugins.
+The SDK provides an async `getGeneratedTable()` helper function to retrieve plugin-generated TailorDB tables. This enables plugins and other tools to work with tables generated by plugins.
 
 ```typescript
 import { join } from "node:path";
-import { getGeneratedType } from "@tailor-platform/sdk/plugin";
+import { getGeneratedTable } from "@tailor-platform/sdk/plugin";
 import { customer } from "./tailordb/customer";
 
 const configPath = join(import.meta.dirname, "./tailor.config.ts");
 
 // Table-attached plugin
-const DeletedCustomer = await getGeneratedType(
+const DeletedCustomer = await getGeneratedTable(
   configPath,
   "@example/soft-delete",
   customer,
   "archive",
 );
 
-// Namespace plugin (pass null as sourceType)
-const AuditLog = await getGeneratedType(configPath, "@example/audit-log", null, "auditLog");
+// Namespace plugin (pass null as sourceTable)
+const AuditLog = await getGeneratedTable(configPath, "@example/audit-log", null, "auditLog");
 ```
 
 **Parameters:**
 
 - `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
 - `pluginId`: The plugin's unique identifier (e.g., `"@example/soft-delete"`)
-- `sourceType`: The TailorDB table that the plugin is attached to (`null` for namespace plugins)
+- `sourceTable`: The TailorDB table that the plugin is attached to (`null` for namespace plugins)
 - `kind`: The generated table kind (e.g., `"archive"`, `"auditLog"`)
 
 **How it works:**
@@ -309,7 +309,7 @@ const AuditLog = await getGeneratedType(configPath, "@example/audit-log", null,
 1. Loads and caches the config from the given path
 2. Finds the plugin by ID from `definePlugins()` exports
 3. Auto-resolves the namespace from config
-4. Calls the plugin's `onTypeLoaded()` or `onNamespaceLoaded()` method
+4. Calls the plugin's `onTableLoaded()` or `onNamespaceLoaded()` method
 5. Caches the result to avoid redundant processing
 6. Returns the generated table matching the specified kind
 
@@ -317,14 +317,14 @@ const AuditLog = await getGeneratedType(configPath, "@example/audit-log", null,
 
 ### Definition-time Plugin (Soft Delete)
 
-A plugin that adds soft delete functionality via `onTypeLoaded`:
+A plugin that adds soft delete functionality via `onTableLoaded`:
 
 ```typescript
 // plugins/soft-delete/plugin.ts
 import { db } from "@tailor-platform/sdk";
-import type { Plugin, PluginProcessContext, TypePluginOutput } from "@tailor-platform/sdk";
+import type { Plugin, PluginTableProcessContext, TablePluginOutput } from "@tailor-platform/sdk";
 
-interface SoftDeleteConfig {
+interface SoftDeleteTableConfig {
   archiveReason?: boolean;
   retentionDays?: number;
 }
@@ -332,28 +332,28 @@ interface SoftDeleteConfig {
 interface SoftDeletePluginConfig {
   archiveTablePrefix?: string;
   defaultRetentionDays?: number;
-  requireTypeConfig?: boolean;
+  requireTableConfig?: boolean;
 }
 
 function processSoftDelete(
-  context: PluginProcessContext<SoftDeleteConfig, SoftDeletePluginConfig>,
-): TypePluginOutput {
-  const { type, typeConfig, pluginConfig, namespace } = context;
+  context: PluginTableProcessContext<SoftDeleteTableConfig, SoftDeletePluginConfig>,
+): TablePluginOutput {
+  const { table, tableConfig, pluginConfig, namespace } = context;
   const prefix = pluginConfig?.archiveTablePrefix ?? "Deleted_";
 
   // Generate archive table
-  const archiveType = db
-    .table(`${prefix}${type.name}`, {
+  const archiveTable = db
+    .table(`${prefix}${table.name}`, {
       originalId: db.uuid().description("ID of the deleted record"),
       originalData: db.string().description("JSON snapshot of deleted record"),
       deletedAt: db.datetime().description("When the record was deleted"),
       deletedBy: db.uuid().description("User who deleted the record"),
-      ...(typeConfig.archiveReason && {
+      ...(tableConfig.archiveReason && {
         reason: db.string({ optional: true }).description("Reason for deletion"),
       }),
       ...db.fields.timestamps(),
     })
-    .description(`Archive for deleted ${type.name} records`);
+    .description(`Archive for deleted ${table.name} records`);
 
   // Extend source table with deletedAt field
   const extendFields = {
@@ -361,15 +361,15 @@ function processSoftDelete(
   };
 
   return {
-    types: { archive: archiveType },
+    tables: { archive: archiveTable },
     extends: { fields: extendFields },
     executors: [
       {
-        name: `${type.name.toLowerCase()}-on-delete`,
+        name: `${table.name.toLowerCase()}-on-delete`,
         resolve: async () => await import("./executors/on-delete"),
         context: {
-          sourceType: type,
-          archiveType,
+          sourceTable: table,
+          archiveTable,
           namespace,
         },
       },
@@ -379,14 +379,14 @@ function processSoftDelete(
 
 function createSoftDeletePlugin(
   pluginConfig?: SoftDeletePluginConfig,
-): Plugin<SoftDeleteConfig, SoftDeletePluginConfig> {
+): Plugin<SoftDeleteTableConfig, SoftDeletePluginConfig> {
   return {
     id: "@example/soft-delete",
     description: "Adds soft delete with archive functionality",
     importPath: "./plugins/soft-delete",
     pluginConfig,
-    typeConfigRequired: (config) => config?.requireTypeConfig === true,
-    onTypeLoaded: processSoftDelete,
+    tableConfigRequired: (config) => config?.requireTableConfig === true,
+    onTableLoaded: processSoftDelete,
   };
 }
 
@@ -403,24 +403,24 @@ import { withPluginContext } from "@tailor-platform/sdk/plugin";
 import { getDB } from "generated/tailordb";
 
 interface SoftDeleteContext {
-  sourceType: TailorAnyDBType;
-  archiveType: TailorAnyDBType;
+  sourceTable: TailorAnyDBType;
+  archiveTable: TailorAnyDBType;
   namespace: string;
 }
 
 export default withPluginContext((ctx: SoftDeleteContext) => {
-  const { sourceType, archiveType, namespace } = ctx;
+  const { sourceTable, archiveTable, namespace } = ctx;
 
   return createExecutor({
-    name: `${sourceType.name.toLowerCase()}-on-delete`,
-    description: `Archives deleted ${sourceType.name} records`,
-    trigger: recordDeletedTrigger({ type: sourceType }),
+    name: `${sourceTable.name.toLowerCase()}-on-delete`,
+    description: `Archives deleted ${sourceTable.name} records`,
+    trigger: recordDeletedTrigger({ type: sourceTable }),
     operation: {
       kind: "function",
       body: async ({ oldRecord, user }) => {
         const db = getDB(namespace as "tailordb");
         await db
-          .insertInto(archiveType.name)
+          .insertInto(archiveTable.name)
           .values({
             originalId: oldRecord.id,
             originalData: JSON.stringify(oldRecord),
@@ -461,28 +461,28 @@ export const customer = db
   });
 ```
 
-### Generation-only Plugin (Type List)
+### Generation-only Plugin (Table List)
 
 A plugin that only uses `onTailorDBReady` to generate output files:
 
 ```typescript
 import type { Plugin, GeneratorResult } from "@tailor-platform/sdk";
 
-const typeListPlugin: Plugin = {
-  id: "@example/type-list",
+const tableListPlugin: Plugin = {
+  id: "@example/table-list",
   description: "Generates a list of all TailorDB table names",
 
   onTailorDBReady(ctx): GeneratorResult {
-    const allTypes = ctx.tailordb.flatMap((ns) =>
-      Object.entries(ns.types).map(([_, type]) => ({
-        name: type.name,
-        fieldCount: Object.keys(type.fields).length,
+    const allTables = ctx.tailordb.flatMap((ns) =>
+      Object.values(ns.tables).map((table) => ({
+        name: table.name,
+        fieldCount: Object.keys(table.fields).length,
         namespace: ns.namespace,
       })),
     );
-    const content = `// Generated type list\nexport const types = ${JSON.stringify(allTypes, null, 2)} as const;\n`;
+    const content = `// Generated table list\nexport const tables = ${JSON.stringify(allTables, null, 2)} as const;\n`;
     return {
-      files: [{ path: `${ctx.baseDir}/types.ts`, content }],
+      files: [{ path: `${ctx.baseDir}/tables.ts`, content }],
     };
   },
 };
@@ -499,15 +499,17 @@ const plugin: Plugin = {
   importPath: "./plugins/hybrid",
 
   // Definition-time: Generate additional tables from attached source tables
-  onTypeLoaded(context) {
-    return { types: { derived: createDerivedType(context.type) } };
+  onTableLoaded(context) {
+    return { tables: { derived: createDerivedTable(context.table) } };
   },
 
   // Generation-time: Generate output files from all finalized tables
   onTailorDBReady(ctx) {
-    const allTypes = ctx.tailordb.flatMap((ns) => Object.values(ns.types).map((t) => t.name));
+    const allTables = ctx.tailordb.flatMap((ns) =>
+      Object.values(ns.tables).map((table) => table.name),
+    );
     return {
-      files: [{ path: `${ctx.baseDir}/output.ts`, content: generateCode(allTypes) }],
+      files: [{ path: `${ctx.baseDir}/output.ts`, content: generateCode(allTables) }],
     };
   },
 };
@@ -515,13 +517,13 @@ const plugin: Plugin = {
 
 ## Adding Type Safety
 
-### Plugin-level type safety (TypeConfig / PluginConfig)
+### Plugin-level type safety (TableConfig / PluginConfig)
 
-Use TypeScript type parameters on `Plugin<TypeConfig, PluginConfig>` to get type-safe config
-in `onTypeLoaded` and `onNamespaceLoaded` methods:
+Use TypeScript type parameters on `Plugin<TableConfig, PluginConfig>` to get type-safe config
+in `onTableLoaded` and `onNamespaceLoaded` methods:
 
 ```typescript
-interface MyTypeConfig {
+interface MyTableConfig {
   archiveReason?: boolean;
 }
 
@@ -529,11 +531,11 @@ interface MyPluginConfig {
   prefix?: string;
 }
 
-const plugin: Plugin<MyTypeConfig, MyPluginConfig> = {
+const plugin: Plugin<MyTableConfig, MyPluginConfig> = {
   id: "@example/my-plugin",
   // ...
-  onTypeLoaded(context) {
-    // context.typeConfig is MyTypeConfig
+  onTableLoaded(context) {
+    // context.tableConfig is MyTableConfig
     // context.pluginConfig is MyPluginConfig
   },
 };
@@ -546,6 +548,9 @@ for the `PluginConfigs` interface. Plugin authors should ship this in their pack
 
 ```typescript
 // your-plugin/types.d.ts (shipped with your plugin package)
+export {}; // required: a top-level import/export makes this file augment
+// the module below instead of replacing its other exports
+
 declare module "@tailor-platform/sdk" {
   interface PluginConfigs<Fields extends string> {
     "@example/soft-delete": {
@@ -559,6 +564,8 @@ declare module "@tailor-platform/sdk" {
 The `Fields` type parameter provides field names from the table being configured, enabling field-aware configurations:
 
 ```typescript
+export {};
+
 declare module "@tailor-platform/sdk" {
   interface PluginConfigs<Fields extends string> {
     "@example/i18n": {
@@ -567,3 +574,41 @@ declare module "@tailor-platform/sdk" {
   }
 }
 ```
+
+### Resolving plugin-level config from a `Plugin[]` array (declaration merging)
+
+`PluginConfig` is already available inside your own plugin's hooks via `context.pluginConfig`.
+If other code instead needs to look up your plugin's config from a `Plugin[]` array by `id` —
+without importing your plugin's config type — register it on the `PluginConfigRegistry`
+interface. Plugin authors should ship this in their package's type definitions:
+
+```typescript
+// your-plugin/types.d.ts (shipped with your plugin package)
+export {}; // required: a top-level import/export makes this file augment
+// the module below instead of replacing its other exports
+
+declare module "@tailor-platform/sdk/plugin" {
+  interface PluginConfigRegistry {
+    "@example/soft-delete": {
+      archiveTablePrefix?: string;
+    };
+  }
+}
+```
+
+This only registers the type; it does not provide a function to read it. Callers resolve a
+registered config from `Plugin[]` using the public `Plugin` and `PluginConfigRegistry` types:
+
+```typescript
+import type { Plugin } from "@tailor-platform/sdk";
+import type { PluginConfigRegistry } from "@tailor-platform/sdk/plugin";
+
+function resolvePluginConfig<Id extends keyof PluginConfigRegistry>(
+  plugins: readonly Plugin[],
+  id: Id,
+): PluginConfigRegistry[Id] | undefined {
+  return plugins.find((p) => p.id === id)?.pluginConfig as PluginConfigRegistry[Id] | undefined;
+}
+```
+
+An `id` that isn't registered fails to compile, instead of silently resolving to `unknown`.

package/docs/plugin/index.md

@@ -73,7 +73,7 @@ export const customer = db
 ### Per-table Config Requirement
 
 Per-table config is optional by default. Plugin authors can change this with
-`typeConfigRequired` (boolean or function). When a function is used, it receives
+`tableConfigRequired` (boolean or function). When a function is used, it receives
 the plugin-level config from `definePlugins()`.
 
 ### Global Plugin Configuration
@@ -116,7 +116,7 @@ Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific
 tailor generate
 │
 ├─ Load TailorDB tables
-│   ├─ onTypeLoaded        ← per table with .plugin() attached
+│   ├─ onTableLoaded       ← per table with .plugin() attached
 │   └─ onNamespaceLoaded   ← once per namespace (namespace plugins)
 │
 ├─ Resolve Auth
@@ -136,7 +136,7 @@ tailor generate
 
 | Hook                | Trigger                              | Can do                                                            |
 | ------------------- | ------------------------------------ | ----------------------------------------------------------------- |
-| `onTypeLoaded`      | Each table with `.plugin()` attached | Generate tables, resolvers, executors; extend source table fields |
+| `onTableLoaded`     | Each table with `.plugin()` attached | Generate tables, resolvers, executors; extend source table fields |
 | `onNamespaceLoaded` | Once per namespace                   | Generate tables, resolvers, executors                             |
 
 These hooks produce TailorDB tables, resolvers, and executors that become part of the application. Requires `importPath` on the plugin.

package/docs/services/tailordb-migration.md

@@ -201,6 +201,20 @@ tailor tailordb migration script 0002 --no-script --reason "no data yet, safe to
 
 This stores the reason in `migrations/0002/diff.json` (commit the change). The next `tailor deploy` applies the schema change as usual, skips only the script step, and logs the recorded reason. The command refuses to record a skip while `migrate.ts` exists — delete the script first. If `migrate.ts` is added back later, `tailor deploy` fails rather than choosing between the script and the acknowledgment; run `tailor tailordb migration script 0002` again to clear the now-stale acknowledgment from `diff.json` (the script then runs on the next deploy), or delete `migrate.ts` to keep the skip.
 
+### Data-only migrations
+
+Sometimes existing data must be transformed without any schema change — fixing values written by an application bug, or a one-off normalization. Create a migration that carries no schema diff and exists only to run its script:
+
+```bash
+tailor tailordb migration generate --data-only --name "normalize legacy phone numbers"
+```
+
+This writes a numbered migration with an empty `diff.json`, a `migrate.ts` skeleton, and `db.ts` typed against the current schema. Edit `migrate.ts` to implement the transformation; the next `tailor deploy` runs it like any other migration script — in a single transaction, advancing the migration checkpoint (see [Performance and Large Tables](#performance-and-large-tables) for batching patterns). Because the entry is part of the migration history, the fix is versioned, ordered relative to schema changes, and applied once per workspace.
+
+The command requires a clean state: if the namespace has schema changes that are not yet in migration files, generate the schema migration first. With multiple namespaces, pass `--namespace` to name the target. `--data-only` cannot be combined with `--init`, `--rename`, `--drop`, or `--expand-contract`.
+
+A data-only migration runs in **every** workspace the history is applied to, including freshly created ones. Write the script so it is safe against tables with no matching rows (a set-based `UPDATE` with a `WHERE` clause is naturally a no-op on an empty table). For a fix that should run in a single environment only, or that is too large for one transaction, run it outside the migration history instead.
+
 ## Configuration
 
 ```typescript
@@ -227,13 +241,13 @@ export default defineConfig({
 
 ## Generated Files
 
-| File                   | When generated                                                                                               | Description                                                                                                              |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `0000/schema.json`     | First `migration generate`                                                                                   | Full snapshot of all tables in the namespace.                                                                            |
-| `XXXX/diff.json`       | Every subsequent migration                                                                                   | Field-level diff against the previous snapshot.                                                                          |
-| `XXXX/migrate.ts`      | Auto-generated for breaking changes; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
-| `XXXX/db.ts`           | Generated once when `migrate.ts` is created                                                                  | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
-| `XXXX/migrate.test.ts` | Added via `tailordb migration script --with-test`                                                            | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
+| File                   | When generated                                                                                                                            | Description                                                                                                              |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `0000/schema.json`     | First `migration generate`                                                                                                                | Full snapshot of all tables in the namespace.                                                                            |
+| `XXXX/diff.json`       | Every subsequent migration                                                                                                                | Field-level diff against the previous snapshot.                                                                          |
+| `XXXX/migrate.ts`      | Auto-generated for breaking changes and `--data-only` migrations; added manually via `tailordb migration script` for warning-tier changes | Data transformation script. The `main` export receives a Kysely `Transaction`.                                           |
+| `XXXX/db.ts`           | Generated once when `migrate.ts` is created                                                                                               | Kysely types reflecting the schema **before** this migration. Exports `Database`, `Transaction`, and `MigrationContext`. |
+| `XXXX/migrate.test.ts` | Added via `tailordb migration script --with-test`                                                                                         | Unit-test scaffold for `migrate.ts` (see [Testing Migrations Locally](#testing-migrations-locally)). Never deployed.     |
 
 `db.ts` reflects the pre-migration schema because the script runs after the pre-migration phase has temporarily relaxed breaking constraints (e.g., a new `required` field is added as `optional` first), so the data being read still matches the previous shape.
 

package/docs/services/workflow.md

@@ -26,12 +26,15 @@ All workflow components must follow these rules:
 - **Job name uniqueness**: Job names must be unique across the entire project (not just within one file)
 - **mainJob required**: Every workflow must specify a `mainJob`
 
-| Rule                                           | Description                                                                                          |
-| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `createWorkflow` result must be default export | Workflow files must export the workflow as default                                                   |
-| All jobs must be named exports                 | Includes `mainJob` and any job started via `.start()` (even if referenced only within the same file) |
-| Job `name` values must be unique               | Job names must be unique across the entire project                                                   |
-| `mainJob` is required                          | Every workflow must specify a `mainJob`                                                              |
+| Rule                                                                     | Description                                                                                                                                                                                    |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createWorkflow` result must be default export                           | Workflow files must export the workflow as default                                                                                                                                             |
+| All jobs must be named exports                                           | Includes `mainJob` and any job started via `.start()` (even if referenced only within the same file)                                                                                           |
+| Job `name` values must be unique                                         | Job names must be unique across the entire project                                                                                                                                             |
+| `mainJob` is required                                                    | Every workflow must specify a `mainJob`                                                                                                                                                        |
+| `createWorkflowJob`'s `name`/`body` must be written directly in the call | Not as a reference to a variable or the result of another function — the build cannot see through that indirection and fails instead of silently leaving the job out                           |
+| `.start()` must be called from within the calling job's `body`           | A function defined inside `body` may call it too, but not a function defined outside `body` — the build cannot see through that indirection and fails instead of silently leaving the call out |
+| Call `<job>.start()`, not `execJobFunction` directly                     | Calling `tailor.workflow.execJobFunction(...)` (or the `workflow` value imported from `@tailor-platform/sdk/runtime`) directly is not detected as a dependency and fails the build             |
 
 ## Creating a Workflow Job
 
@@ -481,7 +484,7 @@ An exact-key policy applies to dispatches whose runtime key equals the policy ke
 
 ### Referencing a Policy from a Workflow
 
-Pass the runtime key through the `executionPolicyKey` option on `job.start()` or `tailor.workflow.execJobFunction()`. For exact-key policies, use `<policy>.key` directly — it's typed so only a value that came from a declared policy can be passed. For wildcard policies (`matchType: "prefix"`), there is no `<policy>.key` — call `<policy>.keyFor(suffix)` to build the concrete key. `keyFor` joins the prefix and suffix with `.` by default; override it with `separator` — the second argument to `defineWorkflowExecutionPolicies` (applies to every policy in the group), or a `def` field on a single `defineWorkflowExecutionPolicy`.
+Pass the runtime key through the `executionPolicyKey` option on `job.start()`. For exact-key policies, use `<policy>.key` directly — it's typed so only a value that came from a declared policy can be passed. For wildcard policies (`matchType: "prefix"`), there is no `<policy>.key` — call `<policy>.keyFor(suffix)` to build the concrete key. `keyFor` joins the prefix and suffix with `.` by default; override it with `separator` — the second argument to `defineWorkflowExecutionPolicies` (applies to every policy in the group), or a `def` field on a single `defineWorkflowExecutionPolicy`.
 
 ```typescript
 import { createWorkflowJob } from "@tailor-platform/sdk";
@@ -507,8 +510,6 @@ export const mainJob = createWorkflowJob({
 });
 ```
 
-The same `executionPolicyKey` option is available on `tailor.workflow.execJobFunction(name, args, options)` for jobs invoked by name.
-
 ## Starting a Workflow from a Resolver
 
 You can start a workflow execution from a resolver using `workflow.start()`.