# PCMA Brain — Operations V3 Dashboard

User manual for the operations team. Covers every panel, button, and decision the dashboard expects you to make.

> **How to use this manual:** Open `/dashboard/v3/manual` in your browser, click *Print / Save as PDF* to save a clean copy, or download this Markdown file directly. You can re-open it anytime from the **Manual** button in the dashboard top bar.

---

## Contents

1. What this dashboard is for
2. Getting started — your first 5 minutes
3. Top bar & system health
4. Ads-Readiness gate
5. Response Inbox
6. Inbound Exclusions (noise filter)
7. System Gaps & auto-fix recipes
8. Conversion Funnel & Efficacy Verdict
9. Revenue Priority Queue
10. Room Engine & Portal Engagement
11. Outreach, Comms & Message Efficacy
12. Plandome Nurture & Actions
13. Controlled-Cohort Campaigns
14. Unit Economics
15. Daily "State of the Union" email
16. Admin actions & the admin token
17. Troubleshooting & common questions
18. Glossary

---

## 1. What this dashboard is for

The V3 dashboard is the single operations cockpit for the PCMA Brain. It pulls together everything the system is doing into one screen so an operator can answer five questions in under a minute:

1. **Are we safe to send today?** (top bar + Ads-Readiness gate)
2. **Is anyone waiting on us?** (Response Inbox)
3. **Where is the funnel leaking?** (Conversion Funnel & Efficacy Verdict)
4. **Where is the next pound of revenue hiding?** (Revenue Priority Queue)
5. **Is the system itself healthy?** (System Gaps + Outreach blocks)

Everything else on the page — campaigns, economics, Plandome, room engine — is supporting context for those five questions.

## 2. Getting started — your first 5 minutes each morning

1. Open `/dashboard/v3`.
2. Glance at the **top bar**. The badges should all be green/blue. A red badge is a stop sign — read it before doing anything else.
3. Check the **Ads-Readiness banner**. GREEN = paid traffic OK, AMBER = caution, RED = pause spend now.
4. Open the **Response Inbox**. Action anything in the *Inbox* tab; ignore the *Lead Platforms* and *Excluded* tabs unless something looks misclassified.
5. Read the **Efficacy Verdict**. It tells you which one stage of the funnel is hurting revenue most today.

> **Tip:** the global time selector (*Today / 7d / 30d / All Time*) at the top right re-scopes most panels at once. Default is *All Time*; switch to *7d* for a "what changed this week" view.

## 3. Top bar & system health

The dark top strip is always visible and tells you whether the system is alive and trustworthy.

**Navigation links**
- **Dashboard V1** — the legacy/full dashboard. Useful for deep historical drill-downs.
- **Plandome Sales** — Plandome-only sales view.
- **Invoices** — billing & invoices.
- **Expediter** — the high-speed lead follow-up engine.

**Status badges (top-right)**

| Badge | What it means | What to do |
|---|---|---|
| Environment | `PROD` means real sends. `DEV` means outbound is blocked. | Make sure it says PROD before expecting messages to actually go out. |
| Circuit Breaker | GHL connection health. Green = open, red = tripped after repeated failures. | If red, GHL is having problems. Wait or check the GHL status page. |
| Auto-Send Mode | Whether automatic outbound is on. | Off = system is in "draft only" mode. Turn back on when you want sends to flow. |
| Daily Caps | How close PCMA & Plandome are to today's email cap. | If you're at 90%+, expect outbound to throttle for the rest of the day. |
| Last Sync | Minutes since the last GHL contact pull. | If > 60min, run a manual *Pull Now* from the inbox panel. |

## 4. Ads-Readiness gate

A coloured banner that tells you whether it is safe to spend on paid traffic today. The verdict comes from a list of independently-tunable checks (lead intake speed, reply rate, deliverability, no-show rate, CPA freshness, etc).

| Verdict | Meaning | Action |
|---|---|---|
| GREEN | All checks pass. Funnel can absorb new traffic. | Spend. |
| AMBER | One or more checks are warning but not failing. | Investigate the listed blockers. You can spend, but watch closely. |
| RED | Critical check failed. | **Pause paid traffic immediately.** The team will also get an email + Slack/WhatsApp alert. |

**Buttons inside the banner**
- **Edit thresholds** — opens the threshold editor. Change the numbers behind each check (e.g. minimum reply rate, max no-show %). All edits are validated and audit-logged.
- **Show recent changes** — full history of who changed what threshold, with old → new values. Each row has a **Revert to this value** button that puts the threshold back exactly where it was, in one click. The rollback itself is logged so you keep a clean chain.
- **Flip history** — every time the verdict changed colour, with timing and the blockers that caused it. Includes *MTTR* (mean time to recovery) for each red episode and per-channel send results (email / Slack / WhatsApp).
- **Alert channels** — turn each of the three alert channels (email, Slack, WhatsApp) on or off without touching code or environment variables. Useful during testing or when one channel is misbehaving. The modal also shows whether each channel is configured at all and what the most recent send result was. Every toggle is audit-logged.

> **Heads-up:** If a verdict change to red fails to send the alert on every enabled channel, the system *does not* persist the red state — it will retry only the channels that failed on the next tick. This is intentional: we never want a silent red.

## 5. Response Inbox

Every inbound reply (email, SMS, WhatsApp) lands here, classified by AI into Interested / Question / Objection / etc. Anything obviously not from a real prospect (lead-broker emails, marketing newsletters, sales pitches) is auto-filtered out via the noise filter (see next section).

**Tabs**
- **Inbox** — real prospects only. This is where 95% of your time goes.
- **Lead Platforms** — notifications from Bark, MyBuilder, Checkatrade, etc. Visible because you may want to skim them, but the system never replies to them.
- **Excluded** — service pitches and marketing newsletters. Hidden by default.

**Buttons on each row**
- **Replied** — mark this thread as handled.
- **Close** — close without action (e.g. spam, irrelevant).
- **This is legit** (Excluded / Lead Platforms tabs only) — restores the contact, removes the do-not-contact flag from GHL, and adds the sender to a permanent allow-list so the same address is never auto-excluded again.

**Buttons at the top of the panel**
- **Pull Now** — manually triggers an inbound mail pull. Use if you're expecting a reply that hasn't shown up.
- **Email Daily Report** — sends the State-of-the-Union email immediately to the configured recipient.

## 6. Inbound Exclusions (noise filter)

The exclusion layer keeps the inbox clean by classifying every inbound message against a deterministic rule chain (no AI cost):

- **Lead-platform notifications** — emails from known platforms (Bark, MyBuilder, Checkatrade, Houzz, Bidvine, Yell, Trustatrader, Thumbtack, ...). Tagged in GHL as `lead-platform:<name>`, marked do-not-contact, but kept visible in their own tab.
- **Marketing lists** — anything with a `List-Unsubscribe` header or from a known bulk sender domain (Mailchimp, SendGrid, HubSpot, Klaviyo, Apollo, Outreach, SalesLoft, Lemlist, Smartlead, Instantly, ...). Tagged `excluded:marketing-list`, marked do-not-contact, hidden.
- **Service pitches** — keyword-matched cold outreach. Tagged `excluded:service-pitch`, marked do-not-contact, hidden.

**The Inbound Exclusions panel**
- **Counts by label** — how many contacts in each bucket.
- **Top noisy senders (last 7d)** — the addresses spamming you most.
- **Allow-list size** — how many senders an operator has marked "legit".
- **Run backfill / Force re-run** — re-classify the entire history (auto-runs once on first deploy; manual button only needed if you change the classifier rules).

> **How an exclusion is reversed:** Click *This is legit* on any excluded row. The system: (1) clears the local exclusion flags, (2) removes `do-not-contact` and `excluded:*` / `lead-platform:*` tags from GHL *without* touching other tags, (3) adds the sender to `exclusions.allowlist` so they'll never be auto-excluded again.

> **Note:** Lead-platform contacts are also flagged `unsubscribed=True` as belt-and-braces. *This is legit* deliberately does **not** flip that back — re-subscribing must be an explicit operator decision.

## 7. System Gaps & auto-fix recipes

A passive integrity monitor that watches for contacts stuck between stages — e.g. an active deal with no owner, a contact with no status, an offer viewed but no application started.

| Severity | What it means |
|---|---|
| CRITICAL | Revenue at risk. Fix today. |
| WARN | Worth fixing this week. |
| INFO | Heads-up only. |

**Buttons**
- **Preview** — shows the exact contacts a recipe would touch, without changing anything.
- **Run** — applies the recipe. Always preview first if you're unsure.

## 8. Conversion Funnel & Efficacy Verdict

A 9-stage rolling-30d view of the funnel from *GHL Contact* through to *Elite Partner*. Each stage shows actual conversion rate vs target.

**Reading the funnel**
- **Green stage** = at or above target.
- **Amber/red stage** = below target. The further from target, the redder.
- Click any stage to edit its target.

**Efficacy Verdict**

Below the funnel, a single sentence calls out the **biggest bottleneck** — the one stage where, if you pulled it back to target, the most downstream revenue would unlock. The verdict includes a **forward projection** in £ so you can prioritise.

> **Use this as your weekly priority compass.** If the verdict says "Tool completion → Offer view is leaking", that's where the team should focus this week, not the prettiest other stage.

## 9. Revenue Priority Queue

Ranks 7 lead pools by *Value × Effort* so you always know where the next pound of revenue is hiding.

| Pool | Definition (typical) |
|---|---|
| Pool 1 — Highest intent | Tool completed + offer viewed in last 7d, no app yet. |
| Pool 2 — Application started | Began application but didn't submit. |
| Pool 3 — Recently engaged | Replied or clicked in last 14d. |
| Pool 4 — Cold but qualified | Past tool completion, no recent activity. |
| Pool 5 — Lost-recoverable | Was in pipeline, dropped out, may be reactivatable. |
| Pool 6 — Long-dormant | No activity in 90d+. |
| Pool 7 — Cold list | Never engaged. |

Click **Pool definitions** to see the exact SQL rules for each pool — useful when explaining why a contact ended up where they did.

## 10. Room Engine & Portal Engagement

The Room Engine tracks prospect movement through the 4 virtual rooms (Report → Playbook → Masterclass → Invitation). The Portal Engagement panel tracks tool completions (T01–T16), offer views, and application starts.

**What to look at**
- **Average days in room** — anything over 14 days = a stall.
- **Advancement rate** between rooms — should trend up over time.
- **Top stall points** — the specific tool or step where most prospects get stuck. This is your CRO target.

## 11. Outreach, Comms & Message Efficacy

**Outreach chart** — daily outbound volume across Email, SMS, WhatsApp. Sudden drops usually mean a daily cap was hit or the circuit breaker tripped.

**Blocked Today** — a breakdown of outbound attempts that were blocked. Reasons:
- **Cooldown** — same contact was messaged too recently.
- **Daily Cap** — brand-level send cap reached.
- **Circuit Breaker** — GHL is unhealthy.
- **Do-not-contact** — contact is on the exclusion list.
- **Unsubscribed** — contact opted out.

**Message Efficacy Leaderboard** — per-template open / click / reply rates with a single composite efficacy score. The system flags **Winners** (replicate the angle) and **Losers** (rewrite or retire).

## 12. Plandome Nurture & Actions

Plandome-specific sequences (Abandoned Tool, Win-Back, ...) with enrollment and conversion rates. The **Gold-Pool Actions** sub-panel surfaces individual high-value contacts to act on today: lost-recoverable leads, stale opportunities, upsell candidates.

## 13. Controlled-Cohort Campaigns

Cohort campaigns are time-boxed sends to a specific lead segment for testing copy or angles before promoting to evergreen.

**Lifecycle**
1. **Build** — system assembles the cohort and a draft template.
2. **Armed** — ready to fire but not sending yet.
3. **Running** — sends are flowing on the daily tick.
4. **Paused** — manually paused, OR auto-paused by the circuit breaker after too many consecutive send failures (shown as ⛔ AUTO-PAUSED with the trip reason).
5. **Done** — finished.

**Auto-paused banner (top of the campaigns panel)**

When any campaign is auto-paused a red summary banner appears above the campaigns table listing the count and the names. Click any name to jump straight to that row — it scroll-snaps and briefly flashes so you find it instantly even in a long table.

**Auto-resume (cooldown + canary)**

An auto-paused campaign doesn't need an operator to recover from a transient outage. After a configurable cooldown (default 30 minutes) the system fires **one canary send**:
- **Canary succeeds** → status flips back to *running*, an "auto-resume" notice is logged, the alert is re-armed, and the next daily tick continues normally.
- **Canary fails or is blocked** → campaign stays paused, the cooldown re-anchors to now, the daily attempt counter ticks up. There's a per-day attempt cap (default 3) so a permanently broken inbox can't burn the day.

Manual pauses are *never* auto-resumed — only circuit-breaker pauses are. You stay in control.

**Real-time auto-pause alerts**

The moment a campaign trips, the team gets paged on three channels in parallel: email, Slack (if webhook configured), and WhatsApp (if phone configured). A second "auto-resume" notice goes out the same way when a paused campaign self-recovers, so pause + recovery sit in the same inbox.

**Buttons per campaign**
- **Arm** / **Pause** / **Resume** — change state. Resume is one click; the system clears the auto-pause flag automatically.
- **Edit template** — inline subject + body editor. Saves are audit-logged with operator name.
- **Preview** — render the template with a sample contact's merge fields.
- **Send test** — dispatch the template to one address you specify, before arming the real campaign.
- **History** — last 10 saved versions of this template, with one-click *Restore*.
- **Reset** — revert the template to the in-code default.

> **Operator name:** Set this once at the top of the editor. It's remembered locally and stamped on every audit row so the history actually tells you who edited what.

## 14. Unit Economics

The financial pulse of the operation, rolling 30 days.

| Metric | Definition |
|---|---|
| Spend (30d) | Total ad spend logged via the spend-entry form. |
| CPL (Cost Per Lead) | Spend ÷ new contacts. |
| CPA (Cost Per Application) | Spend ÷ submitted applications. |
| ROAS — Actual | Realised revenue ÷ spend. |
| ROAS — Projected LTV | Modelled lifetime value of the cohort ÷ spend. |

Use the **Log spend** button to enter today's ad spend; this feeds CPL/CPA/ROAS and the Ads-Readiness *cpa_freshness* check.

## 15. Daily "State of the Union" email

An automated 7am summary email that recaps the previous 24 hours: KPI deltas, what the system did autonomously, what needs an operator decision, ads-readiness verdict, exclusions caught, campaigns active, and bottleneck verdict.

- Click **Email Daily Report** in the Response Inbox panel to send it on demand.
- Click **Preview Daily Report** to see the HTML in-browser before sending.

## 16. Admin actions & the admin token

Mutating actions (restore-legit, run backfill, edit thresholds, restore template version, send test, force alert, log spend, etc.) are gated by an admin token. The dashboard prompts for it the first time you click an admin action and remembers it for the session.

> **Don't share the admin token.** Treat it like a password — anyone with it can change campaign copy, restore excluded contacts, and trigger sends.

## 17. Troubleshooting & common questions

**"Why are no messages going out?"**
1. Check the Environment badge: it must say `PROD`.
2. Check the Circuit Breaker badge: it must be open (green).
3. Check Daily Caps: if 100%, you're done for the day.
4. Check the Blocked Today panel for the actual block reason.
5. Check the Campaigns table for any ⛔ AUTO-PAUSED rows.

**"A real prospect ended up in Excluded — how do I get them back?"**
Open the *Excluded* tab, find the row, click **This is legit**. The contact is restored locally and in GHL, and that sender goes on the permanent allow-list.

**"The Ads-Readiness banner went red — what now?"**
Read the listed blockers in the banner. Each blocker maps to a specific check (e.g. `cold_reply_rate`, `noshow_rate`, `cpa_freshness`). Either fix the underlying issue or, if the threshold itself is wrong, click **Edit thresholds** and adjust. All edits are audit-logged.

**"I edited a campaign template by mistake."**
Open the template, click **History**, find the previous version, click **Restore**. The restore itself is logged so you have a full chain.

**"The numbers in two panels don't match."**
Check the global time selector — different panels honour it differently. Some are always rolling-30d (Funnel, Economics) regardless of the selector.

**"I think the Last Sync is too old."**
Click **Pull Now** in the Response Inbox panel; this triggers a manual GHL sync and inbound mail pull.

## 18. Glossary

| Term | Meaning |
|---|---|
| Ads-Readiness | The composite gate that says whether it's safe to spend on paid traffic. |
| Auto-pause | A campaign that the circuit breaker stopped after repeated send failures. |
| Circuit breaker | Generic safety mechanism that trips a system off when failures pile up. |
| Cohort campaign | A controlled, time-boxed send to a specific lead segment, used for testing. |
| CPA freshness | How recently spend was logged. Stale spend invalidates ROAS. |
| Daily Caps | Per-brand maximum number of outbound emails per day. |
| Do-not-contact | Contact-level flag that hard-blocks all outbound. |
| Efficacy Verdict | The single sentence that tells you which funnel stage to fix next. |
| Exclusion label | Why a contact was filtered out: `service_pitch`, `marketing_list`, or `lead_platform_notification`. |
| MTTR | Mean Time To Recovery — how long an ads-readiness red episode lasted. |
| Pool | A lead segment defined by behaviour, ranked in the Revenue Priority Queue. |
| Room | One of the 4 virtual stages a prospect moves through inside the portal. |

---

*PCMA Brain · Operations V3 Dashboard Manual · Version 1.1*