diff --git a/.gitignore b/.gitignore
index 7bbff89..ad8f693 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
 __pycache__/
 *.py[cod]
 .aider*
+
+.idea/
+.vscode/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a9d912f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# Agent System
+
+Distributed multi-agent runtime for the homelab environment.
+
+## Components
+
+- orchestrator
+- node-agent
+- monitor-agent
+- webui
+- redis event bus
+
+## Architecture
+
+The system operates as a lightweight distributed orchestration layer across homelab nodes connected via Tailscale.
+
+SATURN:
+- development
+- orchestration
+- source of truth
+
+SOLARIA:
+- compute workloads
+- GPU tasks
+- inference
+
+PIHA:
+- infrastructure services
+- Forgejo
+- MQTT
+- automation
+
+VPS:
+- public ingress
+- edge services
+
+## Development Flow
+
+1. Develop on SATURN
+2. Commit and push to Forgejo
+3. Execution nodes pull updates
+4. Containers redeploy via docker compose
+
+## Runtime
+
+Current runtime stack:
+- Redis
+- Orchestrator
+- WebUI
+- Monitor Agents
+- Node Agents
+
diff --git a/docker-compose.monitor-agent.yml b/compose/monitor-agent.yml
similarity index 100%
rename from docker-compose.monitor-agent.yml
rename to compose/monitor-agent.yml