README: the 7 production maps up front, one capabilities x deploy table, the library tree and rule

- A gallery of the seven production maps (Big Picture, Simple Research,
  Regions, UPG-100 List, Prayer Progress, Cities with Internet, Gospel
  Resources) plus the Research Gallery, each shot from its own standalone page
  after its map finished loading. Five new shot definitions in readme-shots.
- One 5 x 5 table: every capability ships every way (iframe, mobile and JS
  embed today; WordPress and desktop proven, not yet in production).
- The "map cruncher" converge/diverge picture, folded.
- Repository layout shows the plugin-designs and shared library trees, and a
  folded "plugin or library?" section states the rule: write your app in its
  own plugin; put code in the library only if it is reusable and parameterized.
- Stale shots retaken from the latest builds.
Closes the README parts of DOCS-README-FOR-A-VISIONARY and BUILD-README-COMPLETE-HANDOFF.

README.md

@@ -24,6 +24,58 @@ capabilities, five deployment methods, one shared library, one build.
 
 ---
 
+## The 7 production maps
+
+**Seven maps DX uses today** — each one a plugin you can embed on its own, and all seven together in
+the Research Gallery.
+
+<table>
+<tr>
+<td width="25%" valign="top"><img src="documentation/readme-images/prod-big-picture.png" alt="Big Picture"><br><b>Big Picture</b><br><sub>the whole research dashboard: filters, map, charts, people groups</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/prod-simple-research.png" alt="Simple Research"><br><b>Simple Research</b><br><sub>the research map with the people-groups grid, made for phones</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/prod-regions.png" alt="Regions"><br><b>Regions</b><br><sub>every region and its countries, then a dashboard per region</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/cap4-upg100-mfe.png" alt="UPG-100 List"><br><b>UPG-100 List</b><br><sub>prayer lists of 100 people groups, with posters to print</sub></td>
+</tr>
+<tr>
+<td width="25%" valign="top"><img src="documentation/readme-images/cap2-prayer.png" alt="Prayer Progress"><br><b>Prayer Progress</b><br><sub>where prayer is happening, and where it is still needed</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/prod-cities-internet.png" alt="Cities with Internet"><br><b>Cities with Internet</b><br><sub>internet access where unreached people groups live</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/prod-gospel-resources.png" alt="Gospel Resources"><br><b>Gospel Resources</b><br><sub>which people groups have scripture, film or audio — and which have nothing</sub></td>
+<td width="25%" valign="top"><img src="documentation/readme-images/cap5-doxa-maps-spa.png" alt="Research Gallery"><br><b>Research Gallery</b><br><sub>all seven in one app — capability 5</sub></td>
+</tr>
+</table>
+
+### Every capability ships every way
+
+| Capability | Example | iframe | Mobile app | JavaScript embed | WordPress / Disciple Tools | Desktop |
+|---|---|:-:|:-:|:-:|:-:|:-:|
+| **5 — app shell** | Research Gallery | ✅ | ✅ | ✅ | 🧪 | 🧪 |
+| **4 — composite** | UPG-100 List | ✅ | ✅ | ✅ | 🧪 | 🧪 |
+| **3 — multi-view** | research map | ✅ | ✅ | ✅ | 🧪 | 🧪 |
+| **2 — presets** | Prayer Progress | ✅ | ✅ | ✅ | 🧪 | 🧪 |
+| **1 — single element** | all people groups | ✅ | ✅ | ✅ | 🧪 | 🧪 |
+
+<sub>✅ works today · 🧪 proven, not yet in production. Every plugin builds into the same folder, and that folder is what all five methods ship — so a capability never limits where a plugin can go.</sub>
+
+<details>
+<summary><b>How one build becomes five ways to ship — the "map cruncher"</b></summary>
+
+```text
+ map · map · map · map · map · map · map        many maps, each once its own codebase
+   \    \    |    |    |    /    /
+    +----- plugin-designs/ ------+              one folder per plugin — the free zone
+                 |
+           library/ (@map)                      shared, reusable pieces — the high bar
+                 |
+            ONE build step
+                 |
+          public/doxa-maps/                     one drop-anywhere folder + manifest.json
+           /     |      \        \              iframe  mobile  JS embed  WordPress  desktop
+```
+
+</details>
+
+---
+
 ## The 5 plugin capabilities
 
 A capability is **how much a plugin nests**, from one element (1) to an app of apps (5). Every
@@ -429,14 +481,45 @@ The studio is a plugin like any other: `plugin-designs/plugin-studio/plugin-stud
 ## Repository layout
 
 ```text
-plugin-designs/   YOUR maps — one folder per plugin, a free zone
-library/          the SHARED toolkit (layouts, components, composables) — a high bar
-public/doxa-maps/ the build output: the drop-anywhere folder + manifest.json
-deployment/       mobile (Capacitor) · WordPress · desktop (Tauri)
-internal/         the build and its checks
-documentation/    tutorial · how-to · reference · architecture — start at documentation/README.md
+doxa-maps/
+├── plugin-designs/            YOUR maps — one folder per plugin (the free zone)
+│   ├── doxa-maps-spa/         the Research Gallery (capability 5)
+│   ├── plugin-studio/         the Plugin Studio (capability 5)
+│   ├── my-upg-100-list/       UPG-100 List (capability 4)
+│   ├── doxa-simple-map/       Prayer Progress and its presets (capability 2)
+│   ├── all-people-groups/     a single map (capability 1)
+│   └── template-bundle/       copy this to start a new plugin
+│       ├── template-map-a.vue     the map itself
+│       ├── index.js               registers its HTML tag
+│       ├── index.html             a preview page
+│       └── src/                   private pieces only this plugin uses
+├── library/                   the SHARED toolkit, imported as @map (the high bar)
+│   ├── layouts/               VerticalTabsLayout, StackLayout — how composites compose
+│   ├── components/            legends, map controls, search, posters, detail panels
+│   ├── composables/           map instance, data, layers, shared helpers
+│   ├── colors/ styles/        colour strategies and the house style
+│   ├── i18n/locales/          the 11 languages
+│   └── data/ api/             lookup tables and data sources
+├── public/doxa-maps/          the BUILD OUTPUT — the drop-anywhere folder + manifest.json
+├── deployment/                mobile (Capacitor) · WordPress · desktop (Tauri)
+├── internal/                  the build and its checks
+└── documentation/             tutorial · how-to · reference · architecture
 ```
 
+<details>
+<summary><b>Where your code goes — a plugin, or the shared library?</b></summary>
+
+- **Write your app in `plugin-designs/<your-map>/`.** On the build step it becomes its own plugin in
+  the output folder — its own embeddable app. Nothing you do there can break anyone else's map.
+- **Only put something in `library/` if it is genuinely reusable *and* parameterized** — built so
+  other maps can use it with their own settings. The library is shared by every map, so every edit
+  there can break every map: it is a high bar. Keep anything specific to one map inside that map's
+  own folder.
+- The full contribution guide: [documentation/CONTRIBUTING.md](./documentation/CONTRIBUTING.md) ·
+  every reusable piece you can import: [documentation/reference-library-index.md](./documentation/reference-library-index.md).
+
+</details>
+
 > **Maps should be open source, run everywhere, and multiply.** One build makes each map a
 > self-contained file for your site, your partners' sites and a phone. The Plugin Studio is where
 > you compose them into something bigger.

documentation/readme-images/shot-bundles.json

@@ -1,23 +1,23 @@
 {
  "cap1-single-element": {
   "bundle": "all-people-groups",
-  "sha256": "312b3a0f64b0842b498ae8c0c88491a9225c353a60c0420e05ac18fa0333a0a5"
+  "sha256": "5f9c52ba3d64b0557562c0302311ec45922c62afa2c35c3ed9222e1b112b8ee0"
  },
  "cap2-adoption": {
   "bundle": "doxa-simple-map",
-  "sha256": "95ab02edf30ab19b1637238bb50f580286daa2808fbcb43478dbb0c3d0115d95"
+  "sha256": "e86de756cd2da00970d29f01fa1d85c63b9573369ded1907461c060063771b2f"
  },
  "cap2-engagement": {
   "bundle": "doxa-simple-map",
-  "sha256": "95ab02edf30ab19b1637238bb50f580286daa2808fbcb43478dbb0c3d0115d95"
+  "sha256": "e86de756cd2da00970d29f01fa1d85c63b9573369ded1907461c060063771b2f"
  },
  "cap2-prayer": {
   "bundle": "doxa-simple-map",
-  "sha256": "95ab02edf30ab19b1637238bb50f580286daa2808fbcb43478dbb0c3d0115d95"
+  "sha256": "e86de756cd2da00970d29f01fa1d85c63b9573369ded1907461c060063771b2f"
  },
  "cap3-monolithic-research": {
   "bundle": "doxa-research-map",
-  "sha256": "7e3637a635faf8223488a4bc21c1f308c5b3ea94fa6c80d5f1560a04ef7ec9cb"
+  "sha256": "e65c82492c8eea2eecefcec522367dddded890442a7a96f03e224b3128450e6f"
  },
  "cap4-upg100-list": {
   "bundle": "my-upg-100-list",
@@ -33,14 +33,34 @@
  },
  "cap5-doxa-maps-spa": {
   "bundle": "doxa-maps-spa",
-  "sha256": "e24edf74f5609549b8d83250ebef269f3d6a00423cd3ca28b9a86e23bfba8e91"
+  "sha256": "39d4d92d343740eb6ab9861897f4420010511149941a2414677a2ce7dd7afc65"
  },
  "cap5-plugin-studio": {
   "bundle": "plugin-studio",
-  "sha256": "fee321fdfd05fc83567987c682f826f890cbf76722d9a94290335f2228b9dd61"
+  "sha256": "4d3910b06d55c7fccdba7102be4f9420a0e1368efd1695a6abaf12442b4fcda0"
  },
  "deploy2-mobile-upg100": {
   "bundle": "my-upg-100-list",
   "sha256": "57dc358c76f736f5c1b01afe57b3f722e08a1620143ca7f72b2d83133b43f86d"
+ },
+ "prod-big-picture": {
+  "bundle": "dashboard-plus-grid",
+  "sha256": "3c1fc9c4af52752e545365676d630e9dfee3a5cd67018ca5181d499304742f61"
+ },
+ "prod-cities-internet": {
+  "bundle": "cities-internet",
+  "sha256": "6d7afee32e5d96007a9ec5582cf89f64697da6b9e0ff8e7712a27dcbb721513f"
+ },
+ "prod-gospel-resources": {
+  "bundle": "gospel-resources",
+  "sha256": "02465fd9ec6101bc37b81960cfdf3dd3cc714cc6730bf8755c585e83f2cc81db"
+ },
+ "prod-regions": {
+  "bundle": "regions-dashboard",
+  "sha256": "558dfe17b1ca477aa8d7acd8a75fb0db1fe4675633808fb68efc0a98617e8e77"
+ },
+ "prod-simple-research": {
+  "bundle": "research-map-plus-grid",
+  "sha256": "458139bb4b1da0e79fefeb3c671b78d81da4ef832e411e54789915ca07007ee7"
  }
 }

internal/readme-shots.mjs

@@ -366,6 +366,15 @@ virtualPages.set('/__readme-iframe-host.html', `<!doctype html>
 await shot('deploy1-iframe', '/__readme-iframe-host.html',
   { vp: { width: 1000, height: 700 }, wait: 11000, countFrames: true, mapboxReferer: false })
 
+// ---- THE 7 PRODUCTION MAPS: one shot each, for the README's opening gallery ----
+// Each is the plugin's own standalone leaf page — the same element the Research Gallery nests.
+// (UPG-100 List and Prayer Progress reuse cap4-upg100-mfe and cap2-prayer.)
+await shot('prod-big-picture', '/doxa-maps/dashboard-plus-grid/dashboard-plus-grid/index.html', { wait: 10000, minElements: 300 })
+await shot('prod-simple-research', '/doxa-maps/research-map-plus-grid/research-map-plus-grid/index.html', { wait: 10000, minElements: 200 })
+await shot('prod-regions', '/doxa-maps/regions-dashboard/regions-mfe/index.html', { wait: 10000, minElements: 100 })
+await shot('prod-cities-internet', '/doxa-maps/cities-internet/connectivity-map/index.html', { wait: 10000, minElements: 60 })
+await shot('prod-gospel-resources', '/doxa-maps/gospel-resources/resources-map/index.html', { wait: 10000, minElements: 100 })
+
 // ---- DEPLOY2: mobile — the UPG-100 list as the phone app ----
 // The mobile example is UPG-100 (ruled 2026-09-24; Simple Research was retired as the example because
 // it was never built for phones). Shot once its owner marked the phone layout ready at 88a566f: