@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/desk.md

@@ -0,0 +1,3007 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.desk`: Desk
+
+71 operations (38 read, 15 write, 10 billable, 8 external).
+
+No hand-written client covers this area. Call it through `g8.api.desk.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+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: [desk.d.ts](desk.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`applyAccountPlan`](#op-applyaccountplan) | `POST /api/v1/desk/accounts/{account_id}/plan/apply` | write | `deals:write` | Apply Account Plan |
+| [`askDesk`](#op-askdesk) | `POST /api/v1/desk/ask` | billable | `deals:run` | Ask Desk |
+| [`checkCommitteePlay`](#op-checkcommitteeplay) | `GET /api/v1/desk/accounts/{account_id}/committee/plays/{action_id}/check` | read | `deals:read` | Check Committee Play |
+| [`checkDeskPlanStageSweep`](#op-checkdeskplanstagesweep) | `GET /api/v1/desk/org-settings/plan-stages/check` | read | `deals:read` | Check Desk Plan Stage Sweep |
+| [`createOrReplanAccountPlan`](#op-createorreplanaccountplan) | `POST /api/v1/desk/accounts/{account_id}/plan` | write | `deals:write` | Create Or Replan Account Plan |
+| [`decideDeskPlayApproval`](#op-decidedeskplayapproval) | `POST /api/v1/desk/plays/approvals/{execution_id}/decide` | external | `deals:run` | Decide Desk Play Approval |
+| [`draftAccountPlan`](#op-draftaccountplan) | `POST /api/v1/desk/accounts/{account_id}/plan/draft` | billable | `deals:run` | Draft Account Plan |
+| [`editAccountCommittee`](#op-editaccountcommittee) | `POST /api/v1/desk/accounts/{account_id}/committee` | write | `deals:write` | Edit Account Committee |
+| [`findCommitteeMemberLinkedin`](#op-findcommitteememberlinkedin) | `POST /api/v1/desk/accounts/{account_id}/committee/{contact_id}/find-linkedin` | billable | `deals:run` | Find Committee Member Linkedin |
+| [`getAccountContext`](#op-getaccountcontext) | `GET /api/v1/desk/accounts/{account_id}/context` | read | `deals:read` | Get Account Context |
+| [`getAccountPlan`](#op-getaccountplan) | `GET /api/v1/desk/accounts/{account_id}/plan` | read | `deals:read` | Get Account Plan |
+| [`getAccountPlanHistory`](#op-getaccountplanhistory) | `GET /api/v1/desk/accounts/{account_id}/plan/history` | read | `deals:read` | Get Account Plan History |
+| [`getDeskAutonomy`](#op-getdeskautonomy) | `GET /api/v1/desk/autonomy` | read | `deals:read` | Get Desk Autonomy |
+| [`getDeskBatch`](#op-getdeskbatch) | `GET /api/v1/desk/batch` | read | `deals:read` | Get Desk Batch |
+| [`getDeskBlockQueue`](#op-getdeskblockqueue) | `GET /api/v1/desk/blocks/{list_id}/queue` | read | `deals:read` | Get Desk Block Queue |
+| [`getDeskCallTarget`](#op-getdeskcalltarget) | `POST /api/v1/desk/decisions/{decision_id}/call-target` | read | `deals:read` | Get Desk Call Target |
+| [`getDeskCommitteeHeat`](#op-getdeskcommitteeheat) | `GET /api/v1/desk/committee-heat` | read | `deals:read` | Get Desk Committee Heat |
+| [`getDeskCommitteeTargets`](#op-getdeskcommitteetargets) | `GET /api/v1/desk/committee-targets` | read | `deals:read` | Get Desk Committee Targets |
+| [`getDeskComplianceSummary`](#op-getdeskcompliancesummary) | `GET /api/v1/desk/compliance-summary` | read | `deals:read` | Get Desk Compliance Summary |
+| [`getDeskContactCallTarget`](#op-getdeskcontactcalltarget) | `POST /api/v1/desk/contacts/{contact_id}/call-target` | read | `deals:read` | Get Desk Contact Call Target |
+| [`getDeskCoverage`](#op-getdeskcoverage) | `GET /api/v1/desk/coverage` | read | `deals:read` | Get Desk Coverage |
+| [`getDeskDecisionBrief`](#op-getdeskdecisionbrief) | `GET /api/v1/desk/decisions/{decision_id}/brief` | read | `deals:read` | Get Desk Decision Brief |
+| [`getDeskDecisionCardContext`](#op-getdeskdecisioncardcontext) | `GET /api/v1/desk/decisions/{decision_id}/card-context` | read | `deals:read` | Get Desk Decision Card Context |
+| [`getDeskDecisionConversation`](#op-getdeskdecisionconversation) | `GET /api/v1/desk/decisions/{decision_id}/conversation` | read | `deals:read` | Get Desk Decision Conversation |
+| [`getDeskHomeSummary`](#op-getdeskhomesummary) | `GET /api/v1/desk/home-summary` | read | `deals:read` | Get Desk Home Summary |
+| [`getDeskKickoff`](#op-getdeskkickoff) | `GET /api/v1/desk/kickoff` | billable | `deals:run` | Get Desk Kickoff |
+| [`getDeskKickoffAudio`](#op-getdeskkickoffaudio) | `GET /api/v1/desk/kickoff/audio` | billable | `deals:run` | Get Desk Kickoff Audio |
+| [`getDeskLinkedinSender`](#op-getdesklinkedinsender) | `GET /api/v1/desk/linkedin-sender` | read | `deals:read` | Get Desk Linkedin Sender |
+| [`getDeskListGoals`](#op-getdesklistgoals) | `GET /api/v1/desk/list-goals` | read | `deals:read` | Get Desk List Goals |
+| [`getDeskListGroupOverride`](#op-getdesklistgroupoverride) | `GET /api/v1/desk/list-group-override` | read | `deals:read` | Get Desk List Group Override |
+| [`getDeskListPriority`](#op-getdesklistpriority) | `GET /api/v1/desk/list-priority` | read | `deals:read` | Get Desk List Priority |
+| [`getDeskNextBest`](#op-getdesknextbest) | `GET /api/v1/desk/next-best` | read | `deals:read` | Get Desk Next Best |
+| [`getDeskOrgSettings`](#op-getdeskorgsettings) | `GET /api/v1/desk/org-settings` | read | `deals:read` | Get Desk Org Settings |
+| [`getDeskPlayExecution`](#op-getdeskplayexecution) | `GET /api/v1/desk/plays/executions/{execution_id}` | read | `deals:read` | Get Desk Play Execution |
+| [`getDeskPulse`](#op-getdeskpulse) | `GET /api/v1/desk/pulse` | read | `deals:read` | Get Desk Pulse |
+| [`getDeskReplyTarget`](#op-getdeskreplytarget) | `POST /api/v1/desk/decisions/{decision_id}/reply-target` | read | `deals:read` | Get Desk Reply Target |
+| [`getDeskSmsTarget`](#op-getdesksmstarget) | `POST /api/v1/desk/decisions/{decision_id}/sms-target` | read | `deals:read` | Get Desk Sms Target |
+| [`getDeskWrapped`](#op-getdeskwrapped) | `GET /api/v1/desk/wrapped` | read | `deals:read` | Get Desk Wrapped |
+| [`improveDeskEmail`](#op-improvedeskemail) | `POST /api/v1/desk/email-improve` | billable | `deals:run` | Improve Desk Email |
+| [`listAccountPlans`](#op-listaccountplans) | `GET /api/v1/desk/accounts/plans` | read | `deals:read` | List Account Plans |
+| [`listCommitteePlays`](#op-listcommitteeplays) | `GET /api/v1/desk/accounts/{account_id}/committee/plays` | read | `deals:read` | List Committee Plays |
+| [`listCompletedDeskDecisions`](#op-listcompleteddeskdecisions) | `GET /api/v1/desk/decisions/completed` | read | `deals:read` | List Completed Desk Decisions |
+| [`listDeskBlocks`](#op-listdeskblocks) | `GET /api/v1/desk/blocks` | read | `deals:read` | List Desk Blocks |
+| [`listDeskCardPlays`](#op-listdeskcardplays) | `GET /api/v1/desk/decisions/{decision_id}/plays` | read | `deals:read` | List Desk Card Plays |
+| [`listDeskDecisions`](#op-listdeskdecisions) | `GET /api/v1/desk/decisions` | read | `deals:read` | List Desk Decisions |
+| [`listDeskPlayApprovals`](#op-listdeskplayapprovals) | `GET /api/v1/desk/plays/approvals` | read | `deals:read` | List Desk Play Approvals |
+| [`listDeskUpcoming`](#op-listdeskupcoming) | `GET /api/v1/desk/upcoming` | read | `deals:read` | List Desk Upcoming |
+| [`markDeskKickoffPlayed`](#op-markdeskkickoffplayed) | `POST /api/v1/desk/kickoff/played` | write | `deals:write` | Mark Desk Kickoff Played |
+| [`postDeskVoiceMemo`](#op-postdeskvoicememo) | `POST /api/v1/desk/voice-memo` | billable | `deals:run` | Post Desk Voice Memo |
+| [`previewAccountPlan`](#op-previewaccountplan) | `POST /api/v1/desk/accounts/{account_id}/plan/preview` | read | `deals:read` | Preview Account Plan |
+| [`pullDeskBatch`](#op-pulldeskbatch) | `POST /api/v1/desk/batch/pull` | write | `deals:write` | Pull Desk Batch |
+| [`replanDeskDecision`](#op-replandeskdecision) | `POST /api/v1/desk/decisions/{decision_id}/replan` | billable | `deals:run` | Replan Desk Decision |
+| [`resolveDeskDecision`](#op-resolvedeskdecision) | `POST /api/v1/desk/decisions/{decision_id}/resolve` | write | `deals:write` | Resolve Desk Decision |
+| [`reviveDeskListGoal`](#op-revivedesklistgoal) | `POST /api/v1/desk/list-goals/{list_id}/revive` | write | `deals:write` | Revive Desk List Goal |
+| [`runCommitteePlay`](#op-runcommitteeplay) | `POST /api/v1/desk/accounts/{account_id}/committee/plays/{action_id}/run` | external | `deals:run` | Run Committee Play |
+| [`runDeskCardPlay`](#op-rundeskcardplay) | `POST /api/v1/desk/decisions/{decision_id}/plays/{action_id}/run` | external | `deals:run` | Run Desk Card Play |
+| [`runDeskPlanStageSweep`](#op-rundeskplanstagesweep) | `POST /api/v1/desk/org-settings/plan-stages/run` | billable | `deals:run` | Run Desk Plan Stage Sweep |
+| [`scoreDeskEmail`](#op-scoredeskemail) | `POST /api/v1/desk/email-score` | billable | `deals:run` | Score Desk Email |
+| [`sendCommitteeLinkedinInvite`](#op-sendcommitteelinkedininvite) | `POST /api/v1/desk/accounts/{account_id}/committee/{contact_id}/linkedin-invite` | external | `deals:run` | Send Committee Linkedin Invite |
+| [`sendDeskReply`](#op-senddeskreply) | `POST /api/v1/desk/decisions/{decision_id}/send-reply` | external | `deals:run` | Send Desk Reply |
+| [`sendDeskSms`](#op-senddesksms) | `POST /api/v1/desk/decisions/{decision_id}/send-sms` | external | `deals:run` | Send Desk Sms |
+| [`startDeskBatch`](#op-startdeskbatch) | `POST /api/v1/desk/batch/start` | write | `deals:write` | Start Desk Batch |
+| [`undoDeskDecision`](#op-undodeskdecision) | `POST /api/v1/desk/decisions/{decision_id}/undo` | write | `deals:write` | Undo Desk Decision |
+| [`unsnoozeDeskDecision`](#op-unsnoozedeskdecision) | `POST /api/v1/desk/decisions/{decision_id}/unsnooze` | write | `deals:write` | Unsnooze Desk Decision |
+| [`updateAccountPlanStep`](#op-updateaccountplanstep) | `PUT /api/v1/desk/accounts/{account_id}/plan/steps/{step_id}` | write | `deals:write` | Update Account Plan Step |
+| [`updateDeskAutonomy`](#op-updatedeskautonomy) | `PUT /api/v1/desk/autonomy` | external | `deals:run` | Update Desk Autonomy |
+| [`updateDeskLinkedinSender`](#op-updatedesklinkedinsender) | `PUT /api/v1/desk/linkedin-sender` | write | `deals:write` | Update Desk Linkedin Sender |
+| [`updateDeskListGoal`](#op-updatedesklistgoal) | `PUT /api/v1/desk/list-goals` | write | `deals:write` | Update Desk List Goal |
+| [`updateDeskListGroupOverride`](#op-updatedesklistgroupoverride) | `PUT /api/v1/desk/list-group-override` | write | `deals:write` | Update Desk List Group Override |
+| [`updateDeskListPriority`](#op-updatedesklistpriority) | `PUT /api/v1/desk/list-priority` | write | `deals:write` | Update Desk List Priority |
+| [`updateDeskOrgSettings`](#op-updatedeskorgsettings) | `PUT /api/v1/desk/org-settings` | external | `deals:run` | Update Desk Org Settings |
+
+---
+
+<a id="op-applyaccountplan"></a>
+
+### `g8.api.desk.applyAccountPlan(input)`
+
+**Apply Account Plan**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/plan/apply`
+- operationId: `apply_account_plan_desk_accounts__account_id__plan_apply_post` (also callable as `g8.api.call("apply_account_plan_desk_accounts__account_id__plan_apply_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Persist the approved steps as a NEW plan version, and return the diff.
+
+`proposed_plan` must be non-empty. Apply REPLACES the account's steps, so
+an empty proposal would blank an active plan; the app answers 400 rather
+than doing it. Prior versions stay immutable and readable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `body` | `AccountPlanApplyRequest` | yes | Request body; fields below. |
+
+Body fields (`AccountPlanApplyRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.instruction` | `string \| null` | no |  |
+| `body.proposed_plan` | `Array<AccountPlanStep>` | no |  |
+| `body.rationale` | `string \| null` | no |  |
+| `body.status` | `string \| null` | no | draft \| active \| paused \| archived. |
+| `body.trigger` | `string` | no | What caused this (re)plan. default `"manual"` |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.applyAccountPlan({ path: { account_id: 1 }, body: {} });
+```
+
+---
+
+<a id="op-askdesk"></a>
+
+### `g8.api.desk.askDesk(input)`
+
+**Ask Desk**
+
+- HTTP: `POST /api/v1/desk/ask`
+- operationId: `ask_desk_desk_ask_post` (also callable as `g8.api.call("ask_desk_desk_ask_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Ask a grounded question about a card or a deal.
+
+FAIL-SOFT: with the org's `ai_briefs` switch off it returns a canned answer
+and HTTP 200, not an error. A caller that needs to know whether it got a
+real answer should look at the payload, not the status code.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskAskRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskAskRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.question` | `string` | yes | min length 1, max length 2000 |
+| `body.deal_id` | `string \| null` | no | Ground the answer in this deal. max length 255 |
+| `body.decision_id` | `string (uuid) \| null` | no | Ground the answer in this decision card. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.askDesk({ body: { question: "example" } });
+```
+
+---
+
+<a id="op-checkcommitteeplay"></a>
+
+### `g8.api.desk.checkCommitteePlay(input)`
+
+**Check Committee Play**
+
+- HTTP: `GET /api/v1/desk/accounts/{account_id}/committee/plays/{action_id}/check`
+- operationId: `check_committee_play_desk_accounts__account_id__committee_plays__action_id__check_get` (also callable as `g8.api.call("check_committee_play_desk_accounts__account_id__committee_plays__action_id__check_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What running this workflow at this committee would DO, in plain words.
+
+Its effects, who it would run for, who it already ran for, and whether the
+desk refuses it. Read-only; runs nothing and spends nothing. This is the
+call to make before the run below.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `path.action_id` | `string` | yes | Play id, from `.../committee/plays`. |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.checkCommitteePlay({ path: { account_id: 1, action_id: "id" } });
+```
+
+---
+
+<a id="op-checkdeskplanstagesweep"></a>
+
+### `g8.api.desk.checkDeskPlanStageSweep(input?)`
+
+**Check Desk Plan Stage Sweep**
+
+- HTTP: `GET /api/v1/desk/org-settings/plan-stages/check`
+- operationId: `check_desk_plan_stage_sweep_desk_org_settings_plan_stages_check_get` (also callable as `g8.api.call("check_desk_plan_stage_sweep_desk_org_settings_plan_stages_check_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+How many open deals the sweep below WOULD plan, and why the rest not.
+
+SPENDS NOTHING. A GET behind a write permission, which is the app's choice
+and the right one: this exists to be read immediately before the charged
+run, by the person allowed to fire it.
+
+Read `cap`, `cap_exhausted` and `eligible` before running - they are what
+tell you whether the press will do anything.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.checkDeskPlanStageSweep();
+```
+
+---
+
+<a id="op-createorreplanaccountplan"></a>
+
+### `g8.api.desk.createOrReplanAccountPlan(input)`
+
+**Create Or Replan Account Plan**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/plan`
+- operationId: `create_or_replan_account_plan_desk_accounts__account_id__plan_post` (also callable as `g8.api.call("create_or_replan_account_plan_desk_accounts__account_id__plan_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Write this account's plan, from a plan the CALLER authored.
+
+Create and replan are the same operation because a plan is versioned: this
+inserts a new version and bumps `plan_version` whether or not one existed.
+Nothing is generated and nothing is charged - the steps come from the
+request body. For the desk to draft them instead, use `/plan/draft`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `body` | `AccountPlanUpsertRequest` | yes | Request body; fields below. |
+
+Body fields (`AccountPlanUpsertRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.buying_committee_id` | `string (uuid) \| null` | no |  |
+| `body.buying_committee_members` | `Array<Record<string, unknown>> \| null` | no |  |
+| `body.current_plan` | `Array<AccountPlanStep>` | no |  |
+| `body.deep_research_summary` | `string \| null` | no |  |
+| `body.goal` | `string \| null` | no |  |
+| `body.rationale` | `string \| null` | no | Optional why-now, recorded in the trigger history. |
+| `body.status` | `string \| null` | no | draft \| active \| paused \| archived. |
+| `body.trigger` | `string` | no | What caused this (re)plan. default `"manual"` |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.createOrReplanAccountPlan({ path: { account_id: 1 }, body: {} });
+```
+
+---
+
+<a id="op-decidedeskplayapproval"></a>
+
+### `g8.api.desk.decideDeskPlayApproval(input)`
+
+**Decide Desk Play Approval**
+
+- HTTP: `POST /api/v1/desk/plays/approvals/{execution_id}/decide`
+- operationId: `decide_desk_play_approval_desk_plays_approvals__execution_id__decide_post` (also callable as `g8.api.call("decide_desk_play_approval_desk_plays_approvals__execution_id__decide_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+Approve or reject one paused run, AS THIS REP.
+
+Approving RESUMES the run, and what it then does is whatever the workflow
+does - which can include sending. The identity matters: the workflow's
+author may have named an approver list, and a caller not on it gets a 403
+rather than a silent no-op.
+
+403 means "not your decision to make", 404 means the run is no longer
+waiting. Neither is a retryable error.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Paused workflow execution id. |
+| `body` | `DeskApprovalDecisionRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskApprovalDecisionRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.decision` | `"approve" \| "reject"` | yes |  |
+| `body.note` | `string \| null` | no | Optional note. The engine records it as `notes` on an approval and `reason` on a rejection. max length 2000 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.decideDeskPlayApproval({ path: { execution_id: "id" }, body: { decision: "approve" } });
+```
+
+---
+
+<a id="op-draftaccountplan"></a>
+
+### `g8.api.desk.draftAccountPlan(input)`
+
+**Draft Account Plan**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/plan/draft`
+- operationId: `draft_account_plan_desk_accounts__account_id__plan_draft_post` (also callable as `g8.api.call("draft_account_plan_desk_accounts__account_id__plan_draft_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+SPENDS CREDITS. Let the desk draft the committee and the first steps.
+
+This runs the same producer the desk runs automatically, and it counts
+against the org's `max_auto_account_plans_per_day` cap - which is what
+makes it a spend rather than a write.
+
+409 when a plan already exists: this only creates a FIRST version. Replan
+an existing one with `POST .../plan` (caller-authored, free) or from a
+review card with `POST /desk/decisions/{id}/replan` (charged).
+422 when the company has no contacts to plan around yet.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.draftAccountPlan({ path: { account_id: 1 } });
+```
+
+---
+
+<a id="op-editaccountcommittee"></a>
+
+### `g8.api.desk.editAccountCommittee(input)`
+
+**Edit Account Committee**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/committee`
+- operationId: `edit_account_committee_desk_accounts__account_id__committee_post` (also callable as `g8.api.call("edit_account_committee_desk_accounts__account_id__committee_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Add and remove buying-committee members.
+
+Rides plan versioning like everything else: it persists a NEW plan version
+preserving the existing steps, rather than mutating the committee in place.
+Both lists apply in the same version, so the committee is never left
+half-changed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `body` | `CommitteeEditRequest` | yes | Request body; fields below. |
+
+Body fields (`CommitteeEditRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.add` | `Array<CommitteeMemberInput>` | no |  |
+| `body.remove` | `Array<integer>` | no | Contact ids to take off the committee. |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.editAccountCommittee({ path: { account_id: 1 }, body: {} });
+```
+
+---
+
+<a id="op-findcommitteememberlinkedin"></a>
+
+### `g8.api.desk.findCommitteeMemberLinkedin(input)`
+
+**Find Committee Member Linkedin**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/committee/{contact_id}/find-linkedin`
+- operationId: `find_committee_member_linkedin_desk_accounts__account_id__committee__contact_id__find_linkedin_post` (also callable as `g8.api.call("find_committee_member_linkedin_desk_accounts__account_id__committee__contact_id__find_linkedin_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+SPENDS CREDITS. Find ONE committee member's LinkedIn profile.
+
+About five credits per attempt, CHARGED ON A MISS AS WELL AS A HIT - both
+providers in the pipeline bill on no-match, at a measured 58% hit rate. So
+the cost is per call, not per result.
+
+Deliberately ONE contact per call, and the contact must be on THIS
+account's committee. There is no bulk entry point and this surface does not
+add one: pointed at contacts generally it would be a seven-figure credit
+button.
+
+Queues an ASYNC lookup - the result lands on the contact record afterwards,
+so read it back from `/desk/committee-targets`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `path.contact_id` | `integer` | yes | The committee member to look up. |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.findCommitteeMemberLinkedin({ path: { account_id: 1, contact_id: 123 } });
+```
+
+---
+
+<a id="op-getaccountcontext"></a>
+
+### `g8.api.desk.getAccountContext(input)`
+
+**Get Account Context**
+
+- HTTP: `GET /api/v1/desk/accounts/{account_id}/context`
+- operationId: `get_account_context_desk_accounts__account_id__context_get` (also callable as `g8.api.call("get_account_context_desk_accounts__account_id__context_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Why this account is here: summary, timeline, deal state, committee.
+
+Read-only; never writes. This is the evidence a plan is built from, so it
+is the right read before proposing one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `query.activity_limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getAccountContext({ path: { account_id: 1 } });
+```
+
+---
+
+<a id="op-getaccountplan"></a>
+
+### `g8.api.desk.getAccountPlan(input)`
+
+**Get Account Plan**
+
+- HTTP: `GET /api/v1/desk/accounts/{account_id}/plan`
+- operationId: `get_account_plan_desk_accounts__account_id__plan_get` (also callable as `g8.api.call("get_account_plan_desk_accounts__account_id__plan_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The LATEST plan version for this account.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getAccountPlan({ path: { account_id: 1 } });
+```
+
+---
+
+<a id="op-getaccountplanhistory"></a>
+
+### `g8.api.desk.getAccountPlanHistory(input)`
+
+**Get Account Plan History**
+
+- HTTP: `GET /api/v1/desk/accounts/{account_id}/plan/history`
+- operationId: `get_account_plan_history_desk_accounts__account_id__plan_history_get` (also callable as `g8.api.call("get_account_plan_history_desk_accounts__account_id__plan_history_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Every version of this account's plan, newest first.
+
+Versions are immutable, so this is the audit trail: what the plan said
+before each replan, and what triggered it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `query.limit` | `integer` | no | default `20` |
+
+**Returns** `ApiResponse_AccountPlanListPayload_`: the envelope `{ data: AccountPlanListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AccountPlanListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getAccountPlanHistory({ path: { account_id: 1 } });
+```
+
+---
+
+<a id="op-getdeskautonomy"></a>
+
+### `g8.api.desk.getDeskAutonomy(input?)`
+
+**Get Desk Autonomy**
+
+- HTTP: `GET /api/v1/desk/autonomy`
+- operationId: `get_desk_autonomy_desk_autonomy_get` (also callable as `g8.api.call("get_desk_autonomy_desk_autonomy_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+This rep's autonomy lanes, and which decision types can be automated.
+
+`autopilot_capable_types` is the useful half: a type not in it cannot be
+put on autopilot, and asking for it is silently DOWNGRADED rather than
+refused, so read this before writing lanes.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskAutonomy();
+```
+
+---
+
+<a id="op-getdeskbatch"></a>
+
+### `g8.api.desk.getDeskBatch(input?)`
+
+**Get Desk Batch**
+
+- HTTP: `GET /api/v1/desk/batch`
+- operationId: `get_desk_batch_desk_batch_get` (also callable as `g8.api.call("get_desk_batch_desk_batch_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+This rep's batch for their local day.
+
+`data` is NULL when no batch has been started today. That is different
+from a batch with nothing left in it, and the difference decides whether a
+UI shows "start your day" or "you are done" - so it is preserved rather
+than flattened into an empty batch.
+
+The app's `include=overview` composite is deliberately not exposed: it
+returns a different response shape from the same path, which is a shell
+optimisation rather than a contract a rebuilder should depend on.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). A batch is scoped to the rep's local day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_Union_DeskBatch__NoneType__`: the envelope `{ data: DeskBatch | null, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`data` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `completed` | `integer \| null` | no |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `item_ids` | `Array<string>` | no |  |
+| `remaining` | `integer \| null` | no |  |
+| `started_at` | `string (date-time) \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `total` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskBatch();
+```
+
+---
+
+<a id="op-getdeskblockqueue"></a>
+
+### `g8.api.desk.getDeskBlockQueue(input)`
+
+**Get Desk Block Queue**
+
+- HTTP: `GET /api/v1/desk/blocks/{list_id}/queue`
+- operationId: `get_desk_block_queue_desk_blocks__list_id__queue_get` (also callable as `g8.api.call("get_desk_block_queue_desk_blocks__list_id__queue_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The ordered work set behind one dial block.
+
+Always 200, including for a list with nothing due - an empty queue is an
+answer, not an error. The ladder and the ownership rules are applied here,
+which is why `/desk/contacts/{contact_id}/call-target` can then resolve a
+number for any stop it produced.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | Dial list (audience) id. |
+| `query.redial_only` | `boolean` | no | Only the contacts whose redial day is up, never the not-yet-called half. default `false` |
+
+**Returns** `ApiResponse_DeskListPayload_`: the envelope `{ data: DeskListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskBlockQueue({ path: { list_id: 123 } });
+```
+
+---
+
+<a id="op-getdeskcalltarget"></a>
+
+### `g8.api.desk.getDeskCallTarget(input)`
+
+**Get Desk Call Target**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/call-target`
+- operationId: `get_desk_call_target_desk_decisions__decision_id__call_target_post` (also callable as `g8.api.call("get_desk_call_target_desk_decisions__decision_id__call_target_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Resolve the dialable number for a CARD, after the opt-out check.
+
+Same always-200 contract as the contact route above. The difference is
+ownership: this one checks the card belongs to the calling rep, because a
+card names a specific person to call.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskCallTarget({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskcommitteeheat"></a>
+
+### `g8.api.desk.getDeskCommitteeHeat(input)`
+
+**Get Desk Committee Heat**
+
+- HTTP: `GET /api/v1/desk/committee-heat`
+- operationId: `get_desk_committee_heat_desk_committee_heat_get` (also callable as `g8.api.call("get_desk_committee_heat_desk_committee_heat_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Four-week engagement heatmap for an account's buying committee.
+
+Read-only and no model call. Fails SOFT to an empty member list rather
+than erroring, so a dashboard degrades instead of breaking.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskCommitteeHeat({ query: { account_id: 1 } });
+```
+
+---
+
+<a id="op-getdeskcommitteetargets"></a>
+
+### `g8.api.desk.getDeskCommitteeTargets(input)`
+
+**Get Desk Committee Targets**
+
+- HTTP: `GET /api/v1/desk/committee-targets`
+- operationId: `get_desk_committee_targets_desk_committee_targets_get` (also callable as `g8.api.call("get_desk_committee_targets_desk_committee_targets_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Who on the committee is reachable on LinkedIn, and why not when not.
+
+Reads only: it never sends and never writes. The send is
+`POST /desk/accounts/{account_id}/committee/{contact_id}/linkedin-invite`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskCommitteeTargets({ query: { account_id: 1 } });
+```
+
+---
+
+<a id="op-getdeskcompliancesummary"></a>
+
+### `g8.api.desk.getDeskComplianceSummary(input?)`
+
+**Get Desk Compliance Summary**
+
+- HTTP: `GET /api/v1/desk/compliance-summary`
+- operationId: `get_desk_compliance_summary_desk_compliance_summary_get` (also callable as `g8.api.call("get_desk_compliance_summary_desk_compliance_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Stage-checklist readiness aggregated across this rep's open deals.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | Open deals to aggregate over. default `50` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskComplianceSummary();
+```
+
+---
+
+<a id="op-getdeskcontactcalltarget"></a>
+
+### `g8.api.desk.getDeskContactCallTarget(input)`
+
+**Get Desk Contact Call Target**
+
+- HTTP: `POST /api/v1/desk/contacts/{contact_id}/call-target`
+- operationId: `get_desk_contact_call_target_desk_contacts__contact_id__call_target_post` (also callable as `g8.api.call("get_desk_contact_call_target_desk_contacts__contact_id__call_target_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Resolve the dialable number for one contact, after the opt-out check.
+
+ALWAYS 200. "No number on file" and "this person opted out" are ordinary
+answers carried in the payload as `is_dialable: false` with a reason, not
+errors - a caller that treats a non-200 as the only failure mode will dial
+people who asked not to be called.
+
+POST rather than GET is the app's choice: it consults the suppression
+ledger, and pressing Call is an intent to contact someone, which should not
+be firable by a prefetch. It resolves and writes nothing, which is why it
+is tiered a READ.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact id. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskContactCallTarget({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-getdeskcoverage"></a>
+
+### `g8.api.desk.getDeskCoverage(input?)`
+
+**Get Desk Coverage**
+
+- HTTP: `GET /api/v1/desk/coverage`
+- operationId: `get_desk_coverage_desk_coverage_get` (also callable as `g8.api.call("get_desk_coverage_desk_coverage_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Quarterly open-pipeline coverage against target.
+
+`{"enabled": false}` when the org has set no quarterly target - a 200 with
+a reason rather than a 404, so a dashboard can say "not configured".
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskCoverage();
+```
+
+---
+
+<a id="op-getdeskdecisionbrief"></a>
+
+### `g8.api.desk.getDeskDecisionBrief(input)`
+
+**Get Desk Decision Brief**
+
+- HTTP: `GET /api/v1/desk/decisions/{decision_id}/brief`
+- operationId: `get_desk_decision_brief_desk_decisions__decision_id__brief_get` (also callable as `g8.api.call("get_desk_decision_brief_desk_decisions__decision_id__brief_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Enriched brief for a card - what the slide-over panel shows.
+
+Returned as an open object: the app types this `-> dict` and assembles it
+from several upstreams, so pinning a schema here would silently DROP a
+field the moment one is added.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**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
+const result = await g8.api.desk.getDeskDecisionBrief({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskdecisioncardcontext"></a>
+
+### `g8.api.desk.getDeskDecisionCardContext(input)`
+
+**Get Desk Decision Card Context**
+
+- HTTP: `GET /api/v1/desk/decisions/{decision_id}/card-context`
+- operationId: `get_desk_decision_card_context_desk_decisions__decision_id__card_context_get` (also callable as `g8.api.call("get_desk_decision_card_context_desk_decisions__decision_id__card_context_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Everything needed to render the card: the entity, its history, the ask.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**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
+const result = await g8.api.desk.getDeskDecisionCardContext({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskdecisionconversation"></a>
+
+### `g8.api.desk.getDeskDecisionConversation(input)`
+
+**Get Desk Decision Conversation**
+
+- HTTP: `GET /api/v1/desk/decisions/{decision_id}/conversation`
+- operationId: `get_desk_decision_conversation_desk_decisions__decision_id__conversation_get` (also callable as `g8.api.call("get_desk_decision_conversation_desk_decisions__decision_id__conversation_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The thread behind the card - what has already been said.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**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
+const result = await g8.api.desk.getDeskDecisionConversation({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskhomesummary"></a>
+
+### `g8.api.desk.getDeskHomeSummary(input?)`
+
+**Get Desk Home Summary**
+
+- HTTP: `GET /api/v1/desk/home-summary`
+- operationId: `get_desk_home_summary_desk_home_summary_get` (also callable as `g8.api.call("get_desk_home_summary_desk_home_summary_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Goal progress, streak, digest and tomorrow's preview, in one read.
+
+`since` narrows the digest lookback in the app. It is not published: it
+defaults to the last 24 hours, is capped at seven days, and exposing it
+would publish a knob whose only effect is to skip a 60-second cache.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskHomeSummary();
+```
+
+---
+
+<a id="op-getdeskkickoff"></a>
+
+### `g8.api.desk.getDeskKickoff(input?)`
+
+**Get Desk Kickoff**
+
+- HTTP: `GET /api/v1/desk/kickoff`
+- operationId: `get_desk_kickoff_desk_kickoff_get` (also callable as `g8.api.call("get_desk_kickoff_desk_kickoff_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+The rep's 60-second AI daily briefing, cached per local day.
+
+SPENDS CREDITS ON THE FIRST READ OF THE DAY: a cache miss builds the
+briefing with a charged model call; every later read that day is served
+from the cache. That is why this GET is tiered `billable`, not `read`.
+
+`{"enabled": false}` when the org's `morning_kickoff` switch is off.
+
+The app's `force=true` rebuild is NOT published, and that is a spend
+decision rather than a tidiness one: the briefing is one model call per rep
+per local day, and a published `force` turns a dashboard poll into a
+charged call per request. Read the cached one; it is the same briefing the
+rep sees. (`force=False` is passed EXPLICITLY below - the app's default is
+a `Query` instance, which is truthy, so omitting it would force a rebuild
+on every single call.)
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.getDeskKickoff();
+```
+
+---
+
+<a id="op-getdeskkickoffaudio"></a>
+
+### `g8.api.desk.getDeskKickoffAudio(input?)`
+
+**Get Desk Kickoff Audio**
+
+- HTTP: `GET /api/v1/desk/kickoff/audio`
+- operationId: `get_desk_kickoff_audio_desk_kickoff_audio_get` (also callable as `g8.api.call("get_desk_kickoff_audio_desk_kickoff_audio_get", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Today's kickoff script, SPOKEN: an `audio/mpeg` body.
+
+The one desk operation that does not answer in the JSON envelope - the
+payload is the MP3 itself, exactly as the app serves it. The script it
+speaks is `GET /desk/kickoff`. The speech call is platform cost, but the
+script behind it is BUILT here on a cache miss - a charged model call, the
+same one `GET /desk/kickoff` makes - so this GET is tiered `billable`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns**: no JSON body is declared for the success response.
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.getDeskKickoffAudio();
+```
+
+---
+
+<a id="op-getdesklinkedinsender"></a>
+
+### `g8.api.desk.getDeskLinkedinSender(input?)`
+
+**Get Desk Linkedin Sender**
+
+- HTTP: `GET /api/v1/desk/linkedin-sender`
+- operationId: `get_desk_linkedin_sender_desk_linkedin_sender_get` (also callable as `g8.api.call("get_desk_linkedin_sender_desk_linkedin_sender_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Which LinkedIn account this rep sends desk invites from.
+
+Returns the rep's own pick plus every account in the org and who holds it,
+so a caller can see what is free before claiming one.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskLinkedinSender();
+```
+
+---
+
+<a id="op-getdesklistgoals"></a>
+
+### `g8.api.desk.getDeskListGoals(input?)`
+
+**Get Desk List Goals**
+
+- HTTP: `GET /api/v1/desk/list-goals`
+- operationId: `get_desk_list_goals_desk_list_goals_get` (also callable as `g8.api.call("get_desk_list_goals_desk_list_goals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The rep's per-list daily dial targets, and progress against them.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskListGoals();
+```
+
+---
+
+<a id="op-getdesklistgroupoverride"></a>
+
+### `g8.api.desk.getDeskListGroupOverride(input?)`
+
+**Get Desk List Group Override**
+
+- HTTP: `GET /api/v1/desk/list-group-override`
+- operationId: `get_desk_list_group_override_desk_list_group_override_get` (also callable as `g8.api.call("get_desk_list_group_override_desk_list_group_override_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The rep's own moves of dial lists into a band, keyed by list id.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskListGroupOverride();
+```
+
+---
+
+<a id="op-getdesklistpriority"></a>
+
+### `g8.api.desk.getDeskListPriority(input?)`
+
+**Get Desk List Priority**
+
+- HTTP: `GET /api/v1/desk/list-priority`
+- operationId: `get_desk_list_priority_desk_list_priority_get` (also callable as `g8.api.call("get_desk_list_priority_desk_list_priority_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The rep's pinned dial lists, most important first.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskListPriority();
+```
+
+---
+
+<a id="op-getdesknextbest"></a>
+
+### `g8.api.desk.getDeskNextBest(input?)`
+
+**Get Desk Next Best**
+
+- HTTP: `GET /api/v1/desk/next-best`
+- operationId: `get_desk_next_best_desk_next_best_get` (also callable as `g8.api.call("get_desk_next_best_desk_next_best_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Next-best account suggestions. At most three; cached for an hour.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskNextBest();
+```
+
+---
+
+<a id="op-getdeskorgsettings"></a>
+
+### `g8.api.desk.getDeskOrgSettings(input?)`
+
+**Get Desk Org Settings**
+
+- HTTP: `GET /api/v1/desk/org-settings`
+- operationId: `get_desk_org_settings_desk_org_settings_get` (also callable as `g8.api.call("get_desk_org_settings_desk_org_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Effective org-level desk settings: kill switches, thresholds and caps.
+
+UNGATED on purpose, matching the app. This is the always-on desk home read
+("watching N signals"), so requiring `settings:read` would break it for
+every SDR and AE. The admin surface is the PUT below.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskOrgSettings();
+```
+
+---
+
+<a id="op-getdeskplayexecution"></a>
+
+### `g8.api.desk.getDeskPlayExecution(input)`
+
+**Get Desk Play Execution**
+
+- HTTP: `GET /api/v1/desk/plays/executions/{execution_id}`
+- operationId: `get_desk_play_execution_desk_plays_executions__execution_id__get` (also callable as `g8.api.call("get_desk_play_execution_desk_plays_executions__execution_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Live state of one play run.
+
+Pass `decision_id` only if you want the card updated when the run reaches a
+terminal state; that is what the desk's own status chip does as it polls.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.execution_id` | `string` | yes | Workflow execution id. |
+| `query.decision_id` | `string \| null` | no | Card this run belongs to. When given, a TERMINAL status is persisted onto the card - so this read has a write side, and omitting it keeps the read pure. |
+| `query.action_id` | `string \| null` | no | Play this run belongs to. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskPlayExecution({ path: { execution_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskpulse"></a>
+
+### `g8.api.desk.getDeskPulse(input?)`
+
+**Get Desk Pulse**
+
+- HTTP: `GET /api/v1/desk/pulse`
+- operationId: `get_desk_pulse_desk_pulse_get` (also callable as `g8.api.call("get_desk_pulse_desk_pulse_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Queue counts, the type breakdown, and the nudge.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskPulse();
+```
+
+---
+
+<a id="op-getdeskreplytarget"></a>
+
+### `g8.api.desk.getDeskReplyTarget(input)`
+
+**Get Desk Reply Target**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/reply-target`
+- operationId: `get_desk_reply_target_desk_decisions__decision_id__reply_target_post` (also callable as `g8.api.call("get_desk_reply_target_desk_decisions__decision_id__reply_target_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Who this card replies TO, and which mailbox it replies FROM.
+
+ALWAYS 200: no address on file, no authorised mailbox and an opt-out all
+come back as `is_sendable: false` with a reason.
+
+Resolving is not sending, and this route does neither a write nor a send.
+Call `/desk/decisions/{id}/send-reply` for that - it re-runs the opt-out
+check, because this answer is only as fresh as the moment it was asked.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskReplyTarget({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdesksmstarget"></a>
+
+### `g8.api.desk.getDeskSmsTarget(input)`
+
+**Get Desk Sms Target**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/sms-target`
+- operationId: `get_desk_sms_target_desk_decisions__decision_id__sms_target_post` (also callable as `g8.api.call("get_desk_sms_target_desk_decisions__decision_id__sms_target_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Which number this card texts, and which number it texts FROM.
+
+Always 200, same as the other two targets. Resolves; never sends.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskSmsTarget({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-getdeskwrapped"></a>
+
+### `g8.api.desk.getDeskWrapped(input?)`
+
+**Get Desk Wrapped**
+
+- HTTP: `GET /api/v1/desk/wrapped`
+- operationId: `get_desk_wrapped_desk_wrapped_get` (also callable as `g8.api.call("get_desk_wrapped_desk_wrapped_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+This local ISO WEEK's numbers, best email and personal records.
+
+Weekly, not daily, and the week boundary follows `tz_offset` - so a wrong
+offset can return last week's numbers around the weekend.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.getDeskWrapped();
+```
+
+---
+
+<a id="op-improvedeskemail"></a>
+
+### `g8.api.desk.improveDeskEmail(input)`
+
+**Improve Desk Email**
+
+- HTTP: `POST /api/v1/desk/email-improve`
+- operationId: `improve_desk_email_desk_email_improve_post` (also callable as `g8.api.call("improve_desk_email_desk_email_improve_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Rewrite a draft, targeting the subscores it is failing.
+
+Unlike `/desk/email-score` this one has no heuristic fallback: it is a
+model call or nothing. 400 when the org's `ai_briefs` switch is off, 502
+when the model could not answer.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskEmailImproveRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskEmailImproveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | max length 50000 |
+| `body.subject` | `string` | no | default `""`, max length 1000 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.improveDeskEmail({ body: { body: "example" } });
+```
+
+---
+
+<a id="op-listaccountplans"></a>
+
+### `g8.api.desk.listAccountPlans(input?)`
+
+**List Account Plans**
+
+- HTTP: `GET /api/v1/desk/accounts/plans`
+- operationId: `list_account_plans_desk_accounts_plans_get` (also callable as `g8.api.call("list_account_plans_desk_accounts_plans_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+The Account Board: the latest plan version per account.
+
+`mine=true` is resolved against the caller's own identity. For a MACHINE
+key that is nobody, so it returns nothing - which is correct rather than
+broken, and is why the default is false.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `"draft" \| "active" \| "paused" \| "archived" \| null` | no | Only plans in this status. |
+| `query.source` | `"all" \| "deals" \| "campaign" \| null` | no | Which board: `deals` (accounts with an open deal), `campaign` (requires `campaign_id`), or `all`. Omitted means all. |
+| `query.campaign_id` | `string \| null` | no | REQUIRED when `source=campaign`. |
+| `query.mine` | `boolean` | no | Only accounts this caller owns. Ownership is resolved BEFORE paging, so this changes the total rather than filtering a page. default `false` |
+| `query.limit` | `integer` | no | default `100` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_AccountPlanListPayload_`: the envelope `{ data: AccountPlanListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AccountPlanListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listAccountPlans();
+```
+
+---
+
+<a id="op-listcommitteeplays"></a>
+
+### `g8.api.desk.listCommitteePlays(input)`
+
+**List Committee Plays**
+
+- HTTP: `GET /api/v1/desk/accounts/{account_id}/committee/plays`
+- operationId: `list_committee_plays_desk_accounts__account_id__committee_plays_get` (also callable as `g8.api.call("list_committee_plays_desk_accounts__account_id__committee_plays_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Workflows that can be fired at this account's committee.
+
+Only the ones the desk would actually run - the listing applies the same
+filter the run does. Read-only; runs nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+
+**Returns** `ApiResponse_AccountPlanListPayload_`: the envelope `{ data: AccountPlanListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`AccountPlanListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listCommitteePlays({ path: { account_id: 1 } });
+```
+
+---
+
+<a id="op-listcompleteddeskdecisions"></a>
+
+### `g8.api.desk.listCompletedDeskDecisions(input?)`
+
+**List Completed Desk Decisions**
+
+- HTTP: `GET /api/v1/desk/decisions/completed`
+- operationId: `list_completed_desk_decisions_desk_decisions_completed_get` (also callable as `g8.api.call("list_completed_desk_decisions_desk_decisions_completed_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+What this rep finished today, in their local day.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer` | no | default `20` |
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). A batch is scoped to the rep's local day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskDecisionListResponse_`: the envelope `{ data: DeskDecisionListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskDecisionListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `decisions` | `Array<DeskDecision>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listCompletedDeskDecisions();
+```
+
+---
+
+<a id="op-listdeskblocks"></a>
+
+### `g8.api.desk.listDeskBlocks(input?)`
+
+**List Desk Blocks**
+
+- HTTP: `GET /api/v1/desk/blocks`
+- operationId: `list_desk_blocks_desk_blocks_get` (also callable as `g8.api.call("list_desk_blocks_desk_blocks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Dial passes due per list, from the redial ladder over call activity.
+
+A "block" is batched calling work: one of the rep's pinned lists, plus how
+many of its contacts the ladder says are due a call today.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskListPayload_`: the envelope `{ data: DeskListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listDeskBlocks();
+```
+
+---
+
+<a id="op-listdeskcardplays"></a>
+
+### `g8.api.desk.listDeskCardPlays(input)`
+
+**List Desk Card Plays**
+
+- HTTP: `GET /api/v1/desk/decisions/{decision_id}/plays`
+- operationId: `list_desk_card_plays_desk_decisions__decision_id__plays_get` (also callable as `g8.api.call("list_desk_card_plays_desk_decisions__decision_id__plays_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Workflows this card can run against its contact or company.
+
+404 when the org has not enabled plays. Each entry carries the effects the
+play would have in plain words, which is what makes the run below a
+deliberate act rather than a guess.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**Returns** `ApiResponse_DeskListPayload_`: the envelope `{ data: DeskListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listDeskCardPlays({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-listdeskdecisions"></a>
+
+### `g8.api.desk.listDeskDecisions(input?)`
+
+**List Desk Decisions**
+
+- HTTP: `GET /api/v1/desk/decisions`
+- operationId: `list_desk_decisions_desk_decisions_get` (also callable as `g8.api.call("list_desk_decisions_desk_decisions_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+This rep's pending queue, ranked.
+
+`source_group` and `source` are a family/exact pair, not synonyms:
+`source_group=forms` matches every form signal, `source=form_submitted`
+matches one.
+
+An omitted filter is passed as a real `None`. The app's own comment warns
+that a `Query(None)` sentinel is TRUTHY and would reach the repository as
+a filter value - so absent must stay absent all the way down.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.decision_type` | `string \| null` | no | Filter by decision type. |
+| `query.source_group` | `string \| null` | no | Filter by signal FAMILY, e.g. "forms" or "website". |
+| `query.source` | `string \| null` | no | Filter by EXACT signal id, e.g. "form_submitted". |
+| `query.limit` | `integer` | no | default `20` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `ApiResponse_DeskDecisionListResponse_`: the envelope `{ data: DeskDecisionListResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskDecisionListResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `decisions` | `Array<DeskDecision>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listDeskDecisions();
+```
+
+---
+
+<a id="op-listdeskplayapprovals"></a>
+
+### `g8.api.desk.listDeskPlayApprovals(input?)`
+
+**List Desk Play Approvals**
+
+- HTTP: `GET /api/v1/desk/plays/approvals`
+- operationId: `list_desk_play_approvals_desk_plays_approvals_get` (also callable as `g8.api.call("list_desk_play_approvals_desk_plays_approvals_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Workflow runs THIS rep started that are paused for a human decision.
+
+Empty list when the org has not enabled plays - this is a read, so a gated
+org gets a quiet 200 empty list rather than a 404 (g8 #19786; the paired
+`decide` action still 404s for a gated org). A reachable-but-unhappy engine
+instead returns an empty list with `engine_unreachable: true`, so "nothing
+waiting" and "cannot tell" are distinguishable rather than both rendering as
+a quiet panel.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskListPayload_`: the envelope `{ data: DeskListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listDeskPlayApprovals();
+```
+
+---
+
+<a id="op-listdeskupcoming"></a>
+
+### `g8.api.desk.listDeskUpcoming(input?)`
+
+**List Desk Upcoming**
+
+- HTTP: `GET /api/v1/desk/upcoming`
+- operationId: `list_desk_upcoming_desk_upcoming_get` (also callable as `g8.api.call("list_desk_upcoming_desk_upcoming_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Plan steps beyond the card horizon - what lands after today.
+
+Empty when nothing is ahead, which is a different statement from an empty
+QUEUE: the queue is what is due now, this is what is coming.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskListPayload_`: the envelope `{ data: DeskListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.listDeskUpcoming();
+```
+
+---
+
+<a id="op-markdeskkickoffplayed"></a>
+
+### `g8.api.desk.markDeskKickoffPlayed(input?)`
+
+**Mark Desk Kickoff Played**
+
+- HTTP: `POST /api/v1/desk/kickoff/played`
+- operationId: `mark_desk_kickoff_played_desk_kickoff_played_post` (also callable as `g8.api.call("mark_desk_kickoff_played_desk_kickoff_played_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Mark today's kickoff as played, so it does not auto-replay.
+
+A 48-hour flag, not a permanent one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.markDeskKickoffPlayed();
+```
+
+---
+
+<a id="op-postdeskvoicememo"></a>
+
+### `g8.api.desk.postDeskVoiceMemo(input?)`
+
+**Post Desk Voice Memo**
+
+- HTTP: `POST /api/v1/desk/voice-memo`
+- operationId: `post_desk_voice_memo_desk_voice_memo_post` (also callable as `g8.api.call("post_desk_voice_memo_desk_voice_memo_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+SPENDS CREDITS. Transcribe a voice memo and turn it into desk actions.
+
+Multipart, like the app. The memo is transcribed, its actions extracted by
+a model, and the result materialised as cards and tasks for this rep - the
+credits are charged per memo. 400 on an empty upload, 413 over 5 MB, 403
+when `deal_id` names a deal this rep may not write, 502 when transcription
+or extraction failed (nothing is materialised then).
+
+**Input**: none.
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.postDeskVoiceMemo();
+```
+
+---
+
+<a id="op-previewaccountplan"></a>
+
+### `g8.api.desk.previewAccountPlan(input)`
+
+**Preview Account Plan**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/plan/preview`
+- operationId: `preview_account_plan_desk_accounts__account_id__plan_preview_post` (also callable as `g8.api.call("preview_account_plan_desk_accounts__account_id__plan_preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `deals:read`
+
+Diff a proposed plan against the current version. WRITES NOTHING.
+
+POST only because the proposed plan is a body. It persists nothing, spends
+nothing and does not consume the signal-replanner cooldown, so it is tiered
+a READ - a read-only key must be able to see what an apply would change
+before anyone applies it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `body` | `AccountPlanPreviewRequest` | yes | Request body; fields below. |
+
+Body fields (`AccountPlanPreviewRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.instruction` | `string \| null` | no | Free-text note echoed back with the diff. |
+| `body.proposed_plan` | `Array<AccountPlanStep>` | no |  |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.previewAccountPlan({ path: { account_id: 1 }, body: {} });
+```
+
+---
+
+<a id="op-pulldeskbatch"></a>
+
+### `g8.api.desk.pullDeskBatch(input)`
+
+**Pull Desk Batch**
+
+- HTTP: `POST /api/v1/desk/batch/pull`
+- operationId: `pull_desk_batch_desk_batch_pull_post` (also callable as `g8.api.call("pull_desk_batch_desk_batch_pull_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Append more cards to today's existing batch.
+
+Capped lower than `start` (40 vs 80) on purpose: pulling is a top-up, not
+a second day.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskBatchPullRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskBatchPullRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.item_ids` | `Array<string (uuid)>` | yes | Decision ids to append. 1-40 - a smaller cap than start, by design. min items 1, max items 40 |
+| `body.tz_offset` | `integer` | no | The rep's UTC offset in minutes. default `0`, min -840, max 840 |
+
+**Returns** `ApiResponse_DeskBatch_`: the envelope `{ data: DeskBatch, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskBatch` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `completed` | `integer \| null` | no |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `item_ids` | `Array<string>` | no |  |
+| `remaining` | `integer \| null` | no |  |
+| `started_at` | `string (date-time) \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `total` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.pullDeskBatch({ body: { item_ids: ["00000000-0000-0000-0000-000000000000"] } });
+```
+
+---
+
+<a id="op-replandeskdecision"></a>
+
+### `g8.api.desk.replanDeskDecision(input)`
+
+**Replan Desk Decision**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/replan`
+- operationId: `replan_desk_decision_desk_decisions__decision_id__replan_post` (also callable as `g8.api.call("replan_desk_decision_desk_decisions__decision_id__replan_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+SPENDS CREDITS. Gather fresh evidence and write a NEW plan version.
+
+Rep-pressed only; nothing automatic reaches this. It rides the org's
+existing `account_plan_replan` switch, the per-account 24-hour cooldown and
+the org's daily cap, and a press cannot bypass any of them.
+
+A refusal from a gate is a 409 and costs NOTHING. A failure after the model
+answered may already have been charged, and says so in the response. There
+is no retry anywhere in this path, so a 409 means stop rather than try
+again.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Plan-review decision id (UUID). |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.replanDeskDecision({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-resolvedeskdecision"></a>
+
+### `g8.api.desk.resolveDeskDecision(input)`
+
+**Resolve Desk Decision**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/resolve`
+- operationId: `resolve_desk_decision_desk_decisions__decision_id__resolve_post` (also callable as `g8.api.call("resolve_desk_decision_desk_decisions__decision_id__resolve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Resolve a pending card.
+
+`snoozed_until` is REQUIRED when `status=snoozed` - it is the fallback
+timeout even when `wake_condition` is set, so a snooze can never be
+indefinite. The app enforces that; this surface does not second-guess it,
+it forwards the request and lets the single enforcement point answer.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+| `body` | `DeskResolveRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskResolveRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.status` | `string` | yes | approved, edited, skipped, deferred, snoozed or done_already. A status the app does not accept is a 400 rather than being silently dropped, which is why this is an open string and not an enum this surface would have to keep in lock-step. `done_already` resolves the card AND records the work on its entity. |
+| `body.action_taken` | `Record<string, unknown> \| null` | no | Action payload, e.g. the edited email body. |
+| `body.snoozed_until` | `string (date-time) \| null` | no | REQUIRED when status=snoozed. Wake time, UTC. |
+| `body.wake_condition` | `string \| null` | no | Early-wake condition, valid only with status=snoozed: reply \| site_visit \| stage_change. `snoozed_until` stays required as the fallback timeout. `stage_change` is accepted but only wakes via that timeout today - no deal-stage-change event reaches the desk signal consumer yet. |
+
+**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
+const result = await g8.api.desk.resolveDeskDecision({ path: { decision_id: "id" }, body: { status: "example" } });
+```
+
+---
+
+<a id="op-revivedesklistgoal"></a>
+
+### `g8.api.desk.reviveDeskListGoal(input)`
+
+**Revive Desk List Goal**
+
+- HTTP: `POST /api/v1/desk/list-goals/{list_id}/revive`
+- operationId: `revive_desk_list_goal_desk_list_goals__list_id__revive_post` (also callable as `g8.api.call("revive_desk_list_goal_desk_list_goals__list_id__revive_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+"I am carrying on today" - keep dialling past a met goal.
+
+Does NOT clear or raise the target. The goal stays what it was and stays
+met; this only stops the desk treating the list as finished for the rest
+of the rep's local day.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.list_id` | `integer` | yes | Dial list (audience) id. |
+| `query.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). The desk day is the rep's LOCAL day; a wrong offset silently returns the wrong day rather than erroring. default `0` |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.reviveDeskListGoal({ path: { list_id: 123 } });
+```
+
+---
+
+<a id="op-runcommitteeplay"></a>
+
+### `g8.api.desk.runCommitteePlay(input)`
+
+**Run Committee Play**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/committee/plays/{action_id}/run`
+- operationId: `run_committee_play_desk_accounts__account_id__committee_plays__action_id__run_post` (also callable as `g8.api.call("run_committee_play_desk_accounts__account_id__committee_plays__action_id__run_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+Fire one workflow at EVERY REACHABLE COMMITTEE MEMBER. One run each.
+
+This is the fan-out on this surface, and it is why the operation is not a
+plain write: one call becomes one workflow execution per person, and a
+workflow can email or message. Read `.../check` first - it names exactly
+who this would reach.
+
+IDEMPOTENT per (org, account, play, member) for one hour, so a retried
+press does not double up on anyone. 409 is a refusal with nothing fired,
+not a failure.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `path.action_id` | `string` | yes | Play id, from `.../committee/plays`. |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.runCommitteePlay({ path: { account_id: 1, action_id: "id" } });
+```
+
+---
+
+<a id="op-rundeskcardplay"></a>
+
+### `g8.api.desk.runDeskCardPlay(input)`
+
+**Run Desk Card Play**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/plays/{action_id}/run`
+- operationId: `run_desk_card_play_desk_decisions__decision_id__plays__action_id__run_post` (also callable as `g8.api.call("run_desk_card_play_desk_decisions__decision_id__plays__action_id__run_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+Run one play against this card's entity. REACHES THE OUTSIDE WORLD.
+
+A play is a workflow, and a workflow can email, send a LinkedIn message or
+push to a third party. That is why this is not a plain write: the grant to
+fire one is the grant to have graph8 act on a customer's behalf.
+
+IDEMPOTENT per (org, card, play) for one hour, so a retried press does not
+fire twice. The play is re-validated against this card's own eligible list,
+so an `action_id` the listing hides cannot be run by posting it directly,
+and the workflow's steps are re-read fresh on every press rather than from
+the listing's cache.
+
+409 is a refusal, not a failure: the workflow exists and the caller may see
+it, the desk just will not fire it - and nothing has spent at that point.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+| `path.action_id` | `string` | yes | Play id, from `/desk/decisions/{id}/plays`. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.runDeskCardPlay({ path: { decision_id: "id", action_id: "id" } });
+```
+
+---
+
+<a id="op-rundeskplanstagesweep"></a>
+
+### `g8.api.desk.runDeskPlanStageSweep(input?)`
+
+**Run Desk Plan Stage Sweep**
+
+- HTTP: `POST /api/v1/desk/org-settings/plan-stages/run`
+- operationId: `run_desk_plan_stage_sweep_desk_org_settings_plan_stages_run_post` (also callable as `g8.api.call("run_desk_plan_stage_sweep_desk_org_settings_plan_stages_run_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+CHARGED, AND IT ACTS ON MANY DEALS AT ONCE.
+
+One model call per plan, capped at 100 credits each, for every open deal
+already sitting in the org's plan-required stages - stopping at the org's
+daily cap. That is the difference between this and every other write on
+the desk: the spend scales with the org's pipeline rather than being one
+unit of work.
+
+Call `/desk/org-settings/plan-stages/check` first; it counts and costs
+nothing. A second press inside the hour buys nothing (the per-deal
+cooldown), and a press while a sweep is running returns
+`stopped: "already_running"` having written nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.limit` | `integer \| null` | no | Plan at most this many deals in this press. Omitted means up to the daily cap. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.runDeskPlanStageSweep();
+```
+
+---
+
+<a id="op-scoredeskemail"></a>
+
+### `g8.api.desk.scoreDeskEmail(input)`
+
+**Score Desk Email**
+
+- HTTP: `POST /api/v1/desk/email-score`
+- operationId: `score_desk_email_desk_email_score_post` (also callable as `g8.api.call("score_desk_email_desk_email_score_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `deals:run`
+
+Score a draft 0-100: heuristics for 60%, a model read for 40%.
+
+Never fails for model reasons - with the org's `ai_briefs` switch off, or
+the model unavailable, it returns the heuristic score alone rather than an
+error. So a 200 here does not prove the AI half ran.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskEmailScoreRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskEmailScoreRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | max length 50000 |
+| `body.contact_name` | `string \| null` | no | Recipient name, used for the personalisation subscore. max length 200 |
+| `body.subject` | `string` | no | default `""`, max length 1000 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.desk.scoreDeskEmail({ body: { body: "example" } });
+```
+
+---
+
+<a id="op-sendcommitteelinkedininvite"></a>
+
+### `g8.api.desk.sendCommitteeLinkedinInvite(input)`
+
+**Send Committee Linkedin Invite**
+
+- HTTP: `POST /api/v1/desk/accounts/{account_id}/committee/{contact_id}/linkedin-invite`
+- operationId: `send_committee_linkedin_invite_desk_accounts__account_id__committee__contact_id__linkedin_invite_post` (also callable as `g8.api.call("send_committee_linkedin_invite_desk_accounts__account_id__committee__contact_id__linkedin_invite_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+REACHES A REAL PERSON on LinkedIn, from the rep's own account.
+
+Costs no credits, and that is not the point: a connection request arrives
+in someone's notifications under a named human's identity and CANNOT BE
+WITHDRAWN. That is why it is tiered alongside the sends rather than with
+the writes.
+
+The sender is the rep's OWN claimed LinkedIn account, resolved strictly -
+it fails closed rather than falling back to whichever account the org
+connected first. Claim one with `PUT /desk/linkedin-sender`.
+
+409 on every refusal, with nothing queued: no sender picked, the account is
+not connected, the person is not on this committee, or an invite is already
+queued for them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `path.contact_id` | `integer` | yes | The committee member to invite. |
+| `body` | `CommitteeLinkedInInviteRequest` | yes | Request body; fields below. |
+
+Body fields (`CommitteeLinkedInInviteRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.note` | `string \| null` | no | Optional invite note. Capped by LinkedIn at 300 characters. max length 300 |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.sendCommitteeLinkedinInvite({ path: { account_id: 1, contact_id: 123 }, body: {} });
+```
+
+---
+
+<a id="op-senddeskreply"></a>
+
+### `g8.api.desk.sendDeskReply(input)`
+
+**Send Desk Reply**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/send-reply`
+- operationId: `send_desk_reply_desk_decisions__decision_id__send_reply_post` (also callable as `g8.api.call("send_desk_reply_desk_decisions__decision_id__send_reply_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+SENDS AN EMAIL to a real person, then resolves the card.
+
+Not idempotent, and it cannot be: the inbox send path carries no request
+id and no dedupe key. What protects a caller instead is the CARD: it is
+claimed before the send, guarded on still being pending, so only one
+request can win and a second gets a 409 having sent nothing.
+
+A retry after a timeout is therefore safe in the usual case and silent in
+one: a crash between the claim and the send leaves a resolved card whose
+mail never went. That is deliberate - recoverable by a human, unlike a
+duplicate email, which cannot be recalled.
+
+The opt-out check runs AGAIN here. `reply-target` already asked, but that
+answer is as old as the caller's editing session and a STOP that arrived
+meanwhile must not be sent through.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+| `body` | `DeskSendReplyRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskSendReplyRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | The reply body. Reaches a real person. min length 1 |
+| `body.subject` | `string \| null` | no | max length 500 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.sendDeskReply({ path: { decision_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+<a id="op-senddesksms"></a>
+
+### `g8.api.desk.sendDeskSms(input)`
+
+**Send Desk Sms**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/send-sms`
+- operationId: `send_desk_sms_desk_decisions__decision_id__send_sms_post` (also callable as `g8.api.call("send_desk_sms_desk_decisions__decision_id__send_sms_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+SENDS A TEXT MESSAGE to a real phone, then resolves the card.
+
+Carrier spend, and unrecallable once gone. Same claim-then-send ordering
+and the same re-run of the opt-out check as `send-reply` - see that
+docstring for why a retry is safe and where it is not.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+| `body` | `DeskSendSmsRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskSendSmsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | The message. Reaches a real phone and costs carrier spend. min length 1, max length 1600 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.sendDeskSms({ path: { decision_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+<a id="op-startdeskbatch"></a>
+
+### `g8.api.desk.startDeskBatch(input)`
+
+**Start Desk Batch**
+
+- HTTP: `POST /api/v1/desk/batch/start`
+- operationId: `start_desk_batch_desk_batch_start_post` (also callable as `g8.api.call("start_desk_batch_desk_batch_start_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Freeze a ranked slice of the queue into today's batch.
+
+This is what makes the day finite. Cards added to the queue afterwards do
+NOT join the batch on their own - use `/batch/pull` to take more.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskBatchStartRequest` | yes | Request body; fields below. |
+
+Body fields (`DeskBatchStartRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.item_ids` | `Array<string (uuid)>` | yes | Decision ids to freeze into the batch. 1-80 - the cap is the app's. min items 1, max items 80 |
+| `body.tz_offset` | `integer` | no | The rep's UTC offset in MINUTES (local = UTC + tz_offset). A batch is scoped to the rep's local day, so a wrong offset returns yesterday's batch or starts a second one. default `0`, min -840, max 840 |
+
+**Returns** `ApiResponse_DeskBatch_`: the envelope `{ data: DeskBatch, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DeskBatch` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `completed` | `integer \| null` | no |  |
+| `completed_at` | `string (date-time) \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `item_ids` | `Array<string>` | no |  |
+| `remaining` | `integer \| null` | no |  |
+| `started_at` | `string (date-time) \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `total` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.desk.startDeskBatch({ body: { item_ids: ["00000000-0000-0000-0000-000000000000"] } });
+```
+
+---
+
+<a id="op-undodeskdecision"></a>
+
+### `g8.api.desk.undoDeskDecision(input)`
+
+**Undo Desk Decision**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/undo`
+- operationId: `undo_desk_decision_desk_decisions__decision_id__undo_post` (also callable as `g8.api.call("undo_desk_decision_desk_decisions__decision_id__undo_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Undo an AUTO-EXECUTED decision.
+
+This is the autopilot escape hatch, not a general undo: it reverses
+something the desk did on the rep's behalf. Reversing a card the rep
+resolved themselves is not what this does.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**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
+const result = await g8.api.desk.undoDeskDecision({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-unsnoozedeskdecision"></a>
+
+### `g8.api.desk.unsnoozeDeskDecision(input)`
+
+**Unsnooze Desk Decision**
+
+- HTTP: `POST /api/v1/desk/decisions/{decision_id}/unsnooze`
+- operationId: `unsnooze_desk_decision_desk_decisions__decision_id__unsnooze_post` (also callable as `g8.api.call("unsnooze_desk_decision_desk_decisions__decision_id__unsnooze_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Wake a snoozed card now, restoring it to the pending queue.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.decision_id` | `string` | yes | Decision id (UUID). |
+
+**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
+const result = await g8.api.desk.unsnoozeDeskDecision({ path: { decision_id: "id" } });
+```
+
+---
+
+<a id="op-updateaccountplanstep"></a>
+
+### `g8.api.desk.updateAccountPlanStep(input)`
+
+**Update Account Plan Step**
+
+- HTTP: `PUT /api/v1/desk/accounts/{account_id}/plan/steps/{step_id}`
+- operationId: `update_account_plan_step_desk_accounts__account_id__plan_steps__step_id__put` (also callable as `g8.api.call("update_account_plan_step_desk_accounts__account_id__plan_steps__step_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Approve, reject or edit ONE step on the latest plan version.
+
+The only in-place edit on this surface. Approving a step does not SEND it -
+it marks it ready, and the desk raises it as a card when its time comes.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.account_id` | `integer` | yes | The account's mashup company id (`cb_account_plans.account_id`). |
+| `path.step_id` | `string` | yes | Step id, as carried on the plan. |
+| `body` | `AccountPlanStepUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`AccountPlanStepUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.action` | `"approve" \| "reject" \| "edit"` | yes |  |
+| `body.draft_content` | `string \| null` | no |  |
+| `body.scheduled_at` | `string \| null` | no |  |
+
+**Returns** `ApiResponse_AccountPlanPayload_`: the envelope `{ data: AccountPlanPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.updateAccountPlanStep({
+  path: { account_id: 1, step_id: "id" },
+  body: { action: "approve" },
+});
+```
+
+---
+
+<a id="op-updatedeskautonomy"></a>
+
+### `g8.api.desk.updateDeskAutonomy(input)`
+
+**Update Desk Autonomy**
+
+- HTTP: `PUT /api/v1/desk/autonomy`
+- operationId: `update_desk_autonomy_desk_autonomy_put` (also callable as `g8.api.call("update_desk_autonomy_desk_autonomy_put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+Decide what the desk may do WITHOUT asking this rep first.
+
+This is not a preference. A lane of `autopilot` means the desk executes
+that decision type on the rep's behalf, and the types that can be automated
+include ones that reach a real person - which is why `POST /desk/decisions/
+{id}/undo` exists at all, and why this operation is not tiered a plain
+`write`.
+
+`lanes` MERGES into the stored map rather than replacing it, and a lane
+asking for autopilot on a type with no executor is downgraded rather than
+refused - so a bulk save echoing back a stale lane still succeeds. An
+omitted `autonomy_families` leaves the family answers alone; an explicit
+`{}` clears them.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskAutonomyUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskAutonomyUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.lanes` | `Record<string, string>` | yes | Map of decision_type -> lane (autopilot/approve/off). |
+| `body.autonomy_families` | `Record<string, string> \| null` | no | Map of lane family -> lane (plan_work/outreach/hygiene_and_alerts). Omit to leave family answers untouched; send `{}` to clear them. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.updateDeskAutonomy({ body: { lanes: {} } });
+```
+
+---
+
+<a id="op-updatedesklinkedinsender"></a>
+
+### `g8.api.desk.updateDeskLinkedinSender(input)`
+
+**Update Desk Linkedin Sender**
+
+- HTTP: `PUT /api/v1/desk/linkedin-sender`
+- operationId: `update_desk_linkedin_sender_desk_linkedin_sender_put` (also callable as `g8.api.call("update_desk_linkedin_sender_desk_linkedin_sender_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Claim a LinkedIn account for this rep, or release the claim with null.
+
+The claim is EXCLUSIVE and enforced by unique constraints, not by a
+permission: claiming an account a colleague holds is a 409. Sending null
+gives the claim up, which is the only way to hand an account over.
+
+No admin gate, deliberately, and the app says why: this is a per-user
+identity rather than an org decision, and an admin permission here would
+stop reps doing the one thing they were told to do.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskLinkedInSenderUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskLinkedInSenderUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.provider_member_id` | `string \| null` | no | The LinkedIn account to claim. NULL releases the current claim. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.updateDeskLinkedinSender({ body: {} });
+```
+
+---
+
+<a id="op-updatedesklistgoal"></a>
+
+### `g8.api.desk.updateDeskListGoal(input)`
+
+**Update Desk List Goal**
+
+- HTTP: `PUT /api/v1/desk/list-goals`
+- operationId: `update_desk_list_goal_desk_list_goals_put` (also callable as `g8.api.call("update_desk_list_goal_desk_list_goals_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Set or clear ONE list's daily dial target.
+
+Unlike `/desk/list-priority` this is a single-list edit, and a null
+`target` CLEARS the goal rather than setting it to zero - a cleared goal
+stops the counter, a zero would be a goal that is already met.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskListGoalUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskListGoalUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_id` | `integer` | yes | The dial list this target belongs to. |
+| `body.target` | `integer \| null` | no | Dials per day. NULL CLEARS the target rather than setting zero. min 1 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.updateDeskListGoal({ body: { audience_id: 123 } });
+```
+
+---
+
+<a id="op-updatedesklistgroupoverride"></a>
+
+### `g8.api.desk.updateDeskListGroupOverride(input)`
+
+**Update Desk List Group Override**
+
+- HTTP: `PUT /api/v1/desk/list-group-override`
+- operationId: `update_desk_list_group_override_desk_list_group_override_put` (also callable as `g8.api.call("update_desk_list_group_override_desk_list_group_override_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Set the rep's band moves. THE WHOLE MAP, not one entry.
+
+Per rep, per org. The stored value is echoed back rather than the submitted
+one, so the response is what a GET would return.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskListGroupOverrideUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskListGroupOverrideUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.overrides` | `Record<string, "form" \| "warm" \| "cold">` | no | Dial-list id -> band (`form`, `warm` or `cold`). REPLACES every stored move. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.updateDeskListGroupOverride({ body: {} });
+```
+
+---
+
+<a id="op-updatedesklistpriority"></a>
+
+### `g8.api.desk.updateDeskListPriority(input)`
+
+**Update Desk List Priority**
+
+- HTTP: `PUT /api/v1/desk/list-priority`
+- operationId: `update_desk_list_priority_desk_list_priority_put` (also callable as `g8.api.call("update_desk_list_priority_desk_list_priority_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `deals:write`
+
+Set the rep's dial-list order. THE WHOLE ORDER.
+
+This REPLACES the stored order rather than merging into it: sending one id
+pins that list and unpins every other, and sending `[]` clears them all.
+The field name reads like an append, which is exactly why it is said here.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskListPriorityUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskListPriorityUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.audience_ids` | `Array<integer>` | no | Dial-list (audience) ids, most important first. REPLACES the whole order - an empty list clears every pin. |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.desk.updateDeskListPriority({ body: {} });
+```
+
+---
+
+<a id="op-updatedeskorgsettings"></a>
+
+### `g8.api.desk.updateDeskOrgSettings(input)`
+
+**Update Desk Org Settings**
+
+- HTTP: `PUT /api/v1/desk/org-settings`
+- operationId: `update_desk_org_settings_desk_org_settings_put` (also callable as `g8.api.call("update_desk_org_settings_desk_org_settings_put", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `deals:run`
+
+Update org-level desk settings. PARTIAL - unset fields are untouched.
+
+Requires `settings:write`, declared on this route because the app's own
+gate is a `Depends`-defaulted PARAMETER of the handler and a direct call
+resolves nothing.
+
+THIS IS THE ORG'S ON SWITCH, AND ITS SPEND CAPS. Saving here registers the
+org on the desk worker's poll list - and saving every decision off
+unregisters it - so this one call starts or stops the desk producing work
+for the whole organisation. It also carries `max_auto_account_plans_per_day`,
+`max_account_replans_per_day` and `max_skill_plans_per_day`, which are
+daily caps on CHARGED model calls, and `desk_acts_on_signals`,
+`desk_drafts_with_ai` and `stalled_deal_send_email`, which let the desk act
+and email on its own. A plain `write` would make raising an org's spend cap
+the same grant as renaming a record.
+
+400 with the reason on anything the settings validator refuses, including
+an empty body - "no settings provided" is an error here rather than a
+silent no-op.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `DeskOrgSettingsUpdate` | yes | Request body; fields below. |
+
+Body fields (`DeskOrgSettingsUpdate`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.contact_update_planned_deals_only` | `boolean \| null` | no |  |
+| `body.daily_action_target` | `integer \| null` | no | min 0, max 200 |
+| `body.desk_acts_on_signals` | `boolean \| null` | no |  |
+| `body.desk_drafts_with_ai` | `boolean \| null` | no |  |
+| `body.desk_escalates_to_managers` | `boolean \| null` | no |  |
+| `body.desk_keeps_crm_tidy` | `boolean \| null` | no |  |
+| `body.desk_writes_deal_plans` | `boolean \| null` | no |  |
+| `body.enrichment_win_fields` | `Array<string> \| null` | no | max items 9 |
+| `body.fallback_owner_emails` | `Array<string> \| null` | no | max items 20 |
+| `body.lead_sla_minutes` | `integer \| null` | no | min 0, max 240 |
+| `body.max_account_replans_per_day` | `integer \| null` | no | DAILY CAP on charged account re-plans. min 0, max 100 |
+| `body.max_auto_account_plans_per_day` | `integer \| null` | no | DAILY CAP on charged auto account plans. min 0, max 100 |
+| `body.max_cards_per_generator_per_day` | `integer \| null` | no | min 1, max 500 |
+| `body.max_skill_plans_per_day` | `integer \| null` | no | DAILY CAP on charged skill plans. min 0, max 100 |
+| `body.no_reply_channels` | `Array<string> \| null` | no | max items 1 |
+| `body.no_reply_threshold_days` | `integer \| null` | no | min 1, max 60 |
+| `body.overdue_self_task_enabled` | `boolean \| null` | no |  |
+| `body.overdue_task_max_age_days` | `integer \| null` | no | min 0, max 365 |
+| `body.pipeline_target_quarterly` | `integer \| null` | no | min 0 |
+| `body.plan_required_stage_ids` | `Array<string> \| null` | no | max items 20 |
+| `body.reps_may_fire_workflows` | `boolean \| null` | no |  |
+| `body.signal_policies` | `Record<string, DeskSignalPolicy> \| null` | no |  |
+| `body.signals_enabled` | `Record<string, boolean> \| null` | no | Per-signal kill switches. `ai_briefs` is the desk-wide LLM-spend gate and `morning_kickoff` gates the daily briefing. |
+| `body.stalled_deal_approve_after_days` | `integer \| null` | no | min 1, max 60 |
+| `body.stalled_deal_enabled` | `boolean \| null` | no |  |
+| `body.stalled_deal_fallback_manager_user_id` | `string \| null` | no | max length 320 |
+| `body.stalled_deal_manager_user_id` | `string \| null` | no | max length 320 |
+| `body.stalled_deal_min_amount` | `integer \| null` | no | min 0 |
+| `body.stalled_deal_min_deal_age_days` | `integer \| null` | no | min 0, max 365 |
+| `body.stalled_deal_reassign_to_user_id` | `string \| null` | no | max length 320 |
+| `body.stalled_deal_reminder_after_hours` | `integer \| null` | no | min 1, max 168 |
+| `body.stalled_deal_require_activity_evidence` | `boolean \| null` | no |  |
+| `body.stalled_deal_send_email` | `boolean \| null` | no | Let the stalled-deal escalation EMAIL the manager. |
+| `body.stalled_deal_skip_crm_synced_transfer` | `boolean \| null` | no |  |
+| `body.stalled_deal_stage_ids` | `Array<string (uuid)> \| null` | no | max items 200 |
+| `body.stalled_deal_undo_window_minutes` | `integer \| null` | no | min 0, max 1440 |
+| `body.stalled_deal_warn_after_days` | `integer \| null` | no | min 1, max 60 |
+
+**Returns** `ApiResponse_DeskPayload_`: the envelope `{ data: DeskPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.desk.updateDeskOrgSettings({ body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-accountplanstep"></a>
+
+### `AccountPlanStep`
+
+One step in a plan: who to reach, on what channel, when, and why now. `extra="allow"` mirrors the app's own model, which is also open - the step shape carries per-channel extras the desk adds as it learns new channels, and a closed mirror would DROP them on the way in rather than pass them through. `approval_status` is closed because it reaches a real `Literal` inside the handler: a free value would raise there and escape as a 500 instead of a 422 naming the four states.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `step_id` | `string` | yes | Caller-assigned id, stable across versions. |
+| `approval_status` | `"pending" \| "approved" \| "rejected" \| "edited"` | no | default `"pending"` |
+| `channel` | `string \| null` | no |  |
+| `contact_id` | `unknown \| null` | no | Committee member this step is aimed at. |
+| `draft_content` | `string \| null` | no |  |
+| `scheduled_at` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `why_now` | `string \| null` | no |  |
+
+<a id="type-committeememberinput"></a>
+
+### `CommitteeMemberInput`
+
+A contact to put on the buying committee.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contact_id` | `integer` | yes |  |
+| `role` | `string \| null` | no | Their part in the decision, e.g. "champion". |
+
+<a id="type-deskdecision"></a>
+
+### `DeskDecision`
+
+One card in the queue: something the desk thinks a rep should do next.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `created_at` | `string (date-time) \| null` | no |  |
+| `decision_type` | `string \| null` | no | What kind of action this card is asking for. |
+| `entity_id` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `id` | `string \| null` | no |  |
+| `priority` | `number \| null` | no |  |
+| `resolved_at` | `string (date-time) \| null` | no |  |
+| `snoozed_until` | `string (date-time) \| null` | no |  |
+| `source` | `string \| null` | no | Exact signal id, e.g. "form_submitted". |
+| `source_group` | `string \| null` | no | Signal family, e.g. "forms". |
+| `status` | `string \| null` | no | pending, approved, edited, skipped, deferred, snoozed, done_already. |
+| `summary` | `string \| null` | no |  |
+| `title` | `string \| null` | no |  |
+
+<a id="type-desksignalpolicy"></a>
+
+### `DeskSignalPolicy`
+
+Per-signal policy override. Mirrors the app's `DeskSignalPolicyUpdate`. Open (`extra="allow"`) rather than pinned: this nests inside a JSONB settings blob the desk extends per signal family, and a closed mirror would reject a key the app has just learned to read.
+
+Type: `Record<string, unknown>`.