@typeship-ax/cli 0.20.0 → 0.21.0

package/api.md

@@ -1,6 +1,6 @@
 # typeship — CLI reference
 
-API version 1.0.0. Package version 0.20.0. Generated by typeship.
+API version 1.0.0. Package version 0.21.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,7 +14,7 @@ For complete input and output schemas, use [`api.json`](./api.json), the machine
 
 ### `typeship generate run [flags]`
 
-Generate one package from a Definition
+Generate one package from a Spec
 
 `POST /generate`
 
@@ -24,26 +24,26 @@ 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.
+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","coverage","warnings","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`.
+Anonymous and Free requests include the first 25 operations. Paid plans include all operations. Anonymous requests are rate limited by IP address. Check `coverage` 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 one-shot generation, provided as exactly one URL or inline entrypoint. |
+| `--spec` | body | `json` | yes | A Spec 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 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. |
+| `--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 Targets. 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.type 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 Spec, 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 Spec itself. One-shot generation also accepts GraphQL settings here; stored projects keep those settings on their Spec. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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://typeship.dev/examples/petstore/openapi.yaml"}' --target '{"generator":"cli"}'
+typeship generate run --spec '{"url":"https://typeship.dev/examples/petstore/openapi.yaml"}' --target '{"type":"cli"}'
 ```
 
 Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
@@ -87,7 +87,7 @@ Safety: **read** · Authentication: **required**
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `--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. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, 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
@@ -105,51 +105,51 @@ Create a project
 
 Safety: **write** · Authentication: **required**
 
-Creates a Project from a URL or GitHub Definition.
+Creates a Project from a URL or GitHub Spec.
+Automatic generation is enabled by default for a saved Project.
 
 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 |
 | --- | --- | --- | --- | --- |
 | `--name` | body | `string` | yes | — |
-| `--definition` | body | `object` | yes | — |
+| `--spec` | body | `object` | yes | — |
 | `--targets` | body | `array` | yes | Initial first-class Targets. More than one may use the same generator with different identities or Deliveries. |
-| `--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, 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. |
+| `--auto-generate` | body | `boolean` | no | Whether Typeship should regenerate automatically when the source or saved configuration changes. Default: true. |
+| `--config` | body | `json` | no | Shared defaults inherited by every Target. GraphQL settings belong in spec.graphql. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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 '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}]}]'
+typeship projects create --name 'Parcel API' --spec '{"source":{"type":"url","url":{"url":"https://api.parcel.example/openapi.json"}}}' --targets '[{"name":"Parcel CLI","type":"cli","deliveries":[{"type":"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}`.
 
 Read the full command contract with `typeship docs projects create --json`.
 
-### `typeship projects retrieve <project_id> [flags]`
+### `typeship projects get <project_id> [flags]`
 
-Retrieve a project
+Get a project
 
 `GET /projects/{project_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns the Project's settings and Definition ID. List its Targets separately to retrieve Target configuration and Deliveries.
+Returns the Project's settings and Spec ID. List its Targets separately to retrieve Target configuration and Deliveries.
 
 | 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. |
 
 ```sh
-typeship projects retrieve prj_4f8k2m7x9q1v6b3n
+typeship projects get prj_4f8k2m7x9q1v6b3n
 ```
 
 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 projects retrieve --json`.
+Read the full command contract with `typeship docs projects get --json`.
 
 ### `typeship projects delete <project_id> [flags]`
 
@@ -184,9 +184,10 @@ 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.
+With auto_generate enabled, changing shared config queues a Generation for each Target whose effective config changes. A queued or running Target reuses that Generation.
 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 `409 target_busy` means a Target is publishing. Retrieve the Project, wait for publishing 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.
 
@@ -195,252 +196,229 @@ See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writ
 | `<project_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 | `--name` | body | `string` | no | — |
 | `--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 --auto-generate true
+typeship projects update prj_4f8k2m7x9q1v6b3n --auto-generate false
 ```
 
 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 projects update --json`.
 
-### `typeship projects retrieve-diagnostics <project_id> [flags]`
+### `typeship projects generate <project_id> [flags]`
 
-Analyze a project's latest Definition Revision
+Start generation for active Targets
 
-`GET /projects/{project_id}/diagnostics`
+`POST /projects/{project_id}/generate`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
+
+Queues one Generation per active Target and returns their IDs. Retrieve each Generation until its status moves from `queued` to `running` and then `completed` or `failed`. `completed` 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.
 
-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.
+If the package already matches a destination and no Draft is open, delivery creates no 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. |
+| `--target-id` | body | `string` | no | Stable identifier for one configured generated product. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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 retrieve-diagnostics 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}`.
 
-Read the full command contract with `typeship docs projects retrieve-diagnostics --json`.
+Read the full command contract with `typeship docs projects generate --json`.
 
-### `typeship projects refresh-diagnostics <project_id> [flags]`
+## specs
 
-Refresh a project's Diagnostics from its configured source
+### `typeship specs get <spec_id> [flags]`
 
-`POST /projects/{project_id}/diagnostics`
+Get a Spec
 
-Safety: **write** · Authentication: **required**
+`GET /specs/{spec_id}`
 
-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.
+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. |
-| `--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. |
+| `<spec_id>` | path | `string` | yes | — |
 
 ```sh
-typeship projects refresh-diagnostics prj_4f8k2m7x9q1v6b3n
+typeship specs get spec_2p8m4q7k1v9d6h3c
 ```
 
 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 projects refresh-diagnostics --json`.
+Read the full command contract with `typeship docs specs get --json`.
 
-### `typeship projects remediate-diagnostics <project_id> [flags]`
+### `typeship specs update <spec_id> [flags]`
 
-Apply exact, reviewed diagnostic remediations
+Update and resolve a Spec
 
-`POST /projects/{project_id}/diagnostics/remediations`
+`PATCH /specs/{spec_id}`
 
 Safety: **write** · Authentication: **required**
 
-Applies reviewed patches from Diagnostics. For a repository source, opens or updates a source pull request. For a URL source, saves Definition patches.
+Resolves the source files before saving the update and records a new Spec Revision when the source changes.
+Omitted fields remain unchanged; supplied objects and arrays replace the whole field.
+If the Spec or its Project configuration changes during validation, returns 409 resource_changed without saving the rejected update. Retrieve the current Spec and Project, reconcile your changes,
+and submit a new request with a new Idempotency-Key if using one.
 
-Findings that need an API-owner decision return `422`. Read the finding's `authoring_brief` and update the source instead.
+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. |
-| `--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, 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. |
+| `<spec_id>` | path | `string` | yes | — |
+| `--source` | 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. |
+| `--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 organization and operation; generation without an organization 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 '["missing-operation-id"]'
+typeship specs update spec_2p8m4q7k1v9d6h3c --source '{"type":"url","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}`.
 
-Read the full command contract with `typeship docs projects remediate-diagnostics --json`.
+Read the full command contract with `typeship docs specs update --json`.
 
-### `typeship projects retrieve-integration-health <project_id> [flags]`
+### `typeship specs refresh <spec_id> [flags]`
 
-Diagnose a project's repository integrations
+Refresh a Spec from its configured source
 
-`GET /projects/{project_id}/integration-health`
+`POST /specs/{spec_id}/refresh`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
 
-Checks repository access, Definition readability, source-approval labels, and required checks. Includes the latest webhook delivery so you can investigate missing updates.
+Fetches the configured source now and creates a new Spec Revision only when its content changes. Diagnostics then reads that revision. If automatic generation is enabled, refresh queues generation for active Targets even when the source is unchanged.
 
 | 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. |
+| `<spec_id>` | path | `string` | yes | — |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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 retrieve-integration-health prj_4f8k2m7x9q1v6b3n
+typeship specs refresh spec_2p8m4q7k1v9d6h3c
 ```
 
 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 projects retrieve-integration-health --json`.
+Read the full command contract with `typeship docs specs refresh --json`.
 
-### `typeship projects list-generations <project_id> [flags]`
+## specRevisions
 
-List a project's generations
+### `typeship spec-revisions list [flags]`
 
-`GET /projects/{project_id}/generations`
+List Spec Revisions
+
+`GET /spec-revisions`
 
 Safety: **read** · Authentication: **required**
 
+Lists Spec Revisions, newest first. Source content is not included; list a revision's files with listSpecRevisionFiles.
+
 | 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. 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. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, 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. |
+| `--spec-id` | query | `string` | no | Only revisions of this Spec. |
 
 ```sh
-typeship projects list-generations prj_4f8k2m7x9q1v6b3n
+typeship spec-revisions list
 ```
 
 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 projects list-generations --json`.
+Read the full command contract with `typeship docs spec-revisions list --json`.
 
-### `typeship projects generate <project_id> [flags]`
-
-Start generation for active Targets
+### `typeship spec-revisions get <spec_revision_id> [flags]`
 
-`POST /projects/{project_id}/generations`
+Get a Spec Revision
 
-Safety: **write** · Authentication: **required**
+`GET /spec-revisions/{spec_revision_id}`
 
-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.
+Safety: **read** · Authentication: **required**
 
-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.
+Returns metadata for a saved Spec Revision with a Diagnostics summary. Pass `include=diagnostics` to add every Diagnostic, evaluated with the Spec's current patches and Diagnostic policy. List its source files and resolved document with listSpecRevisionFiles.
 
 | 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. |
-| `--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.
+| `<spec_revision_id>` | path | `string` | yes | — |
+| `--include` | query | `string` | no | Add related data to the response. `diagnostics` adds the `diagnostics` and `patch_diagnostics` arrays. |
 
 ```sh
-typeship projects generate prj_4f8k2m7x9q1v6b3n --target-id tgt_5m8q2v7k1p9d4h6c
+typeship spec-revisions get srev_6m1q8v4k2p9d7h3c
 ```
 
 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 projects generate --json`.
-
-## definitions
+Read the full command contract with `typeship docs spec-revisions get --json`.
 
-### `typeship definitions retrieve <definition_id> [flags]`
+### `typeship spec-revisions list-files <spec_revision_id> [flags]`
 
-Retrieve a Definition
+List a Spec Revision's files
 
-`GET /definitions/{definition_id}`
+`GET /spec-revisions/{spec_revision_id}/files`
 
 Safety: **read** · Authentication: **required**
 
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `<definition_id>` | path | `string` | yes | — |
-
-```sh
-typeship definitions retrieve def_2p8m4q7k1v9d6h3c
-```
-
-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 definitions retrieve --json`.
-
-### `typeship definitions update <definition_id> [flags]`
-
-Update and resolve a Definition
-
-`PATCH /definitions/{definition_id}`
-
-Safety: **write** · Authentication: **required**
-
-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.
+Lists the captured source files and the resolved document Typeship generated from, ordered by path. Read content with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_id>` | path | `string` | yes | — |
-| `--source` | 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. |
-| `--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.
+| `<spec_revision_id>` | path | `string` | yes | — |
+| `--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 organization, 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 definitions update def_2p8m4q7k1v9d6h3c --source '{"kind":"url","url":"https://api.parcel.example/openapi.json"}'
+typeship spec-revisions list-files srev_6m1q8v4k2p9d7h3c
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+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 definitions update --json`.
+Read the full command contract with `typeship docs spec-revisions list-files --json`.
 
 ## targets
 
-### `typeship targets list <project_id> [flags]`
+### `typeship targets list [flags]`
 
-List a project's Targets
+List Targets
 
-`GET /projects/{project_id}/targets`
+`GET /targets`
 
 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. 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. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, 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. |
+| `--project-id` | query | `string` | no | Only Targets in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
 
 ```sh
-typeship targets list prj_4f8k2m7x9q1v6b3n
+typeship targets list
 ```
 
 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 --json`.
 
-### `typeship targets create <project_id> [flags]`
+### `typeship targets create [flags]`
 
 Create an independently configured Target
 
-`POST /projects/{project_id}/targets`
+`POST /targets`
 
 Safety: **write** · Authentication: **required**
 
@@ -448,32 +426,30 @@ Creates a Target with its own configuration, Deliveries, and release history. Mu
 
 | 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. |
+| `--project-id` | body | `string` | yes | Unique identifier for a project. 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. 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". |
+| `--spec-id` | body | `string` | yes | Unique identifier for a project's logical API Spec. |
+| `--type` | 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. |
+| `--status` | body | `string` | no | Default: "active". |
 | `--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. |
+| `--checks` | body | `object` | no | Required checks run against the code in the Draft. 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 Spec. |
 | `--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, 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. |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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 '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}]'
+typeship targets create --project-id prj_4f8k2m7x9q1v6b3n --name 'Parcel CLI' --spec-id spec_2p8m4q7k1v9d6h3c --type cli --config '{"cli":{"command_name":"parcel"}}' --deliveries '[{"type":"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}`.
 
 Read the full command contract with `typeship docs targets create --json`.
 
-### `typeship targets retrieve <target_id> [flags]`
+### `typeship targets get <target_id> [flags]`
 
-Retrieve a Target
+Get a Target
 
 `GET /targets/{target_id}`
 
@@ -481,15 +457,15 @@ Safety: **read** · Authentication: **required**
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship targets retrieve tgt_5m8q2v7k1p9d4h6c
+typeship targets get tgt_5m8q2v7k1p9d4h6c
 ```
 
 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 --json`.
+Read the full command contract with `typeship docs targets get --json`.
 
 ### `typeship targets delete <target_id> [flags]`
 
@@ -505,7 +481,7 @@ See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writ
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_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
@@ -518,330 +494,327 @@ Read the full command contract with `typeship docs targets delete --json`.
 
 ### `typeship targets update <target_id> [flags]`
 
-Update a Target, its Deliveries, or its next reviewed version
+Update a Target or its Deliveries
 
 `PATCH /targets/{target_id}`
 
 Safety: **write** · Authentication: **required**
 
 Omitted fields keep their current values. Supplied config, checks, and deliveries replace their complete stored values.
+With Project auto_generate enabled, changing Target config, checks, or Deliveries queues that Target's Generation. A queued or running Target reuses that Generation.
 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.
+Select the next version through PATCH /drafts/{draft_id} on the Target's draft_id.
 
 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.
+A `502` response means the update was saved, but retiring an obsolete review or regenerating the Target failed. Retrieve the Target and follow the error's retryable and suggested_action fields.
 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 | — |
+| `<target_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 | `--name` | body | `string` | no | — |
-| `--state` | body | `string` | no | — |
-| `--edition` | body | `string` | no | — |
+| `--status` | body | `string` | no | — |
 | `--release-channel` | body | `string` | 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. |
+| `--checks` | body | `object` | no | Required checks run against the code in the Draft. 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 Spec. |
 | `--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 --state disabled
+typeship targets update tgt_5m8q2v7k1p9d4h6c --status disabled
 ```
 
 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 update --json`.
 
-### `typeship targets list-releases <target_id> [flags]`
+### `typeship targets adopt <target_id> [flags]`
 
-List immutable releases for a Target
+Adopt a verified existing package as the latest release
 
-`GET /targets/{target_id}/releases`
+`POST /targets/{target_id}/adopt`
 
-Safety: **read** · Authentication: **required**
+Safety: **write** · Authentication: **required**
+
+Checks the repository tag, package metadata, and registry artifact, then records the package as an Imported latest 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 | — |
-| `--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>` | path | `string` | yes | Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--body-version` | body | `string` | yes | Exact already-published package version to make the latest release. |
+| `--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 organization and operation; generation without an organization 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 list-releases tgt_5m8q2v7k1p9d4h6c
+typeship targets adopt tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag v1.0.0
 ```
 
-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.
+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 adopt --json`.
 
-Read the full command contract with `typeship docs targets list-releases --json`.
+## drafts
 
-### `typeship targets retrieve-draft <target_id> [flags]`
+### `typeship drafts list [flags]`
 
-Retrieve a Target's rolling Draft release
+List Drafts
 
-`GET /targets/{target_id}/draft`
+`GET /drafts`
 
 Safety: **read** · Authentication: **required**
 
-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.
+Lists open and merged Drafts, newest first. Each Target has one open Draft; each merge adds a merged Draft.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
+| `--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 organization, 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 Drafts of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--status` | query | `string` | no | Only Drafts with this status. |
 
 ```sh
-typeship targets retrieve-draft tgt_5m8q2v7k1p9d4h6c
+typeship drafts list
 ```
 
-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 --json`.
+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.
 
-### `typeship targets update-draft <target_id> [flags]`
+Read the full command contract with `typeship docs drafts list --json`.
 
-Select an exact Draft version or return to automatic versioning
+### `typeship drafts get <draft_id> [flags]`
 
-`PATCH /targets/{target_id}/draft`
+Get a Draft
 
-Safety: **write** · Authentication: **required**
+`GET /drafts/{draft_id}`
 
-Checks your version choice against the required version bump, then regenerates the existing Draft pull request.
+Safety: **read** · Authentication: **required**
 
-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.
+Returns the Draft's status. An open Draft also reports its typed reason when action is required, next version and its source, readiness, checks, and conflict counts. 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 |
 | --- | --- | --- | --- | --- |
-| `<target_id>` | path | `string` | yes | — |
-| `--body-version` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
-| `--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.
+| `<draft_id>` | path | `string` | yes | — |
 
 ```sh
-typeship targets update-draft tgt_5m8q2v7k1p9d4h6c --body-version 1.1.0
+typeship drafts get drf_3q7m1v8k2p5d9h4c
 ```
 
 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 update-draft --json`.
+Read the full command contract with `typeship docs drafts get --json`.
 
-### `typeship targets adopt-release <target_id> [flags]`
+### `typeship drafts update <draft_id> [flags]`
 
-Adopt a verified existing package as Current
+Select an exact Draft version or return to automatic versioning
 
-`POST /targets/{target_id}/adopt`
+`PATCH /drafts/{draft_id}`
 
 Safety: **write** · Authentication: **required**
 
-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.
+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_next 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 draft_merged` means the Draft merged; retrieve the Target and select a version on its `draft_id`. 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 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, 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. |
+| `<draft_id>` | path | `string` | yes | — |
+| `--version-next` | body | `string` | yes | Exact SemVer, or null to return to automatic selection. |
+| `--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 adopt-release tgt_5m8q2v7k1p9d4h6c --body-version 1.0.0 --tag v1.0.0
+typeship drafts update drf_3q7m1v8k2p5d9h4c --version-next 1.1.0
 ```
 
 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 adopt-release --json`.
+Read the full command contract with `typeship docs drafts update --json`.
 
-### `typeship targets retrieve-release <target_release_id> [flags]`
+### `typeship drafts list-files <draft_id> [flags]`
 
-Retrieve an immutable Target release
+List customized and conflicted files on a Draft
 
-`GET /target-releases/{target_release_id}`
+`GET /drafts/{draft_id}/files`
 
 Safety: **read** · Authentication: **required**
 
+Lists the Draft's files that differ from the last merged package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, the saved decision, and the sides you can read with getFile. With `filter=history`, lists files affected by a default-branch history rewrite; the list is empty when none is pending.
+
+Returns `409 resource_changed` while Typeship is carrying the Draft's latest commit forward (status working), or when the Draft changes between pages.
+
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<target_release_id>` | path | `string` | yes | — |
+| `<draft_id>` | path | `string` | yes | — |
+| `--filter` | query | `string` | no | conflicted: conflicts only. customized: files that differ from the last merged 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 organization, 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 retrieve-release rel_7m2q8v4k1p9d5h6c
+typeship drafts list-files drf_3q7m1v8k2p5d9h4c
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+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 retrieve-release --json`.
+Read the full command contract with `typeship docs drafts list-files --json`.
 
-### `typeship targets republish-release <target_release_id> [flags]`
+### `typeship drafts resolve <draft_id> [flags]`
 
-Retry publication of an exact Target release
+Resolve selected Draft files
 
-`POST /target-releases/{target_release_id}/republish`
+`POST /drafts/{draft_id}/resolve`
 
 Safety: **write** · Authentication: **required**
 
-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.
+Resolves conflicts on the Draft's head_sha: keep yours or generated, or supply final content as text or, for binary files, base64. Choosing generated for a customized path replaces it with the generated file, or deletes a Draft-only file.
 
-A `502` response means the repository publication workflow could not be dispatched.
+Conflict decisions are saved together and can be replaced until applied. Choosing generated for customized paths commits those changes together on the Draft branch. Returns the Draft. When every conflict has a decision, `conflicts.decided` equals `conflicts.total` and Typeship continues the Draft and runs checks. Paths that already match the Draft change nothing.
 
 | 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, 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. |
+| `<draft_id>` | path | `string` | yes | — |
+| `--expected-head-sha` | body | `string` | yes | The Draft's head_sha. A newer Draft commit returns 409 resource_changed without saving. |
+| `--resolutions` | body | `array` | yes | Unique current conflict or customized paths. Choose generated to discard a customization, including a Draft-only file. Final file content must total at most 2 MiB. Decisions apply together or not at all. |
+
+Use `--data '<json>'`, `--data @body.json`, or `--data -` to supply the request body. Field flags override matching body fields.
 
 ```sh
-typeship targets republish-release rel_7m2q8v4k1p9d5h6c
+typeship drafts resolve drf_3q7m1v8k2p5d9h4c --expected-head-sha 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 republish-release --json`.
+Read the full command contract with `typeship docs drafts resolve --json`.
 
-### `typeship targets list-draft-files <target_id> [flags]`
+### `typeship drafts recover <draft_id> [flags]`
 
-List customized and conflicted files on a Draft
-
-`GET /targets/{target_id}/draft/files`
+Approve recovery from rewritten default-branch history
 
-Safety: **read** · Authentication: **required**
+`POST /drafts/{draft_id}/recover`
 
-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.
+Safety: **write** · Authentication: **required**
 
-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.
+When the Draft has status `action_required` and reason `history_rewritten`, review affected files with `listDraftFiles` and `filter=history`, then approve with the Draft's `history_recovery` revisions. Approval saves the recovery without changing Git and returns the Draft; the next generation rebuilds it 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 | — |
-| `--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. |
+| `<draft_id>` | path | `string` | yes | — |
+| `--expected-default-sha` | body | `string` | yes | The Draft's history_recovery.default_sha. |
+| `--expected-head-sha` | body | `string` | yes | The Draft's history_recovery.head_sha; 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 list-draft-files tgt_5m8q2v7k1p9d4h6c
+typeship drafts recover drf_3q7m1v8k2p5d9h4c --expected-default-sha 89abcdef0123456789abcdef0123456789abcdef --expected-head-sha 0123456789abcdef0123456789abcdef01234567
 ```
 
-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.
+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 list-draft-files --json`.
+Read the full command contract with `typeship docs drafts recover --json`.
 
-### `typeship targets retrieve-draft-file-content <target_id> [flags]`
+## releases
 
-Read one side of a Draft file
+### `typeship releases list [flags]`
 
-`GET /targets/{target_id}/draft/files/content`
+List releases
 
-Safety: **read** · Authentication: **required**
+`GET /releases`
 
-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.
+Safety: **read** · Authentication: **required**
 
 | 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. |
+| `--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 organization, 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 releases of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship targets retrieve-draft-file-content tgt_5m8q2v7k1p9d4h6c --path src/index.ts --side base
+typeship releases list
 ```
 
-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]`
+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.
 
-Resolve selected Draft conflicts
+Read the full command contract with `typeship docs releases list --json`.
 
-`POST /targets/{target_id}/draft/conflicts/resolve`
+### `typeship releases get <release_id> [flags]`
 
-Safety: **write** · Authentication: **required**
+Get an immutable release
 
-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.
+`GET /releases/{release_id}`
 
-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.
+Safety: **read** · Authentication: **required**
 
 | 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.
+| `<release_id>` | path | `string` | yes | — |
 
 ```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"}]'
+typeship releases get rel_7m2q8v4k1p9d5h6c
 ```
 
 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`.
+Read the full command contract with `typeship docs releases get --json`.
 
-### `typeship targets discard-draft-customizations <target_id> [flags]`
+### `typeship releases republish <release_id> [flags]`
 
-Discard selected Draft customizations
+Retry publishing an exact release
 
-`POST /targets/{target_id}/draft/customizations/discard`
+`POST /releases/{release_id}/republish`
 
 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.
+Retries publishing the specified release through its repository workflow. Uses that release's version and accepted commit, even if a newer Draft or release exists.
 
-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.
+A `502` response means the repository publishing workflow could not be dispatched.
 
 | 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.
+| `<release_id>` | path | `string` | yes | — |
+| `--idempotency-key` | header | `string` | no | Identifies one logical write for 24 hours. The key is scoped to the authenticated organization and operation; generation without an organization 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 discard-draft-customizations tgt_5m8q2v7k1p9d4h6c --expected-head-revision 0123456789abcdef0123456789abcdef01234567 --paths '["src/helper.ts"]' --dry-run true
+typeship releases republish rel_7m2q8v4k1p9d5h6c
 ```
 
 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`.
+Read the full command contract with `typeship docs releases republish --json`.
 
-### `typeship targets recover-draft-history <target_id> [flags]`
+## deliveries
 
-Approve recovery from rewritten default-branch history
+### `typeship deliveries list [flags]`
 
-`POST /targets/{target_id}/draft/history/recover`
+List Deliveries
 
-Safety: **write** · Authentication: **required**
+`GET /deliveries`
 
-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.
+Safety: **read** · Authentication: **required**
 
 | 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.
+| `--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 organization, 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 Deliveries of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
 
 ```sh
-typeship targets recover-draft-history tgt_5m8q2v7k1p9d4h6c --expected-default-revision 89abcdef0123456789abcdef0123456789abcdef --expected-head-revision 0123456789abcdef0123456789abcdef01234567
+typeship deliveries list
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+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 recover-draft-history --json`.
+Read the full command contract with `typeship docs deliveries list --json`.
 
-### `typeship targets retrieve-delivery <delivery_id> [flags]`
+### `typeship deliveries get <delivery_id> [flags]`
 
-Retrieve a Delivery
+Get a Delivery
 
 `GET /deliveries/{delivery_id}`
 
@@ -854,214 +827,175 @@ Returns the configured repository or hosted MCP Delivery for a Target. A Deliver
 | `<delivery_id>` | path | `string` | yes | — |
 
 ```sh
-typeship targets retrieve-delivery dlv_4q8m2v7k1p9d5h6c
+typeship deliveries get 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}`
+Read the full command contract with `typeship docs deliveries get --json`.
 
-Safety: **read** · Authentication: **required**
+## publications
 
-Returns the current registry publication state for a Target Release. A Publication in another organization returns 404 not_found.
+### `typeship publications list [flags]`
 
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `<publication_id>` | path | `string` | yes | — |
+List publications
 
-```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]`
-
-Retrieve a generation
-
-`GET /generations/{generation_id}`
+`GET /publications`
 
 Safety: **read** · Authentication: **required**
 
-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 |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | — |
+| `--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 organization, 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. |
+| `--release-id` | query | `string` | no | Only publications of this release. |
 
 ```sh
-typeship generations retrieve gen_7h2p5d9c3m8w1k6q
+typeship publications list
 ```
 
-Output: the response payload as JSON on stdout. A successful response without a body produces `{"ok": true}`.
+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 generations retrieve --json`.
+Read the full command contract with `typeship docs publications list --json`.
 
-### `typeship generations retrieve-file <generation_id> [flags]`
+### `typeship publications get <publication_id> [flags]`
 
-Fetch one file from a generation
+Get publishing status
 
-`GET /generations/{generation_id}/file`
+`GET /publications/{publication_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns one file's raw content. Use a path from `files_index` when the Generation reports `files_omitted: true`.
+Returns the registry publishing status for a release. A status in another organization returns 404 not_found.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<generation_id>` | path | `string` | yes | — |
-| `--path` | query | `string` | yes | Repo-relative path inside the generated package. |
+| `<publication_id>` | path | `string` | yes | — |
 
 ```sh
-typeship generations retrieve-file gen_7h2p5d9c3m8w1k6q --path README.md
+typeship publications get 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 generations retrieve-file --json`.
+Read the full command contract with `typeship docs publications get --json`.
 
-## definitionRevisions
+## generations
 
-### `typeship definition-revisions list <definition_id> [flags]`
+### `typeship generations list [flags]`
 
-List Definition Revisions
+List generations
 
-`GET /definitions/{definition_id}/revisions`
+`GET /generations`
 
 Safety: **read** · Authentication: **required**
 
-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. 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. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, 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. |
+| `--project-id` | query | `string` | no | Only Generations in this Project. Accepts an ID or an exact name (resolved via projects_list). IDs come from projects_list. |
+| `--target-id` | query | `string` | no | Only Generations of this Target. Accepts an ID or an exact name (resolved via targets_list). IDs come from targets_list. |
+| `--status` | query | `string` | no | Only Generations with this status. |
 
 ```sh
-typeship definition-revisions list def_2p8m4q7k1v9d6h3c
+typeship generations list
 ```
 
 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 definition-revisions list --json`.
+Read the full command contract with `typeship docs generations list --json`.
 
-### `typeship definition-revisions retrieve <definition_revision_id> [flags]`
+### `typeship generations get <generation_id> [flags]`
 
-Retrieve a Definition Revision
+Get a generation
 
-`GET /definition-revisions/{definition_revision_id}`
+`GET /generations/{generation_id}`
 
 Safety: **read** · Authentication: **required**
 
-Returns metadata for a saved Definition Revision. Retrieve its resolved content or individual source documents separately.
+Returns the status of that Generation. `queued` and `running` mean generation is still in progress. `completed` means generated files are saved, not that repository delivery or a Draft is complete. List its files with listGenerationFiles and read each with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
+| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
 
 ```sh
-typeship definition-revisions retrieve drev_6m1q8v4k2p9d7h3c
+typeship generations get gen_7h2p5d9c3m8w1k6q
 ```
 
 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 --json`.
+Read the full command contract with `typeship docs generations get --json`.
 
-### `typeship definition-revisions retrieve-content <definition_revision_id> [flags]`
+### `typeship generations list-files <generation_id> [flags]`
 
-Retrieve a Definition Revision's canonical content
+List a Generation's files
 
-`GET /definition-revisions/{definition_revision_id}/content`
+`GET /generations/{generation_id}/files`
 
 Safety: **read** · Authentication: **required**
 
-Returns the saved, resolved content for this revision. Save it locally or compare it with another revision.
+Lists the generated package's files, ordered by path. Read content with getFile.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
+| `<generation_id>` | path | `string` | yes | Accepts an ID or an exact name (resolved via generations_list). IDs come from generations_list. |
+| `--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 organization, 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 retrieve-content drev_6m1q8v4k2p9d7h3c
+typeship generations list-files gen_7h2p5d9c3m8w1k6q
 ```
 
-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-content --json`.
-
-### `typeship definition-revisions retrieve-document-content <definition_revision_id> <document_id> [flags]`
-
-Retrieve one source document from a Definition Revision
-
-`GET /definition-revisions/{definition_revision_id}/documents/{document_id}/content`
-
-Safety: **read** · Authentication: **required**
-
-| Argument or flag | In | Type | Required | Description |
-| --- | --- | --- | --- | --- |
-| `<definition_revision_id>` | path | `string` | yes | — |
-| `<document_id>` | path | `string` | yes | — |
-
-```sh
-typeship definition-revisions retrieve-document-content drev_6m1q8v4k2p9d7h3c doc_8q2m5v1k9p4d7h3c
-```
+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.
 
-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 generations list-files --json`.
 
-Read the full command contract with `typeship docs definition-revisions retrieve-document-content --json`.
+## files
 
-### `typeship definition-revisions retrieve-document <definition_document_id> [flags]`
+### `typeship files get <file_id> [flags]`
 
-Retrieve a Definition Document
+Get a file
 
-`GET /definition-documents/{definition_document_id}`
+`GET /files/{file_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.
+Returns one bounded chunk of an immutable file: at most 24 KiB, as UTF-8 text or, for binary bytes, base64. When next_cursor is not null, repeat the request with cursor and concatenate the chunks in order. A file ID always returns the same bytes.
 
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
-| `<definition_document_id>` | path | `string` | yes | — |
+| `<file_id>` | path | `string` | yes | — |
+| `--cursor` | query | `string` | no | next_cursor from the preceding chunk of this file. |
 
 ```sh
-typeship definition-revisions retrieve-document doc_8q2m5v1k9p4d7h3c
+typeship files get file_4k8m2v7q1p9d5h6c
 ```
 
 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`.
+Read the full command contract with `typeship docs files get --json`.
 
-## account
+## organization
 
-### `typeship account retrieve [flags]`
+### `typeship organization get [flags]`
 
-The account behind the presented credentials
+The organization behind the presented credentials
 
-`GET /me`
+`GET /organization`
 
 Safety: **read** · Authentication: **required**
 
-Returns the account associated with your credential. The Typeship CLI uses this endpoint for `whoami`.
+Returns the organization associated with your credential. The Typeship CLI uses this endpoint for `whoami`.
 
 ```sh
-typeship account retrieve
+typeship organization get
 ```
 
 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 account retrieve --json`.
+Read the full command contract with `typeship docs organization get --json`.
 
 ## apiKeys
 
@@ -1078,7 +1012,7 @@ Lists key metadata and the last four characters of each key. Full keys are not r
 | Argument or flag | In | Type | Required | Description |
 | --- | --- | --- | --- | --- |
 | `--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. |
+| `--cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. Valid only for the same organization, 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
@@ -1088,9 +1022,9 @@ 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]`
+### `typeship api-keys get <api_key_id> [flags]`
 
-Retrieve an API key
+Get an API key
 
 `GET /api-keys/{api_key_id}`
 
@@ -1103,12 +1037,12 @@ Returns the key summary and its ETag for conditional revocation.
 | `<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
+typeship api-keys get 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`.
+Read the full command contract with `typeship docs api-keys get --json`.
 
 ### `typeship api-keys revoke <api_key_id> [flags]`
 
@@ -1120,7 +1054,7 @@ Safety: **destructive** · Authentication: **required**
 
 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.
+With OAuth, members can revoke their own keys; organization admins can revoke any key. Organization API keys can revoke any key in their organization.
 See [conditional writes](https://typeship.dev/docs/typeship-api#conditional-writes) for ETag and If-Match.
 
 | Argument or flag | In | Type | Required | Description |