@copado/agentia-cli 1.3.0 → 1.5.0-rc.0

package/oclif.manifest.json

@@ -2447,11 +2447,11 @@
           "required": false
         }
       },
-      "description": "Create a Copado cloud metadata commit for a user story.\nPreflights the story, submits POST /release/commit, and polls the job monitor by default.\nFor local Git work, use git add/commit then `cicd work publish`. Permission and full-metadata selections belong on `cicd work publish`.\n\nNOTE: Do not use this command along with local development (git operations, cicd work push/submit).",
+      "description": "Create a Copado cloud metadata commit for a user story.\nPreflights the story, submits POST /release/commit, and polls the job monitor by default.\nSimple --metadata-* flags commit exactly one component. Use --file or --stdin with a changes[] array for multiple components.\nFor local Git work, use git add/commit then `cicd work publish`. Permission and full-metadata selections belong on `cicd work publish`.\n\nNOTE: Do not use this command along with local development (git operations, cicd work push/submit).",
       "examples": [
         "<%= config.bin %> <%= command.id %> --message \"Commit AccountService\" --metadata-name AccountService --metadata-type ApexClass --metadata-category SFDX --action Add",
         "<%= config.bin %> <%= command.id %> a07XXXXXXXXXXXXXXX --message \"Update Aura files\" --metadata-name accountEditor --metadata-type AuraDefinitionBundle --metadata-category SFDX --action SelectiveCommit --selection accountEditor/accountEditor.cmp --selection accountEditor/accountEditorController.js",
-        "<%= config.bin %> <%= command.id %> --file commit-request.json  # {\"message\":\"Commit AccountService\",\"changes\":[{\"a\":\"Add\",\"c\":\"SFDX\",\"n\":\"AccountService\",\"t\":\"ApexClass\"}]}",
+        "<%= config.bin %> <%= command.id %> --file commit-request.json  # {\"message\":\"Commit metadata\",\"changes\":[{\"a\":\"Add\",\"c\":\"SFDX\",\"n\":\"AccountService\",\"t\":\"ApexClass\"},{\"a\":\"Add\",\"c\":\"SFDX\",\"n\":\"AccountTrigger\",\"t\":\"ApexTrigger\"}]}",
         "cat commit-request.json | <%= config.bin %> <%= command.id %> --stdin --json"
       ],
       "flags": {
@@ -2513,7 +2513,7 @@
         },
         "file": {
           "char": "f",
-          "description": "Path to a JSON commit request body.",
+          "description": "Path to a JSON commit request with message and changes[] (one object per metadata component).",
           "name": "file",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -2576,7 +2576,7 @@
           "type": "option"
         },
         "stdin": {
-          "description": "Read a JSON commit request body from stdin.",
+          "description": "Read a JSON commit request with message and changes[] from stdin.",
           "name": "stdin",
           "allowNo": false,
           "type": "boolean"
@@ -2673,7 +2673,7 @@
           "type": "option"
         },
         "promotion-id": {
-          "description": "Explicit 18-character Promotion ID when the User Story belongs to multiple promotions.",
+          "description": "Explicit 18-character Promotion ID when the User Story belongs to multiple promotions. Used as is; never creates a promotion.",
           "name": "promotion-id",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -6777,6 +6777,55 @@
         "run.js"
       ]
     },
+    "cicd:promotion:status": {
+      "aliases": [],
+      "args": {
+        "id": {
+          "description": "Copado promotion ID",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Show actionable status for a Copado promotion: user stories, current job step, queue summary, and whether a Manual Task or queue item needs attention.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> <promotion-id>",
+        "<%= config.bin %> <%= command.id %> <promotion-id> --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "cicd-connection": {
+          "description": "Named CICD connection for this invocation only (see agentia auth set --connection). Does not change stored default auth.",
+          "name": "cicd-connection",
+          "required": false,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "cicd:promotion:status",
+      "pluginAlias": "@copado/agentia-cli",
+      "pluginName": "@copado/agentia-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "experimental": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "cicd",
+        "promotion",
+        "status.js"
+      ]
+    },
     "cicd:repository:create": {
       "aliases": [],
       "args": {
@@ -8262,7 +8311,7 @@
         },
         "file": {
           "char": "f",
-          "description": "Path to a JSON commit request body.",
+          "description": "Path to a JSON commit request with message and changes[] (one object per metadata component).",
           "name": "file",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -8325,7 +8374,7 @@
           "type": "option"
         },
         "stdin": {
-          "description": "Read a JSON commit request body from stdin.",
+          "description": "Read a JSON commit request with message and changes[] from stdin.",
           "name": "stdin",
           "allowNo": false,
           "type": "boolean"
@@ -8494,7 +8543,7 @@
           "type": "option"
         },
         "record-type": {
-          "description": "Record type",
+          "description": "Record type DeveloperName",
           "name": "record-type",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -8600,12 +8649,12 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "User story ID",
+          "description": "User story ID or name",
           "name": "id",
           "required": true
         }
       },
-      "description": "Delete a Copado user story by ID",
+      "description": "Delete a Copado user story by ID or name",
       "examples": [
         "<%= config.bin %> <%= command.id %> a0SKC000000CmZ2AU",
         "<%= config.bin %> <%= command.id %> a0SKC000000CmZ2AU --json"
@@ -8699,13 +8748,16 @@
     "cicd:work:environment-sync": {
       "aliases": [],
       "args": {},
-      "description": "Sync committed metadata from the next environment onto the destination environment (or current feature branch). Back-promotes every user story behind the destination environment from the next environment branch. GET user stories ahead and behind. If none are behind, log that and stop. Otherwise create a back-promotion and POST those behind stories onto the promotion. Resolves the next-environment Git branch from --destination-environment or --dev-org-branch (the dest pipeline connection destinationBranch, or that destination environment's outbound branch). Merges origin/<next-env> with --no-ff --no-commit, restores every other path from HEAD, commits the guessed pathspecs, and pushes the dest org branch (and the feature branch when HEAD starts with feature/). If guessed pathspecs still conflict, PATCH the back-promotion status to Merge Conflict, store lastEnvironmentSyncName, resolve the files, and re-run with --continue (optional --promotion). The promotion destination environment supplies the dest org branch and the next-env branch. To discard a conflicted merge, re-run with --abort (optional --promotion); runs git merge --abort and sets the back-promotion status to Draft. After a successful sync, PATCH the back-promotion status to Completed and clear lastEnvironmentSyncName. On git/merge failure (including conflicts) and after a successful --continue, uploads the captured command transcript as a Salesforce File on the back-promotion (`Environment Sync Logs <name-or-id> <datetime>.txt`) via `/agentia/headless/file/upload`. HTTP 404 is ignored until that endpoint is rolled out; other upload failures are warned and do not change the environment-sync outcome.",
+      "description": "Sync committed metadata from the next environment onto the destination environment (or current feature branch). Back-promotes every user story behind the destination environment from the next environment branch. On a feature branch, requires published commits first: stops when HEAD is ahead of origin/<feature> and suggests `cicd work publish`. GET user stories ahead and behind. If none are behind, log that and stop. Otherwise create a back-promotion via POST /agentia/headless/work/promote-action (PromoteAction with execute flags false) including those behind stories. Resolves the next-environment Git branch from --destination-environment or --dev-org-branch (the dest pipeline connection destinationBranch, or that destination environment's outbound branch). Creates promotion/<promotionName> from the dest org branch, merges origin/<next-env> pathspecs into that promotion branch (--no-ff --no-commit, restores non-pathspec paths), commits, merges the promotion branch into the dest org branch, and pushes both refs. If the run started on a feature branch, checks out that branch's changed files (vs lastBaseBranch) from the dest org, commits updates when needed, and tells you to re-check and publish again. If guessed pathspecs still conflict, PATCH the back-promotion status to Merge Conflict, store lastEnvironmentSyncName, resolve the files on promotion/<name>, and re-run with --continue (optional --promotion). To discard a conflicted merge, re-run with --abort (optional --promotion); runs git merge --abort and POST /agentia/headless/work/promote-action/complete with status Cancelled. After a successful sync, when --deployment resolves to local, runs `sf project deploy start --ignore-conflicts` against --sf-alias (Add-only changes), then POST /agentia/headless/work/promote-action/complete with status Completed and the resolved deployment (none|local|cloud; auto chooses local when every change is Add and --sf-alias is set, otherwise cloud). By default polls the cloud deployment JobExecution to a terminal status when deployment is cloud (--no-wait to skip). On git/merge failure (including conflicts) and after a successful --continue, uploads the captured command transcript as a Salesforce File on the back-promotion (`Environment Sync Logs <name-or-id> <datetime>.txt`) via `/agentia/headless/file/upload`. HTTP 404 is ignored until that endpoint is rolled out; other upload failures are warned and do not change the environment-sync outcome.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --destination-environment=dev1",
         "<%= config.bin %> <%= command.id %> --dev-org-branch=dev1-sfp",
         "<%= config.bin %> <%= command.id %> --continue",
         "<%= config.bin %> <%= command.id %> --abort",
         "<%= config.bin %> <%= command.id %> --promotion=P29334 --continue",
+        "<%= config.bin %> <%= command.id %> --destination-environment=dev1 --deployment=local --sf-alias=dev1",
+        "<%= config.bin %> <%= command.id %> --destination-environment=dev1 --deployment=cloud",
+        "<%= config.bin %> <%= command.id %> --destination-environment=dev1 --no-wait",
         "<%= config.bin %> <%= command.id %> --destination-environment=dev1 --json"
       ],
       "flags": {
@@ -8725,7 +8777,7 @@
           "type": "option"
         },
         "abort": {
-          "description": "Abort an in-progress merge (`git merge --abort`) and set the back-promotion status to Draft. Uses --promotion or lastEnvironmentSyncName. Exclusive with --continue.",
+          "description": "Abort an in-progress merge (`git merge --abort`) and cancel the back-promotion via promote-action/complete. Uses --promotion or lastEnvironmentSyncName. Exclusive with --continue.",
           "exclusive": [
             "continue"
           ],
@@ -8742,8 +8794,22 @@
           "allowNo": false,
           "type": "boolean"
         },
+        "deployment": {
+          "description": "How promote-action/complete handles deployment after a successful sync: none (leave deployment job untouched), local (sf project deploy start --ignore-conflicts then mark deployment JobExecution Successful; Add-only changes; requires --sf-alias), cloud (start PromotionDeployAction), or auto (local when every change is Add and --sf-alias is set, otherwise cloud). Sent to the gateway as none|local|cloud (never auto).",
+          "name": "deployment",
+          "default": "auto",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "none",
+            "local",
+            "cloud",
+            "auto"
+          ],
+          "type": "option"
+        },
         "destination-credential": {
-          "description": "Credential ID posted as destinationCredentialId when creating the back-promotion. Copado requires a credential on the next/source environment (PRO-033 if a dest/dev credential is sent) and then stores the dest/dev credential. Defaults to that source environment defaultCredential, otherwise the first source credential.",
+          "description": "Credential ID recorded on the environment-sync result as destinationCredentialId. Defaults to the next/source environment defaultCredential, otherwise the first source credential. PromoteAction resolves deployment credentials itself.",
           "name": "destination-credential",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -8782,6 +8848,27 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "sf-alias": {
+          "description": "Salesforce CLI org alias or username for local deployment (`sf project deploy start -o`). Required with --deployment=local; with --deployment=auto enables local when changes are Add-only.",
+          "name": "sf-alias",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "wait": {
+          "description": "Poll promotion and deployment executions to terminal status.",
+          "name": "wait",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "wait-timeout": {
+          "description": "Maximum total seconds to wait for promotion and deployment executions.",
+          "name": "wait-timeout",
+          "default": 900,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -8792,7 +8879,7 @@
       "pluginType": "core",
       "strict": true,
       "enableJsonFlag": true,
-      "experimental": false,
+      "experimental": true,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -8806,12 +8893,12 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "User story ID (defaults to the active work item from `work set`)",
+          "description": "User story ID or name (defaults to the active work item from `work set`)",
           "name": "id",
           "required": false
         }
       },
-      "description": "Get a Copado user story by ID",
+      "description": "Get a Copado user story by ID or name",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "<%= config.bin %> <%= command.id %> a0SKC000000CmZ2AU",
@@ -9536,11 +9623,12 @@
     "cicd:work:test": {
       "aliases": [],
       "args": {},
-      "description": "Run quality gates for the current work item. With --local (the default) it runs project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows) when present. When no project script exists it warns, runs the stock Agentia setup sample from a temporary file, then deletes that file. With --cloud it runs remote Copado quality gates (not implemented yet).",
+      "description": "Run quality gates for the current work item. Runs the project-root .agentia_quality_gates.sh (macOS/Linux) or .agentia_quality_gates.cmd (Windows); when none exists it warns and runs the stock Agentia sample from a temporary file. Every gate runs by default. Use --gate <id> (repeatable or comma-separated) to select gates; the selection is exported as AGENTIA_GATES. Standard ids are apex, lint and lwc; scripts declare gates with `# agentia-gate: <id> - <description>` comments (see --list-gates). `--gate apex` alone skips the script, runs the Apex tests directly and uploads the result to the work item (nested inside a script it does not upload; the outer run reports). With --cloud it runs remote Copado quality gates (not implemented yet).",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
-        "<%= config.bin %> <%= command.id %> --local --apex-test-classes=MyTest,OtherTest",
-        "<%= config.bin %> <%= command.id %> --local --rerun-failed-apex-tests",
+        "<%= config.bin %> <%= command.id %> --gate lint --gate lwc",
+        "<%= config.bin %> <%= command.id %> --gate apex --apex-test-classes=MyTest,OtherTest",
+        "<%= config.bin %> <%= command.id %> --list-gates",
         "<%= config.bin %> <%= command.id %> -e SKIP_LWC_TESTS=1 -e TOOL_API_KEY=secret",
         "<%= config.bin %> <%= command.id %> --json",
         "<%= config.bin %> <%= command.id %> --cloud"
@@ -9561,6 +9649,16 @@
           "multiple": false,
           "type": "option"
         },
+        "all": {
+          "description": "Run every gate in the quality-gates script (the default when no --gate is given).",
+          "exclusive": [
+            "gate",
+            "list-gates"
+          ],
+          "name": "all",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "apex-test-classes": {
           "description": "Comma-separated Apex test class names passed to local quality gates as AGENTIA_APEX_TEST_CLASSES",
           "name": "apex-test-classes",
@@ -9582,6 +9680,23 @@
           "multiple": true,
           "type": "option"
         },
+        "gate": {
+          "description": "Run only this gate id (for example apex, lint, lwc or a custom id declared in the script). Repeatable or comma-separated. Exported to the script as AGENTIA_GATES.",
+          "exclusive": [
+            "all",
+            "list-gates"
+          ],
+          "name": "gate",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "list-gates": {
+          "description": "List the gates declared in the quality-gates script (or the stock sample) and exit.",
+          "name": "list-gates",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "local": {
           "description": "Run local project-root quality gates scripts. Used by default when --cloud is omitted.",
           "name": "local",
@@ -9589,10 +9704,19 @@
           "type": "boolean"
         },
         "rerun-failed-apex-tests": {
-          "description": "Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to work test apex.",
+          "description": "Pass AGENTIA_APEX_RERUN_FAILED=--rerun-failed-apex-tests to local quality gates so sample scripts forward that flag to the apex gate.",
           "name": "rerun-failed-apex-tests",
           "allowNo": false,
           "type": "boolean"
+        },
+        "wait": {
+          "char": "w",
+          "description": "Minutes to wait for Apex test results (only with --gate apex alone).",
+          "name": "wait",
+          "default": 60,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -9617,12 +9741,12 @@
       "aliases": [],
       "args": {
         "id": {
-          "description": "User story ID (defaults to the active work item from `work set`)",
+          "description": "User story ID or name (defaults to the active work item from `work set`)",
           "name": "id",
           "required": false
         }
       },
-      "description": "Update a Copado user story by ID",
+      "description": "Update a Copado user story by ID or name",
       "examples": [
         "<%= config.bin %> <%= command.id %> --title \"Updated story\"",
         "<%= config.bin %> <%= command.id %> --custom-field JIRA_Key__c=CICD-1",
@@ -9750,7 +9874,7 @@
           "type": "option"
         },
         "record-type": {
-          "description": "Record type",
+          "description": "Record type DeveloperName",
           "name": "record-type",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -10463,73 +10587,6 @@
         "recorder.js"
       ]
     },
-    "testing:browser:reports": {
-      "aliases": [],
-      "args": {
-        "job-id": {
-          "description": "CRT job ID.",
-          "name": "job-id",
-          "required": false
-        }
-      },
-      "deprecateAliases": true,
-      "description": "List or save report artifacts from an active CRT browser session",
-      "examples": [
-        "<%= config.bin %> <%= command.id %> --project <project-id>",
-        "<%= config.bin %> <%= command.id %> --project <project-id> --output-dir ./reports"
-      ],
-      "flags": {
-        "json": {
-          "description": "Format output as json.",
-          "helpGroup": "GLOBAL",
-          "name": "json",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "project": {
-          "char": "p",
-          "description": "CRT project ID.",
-          "name": "project",
-          "required": true,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "session-id": {
-          "description": "Active CRT browser session ID.",
-          "name": "session-id",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "output-dir": {
-          "description": "Directory for log.html, report.html, and output.xml.",
-          "name": "output-dir",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [
-        "testing:live:reports"
-      ],
-      "id": "testing:browser:reports",
-      "pluginAlias": "@copado/agentia-cli",
-      "pluginName": "@copado/agentia-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": true,
-      "experimental": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "testing",
-        "browser",
-        "reports.js"
-      ]
-    },
     "testing:browser:screenshot": {
       "aliases": [],
       "args": {
@@ -15977,7 +16034,7 @@
           "type": "option"
         },
         "file-id": {
-          "description": "File Id returned by result-file list",
+          "description": "fileId (068...) returned by result-file list; a contentDocumentId (069...) is resolved automatically",
           "name": "file-id",
           "required": true,
           "hasDynamicHelp": false,
@@ -20579,7 +20636,7 @@
     "cicd:work:test:apex": {
       "aliases": [],
       "args": {},
-      "description": "Run specified Apex test classes via Salesforce CLI (`sf apex run test`) with code coverage. Usually run from project-root local quality gates (`.agentia_quality_gates.sh` / `.agentia_quality_gates.cmd`) when those scripts are configured. When `--apex-test-classes` is omitted or empty, logs that no Apex tests were specified and exits without running Salesforce CLI. Failed runs save `.agentia/apex.tests.<user-story>.json`; successful runs delete that file. `--rerun-failed-apex-tests` runs the previously failed classes (optionally filtered by `--apex-test-classes`). Prints the test-run summary when the run passes, or failing tests with their messages and stack traces when it fails. Exits with the same process exit code as Salesforce CLI (`sf`), including 100 when Apex tests fail.",
+      "description": "Legacy alias of `work test --gate apex`; prefer that form (it is what the sample quality-gate scripts call). Run specified Apex test classes via Salesforce CLI (`sf apex run test`) with code coverage. When `--apex-test-classes` is omitted or empty, logs that no Apex tests were specified and exits without running Salesforce CLI. Failed runs save `.agentia/apex.tests.<user-story>.json`; successful runs delete that file. `--rerun-failed-apex-tests` runs the previously failed classes (optionally filtered by `--apex-test-classes`). Prints the test-run summary when the run passes, or failing tests with their messages and stack traces when it fails. Exits with the same process exit code as Salesforce CLI (`sf`), including 100 when Apex tests fail.",
       "examples": [
         "<%= config.bin %> <%= command.id %> -t HelloWorldTest",
         "<%= config.bin %> <%= command.id %> --apex-test-classes=MyTest,OtherTest",
@@ -20628,6 +20685,7 @@
         }
       },
       "hasDynamicHelp": false,
+      "hidden": true,
       "hiddenAliases": [],
       "id": "cicd:work:test:apex",
       "pluginAlias": "@copado/agentia-cli",
@@ -22220,5 +22278,5 @@
       ]
     }
   },
-  "version": "1.3.0"
+  "version": "1.5.0-rc.0"
 }

package/package.json

@@ -275,7 +275,7 @@
     }
   },
   "type": "module",
-  "version": "1.3.0",
+  "version": "1.5.0-rc.0",
   "x-agentia-protected-build": true,
   "x-agentia-protected-files": [
     "dist/lib/runtime.js"

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

@@ -64,7 +64,7 @@ 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.
+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. The native Support AI service injects the system-role support persona; the CLI does not send a second system message. 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 as data in the current user message. 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.
 

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

@@ -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)
@@ -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/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

@@ -9,7 +9,7 @@ Use this reference for `agentia cicd promotion ...`, `agentia cicd promotion con
 | 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
 ```
@@ -61,7 +73,7 @@ List first and take item IDs from the output. Removal is destructive: confirm th
 
 ## 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.