---
name: kai-client-dashboard
description: Build a white-labeled, client-facing intelligence dashboard — a live, branded reporting surface an agency stands up per client instead of sending static reports. Covers brand auto-extraction from the client's URL, a three-tier build (Basic/Standard/Advanced), an onboarding feature wizard, a 10-page inventory, public-access tradeoffs, and the retention plays that make the dashboard sticky. Use when "client dashboard", "client intelligence dashboard", "white label dashboard", "client portal", "branded dashboard for my client", "agency dashboard", "build my client a dashboard", "give the client a live view instead of a report", or any request to stand up a durable, client-facing reporting surface.
---

> **Kai root note:** `knowledge/`, `harness/`, and `scripts/` paths in this skill live in the Kai install, not the user's project. Resolve them against the first ancestor directory of this SKILL.md that contains a `knowledge/` folder (the Kai plugin root, `~/.claude/kai`, or the kai-cmo-harness repo). `MARKETING.md`, `memory/`, and any output files live in the current project. If a referenced `scripts/` command is not available in this install, say so, skip it, and continue with the file-based guidance — never fabricate its output.

# /kai-client-dashboard — A Live Branded Surface The Client Bookmarks

## Objective

A co-branded, always-on reporting product standing up for **one** client: brand shell extracted from their own site, the page set they actually asked for, real data wired to real credentials, an explicit public-access decision, and the retention program that keeps them opening it. A report is a snapshot forgotten by Friday; this is a URL they return to.

This is distinct from `/kai-data-dashboard`, which turns already-sourced data into a spec or static handoff, and from `scripts/build_dashboard.py`, which builds the *operator's own* internal ops dashboard (goals, tasks, integrations — `workspace/dashboard.html`). Use this skill when the deliverable is a durable product for someone outside your own team.

**One client = one dashboard = one deployment.** Never fold a second client into an existing client's project. A shared default — a hardcoded client id, a fallback credential — that leaks from client A into client B is the most common failure mode in this workflow.

## Done when

Work type `audit-report` — floor **E3/C4/O1** (`harness/eco-floors.yaml`), `client_facing: true`.

- **E3** — an explicit go-ahead on the exact page set, credentials, and public-access decision before build, and after build a verified read-back: every page loads or shows a labeled empty state, a manual sync has been triggered, and the access posture matches what is actually served. Where the dashboard deploys to a live URL, that read-back is the execution evidence — a deploy that reported success is not it.
- **C4** — the Kai Data Provenance Rule: a declared mode per metric, a source and sync timestamp on every number, no score or dollar figure without a stated formula and a source per input, and `python scripts/quality_gates/audit_provenance_lint.py <dashboard-source-folder> --audit-dir` passing.
- **O1** — the dashboard names the metric it is meant to move for this client (dashboard opens, strategy-call attendance, retention) with a baseline and an owner. Engagement lift is a hypothesis to prove with this client's own numbers, never an assumed result.

## Constraints

### Provenance and access, before wiring a single page

1. **Load `harness/references/audit-data-provenance.md` and declare a data mode for every metric.** A live dashboard reading connected accounts is `onboarding_connected` by definition. Use `internal_demo` only for an unmistakably labeled sample shell shown before data is connected — never as silent filler.
2. **Load `knowledge/checklists/privacy-sanitizer-checklist.md` before deciding what is public.**
3. **Never fabricate a metric, review count, ranking, health score, or dollar figure to fill an empty panel.** A missing source is a `data-gaps.md` entry plus a visible empty state in the UI.

### Public access — what "no login" actually means

The default posture is a bookmarkable public URL, because a client who has to remember a password stops checking. That default is fine for aggregate marketing metrics: traffic trends, ranking positions, aggregate review scores, campaign-level spend and ROAS. It is **not** automatically fine for anything carrying a name, phone number, email address, or dollar figure attached to an individual — Leads and Communications are the obvious risk, and Sales Intelligence is worse.

Run the Publication Gate in `knowledge/checklists/privacy-sanitizer-checklist.md` before every public flip, not only at launch, and pick one:

- **Split access.** Aggregate pages public; Leads, Communications, and deal data behind lightweight auth.
- **Obscured + gated.** Unguessable slug, `noindex`, plus a shared passcode — only with the client's explicit sign-off on that exposure for that data.

Check specifically for a global "redirect to login on any 401" handler. It is the most common way a page meant to be public silently isn't, and the most common way a page meant to be gated silently isn't either. Confirm both directions before sharing the URL.

### Build and data

- **Know before building:** business name as it should appear; website URL; industry or business type; the logo (confirmed, not assumed); which analytics are connected — GA4 property id, GSC site URL exactly as registered (`https://www.example.com/` or `sc-domain:example.com`), Google Business Profile name; which CRM or lifecycle tool the client runs and whether API access already exists; 5–15 target keywords for rankings and AI visibility; and any competitors to benchmark.
- **Auto-extract the brand from the URL rather than re-asking for it.** Fetch the site (WebFetch, or the pre-installed Chromium/Playwright for JS-rendered sites) and pull logo, dominant colors with hex codes, heading/body font stack, business name, tagline, and industry signals from copy or schema. Apply them as the shell theme. **Mark anything inferred — a font stack guessed from a system-font fallback — as unconfirmed rather than presenting it as the client's real brand guide.**
- **A declined feature gets no page.** An empty or placeholder page for something the client said no to is worse than not having the page. Any custom page the client asks for gets its scope, sidebar placement, and required credentials confirmed before it enters the plan.
- **The public-access decision is explicit and covers every page, not just the Overview.** Summarize the full page set, every credential collected, everything still outstanding, and that access decision — then get an explicit go-ahead before building.
- **Credentials resolve as config, never as code constants.** One client = one config record + one credential set, through `kai/runtime/connections.py` / `kai/runtime/integrations.py` or an equivalent. No per-client constant with a default that silently applies to the next build.
- **Every page needs** a plain-language paragraph explaining what the data means, an Agency Recommendations block (3–4 insights in the agency's voice, specific to this client, never generic filler), a visible "last synced" timestamp, and a loading state rather than a blank screen. Flag failed syncs, not just successful ones.
- **Deliverables and Agent Registry reflect real current state.** Never mark a service active that isn't running; populate the registry only from real scheduled work — `workspace/HEARTBEAT.md` heartbeats, `agent/tasks/` scheduled tasks such as the weekly `cmo_review`, or real Routines when running on Claude Code Remote. An agent that hasn't run shows "not yet run," never a fabricated date.

### Engagement automation is compliance-gated

Before enrolling a single contact in SMS or any prerecorded or ringless-voicemail channel, load `harness/skills/kai-sdr-operator/references/compliance-matrix.md` and confirm consent and an opt-out path for that channel. TCPA-type rules apply to prerecorded and autodialed voice and SMS in the US, with equivalents elsewhere. **A client's own lead did not consent to hear from the agency just because they sit in the client's CRM.** Email-only cadences do not carry this risk; SMS and voicemail drops do.

## Context

| Need | Load |
|---|---|
| Provenance rule, modes, source tiers | `harness/references/audit-data-provenance.md` |
| What may go public, Publication Gate | `knowledge/checklists/privacy-sanitizer-checklist.md` |
| SMS/voicemail consent rules | `harness/skills/kai-sdr-operator/references/compliance-matrix.md` |
| Health-claim compliance | `harness/references/advertising-compliance.md` |
| Fast-path shell and template | `scripts/build_dashboard.py`, `scripts/templates/dashboard_template.html` |
| Connectors | `kai/connectors/analytics/ga4.py`, `kai/connectors/ads/google_ads.py`, `kai/connectors/ads/meta_ads.py`, `kai/connectors/lifecycle/` |
| Credential and connection resolution | `kai/runtime/connections.py`, `kai/runtime/integrations.py` |
| Rank tracking | `scripts/intel/serp_tracker.py` |
| Cited competitive and review data | `/kai-competitors`, `/kai-brand-pulse` |
| AI-search visibility feed | `/kai-surround-sound` |
| Data contract once sources are connected | `/kai-data-dashboard` |

**Tiers** — default to Standard; drop to Basic when the credential list comes back mostly empty; add an Advanced module only when both agency and client want the deeper build and the extra data-sensitivity that comes with it (deal values, individual rep performance, scored leads):

| Tier | Use when | Data sources | Build |
|---|---|---|---|
| Basic | GA4 + GSC only, no CRM/ads stack yet | GA4, GSC | 3 pages: Overview, Website Traffic, Search Performance |
| Standard | Client runs a real marketing stack | GA4, GSC, CRM/lifecycle, ad platforms, reviews | Full 10-page set, branded shell, scheduled sync |
| Advanced | Sales throughput or reputation is the growth lever | Standard + CRM deal data and lead scoring, or competitor review/AI-mention tracking | One extra module — Sales Intelligence **or** Reputation Intelligence, not both by default |

**Two honest build paths.** Kai ships no prebuilt multi-tenant client-dashboard codebase. *Fast path:* restyle `scripts/build_dashboard.py` + `scripts/templates/dashboard_template.html` (shipped dark-themed for internal ops — a structural starting point, not the final look) toward the white-background co-branded look, fed by a `/kai-data-dashboard` data contract. That is the right ceiling for Basic. *Full-app path:* stand up your own project in your usual stack; your first build becomes the reference for builds #2 and #3, copied and find-and-replaced on client-specific values. Deploy via a Vercel connector if available, otherwise hand off standard deployment steps.

**Page inventory (Standard, 10 pages):**

| Route | Page | Source |
|---|---|---|
| `/` | Dashboard Overview | All connected sources, rolled up |
| `/visitor-id` | Smart Visitor ID *(optional)* | Visitor-identification tool, if wired |
| `/rankings` | Google Rankings | GSC + `scripts/intel/serp_tracker.py` |
| `/llm-rankings` | AI / LLM Rankings | `/kai-surround-sound` output |
| `/traffic` | Website Traffic | GA4 (`kai/connectors/analytics/ga4.py`) |
| `/adroll` | Retargeting *(optional)* | `kai/connectors/ads/google_ads.py`, `meta_ads.py`, or CSV |
| `/content` | Content & Social | CRM/ESP + `/kai-social` content log |
| `/reviews` | Reviews | `/kai-brand-pulse` cited aggregation |
| `/leads` | Leads | CRM form/contact data |
| `/communications` | Communications | CRM contact/message data |

**Optional features and where their data comes from** — retargeting (Google/Meta connectors exist; other platforms need CSV or a new connector, flagged as a gap) · visitor identification and lead scoring (no bundled connector; never invent a score without a stated formula) · competitor benchmarks (route through `/kai-competitors` and `/kai-brand-pulse`, not hand-scraped review counts) · Brand Assets page (from the site extraction, refined) · press releases and brand visibility (manual distribution URLs) · video library (manual embed flow) · AI/LLM rankings (fed from `/kai-surround-sound`, not a hand-rolled query mechanism) · social performance (`/kai-social` content log where available) · email/CRM automation visibility (same CRM connection) · Deliverables page · What's Next roadmap (source-backed reasoning, no invented benchmarks) · multi-brand or multi-location (tabbed or sectioned) · Agent Registry.

**Two pages carry most of the retention value.** *Deliverables* — a visual checklist of every service the agency is actively delivering: green/active, yellow/in-progress, grey/available-but-not-purchased. It answers "what am I paying for" before the client asks, and a grey card is an upsell without a sales call. *Agent Registry* — every automated Kai workflow running for this client: name, purpose, trigger, how to start it manually, last run, status.

**Retention plays:** Core — Brand Guide, Deliverables page, "Powered By [Agency]" co-branding (client logo top-left, agency mark top-right and smaller). Recommended — Competitor Watchlist, What's Next roadmap. Optional — Review Response Center and Lead Alert Feed for daily-use stickiness; Marketing Health Grade or ROI summary **only** with a named formula and a source per input, since an invented "B+" or "$40K in pipeline value" is exactly what the provenance rule exists to block.

**Credentials, where they live:** GA4 Property ID → Analytics → Admin → Property Settings · GSC Site URL → Search Console property selector, exactly as registered · Google Service Account JSON → Cloud Console → IAM & Admin → Service Accounts → Keys → Add Key → JSON · GoHighLevel Location ID / API Key → Settings → Business Info, and Settings → Integrations · HubSpot Private App Token → Settings → Integrations → Private Apps, CRM read scopes · Google Business Profile → Business Profile Manager, matched by business name. A credential not on this list is not a connector this harness ships today — collect it if the client has it, log the integration as a data gap until wired, and never fake its output meanwhile.

**Industry customization:**

| Industry | Review platforms | Distinctive page |
|---|---|---|
| Home Services | Google, Yelp, Houzz, Angi | Project gallery / before-after |
| Healthcare / Insurance | Google, Healthgrades | Compliance-safe lead pipeline (check `harness/references/advertising-compliance.md` before any health claim ships) |
| Hospitality | Google, TripAdvisor, Yelp | Visitor origin map + sentiment by area |
| E-commerce / Retail | Google, Yelp, Facebook | Product performance + cart abandonment |
| Professional Services | Google, LinkedIn | Proposal pipeline + retention view |
| Financial Services | Google, BBB | Deal tracker + sales leaderboard — Advanced tier only, and only with sign-off on showing individual rep numbers |

**Known failure modes:** a hardcoded default client id or credential from build #1 silently applying to build #2 · a public dashboard showing a login screen anyway (global 401 redirect) · a PII-bearing page left fully public · an empty panel filled with an invented number · a missing credential silently serving stale cache · SMS/voicemail enrolling a contact who never consented to hear from the agency · a fabricated Health Grade or ROI figure · an Agent Registry listing automation that isn't actually scheduled.

**Final response covers:** the dashboard URL (or the folder path and what remains to wire), the tier and which optional features shipped versus were skipped, every outstanding credential listed as a data gap, the public-access decision and why, and whether Deliverables and Agent Registry reflect real current state.

## Escalate when

- A page would expose PII publicly and the client has not signed off on that exposure for that data.
- A metric the client wants displayed has no source, or a score they want has no formula.
- SMS or voicemail engagement is requested without a documented consent basis and opt-out path.
- A second client's build would reuse the first client's config, credentials, or deployment.
- An Advanced module would surface individual rep performance or deal values without explicit sign-off.
- A required connector does not exist in this harness and the client expects live data from it.