onecrawl 4.0.0-alpha.55 → 4.0.0-alpha.57

package/assets/skills/breaking-change-paths/SKILL.md

@@ -5,27 +5,55 @@ description: "Structured decision process between Non-Breaking and Breaking path
 # Breaking Change Decision Skill
 
 ## Purpose
-Run a structured, future-proof decision process between Non-Breaking and Breaking paths without relaxing quality gates.
+Run a structured, future-proof decision process when a task may affect public contracts, APIs, schemas, or behavioral compatibility.
 
 ## Use when
 - A task may affect public contracts, APIs, schemas, or behavioral compatibility
-- Root-cause fixes suggest architectural reshaping
-
-## Checklist
-- Explicitly classify impact: Non-Breaking vs Breaking.
-- Present both paths with:
-  - pros/cons
-  - risk level
-  - migration steps
-- State explicitly: quality gates are unchanged for both paths.
-- Require green unit/integration/E2E/non-regression tests in both cases.
-- If Breaking is selected, include migration and compatibility notes before execution.
-
-## Short examples
-- Non-Breaking path: adapter layer preserving old contract while introducing new internals.
-- Breaking path: remove deprecated endpoint + provide migration map + test updates.
+- A root-cause fix implies architectural reshaping
+- The user explicitly asks for breaking/non-breaking analysis
+
+## OneCrawl Contract Surfaces
+
+| Surface | Breaking Impact | Examples |
+|---------|----------------|----------|
+| **CLI flags/args** | HIGH | Renaming `--headless` → `--head`, removing `--native` |
+| **MCP tool names/schemas** | HIGH | Renaming tool actions, changing JSON schemas |
+| **NAPI/PyO3 method signatures** | HIGH | Changing function names, param types, return types |
+| **Config keys** | MEDIUM | Renaming `config.toml` keys, changing defaults |
+| **Session file format** | MEDIUM | Changing `/tmp/onecrawl-session-*.json` structure |
+| **Daemon protocol** | MEDIUM | Changing HTTP/WS API between CLI and daemon |
+| **Internal crate APIs** | LOW | Changing `pub` functions in workspace crates |
+| **CDP layer** | LOW | Internal CDP wrapper changes |
+
+## Decision Framework
+
+### Non-Breaking Path
+- Add new flags/options alongside existing ones
+- Deprecation warnings before removal (minimum 2 alpha releases)
+- Backward-compatible config: new keys get defaults, old keys still work
+- Additive MCP actions (new actions, not renamed ones)
+
+### Breaking Path (requires justification)
+- Must document: what breaks, who is affected, migration steps
+- Must provide: migration guide or automated migration tool
+- Must bump: version increment that signals the break
+- Quality gates unchanged: unit/integration/E2E/non-regression must still pass
+
+## Procedure
+1. Identify all contract surfaces affected.
+2. For each, classify as non-breaking or breaking.
+3. Present options via `ask_user` with the compatibility triad:
+   - Non-Breaking Path (additive/compatible)
+   - Breaking Path (with migration plan)
+   - Alternative Structural Path (redesign to avoid the break)
+4. Document decision in commit message and CHANGELOG.
+
+## Done Criteria
+- Decision documented with rationale.
+- Migration steps provided for any breaking change.
+- All quality gates pass.
 
 ## Anti-patterns
-- Assuming breaking path without explicit selection
-- Treating breaking changes as exempt from test gates
-- Missing migration guidance
+- Silent breaking changes (no documentation)
+- Breaking changes without version bump
+- Assuming internal changes are safe (NAPI/PyO3 are public)

package/assets/skills/completion-gate/SKILL.md

@@ -19,9 +19,30 @@ Enforce a mandatory quality gate for every Issue, Milestone, and PR with zero-er
 4. Required tests pass (unit, integration if applicable, E2E if applicable, non-regression).
 5. Full suite passes; coverage is not below baseline.
 
+## OneCrawl Gate Commands
+
+Run these in order. Both must pass **twice consecutively** with zero output:
+
+```bash
+# 1. Clippy (lint + static analysis) - 0 warnings required
+cargo clippy --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- -W clippy::all
+
+# 2. Build check (fast compilation verification)
+cargo check --workspace
+
+# 3. Test suite (all tests, single-threaded for determinism)
+cargo test --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- --test-threads=1
+
+# 4. Health check (binary runs correctly)
+./target/release/onecrawl health
+./target/release/onecrawl --version
+```
+
+Acceptable warnings: `onecrawl-browser` vendor crate (1 warning, do not touch).
+
 ## Procedure
-1. Run full review/check suite.
-2. If any error/warning exists, fix and restart from step 1.
+1. Run all gate commands above.
+2. If any error/warning exists in owned crates, fix and restart from step 1.
 3. Repeat until two clean consecutive passes are recorded.
 4. Only then mark status `done`/merge.
 
@@ -32,4 +53,5 @@ Enforce a mandatory quality gate for every Issue, Milestone, and PR with zero-er
 ## Anti-patterns
 - Single-pass approval
 - Ignoring warnings
-- Deferring known issues to “later”
+- Deferring known issues to "later"
+- Excluding tests with `#[ignore]` to pass the gate

package/assets/skills/e2e-testing/SKILL.md

@@ -5,26 +5,49 @@ description: "Deterministic, CI-ready end-to-end validation for critical user fl
 # E2E Testing Skill
 
 ## Purpose
-Define deterministic, CI-ready end-to-end validation for critical user flows.
+Ensure critical user flows work end-to-end with deterministic, CI-compatible execution.
 
 ## Use when
-- A user-facing flow changes
-- A critical integration path is introduced or modified
-- Regression risk is non-trivial
+- A user-facing flow changes or a critical integration path is introduced/modified
+
+## OneCrawl E2E Architecture
+
+E2E tests live in `packages/onecrawl-rust/crates/onecrawl-e2e/` and require a running Chrome instance.
+
+```bash
+# Run E2E tests (requires Chrome)
+cargo test -p onecrawl-e2e -- --test-threads=1
+
+# Manual E2E verification (quick smoke test)
+onecrawl session start -H                    # Headless Chrome
+onecrawl navigate https://example.com        # Navigate
+onecrawl get title                           # Verify page loaded
+onecrawl screenshot --full                   # Visual verification
+onecrawl session close                       # Cleanup
+```
+
+## Critical Flows to Test
+1. **Session lifecycle**: start → navigate → interact → close
+2. **Daemon mode**: daemon start → session start → exec → daemon stop
+3. **Multi-agent isolation**: session start -s a1 → session start -s a2 → verify isolation
+4. **Profile management**: profile create → session start --profile → profile delete
+5. **Config management**: config set → config show → verify change persists
+6. **Auth persistence**: auth-state save → session close → session start → auth-state load
+7. **Stealth**: session start → stealth detection-audit → verify 0% headless detection
 
 ## Checklist
-- Cover at least one E2E scenario per critical flow.
-- Include happy path + key error/edge cases.
-- Use programmatic execution only (CI-compatible, non-interactive).
-- Prefer stable selectors (for example, `data-testid`).
-- Keep tests deterministic and isolated with proper setup/teardown.
-- Ensure E2E is part of non-regression validation before completion.
+- [ ] Happy path covered for each critical flow
+- [ ] Edge cases: invalid input, missing Chrome, concurrent sessions
+- [ ] Cleanup: sessions closed, temp files removed, profiles deleted
+- [ ] Deterministic: no timing-dependent assertions
+- [ ] Stable selectors: use `data-testid` or semantic selectors
+- [ ] CI-compatible: headless mode, no GUI dependencies
 
-## Short examples
-- Checkout flow: payment success + payment failure retry path.
-- Auth flow: valid login + expired token refresh path.
+## Done Criteria
+- All critical flows pass in headless mode.
+- No leaked browser processes after test completion.
 
 ## Anti-patterns
-- Manual-only E2E verification
-- Flaky timing-based waits without stable signals
-- Skipping E2E updates after flow changes
+- Hard-coded sleep/timeouts instead of wait-for conditions
+- Tests that depend on network state
+- Shared mutable state between test cases

package/assets/skills/github-sync/SKILL.md

@@ -5,35 +5,49 @@ description: "Keep local plan and GitHub project artifacts perfectly aligned wit
 # GitHub Sync Skill
 
 ## Purpose
-Keep local plan and GitHub project artifacts perfectly aligned (milestones, issues, labels, statuses, dependencies).
+Keep local plan and GitHub project artifacts perfectly aligned.
 
 ## Use when
-- Creating/updating plan
+- Creating or updating a plan
 - Changing issue status
 - Completing milestones
 
+## OneCrawl Repository
+- Owner: `giulio-leone`
+- Repo: `onecrawl`
+- Branch: `main`
+- Tags: `v4.0.0-alpha.XX`
+
 ## Naming Rules
-- Milestone: `M<id> — <description>`
-- Issue: `[M<milestone_id>] I<issue_id> — <task>`
+- Milestones: `MX: <Title>` (e.g., `M14: Deep Audit`)
+- Issues: `<type>: <description>` (e.g., `fix: session name path traversal`)
+- Branches: `<type>/<short-description>` (e.g., `fix/session-path-traversal`)
+- Tags: `v4.0.0-alpha.XX` (SemVer pre-release)
 
-## Required Metadata
-- Priority label: `P-critical|P-high|P-medium|P-low`
-- Type label: `feat|fix|refactor|chore|test`
-- Status label: `in-progress|review|blocked`
-- Milestone link
-- Dependency note: `depends on #<issue_number>`
-- Parent/child note: `part of #<issue_number>`
+## Required Labels
+- Priority: `P0-critical`, `P1-high`, `P2-medium`, `P3-low`
+- Type: `bug`, `feature`, `refactor`, `docs`, `chore`
+- Status: `todo`, `in-progress`, `review`, `done`, `blocked`
 
 ## Procedure
-1. On plan create/update, create/update corresponding GitHub milestones/issues.
-2. On local issue status change, sync GitHub status + labels immediately.
-3. Close milestone when all linked issues are done.
-4. Ensure no orphan issues (every issue belongs to a milestone).
+1. Create GitHub milestone matching local plan milestone.
+2. Create issues for each task, linked to milestone.
+3. Apply labels (priority + type + status).
+4. Update issue status as work progresses.
+5. Close milestone when all issues are done.
+
+## OneCrawl Release Sync
+After each alpha release:
+1. Tag: `git tag v4.0.0-alpha.XX && git push origin main --tags`
+2. npm: `npm publish --tag alpha --access public`
+3. CHANGELOG: update with release notes
 
 ## Done Criteria
-- Local plan == GitHub state (titles, labels, status, dependencies).
+- All plan items have matching GitHub artifacts.
+- Labels are applied consistently.
+- Milestones reflect actual progress.
 
 ## Anti-patterns
-- Local-only tracking
-- Orphan issues
-- Stale labels/status
+- Local plan diverges from GitHub state
+- Missing labels on issues
+- Stale milestones with no issues

package/assets/skills/onecrawl-commands/SKILL.md

@@ -354,6 +354,9 @@ daemon exec goto url=https://example.com --session linkedin
 daemon exec evaluate expression="1+1" --session work
 daemon status                    # Daemon health + session list
 daemon stop                      # Stop daemon
+session start --auto-connect     # Attach to existing Chrome with CDP
+session start --profile work     # Launch with named profile
+session start -s my-agent        # Named session for multi-agent
 ```
 
 ### 26. Agent Automation
@@ -366,6 +369,38 @@ agent chain "<js actions>"       # Execute pre-written action sequences
 agent observe                    # Get annotated page state with coordinates
 ```
 
+### 27. Profile Management
+```bash
+profile list                     # List all named profiles with size/date
+profile create <name>            # Create isolated Chrome user-data-dir
+profile delete <name>            # Remove a named profile
+profile info <name>              # Show profile details (cookies, logins, prefs)
+profile gc                       # Remove profiles not accessed in 30 days
+profile gc --days 7              # Custom age threshold
+```
+
+### 28. Config CLI
+```bash
+config show                      # Display all config values (formatted)
+config show --raw                # Output raw TOML
+config set <key> <value>         # Modify a config value
+config path                      # Print config file path
+config init                      # Reset to defaults (creates .bak backup)
+```
+
+### 29. Tab Management
+```bash
+tab list                         # Human-readable tab list with active marker (◀)
+tab find <query>                 # Search tabs by URL or title (case-insensitive)
+tab activate <id>                # Switch to tab by ID
+tab close <id>                   # Close tab by ID
+```
+
+### 30. Health Check
+```bash
+health                           # Enhanced: daemon + sessions + config + profiles
+```
+
 ## Anti-Patterns (Don't Do This)
 
 | ❌ Bad (eval) | ✅ Good (primitive) |
@@ -396,13 +431,20 @@ daemon = true                   # daemon mode by default
 daemon_headless = true
 session_name = "default"
 session_auto_isolate = true     # auto-unique session names per agent
+auto_connect = false            # auto-discover running Chrome with CDP
 persist_cookies = ""            # auto-persist path, empty = disabled
 chrome_profile = ""             # empty = auto (~/.onecrawl/chrome-profile/)
 user_agent = ""                 # empty = auto
 daemon_idle_timeout = 1800      # 30 minutes
 daemon_max_sessions = 8
+daemon_shutdown_grace_secs = 5
+daemon_max_log_mb = 50
+daemon_ws_proxy_port = 0        # 0 = disabled
+daemon_event_buffer = 1000
 daemon_pool_size = 0            # pre-warmed sessions (0 = disabled)
 daemon_rate_limit = 0           # per-second (0 = unlimited)
+lightpanda_host = "127.0.0.1"
+lightpanda_port = 9222
 ```
 
 CLI flags always override config values.

package/assets/skills/planning-tracking/SKILL.md

@@ -2,7 +2,7 @@
 name: planning-tracking
 description: "Execution plan with milestone/issue hierarchy, explicit dependencies, and safe parallelism."
 ---
-# Planning & Tracking Skill
+# Planning and Tracking Skill
 
 ## Purpose
 Create and maintain an execution plan with milestone/issue hierarchy, explicit dependencies, and safe parallelism.
@@ -19,13 +19,36 @@ interface Milestone { id: string; description: string; priority: "critical"|"hig
 interface Issue { id: string; task: string; priority: "critical"|"high"|"medium"|"low"; status: "todo"|"in_progress"|"review"|"done"|"blocked"; depends_on: string[]; children: Record<string, Issue>; }
 ```
 
+## OneCrawl Workspace Parallelism Rules
+
+Safe to parallelize:
+- Changes in different crates (e.g., `onecrawl-cdp` + `onecrawl-parser`)
+- NAPI + PyO3 bindings (independent build targets)
+- Documentation + code changes
+
+NOT safe to parallelize:
+- Changes in a crate + its dependents (e.g., `onecrawl-cdp` + `onecrawl-cli-rs`)
+- Multiple changes to the same file
+- Version bumps (must be sequential: Cargo.toml then package.json)
+
+## OneCrawl Crate Dependency Graph
+```
+onecrawl-cli-rs
+  -> onecrawl-mcp-rs -> onecrawl-cdp -> onecrawl-browser
+  -> onecrawl-server -> onecrawl-cdp
+  -> onecrawl-core
+  -> onecrawl-crypto
+  -> onecrawl-parser
+  -> onecrawl-storage
+```
+
 ## Procedure
 1. Build plan before implementation.
 2. Assign unique IDs to milestones/issues.
-3. Declare dependencies for every issue (`depends_on`).
-4. Execute by dependency order, then priority (`critical` → `high` → `medium` → `low`).
+3. Declare dependencies for every issue.
+4. Execute by dependency order, then priority (critical then high then medium then low).
 5. Run independent same-priority milestones in parallel when safe.
-6. Update statuses continuously and append concise progress summaries.
+6. Update statuses continuously.
 
 ## Done Criteria
 - Plan exists, is up-to-date, and reflects actual execution state.

package/assets/skills/policy-coherence-audit/SKILL.md

@@ -8,22 +8,45 @@ description: "Detect and remove contradictions across agent policies before exec
 Detect and remove contradictions across agent policies before execution.
 
 ## Use when
-- Updating `AGENTS.MD`
+- Updating AGENTS.md or runtime adapters
 - Merging new workflow rules
 - Noticing behavioral ambiguity during execution
 
-## Checklist
-- Language coherence: English-only wording.
-- Interaction coherence: one question + 5-option model is consistently respected.
-- Gate coherence: completion gates apply to both Non-Breaking and Breaking paths.
-- Scope coherence: avoid wording that causes uncontrolled scope creep.
-- Reference coherence: every mentioned skill path exists.
+## OneCrawl Policy Files
 
-## Short examples
-- Fix mixed language term: "TASSATIVO" -> "MANDATORY".
-- Fix model mismatch: "propose one option" -> explicit 5-option decision set.
+| File | Purpose |
+|------|---------|
+| `AGENTS.md` | Root dispatcher, skill catalog |
+| `AGENTS.vscode.MD` | VS Code runtime adapter |
+| `AGENTS.copilot-cli.MD` | Copilot CLI runtime adapter |
+| `.github/copilot-instructions.md` | Build, test, architecture reference |
+| `.github/skills/*/SKILL.md` | 14 operational skills |
+
+## Audit Checklist
+
+1. Language: Are all policies in English?
+2. Interaction model: Is ask_user (CLI) vs vscode_askQuestions (VS Code) correctly bound?
+3. Freeform invariant: Is option 4 always Freeform in all 5-option prompts?
+4. Completion gates: Do all skills reference the same gate procedure?
+5. Scope: Are skills non-overlapping? No duplicate procedures?
+6. Skill references: Do AGENTS.md catalog entries match actual SKILL.md files?
+7. Tool names: Are MCP tool references correct (onecrawl run, not chrome-devtools)?
+8. Build commands: Are cargo/npm commands consistent across all skills?
+9. Version: Are version references up-to-date?
+10. Stop condition: Is "I am satisfied" the only stop phrase in all loop references?
+
+## Procedure
+1. Read all policy files listed above.
+2. Run each checklist item.
+3. Document any contradictions found.
+4. Fix contradictions (update the owning file).
+5. Verify fix does not introduce new contradictions.
+
+## Done Criteria
+- All checklist items pass.
+- No contradictions between any two policy files.
 
 ## Anti-patterns
-- Leaving ambiguous precedence between structural and surgical strategies
-- Contradictory clauses in different sections
-- Referencing non-existent skill files
+- Duplicating procedures across skills and AGENTS files
+- Mixing tool names across runtimes
+- Updating one file without checking cross-references

package/assets/skills/rollback-rca/SKILL.md

@@ -2,35 +2,54 @@
 name: rollback-rca
 description: "Stop ineffective iteration loops and choose a controlled recovery path after repeated gate failures."
 ---
-# Rollback & RCA Skill
+# Rollback and RCA Skill
 
 ## Purpose
-Stop ineffective iteration loops and choose a controlled recovery path after repeated gate failures.
+Stop ineffective iteration loops after repeated completion gate failures and choose a controlled recovery path.
 
 ## Use when
-- An issue fails completion gate 3 consecutive times
-
-## Procedure
-1. Stop work on the issue immediately.
-2. Run root cause analysis:
-   - Architecture mismatch?
-   - Dependency/environment problem?
-   - Scope too broad?
-3. Present options via `ask_user`:
-   - Rescope (split into smaller sub-issues)
-   - Rollback (revert to last known good commit)
-   - Redesign (change architecture)
-4. Execute selected path and document rationale in session log.
-
-## Rollback Rules
-- Keep history clean and revertible.
-- Roll back only to the last commit that passed gate.
-- Record rollback cause and follow-up plan.
+- An issue fails the completion gate 3 consecutive times
+
+## OneCrawl Common Failure Modes
+
+| Failure | Root Cause | Recovery |
+|---------|-----------|----------|
+| Clippy warnings persist | Vendor crate or structural pattern | Add targeted allow with justification |
+| Test timeout | Browser not running or port conflict | Check daemon status |
+| Linker error PyO3 | PyO3 test mode linker conflict | Exclude onecrawl-python from test runs |
+| CDP connection refused | Daemon crashed or wrong port | Restart daemon |
+| Memory growth in tests | Unbounded Vec or HashMap | Cap with VecDeque |
+| Send compile error | rand rng across await | Scope RNG in sync block before await |
+
+## RCA Procedure
+1. Reproduce: Run the exact failing command and capture full output.
+2. Classify: Is it architecture, dependency, scope, or environment?
+3. Analyze:
+   - Architecture: Does the fix require structural changes across crates?
+   - Dependency: Is a third-party crate causing the issue?
+   - Scope: Was the original issue too broadly defined?
+   - Environment: Is it platform or toolchain specific?
+
+## Recovery Options (present via ask_user)
+1. Rescope: Break the issue into smaller, independently-completable pieces.
+2. Rollback: git stash or git checkout to last known-good state, then retry with different approach.
+3. Redesign: Rethink the approach, maybe the breaking change path is needed.
+
+## OneCrawl Rollback Commands
+
+```bash
+git stash push -m "rollback: issue-id"
+git checkout v4.0.0-alpha.XX
+cargo check --workspace
+cargo test --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- --test-threads=1
+```
 
 ## Done Criteria
-- Issue has an approved recovery path and documented rationale.
+- Root cause identified and documented.
+- Recovery option selected and executed.
+- Gate passes after recovery.
 
 ## Anti-patterns
-- Blindly retrying same failing strategy
-- Silent rollback without traceability
-- Continuing without user alignment
+- Continuing to iterate without analyzing root cause
+- Ignoring test failures to move forward
+- Rolling back without understanding what went wrong

package/assets/skills/session-logging/SKILL.md

@@ -8,32 +8,62 @@ description: "Accurate, auditable execution journal for each working session."
 Maintain an accurate, auditable execution journal for each working session.
 
 ## Use when
-- Starting/ending a session
-- Completing issues/milestones
+- Starting or ending a session
+- Completing issues or milestones
 - Syncing GitHub status
 
-## Required File
-`sessions-<ISO-date>.md`
+## OneCrawl Session Template
 
-## Required Sections
-- Status (milestone states)
-- Work Completed (`[mX/iY]` references)
-- Completion Gate Passed (include ✅ and consecutive-pass evidence)
-- Decisions Made
-- Blockers
-- GitHub Sync (created/closed/updated issue IDs)
-- Branch
-- Date (ISO timestamp)
+```markdown
+# Session: YYYY-MM-DD
 
-## Procedure
-1. Create/update the session file at session start and after meaningful milestones.
-2. Keep entries factual and aligned with plan/GitHub state.
-3. Record gate-pass evidence per completed issue.
+## Status
+- Branch: main
+- Version: v4.0.0-alpha.XX
+- Mode: Autonomous / Interactive
+
+## Work Completed
+- [ ] Issue/feature description
+- [ ] Tests added/updated
+
+## Completion Gate Evidence
+- Clippy: 0 warnings (1 vendor)
+- Tests: XX passed, 0 failed
+- Build: cargo check clean
+
+## Decisions
+- Decision 1: rationale
+
+## Blockers
+- None / description
+
+## GitHub Sync
+- Commits pushed: X
+- Tags: vX.X.X-alpha.XX
+- npm: published vX.X.X-alpha.XX
+
+## OneCrawl Health
+- CLI: vX.X.X-alpha.XX
+- Binary: XXM
+- Daemon: running/stopped
+- Sessions: X active
+```
+
+## OneCrawl Version Bump Checklist
+1. Update version in `packages/onecrawl-rust/Cargo.toml`
+2. `cargo check --workspace` (propagates to all crates)
+3. Commit with `chore: bump version to vX.X.X-alpha.XX`
+4. `git tag vX.X.X-alpha.XX`
+5. `git push origin main --tags`
+6. Update `packages/onecrawl/package.json` version
+7. `node scripts/sync-assets.js`
+8. `npm publish --tag alpha --access public`
 
 ## Done Criteria
-- Session file reflects real progress and traceable references.
+- Session journal file exists with all required sections.
+- All status fields are accurate.
 
 ## Anti-patterns
-- Retroactive guesswork
-- Missing gate evidence
-- Inconsistent milestone/issue IDs
+- Missing completion gate evidence
+- Undocumented decisions
+- Stale version numbers

package/assets/skills/systematic-debugging/SKILL.md

@@ -47,10 +47,10 @@ Replace blind trial-and-error debugging with a structured, evidence-based proces
    - Terminal: `node app.js 2>&1 | tee debug-data.log`
    - Test runner: `npm test 2>&1 | tee debug-data.log`
    - Browser: copy console output into `debug-data.log`
-3. If using MCP tools, also collect:
-   - `chrome-devtools` → `list_console_messages` → append to `debug-data.log`
-   - `chrome-devtools` → `list_network_requests` → append failed/relevant requests
-   - `next-devtools` → `nextjs_call("get_errors")` → append runtime errors
+3. If using OneCrawl MCP tools, also collect:
+   - `onecrawl run browser get_console_messages` → append to `debug-data.log`
+   - `onecrawl har drain` → append failed/relevant requests
+   - `onecrawl health` → append daemon/session state
 
 ### Step 5 — Analyze
 1. Read `debug-data.log` and correlate with hypotheses.
@@ -73,20 +73,22 @@ Replace blind trial-and-error debugging with a structured, evidence-based proces
 
 ## MCP Tool Integration
 
-When available, prefer MCP tools over manual instrumentation:
+When available, prefer OneCrawl MCP tools over manual instrumentation:
 
 | Tool | Use for |
 |------|---------|
-| `chrome-devtools` → `list_console_messages` | Capture browser console output |
-| `chrome-devtools` → `evaluate_script` | Test hypotheses live in browser context |
-| `chrome-devtools` → `list_network_requests` | Debug API/network failures |
-| `chrome-devtools` → `get_network_request` | Inspect specific request/response bodies |
-| `chrome-devtools` → `take_screenshot` | Visual/layout bug evidence |
-| `chrome-devtools` → `take_memory_snapshot` | Memory leak investigation |
-| `next-devtools` → `nextjs_call("get_errors")` | Next.js runtime error collection |
-| `lighthouse` → performance audits | Performance regression debugging |
-| Terminal → `run_command` | Execute tests, capture output |
-| File system → `grep_search` | Trace error messages to source code |
+| `onecrawl run browser get_console_messages` | Capture browser console output |
+| `onecrawl eval "<expression>"` | Test hypotheses live in browser context |
+| `onecrawl run browser get_network_log` | Debug API/network failures |
+| `onecrawl har drain` | Inspect request/response bodies |
+| `onecrawl screenshot` | Visual/layout bug evidence |
+| `onecrawl stealth detection-audit` | Verify stealth patches are working |
+| `onecrawl health` | Check CLI/daemon/session state |
+| `onecrawl config show` | Verify configuration values |
+| `onecrawl page-watcher drain` | Monitor DOM changes |
+| `onecrawl network-log drain` | Live network traffic |
+| `cargo test -p <crate> -- test_name` | Run specific failing test |
+| `RUST_LOG=debug cargo test` | Verbose test output |
 
 ## Escalation
 If after **2 instrumentation → analysis cycles** the root cause is still unclear:

package/assets/skills/testing-policy/SKILL.md

@@ -17,21 +17,55 @@ Guarantee deterministic, CI-ready quality verification with no regressions and n
 - E2E tests (user-facing/critical flows, when applicable)
 - Non-regression checks (previously passing tests must remain green)
 
+## OneCrawl Test Commands
+
+```bash
+# Full test suite (excludes E2E and PyO3 — known linker issue in test mode)
+cargo test --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- --test-threads=1
+
+# Single crate (fast iteration)
+cargo test -p onecrawl-cli-rs -- --test-threads=1
+cargo test -p onecrawl-cdp -- --test-threads=1
+cargo test -p onecrawl-mcp-rs -- --test-threads=1
+
+# Run specific test
+cargo test -p onecrawl-cli-rs -- test_name --test-threads=1
+
+# Clippy as static analysis layer
+cargo clippy --workspace --exclude onecrawl-e2e --exclude onecrawl-python -- -W clippy::all
+```
+
+## Workspace Crate Map
+
+| Crate | Tests | Scope |
+|-------|-------|-------|
+| `onecrawl-cli-rs` | Unit | CLI dispatch, config, parsing |
+| `onecrawl-cdp` | Unit | CDP protocol, stealth, JS evaluation |
+| `onecrawl-mcp-rs` | Unit | MCP server, tool dispatch |
+| `onecrawl-core` | Unit | Shared types, utilities |
+| `onecrawl-crypto` | Unit | Encryption, TOTP, PKCE |
+| `onecrawl-parser` | Unit + Doc | HTML parsing, accessibility tree |
+| `onecrawl-storage` | Unit | KV storage, encrypted store |
+| `onecrawl-server` | Unit | HTTP API server |
+| `onecrawl-e2e` | E2E | **Excluded** — requires running Chrome |
+| `onecrawl-python` | Unit | **Excluded** — PyO3 linker issue |
+
 ## Procedure
-1. **Before changes**: run full suite and record baseline (totals + line/branch coverage).
+1. **Before changes**: run full suite and record baseline.
 2. Implement changes and add/update tests.
-3. **After changes**: rerun full suite and produce diff (added/removed/broken tests + coverage delta).
-4. If any previously passing test breaks or coverage drops, fix before completion.
+3. **After changes**: rerun full suite and verify no regressions.
+4. If any previously passing test breaks, fix before completion.
 5. Ensure tests are deterministic, isolated, non-interactive, and CI-compatible.
 
-## E2E Notes
-- Cover happy path + key edge/error cases for each critical flow.
-- Prefer stable selectors (`data-testid`) over fragile CSS/DOM coupling.
+## Key Rules
+- Use `--test-threads=1` — some tests share browser state.
+- Never use `#[ignore]` to skip failing tests.
+- VecDeque: use `.back()` not `.last()`, `.iter().skip(n)` not `[n..]`.
 
 ## Done Criteria
-- Full suite green, no regressions, coverage >= baseline.
+- Full suite green, no regressions.
 
 ## Anti-patterns
 - Manual-only validation
 - Flaky timeout-driven E2E
-- Merging with coverage regression
+- Merging with failing tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onecrawl",
-  "version": "4.0.0-alpha.55",
+  "version": "4.0.0-alpha.57",
   "description": "Browser automation engine — CLI, MCP server, and agent skills installer",
   "license": "BUSL-1.1",
   "author": "Giulio Leone <giulio@onecrawl.dev>",