@typeship-ax/cli 0.10.0 → 0.20.0

package/api.md

@@ -1,6 +1,6 @@
 # typeship — CLI reference
 
-API version 1.0.0. Package version 0.10.0. Generated by typeship; regenerate rather than editing.
+API version 1.0.0. Package version 0.20.0. Generated by typeship.
 
 Run `typeship help --json` for the command index. Path arguments are positional; flags use the names shown below. Arrays accept repeated flags, comma-separated values, or a JSON array; object values use JSON.
 
@@ -14,40 +14,66 @@ For complete input and output schemas, use [`api.json`](./api.json), the machine
 
 ### `typeship generate run [flags]`
 
-Generate one Target from a Definition
+Generate one package from a Definition
 
 `POST /generate`
 
 Safety: **write** · Authentication: **optional**
 
-Stateless generation: nothing is stored. Returns the full generated
-package as files. Works without an API key: anonymous calls generate
-the first 25 operations, rate limited per IP address, and the
-response's `limits` object says what was held back and where to lift
-it; anonymous calls from a Definition URL also carry `claim.url`, a link
-that turns the run into a project once a person signs in. With a key, the free plan generates the first 25 operations and
-paid plans generate the complete Definition. A present but invalid key is a
-401, not a downgrade to anonymous.
+Returns one generated package without creating a Project.
+
+Supports [idempotent retries](https://typeship.dev/docs/typeship-api/idempotency); keyed responses include generated files in the replay cache.
+
+Use `download.url` to save the complete ZIP, verify `download.sha256`, and extract it into an empty directory. The link expires at `download.expires_at` and grants access to anyone who has it. CLI, MCP, and SDK calls supply an idempotency key automatically. Agents should request `fields=["download","meta","warnings","limits","claim"]` to keep the MCP result compact; files can exceed the response limit. Download the ZIP instead of repeating generation to retrieve omitted files.
+
+Anonymous and Free requests include the first 25 operations. Paid plans include all operations. Anonymous requests are rate limited by IP address. Check `limits` for omitted operations; an invalid API key returns `401`.
+
+An anonymous URL request without source headers may return `claim.url`. Sign in through that link within seven days to save the recipe as a Project.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--definition` | body | `json` | yes | A Definition for stateless generation, provided as exactly one URL or inline entrypoint. |
-| `--target` | body | `object` | yes | Stateless generator descriptor; no persisted Target is created. |
+| `--definition` | body | `json` | yes | A Definition for one-shot generation, provided as exactly one URL or inline entrypoint. |
+| `--target` | body | `object` | yes | One-shot generator descriptor; no persisted Target is created. |
 | `--package-name` | body | `string` | no | npm package or Python distribution override. Valid only for the TypeScript and Python SDK targets. |
-| `--module-path` | body | `string` | no | Go module path override. Valid only for the Go SDK. Linked projects derive this from the Go destination repository by default. |
-| `--config` | body | `object` | no | Everything Typeship needs beyond the Definition, in one object: generation customization (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package, docs_url). Plain configuration. Typeship never requires vendor extensions inside the Definition itself. Stateless generation also accepts GraphQL settings here; stored projects keep those settings on their Definition. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--module-path` | body | `string` | no | Go module path override for the generated artifact's own module. Valid only for the Go SDK and Go CLI outputs. Linked projects derive this from the Go destination repository by default. |
+| `--go-sdk` | body | `object` | no | The exact paired Go SDK a go-cli generation is built on. Required when target.generator is go-cli and rejected otherwise. The descriptor is closed and immutable, because a CLI that pins a range or a branch pins nothing. |
+| `--config` | body | `object` | no | Everything Typeship needs beyond the Definition, in one object: generation customization (globals, retries, pagination, readme) and how the generated tooling behaves (cli, mcp, package, docs_url). Plain configuration. Typeship never requires vendor extensions inside the Definition itself. One-shot generation also accepts GraphQL settings here; stored projects keep those settings on their Definition. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship generate run --definition '{"url":"https://example.com"}' --target '{"generator":"typescript-sdk"}'
+typeship generate run --definition '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' --target '{"generator":"cli"}'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
 
 Read the full command contract with `typeship docs generate run --json`.
 
+### `typeship generate download-package [flags]`
+
+Download a generated package
+
+`GET /generate/download`
+
+Safety: **read** · Authentication: **none**
+
+Download the complete ZIP referenced by `generate_run`'s `download.url`. Pass the token from that URL. No API key is needed; the token grants access only to that exact package until its replay window expires. Keep the token private.
+
+The local MCP server saves this binary response to disk. On a hosted MCP connection, download the original URL directly to your workspace. Verify the ZIP against `download.sha256` before extracting it into an empty directory. Expired or invalid tokens return `404`; a new generation creates a new download.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `--query-token` | query | `string` | yes | Private download token from download.url in the generation result. |
+
+```sh
+typeship generate download-package --query-token parcel_download_example_token_1234567890123
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs generate download-package --json`.
+
 ## projects
 
 ### `typeship projects list [flags]`
@@ -60,8 +86,8 @@ Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship projects list
@@ -79,7 +105,9 @@ Create a project
 
 Safety: **write** · Authentication: **required**
 
-Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected target, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and generates every operation in the Definition.
+Creates a Project from a URL or GitHub Definition.
+
+Free includes one saved Project, all selected Targets, and the first 25 operations per Target, with regeneration, history, delivery pull requests, and previews. Pro supports additional Projects and all operations. One-shot generation does not use a Project slot.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -89,12 +117,12 @@ Stores a URL- or GitHub-sourced project. Free includes one stored project, every
 | `--auto-generate` | body | `boolean` | no | Whether Typeship should regenerate automatically when the source changes. Default: false. |
 | `--relay-enabled` | body | `boolean` | no | Enable webhook relay sessions. Requires the CLI target and Pro. Default: false. |
 | `--config` | body | `json` | no | Shared defaults inherited by every Target. GraphQL settings belong in definition.graphql. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship projects create --name example --definition '{"source":{"kind":"url","url":"https://example.com"}}' --targets '[{"name":"example","generator":"typescript-sdk"}]'
+typeship projects create --name 'Parcel API' --definition '{"source":{"kind":"url","url":"https://api.parcel.example/openapi.json"}}' --targets '[{"name":"Parcel CLI","generator":"cli","deliveries":[{"kind":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client"},"package_name":"parcel-client","publish_on_merge":false}]}]'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -109,7 +137,7 @@ Retrieve a project
 
 Safety: **read** · Authentication: **required**
 
-Returns Project-owned fields only. List Targets separately for Target and Delivery data.
+Returns the Project's settings and Definition ID. List its Targets separately to retrieve Target configuration and Deliveries.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -131,9 +159,13 @@ Delete a project
 
 Safety: **destructive** · Authentication: **required**
 
+A `502` response means the Project was not deleted because its release pull requests could not be retired. Retry deletion to finish retiring the remaining reviews. Repeating a completed deletion returns `404`.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
 typeship projects delete prj_4f8k2m7x9q1v6b3n --force
@@ -151,6 +183,13 @@ Update a project
 
 Safety: **write** · Authentication: **required**
 
+Omitted fields keep their current values. A supplied config replaces the entire stored object; null or an empty object clears it.
+Omitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.
+
+A `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publication to finish, reconcile your update, and retry.
+A `502` response means the Project was saved, but an obsolete release pull request could not be retired. Retrieve the Project and retry the same update to finish retiring reviews if that update is still desired.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
@@ -158,11 +197,12 @@ Safety: **write** · Authentication: **required**
 | `--auto-generate` | body | `boolean` | no | — |
 | `--relay-enabled` | body | `boolean` | no | Enable webhook relay sessions. Requires the CLI target and Pro. |
 | `--config` | body | `json` | no | Replaces the Project's shared Target defaults. Send null to clear them. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship projects update prj_4f8k2m7x9q1v6b3n
+typeship projects update prj_4f8k2m7x9q1v6b3n --auto-generate true
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -177,7 +217,7 @@ Analyze a project's latest Definition Revision
 
 Safety: **read** · Authentication: **required**
 
-Runs deterministic OpenAPI or GraphQL authorship checks against the latest observed immutable Definition Revision after applying the Definition's existing patches. Diagnostics group every affected location under a stable rule. Exact patches are included only when Typeship can derive the change without inventing API behavior.
+Checks the latest Definition Revision after applying its saved patches. Each finding groups affected locations under a stable rule ID. A suggested patch is included only when the Definition provides enough information to determine the correction.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -199,12 +239,12 @@ Refresh a project's Diagnostics from its configured source
 
 Safety: **write** · Authentication: **required**
 
-Fetches the complete configured source, records a new immutable revision only when content changed, and returns its Diagnostics. This does not generate targets or consume a metered generation.
+Fetches the configured source and returns updated Diagnostics. Creates a Definition Revision only when the content changes. Does not generate Targets or use a metered generation.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 ```sh
 typeship projects refresh-diagnostics prj_4f8k2m7x9q1v6b3n
@@ -222,18 +262,20 @@ Apply exact, reviewed diagnostic remediations
 
 Safety: **write** · Authentication: **required**
 
-Applies only deterministic patches. Repository sources receive an updateable source pull request; URL sources receive project overlays. Diagnostics that require API-owner intent return 422 and include an authoring_brief in the Diagnostic instead.
+Applies reviewed patches from Diagnostics. For a repository source, opens or updates a source pull request. For a URL source, saves Definition patches.
+
+Findings that need an API-owner decision return `422`. Read the finding's `authoring_brief` and update the source instead.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 | `--diagnostic-ids` | body | `array` | yes | Stable IDs of current diagnostics whose exact patches should be reviewed and applied. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship projects remediate-diagnostics prj_4f8k2m7x9q1v6b3n --diagnostic-ids '["value"]'
+typeship projects remediate-diagnostics prj_4f8k2m7x9q1v6b3n --diagnostic-ids '["missing-operation-id"]'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -248,7 +290,7 @@ Diagnose a project's repository integrations
 
 Safety: **read** · Authentication: **required**
 
-Returns provider-neutral, machine-actionable source and destination access, Definition readability, source-approval label setup, required status names, and the latest durable webhook delivery. The Console renders this same result.
+Checks repository access, Definition readability, source-approval labels, and required checks. Includes the latest webhook delivery so you can investigate missing updates.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -273,8 +315,8 @@ Safety: **read** · Authentication: **required**
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 | `--target-id` | query | `string` | no | Only generations for this persisted Target. |
 
 ```sh
@@ -287,27 +329,26 @@ Read the full command contract with `typeship docs projects list-generations --j
 
 ### `typeship projects generate <project_id> [flags]`
 
-Generate targets and open pull requests
+Start generation for active Targets
 
 `POST /projects/{project_id}/generations`
 
 Safety: **write** · Authentication: **required**
 
-Resolves the project's URL or GitHub source, generates every
-configured delivery package, stores each result in the project's history,
-and attempts to open a pull request in every configured destination.
-When the complete generated tree already matches a destination, no
-commit, branch, or pull request is created and that generation reports
-`pr_status: no_changes`. This is the same pipeline automatic
-regeneration runs after a source change.
+Queues one Generation per active Target and returns their IDs. Retrieve each Generation until its status moves from `queued` to `running` and then `succeeded` or `failed`. `succeeded` means generated files are saved; check Delivery and Draft status separately for repository delivery and pull requests. A Target already queued or running is returned without starting another Generation. A matching Idempotency-Key replay returns the same Generations with their current statuses.
+
+If the package already matches a destination and no Draft is open, delivery reports `pr_status: no_changes` without creating a commit, branch, or pull request. An existing Draft stays open. Automatic generation uses the same workflow.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--target-id` | body | `string` | no | Stable identifier for one configured generated product. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship projects generate prj_4f8k2m7x9q1v6b3n
+typeship projects generate prj_4f8k2m7x9q1v6b3n --target-id tgt_5m8q2v7k1p9d4h6c
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -344,21 +385,27 @@ Update and resolve a Definition
 
 Safety: **write** · Authentication: **required**
 
-Resolves the complete document graph and records a new immutable revision before saving.
+Resolves the source documents before saving the update and records a new Definition Revision when the source changes.
+Omitted fields remain unchanged; supplied objects and arrays replace the whole field.
+If the Definition or its Project configuration changes during validation, returns 409 definition_changed without saving the rejected update. Retrieve the current Definition and Project, reconcile your changes,
+and submit a new request with a new Idempotency-Key if using one.
+
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<definition_id>` | path | `string` | yes | — |
 | `--source` | body | `json` | no | — |
-| `--patches` | body | `array` | no | — |
-| `--graphql` | body | `json` | no | — |
+| `--patches` | body | `array` | no | Replace all patches in order. An empty array removes every patch; null is invalid. |
+| `--graphql` | body | `json` | no | Replace all GraphQL settings. Null or an empty object clears them. |
 | `--diagnostic-policy` | body | `object` | no | Source pull-request enforcement threshold, new-versus-complete baseline, and explicitly reviewed rule or location exceptions. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship definitions update def_2p8m4q7k1v9d6h3c
+typeship definitions update def_2p8m4q7k1v9d6h3c --source '{"kind":"url","url":"https://api.parcel.example/openapi.json"}'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -378,8 +425,8 @@ Safety: **read** · Authentication: **required**
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship targets list prj_4f8k2m7x9q1v6b3n
@@ -397,26 +444,27 @@ Create an independently configured Target
 
 Safety: **write** · Authentication: **required**
 
-Several Targets may use the same generator with distinct configuration, Deliveries, and release streams.
+Creates a Target with its own configuration, Deliveries, and release history. Multiple Targets can use the same generator.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 | `--name` | body | `string` | yes | — |
 | `--definition-id` | body | `string` | yes | Unique identifier for a project's logical API Definition. |
-| `--generator` | body | `string` | yes | Generator implementation selected by a Target. This is configuration, not identity; several Targets may use the same generator. |
+| `--generator` | body | `string` | yes | Generator implementation selected by a Target. This is configuration, not identity; several Targets may use the same generator. cli is the TypeScript CLI; go-cli is the native Go CLI, a distinct product that imports one exact paired Go SDK module rather than a client of its own. |
 | `--state` | body | `string` | no | Default: "active". |
 | `--edition` | body | `string` | no | Default: "2026-08-24". |
 | `--release-channel` | body | `string` | no | Default: "stable". |
 | `--proposed-version` | body | `string` | no | Optional larger or prerelease SemVer for the next reviewed release. |
+| `--checks` | body | `object` | no | Required checks run against the complete combined package. Generated checks and customer commands share one reproducible workflow; repository_required names existing repository checks. Supplying checks replaces all settings. Omitted generated restores build, package, and public_entrypoint; omitted repository_required and customer restore empty lists. An empty object restores these defaults. An empty array clears the corresponding list. |
 | `--config` | body | `json` | no | Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Definition. |
 | `--deliveries` | body | `array` | no | — |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets create prj_4f8k2m7x9q1v6b3n --name example --definition-id def_2p8m4q7k1v9d6h3c --generator typescript-sdk
+typeship targets create prj_4f8k2m7x9q1v6b3n --name 'Parcel CLI' --definition-id def_2p8m4q7k1v9d6h3c --generator cli --config '{"cli":{"command_name":"parcel"}}' --deliveries '[{"kind":"repository","repository":{"provider":"github","identifier":"parcel-example/parcel-client"},"package_name":"parcel-client","publish_on_merge":false}]'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -451,11 +499,14 @@ Delete an unused Target
 
 Safety: **destructive** · Authentication: **required**
 
-Targets with Generation or release history, or an active release candidate, must be disabled instead.
+Deletes a Target with no Generation history, release history, or active Draft. A `409 resource_has_dependencies` means one of those resources still depends on it. Retrieve the Target, disable it instead, or resolve the dependency before retrying.
+
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | — |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
 typeship targets delete tgt_5m8q2v7k1p9d4h6c --force
@@ -473,6 +524,14 @@ Update a Target, its Deliveries, or its next reviewed version
 
 Safety: **write** · Authentication: **required**
 
+Omitted fields keep their current values. Supplied config, checks, and deliveries replace their complete stored values.
+Omitting If-Match applies the update to the current resource; with If-Match, a stale ETag returns 412 precondition_failed without saving.
+Send proposed_version by itself; use the Draft endpoint to select a version directly.
+
+A `409 target_busy` means the Target is publishing; wait for it to finish. A `409 delivery_conflict` means another Target owns the requested repository tree; retrieve both Targets, choose a free destination, and retry.
+A `502` response means the update was saved, but retiring an obsolete review or regenerating a version selection failed. Retrieve the Target and follow the error's retryable and suggested_action fields. Repeating an unfinished version selection resumes generation; repeating a completed selection starts no new work.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | — |
@@ -480,14 +539,16 @@ Safety: **write** · Authentication: **required**
 | `--state` | body | `string` | no | — |
 | `--edition` | body | `string` | no | — |
 | `--release-channel` | body | `string` | no | — |
-| `--proposed-version` | body | `string` | no | — |
-| `--config` | body | `json` | no | Target-specific overrides merged over Project.config. GraphQL settings are rejected here and belong to the Definition. |
-| `--deliveries` | body | `array` | no | — |
+| `--proposed-version` | body | `string` | no | Send only this field to select an exact SemVer, or null for automatic selection. The Target and Draft endpoints both support an optional If-Match precondition. |
+| `--checks` | body | `object` | no | Required checks run against the complete combined package. Generated checks and customer commands share one reproducible workflow; repository_required names existing repository checks. Supplying checks replaces all settings. Omitted generated restores build, package, and public_entrypoint; omitted repository_required and customer restore empty lists. An empty object restores these defaults. An empty array clears the corresponding list. |
+| `--config` | body | `json` | no | Replaces the complete stored override object. Send null or an empty object to resume Project inheritance. Effective values merge over Project.config; GraphQL settings belong to the Definition. |
+| `--deliveries` | body | `array` | no | Replaces the Delivery set; include each kind you want to keep. Retained kinds preserve their ID, creation time, and hosted URL. Each supplied Delivery replaces its configuration, so omitted optional settings reset to their defaults. Omit deliveries to keep the existing set, or send [] to remove all Deliveries. Removing and later recreating a kind allocates a new ID and, for hosted_mcp, a new URL. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets update tgt_5m8q2v7k1p9d4h6c
+typeship targets update tgt_5m8q2v7k1p9d4h6c --state disabled
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -505,8 +566,8 @@ Safety: **read** · Authentication: **required**
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | — |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship targets list-releases tgt_5m8q2v7k1p9d4h6c
@@ -524,7 +585,7 @@ Retrieve a Target's rolling Draft release
 
 Safety: **read** · Authentication: **required**
 
-Returns Current, the cumulative Draft version and readiness, its exact head, and the optimistic release revision.
+Returns the Draft's status and its one next step, Current's version, the proposed version, readiness, checks, and conflict counts. Every status is described on `status`. The response carries an `ETag`; send it in `If-Match` when updating the Draft to avoid changing a newer version selection.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -546,18 +607,24 @@ Select an exact Draft version or return to automatic versioning
 
 Safety: **write** · Authentication: **required**
 
-Validates the selection against the cumulative required bump and regenerates the same rolling Draft pull request.
+Checks your version choice against the required version bump, then regenerates the existing Draft pull request.
+
+Send the Draft's `ETag` in `If-Match` to reject an intervening change with 412 precondition_failed before saving or regenerating. Omitting `If-Match` applies the selection to the current Draft. Version is required; null restores automatic selection.
+
+A `502` response means the selected version was saved, but regeneration failed. Follow the error's retryable and suggested_action fields. Repeating an unfinished selection resumes generation; repeating a completed selection starts no new work. If using If-Match, retrieve the Draft and confirm the saved selection before retrying with its current ETag.
+A `409 target_busy` means the Target is publishing; wait and retry. A `409 version_occupied` means the version is already released; retrieve the Draft and releases, choose a new version, and retry.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | — |
 | `--body-version` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
-| `--expected-revision` | body | `number` | no | — |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets update-draft tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0
+typeship targets update-draft tgt_5m8q2v7k1p9d4h6c --body-version 1.1.0
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -572,19 +639,19 @@ Adopt a verified existing package as Current
 
 Safety: **write** · Authentication: **required**
 
-Verifies the repository tag, package metadata, and registry artifact; records an Imported Current release; then opens the first Typeship Draft at the next major version because no trusted generated baseline exists yet.
+Checks the repository tag, package metadata, and registry artifact, then records the package as an Imported Current release. Opens the first Typeship Draft at the next major version; review it to establish the baseline for preserving existing code.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_id>` | path | `string` | yes | — |
 | `--body-version` | body | `string` | yes | Exact already-published package version to make Current. |
 | `--tag` | body | `string` | yes | Immutable repository tag containing the matching package source. |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets adopt-release tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag value
+typeship targets adopt-release tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag v1.0.0
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -595,7 +662,7 @@ Read the full command contract with `typeship docs targets adopt-release --json`
 
 Retrieve an immutable Target release
 
-`GET /target_releases/{target_release_id}`
+`GET /target-releases/{target_release_id}`
 
 Safety: **read** · Authentication: **required**
 
@@ -615,16 +682,18 @@ Read the full command contract with `typeship docs targets retrieve-release --js
 
 Retry publication of an exact Target release
 
-`POST /target_releases/{target_release_id}/republish`
+`POST /target-releases/{target_release_id}/republish`
 
 Safety: **write** · Authentication: **required**
 
-Dispatches the repository-owned republish workflow for this immutable version and accepted commit. It never selects the latest Draft or release.
+Retries publication of the specified release through its repository workflow. Uses that release's version and accepted commit, even if a newer Draft or release exists.
+
+A `502` response means the repository publication workflow could not be dispatched.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<target_release_id>` | path | `string` | yes | — |
-| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated account and operation; account-less generation uses a hashed network identity. Retrying the same method, path, query, If-Match header, and JSON body replays the original response. Reusing the key with changed intent returns 409. After expiry the key starts a new write. |
 
 ```sh
 typeship targets republish-release rel_7m2q8v4k1p9d5h6c
@@ -634,6 +703,186 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs targets republish-release --json`.
 
+### `typeship targets list-draft-files <target_id> [flags]`
+
+List customized and conflicted files on a Draft
+
+`GET /targets/{target_id}/draft/files`
+
+Safety: **read** · Authentication: **required**
+
+Lists the Draft's files that differ from the last accepted package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, where the incoming version comes from, the saved decision, and the sides you can read with retrieveDraftFileContent. With `filter=history`, lists the files affected by a default-branch history rewrite instead; the list is empty when none is pending.
+
+Returns `409 stale_draft` while Typeship has not integrated the Draft's latest commit (Draft status generating or branch_changed), or when the Draft changes between pages.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--filter` | query | `string` | no | conflicted: conflicts only. customized: files that differ from the last accepted package. history: files affected by a default-branch history rewrite. Omit for conflicted and customized files. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
+
+```sh
+typeship targets list-draft-files tgt_5m8q2v7k1p9d4h6c
+```
+
+Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` contains its arguments and `nextCommand` contains the command to fetch it. Use `--all` to stream every item from every page as NDJSON.
+
+Read the full command contract with `typeship docs targets list-draft-files --json`.
+
+### `typeship targets retrieve-draft-file-content <target_id> [flags]`
+
+Read one side of a Draft file
+
+`GET /targets/{target_id}/draft/files/content`
+
+Safety: **read** · Authentication: **required**
+
+Returns up to 24 KiB of one side of a conflicted or history-affected file: text as UTF-8, binary content as base64. Follow `next_cursor` with the same path and side to read the rest, and concatenate the chunks in order. A side where the file is absent returns 404.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--path` | query | `string` | yes | File path from listDraftFiles. |
+| `--side` | query | `string` | yes | A side listed for the file. |
+| `--cursor` | query | `string` | no | next_cursor from the preceding chunk of the same path and side. |
+
+```sh
+typeship targets retrieve-draft-file-content tgt_5m8q2v7k1p9d4h6c --path src/index.ts --side base
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets retrieve-draft-file-content --json`.
+
+### `typeship targets resolve-draft-conflicts <target_id> [flags]`
+
+Resolve selected Draft conflicts
+
+`POST /targets/{target_id}/draft/conflicts/resolve`
+
+Safety: **write** · Authentication: **required**
+
+Saves decisions for conflicts on the Draft's head_revision: keep the repository or incoming version, or supply the final content as text or, for binary files, base64. Decisions save together or not at all, and a decision can be replaced until it is applied. Use `dry_run` to validate them first.
+
+Saving changes no files. When every conflict has a decision, `remaining_conflicts` is 0 and the Draft status becomes `needs_generation`: generate the Target to apply the decisions and run its checks. Applying them can report conflicts from the next merge stage.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--expected-head-revision` | body | `string` | yes | The Draft's head_revision. A newer Draft commit returns 409 stale_draft without saving. |
+| `--resolutions` | body | `array` | yes | Unique current conflict paths. Final file content must total at most 2 MiB. Decisions save together or not at all. |
+| `--dry-run` | body | `boolean` | no | Validate the decisions and return the planned files without saving. Default: false. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
+```sh
+typeship targets resolve-draft-conflicts tgt_5m8q2v7k1p9d4h6c --expected-head-revision 0123456789abcdef0123456789abcdef01234567 --resolutions '[{"path":"src/index.ts","keep":"content","mode":"100644","content":"export { ParcelClient } from \"./client.js\";\nexport type { Shipment, Label } from \"./types.js\";\nexport { createParcelClient } from \"./helper.js\";\n"}]'
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets resolve-draft-conflicts --json`.
+
+### `typeship targets discard-draft-customizations <target_id> [flags]`
+
+Discard selected Draft customizations
+
+`POST /targets/{target_id}/draft/customizations/discard`
+
+Safety: **write** · Authentication: **required**
+
+Replaces the listed customized paths that are not conflicts with the generated files, in one commit on the Draft branch. A listed file that exists only on the Draft is deleted. Use `dry_run` to see the planned writes and deletions first. Resolve conflicts with resolveDraftConflicts.
+
+After the commit, the Draft status is `branch_changed` until Typeship integrates it from the repository's pull request event and reruns the checks; you do not need to generate the Target.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--expected-head-revision` | body | `string` | yes | The Draft's head_revision. A newer Draft commit returns 409 stale_draft without committing. |
+| `--paths` | body | `array` | yes | Customized paths that are not conflicts, to replace with the generated files. A listed file that exists only on the Draft is deleted. |
+| `--dry-run` | body | `boolean` | no | Return the planned writes and deletions without committing. Default: false. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
+```sh
+typeship targets discard-draft-customizations tgt_5m8q2v7k1p9d4h6c --expected-head-revision 0123456789abcdef0123456789abcdef01234567 --paths '["src/helper.ts"]' --dry-run true
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets discard-draft-customizations --json`.
+
+### `typeship targets recover-draft-history <target_id> [flags]`
+
+Approve recovery from rewritten default-branch history
+
+`POST /targets/{target_id}/draft/history/recover`
+
+Safety: **write** · Authentication: **required**
+
+When the Draft status is `history_rewritten`, review the affected files with `listDraftFiles` and `filter=history`, then approve with the Draft's `history_recovery` revisions. Approval saves the recovery without changing Git, and the Draft status becomes `needs_generation`: generate the Target to open a new Draft from the rewritten default branch. The previous Draft branch stays available, and overlapping code comes back as conflicts to resolve. A rewritten Draft branch alone needs no approval.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<target_id>` | path | `string` | yes | — |
+| `--expected-default-revision` | body | `string` | yes | The Draft's history_recovery.default_revision. |
+| `--expected-head-revision` | body | `string` | yes | The Draft's history_recovery.head_revision; null when the Draft branch is absent. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
+
+```sh
+typeship targets recover-draft-history tgt_5m8q2v7k1p9d4h6c --expected-default-revision 89abcdef0123456789abcdef0123456789abcdef --expected-head-revision 0123456789abcdef0123456789abcdef01234567
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets recover-draft-history --json`.
+
+### `typeship targets retrieve-delivery <delivery_id> [flags]`
+
+Retrieve a Delivery
+
+`GET /deliveries/{delivery_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns the configured repository or hosted MCP Delivery for a Target. A Delivery in another organization returns 404 not_found.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<delivery_id>` | path | `string` | yes | — |
+
+```sh
+typeship targets retrieve-delivery dlv_4q8m2v7k1p9d5h6c
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets retrieve-delivery --json`.
+
+### `typeship targets retrieve-publication <publication_id> [flags]`
+
+Retrieve a Publication
+
+`GET /publications/{publication_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns the current registry publication state for a Target Release. A Publication in another organization returns 404 not_found.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<publication_id>` | path | `string` | yes | — |
+
+```sh
+typeship targets retrieve-publication pub_2m8q4v7k1p9d5h6c
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs targets retrieve-publication --json`.
+
 ## generations
 
 ### `typeship generations retrieve <generation_id> [flags]`
@@ -644,7 +893,7 @@ Retrieve a generation
 
 Safety: **read** · Authentication: **required**
 
-Includes the generated files when the generation succeeded.
+Returns the current Generation status. `queued` and `running` mean generation is still in progress. `succeeded` means generated files are saved, not that repository delivery or a Draft is complete. Successful results include files, or a file index when the package is too large to inline.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -666,7 +915,7 @@ Fetch one file from a generation
 
 Safety: **read** · Authentication: **required**
 
-Raw file content, for generations whose target was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+Returns one file's raw content. Use a path from `files_index` when the Generation reports `files_omitted: true`.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -674,7 +923,7 @@ Raw file content, for generations whose target was too large to inline (files_om
 | `--path` | query | `string` | yes | Repo-relative path inside the generated package. |
 
 ```sh
-typeship generations retrieve-file gen_7h2p5d9c3m8w1k6q --path openapi.yaml
+typeship generations retrieve-file gen_7h2p5d9c3m8w1k6q --path README.md
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -691,13 +940,13 @@ List Definition Revisions
 
 Safety: **read** · Authentication: **required**
 
-Immutable snapshots of the complete resolved document graph this Definition observed, newest first. Content is available from the revision and document endpoints and is never embedded in a list response.
+Lists the Definition's revisions, newest first. Source content is not included; retrieve the revision content or individual documents separately.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<definition_id>` | path | `string` | yes | — |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship definition-revisions list def_2p8m4q7k1v9d6h3c
@@ -711,11 +960,11 @@ Read the full command contract with `typeship docs definition-revisions list --j
 
 Retrieve a Definition Revision
 
-`GET /definition_revisions/{definition_revision_id}`
+`GET /definition-revisions/{definition_revision_id}`
 
 Safety: **read** · Authentication: **required**
 
-Metadata for one immutable resolved document graph. Fetch its canonical content or individual source documents from the content endpoints.
+Returns metadata for a saved Definition Revision. Retrieve its resolved content or individual source documents separately.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -733,11 +982,11 @@ Read the full command contract with `typeship docs definition-revisions retrieve
 
 Retrieve a Definition Revision's canonical content
 
-`GET /definition_revisions/{definition_revision_id}/content`
+`GET /definition-revisions/{definition_revision_id}/content`
 
 Safety: **read** · Authentication: **required**
 
-Returns the exact canonical resolved content identified by the revision's graph digest, suitable for saving or piping into a diff.
+Returns the saved, resolved content for this revision. Save it locally or compare it with another revision.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
@@ -755,7 +1004,7 @@ Read the full command contract with `typeship docs definition-revisions retrieve
 
 Retrieve one source document from a Definition Revision
 
-`GET /definition_revisions/{definition_revision_id}/documents/{document_id}/content`
+`GET /definition-revisions/{definition_revision_id}/documents/{document_id}/content`
 
 Safety: **read** · Authentication: **required**
 
@@ -772,6 +1021,28 @@ Output: the response payload as JSON on stdout. A successful response without a
 
 Read the full command contract with `typeship docs definition-revisions retrieve-document-content --json`.
 
+### `typeship definition-revisions retrieve-document <definition_document_id> [flags]`
+
+Retrieve a Definition Document
+
+`GET /definition-documents/{definition_document_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns metadata for one source document captured in a Definition Revision. Retrieve its content through the revision's document content endpoint. A document in another organization returns 404 not_found.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<definition_document_id>` | path | `string` | yes | — |
+
+```sh
+typeship definition-revisions retrieve-document doc_8q2m5v1k9p4d7h3c
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs definition-revisions retrieve-document --json`.
+
 ## account
 
 ### `typeship account retrieve [flags]`
@@ -782,8 +1053,7 @@ The account behind the presented credentials
 
 Safety: **read** · Authentication: **required**
 
-Returns the account that owns the presented API key. This is also the
-identity endpoint the generated typeship CLI's `whoami` calls.
+Returns the account associated with your credential. The Typeship CLI uses this endpoint for `whoami`.
 
 ```sh
 typeship account retrieve
@@ -799,16 +1069,16 @@ Read the full command contract with `typeship docs account retrieve --json`.
 
 List API keys
 
-`GET /api_keys`
+`GET /api-keys`
 
 Safety: **read** · Authentication: **required**
 
-Keys are never returned in full — only their identity and last four. Creation stays in the console deliberately: a leaked key that can mint more keys is a leaked account.
+Lists key metadata and the last four characters of each key. Full keys are not returned. Create keys in the Console.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `--limit` | query | `number` | no | Maximum number of resources to return. Default: 20. |
-| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. |
+| `--limit` | query | `number` | no | Maximum number of resources to return. Omit for 20; otherwise supply base-10 digits representing an integer from 1 to 100. Empty, malformed, or out-of-range values return 400 invalid_request. List query parameters must appear only once; unrecognized parameters also return 400. Default: 20. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same account, operation, filters, and ordering that issued it. Omit to start at the first page. Empty, malformed, or repeated cursors return 400 invalid_request. The page limit may change between requests. |
 
 ```sh
 typeship api-keys list
@@ -818,22 +1088,48 @@ Output: JSON with `items` and `hasMore`; when another page exists, `nextPage` co
 
 Read the full command contract with `typeship docs api-keys list --json`.
 
+### `typeship api-keys retrieve <api_key_id> [flags]`
+
+Retrieve an API key
+
+`GET /api-keys/{api_key_id}`
+
+Safety: **read** · Authentication: **required**
+
+Returns the key summary and its ETag for conditional revocation.
+
+| Argument or flag | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `<api_key_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via api_keys_list). IDs come from api_keys_list. |
+
+```sh
+typeship api-keys retrieve apikey_2nY8mR6pQ4vK9cH3
+```
+
+Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+
+Read the full command contract with `typeship docs api-keys retrieve --json`.
+
 ### `typeship api-keys revoke <api_key_id> [flags]`
 
 Revoke an API key
 
-`DELETE /api_keys/{api_key_id}`
+`DELETE /api-keys/{api_key_id}`
 
 Safety: **destructive** · Authentication: **required**
 
-Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded. An OAuth member may revoke a key they created; an organization admin may revoke any key. Organization API keys retain account-wide authority.
+Revokes a key. Repeating the request returns the same result.
+
+With OAuth, members can revoke their own keys; organization admins can revoke any key. Organization API keys can revoke any key in their account.
+See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `<api_key_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via api_keys_list). IDs come from api_keys_list. |
+| `--if-match` | header | `string` | no | ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes. |
 
 ```sh
-typeship api-keys revoke api_key_123 --force
+typeship api-keys revoke apikey_2nY8mR6pQ4vK9cH3 --force
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.