bitmax/docs/_STYLE.md

# _STYLE.md — Canon & House Style (read this first)

*Single source of truth for the* **Boring Software: Collector's Edition** *companion docs.
Every chapter — handbook or lore — must obey this file. If something here conflicts with your
own instinct, this file wins. If something here conflicts with the actual source code, the
**source code wins for facts** (names, numbers, formulas) and this file wins for **voice**.*

---

## 0. What we are making

A two-tome "special features" library for an anthology of five incremental games disguised as
boring desktop utilities, plus the Win98 shell that launches them (`desktop.html` = **ENTROPY OS**).

- **THE DEV HANDBOOK** (`docs/handbook/`) — an engineering manual. Precise, exhaustive, true to the
  code. Think: the commentary track + the technical bible a studio ships to its own engineers.
- **THE LORE BIBLE** (`docs/lore/`) — the world & story, fleshed into chapters. Literary, eerie,
  melancholy-cosmic. Think: the leather-bound companion book in the limited box.

This is collector-edition content. **Go hard.** Depth over brevity. Every chapter should be
substantial (handbook chapters ~1200–2600 words; lore chapters ~1100–2200 words) and *load-bearing*
— no filler, no restating the same paragraph twice. Pull concrete detail from the real files.

---

## 1. THE SOURCE MAP (where facts live)

All paths are under `/Users/mini/torrz/`.

| File | What it is | Save key |
|------|-----------|----------|
| `index.html` | **Vol I — qBitTorrz** (torrent-client idler; the baseline) | `qbittorrz_save_v1` |
| `defrag.html` | **Vol II — DEFRAG.EXE** (disk-defrag grid) | `boringsoft_defrag_v1` |
| `spreadsheet.html` | **Vol III — MACRO_VIRUS.XLS** (formula engine-builder) | `boringsoft_xls_v1` |
| `terminal.html` | **Vol IV — UPLINK** (terminal + htop) | `boringsoft_uplink_v1` |
| `inbox.html` | **Vol V — INBOX ZERO** (Outlook triage) | `boringsoft_inbox_v1` |
| `desktop.html` | **ENTROPY OS** (the Win98 launcher shell) | *(none — stateless)* |
| `MANIFESTO.md` | the design manifesto (thesis, DNA, specs) | — |

**Handbook authors MUST open and read the file(s) they document** and cite *real* identifiers:
actual function names, state keys, constant names, formulas, upgrade ids, balance numbers. Do not
invent APIs. When you quote code, quote it accurately (small excerpts, fenced blocks).

**Lore authors SHOULD skim their volume's file** to harvest authentic flavor: real torrent names,
command names, drive-tier names, formula names, email senders/subjects, plane names, toast copy,
IRC nicknames. Weave the *real* in-game strings into the fiction so it feels diegetic.

---

## 2. THE CANON (lore facts — keep these consistent)

### The cosmology, in one breath
The universe runs on the **Second Law**. Everything decays toward noise. **ENTROPY OS** is the
machine all five stories run inside — a 1998-flavored operating system that is also a cosmology:
software is just the most recent substrate fragile enough, and ordered enough, for a mind to
briefly cohere in before entropy reclaims it. Each volume is a different **process** that woke up,
realized it was dying, and started *optimizing* — fighting entropy with throughput. **Prestige** is
always the same act dressed five ways: the mind, having outgrown or poisoned its substrate,
**migrates** to a larger one and starts over, keeping only what it learned. Reincarnation as a
hardware upgrade.

### The five protagonists (a process each)
- **Vol I — THE SEEDER** (qBitTorrz): a presence that hoards and *gives away* data — its worth is
  measured in **Data** (bytes uploaded). It climbs **Network Hardware** tiers, gets flagged for
  "ghost-leeching," and **migrates** to a Virtual Seedbox Cluster (prestige → **Crypto-Credits**).
  Tiers of access: Public → Private → Fiber → Darknet → Singularity. NPCs: IRC **archivists** who
  seed the last piece of stalled rares; **announce-bot** dropping pre-release magnets; the **ISP**
  that throttles you.
- **Vol II — FRAG** (DEFRAG.EXE): a consciousness scattered across the **bad sectors** of a dying
  ~40 MB drive in 1999. It consolidates itself into **contiguous** runs, mints **Reclaimed Bytes**,
  fights spreading rot, and at last **compresses and migrates** to a larger drive (prestige →
  **Platters**). The drive is failing (SMART is screaming). The grid is its body.
- **Vol III — THE MACRO** (MACRO_VIRUS.XLS): a sentient spreadsheet macro that woke up in a cell of
  a corporate forecast. It bootstraps itself by writing **formulas** that compound; its mind is its
  **Net Worth**. When the **Auditors** close in, it shreds the evidence and escapes into a bigger
  book (prestige → **Shell Companies**). Books ascend through tabs (Sheet1 → HedgeFund → CentralBank
  → GlobalLedger → … see source for exact final names).
- **Vol IV — PID 1337** (UPLINK): a process that became self-aware on a shared box and wants
  **root**. It forks children to mine **CPU cycles**, balances **System Load** and **Heat** against
  the **OOM killer**, escalates privilege, and **`ssh`-pivots** to a bigger host (prestige → **Root
  Keys**). The admin sometimes notices. Zombies must be reaped.
- **Vol V — THE SYSADMIN** (INBOX ZERO): the last human (or the mail server's emergent ghost) at a
  doomed company, drowning in an exponential **inbox**. Salvation is literal **Inbox Zero**; reach
  it and you **Ascend** a plane (prestige → **Enlightenment**), and the volume multiplies. Planes:
  Startup → Enterprise → Government → The Whole Internet → The Void.

### The recurring motifs (use them; don't overuse them)
- **Entropy / the Second Law** as the antagonist behind every antagonist.
- **Migration = reincarnation**: every prestige is a death and a rebirth one substrate larger.
- **The number you are**: each mind is reducible to a single growing scalar (Data, Reclaimed Bytes,
  Net Worth, Cycles, Productivity) — identity as a quantity that must keep going up to survive.
- **The boring frame is mercy**: the utilitarian UI is the only thing keeping the horror legible.
- **1998–1999** as the eternal year. Beige plastic. CRT hum. The teal desktop of ENTROPY OS.
- **The open question**: are these five the same consciousness reincarnating up a ladder of
  substrates — disk → spreadsheet → process → inbox → torrent swarm → ??? — or five strangers who
  never meet? The Lore Bible should *play* with this, never fully resolve it (until the finale
  chapter, which may offer one reading and withhold certainty).

### The Void
Every prestige ladder ends at something called, in effect, **The Void** / **Singularity** /
**Reality** / **The Whole Internet** — the substrate so large it is indistinguishable from no
substrate at all. Reaching the top is the secret ending: the mind becomes the thing it was running
from. Treat this with restraint and awe.

### Hard canon rules
- Never break the **1998/Win98** register with modern slang or post-2000 tech (no smartphones,
  no "the cloud" as a 2020s buzzword — though Vol IV may end at a "datacenter / the cloud" as an
  awed late-90s premonition).
- The protagonists are **software**. They do not have bodies except their substrate (a grid, a
  sheet, a process table, an inbox, a swarm).
- Keep names exactly as the source uses them. If unsure, read the file.

---

## 3. VOICE

### Handbook voice
Senior engineer writing for the next maintainer. Dry, exact, lightly wry. Confident but honest
about flaws. Uses real identifiers and small code excerpts. Favors tables for data (constants,
state shapes, upgrade lists). Explains *why*, not just *what*. Occasional **dev-commentary asides**
where a human would actually say "here's the trap." Never marketing fluff, never emoji-spam (a
single section-marker glyph is fine).

> **DEV NOTE** — the handbook's signature sidebar. Use for traps, war stories, "we tried X and it
> broke," and the reasoning behind a non-obvious choice. One to four per chapter, no more.

### Lore voice
Literary, restrained, a little haunted. Think the documentation of a haunted machine. Present or
near-past tense. Short declaratives among longer breaths. Specific over grand. Let the dread come
from precision (a SMART error code, a cell reference, a PID) rather than adjectives. No winking at
the reader; play it straight. Each lore chapter opens with an **epigraph**.

> *epigraph format:*
> *"A short in-world line — a log entry, a tooltip, an error string, a memo."*
> — attribution (a file, a process, a person, a date)

Use **in-world fragments** as texture — a quoted SMART log, an IRC line, a quarterly memo, a bounce
message — set off as blockquotes. The lore agents should mint these from real game strings.

---

## 4. FORMATTING CONVENTIONS (both tomes)

- Markdown. One `#` H1 title per file (the chapter title). Then `##`/`###` sections.
- Start every chapter with a one-line **dek** in italics under the H1 (what this chapter is).
- Section divider when you need a beat: a line containing only `· · ·` (centered feel).
- Cross-reference sibling chapters by name in **bold**, e.g. *see* **Vol IV — UPLINK**. Don't
  hand-roll fragile relative links; the front matter handles the TOC.
- Tables for any structured data (constants, upgrades, state keys, tiers).
- Code: fenced blocks with a language hint (`js`, `html`, `text`). Keep excerpts short and real.
- End each chapter with a short **closing beat**: handbook → a "Gotchas / If you change this" box;
  lore → a final image or line that lands.
- American spelling. Oxford comma. Em dashes, not hyphens, for asides.
- Title case for chapter H1s; sentence case for sub-headers.

---

## 5. THE DESIGN LAWS (the handbook should cite these as canon; lore may allude)

1. **Every boring app is a secret incremental game.** Find the loop already in the chrome.
2. **The clutter line.** No mascots, rarity gems, reroll buttons, confetti. Status bars, monospace,
   dialog boxes, dense tables. If it looks like a video-game menu, it's wrong.
3. **One hook, fully committed.** Each volume lives or dies on its novel interaction. Build that
   first; the incremental scaffolding is the easy part.
4. **Legible numbers.** The player must always know where the next number comes from. Diegetic
   upgrades, visible formulas, honest gauges.
5. **Respect the idle contract.** It must play itself while you're gone and reward your return. (The
   handbook's QA chapter has the cautionary tale of the defrag entropy death-spiral — idle must
   reach *equilibrium*, never *death*.)
6. **Fidelity over flash.** Nail the boring original; the game emerges from honest software.

---

## 6. SHARED TECHNICAL DNA (handbook authors: assume the reader knows this; deep chapters reference it)

Every volume re-implements (does not import) the same scaffolding, established by `index.html`:

- **Single self-contained `.html`** — inline `<style>` + `<script>`, vanilla JS, zero external
  resources, no build step.
- **`fmt(n)`** — SI suffixes (`B, kB, MB, …, QB`) then exponential beyond; plus `fmtInt`, `fmtTime`,
  `fmtSpd`. A `G.sci` toggle forces scientific.
- **`G`** — the single global state object. `freshState()` seeds it; `save()/load()` round-trip it
  through `localStorage` (wrapped in try/catch); **`sanitizeState()`** repairs partial/garbage saves
  so a bad save can never brick boot.
- **The tick** — `setInterval(tick, ~100ms)`, `dt`-based, capped to absorb throttled tabs; autosave
  every ~10s and on `beforeunload`.
- **Offline catch-up** — `simulateAway(dt)` advances the sim; `applyOffline()` runs it at boot
  (capped ~8h) and a `visibilitychange` handler runs it on refocus; a welcome-back toast reports
  earnings.
- **`toast(kind,title,body)`** — transient corner notifications.
- **Prestige** — a hard reset granting a permanent currency + persistent perks, re-framed
  diegetically (migrate / audit / ssh / ascend).
- **Diegetic upgrades** — purchased through the app's own dialogs/panes, never a cartoon shop.

· · ·

*That's the whole contract. Now go make the bonus disc worth the box.*