# AI Copilot (Manage)

**Portal:** Manage · **Routes:** `manage.ai-copilot.{index,activity,analytics,analytics.chat,knowledge}` · **Nav:** the top-level
**AI Employee** sidebar entry (`prefixes: ['/manage/ai-copilot']`), fronting the
`SectionTabs` section `ai-copilot`. **Permissions** (2026-08-12): the whole surface —
routes and the sidebar entry — is gated on **any leads view level** (`Permission::viewLeadsAny()`),
because Analytics reads customer (lead) data and the grounded chat answers from it. The
original "no permission middleware while it's a coming-soon page" note honoured its own
"gate it the moment it grows a real surface" clause then; a role with no lead level (the
**Marketing** role) doesn't see or reach it.

## What it does

The fleet headquarters of the five AI agents (Zoom, Phone Call, Messages, Showroom F2F,
Member Portal — each documented with its own module). Summary shows what the whole fleet did
and cost this period, per-agent, with **rule-based analytics insights**; Activity is the
combined work diary (done + coming up), every line tagged with its agent and linking to that
agent's page.

## How it works

- `Manage\Ai\CopilotController` (read-only, `auth`+`admin`). **Attribution:** every
  `ai_requests` row maps to exactly one agent by `subject_type` first (ZoomMeeting /
  CallRecording / F2fRecording / WhatsappConversation — decides the shared
  conversation/transcription prompts), then `prompt_key` (the agent-specific keys); anything
  unattributable (lead enrichment etc.) is reported as **"other AI spend"**, never silently
  folded into an agent.
- **Insights are computed, never model-generated** (`insights()`): reliability warnings
  (≥50% failure with ≥5 settled), cost concentration (≥50% share), cost-per-action spread
  (≥3× with volume), the switched-off capability inventory across the fleet, and the
  cheapest non-staff-serving agent. Ranked most-actionable first, capped at 5.
- Activity merges the same ledgers each agent page reads (`ai_requests` work lines, the three
  brief ledgers, flow objectives, funnel reminder sends, watchdog `notify_deliveries`) and the
  real schedule state for "coming up" — planned work is never invented.

## Related files

- [app/Http/Controllers/Manage/Ai/CopilotController.php](/app/Http/Controllers/Manage/Ai/CopilotController.php)
- [resources/js/Pages/Manage/Ai/Copilot/Summary.vue](/resources/js/Pages/Manage/Ai/Copilot/Summary.vue) ·
  [Activity.vue](/resources/js/Pages/Manage/Ai/Copilot/Activity.vue)
- [resources/js/Components/SectionTabs.vue](/resources/js/Components/SectionTabs.vue) — section `ai-copilot`
- Routes: [routes/web.php](/routes/web.php) (`manage.ai-copilot.*`)