From 6785dd826b229925f9ad0776a7ac1757d5e7b91f Mon Sep 17 00:00:00 2001
From: doxa-maps <noreply@doxa.life>
Date: Fri, 11 Sep 2026 17:43:48 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20README=20leads=20with=20plain-words=20e?=
 =?UTF-8?q?xplainer=20=E2=80=94=20bundler,=20bundles,=20elements,=20lean/t?=
 =?UTF-8?q?ree-shaken,=20embed=20anywhere,=20SPA,=20JAMstack=20hot-swap?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 47 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 35 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index f5a8f1d5b..dd0e08aa7 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,43 @@
 # doxa-maps
 
-**A portable bundler that generates JAMstack maps that embed on all your partner sites.**
+**A bundler that turns your maps into small embeddable pieces you can drop onto any website.**
 
 > ### ✨ New here, and you don't write code?
 > You can build real, embeddable maps by **describing them to an AI coding agent** — no
 > programming required. Start with the friendly, zero-jargon guide:
 > **[docs/tutorial.md](./docs/tutorial.md)**.
 
+## In plain words
+
+**What a bundler is.** It's a tool that takes your map code and packages it into a small,
+ready-to-use file. You write the map once; the bundler produces the shippable piece.
+
+**What it outputs.** Plain `.js` files in the `public/` folder — one per bundle. That's it.
+No server, no build step on anyone else's side. Serve the folder from anywhere and the maps work.
+
+**What a bundle is.** A self-contained web component — a custom HTML tag like `<my-map>`. You add
+one `<script>` and drop the tag on a page. It carries everything it needs, so it runs on any site,
+in any framework, or in none.
+
+**One bundle can hold several maps.** A single bundle can define more than one element
+(`<my-map>`, `<coverage-map>`, …). One file, many maps — fewer things to load and manage.
+
+**The bundles are lean.** The build is tree-shaken: only the code a map actually uses gets
+included, unused code is dropped. Small files, fast loads — which matters when a map embeds on
+someone else's page.
+
+**Embed on other people's websites.** Because each map is just a tag, you can put your maps on a
+partner's or customer's site — or in any tool that accepts an embed, like Start.me, Notion, a CMS,
+a landing page. Same map, many places. Write it once, embed it everywhere.
+
+**Build a whole app (SPA), not just single maps.** Bundle several elements into one layout and you
+get a single-page app made of your maps — lazy-loaded so it stays fast. So the same pieces are both
+standalone embeds *and* the building blocks of a full site.
+
+**They're JAMstack, so the API is hot-swappable.** The map is static; the data/service it talks to
+is a runtime setting, not baked in. You can point a map at a different API — or swap the map engine
+itself (Mapbox ↔ MapLibre) — by changing config, no rebuild. Portable and future-proof.
+
 ## Quickstart
 
 Bun is required (`bun.lock` is the committed lockfile — install from <https://bun.sh>).
@@ -32,23 +63,15 @@ anywhere and the bundles are embeddable from it.
 ```
 
 The bundle is a plain `<script>` web component — the host page needs no build step and no
-framework. `profile-config` is read at runtime, so the same bundle re-points at different data
-or colors with no rebuild.
-
-## Run it in your site, share it to partners — same map, many places
-
-Two levels. The **maps** are web-component / iframe embeds you drop on any partner site with no
-build step on their end. The **bundler** is self-contained: it runs standalone, or drops inside
-a host repo and builds in place — so you own and vendor the whole thing, and choose where the
-built maps are served from (your own site, GitHub/jsDelivr, or any CDN). One map runs in your
-own site *and* embeds on your partner sites.
+framework. `profile-config` is read at runtime, so the same bundle re-points at different data,
+colors, or API with no rebuild.
 
 ## Docs
 
 - **[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 architecture and why it's shaped this way.
+- **[Explanation](./docs/explanation.md)** — the short "what it is".
 
 Contributors: see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.