docs: update README with experimental banner, badges, and accurate prerequisites

The Quick Start and prerequisites were outdated — they still referenced
propolis as a sibling directory requirement, but `task build` now
auto-downloads the runtime from GitHub Releases. Also fixes Go version
(1.25.7 → 1.26), adds CI/license/Go badges, a TOC, contributing
section, experimental warning banner, and a health check verification
step. Updates docs/DEVELOPMENT.md to match.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: JAORMX

CLAUDE.md

@@ -27,7 +27,7 @@ Run a single test: `go test -v -race -run TestName ./pkg/path/to/package`
 
 ## Things That Will Bite You
 
-- **propolis is a tagged dependency (v0.0.15)**: `task build` embeds propolis-runner, libkrun, and libkrunfw into the binary (downloaded via `task fetch-runtime`/`task fetch-firmware`, verified with sha256sums). Use `build-dev-system` for the system libkrun-devel path.
+- **propolis is a tagged dependency (v0.0.16)**: `task build` embeds propolis-runner, libkrun, and libkrunfw into the binary (downloaded via `task fetch-runtime`/`task fetch-firmware`, verified with sha256sums). Use `build-dev-system` for the system libkrun-devel path.
 - **Image cache and log level**: `WAGGLE_IMAGE_CACHE_DIR` (default `~/.cache/waggle/images/`) enables shared OCI image cache with layer-level caching and COW rootfs cloning. `WAGGLE_IMAGE_CACHE_MAX_AGE` (default `168h`/7d) controls eviction. `WAGGLE_LOG_LEVEL` (0-5, default 0) sets libkrun verbosity; levels > 3 leak hypervisor internals.
 - **Layered images**: Runtime images (python/node/shell) inherit from `images/base/` via `ARG BASE_IMAGE`. Build base first: `task build-image-base`. All runtime image tasks depend on it automatically.
 - **MCP error handling has two paths**: Return `mcp.NewToolResultError("msg"), nil` for user-facing errors (bad input, not found). Return `nil, err` only for internal server failures. Mixing these up breaks the MCP protocol.

README.md

@@ -1,9 +1,30 @@
 # Waggle
 
+[![Build](https://github.com/stacklok/waggle/actions/workflows/build.yml/badge.svg)](https://github.com/stacklok/waggle/actions/workflows/build.yml)
+[![Tests](https://github.com/stacklok/waggle/actions/workflows/test.yml/badge.svg)](https://github.com/stacklok/waggle/actions/workflows/test.yml)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Go](https://img.shields.io/github/go-mod/go-version/stacklok/waggle)](go.mod)
+
+> [!WARNING]
+> **Experimental** — Waggle is under active development. APIs, configuration, and behavior may change without notice. Use at your own risk and expect breaking changes between releases.
+
 An MCP server that gives AI agents their own isolated coding environments. Each environment is a real microVM — spin one up, write code, execute it, install packages, read results, tear it down. All through 8 simple MCP tools.
 
 > The waggle dance is one of the most fascinating things in nature — bees encode distance, direction, and quality of resources in a figure-eight dance pattern. Waggle encodes execution environments, runs code, and communicates structured results back to the AI.
 
+## Table of Contents
+
+- [What It Looks Like](#what-it-looks-like)
+- [MCP Tools](#mcp-tools)
+- [Why MicroVMs](#why-microvms)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Security](#security)
+- [Runtime Images](#runtime-images)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## What It Looks Like
 
 When an AI agent connects to Waggle, it gets tools to create and use isolated environments. Here's a typical interaction:
@@ -101,31 +122,29 @@ The trade-off is startup time (seconds vs milliseconds), but you get a real Linu
 
 ## Quick Start
 
+### Prerequisites
+
+- [Go](https://go.dev/dl/) 1.26+
+- [Task](https://taskfile.dev/) (`go install github.com/go-task/task/v3/cmd/task@latest`)
+- [GitHub CLI](https://cli.github.com/) (`gh`) — used to download the propolis runtime
+- KVM access on Linux (`/dev/kvm`) or Hypervisor.framework on macOS
+
+### Build and Run
+
 ```bash
-# Clone alongside propolis (required as sibling directory)
-cd ~/Development/stacklok
 git clone https://github.com/stacklok/waggle.git
-
-# Build
 cd waggle
-task build
-
-# Optional: override runtime images
-# export WAGGLE_IMAGE_PYTHON=ghcr.io/stacklok/waggle/python:latest
-# export WAGGLE_IMAGE_NODE=ghcr.io/stacklok/waggle/node:latest
-# export WAGGLE_IMAGE_SHELL=ghcr.io/stacklok/waggle/shell:latest
-task run
+task build    # Downloads propolis runtime + firmware, builds a self-contained binary
+task run      # Starts the MCP server
 ```
 
 The server starts on `127.0.0.1:8080` with the MCP endpoint at `/mcp` (Streamable HTTP transport).
 
-### Prerequisites
+Verify it's running:
 
-- Go 1.25.7+, [Task](https://taskfile.dev/)
-- [propolis](https://github.com/stacklok/propolis) checked out at `../propolis`
-- `propolis-runner` binary in PATH (see propolis docs)
-- libkrun (Linux: `libkrun-devel`, macOS: Homebrew)
-- KVM access on Linux (`/dev/kvm`) or Hypervisor.framework on macOS
+```bash
+curl -s http://127.0.0.1:8080/healthz
+```
 
 ## Configuration
 
@@ -208,6 +227,18 @@ task verify   # Full CI gate (fmt + lint + test)
 
 See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the DDD layer breakdown and [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full dev guide.
 
+## Contributing
+
+Contributions are welcome! Whether it's bug reports, feature requests, or pull requests — all contributions help.
+
+To get started with development:
+
+```bash
+task verify   # Full CI gate: format, lint, test
+```
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full development guide, including how to add new MCP tools and runtimes.
+
 ## License
 
-Apache-2.0 — see [LICENSE](LICENSE).
+This project is licensed under the Apache 2.0 License — see the [LICENSE](LICENSE) file for details.

docs/DEVELOPMENT.md

@@ -4,14 +4,19 @@
 
 | Requirement | Purpose |
 |-------------|---------|
-| Go 1.25.7+ | Language runtime |
+| [Go](https://go.dev/dl/) 1.26+ | Language runtime |
 | [Task](https://taskfile.dev/) | Build system (`go install github.com/go-task/task/v3/cmd/task@latest`) |
+| [GitHub CLI](https://cli.github.com/) (`gh`) | Downloads propolis runtime from GitHub Releases |
 | [golangci-lint](https://golangci-lint.run/) | Linting |
 | [goimports](https://pkg.go.dev/golang.org/x/tools/cmd/goimports) | Import formatting |
-| [propolis](https://github.com/stacklok/propolis) | VM substrate (checked out as sibling directory) |
-| libkrun-devel | VM hypervisor (Linux: `dnf install libkrun-devel`, macOS: `brew install libkrun`) |
 | KVM access | Linux: ensure `/dev/kvm` is accessible to your user |
 
+For the `build-dev-system` target (builds propolis-runner from source instead of downloading):
+
+| Requirement | Purpose |
+|-------------|---------|
+| libkrun-devel | VM hypervisor (Linux: `dnf install libkrun-devel`, macOS: `brew install libkrun`) |
+
 ## Repository Layout
 
 ```
@@ -36,16 +41,13 @@ waggle/
 ├── docs/                       # Architecture and development docs
 ├── Taskfile.yaml               # Build system
 ├── CLAUDE.md                   # AI assistant instructions
-└── go.mod                      # Go module (with propolis replace)
+└── go.mod                      # Go module
 ```
 
 ## Getting Started
 
 ```bash
-# Ensure propolis is checked out alongside waggle
-ls ../propolis/go.mod  # Should exist
-
-# Build
+# Build (automatically downloads propolis runtime + firmware from GitHub Releases)
 task build
 
 # Run tests