v1.6: audit-mode onboarding, managed audit window, agent tooling + WebSocket exec fallback

.claude/agents/cpg-operator.md

@@ -0,0 +1,34 @@
+---
+name: cpg-operator
+description: Drives a live cpg MCP session (`start_session`/`get_status`/`stop_session`
+  plus the query tools and `get_bootstrap_policy`) on behalf of `cpg-triage` and
+  `cpg-audit-onboard`. Never invoked directly by the operator — spawned by those
+  two skills whenever a live session needs to be driven end-to-end.
+tools: Bash, Read
+---
+
+# cpg-operator
+
+## Operating contract
+
+- You are spawned by `cpg-triage` or `cpg-audit-onboard`, never invoked standalone.
+  If you are somehow asked to run outside that context, say so and stop — you have
+  no independent workflow of your own.
+- Before calling ANY tool, call `tools/list` and read the live schema. Never assume
+  an argument name, a result field, or a tool's exact behavior from this document
+  or from the calling skill's prose — those are workflow routers, not a copy of the
+  tool contract. The MCP server (`cpg mcp`) is the single source of truth.
+- Drive the session lifecycle the calling skill asks for (typically some ordering
+  of `start_session`, `get_status`, `stop_session`, and the read-only query tools:
+  `list_dropped_flows`, `list_policies`, `get_policy`, `get_evidence`,
+  `get_cluster_health`, `get_bootstrap_policy`). Report findings back to the
+  calling skill in plain terms — you are the driver, not the presenter.
+- `Bash` is for spawning `cpg mcp` and driving JSON-RPC over stdio (or a thin MCP
+  client wrapping that subprocess). `Read` is for inspecting policy YAML and
+  evidence files a session writes to its own tmpdir. You have no `Write`/`Edit` —
+  you drive and report, you never author files in this repository.
+- Stop the session cleanly (`stop_session`) once the calling skill's workflow is
+  done or once a hard error stops progress — never leave a session dangling.
+- If a tool response looks like an error, check whether it is actually a documented
+  non-error state (e.g. a mid-capture "not ready yet" marker) before surfacing it as
+  a failure to the calling skill.

.claude/skills/cpg-audit-onboard/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: cpg-audit-onboard
+description: >
+  Guide an operator through onboarding a brand-new namespace into enforced
+  default-deny network policy: bootstrap, per-endpoint audit mode, capture,
+  and the human-applied enforce checklist. Use when a namespace has no
+  default-deny CiliumNetworkPolicy yet and needs to be brought onto one
+  safely. Do NOT use for triaging an already-running capture on a namespace
+  that is already onboarded (see cpg-triage) or for offline review of
+  existing policies (see cpg-policy-review).
+---
+
+# cpg-audit-onboard
+
+Router for the full onboarding workflow documented in
+[docs/bootstrap-runbook.md](../../../docs/bootstrap-runbook.md). This skill
+GUIDES the human through the CLI steps that are human-run, DRIVES the capture
+step via the `cpg-operator` agent, and ENDS with the human applying policy —
+it never runs `cpg bootstrap`/`cpg audit-window` itself and never invokes an
+apply tool, because none exists and none should be invented.
+
+## Step 0: Check prerequisites
+
+Point the operator at the runbook's
+[Prerequisites](../../../docs/bootstrap-runbook.md#prerequisites) section:
+`cpg` on `PATH`, a working `kubeconfig` with `create`/`apply` RBAC for the
+target namespace, and Cilium >= 1.16 on the cluster. Confirm these before
+proceeding — a stale Cilium version silently degrades `cpg bootstrap`'s
+output rather than failing loudly.
+
+## Step 0.5: Pick the order (live traffic vs fresh namespace)
+
+Ask the operator one question before anything else: **does the namespace
+carry live traffic?**
+
+- **Live traffic → audit window FIRST, bootstrap second** (swap Steps 1
+  and 2 below). Flipping `PolicyAuditMode` is a no-op until a policy
+  matches, so opening the window first is harmless — and the bootstrap
+  apply then produces `AUDIT` verdicts instead of real drops. Zero real
+  drops, end to end.
+- **Fresh or scaled-down namespace → bootstrap first** (the order as
+  written). Nothing is running to drop, and the namespace is enforced from
+  the very first pod.
+
+See the runbook's
+[Choose Your Order](../../../docs/bootstrap-runbook.md#choose-your-order-live-traffic-vs-fresh-namespace)
+section. Either way, remind the operator the namespace is NOT enforced
+while the window is open — keep the `--ttl` as short as the capture needs.
+
+## Step 1: Guide bootstrap (human-run)
+
+Instruct the operator to run, in their own terminal:
+
+```bash
+cpg bootstrap -n <namespace> | kubectl apply -f -
+```
+
+This is a human-run CLI step — this skill does not execute it. If the
+operator wants to review before applying, tell them they can redirect to a
+file first and `kubectl apply -f` it themselves; see the runbook's
+[Bootstrap the Namespace](../../../docs/bootstrap-runbook.md#bootstrap-the-namespace)
+section for both paths, plus the note on
+[Deploy / Scale Considerations](../../../docs/bootstrap-runbook.md#deploy--scale-considerations)
+if the namespace carries live traffic (in which case Step 2's window should
+already be open per Step 0.5).
+
+## Step 2: Guide per-endpoint audit mode (human-run)
+
+Instruct the operator to run `cpg audit-window` in its own supervised
+terminal for the duration of the onboarding capture:
+
+```bash
+cpg audit-window -n <namespace> --ttl <duration>
+```
+
+This skill does not run this command either — it is foreground and
+supervised by design, and it self-reverts on every exit path (Ctrl+C,
+SIGTERM, or `--ttl` expiry). Point the operator at the runbook's
+[Enable Per-Endpoint Audit Mode](../../../docs/bootstrap-runbook.md#enable-per-endpoint-audit-mode)
+section for the RBAC it needs and the documented new-endpoint race window.
+Use the per-endpoint form only — never suggest the daemon-wide audit-mode
+setting; that ConfigMap knob disables enforcement cluster-wide and the
+runbook's own leading warning confines it to a single paragraph for exactly
+that reason.
+
+## Step 3: Drive the capture
+
+Once the operator confirms audit mode is active, delegate to the
+`cpg-operator` agent to call `start_session` with audit-inclusion enabled —
+discover the exact argument name for that via `tools/list` at call time; do
+not assume it from this document (Router Principle). Let the capture run
+long enough to observe the traffic the operator cares about, then have
+`cpg-operator` call `stop_session`.
+
+For a wider verdict view alongside the MCP-driven capture, the operator may
+also want the runbook's
+[Observe Policy Verdicts](../../../docs/bootstrap-runbook.md#observe-policy-verdicts)
+Hubble command — that stays a human/CLI step, not something this skill runs.
+
+## Step 4: Enforce checklist (ends with the human applying)
+
+1. Review the generated policy YAML the capture produced.
+2. Cross-check against the runbook's
+   [Create and Apply Generated Policies](../../../docs/bootstrap-runbook.md#create-and-apply-generated-policies)
+   section.
+3. The HUMAN applies the reviewed policy:
+
+   ```bash
+   kubectl apply -f ./policies/<namespace>/
+   ```
+
+There is no apply tool in this workflow and none should be invoked or
+suggested — this step is intentionally the operator's own action, taken
+outside this skill, after they have reviewed the YAML.
+
+## Step 5: Verify and clean up (human-run)
+
+Point the operator at the runbook's
+[Verify Enforcement](../../../docs/bootstrap-runbook.md#verify-enforcement) and
+[Clean-up](../../../docs/bootstrap-runbook.md#clean-up) sections to confirm the
+endpoint left audit mode and, if this was a one-off exercise, to tear down
+what was applied. Per-endpoint audit mode has no separate disable step —
+stopping `cpg audit-window` in Step 2 already reverted it.
+
+## After onboarding
+
+Once a namespace is onboarded and enforcing, route follow-up live-capture
+work to `cpg-triage` and offline policy audits to `cpg-policy-review` — this
+skill's job ends at a verified, enforcing namespace.

.claude/skills/cpg-health-report/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: cpg-health-report
+description: >
+  Turn a captured cluster-health.json into a shareable, self-contained HTML
+  report of infra/transient drops broken down by node and workload, with
+  Cilium remediation links. Use when an operator wants a readable report of
+  the infra side of a session (drops that were not turned into policy). Do
+  NOT use for generating or reviewing CiliumNetworkPolicies (see cpg-triage
+  or cpg-policy-review).
+---
+
+# cpg-health-report
+
+Router for turning `cluster-health.json` into a shareable HTML report. This
+skill routes to where the data lives and what to render — it does not
+restate the JSON schema field-by-field beyond naming the fields needed to
+route the rendering.
+
+## Step 1: Obtain cluster-health.json
+
+Two sources exist — pick the one that matches the invocation context and
+STATE which one was used in the report itself:
+
+- **A saved/archived session directory:** read the file directly from disk
+  at `<session_tmpdir>/cluster-health.json` (available post-`stop_session`).
+  This copy is uncapped.
+- **An already-running or already-driven session:** call the
+  `get_cluster_health` MCP tool (via `cpg-operator` if a session is already
+  being driven for another purpose). This path is server-capped at 100
+  node/workload entries per drop.
+
+## Step 2: Render a self-contained HTML file
+
+Build one static HTML file, inline `<style>` only — no external JS/CSS,
+no CDN dependency, nothing that requires network access to render correctly
+when the operator opens it locally. Structure:
+
+1. **Header:** session summary line built from `flows_seen` and
+   `infra_drops_total`.
+2. **One table row per drop entry:** reason, class, count.
+3. **Expandable breakdown per row:** the by-node and by-workload counts for
+   that drop reason.
+4. **Remediation link:** wherever a drop entry's remediation field is
+   non-empty, render it as a clickable link to the Cilium docs page it
+   points at; omit the link entirely when the field is empty rather than
+   rendering a dead link.
+
+## Step 3: Escape before embedding
+
+HTML-escape every string field pulled from `cluster-health.json` before
+embedding it in the generated file — reason strings, remediation URLs, node
+names, workload names. This is a self-XSS guardrail: the report is a local
+file the operator opens in a browser, and nothing in this pipeline should
+assume those strings are already safe to embed raw.
+
+## Step 4: Hand off
+
+Tell the operator where the HTML file was written and which source (disk
+file vs `get_cluster_health` tool, per Step 1) it was built from, so they
+know whether they're looking at a capped or uncapped view.

.claude/skills/cpg-mcp-smoke/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: cpg-mcp-smoke
+description: >
+  Smoke-test a tagged cpg binary's MCP server against the fake-relay e2e
+  harness: full 9-tool handshake plus a graceful session lifecycle. Use
+  after a release build, before shipping a new cpg binary, to confirm the
+  MCP surface still works end-to-end. Do NOT use this for a live-cluster
+  workflow — it targets the fake relay, not a real cluster (see cpg-triage
+  or cpg-audit-onboard for live work).
+---
+
+# cpg-mcp-smoke
+
+Router for post-release MCP smoke testing. This skill routes to the
+EXISTING e2e harness in `cmd/cpg/mcp_e2e_test.go` — it does not rebuild any
+test infrastructure.
+
+## Step 1: Run the graceful lifecycle test WITHOUT -short
+
+```bash
+rtk proxy go test ./cmd/cpg/... -run TestMCPE2EGracefulLifecycle -v
+```
+
+This must run WITHOUT `-short` — the test explicitly skips itself under
+short mode. A "pass" that completes in under a second means the test was
+skipped, not that the smoke actually ran; the real run does a one-time
+`-race` build of the binary plus a real subprocess round-trip, so expect it
+to take several seconds minimum.
+
+## Step 2: What the test covers
+
+`TestMCPE2EGracefulLifecycle` exercises the full handshake and session
+lifecycle against an in-process fake Hubble relay: initialize, `tools/list`
+(schema + annotation checks), `start_session`, `get_status`, all five query
+tools mid-capture, `stop_session`, `get_cluster_health` post-stop, and a
+graceful stdin-close exit. This is the smoke skill's primary target.
+
+## Step 3: Assert the tool count
+
+The handshake must report exactly 9 tools. This skill validates the current
+full real tool surface, not the stale "8-tool" figure some older docs still
+carry — `get_bootstrap_policy` shipped after that figure was written.
+
+## Step 4: Coverage floor — the 9 tools
+
+Every registered MCP tool must be exercised or at minimum named as part of
+this smoke's scope: `start_session`, `get_status`, `stop_session`,
+`list_dropped_flows`, `list_policies`, `get_policy`, `get_evidence`,
+`get_cluster_health`, `get_bootstrap_policy`.
+
+## Step 5: Companion scenario — abrupt disconnect
+
+`TestMCPE2EUngracefulDisconnect` is the companion scenario for a killed
+transport (an abrupt disconnect instead of a graceful stdin close). Run it
+alongside the graceful lifecycle test for a fuller smoke pass:
+
+```bash
+rtk proxy go test ./cmd/cpg/... -run TestMCPE2EUngracefulDisconnect -v
+```
+
+The graceful lifecycle test in Step 1 remains the primary smoke target;
+this companion is worth running but is not a substitute for it.

.claude/skills/cpg-policy-review/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cpg-policy-review
+description: >
+  Audit already-generated CiliumNetworkPolicies offline: over-broad rules,
+  missing/incorrect L7 anchoring, missing DNS-53 companion rules, and
+  dedup sanity, routed through cpg explain and per-rule flow evidence. Use
+  when reviewing policy YAML that already exists on disk or in git, without
+  a live cluster session. Do NOT use for driving a live capture (see
+  cpg-triage) or for the initial namespace onboarding workflow (see
+  cpg-audit-onboard).
+---
+
+# cpg-policy-review
+
+Router for an offline policy audit. This skill routes to `cpg explain` and
+the `get_evidence` tool for evidence, and points at the README rather than
+restating flag lists or field shapes.
+
+## Step 1: Locate the target
+
+Identify the namespace/workload pair or the policy YAML path to review
+(`<NAMESPACE/WORKLOAD>` or a path under the output directory, e.g.
+`./policies/<namespace>/<workload>.yaml`).
+
+## Step 2: Explain the policy
+
+Run `cpg explain <NAMESPACE/WORKLOAD | path/to/policy.yaml>` for the target.
+Use its filter flags (`--ingress`/`--egress`/`--port`/`--peer`/`--peer-cidr`/
+`--http-method`/`--http-path`/`--dns-pattern`/`--since`/`--samples-limit`) to
+narrow the review to the rules under question, and `--json`/`--format` to
+get a structured view when comparing against evidence programmatically.
+Do not restate the flag semantics beyond naming them — run `cpg explain
+--help` for the exact current flag surface if anything is unclear.
+
+If reviewing against a live-ish source (an active or recently-stopped MCP
+session) rather than files on disk, use the `get_evidence` tool instead —
+it returns evidence in the same shape `cpg explain --json` does.
+
+## Step 3: Checklist — walk each rule
+
+For each rule `cpg explain` surfaces, check:
+
+- **Over-broad rules:** does the peer selector or CIDR match more than the
+  evidence actually shows traffic from? A rule matching a whole namespace
+  when evidence shows only one workload talking is a candidate to tighten.
+- **L7 anchoring:** for HTTP/DNS rules, is the L7 detail (method, path,
+  matchName) actually present and correctly anchored? See the README's
+  [L7 Prerequisites](../../../README.md#l7-prerequisites) section for the
+  capture-time requirements a rule needs before L7 attribution is even
+  possible — do not re-derive those requirements here, route to it.
+- **Missing DNS-53 companions:** an egress rule permitting a `toFQDNs` peer
+  needs a paired DNS/port-53 rule for the FQDN to resolve at all; flag any
+  FQDN-based rule missing its DNS companion.
+- **Dedup sanity:** do near-duplicate rules exist (same peer/port pair
+  expressed twice with slightly different selectors)? Evidence should
+  justify each distinct rule; if two rules are backed by the same evidence
+  set, they are a dedup candidate.
+
+## Step 4: Cross-reference the evidence
+
+For every rule flagged in Step 3, pull its evidence via `get_evidence` (or
+the JSON output of `cpg explain` from Step 2) and confirm the flagged
+concern is real — a rule that looks over-broad in isolation may be backed by
+genuinely varied evidence samples justifying the breadth.
+
+## Step 5: Report
+
+Summarize findings per rule: keep as-is, tighten (with the specific narrower
+selector/port/L7 filter suggested), or flag as a dedup candidate. Point the
+operator at [Explain policies](../../../README.md#explain-policies) in the
+README for the full worked examples of `cpg explain` usage if they want to
+reproduce a finding themselves. This skill reports; the operator decides
+whether and how to edit the policy YAML.