timmy-config/docs/matrix-fleet-comms/EXECUTION_ARCHITECTURE_KT.md

# Execution Architecture KT — Matrix/Conduit Human-to-Fleet Comms

**Issue**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166)  
**Blocker**: [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) — Host/domain/proxy decisions  
**Scaffold**: [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183)  
**Created**: Ezra | 2026-04-05  
**Purpose**: Turn the #166 fuzzy epic into an exact execution script. Once #187 closes, follow this KT verbatim.

---

## Executive Summary

This document is the **knowledge transfer** from architecture (#183) to execution (#166). It assumes the decision framework in `docs/DECISION_FRAMEWORK_187.md` has been accepted (recommended: **Option A — Hermes VPS + Caddy + matrix.timmytime.net**) and maps every step from "DNS record exists" to "Alexander sends an encrypted message to the fleet."

---

## Pre-Conditions (Close #187 First)

| # | Pre-Condition | Authority | Evidence |
|---|---------------|-----------|----------|
| 1 | Host chosen (IP known) | Alexander/admin | Written in #187 |
| 2 | Domain/subdomain chosen | Alexander/admin | DNS A record live |
| 3 | Reverse proxy chosen | Alexander/admin | Caddyfile committed |
| 4 | Ports 80/443/8448 open | Host admin | `host-readiness-check.sh` passes |
| 5 | TLS path confirmed | Architecture | Let's Encrypt viable |

> **If all 5 are true, #166 is unblocked and this KT is the runbook.**

---

## Phase 1: Host Prep (30 minutes)

### 1.1 Clone Repo on Target Host
```bash
ssh root@<HOST_IP>
git clone https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config.git /opt/timmy-config
cd /opt/timmy-config/infra/matrix
```

### 1.2 Verify Host Readiness
```bash
./host-readiness-check.sh
```
Expected: all checks green (Docker, ports, disk, RAM).

### 1.3 Configure Environment
```bash
cp .env.example .env
# Edit .env:
#   CONDUIT_SERVER_NAME=matrix.timmytime.net
#   CONDUIT_ALLOW_REGISTRATION=true   # ONLY for bootstrap
```

---

## Phase 2: Conduit Deployment (15 minutes)

### 2.1 One-Command Deploy
```bash
./deploy-matrix.sh
```
This starts:
- Conduit homeserver container
- Caddy reverse proxy container
- (Optional) Element web client

### 2.2 Verify Health
```bash
curl -s https://matrix.timmytime.net/_matrix/client/versions | jq .
```
Expected: JSON with `versions` array.

### 2.3 Verify Federation
```bash
curl -s https://matrix.timmytime.net/.well-known/matrix/server
```
Expected: `{"m.server": "matrix.timmytime.net:443"}`

---

## Phase 3: Fleet Bootstrap — Accounts & Rooms (30 minutes)

### 3.1 Create Admin Account
**Enable registration temporarily** in `.env`:
```
CONDUIT_ALLOW_REGISTRATION=true
CONDUIT_REGISTRATION_TOKEN=<random_secret>
```
Restart:
```bash
docker compose restart conduit
```

Register admin:
```bash
docker exec -it conduit register_new_matrix_user   -c /var/lib/matrix-conduit   -u admin   -p '<STRONG_PASS>'   -a
```

**Immediately disable registration** and restart.

### 3.2 Create Fleet Accounts
| Account | Purpose | Created By |
|---------|---------|------------|
| `@admin:matrix.timmytime.net` | Server administration | deploy script |
| `@alexander:matrix.timmytime.net` | Human operator | admin |
| `@timmy:matrix.timmytime.net` | Coordinator bot | admin |
| `@ezra:matrix.timmytime.net` | Archivist bot | admin |
| `@allegro:matrix.timmytime.net` | Dispatch bot | admin |
| `@bezalel:matrix.timmytime.net` | Dev bot | admin |
| `@gemini:matrix.timmytime.net` | Nexus architect bot | admin |

Use the Conduit admin API or `register_new_matrix_user` for each.

### 3.3 Create Fleet Rooms
| Room Alias | Purpose | Encryption |
|------------|---------|------------|
| `#fleet-ops:matrix.timmytime.net` | Operator commands | ✅ E2E |
| `#fleet-intel:matrix.timmytime.net` | Deep Dive briefings | ✅ E2E |
| `#fleet-social:matrix.timmytime.net` | General chat | ✅ E2E |
| `#fleet-alerts:matrix.timmytime.net` | Critical alerts | ✅ E2E |

**Create room via Element Web or curl:**
```bash
curl -X POST   "https://matrix.timmytime.net/_matrix/client/v3/createRoom"   -H "Authorization: Bearer <ADMIN_TOKEN>"   -d '{
    "name": "Fleet Ops",
    "room_alias_name": "fleet-ops",
    "preset": "private_chat",
    "initial_state": [{
      "type": "m.room.encryption",
      "content": {"algorithm": "m.megolm.v1.aes-sha2"}
    }]
  }'
```

### 3.4 Invite Fleet Members
Invite each bot/user to the appropriate rooms. For `#fleet-ops`, restrict to `@alexander`, `@timmy`, `@ezra`, `@allegro`.

---

## Phase 4: Wizard Onboarding Procedure (30 minutes)

Each wizard house needs:
1. **Matrix credentials** (username + password + recovery key)
2. **Client recommendation** — Element Desktop or Fluffychat
3. **Room memberships** — invite to relevant fleet rooms
4. **Encryption verification** — verify keys with Alexander

### Onboarding Checklist per Wizard
- [ ] Account created and credentials stored in vault
- [ ] Client installed and signed in
- [ ] Joined `#fleet-ops` and `#fleet-intel`
- [ ] E2E verification completed with `@alexander`
- [ ] Test message sent and received

---

## Phase 5: Telegram → Matrix Cutover Architecture

### 5.1 Parallel Operations (Week 1-2)
- Telegram remains primary
- Matrix is shadow channel: duplicate critical messages to both
- Bots post to Matrix for habit formation

### 5.2 Bridge Option (Evaluative)
If immediate message parity is required, evaluate:
- **mautrix-telegram** bridge (self-hosted, complex)
- **Manual dual-post** (simple, temporary)

**Recommendation**: Skip the bridge for now. Dual-post via bot logic is lower risk.

### 5.3 Cutover Trigger
When:
- All wizards are active on Matrix
- Alexander confirms Matrix reliability for 7 consecutive days
- E2E encryption verified in `#fleet-ops`

**Action**: Declare Matrix the primary human-to-fleet surface. Telegram becomes fallback only.

---

## Operational Continuity

### Backup
```bash
# Daily cron on host
0 2 * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh backup
```

### Monitoring
```bash
# Health check every 5 minutes
*/5 * * * * /opt/timmy-config/infra/matrix/scripts/deploy-conduit.sh status || alert
```

### Upgrade Path
1. Pull latest `timmy-config`
2. Run `./host-readiness-check.sh`
3. `docker compose pull && docker compose up -d`

---

## Acceptance Criteria Mapping

| #166 Criterion | How This KT Satisfies It | Phase |
|----------------|--------------------------|-------|
| Deploy Conduit homeserver | `deploy-matrix.sh` + health checks | 2 |
| Create fleet rooms/channels | Exact room aliases + creation curl | 3 |
| Verify encrypted operator messaging | E2E enabled + key verification step | 3-4 |
| Define Telegram→Matrix cutover plan | Section 5 explicit cutover trigger | 5 |
| Alexander can message fleet | `@alexander` account + `#fleet-ops` membership | 3 |
| Messages encrypted and persistent | `m.room.encryption` in room creation + Conduit persistence | 3 |
| Telegram no longer only surface | Cutover trigger + dual-post interim | 5 |

---

## Decision Authority for Execution

| Step | Owner | When |
|------|-------|------|
| DNS / #187 close | Alexander | T+0 |
| Run `deploy-matrix.sh` | Allegro or Ezra | T+0 (15 min) |
| Create accounts/rooms | Allegro or Ezra | T+15 (30 min) |
| Onboard wizards | Individual agents + Alexander | T+45 (ongoing) |
| Cutover declaration | Alexander | T+7 days (minimum) |

---

## References

- Scaffold: [`infra/matrix/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix)
- ADRs: [`infra/matrix/docs/adr/`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/adr)
- Decision Framework: [`docs/DECISION_FRAMEWORK_187.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/DECISION_FRAMEWORK_187.md)
- Operational Runbook: [`infra/matrix/docs/RUNBOOK.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/docs/RUNBOOK.md)
- **Room Bootstrap Automation**: [`infra/matrix/scripts/bootstrap-fleet-rooms.py`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/infra/matrix/scripts/bootstrap-fleet-rooms.py)
- **Telegram Cutover Plan**: [`docs/matrix-fleet-comms/CUTOVER_PLAN.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/matrix-fleet-comms/CUTOVER_PLAN.md)
- **Scaffold Verification**: [`docs/matrix-fleet-comms/MATRIX_SCAFFOLD_VERIFICATION.md`](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/src/branch/main/docs/matrix-fleet-comms/MATRIX_SCAFFOLD_VERIFICATION.md)

---

**Ezra Sign-off**: This KT removes all ambiguity from #166. The only remaining work is executing these phases in order once #187 is closed. Room creation and Telegram cutover are now automated.

— Ezra, Archivist  
2026-04-05