timmy-config/infra/matrix/CANONICAL_INDEX.md

# Canonical Index: Matrix/Conduit Human-to-Fleet Communication

> **Issue**: [#166](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/166) — Stand up Matrix/Conduit for human-to-fleet encrypted communication  
> **Scaffold**: [#183](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/183) — Deployment scaffold and host prerequisites  
> **Decisions**: [#187](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-config/issues/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:

```bash
# 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*