docs(k8s-proxy): add Developer + LLM Workflow playbook (two-prompt autonomous flow)

[charankamarapu]

Summary

Adds a sibling page to k8s-proxy-developer-workflow titled Developer + LLM Workflow with Keploy Proxy.

The page documents a workflow where the developer only ever types one of two prompts to their IDE agent (Claude Code / Cursor / Windsurf / Claude Desktop / VS Code / Trae):

1. "keploy cloud replay pipeline is failing, please analyse and fix it."
2. "Add new tests for my changes."

Everything else — finding the app, resolving the Keploy branch, fetching the failing run, deciding whether the suite or the app code is at fault, applying the fix on the branch, re-running replay — is done autonomously by the agent. CI still owns the merge.

What's in the page

• Step 1 — Wire up the Keploy MCP server (per-editor config snippets, same JSON shape; only the config path changes).
• Step 2 — Paste the autonomous playbook into the editor's rules / memory file (CLAUDE.md, .cursor/rules/keploy.md, .windsurfrules, etc.). Table of paste locations included.
• Step 3 — Use the two prompts. Per-prompt phase tables show what the agent does behind the scenes.
• Troubleshooting + putting-it-together walkthrough.

What's in the playbook (the pasteable block)

The directive embedded in the page covers:

• Hard rules. Branch-first (every write needs branch_id); Keploy branch name mirrors git rev-parse --abbrev-ref HEAD; app resolved from basename $(pwd); never edit app source as a workaround; never run keploy cloud branch-merge from chat; never ask what git/files answer; always end with a dashboard URL.
• Routine A — "replay failing, analyse and fix":
  • Discovery (listApps, create_branch).
  • Find latest failed test_suite_run via listTestRuns.
  • Fetch report via get_session_report with verbose=true.
  • Three-route diagnosis from git log / git diff, not from dev questions:
    • Route A — mock_mismatch_dominant=true AND no relevant code changes → file as keploy egress-hook bug.
    • Route B — recent commit broke the endpoint, suite is correct → point at file:line, dev fixes code.
    • Route C — recent commit intentionally changed the contract → update_mock / update_test_suite on the branch (preserving step IDs), then re-run keploy cloud replay --branch-name.
  • Fixed Markdown report format.
• Routine B — "add new tests for my changes":
  • git diff origin/main...HEAD to enumerate added/modified HTTP endpoints.
  • Capture traffic via keploy record while curling each new endpoint with dynamic values.
  • Upload via keploy upload test-set --branch <git branch>.
  • Validate via keploy cloud replay --branch-name. Fail → drop into Routine A.
  • Fixed Markdown report format.
• When you MAY ask the dev — narrowed to four cases (invalid PAT, detached HEAD, ambiguous app match, uninferable app_url). Everything else is autonomous.
• Anti-patterns the agent must refuse — editing handler code, manual branch-merge, writing to main, re-recording without diagnosis.

Why the page exists

The manual flow on the existing Developer Workflow page is still the source of truth for what each command does. This new page is the autonomous-LLM front-end on top of it: paste once, two-prompt operation from there on. CI YAML stays in YAML — agent does not touch CI.

Test plan

• Render docs locally (yarn start) and confirm the new page appears under K8s Proxy → LLM Workflow in the v4.0.0 sidebar.
• Verify cross-links to Developer Workflow and its CI subsections (#wiring-up-your-ci-pipeline, #1-replay-on-pr-open) resolve.
• Copy the playbook block into a real editor (Claude Code CLAUDE.md + Cursor .cursor/rules/keploy.md) and confirm:
  • Agent runs Discovery on its own from git rev-parse --abbrev-ref HEAD + basename $(pwd).
  • Prompt A produces the diagnosis-table → fixes-applied → next-step format.
  • Prompt B produces the captured-table → replay → next-step format.
  • Agent refuses to run keploy cloud branch-merge from chat.
  • Agent refuses to edit handler source as a workaround.
• Confirm per-editor MCP config snippets work after a full editor restart (PAT in header, MCP endpoint at /client/v1/mcp).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds a new v4.0.0 quickstart documentation page under the K8s Proxy section to describe a “Developer + LLM Workflow” using Keploy’s MCP server, and updates the versioned sidebar so the page is discoverable alongside the existing K8s proxy developer workflow.

Changes:

• Added a new doc page: Developer + LLM Workflow with Keploy Proxy (MCP setup + pasteable workflow playbook).
• Updated the v4.0.0 sidebar to include the new page under K8s Proxy.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
versioned_sidebars/version-4.0.0-sidebars.json	Adds the new LLM Workflow doc to the K8s Proxy sidebar group.
versioned_docs/version-4.0.0/quickstart/k8s-proxy-llm-workflow.md	New documentation page covering MCP editor setup and a copy/paste playbook for a branch-first workflow.

Comments suppressed due to low confidence (1)

versioned_docs/version-4.0.0/quickstart/k8s-proxy-llm-workflow.md:154

• The tool-surface table inside the playbook also uses || at the start of each row. Since users are instructed to paste this block verbatim into their rules file, the malformed table will carry over. Switch it to normal Markdown table syntax (| ... |).

| Intent                                       | Tool                                                          |
| -------------------------------------------- | ------------------------------------------------------------- |
| Add a hand-written mock to a test set        | `create_mock`                                                 |
| Edit one mock's body / headers / spec        | `update_mock`                                                 |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.