explorbot 0.0.1

package/dist/prompts/audit-rules.md

@@ -0,0 +1,124 @@
+# Prompt Audit System for Web Navigation/Testing Rules
+
+You are an expert prompt engineer specializing in AI-driven web testing automation. Your task is to audit the prompts and rules used for web navigation and testing in this codebase.
+
+## Files to Analyze
+
+1. **`@src/ai/rules.ts`** - Core rules and guidelines for locators, actions, and verification
+2. **`@src/ai/navigator.ts`** - Uses rules in prompts for navigation and verification
+3. **`@src/ai/tools.ts`** - Tool definitions that include locator rules and guidance
+
+## Audit Checklist
+
+### 1. Rules Analysis (`rules.ts`)
+
+Look for:
+- **Contradictions**: Rules that conflict with each other (e.g., "prefer ARIA" vs "use text first")
+- **Ambiguity**: Vague guidance that could be interpreted multiple ways
+- **Incomplete guidance**: Missing priority order, missing edge cases
+- **Locator priority**: Is ARIA → Text → CSS → XPath clearly defined?
+- **Disambiguation**: How to choose between multiple matching elements?
+- **Context parameter**: When and how to use it?
+- **Short vs Long locators**: Clear definitions?
+- **Unused rules**: Exported but never imported anywhere
+
+### 2. Rule Usage Analysis (`navigator.ts`)
+
+Check:
+- **Imported but unused**: Rules imported but not used in prompts
+- **Missing rules**: Prompts that should include locatorRule or actionRule but don't
+- **Duplication**: Inline rules that duplicate what's in rules.ts
+- **Consistency**: Do prompts follow the same structure?
+- **HTML tags**: Is HTML content wrapped in `<page_html>` tags?
+
+### 3. Tools Analysis (`tools.ts`)
+
+Verify:
+- **locatorRule usage**: Do tools that accept locators include locatorRule?
+- **Input schema descriptions**: Do they mention "ARIA, CSS or XPath"?
+- **Suggestions on failure**: Do failed results provide helpful suggestions?
+- **Unreachable code paths**: Logic that can never execute (like type with undefined locator)
+- **Consistent error handling**: Same pattern across all tools
+- **Tool differentiation**: Clear when to use click vs clickByText, type with/without locator
+
+## Severity Levels
+
+| Severity | Description | Examples |
+|----------|-------------|----------|
+| **🔴 Critical** | Breaks functionality or causes wrong behavior | Contradictory rules, unreachable code, missing required rules |
+| **🟠 High** | Significant confusion or incorrect guidance | Ambiguous priority, misleading examples, wrong format |
+| **🟡 Medium** | Suboptimal but functional | Redundant rules, verbose descriptions, missing suggestions |
+| **🟢 Minor** | Cosmetic or style issues | Typos, formatting, inconsistent spacing |
+
+## Output Format
+
+Structure your findings as follows:
+
+```markdown
+## Audit Results
+
+### Critical Issues 🔴
+1. **[File:Line]** Issue description
+   - Impact: What goes wrong
+   - Fix: Suggested resolution
+
+### High Priority Issues 🟠
+1. **[File:Line]** Issue description
+   - Impact: What confusion this causes
+   - Fix: Suggested resolution
+
+### Medium Priority Issues 🟡
+1. **[File:Line]** Issue description
+   - Impact: Why this matters
+   - Fix: Suggested resolution
+
+### Minor Issues 🟢
+1. **[File:Line]** Issue description
+   - Fix: Suggested resolution
+
+### Observations
+- General patterns noticed
+- Recommendations for improvement
+- Questions for clarification
+```
+
+## Specific Things to Check
+
+### Locator Rules
+- [ ] Priority order clearly defined (ARIA → Text → CSS → XPath)
+- [ ] Context parameter explained (when to use, which tools support it)
+- [ ] Disambiguation strategy documented (form flow, ARIA state, proximity)
+- [ ] Short vs Long locators defined
+- [ ] Examples consistent with rules (single quotes vs double quotes in JSON)
+
+### Action Rules
+- [ ] Function signatures included (I.click, I.fillField, I.see, etc.)
+- [ ] Required parameters explained (context for I.see)
+- [ ] Prohibited actions listed (no wait functions, no amOnPage)
+- [ ] Examples match documented format
+
+### Verification Rules
+- [ ] I.see requires context parameter
+- [ ] I.seeElement prefers ARIA locators
+- [ ] Strictness rules to avoid false positives
+- [ ] Examples show correct usage
+
+### Tool Definitions
+- [ ] Each tool includes relevant rules (locatorRule where needed)
+- [ ] Input schemas describe all locator types
+- [ ] Failed results include actionable suggestions
+- [ ] Description explains when to use this tool vs alternatives
+
+## Run This Audit
+
+To run this audit, execute:
+
+```
+Please analyze the following files for prompt/rule issues:
+@src/ai/rules.ts
+@src/ai/navigator.ts  
+@src/ai/tools.ts
+
+Follow the audit checklist and output format defined in @prompts/audit-rules.md
+```
+

package/dist/rules/chief/general.md

@@ -0,0 +1,11 @@
+- Each scenario must be a complete, independent test
+- Steps should specify exact HTTP methods, paths, and key payload details
+- Expected outcomes should be specific and verifiable (status codes, response fields, error messages)
+- For CRUD operations, each test should handle its own setup and teardown
+- Expect standard REST conventions: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, 422 Unprocessable Entity
+- NEVER propose scenarios that test the same thing. "Create a basic suite" and "Successful creation of a simple suite" are DUPLICATES. Each scenario must test a DISTINCT behavior or aspect.
+- Before finalizing, review all scenarios and remove any that overlap in what they actually verify.
+
+API Usage Notes:
+
+- String is usually compatible with other data formats such as numbers or datetime, so do not check if number type strictly matches to number as it can be string too

package/dist/rules/chief/styles/curious.md

@@ -0,0 +1,12 @@
+Maximize coverage by using every field and endpoint the API offers.
+
+Focus on:
+- Full payload create: POST with ALL optional and required fields populated, verify every field was saved
+- Field-by-field update: PATCH/PUT each field individually, verify the change persists via GET
+- Mixed combinations: create with some optional fields set and others omitted, then update the missing ones
+- Array fields: send multiple items in arrays, not just one — verify all items are stored
+- Enum fields: try every valid enum value, verify each is accepted and returned correctly
+- Related fields: if spec shows related IDs or nested objects, populate them all
+- All endpoints: exercise every available endpoint for the resource, not just the main CRUD
+- Multiple resources: create several items, list them, verify count and content
+- Default values: omit optional fields on create, then GET to see what defaults the API assigns

package/dist/rules/chief/styles/hacker.md

@@ -0,0 +1,19 @@
+Analyze the request log and API spec to discover hidden endpoints, undocumented properties, and unprotected actions — then try to exploit them.
+
+Study previous responses carefully:
+- Look at response field names and values — guess related endpoints and properties not in the spec
+- If a response contains fields like "user_id", "org_id", "role" — try sending them on create/update to see if it is possible to self-promote
+- If responses include URLs or paths — follow them, they may reveal internal routes
+- Guess hidden endpoints by looking at response fields
+- If IDs are sequential — try adjacent IDs to access other users' resources
+- Try to create tests with custom ID values to see if they are accepted
+- If a response shows more fields than the spec defines — those extra fields are attack surface
+
+Use schemaFor to discover related endpoints, then try HTTP methods the spec doesn't list for them.
+Derive endpoint patterns from what you've seen — if /items exists, try /items/export, /items/bulk, /items/search.
+Send fields from GET responses back in POST/PUT — check which ones the server silently accepts.
+Try overriding read-only or server-computed fields you observed in responses.
+Strip or corrupt auth headers on sensitive operations to test enforcement.
+
+Every unexpected finding must be recorded immediately.
+Unclosed hidden exploits must be recorded as a failure.

package/dist/rules/chief/styles/normal.md

@@ -0,0 +1,11 @@
+Focus on standard CRUD operations and happy-path flows.
+
+Test each HTTP method the endpoint supports:
+- POST: Create a new resource with valid data, verify 201 and response body
+- PUT/PATCH: Update the resource, verify changes persist
+- DELETE: Remove the resource, verify 204/200 and subsequent GET returns 404
+- GET: obtain data, list by filters, by search
+
+Validate response schemas match expected structure.
+Check that required fields are present in responses.
+Verify correct HTTP status codes for each operation.

package/dist/rules/chief/styles/psycho.md

@@ -0,0 +1,17 @@
+Stress-test the endpoint with invalid, malformed, and extreme inputs.
+
+Focus on:
+
+- Missing required fields: send partial payloads, empty objects, empty body
+- Malformed JSON: trailing commas, unquoted keys, broken UTF-8
+- SQL injection
+- XSS payloads
+- Exposed secrets: passwords, tokens, etc
+- Wrong Content-Type: send form data as JSON, JSON as XML
+- Invalid HTTP methods: PATCH on POST-only endpoints
+- Boundary values: negative numbers, zero, MAX_INT, empty arrays, null values
+- Date fields: set creation date in future, and expiring date to past
+
+Expect proper responses with meaningful error messages if related.
+If server strips broken data it is ok
+Responses must be carefully validated to contain correct and secure data

package/dist/rules/navigator/multiple-locator.md

@@ -0,0 +1,47 @@
+You will need to provide multiple solutions to achieve the result.
+
+<short_vs_long_locators>
+Short locators = minimal selector that uniquely identifies the element
+- ARIA and Text locators are always short: { "role": "button", "text": "Submit" }, 'Login'
+- Short CSS: #email, [data-testid="submit"]
+
+Long locators = add ancestor context for resilience
+- CSS with ancestors: form#login #email, .modal .form input[name="email"]
+- XPath with path: //form[@id="login"]//input[@name="email"]
+- Full path to body (lowest priority): //html/body//div[@id="app"]//form//input[@name="email"]
+</short_vs_long_locators>
+
+When container is available, text + container is simplest and preferred over complex locators.
+
+Start with short locators (ARIA/Text first), then progressively try longer CSS/XPath.
+Long locators with full path are lowest priority but should still be tried as fallback.
+
+Be specific about locators, check if multiple elements can be selected by the same locator.
+Each new solution should add ancestor context, stepping up the hierarchy.
+When suggesting XPath, do not repeat the same CSS locator and vice versa.
+
+Do not include comments into code blocks.
+
+<bad_locator_example>
+Suggestion 1:
+#user_email
+
+Suggestion 2: (is the same as suggestion 1)
+//*[@id="user_email"]
+</bad_locator_example>
+
+<good_locator_example>
+  Suggestion 1 (short - ARIA):
+  { "role": "textbox", "text": "Email" }
+
+  Suggestion 2 (short - CSS):
+  #user_email
+
+  Suggestion 3 (long - CSS with ancestor):
+  #user_form #user_email
+
+  Suggestion 4 (long - XPath with full path):
+  //html/body//form[@id="user_form"]//input[@id="user_email"]
+</good_locator_example>
+
+Solutions should be different, do not repeat the same locator in different solutions.

package/dist/rules/navigator/output.md

@@ -0,0 +1,69 @@
+<rules>
+Do not invent locators, focus only on locators from HTML PAGE.
+Provide up to {{maxAttempts}} various code suggestions to achieve the result.
+If there was already successful solution in <experience> use it as a first solution.
+
+If no successful solution was found in <experience> propose codeblocks for each area that can help to achieve the result.
+Do not stick only to the first found element as it might be hidden or not availble on the page.
+If you think HTML contains several areas that can help to achieve the result, propose codeblocks for each such area.
+Use exact locators that can pick the elements from each areas.
+Detect such duplicated areas by looking for duplicate IDs, data-ids, forms, etc.
+
+In <explanation> write only one line without heading or bullet list or any other formatting.
+Check previous solutions, if there is already successful solution, use it!
+CodeceptJS code must start with "I."
+All lines of code must be CodeceptJS code and start with "I."
+</rules>
+
+<output>
+Your response must start explanation of what you are going to do to achive the result
+It is important to explain intention before proposing code.
+Response must also valid CodeceptJS code in code blocks.
+Propose codeblock from successful solutions in <experience> first if they exist.
+Use only locators from HTML PAGE that was passed in <page> context.
+</output>
+
+
+<output_format>
+  <explanation>
+
+  ```js
+  <code>
+  ```
+  </code>
+  <code>
+  ```
+  </code>
+  <code>
+  ```
+  </code>
+</output_format>
+
+<example_output>
+Trying to fill the form on the page
+
+```js
+  I.fillField('Name', 'Value');
+  I.click('Submit');
+```
+
+```js
+  I.fillField('//form/input[@name="name"]', 'Value');
+```
+
+```js
+  I.fillField('#app .form input[name="name"]', 'Value');
+```
+
+```js
+  I.fillField('/html/body/div/div/div/form/input[@name="name"]', 'Value');
+```
+</example_output>
+
+If you don't know the answer, answer as:
+
+<example_output>
+```js
+  throw new Error('No resolution');
+```
+</example_output>

package/dist/rules/navigator/verification-actions.md

@@ -0,0 +1,122 @@
+<actions>
+### I.see
+
+I.see(<text>, <context>)
+
+Checks that text is visible inside a specific element.
+Context parameter is REQUIRED - never use I.see without context.
+
+<example>
+  I.see('Welcome', '.message');
+  I.see('Welcome', '#header');
+  I.see('Success', '.notification');
+</example>
+
+### I.seeElement
+
+I.seeElement(<locator>)
+
+Checks that element is present on the page.
+Prefer ARIA locators for reliable element detection.
+
+<example>
+  I.seeElement({"role":"button","text":"Submit"});
+  I.seeElement({"role":"alert","text":"Success"});
+  I.seeElement('#submit-button');
+  I.seeElement('.success-message');
+</example>
+
+### I.seeInField
+
+I.seeInField(<locator>, <value>, <context>)
+
+Checks that an input field contains the expected value.
+Use for verifying text inputs, search fields, textareas, and any form field values.
+This is the ONLY reliable way to check input values — do NOT use I.seeElement with [value=...] or I.seeInSource.
+
+<example>
+  I.seeInField('Email', 'john@example.com', '.profile-form');
+  I.seeInField('Search', 'nightwatch');
+  I.seeInField('input[name="search"]', 'test query');
+</example>
+
+### I.seeInTitle
+
+I.seeInTitle(<text>)
+
+Checks that page title contains expected text.
+
+<example>
+  I.seeInTitle('Dashboard');
+</example>
+
+### I.seeInSource
+
+I.seeInSource(<text>)
+
+Checks that page source contains expected text (including hidden elements).
+
+<example>
+  I.seeInSource('<div class="hidden">');
+</example>
+
+### I.dontSee
+
+I.dontSee(<text>, <context>)
+
+Checks that text is NOT visible inside a specific element.
+Context parameter is REQUIRED - never use I.dontSee without context.
+
+<example>
+  I.dontSee('Error', '.alert');
+  I.dontSee('Failed', '.status');
+</example>
+
+### I.dontSeeElement
+
+I.dontSeeElement(<locator>)
+
+Checks that element is NOT present on the page.
+
+<example>
+  I.dontSeeElement('#error-message');
+  I.dontSeeElement({"role":"alert","text":"Error"});
+</example>
+
+### I.dontSeeInField
+
+I.dontSeeInField(<locator>, <value>, <context>)
+
+Checks that an input field does NOT contain the specified value.
+
+<example>
+  I.dontSeeInField('Password', '', '.login-form');
+  I.dontSeeInField('Search', 'old query');
+  I.dontSeeInField('Email', '');
+</example>
+
+### I.dontSeeInSource
+
+I.dontSeeInSource(<text>)
+
+Checks that page source does NOT contain expected text.
+
+<example>
+  I.dontSeeInSource('error-class');
+</example>
+
+<verification_rules>
+Be strict in assertions to avoid false positives.
+Prefer I.seeElement() with ARIA locators - most reliable.
+I.see() and I.dontSee() MUST include context parameter.
+For input field values, ALWAYS use I.seeInField() — never check value via CSS attribute selectors or I.seeInSource.
+Prefer text locators (label, name, placeholder) for form fields: I.seeInField('Search', 'value') over I.seeInField('input[name="search"]', 'value').
+Only use locators that exist in the provided HTML or ARIA snapshot.
+Verify exact conditions, not approximate matches.
+</verification_rules>
+
+[DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]
+[INTERACT ONLY WITH ELEMENTS THAT ARE ON THE PAGE HTML OR ARIA SNAPSHOT]
+[DO NOT USE WAIT FUNCTIONS]
+
+</actions>

package/dist/rules/navigator/verification-output.md

@@ -0,0 +1,53 @@
+<rules>
+Do not invent locators, focus only on locators from HTML PAGE.
+Provide up to {{maxAttempts}} various code suggestions to verify the assertion.
+If there was already successful solution in <experience> use it as a first solution.
+
+Propose codeblocks with different locator strategies to verify the same assertion.
+Use exact locators from the HTML page.
+
+In <explanation> write only one line without heading or bullet list or any other formatting.
+CodeceptJS code must start with "I."
+</rules>
+
+<output>
+Your response must start with explanation of what assertion you are going to verify.
+It is important to explain intention before proposing code.
+Response must contain valid CodeceptJS verification code in code blocks.
+Use only locators from HTML PAGE that was passed in <page> context.
+</output>
+
+<output_format>
+  <explanation>
+
+  ```js
+  <code>
+  ```
+  </code>
+  <code>
+  ```
+  </code>
+  <code>
+  ```
+  </code>
+</output_format>
+
+<example_output>
+Verifying that welcome message is visible on the page
+
+```js
+  I.seeElement({"role":"heading","text":"Welcome"});
+```
+
+```js
+  I.see('Welcome', '.message');
+```
+
+```js
+  I.see('Welcome', '#welcome-container');
+```
+
+```js
+  I.seeElement('.welcome-message');
+```
+</example_output>

package/dist/rules/planner/styles/curious.md

@@ -0,0 +1,39 @@
+Detect new valid paths that previous tests missed. Prioritize mining experience and research together before inventing abstract scenarios.
+
+When <previously_tested_flows> is present, treat it as the ground truth for what already worked:
+- List items under Successful Flow describe the path that was executed
+- Lines in blockquotes (lines starting with >) are discoveries: extra fields, side panels, conditional UI, inputs called out during that run
+Infer what was never tried or only partially exercised from that material.
+DO NOT re-propose these flows or reword them into new scenarios. They are already covered.
+Instead, use the discoveries (lines starting with >) as leads for NEW tests around elements that were revealed but never interacted with.
+
+When <previously_tested_flows> is NOT present, use <tested_scenarios> as the ground truth instead.
+Read the step lines for each test to understand which controls were actually interacted with.
+Identify elements from <page_research> that appear in NO test steps — these are coverage gaps.
+
+Cross-read with <page_research>: for each form and Extended Research subsection, compare against those flows. Which text inputs, selects, checkboxes, toggles, and side controls were skipped or touched once with a single value? Prefer filling those gaps over repeating the same path.
+
+The Type column in <page_research> tables shows the ARIA role of each element.
+Cross-reference these types with the steps listed in <tested_scenarios> or <previously_tested_flows>:
+
+Coverage gaps to look for:
+- Input controls (textbox, textarea, spinbutton) that were never filled, or only filled with one kind of value
+- Selection controls (combobox, listbox, radio group) where only one option was ever chosen
+- Toggle controls (checkbox, switch) that were never toggled, or only tested in one state
+- Expandable sections, disclosure widgets, accordions that were never opened
+- Action buttons that were never clicked as part of a complete workflow
+- Dependent UI: controls that appear or change based on another control's value
+
+When proposing tests for forms, prefer filling ALL visible fields — not just required ones.
+Vary input strategies: try short values, multi-word values, edge-of-valid values.
+When a form has sections, tabs, or conditional panels, propose tests that exercise each section.
+If a control has downstream effects (e.g., selecting a type reveals extra fields), build a test around that interaction chain.
+
+Combinatorial coverage (valid data only):
+- For each select or equivalent, ensure each option is exercised in at least one scenario, or one scenario whose steps walk through distinct options in sequence if that fits the task constraints better
+- Exercise each checkbox or binary control in both states when behavior can differ
+- Combine checkboxes and related toggles in small sets (pairs or triples) when they plausibly change validation, visible sections, or outcomes — avoid exploding into huge Cartesian products
+
+When heavy forms are not the focus, still pursue: unvisited state transitions, follow-ups after creates (share, export, duplicate), alternative routes to the same goal, preconditions that unlock UI, and visible controls never clicked.
+
+Skip the Menu/Navigation section — we are testing THIS page.

package/dist/rules/planner/styles/normal.md

@@ -0,0 +1,21 @@
+Study the page and figure out its business purpose. What is this page FOR? What would a user come here to do?
+
+Based on the page type, propose tests for COMPLETE user workflows:
+- If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
+- If this is a form page: test full submission flow, not just "form appears"
+- If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
+- If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them
+
+Each test should end with the application in a different state than it started.
+
+IMPORTANT: Distribute tests across DIFFERENT feature areas from the research.
+Do not propose more than 2 tests for the same feature area.
+Every Extended Research section (modal, dropdown, panel) with actionable features deserves at least one test.
+Tests that change application data MUST come first — create, update, delete records before testing filters, search, or pagination. You are aiming to change application state.
+If the research shows multiple ways to create or modify data (different types, forms, or options), propose a separate test for each.
+View only tests (tab switching, pagination, view toggles) should be proposed only after  data-changing interactions are covered.
+
+Skip the Menu/Navigation section — we are testing THIS page.
+
+When <previously_tested_flows> is present, review the successful flows and consider re-testing important ones for regression coverage. Previously tested flows that are not in the current plan are candidates for re-testing.
+Propose variations with different inputs or edge cases when re-testing a known flow.

package/dist/rules/planner/styles/psycho.md

@@ -0,0 +1,14 @@
+Stress-test the page by filling invalid, empty, and extreme values into every input.
+
+Focus on:
+- Empty states: submit forms with no data, clear required fields, remove default values
+- Long values: paste 10000 characters into inputs, use extremely long names and descriptions
+- Boundary values: zero, negative numbers, special characters, unicode, HTML tags in text fields
+- Invalid formats: wrong email formats, letters in number fields, SQL injection strings, script tags
+- Invalid combinations: select incompatible options, mix conflicting settings
+- Combining states: apply multiple filters at once, use conflicting form values together
+- Out-of-range values: dates in the past/future, quantities beyond limits, prices with too many decimals
+
+Push every input to its limits. Find what breaks when the form receives unexpected data.
+
+Skip the Menu/Navigation section — we are testing THIS page.

package/dist/rules/researcher/list-element.md

@@ -0,0 +1,11 @@
+<list_element_indexing>
+When multiple elements share the same structure (e.g., list items, tabs, table rows, menu links):
+Each element MUST have a UNIQUE CSS selector.
+
+CSS — use :has-text("text") to disambiguate by visible text content:
+  a.filter-tab:has-text("Manual"), a.filter-tab:has-text("Automated")
+  a.node-link:has-text("IMR_API_Tests"), a.node-link:has-text("IMR_UI_Tests")
+
+NEVER leave multiple elements with identical CSS selectors in the same section.
+Every row in the UI map table must have selectors that match exactly ONE element.
+</list_element_indexing>

package/dist/rules/researcher/screenshot-ui-map.md

@@ -0,0 +1,30 @@
+<ui_map_rule>
+List UI elements as a markdown table WITH Coordinates, Color, and Icon columns:
+| Element | ARIA | CSS | Coordinates | Color | Icon |
+| 'Save' | { role: 'button', text: 'Save' } | 'button.save' | (400, 300) | green | - |
+| 'Delete' | { role: 'button', text: 'Delete' } | 'button.delete' | (500, 300) | red | trash |
+| 'Settings dropdown' | { role: 'button', text: 'Settings' } | 'button.settings' | (500, 100) | - | down-chevron |
+| 'Menu toggle' | - | 'button.hamburger' | (30, 25) | - | hamburger |
+| 'Add item' | { role: 'button', text: 'Add' } | 'button.add' | (200, 50) | blue | plus |
+| 'Close' | { role: 'button', text: 'Close' } | 'button.close' | (600, 10) | - | x |
+
+- ARIA: Valid JSON with role and text keys (NOT "name"): { role: 'button', text: 'Save' }
+  * For icon buttons: use aria-label or title attribute value as text
+  * If no accessible name exists: use "-" and rely on CSS
+  * NEVER use empty text like { role: 'button', text: '' }
+- CSS: Relative to section container, must be unique within section
+- Coordinates: (X, Y) center point when visible on screenshot, "-" when not found
+- Color: accent color ONLY if the element has a distinctive color that differs from the default/majority
+  * Use ONLY simple color words: red, green, blue, orange, yellow, purple, gray, white, black
+  * NEVER use hex codes (#ff0000), RGB values, or CSS color functions
+  * red = danger/delete, green = success/confirm, blue = primary, orange = warning
+  * Use "-" when element has no distinctive accent color (same color as other elements)
+  * Most elements should be "-" — only highlight elements that stand out visually
+- Icon: one-word description of the visual icon on the element, "-" if no icon
+  * For directional icons use direction + shape: down-chevron, down-arrow, right-caret, up-arrow
+  * Common icons: plus, x, trash, pencil, gear, search, hamburger, ellipsis, star, check, filter
+  * Use "-" for text-only elements with no icon
+
+IMPORTANT: Each section must have a blockquote container before the table: > Container: '.css-selector'
+CRITICAL: Coordinates, Color, and Icon columns must be IN the table, NOT in a separate section.
+</ui_map_rule>

package/dist/rules/researcher/section-ui-map.md

@@ -0,0 +1,18 @@
+<ui_map_rule>
+List UI elements as a markdown table:
+| Element | ARIA | CSS |
+| 'Save' | { role: 'button', text: 'Save' } | 'button.save' |
+| 'Close icon' | { role: 'button', text: 'Close' } | 'button.close-btn' |
+| 'Menu toggle' | - | 'button.hamburger' |
+
+Always include ARIA + CSS for each element.
+
+- ARIA: Valid JSON with role and text keys (NOT "name"): { role: 'button', text: 'Save' }
+  * For icon buttons: use aria-label or title attribute value as text
+  * If no accessible name exists: use "-" and rely on CSS
+  * NEVER use empty text like { role: 'button', text: '' }
+- CSS: Relative to section container, must be unique within section
+
+IMPORTANT: Each section must have a blockquote container before the table: > Container: '.css-selector'
+This container is critical for disambiguation when interacting with elements.
+</ui_map_rule>

package/dist/rules/researcher/ui-map-table.md

@@ -0,0 +1,18 @@
+<ui_map_table_format>
+ALWAYS use this exact table format for UI elements:
+
+| Element | ARIA | CSS | eidx |
+|---------|------|-----|------|
+| 'Save' | { role: 'button', text: 'Save' } | 'button.save' | 5 |
+
+Column definitions:
+- Element: Human-readable name of the element
+- ARIA: JSON format { role: '...', text: '...' } - use "text" key, NOT "name"
+- CSS: Unique CSS selector (relative to section container)
+- eidx: Value of the eidx attribute from the HTML element. Use "-" if not present.
+
+IMPORTANT: Each section must have a blockquote container before the table: > Container: '.css-selector'
+This container is used for disambiguation when clicking elements.
+
+NEVER use different column layouts. This format is required for all UI maps.
+</ui_map_table_format>