From dbf31018a32b3e0b9c2f2aa6b3446b7d57f4946e Mon Sep 17 00:00:00 2001
From: doxa-maps <noreply@doxa.life>
Date: Fri, 11 Sep 2026 18:04:58 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20add=20why.md=20=E2=80=94=20problem-firs?=
 =?UTF-8?q?t=20'map=20islands'=20concept=20page=20(Vite/Astro/Stencil=20pa?=
 =?UTF-8?q?ttern);=20wire=20into=20front=20doors=20+=20playground=20link?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                   |  5 +++
 docs/architecture/README.md |  2 +-
 docs/explanation.md         |  3 +-
 docs/reference.md           |  2 +-
 docs/why.md                 | 72 +++++++++++++++++++++++++++++++++++++
 5 files changed, 81 insertions(+), 3 deletions(-)
 create mode 100644 docs/why.md

diff --git a/README.md b/README.md
index 4ce68d256..3ec5484e1 100644
--- a/README.md
+++ b/README.md
@@ -83,10 +83,15 @@ colors, or API with no rebuild.
 
 ## Docs
 
+- **[Why doxa-maps](./docs/why.md)** — the problem, the "map islands" idea, one diagram.
 - **[Tutorial](./docs/tutorial.md)** — build your first map, step by step.
 - **[How-to](./docs/how-to.md)** — task recipes: embed, add a profile, choose a CDN, set tokens.
 - **[Reference](./docs/reference.md)** — file map, config fields, contracts, the `@map` library index.
 - **[Explanation](./docs/explanation.md)** — the short "what it is".
+- **[Architecture](./docs/architecture/)** — the deep end: contracts, catalogs, wiring.
+
+**Try it live:** `bun run dev` opens the staging playground — every map, clickable, with a
+paste-ready embed snippet for each.
 
 Contributors: see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.
 
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 23c938e3d..a5151b6d6 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -13,5 +13,5 @@ when a simple doc says *"full contract in architecture/…"*, this is where it p
 | [app-wrappers.md](./app-wrappers.md) | the SPA shell / sidebar `nav.js` contract |
 | [poster-generation.md](./poster-generation.md) | the poster/preview generator pipeline |
 
-Simple docs: [../tutorial.md](../tutorial.md) · [../how-to.md](../how-to.md) ·
+Simple docs: [../why.md](../why.md) · [../tutorial.md](../tutorial.md) · [../how-to.md](../how-to.md) ·
 [../reference.md](../reference.md) · [../explanation.md](../explanation.md)
diff --git a/docs/explanation.md b/docs/explanation.md
index dc5837c96..34bf1caba 100644
--- a/docs/explanation.md
+++ b/docs/explanation.md
@@ -8,7 +8,8 @@ any host unchanged — it runs standalone, embedded in a site's `public/` folder
 another platform, no modifications. Same build → embed one map, compose several into a
 lazy-loaded SPA, or wrap a Capacitor mobile app.
 
-That's the model. For the practical docs:
+That's the model. For the story of *why* it's shaped this way, read **[why.md](./why.md)**.
+For the practical docs:
 
 - **[tutorial.md](./tutorial.md)** — build your first map
 - **[how-to.md](./how-to.md)** — do a specific task
diff --git a/docs/reference.md b/docs/reference.md
index 1e698c1cf..d41be41bb 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -2,7 +2,7 @@
 
 Look-up tables and contracts for doxa-maps. For learning, see the
 **[tutorial](./tutorial.md)**; for tasks, **[how-to.md](./how-to.md)**; for the *why*,
-**[explanation.md](./explanation.md)**.
+**[why.md](./why.md)**; for the short "what it is", **[explanation.md](./explanation.md)**.
 
 `doxa-maps` is a Vite bundler: **one shared library, N independent embeddable bundles.** Each
 bundle is a single self-contained `.js` file that registers a custom HTML element
diff --git a/docs/why.md b/docs/why.md
new file mode 100644
index 000000000..9443cd85e
--- /dev/null
+++ b/docs/why.md
@@ -0,0 +1,72 @@
+# Why doxa-maps
+
+## The problem
+
+You built a good map. Now ten partner organizations want it on *their* websites — one runs
+WordPress, one runs Nuxt, one is a plain landing page, one is a link-dashboard like Start.me.
+The usual answers are all bad:
+
+- **Rebuild the map for each site** — ten codebases to keep in sync.
+- **Give everyone an iframe** — clunky, hard to style, another server to run.
+- **Ship a framework widget** — now every host must adopt your framework and your build step.
+
+And when the data or the design changes, you get to do it ten times.
+
+## The answer: map islands
+
+doxa-maps builds each map into a **self-contained island** — one `.js` file that registers a
+standard HTML element. The host page drops it in like an image. It carries its own Vue, its own
+CSS, its own logic; the host needs **no framework and no build step**.
+
+```
+   A PARTNER'S PAGE (theirs — any stack, or none)
+   ┌───────────────────────────────────────────────┐
+   │  their header                                  │
+   │  their text …                                  │
+   │  ┌─────────────────────┐                       │
+   │  │  <doxa-map>          │ ← your island:        │
+   │  │   pins · legend ·    │   one <script>,       │
+   │  │   search · share     │   self-contained      │
+   │  └─────────────────────┘                       │
+   │  their footer                                  │
+   └───────────────────────────────────────────────┘
+        ten sites, same island, one build
+```
+
+Change the map once, rebuild once — every site that embeds it updates, because they all load the
+same file from your CDN.
+
+## A bundler, not a framework
+
+doxa-maps is a **build-time tool**. What it outputs is the standard — plain
+[web components](https://developer.mozilla.org/docs/Web/API/Web_components) — so the maps keep
+working in any host that can render HTML, today and after any framework fashion changes. Hosts
+never install anything from us; they paste two tags.
+
+## JAMstack: the map is static, the wiring is runtime
+
+Each island is a static file, but everything it *talks to* is a runtime setting read from the
+page (`profile-config`, `window.MAP_APP_API_URL`): point it at a different API, different data,
+a different Mapbox token — even a different map engine (Mapbox ↔ MapLibre) — with **no rebuild**.
+That's the JAMstack trade: prebuild the app, decide the connections at load time.
+
+## One build, three products
+
+The same islands compose three ways — this is why there's one bundler, not three tools:
+
+1. **Embeds** — each island on partner sites, docs, dashboards.
+2. **A SPA** — several islands in one lazy-loaded layout = a full map site.
+3. **A mobile app** — Capacitor wraps the same built folder into Android/iOS.
+
+## Prior art, honestly
+
+None of the pieces are ours: web components are a browser standard, JAMstack is a movement,
+Vite does the bundling, the islands idea comes from the wider frontend world (Jason Miller,
+Katie Sylor-Miller; popularized by Astro). doxa-maps' contribution is small and deliberate —
+one shared map library, N independent islands, one build.
+
+---
+
+*What it is: [explanation.md](./explanation.md) · learn: [tutorial.md](./tutorial.md) · tasks:
+[how-to.md](./how-to.md) · lookup: [reference.md](./reference.md) · the deep end:
+[architecture/](./architecture/)*