claude-home/paper-dynasty/card-evolution-prd/README.md

# PRD: Card Evolution System

**Document Status:** Draft v4.0 — Phase 0 complete, Phase 1 in progress
**Author:** Atlas (Principal Software Architect)
**Date:** 2026-03-10 (last updated 2026-03-17)
**Issue Reference:** Gitea #46 (Evolution), #49 (Crafting)
**Stakeholder:** Cal

## Implementation Status

| Phase | Status | Notes |
|-------|--------|-------|
| Phase 0 — Render Pipeline | ✅ Mostly complete | Browser persistence + lifespan hooks in main (2026.3.17). Self-hosted fonts (PR #96) and benchmark script (PR #95) still in next-release. |
| Phase 1 — Foundation | 🔄 In progress | Season stats models, formula engine, track catalog API, seed data all in main. SQL migration + Peewee models (PR #84) and evaluate endpoint (PR #98) pending on `card-evolution` branch. |
| Phase 2 — Rating Boosts | ⬜ Not started | |
| Phase 3 — Static Cosmetics | ⬜ Not started | |
| Phase 4 — Animated Cosmetics | ⬜ Not started | |

**Active branch:** `card-evolution` (paper-dynasty-database repo)
**Open PRs targeting card-evolution:** #84 (SQL migration + models), #98 (evaluate endpoint)

---

## Revision History

> **v4.0 (2026-03-11):** Added animated card support (APNG) and render pipeline optimization.
> Persistent browser instance replaces per-request Chromium launch (~3x per-card speedup).
> Concurrent upload pipeline with `asyncio.gather` (~10-20x total run speedup). Self-hosted
> fonts eliminate CDN dependency. APNG pipeline uses deterministic `--anim-progress` CSS custom
> property for reproducible frame capture. New Phase 0 (render optimization) added as pre-requisite.
> See [02-architecture.md](02-architecture.md#card-render-pipeline-optimization) and
> [08-display.md § 8.6](08-display.md#86-animated-card-pipeline).
>
> **v3.0 (2026-03-10):** Variant system redesigned to use deterministic hash-based variant
> numbering. `card.variant` (nullable) added to card table. `image_url` added to
> `battingcard`/`pitchingcard` for variant-specific rendered images with cosmetics baked in.
> Trading resets evolution (team-scoped progress). Card images rendered once per variant creation.
>
> **v2.0 (2026-03-10):** Major design pivot from opt-in enrollment model to passive, automatic,
> free evolution. Every card always evolves; currency sinks are cosmetics
> choice, not activation fees. Slot limits and abandonment mechanics removed.

---

## Table of Contents

| Chapter | Section | File |
|---------|---------|------|
| — | Executive Summary | [README.md](#executive-summary) (below) |
| 1 | Business Objectives and Success Metrics | [01-objectives.md](01-objectives.md) |
| 2 | System Architecture + Render Pipeline Optimization | [02-architecture.md](02-architecture.md) |
| 3 | Evolution Track Design | [03-tracks.md](03-tracks.md) |
| 4 | Milestone Challenge System | [04-milestones.md](04-milestones.md) |
| 5 | Rating Boost Mechanics | [05-rating-boosts.md](05-rating-boosts.md) |
| 6 | Database Schema | [06-database.md](06-database.md) |
| 7 | Card Model Changes and Variant System | [07-variant-system.md](07-variant-system.md) |
| 8 | Discord Display, Visual Identity, and Animated Cards | [08-display.md](08-display.md) |
| 9 | System Integrations (Crafting, Existing Systems) | [09-integrations.md](09-integrations.md) |
| 10 | Economy Design and Currency Sinks | [10-economy.md](10-economy.md) |
| 11 | Anti-Abuse Safeguards | [11-safeguards.md](11-safeguards.md) |
| 12 | API Endpoints | [12-api.md](12-api.md) |
| 13 | Implementation Phases and Checklists | [13-implementation.md](13-implementation.md) |
| 14 | Risk Register and Open Questions | [14-risks.md](14-risks.md) |

**Related files:**
- [Card Cosmetics Playground](../card-cosmetics-playground.html) — Interactive visual explorer for cosmetic options

---

## Executive Summary

### Project Overview

Card Evolution is a passive, automatic progression system that permanently upgrades cards as
players use them in games. Every card a team owns is always evolving — there is no opt-in,
no activation cost, and no slot limit. Players build attachment to specific cards by simply
playing games with them. When enough milestones accumulate, the card tiers up automatically
and its ratings improve.

The system takes direct inspiration from EA FC's Evolutions mechanic and adapts it to Paper
Dynasty's D20 probability engine, Discord-native UX, and PostgreSQL/Peewee architecture. The
v2.0 pivot strips away the management overhead (slots, activation fees, abandonment) that would
have made evolution feel like a second job and instead makes it feel like a natural reward for
playing the game.

### Core Design Philosophy

- **Passive and automatic**: Evolution happens in the background. Players do not enroll cards or
  manage slots. They play games; cards evolve.
- **Free to evolve**: Rating boosts cost nothing. Currency is spent on customization and cosmetics,
  not on unlocking basic progression.
- **Visible progress**: Players can always check any card's current evolution tier and milestone
  progress. The system rewards curiosity.
- **Premium expression layer**: Players who want to customize their card's visuals (frames,
  themes, animated effects) spend currency to do so. Flex culture is the monetization hook,
  not gatekeeping.

### Scope

This PRD covers:
- Passive evolution track structure and milestone types
- Lazy evaluation architecture against existing game data tables
- D20-safe rating boost calculations
- Premium cosmetic system
- Animated card rendering pipeline (APNG) for premium cosmetics
- All new database tables and changes to existing tables
- Discord embed design for evolved cards
- Interplay with the planned Crafting (#49) system
- Economy balance (cosmetics-based, not activation-based)
- A phased implementation plan

### Out of Scope

- The Crafting / Duplicate Merging system itself (covered in its own PRD, #49)
- Ranked mode (separate project)
- Mobile or web frontend