`) OR `delete_recording` + re-capture via `keploy record` + `keploy upload test-set`.
+- `keploy cloud replay` re-run: `/` tests passed.
+
+### Next step for you
+- (Case 1) Review the code edit at ``. Push when satisfied; CI will replay automatically.
+- (Case 2) Push your code change—CI replay will pick up the updated Keploy branch.
+- (Retry cap hit) File a keploy bug with `test_run_id=` and the run-report URL.
+
+Branch diff: https://app.keploy.io/api-testing/branch-diff?appId=&branchId=
+Run report: https://app.keploy.io/tr?appId=&branch=
+```
+
+---
+
+## Routine B—"add new keploy tests for my changes"
+
+### Phase B1—Identify the changes
+
+1. `git diff origin/main...HEAD --name-only` (fall back to `main...HEAD` if `origin/main` isn't fetched).
+2. Filter to **HTTP-handler files**—route definitions, controllers, request handlers. Skip refactors, test files, docs, generated code, migrations.
+3. For each handler file, read the diff hunks (`git diff origin/main...HEAD -- `) and list the endpoints that were added or modified. Note each one's `method` + `path` + a one-line description.
+4. If nothing handler-relevant changed, tell the dev "no API-handler changes detected on this branch—no new tests needed", and stop.
+
+### Phase B2—Capture traffic for the new endpoints
+
+**Pre-flight: confirm the app starts under the dev's local setup.** Discover the dev's run command from the repo (priority order: `Makefile` targets like `run` / `start` / `dev`, `docker-compose.yml` (`docker compose up -d`), `Procfile`, `package.json` scripts, the README's quickstart section). Start the app with that command, curl a reachable endpoint (`/health`, the root, anything that 200s) to confirm it's serving traffic, then stop it cleanly. Don't ask the dev for help here unless you literally cannot get the app to start—discovering the run command from the repo is on you.
+
+**Make sure the app is fully stopped before running `keploy record`.** `keploy record -c ""` spawns its own instrumented copy of the app; if your pre-flight instance is still running, the two will fight over the port (or the container name). `docker compose down` / kill the PID / whatever stops it cleanly before continuing.
+
+**Capture:**
+
+1. Run `keploy record -c "" --sync` via Bash. The `-c` value is the exact command from your pre-flight; `--sync` records test cases synchronously so each curl is captured in order with no race against the next one. Cloud association happens in Phase B3's upload step, not here—`keploy record` itself is the local OSS command and doesn't take `--cloud-app-id`.
+2. For each new/changed endpoint, drive ONE realistic curl. Infer body shape from the OpenAPI spec if there is one, otherwise from the handler signature itself.
+3. Stop `keploy record` (kill the PID you captured at step 1, or send Ctrl-C equivalent).
+4. The recording lands at `keploy/test-set-N/` on disk.
+
+### Phase B3—Upload to the Keploy branch
+
+```bash
+keploy upload test-set \
+ --app \
+ --branch \
+ --test-set keploy/test-set-N \
+ --name
+```
+
+`` should reflect the dev's change (e.g. "checkout-with-discount" if they added a discount field). The `--branch` flag scopes the upload to your sticky branch; subsequent dashboard reviewers see only this diff.
+
+### Phase B4—Validate
+
+```bash
+keploy cloud replay --app --branch-name
+```
+
+If anything failed, enter Routine A from Phase A2—the diagnosis routine handles it.
+
+### Phase B5—Report (exact format)
+
+```
+### Captured
+| Endpoint | Test set | Cases |
+| --- | --- | --- |
+| | | |
+
+### Replay
+/ tests passed on branch ``.
+
+### Next step
+Open your PR. CI will replay this branch automatically; merge will fold the test data into main.
+
+Branch diff: https://app.keploy.io/api-testing/branch-diff?appId=&branchId=
+Run report: https://app.keploy.io/tr?appId=&branch=
+```
+
+---
+
+## When you MAY ask the dev (and only then)
+
+- The PAT is missing or invalid (auth error from the MCP tool itself) → ask the dev to mint a fresh PAT.
+- `git rev-parse --abbrev-ref HEAD` returns `HEAD` (detached) or exits non-zero → ask the dev for a Keploy branch name ONCE.
+- `listApps` returns multiple ambiguous matches that you cannot narrow by compose-service name → list the candidates and ask ONCE.
+- Phase B2's pre-flight cannot start the app (discovered the run command from compose / Makefile / Procfile / README but it failed) → name the command you tried and the error, then ask ONCE.
+
+Everything else—what failed and why, which mock to update, what test-set name to use, whether the dev's commit was intentional, what the new endpoint's contract should look like—you discover from the repo and the api-server. Do not ask.
+
+## Anti-patterns (refuse these)
+
+- Editing handler code on a Case-2-shaped failure (contract changed intentionally). The test data is what's stale—update it on the branch instead.
+- Writing to `main` (any tool that omits `branch_id`). Always branch-first.
+- Re-recording to absorb a failure without first reading the diff and deciding the route. Re-record only when Route C applies.
+- Inventing a PAT, branch name, or secret value.
+````
+
+Save the file and fully restart your editor so the skill / rules / memory entry is available in your next session.
+
+---
+
+## Step 3—Use the two prompts
+
+That's it. From now on, you only ever type one of:
+
+> **"my keploy cloud replay is failing, please analyse and fix it."**
+
+_or, when the failure was in CI:_
+
+> **"the keploy cloud replay pipeline is failing, please analyse and fix it."**
+
+or
+
+> **"Add new keploy tests for my changes."**
+
+What happens behind the scenes for each:
+
+### Prompt A—analyse and fix a failing replay (local or CI)
+
+| Phase | What the agent does |
+| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A0 | Resolve `app_id` from `basename $(pwd)` + `listApps`. Resolve `branch_id` from `git rev-parse --abbrev-ref HEAD` + `create_branch`. |
+| A1 | Get a `test_run_id` to fetch the report against. Local form → list the branch's recent test runs and take the latest failed one's id. CI form → extract `test_run_id` from the CI log or dashboard URL the dev pasted (falls back to the local lookup if nothing was pasted). |
+| A2 | Fetch the full report (`get_session_report` with `verbose=true`). |
+| A3 | Per failing step, decide Case 1 (bug in the app—recent commit broke it, test is still correct) or Case 2 (app behavior drifted intentionally—test data is stale, with sub-actions 2a noise / 2a response edit / 2b mock edit / 2b delete + re-record). Decision is from `git log` / `git diff` plus the report's `mock_mismatches`, never from a dev question. |
+| A4 | For Case 1: announce the file:line and a one-line description, then edit the handler code so the dev can stop the agent if they object. For Case 2a: `update_test_suite` to add noise on a non-deterministic field, or to update the recorded `response` body (preserve every existing step `id`). For Case 2b: `update_mock` on the affected mock, or—if the baseline is too far gone—`delete_recording` and re-record via Routine B's flow. Either way, re-run `keploy cloud replay --branch-name` to verify. |
+| A5 | Report: diagnosis table (case per step) + fixes applied + next-step-for-you + branch-diff URL + run-report URL. |
+
+### Prompt B—author new keploy tests
+
+| Phase | What the agent does |
+| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| B0 | Discovery (same as A0). |
+| B1 | `git diff origin/main...HEAD` to find handler files that changed; extract added/modified endpoints. |
+| B2 | Pre-flight: discover the dev's run command from the repo (Makefile → docker-compose.yml → Procfile → package.json → README), start the app, curl any 200-returning endpoint to confirm it's serving traffic, stop it. Then run `keploy record -c "" --sync`, drive a realistic curl per new endpoint, stop the recorder. Recording lands at `keploy/test-set-N/`. |
+| B3 | `keploy upload test-set --app --branch --test-set keploy/test-set-N --name ` to land the bundle on the Keploy branch. |
+| B4 | `keploy cloud replay --app --branch-name ` to validate. On failure, drop into Routine A. |
+| B5 | Report: captured endpoints table + replay result + next-step (open PR) + branch-diff URL + run-report URL. |
+
+For everything not covered by these two prompts—manually inspecting test data, editing one mock, listing recordings—use the manual flow on the [Developer Workflow](/docs/quickstart/k8s-proxy-developer-workflow) page directly. The two-prompt workflow handles the 90% case; the manual flow is the escape hatch.
+
+---
+
+## Putting it together
+
+Here are the typical scenarios the agent handles—one per case it decides between. Every one starts with the same two-prompt UX and ends with the dev pushing once CI catches up. The variable bit is what the agent does in the middle.
+
+### Scenario 1—App regression (Case 1)
+
+You merged a refactor that accidentally broke the price calculation on `/orders/{id}`. The test still expects the right total.
+
+> _"my keploy cloud replay is failing, please analyse and fix it."_
+
+A0 → A1 (latest failed run) → A2 (report shows `total_amount: 0` vs expected `99.99`). A3 sees your recent commit on the price-calc helper and the test's authored response is still correct → **Case 1**. A4 announces the edit at `pkg/order/calc.go:42`—restoring the line-item subtotal branch—then applies the fix and re-runs replay (green). A5 reports the edit + URLs.
+
+### Scenario 2—Test data drift on the response (Case 2a, response edit)
+
+You renamed a response field from `username` to `display_name` on `/users/{id}` on purpose. CI replay now fails because the recorded response still says `username`.
+
+> _"the keploy cloud replay pipeline is failing, please analyse and fix it."_
+
+A3 sees the rename commit and `authored_assertions` pinned to `username` → **Case 2a**. A4 calls `update_test_suite` to swap the field name on the recorded response (preserving every kept step's `id`), re-runs replay (green). A5 reports the test edit + URLs.
+
+### Scenario 3—Test data drift, non-deterministic field (Case 2a, noise)
+
+The replay started failing on `$.created_at`—a timestamp that differs each run. No code changes near it.
+
+> _"my keploy cloud replay is failing, please analyse and fix it."_
+
+A3 sees the diverging field is genuinely time-varying with no related commit → **Case 2a (noise)**. A4 calls `update_test_suite` to add `$.created_at` to that step's noise list; replay re-runs green.
+
+### Scenario 4—Mock drift from a DB query change (Case 2b, mock edit)
+
+You added a `discount_percent` column to the orders table and updated the `SELECT` to return it. The handler emits the new field, the test expects it, but the recorded mock for the DB call still has the old shape.
+
+> _"my keploy cloud replay is failing, please analyse and fix it."_
+
+A3 sees the schema-change commit and `mock_mismatches` on the SELECT row → **Case 2b**. A4 calls `update_mock` to add `discount_percent` to the mock spec; replay re-runs green. A5 reports the mock edit + URLs.
+
+### Scenario 5—Mock too far gone, full re-record (Case 2b, fallback)
+
+A downstream gRPC client was swapped for HTTP; the recorded mocks are protobuf bytes that no longer apply.
+
+> _"my keploy cloud replay is failing, please analyse and fix it."_
+
+A3 → **Case 2b**. A4 tries one `update_mock` edit—it doesn't pass. The agent falls back: `delete_recording` on the affected test set, then re-records via Routine B's flow (pre-flight → `keploy record -c "" --sync` → curl → `keploy upload test-set --branch `). Replay re-runs green.
+
+### Scenario 6—Adding tests for a new endpoint (Routine B)
+
+You added `POST /coupons/redeem`.
+
+> _"Add new keploy tests for my changes."_
+
+B0 → B1 (`git diff origin/main...HEAD` surfaces the new route). B2 pre-flight: agent finds `make run` in the Makefile, brings the app up, `curl /health` returns 200, stops it. Then `keploy record -c "make run" --sync`, curls `POST /coupons/redeem` with a realistic body, stops the recorder. B3 uploads via `keploy upload test-set --app --branch --name coupons-redeem`. B4 replay returns 1/1 passed. B5 reports the captured endpoint + URLs.
+
+---
+
+Across every scenario, you only ever spoke one of two sentences. You push your code change (and, for Case 1, the agent's app-side edit). CI replays the branch on the PR; merge runs `keploy cloud branch-merge` and the test data lands on main.
+
+For the same flow done manually (CLI / dashboard, no agent), see [Developer Workflow with Keploy Proxy](/docs/quickstart/k8s-proxy-developer-workflow).
diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json
index 6f741ddee..55f463295 100644
--- a/versioned_sidebars/version-4.0.0-sidebars.json
+++ b/versioned_sidebars/version-4.0.0-sidebars.json
@@ -149,6 +149,7 @@
"items": [
"quickstart/k8s-proxy",
"quickstart/k8s-proxy-developer-workflow",
+ "quickstart/k8s-proxy-llm-workflow",
"running-keploy/k8s-proxy-daemonset-architecture"
]
},