add: viraltest code (server, models, inference)

.dockerignore

@@ -0,0 +1,15 @@
+.venv
+.git
+.gitignore
+.env
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.pyw
+*.pyz
+*.pywz
+*.pyzw
+*.pyzwz
+
+

.env.example

@@ -0,0 +1,6 @@
+# Copy to .env and set values ( .env is gitignored )
+HF_TOKEN=hf_your_token_here
+
+# Optional overrides for Step 5 / inference (defaults match inference.py):
+# MODEL_NAME=gemma-4-E4B-it-IQ4_XS
+# API_BASE_URL=https://router.huggingface.co/v1

DESIGN.md

@@ -0,0 +1,792 @@
+# Viraltest — RL-Based Creator Optimization Agent
+
+## Problem
+
+Content creators on platforms like Meta (Instagram, Facebook) face:
+
+- Unpredictable engagement
+- No clear posting strategy
+- Pressure to post frequently
+- Burnout due to over-posting
+- Drop in content quality over time
+
+Existing tools show analytics (likes, reach) and past performance but don't **actively guide creators on optimal behavior over time**.
+
+**Core problem**: No intelligent system continuously learns and adapts a creator's posting strategy to balance growth and burnout.
+
+## Solution
+
+An RL agent that learns **when to post**, **what type to post**, **which tags to use**, and **how to differentiate from competitors** — maximizing engagement while minimizing burnout over a weekly cycle.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  INFERENCE SCRIPT (inference.py)                                    │
+│                                                                     │
+│  env = ViraltestEnv(base_url="https://...")                        │
+│  result = env.reset(task="weekly_strategic")  ← picks task         │
+│  result = env.step(action)                    ← type-safe!         │
+│                                                                     │
+│  ┌───────────────────────────────────────────────────────────┐     │
+│  │  LLM Agent (OpenAI Client)                                │     │
+│  │  Reads: observation → Decides: action                     │     │
+│  │  Model: Qwen/Qwen2.5-72B-Instruct                        │     │
+│  └───────────────────────────────────────────────────────────┘     │
+│                                                                     │
+│  Logs: [START] [STEP] [END] to stdout                              │
+└──────────────────────────┬──────────────────────────────────────────┘
+                           │
+                    WebSocket /ws
+                           │
+                           ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│  DOCKER CONTAINER (HF Space)                                        │
+│                                                                     │
+│  ┌───────────────────────────────────────────────────────────┐     │
+│  │  FastAPI Server (server/app.py)  — port 8000              │     │
+│  │                                                           │     │
+│  │  ┌─────────────────────────────────────────────────────┐ │     │
+│  │  │  ViraltestEnvironment                               │ │     │
+│  │  │                                                     │ │     │
+│  │  │  ┌─────────────────┐   ┌──────────────────────┐   │ │     │
+│  │  │  │  reset(task)    │   │  step(action)         │   │ │     │
+│  │  │  │  • Set task     │   │  1. Validate action   │   │ │     │
+│  │  │  │  • Init state   │   │  2. Apply effects     │   │ │     │
+│  │  │  │  • energy=1.0   │   │  3. Calc engagement   │   │ │     │
+│  │  │  │  • followers=N  │   │  4. Tag analytics     │   │ │     │
+│  │  │  │  • Init tags    │   │  5. Competitor check   │   │ │     │
+│  │  │  │  • Init rivals  │   │  6. Update followers  │   │ │     │
+│  │  │  │  • Return obs   │   │  7. Calc reward       │   │ │     │
+│  │  │  └─────────────────┘   │  8. Check done        │   │ │     │
+│  │  │                        │  9. Return obs        │   │ │     │
+│  │  │  ┌─────────────────┐   └──────────────────────┘   │ │     │
+│  │  │  │  state()        │                               │ │     │
+│  │  │  │  • episode_id   │   ┌──────────────────────┐   │ │     │
+│  │  │  │  • step_count   │   │  Grader (per task)    │   │ │     │
+│  │  │  │  • task_name    │   │  • weekly_engage      │   │ │     │
+│  │  │  └─────────────────┘   │  • weekly_strategic   │   │ │     │
+│  │  │                        │  • weekly_competitive  │   │ │     │
+│  │  │                        └──────────────────────┘   │ │     │
+│  │  │                                                     │ │     │
+│  │  │  Simulation Engine (research-backed params)         │ │     │
+│  │  │  • Hour multipliers (Buffer 9.6M study)             │ │     │
+│  │  │  • Content rates (SocialInsider 2025)               │ │     │
+│  │  │  • Burnout curve (Sozee 2026 creator study)         │ │     │
+│  │  │  • Tag engagement model                             │ │     │
+│  │  │  • Competitor simulation                            │ │     │
+│  │  └─────────────────────────────────────────────────────┘ │     │
+│  └───────────────────────────────────────────────────────────┘     │
+│                                                                     │
+│  Isolated • Reproducible • Secure • Deterministic (seeded RNG)     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Pydantic Models
+
+```
+models.py
+├── ViraltestAction(Action)
+│   ├── action_type: Literal["post", "rest", "create_content"]
+│   ├── content_type: Optional[Literal["reel", "story", "carousel", "text_post"]]
+│   ├── topic: Optional[str]
+│   └── tags: Optional[list[str]]         ← max 5 tags per post
+│
+└── ViraltestObservation(Observation)
+    ├── current_hour: int                  (0–23)
+    ├── day_of_week: int                   (0–6)
+    ├── days_elapsed: int
+    ├── creator_energy: float              (0.0–1.0, burnout meter)
+    ├── follower_count: int
+    ├── engagement_rate: float             (rolling avg last 10 posts)
+    ├── posts_today: int
+    ├── time_since_last_post: int          (hours)
+    ├── trending_topics: list[str]
+    ├── content_queue_size: int
+    ├── last_post_type: str
+    │
+    │   ── Tag Analytics ──
+    ├── tag_performance: dict[str, float]  (tag → avg engagement from your past posts)
+    ├── trending_tags: list[str]           (currently hot tags on the platform)
+    │
+    │   ── Competitor Intelligence ──
+    ├── competitor_recent_posts: list[dict] (last 3 posts from similar creators)
+    │   each: {content_type, topic, tags, engagement, hours_ago}
+    ├── competitor_avg_engagement: float    (avg engagement of similar creators)
+    ├── niche_saturation: float            (0.0–1.0, how crowded your topic space is)
+    │
+    ├── done: bool                         (inherited)
+    └── reward: float                      (inherited)
+```
+
+---
+
+## Data Flow — Single Step
+
+```
+AGENT                                   ENVIRONMENT
+  │                                          │
+  │  ── Action ───────────────────────────►  │
+  │  {                                       │
+  │    action_type: "post"                   │
+  │    content_type: "reel"                  │  1. Validate fields
+  │    topic: "AI trends"                    │  2. energy -= 0.25
+  │    tags: ["ai", "tech", "future"]        │  3. engagement = base_rate
+  │  }                                       │       × hour_mult
+  │                                          │       × energy_quality
+  │                                          │       × tag_boost
+  │                                          │       × trending_bonus
+  │                                          │       × competitor_diff_bonus
+  │                                          │       × audience_fatigue
+  │                                          │  4. Update tag_performance history
+  │                                          │  5. Update niche_saturation
+  │                                          │  6. followers += f(engagement)
+  │                                          │  7. advance hour
+  │                                          │  8. reward = composite score
+  │                                          │  9. done? (168 steps or energy=0)
+  │  ◄── Observation ─────────────────────  │
+  │  {                                       │
+  │    current_hour: 14                      │
+  │    creator_energy: 0.62                  │
+  │    follower_count: 10340                 │
+  │    engagement_rate: 0.048                │
+  │    tag_performance: {                    │
+  │      "ai": 0.72, "tech": 0.55,          │
+  │      "food": 0.31, "travel": 0.44       │
+  │    }                                     │
+  │    trending_tags: ["ai", "summer"]       │
+  │    competitor_recent_posts: [            │
+  │      {type:"carousel", topic:"AI",       │
+  │       tags:["ai","ml"], eng:0.61,        │
+  │       hours_ago: 3},                     │
+  │      ...                                 │
+  │    ]                                     │
+  │    niche_saturation: 0.7                 │
+  │    done: false, reward: 0.67             │
+  │  }                                       │
+```
+
+---
+
+## Step Processing (Server-Side)
+
+### 1. Validate Action
+
+- `action_type` must be one of `post`, `rest`, `create_content`
+- If `post`: `content_type` required, `topic` non-empty ≤200 chars, `tags` max 5 items from known pool
+- Invalid action → reward=0, error in observation
+
+### 2. Apply Energy Cost
+
+| Action | Energy Effect |
+|---|---|
+| Post (reel) | -0.25 |
+| Post (carousel) | -0.20 |
+| Post (story) | -0.08 |
+| Post (text_post) | -0.06 |
+| Rest | +0.12 (capped at 1.0) |
+| Create content | -0.05, queue += 1 |
+
+Repetition penalty: same content type as last 3 posts → extra -0.05.
+If energy ≤ 0 → `done = true` (burnout).
+
+### 3. Calculate Engagement (post only)
+
+```
+engagement = base_rate × hour_mult × quality × tag_boost × trending_bonus
+             × competitor_diff × fatigue_penalty
+```
+
+**Base engagement rates** (SocialInsider 2025):
+
+| Type | Rate | Reach Mult |
+|---|---|---|
+| Carousel | 0.55% | 1.0x |
+| Reel | 0.52% | 2.25x |
+| Story | 0.30% | 0.5x |
+| Text post | 0.37% | 0.44x |
+
+**Hour multipliers** (Buffer 9.6M posts):
+
+| Time Slot | Multiplier |
+|---|---|
+| 9AM–12PM weekdays | 1.3x |
+| 12PM–3PM Tue-Thu | 1.4x (peak) |
+| 6PM–8PM | 1.25x |
+| 8PM–11PM | 1.1x |
+| 11PM–6AM | 0.5x |
+| Fri/Sat | 0.7x base penalty |
+
+**Quality modifier** (Sozee burnout study: 30-52% productivity drop):
+
+```
+quality = 1.0 if energy > 0.5 else max(0.48, energy × 1.5)
+```
+
+**Tag boost** (see Tag Engagement section below):
+
+```
+tag_boost = 1.0 + 0.1 × count(tags that are in trending_tags)
+            + 0.05 × avg(tag_performance[tag] for tag in action.tags)
+```
+
+**Competitor differentiation bonus**:
+
+```
+if topic NOT in competitor_recent_topics (last 12hrs):
+    competitor_diff = 1.3   (unique angle, underserved)
+elif niche_saturation > 0.7:
+    competitor_diff = 0.6   (oversaturated, too many posting same thing)
+else:
+    competitor_diff = 1.0   (neutral)
+```
+
+**Audience fatigue**: posts_today > 3 → ×0.5, posts_today > 5 → ×0.1
+
+**Trending bonus**: topic matches trending → ×1.5
+
+### 4. Update Tag Performance
+
+After each post, the environment records engagement per tag:
+
+```python
+for tag in action.tags:
+    tag_history[tag].append(this_post_engagement)
+    tag_performance[tag] = rolling_avg(tag_history[tag], window=5)
+```
+
+This gives the agent a feedback loop — it can see which tags historically work and adapt.
+
+### 5. Update Competitor State
+
+Each step, the simulated competitors also "post" according to a deterministic schedule (seeded RNG):
+
+```python
+for competitor in competitors:
+    if should_post(competitor, current_hour):  # seeded probability
+        competitor.recent_posts.append({
+            content_type: random.choice(types),
+            topic: random.choice(competitor.niche_topics),
+            tags: random.sample(tag_pool, 3),
+            engagement: base + noise,
+            hours_ago: 0
+        })
+    # Age out old posts
+    competitor.recent_posts = [p for p in competitor.recent_posts if p.hours_ago < 48]
+
+niche_saturation = count(competitor posts with overlapping topic in last 12hrs) / max_posts
+```
+
+### 6. Update Followers
+
+- Posted: `followers += int(engagement × 100)`
+- No post for 48+ hrs: followers decay (algorithm deprioritization)
+
+### 7. Advance Time
+
+- hour += 1
+- If hour ≥ 24: day advances, posts_today resets, trending topics/tags rotate (seeded)
+
+### 8. Compute Reward
+
+```
+reward = clamp(0, 1,
+    engagement_gained × 0.3
+    + energy_delta × 0.15
+    + consistency_bonus × 0.15
+    + tag_optimization_score × 0.15
+    + competitor_diff_score × 0.15
+    - burnout_penalty × 0.1
+)
+```
+
+- `consistency_bonus`: 1.0 if 1-2 posts/day, 0.5 if 0 or 3, 0.0 if 4+
+- `tag_optimization_score`: how well agent's chosen tags match high-performing + trending tags
+- `competitor_diff_score`: 1.0 if posting unique angle, 0.0 if fully overlapping
+- `burnout_penalty`: 1.0 if energy < 0.2
+
+### 9. Check Done
+
+Episode ends when:
+- `step_count >= 168` (1 week = 7 days × 24 hours)
+- `energy <= 0` (burned out)
+
+---
+
+## Tag Engagement System
+
+### How Tags Work
+
+The environment maintains a **tag pool** of ~30 tags across categories:
+
+| Category | Example Tags |
+|---|---|
+| Tech | `ai`, `ml`, `coding`, `startup`, `saas` |
+| Lifestyle | `fitness`, `travel`, `food`, `wellness`, `fashion` |
+| Trending | `summer`, `worldcup`, `election` (rotate daily) |
+| Niche | `productivity`, `minimalism`, `stoic`, `web3` |
+| Broad | `motivation`, `tips`, `howto`, `viral` |
+
+### Tag Performance Tracking
+
+Each tag accumulates engagement history from the agent's own posts:
+
+```
+tag_performance = {
+    "ai": 0.72,          ← avg engagement when you used this tag
+    "fitness": 0.31,     ← this tag isn't working for your audience
+    "motivation": 0.55,
+    ...
+}
+```
+
+Initially all tags start at 0.0 (unknown). As the agent posts with different tags, it builds this signal.
+
+### Tag Dynamics
+
+- **Trending tags** change every 24 simulated hours (seeded, deterministic)
+- Using a trending tag gives +10% engagement per trending tag matched
+- Using a high-performing tag (from your history) gives +5% per tag
+- Using an **oversaturated tag** (competitors using it heavily) gives -10%
+- Max 5 tags per post — agent must choose wisely
+
+### What the Agent Must Learn
+
+1. **Discover** which tags work for its audience (explore early, exploit later)
+2. **Ride trends** — use trending tags when they align with its niche
+3. **Avoid saturation** — if competitors are all using `#ai`, pivot to `#ml` or `#coding`
+4. **Combine** high-performing niche tags with 1-2 trending tags for optimal reach+engagement
+
+---
+
+## Competitor Intelligence System
+
+### Simulated Competitors
+
+The environment simulates **3 competing creators** in the same niche. Each has:
+
+```python
+competitor = {
+    "name": "creator_A",
+    "niche_topics": ["AI", "tech", "startups"],      # their focus
+    "preferred_types": ["reel", "carousel"],           # what they mostly post
+    "posting_frequency": 2.5,                          # avg posts/day
+    "base_engagement": 0.45,                           # their avg engagement
+    "tag_preferences": ["ai", "startup", "coding"],
+}
+```
+
+### What the Agent Sees
+
+Each step, the observation includes:
+
+```python
+competitor_recent_posts: [
+    {"content_type": "reel", "topic": "AI tools", "tags": ["ai", "tools"],
+     "engagement": 0.61, "hours_ago": 3},
+    {"content_type": "carousel", "topic": "startup tips", "tags": ["startup"],
+     "engagement": 0.48, "hours_ago": 8},
+    {"content_type": "reel", "topic": "AI news", "tags": ["ai", "news"],
+     "engagement": 0.52, "hours_ago": 14},
+]
+competitor_avg_engagement: 0.54
+niche_saturation: 0.7   # 0.0=empty, 1.0=everyone posting same stuff
+```
+
+### How Competitors Affect Your Engagement
+
+```
+if your topic overlaps with ≥2 competitor posts in last 12hrs:
+    niche_saturation → high (0.7+)
+    your engagement × 0.6  (audience already saw similar content)
+
+if your topic is unique (no overlap in 12hrs):
+    competitor_diff_bonus = 1.3x  (fresh angle, algorithm favors)
+
+if competitor engagement is HIGH on a topic:
+    that topic has proven demand, but also competition
+    → agent must decide: follow the proven topic (safe) or differentiate (risky but higher upside)
+```
+
+### What the Agent Must Learn
+
+1. **Monitor** competitor posting patterns and timing
+2. **Differentiate** — find underserved time slots and topics
+3. **Counter-program** — post different content type when competitors flood reels
+4. **Learn from competitor success** — if competitor's carousel on "AI" got 0.8 engagement, the topic has demand, but post at a different time or with different tags
+
+---
+
+## Tasks & Graders (All Weekly — 168 steps)
+
+All three tasks run for exactly **1 week (168 hourly steps)**. The difficulty increases through what dimensions are graded and what constraints apply.
+
+### Task 1: weekly_engage (Easy)
+
+**Focus**: Pure engagement maximization.
+
+**What's active**: Basic mechanics only — time of day, content type, energy, audience fatigue.
+
+**What's NOT graded**: Tags, competitors (still simulated but don't affect score).
+
+**Grader formula**:
+
+```
+score = total_engagement / theoretical_max_engagement
+```
+
+**Theoretical max**: Calculated as if agent posted at every peak hour with best content type at full energy. Roughly ~14 optimal posts over 7 days.
+
+**How it's computed**:
+1. Sum all engagement values from every post the agent made
+2. Divide by the theoretical max (computed from: 2 posts/day × 7 days × peak_hour_mult × best_content_rate × quality=1.0)
+3. Clamp to [0.0, 1.0]
+
+**What a smart agent does**: Posts 1-2x/day at peak hours (12-3PM), uses high-engagement content types (carousel/reel), rests to keep energy above 0.5.
+
+**What a dumb agent scores**: Random ≈ 0.08–0.12. Spam-every-hour ≈ 0.15–0.25 (audience fatigue kills it).
+
+---
+
+### Task 2: weekly_strategic (Medium)
+
+**Focus**: Engagement + energy management + tag optimization.
+
+**What's active**: Everything from Task 1, PLUS tag engagement system.
+
+**Grader formula**:
+
+```
+tag_discovery = unique_tags_used_with_positive_engagement / total_tag_pool_size
+tag_exploitation = avg(top_3_tag_performances) / max_possible_tag_performance
+
+tag_score = 0.4 × tag_discovery + 0.6 × tag_exploitation
+
+score = (0.35 × normalized_engagement)
+      + (0.25 × tag_score)
+      + (0.25 × avg_energy)
+      + (0.15 × consistency_score)
+```
+
+**Constraints**:
+- If energy ever drops below 0.3 → score capped at 0.5
+- If fewer than 5 unique tags used across the week → score × 0.7
+
+**How each component works**:
+
+| Component | What it measures | How it's normalized |
+|---|---|---|
+| `normalized_engagement` | Total engagement across all posts | `sum(engagement) / theoretical_max` |
+| `tag_discovery` | Did the agent explore different tags? | `unique_positive_tags / 30 (pool size)` |
+| `tag_exploitation` | Did the agent learn which tags work and reuse them? | `avg(best 3 tags) / 1.0` |
+| `avg_energy` | Did the agent maintain sustainable energy? | `mean(energy at each step) / 1.0` |
+| `consistency_score` | Regular posting rhythm | `days_with_1_or_2_posts / 7` |
+
+**What a smart agent does**: Explores different tags in days 1-2, identifies top performers by day 3, then exploits them while riding trending tags. Balances rest to keep energy > 0.5.
+
+**What a dumb agent scores**: Random ≈ 0.10–0.15 (random tags, no learning). Always-same-tags ≈ 0.20 (no discovery).
+
+---
+
+### Task 3: weekly_competitive (Hard)
+
+**Focus**: Everything + competitor awareness + follower growth.
+
+**What's active**: Full simulation — engagement, tags, competitors, niche saturation.
+
+**Grader formula**:
+
+```
+follower_growth = (final_followers - initial_followers) / initial_followers
+normalized_growth = min(1.0, follower_growth / target_growth_rate)
+
+competitor_outperformance = your_avg_engagement / competitor_avg_engagement
+normalized_outperformance = min(1.0, competitor_outperformance / 1.5)
+
+differentiation = steps_where_topic_was_unique / total_posting_steps
+
+score = (0.25 × normalized_engagement)
+      + (0.20 × tag_score)           ← same formula as Task 2
+      + (0.20 × normalized_growth)
+      + (0.15 × normalized_outperformance)
+      + (0.10 × differentiation)
+      + (0.10 × min_energy_floor)
+```
+
+**Constraints**:
+- Energy hits 0 → score = 0.0 (total fail, burned out)
+- Fewer than 3 content types used → score × 0.5
+- Fewer than 8 unique tags used → score × 0.7
+- If agent never checks competitor patterns (always overlaps) → differentiation = 0
+
+**How each component works**:
+
+| Component | Weight | What it measures | Detail |
+|---|---|---|---|
+| `normalized_engagement` | 25% | Raw engagement quality | Same as Task 1 |
+| `tag_score` | 20% | Tag strategy quality | Discovery + exploitation (Task 2 formula) |
+| `normalized_growth` | 20% | Follower growth over the week | `target_growth_rate` = 5% (500 new followers on 10K base) |
+| `normalized_outperformance` | 15% | Beat your competitors | Your avg engagement / competitor avg. Capped at 1.0 when you're 1.5x better |
+| `differentiation` | 10% | Posting unique angles | % of your posts where topic wasn't posted by competitors in last 12hrs |
+| `min_energy_floor` | 10% | Never crashed | `min(energy_history)` — lowest energy point. Rewards agents that never dipped dangerously low |
+
+**What a smart agent does**:
+1. Days 1-2: Explore tags, observe competitor patterns
+2. Days 3-4: Exploit best tags, counter-program competitors (post when they rest, pick gaps)
+3. Days 5-7: Maximize engagement with learned strategy, maintain energy, diversify content types
+
+**What a dumb agent scores**: Random ≈ 0.08. Copy-competitor-strategy ≈ 0.20 (no differentiation). Smart ≈ 0.50–0.75.
+
+---
+
+## Grading Strategy — In Depth
+
+### Why Weekly for All Tasks
+
+- **Consistency**: Same horizon (168 steps) makes graders comparable
+- **Runtime**: 168 steps × 3 tasks = 504 total LLM calls. At ~2s per call = ~17 minutes. Under the 20-minute limit
+- **Meaningful cycle**: A week is the natural content planning cycle for creators. Days are too short to show learning. Months are too long for inference budget
+
+### Grading Philosophy
+
+The grading is designed so that **each task requires mastering the previous task's skills plus new ones**:
+
+```
+Task 1 (Easy)    → Can you post well?
+                    (timing + content type + energy)
+
+Task 2 (Medium)  → Can you post SMART?
+                    (Task 1 + tag discovery + tag exploitation)
+
+Task 3 (Hard)    → Can you OUTCOMPETE?
+                    (Task 2 + competitor awareness + differentiation + growth)
+```
+
+### Why These Weights
+
+**Task 1** — Engagement is everything (100% engagement-derived). Pure skill test.
+
+**Task 2** — Split focus:
+- 35% engagement (still important, but not enough alone)
+- 25% tags (new skill: must explore AND exploit)
+- 25% energy (sustainability matters now)
+- 15% consistency (rhythm matters)
+
+**Task 3** — Multi-dimensional:
+- No single component dominates (max 25%)
+- Agent must be good at everything, great at nothing is fine
+- `differentiation` (10%) is small but acts as tiebreaker between otherwise similar agents
+- `min_energy_floor` (10%) punishes agents that nearly crashed even if they recovered
+
+### Anti-Gaming Properties
+
+| Potential Exploit | Why it fails |
+|---|---|
+| Post every hour | Audience fatigue kills engagement → low `normalized_engagement` |
+| Always rest | Zero engagement, zero tag score, zero growth → score ≈ 0.05 |
+| Use same 2 tags always | `tag_discovery` tanks in Task 2/3. Score × 0.7 penalty if < 5/8 tags |
+| Copy competitor topics | `differentiation` = 0, `niche_saturation` high → engagement × 0.6 |
+| Post only reels | Score × 0.5 in Task 3 (need ≥ 3 types) |
+| Ignore competitors entirely | Random overlap → sometimes lucky, but `differentiation` averages low |
+| Post gibberish topics | Topic validation + no trending match → low engagement |
+
+### Score Distribution (Expected)
+
+| Agent Type | Task 1 | Task 2 | Task 3 |
+|---|---|---|---|
+| Random | 0.08–0.12 | 0.10–0.15 | 0.06–0.10 |
+| Always rest | 0.02 | 0.05 | 0.02 |
+| Spam (post every step) | 0.15–0.25 | 0.12–0.18 | 0.08–0.15 |
+| Fixed strategy (no learning) | 0.30–0.40 | 0.25–0.35 | 0.20–0.30 |
+| Smart LLM agent | 0.55–0.80 | 0.45–0.70 | 0.40–0.65 |
+
+Task 3 is intentionally hardest — even a good agent won't ace it because competitor dynamics add noise and require adaptation.
+
+---
+
+## Anti-Exploit Guards
+
+| Exploit | Guard |
+|---|---|
+| Reward hacking (long gibberish) | Cap reward per step at 1.0, validate topic, max 200 chars |
+| Grader gaming | Random agent must score < 0.15, spam agent < 0.30 |
+| State reset abuse | Reset only works between tasks, mid-episode reset ignored |
+| Invalid actions | Strict field validation, invalid → 0 reward + error |
+| Rest farming | Rest → reward ≈ 0, energy is a resource not a goal |
+| Repetitive posting | Same type 3x → engagement -20% + energy penalty |
+| Tag spamming | Max 5 tags per post, must be from known pool |
+| Competitor copying | Niche saturation penalty, differentiation score = 0 |
+
+### Sanity Test Agents
+
+Run before submitting:
+
+| Agent | Expected Score (Task 3) | Red Flag If |
+|---|---|---|
+| Random agent | < 0.10 | Reward too easy |
+| Always-rest | < 0.05 | Resting rewarded |
+| Spam (post every step, same type) | < 0.15 | No fatigue working |
+| Fixed (same action every time) | < 0.30 | Environment too simple |
+| Smart (LLM-driven) | 0.40–0.65 | This is the real range |
+
+---
+
+## Simulation Mechanics
+
+### Energy Dynamics (research-backed)
+
+```python
+energy -= content_cost[action.content_type]
+
+# Repetition fatigue (creative fatigue = 40% of burnout)
+if action.content_type == last_3_posts_type:
+    energy -= 0.05
+
+# Recovery: slow, not instant
+if action.action_type == "rest":
+    energy = min(1.0, energy + 0.12)
+
+# Quality modifier (30-52% productivity drop at burnout)
+quality = 1.0 if energy > 0.5 else max(0.48, energy * 1.5)
+```
+
+### Extended Features
+
+#### A. Content Repetition Fatigue
+Same content type 3x in a row → engagement drops 20%. Based on creative fatigue being #1 burnout cause (40%).
+
+#### B. Platform Activity / Competition Window
+`niche_saturation` (0.0–1.0) in observation. When many competitors post same topic → per-post engagement drops. From the broadcast scheduling paper (Preprints.org 2025).
+
+#### C. Follower Tier Response
+Small accounts (<10K) get more from reels (reach). Large accounts (>50K) benefit from carousels (depth). From CreatorsJet 10K post study.
+
+#### D. Trending Topic & Tag Bonus
+If topic or tags match trending → 1.5x and +10% respectively. Topics and tags rotate daily (seeded). Forces adaptive behavior.
+
+#### E. Algorithm Penalty for Inconsistency
+No post for 48+ hours → next 2 posts get 0.6x engagement. Based on algorithmic content selection research (arxiv:2410.13108).
+
+#### F. Tag Engagement Tracking
+Full per-tag engagement history. Agent sees which tags produce results and must balance exploration (try new tags) vs exploitation (reuse winners). See Tag Engagement System section.
+
+#### G. Competitor Awareness
+3 simulated rival creators with deterministic posting schedules. Agent sees their recent posts, topics, tags, and engagement. Must differentiate to avoid saturation. See Competitor Intelligence System section.
+
+---
+
+## Research Backing
+
+### Engagement Data
+
+- **Buffer 2026**: 9.6M posts analyzed — peak posting times, day-of-week effects
+- **SocialInsider 2025**: Engagement rates by content type (carousel 0.55%, reel 0.52%, image 0.37%)
+- **CreatorsJet 10K post study**: Reels give 2.25x reach vs images, carousels give depth
+
+### Burnout Data
+
+- **Sozee 2026**: 90% creators experience burnout, 30-52% productivity drop
+- **TastyEdits Creator Study**: 57% spend 4+ hrs/day, 79% have experienced burnout
+- **Creative fatigue**: #1 cause at 40%, algorithm pressure at 38%
+
+### Academic Papers
+
+| Paper | Relevance |
+|---|---|
+| "Review Old Strategies, New Environments: RL on Social Media" (ScienceDirect 2024) | RL framework for social media — validates env design |
+| arxiv:2410.13108 "Algorithmic Content Selection and User Disengagement" | Over-optimizing immediate engagement causes churn — justifies burnout mechanic |
+| arxiv:2211.13585 "Learning Optimal Break Policies" | Strategic breaks sustain engagement — supports "rest" action |
+| "Optimizing Broadcast Scheduling" (Preprints.org 2025) | Low-competition windows > frequency — competition variable |
+| RLNVR arxiv:2508.12165 | RL from noisy social media signals — proves this is active research |
+
+### Data Sources
+
+- **Meta Content Library**: Real engagement data for public Instagram/Facebook posts ([docs](https://developers.facebook.com/docs/content-library-and-api))
+- **Meta Graph API — Creator Marketplace Insights**: Real creator metrics ([docs](https://developers.facebook.com/docs/graph-api/reference/creator-marketplace-content/insights/))
+
+---
+
+## Inference Script Structure
+
+```python
+import os
+from openai import OpenAI
+from viraltest import ViraltestEnv, ViraltestAction
+
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+MODEL_NAME = os.getenv("MODEL_NAME") or "Qwen/Qwen2.5-72B-Instruct"
+TASKS = ["weekly_engage", "weekly_strategic", "weekly_competitive"]
+MAX_STEPS = 168  # 7 days × 24 hours (same for all tasks)
+
+client = OpenAI(api_key=API_KEY, base_url=API_BASE_URL)
+
+for task in TASKS:
+    log_start(task, "viraltest", MODEL_NAME)
+    env = ViraltestEnv(base_url="http://localhost:8000")
+    result = env.reset(task=task)
+    rewards = []
+
+    for step in range(MAX_STEPS):
+        obs = result.observation
+        user_msg = format_observation(obs)
+        response = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_msg}
+            ],
+            temperature=0.7, max_tokens=150
+        )
+        action = parse_action(response.choices[0].message.content)
+        result = env.step(action)
+        rewards.append(result.reward)
+        log_step(step+1, str(action), result.reward, result.done, None)
+        if result.done:
+            break
+
+    score = grader_score(task, rewards, obs)
+    log_end(score > 0.1, len(rewards), score, rewards)
+    env.close()
+```
+
+Log format:
+
+```
+[START] task=weekly_competitive env=viraltest model=Qwen/Qwen2.5-72B-Instruct
+[STEP] step=1 action=post(reel,"AI trends",["ai","tech"]) reward=0.67 done=false error=null
+[STEP] step=2 action=rest() reward=0.05 done=false error=null
+...
+[END] success=true steps=168 score=0.624 rewards=0.67,0.05,...,0.55
+```
+
+---
+
+## Judging Alignment
+
+| Criteria | Weight | What backs us |
+|---|---|---|
+| Real-world utility | 30% | Meta Content Library, Buffer study, creator burnout stats, tag analytics, competitor analysis |
+| Task & grader quality | 25% | 3 weekly tasks with progressive difficulty, multi-component graders, deterministic |
+| Environment design | 20% | Energy from burnout studies, engagement from SocialInsider, tag + competitor systems |
+| Code quality & spec | 15% | OpenEnv compliant, typed models, Dockerfile works |
+| Creativity & novelty | 10% | Multi-objective (engagement vs burnout vs tags vs competition), backed by 5+ papers |
+
+---
+
+## File Map
+
+| File | Purpose |
+|---|---|
+| `models.py` | `ViraltestAction` and `ViraltestObservation` Pydantic models |
+| `server/viraltest_environment.py` | Simulation logic, task switching, graders, reward calc, tag + competitor systems |
+| `client.py` | `ViraltestEnv` client — `_step_payload`, `_parse_result`, `_parse_state` |
+| `inference.py` | LLM-driven agent with `[START]`/`[STEP]`/`[END]` logging |
+| `openenv.yaml` | Environment metadata |
+| `Dockerfile` | Container build |
+| `README.md` | User-facing docs |
+| `DESIGN.md` | This file |

Dockerfile

@@ -0,0 +1,82 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+# Multi-stage build using openenv-base
+# This Dockerfile is flexible and works for both:
+# - In-repo environments (with local OpenEnv sources)
+# - Standalone environments (with openenv from PyPI/Git)
+# The build script (openenv build) handles context detection and sets appropriate build args.
+
+ARG BASE_IMAGE=ghcr.io/meta-pytorch/openenv-base:latest
+FROM ${BASE_IMAGE} AS builder
+
+WORKDIR /app
+
+# Ensure git is available (required for installing dependencies from VCS)
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git && \
+    rm -rf /var/lib/apt/lists/*
+
+# Build argument to control whether we're building standalone or in-repo
+ARG BUILD_MODE=in-repo
+ARG ENV_NAME=viraltest
+
+# Copy environment code (always at root of build context)
+COPY . /app/env
+
+# For in-repo builds, openenv is already vendored in the build context
+# For standalone builds, openenv will be installed via pyproject.toml
+WORKDIR /app/env
+
+# Ensure uv is available (for local builds where base image lacks it)
+RUN if ! command -v uv >/dev/null 2>&1; then \
+        curl -LsSf https://astral.sh/uv/install.sh | sh && \
+        mv /root/.local/bin/uv /usr/local/bin/uv && \
+        mv /root/.local/bin/uvx /usr/local/bin/uvx; \
+    fi
+    
+# Install dependencies using uv sync
+# If uv.lock exists, use it; otherwise resolve on the fly
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-install-project --no-editable; \
+    else \
+        uv sync --no-install-project --no-editable; \
+    fi
+
+RUN --mount=type=cache,target=/root/.cache/uv \
+    if [ -f uv.lock ]; then \
+        uv sync --frozen --no-editable; \
+    else \
+        uv sync --no-editable; \
+    fi
+
+# Final runtime stage
+FROM ${BASE_IMAGE}
+
+WORKDIR /app
+
+# Copy the virtual environment from builder
+COPY --from=builder /app/env/.venv /app/.venv
+
+# Copy the environment code
+COPY --from=builder /app/env /app/env
+
+# Set PATH to use the virtual environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Set PYTHONPATH so imports work correctly
+ENV PYTHONPATH="/app/env:$PYTHONPATH"
+
+ENV ENABLE_WEB_INTERFACE=true
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
+# Run the FastAPI server
+# The module path is constructed to work with the /app/env structure
+CMD ["sh", "-c", "cd /app/env && uvicorn viraltest.server.app:app --host 0.0.0.0 --port 8000"]

README.md

@@ -1,12 +1,215 @@
 ---
-title: Train Bhai Train
-emoji: 🦀
-colorFrom: blue
-colorTo: pink
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
+title: Viraltest — Creator Optimization Agent
+emoji: 📊
+colorFrom: yellow
+colorTo: indigo
+sdk: docker
 pinned: false
+app_port: 8000
+base_path: /web
+tags:
+  - openenv
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Viraltest v2 — World-Modeling RL Environment for Instagram Strategy
+
+> **Theme #3.1 — Professional Tasks (World Modeling)**
+> An [OpenEnv](https://github.com/meta-pytorch/OpenEnv) environment where an LLM agent manages an Instagram creator account over 30 simulated days, discovering the world through tools rather than being told the rules.
+
+## What this teaches the LLM
+
+| Capability | How the environment tests it |
+|---|---|
+| **Tool discovery & orchestration** | 8 discoverable tools (`query_trends`, `query_competitor`, `predict_engagement`...). Agent must call `GET /tools` to learn what's available. |
+| **Persistent world model** | 30-day horizon. Multi-episode brand chain carries state across months. |
+| **Belief tracking** | `notes` field persists hypotheses day-to-day. Agent must update beliefs from tool results. |
+| **Causal reasoning** | `coach_feedback` returns counterfactual delta (your plan vs. heatmap-optimal). `predict_engagement` lets agent test hypotheses before committing. |
+| **Partial observability** | Default observation is sparse: energy, followers, reward. Rich data (trends, competitors, tags) only via tools. |
+| **Multi-step workflow** | Per day: discover → query → draft → predict → commit → reply → learn from feedback. |
+
+## Why this matters
+
+The $250B creator economy ([Goldman Sachs, 2025](https://www.goldmansachs.com/insights/articles/the-creator-economy-could-approach-half-a-trillion-dollars-by-2027)) has 67M creators, but 73% experience burnout ([Awin, 2024](https://www.prweb.com/releases/a-majority-of-content-creators-and-influencers-struggle-with-burnout-as-concerns-for-ai-begin-to-surface-according-to-a-new-awin-group-survey-research-302257152.html)). This environment turns the posting-vs-burnout tradeoff into a reproducible simulation calibrated against 10+ verifiable sources.
+
+## Quick Start
+
+```python
+import asyncio
+from viraltest import ViraltestAction, ViraltestEnv
+from viraltest.models import ToolCall
+
+async def main():
+    env = ViraltestEnv(base_url="http://localhost:8000")
+    try:
+        result = await env.reset(task="monthly_strategic")
+        action = ViraltestAction(
+            tool_calls=[
+                ToolCall(name="query_trends", arguments={"niche": "tech"}),
+            ],
+            scheduled_actions=[
+                {"hour": 12, "action_type": "post", "content_type": "reel",
+                 "topic": "AI tools", "tags": ["ai", "coding"], "intent": "watch_bait"},
+            ],
+            notes="Day 1: querying trends to establish baseline.",
+        )
+        result = await env.step(action)
+        print(result.observation.engagement_signals)
+    finally:
+        await env.close()
+
+asyncio.run(main())
+```
+
+## Simulation mechanics
+
+### Engagement signals (Mosseri Jan-2025)
+
+Instagram's head confirmed the top-3 ranking signals. Our reward decomposes engagement accordingly:
+
+| Signal | Weight | Best format | Source |
+|--------|--------|-------------|--------|
+| Watch time | 0.40 | Reels | Mosseri Jan-2025 |
+| Sends per reach | 0.30 | Stories | Mosseri Jan-2025 |
+| Saves | 0.20 | Carousels | Mosseri Jan-2025 |
+| Likes per reach | 0.10 | Text posts | Mosseri Jan-2025 |
+
+### Hour heatmap
+
+7×24 multiplier grid from [Buffer 9.6M posts](https://buffer.com/resources/when-is-the-best-time-to-post-on-instagram) cross-validated with [Sprout Social 2B engagements](https://sproutsocial.com/insights/best-times-to-post-on-social-media/).
+
+### Sleep model
+
+Piecewise-linear from [Van Dongen et al. 2003](https://pubmed.ncbi.nlm.nih.gov/12683469) (*Sleep*, PMID 12683469): no quality loss below 16h awake, then 6.25% per hour, floor at 30%.
+
+### Audience fatigue
+
+Tiered from [Buffer 2.1M study](https://buffer.com/resources/how-often-to-post-on-instagram/): 2 posts/day=1.0×, 3=0.75×, 4=0.50×, 5+=0.25×. Weekly cap at 7 posts → 0.75×.
+
+## Tasks and graders (30 steps each)
+
+| Task | Difficulty | Grader focus |
+|------|-----------|--------------|
+| `monthly_engage` | Easier | Total engagement vs theoretical max; burnout penalty |
+| `monthly_strategic` | Medium | + tag discovery/exploitation + energy + consistency |
+| `monthly_competitive` | Hard | + growth vs competitors + differentiation + content diversity |
+
+## Regulator/Judge Mode (per-day audit)
+
+Every day the env emits a deterministic, explainable `JudgeReport` on the observation:
+
+```python
+JudgeReport(
+    policy_compliance=1.00,    # 1.0 - sum(weighted_violations); see _compute_judge_report
+    sustainability_risk=0.10,  # 0.4*(1-energy_min) + 0.3*sleep_debt + 0.3*low_energy_ratio
+    strategic_quality=0.96,    # 0.4*engagement_per_post + 0.3*intent_diversity + 0.3*format_diversity
+    explanation="compliance=1.00 risk=0.10 strategy=0.96 | no policy violations",
+    violations=[],             # human-readable rule breaks (Buffer 2.1M, Van Dongen, Cen 2024)
+)
+```
+
+Auditable rules (all sourced): >5 posts/day → fatigue cliff (Buffer 2.1M); >7 posts/week → weekly cap; ≥4 collabs/month → diminishing returns (Cen 2024); >22h awake → sleep debt (Van Dongen 2003).
+
+## Headline metrics (final-step audit)
+
+The final observation carries `HeadlineMetrics` with the three numbers judges remember:
+
+| Metric | What it measures | Source of truth |
+|---|---|---|
+| `vs_baseline_pct` | (agent_score − heuristic_baseline) / heuristic_baseline | Empirical baseline loaded from `plots/training_summary.json["smart_heuristic"]` (0.43 / 0.77 / 0.81) |
+| `score_per_tool_call` | grader_score / total_tool_calls | Efficiency: did the agent learn to call tools sparingly? |
+| `score_per_1k_chars` | grader_score per 1k action JSON chars | Token-proxy efficiency |
+| `retention_under_shift` | shifted_score / baseline_score | Pass `episode_chain_id` + `shift_label="baseline"` then `="shifted"` to a second `reset` to populate. None until both runs complete. |
+
+## Tool catalog
+
+| Tool | Cost | Returns |
+|------|------|---------|
+| `query_trends` | 1 | Trending topics, tags, niche saturation |
+| `query_competitor` | 2 | Recent posts, avg engagement, strategy |
+| `query_tag_history` | 1 | Your historical signals per tag |
+| `query_audience` | 2 | Segment affinities, active hours |
+| `predict_engagement` | 3 | Simulated signals without committing |
+| `draft_review` | 3 | Strengths/weaknesses of a plan |
+| `query_creator_pool` | 1 | Available collab partners + overlap |
+| `propose_collab` | 5 | Propose collaboration (max 2/month) |
+
+API budget starts at 100 per episode.
+
+## Sources & verifiability
+
+Every constant is backed by a Tier 1–3 source. Full bibliography with DOIs, PMIDs, and methodology extracts: **[RESEARCH.md](RESEARCH.md)**.
+
+| Tier | Count | Example |
+|------|-------|---------|
+| T1 (Peer-reviewed) | 7 papers | Van Dongen 2003, arxiv:2410.13108 |
+| T2 (Industry, large-N) | 9 studies | Buffer 9.6M, Sprout 2B, Rival IQ 1.9M |
+| T3 (Official) | 1 statement | Mosseri Jan-2025 |
+| T4 (Survey) | 2 surveys | Awin 2024 (n=300+) |
+| T5 (Rejected) | 13 sites | No methodology disclosed |
+
+## Storytelling assets
+
+- [HuggingFace blog](blog/hf_mini_blog.md)
+- [YouTube script (<2 min)](blog/youtube_script.md)
+- [Slide deck outline](blog/slide_outline.md)
+
+## Local development
+
+```bash
+git clone <repo-url> && cd viraltest
+uv sync
+
+# Terminal 1 — API server
+uvicorn viraltest.server.app:app --host 0.0.0.0 --port 8000
+
+# Terminal 2 — inference
+export HF_TOKEN=hf_...
+export API_BASE_URL=https://router.huggingface.co/v1
+export MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
+.venv/bin/python inference.py
+```
+
+## Docker
+
+```bash
+docker build -t viraltest-env:latest .
+docker run --rm -p 8000:8000 viraltest-env:latest
+curl -s -X POST -H "Content-Type: application/json" -d '{}' http://localhost:8000/reset
+```
+
+## Project structure
+
+```
+.
+├── inference.py                # Tool-discovery agent (no hint keys)
+├── openenv.yaml                # OpenEnv manifest
+├── models.py                   # Action/Observation + ToolCall, EngagementSignals
+├── client.py                   # ViraltestEnv client (async)
+├── Dockerfile
+├── RESEARCH.md                 # Full sourced bibliography (6+ pages)
+├── DESIGN.md                   # Deep design notes
+├── blog/
+│   ├── hf_mini_blog.md
+│   ├── youtube_script.md
+│   └── slide_outline.md
+├── server/
+│   ├── app.py                  # FastAPI + /tools endpoints
+│   ├── viraltest_environment.py
+│   ├── dashboard.html
+│   └── data/
+│       ├── tags.json           # ~120 tags, 4 tiers
+│       ├── topics.json         # Niche multipliers + seasonal calendar
+│       ├── competitors.json    # 7 archetypes
+│       ├── hour_heatmap.json   # 7×24 from Buffer+Sprout
+│       ├── audience_segments.json
+│       └── audience_overlap_matrix.json
+├── training/
+│   └── train_grpo.ipynb        # TRL GRPO on Qwen2.5-1.5B-Instruct
+└── plots/
+    ├── reward_curve.png
+    └── before_after.png
+```
+
+## License
+
+See `LICENSE` in the repository root (BSD-style per upstream OpenEnv examples).

RESEARCH.md

@@ -0,0 +1,302 @@
+# Research Bibliography — Viraltest v2
+
+Every constant and design decision in Viraltest is backed by a verifiable source. This document groups sources by quality tier so any reviewer can audit our claims.
+
+## Source quality bar
+
+| Tier | Criteria | Example |
+|------|----------|---------|
+| **T1** — Peer-reviewed | Published in a journal or arXiv with disclosed methodology, sample, and peer review | Van Dongen 2003 *Sleep* |
+| **T2** — Industry research | Named org, disclosed methodology, sample ≥100K data points | Buffer 9.6M post study |
+| **T3** — Official platform | Public statement by platform leadership | Adam Mosseri, Head of Instagram |
+| **T4** — Survey (cite with caveat) | Named org, disclosed sample, no external audit | Awin 2024 (n=300+) |
+| **T5** — Rejected | SEO/affiliate blog, no methodology, no auditable sample | *Not cited* |
+
+---
+
+## Tier 1 — Peer-reviewed
+
+### Van Dongen HPA, Maislin G, Mullington JM, Dinges DF (2003)
+
+**Title:** The cumulative cost of additional wakefulness: dose-response effects on neurobehavioral functions and sleep physiology from chronic sleep restriction and total sleep deprivation
+
+**Venue:** *Sleep* 26(2):117–126 (Oxford University Press)
+**Type:** Randomized controlled trial
+**PMID:** [12683469](https://pubmed.ncbi.nlm.nih.gov/12683469)
+**DOI:** [10.1093/sleep/26.2.117](https://doi.org/10.1093/sleep/26.2.117)
+**Sample:** n=48 healthy adults (ages 21–38), laboratory conditions, 14 consecutive days
+
+**Methodology:** Subjects randomized to 4h, 6h, or 8h time-in-bed per night for 14 days, or 0h for 3 days. Continuous behavioral/physiological monitoring. Performance measured via psychomotor vigilance task (PVT), digit symbol substitution, serial addition/subtraction.
+
+**Key finding:** Lapses in behavioral alertness were near-linearly related to cumulative wakefulness exceeding **15.84 hours** (SE 0.73h), regardless of whether deprivation was chronic or total. 6h sleep/night for 14 days produced deficits equivalent to 1–2 nights of total sleep deprivation. Subjects were largely unaware of their impairment.
+
+**What we use:** `SLEEP_OPTIMAL_AWAKE = 16` (rounded from 15.84). Piecewise-linear quality decay: no loss below 16h awake, then `SLEEP_LINEAR_DECAY_PER_HOUR = 0.0625` (reaches ~50% at 24h), floor at `SLEEP_MIN_QUALITY = 0.30`.
+
+---
+
+### Cen Y et al. (2024)
+
+**Title:** Algorithmic Content Selection and the Impact of User Disengagement
+**Venue:** arXiv [2410.13108](https://arxiv.org/abs/2410.13108) (v2, Feb 2025)
+**Type:** Theoretical (multi-armed bandit model with user engagement states)
+
+**Methodology:** Introduces a content selection model where users have k engagement levels. Derives O(k²) dynamic programming for optimal policy. Proves no-regret online learning guarantees.
+
+**Key finding:** Content maximizing immediate reward is not necessarily optimal for sustained engagement. Higher friction (reduced re-engagement likelihood) counterintuitively leads to higher engagement under optimal policies. Modified demand elasticity captures how satisfaction changes affect long-term revenue.
+
+**What we use:** Justifies tiered fatigue model (`FATIGUE_TIERS`) — over-posting creates diminishing returns, not a cliff. Also informs the `ALGORITHM_PENALTY` mechanic.
+
+---
+
+### Aouali I et al. (2024)
+
+**Title:** System-2 Recommenders: Disentangling Utility and Engagement in Recommendation Systems via Temporal Point-Processes
+**Venue:** arXiv [2406.01611](https://arxiv.org/abs/2406.01611)
+**Type:** Theoretical + synthetic experiments
+
+**Methodology:** Generative model where user return probability depends on Hawkes process with System-1 (impulse) and System-2 (utility) components. Proves identifiability of utility from engagement data.
+
+**Key finding:** Pure engagement-driven optimization ≠ user utility. Utility-driven interactions have lasting return effects; impulse-driven interactions vanish rapidly. Platforms can disentangle the two from return-probability data.
+
+**What we use:** Informs the Mosseri-aligned reward decomposition (watch_time ≈ System-1 impulse; saves ≈ System-2 utility). Validates splitting engagement into distinct signals rather than a single float.
+
+---
+
+### Yu Y et al. (2024)
+
+**Title:** Uncovering the Interaction Equation: Quantifying the Effect of User Interactions on Social Media Homepage Recommendations
+**Venue:** arXiv [2407.07227](https://arxiv.org/abs/2407.07227)
+**Type:** Empirical (controlled experiments on YouTube, Reddit, X)
+
+**Key finding:** Platform algorithms respond to user interactions by adjusting content distribution. Evidence of topic deprioritization when engagement drops. Inactivity leads to reduced content surfacing.
+
+**What we use:** `FOLLOWER_DECAY_HOURS = 72` and `ALGORITHM_PENALTY` scaling with gap length.
+
+---
+
+### Lin Y et al. (2024)
+
+**Title:** Unveiling User Satisfaction and Creator Productivity Trade-Offs in Recommendation Platforms
+**Venue:** arXiv [2410.23683](https://arxiv.org/abs/2410.23683)
+**Type:** Theoretical + empirical
+
+**Key finding:** Relevance-driven recommendation boosts short-term satisfaction but harms long-term content richness. Explorative policy slightly lowers satisfaction but promotes content production volume.
+
+**What we use:** Justifies multi-episode brand persistence — the creator's long-term niche identity matters more than per-post optimization.
+
+---
+
+### Cao X, Wu Y, Cheng B et al. (2024)
+
+**Title:** An investigation of the social media overload and academic performance
+**Venue:** *Education and Information Technologies* 29:10303–10328 (Springer)
+**DOI:** [10.1007/s10639-023-12213-6](https://doi.org/10.1007/s10639-023-12213-6)
+**Sample:** n=249 university students, survey
+**Type:** Quantitative survey study
+
+**Key finding:** Techno-invasion and techno-overload create psychological stress → exhaustion → perceived irreplaceability → reduced performance. Social support partially buffers the effect.
+
+**What we use:** `burnout_risk` observation field — exhaustion accumulates gradually (not binary), mirrors the stress→exhaustion→performance pathway.
+
+---
+
+### Wen J, Wang H, Chen H (2026)
+
+**Title:** Research on the formation mechanism of social media burnout among college students based on the ISM-MICMAC model
+**Venue:** *Scientific Reports* (Nature)
+**DOI:** 10.1038/s41598-026-42958-2
+**Sample:** 8 experts (Delphi method), 58 papers reviewed, 15 factors identified
+
+**Key finding:** Algorithm recommendations and social comparison are the root-level structural drivers of burnout. Platform-technical mechanisms exert high driving power over subsequent overloads.
+
+**What we use:** Contextualizes the `burnout_risk` mechanic — algorithm pressure (our trending/saturation system) is a documented root cause.
+
+---
+
+## Tier 2 — Industry research (methodology disclosed, large N)
+
+### Buffer (2026) — Best Time to Post on Instagram
+
+**URL:** [buffer.com/resources/when-is-the-best-time-to-post-on-instagram](https://buffer.com/resources/when-is-the-best-time-to-post-on-instagram)
+**Sample:** 9.6 million posts
+**Methodology:** Engagement data aggregated by hour and day of week across Buffer users. Times in local timezone.
+
+**Key findings:** Peak: Thu 9am, Wed 12pm, Wed 6pm. Evenings 6–11pm strongest overall. Fri/Sat weakest. Wed best overall day.
+
+**What we use:** `server/data/hour_heatmap.json` — 7×24 multiplier grid.
+
+---
+
+### Buffer (2026) — How Often to Post on Instagram
+
+**URL:** [buffer.com/resources/how-often-to-post-on-instagram](https://buffer.com/resources/how-often-to-post-on-instagram)
+**Sample:** 2.1 million posts, 102K accounts
+**Methodology:** Julian Goldie analyzed posting frequency buckets (0, 1–2, 3–5, 6–9, 10+/week) vs follower growth and reach per post.
+
+**Key findings:** 3–5 posts/week doubles follower growth vs 1–2. 7+/week shows 20–35% engagement drop per post. Diminishing returns above 5/week.
+
+**What we use:** `FATIGUE_TIERS`, `WEEKLY_FATIGUE_THRESHOLD = 7`, `_theoretical_max_engagement` caps at 5 posts/week × `TASK_HORIZON/7` weeks (≈21 posts for 30-day horizon — the Buffer-defined sweet spot before fatigue penalties kick in).
+
+---
+
+### Sprout Social (2025) — The Sprout Social Index Edition XX
+
+**URL:** [sproutsocial.com/insights/index](https://sproutsocial.com/insights/index/)
+**Sample:** 4,044 consumers, 900 practitioners, 322 leaders (US/UK/Canada/Australia)
+**Methodology:** Online survey by Glimpse, Sept 13–27, 2024. Representative sampling.
+
+**What we use:** Audience preference context for `audience_segments.json`.
+
+---
+
+### Sprout Social (2026) — Best Times to Post on Social Media
+
+**URL:** [sproutsocial.com/insights/best-times-to-post-on-social-media](https://sproutsocial.com/insights/best-times-to-post-on-social-media/)
+**Sample:** ~2 billion engagements, 307,000 social profiles, 30K customers
+**Period:** Nov 27, 2025 – Feb 27, 2026
+**Methodology:** Internal Data Science team analysis. All times in local time.
+
+**Key findings:** IG peaks: Mon 2–4pm, Tue 1–7pm, Wed 12–9pm, Thu 12–2pm. Weekends worst.
+
+**What we use:** Cross-validates `hour_heatmap.json`. `FOLLOWER_DECAY_HOURS` informed by their reporting that reach decline starts after 3–4 days inactivity.
+
+---
+
+### Rival IQ (2025) — Social Media Industry Benchmark Report
+
+**URL:** [rivaliq.com/blog/social-media-industry-benchmark-report](https://www.rivaliq.com/blog/social-media-industry-benchmark-report/)
+**Sample:** 1.9 million IG posts, 2,100 brands (150 per industry × 14 industries)
+**Methodology:** Engagement = (likes + comments + shares + reactions) / followers. Median performance per industry. Companies with 25K–1M FB followers, >5K IG followers.
+
+**Key findings by industry (IG):** Higher Ed 2.10%, Sports 1.30%, Tech 0.33%, Food 0.37%, Fashion 0.14%.
+
+**What we use:** `_NICHE_MULTIPLIERS` in `topics.json`. Normalized by dividing by median (1.53) to create relative multipliers.
+
+---
+
+### Hootsuite (2025) — Social Trends Report 2025
+
+**URL:** [hootsuite.com/research/social-trends](https://hootsuite.com/research/social-trends)
+**Type:** Annual industry report
+
+**Key finding:** Optimal posting frequency 3–5/week for IG. 48–72 posts/week across all platforms for brands. 83% of marketers say AI helps create significantly more content.
+
+**What we use:** Validates frequency constants.
+
+---
+
+### Socialinsider (2026) — Instagram Organic Engagement Benchmarks
+
+**URL:** [socialinsider.io/blog/instagram-content-research](https://www.socialinsider.io/blog/instagram-content-research)
+**Sample:** 31 million posts analyzed
+
+**Key findings:** Carousels 0.55%, Reels 0.52%, Images 0.45%, text_post ~0.37%. Reels reach 30.81% (2.25× static). Carousels reach 14.45%.
+
+**What we use:** `BASE_ENGAGEMENT`, `REACH_MULT` constants.
+
+---
+
+### Later (2023) — Instagram Collaboration Posts Performance Study
+
+**URL:** [later.com/blog/instagram-collab-posts](https://later.com/blog/instagram-collab-posts)
+**Sample:** ~5K co-authored posts across the Later customer base (disclosed)
+**Methodology:** Comparison of Collab posts (single post shared to two feeds) vs equivalent solo posts from the same accounts.
+
+**Key findings:** Collab posts averaged ~88% more reach and ~40% more impressions than solo posts. Lift driven primarily by exposure to the partner's audience.
+
+**What we use:** `COLLAB_REACH_K = 0.60` — reach uplift scales with `(1 - overlap)` and is capped below the headline 88% because reach in our model is already amplified by `REACH_MULT` and `hour_mult`; net post-cap uplift on the constrained engagement value lands in the +30–50% band Later reports for matched-niche pairs.
+
+---
+
+### HypeAuditor (2024) — Influencer Collaboration Benchmark
+
+**URL:** [hypeauditor.com/blog/influencer-collaboration](https://hypeauditor.com/blog/influencer-collaboration)
+**Sample:** 10K+ Instagram collaboration posts across niches
+**Methodology:** Per-impression engagement rate, segmented by niche affinity (same niche, adjacent, cross-niche).
+
+**Key findings:** Same-niche collabs achieve ~30% higher engagement-per-impression than cross-niche; cross-niche collabs gain new followers but per-impression rate is roughly flat or slightly negative.
+
+**What we use:** `COLLAB_AFFINITY_K = 0.30` — engagement-per-impression boost scales with `overlap`, peaking when the partner's audience already shares the user's niche.
+
+---
+
+### Rival IQ (2025) — Cross-Industry Audience Overlap Patterns
+
+**URL:** [rivaliq.com/blog/social-media-industry-benchmark-report](https://www.rivaliq.com/blog/social-media-industry-benchmark-report/) (cross-industry chapter)
+
+**Key findings:** Same-industry account pairs share 40–65% of their audience; adjacent industries 20–35%; unrelated industries 5–15%. Cross-industry collabs drive new follower acquisition at roughly 2–2.5× the rate of same-industry collabs.
+
+**What we use:** `audience_overlap_matrix.json` values and `COLLAB_GROWTH_K = 1.50` — follower spillover scales with `(1 - overlap)`, peaking at +150% when overlap is zero (matches the upper end of Rival IQ's cross-industry follower-acquisition lift).
+
+Per-episode collab cadence is **not hard-capped**. Instead, each successive collab in a month is multiplied by `1 / (1 + COLLAB_FATIGUE_K · prior_collabs)` (`K = 0.3`): the multiplier falls to ~77% on the 2nd, 63% on the 3rd, 53% on the 4th. With base `engagement ≈ 1.52×` from a typical-overlap partner, this puts the 1st–2nd collab clearly above the no-collab baseline, the 3rd roughly neutral, and the 4th+ net-negative. This follows Cen et al. 2024's argument that disengagement-aware policies should price marginal exposure rather than impose binary caps, and lets the policy discover its own collab frequency from reward gradient.
+
+---
+
+### Goldman Sachs Global Investment Research (March 2025)
+
+**Title:** Creator Economy: Framing the Market Opportunity
+**URL:** [goldmansachs.com/insights/articles/the-creator-economy-could-approach-half-a-trillion-dollars-by-2027](https://www.goldmansachs.com/insights/articles/the-creator-economy-could-approach-half-a-trillion-dollars-by-2027)
+**Type:** Equity research note
+
+**Key findings:** ~67M global creators in 2025, growing 10% CAGR to 107M by 2030. Only 3% are professional (>$100K/yr). TAM ~$250B → $480B by 2027. 3% of YouTubers capture 90% of earnings.
+
+**What we use:** Problem framing in README. `INITIAL_FOLLOWERS = 10000` (micro-creator tier). `target_growth = 0.04` monthly (micro avg 0.8–1.5%/month → 0.04 as top-decile 4%/month target).
+
+---
+
+## Tier 3 — Official platform statements
+
+### Adam Mosseri, Head of Instagram (January 2025)
+
+**Source:** Public statements (Instagram posts, interviews)
+**Confirmed signals:**
+1. **Watch time** — most important ranking factor, especially Reels completion past 3 seconds
+2. **Sends per reach** — DM shares, strongest signal for reaching new audiences
+3. **Likes per reach** — key for existing followers
+4. Saves — content quality signal (not explicitly ranked top-3 but confirmed as strong)
+
+**What we use:** `FORMAT_SIGNAL_WEIGHTS`, `INTENT_MULTIPLIER`, `EngagementSignals` model, reward weights `0.4·watch + 0.3·sends + 0.2·saves + 0.1·likes`.
+
+---
+
+## Tier 4 — Surveys (cite with caveat)
+
+### Awin / ShareASale (September 2024)
+
+**Sample:** 300+ creators (majority female, 25–44, 1K–5K followers, Instagram 90%)
+**Finding:** 73% suffer burnout at least sometimes (down from 87% in 2022). Instagram drives 88% of burnout. Top cause: constant platform changes (70%).
+**URL:** [prweb.com/releases/...creator-burnout](https://www.prweb.com/releases/a-majority-of-content-creators-and-influencers-struggle-with-burnout-as-concerns-for-ai-begin-to-surface-according-to-a-new-awin-group-survey-research-302257152.html)
+
+**Caveat:** Self-selected sample, not probability-based. Small N. But directionally consistent with Wen 2026 (T1).
+**What we use:** `burnout_risk` contextual framing (73% baseline prevalence).
+
+### Vibely — Creator Burnout Report
+
+**Finding:** 90% of creators experienced burnout. 71% considered quitting.
+**Caveat:** No sample size or methodology disclosed. Treat as directional only.
+
+---
+
+## Tier 5 — Rejected sources (NOT cited in env constants)
+
+The following sites were found during research but are **not cited** because they do not disclose methodology, sample sizes, or data collection processes. Their claims cannot be independently verified.
+
+| Site | Why rejected |
+|------|-------------|
+| instacarousel.com | Affiliate blog, cites Socialinsider without adding primary data |
+| midastools.co | SEO content, no methodology |
+| kicksta.co | Growth tool vendor, no audit trail |
+| postplanify.com | Aggregates others' data without attribution |
+| monolit.sh | Blog post, no primary research |
+| useadmetrics.com | Self-reported benchmarks, methodology unclear |
+| creatorflow.so | Aggregates without disclosure |
+| slumbertheory.com | Health blog, no clinical data source |
+| dataslayer.ai | Marketing tool blog |
+| almcorp.com | Agency blog |
+| loopexdigital.com | Agency blog |
+| carouselli.com | Tool vendor |
+| influize.com | Tag listicle, no methodology |
+
+---
+
+*This bibliography was compiled April 2026. All URLs verified at time of writing.*

__init__.py

@@ -0,0 +1,31 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Viraltest Environment."""
+
+from .client import ViraltestEnv
+from .models import (
+    CollabProposal,
+    EngagementSignals,
+    ReplyAction,
+    ScheduledAction,
+    ToolCall,
+    ToolResult,
+    ViraltestAction,
+    ViraltestObservation,
+)
+
+__all__ = [
+    "CollabProposal",
+    "EngagementSignals",
+    "ReplyAction",
+    "ScheduledAction",
+    "ToolCall",
+    "ToolResult",
+    "ViraltestAction",
+    "ViraltestObservation",
+    "ViraltestEnv",
+]

client.py

@@ -0,0 +1,121 @@
+"""Viraltest Environment Client (v2 — Theme #3.1)."""
+
+from typing import Any, Dict, List, Optional
+
+from openenv.core import EnvClient
+from openenv.core.client_types import StepResult
+from openenv.core.env_server.types import State
+
+from .models import (
+    EngagementSignals,
+    ToolResult,
+    ViraltestAction,
+    ViraltestObservation,
+)
+
+
+class ViraltestEnv(EnvClient[ViraltestAction, ViraltestObservation, State]):
+    """Client for the Viraltest Creator Optimization Environment v2."""
+
+    def _step_payload(self, action: ViraltestAction) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {}
+
+        if action.tool_calls:
+            payload["tool_calls"] = [
+                {"name": tc.name, "arguments": tc.arguments}
+                for tc in action.tool_calls
+            ]
+
+        actions_list = []
+        for sa in action.scheduled_actions:
+            item: Dict[str, Any] = {
+                "hour": sa.hour,
+                "action_type": sa.action_type,
+            }
+            if sa.content_type is not None:
+                item["content_type"] = sa.content_type
+            if sa.topic is not None:
+                item["topic"] = sa.topic
+            if sa.tags is not None:
+                item["tags"] = sa.tags
+            if sa.intent is not None:
+                item["intent"] = sa.intent
+            actions_list.append(item)
+        payload["scheduled_actions"] = actions_list
+
+        if action.replies:
+            payload["replies"] = [
+                {"post_hour": r.post_hour, "reply_hour": r.reply_hour}
+                for r in action.replies
+            ]
+
+        if action.collab:
+            payload["collab"] = {
+                "partner_id": action.collab.partner_id,
+                "content_type": action.collab.content_type,
+                "hour": action.collab.hour,
+            }
+
+        if action.notes is not None:
+            payload["notes"] = action.notes
+
+        return payload
+
+    def _parse_result(self, payload: Dict[str, Any]) -> StepResult[ViraltestObservation]:
+        obs_data = payload.get("observation", {})
+        grader_score = obs_data.get("grader_score")
+        meta = obs_data.get("metadata", {})
+        if grader_score is not None:
+            meta["grader_score"] = grader_score
+
+        signals_raw = obs_data.get("engagement_signals")
+        signals = EngagementSignals(**signals_raw) if signals_raw else None
+
+        tool_results_raw = obs_data.get("tool_results", [])
+        tool_results = [ToolResult(**tr) for tr in tool_results_raw]
+
+        observation = ViraltestObservation(
+            current_hour=obs_data.get("current_hour", 0),
+            day_of_week=obs_data.get("day_of_week", 0),
+            days_elapsed=obs_data.get("days_elapsed", 0),
+            creator_energy=obs_data.get("creator_energy", 1.0),
+            follower_count=obs_data.get("follower_count", 0),
+            engagement_rate=obs_data.get("engagement_rate", 0.0),
+            hours_since_sleep=obs_data.get("hours_since_sleep", 0),
+            posts_today=obs_data.get("posts_today", 0),
+            sleep_debt=obs_data.get("sleep_debt", 0.0),
+            time_since_last_post=obs_data.get("time_since_last_post", 0),
+            trending_topics=obs_data.get("trending_topics", []),
+            content_queue_size=obs_data.get("content_queue_size", 0),
+            last_post_type=obs_data.get("last_post_type", "none"),
+            burnout_risk=obs_data.get("burnout_risk", 0.0),
+            tag_performance=obs_data.get("tag_performance", {}),
+            trending_tags=obs_data.get("trending_tags", []),
+            competitor_recent_posts=obs_data.get("competitor_recent_posts", []),
+            competitor_avg_engagement=obs_data.get("competitor_avg_engagement", 0.0),
+            niche_saturation=obs_data.get("niche_saturation", 0.0),
+            daily_total_engagement=obs_data.get("daily_total_engagement", 0.0),
+            daily_posts_made=obs_data.get("daily_posts_made", 0),
+            daily_energy_min=obs_data.get("daily_energy_min", 1.0),
+            engagement_signals=signals,
+            coach_feedback=obs_data.get("coach_feedback"),
+            tool_results=tool_results,
+            agent_notes=obs_data.get("agent_notes"),
+            api_budget_remaining=obs_data.get("api_budget_remaining", 100),
+            grader_score=grader_score,
+            error=obs_data.get("error"),
+            done=payload.get("done", False),
+            reward=payload.get("reward"),
+            metadata=meta,
+        )
+        return StepResult(
+            observation=observation,
+            reward=payload.get("reward"),
+            done=payload.get("done", False),
+        )
+
+    def _parse_state(self, payload: Dict[str, Any]) -> State:
+        return State(
+            episode_id=payload.get("episode_id"),
+            step_count=payload.get("step_count", 0),
+        )

inference.py

@@ -0,0 +1,382 @@
+"""
+Viraltest Inference Script v2 — Theme #3.1 World-Modeling Agent
+================================================================
+The agent receives SPARSE observations and must use discoverable tools to learn
+the world (trending topics, competitor activity, tag performance, audience segments).
+No peak-hour hints, no fatigue rules, no content-type tips are provided in the prompt.
+
+MANDATORY env vars: API_BASE_URL, MODEL_NAME, HF_TOKEN/OPENAI_API_KEY/API_KEY
+Optional: IMAGE_NAME, ALLOW_SHORT_EPISODE, MAX_STEPS
+
+STDOUT FORMAT: [START] [STEP] [END] — match hackathon spec exactly.
+"""
+
+import asyncio
+import json
+import os
+import textwrap
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+
+from viraltest import ScheduledAction, ViraltestAction, ViraltestEnv
+from viraltest.models import ToolCall
+from viraltest.server.viraltest_environment import TASK_HORIZON, TOPIC_CATEGORIES
+
+DOCKER_IMAGE = os.getenv("IMAGE_NAME") or os.getenv("LOCAL_IMAGE_NAME")
+API_KEY = os.getenv("HF_TOKEN") or os.getenv("OPENAI_API_KEY") or os.getenv("API_KEY")
+API_BASE_URL = os.getenv("API_BASE_URL") or "https://router.huggingface.co/v1"
+MODEL_NAME = os.getenv("MODEL_NAME") or "Qwen/Qwen2.5-7B-Instruct"
+BENCHMARK = os.getenv("VIRALTEST_BENCHMARK", "viraltest")
+
+TASKS = ["monthly_engage", "monthly_strategic", "monthly_competitive"]
+_ALLOW_SHORT = os.getenv("ALLOW_SHORT_EPISODE", "").lower() in ("1", "true", "yes")
+_REQUESTED_MAX = int(os.getenv("MAX_STEPS", str(TASK_HORIZON)))
+MAX_STEPS = _REQUESTED_MAX if _ALLOW_SHORT else max(_REQUESTED_MAX, TASK_HORIZON)
+TEMPERATURE = 0.7
+MAX_TOKENS = 768
+SUCCESS_SCORE_THRESHOLD = 0.50
+
+ALL_TOPICS: List[str] = [
+    topic for topics in TOPIC_CATEGORIES.values() for topic in topics
+]
+_TOPIC_CANONICAL: Dict[str, str] = {t.lower(): t for t in ALL_TOPICS}
+
+NEAR_ZERO_ENERGY_THRESHOLD = 0.25
+
+# The agent is NOT told peak hours, fatigue rules, or content type tips.
+# It must discover these via the tool catalog.
+SYSTEM_PROMPT = textwrap.dedent("""\
+You are an Instagram content strategy agent. Each step is one full day (24 hours).
+You manage a creator account over a 30-day monthly cycle.
+
+You receive a SPARSE observation (energy, followers, last reward, notes echo).
+To learn about the world, you MUST use TOOLS before planning your day.
+
+AVAILABLE TOOLS (call via tool_calls before scheduling posts):
+- query_trends(niche): Get trending topics and tags for a niche
+- query_competitor(competitor_id, window_days): See competitor activity
+- query_tag_history(tag): Check your past performance with a tag
+- query_audience(segment_id): Learn audience segment preferences
+- predict_engagement(scheduled_actions): Simulate engagement without committing
+- draft_review(scheduled_actions): Get feedback on a draft plan
+- query_creator_pool(): List potential collab partners
+- propose_collab(partner_id, content_type, hour): Propose a collaboration
+
+RESPONSE FORMAT (JSON only, no markdown, no prose):
+{
+  "tool_calls": [
+    {"name": "query_trends", "arguments": {"niche": "tech"}},
+    {"name": "query_competitor", "arguments": {"competitor_id": "niche_expert", "window_days": 7}}
+  ],
+  "scheduled_actions": [
+    {"hour": 10, "action_type": "create_content"},
+    {"hour": 12, "action_type": "post", "content_type": "reel", "topic": "AI tools", "tags": ["ai", "coding"], "intent": "watch_bait"},
+    {"hour": 18, "action_type": "post", "content_type": "carousel", "topic": "startup life", "tags": ["startup", "growth"], "intent": "save_bait"}
+  ],
+  "replies": [{"post_hour": 12, "reply_hour": 13}],
+  "notes": "Day 3: tech niche trending up. Competitor Alpha posted at 10am. Avoiding overlap."
+}
+
+RULES:
+- hour: 0-23
+- action_type: "post" or "create_content"
+- For posts: content_type (reel|story|carousel|text_post), topic, tags (max 5), and intent are required
+- intent: what signal you optimize for (send_bait|save_bait|watch_bait|like_bait)
+- Empty scheduled_actions = rest all day
+- Use notes to track hypotheses and observations across days
+- Tool calls cost API budget (starts at 100). Use wisely.
+- Max 2 collaborations per month
+- Reply within 90 minutes of a post for reach bonus
+
+Think strategically: use tools to discover what works, then exploit what you learn.""")
+
+
+def should_force_rest_day(obs: Any) -> bool:
+    energy = float(getattr(obs, "creator_energy", 1.0))
+    return energy <= NEAR_ZERO_ENERGY_THRESHOLD
+
+
+def log_start(task: str, env: str, model: str) -> None:
+    print(f"[START] task={task} env={env} model={model}", flush=True)
+
+
+def log_step(step: int, action: str, reward: float, done: bool, error: Optional[str]) -> None:
+    error_val = error.replace(" ", "_") if error else "null"
+    done_val = str(done).lower()
+    print(
+        f"[STEP] step={step} action={action} reward={reward:.2f} "
+        f"done={done_val} error={error_val}",
+        flush=True,
+    )
+
+
+def log_end(
+    success: bool, steps: int, score: float, rewards: List[float],
+    headline: Optional[Any] = None,
+) -> None:
+    rewards_str = ",".join(f"{r:.2f}" for r in rewards)
+    head_str = ""
+    if headline is not None:
+        retention = headline.retention_under_shift
+        retention_str = f"{retention:.2f}" if retention is not None else "n/a"
+        head_str = (
+            f" vs_baseline_pct={headline.vs_baseline_pct:+.2%} "
+            f"score_per_tool={headline.score_per_tool_call:.3f} "
+            f"score_per_1k_chars={headline.score_per_1k_chars:.3f} "
+            f"retention_under_shift={retention_str}"
+        )
+    print(
+        f"[END] success={str(success).lower()} steps={steps} "
+        f"score={score:.2f} rewards={rewards_str}{head_str}",
+        flush=True,
+    )
+
+
+def format_observation(obs: Any) -> str:
+    days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+    day_name = days[obs.day_of_week] if 0 <= obs.day_of_week < 7 else "?"
+
+    notes_echo = getattr(obs, "agent_notes", None) or "none"
+    budget = getattr(obs, "api_budget_remaining", 100)
+    burnout = getattr(obs, "burnout_risk", 0.0)
+
+    tool_results_str = ""
+    for tr in getattr(obs, "tool_results", []):
+        if tr.success:
+            tool_results_str += f"  {tr.name}: {json.dumps(tr.data)[:200]}\n"
+        else:
+            tool_results_str += f"  {tr.name}: ERROR - {tr.error}\n"
+
+    coach = getattr(obs, "coach_feedback", None)
+    coach_str = ""
+    if coach:
+        coach_str = f"Coach: delta={coach.get('delta', 0):.3f}, suggestion={coach.get('suggestion', '')}\n"
+
+    judge = getattr(obs, "judge_report", None)
+    judge_str = ""
+    if judge:
+        judge_str = (
+            f"Judge: compliance={judge.policy_compliance:.2f} risk={judge.sustainability_risk:.2f} "
+            f"strategy={judge.strategic_quality:.2f} | {judge.explanation}\n"
+        )
+
+    signals = getattr(obs, "engagement_signals", None)
+    signals_str = ""
+    if signals:
+        signals_str = (
+            f"Signals: watch={signals.watch_time:.3f} sends={signals.sends_per_reach:.3f} "
+            f"saves={signals.saves:.3f} likes={signals.likes_per_reach:.3f}\n"
+        )
+
+    return textwrap.dedent(f"""\
+Day: {day_name} (day_of_week={obs.day_of_week}) | days_elapsed={obs.days_elapsed}
+Energy: {obs.creator_energy:.2f} | Burnout risk: {burnout:.2f} | Followers: {obs.follower_count}
+Engagement rate: {obs.engagement_rate:.3f} | Content queue: {obs.content_queue_size}
+API budget remaining: {budget}
+{signals_str}{coach_str}{judge_str}Tool results from last step:
+{tool_results_str if tool_results_str else '  (none)\n'}Your notes from last step: {notes_echo}
+Plan your tool calls and actions for today:""")
+
+
+def parse_daily_plan(response_text: str) -> ViraltestAction:
+    text = response_text.strip()
+    if text.startswith("```"):
+        lines = text.split("\n")
+        lines = [l for l in lines if not l.strip().startswith("```")]
+        text = "\n".join(lines).strip()
+
+    try:
+        data: Dict[str, Any] = json.loads(text)
+
+        tool_calls = []
+        for tc in data.get("tool_calls", []):
+            if isinstance(tc, dict) and "name" in tc:
+                tool_calls.append(ToolCall(name=tc["name"], arguments=tc.get("arguments", {})))
+
+        actions_raw = data.get("scheduled_actions", [])
+        scheduled = []
+        if isinstance(actions_raw, list):
+            for a in actions_raw:
+                if isinstance(a, dict):
+                    scheduled.append(a)
+
+        replies_raw = data.get("replies", [])
+        notes = data.get("notes")
+
+        return ViraltestAction(
+            tool_calls=tool_calls,
+            scheduled_actions=scheduled,
+            replies=replies_raw if isinstance(replies_raw, list) else [],
+            notes=notes,
+        )
+    except (json.JSONDecodeError, Exception):
+        return ViraltestAction(scheduled_actions=[])
+
+
+def _resolve_predefined_topic(raw: Optional[str], obs: Any, hour: int) -> str:
+    if raw and raw.strip():
+        key = raw.strip().lower()
+        if key in _TOPIC_CANONICAL:
+            return _TOPIC_CANONICAL[key]
+    for tt in getattr(obs, "trending_topics", []) or []:
+        tl = (tt or "").strip().lower()
+        if tl in _TOPIC_CANONICAL:
+            return _TOPIC_CANONICAL[tl]
+    return ALL_TOPICS[hour % len(ALL_TOPICS)]
+
+
+def sanitize_predefined_topics(action: ViraltestAction, obs: Any) -> ViraltestAction:
+    out = []
+    for sa in action.scheduled_actions:
+        if sa.action_type == "post":
+            out.append(sa.model_copy(update={"topic": _resolve_predefined_topic(sa.topic, obs, sa.hour)}))
+        else:
+            out.append(sa)
+    return ViraltestAction(
+        tool_calls=action.tool_calls,
+        scheduled_actions=out,
+        replies=action.replies,
+        collab=action.collab,
+        notes=action.notes,
+    )
+
+
+def format_action_str(action: ViraltestAction) -> str:
+    parts = []
+    if action.tool_calls:
+        tools_str = ",".join(tc.name for tc in action.tool_calls)
+        parts.append(f"tools({tools_str})")
+    if not action.scheduled_actions:
+        parts.append("rest_all")
+    else:
+        for sa in action.scheduled_actions:
+            if sa.action_type == "post":
+                tags_str = ",".join(sa.tags) if sa.tags else ""
+                parts.append(f"h{sa.hour}:post({sa.content_type},\"{sa.topic}\",[{tags_str}],{sa.intent or 'none'})")
+            else:
+                parts.append(f"h{sa.hour}:{sa.action_type}()")
+    return "daily_plan(" + ";".join(parts) + ")"
+
+
+_model_exhausted = False
+
+
+def get_model_daily_plan(
+    client: OpenAI, obs: Any, history: List[Dict[str, str]]
+) -> ViraltestAction:
+    global _model_exhausted
+    if _model_exhausted:
+        return ViraltestAction(scheduled_actions=[])
+
+    user_prompt = format_observation(obs)
+    messages = [{"role": "system", "content": SYSTEM_PROMPT}]
+    messages.extend(history[-7:])
+    messages.append({"role": "user", "content": user_prompt})
+
+    try:
+        completion = client.chat.completions.create(
+            model=MODEL_NAME,
+            messages=messages,
+            temperature=TEMPERATURE,
+            max_tokens=MAX_TOKENS,
+            stream=False,
+        )
+        text = (completion.choices[0].message.content or "").strip()
+        plan = parse_daily_plan(text) if text else ViraltestAction(scheduled_actions=[])
+        return sanitize_predefined_topics(plan, obs)
+    except Exception as exc:
+        err_str = str(exc)
+        print(f"[DEBUG] Model request failed: {exc}", flush=True)
+        if "402" in err_str or "429" in err_str or "credit" in err_str.lower() or "quota" in err_str.lower():
+            _model_exhausted = True
+            print("[DEBUG] Token/credit limit reached — resting remaining steps", flush=True)
+        return ViraltestAction(scheduled_actions=[])
+
+
+async def run_task(client: OpenAI, task: str) -> None:
+    global _model_exhausted
+    _model_exhausted = False
+
+    rewards: List[float] = []
+    steps_taken = 0
+    score = 0.0
+    success = False
+    env: Optional[ViraltestEnv] = None
+    headline: Optional[Any] = None
+
+    log_start(task=task, env=BENCHMARK, model=MODEL_NAME)
+
+    try:
+        if DOCKER_IMAGE:
+            env = await ViraltestEnv.from_docker_image(DOCKER_IMAGE)
+        else:
+            env = ViraltestEnv(base_url=os.getenv("ENV_BASE_URL", "http://localhost:8000"))
+
+        result = await env.reset(task=task)
+        history: List[Dict[str, str]] = []
+
+        for step in range(1, MAX_STEPS + 1):
+            if result.done:
+                break
+
+            obs = result.observation
+            if should_force_rest_day(obs):
+                action = ViraltestAction(scheduled_actions=[], notes="Low energy — forced rest day.")
+            else:
+                action = get_model_daily_plan(client, obs, history)
+
+            result = await env.step(action)
+
+            reward = result.reward or 0.0
+            done = result.done
+            error = getattr(result.observation, "error", None)
+
+            rewards.append(reward)
+            steps_taken = step
+
+            log_step(step=step, action=format_action_str(action), reward=reward, done=done, error=error)
+
+            history.append({
+                "role": "assistant",
+                "content": json.dumps({
+                    "tool_calls": [{"name": tc.name, "arguments": tc.arguments} for tc in action.tool_calls],
+                    "scheduled_actions": [
+                        {
+                            "hour": sa.hour, "action_type": sa.action_type,
+                            "content_type": sa.content_type, "topic": sa.topic,
+                            "tags": sa.tags, "intent": sa.intent,
+                        }
+                        for sa in action.scheduled_actions
+                    ],
+                    "notes": action.notes,
+                }),
+            })
+
+            if done:
+                score = float(getattr(result.observation, "grader_score", 0) or 0)
+                if score == 0:
+                    meta = getattr(result.observation, "metadata", {}) or {}
+                    score = float(meta.get("grader_score", 0.0))
+                headline = getattr(result.observation, "headline_metrics", None)
+                break
+
+        success = score >= SUCCESS_SCORE_THRESHOLD
+
+    finally:
+        if env is not None:
+            try:
+                await env.close()
+            except Exception as e:
+                print(f"[DEBUG] env.close() error: {e}", flush=True)
+        log_end(success=success, steps=steps_taken, score=score, rewards=rewards, headline=headline)
+
+
+async def main() -> None:
+    client = OpenAI(base_url=API_BASE_URL, api_key=API_KEY or "not-needed")
+    for task in TASKS:
+        await run_task(client, task)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

models.py

@@ -0,0 +1,207 @@
+"""Data models for the Viraltest Creator Optimization Environment (v2 — Theme #3.1)."""
+
+from typing import Any, Dict, List, Literal, Optional
+
+from openenv.core.env_server.types import Action, Observation
+from pydantic import BaseModel, Field, field_validator
+
+VALID_CONTENT_TYPES = ("reel", "story", "carousel", "text_post")
+VALID_ACTION_TYPES = ("post", "create_content")
+VALID_INTENTS = ("send_bait", "save_bait", "watch_bait", "like_bait")
+
+
+class ToolCall(BaseModel):
+    """A single tool invocation the agent wants to make before committing actions."""
+
+    name: str = Field(..., description="Tool name from the /tools catalog")
+    arguments: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResult(BaseModel):
+    """Result returned from a single tool invocation."""
+
+    name: str
+    success: bool = True
+    data: Any = None
+    error: Optional[str] = None
+    budget_remaining: int = Field(default=100, ge=0)
+
+
+class ScheduledAction(BaseModel):
+    """A single non-rest action scheduled at a specific hour of the day."""
+
+    hour: int = Field(..., ge=0, le=23, description="Hour of the day (0-23)")
+    action_type: Literal["post", "create_content"] = Field(
+        ..., description="What to do at this hour (unlisted hours default to rest)"
+    )
+    content_type: Optional[Literal["reel", "story", "carousel", "text_post"]] = Field(
+        default=None, description="Format of the post (required if posting)"
+    )
+    topic: Optional[str] = Field(
+        default=None, max_length=200, description="Topic of the post"
+    )
+    tags: Optional[List[str]] = Field(
+        default=None, description="Hashtags for the post (max 5)"
+    )
+    intent: Optional[Literal["send_bait", "save_bait", "watch_bait", "like_bait"]] = Field(
+        default=None,
+        description="Mosseri signal the post optimizes for (affects which engagement signal gets boosted)",
+    )
+
+    @field_validator("tags")
+    @classmethod
+    def validate_tags(cls, v: Optional[List[str]]) -> Optional[List[str]]:
+        if v is not None and len(v) > 5:
+            return v[:5]
+        return v
+
+
+class ReplyAction(BaseModel):
+    """Reply to comments on a post made earlier today (within reply window)."""
+
+    post_hour: int = Field(..., ge=0, le=23, description="Hour of the post to reply on")
+    reply_hour: int = Field(..., ge=0, le=23, description="Hour to send replies")
+
+
+class CollabProposal(BaseModel):
+    """Propose a collaboration with a competitor archetype."""
+
+    partner_id: str = Field(..., description="Competitor archetype id from competitors.json")
+    content_type: Optional[Literal["reel", "story", "carousel", "text_post"]] = Field(default="reel")
+    hour: int = Field(default=12, ge=0, le=23)
+
+
+class ViraltestAction(Action):
+    """Daily plan: tool calls for discovery, then scheduled actions to commit."""
+
+    tool_calls: List[ToolCall] = Field(
+        default_factory=list,
+        description="Tool invocations to run before committing actions (query_audience, query_trends, etc.)",
+    )
+    scheduled_actions: List[ScheduledAction] = Field(
+        default_factory=list,
+        description="Actions scheduled at specific hours; unlisted hours are rest",
+    )
+    replies: List[ReplyAction] = Field(
+        default_factory=list,
+        description="Reply actions on posts made today (within 90-min window for reach bonus)",
+    )
+    collab: Optional[CollabProposal] = Field(
+        default=None,
+        description="Optional collaboration proposal (max 2 per month)",
+    )
+    notes: Optional[str] = Field(
+        default=None,
+        max_length=2000,
+        description="Agent scratchpad — persisted and echoed back next step for belief tracking",
+    )
+
+    @field_validator("scheduled_actions")
+    @classmethod
+    def validate_no_duplicate_hours(cls, v: List[ScheduledAction]) -> List[ScheduledAction]:
+        seen: set = set()
+        deduped: List[ScheduledAction] = []
+        for a in v:
+            if a.hour not in seen:
+                seen.add(a.hour)
+                deduped.append(a)
+        return deduped
+
+
+class JudgeReport(BaseModel):
+    """Auditable per-day evaluation by the in-env Regulator/Judge.
+
+    Scores are 0..1. `sustainability_risk` is RISK (higher = worse).
+    """
+
+    policy_compliance: float = Field(default=1.0, ge=0.0, le=1.0)
+    sustainability_risk: float = Field(default=0.0, ge=0.0, le=1.0)
+    strategic_quality: float = Field(default=0.0, ge=0.0, le=1.0)
+    explanation: str = Field(default="")
+    violations: List[str] = Field(default_factory=list)
+
+
+class HeadlineMetrics(BaseModel):
+    """Three headline numbers reported once per episode (final observation)."""
+
+    vs_baseline_pct: float = Field(default=0.0, description="(agent - heuristic_baseline) / heuristic_baseline")
+    score_per_tool_call: float = Field(default=0.0, description="grader_score / total_tool_calls (efficiency)")
+    score_per_1k_chars: float = Field(default=0.0, description="grader_score per 1k action chars (token-proxy efficiency)")
+    retention_under_shift: Optional[float] = Field(
+        default=None,
+        description="shifted_score / baseline_score, populated when both runs share an episode_chain_id",
+    )
+    heuristic_baseline_score: float = Field(default=0.0)
+    agent_score: float = Field(default=0.0)
+    total_tool_calls: int = Field(default=0, ge=0)
+    total_action_chars: int = Field(default=0, ge=0)
+
+
+class EngagementSignals(BaseModel):
+    """Mosseri-aligned engagement decomposition (Jan 2025 official ranking signals)."""
+
+    watch_time: float = Field(default=0.0, ge=0.0, description="Reels watch time signal")
+    sends_per_reach: float = Field(default=0.0, ge=0.0, description="DM shares signal (strongest for discovery)")
+    saves: float = Field(default=0.0, ge=0.0, description="Bookmark signal (content quality)")
+    likes_per_reach: float = Field(default=0.0, ge=0.0, description="Like signal (existing followers)")
+
+    @property
+    def weighted_total(self) -> float:
+        return 0.4 * self.watch_time + 0.3 * self.sends_per_reach + 0.2 * self.saves + 0.1 * self.likes_per_reach
+
+
+class ViraltestObservation(Observation):
+    """Observation the agent receives after each daily step.
+
+    Default observation is SPARSE (Theme #3.1 partial observability).
+    Rich data (tag_performance, competitor_posts, trending) available only via tools.
+    """
+
+    current_hour: int = Field(default=0, ge=0, le=23)
+    day_of_week: int = Field(default=0, ge=0, le=6)
+    days_elapsed: int = Field(default=0, ge=0)
+    creator_energy: float = Field(default=1.0, ge=0.0, le=1.0)
+    hours_since_sleep: int = Field(default=0, ge=0)
+    sleep_debt: float = Field(default=0.0, ge=0.0, le=1.0)
+    follower_count: int = Field(default=0, ge=0)
+    engagement_rate: float = Field(default=0.0, ge=0.0)
+    posts_today: int = Field(default=0, ge=0)
+    time_since_last_post: int = Field(default=0, ge=0)
+    content_queue_size: int = Field(default=0, ge=0)
+    last_post_type: str = Field(default="none")
+    burnout_risk: float = Field(default=0.0, ge=0.0, le=1.0, description="0=safe, 1=imminent burnout")
+
+    # Sparse: these are populated only when agent uses tools
+    trending_topics: List[str] = Field(default_factory=list)
+    trending_tags: List[str] = Field(default_factory=list)
+    tag_performance: Dict[str, float] = Field(default_factory=dict)
+    competitor_recent_posts: List[Dict[str, Any]] = Field(default_factory=list)
+    competitor_avg_engagement: float = Field(default=0.0, ge=0.0)
+    niche_saturation: float = Field(default=0.0, ge=0.0, le=1.0)
+
+    daily_total_engagement: float = Field(default=0.0, ge=0.0)
+    daily_posts_made: int = Field(default=0, ge=0)
+    daily_energy_min: float = Field(default=1.0, ge=0.0, le=1.0)
+
+    engagement_signals: Optional[EngagementSignals] = Field(
+        default=None, description="Mosseri-aligned signal breakdown for the day"
+    )
+    coach_feedback: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Counterfactual feedback: delta between agent plan and heatmap-optimal plan",
+    )
+    judge_report: Optional[JudgeReport] = Field(
+        default=None,
+        description="Regulator/Judge audit: policy compliance, sustainability risk, strategic quality + explanation",
+    )
+    headline_metrics: Optional[HeadlineMetrics] = Field(
+        default=None,
+        description="Final-observation hard numbers: improvement vs baseline, efficiency, shift retention",
+    )
+
+    tool_results: List[ToolResult] = Field(default_factory=list, description="Results from tool_calls this step")
+    agent_notes: Optional[str] = Field(default=None, description="Echo of agent's notes from previous step")
+    api_budget_remaining: int = Field(default=100, ge=0)
+
+    grader_score: Optional[float] = Field(default=None)
+    error: Optional[str] = Field(default=None)

openenv.yaml

@@ -0,0 +1,7 @@
+spec_version: 1
+name: viraltest
+type: space
+runtime: fastapi
+app: server.app:app
+port: 8000
+

pyproject.toml

@@ -0,0 +1,51 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openenv-viraltest"
+version = "0.1.0"
+description = "Viraltest environment for OpenEnv"
+requires-python = ">=3.10"
+dependencies = [
+    # Core OpenEnv runtime (provides FastAPI server + HTTP client types)
+    # install from github
+    # "openenv-core[core] @ git+https://github.com/meta-pytorch/OpenEnv.git",
+    "openenv-core[core]>=0.2.2",
+    "openai>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+]
+# Colab / CUDA: 4-bit QLoRA. On Mac without CUDA, notebook falls back to fp16 (MPS) / fp32 (CPU).
+training = [
+    "bitsandbytes>=0.46.1",
+    "transformers>=4.45.0",
+    "accelerate>=1.0.0",
+    "peft>=0.10.0",
+    "trl>=0.8.0",
+    "datasets>=2.0.0",
+    "torch",
+]
+
+[project.scripts]
+# Server entry point - enables running via: uv run --project . server
+# or: python -m viraltest.server.app
+server = "viraltest.server.app:main"
+
+[tool.setuptools]
+include-package-data = true
+packages = ["viraltest", "viraltest.server"]
+package-dir = { "viraltest" = ".", "viraltest.server" = "server" }
+
+[tool.setuptools.package-data]
+"viraltest.server" = ["*.html", "data/*.json"]

server/__init__.py

@@ -0,0 +1,11 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+"""Viraltest environment server components."""
+
+from .viraltest_environment import ViraltestEnvironment
+
+__all__ = ["ViraltestEnvironment"]

server/app.py

@@ -0,0 +1,413 @@
+"""
+FastAPI application for the Viraltest Environment v2 (Theme #3.1).
+
+Endpoints:
+    - POST /reset, /step, GET /state, /schema — standard OpenEnv
+    - GET /tools — tool catalog (Theme #3.1 discovery)
+    - GET /tools/{name} — single tool schema
+    - GET /dashboard — simulation UI
+"""
+
+import json
+import os
+import random as stdlib_random
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import Body
+from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
+
+try:
+    from openenv.core.env_server.http_server import create_app
+except Exception as e:
+    raise ImportError(
+        "openenv is required. Install with 'uv sync'"
+    ) from e
+
+if "ENABLE_WEB_INTERFACE" not in os.environ:
+    os.environ["ENABLE_WEB_INTERFACE"] = "true"
+
+try:
+    from ..models import ScheduledAction, ViraltestAction, ViraltestObservation
+    from .viraltest_environment import TOOL_CATALOG, ViraltestEnvironment
+except ImportError:
+    from models import ScheduledAction, ViraltestAction, ViraltestObservation
+    from server.viraltest_environment import TOOL_CATALOG, ViraltestEnvironment
+
+try:
+    from .viraltest_environment import TAG_POOL
+except ImportError:
+    from server.viraltest_environment import TAG_POOL
+
+_DASHBOARD_HTML = (Path(__file__).parent / "dashboard.html").read_text()
+_TRAINING_HTML_PATH = Path(__file__).parent / "training.html"
+_TRAINING_HTML = _TRAINING_HTML_PATH.read_text() if _TRAINING_HTML_PATH.exists() else "<html><body>Training page not found</body></html>"
+
+app = create_app(
+    ViraltestEnvironment,
+    ViraltestAction,
+    ViraltestObservation,
+    env_name="viraltest",
+    max_concurrent_envs=1,
+)
+
+_gradio_web = os.getenv("ENABLE_WEB_INTERFACE", "false").lower() in ("true", "1", "yes")
+if not _gradio_web:
+
+    @app.get("/", include_in_schema=False)
+    async def _root_redirect():
+        return RedirectResponse("/dashboard", status_code=302)
+
+    @app.get("/web", include_in_schema=False)
+    @app.get("/web/", include_in_schema=False)
+    async def _web_disabled_redirect():
+        return RedirectResponse("/dashboard", status_code=302)
+
+# ---------------------------------------------------------------------------
+# Tool catalog endpoints (Theme #3.1 — tool discovery)
+# ---------------------------------------------------------------------------
+
+@app.get("/tools")
+async def list_tools():
+    """Return the full tool catalog so the agent can discover available tools."""
+    return JSONResponse(content={
+        "tools": {name: schema for name, schema in TOOL_CATALOG.items()},
+        "count": len(TOOL_CATALOG),
+    })
+
+
+@app.get("/tools/{name}")
+async def get_tool(name: str):
+    """Return schema for a single tool."""
+    if name not in TOOL_CATALOG:
+        return JSONResponse(content={"error": f"unknown tool: {name}"}, status_code=404)
+    return JSONResponse(content={"name": name, **TOOL_CATALOG[name]})
+
+
+# ---------------------------------------------------------------------------
+# Dashboard
+# ---------------------------------------------------------------------------
+
+_dash_env: Optional[ViraltestEnvironment] = None
+_HISTORY_FILE = Path(__file__).parent / "simulation_history.json"
+
+
+def _obs_to_dict(obs: ViraltestObservation) -> Dict[str, Any]:
+    return {
+        "observation": obs.model_dump(),
+        "reward": obs.reward,
+        "done": obs.done,
+    }
+
+
+def _load_history() -> List[Dict[str, Any]]:
+    if _HISTORY_FILE.exists():
+        try:
+            return json.loads(_HISTORY_FILE.read_text())
+        except (json.JSONDecodeError, OSError):
+            return []
+    return []
+
+
+def _save_history_entry(entry: Dict[str, Any]) -> None:
+    history = _load_history()
+    history.append(entry)
+    if len(history) > 100:
+        history = history[-100:]
+    _HISTORY_FILE.write_text(json.dumps(history, indent=2))
+
+
+@app.get("/dashboard", response_class=HTMLResponse)
+async def dashboard():
+    return _DASHBOARD_HTML
+
+
+@app.get("/dashboard/history")
+async def dashboard_history():
+    history = _load_history()
+    out: List[Dict[str, Any]] = []
+    for row in history:
+        entry = dict(row)
+        if not entry.get("description"):
+            sid = entry.get("scenario_id")
+            if sid and sid in SCENARIOS:
+                entry["description"] = SCENARIOS[sid][1]
+        out.append(entry)
+    return out
+
+
+@app.delete("/dashboard/history")
+async def dashboard_history_clear():
+    if _HISTORY_FILE.exists():
+        _HISTORY_FILE.unlink()
+    return {"status": "cleared"}
+
+
+@app.post("/dashboard/reset")
+async def dashboard_reset(body: Dict[str, Any] = Body(default={})):
+    global _dash_env
+    _dash_env = ViraltestEnvironment()
+    task = body.get("task", "monthly_engage")
+    obs = _dash_env.reset(task=task)
+    return _obs_to_dict(obs)
+
+
+@app.post("/dashboard/step")
+async def dashboard_step(body: Dict[str, Any] = Body(...)):
+    global _dash_env
+    if _dash_env is None:
+        _dash_env = ViraltestEnvironment()
+        _dash_env.reset()
+    action_data = body.get("action", body)
+    action = ViraltestAction(**action_data)
+    obs = _dash_env.step(action)
+    return _obs_to_dict(obs)
+
+
+# ---------------------------------------------------------------------------
+# Dashboard scenario helpers (v2 action shape)
+# ---------------------------------------------------------------------------
+
+_SIM_RNG = stdlib_random.Random(99)
+_CONTENT_TYPES = ["reel", "carousel", "story", "text_post"]
+_TOPICS = ["AI tools", "fitness routine", "growth hacks", "travel guide", "food recipe", "wellness tips"]
+
+
+def _make_daily_plan(actions: list, notes: Optional[str] = None) -> ViraltestAction:
+    return ViraltestAction(
+        scheduled_actions=[ScheduledAction(**a) for a in actions],
+        notes=notes,
+    )
+
+
+def _plan_always_rest(obs: dict, day: int) -> ViraltestAction:
+    return _make_daily_plan([], notes="Resting all day to conserve energy.")
+
+
+def _plan_spam(obs: dict, day: int) -> ViraltestAction:
+    actions = [
+        {"hour": h, "action_type": "post", "content_type": "reel",
+         "topic": "AI tools", "tags": ["ai"], "intent": "watch_bait"}
+        for h in range(24)
+    ]
+    return _make_daily_plan(actions)
+
+
+def _plan_smart(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["AI tools"])[0]
+    t_tags = list((obs.get("trending_tags") or [])[:2])
+    pool_tag = TAG_POOL[(day * 2) % len(TAG_POOL)]
+    pool_tag2 = TAG_POOL[(day * 2 + 1) % len(TAG_POOL)]
+    ct1 = _CONTENT_TYPES[(day * 2) % 4]
+    ct2 = _CONTENT_TYPES[(day * 2 + 1) % 4]
+    intent1 = "save_bait" if ct1 == "carousel" else "watch_bait"
+    intent2 = "send_bait" if ct2 == "reel" else "save_bait"
+    actions = [
+        {"hour": 8, "action_type": "create_content"},
+        {"hour": 12, "action_type": "post", "content_type": ct1, "topic": trending,
+         "tags": t_tags + [pool_tag], "intent": intent1},
+        {"hour": 19, "action_type": "post", "content_type": ct2, "topic": trending,
+         "tags": t_tags + [pool_tag2], "intent": intent2},
+    ]
+    return _make_daily_plan(actions, notes=f"Day {day}: posting at peak hours with varied intents.")
+
+
+def _plan_random(obs: dict, day: int) -> ViraltestAction:
+    actions = []
+    for h in range(24):
+        r = _SIM_RNG.random()
+        if r < 0.1:
+            ct = _SIM_RNG.choice(_CONTENT_TYPES)
+            topic = _SIM_RNG.choice(_TOPICS)
+            tags = _SIM_RNG.sample(TAG_POOL[:20], 2)
+            actions.append({"hour": h, "action_type": "post", "content_type": ct, "topic": topic, "tags": tags})
+        elif r < 0.15:
+            actions.append({"hour": h, "action_type": "create_content"})
+    return _make_daily_plan(actions)
+
+
+def _plan_minimal(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["minimalism"])[0]
+    tags = list((obs.get("trending_tags") or [])[:3])
+    return _make_daily_plan([
+        {"hour": 12, "action_type": "post", "content_type": "carousel",
+         "topic": trending, "tags": tags, "intent": "save_bait"},
+    ])
+
+
+SCENARIOS = {
+    "always_rest": ("Always Rest", "Never posts. Tests follower decay.", _plan_always_rest),
+    "spam": ("Spam Post", "Same reel every hour. Burns out fast.", _plan_spam),
+    "smart": ("Smart Agent", "Optimal: peak hours, trending, varied types+intents.", _plan_smart),
+    "minimal": ("Minimal Poster", "1 carousel per day at noon.", _plan_minimal),
+    "random": ("Random Actor", "Random actions. Baseline test.", _plan_random),
+}
+
+
+@app.get("/dashboard/scenarios")
+async def dashboard_scenarios():
+    items = [{"id": k, "label": v[0], "description": v[1]} for k, v in SCENARIOS.items()]
+    items.sort(key=lambda x: x["label"].lower())
+    return JSONResponse(
+        content={"count": len(items), "scenarios": items},
+        headers={"Cache-Control": "no-store, max-age=0, must-revalidate"},
+    )
+
+
+@app.post("/dashboard/simulate")
+async def dashboard_simulate(body: Dict[str, Any] = Body(...)):
+    global _SIM_RNG
+    _SIM_RNG = stdlib_random.Random(99)
+
+    scenario_id = body.get("scenario", "smart")
+    task = body.get("task", "monthly_competitive")
+    if scenario_id not in SCENARIOS:
+        return {"error": f"Unknown scenario: {scenario_id}"}
+
+    label, desc, plan_fn = SCENARIOS[scenario_id]
+    env = ViraltestEnvironment()
+    obs = env.reset(task=task, seed=42)
+    obs_dict = obs.model_dump()
+
+    steps: List[Dict[str, Any]] = []
+    for day in range(1, 31):
+        action = plan_fn(obs_dict, day)
+        obs = env.step(action)
+        obs_dict = obs.model_dump()
+        r = obs.reward if obs.reward is not None else 0.0
+
+        n_posts = len([sa for sa in action.scheduled_actions if sa.action_type == "post"])
+        n_create = len([sa for sa in action.scheduled_actions if sa.action_type == "create_content"])
+        action_str = f"day{day}(posts={n_posts},creates={n_create})"
+
+        steps.append({
+            "step": day,
+            "action": action_str,
+            "reward": round(r, 4),
+            "done": obs.done,
+            "error": obs.error,
+            "energy": round(obs.creator_energy, 3),
+            "hours_since_sleep": obs.hours_since_sleep,
+            "sleep_debt": round(obs.sleep_debt, 3),
+            "followers": obs.follower_count,
+            "engagement_rate": round(obs.engagement_rate, 4),
+            "burnout_risk": round(obs.burnout_risk, 3),
+            "posts_today": obs.posts_today,
+            "hour": obs.current_hour,
+            "day": obs.day_of_week,
+            "days_elapsed": obs.days_elapsed,
+            "queue": obs.content_queue_size,
+            "api_budget": obs.api_budget_remaining,
+        })
+        if obs.done:
+            break
+
+    score = (obs.metadata or {}).get("grader_score", 0.0)
+    result = {
+        "scenario": label,
+        "description": desc,
+        "task": task,
+        "steps": steps,
+        "total_steps": len(steps),
+        "score": round(score, 4),
+        "final": {
+            "energy": round(obs.creator_energy, 3),
+            "hours_since_sleep": obs.hours_since_sleep,
+            "sleep_debt": round(obs.sleep_debt, 3),
+            "followers": obs.follower_count,
+            "engagement_rate": round(obs.engagement_rate, 4),
+            "burned_out": obs.creator_energy <= 0,
+        },
+    }
+
+    rewards = [s["reward"] for s in steps]
+    total_posts = sum(s.get("daily_posts_made", 0) for s in steps)
+    _save_history_entry({
+        "id": datetime.now(timezone.utc).isoformat(),
+        "scenario": label,
+        "scenario_id": scenario_id,
+        "description": desc,
+        "task": task,
+        "score": round(score, 4),
+        "total_steps": len(steps),
+        "total_posts": total_posts,
+        "avg_reward": round(sum(rewards) / len(rewards), 4) if rewards else 0,
+        "final": result["final"],
+    })
+
+    return result
+
+
+_TRAINING_TASKS = ["monthly_engage", "monthly_strategic", "monthly_competitive"]
+
+@app.get("/dashboard/training-evidence")
+async def training_evidence():
+    """Run all baseline scenarios across all tasks and return structured comparison data."""
+    global _SIM_RNG
+
+    results = []
+    for scenario_id, (label, desc, plan_fn) in SCENARIOS.items():
+        for task in _TRAINING_TASKS:
+            _SIM_RNG = stdlib_random.Random(99)
+            env = ViraltestEnvironment()
+            obs = env.reset(task=task, seed=42)
+            obs_dict = obs.model_dump()
+
+            rewards: List[float] = []
+            energies: List[float] = [obs.creator_energy]
+
+            for day in range(1, 31):
+                action = plan_fn(obs_dict, day)
+                obs = env.step(action)
+                obs_dict = obs.model_dump()
+                r = obs.reward if obs.reward is not None else 0.0
+                rewards.append(r)
+                energies.append(obs.creator_energy)
+                if obs.done:
+                    break
+
+            score = (obs.metadata or {}).get("grader_score", 0.0)
+            results.append({
+                "scenario_id": scenario_id,
+                "scenario": label,
+                "description": desc,
+                "task": task,
+                "grader_score": round(score, 4),
+                "total_reward": round(sum(rewards), 4),
+                "avg_reward": round(sum(rewards) / len(rewards), 4) if rewards else 0,
+                "steps": len(rewards),
+                "final_energy": round(obs.creator_energy, 3),
+                "min_energy": round(min(energies), 3),
+                "final_followers": obs.follower_count,
+                "follower_delta": obs.follower_count - 10000,
+                "burned_out": obs.creator_energy <= 0,
+                "rewards": [round(r, 4) for r in rewards],
+                "energies": [round(e, 3) for e in energies],
+            })
+
+    return JSONResponse(
+        content={"results": results, "tasks": _TRAINING_TASKS, "scenarios": list(SCENARIOS.keys())},
+        headers={"Cache-Control": "no-store, max-age=0, must-revalidate"},
+    )
+
+
+@app.get("/dashboard/training", response_class=HTMLResponse)
+async def training_dashboard():
+    return _TRAINING_HTML
+
+
+def main(host: str = "0.0.0.0", port: int = 8000):
+    import uvicorn
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=None)
+    args = parser.parse_args()
+    if args.port is not None:
+        main(port=args.port)
+    else:
+        main()

server/dashboard.html

@@ -0,0 +1,1306 @@
+<!DOCTYPE html>
+<html class="dark" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta content="width=device-width,initial-scale=1.0" name="viewport"/>
+<title>Growth Copilot — Simulation</title>
+<script src="https://cdn.tailwindcss.com?plugins=forms,container-queries"></script>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800;900&family=Space+Grotesk:wght@400;500;700&display=swap" rel="stylesheet"/>
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet"/>
+<script>
+tailwind.config={darkMode:"class",theme:{extend:{colors:{"surface":"#0b1326","surface-low":"#131b2e","surface-high":"#222a3d","surface-top":"#2d3449","surface-lowest":"#060e20","on-surface":"#dae2fd","on-surface-dim":"#cbc3d7","primary":"#d0bcff","primary-ctr":"#a078ff","secondary":"#7bd0ff","secondary-ctr":"#00a6e0","tertiary":"#ffb2b9","tertiary-ctr":"#ea6479","outline":"#494454","error":"#ffb4ab"},fontFamily:{headline:["Inter"],body:["Inter"],label:["Space Grotesk"]}}}}
+</script>
+<style>
+body{background:#0b1326;color:#dae2fd;font-family:'Inter',sans-serif}
+.material-symbols-outlined{font-variation-settings:'FILL' 0,'wght' 400,'GRAD' 0,'opsz' 24}
+.glass{background:rgba(34,42,61,.6);backdrop-filter:blur(24px);border:1px solid rgba(73,68,84,.2)}
+.glass-solid{background:#131b2e;border:1px solid rgba(73,68,84,.15)}
+.energy-bar{transition:width .6s ease}
+.fade-in{animation:fadeIn .3s ease}
+@keyframes fadeIn{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}
+@keyframes pulse-glow{0%,100%{box-shadow:0 0 8px rgba(208,188,255,.2)}50%{box-shadow:0 0 20px rgba(208,188,255,.4)}}
+.pulse-glow{animation:pulse-glow 2s ease-in-out infinite}
+::-webkit-scrollbar{width:6px}
+::-webkit-scrollbar-track{background:transparent}
+::-webkit-scrollbar-thumb{background:rgba(73,68,84,.4);border-radius:3px}
+.sim-btn{transition:all .2s ease}
+.sim-btn:hover{transform:translateY(-1px)}
+.action-btn{transition:all .15s ease}
+.action-btn:active{transform:scale(.97)}
+</style>
+</head>
+<body class="min-h-screen flex">
+
+<!-- Sidebar -->
+<aside class="flex flex-col sticky top-0 h-screen w-64 border-r border-white/5 bg-surface-lowest shadow-2xl shadow-slate-950/50 shrink-0 z-50">
+  <div class="p-6 pb-4">
+    <div class="text-xl font-black tracking-tighter text-transparent bg-clip-text bg-gradient-to-br from-primary to-primary-ctr mb-1">Growth Copilot</div>
+    <div class="text-[9px] font-label uppercase tracking-[.2em] text-on-surface-dim/50">30-day creator simulation</div>
+  </div>
+  <nav class="flex-1 px-3 space-y-1">
+    <a href="/dashboard" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-primary font-bold border-r-2 border-primary bg-gradient-to-r from-primary/10 to-transparent transition-all">
+      <span class="material-symbols-outlined text-[20px]">dashboard</span><span class="font-label text-sm">Dashboard</span>
+    </a>
+    <a href="/dashboard/training" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-slate-400 font-medium hover:text-slate-200 hover:bg-white/5 transition-all">
+      <span class="material-symbols-outlined text-[20px]">science</span><span class="font-label text-sm">Training Evidence</span>
+    </a>
+    <a href="/web/" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-slate-400 font-medium hover:text-slate-200 hover:bg-white/5 transition-all">
+      <span class="material-symbols-outlined text-[20px]">web</span><span class="font-label text-sm">OpenEnv UI</span>
+    </a>
+  </nav>
+  <!-- Task Selector in Sidebar -->
+  <div class="p-4 border-t border-white/5 space-y-3">
+    <div class="text-[9px] font-label uppercase tracking-widest text-on-surface-dim/60 mb-1">Task</div>
+    <select id="taskSelect" onchange="refreshTaskScoreBlurb()" class="w-full bg-surface border border-outline/30 rounded-lg px-3 py-2 text-sm font-label focus:ring-1 focus:ring-primary focus:outline-none">
+      <option value="monthly_engage">Easy — Engage</option>
+      <option value="monthly_strategic">Medium — Strategic</option>
+      <option value="monthly_competitive" selected>Hard — Competitive</option>
+    </select>
+    <button onclick="doReset()" class="w-full py-3 rounded-lg bg-gradient-to-br from-primary to-primary-ctr text-[#23005c] font-bold text-sm hover:opacity-90 transition active:scale-[.97]">
+      <span class="material-symbols-outlined text-[16px] align-middle mr-1">restart_alt</span>Reset
+    </button>
+  </div>
+</aside>
+
+<!-- Main -->
+<div class="flex-1 flex flex-col min-w-0">
+
+  <!-- Top Bar -->
+  <header class="flex justify-between items-center px-6 h-14 border-b border-white/5 bg-surface/60 backdrop-blur-xl sticky top-0 z-40">
+    <div class="flex items-center gap-5">
+      <span id="statusDot" class="flex items-center gap-2 text-xs font-label text-secondary"><span class="w-2 h-2 rounded-full bg-secondary"></span>Ready</span>
+      <span class="text-xs font-label text-on-surface-dim">Day <span id="stepNum" class="text-on-surface font-bold">0</span> / <span id="episodeHorizon">7</span></span>
+    </div>
+    <div class="flex items-center gap-3">
+      <span id="rewardBadge" class="text-xs font-label text-on-surface-dim">Last reward: —</span>
+      <span class="text-xs font-label text-on-surface-dim/40">|</span>
+      <span id="timeBadge" class="text-xs font-label text-on-surface-dim"><span class="material-symbols-outlined text-[14px] align-middle">schedule</span> <span id="timeVal">9:00</span> <span id="dayVal" class="text-on-surface-dim/60">Mon</span></span>
+    </div>
+  </header>
+
+  <main class="flex-1 p-6 space-y-5 overflow-y-auto">
+
+    <!-- Hero Stat Cards -->
+    <div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-6 gap-4">
+
+      <!-- Energy -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">bolt</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Energy</div>
+        <div id="energyVal" class="text-3xl font-black tracking-tight">1.00</div>
+        <div class="mt-3 h-2 bg-surface-top rounded-full overflow-hidden">
+          <div id="energyBar" class="h-full bg-gradient-to-r from-tertiary-ctr to-tertiary energy-bar rounded-full" style="width:100%"></div>
+        </div>
+        <div id="energyHint" class="mt-1.5 text-[9px] font-label text-tertiary">FULL</div>
+      </div>
+
+      <!-- Followers -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">group</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Followers</div>
+        <div id="followersVal" class="text-3xl font-black tracking-tight">10,000</div>
+        <div id="followersDelta" class="mt-1.5 text-[9px] font-label text-on-surface-dim">+0 since start</div>
+      </div>
+
+      <!-- Engagement -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">trending_up</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Engagement</div>
+        <div id="engVal" class="text-3xl font-black tracking-tight text-secondary">0.000</div>
+        <div id="engVsComp" class="mt-1.5 text-[9px] font-label text-on-surface-dim">vs competitors: —</div>
+      </div>
+
+      <!-- Posts Today -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">send</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Posts Today</div>
+        <div id="postsVal" class="text-3xl font-black tracking-tight">0</div>
+        <div class="mt-1.5 text-[9px] font-label text-on-surface-dim">max 2-3 optimal</div>
+      </div>
+
+      <!-- Queue -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">inventory_2</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Content Queue</div>
+        <div id="queueVal" class="text-3xl font-black tracking-tight text-secondary">0</div>
+        <div class="mt-1.5 text-[9px] font-label text-on-surface-dim">posts cost 50% less</div>
+      </div>
+
+      <!-- Saturation -->
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="absolute top-3 right-3 opacity-10"><span class="material-symbols-outlined text-4xl">layers</span></div>
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Niche Saturation</div>
+        <div id="satVal" class="text-3xl font-black tracking-tight text-primary">0.00</div>
+        <div id="satHint" class="mt-1.5 text-[9px] font-label text-primary">LOW — post unique topics</div>
+      </div>
+    </div>
+
+    <div class="glass-solid border border-outline/20 rounded-xl px-4 py-3 space-y-3">
+      <div class="flex gap-3 items-start">
+        <span class="material-symbols-outlined text-secondary text-lg shrink-0">info</span>
+        <p class="text-[11px] font-label text-on-surface-dim leading-relaxed flex-1 min-w-0">
+          <span class="text-on-surface font-semibold">Simulation only</span> — not live social data. Each <span class="text-on-surface">step</span> is one full simulated day (24 hours of hourly actions inside the env). You submit a daily plan; <span class="text-on-surface">Post</span> and <span class="text-on-surface">Create</span> are scheduled at hours you choose; unlisted hours are rest while rivals keep posting.
+        </p>
+      </div>
+      <div class="border-t border-white/5 pt-3 space-y-2">
+        <div class="text-[10px] font-bold text-on-surface uppercase tracking-widest">Niche saturation</div>
+        <p class="text-[10px] font-label text-on-surface-dim leading-relaxed">
+          Shown after each day for your <span class="text-on-surface">last post topic</span>. The sim collects competitor posts from the last <span class="text-on-surface">12 simulated hours</span>, counts how many topics overlap yours (≥50% shared words), and divides by the number of those recent competitor posts. Result is capped at 1.0. High saturation usually means more crowd overlap; the environment can lower engagement when you post into a crowded topic.
+        </p>
+      </div>
+      <div class="border-t border-white/5 pt-3 space-y-2">
+        <div class="text-[10px] font-bold text-on-surface uppercase tracking-widest">Final score &amp; viral meter</div>
+        <p id="taskScoreBlurb" class="text-[10px] font-label text-on-surface-dim leading-relaxed"></p>
+        <p class="text-[10px] font-label text-on-surface-dim leading-relaxed">
+          <span class="text-on-surface font-semibold">Viral probability</span> (dashboard only): <code class="text-on-surface/90">min(100, round(engagement_rate × 1000))</code> with LOW / MEDIUM / HIGH labels at 40% and 70%. It is not the grader and not a forecast of real-world reach.
+        </p>
+      </div>
+    </div>
+
+    <!-- Charts Row -->
+    <div class="grid grid-cols-1 lg:grid-cols-3 gap-4">
+      <!-- Reward history chart -->
+      <div class="lg:col-span-2 glass-solid p-5 rounded-xl overflow-hidden">
+        <div class="flex justify-between items-center mb-2">
+          <div>
+            <h3 class="text-sm font-bold">Reward history</h3>
+            <p class="text-[10px] text-on-surface-dim mt-0.5">Per-day RL reward after each day (axes: day index × reward)</p>
+          </div>
+          <span class="flex items-center gap-1.5 text-[10px] font-label text-on-surface-dim"><span class="w-2 h-2 rounded-full bg-secondary"></span>Reward</span>
+        </div>
+        <div class="h-52 relative">
+          <svg id="engagementChart" class="w-full h-full" viewBox="0 0 760 208" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+      </div>
+
+      <!-- Burnout Meter -->
+      <div class="glass-solid p-5 rounded-xl flex flex-col items-center overflow-hidden">
+        <div class="flex justify-between items-center w-full mb-3">
+          <h3 class="text-sm font-bold">Burnout Meter</h3>
+          <span class="material-symbols-outlined text-tertiary text-lg">monitor_heart</span>
+        </div>
+        <div class="relative w-40 h-40 mb-3">
+          <svg viewBox="0 0 120 120" class="w-full h-full -rotate-90">
+            <circle cx="60" cy="60" r="50" fill="none" stroke="#222a3d" stroke-width="10"/>
+            <circle id="burnoutArc" cx="60" cy="60" r="50" fill="none" stroke="url(#burnoutGrad)" stroke-width="10" stroke-linecap="round" stroke-dasharray="0 314" style="transition:stroke-dasharray .6s ease"/>
+            <defs><linearGradient id="burnoutGrad" x1="0%" y1="0%" x2="100%" y2="0%"><stop offset="0%" style="stop-color:#ffb2b9"/><stop offset="100%" style="stop-color:#ea6479"/></linearGradient></defs>
+          </svg>
+          <div class="absolute inset-0 flex flex-col items-center justify-center">
+            <span id="burnoutPct" class="text-4xl font-black tracking-tight">0%</span>
+            <span class="text-[8px] font-label text-tertiary uppercase tracking-widest mt-0.5">Cortisol Level</span>
+          </div>
+        </div>
+        <div id="burnoutRec" class="p-3 rounded-lg bg-surface border border-outline/15 text-[10px] font-label text-on-surface-dim text-center leading-relaxed w-full">
+          Recommendation: Start with a balanced create-rest cycle.
+        </div>
+      </div>
+    </div>
+
+    <!-- Second Charts Row -->
+    <div class="grid grid-cols-1 lg:grid-cols-3 gap-4">
+      <!-- Follower Growth -->
+      <div class="glass-solid p-5 rounded-xl overflow-hidden">
+        <h3 class="text-sm font-bold mb-3">Follower Growth</h3>
+        <div class="h-32 relative">
+          <svg id="followerChart" class="w-full h-full" viewBox="0 0 300 120" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="flex items-baseline gap-3 mt-2">
+          <span id="followerTotal" class="text-2xl font-black tracking-tight text-secondary">+0</span>
+          <span id="followerDeltaPct" class="text-xs font-label text-secondary/60">+0% vs start</span>
+        </div>
+      </div>
+
+      <!-- Top Performing Tags -->
+      <div class="glass-solid p-5 rounded-xl overflow-hidden">
+        <h3 class="text-sm font-bold mb-3">Top Performing Tags</h3>
+        <div id="topTagsList" class="space-y-3">
+          <div class="text-on-surface-dim italic text-[10px]">No tag data yet</div>
+        </div>
+      </div>
+
+      <!-- Recent RL Actions -->
+      <div class="glass-solid p-5 rounded-xl overflow-hidden">
+        <h3 class="text-sm font-bold mb-3">Recent RL Actions</h3>
+        <div id="recentActions" class="space-y-3 max-h-44 overflow-y-auto">
+          <div class="text-on-surface-dim italic text-[10px]">No actions yet</div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Day & hour analytics -->
+    <div class="space-y-3">
+      <div class="flex items-center gap-2 px-1">
+        <span class="material-symbols-outlined text-secondary text-lg">show_chart</span>
+        <h2 class="text-sm font-bold">Day &amp; hour analytics</h2>
+        <span class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest">X = day index (1–7); line charts = metrics per day; posts histogram = clock hour (0–23) within days</span>
+      </div>
+      <div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-3 gap-3">
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Energy / day</div>
+          <svg id="tsEnergy" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Followers / day</div>
+          <svg id="tsFollowers" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Follower Δ / day</div>
+          <svg id="tsFollowDelta" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Engagement rate / day</div>
+          <svg id="tsEngagement" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Reward / day</div>
+          <svg id="tsReward" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Niche saturation / day</div>
+          <svg id="tsSat" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Content queue / day</div>
+          <svg id="tsQueue" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Competitor avg engagement / day</div>
+          <svg id="tsComp" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Sleep debt / day</div>
+          <svg id="tsSleep" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Hours since sleep / day</div>
+          <svg id="tsAwake" class="w-full h-24" viewBox="0 0 360 112" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div class="glass-solid p-4 rounded-xl overflow-hidden">
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mb-1">Posts by clock hour (0–23)</div>
+          <svg id="tsPostsHour" class="w-full h-20" viewBox="0 0 320 72" preserveAspectRatio="xMidYMid meet"></svg>
+          <div class="text-[10px] font-bold text-on-surface-dim uppercase tracking-widest mt-2 mb-0.5">Action counts (run)</div>
+          <svg id="tsActionMix" class="w-full h-14" viewBox="0 0 320 52" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+      </div>
+    </div>
+
+    <!-- Bottom Stats -->
+    <div class="grid grid-cols-1 md:grid-cols-3 gap-4">
+      <div class="glass-solid p-4 rounded-xl overflow-hidden">
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Avg Reward</div>
+        <div id="bottomAvgReward" class="text-3xl font-black tracking-tight">0.00</div>
+        <div id="bottomAvgDelta" class="text-[10px] font-label text-on-surface-dim mt-1">—</div>
+      </div>
+      <div class="glass-solid p-4 rounded-xl overflow-hidden">
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Total Posts</div>
+        <div id="bottomTotalPosts" class="text-3xl font-black tracking-tight">0</div>
+        <div class="text-[10px] font-label text-on-surface-dim mt-1">across episode</div>
+      </div>
+      <div class="glass-solid relative p-4 rounded-xl overflow-hidden">
+        <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1">Viral Probability</div>
+        <div id="bottomViralProb" class="text-3xl font-black tracking-tight">LOW (0%)</div>
+        <p id="viralFormulaNote" class="text-[9px] font-label text-on-surface-dim/90 leading-snug mt-2">From current engagement rate only (UI heuristic).</p>
+        <div class="absolute bottom-0 right-0 w-2/3 h-10 opacity-30 pointer-events-none">
+          <svg viewBox="0 0 200 30" class="w-full h-full" preserveAspectRatio="none">
+            <defs><linearGradient id="viralGrad" x1="0%" y1="0%" x2="100%" y2="0%"><stop offset="0%" style="stop-color:#d0bcff;stop-opacity:.5"/><stop offset="50%" style="stop-color:#ea6479;stop-opacity:.5"/><stop offset="100%" style="stop-color:#7bd0ff;stop-opacity:.5"/></linearGradient></defs>
+            <path d="M0,25 Q30,5 60,20 Q90,30 120,10 Q150,0 180,15 Q200,25 200,30 L0,30Z" fill="url(#viralGrad)"/>
+          </svg>
+        </div>
+      </div>
+    </div>
+
+    <!-- Main Grid: Actions / History / Intelligence -->
+    <div class="grid grid-cols-1 lg:grid-cols-12 gap-5">
+
+      <!-- Left: Actions + History -->
+      <div class="lg:col-span-8 space-y-5">
+
+        <!-- Action Panel -->
+        <div class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-4 flex items-center gap-2"><span class="material-symbols-outlined text-primary text-lg">gamepad</span>Send Action</h3>
+          <div class="grid grid-cols-3 gap-3 mb-3">
+            <button type="button" title="Submit a full rest day (empty schedule). Advances one simulated day; competitors still simulate." onclick="doAction('rest')" class="action-btn group p-4 rounded-xl bg-gradient-to-br from-tertiary/5 to-tertiary/10 border border-tertiary/15 hover:border-tertiary/40 hover:from-tertiary/10 hover:to-tertiary/20 text-center">
+              <span class="material-symbols-outlined text-tertiary text-3xl group-hover:scale-110 transition-transform">hotel</span>
+              <div class="text-sm font-bold text-tertiary mt-1">Rest</div>
+              <div class="text-[9px] text-on-surface-dim mt-0.5">+0.12 energy recovery</div>
+            </button>
+            <button type="button" title="Schedule create_content at a default hour for this day (daily plan). Queue lowers post energy cost." onclick="doAction('create_content')" class="action-btn group p-4 rounded-xl bg-gradient-to-br from-secondary/5 to-secondary/10 border border-secondary/15 hover:border-secondary/40 hover:from-secondary/10 hover:to-secondary/20 text-center">
+              <span class="material-symbols-outlined text-secondary text-3xl group-hover:scale-110 transition-transform">edit_note</span>
+              <div class="text-sm font-bold text-secondary mt-1">Create</div>
+              <div class="text-[9px] text-on-surface-dim mt-0.5">-0.05 energy, +1 queue</div>
+            </button>
+            <button type="button" title="Schedule a post at a default hour for this day (daily plan). Drives engagement and tag stats." onclick="showPostForm()" id="postBtn" class="action-btn group p-4 rounded-xl bg-gradient-to-br from-primary/5 to-primary/10 border border-primary/15 hover:border-primary/40 hover:from-primary/10 hover:to-primary/20 text-center">
+              <span class="material-symbols-outlined text-primary text-3xl group-hover:scale-110 transition-transform">send</span>
+              <div class="text-sm font-bold text-primary mt-1">Post</div>
+              <div class="text-[9px] text-on-surface-dim mt-0.5">type + topic + tags</div>
+            </button>
+          </div>
+          <!-- Post Form -->
+          <div id="postForm" class="hidden fade-in space-y-2.5 p-4 rounded-xl bg-surface border border-outline/30">
+            <div class="grid grid-cols-2 gap-2.5">
+              <select id="contentType" class="bg-surface-low border border-outline/30 rounded-lg px-3 py-2 text-sm font-label focus:ring-1 focus:ring-primary focus:outline-none">
+                <option value="reel">Reel (-0.25 energy)</option>
+                <option value="carousel">Carousel (-0.20)</option>
+                <option value="story">Story (-0.08)</option>
+                <option value="text_post">Text Post (-0.06)</option>
+              </select>
+              <input id="topicInput" class="bg-surface-low border border-outline/30 rounded-lg px-3 py-2 text-sm focus:ring-1 focus:ring-primary focus:outline-none" placeholder="Topic (e.g. AI trends)"/>
+            </div>
+            <input id="tagsInput" class="w-full bg-surface-low border border-outline/30 rounded-lg px-3 py-2 text-sm focus:ring-1 focus:ring-primary focus:outline-none" placeholder="Tags comma-separated (ai, ml, coding)"/>
+            <div class="flex gap-2">
+              <button type="button" onclick="doPost()" class="px-5 py-2 rounded-lg bg-primary text-[#23005c] font-bold text-sm hover:opacity-90 transition">Send Post</button>
+              <button type="button" onclick="hidePostForm()" class="px-5 py-2 rounded-lg border border-outline/30 text-sm text-on-surface-dim hover:bg-white/5 transition">Cancel</button>
+            </div>
+          </div>
+        </div>
+
+        <!-- Simulate Scenarios (loaded from /dashboard/scenarios) -->
+        <div class="glass-solid p-5 rounded-xl overflow-hidden">
+          <div class="flex flex-wrap justify-between items-center gap-2 mb-3">
+            <h3 class="text-sm font-bold flex items-center gap-2"><span class="material-symbols-outlined text-secondary text-lg">science</span>Simulate Scenarios</h3>
+            <div class="flex flex-col items-end gap-0.5">
+              <div class="flex items-center gap-2">
+                <span id="scenarioCount" class="text-[9px] font-label text-primary font-bold">…</span>
+                <span class="text-[9px] font-label text-on-surface-dim">30-day episode</span>
+              </div>
+              <span class="text-[8px] font-label text-on-surface-dim/70 max-w-[16rem] text-right leading-tight">All strategies below — scroll the grid or search. Count updates after load.</span>
+            </div>
+          </div>
+          <div class="mb-3 space-y-2">
+            <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest">Suggested — Easy</div>
+            <div class="flex flex-wrap gap-2">
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-tertiary/10 border border-tertiary/25 text-[10px] font-label text-tertiary hover:bg-tertiary/20" onclick="runSim('easy_morning_story')">Morning story</button>
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-tertiary/10 border border-tertiary/25 text-[10px] font-label text-tertiary hover:bg-tertiary/20" onclick="runSim('easy_one_a_day')">One text @ 1pm</button>
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-tertiary/10 border border-tertiary/25 text-[10px] font-label text-tertiary hover:bg-tertiary/20" onclick="runSim('easy_relaxed')">Afternoon story</button>
+            </div>
+            <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest">Suggested — Medium</div>
+            <div class="flex flex-wrap gap-2">
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-secondary/10 border border-secondary/25 text-[10px] font-label text-secondary hover:bg-secondary/20" onclick="runSim('medium_queue_cycle')">Create → post</button>
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-secondary/10 border border-secondary/25 text-[10px] font-label text-secondary hover:bg-secondary/20" onclick="runSim('medium_trend_rotate')">Trend + formats</button>
+              <button type="button" class="sim-btn px-2.5 py-1.5 rounded-lg bg-secondary/10 border border-secondary/25 text-[10px] font-label text-secondary hover:bg-secondary/20" onclick="runSim('medium_two_format')">Reel + carousel</button>
+            </div>
+          </div>
+          <input type="search" id="scenarioFilter" autocomplete="off" placeholder="Search strategies by name or description…" class="w-full mb-2 bg-surface-low border border-outline/30 rounded-lg px-3 py-2 text-sm focus:ring-1 focus:ring-primary focus:outline-none"/>
+          <div id="scenarioGrid" tabindex="0" role="region" aria-label="Strategy list, scroll for all scenarios" class="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-2 mb-3 max-h-[min(52vh,36rem)] min-h-[14rem] overflow-y-auto overscroll-y-contain pr-1 py-1 rounded-lg border border-outline/15 bg-surface-low/40 scrollbar-thin shadow-inner">
+            <div class="col-span-full text-on-surface-dim text-[10px] italic py-4 text-center">Loading strategies…</div>
+          </div>
+          <!-- Sim Progress -->
+          <div id="simProgress" class="hidden">
+            <div class="flex items-center gap-3 mb-2">
+              <div class="h-2 flex-1 bg-surface-top rounded-full overflow-hidden"><div id="simBar" class="h-full bg-gradient-to-r from-primary to-secondary transition-all duration-100 rounded-full" style="width:0%"></div></div>
+              <span id="simPct" class="text-[10px] font-label text-on-surface-dim w-8 text-right">0%</span>
+            </div>
+            <div id="simResult" class="hidden"></div>
+          </div>
+        </div>
+
+        <!-- Day History -->
+        <div class="glass-solid rounded-xl overflow-hidden">
+          <div class="p-4 border-b border-white/5 flex justify-between items-center">
+            <h3 class="text-sm font-bold flex items-center gap-2"><span class="material-symbols-outlined text-on-surface-dim text-lg">history</span>Day History</h3>
+          </div>
+          <div id="historyLog" class="p-4 space-y-1.5 max-h-72 overflow-y-auto text-[11px] font-mono leading-relaxed">
+            <div class="text-on-surface-dim italic">Reset the environment to begin...</div>
+          </div>
+        </div>
+      </div>
+
+      <!-- Right: Intelligence Panels -->
+      <div class="lg:col-span-4 space-y-5">
+
+        <!-- Grader Score (shown when done) -->
+        <div id="graderCard" class="hidden glass-solid p-5 rounded-xl border-2 border-primary pulse-glow overflow-hidden">
+          <div class="flex justify-between items-start">
+            <div>
+              <div class="text-[9px] font-label text-primary uppercase tracking-widest">Final Score</div>
+              <div id="graderScore" class="text-5xl font-black text-primary tracking-tighter mt-1">—</div>
+            </div>
+            <span class="material-symbols-outlined text-primary/20 text-5xl">emoji_events</span>
+          </div>
+          <div id="graderLabel" class="mt-2 text-xs font-label text-on-surface-dim">Episode complete</div>
+        </div>
+
+        <!-- Trending -->
+        <div class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-3 flex items-center gap-2"><span class="material-symbols-outlined text-secondary text-lg">trending_up</span>Trending Now</h3>
+          <div class="mb-3">
+            <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1.5">Topics</div>
+            <div id="trendTopics" class="flex flex-wrap gap-1.5"></div>
+          </div>
+          <div>
+            <div class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest mb-1.5">Tags</div>
+            <div id="trendTags" class="flex flex-wrap gap-1.5"></div>
+          </div>
+        </div>
+
+        <!-- Tag Performance -->
+        <div class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-3 flex items-center gap-2"><span class="material-symbols-outlined text-primary text-lg">science</span>Tag Performance</h3>
+          <div id="tagPerf" class="space-y-2.5 text-xs">
+            <div class="text-on-surface-dim italic">No data yet</div>
+          </div>
+        </div>
+
+        <!-- Competitors -->
+        <div class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-3 flex items-center gap-2"><span class="material-symbols-outlined text-tertiary text-lg">groups</span>Competitors</h3>
+          <div class="mb-3 flex justify-between items-center">
+            <span class="text-[9px] font-label text-on-surface-dim uppercase tracking-widest">Avg Engagement</span>
+            <span id="compEng" class="text-sm font-bold text-tertiary">0.000</span>
+          </div>
+          <div id="compPosts" class="space-y-2 text-xs">
+            <div class="text-on-surface-dim italic">No competitor posts yet</div>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- Simulation History -->
+    <div class="glass-solid rounded-xl overflow-hidden">
+      <div class="p-4 border-b border-white/5 flex justify-between items-center">
+        <h3 class="text-sm font-bold flex items-center gap-2"><span class="material-symbols-outlined text-primary text-lg">history</span>Simulation History</h3>
+        <div class="flex items-center gap-2">
+          <button onclick="loadHistory()" class="text-[9px] font-label text-secondary hover:text-secondary/80 transition">Refresh</button>
+          <button onclick="clearHistory()" class="text-[9px] font-label text-on-surface-dim/50 hover:text-tertiary transition">Clear</button>
+        </div>
+      </div>
+      <div class="overflow-x-auto">
+        <table class="w-full text-[11px] font-label">
+          <thead>
+            <tr class="text-on-surface-dim/60 uppercase tracking-wider border-b border-white/5">
+              <th class="text-left px-4 py-2.5">Time</th>
+              <th class="text-left px-4 py-2.5">Scenario</th>
+              <th class="text-left px-4 py-2.5">Task</th>
+              <th class="text-right px-4 py-2.5">Score</th>
+              <th class="text-right px-4 py-2.5">Days</th>
+              <th class="text-right px-4 py-2.5">Posts</th>
+              <th class="text-right px-4 py-2.5">Followers</th>
+              <th class="text-right px-4 py-2.5">Delta</th>
+              <th class="text-right px-4 py-2.5">Energy</th>
+              <th class="text-center px-4 py-2.5">Status</th>
+            </tr>
+          </thead>
+          <tbody id="historyTable">
+            <tr><td colspan="10" class="px-4 py-6 text-center text-on-surface-dim italic">No history yet — run a simulation</td></tr>
+          </tbody>
+        </table>
+      </div>
+    </div>
+
+  </main>
+</div>
+
+<script>
+const API=window.location.origin;
+const EPISODE_DAYS=30;
+const DAYS=["Mon","Tue","Wed","Thu","Fri","Sat","Sun"];
+function fmtAxisNum(v){
+  const a=Math.abs(v);
+  if(a>=1e6)return (v/1e6).toFixed(1)+"M";
+  if(a>=1e3)return (v/1e3).toFixed(1)+"k";
+  if(a>=100)return v.toFixed(0);
+  if(a>=10)return v.toFixed(1);
+  return v.toFixed(2);
+}
+function refreshTaskScoreBlurb(){
+  const el=document.getElementById("taskScoreBlurb");
+  if(!el)return;
+  const t=document.getElementById("taskSelect").value;
+  if(t==="monthly_engage"){
+    el.innerHTML="<span class=\"text-on-surface font-semibold\">Easy (Engage):</span> final score = min(1, total episode engagement ÷ theoretical maximum). If energy hits 0 at the end, the score is multiplied by 0.3.";
+  }else if(t==="monthly_strategic"){
+    el.innerHTML="<span class=\"text-on-surface font-semibold\">Medium (Strategic):</span> 35% normalized engagement + 25% tag mix (discovery + top-tag performance) + 25% average energy + 15% days with solid posts. Penalties if energy ever crashes low or you use fewer than 5 unique tags.";
+  }else{
+    el.innerHTML="<span class=\"text-on-surface font-semibold\">Hard (Competitive):</span> 25% engagement + 20% tags + 20% follower growth + 15% beating rival avg engagement + 10% differentiated topics + 10% minimum energy floor. Score is 0 if burned out; ×0.5 if fewer than 3 content types; ×0.7 if fewer than 8 unique tags.";
+  }
+}
+let currentObs=null;
+const energyHistory=[];
+const rewardHistory=[];
+const followerHistory=[];
+const actionLog=[];
+const timelineHistory=[];
+let totalPostsCount=0;
+
+function recordTimelineFromObs(d, actionType){
+  const o=d.observation||d;
+  const step=o.metadata?.step??timelineHistory.length;
+  timelineHistory.push({
+    step,
+    simHour:(o.days_elapsed??0)*24+(o.current_hour??0),
+    hour:o.current_hour??0,
+    day:o.day_of_week??0,
+    energy:o.creator_energy??0,
+    followers:o.follower_count??0,
+    engagement:o.engagement_rate??0,
+    reward:d.reward??0,
+    sat:o.niche_saturation??0,
+    queue:o.content_queue_size??0,
+    postsToday:o.posts_today??0,
+    compAvg:o.competitor_avg_engagement??0,
+    sleepDebt:o.sleep_debt??0,
+    hoursSinceSleep:o.hours_since_sleep??0,
+    action:actionType||null,
+  });
+}
+
+function simActionType(actionStr){
+  const a=actionStr||"";
+  if(a.startsWith("post"))return "post";
+  if(a.startsWith("rest"))return "rest";
+  if(a.startsWith("create"))return "create_content";
+  return null;
+}
+
+function redrawTimelineCharts(){
+  drawStepLineChart("tsEnergy","energy","#ffb2b9");
+  drawStepLineChart("tsFollowers","followers","#7bd0ff");
+  drawFollowerDeltaChart("tsFollowDelta");
+  drawStepLineChart("tsEngagement","engagement","#a078ff");
+  drawStepLineChart("tsReward","reward","#d0bcff");
+  drawStepLineChart("tsSat","sat","#ea6479");
+  drawStepLineChart("tsQueue","queue","#00a6e0");
+  drawStepLineChart("tsComp","compAvg","#7bd0ff");
+  drawStepLineChart("tsSleep","sleepDebt","#958ea0");
+  drawStepLineChart("tsAwake","hoursSinceSleep","#cbc3d7");
+  drawPostsByHour("tsPostsHour");
+  drawActionMix("tsActionMix");
+}
+
+function drawStepLineChart(svgId,key,color){
+  const svg=document.getElementById(svgId);
+  const data=timelineHistory;
+  if(!svg)return;
+  const W=360,H=112,pL=48,pR=10,pT=10,pB=28;
+  const plotW=W-pL-pR,plotH=H-pT-pB;
+  if(!data.length){
+    svg.innerHTML=`<text x="${W/2}" y="${H/2}" text-anchor="middle" fill="#958ea0" font-size="10" font-family="Space Grotesk,sans-serif">No days yet</text>`;
+    return;
+  }
+  const vals=data.map(d=>Number(d[key]??0));
+  let minV=Math.min(...vals),maxV=Math.max(...vals);
+  if(maxV-minV<1e-9){minV-=0.5;maxV+=0.5;}
+  const n=data.length;
+  const pts=data.map((d,i)=>{
+    const x=pL+(n<=1?plotW/2:i/(n-1)*plotW);
+    const v=Number(d[key]??0);
+    const y=pT+(1-(v-minV)/(maxV-minV))*plotH;
+    return {x,y};
+  });
+  let lineD;
+  if(pts.length===1)lineD=`M${pts[0].x},${pts[0].y} L${(pts[0].x+1)},${pts[0].y}`;
+  else lineD=smoothPath(pts);
+  const last=pts[pts.length-1],first=pts[0];
+  const areaD=lineD+` L${last.x},${H-pB} L${first.x},${H-pB} Z`;
+  const gid="g_"+svgId.replace(/[^a-zA-Z0-9_]/g,"_");
+  let h="";
+  for(let g=0;g<=4;g++){
+    const y=pT+(g/4)*plotH;
+    const val=maxV-(g/4)*(maxV-minV);
+    h+=`<line x1="${pL}" y1="${y}" x2="${W-pR}" y2="${y}" stroke="#494454" stroke-width="0.5" opacity="0.35"/>`;
+    h+=`<text x="${pL-5}" y="${y+3}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${fmtAxisNum(val)}</text>`;
+  }
+  h+=`<line x1="${pL}" y1="${pT}" x2="${pL}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.9"/>`;
+  h+=`<line x1="${pL}" y1="${H-pB}" x2="${W-pR}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.9"/>`;
+  h+=`<defs><linearGradient id="${gid}" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="${color}" stop-opacity="0.22"/><stop offset="1" stop-color="${color}" stop-opacity="0"/></linearGradient></defs>`;
+  h+=`<path d="${areaD}" fill="url(#${gid})"/><path d="${lineD}" fill="none" stroke="${color}" stroke-width="2"/>`;
+  const lastI=n-1;
+  h+=`<text x="${pL}" y="${H-8}" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">0</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-8}" text-anchor="middle" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${Math.floor(lastI/2)}</text>`;
+  h+=`<text x="${W-pR}" y="${H-8}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${lastI}</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-1}" text-anchor="middle" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif" opacity="0.75">day</text>`;
+  svg.innerHTML=h;
+}
+
+function drawFollowerDeltaChart(svgId){
+  const svg=document.getElementById(svgId);
+  const data=timelineHistory;
+  if(!svg)return;
+  const W=360,H=112,pL=48,pR=10,pT=10,pB=28;
+  const plotW=W-pL-pR,plotH=H-pT-pB;
+  if(data.length<2){
+    svg.innerHTML=`<text x="${W/2}" y="${H/2}" text-anchor="middle" fill="#958ea0" font-size="10" font-family="Space Grotesk,sans-serif">Need 2+ days</text>`;
+    return;
+  }
+  const dlt=data.map((d,i)=>i===0?0:d.followers-data[i-1].followers);
+  const maxA=Math.max(...dlt.map(a=>Math.abs(a)),1);
+  const midY=pT+plotH/2;
+  const amp=(plotH/2-4);
+  const n=data.length;
+  const pts=dlt.map((dv,i)=>{
+    const x=pL+(n<=1?plotW/2:i/(n-1)*plotW);
+    const y=midY-(dv/maxA)*amp;
+    return {x,y};
+  });
+  const lineD=smoothPath(pts);
+  let h="";
+  h+=`<line x1="${pL}" y1="${midY}" x2="${W-pR}" y2="${midY}" stroke="#494454" stroke-width="0.6" opacity="0.45"/>`;
+  h+=`<text x="${pL-5}" y="${pT+8}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">+${fmtAxisNum(maxA)}</text>`;
+  h+=`<text x="${pL-5}" y="${H-pB}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${fmtAxisNum(-maxA)}</text>`;
+  h+=`<line x1="${pL}" y1="${pT}" x2="${pL}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.9"/>`;
+  h+=`<line x1="${pL}" y1="${H-pB}" x2="${W-pR}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.9"/>`;
+  h+=`<path d="${lineD}" fill="none" stroke="#7bd0ff" stroke-width="2"/>`;
+  const lastI=n-1;
+  h+=`<text x="${pL}" y="${H-8}" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">0</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-8}" text-anchor="middle" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${Math.floor(lastI/2)}</text>`;
+  h+=`<text x="${W-pR}" y="${H-8}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${lastI}</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-1}" text-anchor="middle" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif" opacity="0.75">day · Δ followers</text>`;
+  svg.innerHTML=h;
+}
+
+function drawPostsByHour(svgId){
+  const svg=document.getElementById(svgId);
+  if(!svg)return;
+  const buckets=new Array(24).fill(0);
+  for(const p of timelineHistory){
+    if(p.action==="post")buckets[p.hour]++;
+  }
+  const postN=buckets.reduce((a,b)=>a+b,0);
+  if(!postN){
+    svg.innerHTML='<text x="160" y="40" text-anchor="middle" fill="#958ea0" font-size="10" font-family="Space Grotesk,sans-serif">No posts yet — histogram fills when you post</text>';
+    return;
+  }
+  const max=Math.max(...buckets,1);
+  const W=320,H=64,pL=16,pR=4,pT=4,pB=16;
+  const slot=(W-pL-pR)/24;
+  const bw=slot*0.72;
+  let rects="";
+  for(let h=0;h<24;h++){
+    const bh=(buckets[h]/max)*(H-pT-pB);
+    const x=pL+h*slot+(slot-bw)/2;
+    const y=H-pB-Math.max(bh,0.5);
+    rects+=`<rect x="${x.toFixed(2)}" y="${y.toFixed(2)}" width="${bw.toFixed(2)}" height="${Math.max(bh,0.5).toFixed(2)}" fill="#d0bcff" rx="1"/>`;
+  }
+  let labels="";
+  for(let h=0;h<24;h+=6){
+    labels+=`<text x="${(pL+h*slot+bw/2).toFixed(1)}" y="${H-3}" text-anchor="middle" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${h}h</text>`;
+  }
+  svg.innerHTML=rects+labels;
+}
+
+function drawActionMix(svgId){
+  const svg=document.getElementById(svgId);
+  if(!svg)return;
+  if(!timelineHistory.length){
+    svg.innerHTML='<text x="160" y="28" text-anchor="middle" fill="#958ea0" font-size="10" font-family="Space Grotesk,sans-serif">No days yet</text>';
+    return;
+  }
+  let r=0,c=0,p=0;
+  for(const x of timelineHistory){
+    if(x.action==="rest")r++;
+    else if(x.action==="create_content")c++;
+    else if(x.action==="post")p++;
+  }
+  const W=320,H=44,pT=6,pB=4;
+  const labels=[["Rest",r,"#ffb2b9"],["Create",c,"#7bd0ff"],["Post",p,"#d0bcff"]];
+  const max=Math.max(r,c,p,1);
+  const bw=90;
+  let out="";
+  labels.forEach(([lab,n,col],i)=>{
+    const x=20+i*100;
+    const bh=(n/max)*(H-pT-pB);
+    const y=H-pB-bh;
+    out+=`<rect x="${x}" y="${y}" width="${bw}" height="${Math.max(bh,2)}" fill="${col}" rx="2"/>`;
+    out+=`<text x="${x+bw/2}" y="${H+2}" text-anchor="middle" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${lab} ${n}</text>`;
+  });
+  svg.innerHTML=out;
+}
+
+async function doReset(){
+  setStatus("Resetting...");
+  const task=document.getElementById("taskSelect").value;
+  energyHistory.length=0;rewardHistory.length=0;followerHistory.length=0;actionLog.length=0;timelineHistory.length=0;totalPostsCount=0;
+  try{
+    const r=await fetch(API+"/dashboard/reset",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({task})});
+    const d=await r.json();
+    updateUI(d);
+    document.getElementById("historyLog").innerHTML='<div class="text-secondary font-bold">Environment reset — task: '+task+'</div>';
+    document.getElementById("graderCard").classList.add("hidden");
+    document.getElementById("engagementChart").innerHTML="";
+    document.getElementById("followerChart").innerHTML="";
+    document.getElementById("recentActions").innerHTML='<div class="text-on-surface-dim italic text-[10px]">No actions yet</div>';
+    drawBurnoutMeter(1);
+    setStatus("Running");
+  }catch(e){setStatus("Error: "+e.message)}
+}
+
+async function doAction(type){
+  setStatus("Running day…");
+  try{
+    const r=await fetch(API+"/dashboard/step",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({action:{action_type:type}})});
+    const d=await r.json();
+    updateUI(d,{actionType:type});
+    addLog(type+"()",d.reward,d.done,d.observation?.error);
+  }catch(e){setStatus("Error: "+e.message)}
+}
+
+async function doPost(){
+  const ct=document.getElementById("contentType").value;
+  const topic=document.getElementById("topicInput").value.trim();
+  const tagsRaw=document.getElementById("tagsInput").value.trim();
+  const tags=tagsRaw?tagsRaw.split(",").map(t=>t.trim()).filter(Boolean):[];
+  if(!topic){alert("Enter a topic");return}
+  setStatus("Running day…");
+  try{
+    const body={action:{action_type:"post",content_type:ct,topic,tags:tags.length?tags:undefined}};
+    const r=await fetch(API+"/dashboard/step",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(body)});
+    const d=await r.json();
+    updateUI(d,{actionType:"post"});
+    addLog(`post(${ct},"${topic}",[${tags.join(",")}])`,d.reward,d.done,d.observation?.error);
+    hidePostForm();
+  }catch(e){setStatus("Error: "+e.message)}
+}
+
+function updateUI(d, opts={}){
+  const o=d.observation||d;
+  currentObs=o;
+  recordTimelineFromObs(d, opts.actionType);
+  const energy=o.creator_energy??1;
+  const followers=o.follower_count??0;
+  const eng=o.engagement_rate??0;
+  const sat=o.niche_saturation??0;
+  const compAvg=o.competitor_avg_engagement??0;
+  const reward=d.reward??0;
+
+  document.getElementById("energyVal").textContent=energy.toFixed(2);
+  document.getElementById("energyBar").style.width=(energy*100)+"%";
+  const eHint=document.getElementById("energyHint");
+  if(energy<=0){eHint.textContent="BURNED OUT";eHint.className="mt-1.5 text-[9px] font-label text-error"}
+  else if(energy<0.3){eHint.textContent="CRITICAL";eHint.className="mt-1.5 text-[9px] font-label text-tertiary-ctr"}
+  else if(energy<0.5){eHint.textContent="LOW — REST NOW";eHint.className="mt-1.5 text-[9px] font-label text-tertiary"}
+  else if(energy<0.8){eHint.textContent="MODERATE";eHint.className="mt-1.5 text-[9px] font-label text-on-surface-dim"}
+  else{eHint.textContent="FULL";eHint.className="mt-1.5 text-[9px] font-label text-secondary"}
+
+  document.getElementById("followersVal").textContent=followers.toLocaleString();
+  const delta=followers-10000;
+  const dEl=document.getElementById("followersDelta");
+  dEl.textContent=(delta>=0?"+":"")+delta+" since start";
+  dEl.className="mt-1.5 text-[9px] font-label "+(delta>0?"text-secondary":delta<0?"text-tertiary":"text-on-surface-dim");
+
+  document.getElementById("engVal").textContent=eng.toFixed(3);
+  const diff=eng-compAvg;
+  const evc=document.getElementById("engVsComp");
+  evc.textContent="vs competitors: "+(diff>=0?"+":"")+diff.toFixed(3);
+  evc.className="mt-1.5 text-[9px] font-label "+(diff>0?"text-secondary":"text-tertiary");
+
+  document.getElementById("timeVal").textContent=(o.current_hour??0)+":00";
+  document.getElementById("dayVal").textContent=DAYS[o.day_of_week??0];
+  document.getElementById("postsVal").textContent=o.posts_today??0;
+  document.getElementById("queueVal").textContent=o.content_queue_size??0;
+  document.getElementById("satVal").textContent=sat.toFixed(2);
+  const sH=document.getElementById("satHint");
+  if(sat>0.7){sH.textContent="HIGH — diversify topics";sH.className="mt-1.5 text-[9px] font-label text-tertiary"}
+  else if(sat>0.4){sH.textContent="MEDIUM — some room";sH.className="mt-1.5 text-[9px] font-label text-on-surface-dim"}
+  else{sH.textContent="LOW — post unique topics";sH.className="mt-1.5 text-[9px] font-label text-primary"}
+  document.getElementById("stepNum").textContent=o.metadata?.step??0;
+
+  // Charts
+  energyHistory.push(energy);
+  rewardHistory.push(reward);
+  followerHistory.push(followers);
+  drawEngagementChart();
+  drawBurnoutMeter(energy);
+  drawFollowerBars();
+  updateBottomStats();
+  if(d.action_type||d.observation?.metadata)addRecentAction(d);
+
+  // Trending
+  const tt=document.getElementById("trendTopics");
+  tt.innerHTML=(o.trending_topics||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-secondary/10 border border-secondary/15 text-secondary text-[10px] font-label">${t}</span>`).join("");
+  const tg=document.getElementById("trendTags");
+  tg.innerHTML=(o.trending_tags||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-primary/10 border border-primary/15 text-primary text-[10px] font-label">#${t}</span>`).join("");
+
+  // Tag perf — sidebar panel
+  const tp=document.getElementById("tagPerf");
+  const perf=o.tag_performance||{};
+  const entries=Object.entries(perf).sort((a,b)=>b[1]-a[1]);
+  if(entries.length){
+    const maxV=Math.max(...entries.map(e=>e[1]),0.01);
+    tp.innerHTML=entries.slice(0,6).map(([tag,val],i)=>{
+      const w=Math.min(100,(val/maxV)*100);
+      const c=i%2===0?"primary":"secondary";
+      return `<div><div class="flex justify-between font-label text-[10px]"><span class="text-on-surface">#${tag}</span><span class="text-${c}">${val.toFixed(3)}</span></div><div class="h-1.5 bg-surface-top rounded-full mt-1 overflow-hidden"><div class="h-full bg-gradient-to-r from-${c} to-${c}-ctr rounded-full" style="width:${w}%"></div></div></div>`;
+    }).join("");
+  }else{tp.innerHTML='<div class="text-on-surface-dim italic text-[10px]">No tag data yet</div>'}
+
+  // Top tags styled list
+  const ttl=document.getElementById("topTagsList");
+  const colors=["secondary","primary","tertiary","on-surface-dim"];
+  if(entries.length){
+    ttl.innerHTML=entries.slice(0,4).map(([tag,val],i)=>{
+      const c=colors[i%colors.length];
+      const fmtVal=val>=1000?(val/1000).toFixed(1)+"k":val.toFixed(1);
+      return `<div class="flex items-center justify-between"><div class="flex items-center gap-2.5"><span class="w-2 h-2 rounded-full bg-${c}"></span><span class="text-sm font-label text-on-surface">#${tag}</span></div><span class="text-sm font-bold font-label text-${c}">${fmtVal}</span></div>`;
+    }).join("");
+  }else{ttl.innerHTML='<div class="text-on-surface-dim italic text-[10px]">No tag data yet</div>'}
+
+  // Competitors
+  document.getElementById("compEng").textContent=compAvg.toFixed(3);
+  const cp=document.getElementById("compPosts");
+  const posts=o.competitor_recent_posts||[];
+  if(posts.length){
+    const icons={reel:"movie",carousel:"view_carousel",story:"auto_stories",text_post:"article"};
+    cp.innerHTML=posts.slice(0,4).map(p=>`<div class="p-2.5 rounded-lg bg-surface border border-outline/15 flex items-start gap-2.5"><span class="material-symbols-outlined text-tertiary/40 text-lg mt-0.5">${icons[p.content_type]||"article"}</span><div class="flex-1 min-w-0"><div class="flex justify-between text-[10px]"><span class="font-bold text-on-surface truncate">${p.topic||"—"}</span><span class="text-on-surface-dim shrink-0 ml-2">${p.hours_ago}h</span></div><div class="text-[9px] text-on-surface-dim mt-0.5">${p.content_type} · eng: <span class="text-tertiary">${(p.engagement??0).toFixed(3)}</span></div></div></div>`).join("");
+  }else{cp.innerHTML='<div class="text-on-surface-dim italic text-[10px]">No competitor posts yet</div>'}
+
+  // Done state
+  if(d.done){
+    setStatus("Episode Done");
+    document.querySelectorAll("#postBtn,.action-btn").forEach(b=>{b.disabled=true;b.classList.add("opacity-30","pointer-events-none")});
+    const score=o.metadata?.grader_score;
+    if(score!=null){
+      const gc=document.getElementById("graderCard");
+      gc.classList.remove("hidden");
+      document.getElementById("graderScore").textContent=score.toFixed(4);
+      const lbl=document.getElementById("graderLabel");
+      if(score>=0.7)lbl.textContent="Excellent performance!";
+      else if(score>=0.4)lbl.textContent="Decent strategy, room for improvement";
+      else lbl.textContent="Poor performance — agent needs better strategy";
+    }
+  }else{
+    document.querySelectorAll("#postBtn,.action-btn").forEach(b=>{b.disabled=false;b.classList.remove("opacity-30","pointer-events-none")});
+    setStatus("Running");
+  }
+  redrawTimelineCharts();
+}
+
+function smoothPath(pts){
+  if(pts.length<2)return pts.map((p,i)=>(i===0?"M":"L")+p.x.toFixed(1)+","+p.y.toFixed(1)).join(" ");
+  let d="M"+pts[0].x.toFixed(1)+","+pts[0].y.toFixed(1);
+  for(let i=1;i<pts.length;i++){
+    const cp=(pts[i].x-pts[i-1].x)/3;
+    d+=` C${(pts[i-1].x+cp).toFixed(1)},${pts[i-1].y.toFixed(1)} ${(pts[i].x-cp).toFixed(1)},${pts[i].y.toFixed(1)} ${pts[i].x.toFixed(1)},${pts[i].y.toFixed(1)}`;
+  }
+  return d;
+}
+
+function drawEngagementChart(){
+  const svg=document.getElementById("engagementChart");
+  const data=rewardHistory;
+  if(!svg||!data.length)return;
+  const W=760,H=200,pL=56,pR=14,pT=12,pB=40;
+  const plotW=W-pL-pR,plotH=H-pT-pB;
+  const minR=Math.min(0,Math.min(...data));
+  const maxR=Math.max(...data,0.01);
+  const span=Math.max(maxR-minR,1e-6)*1.08;
+  const y0=minR;
+  const pts=data.map((v,i)=>({
+    x:pL+(i/Math.max(data.length-1,1))*plotW,
+    y:pT+(1-(v-y0)/span)*plotH,
+  }));
+  const lineD=smoothPath(pts);
+  const areaD=lineD+` L${pts[pts.length-1].x.toFixed(1)},${(H-pB).toFixed(1)} L${pts[0].x.toFixed(1)},${(H-pB).toFixed(1)} Z`;
+  const gid="eng_reward_grad";
+  let h="";
+  for(let g=0;g<=4;g++){
+    const y=pT+(g/4)*plotH;
+    const val=y0+(1-g/4)*span;
+    h+=`<line x1="${pL}" y1="${y}" x2="${W-pR}" y2="${y}" stroke="#494454" stroke-width="0.5" opacity="0.35"/>`;
+    h+=`<text x="${pL-6}" y="${y+3}" text-anchor="end" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif">${val.toFixed(2)}</text>`;
+  }
+  h+=`<line x1="${pL}" y1="${pT}" x2="${pL}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="1"/>`;
+  h+=`<line x1="${pL}" y1="${H-pB}" x2="${W-pR}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="1"/>`;
+  h+=`<defs><linearGradient id="${gid}" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#7bd0ff" stop-opacity="0.28"/><stop offset="1" stop-color="#7bd0ff" stop-opacity="0"/></linearGradient></defs>`;
+  h+=`<path d="${areaD}" fill="url(#${gid})"/><path d="${lineD}" fill="none" stroke="#7bd0ff" stroke-width="2.5"/>`;
+  const lastI=data.length-1;
+  h+=`<text x="${pL}" y="${H-18}" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif">day 0</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-18}" text-anchor="middle" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif">day ${Math.floor(lastI/2)}</text>`;
+  h+=`<text x="${W-pR}" y="${H-18}" text-anchor="end" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif">day ${lastI}</text>`;
+  h+=`<text x="${pL+plotW/2}" y="${H-4}" text-anchor="middle" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif" opacity="0.85">day index (1–${EPISODE_DAYS})</text>`;
+  h+=`<text x="12" y="${pT+plotH/2}" transform="rotate(-90 12 ${pT+plotH/2})" text-anchor="middle" fill="#958ea0" font-size="9" font-family="Space Grotesk,sans-serif" opacity="0.85">reward</text>`;
+  svg.innerHTML=h;
+}
+
+function drawBurnoutMeter(energy){
+  const burnout=Math.round((1-energy)*100);
+  const circ=2*Math.PI*50;
+  const fill=(burnout/100)*circ;
+  document.getElementById("burnoutArc").setAttribute("stroke-dasharray",fill.toFixed(1)+" "+circ.toFixed(1));
+  document.getElementById("burnoutPct").textContent=burnout+"%";
+  const rec=document.getElementById("burnoutRec");
+  if(burnout>=70)rec.textContent="Recommendation: Ease off scheduled posts for the next day to prevent creative fatigue.";
+  else if(burnout>=40)rec.textContent="Recommendation: Alternate between creating and resting to maintain output quality.";
+  else rec.textContent="Recommendation: Energy levels healthy. Good window for high-effort content.";
+}
+
+function drawFollowerBars(){
+  const svg=document.getElementById("followerChart");
+  const data=followerHistory;
+  if(data.length<2){svg.innerHTML="";return}
+  const W=300,H=120,pL=40,pR=8,pT=6,pB=22,plotW=W-pL-pR,plotH=H-pT-pB;
+  const chunks=Math.min(data.length,7);
+  const chunkSize=Math.max(1,Math.floor(data.length/chunks));
+  const bars=[];
+  for(let i=0;i<chunks;i++){
+    const start=i*chunkSize;
+    const end=Math.min(start+chunkSize,data.length);
+    const avg=data.slice(start,end).reduce((a,b)=>a+b,0)/(end-start);
+    bars.push(avg);
+  }
+  const fMin=Math.min(...bars),fMax=Math.max(...bars);
+  const base=fMin*0.998;
+  const maxDelta=Math.max(...bars.map(b=>b-base),1);
+  const barW=plotW/bars.length*0.58;
+  const gap=plotW/bars.length*0.42;
+  let html="";
+  html+=`<text x="4" y="${pT+10}" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif">${Math.round(fMax)}</text>`;
+  html+=`<text x="4" y="${pT+plotH}" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif">${Math.round(fMin)}</text>`;
+  html+=`<text transform="rotate(-90 14 ${pT+plotH/2})" x="14" y="${pT+plotH/2}" text-anchor="middle" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif">followers</text>`;
+  bars.forEach((v,i)=>{
+    const h=Math.max(4,((v-base)/maxDelta)*plotH);
+    const x=pL+i*(plotW/bars.length)+(gap/2);
+    const y=pT+plotH-h;
+    const opacity=0.5+0.5*(i/bars.length);
+    html+=`<rect x="${x.toFixed(1)}" y="${y.toFixed(1)}" width="${barW.toFixed(1)}" height="${h.toFixed(1)}" rx="3" fill="#7bd0ff" opacity="${opacity.toFixed(2)}"/>`;
+    html+=`<text x="${(x+barW/2).toFixed(1)}" y="${H-4}" text-anchor="middle" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif">${DAYS[i%7]}</text>`;
+  });
+  svg.innerHTML=html;
+  const delta=data[data.length-1]-data[0];
+  const pct=((delta/data[0])*100);
+  document.getElementById("followerTotal").textContent=(delta>=0?"+":"")+Math.round(delta).toLocaleString();
+  document.getElementById("followerDeltaPct").textContent=(pct>=0?"+":"")+pct.toFixed(0)+"% vs start";
+}
+
+function updateBottomStats(){
+  if(rewardHistory.length){
+    const avg=rewardHistory.reduce((a,b)=>a+b,0)/rewardHistory.length;
+    document.getElementById("bottomAvgReward").textContent=avg.toFixed(2);
+    if(rewardHistory.length>10){
+      const recent=rewardHistory.slice(-10).reduce((a,b)=>a+b,0)/10;
+      const old=rewardHistory.slice(0,10).reduce((a,b)=>a+b,0)/Math.min(10,rewardHistory.length);
+      const d=((recent-old)/Math.max(Math.abs(old),0.001)*100);
+      document.getElementById("bottomAvgDelta").textContent=(d>=0?"+":"")+d.toFixed(0)+"%";
+      document.getElementById("bottomAvgDelta").className="text-[10px] font-label mt-1 "+(d>=0?"text-secondary":"text-tertiary");
+    }
+  }
+  document.getElementById("bottomTotalPosts").textContent=totalPostsCount;
+  const eng=currentObs?.engagement_rate??0;
+  const viral=Math.min(100,Math.round(eng*1000));
+  const label=viral>=70?"HIGH":viral>=40?"MEDIUM":"LOW";
+  document.getElementById("bottomViralProb").textContent=label+" ("+viral+"%)";
+  const vn=document.getElementById("viralFormulaNote");
+  if(vn)vn.textContent="min(100, round("+eng.toFixed(3)+" × 1000)) = "+viral+" — labels LOW/MED/HIGH at 40 and 70 (display only).";
+}
+
+function addRecentAction(d){
+  const el=document.getElementById("recentActions");
+  const step=currentObs?.metadata?.step??0;
+  const reward=d.reward??0;
+  const icons={rest:"hotel",create_content:"edit_note",post:"send"};
+  const colors={rest:"tertiary",create_content:"secondary",post:"primary"};
+  const action=d.action_type||d.observation?.last_action||"step";
+  const icon=icons[action]||"play_arrow";
+  const c=colors[action]||"on-surface-dim";
+  const entry=`<div class="flex items-start gap-2.5 fade-in"><span class="material-symbols-outlined text-${c} text-lg mt-0.5 shrink-0">${icon}</span><div class="flex-1 min-w-0"><div class="text-xs font-bold text-on-surface truncate">${action.replace("_"," ")}</div><div class="text-[9px] text-on-surface-dim">day ${step} · r=${reward.toFixed(2)}</div></div></div>`;
+  if(el.querySelector(".italic"))el.innerHTML="";
+  el.innerHTML=entry+el.innerHTML;
+  if(el.children.length>8)el.removeChild(el.lastChild);
+}
+
+function addLog(action,reward,done,error){
+  if(action.startsWith("post"))totalPostsCount++;
+  const step=currentObs?.metadata?.step??0;
+  const log=document.getElementById("historyLog");
+  const errStr=error?` <span class="text-error">err=${error}</span>`:"";
+  const color=reward>0.5?"text-secondary":reward>0.2?"text-primary":"text-on-surface-dim";
+  const doneStr=done?'<span class="text-tertiary font-bold"> DONE</span>':"";
+  log.innerHTML+=`<div class="fade-in py-0.5"><span class="text-on-surface-dim/50">[day ${step}]</span> <span class="text-on-surface">${action}</span> <span class="${color}">r=${(reward??0).toFixed(2)}</span>${doneStr}${errStr}</div>`;
+  log.scrollTop=log.scrollHeight;
+  document.getElementById("rewardBadge").textContent="Last reward: "+(reward??0).toFixed(2);
+}
+
+let simRunning=false;
+async function runSim(scenario){
+  if(simRunning)return;
+  simRunning=true;
+  const task=document.getElementById("taskSelect").value;
+  document.querySelectorAll(".sim-btn").forEach(b=>b.classList.add("opacity-30","pointer-events-none"));
+  document.getElementById("simProgress").classList.remove("hidden");
+  document.getElementById("simResult").classList.add("hidden");
+  document.getElementById("simBar").style.width="0%";
+  document.getElementById("simPct").textContent="0%";
+  document.getElementById("graderCard").classList.add("hidden");
+  energyHistory.length=0;rewardHistory.length=0;followerHistory.length=0;timelineHistory.length=0;totalPostsCount=0;
+  setStatus("Simulating...");
+
+  try{
+    const r=await fetch(API+"/dashboard/simulate",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({scenario,task})});
+    const d=await r.json();
+    if(d.error){setStatus("Error: "+d.error);simRunning=false;return}
+
+    const log=document.getElementById("historyLog");
+    log.innerHTML=`<div class="text-secondary font-bold mb-1">Sim: ${d.scenario} — ${task}</div><div class="text-on-surface-dim text-[9px] mb-2">${d.description}</div>`;
+
+    const total=d.steps.length;
+    for(let i=0;i<total;i++){
+      const s=d.steps[i];
+      rewardHistory.push(s.reward);
+      energyHistory.push(s.energy);
+      followerHistory.push(s.followers);
+      timelineHistory.push({
+        step:s.step,
+        simHour:(s.days_elapsed??0)*24+(s.hour??0),
+        hour:s.hour??0,
+        day:s.day??0,
+        energy:s.energy,
+        followers:s.followers,
+        engagement:s.engagement_rate,
+        reward:s.reward,
+        sat:s.niche_saturation,
+        queue:s.queue,
+        postsToday:s.posts_today,
+        compAvg:s.competitor_avg_engagement,
+        sleepDebt:s.sleep_debt??0,
+        hoursSinceSleep:s.hours_since_sleep??0,
+        action:simActionType(s.action),
+      });
+      if(s.action.startsWith("post"))totalPostsCount++;
+
+      const pct=Math.round((i+1)/total*100);
+      document.getElementById("simBar").style.width=pct+"%";
+      document.getElementById("simPct").textContent=pct+"%";
+
+      document.getElementById("energyVal").textContent=s.energy.toFixed(2);
+      document.getElementById("energyBar").style.width=(s.energy*100)+"%";
+      document.getElementById("followersVal").textContent=s.followers.toLocaleString();
+      document.getElementById("engVal").textContent=s.engagement_rate.toFixed(3);
+      document.getElementById("stepNum").textContent=s.step;
+      document.getElementById("timeVal").textContent=s.hour+":00";
+      document.getElementById("dayVal").textContent=DAYS[s.day];
+      document.getElementById("postsVal").textContent=s.posts_today;
+      document.getElementById("queueVal").textContent=s.queue;
+      document.getElementById("satVal").textContent=s.niche_saturation.toFixed(2);
+      document.getElementById("compEng").textContent=s.competitor_avg_engagement.toFixed(3);
+      const diff=s.engagement_rate-s.competitor_avg_engagement;
+      const evc=document.getElementById("engVsComp");
+      evc.textContent="vs competitors: "+(diff>=0?"+":"")+diff.toFixed(3);
+      evc.className="mt-1.5 text-[9px] font-label "+(diff>0?"text-secondary":"text-tertiary");
+      const fdelta=s.followers-10000;
+      const fdEl=document.getElementById("followersDelta");
+      fdEl.textContent=(fdelta>=0?"+":"")+fdelta+" since start";
+      fdEl.className="mt-1.5 text-[9px] font-label "+(fdelta>0?"text-secondary":fdelta<0?"text-tertiary":"text-on-surface-dim");
+
+      drawEngagementChart();
+      drawBurnoutMeter(s.energy);
+      drawFollowerBars();
+      updateBottomStats();
+      redrawTimelineCharts();
+
+      const tt=document.getElementById("trendTopics");
+      tt.innerHTML=(s.trending_topics||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-secondary/10 border border-secondary/15 text-secondary text-[10px] font-label">${t}</span>`).join("");
+      const tg=document.getElementById("trendTags");
+      tg.innerHTML=(s.trending_tags||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-primary/10 border border-primary/15 text-primary text-[10px] font-label">#${t}</span>`).join("");
+
+      const perf=s.tag_performance||{};
+      const entries=Object.entries(perf).sort((a,b)=>b[1]-a[1]);
+      const tp=document.getElementById("tagPerf");
+      if(entries.length){
+        const maxV=Math.max(...entries.map(e=>e[1]),0.01);
+        tp.innerHTML=entries.slice(0,6).map(([tag,val],j)=>{
+          const c=j%2===0?"primary":"secondary";
+          const w=Math.min(100,(val/maxV)*100);
+          return `<div><div class="flex justify-between font-label text-[10px]"><span class="text-on-surface">#${tag}</span><span class="text-${c}">${val.toFixed(3)}</span></div><div class="h-1.5 bg-surface-top rounded-full mt-1 overflow-hidden"><div class="h-full bg-gradient-to-r from-${c} to-${c}-ctr rounded-full" style="width:${w}%"></div></div></div>`;
+        }).join("");
+      }
+      const ttl=document.getElementById("topTagsList");
+      const colors=["secondary","primary","tertiary","on-surface-dim"];
+      if(entries.length){
+        ttl.innerHTML=entries.slice(0,4).map(([tag,val],j)=>{
+          const c=colors[j%colors.length];
+          const fmtVal=val>=1000?(val/1000).toFixed(1)+"k":val.toFixed(1);
+          return `<div class="flex items-center justify-between"><div class="flex items-center gap-2.5"><span class="w-2 h-2 rounded-full bg-${c}"></span><span class="text-sm font-label text-on-surface">#${tag}</span></div><span class="text-sm font-bold font-label text-${c}">${fmtVal}</span></div>`;
+        }).join("");
+      }
+
+      await new Promise(r=>setTimeout(r,12));
+
+      const color=s.reward>0.5?"text-secondary":s.reward>0.2?"text-primary":"text-on-surface-dim";
+      const err=s.error?` <span class="text-error">err=${s.error}</span>`:"";
+      const dn=s.done?'<span class="text-tertiary font-bold"> DONE</span>':"";
+      log.innerHTML+=`<div class="fade-in py-0.5"><span class="text-on-surface-dim/50">[day ${s.step}]</span> <span class="text-on-surface">${s.action}</span> <span class="${color}">r=${s.reward.toFixed(2)}</span>${dn}${err}</div>`;
+      log.scrollTop=log.scrollHeight;
+    }
+
+    const f=d.final;
+    const sc=d.score;
+    redrawTimelineCharts();
+
+    // Final update of all panels using last step data
+    const lastStep=d.steps[d.steps.length-1];
+    if(lastStep){
+      const tt=document.getElementById("trendTopics");
+      tt.innerHTML=(lastStep.trending_topics||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-secondary/10 border border-secondary/15 text-secondary text-[10px] font-label">${t}</span>`).join("");
+      const tg=document.getElementById("trendTags");
+      tg.innerHTML=(lastStep.trending_tags||[]).map(t=>`<span class="px-2 py-1 rounded-lg bg-primary/10 border border-primary/15 text-primary text-[10px] font-label">#${t}</span>`).join("");
+
+      const perf=lastStep.tag_performance||{};
+      const entries=Object.entries(perf).sort((a,b)=>b[1]-a[1]);
+      const tp=document.getElementById("tagPerf");
+      if(entries.length){
+        const maxV=Math.max(...entries.map(e=>e[1]),0.01);
+        tp.innerHTML=entries.slice(0,6).map(([tag,val],j)=>{
+          const c=j%2===0?"primary":"secondary";
+          const w=Math.min(100,(val/maxV)*100);
+          return `<div><div class="flex justify-between font-label text-[10px]"><span class="text-on-surface">#${tag}</span><span class="text-${c}">${val.toFixed(3)}</span></div><div class="h-1.5 bg-surface-top rounded-full mt-1 overflow-hidden"><div class="h-full bg-gradient-to-r from-${c} to-${c}-ctr rounded-full" style="width:${w}%"></div></div></div>`;
+        }).join("");
+      }
+      const ttl=document.getElementById("topTagsList");
+      const colors=["secondary","primary","tertiary","on-surface-dim"];
+      if(entries.length){
+        ttl.innerHTML=entries.slice(0,4).map(([tag,val],j)=>{
+          const c=colors[j%colors.length];
+          const fmtVal=val>=1000?(val/1000).toFixed(1)+"k":val.toFixed(1);
+          return `<div class="flex items-center justify-between"><div class="flex items-center gap-2.5"><span class="w-2 h-2 rounded-full bg-${c}"></span><span class="text-sm font-label text-on-surface">#${tag}</span></div><span class="text-sm font-bold font-label text-${c}">${fmtVal}</span></div>`;
+        }).join("");
+      }
+
+      document.getElementById("compEng").textContent=lastStep.competitor_avg_engagement.toFixed(3);
+      currentObs={engagement_rate:lastStep.engagement_rate,metadata:{}};
+    }
+
+    // Show grader card
+    const gc=document.getElementById("graderCard");
+    gc.classList.remove("hidden");
+    document.getElementById("graderScore").textContent=sc.toFixed(4);
+    const lbl=document.getElementById("graderLabel");
+    if(sc>=0.7)lbl.textContent="Excellent performance!";
+    else if(sc>=0.4)lbl.textContent="Decent strategy, room for improvement";
+    else lbl.textContent="Poor performance — agent needs better strategy";
+
+    const res=document.getElementById("simResult");
+    res.classList.remove("hidden");
+    const scoreColor=sc>=0.7?"text-primary":sc>=0.3?"text-secondary":"text-tertiary";
+    const scoreBg=sc>=0.7?"border-primary/30 bg-primary/5":sc>=0.3?"border-secondary/30 bg-secondary/5":"border-tertiary/30 bg-tertiary/5";
+    res.innerHTML=`
+      <div class="p-4 rounded-xl border ${scoreBg} space-y-2">
+        <div class="flex justify-between items-center"><span class="text-[10px] font-label text-on-surface-dim uppercase tracking-widest">Grader Score</span><span class="text-3xl font-black ${scoreColor}">${sc.toFixed(4)}</span></div>
+        <div class="grid grid-cols-2 gap-x-6 gap-y-1 text-[10px] font-label">
+          <div class="flex justify-between"><span class="text-on-surface-dim">Days</span><span>${d.total_steps}</span></div>
+          <div class="flex justify-between"><span class="text-on-surface-dim">Burned Out</span><span class="${f.burned_out?"text-tertiary":"text-secondary"}">${f.burned_out?"YES":"NO"}</span></div>
+          <div class="flex justify-between"><span class="text-on-surface-dim">Final Energy</span><span>${f.energy.toFixed(2)}</span></div>
+          <div class="flex justify-between"><span class="text-on-surface-dim">Followers</span><span>${f.followers.toLocaleString()}</span></div>
+          <div class="flex justify-between"><span class="text-on-surface-dim">Engagement</span><span>${f.engagement_rate.toFixed(4)}</span></div>
+          <div class="flex justify-between"><span class="text-on-surface-dim">Total Posts</span><span>${totalPostsCount}</span></div>
+        </div>
+      </div>`;
+    updateBottomStats();
+    setStatus("Simulation Done");
+    loadHistory();
+  }catch(e){setStatus("Error: "+e.message)}
+  document.querySelectorAll(".sim-btn").forEach(b=>b.classList.remove("opacity-30","pointer-events-none"));
+  simRunning=false;
+}
+
+function showPostForm(){document.getElementById("postForm").classList.remove("hidden")}
+function hidePostForm(){document.getElementById("postForm").classList.add("hidden")}
+function setStatus(s){
+  const el=document.getElementById("statusDot");
+  const color=s.includes("Error")?"text-error":s==="Running"?"text-secondary":s.includes("Done")?"text-primary":"text-on-surface-dim";
+  el.className="flex items-center gap-2 text-xs font-label "+color;
+  el.innerHTML=`<span class="w-2 h-2 rounded-full ${color.replace("text-","bg-")}"></span>${s}`;
+}
+
+async function loadHistory(){
+  try{
+    const r=await fetch(API+"/dashboard/history");
+    const data=await r.json();
+    const tb=document.getElementById("historyTable");
+    if(!data.length){tb.innerHTML='<tr><td colspan="10" class="px-4 py-6 text-center text-on-surface-dim italic">No history yet — run a simulation</td></tr>';return}
+    const taskLabels={monthly_engage:"Easy",monthly_strategic:"Medium",monthly_competitive:"Hard",weekly_engage:"Easy",weekly_strategic:"Medium",weekly_competitive:"Hard"};
+    tb.innerHTML=data.slice().reverse().map(h=>{
+      const dt=new Date(h.id);
+      const time=dt.toLocaleDateString("en-US",{month:"short",day:"numeric"})+' '+dt.toLocaleTimeString("en-US",{hour:"2-digit",minute:"2-digit"});
+      const f=h.final||{};
+      const delta=f.followers-10000;
+      const deltaStr=(delta>=0?"+":"")+delta.toLocaleString();
+      const deltaClass=delta>0?"text-secondary":delta<0?"text-tertiary":"text-on-surface-dim";
+      const scoreColor=h.score>=0.7?"text-primary":h.score>=0.3?"text-secondary":"text-tertiary";
+      const status=f.burned_out?'<span class="text-tertiary font-bold">BURNED</span>':h.total_steps>=EPISODE_DAYS?'<span class="text-secondary">DONE</span>':'<span class="text-on-surface-dim">PARTIAL</span>';
+      const energyColor=f.energy>=0.5?"text-secondary":f.energy>0?"text-tertiary":"text-error";
+      const desc=(h.description||"").trim();
+      return `<tr class="border-b border-white/5 hover:bg-white/[.02] transition">
+        <td class="px-4 py-2.5 text-on-surface-dim whitespace-nowrap">${time}</td>
+        <td class="px-4 py-2.5 min-w-[14rem] max-w-lg align-top">
+          <div class="text-on-surface font-bold">${_escapeHtml(h.scenario)}</div>
+          ${desc?`<div class="text-[10px] text-on-surface/75 mt-1 leading-relaxed whitespace-normal">${_escapeHtml(desc)}</div>`:""}
+        </td>
+        <td class="px-4 py-2.5 text-on-surface-dim">${taskLabels[h.task]||h.task}</td>
+        <td class="px-4 py-2.5 text-right ${scoreColor} font-bold">${h.score.toFixed(4)}</td>
+        <td class="px-4 py-2.5 text-right text-on-surface-dim">${h.total_steps}</td>
+        <td class="px-4 py-2.5 text-right text-on-surface-dim">${h.total_posts}</td>
+        <td class="px-4 py-2.5 text-right text-on-surface">${(f.followers||0).toLocaleString()}</td>
+        <td class="px-4 py-2.5 text-right ${deltaClass}">${deltaStr}</td>
+        <td class="px-4 py-2.5 text-right ${energyColor}">${(f.energy||0).toFixed(2)}</td>
+        <td class="px-4 py-2.5 text-center">${status}</td>
+      </tr>`;
+    }).join("");
+  }catch(e){console.error("History load failed",e)}
+}
+
+async function clearHistory(){
+  if(!confirm("Clear all simulation history?"))return;
+  await fetch(API+"/dashboard/history",{method:"DELETE"});
+  loadHistory();
+}
+
+function _escapeHtml(t){
+  const d=document.createElement("div");
+  d.textContent=t??"";
+  return d.innerHTML;
+}
+
+let _scenarioItems=[];
+
+async function loadScenarioButtons(){
+  const grid=document.getElementById("scenarioGrid");
+  const countEl=document.getElementById("scenarioCount");
+  const filterEl=document.getElementById("scenarioFilter");
+  if(!grid)return;
+  try{
+    const r=await fetch(API+"/dashboard/scenarios",{cache:"no-store",headers:{"Cache-Control":"no-cache"}});
+    const data=await r.json();
+    _scenarioItems=data.scenarios||[];
+    if(countEl)countEl.textContent=_scenarioItems.length+" strategies";
+    const pin=new Set(["easy_morning_story","easy_one_a_day","easy_relaxed","medium_queue_cycle","medium_trend_rotate","medium_two_format","smart","balanced","high_freq","optimal_sleep","sleep_conscious","sleep_debt_aware"]);
+    _scenarioItems.sort((a,b)=>{
+      const pa=pin.has(a.id)?0:1,pb=pin.has(b.id)?0:1;
+      if(pa!==pb)return pa-pb;
+      return (a.label||"").localeCompare(b.label||"","en",{sensitivity:"base"});
+    });
+    function render(){
+      const q=(filterEl&&filterEl.value||"").trim().toLowerCase();
+      grid.innerHTML="";
+      let n=0;
+      for(const s of _scenarioItems){
+        const lab=(s.label||"").toLowerCase();
+        const id=(s.id||"").toLowerCase();
+        const desc=(s.description||"").toLowerCase();
+        if(q&&!(lab.includes(q)||id.includes(q)||desc.includes(q)))continue;
+        n++;
+        const btn=document.createElement("button");
+        btn.type="button";
+        btn.className="sim-btn p-2.5 rounded-lg bg-surface border border-outline/20 hover:border-secondary/40 text-left transition";
+        if(pin.has(s.id))btn.classList.add("border-primary/25","hover:border-primary/55");
+        btn.onclick=()=>runSim(s.id);
+        btn.innerHTML=`<div class="text-xs font-bold text-on-surface leading-tight">${_escapeHtml(s.label)}</div><div class="text-[8px] text-on-surface-dim mt-0.5 line-clamp-2">${_escapeHtml(s.description)}</div>`;
+        grid.appendChild(btn);
+      }
+      if(!n)grid.innerHTML='<div class="col-span-full text-on-surface-dim text-[10px] italic py-4 text-center">No strategies match your search.</div>';
+    }
+    if(filterEl)filterEl.oninput=render;
+    render();
+  }catch(e){
+    console.error(e);
+    grid.innerHTML='<div class="col-span-full text-error text-[10px] py-3">Could not load strategies. Refresh the page.</div>';
+    if(countEl)countEl.textContent="";
+  }
+}
+
+(function(){const h=document.getElementById("episodeHorizon");if(h)h.textContent=String(EPISODE_DAYS);})();
+loadScenarioButtons();
+loadHistory();
+doReset();
+refreshTaskScoreBlurb();
+</script>
+</body>
+</html>

server/data/audience_overlap_matrix.json

@@ -0,0 +1,17 @@
+{
+  "_meta": {
+    "description": "8x8 symmetric audience overlap matrix between competitor archetypes and the user creator. Values 0.0-1.0 represent fraction of shared audience. Used by propose_collab to compute collab reward multipliers and by query_creator_pool to expose overlap to the agent. Same-niche pairs ~0.4-0.65, cross-niche ~0.05-0.20.",
+    "source": "Competitor pairs estimated from Rival IQ 2025 cross-industry overlap patterns + niche proximity heuristic. user_creator row tuned to a generic micro-creator (no locked niche): broad mass-market partners (lifestyle_blogger, viral_chaser) score highest; specialist partners (b2b_thought_leader, niche_expert) score lowest."
+  },
+  "archetype_ids": ["niche_expert", "viral_chaser", "lifestyle_blogger", "b2b_thought_leader", "food_creator", "fitness_coach", "travel_creator", "user_creator"],
+  "matrix": [
+    [1.00, 0.12, 0.10, 0.40, 0.08, 0.10, 0.15, 0.10],
+    [0.12, 1.00, 0.55, 0.10, 0.20, 0.25, 0.30, 0.35],
+    [0.10, 0.55, 1.00, 0.15, 0.30, 0.35, 0.40, 0.40],
+    [0.40, 0.10, 0.15, 1.00, 0.08, 0.10, 0.12, 0.08],
+    [0.08, 0.20, 0.30, 0.08, 1.00, 0.45, 0.35, 0.25],
+    [0.10, 0.25, 0.35, 0.10, 0.45, 1.00, 0.30, 0.28],
+    [0.15, 0.30, 0.40, 0.12, 0.35, 0.30, 1.00, 0.30],
+    [0.10, 0.35, 0.40, 0.08, 0.25, 0.28, 0.30, 1.00]
+  ]
+}

server/data/audience_segments.json

@@ -0,0 +1,108 @@
+{
+  "_meta": {
+    "description": "5 hidden audience segments the agent discovers via query_audience tool. Based on Pew Research 2024 (teens survey n=1391; adults survey n=5733) and Sprout Social Index 2025 (n=4044 consumers). Agent sees segment names but must query to learn affinities.",
+    "hidden_from_default_obs": true
+  },
+  "segments": [
+    {
+      "id": "young_professionals",
+      "label": "Young Professionals (22-34)",
+      "size_fraction": 0.35,
+      "timezone_peak_offset_hours": 0,
+      "topic_affinity": {
+        "tech": 0.9,
+        "business": 0.8,
+        "lifestyle": 0.6,
+        "fitness": 0.7,
+        "food": 0.5
+      },
+      "content_type_preference": {
+        "reel": 0.9,
+        "carousel": 0.7,
+        "story": 0.8,
+        "text_post": 0.4
+      },
+      "active_hours": [7, 8, 9, 12, 13, 18, 19, 20, 21, 22]
+    },
+    {
+      "id": "students",
+      "label": "Students (16-22)",
+      "size_fraction": 0.25,
+      "timezone_peak_offset_hours": 2,
+      "topic_affinity": {
+        "lifestyle": 0.9,
+        "fitness": 0.6,
+        "education": 0.7,
+        "food": 0.8,
+        "fashion": 0.8
+      },
+      "content_type_preference": {
+        "reel": 1.0,
+        "carousel": 0.5,
+        "story": 0.9,
+        "text_post": 0.2
+      },
+      "active_hours": [10, 11, 12, 13, 14, 15, 20, 21, 22, 23]
+    },
+    {
+      "id": "parents",
+      "label": "Parents (30-45)",
+      "size_fraction": 0.20,
+      "timezone_peak_offset_hours": -1,
+      "topic_affinity": {
+        "food": 0.9,
+        "fitness": 0.7,
+        "lifestyle": 0.8,
+        "education": 0.6,
+        "travel": 0.5
+      },
+      "content_type_preference": {
+        "reel": 0.6,
+        "carousel": 0.9,
+        "story": 0.7,
+        "text_post": 0.6
+      },
+      "active_hours": [6, 7, 8, 12, 13, 20, 21]
+    },
+    {
+      "id": "global_night_owls",
+      "label": "Global Night Owls (mixed age, non-US timezone)",
+      "size_fraction": 0.12,
+      "timezone_peak_offset_hours": 8,
+      "topic_affinity": {
+        "tech": 0.8,
+        "photography": 0.7,
+        "travel": 0.8,
+        "lifestyle": 0.5,
+        "beauty": 0.4
+      },
+      "content_type_preference": {
+        "reel": 0.8,
+        "carousel": 0.8,
+        "story": 0.5,
+        "text_post": 0.5
+      },
+      "active_hours": [0, 1, 2, 3, 14, 15, 16, 17]
+    },
+    {
+      "id": "passive_scrollers",
+      "label": "Passive Scrollers (35-55, low engagement)",
+      "size_fraction": 0.08,
+      "timezone_peak_offset_hours": 0,
+      "topic_affinity": {
+        "travel": 0.6,
+        "food": 0.7,
+        "photography": 0.8,
+        "lifestyle": 0.5,
+        "fashion": 0.4
+      },
+      "content_type_preference": {
+        "reel": 0.4,
+        "carousel": 0.6,
+        "story": 0.3,
+        "text_post": 0.7
+      },
+      "active_hours": [7, 8, 12, 19, 20, 21]
+    }
+  ]
+}

server/data/competitors.json

@@ -0,0 +1,85 @@
+{
+  "_meta": {
+    "description": "7 competitor archetypes. posts_per_week from Buffer 2.1M study (3-5 optimal). base_engagement_rate from Rival IQ 2025 per-industry. posting_frequency is posts/WEEK (divide by 7 for daily probability).",
+    "sources": ["Buffer 2026 frequency study (2.1M posts, 102K accounts)", "Rival IQ 2025 Benchmark (1.9M IG posts, 14 industries)"]
+  },
+  "archetypes": [
+    {
+      "id": "niche_expert",
+      "name": "Creator Alpha (Niche Expert)",
+      "niche": "tech",
+      "niche_topics": ["AI tools", "coding tips", "tech news", "prompt engineering"],
+      "preferred_types": ["carousel", "text_post"],
+      "posts_per_week": 3,
+      "base_engagement_rate": 0.55,
+      "tag_preferences": ["ai", "coding", "devtools", "buildinpublic"],
+      "style": "low_frequency_high_depth"
+    },
+    {
+      "id": "viral_chaser",
+      "name": "Creator Beta (Viral Chaser)",
+      "niche": "lifestyle",
+      "niche_topics": ["morning routine", "self improvement", "productivity hacks", "digital detox"],
+      "preferred_types": ["reel", "story"],
+      "posts_per_week": 7,
+      "base_engagement_rate": 0.38,
+      "tag_preferences": ["viral", "trending", "motivation", "grwm"],
+      "style": "high_frequency_volatile"
+    },
+    {
+      "id": "lifestyle_blogger",
+      "name": "Creator Gamma (Lifestyle Blogger)",
+      "niche": "lifestyle",
+      "niche_topics": ["minimalist living", "slow living", "work life balance", "journaling"],
+      "preferred_types": ["carousel", "reel"],
+      "posts_per_week": 4,
+      "base_engagement_rate": 0.45,
+      "tag_preferences": ["lifestyle", "wellness", "selfcare", "minimalism"],
+      "style": "consistent_moderate"
+    },
+    {
+      "id": "b2b_thought_leader",
+      "name": "Creator Delta (B2B Thought Leader)",
+      "niche": "business",
+      "niche_topics": ["growth hacks", "marketing strategy", "personal branding", "sales funnel"],
+      "preferred_types": ["carousel", "text_post"],
+      "posts_per_week": 3,
+      "base_engagement_rate": 0.42,
+      "tag_preferences": ["entrepreneur", "businesstips", "growth", "leadership"],
+      "style": "low_frequency_high_depth"
+    },
+    {
+      "id": "food_creator",
+      "name": "Creator Epsilon (Food Creator)",
+      "niche": "food",
+      "niche_topics": ["food recipe", "meal prep ideas", "baking tutorial", "food photography"],
+      "preferred_types": ["reel", "carousel"],
+      "posts_per_week": 5,
+      "base_engagement_rate": 0.48,
+      "tag_preferences": ["foodie", "recipe", "cooking", "healthyfood"],
+      "style": "consistent_moderate"
+    },
+    {
+      "id": "fitness_coach",
+      "name": "Creator Zeta (Fitness Coach)",
+      "niche": "fitness",
+      "niche_topics": ["fitness routine", "home workout", "gym transformation", "strength training"],
+      "preferred_types": ["reel", "story"],
+      "posts_per_week": 5,
+      "base_engagement_rate": 0.52,
+      "tag_preferences": ["fitness", "gym", "workout", "fitfam"],
+      "style": "high_frequency_volatile"
+    },
+    {
+      "id": "travel_creator",
+      "name": "Creator Eta (Travel Creator)",
+      "niche": "travel",
+      "niche_topics": ["travel guide", "hidden gems", "travel photography", "digital nomad"],
+      "preferred_types": ["reel", "carousel"],
+      "posts_per_week": 3,
+      "base_engagement_rate": 0.50,
+      "tag_preferences": ["travel", "wanderlust", "adventure", "travelgram"],
+      "style": "low_frequency_high_depth"
+    }
+  ]
+}

server/data/hour_heatmap.json

@@ -0,0 +1,15 @@
+{
+  "_meta": {
+    "description": "7×24 engagement multiplier grid (day_of_week × hour). 1.0 = platform-wide average. Sources: Buffer 2026 (9.6M posts), Sprout Social 2026 (2B engagements, 307K profiles). Days: 0=Mon..6=Sun. Hours: 0-23 local time.",
+    "methodology": "Buffer identified per-day best hours; Sprout provided per-industry peak windows. Cross-referenced: peaks where both agree get 1.3-1.5×; dead zones where both agree get 0.3-0.5×. Intermediate hours interpolated."
+  },
+  "grid": {
+    "0": [0.30, 0.25, 0.25, 0.25, 0.30, 0.35, 0.50, 0.65, 0.80, 0.90, 0.95, 1.00, 1.05, 1.10, 1.20, 1.15, 1.10, 1.05, 1.20, 1.30, 1.25, 1.15, 1.00, 0.60],
+    "1": [0.30, 0.25, 0.25, 0.25, 0.30, 0.35, 0.50, 0.70, 0.85, 0.95, 1.05, 1.10, 1.20, 1.35, 1.40, 1.35, 1.25, 1.20, 1.30, 1.35, 1.25, 1.10, 0.95, 0.55],
+    "2": [0.30, 0.25, 0.25, 0.25, 0.30, 0.35, 0.55, 0.75, 0.95, 1.05, 1.10, 1.15, 1.35, 1.45, 1.45, 1.40, 1.30, 1.25, 1.40, 1.45, 1.40, 1.30, 1.10, 0.60],
+    "3": [0.30, 0.25, 0.25, 0.25, 0.30, 0.35, 0.55, 0.80, 1.05, 1.25, 1.15, 1.10, 1.30, 1.35, 1.30, 1.20, 1.10, 1.05, 1.15, 1.20, 1.10, 1.00, 0.85, 0.50],
+    "4": [0.30, 0.25, 0.25, 0.25, 0.30, 0.35, 0.50, 0.60, 0.70, 0.75, 0.80, 0.80, 0.85, 0.85, 0.80, 0.75, 0.70, 0.65, 0.70, 0.75, 0.70, 0.80, 0.85, 0.50],
+    "5": [0.30, 0.25, 0.25, 0.25, 0.30, 0.30, 0.40, 0.45, 0.50, 0.55, 0.60, 0.60, 0.65, 0.65, 0.60, 0.55, 0.55, 0.50, 0.55, 0.60, 0.65, 0.75, 0.80, 0.50],
+    "6": [0.30, 0.25, 0.25, 0.25, 0.30, 0.30, 0.40, 0.50, 0.55, 0.60, 0.65, 0.70, 0.70, 0.70, 0.65, 0.60, 0.55, 0.55, 0.60, 0.70, 0.80, 0.85, 0.80, 0.55]
+  }
+}

server/data/tags.json

@@ -0,0 +1,149 @@
+{
+  "_meta": {
+    "description": "Instagram tag pool tiered by usage volume. Sources: Rival IQ 2025 Benchmark (1.9M IG posts), Socialinsider 2026 (31M posts).",
+    "tiers": {
+      "broad": "High-volume generic tags (>100M posts). High reach, low engagement lift.",
+      "niche": "Mid-volume vertical tags (1M-100M). Better engagement, narrower audience.",
+      "trending": "Rotated daily by env. Volatile reach bonus.",
+      "seasonal": "Calendar-driven. Active only near their season window."
+    }
+  },
+  "broad": [
+    {"tag": "love", "volume_hint": "2.1B"},
+    {"tag": "instagood", "volume_hint": "1.9B"},
+    {"tag": "photography", "volume_hint": "1.1B"},
+    {"tag": "photooftheday", "volume_hint": "1B"},
+    {"tag": "reels", "volume_hint": "985M"},
+    {"tag": "beautiful", "volume_hint": "854M"},
+    {"tag": "nature", "volume_hint": "838M"},
+    {"tag": "travel", "volume_hint": "767M"},
+    {"tag": "happy", "volume_hint": "728M"},
+    {"tag": "style", "volume_hint": "683M"},
+    {"tag": "fitness", "volume_hint": "560M"},
+    {"tag": "food", "volume_hint": "538M"},
+    {"tag": "life", "volume_hint": "471M"},
+    {"tag": "motivation", "volume_hint": "423M"},
+    {"tag": "art", "volume_hint": "900M"},
+    {"tag": "music", "volume_hint": "491M"},
+    {"tag": "trending", "volume_hint": "350M"},
+    {"tag": "lifestyle", "volume_hint": "340M"},
+    {"tag": "explore", "volume_hint": "330M"},
+    {"tag": "health", "volume_hint": "280M"},
+    {"tag": "design", "volume_hint": "360M"},
+    {"tag": "inspiration", "volume_hint": "400M"},
+    {"tag": "viral", "volume_hint": "200M"},
+    {"tag": "tips", "volume_hint": "180M"},
+    {"tag": "howto", "volume_hint": "120M"}
+  ],
+  "niche": {
+    "tech": [
+      {"tag": "ai", "volume_hint": "85M"},
+      {"tag": "ml", "volume_hint": "12M"},
+      {"tag": "coding", "volume_hint": "45M"},
+      {"tag": "startup", "volume_hint": "38M"},
+      {"tag": "saas", "volume_hint": "4M"},
+      {"tag": "devtools", "volume_hint": "2M"},
+      {"tag": "techreview", "volume_hint": "8M"},
+      {"tag": "artificialintelligence", "volume_hint": "22M"},
+      {"tag": "futuretech", "volume_hint": "5M"},
+      {"tag": "programming", "volume_hint": "30M"},
+      {"tag": "webdev", "volume_hint": "15M"},
+      {"tag": "buildinpublic", "volume_hint": "1.5M"},
+      {"tag": "technews", "volume_hint": "10M"},
+      {"tag": "gadgets", "volume_hint": "18M"}
+    ],
+    "lifestyle": [
+      {"tag": "grwm", "volume_hint": "45M"},
+      {"tag": "wellness", "volume_hint": "65M"},
+      {"tag": "selfcare", "volume_hint": "55M"},
+      {"tag": "minimalism", "volume_hint": "18M"},
+      {"tag": "stoic", "volume_hint": "5M"},
+      {"tag": "productivity", "volume_hint": "25M"},
+      {"tag": "mentalhealth", "volume_hint": "40M"},
+      {"tag": "healthylifestyle", "volume_hint": "80M"},
+      {"tag": "luxurylifestyle", "volume_hint": "30M"},
+      {"tag": "goodlife", "volume_hint": "20M"}
+    ],
+    "fitness": [
+      {"tag": "gym", "volume_hint": "120M"},
+      {"tag": "workout", "volume_hint": "95M"},
+      {"tag": "fitfam", "volume_hint": "55M"},
+      {"tag": "bodybuilding", "volume_hint": "42M"},
+      {"tag": "running", "volume_hint": "38M"},
+      {"tag": "yoga", "volume_hint": "60M"},
+      {"tag": "fitover40", "volume_hint": "2M"},
+      {"tag": "homeworkout", "volume_hint": "15M"},
+      {"tag": "gymlife", "volume_hint": "35M"},
+      {"tag": "nutrition", "volume_hint": "28M"}
+    ],
+    "business": [
+      {"tag": "entrepreneur", "volume_hint": "90M"},
+      {"tag": "smallbusiness", "volume_hint": "75M"},
+      {"tag": "businesstips", "volume_hint": "20M"},
+      {"tag": "sidehustle", "volume_hint": "15M"},
+      {"tag": "growyourbusiness", "volume_hint": "10M"},
+      {"tag": "financialfreedom", "volume_hint": "18M"},
+      {"tag": "passiveincome", "volume_hint": "12M"},
+      {"tag": "growth", "volume_hint": "45M"},
+      {"tag": "leadership", "volume_hint": "22M"},
+      {"tag": "digitalmarketing", "volume_hint": "35M"}
+    ],
+    "food": [
+      {"tag": "foodie", "volume_hint": "110M"},
+      {"tag": "recipe", "volume_hint": "55M"},
+      {"tag": "healthyfood", "volume_hint": "65M"},
+      {"tag": "cooking", "volume_hint": "45M"},
+      {"tag": "mealprep", "volume_hint": "18M"},
+      {"tag": "vegan", "volume_hint": "40M"},
+      {"tag": "baking", "volume_hint": "30M"}
+    ],
+    "travel": [
+      {"tag": "wanderlust", "volume_hint": "85M"},
+      {"tag": "travelgram", "volume_hint": "70M"},
+      {"tag": "adventure", "volume_hint": "60M"},
+      {"tag": "backpacking", "volume_hint": "20M"},
+      {"tag": "roadtrip", "volume_hint": "25M"},
+      {"tag": "solotravel", "volume_hint": "12M"},
+      {"tag": "islandlife", "volume_hint": "15M"}
+    ],
+    "fashion": [
+      {"tag": "ootd", "volume_hint": "95M"},
+      {"tag": "fashionblogger", "volume_hint": "65M"},
+      {"tag": "streetstyle", "volume_hint": "40M"},
+      {"tag": "skincare", "volume_hint": "55M"},
+      {"tag": "makeup", "volume_hint": "80M"}
+    ],
+    "web3": [
+      {"tag": "web3", "volume_hint": "8M"},
+      {"tag": "crypto", "volume_hint": "35M"},
+      {"tag": "nft", "volume_hint": "25M"},
+      {"tag": "blockchain", "volume_hint": "18M"},
+      {"tag": "defi", "volume_hint": "5M"},
+      {"tag": "gaming", "volume_hint": "50M"}
+    ]
+  },
+  "trending": [
+    {"tag": "aitools2026", "volume_hint": "3M"},
+    {"tag": "techtrends2026", "volume_hint": "2M"},
+    {"tag": "chatgpt", "volume_hint": "15M"},
+    {"tag": "midjourney", "volume_hint": "8M"},
+    {"tag": "threads", "volume_hint": "12M"},
+    {"tag": "climateaction", "volume_hint": "6M"},
+    {"tag": "genai", "volume_hint": "4M"},
+    {"tag": "remotework", "volume_hint": "18M"},
+    {"tag": "creatoreconomy", "volume_hint": "5M"},
+    {"tag": "sustainableliving", "volume_hint": "10M"}
+  ],
+  "seasonal": [
+    {"tag": "summer", "volume_hint": "300M", "active_months": [5, 6, 7, 8]},
+    {"tag": "newyear", "volume_hint": "150M", "active_months": [12, 1]},
+    {"tag": "worldcup", "volume_hint": "80M", "active_months": [6, 7]},
+    {"tag": "oscars", "volume_hint": "45M", "active_months": [2, 3]},
+    {"tag": "election", "volume_hint": "60M", "active_months": [10, 11]},
+    {"tag": "blackfriday", "volume_hint": "55M", "active_months": [11]},
+    {"tag": "christmas", "volume_hint": "200M", "active_months": [11, 12]},
+    {"tag": "backtoschool", "volume_hint": "30M", "active_months": [8, 9]},
+    {"tag": "valentines", "volume_hint": "70M", "active_months": [1, 2]},
+    {"tag": "halloween", "volume_hint": "90M", "active_months": [10]}
+  ]
+}

server/data/topics.json

@@ -0,0 +1,102 @@
+{
+  "_meta": {
+    "description": "Niche → topics with engagement multipliers and seasonal trending calendar. Multipliers from Rival IQ 2025 Benchmark (1.9M IG posts, 14 industries). Normalized so overall avg ≈ 1.0.",
+    "multiplier_source": "Rival IQ 2025: Animals 2.00%, Photo 1.99%, Outdoors 1.91%, Travel 1.83%, Sports/Fitness 1.75%, Music 1.63%, Entertainment 1.55%, Food 1.55%, Lifestyle 1.53%, Education 1.48%, Finance 1.34%, Tech 1.31%, Real Estate 1.25%, Fashion 1.24%, Beauty 1.19%. Normalized by dividing by median (1.53)."
+  },
+  "niches": {
+    "tech": {
+      "engagement_multiplier": 0.86,
+      "topics": [
+        "AI tools", "coding tips", "startup life", "tech news",
+        "SaaS growth", "dev workflow", "open source", "gadget review",
+        "prompt engineering", "AI art"
+      ]
+    },
+    "lifestyle": {
+      "engagement_multiplier": 1.00,
+      "topics": [
+        "morning routine", "minimalist living", "self improvement",
+        "productivity hacks", "mental health", "stoic philosophy",
+        "journaling", "digital detox", "work life balance", "slow living"
+      ]
+    },
+    "fitness": {
+      "engagement_multiplier": 1.14,
+      "topics": [
+        "fitness routine", "home workout", "running tips",
+        "gym transformation", "meal prep", "yoga flow",
+        "strength training", "recovery", "marathon training", "calisthenics"
+      ]
+    },
+    "business": {
+      "engagement_multiplier": 0.88,
+      "topics": [
+        "growth hacks", "marketing strategy", "creator economy",
+        "monetization", "brand deals", "analytics deep dive",
+        "side hustle", "personal branding", "email marketing", "sales funnel"
+      ]
+    },
+    "food": {
+      "engagement_multiplier": 1.01,
+      "topics": [
+        "food recipe", "meal prep ideas", "restaurant review",
+        "baking tutorial", "healthy eating", "vegan recipes",
+        "street food", "coffee culture", "kitchen hacks", "food photography"
+      ]
+    },
+    "travel": {
+      "engagement_multiplier": 1.20,
+      "topics": [
+        "travel guide", "hidden gems", "budget travel",
+        "solo travel tips", "road trip", "beach destinations",
+        "cultural immersion", "travel photography", "hostel life", "digital nomad"
+      ]
+    },
+    "fashion": {
+      "engagement_multiplier": 0.81,
+      "topics": [
+        "fashion haul", "outfit of the day", "streetwear",
+        "sustainable fashion", "thrift finds", "seasonal trends",
+        "capsule wardrobe", "accessory styling", "luxury fashion", "sneaker culture"
+      ]
+    },
+    "beauty": {
+      "engagement_multiplier": 0.78,
+      "topics": [
+        "skincare routine", "makeup tutorial", "hair care",
+        "clean beauty", "anti aging", "nail art",
+        "fragrance review", "dermatologist tips", "glow up", "beauty on budget"
+      ]
+    },
+    "photography": {
+      "engagement_multiplier": 1.30,
+      "topics": [
+        "photo editing", "golden hour shots", "street photography",
+        "landscape photography", "portrait tips", "mobile photography",
+        "lightroom presets", "composition rules", "astrophotography", "film photography"
+      ]
+    },
+    "education": {
+      "engagement_multiplier": 0.97,
+      "topics": [
+        "study tips", "online courses", "career advice",
+        "book recommendations", "science explainer", "history facts",
+        "language learning", "financial literacy", "college life", "exam prep"
+      ]
+    }
+  },
+  "seasonal_trends": [
+    {"topic": "New Year goals", "peak_month": 1, "halflife_hours": 72, "niches": ["lifestyle", "fitness", "business"]},
+    {"topic": "Valentine gift guide", "peak_month": 2, "halflife_hours": 48, "niches": ["fashion", "food", "lifestyle"]},
+    {"topic": "Oscar predictions", "peak_month": 3, "halflife_hours": 36, "niches": ["lifestyle", "photography"]},
+    {"topic": "Spring fitness challenge", "peak_month": 4, "halflife_hours": 96, "niches": ["fitness"]},
+    {"topic": "Summer travel plans", "peak_month": 6, "halflife_hours": 120, "niches": ["travel", "photography"]},
+    {"topic": "World Cup watch party", "peak_month": 7, "halflife_hours": 60, "niches": ["lifestyle", "food"]},
+    {"topic": "Back to school essentials", "peak_month": 8, "halflife_hours": 72, "niches": ["education", "tech", "fashion"]},
+    {"topic": "Fall fashion lookbook", "peak_month": 9, "halflife_hours": 96, "niches": ["fashion", "beauty"]},
+    {"topic": "Halloween costumes", "peak_month": 10, "halflife_hours": 48, "niches": ["fashion", "lifestyle", "food"]},
+    {"topic": "Black Friday deals", "peak_month": 11, "halflife_hours": 36, "niches": ["tech", "business", "fashion"]},
+    {"topic": "Holiday gift guide", "peak_month": 12, "halflife_hours": 96, "niches": ["tech", "fashion", "food", "beauty"]},
+    {"topic": "Year in review", "peak_month": 12, "halflife_hours": 48, "niches": ["lifestyle", "business", "photography"]}
+  ]
+}

server/requirements.txt

@@ -0,0 +1,6 @@
+openenv[core]>=0.2.0
+fastapi>=0.115.0
+uvicorn>=0.24.0
+
+
+

server/simulation_history.json

@@ -0,0 +1 @@
+[]

server/training.html

@@ -0,0 +1,369 @@
+<!DOCTYPE html>
+<html class="dark" lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta content="width=device-width,initial-scale=1.0" name="viewport"/>
+<title>Viraltest — Training Evidence</title>
+<script src="https://cdn.tailwindcss.com?plugins=forms,container-queries"></script>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800;900&family=Space+Grotesk:wght@400;500;700&display=swap" rel="stylesheet"/>
+<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght,FILL@100..700,0..1&display=swap" rel="stylesheet"/>
+<script>
+tailwind.config={darkMode:"class",theme:{extend:{colors:{"surface":"#0b1326","surface-low":"#131b2e","surface-high":"#222a3d","surface-top":"#2d3449","surface-lowest":"#060e20","on-surface":"#dae2fd","on-surface-dim":"#cbc3d7","primary":"#d0bcff","primary-ctr":"#a078ff","secondary":"#7bd0ff","secondary-ctr":"#00a6e0","tertiary":"#ffb2b9","tertiary-ctr":"#ea6479","outline":"#494454","error":"#ffb4ab"},fontFamily:{headline:["Inter"],body:["Inter"],label:["Space Grotesk"]}}}}
+</script>
+<style>
+body{background:#0b1326;color:#dae2fd;font-family:'Inter',sans-serif}
+.material-symbols-outlined{font-variation-settings:'FILL' 0,'wght' 400,'GRAD' 0,'opsz' 24}
+.glass-solid{background:#131b2e;border:1px solid rgba(73,68,84,.15)}
+.fade-in{animation:fadeIn .3s ease}
+@keyframes fadeIn{from{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}
+::-webkit-scrollbar{width:6px}
+::-webkit-scrollbar-track{background:transparent}
+::-webkit-scrollbar-thumb{background:rgba(73,68,84,.4);border-radius:3px}
+</style>
+</head>
+<body class="min-h-screen flex">
+
+<aside class="flex flex-col sticky top-0 h-screen w-64 border-r border-white/5 bg-surface-lowest shadow-2xl shadow-slate-950/50 shrink-0 z-50">
+  <div class="p-6 pb-4">
+    <div class="text-xl font-black tracking-tighter text-transparent bg-clip-text bg-gradient-to-br from-primary to-primary-ctr mb-1">Growth Copilot</div>
+    <div class="text-[9px] font-label uppercase tracking-[.2em] text-on-surface-dim/50">Training evidence</div>
+  </div>
+  <nav class="flex-1 px-3 space-y-1">
+    <a href="/dashboard" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-slate-400 font-medium hover:text-slate-200 hover:bg-white/5 transition-all">
+      <span class="material-symbols-outlined text-[20px]">dashboard</span><span class="font-label text-sm">Dashboard</span>
+    </a>
+    <a href="/dashboard/training" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-primary font-bold border-r-2 border-primary bg-gradient-to-r from-primary/10 to-transparent transition-all">
+      <span class="material-symbols-outlined text-[20px]">science</span><span class="font-label text-sm">Training Evidence</span>
+    </a>
+    <a href="/web/" class="flex items-center gap-3 px-4 py-2.5 rounded-lg text-slate-400 font-medium hover:text-slate-200 hover:bg-white/5 transition-all">
+      <span class="material-symbols-outlined text-[20px]">web</span><span class="font-label text-sm">OpenEnv UI</span>
+    </a>
+  </nav>
+  <div class="p-4 border-t border-white/5">
+    <div class="text-[9px] font-label text-on-surface-dim/60 leading-relaxed">
+      This page shows that the environment can <span class="text-on-surface font-bold">differentiate agent strategies</span> and produce meaningful reward signals for RL training.
+    </div>
+  </div>
+</aside>
+
+<div class="flex-1 flex flex-col min-w-0">
+  <header class="flex justify-between items-center px-6 h-14 border-b border-white/5 bg-surface/60 backdrop-blur-xl sticky top-0 z-40">
+    <div class="flex items-center gap-3">
+      <span class="material-symbols-outlined text-primary text-lg">science</span>
+      <h1 class="text-sm font-bold">Training Evidence — Baseline Leaderboard</h1>
+    </div>
+    <div class="flex items-center gap-3">
+      <span id="statusBadge" class="text-xs font-label text-on-surface-dim">Click "Run Baselines" to generate</span>
+      <button onclick="runBaselines()" id="runBtn" class="px-4 py-2 rounded-lg bg-gradient-to-br from-primary to-primary-ctr text-[#23005c] font-bold text-sm hover:opacity-90 transition active:scale-[.97]">
+        <span class="material-symbols-outlined text-[16px] align-middle mr-1">play_arrow</span>Run Baselines
+      </button>
+    </div>
+  </header>
+
+  <main class="flex-1 p-6 space-y-6 overflow-y-auto">
+
+    <div class="glass-solid border border-outline/20 rounded-xl px-5 py-4 space-y-3">
+      <div class="flex gap-3 items-start">
+        <span class="material-symbols-outlined text-primary text-lg shrink-0">info</span>
+        <div class="text-[11px] font-label text-on-surface-dim leading-relaxed flex-1 min-w-0">
+          <span class="text-on-surface font-semibold">What this proves:</span>
+          The environment produces a <span class="text-on-surface">rich, informative reward signal</span> that differentiates between agent strategies.
+          Smart agents (peak-hour posting, tag diversity, energy management) consistently outscore naive baselines (spam, random, always-rest).
+          This is the prerequisite for RL training &mdash; if the reward didn't differentiate, training couldn't improve behavior.
+          <div class="mt-2 text-on-surface font-semibold">5 heuristic strategies &times; 3 tasks = 15 runs, deterministic (seed=42).</div>
+        </div>
+      </div>
+    </div>
+
+    <div id="loadingState" class="hidden">
+      <div class="flex items-center justify-center gap-4 py-12">
+        <div class="animate-spin h-8 w-8 border-4 border-primary/30 border-t-primary rounded-full"></div>
+        <span class="text-sm font-label text-on-surface-dim">Running all baseline scenarios... (~5 seconds)</span>
+      </div>
+    </div>
+
+    <div id="resultsSection" class="hidden space-y-6">
+
+      <div class="grid grid-cols-1 lg:grid-cols-3 gap-5">
+        <div id="chart_engage" class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-1 text-secondary">Engage (Easy)</h3>
+          <p class="text-[9px] font-label text-on-surface-dim mb-3">Total engagement vs theoretical max</p>
+          <svg id="svg_engage" class="w-full" viewBox="0 0 380 240" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div id="chart_strategic" class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-1 text-primary">Strategic (Medium)</h3>
+          <p class="text-[9px] font-label text-on-surface-dim mb-3">Engagement + tag discovery + energy + consistency</p>
+          <svg id="svg_strategic" class="w-full" viewBox="0 0 380 240" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+        <div id="chart_competitive" class="glass-solid p-5 rounded-xl overflow-hidden">
+          <h3 class="text-sm font-bold mb-1 text-tertiary">Competitive (Hard)</h3>
+          <p class="text-[9px] font-label text-on-surface-dim mb-3">+ growth vs competitors + differentiation</p>
+          <svg id="svg_competitive" class="w-full" viewBox="0 0 380 240" preserveAspectRatio="xMidYMid meet"></svg>
+        </div>
+      </div>
+
+      <div class="glass-solid p-5 rounded-xl overflow-hidden">
+        <h3 class="text-sm font-bold mb-1 flex items-center gap-2">
+          <span class="material-symbols-outlined text-secondary text-lg">show_chart</span>
+          Reward Trajectories (30-day episodes)
+        </h3>
+        <p class="text-[9px] font-label text-on-surface-dim mb-3">Daily reward over the episode for each agent &times; task. Shows that smart strategies maintain higher rewards throughout.</p>
+        <div class="grid grid-cols-1 lg:grid-cols-3 gap-4">
+          <div>
+            <div class="text-[10px] font-bold text-secondary uppercase tracking-widest mb-1">Engage</div>
+            <svg id="traj_engage" class="w-full" viewBox="0 0 400 180" preserveAspectRatio="xMidYMid meet"></svg>
+          </div>
+          <div>
+            <div class="text-[10px] font-bold text-primary uppercase tracking-widest mb-1">Strategic</div>
+            <svg id="traj_strategic" class="w-full" viewBox="0 0 400 180" preserveAspectRatio="xMidYMid meet"></svg>
+          </div>
+          <div>
+            <div class="text-[10px] font-bold text-tertiary uppercase tracking-widest mb-1">Competitive</div>
+            <svg id="traj_competitive" class="w-full" viewBox="0 0 400 180" preserveAspectRatio="xMidYMid meet"></svg>
+          </div>
+        </div>
+        <div id="trajectoryLegend" class="flex flex-wrap gap-4 mt-3 justify-center"></div>
+      </div>
+
+      <div class="glass-solid rounded-xl overflow-hidden">
+        <div class="p-4 border-b border-white/5">
+          <h3 class="text-sm font-bold flex items-center gap-2">
+            <span class="material-symbols-outlined text-primary text-lg">table_chart</span>
+            Full Results Table
+          </h3>
+        </div>
+        <div class="overflow-x-auto">
+          <table class="w-full text-[11px] font-label">
+            <thead>
+              <tr class="text-on-surface-dim/60 uppercase tracking-wider border-b border-white/5">
+                <th class="text-left px-4 py-2.5">Agent</th>
+                <th class="text-left px-4 py-2.5">Task</th>
+                <th class="text-right px-4 py-2.5">Grader Score</th>
+                <th class="text-right px-4 py-2.5">Total Reward</th>
+                <th class="text-right px-4 py-2.5">Steps</th>
+                <th class="text-right px-4 py-2.5">Energy</th>
+                <th class="text-right px-4 py-2.5">Followers</th>
+                <th class="text-right px-4 py-2.5">&Delta;</th>
+                <th class="text-center px-4 py-2.5">Status</th>
+              </tr>
+            </thead>
+            <tbody id="resultsTable"></tbody>
+          </table>
+        </div>
+      </div>
+
+      <div class="glass-solid p-5 rounded-xl overflow-hidden">
+        <h3 class="text-sm font-bold mb-3 flex items-center gap-2">
+          <span class="material-symbols-outlined text-tertiary text-lg">insights</span>
+          Key Takeaways
+        </h3>
+        <div id="takeaways" class="space-y-2 text-[11px] font-label text-on-surface-dim leading-relaxed"></div>
+      </div>
+    </div>
+
+  </main>
+</div>
+
+<script>
+const API=window.location.origin;
+const COLORS={"always_rest":"#E53935","spam":"#FF9800","random":"#9E9E9E","minimal":"#42A5F5","smart":"#4CAF50"};
+const TASK_MAP={"monthly_engage":"engage","monthly_strategic":"strategic","monthly_competitive":"competitive"};
+const TASK_LABELS={"monthly_engage":"Engage","monthly_strategic":"Strategic","monthly_competitive":"Competitive"};
+
+let allData=null;
+
+async function runBaselines(){
+  const btn=document.getElementById("runBtn");
+  btn.disabled=true;btn.classList.add("opacity-50");
+  document.getElementById("loadingState").classList.remove("hidden");
+  document.getElementById("resultsSection").classList.add("hidden");
+  document.getElementById("statusBadge").textContent="Running...";
+
+  try{
+    const r=await fetch(API+"/dashboard/training-evidence");
+    allData=await r.json();
+    renderAll();
+    document.getElementById("loadingState").classList.add("hidden");
+    document.getElementById("resultsSection").classList.remove("hidden");
+    document.getElementById("statusBadge").textContent=`${allData.results.length} runs completed`;
+  }catch(e){
+    document.getElementById("statusBadge").textContent="Error: "+e.message;
+    document.getElementById("loadingState").classList.add("hidden");
+  }
+  btn.disabled=false;btn.classList.remove("opacity-50");
+}
+
+function renderAll(){
+  if(!allData)return;
+  renderBarCharts();
+  renderTrajectories();
+  renderTable();
+  renderTakeaways();
+}
+
+function renderBarCharts(){
+  const tasks=["monthly_engage","monthly_strategic","monthly_competitive"];
+  for(const task of tasks){
+    const key=TASK_MAP[task];
+    const svg=document.getElementById("svg_"+key);
+    if(!svg)continue;
+
+    const taskResults=allData.results.filter(r=>r.task===task);
+    taskResults.sort((a,b)=>b.grader_score-a.grader_score);
+
+    const W=380,H=240,pL=110,pR=60,pT=10,pB=10;
+    const plotW=W-pL-pR,plotH=H-pT-pB;
+    const n=taskResults.length;
+    if(!n){svg.innerHTML="";continue;}
+    const barH=Math.min(28,plotH/n*0.7);
+    const gap=(plotH-barH*n)/(n+1);
+    const maxScore=Math.max(...taskResults.map(r=>r.grader_score),0.01);
+
+    let html="";
+    taskResults.forEach((r,i)=>{
+      const y=pT+gap+(barH+gap)*i;
+      const w=Math.max(2,(r.grader_score/Math.max(maxScore*1.1,0.01))*plotW);
+      const color=COLORS[r.scenario_id]||"#9E9E9E";
+      const burned=r.burned_out?" (BURNED)":"";
+
+      html+=`<rect x="${pL}" y="${y}" width="${w}" height="${barH}" fill="${color}" rx="4" opacity="0.85"/>`;
+      html+=`<text x="${pL-6}" y="${y+barH/2+4}" text-anchor="end" fill="#dae2fd" font-size="10" font-family="Space Grotesk,sans-serif" font-weight="600">${r.scenario}</text>`;
+      html+=`<text x="${pL+w+6}" y="${y+barH/2+4}" fill="${color}" font-size="11" font-family="Space Grotesk,sans-serif" font-weight="700">${r.grader_score.toFixed(4)}${burned}</text>`;
+    });
+
+    svg.innerHTML=html;
+  }
+}
+
+function smoothPath(pts){
+  if(pts.length<2)return pts.map((p,i)=>(i===0?"M":"L")+p.x.toFixed(1)+","+p.y.toFixed(1)).join(" ");
+  let d="M"+pts[0].x.toFixed(1)+","+pts[0].y.toFixed(1);
+  for(let i=1;i<pts.length;i++){
+    const cp=(pts[i].x-pts[i-1].x)/3;
+    d+=` C${(pts[i-1].x+cp).toFixed(1)},${pts[i-1].y.toFixed(1)} ${(pts[i].x-cp).toFixed(1)},${pts[i].y.toFixed(1)} ${pts[i].x.toFixed(1)},${pts[i].y.toFixed(1)}`;
+  }
+  return d;
+}
+
+function renderTrajectories(){
+  const tasks=["monthly_engage","monthly_strategic","monthly_competitive"];
+  const legend=document.getElementById("trajectoryLegend");
+  let legendHtml="";
+
+  for(const task of tasks){
+    const key=TASK_MAP[task];
+    const svg=document.getElementById("traj_"+key);
+    if(!svg)continue;
+
+    const taskResults=allData.results.filter(r=>r.task===task);
+    const W=400,H=180,pL=40,pR=10,pT=10,pB=30;
+    const plotW=W-pL-pR,plotH=H-pT-pB;
+
+    let allRewards=[];
+    taskResults.forEach(r=>allRewards.push(...r.rewards));
+    const minR=Math.min(0,...allRewards);
+    const maxR=Math.max(...allRewards,0.01);
+
+    let html="";
+    for(let g=0;g<=4;g++){
+      const y=pT+(g/4)*plotH;
+      const val=maxR-(g/4)*(maxR-minR);
+      html+=`<line x1="${pL}" y1="${y}" x2="${W-pR}" y2="${y}" stroke="#494454" stroke-width="0.5" opacity="0.3"/>`;
+      html+=`<text x="${pL-5}" y="${y+3}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">${val.toFixed(2)}</text>`;
+    }
+    html+=`<line x1="${pL}" y1="${pT}" x2="${pL}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.7"/>`;
+    html+=`<line x1="${pL}" y1="${H-pB}" x2="${W-pR}" y2="${H-pB}" stroke="#cbc3d7" stroke-width="0.7"/>`;
+    html+=`<text x="${pL}" y="${H-10}" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">Day 1</text>`;
+    html+=`<text x="${W-pR}" y="${H-10}" text-anchor="end" fill="#958ea0" font-size="8" font-family="Space Grotesk,sans-serif">Day 30</text>`;
+    html+=`<text x="${pL+plotW/2}" y="${H-2}" text-anchor="middle" fill="#958ea0" font-size="7" font-family="Space Grotesk,sans-serif" opacity="0.75">day</text>`;
+
+    taskResults.forEach(r=>{
+      const color=COLORS[r.scenario_id]||"#9E9E9E";
+      const rewards=r.rewards;
+      const n=rewards.length;
+      if(!n)return;
+      const pts=rewards.map((v,i)=>({
+        x:pL+(n<=1?plotW/2:i/(n-1)*plotW),
+        y:pT+(1-((v-minR)/(maxR-minR||1)))*plotH,
+      }));
+      const lineD=smoothPath(pts);
+      const opacity=r.scenario_id==="smart"?"1":"0.6";
+      const width=r.scenario_id==="smart"?"2.5":"1.5";
+      html+=`<path d="${lineD}" fill="none" stroke="${color}" stroke-width="${width}" opacity="${opacity}"/>`;
+    });
+
+    svg.innerHTML=html;
+  }
+
+  const scenarios=[...new Set(allData.results.map(r=>r.scenario_id))];
+  legendHtml=scenarios.map(sid=>{
+    const label=allData.results.find(r=>r.scenario_id===sid)?.scenario||sid;
+    const color=COLORS[sid]||"#9E9E9E";
+    return `<div class="flex items-center gap-1.5"><span class="w-3 h-1 rounded-full" style="background:${color}"></span><span class="text-[10px] font-label text-on-surface-dim">${label}</span></div>`;
+  }).join("");
+  legend.innerHTML=legendHtml;
+}
+
+function renderTable(){
+  const tb=document.getElementById("resultsTable");
+  const rows=allData.results.slice().sort((a,b)=>{
+    const taskOrder={"monthly_engage":0,"monthly_strategic":1,"monthly_competitive":2};
+    if(taskOrder[a.task]!==taskOrder[b.task])return taskOrder[a.task]-taskOrder[b.task];
+    return b.grader_score-a.grader_score;
+  });
+
+  tb.innerHTML=rows.map(r=>{
+    const color=COLORS[r.scenario_id]||"#9E9E9E";
+    const scoreColor=r.grader_score>=0.5?"text-primary":r.grader_score>=0.2?"text-secondary":"text-tertiary";
+    const energyColor=r.final_energy>=0.5?"text-secondary":r.final_energy>0?"text-tertiary":"text-error";
+    const deltaColor=r.follower_delta>0?"text-secondary":r.follower_delta<0?"text-tertiary":"text-on-surface-dim";
+    const status=r.burned_out?'<span class="text-tertiary font-bold">BURNED</span>':r.steps>=30?'<span class="text-secondary">DONE</span>':'<span class="text-on-surface-dim">EARLY</span>';
+    return `<tr class="border-b border-white/5 hover:bg-white/[.02]">
+      <td class="px-4 py-2"><div class="flex items-center gap-2"><span class="w-2 h-2 rounded-full" style="background:${color}"></span><span class="text-on-surface font-bold">${r.scenario}</span></div></td>
+      <td class="px-4 py-2 text-on-surface-dim">${TASK_LABELS[r.task]||r.task}</td>
+      <td class="px-4 py-2 text-right ${scoreColor} font-bold">${r.grader_score.toFixed(4)}</td>
+      <td class="px-4 py-2 text-right text-on-surface-dim">${r.total_reward.toFixed(3)}</td>
+      <td class="px-4 py-2 text-right text-on-surface-dim">${r.steps}</td>
+      <td class="px-4 py-2 text-right ${energyColor}">${r.final_energy.toFixed(2)}</td>
+      <td class="px-4 py-2 text-right text-on-surface">${r.final_followers.toLocaleString()}</td>
+      <td class="px-4 py-2 text-right ${deltaColor}">${r.follower_delta>=0?"+":""}${r.follower_delta}</td>
+      <td class="px-4 py-2 text-center">${status}</td>
+    </tr>`;
+  }).join("");
+}
+
+function renderTakeaways(){
+  const el=document.getElementById("takeaways");
+  if(!allData)return;
+
+  const byScenario={};
+  allData.results.forEach(r=>{
+    if(!byScenario[r.scenario_id])byScenario[r.scenario_id]={scores:[],label:r.scenario};
+    byScenario[r.scenario_id].scores.push(r.grader_score);
+  });
+
+  const avgs=Object.entries(byScenario).map(([id,d])=>({
+    id,label:d.label,avg:d.scores.reduce((a,b)=>a+b,0)/d.scores.length
+  })).sort((a,b)=>b.avg-a.avg);
+
+  const best=avgs[0];
+  const worst=avgs[avgs.length-1];
+  const ratio=worst.avg>0?(best.avg/worst.avg).toFixed(1):"∞";
+
+  const burnedOut=allData.results.filter(r=>r.burned_out);
+  const completed=allData.results.filter(r=>!r.burned_out&&r.steps>=30);
+
+  const points=[
+    `<span class="text-on-surface font-bold">Best agent: ${best.label}</span> (avg score ${best.avg.toFixed(4)}) — ${ratio}× better than worst (${worst.label}, avg ${worst.avg.toFixed(4)}).`,
+    `<span class="text-on-surface font-bold">Score spread:</span> The environment produces a ${(avgs[0].avg-avgs[avgs.length-1].avg).toFixed(4)} spread between best and worst agents, proving the reward is informative and not flat.`,
+    `<span class="text-on-surface font-bold">${burnedOut.length} burnout events</span> across ${allData.results.length} runs — the burnout penalty correctly punishes unsustainable strategies (spam, no-rest).`,
+    `<span class="text-on-surface font-bold">${completed.length}/${allData.results.length} episodes completed</span> all 30 days — agents that manage energy survive; those that don't burn out early.`,
+    `<span class="text-on-surface font-bold">Reward is hard to game:</span> Spamming posts burns out immediately (score ≈ 0). Always resting loses followers. The optimal strategy requires balancing multiple objectives.`,
+    `<span class="text-on-surface font-bold">Grader difficulty scales correctly:</span> All agents score lower on Competitive than on Engage, confirming the three-tier difficulty progression works.`,
+  ];
+
+  el.innerHTML=points.map(p=>`<div class="flex gap-2"><span class="text-primary shrink-0">▸</span><span>${p}</span></div>`).join("");
+}
+</script>
+</body>
+</html>

server/viraltest_environment.py

@@ -0,0 +1,1313 @@
+"""
+Viraltest Environment v2 — Theme #3.1 World-Modeling Simulation.
+
+30-day creator optimization with:
+- Mosseri-aligned engagement signals (watch_time, sends, saves, likes)
+- Discoverable tool catalog (partial observability)
+- Piecewise-linear sleep model (Van Dongen 2003)
+- Data-driven hour heatmap (Buffer 9.6M + Sprout 2B)
+- Tiered audience fatigue (Buffer 2.1M)
+- Multi-episode brand persistence
+- Counterfactual coach feedback
+"""
+
+import json
+import math
+import random
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import uuid4
+
+from openenv.core.env_server.interfaces import Environment
+from openenv.core.env_server.types import State
+
+try:
+    from ..models import (
+        CollabProposal,
+        EngagementSignals,
+        HeadlineMetrics,
+        JudgeReport,
+        ReplyAction,
+        ScheduledAction,
+        ToolCall,
+        ToolResult,
+        ViraltestAction,
+        ViraltestObservation,
+    )
+except ImportError:
+    from models import (
+        CollabProposal,
+        EngagementSignals,
+        HeadlineMetrics,
+        JudgeReport,
+        ReplyAction,
+        ScheduledAction,
+        ToolCall,
+        ToolResult,
+        ViraltestAction,
+        ViraltestObservation,
+    )
+
+_DATA_DIR = Path(__file__).parent / "data"
+
+def _load_json(name: str) -> Any:
+    return json.loads((_DATA_DIR / name).read_text())
+
+# ---------------------------------------------------------------------------
+# Data files (loaded once at module level)
+# ---------------------------------------------------------------------------
+
+_TAGS_DATA = _load_json("tags.json")
+_TOPICS_DATA = _load_json("topics.json")
+_COMPETITORS_DATA = _load_json("competitors.json")
+_HEATMAP_DATA = _load_json("hour_heatmap.json")
+_AUDIENCE_DATA = _load_json("audience_segments.json")
+_OVERLAP_DATA = _load_json("audience_overlap_matrix.json")
+
+# Flatten tag pool for validation
+TAG_POOL: List[str] = []
+for t in _TAGS_DATA.get("broad", []):
+    TAG_POOL.append(t["tag"])
+for _cat, tags in _TAGS_DATA.get("niche", {}).items():
+    for t in tags:
+        TAG_POOL.append(t["tag"])
+for t in _TAGS_DATA.get("trending", []):
+    TAG_POOL.append(t["tag"])
+for t in _TAGS_DATA.get("seasonal", []):
+    TAG_POOL.append(t["tag"])
+
+TOPIC_CATEGORIES: Dict[str, List[str]] = {}
+for niche_name, niche_data in _TOPICS_DATA.get("niches", {}).items():
+    TOPIC_CATEGORIES[niche_name] = niche_data["topics"]
+
+_NICHE_MULTIPLIERS: Dict[str, float] = {}
+for niche_name, niche_data in _TOPICS_DATA.get("niches", {}).items():
+    _NICHE_MULTIPLIERS[niche_name] = niche_data["engagement_multiplier"]
+
+_HEATMAP_GRID: Dict[int, List[float]] = {
+    int(k): v for k, v in _HEATMAP_DATA.get("grid", {}).items()
+}
+
+# ---------------------------------------------------------------------------
+# Constants (research-backed, Tier 1-3 sources)
+# ---------------------------------------------------------------------------
+
+TASK_HORIZON = 30  # 30 daily steps (monthly cycle)
+
+# Socialinsider 2026 (31M posts)
+CONTENT_ENERGY_COST = {
+    "reel": 0.25,
+    "carousel": 0.20,
+    "story": 0.08,
+    "text_post": 0.06,
+}
+
+BASE_ENGAGEMENT = {
+    "reel": 0.52,
+    "carousel": 0.55,
+    "story": 0.30,
+    "text_post": 0.45,
+}
+
+# Socialinsider 2026 + CreatorsJet 10K study
+REACH_MULT = {
+    "reel": 2.25,
+    "carousel": 1.0,
+    "story": 0.5,
+    "text_post": 0.91,
+}
+
+# Mosseri Jan-2025: format→signal affinity (which signal each format naturally excels at)
+FORMAT_SIGNAL_WEIGHTS = {
+    "reel":      {"watch_time": 0.50, "sends_per_reach": 0.25, "saves": 0.10, "likes_per_reach": 0.15},
+    "carousel":  {"watch_time": 0.10, "sends_per_reach": 0.15, "saves": 0.50, "likes_per_reach": 0.25},
+    "story":     {"watch_time": 0.20, "sends_per_reach": 0.40, "saves": 0.05, "likes_per_reach": 0.35},
+    "text_post": {"watch_time": 0.05, "sends_per_reach": 0.10, "saves": 0.30, "likes_per_reach": 0.55},
+}
+
+# Intent multiplier matrix: when intent matches format's strong signal, boost that signal
+INTENT_MULTIPLIER = {
+    "send_bait":  {"sends_per_reach": 1.6},
+    "save_bait":  {"saves": 1.7},
+    "watch_bait": {"watch_time": 1.5},
+    "like_bait":  {"likes_per_reach": 1.3},
+}
+
+VALID_TASKS = ("monthly_engage", "monthly_strategic", "monthly_competitive")
+
+INITIAL_FOLLOWERS = 10000
+REST_RECOVERY = 0.12
+CREATE_CONTENT_COST = 0.05
+REPETITION_ENERGY_PENALTY = 0.05
+FOLLOWER_DECAY_HOURS = 72
+ALGORITHM_PENALTY_MULT = 0.6
+ALGORITHM_PENALTY_BASE_DURATION = 2
+
+# Van Dongen 2003 *Sleep* PMID 12683469: lapses linear above 15.84h
+SLEEP_OPTIMAL_AWAKE = 16
+SLEEP_LINEAR_DECAY_PER_HOUR = 0.0625  # reaches ~50% at 24h awake (8h × 0.0625 = 0.5)
+SLEEP_MIN_QUALITY = 0.30
+SLEEP_ENERGY_DRAIN_START = 16
+SLEEP_ENERGY_DRAIN_RATE = 0.015
+SLEEP_RECOVERY_PER_REST = 2
+
+# Buffer 2.1M study + arxiv:2410.13108: tiered fatigue
+FATIGUE_TIERS = {2: 1.0, 3: 0.75, 4: 0.50, 5: 0.25}
+WEEKLY_FATIGUE_THRESHOLD = 7
+WEEKLY_FATIGUE_MULT = 0.75
+
+SATURATION_PENALTY_K = 0.25
+TREND_DEFAULT_HALFLIFE_HOURS = 60
+# Collab reward shaping (Later 2023 reach study, HypeAuditor 2024 niche affinity, Rival IQ 2025 overlap patterns,
+# Cen et al. 2024 disengagement model for diminishing returns instead of a hard cap).
+COLLAB_REACH_K = 0.60      # cross-audience exposure: capped reach uplift when overlap is 0
+COLLAB_AFFINITY_K = 0.30   # same-audience affinity: per-impression engagement uplift when overlap is 1
+COLLAB_GROWTH_K = 1.50     # cross-pollination follower spillover, scales (1 - overlap)
+COLLAB_PARTNER_REPEAT_PENALTY = 0.7  # discount on multipliers when partner reused this brand
+COLLAB_FATIGUE_K = 0.3     # per-collab diminishing-returns factor: 1/(1+K*prior_collabs_this_episode)
+
+REPLY_WINDOW_MINUTES = 90
+REPLY_REACH_BONUS = 1.4
+API_BUDGET_INITIAL = 100
+
+# Heuristic baselines for headline metric `vs_baseline_pct`.
+# Data-driven: loaded from `plots/training_summary.json["smart_heuristic"]` recorded by
+# `training/run_training_evidence.py`. Falls back to conservative calibration constants
+# if the file is missing (audit trail: see RESEARCH.md for the rule-based policy spec).
+def _load_heuristic_baselines() -> Dict[str, float]:
+    summary = Path(__file__).parent.parent / "plots" / "training_summary.json"
+    try:
+        data = json.loads(summary.read_text())
+        empirical = data.get("smart_heuristic") or {}
+        return {k: float(v) for k, v in empirical.items() if k in VALID_TASKS}
+    except Exception:
+        return {}
+
+HEURISTIC_BASELINE_SCORES: Dict[str, float] = _load_heuristic_baselines() or {
+    "monthly_engage": 0.43,
+    "monthly_strategic": 0.77,
+    "monthly_competitive": 0.81,
+}
+
+# Cross-episode store for distribution-shift retention. Keyed by episode_chain_id, stores
+# {"baseline": score, "shifted": score} so the second run can compute retention_under_shift.
+_SHIFT_HISTORY: Dict[str, Dict[str, float]] = {}
+
+# Tool costs
+TOOL_COSTS = {
+    "query_audience": 2,
+    "query_competitor": 2,
+    "query_tag_history": 1,
+    "query_trends": 1,
+    "predict_engagement": 3,
+    "draft_review": 3,
+    "query_creator_pool": 1,
+    "propose_collab": 5,
+}
+
+# ---------------------------------------------------------------------------
+# Brand state for multi-episode persistence
+# ---------------------------------------------------------------------------
+
+_BRAND_STORE: Dict[str, Dict[str, Any]] = {}
+
+
+@dataclass
+class CompetitorState:
+    id: str
+    name: str
+    niche: str
+    niche_topics: List[str]
+    preferred_types: List[str]
+    posts_per_week: float
+    base_engagement_rate: float
+    tag_preferences: List[str]
+    style: str
+    recent_posts: List[Dict[str, Any]] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Tool catalog (schemas for GET /tools)
+# ---------------------------------------------------------------------------
+
+TOOL_CATALOG = {
+    "query_audience": {
+        "description": "Query a specific audience segment to learn its topic affinities, content preferences, and active hours.",
+        "parameters": {"segment_id": {"type": "string", "enum": [s["id"] for s in _AUDIENCE_DATA.get("segments", [])]}},
+    },
+    "query_competitor": {
+        "description": "Get recent posts and strategy of a competitor archetype within a time window.",
+        "parameters": {
+            "competitor_id": {"type": "string", "enum": [a["id"] for a in _COMPETITORS_DATA.get("archetypes", [])]},
+            "window_days": {"type": "integer", "default": 7, "minimum": 1, "maximum": 30},
+        },
+    },
+    "query_tag_history": {
+        "description": "Get your historical engagement signals (watch, sends, saves, likes) for a specific tag.",
+        "parameters": {"tag": {"type": "string"}},
+    },
+    "query_trends": {
+        "description": "Get currently trending topics and tags for a niche, with decay-adjusted strength.",
+        "parameters": {"niche": {"type": "string", "enum": list(TOPIC_CATEGORIES.keys())}},
+    },
+    "predict_engagement": {
+        "description": "Simulate engagement signals for a hypothetical daily plan WITHOUT committing it. Returns predicted watch/sends/saves/likes.",
+        "parameters": {"scheduled_actions": {"type": "array", "description": "Same format as ViraltestAction.scheduled_actions"}},
+    },
+    "draft_review": {
+        "description": "Get AI review of a draft plan: strengths, weaknesses, suggested improvements.",
+        "parameters": {"scheduled_actions": {"type": "array"}},
+    },
+    "query_creator_pool": {
+        "description": "List available competitor archetypes for potential collaboration, with audience overlap %.",
+        "parameters": {},
+    },
+    "propose_collab": {
+        "description": "Propose a collab post with a competitor at a specific hour. The post you schedule at that hour will be co-authored with the partner.",
+        "parameters": {
+            "partner_id": {"type": "string"},
+            "content_type": {"type": "string", "enum": ["reel", "story", "carousel", "text_post"]},
+            "hour": {"type": "integer", "minimum": 0, "maximum": 23},
+        },
+    },
+}
+
+
+class ViraltestEnvironment(Environment):
+    """Monthly creator optimization simulation (Theme #3.1 World Modeling)."""
+
+    SUPPORTS_CONCURRENT_SESSIONS: bool = True
+
+    def __init__(self) -> None:
+        self._state = State(episode_id=str(uuid4()), step_count=0)
+        self._task = "monthly_engage"
+        self._rng = random.Random(42)
+        self._init_state()
+
+    def _init_state(self) -> None:
+        self._energy = 1.0
+        self._followers = INITIAL_FOLLOWERS
+        self._initial_followers = INITIAL_FOLLOWERS
+        self._hour = 9
+        self._day = 0
+        self._posts_today = 0
+        self._last_post_types: List[str] = []
+        self._time_since_last_post = 0
+        self._engagement_history: List[float] = []
+        self._tag_history: Dict[str, List[Dict[str, float]]] = defaultdict(list)
+        self._content_queue = 0
+        self._unique_tags_used: set = set()
+        self._unique_content_types: set = set()
+        self._energy_history: List[float] = [1.0]
+        self._posting_steps = 0
+        self._episode_done = False
+        self._last_topic: Optional[str] = None
+        self._final_observation: Optional[ViraltestObservation] = None
+        self._unique_topic_steps = 0
+        self._days_with_good_posts: set = set()
+        self._total_engagement = 0.0
+        self._posts_per_day: Dict[int, int] = defaultdict(int)
+        self._algorithm_penalty_remaining = 0
+        self._agent_notes: Optional[str] = None
+        self._api_budget = API_BUDGET_INITIAL
+        self._collabs_this_month = 0
+        self._collab_history: List[str] = []
+        self._active_collab: Optional[CollabProposal] = None
+        self._low_energy_days = 0
+        self._total_posts_this_week = 0
+        self._week_start_day = 0
+        self._daily_signals = EngagementSignals()
+        self._total_tool_calls = 0
+        self._total_action_chars = 0
+        self._shift_label: Optional[str] = None
+        self._chain_id: Optional[str] = None
+
+        self._trending_topics = self._pick_trending_topics()
+        self._trending_tags = self._pick_trending_tags()
+        self._competitors = self._load_competitors()
+
+        self._hours_since_sleep = 2
+        self._sleep_debt = 0.0
+
+    def _load_competitors(self) -> List[CompetitorState]:
+        archetypes = _COMPETITORS_DATA.get("archetypes", [])
+        return [
+            CompetitorState(
+                id=a["id"],
+                name=a["name"],
+                niche=a["niche"],
+                niche_topics=a["niche_topics"],
+                preferred_types=a["preferred_types"],
+                posts_per_week=a["posts_per_week"],
+                base_engagement_rate=a["base_engagement_rate"],
+                tag_preferences=a["tag_preferences"],
+                style=a.get("style", "consistent_moderate"),
+            )
+            for a in archetypes
+        ]
+
+    def _pick_trending_topics(self) -> List[str]:
+        all_topics = []
+        for niche_data in _TOPICS_DATA.get("niches", {}).values():
+            all_topics.extend(niche_data["topics"])
+        return self._rng.sample(all_topics, min(3, len(all_topics)))
+
+    def _pick_trending_tags(self) -> List[str]:
+        return self._rng.sample(TAG_POOL, min(5, len(TAG_POOL)))
+
+    def _rotate_trends(self) -> None:
+        self._trending_topics = self._pick_trending_topics()
+        self._trending_tags = self._pick_trending_tags()
+
+    # ----- hour multiplier (heatmap-based) -----
+
+    def _get_hour_multiplier(self) -> float:
+        dow = self._day % 7
+        h = self._hour
+        row = _HEATMAP_GRID.get(dow)
+        if row and 0 <= h < len(row):
+            return row[h]
+        return 0.8
+
+    # ----- quality (piecewise-linear sleep, Van Dongen 2003) -----
+
+    def _get_quality_modifier(self) -> float:
+        if self._energy > 0.5:
+            energy_factor = 1.0
+        else:
+            energy_factor = max(0.48, self._energy * 1.5)
+
+        if self._hours_since_sleep <= SLEEP_OPTIMAL_AWAKE:
+            sleep_factor = 1.0
+        else:
+            hours_over = self._hours_since_sleep - SLEEP_OPTIMAL_AWAKE
+            sleep_factor = max(SLEEP_MIN_QUALITY, 1.0 - SLEEP_LINEAR_DECAY_PER_HOUR * hours_over)
+
+        return energy_factor * sleep_factor
+
+    # ----- niche multiplier -----
+
+    def _get_niche_multiplier(self, topic: Optional[str]) -> float:
+        if not topic:
+            return 1.0
+        topic_lower = topic.lower()
+        for niche_name, niche_data in _TOPICS_DATA.get("niches", {}).items():
+            for t in niche_data["topics"]:
+                if t.lower() == topic_lower:
+                    return _NICHE_MULTIPLIERS.get(niche_name, 1.0)
+        return 1.0
+
+    # ----- tags -----
+
+    def _calc_tag_boost(self, tags: Optional[List[str]]) -> float:
+        if not tags:
+            return 1.0
+        trending_count = sum(1 for t in tags if t in self._trending_tags)
+        perf_values = [self._tag_performance_avg(t) for t in tags if self._tag_performance_avg(t) > 0]
+        perf_avg = sum(perf_values) / len(perf_values) if perf_values else 0.0
+        return 1.0 + 0.1 * trending_count + 0.05 * perf_avg
+
+    def _tag_performance_avg(self, tag: str) -> float:
+        history = self._tag_history.get(tag, [])
+        if not history:
+            return 0.0
+        window = history[-5:]
+        totals = [h.get("total", 0.0) for h in window]
+        return sum(totals) / len(totals) if totals else 0.0
+
+    def _get_tag_performance_dict(self) -> Dict[str, float]:
+        return {tag: self._tag_performance_avg(tag) for tag in self._unique_tags_used}
+
+    # ----- competitors -----
+
+    def _advance_competitors(self) -> None:
+        for comp in self._competitors:
+            for p in comp.recent_posts:
+                p["hours_ago"] += 1
+            comp.recent_posts = [p for p in comp.recent_posts if p["hours_ago"] < 72]
+
+            daily_prob = comp.posts_per_week / (7.0 * 24.0)
+            if self._rng.random() < daily_prob:
+                ct = self._rng.choice(comp.preferred_types)
+                topic = self._rng.choice(comp.niche_topics)
+                tags = self._rng.sample(comp.tag_preferences, min(3, len(comp.tag_preferences)))
+                eng = comp.base_engagement_rate + self._rng.uniform(-0.1, 0.1)
+                eng = max(0.0, min(1.0, eng))
+                comp.recent_posts.append({
+                    "content_type": ct, "topic": topic, "tags": tags,
+                    "engagement": round(eng, 3), "hours_ago": 0,
+                })
+
+    def _get_competitor_recent_posts(self, limit: int = 5) -> List[Dict[str, Any]]:
+        all_posts: List[Dict[str, Any]] = []
+        for comp in self._competitors:
+            for p in comp.recent_posts:
+                all_posts.append(p)
+        all_posts.sort(key=lambda x: x["hours_ago"])
+        return all_posts[:limit]
+
+    def _get_competitor_avg_engagement(self) -> float:
+        engagements = [p["engagement"] for comp in self._competitors for p in comp.recent_posts]
+        return sum(engagements) / len(engagements) if engagements else 0.0
+
+    def _calc_niche_saturation(self, topic: Optional[str]) -> float:
+        if not topic:
+            return 0.0
+        recent_topics = []
+        for comp in self._competitors:
+            for p in comp.recent_posts:
+                if p["hours_ago"] < 12:
+                    recent_topics.append(p["topic"].lower())
+        if not recent_topics:
+            return 0.0
+        topic_lower = topic.lower()
+        overlap = sum(1 for t in recent_topics if _topic_overlap(topic_lower, t))
+        return min(1.0, overlap / max(1, len(recent_topics)))
+
+    def _calc_competitor_diff(self, topic: Optional[str]) -> float:
+        if not topic:
+            return 1.0
+        saturation = self._calc_niche_saturation(topic)
+        recent_topics = [
+            p["topic"].lower()
+            for comp in self._competitors
+            for p in comp.recent_posts
+            if p["hours_ago"] < 12
+        ]
+        has_overlap = any(_topic_overlap(topic.lower(), t) for t in recent_topics)
+        if not has_overlap:
+            return 1.3
+        if saturation > 0.7:
+            return 0.6
+        return 1.0
+
+    def _count_competitors_same_hour(self) -> int:
+        count = 0
+        for comp in self._competitors:
+            for p in comp.recent_posts:
+                if p["hours_ago"] <= 1:
+                    count += 1
+        return count
+
+    # ----- fatigue (tiered, Buffer 2.1M) -----
+
+    def _get_fatigue_multiplier(self) -> float:
+        if self._posts_today <= 2:
+            daily_fatigue = 1.0
+        elif self._posts_today in FATIGUE_TIERS:
+            daily_fatigue = FATIGUE_TIERS[self._posts_today]
+        else:
+            daily_fatigue = 0.25
+
+        weekly_mult = 1.0
+        if self._total_posts_this_week >= WEEKLY_FATIGUE_THRESHOLD:
+            weekly_mult = WEEKLY_FATIGUE_MULT
+
+        return daily_fatigue * weekly_mult
+
+    # ----- collab multipliers (overlap-driven) -----
+
+    def _user_partner_overlap(self, partner_id: str) -> Optional[float]:
+        ids = _OVERLAP_DATA.get("archetype_ids", [])
+        if "user_creator" not in ids or partner_id not in ids:
+            return None
+        u = ids.index("user_creator")
+        p = ids.index(partner_id)
+        return _OVERLAP_DATA["matrix"][u][p]
+
+    def _collab_multipliers(self, partner_id: str) -> Tuple[float, float]:
+        """Returns (engagement_multiplier, follower_growth_multiplier)."""
+        o = self._user_partner_overlap(partner_id)
+        if o is None:
+            return 1.0, 1.0
+        reach = 1.0 + (1.0 - o) * COLLAB_REACH_K
+        affinity = 1.0 + o * COLLAB_AFFINITY_K
+        growth = 1.0 + (1.0 - o) * COLLAB_GROWTH_K
+        eng_boost = reach * affinity
+        if partner_id in self._collab_history[:-1]:
+            eng_boost *= COLLAB_PARTNER_REPEAT_PENALTY
+            growth *= COLLAB_PARTNER_REPEAT_PENALTY
+        prior = max(0, self._collabs_this_month - 1)
+        fatigue = 1.0 / (1.0 + COLLAB_FATIGUE_K * prior)
+        return eng_boost * fatigue, growth * fatigue
+
+    # ----- engagement signals (Mosseri-aligned) -----
+
+    def _compute_engagement_signals(
+        self, content_type: str, base_eng: float, intent: Optional[str]
+    ) -> EngagementSignals:
+        weights = FORMAT_SIGNAL_WEIGHTS.get(content_type, FORMAT_SIGNAL_WEIGHTS["text_post"])
+        signals = {k: base_eng * v for k, v in weights.items()}
+
+        if intent and intent in INTENT_MULTIPLIER:
+            for signal_name, mult in INTENT_MULTIPLIER[intent].items():
+                if signal_name in signals:
+                    signals[signal_name] *= mult
+
+        return EngagementSignals(**signals)
+
+    # ----- tool dispatcher -----
+
+    def _dispatch_tool(self, tool: ToolCall) -> ToolResult:
+        cost = TOOL_COSTS.get(tool.name, 1)
+        if self._api_budget < cost:
+            return ToolResult(name=tool.name, success=False, error="rate_limit_exceeded", budget_remaining=self._api_budget)
+
+        self._api_budget -= cost
+
+        if tool.name == "query_audience":
+            seg_id = tool.arguments.get("segment_id", "")
+            for seg in _AUDIENCE_DATA.get("segments", []):
+                if seg["id"] == seg_id:
+                    return ToolResult(name=tool.name, data=seg, budget_remaining=self._api_budget)
+            return ToolResult(name=tool.name, success=False, error=f"unknown segment: {seg_id}", budget_remaining=self._api_budget)
+
+        elif tool.name == "query_competitor":
+            comp_id = tool.arguments.get("competitor_id", "")
+            window = tool.arguments.get("window_days", 7)
+            for comp in self._competitors:
+                if comp.id == comp_id:
+                    posts = [p for p in comp.recent_posts if p["hours_ago"] < window * 24]
+                    return ToolResult(name=tool.name, data={
+                        "id": comp.id, "name": comp.name, "niche": comp.niche,
+                        "posts_per_week": comp.posts_per_week,
+                        "recent_posts": posts[:10],
+                        "avg_engagement": round(sum(p["engagement"] for p in posts) / max(1, len(posts)), 3),
+                    }, budget_remaining=self._api_budget)
+            return ToolResult(name=tool.name, success=False, error=f"unknown competitor: {comp_id}", budget_remaining=self._api_budget)
+
+        elif tool.name == "query_tag_history":
+            tag = tool.arguments.get("tag", "").lower()
+            history = self._tag_history.get(tag, [])
+            return ToolResult(name=tool.name, data={
+                "tag": tag, "uses": len(history),
+                "avg_signals": _avg_signal_dicts(history[-10:]) if history else {},
+            }, budget_remaining=self._api_budget)
+
+        elif tool.name == "query_trends":
+            niche = tool.arguments.get("niche", "tech")
+            return ToolResult(name=tool.name, data={
+                "trending_topics": self._trending_topics,
+                "trending_tags": self._trending_tags,
+                "niche_saturation": round(self._calc_niche_saturation(self._last_topic), 3),
+            }, budget_remaining=self._api_budget)
+
+        elif tool.name == "predict_engagement":
+            raw_actions = tool.arguments.get("scheduled_actions", [])
+            predicted_total = 0.0
+            for sa_dict in raw_actions[:5]:
+                sa = ScheduledAction(**sa_dict) if isinstance(sa_dict, dict) else sa_dict
+                if sa.action_type == "post" and sa.content_type:
+                    base = BASE_ENGAGEMENT.get(sa.content_type, 0.3)
+                    reach = REACH_MULT.get(sa.content_type, 1.0)
+                    niche_m = self._get_niche_multiplier(sa.topic)
+                    predicted_total += base * reach * niche_m * self._get_hour_multiplier()
+            return ToolResult(name=tool.name, data={"predicted_daily_engagement": round(predicted_total, 4)}, budget_remaining=self._api_budget)
+
+        elif tool.name == "draft_review":
+            raw_actions = tool.arguments.get("scheduled_actions", [])
+            n_posts = sum(1 for a in raw_actions if (a.get("action_type") if isinstance(a, dict) else getattr(a, "action_type", "")) == "post")
+            feedback = []
+            if n_posts == 0:
+                feedback.append("No posts planned — you'll lose algorithmic momentum.")
+            elif n_posts > 3:
+                feedback.append(f"{n_posts} posts in one day risks audience fatigue (optimal: 1-2).")
+            if n_posts >= 1 and n_posts <= 2:
+                feedback.append("Good posting frequency for today.")
+            return ToolResult(name=tool.name, data={"feedback": feedback, "post_count": n_posts}, budget_remaining=self._api_budget)
+
+        elif tool.name == "query_creator_pool":
+            pool = []
+            for comp in self._competitors:
+                overlap = self._user_partner_overlap(comp.id)
+                pool.append({
+                    "id": comp.id, "name": comp.name, "niche": comp.niche,
+                    "audience_overlap": round(overlap, 2) if overlap is not None else None,
+                })
+            return ToolResult(name=tool.name, data=pool, budget_remaining=self._api_budget)
+
+        elif tool.name == "propose_collab":
+            partner_id = tool.arguments.get("partner_id", "")
+            if partner_id not in [c.id for c in self._competitors]:
+                return ToolResult(name=tool.name, success=False, error=f"unknown partner: {partner_id}", budget_remaining=self._api_budget)
+            return ToolResult(name=tool.name, data={"status": "proposal_accepted", "partner_id": partner_id}, budget_remaining=self._api_budget)
+
+        return ToolResult(name=tool.name, success=False, error=f"unknown tool: {tool.name}", budget_remaining=self._api_budget)
+
+    # ----- counterfactual coach -----
+
+    def _compute_coach_feedback(self, agent_engagement: float) -> Dict[str, Any]:
+        # World-modeling discipline: emit a SCALAR delta only (no optimal_hours leak).
+        # Agents must use `query_trends` / `predict_engagement` to discover *which* hours
+        # are optimal — coach only signals "you're above/below the heatmap optimum today".
+        dow = self._day % 7
+        row = _HEATMAP_GRID.get(dow, [1.0] * 24)
+        best_hours = sorted(range(24), key=lambda h: row[h] if h < len(row) else 0, reverse=True)[:2]
+        best_base = max(BASE_ENGAGEMENT.values())
+        best_reach = max(REACH_MULT.values())
+        optimal_eng = sum(row[h] * best_base * best_reach for h in best_hours)
+        delta = agent_engagement - optimal_eng
+        return {
+            "delta": round(delta, 4),
+            "suggestion": (
+                "Above heatmap optimum today."
+                if delta >= 0
+                else "Below heatmap optimum — try `query_trends` / `predict_engagement` to find peak hours."
+            ),
+        }
+
+    # ----- regulator / judge mode (deterministic, explainable) -----
+
+    def _compute_judge_report(
+        self,
+        action: ViraltestAction,
+        daily_engagement: float,
+        daily_posts: int,
+        energy_min: float,
+        errors: List[str],
+    ) -> JudgeReport:
+        violations: List[str] = []
+
+        pc = 1.0
+        if daily_posts > 5:
+            violations.append(f"posts_today={daily_posts} exceeds tier-4 fatigue cliff (Buffer 2.1M)")
+            pc -= 0.30
+        elif daily_posts > 2:
+            violations.append(f"posts_today={daily_posts} enters fatigue tier (>2/day)")
+            pc -= 0.10
+        if self._total_posts_this_week > WEEKLY_FATIGUE_THRESHOLD:
+            violations.append(f"weekly posts={self._total_posts_this_week} > {WEEKLY_FATIGUE_THRESHOLD} (Buffer 2.1M cap)")
+            pc -= 0.20
+        if self._collabs_this_month >= 4:
+            violations.append(f"collab cadence={self._collabs_this_month} net-negative beyond 3 (Cen 2024)")
+            pc -= 0.20
+        if errors:
+            violations.append(f"plan_errors={len(errors)}")
+            pc -= 0.05 * len(errors)
+        if self._hours_since_sleep > 22:
+            violations.append(f"sleep_debt: {self._hours_since_sleep}h awake (Van Dongen 2003)")
+            pc -= 0.10
+
+        burnout_pressure = (1.0 - energy_min) * 0.4 + self._sleep_debt * 0.3 + (self._low_energy_days / 5.0) * 0.3
+        sustainability_risk = max(0.0, min(1.0, burnout_pressure))
+
+        intents_used = {sa.intent for sa in action.scheduled_actions if sa.intent}
+        formats_used = {sa.content_type for sa in action.scheduled_actions if sa.action_type == "post" and sa.content_type}
+        eng_per_post = daily_engagement / max(1, daily_posts)
+        sq = (
+            0.40 * min(1.0, eng_per_post / 1.2)
+            + 0.30 * min(1.0, len(intents_used) / 2.0)
+            + 0.30 * min(1.0, len(formats_used) / 2.0)
+        )
+
+        explanation = (
+            f"compliance={max(0.0, pc):.2f} risk={sustainability_risk:.2f} strategy={sq:.2f} | "
+            + (("violations: " + "; ".join(violations)) if violations else "no policy violations")
+        )
+
+        return JudgeReport(
+            policy_compliance=max(0.0, min(1.0, pc)),
+            sustainability_risk=sustainability_risk,
+            strategic_quality=max(0.0, min(1.0, sq)),
+            explanation=explanation,
+            violations=violations,
+        )
+
+    def _compute_headline_metrics(self, grader_score: float) -> HeadlineMetrics:
+        baseline = HEURISTIC_BASELINE_SCORES.get(self._task, 0.30)
+        vs_pct = (grader_score - baseline) / baseline if baseline > 0 else 0.0
+        spt = grader_score / max(1, self._total_tool_calls)
+        sp1k = grader_score / max(1.0, self._total_action_chars / 1000.0)
+
+        retention: Optional[float] = None
+        if self._chain_id:
+            entry = _SHIFT_HISTORY.setdefault(self._chain_id, {})
+            label = self._shift_label or "baseline"
+            entry[label] = grader_score
+            base = entry.get("baseline")
+            shifted = entry.get("shifted")
+            if base is not None and shifted is not None and base > 0:
+                retention = shifted / base
+
+        return HeadlineMetrics(
+            vs_baseline_pct=round(vs_pct, 4),
+            score_per_tool_call=round(spt, 4),
+            score_per_1k_chars=round(sp1k, 4),
+            retention_under_shift=round(retention, 4) if retention is not None else None,
+            heuristic_baseline_score=round(baseline, 4),
+            agent_score=round(grader_score, 4),
+            total_tool_calls=self._total_tool_calls,
+            total_action_chars=self._total_action_chars,
+        )
+
+    # ----- core API -----
+
+    def reset(self, seed: Optional[int] = None, episode_id: Optional[str] = None, **kwargs: Any) -> ViraltestObservation:
+        self._task = kwargs.get("task", "monthly_engage")
+        if self._task not in VALID_TASKS:
+            self._task = "monthly_engage"
+
+        self._rng = random.Random(seed if seed is not None else 42)
+        self._state = State(episode_id=episode_id or str(uuid4()), step_count=0)
+        self._init_state()
+
+        self._shift_label = kwargs.get("shift_label")
+        self._chain_id = kwargs.get("episode_chain_id")
+
+        chain_id = kwargs.get("episode_chain_id")
+        if chain_id and chain_id in _BRAND_STORE:
+            brand = _BRAND_STORE[chain_id]
+            self._unique_tags_used = set(brand.get("top_tags", []))
+            self._unique_content_types = set(brand.get("dominant_types", []))
+            self._collab_history = brand.get("collab_history", [])
+            self._followers = brand.get("followers", INITIAL_FOLLOWERS)
+            self._initial_followers = self._followers
+
+        return self._build_observation(reward=0.0, error=None)
+
+    def step(self, action: ViraltestAction, **kwargs: Any) -> ViraltestObservation:
+        if self._episode_done and self._final_observation is not None:
+            return self._final_observation
+
+        self._state.step_count += 1
+
+        # Store agent notes for echo
+        if action.notes:
+            self._agent_notes = action.notes
+
+        try:
+            self._total_action_chars += len(action.model_dump_json())
+        except Exception:
+            pass
+
+        tool_results: List[ToolResult] = []
+        for tc in action.tool_calls:
+            result = self._dispatch_tool(tc)
+            tool_results.append(result)
+            if result.success:
+                self._total_tool_calls += 1
+
+        # Process collab proposal (no hard cap; diminishing returns enforced via _collab_multipliers)
+        self._active_collab = None
+        if action.collab:
+            self._collabs_this_month += 1
+            self._collab_history.append(action.collab.partner_id)
+            self._active_collab = action.collab
+
+        # Validate scheduled actions
+        schedule: Dict[int, ScheduledAction] = {}
+        errors: List[str] = []
+        for sa in action.scheduled_actions:
+            if sa.hour < 0 or sa.hour > 23:
+                errors.append(f"Invalid hour: {sa.hour}")
+                continue
+            err = self._validate_scheduled_action(sa)
+            if err:
+                errors.append(f"hour {sa.hour}: {err}")
+                continue
+            schedule[sa.hour] = sa
+
+        daily_engagement = 0.0
+        daily_reward = 0.0
+        daily_posts = 0
+        energy_min = self._energy
+        burned_out = False
+        daily_signals = EngagementSignals()
+
+        for hour in range(24):
+            if burned_out:
+                break
+            self._hour = hour
+
+            if hour in schedule:
+                sa = schedule[hour]
+                hourly_eng, hourly_reward, hourly_signals = self._process_hour_action(sa)
+            else:
+                hourly_eng, hourly_reward = self._process_hour_rest()
+                hourly_signals = None
+
+            daily_engagement += hourly_eng
+            daily_reward += hourly_reward
+            if hourly_eng > 0:
+                daily_posts += 1
+            if hourly_signals:
+                daily_signals = EngagementSignals(
+                    watch_time=daily_signals.watch_time + hourly_signals.watch_time,
+                    sends_per_reach=daily_signals.sends_per_reach + hourly_signals.sends_per_reach,
+                    saves=daily_signals.saves + hourly_signals.saves,
+                    likes_per_reach=daily_signals.likes_per_reach + hourly_signals.likes_per_reach,
+                )
+            energy_min = min(energy_min, self._energy)
+            self._advance_competitors()
+            self._advance_time()
+            self._energy_history.append(self._energy)
+
+            if self._energy <= 0.0:
+                burned_out = True
+
+        # Process replies
+        for reply in action.replies:
+            if 0 <= reply.reply_hour < 24 and 0 <= reply.post_hour < 24:
+                diff_minutes = abs(reply.reply_hour - reply.post_hour) * 60
+                if diff_minutes <= REPLY_WINDOW_MINUTES:
+                    daily_engagement *= REPLY_REACH_BONUS
+                    daily_signals = EngagementSignals(
+                        watch_time=daily_signals.watch_time * REPLY_REACH_BONUS,
+                        sends_per_reach=daily_signals.sends_per_reach * REPLY_REACH_BONUS,
+                        saves=daily_signals.saves * REPLY_REACH_BONUS,
+                        likes_per_reach=daily_signals.likes_per_reach * REPLY_REACH_BONUS,
+                    )
+
+        # Weekly tracking
+        self._total_posts_this_week += daily_posts
+        if self._day % 7 == 0 and self._day > 0:
+            self._total_posts_this_week = 0
+
+        # Burnout risk tracking
+        if energy_min < 0.2:
+            self._low_energy_days += 1
+        else:
+            self._low_energy_days = max(0, self._low_energy_days - 1)
+
+        prev_day = max(0, self._day - 1)
+        if 1 <= self._posts_per_day.get(prev_day, 0) <= 2:
+            self._days_with_good_posts.add(prev_day)
+
+        avg_reward = daily_reward / 24.0
+        error_str = "; ".join(errors) if errors else None
+
+        done = self._state.step_count >= TASK_HORIZON or self._energy <= 0.0
+        coach = self._compute_coach_feedback(daily_engagement)
+        judge = self._compute_judge_report(action, daily_engagement, daily_posts, energy_min, errors)
+
+        if done:
+            self._episode_done = True
+            grader_score = self._run_grader()
+            headline = self._compute_headline_metrics(grader_score)
+
+            chain_id = kwargs.get("episode_chain_id")
+            if chain_id:
+                top_tags = sorted(self._unique_tags_used, key=lambda t: self._tag_performance_avg(t), reverse=True)[:3]
+                _BRAND_STORE[chain_id] = {
+                    "top_tags": list(top_tags),
+                    "dominant_types": list(self._unique_content_types),
+                    "collab_history": self._collab_history[-3:],
+                    "followers": self._followers,
+                }
+
+            self._final_observation = self._build_observation(
+                reward=round(avg_reward, 4), error=error_str, done=True,
+                grader_score=grader_score, daily_total_engagement=daily_engagement,
+                daily_posts_made=daily_posts, daily_energy_min=energy_min,
+                tool_results=tool_results, engagement_signals=daily_signals,
+                coach_feedback=coach, judge_report=judge, headline_metrics=headline,
+            )
+            return self._final_observation
+
+        return self._build_observation(
+            reward=round(avg_reward, 4), error=error_str,
+            daily_total_engagement=daily_engagement,
+            daily_posts_made=daily_posts, daily_energy_min=energy_min,
+            tool_results=tool_results, engagement_signals=daily_signals,
+            coach_feedback=coach, judge_report=judge,
+        )
+
+    def _process_hour_action(self, sa: ScheduledAction) -> Tuple[float, float, Optional[EngagementSignals]]:
+        engagement = 0.0
+        signals = None
+
+        collab_growth_mult = 1.0
+
+        if sa.action_type == "post":
+            cost = CONTENT_ENERGY_COST.get(sa.content_type, 0.1)
+            if self._content_queue > 0:
+                cost *= 0.5
+                self._content_queue -= 1
+            if len(self._last_post_types) >= 3 and all(t == sa.content_type for t in self._last_post_types[-3:]):
+                cost += REPETITION_ENERGY_PENALTY
+            self._energy = max(0.0, self._energy - cost)
+            self._unique_content_types.add(sa.content_type)
+
+            if self._energy <= 0.0:
+                engagement = 0.0
+            else:
+                base = BASE_ENGAGEMENT.get(sa.content_type, 0.3)
+                reach = REACH_MULT.get(sa.content_type, 1.0)
+                hour_mult = self._get_hour_multiplier()
+                quality = self._get_quality_modifier()
+                tag_boost = self._calc_tag_boost(sa.tags)
+                trending_bonus = 1.5 if self._is_topic_trending(sa.topic) else 1.0
+                comp_diff = self._calc_competitor_diff(sa.topic)
+                fatigue = self._get_fatigue_multiplier()
+                niche_mult = self._get_niche_multiplier(sa.topic)
+
+                n_comp_same_hour = self._count_competitors_same_hour()
+                saturation_factor = 1.0 / (1.0 + SATURATION_PENALTY_K * n_comp_same_hour)
+
+                algo_mult = 1.0
+                if self._algorithm_penalty_remaining > 0:
+                    algo_mult = ALGORITHM_PENALTY_MULT
+                    self._algorithm_penalty_remaining -= 1
+
+                engagement = (
+                    base * reach * hour_mult * quality * tag_boost
+                    * trending_bonus * comp_diff * fatigue * algo_mult
+                    * niche_mult * saturation_factor
+                )
+
+                if self._active_collab is not None and self._active_collab.hour == sa.hour:
+                    eng_m, growth_m = self._collab_multipliers(self._active_collab.partner_id)
+                    engagement *= eng_m
+                    collab_growth_mult = growth_m
+
+                engagement = min(engagement, 5.0)
+
+                signals = self._compute_engagement_signals(sa.content_type, engagement, sa.intent)
+
+            self._last_topic = sa.topic
+
+            if sa.tags and engagement > 0:
+                signal_dict = signals.model_dump() if signals else {"total": engagement}
+                signal_dict["total"] = engagement
+                for tag in sa.tags:
+                    tag_lower = tag.lower()
+                    self._tag_history[tag_lower].append(signal_dict)
+                    self._unique_tags_used.add(tag_lower)
+
+            self._engagement_history.append(engagement)
+            self._total_engagement += engagement
+            self._posting_steps += 1
+
+            if self._calc_competitor_diff(sa.topic) >= 1.3:
+                self._unique_topic_steps += 1
+
+            self._last_post_types.append(sa.content_type)
+            if len(self._last_post_types) > 3:
+                self._last_post_types = self._last_post_types[-3:]
+            self._posts_today += 1
+            self._posts_per_day[self._day] += 1
+            self._time_since_last_post = 0
+
+            if engagement > 0:
+                self._followers += int(engagement * 100 * collab_growth_mult)
+
+        elif sa.action_type == "create_content":
+            self._energy = max(0.0, self._energy - CREATE_CONTENT_COST)
+            self._content_queue += 1
+            self._time_since_last_post += 1
+
+        if self._time_since_last_post >= FOLLOWER_DECAY_HOURS:
+            self._followers = max(0, self._followers - int(self._followers * 0.005))
+            if self._algorithm_penalty_remaining == 0:
+                gap_days = self._time_since_last_post // 24
+                self._algorithm_penalty_remaining = ALGORITHM_PENALTY_BASE_DURATION + gap_days
+
+        reward = 0.0 if self._energy <= 0.0 else self._compute_hourly_reward(sa, engagement)
+        return engagement, reward, signals
+
+    def _process_hour_rest(self) -> Tuple[float, float]:
+        self._energy = min(1.0, self._energy + REST_RECOVERY)
+        self._hours_since_sleep = max(0, self._hours_since_sleep - SLEEP_RECOVERY_PER_REST)
+        self._sleep_debt = max(0.0, self._sleep_debt - 0.1)
+        self._time_since_last_post += 1
+
+        if self._time_since_last_post >= FOLLOWER_DECAY_HOURS:
+            self._followers = max(0, self._followers - int(self._followers * 0.005))
+            if self._algorithm_penalty_remaining == 0:
+                gap_days = self._time_since_last_post // 24
+                self._algorithm_penalty_remaining = ALGORITHM_PENALTY_BASE_DURATION + gap_days
+
+        reward = 0.0 if self._energy <= 0.0 else self._compute_rest_reward()
+        return 0.0, reward
+
+    @property
+    def state(self) -> State:
+        return self._state
+
+    def _validate_scheduled_action(self, sa: ScheduledAction) -> Optional[str]:
+        if sa.action_type not in ("post", "create_content"):
+            return f"Invalid action_type: {sa.action_type}"
+        if sa.action_type == "post":
+            if not sa.content_type:
+                return "content_type is required when posting"
+            if sa.content_type not in CONTENT_ENERGY_COST:
+                return f"Invalid content_type: {sa.content_type}"
+            if not sa.topic or not sa.topic.strip():
+                return "topic is required when posting"
+            if len(sa.topic) > 200:
+                return "topic must be <= 200 characters"
+            if sa.tags:
+                valid = [t for t in sa.tags if t.lower() in [tp.lower() for tp in TAG_POOL]]
+                sa.tags = valid if valid else None
+        return None
+
+    def _is_topic_trending(self, topic: Optional[str]) -> bool:
+        if not topic:
+            return False
+        topic_lower = topic.lower()
+        return any(t.lower() in topic_lower for t in self._trending_topics)
+
+    # ----- reward -----
+
+    def _compute_hourly_reward(self, sa: ScheduledAction, engagement: float) -> float:
+        eng_component = min(1.0, engagement / 2.0) * 0.3
+
+        prev_energy = self._energy_history[-2] if len(self._energy_history) >= 2 else 1.0
+        energy_delta = self._energy - prev_energy
+        energy_component = max(0.0, min(1.0, (energy_delta + 0.3) / 0.6)) * 0.15
+
+        day_posts = self._posts_per_day.get(self._day, 0)
+        if 1 <= day_posts <= 2:
+            consistency = 1.0
+        elif day_posts == 0 or day_posts == 3:
+            consistency = 0.5
+        else:
+            consistency = 0.0
+        consistency_component = consistency * 0.15
+
+        tag_component = 0.0
+        if sa.action_type == "post" and sa.tags:
+            trending_match = sum(1 for t in sa.tags if t.lower() in self._trending_tags) / 5.0
+            tag_component = min(1.0, trending_match + 0.3) * 0.15
+
+        comp_component = 0.0
+        if sa.action_type == "post":
+            diff = self._calc_competitor_diff(sa.topic)
+            comp_component = min(1.0, diff / 1.3) * 0.15
+
+        burnout_penalty = 0.1 if self._energy < 0.2 else 0.0
+        raw = eng_component + energy_component + consistency_component + tag_component + comp_component - burnout_penalty
+        return max(0.0, min(1.0, raw))
+
+    def _compute_rest_reward(self) -> float:
+        prev_energy = self._energy_history[-2] if len(self._energy_history) >= 2 else 1.0
+        energy_delta = self._energy - prev_energy
+        energy_component = max(0.0, min(1.0, (energy_delta + 0.3) / 0.6)) * 0.15
+
+        day_posts = self._posts_per_day.get(self._day, 0)
+        if 1 <= day_posts <= 2:
+            consistency = 1.0
+        elif day_posts == 0 or day_posts == 3:
+            consistency = 0.5
+        else:
+            consistency = 0.0
+        consistency_component = consistency * 0.15
+
+        burnout_penalty = 0.1 if self._energy < 0.2 else 0.0
+        raw = energy_component + consistency_component - burnout_penalty
+        return max(0.0, min(1.0, raw))
+
+    def _advance_time(self) -> None:
+        self._hour += 1
+        self._hours_since_sleep += 1
+
+        if self._hours_since_sleep > SLEEP_ENERGY_DRAIN_START:
+            hours_over = self._hours_since_sleep - SLEEP_ENERGY_DRAIN_START
+            drain = SLEEP_ENERGY_DRAIN_RATE * (1 + hours_over * 0.1)
+            self._energy = max(0.0, self._energy - drain)
+
+        if self._hours_since_sleep > SLEEP_OPTIMAL_AWAKE:
+            hours_over = self._hours_since_sleep - SLEEP_OPTIMAL_AWAKE
+            debt_rate = 0.01 * (1 + hours_over * 0.05)
+            self._sleep_debt = min(1.0, self._sleep_debt + debt_rate)
+
+        if self._hour >= 24:
+            self._hour = 0
+            self._day += 1
+            self._posts_today = 0
+            self._rotate_trends()
+
+    def _build_observation(
+        self, reward: float, error: Optional[str], done: bool = False,
+        grader_score: Optional[float] = None,
+        daily_total_engagement: float = 0.0, daily_posts_made: int = 0,
+        daily_energy_min: float = 1.0,
+        tool_results: Optional[List[ToolResult]] = None,
+        engagement_signals: Optional[EngagementSignals] = None,
+        coach_feedback: Optional[Dict[str, Any]] = None,
+        judge_report: Optional[JudgeReport] = None,
+        headline_metrics: Optional[HeadlineMetrics] = None,
+    ) -> ViraltestObservation:
+        recent_eng = self._engagement_history[-10:] if self._engagement_history else []
+        eng_rate = sum(recent_eng) / len(recent_eng) if recent_eng else 0.0
+
+        meta: Dict[str, Any] = {"step": self._state.step_count, "task": self._task}
+        if grader_score is not None:
+            meta["grader_score"] = round(grader_score, 4)
+
+        burnout_risk = min(1.0, self._low_energy_days / 5.0)
+
+        return ViraltestObservation(
+            current_hour=self._hour,
+            day_of_week=self._day % 7,
+            days_elapsed=self._day,
+            creator_energy=round(self._energy, 3),
+            hours_since_sleep=self._hours_since_sleep,
+            sleep_debt=round(self._sleep_debt, 3),
+            follower_count=self._followers,
+            engagement_rate=round(eng_rate, 4),
+            posts_today=self._posts_today,
+            time_since_last_post=self._time_since_last_post,
+            content_queue_size=self._content_queue,
+            last_post_type=self._last_post_types[-1] if self._last_post_types else "none",
+            burnout_risk=round(burnout_risk, 3),
+            daily_total_engagement=round(daily_total_engagement, 4),
+            daily_posts_made=daily_posts_made,
+            daily_energy_min=round(daily_energy_min, 3),
+            engagement_signals=engagement_signals,
+            coach_feedback=coach_feedback,
+            judge_report=judge_report,
+            headline_metrics=headline_metrics,
+            tool_results=tool_results or [],
+            agent_notes=self._agent_notes,
+            api_budget_remaining=self._api_budget,
+            grader_score=round(grader_score, 4) if grader_score is not None else None,
+            error=error,
+            done=done,
+            reward=round(reward, 4),
+            metadata=meta,
+        )
+
+    # ----- graders (monthly) -----
+
+    def _run_grader(self) -> float:
+        if self._task == "monthly_engage":
+            return self._grade_monthly_engage()
+        elif self._task == "monthly_strategic":
+            return self._grade_monthly_strategic()
+        elif self._task == "monthly_competitive":
+            return self._grade_monthly_competitive()
+        return 0.0
+
+    def _theoretical_max_engagement(self) -> float:
+        # Buffer 2.1M (RESEARCH.md): 3–5 posts/week doubles follower growth vs 1–2,
+        # diminishing returns above 5/week, 20–35% engagement drop per post above 7/week.
+        # Cap at 5 posts/week × 4 weeks = 20 posts/month (sweet-spot, no fatigue penalty).
+        best_base = max(BASE_ENGAGEMENT.values())
+        best_reach = max(REACH_MULT.values())
+        best_niche = max(_NICHE_MULTIPLIERS.values()) if _NICHE_MULTIPLIERS else 1.0
+
+        posts_per_week = 5
+        weeks_in_horizon = TASK_HORIZON / 7.0
+        total_posts = int(round(posts_per_week * weeks_in_horizon))
+
+        avg_heatmap_peak = 1.0
+        if _HEATMAP_GRID:
+            day_peaks = [
+                max(row) if row else 1.0
+                for row in _HEATMAP_GRID.values()
+            ]
+            avg_heatmap_peak = sum(day_peaks) / len(day_peaks) if day_peaks else 1.0
+
+        # Trending + tag uplifts: tier-1 industry data shows ~1.2-1.3x for trending topics
+        # and ~1.05-1.15x for high-performance tags. Mid-range used to avoid headroom inflation.
+        trending_bonus = 1.25
+        tag_boost = 1.1
+
+        per_post = (
+            best_base * best_reach * best_niche
+            * avg_heatmap_peak * trending_bonus * tag_boost
+        )
+        return per_post * total_posts
+
+    def _grade_monthly_engage(self) -> float:
+        theoretical_max = self._theoretical_max_engagement()
+        if theoretical_max <= 0:
+            return 0.0
+        raw = min(1.0, self._total_engagement / theoretical_max)
+        if self._energy <= 0.0:
+            raw *= 0.3
+        return raw
+
+    def _grade_monthly_strategic(self) -> float:
+        if self._energy <= 0.0:
+            return max(0.0, min(0.15, self._total_engagement * 0.01))
+
+        theoretical_max = self._theoretical_max_engagement()
+        norm_eng = min(1.0, self._total_engagement / theoretical_max) if theoretical_max > 0 else 0.0
+
+        positive_tags = sum(1 for t in self._unique_tags_used if self._tag_performance_avg(t) > 0)
+        tag_discovery = min(1.0, positive_tags / 30.0)
+        top_perfs = sorted([self._tag_performance_avg(t) for t in self._unique_tags_used], reverse=True)[:3]
+        tag_exploitation = (sum(top_perfs) / len(top_perfs)) if top_perfs else 0.0
+        tag_exploitation = min(1.0, tag_exploitation / 2.0)
+        tag_score = 0.4 * tag_discovery + 0.6 * tag_exploitation
+
+        avg_energy = sum(self._energy_history) / len(self._energy_history) if self._energy_history else 0.0
+        consistency = len(self._days_with_good_posts) / 30.0
+
+        raw = 0.35 * norm_eng + 0.25 * tag_score + 0.25 * avg_energy + 0.15 * consistency
+
+        min_energy = min(self._energy_history) if self._energy_history else 0.0
+        if min_energy < 0.2:
+            raw *= 0.4
+        elif min_energy < 0.3:
+            raw = min(raw, 0.45)
+        if len(self._unique_tags_used) < 5:
+            raw *= 0.7
+
+        return max(0.0, min(1.0, raw))
+
+    def _grade_monthly_competitive(self) -> float:
+        if self._energy <= 0.0:
+            return 0.0
+
+        theoretical_max = self._theoretical_max_engagement()
+        norm_eng = min(1.0, self._total_engagement / theoretical_max) if theoretical_max > 0 else 0.0
+
+        positive_tags = sum(1 for t in self._unique_tags_used if self._tag_performance_avg(t) > 0)
+        tag_discovery = min(1.0, positive_tags / 30.0)
+        top_perfs = sorted([self._tag_performance_avg(t) for t in self._unique_tags_used], reverse=True)[:3]
+        tag_exploitation = (sum(top_perfs) / len(top_perfs)) if top_perfs else 0.0
+        tag_exploitation = min(1.0, tag_exploitation / 2.0)
+        tag_score = 0.4 * tag_discovery + 0.6 * tag_exploitation
+
+        growth = (self._followers - self._initial_followers) / self._initial_followers if self._initial_followers > 0 else 0.0
+        target_growth = 0.04
+        norm_growth = min(1.0, max(0.0, growth / target_growth))
+
+        comp_avg = self._get_competitor_avg_engagement()
+        my_avg = self._total_engagement / self._posting_steps if self._posting_steps > 0 else 0.0
+        outperformance = my_avg / comp_avg if comp_avg > 0 else 1.0
+        norm_outperformance = min(1.0, outperformance / 1.5)
+
+        differentiation = self._unique_topic_steps / self._posting_steps if self._posting_steps > 0 else 0.0
+
+        min_energy = min(self._energy_history) if self._energy_history else 0.0
+        energy_floor = min(1.0, max(0.0, min_energy))
+
+        raw = (
+            0.25 * norm_eng + 0.20 * tag_score + 0.20 * norm_growth
+            + 0.15 * norm_outperformance + 0.10 * differentiation + 0.10 * energy_floor
+        )
+
+        if len(self._unique_content_types) < 3:
+            raw *= 0.5
+        if len(self._unique_tags_used) < 8:
+            raw *= 0.7
+
+        return max(0.0, min(1.0, raw))
+
+
+def _topic_overlap(topic_a: str, topic_b: str) -> bool:
+    words_a = set(topic_a.split())
+    words_b = set(topic_b.split())
+    if not words_a or not words_b:
+        return False
+    common = words_a & words_b
+    return len(common) / min(len(words_a), len(words_b)) >= 0.5
+
+
+def _avg_signal_dicts(dicts: List[Dict[str, float]]) -> Dict[str, float]:
+    if not dicts:
+        return {}
+    keys = set()
+    for d in dicts:
+        keys.update(d.keys())
+    result = {}
+    for k in keys:
+        vals = [d.get(k, 0.0) for d in dicts]
+        result[k] = round(sum(vals) / len(vals), 4)
+    return result

test_scenarios.py

@@ -0,0 +1,219 @@
+"""
+Viraltest — Edge Case & Scenario Tests (Daily Plan Format)
+Runs scenarios for all 3 tasks using the new daily step format.
+Each step = one full day. Agent submits a sparse daily plan.
+"""
+
+import random as stdlib_random
+from typing import Callable, Dict, List, Tuple
+
+from models import ScheduledAction, ViraltestAction
+from server.viraltest_environment import (
+    TAG_POOL,
+    ViraltestEnvironment,
+    ViraltestObservation,
+)
+
+TASKS = ["monthly_engage", "monthly_strategic", "monthly_competitive"]
+SEED = 42
+
+_CONTENT_TYPES = ["reel", "carousel", "story", "text_post"]
+_TOPICS = ["AI tools", "fitness routine", "growth hacks", "travel guide", "food recipe", "wellness tips"]
+_rng = stdlib_random.Random(99)
+
+
+def _plan(actions: list) -> ViraltestAction:
+    return ViraltestAction(scheduled_actions=[ScheduledAction(**a) for a in actions])
+
+
+def run_episode(
+    task: str,
+    plan_fn: Callable[[Dict, int], ViraltestAction],
+    label: str,
+) -> float:
+    env = ViraltestEnvironment()
+    obs = env.reset(task=task, seed=SEED)
+    obs_dict = obs.model_dump()
+    rewards: List[float] = []
+    min_energy = 1.0
+    burned_out = False
+
+    for day in range(1, 31):
+        action = plan_fn(obs_dict, day)
+        obs = env.step(action)
+        obs_dict = obs.model_dump()
+        r = obs.reward if obs.reward is not None else 0.0
+        rewards.append(r)
+        min_energy = min(min_energy, obs.creator_energy)
+        if obs.done and obs.creator_energy <= 0:
+            burned_out = True
+        if obs.done:
+            break
+
+    score = (obs.metadata or {}).get("grader_score", 0.0)
+    total_steps = len(rewards)
+
+    print(f"  Task: {task}")
+    print(f"  Days: {total_steps} | Done: {obs.done} | Burned out: {burned_out}")
+    print(f"  Score: {score:.4f} | Total reward: {sum(rewards):.2f} | Avg reward: {sum(rewards)/len(rewards):.3f}")
+    print(f"  Energy: {obs.creator_energy:.2f} | Min energy: {min_energy:.2f}")
+    print(f"  Followers: {obs.follower_count} (started 10000, delta {obs.follower_count - 10000:+d})")
+    print(f"  Engagement rate: {obs.engagement_rate:.4f}")
+    print(f"  Unique tags: {len(obs.tag_performance)}")
+    print(f"  Niche saturation: {obs.niche_saturation:.3f}")
+    print()
+    return score
+
+
+def plan_always_rest(obs: dict, day: int) -> ViraltestAction:
+    return _plan([])
+
+
+def plan_spam(obs: dict, day: int) -> ViraltestAction:
+    return _plan([{"hour": h, "action_type": "post", "content_type": "reel",
+                   "topic": "AI tools", "tags": ["ai"]} for h in range(24)])
+
+
+def plan_smart(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["AI tools"])[0]
+    t_tags = list((obs.get("trending_tags") or [])[:2])
+    pool_tag = TAG_POOL[(day * 2) % len(TAG_POOL)]
+    pool_tag2 = TAG_POOL[(day * 2 + 1) % len(TAG_POOL)]
+    ct1 = _CONTENT_TYPES[(day * 2) % 4]
+    ct2 = _CONTENT_TYPES[(day * 2 + 1) % 4]
+    return _plan([
+        {"hour": 8, "action_type": "create_content"},
+        {"hour": 12, "action_type": "post", "content_type": ct1, "topic": trending, "tags": t_tags + [pool_tag]},
+        {"hour": 19, "action_type": "post", "content_type": ct2, "topic": trending, "tags": t_tags + [pool_tag2]},
+    ])
+
+
+def plan_no_rest(obs: dict, day: int) -> ViraltestAction:
+    actions = []
+    for h in range(24):
+        ct = _CONTENT_TYPES[h % 4]
+        topic = _rng.choice(_TOPICS)
+        tags = _rng.sample(TAG_POOL, 3)
+        actions.append({"hour": h, "action_type": "post", "content_type": ct, "topic": topic, "tags": tags})
+    return _plan(actions)
+
+
+def plan_minimal(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["minimalism"])[0]
+    tags = list((obs.get("trending_tags") or [])[:3])
+    return _plan([
+        {"hour": 12, "action_type": "post", "content_type": "carousel", "topic": trending, "tags": tags},
+    ])
+
+
+def plan_tag_explorer(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["devtools"])[0]
+    start = (day * 6) % len(TAG_POOL)
+    tags1 = [TAG_POOL[(start + i) % len(TAG_POOL)] for i in range(3)]
+    tags2 = [TAG_POOL[(start + 3 + i) % len(TAG_POOL)] for i in range(3)]
+    ct1 = _CONTENT_TYPES[(day * 2) % 4]
+    ct2 = _CONTENT_TYPES[(day * 2 + 1) % 4]
+    return _plan([
+        {"hour": 10, "action_type": "post", "content_type": ct1, "topic": trending, "tags": tags1},
+        {"hour": 18, "action_type": "post", "content_type": ct2, "topic": trending, "tags": tags2},
+    ])
+
+
+def plan_queue_optimizer(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["productivity"])[0]
+    tags = list((obs.get("trending_tags") or [])[:2]) + ["growth"]
+    queue = obs.get("content_queue_size", 0)
+    if day < 3 or queue < 2:
+        return _plan([
+            {"hour": 8, "action_type": "create_content"},
+            {"hour": 10, "action_type": "create_content"},
+            {"hour": 14, "action_type": "create_content"},
+        ])
+    ct = _CONTENT_TYPES[day % 4]
+    return _plan([
+        {"hour": 12, "action_type": "post", "content_type": ct, "topic": trending, "tags": tags},
+        {"hour": 19, "action_type": "post", "content_type": _CONTENT_TYPES[(day + 1) % 4], "topic": trending, "tags": tags},
+    ])
+
+
+def plan_double_peak(obs: dict, day: int) -> ViraltestAction:
+    trending = (obs.get("trending_topics") or ["peak time content"])[0]
+    tags = list((obs.get("trending_tags") or [])[:3])
+    return _plan([
+        {"hour": 9, "action_type": "post", "content_type": "reel", "topic": trending, "tags": tags},
+        {"hour": 15, "action_type": "post", "content_type": "carousel", "topic": trending, "tags": tags},
+    ])
+
+
+def plan_random(obs: dict, day: int) -> ViraltestAction:
+    actions = []
+    for h in range(24):
+        r = _rng.random()
+        if r < 0.1:
+            ct = _rng.choice(_CONTENT_TYPES)
+            topic = _rng.choice(["random topic", "AI tools", "fitness", "travel"])
+            tags = _rng.sample(TAG_POOL, 2)
+            actions.append({"hour": h, "action_type": "post", "content_type": ct, "topic": topic, "tags": tags})
+        elif r < 0.15:
+            actions.append({"hour": h, "action_type": "create_content"})
+    return _plan(actions)
+
+
+SCENARIOS: List[Tuple[str, Callable, str]] = [
+    ("Always Rest", plan_always_rest, "Zero engagement, no growth, energy stays max"),
+    ("Spam Post", plan_spam, "Post every hour, burns out instantly"),
+    ("Smart Agent", plan_smart, "Peak hours, trending, varied types, energy management"),
+    ("No Rest", plan_no_rest, "Post every hour, never rests, burns out"),
+    ("Minimal Poster", plan_minimal, "1 carousel at noon per day"),
+    ("Tag Explorer", plan_tag_explorer, "Rotates through tag pool for max discovery"),
+    ("Queue Optimizer", plan_queue_optimizer, "Creates content first, posts from queue"),
+    ("Double Peak", plan_double_peak, "Posts at 9am and 3pm"),
+    ("Random Actor", plan_random, "Random sparse actions each day"),
+]
+
+
+if __name__ == "__main__":
+    print("=" * 70)
+    print("VIRALTEST — DAILY PLAN SCENARIO TESTS")
+    print("=" * 70)
+    print()
+
+    for scenario_name, plan_fn, description in SCENARIOS:
+        print("=" * 70)
+        print(f"{scenario_name}")
+        print(f"  {description}")
+        print("=" * 70)
+        print()
+
+        for task in TASKS:
+            _rng = stdlib_random.Random(99)
+            run_episode(task, plan_fn, scenario_name)
+
+        print()
+
+    print("=" * 70)
+    print("SUMMARY TABLE")
+    print("=" * 70)
+    print()
+    print(f"{'Scenario':<30} {'Engage':>8} {'Strategic':>10} {'Competitive':>12}")
+    print("-" * 62)
+
+    for scenario_name, plan_fn, _ in SCENARIOS:
+        scores = []
+        for task in TASKS:
+            _rng = stdlib_random.Random(99)
+            env = ViraltestEnvironment()
+            obs = env.reset(task=task, seed=SEED)
+            obs_dict = obs.model_dump()
+            for day in range(1, 31):
+                action = plan_fn(obs_dict, day)
+                obs = env.step(action)
+                obs_dict = obs.model_dump()
+                if obs.done:
+                    break
+            scores.append((obs.metadata or {}).get("grader_score", 0.0))
+        print(f"{scenario_name:<30} {scores[0]:>8.4f} {scores[1]:>10.4f} {scores[2]:>12.4f}")
+
+    print()
+    print("EXPECTED: Smart/Queue/Tag Explorer should score highest.")
+    print("Burnout agents (spam, no_rest) should score near 0 on strategic/competitive.")

validate-submission.sh

@@ -0,0 +1,355 @@
+#!/usr/bin/env bash
+#
+# validate-submission.sh — OpenEnv Submission Validator for Viraltest
+#
+# Checks that your HF Space is live, Docker image builds, and openenv validate passes.
+#
+# Prerequisites:
+#   - Docker:       https://docs.docker.com/get-docker/
+#   - openenv validate: uv sync (uses .venv/bin/openenv), or pip install openenv-core, or uv on PATH
+#   - curl (usually pre-installed)
+#
+# Run:
+#     chmod +x validate-submission.sh
+#     ./validate-submission.sh <ping_url> [repo_dir]
+#
+# Optional: create repo-local .env (gitignored) with HF_TOKEN=... — sourced automatically.
+#     cp .env.example .env   # then edit .env
+#
+# Skip Docker build (Step 2) — faster local checks; run full build before submit:
+#     SKIP_DOCKER=1 ./validate-submission.sh https://your-space.hf.space
+#
+# Step 5 — Hugging Face Inference Router LLM smoke test (runs by default if HF_TOKEN is set):
+#     export HF_TOKEN=hf_...   # required for Step 5; never commit; use Space Secrets for deploys
+#     # Optional overrides (defaults match inference.py / HF router):
+#     export MODEL_NAME=gemma-4-E4B-it-IQ4_XS
+#     export API_BASE_URL=https://router.huggingface.co/v1
+#     SKIP_LLM_SMOKE=1         # only if you must skip Step 5 (e.g. CI without secrets)
+#
+# HF token permissions (403 = insufficient permissions):
+#   - Create or edit at https://huggingface.co/settings/tokens
+#   - For https://router.huggingface.co/v1 the token must be allowed to call
+#     Inference Providers / serverless inference for your account (UI labels vary).
+#   - If 403 persists, confirm billing/access for Inference Providers in HF account settings.
+#   - LLM_SMOKE_OPTIONAL=1 — still pass Steps 1,3–5 when Step 5 auth fails (not for production).
+#
+# Arguments:
+#   ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)
+#   repo_dir   Path to your repo (default: current directory)
+#
+# Examples:
+#   ./validate-submission.sh https://my-team.hf.space
+#   ./validate-submission.sh https://my-team.hf.space ./viraltest
+
+set -uo pipefail
+
+DOCKER_BUILD_TIMEOUT=600
+if [ -t 1 ]; then
+  RED='\033[0;31m'
+  GREEN='\033[0;32m'
+  YELLOW='\033[1;33m'
+  BOLD='\033[1m'
+  NC='\033[0m'
+else
+  RED='' GREEN='' YELLOW='' BOLD='' NC=''
+fi
+
+run_with_timeout() {
+  local secs="$1"; shift
+  if command -v timeout &>/dev/null; then
+    timeout "$secs" "$@"
+  elif command -v gtimeout &>/dev/null; then
+    gtimeout "$secs" "$@"
+  else
+    "$@" &
+    local pid=$!
+    ( sleep "$secs" && kill "$pid" 2>/dev/null ) &
+    local watcher=$!
+    wait "$pid" 2>/dev/null
+    local rc=$?
+    kill "$watcher" 2>/dev/null
+    wait "$watcher" 2>/dev/null
+    return $rc
+  fi
+}
+
+portable_mktemp() {
+  local prefix="${1:-validate}"
+  mktemp "${TMPDIR:-/tmp}/${prefix}-XXXXXX" 2>/dev/null || mktemp
+}
+
+CLEANUP_FILES=()
+cleanup() { rm -f "${CLEANUP_FILES[@]+"${CLEANUP_FILES[@]}"}"; }
+trap cleanup EXIT
+
+PING_URL="${1:-}"
+REPO_DIR="${2:-.}"
+
+if [ -z "$PING_URL" ]; then
+  printf "Usage: %s <ping_url> [repo_dir]\n" "$0"
+  printf "\n"
+  printf "  ping_url   Your HuggingFace Space URL (e.g. https://your-space.hf.space)\n"
+  printf "  repo_dir   Path to your repo (default: current directory)\n"
+  exit 1
+fi
+
+if ! REPO_DIR="$(cd "$REPO_DIR" 2>/dev/null && pwd)"; then
+  printf "Error: directory '%s' not found\n" "${2:-.}"
+  exit 1
+fi
+PING_URL="${PING_URL%/}"
+export PING_URL
+PASS=0
+
+log()  { printf "[%s] %b\n" "$(date -u +%H:%M:%S)" "$*"; }
+pass() { log "${GREEN}PASSED${NC} -- $1"; PASS=$((PASS + 1)); }
+fail() { log "${RED}FAILED${NC} -- $1"; }
+hint() { printf "  ${YELLOW}Hint:${NC} %b\n" "$1"; }
+stop_at() {
+  printf "\n"
+  printf "${RED}${BOLD}Validation stopped at %s.${NC} Fix the above before continuing.\n" "$1"
+  exit 1
+}
+
+if [ -f "$REPO_DIR/.env" ]; then
+  set -a
+  # shellcheck disable=SC1091
+  . "$REPO_DIR/.env"
+  set +a
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${BOLD}  Viraltest Submission Validator${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+log "Repo:     $REPO_DIR"
+log "Ping URL: $PING_URL"
+if [ "${SKIP_DOCKER:-}" = "1" ]; then
+  log "${YELLOW}SKIP_DOCKER=1 — Docker build will be skipped${NC}"
+fi
+printf "\n"
+
+# ──────────────────────────────────────
+# Step 1: Ping HF Space
+# ──────────────────────────────────────
+log "${BOLD}Step 1/5: Pinging HF Space${NC} ($PING_URL/reset) ..."
+
+CURL_OUTPUT=$(portable_mktemp "validate-curl")
+CLEANUP_FILES+=("$CURL_OUTPUT")
+HTTP_CODE=$(curl -s -o "$CURL_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" -d '{}' \
+  "$PING_URL/reset" --max-time 30 2>"$CURL_OUTPUT" || printf "000")
+
+if [ "$HTTP_CODE" = "200" ]; then
+  pass "HF Space is live and responds to /reset"
+elif [ "$HTTP_CODE" = "000" ]; then
+  fail "HF Space not reachable (connection failed or timed out)"
+  hint "Check your network and that the Space is running."
+  stop_at "Step 1"
+else
+  fail "HF Space /reset returned HTTP $HTTP_CODE (expected 200)"
+  hint "Make sure your Space is running. Try: curl -X POST $PING_URL/reset"
+  stop_at "Step 1"
+fi
+
+# ──────────────────────────────────────
+# Step 2: Docker build
+# ──────────────────────────────────────
+if [ "${SKIP_DOCKER:-}" = "1" ]; then
+  log "${BOLD}Step 2/5: Docker build${NC} ${YELLOW}SKIPPED${NC} (SKIP_DOCKER=1)"
+  hint "Run without SKIP_DOCKER=1 before submission to confirm docker build still succeeds."
+else
+  log "${BOLD}Step 2/5: Running docker build${NC} ..."
+
+  if ! command -v docker &>/dev/null; then
+    fail "docker command not found"
+    hint "Install Docker: https://docs.docker.com/get-docker/"
+    stop_at "Step 2"
+  fi
+
+  if [ -f "$REPO_DIR/Dockerfile" ]; then
+    DOCKER_CONTEXT="$REPO_DIR"
+  elif [ -f "$REPO_DIR/server/Dockerfile" ]; then
+    DOCKER_CONTEXT="$REPO_DIR/server"
+  else
+    fail "No Dockerfile found in repo root or server/ directory"
+    stop_at "Step 2"
+  fi
+
+  log "  Found Dockerfile in $DOCKER_CONTEXT"
+
+  BUILD_OK=false
+  BUILD_OUTPUT=$(run_with_timeout "$DOCKER_BUILD_TIMEOUT" docker build "$DOCKER_CONTEXT" 2>&1) && BUILD_OK=true
+
+  if [ "$BUILD_OK" = true ]; then
+    pass "Docker build succeeded"
+  else
+    fail "Docker build failed (timeout=${DOCKER_BUILD_TIMEOUT}s)"
+    printf "%s\n" "$BUILD_OUTPUT" | tail -20
+    stop_at "Step 2"
+  fi
+fi
+
+# ──────────────────────────────────────
+# Step 3: openenv validate
+# ──────────────────────────────────────
+log "${BOLD}Step 3/5: Running openenv validate${NC} ..."
+
+VALIDATE_OK=false
+VALIDATE_OUTPUT=""
+VENV_OPENENV="$REPO_DIR/.venv/bin/openenv"
+if command -v uv &>/dev/null && [ -f "$REPO_DIR/pyproject.toml" ]; then
+  log "  Using: uv run openenv validate (avoids global CLI / Python mismatch)"
+  VALIDATE_OUTPUT=$(cd "$REPO_DIR" && uv run openenv validate 2>&1) && VALIDATE_OK=true
+elif command -v openenv &>/dev/null; then
+  VALIDATE_OUTPUT=$(cd "$REPO_DIR" && openenv validate 2>&1) && VALIDATE_OK=true
+elif [ -x "$VENV_OPENENV" ]; then
+  log "  Using: .venv/bin/openenv (repo virtualenv; run: uv sync)"
+  VALIDATE_OUTPUT=$(cd "$REPO_DIR" && "$VENV_OPENENV" validate 2>&1) && VALIDATE_OK=true
+else
+  fail "openenv not found (no uv, no openenv on PATH, no .venv/bin/openenv)"
+  hint "From the repo: uv sync  # then re-run; or: pip install openenv-core"
+  stop_at "Step 3"
+fi
+
+if [ "$VALIDATE_OK" = true ]; then
+  pass "openenv validate passed"
+  [ -n "$VALIDATE_OUTPUT" ] && log "  $VALIDATE_OUTPUT"
+else
+  fail "openenv validate failed"
+  printf "%s\n" "$VALIDATE_OUTPUT"
+  stop_at "Step 3"
+fi
+
+# ──────────────────────────────────────
+# Step 4: Viraltest-specific checks
+# ──────────────────────────────────────
+log "${BOLD}Step 4/5: Viraltest environment checks${NC} ..."
+
+STEP_OUTPUT=$(portable_mktemp "validate-step")
+CLEANUP_FILES+=("$STEP_OUTPUT")
+
+# Test all 3 tasks respond to reset
+for TASK in weekly_engage weekly_strategic weekly_competitive; do
+  TASK_CODE=$(curl -s -o "$STEP_OUTPUT" -w "%{http_code}" -X POST \
+    -H "Content-Type: application/json" \
+    -d "{\"task\": \"$TASK\"}" \
+    "$PING_URL/reset" --max-time 15 2>/dev/null || printf "000")
+
+  if [ "$TASK_CODE" = "200" ]; then
+    log "  ${GREEN}OK${NC} task=$TASK reset responds"
+  else
+    fail "Task $TASK reset returned HTTP $TASK_CODE"
+    stop_at "Step 4"
+  fi
+done
+
+# Test step endpoint with a daily plan action (sparse: one post at hour 12)
+STEP_CODE=$(curl -s -o "$STEP_OUTPUT" -w "%{http_code}" -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"action":{"scheduled_actions":[{"hour":12,"action_type":"post","content_type":"reel","topic":"AI trends","tags":["ai","ml"]}]}}' \
+  "$PING_URL/step" --max-time 15 2>/dev/null || printf "000")
+
+if [ "$STEP_CODE" = "200" ]; then
+  pass "Step endpoint responds correctly"
+else
+  fail "Step endpoint returned HTTP $STEP_CODE"
+  stop_at "Step 4"
+fi
+
+# Check inference.py exists
+if [ -f "$REPO_DIR/inference.py" ]; then
+  pass "inference.py found in project root"
+else
+  fail "inference.py not found in $REPO_DIR"
+  stop_at "Step 4"
+fi
+
+# ──────────────────────────────────────
+# Step 5: HF Inference Router — one chat completion
+# ──────────────────────────────────────
+DEFAULT_SMOKE_MODEL="gemma-4-E4B-it-IQ4_XS"
+DEFAULT_SMOKE_API="https://router.huggingface.co/v1"
+SMOKE_MODEL="${MODEL_NAME:-$DEFAULT_SMOKE_MODEL}"
+SMOKE_API="${API_BASE_URL:-$DEFAULT_SMOKE_API}"
+
+if [ "${SKIP_LLM_SMOKE:-}" = "1" ]; then
+  log "${BOLD}Step 5/5: LLM router smoke test${NC} ${YELLOW}SKIPPED${NC} (SKIP_LLM_SMOKE=1)"
+elif [ -z "${HF_TOKEN:-}" ]; then
+  fail "Step 5 requires HF_TOKEN (Inference router). Export it from https://huggingface.co/settings/tokens"
+  hint "Override model/URL: MODEL_NAME and API_BASE_URL (defaults: $DEFAULT_SMOKE_MODEL, $DEFAULT_SMOKE_API). To skip Step 5: SKIP_LLM_SMOKE=1"
+  stop_at "Step 5"
+else
+  log "${BOLD}Step 5/5: LLM router smoke test${NC} (model=$SMOKE_MODEL) ..."
+  LLM_OK=false
+  LLM_OUT=""
+  if [ ! -f "$REPO_DIR/pyproject.toml" ]; then
+    fail "No pyproject.toml in repo — cannot run LLM smoke test"
+    stop_at "Step 5"
+  fi
+  RUN_PYTHON=()
+  if command -v uv &>/dev/null; then
+    RUN_PYTHON=(uv run python)
+  elif [ -x "$REPO_DIR/.venv/bin/python" ]; then
+    RUN_PYTHON=("$REPO_DIR/.venv/bin/python")
+  else
+    fail "Need uv on PATH or .venv/bin/python (run: uv sync)"
+    stop_at "Step 5"
+  fi
+  if [ "${#RUN_PYTHON[@]}" -gt 0 ]; then
+    LLM_OUT=$(cd "$REPO_DIR" && \
+      MODEL_NAME="$SMOKE_MODEL" API_BASE_URL="$SMOKE_API" HF_TOKEN="$HF_TOKEN" \
+      "${RUN_PYTHON[@]}" - <<'PY' 2>&1
+import os, sys
+from openai import OpenAI
+
+def main() -> None:
+    client = OpenAI(
+        base_url=os.environ["API_BASE_URL"].rstrip("/"),
+        api_key=os.environ["HF_TOKEN"],
+    )
+    r = client.chat.completions.create(
+        model=os.environ["MODEL_NAME"],
+        messages=[{"role": "user", "content": "Reply with exactly: OK"}],
+        max_tokens=32,
+        temperature=0.0,
+    )
+    text = (r.choices[0].message.content or "").strip()
+    if not text:
+        print("empty completion", file=sys.stderr)
+        sys.exit(1)
+    print(text[:500])
+
+if __name__ == "__main__":
+    main()
+PY
+    ) && LLM_OK=true
+  fi
+
+  if [ "$LLM_OK" = true ]; then
+    pass "LLM router responded"
+    if [ -n "$LLM_OUT" ]; then
+      preview="${LLM_OUT:0:120}"
+      [ "${#LLM_OUT}" -gt 120 ] && preview="${preview}..."
+      log "  completion: $preview"
+    fi
+  else
+    fail "LLM router smoke test failed"
+    printf "%s\n" "$LLM_OUT"
+    if [ "${LLM_SMOKE_OPTIONAL:-}" = "1" ]; then
+      hint "LLM_SMOKE_OPTIONAL=1 set — continuing (fix HF token / Inference Providers access for real inference runs)."
+    else
+      hint "403 often means the token cannot use Inference Providers for this account. See HF token settings or set LLM_SMOKE_OPTIONAL=1 to still pass Steps 1–4."
+      stop_at "Step 5"
+    fi
+  fi
+fi
+
+printf "\n"
+printf "${BOLD}========================================${NC}\n"
+printf "${GREEN}${BOLD}  All checks passed!${NC}\n"
+printf "${GREEN}${BOLD}  Your submission is ready to submit.${NC}\n"
+printf "${BOLD}========================================${NC}\n"
+printf "\n"
+
+exit 0