# Matrix + Element — coalition ops (operator guide)

**Scope:** Gather + async working group — **not** the public map (The Weave stays static JSON).

**Site integration:** `gather.html` reads `assets/config/matrix-rooms.json` and renders join UI.

---

## What runs where

| Component | Role | Typical host |
|-----------|------|----------------|
| **Synapse** | Matrix homeserver (rooms, auth, media store) | Coalition VPS or EU host (G1) |
| **PostgreSQL** | Synapse database | Same host |
| **Element Web** | Browser client (optional self-host) | Static subdomain or CDN |
| **Element Call / TURN** | Voice/video | Coturn + Element Call config on Synapse |
| **Loom site** | Links + room directory only | Static `website/` deploy |

No Synapse binaries live in this repo. Production deploy of Synapse is **G1** (human approval, backups, legal).

---

## Go-live checklist (coalition operator)

1. Provision VPS or managed Matrix (EU/CH preferred — align with `tooling-decisions.md`).
2. Install Synapse per [Matrix Synapse docs](https://matrix-org.github.io/synapse/latest/setup/installation.html) (Docker common).
3. Register domain e.g. `matrix.loomsite.example` → set `server_name` in Synapse config.
4. Deploy Element Web (optional) or use `app.element.io` with **custom homeserver** URL.
5. Create rooms; set **aliases** (`#loom-gather:your.domain`, etc.).
6. Invite stewards; configure moderation room separately from public Gather room.
7. Update `assets/config/matrix-rooms.json`:
   - `configured`: `true`
   - `homeserverClientBaseUrl`: public HTTPS client API URL
   - `elementWebSelfHosted`: if used
   - Replace `rooms[].alias` with live aliases
   - Remove or set `sample`: false on rooms
8. Run `@skill-code-audit` before exposing public join links if rooms are discoverable.

---

## Files and chat

- **Chat / async:** Matrix rooms (working group, fringe, gather).
- **Calls:** Element Call from room (requires TURN for reliable NAT traversal).
- **Files:** Room uploads suit drafts; **Weaver's Kit** canonical docs stay on **Nextcloud** (public shares linked from `kit.html`). WhatsApp is not used for coalition messaging.

---

## Privacy

- Matrix room membership is **not** anonymous — distinct from public Add a Thread form.
- Document processor/controller in coalition privacy policy when homeserver goes live.
- Do not commit registration shared secrets, `.well-known` private keys, or admin tokens to git.

---

## Local preview

Matrix join buttons stay in **preview mode** until `configured: true`. Test page layout:

```bash
cd website && python3 -m http.server 8080
```

Open http://127.0.0.1:8080/gather.html