docs: narrow public claims to match current sidecar architecture

The README hero sentence, ROADMAP, and annotation table overstated
the listener-to-enforcement transition for injected sidecars. Sidecars
use DefaultListenerConfig() and do not read the charted ConfigMap, so
enforcement is not yet "a config change" for the primary use case.

- Scope enforcement-as-config-change claim to standalone deployments
- Remove "same metrics" (listener and enforcement use different families)
- Mark runtime.getkoshi.ai/policy as not functional for injected sidecars
  in the current default install path
- Qualify "unknown workload gets 403" by mode (enforcement only)
- Add default/configurable qualifiers to all hardcoded 15080 references
- Fix stale 1.0.0 version examples in validate-release.sh

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

Author: kernel-gd

README.md

@@ -2,7 +2,7 @@
 
 Koshi Runtime is a workload-scoped governance plane for AI systems. It deploys as a Kubernetes sidecar that enforces deterministic policy at the workload boundary — token budgets, per-request guards, and tiered enforcement decisions — using reservation-first accounting.
 
-**Discover your governance posture before enforcing it.** Koshi ships in **listener mode** by default: the full enforcement pipeline — identity resolution, policy lookup, guard evaluation, budget accounting — executes on every request, but no traffic is blocked. Shadow decisions (`would_reject`, `would_throttle`, `would_kill`) reveal exactly where your policies would intervene. When the posture matches your intent, enabling enforcement is a config change — same binary, same pipeline, same metrics.
+**Discover your governance posture before enforcing it.** Koshi ships in **listener mode** by default: the full enforcement pipeline — identity resolution, policy lookup, guard evaluation, budget accounting — executes on every request, but no traffic is blocked. Shadow decisions (`would_reject`, `would_throttle`, `would_kill`) reveal exactly where your policies would intervene. When the posture matches your intent, enforcement uses the same binary and Helm chart. For standalone deployments, enabling enforcement is a config change. For injected sidecars, sidecar-level enforcement is planned for a future release — see [Enabling Enforcement](#enabling-enforcement).
 
 **No repo clone required.** Install Koshi directly from the published OCI Helm chart and container image.
 
@@ -24,7 +24,7 @@ kubectl rollout restart deployment -n my-namespace
 kubectl logs -n my-namespace deploy/my-app -c koshi-listener --tail=100 | \
   jq 'select(.stream == "event")'
 
-# 5. Check metrics
+# 5. Check metrics (default sidecar port; adjust if you changed sidecar.port)
 kubectl port-forward -n my-namespace deploy/my-app 15080:15080
 curl http://localhost:15080/metrics | grep koshi_listener
 ```
@@ -34,7 +34,7 @@ curl http://localhost:15080/metrics | grep koshi_listener
 - Install Koshi in listener mode — one Helm command, no repo clone or config files required
 - Label any namespace and restart workloads to get sidecars injected
 - Collect structured JSON events from `koshi-listener` container logs
-- Scrape Prometheus metrics from `/metrics` on port `15080`
+- Scrape Prometheus metrics from `/metrics` on the sidecar port (default `15080`, configurable via `sidecar.port`)
 - Observe real shadow decisions (`allow`, `would_throttle`, `would_kill`, `would_reject`) on live traffic without blocking anything
 
 ### What Traffic Produces Signal
@@ -63,7 +63,7 @@ Workloads produce governance signal when they send OpenAI- or Anthropic-compatib
 | NetworkPolicy | `koshi-system` | Restricts injector ingress to apiserver, sidecar egress to upstreams |
 
 The sidecar (`koshi-listener`) is injected into workload pods automatically. It:
-- Listens on `:15080` (configurable)
+- Listens on `:15080` by default (configurable via `sidecar.port` Helm value)
 - Exposes `/metrics`, `/healthz`, `/readyz`, `/status`
 - Receives traffic via `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` env vars injected into app containers
 
@@ -257,7 +257,7 @@ Key Helm values:
 | Annotation | Values | Description |
 |------------|--------|-------------|
 | `runtime.getkoshi.ai/inject` | `"false"` | Opt out a specific pod from injection |
-| `runtime.getkoshi.ai/policy` | policy ID | Override the default policy for this pod's sidecar |
+| `runtime.getkoshi.ai/policy` | policy ID | Per-workload policy override. Not functional for injected sidecars in the current default install path — the built-in default config does not include named policies, so setting this annotation will cause the sidecar to fail at startup. Planned for a future release. |
 
 ## Health Endpoints
 
@@ -311,7 +311,7 @@ Listener mode is designed for discovering your governance posture. Injected side
 - **Webhook `failurePolicy: Ignore`.** If the injector is down, pods still create — they just don't get the sidecar.
 - **Base-URL injection is safe.** `OPENAI_BASE_URL` / `ANTHROPIC_BASE_URL` are only set on app containers if not already present. See [What Traffic Produces Signal](#what-traffic-produces-signal) for implications when these vars are already defined.
 - **Reservation-first accounting.** Tokens are reserved before the request and reconciled with actual usage after the response.
-- **Fail open on infrastructure, fail closed on policy.** A panic triggers degraded pass-through mode. An unknown workload gets 403.
+- **Fail open on infrastructure, fail closed on policy.** A panic triggers degraded pass-through mode. In enforcement mode, an unknown workload gets 403. In listener mode, unknown workloads emit `would_reject` and traffic proxies through.
 
 ## Uninstall / Rollback
 

ROADMAP.md

@@ -8,7 +8,7 @@ Koshi Runtime is a Kubernetes-native runtime substrate that sits at the workload
 
 - **Listener-first adoption.** Discover your governance posture at the execution boundary before enforcing it. The full enforcement pipeline runs on every request in listener mode, emitting structured events and metrics that reveal exactly where policies would intervene — without blocking traffic.
 - **Structured governance signals.** Every request produces a machine-readable decision with a stable reason code — identity resolution, policy lookup, per-request guards, rolling budget accounting, and tiered enforcement.
-- **Config-driven mode switching.** The same binary and image supports both listener and enforcement modes. Moving from observation to enforcement is a config change, not a new deployment.
+- **Config-driven mode switching.** The same binary and image supports both listener and enforcement modes. For standalone deployments, moving from observation to enforcement is a config change. For injected sidecars, enforcement and config delivery to sidecars are planned for a future release.
 - **Auditable, reversible, bounded behavior.** Reservation-first token accounting with reconciliation. Deterministic enforcement decisions. Safe defaults that fail open on infrastructure and fail closed on policy.
 
 ## Available Now
@@ -19,7 +19,7 @@ Koshi Runtime is a Kubernetes-native runtime substrate that sits at the workload
 - **Reservation-first token accounting** — budget pre-deducted before proxying, reconciled with actual usage after response. Rolling window with optional burst. Budget floor at zero.
 - **Stable reason codes** — machine-readable codes on all decisions and error responses: `identity_missing`, `policy_not_found`, `guard_max_tokens`, `budget_exhausted_throttle`, `budget_exhausted_kill`, and others.
 - **Helm chart with safe defaults** — NetworkPolicy, PodDisruptionBudget, security context (read-only root, non-root, drop all capabilities), self-signed webhook cert generation.
-- **Enforcement mode** — same binary, activated by config. Identity via HTTP header, per-workload policy binding, tiered decisions (allow, throttle, kill).
+- **Enforcement mode** — same binary, activated by config. Currently available for standalone deployments; injected-sidecar enforcement is planned. Identity via HTTP header, per-workload policy binding, tiered decisions (allow, throttle, kill).
 - **Design documentation** — formal specifications for [deterministic accounting invariants](docs/design/koshi-v1-deterministic-accounting-invariants.md), [enforcement boundary](docs/design/koshi-v1-enforcement-boundary.md), [operator trust guarantees](docs/design/koshi-v1-operator-trust-guarantees.md), and [why Koshi exists](docs/design/koshi-v1-why-koshi-exists.md).
 
 ## Next

docs/kubernetes-observability.md

@@ -73,7 +73,7 @@ The webhook injects scrape annotations on workload pods:
 
 ```yaml
 prometheus.io/scrape: "true"
-prometheus.io/port: "15080"
+prometheus.io/port: "15080"   # Matches sidecar.port Helm value (default)
 prometheus.io/path: "/metrics"
 ```
 

docs/onboarding.md

@@ -43,6 +43,7 @@ kubectl logs -n <namespace> deploy/<your-app> -c koshi-listener --tail=50 | \
 **Confirm the metrics endpoint is reachable:**
 
 ```bash
+# Default sidecar port; adjust if you changed sidecar.port in your Helm values
 kubectl port-forward -n <namespace> deploy/<your-app> 15080:15080
 curl -s http://localhost:15080/metrics | grep koshi_listener
 ```
@@ -66,7 +67,7 @@ Koshi outputs two signal types. Any observability tool that ingests these format
 - Fields: `namespace`, `workload_kind`, `workload_name`, `provider`, `decision_shadow`, `reason_code`, `estimated_tokens`, `actual_tokens`
 
 **Prometheus metrics:**
-- Source: `:15080/metrics` on each sidecar
+- Source: `/metrics` on each sidecar (default port `15080`, configurable via `sidecar.port`)
 - Series: `koshi_listener_decisions_total`, `koshi_listener_tokens_total`, `koshi_listener_latency_seconds`
 - Labels: `namespace`, `decision_shadow`, `reason_code`, `provider`, `phase`
 

scripts/validate-release.sh

@@ -8,13 +8,13 @@ set -euo pipefail
 #   ./scripts/validate-release.sh <chart-version> <image-tag> [image-repo]
 #
 # Arguments:
-#   chart-version  Helm chart version (e.g. 1.0.0)
-#   image-tag      Image tag (e.g. v1.0.0)
+#   chart-version  Helm chart version (e.g. 0.2.12)
+#   image-tag      Image tag (e.g. v0.2.12)
 #   image-repo     Image repository (default: ghcr.io/koshihq/koshi-runtime)
 #
 # Examples:
-#   ./scripts/validate-release.sh 1.0.0 v1.0.0
-#   ./scripts/validate-release.sh 1.0.0 v1.0.0 docker.io/koshihq/koshi-runtime
+#   ./scripts/validate-release.sh 0.2.12 v0.2.12
+#   ./scripts/validate-release.sh 0.2.12 v0.2.12 docker.io/koshihq/koshi-runtime
 
 CHART_VERSION="${1:?Usage: validate-release.sh <chart-version> <image-tag> [image-repo]}"
 IMAGE_TAG="${2:?Usage: validate-release.sh <chart-version> <image-tag> [image-repo]}"