Introduction

Welcome to the HeroTerminal developer docs. HeroTerminal is Mystery-as-Code: noir investigations defined as text + assets in git, layered into the Lens filesystem at runtime.

Core terminology:

• Case File — the full investigation dossier (root directory, manifest, HeroCert).
• Lead — a chapter inside the case with its own brief, evidence, and completion checks.
• Finding / File Report — what the investigator submits to close a Lead.
• Reputation — the scoring unit awarded for clearing Leads.

What you’ll find here:

• How to author Case/Lead YAML.
• How the layered filesystem works (Investigator Home → Lead overlay on ~/desk with drawer rollover).
• How validation and the APIs behave so you can keep the “forensic workstation” illusion intact.

HeroTerminal Universal Protocols: The Core Pillars

Welcome to the Collective.

HeroTerminal is not just a puzzle platform. It is an interactive narrative engine designed to immerse players in grounded, noir-style investigations.

Whether your investigator is a technophobe in Lyon, a hacker in Berlin, or a journalist in Tokyo, every single Case File across the entire platform must adhere to these three core pillars.

If your idea doesn't fit these pillars, it doesn't fit HeroTerminal.

Pillar 1: The Knowledge Mandate

The primary goal of HeroTerminal is edutainment. The player must walk away from every investigation knowing something real about the world that they didn't know before.

1.1. The World is Real

Every case must be grounded in real-world geography.

• Rule: You cannot invent cities. You must use real locations, streets, buildings, and historical contexts.
• Goal: The player should feel like they have virtually visited a place. If a case is set in Hamburg, they should learn about the Speicherstadt district or the history of the port. If it's in Lyon, they learn about the traboules.

1.2. The "Hidden Fact" Requirement

Every Lead (folder) within a case should contain at least one "nugget" of real-world information woven into the narrative or flavor text.

• Good: Solving a puzzle reveals a password.
• Better (HeroTerminal Standard): Solving a puzzle reveals a password which is derived from an obscure historical fact about the building the suspect is hiding in.

Pillar 2: Narrative Immersion

We are creating interactive cinema/literature. The experience should feel like binging a high-quality crime show or reading a gripping noir novel, but the player is in the driver's seat.

2.1. Story Over Puzzles

The technical puzzles (the logs, ciphers, data crunching) exist to serve the story, not the other way around.

• Rule: Never break narrative immersion for the sake of a difficult puzzle. The puzzle must make sense within the context of the scene.
• Goal: The player should feel the tension of the investigation, not the frustration of a math test.

2.2. Atmosphere is Key

The "Flavor" files (descriptions, emails, notes) are just as important as the "Evidence" files. They set the mood, tone, and emotional stakes of the case.

Pillar 3: Grounded Investigation

HeroTerminal is about the process of investigation, respecting human limitations and reality.

3.1. No Superpowers

• Physics applies: No magic, no psychic abilities, no sci-fi tech that doesn't exist today.
• Human Limits: Investigators get tired, they make mistakes, they have biases. The player must navigate these flaws.

3.2. Learning the Process

The player is stepping into the shoes of a professional. They should learn how to think like an investigator:

• Cross-referencing conflicting data sources.
• Following a paper trail across different locations.
• Understanding that human witnesses are unreliable, but logs usually tell the truth (if you know how to read them).

Summary for New Authors: If you can create a compelling mystery that teaches the player a real fact about a real place, while making them feel like the star of a noir thriller, you belong here.

New Investigator Dossier: Submission Template

Instructions: Define your investigator before you write their first case. This establishes their "rules."

🔢 1. The Basics

• Full Name:
• Age:
• Base Location: (e.g., Berlin, London, Tokyo, rural Texas. Must be a real place.)
• Their "Peugeot": (How do they travel? Luc has his old car. Does yours take the U-Bahn? Ride a bicycle? Walk everywhere? This defines their relationship with the city.)

🧠 2. The Psychology & Tone

• The Vibe in 3 Words: (e.g., "Cold, Analytical, Efficient" OR "Chaotic, Charming, Lucky")
• The Major Flaw: (What holds them back? Be specific.)
• Their "Voice": (How do they speak in their notes? Are they poetic? Bullet-pointed? Angry? Funny?)
• Relationship with Tech: (Do they love it? Hate it? Tolerate it?)

🤝 3. The Handler (The "Claire" Equivalent)

• Who gives them assignments?
• What is the dynamic? (Are they enemies? Lovers? A faceless algorithm? An old mentor?)

🗺️ 4. The Territory & Edutainment Focus

• What kind of locations will they explore?
• What kind of "secrets" will players learn from them? (e.g., A Berlin investigator might teach about Cold War infrastructure. A Tokyo investigator might teach about urban density zoning.)

Example Investigator: Klara "Glitch" Weber

• Location: Berlin.
• Vibe: Cold, hyper-technical, socially awkward.
• The Flaw: She can't talk to people (unlike Luc). She only trusts data. If a witness says one thing and the data says another, she believes the data 100% (which is sometimes wrong).
• Their "Peugeot": U-Bahn (subway). She hates going above ground. She describes the world from U-Bahn stations and technical infrastructure.
• Handler: "The Collective" – an anonymous group of hackers in an encrypted chat. No personal connection.

HeroTerminal Authoring: The Luc Vernier Protocols

NOTE TO AUTHORS: This guide defines the specific narrative constraints, tone, and rules for cases featuring Luc Vernier as the lead investigator.

HeroTerminal is a platform designed to host multiple investigators, each with their own unique methods, locations, and rules. If you are creating a new investigator from scratch, these specific rules (Lyon, the Peugeot, Claire) do not apply to you.

However, if you are writing a case for Luc Vernier, treat this document as law. To maintain consistency in his storyline, you must inhabit his world completely.

Welcome to Luc's World

In Luc Vernier's corner of HeroTerminal, we aren't just creating puzzles; we're writing interactive noir grounded in the Rhône-Alpes region of France.

This document outlines how to capture his voice, build his world, and structure his investigations.

1. The Golden Rule: The Place is the Storyteller & The Teacher

The setting is typically Lyon, France, and its surrounding regions. Use real street names, districts (Vieux Lyon, La Part-Dieu), and local culture to ground the story.

We don't create disconnected databases. Each case is a journey.

When the player opens a folder (Lead), they are physically located at a specific place (e.g., Vieux Lyon, The Docks, or The Abandoned Warehouse).

The goal is for the player to experience the atmosphere and learn something real and specific about the location in every single Lead.

The "Hyper-Local" Mandate: The player must walk away from every folder knowing a secret about that place—a historical quirk, a geological fact, or a local legend—that they didn't know before. This isn't a Wikipedia entry; it's "insider knowledge" filtered through Luc's noir lens.

1.1. Luc’s Territory (Geographic Scope)

Luc is based in Lyon, but his cases take him anywhere within a roughly 4-hour driving radius. This includes:

• Lyon & Surroundings: The industrial heart.
• Switzerland (Geneva): High finance, cold efficiency.
• The South (Montpellier/Marseille): Heat, ports, and traffic.
• The Alps (Grenoble/Annecy): Isolation and mountains.

2. Case Structure (The Lead Chain)

A case always follows a linear, geographical progression. Luc Vernier doesn't "teleport." He drives his old Peugeot. The journey between Lead 01 and Lead 02 is part of the story. Use this travel time to describe the changing landscape, the traffic on the A7 autoroute, or Luc's complaints about Swiss border control. The travel builds anticipation for the next location.

Briefing (Claire) ➔ Lead 01 (Location A) ➔ Lead 02 (Location B) ➔ Lead 03 (Final Destination)

• Lead 01: Starting point (e.g., crime scene).
• The Bridge: A clue that points to the next location.
• Lead 02: The pursuit (e.g., witness or hidden location).
• Lead 03: The resolution (e.g., arrest or discovery).

3. Folder Content: What's on the Desk?

Each Lead folder the player opens must contain a mix of the following four types of data:

• 🔹 A. The Flavor (Atmosphere & Lore)

  • Role: To build the world and teach the player something.
  • Examples: Old newspaper articles, historical documents about the building, a cafe menu, a police report about the weather.
  • Note: This does not have to be directly related to the crime, but must be connected to the location.

• 🔹 B. The Hard Evidence (The Technical Puzzle)

  • Role: The actual puzzle that needs to be solved.
  • Examples: Server logs, access logs, IP addresses, license plates, bank transactions.
  • Note: The solution must be an objective fact (Fact-based logic).

• 🔹 C. The Soft Evidence (The Human Element)

  • Role: To give the story heart and show human fallibility.
  • Examples: An audio recording of a witness, email correspondence, call records, a note.
  • Note: People lie or misremember. Computers rarely lie.

• 🔹 D. The Bridge

  • Role: To tell Luc (and the player) where to go next.
  • Examples: Luc's Note confirming the destination and complaining about traffic.

Example Scenario: The Docks

A. Flavor: A scanned pamphlet about the history of Lyon's silk trade routes.

B. Hard Evidence: A shipping container manifest (CSV file) with weight discrepancies.

C. Soft Evidence: An audio recording of a nervous crane operator trying to explain the weight difference.

D. Bridge: Luc's note: "The manifest mentions a warehouse in the industrial zone. The crane operator is lying, but the paperwork points north. Time to drive."

4. Character Voices (Tone of Voice)

The communication between Claire and Luc is the heart of the "meta-story."

How Luc Thinks (Teaching via Monologue)

Luc doesn't just list facts in his notes; he synthesizes them. He looks for anomalies. When you write Luc's notes, teach the player how to think like a detective.

Bad Note: "The IP address is 192.168.1.55."

Good (Luc) Note: "A local IP address in a secure server log? That’s sloppy. Someone was in the building, bypassing the firewall entirely. I need to check physical access logs, not just network traffic."

5. Six Rules for Authors

1. No Sci-Fi Tech: Technology should be realistic (Unix commands, logs, IP addresses). No "Enhance" buttons or magic tricks.
2. The Story is Noir: The world is rainy, dirty, and full of human error.
3. Educational Value: The player should leave knowing something new (e.g., how a port works or how timestamps work).
4. No Teleport: If Luc goes from A to B, there must be a record of it (gas receipt, note about traffic).
5. Clear Resolution: Each puzzle must end with a clear outcome that moves the story forward (Name, Place, Time).
6. Lore is Everywhere: Use Lyon Herald articles, blog posts, and forum threads to deepen the world.

📋 Case Template (Copy/Paste)

Below is a template you should use when writing a new case.

# CASE TITLE: [Case Name]
# AUTHOR: [Author Name]
# DIFFICULTY: [Easy / Medium / Hard]

---

## 📨 1. BRIEFING (Claire & Luc)
**Context:** Why are we here? Who is the client?
**Claire (Email/Msg):** "[Corporate speak introduction to the problem]"
**Luc (Personal Note):** "[Sarcastic translation of what Claire said + travel plan]"

---

## 📍 2. LEAD 01: [Location Name, e.g., The Old Bank]
**Location Vibe:** [Short description of the location for designers/players]

**📂 FILES ON DESK:**
1.  **Flavor (Lore):** [File name + Description of content]
2.  **Hard Evidence (Puzzle):** [File name + How the puzzle works]
3.  **Soft Evidence (Witness):** [File name + What does the witness say?]

**🗝️ FINDING LOGIC:**
* **Input:** [What data does the player use?]
* **Output:** [What does he find? e.g., License plate]
* **The Bridge (What connects to the next lead?):** [E.g., An address found in the shipping manifest points to the warehouse.]

---

## 📍 3. LEAD 02: [Location Name, e.g., The Garage]
**Luc's Travel Log:** "[Short text about the journey from Lead 01]"

**📂 FILES ON DESK:**
1.  **Flavor (Lore):** ...
2.  **Hard Evidence (Puzzle):** ...
3.  **Soft Evidence (Witness):** ...

**🗝️ FINDING LOGIC:**
* **Input:** ...
* **Output:** ...
* **The Bridge (What connects to the next lead?):** [E.g., An address found in the shipping manifest points to the warehouse.]

---

## 🏁 4. CONCLUSION (Final Destination)
**Luc's Final Report:** "[How did the case end?]"
**Claire's Feedback:** "[Was she happy with 'KPIs'?]"

📁 The Vernier Clan (Canon Data)

1) Luc Étienne Vernier (The Protagonist / The Analog Architect)

• Born: Nov 12, 1978 (Scorpio), 47

• Role: Independent Contractor / Forensic Technician. The Architect of the Lens platform.

• Based: Lyon (A small, cluttered apartment in Croix-Rousse that smells of old paper and espresso).

• Current Situation: Until late 2023, Luc was a part-time father. Élise lived with her mother in Provence. After "The Incident," Élise moved in with him in Lyon full-time. He is now drowning in casework AND trying to raise a rebellious teenage daughter in a cramped apartment that wasn't meant for two people.

• Status within HeroTerminal: He is not Claire's employee. He is a high-level independent contractor.

• The Deal: Luc refuses to hold shares in HeroTerminal. However, he agreed to the licensing of Lens on one condition: a significant equity stake was placed in a trust for his daughter, Élise, which she inherits at age 25.

• Motivation: The unsolvable disappearance of his father, and now, the terrifying reality of being the sole stabilizing force in his daughter's life. The deal with Claire (the trust fund) is now essential for her future.

• The Paradox (Why he built Lens): Luc is a technophobe who is paradoxically a brilliant systems architect. He built Lens out of frustration with existing tools. To him, it's not software; it's a necessary workbench to organize the chaos he gathers in the field.

• Methodology (The Field Operator): Luc refuses to run investigations solely from a screen. He drives his father's old Peugeot 504 to the physical location to gather sensory data before using Lens.

• Motivation: The unsolved disappearance of his father. A deep need to prove that human grit and intuition still matter in an automated world.

• Luc’s Note on Himself: “Claire tried to buy me with shares. I told her I don't want her corporate paper. We made a deal: the platform is hers to sell, but the future belongs to Élise. I'll do the work, I'll use the tools, but I won't become one of them. I do this so my daughter never has to rely on anyone.”

2) Claire Dominique Vernier (The CEO / Older Sister)

• Born: Jan 4, 1975 (Capricorn), 50
• Role: CEO of HeroTerminal; the corporate shield. She is the "break glass in case of emergency" option when Luc’s street-level methods blow up in his face.
• Based: Paris (La Défense).
• Personality: Controlling, protective, fiercely pragmatic. She views Luc’s adherence to "old-school honor" as a dangerous liability.
• Relationship to Luc: She respects his integrity but finds it maddeningly impractical. She knows the only way to get him to cooperate is by framing it as being "for Élise's sake." She uses the trust fund as a subtle reminder of why he needs her network to succeed.
• Luc’s Note: “We despise each other’s worlds. She thinks I’m a dinosaur; I think she sold her soul to shareholders. I don't take her money—I have my pride. But she's the only one with the leverage to fix things when the law fails, and she's holding Élise's future. I hate that I need her influence.”

3) Julien Christophe Delacroix (Claire’s Husband / The Fixer)

• Born: May 18, 1972, 53
• Role: M&A Partner; the mechanism of Claire's help. He set up the trust structure for Élise.
• Relationship: They loathe each other. Luc distrusts his motives.
• Luc’s Note: “He calls me a 'technician'. I call him an empty suit. He set up the trust for Élise, and I'm sure he buried a dozen loopholes in it for Claire. I don't owe him anything; he's just her tool.”

4) Sylvie Hélène Vernier (Younger Sister / The Archivist)

• Born: Sep 22, 1976 (Virgo), 49
• Role: Head Archivist, Bibliothèque de Lyon; neutral, precise, remembers everything; source for offline records.
• Based: Lyon.
• Relationship: Ally to Luc, nonjudgmental; supplies old newspapers/church records.

5) Madeleine Yvette Vernier (née Dubois) “Maman”

• Born: Mar 14, 1948, 77
• Role: Widowed; anchor of the family; Sunday cooking.
• Based: Lyon (old family apartment).
• Relationship: Knows Luc is chasing his father; avoids the topic.

6) Élise Marie Vernier (The Daughter / The Runaway)

• Born: Jun 14, 2009, 16
• Role: Student, rebellious teenager.
• Current Location: Living with Luc in Lyon (since Nov 2023). Before that, she lived with her mother and stepfather in Aix-en-Provence.
• Personality: Smart, angry, hates phoniness. She despises her stepfather Alexis and the fake wealth he represents. She adores her aunt Claire ("La Marquise") for her genuine power. She loves Luc but finds his lifestyle frustratingly stubborn.
• The Incident (Nov 2023): Rebelling against life with Alexis, she ran away to Paris with friends. They got caught shoplifting high-value items at Galeries Lafayette. It wasn't just teen acting out; it was a cry for help.
• The Rescue: Luc didn't know she was in Paris until he got the call. Helpless in the capital, he forced himself to call Claire. Claire sent Julien to fix the legal mess.
• The Fallout: It became clear she couldn't stay in Provence. Luc stepped up and took her in. She wants to be with him, even though it's harder, because it's "real."

7) Jean Paul Vernier (The Father / The Ghost)

• Born: Jun 20, 1946
• Disappeared: Jan 12, 2000
• Role: Detective Inspector (Police Nationale); missing/presumed dead.
• Legacy: Left Luc the Peugeot, the investigative mind, and a void.

8) Camille Sophie Moreau (née Laurent) - (The Ex-Partner / The One Who Escaped)

• Born: Apr 18, 1980 (Aries), 45
• Role: Élise’s mother. Luc’s former long-term partner (they never married).
• Based: Aix-en-Provence (Luxury villa).
• The Backstory: Left Luc years ago because she couldn't live with the ghost of his father. Married a wealthy, stable man (Alexis) to give Élise a "good life."
• The Failure: She loves Élise deeply but couldn't control her rebellion against Alexis. The Paris incident broke her confidence as a mother. She agreed that Élise needed to be with Luc.
• Relationship to Luc now: No lawyers. They talk directly. There is mutual respect mixed with sadness. She wants Élise to visit, but knows Élise prefers Luc's "authenticity" over her comfortable life. Luc doesn't blame her; he blames Alexis.

9) Alexis Victor Moreau - (The Stepfather / The Slick Empty Suit)

• Born: Dec 5, 1975, 49
• Role: Camille’s wealthy husband. Private wealth management in Southern France.
• Vibe: Slicked-back hair, expensive suits, polished exterior with nothing underneath.
• Relationship to Élise: Disaster. He tried to buy her affection with gifts (horses, designer clothes). When that failed, he viewed her as a "damaged asset". He is secretly relieved she moved to Lyon.
• Luc's Note: "He had ten years with her in sunshine and luxury and he blew it because he’s empty inside. Now I have to fix the damage in the rain in Lyon. I don't hate him for taking Camille; I hate him for failing Élise."

10) Antoine Marc Besson (Friend / The Muscle)

• Born: Jul 12, 1978 (same age as Luc)
• Role: Head of Security (Private) / ex-Police. Best friend; was fired in 2010 (Luc wrote the report; Antoine eventually forgave him).
• Value: Physical access (doors, CCTV), “old police favors,” friends on the force.

11) Henri Jacques Gautier (Friend / The Old Badge)

• Born: Feb 2, 1950, 75
• Role: Retired Commissaire; best friend of Luc’s father Jean.
• Value: Protects Luc inside the police when he can; warns him not to dig too deep.

Mystery-as-Code

HeroTerminal treats every investigation as code. Content lives in git and is layered into Lens at runtime:

• Investigators (investigators/<id>/home/**): persistent personal files (music, inbox, notes).
• Case Files (cases/<case-key>/case.yaml): metadata, leads, reputation, briefing, hero cert text.
• Lead Assets (cases/<case-key>/fs/lead-XX/**): evidence for a single lead. These are mounted onto ~/desk/ for the active lead.

Why this matters:

• Deterministic: same repo -> same workstation state; easy to diff and review.
• Auditable: everything versioned; no hidden database data.
• Composable: investigator home + case + lead overlay -> single sandbox for Lens.

Content authors change YAML and files, then redeploy. No database migrations required for story data.

Lens Filesystem Architecture

Lens builds a virtual filesystem by stacking authored layers. The player only sees a single Workspace, but behind the scenes Investigator, Case, and Lead assets are overlaid with strict precedence.

Asset Hierarchy (what belongs where?)

• Investigator Assets (Inventory): Old Luc personal belongings (e.g., Personal notes, Old emails, shopping lists). Lives in investigators/<id>/fs/**.
• Case Assets (Starting Desk): Files Claire/Sylvie send at the start (maps, background briefs, manuals). Lives in cases/<case>/fs/**.
• Lead Assets (Evidence): Items discovered while solving a lead (scent strip, copper flask, chemical vial). Lives in cases/<case>/fs/<lead-key>/** and only appear when that lead is active.

Directory Layout at Runtime

• / — Workspace (merged Investigator + Case layers).
• /desk/ — Active Lead evidence.
• /desk/drawer/ — Archived evidence from completed leads.

Authoring Rules

• Put global investigator files in investigators/<id>/fs/** → becomes /....
• Put case-wide files in cases/<case>/fs/** → becomes /... (you can place them under a subfolder like /desk/ if you want them on the desk from the start of every lead).
• Put lead-specific files in cases/<case>/fs/<lead-key>/** → becomes /desk/... while that lead is active.
• Do not author anything into /desk/drawer; rollover is automatic.

Overlay Precedence (highest wins)

Lead Layer > Case Layer > Investigator Layer

If two layers define the same path, the active lead file wins, then case, then investigator.

Desk Lifecycle

1. Start of a lead: /desk/ is populated with the active lead’s assets plus any case files you placed under /desk/.
2. Complete a lead: everything in /desk/ is moved to /desk/drawer/<lead-key>/.
3. Next lead starts with a fresh /desk/, but the drawer keeps history.

Example: “The Midnight Harvest”

State: Investigator lvernier; active case 2025-lvernier-the-midnight-harvest; Lead 1 solved, Lead 2 active.

Authored sources

• Investigator: fs/playlist/blues.m3u, fs/personal/elise/2023_incident_galeries.eml
• Case (global): fs/desk/map_grasse_valley.svg, fs/desk/clipping_lyon_herald.svg, fs/desk/doc_lab_codes.md, fs/desk/manual_refractometry.md, fs/desk/dossier_helene_vasseur.txt
• Lead 02: fs/lead-02/tool_refractometer_view.svg
• Lead 01 (completed, rolled into drawer): fs/lead-01/evidence_mouillette_strip.svg, fs/lead-01/log_visual_inspection.txt

What Luc sees

/ (Workspace)
├── playlist/
│   ├── blues.m3u                      <-- Investigator
├── personal/elise/
│   └── 2023_incident_galeries.eml     <-- Investigator
└── desk/
    ├── map_grasse_valley.svg          <-- Case asset (available every lead)
    ├── clipping_lyon_herald.svg       <-- Case asset
    ├── doc_lab_codes.md               <-- Case asset
    ├── manual_refractometry.md        <-- Case asset
    ├── dossier_helene_vasseur.txt     <-- Case asset
    ├── tool_refractometer_view.svg    <-- Active lead-02 evidence
    └── drawer/
        └── lead-01/
            ├── evidence_mouillette_strip.svg  <-- Archived after lead-01
            └── log_visual_inspection.txt      <-- Archived after lead-01

Use this pattern for future cases: keep evergreen gear in the investigator layer, ship onboarding materials in the case layer, and drop clue-by-clue evidence into each lead. The overlay will do the rest.

Case File Design Overview

HeroTerminal Case Files are structured noir investigations. Each Case File bundles a set of Leads, and the HeroCert that investigators earn upon completion.

A healthy Case File includes:

• A clear theme or incident narrative.
• 3–6 Leads that escalate in difficulty.
• Consistent Reputation awards aligned with the global rules.
• Optional supporting assets such as inbox messages, or overlays.

Use this section together with the Case File manifest (case.yaml) and Lead references to plan your story before touching YAML. Sketch the incident, define the investigation beats, then translate them into Leads with concrete Findings.

The case.yaml Manifest

The Case File manifest (case.yaml) is the entry point for your investigation. It defines the metadata, the author, the case briefing, and the Leads an investigator will work through.

File Structure

A Case File is a single directory in the Case Files repository.

2025-lvernier-the-dockyard-protocol/
├── case.yaml           <-- This file
├── herocert.svg        <-- (Optional) Custom badge
├── fs/                 <-- Filesystem overlay (desk)
└── leads/
    ├── lead-01.yaml
    ├── lead-02.yaml
    └── lead-03.yaml

case.yaml Specification

Author Block (author:)

author:
  # (Required) The display name for the creator.
  name: "Hero Terminal"
  # (Required) The creator's GitHub username.
  github: "heroterm"

Example case.yaml (from The Dockyard Protocol)

key: "2025-lvernier-dockyard-protocol"
title: "The Dockyard Protocol"
difficulty: "beginner"
investigator: "lvernier"
summary: "A ghost shipping container appears in Lyon with no manifest and a suspicious hum. Find out what is inside and who hid it."

author:
  name: "HeroTerminal team"
  github: "heroterminal"

briefing: |
  LOCATION: Port Édouard Herriot, Lyon
  SOURCE: Antoine Besson (Private Security)
  HANDLER: Claire Vernier
  A 40-foot shipping container exists physically but not in the registry. Pull the data dump and find who hid it.

leads:
  - key: "lead-01"
    title: "The Ghost Container"
    reputation: 50
    briefing: "Find the missing container ID and its declared cargo."
    solution:
      logic:
        all:
          - submission:
              contains: "LXRU-881203-7"
          - submission:
              contains: "V12_ENGINE_BLUEPRINT"
  - key: "lead-02"
    title: "The Access Trail"
    reputation: 50
    briefing: "Correlate badge access with RFID reads to find the abused badge."
    solution:
      logic:
        any:
          - submission: { contains: "AC-221" }
          - submission: { contains: "Marc Duret" }

herocert:
  title: "Lyon Docks Investigator"
  subtitle: "Solved: The Dockyard Protocol"
  description: "Identified the ghost container, traced the access trail, and exposed the insider."

The herocert Spec

Every Case File awards a HeroCert when all Leads are completed. The herocert block in case.yaml controls how that certificate is rendered on app.heroterminal.com and in public share links.

Example (The Dockyard Protocol)

herocert:
  title: "Lyon Docks Investigator"
  subtitle: "Solved: The Dockyard Protocol"
  description: |
    Identified the ghost container, reconstructed the tampered manifests,
    uncovered fraudulent internal access, and attributed the manipulation
    to the responsible party.
  default_sharing_text: "I just closed The Dockyard Protocol in Lens."

Tips

• Keep titles under 60 characters.
• Use action verbs in subtitle/description so the accomplishment feels heroic.
• Provide a custom herocert.svg (200x200) if the standard badge does not fit your theme.

Hero Terminal – Reputation Guidelines (v2)

📊 Lead Valuation Standard

Reputation Points (reps in UI copy) should reflect the complexity of the investigative step and the technical knowledge required to solve it.

• Beginner Lead: 25–75 Reputation Points
• Intermediate Lead: 75–150 Reputation Points
• Advanced Lead: 150–250 Reputation Points

📏 The Rules of Engagement

1. The Ceiling: Never assign more than 250 Reputation Points to a single Lead.
2. The Floor: Never go below 10 Reputation Points (unless it's a pure tutorial step).
3. Case Totals: For a standard Case File (3–5 Leads), the total payout should generally land between ~200 and 600 Reputation Points.
4. The Splitting Rule (Crucial): If you think a single Lead deserves more than 250 Reputation Points, it is too complex. Split it into multiple, smaller Leads.

The lead.yaml Manifest

Each file in the leads/ directory defines a single Lead, its environment, and its solution.

Example lead-01.yaml

key: "lead-01"
title: "The Ghost Container"
reputation: 50

briefing: |
  The port registry shows a gap in the container sequence. One container is physically present on the dock, but its manifest entry is missing.

  Your focus:
  - Open the manifest export and registry logs on your desk.
  - Find the container that "should not exist."
  - Submit the container ID and the declared cargo reference.

environment:
  initial_filesystem:
    "/desk/logs/manifest_export.csv": |
      # ...redacted sample data...
    "/desk/logs/registry.log": |
      # ...redacted sample data...

solution:
  logic:
    all:
      - name: "Container ID submitted"
        submission:
          contains: "LXRU-881203-7"
      - name: "Cargo reference submitted"
        submission:
          contains: "V12_ENGINE_BLUEPRINT"

Defining the Solution (solution)

The solution block defines what constitutes a "win". In Lens, submissions are validated directly against the text the investigator sends with the submit command.

solution:
  logic:
    all:  # Can be 'all' (AND) or 'any' (OR)
      - name: "Container ID submitted"
        submission:
          contains: "LXRU-881203-7"
      - name: "Cargo reference submitted"
        submission:
          contains: "V12_ENGINE_BLUEPRINT"

Check Types

• submission: Checks the investigator’s submitted text.
  • equals: optional exact match
  • contains: required substring
  • regex: optional regular expression

Combine all/any blocks to express complex requirements. Keep checks descriptive so Lead failure messages help investigators understand what remains.

Legal

HeroTerminal Developer Docs are covered by the same Terms of Use and Privacy Policy that govern heroterminal.com, app.heroterminal.com, and the HeroTerminal API. By contributing or using these docs, you agree to:

• HeroTerminal Terms of Use
• HeroTerminal Privacy Policy

Please review those documents before submitting Case Files or relying on this material.