ai-cto 0.1.0

package/docs/COPY.md

@@ -0,0 +1,121 @@
+# 💬 AI CTO — Master Copywriting Reference (COPY.md)
+
+> **One-Stop Reference:** This document contains every user-facing string, headline, feedback banner, rank title, and micro-copy used across **AI CTO**.
+
+---
+
+## 🎯 1. Elevator Pitches & Hero Headlines
+
+### Main Tagline
+> **Run an AI startup for 5 minutes.**
+
+### Subtitle & Hook
+> Every request is a business decision. Choose the cheapest model that satisfies the customer. Higher profit wins. No tutorials — learn by making mistakes.
+
+### Onboarding Tooltips
+- *"20 requests per daily session."*
+- *"Trade-off: Inference Cost vs Latency vs Output Accuracy."*
+- *"Higher profits rank higher on the daily leaderboard."*
+
+---
+
+## 🤖 2. Model Tier Names, Badges & Descriptions
+
+| Model Tier | Display Name | UI Badge Subtitle | Card Micro-Description |
+| :--- | :--- | :--- | :--- |
+| **Nano** | `Nano` | `Ultra Low Cost` | *"Ultra-fast, cheapest model. Great for quick text cleanup, simple parsing, and low-risk requests."* |
+| **Mini** | `Mini` | `Balanced Standard` | *"Mid-tier powerhouse. Balanced speed, coding capability, and high accuracy for standard business tasks."* |
+| **Large** | `Large` | `Heavyweight Reasoning` | *"Maximum reasoning & accuracy. Handles high-stakes code, complex vision OCR, and strict compliance tasks."* |
+
+---
+
+## ⚡ 3. Evaluation Feedback Copy
+
+When a player selects a model, the engine evaluates the choice and returns one of the following short headlines & explanatory sub-texts:
+
+### 🟢 Success Outcomes (Positive Profits)
+
+#### 1. Perfect Match (`reqCapabilities == model.capabilities`)
+- **Headline:** `Perfect fit.`
+- **Sub-text:** *"Model specs matched request requirements cleanly."*
+
+#### 2. Maximum Margin (`Nano` chosen for Medium/High task & succeeds)
+- **Headline:** `Excellent margin.`
+- **Sub-text:** *"Nano pulled through! High profit margin achieved."*
+
+#### 3. Over-Engineered (`Large` chosen for simple task)
+- **Headline:** `You burned money.`
+- **Sub-text:** *"Over-engineered! Large model cost cut deeply into profits."*
+
+#### 4. Lucky Pass (Capability Gap <= 1 point & RNG roll passed)
+- **Headline:** `You got lucky.`
+- **Sub-text:** *"Barely passed quality check despite capability gap."*
+
+#### 5. Slow SLA Pass (`model.latency > request.slaLatency` but customer accepts)
+- **Headline:** `Barely met SLA.`
+- **Sub-text:** *"Customer accepted output but complained about slow response time."*
+
+---
+
+### 🔴 Failure Outcomes (Losses / Refunds)
+
+#### 1. Capability Deficit (Model underpowered for task)
+- **Headline:** `Customer rejected output.`
+- **Sub-text:** *"Model hallucinated or failed required capability checks."*
+
+#### 2. Extreme Cost Failure (Deep capability gap)
+- **Headline:** `Inference costs are eating profits.`
+- **Sub-text:** *"Underpowered model failed completely on complex task."*
+
+#### 3. Latency SLA Exceeded
+- **Headline:** `Fast but sloppy.`
+- **Sub-text:** *"Latency SLA exceeded and customer cancelled request."*
+
+#### 4. High-Risk Compliance Failure
+- **Headline:** `Audit refund triggered!`
+- **Sub-text:** *"Severe calculation error in tax report triggered full penalty refund."*
+
+---
+
+## 🏆 4. End-of-Day Performance Tier Ranks
+
+Calculated after Request #20 based on net profit and customer satisfaction:
+
+| Tier | Rank Title | Subtitle Badge | Description / Trigger |
+| :--- | :--- | :--- | :--- |
+| **S Tier** | 👑 `S Tier AI CTO` | `Top 5% — Unicorn Founder` | Profit `> $250.00` & Trust `>= 90%` |
+| **A Tier** | 🚀 `A Tier AI CTO` | `Top 15% — Profitable AI Startup` | Profit `> $150.00` |
+| **B Tier** | 📊 `B Tier AI CTO` | `Top 35% — Sustainable Ops` | Profit `> $50.00` |
+| **C Tier** | 💼 `C Tier AI CTO` | `Break-even — Living on Grants` | Profit `>= $0.00` |
+| **F Tier** | 💀 `Bankrupt Founder` | `Inference Costs Ate Your Capital` | Profit `< $0.00` |
+
+---
+
+## 🏷️ 5. Category Badges & Task Labels
+
+### Category Badges
+- ✍️ `Text Processing`
+- 💻 `Coding`
+- 👁️ `Vision OCR`
+- 📜 `Long Context`
+- ⚠️ `High-Risk Audit`
+
+### Financial HUD Labels
+- 💵 `Capital` *(Available bank balance in USD)*
+- ❤️ `Trust` *(Customer satisfaction percentage)*
+- ⏳ `Turn Progress` *(e.g. `14 / 20`)*
+- 💰 `Success Reward` *(e.g. `+$18.00`)*
+- 📉 `Failure Risk` *(e.g. `-$35.00`)*
+- ⚡ `Max Latency` *(e.g. `2.0s`)*
+
+---
+
+## 🔘 6. Button & Navigation Micro-Copy
+
+- `Dispatch Nano`
+- `Dispatch Mini`
+- `Dispatch Large`
+- `Next Incoming Request`
+- `View Day Summary & Final Score`
+- `Replay 5-Minute Session`
+- `Restart Session`

package/docs/PRD.md

@@ -0,0 +1,195 @@
+# 🤖 AI CTO — Product Requirement Document (PRD)
+
+> **Elevator Pitch:** Run an AI startup for five minutes. Every request is a business decision. Choose the cheapest model that satisfies the customer. Higher profit wins. No tutorials — learn by making mistakes.
+
+---
+
+## 🎯 Core Hypothesis
+
+> Developers enjoy making AI architecture decisions and return daily to optimize their score.
+
+---
+
+## ⏱️ Session Overview
+
+| Metric | Target |
+| :--- | :--- |
+| **Session Length** | 3 – 5 minutes |
+| **Requests per Session** | Exactly 20 requests |
+| **Game Over Condition** | Session ends after request #20 is evaluated |
+
+---
+
+## 📊 Success Metrics
+
+### Primary Metric
+- **D1 Retention:** `> 30%`
+
+### Secondary Metrics
+- **Average Session Duration:** `> 4 minutes`
+- **Session Finish Rate:** `> 80%`
+- **Replay Rate:** `> 40%`
+
+> [!NOTE]
+> **V1 Non-Goals:** Ignore revenue monetization, global user accounts, and complex multiplayer leaderboards for V1.
+
+---
+
+## 🔄 Core Loop
+
+```mermaid
+graph TD
+    A[📥 Request Appears] --> B[🧐 Player Inspects Requirements]
+    B --> C[🤖 Player Chooses Model]
+    C --> D[⚡ Engine Simulates Outcome]
+    D --> E[💰 Money & Trust Updated]
+    E --> F{Request # < 20?}
+    F -- Yes --> A
+    F -- No --> G[🏁 Daily Score & Summary]
+```
+
+---
+
+## 🖼️ UI Wireframe Blueprint
+
+```
++-----------------------------------------------------------------------+
+|  💰 Money: $124        ❤️ Satisfaction: 92%        🏆 Day Score: 8,220  |
++-----------------------------------------------------------------------+
+|                                                                       |
+|  📥 INCOMING REQUEST (#14/20)                                         |
+|  "Generate SQL query for analytics dashboard"                         |
+|                                                                       |
+|  💰 Reward: +$18   |  ⚡ Max Latency: 2.0s   |  🎯 Quality Req: Medium  |
+|                                                                       |
++-----------------------------------------------------------------------+
+|  CHOOSE INFERENCE MODEL                                               |
+|                                                                       |
+|  [ ] Nano     💸 Cost: $0.03   ⚡ Latency: 0.4s   Rating: ★★★★☆  |
+|  [ ] Mini     💸 Cost: $0.14   ⚡ Latency: 1.2s   Rating: ★★★★★  |
+|  [ ] Large    💸 Cost: $0.82   ⚡ Latency: 3.8s   Rating: ★★★★★  |
+|                                                                       |
+|  [ DISPATCH REQUEST ]                                                 |
++-----------------------------------------------------------------------+
+```
+
+---
+
+## 🤖 V1 Models
+
+To avoid model bias, V1 uses generic model tiers rather than real brand names:
+
+| Model Tier | Cost / Req | Latency | Baseline Rating | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| **Nano** | `$0.03` | `0.4s` | ★★★★☆ | Ultra-fast, low cost. Great for basic text. |
+| **Mini** | `$0.14` | `1.2s` | ★★★★★ | Balanced tier. Handles medium tasks & code. |
+| **Large** | `$0.82` | `3.8s` | ★★★★★ | Heavyweight. Expensive & slow, high accuracy. |
+
+---
+
+## 🔍 Hidden Model Stats & Discovery
+
+Models possess hidden capability vectors that are initially undisclosed to players:
+
+- 💰 **Cost**
+- ⚡ **Latency**
+- 🎯 **Quality**
+- 🧠 **Reasoning**
+- 💻 **Coding**
+- 👁️ **Vision**
+- 📜 **Context Length**
+
+> [!TIP]
+> Players uncover hidden stats through trial and error. Later progression unlocks an **Encyclopedia** detailing exact model strengths.
+
+---
+
+## 📋 Request Attributes & Scenarios
+
+Each request presents specific requirements:
+- **Category:** `Text Processing`, `Coding`, `Vision`, `Long Context`, etc.
+- **Difficulty:** `Low`, `Medium`, `High`
+- **Max Latency SLA:** Maximum allowed time (e.g., `2.0s`)
+- **Expected Quality:** Minimum required standard
+- **Reward / Penalty:** Financial return vs refund risk
+
+### Example Scenarios
+
+#### Scenario A: Simple Task
+- **Task:** "Rewrite customer service email"
+- **Reward:** `+$4.00` | **Quality:** Low | **Latency SLA:** Fast
+- **Winning Choice:** **Nano** *(Maximizes profit margin)*
+
+#### Scenario B: High-Risk Task
+- **Task:** "Generate annual tax filing report"
+- **Reward:** `+$80.00` | **Penalty:** `-$300.00` | **Quality:** High
+- **Winning Choice:** **Large** *(Nano risks failure penalty)*
+
+---
+
+## 💬 Immediate Feedback Mechanics
+
+Feedback is delivered instantaneously upon choice evaluation:
+
+| Outcome | Feedback Example | Effect |
+| :--- | :--- | :--- |
+| **Success** | *"Great choice! Query resolved cleanly."* | Profit `+$7.00` |
+| **Failure** | *"Customer rejected output. Hallucinated SQL syntax."* | Refund `-$18.00`, Trust `-5%` |
+
+> [!IMPORTANT]
+> Keep feedback concise and intriguing. Curiosity drives learning better than lectures.
+
+---
+
+## 🏁 End Screen Summary
+
+At the conclusion of 20 requests, players receive a performance breakdown:
+
+```
++------------------------------------+
+|         DAY COMPLETE SUMMARY       |
++------------------------------------+
+|  💵 Gross Revenue:       $214.00   |
+|  📉 Inference Cost:     -$63.00    |
+|  😊 Customer Satisf.:      96%     |
+|  --------------------------------  |
+|  💰 NET PROFIT:          $151.00   |
+|  🏆 SCORE RANK:          Top 28%   |
++------------------------------------+
+```
+
+---
+
+## 🎲 Daily Seed & Progression
+
+- **Daily Seed:** Every player receives the exact same sequence of 20 requests daily, creating a fair & competitive leaderboard experience.
+- **Difficulty Progression:**
+  - **Day 1:** Simple text formatting & editing
+  - **Day 2:** Vision & multimodal requests
+  - **Day 3:** Complex coding & debugging
+  - **Day 4:** Long context summarization
+  - **Day 5:** Mixed heavy-workload scenarios
+
+---
+
+## 🚫 Out of Scope for V1
+
+> [!WARNING]
+> To ensure a weekend MVP launch, the following features are explicitly deferred:
+
+- ❌ No RAG / Vector DBs
+- ❌ No Agentic workflows
+- ❌ No Caching / Prompt editing
+- ❌ No Hardware / Model upgrades
+- ❌ No Multiplayer or User Accounts
+
+**Primary V1 Question to Answer:** *Is choosing models fun?*
+
+---
+
+## 🛠️ Minimal Tech Stack
+
+- **Frontend:** React + Vite + Tailwind CSS
+- **Data Source:** Single static `JSON` file describing daily requests
+- **Backend:** None (100% client-side execution)
+- **Persistence:** LocalStorage

package/docs/SCHEMA.md

@@ -0,0 +1,293 @@
+# 📐 AI CTO — Data Schema & Architecture Specification
+
+> **Overview:** This document defines all data models, TypeScript contracts, JSON schemas, and game engine data structures used in **AI CTO**. It includes an architectural review detailing the **Pros & Cons** of each schema design choice to guide future iteration.
+
+---
+
+## 📋 Table of Contents
+1. [Core Capabilities Vector Schema](#1-core-capabilities-vector-schema)
+2. [Model Schema (`models.json`)](#2-model-schema-modelsjson)
+3. [Request Schema (`requests.json`)](#3-request-schema-requestsjson)
+4. [Evaluation Result Schema](#4-evaluation-result-schema)
+5. [Turn History & Session State Schema](#5-turn-history--session-state-schema)
+6. [Persistence Schema (LocalStorage)](#6-persistence-schema-localstorage)
+7. [Comprehensive Pros & Cons Architectural Review](#7-comprehensive-pros--cons-architectural-review)
+
+---
+
+## 1. Core Capabilities Vector Schema
+
+The foundational model representing both AI model capabilities and incoming request requirements across 5 capability dimensions.
+
+```typescript
+export interface CapabilityVector {
+  /** Baseline quality requirement or output grade (Range: 1 to 5) */
+  quality: number;
+
+  /** Code generation & syntax correctness requirement (Range: 0 to 5) */
+  coding: number;
+
+  /** Logical deduction, step-by-step math & planning requirement (Range: 0 to 5) */
+  reasoning: number;
+
+  /** Image OCR, diagram understanding & visual parsing (Range: 0 to 5) */
+  vision: number;
+
+  /** Token window size requirement (Range: 1 to 5; 1 = short, 5 = 100k+ tokens) */
+  context: number;
+}
+```
+
+---
+
+## 2. Model Schema (`models.json`)
+
+Defines available inference models, their cost metrics, SLAs, and capability vectors.
+
+```typescript
+export interface Model {
+  /** Unique model identifier ('nano' | 'mini' | 'large') */
+  id: 'nano' | 'mini' | 'large';
+
+  /** Display name shown in UI cards (e.g., "Nano") */
+  name: string;
+
+  /** UI badge subtitle (e.g., "Ultra Low Cost", "Heavyweight Reasoning") */
+  badge: string;
+
+  /** Inference cost per single request in USD ($) */
+  cost: number;
+
+  /** Expected latency delay in seconds (s) */
+  latency: number;
+
+  /** Short descriptive string highlighting strengths/weaknesses */
+  description: string;
+
+  /** Multidimensional vector defining model performance levels */
+  capabilities: CapabilityVector;
+}
+```
+
+### Example Instance (`models.json`)
+
+```json
+{
+  "id": "nano",
+  "name": "Nano",
+  "badge": "Ultra Low Cost",
+  "cost": 0.03,
+  "latency": 0.4,
+  "description": "Ultra-fast, cheapest model. Great for quick text cleanup, simple parsing, and low-risk requests.",
+  "capabilities": {
+    "quality": 2,
+    "coding": 1,
+    "reasoning": 1,
+    "vision": 0,
+    "context": 1
+  }
+}
+```
+
+---
+
+## 3. Request Schema (`requests.json`)
+
+Defines incoming customer tasks, SLA limits, financial rewards/penalties, and required capability vectors.
+
+```typescript
+export interface RequestItem {
+  /** Unique request numeric ID (1 to 20) */
+  id: number;
+
+  /** Task headline shown to player */
+  title: string;
+
+  /** Detailed task context explaining customer constraints */
+  description: string;
+
+  /** Task classification category */
+  category: 'text' | 'coding' | 'vision' | 'context' | 'high_risk';
+
+  /** Relative difficulty tier */
+  difficulty: 'low' | 'medium' | 'high';
+
+  /** Financial payout in USD ($) awarded on successful completion */
+  reward: number;
+
+  /** Financial penalty / refund in USD ($) deducted on failure */
+  penalty: number;
+
+  /** Maximum acceptable customer SLA latency in seconds (s) */
+  slaLatency: number;
+
+  /** Minimum required capability vector for 100% success match */
+  reqCapabilities: CapabilityVector;
+}
+```
+
+### Example Instance (`requests.json`)
+
+```json
+{
+  "id": 13,
+  "title": "Generate annual tax filing report",
+  "description": "High-risk financial compliance output. Any calculation mistake triggers audit refund.",
+  "category": "high_risk",
+  "difficulty": "high",
+  "reward": 80.00,
+  "penalty": -250.00,
+  "slaLatency": 5.0,
+  "reqCapabilities": {
+    "quality": 5,
+    "coding": 3,
+    "reasoning": 5,
+    "vision": 0,
+    "context": 3
+  }
+}
+```
+
+---
+
+## 4. Evaluation Result Schema
+
+Returned by the pure TypeScript engine when a player dispatches a model choice for a request.
+
+```typescript
+export interface EvaluationResult {
+  /** Boolean indicating whether customer accepted the generated output */
+  success: boolean;
+
+  /** Net financial delta in USD: (reward - cost) or (penalty - cost) */
+  profit: number;
+
+  /** Customer satisfaction / trust percentage change (-100% to +100%) */
+  trustDelta: number;
+
+  /** Descriptive explanation of execution outcome */
+  message: string;
+
+  /** Snappy status copy (e.g., "Perfect fit", "Over-engineered", "Customer rejected output") */
+  copyFeedback: string;
+
+  /** Breakdown of individual requirement checks */
+  details: {
+    latencyMet: boolean;
+    qualityMet: boolean;
+    reasoningMet: boolean;
+    codingMet: boolean;
+    visionMet: boolean;
+    contextMet: boolean;
+  };
+}
+```
+
+---
+
+## 5. Turn History & Session State Schema
+
+Tracks user choices across the 20-request game loop.
+
+```typescript
+export interface TurnHistoryItem {
+  request: RequestItem;
+  model: Model;
+  result: EvaluationResult;
+}
+
+export interface GameState {
+  /** Current available capital in USD ($) */
+  money: number;
+
+  /** Current customer satisfaction score (0% to 100%) */
+  trust: number;
+
+  /** Zero-indexed current turn number (0 to 19) */
+  currentTurn: number;
+
+  /** Array of completed turns in chronological order */
+  history: TurnHistoryItem[];
+
+  /** Active modal evaluation result (null if waiting for choice) */
+  activeResult: EvaluationResult | null;
+
+  /** Flag set to true when turn 20 is completed */
+  isGameOver: boolean;
+}
+```
+
+---
+
+## 6. Persistence Schema (LocalStorage)
+
+Format used for persisting user high scores and session statistics across visits.
+
+```typescript
+export interface SavedState {
+  version: string;
+  bestScore: number;
+  highestProfit: number;
+  sessionsCompleted: number;
+  unlockedEncyclopediaIds: string[];
+  lastPlayedDate: string; // ISO String (e.g. "2026-08-01")
+}
+```
+
+---
+
+## 7. Comprehensive Pros & Cons Architectural Review
+
+Here is an architectural review of the schema design decisions:
+
+### A. Multidimensional Capability Vectors (`CapabilityVector`)
+
+- **Pros:**
+  - 🟢 **Generic & Scalable:** Engine logic relies on generic vector comparisons (`reqCapabilities` vs `capabilities`) rather than hardcoded `if/else` checks per request type.
+  - 🟢 **Extensible:** Adding new dimensions (e.g. `multilingual`, `audio`, `functionCalling`) requires only extending the vector interface without refactoring evaluation logic.
+  - 🟢 **Rich Trade-offs:** Allows creating nuanced requests (e.g., high coding but low vision vs high reasoning but short context).
+- **Cons:**
+  - 🔴 **Initial Complexity:** Players must learn what each vector dimension means (Quality, Coding, Reasoning, Vision, Context) rather than a single simple star rating.
+  - 🔴 **Hidden Stats Obscurity:** If hidden stats aren't exposed cleanly in the UI, failure reasons can feel opaque to novice players.
+
+---
+
+### B. Fixed JSON Scenarios (`requests.json`) vs Procedural Generation
+
+- **Pros:**
+  - 🟢 **Deterministic Daily Challenge:** Ensures every player gets the exact same 20 requests on a given day for fair competitive leaderboards.
+  - 🟢 **Handcrafted Pacing:** Allows designing specific difficulty curves (e.g., low-risk text on Turn 1, extreme high-risk tax audit on Turn 13, enterprise migration on Turn 20).
+  - 🟢 **Zero Runtime Overhead:** Instant load time with no RNG calculation lag or invalid request edge-cases.
+- **Cons:**
+  - 🔴 **Finite Replayability:** Once a player memorizes the optimal model choice for the 20 fixed requests, replay value drops until new JSON packs are released.
+  - 🔴 **Manual Maintenance:** Modifying request balance requires manually editing JSON files.
+
+---
+
+### C. Flat Asymmetric Reward vs Penalty Schema (`reward` / `penalty`)
+
+- **Pros:**
+  - 🟢 **High-Stakes Tension:** Large penalties (e.g. `Reward: +$80` vs `Penalty: -$250`) force players to think carefully about risk tolerance rather than blindly selecting the cheapest Nano model.
+  - 🟢 **Realistic Business Simulation:** Mirrors real AI startup dynamics where severe outages or hallucinated compliance advice destroy customer trust and revenue.
+- **Cons:**
+  - 🔴 **Punishing First Playthrough:** Players who pick Nano on Turn 13 without understanding hidden capability requirements suffer massive negative balance drops.
+
+---
+
+### D. Client-Side LocalStorage vs Server-Side DB
+
+- **Pros:**
+  - 🟢 **Zero Backend Overhead:** Zero server hosting costs, zero database management, zero latency, zero login flow required.
+  - 🟢 **Instant Playability:** Game starts instantly in any web browser without auth barriers.
+- **Cons:**
+  - 🔴 **Tamper Risk:** Savvy users can manually edit `localStorage` values to spoof high scores. (Sufficient for V1 MVP validation, but would require a backend for cash prize leaderboards).
+
+---
+
+## 🔍 Review & Feedback Checklist for You
+
+Please review the data schemas and pros/cons above:
+
+1. **Vector Dimension Granularity:** Do you like having 5 distinct capability dimensions (`quality`, `coding`, `reasoning`, `vision`, `context`), or would you prefer simplifying to just 3 (`quality`, `speed`, `complexity`)?
+2. **Financial Balance:** Are the high-risk penalties (e.g. `+$80` reward vs `-$250` penalty) creating the right level of tension, or should failure penalties be capped at 2x the reward?
+3. **JSON vs Procedural Requests:** Should we keep handcrafted JSON request sets, or introduce procedural request generators for infinite replayability?