proxymock: add In-Cluster (Web) quickstart with screenshots

AGENTS.md

@@ -13,7 +13,7 @@ This document orients any AI coding agent working in this repository. Follow the
 ## Project Overview
 This is Speedscale's documentation website built with Docusaurus 3 (currently 3.8.1). Speedscale is an API testing platform that uses traffic capture and replay for stress testing APIs with real-world scenarios. The documentation covers two main products:
 - **Speedscale Platform**: Full enterprise API testing platform  
-- **ProxyMock**: Local development tool for mocking APIs
+- **proxymock**: Local development tool for mocking APIs
 
 ## Development Commands
 
@@ -101,7 +101,7 @@ When deleting pages, always add redirects to `docusaurus.config.js` to prevent b
 
 #### **Phase 1: Critical Content Gaps**
 - **Setup/Upgrade Documentation**: Expand beyond operator upgrades to include CLI/Docker procedures, rollback guides
-- **ProxyMock Guides**: Currently minimal (4 files) - needs comprehensive getting started guides, troubleshooting, integration examples
+- **proxymock Guides**: Currently minimal (4 files) - needs comprehensive getting started guides, troubleshooting, integration examples
 - **Transform Documentation Consolidation**: Content split between `/transform/` and `/reference/transform-traffic/` - consolidate for clarity
 
 #### **Phase 2: Information Architecture**

docs/getting-started/quick-start.md

@@ -10,7 +10,7 @@ import ApiKey from './installation/install/api-key.png'
 # Quick Start
 
 :::info Local installation
-For local development and testing without a cloud cluster, use **proxymock** to run a local mock server and generate tests from your traffic. See **[Local Development (AI) – Getting Started](/proxymock/)** to install proxymock and get started in about 30 seconds.
+For local development and testing without a cloud cluster, use **proxymock** to run a local mock server and generate tests from your traffic. See **[Local Development – Getting Started](/proxymock/)** to install proxymock and get started in about 30 seconds.
 :::
 
 :::tip Security options

docs/guides/message-brokers/kafka.md

@@ -1,6 +1,6 @@
 ---
 title: Kafka
-description: "Record, mock, and replay Kafka traffic using Speedscale and ProxyMock for efficient traffic simulation and testing."
+description: "Record, mock, and replay Kafka traffic using Speedscale and proxymock for efficient traffic simulation and testing."
 sidebar_position: 12
 ---
 

docs/guides/replay/mocks/from-scratch.md

@@ -1,6 +1,6 @@
 ---
 title: From Scratch
-description: "Create mock services from scratch with ProxyMock by seeding and deleting mock responses, and configuring passthrough mode for effective API testing."
+description: "Create mock services from scratch with proxymock by seeding and deleting mock responses, and configuring passthrough mode for effective API testing."
 sidebar_position: 20
 ---
 

docs/guides/signature-refinement-guide.md

@@ -1,5 +1,5 @@
 ---
-description: "Refine signatures in ProxyMock to enhance mock accuracy, ensuring your service mock returns correct responses for every incoming request."
+description: "Refine signatures in proxymock to enhance mock accuracy, ensuring your service mock returns correct responses for every incoming request."
 sidebar_position: 22
 ---
 

docs/proxymock/aws/ses.md

@@ -1,5 +1,5 @@
 ---
-description: "Mock AWS SES connections for local development using ProxyMock to test email functionality without sending real emails or incurring costs with Speedscale."
+description: "Mock AWS SES connections for local development using proxymock to test email functionality without sending real emails or incurring costs with Speedscale."
 sidebar_position: 9
 ---
 

docs/proxymock/getting-started/faq.md

@@ -1,5 +1,5 @@
 ---
-description: "Explore the FAQ for ProxyMock, covering supported protocols, Windows compatibility, differences from Speedscale Enterprise, and mock server functionality."
+description: "Explore the FAQ for proxymock, covering supported protocols, Windows compatibility, differences from Speedscale Enterprise, and mock server functionality."
 sidebar_position: 4
 ---
 
@@ -19,7 +19,7 @@ Yes. The **proxymock** cli is available as a native Windows executable. Alternat
 
 Speedscale Enterprise is a cloud platform that allows you to create, manage, and scale mock servers. It allows you to record from a real production environment and bring that environment back to your desktop. That is a paid product that requires a subscription (and helps fund **proxymock** development).
 
-## Can Proxymock be used as a shared mock server to replace part of a dev environment?
+## Can proxymock be used as a shared mock server to replace part of a dev environment?
 
 Most definitely, but for that you need to consider an Enterprise subscription. Beyond licensing, you will need the more sophisticated tools provided by Speedscale Enterprise to manage that use case.
 

docs/proxymock/getting-started/help.md

@@ -1,5 +1,5 @@
 ---
-description: "Get help with ProxyMock by connecting on the Speedscale Slack or emailing support@speedscale.com for assistance with your API testing needs"
+description: "Get help with proxymock by connecting on the Speedscale Slack or emailing support@speedscale.com for assistance with your API testing needs"
 sidebar_position: 5
 ---
 

docs/proxymock/getting-started/installation.md

@@ -1,5 +1,5 @@
 ---
-description: "Install ProxyMock via the command line to automate simulation environments, record traffic, and replay transactions efficiently for your API testing needs"
+description: "Install proxymock via the command line to automate simulation environments, record traffic, and replay transactions efficiently for your API testing needs"
 sidebar_position: 2
 ---
 import Tabs from '@theme/Tabs';

docs/proxymock/getting-started/language-reference.md

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 3
 title: Language Configuration
-description: "Configure language-specific settings for ProxyMock to route traffic effectively without modifying application code, ensuring seamless API testing and traffic replay."
+description: "Configure language-specific settings for proxymock to route traffic effectively without modifying application code, ensuring seamless API testing and traffic replay."
 ---
 
 import Tabs from '@theme/Tabs';

docs/proxymock/getting-started/quickstart/in-cluster/index.mdx

@@ -0,0 +1,151 @@
+---
+title: In-Cluster (Web)
+description: Use proxymock web to connect to your Kubernetes cluster, enable capture, and run replays in cluster with live results.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Admonition from '@theme/Admonition';
+import MacCLIInstall from '../../../index/_cli_macos_minified.mdx'
+import LinuxCLIInstall from '../../../index/_cli_linux_minified.mdx'
+
+# In-Cluster (Web)
+
+Use proxymock web to work directly against your Kubernetes cluster. You can:
+- Enable eBPF capture on a workload to record real in-cluster traffic
+- Run an in-cluster replay of your local recordings (“Run in cluster”) and stream results live
+
+This path is best when you want realistic in-environment behavior or to validate changes inside the cluster.
+
+## Prerequisites
+- Kubernetes cluster access (`kubectl` working, correct context)
+- Authorized (if you plan to run in-cluster replay): `proxymock init` (browser sign-in)
+
+## 1) Install the proxymock CLI (if not installed)
+
+Install proxymock locally — this gives you both the CLI and `proxymock web`.
+
+<Tabs>
+  <TabItem value="mac" label="macOS">
+    <MacCLIInstall />
+  </TabItem>
+  <TabItem value="linux" label="Linux">
+    <LinuxCLIInstall />
+  </TabItem>
+  <TabItem value="other" label="Other / Detailed">
+    See: [/proxymock/getting-started/installation](/proxymock/getting-started/installation)
+  </TabItem>
+</Tabs>
+
+After install, initialize once (browser sign-in by default):
+
+```bash
+proxymock init
+```
+
+## 2) Install the Speedscale Operator (if not installed)
+
+If your cluster doesn’t have the Speedscale Operator and Forwarder yet, install them first. Full instructions live here: [/getting-started/installation/install/kubernetes-operator/](/getting-started/installation/install/kubernetes-operator/)
+
+Quick Helm example:
+
+```bash
+helm repo add speedscale https://speedscale.github.io/operator-helm/
+helm repo update
+helm install speedscale-operator speedscale/speedscale-operator \
+  -n speedscale \
+  --create-namespace \
+  --set apiKey=<YOUR-SPEEDSCALE-API-KEY> \
+  --set clusterName=<YOUR-CLUSTER-NAME>
+```
+
+Once installed and reachable, proxymock web will detect the Forwarder and enable Observability and live features via Kubernetes port-forwarding.
+
+<Admonition type="caution" title="Kubernetes Permissions Required">
+  To use <b>proxymock web</b> with your cluster, you must have Kubernetes RBAC permissions that allow <b>port forwarding</b>.  
+  If you cannot port-forward (e.g., on restricted clusters), use the <b>cloud-based replay</b> feature in Speedscale instead.
+</Admonition>
+
+## 3) Start proxymock web and connect to your cluster
+
+```bash
+proxymock web
+# Open the printed http://127.0.0.1:XXXX URL
+```
+
+- Open Observability → Topology.
+- If not connected, use the Retry control (proxymock web auto port-forwards to the Forwarder when possible).
+- Optionally switch kube context from the toolbar.
+
+![Observability → Topology with the cluster connected](./images/proxymock-web-observability-connect.png)
+
+![Switch kube context from the toolbar](./images/proxymock-web-kube-context.png)
+
+## 4) Record traffic from a workload (eBPF capture)
+
+From Observability → Topology:
+1) Pick a namespace and select a workload (Deployment/StatefulSet/etc.)
+2) Open the workload pane and enable Capture (eBPF)
+3) Generate traffic (e.g., hit your service from a client)
+
+Requests will stream back and appear in the Requests tab. The persistent live-tap card shows active sessions and counters.
+
+![Selected workload pane with Overview tab](./images/proxymock-web-workload-pane.png)
+
+![eBPF capture toggle on the workload pane](./images/proxymock-web-capture-toggle.png)
+
+![Persistent live-tap card with active session and counters](./images/proxymock-web-tap-card.png)
+
+Tips:
+- Java services: enable the Java agent checkbox when prompted
+- Ports: set custom capture ports when your service listens on non-default ports
+
+## 5) Inspect captured traffic
+
+Go to Requests → pick the active run from the Run selector. Inspect inbound/outbound RRPairs, filter by host, method, path, and drill into details.
+
+![Requests grid with Run selector](./images/proxymock-web-requests-run.png)
+
+![Drilled-in RRPair detail pane](./images/proxymock-web-request-detail.png)
+
+## 6) Optional — Run in cluster (replay recordings inside your cluster)
+
+You can take any local recordings (`./proxymock/recorded-*`) and run them against a target in your connected cluster. Results stream back live over the Forwarder tap.
+
+Steps (Replay tab):
+1) Pick one or more recordings (left side)
+2) Source & Target → choose a destination:
+   - URL (custom) or
+   - Cluster Workload / Service (preferred)
+3) Optional: enable Mock dependencies, click Rescan to load outbound dependencies, and keep the ones to mock
+4) Click “Run in cluster”
+
+While running:
+- A stepper shows progress (build, push, run)
+- A bottom drawer streams live generator/responder/SUT logs
+- The persistent live-tap card shows ‘Live replay’ with counters
+
+On completion, proxymock web opens the report and scopes the Requests tab to the run output directory.
+
+![Pick the recordings to feed the replay](./images/proxymock-web-replay-select-recordings.png)
+
+![Cluster namespace + Cluster Workload destination](./images/proxymock-web-replay-destination.png)
+
+![Mock dependencies enabled with the inferred outbound list](./images/proxymock-web-replay-mock-deps.png)
+
+![Run in cluster button in the replay toolbar](./images/proxymock-web-replay-cluster-button.png)
+
+![Stage stepper during a live in-cluster replay](./images/proxymock-web-replay-stepper.png)
+
+![Bottom drawer streaming live generator/responder/SUT logs](./images/proxymock-web-replay-logs.png)
+
+Troubleshooting:
+- If “Run in cluster” is unavailable, ensure you’ve run `proxymock init` (browser sign-in) and that Observability shows a connected cluster
+- Mocking requires a Workload/Service destination (not just a URL)
+
+## Next steps
+- [Local quickstart](/proxymock/getting-started/quickstart/local/) — record and replay traffic against an app on your machine, no cluster required
+- [Live Tail (Web)](/proxymock/getting-started/quickstart/live-tail/) — point proxymock web at a running app and watch RRPairs stream in
+- [Observability guide](/proxymock/guides/observability) — go deeper on topology, eBPF capture, and live-tap workflows
+- [How it works](/proxymock/how-it-works/architecture) — architecture, lifecycle, and the RRPair format
+- [Guides index](/proxymock/guides/) — credentials swap, CI/CD, OpenAPI, gRPC, databases, and more

docs/proxymock/getting-started/quickstart/index.md

@@ -1,14 +1,12 @@
 ---
-description: "Create a mock server and tests for your Go application with ProxyMock's quickstart guide, covering installation, traffic recording, and test execution."
+description: "Create a mock server and tests for your Go application with proxymock's quickstart guide, covering installation, traffic recording, and test execution."
 sidebar_position: 1
 ---
 import ArchitectureOverview from './outerspace-go.png'
 
-# Quickstart
+# Quickstart: Choose Your Path
 
-Welcome to proxymock!
-
-This guide provides a step-by-step approach to creating a [mock server](/reference/glossary.md#mock-server) and tests for a simple Go application. Choose your preferred workflow below:
+Welcome to proxymock! Pick the workflow that matches your environment. Each path helps you create a [mock server](/reference/glossary.md#mock-server) and tests from real traffic.
 
 ## What You'll Learn
 
@@ -22,16 +20,17 @@ Both workflows will teach you how to:
 
 ## Choose Your Workflow
 
-### 🖥️ Command Line Interface (CLI)
-**For software engineers who prefer traditional command-line tools**
+### 🖥️ Local Recording (Desktop)
+Record a local service and generate mocks/tests. Best for fast, single-machine workflows. Choose CLI or MCP.
 
-Use the proxymock CLI directly from your terminal to record traffic, create mocks, and run tests. This approach gives you full control over each step and is ideal for automation and scripting.
+**[Go to Local Recording →](./local/)**
 
-**[Start CLI Tutorial →](./quickstart-cli.md)**
+### ☸️ In-Cluster Recording (Web)
+Start a recording inside your Kubernetes cluster from proxymock web. Best for realistic, in-environment traffic.
 
-### 🤖 MCP Workflow (LLM-Driven)
-**For developers using AI coding assistants like Cursor, Claude, or GitHub Copilot**
+**[Go to In-Cluster →](./in-cluster/)**
 
-Leverage the power of AI coding assistants with proxymock's MCP (Model Context Protocol) integration. Simply describe what you want to do in natural language, and your LLM will execute the appropriate proxymock commands.
+### 📡 Live Tail (Web)
+Stream traffic live from proxymock web and selectively capture what you need for mocks and tests.
 
-**[Start MCP Tutorial →](./quickstart-mcp.md)**
+**[Go to Live Tail →](./live-tail/)**

docs/proxymock/getting-started/quickstart/live-tail/index.mdx

@@ -0,0 +1,62 @@
+---
+title: Live Tail (Web)
+description: Stream live RRPairs from your cluster in proxymock web, view counters and logs, and pivot to captured requests.
+---
+
+# Live Tail (Web)
+
+Live Tail streams requests from your cluster into proxymock web in real time. Use it to observe activity, verify traffic is flowing, and pivot to the captured requests for mocking or replay.
+
+## Prerequisites
+- proxymock web running locally: `proxymock web`
+- Connected cluster in Observability (Forwarder reachable)
+
+## 1) Connect to your cluster
+
+Open Observability → Topology. If needed, use Retry to connect (auto port-forward), or switch kube context.
+
+![Observability → Topology with the cluster connected](../in-cluster/images/proxymock-web-observability-connect.png)
+
+## 2) Start a Live Tail session (workload tap)
+
+From the Topology view:
+1) Pick a namespace, click a workload to open its pane
+2) Start a live tap session for that workload (the UI provides start/stop controls)
+3) Generate some load on the service
+
+The persistent “Live capture” card appears at the top of the content area showing broadcast/received/written counters and per-session actions.
+
+![Selected workload pane with Overview tab](../in-cluster/images/proxymock-web-workload-pane.png)
+
+![Persistent live-tap card with active session and counters](../in-cluster/images/proxymock-web-tap-card.png)
+
+Tips:
+- The tap card shows all active sessions. Click “View” to jump to Requests scoped to that run
+- Click “Stop” to end a session; previously captured data remains available
+
+## 3) Inspect captured requests
+
+Go to the Requests tab. Use the Run selector to scope to the current live-tail run; filter by host, method, path. Open details to view full request/response (headers, body, timing).
+
+![Requests grid with Run selector](../in-cluster/images/proxymock-web-requests-run.png)
+
+![Drilled-in RRPair detail pane](../in-cluster/images/proxymock-web-request-detail.png)
+
+## 4) Optional — Replay or mock
+
+With a live-tail run selected you can:
+- Replay locally against a URL
+- Or switch to the Replay tab and “Run in cluster” against a Workload/Service, with optional dependency mocking
+
+![Cluster namespace + Cluster Workload destination](../in-cluster/images/proxymock-web-replay-destination.png)
+
+![Run in cluster button in the replay toolbar](../in-cluster/images/proxymock-web-replay-cluster-button.png)
+
+## Data considerations
+- Live Tail streams metadata and payloads; apply DLP when exporting to cloud
+- Enterprise isolation: consider BYOC if data residency constraints apply
+
+## Next steps
+- In-Cluster (Web): /proxymock/getting-started/quickstart/in-cluster/
+- How It Works: /proxymock/how-it-works/
+- Guides: /proxymock/guides/