@copado/agentia-cli 1.1.0 → 1.3.0

package/package.json

@@ -12,6 +12,8 @@
     "@oclif/plugin-plugins": "^5",
     "@xmldom/xmldom": "^0.9.12",
     "exceljs": "^4.4.0",
+    "proxy-agent": "^8.0.2",
+    "proxy-from-env": "^2.1.0",
     "semver": "^7.8.5",
     "tty-table": "^7.0.1",
     "uuid": "^14.0.1",
@@ -59,6 +61,7 @@
     "bin": "agentia",
     "dirname": "agentia-cli",
     "commands": "./dist/commands",
+    "helpClass": "./dist/help.js",
     "hooks": {
       "finally": [
         "./dist/hooks/finally/ide-command-event"
@@ -66,7 +69,8 @@
       "init": [
         "./dist/hooks/init/version-warning",
         "./dist/hooks/init/migrate-user-config",
-        "./dist/hooks/init/plugin-host"
+        "./dist/hooks/init/plugin-host",
+        "./dist/hooks/init/cicd-connection"
       ]
     },
     "plugins": [
@@ -94,6 +98,9 @@
       "auth": {
         "description": "Manage authentication credentials"
       },
+      "history": {
+        "description": "Inspect temporary local command history"
+      },
       "adv": {
         "description": "Manage Copado Pipelines Advanced deployments"
       },
@@ -214,6 +221,9 @@
       "cicd:promotion:job-step": {
         "description": "Manage Copado promotion job steps"
       },
+      "cicd:promotion:queue": {
+        "description": "Inspect and clear the promotion job queue"
+      },
       "cicd:notification": {
         "description": "Configure Copado notification subscriptions"
       },
@@ -227,15 +237,45 @@
         "description": "Create and update Agentia Agent Skills"
       },
       "testing": {
-        "description": "Manage Copado Robotic Testing projects, tests, runs, logs, and variables"
+        "description": "Manage Copado Robotic Testing projects, jobs, runs, logs, and variables"
+      },
+      "testing:data-table": {
+        "description": "Manage Copado Robotic Testing data tables"
+      },
+      "testing:job": {
+        "description": "Manage Copado Robotic Testing jobs and their runs"
+      },
+      "testing:job:files": {
+        "description": "Manage files stored in a Copado Robotic Testing job"
+      },
+      "testing:job:runs": {
+        "description": "Inspect and control Copado Robotic Testing job runs"
+      },
+      "testing:job:schedule": {
+        "description": "Manage the schedule for a Copado Robotic Testing job"
+      },
+      "testing:browser": {
+        "description": "Manage Copado Robotic Testing browser sessions"
+      },
+      "testing:project": {
+        "description": "Manage Copado Robotic Testing projects"
+      },
+      "testing:project:permission": {
+        "description": "Manage Copado Robotic Testing project permissions"
+      },
+      "testing:robot": {
+        "description": "Manage Copado Robotic Testing robots"
+      },
+      "testing:user-parameter": {
+        "description": "Manage account-scoped Copado Robotic Testing user parameters"
       },
-      "testing:live": {
-        "description": "Manage Copado Robotic Testing live sessions"
+      "testing:variable": {
+        "description": "Manage Copado Robotic Testing variables and secrets"
       }
     }
   },
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "x-agentia-protected-build": true,
   "x-agentia-protected-files": [
     "dist/lib/runtime.js"

package/templates/skills/agentia-ai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentia-ai
-description: Use this skill when prompting Copado AI agents through the Agentia CLI or MCP, including `agentia ai agent ask`, `agentia ai agent chat`, Plan, Build, Test, Release, Operate, Knowledge, workspace, dialogue, user story, Salesforce org, and component context.
+description: Use this skill when prompting Copado AI agents or using interactive in-app support through the Agentia CLI or MCP, including `agentia help-agent`, `agentia ai agent ask`, `agentia ai agent chat`, Plan, Build, Test, Release, Operate, Knowledge, workspace, dialogue, user story, Salesforce org, and component context.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -11,13 +11,14 @@ Use this skill to ask Copado AI agents through Agentia with the right agent sele
 
 Prefer the `agentia_ai_ask` MCP tool when it is available for single-turn prompts. Use CLI examples as the fallback. Use `agentia ai agent chat` only for interactive terminal sessions.
 
+Use `agentia help-agent` when a person wants interactive Copado product support. It opens without an eager CICD credential preflight, obtains fresh short-lived access per turn, and writes response deltas immediately. Each turn refreshes bounded local context, including dominant CLI/IDE/MCP usage; follow-ups include a bounded redacted digest of successful prior messages. Successful turn pairs are retained separately for at most 24 hours but never restored into a later chat. Use `agentia history list` to inspect sanitized command outcomes or `agentia history clear --yes` to remove command and Help Agent interaction history.
+
 ## Start Here
 
-1. Confirm AI auth with `agentia auth get --ai --json`. Configure missing credentials with `agentia auth set --ai ...` or the supported `AGENTIA_AI_*` environment variables.
-2. Choose exactly one required `--agent` option for `ask`: `plan`, `build`, `test`, `release`, `operate`, or `knowledge`. `orchestrate` is not valid for `ask`.
-3. Choose exactly one required `--agent` option for `chat`: `plan`, `build`, `test`, `release`, `operate`, `knowledge`, or `orchestrate`.
-4. Add useful context flags when available: `--workspace`, `--dialogue`, `--user-story`, `--sf-org`, and `--component`.
-5. Use `--json` for automation. Use `--no-stream` when the caller needs a buffered response.
+1. For `ai agent` and workspace commands, confirm AI auth with `agentia auth get --ai --json`. Configure missing credentials with `agentia auth set --ai ...` or the supported `AGENTIA_AI_*` environment variables. For `help-agent`, confirm CICD auth with `agentia auth get --cicd --json`.
+2. Omit `--agent` by default: `ask` and `chat` use `orchestrate`, which routes work to the right specialist. Pass `--agent plan`, `build`, `test`, `release`, `operate`, or `knowledge` only to target a specialist explicitly.
+3. Add useful context flags when available: `--workspace`, `--dialogue`, `--user-story`, `--sf-org`, and `--component`.
+4. Use `--json` for automation. Use `--no-stream` when the caller needs a buffered response.
 
 ## Reference
 
@@ -29,6 +30,8 @@ Prefer the `agentia_ai_ask` MCP tool when it is available for single-turn prompt
 - Use the Knowledge agent for Copado AI Knowledge grounding and product questions.
 - Use the Plan, Build, Test, Release, and Operate agents according to the lifecycle intent.
 - Do not paste PATs or secrets into prompts.
+- Use `help-agent` only in an interactive terminal; it has no JSON or MCP mode.
+- Treat history as temporary diagnostic context, not an audit log. CLI/IDE command rows can contain sanitized parameters, structured results, and bounded output tails; MCP rows contain metadata only. Successful Help Agent turn pairs are redacted, bounded, and retained separately for up to 24 hours. Raw User-Agent values, secrets, full paths, conversation IDs, and HMACs are excluded.
 
 ## Report Back
 

package/templates/skills/agentia-ai/references/ai-agents.md

@@ -2,7 +2,7 @@
 
 # AI Agents Reference
 
-Use this reference for `agentia ai agent ask`, `agentia ai agent chat`, and the matching `agentia_ai_ask` MCP tool.
+Use this reference for `agentia help-agent`, `agentia ai agent ask`, `agentia ai agent chat`, and the matching `agentia_ai_ask` MCP tool.
 
 ## Authentication And Context
 
@@ -25,9 +25,9 @@ Operational options include `--workspace` and `--timeout`; authentication is res
 | `release` | Release, promotion, packaging, and deployment questions. |
 | `operate` | Operational diagnostics, monitoring, and runbook style questions. |
 | `knowledge` | Copado AI Knowledge grounding, product documentation, personas, and troubleshooting. |
-| `orchestrate` | Chat-only orchestration mode for interactive sessions. |
+| `orchestrate` | Default. Routes the request to the right specialist automatically. |
 
-Pass the selected value with the required `--agent` option. `ask` accepts `plan`, `build`, `test`, `release`, `operate`, or `knowledge`; `chat` also accepts `orchestrate`. `ask` requires a prompt with `-p` or `--prompt`; `chat` is TTY-only and prompts interactively.
+`--agent` is optional and defaults to `orchestrate` for `ask`, `chat`, and the `agentia_ai_ask` MCP tool. Pass a specialist only to target it explicitly. `ask` requires a prompt with `-p` or `--prompt`; `chat` is TTY-only and prompts interactively.
 
 ## Single-Turn Ask
 
@@ -52,6 +52,22 @@ agentia ai agent chat --agent orchestrate --workspace <workspace-id>
 
 Chat creates or reuses one dialogue for the session and supports session slash commands. It is not suitable for headless JSON workflows.
 
+## Interactive Product Support
+
+Use the experimental Help Agent for Copado product questions when a human is present:
+
+```sh
+agentia help-agent
+agentia support
+agentia help --agent
+agentia history list --limit 10
+agentia history clear --yes
+```
+
+All three Help Agent entry points share the same behavior. They open without a CICD user or credential preflight and do not use the separately configured AI PAT. Every request identifies the assistant as a concise Copado expert on Agentia Headless and Copado tools for developers working locally. The system prompt uses retained history to identify dominant CLI/IDE/MCP usage and asks one brief question when tooling or a local-versus-cloud operations flow is unclear. Each turn requests a fresh short-lived HMAC and refreshes CLI version, platform, architecture, workspace basename, normalized current origin, aggregate tool counts, and the three newest sanitized command summaries. Follow-up turns include a deterministic redacted digest of at most six successful prior messages. SSE response deltas render immediately. `/help`, `/clear`, and `/exit` are supported; `/clear` resets the conversation identifier and in-memory digest.
+
+The `history` commands inspect up to 100 sanitized command summaries and clear all temporary history. CLI/IDE rows can contain sanitized parameters, a redacted structured result, and ordered 20 KiB stdout/stderr tails. MCP rows contain only command ID, timing, outcome, CLI version, workspace basename, and `mcp` origin—never arguments, output, results, or errors. Successful Help Agent turn pairs are separately redacted, capped at 4 KiB per message, and retained in private storage for at most 24 hours/100 pairs; they are not restored into later chats. `history clear --yes` deletes both stores. Help Agent has no JSON or MCP mode. Never paste credentials or tokens into prompts.
+
 ## Workspace And Quota Helpers
 
 Use these adjacent commands when the prompt workflow needs context setup:
@@ -68,3 +84,5 @@ Use these adjacent commands when the prompt workflow needs context setup:
 - `--user-story`, `--sf-org`, and `--component` enrich prompt context but do not replace a clear prompt.
 - Streaming is human-friendly. For tools, CI, or follow-up parsing, use `--json` and consider `--no-stream`.
 - `chat` has no MCP equivalent and should not be used in non-interactive shells.
+- `help-agent` requires CICD authentication and a CICD environment where Support AI authentication is enabled.
+- Temporary command history is diagnostic context, not a durable audit log; the operating system may remove it.

package/templates/skills/agentia-cicd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentia-cicd
-description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools: user stories (including current/active story context), cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, Copado Functions, Job Templates, git-hosted CICD extensions, environments, credentials, pipelines, stages, Slack pipeline notification subscriptions, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
+description: Use this skill when managing Copado CICD work with the Agentia CLI or Agentia MCP tools, including user stories (including current/active story context), cloud commit/promote, work publish/submit/done, promotion runs and conflicts, job executions, Copado Functions, Job Templates, git-hosted CICD extensions, environments, credentials, pipelines, stages, Slack pipeline notification subscriptions, and release data templates. Use it whenever the user asks an agent to operate Copado CICD from a terminal, IDE, or headless workflow.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -13,7 +13,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 
 ## Start Here
 
-1. Confirm `agentia auth get --cicd --json` is configured, or that the current process supplies `AGENTIA_CICD_API_KEY` and `AGENTIA_CICD_BASE_URL`.
+1. Confirm `agentia auth get --cicd --json` is configured, or that the current process supplies `AGENTIA_CICD_API_KEY` and `AGENTIA_CICD_BASE_URL`. For sandbox function/template/extension work against a different Copado org, use a named connection (`auth set --connection`) plus `--cicd-connection` / MCP `cicdConnection` instead of swapping the default key.
 2. Identify the domain below and read only the matching reference file.
 3. Before mutating data, read the target record first with the matching `get`, `list`, or `status` command.
 4. Never print credentials, PATs, OAuth signatures, or unmasked environment variables.
@@ -27,13 +27,16 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - Git-hosted Copado CICD extensions (`cicd extension`, experimental): [references/extensions.md](references/extensions.md)
 - Copado Job Templates (`cicd template`, not data templates): [references/templates.md](references/templates.md)
 - Copado environments, environment credentials, and browser authentication: [references/environments-and-credentials.md](references/environments-and-credentials.md)
-- Pipelines, environment connections, stages, and stage connections: [references/pipelines.md](references/pipelines.md)
+- Pipelines, automations, quality gates, extension configurations, environment connections, stages, and stage connections: [references/pipelines.md](references/pipelines.md)
 - Slack notification subscriptions on a pipeline (`agentia_notification_configure` / CLI): [references/notifications.md](references/notifications.md)
 - Release data templates, records, matching, sync, dataset files, and data commits: [references/data.md](references/data.md)
 
+For **Org Intelligence** (read Salesforce metadata against a sandbox/developer org credential; prefer local files first, then the org; metadata only—not data, not edits), use the separate skill `agentia-metadata/SKILL.md` (`cicd metadata explore` / MCP `agentia_metadata_explore`). For the **Copado dependency graph**—including local DX `--path` and story/project-default context—use the same skill’s [metadata-dependency](../agentia-metadata/references/metadata-dependency.md) reference (`cicd metadata dependency list` / MCP `agentia_metadata_dependency_list`).
+
 ## General Rules
 
-- When the user means the **current story**, **current user story**, **active story**, **story context**, or similar without giving an ID, resolve context first with `agentia cicd work get --json` (no positional story ID). Use the returned user story (`result`) for follow-up work—any fields the task needs (for example `id`, `name`, `title`, `status`, specs, pipeline or environment IDs), not only identifiers. If the command fails (for example no active work item from `work set`), report the CLI error to the user and stop; do not guess, list stories, or pick a substitute unless the user asks you to.
+- When the user means the **current story**, **current user story**, **active story**, **story context**, or similar without giving an ID, resolve context first with `agentia cicd work get --json` (no positional story ID). Use the returned user story (`result`) for follow-up work—any fields the task needs (for example `id`, `name`, `title`, `status`, specs, pipeline or environment IDs, subscriber `customFields`), not only identifiers. If the command fails (for example no active work item from `work set`), report the CLI error to the user and stop; do not guess, list stories, or pick a substitute unless the user asks you to.
+- User Story subscriber custom fields: read `result.customFields` from `work get` / MCP `agentia_work_get`. Write with CLI `--custom-field ApiName=value` (repeatable) or MCP `customFields: [{ apiName, value }]` on create/update. See [references/work.md](references/work.md#subscriber-custom-fields).
 - Use Salesforce record IDs or generated names read from Copado. Do not invent story names, promotion IDs, job IDs, credential IDs, or pipeline IDs.
 - Keep human output off stdout in JSON workflows. Prefer `--json`, then parse the result object.
 - For local project work, keep the tracked working tree clean before commands that require it: `work set`, `work publish`, and `work submit`. If `work set` returns `status: "warning"`, show the message and do not assume a feature branch was created; branch keys are cleared and the work item id/name/title are still recorded in config.user.json.
@@ -41,7 +44,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - Treat `cicd function` as Copado Function definitions and runs. It is different from JobExecution (`cicd job`) and Job Templates (`cicd template`).
 - Treat `cicd extension` as experimental git-hosted packaging of Functions/Templates (plus optional `force-app`). It is different from per-asset `cicd function` / `cicd template` upserts.
 - Treat `cicd template` as Copado Job Templates via `/release/jobs/templates`. It is different from Release Data Templates (`cicd data template`).
-- Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing test run`.
+- Treat `cicd work test` as local quality gates (`--local` is the default). It is different from CRT `testing job run`.
 - Treat `cicd work test apex` as the Apex test runner that local quality gates (`.agentia_quality_gates.*`) usually call. An empty `--apex-test-classes` list skips Salesforce CLI. It can also be invoked directly. It is different from CRT.
 - Treat `auth` credentials as keychain/API credentials and `cicd credential` records as Copado environment credentials.
 

package/templates/skills/agentia-cicd/references/environments-and-credentials.md

@@ -4,7 +4,23 @@
 
 Use this reference for `agentia cicd environment ...`, `agentia cicd environment auth ...`, and `agentia cicd credential ...`.
 
-`auth set --cicd` stores the API key used by the CLI. `cicd credential` lists, creates, or updates Copado environment credential records. They are different credential types.
+`auth set --cicd` stores the API key used by the CLI. `cicd credential` lists, creates, updates, opens, or authenticates Copado environment credential records. They are different credential types.
+
+## Named CICD Connections
+
+Use a named connection when story lifecycle should stay on the default/production Copado org while function, template, or extension work targets a sandbox.
+
+```sh
+agentia auth set --cicd "$SANDBOX_KEY" --custom-url https://test.api.copado.com --connection sandbox --kind sandbox
+agentia cicd function upsert MyFn --file ./fn.json --cicd-connection sandbox
+agentia auth get --cicd --json
+agentia auth unset --connection sandbox --yes
+```
+
+- `--cicd-connection <name>` is available only on `agentia cicd ...` commands (and MCP `cicdConnection` on CICD tools). It does not appear on `ai`, `adv`, `testing`, or `auth`.
+- `AGENTIA_CICD_CONNECTION=<name>` sets a session default for `cicd` commands without changing keychain storage.
+- Do not combine a named connection with `AGENTIA_CICD_API_KEY` / `AGENTIA_CICD_BASE_URL`; the CLI errors instead of silently picking one.
+- Connections tagged `--kind production` require confirmation (CLI TTY), `--yes`, or `AGENTIA_CICD_ALLOW_PRODUCTION=true` (required for MCP).
 
 ## Environment Commands
 
@@ -14,9 +30,9 @@ Use this reference for `agentia cicd environment ...`, `agentia cicd environment
 | `environment get ID` | Inspect one environment | Read before updates, credential changes, or auth checks. |
 | `environment create NAME` | Create an environment | Set `--type`; platform defaults to SFDX. |
 | `environment update ID` | Sparse environment changes | Use only the fields the user wants changed. |
-| `environment open [ID]` | Open environment or credential | `--credentialid` opens a credential. CLI-only navigation helper. |
-| `environment auth status ID` | Validate org credential auth | Use `--credentialid` when multiple credentials need disambiguation. |
-| `environment auth web login ID` | Complete browser OAuth login | CLI-only, interactive browser flow. Supports bounded port and timeout flags. |
+| `environment open [ID]` | Open an environment | Uses the project default environment when ID is omitted. CLI-only navigation helper. |
+| `environment auth status ID` | Validate auth for an environment credential | Auto-selects when possible; use `--credentialid` to disambiguate. |
+| `environment auth web login ID` | Complete browser OAuth for an environment credential | CLI-only interactive browser flow. Supports bounded port and timeout flags. |
 
 Examples:
 
@@ -26,33 +42,39 @@ agentia cicd environment get <environment-id> --json
 agentia cicd environment auth status <environment-id> --credentialid <credential-id> --json
 ```
 
-## Environment Credential Commands
+## Credential Commands
 
 | Command | Use For | Notes |
 | --- | --- | --- |
-| `credential list` | Find credentials in one environment | Requires `--environmentid`; returns the environment's embedded credentials. OAuth signatures are never returned. |
+| `credential list` | Find credentials across environments | Optional `--name`, `--page-size`, and `--cursor`. OAuth signatures are never returned. |
 | `credential create` | Create a Copado environment credential | Requires `--environmentid` and `--name`; `--default` marks it default. |
-| `credential update ID` | Update a Copado environment credential | Requires `--environmentid`; use `--default` or `--no-default`. |
+| `credential update ID` | Update a Copado credential by ID | No environment flag; resolves environment/orgType from the credential. |
+| `credential open ID` | Open a credential in the browser | CLI-only navigation helper. |
+| `credential auth status ID` | Validate a specific credential | Derives the environment from GET `/corpus/credentials/{id}`. |
+| `credential auth web login ID` | Browser OAuth for a specific credential | CLI-only; derives the environment from the credential. |
 
 Examples:
 
 ```sh
-agentia cicd credential list --environmentid <environment-id> --json
+agentia cicd credential list --name CI --json
 agentia cicd credential create --environmentid <environment-id> --name "CI User" --default --json
-agentia cicd credential update <credential-id> --environmentid <environment-id> --no-default --json
+agentia cicd credential update <credential-id> --no-default --json
+agentia cicd credential open <credential-id>
+agentia cicd credential auth status <credential-id> --json
+agentia cicd credential auth web login <credential-id>
 ```
 
 ## When To Use Which Credential
 
 - Use `agentia auth set --cicd` when the CLI cannot authenticate to the Copado CICD API.
-- Use `agentia cicd credential list` to inspect an environment's credential records before changing authentication or defaults.
+- Use `agentia cicd credential list` to discover credentials without first knowing an environment ID.
 - Use `agentia cicd credential create/update` when a Copado environment needs a Salesforce org credential record.
-- Use `agentia cicd environment auth web login` when a credential exists but needs browser-based OAuth authentication.
+- Use `agentia cicd credential auth web login` when you already know the credential ID; use `agentia cicd environment auth web login` when you want automatic/default selection within an environment.
 - Use `agentia auth get --cicd --json` to inspect local CLI auth status without exposing the raw API key.
 
 ## Gotchas
 
 - Custom Domain environments are not supported by the credential create/update helpers.
-- The credential helper reads the environment first and copies its org type into the credential payload.
+- Create still reads the environment first and copies its org type into the credential payload; update and credential-targeted auth derive environment/orgType from the global credential record.
 - Environment authentication can auto-select only when there is a single obvious credential. Pass `--credentialid` if multiple credentials exist.
-- Browser login is intentionally CLI-only; there is no equivalent MCP flow.
+- Browser login and open are intentionally CLI-only; MCP exposes `agentia_credential_auth_status` for non-interactive validation.

package/templates/skills/agentia-cicd/references/extensions.md

@@ -1,3 +1,6 @@
+
+<!-- Agentia managed skill file: agentia setup skills -->
+
 # Copado CICD Extensions
 
 Use this reference for experimental git-hosted extension commands under `agentia cicd extension ...`.

package/templates/skills/agentia-cicd/references/pipelines.md

@@ -2,9 +2,9 @@
 
 # CICD Pipelines Reference
 
-Use this reference for `agentia cicd pipeline ...`, `agentia cicd pipeline connection ...`, `agentia cicd pipeline stage-connection ...`, and `agentia cicd stage ...`.
+Use this reference for `agentia cicd pipeline ...`, `agentia cicd pipeline automation ...`, `agentia cicd pipeline quality-gate ...`, `agentia cicd pipeline connection ...`, `agentia cicd pipeline stage-connection ...`, `agentia cicd stage ...`, and `agentia cicd extension-configuration ...`.
 
-Pipeline connections, stage connections, and stages are related but distinct. Read the target object before mutating it.
+Pipeline connections, stage connections, stages, automation rules, quality gates, and extension configurations are related but distinct. Read the target object before mutating it. These pipeline quality gates are not local `cicd work test` quality gates.
 
 ## Pipeline Commands
 
@@ -23,6 +23,38 @@ agentia cicd pipeline list --platform SFDX --active --json
 agentia cicd pipeline get <pipeline-id> --json
 ```
 
+## Automation Rules
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `pipeline automation list --pipeline-id <id>` | List automation rules | Filters: `--active`, `--name`, `--source-action`, `--execution-time`, `--include-system-generated`. |
+| `pipeline automation get ID --pipeline-id <id>` | Inspect one rule | Accepts Id or name. |
+| `pipeline automation create --pipeline-id <id> ...` | Create an inactive rule | Scopes: `promotion`, `backPromotion`, `environmentSyncBackPromotion`, `advanced`. Requires stage/environment targets; Scheduled needs `--cron-expression`. Optional `--filter-criteria` is a user-story filter: builder `{mode,logic,conditions[]}` or custom `{mode:"custom",whereCondition}`. |
+| `pipeline automation update ID --pipeline-id <id> ...` | Sparse update | Scope is immutable after create. |
+| `pipeline automation activate\|deactivate ID --pipeline-id <id>` | Lifecycle | Salesforce Id only (not name). Requires Copado Deployer ≥ 27.46. |
+| `pipeline automation delete ID --pipeline-id <id> --yes` | Delete | Confirmation required for headless/JSON. |
+| `pipeline automation open ID` | Open in browser | Salesforce Id only. |
+
+## Quality Gates
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `pipeline quality-gate list --pipeline-id <id>` | List quality gates | Filters: `--name`, `--tool`. |
+| `pipeline quality-gate get ID --pipeline-id <id>` | Inspect one gate | Aggregate may include multiple conditions. |
+| `pipeline quality-gate create --pipeline-id <id> ...` | Create inactive gates | Requires an active `--extension-configuration-id` and targeting (`--entire-pipeline` or stage/environment Ids). Optional `--filter-criteria` is a metadata-change filter (`Name`/`Type`/`Directory` conditions + numbered `logic`). Create may return an array. |
+| `pipeline quality-gate update ID --pipeline-id <id> ...` | Sparse update | Gate must be inactive; update uses singular `--stage-id` / `--environment-id`. |
+| `pipeline quality-gate activate\|deactivate ID --pipeline-id <id>` | Lifecycle | Salesforce Id only. |
+| `pipeline quality-gate delete ID --pipeline-id <id> --yes` | Delete inactive gate | Confirmation required for headless/JSON. |
+| `pipeline quality-gate open ID` | Open in browser | Salesforce Id only. |
+
+## Extension Configurations
+
+| Command | Use For | Notes |
+| --- | --- | --- |
+| `extension-configuration list` | Discover configs | Filters: `--name`, `--tool`, `--test-type`, `--active`. |
+| `extension-configuration get ID` | Inspect one config | Accepts Id or name. |
+| `extension-configuration open ID` | Open in browser | Salesforce Id only. Create/update/activate are not exposed (gateway lifecycle currently unavailable). |
+
 ## Environment Connections
 
 Pipeline connections define source-to-destination environment promotion edges.
@@ -59,5 +91,7 @@ Stages are reusable stage records. Stage connections order those stages inside a
 - `pipeline connection` is an environment promotion edge.
 - `pipeline stage-connection` is the ordered stage chain inside a pipeline.
 - `cicd stage` manages stage records that can be referenced by stage connections.
+- Pipeline `quality-gate` commands manage Copado pipeline quality gates. Local script gates remain under `cicd work test`.
+- Activate/deactivate and open require Salesforce Ids, not names.
 - Delete commands prompt in interactive mode. Use `--yes` only when the user already confirmed the destructive action.
 - Repository setup is a neighboring domain: pipelines can reference `--git-repository-id`, but repository lifecycle commands are under `agentia cicd repository`.

package/templates/skills/agentia-cicd/references/promotions.md

@@ -2,7 +2,7 @@
 
 # CICD Promotions Reference
 
-Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion conflict ...`, and `agentia cicd cloud promote`.
+Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion conflict ...`, `agentia cicd promotion queue ...`, and `agentia cicd cloud promote`.
 
 ## Entry Points
 
@@ -50,6 +50,15 @@ Use `--resume <job-execution-id>` to resume the original execution after conflic
 
 Read conflict content before manual resolution. Do not invent resolved content; use the user's reviewed file or ask for confirmation.
 
+## Queue Commands
+
+| Command | Use For |
+| --- | --- |
+| `promotion queue list <promotion-id>` | Show the job queue holding the promotion's destination (status, step, owner, whether the user can manage the queue). |
+| `promotion queue remove <promotion-id> --item <queue-item-id> --yes` | Remove queued items; needs the Manage Queue permission. Repeat `--item` for several. |
+
+List first and take item IDs from the output. Removal is destructive: confirm the item with the user. A conflict error means the queue changed since the read; list again. MCP: `agentia_promotion_queue_list`, `agentia_promotion_queue_remove` (`itemIds`).
+
 ## Gotchas
 
 - Promotion IDs are not User Story IDs. Use `cloud promote` if you only have the story.

package/templates/skills/agentia-cicd/references/work.md

@@ -21,7 +21,7 @@ agentia cicd work get --json
 
 Omit the positional story ID only; keep `--json` so agents parse the `result` object. With MCP, call `agentia_work_get` without an `id` when available.
 
-**On success:** treat the JSON `result` user story as the story context for the rest of the task. Reuse any returned fields later commands or flags need (identifiers, names, status, acceptance criteria, functional or technical specs, pipeline or environment references, and similar)—not only `id` and `name`.
+**On success:** treat the JSON `result` user story as the story context for the rest of the task. Reuse any returned fields later commands or flags need (identifiers, names, status, acceptance criteria, functional or technical specs, pipeline or environment references, subscriber `customFields`, and similar)—not only `id` and `name`.
 
 **On failure:** the CLI exits when no active work item is recorded (typical message: no active work item; suggestion to run `agentia cicd work set <id>`). Tell the user that no current story is set, include the sanitized error text, and stop. Do not invent an ID, run `work list` to pick one, or continue the original request until the user sets context or provides an explicit story ID.
 
@@ -61,9 +61,9 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 | Command            | Use For                                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | ------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `work list`        | Find candidate stories                         | Use `--assigned-to-me`, `--status`, `--project-name`, `--name`, pagination flags.                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `work get [ID]`    | Read story details                             | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields. `--committed-metadata` also includes the Story committed metadata list as `committedMetadata` in the result.                                                                                                                                                                                                                                                                                |
-| `work create`      | Create a story                                 | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment.                                                                                                                                                                                                                                                                                                              |
-| `work update [ID]` | Mutate story fields or status                  | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. `--source-credential` sends `sourceEnvironment` as null.                                                                                                                                                                                                                                                                                                                                                          |
+| `work get [ID]`    | Read story details                             | ID is optional after `work set`. Human output redacts OAuth signatures; JSON preserves structured fields including subscriber `customFields` (`apiName`, `label`, `type`, `value`, `displayValue`, `updateable`, optional `options`). `--committed-metadata` also includes the Story committed metadata list as `committedMetadata` in the result.                                                                                                                                                |
+| `work create`      | Create a story                                 | Use `--title`, project/team/assignee/theme fields, specs, and short acceptance criteria. Write subscriber fields with repeatable `--custom-field ApiName=value` (MCP: `customFields: [{ apiName, value }]`). `--source-credential` sends `sourceEnvironment` as null so Salesforce assigns the environment.                                                                                                                                                                                          |
+| `work update [ID]` | Mutate story fields or status                  | ID is optional after `work set`. Acceptance criteria must be fewer than 255 chars. Same `--custom-field` / MCP `customFields` write shape as create; update-only custom fields is allowed. `--source-credential` sends `sourceEnvironment` as null.                                                                                                                                                                                                                                                  |
 | `work set ID`      | Mark active and prepare branch                 | Fetches the base branch and, when present, the remote feature branch; creates/checks out `feature/<story-name>` from `origin/feature` when that ref exists, otherwise from the base; stores local context. A gateway warning prints the message, skips git, clears branch keys, and records work-item id/name/title. Warns without PATCHing when the Story credential differs from the project default; use `work update --source-credential` to change it. `--none` clears every `last*` key and checks out `lastBaseBranch`, else `main`, else `master`. |
 | `cloud commit`     | Copado cloud metadata commit                   | Prefer `agentia cicd cloud commit`. Requires `--metadata-category` (or `c`/`category` per `--file` change); use `SFDX` for Salesforce metadata. For local Git work, use `git commit` then `work publish`. `cicd work commit` remains a hidden compatibility alias.                                                                                                                                                                                                                                  |
 | `work publish`     | Publish local commits and register with Copado | Requires active story context and clean tree. Accepts `--permissions` and `--full-metadata` when nested detection is not enough. `work push` is a compatibility alias.                                                                                                                                                                                                                                                                                                                               |
@@ -72,7 +72,7 @@ Cloud commit checks Story readiness and source credentials before submission. Av
 | `work submit`      | Submit for review/validation or promote        | Runs local gates unless `--skip-local-tests`; can push ahead commits. Waits up to 5 minutes when the last pending related job template contains `Commit`. `--skip-pull-request` skips opening the MR URL. `--done` and `--deploy` match Copado UI Submit when promoting.                                                                                                                                                                                                                             |
 | `work done`        | Compatibility alias                            | Prefer `work submit --done`; both promote and deploy rather than validate-only.                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `work promote`     | Experimental local promotion                   | Skips Quality Gates. Requires `enableLocalPromote: true` in `.agentia/config.json`. Merges `feature/<name>` into `promotion/<promotionName>`. Use `--backpromote --destination-branch` for back promotions; `--continue` after conflict resolution.                                                                                                                                                                                                                                                  |
-| `work environment-sync` | Sync next-env commits onto dest/dev       | Back-promotes every story behind the destination environment. Use `--destination-environment` or `--dev-org-branch`; `--continue --promotion` after pathspec conflicts.                                                                                                                                                                                                                                                                                                                             |
+| `work environment-sync` | Sync next-env commits onto dest/dev       | Back-promotes every story behind the destination environment. Use `--destination-environment` or `--dev-org-branch`. On conflict, stores `lastEnvironmentSyncName` so `--continue` / `--abort` can omit `--promotion` (cleared on success, abort, and `work set`).                                                                                                                                                                                                                                  |
 | `cloud promote`    | Story-centric cloud promotion run              | Use `--deploy` for merge and deploy. Prefer this over local `work promote` unless you explicitly enabled local promote.                                                                                                                                                                                                                                                                                                                                                                              |
 | `work status [ID]` | Check story and related executions             | Useful after submit, promote, or commit jobs.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `work open [ID]`   | Open story in browser                          | CLI-only browser helper.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
@@ -118,6 +118,21 @@ agentia cicd cloud promote <story-id> --deploy --json
 
 Cloud commit and promotion wait for Job Executions by default and return nonzero on failed or timed-out jobs while preserving diagnostic IDs. If a Promotion reaches Merge Conflict, resolve it and resume the original execution; do not start a replacement run.
 
+## Subscriber Custom Fields
+
+Org-defined User Story fields (API names ending in `__c`, excluding packaged `copado__*`) are exposed as `customFields` on `work get` / create / update responses.
+
+- **Read:** prefer `agentia cicd work get [id] --json` (or MCP `agentia_work_get`) and use `result.customFields`. Prefer `displayValue` when presenting values; use `apiName` when writing. Human output lists them under `Custom Fields:` after `Components:`.
+- **Write (CLI):** repeatable `--custom-field ApiName=value` (string values; first `=` splits key/value). Duplicate `apiName` values are rejected.
+- **Write (MCP):** `customFields: [{ "apiName": "JIRA_Key__c", "value": "CICD-1" }]` on `agentia_work_create` / `agentia_work_update` (values may be string, number, boolean, or null).
+- Omit custom-field flags/args for packaged-only mutations. Unknown or non-updateable names fail with gateway `PLA-US-009`.
+
+```sh
+agentia cicd work create --title "Story" --custom-field JIRA_Key__c=CICD-1 --json
+agentia cicd work update --custom-field Priority_Pick__c=P1 --json
+agentia cicd work get --json
+```
+
 ## Deployment Steps
 
 Deployment steps are attached to a user story and run during promotion.