@tailor-platform/sdk 2.0.0-next.5 → 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/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

@@ -28,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
 
@@ -117,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
@@ -133,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
@@ -195,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

@@ -1031,6 +1031,47 @@ Migration steps for each `.hooks()` call on a `db.type()`:
 
 </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.

package/docs/runtime.md

@@ -31,7 +31,7 @@ const token = await authconnection.getConnectionToken("google");
 const client = new idp.Client({ namespace: "my-namespace" });
 const { users } = await client.users({ first: 10 });
 
-const executionId = await workflow.triggerWorkflow("approval", { reportId });
+const executionId = await workflow.startWorkflow("approval", { reportId });
 
 const invoker = context.getInvoker();
 
@@ -81,7 +81,7 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
 - `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
 - `idp` — IdP user management (`new Client({ namespace })`)
-- `workflow` — workflow & job control (`triggerWorkflow`, `resumeWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `startJobFunction`, `wait`, `resolve`; the pre-alignment names `triggerWorkflow`, `resumeWorkflow`, `triggerJobFunction` are kept as frozen aliases)
 - `context` — execution context (`getInvoker`)
 - `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
 - `aigateway` — AI Gateway URL resolution (`get`)
@@ -97,17 +97,16 @@ import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
   using iconvM = mockIconv();
-  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvM.calls[0]?.method).toBe("convert");
+  expect(iconvM.convert).toHaveBeenCalledWith("あ", "UTF-8", "Shift_JIS");
 }); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/executor.md

@@ -329,6 +329,11 @@ createExecutor({
 });
 ```
 
+`args` must match the workflow's main job input. It is required when that input is required
+and can be omitted when the workflow has no input. Static arguments can be JSON-compatible
+primitives, arrays, or plain objects; top-level `null` is not supported. An argument callback
+must return the same input type.
+
 ### Authentication for Operations
 
 GraphQL and Workflow operations can specify an `invoker` to execute with machine user credentials. Pass the machine user name as a plain string — it is type-narrowed to the names defined in your auth config:

package/docs/services/tailordb.md

@@ -555,6 +555,48 @@ db.table("User", {
    });
    ```
 
+#### GraphQL Operations
+
+Control which GraphQL operations (`create`, `update`, `delete`, `read`) are exposed for a type. All operations are enabled by default.
+
+```typescript
+db.type("Order", {
+  status: db.string(),
+}).features({
+  gqlOperations: {
+    delete: false, // Disable the delete mutation
+  },
+});
+```
+
+Use the `"query"` alias to disable all mutations at once (read-only type: `create`/`update`/`delete` false, `read` true):
+
+```typescript
+db.type("AuditLog", {
+  action: db.string(),
+}).features({
+  gqlOperations: "query",
+});
+```
+
+**Namespace-level default**
+
+Set a default for every type in a TailorDB namespace in `tailor.config.ts`. A type's own `.features({ gqlOperations })` always takes precedence over this default.
+
+```typescript
+// tailor.config.ts
+export default defineConfig({
+  db: {
+    tailordb: {
+      files: ["./tailordb/*.ts"],
+      gqlOperations: { delete: false }, // Default for every type in this namespace
+    },
+  },
+});
+```
+
+This default is re-evaluated on every `tailor-sdk deploy`, so changing it also updates types that already exist on the platform, not only newly created ones.
+
 ### Field Extraction (`pickFields` / `omitFields`)
 
 Extract subsets of fields from a `TailorDBType` for reuse in resolvers, executors, seed schemas, etc.
@@ -635,6 +677,8 @@ Configure Permission and GQLPermission. For details, see the [TailorDB Permissio
 
 **Important**: Following the secure-by-default principle, all operations are denied if permissions are not configured. You must explicitly grant permissions for each operation (create, read, update, delete).
 
+`generate`/`deploy` reject a type that has no `.permission()`, or no `.gqlPermission()` while GraphQL operations are enabled for it (see [GraphQL Operations](#graphql-operations) above). Disable GraphQL exposure entirely with `.features({ gqlOperations: { create: false, update: false, delete: false, read: false } })` if a type only needs record-level permission.
+
 ```typescript
 db.table("User", {
   name: db.string(),

package/docs/services/workflow.md

@@ -401,7 +401,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.trigger()` or `tailor.workflow.triggerJobFunction()`. 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.trigger()` or `tailor.workflow.startJobFunction()` (or its frozen alias `triggerJobFunction`). 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";
@@ -427,7 +427,7 @@ export const mainJob = createWorkflowJob({
 });
 ```
 
-The same `executionPolicyKey` option is available on `tailor.workflow.triggerJobFunction(name, args, options)` for jobs invoked by name.
+The same `executionPolicyKey` option is available on `tailor.workflow.startJobFunction(name, args, options)` (or the frozen alias `tailor.workflow.triggerJobFunction`) for jobs invoked by name.
 
 ## Triggering a Workflow from a Resolver