docs: update documentation to OKF v0.1 format

docs/guides/theming.md

@@ -1,50 +1,84 @@
 ---
 type: guide
 title: Theming
-description: How the 10 canonical themes are loaded, validated, and applied to the SPA via CSS custom properties.
-tags: [guide, theming, design]
-timestamp: 2026-07-21T18:28:00Z
+description: How the canonical themes are loaded, selected by administrators, and applied to the SPA via CSS custom properties.
+tags: [guide, theming, design, admin]
+timestamp: 2026-07-22T13:40:00Z
 ---
 
 # Theme catalog
 
-HIPCTF ships 10 canonical themes defined as JSON files in
-`backend/themes/` (`01-classic.json` … `10-monochrome.json`). The full
-list lives in `backend/src/common/types/theme-ids.ts`:
+HIPCTF ships canonical themes defined as JSON files in `backend/themes/`. The
+catalog is identified by `THEME_IDS` in
+`backend/src/common/types/theme-ids.ts`; the default is `classic`.
 
-`classic`, `midnight`, `sunset`, `forest`, `cyber`, `paper`, `crimson`,
-`ocean`, `neon`, `monochrome`.
+Each theme contains an `id`, display `name`, and token set containing colors,
+font family, radii, and spacing values. The frontend maps the supported visual
+tokens to CSS custom properties.
 
-Each theme is a flat map of CSS custom properties (colors, radii, font
-family) consumed by `frontend/src/styles.css`.
+# Administrator workflow
+
+1. Sign in as an administrator and open **Admin area → General**, or navigate
+to `/admin/general`.
+2. Wait for the settings and available-theme requests to finish.
+3. Choose a value from **Global theme** (`data-testid="general-themeKey"`).
+4. Click **Save** (`data-testid="general-save"`).
+5. Verify that `Saved.` appears and that the page uses the selected colors,
+font, and corner radii. Reloading the application should preserve the theme.
+
+The selector lists themes exposed by `GET /api/v1/admin/general/themes`. Only
+theme JSON files present in the configured `THEMES_DIR` are listed, while the
+loader still maintains canonical fallback themes for bootstrap and runtime
+safety.
 
 # Backend loading
 
 `ThemeLoaderService` (`backend/src/common/utils/theme-loader.service.ts`)
-runs on module init:
+runs on module initialization:
 
-1. Reads every `*.json` file in `backend/themes/`.
-2. Validates each against the `Theme` interface
-   (`backend/src/common/types/theme.ts`) — unknown theme ids, malformed
-   JSON, or missing tokens throw `ApiError(THEME_INVALID)`.
-3. Backfills any of the 10 canonical themes that are missing from disk
-   (safety net so a partial checkout still boots).
-4. Reads `SETTINGS_KEYS.THEME_KEY` (default `'classic'`). If the value is
-   not in `THEME_IDS`, the loader falls back to `classic`, logs a
-   warning, and persists `'classic'` back to settings so the next request
-   is self-healing.
+1. Reads theme JSON files from `THEMES_DIR` (default `./themes`).
+2. Validates IDs and tokens; malformed files are skipped or reported through
+the loader's validation path.
+3. Backfills missing canonical themes so the application always has a valid
+catalog.
+4. Validates the configured `SETTINGS_KEYS.THEME_KEY`; an unknown value falls
+back to `classic` and is persisted as the repaired setting.
 
-The resolved theme object is sent to the SPA in the
-`GET /api/v1/bootstrap` payload (see [System Endpoints](/api/system.md)).
+The selected theme is sent to the SPA in `GET /api/v1/bootstrap` (see
+[System Endpoints](/api/system.md)). Administrators can read and update the
+selection through [Admin Endpoints](/api/admin.md). A successful general-settings
+update emits a `general` SSE event containing the new `themeKey`.
 
 # Frontend application
 
 `BootstrapService` (`frontend/src/app/core/services/bootstrap.service.ts`)
-writes each theme token onto `document.documentElement` (e.g.
-`--color-primary`, `--radius-md`, `--font-family`). Because `styles.css`
-references the tokens via `var(--token)`, swapping themes is instant.
+fetches `/api/v1/bootstrap` once per application lifecycle, stores the payload
+in signals, and applies the returned theme before the UI is rendered. The
+`applyThemeToCss` helper in
+`frontend/src/app/core/services/bootstrap.types.ts` writes these tokens to
+`document.documentElement`:
+
+| Theme token | CSS custom property |
+|---|---|
+| `primary`, `secondary`, `accent`, `surface`, `text` | `--color-*` |
+| `success`, `warning`, `danger` | `--color-*` |
+| `fontFamily` | `--font-family` |
+| `radii.sm`, `radii.md`, `radii.lg` | `--radius-sm`, `--radius-md`, `--radius-lg` |
+
+Reapplying a theme replaces the existing values. `clearThemeCss` removes every
+property managed by the helper. Components consume the properties through
+`var(--token)` in the global stylesheet and component styles.
+
+# Verification
+
+The frontend theme tests in `tests/frontend/bootstrap-theme.spec.ts` verify
+that all tokens are written, missing tokens are a no-op, reapplication replaces
+values, zero-valued radii are preserved, and cleanup removes every managed
+property.
 
 # See also
 
 - [System Endpoints](/api/system.md)
+- [Admin — General Settings](/guides/admin-general-settings.md)
+- [Admin Endpoints](/api/admin.md)
 - [Backend Module Map](/architecture/backend-modules.md)