# Canonical Index: Matrix/Conduit Deployment Artifacts

> **Issues**: [#166](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/166) (Execution Epic) | [#183](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/183) (Scaffold — Closed) | [#187](http://143.198.27.163:3000/Timmy_Foundation/timmy-config/issues/187) (Decision Blocker)  
> **Created**: 2026-04-05 by Ezra (burn mode)  
> **Purpose**: Single source of truth mapping every Matrix/Conduit artifact in `timmy-config`. Stops scatter, eliminates "which file is real?" ambiguity.

---

## Status at a Glance

| Milestone | State | Evidence |
|-----------|-------|----------|
| Deployment scaffold | ✅ Complete | `infra/matrix/` (15 files) |
| Operator runbook | ✅ Complete | `docs/matrix-fleet-comms/` |
| Host readiness script | ✅ Complete | `infra/matrix/host-readiness-check.sh` |
| Target host selected | ⚠️ **BLOCKED** | Pending [#187](../issues/187) |
| Live deployment | ⚠️ **BLOCKED** | Waiting on host + domain + proxy decision |

---

## Authoritative Paths (Read/Edit These)

### 1. Deployment Scaffold — `infra/matrix/`
This is the **primary executable scaffold**. If you are deploying Conduit, start here and nowhere else.

| File | Purpose | Lines/Size |
|------|---------|------------|
| `README.md` | Entry point, quick-start, architecture diagram | 3,275 bytes |
| `prerequisites.md` | 6 concrete blocking items pre-deployment | 2,690 bytes |
| `docker-compose.yml` | Conduit + Postgres + optional Element Web | 1,427 bytes |
| `conduit.toml` | Base Conduit configuration template | 1,498 bytes |
| `.env.example` | Environment secrets template | 1,861 bytes |
| `deploy-matrix.sh` | One-command deployment orchestrator | 3,388 bytes |
| `host-readiness-check.sh` | Pre-flight validation script | 3,321 bytes |
| `caddy/Caddyfile` | Reverse-proxy rules for Caddy users | 1,612 bytes |
| `conduit/conduit.toml` | Advanced Conduit config (federation-ready) | 2,280 bytes |
| `conduit/docker-compose.yml` | Extended compose with replication | 1,469 bytes |
| `scripts/deploy-conduit.sh` | Low-level Conduit installer | 5,488 bytes |
| `docs/RUNBOOK.md` | Day-2 operations (backup, upgrade, health) | 3,412 bytes |

**Command for next deployer:**
```bash
cd infra/matrix
./host-readiness-check.sh   # 1. verify target
# Edit conduit.toml + .env
./deploy-matrix.sh          # 2. deploy
```

### 2. Operator Runbook — `docs/matrix-fleet-comms/`
Human-facing narrative for Alexander and operators.

| File | Purpose | Size |
|------|---------|------|
| `README.md` | Fleet communications authority map + onboarding | 7,845 bytes |
| `DEPLOYMENT_RUNBOOK.md` | Step-by-step operator playbook | 4,484 bytes |

---

## Legacy / Duplicate Paths (Do Not Edit — Reference Only)

The following directories contain **overlapping or superseded** material. They exist for historical continuity but are **not** the current source of truth. If you edit these, you create divergence.

| Path | Status | Note |
|------|--------|------|
| `deploy/matrix/` | 🔴 Superseded by `infra/matrix/` | Smaller subset; lacks host-readiness check |
| `deploy/conduit/` | 🔴 Superseded by `infra/matrix/scripts/` | `install.sh` + `health.sh` — good ideas ported into `infra/matrix/` |
| `matrix/` | 🔴 Superseded by `infra/matrix/` | Early docker-compose experiment |
| `docs/matrix-conduit/DEPLOYMENT.md` | 🔴 Superseded by `docs/matrix-fleet-comms/DEPLOYMENT_RUNBOOK.md` | |
| `docs/matrix-deployment.md` | 🔴 Superseded by `infra/matrix/prerequisites.md` + runbook | |
| `scaffold/matrix-conduit/` | 🔴 Superseded by `infra/matrix/` | Bootstrap + nginx configs; nginx approach not chosen |

> **House Rule**: New Matrix work must branch from `infra/matrix/` or `docs/matrix-fleet-comms/`. If a legacy file needs resurrection, migrate it into the authoritative tree and delete the old reference.

---

## Decision Blocker: #187

**#166 cannot proceed until [#187](../issues/187) is resolved.**

Ezra has produced a dedicated decision framework to make this a 5-minute choice rather than an architectural debate:

📄 **See**: [`docs/DECISION_FRAMEWORK_187.md`](DECISION_FRAMEWORK_187.md)

The framework recommends:
- **Host**: Timmy-Home bare metal (primary) or existing VPS
- **Domain**: `matrix.timmytime.net` (or sub-domain of existing fleet domain)
- **Proxy**: Caddy (simplest) or extend existing Traefik
- **TLS**: Let's Encrypt ACME HTTP-01 (port 80/443 open)

---

## Next Agent Checklist

If you are picking up #166:

1. [ ] Read `infra/matrix/README.md`
2. [ ] Read `docs/DECISION_FRAMEWORK_187.md`
3. [ ] Confirm resolution of #187 (host/domain/proxy chosen)
4. [ ] Run `infra/matrix/host-readiness-check.sh` on target host
5. [ ] Cut a feature branch; edit `infra/matrix/conduit.toml` and `.env`
6. [ ] Execute `infra/matrix/deploy-matrix.sh`
7. [ ] Verify federation with Matrix.org test server
8. [ ] Create operator room; invite Alexander
9. [ ] Post SITREP on #166 with proof-of-deployment

---

## Changelog

| Date | Change | Author |
|------|--------|--------|
| 2026-04-05 | Canonical index created; authoritative paths declared | Ezra |