feat: rename rails/ to tools/ and add service tool suites (#4)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

tools/orchestrator-matrix/README.md

@@ -0,0 +1,85 @@
+# Mosaic Matrix Orchestrator Rail
+
+Runtime-agnostic orchestration rail for delegating work to worker agents and enforcing
+mechanical quality gates.
+
+## Purpose
+
+- Decouple orchestration from any single agent runtime feature set
+- Persist state in repo-local `.mosaic/orchestrator/` files
+- Emit structured events for Matrix transport and audit trails
+- Enforce rails before marking tasks complete
+
+## Components
+
+- `protocol/` - JSON schemas for task/event payloads
+- `controller/mosaic_orchestrator.py` - deterministic controller loop
+- `adapters/` - runtime adapter guidance
+
+## Repo Contract
+
+The controller expects this layout in each bootstrapped repo:
+
+```text
+.mosaic/orchestrator/
+  config.json
+  tasks.json
+  state.json
+  events.ndjson
+  logs/
+  results/
+```
+
+## Quick Start
+
+From a bootstrapped repo:
+
+```bash
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
+~/.config/mosaic/bin/mosaic-orchestrator-run --once
+~/.config/mosaic/bin/mosaic-orchestrator-drain
+```
+
+Continuous loop:
+
+```bash
+~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+```
+
+Sync from `docs/TASKS.md` to queue:
+
+```bash
+~/.config/mosaic/bin/mosaic-orchestrator-sync-tasks --apply
+```
+
+Set worker command when needed:
+
+```bash
+export MOSAIC_WORKER_EXEC="codex -p"
+# or
+export MOSAIC_WORKER_EXEC="opencode -p"
+```
+
+Publish new orchestrator events to Matrix:
+
+```bash
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
+```
+
+Consume Matrix task messages into `tasks.json`:
+
+```bash
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
+```
+
+## Matrix Note
+
+This rail writes canonical events to `.mosaic/orchestrator/events.ndjson`.
+The Matrix transport bridge publishes those events into the configured control room
+and can consume task commands from that room.
+
+Task injection message format (room text):
+
+```text
+!mosaic-task {"id":"TASK-123","title":"Fix bug","command":"echo run","quality_gates":["pnpm lint"]}
+```