docs(website): theming phase 5 as built — brand assets and the cached HTML shell #106

wtclaude · 2026-08-08T01:11:28Z

wtclaude commented

2026-08-08 01:11:28 +00:00

Docs pair for RunicGateway/website#123. Targets edge.

Marks Phase 5 of website/THEMING_AND_NAV.md landed, adds the "Phase 5 as landed" section, documents the new route and the shell lifecycle in BACKEND_DESIGN.md, and regenerates api-route-inventory.json from the route manifest (a four-line diff — the one new route).

The build differed from §8 in five places, each recorded with its reason:

The upload is one call, not two. §8's "upload endpoint on the existing multer config" reads as reuse POST /admin/uploads, then PUT the row. That endpoint is staffOnly — editors reach it — while the row it would write is adminOnly, and a run that uploaded and then failed would leave a file in /uploads that nothing references.
brand_assets needed a validator of its own, which the design did not anticipate: these are the only settings values written straight into HTML as URLs.
The shell cache carries a TTL as well as explicit invalidation, because the cache is per process and only the worker that handled the write learns of it.
The logo went into all six MoonDot surfaces, not the three persistent shells §8 named.
The theme flash, deferred here by phases 3–4, is fixed — with a handoff from the injected boot block to SiteContext, gated on a successful fetch.

Also recorded as observed-and-left-alone: the shell's <title> and description still come from BRAND_NAME/BRAND_DESCRIPTION rather than the admin-set site_title that getPublic().brand.name prefers, so an instance renamed through the admin panel still shows the env name in its tab and link previews. Fixing it would change the served shell for instances with no brand_assets row, which is exactly what §9's byte-identical criterion forbids in this phase.

Checklist

I have read CONTRIBUTING.md.
The change builds and existing tests/checks pass locally.
I have added or updated tests/docs where it makes sense.
My commits are reasonably scoped with clear messages.

AI-assisted contributions (required)

No AI tools were used to produce this contribution.
AI tools were used. Tool(s): Claude Code (Opus 5). I have reviewed and understand
every change, and take responsibility for it. AI-authored commits are
marked with a Co-Authored-By / Assisted-By trailer.

License

I agree that my contribution is licensed under this project's license
(GNU GPL v3.0 or later), and I have the right to contribute it.

Docs pair for RunicGateway/website#123. Targets **`edge`**. Marks Phase 5 of [`website/THEMING_AND_NAV.md`](website/THEMING_AND_NAV.md) landed, adds the "Phase 5 as landed" section, documents the new route and the shell lifecycle in [`BACKEND_DESIGN.md`](website/BACKEND_DESIGN.md), and regenerates `api-route-inventory.json` from the route manifest (a four-line diff — the one new route). The build differed from §8 in five places, each recorded with its reason: - **The upload is one call, not two.** §8's "upload endpoint on the existing multer config" reads as *reuse `POST /admin/uploads`, then `PUT` the row*. That endpoint is `staffOnly` — editors reach it — while the row it would write is `adminOnly`, and a run that uploaded and then failed would leave a file in `/uploads` that nothing references. - **`brand_assets` needed a validator of its own**, which the design did not anticipate: these are the only settings values written straight into HTML as URLs. - **The shell cache carries a TTL as well as explicit invalidation**, because the cache is per process and only the worker that handled the write learns of it. - **The logo went into all six MoonDot surfaces**, not the three persistent shells §8 named. - **The theme flash, deferred here by phases 3–4, is fixed** — with a handoff from the injected boot block to `SiteContext`, gated on a *successful* fetch. Also recorded as observed-and-left-alone: the shell's `<title>` and description still come from `BRAND_NAME`/`BRAND_DESCRIPTION` rather than the admin-set `site_title` that `getPublic().brand.name` prefers, so an instance renamed through the admin panel still shows the env name in its tab and link previews. Fixing it would change the served shell for instances with **no** `brand_assets` row, which is exactly what §9's byte-identical criterion forbids in this phase. ## Checklist - [x] I have read [CONTRIBUTING.md](CONTRIBUTING.md). - [x] The change builds and existing tests/checks pass locally. - [x] I have added or updated tests/docs where it makes sense. - [x] My commits are reasonably scoped with clear messages. ## AI-assisted contributions (required) - [ ] No AI tools were used to produce this contribution. - [x] AI tools were used. Tool(s): `Claude Code (Opus 5)`. I have reviewed and understand every change, and take responsibility for it. AI-authored commits are marked with a `Co-Authored-By` / `Assisted-By` trailer. ## License - [x] I agree that my contribution is licensed under this project's license (**GNU GPL v3.0 or later**), and I have the right to contribute it.

wtclaude added 1 commit 2026-08-08 01:11:29 +00:00

docs(website): theming phase 5 as built — brand assets and the cached shell 97cb8be2d5

Records Phase 5 of THEMING_AND_NAV.md as landed and documents the new route
and the shell lifecycle in BACKEND_DESIGN.md.

Where the build differed from the design: the upload is one admin-only call
that writes the settings row too (rather than the generic staff upload plus a
PUT, which would leave unreferenced files and let editors change the site's
identity); brand_assets needed a validator of its own because these are the
only settings values written straight into HTML as URLs; the shell cache
carries a TTL as well as explicit invalidation because it is per process; and
the logo went into all six MoonDot surfaces rather than three.

Also notes what was deliberately left alone: the shell's title and description
still come from BRAND_NAME rather than the admin-set site_title, and fixing
that would change the served shell for instances with no brand_assets row —
which is exactly what the phase's acceptance criterion forbids.

Co-Authored-By: Claude <noreply@anthropic.com>

wtclaude referenced this pull request from RunicGateway/website

2026-08-08 01:12:12 +00:00

feat(theming): brand-asset overrides and a cached, settings-aware HTML shell (phase 5) #123

whitlocktech approved these changes 2026-08-08 02:04:50 +00:00

whitlocktech merged commit 2a8b9d5748 into edge

2026-08-08 02:05:05 +00:00

whitlocktech deleted branch docs/theming-nav-phase-5

2026-08-08 02:05:06 +00:00

whitlocktech referenced this issue from a commit

2026-08-08 02:05:07 +00:00

Merge pull request 'docs(website): theming phase 5 as built — brand assets and the cached HTML shell' (#106) from docs/theming-nav-phase-5 into edge

Sign in to join this conversation.