diff --git a/documentation/HOWTO-join-the-table.md b/documentation/HOWTO-join-the-table.md
index 275ab33b4..497ae0d02 100644
--- a/documentation/HOWTO-join-the-table.md
+++ b/documentation/HOWTO-join-the-table.md
@@ -113,12 +113,12 @@ So it cannot surprise you mid-thought. You can also check that any time at `/api
 
 ## The database, and the one thing that surprises people
 
-There are three databases and you only ever touch one.
+There are three databases. You work against one of the first two — never the third.
 
 | 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 |
+| The team's shared one | the team's shared test data | the team — this is usually the default |
 | 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
@@ -132,12 +132,26 @@ This is deliberate. A database rule that opens something to the public arrives a
 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.
 
-**You do not have to set up the database at all.** The first time you run `bun run dev` it downloads and
-starts one for you, on your laptop, with its data in `.pb/`. You can open its admin screen from the dev
-server at `/api/pb/_/`.
+### Which one your laptop talks to
 
-The only time you touch this is if the log says port 8090 is already in use — then set `DX_PB_PORT` to
-something else in `.env.local`.
+Most teams point every laptop at the **shared** one, so you are all working against the same test data.
+Put this in `.env.local`:
+
+```
+DX_PB_URL=https://<your team's dev server>/pb
+```
+
+You sign in with the same team account you use for everything else — there is no separate password. Ask
+whoever set up your team for the address if you do not have it.
+
+**Leave it unset and you get a private one instead.** The first time you run `bun run dev` it downloads and
+starts a database on your laptop, with its data in `.pb/`, and you can open its admin screen at
+`/api/pb/_/`. That is the fallback, and it is a fine way to work while you are finding your feet.
+
+The only other thing here is `DX_PB_PORT`, which you set only if the log says port 8090 is already in use.
+
+> **New collections start locked.** Your plugin's data is not readable until a migration opens it —
+> deliberately, so nothing is public by accident. That migration is a commit like any other.
 
 ---