opendevbrowser 0.0.12 → 0.0.15

package/skills/AGENTS.md

@@ -1,36 +1,25 @@
-# Local AGENTS.md (skills/)
+# skills/ — Agent Guidelines
 
-Applies to `skills/` and subdirectories. Extends root `AGENTS.md`.
+Bundled skill packs. Extends root `AGENTS.md`.
 
-## Skill Pack Architecture
-- Each skill pack lives in its own folder with `SKILL.md` as the entry point.
-- `opendevbrowser-best-practices` is the canonical prompting guide source.
-- OpenCode-native discovery is primary:
-  - Project-local: `.opencode/skill/*/SKILL.md`
-  - Global: `~/.config/opencode/skill/*/SKILL.md`
-- Compatibility-only paths: `.claude/skills/*/SKILL.md`, `~/.claude/skills/*/SKILL.md`
-- `opendevbrowser_skill_list/load` are compatibility wrappers; OpenCode `skill` is primary.
+## Structure
 
-## Skill Pack Rules
-- `skills/opendevbrowser-best-practices/SKILL.md` is the source for prompting guide output.
-- Keep guidance short, script-first, and snapshot-first.
-- Keep examples aligned with `opendevbrowser_*` tool names.
-- Do not include secrets or captured page data in skill content.
-- If adding a consolidated skill pack, update `docs/REFACTORING_PLAN.md` and `docs/CLI.md`.
-
-## Skill Format Specification
+```
+skills/
+├── opendevbrowser-best-practices/SKILL.md   # Core prompting guide
+├── opendevbrowser-continuity-ledger/SKILL.md
+├── login-automation/SKILL.md
+├── form-testing/SKILL.md
+└── data-extraction/SKILL.md
+```
 
-### Naming Conventions (OpenCode alignment)
-- Skill names: lowercase, hyphens only, 1-64 characters
-- Directory name must match skill name in frontmatter
-- Examples: `login-automation`, `form-testing`, `data-extraction`
+## SKILL.md Format
 
-### SKILL.md Structure
 ```markdown
 ---
-name: skill-name
-description: Brief description (1-1024 chars)
-version: 1.0.0
+name: skill-name          # lowercase, hyphens, 1-64 chars
+description: Brief desc   # 1-1024 chars
+version: 1.0.0           # optional, defaults to 1.0.0
 ---
 
 # Skill Title
@@ -39,43 +28,26 @@ version: 1.0.0
 Content organized by topic for filtering.
 ```
 
-### Required Frontmatter
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | Yes | Skill identifier (lowercase, hyphens) |
-| `description` | Yes | Brief description for listing |
-| `version` | No | Semantic version (defaults to 1.0.0) |
+## Discovery Priority
 
-## Available Skills
+1. `.opencode/skill/` (project-local)
+2. `~/.config/opencode/skill/` (global)
+3. `.claude/skills/` (compatibility)
+4. `~/.claude/skills/` (compatibility)
+5. `skillPaths` config (custom)
 
-| Skill | Purpose |
-|-------|---------|
-| `opendevbrowser-best-practices` | Core prompting guide for browser automation |
-| `opendevbrowser-continuity-ledger` | Continuity ledger guidance for long-running tasks |
-| `login-automation` | Authentication and credential handling |
-| `form-testing` | Form validation and submission testing |
-| `data-extraction` | Table extraction and pagination handling |
+## Constraints
 
-## Custom Skill Paths
-Advanced: users can add custom search paths via `skillPaths` in `opendevbrowser.jsonc`:
-```jsonc
-{
-  "skillPaths": ["~/.config/opencode/opendevbrowser-skills"]
-}
-```
+- Directory name must match `name` in frontmatter
+- Keep guidance short, script-first, snapshot-first
+- Examples must use `opendevbrowser_*` tool names
+- Never include secrets or page data in content
+- Match the snapshot → refs → actions flow in `docs/ARCHITECTURE.md` and tool list in `docs/CLI.md`.
+- Note that extension relay requires Chrome 125+ and uses hub-only relay ownership when enabled.
+- Refer to root `AGENTS.md` for connection flag/status semantics (extensionConnected, handshake, cdpConnected, pairingRequired).
 
-## Folder Structure
-```
-skills/
-|-- opendevbrowser-best-practices/
-|   `-- SKILL.md
-|-- opendevbrowser-continuity-ledger/
-|   `-- SKILL.md
-|-- login-automation/
-|   `-- SKILL.md
-|-- form-testing/
-|   `-- SKILL.md
-|-- data-extraction/
-|   `-- SKILL.md
-`-- AGENTS.md
-```
+## Adding Skills
+
+1. Create `skills/<skill-name>/SKILL.md`
+2. Follow frontmatter format above
+3. Update `docs/CLI.md` if adding CLI-related guidance

package/skills/data-extraction/SKILL.md

@@ -1,136 +1,128 @@
 ---
 name: data-extraction
-description: Patterns for extracting structured data from web pages including tables, lists, and paginated content with OpenDevBrowser.
-version: 1.0.0
+description: This skill should be used when the user asks to "extract data from a page", "scrape tables", "collect paginated results", "parse list/card content", or "export structured web data" with OpenDevBrowser.
+version: 1.1.0
 ---
 
 # Data Extraction Skill
 
-## Table Extraction
+Use this guide to collect structured data from dynamic pages with predictable output quality.
+
+## Extraction Planning
+
+Define the schema before interacting:
 
-1. Navigate to page with data table:
-   ```
-   opendevbrowser_goto url="https://example.com/data"
-   ```
+1. Define output fields and required keys.
+2. Identify page regions that contain those fields.
+3. Capture a fresh snapshot and map refs to schema fields.
 
-2. Wait for table to load:
-   ```
-   opendevbrowser_wait state="networkidle"
-   ```
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+```
 
-3. Get table HTML structure:
-   ```
-   opendevbrowser_dom_get_html ref="[table-ref]"
-   ```
+## Table Extraction
 
-4. Parse the HTML to extract rows and cells.
+For semantic HTML tables:
 
-### Common Table Patterns
+1. Wait for table visibility.
+2. Snapshot and identify table/container refs.
+3. Extract targeted table HTML.
+4. Parse rows/cells in the host script.
 
-Standard HTML tables:
-```html
-<table>
-  <thead><tr><th>Header</th></tr></thead>
-  <tbody><tr><td>Data</td></tr></tbody>
-</table>
+```text
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_dom_get_html sessionId="<session-id>" ref="<table-ref>"
 ```
 
-CSS-based grids:
-```html
-<div class="grid">
-  <div class="row">
-    <div class="cell">Data</div>
-  </div>
-</div>
+For virtualized or grid UIs, extract per-row/card refs and normalize in post-processing.
+
+## List and Card Extraction
+
+For repeated list/card content:
+
+1. Snapshot and identify repeating item refs.
+2. Extract only needed nodes per item (`title`, `price`, `meta`, `url`).
+3. Normalize records to a stable schema.
+
+```text
+opendevbrowser_dom_get_text sessionId="<session-id>" ref="<item-title-ref>"
+opendevbrowser_get_attr sessionId="<session-id>" ref="<item-link-ref>" name="href"
 ```
 
-## List Extraction
-
-For unordered/ordered lists:
-1. Identify list container ref
-2. Extract text content:
-   ```
-   opendevbrowser_dom_get_text ref="[list-ref]"
-   ```
-
-For card-based layouts:
-1. Identify repeating pattern
-2. Extract each card's content individually
-
-## Pagination Handling
-
-### Numbered Pagination
-
-1. Extract current page data
-2. Find "Next" or page number button:
-   ```
-   opendevbrowser_snapshot
-   ```
-3. Click next page:
-   ```
-   opendevbrowser_click ref="[next-button-ref]"
-   ```
-4. Wait for new content:
-   ```
-   opendevbrowser_wait state="networkidle"
-   ```
-5. Repeat until no more pages
+## Pagination Patterns
+
+### Numbered or Next/Previous Pagination
+
+1. Extract current page records.
+2. Click next/page ref.
+3. Wait for load.
+4. Re-snapshot and continue until terminal state.
+
+```text
+opendevbrowser_click sessionId="<session-id>" ref="<next-ref>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+```
 
 ### Infinite Scroll
 
-1. Extract visible data
-2. Scroll to load more:
-   ```
-   opendevbrowser_scroll direction="down" amount=1000
-   ```
-3. Wait for new content
-4. Repeat until no new items appear
+1. Extract visible records.
+2. Scroll incrementally.
+3. Wait for newly loaded items.
+4. Stop when no new unique records appear.
+
+```text
+opendevbrowser_scroll sessionId="<session-id>" dy=1000
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+```
 
 ### Load More Button
 
-1. Extract visible data
-2. Click "Load More":
-   ```
-   opendevbrowser_click ref="[load-more-ref]"
-   ```
-3. Wait for new content
-4. Repeat until button disappears
+1. Extract visible records.
+2. Click load-more ref.
+3. Wait and re-snapshot.
+4. Repeat until button disappears or no new data arrives.
 
-## Data Export Workflow
+## Structured Data Shortcuts
 
-1. Collect all extracted data in structured format
-2. Use `opendevbrowser_run` to serialize data:
-   ```javascript
-   return JSON.stringify(collectedData, null, 2);
-   ```
+When available, prefer embedded structured data:
 
-## Handling Dynamic Content
+- JSON-LD scripts
+- Microdata attributes (`itemscope`, `itemprop`)
 
-For JavaScript-rendered content:
+```text
+opendevbrowser_dom_get_text sessionId="<session-id>" ref="<json-ld-script-ref>"
+```
 
-1. Wait for specific element to appear
-2. Use network polling to detect data loading:
-   ```
-   opendevbrowser_network_poll
-   ```
-3. Take snapshot after XHR/Fetch completes
+Parse JSON-LD in the host script and merge with extracted UI records if needed.
 
-## Structured Data Detection
+## Quality Controls
 
-Look for embedded structured data:
-- JSON-LD scripts: `<script type="application/ld+json">`
-- Microdata attributes: `itemscope`, `itemprop`
-- RDFa attributes: `typeof`, `property`
+Apply quality checks during extraction:
 
-Extract via:
-```
-opendevbrowser_run script="return document.querySelector('script[type=\"application/ld+json\"]')?.textContent"
+- Deduplicate by stable key (URL, ID, composite key).
+- Track page number and source URL per record.
+- Record null/missing fields explicitly.
+- Validate record counts per page before continuing.
+
+Use `opendevbrowser_network_poll` when extraction depends on API completion.
+
+```text
+opendevbrowser_network_poll sessionId="<session-id>" max=50
 ```
 
-## Rate Limiting Considerations
+## Export Pattern
+
+Perform export in the host environment (outside tool calls):
+
+- Normalize to JSON for structured pipelines.
+- Convert to CSV only after schema normalization.
+- Keep raw extraction artifacts when auditability is required.
+
+## Compliance and Rate Limits
+
+Follow site constraints:
 
-When extracting large datasets:
-- Add delays between page requests
-- Monitor for rate limit responses (429 status)
-- Respect robots.txt and terms of service
-- Consider using persistent profile to maintain session
+- Respect robots, terms, and legal boundaries.
+- Add pacing between page transitions when needed.
+- Stop on repeated 429/403 responses and apply cooldown/retry policy.

package/skills/form-testing/SKILL.md

@@ -1,113 +1,106 @@
 ---
 name: form-testing
-description: Comprehensive form testing patterns including validation, submission, and error handling with OpenDevBrowser.
-version: 1.0.0
+description: This skill should be used when the user asks to "test a form", "verify validation", "check submission behavior", "test multi-step forms", or "debug form errors" with OpenDevBrowser.
+version: 1.1.0
 ---
 
 # Form Testing Skill
 
-## Form Field Discovery
+Use this guide for comprehensive validation, submission, and error-state testing.
 
-1. Take a snapshot to map all form elements:
-   ```
-   opendevbrowser_snapshot
-   ```
+## Form Discovery Pass
 
-2. Identify field types:
-   - Text inputs: `<input type="text">`
-   - Email fields: `<input type="email">`
-   - Number fields: `<input type="number">`
-   - Select dropdowns: `<select>`
-   - Checkboxes: `<input type="checkbox">`
-   - Radio buttons: `<input type="radio">`
-   - Textareas: `<textarea>`
-   - File uploads: `<input type="file">`
+Start every form suite with structural discovery:
 
-3. Note required fields (often marked with `required` attribute or asterisk).
+1. Capture `actionables` snapshot.
+2. Map refs for each input, control, and submit button.
+3. Record required and optional fields.
+4. Record dependent/conditional fields.
 
-## Validation Testing
+```text
+opendevbrowser_snapshot sessionId="<session-id>" format="actionables"
+```
 
-Test each field's validation rules:
+## Validation Matrix
 
-### Required Fields
-1. Leave field empty
-2. Submit form
-3. Verify error message appears
+Build a deterministic matrix per field type:
 
-### Email Validation
-Test with:
-- Valid email: `user@example.com`
-- Missing @: `userexample.com`
-- Missing domain: `user@`
-- Invalid TLD: `user@example`
+| Category | Cases |
+|---|---|
+| Required | empty value, whitespace-only, valid value |
+| Email | valid format, missing `@`, missing domain |
+| Numeric | below min, above max, boundary values |
+| Length | below min length, exact bounds, above max length |
+| Pattern | valid regex match, invalid charset, malformed input |
+| Select/Radio | no selection, valid selection, invalid dependent state |
 
-### Length Constraints
-- Minimum length: Enter fewer characters than required
-- Maximum length: Enter more characters than allowed
-- Boundary values: Test exact min/max limits
+Re-snapshot after each invalid submit to capture updated error refs.
 
-### Pattern Matching
-For fields with regex patterns:
-- Valid pattern match
-- Invalid characters
-- Edge cases
+## Submission Workflow
 
-## Form Submission Workflow
+Run positive-path submission only after field validation is complete:
 
-1. Fill all required fields:
-   ```
-   opendevbrowser_type ref="[field-ref]" text="value"
-   ```
+1. Fill required fields.
+2. Set select/radio/checkbox controls.
+3. Verify submit button is enabled.
+4. Submit and wait for network/UI completion.
 
-2. For select dropdowns:
-   ```
-   opendevbrowser_select ref="[select-ref]" value="option-value"
-   ```
+```text
+opendevbrowser_type sessionId="<session-id>" ref="<text-ref>" text="valid value"
+opendevbrowser_select sessionId="<session-id>" ref="<select-ref>" values=["expected-option"]
+opendevbrowser_check sessionId="<session-id>" ref="<terms-ref>"
+opendevbrowser_is_enabled sessionId="<session-id>" ref="<submit-ref>"
+opendevbrowser_click sessionId="<session-id>" ref="<submit-ref>"
+opendevbrowser_wait sessionId="<session-id>" until="networkidle"
+```
 
-3. For checkboxes:
-   ```
-   opendevbrowser_click ref="[checkbox-ref]"
-   ```
+## Error-State Assertions
 
-4. Submit the form:
-   ```
-   opendevbrowser_click ref="[submit-ref]"
-   ```
+For invalid submissions, assert three dimensions:
 
-5. Wait for response:
-   ```
-   opendevbrowser_wait state="networkidle"
-   ```
+1. Error text is present and specific.
+2. Accessibility attributes are set correctly (for example `aria-invalid="true"`).
+3. Focus behavior moves to first invalid field when applicable.
 
-## Error Message Verification
+```text
+opendevbrowser_get_attr sessionId="<session-id>" ref="<field-ref>" name="aria-invalid"
+opendevbrowser_dom_get_text sessionId="<session-id>" ref="<error-ref>"
+```
 
-After invalid submission:
+## Multi-Step Form Pattern
 
-1. Take new snapshot to capture error state
-2. Look for error messages near each field
-3. Verify error text matches expected message
-4. Check ARIA attributes for accessibility
+For wizard-style forms:
 
-## Multi-Step Forms
+1. Validate and submit current step.
+2. Wait for next-step container ref.
+3. Continue step-by-step until final submit.
+4. Verify completion state and any generated confirmation ID.
 
-For wizard-style forms:
+Use `opendevbrowser_wait` with `ref` checks between steps.
+
+## Network Verification
+
+Correlate UI behavior with network activity:
+
+- Poll network events after submit.
+- Confirm expected endpoint, method, and status.
+- Flag silent frontend failures where UI does not surface server errors.
+
+```text
+opendevbrowser_network_poll sessionId="<session-id>" max=50
+```
+
+## File Upload Limitation
 
-1. Complete current step
-2. Click next/continue button
-3. Wait for next step to load
-4. Repeat until completion
-5. Verify final submission
+Current tool surface does not provide direct file input attachment.
 
-## File Upload Testing
+- Handle upload steps manually, or
+- Extend tooling with a dedicated upload capability before automating file-input paths.
 
-1. Use `opendevbrowser_run` to execute file input script
-2. Verify file preview appears
-3. Test file type restrictions
-4. Test file size limits
+## Regression-Friendly Batch Pattern
 
-## Form Reset Testing
+Use `opendevbrowser_run` to keep suites deterministic and compact:
 
-1. Fill form with data
-2. Click reset button
-3. Verify all fields cleared
-4. Verify any default values restored
+```text
+opendevbrowser_run sessionId="<session-id>" steps=[{"action":"snapshot","args":{"format":"actionables"}},{"action":"type","args":{"ref":"<field-ref>","text":""}},{"action":"click","args":{"ref":"<submit-ref>"}},{"action":"snapshot","args":{"format":"outline"}}]
+```