@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.10

package/docs/cli/application.md

@@ -2,142 +2,135 @@
 
 Commands for managing Tailor Platform applications. These commands work with `tailor.config.ts`.
 
-<!-- politty:command:init:heading:start -->
-
 ## init
 
-<!-- politty:command:init:heading:end -->
-
-<!-- politty:command:init:description:start -->
-
 Initialize a new project using create-sdk.
 
-<!-- politty:command:init:description:end -->
-
-<!-- politty:command:init:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk init [options] [name]
+tailor init [options] [name]
 ```
 
-<!-- politty:command:init:usage:end -->
-
-<!-- politty:command:init:arguments:start -->
-
 **Arguments**
 
 | Argument | Description  | Required |
 | -------- | ------------ | -------- |
 | `name`   | Project name | No       |
 
-<!-- politty:command:init:arguments:end -->
-
-<!-- politty:command:init:options:start -->
-
 **Options**
 
 | Option                  | Alias | Description   | Required | Default |
 | ----------------------- | ----- | ------------- | -------- | ------- |
 | `--template <TEMPLATE>` | `-t`  | Template name | No       | -       |
 
-<!-- politty:command:init:options:end -->
-
-<!-- politty:command:init:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:init:global-options-link:end -->
-
-<!-- politty:command:generate:heading:start -->
-
 ## generate
 
-<!-- politty:command:generate:heading:end -->
-
-<!-- politty:command:generate:description:start -->
-
 Generate files using Tailor configuration.
 
-<!-- politty:command:generate:description:end -->
-
-<!-- politty:command:generate:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk generate [options]
+tailor generate [options]
 ```
 
-<!-- politty:command:generate:usage:end -->
-
-<!-- politty:command:generate:options:start -->
-
 **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"` |
 
-<!-- politty:command:generate:options:end -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:generate:global-options-link:start -->
+## deploy
 
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+Deploy your application by applying the Tailor configuration.
 
-<!-- politty:command:generate:global-options-link:end -->
+**Usage**
 
-<!-- politty:command:deploy:heading:start -->
+```
+tailor deploy [options]
+```
 
-## deploy
+**Options**
 
-<!-- politty:command:deploy:heading:end -->
+| 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       | -                    | -                                 |
 
-<!-- politty:command:deploy:description:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+**Workspace Selection:**
 
-Deploy your application by applying the Tailor configuration.
+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.
 
-<!-- politty:command:deploy:description:end -->
+When the project has no saved selection, `deploy` discovers the account's workspaces:
 
-<!-- politty:command:deploy:usage:start -->
+- 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.
 
-**Usage**
+In CI and other non-interactive environments, workspace creation must be explicit:
 
-```
-tailor-sdk deploy [options]
+```bash
+tailor deploy \
+  --create-workspace \
+  --workspace-name example-workspace \
+  --workspace-region us-west
 ```
 
-<!-- politty:command:deploy:usage:end -->
+`--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.
 
-<!-- politty:command:deploy:options:start -->
+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.
 
-**Options**
+`--dry-run` never creates a workspace or writes project context. When an account has no workspace,
+create one explicitly before requesting a deployment plan.
 
-| 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                                           | 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       | -                    | -                                 |
+**Config File Modification:**
 
-<!-- politty:command:deploy:options:end -->
+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.
 
-<!-- politty:command:deploy:global-options-link:start -->
+**Multiple Config Deploys:**
 
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
+To deploy interdependent applications to the same workspace in one run, pass comma-separated config paths:
 
-<!-- politty:command:deploy:global-options-link:end -->
+```bash
+tailor deploy --config apps/buyer/tailor.config.ts,apps/supplier/tailor.config.ts
+```
 
-**Config File Modification:**
+When multiple configs are provided, `deploy` creates or updates all configured services first, then updates the applications. This lets one application reference resources owned by another config with `external: true` during the same deploy.
 
-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.
+Each config's `files` and `ignores` patterns (see [Service Configuration](../configuration.md#service-configuration)) resolve relative to that config's own directory, not the directory you ran `deploy` from. For example, `apps/buyer/tailor.config.ts` declaring `files: ["db/**/*.ts"]` loads files from `apps/buyer/db/`, independent of where `apps/supplier/tailor.config.ts`'s patterns resolve. If a config's relative patterns match nothing under its own directory, the SDK falls back to the invocation directory and logs a warning (see [Service Configuration](../configuration.md#service-configuration) for details).
 
 **Migration Handling:**
 
@@ -150,6 +143,10 @@ When migrations are configured (`db.tailordb.migration` in config), the `deploy`
 
 See [Automatic Migration Execution](../services/tailordb-migration.md#automatic-migration-execution) for details on automatic migration execution.
 
+**Concurrent Deploys:**
+
+Deploys that target the same workspace and application from the same project directory are serialized while secrets and auth connections are updated: one deploy proceeds and the other waits for it to finish. A deploy that cannot proceed within 5 minutes fails with an error, which normally means another deploy is still running. If a previous deploy was interrupted, the next deploy recovers automatically within about a minute. Deploys to different workspaces or applications are not affected.
+
 **Schema Check:**
 
 By default, `deploy` performs two verification steps:
@@ -173,219 +170,171 @@ Before applying changes, `deploy` shows a preview of the planned resource change
 After the detailed list, a summary line is printed:
 
 ```text
-Plan: 5 to create, 3 to update, 1 to delete, 25 unchanged
+Plan: 5 to create, 3 to update, 1 to delete
 ```
 
-Use `--dry-run` to preview the plan without applying anything.
+Use `--dry-run` to preview the plan without applying anything. In dry-run mode the plan is written to **stdout**, so it can be captured in CI without `2>&1`:
 
-<!-- politty:command:remove:heading:start -->
+```bash
+tailor deploy --dry-run > plan.txt
+```
 
-## remove
+In apply mode, the plan is printed to stderr so it does not interfere with piped output.
 
-<!-- politty:command:remove:heading:end -->
+**JSON Output:**
 
-<!-- politty:command:remove:description:start -->
+Pass the global `--json` / `-j` flag to get machine-readable output.
 
-Remove all resources managed by the application from the workspace.
+**Dry-run** (`--dry-run --json`): writes a JSON object to stdout:
 
-<!-- politty:command:remove:description:end -->
+```json
+{
+  "summary": { "create": 2, "update": 1, "delete": 0, "replace": 0 },
+  "changes": [{ "action": "create", "name": "Order", "labels": ["type"], "namespace": "tailordb" }],
+  "warnings": [
+    { "type": "unmanaged", "resourceType": "tailorDB", "name": "LegacyType" },
+    { "type": "skippedSecret", "resourceType": "secret", "name": "DB_PASSWORD" }
+  ],
+  "conflicts": [{ "resourceType": "tailorDB", "name": "User", "currentOwner": "other-app" }]
+}
+```
 
-<!-- politty:command:remove:usage:start -->
+- `summary` — counts of each change type.
+- `changes` — planned resource changes, each with `action`, `name`, and optional `labels` / `namespace`.
+- `warnings` — resources not in config (`type: "unmanaged"`) or secrets with missing values (`type: "skippedSecret"`). Unmanaged resources require confirmation in apply mode (apply is cancelled if declined); skipped secrets are non-blocking.
+- `conflicts` — resources owned by another application that conflict with the current config. Require confirmation in apply mode; apply is cancelled if declined.
 
-**Usage**
+**Apply** (`--json`): writes a JSON object to stdout:
 
-```
-tailor-sdk remove [options]
+```json
+{ "summary": { "create": 1, "update": 2, "delete": 0, "replace": 0 }, "status": "applied" }
 ```
 
-<!-- politty:command:remove:usage:end -->
+## remove
 
-<!-- politty:command:remove:options:start -->
+Remove all resources managed by the application from the workspace.
 
-**Options**
+**Usage**
 
-| 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   | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                         | `-y`  | Skip confirmation prompts | No       | `false`              | -                                 |
+```
+tailor remove [options]
+```
 
-<!-- politty:command:remove:options:end -->
+**Options**
 
-<!-- politty:command:remove:global-options-link:start -->
+| Option                          | Alias | Description                | Required | Default              | Env                            |
+| ------------------------------- | ----- | -------------------------- | -------- | -------------------- | ------------------------------ |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID` |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile          | No       | -                    | `TAILOR_PLATFORM_PROFILE`      |
+| `--config <CONFIG>`             | `-c`  | Path to Tailor config file | No       | `"tailor.config.ts"` | `TAILOR_CONFIG_PATH`           |
+| `--yes`                         | `-y`  | Skip confirmation prompts  | No       | `false`              | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:remove:global-options-link:end -->
-
-<!-- politty:command:show:heading:start -->
-
 ## show
 
-<!-- politty:command:show:heading:end -->
-
-<!-- politty:command:show:description:start -->
-
 Show information about the deployed application.
 
-<!-- politty:command:show:description:end -->
-
-<!-- politty:command:show:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk show [options]
+tailor show [options]
 ```
 
-<!-- politty:command:show:usage:end -->
-
-<!-- politty:command:show:options:start -->
-
 **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 | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-
-<!-- politty:command:show:options:end -->
-
-<!-- politty:command:show:global-options-link:start -->
+| 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`           |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:show:global-options-link:end -->
-
-<!-- politty:command:open:heading:start -->
-
 ## open
 
-<!-- politty:command:open:heading:end -->
-
-<!-- politty:command:open:description:start -->
-
 Open Tailor Platform Console.
 
-<!-- politty:command:open:description:end -->
-
-<!-- politty:command:open:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk open [options]
+tailor open [options]
 ```
 
-<!-- politty:command:open:usage:end -->
-
-<!-- politty:command:open:options:start -->
-
 **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 | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-
-<!-- politty:command:open:options:end -->
-
-<!-- politty:command:open:global-options-link:start -->
+| 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`           |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:open:global-options-link:end -->
-
-<!-- politty:command:api:heading:start -->
-
 ## api
 
-<!-- politty:command:api:heading:end -->
-
-<!-- politty:command:api:description:start -->
-
 Call Tailor Platform API endpoints directly.
 
-<!-- politty:command:api:description:end -->
-
-<!-- politty:command:api:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk api [options] [command] <endpoint>
+tailor api [options] [command] <endpoint>
 ```
 
-<!-- politty:command:api:usage:end -->
-
-<!-- politty:command:api:arguments:start -->
-
 **Arguments**
 
 | Argument   | Description                                                                                  | Required |
 | ---------- | -------------------------------------------------------------------------------------------- | -------- |
 | `endpoint` | API endpoint to call (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |
 
-<!-- politty:command:api:arguments:end -->
-
-<!-- politty:command:api:options:start -->
-
 **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                                                           | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--body <BODY>`                 | `-b`  | Request body as JSON.                                                             | No       | `"{}"`               | -                                 |
-| `--field <FIELD>`               | `-f`  | Set a body field as `key=value` (repeatable; dotted keys nest). Overrides --body. | No       | -                    | -                                 |
-
-<!-- politty:command:api:options:end -->
-
-<!-- politty:command:api:global-options-link:start -->
+| 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`           |
+| `--body <BODY>`                 | `-b`  | Request body as JSON.                                                             | No       | `"{}"`               | -                              |
+| `--field <FIELD>`               | `-f`  | Set a body field as `key=value` (repeatable; dotted keys nest). Overrides --body. | No       | -                    | -                              |
 
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api:global-options-link:end -->
+**Commands**
 
-<!-- politty:command:api:examples:start -->
+| Command                       | Description                                                  |
+| ----------------------------- | ------------------------------------------------------------ |
+| [`api list`](#api-list)       | List all invocable OperatorService methods.                  |
+| [`api inspect`](#api-inspect) | Print the input message tree of an OperatorService endpoint. |
 
 **Examples**
 
 **Call an endpoint; workspaceId is auto-injected.**
 
 ```bash
-$ tailor-sdk api GetApplication -b '{"applicationName":"app-1"}'
+$ tailor api GetApplication -b '{"applicationName":"app-1"}'
 ```
 
 **Same as above, using --field instead of --body.**
 
 ```bash
-$ tailor-sdk api GetApplication -f applicationName=app-1
+$ tailor api GetApplication -f applicationName=app-1
 ```
 
 **List all invocable OperatorService methods.**
 
 ```bash
-$ tailor-sdk api list
+$ tailor api list
 ```
 
 **Show the input message tree for an endpoint.**
 
 ```bash
-$ tailor-sdk api inspect GetApplication
+$ tailor api inspect GetApplication
 ```
 
-<!-- politty:command:api:examples:end -->
-
-<!-- politty:command:api:notes:start -->
-
 **Notes**
 
-Use `tailor-sdk api list` to enumerate invocable methods and `tailor-sdk api inspect <endpoint>` to print an endpoint's input message tree (combine with `--json` for machine-readable output).
+Use `tailor api list` to enumerate invocable methods and `tailor api inspect <endpoint>` to print an endpoint's input message tree (combine with `--json` for machine-readable output).
 
 The request body is inferred from the target endpoint's request schema, and commonly required fields are auto-injected so they can be omitted from `--body`:
 
@@ -398,103 +347,54 @@ Values already present in `--body` are never overridden. If a value cannot be re
 
 Use `--field key=value` (repeatable) to set request body fields without writing JSON. Dotted keys (e.g. `application.name=foo`) build nested objects. `--field` overrides matching fields in `--body` and tab-completes from the endpoint's request schema.
 
-<!-- politty:command:api:notes:end -->
-<!-- politty:command:api inspect:heading:start -->
-
 ### api inspect
 
-<!-- politty:command:api inspect:heading:end -->
-
-<!-- politty:command:api inspect:description:start -->
-
 Print the input message tree of an OperatorService endpoint.
 
-<!-- politty:command:api inspect:description:end -->
-
-<!-- politty:command:api inspect:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk api inspect <endpoint>
+tailor api inspect <endpoint>
 ```
 
-<!-- politty:command:api inspect:usage:end -->
-
-<!-- politty:command:api inspect:arguments:start -->
-
 **Arguments**
 
 | Argument   | Description                                                                                     | Required |
 | ---------- | ----------------------------------------------------------------------------------------------- | -------- |
 | `endpoint` | API endpoint to inspect (e.g., 'GetApplication' or 'tailor.v1.OperatorService/GetApplication'). | Yes      |
 
-<!-- politty:command:api inspect:arguments:end -->
-
-<!-- politty:command:api inspect:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api inspect:global-options-link:end -->
-
-<!-- politty:command:api inspect:examples:start -->
-
 **Examples**
 
 **Show fields of GetApplicationRequest.**
 
 ```bash
-$ tailor-sdk api inspect GetApplication
+$ tailor api inspect GetApplication
 ```
 
 **Inspect a deeply nested input with `(oneof config)` annotations.**
 
 ```bash
-$ tailor-sdk api inspect CreateExecutorExecutor
+$ tailor api inspect CreateExecutorExecutor
 ```
 
-<!-- politty:command:api inspect:examples:end -->
-
-<!-- politty:command:api inspect:notes:start -->
-
 **Notes**
 
-Combine with the global `--json` flag for a machine-readable descriptor. Recursive type references and `oneof` membership are annotated. Use `tailor-sdk api list` to discover endpoint names.
-
-<!-- politty:command:api inspect:notes:end -->
-
-<!-- politty:command:api list:heading:start -->
+Combine with the global `--json` flag for a machine-readable descriptor. Recursive type references and `oneof` membership are annotated. Use `tailor api list` to discover endpoint names.
 
 ### api list
 
-<!-- politty:command:api list:heading:end -->
-
-<!-- politty:command:api list:description:start -->
-
 List all invocable OperatorService methods.
 
-<!-- politty:command:api list:description:end -->
-
-<!-- politty:command:api list:usage:start -->
-
 **Usage**
 
 ```
-tailor-sdk api list
+tailor api list
 ```
 
-<!-- politty:command:api list:usage:end -->
-
-<!-- politty:command:api list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:api list:global-options-link:end -->
-
-<!-- politty:command:api list:notes:start -->
-
 **Notes**
 
 Only single-request (non-streaming) methods are listed, because the CLI issues a single JSON request and reads one JSON response.
-
-<!-- politty:command:api list:notes:end -->