docs: add stack readmes and overview

README.md

@@ -1,3 +1,48 @@
-# TSYSDevStack
+# 🌐 TSYSDevStack
 
-TSYS Group Development Stack 
+> A constellation of curated stacks that power rapid prototyping, support simulations, developer workspaces, and (soon) lifecycle orchestration for TSYS Group.
+
+---
+
+## 📚 Stack Directory Map
+| Stack | Focus | Highlights | README |
+|-------|-------|------------|--------|
+| 🛰️ CloudronStack | Cloudron application packaging and upstream research. | Catalog of third-party services grouped by capability. | [Open](CloudronStack/README.md) |
+| ♻️ LifecycleStack | Promotion workflows, governance, and feedback loops. | Roadmap placeholders ready for lifecycle charters. | [Open](LifecycleStack/README.md) |
+| 🛟 SupportStack | Demo environment for support tooling (homepage, WakaAPI, MailHog, socket proxy). | Control script automation, Docker Compose bundles, targeted shell tests. | [Open](SupportStack/README.md) |
+| 🧰 ToolboxStack | Reproducible developer workspaces and containerized tooling. | Ubuntu-based dev container with mise, aqua, and helper scripts. | [Open](ToolboxStack/README.md) |
+
+---
+
+## 🚀 Quick Start
+1. **Clone & Inspect**
+   ```bash
+   git clone <repo-url>
+   cd TSYSDevStack
+   tree -L 2   # optional: explore the stack layout
+   ```
+2. **Run the Support Stack Demo**
+   ```bash
+   cd SupportStack
+   ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh start
+   ./output/code/TSYSDevStack-SupportStack-Demo-Control.sh test
+   ```
+   > Uses Docker Compose bundles under `SupportStack/output/docker-compose/`.
+3. **Enter the Toolbox Workspace**
+   ```bash
+   cd ToolboxStack/output/toolbox-base
+   ./build.sh && ./run.sh up
+   docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
+   ```
+
+---
+
+## 🧭 Working Agreement
+- **Stacks stay in sync.** When you add or modify automation, update both the relevant stack README and any linked prompts/docs.
+- **Collab vs Output.** Use `collab/` for planning and prompts, keep runnable artifacts under `output/`.
+- **Document forward.** New workflows should land alongside tests and a short entry in the appropriate README table.
+
+---
+
+## 📄 License
+See [LICENSE](LICENSE) for full terms. Contributions are welcome—open a discussion in the relevant stack’s `collab/` area to kick things off.