Trial state of 29 Oct 2026: ATOMA reader setup, app dashboards, embedding notes

Baseline before the clean-up (PD-13): the PD-11 reader setup and the PD-12 app
dashboards as they ran on the local stack, uncommitted until now. Not deployed,
not independently reviewed.

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

petrolyst-insights/README.md

@@ -14,9 +14,12 @@ and where it runs lives in `stacks/`, `traefik/`, `deploy/` and `host/`.
 | Path | What it is | In the image at |
 |---|---|---|
 | `superset_config.py` | Keycloak sign-in, role mapping, proxy and cookie settings, Redis caches, theme and chart palettes | `/app/pythonpath/` |
-| `petrolyst_security.py` | `PetrolystSecurityManager`: user info and roles from the Keycloak ID token, `/login/` straight to Keycloak, `/logout/` through Keycloak | `/app/pythonpath/` |
-| `assets/branding/` | logos (full colour and white), favicons, app icons | `/app/superset/static/assets/branding/`, served at `/static/assets/branding/…` |
-| `patches/` | runtime patches, `fix_*.py` with `--verify` (see its README); empty at start | `/app/patches/petrolyst/`, applied during the build |
+| `petrolyst_security.py` | `PetrolystSecurityManager`: user info and roles from the Keycloak ID token, `/login/` straight to Keycloak, `/logout/` through Keycloak; takes the reader rules | `/app/pythonpath/` |
+| `petrolyst_reader.py` | readers ("ATOMA Reader"): reach only dashboards granted to the role, own nothing, get no SQL; land on the ATOMA dashboard; `register` is `FLASK_APP_MUTATOR` | `/app/pythonpath/` |
+| `templates/` | `head_custom_extra.html`: loads `reader.css` for readers on every page | `/app/pythonpath/templates/` |
+| `roles/` | `atoma_reader.py`: the role "ATOMA Reader" with exactly its permissions, run by `superset-init`; `atoma_guest.py`: the role "ATOMA Guest" for the Petrolyst app's embedded dashboards, run by hand (see "Embedding") | `/app/petrolyst-roles/` |
+| `assets/branding/` | logos (full colour and white): the wordmark alone for the navbar, and the stacked logo; favicons, app icons; `reader.css`; ATOMA's logo for the fleet map | `/app/superset/static/assets/branding/`, served at `/static/assets/branding/…` |
+| `patches/` | runtime patches, `fix_*.py` with `--verify` (see its README): `fix_redact_query_for_readers.py` | `/app/patches/petrolyst/`, applied during the build |
 | `dashboards/` | exported dashboards and import scripts (see its README) | not in the image |
 
 How the image consumes this folder: `stacks/fuel-monitoring/compose.yaml` passes it to the build
@@ -51,10 +54,34 @@ On the server they come from `/opt/petrolyst/secrets/` (see the deployment READM
   | `superset-admin` | Admin |
   | `superset-editor` | Alpha |
   | `superset-viewer` | Gamma |
+  | `atoma-reader` | ATOMA Reader: the ATOMA dashboard only, read-only (SPEC.md §6) |
   | none | Public (no permissions) |
 
 - `DASHBOARD_RBAC` is on: a viewer sees a dashboard once an admin adds the Gamma role (or a
   custom one) to it.
+- `FILTERBAR_CLOSED_BY_DEFAULT` is on: a dashboard's filter column opens collapsed, a narrow
+  strip with an expand button; `?expand_filters=true` opens it from a link.
+
+## Embedding (local trial only)
+
+The Petrolyst app (PD-12, petrolyst-platform `app/` and `services/app/`) shows dashboards inside
+its Insights lens with Superset guest passes. This is switched on **only in the local scratch
+stack** (`.local/fmdb-scratch`); `superset_config.py` here leaves it off, and loads without the
+guest secret.
+
+- The scratch stack's `superset_config_local.py` turns on `EMBEDDED_SUPERSET`, names the guest
+  role `GUEST_ROLE_NAME = "ATOMA Guest"`, reads the signing secret with
+  `_read_secret("superset_guest_token_secret")` and expects the audience `petrolyst-app`. The
+  app service signs the guest passes itself with the same secret.
+- `roles/atoma_guest.py` gives "ATOMA Guest" the same permissions as "ATOMA Reader". Which
+  dashboard a guest sees comes from the pass, not the role. It is not in `init.sh`; run it once,
+  and again whenever the permissions in `atoma_reader.py` change:
+
+      docker exec <superset> /app/.venv/bin/python /app/petrolyst-roles/atoma_guest.py
+
+- The app's dashboards and their embedding ids: `dashboards/README.md`.
+
+Production embedding is an open point of PD-12 (`.context/design-decisions.md`).
 
 ## Look and feel