64b6c523ef
dx-shepherd ENDTOKEN-UPG-DOC, from the Driver's laptop-first decision. Written for someone staring at a repo, a dev server and a database, unsure which one they are allowed to touch — so it answers that first and explains second. THE SHAPE, in the Driver's own three places: laptop = your workshop · main = the truth · the shared server = the table, look but do not edit. Plus the rule the whole thing rests on, one plugin folder per person. ★ THE 95% NUMBER IS THE POINT OF THE PUSH SECTION, not decoration. A newcomer whose first push is rejected assumes they broke something. The measured result — 95% of pushes rejected, 0 conflicts, 1.1 retries on average — tells them the rejection IS the normal case and explains why it is cheap: you collide on who goes first, never on the same lines, because you are never in the same file. That reframes a scary error into one extra command, and it is the strongest argument for the one-folder rule. ⚠ TWO THINGS I CORRECTED RATHER THAN SHIPPED: - I first cited `backend/pocketbase/pb_migrations` as the migrations path. It does NOT exist in this repo — it is from the architecture doc's PLAN. A path a reader cannot find is worse than no path, because they assume they cloned wrong. Now says "committed alongside the code" until it is real. - "reloads every few seconds" is now "about every 15 seconds", which is what the source actually states. NO INTERNAL NAMES, checked rather than intended: zero hits for the server hostnames, the source-control product, the agent tabs, the dictation tool, the auth stack, "tenant" or the project's own code names. Cross-linked to develop-a-plugin-and-see-it-live.md, which answers the different question of how to BUILD a plugin — this page is about working alongside other people once you have one. ⚠ THE ENV SECTION IS PROVISIONAL. DX_SYNC_REMOTE / DX_SYNC_BRANCH / DX_PB_URL are taken from the architecture doc; repo is building them now and I have asked for the exact names, which are required vs optional, and what each points at. A doc with a wrong env name is worse than no doc — the reader blames themselves — so this gets corrected the moment repo answers, before anyone links it. |
||
|---|---|---|
| .. | ||
| architecture | ||
| assets | ||
| contributing | ||
| needs-eyes | ||
| readme-images | ||
| screenshots | ||
| CONTRIBUTING.md | ||
| develop-a-plugin-and-see-it-live.md | ||
| explanation.md | ||
| how-to.md | ||
| HOWTO-join-the-table.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.