ae899010cf
Driver via dx-shepherd (ENDTOKEN-UPG-DRV1 item 2). Written entirely from repo's exact text
(END-REPO-CLOUDNAMES) rather than from the architecture doc, because the last page needed two rounds of
corrections and every one was something I would have guessed wrong.
It opens by sending most readers away: "Most people do not need this page." The default is a fresh clone
and `bun run dev`, and a doc that implies otherwise costs a newcomer their first afternoon.
TWO OPTIONS, with option 1 recommended as the Driver asked:
1. Keep working locally and follow the remote — one line, DX_SYNC_REMOTE. You keep dictation, your own
database, and a broken push only breaks your own screen.
2. Run the shared container — everyone opens one URL, and the trade-offs are listed honestly rather than
buried: no dictation (the engine falls ~4 s behind speech on 2 CPUs, so it ships off), nobody can edit
on it, one broken push breaks it for everyone, it needs ~2.5 GB and 2 vCPUs, and its database is the
shared team one.
★ THE CONDITION I GAVE ITS OWN CALLOUT is the one that bites silently: the sync only fast-forwards when you
are on the branch with no unsaved edits AND no local commits. Otherwise it stops pulling and says "main is
N commits ahead". That is protective, and the consequence is not obvious — leave local commits sitting
while an agent lands twenty changes and the eventual pull carries a day of divergence. So the page says
"push your own work, or you will drift" in as many words.
EVERY CLAIM VERIFIED IN THE SOURCE, not taken from the message: deployment/cloud/ exists with its
Dockerfile and README, that README really does carry the OIDC_* settings (12 mentions), entry.sh defaults
PULL_INTERVAL to 15 and RUDDER_ENGINE to 0 — which is exactly the "it falls behind so we switched it off"
repo described.
No internal names: the only hit was `dx-maps-dev`, which is the Docker IMAGE TAG in repo's own command, not
a hostname. Same substring trap as 'aggregates' matching 'rega'.
Cross-linked both ways with HOWTO-join-the-table.md.
|
||
|---|---|---|
| .. | ||
| architecture | ||
| assets | ||
| contributing | ||
| needs-eyes | ||
| readme-images | ||
| screenshots | ||
| CLOUD-DEVELOPMENT-ENVIRONMENT.md | ||
| CONTRIBUTING.md | ||
| develop-a-plugin-and-see-it-live.md | ||
| explanation.md | ||
| how-to.md | ||
| HOWTO-join-the-table.md | ||
| PRESET-PLUGIN-STANDARD.md | ||
| README-embed-example.md | ||
| README-embed-gospel-resources.md | ||
| README-SECTION-3-cli-commands.md | ||
| README.md | ||
| reference-capability-exemplars.md | ||
| reference-library-index.md | ||
| reference-universal-props.md | ||
| reference.md | ||
| tutorial.md | ||
| vendored-font-noto-serif-devanagari.md | ||
| why.md | ||
documentation/ — pick your path
"what is this?" "teach me" "how do I …?" "look it up" "all the detail"
│ │ │ │ │
why.md ──────────► tutorial.md ────► how-to.md ────► reference.md ───► architecture/
(2 min, 1 diagram) (first map) (task recipes) (tables) (contracts)
- why.md — the problem and the "map islands" idea. Start here.
- tutorial.md — build your first map, no jargon.
- how-to.md — recipes: embed, iframe, SPA, colors, CDN, mobile, tokens.
- reference.md — config fields, build scripts, the
profile-configcontract. - explanation.md — the model in 15 lines.
- architecture/ — the deep end: full contracts, the per-file catalog.
- README-embed-example.md — the drop-in README used when this bundler is embedded inside a host repo.
- 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:
- develop-a-plugin-and-see-it-live.md — ★ the golden path: zero to a plugin live, in 6 steps.
- README-SECTION-3-cli-commands.md — every command, per deployment method, with prerequisites.
- reference-capability-exemplars.md — which bundle is at which capability tier (generated).
- reference-library-index.md — the reusable
library/pieces you can import (generated). - CONTRIBUTING.md and contributing/ — how to contribute, and the bar for
library/.
Nothing on the simple path is longer than a few minutes; everything complex lives in
architecture/, linked from where you'd need it.