@copado/agentia-cli 1.2.0 → 1.3.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.3.0",
   "x-agentia-protected-build": true,
   "x-agentia-protected-files": [
     "dist/lib/runtime.js"

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

@@ -1,6 +1,6 @@
 ---
 name: agentia-ai
-description: Use this skill when prompting Copado AI agents through the Agentia CLI or MCP, including `agentia ai agent ask`, `agentia ai agent chat`, Plan, Build, Test, Release, Operate, Knowledge, workspace, dialogue, user story, Salesforce org, and component context.
+description: Use this skill when prompting Copado AI agents or using interactive in-app support through the Agentia CLI or MCP, including `agentia help-agent`, `agentia ai agent ask`, `agentia ai agent chat`, Plan, Build, Test, Release, Operate, Knowledge, workspace, dialogue, user story, Salesforce org, and component context.
 ---
 
 <!-- Agentia managed skill file: agentia setup skills -->
@@ -11,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.
@@ -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
 

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/promotions.md

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

package/templates/skills/agentia-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.

package/templates/skills/agentia-testing/references/browser-testing.md

@@ -0,0 +1,93 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# CRT Browser Testing Reference
+
+Use `agentia testing browser` (and the matching `agentia_testing_browser_*` MCP tools) to drive an interactive Copado Robotic Testing browser session tied to a CRT Job and Project.
+
+## Mental Model
+
+- **One active session at a time**, stored in `.agentia/config.user.json` under `testingBrowserSession`. Always pass `--project <project-id>` (and optional `<job-id>` / `--session-id` guards).
+- **In-memory Session Cookies**: Agentia exchanges your CRT PAK for `FL`, `XSRF-TOKEN`, and `sessionsToken` cookies via `/user/access-keys/tokens?toSign=all`. Cookies stay in memory (cached with a 60s expiry buffer in long-lived processes like MCP and `recorder`) and are never written to disk.
+- **Browser Viewer**: Always pass `--no-open` to `testing browser view` by default (`agentia testing browser view --project <project-id> --no-open --json`) to print/return the interactive CRT browser session URL `https://<domain>/browser/session/<sessionId>?projectId=<projectId>&orgId=<orgId>` without launching a local browser window. Omit `--no-open` only when the user explicitly asks to open the browser. `testing browser stop` cleans up the session automatically.
+- **Replayable Keyword History**: Every `testing browser execute` and `testing browser recorder` event appends to `~/.agentia/testing-live/<projectId>/<jobId>.jsonl` with full Robot Framework keyword lines (`TypeSecret` values and auth tokens redacted). Closing a session does not clear history.
+
+## Canonical Workflow
+
+```sh
+# 1. Start the session (polls /api/status, loads QWeb/QForce/QMobile, sets QWeb config, opens Chrome)
+agentia testing browser start <job-id> --project <project-id> --json
+
+# 2. (Optional) Start the recorder in a background subagent before handing the viewer URL to a user
+agentia testing browser recorder --project <project-id> --output flow.robot
+
+# 3. Surface the viewer URL with --no-open by default (omit --no-open only if the user explicitly asks to open the browser)
+agentia testing browser view --project <project-id> --no-open --json
+
+# 4. Execute Robot Framework keywords (4+ spaces separate arguments)
+agentia testing browser execute --project <project-id> \
+  --line "GoTo    https://example.com" \
+  --line "VerifyText    Example Domain" --json
+
+# 5. Observe page state, DOM, and annotated screenshots
+agentia testing browser inspect --project <project-id> --json
+agentia testing browser inspect --project <project-id> --dom --json
+agentia testing browser screenshot --project <project-id> --output /tmp/page.png --json
+
+# 6. Export proven steps from Keyword History into a .robot script
+agentia testing browser history <job-id> --project <project-id> --lines-only > flow.robot
+
+# 7. Tear down the session (cleans up host, PACE, and local state)
+agentia testing browser stop --project <project-id> --yes --json
+```
+
+## Subcommands & Flags
+
+| Subcommand | Purpose & Key Flags |
+| --- | --- |
+| `testing browser start <job-id>` | Create and bootstrap a session. Flags: `--project` (required), `--library QWeb\|QForce\|QMobile` (default `QWeb`), `--no-bootstrap`, `--no-browser`, `--screen WIDTHxHEIGHTxDEPTH`, `--viewport WIDTHxHEIGHT`, `--file`, `--timeout`. |
+| `testing browser status [job-id]` | Check `env` (`isBrowserStarted`, `isWindowOpen`), `recorder` (`connected`), `server` (`ambleApiVersion`, `inShutdownState`, `inFatalErrorState`), and `session` (`currentIdleTime`, `sessionIdleTimeout`, `timeToExpire`, `isKeywordExecutionPending`). |
+| `testing browser execute [job-id]` | Run keywords using `--line "..."` (repeatable), `--keyword <name> --arg <val>`, `--file <path>`, or `--stdin`. Pass `--raw` to skip `.robot` section parsing. |
+| `testing browser inspect [job-id]` | Fetch `GET /api/system-state` (`url`, `timestamp`, `changeOrigin`, `systemState` interactive element annotations). Add `--dom` with `--output <file>` or `--json` to stream and reassemble `document.documentElement.outerHTML` over the terminal WebSocket. |
+| `testing browser screenshot [job-id]` | Save the current viewport PNG (including teal detection bounding boxes) to `--output <path>`. |
+| `testing browser reports [job-id]` | Fetch Robot Framework `log.html`, `report.html`, and `output.xml` metadata, or write them to `--output-dir <dir>`. |
+| `testing browser set-options [job-id]` | Set the full recorder option block (`--[no-]enable`, `--[no-]scroll-text`, `--[no-]healing-context`, `--[no-]hover-text`, `--[no-]system-state`, `--[no-]verify-text`, `--[no-]table-keywords`). Unspecified options default to `false`. |
+| `testing browser view` | Print (`--no-open`, default for agents) or open the CRT browser session URL. Always use `--no-open` unless the user explicitly asks to open the browser. |
+| `testing browser recorder [job-id]` | Connect to the session WebSocket, enable backend recording, and stream captured interactions and executed keywords as Robot Framework lines (or JSON lines with `--json`). Flags: `--output <file.robot>`, `--no-enable`, `--force` (reclaim stale lock), `--debug`. |
+| `testing browser history [job-id]` | Read per-job keyword history. Flags: `--job <id>`, `--limit <n>`, `--keyword <name>` (case-insensitive first token), `--lines-only` (flatten to raw `.robot` lines), `--include-failed` (failed executions are omitted by default), `--status completed\|failed\|recorded`. MCP `linesOnly: true` returns `count`, `jobId`, `lines`, and `projectId` without `executions`. |
+| `testing browser stop [job-id]` | Stop the session on the session host and PACE, and clear local state. Requires `--yes` in `--json` / non-TTY mode (`confirm: true` in MCP). |
+
+## Parallel Recorder & Idle Keepalive Patterns
+
+### 1. Parallel Recorder via Background Subagent
+When driving or co-piloting a browser session with a human:
+1. Run `agentia testing browser start <job-id> --project <project-id> --json`.
+2. Before handing the viewer URL to the user, start `agentia testing browser recorder --project <project-id> --output captured.robot` in a background shell/subagent. The recorder captures both browser interactions (`status: "recorded"`) and `testing browser execute` commands (`status: "completed"`) in execution order so `--output` produces a complete `.robot` file.
+3. Run `agentia testing browser view --project <project-id> --no-open --json` (always pass `--no-open` by default unless the user explicitly asks to open the browser) and share the `url` with the user.
+4. **Verify capture after the user's first action**:
+   ```sh
+   agentia testing browser history --project <project-id> --status recorded --json
+   ```
+   `recorder.connected: true` in `status` only proves the WebSocket is open, not that events are firing. If `count` remains `0` after the user clicks, drive the steps via `testing browser execute` instead.
+5. **Clean shutdown**: Send `SIGINT` (`kill -INT <pid>`) to the recorder process before running `testing browser stop` so it cleanly posts `setoptions {recorder: {enabled: false}}`. Then export the unified script from history with `agentia testing browser history --project <project-id> --lines-only > captured.robot`.
+
+### 2. Keeping Idle Sessions Warm (600s Timeout)
+- `session.sessionIdleTimeout` defaults to **600 seconds (10 minutes)** and is reset **only by executed keywords**.
+- The recorder's 3-second WebSocket heartbeat keeps the socket open but **does not reset the session idle timer**.
+- When waiting on a human to log in (e.g., MFA/SSO) or inspect the viewer, run a lightweight keepalive loop that fires `GetTitle` every 4 minutes:
+  ```sh
+  while true; do sleep 240; agentia testing browser execute --project <project-id> --line "GetTitle" --json || break; done &
+  ```
+  Stop the keepalive loop before `testing browser stop`.
+
+## Troubleshooting
+
+- **`No active CRT browser session`**: Start a session with `agentia testing browser start <job-id> --project <project-id>`. If a session died from the 600s idle timeout (`404` / `410`), Agentia clears the stale local state automatically on `status` or `stop`.
+- **`A CRT browser recorder is already running for session <id>`**: Another recorder holds the owner-scoped lock at `~/.agentia/testing-live/locks/<sessionId>.lock`. Stop the other process or pass `--force` if the prior process crashed.
+- **Keyword fails (`CRT browser keyword execution failed`)**:
+  1. Do not retry blindly. Run `agentia testing browser inspect --project <project-id> --json`.
+  2. Check if the target element has `isCovered: true` (modal/sticky header blocking it) or different `readableTexts`.
+  3. Check `agentia testing browser status --project <project-id> --json` to confirm `env.isWindowOpen: true` and `server.inFatalErrorState: false`.
+- **Browser window closed (`isWindowOpen: false`)**: Re-open Chrome with:
+  ```sh
+  agentia testing browser execute --project <project-id> --line "Open Browser    about:blank    chrome" --json
+  ```

package/templates/skills/agentia-testing/references/flow-automation.md

@@ -0,0 +1,112 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Goal-Driven Flow Automation in CRT Browser Testing
+
+Use this methodology when turning a natural-language goal ("create a lead", "add a product to the cart and verify checkout") into a verified sequence of Robot Framework keywords against an active `agentia testing browser` session.
+
+Applies to `QWeb` (default), `--library QForce` (see [qforce.md](qforce.md) for Lightning-specific rules layered on top), and `--library QMobile`.
+
+## The Core Loop
+
+```text
+Observe -> Act (one logical step) -> Verify expected state -> Recover if needed -> Continue
+```
+
+Do **not** write an entire multi-page `.robot` script up front and fire it in one `testing browser execute --file` call. Every page transition is a hypothesis until confirmed against the browser session. Execute one logical step at a time, verify the transition, and then choose the next keyword. Batching is only appropriate for coupled inputs on the same verified view (such as `TypeText    Username    ...` + `TypeSecret    Password    ...`).
+
+```sh
+# 1. Act
+agentia testing browser execute --project <project-id> --line "GoTo    https://example.com" --json
+
+# 2. Verify
+agentia testing browser execute --project <project-id> --line "VerifyText    Example Domain" --json
+
+# 3. Observe interactive elements before the next decision
+agentia testing browser inspect --project <project-id> --json
+```
+
+## Choosing Locators (Priority Order)
+
+Always prefer semantic locators over structural XPaths:
+
+1. **Visible text** (`ClickText`, `TypeText`, `TypeSecret`, `VerifyText`, `DropDown`, `ClickCheckbox`). Disambiguate repeated text with `anchor=<nearby text>` before reaching for `index=<N>`.
+2. **Unique attribute** (`alt`, `title`, `tooltip`, `data-icon`) when there is no visible text — use `ClickItem` / `VerifyItem`.
+3. **XPath as a last resort** (`ClickElement`, `VerifyElement`) only when text and attribute locators cannot reach the element.
+
+While exploring unfamiliar pages, pass a short bounded timeout (`timeout=3`) so a wrong locator fails in 3 seconds instead of 10 seconds:
+
+```sh
+agentia testing browser execute --project <project-id> --line "ClickText    Sign In    timeout=3" --json
+```
+
+Drop the tight `timeout=3` override when curating the final exported `.robot` suite.
+
+## Why "Completed" Execution Still Needs Verification
+
+`testing browser execute` returning `status: "completed"` only proves the keyword ran without throwing an error—it does **not** prove that navigation succeeded, a form submitted, or a modal opened.
+
+After any state-changing keyword (`GoTo`, `Click*`, `Type*`, `DropDown`, `PickList`, `ComboBox`, `PressKey`), run a `Verify*` keyword targeting content **unique to the new state**:
+- After login -> verify dashboard heading or app navigation.
+- After opening a modal -> verify a field label inside the modal before typing.
+- After saving a record -> verify the saved state or record detail field.
+
+Watch for missing workflow transitions:
+- **Typed into a search box**: Append `\n` to the `TypeText` value to submit on Enter, or click the search button.
+- **Filled form fields**: Click `Save` / `Submit` before asserting the outcome.
+
+## Observing Page State: `inspect` + `screenshot` Overlay
+
+| Question | Command |
+| --- | --- |
+| Which interactive elements are visible? | `agentia testing browser inspect --project <project-id> --json` |
+| What does the viewport look like with detection boxes? | `agentia testing browser screenshot --project <project-id> --output /tmp/page.png --json` |
+| What is the raw HTML (`outerHTML`)? | `agentia testing browser inspect --project <project-id> --dom --json` |
+
+### Reading `inspect` and `screenshot` Together
+The PNG saved by `testing browser screenshot` is not a plain screenshot: the CRT inspection engine draws colored bounding rectangles (teal by default from `SetConfig    HighlightColor    teal`) around every detected UI element. Each rectangle corresponds to an entry in the `systemState` array from `testing browser inspect`:
+- `annotationIndex` — matches the numbered/boxed element in the detection pass.
+- `readableTexts` (`ownText`, `ariaLabel`, `nearbyTexts`) — exact strings to pass to `ClickText` / `TypeText` and `anchor=`.
+- `elementType` and `role` — distinguishes inputs, buttons, links, and `role="combobox"` lookups.
+- `isVisible`, `isInteractive`, `isEnabled`, `isCovered` — if `isCovered: true`, a modal, toast, or sticky header is covering the element and must be closed or scrolled past first.
+
+## Recovery Protocol
+
+When an action or verification fails:
+1. **Stop immediately.** Do not execute the next planned step.
+2. **Inspect first** (`testing browser inspect` and `testing browser screenshot`) — never retry blindly.
+3. **Compare expected vs. actual state**:
+   - *Still on the previous view?* A workflow transition (submit, save, menu click) didn't fire. Complete the transition rather than swapping locators.
+   - *On the expected view?* The locator was wrong. Pick up to 3 semantic alternatives directly from `systemState[].readableTexts` (`anchor=`, `ClickItem`, etc.).
+4. **Wrong-but-successful action** (e.g., clicked the wrong `New` button):
+   - Inspect where you landed, restore the prior view (`Back` or re-navigate), verify restoration, and retry with `anchor=<nearby text>` or `SetConfig    PartialMatch    False`.
+   - Remember that successful wrong clicks land in `testing browser history` (`status: "completed"`) — strip them when curating the final `.robot` file.
+
+## Tuning the Session for Agent-Driven Flows
+
+- **Exact text matching**: Bootstrap sets `PartialMatch    True`. On text-dense pages (especially Salesforce Lightning), switch to exact matching since you have exact `readableTexts` from `inspect`:
+  ```sh
+  agentia testing browser execute --project <project-id> --line "SetConfig    PartialMatch    False" --json
+  ```
+- **XHR-heavy pages**: Raise timeouts with `SetConfig    DefaultTimeout    20s` and `SetConfig    XHRTimeout    30s` instead of adding `Sleep`.
+
+## Exporting and Promoting the Proven Flow
+
+Failed probes (`status: "failed"`) are automatically excluded by `testing browser history`:
+
+```sh
+agentia testing browser history <job-id> --project <project-id> --lines-only > flow.robot
+```
+
+Curate `flow.robot` by removing exploratory detours, temporary `timeout=3` overrides, and duplicate steps, then wrap it in a standard Robot Framework suite for `agentia testing job files upload` and `agentia testing job run`:
+
+```robotframework
+*** Settings ***
+Library           QWeb
+Suite Setup       Open Browser    about:blank    chrome
+Suite Teardown    Close All Browsers
+
+*** Test Cases ***
+Verified Flow
+    GoTo          https://example.com
+    VerifyText    Example Domain
+```