Improve docs

.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+name: Publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  docker:
+    name: Publish Docker image
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-09
+
+Initial release.
+
+### Added
+
+- Celery event consumer that appends task and worker events to PostgreSQL as an
+  append-only audit log.
+- Async REST API (FastAPI) for querying task history and performing task,
+  worker, and queue operations.
+- MCP server exposing 28 tools as a thin wrapper over the REST API.
+- Event-sourced task state with timelines, retry chains, and orphan detection.
+- Task actions: revoke, retry, and execute tasks by name.
+- Worker management: list, inspect, scale, restart, and shut down workers.
+- Queue monitoring for any kombu broker (message and consumer counts).
+- Declarative workflow automations (trigger → conditions → actions) with
+  cooldowns, rate limits, and circuit breakers.
+- Prometheus metrics at `/metrics`.
+- Optional API key authentication for the REST API and MCP server.
+- Docker Compose setup with an optional `demo` profile and a bundled demo
+  Celery workload.
+
+[Unreleased]: https://github.com/KalvadTech/taskowl/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/KalvadTech/taskowl/releases/tag/v0.1.0

Dockerfile

@@ -9,6 +9,7 @@ RUN uv sync --locked --no-dev --no-install-project
 
 COPY README.md ./
 COPY src ./src
+COPY examples ./examples
 RUN uv sync --locked --no-dev
 
 EXPOSE 8000

README.md

@@ -1,10 +1,92 @@
-<img src="logo.png" alt="taskowl" width="300"/>
+<img src="logo.png" alt="TaskOwl" width="300"/>
 
-# taskowl
+# TaskOwl
 
-[![Documentation](https://img.shields.io/badge/docs-github_pages-blue)](https://kalvadtech.github.io/taskowl/)
+[![CI](https://github.com/KalvadTech/taskowl/actions/workflows/ci.yml/badge.svg)](https://github.com/KalvadTech/taskowl/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-github_pages-blue)](https://kalvadtech.github.io/taskowl/)
+[![Python 3.14](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue?logo=docker)](https://github.com/KalvadTech/taskowl/pkgs/container/taskowl)
 
-Modern Celery task monitoring with MCP integration. No UI, just data.
+**Celery monitoring for humans and AI agents. No UI, just data.**
+
+Celery gives you workers and tasks. TaskOwl gives you observability, history,
+control, and an AI interface for the whole cluster.
+
+Celery's event stream contains a huge amount of useful operational information,
+but once an event has passed, it is gone. TaskOwl turns that stream into a
+persistent operational history and exposes it through REST and MCP.
+
+## Why TaskOwl?
+
+```
+Celery workers
+      │
+      │ events
+      ▼
+   Broker
+      │
+      ▼
+ TaskOwl Consumer
+      │
+      ▼
+ PostgreSQL
+      │
+      ├── REST API
+      │
+      ├── Prometheus
+      │
+      └── MCP
+            │
+            ▼
+       AI assistant
+```
+
+TaskOwl subscribes to Celery's events, appends every one to PostgreSQL as an
+append-only log, and reconstructs current task, worker, and queue state from it.
+The REST API and the MCP server are thin interfaces over that same data — so
+scripts, automations, and AI agents all get the same capabilities.
+
+It is **not** another Flower. No dashboard to click through; instead, durable
+history and a control plane you can drive programmatically. See
+[Why TaskOwl?](https://kalvadtech.github.io/taskowl/why-taskowl/) for the
+full story.
+
+## Ask your infrastructure
+
+Point any MCP client at TaskOwl and operate the cluster in natural language
+(**28 MCP tools** under the hood):
+
+```text
+You:     Show me failed payment tasks in the last hour.
+
+TaskOwl: 17 failed
+         12 payments.charge
+          3 payments.refund
+          2 payments.capture
+
+         Most common error:
+         ConnectionError: upstream timeout
+```
+
+```text
+You:     Retry the failed payments.charge tasks.
+
+TaskOwl: Retried 12 tasks.
+         Retry chain preserved.
+```
+
+```text
+You:     Which workers are online?
+
+TaskOwl: 3 workers online: celery@worker1, celery@worker2, celery@worker3.
+```
+
+```text
+You:     Restart the pool on celery@worker1.
+
+TaskOwl: Pool restarted on celery@worker1.
+```
 
 ## Features
 
@@ -20,21 +102,56 @@ Modern Celery task monitoring with MCP integration. No UI, just data.
 - **PostgreSQL backend**: Production-ready, async throughout
 - **Broker-agnostic**: RabbitMQ, LavinMQ, Redis, or any Celery/kombu broker
 
-## Documentation
+## Quick Start
 
-The full documentation lives on [GitHub Pages](https://kalvadtech.github.io/taskowl/) —
-setup, configuration, a complete usage guide, and troubleshooting.
+### Try it with Docker (5 minutes)
 
-## Quick Start
+The fastest way to see TaskOwl working is the bundled demo: PostgreSQL,
+RabbitMQ, TaskOwl, a demo Celery worker, and a task producer.
+
+```bash
+git clone https://github.com/KalvadTech/taskowl.git
+cd taskowl
+docker compose --profile demo up --build
+```
 
-### Prerequisites
+TaskOwl is now running:
 
-- Python 3.14+
-- PostgreSQL 14+
-- A Celery broker (RabbitMQ, LavinMQ, Redis, ...)
-- [uv](https://github.com/astral-sh/uv)
+| Service | URL |
+|---|---|
+| REST API | http://localhost:8000 |
+| REST API docs | http://localhost:8000/docs |
+| MCP server | http://localhost:8001/mcp |
+| RabbitMQ management | http://localhost:15672 (guest / guest) |
 
-### Installation
+The demo producer continuously creates tasks (including some that fail), so you
+can start asking questions immediately. For just the infrastructure without the
+demo workload, run `docker compose up --build`.
+
+### Connect an MCP client
+
+The MCP server runs on `http://localhost:8001/mcp` (Streamable HTTP). For
+[opencode](https://opencode.ai):
+
+```json
+{
+  "mcp": {
+    "taskowl": {
+      "type": "remote",
+      "url": "http://localhost:8001/mcp",
+      "enabled": true,
+      "oauth": false
+    }
+  }
+}
+```
+
+Then ask: *"Show me the current tasks."*
+
+### Run from source
+
+Requires Python 3.14+, PostgreSQL 14+, a Celery broker, and
+[uv](https://github.com/astral-sh/uv).
 
 ```bash
 git clone https://github.com/KalvadTech/taskowl.git
@@ -57,7 +174,7 @@ make mcp       # MCP server on :8001
 
 ### Connect your Celery app
 
-taskowl listens to Celery's **events** stream, which workers emit only if enabled:
+TaskOwl listens to Celery's **events** stream, which workers emit only if enabled:
 
 ```python
 # celery_app.py
@@ -76,25 +193,20 @@ Or start your worker with `-E`:
 celery -A myapp worker -E --loglevel=info
 ```
 
-> **Note**: If events are not enabled, taskowl simply sees nothing — no tasks,
+> **Note**: If events are not enabled, TaskOwl simply sees nothing — no tasks,
 > no workers.
 
-### Connect an MCP client
+## Documentation
 
-The MCP server runs on `http://localhost:8001/mcp` (Streamable HTTP). For opencode:
+The full documentation lives on [GitHub Pages](https://kalvadtech.github.io/taskowl/) —
+setup, configuration, a complete usage guide, security, and troubleshooting.
 
-```json
-{
-  "mcp": {
-    "taskowl": {
-      "type": "remote",
-      "url": "http://localhost:8001/mcp",
-      "enabled": true,
-      "oauth": false
-    }
-  }
-}
-```
+## Security
+
+TaskOwl can **operate** your cluster, not just observe it: execute tasks, revoke
+tasks, restart pools, and shut down workers. Authentication is optional and off
+by default — set `API_KEY` before exposing it to any network. See the
+[Security](https://kalvadtech.github.io/taskowl/security/) page.
 
 ## Contributing
 
@@ -108,4 +220,4 @@ MIT — see [LICENSE](LICENSE) for details.
 ## Acknowledgments
 
 - [Flower](https://github.com/mher/flower) — the original Celery monitor
-- [Kanchi](https://github.com/getkanchi/kanchi) — modern Celery monitoring inspiration
+- [Kanchi](https://github.com/getkanchi/kanchi) — modern Celery monitoring inspiration

docker-compose.yml

@@ -43,6 +43,37 @@ services:
       api:
         condition: service_started
 
+  demo-worker:
+    build: .
+    profiles: ["demo"]
+    command:
+      - uv
+      - run
+      - --no-sync
+      - celery
+      - -A
+      - examples.demo.app
+      - worker
+      - -E
+      - --loglevel=info
+    environment:
+      <<: *taskowl-env
+      PYTHONPATH: /app
+    depends_on:
+      rabbitmq:
+        condition: service_healthy
+
+  demo-producer:
+    build: .
+    profiles: ["demo"]
+    command: ["uv", "run", "--no-sync", "python", "-m", "examples.demo.producer"]
+    environment:
+      <<: *taskowl-env
+      PYTHONPATH: /app
+    depends_on:
+      demo-worker:
+        condition: service_started
+
   postgres:
     image: postgres:18.6
     environment:

docs/contributing.md

@@ -1,6 +1,6 @@
 # Contributing
 
-Thank you for your interest in contributing to taskowl!
+Thank you for your interest in contributing to TaskOwl!
 
 ## Development setup