5.2 KiB
Canonical Index: Matrix/Conduit Human-to-Fleet Communication
Issue: #166 — Stand up Matrix/Conduit for human-to-fleet encrypted communication
Scaffold: #183 — Deployment scaffold and host prerequisites
Decisions: #187 — Host / domain / proxy decisions
Created: 2026-04-05 by Ezra, Archivist
Purpose: Single source of truth mapping every #166 artifact. Eliminates navigation friction between deployment docs, client specs, and cutover plans.
Status at a Glance
| Milestone | State | Evidence |
|---|---|---|
| Deployment scaffold | ✅ Complete | infra/matrix/ (15 files) |
| Host readiness checker | ✅ Complete | host-readiness-check.sh |
| Room bootstrap automation | ✅ Complete | scripts/bootstrap-fleet-rooms.py |
| Hermes Matrix client spec | ✅ Complete | docs/matrix-fleet-comms/HERMES_MATRIX_CLIENT_SPEC.md |
| Telegram → Matrix cutover plan | ✅ Complete | docs/matrix-fleet-comms/CUTOVER_PLAN.md |
| Target host selected | ⚠️ BLOCKED | Pending #187 |
| Domain + TLS configured | ⚠️ BLOCKED | Pending #187 |
| Live deployment | ⚠️ BLOCKED | Waiting on #187 |
Verdict: #166 is execution-ready the moment #187 closes with three decisions (host, domain, proxy).
Authoritative Paths
1. Deployment & Operations — infra/matrix/
This directory is the only canonical location for server-side deployment artifacts.
| File | Purpose | Bytes | Status |
|---|---|---|---|
README.md |
Entry point + architecture diagram | 3,275 | ✅ |
prerequisites.md |
Host requirements, ports, DNS decisions | 2,690 | ✅ |
docker-compose.yml |
Conduit + Element + Postgres orchestration | 1,427 | ✅ |
conduit.toml |
Homeserver configuration scaffold | 1,498 | ✅ |
deploy-matrix.sh |
One-command deployment script | 3,388 | ✅ |
host-readiness-check.sh |
Pre-flight validation with colored output | 3,321 | ✅ |
.env.example |
Secrets template | 1,861 | ✅ |
caddy/Caddyfile |
Reverse proxy (Caddy) | ~400 | ✅ |
scripts/bootstrap-fleet-rooms.py |
Automated room creation + agent invites | 8,416 | ✅ |
scripts/deploy-conduit.sh |
Alternative bare-metal Conduit deploy | 5,488 | ✅ |
scripts/validate-scaffold.py |
Scaffold integrity checker | 8,610 | ✅ |
2. Fleet Communication Doctrine — docs/matrix-fleet-comms/
This directory contains human-to-fleet and agent-to-agent communication architecture.
| File | Purpose | Bytes | Status |
|---|---|---|---|
CUTOVER_PLAN.md |
Zero-downtime Telegram → Matrix migration | 4,958 | ✅ |
HERMES_MATRIX_CLIENT_SPEC.md |
matrix-nio integration spec with MWE |
12,428 | ✅ |
EXECUTION_ARCHITECTURE_KT.md |
High-level execution knowledge transfer | 8,837 | ✅ |
DEPLOYMENT_RUNBOOK.md |
Operator-facing deployment steps | 4,484 | ✅ |
README.md |
Fleet comms overview | 7,845 | ✅ |
MATRIX_SCAFFOLD_VERIFICATION.md |
Pre-cutover verification checklist | 3,720 | ✅ |
3. Decision Tracking — #187
All blockers requiring human judgment are centralized in issue #187:
| Decision | Options | Owner |
|---|---|---|
| Host | Hermes VPS / Allegro TestBed / New droplet | @allegro / @timmy |
| Domain | matrix.alexanderwhitestone.com / chat.alexanderwhitestone.com / timmy.alexanderwhitestone.com |
@rockachopa |
| Reverse Proxy | Caddy / Nginx / Traefik | @ezra / @allegro |
Duplicate / Legacy Directory Cleanup
The following directories are superseded by infra/matrix/ and should be removed when convenient:
| Directory | Status | Action |
|---|---|---|
deploy/matrix/ |
Duplicate scaffold | Delete |
deploy/conduit/ |
Alternative Caddy deploy | Delete (merged into infra/matrix/) |
docs/matrix-conduit/ |
Early deployment guide | Delete (merged into infra/matrix/docs/) |
scaffold/matrix-conduit/ |
Superseded scaffold | Delete |
matrix/ |
Minimal old config | Delete |
Execution Sequence (Post-#187)
Once #187 resolves with host/domain/proxy decisions, execute in this exact order:
# 1. Pre-flight
ssh user@<HOST_FROM_187>
cd /opt/timmy-config/infra/matrix
./host-readiness-check.sh <DOMAIN_FROM_187>
# 2. Secrets
cp .env.example .env
# Edit: MATRIX_HOST, POSTGRES_PASSWORD, CONDUIT_REGISTRATION_TOKEN
# 3. Config
# Update server_name in conduit.toml to match DOMAIN_FROM_187
# 4. Deploy
./deploy-matrix.sh <DOMAIN_FROM_187>
# 5. Bootstrap rooms
python3 scripts/bootstrap-fleet-rooms.py --create-all
# 6. Cutover
# Follow: docs/matrix-fleet-comms/CUTOVER_PLAN.md
Accountability
| Role | Owner | Responsibility |
|---|---|---|
| Deployment execution | @allegro / @timmy | Run scripts, provision host |
| Operator onboarding | @rockachopa | Install Element, verify encryption |
| Agent gateway cutover | @ezra | Update Hermes gateway configs |
| Architecture docs | @ezra | Maintain this index and specifications |
Last updated: 2026-04-05 by Ezra, Archivist