sysadmin-chronicles/docs/design/STORY_DESIGN_CONTEXT.md

# Story Design Context — Sysadmin Chronicles

For story designers and AI agents creating new quests and narrative content.

**Related docs:**
- `CHARACTERS.md` — character bios, relationships, story hooks
- `COMPANY_LORE.md` — world, company, tone
- `QUEST_AUTHORING.md` — technical JSON spec for implementers

This document answers: *how does story actually work in this game, and what does a quest
concept need to contain to be usable?*

---

## The Core Premise

The player is a new junior sysadmin at Axiom Works, a mid-size B2B software company.
They are replacing someone named Dale. Nobody will explain why Dale is gone.

The game is played entirely through a simulated work environment: a terminal, an email
inbox, and a company website. There are no cutscenes, no narration, no inventory, no
combat. Everything that happens is expressed through:

- **Tickets** — the player receives a ticket describing a problem
- **The terminal** — the player SSHes into VMs, investigates, and fixes things
- **Character dialogue** — characters react to how the player solved the problem
- **The next ticket** — the world moves on, and the consequences of what the player
  did are baked into the next situation

That's it. Story is not told — it is accumulated from the choices the player makes
when fixing real Linux problems on real virtual machines.

---

## The Three Machines (VMs)

Every quest happens on one or more of these machines. Their narrative identities
matter as much as their technical roles.

### ares — the Workstation
The player's home machine. Ubuntu 24.04. Quests here are onboarding-flavored —
establishing access, learning the environment. It's the only machine the player
can reach on day one.

*Narrative identity:* Where you start. Safe-ish. The first one you break is here.

### hermes — the Web / App Server
Debian 12. Runs nginx and the AxiomFlow demo/staging application. This is the
machine that Sarah Chen cares about, that customers can feel, and that Priya Nair
watches for security posture. Most of the early-game quests are here.

*Narrative identity:* The product's face to the world. Breaking this makes noise
immediately. The most politically visible machine.

### vulcan — the Build Machine
Arch Linux. Compiles packages, runs the internal build pipeline, serves packages
to hermes via an internal apt repo. Nikhil Sharma owns this in principle but nobody
manages it daily. Things here break silently until hermes starts serving bad software.

*Narrative identity:* The machine nobody watches until something downstream fails.
Quests here reveal that problems have upstream causes the player didn't expect.

### Planned future machines
As the story expands, new machines can be added. Each should have a clear narrative
role before it's introduced. (See `COMPANY_LORE.md` for the candidate list.)

---

## How Story Is Delivered

### Tickets as Act One
Every quest begins with a ticket in the player's inbox. The ticket is a short email
from a character describing a symptom — not a cause. The sender's perception of the
problem is usually incomplete and sometimes wrong. This is intentional: the player's
job is to investigate, not to execute instructions.

Good ticket writing:
- Describes what the sender experienced, not what the cause is
- Has the sender's voice and perspective (Sarah is outcome-focused; Dave is confused;
  Priya is terse and specific)
- Does not hint at the solution
- Creates genuine stakes (site is down, builds are failing, someone is locked out)

Bad ticket writing:
- Explains the root cause ("the log file is too big")
- Has no character voice (generic IT help desk language)
- Stakes are unclear or low

### The Terminal as Act Two
The player investigates. They SSH in, run commands, read logs, check configs, look at
file ownership. The evidence is seeded into the VM baseline — it is genuinely there
to find, not procedurally generated. A good quest has a natural clue trail:

- The most obvious thing points to a second thing
- The second thing reveals the actual problem
- The fix is achievable with real Linux knowledge

The player cannot be told what to do. They can ask Marcus for hints (via dialogue
choices), but good players don't need to.

### Branching Resolution as Act Three
When the player has made changes to the VM, the game checks the state of the
system against the quest's solution branches. The branch that matches determines:

- What dialogue fires (Marcus's reaction, Sarah's reaction, Priya's follow-up)
- What trust delta the player receives
- What world flag is set (persistent story state)
- Whether an incident is triggered (a future consequence of a partial fix)
- What ticket comes next

**This is the central story mechanic.** Every quest should be designed with at
least two and ideally three resolution branches:

| Branch type | What it means |
|-------------|---------------|
| **Clean fix** | Player understood the root cause and solved it properly. High trust, no downstream risk. |
| **Acceptable fix** | Problem is solved but with a tradeoff — brittle approach, future maintenance burden, or incomplete cleanup. Lower trust. |
| **Regression** | Player fixed the symptom but made something else worse. Negative trust. Story consequences. |

The **regression branch** is not about punishment — it's about realism. A real
sysadmin who removes all SSH restrictions to restore one person's access has
technically solved the ticket while creating a larger problem. The story should
treat this as realistic professional consequence, not a game-over failure.

Players on a clean-fix path get more trust, unlock more access, and receive warmer
character reactions. Players on a regression path continue playing but face the
downstream effects of their choices.

---

## World Flags — Persistent Story State

World flags are string keys set when a quest's branch resolves. They persist for
the entire playthrough and can be read by later quests, incidents, and dialogue.

Examples:
- `hermes_logrotate_healthy` — set when the player properly fixed log rotation
- `hermes_ssh_allowusers_fragile` — set when the player restored SSH access using
  the brittle AllowUsers approach instead of the robust AllowGroups approach
- `player_ssh_configured` — set when the player successfully set up SSH on day one

World flags are how story continuity works. A later quest can check whether the
player fixed something correctly earlier and behave differently. Marcus can reference
a past fix. Priya can flag a previously introduced risk in a later audit. A problem
that was "solved" with a quick fix can recur.

**When designing a new quest, ask:** what flag should this set, and what future quests
or dialogue might reference it?

---

## Trust — The Narrative Currency

Trust is a numeric score that tracks the player's professional standing with Marcus
and the IT team. It affects:

- **VM access** — the player gains SSH access to hermes and vulcan as trust increases.
  If trust drops badly, access can be revoked.
- **Documentation access** — more trusted players get access to internal runbooks
  and admin guides
- **Character warmth** — Marcus's messages change tone subtly as trust grows
- **Incident visibility** — at a certain trust level, the player starts seeing
  background incidents before they become critical

Trust is not displayed as a raw number. Players experience it as consequences.

**For quest designers:** each branch should have a `trust_delta` that reflects the
quality of the fix. A proper root-cause fix should earn more than a workaround.
Regression branches should cost trust. Day-one onboarding quests are lenient;
later quests at higher tiers should be less forgiving.

---

## Incidents — Consequences of Incomplete Fixes

An incident is a time-delayed consequence that fires when a quest's partial-fix
branch was taken. It represents the problem coming back.

Example: The player clears a full disk by deleting a log file but doesn't restore
the logrotate config. Two in-game hours later, the disk starts filling again. Dave
notices. The player gets another ticket about the same symptom.

Incidents are not punishments — they are realistic. The world doesn't stay fixed
just because the player touched it. A player who takes clean-fix branches will
rarely see incidents. A player who takes every shortcut will find their ticket queue
filling up with problems they already "solved."

For story purposes: incidents can also carry narrative weight. If the player made a
security regression, an incident could represent an audit finding, an unusual login,
or a configuration discrepancy Priya noticed.

---

## The Character Conversation Model

Quest dialogue fires after a branch resolves. Three characters can speak:

### Marcus Webb
The primary voice. Appears in every quest. His post-resolution message reflects:
- What the player actually did (not just whether they succeeded)
- Whether they understood the root cause or just cleared the symptom
- A forward-looking observation (usually a quiet flag for what's coming next)

Marcus does not praise effusively or scold dramatically. He states what he observed.
His message for a clean fix is warmer and sometimes wry. His message for a regression
is brief and pointed. He never says "well done!" He might say "that's the right call."

### Sarah Chen
Speaks when the quest affects something product-facing (hermes being up or down,
deploys working or failing). Her messages are reactive — she responds to outcomes,
not process. She is not hostile unless the player makes her situation worse.

### Priya Nair
Speaks when the quest has security implications — access changes, hardening,
audit posture. She does end-of-shift reviews that grade overall performance.
Her per-quest messages are brief and evaluative. She notices things Marcus might not.

### Other characters
Dave Okonkwo files tickets. He does not have post-resolution dialogue — he
just stops or starts noticing things. Future characters (Kowalski, Nikhil, Tanya)
can speak in dialogue if quests are designed to involve them.

---

## The Narrative Arc

The overall story has six phases. Quests should be designed with their phase in mind.
The phase is usually not visible to the player — it emerges from what's happening
around them.

### Phase 1 — Normal Work
*Tier 1 quests. Early game.*

The player is new. Everything is routine. Marcus is helpful. The problems are real
but not alarming — a broken config, a full disk, a permission issue. The player is
learning the environment. The subtext is that things are slightly more wrong than
they should be, but there's nothing to point at.

Hidden layer: small anomalies in the systems that curious players can notice but
don't have context for yet.

### Phase 2 — Unease
*Tier 1/2 transition.*

The problems start to have patterns. The same kind of thing breaks twice. A fix
the player made doesn't hold the way it should. Nothing is alarming, but Marcus's
messages have a slightly different quality — he notices things he doesn't explain.

Hidden layer: a world flag from an early quest points somewhere unexpected.

### Phase 3 — Suspicion
*Tier 2 quests. Mid game.*

The player starts encountering problems they didn't cause and can't fully explain.
Access was changed by someone. A config was edited recently. A log shows an
unusual pattern. Nobody is accusing anyone. But the player now has enough context
to start asking questions — even if no quest explicitly tells them to.

This is where Dale becomes relevant again. The systems the player inherits were
last touched by Dale. Some of them have been in a particular state for a long time.

### Phase 4 — Investigation
*Tier 2/3 transition.*

The player has connected enough dots to understand that something happened before
they arrived. The quests in this phase involve digging into logs, access records,
and configuration history. The investigation is framed as professional work
(audit the access logs, trace the package build history) — but the results tell
a story.

Marcus's messages are shorter. Priya starts appearing more. Kowalski schedules a
meeting nobody explains.

### Phase 5 — Conflict
*Tier 3 quests. Late game.*

The player knows what happened. Acting on that knowledge has professional
consequences. The conflict is not physical — it is about what the player chooses
to surface, who they tell, and what they do with access they were given for one
purpose that could be used for another.

### Phase 6 — Resolution
*Endgame.*

The situation resolves. The ending the player gets depends on the world flags
accumulated across their entire playthrough — not just whether they clicked the
"good ending" button. A player who took clean-fix branches throughout, built
trust, and noticed the hidden anomalies gets a different ending than a player
who patched symptoms, lost trust, and missed everything.

---

## What Makes a Good Quest Scenario

The best quests have a **plausible mundane cause** and a **visible technical trail**.
Players should never need to guess — they should be able to find the answer by
looking at the right files and running the right commands.

### Good scenario types
- Service down → config syntax error → player traces error output to the line
- Disk full → log file enormous → logrotate config missing → player restores it
- Deploy fails → files owned by wrong user → someone ran a script as root manually
- Build failures → clock drift → NTP not running → player enables time sync
- Access locked out → sshd_config modified → wrong directive → player corrects it
- App crashes after update → bad package from internal repo → player traces to source

### What makes these work
1. **The symptom is real and urgent.** Something is actually broken.
2. **The cause is discoverable.** The evidence is in logs, config files, or system state.
3. **The fix is a real Linux operation.** Not artificial — `chown`, `systemctl`, editing
   a config, fixing a cron entry, rolling back a package.
4. **Multiple approaches exist.** The quick fix works. The proper fix is better and
   the game knows the difference.
5. **The character reactions are grounded.** Sarah cares about the demo being up.
   Priya cares about the access control implications. Marcus cares about whether the
   player understood what they were doing.

### Bad scenario types to avoid
- Problems that require packages not in the VM's guaranteed baseline (see `QUEST_AUTHORING.md`)
- Problems that require real-time events the validation engine can't check
- Problems where the "correct" fix is the only fix (no meaningful branch differentiation)
- Problems that break the fourth wall or require the player to know game-layer information
- Problems that are gotchas rather than investigations (the cause can't be found by looking)

---

## Hidden Anomalies — Environmental Storytelling

Every 3–5 quests should include something unusual in the VM environment that the player
is not told about and not required to engage with. These are not quest objectives.
They are breadcrumbs for curious players.

Examples of the kind of thing these should be:
- A user account that shouldn't exist
- A log entry from an odd time that doesn't match the official history
- A file that was modified recently but wasn't part of the quest setup
- A cron job that's been disabled but was once important
- An SSH key in authorized_keys that doesn't belong to anyone obvious

These anomalies should be consistent with the overall narrative arc — a player who
collects them across the whole game should be able to piece together what happened
before they arrived. They should never be labelled, never referenced in objectives,
and never required. They are for the players who look.

---

## Quest Output Format for Story Agents

When proposing new quests, provide the following. This is the minimum needed for
a technical author to implement the quest.

```
Quest ID: QXXX
Title: [player-facing]
Narrative phase: [1–6]
Tier: [1, 2, or 3]

Primary VM: [ares / hermes / vulcan]
Additional VMs: [if any]

Scenario summary:
  What is broken, why it is broken (the root cause), and what the player
  will encounter. 1–3 sentences. Written for the implementer, not the player.

Ticket:
  From: [character name]
  Subject: [email subject line]
  Body: [the email the player receives. Written in the sender's voice.
         Describes the symptom. Does not explain the cause.]

Clue trail:
  What the player will find when they investigate. The evidence that leads
  them to the root cause. Describe the actual files, log entries, and system
  states — not the player's steps.

Solution branches:
  Branch 1 (clean fix, highest trust):
    What the player has done. Why it's correct. Trust delta.
  Branch 2 (acceptable fix):
    What the player has done. What tradeoff it introduces. Trust delta.
  Branch 3 (regression, if applicable):
    What the player did wrong. What it breaks. Negative trust delta.

Character reactions:
  Marcus (post-resolution):
    Clean: [what Marcus says]
    Acceptable: [what Marcus says]
    Regression: [what Marcus says]
  Sarah / Priya (if relevant):
    [reaction to the specific outcome that affects them]

World flags set: [list flags each branch sets]
Follow-up incident (if any): [what recurs if the acceptable-fix branch was taken]
Hidden anomaly (if any): [something unusual seeded into the VM that's not part of
  the quest objectives]
Narrative notes: [anything a future quest author should know — Dale connections,
  story threads this opens or closes, things characters should remember]
```

---

## The Dale Thread — Notes for Story Designers

Dale's story should emerge slowly from the systems themselves, not from exposition.
When designing quests — especially mid-to-late game — consider:

- **What did Dale last touch?** The VMs the player inherits have a history. Some
  configurations were made by Dale. Some are good. Some are wrong in ways that
  suggest Dale was dealing with something.

- **What was Dale trying to do?** As the investigation phase develops, the picture
  should become coherent. Dale wasn't random — there was a pattern to their actions.

- **Who knew?** Marcus knew Dale. Priya may have been involved in whatever ended
  Dale's tenure. Kowalski definitely knows. The player assembles this from fragments,
  not a scene where someone explains it.

- **The player is inheriting Dale's problems.** Some of the broken things the player
  fixes are broken because Dale broke them. Some of the broken things were broken on
  purpose. The player won't know which is which until later.

The reveal of what Dale did should feel like the player figured it out, not like the
game told them.