@ccoalm/ccl-skills 0.1.0

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/dual-sidecar-and-traffic-config-center.md

@@ -0,0 +1,127 @@
+# Dual Sidecar + Traffic Config Center
+
+Two mature patterns observed in production platforms that complement the canonical mesh model.
+
+## Dual sidecar (mesh + platform)
+
+A pod may run two sidecars besides the app container:
+
+```
+Pod
+├─ app                    business code, ports 8888 (server) / 8889 (grpc reflection)
+├─ <platform-sidecar>     framework helper, port 18888
+│                         responsibilities: service discovery client cache,
+│                                            local SDK companion, log-shipping
+│                                            adapter, framework-only metrics
+└─ <mesh-sidecar>         Envoy / Linkerd / etc, mTLS + traffic policy
+                          (optional per protocol — see below)
+```
+
+The platform sidecar is **not** a replacement for the mesh sidecar. It owns concerns the mesh cannot see:
+
+| Concern | Owner |
+|---|---|
+| mTLS, retries, transport timeouts | Mesh sidecar (Envoy) |
+| Service discovery client cache | Platform sidecar |
+| Framework-only metrics emission | Platform sidecar |
+| Per-application config/secret companion | Platform sidecar |
+| Stress/shadow traffic tag handling at app layer | Platform sidecar |
+
+If you do not need a platform sidecar (no shared SD cache, no framework companion), do not deploy one. A single mesh sidecar plus a thick SDK in the app is the cheaper baseline.
+
+## Mesh injection by protocol
+
+Mesh injection is not all-or-nothing. Real platforms apply per-protocol policy:
+
+| App protocol | Inject Istio sidecar? | Reason |
+|---|---|---|
+| HTTP (REST) | YES | Envoy handles HTTP/1.1, HTTP/2; full feature support |
+| gRPC | YES | HTTP/2 + per-call routing; needs `:authority` quirk handling |
+| TCP (raw) | NO (often) | Envoy TCP proxy is feature-poor; routing/auth less useful at L4 |
+| Thrift (TTHeader) | NO (often) | Same — L4-ish; tooling limited |
+
+Express via pod annotations:
+
+```yaml
+annotations:
+  sidecar.istio.io/inject: "{{ if has protocol "http" "grpc" }}true{{ else }}false{{ end }}"
+```
+
+For services with mixed protocols (rare), default to inject and design the bypass at the listener.
+
+## Traffic config center (separate from mesh routing)
+
+A platform may want **per-caller-callee** traffic policy (timeouts, retry, circuit-breaker thresholds, hedging windows) that mesh DestinationRule cannot express (DR is per-callee, not per-pair).
+
+The pattern:
+
+```
+Operator
+   │ updates pair policy via control-plane API
+   ▼
+Control plane
+   │ writes to config center (dcc / Apollo / Consul KV / etcd KV)
+   │ keyed by (caller_psm, callee_psm)
+   ▼
+Config center
+   │ pushes updates to subscribers
+   ▼
+Framework client SDK in every caller service
+   │ subscribes to its own outbound pairs
+   │ applies new policy at next call (no restart)
+```
+
+Payload shape per pair:
+
+```yaml
+ServiceTrafficConfig:
+  caller_psm: <psm>
+  callee_psm: <psm>
+  content:
+    timeout_ms: <int>
+    retry_attempts: <int>
+    retry_backoff_ms: <int>
+    circuit_breaker:
+      consecutive_5xx: <int>
+      eject_seconds: <int>
+    hedging:
+      enabled: <bool>
+      delay_ms: <int>
+```
+
+Why per-pair, not per-callee:
+- Different callers may have different criticality. The user-facing service might accept 200ms timeout calling the search service; the batch job calling the same search service may accept 5s.
+- Retry budgets are per-caller — uniform per-callee retry can amplify load from a single misbehaving caller.
+
+Write concurrency control:
+- Per-pair Redis lock (lease longer than the maximum write duration; renew via heartbeat if needed).
+- **Lock lease MUST exceed worst-case fanout time.** A 10s lease with a 2-min fanout window means lock A can expire mid-flight, operator B acquires the lock and writes, then A's late write overwrites B silently. Either: (a) make the lease longer than the fanout timeout, OR (b) renew the lease via heartbeat during the operation, OR (c) use fencing tokens — every write to the config center includes the lock's fencing token; the config center rejects writes with a stale token. Option (c) is the only one that's correct under all timing edge cases; (a) and (b) are pragmatic for shorter operations.
+- **Prefer config-center-native CAS over external locks** where the backend supports it. etcd's `mod_revision` precondition on `Put` (transaction with `Compare(mod_revision)`) is the cleanest fencing primitive — the write fails if anyone else wrote since the read.
+- Updates fan out via WaitGroup with concurrency limit (e.g. 20) and total timeout (e.g. 2 min).
+
+## Layering with mesh
+
+The two systems answer different questions:
+
+| Question | Owner |
+|---|---|
+| Which pod gets this request? (lane routing, load balance) | Mesh VirtualService |
+| Is this peer authorized? (mTLS, AuthorizationPolicy) | Mesh |
+| Connection-level retry on TCP error | Mesh |
+| Should this caller retry on 5xx from this callee? | Framework client SDK (reads pair config from config center) |
+| What timeout for this caller→callee call? | Framework client SDK |
+| Circuit-breaker per-pair | Framework client SDK |
+
+A platform may run only mesh (simpler), only app-level traffic config (no mesh), or both. The dual approach is more work but gives both network-level and app-level levers.
+
+## Anti-pattern to avoid
+
+- Running both mesh DR policy AND app-level traffic config without an ownership boundary. Two layers retrying the same call amplifies load 9× (3×3). Document which layer owns retry; disable the other.
+- Letting per-pair config become per-call config — the cardinality explodes. Per-pair is workable (services × services); per-call is not.
+- Config center as a routing replacement. Routing belongs in mesh (or in SDK resolver). Config center is for policy values, not topology.
+
+## Verification
+
+- Update a pair policy via the control-plane API → log into a caller pod → SDK shows new value applied within the subscription propagation window (typically 1-10s).
+- Inject a synthetic 5xx storm from a callee → mesh outlier detection ejects pods (mesh-level), and the framework client SDK respects the per-pair retry budget without amplifying.
+- Disable mesh inject for a TCP service → verify connectivity still works (registry + direct TCP); verify mTLS is intentionally absent (or applied via app-level TLS if required).

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/framework-middleware.md

@@ -0,0 +1,143 @@
+# Framework Middleware (Client and Server)
+
+The middleware chain that propagates app-level context across hops, layered above mesh transport.
+
+## RPC server suite — default chain
+
+In platform RPC server bootstrap (Kitex `server.Suite`, gRPC interceptor chain, or equivalent):
+
+```
+incoming RPC
+   │
+   ▼
+ ctx_inject (server)
+   │ extracts log-id, lane, caller-identity from RPC base struct or metadata
+   │ generates log-id if absent (server side fallback)
+   │ injects into context.Context
+   ▼
+ tracing (OTel contrib)
+   │ extracts traceparent; starts a kind=server span
+   ▼
+ metrics
+   │ counts QPS + latency histogram, labels = baseline + caller + callee + method
+   ▼
+ request_info_log (gated by env flag)
+   │ INFO line on entry and exit with method, code, duration
+   ▼
+ err_handler
+   │ catches kerrors.ErrPanic / ErrACL / ErrRPCTimeout / ErrBiz
+   │ maps to a stable error-code enum (server_panic, forbidden, timeout, biz)
+   ▼
+ handler
+```
+
+`server.WithMetaHandler` typically wires the transport-level metadata propagation (TTHeader for Thrift, HTTP/2 metadata for gRPC). Set at server suite construction; don't re-set per service.
+
+## RPC client suite — default chain
+
+```
+outgoing RPC (from app code)
+   │
+   ▼
+ client_base_inject
+   │ reads log-id, lane, idc, cluster from context.Context
+   │ populates the canonical RPC base struct on the outbound request
+   ▼
+ ctx_inject (client)
+   │ adds log-id to metadata for transports that don't use base struct
+   │ logs caller-side observation
+   ▼
+ metrics
+   │ counts QPS + latency, labels = baseline + caller + callee + method
+   ▼
+ request_info_log (gated)
+   ▼
+ tracing (OTel client suite)
+   │ starts kind=client span; injects traceparent into outbound metadata
+   ▼
+ err_handler
+   │ classifies framework errors so callers see a stable error-code
+   ▼
+ transport (mesh sidecar then network)
+```
+
+## Canonical RPC base struct
+
+For RPC platforms with a "base request" concept (Kitex, Thrift):
+
+```thrift
+struct Base {
+  1: i64 UnixTime              // ms since epoch, caller's clock
+  2: string LogId              // platform log-id
+  3: string Caller             // PSM-style caller identity
+  4: map<string,string> Tags { // standard tag names below
+       "idc":     <region>
+       "cluster": <k8s cluster name>
+       "lane":    <env/lane label>
+       // optional below
+       "stress_tag": "true" | absent      // load-test traffic flag
+       "shadow":     "true" | absent      // shadow-traffic flag
+  }
+}
+```
+
+Whether request metadata rides an in-message `Base` field or the transport metadata/header channel is a scenario decision, not a universal mandate — see the Carrier decision in `rpc-framework-recipe.md` (transport metadata + interceptors is the industry-standard default for ordinary unary and streaming gRPC). **On a platform that has standardized the in-message `Base` carrier**, each RPC method's request type embeds `Base`, the IDL generator auto-includes it, and it is not optional per-method within that platform. **On a metadata-carrier platform**, the request type does NOT embed `Base`; the same metadata set rides the R7 owner-recorded header set and the middleware injects/extracts it there. The middleware obligation (inject on the client, extract on the server) holds on either carrier.
+
+The client middleware fills the chosen carrier (in-message `Base` or the metadata/header set) from ctx; the server middleware extracts it. App code uses `appctx.GetLogId(ctx)`, `appctx.GetLane(ctx)` etc., never touches the carrier directly.
+
+## HTTP equivalent (Hertz / Gin / FastAPI)
+
+For HTTP, replace base struct with header set:
+
+```
+<log-id-header>     log-id, generated if missing
+<lane-header>       lane / env
+X-Caller-PSM        PSM-style identity of upstream caller (if any)
+X-Caller-IDC        region
+X-Caller-Cluster    cluster
+traceparent         OTel trace context
+tracestate          OTel trace context
+```
+
+Header names are a platform constant. The literal value does not matter; consistency does. Both client and server middleware MUST use the same names.
+
+## Local dev mode
+
+The middleware chain must work locally:
+- No registry → resolve via `LOCAL_HOST` config or direct address.
+- No mesh → app talks plaintext.
+- No otel collector → tracing exporter no-ops.
+- Log-id, lane, ctx propagation must still work end-to-end.
+
+If a developer can't reproduce a multi-hop context propagation bug locally, the local mode is broken.
+
+## What MUST NOT be in the default chain
+
+- **Auth/authz at framework layer**. Authz belongs in handler or in mesh AuthorizationPolicy. Embedding in middleware creates a hidden coupling.
+- **Rate limiting**. Use mesh / API gateway / RLS.
+- **Circuit breaking**. Use mesh outlier-detection or SDK-native circuit breaker; not a middleware.
+- **Cache layer**. Cache is a handler concern.
+
+Each item above can be added as opt-in middleware for specific services, but is NOT in the default chain.
+
+## Verification
+
+```bash
+# Server side
+grep -E "ctx_inject|tracing|metrics|request_info_log|err_handler|base_inject" \
+  <platform-framework-default-server-options.go>
+# expect ≥ 5 hits
+
+# Client side
+grep -E "ctx_inject|client_base_inject|tracing|metrics|err_handler" \
+  <platform-framework-default-client-options.go>
+# expect ≥ 5 hits
+
+# Service code does not re-add the same middleware
+grep -rE "WithMiddleware\(.*(CtxInject|Metrics|Tracing|ErrorHandler)" <service-dir>
+# expect zero hits
+
+# Live: cross-service call carries log-id and lane
+# Make a synthetic call from A → B; inspect B's INFO log on entry.
+# Expect to see same log-id as A wrote; same lane.
+```

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/grpc-authority-workaround.md

@@ -0,0 +1,90 @@
+# gRPC `:authority` and DNS-Label Hyphenation
+
+## The quirk
+
+HTTP/2's `:authority` pseudo-header (which carries the host of a gRPC request) is parsed strictly. RFC 1035 says DNS labels can contain letters, digits, and hyphens — but NOT underscores.
+
+Many platforms use PSM-style service names like `<owner>.<class>.<env>`. When any segment contains underscores (e.g. an env segment named `prod_v2` or a feature-flagged variant `payments.ledger.prod_2024`), the SDK puts that name into `:authority`. Envoy / strict gRPC implementations reject the request:
+
+```
+RST_STREAM with INTERNAL_ERROR
+```
+
+You lose the connection on every call. Frustrating to debug because it looks like network failure.
+
+## Two fixes
+
+### Fix 1 (clean, long-term): forbid underscores in service names
+
+- Naming policy: service name = lowercase, dot-separated segments, hyphens within segments allowed, underscores forbidden.
+- Enforce at registry registration (reject the registration).
+- Enforce at CI / lint when defining new services.
+- Migrate existing names by renaming + parallel registration during a deprecation window.
+
+### Fix 2 (live-system workaround): mesh-level rewrite
+
+When you can't break existing names, an Envoy Lua filter rewrites `:authority` on the fly:
+
+```yaml
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+  name: modify-grpc-authority
+  namespace: istio-system
+spec:
+  configPatches:
+    - applyTo: HTTP_FILTER
+      match:
+        context: ANY
+        listener:
+          filterChain:
+            filter:
+              name: "envoy.filters.network.http_connection_manager"
+      patch:
+        operation: INSERT_BEFORE
+        value:
+          name: envoy.filters.http.lua
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.filters.http.lua.v3.Lua
+            inlineCode: |
+              function envoy_on_request(request_handle)
+                local authority = request_handle:headers():get(":authority")
+                local content_type = request_handle:headers():get("content-type")
+                if authority and content_type and string.find(content_type, "application/grpc") then
+                  local modified_authority = string.gsub(authority, "_", "-")
+                  request_handle:headers():replace(":authority", modified_authority)
+                end
+              end
+```
+
+Effects:
+- Applies to gRPC traffic only (content-type check).
+- Rewrites `_` to `-` in `:authority`.
+- Callee's registry instance name must also use the `-` form so routing matches.
+
+## When to use which
+
+| Situation | Fix |
+|---|---|
+| Greenfield platform | Fix 1 — naming policy from day one |
+| Mature platform, many existing names | Fix 2 — buy time, then schedule Fix 1 migration |
+| Mixed HTTP + gRPC for same service | Fix 2 — HTTP tolerates `_`, gRPC doesn't; rewrite only at gRPC layer |
+| Service-mesh-less (direct gRPC) | Fix 1 only — no Envoy to rewrite |
+
+## Verification
+
+Fix 1:
+- Registry rejects registration with `_` in name.
+- Linter / CI rejects PR adding such a name.
+
+Fix 2:
+- Synthetic gRPC call to `<svc>_<env>` → inspect Envoy access log `:authority` field → expect `<svc>-<env>`.
+- Callee's access log `host` shows the rewritten form.
+
+## Common variants of the same bug
+
+- HTTP/2 SETTINGS frame rejection on cert SAN mismatch (separate issue, but presents similarly — RST_STREAM with INTERNAL_ERROR).
+- gRPC `:scheme` set to `http` while upstream expects `https` (mTLS mismatch).
+- IPv6 literal in `:authority` not bracketed.
+
+The Lua rewrite filter is the right tool for the underscore case; do not generalize it to all of the above. Each bug has its own fix.

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/http-response-envelope-contract.md

@@ -0,0 +1,24 @@
+# HTTP Response Envelope Contract
+
+The cross-stack contract for the JSON business-response shape a backend returns and its clients parse. Owned here alongside the request-side base struct (`rpc-framework-recipe.md`) and the wire-format gate (`protobuf-http-contract-signals.md`) because it is shared across the Go, Python, web, mini-program, and testing skills — each points here and adds only its stack-specific verb (define / implement / consume / assert). Do not restate this policy per stack.
+
+## Canonical envelope
+
+- The canonical JSON business envelope is `code`, `message`, and `data`. `data` is the typed business data model for that operation.
+- It is defined in the shared contract source, not invented per handler, route, or client.
+
+## Adoption & migration
+
+- New services and service-level envelope migrations use the canonical `code` / `message` / `data` envelope.
+- A new route inside an existing service follows that service's already-shipped envelope until a consumer-migration decision adopts `code` / `message` / `data` for the service.
+- An existing surface with a different shipped envelope preserves current behavior until a migration decision exists.
+
+## Surfaces that are not the JSON envelope
+
+Binary protobuf, streaming, file/download, redirect, healthcheck, and externally dictated callback / standard-protocol responses record, implement, and assert their own response contract instead of pretending to use the JSON envelope.
+
+## Anti-patterns (when the canonical JSON envelope applies)
+
+- Do not invent alternate or per-handler / per-route top-level business response shapes.
+- Do not duplicate the common envelope fields across clients, or scatter duplicate envelope parsing.
+- Do not place business fields outside `data`.

package/dist/assets/marketplace/plugins/ccl-skills/skills/platform-service-connectivity/references/mesh-architecture.md

@@ -0,0 +1,127 @@
+# Mesh Architecture
+
+Reference topology and component rules. Istio is the recurring example; rules generalize to Linkerd, Consul Connect, or App Mesh with vendor-specific naming.
+
+## Topology
+
+```
+                ┌────────────────────────────────┐
+                │  Mesh control plane (pilot/    │
+                │  istiod), 1-3 replicas         │
+                │  - issues identity / certs     │
+                │  - pushes config to sidecars   │
+                │  - watches k8s API + registry  │
+                └──────┬─────────────────────────┘
+                       │ xDS config
+        ┌──────────────┼──────────────┬───────────────┐
+        ▼              ▼              ▼               ▼
+   ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌──────────────┐
+   │ Pod A   │    │ Pod B   │    │ Pod C   │    │ Ingress      │
+   │ ┌─────┐ │    │ ┌─────┐ │    │ ┌─────┐ │    │ Gateway      │
+   │ │ app │ │    │ │ app │ │    │ │ app │ │    │ (Envoy)      │
+   │ └──┬──┘ │    │ └──┬──┘ │    │ └──┬──┘ │    └──────┬───────┘
+   │    │    │    │    │    │    │    │    │           │
+   │ ┌──▼──┐ │    │ ┌──▼──┐ │    │ ┌──▼──┐ │           │
+   │ │Envoy│◄┼────┼─┤Envoy│◄┼────┼─┤Envoy│ │           │
+   │ │side │ │    │ │side │ │    │ │side │ │           │
+   │ │car  │ │    │ │car  │ │    │ │car  │ │           │
+   │ └─────┘ │    │ └─────┘ │    │ └─────┘ │           │
+   └─────────┘    └─────────┘    └─────────┘           │
+                                                       │
+   Client traffic ─────────────────────────────────────┘
+```
+
+## Istio Ambient Mode (GA Nov 2024, v1.24+)
+
+- **Istio Ambient Mode reached General Availability in Istio v1.24 (announced November 2024)** per `istio.io/latest/blog/2024/ambient-reaches-ga/` — `ztunnel` + `waypoint` architecture is the stable sidecar alternative for new production mesh deployments. **Two-layer split**: `ztunnel` (Rust-based DaemonSet, one per node, L4-only — mTLS + simple L4 authz + telemetry) handles every pod's transport-layer mesh participation without per-pod sidecar injection; `waypoint` proxies (Envoy-based, scaled independently from app workloads) handle L7 features when needed (rich authz, traffic routing, resilience). Per Istio's own reported numbers, the architecture can save 90%+ memory/CPU vs the sidecar model in dense-pod-per-node workloads (Istio's claim — re-measure on the team's actual workload before quoting savings). **Architecture choice for new mesh**: (a) **choose ambient** when memory/CPU per pod is the binding constraint, sidecar injection causes restart cycles the team wants to avoid, or a subset of namespaces don't need L7 features at all; (b) **stay on sidecar mode** when the team has deep sidecar-specific tooling (custom `EnvoyFilter`s injected per pod, sidecar-aware debugging recipes, app code that expects `localhost:15001` proxy conventions), or when ambient's narrower L7-feature coverage hits a gap the team relies on. **Mixed-mode in one cluster is officially supported** per the Istio docs: sidecar-mode namespaces and ambient-mode namespaces coexist; migration can be incremental namespace-by-namespace. **CRITICAL migration block: AuthorizationPolicy enforcement loss when flipping a namespace from sidecar to ambient without waypoint** — sidecar mode enforces full L7 `AuthorizationPolicy` rules (HTTP method, path, header, JWT claims) at the per-pod proxy. In ambient mode, ztunnel alone enforces only L4-level policy (workload identity, port); any L7-condition rule (`request.method`, `request.headers[...]`, `request.path`, `request.auth.claims[...]`) silently DOES NOT MATCH on ambient-mode pods until a waypoint proxy is deployed for the namespace/service and the policy is targeted at the waypoint. The failure shape: team flips `istio.io/dataplane-mode=ambient` label, sidecar comes down, ztunnel takes over L4, and every L7 authz policy stops gating traffic — without a visible error, because L4 policy still works. **Pre-flip gate**: inventory every `AuthorizationPolicy` targeting workloads in the namespace, identify the ones using L7 conditions, ensure a waypoint is deployed and the policy `targetRefs` is set to the waypoint (not the workload) BEFORE flipping the namespace label. Validate by re-running the authz integration tests against the ambient-mode namespace before completing the migration. **Observability shift**: ztunnel emits L4 metrics; waypoint emits L7 metrics; existing dashboards keyed on sidecar `istio_requests_total` need a ambient-mode equivalent for the L7-routed traffic — route this update through `platform-observability` rather than redesigning here.
+
+## Sidecar injection rules
+
+- **Default** (sidecar mode): every workload namespace labelled `istio-injection=enabled` (or pod-level `sidecar.istio.io/inject: "true"`). For ambient-mode namespaces, sidecar injection is OFF; the ambient-mode label and ztunnel DaemonSet handle participation instead.
+- **Opt-out cases** (each must be documented):
+  - Telemetry collectors (would loop).
+  - Log-shipping DaemonSets (hostPath access, no app traffic).
+  - Service registry pods (mesh would bootstrap-cycle).
+  - Mesh control plane itself.
+  - Pure batch jobs that don't communicate with services.
+- **Verification**: `kubectl get pods -A -o jsonpath='{.items[?(@.spec.containers[*].name=="istio-proxy")].metadata.name}'` should cover ~all app pods.
+
+## Mesh config minimums
+
+```yaml
+meshConfig:
+  accessLogFile: "/dev/stdout"       # log to stdout, captured by file-collector daemonset
+  accessLogFormat: |
+    { "start_time": "%START_TIME%",
+      "method":     "%REQ(:METHOD)%",
+      "path":       "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%",
+      "protocol":   "%PROTOCOL%",
+      "host":       "%REQ(HOST)%",
+      "log_id":     "%REQ(<log-id-header>)%",
+      "lane":       "%REQ(<lane-header>)%",
+      "response_code":     "%RESPONSE_CODE%",
+      "x_forwarded_for":   "%REQ(X-FORWARDED-FOR)%",
+      "upstream_host":     "%UPSTREAM_HOST%",
+      "upstream_cluster":  "%UPSTREAM_CLUSTER%" }
+  enablePrometheusMerge: true        # Envoy stats merged into app's Prom scrape
+```
+
+The access log JSON shape MUST include `log_id` and `lane`. These are the join keys between mesh logs and app logs.
+
+`enablePrometheusMerge` saves an entire scrape target per pod; Envoy stats appear in the same `/metrics` endpoint as the app.
+
+## Gateway
+
+One default ingress gateway per environment is the baseline. The gateway terminates TLS, applies WAF/rate-limit if needed, and routes to mesh-internal services.
+
+```yaml
+kind: Gateway
+spec:
+  selector:
+    istio: ingressgateway
+  servers:
+    - port: { number: 80, name: http, protocol: HTTP }
+      hosts: ["<public-host-pattern>"]
+    - port: { number: 443, name: https, protocol: HTTPS }
+      hosts: ["<public-host-pattern>"]
+      tls: { mode: SIMPLE, credentialName: <tls-secret> }
+```
+
+Egress gateway is OFF by default. Turn ON only when a workload needs controlled external access (compliance, audit, retry).
+
+## EnvoyFilter usage
+
+EnvoyFilter is the escape hatch. Use sparingly; each filter is hard to test and easy to break across Envoy upgrades.
+
+Acceptable uses:
+- Header rewrite for protocol quirks (e.g. gRPC `:authority` hyphenation — see `grpc-authority-workaround.md`).
+- Adding a Lua filter for one-off business handling that doesn't yet have a first-class WASM filter.
+- Custom rate-limit before the canonical RLS is rolled out.
+
+Unacceptable uses:
+- Disabling mTLS for a specific service to "fix" a connectivity issue (root-cause it).
+- Removing access log fields per service (breaks log-join).
+- Inline business logic (mesh is not a runtime — push to a sidecar service if you really need it).
+
+## What mesh owns vs framework owns
+
+| Concern | Mesh | Framework client/server middleware |
+|---|---|---|
+| TLS / identity | YES (mTLS) | NO |
+| Connection retry (network errors) | YES | NO (don't double-retry) |
+| Per-call business retry (idempotent op) | NO | YES, with idempotency awareness |
+| Transport timeout | YES (ceiling) | YES (per-call budget, ≤ ceiling) |
+| Business deadline | NO | YES (ctx.Deadline) |
+| Circuit breaker / outlier detection | YES | (fallback if mesh absent) |
+| Load balancing | YES (topology-aware) | YES (resolver level) |
+| Lane routing | YES (VirtualService) | Sets the lane label; doesn't pick routes |
+| Authn/authz at network | YES (AuthorizationPolicy) | NO |
+| Authn/authz at request | NO | YES (or in service handler) |
+| Log-id propagation | Passes through; logs it | Sets it, extracts it |
+
+## Failure modes to test
+
+- **Sidecar crashed**: pod fails readiness; mesh control plane re-pushes config; rolling restart needed?
+- **Mesh control plane unreachable**: existing sidecars keep last config (sidecars are stateless data-plane proxies); new pods can't start.
+- **mTLS cert expiry**: control plane rotates; verify rotation works under load.
+- **Mesh upgrade**: data plane behind control plane is allowed; control plane behind data plane is not.