@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/apps.md

@@ -0,0 +1,1342 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.apps`: Apps
+
+22 operations (8 read, 9 write, 4 destructive, 1 billable).
+
+14 of these also have a hand-written method (`g8.appPlatform`, `g8.apps`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [apps.d.ts](apps.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`applyAppManifest`](#op-applyappmanifest) | `POST /api/v1/apps/{app_id}/manifest` | write | `apps:write` | Apply App Manifest |
+| [`clearAppLimit`](#op-clearapplimit) | `DELETE /api/v1/apps/{app_id}/limit` | destructive | `apps:delete` | Clear App Limit |
+| [`clearAppSource`](#op-clearappsource) ★ | `DELETE /api/v1/apps/{app_id}/source` | destructive | `apps:delete` | Clear App Source |
+| [`createApp`](#op-createapp) ★ | `POST /api/v1/apps` | write | `apps:write` | Create App |
+| [`createAppCredential`](#op-createappcredential) | `POST /api/v1/apps/{app_id}/credentials` | write | `apps:write` | Create App Credential |
+| [`deleteAppSecret`](#op-deleteappsecret) ★ | `DELETE /api/v1/apps/{app_id}/secrets/{secret_key}` | destructive | `apps:delete` | Delete App Secret |
+| [`getApp`](#op-getapp) ★ | `GET /api/v1/apps/{app_id}` | read | `apps:read` | Get App |
+| [`getAppLimit`](#op-getapplimit) ★ | `GET /api/v1/apps/{app_id}/limit` | read | `apps:read` | Get App Limit |
+| [`getAppRuntime`](#op-getappruntime) | `GET /api/v1/apps/{app_id}/runtime` | billable | `apps:run` | Get App Runtime |
+| [`getAppUsage`](#op-getappusage) ★ | `GET /api/v1/apps/{app_id}/usage` | read | `apps:read` | Get App Usage |
+| [`listAppCredentials`](#op-listappcredentials) | `GET /api/v1/apps/{app_id}/credentials` | read | `apps:read` | List App Credentials |
+| [`listAppInstalls`](#op-listappinstalls) ★ | `GET /api/v1/apps/{app_id}/installs` | read | `apps:read` | List App Installs |
+| [`listAppSchemaVersions`](#op-listappschemaversions) ★ | `GET /api/v1/apps/{app_id}/schema-versions` | read | `apps:read` | List App Schema Versions |
+| [`listAppSecrets`](#op-listappsecrets) ★ | `GET /api/v1/apps/{app_id}/secrets` | read | `apps:read` | List App Secrets |
+| [`listApps`](#op-listapps) ★ | `GET /api/v1/apps` | read | `apps:read` | List Apps |
+| [`publishAppSchemaVersion`](#op-publishappschemaversion) ★ | `POST /api/v1/apps/{app_id}/schema-versions` | write | `apps:write` | Publish App Schema Version |
+| [`putAppSecret`](#op-putappsecret) ★ | `PUT /api/v1/apps/{app_id}/secrets/{secret_key}` | write | `apps:write` | Put App Secret |
+| [`revokeAppCredential`](#op-revokeappcredential) | `DELETE /api/v1/apps/{app_id}/credentials/{client_id}` | destructive | `apps:delete` | Revoke App Credential |
+| [`setAppLimit`](#op-setapplimit) | `PUT /api/v1/apps/{app_id}/limit` | write | `apps:write` | Set App Limit |
+| [`setAppSource`](#op-setappsource) ★ | `PUT /api/v1/apps/{app_id}/source` | write | `apps:write` | Set App Source |
+| [`setAppStatus`](#op-setappstatus) ★ | `POST /api/v1/apps/{app_id}/status` | write | `apps:write` | Set App Status |
+| [`validateAppManifest`](#op-validateappmanifest) | `POST /api/v1/apps/manifest/validate` | write | `apps:write` | Validate App Manifest |
+
+---
+
+<a id="op-applyappmanifest"></a>
+
+### `g8.api.apps.applyAppManifest(input)`
+
+**Apply App Manifest**
+
+- HTTP: `POST /api/v1/apps/{app_id}/manifest`
+- operationId: `apply_app_manifest_apps__app_id__manifest_post` (also callable as `g8.api.call("apply_app_manifest_apps__app_id__manifest_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Apply a `graph8.app.yaml` to this app.
+
+Publishes the `objects:` block as a schema version through the same path
+`POST /{app_id}/schema-versions` uses, including the digest idempotency and
+the failure-isolated tenant fan-out, and stores `frontend:` / `backend:` as
+the build config a later deploy reads.
+
+Refuses when the manifest's `app.slug` names a DIFFERENT app than the one in
+the path. Both halves of that mismatch are plausible mistakes -- a copied
+file, a wrong id in a script -- and either one silently applied would
+publish one app's schema into another app's tenants.
+
+A manifest with no `objects:` publishes nothing. That is not an oversight:
+an empty schema would archive every object the app has ever declared across
+every consented tenant, so `schema_publish` refuses it, and a build-config
+only manifest is a legitimate thing to apply.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `ManifestRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`ManifestRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.manifest` | `string` | yes | The full graph8.app.yaml document as text. Sent verbatim, including newlines. Rejected above 256 KiB by the parser. |
+
+**Returns** `ApiResponse_ApplyManifestResponse_`: the envelope `{ data: ApplyManifestResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ApplyManifestResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `summary` | `ManifestSummary` | yes |  |
+| `deploy_config_stored` | `boolean` | no | default `false` |
+| `materialization` | `MaterializationSummary \| null` | no |  |
+| `schema_created` | `boolean` | no | False when an identical schema was already published. The version named above exists either way; this is what says nothing changed. default `false` |
+| `schema_version` | `SchemaVersionResponse \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.applyAppManifest({ path: { app_id: "id" }, body: { manifest: "example" } });
+```
+
+---
+
+<a id="op-clearapplimit"></a>
+
+### `g8.api.apps.clearAppLimit(input)`
+
+**Clear App Limit**
+
+- HTTP: `DELETE /api/v1/apps/{app_id}/limit`
+- operationId: `clear_app_limit_apps__app_id__limit_delete` (also callable as `g8.api.call("clear_app_limit_apps__app_id__limit_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Remove every window's cap for this app, returning it to uncapped.
+
+A DELETE rather than `PUT {"credit_cap": 0}`, because absence of a row IS
+"no cap" (`contracts.py:655`) and zero is a real cap meaning "allow nothing".
+Collapsing the two would make an accidental zero indistinguishable from
+uncapped, in the one place where guessing wrong costs money.
+
+Idempotent: clearing an app that has no cap succeeds.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_NoneType_`: the envelope `{ data: null, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.apps.clearAppLimit({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-clearappsource"></a>
+
+### `g8.api.apps.clearAppSource(input)`
+
+**Clear App Source**
+
+- HTTP: `DELETE /api/v1/apps/{app_id}/source`
+- operationId: `clear_app_source_apps__app_id__source_delete` (also callable as `g8.api.call("clear_app_source_apps__app_id__source_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- ★ Hand-written: [`g8.appPlatform.clearSource()`](../sdk-clients.md#g8-appplatform-clearsource)
+
+Unbind this app's source.
+
+Idempotent: unbinding an app that has no source is a 200 describing an app
+with no source, not a 404. The caller asked for a state, and that state
+already holds.
+
+Clearing the binding does NOT touch deployments already built from it. A
+deployment records what was built; rewriting history to match a since-removed
+binding would make the audit trail lie about what is running.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AppResponse_`: the envelope `{ data: AppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.apps.clearAppSource({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-createapp"></a>
+
+### `g8.api.apps.createApp(input)`
+
+**Create App**
+
+- HTTP: `POST /api/v1/apps`
+- operationId: `create_app_apps_post` (also callable as `g8.api.call("create_app_apps_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.create()`](../sdk-clients.md#g8-apps-create)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Create an app. It starts in `draft` and serves no traffic until published.
+
+The slug is unique within your organization, not globally — two builders may
+both ship a `crm`. A collision returns 409 naming `slug`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateAppRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`CreateAppRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | min length 1, max length 200 |
+| `body.slug` | `string` | yes | Stable identifier, unique within your organization. Lowercased on write, so `CRM` and `crm` are the same app. min length 1, max length 100, pattern `^[a-zA-Z0-9][a-zA-Z0-9_-]*$` |
+| `body.registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. An http origin is rejected — a bearer token sent over http is a token disclosed to the network. max items 20 |
+
+**Returns** `ApiResponse_AppResponse_`: the envelope `{ data: AppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.createApp({ body: { name: "Example", slug: "example" } });
+```
+
+---
+
+<a id="op-createappcredential"></a>
+
+### `g8.api.apps.createAppCredential(input)`
+
+**Create App Credential**
+
+- HTTP: `POST /api/v1/apps/{app_id}/credentials`
+- operationId: `create_app_credential_apps__app_id__credentials_post` (also callable as `g8.api.call("create_app_credential_apps__app_id__credentials_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Create a service credential for one consented client organization.
+
+**The secret is returned once and never again.** Only its SHA-256 is stored —
+`developer_app_credentials` has no column that could hold a plaintext secret.
+Rotate by creating a new credential and revoking the old one.
+
+The target organization must already have a **consented** installation of
+this app. A credential for a workspace that never consented would be a
+standing key into a tenant that never agreed to it, and the M6-1d clamp would
+refuse every request it minted anyway — failing here says why, instead of
+leaving a credential that silently cannot work.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `CreateCredentialRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`CreateCredentialRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.client_org_id` | `string` | yes | The client organization this credential acts for. It must already have a consented installation of the app — a credential is bound to one tenant and cannot be pointed at another later. |
+
+**Returns** `ApiResponse_CreatedCredentialResponse_`: the envelope `{ data: CreatedCredentialResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CreatedCredentialResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `client_secret` | `string` | yes | Shown ONCE. Store it now — only its hash is kept, so it cannot be retrieved again. Rotate by creating a new credential and revoking this one. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.createAppCredential({ path: { app_id: "id" }, body: { client_org_id: "id" } });
+```
+
+---
+
+<a id="op-deleteappsecret"></a>
+
+### `g8.api.apps.deleteAppSecret(input)`
+
+**Delete App Secret**
+
+- HTTP: `DELETE /api/v1/apps/{app_id}/secrets/{secret_key}`
+- operationId: `delete_app_secret_apps__app_id__secrets__secret_key__delete` (also callable as `g8.api.call("delete_app_secret_apps__app_id__secrets__secret_key__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- ★ Hand-written: [`g8.appPlatform.deleteSecret()`](../sdk-clients.md#g8-appplatform-deletesecret)
+
+Stop declaring a secret.
+
+Removes the DECLARATION, not the value: the value lives in the secret manager
+and this surface never had it to delete. A builder revoking a credential has
+to do it there as well, which the description says so nobody assumes this call
+was enough.
+
+404 when the app declares no such key, so a typo is not reported as a
+successful removal of something else.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.secret_key` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.apps.deleteAppSecret({ path: { app_id: "id", secret_key: "example" } });
+```
+
+---
+
+<a id="op-getapp"></a>
+
+### `g8.api.apps.getApp(input)`
+
+**Get App**
+
+- HTTP: `GET /api/v1/apps/{app_id}`
+- operationId: `get_app_apps__app_id__get` (also callable as `g8.api.call("get_app_apps__app_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.get()`](../sdk-clients.md#g8-apps-get)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Fetch one of your apps by id.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AppResponse_`: the envelope `{ data: AppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.getApp({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-getapplimit"></a>
+
+### `g8.api.apps.getAppLimit(input)`
+
+**Get App Limit**
+
+- HTTP: `GET /api/v1/apps/{app_id}/limit`
+- operationId: `get_app_limit_apps__app_id__limit_get` (also callable as `g8.api.call("get_app_limit_apps__app_id__limit_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.getLimit()`](../sdk-clients.md#g8-apps-getlimit)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+This app's hard credit cap, or `null` when it is uncapped.
+
+`null` is the real answer, not an empty object: absence of a limit row IS
+"no cap", and there is no unlimited sentinel — so an accidental zero can
+never read as no limit.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_Union_AppLimitResponse__NoneType__`: the envelope `{ data: AppLimitResponse | null, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`data` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `credit_cap` | `integer` | yes |  |
+| `window` | `string` | yes | Cap window. `calendar_month` today. |
+| `created_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.getAppLimit({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-getappruntime"></a>
+
+### `g8.api.apps.getAppRuntime(input)`
+
+**Get App Runtime**
+
+- HTTP: `GET /api/v1/apps/{app_id}/runtime`
+- operationId: `get_app_runtime_apps__app_id__runtime_get` (also callable as `g8.api.call("get_app_runtime_apps__app_id__runtime_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `apps:run`
+
+Can this app be built and run yet, and if not, what is missing (M9 J9).
+
+ANSWERS FROM THE CONTROL PLANE, AND SAYS SO. It reports what graph8 has
+recorded: a bound source, an assigned hostname, declared secrets, the last
+deployment's state. It does NOT claim the cluster side is ready, because the
+namespace provisioner, the image registry and the runtime objects are
+separate, unbuilt work. Reporting `ready: true` on that basis would be the
+most expensive kind of wrong: a builder would push and wait for something
+nothing can serve.
+
+`blockers` is the field that matters. An agent driving a build needs to know
+WHY it cannot proceed; a bare `ready: false` sends it guessing, and guessing
+against a deploy pipeline is how you get retry loops.
+
+Deliberately cheap: three reads the caller could make themselves across
+`GET /apps/{id}`, `/secrets` and `/deployments`. It exists so the answer is
+computed in one place, because "am I ready" is a judgement about which
+prerequisites matter, and three clients would each get it slightly wrong.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AppRuntimeResponse_`: the envelope `{ data: AppRuntimeResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppRuntimeResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `hostname_assigned` | `boolean` | yes |  |
+| `ready` | `boolean` | yes | True only when nothing in `blockers` remains. False is the normal answer today. |
+| `secrets_declared` | `integer` | yes |  |
+| `source_bound` | `boolean` | yes |  |
+| `blockers` | `Array<string>` | no | Each unmet prerequisite, named. Empty means ready. |
+| `latest_deployment_status` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.apps.getAppRuntime({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-getappusage"></a>
+
+### `g8.api.apps.getAppUsage(input)`
+
+**Get App Usage**
+
+- HTTP: `GET /api/v1/apps/{app_id}/usage`
+- operationId: `get_app_usage_apps__app_id__usage_get` (also callable as `g8.api.call("get_app_usage_apps__app_id__usage_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.usage()`](../sdk-clients.md#g8-apps-usage)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Credits this app consumed in a calendar month, broken down per client org.
+
+The breakdown keys on the client whose DATA was touched, not on who paid —
+the builder pays for all of them. A month with no usage returns zeroes rather
+than 404: "nothing happened" is an answer, and a 404 would read as "no such
+app".
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `query.period` | `string \| null` | no | Calendar month `YYYY-MM`. Defaults to the current month. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_UsageSummaryResponse_`: the envelope `{ data: UsageSummaryResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`UsageSummaryResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `event_count` | `integer` | yes |  |
+| `period` | `string` | yes | Calendar month, `YYYY-MM`. |
+| `total_credits` | `integer` | yes |  |
+| `discount_credits` | `integer` | no | Everything deducted from list: the builder discount AND any hard-cap clamp. One compound number, not 'the 25%'. default `0` |
+| `gross_credits` | `integer` | no | Undiscounted list total for the period. `gross_credits - discount_credits == total_credits`. default `0` |
+| `per_client_credits` | `Record<string, integer>` | no | Credits per CLIENT org — whose data was touched, not who paid. The builder pays for all of them. |
+| `per_operation_credits` | `Record<string, integer>` | no | Net credits per operation id, so you can see which calls cost money. |
+| `per_payer_credits` | `Record<string, integer>` | no | Net credits per BILLING org, who pays. The mirror of `per_client_credits`, which is whose data was touched. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.getAppUsage({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listappcredentials"></a>
+
+### `g8.api.apps.listAppCredentials(input)`
+
+**List App Credentials**
+
+- HTTP: `GET /api/v1/apps/{app_id}/credentials`
+- operationId: `list_app_credentials_apps__app_id__credentials_get` (also callable as `g8.api.call("list_app_credentials_apps__app_id__credentials_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List this app's service credentials. Never returns a secret.
+
+Includes revoked ones: a builder auditing which credentials exist needs to
+see the one they turned off, and hiding it would make a rotation look like a
+deletion.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_CredentialResponse__`: the envelope `{ data: Array<CredentialResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CredentialResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.listAppCredentials({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listappinstalls"></a>
+
+### `g8.api.apps.listAppInstalls(input)`
+
+**List App Installs**
+
+- HTTP: `GET /api/v1/apps/{app_id}/installs`
+- operationId: `list_app_installs_apps__app_id__installs_get` (also callable as `g8.api.call("list_app_installs_apps__app_id__installs_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.listInstalls()`](../sdk-clients.md#g8-apps-listinstalls)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List the client organizations that installed this app, and their consent state.
+
+Includes revoked and pending installs, not only consented ones — a builder
+debugging "why can't my app reach this tenant" needs to see the revocation,
+and hiding it turns a clear answer into a mystery.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_InstallationResponse__`: the envelope `{ data: Array<InstallationResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InstallationResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `install_id` | `string` | yes |  |
+| `status` | `string` | yes | `pending`, `consented`, `revoked`, `suspended` or `expired`. |
+| `consented_scopes` | `Array<string>` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.listAppInstalls({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listappschemaversions"></a>
+
+### `g8.api.apps.listAppSchemaVersions(input)`
+
+**List App Schema Versions**
+
+- HTTP: `GET /api/v1/apps/{app_id}/schema-versions`
+- operationId: `list_app_schema_versions_apps__app_id__schema_versions_get` (also callable as `g8.api.call("list_app_schema_versions_apps__app_id__schema_versions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.listSchemaVersions()`](../sdk-clients.md#g8-appplatform-listschemaversions)
+
+Every schema version for this app, oldest ordinal first.
+
+Includes drafts and deprecated versions. A builder asking "what did I ship
+and when" needs the whole history, and a filtered list would make a
+deprecated version look deleted.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_SchemaVersionResponse__`: the envelope `{ data: Array<SchemaVersionResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SchemaVersionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `digest` | `string` | yes | SHA-256 of the canonical schema. Re-publishing the same schema resolves here. |
+| `schema_version_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `version` | `integer` | yes | Human-facing ordinal. Nothing keys on it; the digest is the identity. |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `deprecated_at` | `string (date-time) \| null` | no |  |
+| `manifest` | `Record<string, unknown>` | no | The stored canonical schema. Self-describing, so the version needs no other source. |
+| `published_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.listAppSchemaVersions({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listappsecrets"></a>
+
+### `g8.api.apps.listAppSecrets(input)`
+
+**List App Secrets**
+
+- HTTP: `GET /api/v1/apps/{app_id}/secrets`
+- operationId: `list_app_secrets_apps__app_id__secrets_get` (also callable as `g8.api.call("list_app_secrets_apps__app_id__secrets_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- ★ Hand-written: [`g8.appPlatform.listSecrets()`](../sdk-clients.md#g8-appplatform-listsecrets)
+
+Which secrets this app declares, and where they live (M9 item J7).
+
+POINTERS ONLY. There is no value in the response and no column that could
+hold one: the platform stores which secrets an app declares so a build can be
+rendered, without ever holding what the build will read.
+
+A hosted app needs config -- its own API keys, a database URL, the graph8
+credential it calls back with -- and there was no route, DTO or operation id
+for any of it anywhere in the contract.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_AppSecretResponse__`: the envelope `{ data: Array<AppSecretResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppSecretResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `secret_key` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `provider_ref` | `string \| null` | no | Where the value lives, e.g. a secret-manager path. Never the value. |
+| `rotated_at` | `string (date-time) \| null` | no | Last time this declaration was rewritten. Moves on every write, including one that repeats the same pointer: the pointer is not the secret, so an unchanged path does not mean an unchanged value. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.listAppSecrets({ path: { app_id: "id" } });
+```
+
+---
+
+<a id="op-listapps"></a>
+
+### `g8.api.apps.listApps(input?)`
+
+**List Apps**
+
+- HTTP: `GET /api/v1/apps`
+- operationId: `list_apps_apps_get` (also callable as `g8.api.call("list_apps_apps_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `apps:read`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.list()`](../sdk-clients.md#g8-apps-list)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+List the apps your organization owns, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_list_AppResponse__`: the envelope `{ data: Array<AppResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.listApps();
+```
+
+---
+
+<a id="op-publishappschemaversion"></a>
+
+### `g8.api.apps.publishAppSchemaVersion(input)`
+
+**Publish App Schema Version**
+
+- HTTP: `POST /api/v1/apps/{app_id}/schema-versions`
+- operationId: `publish_app_schema_version_apps__app_id__schema_versions_post` (also callable as `g8.api.call("publish_app_schema_version_apps__app_id__schema_versions_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.publishSchemaVersion()`](../sdk-clients.md#g8-appplatform-publishschemaversion)
+
+Publish a declared object schema and materialize it across consented tenants.
+
+422 with every validation problem at once, so a builder fixes their whole
+schema in one round trip rather than one error per attempt.
+
+A publish that resolves to an EXISTING version still returns 201 with
+`created: false` -- the resource named by the response exists either way, and
+the flag is what tells a caller nothing changed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `PublishSchemaVersionRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`PublishSchemaVersionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.objects` | `Array<unknown>` | yes | Declared custom objects, in `graph8.app.yaml` `objects:` shape. |
+
+**Returns** `ApiResponse_PublishSchemaVersionResponse_`: the envelope `{ data: PublishSchemaVersionResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`PublishSchemaVersionResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created` | `boolean` | yes | False when an identical schema was already published -- the retry no-op. |
+| `materialization` | `MaterializationSummary` | yes |  |
+| `version` | `SchemaVersionResponse` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.publishAppSchemaVersion({ path: { app_id: "id" }, body: { objects: [{}] } });
+```
+
+---
+
+<a id="op-putappsecret"></a>
+
+### `g8.api.apps.putAppSecret(input)`
+
+**Put App Secret**
+
+- HTTP: `PUT /api/v1/apps/{app_id}/secrets/{secret_key}`
+- operationId: `put_app_secret_apps__app_id__secrets__secret_key__put` (also callable as `g8.api.call("put_app_secret_apps__app_id__secrets__secret_key__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.putSecret()`](../sdk-clients.md#g8-appplatform-putsecret)
+
+Declare a secret, or rotate where an existing one lives.
+
+UPSERT, not create. Re-declaring a key is a rotation rather than a 409: the
+builder is saying the value moved, and refusing would make the common case an
+error and push them towards delete-then-create, which loses `created_at` and
+briefly leaves the app declaring nothing.
+
+`provider_ref` is a POINTER. The DTO refuses the obvious credential shapes,
+which is a guardrail against the honest mistake rather than a security
+control: nothing can reliably tell a path from a secret, but someone pasting a
+value because the field sits next to the key is the likely error, and this
+turns a silent unrecoverable leak into a 422 they read.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.secret_key` | `string` | yes |  |
+| `body` | `PutAppSecretRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`PutAppSecretRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.provider_ref` | `string \| null` | no | Secret-manager PATH for the value. Never the value itself. max length 500 |
+
+**Returns** `ApiResponse_AppSecretResponse_`: the envelope `{ data: AppSecretResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppSecretResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `secret_key` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `provider_ref` | `string \| null` | no | Where the value lives, e.g. a secret-manager path. Never the value. |
+| `rotated_at` | `string (date-time) \| null` | no | Last time this declaration was rewritten. Moves on every write, including one that repeats the same pointer: the pointer is not the secret, so an unchanged path does not mean an unchanged value. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.putAppSecret({ path: { app_id: "id", secret_key: "example" }, body: {} });
+```
+
+---
+
+<a id="op-revokeappcredential"></a>
+
+### `g8.api.apps.revokeAppCredential(input)`
+
+**Revoke App Credential**
+
+- HTTP: `DELETE /api/v1/apps/{app_id}/credentials/{client_id}`
+- operationId: `revoke_app_credential_apps__app_id__credentials__client_id__delete` (also callable as `g8.api.call("revoke_app_credential_apps__app_id__credentials__client_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `apps:delete`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Revoke a service credential. A status flip, never a delete.
+
+Deleting would erase the evidence that the credential ever existed, which is
+precisely what an incident review needs. Tokens already minted from it are
+NOT retroactively invalid — they expire on their own short TTL — but no new
+one can be minted.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `path.client_id` | `string` | yes |  |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_CredentialResponse_`: the envelope `{ data: CredentialResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CredentialResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `client_id` | `string` | yes |  |
+| `client_org_id` | `string` | yes |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `revoked` | `boolean` | no | default `false` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.apps.revokeAppCredential({ path: { app_id: "id", client_id: "id" } });
+```
+
+---
+
+<a id="op-setapplimit"></a>
+
+### `g8.api.apps.setAppLimit(input)`
+
+**Set App Limit**
+
+- HTTP: `PUT /api/v1/apps/{app_id}/limit`
+- operationId: `set_app_limit_apps__app_id__limit_put` (also callable as `g8.api.call("set_app_limit_apps__app_id__limit_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Set this app's hard credit cap for a window.
+
+`set_limit` and `clear_limit` shipped with the repository layer
+(`repositories/usage.py:198,229`), with a Protocol (`contracts.py:957`) and
+tests, and NO route ever called them. So a builder could read their cap and
+could never set one, and the only way a limit row came into existence was by
+hand.
+
+That matters more than a missing endpoint usually would: in a builder-pays
+model the cap is the entire spend-safety story. Enforcement was complete and
+unreachable.
+
+Same shape as the #16816 bug, where `store_credential` and `revoke_credential`
+shipped without callers so no service token could ever be minted.
+
+SINGULAR `/limit`, not `/limits`. The read half is singular and is frozen
+that way in `openapi_operation_ids.json` and the published bundle; adding a
+plural verb would put two spellings of one resource in the public contract
+forever.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `SetAppLimitRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`SetAppLimitRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.credit_cap` | `integer` | yes | Hard cap in credits for the window. `0` means 'cap at zero', NOT 'uncapped' -- to remove a cap, DELETE the limit instead. min 0 |
+| `body.window` | `string` | no | Cap window. `calendar_month` is the only value today. default `"calendar_month"` |
+
+**Returns** `ApiResponse_AppLimitResponse_`: the envelope `{ data: AppLimitResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppLimitResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `credit_cap` | `integer` | yes |  |
+| `window` | `string` | yes | Cap window. `calendar_month` today. |
+| `created_at` | `string (date-time) \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.setAppLimit({ path: { app_id: "id" }, body: { credit_cap: 0 } });
+```
+
+---
+
+<a id="op-setappsource"></a>
+
+### `g8.api.apps.setAppSource(input)`
+
+**Set App Source**
+
+- HTTP: `PUT /api/v1/apps/{app_id}/source`
+- operationId: `set_app_source_apps__app_id__source_put` (also callable as `g8.api.call("set_app_source_apps__app_id__source_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- ★ Hand-written: [`g8.appPlatform.setSource()`](../sdk-clients.md#g8-appplatform-setsource)
+
+Bind this app to the repository a build should fetch (J1).
+
+Idempotent, and a REPLACE rather than a merge: every field is written, so
+rebinding from one provider to another cannot leave the previous provider's
+credential pointer behind. A build fetching a new repo with a stale
+credential is the failure this shape exists to prevent.
+
+There is no GET here on purpose. Source is 1:1 with the app and comes back on
+`GET /apps/{app_id}` through `AppResponse`, so a separate read would be a
+second thing to keep in step for no new information.
+
+`credential_ref` is a POINTER to a secret, never a secret. The DTO says so and
+the column comment says so, because a token written here would also live in
+every backup of the control plane and in this route's own response.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `AppSourceRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`AppSourceRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.provider` | `string` | yes | One of: github, gitlab, bitbucket. |
+| `body.repo_url` | `string` | yes | Clone URL. min length 1, max length 2000 |
+| `body.credential_ref` | `string \| null` | no | Secret-manager PATH for the fetch credential. Never the credential itself. max length 500 |
+| `body.default_branch` | `string \| null` | no | Defaults to the repository's own default when omitted. max length 255 |
+
+**Returns** `ApiResponse_AppResponse_`: the envelope `{ data: AppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.setAppSource({
+  path: { app_id: "id" },
+  body: { provider: "example", repo_url: "https://example.com" },
+});
+```
+
+---
+
+<a id="op-setappstatus"></a>
+
+### `g8.api.apps.setAppStatus(input)`
+
+**Set App Status**
+
+- HTTP: `POST /api/v1/apps/{app_id}/status`
+- operationId: `set_app_status_apps__app_id__status_post` (also callable as `g8.api.call("set_app_status_apps__app_id__status_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+- Lifecycle: `preview` (may not be enabled for every org yet)
+- ★ Hand-written: [`g8.apps.setStatus()`](../sdk-clients.md#g8-apps-setstatus)
+
+PREVIEW. This endpoint is deployed but gated: it returns 404 unless the hosted app platform is enabled for your organization. It is published here so the contract describes the whole surface, not so it can be called today.
+
+Move an app through its lifecycle: `draft` → `published` → `archived`.
+
+`suspended` is the platform's kill switch and is NOT settable here — a builder
+suspending and un-suspending their own app would defeat it entirely.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.app_id` | `string` | yes |  |
+| `body` | `SetAppStatusRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`SetAppStatusRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `string` | yes | `draft`, `published`, `suspended` or `archived`. `active` is accepted as the legacy spelling of `published`. |
+
+**Returns** `ApiResponse_AppResponse_`: the envelope `{ data: AppResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AppResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `app_id` | `string` | yes |  |
+| `builder_org_id` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `slug` | `string` | yes |  |
+| `status` | `string` | yes | Lifecycle state: `draft`, `published`, `suspended` or `archived`. `active` is accepted on write as a legacy spelling of `published`. |
+| `archived_at` | `string (date-time) \| null` | no |  |
+| `created_at` | `string (date-time) \| null` | no |  |
+| `default_hostname` | `string \| null` | no |  |
+| `registered_origins` | `Array<string>` | no | https-only origins a browser app token may be presented from. |
+| `source_credential_ref` | `string \| null` | no | A POINTER to the credential (a secret-manager path), never the credential itself. |
+| `source_default_branch` | `string \| null` | no |  |
+| `source_provider` | `string \| null` | no |  |
+| `source_repo_url` | `string \| null` | no | Where this app's code lives. Null until bound. |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.setAppStatus({ path: { app_id: "id" }, body: { status: "example" } });
+```
+
+---
+
+<a id="op-validateappmanifest"></a>
+
+### `g8.api.apps.validateAppManifest(input)`
+
+**Validate App Manifest**
+
+- HTTP: `POST /api/v1/apps/manifest/validate`
+- operationId: `validate_app_manifest_apps_manifest_validate_post` (also callable as `g8.api.call("validate_app_manifest_apps_manifest_validate_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `apps:write`
+
+Validate a `graph8.app.yaml` without applying it. No app id needed.
+
+Answers 200 whether or not the manifest is valid: the question "is this
+valid" was served correctly even when the answer is no, and a 422 would make
+a builder's linter treat a working call as a transport failure. `valid` is
+the answer; `issues` carries every problem at once, each with a path pointer,
+so a whole file is fixed in one round trip.
+
+Requires an allowlisted builder org but no app, because linting a manifest
+in CI should not require naming an app or holding a credential scoped to one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ManifestRequest` | yes | Request body; fields below. |
+| `headers.X-Org-Id` | `string \| null` | no |  |
+
+Body fields (`ManifestRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.manifest` | `string` | yes | The full graph8.app.yaml document as text. Sent verbatim, including newlines. Rejected above 256 KiB by the parser. |
+
+**Returns** `ApiResponse_ValidateManifestResponse_`: the envelope `{ data: ValidateManifestResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ValidateManifestResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `valid` | `boolean` | yes |  |
+| `issues` | `Array<ManifestIssueResponse>` | no |  |
+| `summary` | `ManifestSummary \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.apps.validateAppManifest({ body: { manifest: "example" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-manifestissueresponse"></a>
+
+### `ManifestIssueResponse`
+
+One validation problem, addressed to a line a builder can fix.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `code` | `string` | yes | Machine-readable cause. Stable; safe to branch on. |
+| `message` | `string` | yes |  |
+| `path` | `string` | yes | Pointer into the document, e.g. objects[0].attributes[1].type |
+
+<a id="type-manifestsummary"></a>
+
+### `ManifestSummary`
+
+What a valid manifest declares. The echo of a successful parse. Deliberately a summary and not the parsed document: a builder who wants the document already has it, and echoing it back would make this response the second place the shape is defined.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `version` | `integer` | yes |  |
+| `app_name` | `string \| null` | no |  |
+| `app_slug` | `string \| null` | no |  |
+| `attribute_count` | `integer` | no | default `0` |
+| `has_backend` | `boolean` | no | default `false` |
+| `has_frontend` | `boolean` | no | default `false` |
+| `object_slugs` | `Array<string>` | no |  |
+
+<a id="type-materializationsummary"></a>
+
+### `MaterializationSummary`
+
+How the fan-out went, as counts. Never tenant ids -- see module docstring.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `failed` | `integer` | no | default `0` |
+| `ready` | `integer` | no | default `0` |
+| `skipped` | `integer` | no | Tenants already materialized on this exact digest. default `0` |
+| `total` | `integer` | no | default `0` |