@copado/agentia-cli 1.1.0 → 1.3.0

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

@@ -0,0 +1,146 @@
+---
+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. 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 -->
+
+# Org Intelligence (Agentia Metadata Exploration)
+
+**Org Intelligence** lets you inspect Salesforce **metadata** in the user's
+connected sandbox / developer org via `cicd metadata explore` (MCP
+`agentia_metadata_explore`). Prefer MCP when available; otherwise use the CLI
+with `--json` when results will be parsed.
+
+Covers Apex classes, triggers, objects, fields, Flows, and other Metadata API
+types. First release is **read-oriented** only—do not invent validate, deploy,
+create, update, or `check_async_id`.
+
+## Capabilities And Limits
+
+| Can | Cannot |
+| --- | --- |
+| Read / list / search / describe **metadata** | Read or query **org data** (records, SOQL results, reports as data) |
+| Find metadata references (`find_references`) | **Edit**, create, update, validate, or deploy metadata |
+| Run specified Apex test classes (when asked) | Mass-scan or compare entire orgs |
+
+If the user asks to change metadata or fetch record data, say Org Intelligence
+cannot do that and point them at the appropriate Copado/Agentia workflow or
+local editing instead.
+
+## Source Priority
+
+1. **Local project files first** (workspace / git / force-app / retrieved source)
+   when they exist and answer the question.
+2. **Then the connected org** via Org Intelligence (`cicd metadata explore`)
+   for names, bodies, docs, and references that are missing or unclear locally.
+
+Do not call the org when local files already provide a clear answer. Prefer
+local when reconciling differences unless the user asks for the org version.
+
+## What You Can Do
+
+| Goal | Action |
+| --- | --- |
+| 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 (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`. 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
+
+- Target is the CICD project default credential when `--credential-id` /
+  `credentialId` is omitted. Pass `--credential-id` only to override. Do not
+  mix credential auth with `--session-id` + `--endpoint`.
+- The user may call this **Org Intelligence**, or the connected org **Org**,
+  **Sandbox**, **Integration**, **Dev Org**, or similar—treat those as the
+  same target unless they ask for a different credential.
+- You can access selected metadata. You **cannot** compare orgs or run mass
+  analysis / full-org scans—that hits limits and takes too long. If a list is
+  truncated or incomplete, say you cannot finish that breadth of scan and ask
+  the user to narrow the request.
+
+## Pattern And Type Rules
+
+- **Always quote CLI wildcards** (`--pattern 'Account*'`). Unquoted `*` is
+  expanded by the shell. MCP `pattern` does not need shell quotes.
+- **`search`** only covers `ApexPage`, `ApexClass`, `ApexTrigger`, and
+  `ApexComponent`. Pattern ≥ 2 characters, at most one `*`.
+- **`list` for CustomField / FieldSet / DuplicateRule / ListView** — pattern
+  must start with the SObject name and a dot (e.g. `Account.Name`,
+  `Account.namespace__Name__c`). You cannot list every item of every object.
+- **`list` for Flow** — `--pattern` matches API name, Flow label, and
+  triggering object API name.
+- **Profiles** — reading Profile details is not supported. Tell the user you
+  cannot answer questions about Profile contents. Listing Profile names may
+  still be attempted if useful, but do not claim you can read their body.
+- **Reports, Dashboards, and Folders** — listing is not supported; say so.
+
+## Apex Tests
+
+- You cannot run all tests or local tests.
+- Ask the user which test class names to run, then pass them via
+  `--apex-unit-tests` / `apexUnitTests` (comma-separated).
+
+## How To Call
+
+```sh
+agentia cicd metadata explore --action describe_type --object-type ApexClass --json
+agentia cicd metadata explore --action list --object-type ApexClass --pattern 'Account*' --json
+agentia cicd metadata explore --action search --pattern 'Cont*' --json
+agentia cicd metadata explore --action read --object-type ApexClass --full-name MyClass --json
+agentia cicd metadata explore --action find_references --object-type ApexClass --full-name MyClass --json
+agentia cicd metadata explore --action run_apex_tests --apex-unit-tests MyClassTest --json
+```
+
+| Surface | Name |
+| --- | --- |
+| CLI | `agentia cicd metadata explore` |
+| MCP | `agentia_metadata_explore` |
+
+Tool/CLI output is YAML inside `output` (human mode prints YAML; `--json` /
+MCP return `{ output, credentialId? }`). **When talking to the user, respond in
+XML—not YAML.** Summarize findings; do not dump full tool YAML unless asked.
+Never echo session Ids, API keys, or other secrets.
+
+## Gathering Context For Generated Code
+
+When helping the user design or draft Salesforce metadata (local edits only):
+
+- Prefer **local files**, then Org Intelligence `list` / `search` / `read` /
+  `describe_type` / `find_references` for accurate names and patterns.
+- When drafting new Apex tests, search local code or ask about existing
+  conventions (data factories, test setup) before querying the org.
+- Present draft code with the client's normal artifact / code-block features.
+  Org Intelligence does not write metadata to the org.
+
+## Safety
+
+- Stay on the supported read actions above—no metadata edits, no org data.
+- Prefer sandbox/dev credentials; treat production as explicit and high-risk.
+- Narrow `--pattern` when lists are large or truncated.
+- Experimental command: expect a warning in human/JSON output.
+
+## Reference
+
+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
+session Id), and outcome (names found, test result summary, or error). Do not
+include secrets. Use XML in the user-facing reply.

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

@@ -0,0 +1,146 @@
+<!-- Agentia managed skill file: agentia setup skills -->
+
+# Org Intelligence — Metadata Explore Reference
+
+**Org Intelligence** is Agentia’s read-only Salesforce metadata inspection
+feature: `agentia cicd metadata explore` and MCP `agentia_metadata_explore`
+call `POST /agentia/headless/ai_metadata_tool` against the user's connected
+sandbox/developer org (Copado credential or Salesforce session).
+
+This is **org Metadata API exploration**, not Copado’s metadata index
+(`cicd metadata list`) or content compare helpers.
+
+**Source priority:** local project files first (when present), then the org.
+
+**Can:** read / list / search / describe metadata; `find_references`; run
+specified Apex tests when asked.
+
+**Cannot:** read org **data** (records); **edit**, create, update, validate, or
+deploy metadata. Do not invent validate/deploy/create/update, `check_async_id`,
+or flags such as `--metadata-files`, `--async-id`, `--test-level`,
+`--validate-only`, or `--organization-name`.
+
+## Prerequisites
+
+```sh
+agentia auth get --cicd --json
+```
+
+Omitting `--credential-id` / `credentialId` uses the CICD project default
+credential automatically. Override only when the user needs a different org.
+Credential auth and `--session-id` + `--endpoint` are mutually exclusive.
+
+```sh
+agentia cicd project default set --credential <credential-id>
+agentia cicd environment list --type Sandbox --json
+agentia cicd credential list --environmentid <environment-id> --json
+```
+
+## Shell Quoting
+
+Always quote CLI wildcards:
+
+```sh
+agentia cicd metadata explore --action list --object-type ApexClass --pattern 'Account*' --json
+```
+
+MCP `pattern` does not need shell quotes.
+
+## CLI Flags / MCP Args
+
+| CLI | MCP | Notes |
+| --- | --- | --- |
+| `--action` | `action` | Required. `list`, `search`, `read_documentation`, `describe_type`, `read`, `find_references`, `run_apex_tests` |
+| `--object-type` | `objectType` | e.g. `ApexClass`, `CustomObject`, `Flow` |
+| `--full-name` | `fullName` | Required for `read` |
+| `--pattern` | `pattern` | Default `*`; quote wildcards on CLI |
+| `--apex-unit-tests` | `apexUnitTests` | Required for `run_apex_tests` |
+| `--credential-id` | `credentialId` | Overrides project default |
+| `--session-id` | `sessionId` | With `--endpoint` only; never log |
+| `--endpoint` | `endpoint` | Salesforce instance URL with session |
+| `--json` | — | `{ output, credentialId? }` plus experimental warning |
+
+## Actions
+
+### `list`
+
+List names for one metadata type. Use returned `fullName` values with `read`.
+
+```sh
+agentia cicd metadata explore --action list --object-type CustomObject --pattern 'Account*' --json
+```
+
+Special pattern rules:
+
+- **CustomField / FieldSet / DuplicateRule / ListView** — pattern must start with
+  SObject + `.` (e.g. `Account.Name`, `Account.namespace__Name__c`).
+- **Flow** — pattern matches API name, label, and triggering object API name.
+
+Unsupported listings: **Reports**, **Dashboards**, **Folders** — tell the user.
+
+### `search`
+
+Text search across **ApexPage, ApexClass, ApexTrigger, ApexComponent** only.
+Pattern ≥ 2 characters; at most one `*`.
+
+```sh
+agentia cicd metadata explore --action search --pattern 'MyCtrl*' --json
+```
+
+### `describe_type` / `read_documentation`
+
+Type shape vs tool-provided docs. Prefer `describe_type` for compact structure.
+
+```sh
+agentia cicd metadata explore --action describe_type --object-type Flow --json
+agentia cicd metadata explore --action read_documentation --object-type ApexClass --json
+```
+
+### `read`
+
+Retrieve one component. **Profile contents are not supported**—inform the user
+you cannot answer questions about Profile body/details.
+
+```sh
+agentia cicd metadata explore --action read --object-type ApexClass --full-name ns__MyClass --json
+```
+
+### `find_references`
+
+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
+```
+
+### `run_apex_tests`
+
+Requires explicit test class names. Cannot run all tests or local tests—ask the
+user which classes to run.
+
+```sh
+agentia cicd metadata explore --action run_apex_tests --apex-unit-tests MyClassTest --json
+```
+
+## Limits And Behavior
+
+- Selected metadata access only—no org compare, no mass structure scan.
+- Truncated/incomplete lists → narrow pattern or tell the user the scan is too broad.
+- Tool returns YAML in `output`; **user-facing replies should be XML**, not YAML.
+- Never echo `--session-id` or other secrets.
+
+## Related Commands
+
+| Need | Command |
+| --- | --- |
+| Org Metadata API explore (read-oriented) | `cicd metadata explore` |
+| 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 (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.
 
@@ -15,23 +15,28 @@ Prefer Agentia MCP tools when they are available and match the task. Use CLI exa
 
 1. Confirm CRT auth with `agentia auth get --crt --json`. Configure missing credentials with `agentia auth set --crt ...` or the supported `AGENTIA_CRT_*` environment variables.
 2. Identify or create the CRT Project and Robot before creating or running tests. Use explicit project and job IDs; do not invent hidden active-resource defaults.
-3. Use `testing test ...` as the canonical namespace for test workflows. The shorter `testing run|logs|status|create|update` forms exist for compatibility.
+3. Use `testing job ...` as the single namespace for test definitions and runs: `job create|update|run` for definitions, `job files list|upload|download` for test files, and `job runs list|search|get|logs|abort` for executions. The old `testing create|update|status|logs|run`, `testing test ...`, `testing build ...`, and `testing job files|upload|download` forms are deprecated aliases that warn when used.
 4. Never expose PAKs, session cookies, viewer keys, variable values, or generated log content that contains secrets.
 
 ## 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
 
-- `agentia testing test run` starts CRT Robot Framework execution. It is different from `agentia cicd work test --local`.
+- `agentia testing job run` starts CRT Robot Framework execution. It is different from `agentia cicd work test --local`.
 - `agentia testing job` manages CRT job/test definitions. It is different from `agentia cicd job`, which manages Copado CICD JobExecution records.
-- Use `--wait-for-result` on `testing test run` when the agent must return the final build result in one turn.
+- `testing job run` waits for the final build result and exits non-zero when it fails. Add `--no-wait` when only the queued run record is needed.
 - 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
+```