# "What's New" Plan

## Status: planning only — nothing in this doc is implemented yet

The problem this solves: `apps/web/lib/changelog.ts`'s `CHANGELOG` array is
a dev log — migration reminders, bug-fix jargon, internal notes ("not
applied in sandbox") mixed in with real feature announcements. Correctly
not public (per `VITRINE_PLAN.md` §6, which flagged this gap). Users have
no clean way to see what's new since they last looked.

**Existing precedent to mirror, not reinvent**: `apps/web/components/social/notification-bell.tsx`
is exactly this UI shape already — bell icon, unread badge, dropdown list,
polling `GET` on an interval, a "mark read" POST. Same skeleton, new data
source.

---

## 1. Content — extend `ChangelogEntry`, don't fork a second data source

Add one optional field to the existing type in `apps/web/lib/changelog.ts`:

```ts
export type ChangelogEntry = {
  version: string;
  date: string;
  added?: string[];
  fixed?: string[];
  security?: string[];
  notes?: string;
  highlights?: string[]; // user-facing, plain language — only set on entries worth telling users about
};
```

Only versions with `highlights` populated ever show up in the "What's New"
panel — everything else in `CHANGELOG` stays exactly as dev-facing as it is
today. This is a deliberate editorial step, not automatic: when a version
ships something a real user would care about, someone (you) writes one or
two `highlights` lines in plain language, same commit as the `added`/`fixed`
entries. Retroactively, only add `highlights` to past entries actually worth
surfacing — no need to backfill all 47+ versions, most were internal
fixes/refactors nobody needs a notification about.

---

## 2. Schema

One column, `apps/web/packages/db/src/schema/users.ts`:
```ts
lastSeenChangelogVersion: text("last_seen_changelog_version"),
```
Nullable. On the migration, backfill existing users to the current
`APP_VERSION` at migration time (not `null`) — otherwise every existing
user sees the entire history of `highlights` entries as "new" the moment
this ships, which is noise, not a useful announcement. New signups after
this ships get set to `APP_VERSION` at account-creation time for the same
reason — someone who just joined doesn't need to be told about features
that existed before they showed up.

---

## 3. API

- **`GET /api/v1/whats-new`** — compares the user's `lastSeenChangelogVersion`
  against `CHANGELOG` (imported directly, no DB query needed for the content
  itself — it's a static in-code array), returns every entry with
  `highlights` whose version is newer (semver comparison, not string
  comparison — `"0.9.0" < "0.10.0"` is false under plain string compare).
  A tiny local semver-compare helper is enough; no need for a package for
  a 3-segment version string this app already controls end to end.
- **`POST /api/v1/whats-new/seen`** — sets `lastSeenChangelogVersion` to the
  current `APP_VERSION` for the calling user. Called when the panel opens
  (or on explicit dismiss — same UX choice `NotificationBell`'s `markAllRead`
  already made for regular notifications, mirror whichever this app's
  notifications settled on).

Both gated by `requireSessionOrApiKey`, same as every other authenticated
route — no new auth pattern needed.

---

## 4. UI

New component `apps/web/components/layout/whats-new-bell.tsx`, structurally
identical to `NotificationBell`: bell/gift icon, badge showing count of
unseen highlighted versions, dropdown listing them (version, date, bullet
list of that version's `highlights`), placed in `apps/web/components/layout/nav.tsx`
next to the existing `NotificationBell`/`MessagesNavLink` icons in the
authenticated header.

Not a public/vitrine concern — this lives entirely inside the authenticated
app shell, unrelated to `VITRINE_PLAN.md`'s route group.

---

## 5. Rollout order

1. Schema migration (backfill existing users to current `APP_VERSION`) — no visible change yet.
2. `highlights` field on `ChangelogEntry` + write it for the next few versions going forward, so there's something to show once the UI ships.
3. API routes.
4. `WhatsNewBell` component wired into `nav.tsx`.
5. Retroactively add `highlights` to a handful of past standout versions (the tier system, the cooking-assistant tools, followers-only visibility) if you want new/returning users to see a bit of history on first exposure, not just what ships after this point.