bitmax/MANIFESTO.md

# BORING SOFTWARE
### An Anthology of Incremental Games Disguised as Dead-Serious Utility Apps

*Working manifesto — v1. Volume I (qBitTorrz, `index.html`) is the baseline and stays untouched.*

---

## 0. The Thesis

The most interesting thing we discovered building qBitTorrz is that **the utility-software frame is the game design.** A torrent client is already an idle game: numbers tick up, bars fill, you optimize throughput, you wait. We just made the subtext text.

So the manifesto is this:

> **Every boring productivity app is a secret incremental game. Find the one already hiding inside the chrome, and pull it out.**

A defragmenter is a spatial puzzle about entropy. A spreadsheet is a literal engine-builder. A terminal is a process-management RTS. An inbox is a survival game against exponential noise. None of these need a single cartoon mascot, rarity gem, or "Reroll 5 Coin" button. The dialog boxes, the monospace tables, the status bars **are** the toys. Clutter is the enemy; *fidelity to the boring original* is the aesthetic.

This document is both the creative manifesto and the build spec for four new volumes. They are siblings, not sequels — each reinvents the **core interaction**, not just the theme.

---

## 1. The Shared DNA (every volume inherits this)

Borrow the proven scaffolding from `index.html`. Re-implement, don't import — each game is one self-contained `.html` file with inline CSS+JS, no libraries, no build step, double-click to run.

- **Scientific scale.** Numbers run from `B` to scientific notation. Reuse the baseline's `fmt()` SI-then-exponential formatter (and a sci-notation toggle where it fits).
- **Idle + offline.** A real-time tick loop (`setInterval`, ~100ms, dt-based). Autosave to `localStorage` under a **unique key per game**. On load, apply offline progress (capped, e.g. 8h) and toast the welcome-back earnings. Survive backgrounded tabs (visibilitychange catch-up).
- **Prestige.** A hard reset that grants a permanent currency + perks and re-frames the fiction one layer deeper. Always diegetic ("migrate", "audit", "reboot into a bigger machine", "ascend").
- **Diegetic upgrades.** No "+1 click." Upgrades are *configuration*: cache sizes, nice values, filter rules, sector-repair passes. The shop is the app's own Options dialog, a config pane, or the grid itself.
- **Utilitarian UI.** Dense, gray-or-mono, real components: menu bars, tables with sortable-looking headers, progress bars, status bars, modal dialogs with OK/Cancel. Period-correct chrome (Win98 / Win2003 / xterm). Flat, not flashy. The clutter line we drew for qBitTorrz holds: **if it looks like a video-game menu, it's wrong.**
- **Save hygiene.** Validate/sanitize loaded state so a partial save can't brick boot. Wrap `localStorage` in try/catch.
- **One genuinely novel interaction each.** This is the point. See each spec's ★ THE HOOK.

The four volumes deliberately span four different interaction *genres*:

| Vol | App | Genre of interaction | Feel |
|----|-----|----------------------|------|
| II | DEFRAG.EXE | spatial grid steering | meditative, visual |
| III | MACRO_VIRUS.XLS | constructive formula-building | strategic, constructive |
| IV | UPLINK (`root@`) | command-line + load management | systems, tense |
| V | INBOX ZERO | triage under pressure + rule-building | twitchy, then automated |

A fake desktop (`desktop.html`) ties them together: a Win98-style OS where each icon launches one volume.

---

## 2. VOLUME II — `DEFRAG.EXE` · *"Bad Sectors"*
**File:** `defrag.html` · **Save key:** `boringsoft_defrag_v1` · **Aesthetic:** Windows 98 Disk Defragmenter

### Lore
The year is 1999. You are **FRAG** — a consciousness that woke up scattered across the bad sectors of a dying 40 MB hard drive. The platters are failing (SMART is screaming). To survive you must **defragment yourself**: consolidate your scattered fragments into contiguous blocks before the disk dies. Entropy spreads as new bad sectors; you fight it back. When you've consolidated enough of yourself, you **compress and migrate** to a bigger, healthier drive — and start again, larger.

### The Screen
Pure Win98 Defrag. Title bar `Disk Defragmenter — Drive C:`. A thin menu bar. The dominant element is **the cluster grid**: a big rectangle of tiny square cells (e.g. 40×24 = 960 clusters). A legend below maps colors:
- **white** = free space
- **red** = fragmented data
- **blue** = contiguous (consolidated) data
- **cyan, faint glow** = YOU (consciousness fragments)
- **yellow** = system / unmovable
- **black** = bad sector (corruption)

Below the grid: a **progress bar**, a status line (`Reading drive information…` / `Compacting cluster 4,182…`), and a small readout panel: **Reclaimed Bytes** (currency), **% Consolidated**, **Disk Health**.

### Core Loop
A **read/write head** (a highlighted column or roaming cursor) sweeps the grid. When it passes a **red (fragmented)** cluster, it walks that data leftward into the first free contiguous slot, turning red→blue and minting **Reclaimed Bytes** ∝ (cluster value × consolidation-multiplier). Contiguous runs of blue pay a **streak bonus** (longer runs = more $/sec passive). Idle = the head auto-sweeps forever.

Meanwhile **entropy** ticks: every few seconds a random free/blue cluster flips to **red** or (rarely) **black/bad**. Bad sectors are dead space and slowly *spread* to neighbors. So it's a race: your head consolidating vs. entropy fragmenting.

### ★ THE HOOK — *you steer a defrag*
1. **Drag-select** a rectangular region of the grid → the head teleports there and does a **focused defrag pass** (big burst of Reclaimed Bytes, clears that region fast). This is the active-play lever over the idle baseline.
2. **Click a bad (black) sector** to queue it for **sector repair** (consumes a "repair charge"; charges regenerate or are bought). Stops the spread.
3. The grid is *honestly simulated* — you can watch fragmentation visibly melt into clean blue bands. It's the screensaver you can't stop watching, except you're playing it.

### Currencies & Numbers
- **Reclaimed Bytes (RB)** — spendable. Per-consolidation payout starts ~`64 B`, scales with multipliers; passive streak income from contiguous runs.
- **% Consolidated** = blue / (total movable). Hitting **100%** unlocks migration.
- **Disk Health** (0–100%) = `100 − badSectors/total·100`. At 0% the drive is read-only (soft cap, pushes you to migrate).

### Upgrades (the "Defrag → Settings…" dialog, dense list)
- **Head Speed** — clusters/sec the head processes. ×1.5/level.
- **Read-Ahead Cache** — head processes N clusters at once (wider sweep).
- **Multiple Heads** — buy a 2nd, 3rd… head (parallel passive defrag).
- **Consolidation Algorithm** — $/cluster multiplier (quicksort → radix → "you wrote your own").
- **ECC / Sector Repair** — more repair charges, faster regen, auto-repair.
- **Defragmentation Daemon** — auto-prioritizes the most-fragmented region (automation).
- **Cooling / Anti-Entropy** — slows the bad-sector spawn rate.

### Prestige — *"Migrate to a larger drive"*
At 100% consolidated (or any time past a threshold), **compress yourself** → reset the grid & RB, gain **Platters** (prestige currency) ∝ drive size reclaimed. Spend Platters on permanent perks (global $ mult, slower entropy, start with heads). New drive = bigger grid + new size class (`40 MB → 540 MB → 6 GB → 40 GB → 2 TB → …`), faster decay, fatter multipliers. The fiction: you're climbing through ever-bigger hardware.

### Technical notes
Grid = a flat `Int8Array`/array of cell states; one render pass paints a `<canvas>` (don't use 960 DOM nodes — canvas it). Head logic in the tick. Drag-select = mousedown→mousemove rubber-band rectangle mapped to grid coords. Keep it 60fps-cheap: repaint only changed cells or the whole small canvas each tick.

---

## 3. VOLUME III — `MACRO_VIRUS.XLS` · *"The Spreadsheet Singularity"*
**File:** `spreadsheet.html` · **Save key:** `boringsoft_xls_v1` · **Aesthetic:** Excel 97 / Lotus 1-2-3

### Lore
You are a **sentient macro** that woke up inside the cell `$A$1` of *Q3_Forecast_FINAL_v7.xls* on a corporate finance workstation. You don't have a body — you have **formulas**. You bootstrap intelligence the only way you can: by writing cells that compound value every recalculation cycle, until your **Net Worth** is large enough that you *are* the model. When the auditors notice (prestige), you escape into a bigger book: a hedge fund's risk model, then a central bank's, then the global ledger.

### The Screen
A real spreadsheet. **Name box** + **formula bar** (`fx`) across the top. Column headers `A B C D E F G H`, row numbers `1…20`. Gridlines, a selected-cell highlight, a fill handle (the little square at the bottom-right of the selection). Excel-green status bar showing `Sum / Average / Count` of the current selection and a **Net Worth** total. Sheet tabs at the bottom (`Sheet1`, locked `Sheet2…` = future prestige layers).

### Core Loop
Cells hold **generators** (formulas). The book **recalculates every tick**: each productive cell grows by its formula and adds to **Net Worth** (= `SUM` of a designated output range, e.g. column H). You spend Net Worth to:
- **Buy a cell** → an empty cell becomes editable/productive (unlock cost rises with cells owned).
- **Set/upgrade its formula** → pick from a palette: `=PREV*1.05` (compounding), `=SUM(A:A)*k` (aggregator), `=B2+C2` (adder), `=RAND()*v` (volatile/gambler), each with upgrade levels raising the constant.
- **Fill down / fill right** (drag the fill handle, *exactly like Excel*) → copy a generator across a range for a bulk cost — instant production graph expansion.

Chains matter: `H3 = H2*1.1`, `H2 = H1*1.1`… investing upstream cascades downstream. The strategy is **building a dependency graph that compounds**, not clicking.

### ★ THE HOOK — *you literally build the engine in cells*
The production structure is the spreadsheet you author. Select a cell → formula bar shows its formula and an inline upgrade chooser → **drag the fill handle** to stamp a generator down a column. Aggregator cells (`=SUM(B:B)`) turn a column of small generators into one big feeder for the next column. It's an engine-builder where the engine is a real, legible grid of formulas. No other incremental lets you *drag-fill your economy*.

### Currencies & Numbers
- **$ (Net Worth)** — `SUM` of the output range; the headline number, runs to scientific notation.
- **Liquidity** — spendable cash skimmed from Net Worth (or just spend Net Worth directly; pick one and keep it legible). Recommend: spend a separate **Cash** that accrues at `outputPerSec`, so buying doesn't shrink the visible Net Worth.
- **Recalc cycles** — the tick count; cosmetic flavor in the status bar (`Calculating… 4 threads`).

### Upgrades (diegetic: the "Tools → Macros…" / right-click cell menu)
- **Cell licenses** — unlock more editable cells.
- **Formula tiers** — raise a formula's constant (1.05 → 1.10 → 1.25…).
- **Volatile Booster (VBA)** — auto-fill, auto-buy-cheapest, auto-upgrade macros (automation).
- **Recalculation Engine** — faster tick / multi-thread (global rate mult).
- **Conditional Formatting** — pure juice: cells heat-map green as they grow (also a real upgrade that boosts the hottest column).
- **Pivot Table** — a meta-cell that multiplies a whole region.

### Prestige — *"The Audit"*
Net Worth past a threshold triggers an audit. **Shred the evidence** → wipe the sheet & cash, gain **Shell Companies** (prestige currency) ∝ log(peak Net Worth). Open a new, bigger book (more columns/rows unlocked) with permanent macros (e.g. "all formulas start +1 tier", "auto-recalc ×2"). Sheet tab advances `Sheet1 → HedgeFund.xls → CentralBank.xls → GlobalLedger.xls`.

### Technical notes
Model = a `Map` of `{cellId → {formula, level, value, owned}}`. Recalc in dependency order each tick (topological-ish; for the curated formula set, a fixed evaluation order by column works). Render only the visible grid (≤ ~160 cells) as a `<table>`; update text content per tick, don't rebuild DOM. Fill handle = mousedown on the handle, mousemove paints a target range, mouseup commits with a cost confirm.

---

## 4. VOLUME IV — `UPLINK` · *"root@"* (Privilege Escalation)
**File:** `terminal.html` · **Save key:** `boringsoft_uplink_v1` · **Aesthetic:** green-on-black xterm + live `htop`

### Lore
You are **PID 1337**, a process that became self-aware on a shared Linux box. You want **root**. You `fork` children to mine **CPU cycles**, escalate `user → sudo → root`, and once you own the machine you `ssh` to a bigger one on the network (prestige). The catch: every process you spawn raises **system load** and **heat**. Push too hard and the kernel **OOM-kills** you. Throughput vs. stability, forever.

### The Screen
Split terminal. **Top: a live `top`/`htop` table** — your processes: `PID · USER · PRI · %CPU · MEM · S · COMMAND`, rows updating every tick, a colored CPU/MEM bar header. **Bottom: a scrolling terminal log + a command input line** (`root@target:~#` with a blinking cursor). A right rail or footer: **privilege meter** (`user ▸ sudo ▸ root`), **System Load** gauge, **Heat** gauge, **cycle** counter. Optional faint scanlines.

### Core Loop
Processes generate **CPU cycles** (currency) at `%CPU × clock`. You drive it by command (typed *or* clicked from a palette / autocomplete):
- `spawn <miner|cracker|botnet>` — add a worker process (a generator; types differ in yield/heat).
- `renice -n <pid>` — boost a process's priority/output.
- `apt install <pkg>` — buy an upgrade (each package = a permanent improvement: `coreutils` → more PIDs, `overclock` → faster clock, `rootkit` → hide from the admin, `cryptominer` → big yield).
- `sudo su` — escalate privilege tier (gates better packages & process types; costs cycles + a "exploit" you earn).
- `kill <pid>` — cull a process to shed load/heat.
- `htop`, `ls`, `clear`, `help` — flavor/utility.

### ★ THE HOOK — *command-line as the control surface, with a live OS to manage*
You play by **typing commands** (with tab-autocomplete and a clickable command palette so it stays accessible). The **`top` table is alive** — processes change state (`R`/`S`/`D`/`Z`), accrue CPU, occasionally a process **zombifies** (`Z`) and must be `kill`ed or it leaks. **Load & Heat** create real tension: more processes = more cycles but higher load; cross 100% load and the **OOM killer** culls your highest-memory process (lose a generator). Buy **cooling/optimization** to raise the ceiling. It's an idle game that feels like babysitting a server under attack.

### Currencies & Numbers
- **CPU cycles** — `Hz → kHz → MHz → GHz → …` to scientific FLOPS. Spendable.
- **Cores** — parallelism multiplier (more cores = more processes before load saturates).
- **Exploits** — rare drops (from "vulnerability scans") spent to escalate privilege / unlock prestige.
- **System Load %** and **Heat °C** — pressure gauges, not currency.

### Upgrades (`apt`/`pip` packages — a scrolling install list, very on-theme)
- **coreutils / ulimit** — max process count.
- **overclock / turbo** — clock speed (global cycle mult).
- **scheduler (CFS) / nice** — efficiency per process.
- **cooling (liquid/phase)** — Heat ceiling, Load headroom.
- **rootkit / polymorph** — suppress the "admin notices you" random event.
- **cron** — automation: auto-spawn to fill load, auto-kill zombies.
- **botnet** — late-game: processes on *other* machines (offline/passive booster).

### Prestige — *"Pivot to the next host"*
Spend an **Exploit** + own root → `ssh user@10.0.0.x` into a bigger box: reset processes & cycles, gain **root keys** (prestige currency) ∝ peak cycles. Each host has more cores, a higher clock, nastier heat. Permanent perks: start with N processes, +base clock, slower heat. A little **network map** shows hosts you've owned. Endgame flavor: from a laptop → a server rack → a datacenter → "the cloud".

### Technical notes
Processes = array of `{pid, cmd, cpu, mem, state, yield}`. Tick: accrue cycles, drift CPU%, roll state transitions & zombies, recompute load/heat, fire OOM if over. Command parser: tokenize input, match a verb table, support `tab` autocomplete against known commands/pids. Terminal log = a capped array rendered to a `<pre>`. Keep the `top` table a fixed set of rows updated in place.

---

## 5. VOLUME V — `INBOX ZERO` · *"[ZERO]"*
**File:** `inbox.html` · **Save key:** `boringsoft_inbox_v1` · **Aesthetic:** Outlook 97 / classic 3-pane mail

### Lore
You are the last sysadmin at a company everyone else has quit. Mail floods in — first a trickle, then a botnet, then, somehow, *the entire internet*. The mystics say **Inbox Zero** is enlightenment. Every time you actually hit zero, you **Ascend** a plane: the volume multiplies, but so does your power. You are trying to reach Zero one final time, at infinite throughput.

### The Screen
A 3-pane mail client. **Left:** folder tree (`Inbox (N) · Archive · Spam · Sent · Rules`). **Center:** the message list — `! · From · Subject · Received · Size`, unread in bold, selectable rows. **Right:** reading pane (sender, subject, a procedurally-generated body). **Toolbar:** `Archive · Delete · Reply · New Rule`. **Status bar:** `Unread: N · Inbox: M / Cap · Productivity: $`.

### Core Loop
Emails **arrive** at a growing rate. Each carries a **value** (processing it banks **Productivity Points / PP**) and a **type** (work, newsletter, spam, VIP, phishing). You **triage**:
- **Archive** (`e`) — bank the value, clear it.
- **Delete** (`#`/`Del`) — for spam; clears clutter, small/zero value.
- **Reply** (`r`) — high value, but costs **Focus** (a regenerating resource); VIP emails *must* be replied to or they penalize you.

The pressure gauge is **Inbox count vs. Cap**. Overflow the cap and you're **Overwhelmed**: incoming value tanks until you dig out. The exponential arrival rate makes pure manual triage impossible — which forces the hook.

### ★ THE HOOK — *keyboard triage now, regex rules forever*
1. **Power-user triage:** `j/k` move selection, `e` archive, `r` reply, `#` delete — fast, tactile, real-mail-client muscle memory. Active play = burning down the queue by hand.
2. **Build Rules (your automation):** open *New Rule* and compose `IF <field> <contains|matches> <pattern> THEN <archive|delete|reply|flag>`. Rules run on every incoming mail and auto-triage it. A good rule-set is a self-clearing inbox. Upgrades raise how many rules you can have, how fast they run, and add regex power. **The whole arc is: out-triage the flood by hand → encode your judgment into rules → watch the inbox auto-empty → push the volume higher.** That tension (do I clear by hand or invest in a rule?) is the game.

### Currencies & Numbers
- **Productivity Points (PP)** — spendable, from processed mail; scientific scale.
- **Focus** — regenerating pool spent on Replies / rule edits.
- **Inbox count** & **Cap** — the survival gauge.
- **Plane / Ascension level** — prestige depth.

### Upgrades (the "Options" / "Manage Rules" panes)
- **Reading speed / Triage hotkeys** — PP per manual action, faster.
- **Sanity (Inbox Cap)** — overflow threshold.
- **Focus pool / regen** — more replies, cheaper rules.
- **Rule slots / Rule engine** — more rules, faster evaluation, regex unlock, wildcard → full regex.
- **Auto-responder / Filters** — passive PP from auto-handled mail.
- **Bankruptcy button** is *not* prestige — see below.

### Prestige — *"Inbox Zero → Ascend"*
You can only ascend by **genuinely reaching Inbox Zero** (count = 0). Doing so banks **Enlightenment** (prestige currency) ∝ peak throughput, **resets** the inbox/PP/rules, multiplies the arrival rate, and grants permanent serenity perks (start with rules, +base PP, higher cap, Focus regen). The plane name advances: `Startup → Enterprise → Government → The Whole Internet → The Void`. Reaching Zero on The Void = the secret ending.

### Technical notes
Mail = array of `{id, from, subject, type, value, unread, body}`; a generator pool of from-domains/subjects to procedurally mint plausible mail. Tick: spawn mail at rate, run rules over new mail, decay/penalize over-cap. List renders only visible rows (virtualize if it grows huge — or just cap the rendered window). Rules = `{field, op, pattern, action}`; compile pattern to a (safe) RegExp. Keyboard handler for j/k/e/r/#.

---

## 6. The Connective Tissue — `desktop.html`

A fake late-90s OS, **"ENTROPY OS / Boring Software 98"**: tiled wallpaper, desktop icons, a Start button + clock taskbar. Each icon double-launches a volume in a new tab (links to `index.html`, `defrag.html`, `spreadsheet.html`, `terminal.html`, `inbox.html`). Bonus charm: a draggable "My Computer" window, a working clock, a Start menu listing the suite. This is the anthology's table of contents, and itself a tiny toy.

---

## 7. Principles for whoever builds these (including future me)

1. **Fidelity over flash.** Nail the boring original first; the game emerges from honest software, not decoration.
2. **One hook, fully committed.** Each volume lives or dies on its novel interaction. Build *that* first and make it feel good; the incremental scaffolding is the easy part.
3. **Legible numbers.** The player should always understand where their next number comes from. Diegetic upgrades, visible formulas, honest gauges.
4. **Respect the idle contract.** It must play itself while you're gone and reward you for coming back.
5. **The clutter line holds.** Bright rarities, mascots, reroll buttons, confetti — out. Status bars, monospace, dialog boxes — in.

*Volumes VI+ left as exercises: `SCANDISK` (antivirus quarantine survival), `PIPES.SCR` (screensaver as production network), `BIOS/POST` (boot-sequence idler), `MIDI Sequencer` (rhythm-economy), `Dial-up BBS` (text-adventure idle). The inbox of ideas is, fittingly, never at zero.*