@salesforce/afv-skills 1.62.0 → 1.64.0

package/skills/dx-lifecycle-center/examples/workflows.md

@@ -0,0 +1,175 @@
+# Lifecycle Center Examples
+
+Worked prompts, grouped by operation (`SKILL.md`, Operations). Listing, status checks, and polling are **read-only**. Connecting and deploying change an org, so they wait for the user's confirmation first (a validate run does not change the target).
+
+---
+
+## A. List orgs
+
+**A1. "Show the list of connected orgs I can deploy to."**
+
+```bash
+bash scripts/resolve-environment.sh my-dev-org
+```
+
+Reply with only the table and the closing sentence (`references/list-orgs.md`, section 4). The Lifecycle Center org is not in it and is not mentioned.
+
+**A2. "What org am I in?"**
+
+Answer from the `source` block: alias, username, URL, and org id. Nothing else.
+
+**A3. The query fails because the session expired.**
+
+The script reports "query failed, not an enablement problem". Say the error plainly and tell them to reconnect the source org (Reconnect prompt in Builder Central, or `sf org login web --alias <alias>` on a local CLI), then try again. Never say DX Inspector is disabled.
+
+**A4. The query fails because DX Inspector is off.**
+
+The script reports "DevOps Center not enabled or no access". Reply only: "DX Inspector isn't enabled for this org or user, so there are no environments to list or deploy to. An admin needs to enable it." Stop.
+
+**A5. "Show my DevOps Center orgs."**
+
+The phrase is plural, so it is not the Lifecycle Center org. List the environments (A1) and do not mention the hub.
+
+---
+
+## B. Connect an org
+
+**B1. "Connect a new sandbox."**
+
+1. Ask for the environment name (letters only). The type is `SANDBOX`; confirm it.
+2. Check the org is not already connected (`references/connect-org.md`, Step 0).
+3. After the user confirms, `POST /connect/devops/environment`.
+4. Give the `redirectUrl` as a clickable link and wait for **done**. Never say a browser was opened.
+5. `PATCH /connect/devops/environment/<id>`, then list again and confirm the new row shows its URL and org id.
+
+**B2. "Connect https://mydomain--qa.sandbox.my.salesforce.com."**
+
+The host contains `.sandbox.`, so the type is `SANDBOX` without asking. Ask only for the environment name.
+
+**B3. "Connect my org."**
+
+The type is not decided by anything the user said. Ask: "Is it a sandbox or scratch org, a production org, or an OrgFarm org?" Never default. A scratch org is handled exactly like a sandbox (`SANDBOX`).
+
+**B4. "Connect the org I'm already in."**
+
+The identifier is the source org. Say it cannot be connected as its own deploy target and ask which other org they mean.
+
+**B5. The environment exists but was never finished.**
+
+The row shows as not authenticated. Do not POST again. Get a fresh link with `GET /connect/devops/environment/<id>`, wait for **done**, then PATCH once.
+
+**B6. What the user sees while connecting.**
+
+Sign-in (Step 2):
+
+> **Connect `QA`**
+>
+> **[Sign in to `QA` →](https://mydomain--qa.sandbox.my.salesforce.com/services/oauth2/authorize?...)**
+>
+> 1. Sign in with the user DX Inspector should act as, and approve access.
+> 2. Come back here and reply **done**.
+>
+> Link not working? Copy it: `https://mydomain--qa.sandbox.my.salesforce.com/services/oauth2/authorize?...`
+
+Connected (Step 5):
+
+> **✅ `QA` is connected**
+>
+> | Org | Type | Status |
+> |---|---|---|
+> | `mydomain--qa.sandbox.my.salesforce.com` | Sandbox | Ready to deploy to |
+
+The Lifecycle Center org uses the same two layouts with its own heading, button text, and a Hub type column.
+
+---
+
+## C. Lifecycle Center org
+
+**C1. "Connect me to the hub org."**
+
+1. "Hub org" is an ambiguous name, so ask: "Do you mean the Lifecycle Center org (the Lifecycle Center hub)?" ("Connect the Lifecycle Center org" is a certain name: skip the question.)
+2. On yes, check the credential. If it is configured, reply only: "The Lifecycle Center org is already configured." Stop.
+3. If it is not configured, confirm, create the credential, and give the login link labeled **Connect to Lifecycle Center org** (`references/connect-org.md`, hub mode).
+
+**C5. "connect to lifecyclecenter org", "lifecycle-center", "connect lifecycle_center".**
+
+These are spelling variants of the same name. Normalize (lowercase, drop spaces and punctuation), find `lifecyclecenter`, and handle it as C1 without asking which org is meant.
+
+**C6. Wording variants of the other operations.**
+
+After normalizing, these route the same way as the plain phrase: "Pls push AccountService into my QA-sandbox", "ship my flows to prod", "deployment to org-farm env", "dry run to my sandbox" → **D**. "Hook up a new scratch-org", "add sandbx", "sign in to prod", "set up an orgfarm env" → **B** (scratch and `sandbx` are `SANDBOX`, prod is `PRODUCTION`). "which envs can I use", "show linked orgs", "where can I deploy" → **A**.
+
+**C2. "Is the Lifecycle Center org connected?"**
+
+Check the credential. Configured: "The Lifecycle Center org is already configured." Not configured: "The Lifecycle Center org is not configured. Want me to connect it?"
+
+**C3. "Deploy AccountService to the Lifecycle Center org."**
+
+Make no API call. Ask: "Do you mean the Lifecycle Center org, or a different org?" For the Lifecycle Center org, explain that a deploy cannot go there because it is the Lifecycle Center hub, and offer to connect an org as a regular deploy target. For a different org, ask which and continue at `references/deploy.md`, Step 2.
+
+**C4. "Why isn't the Lifecycle Center org in my list?"**
+
+Say it is the Lifecycle Center hub, kept separate from deploy targets, and is never part of the deploy list.
+
+---
+
+## D. Deploy
+
+**D1. "Deploy AccountService to https://mydomain--mysandbox.sandbox.my.salesforce.com."**
+
+```bash
+bash scripts/resolve-environment.sh my-dev-org https://mydomain--mysandbox.sandbox.my.salesforce.com
+```
+
+- `matched` and `selectable`: confirm the row back with name, URL, and org id, build the request, show the Step 4 confirmation, then submit.
+- `not-connected`: say so and offer to connect it, carrying the URL into the connect flow (D2).
+
+The same call works with an alias (`my-sandbox`), an org id (`00D5g000001AbCd`), or an environment name (`MySandbox`).
+
+**D2. Deploy to an org that is not connected yet.**
+
+**User prompt:** "Deploy AccountService to my QA sandbox."
+
+1. The lookup says `not-connected`. Offer to connect it. The user agrees.
+2. Run the connect flow (B1). When it finishes, say: "`QA` is now connected. I'll continue deploying `AccountService` to it."
+3. Go straight to the Step 4 confirmation. Nothing is deployed until the user says yes.
+
+**D3. "Deploy."**
+
+Make no API call. Ask one question: which components to deploy. Then ask for the target.
+
+**D4. "Validate AccountService against production," then quick deploy.**
+
+State what you will validate, then submit with `"isCheckDeploy": true` (`references/request-body.md`), then:
+
+```bash
+bash scripts/poll-deploy-status.sh <requestId> my-dev-org 10 100
+# Exit codes: 0 succeeded, 2 failed or not found, 3 timeout, 1 usage or call error (4 only with --once)
+```
+
+On success, report the validation id from `metadata.deployId` and offer a quick deploy with it. For the quick deploy, send only `isQuickDeploy` and `checkDeployIdentifier`. If it is still running after 2 minutes, see D9; never resubmit.
+
+**D5. "Check request `<requestId>`" or a `requestId` from earlier.**
+
+Skip the component and target steps. Poll once:
+
+```bash
+bash scripts/poll-deploy-status.sh --once <requestId> my-dev-org
+# Exit 4 means still processing: report the status and step
+```
+
+**D9. The deploy takes more than 2 minutes.**
+
+The poll exits `3`. Reply: "Your deploy is still running. Request id: `<requestId>`. Send me this id and I'll check its status." Stop polling. When the user sends the id, run `bash scripts/poll-deploy-status.sh --once <requestId> my-dev-org` and report the status in plain language.
+
+**D8. The user gives only an id starting `0Af`.**
+
+It is a validation id, not a `requestId`: never poll it. Ask whether to quick deploy it and to which target, then show the quick-deploy confirmation (`references/deploy.md`, Step 4).
+
+**D6. The user names two targets.**
+
+Deploy to the first, report, then ask before starting the second. Each target gets its own confirmation.
+
+**D7. The target answers `Bad_OAuth_Token` or `TARGET_ORG_SESSION_EXPIRED`.**
+
+The stored login for that environment is stale. Say so, reconnect that environment (`references/connect-org.md`, repair path), and ask before trying the deploy again.

package/skills/dx-lifecycle-center/references/connect-api.md

@@ -0,0 +1,123 @@
+# DX Inspector Named Credential Connect API
+
+All calls target the **development org** (where DX Inspector runs). This skill requires API v67.0 or later. The caller needs DevOps common API access (`USER_HAS_DEVOPS_COMMON_API_ACCESS`). Portal users are rejected.
+
+Both calls are part of the DevOps Center Connect API (v67.0).
+
+---
+
+## `/connect/devops/environment` (deploy targets)
+
+Creates the NC, the EC, **and the `DevopsEnvironment` row** that simple-deploy requires. `setupNamedCredential` never creates the row.
+
+Part of the DevOps Center Connect API (v67.0).
+
+| Method | Path | Body | Result |
+|---|---|---|---|
+| POST | `/connect/devops/environment` | `{envName, orgType, isDevEnv?, replaceEnvironmentId?}` | `{id, name, namedCredential, externalCredential, redirectUrl, orgType, isDevEnv}` |
+| PATCH | `/connect/devops/environment/{id}` | none | `{id, organizationId, orgUrl, status, message}` after the login. `name` and `namedCredential` are not returned; keep them from the POST |
+| GET | `/connect/devops/environment/{id}` | none | The environment, with a fresh `redirectUrl` pinned to the row's org URL: use it for the repair link |
+| DELETE | `/connect/devops/environment/{id}` | none | Removes the NC/EC and the row |
+
+- `envName` and `orgType` are required. `orgType` is `PRODUCTION`, `SANDBOX`, or `ORGFARM`; it maps to `ORG_TO_ORG`, `ORG_TO_SANDBOX_ORG`, `ORG_TO_ORGFARM_ORG`.
+- The NC/EC name is generated as `<letters-of-envName>_<epochMillis>`.
+- POST sets up the NC/EC, builds the OAuth `redirectUrl`, then inserts the row. The user logs in at `redirectUrl`; PATCH then reads `/services/oauth2/userinfo` through the NC, rewrites the callout URL to the real My Domain, and stores `organizationId` and `orgUrl` on the row.
+- Errors are prefixed `TARGET_ORG_ENVIRONMENT_CREATION_FAILED`, `TARGET_ORG_AUTHENTICATION_STATUS_CHECK_FAILED` (401/403), `TARGET_ORG_AUTHENTICATION_TIMEOUT` (408/504), or `TARGET_ORG_UNKNOWN_ERROR`.
+
+---
+
+## `/connect/devops/setupNamedCredential` (hub)
+
+The POST and PATCH take the same flat JSON body:
+
+```json
+{ "namedCredentialName": "<name>", "namedCredentialType": "<DevopsAuthType>" }
+```
+
+Use `ORG_TO_ORG`, `ORG_TO_SANDBOX_ORG`, or `ORG_TO_ORGFARM_ORG`. Any other value returns `400 namedCredentialType is not supported.`
+
+### POST: create the credential and get the login URL
+
+Server behavior (`setUpNamedCredentialsForDevops`, then `getOAuthCredentialAuthUrl`):
+
+1. **External Credential.** If missing, it creates one with:
+   - developer name and label set to `<name>`,
+   - protocol **OAuth**,
+   - `ExternalAuthIdentityProvider` set to the platform standard IdP for the type:
+
+     | Type | IdP |
+     |---|---|
+     | `ORG_TO_ORG` | `sfdc.ALMDevOpsOrgStandardIdP` |
+     | `ORG_TO_SANDBOX_ORG` | `sfdc.ALMDevOpsSandoxOrgStandardIdp` |
+     | `ORG_TO_ORGFARM_ORG` | `sfdc.ALMDevOpsOrgFarmOrgStandardIdp` |
+
+   - `AdditionalRefreshStatusCode` set to `403`,
+   - one **PerUserPrincipal** (sequence 1).
+
+   The IdP uses the authorization code flow with PKCE. The client id and secret come from the platform secrets store, so no per-org connected app is needed.
+2. **Named Credential.** If missing, it creates a `SecuredEndpoint` NC linked to the EC, with:
+   - `generateAuthorizationHeader=true`, `allowMergeFieldsInHeader=true`, `allowMergeFieldsInBody=false`,
+   - a **placeholder** callout URL (the login host),
+   - headers `target_org_auth_token: Bearer {!$Credential.OAuthToken}` and `x-salesforce-region`.
+3. **Principal access.** Grants the EC principal to the permission set `AccessDevOpsCenterNamedCredentials` ("Access DevOps Center Named Credentials").
+4. **Response.** Returns `{"redirectUrl": "<OAuth start URL>"}`, HTML-escaped, so you must replace `&amp;` with `&`.
+
+The POST is **idempotent**: existing NCs and ECs are reused. Errors inside steps 1–3 are **logged and swallowed**, so a "successful" POST can still leave things half-created. Always verify with *Check credential status*. An empty `redirectUrl` means URL generation failed.
+
+Error wrapping: `DOCE_AUTHENTICATION_FAILED:<msg>` or `DOCE_AUTH_UNKNOWN_ERROR:<msg>` (500), and `INVALID_INPUT` (400).
+
+### PATCH: finalize after the OAuth login
+
+Server behavior (`updateNamedCredentialsForDevops`):
+
+1. Returns `404 Named credential does not exist: <name>` if the NC is missing.
+2. Calls `callout:<name>/services/oauth2/userinfo` and takes the org URL from `urls.rest`. **This requires the OAuth token from the browser login.**
+3. Pre-warms the remote API version cache (`GET /services/data`).
+4. Rewrites the NC callout URL to the org URL. It keeps the label, type, callout options, and EC link.
+
+The response is `{"namedCredentialName": "<name>", "calloutUrl": "<org url>", "redirectUrl": null}`.
+
+On failure it returns `DOCE_CONNECTION_UPDATE_FAILED:<msg>` and **also clears the user's saved DX Inspector selections**. Unexpected failures return `DOCE_AUTH_UNKNOWN_ERROR:<msg>`.
+
+---
+
+## Check credential status
+
+Use the standard Named Credentials Connect API in the dev org:
+
+```bash
+# External credential and its per-user principal status
+sf api request rest "/services/data/v<ver>/named-credentials/external-credentials/<name>" \
+  --target-org <dev-org-alias>
+# → principals[].principalType == "PerUserPrincipal", principals[].authenticationStatus == "Configured" | "NotConfigured"
+
+# Named credential callout URL
+sf api request rest "/services/data/v<ver>/named-credentials/named-credential-setup/<name>" \
+  --target-org <dev-org-alias>
+# → calloutUrl  (placeholder login host before PATCH, org My Domain after); calloutStatus "Enabled"
+
+# List named credentials (diagnostics only; deploy targets come from DevopsEnvironment)
+sf data query --use-tooling-api \
+  --query "SELECT DeveloperName FROM NamedCredential ORDER BY CreatedDate DESC" \
+  --target-org <dev-org-alias> --json
+```
+
+Tooling `NamedCredential.Endpoint` is `null` for these `SecuredEndpoint` credentials, so always read `calloutUrl` from the `named-credential-setup` GET. DevOps-created target credentials match `<letters>_<millis>`. Never build the deploy-target list from this query.
+
+A missing credential returns `NOT_FOUND` ("We couldn't access the credential(s)... might not exist") on either GET. That means the credential does not exist, or the user lacks access to it. `authenticationStatus` is reported **for the running user**: the token is per user, so another user's login does not count.
+
+| EC principal | NC callout URL | State |
+|---|---|---|
+| — (404) | — (404) | Not created. Run POST. |
+| `NotConfigured` | login host | Created, but login not done. Run browser login, then PATCH. |
+| `Configured` | login host | Login done, PATCH missing. Run PATCH. |
+| `Configured` | org My Domain | Ready. |
+
+---
+
+## How the flows consume the credential
+
+| Flow | Dev-org endpoint | Credential use |
+|---|---|---|
+| Deploy | `POST /connect/devops/simple-deploy/deploy` with `{"namedCredential": "<name>", ...}` | Calls `userinfo` through the NC (refreshing the token if needed), then forwards the target token and instance URL to the deploy service. `TARGET_ORG_NAMED_CREDENTIAL_NOT_AUTHENTICATED` means the principal is not configured. |
+| Hub type | `GET /connect/devops/doceConnectionType` | Reads the hub `DevHubSettings` through `ALMDevOpsCenterHub` and returns `CORE` or `MANAGED_PACKAGE`. |

package/skills/dx-lifecycle-center/references/connect-org.md

@@ -0,0 +1,184 @@
+# Connecting an Org (Named Credential Setup)
+
+Creates and configures the Named Credential (NC) and External Credential (EC) that DX Inspector uses to call another org, through `/connect/devops/setupNamedCredential`. Use it when the user wants to connect an org, or a deploy needs a target that is not connected yet.
+
+The **development org** is the source org, where DX Inspector runs. It holds every credential, so every API call here targets that org (`<dev-org-alias>`). The org being connected to is touched only through the browser login. API shapes and status checks: `connect-api.md`. Failures: `troubleshooting.md`.
+
+## Modes
+
+| Mode | Used by | NC/EC name | Type field |
+|---|---|---|---|
+| **Deploy target** | Operation B, and Operation D when its target is not connected | Generated by the server: `<EnvName>_<epochMillis>` (letters only in `EnvName`, which must contain at least one letter). Uses the **Environment API**, which also creates the `DevopsEnvironment` row | `orgType` `PRODUCTION`, `SANDBOX`, or `ORGFARM` |
+| **Lifecycle Center org** (the hub) | `hub-org.md` | Fixed: `ALMDevOpsCenterHub` (exact casing). Uses `setupNamedCredential`; no `DevopsEnvironment` row is needed | `ORG_TO_ORG` |
+
+**Why two APIs:** `setupNamedCredential` creates only the NC and EC. It never creates a `DevopsEnvironment` row, and deploy needs that row (`targetEnvironmentId`). For a deploy target always use `POST /connect/devops/environment`, which creates the NC, the EC, and the row in one call.
+
+Target org to type (deploy mode sends `orgType`; hub mode sends `namedCredentialType`, normally `ORG_TO_ORG` for the hub org):
+
+| Target org | `orgType` (deploy) | `namedCredentialType` (hub) |
+|---|---|---|
+| Production or Developer Edition (logs in at login.salesforce.com) | `PRODUCTION` | `ORG_TO_ORG` |
+| Sandbox or scratch org (logs in at test.salesforce.com; both are the same type) | `SANDBOX` | `ORG_TO_SANDBOX_ORG` |
+| OrgFarm org | `ORGFARM` | `ORG_TO_ORGFARM_ORG` |
+
+The type picks the login page. The API takes no login URL, and the PATCH later discovers the org's real My Domain from the login. If the user gives an org URL instead of a type, map it by host, checking rows top to bottom (first match wins, so an OrgFarm sandbox is a sandbox):
+
+| Host pattern | Type |
+|---|---|
+| Contains `.sandbox.` (e.g. `*.sandbox.my.salesforce.com`), or `test.salesforce.com`, or contains `.scratch.` | Sandbox (scratch orgs included) |
+| Starts with `orgfarm-` | OrgFarm |
+| Other `*.my.salesforce.com`, `login.salesforce.com` | Production |
+
+Read the type from any common spelling, ignoring case, spaces, and hyphens: sandbox, sbx, sand box, test org, scratch, scratch org, scratchorg → `SANDBOX`; production, prod, prd, live, developer edition, dev edition → `PRODUCTION`; orgfarm, org farm, org-farm → `ORGFARM`. A word that fits none of these is not a type: ask.
+
+If the type is still ambiguous (for example only an environment name like "MySandbox", or a vague "connect my org"), **ask the user**; never default. Never infer the type from the environment name: a wrong type sends them to the wrong login host.
+
+---
+
+## Step 0 — Resolve inputs and check for an existing credential
+
+1. Resolve `<dev-org-alias>`: the alias the user named, else the default org from `sf org display --json`. Read `result.apiVersion` as `<ver>`; it must be at least `67.0`.
+2. Determine the mode. Hub mode only when reached from `hub-org.md`; every other connect is deploy mode. In deploy mode also determine the target org type and a short environment name.
+3. Check whether a usable credential already exists (`connect-api.md`, *Check credential status*).
+   - **Hub mode:** check `ALMDevOpsCenterHub`.
+   - **Deploy mode:** run the environment lookup (`list-orgs.md`) using the org's **URL, org id, or local alias only**, never the environment name the user wants to give it. If `sourceMatched` is `true`, say it cannot be connected as its own deploy target and ask for another org. If a row matches, check its `NamedCredential`. A row that matches only by name belongs to another org: that name is taken, so ask for a different one. If the user gave no URL, org id, or alias, there is nothing to match: create.
+
+| Finding | Action |
+|---|---|
+| Exists, principal `Configured`, callout URL is the real org (not a login host) | Stop. Already connected; return to the calling flow with the NC name. **Hub, asked for directly by the user:** reply only "The Lifecycle Center org is already configured." with no reconnect offer, org details, or login link. |
+| Exists but `NotConfigured`, or callout URL is still a login host | Repair. **Hub:** re-run Steps 1–4 with the same name (POST is idempotent). **Deploy:** reuse the existing row's `Id`; do **not** POST a second environment. Confirm first: "I'll reconnect `<name>`: this refreshes its credential. Proceed?" Then get a fresh login URL with `GET /connect/devops/environment/<id>` (its `redirectUrl`) and go to Step 2. |
+| Matched row is `expired` | Not repairable. Create a new environment (Steps 1–4) with a new name. |
+| `ambiguous` | Show the matches and ask which one. |
+| Does not exist | Create. Run Steps 1–4. |
+
+## Step 1 — Create the credential and get the login URL (POST)
+
+**This creates metadata in the dev org. Confirm with the user first:**
+
+> "I'll connect `<name>` (`<type>`) to DX Inspector in `<dev-org-alias>`: this creates the environment record and its credential. Proceed?"
+
+**Hub mode** has no environment record. Say instead: "I'll connect the Lifecycle Center org to `<dev-org-alias>`: this creates its credential. Proceed?" For a repair, add that a failed finish step clears their saved DX Inspector selections.
+
+**Deploy mode** — Environment API (creates NC, EC, and the `DevopsEnvironment` row):
+
+```bash
+sf api request rest "/services/data/v<ver>/connect/devops/environment" \
+  --method POST \
+  --body '{"envName":"<name>","orgType":"<PRODUCTION|SANDBOX|ORGFARM>","isDevEnv":false}' \
+  --target-org <dev-org-alias>
+```
+
+Response: `{id, name, namedCredential, redirectUrl, orgType, ...}`. Keep `id` (the `DevopsEnvironment` Id) and `namedCredential`. Send only `envName`, `orgType`, and `isDevEnv`. A `BAD_REQUEST` naming `Invalid org type` means the value above was wrong.
+
+**Hub mode** — `setupNamedCredential`:
+
+```bash
+sf api request rest "/services/data/v<ver>/connect/devops/setupNamedCredential" \
+  --method POST \
+  --body '{"namedCredentialName":"ALMDevOpsCenterHub","namedCredentialType":"ORG_TO_ORG"}' \
+  --target-org <dev-org-alias>
+```
+
+Response: `{"redirectUrl": "..."}`. In both modes replace every `&amp;` in `redirectUrl` with `&`.
+
+The server **swallows setup errors** and can still return an empty `redirectUrl`. If it is empty, stop and diagnose with `troubleshooting.md`. Do not continue to the PATCH. In deploy mode an environment row may already exist; tell the user and offer to delete it with `DELETE /connect/devops/environment/<id>` (removes the NC/EC too) after confirmation.
+
+## Step 2 — User completes the OAuth login via a link
+
+This step **requires a human** (authorization code with PKCE, stored per user). The CLI cannot open the user's browser from a chat, so **do not claim a browser was opened** and do not run `sf org open`. Show the sign-in as a button-style link, using exactly this layout (deploy mode shown; `<name>` is the environment name):
+
+> **Connect `<name>`**
+>
+> **[Sign in to `<name>` →](<redirectUrl>)**
+>
+> 1. Sign in with the user DX Inspector should act as, and approve access.
+> 2. Come back here and reply **done**.
+>
+> Link not working? Copy it: `<redirectUrl>`
+
+Hub mode uses the same layout with the heading **Connect the Lifecycle Center org** and the button text **Connect to Lifecycle Center org →**.
+
+Rules for the link:
+- Use the full `redirectUrl` after the `&amp;` fix, unmodified, as the Markdown link, and again in the "Link not working?" line. Show the sign-in once; do not repeat it in other words.
+- Only the newest link works. Each new Step 1 run (hub) or `GET /connect/devops/environment/<id>` (deploy) replaces the previous one, so never run one while the user is still signing in, and never show an older link again. If the user reports it expired or failed, get a fresh one the same way.
+- The user should open it in a browser that is signed in to the dev org as the same user the CLI uses (the final confirmation happens on the dev org). Otherwise the browser lands on that org's login page: tell them to sign in there, then use the link again.
+- Right after showing the layout, wait for the user to reply **done**. Do not run other steps in between.
+
+**Hub mode:** the user must log in as someone holding the **DevOps Center User** permission set in the hub org.
+
+## Step 3 — Confirm the OAuth token landed
+
+When the user says they are done, check the EC principal (`connect-api.md`, *Check credential status*).
+
+| Status | Action |
+|---|---|
+| `Configured` | Go to Step 4. |
+| `NotConfigured` | The login did not complete. Ask whether they saw an error and offer to re-run Step 1 for a fresh URL. Do not PATCH. |
+
+## Step 4 — Finalize: set the real org URL (PATCH)
+
+The NC is created pointing at a placeholder login host. The PATCH calls `/services/oauth2/userinfo` through the NC, rewrites the callout URL to the real My Domain, and (deploy mode) stores the target's org id and URL on the `DevopsEnvironment` row. Until it succeeds, callouts go to the wrong host.
+
+**Deploy mode:**
+
+```bash
+sf api request rest "/services/data/v<ver>/connect/devops/environment/<id>" \
+  --method PATCH --target-org <dev-org-alias>
+```
+
+Success returns `id`, `organizationId`, `orgUrl`, `status`, and `message`. Keep `namedCredential` from the POST. Verify `orgUrl` is a My Domain URL and **not** `login.salesforce.com` or `test.salesforce.com`.
+
+**Hub mode:**
+
+```bash
+sf api request rest "/services/data/v<ver>/connect/devops/setupNamedCredential" \
+  --method PATCH \
+  --body '{"namedCredentialName":"ALMDevOpsCenterHub","namedCredentialType":"ORG_TO_ORG"}' \
+  --target-org <dev-org-alias>
+```
+
+Success returns `{"namedCredentialName": "...", "calloutUrl": "https://<org>.my.salesforce.com", "redirectUrl": null}`. Verify `calloutUrl` the same way.
+
+- On failure (`DOCE_CONNECTION_UPDATE_FAILED`, a 404, a userinfo failure, or `TARGET_ORG_*` codes) see `troubleshooting.md`.
+- **Never retry the PATCH in a loop.** **Hub mode only:** a failed PATCH also **clears the user's saved DX Inspector selections**. Tell the user.
+
+## Step 5 — Verify and hand off
+
+1. Re-run the status check. Expect principal `Configured` and a callout URL equal to the PATCH `calloutUrl`.
+2. **Hub mode only:** optionally record the hub type the way DX Inspector does. A `CORE` or `MANAGED_PACKAGE` response proves the NC works end to end.
+
+   ```bash
+   sf api request rest "/services/data/v<ver>/connect/devops/doceConnectionType" --target-org <dev-org-alias>
+   ```
+
+3. Show the result with exactly this layout, no raw JSON, and never the credential name.
+
+   Deploy mode:
+
+   > **✅ `<name>` is connected**
+   >
+   > | Org | Type | Status |
+   > |---|---|---|
+   > | `<host of orgUrl>` | Sandbox, Production, or OrgFarm | Ready to deploy to |
+
+   Hub mode (use the `calloutUrl` host; leave out the Hub type column when the type call was skipped or unknown):
+
+   > **✅ The Lifecycle Center org is connected**
+   >
+   > | Org | Hub type | Status |
+   > |---|---|---|
+   > | `<host of calloutUrl>` | Core or Managed package | Connected |
+
+   Say "Sandbox" for a scratch org too. If the status check in item 1 did not return `Configured`, do not show this layout: say the sign-in is not complete and offer a fresh link.
+4. **Deploy mode:** re-run the environment lookup (`list-orgs.md`) and confirm the row with the `id` from Step 1 is listed, `selectable`, with its `NamedCredential`. Carry that `id` and `namedCredential` forward. If it is missing, do not deploy and do not invent an id; report that the credential is connected but the row was not found.
+5. **If this connect started from a deploy request** (`deploy.md`, Step 2): tell the user in one sentence that `<name>` is connected and that you are continuing the deploy of the components they gave. Then go to `deploy.md`, Step 3 and Step 4. The deploy confirmation is theirs to give; do not submit anything before it. If the connect did not start from a deploy, end here and do not offer anything beyond the result.
+
+## Rules
+
+- Never fabricate an NC name, callout URL, or `Configured` status. Report only what the org returned.
+- Never print access tokens, and never pass `headerTargetAccessToken` in place of a stored connection.
+- One environment per target org. Do not reuse a deploy NC for a different org; create a new environment.
+- Deploy-target connections always use the Environment API so the `DevopsEnvironment` row exists. Never use `setupNamedCredential` alone for a deploy target.
+- Never tell the user a browser was opened. Give the link.
+- Do not rename `ALMDevOpsCenterHub`. DX Inspector looks it up by that exact name.
+- Only the org-to-org types (`ORG_TO_ORG`, `ORG_TO_SANDBOX_ORG`, `ORG_TO_ORGFARM_ORG`) are used here.

package/skills/dx-lifecycle-center/references/deploy.md

@@ -0,0 +1,153 @@
+# Deploy, validate, or quick deploy (Operation D)
+
+Deploys metadata that already exists in the **source org** (the org the user built in) to a **target environment** connected in DX Inspector. It calls `POST /connect/devops/simple-deploy/deploy`, then polls `GET` until the request reaches a final status.
+
+Metadata only. Data (record) deploys are not supported. Needs Salesforce API **v67.0** or later.
+
+| Mode | When | Request body |
+|---|---|---|
+| `deploy` (default) | The user wants the components in the target | `references/request-body.md` |
+| `validate` | The user asks for a check only. For a Production target, recommend it first (Step 3), but never switch the mode without their agreement | `isCheckDeploy: true` |
+| `quickDeploy` | The user has a successful validation id (`0Af…`) to deploy | `isQuickDeploy: true` + `checkDeployIdentifier` |
+
+## Before Step 1
+
+1. Source org: the alias the user named, else the default org from `sf org display --json`. If it cannot be read, ask which org they build in.
+2. Read `result.apiVersion` from that output. If it is below `67.0`, stop and say the org's API version is too old for this skill.
+3. One target per run. If the user names several, deploy to the first, finish, and ask before starting the next. Each target gets its own confirmation (Step 4).
+
+## Step 1: Components
+
+Skip this step for `quickDeploy`: it sends no `changes`.
+
+Ask: "Which components do you want to deploy? Give the name and type of each (for example `AccountService` ApexClass, `Account.Tier__c` CustomField), and tell me whether each is **new**, **changed**, or **removed**."
+
+Map the answer to the wire `operation`: new → `add`, changed → `modify`, removed → `delete`. Anything unclear → `modify`.
+
+Build `changes[]` as `{fullName, type, operation}`. All three are required and non-blank. Types are Metadata API type names (`ApexClass`, `CustomObject`, `CustomField`, `Flow`, `LightningComponentBundle`, …). If the user gives a name without a type, ask; do not guess.
+
+## Step 2: Target environment
+
+Follow `references/list-orgs.md` with the identifier the user gave (sections 1 to 3). Then:
+
+| Outcome | Do |
+|---|---|
+| Target is `matched` and `selectable` | Carry `id` and `namedCredential` from that row. Go to Step 3. |
+| No target named yet | Ask which target. Show the list (`list-orgs.md`, section 4) if they want to choose. |
+| `not-connected` | Offer to connect it. If the user agrees, run `references/connect-org.md` (deploy-target mode), then **continue as below**. |
+| `unauthenticated` | Offer to finish connecting it (repair path), then continue as below. |
+| `expired` | Not deployable. Ask for another target or offer to connect a new one. |
+
+**Continuing after a connect.** When the connect flow finishes and the environment shows as `selectable`, tell the user in one sentence that `<name>` is now connected, and that you will continue the deploy of `<components>` to it. Then go straight to Step 3 and Step 4. The Step 4 message is the confirmation they give before anything is deployed; connecting an org never deploys by itself.
+
+If the user connected the org but gave no components yet, ask for them (Step 1) after the connect.
+
+## Step 3: Build the request
+
+Write the POST body to a temp file (`BODY=$(mktemp)`; this avoids shell-quoting nested JSON):
+
+```json
+{
+  "namedCredential": "<NamedCredential>",
+  "targetEnvironmentId": "<DevopsEnvironment Id>",
+  "requestBody": {
+    "changes": [{"fullName": "AccountService", "type": "ApexClass", "operation": "modify"}],
+    "testOptions": {"level": "NoTestRun", "tests": []}
+  }
+}
+```
+
+Mode variants and test-level rules: `references/request-body.md`.
+
+- **Production target:** recommend a `validate` run first unless the user already has a successful one, and default the test level to `RunLocalTests`. An explicit user choice of test level always wins.
+- **Quick deploy:** the validation id comes from the user or from an earlier `validate` in this conversation (`metadata.deployId`). If you have neither, ask for it. Never invent one. Send only `isQuickDeploy` and `checkDeployIdentifier`, never `changes` or `testOptions`.
+
+## Step 4: Confirmation gate
+
+**This call changes the target org (except `validate`). Do not proceed without an explicit yes.** Show:
+
+> "I'm about to **<deploy | validate | quick deploy>** from `<source-org-alias>` to `<environment Name>` (<OrgType>):
+> - Components: <n> (<first few, with new/changed/removed>)
+> - Test level: <level>
+>
+> Shall I proceed?"
+
+For **quick deploy**, replace the components and test-level lines with `- Validation id: <0Af…>`, and use the same target environment the validation ran against. If the user gives only the id, ask which target it was validated against.
+
+Call out any `delete` and any Production target explicitly. `validate` does not change the target, so it needs no confirmation, but still state what you are about to validate.
+
+## Step 5: Submit
+
+```bash
+sf api request rest \
+  "/services/data/v67.0/connect/devops/simple-deploy/deploy" \
+  --method POST \
+  --body @"$BODY" \
+  --target-org <source-org-alias>
+```
+
+Read `response.requestId`. If it is absent, the call failed: use `references/error-handling.md`. Make **one** attempt. Never retry in a loop, never resubmit after a timeout, and never invent a `requestId`.
+
+## Step 6: Poll to completion
+
+Polling is automatic and read-only. Every check reads **two sources**, and a terminal state from **either** one ends it: the Simple Deploy status endpoint (live `step`, `metadata.deployId`) and the `DevopsRequestInfo` record for the `requestId` (`Status` is `SUCCESS` or `ERROR`; it is the same record commit polling uses).
+
+```bash
+bash scripts/poll-deploy-status.sh <requestId> <source-org-alias> 10 100
+```
+
+Checks come at 3 s, then 5 s, then every 10 s, for at most **100 seconds**, about 2 minutes in all. Set the shell tool timeout to at least 180 seconds so the run is not killed before it exits. Progress lines (`status=… step=… request-info=…`) go to stderr; relay the current step to the user while waiting. Never say the deploy is "still waiting" after the script has printed a result.
+
+On a failed deploy the script also reads the failure detail that Core attaches to the request (the `DEPLOYMENT_COMPLETED` `DevopsActivityLog` row). Core fills it in a few seconds after the failure by calling the target org's Metadata API through the deploy's named credential, so **no login to the target org is needed**. The script waits up to 20 s for it (`DETAIL_WAIT`), and skips the wait when the deploy failed before reaching the target org.
+
+The script prints one JSON object when it ends:
+
+| Field | Meaning |
+|---|---|
+| `outcome` | `SUCCEEDED`, `FAILED`, `NOT_FOUND`, `TIMEOUT` (poll ran out of time), or `IN_PROGRESS` (`--once` only) |
+| `step`, `status` | Last phase seen (`RETRIEVE_METADATA`, `DEPLOY_METADATA`, `VALIDATE_METADATA`, …) and its status |
+| `deployId` | The target org's deploy id (`0Af…`). For a successful `validate` this is the id for a quick deploy |
+| `message`, `errorDetails`, `activityMessage` | Failure text. For a failure before the target org (retrieve or validation) this already names the problem; for a failed target deploy it is generic ("Metadata deployment failed with status: Failed"). Prefer these over `errorMessage`, which can be HTML-escaped (`&#39;`) |
+| `deployJobLogURL` | Per-component detail, in the target org |
+| `errorDetail` | Core's detail for a failed target deploy: `numberComponentErrors`, `componentFailures[]` (`componentType`, `fileName`, `problem`, `problemType`, `lineNumber`, `columnNumber`), `testFailures[]` (`name`, `methodName`, `message`, `stackTrace`), `errorMessage` (for example a code-coverage shortfall), `truncated` (only the first 5 of each are kept). `null` when none |
+| `errorDetailUnavailable` | `true` when Core recorded that no detail will come |
+| `decidedBy` | `endpoint` or `request-info`: which source reported the final state |
+| `response` | The raw endpoint response |
+
+Exit codes: `0` succeeded, `2` failed or not found, `3` timeout, `1` usage error or both sources failed, `4` still processing (`--once` only). `outcome` tells `FAILED` from `NOT_FOUND`.
+
+`NOT_FOUND` right after a submit can be transient (the script allows a short grace period, and a `DevopsRequestInfo` row overrides it). If it persists, the id is unknown or older than about 2 days.
+
+On timeout (exit `3`, `outcome` `TIMEOUT`, about 2 minutes), stop polling and tell the user, in plain words, that the deploy has not reported a final status yet but may still be running. Give them what they need to check it later:
+
+- **Request token (`requestId`)**: "Send me this id and I'll check its status."
+- **Deployment id (`deployId`, starts `0Af`)**, only if the result has one: it is the deploy job in the target org. They can find it in the target org under Setup → Deployment Status, or at `deployJobLogURL`.
+- The `step` it had reached.
+- That the deploy also shows in DX Inspector's activity history for this org.
+
+Example: "Your deploy to `<target>` hasn't reported a final status after 2 minutes. It was at `DEPLOY_METADATA` and may still be running. Request token: `<requestId>`. Deployment id: `<deployId>`. Send me the request token any time and I'll check it, or look up the deployment id in `<target>` under Setup → Deployment Status." Never resubmit, and do not keep polling.
+
+For a one-off check, put `--once` **first**: `bash scripts/poll-deploy-status.sh --once <requestId> <source-org-alias>`. It exits `4` while the request is still processing: report the current `step` and do not poll again unless the user asks. With `--once` there is no grace period, so `NOT_FOUND` right after a submit may be transient: say the request is not visible yet and check again shortly, not that it failed.
+
+If the user gives a `requestId` to check (also when they come back with the id from a timeout), skip Steps 1 to 5 and check it once with `--once`, using the source org alias. If the user asks for the status without an id, use the `requestId` from earlier in this conversation; if there is none, ask for it. Then report as in Step 7.
+
+## Step 7: Report
+
+Summarize in plain language: what was deployed, from where, to where, and the outcome. No raw JSON.
+
+- **Succeeded:** say so, with the completion time (`completedAt`). After a successful `validate`, give `deployId` as the validation id and offer a quick deploy with it.
+- **Failed:** always show the error, never just "failed".
+  1. Say which `step` failed. If `errorDetail` is present, use it: list each `errorDetail.componentFailures` entry as `<fileName> (<componentType>), line <lineNumber>: <problem>`, each `testFailures` entry as `<name>.<methodName>: <message>`, and always include `errorDetail.errorMessage` when set (a code-coverage shortfall appears only there, with `numberComponentErrors` at 0). If `truncated` is true, say only the first few are shown and give `deployJobLogURL`.
+  2. If `errorDetail` is `null`, quote `activityMessage` (else `errorDetails`, else `message`). A failure at `RETRIEVE_METADATA` or validation, such as "Entity of type 'CustomField' named 'Book__c.Author__c' cannot be found", is complete as is: the component is missing from the source org.
+  3. If `errorDetail` is `null` and the message is only the generic "Metadata deployment failed with status: Failed", the detail was not attached in time (or `errorDetailUnavailable` is `true`). Say so, give `deployJobLogURL` (also Setup → Deployment Status in the target org), and offer to check again shortly with `--once`.
+  4. Map the error with `references/error-handling.md`, and ask before retrying. Never resubmit on your own.
+
+## Gotchas
+
+| Gotcha | What to do |
+|---|---|
+| Component not in the source org | The deploy retrieves from the source org. Confirm the name and type exist there before submitting. |
+| Quick deploy with `changes` | Forbidden. Send only `isQuickDeploy` and `checkDeployIdentifier`. |
+| Target equals the source org | Not allowed. Ask for a different target. |
+| An id starting `0Af` | It is a validation id, not a `requestId`. Never poll it. If the user gives one alone, ask whether to quick deploy it, and to which target. |
+| Stale target login | Shows only at deploy time (`Bad_OAuth_Token`, `TARGET_ORG_SESSION_EXPIRED`). Reconnect that environment (`connect-org.md`, repair path), then ask before retrying. |