Developer guide — a map of the repo

Where things live. Mission is the why and the decision test; Contributing is the rules (freeze, CI, branches, releases). Read those once; this one is a lookup table.

Start here, by goal

Repo map

Inside src/ — one file per layer

Status

Exactly two places record state, and they answer different questions:

Check both: a PR can be merged while part of its original scope stays open.

Do not add a third status table, an unlinked TODO, or a doc claiming something neither agrees with. git log --grep='^S-' is full of findings of exactly that shape — claims with no implementation behind them — and this project treats that as a bug class.

Two docs carry a narrow slice of state and MUST NOT be duplicated elsewhere: docs/THREAT_MODEL.md (what is defended, and how) and docs/HARDWARE.md + android/TESTING.md (device evidence — 🧪 means verified in code, not on hardware).

Install & verify a release

The four surfaces in docs/APPS.md, with the commands that don't fit on a picker page.

Android APK. Permanent rolling link, rebuilt on every merge: <major>.<minor>.<stamp>+<sha>.

curl -LO https://github.com/sloev/spore/releases/download/rolling/spore-android.apk
curl -LO https://github.com/sloev/spore/releases/download/rolling/spore-android.apk.sha256
sha256sum -c spore-android.apk.sha256

Allow installs from the browser/files app — builds are debug-signed until a release keystore exists, so Android will warn about an unknown developer. nightly-YYYY.MM.DD keeps the last five dated builds for rollback; /releases/ latest/download/spore-android.apk is the last tagged build with assets.

Single-file web node. Save it, mail it, put it on a stick — CI asserts zero external requests, so it opens over file:// with no internet. Its own "Download a copy" button re-serializes the page so one seed makes the next; identity and bridges live in localStorage. Every release carries the same file as a permanent asset, so a copy doesn't depend on this site staying up.

cargo build --release --lib --target wasm32-unknown-unknown
node web/build-standalone.mjs                            # -> web/spore-standalone.html

Desktop daemon.

cargo build --release        # -> target/release/spore
cargo run                    # in-memory mesh demo
cargo run -- node.yaml       # bridges from a config file

No network to reach crates.io? Every release also carries this source tree with every dependency vendored in — it unpacks flat, so give it a folder:

mkdir spore-offline && cd spore-offline
curl -LO https://github.com/sloev/spore/releases/latest/download/spore-offline-bundle.tar.gz
tar xzf spore-offline-bundle.tar.gz
cargo build --release --offline

Seed Sheet. Printable A4, fountain-coded QR on one side, wire format by hand on the other — a stained or partial print can still recover the payload (SPORE's own erasure coding, turned on itself). See Continuity for why this exists.

cd site && npm install && node seed/build-seedsheet.mjs   # -> web/spore-seedsheet.html

Building and testing

docs/CONTRIBUTING.md has the full CI command list. This is which commands apply to which part:

Conventions

• The wire format, the C ABI and the golden vectors are frozen. pr-guard.yml's file list is the ground truth; allow-frozen-change is the escape hatch for a deliberate 2.0.
• No fake UI. A control that does not do what it visually claims — a toggle with no backend, a status that cannot be false, a 🧪 claim with no device behind it — either does not ship, or ships visibly disabled with a reason.
• HARDBRUT upstream (supernihil/hardbrut) is normative for anything a person looks at. SPORE keeps no design-language document of its own. The flat web/vendor/hardbrut/ is vendored at build time and trusted as-is for the Pages site and Android; the web app (the standalone) instead consumes HARDBRUT/3 at web/vendor/hardbrut3/ (M10-D).
• Docs MUST NOT drift from code. Documented byte values live once, generated, in reference/vectors.json. CI enforces it.
• Branch model: master is protected; work happens on a topic branch off it (feat/…, fix/…, docs/…) and squash-merges back. No develop.

Android → HARDBRUT token mapping

The Android app consumes HARDBRUT (supernihil/hardbrut v0.6) through Chrome.kt. The token source of truth is design/tokens.json, regenerated by design/generate.py into that file between the // >>> design tokens markers.

CRITICAL: Compose's Modifier.shadow() does not do zero blur — it is the blurred Material elevation shadow this language exists to replace. The hard shadow is drawn by hand in crate / CrateButton with a drawBehind offset rect (see Modifier.crate in Chrome.kt). Reach for Modifier.shadow() and a crate stops being a crate.

Typography. Display (headings, labels): system sans at FontWeight.Black, uppercase — HARDBRUT's Impact has no Android equivalent and constraint 1 forbids bundling a webfont, so this is the honest stand-in (DisplayHeading). Body / mono: FontFamily.Monospace (badges, captions, status, addresses).

Buttons (CrateButton). Two kinds, no more: Default (Palette.Yellow face) and Cancel (Palette.Paper face), both Palette.Ink ink. Same size, same Metrics.Border ink border, same hard shadow. Press translates the face 3dp down/right and drops the shadow to zero (Metrics.Throw). Disabled is frozen (no recolour).

Cards (Crate). Modifier.crate(): paper fill, 3dp ink border, hard no-blur offset shadow into reserved padding, zero radius (CrateShape = RoundedCornerShape(Metrics.Radius) where Radius = 0).

Inputs (ToughbookField). Paper field, 3dp ink border, hard shadow; focus thickens the border rather than removing it.

What was dropped with the old language. Scanlines/vignette/CRT bloom — HARDBRUT has no ambient VFX, removed entirely (scanlines() is gone). The old mascot — removed entirely: SPORE's brand is the wordmark only, no mascot, no icon. The old Void/Asphalt/Amber/Pink/Cyan/Phosphor/Kevlar/Dim palette members.

Where to go deeper