docs/ARCS.md

# Arc roadmap

This is the living plan for the game's arcs (skins/backstories). It records the
design rules every arc must follow, what's already built, and the queue of
future arcs so we can pick up any of them later without re-deriving the idea.

Each arc is one self-contained `data/arcs/<id>.json` file plus a
`body[data-skin="<name>"]` block in `static/style.css`. See the README section
*Adding an arc* for the file schema. New arcs appear on the opening screen
automatically.

---

## Design rules (apply to every arc)

The mechanic is fixed: move through a place that should be identical each loop;
**turn back** if something changed, **go on** if nothing did; eight correct
calls in a row wins, one wrong call resets. What differs per arc is the story,
vocabulary, skin — and the *flavour* of the anomalies. Every arc must include:

1. **A strong motivation ("the hook").** A concrete in-world reason you're stuck
   doing this, revealed in the intro — the equivalent of Stairway 8's
   out-of-order elevator. Never "you are being tested" with no diegetic cause.
2. **An NPC.** A recurring character that is normally passive but can become the
   anomaly — turning, watching, approaching, vanishing, duplicating. Every arc
   needs its own recurring uncanny figure.
3. **A loop-aware NPC twist.** At least one NPC anomaly that breaks past physical
   change into the uncanny: the character *acknowledges you* or the loop itself
   (waves, beckons, mouths/says "again"). Property key convention: `knows` for
   silent figures, `speaks` for ones that can talk.
4. **A psychological layer (`sense`).** A non-physical property whose baseline is
   your ordinary state and whose anomalies are perceptual/emotional wrongness —
   losing count, a calm that shouldn't be there, a conviction you're going the
   wrong way. Anomalies beyond objects, per the "twists" requirement.
5. **Meta drift (free).** The engine already drifts the heading, wording, pacing,
   weight, spacing and background every loop — no per-arc work needed, but keep
   `title_variants` themed.
6. **Win-screen strings (in `meta`).** Three short, arc-flavoured lines the exit
   screen needs, so the reward matches the place:
   - `share_prompt` — the invitation above the share row, phrased for this arc's
     exit (Hallway: *Leave the door open.*, Stairway: *Leave the door open
     below.*, Coach: *Hold the doors.*).
   - `attempt` — the "look back" line shown when the run took more than one try.
     **Must contain the `{n}` placeholder** (the run count), spliced in front so
     it localizes cleanly, e.g. *{n} times down this corridor, and this time it
     opened.*
   - `attempt_first` — the line for a clean first run (no placeholder), a small
     reward for a flawless escape, e.g. *First time through, and the corridor let
     you go.*

Keep anomalies *plausible*, never loud. One property mutates per anomalous loop,
and it is always among the details shown that loop (the engine guarantees this).

---

## Shared tuning (all arcs inherit this — do not re-tune per arc)

These curves are engine-wide, not per-arc. A new arc gets them for free; only
change them if you intend to change the feel of *every* arc.

### Difficulty ramp — `hallway.py`

The chance a loop contains an anomaly is a function of the player's level, so the
first stage after entering leans toward "nothing changed" (learn the baseline by
proceeding) and gets harder as you descend/advance:

```
anomaly_chance(level) = min(ANOMALY_MAX, ANOMALY_BASE + ANOMALY_STEP * level)
ANOMALY_BASE = 0.02   # level 0: VERY low, no baseline seen yet
ANOMALY_STEP = 0.076  # per level cleared (steep, to reach the cap by ~L7)
ANOMALY_MAX  = 0.55   # capped so "always turn back" never wins
```

So the opening loop (level 0) is only ~2% (easy 1%, hard 3%), rising steeply to
the cap by around level 7 (normal 55%, easy 30%, hard 60%). The very-low opening
is deliberate: on your first loop you have no baseline, so being turned back
would be a coin flip you cannot win. It is not zero (a rare early jolt keeps the
place honest). Level resets to 0 on a wrong call, which re-eases the first stage,
intentional re-onboarding, not a bug. There is no level-0 floor (the low opening
is the point; levels 1+ ramp well clear of zero so "always continue" still
loses). Because content is *shown* fairly (the mutated property is always among
the details displayed), the ramp changes frequency, never fairness. Guard: keep
`ANOMALY_MAX ≤ ~0.55` or turning back becomes dominant.

### Aggro-item / late reveal (`hallway.py`)

Each arc's `meta.late_props` names a couple of small, inconspicuous properties
(existing details, not new ones). Once per climb, `build()` may **hold some out**
of the early loops so they first surface mid-run. `mem.held` maps each held prop
to its reveal level:

```
reveal level ∈ [2, GOAL-2]   # ~level 2-6 at goal 8, never the last
hold: hard  → always, 1 or 2 items (the "not everything up front" pressure)
      normal → rare (~15%), a single item; rotation is the everyday replay hook
      easy  → never
```

Holding 1-2 items reliably is a **hard-mode** feature. Normal mode leans on the
ordinary fact that only 4-6 of ~9 details show each loop (and Act 2 touch
outcomes vary), so a normal player meets almost every encounter over a few runs
without ever being deliberately starved. Not showing everything every run is a
core principle and the replay hook.

Fairness guard (`mem.seen_props`): an anomaly may only land on a detail the
player has already seen at **baseline on an earlier loop**, so the held item is
never the change on the loop it first appears. Its debut is always a calm
baseline; only later can it move. This keeps a late arrival a memory test, never
pure luck, even at the last level (by then it is long established). Pick
`late_props` that are genuinely minor (a fixture, a small object), never the NPC
or the `sense`.

### Doubt prompt curve — `static/game.js`

The confidence prompt is not shown every turn. After a Go-on/Turn-back choice,
the chance it interrupts grows as you near the exit:

```
chance = min(0.85, 0.12 + level * (0.7 / goal))     # ~12% early → ~73% at level 7
```

- **Certain / Almost sure** (conf ≥ 3) → the choice commits and is judged.
- **Guessing / I think so** (conf ≤ 2) → does *not* commit; returns you to the
  scene for exactly **one** re-decide (the `hesitated` flag blocks a second
  prompt that turn). The re-look is the only "reward" — no points, no safety net.

This is pure client-side UX: confidence never enters the server's correctness
formula (`correct = (choice == "back") == has_anomaly`). New arcs need no work to
inherit it.

### Session state — `app.py`

State is keyed by a client-echoed `sid` (X-Sid header), **not** the session
cookie, so an arc and its progress survive in a cross-site iframe (Spaces). Arcs
never need to touch this.

### Win screen & sharing — engine-wide

The exit screen is shared by every arc; an arc only fills in the three `meta`
strings above. The engine handles the rest:

- **Look back (fleeting run count).** A quiet toggle under "You're out." surfaces
  the arc's `attempt` / `attempt_first` line, then fades after a few seconds and
  reclaims its space so the eye settles on sharing or replaying. The run count is
  a per-session counter in `PlayerMemory` (`attempts`, resets + 1), and the line
  is localized server-side like win text.
- **Sharing.** One of eight cryptic "invitation" lines (shared UI strings
  `share_1..8`) is chosen at random, with the arc's `share_prompt` above it.
  Mobile-first: where a native share sheet exists it is the single button (it
  reaches Instagram, Snapchat, X, Messages, everything); otherwise explicit X /
  Facebook / LinkedIn links plus Copy link. The shared URL unfurls as the game's
  own "8" Open Graph card (`static/img/og.png`).

New arcs inherit all of this for free once the three `meta` strings are set.

---

## Built

*These three are the only production arcs for the current phase. Everything in
"Planned", "Backlog", and "Brainstorm" below is idea-stage only — keep it out of
the live 3-arc game until an idea is deliberately promoted up into this table.*

| Arc | Hook | Loop unit | NPC (+ twist) | `sense` anomalies | Skin |
|-----|------|-----------|---------------|-------------------|------|
| **Hallway 8** (`hallway-eight`) | Locked in after hours; a sign points to the fire exit | corridor | man in grey suit (`knows`: turns/beckons/"again") | longer, forget, calm | cold teal |
| **Stairway 8** (`stairway8`) | Elevator out of order; descend on foot | landing | figure on the stairs below (`knows`: looks up, waves, ascends) | deeper, forget, wrong-way | emergency green |
| **Coach 8** (`coach8`) | Conductor sent you to coach 8; the train never reaches it | carriage | sleeping passenger (`speaks`: murmurs "again", "you were just here") | forget, calm, watched | cabin amber |

---

## Planned (not yet built)

Each entry is enough to implement directly. Ordered by how strong/fresh the loop
feels; pick any.

### Platform 8 (`platform8`) — the underpass
- **Hook:** last train of the night; the turnstiles are shut and a sign routes
  you through the pedestrian underpass — FOLLOW SIGNS TO PLATFORM 8.
- **Loop unit:** identical tiled underpass segments. **Go on** = walk on /
  **Turn back** = double back.
- **NPC:** a busker sitting against the wall with an open case. Twist (`knows`):
  stops playing to watch you; case is suddenly empty/overfull; plays the same
  bar as you pass "again."
- **Physical anomalies:** tiled advert, the drip-puddle, map's "YOU ARE HERE"
  dot, poster date, platform number on the sign, tile colour, a pigeon.
- **`sense`:** the tunnel feels longer; you forget which platform you wanted; a
  certainty you already caught the train.
- **Skin:** cold blue-white station tile (`--hue: 205`).

### Aisle 8 (`aisle8`) — locked in the supermarket
- **Hook:** you looked up and the shop had closed around you; the tannoy loops
  "please proceed to checkout 8 to exit."
- **Loop unit:** identical grocery aisles. **Go on** = next aisle / **Turn
  back** = previous aisle.
- **NPC:** a night-shift stocker with a trolley, back to you. Twist (`knows`):
  turns and stares; trolley abandoned mid-aisle; softly says "again" over the
  muzak.
- **Physical anomalies:** a shelf gap, a product facing the wrong way, a price
  label, the end-cap promo, the muzak track, the abandoned trolley, floor sheen.
- **`sense`:** the aisle feels longer; you forget your list; a calm certainty
  you've already paid.
- **Skin:** flat retail fluorescent, a touch too bright (`--hue: 60`, high L).

### Ward 8 (`ward8`) — the hospital at night
- **Hook:** visiting hours are over; the night sign says the way out is via Ward
  8. *(Handle tone with care — dread, not gore.)*
- **Loop unit:** identical hospital corridors. **Go on** / **Turn back**.
- **NPC:** a patient in a gown standing in a doorway, or a nurse at the far
  station. Twist (`knows`): the figure has moved to the next doorway; is facing
  you; mouths "again."
- **Physical anomalies:** a gurney's position, the room-number plate, a
  flickering "NIL BY MOUTH" sign, the hand-gel dispenser, a chart on a door,
  distant monitor beeps, a wheelchair.
- **`sense`:** the corridor feels longer; you forget why you came; a wrong calm.
- **Skin:** pale clinical green-grey (`--hue: 160`, low sat).

### Level 8 (`level8`) — the underground car park
- **Hook:** your ticket says Level 8; the lift to the street is dead, so follow
  the ramp up. (Ascending mirror of Stairway 8.)
- **Loop unit:** identical parking rows. **Go on** = up a ramp / **Turn back** =
  back down.
- **NPC:** a figure between the parked cars, or someone sitting in a driver's
  seat. Twist (`knows`): the seated figure's headlights flick on as you pass; it
  has moved cars; it waves.
- **Physical anomalies:** a parked car's colour, the level number on the pillar,
  a flickering strip light, the arrow painted on the floor, an oil stain, a
  distant engine, a car alarm.
- **`sense`:** the level feels deeper; you forget where you parked; certainty
  you're descending, not climbing.
- **Skin:** concrete grey with sodium-orange pools (`--hue: 30`, low L).

### Gate 8 (`gate8`) — the airport after the last flight
- **Hook:** you dozed off; the terminal's near-empty and the board shows one
  route left — EXIT VIA GATE 8.
- **Loop unit:** identical concourse stretches / travelators. **Go on** /
  **Turn back**.
- **NPC:** a lone cleaner with a floor-buffer, or a single seated passenger.
  Twist (`knows`): stops buffing to watch; the seated passenger is gone/closer;
  a gate announcement says your name.
- **Physical anomalies:** the gate number, a departures-board row, the duty-free
  window display, an abandoned bag (unsettling), the announcement chime, a clock,
  a potted plant.
- **`sense`:** the concourse feels longer; you forget your destination; a calm
  that you've already boarded.
- **Skin:** glassy blue night-terminal (`--hue: 215`).

---

## Backlog ideas (thin — flesh out before building)

- **Museum after close** — galleries loop; NPC is a security guard or a statue
  that isn't always in the same pose.
- **Motel corridor** — reach room 8 / the exit; NPC is someone at an ice machine.
- **Ferry decks** — climb decks to the exit; NPC a lone smoker at the rail;
  motion + sea outside the windows.

---

## Brainstorm — later phases (idea-stage, NOT production)

Fresh settings that complement the transit/civic bias of the Planned queue: a
knowledge space, a money/dread space, a modern-tech space, a sacred space, and a
play-gone-wrong space — five different emotional registers, still melancholy
rather than violent. Each satisfies the design rules (hook, loop unit, NPC with
a loop-aware twist, physical anomalies, a `sense` property). Suggested skin hues
are candidates only; whichever get built must stay visually distinct from the
live blue/amber/green and from each other.

### Stacks 8 (`stacks8`) — the library at lockup
- **Hook:** the lights dropped to night mode while you read; a card says the way
  out is past Aisle 8 of the stacks.
- **Loop unit:** identical rows of tall shelving. **Go on** = next aisle /
  **Turn back**.
- **NPC:** a night librarian re-shelving from a trolley, back to you. Twist
  (`knows`): stops, turns to watch, mouths "again". Or a reader asleep at a
  carrel (`speaks`: "you already returned it").
- **Physical anomalies:** a book's spine title, a shelf gap, a volume shelved
  upside-down or backwards, the aisle-number sign, a reading lamp on/off, the
  step-stool moved.
- **`sense`:** the aisle feels longer; you forget which book you came for; a
  wrong calm that you've already checked out.
- **Skin:** violet dusk through high windows (`--hue: ~275`). Books are an
  unusually strong anomaly engine — probably the richest of these five.

### Vault 8 (`vault8`) — the bank vault, timelock running down
- **Hook:** your safe-deposit box is in aisle 8; the outer door is on a timelock
  that reopens at dawn, so keep going.
- **Loop unit:** identical corridors of numbered brass boxes. **Go on** /
  **Turn back**.
- **NPC:** a night guard on his rounds (`knows`: stops, watches, nearer) or a
  customer at an open box who won't leave (`speaks`: "you were just here").
- **Physical anomalies:** a box number, a box door ajar, a dropped key on the
  runner, the timelock clock's hands, the carpet runner's colour, a convex
  security mirror's angle.
- **`sense`:** the vault feels deeper; you forget your box number; a calm that
  you've already emptied it; wrong-way.
- **Skin:** crimson carpet + burnished brass (`--hue: ~350`).

### Data Hall 8 (`datahall8`) — the data-centre cold aisle at 3am
- **Hook:** the badge reader sent you to Hall 8 to reseat a server; the lift back
  is locked to your card, so walk the aisle.
- **Loop unit:** identical rows of caged server racks. **Go on** / **Turn back**.
- **NPC:** a lone technician with a laptop cart far down the aisle (`knows`:
  turns, watches, closer) — very modern loneliness.
- **Physical anomalies:** a rack's blinking-LED count, a cage door ajar, a coiled
  cable on the floor, a KVM screen showing your own login, a warm aisle where it
  should be cold, the hum's pitch.
- **`sense`:** the hall feels longer; you forget which rack; the hum stops (a
  diegetic "wrong silence"); a wrong calm.
- **Skin:** indigo LED wash (`--hue: ~265`). The only contemporary/tech setting.

### Cloister 8 (`cloister8`) — the abbey at night
- **Hook:** locked in after the last visitors; complete the eighth circuit of the
  cloister to reach the chapel door.
- **Loop unit:** identical vaulted arcades around a dark garth. **Go on** /
  **Turn back**.
- **NPC:** a cowled figure with a taper at the far arcade (`knows`: turns, raises
  a hand, nearer each loop, mouths "again").
- **Physical anomalies:** a wall sconce lit/dark, a carved boss or gargoyle, a
  statue's pose out in the garth, a grave-slab inscription underfoot, the bell
  (tolls once too many), a stained-glass panel.
- **`sense`:** the walk feels longer; you forget which office you came to pray; a
  wrong serenity; wrong-way (the cloister circles anticlockwise now).
- **Skin:** candle-lit stone, very low saturation warm grey (`--hue: ~35`,
  desaturated so it reads neutral, not Coach's amber).

### Midway 8 (`midway8`) — the shuttered funfair
- **Hook:** you stayed past closing; the only lit exit sign is down the midway,
  past booth 8.
- **Loop unit:** identical stretches of game stalls and strung bulbs. **Go on** /
  **Turn back**.
- **NPC:** a costumed mascot standing dead still by a stall. Twist (`knows`): it
  has turned to face you; it's closer; its head is tilted. (Unsettling without
  gore.)
- **Physical anomalies:** a prize wall, a strung bulb dark/lit, a carousel
  horse's position, a ticket-booth number, the calliope music (loops backward),
  a balloon snagged on a wire.
- **`sense`:** the midway feels longer; you forget which ride you were heading
  to; a wrong festive calm; wrong-way.
- **Skin:** faded pink-and-gold neon (`--hue: ~320`).