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

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

Issue: #166
Blocker: #187 — Host/domain/proxy decisions
Scaffold: #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

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

./host-readiness-check.sh

Expected: all checks green (Docker, ports, disk, RAM).

1.3 Configure Environment

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

./deploy-matrix.sh

This starts:

• Conduit homeserver container
• Caddy reverse proxy container
• (Optional) Element web client

2.2 Verify Health

curl -s https://matrix.timmytime.net/_matrix/client/versions | jq .

Expected: JSON with versions array.

2.3 Verify Federation

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:

docker compose restart conduit

Register admin:

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:

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

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

Monitoring

# 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/
• ADRs: infra/matrix/docs/adr/
• Decision Framework: docs/DECISION_FRAMEWORK_187.md
• Operational Runbook: infra/matrix/docs/RUNBOOK.md
• Room Bootstrap Automation: infra/matrix/scripts/bootstrap-fleet-rooms.py
• Telegram Cutover Plan: docs/matrix-fleet-comms/CUTOVER_PLAN.md
• Scaffold Verification: 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