understand-anything · the shelf

When	Subject	Artifact	Area	Mode	Pages	Command
14 Sep 26	described subject server-match-lifecycle-design	One Log, Many Games BinaryBubble is a Go server behind gRPC that hosts many independently plugged games, where a match is nothing but its ordered action log and every process that touches that log is disposable.	docs · server	high-level 8-10 pages	10	/understand-anything --custom "How the BinaryBubble Go server runs a multiplayer match end to end, from the design point of view, for a reader who knows none of the technologies. Teach every technology and concept where it first matters, with the reasons and the rejected alternatives the design docs record. Transport: gRPC and why, Connect (connect-go, connectrpc for Flutter), gRPC-Web, unary-up / server-stream-down and why never bidirectional, protobuf and buf, the L7 load balancer and routing by service. Go: goroutines, one actor per match with a mailbox and no locks, context and cancellation, select on a fixed set of arms, the modular monolith and one binary that is split-ready, pods never dial pods, cattle versus pets. Redis as the backplane: what a stream is, XADD, XREAD, XRANGE, consumer groups with XREADGROUP, XACK and XAUTOCLAIM, the pending entries list, MAXLEN trimming, NOMKSTREAM, the four stream kinds WQ / LOG / LIVE / TAIL, hashes, sets, sorted sets, TTL with PX and EXPIRE, SET NX as a lease, Lua scripts as atomic compare-and-set, Redis TIME as the one clock, hash tags for cluster, AOF and async replication and what failover can lose. Distributed-systems ideas: a lease versus a lock, the epoch fence and writer fencing, at-least-once delivery absorbed by idempotency keys, the append is the commit, state = reduce(log) as event sourcing, replay by after_seq, the zombie writer, adoption by scan rather than notifications, drain versus kill, promise-after-resource. The system: matchmaking (tickets, per-shard leader lease, the pairing pass, pair_commit, the wake stream and floor timer), the match host (creation Law C, steady state Law B, adoption Law A, end and retention), the gateway relay (replay then live, synthesized heartbeats, live-only rejections, presence), the player service (guest identity, tokens, Ping and presence), the engine contract (Init, Validate, Apply, Evolve, OnTick) and the plugin freeze test, game config as versioned data, and Postgres as the deferred store. On top: how Fray Five rides all of it, as the closing walkthrough. No source code listings; pseudo-code at most. Universe: docs/server/server-lean-hld.md, docs/server/vision.md, docs/design/server/2026-08-15-matchmaking-component-design.md, docs/design/server/2026-08-15-server-internal-seams-design.md, server/CONTEXT.md, docs/api/README.md, docs/games/fray-five-rules.md. No Go or Dart source files." --mode "high-level 8-10 pages" --auto	offline open
Thesis BinaryBubble is a Go server behind gRPC that hosts many independently plugged games, where a match is nothing but its ordered action log and every process that touches that log is disposable. Asked for Explain, for a total newcomer, how the BinaryBubble Go server runs a multiplayer match end to end from a design perspective — teaching every technology and concept (transport, Go concurrency model, Redis backplane, distributed-systems primitives, and each system component) at the point it first matters, including the reasons and rejected alternatives the design docs record, closing with how Fray Five rides the whole system. Mode high-level 8-10 pages Universe docs · server · 7 files Pages 10 Built 14 Sep 2026, 14:18 · recorded Command /understand-anything --custom "How the BinaryBubble Go server runs a multiplayer match end to end, from the design point of view, for a reader who knows none of the technologies. Teach every technology and concept where it first matters, with the reasons and the rejected alternatives the design docs record. Transport: gRPC and why, Connect (connect-go, connectrpc for Flutter), gRPC-Web, unary-up / server-stream-down and why never bidirectional, protobuf and buf, the L7 load balancer and routing by service. Go: goroutines, one actor per match with a mailbox and no locks, context and cancellation, select on a fixed set of arms, the modular monolith and one binary that is split-ready, pods never dial pods, cattle versus pets. Redis as the backplane: what a stream is, XADD, XREAD, XRANGE, consumer groups with XREADGROUP, XACK and XAUTOCLAIM, the pending entries list, MAXLEN trimming, NOMKSTREAM, the four stream kinds WQ / LOG / LIVE / TAIL, hashes, sets, sorted sets, TTL with PX and EXPIRE, SET NX as a lease, Lua scripts as atomic compare-and-set, Redis TIME as the one clock, hash tags for cluster, AOF and async replication and what failover can lose. Distributed-systems ideas: a lease versus a lock, the epoch fence and writer fencing, at-least-once delivery absorbed by idempotency keys, the append is the commit, state = reduce(log) as event sourcing, replay by after_seq, the zombie writer, adoption by scan rather than notifications, drain versus kill, promise-after-resource. The system: matchmaking (tickets, per-shard leader lease, the pairing pass, pair_commit, the wake stream and floor timer), the match host (creation Law C, steady state Law B, adoption Law A, end and retention), the gateway relay (replay then live, synthesized heartbeats, live-only rejections, presence), the player service (guest identity, tokens, Ping and presence), the engine contract (Init, Validate, Apply, Evolve, OnTick) and the plugin freeze test, game config as versioned data, and Postgres as the deferred store. On top: how Fray Five rides all of it, as the closing walkthrough. No source code listings; pseudo-code at most. Universe: docs/server/server-lean-hld.md, docs/server/vision.md, docs/design/server/2026-08-15-matchmaking-component-design.md, docs/design/server/2026-08-15-server-internal-seams-design.md, server/CONTEXT.md, docs/api/README.md, docs/games/fray-five-rules.md. No Go or Dart source files." --mode "high-level 8-10 pages" --auto human In the repository `docs/understand-anything/server-match-lifecycle-design/` open the artifact offline copy the run behind it
14 Sep 26	PR #749 749	The Gateway Gains a Backplane A gateway that only answered health checks and version queries, holding state in memory a restart would erase, gains a shared Redis store, a real guest-identity call, and a component-registration seam.	docs · server	high-level 5-10 pages	7	/understand-anything --pr 749 --mode "high-level 5-10 pages" --auto	open
Thesis A gateway that only answered health checks and version queries, holding state in memory a restart would erase, gains a shared Redis store, a real guest-identity call, and a component-registration seam. Asked for You want an explanation of everything pull request #749 changed — the Map 02 wayfinder integration PR (closing map #626) that landed the Redis rig and player guest-identity platform foundation on the server. Mode high-level 5-10 pages Universe docs · server · 161 files Pages 7 Built 14 Sep 2026, 17:40 · recorded Command /understand-anything --pr 749 --mode "high-level 5-10 pages" --auto human In the repository `docs/understand-anything/749/` open the artifact the run behind it
12 Sep 26	PR #859 859-high-level-5-10-pages	The Frozen Five At the merge base a game plugin was one line in a design document over an empty tree; now an engine contract package, a conformance kit and a counter game stand where nothing did.	server · docs	high-level 5-10 pages	8	/understand-anything --pr 859 --mode "high-level 5-10 pages" --auto	open
Thesis At the merge base a game plugin was one line in a design document over an empty tree; now an engine contract package, a conformance kit and a counter game stand where nothing did. Asked for Explain pull request #859 as a whole, exactly as it stands — no part of it singled out. Mode high-level 5-10 pages Universe server · docs · 137 files Pages 8 Built 12 Sep 2026, 00:29 · recorded Command /understand-anything --pr 859 --mode "high-level 5-10 pages" --auto human In the repository `docs/understand-anything/859-high-level-5-10-pages/` open the artifact the run behind it
09 Sep 26	PR #971 971	A Second, Throwaway Fray Five Before this change, the tree meant to hold this match had zero tracked files — no clock, no seed stream, no architecture check, no transcript checker anywhere under it; after, a second, throwaway copy of Fray Five's rules sits there so bot matches can run at volume before the real engine lands, non-canonical by construction, yielding to the rules document wherever the two disagree.	server · docs	high-level 5-10 pages	8	/understand-anything --pr 971 --mode "high-level 5-10 pages" --auto run-afk --map 811	open
Thesis Before this change, the tree meant to hold this match had zero tracked files — no clock, no seed stream, no architecture check, no transcript checker anywhere under it; after, a second, throwaway copy of Fray Five's rules sits there so bot matches can run at volume before the real engine lands, non-canonical by construction, yielding to the rules document wherever the two disagree. Asked for Explain pull request #971 — BinaryBubble's final integration PR for wayfinder map #811, the bot match harness (rules sim, driver, transcript, run-one-match API) — at a high level, in roughly 5-10 pages. Mode high-level 5-10 pages Universe server · docs · 84 files Pages 8 Built 09 Sep 2026, 06:00 · recorded Command /understand-anything --pr 971 --mode "high-level 5-10 pages" --auto run-afk --map 811 In the repository `docs/understand-anything/971/` open the artifact the run behind it
09 Sep 26	PR #891 891	Guessing Like a Person Before this change a decide could already see the board and list every word the rules still allowed, but nothing turned that list into a guess; now two new stages run at the top of every decide — a felt state re-derived fresh each time, and a guess policy that surfaces words, doubts them and settles on one — under a standing rule that the same seed always replays the same play.	docs · server	high-level 5-10 pages	9	/understand-anything --pr 891 --mode "high-level 5-10 pages" --auto	open
Thesis Before this change a decide could already see the board and list every word the rules still allowed, but nothing turned that list into a guess; now two new stages run at the top of every decide — a felt state re-derived fresh each time, and a guess policy that surfaces words, doubts them and settles on one — under a standing rule that the same seed always replays the same play. Asked for Explain everything pull request #891 did — a wayfinder-map integration PR (closing #688) that adds the bot 'frayfive' brain: vocabulary completion, the B1 state spine, and the B2 guess policy. Mode high-level 5-10 pages Universe docs · server · 126 files Pages 9 Built 09 Sep 2026, 07:55 · recorded Command /understand-anything --pr 891 --mode "high-level 5-10 pages" --auto human In the repository `docs/understand-anything/891/` open the artifact the run behind it
08 Sep 26	PR #960 960	Ladders, Floors, and Honest Gates The pipeline's unattended mode still stopped and showed the owner at the cut and the write-repair stage, and two of its own checks reported a pass or fail the repository could not back; the mode now answers every failure from a fixed ladder that ends in a stop or a named, recorded loss, and every check that passes now means what it says.	docs · tools · other	high-level	6	/understand-anything --pr 960 --mode high-level --auto	open
Thesis The pipeline's unattended mode still stopped and showed the owner at the cut and the write-repair stage, and two of its own checks reported a pass or fail the repository could not back; the mode now answers every failure from a fixed ladder that ends in a stop or a named, recorded loss, and every check that passes now means what it says. Asked for Explain what pull request 960 changed, with no particular sub-part singled out. Mode high-level Universe docs · tools · other · 44 files Pages 6 Built 08 Sep 2026, 21:03 · recorded Command /understand-anything --pr 960 --mode high-level --auto human In the repository `docs/understand-anything/960/` open the artifact the run behind it
08 Sep 26	described subject persona-calibration	Persona & Calibration Persona & Calibration is the design that owns Fray Five's bot personas end to end — the axis space, the expansion map, the belt catalogs, and the self-play rig that checks them — so that a designer authors twelve closed axes instead of hand-tuning 101 parameters across 7 belts times 12 personas, and every resulting catalog is proven correct by running the real decision-making Brain rather than assumed at design time.	docs	high-level 3-4 pages only	4	/understand-anything --custom "Explain at high level subpart 4 Persona calibration and using only fray five bot design docs marked implementation ready by map 53 living in docs/design/gamebot. The step by step flow of what happens there and how it interacts with brain in plain concepts rather than formulas" --mode "high-level 3-4 pages only" --auto owner	open
Thesis Persona & Calibration is the design that owns Fray Five's bot personas end to end — the axis space, the expansion map, the belt catalogs, and the self-play rig that checks them — so that a designer authors twelve closed axes instead of hand-tuning 101 parameters across 7 belts times 12 personas, and every resulting catalog is proven correct by running the real decision-making Brain rather than assumed at design time. Asked for Give a high-level, plain-concept, step-by-step explanation of how the Persona & Calibration subpart (subpart 4) works and how it feeds into the Brain, drawing only on the fray-five bot design docs in docs/design/gamebot that map #53's readiness review certified implementation-ready. Mode high-level 3-4 pages only Universe docs · 7 files Pages 4 Built 08 Sep 2026, 20:09 · recorded Command /understand-anything --custom "Explain at high level subpart 4 Persona calibration and using only fray five bot design docs marked implementation ready by map 53 living in docs/design/gamebot. The step by step flow of what happens there and how it interacts with brain in plain concepts rather than formulas" --mode "high-level 3-4 pages only" --auto owner In the repository `docs/understand-anything/persona-calibration/` open the artifact the run behind it
08 Sep 26	described subject frayfive-bot-brain	Fray Five Bot Brain This follows one Decide call as it reads the board's felt shape, lets a guess voice and a power voice each propose a move, then settles and paces the winner like a human hand — one bot decision, four packages, step by step.	docs	high-level 3-4 pages only	4	not recorded	open
Thesis This follows one Decide call as it reads the board's felt shape, lets a guess voice and a power voice each propose a move, then settles and paces the winner like a human hand — one bot decision, four packages, step by step. Asked for Explain, at a high level and using only the six Fray Five Brain design documents (B1 cognitive state, B2 guess policy, B3 timing & pacing, B4 power policy, the consolidation amendment, and the errata amendment — the docs the implementation-readiness review certified as the Brain's final effective spec), the step-by-step flow of how B1 through B4 combine into a single bot decision, in plain concepts rather than formulas. Mode high-level 3-4 pages only Universe docs · 6 files Pages 4 Built 08 Sep 2026, 10:59 · committed Command not recorded — this pack predates run.json In the repository `docs/understand-anything/frayfive-bot-brain/` open the artifact the run behind it
08 Sep 26	PR #859 859	The Engine Contract Design rule 8 had long promised a game plugin behind three named methods with no Go package ever built to give that promise a shape; this change grows the rule to five frozen methods and backs it with a real interface, a tagged output type, a conformance kit that runs a game's own scenario files as a reference host, and a small game proving all three work.	server · docs	full	24	not recorded	open
Thesis Design rule 8 had long promised a game plugin behind three named methods with no Go package ever built to give that promise a shape; this change grows the rule to five frozen methods and backs it with a real interface, a tagged output type, a conformance kit that runs a game's own scenario files as a reference host, and a small game proving all three work. Asked for Explain pull request #859 in full — the entire change, not a narrowed slice of it. Mode full Universe server · docs · 137 files Pages 24 Built 08 Sep 2026, 00:52 · committed Command not recorded — this pack predates run.json In the repository `docs/understand-anything/859/` open the artifact the run behind it
07 Sep 26	described subject match-high	Disposable Pods, Living Matches A match is a live game session reached through a gateway relay and a per-match Redis event log, built so any server pod can die at any moment without losing it and so the platform never has to understand the game being played.	server	high-level	8	not recorded	open
Thesis A match is a live game session reached through a gateway relay and a per-match Redis event log, built so any server pod can die at any moment without losing it and so the platform never has to understand the game being played. Asked for Explain, at a high level, how a match executes on the BinaryBubble server — from the point players are in a match through actions being taken, state advancing, and the match ending. Mode high-level Universe server · 70 files Pages 8 Built 07 Sep 2026, 20:30 · committed Command not recorded — this pack predates run.json In the repository `docs/understand-anything/match-high/` open the artifact the run behind it

Newest first, rebuilt from the packs on disk by python3 tools/understand-anything/index.py --open — every row comes from that pack's own json, and this page is never committed.