@graph8/sdk 0.308.1 → 0.358.0

package/docs/api/seo.md

@@ -2,7 +2,7 @@
 
 # `g8.api.seo`: SEO
 
-14 operations (8 read, 2 write, 4 billable).
+22 operations (14 read, 4 write, 4 billable).
 
 No hand-written client covers this area. Call it through `g8.api.seo.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
 
@@ -22,14 +22,22 @@ Exact TypeScript types for every operation on this page, and every schema they u
 
 | Call | HTTP | Tier | Scope | Summary |
 |---|---|---|---|---|
+| [`claimSeoFix`](#op-claimseofix) | `POST /api/v1/seo/fixes/{fix_id}/claim` | write | `intent:write` | Claim Seo Fix |
+| [`completeSeoFix`](#op-completeseofix) | `POST /api/v1/seo/fixes/{fix_id}/complete` | write | `intent:write` | Complete Seo Fix |
+| [`getSeoAgentHandoff`](#op-getseoagenthandoff) | `GET /api/v1/seo/fixes/agent-handoff` | read | `intent:read` | Get Seo Agent Handoff |
 | [`getSeoAudit`](#op-getseoaudit) | `GET /api/v1/seo/audits/{audit_id}` | read | `intent:read` | Get Seo Audit |
 | [`getSeoAuditIssues`](#op-getseoauditissues) | `GET /api/v1/seo/audits/{audit_id}/issues` | read | `intent:read` | Get Seo Audit Issues |
 | [`getSeoDomainBacklinks`](#op-getseodomainbacklinks) | `GET /api/v1/seo/domains/{domain}/backlinks` | billable | `intent:run` | Get Seo Domain Backlinks |
 | [`getSeoDomainOverview`](#op-getseodomainoverview) | `GET /api/v1/seo/domains/{domain}/overview` | billable | `intent:run` | Get Seo Domain Overview |
+| [`getSeoFixPack`](#op-getseofixpack) | `GET /api/v1/seo/fixes/{fix_id}/pack` | read | `intent:read` | Get Seo Fix Pack |
+| [`getSeoPage360`](#op-getseopage360) | `GET /api/v1/seo/pages/360/detail` | read | `intent:read` | Get Seo Page 360 |
 | [`getSeoRankHistory`](#op-getseorankhistory) | `GET /api/v1/seo/rank-tracking/{keyword_id}/history` | read | `intent:read` | Get Seo Rank History |
+| [`getSeoToday`](#op-getseotoday) | `GET /api/v1/seo/today` | read | `intent:read` | Get Seo Today |
 | [`getSeoTrackedDomain`](#op-getseotrackeddomain) | `GET /api/v1/seo/domains/tracked/{domain}` | read | `intent:read` | Get Seo Tracked Domain |
 | [`listSeoAudits`](#op-listseoaudits) | `GET /api/v1/seo/audits` | read | `intent:read` | List Seo Audits |
 | [`listSeoDomainPages`](#op-listseodomainpages) | `GET /api/v1/seo/domains/tracked/{domain}/pages` | read | `intent:read` | List Seo Domain Pages |
+| [`listSeoFixes`](#op-listseofixes) | `GET /api/v1/seo/fixes` | read | `intent:read` | List Seo Fixes |
+| [`listSeoPages360`](#op-listseopages360) | `GET /api/v1/seo/pages/360` | read | `intent:read` | List Seo Pages 360 |
 | [`listSeoTrackedDomains`](#op-listseotrackeddomains) | `GET /api/v1/seo/domains/tracked` | read | `intent:read` | List Seo Tracked Domains |
 | [`listSeoTrackedKeywords`](#op-listseotrackedkeywords) | `GET /api/v1/seo/rank-tracking` | read | `intent:read` | List Seo Tracked Keywords |
 | [`removeSeoTrackedKeywords`](#op-removeseotrackedkeywords) | `POST /api/v1/seo/rank-tracking/keywords/remove` | write | `intent:write` | Remove Seo Tracked Keywords |
@@ -39,6 +47,152 @@ Exact TypeScript types for every operation on this page, and every schema they u
 
 ---
 
+<a id="op-claimseofix"></a>
+
+### `g8.api.seo.claimSeoFix(input)`
+
+**Claim Seo Fix**
+
+- HTTP: `POST /api/v1/seo/fixes/{fix_id}/claim`
+- operationId: `claim_seo_fix_seo_fixes__fix_id__claim_post` (also callable as `g8.api.call("claim_seo_fix_seo_fixes__fix_id__claim_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `intent:write`
+
+SPENDS NOTHING. Claim one queued fix for your coding agent.
+
+Row-locked: if another agent already holds it the answer is 409. Claiming again with the same `agent` label
+is a no-op. A claim nobody completes expires after a few hours and the fix is offered again.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.fix_id` | `string (uuid)` | yes | A fix id from `GET /seo/fixes`. |
+| `body` | `SeoClaimFixRequest` | no | Request body; fields below. |
+
+Body fields (`SeoClaimFixRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent` | `string \| null` | no | A label for this agent, e.g. claude-code. max length 80 |
+
+**Returns** `ApiResponse_SeoClaimFixResponse_`: the envelope `{ data: SeoClaimFixResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoClaimFixResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `claim_note` | `string` | yes |  |
+| `claimed` | `boolean` | yes |  |
+| `fix` | `SeoAgentFix` | yes |  |
+| `claimed_by` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.claimSeoFix({ path: { fix_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-completeseofix"></a>
+
+### `g8.api.seo.completeSeoFix(input)`
+
+**Complete Seo Fix**
+
+- HTTP: `POST /api/v1/seo/fixes/{fix_id}/complete`
+- operationId: `complete_seo_fix_seo_fixes__fix_id__complete_post` (also callable as `g8.api.call("complete_seo_fix_seo_fixes__fix_id__complete_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `intent:write`
+
+SPENDS NOTHING. Report a claimed fix as done (with the commit or pull request) or as failed (with why).
+
+`outcome=done` needs `ref`, a commit SHA or an http(s) URL, and moves the fix to `applied`; graph8 then
+re-fetches the live page to verify it. `outcome=failed` needs `note`. 409 when the fix is not claimed by
+this agent, 422 for a missing or malformed `ref`.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.fix_id` | `string (uuid)` | yes | A fix id from `GET /seo/fixes`. |
+| `body` | `SeoCompleteFixRequest` | yes | Request body; fields below. |
+
+Body fields (`SeoCompleteFixRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.agent` | `string \| null` | no | max length 80 |
+| `body.note` | `string` | no | default `""`, max length 2000 |
+| `body.outcome` | `"done" \| "failed"` | no | default `"done"` |
+| `body.ref` | `string \| null` | no | Commit SHA or commit/pull request URL. max length 500 |
+
+**Returns** `ApiResponse_SeoCompleteFixResponse_`: the envelope `{ data: SeoCompleteFixResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoCompleteFixResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fix_id` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `applied_ref` | `string \| null` | no |  |
+| `verification` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.completeSeoFix({ path: { fix_id: "00000000-0000-0000-0000-000000000000" }, body: {} });
+```
+
+---
+
+<a id="op-getseoagenthandoff"></a>
+
+### `g8.api.seo.getSeoAgentHandoff(input?)`
+
+**Get Seo Agent Handoff**
+
+- HTTP: `GET /api/v1/seo/fixes/agent-handoff`
+- operationId: `get_seo_agent_handoff_seo_fixes_agent_handoff_get` (also callable as `g8.api.call("get_seo_agent_handoff_seo_fixes_agent_handoff_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. AGENTS.md and CLAUDE.md for the queued fixes plus one-line MCP setup for Claude Code and Cursor.
+
+The setup lines connect the coding agent to graph8 over MCP so it can list, claim and complete fixes itself.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string \| null` | no | Only fixes for this domain. |
+
+**Returns** `ApiResponse_SeoAgentHandoff_`: the envelope `{ data: SeoAgentHandoff, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAgentHandoff` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `files` | `Record<string, string>` | yes |  |
+| `fix_count` | `integer` | yes |  |
+| `setup` | `SeoAgentSetup` | yes |  |
+| `domain` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoAgentHandoff();
+```
+
+---
+
 <a id="op-getseoaudit"></a>
 
 ### `g8.api.seo.getSeoAudit(input)`
@@ -218,6 +372,89 @@ const result = await g8.api.seo.getSeoDomainOverview({ path: { domain: "acme.com
 
 ---
 
+<a id="op-getseofixpack"></a>
+
+### `g8.api.seo.getSeoFixPack(input)`
+
+**Get Seo Fix Pack**
+
+- HTTP: `GET /api/v1/seo/fixes/{fix_id}/pack`
+- operationId: `get_seo_fix_pack_seo_fixes__fix_id__pack_get` (also callable as `g8.api.call("get_seo_fix_pack_seo_fixes__fix_id__pack_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The pack for one fix: its instructions, any generated files, and AGENTS.md / CLAUDE.md.
+
+404 for a fix this organisation does not have.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.fix_id` | `string (uuid)` | yes | A fix id from `GET /seo/fixes`. |
+
+**Returns** `ApiResponse_SeoAgentFixPack_`: the envelope `{ data: SeoAgentFixPack, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAgentFixPack` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `agents_md` | `string` | yes |  |
+| `claude_md` | `string` | yes |  |
+| `fix` | `SeoAgentFix` | yes |  |
+| `files` | `Record<string, string>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoFixPack({ path: { fix_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-getseopage360"></a>
+
+### `g8.api.seo.getSeoPage360(input)`
+
+**Get Seo Page 360**
+
+- HTTP: `GET /api/v1/seo/pages/360/detail`
+- operationId: `get_seo_page_360_seo_pages_360_detail_get` (also callable as `g8.api.call("get_seo_page_360_seo_pages_360_detail_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. One page in full: Search Console, vitals, indexing, visitors, companies, top queries, open fixes.
+
+404 when the page has not been analysed yet.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string` | yes | A tracked domain. |
+| `query.url` | `string` | yes | The page URL or path, e.g. /pricing. |
+
+**Returns** `ApiResponse_SeoPage360_`: the envelope `{ data: SeoPage360, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoPage360` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `fixes` | `Array<Record<string, unknown>>` | no |  |
+| `queries` | `Array<Record<string, unknown>>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoPage360({ query: { domain: "acme.com", url: "https://example.com" } });
+```
+
+---
+
 <a id="op-getseorankhistory"></a>
 
 ### `g8.api.seo.getSeoRankHistory(input)`
@@ -261,6 +498,56 @@ const result = await g8.api.seo.getSeoRankHistory({ path: { keyword_id: "0000000
 
 ---
 
+<a id="op-getseotoday"></a>
+
+### `g8.api.seo.getSeoToday(input?)`
+
+**Get Seo Today**
+
+- HTTP: `GET /api/v1/seo/today`
+- operationId: `get_seo_today_seo_today_get` (also callable as `g8.api.call("get_seo_today_seo_today_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. Today in Signals > SEO: health, KPIs, what changed, the approval queue and open alerts.
+
+Every modelled number carries `confidence` (`measured`, `estimated` or `partial`). Sources that are not
+connected degrade to a card saying so; `sources` lists which answered.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string \| null` | no | A tracked domain. Omit for the primary one. |
+
+**Returns** `ApiResponse_SeoToday_`: the envelope `{ data: SeoToday, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoToday` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `alerts` | `Array<SeoTodayAlert>` | yes |  |
+| `approval_queue` | `SeoApprovalQueue` | yes |  |
+| `briefing` | `Array<SeoTodayCard>` | yes |  |
+| `end_of_day` | `SeoEndOfDay` | yes |  |
+| `generated_at` | `string` | yes |  |
+| `kpis` | `Array<SeoTodayKpi>` | yes |  |
+| `movers` | `Array<SeoMover>` | yes |  |
+| `setup` | `SeoSetupChecklist` | yes |  |
+| `domain` | `string \| null` | no |  |
+| `health_score` | `integer \| null` | no |  |
+| `sources` | `Record<string, boolean>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.getSeoToday();
+```
+
+---
+
 <a id="op-getseotrackeddomain"></a>
 
 ### `g8.api.seo.getSeoTrackedDomain(input)`
@@ -412,6 +699,102 @@ const result = await g8.api.seo.listSeoDomainPages({ path: { domain: "acme.com"
 
 ---
 
+<a id="op-listseofixes"></a>
+
+### `g8.api.seo.listSeoFixes(input?)`
+
+**List Seo Fixes**
+
+- HTTP: `GET /api/v1/seo/fixes`
+- operationId: `list_seo_fixes_seo_fixes_get` (also callable as `g8.api.call("list_seo_fixes_seo_fixes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The SEO fixes queued for a coding agent, with exact instructions and code.
+
+Only fixes the organisation approved for its coding agent appear (status `ready_for_agent`), plus any whose
+claim expired. Each carries the page, ordered steps, the snippets to add and how success is checked.
+`agents_md` is the same list as an AGENTS.md document.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string \| null` | no | Only fixes for this domain. |
+| `query.limit` | `integer` | no | Fixes to return, most severe first. default `20` |
+
+**Returns** `ApiResponse_SeoAgentFixQueue_`: the envelope `{ data: SeoAgentFixQueue, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoAgentFixQueue` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `agents_md` | `string` | yes |  |
+| `count` | `integer` | yes |  |
+| `fixes` | `Array<SeoAgentFix>` | yes |  |
+| `domain` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoFixes();
+```
+
+---
+
+<a id="op-listseopages360"></a>
+
+### `g8.api.seo.listSeoPages360(input)`
+
+**List Seo Pages 360**
+
+- HTTP: `GET /api/v1/seo/pages/360`
+- operationId: `list_seo_pages_360_seo_pages_360_get` (also callable as `g8.api.call("list_seo_pages_360_seo_pages_360_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `intent:read`
+
+SPENDS NOTHING. The Page360 grid: every page with Search Console, vitals, visitors, companies and open fixes.
+
+`filter=money` keeps pages that sit on a closed-won or open-deal path (an inference, labelled estimated).
+`gsc_connected` is false until Search Console is linked; the rows then carry visitor data only.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.domain` | `string` | yes | A tracked domain. |
+| `query.q` | `string` | no | Only pages whose path contains this text. default `""` |
+| `query.sort` | `"pageviews" \| "clicks" \| "position" \| "companies" \| "pipeline" \| "issues"` | no | default `"pageviews"` |
+| `query.order` | `"asc" \| "desc"` | no | default `"desc"` |
+| `query.filter` | `"all" \| "money" \| "decay" \| "fixes" \| "companies" \| "slow"` | no | default `"all"` |
+| `query.limit` | `integer` | no | Rows to return. default `50` |
+| `query.offset` | `integer` | no | Rows to skip. default `0` |
+
+**Returns** `ApiResponse_SeoPages360_`: the envelope `{ data: SeoPages360, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SeoPages360` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `gsc_connected` | `boolean` | yes |  |
+| `limit` | `integer` | yes |  |
+| `offset` | `integer` | yes |  |
+| `rows` | `Array<Record<string, unknown>>` | yes |  |
+| `total` | `integer` | yes |  |
+| `last_sync_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.seo.listSeoPages360({ query: { domain: "acme.com" } });
+```
+
+---
+
 <a id="op-listseotrackeddomains"></a>
 
 ### `g8.api.seo.listSeoTrackedDomains(input?)`
@@ -642,7 +1025,7 @@ Body fields (`SeoSaveTrackedKeywordsRequest`):
 |---|---|---|---|
 | `body.domain` | `string` | yes | min length 3, max length 255 |
 | `body.keywords` | `Array<SeoTrackKeywordItem>` | yes | min items 1, max items 100 |
-| `body.cadence` | `"daily" \| "weekly"` | no | default `"daily"` |
+| `body.cadence` | `"daily" \| "weekly" \| "manual"` | no | default `"daily"` |
 | `body.language_code` | `string` | no | default `"en"`, max length 10 |
 | `body.location_code` | `integer` | no | default `2840` |
 
@@ -743,6 +1126,48 @@ const result = await g8.api.seo.startSeoAudit({ body: { domain: "acme.com" } });
 
 Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
 
+<a id="type-seoagentfix"></a>
+
+### `SeoAgentFix`
+
+One fix with exact instructions: the page, the steps, the code to add and how success is checked.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `acceptance` | `Array<string>` | yes |  |
+| `category` | `string` | yes |  |
+| `domain` | `string` | yes |  |
+| `fix_id` | `string` | yes |  |
+| `severity` | `string` | yes |  |
+| `status` | `string` | yes |  |
+| `steps` | `Array<string>` | yes |  |
+| `title` | `string` | yes |  |
+| `files` | `Record<string, string>` | no |  |
+| `snippets` | `Array<SeoAgentSnippet>` | no |  |
+| `target_url` | `string \| null` | no |  |
+| `why` | `string` | no | default `""` |
+
+<a id="type-seoagentsetup"></a>
+
+### `SeoAgentSetup`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `claude_code` | `string` | yes |  |
+| `cursor` | `SeoAgentSetupCursor` | yes |  |
+| `mcp_url` | `string` | yes |  |
+| `prompt` | `string` | yes |  |
+| `tools` | `Array<string>` | yes |  |
+
+<a id="type-seoapprovalqueue"></a>
+
+### `SeoApprovalQueue`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `count` | `integer` | yes |  |
+| `items` | `Array<SeoApprovalItem>` | yes |  |
+
 <a id="type-seoauditissue"></a>
 
 ### `SeoAuditIssue`
@@ -801,6 +1226,17 @@ Mirrors `DomainPageDTO`.
 | `top_keyword` | `string \| null` | no |  |
 | `traffic_change_30d` | `number \| null` | no |  |
 
+<a id="type-seoendofday"></a>
+
+### `SeoEndOfDay`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `ask` | `string` | yes |  |
+| `risk` | `string` | yes |  |
+| `win` | `string` | yes |  |
+| `work_channel_id` | `string \| null` | no |  |
+
 <a id="type-seokeywordrow"></a>
 
 ### `SeoKeywordRow`
@@ -816,6 +1252,21 @@ Mirrors `KeywordRow`.
 | `keyword_difficulty` | `integer \| null` | no |  |
 | `search_volume` | `integer` | no | default `0` |
 
+<a id="type-seomover"></a>
+
+### `SeoMover`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `detail` | `string` | yes |  |
+| `kind` | `"rank_up" \| "rank_down" \| "gsc_drop" \| "gsc_gain" \| "low_ctr"` | yes |  |
+| `title` | `string` | yes |  |
+| `confidence` | `"measured" \| "estimated" \| "partial"` | no | default `"measured"` |
+| `delta` | `number \| null` | no |  |
+| `from_value` | `number \| null` | no |  |
+| `to_value` | `number \| null` | no |  |
+| `url` | `string \| null` | no |  |
+
 <a id="type-seoranksnapshot"></a>
 
 ### `SeoRankSnapshot`
@@ -828,6 +1279,59 @@ Mirrors `RankSnapshotDTO`.
 | `rank` | `integer \| null` | no |  |
 | `serp_url` | `string \| null` | no |  |
 
+<a id="type-seosetupchecklist"></a>
+
+### `SeoSetupChecklist`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `done_count` | `integer` | yes |  |
+| `items` | `Array<SeoSetupItem>` | yes |  |
+| `total` | `integer` | yes |  |
+
+<a id="type-seotodayalert"></a>
+
+### `SeoTodayAlert`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `string` | yes |  |
+| `fired_at` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `kind` | `string` | yes |  |
+| `severity` | `"critical" \| "high" \| "medium" \| "low"` | yes |  |
+| `title` | `string` | yes |  |
+| `action` | `SeoTodayAction \| null` | no |  |
+| `payload` | `Record<string, unknown>` | no |  |
+
+<a id="type-seotodaycard"></a>
+
+### `SeoTodayCard`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `SeoTodayAction` | yes |  |
+| `category` | `string` | yes |  |
+| `detail` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `severity` | `"critical" \| "high" \| "medium" \| "low"` | yes |  |
+| `title` | `string` | yes |  |
+| `confidence` | `"measured" \| "estimated" \| "partial"` | no | default `"measured"` |
+| `stake` | `string \| null` | no |  |
+
+<a id="type-seotodaykpi"></a>
+
+### `SeoTodayKpi`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `key` | `string` | yes |  |
+| `label` | `string` | yes |  |
+| `confidence` | `"measured" \| "estimated" \| "partial"` | no | default `"measured"` |
+| `delta_pct` | `number \| null` | no |  |
+| `hint` | `string \| null` | no |  |
+| `value` | `number \| null` | no |  |
+
 <a id="type-seotrackkeyworditem"></a>
 
 ### `SeoTrackKeywordItem`

package/docs/api/workflows.md

@@ -193,6 +193,14 @@ Send an `Idempotency-Key` header as well for the app-wide guard.
 Every execution in the batch is scoped to the caller's org before it is
 touched; ids belonging to another tenant are simply not found.
 
+A restart runs each workflow as it is NOW. When one has record steps or a
+record trigger, the key needs the object scopes they exercise (403
+``missing_scopes`` refuses the whole batch, nothing restarts), and only the
+workflow's owner or a graph8 admin may restart it: for any other member that
+item is reported in ``failed`` with ``owner_or_admin_required`` while the
+rest of the batch goes ahead. When graph8 cannot confirm who is an admin,
+that item is refused, never guessed, and also reported in ``failed``.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -319,6 +327,13 @@ const result = await g8.api.workflows.createWorkbench({ body: {} });
 Create a new workflow. Pins ``org_id`` and ``runtime_type='workflow'``
 server-side - the body cannot override either.
 
+The workflow's OWNER is the authenticated caller, never a body field: a
+body ``created_by`` is dropped (see ``voice_owner_headers``). Record steps
+and record triggers run with the owner's record access, so the key must hold
+the object scopes they exercise (403 ``missing_scopes``). A node or trigger
+config that carries the same key in snake_case and camelCase with values
+that disagree is refused (422 ``conflicting_node_keys``): keep one spelling.
+
 Translates the public ``config`` field to voice's internal
 ``skill_config`` before forwarding (see module docstring).
 
@@ -573,6 +588,14 @@ const result = await g8.api.workflows.diffSkillVersions({ path: { action_id: "id
 
 Trigger a workflow run. Returns ``execution_id`` for polling.
 
+A workflow with record steps or a record trigger runs them with its OWNER's
+record access, and this run's input feeds them: the key must hold the object
+scopes they exercise (403 ``missing_scopes``) and its member must own the
+workflow or administer the org (403 ``owner_or_admin_required``, from the
+workflow service, which receives the member as the verified identity). The
+saved workflow is read before the run so that check is never skipped: when
+it cannot be read, the answer is ``502`` and nothing runs.
+
 Pins ``org_id`` server-side; the caller cannot override which org's
 execution row is created. ``triggered_by`` defaults to the caller's
 user id when not supplied.
@@ -1908,6 +1931,14 @@ a paused run instead, use `POST /workflows/executions/{id}/resume`.
 The org is forwarded and voice scopes the lookup by it, so one tenant
 cannot restart another's run.
 
+A restart runs the workflow as it is NOW, with the original or new input.
+When it has record steps or a record trigger, the key needs the object
+scopes they exercise (403 ``missing_scopes``), and only the workflow's
+owner or a graph8 admin may restart it, with reused or new input (403
+``owner_or_admin_required``). When graph8 cannot confirm who is an admin the
+restart is refused, never guessed: the workflow service answers 503, which
+reaches the caller as ``502`` like its other upstream failures; retry later.
+
 **Input**
 
 | Field | Type | Required | Description |
@@ -1941,7 +1972,14 @@ const result = await g8.api.workflows.restartExecution({ path: { execution_id: "
 
 SPENDS NOTHING. Publishes the old snapshot as a NEW version, live for the
 next run - agents and workflows using the skill pick it up. Append-only, so
-the restore can itself be rolled back. Routine-managed skills refuse (403).
+the restore can itself be rolled back. Routine-managed skills refuse (403). A
+restored graph with record steps or a record trigger needs the same object
+scopes as a create or an update (403 ``missing_scopes``), a restored graph
+whose snake_case and camelCase node keys disagree is refused (422
+``conflicting_node_keys``), and a restore that changes such a workflow's
+graph is refused (403 ``owner_or_admin_required``) unless the key's member
+owns the workflow or administers the org. The version's graph is read first
+to run those checks: 404 when it cannot be found (unknown skill or version).
 
 **Input**
 
@@ -2250,7 +2288,13 @@ const result = await g8.api.workflows.updateSkillTestCase({ path: { action_id: "
 - ★ Hand-written: [`g8.workflows.update()`](../sdk-clients.md#g8-workflows-update)
 
 Update a workflow. The voice update endpoint takes ``org_id`` as a
-query param and the partial body in JSON, so we forward both.
+query param and the partial body in JSON, so we forward both. A graph with
+record steps or a record trigger needs the object scopes they exercise
+(403 ``missing_scopes``), like create, and a node or trigger config whose
+snake_case and camelCase keys disagree is refused (422
+``conflicting_node_keys``). On a workflow with record steps or a record
+trigger, only its owner or a graph8 admin may change what it runs (403
+``owner_or_admin_required``); its name and description stay editable.
 
 Translates the public ``config`` field to voice's internal
 ``skill_config`` before forwarding (see module docstring).