A joining page for people who have never seen this repo

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.

documentation/HOWTO-join-the-table.md

@@ -0,0 +1,144 @@
+# How to join the table
+
+You want to build a map. Someone told you there is a repo, a dev server, and a thing called PocketBase, and
+now you are staring at three of them wondering which one you are supposed to touch.
+
+Short answer: **you work on your laptop, you land your work on main, and a shared server shows everyone what
+landed.** That is the whole shape. The rest of this page is what each of those three is for, and the five
+commands you actually type.
+
+> **This page is about working alongside other people.** If you want to know how to build a plugin itself —
+> the files, the build, getting it live — read
+> [develop-a-plugin-and-see-it-live.md](./develop-a-plugin-and-see-it-live.md) first and come back here when
+> you are ready to share your work.
+
+---
+
+## The three places
+
+### 1. Your laptop — the workshop
+
+This is where you build. Everything is local and fast, and nothing you do here can affect anyone else.
+
+```bash
+bun install
+bun run dev
+```
+
+You get the Plugin Studio, hot reload on your own edits, and a local database with your own test data. Break
+it, reset it, fill it with nonsense — it is yours.
+
+### 2. `main` — the truth
+
+When your work is ready, it goes to `main`. That is the one place everybody agrees on. Nothing is "real"
+until it is there.
+
+### 3. The shared dev server — the table
+
+A server watches `main` and reloads about every 15 seconds. That is where the team sees each other's work without
+anyone sending anyone a zip file. You do not edit here. You never need to log into it to do your job.
+
+> **The rule that makes this work:** one plugin folder per person. You edit `plugin-designs/<your-plugin>/`
+> and nobody else does. Everything below depends on that.
+
+---
+
+## Getting your work onto main
+
+Three commands, in this order, every time:
+
+```bash
+git add -A && git commit -m "what you changed"
+git pull --rebase origin main
+git push origin HEAD:main
+```
+
+If the push is rejected, someone landed first. Run the middle command again and push again. That is not an
+error — it is the normal case, and it is worth knowing how normal.
+
+**We measured it.** In a ten-writer stress test at a far faster edit rate than a human works at:
+
+| | |
+|---|---|
+| pushes rejected, then retried | **95%** |
+| merge conflicts | **0** |
+| retries needed per edit | 1.1 average, 3 at worst |
+
+Nearly every push got rejected. **Not one caused a conflict.** That is the one-folder-each rule paying off:
+you are all pushing to the same branch, so you collide on *who goes first* — but never on the same lines of
+code, because you are never in the same file. A rejected push costs you one extra command. It does not cost
+you an afternoon untangling someone else's work.
+
+If you *do* hit a real conflict, it means two people edited one file. Stop and talk to the other person;
+that is a coordination problem, not a git problem.
+
+---
+
+## Seeing your teammates' work on your laptop (optional)
+
+By default your laptop only reloads on *your* edits. If you want teammates' landed work to hot-reload locally
+too, put this in `.env.local`:
+
+```
+DX_SYNC_REMOTE=<the repo URL>
+DX_SYNC_BRANCH=main
+```
+
+Your laptop then fast-forwards onto `main` as people land.
+
+> **It never merges over your edits.** If your working copy is dirty, it leaves it alone. Uncommitted work
+> cannot be overwritten by this — that is the whole reason it is a fast-forward and not a merge.
+
+This is optional. Skip it if you would rather pull manually.
+
+---
+
+## The database, and the one thing that surprises people
+
+There are three databases and you only ever touch one.
+
+| Where | What is in it | Who touches it |
+|---|---|---|
+| Your laptop | your own sandbox data | you, freely |
+| The shared dev server | the team's shared test data | the team |
+| Production | what the public sees | nobody directly |
+
+**You never publish a database.** Not yours, not anyone's. What travels is the *shape* — the tables and
+fields — as migration files committed to the repo alongside the code.
+
+So adding a field is a normal change: you edit, you commit the migration, you push it like any other file,
+and it goes through review with everything else. When the person who publishes runs the publish step, the
+migrations apply.
+
+This is deliberate. A database rule that opens something to the public arrives as **a commit someone can
+read** rather than as a setting somebody clicked at midnight. If you have ever inherited a system where the
+live config did not match the repo, you already know why.
+
+To point your laptop at the team's shared test data instead of your own:
+
+```
+DX_PB_URL=<the shared database URL>
+```
+
+Leave it unset and you get your local one, which is usually what you want while building.
+
+---
+
+## The five things to remember
+
+1. **Build on your laptop.** It is fast and it is yours.
+2. **One plugin folder per person.** This is what keeps ten people out of each other's way.
+3. **`pull --rebase`, then push.** A rejected push is normal — 95% of them were, and none became conflicts.
+4. **The shared server is for looking, not editing.**
+5. **Schema is a commit, never a click.** You never publish a database.
+
+---
+
+## When something is wrong
+
+- **"Your push was rejected"** — normal. `git pull --rebase origin main`, push again.
+- **A real merge conflict** — two people edited one file. Talk to them; the one-folder rule slipped.
+- **Your change is not on the shared server** — it reloads about every 15 seconds, not instantly. Check your
+  push actually landed: `git log origin/main -1`.
+- **The shared server shows an old version of your plugin** — you are probably looking at what is on `main`,
+  not what is on your laptop. Those are different on purpose.