docs: add Docker quick-start, demo2 section, fix stale env var names (#21)

docs: Docker quick-start, demo2 section, fix stale AACTL_ env var names. Closes #5, Refs devonartis/agentwrit#31, Refs devonartis/agentwrit#33

Author: devonartis

README.md

@@ -173,27 +173,54 @@ The [`demo/`](demo/) directory contains **MedAssist AI** — an interactive heal
 | **Token lifecycle** | Renewal and release shown at end of each encounter |
 | **Audit trail** | Dedicated audit tab showing hash-chained broker events |
 
-### Running the demo
+### Running with Docker (recommended)
 
 ```bash
-# 1. Start the AgentWrit broker
-docker compose up -d
+AGENTWRIT_ADMIN_SECRET="your-secret" \
+LLM_API_KEY="your-llm-key" \
+docker compose up -d broker medassist
+```
+
+Open [http://localhost:5000](http://localhost:5000). The demo auto-registers with the broker on startup — no manual setup needed. You only need an OpenAI-compatible LLM endpoint (set `LLM_BASE_URL` and `LLM_MODEL` if not using OpenAI).
 
-# 2. Register the demo app with the broker (one-time setup)
+### Running from source
+
+```bash
+# 1. Start the broker
+docker compose up -d broker
+
+# 2. Register the demo app (one-time)
 export AGENTWRIT_ADMIN_SECRET="your-admin-secret"
 uv run python demo/setup.py
-# → Prints client_id and client_secret
 
 # 3. Configure demo/.env (copy from demo/.env.example)
 cp demo/.env.example demo/.env
-# Fill in: broker URL, client_id, client_secret, LLM endpoint
 
 # 4. Run it
 uv run uvicorn demo.app:app --reload --port 5000
-# Open http://127.0.0.1:5000
 ```
 
-For architecture diagrams, step-by-step traces, and a live presentation script, see [`demo/BEGINNERS_GUIDE.md`](demo/BEGINNERS_GUIDE.md) and [`demo/PRESENTERS_GUIDE.md`](demo/PRESENTERS_GUIDE.md).
+For architecture diagrams and a live presentation script, see [`demo/BEGINNERS_GUIDE.md`](demo/BEGINNERS_GUIDE.md) and [`demo/PRESENTERS_GUIDE.md`](demo/PRESENTERS_GUIDE.md).
+
+## Support Ticket Demo
+
+The [`demo2/`](demo2/) directory contains **AgentWrit Live** — a support ticket pipeline where three LLM-driven agents (triage, knowledge, response) process customer requests under zero-trust scoped credentials.
+
+```bash
+AGENTWRIT_ADMIN_SECRET="your-secret" \
+LLM_API_KEY="your-llm-key" \
+docker compose up -d broker support-tickets
+```
+
+Open [http://localhost:5001](http://localhost:5001).
+
+| Capability | How the demo shows it |
+|------------|----------------------|
+| **Identity-gated pipeline** | Anonymous tickets halt at triage — no customer-scoped agents spawn |
+| **Per-customer scope isolation** | Each agent is scoped to the verified customer only |
+| **Cross-customer denial** | Asking about another customer's data → scope denied |
+| **Tool-level enforcement** | `delete_account` and `send_external_email` blocked by scope |
+| **Natural token expiry** | 5-second TTL credential expires on its own |
 
 ## Scope Format
 

docs/sample-app-mini-max.md

@@ -385,21 +385,21 @@ run_pipeline("batch-102")
 **What you learn:** Admin auth is not part of the SDK — it uses raw HTTP or `aactl`. The SDK only handles app-level operations. This app does not use `AgentWritApp`.
 
 **Broker ceiling required:** N/A — no agent scopes, no SDK
-**What it uses:** `AACTL_ADMIN_SECRET` for admin auth. `GET /v1/audit/events` with an admin Bearer token.
+**What it uses:** `AGENTWRIT_ADMIN_SECRET` for admin auth. `GET /v1/audit/events` with an admin Bearer token.
 
 ```python
 # app5_audit_reader.py
 """
 Audit log reader — queries the broker's hash-chained audit trail.
 Shows who did what, when, and whether it succeeded.
 
-Requires admin credentials (AACTL_ADMIN_SECRET). The SDK does not handle admin auth.
+Requires admin credentials (AGENTWRIT_ADMIN_SECRET). The SDK does not handle admin auth.
 """
 import os
 import httpx
 
 BROKER_URL = os.environ["AGENTWRIT_BROKER_URL"]
-ADMIN_SECRET = os.environ["AACTL_ADMIN_SECRET"]
+ADMIN_SECRET = os.environ["AGENTWRIT_ADMIN_SECRET"]
 
 # Step 1: Authenticate as admin (raw HTTP — not part of the SDK)
 auth_resp = httpx.post(
@@ -449,7 +449,7 @@ else:
 
 **The real-world pattern this teaches:**
 - Operators and compliance teams need to query the audit trail programmatically
-- Admin auth uses `AACTL_ADMIN_SECRET` — not part of the SDK, done via raw HTTP or `aactl`
+- Admin auth uses `AGENTWRIT_ADMIN_SECRET` — not part of the SDK, done via raw HTTP or `aactl`
 - Filtering by event type, agent, and time range lets you find specific incidents
 - This is how you build automated compliance reporting
 
@@ -900,8 +900,8 @@ print(f"\nFinal outcome: {outcome}")
 In a second terminal, while the loop is running, revoke the agent:
 
 ```bash
-export AACTL_BROKER_URL="http://localhost:8080"
-export AACTL_ADMIN_SECRET="your-admin-secret"
+export AGENTWRIT_BROKER_URL="http://localhost:8080"
+export AGENTWRIT_ADMIN_SECRET="your-admin-secret"
 aactl revoke --level agent --target "spiffe://agentwrit.local/agent/monitoring-service/continuous-monitor-001/..."
 ```
 

docs/sample-apps-broker-setup.md

@@ -22,8 +22,8 @@ Register the app once. Replace the scopes with what your operator approved.
 ### Option A: Using aactl (recommended)
 
 ```bash
-export AACTL_BROKER_URL="http://localhost:8080"
-export AACTL_ADMIN_SECRET="your-admin-secret"
+export AGENTWRIT_BROKER_URL="http://localhost:8080"
+export AGENTWRIT_ADMIN_SECRET="your-admin-secret"
 
 aactl app register \
   --name sample-apps \
@@ -112,7 +112,7 @@ The pipeline reads from source partitions and writes to destination partitions.
 ```
 Scope ceiling:            N/A — no agent scopes needed
 What it uses:            Admin auth only (aactl or raw HTTP admin API)
-                          POST /v1/admin/auth with AACTL_ADMIN_SECRET
+                          POST /v1/admin/auth with AGENTWRIT_ADMIN_SECRET
                           GET /v1/audit/events with admin Bearer token
 ```
 
@@ -196,6 +196,14 @@ curl -X POST "http://localhost:8080/v1/admin/apps/sample-apps" \
 
 ## Broker Start Command
 
+The recommended way to run the broker is with Docker:
+
+```bash
+AGENTWRIT_ADMIN_SECRET="your-admin-secret" docker compose up -d broker
+```
+
+If running the broker binary directly, set these environment variables. Note: the broker binary currently uses the `AA_` prefix for its env vars ([rename tracked in devonartis/agentwrit#44](https://github.com/devonartis/agentwrit/issues/44)):
+
 ```bash
 AA_ADMIN_SECRET="your-admin-secret" \
 AA_DB_PATH="/tmp/agentwrit.db" \
@@ -204,8 +212,8 @@ AA_MAX_TTL="600" \
 ./broker
 ```
 
-| Flag | Purpose |
-|------|---------|
+| Variable | Purpose |
+|----------|---------|
 | `AA_ADMIN_SECRET` | Admin password for operator tasks (app registration, revocation, audit) |
 | `AA_DB_PATH` | SQLite database path — audit log and revocation data |
 | `AA_DEFAULT_TTL` | Default agent token TTL in seconds (300 = 5 minutes) |
@@ -237,7 +245,7 @@ aactl app list
 |--------|-------|-----|
 | `401` on app auth | Wrong `client_id` or `client_secret` | Re-register the app and save the credentials |
 | `403` on agent creation | Requested scope outside app ceiling | Extend the app ceiling with `aactl app update`, or narrow the requested scope |
-| `403` on admin auth | Wrong `AACTL_ADMIN_SECRET` | Restart the broker with the correct secret |
+| `403` on admin auth | Wrong `AGENTWRIT_ADMIN_SECRET` | Restart the broker with the correct secret |
 | `Connection refused` | Broker not running | `./broker` or `docker compose up` |
 | App 5 returns empty events | Admin token expired | Re-run the aactl command or re-authenticate |
 | App 9 shows all `PASS` | Ceiling is too wide — all test scopes are allowed | Narrow the ceiling so `admin:revoke:*` and `read:logs:*` are outside it |