You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2026/06/26 03:15:58 UTC

(skywalking-horizon-ui) branch main updated: feat: offline-capable readonly template mode, env-native config, and reachability-based Cluster Status (#80)

This is an automated email from the ASF dual-hosted git repository.

wu-sheng pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/skywalking-horizon-ui.git


The following commit(s) were added to refs/heads/main by this push:
     new d3b66d2  feat: offline-capable readonly template mode, env-native config, and reachability-based Cluster Status (#80)
d3b66d2 is described below

commit d3b66d203d19622f03f976d0b8f62de6e4f9f880
Author: 吴晟 Wu Sheng <wu...@foxmail.com>
AuthorDate: Fri Jun 26 11:15:54 2026 +0800

    feat: offline-capable readonly template mode, env-native config, and reachability-based Cluster Status (#80)
    
    * feat(config): readonly template mode (run without ui_template API) + env-native config (mount-free image)
    
    Goal A — `templates.mode: live | readonly` (HORIZON_TEMPLATES_MODE):
    - `readonly` renders every dashboard / overview / alert / 3D / translation from
      the local disk bundle, loaded into the same in-memory row shape live mode
      reads from OAP, so every render consumer resolves it unchanged. The
      ui_template store is never called (no seed, no readiness wait); OAP's query API
      is still used + boot-checked (config-only offline).
    - The config surface is read-only: admin pages still open + show the bundled
      config, but write controls are gone (the BFF rejects config-template writes at
      the route edge regardless — UI bypass still fails). Per-page + cluster-status
      surfaces show the mode; the global banner suppresses the ui_template-store
      strip in readonly (the query-unreachable strip still fires).
    - `live` (default) is unchanged: seed-to-OAP + read-from-OAP.
    
    Goal B — env-native config:
    - Every field in horizon.example.yaml is now a `${HORIZON_…:default}` token, so
      the config file is the complete, self-documenting env-var reference. Scalars
      take a value; lists / optional blocks (users, ldap, oap.auth, rbac.roles,
      performance, …) take a JSON-string env var; a `:null` token falls through to
      the schema default via a new `stripNullish` loader pass. Precedence env > file
      > default.
    - The image bakes the tokenized config AS /app/horizon.yaml, so `docker run`
      with env vars alone works — no mount, no repackage. A bind-mount still
      overrides it.
    
    Docs: container-image full env table + env-only / readonly run recipes.
    Tests: example parses to defaults (parity); env-merge (scalar / JSON / null /
    malformed); readonly status. type-check / lint / license / 263 unit tests / i18n
    green. Validated live (demo OAP): readonly bundled render + write-409 + query
    live; live-mode regression; mount-free env-only boot + login.
    
    * fix(config): review pass 1 — readonly translations + env-native robustness
    
    - P1: readonly mode rendered every non-English locale in English. Translation
      overlays were sourced from `deps.bundledOverlays`, which only the (skipped-in-
      readonly) boot seed supplies; the render callers omit it. The readonly branch
      now sources overlays from the canonical `iterateBundledOverlays()` disk
      iterator. Validated live: zh-CN readonly bundle carries the bundled overlays
      (8551 CJK chars).
    - Scalar string env values are now injected into a quoted YAML position
      (`"${HORIZON_X:default}"`), so a value with YAML metacharacters can't break
      parsing; JSON list/object tokens + numbers/bools stay unquoted for typing.
    - `templates.mode` is fixed at boot (a hot-reload flip can't run the boot seed),
      warning if the file later changes it.
    - `setTemplateReadOnly` also clears the in-flight sync probe (no cross-mode
      backfill); the parity test resolves tokens against the same env the schema's
      inline defaults read; the admin `TemplateSyncStatus` UI type gains `mode`;
      config-bundle cache bumped v2→v3 so a stale cache can't show the wrong mode.
    
    type-check / lint / license / 263 unit tests green; readonly + env-native re-validated live.
    
    * test(bff): readonly-mode sync — renders from disk, includes translation overlays, no OAP call
    
    * fix(config): review pass 2 — readonly UI gating, friendly config error, tests
    
    - Translations page is now read-only in readonly mode like its siblings: the
      widget editor never opens (openPanel early-returns) and pushToOap guards on
      readOnly. Previously the operator could translate→stage→push and was only
      stopped by the server 409 at the end.
    - Invalid config (e.g. a bool env var set to no/off/0, a non-numeric port, or
      malformed JSON env) now fails boot with a field-path-annotated fatal message
      instead of a raw ZodError dump (the crash itself is correct — fail loud).
    - Tests: the readonly write-deny route hook (isTemplateWriteRoute matches the
      config-template writes, not runtime-rule / local-state; deny → 409 in
      readonly, no-op in live); quoted string scalars survive YAML-metachar values;
      the example-parity test interpolates only the env vars the schema reads inline
      (a stray HORIZON_* no longer reads as drift).
    
    type-check / lint / license / 155 BFF + 116 UI unit tests green.
    
    * feat(cluster): reachability-based admin preflight + ui_template unified as a feature
    
    Health on the Cluster Status admin pane is now the live probe, not config-
    presence. Each admin feature declares the relative REST path it actually calls
    on OAP; the BFF fires a safe GET at it and reports whether it responds:
    
      admin-server           /debugging/config/dump
      receiver-runtime-rule  /runtime/rule/list
      dsl-debugging          /dsl-debugging/status
      inspect                /inspect/metrics
      ui-management          /ui-management/templates
    
    `reachable` drives the green/red + the per-page warning gates. The config-dump
    prefix check (`enabled`) is demoted to an informational "selector detected"
    footnote — it only tells you the official upstream release advertises that
    selector, so a renamed / forked / on-but-broken module that 404s now reads as
    unreachable instead of a misleading green (validated live: inspect on the demo
    OAP advertises its selector but only /inspect/metrics responds — the catalog
    path 404s).
    
    ui_template joins the same table as a feature, mode-aware: in readonly it is
    never probed (`reachable: null` → "readonly · bundled"). Each row shows how long
    ago it was last checked (anchored to the BFF's generatedAt, so it reflects real
    probe + cache age), and a force re-check bypasses the cache. The 5 probes are
    single-flighted for 30s on the BFF so the UI's 60s poll across N sessions
    doesn't fan out on OAP.
    
    Validated live (demo OAP): live = all five reachable; readonly = ui_template
    null + others probed; admin-port down = all unreachable, no path probes.
    type-check / lint / license / 161 BFF + 116 UI tests / builds / 8-locale i18n green.
    
    * refactor(cluster): fold the Env var column into the Gates description
    
    Drop the standalone Env var column; the selector now reads as an 'Enable on
    OAP: SW_X=default' line under each feature's Gates description. Four columns
    (Feature / State / Probe path / Gates) read cleaner now that reachability — not
    the selector — is the verdict.
    
    * fix(cluster): badge no longer claims 'all reachable' when a feature is bundled
    
    reachable===null (ui_template in readonly: not probed, serving bundled
    templates) was slipping past the reachable===false filter, so the summary read
    'all reachable' while a row showed 'readonly · bundled'. Count the null/bundled
    features separately — the badge now reads '4 reachable · 1 bundled'.
    
    * fix(cluster): admin badge reads 'N/M reachable' in yellow when not all live
    
    '4 reachable · 1 bundled' wasn't a proper summary. The badge now shows a plain
    fraction — 'all reachable' (green) only when every feature probes live, else
    '{n}/{total} reachable' (yellow). Covers both a 404'd path and a bundled /
    not-probed feature (ui_template in readonly); the per-row chip says which.
    
    * fix(readonly): close alert-page write gap, yellow read-only banner, stronger env parity
    
    Three review findings + a UX fix:
    
    - HIGH: the alert page-setup (/api/alarms/config) was still writable in readonly.
      The readonly backstop only covered /api/admin/templates* and
      /api/admin/overview-templates*; /api/alarms/config writes the
      horizon.alert.page-setup template (file-backed) and slipped through. It's now
      in the config-surface write set — a direct POST returns 409 in readonly — and
      GET serves the bundled alert page-setup (like every other template) instead of
      the local store. Validated live: POST 409, GET serves the bundle.
    
    - The read-only SyncStatusBanner was muted gray ("white") and easy to miss next
      to the green per-row sync chips. It's now warning-yellow so it's unmistakable
      that the whole config surface is bundle-served and uneditable. (The per-row
      "synced" chip is correct as-is: in readonly the bundle IS the presented remote,
      so bundled == remote and the diff legitimately reads synced.)
    
    - The env parity guard only checked top-level sections + four hard-coded tokens.
      It now recursively walks every schema-default field and asserts each is covered
      by a ${HORIZON_…} token in horizon.example.yaml (a scalar token, or a JSON-env
      token for a whole subtree). It immediately caught a real gap — oap.mqe shipped
      untokenized — now fixed (HORIZON_OAP_MQE). A future nested field without env
      coverage will now fail the test.
    
    type-check / lint / license / 162 BFF + 116 UI tests / builds green.
    
    * fix(infra-3d): remove the silent disk-bundle fallback from the live render path
    
    The 3D map was the lone surface that silently served the disk bundle when its
    remote couldn't be resolved — in live mode an unreachable ui_template store (or
    a missing / invalid remote row) returned the bundled config instead of blocking.
    Every other surface (bundle.ts) renders ONLY from remote rows and treats an
    unsynced / disabled / unreachable template as simply absent.
    
    resolveEffectiveConfig now does the same: render only from the remote row — a
    real OAP row in live mode, the synthetic bundled row in readonly — and return
    null otherwise. The route 503s on null, so the map blocks with its connectivity
    state (like layer/overview/alert) instead of masking an outage with a stale
    bundle. The bundle still reaches OAP via boot-seed and is served in readonly
    through the fake-remote row; it is never a live runtime fallback.
    
    Validated live: readonly 200 (bundle via fake-remote), live+reachable 200
    (remote), live+ui_template-unreachable 503 (blocks). 162 BFF + 116 UI tests green.
    
    * refactor(config): one committed env-driven horizon.yaml (drop the example/copy split)
    
    Collapse `horizon.example.yaml` + the gitignored local copy into a single
    committed `horizon.yaml` — the same fully tokenized file the image ships and the
    default `pnpm start` reads. Every field is a `${HORIZON_…:default}` token, so all
    config is supplied via environment variables; nothing is edited in the file.
    
    - `git mv horizon.example.yaml horizon.yaml`; un-ignore it in .gitignore +
      .dockerignore (now a tracked build input, not a local secret-bearing file).
    - Dockerfile bakes `dist/horizon.yaml` directly as `/app/horizon.yaml` — no more
      separate `/app/horizon.example.yaml` reference copy, no rename-on-copy.
    - package.mjs copies the committed `horizon.yaml` into dist/; release.sh + the
      parity tests (schema/loader) read `horizon.yaml`.
    - Docs: README, setup/overview, container-image, rbac, local-backend, ports no
      longer reference an example file; local-backend clarifies the committed file
      holds only `${HORIZON_…}` tokens (real hashes via HORIZON_AUTH_LOCAL_USERS).
    - local-boot skill: boots the repo `horizon.yaml` with OAP target + dev users
      (`dev-users.json`) / LDAP (`dev-ldap.json`) injected via HORIZON_* env vars;
      the three per-scenario yaml configs are removed. Documents the single-line-JSON
      constraint for env-injected lists/objects.
    
    Validated live: env-native boot (root horizon.yaml + env vars only) against the
    demo OAP — auth configured, login admin/admin → 200, OAP admin URL injected.
    type-check / lint / license / 162 BFF + 116 UI tests green.
---
 .claude/skills/local-boot/SKILL.md                 | 354 +++++++++------------
 .claude/skills/local-boot/dev-ldap.json            |   1 +
 .claude/skills/local-boot/dev-users.json           |   1 +
 .claude/skills/local-boot/horizon.demo.yaml        | 119 -------
 .claude/skills/local-boot/horizon.ldap.yaml        | 125 --------
 .claude/skills/local-boot/horizon.local.yaml       | 122 -------
 .dockerignore                                      |  14 +-
 .gitignore                                         |   4 +-
 CHANGELOG.md                                       |   6 +
 Dockerfile                                         |   6 +-
 README.md                                          |   2 +-
 apps/bff/src/config/loader.test.ts                 |  67 +++-
 apps/bff/src/config/loader.ts                      |  23 +-
 apps/bff/src/config/schema.test.ts                 | 108 +++++--
 apps/bff/src/config/schema.ts                      |  17 +
 apps/bff/src/http/config/alarms.ts                 |   7 +-
 apps/bff/src/http/config/bundle.ts                 |   5 +
 apps/bff/src/http/config/infra-3d.ts               |  51 ++-
 apps/bff/src/http/query/preflight.ts               |  14 +-
 apps/bff/src/logic/preflight/preflight.test.ts     | 145 +++++++++
 apps/bff/src/logic/preflight/preflight.ts          | 159 +++++++--
 apps/bff/src/logic/templates/sync.test.ts          |  67 ++++
 apps/bff/src/logic/templates/sync.ts               |  85 ++++-
 apps/bff/src/rbac/route-policy.test.ts             |  64 ++++
 apps/bff/src/rbac/route-policy.ts                  |  31 ++
 apps/bff/src/server.ts                             |  45 ++-
 apps/ui/src/api/scopes/configs.ts                  |   3 +
 apps/ui/src/api/scopes/menu.ts                     |   4 +-
 apps/ui/src/api/scopes/template-sync.ts            |   2 +
 apps/ui/src/controls/configBundle.ts               |  14 +-
 .../features/admin/_shared/SyncStatusBanner.vue    |  10 +
 .../src/features/admin/_shared/useTemplateSync.ts  |  20 +-
 .../admin/translations/TranslationsView.vue        |   6 +-
 .../features/operate/cluster/ClusterStatusView.vue | 111 +++++--
 apps/ui/src/i18n/locales/de.json                   |  18 +-
 apps/ui/src/i18n/locales/en.json                   |  18 +-
 apps/ui/src/i18n/locales/es.json                   |  18 +-
 apps/ui/src/i18n/locales/fr.json                   |  18 +-
 apps/ui/src/i18n/locales/ja.json                   |  18 +-
 apps/ui/src/i18n/locales/ko.json                   |  18 +-
 apps/ui/src/i18n/locales/pt.json                   |  18 +-
 apps/ui/src/i18n/locales/zh-CN.json                |  18 +-
 apps/ui/src/shell/AdminFeatureWarning.vue          |  12 +-
 apps/ui/src/shell/useAdminFeatures.ts              |  40 +--
 docs/access-control/local-backend.md               |   4 +-
 docs/compatibility/ports.md                        |   2 +-
 docs/setup/container-image.md                      |  52 ++-
 docs/setup/overview.md                             |   5 +-
 docs/setup/rbac.md                                 |   2 +-
 horizon.example.yaml                               | 286 -----------------
 horizon.yaml                                       | 141 ++++++++
 packages/api-client/src/preflight.ts               |  49 ++-
 scripts/package.mjs                                |   8 +-
 scripts/release.sh                                 |   2 +-
 54 files changed, 1512 insertions(+), 1047 deletions(-)

diff --git a/.claude/skills/local-boot/SKILL.md b/.claude/skills/local-boot/SKILL.md
index e623e65..a7993e7 100644
--- a/.claude/skills/local-boot/SKILL.md
+++ b/.claude/skills/local-boot/SKILL.md
@@ -1,81 +1,71 @@
 ---
 name: local-boot
-description: Boot the Horizon UI dev env (BFF + UI) against a local OAP or the public Apache demo OAP, using the static configs bundled with this skill. Handles the apps/bff cwd / HORIZON_CONFIG gotcha and the demo OAP password (kept out of git via ${OAP_PASSWORD}).
+description: Boot the Horizon UI dev env (BFF + UI) against a local OAP or the public Apache demo OAP. Uses the repo's committed, env-driven horizon.yaml — the same config the image ships — and injects the OAP target + dev users purely via HORIZON_* environment variables. Handles the apps/bff cwd / HORIZON_CONFIG gotcha and the demo OAP password (kept out of git via the cached oap-password.local).
 user-invocable: true
 ---
 
 # Boot the Horizon UI local dev env
 
-Two bundled static configs live next to this file:
+There is **one config file**: the repo's committed `horizon.yaml` at the
+repo root. Every field in it is a `${HORIZON_…:default}` token, so dev boots
+use the SAME file the Docker image ships and override only what they need via
+**environment variables** — there are no per-scenario config files anymore.
 
-- `horizon.local.yaml` — no-auth OAP. Defaults to `127.0.0.1:12800`, but the OAP URLs are env-overridable (see "Custom OAP target" below) so the same file boots against any no-auth OAP (remote dev cluster, deliberately-unreachable port for the landing-block preview, etc.).
-- `horizon.demo.yaml` — public Apache demo OAP, OAP password read from `${OAP_PASSWORD}`.
+Two committed helpers live next to this file (throwaway dev values, safe to
+commit):
 
-Both define the same throwaway Horizon login users (password == username):
-`viewer`, `maintainer`, `operator`, `admin`.
+- `dev-users.json` — the four local login users (`viewer` / `maintainer` /
+  `operator` / `admin`, **password == username**), as a **single-line** JSON
+  array for `HORIZON_AUTH_LOCAL_USERS`.
+- `dev-ldap.json` — the test-OpenLDAP config for `HORIZON_AUTH_LDAP` (single line).
 
-The stack: **BFF** (Fastify) on `:8081`, **UI** (Vite) on `:9091` proxying `/api` → `:8081`. Open **`http://127.0.0.1:9091`** (use the IPv4 literal, not `localhost` — see the proxy/IPv4 section).
+The stack: **BFF** (Fastify) on `:8081`, **UI** (Vite) on `:9091` proxying
+`/api` → `:8081`. Open **`http://127.0.0.1:9091`** (use the IPv4 literal, not
+`localhost` — see the proxy/IPv4 section). Both ports are overridable — see
+"Custom ports".
 
-Both ports are overridable — see "Custom ports" below. The defaults are what the examples use throughout this doc.
+> **JSON env values must be SINGLE-LINE.** `HORIZON_AUTH_LOCAL_USERS`,
+> `HORIZON_OAP_AUTH`, `HORIZON_AUTH_LDAP`, etc. are spliced into the YAML before
+> parsing; a multi-line JSON value breaks the parse (`YAMLParseError: Flow
+> sequence … must be sufficiently indented`). The `dev-*.json` files are already
+> single-line — keep them that way.
 
 ## Environment variables (the dev contract)
 
-Local dev runs as **two processes / two ports**: the BFF (Fastify, owns
-`/api`) and Vite (serves the UI, proxies `/api` → BFF). They coordinate
-through env vars below. The BFF reads them via the YAML loader's
-`${VAR:default}` interpolation; Vite reads `BFF_PORT` + `UI_DEV_PORT`
-directly in `apps/ui/vite.config.ts`. Set them on **both** processes
-when overriding (or the proxy points at the wrong BFF).
+Local dev runs as **two processes / two ports**: the BFF (Fastify, owns `/api`)
+and Vite (serves the UI, proxies `/api` → BFF). The BFF reads `HORIZON_*` via the
+config loader's `${VAR:default}` interpolation; Vite reads `BFF_PORT` +
+`UI_DEV_PORT` directly in `apps/ui/vite.config.ts`.
 
-| Variable          | Default                          | Used by  | Purpose |
+| Variable                    | Default                    | Used by | Purpose |
 |---|---|---|---|
-| `HORIZON_CONFIG`  | _(none — required)_              | BFF      | **Absolute** path to the yaml config. A bare `./horizon.yaml` resolves under `apps/bff/` and silently boots with zero users — see "The one gotcha" below. |
-| `BFF_PORT`        | `8081`                           | BFF + UI | BFF listen port (yaml `server.port`) AND Vite's proxy target. Set the same value on both. Prod uses this as the single port (BFF serves the built UI). |
-| `UI_DEV_PORT`     | `9091`                           | UI       | Vite listen port. Dev-only — meaningless in prod. |
-| `OAP_QUERY_URL`   | `http://localhost:12800`         | BFF      | OAP GraphQL endpoint (applies to `horizon.local.yaml`). |
-| `OAP_ADMIN_URL`   | `http://localhost:12800`         | BFF      | OAP admin REST endpoint. Often differs from GraphQL on real deployments (e.g. demo splits on `:17128`) — if BFF logs `UITemplate 404`, override this. |
-| `OAP_ZIPKIN_URL`  | `http://localhost:9412/zipkin`   | BFF      | Zipkin query endpoint (Zipkin trace layer). |
-| `OAP_TIMEOUT_MS`  | `15000`                          | BFF      | OAP request timeout. Lower it (`5000`) when previewing the "OAP unreachable" landing block so errors surface fast. |
-| `OAP_PASSWORD`    | _(none)_                         | BFF      | Demo OAP basic-auth password (`horizon.demo.yaml` only). Cached at `oap-password.local` (git-ignored). |
-| `LDAP_BIND_PW`    | `admin` _(test value)_           | BFF      | LDAP service-bind password (`horizon.ldap.yaml` only). Set a real value before pointing at a real directory. |
-
-Minimal local dev (defaults, no overrides):
-
-```bash
-REPO="$(git rev-parse --show-toplevel)"
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &           # → :8081
-( cd "$REPO/apps/ui" && node_modules/.bin/vite --host 127.0.0.1 & ) # → :9091
-```
-
-Custom ports for a parallel env (e.g. coexist with booster-ui on 8080):
-
-```bash
-BFF_PORT=10081 UI_DEV_PORT=10091 \
-  HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-( cd "$REPO/apps/ui" && BFF_PORT=10081 UI_DEV_PORT=10091 \
-    node_modules/.bin/vite --host 127.0.0.1 & )
-```
-
-Remote OAP (no auth) via env override:
-
-```bash
-OAP_QUERY_URL=http://oap.dev.example:12800 \
-OAP_ADMIN_URL=http://oap.dev.example:17128 \
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-```
-
-The longer "Custom ports" and "Custom OAP target" sections below cover
-the prod single-port model, the GraphQL/admin port split, and the
-unreachable-OAP preview.
+| `HORIZON_CONFIG`            | _(none — required)_        | BFF     | **Absolute** path to the config. Always `"$REPO/horizon.yaml"`. A bare `./horizon.yaml` resolves under `apps/bff/` — see "The one gotcha". |
+| `HORIZON_SERVER_PORT`       | `8081`                     | BFF     | BFF listen port (`server.port`). For a custom port set this AND `BFF_PORT` to the same value. |
+| `BFF_PORT`                  | `8081`                     | UI      | Vite's `/api` proxy target. Must match `HORIZON_SERVER_PORT`. |
+| `UI_DEV_PORT`               | `9091`                     | UI      | Vite listen port. Dev-only. |
+| `HORIZON_OAP_QUERY_URL`     | `http://127.0.0.1:12800`   | BFF     | OAP GraphQL endpoint. |
+| `HORIZON_OAP_ADMIN_URL`     | `http://127.0.0.1:17128`   | BFF     | OAP admin REST endpoint. Often a different port from GraphQL (the demo splits on `:17128`) — if the BFF logs `UITemplate 404`, this is wrong. |
+| `HORIZON_OAP_ZIPKIN_URL`    | `http://127.0.0.1:9412/zipkin` | BFF | Zipkin query endpoint (Zipkin trace layer). |
+| `HORIZON_OAP_TIMEOUT_MS`    | `15000`                    | BFF     | OAP request timeout. Lower it (`4000`) when previewing the "OAP unreachable" landing block so errors surface fast. |
+| `HORIZON_OAP_AUTH`          | _(none)_                   | BFF     | OAP basic-auth as JSON, e.g. `{"username":"admin","password":"…"}`. The demo needs it (password from `oap-password.local`). |
+| `HORIZON_AUTH_LOCAL_USERS`  | `[]`                       | BFF     | Local login users (JSON array, single-line). Use `$(cat dev-users.json)`. |
+| `HORIZON_AUTH_BACKEND`      | `local`                    | BFF     | `local` or `ldap`. |
+| `HORIZON_AUTH_LDAP`         | _(none)_                   | BFF     | LDAP config (JSON, single-line) when backend=ldap. Use `$(cat dev-ldap.json)`. |
+| `HORIZON_TEMPLATES_MODE`    | `live`                     | BFF     | `live` (seed + read ui_template) or `readonly` (render the bundle, config read-only). |
+
+RBAC is left to the built-in role defaults (the `horizon.yaml` token
+`roles: ${HORIZON_RBAC_ROLES:null}` falls through to them), so no roles env var
+is needed for dev.
 
 ## The one gotcha that bites every time
 
-The BFF dev script is `tsx watch src/server.ts` and pnpm runs it with **cwd = `apps/bff`**. The config path is `process.env.HORIZON_CONFIG ?? './horizon.yaml'`, resolved relative to cwd — so a bare `./horizon.yaml` points at the non-existent `apps/bff/horizon.yaml`, and the loader silently falls back to **defaults with zero users** (every login then fails with "invalid credentials", and the boot log warns `auth.local.users is empty`).
+The BFF dev script is `tsx watch src/server.ts` and pnpm runs it with **cwd =
+`apps/bff`**. The config path defaults to `./horizon.yaml`, resolved relative to
+cwd — so a bare `./horizon.yaml` points at the non-existent `apps/bff/horizon.yaml`
+(NOT the repo-root one), and the loader silently falls back to schema defaults
+with **zero users** (every login then fails "invalid credentials").
 
-**Always pass `HORIZON_CONFIG` as an ABSOLUTE path.** Use `"$REPO/.claude/skills/local-boot/<file>"`.
+**Always pass `HORIZON_CONFIG` as an ABSOLUTE path:** `"$REPO/horizon.yaml"`.
 
 ## Proxy + IPv4 (the second gotcha)
 
@@ -91,119 +81,23 @@ env | grep -iE '^(http_proxy|https_proxy|all_proxy)=' && echo "local proxy detec
 
 The browser uses its OWN proxy settings (not the shell's), so the developer must also let `127.0.0.1` / `localhost` go direct (ClashX "bypass localhost" / system proxy no-proxy list). The env-level bypass below only fixes CLI tools and Vite's own fetches.
 
-## Custom ports (two parallel envs, prod single-port)
-
-The defaults are BFF `:8081` and UI `:9091`. To run a second Horizon
-side-by-side (e.g. comparing two OAPs, or coexisting with the legacy
-booster-ui on 8080) override with two env vars **at boot time**:
-
-- `BFF_PORT` — the Fastify listen port. Read by the BFF yaml as
-  `port: ${BFF_PORT:8081}` (interpolated by the loader before parse) AND
-  by Vite's dev server when building the `/api` proxy target. **Set the
-  same value on both processes** or the proxy points at the wrong BFF.
-- `UI_DEV_PORT` — the Vite listen port. Dev-only, read by
-  `apps/ui/vite.config.ts`.
-
-```bash
-# parallel env on 10081/10091 (e.g. against a second OAP):
-BFF_PORT=10081 UI_DEV_PORT=10091 \
-  HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.<file>.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-( cd "$REPO/apps/ui" && BFF_PORT=10081 UI_DEV_PORT=10091 \
-    env -u http_proxy -u https_proxy -u all_proxy ... \
-        node_modules/.bin/vite --host 127.0.0.1 & )
-```
-
-The recipes below all use `${BFF_PORT:-8081}` / `${UI_DEV_PORT:-9091}`
-shell expansions, so they pick up an override that's already exported
-(or just use the defaults if not).
-
-**Prod is single-port.** The BFF serves the built UI as static files via
-`@fastify/static`, so `UI_DEV_PORT` is meaningless outside Vite. In prod
-only `server.port` (i.e. `BFF_PORT`) matters.
-
-## Custom OAP target (point horizon.local.yaml at any no-auth OAP)
-
-`horizon.local.yaml` is the canonical no-auth config — there are no
-separate `horizon.remote.yaml` / `horizon.unreachable.yaml` files
-anymore. The four OAP fields all accept env-var overrides via the
-loader's `${VAR:default}` syntax, so the same config boots against:
-
-- **A LOCAL OAP** (default). No env vars needed.
-- **A REMOTE OAP** — `OAP_QUERY_URL` + `OAP_ADMIN_URL` + `OAP_ZIPKIN_URL`.
-- **A deliberately-unreachable port** — to preview the "OAP query host
-  unreachable" landing block. Pair with a short `OAP_TIMEOUT_MS` so
-  errors surface fast.
-
-Heads-up: many real deployments split the GraphQL surface (12800) and
-the admin REST surface (often 17128 — same split as the public demo).
-If the BFF startup log warns `UITemplate 404` on `/ui-management/...`,
-the admin URL is wrong — override `OAP_ADMIN_URL` separately.
-
-```bash
-# Remote OAP (GraphQL 12800, admin REST split on 17128):
-OAP_QUERY_URL=http://oap.dev.example:12800 \
-OAP_ADMIN_URL=http://oap.dev.example:17128 \
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-
-# Unreachable-OAP landing-block preview:
-OAP_QUERY_URL=http://127.0.0.1:12801 \
-OAP_ADMIN_URL=http://127.0.0.1:12801 \
-OAP_TIMEOUT_MS=5000 \
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-```
-
 ## The stale-process trap (why a config switch "didn't take")
 
-`tsx watch` keeps the old BFF alive, so a freshly launched BFF with a NEW config silently dies on `EADDRINUSE: 127.0.0.1:${BFF_PORT:-8081}` while the OLD process keeps serving the OLD OAP. Symptom: you switch local↔demo, everything looks fine, but the UI still shows the previous OAP's data.
+`tsx watch` keeps the old BFF alive, so a freshly launched BFF silently dies on `EADDRINUSE: 127.0.0.1:8081` while the OLD process keeps serving the OLD env. Symptom: you switch demo↔local, everything looks fine, but the UI still shows the previous OAP's data.
 
-Killing matters in two ways:
-- `pkill -f "tsx watch src/server.ts"` may miss the actual listener — also `pkill -f "tsx/dist/cli.mjs watch"`, and **verify the port is actually free with `lsof` before relaunching** (loop until free; the watcher can respawn a child).
-- After boot, **confirm which OAP the LIVE process is using** — don't trust that your new process won the port. The authoritative check:
+- `pkill -f "tsx watch src/server.ts"` may miss the actual listener — also `pkill -f "tsx/dist/cli.mjs watch"`, and **verify the port is free with `lsof` before relaunching** (loop until free; the watcher respawns a child).
+- After boot, **confirm which OAP the LIVE process uses** — don't trust that your new process won the port:
   ```bash
-  curl -s --noproxy '*' -b /tmp/sw.cookies "http://127.0.0.1:${BFF_PORT:-8081}/api/oap/config" | grep -oE '"adminUrl":"[^"]*"'
-  # local => http://localhost:12800 ; demo => https://demo.skywalking.apache.org:17128
+  curl -s --noproxy '*' -b /tmp/sw.cookies "http://127.0.0.1:8081/api/oap/config" | grep -oE '"adminUrl":"[^"]*"'
+  # local => http://127.0.0.1:17128 ; demo => https://demo.skywalking.apache.org:17128
   ```
-  Also grep the boot log for `EADDRINUSE` and the `configPath` line. If the adminUrl is wrong, a stale BFF is still bound — kill it, confirm the port is free, relaunch.
-
-## Boot against the local OAP
-
-```bash
-REPO="$(git rev-parse --show-toplevel)"
-# 1. Kill prior dev servers AND confirm the BFF port is actually free —
-#    a stale BFF holding it makes the new one die on EADDRINUSE while
-#    the old config keeps serving (see "stale-process trap"). For a
-#    parallel env on custom ports, export BFF_PORT / UI_DEV_PORT first.
-pkill -f "tsx watch src/server.ts" 2>/dev/null
-pkill -f "tsx/dist/cli.mjs watch" 2>/dev/null; pkill -f vite 2>/dev/null
-until ! lsof -nP -iTCP:"${BFF_PORT:-8081}" -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
-
-# 2. BFF — absolute config path is mandatory (see gotcha above). The
-#    yaml resolves ${BFF_PORT:8081} at load time, so just exporting
-#    BFF_PORT before this command is enough:
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.local.yaml" \
-  pnpm --filter @skywalking-horizon-ui/bff run dev &
-
-# 3. UI — IPv4 host + loopback proxy bypass (run the binary directly so
-#    --host actually applies). vite.config.ts reads BFF_PORT and
-#    UI_DEV_PORT from this env:
-( cd "$REPO/apps/ui" && \
-  env -u http_proxy -u https_proxy -u all_proxy -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
-      no_proxy="localhost,127.0.0.1,::1" NO_PROXY="localhost,127.0.0.1,::1" \
-      node_modules/.bin/vite --host 127.0.0.1 & )
-```
-
-Then open **`http://127.0.0.1:${UI_DEV_PORT:-9091}`** and log in as `admin` / `admin`.
 
 ## Boot against the public demo OAP
 
-The demo OAP needs basic-auth (network username `admin`). The password is
-NOT committed — it lives in `oap-password.local` next to this file, which
-is git-ignored via the repo-wide `*.local` rule. Source it before booting;
-if the file is missing, ask the developer and recreate it (one line, the
-password only):
+The demo OAP needs basic-auth (network username `admin`). The password is NOT
+committed — it lives in `oap-password.local` next to this file (git-ignored via
+the repo-wide `*.local` rule). Source it; if missing, ask the developer and
+recreate it (one line, the password only).
 
 ```bash
 REPO="$(git rev-parse --show-toplevel)"
@@ -215,83 +109,129 @@ else
   printf '%s\n' "$OAP_PASSWORD" > "$SECRET" && chmod 600 "$SECRET"  # cache for next boot
 fi
 
+# Kill prior dev servers + confirm the port is free (see stale-process trap).
 pkill -f "tsx watch src/server.ts" 2>/dev/null
 pkill -f "tsx/dist/cli.mjs watch" 2>/dev/null; pkill -f vite 2>/dev/null
-until ! lsof -nP -iTCP:"${BFF_PORT:-8081}" -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.demo.yaml" \
+until ! lsof -nP -iTCP:8081 -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
+
+# BFF — repo horizon.yaml + everything via env. JSON values are single-line.
+SK="$REPO/.claude/skills/local-boot"
+HORIZON_CONFIG="$REPO/horizon.yaml" \
+HORIZON_OAP_QUERY_URL=https://demo.skywalking.apache.org:12800 \
+HORIZON_OAP_ADMIN_URL=https://demo.skywalking.apache.org:17128 \
+HORIZON_OAP_ZIPKIN_URL=https://demo.skywalking.apache.org:9412/zipkin \
+HORIZON_OAP_AUTH="{\"username\":\"admin\",\"password\":\"$OAP_PASSWORD\"}" \
+HORIZON_AUTH_LOCAL_USERS="$(cat "$SK/dev-users.json")" \
   pnpm --filter @skywalking-horizon-ui/bff run dev &
+
+# UI — IPv4 host + loopback proxy bypass (run the binary directly so --host applies).
 ( cd "$REPO/apps/ui" && \
   env -u http_proxy -u https_proxy -u all_proxy -u HTTP_PROXY -u HTTPS_PROXY -u ALL_PROXY \
       no_proxy="localhost,127.0.0.1,::1" NO_PROXY="localhost,127.0.0.1,::1" \
       node_modules/.bin/vite --host 127.0.0.1 & )
 ```
 
-The cached `oap-password.local` is git-ignored, so it is safe to keep on
-disk between boots. If it is absent and `OAP_PASSWORD` is unset, ask the
-developer rather than guessing. The OAP network username is fixed as
-`admin` in `horizon.demo.yaml`.
+Then open **`http://127.0.0.1:9091`** and log in as `admin` / `admin`. To boot in
+read-only template mode, add `HORIZON_TEMPLATES_MODE=readonly` to the BFF line.
+
+## Boot against a local / remote no-auth OAP
+
+Same recipe, different OAP env vars (no `HORIZON_OAP_AUTH` for a no-auth OAP):
+
+```bash
+REPO="$(git rev-parse --show-toplevel)"; SK="$REPO/.claude/skills/local-boot"
+pkill -f "tsx watch src/server.ts" 2>/dev/null; pkill -f "tsx/dist/cli.mjs watch" 2>/dev/null; pkill -f vite 2>/dev/null
+until ! lsof -nP -iTCP:8081 -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
+
+# LOCAL OAP (defaults already point at 127.0.0.1, so only users are needed):
+HORIZON_CONFIG="$REPO/horizon.yaml" \
+HORIZON_AUTH_LOCAL_USERS="$(cat "$SK/dev-users.json")" \
+  pnpm --filter @skywalking-horizon-ui/bff run dev &
+
+# REMOTE no-auth OAP (GraphQL 12800, admin split on 17128):
+HORIZON_CONFIG="$REPO/horizon.yaml" \
+HORIZON_OAP_QUERY_URL=http://oap.dev.example:12800 \
+HORIZON_OAP_ADMIN_URL=http://oap.dev.example:17128 \
+HORIZON_AUTH_LOCAL_USERS="$(cat "$SK/dev-users.json")" \
+  pnpm --filter @skywalking-horizon-ui/bff run dev &
+
+# UNREACHABLE-OAP landing-block preview (short timeout so errors surface fast):
+HORIZON_CONFIG="$REPO/horizon.yaml" \
+HORIZON_OAP_QUERY_URL=http://127.0.0.1:12801 HORIZON_OAP_ADMIN_URL=http://127.0.0.1:12801 \
+HORIZON_OAP_TIMEOUT_MS=4000 \
+HORIZON_AUTH_LOCAL_USERS="$(cat "$SK/dev-users.json")" \
+  pnpm --filter @skywalking-horizon-ui/bff run dev &
+```
+
+## Custom ports (two parallel envs)
+
+Defaults are BFF `:8081`, UI `:9091`. To run a second Horizon side-by-side, set
+the BFF port via **`HORIZON_SERVER_PORT`** (the config's `server.port` token) AND
+**`BFF_PORT`** (Vite's proxy target) to the same value, plus `UI_DEV_PORT`:
+
+```bash
+HORIZON_SERVER_PORT=10081 BFF_PORT=10081 UI_DEV_PORT=10091 \
+  HORIZON_CONFIG="$REPO/horizon.yaml" \
+  HORIZON_AUTH_LOCAL_USERS="$(cat "$SK/dev-users.json")" \
+  pnpm --filter @skywalking-horizon-ui/bff run dev &
+( cd "$REPO/apps/ui" && BFF_PORT=10081 UI_DEV_PORT=10091 \
+    env -u http_proxy -u https_proxy -u all_proxy \
+        node_modules/.bin/vite --host 127.0.0.1 & )
+```
+
+**Prod is single-port.** The BFF serves the built UI as static files, so
+`UI_DEV_PORT` is meaningless outside Vite; only `HORIZON_SERVER_PORT` matters.
 
 ## Boot against an LDAP directory (test)
 
-`horizon.ldap.yaml` points the BFF at a throwaway OpenLDAP seeded from
-`ldap-seed.ldif`. Stand the directory up, seed it, then boot:
+Stand up a throwaway OpenLDAP, seed it from `ldap-seed.ldif`, then boot with
+`HORIZON_AUTH_BACKEND=ldap` and the LDAP config from `dev-ldap.json`. Test logins
+mirror the local set (password == username): `admin` → admin, `operator` →
+operator, `maintainer` → maintainer, `viewer` → viewer (`*` fallback). The bind
+account is `cn=admin,dc=horizon,dc=test` / `admin`.
 
 ```bash
-REPO="$(git rev-parse --show-toplevel)"
+REPO="$(git rev-parse --show-toplevel)"; SK="$REPO/.claude/skills/local-boot"
 docker rm -f horizon-ldap 2>/dev/null
 docker run -d --name horizon-ldap -p 389:389 -p 636:636 \
   --env LDAP_ORGANISATION="Horizon Test" --env LDAP_DOMAIN="horizon.test" \
   --env LDAP_ADMIN_PASSWORD="admin" osixia/openldap:1.5.0
-# wait for slapd, then seed:
 until docker exec horizon-ldap ldapwhoami -x -H ldap://localhost \
   -D "cn=admin,dc=horizon,dc=test" -w admin >/dev/null 2>&1; do sleep 1; done
-docker cp "$REPO/.claude/skills/local-boot/ldap-seed.ldif" horizon-ldap:/tmp/seed.ldif
+docker cp "$SK/ldap-seed.ldif" horizon-ldap:/tmp/seed.ldif
 docker exec horizon-ldap ldapadd -x -H ldap://localhost \
   -D "cn=admin,dc=horizon,dc=test" -w admin -f /tmp/seed.ldif
 
 pkill -f "tsx watch src/server.ts" 2>/dev/null; pkill -f "tsx/dist/cli.mjs watch" 2>/dev/null
-until ! lsof -nP -iTCP:"${BFF_PORT:-8081}" -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
-HORIZON_CONFIG="$REPO/.claude/skills/local-boot/horizon.ldap.yaml" \
+until ! lsof -nP -iTCP:8081 -sTCP:LISTEN >/dev/null 2>&1; do sleep 1; done
+HORIZON_CONFIG="$REPO/horizon.yaml" \
+HORIZON_AUTH_BACKEND=ldap \
+HORIZON_AUTH_LDAP="$(cat "$SK/dev-ldap.json")" \
   pnpm --filter @skywalking-horizon-ui/bff run dev &
 ```
 
-Test accounts (seeded by `ldap-seed.ldif`). Login users are named after
-their role and **password == username**, mirroring `horizon.local.yaml`:
-
-| Login | Group | Role |
-|---|---|---|
-| `admin` | cn=horizon-admin | admin |
-| `operator` | cn=sre | operator |
-| `maintainer` | cn=platform | maintainer |
-| `viewer` | (none) | viewer (`*` fallback) |
-
-Directory bind account: `cn=admin,dc=horizon,dc=test` / `admin` (override via `LDAP_BIND_PW`).
-
-```bash
-# verify a login resolves the expected role:
-curl -s --noproxy '*' -H 'Content-Type: application/json' -X POST \
-  "http://127.0.0.1:${BFF_PORT:-8081}/api/auth/login" -d '{"username":"admin","password":"admin"}'
-```
-
-Note: group resolution runs on the **service bind**, not the user's
-credentials (regular users usually can't read the group subtree).
+`dev-ldap.json` reads the bind password as the test value `admin`; for a real
+directory, edit it (or build the JSON with your own bind password) and never
+commit a real one. Group resolution runs on the **service bind**, not the user's
+credentials.
 
 ## Verify the BFF is healthy (no browser)
 
 ```bash
 # --noproxy so a local proxy (ClashX etc.) doesn't 502 the loopback call.
-until curl -s --noproxy '*' -m2 -o /dev/null "http://127.0.0.1:${BFF_PORT:-8081}/api/auth/health"; do sleep 1; done
+until curl -s --noproxy '*' -m2 -o /dev/null "http://127.0.0.1:8081/api/auth/health"; do sleep 1; done
 curl -s --noproxy '*' -c /tmp/sw.cookies -H 'Content-Type: application/json' -X POST \
-  "http://127.0.0.1:${BFF_PORT:-8081}/api/auth/login" -d '{"username":"admin","password":"admin"}'
-# Expect 200 with {username, roles, verbs, landingRoute}. A 401
-# "invalid credentials" almost always means the wrong config loaded —
-# re-check the absolute HORIZON_CONFIG path and that no stale BFF holds the BFF port.
+  "http://127.0.0.1:8081/api/auth/login" -d '{"username":"admin","password":"admin"}'
+# Expect 200 with {username, roles, verbs, landingRoute}. A 401 "invalid
+# credentials" usually means HORIZON_AUTH_LOCAL_USERS wasn't passed (or the
+# wrong HORIZON_CONFIG path / a stale BFF holds the port).
 ```
 
-## Editing the configs
+## Editing the dev values
 
-These files are the source of truth for dev boot. Keep secrets out:
-local-user hashes (password == username) are fine to commit; real OAP
-passwords must stay in `${OAP_PASSWORD}` (the loader's `interpolateEnv`
-expands `${VAR}` / `${VAR:default}` in the raw YAML before parsing).
-To mint a new local-user hash: `pnpm --filter @skywalking-horizon-ui/bff cli:hash`.
+`horizon.yaml` (repo root) is the committed, env-driven config — leave it as-is
+and override via `HORIZON_*` env vars. The dev users / LDAP config live in
+`dev-users.json` / `dev-ldap.json` here (throwaway, single-line JSON). Real OAP
+or LDAP passwords stay out of git: the demo OAP password in `oap-password.local`
+(git-ignored), real bind passwords supplied at boot. To mint a new local-user
+hash: `pnpm --filter @skywalking-horizon-ui/bff cli:hash`.
diff --git a/.claude/skills/local-boot/dev-ldap.json b/.claude/skills/local-boot/dev-ldap.json
new file mode 100644
index 0000000..f52c039
--- /dev/null
+++ b/.claude/skills/local-boot/dev-ldap.json
@@ -0,0 +1 @@
+{"url":"ldap://localhost:389","bindDn":"cn=admin,dc=horizon,dc=test","bindPassword":"admin","userBaseDn":"ou=people,dc=horizon,dc=test","userFilter":"(uid={username})","displayNameAttr":"cn","groupStrategy":"search","groupBaseDn":"ou=groups,dc=horizon,dc=test","memberAttr":"member","timeoutMs":5000,"tlsInsecure":false,"groupMappings":[{"group":"cn=horizon-admin,ou=groups,dc=horizon,dc=test","role":"admin"},{"group":"cn=sre,ou=groups,dc=horizon,dc=test","role":"operator"},{"group":"cn=pla [...]
diff --git a/.claude/skills/local-boot/dev-users.json b/.claude/skills/local-boot/dev-users.json
new file mode 100644
index 0000000..a0f7972
--- /dev/null
+++ b/.claude/skills/local-boot/dev-users.json
@@ -0,0 +1 @@
+[{"username":"viewer","passwordHash":"$argon2id$v=19$m=65536,t=3,p=4$Gp175hqr+EF2iZ7v1fndvw$w6w9hDI59/UA+CRARChDoGRlR1TkVt6kqzApa021K+0","roles":["viewer"]},{"username":"maintainer","passwordHash":"$argon2id$v=19$m=65536,t=3,p=4$w7ULwB3/jzH9FxVoHJ238A$y+qGoX6IPeOoGywLQCpfpAN5VJXcaevoWeJQhaybvQU","roles":["maintainer"]},{"username":"operator","passwordHash":"$argon2id$v=19$m=65536,t=3,p=4$nzoI4RqiobprtzX/mJqe5Q$FY2Hi7mKep0DPHoaE++r/KD++WLUwTgRUFLde87j2Wg","roles":["operator"]},{"username" [...]
diff --git a/.claude/skills/local-boot/horizon.demo.yaml b/.claude/skills/local-boot/horizon.demo.yaml
deleted file mode 100644
index f68f222..0000000
--- a/.claude/skills/local-boot/horizon.demo.yaml
+++ /dev/null
@@ -1,119 +0,0 @@
-# Static demo-boot config for the Horizon UI BFF — points at the public
-# Apache demo OAP (demo.skywalking.apache.org). The OAP network basic-auth
-# password is NOT committed: it is read from ${OAP_PASSWORD} at boot.
-# Ask the developer for it before booting and export it, e.g.
-#   read -rs OAP_PASSWORD && export OAP_PASSWORD
-# Boot via the `local-boot` skill (see SKILL.md), which passes this file
-# through HORIZON_CONFIG as an ABSOLUTE path. Horizon login users below
-# are throwaway dev credentials (password == username).
-
-server:
-  host: 127.0.0.1
-  port: ${BFF_PORT:8081}
-
-oap:
-  queryUrl: https://demo.skywalking.apache.org:12800
-  adminUrl: https://demo.skywalking.apache.org:17128
-  zipkinUrl: https://demo.skywalking.apache.org:9412/zipkin
-  timeoutMs: 15000
-  auth:
-    username: admin
-    # Supplied via the environment so the demo password stays out of git.
-    # interpolateEnv() in apps/bff/src/config/loader.ts expands ${OAP_PASSWORD}.
-    password: "${OAP_PASSWORD}"
-
-auth:
-  backend: local
-  local:
-    users:
-      - username: viewer
-        # password: viewer
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$Gp175hqr+EF2iZ7v1fndvw$w6w9hDI59/UA+CRARChDoGRlR1TkVt6kqzApa021K+0"
-        roles: [viewer]
-      - username: maintainer
-        # password: maintainer
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$w7ULwB3/jzH9FxVoHJ238A$y+qGoX6IPeOoGywLQCpfpAN5VJXcaevoWeJQhaybvQU"
-        roles: [maintainer]
-      - username: operator
-        # password: operator
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$nzoI4RqiobprtzX/mJqe5Q$FY2Hi7mKep0DPHoaE++r/KD++WLUwTgRUFLde87j2Wg"
-        roles: [operator]
-      - username: admin
-        # password: admin
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$joV9AVlyLS3pqq4mLrYokQ$pJLkTKrz9/LzEH6YaFljdz9k8dyBiryjwSB26Diiz9U"
-        roles: [admin]
-
-rbac:
-  enabled: true
-  roles:
-    viewer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-    maintainer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-    operator:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "source-map:write"
-      - "topology:read"
-      - "profile:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-      - "overview:read"
-      - "overview:write"
-      - "setup:read"
-      - "setup:write"
-      - "dashboard:read"
-      - "dashboard:write"
-      - "alarm-setup:read"
-      - "alarm-setup:write"
-      - "alarm-rule:read"
-      - "alarm-rule:write"
-      - "rule:read"
-      - "rule:write"
-      - "rule:write:structural"
-      - "rule:delete"
-      - "rule:debug"
-      - "live-debug:read"
-      - "live-debug:write"
-      - "profile:enable"
-    admin:
-      - "*"
-  landingByRole:
-    viewer: /
-    maintainer: /operate/cluster
-    operator: /
-    admin: /
-
-session:
-  ttlMinutes: 60
-  cookieName: horizon_sid
-  cookieSecure: false
-
-audit:    { file: ./horizon-audit.jsonl }
-setup:    { file: ./horizon-setup.json }
-alarms:   { file: ./horizon-alarms.json }
-debugLog: { enabled: false, file: ./horizon-wire.jsonl, maxBodyChars: 8192, redactAuthHeaders: true }
-sourceMaps: { enabled: true, maxFileBytes: 67108864, maxTotalBytes: 536870912, maxFileCount: 128, bootMountDir: "" }
diff --git a/.claude/skills/local-boot/horizon.ldap.yaml b/.claude/skills/local-boot/horizon.ldap.yaml
deleted file mode 100644
index e324a59..0000000
--- a/.claude/skills/local-boot/horizon.ldap.yaml
+++ /dev/null
@@ -1,125 +0,0 @@
-# LDAP-backend boot config for the Horizon UI BFF. Authenticates against
-# an external directory; Horizon stores no passwords. This file targets
-# the throwaway test OpenLDAP described in SKILL.md ("Test the LDAP
-# backend"): base dc=horizon,dc=test, users under ou=people, groups
-# (groupOfNames) under ou=groups, seeded from ldap-seed.ldif.
-#
-# Test directory accounts (all seeded by ldap-seed.ldif). Login users
-# are named after their role and password == username, mirroring
-# horizon.local.yaml:
-#   directory admin (bindDn):  cn=admin,dc=horizon,dc=test  /  admin
-#   login users (password == username):
-#     admin       -> cn=horizon-admin   -> role admin
-#     operator    -> cn=sre             -> role operator
-#     maintainer  -> cn=platform        -> role maintainer
-#     viewer      -> (no group)         -> role viewer (the "*" fallback)
-#
-# The directory bind password is read from ${LDAP_BIND_PW} (defaults to
-# the test value `admin`); for a real directory, export LDAP_BIND_PW and
-# never commit it.
-#
-# OAP still points at a local OAP so the rest of the app works. Boot via
-# the local-boot skill with an ABSOLUTE HORIZON_CONFIG path.
-
-server:
-  host: 127.0.0.1
-  port: ${BFF_PORT:8081}
-
-oap:
-  queryUrl: http://localhost:12800
-  adminUrl: http://localhost:12800
-  zipkinUrl: http://localhost:9412/zipkin
-  timeoutMs: 15000
-
-auth:
-  backend: ldap
-  ldap:
-    url: ldap://localhost:389
-    bindDn: "cn=admin,dc=horizon,dc=test"
-    bindPassword: "${LDAP_BIND_PW:admin}"
-    userBaseDn: "ou=people,dc=horizon,dc=test"
-    userFilter: "(uid={username})"
-    displayNameAttr: cn
-    # This test directory uses groupOfNames groups without a memberOf
-    # overlay, so resolve membership by searching ou=groups for the
-    # user's DN. Switch to `memberOf` against directories that populate it.
-    groupStrategy: search
-    groupBaseDn: "ou=groups,dc=horizon,dc=test"
-    memberAttr: member
-    timeoutMs: 5000
-    tlsInsecure: false
-    groupMappings:
-      - { group: "cn=horizon-admin,ou=groups,dc=horizon,dc=test", role: admin }
-      - { group: "cn=sre,ou=groups,dc=horizon,dc=test", role: operator }
-      - { group: "cn=platform,ou=groups,dc=horizon,dc=test", role: maintainer }
-      - { group: "*", role: viewer }
-
-rbac:
-  enabled: true
-  roles:
-    viewer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-    maintainer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-    operator:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "topology:read"
-      - "profile:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-      - "overview:read"
-      - "overview:write"
-      - "setup:read"
-      - "setup:write"
-      - "dashboard:read"
-      - "dashboard:write"
-      - "alarm-setup:read"
-      - "alarm-setup:write"
-      - "alarm-rule:read"
-      - "alarm-rule:write"
-      - "rule:read"
-      - "rule:write"
-      - "rule:write:structural"
-      - "rule:delete"
-      - "rule:debug"
-      - "live-debug:read"
-      - "live-debug:write"
-      - "profile:enable"
-    admin:
-      - "*"
-  landingByRole:
-    viewer: /
-    maintainer: /operate/cluster
-    operator: /
-    admin: /
-
-session:
-  ttlMinutes: 60
-  cookieName: horizon_sid
-  cookieSecure: false
-
-audit:    { file: ./horizon-audit.jsonl }
-setup:    { file: ./horizon-setup.json }
-alarms:   { file: ./horizon-alarms.json }
-debugLog: { enabled: false, file: ./horizon-wire.jsonl, maxBodyChars: 8192, redactAuthHeaders: true }
diff --git a/.claude/skills/local-boot/horizon.local.yaml b/.claude/skills/local-boot/horizon.local.yaml
deleted file mode 100644
index c21c19b..0000000
--- a/.claude/skills/local-boot/horizon.local.yaml
+++ /dev/null
@@ -1,122 +0,0 @@
-# Static local-boot config for the Horizon UI BFF. Defaults to a LOCAL
-# OAP on 127.0.0.1 with NO network auth, but the four OAP fields below
-# accept env-var overrides so the same file boots against a remote OAP
-# (any URL), a deliberately-unreachable port (for the "OAP unreachable"
-# landing-block preview), or any other no-auth OAP. For demo-OAP access
-# use horizon.demo.yaml instead, which keeps the password out of git
-# via ${OAP_PASSWORD}.
-#
-# Boot via the `local-boot` skill (see SKILL.md) which passes this
-# file through HORIZON_CONFIG as an ABSOLUTE path. The local-user
-# password hashes below are throwaway dev credentials (password ==
-# username) — safe to commit; do NOT add real secrets here.
-
-server:
-  host: 127.0.0.1
-  port: ${BFF_PORT:8081}
-
-oap:
-  # On the default LOCAL OAP, GraphQL and the admin REST surface share
-  # the same port (12800). On the public demo and some k8s deployments
-  # they split (12800 / 17128) — override OAP_ADMIN_URL accordingly.
-  # Zipkin (9412) may not be exposed locally.
-  queryUrl: ${OAP_QUERY_URL:http://localhost:12800}
-  adminUrl: ${OAP_ADMIN_URL:http://localhost:12800}
-  zipkinUrl: ${OAP_ZIPKIN_URL:http://localhost:9412/zipkin}
-  timeoutMs: ${OAP_TIMEOUT_MS:15000}
-
-auth:
-  backend: local
-  local:
-    # One account per role for manual menu-RBAC checks. Password == username.
-    users:
-      - username: viewer
-        # password: viewer
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$Gp175hqr+EF2iZ7v1fndvw$w6w9hDI59/UA+CRARChDoGRlR1TkVt6kqzApa021K+0"
-        roles: [viewer]
-      - username: maintainer
-        # password: maintainer
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$w7ULwB3/jzH9FxVoHJ238A$y+qGoX6IPeOoGywLQCpfpAN5VJXcaevoWeJQhaybvQU"
-        roles: [maintainer]
-      - username: operator
-        # password: operator
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$nzoI4RqiobprtzX/mJqe5Q$FY2Hi7mKep0DPHoaE++r/KD++WLUwTgRUFLde87j2Wg"
-        roles: [operator]
-      - username: admin
-        # password: admin
-        passwordHash: "$argon2id$v=19$m=65536,t=3,p=4$joV9AVlyLS3pqq4mLrYokQ$pJLkTKrz9/LzEH6YaFljdz9k8dyBiryjwSB26Diiz9U"
-        roles: [admin]
-
-rbac:
-  enabled: true
-  roles:
-    viewer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-    maintainer:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "topology:read"
-      - "profile:read"
-      - "overview:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-    operator:
-      - "metrics:read"
-      - "alarms:read"
-      - "traces:read"
-      - "logs:read"
-      - "browser-errors:read"
-      - "source-map:write"
-      - "topology:read"
-      - "profile:read"
-      - "cluster:read"
-      - "inspect:read"
-      - "ttl:read"
-      - "config:read"
-      - "overview:read"
-      - "overview:write"
-      - "setup:read"
-      - "setup:write"
-      - "dashboard:read"
-      - "dashboard:write"
-      - "alarm-setup:read"
-      - "alarm-setup:write"
-      - "alarm-rule:read"
-      - "alarm-rule:write"
-      - "rule:read"
-      - "rule:write"
-      - "rule:write:structural"
-      - "rule:delete"
-      - "rule:debug"
-      - "live-debug:read"
-      - "live-debug:write"
-      - "profile:enable"
-    admin:
-      - "*"
-  landingByRole:
-    viewer: /
-    maintainer: /operate/cluster
-    operator: /
-    admin: /
-
-session:
-  ttlMinutes: 60
-  cookieName: horizon_sid
-  cookieSecure: false
-
-audit:    { file: ./horizon-audit.jsonl }
-setup:    { file: ./horizon-setup.json }
-alarms:   { file: ./horizon-alarms.json }
-debugLog: { enabled: false, file: ./horizon-wire.jsonl, maxBodyChars: 8192, redactAuthHeaders: true }
diff --git a/.dockerignore b/.dockerignore
index d3ea2be..4690a97 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -16,8 +16,8 @@
 # Denylist style: the image builds FROM SOURCE (see Dockerfile), so the
 # context is the source tree. Exclude only what must NOT enter the build —
 # host-built artifacts (arch-specific node_modules + dist), VCS, CI config,
-# local secrets, and scratch dirs. Everything else (source, lockfile,
-# horizon.example.yaml) is needed by `pnpm install` + `pnpm package`.
+# local secrets, and scratch dirs. Everything else (source, lockfile, the
+# committed horizon.yaml) is needed by `pnpm install` + `pnpm package`.
 
 **/node_modules
 **/dist
@@ -29,6 +29,10 @@ scripts/.release-work
 scripts/.finalize-work
 .claude
 
-# Local runtime config may carry secrets — never ship it. The committed
-# horizon.example.yaml stays (package.mjs reads it into dist/).
-horizon.yaml
+# horizon.yaml is the committed, env-driven config (package.mjs reads it into
+# dist/, the Dockerfile bakes it as /app/horizon.yaml) — keep it in the context.
+# Runtime state files carry local data; never ship them.
+horizon-audit.jsonl
+horizon-wire.jsonl
+horizon-setup.json
+horizon-alarms.json
diff --git a/.gitignore b/.gitignore
index e06b6d8..c4ae196 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,11 +40,11 @@ coverage
 # OS
 Thumbs.db
 
-# BFF runtime files
-horizon.yaml
+# BFF runtime files (horizon.yaml itself is committed — the env-driven config)
 horizon-audit.jsonl
 horizon-wire.jsonl
 horizon-setup.json
+horizon-alarms.json
 
 # Release
 scripts/.release-work
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b952ade..916148a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,12 @@ The version line is shared by every package in the monorepo (apps + shared packa
 
 ## 1.1.0
 
+### Deployment & configuration
+
+- **Run on the bundled templates, read-only — no OAP ui_template API needed.** A new `templates.mode` setting (`HORIZON_TEMPLATES_MODE`) adds a `readonly` mode: Horizon renders every dashboard / overview / alert-page / 3D-map / translation from the **local bundle** and never calls OAP's ui_template admin API. The whole config surface goes **read-only** — the admin pages still open and show the bundled config, but editing and publishing are disabled (and the BFF rejects a write even if it [...]
+- **The container image runs with environment variables only — no mounted config file.** There is now **one committed, env-driven `horizon.yaml`** (the former `horizon.example.yaml` / local-copy split is gone): every field is a `${HORIZON_…:default}` token, and the image bakes that same file. So `docker run -e HORIZON_OAP_QUERY_URL=… -e HORIZON_AUTH_LOCAL_USERS='[…]' …` is enough — no `-v` mount, no repackaging. Previously `oap.*`, `auth.*`, users, LDAP, RBAC, and performance tuning were [...]
+- **Cluster Status now reports admin-feature reachability, not just config-presence.** The admin-host pane fires a safe GET at the real REST path each feature calls on OAP — dashboard templates → `/ui-management/templates`, DSL management → `/runtime/rule/list`, live debugger → `/dsl-debugging/status`, Inspect → `/inspect/metrics` — and colors each row by whether that path actually responds. A feature whose module is loaded but whose endpoint 404s (a renamed or forked module, a selector  [...]
+
 ### General Service — PHP runtime (PHM)
 
 - **Six instance dashboard line widgets for PHP Health Metrics** — process CPU utilization, memory used/peak, virtual memory, thread count, and open file descriptors (`meter_instance_php_*`). Each line widget uses `visibleWhen` so widgets render only when the PHP agent reports PHM data (Linux `/proc` sampling of the parent PHP process via `getppid()`).
diff --git a/Dockerfile b/Dockerfile
index fe998dc..f5c0318 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -58,7 +58,11 @@ COPY --from=build /src/dist/server.js              ./server.js
 COPY --from=build /src/dist/package.json           ./package.json
 COPY --from=build /src/dist/node_modules           ./node_modules
 COPY --from=build /src/dist/static                 ./static
-COPY --from=build /src/dist/horizon.example.yaml   ./horizon.example.yaml
+# The fully tokenized horizon.yaml is the active config — every field is a
+# `${HORIZON_…:default}` token, so the image runs with NO mounted file:
+# `docker run -e HORIZON_OAP_QUERY_URL=… -e HORIZON_AUTH_LOCAL_USERS='[…]' …`
+# is enough. A bind-mount at /app/horizon.yaml still overrides it.
+COPY --from=build /src/dist/horizon.yaml           ./horizon.yaml
 
 COPY --from=build --chown=horizon:horizon /src/dist/bundled_templates  ./bundled_templates
 
diff --git a/README.md b/README.md
index b25be5d..f24e853 100644
--- a/README.md
+++ b/README.md
@@ -127,7 +127,7 @@ See [`docs/setup/container-image.md`](docs/setup/container-image.md) for image t
 
 ## Configuration
 
-Horizon UI is configured by a single `horizon.yaml` (hot-reloaded, with `${VAR}` environment-variable interpolation) — see `horizon.example.yaml`. Key sections:
+Horizon UI is configured by a single `horizon.yaml` (hot-reloaded, with `${VAR}` environment-variable interpolation) — see `horizon.yaml`. Key sections:
 
 - `server` — host / port.
 - `oap` — `queryUrl`, `adminUrl`, `zipkinUrl`, `timeoutMs`, and optional outbound basic-auth.
diff --git a/apps/bff/src/config/loader.test.ts b/apps/bff/src/config/loader.test.ts
index b27245e..bae60ca 100644
--- a/apps/bff/src/config/loader.test.ts
+++ b/apps/bff/src/config/loader.test.ts
@@ -15,9 +15,13 @@
  * limitations under the License.
  */
 
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import YAML from 'yaml';
 import { describe, expect, it } from 'vitest';
 import { configSchema } from './schema.js';
-import { interpolateEnv, isAuthConfigured, validateBootstrap } from './loader.js';
+import { interpolateEnv, stripNullish, isAuthConfigured, validateBootstrap } from './loader.js';
 
 describe('interpolateEnv', () => {
   it('substitutes a defined variable', () => {
@@ -45,6 +49,67 @@ describe('interpolateEnv', () => {
     expect(interpolateEnv('${lowercase}', { lowercase: 'ok' })).toBe('ok');
     expect(interpolateEnv('${lowercase:fallback}', {})).toBe('fallback');
   });
+});
+
+describe('stripNullish', () => {
+  it('drops null-valued keys (a ${VAR:null} that resolved to null = use default)', () => {
+    expect(stripNullish({ a: 1, b: null, c: { d: null, e: 2 } })).toEqual({ a: 1, c: { e: 2 } });
+  });
+  it('keeps empty arrays + empty strings (those are real values, not "unset")', () => {
+    expect(stripNullish({ a: [], b: '', c: 0, d: false })).toEqual({ a: [], b: '', c: 0, d: false });
+  });
+});
+
+// The env-native contract: the tokenized horizon.yaml, interpolated +
+// stripped + parsed, must accept env overrides for every kind of field.
+describe('env-native config (horizon.yaml + env)', () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const raw = readFileSync(resolve(here, '../../../../horizon.yaml'), 'utf8');
+  const load = (env: NodeJS.ProcessEnv): ReturnType<typeof configSchema.parse> =>
+    configSchema.parse(stripNullish(YAML.parse(interpolateEnv(raw, env)) ?? {}));
+
+  it('scalar env overrides (oap url, templates mode, boolean)', () => {
+    const cfg = load({
+      HORIZON_OAP_QUERY_URL: 'http://oap.prod:12800',
+      HORIZON_TEMPLATES_MODE: 'readonly',
+      HORIZON_RBAC_ENABLED: 'false',
+    });
+    expect(cfg.oap.queryUrl).toBe('http://oap.prod:12800');
+    expect(cfg.templates.mode).toBe('readonly');
+    expect(cfg.rbac.enabled).toBe(false);
+  });
+
+  it('JSON-array env override seeds local users (incl. an argon2 $ hash)', () => {
+    const hash = '$argon2id$v=19$m=65536,t=3,p=4$abc$def';
+    const cfg = load({
+      HORIZON_AUTH_LOCAL_USERS: JSON.stringify([{ username: 'admin', passwordHash: hash, roles: ['admin'] }]),
+    });
+    expect(cfg.auth.local.users).toEqual([{ username: 'admin', passwordHash: hash, roles: ['admin'] }]);
+  });
+
+  it('JSON-object env override sets the optional oap.auth block', () => {
+    const cfg = load({ HORIZON_OAP_AUTH: '{"username":"sw","password":"sw"}' });
+    expect(cfg.oap.auth).toEqual({ username: 'sw', password: 'sw' });
+  });
+
+  it('unset optional/structured blocks fall through to the schema default', () => {
+    const cfg = load({});
+    expect(cfg.oap.auth).toBeUndefined();
+    expect(cfg.performance.bulk.dashboard.bulkSize).toBe(6);
+    expect(cfg.layers.excluded.map((e) => e.key)).toEqual(['FAAS', 'VIRTUAL_GATEWAY']);
+  });
+
+  it('malformed JSON env throws at parse (fail loud, not silently default)', () => {
+    expect(() => load({ HORIZON_AUTH_LOCAL_USERS: '[{bad json' })).toThrow();
+  });
+
+  it('quoted string scalars survive a value with YAML metacharacters (: and #)', () => {
+    // The string tokens are quoted (`"${X:default}"`), so a metachar value
+    // lands safely inside a YAML string instead of breaking the parse.
+    const cfg = load({ HORIZON_SESSION_COOKIE_NAME: 'weird: name #x', HORIZON_OAP_QUERY_URL: 'http://oap:12800' });
+    expect(cfg.session.cookieName).toBe('weird: name #x');
+    expect(cfg.oap.queryUrl).toBe('http://oap:12800');
+  });
 
   it('survives newlines and YAML formatting', () => {
     const raw = `auth:\n  ldap:\n    bindPassword: "\${HORIZON_LDAP_BIND_PW:dev-only}"\n`;
diff --git a/apps/bff/src/config/loader.ts b/apps/bff/src/config/loader.ts
index bd1a3ad..20d9765 100644
--- a/apps/bff/src/config/loader.ts
+++ b/apps/bff/src/config/loader.ts
@@ -50,6 +50,27 @@ export function interpolateEnv(
   });
 }
 
+/**
+ * Recursively drop keys whose value is `null`. A `${VAR:null}` token (used for
+ * optional blocks + structured defaults like `oap.auth`, `auth.ldap`,
+ * `rbac.roles`, `performance`) resolves to `null` when the env var is unset,
+ * meaning "not provided — use the schema default", NOT an explicit null. No
+ * config field legitimately accepts null, so stripping them lets the strict
+ * schema fall through to its default instead of rejecting `key: null`.
+ */
+export function stripNullish(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stripNullish);
+  if (value && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      if (v === null) continue;
+      out[k] = stripNullish(v);
+    }
+    return out;
+  }
+  return value;
+}
+
 /** Raised when the loaded config is structurally valid but operationally
  *  unusable in a way that cannot be deferred to runtime (reserved — no
  *  current callers; the auth-unconfigured cases boot and surface the
@@ -138,7 +159,7 @@ function parseFile(absPath: string): HorizonConfig {
   }
   const interpolated = interpolateEnv(raw);
   const parsed = YAML.parse(interpolated) ?? {};
-  return configSchema.parse(parsed);
+  return configSchema.parse(stripNullish(parsed));
 }
 
 export function loadConfig(configPath: string): ConfigSource {
diff --git a/apps/bff/src/config/schema.test.ts b/apps/bff/src/config/schema.test.ts
index f742523..ae16cd0 100644
--- a/apps/bff/src/config/schema.test.ts
+++ b/apps/bff/src/config/schema.test.ts
@@ -21,7 +21,7 @@ import { dirname, resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 import YAML from 'yaml';
 import { configSchema } from './schema.js';
-import { interpolateEnv } from './loader.js';
+import { interpolateEnv, stripNullish } from './loader.js';
 
 describe('configSchema defaults', () => {
   it('parses an empty object — every non-optional field has a default', () => {
@@ -29,42 +29,84 @@ describe('configSchema defaults', () => {
   });
 });
 
-// Guard against horizon.example.yaml drifting from the schema defaults. The
-// example is "reference, not override" — every value it shows is meant to
-// equal what the BFF runs with when the block is omitted. If a default
-// changes (or someone edits the example to a non-default), this fails so the
-// two are reconciled before merge.
-describe('horizon.example.yaml matches schema defaults', () => {
+// horizon.yaml is the SHIPPED default + the env-var reference: every
+// field is a `${HORIZON_…:default}` token. Two contracts guarded here:
+//   1. With NO env set, the tokens' defaults parse to EXACTLY the schema
+//      defaults — so the file is a faithful "this is what you get" reference.
+//   2. Every top-level config section appears in the example, so a new
+//      section can't be added to the schema without an env-overridable token.
+describe('horizon.yaml — tokenized default + parity', () => {
   const here = dirname(fileURLToPath(import.meta.url));
-  const examplePath = resolve(here, '../../../../horizon.example.yaml');
-  const example = YAML.parse(interpolateEnv(readFileSync(examplePath, 'utf8'))) ?? {};
-  const defaults = configSchema.parse({}) as Record<string, unknown>;
+  const examplePath = resolve(here, '../../../../horizon.yaml');
+  const raw = readFileSync(examplePath, 'utf8');
 
-  // YAML omits a value as null; the schema models the same absence as the
-  // empty string (interpolated `${VAR:}`). Treat the two as equal so an
-  // unset path doesn't read as drift.
-  const norm = (v: unknown): unknown => (v === null || v === undefined ? '' : v);
+  it('parses to exactly the schema defaults (token defaults match the schema)', () => {
+    // configSchema.parse({}) reads a FIXED set of HORIZON_* env vars inline for
+    // its defaults (server host/port, the *_FILE paths, sourcemaps dir,
+    // templates mode). Interpolate the example with ONLY those — so the two
+    // sides agree on the env-derived defaults, while every OTHER stray HORIZON_*
+    // in a dev/CI env is ignored (it would otherwise read as drift, since the
+    // schema default for e.g. oap.queryUrl is a literal, not env-read).
+    const SCHEMA_ENV = [
+      'HORIZON_SERVER_HOST', 'HORIZON_SERVER_PORT', 'HORIZON_AUDIT_FILE', 'HORIZON_SETUP_FILE',
+      'HORIZON_ALARMS_FILE', 'HORIZON_WIRE_LOG_FILE', 'HORIZON_SOURCEMAPS_DIR', 'HORIZON_TEMPLATES_MODE',
+    ];
+    const env: NodeJS.ProcessEnv = {};
+    for (const k of SCHEMA_ENV) if (process.env[k] !== undefined) env[k] = process.env[k];
+    const parsed = stripNullish(YAML.parse(interpolateEnv(raw, env)) ?? {});
+    expect(configSchema.parse(parsed)).toEqual(configSchema.parse({}));
+  });
 
-  // Walk only what the example actually declares; the example is allowed to
-  // omit fields (those fall back to defaults at runtime). Every scalar /
-  // array it DOES carry must match the parsed default at the same path.
-  const walk = (exVal: unknown, defVal: unknown, path: string): void => {
-    if (Array.isArray(exVal) || (exVal !== null && typeof exVal === 'object')) {
-      if (Array.isArray(exVal)) {
-        expect(defVal, `${path} should be an array in defaults`).toEqual(exVal);
-        return;
-      }
-      const exObj = exVal as Record<string, unknown>;
-      const defObj = (defVal ?? {}) as Record<string, unknown>;
-      for (const key of Object.keys(exObj)) {
-        walk(exObj[key], defObj[key], path ? `${path}.${key}` : key);
-      }
-      return;
+  it('every top-level config section has a token in the example', () => {
+    const sections = Object.keys(configSchema.parse({}) as Record<string, unknown>);
+    const exampleKeys = Object.keys((YAML.parse(raw) ?? {}) as Record<string, unknown>);
+    for (const s of sections) {
+      // `infra3d` is the deprecated/ignored passthrough — never tokenized.
+      if (s === 'infra3d') continue;
+      expect(exampleKeys, `config section "${s}" is missing from horizon.yaml`).toContain(s);
     }
-    expect(norm(exVal), `${path} drifted from schema default`).toEqual(norm(defVal));
-  };
+  });
 
-  it('every value present in the example equals the schema default', () => {
-    walk(example, defaults, '');
+  it('key fields are env tokens (not literals), so they are overridable', () => {
+    expect(raw).toContain('${HORIZON_OAP_QUERY_URL');
+    expect(raw).toContain('${HORIZON_AUTH_LOCAL_USERS');
+    expect(raw).toContain('${HORIZON_TEMPLATES_MODE');
+    expect(raw).toContain('${HORIZON_OAP_ADMIN_URL');
+  });
+
+  // The real contract: EVERY schema-default field is env-overridable. Walk the
+  // fully-defaulted config and assert each node is covered in the example by a
+  // `${HORIZON_…}` token — either a scalar token at that path, or a JSON-env
+  // token standing in for a whole subtree (performance, rbac.roles, …). Catches
+  // a new nested field shipped without env coverage, which the top-level-section
+  // check above would miss.
+  it('every schema-default field is env-tokenized in the example (recursive)', () => {
+    const defaults = configSchema.parse({}) as Record<string, unknown>;
+    const example = (YAML.parse(raw) ?? {}) as Record<string, unknown>;
+    const TOKEN = /\$\{HORIZON_[A-Z0-9_]+(:[\s\S]*)?\}/;
+    const uncovered: string[] = [];
+    const walk = (schemaNode: unknown, exampleNode: unknown, path: string): void => {
+      // A token string covers this node (scalar token, or a JSON-env token
+      // collapsing a whole subtree to one var).
+      if (typeof exampleNode === 'string' && TOKEN.test(exampleNode)) return;
+      if (schemaNode !== null && typeof schemaNode === 'object' && !Array.isArray(schemaNode)) {
+        if (exampleNode === null || typeof exampleNode !== 'object' || Array.isArray(exampleNode)) {
+          uncovered.push(`${path} (section absent from example)`);
+          return;
+        }
+        for (const key of Object.keys(schemaNode)) {
+          if (path === '' && key === 'infra3d') continue; // deprecated passthrough, never tokenized
+          walk(
+            (schemaNode as Record<string, unknown>)[key],
+            (exampleNode as Record<string, unknown>)[key],
+            path ? `${path}.${key}` : key,
+          );
+        }
+        return;
+      }
+      uncovered.push(`${path} (leaf not tokenized)`);
+    };
+    walk(defaults, example, '');
+    expect(uncovered, `fields lacking an env token in horizon.yaml:\n  ${uncovered.join('\n  ')}`).toEqual([]);
   });
 });
diff --git a/apps/bff/src/config/schema.ts b/apps/bff/src/config/schema.ts
index e00907b..e9e21a5 100644
--- a/apps/bff/src/config/schema.ts
+++ b/apps/bff/src/config/schema.ts
@@ -461,10 +461,26 @@ const performanceSchema = z
   .strict()
   .default({});
 
+// Template source mode. `live` (default) seeds bundled templates into OAP's
+// ui_template store at boot and reads/writes them via the ui_template API.
+// `readonly` renders templates from the local disk bundle only — the
+// ui_template API is never called and the config surface is read-only; OAP's
+// query API (metrics/traces/logs) is still used + boot-checked. Env-overridable
+// (`HORIZON_TEMPLATES_MODE`) so a file-less container can pick the mode.
+const templatesModeDefault: 'live' | 'readonly' =
+  process.env.HORIZON_TEMPLATES_MODE === 'readonly' ? 'readonly' : 'live';
+const templatesSchema = z
+  .object({
+    mode: z.enum(['live', 'readonly']).default(templatesModeDefault),
+  })
+  .strict()
+  .default({ mode: templatesModeDefault });
+
 export const configSchema = z
   .object({
     server: serverSchema.default({}),
     layers: layersSchema,
+    templates: templatesSchema,
     oap: oapSchema.default({}),
     auth: authSchema,
     rbac: rbacSchema,
@@ -485,6 +501,7 @@ export const configSchema = z
   .strict();
 
 export type HorizonConfig = z.infer<typeof configSchema>;
+export type TemplatesConfig = z.infer<typeof templatesSchema>;
 export type SourceMapsConfig = z.infer<typeof sourceMapsSchema>;
 export type LdapConfig = z.infer<typeof ldapSchema>;
 export type LocalUser = z.infer<typeof localUserSchema>;
diff --git a/apps/bff/src/http/config/alarms.ts b/apps/bff/src/http/config/alarms.ts
index 1b1e5c3..467259d 100644
--- a/apps/bff/src/http/config/alarms.ts
+++ b/apps/bff/src/http/config/alarms.ts
@@ -30,6 +30,8 @@ import type { ConfigSource } from '../../config/loader.js';
 import type { SessionStore } from '../../user/sessions.js';
 import type { AuditLogger } from '../../audit/logger.js';
 import { requireAuth } from '../../user/middleware.js';
+import { isTemplateReadOnly } from '../../logic/templates/sync.js';
+import { loadBundledAlertPageSetup } from '../../logic/alarms/bundled.js';
 import type { ServiceLayerCatalog } from '../../logic/services/service-layer-catalog.js';
 import {
   ALARMS_WINDOW_OPTIONS,
@@ -77,7 +79,10 @@ export function registerAlarmsConfigRoutes(
     '/api/alarms/config',
     { preHandler: auth },
     async (_req: FastifyRequest, reply: FastifyReply) => {
-      const cfg = await deps.store.load();
+      // Readonly mode serves the alert page-setup from the bundle like every
+      // other template; the local store (a prior live session's edits) is not
+      // the source here. Writes are denied by the route-policy backstop.
+      const cfg = isTemplateReadOnly() ? loadBundledAlertPageSetup() : await deps.store.load();
       return reply.send(cfg);
     },
   );
diff --git a/apps/bff/src/http/config/bundle.ts b/apps/bff/src/http/config/bundle.ts
index eff0884..83cccc4 100644
--- a/apps/bff/src/http/config/bundle.ts
+++ b/apps/bff/src/http/config/bundle.ts
@@ -86,6 +86,10 @@ type ScopeMap = Partial<Record<'service' | 'instance' | 'endpoint', DashboardWid
  *  omitted here (they'd bloat the bundle 5x); the admin pages fetch
  *  them on demand from `/api/admin/templates/sync-status`. */
 export interface BundleSyncStatus {
+  /** `live` = templates read/written via OAP's ui_template store. `readonly` =
+   *  rendered from the local disk bundle; the store is not used and the config
+   *  surface is read-only. Drives the SPA's read-only chrome + banner. */
+  mode: 'live' | 'readonly';
   unreachable: boolean;
   lastSuccessfulSyncAt: number | null;
   generatedAt: number;
@@ -225,6 +229,7 @@ async function buildBundle(
   }
 
   const syncStatus: BundleSyncStatus = {
+    mode: sync.mode,
     unreachable: sync.unreachable,
     lastSuccessfulSyncAt: sync.lastSuccessfulSyncAt,
     generatedAt: sync.generatedAt,
diff --git a/apps/bff/src/http/config/infra-3d.ts b/apps/bff/src/http/config/infra-3d.ts
index 84ac1f4..f6c87e5 100644
--- a/apps/bff/src/http/config/infra-3d.ts
+++ b/apps/bff/src/http/config/infra-3d.ts
@@ -18,12 +18,13 @@
 /**
  * `GET /api/infra-3d/config` — the EFFECTIVE 3D Infrastructure Map config
  * the `/3d/map` view consumes. The config is a first-class template kind
- * (`horizon.infra-3d.config`), so it follows the same bundled → remote
- * policy as every other template: when OAP holds a non-disabled remote
- * row, that wins; otherwise the bundled default is served. Writes do NOT
- * happen here — the admin editor publishes through the generic template
- * sync surface (`POST /api/admin/templates/save`), which validates the
- * 3D-map content before it reaches OAP.
+ * (`horizon.infra-3d.config`) and is read ONLY from the remote row, exactly
+ * like the layer/overview surfaces — never the disk bundle as a runtime
+ * fallback. The bundle reaches OAP via boot-seed; readonly mode renders it
+ * through the synthetic bundled row. When the ui_template store is unreachable
+ * (or the row is absent / invalid) this 503s so the map blocks, rather than
+ * silently serving a stale bundle. Writes do NOT happen here — the admin editor
+ * publishes through the generic template sync surface (`POST /api/admin/templates/save`).
  */
 
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
@@ -38,7 +39,6 @@ import {
   parseEnvelope,
   INFRA3D_CONFIG_KEY,
 } from '../../logic/templates/names.js';
-import { loadBundledInfra3dConfig } from '../../logic/infra-3d/bundled.js';
 import { validateInfra3dConfig } from '../../logic/infra-3d/validate.js';
 import type { Infra3dConfig } from '../../logic/infra-3d/types.js';
 import { logger } from '../../logger.js';
@@ -60,6 +60,16 @@ export function registerInfra3dConfigRoutes(
     { preHandler: auth },
     async (_req: FastifyRequest, reply: FastifyReply) => {
       const cfg = await resolveEffectiveConfig(deps);
+      // Live + ui_template store unreachable → block, exactly like every other
+      // surface (the UI renders its connectivity-empty state). The 3D map used
+      // to be the lone exception that silently served the bundle here.
+      if (!cfg) {
+        return reply.code(503).send({
+          error: 'template_store_unreachable',
+          reason:
+            "OAP's ui_template store is unreachable; in live mode the 3D map renders only from OAP (no bundled fallback). It recovers when the store is reachable, or run templates.mode=readonly to serve the bundle.",
+        });
+      }
       // The metric fan-out budget is OPERATIONAL (per-deployment, hot-
       // reloaded), so it lives in horizon.yaml — NOT the published template.
       // Inject it server-side so the UI keeps reading `cfg.pipeline.*`; this
@@ -79,18 +89,26 @@ export function registerInfra3dConfigRoutes(
   );
 }
 
-/** Remote-wins resolution, mirroring `pickLayerContent` in the config
- *  bundle. The remote envelope is re-validated defensively — a row
- *  hand-edited on OAP into an invalid shape falls back to bundled rather
- *  than breaking the map. */
-async function resolveEffectiveConfig(deps: Infra3dConfigRouteDeps): Promise<Infra3dConfig> {
-  const bundled = loadBundledInfra3dConfig();
+/**
+ * Render ONLY from the remote row — never the disk bundle as a runtime
+ * fallback. This matches the layer/overview surfaces (bundle.ts): the bundle
+ * reaches OAP via boot-seed, then is read back as a remote row. `getSyncStatus`
+ * supplies that row — a real OAP row in live mode, the synthetic bundled row in
+ * readonly — so readonly renders the bundle through the SAME remote path.
+ *
+ * Returns null (→ the route blocks with 503) when there is no usable remote
+ * row: the store is unreachable, the row is absent / not-yet-seeded / disabled,
+ * or the remote envelope is invalid. A live ui_template outage must surface as
+ * a block like every other surface, not a silent stale bundle.
+ */
+async function resolveEffectiveConfig(deps: Infra3dConfigRouteDeps): Promise<Infra3dConfig | null> {
   try {
     const sync = await getSyncStatus({
       client: deps.uiTemplateClient(),
       bundled: () => iterateBundledTemplates(),
       logger,
     });
+    if (sync.unreachable) return null;
     const name = formatName('infra-3d', INFRA3D_CONFIG_KEY);
     const row = sync.rows.find((r) => r.name === name);
     if (row && row.status !== 'disabled' && row.effective === 'remote' && row.remote) {
@@ -98,11 +116,12 @@ async function resolveEffectiveConfig(deps: Infra3dConfigRouteDeps): Promise<Inf
       if (env) {
         const v = validateInfra3dConfig(env.content);
         if (v.ok) return v.value;
-        logger.warn({ issues: v.issues }, 'remote infra-3d config invalid; using bundled');
+        logger.warn({ issues: v.issues }, 'remote infra-3d config invalid — blocking, not falling back');
       }
     }
+    return null;
   } catch (err) {
-    logger.warn({ err }, 'infra-3d effective resolve failed; using bundled');
+    logger.warn({ err }, 'infra-3d effective resolve failed — blocking, not falling back');
+    return null;
   }
-  return bundled;
 }
diff --git a/apps/bff/src/http/query/preflight.ts b/apps/bff/src/http/query/preflight.ts
index 99a2902..530e8ce 100644
--- a/apps/bff/src/http/query/preflight.ts
+++ b/apps/bff/src/http/query/preflight.ts
@@ -20,7 +20,7 @@ import type { FetchLike } from '@skywalking-horizon-ui/api-client';
 import type { ConfigSource } from '../../config/loader.js';
 import { requireAuth } from '../../user/middleware.js';
 import type { SessionStore } from '../../user/sessions.js';
-import { runPreflight } from '../../logic/preflight/preflight.js';
+import { getPreflight } from '../../logic/preflight/preflight.js';
 
 export interface PreflightRouteDeps {
   config: ConfigSource;
@@ -28,17 +28,19 @@ export interface PreflightRouteDeps {
   fetch?: FetchLike;
 }
 
-/** `GET /api/preflight` — interrogates OAP's config-dump and returns
- *  per-module enablement. Authenticated but ungated by verb — every
- *  logged-in user can see whether OAP is correctly set up. */
+/** `GET /api/preflight` — probes each admin feature's REST path and
+ *  returns per-feature reachability (30s single-flight cache; pass
+ *  `?refresh=1` to force a fresh round). Authenticated but ungated by
+ *  verb — every logged-in user can see whether OAP is correctly set up. */
 export function registerPreflightRoutes(app: FastifyInstance, deps: PreflightRouteDeps): void {
   const auth = requireAuth(deps);
   app.get(
     '/api/preflight',
     { preHandler: auth },
-    async (_req: FastifyRequest, reply: FastifyReply) => {
+    async (req: FastifyRequest, reply: FastifyReply) => {
       const fetchImpl = deps.fetch ?? globalThis.fetch.bind(globalThis);
-      const result = await runPreflight(deps.config.current, fetchImpl);
+      const force = (req.query as { refresh?: string }).refresh === '1';
+      const result = await getPreflight(deps.config.current, fetchImpl, { force });
       return reply.send(result);
     },
   );
diff --git a/apps/bff/src/logic/preflight/preflight.test.ts b/apps/bff/src/logic/preflight/preflight.test.ts
new file mode 100644
index 0000000..53adff4
--- /dev/null
+++ b/apps/bff/src/logic/preflight/preflight.test.ts
@@ -0,0 +1,145 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { FetchLike } from '@skywalking-horizon-ui/api-client';
+import type { HorizonConfig } from '../../config/schema.js';
+import { runPreflight, getPreflight, invalidatePreflightCache } from './preflight.js';
+
+const DUMP = '/debugging/config/dump';
+// The config dump advertises every module prefix (the "selector detected"
+// footnote) — so reachability, not config-presence, is what the test drives.
+const DUMP_BODY: Record<string, string> = {
+  'admin-server.provider': 'default',
+  'receiver-runtime-rule.provider': 'default',
+  'dsl-debugging.provider': 'default',
+  'inspect.provider': 'default',
+  'ui-management.provider': 'default',
+};
+
+function res(status: number, body: unknown = {}): Response {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    text: async () => (typeof body === 'string' ? body : JSON.stringify(body)),
+    json: async () => body,
+  } as unknown as Response;
+}
+
+/** A fetch that answers the dump 200 and each probe path by a status map;
+ *  a path mapped to `'throw'` simulates a network error. Records every URL. */
+function fetchWith(statusByPath: Record<string, number | 'throw'>, calls: string[] = []): FetchLike {
+  return ((url: string) => {
+    calls.push(url);
+    if (url.endsWith(DUMP)) return Promise.resolve(res(200, DUMP_BODY));
+    for (const [path, st] of Object.entries(statusByPath)) {
+      if (url.endsWith(path)) {
+        if (st === 'throw') return Promise.reject(new Error('ECONNREFUSED'));
+        return Promise.resolve(res(st));
+      }
+    }
+    return Promise.resolve(res(404));
+  }) as unknown as FetchLike;
+}
+
+function cfg(mode: 'live' | 'readonly' = 'live'): HorizonConfig {
+  return {
+    oap: { adminUrl: 'http://oap:17128', timeoutMs: 0, queryUrl: '', zipkinUrl: '' },
+    templates: { mode },
+  } as unknown as HorizonConfig;
+}
+
+const ALL_OK = {
+  '/ui-management/templates': 200,
+  '/runtime/rule/list': 200,
+  '/dsl-debugging/status': 200,
+  '/inspect/metrics': 200,
+} as const;
+
+const byName = (r: Awaited<ReturnType<typeof runPreflight>>, name: string) =>
+  r.modules.find((m) => m.name === name)!;
+
+describe('runPreflight — reachability via path probes', () => {
+  beforeEach(() => invalidatePreflightCache());
+
+  it('probes every feature path; reachable comes from the real GET', async () => {
+    const r = await runPreflight(cfg('live'), fetchWith(ALL_OK));
+    expect(r.adminReachable).toBe(true);
+    expect(r.templatesMode).toBe('live');
+    // admin-server's probe IS the dump fetch — reachable without a 2nd call.
+    expect(byName(r, 'admin-server').reachable).toBe(true);
+    for (const n of ['receiver-runtime-rule', 'dsl-debugging', 'inspect', 'ui-management']) {
+      expect(byName(r, n).reachable).toBe(true);
+    }
+    // config-presence is a footnote, present here for every module.
+    expect(r.modules.every((m) => m.enabled)).toBe(true);
+  });
+
+  it('a 404 / 5xx / network error on a path reads as unreachable', async () => {
+    const r = await runPreflight(
+      cfg('live'),
+      fetchWith({ ...ALL_OK, '/inspect/metrics': 404, '/runtime/rule/list': 500, '/dsl-debugging/status': 'throw' }),
+    );
+    expect(byName(r, 'inspect').reachable).toBe(false); // 404 = route not registered
+    expect(byName(r, 'receiver-runtime-rule').reachable).toBe(false); // 5xx
+    expect(byName(r, 'dsl-debugging').reachable).toBe(false); // network error
+    expect(byName(r, 'ui-management').reachable).toBe(true);
+    // enabled stays true (the dump still advertises them) — proving reachable,
+    // not config-presence, drives health.
+    expect(byName(r, 'inspect').enabled).toBe(true);
+  });
+
+  it('a 4xx that is not 404 still counts as reachable (route exists)', async () => {
+    const r = await runPreflight(cfg('live'), fetchWith({ ...ALL_OK, '/runtime/rule/list': 400 }));
+    expect(byName(r, 'receiver-runtime-rule').reachable).toBe(true);
+  });
+
+  it('readonly mode does not probe ui_template — reachable is null', async () => {
+    const calls: string[] = [];
+    const r = await runPreflight(cfg('readonly'), fetchWith(ALL_OK, calls));
+    expect(byName(r, 'ui-management').reachable).toBeNull();
+    expect(calls.some((u) => u.endsWith('/ui-management/templates'))).toBe(false);
+    expect(byName(r, 'inspect').reachable).toBe(true); // others still probed
+  });
+
+  it('admin port down — every feature unreachable, no path probes', async () => {
+    const calls: string[] = [];
+    const downFetch = ((url: string) => {
+      calls.push(url);
+      return Promise.reject(new Error('ECONNREFUSED'));
+    }) as unknown as FetchLike;
+    const r = await runPreflight(cfg('live'), downFetch);
+    expect(r.adminReachable).toBe(false);
+    expect(r.modules.every((m) => m.reachable === false)).toBe(true);
+    expect(calls.every((u) => u.endsWith(DUMP))).toBe(true); // only the dump was tried
+  });
+});
+
+describe('getPreflight — single-flight cache', () => {
+  beforeEach(() => invalidatePreflightCache());
+
+  it('serves a cached round to concurrent / repeat reads, force bypasses it', async () => {
+    const calls: string[] = [];
+    const f = fetchWith(ALL_OK, calls);
+    await getPreflight(cfg('live'), f);
+    const dumpCalls1 = calls.filter((u) => u.endsWith(DUMP)).length;
+    await getPreflight(cfg('live'), f); // cached → no new probes
+    expect(calls.filter((u) => u.endsWith(DUMP)).length).toBe(dumpCalls1);
+    await getPreflight(cfg('live'), f, { force: true }); // bypass → fresh round
+    expect(calls.filter((u) => u.endsWith(DUMP)).length).toBe(dumpCalls1 + 1);
+  });
+});
diff --git a/apps/bff/src/logic/preflight/preflight.ts b/apps/bff/src/logic/preflight/preflight.ts
index 6026a81..5c551be 100644
--- a/apps/bff/src/logic/preflight/preflight.ts
+++ b/apps/bff/src/logic/preflight/preflight.ts
@@ -16,19 +16,25 @@
  */
 
 /**
- * Preflight check — interrogates `/debugging/config/dump` on OAP and
- * reports which of Studio's required OAP modules are enabled. The
- * SPA shows a one-time modal at login when any required selector is
- * missing, listing the env var and what UI breaks without it.
+ * Preflight — a REACHABILITY check of every OAP admin feature Horizon
+ * depends on. Each feature declares the relative admin REST path it
+ * actually calls; the BFF fires a safe GET at that path and reports
+ * whether it responds.
  *
- * The dump returns a `Map<String,String>` of dotted keys
- * `<module>.<provider>.<property>`. A module is enabled iff at least
- * one key with its prefix appears in the dump.
+ * Health = `reachable`, NOT `enabled`. The config-dump prefix check
+ * (`enabled`) only tells us the *official upstream release* advertises
+ * that selector — a fork / rename / different layout can be perfectly
+ * reachable yet show "disabled", or advertise a selector that 404s. So
+ * `enabled` is demoted to an informational footnote and the real GET
+ * decides green/red. A 404 = the route isn't there = unreachable.
  *
- * If admin-server itself is unreachable we return early with
- * `adminReachable: false` and every module marked `enabled: false`;
- * the operator's first move is "check OAP / admin port" rather than
- * "set selectors".
+ * Cost is bounded by a single-flight cache (`getPreflight`): concurrent
+ * / multi-user `/api/preflight` reads share one round of probes. It
+ * stays on-demand (only runs while a page is watching), not a timer.
+ *
+ * If the admin port itself is down (`/debugging/config/dump` fails) we
+ * return early with `adminReachable: false` and every feature
+ * `reachable: false` — fix the network / port first, not selectors.
  */
 
 import type {
@@ -44,6 +50,8 @@ interface ModuleDef {
   name: string;
   envVar: string;
   required: boolean;
+  /** Relative admin REST path the BFF GETs to test reachability. */
+  probePath: string;
   affects: string;
 }
 
@@ -52,13 +60,15 @@ const REQUIRED_MODULES: readonly ModuleDef[] = [
     name: 'admin-server',
     envVar: 'SW_ADMIN_SERVER',
     required: true,
+    probePath: '/debugging/config/dump',
     affects:
-      'Everything Studio does against the admin port. Without admin-server, the other three modules fail at boot with ModuleNotFoundException.',
+      'Everything Studio does against the admin port. Without admin-server, the other modules fail at boot with ModuleNotFoundException.',
   },
   {
     name: 'receiver-runtime-rule',
     envVar: 'SW_RECEIVER_RUNTIME_RULE',
     required: true,
+    probePath: '/runtime/rule/list',
     affects:
       "DSL Management (Catalog, OAL catalog), Editor save/load, Cluster status rule matrix, Live debugger rule picker, and the Inspect drawer's source attribution.",
   },
@@ -66,6 +76,7 @@ const REQUIRED_MODULES: readonly ModuleDef[] = [
     name: 'dsl-debugging',
     envVar: 'SW_DSL_DEBUGGING',
     required: true,
+    probePath: '/dsl-debugging/status',
     affects:
       'Live debugger across MAL / LAL / OAL (start / poll / stop) and the DSL-debugging health pane on Cluster status.',
   },
@@ -73,9 +84,18 @@ const REQUIRED_MODULES: readonly ModuleDef[] = [
     name: 'inspect',
     envVar: 'SW_INSPECT',
     required: true,
+    probePath: '/inspect/metrics',
     affects:
       'The Inspect page — every /api/inspect/* call returns 404 inspect_not_enabled and the page shows a banner instead of the board.',
   },
+  {
+    name: 'ui-management',
+    envVar: 'SW_UI_MANAGEMENT',
+    required: true,
+    probePath: '/ui-management/templates',
+    affects:
+      'Dashboard templates — the layer / overview / alert / 3D template store the config surface reads and writes. Unreachable in live mode blocks the config surface; in readonly mode Horizon serves bundled templates and never calls it.',
+  },
 ];
 
 export async function runPreflight(
@@ -83,50 +103,143 @@ export async function runPreflight(
   fetch: FetchLike,
 ): Promise<PreflightResult> {
   const adminUrl = config.oap.adminUrl;
+  const templatesMode = config.templates.mode;
   const generatedAt = Date.now();
   const dump = await fetchConfigDump(adminUrl, fetch, config.oap.timeoutMs, config.oap.auth);
 
   if (!dump.ok) {
+    // Admin port down — nothing downstream is reachable. Probing each
+    // path would just repeat the same failure N times.
     return {
       adminUrl,
       adminReachable: false,
       adminError: dump.error,
+      templatesMode,
       modules: REQUIRED_MODULES.map((m) => ({
         name: m.name,
         envVar: m.envVar,
         required: m.required,
-        affects: m.affects,
+        probePath: m.probePath,
+        reachable: false,
         enabled: false,
+        affects: m.affects,
       })),
       dumpKeyCount: 0,
       generatedAt,
     };
   }
 
-  const keys = Object.keys(dump.body);
   const enabledPrefixes = new Set<string>();
-  for (const k of keys) {
+  for (const k of Object.keys(dump.body)) {
     const top = k.split('.', 1)[0];
     if (top) enabledPrefixes.add(top);
   }
 
-  const modules: PreflightModule[] = REQUIRED_MODULES.map((m) => ({
-    name: m.name,
-    envVar: m.envVar,
-    required: m.required,
-    affects: m.affects,
-    enabled: enabledPrefixes.has(m.name),
-  }));
+  const modules: PreflightModule[] = await Promise.all(
+    REQUIRED_MODULES.map(async (m): Promise<PreflightModule> => {
+      const base = {
+        name: m.name,
+        envVar: m.envVar,
+        required: m.required,
+        probePath: m.probePath,
+        enabled: enabledPrefixes.has(m.name),
+        affects: m.affects,
+      };
+      // admin-server's probe IS the dump fetch we just did.
+      if (m.name === 'admin-server') return { ...base, reachable: true };
+      // ui_template is not called in readonly mode — don't probe it.
+      if (m.name === 'ui-management' && templatesMode === 'readonly') {
+        return { ...base, reachable: null };
+      }
+      const reachable = await probeReachable(adminUrl, m.probePath, fetch, config.oap.timeoutMs, config.oap.auth);
+      return { ...base, reachable };
+    }),
+  );
 
   return {
     adminUrl,
     adminReachable: true,
+    templatesMode,
     modules,
-    dumpKeyCount: keys.length,
+    dumpKeyCount: Object.keys(dump.body).length,
     generatedAt,
   };
 }
 
+/**
+ * Cached `runPreflight`. A single-flight 30s cache bounds OAP load when
+ * many sessions poll `/api/preflight` (the UI polls every 60s). Pass
+ * `force` for the cluster page's manual "re-check now" after the
+ * operator fixes the network / a selector.
+ */
+let cache: { at: number; result: PreflightResult } | null = null;
+let inFlight: Promise<PreflightResult> | null = null;
+const CACHE_TTL_MS = 30_000;
+
+export async function getPreflight(
+  config: HorizonConfig,
+  fetch: FetchLike,
+  opts: { force?: boolean } = {},
+): Promise<PreflightResult> {
+  const now = Date.now();
+  if (!opts.force && cache && now - cache.at < CACHE_TTL_MS) return cache.result;
+  if (!opts.force && inFlight) return inFlight;
+  inFlight = runPreflight(config, fetch)
+    .then((result) => {
+      cache = { at: Date.now(), result };
+      inFlight = null;
+      return result;
+    })
+    .catch((err) => {
+      inFlight = null;
+      throw err;
+    });
+  return inFlight;
+}
+
+/** Test seam — drop the cached probe round. */
+export function invalidatePreflightCache(): void {
+  cache = null;
+  inFlight = null;
+}
+
+/**
+ * Reachability of one admin REST path. Reachable = the GET got an HTTP
+ * response that isn't 404 or 5xx; a 404 means the route isn't
+ * registered (selector off / module absent), a 5xx / network error
+ * means the feature can't serve. A 4xx like 400/401 still proves the
+ * route exists, so it counts as reachable.
+ */
+async function probeReachable(
+  adminUrl: string,
+  path: string,
+  fetch: FetchLike,
+  timeoutMs: number,
+  auth?: { username: string; password: string },
+): Promise<boolean> {
+  const url = `${adminUrl.replace(/\/$/, '')}${path}`;
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (auth) {
+    const b64 = Buffer.from(`${auth.username}:${auth.password}`, 'utf8').toString('base64');
+    headers.authorization = `Basic ${b64}`;
+  }
+  let init: RequestInit = { method: 'GET', headers };
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  if (timeoutMs > 0) {
+    const ctrl = new AbortController();
+    timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    init = { ...init, signal: ctrl.signal };
+  }
+  try {
+    const res = await fetch(url, init);
+    return res.status !== 404 && res.status < 500;
+  } catch {
+    return false;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
 interface DumpOk {
   ok: true;
   body: Record<string, string>;
diff --git a/apps/bff/src/logic/templates/sync.test.ts b/apps/bff/src/logic/templates/sync.test.ts
new file mode 100644
index 0000000..b416292
--- /dev/null
+++ b/apps/bff/src/logic/templates/sync.test.ts
@@ -0,0 +1,67 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import type { UITemplateClient } from '@skywalking-horizon-ui/api-client';
+import { getSyncStatus, setTemplateReadOnly, invalidateSyncCache } from './sync.js';
+import { iterateBundledTemplates } from './aggregator.js';
+import { logger } from '../../logger.js';
+
+// A client that THROWS on any call — proves readonly mode never touches the
+// OAP ui_template store (it short-circuits to the disk bundle before list()).
+const throwingClient = {
+  list: () => Promise.reject(new Error('ui_template store must not be called in readonly mode')),
+  create: () => Promise.reject(new Error('no')),
+  update: () => Promise.reject(new Error('no')),
+  disable: () => Promise.reject(new Error('no')),
+} as unknown as UITemplateClient;
+
+const deps = { client: throwingClient, bundled: () => iterateBundledTemplates(), logger };
+
+describe('sync — readonly mode renders from the disk bundle', () => {
+  afterEach(() => {
+    setTemplateReadOnly(false);
+    invalidateSyncCache();
+  });
+
+  it('returns mode=readonly + reachable, without calling the ui_template client', async () => {
+    setTemplateReadOnly(true);
+    const status = await getSyncStatus(deps);
+    expect(status.mode).toBe('readonly');
+    expect(status.unreachable).toBe(false);
+    expect(status.rows.length).toBeGreaterThan(0);
+    // Every row is presented as effective:'remote' so every render consumer
+    // resolves it exactly as it would a live remote row.
+    expect(status.rows.every((r) => r.effective === 'remote' && r.remote !== null)).toBe(true);
+  });
+
+  it('includes per-locale translation overlay rows so non-English locales render translated', async () => {
+    setTemplateReadOnly(true);
+    const status = await getSyncStatus(deps);
+    const overlays = status.rows.filter((r) => r.locale !== undefined);
+    expect(overlays.length).toBeGreaterThan(0);
+    expect(overlays.some((r) => r.locale === 'zh-CN')).toBe(true);
+  });
+
+  it('carries the bundled source rows (layer/overview/alert/...) as effective content', async () => {
+    setTemplateReadOnly(true);
+    const status = await getSyncStatus(deps);
+    const kinds = new Set(status.rows.filter((r) => r.locale === undefined).map((r) => r.kind));
+    expect(kinds.has('layer')).toBe(true);
+    expect(kinds.has('overview')).toBe(true);
+  });
+});
diff --git a/apps/bff/src/logic/templates/sync.ts b/apps/bff/src/logic/templates/sync.ts
index 752a5e5..e53372a 100644
--- a/apps/bff/src/logic/templates/sync.ts
+++ b/apps/bff/src/logic/templates/sync.ts
@@ -46,6 +46,7 @@ import {
   serializeEnvelope,
   type TemplateKind,
 } from './names.js';
+import { iterateBundledOverlays } from './aggregator.js';
 
 export interface BundledTemplate {
   kind: TemplateKind;
@@ -94,9 +95,15 @@ export interface ConflictRow {
 }
 
 export interface SyncStatus {
+  /** Template source mode. `live` = read/write via OAP's ui_template store
+   *  (default). `readonly` = the store is never consulted; `rows` are the local
+   *  disk bundle loaded into the same in-memory shape and presented as the
+   *  effective content, and the config surface is read-only. */
+  mode: 'live' | 'readonly';
   /** When true, OAP admin was unreachable at the time this status was
    *  computed. `rows` will be a bundled-only view (every bundled row marked
-   *  `bundled-fallback`, no remote info). */
+   *  `bundled-fallback`, no remote info). Always false in `readonly` mode —
+   *  the store is deliberately not used, not unreachable. */
   unreachable: boolean;
   /** Epoch ms of the most-recent successful OAP probe. `null` when we
    *  have never reached OAP since process start. */
@@ -145,6 +152,22 @@ let cache: CacheEntry | null = null;
 let inFlight: Promise<SyncStatus> | null = null;
 let lastSuccessfulSyncAt: number | null = null;
 
+/** Boot-time template mode (`config.templates.mode`). In `readonly` the
+ *  orchestrator never touches the ui_template client — `runOnce` short-circuits
+ *  to the disk bundle. Set once at boot (and on config reload) by the server. */
+let readOnlyMode = false;
+export function setTemplateReadOnly(on: boolean): void {
+  readOnlyMode = on;
+  // A mode flip must not serve a stale cross-mode status: drop the cache AND
+  // orphan any in-flight probe (it still resolves its awaiters, but won't
+  // backfill the cache with a result computed under the old mode).
+  cache = null;
+  inFlight = null;
+}
+export function isTemplateReadOnly(): boolean {
+  return readOnlyMode;
+}
+
 export function invalidateSyncCache(): void {
   cache = null;
 }
@@ -261,6 +284,27 @@ async function runOnce(deps: SyncDeps, opts: RunOptions): Promise<SyncStatus> {
   const now = (deps.now ?? Date.now)();
   const bundledRows = buildBundledRows(deps.bundled());
 
+  // readonly mode: the disk bundle IS the source. Never call the ui_template
+  // client (no list, no seed); present every bundled source + translation
+  // overlay as the effective content so all render consumers resolve them
+  // exactly as they would a live remote row.
+  if (readOnlyMode) {
+    lastSuccessfulSyncAt = now;
+    // Source overlays from the canonical disk iterator — the on-demand render
+    // callers (bundle / menu / overlay / effective) don't pass `bundledOverlays`
+    // (only the boot seed does, and that's skipped in readonly), so without this
+    // every non-English locale would silently render in English.
+    const overlays = deps.bundledOverlays ? [...deps.bundledOverlays()] : [...iterateBundledOverlays()];
+    return {
+      mode: 'readonly',
+      unreachable: false,
+      lastSuccessfulSyncAt,
+      generatedAt: now,
+      rows: readonlyRows(bundledRows, overlays),
+      conflicts: [],
+    };
+  }
+
   let oapRows;
   try {
     oapRows = await deps.client.list();
@@ -270,6 +314,7 @@ async function runOnce(deps: SyncDeps, opts: RunOptions): Promise<SyncStatus> {
       'OAP UI-template list failed — rendering bundled, admin read-only',
     );
     return {
+      mode: 'live',
       unreachable: true,
       lastSuccessfulSyncAt,
       generatedAt: now,
@@ -315,6 +360,7 @@ async function runOnce(deps: SyncDeps, opts: RunOptions): Promise<SyncStatus> {
 
   const rows = mergeRows(bundledRows, parsedRemote.byName);
   return {
+    mode: 'live',
     unreachable: false,
     lastSuccessfulSyncAt,
     generatedAt: now,
@@ -323,6 +369,43 @@ async function runOnce(deps: SyncDeps, opts: RunOptions): Promise<SyncStatus> {
   };
 }
 
+/** readonly-mode rows: every bundled source template + translation overlay,
+ *  presented with the disk content as the effective (`remote`) configuration so
+ *  every render consumer resolves them uniformly (the ui_template store is never
+ *  consulted in this mode). `status: 'synced'` because the rendered config is,
+ *  by construction, exactly the bundled source; the synthetic `bundled:` id is
+ *  never used for a write (writes are denied in readonly). */
+function readonlyRows(bundled: Map<string, BundledRow>, overlays: BundledOverlay[]): TemplateRow[] {
+  const out: TemplateRow[] = [];
+  for (const b of bundled.values()) {
+    out.push({
+      name: b.name,
+      kind: b.kind,
+      key: b.key,
+      status: 'synced',
+      effective: 'remote',
+      remote: { id: `bundled:${b.name}`, configuration: b.configuration, disabled: false },
+      bundled: { configuration: b.configuration },
+    });
+  }
+  for (const ov of overlays) {
+    const env = buildOverlayEnvelope(ov.kind, ov.key, ov.locale, ov.content);
+    const configuration = serializeEnvelope(env);
+    out.push({
+      name: env.name,
+      kind: ov.kind,
+      key: ov.key,
+      locale: ov.locale,
+      status: 'synced',
+      effective: 'remote',
+      remote: { id: `bundled:${env.name}`, configuration, disabled: false },
+      bundled: { configuration },
+    });
+  }
+  out.sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
 /** Thrown when a write to OAP succeeded but the resulting row state
  *  didn't become visible to `list()` within the polling window. Routes
  *  catch this and return 504. */
diff --git a/apps/bff/src/rbac/route-policy.test.ts b/apps/bff/src/rbac/route-policy.test.ts
new file mode 100644
index 0000000..750dc3a
--- /dev/null
+++ b/apps/bff/src/rbac/route-policy.test.ts
@@ -0,0 +1,64 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { isTemplateWriteRoute, denyTemplateWriteWhenReadOnly } from './route-policy.js';
+import { setTemplateReadOnly } from '../logic/templates/sync.js';
+
+describe('isTemplateWriteRoute — which routes the readonly backstop covers', () => {
+  it('matches non-GET config-template write routes', () => {
+    expect(isTemplateWriteRoute('POST', '/api/admin/templates/save')).toBe(true);
+    expect(isTemplateWriteRoute('POST', '/api/admin/templates/save-translation')).toBe(true);
+    expect(isTemplateWriteRoute('POST', '/api/admin/templates/sync-all')).toBe(true);
+    expect(isTemplateWriteRoute('POST', '/api/admin/overview-templates')).toBe(true);
+    expect(isTemplateWriteRoute('DELETE', '/api/admin/overview-templates/x')).toBe(true);
+    // The alert page-setup (horizon.alert.page-setup) is config-surface too.
+    expect(isTemplateWriteRoute('POST', '/api/alarms/config')).toBe(true);
+  });
+  it('does NOT match reads, nor non-config writes (runtime-rule / live-debug stay editable)', () => {
+    expect(isTemplateWriteRoute('GET', '/api/admin/templates/sync-status')).toBe(false);
+    expect(isTemplateWriteRoute('HEAD', '/api/admin/templates/sync-status')).toBe(false);
+    expect(isTemplateWriteRoute('GET', '/api/alarms/config')).toBe(false); // read stays open
+    expect(isTemplateWriteRoute('POST', '/api/rule')).toBe(false); // runtime rule
+    expect(isTemplateWriteRoute('POST', '/api/debug/session')).toBe(false); // live-debug
+  });
+});
+
+describe('denyTemplateWriteWhenReadOnly — the BFF backstop', () => {
+  afterEach(() => setTemplateReadOnly(false));
+
+  const fakeReply = (): { reply: FastifyReply; code: ReturnType<typeof vi.fn> } => {
+    const send = vi.fn();
+    const code = vi.fn(() => ({ send }));
+    return { reply: { code } as unknown as FastifyReply, code };
+  };
+
+  it('rejects with 409 in readonly mode', async () => {
+    setTemplateReadOnly(true);
+    const { reply, code } = fakeReply();
+    await denyTemplateWriteWhenReadOnly({} as FastifyRequest, reply);
+    expect(code).toHaveBeenCalledWith(409);
+  });
+
+  it('is a no-op in live mode (lets the write proceed)', async () => {
+    setTemplateReadOnly(false);
+    const { reply, code } = fakeReply();
+    await denyTemplateWriteWhenReadOnly({} as FastifyRequest, reply);
+    expect(code).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/bff/src/rbac/route-policy.ts b/apps/bff/src/rbac/route-policy.ts
index 6e20dce..257a74b 100644
--- a/apps/bff/src/rbac/route-policy.ts
+++ b/apps/bff/src/rbac/route-policy.ts
@@ -28,10 +28,37 @@ import type { FastifyReply, FastifyRequest, RouteOptions } from 'fastify';
 import { sessionHasVerb } from './policy.js';
 import type { AuthDeps } from '../user/middleware.js';
 import { requireAuth } from '../user/middleware.js';
+import { isTemplateReadOnly } from '../logic/templates/sync.js';
 import { logger } from '../logger.js';
 
 export type RoutePolicy = 'public' | 'auth' | string;
 
+/** A config-surface write. The template routes push to OAP's ui_template store;
+ *  `/api/alarms/config` writes the alert page-setup (the `horizon.alert.page-setup`
+ *  template, file-backed). In `templates.mode=readonly` the whole config surface
+ *  is served from the local bundle and read-only, so these are denied at the edge
+ *  regardless of the verb grant (the UI hides them too, but a direct request must
+ *  still fail — the BFF is the authority). */
+export function isTemplateWriteRoute(method: string, url: string): boolean {
+  if (method === 'GET' || method === 'HEAD') return false;
+  return (
+    url.startsWith('/api/admin/templates') ||
+    url.startsWith('/api/admin/overview-templates') ||
+    url.startsWith('/api/alarms/config')
+  );
+}
+export async function denyTemplateWriteWhenReadOnly(
+  _req: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  if (isTemplateReadOnly()) {
+    reply.code(409).send({
+      error: 'read_only',
+      reason: 'templates.mode=readonly — config templates are served from the local bundle and cannot be edited',
+    });
+  }
+}
+
 /**
  * Verb-only check. Assumes a prior pre-handler (`requireAuth`) has
  * already populated `req.session`; sends 401 if not.
@@ -293,6 +320,10 @@ export function makeRouteAuthHook(deps: AuthDeps) {
     const newHandlers = [];
     if (!hasAuth) newHandlers.push(requireAuth(deps));
     if (chosen !== 'auth') newHandlers.push(checkVerb(deps, chosen));
+    // readonly-mode backstop on the config-template write routes.
+    if (methods.some((m) => isTemplateWriteRoute(String(m).toUpperCase(), route.url))) {
+      newHandlers.push(denyTemplateWriteWhenReadOnly);
+    }
 
     route.preHandler = [...existing, ...newHandlers];
   };
diff --git a/apps/bff/src/server.ts b/apps/bff/src/server.ts
index 03be503..eba8ce9 100644
--- a/apps/bff/src/server.ts
+++ b/apps/bff/src/server.ts
@@ -17,6 +17,7 @@
 
 import { existsSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
+import { ZodError } from 'zod';
 import Fastify from 'fastify';
 import cookie from '@fastify/cookie';
 import fastifyStatic from '@fastify/static';
@@ -66,7 +67,7 @@ import { registerOverviewRoutes } from './http/config/overview.js';
 import { registerConfigBundleRoute } from './http/config/bundle.js';
 import { registerTemplateSyncAdminRoutes } from './http/admin/template-sync.js';
 import { buildOapClients } from './client/index.js';
-import { bootSeed, waitForOapAdminReady } from './logic/templates/sync.js';
+import { bootSeed, waitForOapAdminReady, setTemplateReadOnly } from './logic/templates/sync.js';
 import { iterateBundledTemplates, iterateBundledOverlays } from './logic/templates/aggregator.js';
 // Admin (operational tools)
 import { registerDslCatalogRoutes } from './http/admin/dsl/catalog.js';
@@ -104,19 +105,49 @@ try {
     logger.fatal({ err: err.message, configPath }, 'BFF refusing to start: bootstrap validation failed');
     process.exit(1);
   }
+  if (err instanceof ZodError) {
+    // A bad value (often a HORIZON_* env override): surface the field path +
+    // reason instead of a raw zod dump. Booleans accept only true/false,
+    // numbers must be numeric, and JSON env vars must be valid JSON.
+    const issues = err.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+    logger.fatal(
+      { issues, configPath },
+      'BFF refusing to start: config validation failed — check the value (and any HORIZON_* env override) at each path. Booleans must be true/false; numbers must be numeric; JSON env vars must be valid JSON',
+    );
+    process.exit(1);
+  }
   throw err;
 }
 logger.info(
-  { configPath: source.path, backend: source.current.auth.backend },
+  {
+    configPath: source.path,
+    backend: source.current.auth.backend,
+    templatesMode: source.current.templates.mode,
+  },
   'config loaded',
 );
+// Template source mode is fixed at BOOT — it selects the boot-seed/source
+// path (live seeds + reads OAP; readonly skips the seed + renders bundled).
+// A hot-reload flip can't safely take effect (readonly→live would need the
+// boot seed that already ran/was-skipped), so we capture it once and only
+// warn if the file later changes it.
+const bootTemplatesMode = source.current.templates.mode;
+setTemplateReadOnly(bootTemplatesMode === 'readonly');
 if (source.current.auth.backend === 'ldap' && source.current.auth.local.users.length > 0) {
   logger.warn(
     { users: source.current.auth.local.users.length },
     'auth.local.users is populated but auth.backend is "ldap"; local users are ignored',
   );
 }
-source.onChange((cfg) => logger.info({ backend: cfg.auth.backend }, 'config reloaded'));
+source.onChange((cfg) => {
+  logger.info({ backend: cfg.auth.backend, templatesMode: cfg.templates.mode }, 'config reloaded');
+  if (cfg.templates.mode !== bootTemplatesMode) {
+    logger.warn(
+      { from: bootTemplatesMode, to: cfg.templates.mode },
+      'templates.mode change needs a BFF restart to take effect (boot-time seed + source selection); keeping the boot mode',
+    );
+  }
+});
 
 const app = Fastify({ logger: loggerOptions });
 
@@ -356,6 +387,14 @@ app.listen({ host, port }).then(
     // admin action triggers a fresh sync. The seed itself is
     // absent-only (`seedMissing` skips templates already present), so
     // a successful previous boot leaves nothing to re-push.
+    // readonly mode renders from the disk bundle and never touches the
+    // ui_template store — skip the readiness wait + seed entirely (otherwise
+    // the backoff loop warn-spams forever against an absent/disabled admin
+    // surface). The OAP *query* reachability check is independent and stays.
+    if (source.current.templates.mode === 'readonly') {
+      logger.info('templates.mode=readonly — rendering bundled templates, ui_template store not used');
+      return;
+    }
     void (async (): Promise<void> => {
       const deps = {
         client: buildOapClients(source.current).uiTemplate(),
diff --git a/apps/ui/src/api/scopes/configs.ts b/apps/ui/src/api/scopes/configs.ts
index 8c2f0d9..e64aea7 100644
--- a/apps/ui/src/api/scopes/configs.ts
+++ b/apps/ui/src/api/scopes/configs.ts
@@ -76,6 +76,9 @@ export interface TemplateConflict {
 /** Bundle-level sync envelope. When `unreachable`, all rows fall back to
  *  bundled and the admin pages render the global read-only banner. */
 export interface BundleSyncStatus {
+  /** `live` = OAP ui_template store is the source. `readonly` = local bundle
+   *  only; the config surface is read-only. */
+  mode: 'live' | 'readonly';
   unreachable: boolean;
   lastSuccessfulSyncAt: number | null;
   generatedAt: number;
diff --git a/apps/ui/src/api/scopes/menu.ts b/apps/ui/src/api/scopes/menu.ts
index 9a332d3..b08eac9 100644
--- a/apps/ui/src/api/scopes/menu.ts
+++ b/apps/ui/src/api/scopes/menu.ts
@@ -29,7 +29,7 @@ export class MenuApi {
   oapInfo(): Promise<OapInfo> {
     return this.bff.request<OapInfo>('GET', '/api/oap/info');
   }
-  preflight(): Promise<PreflightResult> {
-    return this.bff.request<PreflightResult>('GET', '/api/preflight');
+  preflight(force = false): Promise<PreflightResult> {
+    return this.bff.request<PreflightResult>('GET', force ? '/api/preflight?refresh=1' : '/api/preflight');
   }
 }
diff --git a/apps/ui/src/api/scopes/template-sync.ts b/apps/ui/src/api/scopes/template-sync.ts
index b7d0d9d..ac1cc12 100644
--- a/apps/ui/src/api/scopes/template-sync.ts
+++ b/apps/ui/src/api/scopes/template-sync.ts
@@ -41,6 +41,8 @@ export interface TemplateSyncRow {
 }
 
 export interface TemplateSyncStatus {
+  /** `live` = OAP ui_template store; `readonly` = local bundle, read-only. */
+  mode: 'live' | 'readonly';
   unreachable: boolean;
   lastSuccessfulSyncAt: number | null;
   generatedAt: number;
diff --git a/apps/ui/src/controls/configBundle.ts b/apps/ui/src/controls/configBundle.ts
index c9513b6..e6e0b62 100644
--- a/apps/ui/src/controls/configBundle.ts
+++ b/apps/ui/src/controls/configBundle.ts
@@ -86,10 +86,11 @@ function preferParam(): 'local' | 'remote' {
   }
 }
 
-// Bumped to v2 in 2026-05 when the bundle gained `syncStatus` (OAP
-// UI-template overlay). v1 cached bundles lack the field; loading them
-// would crash the admin pages reading badges.
-const STORAGE_KEY = 'horizon:configBundle:v2';
+// v2 (2026-05) added `syncStatus`; v3 added `syncStatus.mode` (live/readonly).
+// A returning operator's stale cache lacking `mode` would read as live even
+// when the BFF is in readonly — bump the key so older shapes are discarded and
+// the next fetch repopulates.
+const STORAGE_KEY = 'horizon:configBundle:v3';
 const state = ref<ConfigBundle | null>(null);
 let loadPromise: Promise<void> | null = null;
 
@@ -99,9 +100,9 @@ function readStorage(): ConfigBundle | null {
     const raw = localStorage.getItem(STORAGE_KEY);
     if (!raw) return null;
     const parsed = JSON.parse(raw) as ConfigBundle;
-    // Strict shape check: a v2 bundle MUST carry syncStatus. Older v1
+    // Strict shape check: a v3 bundle MUST carry syncStatus with a mode. Older
     // shapes are silently discarded — the next bundle fetch repopulates.
-    if (!parsed?.etag || !parsed?.layers || !parsed?.syncStatus) return null;
+    if (!parsed?.etag || !parsed?.layers || !parsed?.syncStatus?.mode) return null;
     return parsed;
   } catch {
     return null;
@@ -169,6 +170,7 @@ export function ensureConfigBundle(): Promise<void> {
           layers: {},
           overviews: [],
           syncStatus: {
+            mode: 'live',
             unreachable: true,
             lastSuccessfulSyncAt: null,
             generatedAt: now,
diff --git a/apps/ui/src/features/admin/_shared/SyncStatusBanner.vue b/apps/ui/src/features/admin/_shared/SyncStatusBanner.vue
index f036903..8f84279 100644
--- a/apps/ui/src/features/admin/_shared/SyncStatusBanner.vue
+++ b/apps/ui/src/features/admin/_shared/SyncStatusBanner.vue
@@ -79,6 +79,8 @@ function chipLabel(s: SyncBanner['severity']): string {
   switch (s) {
     case 'unreachable':
       return 'READ-ONLY';
+    case 'readonly':
+      return 'READ-ONLY';
     case 'conflict':
       return 'CONFLICT';
     case 'diverged':
@@ -122,6 +124,14 @@ export default { chipLabel };
   border-color: var(--sw-muted, #4a525c);
   background: var(--sw-bg-elev, #161a20);
 }
+/* Deliberate read-only (templates.mode=readonly) — not an error (no red), but
+ * warning-yellow so it's unmistakable that the whole surface is uneditable; a
+ * muted gray strip was too easy to miss next to the green per-row chips. */
+.sbb--readonly {
+  border-color: var(--sw-warn, #b88500);
+  background: rgba(184, 133, 0, 0.10);
+}
+.sbb--readonly .sbb__chip { background: var(--sw-warn, #b88500); color: #1a1a1a; }
 .sbb__row {
   display: flex;
   gap: 12px;
diff --git a/apps/ui/src/features/admin/_shared/useTemplateSync.ts b/apps/ui/src/features/admin/_shared/useTemplateSync.ts
index 0efff87..cebdcc3 100644
--- a/apps/ui/src/features/admin/_shared/useTemplateSync.ts
+++ b/apps/ui/src/features/admin/_shared/useTemplateSync.ts
@@ -46,7 +46,7 @@ import type {
   TemplateStatus,
 } from '@/api/scopes/configs';
 
-export type BannerSeverity = 'unreachable' | 'conflict' | 'diverged' | 'clean' | 'unknown';
+export type BannerSeverity = 'unreachable' | 'readonly' | 'conflict' | 'diverged' | 'clean' | 'unknown';
 
 export interface SyncBanner {
   severity: BannerSeverity;
@@ -101,7 +101,11 @@ export function useTemplateSync(opts: UseTemplateSyncOptions): UseTemplateSyncRe
     return (s.conflicts ?? []).filter((c) => c.kind === opts.kind);
   });
 
-  const readOnly = computed<boolean>(() => status.value?.unreachable === true);
+  // Read-only when OAP admin is unreachable (live mode, transient) OR the BFF
+  // is deliberately in readonly template mode (rendering the local bundle).
+  const readOnly = computed<boolean>(
+    () => status.value?.unreachable === true || status.value?.mode === 'readonly',
+  );
 
   // Shown on diverged + clean banners so the operator always knows what
   // the two axes mean.
@@ -128,6 +132,18 @@ export function useTemplateSync(opts: UseTemplateSyncOptions): UseTemplateSyncRe
     const counts: Partial<Record<TemplateStatus, number>> = {};
     for (const b of ownBadges.value) counts[b.status] = (counts[b.status] ?? 0) + 1;
 
+    if (s.mode === 'readonly') {
+      return {
+        severity: 'readonly',
+        message:
+          'Read-only mode — templates are served from the local bundle. Editing and publishing are disabled.',
+        detail:
+          'Set templates.mode=live (HORIZON_TEMPLATES_MODE=live) with OAP’s ui_template store reachable to edit.',
+        counts,
+        localCount: localCount.value,
+        conflicts: [],
+      };
+    }
     if (s.unreachable) {
       const last = s.lastSuccessfulSyncAt
         ? new Date(s.lastSuccessfulSyncAt).toLocaleString()
diff --git a/apps/ui/src/features/admin/translations/TranslationsView.vue b/apps/ui/src/features/admin/translations/TranslationsView.vue
index f21ccf9..333881e 100644
--- a/apps/ui/src/features/admin/translations/TranslationsView.vue
+++ b/apps/ui/src/features/admin/translations/TranslationsView.vue
@@ -398,6 +398,10 @@ interface PanelState {
 const panel = ref<PanelState>({ open: false, anchor: null, point: null, fields: [], label: '' });
 
 function openPanel(fields: TranslatableField[], label: string, el: HTMLElement, point: { x: number; y: number }): void {
+  // Read-only mode (templates.mode=readonly or admin unreachable): the canvas
+  // stays viewable but the editor never opens — no edit can start that could
+  // only end in a server 409. Sibling admin pages gate the same way.
+  if (readOnly.value) return;
   // Widgets with no translatable text (e.g. a topology widget that
   // only carries `layer`) shouldn't open an empty panel.
   if (fields.length === 0) return;
@@ -600,7 +604,7 @@ async function pushToOap(): Promise<void> {
   const name = selectedName.value;
   const loc = target.value;
   const overlay = draftOverlayForTarget.value;
-  if (!name || saving.value) return;
+  if (!name || saving.value || readOnly.value) return; // BFF denies it anyway
   saving.value = true;
   saveMsg.value = t('Saving to OAP…');
   let elapsed = 0;
diff --git a/apps/ui/src/features/operate/cluster/ClusterStatusView.vue b/apps/ui/src/features/operate/cluster/ClusterStatusView.vue
index 75f1e8f..7278d9b 100644
--- a/apps/ui/src/features/operate/cluster/ClusterStatusView.vue
+++ b/apps/ui/src/features/operate/cluster/ClusterStatusView.vue
@@ -15,8 +15,9 @@
   limitations under the License.
 -->
 <script setup lang="ts">
-import { computed } from 'vue';
+import { computed, ref, onMounted, onUnmounted } from 'vue';
 import { useI18n } from 'vue-i18n';
+import type { PreflightModule } from '@skywalking-horizon-ui/api-client';
 import { useOapInfo } from '@/shell/useOapInfo';
 import { useAdminFeatures } from '@/shell/useAdminFeatures';
 
@@ -48,9 +49,37 @@ const {
   adminUrl,
   adminReachable,
   adminError,
-  refetch: refetchPreflight,
+  recheck: refetchPreflight,
 } = useAdminFeatures();
 
+// "Checked Ns ago" advances against a slow ticker, anchored to the BFF's
+// generatedAt (so it reflects the real probe time incl. cache age, not the
+// render moment). 5s granularity is plenty for a 30s-cached / 60s-polled check.
+const now = ref(Date.now());
+let nowTimer: ReturnType<typeof setInterval> | null = null;
+onMounted(() => {
+  nowTimer = setInterval(() => (now.value = Date.now()), 5_000);
+});
+onUnmounted(() => {
+  if (nowTimer) clearInterval(nowTimer);
+});
+
+function agoLabel(ts: number | undefined): string {
+  if (!ts) return '—';
+  const sec = Math.max(0, Math.round((now.value - ts) / 1000));
+  if (sec < 60) return t('{n}s ago', { n: sec });
+  return t('{n}m ago', { n: Math.round(sec / 60) });
+}
+
+// Health = reachability of the feature's probed REST path, NOT config-presence.
+// reachable === null = not probed (ui_template in readonly: bundled, never called).
+function featureState(m: PreflightModule): { cls: string; label: string } {
+  if (m.reachable === null) return { cls: 'is-warn', label: t('readonly · bundled') };
+  return m.reachable
+    ? { cls: 'is-ok', label: t('reachable') }
+    : { cls: 'is-err', label: t('unreachable') };
+}
+
 const serverClockLocal = computed<string>(() => {
   const ts = info.value?.currentTimestamp;
   if (!ts) return '—';
@@ -77,24 +106,24 @@ const healthLabel = computed<string>(() => {
 const adminBadgeState = computed<'ok' | 'warn' | 'err' | 'unknown'>(() => {
   if (!preflight.value) return 'unknown';
   if (!adminReachable.value) return 'err';
-  // Admin port replied but some required selectors are off.
-  if (preflight.value.modules.some((m) => m.required && !m.enabled)) return 'warn';
+  // Anything not fully live-reachable — a path that 404s, or a bundled /
+  // not-probed feature (ui_template in readonly) — is a partial state.
+  if (preflight.value.modules.some((m) => m.reachable !== true)) return 'warn';
   return 'ok';
 });
 
 const adminBadgeLabel = computed<string>(() => {
   if (!preflight.value) return t('loading…');
   if (!adminReachable.value) return t('unreachable');
-  const off = preflight.value.modules.filter((m) => m.required && !m.enabled);
-  if (off.length === 0) return t('all selectors on');
-  return t('{n} selectors off', { n: off.length });
+  const mods = preflight.value.modules;
+  const reachable = mods.filter((m) => m.reachable === true).length;
+  if (reachable === mods.length) return t('all reachable');
+  // X/Y — covers both an unreachable path and a bundled (readonly) feature;
+  // the per-row chip says which.
+  return t('{n}/{total} reachable', { n: reachable, total: mods.length });
 });
 
-const adminGeneratedAt = computed<string>(() => {
-  const ts = preflight.value?.generatedAt;
-  if (!ts) return '—';
-  return new Date(ts).toLocaleTimeString();
-});
+const adminGeneratedAt = computed<string>(() => agoLabel(preflight.value?.generatedAt));
 
 // Zipkin / OTLP trace endpoint. Probed on the same poll as Pane A but
 // independently — it only feeds the Zipkin/OTLP trace menu, so a red
@@ -189,7 +218,7 @@ function refreshAll(): void {
       </header>
 
       <p class="pane-lede">
-        {{ t("Per-module enablement on the admin port. Each row gates a slice of horizon's UI — flip the corresponding env var on OAP and restart to enable, or remove the corresponding page from your operator menu if you don't need it.") }}
+        {{ t("Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.") }}
       </p>
 
       <div v-if="!preflight" class="empty">{{ t('loading preflight…') }}</div>
@@ -205,22 +234,31 @@ function refreshAll(): void {
       <table v-else class="mod-table">
         <thead>
           <tr>
-            <th>{{ t('Module') }}</th>
+            <th>{{ t('Feature') }}</th>
             <th>{{ t('State') }}</th>
-            <th>{{ t('Env var') }}</th>
+            <th>{{ t('Probe path') }}</th>
             <th>{{ t('Gates') }}</th>
           </tr>
         </thead>
         <tbody>
-          <tr v-for="m in preflight.modules" :key="m.name" :class="{ off: !m.enabled }">
+          <tr v-for="m in preflight.modules" :key="m.name" :class="{ off: m.reachable === false }">
             <td class="modname"><code>{{ m.name }}</code></td>
             <td>
-              <span class="sw-badge" :class="m.enabled ? 'is-ok' : 'is-err'">
-                <span class="state-dot" />{{ m.enabled ? t('enabled') : t('missing') }}
+              <span class="sw-badge" :class="featureState(m).cls">
+                <span class="state-dot" />{{ featureState(m).label }}
               </span>
+              <div class="state-foot">
+                <span class="checked">{{ t('checked {at}', { at: agoLabel(preflight.generatedAt) }) }}</span>
+                <span class="sel" :class="{ 'sel-off': !m.enabled }">{{
+                  m.enabled ? t('selector detected') : t('selector not detected')
+                }}</span>
+              </div>
+            </td>
+            <td class="modpath"><code>{{ m.probePath }}</code></td>
+            <td class="modaffects">
+              {{ t(m.affects) }}
+              <span class="env-ref">{{ t('Enable on OAP:') }} <code>{{ m.envVar }}=default</code></span>
             </td>
-            <td class="modenv"><code>{{ m.envVar }}</code></td>
-            <td class="modaffects">{{ t(m.affects) }}</td>
           </tr>
         </tbody>
       </table>
@@ -441,6 +479,23 @@ function refreshAll(): void {
   border-radius: 6px;
 }
 
+.state-foot {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px 10px;
+  margin-top: 4px;
+  font-size: var(--sw-fs-xs);
+  color: var(--sw-fg-3);
+}
+.state-foot .sel-off {
+  color: var(--sw-fg-4);
+  text-decoration: line-through;
+}
+.modpath code {
+  font-family: var(--sw-mono);
+  font-size: var(--sw-fs-sm);
+  color: var(--sw-fg-2);
+}
 .mod-table {
   width: 100%;
   border-collapse: collapse;
@@ -470,16 +525,24 @@ function refreshAll(): void {
 .mod-table tbody tr:last-child td {
   border-bottom: none;
 }
-.mod-table tr.off .modname code,
-.mod-table tr.off .modenv code {
+.mod-table tr.off .modname code {
   color: var(--sw-fg-2);
 }
-.modname code,
-.modenv code {
+.modname code {
   font-family: var(--sw-mono);
   font-size: var(--sw-fs-sm);
   color: var(--sw-fg-0);
 }
+.env-ref {
+  display: block;
+  margin-top: 4px;
+  font-size: var(--sw-fs-xs);
+  color: var(--sw-fg-3);
+}
+.env-ref code {
+  font-family: var(--sw-mono);
+  color: var(--sw-fg-2);
+}
 .modaffects {
   line-height: var(--sw-lh-relaxed);
   color: var(--sw-fg-2);
diff --git a/apps/ui/src/i18n/locales/de.json b/apps/ui/src/i18n/locales/de.json
index da89ed0..d0c4389 100644
--- a/apps/ui/src/i18n/locales/de.json
+++ b/apps/ui/src/i18n/locales/de.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "Keine Widgets in diesem Tab sichtbar.",
   "This tab has no widgets.": "Keine Widgets in diesem Tab.",
   "Clear all": "Alle löschen",
-  "Clear all and exit comparison": "Alle löschen und Vergleich beenden"
+  "Clear all and exit comparison": "Alle löschen und Vergleich beenden",
+  "Dashboard templates": "Dashboard-Vorlagen",
+  "read-only · bundled": "schreibgeschützt · gebündelt",
+  "live · OAP ui_template": "live · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "Rendering aus dem lokalen Bundle; die ui_template-API wird nicht verwendet und die Bearbeitung ist deaktiviert.",
+  "ui_template store reachable — editing enabled.": "ui_template-Speicher erreichbar — Bearbeitung aktiviert.",
+  "ui_template store unreachable — editing disabled.": "ui_template-Speicher nicht erreichbar — Bearbeitung deaktiviert.",
+  "Feature": "Funktion",
+  "Probe path": "Prüfpfad",
+  "readonly · bundled": "schreibgeschützt · gebündelt",
+  "selector detected": "Selektor erkannt",
+  "selector not detected": "Selektor nicht erkannt",
+  "all reachable": "alle erreichbar",
+  "{n} unreachable": "{n} nicht erreichbar",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "Erreichbarkeit jeder Admin-Funktion — der BFF sendet ein GET an den relativen REST-Pfad, den die Funktion tatsächlich aufruft, und meldet, ob er  [...]
+  "Enable on OAP:": "Auf OAP aktivieren:",
+  "{n}/{total} reachable": "{n}/{total} erreichbar"
 }
diff --git a/apps/ui/src/i18n/locales/en.json b/apps/ui/src/i18n/locales/en.json
index cb27a5b..10d1945 100644
--- a/apps/ui/src/i18n/locales/en.json
+++ b/apps/ui/src/i18n/locales/en.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "No widgets visible in this tab.",
   "This tab has no widgets.": "This tab has no widgets.",
   "Clear all": "Clear all",
-  "Clear all and exit comparison": "Clear all and exit comparison"
+  "Clear all and exit comparison": "Clear all and exit comparison",
+  "Dashboard templates": "Dashboard templates",
+  "read-only · bundled": "read-only · bundled",
+  "live · OAP ui_template": "live · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "Rendering from the local bundle; the ui_template API is not used and editing is disabled.",
+  "ui_template store reachable — editing enabled.": "ui_template store reachable — editing enabled.",
+  "ui_template store unreachable — editing disabled.": "ui_template store unreachable — editing disabled.",
+  "Feature": "Feature",
+  "Probe path": "Probe path",
+  "readonly · bundled": "readonly · bundled",
+  "selector detected": "selector detected",
+  "selector not detected": "selector not detected",
+  "all reachable": "all reachable",
+  "{n} unreachable": "{n} unreachable",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is th [...]
+  "Enable on OAP:": "Enable on OAP:",
+  "{n}/{total} reachable": "{n}/{total} reachable"
 }
diff --git a/apps/ui/src/i18n/locales/es.json b/apps/ui/src/i18n/locales/es.json
index eb106de..107a9f1 100644
--- a/apps/ui/src/i18n/locales/es.json
+++ b/apps/ui/src/i18n/locales/es.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "No hay widgets visibles en esta pestaña.",
   "This tab has no widgets.": "Esta pestaña no contiene widgets.",
   "Clear all": "Borrar todo",
-  "Clear all and exit comparison": "Borrar todo y salir de la comparación"
+  "Clear all and exit comparison": "Borrar todo y salir de la comparación",
+  "Dashboard templates": "Plantillas de panel",
+  "read-only · bundled": "solo lectura · incluido",
+  "live · OAP ui_template": "en vivo · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "Renderizado desde el paquete local; la API ui_template no se usa y la edición está deshabilitada.",
+  "ui_template store reachable — editing enabled.": "Almacén ui_template accesible — edición habilitada.",
+  "ui_template store unreachable — editing disabled.": "Almacén ui_template inaccesible — edición deshabilitada.",
+  "Feature": "Función",
+  "Probe path": "Ruta de sondeo",
+  "readonly · bundled": "solo lectura · incluido",
+  "selector detected": "selector detectado",
+  "selector not detected": "selector no detectado",
+  "all reachable": "todos accesibles",
+  "{n} unreachable": "{n} inaccesible(s)",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "Accesibilidad de cada función de administración: el BFF hace un GET a la ruta REST relativa que la función realmente llama e informa si responde. [...]
+  "Enable on OAP:": "Activar en OAP:",
+  "{n}/{total} reachable": "{n}/{total} accesibles"
 }
diff --git a/apps/ui/src/i18n/locales/fr.json b/apps/ui/src/i18n/locales/fr.json
index 5818403..518256d 100644
--- a/apps/ui/src/i18n/locales/fr.json
+++ b/apps/ui/src/i18n/locales/fr.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "Aucun widget visible dans cet onglet.",
   "This tab has no widgets.": "Aucun widget dans cet onglet.",
   "Clear all": "Tout effacer",
-  "Clear all and exit comparison": "Tout effacer et quitter la comparaison"
+  "Clear all and exit comparison": "Tout effacer et quitter la comparaison",
+  "Dashboard templates": "Modèles de tableau de bord",
+  "read-only · bundled": "lecture seule · intégré",
+  "live · OAP ui_template": "en direct · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "Rendu à partir du paquet local ; l’API ui_template n’est pas utilisée et l’édition est désactivée.",
+  "ui_template store reachable — editing enabled.": "Magasin ui_template accessible — édition activée.",
+  "ui_template store unreachable — editing disabled.": "Magasin ui_template inaccessible — édition désactivée.",
+  "Feature": "Fonctionnalité",
+  "Probe path": "Chemin de sonde",
+  "readonly · bundled": "lecture seule · intégré",
+  "selector detected": "sélecteur détecté",
+  "selector not detected": "sélecteur non détecté",
+  "all reachable": "tous accessibles",
+  "{n} unreachable": "{n} inaccessible(s)",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "Accessibilité de chaque fonctionnalité d'administration — le BFF envoie un GET sur le chemin REST relatif que la fonctionnalité appelle réellemen [...]
+  "Enable on OAP:": "Activer sur OAP :",
+  "{n}/{total} reachable": "{n}/{total} accessibles"
 }
diff --git a/apps/ui/src/i18n/locales/ja.json b/apps/ui/src/i18n/locales/ja.json
index 25b67b6..bcb8878 100644
--- a/apps/ui/src/i18n/locales/ja.json
+++ b/apps/ui/src/i18n/locales/ja.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "このタブに表示できるウィジェットはありません。",
   "This tab has no widgets.": "このタブにはウィジェットがありません。",
   "Clear all": "すべてクリア",
-  "Clear all and exit comparison": "すべてクリアして比較を終了"
+  "Clear all and exit comparison": "すべてクリアして比較を終了",
+  "Dashboard templates": "ダッシュボードテンプレート",
+  "read-only · bundled": "読み取り専用 · バンドル",
+  "live · OAP ui_template": "ライブ · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "ローカルバンドルからレンダリングしています。ui_template API は使用されず、編集は無効です。",
+  "ui_template store reachable — editing enabled.": "ui_template ストアに到達可能 —— 編集が有効です。",
+  "ui_template store unreachable — editing disabled.": "ui_template ストアに到達不可 —— 編集が無効です。",
+  "Feature": "機能",
+  "Probe path": "プローブパス",
+  "readonly · bundled": "読み取り専用 · バンドル",
+  "selector detected": "selector を検出",
+  "selector not detected": "selector を検出せず",
+  "all reachable": "すべて到達可能",
+  "{n} unreachable": "{n} 件が到達不可",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "各管理機能の到達可能性 —— BFF は機能が実際に呼び出す相対 REST パスへ GET し、応答するかどうかを報告します。健全性は設定の有無ではなくライブプローブで判定されます。404 を返すパス(selector が無効、リネーム、またはフォークで欠落)は到達不可とみなされます。下の [...]
+  "Enable on OAP:": "OAP で有効化:",
+  "{n}/{total} reachable": "{n}/{total} 件が到達可能"
 }
diff --git a/apps/ui/src/i18n/locales/ko.json b/apps/ui/src/i18n/locales/ko.json
index aead661..680a3a9 100644
--- a/apps/ui/src/i18n/locales/ko.json
+++ b/apps/ui/src/i18n/locales/ko.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "이 탭에 표시할 위젯이 없습니다.",
   "This tab has no widgets.": "이 탭에는 위젯이 없습니다.",
   "Clear all": "모두 지우기",
-  "Clear all and exit comparison": "모두 지우고 비교 종료"
+  "Clear all and exit comparison": "모두 지우고 비교 종료",
+  "Dashboard templates": "대시보드 템플릿",
+  "read-only · bundled": "읽기 전용 · 번들",
+  "live · OAP ui_template": "라이브 · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "로컬 번들에서 렌더링합니다. ui_template API는 사용되지 않으며 편집이 비활성화됩니다.",
+  "ui_template store reachable — editing enabled.": "ui_template 저장소에 연결됨 — 편집이 활성화됩니다.",
+  "ui_template store unreachable — editing disabled.": "ui_template 저장소에 연결할 수 없음 — 편집이 비활성화됩니다.",
+  "Feature": "기능",
+  "Probe path": "프로브 경로",
+  "readonly · bundled": "읽기 전용 · 번들",
+  "selector detected": "selector 감지됨",
+  "selector not detected": "selector 감지 안 됨",
+  "all reachable": "모두 도달 가능",
+  "{n} unreachable": "{n}개 도달 불가",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "각 관리 기능의 도달 가능성 — BFF가 해당 기능이 실제로 호출하는 상대 REST 경로로 GET 요청을 보내 응답 여부를 보고합니다. 상태는 설정 존재 여부가 아니라 실시간 프로브로 판단합니다. 404를 반환하는 경로(selector 꺼짐, 이름 변경 또는  [...]
+  "Enable on OAP:": "OAP에서 활성화:",
+  "{n}/{total} reachable": "{n}/{total}개 도달 가능"
 }
diff --git a/apps/ui/src/i18n/locales/pt.json b/apps/ui/src/i18n/locales/pt.json
index 27d3113..8305b7f 100644
--- a/apps/ui/src/i18n/locales/pt.json
+++ b/apps/ui/src/i18n/locales/pt.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "Nenhum widget visível nesta aba.",
   "This tab has no widgets.": "Nenhum widget nesta aba.",
   "Clear all": "Limpar tudo",
-  "Clear all and exit comparison": "Limpar tudo e sair da comparação"
+  "Clear all and exit comparison": "Limpar tudo e sair da comparação",
+  "Dashboard templates": "Modelos de painel",
+  "read-only · bundled": "somente leitura · incluído",
+  "live · OAP ui_template": "ao vivo · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "Renderizando a partir do pacote local; a API ui_template não é usada e a edição está desabilitada.",
+  "ui_template store reachable — editing enabled.": "Armazenamento ui_template acessível — edição habilitada.",
+  "ui_template store unreachable — editing disabled.": "Armazenamento ui_template inacessível — edição desabilitada.",
+  "Feature": "Recurso",
+  "Probe path": "Caminho de sondagem",
+  "readonly · bundled": "somente leitura · incluído",
+  "selector detected": "selector detectado",
+  "selector not detected": "selector não detectado",
+  "all reachable": "todos acessíveis",
+  "{n} unreachable": "{n} inacessível(is)",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "Acessibilidade de cada recurso de administração: o BFF faz um GET no caminho REST relativo que o recurso realmente chama e informa se ele respond [...]
+  "Enable on OAP:": "Ativar no OAP:",
+  "{n}/{total} reachable": "{n}/{total} acessíveis"
 }
diff --git a/apps/ui/src/i18n/locales/zh-CN.json b/apps/ui/src/i18n/locales/zh-CN.json
index ea6d75e..2eb38b0 100644
--- a/apps/ui/src/i18n/locales/zh-CN.json
+++ b/apps/ui/src/i18n/locales/zh-CN.json
@@ -1533,5 +1533,21 @@
   "No widgets visible in this tab.": "此标签页中没有可见的组件。",
   "This tab has no widgets.": "此标签页中暂无组件。",
   "Clear all": "全部清除",
-  "Clear all and exit comparison": "清除全部并退出对比"
+  "Clear all and exit comparison": "清除全部并退出对比",
+  "Dashboard templates": "仪表板模板",
+  "read-only · bundled": "只读 · 内置",
+  "live · OAP ui_template": "在线 · OAP ui_template",
+  "Rendering from the local bundle; the ui_template API is not used and editing is disabled.": "从本地内置模板渲染;不使用 ui_template API,编辑已禁用。",
+  "ui_template store reachable — editing enabled.": "ui_template 存储可达 —— 编辑已启用。",
+  "ui_template store unreachable — editing disabled.": "ui_template 存储不可达 —— 编辑已禁用。",
+  "Feature": "功能",
+  "Probe path": "探测路径",
+  "readonly · bundled": "只读 · 内置",
+  "selector detected": "检测到 selector",
+  "selector not detected": "未检测到 selector",
+  "all reachable": "全部可达",
+  "{n} unreachable": "{n} 个不可达",
+  "Reachability of each admin feature — the BFF GETs the relative REST path the feature actually calls and reports whether it responds. Health is the live probe, not config-presence: a path that 404s (selector off, renamed, or absent in a fork) reads as unreachable. 'selector detected' below is only an upstream-release hint, not the verdict.": "每个管理功能的可达性 —— BFF 会向该功能实际调用的相对 REST 路径发起 GET,并报告其是否响应。健康状态取决于实时探测,而非配置存在性:返回 404 的路径(selector 关闭、被重命名或在 fork 版本中缺失)将被视为不可达。下方的“检测到 selector”仅为上游发 [...]
+  "Enable on OAP:": "在 OAP 上启用:",
+  "{n}/{total} reachable": "{n}/{total} 个可达"
 }
diff --git a/apps/ui/src/shell/AdminFeatureWarning.vue b/apps/ui/src/shell/AdminFeatureWarning.vue
index 628b069..8825b54 100644
--- a/apps/ui/src/shell/AdminFeatureWarning.vue
+++ b/apps/ui/src/shell/AdminFeatureWarning.vue
@@ -53,15 +53,17 @@ const { result, adminReachable, adminError, adminUrl, moduleByName, refetch } =
   useAdminFeatures();
 
 const mod = moduleByName(props.module);
-const moduleEnabled = computed<boolean>(() => mod.value?.enabled ?? false);
+// Health is the feature's path probe, not config-presence. `reachable`
+// is a boolean for these three (null is only ui_template/readonly).
+const moduleReachable = computed<boolean>(() => mod.value?.reachable !== false);
 
-/** Hide when everything is fine — admin reachable AND target module
- *  on. Loading state also hides (page renders normally; banner pops
- *  in if/when preflight returns a failure). */
+/** Hide when everything is fine — admin reachable AND this feature's
+ *  path responds. Loading state also hides (page renders normally;
+ *  banner pops in if/when the probe comes back unreachable). */
 const visible = computed<boolean>(() => {
   if (!result.value) return false;
   if (!adminReachable.value) return true;
-  return !moduleEnabled.value;
+  return !moduleReachable.value;
 });
 
 const kind = computed<'host' | 'module'>(() =>
diff --git a/apps/ui/src/shell/useAdminFeatures.ts b/apps/ui/src/shell/useAdminFeatures.ts
index a3cefa2..28c10fd 100644
--- a/apps/ui/src/shell/useAdminFeatures.ts
+++ b/apps/ui/src/shell/useAdminFeatures.ts
@@ -16,14 +16,15 @@
  */
 
 import { computed } from 'vue';
-import { useQuery } from '@tanstack/vue-query';
+import { useQuery, useQueryClient } from '@tanstack/vue-query';
 import type { PreflightResult } from '@skywalking-horizon-ui/api-client';
 import { bffClient } from '@/api/client';
 
 /**
- * Admin-port preflight — interrogates OAP's `/debugging/config/dump`
- * (port 17128 by default) and exposes per-module enablement plus a
- * shorthand `adminReachable` flag. Drives:
+ * Admin-port preflight — a REACHABILITY check of each OAP admin feature
+ * Horizon depends on (the BFF GETs the feature's real REST path).
+ * Exposes per-feature reachability plus a shorthand `adminReachable`.
+ * Drives:
  *   - the admin section of `/operate/cluster`
  *   - the per-page warning header on admin-host routes (DSL Mgmt,
  *     Live Debugger, Dump, OAL viewer, Inspect)
@@ -32,10 +33,13 @@ import { bffClient } from '@/api/client';
  * keeping the two checks split lets the cluster page show "graphql
  * fine, admin down" without false negatives on either side.
  *
- * Polled every 60s; the cluster page can call `refetch()` to poke
- * it on demand after the operator fixes the network / selectors.
+ * Polled every 60s (the BFF single-flights the underlying probes for
+ * 30s). `recheck()` forces a fresh round on the BFF — for the cluster
+ * page's "re-check now" after the operator fixes the network / a
+ * selector — and seeds it into the shared cache.
  */
 export function useAdminFeatures() {
+  const qc = useQueryClient();
   const q = useQuery({
     queryKey: ['oap-preflight'],
     queryFn: () => bffClient.menu.preflight(),
@@ -48,22 +52,13 @@ export function useAdminFeatures() {
   const adminReachable = computed<boolean>(() => result.value?.adminReachable ?? false);
   const adminUrl = computed<string | undefined>(() => result.value?.adminUrl);
   const adminError = computed<string | undefined>(() => result.value?.adminError);
+  const templatesMode = computed<'live' | 'readonly'>(() => result.value?.templatesMode ?? 'live');
 
   /** Look up a single module by OAP name (e.g. `receiver-runtime-rule`). */
   function moduleByName(name: string) {
     return computed(() => result.value?.modules.find((m) => m.name === name));
   }
 
-  const runtimeRuleEnabled = computed<boolean>(
-    () => moduleByName('receiver-runtime-rule').value?.enabled ?? false,
-  );
-  const dslDebuggingEnabled = computed<boolean>(
-    () => moduleByName('dsl-debugging').value?.enabled ?? false,
-  );
-  const inspectEnabled = computed<boolean>(
-    () => moduleByName('inspect').value?.enabled ?? false,
-  );
-
   /** Convenience for the per-page warning header — true when nothing
    *  on the admin port works (port itself down OR admin-server module
    *  off). Page UIs render the warning + still try to mount so the
@@ -72,6 +67,14 @@ export function useAdminFeatures() {
     () => !result.value || !adminReachable.value,
   );
 
+  /** Force a fresh probe round on the BFF (bypasses its 30s cache) and
+   *  push the result into the shared query cache. */
+  async function recheck(): Promise<PreflightResult> {
+    const fresh = await bffClient.menu.preflight(true);
+    qc.setQueryData(['oap-preflight'], fresh);
+    return fresh;
+  }
+
   return {
     isLoading: q.isLoading,
     result,
@@ -79,10 +82,9 @@ export function useAdminFeatures() {
     adminReachable,
     adminUnavailable,
     adminError,
-    runtimeRuleEnabled,
-    dslDebuggingEnabled,
-    inspectEnabled,
+    templatesMode,
     moduleByName,
     refetch: q.refetch,
+    recheck,
   };
 }
diff --git a/docs/access-control/local-backend.md b/docs/access-control/local-backend.md
index dc01ce7..6ff3d86 100644
--- a/docs/access-control/local-backend.md
+++ b/docs/access-control/local-backend.md
@@ -60,10 +60,10 @@ The session captures the role list at authentication time, not on every request.
 
 ## File permissions
 
-`horizon.yaml` contains password hashes. Treat it as a secret-bearing file:
+The `horizon.yaml` shipped in the repo and image is **env-driven and holds no secrets** — `local.users` defaults to the `HORIZON_AUTH_LOCAL_USERS` variable. Supply your users (with their Argon2id hashes) through that environment variable so hashes never land in a version-controlled file. If you instead write hashes directly into a `horizon.yaml` you deploy, treat that copy as a secret-bearing file:
 
 - Filesystem perms `0600` (BFF user only).
-- Not in version control. The repo's `.gitignore` excludes `horizon.yaml`; only `horizon.example.yaml` is committed.
+- Keep it out of version control — the committed `horizon.yaml` holds only `${HORIZON_…}` tokens, never real hashes.
 - If you store the file in configuration management (Ansible, Helm secret, etc.), encrypt at rest.
 
 ## Mixing with LDAP
diff --git a/docs/compatibility/ports.md b/docs/compatibility/ports.md
index 6707bb5..0a3d51b 100644
--- a/docs/compatibility/ports.md
+++ b/docs/compatibility/ports.md
@@ -38,7 +38,7 @@ The OAP defaults. Each module binds its own port:
 - `:17128` for admin
 - `:9412` for Zipkin
 
-This is what `horizon.example.yaml` shows.
+This is what `horizon.yaml` shows.
 
 ### Shared port (Docker / Kubernetes presets)
 
diff --git a/docs/setup/container-image.md b/docs/setup/container-image.md
index 7053553..0e89006 100644
--- a/docs/setup/container-image.md
+++ b/docs/setup/container-image.md
@@ -28,8 +28,7 @@ The full commit SHA is the canonical, immutable identifier. Moving tags are conv
 | `/app/server.js` | root | no | Compiled BFF entry point. `CMD` runs `node server.js`. |
 | `/app/node_modules/` | root | no | Production npm dependencies. |
 | `/app/static/` | root | no | Built UI assets (Vite `dist/`). |
-| `/app/horizon.example.yaml` | root | no | Example config — **read-only reference**, copy from it. |
-| `/app/horizon.yaml` | n/a | n/a | Where the BFF expects the **active** config. **Not present in the image** — provide via mount or `COPY` (see below). |
+| `/app/horizon.yaml` | root | no | The **active** config — a **baked, fully tokenized default** (every field is a `${HORIZON_…:default}` env token). The image runs with no mounted file; override any field via env (see [Run with env vars only](#run-with-env-vars-only-no-mounted-file)), or bind-mount your own to replace it. |
 | `/app/bundled_templates/` | **horizon** | **yes** | Layer + overview JSON templates. Owned by `horizon` because the admin **Layer-Templates** and **Overview-Templates** editors write into per-key files here. |
 | `/data/` | **horizon** | **yes** | Declared `VOLUME`. Default destination for the audit log, setup state, alarm state, and wire debug log. Mount a PVC / named volume / host bind here for durable storage. |
 | `/app/sourcemaps/` | **horizon** | (read) | Static source maps for the **Browser Logs** tab. Bind-mount or copy `.map` files here and they're loaded at boot — durable across restarts. Optional; runtime uploads work without it. See [Browser Logs & Source Maps](../operate/browser-source-maps.md). |
@@ -54,6 +53,55 @@ The four `HORIZON_*_FILE` env vars seed the **defaults** the config schema uses
 
 `server.host` and `server.port` come from the YAML when present. If they are omitted, the image supplies defaults via `HORIZON_SERVER_HOST=0.0.0.0` and `HORIZON_SERVER_PORT=8081`. The image sets `EXPOSE 8081`; if you change `server.port`, also publish the new port.
 
+## Run with env vars only (no mounted file)
+
+The baked `/app/horizon.yaml` is **fully tokenized** — every config field is a `${HORIZON_…:default}` env var — so you can run the published image with **no mounted config** and set only the vars you need. Precedence is **env var > the baked file's default > built-in default**. The config file itself is the complete, self-documenting list; the table below mirrors it.
+
+Scalar vars take a plain value; **list / object vars take a JSON string** (injected into the YAML and parsed). A `null`/`[]` default means "use the built-in default".
+
+| Variable | Default | Type | Sets |
+|---|---|---|---|
+| `HORIZON_TEMPLATES_MODE` | `live` | `live` \| `readonly` | Template source: OAP ui_template store (`live`) vs. the local bundle, read-only (`readonly`). |
+| `HORIZON_OAP_QUERY_URL` | `http://127.0.0.1:12800` | url | OAP GraphQL / query host. |
+| `HORIZON_OAP_ADMIN_URL` | `http://127.0.0.1:17128` | url | OAP admin host (runtime-rule / inspect / status). |
+| `HORIZON_OAP_ZIPKIN_URL` | `http://127.0.0.1:9412/zipkin` | url | OAP Zipkin v2 host. |
+| `HORIZON_OAP_TIMEOUT_MS` | `15000` | int | Outbound OAP request timeout. |
+| `HORIZON_OAP_AUTH` | (none) | JSON | OAP basic-auth, e.g. `{"username":"sw","password":"sw"}`. |
+| `HORIZON_AUTH_BACKEND` | `local` | `local` \| `ldap` | Auth backend. |
+| `HORIZON_AUTH_LOCAL_USERS` | `[]` | JSON | Local users: `[{"username":"admin","passwordHash":"$argon2id$…","roles":["admin"]}]` (hash via `pnpm --filter bff cli:hash`). |
+| `HORIZON_AUTH_LDAP` | (none) | JSON | LDAP block: `{"url":"ldaps://…","userBaseDn":"…","groupMappings":[{"group":"*","role":"viewer"}]}`. |
+| `HORIZON_AUTH_BREAK_GLASS` | (none) | JSON | Break-glass admin (honored only when `ldap` + LDAP probe failing). |
+| `HORIZON_RBAC_ENABLED` | `true` | bool | When `false`, every session gets `*`. |
+| `HORIZON_RBAC_ROLES` | (built-in) | JSON | Role → verb-grants map. |
+| `HORIZON_RBAC_LANDING_BY_ROLE` | (built-in) | JSON | Post-login landing route per role. |
+| `HORIZON_LAYERS_EXCLUDED` | `FAAS`, `VIRTUAL_GATEWAY` | JSON | Layers hidden from the sidebar; `[]` shows all. |
+| `HORIZON_SESSION_TTL_MINUTES` | `60` | int | Session lifetime. |
+| `HORIZON_SESSION_COOKIE_NAME` | `horizon_sid` | string | Session cookie name. |
+| `HORIZON_SESSION_COOKIE_SECURE` | `false` | bool | Set `true` behind HTTPS. |
+| `HORIZON_QUERY_LANDING_SERVICE_CAP` | `100` | int | Max services a layer landing fetches metrics for per request. |
+| `HORIZON_SOURCEMAPS_ENABLED` | `true` | bool | Source-map upload / resolve capability. |
+| `HORIZON_SOURCEMAPS_MAX_FILE_BYTES` | `67108864` | int | Reject a `.map` larger than this (64 MiB). |
+| `HORIZON_SOURCEMAPS_MAX_TOTAL_BYTES` | `536870912` | int | In-memory map budget (512 MiB, LRU-evicted). |
+| `HORIZON_SOURCEMAPS_MAX_FILE_COUNT` | `128` | int | Max hosted maps. |
+| `HORIZON_DEBUG_LOG_ENABLED` | `false` | bool | OAP wire debug log. |
+| `HORIZON_DEBUG_LOG_MAX_BODY_CHARS` | `8192` | int | Wire-log body truncation. |
+| `HORIZON_DEBUG_LOG_REDACT_AUTH` | `true` | bool | Redact auth headers in the wire log. |
+| `HORIZON_PERFORMANCE` | (built-in) | JSON | BFF→OAP fan-out + caps, e.g. `{"bulk":{"dashboard":{"bulkSize":8}}}`. |
+
+Server bind, static dir, the `HORIZON_*_FILE` state paths, and `HORIZON_SOURCEMAPS_DIR` are in the table above this section (the image already sets them to container-appropriate values).
+
+A minimal env-only run against a real OAP with one admin user:
+
+```bash
+docker run --rm -p 8081:8081 \
+  -e HORIZON_OAP_QUERY_URL=http://oap:12800 \
+  -e HORIZON_OAP_ADMIN_URL=http://oap:17128 \
+  -e HORIZON_AUTH_LOCAL_USERS='[{"username":"admin","passwordHash":"'"$(…cli:hash…)"'","roles":["admin"]}]' \
+  ghcr.io/apache/skywalking-horizon-ui:<version>
+```
+
+To run standalone on the bundled templates (no ui_template admin API), add `-e HORIZON_TEMPLATES_MODE=readonly` — dashboards render from the local bundle and the config surface is read-only (the OAP query host is still required for metrics / traces / logs).
+
 ## Memory & sizing
 
 The BFF holds its **source-map cache in the Node heap** — uploaded Browser-Logs maps live in process memory, not in OAP — so the container's memory limit and Node's heap limit must be sized together with the source-map budget.
diff --git a/docs/setup/overview.md b/docs/setup/overview.md
index 143122f..ea218d7 100644
--- a/docs/setup/overview.md
+++ b/docs/setup/overview.md
@@ -12,15 +12,14 @@ This page is the shortest path from "no Horizon" to "Horizon in front of a runni
 
 ### 1. Unpack Horizon
 
-Unpack the binary tarball (substitute the release version you downloaded for `<version>`) and copy the example config:
+Unpack the binary tarball (substitute the release version you downloaded for `<version>`):
 
 ```sh
 tar -xzf apache-skywalking-horizon-ui-<version>-bin.tar.gz
 cd apache-skywalking-horizon-ui-<version>-bin
-cp horizon.example.yaml horizon.yaml
 ```
 
-The binary is self-contained: `server.js`, `node_modules/`, `static/`, and bundled templates are already present. There is no `pnpm install` step.
+The binary is self-contained: `server.js`, `node_modules/`, `static/`, bundled templates, and the config `horizon.yaml` are already present. There is no `pnpm install` step. `horizon.yaml` is **env-driven** — every field is a `${HORIZON_…:default}` variable, so you can leave the file as-is and set only the environment variables you need (starting with your OAP address), or edit the file directly.
 
 ### 2. Point Horizon at OAP
 
diff --git a/docs/setup/rbac.md b/docs/setup/rbac.md
index 31b195a..346c119 100644
--- a/docs/setup/rbac.md
+++ b/docs/setup/rbac.md
@@ -24,7 +24,7 @@ rbac:
 | Field | Type | Default | Required | Notes |
 |---|---|---|---|---|
 | `enabled` | boolean | `true` | no | When `false`, every authenticated session is granted `*` (full access). Useful for dev. **Set `true` in production.** |
-| `roles` | object | the four built-ins | no | Custom role definitions. Keys are role names; values are arrays of permission strings. **Omitting this block uses the four built-ins** (`viewer`, `maintainer`, `operator`, `admin`) — see `horizon.example.yaml` for the full grants. Defining the block at all overrides the built-ins entirely; redefine all four if you want to keep them. |
+| `roles` | object | the four built-ins | no | Custom role definitions. Keys are role names; values are arrays of permission strings. **Omitting this block uses the four built-ins** (`viewer`, `maintainer`, `operator`, `admin`) — see `horizon.yaml` for the full grants. Defining the block at all overrides the built-ins entirely; redefine all four if you want to keep them. |
 | `landingByRole` | object | see below | no | Post-login redirect route per role. First role on the user wins. |
 
 ## Built-in roles (used when `roles` is not set)
diff --git a/horizon.example.yaml b/horizon.example.yaml
deleted file mode 100644
index 922b140..0000000
--- a/horizon.example.yaml
+++ /dev/null
@@ -1,286 +0,0 @@
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements.  See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License.  You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# Copy this file to `horizon.yaml` and edit. Hot-reload picks up changes.
-#
-# Env-var interpolation: `${VAR}` or `${VAR:default}` is expanded BEFORE
-# YAML parsing. Use the `:default` form for non-secret values; for
-# secrets prefer the bare `${VAR}` form so a missing env var fails loud
-# instead of silently falling back to a placeholder.
-
-server:
-  host: 127.0.0.1
-  port: 8081
-
-# Layers hidden from the sidebar even when OAP reports them in listLayers.
-# Config-driven — there is no hard-coded hide list. Clear `excluded` to
-# surface every reported layer, or add keys for internal-only layers you
-# don't want on the menu. `reason` is a note for whoever reads this file;
-# it is NOT shown in the UI (an excluded layer simply doesn't appear).
-# Keys are OAP layer keys (UPPER_SNAKE), matched case-insensitively.
-# The defaults below are applied when this block is omitted entirely.
-layers:
-  excluded:
-    - key: FAAS
-      reason: Deprecated.
-    - key: VIRTUAL_GATEWAY
-      reason: Not planned to set up.
-
-oap:
-  # OAP query host (port 12800 by default; GraphQL + /status/*). One URL
-  # because query traffic is load-balanceable — any OAP node can answer.
-  queryUrl: http://127.0.0.1:12800
-  # OAP admin host (port 17128 by default; runtime-rule / dsl-debugging
-  # / inspect / status live here). Single URL — point it at a DNS name
-  # or VIP fronting your OAP cluster. Runtime-rule lists hit it once
-  # (OAP routes cluster-internal); per-node live-debug status uses a
-  # DNS lookup on the hostname to discover all node IPs and probes each.
-  adminUrl: http://127.0.0.1:17128
-  # OAP's Zipkin v2 REST host. Defaults to a standalone port (9412 +
-  # /zipkin) per the upstream Armeria binding. When OAP is configured
-  # to share the GraphQL port (typical for the demo / k8s deploys),
-  # use `<queryUrl>/zipkin` instead.
-  zipkinUrl: http://127.0.0.1:9412/zipkin
-  timeoutMs: 15000
-  # Optional basic-auth credentials for outbound OAP calls.
-  # auth:
-  #   username: skywalking
-  #   password: skywalking
-
-# ────────────────────────────────────────────────────────────────────
-# Authentication
-#
-# Pick ONE backend: `local` or `ldap`. The other block can stay
-# populated for break-glass / future use, but it's IGNORED. If you set
-# `backend: ldap` and leave `auth.local.users` populated, a warning is
-# logged at startup.
-#
-# Bootstrap rule: if `backend: local` and `auth.local.users` is empty,
-# OR `backend: ldap` and `auth.ldap` is missing / `groupMappings` empty,
-# the BFF boots but no login succeeds until auth is configured. There is
-# no "default admin/admin" password.
-# Generate hashes with:   pnpm --filter bff cli:hash
-# ────────────────────────────────────────────────────────────────────
-auth:
-  backend: local
-
-  local:
-    users: []
-    # - username: admin
-    #   passwordHash: "$argon2id$v=19$..."
-    #   roles: [admin]
-
-  # ── LDAP ──────────────────────────────────────────────────────────
-  # Required when `backend: ldap`. Passwords are never stored or read
-  # from the directory — login binds AS the user with their typed
-  # password, and group membership maps to a Horizon role via
-  # `groupMappings` (first match wins, multiple matches union).
-  # ldap:
-  #   url: ldaps://ldap.corp:636
-  #   bindDn: "cn=horizon,ou=services,dc=corp"
-  #   # `${VAR}` (required) or `${VAR:default}` (optional). Leave empty
-  #   # for anonymous service-bind (only works if the directory permits
-  #   # anonymous searches).
-  #   bindPassword: "${HORIZON_LDAP_BIND_PW}"
-  #   userBaseDn: "ou=people,dc=corp"
-  #   # `{username}` is substituted with the typed username (RFC 4515
-  #   # escaped). Use `(sAMAccountName={username})` for AD.
-  #   userFilter: "(uid={username})"
-  #   displayNameAttr: cn
-  #   # `memberOf` reads the attr off the user entry (AD-style);
-  #   # `search` searches `groupBaseDn` for the user's DN (OpenLDAP-style).
-  #   groupStrategy: memberOf
-  #   groupBaseDn: ""        # only used when groupStrategy: search
-  #   memberAttr: member     # only used when groupStrategy: search
-  #   timeoutMs: 5000
-  #   tlsInsecure: false     # set true only for dev with self-signed certs
-  #   groupMappings:
-  #     - group: "cn=horizon-admin,ou=groups,dc=corp"
-  #       role: admin
-  #     - group: "cn=sre,ou=groups,dc=corp"
-  #       role: operator
-  #     - group: "cn=platform,ou=groups,dc=corp"
-  #       role: maintainer
-  #     - group: "*"           # fallback for every authenticated user
-  #       role: viewer
-
-  # ── Break-glass ───────────────────────────────────────────────────
-  # Optional local admin credential honored ONLY when:
-  #   - backend: ldap, AND
-  #   - the LDAP probe is currently failing.
-  # Every successful break-glass login is audited at WARN level. Leave
-  # commented out to disable.
-  # breakGlass:
-  #   username: emergency-admin
-  #   passwordHash: "${HORIZON_BREAK_GLASS_HASH}"
-  #   roles: [admin]
-
-# ────────────────────────────────────────────────────────────────────
-# RBAC: four built-in roles. Verbs are dot-namespaced; `*:read` grants
-# every read across all areas, `area:*` grants every action in one area,
-# `*` grants everything. Routes are gated by a single policy table on
-# the BFF — see `apps/bff/src/rbac/route-policy.ts`.
-# ────────────────────────────────────────────────────────────────────
-rbac:
-  enabled: true
-  roles:
-    # Data catalog + read-only overview dashboards. Deliberately NOT
-    # `*:read` so a viewer can't accidentally see rule definitions,
-    # live-debug sessions, setup screens, or cluster / TTL / config internals.
-    viewer:
-      - metrics:read
-      - alarms:read
-      - traces:read
-      - logs:read
-      - browser-errors:read
-      - inspect:read
-      - topology:read
-      - profile:read
-      - overview:read
-      - infra-3d:read
-
-    # Viewer + platform monitoring (OAP cluster + module inspector).
-    maintainer:
-      - metrics:read
-      - alarms:read
-      - traces:read
-      - logs:read
-      - browser-errors:read
-      - topology:read
-      - profile:read
-      - overview:read
-      - cluster:read
-      - inspect:read
-      - ttl:read
-      - config:read
-      - infra-3d:read
-
-    # Configures observability: dashboards, alarm rules, DSL/OAL,
-    # diagnostics, profiling. Inherits viewer + platform reads so the
-    # operator can verify their edits against live data.
-    operator:
-      - metrics:read
-      - alarms:read
-      - traces:read
-      - logs:read
-      - browser-errors:read
-      - source-map:write
-      - topology:read
-      - profile:read
-      - cluster:read
-      - inspect:read
-      - ttl:read
-      - config:read
-      - overview:read
-      - overview:write
-      - setup:read
-      - setup:write
-      - dashboard:read
-      - dashboard:write
-      - alarm-setup:read
-      - alarm-setup:write
-      - alarm-rule:read
-      - alarm-rule:write
-      - infra-3d:read
-      - rule:read
-      - rule:write
-      - rule:write:structural
-      - rule:delete
-      - rule:debug
-      - live-debug:read
-      - live-debug:write
-      - profile:enable
-
-    admin:
-      - "*"
-  # Where each role lands after login. First role on the user wins.
-  # Cluster status lives under /operate/cluster (it's an operator tool
-  # against OAP, not an admin / RBAC surface); the prior `/admin/cluster`
-  # values 404'd because no route by that name exists.
-  landingByRole:
-    viewer: /
-    maintainer: /operate/cluster
-    operator: /
-    admin: /operate/cluster
-
-session:
-  ttlMinutes: 60
-  cookieName: horizon_sid
-  cookieSecure: false           # set true behind HTTPS
-
-# State files (audit log, setup state, alarm state, wire debug log).
-# Leave the `file:` paths unset and the right location is chosen for you:
-#   • published container image → /data/*    (its writable volume)
-#   • local binary run          → ./horizon-* (relative to the working dir)
-# Set an explicit `file:` under each block ONLY if you need a specific
-# location — and make sure the running process can write it (in the image
-# that means a path under /data, since the non-root `horizon` user cannot
-# write /app).
-
-debugLog:
-  enabled: false
-  maxBodyChars: 8192
-  redactAuthHeaders: true
-
-# JS source maps for the BROWSER-layer "Browser Errors" tab (#6784).
-# Maps de-obfuscate minified error stacks back to original source. They
-# are held in the BFF process memory ONLY — there is no OAP-side storage —
-# so this cache is per-instance and intentionally temporary: uploaded maps
-# are lost on restart and the least-recently-used are evicted once the
-# budget is hit. For durable provisioning, drop .map files into the static
-# `bootMountDir` (Docker/k8s mount) — those are reloaded on demand and
-# survive restarts.
-sourceMaps:
-  enabled: true
-  maxFileBytes: 67108864      # 64 MiB — reject any single .map larger
-  maxTotalBytes: 536870912    # 512 MiB — total in-memory budget (LRU-evicted)
-  maxFileCount: 128           # cap on number of hosted maps
-  # Directory scanned at boot for statically-provisioned .map files. The
-  # published image sets HORIZON_SOURCEMAPS_DIR=/app/sourcemaps; leave empty
-  # to disable the static mount.
-  bootMountDir: ${HORIZON_SOURCEMAPS_DIR:}
-
-# ────────────────────────────────────────────────────────────────────
-# Performance / behavior tuning — how hard the BFF fans queries out to
-# OAP, and the caps that protect storage. OPERATIONAL (per-deployment,
-# hot-reloaded, never published to OAP), unlike dashboard content, which
-# lives in templates. The whole block is optional — defaults equal the
-# built-in values, shown here for reference. Every value is clamped to a
-# hard ceiling; config can lower it, never raise it past that.
-#
-# Node heap: the BFF holds the source-map cache (above) in process memory,
-# so size the container memory limit and `NODE_OPTIONS=--max-old-space-size`
-# to your sourceMaps budget. (--max-old-space-size is a process flag, not a
-# config field — V8 reads it before this file loads.)
-performance:
-  bulk:
-    # Service-map family (topology / instance-topology / deployment /
-    # endpoint-dependency): bulkSize = aliased MQE fragments per OAP
-    # request; concurrency = parallel requests.
-    topology:   { nodeBulkSize: 150, edgeBulkSize: 200, concurrency: 4 }
-    # 3D infrastructure-map metric fan-out (was the 3D template `pipeline`).
-    infra3d:    { metricBulkSize: 6, metricConcurrency: 4, topologyConcurrency: 4, templateConcurrency: 8 }
-    # Per-layer landing metric-column batches.
-    landing:    { bulkSize: 6, concurrency: 8 }
-    # Dashboard widget metric fan-out.
-    dashboard:  { bulkSize: 6 }
-  limits:
-    # Service-map render valve — a larger graph is rejected with a
-    # "narrow the scope" notice rather than drawn unreadably.
-    topologyMaxNodes: 5000
-    topologyMaxEdges: 15000
-    # Max RECORDS per request for each event list (the OAP storage LIMIT)
-    # — not a page count; the UI picker maxes at the same value.
-    maxPageSize: { traces: 100, logs: 100, browserLogs: 100 }
diff --git a/horizon.yaml b/horizon.yaml
new file mode 100644
index 0000000..4da1e8f
--- /dev/null
+++ b/horizon.yaml
@@ -0,0 +1,141 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# ─────────────────────────────────────────────────────────────────────
+# This is the SHIPPED default config. EVERY field below is an env var:
+# `${HORIZON_X:default}` expands BEFORE YAML parsing. So you can run the
+# container with NO mounted file and set only the env vars you care about
+# (image-native), OR copy this to `horizon.yaml`, edit, and mount it.
+#
+#   • String scalars are quoted (`"${X:default}"`) so a value with YAML
+#     metacharacters (`:`, `#`, …) can't break parsing.
+#   • Numbers / booleans are unquoted so they keep their type.
+#   • Lists / objects (users, ldap, roles, excluded, performance, oap.auth)
+#     are UNQUOTED and take a JSON STRING env var — injected inline + parsed.
+#     A `:null` default means "fall through to the built-in default".
+#   • Precedence: env var > this file's `:default` > built-in schema default.
+#   • Secrets (password hashes, ldap bind pw) are env-only — never bake them.
+#
+# Hot-reload picks up file edits; env vars are fixed at process start.
+# ─────────────────────────────────────────────────────────────────────
+
+server:
+  # Bind host/port. The image sets HORIZON_SERVER_HOST=0.0.0.0 so the BFF
+  # is reachable from outside the container (the YAML default 127.0.0.1
+  # would bind container-loopback only).
+  host: "${HORIZON_SERVER_HOST:127.0.0.1}"
+  port: ${HORIZON_SERVER_PORT:8081}
+
+templates:
+  # `live` (default): seed bundled dashboard templates into OAP's
+  # ui_template store at boot, then read/write them via that API.
+  # `readonly`: render templates from the local bundle only — the
+  # ui_template API is never called and the whole config surface is
+  # read-only. OAP's query API (metrics/traces/logs) is still used either
+  # way. Use `readonly` to run standalone against an OAP whose ui_template
+  # admin API is absent or disabled. (Change needs a BFF restart.)
+  mode: "${HORIZON_TEMPLATES_MODE:live}"
+
+oap:
+  # OAP query host (GraphQL + /status/*; default port 12800).
+  queryUrl: "${HORIZON_OAP_QUERY_URL:http://127.0.0.1:12800}"
+  # OAP admin host (runtime-rule / dsl-debugging / inspect / status;
+  # default port 17128). Point at a DNS name / VIP fronting the cluster.
+  adminUrl: "${HORIZON_OAP_ADMIN_URL:http://127.0.0.1:17128}"
+  # OAP Zipkin v2 REST host. Use `<queryUrl>/zipkin` when OAP shares the
+  # GraphQL port (typical for the demo / k8s deploys).
+  zipkinUrl: "${HORIZON_OAP_ZIPKIN_URL:http://127.0.0.1:9412/zipkin}"
+  timeoutMs: ${HORIZON_OAP_TIMEOUT_MS:15000}
+  # Optional MQE host/port override (defaults to the query host). JSON env, e.g.
+  # HORIZON_OAP_MQE='{"host":"mqe.internal","port":12800}'.
+  mqe: ${HORIZON_OAP_MQE:null}
+  # Optional basic-auth for outbound OAP calls. JSON env, e.g.
+  # HORIZON_OAP_AUTH='{"username":"skywalking","password":"skywalking"}'.
+  auth: ${HORIZON_OAP_AUTH:null}
+
+# Layers hidden from the sidebar even when OAP reports them. JSON array of
+# {key, reason}; `:null` keeps the built-in default (FAAS, VIRTUAL_GATEWAY).
+# HORIZON_LAYERS_EXCLUDED='[]' surfaces every reported layer.
+layers:
+  excluded: ${HORIZON_LAYERS_EXCLUDED:null}
+
+# ─────────────────────────────────────────────────────────────────────
+# Authentication. Pick ONE backend: `local` or `ldap`. With `local` and no
+# users (or `ldap` with no group mappings) the BFF boots but no login
+# succeeds until configured — there is no default admin/admin.
+# Generate password hashes with:  pnpm --filter bff cli:hash
+# ─────────────────────────────────────────────────────────────────────
+auth:
+  backend: "${HORIZON_AUTH_BACKEND:local}"
+  # Local users — JSON array, e.g.
+  # HORIZON_AUTH_LOCAL_USERS='[{"username":"admin","passwordHash":"$argon2id$v=19$...","roles":["admin"]}]'
+  local:
+    users: ${HORIZON_AUTH_LOCAL_USERS:[]}
+  # LDAP block (required when backend=ldap) — JSON object, e.g.
+  # HORIZON_AUTH_LDAP='{"url":"ldaps://ldap.corp:636","userBaseDn":"ou=people,dc=corp","groupMappings":[{"group":"*","role":"viewer"}]}'
+  ldap: ${HORIZON_AUTH_LDAP:null}
+  # Break-glass admin, honored ONLY when backend=ldap AND the LDAP probe is
+  # failing; every use is audited at WARN. JSON object or null.
+  breakGlass: ${HORIZON_AUTH_BREAK_GLASS:null}
+
+# RBAC. `roles` maps a role → its verb grants; `landingByRole` is the
+# post-login landing route per role. `:null` keeps the built-in defaults
+# (viewer/maintainer/operator/admin). Override with a JSON object env var.
+rbac:
+  enabled: ${HORIZON_RBAC_ENABLED:true}
+  roles: ${HORIZON_RBAC_ROLES:null}
+  landingByRole: ${HORIZON_RBAC_LANDING_BY_ROLE:null}
+
+session:
+  ttlMinutes: ${HORIZON_SESSION_TTL_MINUTES:60}
+  cookieName: "${HORIZON_SESSION_COOKIE_NAME:horizon_sid}"
+  cookieSecure: ${HORIZON_SESSION_COOKIE_SECURE:false}   # set true behind HTTPS
+
+# State files. The image sets HORIZON_*_FILE=/data/* (its writable volume);
+# a local run defaults to ./horizon-* in the working dir. Set an explicit
+# path only if you need one the running process can write.
+audit:
+  file: "${HORIZON_AUDIT_FILE:./horizon-audit.jsonl}"
+setup:
+  file: "${HORIZON_SETUP_FILE:./horizon-setup.json}"
+alarms:
+  file: "${HORIZON_ALARMS_FILE:./horizon-alarms.json}"
+
+debugLog:
+  enabled: ${HORIZON_DEBUG_LOG_ENABLED:false}
+  file: "${HORIZON_WIRE_LOG_FILE:./horizon-wire.jsonl}"
+  maxBodyChars: ${HORIZON_DEBUG_LOG_MAX_BODY_CHARS:8192}
+  redactAuthHeaders: ${HORIZON_DEBUG_LOG_REDACT_AUTH:true}
+
+query:
+  # Max services a layer landing runs metric MQE for, per request.
+  landingServiceCap: ${HORIZON_QUERY_LANDING_SERVICE_CAP:100}
+
+# JS source maps for the BROWSER-layer "Browser Errors" tab (#6784). Held
+# in BFF process memory only (no OAP storage), per-instance + ephemeral.
+# Drop durable .map files into `bootMountDir` (the image sets it to
+# /app/sourcemaps).
+sourceMaps:
+  enabled: ${HORIZON_SOURCEMAPS_ENABLED:true}
+  maxFileBytes: ${HORIZON_SOURCEMAPS_MAX_FILE_BYTES:67108864}      # 64 MiB
+  maxTotalBytes: ${HORIZON_SOURCEMAPS_MAX_TOTAL_BYTES:536870912}   # 512 MiB
+  maxFileCount: ${HORIZON_SOURCEMAPS_MAX_FILE_COUNT:128}
+  bootMountDir: "${HORIZON_SOURCEMAPS_DIR:}"
+
+# Performance / behavior tuning — BFF→OAP fan-out + storage-protective caps.
+# Operational, hot-reloaded. `:null` keeps the built-in defaults (shown in
+# the docs); override the whole tree with a JSON object env var, e.g.
+# HORIZON_PERFORMANCE='{"bulk":{"dashboard":{"bulkSize":8}}}'.
+performance: ${HORIZON_PERFORMANCE:null}
diff --git a/packages/api-client/src/preflight.ts b/packages/api-client/src/preflight.ts
index c4f61f7..9c471ad 100644
--- a/packages/api-client/src/preflight.ts
+++ b/packages/api-client/src/preflight.ts
@@ -16,17 +16,24 @@
  */
 
 /**
- * Wire shape for `GET /api/preflight` — interrogates OAP admin's
- * `/debugging/config/dump` and reports which OAP modules / SWIP-13
- * selectors are enabled. Drives the admin-port section of the
- * Cluster Status page and the per-page warning headers on admin-host
- * routes (DSL Management, Live Debugger, Dump, OAL viewer, Inspect).
+ * Wire shape for `GET /api/preflight` — a REACHABILITY check of each
+ * OAP admin feature Horizon depends on. Drives the admin-port section
+ * of the Cluster Status page and the per-page warning headers on
+ * admin-host routes (DSL Management, Live Debugger, Dump, OAL viewer,
+ * Inspect, dashboard templates).
+ *
+ * Health = `reachable`, NOT `enabled`. Each feature declares the
+ * relative admin REST path it actually calls; the BFF fires a safe GET
+ * at that path and reports whether the feature responds. A 404 (module
+ * selector off, renamed, or absent in a fork) reads as unreachable —
+ * an honest, release-agnostic signal. `enabled` (the config-dump
+ * prefix) is kept only as an informational "the upstream release
+ * advertises this selector" footnote, never as the health verdict.
  *
  * `adminReachable === false` means the admin host itself is down
- * (network, port not exposed, OAP not started); every module is
- * reported `enabled: false` regardless of selector config. The
- * operator's first move in that case is to fix the network / port
- * exposure, not to flip selectors on.
+ * (network, port not exposed, OAP not started); every feature is then
+ * reported `reachable: false`. The operator's first move is to fix the
+ * network / port exposure, not to flip selectors on.
  */
 
 export interface PreflightModule {
@@ -34,20 +41,36 @@ export interface PreflightModule {
   name: string;
   /** The env var that toggles this module's selector on OAP. */
   envVar: string;
-  /** True when horizon depends on this module being on. */
+  /** True when horizon depends on this module being reachable. */
   required: boolean;
-  /** True iff the dump carries at least one key with this module's prefix. */
+  /** The relative admin REST path the BFF GETs to test reachability. */
+  probePath: string;
+  /**
+   * THE health signal: true iff the safe GET on `probePath` responded
+   * (any status except 404 / 5xx / network error). `null` = not probed
+   * (e.g. ui_template in readonly mode — Horizon never calls it).
+   */
+  reachable: boolean | null;
+  /**
+   * Informational footnote only: the upstream config dump carries a key
+   * under this module's prefix. Release-specific; NOT a health verdict.
+   */
   enabled: boolean;
-  /** What part of horizon breaks when this module is off. */
+  /** What part of horizon breaks when this feature is unreachable. */
   affects: string;
 }
 
 export interface PreflightResult {
   adminUrl: string;
-  /** True iff `/debugging/config/dump` responded 2xx. */
+  /** True iff `/debugging/config/dump` responded 2xx (admin port up). */
   adminReachable: boolean;
   /** Short reason when `adminReachable` is false. */
   adminError?: string;
+  /**
+   * Active template mode. In `readonly` the ui_template feature is not
+   * probed (Horizon serves bundled templates) and its row reads "n/a".
+   */
+  templatesMode: 'live' | 'readonly';
   modules: PreflightModule[];
   /** Total keys in the dump. Diagnostic only. */
   dumpKeyCount: number;
diff --git a/scripts/package.mjs b/scripts/package.mjs
index 7355445..b750d47 100644
--- a/scripts/package.mjs
+++ b/scripts/package.mjs
@@ -30,7 +30,7 @@
  *       node_modules/          — production deps (npm + workspace dists)
  *       bundled_templates/     — layer + overview JSON templates
  *       static/                — built UI (Vite dist)
- *       horizon.example.yaml   — copy-and-edit starting point
+ *       horizon.yaml           — env-driven config (override fields via HORIZON_… env vars)
  *
  * The build:
  *   1. Builds each workspace package under `packages/*` (tsc → dist/).
@@ -102,7 +102,7 @@ cpSync(
   { recursive: true },
 );
 cpSync(resolve(root, 'apps/ui/dist'), resolve(dist, 'static'), { recursive: true });
-cpSync(resolve(root, 'horizon.example.yaml'), resolve(dist, 'horizon.example.yaml'));
+cpSync(resolve(root, 'horizon.yaml'), resolve(dist, 'horizon.yaml'));
 
 step('Done');
 console.log(`
@@ -110,8 +110,8 @@ Target binary: ${resolve(dist, 'server.js')}
 
 Boot it:
 
-    cp horizon.example.yaml horizon.yaml         # configure once
-    HORIZON_CONFIG=./horizon.yaml \\
+    HORIZON_CONFIG=./horizon.yaml \\             # every field is a \${HORIZON_…} env var
+      HORIZON_OAP_QUERY_URL=http://oap:12800 \\  # override only what you need
       HORIZON_STATIC_DIR=./dist/static \\
       node dist/server.js
 
diff --git a/scripts/release.sh b/scripts/release.sh
index 9320107..7b2cf10 100755
--- a/scripts/release.sh
+++ b/scripts/release.sh
@@ -504,7 +504,7 @@ Guide to build the release from source:
  * cd into the extracted directory
  * pnpm install --frozen-lockfile
  * pnpm package
- * node dist/server.js (after copying horizon.example.yaml → horizon.yaml)
+ * node dist/server.js (after copying horizon.yaml → horizon.yaml)
 
 Voting will start now (${VOTE_DATE}) and will remain open for at least
 72 hours. PMC members, please cast your vote.