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/dashboards/README.md

@@ -1,8 +1,52 @@
 # dashboards/
 
-Exported Superset dashboards and the operator scripts that import them. Not baked into the
-image, so changes here do not rebuild or restart Superset. Empty until the first fuel
-dashboards exist.
+Superset dashboards as code and the operator scripts that import them. Not baked into the
+image, so changes here do not rebuild or restart Superset.
+
+- `atoma/`: the ATOMA dashboard, with a Map tab (the fleet map) and an Insights tab (one site's
+  details), shown to readers as a lens switch in the navbar. `SPEC.md` is
+  the design; `build_bundle.py` generates the import bundle and `import_bundle.py` imports it
+  (overwriting the objects the bundle defines). `dashboard.css` is the dashboard's own CSS,
+  which the bundle carries.
+
+  The Fleet tab is an iframe of the fleet-map view from the petrolyst-platform repository. It
+  needs that view and its read service served on Superset's own origin under `/views`, and the
+  image's `superset_config.py` with the iframe setting (SPEC.md §6). Without them the tab stays
+  empty, and the Site details tab works as before.
+
+  Build and import:
+
+      docker cp atoma/import_bundle.py fuel-monitoring-superset-1:/tmp/
+      docker exec fuel-monitoring-superset-1 /app/.venv/bin/python /tmp/import_bundle.py --show-database
+      python3 atoma/build_bundle.py --database-uuid <printed uuid> --out atoma-dashboards.zip
+      docker cp atoma-dashboards.zip fuel-monitoring-superset-1:/tmp/
+      docker exec fuel-monitoring-superset-1 /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip --user <username>
+
+  Exit status 2 means a dataset's columns differ from its view: regenerate `atoma/columns.tsv`
+  (command in its header), rebuild and import again.
+
+  The import attaches the role "ATOMA Reader" to the dashboard (a bundle cannot carry roles),
+  so the role must exist first: `superset-init` creates it (`petrolyst-insights/roles/`). The
+  Fleet tab shows ATOMA's logo from `petrolyst-insights/assets/branding/atoma_logo.svg`, in the
+  image.
+
+  An import never deletes. On an instance that still has the two dashboards from before
+  28 Oct 2026 ("ATOMA - Sites" and "ATOMA - Site Detail") and their charts M1, M3, M4 and M5,
+  delete those by hand after importing.
+
+  The bundle also carries the Petrolyst app's dashboards (PD-12, SPEC.md §10): `atoma-overview`
+  (fleet totals) and `atoma-site` (one site, its four sections as tabs; it replaced
+  `atoma-site-summary`, `-fuel`, `-runtime` and `-baseline` on 29 Oct: delete those by hand
+  where they exist).
+  They get no role; the app shows them with guest passes (see "Embedding" in the parent
+  README; local stack only). Add `--embedded-out FILE --embed-domain <app origin>` to the
+  import to make them embeddable from the app's origin; FILE then receives
+  `{slug: embedding id}` for the app service. The ids stay the same across imports. Local
+  stack:
+
+      docker exec fmdb-scratch-superset /app/.venv/bin/python /tmp/import_bundle.py /tmp/atoma-dashboards.zip \
+          --user admin --embedded-out /tmp/embedded-dashboards.json --embed-domain http://127.0.0.1:8098
+      docker cp fmdb-scratch-superset:/tmp/embedded-dashboards.json <Petrolist>/.local/fmdb-scratch/
 
 Export from a running instance (inside the container, as the server's deploy user):