chore: recast demo/local as truthful listener-sidecar smoke demo

Remove mock-upstream from default setup flow, fix broken wget-based
metrics check to use port-forward+curl, bound synthetic request timeouts,
correct stale ConfigMap comments in values.yaml, and reframe README as
listener-audit validation with explicit scope boundaries.

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

Author: kernel-gd

demo/local/README.md

@@ -1,9 +1,20 @@
 # Local Cluster Demo
 
-This demo creates a local Kubernetes cluster with kind, installs Koshi in listener mode, deploys a mock upstream and sample workload, sends synthetic traffic, and validates structured events and metrics.
+This demo creates a local kind cluster, installs Koshi in listener mode, injects a sidecar into a sample workload, sends synthetic traffic, and validates that structured events and Prometheus metrics are emitted by the listener sidecar.
 
 > **This demo is for local development and validation only.** It requires a repo checkout, a local Docker build, and a kind cluster. To install Koshi on a real cluster using published artifacts, see [Koshi Onboarding](../../docs/onboarding.md).
 
+## What This Demo Validates
+
+- Sidecar injection via the mutating admission webhook
+- Structured governance events (`stream: "event"`) emitted by the listener
+- Prometheus metrics (`koshi_listener_*`) exposed by the sidecar
+
+## What This Demo Does Not Validate
+
+- Real upstream AI provider responses — the sidecar routes to `api.openai.com` by default. Upstream responses may fail due to auth or connectivity. Demo success is based on listener events and metrics, not upstream response status.
+- Enforcement mode, custom policy, or standalone deployment — this demo is listener-only.
+
 ## Prerequisites
 
 - [Docker](https://docs.docker.com/get-docker/)
@@ -40,42 +51,41 @@ helm install koshi ../../deploy/helm/koshi/ \
   -f values.yaml
 ```
 
-### 3. Deploy the mock upstream
-
-The mock upstream returns OpenAI-shaped responses with token usage data:
+### 3. Label the namespace and deploy a workload
 
 ```bash
-kubectl apply -f mock-upstream.yaml
+kubectl label namespace default runtime.getkoshi.ai/inject=true
+kubectl apply -f workload.yaml
+kubectl wait --for=condition=available deploy/demo-workload -n default --timeout=120s
 ```
 
-### 4. Label the namespace and deploy a workload
+### 4. Verify sidecar injection
 
 ```bash
-kubectl label namespace default runtime.getkoshi.ai/inject=true
-kubectl apply -f workload.yaml
+kubectl get pod -l app=demo-workload -o jsonpath='{.items[0].spec.containers[*].name}'
+# Should include "koshi-listener"
 ```
 
-### 5. Wait for pods and send traffic
+### 5. Send synthetic traffic
 
 ```bash
-kubectl wait --for=condition=ready pod -l app=demo-workload -n default --timeout=120s
-
-# Send a few requests through the sidecar
 kubectl exec deploy/demo-workload -c app -- \
   curl -s -X POST http://localhost:15080/v1/chat/completions \
     -H "Content-Type: application/json" \
     -H "Host: api.openai.com" \
     -d '{"model":"gpt-4","max_tokens":100,"messages":[{"role":"user","content":"hello"}]}'
 ```
 
+The sidecar routes to `api.openai.com` by default. Upstream responses may fail due to auth or connectivity — the listener emits structured events and metrics before upstream proxying, so failures do not affect demo validation. The setup script bounds request time (`--connect-timeout 2 --max-time 5`) for the same reason.
+
 ### 6. Validate structured events
 
 ```bash
 kubectl logs deploy/demo-workload -c koshi-listener --tail=50 | \
   jq 'select(.stream == "event")'
 ```
 
-You should see events with `decision_shadow: "allow"` and shadow fields like `namespace`, `workload_kind`, `provider`.
+You should see events with `decision_shadow` and fields like `namespace`, `workload_kind`, `provider`.
 
 ### 7. Check metrics
 
@@ -95,26 +105,21 @@ Expected metrics:
 curl -s http://localhost:15080/status | jq .
 ```
 
-## What to Look For
+## Notes
 
-- **Events with `"stream": "event"`** — these are the structured governance events
-- **`decision_shadow: "allow"`** — traffic is flowing and passing all checks
-- **`koshi_listener_decisions_total`** — Prometheus counter with namespace and shadow decision labels
-- **No 403/429/503 responses** — listener mode never blocks traffic
+`mock-upstream.yaml` is retained in this directory but is not part of the default demo flow. Injected sidecars use `DefaultListenerConfig()`, which routes to real AI provider APIs — the mock upstream is not reachable without overriding sidecar upstream routing, which is not supported for injected sidecars in the current release.
 
 ## Using Released Artifacts
 
-The local demo above uses a locally built image and a mock upstream. To use published artifacts on a real cluster with real AI API providers:
+To use published artifacts on a real cluster with real AI API providers:
 
 ```bash
 helm install koshi oci://ghcr.io/koshihq/charts/koshi \
   --version 0.2.12 \
   --namespace koshi-system --create-namespace
 ```
 
-Injected sidecars use the built-in default listener config, which routes traffic to `https://api.openai.com` and `https://api.anthropic.com`. The mock-upstream flow in this demo is for local development only — it is not part of the released-artifact validation path.
-
-For partner onboarding on a real cluster, see [Koshi Onboarding](../../docs/onboarding.md).
+For onboarding on a real cluster, see [Koshi Onboarding](../../docs/onboarding.md).
 
 ## Cleanup
 

demo/local/setup.sh

@@ -4,9 +4,20 @@ set -euo pipefail
 CLUSTER_NAME="koshi-demo"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+PORT_FWD_PID=""
+
+cleanup_port_forward() {
+    [ -n "${PORT_FWD_PID}" ] && kill "${PORT_FWD_PID}" 2>/dev/null || true
+    [ -n "${PORT_FWD_PID}" ] && wait "${PORT_FWD_PID}" 2>/dev/null || true
+    PORT_FWD_PID=""
+}
+trap cleanup_port_forward EXIT
 
 echo "=== Koshi Runtime Local Demo ==="
 echo ""
+echo "This demo validates listener-sidecar injection, structured events,"
+echo "and Prometheus metrics on a local kind cluster."
+echo ""
 
 # 1. Create kind cluster.
 if kind get clusters 2>/dev/null | grep -q "^${CLUSTER_NAME}$"; then
@@ -31,13 +42,7 @@ helm upgrade --install koshi "$REPO_ROOT/deploy/helm/koshi/" \
   -f "$SCRIPT_DIR/values.yaml" \
   --wait --timeout 120s
 
-# 4. Deploy mock upstream.
-echo ""
-echo "Deploying mock upstream..."
-kubectl apply -f "$SCRIPT_DIR/mock-upstream.yaml"
-kubectl wait --for=condition=available deploy/mock-upstream -n default --timeout=120s
-
-# 5. Label namespace and deploy workload.
+# 4. Label namespace and deploy workload.
 echo ""
 echo "Labeling default namespace for injection..."
 kubectl label namespace default runtime.getkoshi.ai/inject=true --overwrite
@@ -48,37 +53,88 @@ kubectl apply -f "$SCRIPT_DIR/workload.yaml"
 echo "Waiting for demo workload to be ready..."
 kubectl wait --for=condition=available deploy/demo-workload -n default --timeout=120s
 
+# 5. Verify sidecar injection.
+echo ""
+CONTAINERS=$(kubectl get pod -l app=demo-workload -o jsonpath='{.items[0].spec.containers[*].name}')
+if echo "${CONTAINERS}" | grep -q "koshi-listener"; then
+  echo "PASS: Sidecar injected (containers: ${CONTAINERS})"
+else
+  echo "FAIL: Sidecar not found in pod containers: ${CONTAINERS}"
+  exit 1
+fi
+
 # 6. Send synthetic traffic.
+# The listener emits shadow events and metrics before proxying upstream,
+# so these requests only need to trigger listener-side evaluation.
+# Timeouts are bounded to avoid waiting on upstream auth/connectivity.
+echo ""
+echo "Sending synthetic requests through the sidecar..."
+echo "(Listener events and metrics are emitted before upstream proxying."
+echo " Timeouts are bounded — upstream auth or connectivity failures do not"
+echo " affect demo success.)"
 echo ""
-echo "Sending synthetic requests..."
 for i in 1 2 3; do
   echo "  Request $i..."
   kubectl exec deploy/demo-workload -c app -- \
-    curl -s -X POST http://localhost:15080/v1/chat/completions \
+    curl -s --connect-timeout 2 --max-time 5 \
+      -X POST http://localhost:15080/v1/chat/completions \
       -H "Content-Type: application/json" \
       -H "Host: api.openai.com" \
       -d "{\"model\":\"gpt-4\",\"max_tokens\":100,\"messages\":[{\"role\":\"user\",\"content\":\"hello $i\"}]}" \
-    || echo "  (request $i failed — sidecar may not be injected yet)"
+    > /dev/null 2>&1 || true
   sleep 1
 done
 
-# 7. Validate events.
+# 7. Validate structured events.
 echo ""
 echo "=== Structured Events (stream: event) ==="
-kubectl logs deploy/demo-workload -c koshi-listener --tail=20 2>/dev/null | \
-  jq -c 'select(.stream == "event")' 2>/dev/null || \
-  echo "(no koshi-listener container found — webhook may not have injected the sidecar)"
+EVENTS=$(kubectl logs deploy/demo-workload -c koshi-listener --tail=50 2>/dev/null | \
+  grep '"stream":"event"' || true)
+if [ -n "${EVENTS}" ]; then
+  EVENT_COUNT=$(echo "${EVENTS}" | wc -l | tr -d ' ')
+  echo "PASS: Found ${EVENT_COUNT} structured events"
+  echo "${EVENTS}" | head -3 | jq -c . 2>/dev/null || echo "${EVENTS}" | head -3
+else
+  echo "FAIL: No structured events found in sidecar logs"
+  exit 1
+fi
 
-# 8. Validate metrics.
+# 8. Validate metrics via port-forward.
 echo ""
 echo "=== Listener Metrics ==="
-kubectl exec deploy/demo-workload -c koshi-listener -- \
-  wget -qO- http://localhost:15080/metrics 2>/dev/null | \
-  grep "^koshi_listener" || \
-  echo "(no listener metrics found)"
+kubectl port-forward deploy/demo-workload 15080:15080 >/dev/null 2>&1 &
+PORT_FWD_PID=$!
+
+METRICS=""
+for attempt in $(seq 1 10); do
+  METRICS=$(curl -fsS http://127.0.0.1:15080/metrics 2>/dev/null) && break
+  METRICS=""
+  sleep 1
+done
+
+cleanup_port_forward
+
+if echo "${METRICS}" | grep -q "koshi_listener_decisions_total"; then
+  echo "PASS: Listener metrics present"
+  echo "${METRICS}" | grep "^koshi_listener" | head -5
+else
+  echo "FAIL: koshi_listener_decisions_total not found in metrics output"
+  exit 1
+fi
 
 echo ""
 echo "=== Demo Complete ==="
+echo ""
+echo "What this demo validated:"
+echo "  - Sidecar injection via mutating webhook"
+echo "  - Structured governance events (stream: event) emitted by the listener"
+echo "  - Prometheus metrics (koshi_listener_*) exposed by the sidecar"
+echo ""
+echo "Note: Injected sidecars use the built-in default listener config, which"
+echo "routes to real AI provider APIs. Upstream responses may fail due to auth"
+echo "or connectivity — this does not affect the listener audit signal. Events"
+echo "and metrics are emitted regardless of upstream response status."
+echo ""
 echo "To explore further:"
 echo "  kubectl logs deploy/demo-workload -c koshi-listener | jq 'select(.stream == \"event\")'"
 echo "  kubectl port-forward deploy/demo-workload 15080:15080"

demo/local/teardown.sh

@@ -7,6 +7,7 @@ echo "=== Tearing down Koshi demo ==="
 
 # Remove workloads.
 kubectl delete -f "$(dirname "$0")/workload.yaml" --ignore-not-found 2>/dev/null || true
+# Defensive: clean up mock-upstream if it was deployed manually.
 kubectl delete -f "$(dirname "$0")/mock-upstream.yaml" --ignore-not-found 2>/dev/null || true
 
 # Remove namespace label.

demo/local/values.yaml

@@ -1,5 +1,12 @@
-# Helm values for the local demo.
-# Uses listener mode with the mock upstream.
+# Helm values for the local demo (listener mode).
+#
+# Injected sidecars use DefaultListenerConfig() — the built-in in-memory config
+# that routes to https://api.openai.com and https://api.anthropic.com. Sidecars
+# do NOT read the chart ConfigMap. The values below (config.*) affect only the
+# control-plane ConfigMap, which is used by standalone deployments.
+#
+# This demo validates listener-sidecar injection, structured events, and metrics.
+# It does not deploy a mock upstream or override sidecar upstreams.
 
 mode: listener
 
@@ -21,8 +28,3 @@ sidecar:
     requests:
       cpu: 50m
       memory: 32Mi
-
-# NOTE: The chart's ConfigMap template (templates/configmap.yaml) uses hardcoded
-# listener config and does not template from .Values.config.
-# Upstream overrides for the local demo are applied via the mock-upstream service
-# that the ConfigMap's hardcoded upstream URLs are replaced with at deploy time.