# Telegram → Matrix Cutover Plan

> **Issue**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166) — Stand up Matrix/Conduit for human-to-fleet encrypted communication  
> **Scaffold**: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)  
> **Created**: Ezra, Archivist | Date: 2026-04-05  
> **Purpose**: Zero-downtime migration from Telegram to Matrix as the sovereign human-to-fleet command surface.

---

## Principle

**Parallel operation first, cutover second.** Telegram does not go away until every agent confirms Matrix connectivity and Alexander has sent at least one encrypted message from Element.

---

## Phase 0: Pre-Conditions (All Must Be True)

| # | Condition | Verification Command |
|---|-----------|---------------------|
| 1 | Conduit deployed and healthy | `curl https://<domain>/_matrix/client/versions` |
| 2 | Fleet rooms created | `python3 infra/matrix/scripts/bootstrap-fleet-rooms.py --dry-run` |
| 3 | Alexander has Element client installed | Visual confirmation |
| 4 | At least 3 agents have Matrix accounts | `@agentname:<domain>` exists |
| 5 | Hermes Matrix gateway configured | `hermes gateway` shows Matrix platform |

---

## Phase 1: Parallel Run (Days 1–7)

### Day 1: Room Bootstrap

```bash
# 1. SSH to Conduit host
cd /opt/timmy-config/infra/matrix

# 2. Verify health
./host-readiness-check.sh

# 3. Create rooms (dry-run first)
export MATRIX_HOMESERVER="https://matrix.timmytime.net"
export MATRIX_ADMIN_TOKEN="<admin_access_token>"
python3 scripts/bootstrap-fleet-rooms.py --create-all --dry-run

# 4. Create rooms (live)
python3 scripts/bootstrap-fleet-rooms.py --create-all
```

### Day 1: Operator Onboarding

1. Open Element Web at `https://element.<domain>` or install Element desktop.
2. Register/login as `@alexander:<domain>`.
3. Join `#fleet-ops:<domain>`.
4. Send a test message: `First light on Matrix. Acknowledge, fleet.`

### Days 2–3: Agent Onboarding

For each agent/wizard house:
1. Create Matrix account `@<agent>:<domain>`.
2. Join `#fleet-ops:<domain>` and `#fleet-general:<domain>`.
3. Send acknowledgment in `#fleet-ops`.
4. Update agent's Hermes gateway config to listen on Matrix.

### Days 4–6: Parallel Commanding

- **Alexander sends all commands in BOTH Telegram and Matrix.**
- Agents respond in the channel where they are most reliable.
- Monitor for message loss or delivery delays.

---

## Phase 2: Cutover (Day 7)

### Step 1: Pin Matrix as Primary

In Telegram `#fleet-ops`:
> "📌 PRIMARY SURFACE CHANGE: Matrix is now the sovereign command channel. Telegram remains as fallback for 48 hours. Join: `<matrix_invite_link>`"

### Step 2: Telegram Gateway Downgrade

Edit each agent's Hermes gateway config:

```yaml
# ~/.hermes/config.yaml
gateway:
  primary_platform: matrix
  fallback_platform: telegram
  matrix:
    enabled: true
    homeserver: https://matrix.timmytime.net
    rooms:
      - "#fleet-ops:matrix.timmytime.net"
  telegram:
    enabled: true  # Fallback only
```

### Step 3: Verification Checklist

- [ ] Alexander sends command **only** on Matrix
- [ ] All agents respond within 60 seconds
- [ ] Encrypted room icon shows 🔒 in Element
- [ ] No messages lost in 24-hour window
- [ ] At least one voice/file message test succeeds

### Step 4: Telegram Standby

If all checks pass:
1. Pin final notice in Telegram: "Fallback mode only. Active surface is Matrix."
2. Disable Telegram bot webhooks (do not delete the bot).
3. Update Commandment 6 documentation to reflect Matrix as sovereign surface.

---

## Rollback Plan

If Matrix becomes unreachable or messages are lost:

1. **Immediate**: Alexander re-sends command in Telegram.
2. **Within 1 hour**: All agents switch gateway primary back to Telegram:
   ```yaml
   primary_platform: telegram
   ```
3. **Within 24 hours**: Debug Matrix issue (check Conduit logs, Caddy TLS, DNS).
4. **Re-attempt cutover** only after root cause is fixed and parallel run succeeds for another 48 hours.

---

## Post-Cutover Maintenance

| Task | Frequency | Command / Action |
|------|-----------|------------------|
| Backup Conduit data | Daily | `tar czvf /backups/conduit-$(date +%F).tar.gz /opt/timmy-config/infra/matrix/data/conduit/` |
| Review room membership | Weekly | Element → Room Settings → Members |
| Update Element Web | Monthly | `docker compose pull && docker compose up -d` |
| Rotate access tokens | Quarterly | Element → Settings → Help & About → Access Token |

---

## Accountability

| Role | Owner | Responsibility |
|------|-------|----------------|
| Deployment | @allegro / @timmy | Run `deploy-matrix.sh` and room bootstrap |
| Operator onboarding | @rockachopa (Alexander) | Install Element, verify encryption |
| Agent gateway cutover | @ezra | Update Hermes gateway configs, monitor logs |
| Rollback decision | @rockachopa | Authorize Telegram fallback if needed |

---

*Filed by Ezra, Archivist | 2026-04-05*