README: a vibe-coder section (Studio, build, embed) and an agent section (what this repo is for)

For vibe coders: run the Plugin Studio, build one map or all of them (and the automatic copy into a sibling
DX Life site), and embed a map: every map's own embed.script in manifest.json, loaded from DX Life's
public/dx-maps. For agents: the repo builds mobilization maps, and each goal (reach a city, mobilize for
people groups, plan outreach, prayer packets and resources) is mapped to the production maps that serve
it, with the skill, the plugin rules, the landing rules and the freeze on experimental maps.

README.md

@@ -64,6 +64,59 @@ capabilities, three outputs, one shared library, one build.
 | **Shared library, private plugins** — reuse without breaking each other | `bun run check:library-index` |
 | **One agent per plugin, one shepherd, one working `main`** | [agent swarm](#build-it-with-an-agent-swarm) |
 
+## For vibe coders: build, open the Studio, embed a map
+
+**1. Open the Plugin Studio** (every map, live, updating as you or your agent edit):
+
+```bash
+bun install --frozen-lockfile
+bun run dev                     # open the address it prints: that page is the Plugin Studio
+```
+
+**2. Build.** The built maps are already in the repo. After a change, rebuild just that map, or all of them:
+
+```bash
+BUNDLE=<map> bun x vite build   # one map (seconds)
+BUILD_ALLOW=1 bun run build     # every map (~4 min); the output is public/dx-maps/
+```
+
+When the DX Life site's repo sits next to this one (`../doxa-life`), the full build also copies the maps into
+its `public/`. That is the one path set in `vite.doxa-maps-build-config.json` (`dropin.dest`); nothing else on
+your computer is searched. No site there: the step says so and skips. `DOXA_DROPIN=off` turns it off, and
+`bun run dropin` copies on demand.
+
+**3. Embed a map.** Every map has its own embed script: its `embed.script` in `public/dx-maps/manifest.json` (an
+`embed.iframe` too). A snippet is two parts, the map's script and its tag:
+
+```html
+<script src="/dx-maps/doxa-simple-map/doxa-simple-map.js" integrity="sha384-…" crossorigin="anonymous"></script>
+<doxa-map profile-config='{"profile":"doxa-simple-map","assetsBase":"/dx-maps/assets"}'></doxa-map>
+```
+
+On DX Life, the maps are served from its own `public/dx-maps/`, so a page loads `/dx-maps/<map>/<map>.js` and
+places the map's tag. Copy each snippet from the manifest: its `integrity` hash changes with every build. More:
+[the three routes](#where-the-folder-goes-three-routes) and [how a page shows a map](#how-a-page-shows-a-map).
+
+## For agents: what this repo is for
+
+This repo builds **mobilization maps**: maps that help disciples, churches and leaders reach their city and the
+people groups of the world. When you work here, the goal is one of these:
+
+| Goal | The production maps that serve it |
+|---|---|
+| **Reach a city** | Cities with Internet (`cities-internet`); Regions (`regions-dashboard`) and the country map (`country-map`) |
+| **Mobilize for people groups** | Big Picture (`dashboard-plus-grid`); Research Map + Grid (`research-map-plus-grid`) |
+| **Plan outreach** | Gospel Resources (`gospel-resources`): what exists in each language; Regions, by country |
+| **Pray: packets and prayer resources** | UPG-100 (`my-upg-100-list`): prayer packets; Prayer Progress (`doxa-simple-map`) |
+
+- **Start with the skill:** [`skills/plugin-designer`](./skills/plugin-designer) teaches the patterns, the shared
+  library and the checks.
+- **One plugin per folder** in `plugin-designs/`; shared code goes in `library/` only if it stays reusable for
+  every other plugin.
+- **Land on `development`**, one change at a time through the lock, with `bun run gates:pre` passing. `main` is
+  production and moves only on a publish.
+- These 8 maps are in production. The experimental maps are frozen: leave them as they are.
+
 *Click any ▸ to read more. Everything below is folded so you can scroll the pictures first.*
 
 ---