Wiki: a user guide with a worked example, not a history of the repository
Task 4 and 6 of the cleanup.
The tracker had 73 rows and 55 of them were finished work. That made it a history
of the development, which is what git is for. The closed rows are gone; what is
left is one table of 18 — the 5 open items, the 8 deliberate decisions, the one
thing waiting on a human, and the 4 notes that are easy to get wrong twice. A line
at the top says where the completed work went, so the emptiness reads as a
decision rather than as an oversight.
Home is a landing page now: the live URL first, then a six-step "try it in sixty
seconds" example with what each step gives you, then navigation, then how to run
it locally. The sidebar carries the live link on every page.
Architecture and Development was the one page that was about the repository
rather than about using RoomCAD — module line counts, design-decision narratives,
and a second copy of rules that already live in AGENTS.md. It is now how to run
it, how to run the tests, a one-line map of the modules, and a pointer to
AGENTS.md and RELEASE.md as the single source. Repeated rules drift; the copy in
the wiki is the one nobody updates.
Verified: every internal wiki link resolves, no page is orphaned, every page is
reachable from the sidebar, and no page claims the tracker shows finished work.
Resync the wiki with the code, and add a Project Tracker
The wiki had not been touched since 2026-08-23, and 38 commits landed on the
code after that. Some of what it said had been wrong for weeks.
Hosting and Deployment was the worst of it: it documented an nginx :443 ->
Caddy :8077 topology with certbot, a certificate hook and /etc/caddy paths.
None of that has existed since RoomCAD moved behind the host's master Caddy —
the real path is master Caddy -> RoomCAD's own Caddy on loopback :8081 ->
server.py, with no certbot anywhere and the master answering ACME itself. It
now describes the architecture that is actually deployed, the two service
accounts, the systemd sandbox, and why deploy.sh chowns the database.
Architecture and Development claimed city.js was ~630 lines (it is ~5200) and
that app.js is the only module that touches the network (login.js does too,
and plan.js/store.js do no I/O at all). It now has accurate sizes and module
responsibilities, the test runner and CI, and the newer invariants — the sky
dome must contain the walkable city, and frames must stop when the 3D view is
not on screen.
Server API and Storage gained the endpoint it was missing (/api/live-check),
the baseSeq staleness rule, the JSON-object body requirement, and the note
that rooms.db.sql is structure only.
Troubleshooting and Live Collaboration lost their nginx instructions and
gained the service-account failure mode and the two-file Caddy ownership.
Project Tracker is new. There was no tracker anywhere — not in the wiki, not
in issues (the repository has never had one), not in milestones. It records
what this audit fixed, the 4 bugs and 11 tasks still open, and the handful of
things that are deliberate and must not be 'fixed' by accident.
Rework every page: simpler, example-led, and matching the code
The wiki had drifted from the app. The worst of it:
- Live Collaboration described an auto-save model that no longer exists
("editing auto-saves, debounced ~600 ms"). The real flow is deliberate:
Join Live, Live Active, Leave Live Mode, with unsaved drafts on a
separate in-memory channel that never creates versions.
- Server API listed six endpoints and no authentication. There are
eleven, all but login behind a session cookie, plus a browser_sessions
table that decides which design a browser reopens.
- File Format documented four furniture kinds; there are ten plus two
ceiling fixtures, and canvas / origin / publicAreas were missing.
- 2D Editor omitted Measure, Public areas and the automatic floor layout.
- 3D Walkthrough claimed the sun advances in real time. It does not — the
hour is a user setting, and the L key switches to placed-lights-only.
Every page is now example-led: a worked bedroom in Getting Started, curl
recipes against the API, a complete valid .rcad document, a two-browser
walkthrough for Live, and copy-pasteable deploy and backup commands.
Architecture gains an Invariants section recording why the shadow bias
must stay zero and why a wall end must cross its neighbour's half
thickness, so the light-leak bug cannot quietly return. Troubleshooting
gains entries for that leak, the fail-closed password file and WebGPU.
All 11 pages checked: no broken internal links.
Document standalone 3D environment
Rework wiki for the web edition
Complete RoomCAD project documentation
Initialize the RoomCAD documentation wiki