The embed contract, written down for partners

?codes, ?country, ?code and ?view=zero are what a partner puts in an iframe and
never touches again, so they are documented where the other embed material lives —
including the two things that decide whether a link is right: the denominator is
Doxa's 2,107, not the 12,379-group corpus, and a link matching nothing shows an
empty map reading "0 / 2,107" rather than pretending a broken list works.

Also says what the map does NOT promise: no zoom or centre parameter, placement is
approximate, and an unknown parameter is ignored rather than fatal.

documentation/README-embed-gospel-resources.md

@@ -0,0 +1,47 @@
+# Embedding the gospel-resources map
+
+The map's **URL is its interface**. A partner embeds one address in an iframe and never touches it
+again, so every parameter below is a promise kept by a gate
+(`bun run check:embed-contract`), not a convention.
+
+```html
+<iframe src="https://<host>/dx-maps/gospel-resources/resources-map/index.html?codes=kfr,cmn,npi"
+        style="width:100%;height:600px;border:0" title="Gospel access"></iframe>
+```
+
+## The four addresses
+
+| Address | What the reader gets |
+|---|---|
+| `?codes=<iso3,iso3,…>` | Only those languages' people groups, framed on them. Shows `74 / 2,107`, and that count is the button back to the whole map. |
+| `?country=<ISO3>` | That country's sheet open, framed on its groups. The country's own name also works (`?country=India`). |
+| `?code=<iso3>` | The people group's sheet, with its resources. `&name=` and `&country=` disambiguate when a language has many groups. |
+| `?view=zero` | The groups with **nothing found** — the question this map exists for. `?view=gap` is the same view. |
+
+`?provider=maplibre` is not this map's parameter but the whole fleet's: it selects the keyless
+engine, and no map ever substitutes a different one (`bun run check:engine-contract`).
+
+## Bring your own list
+
+The join is **ISO 639-3**, the key every resource in this map is already joined on. A partner's list
+needs no agreement with Doxa's roster — only the codes their own data carries. That is the point:
+this corpus is public so that other lists can stand on it.
+
+Two things to know before you publish a link:
+
+- **The denominator is Doxa's roster.** The research corpus holds 12,379 people groups; this map
+  draws the **2,107** Doxa works, so `?codes=` intersects with those. A code outside the roster
+  draws nothing.
+- **It filters, it never invents.** A link matching none of its codes shows an empty map reading
+  `0 / 2,107`. That is the truth about the link — showing the full map instead would tell you your
+  broken list works.
+
+## What the map does not promise
+
+- **No zoom or centre parameter.** The frame is derived from the pins the link selects, so a link
+  stays correct when the data moves under it.
+- **Placement is approximate.** A dot marks where a *people* is found, not a town or a boundary,
+  and 108 of the placed groups share a coordinate with another group. The sheet says so in the
+  reader's language.
+- **An unknown parameter is ignored, never fatal.** `?country=ZZZ` renders the map, not an error —
+  a partner's typo must not break their page.

documentation/README.md

@@ -14,6 +14,7 @@
 - **[explanation.md](./explanation.md)** — the model in 15 lines.
 - **[architecture/](./architecture/)** — the deep end: full contracts, the per-file catalog.
 - **[README-embed-example.md](./README-embed-example.md)** — the drop-in README used when this bundler is embedded inside a host repo.
+- **[README-embed-gospel-resources.md](./README-embed-gospel-resources.md)** — the gospel map's URL contract for partner embeds: bring your own ISO 639-3 list, one country, one group, or the zero-access view.
 
 Working on the repo: