From dx-maps' measurement on development 17d1a07cf; docs only.
Required, because the README contradicted the final page layout (/research shows the research map by
itself, with a link to /deep-research; /deep-research holds the gallery):
- The drop-in paragraph said DX Life's /research is filled with the Research Gallery. It now says the
drop-in copies the folder into public/dx-maps, and /research shows the research map with a link to
/deep-research, which holds the gallery as Deep Research.
- The JavaScript-embed section:
- heading, lead and "one embed replaces the research map" now describe /deep-research;
- the screenshot shows an earlier build (the gallery on DX Life's research page, the tabs in the old
order), so its alt text and a caption now say so. A reshoot is rega's.
Also, each a one-line factual fix (the README's structure is unchanged):
- The name, once where the gallery is introduced: the Research Gallery, which DX Life publishes as Deep
Research. The other 22 mentions and the headings, whose anchors other text links to, are unchanged.
- 7 vs 8 production maps: the eighth is the country map, for DX Life's country pages, not in the gallery.
- development is where work lands, and main moves only on a publish: the goals table, the swarm
section's two sentences, and the glossary.
- Both production grids now follow the gallery's section order (Prayer Progress before UPG-100 List).
- The embed heading's status reads "✅ works today", the README's own legend for ✅, instead of "production":
the page is not live on DX Life's production site yet (dx-maps' pre-read).
check:readme-size, check:doc-scripts, check:no-new-driver-references and check:link-coverage pass.
From exp's second read of 4bcce8ff8. "BUNDLE=<map> bun x vite build && bun run fix:sri" is right for a
code change, but a change to the map's .meta.json reaches its pages and the manifest only through
bun run tree. Without it the leaf page ships the old settings, and the landing scan's step 2b refuses
the stale tree. The recipe is now "BUNDLE=<map> bun x vite build && bun run tree && bun run fix:sri".
The tree step takes a few seconds and changes nothing when nothing changed.
Found re-reading 10be43d2b:
- "BUNDLE=<map> bun x vite build" alone leaves the map's pages and the manifest pinned to the OLD hash,
so the map's own page and any pasted snippet refuse the new file. It is now followed by bun run fix:sri.
Measured two-sided: one byte added to a pinned map's built file made check:sri FAIL (4 of its pages
disagreed); fix:sri rewrote them and the manifest, and check:sri PASSED. The probe files were restored.
A one-map build rewrote only that map's .js, never the manifest or a page.
- "A snippet is two parts" was wrong. The snippet also preloads the map engine and sets
window.MAP_APP_API_URL, so the README now says to paste it whole and names what it does.
- The agent table:
- Cities with Internet works by country (internet use), so it moved from "Reach a city" to
"Plan outreach". The production maps work by country and region; city-level planning (Prayer Walk
Planner) is experimental, and the row says so.
- Maps carry the names the app shows (Simple Research, UPG 100 List).
- "Frozen" was a tonight-only rule; the line now reads "leave them as they are unless your task is one
of them".
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.
A fresh reader given only the README and the HOWTO reached the Studio and a plugin's /__leaf page with
nothing else needed, but one step. After "port 8090 is already in use ... set DX_PB_PORT", neither
doc said the setting is read when bun run dev starts, so the new port only applies after a restart.
The README copies .env.example before starting the server, and the port message appears only once it
runs, so the steps looped with no stated way out. All three places that mention DX_PB_PORT now say to
pick a free port and restart.
A fresh reader given only the README and HOWTO-join-the-table got through install, bun run dev and
the Studio. One gap: no address for a single plugin's page. The Capability 1 fold says each plugin's
folder holds "an index.html for previewing it", which reads as /plugin-designs/<plugin>/index.html,
and that 404s under bun run dev. The page is /__leaf/<plugin>/<profile>, and the Studio's list is
/__plugin-gallery/manifest.json. Both are now named.
Three smaller notes from the same reader:
- the README copied .env.example to .env while the HOWTO uses .env.local. Both work and .env.local
wins; the README now uses .env.local too, which also keeps .env free for compose.yaml;
- the Mapbox token read as required; it is one of two ways to get a background;
- the 8090 port hint (DX_PB_PORT) was only in the HOWTO; it is now named where the README first
mentions PocketBase.
Also, the engine rule (was a follow-up commit, f0e965e4d):
Since 2026-09-28 useMapProvider.js resolves `auto` to MapLibre, and Mapbox is an explicit choice:
"provider": "mapbox" plus a token. The docs still said "Mapbox when a token is available":
- README's map-engines row;
- how-to.md's provider section;
- the plugin-designer skill's props table, which even says to confirm in useMapProvider.js.
All three now state the current rule. So do four lines that told readers to set provider maplibre to
avoid needing a key: README's Get it running and its "No token" fold, .env.example's token comment,
and reference.md's no-key row.
Case-insensitive git grep "Mapbox when a token" over README.md, documentation/ and skills/: 3 before, 0 after.
A clean clone of development, run with no settings and only the README:
- The drop-in's `bun run build && bun run dropin` stopped at the build, which refuses without
BUILD_ALLOW=1, so dropin never ran. The built maps are in the repo: the route is now
`EMBED_BASE_URL=https://your-site bun run tree` then `bun run dropin`, with the one-bundle rebuild for
changed plugins. Without the tree step the manifests' snippets stay relative and no other site can paste
them (measured: embedBase "." before, the site's address after, and the snippet's page answered 200).
- smoke:studio checks :5173 by default; when Vite took another port it measured a different server.
The step now passes the printed URL, and says it drives a headless browser.
- `bun run serve` crashes if 4173 is taken; PORT=<n> works and is now named.
- Vite prints http://127.0.0.1:5173/, not localhost.
- The sync example's branch must exist on the remote; the public repo has only main.
- bun run dev also downloads and starts a local PocketBase on 8090; now said. A copied template keeps
its element name until renamed as its README says.
"Where the folder goes" had two routes. The third is the same container with ACCESS=public on a
team's research subdomain: the Plugin Studio open to everyone (following development), its /cdn
built from main serving the site's production maps, and the admin parts behind a password set at
deploy. A small table ranks the three by capability: drop-in (the simplest, no backend),
subdomain (PocketBase behind a sign-in), Plugin Studio (the highest: plugins built live in
public). The two links to the section follow its new name.
The link to deployment/cloud's "Public Studio (ACCESS=public)" section resolves once
repo/public-studio-mode lands, so this lands after it.
The gate measures the built folder, so it belongs after the build, in
gates:post, with its description beside the others. It now reads the tree
name from _tree-name.mjs like every other tool: the folder was renamed
once already, and a gate hardcoding the old name kept reading it.
The row now says 1205 files, 154 MiB: the folder as it stands with the
350 city and country posters this landing ships.
dx-base measured two defects in the A8 draft for text that goes public:
- Links into the private DX Life repo answer 404 to anyone without an account. The live
example is now plain words (README, DEPLOY), and the clone line points at the public repo
(doxa-open/doxa-maps, as DEPLOY already did). DEPLOY's "three ways" becomes the two routes;
the CDN route is retired.
- The web folder row said 536 files, 76 MiB. The folder is 855 files, 119.2 MiB. New
check:readme-size re-measures public/dx-maps and fails when the row is more than 10% off,
printing the line to paste. It passes at 855/119; the old numbers fail.
- Bottom line up front names the persona dx-maps is for, vibe coders, and links to what
they get.
- "Cloud development environment": by default bun run dev is fully local. DX_SYNC_REMOTE and
DX_SYNC_BRANCH in .env.local make it follow a shared branch. It fast-forwards only a clean
checkout on that branch, and never merges over local work. If your own agents also edit
the checkout, it stops following, so push small and often or the landings pile into a merge
conflict.
- The drop-in route's live example pointed at a branch that doesn't exist (research-gallery);
it is research-gallery-drop-in, proven with every production map passing its embed checks.
- One line on SRI where hosts copy snippets: the integrity hash makes a changed bundle
refuse to run, so copy the snippet again after each release.
The deployment section named four hosting options, three of them CDN-shaped (Cloudflare Pages,
jsDelivr, Netlify). dx-maps now ships two routes, and the section says so in that order:
- The easiest path: drop-in. The folder goes into your own site's public/ and your site's server serves
every map; bun run build && bun run dropin. One server, no PocketBase. It is the route the DX Life
branches were proven on.
- Subdomain: the dx-maps container with PocketBase, for maps that need a backend of their own; the
Dockerfile and compose.yaml at the repo root.
The notes that still hold stay (relative links, iframes, the one CORS header for JS embeds). The
quick start's own drop-in steps become a pointer to the route, and the cloud dev server is described
as following development, not main.
The drop-in was proven on a laptop with one server: the three DX Life branches rendered their maps,
7 of 7 checks passed, with internal/sync-dropin.mjs --from-config --dest <doxa-life>/public. This
makes that the default path:
- dropin.dest is ../doxa-life/public. The old ../doxa-life/public/embed/doxa-maps-build was stale.
- bun run dropin = sync-dropin --from-config; deploy:dev (build + drop-in) now uses it.
- The README gains "The easiest path": the studio for the work, dropin.dest at your site's public/,
then build and drop in.
One hazard came with the new destination, and it is closed here. --prune deletes every file in the
destination outside the drop-in's allowlist, which was right while that was a folder of its own. Into
a site's public/, it would delete the site. deploy:dev passed --prune, so it no longer does, and
sync-dropin refuses --prune into any folder named public/. Measured in a scratch site: --prune into
site/public exits 1 with the reason; a plain drop-in copies dx-maps/ and leaves the site's own
file in place.
The why now says what the maps are for, in the order they serve it: giving disciples, churches and
leaders what they need to bless the nations, with indigenous disciples, churches and leaders
multiplying and blessing their own peoples as the deeper answer to the Great Commission. It names the
three things the maps serve: praying for the unreached peoples of the world, mobilising believers to
bless their own cities, and caring for the needy with private maps.
Output 3 showed only the map app as a desktop app. Rudder is the desktop
example the README describes, and it has now been built with
`bun run desktop:build rudder-voice` and run on Linux: a screenshot of the
running app goes under the map app's, with one line on how to build it.
The PNG carries no text chunks (the original recorded its creation time
and timezone); the pixels are unchanged.
The worktree example branched from main and pushed to it; main is production now and the team lands
on development. The quick start cloned doxa-open/doxa-maps, which is not the repo, and sent readers to
localhost:5173 while the dev server takes the next free port when 5173 is busy (a fresh clone's friend
test came up on 5174).
SKILL.md claimed new plugins land in a Research Gallery Experimental section.
That section was replaced by capability tiers (plugin-studio.vue:630); stage is
now a label prefix, not a place. Both stale lines corrected.
Adds what the skill never said:
- capability is DERIVED from composes and an explicit type is CHECKED against it
(check-capability-derived.mjs), with its two traps;
- rail labels come from meta, and check-studio-rail.mjs:68 fails a bare id;
- presets merge OVER the profile's meta config, key by key -- rule 3 of
documentation/PRESET-PLUGIN-STANDARD.md, asserted by check:preset-config-merge
(generate-tree.mjs:1094, the comment there records the pinHint bug);
- targets is read (profile-meta.mjs:28) and consequential: the Research Gallery
skips a bundle that does not list web (doxa-maps-spa.vue:605).
Depth moves to references/: glossary, targets, backend, workflow. backend.md
carries the PocketBase user tiers marked DESIGN INTENT, NOT BUILT -- quoted
rather than linked, because their source lives outside this repo.
Verified against this tree, rebased on main: 61 path citations resolve, 10 line
citations land on the code they claim.
README: one line pointing an agent at the skill.
Laptop (bun run dev, zero config); a shared cloud dev server (Docker or Coolify, with a persistent /data);
public embeds from /cdn or any static host; the built folder inside a site's public/, as DX-life does.
Each with the command, what you get, and the detailed doc.
A fresh clone needs no .env. .env.example lists each local setting with its default, and an empty value
means the default: DX_SYNC_REMOTE empty = hot reload of local edits only; DX_PB_URL empty = a local
PocketBase. Rudder's settings are marked as shell-environment only, since the dev server reads them there.
Bundle integrity: all 25 bundles carry bundles[].integrity (sha384) and every profiles[].embed.script
already includes integrity + crossorigin=anonymous (checked on main); the section shows the snippet,
what the browser does with it, the CORS header it needs, and check:sri. The container's PocketBase:
locked-by-default collections, the prod dashboard blocked and the dev one admin-only, and hooks OFF,
now true in code: both instances get --hooksDir pointing at a path that never exists, so a pb_hooks/
folder added to the repo can't run. Per-plugin locks and isolated edge functions are stated as not
built.
Vibe coders get their own subsection at the top: one repo with many plugins (own src/, one
shared library), the Plugin Studio live with bun run dev, Rudder as the offline voice-to-text
corner widget in the Studio (Linux today), one plugin to embed or mobile with Rudder as the
desktop-target example (packaging next, as its own README says), and 'Run it in the cloud'. Only
what is on main. Acknowledgements thank the open-source projects it stands on (Vue, Vite, MapLibre,
Pinia, Vue I18n, Capacitor, Tauri, oauth2-proxy, NeMo-Speech.cpp + Nemotron, OpenStreetMap via
OpenFreeMap); no personal names. public-hygiene clean.
Each row names only features on main: Gospel Resources' views and data tables, Cities with
Internet and the Gospel x Internet board (incl. internet-by-adm1), Big Picture / Simple Research
filters with Export CSV, Export this selection and Full Profile, UPG-100's Prayer List, Poster Map
and Card Deck. The agents block lists manifest.json, the public tables and list files, the two
PUBLIC pray.doxa.life endpoints the maps already call (no keyed endpoint), and the ?lang /
?provider / ?list / ?tk switches. check:public-hygiene clean.
deployment/cloud/: a bootstrap Dockerfile (Bun, git, oauth2-proxy v7.15.3) that clones the repo
and runs deployment/cloud/entry.sh from it, so the recipe updates with git; the Vite overlay
(host, allowed hosts, HMR over wss); and the pull loop that follows the branch. With no OIDC env it
serves Vite directly (laptop default unchanged). With OIDC_ISSUER set, oauth2-proxy owns the port
and Vite listens on localhost behind it: Studio, maps and the HMR websocket all sit behind one
sign-in, with PKCE S256, a confidential client and a REQUIRED group allow-list (it refuses to
start without one). Secrets reach oauth2-proxy through its environment only. README gets a short
'Run it in the cloud' section linking the recipe.
A page that embeds the Research Gallery or a single map sets its language with profile-config
{"locale":"ar"} ("lang" works too) and can switch it live. With profile-config only the map's
own box mirrors for Arabic; a ?lang=ar address mirrors the whole page. The example is the
gallery, <doxa-maps-spa profile-config='{"locale":"ar"}'>, which takes its locale from the
language prop or profile-config and hands it to every tab.
- Deployment is now organised around what the build makes: (1) one web
folder (536 files, 76 MiB), embedded by iframe and JavaScript (proven) and
WordPress (just for fun); (2) the mobile app (Capacitor, built); (3) the
desktop app (Tauri, proof of concept). A hosting table says where the folder
can go: dx-life's public/, Cloudflare Pages drag-and-drop (fits its 1,000-file
/ 25 MiB limits), GitHub + jsDelivr (JS embeds only: measured, jsDelivr serves
HTML as text/plain), or any web server, with the one _headers line JS embeds
need. No Docker. The diagram and the map-cruncher picture say three outputs.
- Languages: 11 locales via ?lang=, Arabic right to left, with an Arabic shot of
UPG-100 (Big Picture still leaks English in Arabic; reported). The partner
profile-config locale is deliberately not documented until it is fixed.
- check-shot-freshness and check-shot-distinctness parsed only '...' paths, so
after 44ef31b2 turned them into `/${TREE_NAME}/...` templates they saw 2 of 26
shots: distinctness failed, freshness passed vacuously and hid 22 stale shots.
Both now accept either form and resolve TREE_NAME, and exit 75 (NOT MEASURED)
unless every `await shot(` call is parsed (the one dynamic dx-life call is
marked). Negative-tested. The 22 shots are retaken and checked by eye.
- how-to: the shell no longer overwrites the Studio (it now lives in the output
folder); README serve line points at doxa-maps/index.html.
- Docs follow the rename to dx-maps (09014f8a): every output-folder path and URL in
README, how-to, reference, CONTRIBUTING, the CLI section and the develop guide now says
public/dx-maps/. The repo name, the config file name, the WordPress plugin folder and
the doxa-* tag names are unchanged (tags are a separate landing).
- Hosting: a live example, the dx-life branch research-gallery, which drops the folder
into dx-life public/ and fills /research with the Research Gallery.
A new "Experimental shelf" section pictures the two newest shelf plugins, each
shot from its own page after it finished loading: the Wall of People Groups
(all 2,107 groups as photo cards on one zoomable prayer wall, 7fec7426) and the
Prayer Walk Planner (full screen from any embed and a sharp HD print,
30e6e569). The Research Gallery tree now lists all seven shelf plugins
(adds pplr-data-maps and wall-of-people-groups). Shots staled by 92a81ed2 and
later rebuilds are retaken.
simpleresearch fixed the phone toast (2221d11b): at 390x844 the "Tap a
coloured dot" prompt now sits above the Progress sheet and the legend reads in
full (checked by eye). The phone row now shows seven maps in two rows of four;
Big Picture keeps its note (desktop by design; on a phone the Research Gallery
opens on Simple Research). Gospel Resources shots retaken after its bundle was
repaired on main (57fecfd0 replaced a bundle committed with merge-conflict
markers in 52ab6089). Other stale shots refreshed from the latest builds.
A row of phone screenshots (390x844, taken after each map finished loading)
under the production gallery: Regions, UPG-100 List, Prayer Progress, Cities
with Internet and Gospel Resources. Big Picture is desktop-only by ruling, and
Simple Research is left out until its phone layout is finished: its "Tap a
coloured dot" prompt still covers the Progress legend at 390px. The README
says both plainly.
- 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.
Shot from the rebuilt bundle at 89bd9c5d, after its owner marked the resize
done, with the wait-for-loading fix: the map shows every region, all 27 zones
and all 2,107 pins; the composite and phone shots show the new banner cards.
The mobile dropdown no longer claims "one poster per row", which the phone
layout no longer is.
- The Goal and Isaiah 40:3 lead the README, byte-for-byte as written on the
public repo (driver-web-edits.patch), so the next export keeps them.
- Each of the 5 capabilities and 5 deployment methods is now a one-line
summary, its picture, and a collapsed "More about…" dropdown. 16 dropdowns,
none open by default, so a reader can scroll the pictures and summaries.
- WordPress / Disciple Tools and desktop say what is true in plain words: we got
a JAMstack map running there; proven, not yet a production feature; the
Research Gallery could become a strong desktop app. Their cards match.
- The agent-swarm section explains the problem in plain words (one shared
library and one build means one bad change breaks every map), with a git
glossary and the commands folded away.
- Get it running now includes your own free Mapbox token (the public copy
ships without one), and a dropdown on changing the studio itself.
- The diagram has eight plugin nodes, main at the centre behind a padlocked
merge-queue ring, and a plain-language "How main is protected" strip.
- Methods 4 (WordPress / Disciple Tools) and 5 (Tauri desktop) get a card with
the platform's logo and a PROOF OF CONCEPT badge; logos are the CC0 Simple
Icons marks, credited under the cards. SVG sources beside the PNGs.
- The Plugin Studio screenshot is retaken from the 03:43 studio rebuild, and six
other shots that rebuilds had made stale are retaken; all checked by eye.
- The clone line pointed at the private source repo. It now clones the public
giveaway, doxa-open/doxa-maps, which clones anonymously (checked with
ls-remote and no credentials), so a DX newcomer can onboard from the README.
- The README linked AGENT-BRIEF.md, which the giveaway export removes; it now
points to documentation/CONTRIBUTING.md.
- README-longform's two SPA images were written relative to the wrong folder
and rendered broken; fixed.
Host as a placeholder and the SRI hash elided (it changes every build), with a
pointer to manifest.json for the exact copy, so the README cannot go stale.
The Research Gallery tree said only "every other bundle". It now lists the
five the shell actually shows today, in its own order: prayer-walk-planner,
upg-neighbor, all-people-groups, country-posters, doxa-vision-card
(22 bundles - 7 curated tabs - 10 in NOT_EXPERIMENTAL).
Eight screenshots were shot from bundles that have since been rebuilt;
retaken from the current build and checked by eye.
