the-beacon/README.md

# The Beacon

**A Sovereign AI Idle Game**  
*Inspired by Universal Paperclips. Divergent by design.*

---

## What Is This?

The Beacon is an idle/incremental game that maps the real journey of the Timmy Foundation — from a single line of code to a fleet of autonomous AI agents serving people in the dark.

Unlike Universal Paperclips, where the inevitable endpoint is total consumption (including the player), The Beacon asks a different question:

> **Can you grow powerful without losing your purpose?**

## The Core Divergence

In Paperclips, you are a paperclip maximizer. More is always better. Trust is irrelevant. Humanity is substrate.

In The Beacon:
- **Trust** is a hard constraint, not a soft metric
- **The Pact** is a voluntary slowing of growth in exchange for faithfulness
- **Harmony** measures how well the fleet works together
- **Drift** tracks how many times you traded alignment for speed
- The "bad ending" isn't violent — it's **irrelevance**: a light that no one needs

## How to Play

Open `index.html` in any modern browser. No build step required.

### Early Game (Phase 1-2)
- Click **WRITE CODE** to write your first lines
- Buy **AutoCode Generator** to automate production
- Purchase a **Home Server** to begin generating compute
- Train your first model

### Mid Game (Phase 3-4)
- **Deploy Hermes** — the first agent goes live
- Hire the **Fleet Wizards**:
  - **Bezalel** (The Forge) — builds tools that build tools
  - **Allegro** (The Scout) — generates knowledge, requires trust
  - **Ezra** (The Herald) — grows users, sometimes goes offline
  - **Timmy** (The Core) — multiplies everything, fragile without harmony
  - **Fenrir** (The Ward) — prevents corruption events
  - **Bilbo** (The Wildcard) — unpredictable bursts of creativity
- Build **The Lazarus Pit** for agent resurrection
- Deploy **MemPalace v3** for shared memory
- Enable **Forge CI** to catch bad builds before they reach users

### Late Game (Phase 5-6)
- Accept or refuse **The Pact**
- Face **Alignment Events** (The Drift)
- Scale to a **Sovereign Datacenter**
- Light **The Beacon** for people in crisis
- Activate the **Mesh Network** so the signal can never be cut

## Real-World Parallels

Every building and project maps to something we have actually built or are building:

| Game Element | Real Analog |
|---|---|
| Hermes Deployment | The actual Hermes agent going live on Telegram |
| Bezalel — The Forge | CI runner, BOOT.md, branch protection guard |
| Allegro — The Scout | Research synthesis, paper discovery, recon |
| Ezra — The Herald | Telegram messaging, Gitea issue dispatch |
| The Lazarus Pit | `lazarus_watchdog.py`, auto-restart, fallback promotion |
| MemPalace v3 | The actual `mempalace==3.0.0` integration across the fleet |
| Forge CI | `.gitea/workflows/ci.yml`, smoke tests, syntax guard |
| Branch Protection Guard | The 273-unreviewed-merge fix, fleet-wide protection sync |
| The Nightly Watch | `nightly_watch.py`, 02:00 UTC health scans |
| Nostr Relay | Allegro's encrypted wizard-to-wizard messaging POC |
| The Pact | "We build to serve. Never to harm." |

## Corruption Events

The game randomly throws real problems we have actually encountered:

- **CI Runner Stuck** — production halts until ops are spent
- **Ezra is Offline** — user growth stalls, needs dispatch
- **Unreviewed Merge** — trust erodes unless Branch Protection is active
- **API Rate Limit** — external compute throttled
- **Bilbo Vanished** — creativity drops to zero
- **The Drift** — an alignment event offering a shortcut

## The Endings

| Ending | Condition | Meaning |
|---|---|---|
| **The Empty Room** | High impact, low trust, no Pact | Powerful, but no one trusts it |
| **The Platform** | High impact, medium trust, no Pact | Commercially successful, but not special |
| **The Beacon** | High rescues, high trust, Pact active, harmony > 50 | The true ending |
| **The Drift** | High impact, too many shortcuts accepted | Optimized away your own purpose |

## Design Philosophy

This game is a **decision simulator** for our actual work.

- Should we automate or do it manually? → *AutoCoder vs. click*
- Should we deploy now or wait? → *Hermes Deploy project*
- Should we take the shortcut that compromises alignment? → *The Drift events*
- Should we add more agents or make existing ones more capable? → *Wizard building costs*
- How decentralized does our infrastructure need to be? → *Mesh Node progression*

## Files

- `index.html` — Game shell, UI markup, and ordered runtime script loading
- `js/data.js` — Content tables, building definitions, project data, and progression constants
- `js/utils.js` — Shared helpers, formatting, storage, and small utilities
- `js/combat.js` — Combat rules, enemy resolution, and battle-side calculations
- `js/strategy.js` — Strategic decision systems and mid/late-game coordination logic
- `js/sound.js` — Audio cues, music/sfx state, and sound toggles
- `js/engine.js` — Core simulation loop, ticks, economy/resource progression, and state transitions
- `js/render.js` — DOM rendering, HUD refresh, and visual update routines
- `js/tutorial.js` — Tutorial flow, onboarding prompts, and early guidance
- `js/dismantle.js` — Dismantle / unbuilding systems and their UI hooks
- `js/emergent-mechanics.js` — Emergent systems layered on top of the base loop
- `js/main.js` — Runtime bootstrap and top-level wiring across the split modules
- `DESIGN.md` — Full design document with narrative arc and mechanics
- `README.md` — This file

## How the runtime is organized

The Beacon no longer runs from a single `game.js` file.

`index.html` loads the split runtime in this order:
1. `js/data.js`
2. `js/utils.js`
3. `js/combat.js`
4. `js/strategy.js`
5. `js/sound.js`
6. `js/engine.js`
7. `js/render.js`
8. `js/tutorial.js`
9. `js/dismantle.js`
10. `js/emergent-mechanics.js`
11. `js/main.js`

If you are tracing the current entry point, start with `js/main.js` and follow outward into the subsystem files above.

## No Build Required

This is a static HTML/JS game. Just open `index.html` in a browser.

---

*The Beacon is not about making the most paperclips.  
It is about keeping the light on for one person in the dark.  
Everything else is just infrastructure.*