> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveku.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Reporting & Approvals

> The shareable client report lifecycle (create, regenerate, send, share, PDF), the implement-with-AI rail that turns SEO findings into deployed fixes behind a two-key approval, and the agent inbox where staged alerts land

Retainer work ends in two artifacts: the report the client opens, and the fix that actually shipped. This page covers both — the client report lifecycle, and the approval rail that stands between an AI-implemented fix and the client's live site.

## The client report lifecycle

A client report is a scheduled, shareable, branded results page. The marketing report covers leads, deals won, traffic, spend, SEO, rankings movement, search-term wins, AEO, local performance, and a work log; a social report covers posts, impressions, engagement, and followers.

<Steps>
  <Step title="Create — marketing_report_create">
    Takes `report_name` and `report_type` (`marketing` or `social`), plus `schedule` (`weekly` default, `monthly`, or `none` for on-demand only), `include_sections`, `delivery_config` (the recipient emails), and `domain`. Marketing reports are **public by default** — the share link is the point — and the delivery schedule is stamped so the scheduler actually delivers on cadence.
  </Step>

  <Step title="Populate — marketing_report_regenerate">
    Rebuilds the report's numbers now and stores them. The public page, the emailed summary, and the PDF all render this stored data verbatim, so **regenerating is the only way the numbers change**. Accepts `days: 7` or `30` (monthly reports usually want 30). It can take a while — the marketing assembly includes live Google Ads pulls. It never emails anyone and never advances the schedule.
  </Step>

  <Step title="Share — marketing_report_share_link">
    Returns the public URL the client opens, no login required. Read-only — if the report isn't public it returns the fix (set `is_public: true` via `marketing_report_update`) rather than silently minting a link.
  </Step>

  <Step title="Send — marketing_report_send">
    Emails the report to its recipients. Real mail lands in the client's inbox, so it's confirm-gated: the first call returns a preview with the exact recipient list and the URL that will be mailed; repeat with `confirm: true` to send. It emails the current stored numbers — regenerate first if they're stale — and requires an existing public link. Pass `recipients` to replace the stored list before sending.
  </Step>
</Steps>

Two more pieces round out the lifecycle:

* `marketing_report_update` — rename, change cadence (the schedule re-stamps so delivery stays in sync), edit the section list or recipients, toggle `is_active`, or manage the share link. `is_public: false` on a marketing report revokes the link outright; a social report keeps its token so re-enabling restores the same URL.
* `marketing_report_pdf` — the marketing report as a server-rendered PDF of the exact stored numbers, for clients who want an attachment instead of a link. If the report has never been generated it says so — regenerate first.

**Sections worth knowing**: `include_sections` for a marketing report chooses from `overview`, `web`, `ppc`, `seo`, `listings`, `social`, `email`, `calls`, `rankings`, `search_terms`, `aeo`, `local`, and `work_log` (omit for all). The `rankings` and `search_terms` sections are the win sections — rankings movement and search-term wins — and `work_log` shows the client what was actually done during the period. Social sections: `overview`, `timeseries`, `followers`, `top_posts`.

## From finding to fix: the implement rail

SEO and content findings (audit issues, listings gaps, digest items) are filed as tasks. The implement rail hands a task to the coder agent for headless implementation — and its end state is code deployed to the client's live site, which is why it runs behind **two separate keys**: one confirmation to dispatch the work, a second approval to ship it.

<Steps>
  <Step title="Pick the task — seo_task_list / seo_task_get">
    `seo_task_list` shows the task queue with an `implementable` flag (open status plus a linked website project) and an implement summary when a session already ran. Filter by `status`, `task_type` (`seo` default, `content`, or `all`), or `website_project_id`. `seo_task_get` returns one task with everything needed to decide: description, AI instructions, the resolved page anchor, and the linked project.
  </Step>

  <Step title="Key one: dispatch — seo_task_implement">
    Confirm-gated. The first call dispatches nothing — it returns a preview with the task, the target website project (name and domain), and the page anchor. Repeat with `confirm: true` to dispatch the agent turn. The agent edits the website project, typechecks, test-builds, then **stages** the production deploy for approval — it never ships on its own. A running session or an already-deployed task is refused rather than double-dispatched.
  </Step>

  <Step title="Watch — seo_task_implement_status">
    The phase machine: `idle`, `running`, `awaiting_approval` (a staged deploy is waiting — the response carries its token, summary, and expiry), `deploying`, `completed` (with the deployment URL; the task auto-completes), or `failed` (naming whether the agent run or the deploy failed). Safe to poll.
  </Step>

  <Step title="Key two: approve — agent_approval_approve">
    Also confirm-gated (see below). Approving executes the staged deploy for real. Or discard it with `agent_approval_reject` — nothing deploys and the token can never be approved afterward.
  </Step>
</Steps>

## The approval rail (`agent_approval_*`)

High-blast-radius coder-agent actions — deploying a project, committing to GitHub — are staged for approval instead of executing inline. The implement rail's production deploy parks here, and so do staged actions from coder chat sessions.

| Tool                     | What it does                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent_approval_list`    | Staged actions awaiting approval: token, action name, a human-readable summary, session id, the staged request, and expiry. Defaults to approvable rows only; `status: "all"` includes history. Match an implement-rail deploy via its `session_id` and `action: "deploy_project"`                                                                                                                                            |
| `agent_approval_get`     | Inspect one token non-destructively — tells "already handled" apart from "still approvable" before you act                                                                                                                                                                                                                                                                                                                    |
| `agent_approval_approve` | Confirm-gated: the first call returns a preview (action, summary, target project, expiry) with `requires_confirm: true`; repeat with `confirm: true` to execute. Tokens are single-use and expire. Execution can take a couple of minutes — don't retry on a timeout; re-check with `agent_approval_get` first, because the deploy may already be shipping. An optional `environment` overrides the staged deploy environment |
| `agent_approval_reject`  | Discards the staged action without executing it. No confirm gate — rejecting only discards                                                                                                                                                                                                                                                                                                                                    |

## The agent inbox

The `agent_inbox_*` tools read the platform's staged alert and suggestion queue. Automated sweeps file here instead of failing silently: [budget guardrail](/marketing/ppc-depth-tools#the-budget-guardrail) findings, store-integration health alerts, briefing suggestions, and voice, billing, and deploy-health warnings.

* `agent_inbox_list` — the open queue (`new` and `seen` by default; also `snoozed`, `actioned`, `dismissed`, `expired`). Filter by `category` (a dotted vocabulary like `shopify.scope_drift`) and `severity` (`info`, `suggestion`, `urgent`).
* `agent_inbox_get` — one item in full: title, markdown body, machine-readable metadata for the underlying problem, and lifecycle timestamps. Works on items in any state.
* `agent_inbox_resolve` — closes an item as `resolved` (you handled it) or `dismissed` (deliberately not acting). Resolving only closes the queue row — it never executes the item's action, and it doesn't make the cause go away: fix the underlying problem first, or the sweep will re-file it.

The dashboard surface for this queue is the [Ops Inbox](/ai/ops-inbox).

## Related pages

* [PPC Depth Tools](/marketing/ppc-depth-tools) — the guardrail whose alerts land in the inbox
* [SEO Delivery Tools](/marketing/seo-delivery-tools) — where the findings that become tasks come from
* [Standing Playbooks](/marketing/standing-playbooks) — the scheduled loops that stage drafts and alerts for approval
* [Advertising Reports](/advertising/reports) — the PPC dashboard's own reporting surface