README: map-cruncher hero, deploy certification shots, repo tree

README.md

@@ -1,5 +1,24 @@
 # doxa-maps — one build, maps that embed everywhere
 
+> **The map cruncher.** Many hand-built maps go in; one shared library, one repo and one build
+> come out — and every map fans out to five deployment targets from the same artifacts.
+>
+> ```text
+>  map · map · map · map · map · map · map        (7 production maps, once 7 codebases)
+>    \    \    |    |    |    /    /
+>     +----- plugin-designs/ ------+              one folder per plugin, free zone
+>                  |
+>            library/ (@map)                      shared, parameterized, high-bar zone
+>                  |
+>             ONE bun run build
+>                  |
+>           doxa-maps/  (drop-anywhere tree: bundles + leaf pages + manifest.json)
+>            /     |      \        \       \
+>        iframe  JS-embed  mobile  WordPress  desktop
+>        (proven) (proven)  (built)  (built)   (built)
+> ```
+
+
 **A Vite bundler that turns each map into a self-contained web component.** Write a map in
 `plugin-designs/<your-map>/`, run one build, and get a folder you can drop on any host — iframe it,
 script-embed it, wrap it as a mobile app, or open every map at once as one SPA.
@@ -104,6 +123,17 @@ Android SDK for method 2, a live WordPress for method 4, and a GUI (this box is
 
 Methods **1 and 3 are the two proven-live paths.** If you need a map on a site today, use one of those.
 
+Both were **certified cross-origin on 2026-09-24** — the entire capability-5 app, embedded on a
+foreign host page, every inner plugin riding along (prove-the-whole = prove-the-parts):
+
+| Method 1 — iframe on a host site | Method 3 — JS embed on a host site |
+|----------------------------------|-------------------------------------|
+| ![The cap-5 app inside a host page iframe](documentation/readme-images/deploy1-iframe-hostsite.png) | ![The cap-5 app JS-embedded on a host page](documentation/readme-images/deploy3-js-embed-hostsite.png) |
+
+> For a JS embed on another site the host page sets `window.MAP_TOKEN` (nested elements read it)
+> and the serving layer must send `Access-Control-Allow-Origin: *` — the tree is fetched
+> cross-origin by `manifest.json`-composed surfaces.
+
 The full per-method command matrix, with every prerequisite, is in
 **[documentation/README-SECTION-3-cli-commands.md](./documentation/README-SECTION-3-cli-commands.md)**.
 
@@ -142,6 +172,29 @@ runs on it yet).
 
 ---
 
+## The repo at a glance
+
+```text
+doxa-maps/
+├── plugin-designs/          YOUR maps live here — one folder per plugin (the FREE zone).
+│   ├── doxa-maps-spa/       the capability-5 app (nests everything below)
+│   ├── dashboard-plus-grid/ capability-4 composite: dashboard + people-groups grid
+│   ├── my-upg-100-list/     capability-4: UPG-100 lists + poster wall + map
+│   ├── doxa-simple-map/     capability-2: one root.vue, three preset maps
+│   └── template-bundle/     copy this to start a new plugin
+├── library/                 the SHARED zone (@map) — reusable, parameterized only.
+│   │                        A change here reaches EVERY bundle: high bar, see
+│   │                        documentation/contributing/.
+│   ├── components/          map controls, legends, search, poster, detail panels
+│   ├── composables/         useMapInstance, shadow styles, print-in-place, retry
+│   └── styles/ colors/ data/  style registry, palettes, lookup tables
+├── data/                    the public datasets the maps ship with
+├── documentation/           tutorial · how-to · reference · explanation + architecture
+├── internal/                the build generator + the verification gates
+└── public/doxa-maps/        the BUILD OUTPUT — the drop-anywhere tree (bundles,
+                             leaf pages, manifest.json). What gets served + embedded.
+```
+
 ## 3. The Plugin Studio
 
 ★ **This is where you work — and the keyword is INTEROPERABILITY.**