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.