Rewrite docs, docstrings, and comments in a plain teaching voice

DESIGN.md

@@ -69,9 +69,9 @@ components:
 
 **Creative North Star: "A project window inside CuperOS"**
 
-The GitHub Pages site must feel like it belongs to Cuper's live portfolio, not like a separate AI-generated landing page. The surface is a retro desktop app: teal dotted desktop, zero-radius window chrome, indigo title bars, pixel icons, inset content panes, taskbar, and project-copy voice that sounds human, technical, and slightly amused.
+The idea is simple. Cuper's portfolio site is styled as a retro operating system called CuperOS. The GitHub Pages site for this project must look like one window inside that OS, not like a separate AI-generated landing page. That means a teal dotted desktop, zero-radius window chrome, indigo title bars, pixel icons, inset content panes, a taskbar, and project copy that sounds human, technical, and slightly amused.
 
-The README remains a GitHub-rendered article, but any browser page for the project should inherit the CuperOS design language. The page can be visual and interactive, but it should do that as an OS control surface, not as a full-bleed marketing hero.
+The README stays a GitHub-rendered article. But any browser page for the project inherits the CuperOS design language. The page can be visual and interactive, as long as it behaves like an OS control surface and never like a full-bleed marketing hero.
 
 **Key Characteristics:**
 - Pixel OS chrome first, modern landing-page composition never.
@@ -81,7 +81,7 @@ The README remains a GitHub-rendered article, but any browser page for the proje
 
 ## 2. Colors
 
-The palette is inherited from the portfolio OS: teal desktop, gray chrome, indigo title bars, off-white document panes, and small utility accents.
+The palette comes straight from the portfolio OS: teal desktop, gray chrome, indigo title bars, off-white document panes, and small utility accents. Nothing here is new.
 
 ### Primary
 - **CuperOS Indigo** (`title-bar`, `title-bar-end`): title bars, selected controls, primary project identity.
@@ -97,17 +97,17 @@ The palette is inherited from the portfolio OS: teal desktop, gray chrome, indig
 
 ### Named Rules
 
-**The No New Brand Rule.** Do not invent a separate gpu_stack palette. The project page is a child window inside CuperOS.
+**The No New Brand Rule.** Do not invent a separate gpu_stack palette. The project page is a child window inside CuperOS, so it uses the parent's colors.
 
-**The Small Accent Rule.** Gold, green, and red are status lights, not brand washes. Use them as signals, not backgrounds.
+**The Small Accent Rule.** Gold, green, and red are status lights, not brand washes. Use them as signals, never as backgrounds.
 
 ## 3. Typography
 
-**The Font Law (portfolio-wide, per Cuper):** every rendered glyph, regardless of size or role, comes from the approved pixel set: DotGothic16, Pixelify Sans, VT323, Handjet, or Silkscreen. No other typeface ever renders. No exceptions for paragraphs, tables, code, or fine print.
+**The Font Law (portfolio-wide, per Cuper):** every rendered glyph, at every size and in every role, comes from the approved pixel set: DotGothic16, Pixelify Sans, VT323, Handjet, or Silkscreen. No other typeface ever renders. No exceptions for paragraphs, tables, code, or fine print.
 
 **Current mapping:** Pixelify Sans carries the interface and all prose (headings, buttons, labels, status lines, paragraphs). VT323, the terminal face, carries commands, identifiers, numeric values, intervals, tables, and console output. The other three approved faces are available but unused here.
 
-**Legibility floor:** pixel faces break down under ~11px, so nothing renders smaller. Dense instrument fine print sits at 0.7rem minimum, chart ticks at 11px.
+**Legibility floor:** pixel faces break down under about 11px, so nothing renders smaller. Dense instrument fine print sits at 0.7rem minimum, chart ticks at 11px.
 
 **Character:** The pixel face IS the voice of the OS, everywhere, at every size.
 
@@ -126,7 +126,7 @@ The palette is inherited from the portfolio OS: teal desktop, gray chrome, indig
 
 ## 4. Elevation
 
-Depth is not blur, glass, or soft shadow. It is the retro OS physical model: `2px outset` for buttons and frames, `2px inset` for content wells, and a crisp `2px 2px 0` shadow behind windows.
+Depth here is not blur, glass, or soft shadow. It is the physical model of a retro OS: `2px outset` for buttons and frames, `2px inset` for content wells, and a crisp `2px 2px 0` shadow behind windows. A surface looks raised or sunken because its border says so.
 
 ### Shadow Vocabulary
 - **Pixel Window Shadow** (`2px 2px 0 oklch(0.08 0.004 250)`): top-level windows only.
@@ -135,7 +135,7 @@ Depth is not blur, glass, or soft shadow. It is the retro OS physical model: `2p
 
 ### Named Rules
 
-**The Chrome Is Structure Rule.** If an element needs hierarchy, give it a real OS affordance: title bar, inset pane, status light, or taskbar. Do not fake hierarchy with decorative cards.
+**The Chrome Is Structure Rule.** If an element needs hierarchy, give it a real OS affordance: a title bar, an inset pane, a status light, or a taskbar entry. Do not fake hierarchy with decorative cards.
 
 ## 5. Components
 

PRODUCT.md

@@ -10,10 +10,11 @@ brand
 
 ## Product Purpose
 
-`gpu_stack` is a causal, uncertainty-aware virtual AI datacenter. It joins
-learning progress, training and inference execution, communication, memory,
-failures, power, cooling, grid behavior, and economics in one inspectable world
-model.
+`gpu_stack` is a causal, uncertainty-aware virtual AI datacenter. Causal means it
+models what drives what, not just what correlates. Uncertainty-aware means it
+says how sure it is. It joins learning progress, training and inference
+execution, communication, memory, failures, power, cooling, grid behavior, and
+economics in one inspectable world model.
 
 The same engine has three inseparable jobs:
 
@@ -24,14 +25,15 @@ The same engine has three inseparable jobs:
    a large AI datacenter to screen.
 
 The recursive physical graph remains valuable, but graph depth is not the
-objective. A deeper lithography or particle relation is research progress only
-when it improves an externally evaluated prediction, reduces decision-relevant
-uncertainty, explains a residual, or enables a falsifiable experiment.
+objective. A deeper lithography or particle relation counts as research
+progress only when it improves an externally evaluated prediction, reduces
+decision-relevant uncertainty, explains a residual, or enables a falsifiable
+experiment.
 
 Success means the engine transfers to held-out hardware and workloads, carries
 calibrated uncertainty, recommends interventions with low decision regret, and
-makes the causal reason visible. A simulation result is a hypothesis, not
-evidence about the real datacenter until measurements validate it.
+makes the causal reason visible. A simulation result is a hypothesis. It
+becomes evidence about the real datacenter only after measurements validate it.
 
 ## Brand Personality
 

README.md

@@ -13,27 +13,27 @@ The question was simple enough to be annoying: if frontier training is supposedl
 
 Not rhetorically. Physically.
 
-A token passes through model architecture, kernels, collectives, memory bandwidth, transistor switching, lithography, materials, thermals, power delivery, and eventually a cost line item that someone has to pay. The stack is usually explained in slices. I wanted the uncomfortable version where the slices have to talk to each other.
+A token passes through model architecture, kernels, collectives, memory bandwidth, transistor switching, lithography, materials, thermals, power delivery, and eventually a cost line item that someone has to pay. Each of those layers is usually explained on its own, in a slice. I wanted the version where the slices have to talk to each other.
 
 ## What This Is Now, And How It Got Here
 
-The project grew in three stages, and knowing the stages makes everything else legible.
+The project grew in three stages. Once you know the stages, everything else in this README makes sense.
 
-First it was an equation graph: thousands of physics and engineering relations wired together so that a question like "what does one token cost" could be traced all the way down instead of stopping at a vendor slide.
+First it was an equation graph: thousands of physics and engineering relations wired together, so that a question like "what does one token cost" could be traced all the way down instead of stopping at a vendor slide.
 
-Then the graph learned to move. Events, failures, checkpoints, power draw, multi-site traffic. A static graph became a small virtual datacenter that can replay what a training run does over time.
+Then the graph learned to move. Events, failures, checkpoints, power draw, multi-site traffic. The static graph became a small virtual datacenter that can replay what a training run does over time.
 
-Now it is a lab. The virtual datacenter runs preregistered experiments. Preregistered means the pass/fail line is frozen before the run starts, so I cannot move the goalposts after seeing the result. Measurements calibrate the engine, the engine powers the explanation, the explanation exposes its own assumptions, and experiments produce new measurements. That loop is the whole point now.
+Now it is a lab. The virtual datacenter runs preregistered experiments. Preregistered means the pass/fail line is frozen before the run starts, so I cannot move the goalposts after seeing the result. Measurements calibrate the engine. The engine powers the explanation. The explanation exposes its own assumptions. Experiments produce new measurements. That loop is the whole point now.
 
 So in one sentence: GPUSTACK is a virtual AI datacenter you can interrogate. It predicts what a training run does to time, power, and money, says how sure it is, and can show you what every one of its numbers is made of.
 
-If that sounds like a weird amount of effort to understand GPU training, yes. That is more or less how the project happened.
+That is a lot of machinery for one question about GPU training. It grew this way one honest step at a time, which is more or less how the project happened.
 
 ## The Shape Of The Stack
 
 ![Dependency cone from datacenter economics down through GPU systems, transistor physics, lithography, atoms, nucleons, quarks, and equations.](docs/assets/readme-equation-cone.svg)
 
-`gpu_stack` treats the training stack like one inspectable dependency cone. Start from a single number at the top, collect everything it depends on, and the shape that falls out is a cone: one question at the tip, hundreds of assumptions at the base.
+`gpu_stack` treats the training stack as one inspectable dependency cone. Pick a single number at the top, collect everything it depends on, and the shape that falls out is a cone: one question at the tip, hundreds of assumptions at the base.
 
 At the wide end are questions people actually ask:
 
@@ -48,7 +48,7 @@ At the narrow end are the things the model refuses to pretend away: how the chip
 
 Most tooling stops at the first satisfying number. `gpu_stack` keeps asking: what is that number made of?
 
-The answer can be an equation, a sourced scenario value, a universal constant, or a root input. A root input is a value the model needs but cannot yet derive, so it names it instead of hiding it. Root inputs are not a shame pile. They are visible modeling debt, which is much better than hidden modeling debt wearing a lab coat.
+The answer can be an equation, a sourced scenario value, a universal constant, or a root input. A root input is a value the model needs but cannot yet derive, so it names the value instead of hiding it. A root input is not a failure. It is modeling debt made visible, and visible debt is much safer than hidden debt.
 
 ## The Central Idea
 
@@ -103,7 +103,7 @@ The model spans:
 | Cluster and facility | nodes, racks, bisection, storage, reliability, power, cooling, PUE |
 | Economics | capex, opex, amortization, power cost, run cost, cost per token |
 
-MFU means Model FLOPs Utilization. HBM means High Bandwidth Memory. PUE means Power Usage Effectiveness. The README should not assume the reader was born knowing datacenter abbreviations. Sadly, many datacenter docs do. If half the other words in that table are new to you, that is fine. The table is a map of where things live, not a quiz.
+MFU means Model FLOPs Utilization. HBM means High Bandwidth Memory. PUE means Power Usage Effectiveness. You should not need to arrive already knowing datacenter abbreviations, so this README defines them. If half the other words in that table are new to you, that is fine. The table is a map of where things live, not a quiz.
 
 ## Try It Without Believing Me
 
@@ -189,11 +189,11 @@ total_weight  root_count  family                                      boundary_c
 
 Reading the columns: `total_weight` is how many downstream variables depend on the family's roots, `family` is the group of related roots, and `primitive_boundary` marks families sitting at the edge of what the model can currently derive. The live table also appends a `top_roots` column naming the heaviest individual roots per family, truncated here for line width.
 
-This is one of the more useful commands because it prevents the project from drifting into "add equations wherever it feels cool." The graph can tell which unknowns are currently expensive.
+This is one of the more useful commands, because it stops the project from adding equations wherever it feels interesting. The graph itself can tell you which unknowns are currently expensive.
 
 ## Scenario Reports
 
-Presets can evaluate named targets and return structured artifacts. A preset is a saved bundle of scenario assignments, so a run is reproducible instead of vibes.
+Presets can evaluate named targets and return structured artifacts. A preset is a saved bundle of scenario assignments, so a run is reproducible instead of a matter of memory.
 
 ```python
 from gpu_stack.presets import scenarios
@@ -247,7 +247,7 @@ econ.cost.per_token     = 3.000078e-06
 
 That last line reads as three millionths of a dollar per token: for this synthetic scenario, a million tokens costs about three dollars of datacenter.
 
-That fixture is synthetic. A fixture is a fixed test anchor: deterministic on purpose, not vendor truth, historical data, or a price recommendation. The distinction matters. Fake authority is how technical debt gets a haircut and calls itself strategy.
+That fixture is synthetic. A fixture is a fixed test anchor: deterministic on purpose, not vendor truth, historical data, or a price recommendation. The distinction matters. A synthetic number wearing the costume of a measurement is exactly the kind of hidden assumption this project exists to avoid.
 
 ## Resolver Workflows
 
@@ -298,9 +298,9 @@ In plain words, the six questions:
 
 A few experiment codes appear throughout the project: LC stands for learning calibration, PW for power waveform, SC for semantic consistency. E001-LC3 is just "the third learning-calibration run of experiment one."
 
-Two results are worth telling as stories, because they are the project behaving the way it was designed to.
+Two results are worth telling as stories, because they show the project behaving the way it was designed to.
 
-The first: E001-SC1 stress-tested the adaptive controller across six failure patterns it had never seen. In three of them the controller recognized it was outside its calibrated experience, 104 times, and each time it recorded an abstention: a logged "I do not know" plus a fallback to the safe baseline, instead of a guess. The persisted conclusion is `abstain_without_policy_claim`. The system declined to claim a win it could not support. That refusal is the result, and it is the most honest thing in this repository.
+The first: E001-SC1 stress-tested the adaptive controller across six failure patterns it had never seen. In three of them, the controller recognized it was outside its calibrated experience, 104 times, and each time it recorded an abstention: a logged "I do not know" plus a fallback to the safe baseline, instead of a guess. The persisted conclusion is `abstain_without_policy_claim`. The system declined to claim a win it could not support. That refusal is the result, and it is the most honest thing in this repository.
 
 The second: E002-PW1 completed all 32 runs and then invalidated itself, because its power meter turned out to sample 25 times slower than requested. The favorable-looking raw numbers were thrown out as inadmissible instead of being quietly kept. The rerun with a valid meter, PW2, is the result that counts.
 

RELEASING.md

@@ -1,9 +1,11 @@
 # Releasing gpu_stack
 
-This document describes how to cut a release.
+This document describes how to cut a release. The short version: you bump the version, tag the commit, and push the tag. CI does the building and publishing. Everything below is the detail behind that sentence.
 
 ## Prerequisites (one-time setup)
 
+These steps happen once, before the first release. They let GitHub Actions publish to PyPI without anyone handling an API token.
+
 1. Create the project on PyPI at https://pypi.org/manage/projects/ using the
    name `gpu_stack`.
 
@@ -55,6 +57,8 @@ sequence:
 
 ## Building locally (optional)
 
+You do not need this for a normal release, but it is the fastest way to check that the package builds before tagging:
+
 ```
 pip install -e ".[release]"
 python -m build