penny-dashboard

name	penny-dashboard
description	Compute per-client cost/billing profitability (Penny Dashboard) and generate an internal owner view plus a locked-down, client-safe HTML page per client. Use when an agency owner asks to run their Penny Dashboard, check which clients are unprofitable, see margin by client, or generate a client-safe cost/spend page to send a client.

Penny Dashboard

What this is (and isn't)

This is a runnable tool, not an instruction-only skill: real Python code at tools/penny-dashboard/ that computes billed/cost/margin per client from YAML config + ad-spend data, then renders two kinds of HTML. This SKILL.md exists so an agent runtime (Claude Code or any other agentic CLI) can drive that code conversationally — it does not reimplement the math itself.

It is: a local, no-server profitability calculator + a client-safe report generator.

It isn't: a live-syncing dashboard, a CRM/billing system of record, or a tool that writes anything back to an ad platform. Read-only ad-spend pull, static HTML output.

When this runs

Trigger phrases: "run my Penny Dashboard", "check client margins", "which clients are losing money", "generate a client-safe cost page for [client]", "is [client] still profitable", "set up my Penny Dashboard".

Prerequisite: the member has already run python3 run.py init once and filled in config/clients.yaml, config/billing.yaml, config/tools-costs.yaml, and config/visibility.yaml with their real data. If those files don't exist yet, run init first and walk the member through filling them in (see README's "Setup" section) before attempting generate — generate will error clearly if a required config file is missing.

How to run

cd tools/penny-dashboard
pip install -r requirements.txt   # first time only

# First time only — scaffolds config/ from the .example templates:
python3 run.py init

# Every subsequent run:
python3 run.py generate                       # current month, 20% margin-alert threshold
python3 run.py generate --period 2026-06       # a specific month
python3 run.py generate --threshold 25         # custom alert threshold

If the member hasn't set up ad-spend data for a client yet (no google_ads_customer_id and no manual_spend_csv, or a CSV file that doesn't exist), that client's ad spend computes as $0 — the run still completes for every other client rather than failing. Point this out if a client's numbers look suspiciously low.

If generate prints a "visibility.yaml requested unsupported field(s)" note to stderr, that's not an error — it means the member listed a field in visibility.yaml that isn't on the client-safe allowlist (only ad_spend_usd, deliverables, results_note are ever shown). Tell them which field got dropped and why, in plain terms — it was never going to appear on the client's page regardless of what the config asked for.

Output

• out/owner.html — the private margin table, one row per client, loss-making clients sorted to the top, each row flagged if below the alert threshold. Tell the member explicitly: never share this file with a client — it contains cost and margin data.
• out/clients/<client_id>.html — one page per client, containing only what visibility.yaml whitelisted for that client. Safe to open, email, or host and send the link — margin/cost data cannot appear on this page by construction (see penny_dashboard/visibility.py's ALLOWED_CLIENT_SAFE_FIELDS).
• Terminal output also lists any client below the margin threshold, plain-English, one line each. If PENNY_SLACK_WEBHOOK_URL or PENNY_ALERT_EMAIL_TO/PENNY_SMTP_* are set in .env, the same lines are also posted/emailed.
• out/history.db (SQLite) — month-over-month margin history, used to compute the "trend" column on the next run. Not meant to be opened directly.

Common mistakes

• Sending the owner view to a client. out/owner.html is internal-only by design — always confirm which file (owner.html vs. clients/<id>.html) before sharing anything.
• Assuming visible_fields in visibility.yaml controls what CAN be shown. It only controls what IS shown, from an already-fixed, code-level allowlist of three fields. Adding a new field name there does nothing unless the field is also added to ALLOWED_CLIENT_SAFE_FIELDS in penny_dashboard/visibility.py — a deliberate code change, not a config edit, precisely so nobody can widen the client-safe surface by accident.
• Expecting Meta Ads / Stripe / hours data in v1. Those are documented "Later phase" items, not bugs — see README's "What it does NOT do" section.
• Forgetting manual_spend_csv needs a real file. A client with neither google_ads_customer_id nor a manual_spend_csv pointing at a real, populated file will show $0 ad spend — not an error, just a silent zero. Sanity-check the owner view's numbers against what you know before sending anything.
• Running generate before init, or before filling in the real config files. The scaffolded files are copies of the .example templates with placeholder client names (acme, bolt-hvac) — real numbers only appear once the member edits them.

Where things land

File	What it is
README.md	Full setup + usage walkthrough, the "done" bar, and the file map.
run.py	The CLI entrypoint this skill drives (init, generate).
penny_dashboard/	The actual logic — margin math, visibility allowlist, adapters, rendering, alerts, config loading.
config/*.example.yaml	Templates init copies into the (gitignored) real config files.
tests/	pytest suite covering the margin math and the client-safe allowlist guarantee.