docs(migration): harden cam-mcp reference for public use

Remove internal CAM REST paths, auth header enumeration, and
retry/timeout details from the MCP reference. Narrow the illustrative
tool schema to parameters agents need; auth is handled by the server.

Align the agent workflow with the registered MCP tool only
(fetch-cam-bpa-findings). Replace the list-projects step with explicit
user confirmation of project id or name, matching aemcs-migration-mcp.

Author: Himani Chauhan

skills/aem/cloud-service/skills/migration/references/cam-mcp.md

@@ -4,15 +4,15 @@ Read this file when **fetching BPA targets via MCP** instead of a CSV or cached
 
 ## Happy path (what the user should see)
 
-1. Agent calls **`list-projects`** and shows **name**, **id**, and **description**.
-2. **You pick** a project (even if only one is listed — confirms the right CAM context).
-3. Agent calls **`fetch-cam-bpa-findings`** with that project and the **one pattern** for this session (`scheduler`, `assetApi`, etc., or `all` then filtered).
+1. Agent asks the user for their **CAM project name or ID**.
+2. **You confirm** the project name or ID (the agent should not guess or infer it).
+3. Agent calls **`fetch-cam-bpa-findings`** with the confirmed project and the **one pattern** for this session (`scheduler`, `assetApi`, etc., or `all` then filtered).
 4. Agent maps returned targets to Java files and continues the migration workflow in `../SKILL.md`.
 
 ### Project name and ID — non-negotiable
 
-- **Never** call **`fetch-cam-bpa-findings`** with a `projectId` or `projectName` that the user typed until it is **matched to a row** from the latest **`list-projects`** response, **or** the user has explicitly confirmed the intended project after you showed **name**, **id**, and **description** for all listed projects.
-- If the user gave a name before you listed projects, still run **`list-projects`**, show the table, and **wait for them to confirm** which project (by id or unambiguous name) — do not assume a fuzzy match.
+- **Never** call **`fetch-cam-bpa-findings`** with a `projectId` or `projectName` that the user has not **explicitly confirmed**.
+- If the tool returns a "project not found" error, **quote the error verbatim**, and ask the user to provide the correct project name or ID — do not guess or retry with a fuzzy match.
 - **Do not** infer the CAM project from the open workspace, repository name, or sample code (e.g. WKND) when using MCP.
 
 ### MCP errors — stop first (especially project-not-found)
@@ -21,7 +21,7 @@ On **any** MCP failure, **stop the migration workflow immediately**. **Quote the
 
 **Exception:** [enablement restriction errors](#enablement-restriction-errors-mandatory-handling) below — follow that section exactly (verbatim to user; no retry; no silent fallback).
 
-**After** that verbatim report, you may briefly explain what went wrong (e.g. unknown project name) and show **relevant rows from `list-projects`** if you already have them. **Only** if the user **explicitly** asks to switch approach (e.g. provides a BPA CSV path, picks another project from the list, or names specific Java files for manual flow) may you proceed — that is a **new** user-directed step, not an automatic fallback.
+**After** that verbatim report, you may briefly explain what went wrong (e.g. unknown project name). **Only** if the user **explicitly** asks to switch approach (e.g. provides a BPA CSV path, picks another project, or names specific Java files for manual flow) may you proceed — that is a **new** user-directed step, not an automatic fallback.
 
 For other failures (auth, timeout, 5xx), still quote errors verbatim; use retries only where the table below allows, then **stop** and ask how the user wants to continue (CSV, different project, or manual files) — do not silently pivot.
 
@@ -47,55 +47,22 @@ If your MCP server documentation adds other error prefixes or codes with the sam
 
 ## Rules before any tool call
 
-1. Call **`list-projects`** first; show **name**, **id**, and **description** to the user.
-2. **Wait for explicit project choice** (even if only one project), then call **`fetch-cam-bpa-findings`** using the **confirmed** `projectId` (preferred) or a name that the user affirmed against that list — do not pass an unconfirmed string the user guessed.
+1. **Ask the user** for their CAM project name or ID. Do not guess from the workspace or sample code.
+2. **Wait for explicit confirmation**, then call **`fetch-cam-bpa-findings`** using the **confirmed** `projectId` (preferred) or `projectName`.
 3. Map the session's **single pattern** to the tool's `pattern` argument (`scheduler`, `assetApi`, `eventListener`, `resourceChangeListener`, `eventHandler`, or `all`). If you used `all`, filter `targets` to the active pattern.
 
-## REST (maintainer context)
-
-The MCP server calls **Adobe AEM Cloud Adoption Service**, for example:
-
-- `GET {base}/projects` — projects for the authenticated IMS org.
-- `GET {base}/projects/{projectId}/bpaReportCodeTransformerData/subtype/{subtype}` — aggregated identifiers per BPA subtype (e.g. `sling.commons.scheduler` for scheduler).
-
-Auth headers typically include `Authorization: Bearer …`, `x-api-key`, and `x-gw-ims-org-id` (often `ident@AdobeOrg`). Subtype mapping is implemented in the MCP server.
-
-**Deeper docs:** `aemcs-migration-mcp/docs/cam-cloud-adoption-api-contract.md`; controllers `ProjectController`, `BpaReportCodeTransformerDataController` in `aem-cloud-adoption-service`.
-
----
-
-## Tool: `list-projects`
-
-Lists CAM projects. **Always call this before `fetch-cam-bpa-findings`.**
-
-**Response (illustrative):**
-
-```typescript
-{
-  success: true;
-  projects: Array<{
-    id: string;
-    name: string;
-    description: string;
-  }>;
-}
-```
-
----
-
 ## Tool: `fetch-cam-bpa-findings`
 
+The only MCP tool registered by the server. It can also resolve a project name to a project ID internally (via the CAM projects API), so a separate `list-projects` call is not needed — pass `projectName` or `projectId`.
+
 **Request (illustrative — confirm against live MCP tool schema):**
 
 ```typescript
 {
-  projectId: string;   // required after user confirms project (from list-projects)
-  projectName?: string; // only if user affirmed this name against list-projects; never pass an unconfirmed guess
+  projectId?: string;   // CAM project ID; either this or projectName must be provided
+  projectName?: string; // human-readable name; resolved to projectId via CAM /projects API
   pattern?: "scheduler" | "assetApi" | "eventListener" | "resourceChangeListener" | "eventHandler" | "all";
-  environment?: "dev" | "stage" | "prod";
-  apiToken?: string;
-  imsOrgId?: string;
-  apiKey?: string;
+  environment?: "dev" | "stage" | "prod";  // defaults to "prod"
 }
 ```
 
@@ -143,7 +110,7 @@ const result = await fetchCamBpaFindings({
 
 ## Retries and agent behavior
 
-**MCP tool:** Often implements exponential backoff (e.g. up to 3 attempts, ~30s timeout, backoff 2s / 4s / 8s). **Confirm in server implementation** if behavior changes.
+**MCP tool:** The server implements its own retry and timeout logic internally. Do not add agent-side retries on top unless the table below says otherwise.
 
 **Agent:**
 
@@ -157,7 +124,7 @@ const result = await fetchCamBpaFindings({
 |-----------|--------|--------|
 | Error starts with `The MCP Server is restricted and isn't able to operate on the given` | No | [Verbatim to user](#enablement-restriction-errors-mandatory-handling); stop automatic fallback |
 | Auth 401 / 403 | No | Quote error verbatim; stop. Ask how to proceed (credentials, CSV, or named files) only after stopping. |
-| 404 / "no project found" / unknown `projectId` | No | Quote error verbatim; stop. Show `list-projects` results again if available; **require** user to confirm the correct project or another source (CSV / explicit file list). **No** automatic "local workspace" migration. |
+| 404 / "no project found" / unknown `projectId` | No | Quote error verbatim; stop. **Require** user to confirm the correct project name/ID or choose another source (CSV / explicit file list). **No** automatic "local workspace" migration. |
 | Network / timeout | Once | Retry after ~2s, then quote error verbatim and stop if still failing. |
 | 5xx | Once | Retry after ~2s, then quote error verbatim and stop if still failing. |
 | 400 | No | Quote error verbatim; stop; ask user to fix parameters or pick another path. |