> ## 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.

# AI Ops Inbox

> A daily AI-driven briefing of actionable recommendations for your store. Hiveku watches your last-24h activity and posts 3-7 specific things to do — each with a one-click action.

## What this is

A daily inbox of AI-surfaced operational recommendations for your business. While other AI builders are reactive (the AI does what you ask), Hiveku's ops inbox is **proactive** — every day at 13:00 UTC, Hiveku reads your last-24h activity (orders, inventory, CRM rollup, workflow status, reviews) and posts 3-7 specific actionable recommendations into a per-account inbox.

Each recommendation has a category, severity, and a one-click action. You don't have to know what to do next — Hiveku tells you, and the inbox is one of the few places in the product that doesn't require you to start a task.

## Where it lives

| Surface                                     | Path                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------- |
| Compact dashboard widget (top of home page) | `/dashboard` — appears under "Welcome back" once a Shopify connection is active |
| Full inbox with snooze / dismiss / history  | `/dashboard/commerce/inbox`                                                     |

The widget shows the top 3 unread items inline. The full page paginates the rest with status tabs (Inbox / History).

## What kinds of items the inbox surfaces

The model has 13 recommendation categories. Some examples:

<CardGroup cols={2}>
  <Card title="Inventory alert" icon="triangle-exclamation">
    "Single-Origin Coffee Bag is down to 8 units across 3 SKUs. At your current sell-through rate, you'll be out of stock in 4 days. Reorder now."
    Action: `open_inventory` — links to Shopify admin.
  </Card>

  <Card title="High-value customer" icon="user-plus">
    "Jane Doe just placed her 5th order (\$420 LTV). Consider a personal thank-you note or VIP coupon."
    Action: `open_crm_contact` — opens her CRM page.
  </Card>

  <Card title="Workflow suggestion" icon="bolt">
    "You've had 12 abandoned carts this week. Build a recovery workflow."
    Action: `open_workflow_builder` — pre-fills a new workflow with the abandoned-cart trigger.
  </Card>

  <Card title="Low-velocity product" icon="chart-line-down">
    "Decaf Blend hasn't sold in 30 days. Consider markdown, bundling, or removing from featured collections."
    Action: `create_product_draft` — opens an updated draft (admin/owner only).
  </Card>

  <Card title="Content opportunity" icon="pen">
    "Your bestseller has no reviews. Schedule a review-request workflow for past buyers."
    Action: `open_workflow_builder` — opens with a review-request template.
  </Card>

  <Card title="Subscription billing failed" icon="credit-card">
    "A recurring charge failed for [jane@example.com](mailto:jane@example.com). Shopify will retry per dunning policy, but it's worth reaching out — failed billing is the #1 churn signal."
    Action: `open_url` — links to Shopify Subscriptions admin.
  </Card>
</CardGroup>

Other categories: cold-lead detection, abandoned cart opportunity, marketing campaign idea, store health (e.g. broken page detected), competitive mention, performance regression, growth experiment, customer feedback synthesis.

## How it works

<Steps>
  <Step title="Daily cron at 13:00 UTC">
    A scheduled job in `hiveku-cron-worker` calls `/api/cron/agent-ops/daily-briefing`.
  </Step>

  <Step title="Fan-out across eligible accounts">
    Hiveku runs the briefing for every account that meets at least one criterion: Shopify connected, has workflows, or has > 5 CRM contacts. Sequential per-account so a slow account doesn't block others.
  </Step>

  <Step title="Per-account context build">
    For each account, Hiveku assembles a `BriefingContext`: orders in the last 24h, inventory levels per top SKU, CRM rollups (new contacts, high-LTV signals), workflow firing status, currently-open inbox items (for dedup so we don't repeat yesterday's recs).
  </Step>

  <Step title="Claude Sonnet 4.6 via OpenRouter">
    Hiveku posts the context to OpenRouter with a strict-JSON-schema response\_format. Claude reads the activity, emits 3-7 recommendations with `category`, `severity`, `title`, `body`, `action_type`, and `action_payload`.
  </Step>

  <Step title="Validate + persist">
    Each recommendation is validated against the JSON schema (no garbage from the model can land). Valid recs insert into `agent_ops_inbox_items` with a 14-day TTL.
  </Step>

  <Step title="You see them at /dashboard or /dashboard/commerce/inbox">
    The widget appears on the dashboard home automatically once you have a Shopify connection. The full inbox at `/dashboard/commerce/inbox` shows all items + history.
  </Step>
</Steps>

## What you do with each item

Every item has a primary action button:

| Action                  | What it does                                                                                |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `enable_workflow`       | Opens a workflow template (e.g. abandoned-cart recovery) and lets you enable with one click |
| `create_product_draft`  | Creates a Shopify draft via the multi-writer Admin proxy (admin/owner only)                 |
| `send_email_draft`      | Opens the email composer with a pre-filled draft                                            |
| `open_crm_contact`      | Deep-links to a CRM contact page                                                            |
| `open_workflow_builder` | Opens the workflow builder, optionally with a starter template                              |
| `open_inventory`        | Links to Shopify admin's inventory page                                                     |
| `open_url`              | Generic URL link (used when the action is on a third-party page)                            |
| `no_action`             | Informational only — read and dismiss                                                       |

Beyond the primary action, every item has:

* **Mark as seen** — auto-fires when you scroll the item into view; lets us measure "delivered but ignored" vs "never seen"
* **Dismiss** — explicit "I read this and I'm done"
* **Snooze** — 24h, 7d, or 30d. The item disappears until then
* **Manual generate** — at the top of the full inbox, force a fresh briefing run (rate-limited 5min per account)

## How this compares to alternatives

| Source                                | Reactive vs proactive | Where it lives     | Hiveku-comparable?                                                       |
| ------------------------------------- | --------------------- | ------------------ | ------------------------------------------------------------------------ |
| Shopify admin's "Home" tab            | Mostly reactive       | Shopify admin      | Partial — Shopify shows recent activity but not specific actions to take |
| Klaviyo's "Insights"                  | Marketing-only        | Klaviyo            | No — limited to email/SMS context                                        |
| Other AI builders (Lovable, v0, Bolt) | Purely reactive       | Their chat         | No — they don't ship operational AI                                      |
| GA4 / Mixpanel intelligence           | Analytics-only        | The analytics tool | No — they surface metrics, not actions                                   |

Hiveku is the only platform where an AI watches your store + customer activity end-to-end and gives you a daily list of *things to actually do*, integrated with the surfaces (CRM, workflows, Shopify) where you'd act on them.

## Architectural intent

The inbox is the seam through which Hiveku transitions from "AI builder" to "AI operator." Today every item is Shopify-driven (the daily briefing produces them all), but the table (`agent_ops_inbox_items`) is generic. Future producers will post into the same inbox:

* **CRM cold-lead detector** — "8 contacts haven't engaged in 30 days; consider a re-warming sequence"
* **Reviews moderation queue** — "3 pending reviews need approval" (already wired)
* **Workflow A/B winner posts** — "Variant B in your subject-line A/B beat Variant A by 11%; promote it"
* **Voice missed-call follow-ups** — "5 missed calls yesterday from numbers tied to known customers"
* **Site health monitors** — "Your contact form has been failing 30% of submissions for 6 hours"

When a new producer lands, it inserts a row with its own category prefix (e.g. `crm.cold_lead_detected`) and the inbox renders it like any other item. You get one inbox for AI-surfaced ops instead of N notification channels.

## Privacy and AI-cost details

* **Per-account isolation** — each briefing reads only that account's data. No cross-account leakage in the prompt.
* **Cost** — typically $0.02-$0.05 per account per day at current Claude Sonnet 4.6 pricing. Hiveku covers this; not user-billable.
* **Data residency** — the briefing context (order summaries, inventory levels) is sent to OpenRouter → Claude. The prompt does **not** include PII like customer email addresses or full order details — only counts, rollups, and product references.
* **Retention** — `agent_ops_briefing_runs` keeps the prompt + completion + token counts + cost for 90 days for debugging.

## Manually triggering a fresh briefing

`/dashboard/commerce/inbox` has a "Generate now" button. Useful when:

* You've just connected a Shopify store and want recommendations sooner than 13:00 UTC tomorrow
* You've taken action on yesterday's items and want to see what's next
* You're testing the briefing pipeline

Rate-limited to one manual run per 5 minutes per account.

## What's next

<CardGroup cols={2}>
  <Card title="Workflow builder" icon="bolt" href="/integrations/workflows">
    Many inbox actions deep-link into the workflow builder.
  </Card>

  <Card title="Shopify integration" icon="bag-shopping" href="/integrations/shopify/overview">
    The inbox widget self-gates on a Shopify connection.
  </Card>
</CardGroup>