docs: README — dashboard overview, tech stack, API surface

README.md

@@ -1,3 +1,66 @@
-# damascus-dashboard
+# Damascus Dashboard
 
-Dashboard chat UI for Damascus agent orchestration
+Chat-first web dashboard for the Damascus agent orchestration framework.
+
+**Talk to your agents. See who's online. Browse personas and skills.**
+
+---
+
+## Features
+
+- **Agent roster** — green dot = online, gray = offline. Click to chat.
+- **Live chat** — message bubbles with color-coded responses (output, tool calls, errors)
+- **Persona viewer** — click any agent to see their YAML frontmatter + markdown body
+- **Skills browser** — see what tools each skill requires and its full instructions
+- **Health bar** — PostgreSQL + Redis status, worker count, latencies
+
+## Tech stack
+
+- **Solid.js** — 7KB reactive framework, signals-based
+- **Vite** — fast dev server + bundler
+- **Tailwind CSS** — utility-first styling
+- **Zero new backend dependencies** — talks to the existing `damascus-v3` API
+
+## Quick start
+
+```bash
+npm install
+npm run dev        # → http://localhost:5173
+```
+
+Requires a running `damascus-v3` API server (the dashboard proxies to it).
+
+## Project structure
+
+```
+src/
+├── App.tsx              # Root layout
+├── components/
+│   ├── AgentList.tsx    # Sidebar — agent roster with status dots
+│   ├── ChatView.tsx     # Main area — message bubbles + input
+│   ├── PersonaPanel.tsx # Slide-out — persona YAML + markdown
+│   ├── SkillsPanel.tsx  # Slide-out — skills with tool requirements
+│   ├── EventFeed.tsx    # Optional — live event log
+│   └── HealthBar.tsx    # Top bar — PG/Redis status + worker count
+├── api.ts               # Fetch wrappers for the damascus-v3 API
+└── index.tsx            # Entry point
+```
+
+## API (provided by damascus-v3)
+
+| Endpoint | What it returns |
+|---|---|
+| `GET /health` | PG + Redis probe results with latencies |
+| `GET /workers` | Active BullMQ workers with agent IDs |
+| `GET /status` | Agent activity counts (last hour) |
+| `GET /events` | Event log with filters |
+| `POST /send` | Enqueue a message to an agent |
+| `GET /persona/:id` | Persona YAML frontmatter + markdown body |
+| `GET /skills/:agentId` | Loaded skills for a specific agent |
+
+## Related repos
+
+| Repo | Purpose |
+|---|---|
+| [damascus-v3](https://git.homelab.local/kaykayyali/damascus-v3) | Agent engine (TypeScript, BullMQ, PostgreSQL) |
+| [damascus-frontier](https://git.homelab.local/kaykayyali/damascus-frontier) | Deployment CLI + `damascus.yaml` config → Docker Compose |