# FuelAlert — Tier Feature Design (Free / Basic / Plus / Pro)

## Context

The existing tier rules (`.claude/rules/tiers.md`) define notification channels
per plan but not the *information* features that make each tier feel worth
paying for. This spec closes that gap by cataloguing always-on information,
personalisation, and analytics features — the value a user sees whether or not
a notification fires — and mapping them to the four tiers. Triggered channel
rules (email/push/WhatsApp/SMS) remain unchanged and are not redefined here.

Goals:
- Give each upgrade a concrete "what do I get for £X more" answer.
- Keep free tier useful enough to retain, but with clear ceiling.
- Keep Plus the commercial sweet spot (LLM prediction + fuel logs + MPG).
- Keep Pro genuinely premium (unlimited, multi-location, route planning, family sharing).

Teaser strategy: **hybrid** — headline features (prediction, extended history,
detailed confidence) are visible but blurred with an upgrade CTA on Free; minor
Pro-only features (route planner, family sharing) are hidden from lower tiers.

---

## Feature Matrix

### 1. Fill-up recommendation (from `AlertScoringService`)

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Recommendation (`fill_up` / `wait` / `no_signal`) | ✓ | ✓ | ✓ | ✓ |
| Confidence % + reason string | — | ✓ | ✓ | ✓ |
| Per-signal breakdown (which of 5 signals fired, weights) | — | — | — | ✓ |
| Accuracy self-tracking ("our last wait call saved you Xp/L") | — | — | ✓ | ✓ |

### 2. Oil price prediction (from `price_predictions`)

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Direction only (EWMA, no reasoning) | — | ✓ | ✓ | ✓ |
| Full LLM prediction (direction + confidence + reasoning) | — | — | ✓ | ✓ |
| Historical prediction accuracy view | — | — | — | ✓ |

Rationale: Basic sees *that* prices are expected to rise/fall; Plus sees *why*.

### 3. Price history & trends

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Local price today | ✓ | ✓ | ✓ | ✓ |
| Price history chart | 7 days | 14 days | 90 days | 365 days |
| Brand comparison ("Tesco avg vs Shell avg near you") | — | — | ✓ | ✓ |
| Local price leaderboard (cheapest N nearby) | top 3 / 5km | top 5 / 5km | top 10 / 15km | top 20 / 50km |

### 4. Saved data & personalisation

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Saved home postcode | ✓ | ✓ | ✓ | ✓ |
| Tracked fuel types | 1 | 1 | 1 | unlimited |
| Saved stations (favourites) | 1 | 3 | 10 | unlimited |
| Multiple locations (home/work/commute) | — | — | 2 | 5 |
| Custom price thresholds per fuel/station | — | 1 | 3 | unlimited |

(Fuel-type cap for free/basic/plus matches existing `tiers.md` rule.)

### 5. Fuel logs & personal analytics (new)

Simple log: date, litres, price per litre, optional odometer.

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Log fill-ups (basic entry) | — | last 10 | last 100 | unlimited |
| MPG / cost-per-mile (needs odometer) | — | — | ✓ | ✓ |
| Monthly spend report | — | — | ✓ | ✓ |
| "You saved £X by following our advice" attribution | — | — | — | ✓ |
| CSV export of fuel log | — | — | — | ✓ |

### 6. Tools (new, mostly Pro)

| Feature | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| Route planner — cheapest station along A→B | — | — | — | ✓ |
| Commute calculator — is the detour worth it? | — | — | — | ✓ |
| Family / household sharing (2 extra members on one account) | — | — | — | ✓ |

---

## Plan `features` JSON shape (additions)

Extend the existing `features` JSON in the `plans` table (see `tiers.md` for
existing shape). New keys to add:

```json
{
  "history_days": 7,
  "prediction": { "level": "none" },
  "recommendation": { "confidence_visible": false, "signal_breakdown": false, "accuracy_tracking": false },
  "leaderboard": { "count": 3, "radius_km": 5 },
  "saved_stations": { "max": 1 },
  "locations": { "max": 1 },
  "thresholds": { "max": 0 },
  "fuel_log": { "enabled": false, "max_entries": 0, "mpg": false, "monthly_report": false, "savings_attribution": false, "csv_export": false },
  "brand_comparison": false,
  "route_planner": false,
  "commute_calculator": false,
  "family_sharing": { "enabled": false, "max_members": 0 }
}
```

`prediction.level` values: `none` | `direction` (EWMA only) | `full` (LLM +
reasoning) | `full_with_accuracy` (Pro).

### Seeded values per tier

| Key | Free | Basic | Plus | Pro |
|---|---|---|---|---|
| `history_days` | 7 | 14 | 90 | 365 |
| `prediction.level` | `none` | `direction` | `full` | `full_with_accuracy` |
| `recommendation.confidence_visible` | false | true | true | true |
| `recommendation.signal_breakdown` | false | false | false | true |
| `recommendation.accuracy_tracking` | false | false | true | true |
| `leaderboard.count` / `radius_km` | 3 / 5 | 5 / 5 | 10 / 15 | 20 / 50 |
| `saved_stations.max` | 1 | 3 | 10 | null (unlimited) |
| `locations.max` | 1 | 1 | 2 | 5 |
| `thresholds.max` | 0 | 1 | 3 | null |
| `fuel_log.enabled` | false | true | true | true |
| `fuel_log.max_entries` | 0 | 10 | 100 | null |
| `fuel_log.mpg` | false | false | true | true |
| `fuel_log.monthly_report` | false | false | true | true |
| `fuel_log.savings_attribution` | false | false | false | true |
| `fuel_log.csv_export` | false | false | false | true |
| `brand_comparison` | false | false | true | true |
| `route_planner` | false | false | false | true |
| `commute_calculator` | false | false | false | true |
| `family_sharing.enabled` / `max_members` | false / 0 | false / 0 | false / 0 | true / 2 |

---

## Out of scope (explicit)

- Implementation of route planner, commute calculator, brand comparison, family sharing — this spec gates them but their actual logic/UI is separate projects.
- Fuel log UI/import — separate project; this spec only defines the model and caps.
- Ads on free tier — dropped per user decision.
- Public API, shareable widgets, early access flags — dropped per user decision.