robotframework-harness 1.0.0__py3-none-any.whl

rf_harness/_assets/hooks/hooks.json

@@ -0,0 +1,84 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" SessionStart --agent auto",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" UserPromptSubmit --agent auto",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" PreToolUse --agent auto",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" PostToolUse --agent auto",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" PostToolUseFailure --agent auto",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" Stop --agent auto",
+            "timeout": 90
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" SessionEnd --agent auto",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

rf_harness/_assets/skills/rf-harness/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: rf-harness
+description: Robot Framework test automation - write, debug and repair .robot/.resource tests (Browser/Playwright web UI incl. iframes, shadow DOM, custom widgets; SeleniumLibrary; RequestsLibrary APIs), explore unknown web pages, fix failing suites, find keywords, analyze output.xml. Hooks execute your test lines live after every edit and attach the results. Use for any Robot Framework task.
+---
+
+# Robot Framework with live hooks
+
+No helper command: you write files and run `robot`; hooks do the rest.
+- **Every Write/Edit of a test file** runs its new/changed lines in a live RF session (page, sessions, variables kept)
+  and answers briefly: `L10-L16 PASS (7 lines)` + the page, or the failing line, the error, a `verdict:`, the nearest
+  controls and a `NEXT:` step (some sessions also get a controls list after each new page, the keyword's signature and
+  a `hint:` with every failure). A failing line stays open: fix it (or insert lines before it) and only that
+  part re-runs. Changing an executed line restarts the test (fresh browser context). `[Teardown]` runs only in the
+  plain run. Only edits that break the file's syntax/structure, delete tests or hide failures are refused; other
+  static findings come as a one-line warning and the live run decides.
+- **Verdicts** (live element timeout 2.5 s; navigation/`Wait*` keep the normal one; never in your files):
+  `COVERED` (another element, e.g. a styled `<span>` over a radio, intercepts the click -> click its label / the element
+  on top; waits and force do not help), `NOT_VISIBLE`, `DISABLED`, `ANIMATING`, `AMBIGUOUS` (several matches),
+  `PRESENT` (element exists, not a timing issue), `MISSING` (no match: wrong selector or iframe), `IN_IFRAME`
+  (use the given `frame >>> sel`), `SLOW` (was absent, appeared late: the page keeps the normal timeout; a wait is only
+  suggested when close to the limit). Value checks show `actual ... vs expected ...`: fix data/steps, not timing.
+
+## Files the hooks write (Read / Grep them; never Read whole huge files)
+- `.rf/state/latest/` after the last executed step of an edit and on failures: `page.txt` (url, title + the page's
+  VISIBLE TEXT), `controls.txt` (every control with label/id/name/data-test, hidden?, `=>` suggested selector, iframe
+  controls with `frame >>> `), `aria.yaml`, `source.html`, `screenshot.jpg`; history `.rf/state/step-NNN-<keyword>/`.
+- `.rf/docs/<Library>.md`: one line per keyword (`grep -i "select option" .rf/docs/*.md`), `<Library>.full.md`: full
+  docs; reading `.rf/docs/kw/<Library>.<Keyword>.md` (path given with a failure) writes that keyword's full doc.
+
+## New test (web or API)
+1. Write the file with `*** Settings ***` (`Library    Browser`, `Suite Setup    New Browser    chromium    headless=True`)
+   and the first lines (`New Page    ${URL}`); pick selectors from `.rf/state/latest/controls.txt`. In a user journey
+   reach pages by clicking like a user (no `Go To` deep links).
+2. Add a few lines per edit and read each result. Read values from the page instead of guessing.
+3. Final proof: `robot -d results tests/x.robot`. Failures are summarized and the first one reproduced live (if it
+   passes live it is a timing race: wait for the needed state before the failing step); a gate at the end of your turn
+   asks for this run if a test file changed since its last green plain run.
+
+## Repair an existing failing suite (references/debug.md)
+1. `robot -d results path/suite.robot` -> one line per failure + live reproduction stopped at the first failing line.
+2. Fix that line with your edit tool (state files show the page at the failure) -> it re-runs from there.
+3. Never delete/rename/skip tests or silence failures (refused) or weaken assertions; no `Sleep`. Finish with a green
+   plain run.
+Results only: `robotcode results summary|show --failed -o results/output.xml` (references/results.md).
+
+## REPL / debugger (optional; a test file runs live too and keeps its page)
+```
+robotcode repl --plain --no-history -d .rf/out 2>&1 <<'RF'
+Library    Browser
+New Browser    chromium    headless=True
+New Page    file:///abs/path/page.html
+${t}=    Get Title
+.exit
+RF
+```
+Quoted heredoc, one statement per line, 4 spaces between cells, no `...` lines, `[ FAIL ]` on stderr, exit code
+always 0, new session per call; `[rfh] COVERED/SLOW/MISSING` lines judge failures. `robotcode robot-debug --plain -d .rf/out
+--break tests/x.robot:12 tests/x.robot 2>&1 <<'RF'` then `.where` / `.pp ${v}` / `.c` (bare `.break` args).
+
+## Rules
+- PORTABLE: plain `robot <file>` must pass. Import project code by path (`Library    ${CURDIR}/../lib/MyLib.py`,
+  `Resource    ${CURDIR}/common.resource`); never -P/PYTHONPATH (warned); pip/playwright installs are refused.
+- Separate keyword and arguments with 4 spaces. A cell starting with `#` is a comment: write `\#id`, `id=x`, `css=#x`.
+
+## Browser facts (verified, Browser 19.12 / 20.5)
+- iframe: `id=frame >>> id=field` (no select-frame keyword). Open shadow DOM: css/id/text pierce it, xpath does not.
+- Stable selectors first: `data-test=x`, `id=x`, `role=button[name="Save"]` (exact name), `text="Save"` (exact;
+  `text=Save` = substring). ARIA lines are not selectors. Strict mode: >1 match fails -> unique or `>> nth=0`.
+- Values do not wait: `${t}=    Get Text    id=x` returns the current value; with an operator it retries only ~1 s.
+  Async UI: `Wait For Condition    Text    id=x    contains    Done    timeout=15s` or
+  `Wait For Elements State    id=spinner    hidden    timeout=15s`.
+- Hidden styled radio/checkbox: click its label (`Click    label[for="opt"]`), assert `Get Checkbox State    id=opt    ==    checked`.
+  Native `<select>`: `Select Options By    id=x    label    Oslo`; custom dropdown: click it, then `role=option[name="Oslo"]`.
+  Cookie banner/overlay: close it first (force=True would click the overlay). Styled radio/checkbox covered by a
+  `<span>`: click the `label[for="id"]`, or `label:has(#id)` when the input sits inside its label (no `for=`);
+  never a positional `>> nth=` pick.
+
+More: references/{browser,explore,waits,debug,requests,results,selenium}.md.

rf_harness/_assets/skills/rf-harness/references/browser.md

@@ -0,0 +1,157 @@
+# Browser library (Playwright): locators, iframes, shadow DOM
+
+BROWSER LIBRARY (Playwright) -- LOCATORS, IFRAMES, SHADOW DOM
+
+VERIFIED CORE (checked live on Browser 19.12 and 20.5):
+- Strategies: css (default, no prefix needed), id=, text=, xpath= (or start with // ), data-test=/data-testid=.
+- IFRAMES: Browser has NO "select frame" keyword. Put the frame selector in front and pierce it with >>>
+      Fill Text    id=editor-frame >>> id=title    Draft
+      Click        iframe[name="payment"] >>> text=Submit order
+  Several steps in one frame:  Set Selector Prefix    id=editor-frame >>>   ...   Set Selector Prefix    ${EMPTY}
+  .rf/state/latest/aria.yaml includes iframe content (Browser < 20.5: one section per iframe headed with the frame
+  selector to prefix; >= 20.5: `Get Aria Snapshot    css=body    mode=ai` inlines it); controls.txt lists iframe
+  controls with the full `frame >>> selector`.
+- SHADOW DOM: css=, text= and id= pierce OPEN shadow roots automatically -> write the inner selector as if
+  there were no shadow root:  Click    css=#shadow-btn  /  Get Text    text=Shadow says hi
+  xpath does NOT pierce shadow roots; css:light= / text:light= deliberately do not pierce; closed roots unreachable.
+- ROLE selectors work too: role=button[name="Sign in"] (exact accessible name; case-sensitive).
+- STRICT MODE: a selector matching >1 element fails. Make it unique, or pick one: `css=.item >> nth=0` (zero-based).
+- A cell STARTING with # is an RF comment: write `\#submit`, `css=#submit` or `id=submit`.
+- Before acting on an unknown page: read .rf/state/latest/controls.txt / aria.yaml (written after each run that navigated or failed), then build a selector.
+  ARIA lines like `button "Sign in"` are NOT selectors -> use text="Sign in" / css=button >> text=Sign in.
+- Element keywords auto-wait up to the browser timeout (default 10 s) for the ELEMENT; values do not
+  (getters with an operator retry only 1 s -> references/waits.md). The hook's probe refuses a step early (NOT RUN):
+  NOT_FOUND (nothing matched within the short live timeout; inside an iframe -> prints the `frame >>> selector` fix;
+  otherwise re-checked with the normal timeout -> SLOW or MISSING),
+  NOT_VISIBLE (hidden styled input -> prints the label to click), COVERED (overlay/cookie banner -> close it).
+- Custom widgets, dropdowns, dates, dialogs, new tabs, cookie banners: references/explore.md.
+
+--- browser locator reference ---
+locator_strategies:
+  css: CSS selector (default strategy) - e.g., 'css=.class > #login_btn' or just '.class > #login_btn'
+  xpath: XPath expression - e.g., 'xpath=//input[@id="login_btn"]' or '//input[@id="login_btn"]'
+  text: Browser text engine (exact/partial/regex) - e.g., 'text=Login' or "Login"
+  id: Element ID attribute - e.g., 'id=login_btn'
+  css:light: CSS without shadow DOM piercing - e.g., 'css:light=article div'
+  text:light: Text without shadow DOM piercing - e.g., 'text:light=Login'
+  data-testid: data-testid attribute - e.g., 'data-testid=submit-button'
+  data-test-id: data-test-id attribute - e.g., 'data-test-id=submit-button'
+  data-test: data-test attribute - e.g., 'data-test=submit-button'
+  id:light: ID without shadow DOM piercing - e.g., 'id:light=login_btn'
+selector_patterns:
+  explicit: strategy=value (e.g., 'css=.button', 'xpath=//button')
+  implicit_css: Plain selectors default to CSS (e.g., '.button' becomes 'css=.button')
+  implicit_xpath: Selectors starting with // or .. become XPath (e.g., '//button')
+  implicit_text: Quoted selectors become text (e.g., '"Login"' becomes 'text=Login')
+  cascaded: Multiple strategies with >> separator (e.g., 'text=Hello >> ../.. >> .select_button')
+  iframe_piercing: Frame piercing with >>> (e.g., 'id=iframe >>> id=btn')
+  element_reference: Element reference with element= (e.g., '${ref} >> .child')
+common_examples:
+  CSS (default): .button-primary
+  CSS explicit: css=.button-primary
+  CSS with ID: \#submit-btn
+  XPath: //input[@type='submit']
+  XPath implicit: //button[contains(text(), 'Login')]
+  Text substring (case-insensitive): text=Login ; exact: text="Login"
+  Text implicit: "Login"
+  Text regex: text=/^Log(in|out)$/i
+  ID: id=submit-button
+  Cascaded: text=Hello >> ../.. >> .select_button
+  iFrame piercing: id=myframe >>> .inner-button
+selector_format_rules:
+  Default strategy: CSS - plain selectors are treated as CSS
+  Explicit format: strategy=value (spaces around = are ignored)
+  XPath detection: Selectors starting with // or .. become XPath automatically
+  Text detection: Quoted selectors ("text" or 'text') become text selectors
+  Cascading: Use >> to chain selectors (css=div >> text=Login >> .button)
+  iFrame access: Use >>> to pierce iFrames (id=frame >>> id=element)
+  Element refs: Use element=${ref} >> .child for element references
+strict_mode_info:
+  description: Browser Library uses strict mode by default
+  strict_true: Keyword fails if selector finds multiple elements
+  strict_false: Keyword succeeds even with multiple matches (uses first)
+  how_to_change: Use 'Set Strict Mode' keyword or library import parameter
+shadow_dom_support:
+  automatic_piercing: CSS and text engines automatically pierce open shadow roots
+  light_engines: Use css:light= or text:light= to disable shadow DOM piercing
+  closed_shadow_roots: Closed shadow roots cannot be accessed
+tips:
+  - Browser Library uses CSS selectors by default (no prefix needed)
+  - Use \# instead of # for ID selectors (Robot Framework escaping)
+  - XPath: Start with // or .. for automatic detection
+  - Text: Use quotes for exact text matching or regex patterns
+  - Cascaded selectors: Chain with >> for complex element paths
+  - iFrames: Use >>> to access elements inside frames
+  - Shadow DOM: CSS pierces automatically, use :light for light DOM only
+  - Strict mode: Controls behavior when multiple elements match
+strict_mode_violation:
+  issue: Selector matches multiple elements but strict mode is enabled
+  solutions:
+    - Make selector more specific to match only one element
+    - Use 'Set Strict Mode    False' to allow multiple matches
+    - Add more specific CSS selectors or attributes
+    - Use nth-child() or other CSS pseudo-selectors for specific elements
+  examples:
+    - Instead of '.button' use '.button.primary' or '.button:nth-child(1)'
+    - Instead of 'div' use 'div.container > div.content'
+    - Add unique attributes like '[data-testid="submit-btn"]'
+element_not_found_suggestions:
+  - Verify element exists on current page
+  - Check if element loads asynchronously (use Wait For Elements State)
+  - Try different selector strategies (CSS, XPath, text, ID)
+  - Check if element is inside an iFrame (use >>> syntax)
+  - Verify element is not in closed shadow DOM
+  - Use browser developer tools to inspect element
+  - Check if element appears after user interaction
+timeout_suggestions:
+  - Increase timeout with explicit waits
+  - Use 'Wait For Elements State' before interaction
+  - Check if element loads dynamically
+  - Verify selector syntax is correct
+  - Use 'Wait For Load State' to ensure page is ready
+shadow_dom_guidance:
+  issue: Element may be in shadow DOM
+  solutions:
+    - Use regular CSS (automatic shadow piercing): 'css=.my-element'
+    - Use text selectors (automatic shadow piercing): 'text=Button Text'
+    - Avoid css:light= for shadow DOM elements
+    - Check if shadow root is closed (not accessible)
+  note: Browser Library automatically pierces open shadow roots with CSS and text engines
+iframe_guidance:
+  issue: Element may be inside an iFrame
+  solutions:
+    - Use frame piercing syntax: 'id=myframe >>> .inner-element'
+    - There is no 'select frame' step in Browser: put the frame selector in front, `<frame> >>> <inner>`
+    - Use 'Set Selector Prefix' for multiple operations in same frame
+  examples:
+    - Click    id=login-frame >>> input[name='username']
+    - Set Selector Prefix    id=content-frame >>>
+Click    .submit-button    (prefix MUST end with >>>; reset: Set Selector Prefix    ${EMPTY})
+
+--- common locator patterns ---
+
+   Browser library (Playwright-backed):
+     id=submit                       — by id attribute (equivalent to css=[id="submit"])
+     css=button.primary              — CSS selector
+     text=Sign in                    — substring match, case-insensitive (use text="Sign in" for exact)
+     xpath=//input[@type='submit']   — XPath fallback
+     id=item >> nth=2                — Playwright cascaded nth filter (zero-based; also via intent_action nth=2)
+     // and ..                       — auto-routed to xpath (no prefix needed)
+     "Quoted string"                 — auto-routed to exact text= (no prefix needed)
+   For ARIA role + accessible name, use Browser's dedicated keywords
+   (Get Element By Role, Click With Options) — the role engine ALSO works as a selector string: role=button[name="Sign in"] (verified live).
+
+   SeleniumLibrary (= or : both work; : is the doc-preferred form):
+     id=submit                       — by id attribute
+     name=username                   — by name attribute
+     css=button.primary              — CSS selector
+     xpath=//input[@type='submit']   — XPath
+     link=Click here                 — full link text
+     partial link=Click              — partial link text (space inside the prefix)
+     css=tr:nth-of-type(3)           — 1-based CSS nth 
+
+   PICKING A LOCATOR
+   - Prefer id= when available (stable, fast).
+   - Fall back to css= or text= for elements without stable ids.
+   - Use xpath= only when CSS/text cannot express the predicate.
+   - When multiple elements match, disambiguate with `>> nth=N` (zero-based).

rf_harness/_assets/skills/rf-harness/references/debug.md

@@ -0,0 +1,39 @@
+# Debugging an existing failing suite
+
+RULES: fix the TEST code (locators, waits, imports, keyword usage, test data handling). Keep every test and the
+intent of every assertion: never delete or skip tests, never loosen/remove assertions (== -> contains, Run Keyword
+And Ignore Error, deleting a check). Change an expected literal only if the app clearly renamed it, and say so.
+
+1. Run it as is: `robot -d results path/suite.robot`. The hook attaches, from output.xml:
+   - one line per failed test: name, file:line, failing keyword, message;
+   - a LIVE REPRODUCTION of the first failing test: re-run from the top in the hook's session, stopped AT the failing
+     line with the page left open; page summary (title, url, controls with suggested selectors); full state in
+     .rf/state/latest/{controls.txt, aria.yaml, source.html, screenshot.jpg, page.txt} (history: .rf/state/step-NN-<keyword>/).
+   More detail without re-running: `robotcode results show --failed -o results/output.xml`,
+   `robotcode results log "*Test Name*" -o results/output.xml` (keyword tree with arguments).
+2. Classify by message: timeout / "waiting for locator" / NOT_FOUND -> locator (or element hidden/covered: NOT_VISIBLE,
+   COVERED with the fix); "should be/contain" with an intermediate value ("Loading...", 0, empty) -> missing wait;
+   "No keyword with name" -> import/typo; ModuleNotFoundError / "does not exist" on an import -> import path.
+3. Fix the failing line with your edit tool (or the .resource keyword it calls). The hook re-runs it right away, in the
+   page that is still open, and continues to the end of the test or the next failure. A failure inside a user keyword
+   is reported on the calling test line (`failed inside: <keyword>`): fix the keyword, the failed line re-runs.
+4. Editing a line of another failing test runs that test (from its setup). Changing a line that already passed
+   restarts that test from the top.
+5. A live re-run of a WAIT fix is weak evidence (the page has finished loading meanwhile): the plain run decides.
+6. Fix every failing test, then the proof: `robot -d results path/suite.robot` (fresh browser, all tests). After a
+   green run the hook records the suite as verified; at the end of your turn a gate asks for this run if a test file
+   changed since its last green plain run.
+
+Typical fixes (Browser library):
+- stale locator -> pick a stable one from .rf/state/latest/controls.txt: data-test=..., id=..., role=button[name="Save"],
+  text="Save"; avoid long CSS chains / nth-child / generated ids.
+- missing wait -> a getter without operator does not wait, with operator it retries only 1 s:
+      Wait For Condition    Text    id=status    contains    Saved    timeout=15s
+      Wait For Elements State    id=spinner    hidden    timeout=15s       (never Sleep; references/waits.md)
+- element covered (cookie banner, modal): close it first; force=True would click the overlay instead.
+- hidden styled radio/checkbox, custom dropdown, dialogs, new tabs, dates: references/explore.md
+- element inside an iframe: `id=frame >>> id=field` (references/browser.md)
+- PORTABLE: the suite must pass with plain `robot <file>`: Library    ${CURDIR}/../lib/MyLib.py (by path, never
+  -P / PYTHONPATH / robot.toml).
+API suites: the reproduction stops at the failing request; the message shows status/body. Log values with
+  `Log    ${resp.json()}` lines while debugging (references/requests.md).

rf_harness/_assets/skills/rf-harness/references/explore.md

@@ -0,0 +1,52 @@
+# Unknown pages and custom widgets
+
+EXPLORING AN UNKNOWN LIVE PAGE + CUSTOM WIDGETS   (verified on Browser 19.12 and 20.5)
+
+Open it and LOOK before writing any selector: write the Settings + `New Page    ${URL}` first; the hook runs it
+and writes the page state (rewritten after every run that navigated or failed):
+  .rf/state/latest/controls.txt   # every field/button/link: label, id, name, data-test, hidden?, native/custom, => selector
+  .rf/state/latest/aria.yaml      # texts, roles, accessible names, one section per iframe Read messages from the page (Get Text) instead of guessing.
+
+Selectors, most stable first: data-test=x / data-testid=x > id=x (not generated ones like id=r12, ember34) >
+  role=textbox[name="E-mail"] / role=button[name="Save"] (name = label / aria-label / text) > text="Save" >
+  short attribute CSS input[name="email"] > xpath. Avoid long CSS chains, nth-child, generated class names.
+  By label/placeholder: ${e}=    Get Element By    Label    E-mail   then   Fill Text    ${e}    me@x.org
+
+Cookie banner / overlay: close it first (Click    text=Accept all). The hook's probe reports COVERED. A click that
+  fails with "intercepts pointer events" is covered too; Click With Options ... force=True does NOT help (the click
+  lands on the overlay, passes, and nothing happens).
+
+Styled radio / checkbox (the real <input> is hidden, a label/span is drawn instead): Check Checkbox / Click on the
+  input waits for visibility and fails (the hook's probe: NOT_VISIBLE + the label to click). Click the visible label:
+      Click    label[for="opt-yes"]         Click    label:has(#newsletter)         Click    text=Round trip
+  Assert on the input (works while hidden): Get Checkbox State    id=opt-yes    ==    checked
+
+Dropdowns:
+  native <select> (aria: combobox WITH option children; controls: "native select"):
+      Select Options By    id=country    label    Germany          (or value    de  /  index    2)
+      Get Selected Options    id=country    label    ==    Germany  (attribute BEFORE the operator)
+  custom dropdown (button/div, role=combobox/listbox; Select Options By fails "Element is not a <select> element"):
+      Click    id=country-picker    ->  .rf/state/latest/aria.yaml  ->  Click    role=option[name="Germany"]   (or text=Germany)
+      Get Text    id=country-picker    ==    Germany
+
+Dates (add `Library    DateTime`): never hard-code a date that expires.
+      ${d}=    Get Current Date    increment=7 days    result_format=%Y-%m-%d       # today + 7
+      ${r}=    Add Time To Date    ${d}    14 days    result_format=%m/%d/%Y         # from another date
+  <input type=date>: Fill Text    id=start    ${d}   with %Y-%m-%d (shown localized). Text fields: the format of
+  their placeholder/label (%d.%m.%Y, %m/%d/%Y ...). Calendar pop-ups: try Fill Text on the input first; else open it
+  and click the day (.rf/state/latest/aria.yaml).
+
+JavaScript alert/confirm/prompt: without a handler they are DISMISSED (confirm() -> false, nothing happens).
+      Handle Future Dialogs    action=accept    prompt_input=My text   # ONCE per page, BEFORE the click; stays active
+      ${p}=    Promise To    Wait For Alert    action=accept    text=Delete item?   /  Click ...  /  Wait For    ${p}
+  One handler per page: a 2nd Handle Future Dialogs (Browser 19.x) or mixing it with Wait For Alert -> two handlers
+  -> the Playwright process crashes and every later test fails. Different answers on one page: one
+  `Promise To    Wait For Alert` per dialog (accept/dismiss, prompt_input=...) and no Handle Future Dialogs there.
+  In-page modals (role=dialog) are normal elements.
+
+New tab / popup:  Click    text=Help   ->   ${prev}=    Switch Page    NEW   ...   Switch Page    ${prev}
+
+Async UI: values do not wait; assertion operators retry only 1 s -> Wait For Condition    Text    id=status
+  contains    Done    timeout=15s / Wait For Elements State    id=spinner    hidden    timeout=15s (references/waits.md).
+Form ignores a filled value ("required" while text is shown): Fill Text fires `input` but not `change`; leave the
+  field: Press Keys    id=email    Tab

rf_harness/_assets/skills/rf-harness/references/requests.md

@@ -0,0 +1,37 @@
+# RequestsLibrary: API testing
+
+REQUESTSLIBRARY -- API TESTING
+
+VERIFIED CORE:
+- Create Session    api    http://127.0.0.1:8000        (alias + base URL)
+- ${resp}=    GET On Session    api    /users.json    expected_status=200
+- Status Should Be    200    ${resp}
+- ${data}=    Set Variable    ${resp.json()}            (outside Evaluate: ${resp.json()}; inside Evaluate: $resp.json())
+- Should Be Equal As Strings    ${resp.json()}[0][name]    Ann
+- ${resp}=    POST On Session    api    /items    json=${body}    (json= for JSON bodies, NOT data=)
+- ${resp}=    GET On Session    api    /missing    expected_status=404     (non-2xx without failing)
+- `grep -i "on session" .rf/docs/RequestsLibrary.md` shows the real parameters (alias, url, data, json, expected_status, msg, **kwargs).
+
+--- requests locator reference ---
+tips:
+  - SESSION: Create Session with an alias + base URL, then use GET/POST/PUT/PATCH/DELETE On Session with that alias and a RELATIVE path. A bare Get/Post takes a full URL.
+  - RESPONSE: On-Session keywords RETURN the response — capture with ${resp}=. Read status via ${resp.status_code}, body via ${resp.json()}, a field via ${resp.json()["bookingid"]}.
+  - EVALUATE: Inside Evaluate use the BARE name ($resp, $token); OUTSIDE Evaluate use ${resp.json()}. Do NOT reach for Evaluate to compare status/fields — use the native assertion keywords.
+  - STATUS ASSERT: use 'Status Should Be    200    ${resp}' — NOT an Evaluate equality on ${resp.status_code}. This is the biggest Evaluate-call remover.
+  - BODY/HEADERS: Send a JSON body with json=<dict> — NOT data=. Set headers with headers=${headers}. A 400/415 usually means data= was used, the body was a string, or Content-Type: application/json is missing.
+  - BODY CONSTRUCTION: Build the JSON body dict, do NOT pass a repr-string. Easiest: inline Python eval — json=${{ {"firstname": "Jane", "totalprice": 111, "depositpaid": True, "bookingdates": {"checkin": "2024-01-01"}} }} (a real Python literal, so True/False/None and nested dicts work). Or define it first and pass it: assign ${body}= via Evaluate  {"firstname": "Jane", ...}  THEN reference json=${body} in the POST — never POST before ${body} exists. Avoid Set Variable/Create Dictionary gymnastics for JSON bodies.
+  - AUTH TOKEN: capture the token from ${resp.json()["token"]}, then send it as a cookie header: headers=${{"Cookie": "token=" + $token}} (or a &{headers} dict). Required for PUT/DELETE on restful-booker.
+  - NON-2XX: pass expected_status=404 (or expected_status=anything) so an error response is RETURNED instead of raising — needed to assert a deleted resource returns 404.
+  - NAMED ARGS: RequestsLibrary named args are positional name=value tokens (expected_status=200, json=${body}, headers=${headers}), not RF &{dict} kwargs.
+warnings:
+  - ${resp.json()} works OUTSIDE Evaluate; inside Evaluate it is $resp.json() (bare) — mixing them is the #1 API time sink.
+  - Without expected_status=, a non-2xx response RAISES — you cannot then assert a 404; pass expected_status to capture error responses.
+  - PUT/DELETE that return 403/Forbidden usually mean the auth token cookie header was not sent.
+examples:
+  - Create Session    rb    https://restful-booker.herokuapp.com      # alias + base URL
+  - ${resp}=    POST On Session    rb    /booking    json=${{ {"firstname": "Jane", "lastname": "Doe", "totalprice": 111, "depositpaid": True, "bookingdates": {"checkin": "2024-01-01", "checkout": "2024-01-05"}} }}      # build the JSON body inline with ${{ }} — no Set Variable/Create Dictionary
+  - ${resp}=    POST On Session    rb    /auth    json=${creds}      # or define ${creds}= first, then reference it (never POST before it exists)
+  - Status Should Be    200    ${resp}      # native status assertion (not Evaluate)
+  - ${token}=    Set Variable    ${resp.json()["token"]}      # read a JSON field outside Evaluate
+  - ${resp}=    GET On Session    rb    /booking/${id}    expected_status=404      # assert a deleted resource → 404 without raising
+  - ${resp}=    DELETE On Session    rb    /booking/${id}    headers=${{"Cookie": "token=" + $token}}      # auth token cookie header

rf_harness/_assets/skills/rf-harness/references/results.md

@@ -0,0 +1,34 @@
+# Running robot and reading output.xml
+
+RESULTS / output.xml ANALYSIS
+
+Run:
+  robot -d results tests/                      # or: robotcode robot -d results tests/
+  robot -d results -t "Login*" -i smoke tests/ # select by test name / tag;  --dryrun = syntax/keyword check only
+  Exit code = number of failed tests (0 = all passed). Files: results/output.xml, log.html, report.html.
+
+Inspect a finished run WITHOUT re-running (robotcode results; -o selects the file, default from robot.toml):
+  robotcode results summary -o results/output.xml            # counts + overall status
+  robotcode results show --failed -o results/output.xml      # one line per failed test: name, path:line, message
+  robotcode results log "*Login*" -o results/output.xml      # keyword tree of matching tests (args, messages)
+  robotcode results stats --by tag -o results/output.xml     # aggregate by tag/suite/status
+  robotcode results diff old/output.xml new/output.xml       # status changes between runs
+  robotcode --format json results summary -o results/output.xml   # machine-readable
+  NOTE: `-o` belongs AFTER the subcommand (robotcode results show -o FILE).
+
+Custom analysis with Robot Framework's API (no extra packages):
+  python - <<'PY'
+  from robot.api import ExecutionResult, ResultVisitor
+  res = ExecutionResult("results/output.xml")
+  s = res.statistics.total
+  print("passed", s.passed, "failed", s.failed, "skipped", s.skipped)
+  class Failed(ResultVisitor):
+      def visit_test(self, test):
+          if test.status == "FAIL":
+              print(test.full_name, "|", test.message.splitlines()[0] if test.message else "", "|", test.elapsed_time)
+  res.visit(Failed())
+  for t in res.suite.all_tests:               # every test: name, status, tags, elapsed
+      print(t.name, t.status, list(t.tags), t.elapsed_time.total_seconds())
+  PY
+  Keyword level: walk test.body (kw.name, kw.status, kw.args, kw.message, kw.elapsed_time; nested kw.body).
+  Merge/re-report: rebot --merge -d merged a/output.xml b/output.xml ; rebot --output NONE --log log2.html output.xml

rf_harness/_assets/skills/rf-harness/references/selenium.md

@@ -0,0 +1,40 @@
+# SeleniumLibrary: locators and frames
+
+SELENIUMLIBRARY -- LOCATORS AND FRAMES
+
+VERIFIED CORE:
+- Strategies: id:x / name:x / css:x / xpath:x / link:Text / partial link:Te (= works too: id=x).
+  A bare value matches id or name only; bare `//...` is xpath.
+- IFRAMES: Select Frame    id:frame-id   ...   Unselect Frame   (no >>> in SeleniumLibrary).
+- SHADOW DOM: not pierced by css/xpath; use Browser library, or Execute Javascript returning the element.
+- Selenium is not strict: with several matches it silently uses the FIRST one.
+
+--- selenium locator reference ---
+locator_strategies:
+  id: Element id (e.g., 'id:example')
+  name: name attribute (e.g., 'name:example')
+  identifier: Either id or name (e.g., 'identifier:example')
+  class: Element class (e.g., 'class:example')
+  tag: Tag name (e.g., 'tag:div')
+  xpath: XPath expression (e.g., 'xpath://div[@id="example"]')
+  css: CSS selector (e.g., 'css:div#example')
+  dom: DOM expression (e.g., 'dom:document.images[5]')
+  link: Exact text a link has (e.g., 'link:The example')
+  partial link: Partial link text (e.g., 'partial link:he ex')
+  sizzle: Sizzle selector deprecated (e.g., 'sizzle:div.example')
+  data: Element data-* attribute (e.g., 'data:id:my_id')
+  jquery: jQuery expression (e.g., 'jquery:div.example')
+  default: Keyword specific default behavior (e.g., 'default:example')
+common_examples:
+  By ID: id:my-button
+  By Name: name:firstname
+  By CSS: css:#submit-btn
+  By XPath: xpath://input[@type='submit']
+  By Class: class:button-primary
+  By Link Text: link:Click Here
+tips:
+  - For form elements, 'name:fieldname' is often most reliable
+  - CSS selectors use 'css:' prefix, not just the selector
+  - XPath expressions must start with 'xpath:' prefix
+  - Use 'identifier:' to match either id or name attributes
+  - For buttons/links, try 'link:' for exact text matching

rf_harness/_assets/skills/rf-harness/references/waits.md

@@ -0,0 +1,28 @@
+# Waits and timeouts
+
+WAITS AND TIMEOUTS   (verified on Browser 19.12 and 20.5)
+
+Browser library:
+- Element keywords (Click, Fill Text, Get Text ...) auto-wait for the ELEMENT (attached, visible, enabled) up to
+  the browser timeout (default 10 s; Set Browser Timeout    20s).
+- VALUES do not wait: a getter WITHOUT an assertion operator returns the current value at once
+      ${t}=    Get Text    id=status          -> "Loading..."      ${n}=    Get Element Count    css=.row    -> 0
+- A getter WITH an assertion operator retries only `retry_assertions_for` = 1 s by default (not 10 s!):
+      Get Text    id=status    ==    Done          Get Element Count    css=.row    >=    3
+- Slower async UI (spinner, search results, toast) -> wait with the full timeout:
+      Wait For Condition    Text    id=status    contains    Done    timeout=15s
+      Wait For Condition    Element Count    css=.row    ==    3
+      Wait For Elements State    id=spinner    hidden    timeout=15s
+      Wait For Elements State    css=.row >> nth=2    visible    timeout=15s
+  or raise the retry for the suite/test: Set Retry Assertions For    10s   (Library    Browser    retry_assertions_for=10s)
+- After navigation: Get Url    contains    /home   or   Wait For Load State    networkidle
+- Do NOT add Sleep; use a condition/state wait instead.
+SeleniumLibrary: Wait Until Element Is Visible    id:x    10s ; Wait Until Page Contains    text ;
+                 Set Selenium Timeout    10s ; Set Selenium Implicit Wait (avoid mixing with explicit waits).
+BuiltIn: Wait Until Keyword Succeeds    10s    1s    <keyword>    <args>
+Hook runs (live session only -- never in your files or the plain robot run): element actions/getters use a SHORT
+timeout (2.5 s; navigation and Wait* keywords keep the normal one). A not-found / not-visible / timeout failure is
+re-checked ONCE with the normal timeout: "recheck: SLOW -- appeared after N s" -> the element is just slow: add
+`Wait For Elements State    <sel>    visible    timeout=10s` before the line (the hook already re-ran it);
+"recheck: MISSING" -> wrong selector / iframe / hidden element (.rf/state/latest/controls.txt).
+A line that runs longer than the hook budget is reported as "still running"; its result comes with your next edit.

rf_harness/_assets/variants/codex/hooks.json

@@ -0,0 +1,72 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" SessionStart --agent codex",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" UserPromptSubmit --agent codex",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" PreToolUse --agent codex",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "apply_patch|Edit|Write|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" PostToolUse --agent codex",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" Stop --agent codex",
+            "timeout": 90
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" SessionEnd --agent codex",
+            "timeout": 3
+          }
+        ]
+      }
+    ]
+  }
+}