# Weekly growth scorecard

Every founder keeps a spreadsheet of weekly KPIs: spend, clicks, signups,
followers, conversion rate, week-over-week change. FunnelKeeper already holds
most of those numbers. The **Scorecard** is that grid, auto-filled from the
warehouse, with a cell you can type when a source does not exist yet.

Tell your agent to keep it current. That is the adoption path.

## Surfaces

| Surface | Call |
|---|---|
| Dashboard | Project → **Scorecard** |
| MCP | `get_scorecard` · `set_scorecard` · `record_scorecard_values` · `suggest_scorecard` · `export_scorecard` · `share_scorecard` |
| REST | `GET /products/{slug}/scorecard` |
| CLI | `fk scorecard --product <slug>` · `fk scorecard set --metric blog.posts --week 2026-08-18 --value 2` |
| Public | Share link (`#/scorecard/<token>`) — read-only, for build-in-public |

## What fills itself

Auto cells roll day-grain warehouse facts into **ISO weeks** (Monday start;
column label is the Sunday). History follows the plan window (Free ≈ 13 weeks).

- Paid spend / clicks / attributed signups — `spend_records` + `events.channel`
- Visitors (total / organic / social / paid) — visit-stage events
- Search clicks and impressions — Search Console / Bing
- Followers, posts, interactions — Meta Social and X snapshots
- Signups, leads, revenue, ICP grades (`events.props.score`)
- Derived: cost per signup, visitor → signup rate, cumulative signups

Manual cells (blog posts, LinkedIn organic, TikTok, YouTube) are typed in the
grid, or written by an agent via `record_scorecard_values`. They are CONFIG,
not append-only facts — a correction overwrites the cell and is audited.

## MCP flow

```text
1. get_scorecard { slug, weeks: 12 }
   → sections → metrics → values[] + wow

2. If a cell is missing (blog posts, a network we do not read):
   record_scorecard_values { slug, actor, cells: [{ metric_key, week_start, value }] }
   week_start is the ISO Monday (YYYY-MM-DD).

3. To change the rows: suggest_scorecard (proposals only), then set_scorecard
   after the human accepts. Never invent a metric_ref — use catalog keys.

4. export_scorecard returns CSV (Growth). Excel is on the dashboard.
```

CLI equivalent:

```bash
fk scorecard --product demo-product --weeks 12
fk scorecard set --product demo-product --metric blog.posts --week 2026-08-18 --value 2
fk scorecard export --product demo-product --out scorecard.csv
```

## Templates

`default` (from connected sources), `saas_waitlist`, `paid_acquisition`,
`content_led`. Apply from the Customise drawer or `POST …/scorecard/template`.

## Insights

Monday, the Keeper raises the largest week-on-week swings as insight cards
(headline ≤90 chars + one metric line). Growth plans get LLM phrasing; every
plan gets the deterministic pass. The same lines ride the weekly digest email.

## Google Sheets

Push-only. The warehouse stays the source of truth — we never read edits back.
Requires `GOOGLE_SHEETS_OAUTH=1` on the API **and** the `spreadsheets` scope
on the Google consent screen. Existing Google grants do not gain the scope;
reconnect after the owner adds it. Growth plan.

## Plans

| Capability | Free | Indie | Growth |
|---|---|---|---|
| Grid + manual cells | yes | yes | yes |
| History | 3 months | 12 months | all |
| LLM metric suggestions | — | yes | yes |
| CSV / Excel / Sheets | — | — | yes |