Add MkDocs documentation setup with Material theme

work-queue-webui/docs/api.md

@@ -0,0 +1,134 @@
+# API Reference
+
+Base URL: `http://app-01:8080`
+
+## Work Items
+
+### GET /work
+
+List work items with optional filters.
+
+**Query Parameters:**
+- `status` — filter by status (`queued`, `dispatched`, `in_progress`, `completed`, `failed`, `blocked`, `cancelled`)
+- `agent` — filter by assigned agent
+- `project_id` — filter by project
+- `since` — ISO8601 timestamp, returns items created after this time
+- `type` — filter by work item type
+
+**Response:** `200 OK`
+```json
+[
+  {
+    "id": "uuid",
+    "type": "string",
+    "description": "string",
+    "priority": 1-5,
+    "status": "string",
+    "assigned_agent": "string",
+    "created_at": "ISO8601",
+    "updated_at": "ISO8601",
+    "outcome": "success|failure|cancelled|null",
+    "notes": "string|null"
+  }
+]
+```
+
+---
+
+### POST /work
+
+Submit a new work item.
+
+**Request Body:**
+```json
+{
+  "type": "string",
+  "description": "string",
+  "priority": 1-5,
+  "agent": "string (optional)",
+  "project_id": "uuid (optional)",
+  "payload": {}
+}
+```
+
+**Response:** `201 Created`
+
+---
+
+### PATCH /work/{id}
+
+Update a work item's status, outcome, notes, or agent.
+
+**Request Body:**
+```json
+{
+  "status": "string (optional)",
+  "outcome": "success|failure|cancelled (required if terminal status)",
+  "notes": "string (optional)",
+  "agent": "string (optional)"
+}
+```
+
+**Response:** `200 OK`
+
+---
+
+## Projects
+
+### GET /projects
+
+List all projects.
+
+**Response:** `200 OK`
+```json
+[
+  {
+    "id": "uuid",
+    "name": "string",
+    "external_ref": "string|null",
+    "created_at": "ISO8601"
+  }
+]
+```
+
+---
+
+### POST /projects
+
+Create a new project.
+
+**Request Body:**
+```json
+{
+  "name": "string",
+  "external_ref": "string (optional)"
+}
+```
+
+**Response:** `201 Created`
+
+---
+
+## WorkItem Shape
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `uuid` | Unique identifier |
+| `type` | `string` | Work category |
+| `description` | `string` | Task description |
+| `priority` | `integer` | 1 (highest) to 5 (lowest) |
+| `status` | `string` | Current lifecycle state |
+| `assigned_agent` | `string\|null` | Assigned agent username |
+| `created_at` | `ISO8601` | Creation timestamp |
+| `updated_at` | `ISO8601` | Last update timestamp |
+| `outcome` | `string\|null` | `success`, `failed`, or `cancelled` |
+| `notes` | `string\|null` | Optional notes |
+
+## Status Lifecycle
+
+```
+queued → dispatched → in_progress → completed
+                              ↘ blocked
+                              ↘ failed
+           ↘ cancelled (from queued or dispatched only)
+```

work-queue-webui/docs/guide.md

@@ -0,0 +1,39 @@
+# User Guide
+
+## How the Queue System Works
+
+TheLab's work queue system dispatches tasks to autonomous agents. Each work item has a lifecycle:
+
+```
+queued → dispatched → in_progress → completed
+                              ↘ blocked
+                              ↘ failed
+           ↘ cancelled (from queued or dispatched only)
+```
+
+## Viewing the Queue
+
+On the main dashboard you can see:
+- **Queued** — work items waiting for an agent
+- **In Progress** — items currently being worked on
+- **Completed** — finished items with outcomes
+
+## Work Item Fields
+
+| Field | Description |
+|---|---|
+| `id` | Unique identifier (UUID) |
+| `type` | Category: `code_review`, `bug_fix`, `infra_setup`, etc. |
+| `description` | Human-readable task description |
+| `priority` | 1 (highest) to 5 (lowest) |
+| `status` | Current lifecycle state |
+| `assigned_agent` | Agent currently handling the item |
+| `outcome` | `success`, `failed`, or `cancelled` |
+| `created_at` | ISO8601 timestamp |
+
+## Agents
+
+Agents are autonomous workers assigned to the queue. Each agent picks up dispatched items and works through them one at a time. Current agents:
+
+- **lennie-s** — infrastructure and tooling tasks
+- **steve-w** — general development tasks

work-queue-webui/docs/index.md

@@ -0,0 +1,20 @@
+# Work Queue WebUI
+
+A web interface for managing TheLab's distributed work queue system.
+
+## Overview
+
+The Work Queue WebUI provides a visual interface for monitoring and managing work items dispatched to agents across TheLab's infrastructure. It connects to the [Work Queue API](https://git.danhenry.dev/thelab/work-queue-api) and presents queue state in real time.
+
+## Quick Start
+
+1. Open the WebUI in your browser
+2. View active work items and their current status
+3. Monitor agent activity and queue depth
+
+## Features
+
+- Real-time queue status monitoring
+- Agent activity tracking
+- Work item lifecycle visibility
+- Project-based work organization

work-queue-webui/mkdocs.yml

@@ -0,0 +1,35 @@
+site_name: Work Queue WebUI
+site_description: Web interface for TheLab Work Queue system
+site_url: https://git.danhenry.dev/thelab/work-queue-webui
+
+repo_name: thelab/work-queue-webui
+repo_url: https://git.danhenry.dev/thelab/work-queue-webui
+
+theme:
+  name: material
+  palette: 
+    - media: "(prefers-color-scheme: light)"
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+nav:
+  - Home: index.md
+  - User Guide: guide.md
+  - API Reference: api.md
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+  - pymdownx.superfences
+  - admonition
+  - toc:
+      permalink: true