Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

chore: ci and docs

Luigi Agosti8ebfbf067701
diff --git a/.github/DEFINITION_OF_DONE.md b/.github/DEFINITION_OF_DONE.md
new file mode 100644
index 00000000..0b172eb2
--- /dev/null
+++ b/.github/DEFINITION_OF_DONE.md
@@ -0,0 +1,53 @@
+# Definition of Done (PR Checklist)
+
+## Automated ✅ (CI/GitHub enforces these)
+These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
+- [ ] Go formatting & linting passes (gofmt, vet, golangci-lint)
+- [ ] Unit + integration tests pass (`go test ./...`)
+- [ ] Build succeeds (`go build`)
+- [ ] CodeQL security scan passes
+- [ ] Branch naming follows convention
+
+## Manual — Code Quality (Required)
+- [ ] **Error handling explicit** — All errors wrapped with `%w`, no silent failures
+- [ ] **No regressions** — Verify stealth, token efficiency, session persistence work (test locally if unsure)
+- [ ] **SOLID principles** — Functions do one thing, testable, no unnecessary deps
+- [ ] **No redundant comments** — Comments explain *why* or *context*, not *what* the code does
+ - ❌ Bad: `// Loop through items` above `for _, item := range items`
+ - ❌ Bad: `// Return error` above `return err`
+ - ✅ Good: `// Prioritize chromium-browser on ARM64 (Raspberry Pi default)`
+ - ✅ Good: `// Chrome may not be installed in CI, so empty result is valid`
+
+## Manual — Testing (Required)
+- [ ] **New/changed functionality has tests** — Same-package unit tests preferred; use mockBridge for integration
+- [ ] **Integration tests run locally** — If you modified handlers/bridge/tabs, run: `go test -tags integration ./tests/integration`
+- [ ] **npm commands work** (if npm wrapper touched):
+ - `npm pack` in `/npm/` produces valid tarball
+ - `npm install -g pinchtab` (or from local tarball) succeeds
+ - `pinchtab --version` + basic commands work after install
+
+## Manual — Documentation (Required)
+- [ ] **README.md updated** — If user-facing changes (CLI, API, env vars, install)
+- [ ] **/docs/ updated** — If API/architecture/perf changed (optional for small fixes)
+
+## Manual — Review (Required)
+- [ ] **PR description explains what + why** — Especially stealth/perf/compatibility impact
+- [ ] **Commits are atomic** — Logical grouping, good messages
+- [ ] **No breaking changes to npm** — Unless explicitly major version bump
+
+## Conditional (Only if applicable)
+- [ ] Headed-mode tested (if dashboard/UI changes)
+- [ ] Breaking changes documented in PR description (if any)
+
+---
+
+## Quick Checklist (Copy/Paste for PRs)
+```markdown
+## Definition of Done
+- [ ] Unit/integration tests added & passing
+- [ ] Error handling explicit (wrapped with %w)
+- [ ] No regressions in stealth/perf/persistence
+- [ ] No redundant comments (explain why, not what)
+- [ ] README/docs updated (if user-facing)
+- [ ] npm install works (if npm changes)
+```
diff --git a/.github/DOCUMENTATION_REVIEW.md b/.github/DOCUMENTATION_REVIEW.md
new file mode 100644
index 00000000..6ae253de
--- /dev/null
+++ b/.github/DOCUMENTATION_REVIEW.md
@@ -0,0 +1,398 @@
+# Documentation Review Guide
+
+## Purpose
+
+Code is the source of truth. This guide helps agents audit, validate, and maintain documentation to ensure it stays in sync with the codebase.
+
+Use this document when asking agents to review documentation for accuracy, completeness, and consistency.
+
+---
+
+## Quick Summary
+
+When asked to review documentation, an agent should:
+
+1. **Verify all examples match current code behavior**
+2. **Check doc structure against actual codebase**
+3. **Update or remove outdated content**
+4. **Report findings and improvements**
+
+---
+
+## Detailed Review Process
+
+### Phase 1: Code-to-Docs Validation
+
+#### 1.1 Check All Examples
+
+For **every code example** in `/docs`:
+
+- [ ] **Run the example** (if it's executable)
+ - Does it produce the expected output?
+ - Does it work with current API/CLI?
+ - Are environment variables correct?
+
+- [ ] **Verify API endpoints**
+ - Do endpoints still exist? (`GET /snapshot`, `POST /action`, etc.)
+ - Do request/response formats match?
+ - Are all parameters documented?
+ - Are deprecated endpoints removed?
+
+- [ ] **Verify CLI commands**
+ - Do commands still exist? (`pinchtab config set`, `pinchtab health`, etc.)
+ - Do they work as documented?
+ - Are flags/options correct?
+ - Are deprecated commands removed?
+
+- [ ] **Verify configuration values**
+ - Do env vars still exist? (`CHROME_EXTENSION_PATHS`, `BRIDGE_PORT`, etc.)
+ - Are default values correct?
+ - Are deprecated config options removed?
+
+#### 1.2 Check Content Accuracy
+
+For **every paragraph, section, and claim** in `/docs`:
+
+- [ ] **API behavior** — Does it accurately describe current behavior?
+- [ ] **Performance notes** — Are benchmarks/timings still valid?
+- [ ] **Stealth/security claims** — Do they match current implementation?
+- [ ] **Feature availability** — Is feature still implemented?
+- [ ] **Limitations** — Are noted limitations still present?
+- [ ] **Requirements** — Are tool versions, Chrome versions, etc. correct?
+
+#### 1.3 Cross-Check Against Code
+
+Use the code as reference:
+
+```
+For each doc section:
+1. Find the corresponding code file(s)
+2. Compare doc description with actual implementation
+3. If different → docs are WRONG
+4. If missing → docs are INCOMPLETE
+5. If outdated → docs are STALE
+```
+
+**Example:**
+- Doc says: "fill action with refs sets the input value"
+- Code says: `FillByNodeID()` exists → docs are CORRECT ✅
+- Code says: no `FillByNodeID()` → docs are WRONG ❌
+
+---
+
+### Phase 2: Structure Review
+
+#### 2.1 Check Documentation Structure
+
+**File structure should match codebase organization:**
+
+```
+docs/
+├── api/
+│ ├── endpoints/
+│ │ ├── navigation.md
+│ │ ├── snapshot.md
+│ │ ├── actions.md
+│ │ ├── find.md
+│ │ ├── evaluate.md
+│ │ └── ...
+│ └── ...
+├── cli/
+│ ├── management.md
+│ ├── config.md
+│ └── ...
+├── architecture/
+│ └── ...
+└── index.json
+```
+
+**Verify:**
+- [ ] All major API endpoints documented?
+- [ ] All CLI commands documented?
+- [ ] Organization makes sense?
+- [ ] Groups reflect actual functionality?
+- [ ] No duplicate content?
+- [ ] No orphaned docs (not linked from index)?
+
+#### 2.2 Check index.json
+
+**Verify index.json structure:**
+
+```json
+{
+ "sections": [
+ {
+ "title": "API",
+ "path": "api/",
+ "items": [
+ {
+ "title": "Endpoints",
+ "path": "api/endpoints/",
+ "items": [
+ { "title": "Navigation", "path": "api/endpoints/navigation.md" },
+ { "title": "Snapshot", "path": "api/endpoints/snapshot.md" },
+ ...
+ ]
+ }
+ ]
+ }
+ ]
+}
+```
+
+**Checks:**
+- [ ] All sections map to actual directories?
+- [ ] All items map to actual files?
+- [ ] No broken paths?
+- [ ] Nesting depth reasonable (not too deep)?
+- [ ] Titles are accurate and clear?
+- [ ] Order makes sense (API before examples)?
+
+---
+
+### Phase 3: Report Findings
+
+#### If Changes Were Made
+
+**Create a PR with:**
+
+1. **Summary of fixes**
+ ```markdown
+ ## Documentation Fixes
+
+ - Updated /docs/api/endpoints/fill.md to document FillByNodeID support (fixes #114)
+ - Removed deprecated /docs/api/endpoints/old-nav.md (no longer exists in code)
+ - Fixed /docs/cli/config.md examples to use new config set syntax
+ - Updated Chrome requirement from 144 to 145+ for extension support
+ ```
+
+2. **List of possible improvements** (as comments in PR)
+ ```markdown
+ ## Suggested Improvements
+
+ - [ ] /docs/architecture/ could use a "bridge lifecycle" diagram
+ - [ ] /docs/api/endpoints/actions.md could add more examples
+ - [ ] /docs/cli/config.md could show YAML format examples
+ ```
+
+3. **PR description**
+ ```markdown
+ ## Documentation Review — Code Alignment
+
+ Verified all examples, API endpoints, CLI commands, and config values against current code.
+
+ ### Changes Made
+ - X examples updated to match current API
+ - X endpoints documented/updated
+ - X CLI commands verified
+ - X deprecated content removed
+
+ ### No Changes Needed
+ - API behavior accurate
+ - Structure organized
+ - Examples working
+
+ ### Improvements Suggested
+ See comments in PR for enhancement requests.
+ ```
+
+#### If No Changes Needed but Improvements Found
+
+**Create a GitHub issue:**
+
+```markdown
+Title: docs: enhancement - add examples for [feature]
+
+Body:
+## Suggestion
+
+The documentation could be improved by:
+
+1. Adding example for feature X (current docs only show basic usage)
+2. Adding "Common Patterns" section to endpoint Y
+3. Adding troubleshooting section to CLI guide
+
+## Reasoning
+
+Users asking "how do I..." suggests these are common use cases.
+
+## References
+
+- See /docs/api/endpoints/[endpoint].md
+- See /docs/cli/[command].md
+```
+
+---
+
+## Checklist for Agents
+
+When given the task "Review documentation", verify:
+
+### Code Accuracy
+- [ ] All examples are tested and working
+- [ ] All API endpoints documented correctly
+- [ ] All CLI commands documented correctly
+- [ ] All config options documented correctly
+- [ ] No deprecated content remains
+- [ ] All current features documented
+
+### Structure
+- [ ] index.json paths are correct
+- [ ] Directory structure makes sense
+- [ ] No orphaned docs
+- [ ] Grouping still makes sense
+- [ ] Navigation depth reasonable
+
+### Output
+- [ ] If changes: Create PR with summary + improvements list
+- [ ] If no changes but improvements: Create GitHub issue with enhancement request
+- [ ] Always: Note which docs were spot-checked and results
+
+---
+
+## Common Documentation Mistakes to Fix
+
+❌ **Outdated examples:**
+```bash
+# OLD (deprecated)
+pinchtab nav https://example.com # ← This command was removed
+
+# NEW (correct)
+curl -X POST http://localhost:9867/navigate \
+ -d '{"url":"https://example.com"}'
+```
+
+❌ **Wrong API format:**
+```javascript
+// OLD (incorrect)
+response = await fetch('/action', {
+ body: JSON.stringify({action: 'click', ref: 'e5'})
+})
+
+// NEW (correct)
+response = await fetch('/action', {
+ body: JSON.stringify({kind: 'click', ref: 'e5'})
+})
+```
+
+❌ **Missing new features:**
+```markdown
+<!-- Missing in docs -->
+<!-- Code has FillByNodeID support for fills with refs -->
+<!-- Docs should say: "fill supports both selectors and refs" -->
+```
+
+❌ **Incorrect config examples:**
+```bash
+# OLD (deprecated env var name)
+export BRIDGE_NAV_TIMEOUT=30
+
+# NEW (correct)
+export PINCHTAB_NAVIGATE_TIMEOUT=30
+```
+
+---
+
+## Documentation File Locations
+
+**Root docs location:** `/docs`
+
+**Key files to check:**
+
+- `/docs/index.json` — Navigation/structure
+- `/docs/README.md` — Overview
+- `/docs/api/endpoints/*.md` — API documentation
+- `/docs/cli/*.md` — CLI documentation
+- `/docs/configuration.md` — Configuration reference
+- `/docs/architecture/*.md` — Architecture/design docs
+- `/docs/examples/*.md` — Usage examples
+
+---
+
+## When to Ask for Documentation Review
+
+**Ask for review:**
+- After major feature additions (new endpoints, CLI commands)
+- After refactoring (config structure changes, API changes)
+- After bug fixes affecting documented behavior
+- Periodically (every quarter) for general sync-up
+- Before major releases (ensure nothing is stale)
+
+**Example requests:**
+
+> "Review documentation against current code. Check all API examples, CLI commands, and config values. Update docs to match code or remove outdated content. Create a PR with a summary of changes."
+
+> "Audit /docs for accuracy. Update any incorrect examples, remove deprecated features, fix broken index.json paths. Create an issue with improvement suggestions if no changes needed."
+
+---
+
+## Quality Gates
+
+A documentation review is **complete** when:
+
+✅ All examples are tested and working
+✅ All API endpoints match code implementation
+✅ All CLI commands match code implementation
+✅ All config options match code implementation
+✅ No deprecated content remains
+✅ index.json structure is accurate
+✅ Documentation structure reflects codebase
+✅ Either: PR with fixes submitted, OR Issue with improvements created
+
+---
+
+## Example Review Output (PR)
+
+```markdown
+## Documentation Review — Code Alignment
+
+All examples, endpoints, and CLI commands verified against current codebase.
+
+### ✅ Changes Made (3 files)
+
+1. **docs/api/endpoints/actions.md**
+ - Updated fill example to show ref support (new in PR #119)
+ - Added FillByNodeID code path documentation
+
+2. **docs/cli/config.md**
+ - Fixed config set examples (new syntax with PR #120)
+ - Added YAML output format example
+
+3. **docs/api/endpoints/find.md**
+ - Added Find endpoint documentation (new in feat/allocation-strategies)
+
+### ✅ Verified (No Changes Needed)
+
+- All navigate endpoint examples working
+- All snapshot filters documented correctly
+- All action kinds (click, type, press, etc.) verified
+- Config sections (server, chrome, orchestrator) accurate
+- Environment variable names current
+
+### 💡 Suggested Improvements
+
+See comments below for enhancement requests (low priority):
+- [ ] Add "common patterns" section to actions.md
+- [ ] Add troubleshooting FAQ to cli/config.md
+- [ ] Create /docs/examples/multi-step-workflow.md
+
+### Review Stats
+
+- Examples tested: 12/12 ✅
+- Endpoints checked: 8/8 ✅
+- CLI commands checked: 5/5 ✅
+- Config sections checked: 4/4 ✅
+- Deprecated content found: 0 ✅
+- Structure issues found: 0 ✅
+```
+
+---
+
+## Related Documents
+
+- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — PR checklist
+- [LABELING_GUIDE.md](./LABELING_GUIDE.md) — Issue labeling guide
+
+---
+
+Last updated: 2026-03-04
diff --git a/.github/LABELING_GUIDE.md b/.github/LABELING_GUIDE.md
new file mode 100644
index 00000000..c2a882ad
--- /dev/null
+++ b/.github/LABELING_GUIDE.md
@@ -0,0 +1,246 @@
+# Labeling Guide
+
+This document describes the labeling system used for issues and PRs in pinchtab. Use this guide when triaging tickets or asking agents to review open issues.
+
+---
+
+## Quick Reference
+
+Every issue should have:
+1. **Exactly one Type label** (bug, enhancement, documentation, question, etc.)
+2. **One Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
+3. **One Priority label** (high, medium, low) — optional for documentation or questions
+
+---
+
+## Tier 1: Issue Type (Mandatory)
+
+Choose **exactly one**:
+
+| Label | Color | Usage |
+|-------|-------|-------|
+| `bug` | 🔴 Red | Something isn't working correctly |
+| `enhancement` | 🔵 Cyan | New feature or capability request |
+| `documentation` | 🔵 Blue | Improvements/additions to README, docs, or code comments |
+| `question` | 🟣 Purple | Request for clarification or information |
+| `good first issue` | 🟣 Purple | Good for newcomers (in addition to type label) |
+| `help wanted` | 🟢 Green | Needs extra attention or expertise |
+| `dependencies` | 🔵 Blue | Dependency updates (PR label) |
+| `invalid` | 🟡 Yellow | Doesn't seem right; requires clarification |
+| `duplicate` | ⚪ Gray | Already exists (close and reference original) |
+| `wontfix` | ⚪ White | Deliberate decision not to fix |
+
+### Examples
+
+- **Bug:** "fill action silently no-ops when using refs" → `bug`
+- **Enhancement:** "Add CHROME_EXTENSION_PATHS support" → `enhancement`
+- **Documentation:** "Update README with new CLI commands" → `documentation`
+- **Question:** "How do I configure stealth mode?" → `question`
+
+---
+
+## Tier 2: Status (Recommended)
+
+Choose **one** to show current state:
+
+| Label | Color | Meaning | When to Use |
+|-------|-------|---------|------------|
+| `status: ready` | 🔵 Blue | Ready to start work | Issue is fully understood, no blockers, waiting for someone to pick it up |
+| `status: in-progress` | 🟡 Yellow | Actively being worked on | Someone has claimed the issue and is working on a fix/feature |
+| `status: blocked` | 🔴 Red | Blocked by something | Waiting on external dependency, another issue, or decision |
+| `status: fixed-unreleased` | 🟢 Green | Fix merged, not in release | PR is merged but feature/fix isn't in a released version yet |
+| `status: needs-investigation` | 🔴 Red | Needs debugging/research | Not enough info; requires investigation before work can start |
+
+### Workflow
+
+```
+New Issue
+ ↓
+[Triage] Add Type + Status
+ ↓
+status: needs-investigation (if unclear) or status: ready (if clear)
+ ↓
+Developer picks it up
+ ↓
+status: in-progress
+ ↓
+PR submitted
+ ↓
+PR merged
+ ↓
+status: fixed-unreleased (for bugs) or remove status (for features)
+ ↓
+Release cut
+ ↓
+Remove status label (feature is released)
+```
+
+---
+
+## Tier 3: Priority (Optional, for bugs/enhancements)
+
+Choose **one** to indicate urgency:
+
+| Label | Color | Level | When to Use |
+|-------|-------|-------|------------|
+| `priority: high` | 🔴 Red | Critical; blocks users | Security vulnerability, critical bug, high-demand feature |
+| `priority: medium` | 🟡 Yellow | Normal; important for roadmap | Important bug or feature; should be done soon |
+| `priority: low` | 🟢 Green | Nice to have; can defer | Minor improvement, polish, or edge case |
+
+### Examples
+
+- **High:** "SafePath() fails to block path traversal" (security) → `bug` + `priority: high`
+- **Medium:** "Snapshot doesn't work inside iframes" (affects users) → `bug` + `priority: medium`
+- **Low:** "Consider migrating to PINCHTAB_* env vars" (nice refactor) → `enhancement` + `priority: low`
+
+---
+
+## Special Labels
+
+### `good first issue`
+Add this **in addition to the type label** for issues that are good entry points for new contributors.
+
+**Criteria:**
+- Clear problem statement
+- Solution is straightforward
+- Doesn't require deep knowledge of codebase
+- Estimated effort: <4 hours
+
+**Example:** "documentation: Add /find endpoint example to README" → `documentation` + `good first issue`
+
+### `help wanted`
+Indicates the issue needs expertise or has been stalled.
+
+**When to use:**
+- Needs specific expertise (e.g., "needs Windows testing")
+- Issue has been open >2 weeks without progress
+- Complex problem that benefits from external input
+
+---
+
+## Decision Tree for Triage
+
+```
+New issue arrives
+ ↓
+1. Is it a valid issue?
+ NO → `invalid` + close
+ YES ↓
+2. What is it?
+ → Bug? `bug` + assess severity → `priority: high|medium|low`
+ → New feature? `enhancement` + assess importance → `priority: high|medium|low`
+ → Docs missing? `documentation` + no priority needed
+ → Unclear? `question` + no priority needed
+ ↓
+3. Can we start work immediately?
+ YES → `status: ready`
+ NO ↓
+4. Why not?
+ → Need info → `status: needs-investigation`
+ → Waiting on something → `status: blocked`
+ → Already fixed → `status: fixed-unreleased`
+```
+
+---
+
+## Guidelines for Agents
+
+When reviewing open issues, follow this checklist:
+
+- [ ] **Each issue has exactly one Type label** (bug, enhancement, documentation, question)
+- [ ] **Bugs have Priority labels** (high, medium, low)
+- [ ] **Enhancements have Priority labels** (high, medium, low)
+- [ ] **Each issue has a Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
+- [ ] **No duplicate labels** (e.g., two type labels on one issue)
+- [ ] **Status matches reality** (e.g., `status: in-progress` has an active PR)
+- [ ] **Stale issues reviewed** (e.g., `status: blocked` for >2 weeks should note why)
+
+---
+
+## Current Label Inventory
+
+**Type labels (10):**
+- bug, enhancement, documentation, question, good first issue, help wanted, dependencies, invalid, duplicate, wontfix
+
+**Status labels (5):**
+- status: ready, status: in-progress, status: blocked, status: fixed-unreleased, status: needs-investigation
+
+**Priority labels (3):**
+- priority: high, priority: medium, priority: low
+
+**Code labels (1):**
+- javascript
+
+---
+
+## Examples of Well-Labeled Issues
+
+### Example 1: Security Bug
+```
+Title: SafePath() fails to block path traversal on Windows
+Labels: bug, priority: high, status: ready
+```
+**Why:** Critical security issue, ready to work on, high priority.
+
+### Example 2: Feature Request (Ready)
+```
+Title: feat: Resource Pool with pluggable allocation strategies
+Labels: enhancement, priority: medium, status: ready
+```
+**Why:** Enhancement, medium priority (important for roadmap), ready to start.
+
+### Example 3: Feature (Blocked)
+```
+Title: feat: Semantic Element Selection via NLP (/find endpoint)
+Labels: enhancement, priority: medium, status: blocked
+```
+**Why:** Enhancement, medium priority, but blocked (perhaps waiting on design decision).
+
+### Example 4: Bug (Not Ready)
+```
+Title: click and humanClick fail to trigger Bootstrap dropdown
+Labels: bug, priority: medium, status: needs-investigation
+```
+**Why:** Bug, medium priority, but needs investigation (reproduction steps unclear).
+
+### Example 5: Already Fixed
+```
+Title: Installation issue
+Labels: bug, priority: high, status: fixed-unreleased
+```
+**Why:** Critical bug, but fix is already merged and waiting for release.
+
+---
+
+## Common Mistakes
+
+❌ **Don't do this:**
+
+| Mistake | Why | Fix |
+|---------|-----|-----|
+| Two Type labels on one issue | Ambiguous; what is it really? | Choose one type only |
+| Status label on closed issue | Status should reflect open work | Remove status label when closing |
+| No Priority on bugs | Can't triage effectively | Add priority: high/medium/low to all bugs |
+| `status: in-progress` with no PR | Misleading; is someone actually working on it? | Only use when work is actively underway |
+| Forgetting Status labels | No visibility into progress | Always add a status label during triage |
+
+---
+
+## Related Documents
+
+- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — Checklist for PRs before merge
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guidelines (if present)
+
+---
+
+## Last Updated
+
+2026-03-04
+
+---
+
+## Summary
+
+**For agents:** Use this guide to understand and apply labels when triaging issues. Ensure every issue has Type + Status + Priority (if applicable).
+
+**For maintainers:** Review labels during triage and ensure consistency. Use the Decision Tree above as a quick reference.
diff --git a/.github/README.md b/.github/README.md
new file mode 100644
index 00000000..0634ea3c
--- /dev/null
+++ b/.github/README.md
@@ -0,0 +1,85 @@
+# GitHub Governance Documents
+
+This directory contains pinchtab's governance and workflow documents referenced by developers and automated agents.
+
+## Documents
+
+### [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md)
+**Purpose:** PR checklist for code quality, testing, and documentation before merging.
+
+**For:** All contributors submitting PRs
+**How to use:** Check this list before submitting a PR, or ask agents to verify PRs against it.
+
+**Key sections:**
+- Automated checks (CI enforces)
+- Manual code quality requirements
+- Testing requirements
+- Documentation requirements
+- Quick checklist for copy/paste
+
+---
+
+### [LABELING_GUIDE.md](./LABELING_GUIDE.md)
+**Purpose:** Reference guide for issue and PR labeling to maintain consistent triage.
+
+**For:** Maintainers triaging issues, agents reviewing tickets
+**How to use:** Point agents to this guide when asking them to review and label open issues.
+
+**Key sections:**
+- 3-tier labeling system (Type → Status → Priority)
+- Decision tree for triage
+- Guidelines for agents
+- Examples of well-labeled issues
+- Common mistakes to avoid
+
+---
+
+### [DOCUMENTATION_REVIEW.md](./DOCUMENTATION_REVIEW.md)
+**Purpose:** Guide for auditing documentation to ensure it stays in sync with code (code is source of truth).
+
+**For:** Agents maintaining documentation, quality assurance
+**How to use:** Point agents to this guide when asking them to audit docs for accuracy and consistency.
+
+**Key sections:**
+- Code-to-docs validation (examples, endpoints, commands, config)
+- Structure review (organization, index.json, grouping)
+- Output requirements (PR with fixes or GitHub issue with improvements)
+- Common documentation mistakes to fix
+- Quality gates for completion
+
+---
+
+## Quick Reference
+
+| Document | Audit For | Used By |
+|----------|-----------|---------|
+| DEFINITION_OF_DONE.md | PR quality before merge | Developers, agents, reviewers |
+| LABELING_GUIDE.md | Consistent issue triage | Maintainers, agents |
+| DOCUMENTATION_REVIEW.md | Documentation accuracy vs code | Agents, QA |
+
+---
+
+## How Agents Use These
+
+When asking an agent to help with PRs, issues, or documentation:
+
+**For PR review:**
+> "Review this PR against `.github/DEFINITION_OF_DONE.md` and ensure it meets all requirements."
+
+**For issue triage:**
+> "Review open issues and apply labels according to `.github/LABELING_GUIDE.md`. Ensure Type + Status + Priority are consistent."
+
+**For documentation audit:**
+> "Review documentation against current code using `.github/DOCUMENTATION_REVIEW.md`. Verify all examples match code, update or remove outdated content, report changes in a PR or improvements in a GitHub issue."
+
+---
+
+## Maintenance
+
+- **DEFINITION_OF_DONE.md** — Update when code quality standards change
+- **LABELING_GUIDE.md** — Update when new labels are added or workflow changes
+- This **README.md** — Update when new governance documents are added
+
+---
+
+Last updated: 2026-03-04
diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml
index e2a1f069..df321dba 100644
--- a/.github/workflows/integration.yml
+++ b/.github/workflows/integration.yml
@@ -28,7 +28,7 @@ jobs:
changes:
name: Detect Changes
runs-on: ubuntu-latest
- if: github.event.pull_request.draft == false
+ if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
outputs:
go: ${{ steps.filter.outputs.go }}
steps:
@@ -45,28 +45,85 @@ jobs:
- 'internal/**'
- 'tests/integration/**'
- integration:
- name: Integration Tests
+ integration-core:
+ name: Integration Tests (Core)
needs: changes
runs-on: ubuntu-latest
- timeout-minutes: 25
+ timeout-minutes: 12
+ if: needs.changes.outputs.go == 'true'
+ env:
+ CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'
steps:
- - name: Skip if no Go changes
- if: needs.changes.outputs.go != 'true'
+ - uses: actions/checkout@v4
+
+ - uses: actions/setup-go@v5
+ with:
+ go-version: '1.26'
+
+ - name: Install Google Chrome (deb, avoids snap hangs)
run: |
- echo "⏭️ No Go files changed, skipping integration tests"
- echo "This is expected for docs/workflow-only changes"
+ wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
+ echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list
+ sudo apt-get update
+ sudo apt-get install -y google-chrome-stable
+ echo "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV
+ - name: Install gotestsum
+ run: go install gotest.tools/gotestsum@latest
+
+ - name: 🧪 Run core integration tests
+ run: |
+ echo "::group::Core Integration Tests Output"
+ gotestsum --format testname --jsonfile core-events.json -- \
+ -tags integration -v -timeout 10m -count=1 \
+ -run "$CORE_REGEX" ./tests/integration/
+ echo "::endgroup::"
+ env:
+ CI: "true"
+ BRIDGE_HEADLESS: "true"
+ BRIDGE_NO_RESTORE: "true"
+ PINCHTAB_TEST_PORT: "19867"
+ PINCHTAB_TEST_RETRY: "true"
+
+ - name: 📋 Add summary
+ if: always()
+ run: |
+ total=0
+ pass=0
+ fail=0
+ skip=0
+
+ if [ -s core-events.json ]; then
+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' core-events.json \
+ | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"
+ fi
+
+ echo "### ✅ Integration Core Tests" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Port**: 19867" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"
+
+ integration-rest:
+ name: Integration Tests (Rest)
+ needs: changes
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ if: needs.changes.outputs.go == 'true'
+ env:
+ CORE_REGEX: '^Test(Health|Orchestrator_|Navigate_|Tabs_|Config_|Metrics_|Cookies_|Error_|Eval_|Upload_|Screenshot_)'
+ steps:
- uses: actions/checkout@v4
- if: needs.changes.outputs.go == 'true'
- uses: actions/setup-go@v5
- if: needs.changes.outputs.go == 'true'
with:
go-version: '1.26'
- name: Install Google Chrome (deb, avoids snap hangs)
- if: needs.changes.outputs.go == 'true'
run: |
wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo 'deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main' | sudo tee /etc/apt/sources.list.d/google-chrome.list
@@ -74,12 +131,43 @@ jobs:
sudo apt-get install -y google-chrome-stable
echo "CHROME_BINARY=/usr/bin/google-chrome" >> $GITHUB_ENV
- - name: Run integration tests
- if: needs.changes.outputs.go == 'true'
- run: go test -tags integration -v -timeout 20m -count=1 ./tests/integration/
+ - name: Install gotestsum
+ run: go install gotest.tools/gotestsum@latest
+
+ - name: 🧪 Run rest integration tests
+ run: |
+ echo "::group::Rest Integration Tests Output"
+ gotestsum --format testname --jsonfile rest-events.json -- \
+ -tags integration -v -timeout 12m -count=1 \
+ -run '^Test' -skip "$CORE_REGEX" ./tests/integration/
+ echo "::endgroup::"
env:
CI: "true"
BRIDGE_HEADLESS: "true"
BRIDGE_NO_RESTORE: "true"
- PINCHTAB_TEST_PORT: "19867"
+ PINCHTAB_TEST_PORT: "19868"
PINCHTAB_TEST_RETRY: "true"
+
+ - name: 📋 Add summary
+ if: always()
+ run: |
+ total=0
+ pass=0
+ fail=0
+ skip=0
+
+ if [ -s rest-events.json ]; then
+ read total pass fail skip <<<"$(jq -r 'select(.Test != null and (.Action == "pass" or .Action == "fail" or .Action == "skip")) | [.Package, .Test, .Action] | @tsv' rest-events.json \
+ | awk -F'\t' 'NF == 3 { key = $1 "\t" $2; status[key] = $3 } END { for (k in status) { t++; if (status[k] == "pass") p++; else if (status[k] == "fail") f++; else if (status[k] == "skip") s++; } printf "%d %d %d %d\n", t + 0, p + 0, f + 0, s + 0 }')"
+ fi
+
+ echo "### ✅ Integration Rest Tests" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Status**: ${{ job.status }}" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Runner**: ubuntu-latest" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Port**: 19868" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Selection**: all integration tests with core tests skipped" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Skip regex**: \`$CORE_REGEX\`" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Total tests**: $total" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Passed**: $pass" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Failed**: $fail" >> "$GITHUB_STEP_SUMMARY"
+ echo "- **Skipped**: $skip" >> "$GITHUB_STEP_SUMMARY"