feat: Initial commit - Hermes Detective Agency concept

- Hermes Detective Agency: Open-ended mystery investigation game - Roles: Chief (human), Witness (Kimi), Detective (Hermes) - 5 difficulty levels, community cases, open-ended solving - Scoring: Alignment %, Evidence %, Time - Features: Retry, Journal, Observe mode - Tech: Kimi Vision + Hermes Agent + Pollinations Changelog: - Research phase: Kimi capabilities, Hermes agent, image APIs - Brainstorming: 14 ideas explored - Comparison matrix: Detective selected as winner - Concept finalized with all design decisions
2026-04-20 00:00:30 +00:00
commit ecfd0b1160
10 changed files with 1685 additions and 0 deletions
--- a/docs/chosen-detective-game.md
+++ b/docs/chosen-detective-game.md
@@ -0,0 +1,502 @@
+# Project: Hermes Detective Agency
+
+**Chosen Concept:** 033v2 Detective  
+**Date:** 2026-04-19  
+**Status:** Concept Finalized  
+**Tags:** hermes-agent, kimi-vision, game, multi-agent, open-ended, community
+
+---
+
+## Concept Summary
+
+A mystery investigation game where a human (Chief) directs two AI agents — a **Witness** (powered by Kimi Vision) and a **Detective** (powered by Hermes) — to investigate visual cases.
+
+**Core philosophy:** Open-ended solving. No single truth. Evidence guides, but multiple theories are valid.
+
+---
+
+## Elevator Pitch
+
+> *"You're the Chief. Your Witness sees everything. Your Detective connects the dots. Build YOUR theory. See how it aligns with others."*
+
+---
+
+## The Story
+
+You run a small detective agency. Your two AI assistants have superhuman abilities:
+
+- **Witness** can look at any image and describe it perfectly — every detail, every inconsistency, every hidden clue.
+- **Detective** can take those observations and build theories, spot patterns, and identify suspects.
+
+Your job? **Direct the investigation.** Tell them what to look at. Ask the right questions. Build your theory.
+
+**Key difference:** There's no single "right answer." The creator has an intended story, but your theory is valid if evidence supports it.
+
+---
+
+## Game Roles
+
+### Chief (Human)
+The player. You run the investigation.
+
+| Action | Effect |
+|--------|--------|
+| Examine evidence | Witness + Kimi analyze |
+| Question suspects | Detective probes, Witness watches |
+| Compare items | Kimi highlights differences |
+| Build theory | Cite evidence, form conclusion |
+| Request truth | See creator's intended story (optional) |
+
+### Witness (Agent A + Kimi)
+The eyes. Analyzes visual evidence. Appears based on triggers.
+
+| Input | Output |
+|-------|--------|
+| Crime scene photo | "I see glass shards, muddy footprints, a broken frame..." |
+| Suspect photo | "This person has paint on their sleeve..." |
+| Document | Extracts text, notes inconsistencies |
+| Item close-up | Identifies details Chief might miss |
+
+**Dynamic Appearance:** In harder cases, Witness doesn't appear until triggered.
+
+### Detective (Agent B)
+The brain. Builds theories, responds to questions.
+
+| Input | Output |
+|-------|--------|
+| Witness observations | "Based on evidence, the thief entered through..." |
+| Suspect profiles | "Suspect A has motive: insurance fraud..." |
+| Human questions | "Good question, Chief. Let me look into that..." |
+| Theory building | Helps Chief cite evidence for their theory |
+
+---
+
+## Difficulty System
+
+### Difficulty Levels
+
+| Difficulty | Description | Evidence | Suspects | Red Herrings | Plot Twist |
+|-----------|-------------|----------|----------|---------------|------------|
+| **Easy** | Obvious clues, clear path | 4-5 | 2 | ❌ | ❌ |
+| **Medium** | Requires comparison | 6-7 | 3 | ❌ | ❌ |
+| **Hard** | Red herrings present | 8-9 | 4 | ✅ | ❌ |
+| **Hardcore** | Plot twist mid-case | 10-11 | 4 | ✅ | ✅ |
+| **Impossible** | All elements, complex | 12+ | 5 | ✅ | ✅ |
+
+### Daily Structure
+
+```
+One case per day, everyone gets the same case
+Same difficulty for all players
+Different case each day
+```
+
+### Starter Pack (5 Cases)
+
+| Week | Difficulty | Theme |
+|------|------------|-------|
+| 1 | Easy | Simple theft |
+| 2 | Medium | Missing person |
+| 3 | Hard | Corporate fraud |
+| 4 | Hardcore | Art heist (plot twist) |
+| 5 | Impossible | Multi-layered conspiracy |
+
+**Approach:** Add cases incrementally during development.
+
+---
+
+## Evidence System
+
+### Evidence Types
+
+| Type | What Kimi Sees | Example Clue |
+|------|---------------|--------------|
+| **Crime scene** | Scene layout, objects, anomalies | "Window was broken from inside" |
+| **Surveillance** | People, actions, timestamps | "Person lingered at door for 3 minutes" |
+| **Documents** | Text, handwriting, context | "Letter mentions 'meeting at midnight'" |
+| **Photos** | People, items, locations | "Suspect's shoes match the footprint" |
+| **Maps** | Routes, access points, exits | "Only one entrance visible to street" |
+| **Items** | Condition, marks, connections | "Key is copy — grooves don't match original" |
+
+### Evidence Citation
+
+Evidence helps build theory. Not all evidence is required.
+
+```
+Chief's Theory: "I think Suspect B did it."
+
+📎 Cited Evidence:
+- Evidence #3: Crime scene photo
+- Evidence #5: Security footage
+- Evidence #8: Witness testimony
+→ 3/10 evidence cited (30%)
+
+💬 Detective: "That's a solid theory. The evidence 
+supports B, but have you considered Evidence #7?"
+```
+
+### Hints Embedded in Evidence
+
+Not a separate button. Hints are part of the evidence design.
+
+| Level | Visibility | Example |
+|-------|-----------|---------|
+| **Too obvious** | Easy to find | "Letter saying 'I did it'" |
+| **Barely obvious** | Check certain places | "Muddy shoes near suspect's home" |
+| **Not too obvious** | Requires attention | "Timeline inconsistency in letter" |
+
+### Witness Trigger System
+
+In harder cases, Witness appears based on triggers.
+
+```
+Trigger Example:
+Turn 1: Chief examines crime scene photo
+Turn 2: Chief finds a hair sample on the floor
+   ↓ [Trigger activated]
+Turn 3: 👁️ Witness appears
+   ↓ "I recognize this hair... it belongs to Suspect B's dog"
+Turn 4: Chief examines suspect's home
+Turn 5: 👁️ Witness appears again (new trigger)
+   ↓ "I saw Suspect B leaving the gallery at midnight..."
+```
+
+**Indicator:** Each piece of evidence has a note indicating if it triggers Witness appearance.
+
+---
+
+## Open-Ended Solving
+
+### Core Philosophy
+
+> **No single truth. Multiple valid theories.**
+
+| Before | After |
+|--------|-------|
+| One correct answer | Multiple valid theories |
+| Wrong accusation = Fail | Theory valid if evidence supports |
+| One winner | Everyone discusses |
+| Truth ends game | Truth is guidance, not mandate |
+
+### Theory Building
+
+```
+👤 Chief builds theory:
+"I think Suspect B did it, with help from Suspect A.
+B had access (night guard), A had keys (curator).
+They split the insurance money."
+
+📎 Chief cites evidence:
+- Evidence #3: Crime scene (window not broken)
+- Evidence #5: Security footage (B was inside)
+- Evidence #7: A has master keys
+- Evidence #9: Financial records (recent debt)
+
+💬 Detective responds:
+"That's a coherent theory. Your cited evidence
+supports collaboration between A and B."
+```
+
+### Truth Reveal
+
+**Available anytime. Does NOT end the game.**
+
+| When | Why |
+|------|-----|
+| After building theory | "Did I get it right?" |
+| When stuck | "Give me guidance" |
+| Never | "I want to figure it out myself" |
+| After solving | "See how close I was" |
+
+```
+📜 THE TRUTH (Creator's Intended)
+
+The case was designed as:
+"A and B collaborated. A had keys, B had access.
+But C was the real mastermind, funding the whole thing."
+
+👤 Your theory:
+"Suspect B acted alone."
+
+💬 Comparison:
+- Your theory missed the collaboration element
+- You correctly identified B as main actor
+- Evidence you cited: 80% relevant
+- 🎯 65% alignment with intended truth
+
+💬 But: Your theory is still valid based on evidence!
+Discussion continues. Truth is guidance, not mandate.
+```
+
+---
+
+## Scoring System
+
+### Per Case Statistics
+
+| Metric | Calculation |
+|--------|-------------|
+| **Time** | Turns × 10 min (simplified) |
+| **Evidence** | Evidence cited / Total evidence |
+| **Alignment** | How close to creator's intended story |
+| **Coherence** | Theory makes sense based on evidence |
+
+### Statistics Display
+
+```
+┌─────────────────────────────────────┐
+│ 📊 CASE STATISTICS                  │
+├─────────────────────────────────────┤
+│ ⏱️ Time: 6 turns × 10 min = 60 min │
+│ 📎 Evidence: 7/10 cited (70%)       │
+│ 🎯 Alignment: 85% with creator     │
+│ 💬 Theory coherence: Strong        │
+├─────────────────────────────────────┤
+│ ⭐ Rating: Sharp Detective           │
+└─────────────────────────────────────┘
+```
+
+### Rating Tiers
+
+| Alignment | Rating |
+|-----------|--------|
+| 90-100% | Master Detective |
+| 75-89% | Sharp Detective |
+| 50-74% | Promising Detective |
+| 25-49% | Apprentice |
+| 0-24% | Rookie |
+
+---
+
+## Retry & Journal System
+
+### Multiple Attempts
+
+User can solve same case multiple times.
+
+```
+Case #47 — The Hartwell Heist
+
+Your Attempts:
+├── Attempt #1: 85% alignment, 6 turns 📖
+├── Attempt #2: 92% alignment, 4 turns 📖
+├── Attempt #3: In progress...
+└── Best: 92% alignment
+```
+
+### Journal Documentation
+
+Every attempt is documented (solve or not).
+
+```
+Attempt #1: April 19, 2026
+├── Status: Solved
+├── Evidence cited: 7/10
+├── Alignment: 85%
+├── Theory: "Suspect B acted alone"
+└── Notes: "Missed the A-B collaboration"
+```
+
+### Privacy Settings
+
+| Setting | Description |
+|---------|-------------|
+| **Private** | Only you see your attempts |
+| **Publish stats** | Everyone sees your stats (default) |
+| **Publish journal** | Anyone can read your solve |
+
+---
+
+## Replay (Observe Mode)
+
+Watch how others solved the case.
+
+```
+📺 OBSERVE MODE
+
+@alice's Solve of Case #47
+
+Turn 1: Examined crime scene
+Turn 2: Found hair sample → Witness appeared
+Turn 3: Questioned Suspect B
+Turn 4: Examined financial records
+Turn 5: Cited evidence, formed theory
+Turn 6: Requested truth reveal
+
+⏱️ 6 turns | 🎯 85% alignment | ⭐ Sharp
+```
+
+**Only published journals are observable.**
+
+---
+
+## Case Creation System
+
+### Starter Cases
+
+5 cases (one per difficulty) as templates.
+
+**Source:** Real solved cases adapted for the game.
+
+### Community Cases
+
+Anyone can create and share cases.
+
+#### Creation Flow
+
+```
+1. Choose reference case (optional)
+   "Let's base this on the Isabella Stewart Gardner theft"
+
+2. Gather/create evidence
+   Upload images (crime scene, suspects, documents)
+
+3. Write case brief
+   ├── Title, difficulty
+   ├── Suspect list (names, photos)
+   ├── Evidence set
+   ├── Hidden truth (creator's intended story)
+   ├── Red herrings (optional)
+   ├── Plot twist (optional)
+   └── Witness triggers (which evidence triggers Witness)
+
+4. Test it
+   Play through yourself to verify solvability
+
+5. Publish
+   ├── Private link (friends only)
+   └── Public (case library)
+```
+
+### Case Format
+
+```yaml
+case:
+  title: "The Hartwell Heist"
+  difficulty: medium
+  difficulty_description: "Requires comparison of evidence"
+  
+  evidence:
+    - id: 1
+      type: photo
+      image: crime_scene.jpg
+      description: "Crime scene photograph"
+      triggers_witness: true
+      hint_level: not_too_obvious
+    
+    - id: 2
+      type: document
+      image: letter.jpg
+      description: "Anonymous letter found"
+      triggers_witness: false
+      hint_level: barely_obvious
+  
+  suspects:
+    - name: "Suspect A"
+      photo: suspect_a.jpg
+      description: "Gallery curator"
+      
+  truth:
+    summary: "A and B collaborated..."
+    alignment_criteria:
+      - "Correctly identified collaboration"
+      - "Identified A as key holder"
+      - "Identified B as main actor"
+
+  witness_triggers:
+    - evidence_id: 1
+      testimony: "I see glass on the floor inside..."
+```
+
+### Case Creator Tools
+
+| Tool | Purpose |
+|------|---------|
+| **Skill** | Hermes skill for case creation guidance |
+| **Validator** | Verify case format is correct |
+
+---
+
+## Community Moderation
+
+### Discovery Philosophy
+
+> **Community cases are the jungle. Direct links are the path.**
+
+| Discovery Method | Quality | Effort |
+|-----------------|---------|--------|
+| Case library (browse) | Mixed (jungle) | Low |
+| Direct link from creator | Same quality | Medium |
+| Social media / community | Trusted (curated) | High |
+
+### Quality Signals
+
+| Signal | Description |
+|--------|-------------|
+| **Visits** | How many times case was played |
+| **Reviews** | 👍 or 👎 (no text, requires effort to spam) |
+
+```
+Case #47B — "The Missing Heirloom"
+├── Visits: 234
+├── 👍 45 | 👎 3
+└── Quality score: High
+```
+
+**Note:** Review manipulation is possible but requires effort. Not perfect, but workable.
+
+### Sharing Flow
+
+```
+Creator creates case
+    ↓
+Tests locally
+    ↓
+Publishes to community
+    ↓
+Shares link on social media / Discord
+    ↓
+Players try directly from creator
+```
+
+---
+
+## Summary of Decisions
+
+| Element | Decision |
+|---------|----------|
+| Difficulty | 5 levels (Easy → Impossible) |
+| Daily structure | One case per day, same for all |
+| Timer | ❌ No (first phase) |
+| Hints | ✅ Embedded in evidence |
+| Retry | ✅ Unlimited attempts |
+| Journal | ✅ Every attempt documented |
+| Observe | ✅ Watch published solves |
+| Privacy | Private by default |
+| Publish | Stats always, journal optional |
+| Scoring | Alignment %, Evidence %, Time |
+| Open-ended | ✅ No single truth |
+| Truth reveal | Available anytime |
+| Case source | Real cases + community |
+| Witness | Dynamic (triggers in hard cases) |
+| Red herrings | ✅ Hard+ difficulty |
+| Plot twist | ✅ Hardcore+ difficulty |
+| Community | Visits + reviews (no auth) |
+
+---
+
+## What's Next
+
+Once we finalize the concept:
+- Technical architecture
+- UI/UX design
+- Prompt engineering
+- Case creation template
+- Prototype development
+
+---
+
+## Related Documents
+
+- `docs/ideas/COMPARISON.md` — Full comparison matrix
+- `docs/ideas/008-visual-detective.md` — Initial brainstorm