docs/ — Index¶

Map of everything under docs/, with freshness flags so agents and humans know what to trust. Agent-facing guides live at the repo root (CLAUDE.md, AGENTS.md) and in each major directory’s CLAUDE.md.

This tree also builds as a Sphinx/MyST site for Read the Docs — conf.py, requirements.txt and index.md (the landing page + nav) here, with .readthedocs.yaml at the repo root. Build it locally with:

pip install -r docs/requirements.txt
python -m sphinx -b html docs docs/_build/html

New Markdown files are picked up by the globbed toctrees in index.md automatically; a file needs an # H1 to get a nav entry.

The site is published in the same 16 languages as the product — see translations.md for the pipeline, the translated-page subset, and the Read the Docs per-language project setup.

Trust order for conflicts: code > docker-compose.yml/deploy.sh > root CLAUDE.md / directory CLAUDE.mds > the reference docs below > dated design docs/plans (historical snapshots — they describe intent at the time of writing, not necessarily the current code).

Reference docs (keep current)¶

Doc	Contents
`site-reference/`	What the site consists of — hand-written area guides (social, economy, content, games/apps) plus generated inventories of every page route, API route, game and app (`pnpm docs:site`)
`codebase-overview.md`	Canonical code-layout overview: stack, repo layout, conventions, where to look first
`architecture.md`	Runtime topology + deploy pipeline: what runs where in production, images, CI, ports, auth across tiers
`testing.md`	Test suites (Vitest main + epic, Go Bazel), how to run them, and which CI workflows gate them
`performance-slo.md`	Performance guardrails: bundle budgets, synthetic probes, RUM SLO bands, and rollback trigger policy
`design-language.md`	The visual system — Radial Avant-Garde Glass (the radial shell/hub/wheel-feed architecture + the Apple-style Liquid Glass material it references): `--site-*` token contract, themes + accent presets, primitives, typography, motion, a11y
`page-consistency.md`	Checklist + recipes for building pages that look native
`people.md`	RMH Capital leadership (canon) — the firm’s executive committee and six business heads, their titles and remits, plus the rules for writing them
`developer-api/`	The developer API documentation — guides plus a generated endpoint reference (`pnpm docs:api`). Replaces the removed in-app `/developer/docs` wiki; `internals.md` is the contributor view
`albums-storage.md`	Albums storage architecture (DB + R2/S3)
`coins.md`	Coin economy design (implementation plan, largely shipped)

Operations¶

Location	Contents
`runbooks/`	Current operational runbooks: Go runtime cutover (2026-06-22), Go fleet steady-state deploy (2026-06-23), assets/CDN cutover, and web hotswap rollback (flip Apache back to the previous blue/green color). Follow these for deploy/rollback work.
`go-migration/`	The Go+Bazel migration book: `go-backend-and-bazel.md` is the authoritative Go operator runbook; the PDF/HTML sections are the rendered design doc (written at the original 9-service scope — the fleet has grown since).
`misc/`	Security audits/reports (`SECURITY.md` is the current upload-security reference) + the UI redesign vision doc
`opti/`	Optimization/build-speed audits and plans (mostly executed)

Plans & specs (dated snapshots — check dates before trusting)¶

Location	Contents
`plans/2026-07-20-parity-qol-customization-design.md`	Parity, QOL & customization design (2026-07-20): sixteen features in four pillars — parity must-haves from comparable platforms (lists/custom feeds, unified saves with folders, history & resume, game hubs with reviews + player guides, post awards, wishlists), social & presence (rich presence + friends rail, custom status, close-friends circle, modular profile showcase), QOL & user customization (appearance/accessibility suite, user-authored theme studio + theme economy, home/sidebar layout control, notification matrix + quiet hours, feed controls), and universal search v2. Verified gap inventory, data models, wave prioritization, KPIs. Companion to the 2026-07-15 and 2026-07-19 docs
`plans/2026-07-19-platform-expansion-design.md`	Platform expansion design (2026-07-19): twelve features specified as deltas over shipped systems — Arcade Pass (per-game daily challenges), Creator Studio (multi-tier memberships + dashboard), live Spaces, cross-game party system, RMHEvents + RSVP, replays-as-content, P2P cosmetic marketplace, gifting v2, weekly digest email, AI concierge, onboarding “First Week” arc, shareable stat cards. Includes a verified ground-truth inventory of what already exists, data models, wave-based prioritization, KPIs. Companion to the 2026-07-15 doc
`plans/2026-07-15-cross-system-feature-ideas.md`	Cross-system feature ideas design doc (2026-07-15): six features that compose existing systems — Tournaments Hub, Wager Matches, self-referential prediction markets, creator coin→value bridge, AI personas as residents, unified live-ops season + spectating/”Guess the ___”. Data models, economy loops, prioritization (RMHLadder “Career Mode” excluded — owned separately)
`plans/2026-07-14-liquid-glass-ui-redesign.md`	Sitewide Liquid Glass redesign design doc (2026-07-14): glass as the material system — tokens, elevation tiers, realism/reactivity/performance specs, per-page coverage incl. library/studio/shop/admin, phased rollout
`superpowers/`	The main archive of dated design specs + implementation plans (~75 files, `plans/` + `specs/`), plus the reusable `i18n-extraction-guide.md`
`plans/`	Older dated plan/design pairs (dream-rift, rmhmusic, rmhcode CLI, terraform/helm migration, farming sim)
`full-rewrite-design-2026-07-18.md`	Full rewrite design & implementation spec (2026-07-18, machine-readable): target architecture, database domain-schema redesign, async backbone, frontend decomposition, exact deletion inventories, and a dependency-ordered task graph (R0–R5) with per-task verify/acceptance/rollback
`scalability-audit-2026-07-17.md`	Scalability & future-proofing audit (2026-07-17): what breaks at 10x–100x users/data across DB, feed/social, caching, realtime, infra, frontend, and security — with a phased roadmap
`ci-speed-audit-2026-07-17.md`	CI/CD speed audit (2026-07-17): measured timings for the 79-workflow fleet, deploy-pipeline latency breakdown, redundancy map, and phased recommendations (parallel deploy gate, `buildx bake`, PR-lane consolidation, registry layer cache)
`website-improvement-plan.md`	Cross-cutting audit + phased roadmap (2026-06-30)
`mobile-friendliness-audit.md`	Mobile audit — findings implemented 2026-06-29 (historical)
`feed/`	Feed/timeline scaling plan

Per-feature docs¶

Location	Feature
`rmhbox/`	RMHBox party games — largest doc set: `info.md` (agent-facing codebase reference — keep in sync when changing RMHBox), design specs, phase plans
`altair/`	Altair strategy game — implementation, multiplayer, balance patch history
`rmhmusic/`, `rmhtube/`, `rmhvibe/`, `rmhtech/`	App design docs (rmhtube `features.md` is a 2025 roadmap — historical)
`signal-forge/`, `temple-of-joy/`, `void-breaker/`, `daily-puzzles/`, `rmhpoetry/`	Game design docs
`alex-tamagotchi/`	Alex, the Discord tamagotchi pet (now implemented in `go-services/internal/discordbot`)
`textbook/`, `indonesia-history/`	Generated book projects (architecture textbook; Library content) — content artifacts, not code docs

⚠️ Known-stale docs (do not trust these claims)¶

These predate the Next.js → TanStack Start migration and/or the Go cutover:

Any reference to a repo-root specs/ directory — it was deleted; the legacy AI-agent game specs it held (vega.md and friends) are gone with it
rmhtube/features.md — 2025 roadmap for a now-shipped app (its stack line is now correct, but it still describes intent rather than the shipped feature set)
Older design docs in rmhbox/, plans/, misc/, and the textbook chapters mention Next.js in historical context — the routes/stack described there map to app/routes/ + TanStack Start today
../go-services/FOUNDATION.md — a pkg/ API reference; the removed pkg/events/pkg/realtime sections were cut, but treat go-services/CLAUDE.md as canonical (go-services/README.md was refreshed to the current 3-service-in-prod reality)
Anything claiming production runs PM2 — production is Docker Compose with a blue/green web hotswap (see architecture.md)

Fixed in the 2026-07-29 audit: the stack lines in void-breaker/specs.md, temple-of-joy/game-design.md and rmhtube/features.md now name TanStack Start. temple-of-joy/ was rewritten again on 2026-07-30 alongside the game itself: game-design.md describes the current economy, and the four docs that described the superseded one (patch-1.md, patch-2.md, content-expansion.md, implementation-plan.md) were deleted. The repo-root specs/ directory this file used to point at no longer exists — the reference was removed rather than repaired.