@copado/agentia-cli 1.2.0 → 1.4.0

package/package.json

@@ -69,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": [
@@ -97,6 +98,9 @@
       "auth": {
         "description": "Manage authentication credentials"
       },
+      "history": {
+        "description": "Inspect temporary local command history"
+      },
       "adv": {
         "description": "Manage Copado Pipelines Advanced deployments"
       },
@@ -217,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"
       },
@@ -247,8 +254,8 @@
       "testing:job:schedule": {
         "description": "Manage the schedule for a Copado Robotic Testing job"
       },
-      "testing:live": {
-        "description": "Manage Copado Robotic Testing live sessions"
+      "testing:browser": {
+        "description": "Manage Copado Robotic Testing browser sessions"
       },
       "testing:project": {
         "description": "Manage Copado Robotic Testing projects"
@@ -268,7 +275,7 @@
     }
   },
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.4.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,9 +11,11 @@ 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.
+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.
@@ -28,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
 
@@ -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

@@ -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.
@@ -21,7 +21,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 ## References
 
 - User stories, git commits, cloud commits, publish, submit, done, quality gates, and deployment steps: [references/work.md](references/work.md)
-- Promotion lookup, run, resume, merge conflicts, and story-centric promotion: [references/promotions.md](references/promotions.md)
+- Promotion lookup, status (blockers/Manual Task/queue), run, resume, merge conflicts, and story-centric promotion: [references/promotions.md](references/promotions.md)
 - Copado JobExecution lookup, actions, logs, and monitoring: [references/jobs.md](references/jobs.md)
 - Copado Functions lifecycle, remote run/results, and local Docker run: [references/functions.md](references/functions.md)
 - Git-hosted Copado CICD extensions (`cicd extension`, experimental): [references/extensions.md](references/extensions.md)
@@ -31,7 +31,7 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - 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 **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
 
@@ -39,13 +39,14 @@ For **Org Intelligence** (read Salesforce metadata against a sandbox/developer o
 - 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.
+- Cursor-paginated CICD lists (`--cursor` / MCP `cursor`) self-heal on gateway category `SF-014` (expired or invalid cursor): Agentia retries once without the cursor and returns page 1 with a `warnings` entry (also mirrored at the top level of CLI `--json`). Treat that as a reset to the first page, not a hard failure; do not keep replaying the same cursor.
 - 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.
 - Treat `cicd job` as Copado CICD JobExecution. It is different from CRT `testing job`.
 - 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 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 `cicd work test` as local quality gates (`--local` is the default). Use `--gate <id>` / `--list-gates` to run or discover individual gates (apex, lint, lwc, custom). It is different from CRT `testing job run`.
+- Treat `cicd work test --gate apex` as the Apex test runner; the sample local quality gates (`.agentia_quality_gates.*`) call it for their apex gate. Run directly it uploads the result to the work item; inside a script (`AGENTIA_QUALITY_GATES_ACTIVE=1`) it does not, because the outer run reports once. An empty `--apex-test-classes` list skips Salesforce CLI. `cicd work test apex` is the legacy hidden alias. It is different from CRT.
 - Treat `auth` credentials as keychain/API credentials and `cicd credential` records as Copado environment credentials.
 
 ## Report Back

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

@@ -6,6 +6,22 @@ Use this reference for `agentia cicd environment ...`, `agentia cicd environment
 
 `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
 
 | Command | Use For | Notes |

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

@@ -13,8 +13,8 @@ Use this reference for Copado CICD JobExecution commands under `agentia cicd job
 | `job list` | Search job executions | Filter by `--status`, `--type`, `--parent`, `--context`, `--mine`, cursor, and page size. |
 | `job get ID` | Inspect a job and ordered steps | Read before action commands or log lookup. |
 | `job log get ID` | Read execution logs | Use `--step <step-id>` when a specific step is needed. |
-| `job result-file list RESULT_ID` | Discover files linked to a job-step Result | Returns file metadata; use its `fileId` with `get`. |
-| `job result-file get RESULT_ID --file-id CONTENT_VERSION_ID` | Retrieve one Result-linked Salesforce File | Use `--output-file <path>` to write validated decoded bytes; JSON and MCP return Base64 content. |
+| `job result-file list RESULT_ID` | Discover files linked to a job-step Result | Human table includes FILE ID (`fileId`, 068); JSON returns `fileId` and `contentDocumentId`. |
+| `job result-file get RESULT_ID --file-id FILE_ID` | Retrieve one Result-linked file | Pass `fileId` from list (068). A ContentDocument id (069) is resolved via list before download. |
 | `job run ID` | Run all steps | Use `--restart` only when the user asks to restart from the beginning. |
 | `job resume ID` | Resume outstanding steps | Good after a paused or partially completed job. |
 | `job pause ID` | Pause/cancel resumably | Confirm intent before interrupting active work. |
@@ -45,5 +45,6 @@ agentia cicd job resume <job-execution-id> --json
 - Some job tools require user and organization context at the gateway layer. If the CLI reports missing context, inspect auth and user context before retrying.
 - Logs can be large. Prefer a specific step when available.
 - Result-file commands require the job-step Result ID, not the JobExecution ID. They accept only 15- or 18-character Salesforce IDs and never derive output paths from remote filenames.
+- Use `fileId` (068) from `result-file list` for downloads. The list table shows FILE ID; JSON also includes `contentDocumentId` (069), which must not be used directly in the download path. `result-file get` and MCP `agentia_job_result_file_get` resolve a 069 id when it matches a listed file.
 - `--output-file` can replace an existing file after Base64 validation. Use an explicitly controlled destination; malformed content leaves an existing target unchanged.
 - Do not use CICD job commands for Robot Framework builds; use the `agentia-testing` skill for CRT run status and logs.

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

@@ -2,14 +2,14 @@
 
 # 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
 
 | Command | Starts From | Use When |
 | --- | --- | --- |
 | `agentia cicd promotion run <promotion-id>` | Promotion ID | You already know the Promotion record and want explicit merge or merge-and-deploy control. |
-| `agentia cicd cloud promote [story-id]` | User Story | You want Agentia to resolve the story's Promotion before running it. |
+| `agentia cicd cloud promote [story-id]` | User Story | Resolve the story's Promotion before running; creates a forward Draft promotion and adds the story when none exists. |
 | `agentia cicd work submit --done` | Active User Story branch | The story is approved and should move to the next stage (Copado UI Submit promote). |
 
 Prefer `cloud promote` when the user talks about a story. Prefer `promotion run` when the user provides a Promotion ID.
@@ -19,15 +19,27 @@ Prefer `cloud promote` when the user talks about a story. Prefer `promotion run`
 | Command | Use For | Notes |
 | --- | --- | --- |
 | `promotion list` | Find promotions | Filter by `--work-id`, status, project, pipeline, source/destination environment, or back-promotion flags. |
-| `promotion get ID` | Inspect one promotion | Read this before running, resuming, or resolving conflicts. |
+| `promotion status ID` | Actionable run status | Prefer when the user asks "promotion status", what is running, or what is blocking. Includes user stories, current job step, queue, and Manual Task action-needed. MCP: `agentia_promotion_status`. |
+| `promotion get ID` | Inspect one promotion record | Read this before running, resuming, or resolving conflicts. Does not load job steps; use `promotion status` for blockers. |
 | `promotion run ID` | Preflight and submit a run | Requires `--operation merge` or `--operation merge_and_deploy` unless `--resume` is used. |
 | `promotion open ID` | Open in browser | CLI-only navigation helper. |
-| `cloud promote [ID]` | Story-centric run | Use `--deploy` for merge and deploy; use `--promotion-id` if the story has multiple promotions. |
+| `cloud promote [ID]` | Story-centric run | Use `--deploy` for merge and deploy; use `--promotion-id` if the story has multiple promotions (explicit ID is used as is and never creates one). JSON/MCP return `createdPromotion` when auto-created. |
+
+## Status Reports
+
+When the user asks about a promotion's progress or blockers, call `agentia cicd promotion status <id> --json` (or MCP `agentia_promotion_status`) and report **all** of:
+
+1. Promotion name/id and status (and Salesforce status when present).
+2. User stories involved (name and id).
+3. Current job and current step (name, status, type).
+4. Whether `actionNeeded.kind` is `manual_task` or `queue` — quote `actionNeeded.message` and tell the user they must act; do not say only "In Progress".
+5. Queue summary when present; call `promotion queue list` if they need item-level detail.
 
 Example:
 
 ```sh
 agentia cicd promotion list --work-id <story-id> --json
+agentia cicd promotion status <promotion-id> --json
 agentia cicd promotion run <promotion-id> --operation merge_and_deploy --json
 agentia cicd cloud promote <story-id> --deploy --json
 ```
@@ -50,9 +62,18 @@ 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.
+- Promotion IDs are not User Story IDs. Use `cloud promote` if you only have the story; do not create the promotion manually first when none contains the story.
 - `--deploy` on `cloud promote` maps to promotion operation `merge_and_deploy`; without it, the default is merge only.
 - `--recreate-promotion-branch` is a sensitive run option and should be paired with explicit user intent and `--yes` when required.
 - If conflicts exist, resolve them first and then resume the same execution.

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

@@ -36,7 +36,7 @@ Use this path when the change exists in the local repository:
 1. Discover and inspect: `agentia cicd work list --assigned-to-me --json`, then `agentia cicd work get <id-or-name> --json`.
 2. Activate: `agentia cicd work set <id-or-name> --json`. This fetches the configured base branch, fetches the Story feature branch when it exists on origin, then checks out `feature/<story-name>` from that remote branch when present (otherwise from the base), and records the story, base branch, dev org branch, and pull-request context in `.agentia/config.user.json`. Use `--base-branch <branch>` only when intentionally overriding the Pipeline default. If the JSON result has `status: "warning"` (missing pipeline or credential), show that `message`, do not assume a feature branch was created, and note that branch keys (`lastBaseBranch`, `lastDevOrgBranch`, `lastPullRequestBaseUrl`) were cleared while `lastWorkItemId`/`lastWorkItem`/`lastWorkItemTitle` were recorded — stop until the Story setup is fixed; publish and submit will not work. If the Story source credential differs from the project default, work set warns with the current credential and environment and does not PATCH; use `agentia cicd work update <id> --source-credential <credential-id>` to change it.
 3. Implement with Salesforce CLI, VS Code, or an IDE. Stage and commit with `git add` / `git commit`. Do not use `agentia cicd cloud commit` for local Git work.
-4. Run project-owned gates: `agentia cicd work test --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. If those files are missing, it warns and runs `agentia cicd work test apex` via the stock sample from a temporary file. Local tests can be slow; pass `--apex-test-classes=MyTest,OtherTest` for faster, earlier Apex checks.
+4. Run project-owned gates: `agentia cicd work test --json`. This runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from the repository root when present. If those files are missing, it warns and runs the stock sample from a temporary file. Local tests can be slow; pass `--apex-test-classes=MyTest,OtherTest` for faster, earlier Apex checks.
 5. Register and synchronize: `agentia cicd work publish --json`. A plain `git push` does not register a Copado Commit or merge the feature branch into the recorded dev org branch. Pass `--permissions` and `--full-metadata` when nested detection is not enough.
 6. Validate and open the merge-request flow: `agentia cicd work submit --json`. Submit runs the local gates unless `--skip-local-tests` is explicit, pushes ahead commits, waits if the last pending related job is a Commit template, and submits with validate-only behavior. `--skip-pull-request` skips opening the compare URL.
 7. Only with explicit approval to promote and deploy, run `agentia cicd work submit --deploy --json` (or `--done`). `work done` is a compatibility alias.
@@ -51,7 +51,7 @@ Use this path when Copado should retrieve metadata from a configured source envi
 1. Inspect the Story and pass its Salesforce ID explicitly when possible. An active Story from `work set` is optional, not a prerequisite for the cloud operation.
 2. Start a cloud commit with `agentia cicd cloud commit <story-id> ... --json`. Use the simple metadata flags for one change, or `--file`/`--stdin` for a multi-change request. Always pass `--metadata-category` (use `SFDX` for Salesforce metadata). With `--file`/`--stdin`, each change requires `c` (or `category`).
 3. Let the command wait for its Job Execution by default. After a timeout, use the returned execution ID with `agentia cicd job get` and `agentia cicd job log get`; do not immediately submit a duplicate commit.
-4. When explicitly approved to promote an existing Promotion, use `agentia cicd cloud promote <story-id> --json`; add `--deploy` only for promote-and-deploy. This is independent of local `work submit`.
+4. When explicitly approved to promote, use `agentia cicd cloud promote <story-id> --json`; add `--deploy` only for promote-and-deploy. Creates a forward Draft promotion when none contains the story (`createdPromotion` in JSON/MCP). This is independent of local `work submit`.
 
 Cloud commit checks Story readiness and source credentials before submission. Avoid concurrent cloud commits to one Story. Treat `--recreate-feature-branch` as destructive because it can overwrite Story-branch work.
 
@@ -60,20 +60,20 @@ 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 list`        | Find candidate stories                         | Use `--assigned-to-me`, `--status`, `--project-name`, `--name`, pagination flags. An expired or invalid `--cursor` (`SF-014`) self-heals to page 1 with a `warnings` entry in human/`--json`/MCP.                                                                                                                                                                                                                                                                                                    |
 | `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.                                                                                                                                                                                                                                                                                                                               |
-| `work test`        | Run local quality gate scripts                 | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. If missing, warns and runs the stock setup sample from a temp file. `--cloud` is not implemented yet.                                                                                                                                                                                                                                                                                         |
-| `work test apex`   | Run named Apex test classes                    | Optional `--apex-test-classes`. Omit or pass empty to log a skip and exit 0 without calling Salesforce CLI. `--rerun-failed-apex-tests` reruns classes from `.agentia/apex.tests.<user-story>.json`. Optional `--wait` minutes (default 60). Usually invoked from `.agentia_quality_gates.*`. |
+| `work test`        | Run local quality gate scripts                 | `--local` is default. Runs `.agentia_quality_gates.sh` or `.agentia_quality_gates.cmd` from repo root. If missing, warns and runs the stock setup sample from a temp file. `--gate <id>` (repeatable) runs only selected gates, `--all` runs everything (default), `--list-gates` lists gates declared via `# agentia-gate: <id> - <description>` in the script. Standard ids: `apex`, `lint`, `lwc`; custom ids allowed. The selection is exported as `AGENTIA_GATES`. `--gate apex` alone skips the script and runs the Apex tests directly (`--apex-test-classes`, `--rerun-failed-apex-tests`, `--wait`). `--cloud` is not implemented yet.                                                                                                                                                                                                                                                                                         |
+| `work test apex`   | Legacy alias of `work test --gate apex`        | Optional `--apex-test-classes`. Omit or pass empty to log a skip and exit 0 without calling Salesforce CLI. `--rerun-failed-apex-tests` reruns classes from `.agentia/apex.tests.<user-story>.json`. Optional `--wait` minutes (default 60). Prefer `work test --gate apex`. |
 | `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`. 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 environment-sync` | Sync next-env commits onto dest/dev (experimental) | Experimental. Back-promotes every story behind the destination environment onto `promotion/<name>` (from dest org), then merges that branch into dest and pushes both. On a feature branch, unpublished commits stop the command (`work publish` first); after a successful sync, feature files changed vs base are refreshed from dest and you are told to re-check and publish again. On conflict, resolve on `promotion/<name>` (or dest) and `--continue` / `--abort` (`lastEnvironmentSyncName` can omit `--promotion`; cleared on success, abort, and `work set`). Success/abort call `promote-action/complete` with `--deployment` resolved to `none`\|`local`\|`cloud` (`auto` → `local` when every change is Add and `--sf-alias` is set, else `cloud`). Local deploy runs on the dest org branch (before feature refresh) via `sf project deploy start --ignore-conflicts` (Add-only); failures include full `package.xml` and raw `sf` stdout/stderr (human and `--json`). After success with cloud deployment, waits for the JobExecution by default (`--no-wait` / `--wait-timeout`). |
+| `cloud promote`    | Story-centric cloud promotion run              | Auto-creates a forward Draft promotion when none contains the story. 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.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
@@ -94,7 +94,7 @@ agentia cicd work submit --json
 
 `--permissions` on publish names metadata that Copado should treat as Retrieve Only. List the components whose access changed, not the permission set or profile files; naming those parent types is rejected. Use `--full-metadata` only for `Profile`, `PermissionSet`, `MutingPermissionSet`, `CustomObject`, or `CustomObjectTranslation` when that complete file should travel; other types are rejected. Both flags apply to that publish only.
 
-`work test` and `work submit` take `--apex-test-classes` when you want the local gate script to receive them as `AGENTIA_APEX_TEST_CLASSES`. Sample quality-gate scripts pass that value to `work test apex`.
+`work test` and `work submit` take `--apex-test-classes` when you want the local gate script to receive them as `AGENTIA_APEX_TEST_CLASSES`. Sample quality-gate scripts pass that value to the apex gate (`work test --gate apex`). Run one gate with `work test --gate lint` (MCP `gates: ["lint"]`); `work submit` always runs every gate. The sample lint gate scans only branch-changed files (diff vs `AGENTIA_BASE_BRANCH` merge-base, plus uncommitted/untracked); set `LINT_SCOPE=all` for a full scan, which is also the fallback outside git.
 
 `work publish` detects nested metadata across the full branch diff from the merge base to `HEAD`, applies Copado environment-variable and YAML replacements, registers every commit in the range, and merges into the recorded dev org branch. Review unexpected Retrieve Only, Full Metadata, or nested-deletion output before continuing.
 
@@ -107,15 +107,29 @@ agentia cicd cloud commit <story-id> --message "Commit AccountService" --metadat
 agentia cicd cloud commit <story-id> --file commit-request.json --json
 ```
 
-`--metadata-category` is required on simple flag input. Each `--file`/`--stdin` change requires `c` (or `category`). For Salesforce metadata, use `SFDX`. Without `c:SFDX`, Copado deploy logs can report "Salesforce changes not found."
+Example `commit-request.json` for multiple components:
 
-For a cloud promotion, the Story must already belong to a Promotion:
+```json
+{
+  "message": "Account service and trigger",
+  "changes": [
+    {"a": "Add", "c": "SFDX", "n": "AccountService", "t": "ApexClass"},
+    {"a": "Add", "c": "SFDX", "n": "AccountTrigger", "t": "ApexTrigger"}
+  ]
+}
+```
+
+`--metadata-category` is required on simple flag input (one component only). Each `--file`/`--stdin` change requires `c` (or `category`). For Salesforce metadata, use `SFDX`. Without `c:SFDX`, Copado deploy logs can report "Salesforce changes not found."
+
+For cloud promotion from a User Story:
 
 ```sh
 agentia cicd cloud promote <story-id> --json
 agentia cicd cloud promote <story-id> --deploy --json
 ```
 
+When no Promotion contains the story, `cloud promote` and MCP `agentia_cloud_promote` create one automatically before running.
+
 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
@@ -154,7 +168,7 @@ Prefer explicit flags for standard step types. Use `--config-json`, `--file`, or
 ## Gotchas
 
 - `work test` is not CRT. For Robot Framework execution, use the `agentia-testing` skill.
-- `work test apex` runs named Apex classes. Local quality gates (`.agentia_quality_gates.*`) usually call it with `-t "${AGENTIA_APEX_TEST_CLASSES}"` and `${AGENTIA_APEX_RERUN_FAILED}` (empty or `--rerun-failed-apex-tests`); an empty class list skips Apex without failing the script. `--rerun-failed-apex-tests` reruns classes saved in `.agentia/apex.tests.<user-story>.json` after a failure. Direct use is for a targeted rerun without the rest of the gates.
+- `work test --gate apex` runs named Apex classes directly (the legacy `work test apex` is an alias). Sample local quality gates (`.agentia_quality_gates.*`) call it with `--apex-test-classes="${AGENTIA_APEX_TEST_CLASSES}"` and `${AGENTIA_APEX_RERUN_FAILED}` (empty or `--rerun-failed-apex-tests`); an empty class list skips Apex without failing the script. `--rerun-failed-apex-tests` reruns classes saved in `.agentia/apex.tests.<user-story>.json` after a failure. Run it directly for a targeted rerun without the rest of the gates.
 - Local Git work uses `git commit` then `work publish`. Cloud `cloud commit` is a separate path.
 - `work submit` may push ahead commits, but the local flow still needs story and branch context from `work set`.
 - `work submit --done` (or `--deploy`) promotes/deploys. Do not run it unless the user explicitly asked to promote or finish the story.

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

@@ -1,6 +1,6 @@
 ---
 name: agentia-metadata
-description: Org Intelligence — read Salesforce metadata in a sandbox or developer org through Agentia `cicd metadata explore` (and MCP `agentia_metadata_explore`). Use when listing or searching metadata names, reading items by API name, finding where a class/field/etc is referenced, describing types, reading type documentation, or running specified Apex tests. Prefer local project files first, then the org. Reads metadata only (not org data); does not edit or deploy metadata.
+description: Org Intelligence — read Salesforce metadata in a sandbox or developer org through Agentia `cicd metadata explore` (and MCP `agentia_metadata_explore`). Use when listing or searching metadata names, reading items by API name, finding where a class/field/etc is referenced, describing types, reading type documentation, or running specified Apex tests. Also covers Copado `cicd metadata dependency list` (MCP `agentia_metadata_dependency_list`), including `--path` for local DX files. Prefer local project files first, then the org. Reads metadata only (not org data); does not edit or deploy metadata.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -45,14 +45,17 @@ local when reconciling differences unless the user asks for the org version.
 | List metadata names that match a pattern | `list` |
 | Search source (Apex Page/Class/Trigger/Component only) | `search` |
 | Retrieve one item by API name | `read` |
-| Find where a class/field/etc is used or called | `find_references` |
+| Find where a class/field/etc is used or called (org) | `find_references` |
+| Copado dependency graph (pipeline/org; local DX `--path`) | `cicd metadata dependency list` |
 | Describe a metadata type shape | `describe_type` |
 | Get type documentation from the tool | `read_documentation` |
 | Run specific Apex test classes | `run_apex_tests` |
 
 Use `list` / `search` to discover exact names before `read` or
 `find_references`. Pass type + name for references. Confirm with the user
-before `run_apex_tests`.
+before `run_apex_tests`. For Copado uses/dependants from a local DX file,
+prefer `cicd metadata dependency list --path` (see dependency reference)—do
+not invent type/name when a path is available.
 
 ## Org And Scope
 
@@ -133,6 +136,9 @@ When helping the user design or draft Salesforce metadata (local edits only):
 Flags, MCP args, examples, and gotchas:
 [references/metadata-explore.md](references/metadata-explore.md)
 
+Copado dependency graph (`--path`, context defaults, human table):
+[references/metadata-dependency.md](references/metadata-dependency.md)
+
 ## Report Back
 
 Report actions run, object type / fullName / pattern, credential Id (never

package/templates/skills/agentia-metadata/references/metadata-dependency.md

@@ -0,0 +1,70 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Copado Metadata Dependency List
+
+Use `agentia cicd metadata dependency list` (MCP `agentia_metadata_dependency_list`)
+for the **Copado CICD dependency graph** against pipeline/org context—not Org
+Intelligence `find_references` (org Metadata API references).
+
+Prefer this when the caller has local Salesforce DX source paths (for example
+IDEX) or already knows metadata type/name and needs uses / dependants from
+Copado.
+
+## Choose An Input Mode
+
+Use **only one**:
+
+| Mode | When |
+| --- | --- |
+| `--path` / MCP `path` | Local DX file path(s). Resolves type/name via existing SDR helpers. |
+| `--metadata-name` + `--metadata-type` | Explicit selection. |
+| `--from-changes` | Committed branch diff + staged index (not unstaged). |
+| `--file` / `--stdin` | Full JSON dependency request body. |
+
+Do not invent a second path mapper—`--path` reuses the same resolvers as
+`--from-changes`. Unresolvable paths fail with a clear error and do not call
+the gateway.
+
+```sh
+agentia cicd metadata dependency list \
+  --path force-app/main/default/classes/MyClass.cls \
+  --target-org-id <id> \
+  --retrieve-mode all \
+  --json
+```
+
+MCP accepts `path` as a string or string array. Mutually exclusive with
+`metadataName` / `metadataType`.
+
+## Context Defaults
+
+When omitted, these resolve from the **active work item**, then **project
+defaults**:
+
+- `--pipeline-id` / `pipelineId`
+- `--source-credential-id` / `sourceCredentialId`
+- `--source-org-id` / `sourceOrgId`
+- `--platform-experience` / `platformExperience` (from story `platform`, else
+  `sfdx`)
+
+`--target-org-id` / `targetOrgId` is **never** inferred—pass it when compare
+status is needed.
+
+Explicit flags always win.
+
+## Output
+
+- **`--json` / MCP:** gateway `DependencyResult` (including enriched
+  `localPaths` for `--path` / `--from-changes` when resolvable).
+- **Human table columns:** `PARENT` (evaluated metadata), `RELATION`
+  (`used by` from `u`, `dependant` from `d`), `NAME`, `TYPE`, and `STATUS`
+  from gateway `s`. The STATUS column is omitted when `s` is absent (typical
+  without a target org).
+
+## Vs Org Intelligence
+
+| Need | Command |
+| --- | --- |
+| Org Metadata API references | `cicd metadata explore --action find_references` |
+| Copado dependency graph (pipeline/org compare) | `cicd metadata dependency list` |
+| Local DX path → dependency graph | `cicd metadata dependency list --path …` |

package/templates/skills/agentia-metadata/references/metadata-explore.md

@@ -107,9 +107,13 @@ agentia cicd metadata explore --action read --object-type ApexClass --full-name
 
 ### `find_references`
 
-Partial reference/dependency lookup: metadata that uses or calls a given item.
-Requires `--object-type` and `--full-name` (type + name of the referenced
-component). Coverage may be incomplete—treat results as a starting point.
+Partial **org** reference lookup: metadata that uses or calls a given item via
+the Metadata API tool. Requires `--object-type` and `--full-name`. Coverage may
+be incomplete—treat results as a starting point.
+
+For the **Copado CICD dependency graph** (including local DX `--path`), use
+`cicd metadata dependency list` instead—see
+[metadata-dependency.md](metadata-dependency.md).
 
 ```sh
 agentia cicd metadata explore --action find_references --object-type ApexClass --full-name MyClass --json
@@ -139,4 +143,4 @@ agentia cicd metadata explore --action run_apex_tests --apex-unit-tests MyClassT
 | Copado metadata index search | `cicd metadata list` |
 | Indexed/Git content blobs | `cicd metadata content get` |
 | Org/Git content diff | `cicd metadata content compare` |
-| Copado dependency graph | `cicd metadata dependency list` |
+| Copado dependency graph (local DX `--path`, story/defaults context) | `cicd metadata dependency list` — [metadata-dependency.md](metadata-dependency.md) |

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

@@ -1,13 +1,13 @@
 ---
 name: agentia-testing
-description: Use this skill when creating, updating, running, inspecting, or troubleshooting Copado Robotic Testing with the Agentia CLI, including projects, permissions, robots, jobs, builds, schedules, data tables, variables, user parameters, live testing, Git-backed storage, and Robot Framework execution.
+description: Use this skill when creating, updating, running, inspecting, or troubleshooting Copado Robotic Testing with the Agentia CLI, including projects, permissions, robots, jobs, builds, schedules, data tables, variables, user parameters, browser testing, Git-backed storage, and Robot Framework execution.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
 
 # Agentia Testing
 
-Use this skill to operate Copado Robotic Testing through Agentia without confusing CRT resources, executions, live sessions, and Copado CICD records.
+Use this skill to operate Copado Robotic Testing through Agentia without confusing CRT resources, executions, browser sessions, and Copado CICD records.
 
 Prefer Agentia MCP tools when they are available and match the task. Use CLI examples as the fallback, and add `--json` whenever the result will be parsed or reused.
 
@@ -20,7 +20,11 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 
 ## Reference
 
-- CRT lifecycle, execution, schedules, data tables, live testing, and safety rules: [references/tests.md](references/tests.md)
+- CRT lifecycle, execution, schedules, data tables, browser testing, and safety rules: [references/tests.md](references/tests.md)
+- Browser session lifecycle, parallel recorder subagent workflow, 600s idle keepalive, and troubleshooting: [references/browser-testing.md](references/browser-testing.md)
+- Goal-driven browser-testing automation loop (Observe -> Act -> Verify -> Recover), screenshot detection overlays, and script export: [references/flow-automation.md](references/flow-automation.md)
+- QWeb Robot Framework keyword catalog, 4-space separator rule, locator priority, and decision tree: [references/qweb.md](references/qweb.md)
+- QForce & Salesforce Lightning automation (`--library QForce`, `LaunchApp`, `VerifyField`, `PickList`, `ComboBox`): [references/qforce.md](references/qforce.md)
 
 ## General Rules
 
@@ -30,8 +34,9 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 - Use Git-backed job flags only when the user or project clearly uses repository-backed CRT test storage.
 - In JSON or non-interactive CLI calls, destructive actions require `--yes`; matching MCP tools require `confirm: true`.
 - Prefer `--value-stdin` and `--git-password-stdin` over putting secrets in process arguments.
+- Always pass `--no-open` to `agentia testing browser view` by default (`agentia testing browser view --project <project-id> --no-open --json`) and share the returned URL; omit `--no-open` only when the user explicitly asks to open the browser.
 - Use the currently configured CRT credential context for validation. Test14 credentials belong to CICD and must not be substituted for CRT credentials.
 
 ## Report Back
 
-Report the CRT project, robot, job/test ID, build or live-session ID when present, final status, cleanup, and where outputs were written. Do not include PAKs or other secrets.
+Report the CRT project, robot, job/test ID, build or browser-session ID when present, final status, cleanup, and where outputs were written. Do not include PAKs or other secrets.