# Introduction — How This Machine Is Built

*The engineering commentary track. What this handbook is, what it assumes, and the handful of laws that every line of the anthology obeys.*

This is the maintainer's manual for **BORING SOFTWARE** — an anthology of incremental games, each
disguised as a boring 1998-era desktop utility, all launched from a Windows-98 shell called
**ENTROPY OS**. If the Lore Bible (Disc Two) is the soul, this is the schematic. Read it before you
touch a balance constant.

## What you are looking at

Six files. Each is a complete, self-contained program:

| File | Volume | Lines (approx) |
|------|--------|----------------|
| `index.html` | **Vol I — qBitTorrz** | ~1,870 |
| `defrag.html` | **Vol II — DEFRAG.EXE** | ~1,660 |
| `spreadsheet.html` | **Vol III — MACRO_VIRUS.XLS** | ~1,620 |
| `terminal.html` | **Vol IV — UPLINK** | ~1,870 |
| `inbox.html` | **Vol V — INBOX ZERO** | ~1,760 |
| `desktop.html` | **ENTROPY OS** (the shell) | ~370 |

There is no framework. There is no bundler. There is no `node_modules`. Each game is inline HTML,
inline CSS, and inline vanilla JavaScript in one `.html` file you can open by double-clicking it.
Persistence is `localStorage`. The entire stack is *the browser*. This is a deliberate constraint,
not a limitation we regret — see the law of **Fidelity over flash** below. A self-contained file is
honest software: it boots instantly, it survives being emailed around, and it will still run in a
decade because it depends on nothing that can rot out from under it. (Which, given what these games
are *about*, is a small joke we are proud of.)

## How this handbook is organized

- **Chapter 01 — Architecture & the Shared DNA.** The reference architecture every volume
  re-implements: the number formatter, the global state object, the save/load/sanitize round-trip,
  the tick loop, offline catch-up, toasts, prestige. Read this once and you understand the skeleton
  of all five games.
- **Chapter 02 — Building a New Volume.** The cookbook. A copy-paste skeleton, the requirements
  checklist, how to choose an interaction hook, the balance-tuning methodology, and how to wire a
  new app into the desktop. This is how Volume VI gets made.
- **Chapter 03 — QA Playbook & Post-Mortems.** How these games are actually tested, and the candid
  autopsies of every bug we shipped and caught. The most useful chapter and the most humbling.
- **Chapters 10–14 — The Volume Internals.** One deep, source-accurate dive per game: the state
  shape, the core model, the signature hook's implementation, the upgrade and prestige tables, and
  the balance levers. When you need to change a specific game, start in its chapter.
- **Chapter 15 — The Desktop Shell.** ENTROPY OS itself: the Win98 chrome technique, the windowing
  system, the program registry, and how to add an app.

Throughout, you will find these:

> **DEV NOTE** — a sidebar for the traps, the war stories, and the reasoning behind a choice that
> looks wrong until you know why. When a chapter says "we tried the obvious thing and it broke,"
> this is where the body is buried.

## The prime directives

Every volume in this anthology obeys six design laws. The handbook treats them as load-bearing; the
chapters cite them by name. They are reproduced from `_STYLE.md §5`, which is canon.

1. **Every boring app is a secret incremental game.** Find the loop already in the chrome. A torrent
   client's throughput, a defragmenter's consolidation, a spreadsheet's recalculation — the idle
   game is already there. We just make the subtext text.
2. **The clutter line.** No mascots. No rarity gems. No reroll buttons. No confetti. Status bars,
   monospace, dense tables, dialog boxes with OK/Cancel. *If it looks like a video-game menu, it is
   wrong.* This is the single most important aesthetic rule and the easiest to violate.
3. **One hook, fully committed.** Each game lives or dies on its one novel interaction. Build that
   first and make it *feel good*; the incremental scaffolding is the easy part you can copy from the
   next chapter.
4. **Legible numbers.** The player must always know where the next number comes from. Diegetic
   upgrades, visible formulas, honest gauges. No black boxes.
5. **Respect the idle contract.** The game must play itself while the player is gone and reward them
   for coming back. This law has a body count — see the **DEFRAG entropy death-spiral** in Chapter
   03. The corollary every engineer must tattoo somewhere: *idle must reach equilibrium, never
   death.*
6. **Fidelity over flash.** Nail the boring original first; the game emerges from honest software,
   not decoration.

## Two invariants the code must never break

Beyond the design laws, there are two engineering invariants. Violating either is, by definition, a
release blocker:

- **A save must never brick boot.** Every game loads through `sanitizeState()`, which repairs
  partial, stale, or hand-corrupted saves so that no value of `localStorage` can throw on startup.
  If you add a state field, you add its guard. Chapter 01 shows the pattern; Chapter 03 shows what
  happens when you forget (the **MACRO_VIRUS soft-lock**).
- **The tick must never throw.** The main loop runs ~10 times a second forever. A single uncaught
  exception in `tick()` silently kills the game — the UI freezes mid-number and the player never
  sees an error. The original **qBitTorrz `renderStatus()` crash** (Chapter 03) is the cautionary
  tale: one stale element reference, one throw per tick, a dead game that *looked* alive for exactly
  one frame.

· · ·

A note on tone before we go in: these games are small, but they are not toys, and this handbook is
not a lark. The numbers are tuned, the saves are hardened, the idle contract is honored, and every
bug in Chapter 03 is real and was really fixed. Boring software, built seriously. That is the whole
joke, and the whole craft.

> **If you change anything in this handbook's scope:** keep the two invariants sacred, keep the
> clutter line, and re-run the QA playbook in Chapter 03 against the game you touched. The anthology
> is robust precisely because nothing in it is clever where it does not need to be.