Docs: the suite is 41 files / 2405 checks, and releases are a thing now
Architecture and Development still quoted 29 files and 1932 checks. It also had
no release section, so it now says what release.sh does, why a release is a source
archive rather than a build, and that the first one is v10.8.
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.
Tracker + architecture: T2 closed — the app's buttons and the inspector actions are driven
Tracker: app.js can be imported now, and T2 is mostly closed
The blocker T2 recorded — "app.js cannot be imported at all" — is gone. A module
resolution hook applies the page's own import map to the whole graph, which
rewriting import lines cannot do, because the vendored addons behind walk3d import
the bare `three` themselves. So app-wiring.test.mjs boots the real app, lets it
adopt the room the server names, fires its own document keydown handler to check
command-Z reaches store.undo, and checks the live EventSource is opened.
What is left of T2 is the click-driven half: the toolbar and inspector buttons.
The stub DOM has no selector engine, so querySelectorAll returns nothing and a
click cannot be aimed at a real button. A known, small gap with a named cause.
Architecture also gained the resolver, the new test, and a correction — it still
said app.js could not be imported at all.
Tracker: the production-readiness pass — T1, T3-T11 closed, and B5 fixed
Ten of the eleven open tasks are done and each row says what actually changed.
T2 narrows to what is genuinely left: app.js's DOM event wiring and inspector
rendering. The pure logic and the escaping boundary are covered now, and
boot.test.mjs holds the ids the page has to provide.
The pass also found a bug. Making the gate trustworthy meant seeding city-fuzz's
traffic — it drove twenty cities with unseeded Math.random, which is why the full
suite failed where the file alone passed — and hunting that drive turned up a bus
leaving the city grid: a recorded junction decision held only a road INDEX, and
an index is not a junction, so a decision to carry on through index 0 one way was
still counted as a decision when the vehicle came back the other way, where there
is no road. The record names the direction now, the stop-for-a-space path clears
it, and _decideTurn refuses to act on a carry-on record where carrying on is not
possible.
Also recorded: the two traps this cost time to learn — a fresh query string does
not re-evaluate an already-imported ES module (the first login test was silently
inert because of it), and a test that configures its own preconditions can hide
the bug it exists to catch.
Three pages updated with the new facts: the stream caps and the same-origin check
(Server API), the checksum verification and the narrow install default (Hosting),
and the new tests plus the seeding rule (Architecture).
Tracker: all four open bugs fixed; note the light limit and the new invariants
B1-B4 are done, so the tracker's bug table is now a record of what each one
actually did rather than a list of what is wrong, and the status line reads 0
open bugs. Every entry names the test that holds it.
3D Walkthrough said 'only the first 16 get one', which was true and was the bug:
the pool was dealt out in plan order, so a particular lamp was dead for the life
of the room. It now describes what happens instead — the nearest sixteen, and
they follow you — and the 2D Editor Guide's note about lights points at it.
Architecture and Development gains the invariants the fixes created: no shadow
caster may hold a negative depth bias, the two wall-length floors are different
rules, the light budget goes to what the viewer can see, and a plan too large to
decompose reports it. Module line counts refreshed, including the two new test
files.
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.
Document the city, and the invariants that keep it cheap
The 3D Walkthrough page now covers what you actually see out of a window
— streets, traffic, night lighting — and why it is stylised rather than
photoreal. Architecture records the two rules that keep it from becoming
a cost: it is a separate module handed only a building envelope, and it
is instanced scenery that never casts into the room's shadow maps, has
no colliders and is cached across edits. The height datum is written
down too, since paving above it appears inside a ground-floor room.
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
Document exterior street ring
Update paths to lowercase roomcad/ folder
Rework wiki for the web edition
Complete RoomCAD project documentation