# DO-009 — Export FreshCards framework (Phase 9E)

**Date:** 2026-07-02
**Status:** Locally binding via OSCR-
**Replaces:** ad-hoc Card markup across all FVW apps (Oscar, FvRE, FVS)
**FVW tier:** §22 (FreshCard standard) + §23 (FreshCard implementation)

---

## Decision

Oscar exports the FreshCards framework as the canonical FVW v8 §22+§23
implementation. The pattern is:

- **One typed data model** (`FreshCardData`)
- **One renderer** (`FreshCard` component)
- **One registry** per app (mapping module IDs to their cards)
- **One composer** (deterministic rules-based, no LLM)
- **One toast host** that renders both text toasts and FreshCards

Other FVW apps (FvRE, FVS) embed the same files into their own `src/`
and adapt the registry to their modules.

## Why

Each FVW app has been building ad-hoc card markup with Mantine
`<Card>`. The patterns diverge across apps. Operators using multiple
FVW apps have to learn multiple card patterns.

A single framework:

- Reduces drift between apps
- Makes AI composition reusable
- Gives operators a consistent mental model
- Pins the §23 senior / ADHD affordances to a single implementation

## The contract

Any FVW app that embeds FreshCards MUST:

1. Use the `FreshCardData` type unchanged
2. Honour the §23 affordances (16px base font, 720px max width,
   single primary action, dark green contrast)
3. Register its own modules in a `registry.ts` that follows the
   same shape
4. Use the same `pinned_cards` / `dismissed_cards` IDB store names
   (so a future cross-app sync is possible)
5. Use the same `pushCard()` / `pushToast()` API for AI output

## What changes

| Before | After |
|---|---|
| Mantine `<Card>` for Tools, Home, toasts, AI suggestions | `<FreshCard>` everywhere |
| One-off state machines for "show the form summary" | One `form-summary` card kind |
| Per-app action handlers | One `FreshCardAction` shape |
| Per-app dismiss UX | One `<FreshCard>` `onDismiss` callback |

## What stays

- IDB schema (v12 with pinned_cards / dismissed_cards) is unchanged
- The `FreshCard` component is presentational only — no navigation,
  no persistence
- The composer remains deterministic (no LLM)
- The §23 affordance constants are preserved for the audit test

## FVW alignment

- FVW v8 §22 — FreshCard standard (single typed shape)
- FVW v8 §23 — FreshCard implementation (component + affordances)
- FVW v8 §35 — Contextual Surfaces
- FVW v8 §40 — Multimodal Capture
- FVW v8 §41 — Ambient AI (DO-008's pattern, now card-first)

## Migration for other FVW apps

FvRE: replace `src/components/Card.tsx` with the FreshCard framework.
FVS: replace the sidebar's assistant cards with FreshCard.
Other modules: ad-hoc Card markup → FreshCard registry entries.

No FVW app is required to migrate immediately. The framework is
additive — existing cards still work. New cards should use
FreshCard.

## Acceptance criteria

- [ ] `src/freshcards/` ships with types, renderer, registry, composer
- [ ] `src/freshcards/README.md` documents how to embed in another app
- [ ] Oscar's Home, Tools, Blog (rewrite), and the toast host all
      render through `FreshCard`
- [ ] The §23 audit test still passes (16px, #1a3d2e, 720px)
- [ ] `pinned_cards` + `dismissed_cards` stores exist in IDB v12
- [ ] AI composer returns up to 3 cards with confidence scores
- [ ] Other FVW apps can copy the 4 files and adapt the registry