# Dynasty Live Product Spec

Status: Draft 0.7  
Last updated: 2026-07-21  
Primary goal: Build a local-first companion app that turns College Football 27 dynasty save files and game screenshots into a living, interactive dynasty world.

## 1. Vision

Dynasty Live should feel like a real college football media ecosystem built around a user's actual dynasty save. Each in-game week, the user imports or syncs a save file, optionally uploads screenshots from played games, and the app builds a browsable world containing factual data, generated coverage, storylines, social reactions, recruiting drama, press conferences, and historical memory.

The app should never replace the dynasty save as the source of truth. The save file and screenshots provide facts. AI turns those facts into presentation, narrative, and interaction. The MVP should prioritize the user's team while still generating enough national context for the dynasty to feel alive.

## 2. Product Principles

1. Facts first, fiction second.
   - Parsed save data and corrected OCR data are canonical.
   - AI-generated content must cite or link back to source facts internally.
   - Generated stories should not invent scores, stats, injuries, commitments, or job moves.

2. Local-first for the first phase.
   - The MVP should run locally on the user's machine.
   - No hosted account, subscription, or cloud dependency should be required.
   - Later hosting should build on the same data model.

3. Read-only save handling.
   - The MVP must never write back to dynasty saves.
   - Every imported save should be copied into an app-managed snapshot archive before parsing.
   - If save writing is ever added later, it must be a separate feature with backups, warnings, and CFB27-specific safe writer validation.

4. Explainable generated world.
   - Every story, recap, social post, or press conference should have traceable source evidence.
   - Users should be able to correct OCR and override generated text.

5. Weekly workflow should be fast.
   - The user should be able to advance in-game, import the new save, add screenshots, and see an updated world without manual data entry beyond correcting mistakes.

## 3. Target Users

### Primary User

A single-player dynasty user who wants their save to feel like a persistent sports universe.

Needs:
- Weekly recaps and headlines.
- Better memory than the game provides.
- User-team-first coverage with national context.
- Team/player history.
- A fun browser-based portal to browse between games.

### Future Users

Hosted or shared-dynasty users.

Needs:
- User accounts.
- Cloud import/sync.
- Shareable public dynasty portals.
- Multi-user permissions.
- Privacy controls.
- Potential support for multiple dynasties per user.

## 4. MVP Scope

The MVP should prove the full weekly loop with a narrow but real slice:

1. Import one College Football 27 dynasty save snapshot.
2. Parse core dynasty data.
3. Optionally upload screenshots for one played game.
4. Extract highlight and box score data when screenshots are available.
5. Generate user-team-first narrative content from parsed facts, with national context.
6. Display everything in a desktop app with an embedded/local browser portal.
7. Save the processed week and generated artifacts for later weeks.

MVP coverage priority:

1. User team game and weekly situation.
2. User team's upcoming opponent and conference context.
3. Major national results, rankings, and award context when reliably parsed.
4. Other games only when they create meaningful national storylines.

### MVP User Flow

1. User opens Dynasty Live.
2. User selects or confirms the configured save folder and save file.
3. App detects the configured dynasty save and shows the last imported week.
4. User clicks one import action to load the latest data from the same save file each week.
5. App copies the save into its permanent snapshot archive.
6. App parses save data into local storage.
7. App checks the screenshot generation setting.
8. If screenshots are required, app waits for upload before rich generation.
9. If screenshots are optional or skipped, app generates a save-only version with adjusted prompts.
10. If screenshots are uploaded, app OCRs screenshots and groups them by game.
11. User reviews/corrects OCR output when screenshots are present.
12. App generates game recap, headlines, social posts, short-form updates, and weekly news.
13. User browses the updated dynasty world in the desktop app.

### MVP Data Domains

Required:
- Dynasty identity and calendar.
- Teams.
- Conferences.
- Coaches.
- Players and rosters.
- Schedule and game results.
- Team game stats.
- Player game stats.
- Rankings/polls if reliably extractable.
- Screenshot-derived highlights when screenshots are available.
- Screenshot-derived box score lines when screenshots are available.
- Generated game recaps.
- Generated social feed.
- Generated weekly hub.
- Editable generated content.
- Editable prompt templates.
- Prompt packs.
- AI provider settings.
- Persistent fictional reporters, fan accounts, and analysts.
- Interactive press conference framework.
- Coach relationship tracking.
- Formula-driven player grades with AI context/explanation.

Useful but not required in the first working version:
- Heisman watch.
- Awards.
- Team/player longform pages.

Explicitly post-MVP:
- Recruiting board and recruiting media.
- Coaching carousel.
- Storyline pinning.

### MVP Screens

1. Import Screen
   - Select save folder and primary dynasty save file.
   - Show detected dynasty, current season, week, and user team.
   - Show last imported snapshot.
   - Provide one-click "Import Latest" for the configured save file.
   - Show import status and parsing errors.

2. Screenshot Upload Screen
   - Drag/drop screenshots.
   - Choose screenshot type if auto-detection fails.
   - Respect the user's screenshot setting:
     - Wait for screenshots before generation.
     - Generate save-only content immediately.
     - Ask each week.
   - Supported MVP types:
     - Game highlights list.
     - Passing stats.
     - Rushing stats.
     - Receiving stats.
   - Later types:
     - Defensive stats.
     - Team stats.
     - Scoring summary.
     - Recruiting screens.

3. OCR Review Screen
   - Show extracted rows beside source screenshot.
   - Allow user correction.
   - Dedupe repeated highlight rows from overlapping screenshots.
   - Assign screenshots to a game if not auto-matched.

4. Weekly Hub
   - Current week.
   - Scoreboard.
   - Top games.
   - Main storylines.
   - Rankings movement.
   - User team panel.

5. Game Center
   - Final score.
   - Quarter scores.
   - Team stats.
   - Player leaders.
   - Highlight timeline.
   - AI recap.
   - AI quotes/social posts.
   - Box score.
   - Player grades.
   - Social reaction.
   - Press conference entry point.

6. Story Feed
   - Generated news cards.
   - Filter by team, player, conference, national.
   - Show source facts or evidence on demand.
   - Generated content publishes immediately.
   - Users can edit or regenerate after publishing.

7. AI Settings Screen
   - Configure provider base URL.
   - Configure API key.
   - Configure model name.
   - Test provider connection.
   - Select default provider/model for each content type.
   - Manage prompt packs.

8. Prompt Editor Screen
   - View and edit prompt templates.
   - Separate prompts for save-only generation and screenshot-enriched generation.
   - Store prompt edits per dynasty.
   - Track prompt version.
   - Restore defaults.

9. Personalities Screen
   - View recurring fictional reporters, fans, insiders, and analysts.
   - Assign tone, outlet/account type, team affinity, and content types.
   - Personalities are generated automatically from prompt-pack archetypes.
   - Example archetypes:
     - Local positive reporter who tends to spin outcomes favorably.
     - Local antagonist who looks for controversy.
     - National reporter who chases clicks.
     - Serious beat reporter focused on facts.
     - Former player analyst focused on locker-room dynamics.
   - Enable or disable individual personalities.

10. Press Conference Screen
   - Show AI-generated reporter questions after a game or major event.
   - For each question, offer three generated response choices:
     - Hostile response.
     - Coach-speak response.
     - Direct response.
   - Allow the user to type a custom response.
   - Apply relationship changes after each answer.
   - Generate a press conference recap after all questions are answered.
   - Generate public response from fans, media, locker room, school leadership, and boosters.

## 5. Future Feature Roadmap

### Phase 2: Deeper Dynasty Portal

- Team pages:
  - Schedule/results.
  - Roster.
  - Season leaders.
  - Coach profile.
  - Program trajectory.

- Player pages:
  - Bio.
  - Game logs.
  - Career stats.
  - Awards/watchlist status.
  - Generated player storyline.

- Conference pages:
  - Standings.
  - Conference title race.
  - Power rankings.
  - Key upcoming games.

- Rankings and playoff race:
  - Poll movement.
  - Resume cards.
  - Strength of schedule if derivable.
  - Bubble teams.

- Expanded press conferences:
  - More reporter personalities.
  - Season-long question memory.
  - Rivalry/week-specific question themes.
  - Follow-up questions based on prior answers.

### Phase 3: Recruiting World

- Recruiting dashboard:
  - User board.
  - Top targets.
  - Team interest.
  - Visits.
  - Commitments.
  - Decommitments/flips if detected.
  - Team recruiting class panel.

- Recruit pages:
  - Bio and ratings.
  - Top schools.
  - Dealbreakers.
  - Visit history.
  - Generated scouting report.

- Recruiting media:
  - Recruiting roundup.
  - Insider rumors.
  - Commitment announcements.
  - Visit previews.
  - Flip watch.

### Phase 4: Coaching Carousel

- Hot seat tracker.
- Live job openings.
- Candidate boards.
- Hiring grades.
- Press conferences.
- Fan and reporter reactions.
- Coach career histories.

The existing week 18 sample appears useful for validating live `JobOpening` parsing.

### Phase 5: World Memory and Personalities

- Persistent generated reporters, fan accounts, analysts, and insiders.
- Tone profiles per source.
- Long-running story arcs:
  - Rivalry heat.
  - Revenge games.
  - Breakout stars.
  - Failed expectations.
  - Coaching pressure.
  - Recruiting battles.
- Dynasty history pages:
  - National champions.
  - Conference champions.
  - Heisman winners.
  - Award winners.
  - Coach moves.
  - Record book.

### Phase 6: Hosted Version

- User accounts.
- Multiple dynasties per user.
- Cloud upload/import queue.
- Hosted web portal.
- Public/private sharing.
- Local-to-cloud sync.
- Usage limits for AI generation.
- Optional server-side OCR/AI.
- Team branding and asset CDN.

## 6. Technical Architecture

### Recommended MVP Architecture

Use a local Node-based app stack because the save parsing ecosystem is already Node-oriented.

Proposed components:

1. Desktop app shell
   - Desktop app is required from day one.
   - Electron is the recommended starting point because the save parser stack is Node-oriented.
   - A lighter Tauri shell remains possible later but would still likely call Node for parsing.
   - The shell handles file selection, imports, screenshot upload, and local API startup.

2. Parser package
   - Uses `madden-franchise` with CFB27 schema support.
   - Reads save files only.
   - Resolves tables by uniqueId and followed references, not hardcoded tableIds.
   - Emits normalized domain objects.

3. OCR package
   - Uses screenshot classifiers and fixed-region crop templates.
   - Extracts highlight list and stat table rows.
   - Stores raw OCR text and corrected values.

4. Local database
   - SQLite for MVP.
   - Stores parsed facts, snapshots, OCR output, corrections, generated artifacts, and source links.

5. AI orchestration package
   - Calls local and cloud models through an OpenAI-compatible provider interface.
   - Provider configuration should use base URL, API key, and model name.
   - Local examples include Ollama, LM Studio, or any OpenAI-compatible local server.
   - Cloud providers can be supported as long as they expose an OpenAI-compatible API.
   - Different content types can use different providers and models.
   - Supports prompt templates and structured JSON outputs.
   - Stores model name, prompt version, source facts, and output.

6. Web portal
   - React/Vite or Next.js.
   - Reads from local API.
   - Provides dashboard, game center, story feed, and correction UI.

### Future Hosted Architecture

The hosted version should reuse the same canonical data shape:

- Local app imports and parses saves.
- Local app uploads normalized facts and screenshots, not raw saves by default.
- Cloud worker runs OCR/AI if enabled.
- Hosted API serves dynasty portals.
- Public portal can be read-only.
- Private portal can support editing/corrections.

Open privacy decision:
- Should raw save files ever be uploaded to hosted infrastructure?
- Safer default: no. Parse locally, upload normalized data and optional images only.

## 7. Data Model Draft

### Core Tables

- `dynasty`
  - id
  - league_id
  - display_name
  - game_version
  - user_team_id
  - active_save_folder
  - active_save_file
  - created_at

- `snapshot`
  - id
  - dynasty_id
  - source_file_name
  - source_hash
  - imported_at
  - season_year
  - dynasty_year
  - week
  - week_type
  - stage
  - offseason_stage

- `team`
  - id
  - dynasty_id
  - game_team_index
  - name
  - abbreviation
  - conference_id
  - prestige
  - colors

- `coach`
  - id
  - dynasty_id
  - game_row
  - first_name
  - last_name
  - role
  - team_id
  - archetype

- `player`
  - id
  - dynasty_id
  - game_row
  - first_name
  - last_name
  - team_id
  - position
  - jersey_number
  - class_year
  - overall

- `game`
  - id
  - snapshot_id
  - season_year
  - week
  - week_type
  - home_team_id
  - away_team_id
  - home_score
  - away_score
  - quarter_scores
  - status
  - is_simmed
  - attendance
  - weather
  - is_major_game
  - major_game_reasons_json

- `game_team_stats`
  - id
  - game_id
  - team_id
  - first_downs
  - total_yards
  - offensive_yards
  - passing_yards
  - rushing_yards
  - turnovers
  - sacks
  - third_downs
  - fourth_downs
  - penalties
  - possession_seconds

- `game_player_stats`
  - id
  - game_id
  - player_id
  - team_id
  - stat_group
  - stat_payload_json
  - source_table
  - source_row

- `player_game_grade`
  - id
  - game_id
  - player_id
  - team_id
  - formula_score
  - grade_label
  - formula_inputs_json
  - prior_grade_context_json
  - ai_context_summary
  - created_at

- `play_highlight`
  - id
  - game_id
  - source_screenshot_id
  - quarter
  - clock
  - rating
  - down_distance
  - field_position
  - raw_text
  - normalized_text
  - play_type
  - players_json
  - corrected_by_user

- `ai_artifact`
  - id
  - dynasty_id
  - snapshot_id
  - provider_id
  - artifact_type
  - entity_type
  - entity_id
  - title
  - body
  - model
  - prompt_version
  - full_prompt_text
  - source_evidence_json
  - publication_status
  - created_at

- `ai_provider`
  - id
  - display_name
  - base_url
  - api_key_ref
  - default_model
  - is_enabled

- `content_generation_setting`
  - id
  - dynasty_id
  - content_type
  - provider_id
  - model
  - prompt_template_id
  - is_enabled

- `prompt_pack`
  - id
  - dynasty_id
  - name
  - base_pack_key
  - is_default
  - is_custom_copy
  - copied_from_pack_id
  - created_at

- `prompt_template`
  - id
  - dynasty_id
  - prompt_pack_id
  - template_key
  - display_name
  - content_type
  - generation_mode
  - body
  - version
  - is_default
  - updated_at

- `social_account`
  - id
  - dynasty_id
  - display_name
  - handle
  - account_type
  - outlet
  - team_affinity_id
  - archetype
  - tone_profile
  - is_enabled

- `screenshot`
  - id
  - dynasty_id
  - snapshot_id
  - original_file_name
  - stored_path
  - file_hash
  - screenshot_type
  - imported_at

- `coach_relationship_state`
  - id
  - dynasty_id
  - coach_id
  - locker_room_score
  - fan_score
  - media_score
  - school_score
  - booster_score
  - scale_min
  - scale_max
  - updated_at

- `coach_relationship_event`
  - id
  - dynasty_id
  - snapshot_id
  - coach_id
  - source_type
  - source_id
  - locker_room_delta
  - fan_delta
  - media_delta
  - school_delta
  - booster_delta
  - explanation
  - created_at

- `press_conference`
  - id
  - dynasty_id
  - snapshot_id
  - game_id
  - coach_id
  - trigger_reason
  - question_count
  - status
  - recap
  - public_response
  - created_at

- `press_conference_question`
  - id
  - press_conference_id
  - reporter_account_id
  - question_text
  - question_type
  - topic
  - tone
  - sort_order

- `press_conference_response_option`
  - id
  - question_id
  - response_type
  - response_text
  - effect_preview_label_json
  - effect_preview_delta_json
  - effect_preview_json
  - relationship_effects_json

- `press_conference_answer`
  - id
  - question_id
  - selected_response_type
  - response_text
  - ai_grade_json
  - relationship_effects_json
  - created_at

### Later Tables

- `recruit`
- `recruiting_board`
- `recruiting_event`
- `coach_transaction`
- `poll_ranking`
- `award_ranking`
- `storyline`
- `social_post`
- `user_correction`

## 8. Save Parsing Requirements

### Known Save Data Sources

Research docs indicate these areas are important:

- Save container and schema:
  - `docs/research/01-save-file-format.md`
- Table inventory:
  - `docs/research/02-table-inventory.md`
- Calendar/stages:
  - `docs/research/05-calendar-and-stages.md`
- Recruiting:
  - `docs/research/04-recruiting.md`
- Coaches/carousel:
  - `docs/research/03-coaches-and-carousel.md`
- Design implications:
  - `docs/research/06-tool-design-implications.md`

### Parser Rules

1. Use `getTableByUniqueId` where possible.
2. Do not assume tableId stability across game builds or dynasty branches.
3. Follow references from records to array tables.
4. Treat duplicate table names as unsafe.
5. Include subclass stat tables when parsing player game stats.
6. Store source table uniqueId, tableId, row, and field names for debuggability.
7. Do not write to the save file.

### Save Snapshot Strategy

On import:

1. Compute file hash.
2. Copy save into app-managed archive.
3. Detect whether snapshot has already been imported.
4. Parse into normalized facts.
5. Diff against prior snapshot from same dynasty.
6. Generate change events.

Change events should power story triggers, such as:
- Upset result.
- Blowout.
- Ranked team loss.
- Player breakout.
- Injury if available.
- Poll movement.
- Award watch movement.

Post-MVP change event triggers:
- Recruit commitment.
- Decommitment.
- Coach fired/hired.

### MVP Import Mode

MVP import is manual but optimized for a repeated weekly save.

The user configures:
- Save folder.
- Primary save file.

Each week:
- User advances/saves in College Football 27.
- User opens Dynasty Live.
- User clicks `Import Latest`.
- App reads the configured save file, snapshots it permanently, and imports any new data.

Folder watching is post-MVP unless it becomes trivial.

### Dynasty Support

The MVP supports one active local dynasty.

Implementation should still keep `dynasty_id` in storage so adding multiple dynasties later does not require a data model rewrite. The UI can stay single-dynasty until there is a clear need for switching.

Imported saves should be organized internally by detected dynasty even though the MVP UI only exposes one active dynasty. This keeps archive/storage behavior compatible with future multi-dynasty support.

## 9. Screenshot and OCR Requirements

### MVP Screenshot Types

1. Highlight list
   - Quarter.
   - Clock.
   - Rating.
   - Down/distance.
   - Field position.
   - Play text.

2. Passing stats
   - Player.
   - Team.
   - Rating.
   - Completions/attempts.
   - Yards.
   - Completion percent.
   - TD.
   - INT.
   - Average.

3. Rushing stats
   - Player.
   - Attempts.
   - Yards.
   - Average.
   - TD.
   - Fumbles.
   - Broken tackles.
   - Yards after contact.
   - Long.

4. Receiving stats
   - Player.
   - Receptions.
   - Yards.
   - Average.
   - TD.
   - RAC.
   - Drops.
   - Long.

### OCR Pipeline

1. Detect screenshot type.
2. Crop known regions.
3. Run OCR.
4. Parse rows with table-specific logic.
5. Normalize names and stat fields.
6. Match screenshot data to save game.
7. Dedupe overlapping highlight screenshots.
8. Show review UI for corrections.
9. Store raw OCR and corrected values.

### Screenshot Generation Setting

The user should control whether screenshots block generation.

Supported modes:

1. Wait for screenshots
   - App imports save facts.
   - App does not generate rich user-team game content until screenshots are uploaded or the user skips them.
   - Best for played games where highlight detail matters.

2. Generate save-only immediately
   - App generates content from parsed save data without waiting.
   - Prompts must avoid claiming full play-by-play detail.
   - Best for simmed games or weeks where the user does not want screenshot work.

3. Ask each week
   - App prompts the user after import.
   - Useful while testing the workflow.

### Screenshot Storage

Raw screenshots should be stored permanently.

Reasons:
- OCR can be rerun as the parser improves.
- Users can audit generated stories against original evidence.
- Future features may support additional stat screens without needing the user to re-capture old games.

For MVP, the screenshot archive is append-only in the UI. Manual deletion controls can be added later if needed.

### Highlight Normalization

The highlight parser should classify:

- Passing touchdown.
- Rushing touchdown.
- Receiving touchdown.
- Interception.
- Pick-six.
- Sack.
- Forced fumble.
- Field goal.
- Missed field goal.
- Punt.
- Kickoff return.
- Punt return.
- Conversion.
- Generic notable play.

The app should be conservative. If classification confidence is low, keep the raw text and mark the play type as `unknown`.

## 10. AI Generation Requirements

### MVP Generated Content

1. Long-form game article
   - Factual score and context.
   - Key performers.
   - Turning points from highlights.
   - If screenshots are unavailable, focus on final stats, matchup context, and implications.
   - Tone should match serious sports journalism.

2. Game headline
   - Short, punchy, factual.

3. Social media feed
   - Beat reporter posts.
   - Fan posts.
   - National analyst posts.
   - Should react to real facts only.
   - Personality and tone can vary by account.

4. Short-form updates
   - Brief news cards.
   - Injury/availability notes if reliably parsed.
   - Rankings movement.
   - Key stat blurbs.

5. Weekly hub stories
   - Top user-team story.
   - National story if rankings/results support it.
   - Player spotlight.

6. Press conference content
   - Reporter questions.
   - Response choices.
   - Relationship impact explanations.
   - Press conference recap.
   - Public response summary.

### Content Modes

The app should support multiple content styles rather than one fixed voice:

- Serious long-form article.
- Short recap.
- Social post.
- Beat reporter update.
- National analyst take.
- Fan reaction.

Each content mode should have its own editable prompt template.

MVP prompt packs should include:
- Serious Newsroom.
- Balanced.
- Chaotic Social.

Prompt packs should also seed recurring personalities automatically. Users can disable personalities, but the MVP should not require manual personality creation.

### Later Generated Content

- Expanded coach/player quote formats outside the press conference module.
- Recruiting insider posts.
- Podcast scripts.
- Magazine covers/articles.
- Rivalry previews.
- Bowl/playoff selection shows.
- Coach carousel rumor mill.

### AI Guardrails

1. Separate deterministic facts from generated prose.
2. Use structured prompts with explicit source facts.
3. Require JSON outputs for artifacts that feed UI.
4. Store prompt version and model name.
5. Allow regeneration.
6. Allow user edits.
7. Allow prompt edits.
8. Avoid inventing unavailable facts.
9. Do not generate rumor/speculation content in MVP.
10. Use different prompts for screenshot-enriched generation and save-only generation.
11. Publish generated content immediately, with edit/regenerate controls available after publishing.
12. Store prompt edits per dynasty.
13. Store full rendered prompt text on generated artifacts for audit and replay.
14. Allow content-type-specific provider/model settings.

### Interactive Press Conferences

Press conferences should create interactive state, not just static generated text.

Supported MVP flow:

1. App generates a press conference after every user-team game.
2. Each question is asked by a recurring personality.
3. Normal games get 3 questions.
4. Major games get 5 questions.
5. Ranked matchups and rivalry games are major games.
6. Question types are selected from a pool based on game context, reporter personality, team status, and recent storylines.
7. Response option types are situational instead of fixed.
   - Examples: hostile, coach-speak, direct, deflect, take blame, praise players, challenge team, protect player, criticize execution, downplay concern.
8. Each generated response shows visible effect previews before selection.
   - Previews should show broad indicators and exact deltas.
   - Example: `Fans +2`, `Media -1`, `Locker Room neutral`.
9. The user can select one generated response or type a custom response.
10. Custom responses are graded immediately after each answer.
11. AI should explain why a custom response changed each relationship category.
12. Each generated or custom response applies relationship effects.
13. After all questions are answered, AI generates:
   - Press conference recap.
   - Public response.
   - Follow-up social posts.

Relationship categories:
- Locker room.
- Fans.
- Media.
- School/athletic department.
- Boosters.

Relationship scale:
- Scores are `0-100`.
- Every category starts at `50`.
- The UI should show numeric values with tier labels.
- Example tiers:
  - 0-19: Hostile.
  - 20-39: Cold.
  - 40-60: Neutral.
  - 61-80: Warm.
  - 81-100: Loyal.

Relationship effects should be small and cumulative. The goal is not to create a punitive management sim immediately; it is to give press conferences consequences and memory.

Coach relationship state should be included in almost every AI prompt. It should influence reporter tone, fan/social reactions, article framing, press conference questions, and future storyline selection.

Relationship effect weights are internal-only for MVP. Users should see relationship state and choice effects, but should not tune the scoring model until a later version.

### Player Grades

Player grades should be formula-driven first, then passed to AI for contextual explanation.

MVP approach:

1. Compute deterministic grades from parsed stats, position, opponent context when available, team result, and role.
2. Include prior game grades and recent trend context.
3. Pass formula score, stat line, prior context, and game context to AI.
4. AI explains the grade without overriding the deterministic score.
5. Store formula inputs and AI explanation for audit.

## 11. UX Direction

The portal should feel like a working sports information product, not a marketing site.

The MVP home screen should feel like a team-based fan site: a user-team-centered news feed with the scoreboard, national context, and upcoming matchup information supporting the feed rather than replacing it.

National, conference, rival, and upcoming-opponent news should live in a sidebar or section called `Across the Landscape`, not inline as the main feed.

Visual direction:
- Dense but readable.
- Scoreboard and news-first.
- Team colors used as accents, not full-page color washes.
- Clear navigation by week, team, game, player, recruit, and story.
- Cards only for repeated items like news posts, games, players, and recruits.

Primary navigation:
- Home
- Scores
- Teams
- Players
- Rankings
- Stories
- Settings

MVP navigation can start smaller:
- Home
- Scores
- Stories
- Import
- AI
- Settings

## 12. Non-Goals for MVP

- Writing or editing dynasty save files.
- Fully hosted cloud product.
- Multiplayer league management.
- Real-time game capture.
- Perfect OCR with no review step.
- Full play-by-play reconstruction without screenshots.
- Support for every screenshot type.
- Support for non-CFB27 games.
- RTG parsing.
- Recruiting.
- Coaching carousel.
- Rumor/speculation generation.
- Multiple active dynasty switching in the UI.
- Screenshot deletion UI.
- Storyline pinning/follow controls.

## 13. Risks and Unknowns

1. Save stat coverage
   - The save gives strong final stats, but likely not full play-by-play.
   - Screenshots are needed for realistic game stories.

2. Table drift
   - Table IDs may shift by game update or save lineage.
   - Parser must use unique IDs and references.

3. Player stat subclasses
   - Some player stats may live in subclass stat tables.
   - Parser must search all relevant game stat tables.

4. OCR accuracy
   - Screenshot rows can overlap across scroll positions.
   - Names and initials may be ambiguous.
   - Correction UI is required.

5. AI hallucination
   - Generated content must stay tied to source facts.
   - Source evidence and user editing are required.

6. Hosting privacy
   - Raw save files may contain more data than users expect.
   - Hosted version should avoid raw save upload unless explicitly enabled.

## 14. Confirmed Product Decisions

1. MVP coverage is mostly the user's team, with enough national context to make the world feel alive.
2. MVP should be an actual desktop app from day one.
3. Screenshots should be optional through a setting:
   - Wait for screenshots.
   - Generate save-only immediately.
   - Ask each week.
4. AI prompts should change depending on whether screenshots are available.
5. Recruiting is post-MVP.
6. Coaching carousel is post-MVP.
7. Generated content should support many formats:
   - Serious long-form articles.
   - Short-form news updates.
   - Social media feeds.
   - Posts from varied personalities.
8. AI should support local and OpenAI-compatible providers through base URL, API key, and model settings.
9. Generated content should be editable.
10. Prompt templates should be editable.
11. Import is manual, with a configured save folder and primary save file.
12. The weekly import path should be one-click `Import Latest` from the same configured save file.
13. MVP supports one active dynasty, while keeping the data model ready for multiple dynasties later.
14. Raw screenshots are stored permanently.
15. Generated content publishes immediately.
16. Prompt edits are per dynasty for MVP.
17. MVP ships with prompt packs.
18. Recurring fictional reporters, fan accounts, and analysts are part of MVP.
19. Rumor/speculation content is post-MVP.
20. MVP home screen should feel like a user-team fan site news feed.
21. MVP screenshot archive is append-only in the UI.
22. Personalities are automatically generated from prompt-pack archetypes.
23. National, conference, and rival news appears in an `Across the Landscape` sidebar/section.
24. Game Center should include recap, highlights, box score, social reaction, player grades, and press conference access.
25. Different content types can use different AI providers/models.
26. AI artifacts should store full rendered prompt text for audit/replay.
27. Press conferences should be interactive:
   - Reporters ask questions.
   - User selects hostile, coach-speak, direct, or custom response.
   - Responses affect coach relationships with locker room, fans, media, school/AD, and boosters.
   - AI recaps the press conference and public response.
28. Coach relationship scores use a visible `0-100` scale with tier labels.
29. All coach relationship categories start at `50`.
30. Press conference response effects are visible before selection.
31. Custom press conference responses are graded immediately after each answer.
32. Press conferences trigger after every user-team game.
33. Normal games get 3 questions; major games get 5.
34. Coach relationship state should be included in nearly every AI prompt.
35. Press conference response options are situational based on question type.
36. Player grades are formula-driven, then passed to AI for context/explanation.
37. `Across the Landscape` includes national, conference, and rival stories.
38. Prompt pack edits create custom copies so defaults remain untouched.
39. `Across the Landscape` includes upcoming opponent stories.
40. Major games are ranked matchups or rivalry games.
41. Press conference response previews show both broad indicators and exact deltas.
42. AI explains why custom press conference responses changed each relationship category.
43. Imported saves are organized internally by detected dynasty even though the MVP UI shows one active dynasty.
44. Dynasty mode is the only product focus; RTG parsing is out of scope.
45. Storyline pinning/following is post-MVP.
46. Relationship effect weights are internal-only for MVP.
47. Hosted/cloud product decisions are deferred until after the local MVP direction is proven.

## 15. Deferred Product Questions

There are no unresolved MVP product questions in this draft. The following are deliberately deferred.

### Post-MVP Product

1. Should users be able to pin storylines and tell the AI to keep following them?
2. Should relationship effect weights become user-configurable later?

### Hosted Future

3. If hosted later, should users upload raw saves, or should the local app parse and upload only normalized data?
4. Should public dynasty portals be shareable without login?
5. Should hosted users be able to bring their own AI keys/models?
6. Should this eventually support paid tiers, or stay personal/open-source?

## 16. Proposed First Build Milestones

### Milestone 1: Parser Proof

- Create a local parser project.
- Import one save.
- Extract dynasty calendar, teams, games, team stats, and player stats.
- Print or store normalized JSON.
- Validate against the LSU 66-0 Auburn sample.
- Confirm a configured save folder and primary save file can be reused for one-click import.

### Milestone 2: Local Database

- Add SQLite.
- Store snapshots, teams, players, games, team stats, and player stats.
- Store one active dynasty with `dynasty_id` throughout the schema.
- Organize imported saves internally by detected dynasty.
- Add basic import dedupe by file hash.
- Add previous-snapshot comparison.

### Milestone 3: Screenshot OCR

- Add screenshot upload.
- Store raw screenshots permanently.
- Detect supported screenshot types.
- Extract highlight rows and stat rows.
- Add correction UI.
- Match screenshots to parsed games.

### Milestone 4: First Portal

- Build weekly hub.
- Make the home screen a user-team fan-site news feed.
- Build scoreboard.
- Build game center.
- Show parsed facts and corrected highlights.
- Prioritize user-team coverage with national context.
- Add `Across the Landscape` sidebar/section.
- Include placeholders/sections for recap, highlights, box score, social reaction, player grades, and press conference.
- Add formula-driven player grade display with AI explanation placeholder.

### Milestone 5: First AI Layer

- Add OpenAI-compatible provider configuration.
- Add base URL, API key, and model settings.
- Add content-type-specific provider/model settings.
- Add editable prompt templates.
- Store prompt edits per dynasty.
- Add default prompt packs.
- Make prompt pack edits create custom copies.
- Add automatically generated recurring fictional personalities from prompt-pack archetypes.
- Generate long-form article, short recap, headline, and social posts.
- Support separate save-only and screenshot-enriched prompt paths.
- Include coach relationship state in relevant prompts.
- Store generated artifacts with source evidence and full rendered prompt text.
- Publish generated artifacts immediately.
- Add regenerate/edit controls after publishing.

### Milestone 6: Interactive Press Conferences

- Generate reporter questions from recurring personalities.
- Generate 3 questions for normal games and 5 for major games.
- Treat ranked matchups and rivalry games as major games.
- Generate situational response options from a response-type pool.
- Show relationship effect previews before selection with broad indicators and exact deltas.
- Support custom typed responses.
- Grade custom responses immediately with AI.
- Explain why custom responses changed each relationship category.
- Track relationship changes for locker room, fans, media, school/AD, and boosters.
- Use visible `0-100` relationship scores with tier labels, starting at `50`.
- Generate press conference recap and public response.

### Milestone 7: Expand World

- Add team/player pages.
- Add persistent storylines.
- Add storyline pinning/follow controls.
- Add recruiting.
- Add coaching carousel.

## 17. Current MVP Decision Set

These are the current working decisions:

1. Local-first.
2. Read-only save parsing.
3. Electron plus Node parser plus React/Vite portal.
4. SQLite local database.
5. Support manual save import first, folder watching later.
6. Build a real desktop app from day one.
7. Support save-only import and screenshot-enriched import.
8. Make screenshot waiting behavior configurable.
9. Generate user-team-first weekly coverage with national context.
10. Support local and cloud OpenAI-compatible AI providers through URL/key/model settings.
11. Make generated content editable.
12. Make prompt templates editable.
13. Require OCR review/correction when screenshots are used.
14. Keep recruiting out of MVP.
15. Keep coaching carousel out of MVP.
16. Configure one save folder and one primary save file for one-click weekly import.
17. Support one active dynasty in the MVP UI, with schema support for future multiple dynasties.
18. Store raw screenshots permanently.
19. Publish generated content immediately.
20. Scope prompt edits per dynasty.
21. Ship prompt packs.
22. Include recurring fictional reporters, fan accounts, and analysts.
23. Keep rumor/speculation content out of MVP.
24. Make the home screen a user-team fan-site news feed.
25. Keep screenshot archive append-only in the MVP UI.
26. Generate personalities automatically from prompt-pack archetypes.
27. Put national, conference, and rival context in an `Across the Landscape` sidebar/section.
28. Include recap, highlights, box score, social reaction, player grades, and press conference access in Game Center.
29. Allow different content types to use different providers/models.
30. Store full rendered prompt text for generated artifacts.
31. Add interactive press conferences with response choices, custom response grading, relationship effects, recap, and public response.
32. Use visible `0-100` coach relationship scores with tier labels.
33. Start every relationship category at `50`.
34. Show response effects before press conference answer selection.
35. Grade custom press conference responses immediately.
36. Trigger press conferences after every user-team game.
37. Use 3 press questions for normal games and 5 for major games.
38. Include coach relationship state in nearly every AI prompt.
39. Use situational press conference response options from a question/response type pool.
40. Make player grades formula-driven, with AI explanation using game and prior-grade context.
41. Include national, conference, rival, and upcoming opponent stories in `Across the Landscape`.
42. Make prompt pack edits create custom copies so defaults remain untouched.
43. Treat ranked matchups and rivalry games as major games.
44. Show broad indicators and exact deltas in press conference response previews.
45. Explain custom-response relationship changes.
46. Organize imported saves internally by detected dynasty.
47. Focus only on Dynasty mode; RTG parsing is out of scope.
48. Keep storyline pinning/following out of MVP.
49. Keep relationship effect weights internal-only for MVP.
50. Defer hosted/cloud product decisions until after the local MVP is proven.