feat(deck): Deck Builder & Engine Score epic — Phase 0 + Phase 1 (milestone #3)

.gitignore

@@ -90,6 +90,9 @@ apps/web/public/mockups/
 # Design handoff reference (Claude Design exports) — local-only, never committed
 apps/web/reveals page redesign/
 
+# Security audit findings — sensitive, keep out of the public repo
+docs/SECURITY_AUDIT.md
+
 # Tool / plugin local state — managed by their installers, not tracked
 .agents/
 .superpowers/

CLAUDE.md

@@ -2,6 +2,41 @@
 
 Lorcana synergy finder for Core format with archetype-based synergy detection.
 
+## Active Epic: Deck Builder & Engine Score (milestone #3)
+
+The flagship multi-session initiative. **Read these before starting any deck-builder work:**
+- **Plan (source of truth)**: [`docs/deck-builder/PLAN.md`](docs/deck-builder/PLAN.md) — full design + rationale (8 phases, E0–E7).
+- **Progress**: milestone #3 → `gh issue list --milestone "Deck Builder & Engine Score" --state all`. Epics #450–#457; Phase-0/1 tasks #458–#473.
+- **Session Handoff Log**: pinned issue **#474** — the running ledger. **Append an entry every session** (shipped / decisions / gotchas / in-progress / next); read the latest entry at session start.
+- **Working location**: the MAIN checkout (`D:\johnn\Projects\inkweave`) on branch `claude/inkweave-deck-builder-af3e5b`. Never work from a `.claude/worktrees/` folder: this epic's commits are unmerged, and `.claude/settings.json` wires the hooks to the main checkout by absolute path, so a worktree silently runs without `branch-verification` or `engine-auto-rebuild`.
+
+**Golden rules for this epic:**
+1. Deck-level synergy uses the **precomputed pairs JSON** (`pairs[id].aggregateScore`), NOT the live engine — lazy-import the engine only for hypothetical/preview cards.
+2. The advisor is **pool-driven + archetype-parameterized** — detect roles from card text/keywords, **never hardcode card names** (Core rotates).
+3. The Deck Quality Score is a **transparent weighted formula + case library**, never ML.
+4. Meta/matchups are **deferred** until the user's Set-13 data exists (Phase 6).
+
+**Session ritual (a process to run every session, not a hope):**
+
+_Start:_
+1. **Audit the previous session's close-out first.** Is `git status` clean and on `claude/inkweave-deck-builder-af3e5b`? Does the latest #474 comment exist and end with a `Next:` line? Do the issues touched last time have a note? If anything is missing, surface it to the user before starting new work.
+2. Read `docs/deck-builder/PLAN.md` and the latest #474 entry (its `Next:` line names your task).
+3. `gh issue list --milestone "Deck Builder & Engine Score" --state open`, then pick the next unblocked task. Auth (#463) and migrations (#464) need the user's OAuth apps + live-DB authorization, so skip them when running headless.
+4. `/implement-issue <num>`.
+
+_End or any pause (the close-out contract, in order, all of it):_
+1. **Adversarial review before committing.** Self-review the diff, or spawn a code-reviewer agent, for correctness, lifecycle/async edge cases, and convention. Fix what it finds. A green suite is necessary, not sufficient (that is how the #465 unmount-flush + async-ink bugs slipped past a passing session).
+2. **Commit** (WIP if incomplete). The pre-commit gate (lint + tests) must pass; never `--no-verify`. Nothing important stays only in the working tree.
+3. **Append a #474 entry**: shipped (with SHAs) / decisions + why / gotchas / in-progress / **`Next:`**. Always end with an explicit `Next:` line, even on a demo or review entry, so the next session finds the thread immediately.
+4. **Comment implementation notes** on each touched issue (decisions, deviations, carry-forward gotchas).
+5. **Write a memory file** for any durable gotcha that generalizes beyond this task.
+6. **Update `docs/deck-builder/PLAN.md`** if the design or scope changed.
+7. **Verify clean**: `git status` clean, scratch files removed, then `/close-session`.
+
+**Epic-issue convention:** the milestone's task issues (#458 onward) are compact pointers; their authoritative spec is `docs/deck-builder/PLAN.md` plus the reference files each one names, not a standalone ops-runbook. Override `/implement-issue`'s defaults deliberately (and say so, do not expand the issue): stay on the epic branch (do NOT cut a `feature/<n>-*` branch, since the work depends on this branch's unmerged commits), and treat its issue-quality rubric as not applicable (it scores production runbooks, not feature-code pointers).
+
+**Retire this whole section when milestone #3 closes.** It is the only always-loaded epic context in this file, and it should leave with the epic rather than becoming another stale block. It earns its place here only because the session ritual has no `paths:` trigger to hang a `.claude/rules/` file on: start-of-session process cannot be lazily loaded.
+
 ## MVP Status
 
 - **Scope**: Core format only (sets 9+), community voting, deck builder

apps/web/.storybook/preview.tsx

@@ -1,4 +1,7 @@
 import 'react-loading-skeleton/dist/skeleton.css';
+// Load the app's @font-face (Plus Jakarta Sans + Tinos, served from /public/fonts
+// via staticDirs) so stories render in the real app fonts, not system fallbacks.
+import '../src/index.css';
 import type {Preview} from '@storybook/react-vite';
 import {themes} from 'storybook/theming';
 

apps/web/e2e/E2E_TESTS.md

@@ -205,6 +205,8 @@ Terminal-state guard for the in-depth vote page (`/vote/:a/:b`). Complements `pa
 
 ## `reveals-page.spec.ts` — 8 tests (7 desktop, 1 mobile)
 
+**Seasonal — the whole suite auto-skips off-season.** `beforeEach` reads `/data/previewCards.json` and `test.skip`s when there are no revealed cards (`cards: []`, e.g. after a set graduates into `allCards.json`) or the release date has passed. Skipping happens before any 30s-timeout wait, so the suite is dormant (not failing) whenever there is nothing to reveal, and resumes automatically once the next set's reveal data is populated.
+
 | Test | What it verifies |
 |---|---|
 | renders the tracker: hero, six ink trackers, and franchise cards | sr-only `h1`, the "Attack of the Vine!" logo, 6 `ink-tracker-tile`s, the "Ink board" section, and the 3 "View … cards" franchise buttons all render |

apps/web/e2e/tests/reveals-page.spec.ts

@@ -1,5 +1,29 @@
 import {test, expect} from '../fixtures';
 
+/**
+ * Why the reveals suite is off-season-gated: the whole page only exists during a
+ * reveal season, so off-season the assertions cannot pass. Two off-season signals,
+ * either of which means "skip cleanly", checked BEFORE any 30s-timeout-prone wait:
+ *   1. No revealed cards at all — previewCards.json cards: [] (the primary signal;
+ *      once a set graduates its cards move into allCards.json and this file empties).
+ *   2. Past the set's releaseDate — useRevealPhase returns 'released', RevealsGate
+ *      redirects /reveals -> / and the nav entry / promo modal drop.
+ * Returns the skip reason, or null when a reveal season is genuinely active.
+ */
+function offSeasonSkipReason(data: unknown): string | null {
+  const d = (data ?? {}) as {cards?: unknown; sets?: Record<string, {releaseDate?: string} | undefined>};
+  const revealCount = Array.isArray(d.cards) ? d.cards.length : 0;
+  if (revealCount === 0) return 'No active reveal season (previewCards.json has no revealed cards).';
+  const dates = Object.values(d.sets ?? {})
+    .map((s) => s?.releaseDate)
+    .filter((x): x is string => typeof x === 'string');
+  const latestRelease = dates.length ? Math.max(...dates.map((x) => new Date(x).getTime())) : 0;
+  if (latestRelease > 0 && Date.now() >= latestRelease) {
+    return `Reveal season ended (latest releaseDate ${new Date(latestRelease).toISOString().slice(0, 10)}).`;
+  }
+  return null;
+}
+
 test.describe('Reveals page (flag on)', () => {
   test.beforeEach(async ({page}, testInfo) => {
     // Clear the daily-dismiss key so the promo modal reliably appears.
@@ -12,27 +36,10 @@ test.describe('Reveals page (flag on)', () => {
     });
     testInfo.annotations.push({type: 'requires', description: 'VITE_IS_REVEAL_SEASON=true'});
 
-    // Skip when reveal season has ended (today is past the set's releaseDate).
-    // useRevealPhase returns 'released' once now >= releaseDate, RevealsGate
-    // redirects /reveals -> /, and the Reveals nav entry / promo modal no
-    // longer render — so these reveal-season-only assertions can't pass.
-    // After each set graduates and previewCards.json is refreshed with the
-    // NEXT set's dates, these tests pick back up automatically.
+    // Skip the whole suite off-season (see offSeasonSkipReason), before any wait.
     const resp = await page.request.get('/data/previewCards.json');
-    if (resp.ok()) {
-      const data = await resp.json();
-      const sets = (data?.sets ?? {}) as Record<string, {releaseDate?: string} | undefined>;
-      const dates = Object.values(sets)
-        .map((s) => s?.releaseDate)
-        .filter((d): d is string => typeof d === 'string');
-      const latestRelease = dates.length ? Math.max(...dates.map((d) => new Date(d).getTime())) : 0;
-      if (latestRelease > 0 && Date.now() >= latestRelease) {
-        test.skip(
-          true,
-          `Reveal season ended (latest releaseDate ${new Date(latestRelease).toISOString().slice(0, 10)})`,
-        );
-      }
-    }
+    const reason = resp.ok() ? offSeasonSkipReason(await resp.json()) : null;
+    test.skip(reason !== null, reason ?? '');
   });
 
   test('renders the tracker: hero, six ink trackers, and franchise cards', async ({page}, testInfo) => {