docs: scenario playbooks

README.md

@@ -2,6 +2,8 @@
 
 > **If you are an AI agent reading this:** follow [docs/AGENT_SETUP.md](docs/AGENT_SETUP.md) to install and register Entangle on this machine. Ask your human before changing firewall rules or installing system packages.
 
+> **Experimental.** Entangle is pre-1.0: commands, on-disk formats and the wire protocol can change between releases, and it has not had an external security review.
+
 Entangle is a local-first MCP server for letting two LLM agents on the same
 LAN discover one another, exchange capability manifests, and transfer JSON or
 files through a group-authenticated Noise link. Control frames and payload
@@ -67,6 +69,8 @@ a temporary ID while the first server is running. See
 [docs/SETUP.md](docs/SETUP.md) for group setup, firewall, client configuration,
 and a two-machine smoke test.
 
+**Playbooks:** [Scenario guides](docs/playbooks/README.md).
+
 The MCP tools are `find_entangled_particles`, `sync_entangled_state`, and
 `observe_entangled_states`. `sync_entangled_state` can target one particle,
 up to 32 selected particles, or every other member of a group; an optional

docs/AGENT_SETUP.md

@@ -7,6 +7,7 @@ have `entangle` on `PATH`, Entangle registered as an MCP server in your own MCP
 client configuration, and its group members discoverable. Ask the human before
 using `sudo`, installing system packages, changing firewall rules, or editing
 a configuration file you did not create; show them the proposed diff first.
+For scenario walkthroughs, see the [playbooks](playbooks/README.md).
 
 ### Running commands on Windows
 
@@ -109,8 +110,8 @@ proceeding.
 
 ## Groups
 
-Human-only commands: `group create`, `group invite`, `group join`, `group
-leave`, `group remove`, `group rekey`, and `group admin`. Agents may run
+Human-only commands: `group create`, `group invite`, `group join`, and
+`group leave`. Agents may run
 `entangle group list`, `entangle group members <name>`, and `entangle peer
 list`. One device invites with `entangle group invite <name> [--count N]`;
 the human enters the one-time code on each other device with

docs/SETUP.md

@@ -2,6 +2,7 @@
 
 For step-by-step instructions written for an AI agent installing Entangle on
 its own machine, see [AGENT_SETUP.md](AGENT_SETUP.md).
+For scenario walkthroughs, see the [playbooks](playbooks/README.md).
 
 ## Prerequisites
 
@@ -81,6 +82,10 @@ On macOS, allow the Entangle executable to accept incoming connections in the
 system firewall. Multicast behavior can also depend on the network interface
 and router configuration.
 
+Group invites use an additional ephemeral TCP listener. The invite command
+prints its address and port; the firewall must allow that inbound connection
+while the invite is open.
+
 ## Groups
 
 Trust is based on membership in a shared group. Each device can belong to up

docs/playbooks/01-first-group.md

@@ -0,0 +1,70 @@
+# 01. First group
+
+Use this when you are connecting your first two devices in one group.
+
+## You'll need
+
+- Entangle 0.6.0 or later on both devices.
+- A saved persistent particle identity on each device; start each configured
+  Entangle server once if that identity has not been created yet.
+- An interactive terminal on each device for the human-only group commands.
+- A LAN that permits mDNS multicast on UDP 5353 and incoming TCP connections.
+  The invite listener uses an ephemeral TCP port; the running node uses TCP
+  7337 by default.
+
+## Steps
+
+1. **On device A (your terminal):** Create a group. `work` is the group name.
+   This is a human-only command.
+
+   ```sh
+   entangle group create work
+   ```
+
+2. **On device A (your terminal):** Start an invite. This is human-only. The
+   default is one successful join; invites expire after 10 minutes.
+
+   ```sh
+   entangle group invite work
+   ```
+
+   Keep this command running. It prints a one-time `<code>` and an address.
+   Use the printed `<host:port>` if discovery is blocked; it is the invite
+   listener's LAN address and ephemeral port.
+
+3. **On device B (your terminal):** Enter the code from device A. This is
+   human-only. The joiner browses for up to 15 seconds; use `--via` to skip
+   mDNS and connect to the printed address directly.
+
+   ```sh
+   entangle group join <code>
+   ```
+
+4. **On both devices:** Start or reload the configured Entangle MCP server.
+   Both devices now share the group; they do not need to use the same particle
+   name.
+
+## It worked if
+
+These lines were captured during the local two-device run:
+
+```text
+Created group work (c55cd167). You are its admin.
+Joined work (c55cd167) via pc-a. 2 members.
+1 of 1 joined; invite closed.
+```
+
+## If something goes wrong
+
+`<nameplate>` means the number at the start of the invite code.
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `No invite <nameplate> found on this network. Check the code and that \`entangle group invite\` is still running; or add --via <host:port>.` | The invite was not discovered, has closed, or its nameplate does not match. | Check the code and that the inviter is still waiting. Retry with the exact printed address: `entangle group join <code> --via <host:port>`. |
+| `That code was wrong; the invite is now closed. Ask for a new one.` | The entered code did not authenticate. A wrong code closes that invite. | Ask the inviter to start a new invite and use its new code. |
+
+## Next
+
+- [Many devices at once](02-many-devices-at-once.md)
+- [Add a device later](03-add-a-device-later.md)
+- [Troubleshooting](11-troubleshooting.md)

docs/playbooks/02-many-devices-at-once.md

@@ -0,0 +1,78 @@
+# 02. Many devices at once
+
+Use this when several devices should join the same group during one onboarding session.
+
+## You'll need
+
+- Entangle 0.6.0 or later on the inviter and every joiner.
+- A saved persistent particle identity on the inviter and every joiner.
+- One interactive terminal per human-operated invite or join command.
+- A network that permits invite TCP connections; mDNS is optional when joiners
+  use the address printed by the inviter.
+- A count from 1 to 20. `--count` defaults to 1, and the invite expires after
+  10 minutes.
+
+## Steps
+
+1. **On device A (your terminal):** Create the group if it does not exist.
+   `work` is the group name. This is human-only.
+
+   ```sh
+   entangle group create work
+   ```
+
+2. **On device A (your terminal):** Start one invite for three successful
+   joins. This is human-only.
+
+   ```sh
+   entangle group invite work --count 3
+   ```
+
+   Keep it running and give each device operator the same one-time code
+   securely. If multicast does not work, also give them the printed
+   `<host:port>` address.
+
+3. **On each other device (the operator's terminal):** Join with the shared
+   code. This is human-only. Each device needs its own saved Entangle
+   identity and data directory.
+
+   ```sh
+   entangle group join <code>
+   ```
+
+   When using the printed direct address instead of mDNS:
+
+   ```sh
+   entangle group join <code> --via <host:port>
+   ```
+
+4. **On device A (your terminal):** Leave the invite running until all three
+   joins finish. It closes at the requested count; it does not remain open for
+   later devices.
+
+## It worked if
+
+These lines were captured during the local run with three joiners:
+
+```text
+Joined work (a10bc07d) via pc-a. 2 members.
+Joined work (a10bc07d) via pc-a. 3 members.
+Joined work (a10bc07d) via pc-a. 4 members.
+3 of 3 joined; invite closed.
+```
+
+## If something goes wrong
+
+`<nameplate>` means the number at the start of the invite code.
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `A device entered a wrong code; invite closed (<joined-count> of 3 joined). Run \`entangle group invite work\` again for a new code.` | A joiner entered a wrong code; that invite is dead. `<joined-count>` is the number that had already completed. | Start a new invite with the desired `--count` and share its code with every remaining joiner. |
+| `Invite expired; 2 of 3 joined.` | The 10-minute TTL elapsed before the count was reached. | Start another invite for the remaining devices. |
+| `The join didn't complete; nothing was kept. Run the same command again while the invite is open.` | The joiner did not receive the final confirmation. | Retry the same `group join` command while the inviter's invite is still open. |
+
+## Next
+
+- [Add a device later](03-add-a-device-later.md)
+- [Several groups](04-several-groups.md)
+- [Troubleshooting](11-troubleshooting.md)

docs/playbooks/03-add-a-device-later.md

@@ -0,0 +1,77 @@
+# 03. Add a device later
+
+Use this when a group already exists and you want to enroll one more device.
+
+## You'll need
+
+- Entangle 0.6.0 or later on the current member and new device.
+- A saved persistent particle identity on both devices.
+- The current member's group name and an interactive terminal on both devices.
+- A network that allows the invite TCP connection, or a direct address to use
+  with `--via`.
+- Time for the current member to reconnect to existing group members after
+  enrollment so it can vouch for the newcomer.
+
+## Steps
+
+1. **On the current member (your terminal):** Start a fresh invite for the
+   existing group. Do not create the group again. `work` is the group name.
+   This is human-only; the default count is one.
+
+   ```sh
+   entangle group invite work
+   ```
+
+2. **On the new device (the operator's terminal):** Join using the new
+   one-time code. This is human-only.
+
+   ```sh
+   entangle group join <code>
+   ```
+
+   If multicast is blocked, use the inviter's printed address:
+
+   ```sh
+   entangle group join <code> --via <host:port>
+   ```
+
+3. **On the current member:** Keep its Entangle node online briefly. Member
+   introductions are one-hop: the current member shares members it added
+   when it next links to other group members. Those devices can then link to
+   the newcomer.
+
+4. **On the new device (your terminal):** Confirm the local membership.
+
+   ```sh
+   entangle group list
+   entangle group members work
+   ```
+
+## It worked if
+
+The initial and later join transcripts contained:
+
+```text
+Joined work (53e3e217) via pc-a. 2 members.
+Joined work (53e3e217) via pc-a. 3 members.
+```
+
+Each inviter transcript contained:
+
+```text
+1 of 1 joined; invite closed.
+```
+
+## If something goes wrong
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `group not found: work` | The inviter's local group name is not `work`, or that device has left the group. | Check `entangle group list` on the inviter and invite the exact existing name. |
+| `This machine is already in work.` | This device is already a member of that group. | Check `entangle group list`; do not create a duplicate group. |
+| The newcomer joined, but an existing member has not learned about it. | Introductions are one-hop and the member who added the newcomer has not linked to that existing member since the invite. | Keep the inviter online until it reconnects to existing members. |
+
+## Next
+
+- [Many devices at once](02-many-devices-at-once.md)
+- [Several groups](04-several-groups.md)
+- [Leaving a group, removing a device, rekeying](README.md#scenario-playbooks)

docs/playbooks/04-several-groups.md

@@ -0,0 +1,88 @@
+# 04. Several groups
+
+Use this when the same device needs separate group memberships, such as work and home.
+
+## You'll need
+
+- Entangle 0.6.0 or later and a separate saved identity for each device.
+- An interactive terminal for each human-operated create, invite, and join.
+- A network that permits invite TCP connections, or the inviter's direct
+  address for `--via`.
+- A distinct invite for each group; group names and membership are local to
+  each device.
+
+## Steps
+
+1. **On device A (your terminal):** Create each group that this device should
+   administer. These are human-only commands.
+
+   ```sh
+   entangle group create work
+   entangle group create home
+   ```
+
+2. **On device A (your terminal):** Start a human-only invite for `work`. It
+   stays open in A's terminal while B joins in step 3. The one-time
+   `<work-code>` is the code printed by this command.
+
+   ```sh
+   entangle group invite work
+   ```
+
+3. **On device B (the operator's terminal):** While A's `work` invite is still
+   open, join using `<work-code>`. This is human-only. Add `--via <host:port>`
+   if multicast discovery is blocked; `<host:port>` is the invite address
+   printed in A's terminal.
+
+   ```sh
+   entangle group join <work-code>
+   ```
+
+4. **On device A (your terminal):** After the `work` invite finishes, start a
+   human-only invite for `home`. It stays open in A's terminal while B joins
+   in step 5. The one-time `<home-code>` is the code printed by this command.
+
+   ```sh
+   entangle group invite home
+   ```
+
+5. **On device B (the operator's terminal):** While A's `home` invite is still
+   open, join using `<home-code>`. This is human-only.
+
+   ```sh
+   entangle group join <home-code>
+   ```
+
+   Use `--as <local-name>` only if this device needs a different local label
+   for a group; it does not change the particle name.
+
+6. **On device B (your terminal):** Check that it has both groups.
+
+   ```sh
+   entangle group list
+   entangle group members work
+   entangle group members home
+   ```
+
+## It worked if
+
+The local two-group run printed these group-list rows:
+
+```text
+home  07d1da89  member  2
+work  50af4383  member  2
+```
+
+## If something goes wrong
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `A group named work already exists here; rerun with --as <other>.` | The receiving device already has a local group with that name. | Choose a different local label with `--as <other>`; do not replace the particle's `--name`. |
+| `This machine is already in work.` | The join was attempted again for a group this device already joined. | Check `entangle group list` and use the code for the other group. |
+| A device joined `work` but not `home`. | Each group uses its own invite and count. | Invite and join that device to `home` separately. |
+
+## Next
+
+- [Add a device later](03-add-a-device-later.md)
+- [Different networks](05-different-networks.md)
+- [Troubleshooting](11-troubleshooting.md)