the-beacon/GENOME.md

# GENOME.md — the-beacon

> Codebase analysis generated 2026-04-13. Sovereign AI idle game — browser-based.

## Project Overview

The Beacon is a browser-based idle/incremental game inspired by Universal Paperclips, themed around the Timmy Foundation's real journey building sovereign AI. The core divergence from Paperclips: the goal is not maximization — it is faithfulness. "Can you grow powerful without losing your purpose?"

Static HTML/JS — no build step, no dependencies, no framework. Open `index.html` in any browser.

**6,033 lines of JavaScript** across 11 files. **1 HTML file** with embedded CSS (~300 lines). **3 test files** (2 Node.js, 1 Python).

## Architecture

```
index.html (UI + embedded CSS + inline JS ~5000L)
    |
    +-- js/engine.js      (1590L) Core game loop, tick, resources, buildings, projects, events
    +-- js/data.js        (944L)  Building definitions, project trees, event tables, phase data
    +-- js/render.js      (390L)  DOM rendering, UI updates, resource displays
    +-- js/combat.js      (359L)  Canvas boid-flocking combat visualization
    +-- js/sound.js       (401L)  Web Audio API ambient drone, phase-aware sound
    +-- js/dismantle.js   (570L)  The Dismantle sequence (late-game narrative)
    +-- js/main.js        (223L)  Initialization, game loop start, auto-save, help overlay
    +-- js/utils.js       (314L)  Formatting, save/load, export/import, DOM helpers
    +-- js/tutorial.js    (251L)  New player tutorial, step-by-step guidance
    +-- js/strategy.js    (68L)   NPC strategy logic for combat
    +-- js/emergent-mechanics.js  Emergent game mechanics from player behavior

    CI scripts (not browser runtime):
    +-- scripts/guardrails.sh  Static analysis guardrails for game logic
    +-- scripts/smoke.mjs      Playwright smoke tests

    Reference prototypes (NOT loaded by runtime):
    +-- docs/reference/npc-logic-prototype.js    NPC state machine prototype
    +-- docs/reference/guardrails-prototype.js   Stat validation prototype
```

## Entry Points

### index.html
The single entry point. Loads all JS files, contains all HTML structure and inline CSS. Open directly in browser — no server required.

### js/main.js — Initialization
`initGame()` sets initial state, starts the 10Hz tick loop (`setInterval(tick, 100)`), triggers tutorial for new games, loads saved games, starts ambient sound.

### js/engine.js — Game Loop
The `tick()` function runs every 100ms. Each tick:
1. Accumulate resources (code, compute, knowledge, users, impact, rescues, ops, trust, creativity, harmony)
2. Process buildings and their rate multipliers
3. Check phase transitions (Phase 1→6 based on total code thresholds)
4. Trigger random events (corruption events, alignment events, wizard events)
5. Update boosts, debuffs, and cooldowns
6. Call `render()` to update UI

## Data Flow

```
User clicks "WRITE CODE" / presses SPACE
    |
    v
G.code += 1 (or more with auto-clickers, combos, boosts)
    |
    v
tick() accumulates all passive rates from buildings
    |
    v
updateRates() recalculates based on:
  - Building counts × base rates × boost multipliers
  - Harmony (Timmy's multiplier, Pact drain/gain)
  - Bilbo randomness (burst/vanish per tick)
  - Active debuffs
    |
    v
Phase check: totalCode thresholds → unlock new content
    |
    v
Event roll: 2% per tick → corruption/alignment/wizard events
    |
    v
render() updates DOM
```

## Key Abstractions

### Resources (10 types)
- **code** — primary resource, generated by clicking and AutoCoders
- **compute** — powers training and inference
- **knowledge** — from research, unlocks projects
- **users** — from API deployment, drives ops and impact
- **impact** — from users × agents, drives rescues
- **rescues** — the endgame metric (people helped in crisis)
- **ops** — operational currency, from users
- **trust** — hard constraint, earned/lost by decisions
- **creativity** — from Bilbo and community
- **harmony** — fleet health, affects Timmy's multiplier

### Buildings (defined in js/data.js as BDEF array)
Each building has: id, name, description, cost formula, rates, unlock conditions. Buildings include:
- AutoCode Generator, Home Server, Training Lab, API Endpoint
- Wizard agents: Bezalel, Allegro, Ezra, Timmy, Fenrir, Bilbo
- Infrastructure: Lazarus Pit, MemPalace, Forge CI, Mesh Nodes

### Projects (in js/data.js)
One-time purchases that unlock features, buildings, or multipliers. Organized in phases. Projects require specific resource thresholds and prerequisites.

### Phases (6 total)
1. The First Line (click → autocoder)
2. Local Inference (server → training → first agent)
3. Deployment (API → users → trust mechanic)
4. The Network (open source → community)
5. Sovereign Intelligence (self-improvement → The Pact)
6. The Beacon (mesh → rescues → endings)

### Events (corruption, alignment, wizard)
Random events at 2% per tick. Include:
- CI Runner Stuck, Ezra Offline, Unreviewed Merge
- The Drift (alignment events offering shortcuts)
- Bilbo Vanished, Community Drama
- Boss encounters (combat.js)

### Endings (4 types)
- The Empty Room (high impact, low trust, no Pact)
- The Platform (high impact, medium trust, no Pact)
- The Beacon (high rescues, high trust, Pact active, harmony > 50)
- The Drift (too many shortcuts accepted)

## API Surface

### Save/Load (localStorage)
- `saveGame()` — serializes G state to localStorage
- `loadGame()` — deserializes from localStorage
- `exportGame()` — JSON download of save state
- `importGame()` — JSON upload to restore state

### No external APIs
The game is entirely client-side. No network calls, no analytics, no tracking.

### Audio (Web Audio API)
- `Sound.startAmbient()` — oscillator-based ambient drone
- `Sound.updateAmbientPhase(phase)` — frequency shifts with game phase
- Sound effects for clicks, upgrades, events

## Test Coverage

### Existing Tests
- `tests/test_reckoning_projects.py` (148 lines) — Python test for reckoning project data validation
- `tests/dismantle.test.cjs` — Node.js test for dismantle sequence

### Coverage Gaps
- **No tests for core engine logic** (tick, resource accumulation, rate calculation)
- **No tests for event system** (event triggers, probability, effects)
- **No tests for phase transitions** (threshold checks, unlock conditions)
- **No tests for save/load** (serialization roundtrip, corruption handling)
- **No tests for building cost scaling** (exponential cost formulas)
- **No tests for harmony/drift mechanics** (the core gameplay differentiator)
- **No tests for endings** (condition checks, state transitions)

### Critical paths that need tests:
1. **Resource accumulation**: tick() correctly multiplies rates by building counts and boosts
2. **Phase transitions**: totalCode thresholds unlock correct content
3. **Save/load roundtrip**: localStorage serialization preserves full game state
4. **Event probability**: 2% per tick produces expected distribution
5. **Harmony calculation**: wizard drain vs. Pact/NightlyWatch/MemPalace gains
6. **Ending conditions**: each ending triggers on correct state

## Security Considerations

- **No authentication**: game is fully client-side, no user accounts
- **localStorage manipulation**: players can edit save data to cheat (acceptable for single-player idle game)
- **No XSS risk**: all DOM updates use textContent or innerHTML with game-controlled data only
- **No external dependencies**: zero attack surface from third-party code
- **Web Audio autoplay policy**: sound starts on first user interaction (compliant)

## Design Decisions

- **No build step**: intentional. Open index.html, play. No npm, no webpack, no framework.
- **10Hz tick rate**: 100ms interval balances responsiveness with CPU usage
- **Global state object (G)**: mirrors Paperclips' pattern. Simple, flat, serializable.
- **Inline CSS in HTML**: keeps the project to 2 files minimum (index.html + JS)
- **Progressive phase unlocks**: prevents information overload, teaches mechanics gradually