# AI Copilot (Manage)

**Portal:** Manage · **Routes:** `manage.ai-copilot.{index,summary,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.

## Customers — first tab

`/manage/ai-copilot` now opens the customer action queue; the fleet Summary is at
`/manage/ai-copilot/summary`. `RevenueIntelligenceQueue` reads permission-scoped
channel evidence and open actions, groups by customer, and applies `RevenueActionPolicy`.
Recorded CRS values are explicitly historical and ordered by conversation time.
The queue refreshes on open/refresh; background reassessment and automatic task
execution are specified in [the implementation plan](../../../plans/2026-09-16-revenue-intelligence-assistant.md).
It never sends a message, marks work done, or changes a customer score on a read.

### Journey checklist

The first tab now puts an ordered journey beside each customer: get started → learn and explore → build the relationship → prepare the decision → book. Seventeen core steps and an optional showroom visit read the customer's full available history. Early profile/goal setup does not require loan eligibility or property selection. Progress never adds points to the historical readiness score.

`CustomerJourney` reads evidence; `CustomerJourneyController` exposes scoped lookup/read routes and a manage-leads confirmation route. `LeadJourneyUpdateRepository` appends dated, attributed staff observations with stale-save protection. Find any customer includes leads without recent alerts. Missing evidence is explicit; how-to progress remains device-local and needs confirmation. Full definitions and limits: [customer journey implementation](../../../plans/2026-09-16-customer-journey.md).

## 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.*`)


### Follow Up / Customer Journey redesign

The Customers tab now opens Follow Up: the actual customer message or behavior appears before the recommended action. Customer Journey is a separate view, with one stage visible at a time. Nineteen core steps include understanding and decision agreement. Journey completion is a percentage of applicable steps; five current decision checks cover understanding, needs, decision agreement, financing and cash. Confirmations older than 30 days need reconfirmation. The previous conversation CRS is collapsed historical context.

See [the interaction and measurement definitions](../../../plans/2026-09-16-follow-up-journey-redesign.md).