Add MkDocs Material documentation site

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "docs/requirements.txt"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  deploy:
+    name: Deploy Docs
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -33,6 +33,9 @@ Thumbs.db
 *.db-shm
 *.db-wal
 
+# Docs build
+site/
+
 # Build
 dist/
 build/output/

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test test-short lint fmt vet vulncheck clean dev setup docker docker-run helm-lint release-dry
+.PHONY: build test test-short lint fmt vet vulncheck clean dev setup docker docker-run helm-lint release-dry docs docs-serve
 
 # Build variables
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
@@ -84,6 +84,16 @@ release-dry:
 ## check: Run all checks (what CI runs)
 check: fmt vet lint test vulncheck
 
+## docs: Build documentation site
+docs:
+	pip install -q -r docs/requirements.txt
+	mkdocs build --strict
+
+## docs-serve: Serve documentation locally with live reload
+docs-serve:
+	pip install -q -r docs/requirements.txt
+	mkdocs serve
+
 ## help: Show this help
 help:
 	@echo "Usage: make [target]"

docs/admin-api.md

@@ -0,0 +1,67 @@
+# Admin API
+
+Manage budget rules and view API key usage at runtime without restarting the proxy.
+
+## Enable
+
+```yaml
+admin:
+  enabled: true
+  token: "your-secret-admin-token"
+```
+
+## Authentication
+
+All admin endpoints require a Bearer token:
+
+```bash
+curl -H "Authorization: Bearer your-secret-admin-token" \
+  http://localhost:8787/api/admin/budgets/rules
+```
+
+## Endpoints
+
+### Budget Rules
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/admin/budgets/rules` | List all budget rules |
+| `POST` | `/api/admin/budgets/rules` | Create a budget rule |
+| `DELETE` | `/api/admin/budgets/rules?pattern=...` | Delete a rule by pattern |
+
+#### Create a Rule
+
+```bash
+curl -X POST http://localhost:8787/api/admin/budgets/rules \
+  -H "Authorization: Bearer your-secret-admin-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "api_key_pattern": "sk-proj-dev-*",
+    "daily_limit_usd": 5.0,
+    "monthly_limit_usd": 50.0,
+    "action": "block"
+  }'
+```
+
+#### Delete a Rule
+
+```bash
+curl -X DELETE "http://localhost:8787/api/admin/budgets/rules?pattern=sk-proj-dev-*" \
+  -H "Authorization: Bearer your-secret-admin-token"
+```
+
+### API Keys
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/admin/api-keys` | List API key hashes with monthly spend |
+
+### Providers
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/admin/providers` | List provider status |
+
+## Persistence
+
+Runtime rules take effect immediately and persist across restarts. They are stored in the database and take precedence over YAML config rules.

docs/configuration/index.md

@@ -0,0 +1,47 @@
+# Configuration Overview
+
+AgentLedger works out of the box with sensible defaults. All configuration is optional — the proxy starts with OpenAI and Anthropic enabled, SQLite storage, and the dashboard on.
+
+## Config File Locations
+
+AgentLedger looks for config in these locations (in order):
+
+1. Path passed via `--config` / `-c` flag
+2. `./agentledger.yaml`
+3. `./configs/agentledger.yaml`
+4. `~/.config/agentledger/agentledger.yaml`
+5. `/etc/agentledger/agentledger.yaml`
+
+## Minimal Config
+
+No config file is needed for basic usage. To customize:
+
+```yaml
+listen: ":8787"
+
+providers:
+  openai:
+    upstream: "https://api.openai.com"
+    enabled: true
+  anthropic:
+    upstream: "https://api.anthropic.com"
+    enabled: true
+
+storage:
+  driver: "sqlite"
+  dsn: "data/agentledger.db"
+```
+
+## Environment Variable Overrides
+
+All settings can be overridden with environment variables prefixed `AGENTLEDGER_`:
+
+```bash
+AGENTLEDGER_LISTEN=":9090"
+AGENTLEDGER_STORAGE_DSN="/tmp/ledger.db"
+AGENTLEDGER_LOG_LEVEL="debug"
+```
+
+## Full Reference
+
+See [Full Reference](reference.md) for every configuration option with descriptions and defaults.