From 50773d8d41f44fe9dc7046ed081f59ef01cd9bd6 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Fri, 7 Aug 2026 23:53:02 +0200
Subject: [PATCH 1/2] docs: sync docs with recent changes (branding
 white-label, SM022/SM023, Docker scaffold)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs had drifted behind several merged features:

- modules/branding: rewritten. The page still described the pre-#237 module
  (name, logo, favicon, colour). Adds the dark-background logo variant,
  design pack, announcement banner, configurable footer + its limits and
  href allow-list, presets, the anonymous asset routes and their cache
  policy, and the magic-number upload check. Corrects the allowed-types
  list, which still advertised image/svg+xml — SVG is excluded on purpose
  (XML that can carry <script>, i.e. stored XSS from our own origin).

- reference/diagnostic-codes: add the missing SM022/SM023 rows. Every other
  code in the framework was documented; these two shipped with #238.

- framework/discovery: document i18n_audience and requires_framework in the
  ModuleMeta section, cross-linked to the i18n page.

- reference/deployment: the Build section told operators to hand-roll a
  Dockerfile that every scaffold has shipped since #252 — and the example
  used a Node-only frontend stage, which cannot work, since gen-pages reads
  the installed Python modules. Replaced with the shipped assets plus why
  the single builder stage is load-bearing.

- alembic upgrade head -> heads across guide/reference. Every real command
  (Makefile, smpy new, the container CMD) uses the plural; the singular
  errors once a second module ships a branch label.

- Module count eleven -> twelve; branding was missing from the home page
  list, and its index row predated the white-label work.

Verified: vitepress build clean, and the four cross-page anchors checked
against the generated HTML (ignoreDeadLinks is on, so the build itself
does not catch them).

Claude-Session: https://claude.ai/code/session_013W1MJ3T4FJEBcx1Xs9Tea2
---
 docs/framework/discovery.md        |  11 ++
 docs/guide/installation.md         |   2 +-
 docs/guide/quickstart.md           |   2 +-
 docs/index.md                      |   2 +-
 docs/modules/branding.md           | 181 ++++++++++++++++++++++++-----
 docs/modules/index.md              |   4 +-
 docs/reference/deployment.md       |  70 ++++++-----
 docs/reference/diagnostic-codes.md |   4 +
 8 files changed, 215 insertions(+), 61 deletions(-)

diff --git a/docs/framework/discovery.md b/docs/framework/discovery.md
index b2168016..48c17720 100644
--- a/docs/framework/discovery.md
+++ b/docs/framework/discovery.md
@@ -44,6 +44,7 @@ meta = ModuleMeta(
     view_prefix="/orders",  # where the view router mounts
     depends_on=["Products"],  # hard ordering requirements
     version="1.0.0",  # semver for the module
+    i18n_audience="public",  # who gets this module's locale catalog
 )
 ```
 
@@ -72,6 +73,16 @@ A list of other modules' `meta.name` values that **must be loaded first**. The f
 
 Semver string. Used in diagnostic/boot logging to help operators correlate deployed module versions with bug reports. Unless a module declares `requires_framework`, it is not parsed for automated version-range checks.
 
+### `requires_framework`
+
+Optional PEP 440 specifier (e.g. `">=1.0,<2.0"`) for the framework API version the module supports. When set, the module is rejected at boot if the installed `simple_module_core.FRAMEWORK_API_VERSION` doesn't satisfy it. When `None` (the default), no compatibility check runs. See [module authoring](/module-authoring).
+
+### `i18n_audience`
+
+Who the module's locale catalog is shipped to — `"public"` (the default) or `"admin"`.
+
+Catalogs ride the Inertia shared props on full page loads, so a module whose UI sits entirely behind login can declare `i18n_audience="admin"` and stop anonymous visitors downloading admin form labels on every public page. The catalog is shipped as soon as the user authenticates, and server-side `Translator` lookups always see every namespace either way. See [Internationalization → Audience](/framework/i18n#audience).
+
 ## The `simple_module` group
 
 Entry points are the same mechanism that ships with `importlib.metadata`:
diff --git a/docs/guide/installation.md b/docs/guide/installation.md
index f0d659e0..a4b3bf5f 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/installation.md
@@ -58,7 +58,7 @@ smpy new myapp --preset standard --with background_tasks,file_storage
 
 Dependencies between modules are resolved automatically — e.g. `users` always pulls in `auth`, and `file_storage` pulls in `settings`. The `settings` module ships only in the `full` preset (or when added explicitly with `--with settings`).
 
-After scaffolding, `smpy new` runs `uv sync`, `npm install`, and `alembic upgrade head` for you (skip with `--no-install` if you'd rather drive that yourself).
+After scaffolding, `smpy new` runs `uv sync`, `npm install`, and `alembic upgrade heads` for you (skip with `--no-install` if you'd rather drive that yourself).
 
 ## Boot it
 
diff --git a/docs/guide/quickstart.md b/docs/guide/quickstart.md
index f504d3c9..865c890d 100644
--- a/docs/guide/quickstart.md
+++ b/docs/guide/quickstart.md
@@ -17,7 +17,7 @@ smpy new myapp --yes
 cd myapp
 ```
 
-`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`). The CLI runs `uv sync`, `npm install`, and `alembic upgrade head` for you.
+`--yes` accepts the defaults (SQLite, no multi-tenancy, the `standard` preset: `auth`, `users`, `dashboard`, `permissions`). The CLI runs `uv sync`, `npm install`, and `alembic upgrade heads` for you.
 
 For an interactive run with prompts, drop the `--yes`. For a preset + extras: `smpy new myapp --preset standard --with background_tasks,file_storage --yes`.
 
diff --git a/docs/index.md b/docs/index.md
index a7fda0e4..3e869c8d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -26,7 +26,7 @@ features:
     link: /guide/first-module
     linkText: Build a module
   - title: Use a bundled module
-    details: Eleven first-party modules ship with the framework — auth, users, keycloak, permissions, settings, file_storage, background_tasks, feature_flags, audit_log, dashboard, site_lock.
+    details: Twelve first-party modules ship with the framework — auth, users, keycloak, permissions, settings, file_storage, branding, background_tasks, feature_flags, audit_log, dashboard, site_lock.
     link: /modules/
     linkText: Browse modules
   - title: Operate it in production
diff --git a/docs/modules/branding.md b/docs/modules/branding.md
index ac93ab74..08e39c94 100644
--- a/docs/modules/branding.md
+++ b/docs/modules/branding.md
@@ -1,6 +1,8 @@
 # branding
 
-Lets an administrator customise the application's identity — **app name**, **logo**, **favicon**, and **primary colour** — from an admin page, with no code change or redeploy. Values persist in the shared [settings](/modules/settings) store (there is no branding table) and reach **every** Inertia page (authenticated *and* guest) through a registered shared-props provider, so the frontend can render the name, swap the logo/favicon, and apply the brand colour everywhere.
+White-labels the application. An administrator sets the **app name**, **logo** (plus an optional dark-background variant), **favicon**, **primary colour**, **[design pack](/framework-conventions#design-packs-site-wide-look)**, a site-wide **announcement banner**, and a **configurable footer** — from an admin page, with no code change or redeploy.
+
+Values persist in the shared [settings](/modules/settings) store (there is no branding table) and reach **every** Inertia page — authenticated *and* guest — through a registered shared-props provider, so the frontend can render the name, swap the logo/favicon, apply the brand colour, and show the banner and footer everywhere.
 
 ## ModuleMeta
 
@@ -10,25 +12,49 @@ Lets an administrator customise the application's identity — **app name**, **l
 | `route_prefix` | `/api/branding` |
 | `view_prefix` | `/branding` |
 | `depends_on` | `["Settings", "FileStorage"]` |
+| `i18n_audience` | `"admin"` |
 
-It depends on `settings` for storage and `file_storage` for the uploaded logo/favicon bytes.
+It depends on `settings` for storage and `file_storage` for the uploaded logo/favicon bytes. Its catalog is admin-form strings, so it declares [`i18n_audience="admin"`](/framework/i18n#audience) and is kept out of the guest bundle — branding's *public* contribution rides the shared-props provider, not i18n keys.
 
 ## Routes
 
-### API
+### API (admin)
 
-All JSON endpoints — including the read — require `branding.manage` (they back the admin editor).
+Every JSON endpoint — including the reads — requires `branding.manage`; they back the admin editor.
 
-| Method + path | Body / response | Permission |
-|---|---|---|
-| `GET /api/branding/` | → `BrandingOut` | `branding.manage` |
-| `PUT /api/branding/` | `BrandingUpdate` → `BrandingOut` | `branding.manage` |
-| `POST /api/branding/logo` | `multipart` (field `file`) → `BrandingOut` | `branding.manage` |
-| `POST /api/branding/favicon` | `multipart` (field `file`) → `BrandingOut` | `branding.manage` |
-| `DELETE /api/branding/logo` | → `BrandingOut` (logo cleared) | `branding.manage` |
-| `DELETE /api/branding/favicon` | → `BrandingOut` (favicon cleared) | `branding.manage` |
+| Method + path | Body / response |
+|---|---|
+| `GET /api/branding/` | → `BrandingOut` |
+| `PUT /api/branding/` | `BrandingUpdate` → `BrandingOut` |
+| `POST /api/branding/presets/{key}` | → `BrandingOut` (`404` for an unknown key) |
+| `GET /api/branding/footer` | → `FooterConfig` |
+| `PUT /api/branding/footer` | `FooterConfig` → `FooterConfig` (whole-object replace) |
+| `POST /api/branding/logo` | `multipart` (field `file`) → `BrandingOut` |
+| `POST /api/branding/logo-dark` | `multipart` (field `file`) → `BrandingOut` |
+| `POST /api/branding/favicon` | `multipart` (field `file`) → `BrandingOut` |
+| `DELETE /api/branding/logo` | → `BrandingOut` (logo cleared) |
+| `DELETE /api/branding/logo-dark` | → `BrandingOut` (dark logo cleared) |
+| `DELETE /api/branding/favicon` | → `BrandingOut` (favicon cleared) |
+
+`PUT /` only touches the text fields (`app_name`, `primary_color`, `design_pack`, `banner_message`, `banner_severity`); images are set and cleared through their dedicated upload/delete routes, and the footer through `PUT /footer`. A `design_pack` slug that no installed module registered is rejected with `422` — accepting it would put `"<slug>-root"` on the document with no stylesheet behind it, so the site would look unchanged with nothing in the UI explaining why.
+
+Uploads are validated **before** the bytes reach `file_storage`: an unsupported or unconvincing type returns `415`, an oversized image `413` (see [Image guard-rails](#image-guard-rails)).
+
+### Public assets (anonymous)
+
+Registered through the [`register_public_routes`](/framework/public-routes) hook as `exact` + **GET-only** rules, so uploading and clearing the same paths stay behind `branding.manage`.
+
+| Method + path | Response |
+|---|---|
+| `GET /api/branding/logo` | The configured logo bytes (`404` when unset) |
+| `GET /api/branding/logo-dark` | The dark-background variant (`404` when unset) |
+| `GET /api/branding/favicon` | The configured favicon (`404` when unset) |
+
+Branding serves these itself rather than linking `file_storage`'s download route, which is gated by `file-storage.download` — no logged-out visitor carries that permission, and the sign-in page, the public landing page and every `<link rel="icon">` are exactly where the logo has to appear. Each route resolves **only** the id currently held in branding settings and streams that one file, so it is not a way to read arbitrary files out of `file_storage`.
+
+Responses carry `Content-Disposition: attachment` and `X-Content-Type-Options: nosniff`. Both are ignored for subresource loads (`<img>`, `<link rel="icon">`) but stop a direct visit rendering the bytes as a document at the app's own origin.
 
-`PUT` only touches the text fields (`app_name`, `primary_color`); the logo and favicon are set/cleared through their dedicated upload/delete routes. Uploads are validated **before** the bytes are handed to `file_storage` — an unsupported MIME type returns `415`, an oversized image returns `413` (see [Image guard-rails](#image-guard-rails)).
+When `file_storage` is backed by S3-compatible storage, the route returns a `302` to a presigned URL. That redirect is deliberately **uncached** — the target expires, so caching it would hand out a dead link after the TTL.
 
 ### View
 
@@ -36,22 +62,39 @@ All JSON endpoints — including the read — require `branding.manage` (they ba
 |---|---|---|
 | `GET /branding/` | `Branding/Manage` | `branding.view` |
 
-The page reads the current values from the shared `branding` prop, so the view endpoint passes no page props of its own.
+Current branding reaches the page through the shared `branding` prop. The endpoint passes only what the shared prop *can't* carry: `designPacks` (which packs the installed modules registered) and `presets` (the built-in list, with swatches).
+
+## Asset caching
+
+The published URL carries `?v=<file id>`. Replacing an image stores a **new** `file_storage` file, so the id doubles as a content address — the URL changes and caches invalidate for free.
+
+| Request | `Cache-Control` |
+|---|---|
+| With a `?v=` version | `public, max-age=31536000, immutable` (one year) |
+| Without a version | `public, max-age=3600` (one hour) |
+
+An unversioned URL can serve new bytes later, so it must never be immutable; the short TTL lets it self-correct. A `404` is never cached, so the next request retries once the setting is fixed.
 
 ## Public contracts
 
 ```python
 from branding.contracts import BrandingOut, BrandingUpdate
+from branding.contracts.footer import FooterConfig, FooterColumn, FooterLink
 ```
 
 | Class | Purpose |
 |---|---|
-| `BrandingOut` | Current branding with logo/favicon resolved to download URLs: `app_name`, `primary_color`, `logo_url`, `favicon_url`. |
-| `BrandingUpdate` | Editable text fields only: `app_name` (≤ 60 chars, non-blank), `primary_color` (`#rrggbb` or empty). |
+| `BrandingOut` | Current branding with images resolved to URLs: `app_name`, `primary_color`, `design_pack`, `logo_url`, `logo_dark_url`, `favicon_url`, `banner_message`, `banner_severity`. |
+| `BrandingUpdate` | Editable text fields, all optional: `app_name`, `primary_color`, `design_pack`, `banner_message`, `banner_severity`. |
+| `FooterConfig` | The whole footer: `tagline`, `copyright_owner`, `note`, `columns`, `social_links`. |
+| `FooterColumn` | A titled group: `title` + `links`. |
+| `FooterLink` | One `label` + `href`. |
+
+`BrandingUpdate` is the strict one. An unknown `banner_severity` is a clear `422` here, while the settings validator normalises it to `info` — settings hydrate from the DB, where a hand-edited row must degrade to a readable banner rather than stop the app from booting. `design_pack` and `primary_color` are shape-checked in the DTO for the same reason: a malformed value becomes a `422` instead of a `500` when `BrandingSettings` re-validates.
 
 ## Models
 
-**None.** Branding owns no tables. The four values are stored in the shared settings store at **SYSTEM** scope, hydrated into `app.state.branding.settings` at boot, and hot-swapped on save via the settings reload path.
+**None.** Branding owns no tables. Every value is stored in the shared settings store at **SYSTEM** scope, hydrated into `app.state.branding.settings` at boot, and hot-swapped on save via the settings reload path.
 
 ## Settings
 
@@ -59,17 +102,84 @@ DB-backed via `register_module_settings`; pydantic defaults seed at boot. Edited
 
 | Field | Default | Purpose |
 |---|---|---|
-| `app_name` | `"SimpleModule"` | Application name (trimmed; must be non-blank and ≤ 60 chars). |
+| `app_name` | `"SimpleModule"` | Application name (trimmed; non-blank, ≤ 60 chars, no control characters). |
 | `primary_color` | `""` | Brand colour as a lowercase `#rrggbb` hex string; `""` ⇒ use the theme default. |
-| `logo_file_id` | `""` | `file_storage` UUID of the uploaded logo; `""` ⇒ no custom logo. |
-| `favicon_file_id` | `""` | `file_storage` UUID of the uploaded favicon; `""` ⇒ no custom favicon. |
+| `design_pack` | `""` | Slug of a registered [design pack](/framework-conventions#design-packs-site-wide-look); `""` ⇒ base tokens only. |
+| `logo_file_id` | `""` | `file_storage` UUID of the logo; `""` ⇒ no custom logo. |
+| `logo_dark_file_id` | `""` | UUID of the dark-background variant; `""` ⇒ fall back to `logo_file_id`. |
+| `favicon_file_id` | `""` | UUID of the favicon; `""` ⇒ no custom favicon. |
+| `banner_message` | `""` | Site-wide announcement text (≤ 500 chars); `""` ⇒ no banner. |
+| `banner_severity` | `"info"` | One of `info`, `warning`, `danger`. Unknown values normalise to `info`. |
+| `footer_tagline` | `""` | Footer tagline line. |
+| `footer_copyright_owner` | `""` | Name in the copyright line. |
+| `footer_note` | `""` | Small footer caption. |
+| `footer_columns` | `""` | JSON blob of `FooterColumn` entries (see [Configurable footer](#configurable-footer)). |
+| `footer_social_links` | `""` | JSON blob of `FooterLink` entries. |
+
+`app_name` rejects control characters, not just blanks: the name is used in HTML titles and — critically — email `Subject` headers, where an embedded CR/LF would survive a bare `strip()` and then raise, breaking every transactional email.
+
+The two footer lists are strings because the settings store holds strings; `branding.footer` owns (de)serialising them, leniently, so a malformed row degrades to "no configured footer" rather than an error. Each blob is capped at 8 000 characters so a single setting row can't grow unbounded.
 
 ### Image guard-rails
 
 Enforced in the API before the upload reaches `file_storage`:
 
 - **Max size:** 2 MB (`413` otherwise).
-- **Allowed types:** `image/png`, `image/jpeg`, `image/svg+xml`, `image/webp`, `image/gif`, `image/x-icon` / `image/vnd.microsoft.icon` (`415` otherwise).
+- **Allowed types:** `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/x-icon` / `image/vnd.microsoft.icon` (`415` otherwise).
+- **Magic-number check:** the first bytes must match the declared format's signature (`415` otherwise).
+
+The declared `Content-Type` on a multipart part is chosen by the caller, so it is a claim rather than a fact — `payload.html` renamed `logo.png` would otherwise be stored and later served back under an `image/*` type. The signature check is what makes the type real.
+
+**SVG is excluded on purpose.** It is an XML document that can carry `<script>`, so serving one back from the app's own origin would be stored XSS. The `attachment` + `nosniff` headers on the asset route defend in depth, but the narrower allow-list is what actually keeps executable markup out of the store.
+
+### Asset lifecycle
+
+Replacing or clearing an image deletes the file it stopped referencing, so repeated logo tweaks don't leave orphans in `file_storage`. Cleanup is **best effort**: the setting change has already been persisted, so a storage fault is logged rather than failing an otherwise-successful rebrand.
+
+## Presets
+
+A preset is a named one-click look, applied through the ordinary update path so every validator still runs:
+
+```http
+POST /api/branding/presets/ocean
+```
+
+Seven ship with the module — `emerald`, `ocean`, `indigo`, `violet`, `amber`, `rose`, `slate` — each setting a `primary_color`.
+
+**A preset carries appearance, never identity.** `PRESET_FIELDS` restricts a preset to `primary_color` and `design_pack`; `BrandingPreset` rejects any other field at construction. The app name, the uploaded images and a live banner are deployment identity or operational state, and survive applying a preset — a preset that overwrote a logo an admin had just uploaded would destroy exactly the work the branding page exists to do.
+
+A preset's `design_pack` runs the same registration check a manual update gets, rather than trusting the built-in list.
+
+Presets are **not an extension point** — the list is fixed in the module. A module that wants to contribute its own look ships a [design pack](/framework-conventions#design-packs-site-wide-look) instead, which is the registry-backed, module-contributed mechanism.
+
+## Announcement banner
+
+A message plus a severity, rendered above every shell — app, public and auth — because an outage notice is most useful to the people who cannot sign in. An empty message hides it entirely.
+
+Severity colours are semantic, not brand-tinted: a warning wearing the deployment's accent colour stops reading as a warning.
+
+## Configurable footer
+
+Whole-object replace via `PUT /api/branding/footer` — a partial merge into nested link lists has no obvious semantics.
+
+| Limit | Value |
+|---|---|
+| Columns | 6 |
+| Links per column | 8 |
+| Social links | 8 |
+| Link label / column title | 40 chars |
+| Link URL | 500 chars |
+| Tagline / copyright / note | 200 chars |
+
+Link URLs are restricted to `http(s)` or a single-leading-slash app path. This is the security-relevant part: these are authored by an admin and rendered into an anchor on *every* page, including guest ones, so the scheme allow-list is what keeps a `javascript:` URL out of the document. `//host` is a protocol-relative absolute URL rather than a path, so it falls through to the scheme check and is rejected.
+
+With nothing configured the shared prop reports `footer: null` and the framework's built-in footer renders unchanged.
+
+## Dark-background logo
+
+The sidebar and mobile bar sit on a near-black surface in every theme, while the sign-in card and public page are light — so a single logo cannot read on both. Uploading a *Logo (dark backgrounds)* variant swaps it in on those surfaces only.
+
+It is optional: with none set the shared prop reports `logoDarkUrl: null` and the frontend falls back to `logoUrl`, so single-logo deployments look exactly as they did. On the frontend, use `darkSurfaceLogo(branding)` from `@simple-module-py/ui/lib/brand`, which applies that fallback in one place.
 
 ## How branding reaches the frontend
 
@@ -80,31 +190,48 @@ On startup the module registers a shared-props provider (`register_inertia_share
   "branding": {
     "appName": "Acme Corp",
     "primaryColor": "#1d4ed8",
-    "logoUrl": "/api/file-storage/files/<id>/download",
-    "faviconUrl": "/api/file-storage/files/<id>/download"
+    "designPack": "gca",
+    "logoUrl": "/api/branding/logo?v=<file id>",
+    "logoDarkUrl": "/api/branding/logo-dark?v=<file id>",
+    "faviconUrl": "/api/branding/favicon?v=<file id>",
+    "banner": { "message": "Maintenance at 22:00 UTC", "severity": "warning" },
+    "footer": {
+      "tagline": "Maps for everyone",
+      "copyrightOwner": "Acme Corp",
+      "note": "",
+      "columns": [{ "title": "Product", "links": [{ "label": "Docs", "href": "/docs" }] }],
+      "socialLinks": [{ "label": "GitHub", "href": "https://github.com/acme" }]
+    }
   }
 }
 ```
 
-`primaryColor` is `null` when unset; `logoUrl` / `faviconUrl` are `null` when no file is configured (otherwise a `file_storage` download URL derived from the stored id). The provider is defensive — it returns `{}` if branding state isn't mounted yet, so a half-booted app never errors a render. Because changes go through the settings store, a save hot-reloads `app.state.branding.settings`; the next render reflects the new values without a restart.
+`primaryColor` and `designPack` are `null` when unset; the three image URLs are `null` when no file is configured. `banner` is `null` when no message is set, so the frontend renders nothing at all rather than an empty bar, and `footer` is `null` when nothing is configured, so the built-in framework footer stays.
+
+The provider is defensive — it returns `{}` if branding state isn't mounted yet, so a half-booted app never errors a render. Because changes go through the settings store, a save hot-reloads `app.state.branding.settings`; the next render reflects the new values without a restart.
 
 ## Permissions
 
 | Code | Granted to | Purpose |
 |---|---|---|
 | `branding.view` | `admin` | open the Branding admin page (`/branding`) |
-| `branding.manage` | `admin` | read + write branding via the API (edit name/colour, upload/clear logo + favicon) |
+| `branding.manage` | `admin` | read + write branding via the API (name, colour, design pack, banner, footer, image upload/clear) |
 
 ## Menu
 
 | Label | URL | Icon | Section | Group | Order | Roles |
 |---|---|---|---|---|---|---|
-| `Branding` | `/branding` | `palette` | `SIDEBAR` | `Administration` | `115` | `["admin"]` |
+| `Branding` | `/branding/` | `palette` | `SIDEBAR` | `Administration` | `115` | `["admin"]` |
 
 ## Inertia pages
 
-- `Branding/Manage.tsx` — the admin editor: app-name + colour form, logo and favicon upload/clear, and a live preview.
+- `Branding/Manage.tsx` — the admin editor: app name, colour and design pack, preset picker, logo / dark logo / favicon upload and clear, banner editor, footer editor, and a live preview.
 
 ## Locales
 
 `branding/locales/en.json` — namespace `branding`, top-level key `manage` (the admin page strings).
+
+## Notes
+
+- Branding is SYSTEM-scoped (one identity per deployment). The settings store already supports tenant/user scope, leaving room for per-tenant branding later.
+- The primary colour overrides the `--primary` / `--sidebar-primary` CSS variables from a single hex; the full OKLCH colour scale is not regenerated.
diff --git a/docs/modules/index.md b/docs/modules/index.md
index c8fce364..7843de5d 100644
--- a/docs/modules/index.md
+++ b/docs/modules/index.md
@@ -1,6 +1,6 @@
 # Bundled modules
 
-simple_module_python ships with eleven first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
+simple_module_python ships with twelve first-party modules. Each is a regular Python package — same shape as a module you'd write yourself — registered through the `simple_module` entry point and discovered at boot. They are independent: install only what you need.
 
 | Module | Depends on | What it provides |
 |---|---|---|
@@ -11,7 +11,7 @@ simple_module_python ships with eleven first-party modules. Each is a regular Py
 | [`settings`](/modules/settings) | — | DB-backed key/value store with system / tenant / user precedence; per-module pydantic settings registration; hot reload; `smpy settings` CLI. |
 | [`feature_flags`](/modules/feature_flags) | — | Runtime feature toggles with system + tenant overrides. |
 | [`file_storage`](/modules/file_storage) | `settings` | Pluggable file storage (filesystem, S3-compatible) with upload validation, presigned URLs, browse/download/delete UI. |
-| [`branding`](/modules/branding) | `settings`, `file_storage` | Admin-configurable app identity — app name, logo, favicon and primary colour — pushed to every page via Inertia shared props. |
+| [`branding`](/modules/branding) | `settings`, `file_storage` | White-labelling — app name, logo (plus a dark-background variant), favicon, primary colour, design pack, announcement banner and configurable footer, pushed to every page via Inertia shared props. Serves the logo and favicon from anonymous routes so guests see the brand too. |
 | [`background_tasks`](/modules/background_tasks) | `users` | Celery + Redis workers, persistent task history, retry, stuck-task sweep, live worker dashboard. |
 | [`audit_log`](/modules/audit_log) | `users` | Automatic field-level audit trail for SQLModel entities, with an admin UI to browse change history. |
 | [`dashboard`](/modules/dashboard) | `users` | Authenticated landing page with system overview (user counts, module list, health checks). |
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index c81fcafc..a85485a9 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -9,7 +9,7 @@ Before serving traffic:
 - [ ] `SM_ENVIRONMENT` set to something other than `development`/`testing` (those two are the only values treated as non-prod).
 - [ ] `SM_SECRET_KEY` is a strong random value (not the default).
 - [ ] `SM_DATABASE_URL` points at Postgres (`postgresql+asyncpg://`), not SQLite.
-- [ ] `alembic upgrade head` run against the production DB.
+- [ ] `alembic upgrade heads` run against the production DB.
 - [ ] Frontend built (`npm run build` → `static/dist/`) and bundled into the image — outside `development`/`testing`, the app renders assets from the Vite manifest, not a dev server (see [Static assets](#static-assets)).
 - [ ] App boot in a non-development `SM_ENVIRONMENT` starts clean. Module discovery runs strict (missing/invalid `meta` and entry-point failures raise), and the migration check (SM010) aborts boot — so a successful start covers those. The full page/locale/auth-provider diagnostic suite only runs in development, so do a clean dev boot before shipping (see [diagnostic codes](/reference/diagnostic-codes)).
 - [ ] Admin bootstrap complete — an admin user exists and can log in.
@@ -19,43 +19,55 @@ Before serving traffic:
 
 ## Build
 
-Typical Docker build for an app scaffolded by `smpy new`:
-
-```dockerfile
-FROM python:3.12-slim AS builder
-WORKDIR /app
-COPY pyproject.toml uv.lock ./
-RUN pip install uv && uv sync --frozen --no-dev
-COPY . .
-RUN uv run python -m compileall .
-
-# Build the frontend
-FROM node:20-slim AS frontend
-WORKDIR /app/client_app
-COPY client_app/package.json client_app/package-lock.json ./
-RUN npm ci
-COPY client_app .
-RUN npm run build
-
-FROM python:3.12-slim
-WORKDIR /app
-COPY --from=builder /app /app
-# Vite builds to ../static/dist relative to client_app, i.e. /app/static/dist
-COPY --from=frontend /app/static/dist /app/static/dist
-CMD ["uv", "run", "uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--proxy-headers"]
+**Every `smpy new` scaffold ships its own Docker assets** — you don't write these by hand:
+
+| Path | What it is |
+|---|---|
+| `docker/host.Dockerfile` | Multi-stage app image (also used for the Celery worker/beat services) |
+| `docker-compose.yml` | Stack matched to your `--db` choice, plus `redis`/`worker`/`beat` when `background_tasks` is installed |
+| `.dockerignore` | Keeps `node_modules`, caches and local state out of the build context |
+| `make docker-build` / `docker-up` / `docker-down` | Build, run and stop the stack |
+
+```bash
+make docker-up   # builds the image, applies migrations, serves on :8000
 ```
 
-Tune worker count with `--workers N` for multi-CPU boxes, or run behind a process manager like Gunicorn with Uvicorn workers. A single worker is CPU-bound (one process, the GIL) — multiple workers scale read throughput roughly linearly on a multi-core box.
+The compose file pins `SM_ENVIRONMENT=production` for the app service — a container has no Vite dev server, so development mode would emit asset tags pointing at nothing.
+
+### Why the image has one builder stage
+
+The obvious split — a Python stage and a Node stage — **cannot work here**. The Vite build imports `modules.generated.{ts,css}`, which `gen-pages` emits by inspecting the *installed Python modules*. A Node-only stage has no venv and no entry points, so it can't generate those files and the frontend build fails for any app with module pages.
+
+So `docker/host.Dockerfile` keeps uv and Node in one builder stage and orders the work:
+
+1. `uv sync --all-packages --no-dev` (deps first, then the real source, for layer caching)
+2. `gen-pages` — writes the page manifest and generated module imports
+3. `npm run build` — the production bundle
+4. `uv sync` once more, so hatch `force-include` picks up freshly built module `static/dist` output
+
+The runtime stage is `python:3.12-slim-bookworm`, runs as a non-root `app` user (uid 10001), and carries a `HEALTHCHECK` against `/health`.
+
+If you build your own image instead, keep that ordering — skipping `gen-pages` before the Vite build is the single most common way to get a container that builds cleanly and then serves a blank page.
+
+### Sizing the web process
+
+The shipped `CMD` runs a single Uvicorn worker. Tune worker count with `--workers N` for multi-CPU boxes, or run behind a process manager like Gunicorn with Uvicorn workers. A single worker is CPU-bound (one process, the GIL) — multiple workers scale read throughput roughly linearly on a multi-core box.
 
 **Size the DB pool to the worker count.** Each worker keeps its own connection pool of up to `SM_DB_POOL_SIZE + SM_DB_MAX_OVERFLOW` (default `10 + 20 = 30`) connections, so the deployment's ceiling is `workers × (pool_size + max_overflow)`. Keep that under the database's `max_connections` (Postgres default `100`) or workers will throw `asyncpg.TooManyConnectionsError: sorry, too many clients already` under load. For example, 4 workers want roughly `SM_DB_POOL_SIZE=5`, `SM_DB_MAX_OVERFLOW=10` (≤ 60 connections). For larger fleets, put PgBouncer in front instead of growing every pool.
 
+### Migrations on container start
+
+The shipped `CMD` runs `alembic upgrade heads && uvicorn …`. Note **`heads` (plural)**: each module's first migration sets its own `branch_labels`, so once a second module ships one, `upgrade head` (singular) errors out.
+
+That default is right for a single container. Once you run more than one replica, move migrations to a one-shot job instead — see [Running migrations on deploy](#running-migrations-on-deploy).
+
 ## Running migrations on deploy
 
-Don't migrate from inside the web container's startup hook — that way lies races when scaling up. Run it as a **one-shot job** before rolling the web tier:
+Once you run more than one replica, drop the `alembic upgrade heads` from the container's start command — concurrent replicas racing the same migration is exactly the failure it causes. Run it as a **one-shot job** before rolling the web tier instead:
 
 ```bash
 # one-shot container — run from the host project (default workspace scaffold)
-cd host && uv run alembic upgrade head
+cd host && uv run alembic upgrade heads
 
 # then roll web tier
 kubectl rollout restart deployment/web
@@ -152,7 +164,7 @@ Outside `development`/`testing` (i.e. any other `SM_ENVIRONMENT`), the app serve
 ## Zero-downtime deploys
 
 1. Build new image.
-2. Run `alembic upgrade head` as a one-shot job.
+2. Run `alembic upgrade heads` as a one-shot job.
 3. `kubectl rollout restart deployment/web` (rolling).
 4. Watch logs for `SM010` (would mean step 2 failed silently).
 5. Rollback path: `kubectl rollout undo`; old pods come back up against the new DB. **Make sure** your migrations are backward-compatible for at least one release cycle (expand/contract pattern — see below).
diff --git a/docs/reference/diagnostic-codes.md b/docs/reference/diagnostic-codes.md
index 36515438..2efef023 100644
--- a/docs/reference/diagnostic-codes.md
+++ b/docs/reference/diagnostic-codes.md
@@ -30,6 +30,10 @@ The framework runs a set of static checks over installed modules at app boot. Th
 | `SM019` | WARNING | Module declares a non-empty `view_prefix` and overrides `register_routes` but registers neither menu items nor permissions — admins can't reach the pages from the sidebar or grant access from the role editor. | Add `register_menu_items` for a sidebar entry, or `register_permissions` to surface the module in the role editor (sub-pages of another module typically just register permissions). |
 | `SM020` | ERROR | More than one auth-provider module is installed (e.g. both `users` and `keycloak`). | Install exactly one auth provider. |
 | `SM021` | WARNING | No auth-provider module is installed. | Install an auth provider (e.g. `simple-module-users` or `simple-module-keycloak`). |
+| `SM022` | WARNING | A module's `styles.css` contains a top-level `@theme`, `@custom-variant` or `@utility` block. That file is imported into `layer(components)`, where those at-rules are inert. | Move the block to the module's `theme.css`, which is imported unlayered so its tokens actually register. |
+| `SM023` | WARNING | A module's `theme.css` contains an unlayered plain rule (anything but an at-rule or a `:root`-style selector). Unlayered CSS outranks every Tailwind utility. | Move the rule to the module's `styles.css`, which is imported into `layer(components)` so utilities still win. |
+
+`SM022`/`SM023` are the two halves of the same invariant: a module's optional [`theme.css` is imported unlayered and `styles.css` into `layer(components)`](/module-authoring#styling), and CSS put in the wrong one silently does nothing (or silently wins everything).
 
 ## When diagnostics fire
 

From 1337b83e37c96fe61c70a967290b63c75fecc9c2 Mon Sep 17 00:00:00 2001
From: Anto Subash <antosubash@live.com>
Date: Sat, 8 Aug 2026 17:05:34 +0200
Subject: [PATCH 2/2] docs: fix accuracy issues found in review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- branding: the magic-number check was overstated. validate_image matches
  the head against *any* allowed signature, not the one the declared
  Content-Type implies, so a genuine PNG sent as image/jpeg passes and is
  stored as image/jpeg. Reworded to the property that actually holds
  (non-images are kept out) rather than type/content agreement.

- branding: the file_storage download permission is `file_storage.download`,
  not `file-storage.download`. Copied the hyphen from the stale comment at
  branding/constants.py:76; the constant is FileStoragePermissions.DOWNLOAD.

- framework/overview: module count said "ten first-party modules" — missed
  in the eleven -> twelve sweep, so two pages one click apart disagreed.

- module-authoring: one more `alembic upgrade head` -> `heads`, in the
  publish-a-module flow whose very next subsection tells the author to add
  branch_labels — i.e. exactly the case the plural exists for.

- deployment: the new "run make docker-up" Build section sat three lines
  under a checklist item requiring Postgres, while the default SQLite
  compose pins SM_ENVIRONMENT=production *and* a SQLite URL. Added a
  warning that the SQLite stack is local/demo only, and why it isn't a
  one-env-var swap (migration histories are dialect-frozen).

Also fixes the scaffold README template, which shipped `upgrade head` into
every generated project while that project's own Makefile and Dockerfile
use `heads`. test_cli_new_scaffold_layout already asserts the singular form
is gone from the Makefile, so the README was simply missed.

Verified: 216 CLI tests pass, vitepress build clean.

Claude-Session: https://claude.ai/code/session_013W1MJ3T4FJEBcx1Xs9Tea2
---
 docs/framework/overview.md                                | 2 +-
 docs/module-authoring.md                                  | 2 +-
 docs/modules/branding.md                                  | 8 +++++---
 docs/reference/deployment.md                              | 6 ++++++
 .../cli/simple_module_cli/templates/host/README.md.tpl    | 4 ++--
 5 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/docs/framework/overview.md b/docs/framework/overview.md
index 939fa066..62169f11 100644
--- a/docs/framework/overview.md
+++ b/docs/framework/overview.md
@@ -92,4 +92,4 @@ This is how the `auth.user` shared prop is built: framework middleware calls wha
 - [Lifecycle hooks](/framework/lifecycle) — the lifecycle hooks in call order with examples.
 - [Middleware pipeline](/framework/middleware) — execution order and how to slot your own in.
 - [Settings & app.state](/framework/settings) — framework vs. module state.
-- [Bundled modules](/modules/) — the ten first-party modules and what each one ships.
+- [Bundled modules](/modules/) — the twelve first-party modules and what each one ships.
diff --git a/docs/module-authoring.md b/docs/module-authoring.md
index 4301a1d6..c7659113 100644
--- a/docs/module-authoring.md
+++ b/docs/module-authoring.md
@@ -200,7 +200,7 @@ installed or a module's models change:
 pip install simple_module_my_module
 alembic revision --autogenerate -m "add my-module"
 # review the generated file
-alembic upgrade head
+alembic upgrade heads
 ```
 
 The host's `env.py` (scaffolded from the framework's template) calls:
diff --git a/docs/modules/branding.md b/docs/modules/branding.md
index 08e39c94..a7f657b0 100644
--- a/docs/modules/branding.md
+++ b/docs/modules/branding.md
@@ -50,7 +50,7 @@ Registered through the [`register_public_routes`](/framework/public-routes) hook
 | `GET /api/branding/logo-dark` | The dark-background variant (`404` when unset) |
 | `GET /api/branding/favicon` | The configured favicon (`404` when unset) |
 
-Branding serves these itself rather than linking `file_storage`'s download route, which is gated by `file-storage.download` — no logged-out visitor carries that permission, and the sign-in page, the public landing page and every `<link rel="icon">` are exactly where the logo has to appear. Each route resolves **only** the id currently held in branding settings and streams that one file, so it is not a way to read arbitrary files out of `file_storage`.
+Branding serves these itself rather than linking `file_storage`'s download route, which is gated by `file_storage.download` — no logged-out visitor carries that permission, and the sign-in page, the public landing page and every `<link rel="icon">` are exactly where the logo has to appear. Each route resolves **only** the id currently held in branding settings and streams that one file, so it is not a way to read arbitrary files out of `file_storage`.
 
 Responses carry `Content-Disposition: attachment` and `X-Content-Type-Options: nosniff`. Both are ignored for subresource loads (`<img>`, `<link rel="icon">`) but stop a direct visit rendering the bytes as a document at the app's own origin.
 
@@ -126,9 +126,11 @@ Enforced in the API before the upload reaches `file_storage`:
 
 - **Max size:** 2 MB (`413` otherwise).
 - **Allowed types:** `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/x-icon` / `image/vnd.microsoft.icon` (`415` otherwise).
-- **Magic-number check:** the first bytes must match the declared format's signature (`415` otherwise).
+- **Magic-number check:** the first bytes must match the signature of *one of* the allowed formats (`415` otherwise).
 
-The declared `Content-Type` on a multipart part is chosen by the caller, so it is a claim rather than a fact — `payload.html` renamed `logo.png` would otherwise be stored and later served back under an `image/*` type. The signature check is what makes the type real.
+The declared `Content-Type` on a multipart part is chosen by the caller, so it is a claim rather than a fact — `payload.html` renamed `logo.png` would otherwise be stored and later served back under an `image/*` type. The signature check is what rules that out.
+
+Note the exact property: the bytes must look like **some** allowed image format, not like the one the caller declared. A genuine PNG uploaded as `image/jpeg` passes and is stored as `image/jpeg`. That mismatch is harmless here — every allowed format is a raster or icon the browser renders inertly — and the check still does the job it exists for, which is keeping non-images out of the store.
 
 **SVG is excluded on purpose.** It is an XML document that can carry `<script>`, so serving one back from the app's own origin would be stored XSS. The `attachment` + `nosniff` headers on the asset route defend in depth, but the narrower allow-list is what actually keeps executable markup out of the store.
 
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index a85485a9..1f950329 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -34,6 +34,12 @@ make docker-up   # builds the image, applies migrations, serves on :8000
 
 The compose file pins `SM_ENVIRONMENT=production` for the app service — a container has no Vite dev server, so development mode would emit asset tags pointing at nothing.
 
+::: warning `SM_ENVIRONMENT=production` doesn't make the default stack production-ready
+A default (SQLite) scaffold's compose file also pins `SM_DATABASE_URL=sqlite+aiosqlite:////app/data/app.db`, which fails the second item in the checklist above. That stack is for local and demo runs — a real deployment wants a `--db postgres` scaffold.
+
+The reason it isn't just a URL swap: a migration history is **dialect-frozen at autogenerate time** (`sa.false()` renders as `DEFAULT 0` under SQLite, which Postgres rejects), so containers must run the same dialect the migrations were generated against. Moving an existing SQLite scaffold to Postgres means regenerating migrations against Postgres, not editing one env var.
+:::
+
 ### Why the image has one builder stage
 
 The obvious split — a Python stage and a Node stage — **cannot work here**. The Vite build imports `modules.generated.{ts,css}`, which `gen-pages` emits by inspecting the *installed Python modules*. A Node-only stage has no venv and no entry points, so it can't generate those files and the frontend build fails for any app with module pages.
diff --git a/framework/cli/simple_module_cli/templates/host/README.md.tpl b/framework/cli/simple_module_cli/templates/host/README.md.tpl
index 591a1bbe..399add26 100644
--- a/framework/cli/simple_module_cli/templates/host/README.md.tpl
+++ b/framework/cli/simple_module_cli/templates/host/README.md.tpl
@@ -14,7 +14,7 @@ cp .env.example .env
 # First time only — initialize the migration history for the modules you
 # picked. Inspect the generated file, then apply it.
 alembic revision --autogenerate -m "initial schema"
-alembic upgrade head
+alembic upgrade heads
 
 # Run the API
 python main.py
@@ -39,7 +39,7 @@ uv add simple_module_my_module
 
 # 2) generate & apply the migration (new tables + any schema changes)
 alembic revision --autogenerate -m "add my-module"
-alembic upgrade head
+alembic upgrade heads
 
 # 3) restart the host — the module's routes, menu items, permissions,
 #    feature flags, events, and health checks register automatically