@salesforce/afv-skills 1.63.0 → 1.65.0

package/skills/dx-lifecycle-center/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: dx-lifecycle-center
+description: "Lifecycle Center for DX Inspector and Builder Central. Use this skill first for four jobs: (A) list the orgs connected to DX Inspector; (B) connect a new org (sandbox or scratch, production, OrgFarm) as a deploy target; (C) connect or check the Lifecycle Center org, also written LifecycleCenter org, lifecycle-center, ALMDevOpsCenterHub, DevOps Center hub, or Hub org; (D) deploy, validate, or quick-deploy components that already exist in the user's org to a connected org, and poll a simple-deploy requestId. TRIGGER on: show, list, or pick connected orgs or environments; connect, add, log in to, or repair an org; connect the Lifecycle Center org; deploy, validate, or push components to another org, URL, org id, alias, or environment name. Short asks like \"connect a new org\", \"which orgs can I deploy to\", or \"deploy to my sandbox\" match. These deploys move components from the connected source org to another org, not local project files."
+metadata:
+  version: "1.0"
+  domains: ["Developer Experience"]
+  minApiVersion: "67.0"
+  cliTools:
+    - tool: ["jq"]
+      semver: ">=1.6"
+    - tool: ["sf"]
+      semver: ">=2.67.0"
+---
+
+# Lifecycle Center: Connect Orgs and Deploy Metadata
+
+This skill manages which orgs a user can deploy to, and deploys to them. Everything runs from the **source org**: the org the user built in, where DX Inspector runs. All connections and environments are stored there.
+
+## Operations
+
+| Op | Name | What it does | Details |
+|---|---|---|---|
+| **A** | List orgs | Shows the orgs connected to DX Inspector (the deploy targets), or the current org's details. Also resolves a target the user names. | `references/list-orgs.md` |
+| **B** | Connect an org | Connects a new sandbox or scratch, production, or OrgFarm org as a deploy target, or repairs a half-finished connection. The user signs in through a link. | `references/connect-org.md` |
+| **C** | Lifecycle Center org | Connects, repairs, or checks the Lifecycle Center org (credential `ALMDevOpsCenterHub`). | `references/hub-org.md` |
+| **D** | Deploy | Deploys, validates, or quick-deploys components from the source org to a connected target, then polls to the end. | `references/deploy.md` |
+
+Connect (B) and deploy or quick deploy (D) change an org, so they wait for the user's confirmation first. Listing, status checks, validate runs, and polling do not change a target org.
+
+## Key terms
+
+| Term | Meaning |
+|---|---|
+| Source org | The org the user built in. Use the alias they name, else the default org from `sf org display --json`. Components must already exist in it. |
+| DX Inspector environment | A `DevopsEnvironment` record in the source org with a Named Credential. The deploy targets are exactly these records. |
+| Deploy target | An environment in state `selectable`. An `expired` or `unauthenticated` environment is not a target. |
+| Lifecycle Center org | The Lifecycle Center hub. A separate connection that is never a deploy target. |
+
+## Routing (deterministic)
+
+Scripts and references are paths inside this skill's folder (the folder that holds this file). This skill owns every request below. Pick the operation by these rules **in order; the first match wins**. Do not hand these requests to another skill, and do not answer them from general knowledge.
+
+| # | The request | Operation |
+|---|---|---|
+| 1 | Names the Lifecycle Center org, in any request, however it is spelled: "Lifecycle Center", "lifecyclecenter", "lifecycle-center", "lifecycle_center" (matching rules in `references/hub-org.md`) | **C** |
+| 2 | Deploy, validate, quick deploy, or push components to an org, URL, org id, alias, or environment name; or gives a `requestId` or validation id | **D** |
+| 3 | Show, list, or pick connected orgs or environments; "which orgs can I deploy to"; the current org's details | **A** |
+| 4 | Connect, add, log in to, reconnect, or repair an org or its credential | **B** |
+| 5 | Anything else about connected orgs or DX Inspector environments | **A** |
+
+The Lifecycle Center org rule (1) has two exclusions: "Dev Hub" is never the Lifecycle Center org, and plural phrases such as "DevOps Center orgs", "DX Inspector orgs", "environments", or "orgs connected to DX Inspector" are not the Lifecycle Center org; route them by rules 2 to 5. Details: `references/hub-org.md`.
+
+**Reading the wording.** Before applying the rules, normalize the request: lowercase it, treat hyphens, underscores, and extra spaces as single spaces, and ignore punctuation, one-letter typos in words of five or more letters, and filler such as "please", "can you", "I want to". (Rule 1 also uses the two forms described in `references/hub-org.md`.) Then match on any word in the groups below; the exact phrase does not matter.
+
+| Operation | Action words (any form: "deploy", "deploying", "deployment") | Object words |
+|---|---|---|
+| **D** | deploy, deployment, validate, validation, check only, dry run, quick deploy, quickdeploy, push, send, ship, move, copy, release, add or install (when the object is a component) | components, metadata, classes, flows, objects, or a named org as the destination ("to", "into", "onto") |
+| **B** | connect, connection, add, link, hook up, hookup, authorize, authenticate, log in, login, sign in, set up, setup, register, onboard, reconnect, repair, fix, refresh | org, environment, env, sandbox, scratch, production, prod, orgfarm, org farm |
+| **A** | show, list, see, view, display, which, what, pick, choose, available | orgs, environments, envs, targets, connections, "where can I deploy" |
+
+A request with a **D** action word and a destination, or that names a component and a destination whatever the verb ("add AccountService to my QA sandbox"), is **D**, even when it also contains a **B** word. A **B** action word whose object is an org or environment makes the request **B**, even when words like "connected" or "linked" also appear ("reconnect my sandbox, it shows not connected"). A request with only **B** words is **B**. A request with only **A** words, or a question about what is connected, is **A**. A bare `requestId` or "status of my deploy" is **D**. If no group matches, use the vague-prompt table below.
+
+A request that mixes jobs (for example "connect my sandbox and deploy AccountService to it") takes the lowest-numbered match, here **D**, which runs **B** itself when the target is not connected.
+
+**Vague prompts.** If the message is only "deploy", "push my changes", "connect an org", or similar, do not guess and do not call any API. Ask exactly one question that fixes the first missing input:
+
+| Intent | Ask, in this order |
+|---|---|
+| Deploy | 1. Which components? (`references/deploy.md`, Step 1) 2. Which target org? |
+| Connect | 1. "Is it a sandbox or scratch org, a production org, or an OrgFarm org?" 2. What short name (letters only) should the environment have? |
+| Not clear which | "Do you want to connect an org or deploy components?" |
+
+A bare "deploy" with no DX Inspector context is a question, not a deploy.
+
+## Rules that always apply
+
+- Targets come from the DX Inspector environments in the source org, never from `sf org list` or local aliases.
+- Never deploy to a target that is not `selectable`, never to the source org, and never to the Lifecycle Center org.
+- The Lifecycle Center org never appears in a list and is not mentioned while listing. It is discussed only when the user asks about it.
+- Confirm before every call that changes an org: connect (`connect-org.md`, Step 1) and deploy (`deploy.md`, Step 4). `validate` is the only mode that needs no confirmation.
+- When a connect started from a deploy and finishes, tell the user the org is connected and that you are continuing the deploy, then ask for the deploy confirmation. Connecting never deploys by itself.
+- A sandbox and a scratch org are the same type (`SANDBOX`). Treat their URLs alike.
+- Make one attempt per API call. Never retry in a loop, resubmit after a timeout, or invent an id, credential name, or status.
+- Never ask for, print, or pass an access token. Never show row ids or credential names.
+- Never say a browser was opened. Give the login link and wait for the user to reply **done**.
+- Do not guess a missing input. Ask one question for the first missing input.
+- Ask the user to confirm an org type that the URL host does not decide. Never infer it from an environment name.
+
+## What the user sees
+
+| After | Reply with |
+|---|---|
+| **A** list | Only the table and the closing sentence (`list-orgs.md`, section 4). No raw JSON, no extra offers. |
+| **A** not enabled | The one-sentence message in `list-orgs.md`, section 2. Nothing else. |
+| **B** connect | The sign-in layout with a button-style link (`connect-org.md`, Step 2), then after **done** the connected layout: environment name, org host, type, and status (`connect-org.md`, Step 5). |
+| **C** | The exact sentences in `hub-org.md`. When connecting, the same sign-in and connected layouts as B, in hub form. |
+| **D** | A plain-language report: what was deployed, from where, to where, and the outcome (`deploy.md`, Step 7). No raw JSON. If the deploy is still running after about 2 minutes: the `requestId`, a note that it is in progress, and a request to send the id back to get the status (`deploy.md`, Step 6). |
+
+## If something fails
+
+| Failure | Where to look |
+|---|---|
+| The list or target lookup fails | `references/list-orgs.md`, section 2 |
+| A connect step fails | `references/troubleshooting.md` |
+| A deploy or validate fails | `references/error-handling.md` |
+| The target login is stale | Reconnect that environment (`references/connect-org.md`, repair path), then ask before retrying |
+
+## References
+
+- `references/list-orgs.md`: Operation A. The resolver script, match statuses, the list table, and the not-enabled handling.
+- `references/connect-org.md`: Operation B. Modes, Steps 0 to 5, and rules for connecting an org.
+- `references/hub-org.md`: Operation C. The Lifecycle Center org: hub names, replies, and rules.
+- `references/deploy.md`: Operation D. Steps 1 to 7 for deploy, validate, quick deploy, and polling.
+- `references/request-body.md`: deploy, validate, and quick-deploy request bodies and test levels.
+- `references/connect-api.md`: Environment API and `setupNamedCredential` request and response shapes, status checks.
+- `references/troubleshooting.md`: connect error codes and recovery.
+- `references/error-handling.md`: deploy error codes.
+- `examples/workflows.md`: worked prompts for each operation.
+- `scripts/resolve-environment.sh`: read-only list and identifier resolver.
+- `scripts/poll-deploy-status.sh`: read-only status poller. Reads the Simple Deploy endpoint and `DevopsRequestInfo`, and reports component errors on failure.

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.