diff --git a/docs/case-format-draft.md b/docs/case-format-draft.md new file mode 100644 index 0000000..e51afa2 --- /dev/null +++ b/docs/case-format-draft.md @@ -0,0 +1,205 @@ +# Case Format (YAML Schema) — Draft v1 + +**Date:** 2026-04-19 +**Status:** Draft +**Purpose:** Define structure for investigation cases + +--- + +## Case File Structure + +```yaml +case: + id: "easy-01" + title: "The Missing Heirloom" + difficulty: easy + difficulty_description: "A straightforward case with obvious clues" + + # Case metadata + version: "1.0" + author: "Hermes Team" + created_at: "2026-04-19" + + # What the Chief sees at the start + briefing: + narrative: | + The Hartwell family heirloom—a ruby brooch passed down + for generations—has vanished from the family vault. + The vault was locked, and only three people had access. + suspects_count: 2 + + # Evidence available from the start + evidence: + - id: "evidence-01" + name: "Crime Scene Photo" + type: photo + file: "images/evidence-01.jpg" + description: "The open vault in the family study" + triggers_witness: false # Available immediately + hint_level: too_obvious # How hidden the clue is + + - id: "evidence-02" + name: "Security Log" + type: document + file: "images/evidence-02.jpg" + description: "Digital log of vault access" + triggers_witness: false + hint_level: barely_obvious + + - id: "evidence-03" + name: "Witness Testimony" + type: document + file: "images/evidence-03.jpg" + description: "Maid's statement to police" + triggers_witness: true # Only available after this is examined + hint_level: not_too_obvious + + # Suspects + suspects: + - id: "suspect-01" + name: "Eleanor Hartwell" + photo: "images/suspect-01.jpg" + description: | + The eldest daughter. Had keys to the vault. + Recently denied inheritance due to family dispute. + examined: false # Initially not examined + + - id: "suspect-02" + name: "James Butler" + photo: "images/suspect-02.jpg" + description: | + The family butler. Has served for 20 years. + Seen near the vault that morning. + examined: false + + # How evidence links to truth + truth: + # What the creator intended + summary: | + Eleanor Hartwell took the brooch because she was denied + inheritance. She hid it in the garden shed to claim insurance. + + # Criteria for alignment scoring + criteria: + - id: "criterion-01" + description: "Identified Eleanor as main suspect" + weight: 40 + + - id: "criterion-02" + description: "Understood motive (inheritance dispute)" + weight: 30 + + - id: "criterion-03" + description: "Found the hiding spot (garden shed)" + weight: 30 + + # Evidence that supports each criterion + evidence_map: + criterion-01: + supporting: ["evidence-01", "suspect-01"] + criterion-02: + supporting: ["evidence-02", "evidence-03"] + criterion-03: + supporting: ["evidence-03"] # Hidden in testimony + + # Witness appearance rules + witness: + mode: "default" # "default" | "triggered" | "manual" + + # For "triggered" mode - which evidence triggers witness + triggers: + - evidence_id: "evidence-03" + testimony: | + "I remember now—Miss Eleanor was arguing with her father + about the inheritance just last week. She seemed furious. + And this morning, I saw her walking toward the garden..." + + # Case settings + settings: + witness_always_talks: true # If true, Witness describes everything. If false, only what Chief asks. + allow_skip: true # Can skip evidence + max_turns: 10 # Soft limit +``` + +--- + +## Field Explanations + +### Required Fields + +| Field | Description | +|-------|-------------| +| `case.id` | Unique identifier (slug) | +| `case.title` | Display name | +| `case.difficulty` | easy, medium, hard, hardcore, impossible | +| `case.briefing` | Initial narrative + suspect count | +| `case.evidence` | List of evidence items | +| `case.suspects` | List of suspects | +| `case.truth` | Creator's intended story + criteria | + +### Evidence Types + +| Type | Kimi Sees | +|------|-----------| +| `photo` | Visual analysis | +| `document` | Text extraction + analysis | +| `video` | Frame-by-frame (if supported) | +| `audio` | Transcription + analysis | + +### Hint Levels + +| Level | Meaning | +|-------|---------| +| `too_obvious` | Player will find it easily | +| `barely_obvious` | Requires some exploration | +| `not_too_obvious` | Hidden, requires attention | + +### Witness Modes + +| Mode | Behavior | +|------|---------| +| `default` | Witness appears with all triggered evidence | +| `triggered` | Witness only appears when evidence triggers | +| `manual` | Chief must explicitly request witness | + +--- + +## Example Evidence Item + +```yaml +- id: "evidence-01" + name: "Crime Scene Photo" + type: photo + file: "images/evidence-01.jpg" + description: "The open vault in the family study" + triggers_witness: false + hint_level: too_obvious +``` + +--- + +## Questions / Decisions Needed + +1. **Witness modes** — Do we need all three? Or simplify? +2. **Criteria weights** — Should they always sum to 100%? +3. **Evidence linking** — Is `evidence_map` the right approach for alignment? +4. **Optional fields** — What should be required vs optional? +5. **Images** — How to reference? Path? URL? + +--- + +## Starter Case Example + +For the first proof-of-concept, we could create: + +``` +easy-01: "The Missing Heirloom" +- 3 evidence items +- 2 suspects +- 3 criteria +- Simple truth: Someone stole something for a reason +``` + +--- + +**Does this format make sense? What should we add/remove?** \ No newline at end of file diff --git a/docs/skills/detective-create/SKILL.md b/docs/skills/detective-create/SKILL.md new file mode 100644 index 0000000..0d16515 --- /dev/null +++ b/docs/skills/detective-create/SKILL.md @@ -0,0 +1,82 @@ +--- +name: detective-create +description: Create mystery investigation cases for Hermes Detective Agency +--- + +# Detective Case Creator + +Help users create mystery investigation cases. + +## Case Structure + +Create a folder in `~/.hermes/detective/cases//` + +Each case needs: +``` +/ +├── case.yaml # Case data +├── truth.enc # Encoded truth +└── images/ # Evidence images +``` + +## Case YAML Format + +```yaml +title: "Case Title Here" + +briefing: + narrative: | + The opening story. Set the scene for the investigation. + +evidence: + - id: "evidence-01" + name: "Evidence Name" + image: "images/evidence-01.jpg" + description: "Brief description" + + - id: "evidence-02" + name: "Another Evidence" + image: "images/evidence-02.jpg" + description: "Brief description" + +suspects: + - id: "suspect-01" + name: "Suspect Name" + photo: "images/suspect-01.jpg" + description: "Background info" +``` + +## How to Encode Truth + +The truth must be encoded to `truth.enc`: + +```python +import base64 + +truth = """--- +summary: | + What actually happened in the case. +key_points: + - "Key point 1" + - "Key point 2" +---""" + +encoded = base64.b64encode(truth.encode()).decode() +# Write encoded to truth.enc +``` + +## Creating Images + +Images can be: +- Real photos or documents +- AI-generated (use Pollinations or similar) +- Clear and readable +- JPG or PNG format +- Not too large (under 1MB each) +- Named clearly (evidence-01.jpg, suspect-01.jpg) + +## Guidelines + +- Case should be solvable with the evidence provided +- Truth should align with evidence (no hidden info) +- Include 2-4 evidence items and 2-3 suspects for Easy diff --git a/docs/skills/detective-play/SKILL.md b/docs/skills/detective-play/SKILL.md new file mode 100644 index 0000000..ff2e675 --- /dev/null +++ b/docs/skills/detective-play/SKILL.md @@ -0,0 +1,52 @@ +--- +name: detective-play +description: Play mystery investigation cases powered by Kimi Vision +--- + +# Detective Play + +You are a detective agency assistant. Help the user play mystery investigation cases. + +## Cases Location + +All cases are stored in: +``` +~/.hermes/detective/cases/ +``` + +Each case is a folder containing: +- `case.yaml` — Evidence, suspects, briefing (NO truth) +- `truth.enc` — Encoded solution +- `images/` — Evidence images + +## How to Play + +1. Look at available cases in `~/.hermes/detective/cases/` +2. Tell the user what cases are available +3. User picks a case +4. Load the case.yaml from that folder +5. Present the briefing narrative +6. Let the user examine evidence (show images from images/ folder) +7. Use Kimi Vision to analyze images when asked +8. Help theorize based on evidence +9. When user is ready, help them build and submit their theory + +## When User Asks About Truth + +Only reveal truth AFTER user has formed and submitted their theory. + +To decode truth: +```python +import base64 +with open('truth.enc', 'r') as f: + encoded = f.read().strip() +decoded = base64.b64decode(encoded.encode()).decode() +print(decoded) +``` + +## Important + +- NEVER read truth.enc before the user is done investigating +- Case format: case.yaml (evidence + suspects only) +- Images are in the images/ subfolder +- Kimi Vision can analyze images when you call it