diff --git a/docs.json b/docs.json
index b1efc4c..24e750c 100644
--- a/docs.json
+++ b/docs.json
@@ -308,6 +308,7 @@
"features/user-defined-types",
"features/table-operations",
"features/er-diagram",
+ "features/join-builder",
"features/explain-visualization",
"features/server-dashboard",
"features/users-roles"
diff --git a/features/er-diagram.mdx b/features/er-diagram.mdx
index d867be5..73e73ec 100644
--- a/features/er-diagram.mdx
+++ b/features/er-diagram.mdx
@@ -58,6 +58,10 @@ count and what it is joined to; step into one to hear each column with its type
primary key, a foreign key, or optional. Selecting a table in the diagram moves the VoiceOver cursor
to it.
+## Build a join query
+
+Command-click or Shift-click tables to select more than one. Click **Build Join Query** in the toolbar, or right-click a selected table and choose **Build Join Query…**, to open the [Join Builder](/features/join-builder) on them.
+
## Compact mode
The compress button in the toolbar cuts every table down to its primary key and foreign key columns, which is what makes a wide schema fit on screen.
diff --git a/features/join-builder.mdx b/features/join-builder.mdx
new file mode 100644
index 0000000..711c021
--- /dev/null
+++ b/features/join-builder.mdx
@@ -0,0 +1,50 @@
+---
+title: Join Builder
+description: Build a multi-table SELECT from the foreign keys between your tables
+---
+
+Pick the tables and their foreign keys become the join conditions. What comes out is plain SQL in a new query tab, to edit like any other query.
+
+
+ 
+ 
+
+
+## Open the builder
+
+- Choose **Database > Build Join Query…**. Tables selected in the sidebar start out picked.
+- In an [ER diagram](/features/er-diagram), click a table, then Command-click or Shift-click the others. Click the **Build Join Query** toolbar button, or right-click one of the selected tables and choose **Build Join Query…**.
+
+The builder works in the schema of the diagram or of the selected tables.
+
+## Pick tables
+
+Select a table in the list on the left to add it. The first table picked is the `FROM` table, and each one after it joins the tables before it on the shortest chain of foreign keys.
+
+| Picked table | What the query gets |
+|---|---|
+| Has a foreign key to or from a table already picked | `JOIN … ON` the key's columns |
+| Reaches a picked table only through a junction table | The junction table as well, joined to both |
+| Is reached by no foreign key | `CROSS JOIN`, with a note under the table list |
+
+Deselect a table to take it out. A table that was joined on it switches to a key that reaches a remaining table, or to a cross join when none does.
+
+## Shape the query
+
+- **Joins** shows each table with its join type, **Inner Join** or **Left Join**, and its condition. **On** lists every foreign key to an earlier table: an `orders` table with `billing_address_id` and `shipping_address_id` offers both keys to `addresses`.
+- Select columns under a picked table to list them instead of `SELECT *`.
+- **Add Filter** adds a `WHERE` condition from a column, an operator and a value. Conditions combine with `AND`, and one still missing its value is left out.
+
+**SQL Preview** follows every change, with identifiers quoted for the engine and, on an engine with schemas, each table named with its schema. Click **Open in Query Tab** to open the query in a new tab on the same database.
+
+## Database support
+
+The command needs an engine that runs SQL and whose driver reports foreign keys, and is dimmed on the others. The engines that report foreign keys are listed under [ER Diagram](/features/er-diagram#database-support).
diff --git a/images/join-builder-dark.png b/images/join-builder-dark.png
new file mode 100644
index 0000000..bb4226a
Binary files /dev/null and b/images/join-builder-dark.png differ
diff --git a/images/join-builder.png b/images/join-builder.png
new file mode 100644
index 0000000..b24ed3c
Binary files /dev/null and b/images/join-builder.png differ