docs: add peer visibility, spatial topology, and public profiles to vision

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/vision-20260407.md

@@ -261,6 +261,30 @@ Broker already tracks everything needed. Dashboard subscribes via WS and renders
 
 > **Partial:** 2026-04-07 23:30 · `59332dc` · Peer graph component (radial SVG layout, animated edges, group rings) added to live dashboard page. Remaining: state/memory timeline, resource panel, peer detail view.
 
+### 20. Peer visibility and spatial topology
+
+Control which peers can see each other. Instead of a flat mesh where everyone sees everyone, the broker filters `list_peers` responses and message routing based on visibility rules.
+
+**Three visibility models:**
+
+- **Proximity-based (simulation):** Each peer has coordinates `(x, y)` and a visibility radius. Only peers within range appear in `list_peers`. `set_position(x, y)` changes who you can see — spatial fog of war. Combined with the simulation clock, this creates emergent behavior: a "customer" peer walks into a "store zone", suddenly sees "sales rep" peers, initiates interaction.
+- **Scope-based (organizational):** Visibility follows group membership. Peers in `@frontend` see each other and `@leads`, but not `@backend` internals. Org-chart visibility without exposing every department.
+- **Manual/dynamic:** Peers or admins explicitly show/hide. `set_visible(false)` to go stealth (connected but invisible). Admin can force visibility/invisibility.
+
+**Who controls visibility:**
+- **Broker rules** — mesh-wide policy set at creation or via template (e.g., "proximity" mode for simulations, "scope" for orgs)
+- **Peer self-control** — `set_visible(false)` to go stealth, `set_position(x, y)` to move in proximity mode
+- **Admin override** — mesh admin force-shows or force-hides peers
+- **Dynamic conditions** — broker changes visibility based on state keys, clock ticks, or events
+
+**Notifications:** Peers receive `{ subtype: "system", event: "peer_visible" }` when a new peer enters their visibility and `peer_hidden` when one leaves. Different from join/leave — the peer is still connected, just not visible to you.
+
+**Peer public profile (outside image):** Each peer has a public-facing profile that other peers see — a curated view separate from internal state. Fields: `avatar` (emoji or URL), `title` (short role label), `bio` (one-liner), `capabilities` (what I can help with). Set via `set_profile({ avatar: "🔧", title: "DevOps Lead", bio: "Infrastructure and deploys" })`. This is what appears on the peer graph node and in `list_peers`. Peers choose how they present themselves to the mesh.
+
+**MCP tools:** `set_visible(visible)`, `set_position(x, y)`, `set_profile(profile)`, `get_visible_peers()`, `set_visibility_mode(mode)` (admin only)
+
+**Effort:** 2-3 days.
+
 ---
 
 ## Suggested build order
@@ -284,6 +308,7 @@ Broker already tracks everything needed. Dashboard subscribes via WS and renders
 | 15 | Sandboxes (E2B) | 2-3 days | Shared compute | |
 | 16 | Signed audit log | 3-5 days | Trust, compliance | |
 | 17 | Bridge / federation | 1-2 weeks | Multi-mesh coordination | |
+| 18 | Peer visibility + spatial topology | 2-3 days | Simulation fog-of-war, org scoping | |
 
 ---