jwbron · jwbron · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/Makefile b/Makefile
@@ -597,11 +597,13 @@ k3s-secrets:  ## Create gateway secrets from ~/.config/egg/
 	@if [ ! -f "$$HOME/.config/egg/launcher-secret" ]; then \
 		echo "ERROR: $$HOME/.config/egg/launcher-secret not found."; \
 		echo "Run 'bin/egg-deploy init' to generate it."; \
+		echo "Or generate it directly: openssl rand -hex 32 > $$HOME/.config/egg/launcher-secret"; \
 		exit 1; \
 	fi
 	@if [ ! -f "$$HOME/.config/egg/lifecycle-secret" ]; then \
 		echo "ERROR: $$HOME/.config/egg/lifecycle-secret not found."; \
-		echo "Generate it: openssl rand -hex 32 > $$HOME/.config/egg/lifecycle-secret"; \
+		echo "Run 'bin/egg-deploy init' to generate it."; \
+		echo "Or generate it directly: openssl rand -hex 32 > $$HOME/.config/egg/lifecycle-secret"; \
 		exit 1; \
 	fi
 	@echo "==> Creating gateway-secrets in egg-system namespace..."

diff --git a/config/README.md b/config/README.md
@@ -29,16 +29,19 @@ All persistent user configuration is consolidated under `~/.config/egg/`:
 
 ```
 ~/.config/egg/
-├── config.yaml        # All non-secret settings (compose, ports, identity, etc.)
-├── secrets.env        # All secrets (Slack, GitHub, Confluence, JIRA tokens)
-├── launcher-secret    # Gateway launcher secret (dedicated file)
-├── github-token       # GitHub token (dedicated file)
-├── github-app-id      # GitHub App ID (if using App auth)
+├── config.yaml                 # All non-secret settings (compose, ports, identity, etc.)
+├── secrets.env                 # All secrets (Slack, GitHub, Confluence, JIRA tokens)
+├── launcher-secret             # Gateway launcher secret — required for k8s deploys; make k3s-secrets aborts without it (bin/egg-deploy init or bin/egg-init generates it)
+├── lifecycle-secret            # Orchestrator lifecycle-control auth token — required for k8s deploys; make k3s-secrets aborts without it (bin/egg-deploy init or bin/egg-init generates it)
+├── github-token                # GitHub token (dedicated file)
+├── github-app-id               # GitHub App ID (if using App auth)
 ├── github-app-installation-id  # GitHub App Installation ID
-├── github-app.pem     # GitHub App private key (bot identity)
-├── reviewer-app.pem   # Reviewer GitHub App private key (optional, for separate reviewer bot)
-├── npm-packages-token # Optional: read-only token for the GitHub Packages npm read-through
-└── repositories.yaml  # Repository access configuration (created by setup.py)
+├── github-app.pem              # GitHub App private key (bot identity)
+├── reviewer-app.pem            # Optional: reviewer GitHub App private key, for a separate reviewer bot identity
+├── npm-packages-token          # Optional: read-only token for the GitHub Packages npm read-through
+├── litellm-models.yaml         # Optional: host-side LiteLLM model_list overlay, applied by make litellm-config (copy from config/litellm-models.template.yaml)
+├── routing-policy.yaml         # Optional: gateway routing policy — switchover remaps + fallback chains, hot-reloaded by make routing-policy (copy from config/routing-policy.template.yaml)
+└── repositories.yaml           # Repository access configuration (created by setup.py)
 ```
 
 ### npm-packages-token (Optional)

diff --git a/docs/development/STRUCTURE.md b/docs/development/STRUCTURE.md
@@ -534,16 +534,22 @@ Key workflows for PR automation (see `.github/workflows/` for complete list):
 
 ```
 config/
-├── config.yaml.example          # Configuration template (copy to ~/.config/egg/config.yaml)
-├── repositories.yaml.example    # Repository access configuration template
-├── secrets.template.env         # Secrets template (includes Jira credential placeholders)
-├── context-filters.yaml         # Operator allowlists for external integrations (jira.projects)
-├── litellm-models.template.yaml # Operator template for registering non-Claude backends (copy to ~/.config/egg/litellm-models.yaml)
-├── litellm/                     # egg-litellm image sources
-│   ├── Dockerfile               # Builds egg-litellm: stock LiteLLM + prompt-cache patches
-│   ├── patch_litellm_cache.py   # Build-time patches for cache_control passthrough on Qwen/DeepSeek routes
-│   └── cost_callback.py         # LiteLLM custom logger: upstream + estimated cost, per-role attribution (x-egg-* headers), cache hit rate, per-call decoding config -> pod stdout
-├── repo_config.py               # Python API for repo access
+├── config.yaml.example               # Configuration template (copy to ~/.config/egg/config.yaml)
+├── repositories.yaml.example         # Repository access configuration template
+├── secrets.template.env              # Secrets template (includes Jira credential placeholders)
+├── context-filters.yaml              # Operator allowlists for external integrations (jira.projects)
+├── litellm-models.template.yaml      # Operator template for registering non-Claude backends (copy to ~/.config/egg/litellm-models.yaml)
+├── routing-policy.template.yaml      # Operator template for the gateway's hot-reloadable model routing policy: switchover remaps + fallback chains (copy to ~/.config/egg/routing-policy.yaml)
+├── litellm/                          # egg-litellm image sources
+│   ├── Dockerfile                    # Builds egg-litellm: stock LiteLLM + prompt-cache and reasoning-parameter patches
+│   ├── patch_litellm_cache.py        # Build-time patches: cache_control passthrough on Qwen/DeepSeek routes, live OpenRouter capability lookup, drop_params visibility, no synthesized reasoning ceiling
+│   ├── openrouter_capabilities.py    # Patch 7: live GET /api/v1/models capability lookup, unioned with LiteLLM's bundled model-cost map
+│   ├── drop_params_visibility.py     # Patch 8: warn once per proxy process per (provider, model, param-set) when drop_params discards a parameter
+│   ├── anthropic_thinking_policy.py  # Patch 9: stop synthesizing a reasoning_effort ceiling from the caller's thinking budget on non-Claude models
+│   └── cost_callback.py              # LiteLLM custom logger: upstream + estimated cost, per-role attribution (x-egg-* headers), cache hit rate, per-call decoding config -> pod stdout
+├── redis/                            # egg-redis image sources
+│   └── Dockerfile                    # Builds egg-redis: pinned stock Redis, repackaged for the local build/publish supply chain; backs the orchestrator's Redis Streams message store
+├── repo_config.py                    # Python API for repo access
 └── README.md
 ```
 

diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
@@ -357,14 +357,26 @@ For reproducible builds, pin to an exact version tag.
 | `~/.config/egg/config.yaml` | Non-secret settings for compose |
 | `repositories.yaml` | Repository configuration |
 
+### Required for k8s Deployments
+
+Both are generated by `bin/egg-deploy init` (or `bin/egg-init`), and on the
+k8s path both are hard requirements rather than optional: `make k3s-secrets`
+— the first recipe line of `make deploy` — aborts if either is missing. The
+compose path does not require them; it picks `launcher-secret` up as
+`EGG_LAUNCHER_SECRET` when the file happens to exist.
+
+| File | Purpose |
+|------|---------|
+| `launcher-secret` | Gateway authentication token |
+| `lifecycle-secret` | Orchestrator lifecycle-control auth token |
+
 ### Optional Files
 
 | File | Purpose |
 |------|---------|
 | `secrets.env` | Additional secrets (GitHub App credentials) |
-| `launcher-secret` | Gateway authentication token |
-| `lifecycle-secret` | Orchestrator lifecycle-control auth token (required for k8s deployments) |
 | `litellm-models.yaml` | Host-side LiteLLM `model_list` overlay; copy from `config/litellm-models.template.yaml` (see [Per-Agent Models](per-agent-models.md)) |
+| `routing-policy.yaml` | Gateway routing policy — switchover remaps + fallback chains; copy from `config/routing-policy.template.yaml`, hot-reloaded by `make routing-policy` ([details above](#make-deploy-details)) |
 
 ## Health Checks
 

diff --git a/docs/guides/per-agent-models.md b/docs/guides/per-agent-models.md
@@ -668,9 +668,23 @@ data:
 >   provider's and can change under you with no egg change.
 > - **It is read after `drop_params` has acted**, so it reports what the wire
 >   carried, not what your config asked for. A knob you set in
->   `litellm_params` that does not appear here was silently discarded or
->   relocated into `extra_body` by LiteLLM's parameter mapper — which is the
->   fastest way to catch a tuning change that never took effect.
+>   `litellm_params` that does not appear here was discarded or relocated
+>   into `extra_body` by LiteLLM's parameter mapper. Patch 8
+>   (`drop_params_visibility.py`) also logs a `litellm.drop_params: dropped
+>   ...` warning once per (provider, model, param-set) combo, for as long as
+>   the proxy's bookkeeping set holds that combo, naming the params and — when
+>   they came from this model's `litellm_params` — the `allowed_openai_params`
+>   remedy, so a drop is visible in the log stream rather than only inferable
+>   from `request_params`. Note the asymmetry when you go looking: that warning
+>   is a one-shot per combo, not per request — a proxy discarding different
+>   param sets across several models emits one warning each, but not a second
+>   for the same combo while the bookkeeping set still holds it — so on a pod
+>   that has been serving traffic it has likely already scrolled past (it
+>   re-fires after a proxy restart, and in cycles on a proxy dropping params
+>   across more than 1000 distinct combos, whose bookkeeping set clears on
+>   overflow — an intra-process clear, so an already-warned combo warns
+>   again). By contrast `request_params` is on every `cost_callback` line and
+>   stays the queryable signal.
 > - **A `<…>` value is a degradation marker, not a recorded value.** Every
 >   field is bounded so one pathological param cannot cost you the line —
 >   cost data included — when it fails to serialize. `<N chars omitted>` means