@weavetab/skills 1.0.1 → 2.5.0-beta.4

package/dist/granular/memory_site-learning.md

@@ -0,0 +1,180 @@
+---
+id: site-learning
+domain: memory
+triggers:
+  - "site learning"
+  - "workflow pattern"
+  - "learn site"
+  - "remember workflow"
+  - "site memory"
+  - "cookie banner quirk"
+  - "fast path replay"
+  - "pattern reliability"
+  - "pattern compiler"
+tools:
+  - "browser_pattern_learn"
+  - "browser_burst"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Site Learning — Autonomous Workflow Memory
+
+Weavetab's Site Learning engine accumulates cross-session knowledge about websites and multi-step automation flows. Each site gets one profile file at ~/.weavetab-system/memory/sites/<origin>.json — never duplicated, always merged on write.
+
+---
+
+## 1. Session Start Protocol
+
+On every session visiting a known or potentially-known site, run:
+
+`json
+{ "tool": "browser_pattern_learn", "action": "get", "origin": "https://github.com" }
+`
+
+Parse the response:
+- known: false → site is new, proceed exploratorily, teach after completion
+- known_patterns → list of named workflows with reliability scores
+- quirks → auto-handle any listed quirks (cookie banners, rate limits) before main task
+- ramework → adjust interaction strategy accordingly (React, Vue, etc.)
+
+---
+
+## 2. Fast-Path vs. Exploratory Decision
+
+Use the _hint field or individual 
+
+| Reliability | Strikes | Strategy |
+|---|---|---|
+| ≥ 0.8, strikes = 0 | ✓ | **Fast path**: replay steps via rowser_burst directly |
+| 0.5–0.79 | 0–1 | **Cautious path**: replay steps, verify success_indicator after each critical step |
+| < 0.5 | any | **Re-explore**: navigate manually, collect correct steps, then teach |
+| any | ≥ 3 | **Re-learn**: ignore cached pattern, re-explore, then call rowser_pattern_learn with updated steps |
+
+---
+
+## 3. Quirk Auto-Handling
+
+If a profile has known quirks, resolve them immediately after navigation before executing your main task:
+
+`
+Profile quirks: { cookie_banner: { selector: "#cookie-consent", action: "click .accept-all", appears: "first_visit" } }
+`
+
+Execute the action before doing anything else. Never spend reasoning turns on a known dismissible popup.
+
+---
+
+## 4. Teaching a Workflow Pattern
+
+After successfully completing a multi-step flow for the first time (or after re-learning):
+
+`json
+{
+  "tool": "browser_pattern_learn",
+  "origin": "https://github.com",
+  "action": "learn",
+  "name": "login_flow",
+  "steps": [
+    { "tool": "browser_navigate", "target": "https://github.com/login" },
+    { "tool": "browser_fill", "target": "#login_field", "value": "{{username}}" },
+    { "tool": "browser_fill", "target": "#password", "value": "{{password}}" },
+    { "tool": "browser_click", "target": "[type=submit]" }
+  ],
+  "success_indicator": "a[aria-label='Homepage']",
+  "entry": "/login"
+}
+`
+
+**Pattern Naming Rules**:
+- Use snake_case
+- Be descriptive: login_flow, pr_review, csv_export, checkout_flow
+- Duplicate name on same origin = **update** (merge), never creates a second pattern
+
+**Step Quality Rules**:
+- Use semantic selectors: data-testid, id, ria-label, readable text-based selectors
+- Avoid: .hash_abc123, div:nth-child(4), deep anonymous chains like div > div > div > span
+  (the engine automatically drops volatile selectors during compilation)
+- For sensitive inputs, record the step with a placeholder like {{username}} — never hardcode credentials
+
+---
+
+## 5. Reliability Upkeep After Replay
+
+Every time you replay a pattern, report the outcome:
+
+`json
+{
+  "tool": "browser_pattern_learn",
+  "origin": "https://github.com",
+  "action": "record_execution",
+  "name": "login_flow",
+  "success": true,
+  "duration_ms": 3100
+}
+`
+
+The engine uses EWMA (α=0.15) to update the reliability score:
+- Success run → reliability climbs toward 1.0 slowly
+- Failure run → reliability drops; 3 consecutive failures trigger [RE-LEARN NEEDED] flag
+
+---
+
+## 6. Recording a New Quirk
+
+When you encounter a cookie consent modal, popup, or rate limit for the first time:
+
+`json
+{
+  "tool": "browser_pattern_learn",
+  "origin": "https://example.com",
+  "action": "record_quirk",
+  "quirk_key": "cookie_banner",
+  "quirk_data": {
+    "selector": "#cookie-consent",
+    "action": "click .accept-all",
+    "appears": "first_visit"
+  }
+}
+`
+
+Supported quirk_key values: cookie_banner, 
+
+For rate limits:
+`json
+{
+  "quirk_key": "rate_limit",
+  "quirk_data": { "threshold": "60req/min", "recovery": "wait 30s" }
+}
+`
+
+---
+
+## 7. Anti-Patterns to Avoid
+
+- **Never create per-session pattern names** like login_2026_09_16 — one name per workflow per origin, forever updated in place.
+- **Never call rowser_pattern_learn in a loop** — one call per workflow completion. The write is idempotent (skips disk write if nothing changed).
+- **Never store credentials in steps** — use placeholders or rowser_type_secret in actual execution.
+- **Never write to ~/.weavetab/** — all memory belongs in ~/.weavetab-system/memory/sites/.
+
+---
+
+## 8. Full Session Example: GitHub PR Review
+
+`
+1. browser_pattern_learn { action: "get", origin: "https://github.com" }
+   → patterns: { pr_review: { reliability: 0.95, steps: 3 } }
+   → quirks: {} (none)
+
+2. Since reliability=0.95 (≥ 0.8): use fast path
+   browser_burst with the 3 stored steps
+
+3. After completion:
+   browser_pattern_learn {
+     action: "record_execution",
+     name: "pr_review",
+     success: true,
+     duration_ms: 2800
+   }
+`
+
+Total agent turns for a known site: **3 tool calls** vs. potentially 12+ with full exploration.

package/dist/granular/network-and-perf_device-and-environment.md

@@ -0,0 +1,87 @@
+---
+id: device-and-environment
+domain: network-and-perf
+triggers:
+  - "emulate device"
+  - "mobile view"
+  - "throttle network"
+  - "geolocation override"
+  - "user agent"
+  - "responsive testing"
+tools:
+  - "browser_emulate"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Device Emulation & Environment Simulation
+
+Auditing mobile responsive layouts, testing geographic restrictions, and simulating degraded network conditions can all be accomplished with `browser_emulate`.
+
+---
+
+## 1. Device Presets & Viewport Simulation
+
+Switch from desktop to realistic mobile hardware profiles:
+
+```json
+{
+  "device": "iPhone 15 Pro",
+  "orientation": "portrait"
+}
+```
+
+Or configure custom screen geometries:
+
+```json
+{
+  "viewport": {
+    "width": 393,
+    "height": 852,
+    "deviceScaleFactor": 3,
+    "isMobile": true,
+    "hasTouch": true
+  }
+}
+```
+
+---
+
+## 2. Network Throttling Simulation
+
+Verify how web applications degrade under poor connectivity:
+
+```json
+{
+  "network": {
+    "offline": false,
+    "downloadThroughput": 1024 * 500, // 500 kb/s (Slow 3G)
+    "uploadThroughput": 1024 * 250,
+    "latency": 400 // ms
+  }
+}
+```
+
+---
+
+## 3. Geolocation & Timezone Overrides
+
+Bypass localized IP redirects or verify localized content rendering:
+
+```json
+{
+  "geolocation": {
+    "latitude": 37.7749,
+    "longitude": -122.4194,
+    "accuracy": 100
+  },
+  "timezoneId": "America/Los_Angeles",
+  "locale": "en-US"
+}
+```
+
+To reset all overrides back to default host system parameters:
+```json
+{
+  "reset": true
+}
+```

package/dist/granular/network-and-perf_network-intercept-and-mock.md

@@ -0,0 +1,84 @@
+---
+id: network-intercept-and-mock
+domain: network-and-perf
+triggers:
+  - "mock api"
+  - "intercept network"
+  - "stub request"
+  - "inspect tls"
+  - "ssl certificate"
+  - "network waterfall"
+tools:
+  - "browser_network_intercept"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Network Interception, Mocking & TLS Forensics
+
+Autonomous testing and debugging often require simulating backend error states (e.g. 500 Internal Server Error, 429 Rate Limit), stubbing third-party analytics, or verifying TLS/SSL certificates.
+
+`browser_network_intercept` provides fine-grained CDP request and response modification.
+
+---
+
+## 1. Mocking API Responses
+
+Intercept outgoing HTTP requests matching a URL pattern and return custom mock data:
+
+```json
+{
+  "pattern": "*/api/v1/user/profile",
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "body": "{\"id\": \"usr_test\", \"role\": \"admin\", \"credits\": 9999}"
+  }
+}
+```
+
+---
+
+## 2. Blocking Unnecessary Traffic & Trackers
+
+Accelerate page loads and eliminate token bloat by aborting non-essential requests:
+
+```json
+{
+  "pattern": "*google-analytics.com*",
+  "action": "abort",
+  "errorReason": "BlockedByClient"
+}
+```
+
+---
+
+## 3. TLS / SSL Forensics & Timing Waterfalls
+
+Extract cryptographic handshake metadata, cipher suites, expiration dates, and microsecond network waterfalls (DNS lookup, TCP connect, SSL handshake, TTFB):
+
+```json
+{
+  "action": "auditTls",
+  "url": "https://weavetab.pages.dev"
+}
+```
+
+### Response Example:
+```json
+{
+  "security": {
+    "protocol": "TLS 1.3",
+    "cipher": "AES_128_GCM",
+    "issuer": "Let's Encrypt",
+    "validTo": "2026-11-15T00:00:00.000Z"
+  },
+  "waterfall": {
+    "dnsMs": 1.4,
+    "tcpMs": 3.2,
+    "sslMs": 4.1,
+    "ttfbMs": 12.8
+  }
+}
+```

package/dist/granular/network-and-perf_performance-and-vitals.md

@@ -0,0 +1,84 @@
+---
+id: performance-and-vitals
+domain: network-and-perf
+triggers:
+  - "measure performance"
+  - "core web vitals"
+  - "lcp"
+  - "cls"
+  - "fcp"
+  - "wait condition"
+  - "page slow"
+tools:
+  - "browser_performance"
+  - "browser_wait"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Performance Forensics & Core Web Vitals
+
+Optimizing agent execution and auditing client performance requires objective metrics rather than arbitrary sleep timers.
+
+---
+
+## 1. Core Web Vitals Auditing (`browser_performance`)
+
+Retrieve Google Core Web Vitals, memory consumption, and frame rendering bottlenecks directly from the Chromium engine:
+
+```json
+{
+  "metrics": ["vitals", "memory", "navigationTiming"]
+}
+```
+
+### Response Example:
+```json
+{
+  "vitals": {
+    "fcp": 320,
+    "lcp": 780,
+    "cls": 0.012,
+    "fid": 8,
+    "inp": 45
+  },
+  "memory": {
+    "jsHeapUsedSizeMb": 42.1,
+    "jsHeapTotalSizeMb": 68.4
+  }
+}
+```
+
+---
+
+## 2. Deterministic Synchronization (`browser_wait`)
+
+> [!WARNING]
+> NEVER call arbitrary fixed sleep timers (e.g. `sleep 5000`). Fixed sleeps waste user time and still fail when network latency spikes.
+
+Always synchronize with deterministic browser conditions:
+
+### Wait for Network Idle:
+```json
+{
+  "condition": "network_idle",
+  "timeout": 10000
+}
+```
+
+### Wait for DOM Mutation Stability:
+```json
+{
+  "condition": "dom_stable",
+  "duration": 500,
+  "timeout": 10000
+}
+```
+
+### Wait for a Specific Element to Appear:
+```json
+{
+  "condition": "element_visible",
+  "selector": "[data-testid=\"checkout-complete\"]",
+  "timeout": 15000
+}
+```

package/dist/granular/plugins_hooks-and-overrides.md

@@ -0,0 +1,36 @@
+---
+id: hooks-and-overrides
+domain: plugins
+triggers:
+  - "plugin hooks"
+  - "before tool call"
+  - "after tool call"
+  - "telemetry interception"
+  - "sdk hooks"
+tools:
+  - "list_plugins"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Plugin Hooks & Lifecycle Overrides
+
+Plugins built with `@weavetab/sdk` register lifecycle hooks that run before and after tool executions. Understanding these hooks helps agents interpret metadata and custom tool responses.
+
+---
+
+## 1. Supported Plugin Hooks
+
+1. **`beforeToolCall(toolName, args)`**:
+   - Validates arguments against custom enterprise schemas.
+   - Injects tenant IDs, authentication headers, or proxy routing.
+2. **`afterToolCall(toolName, result, durationMs)`**:
+   - Emits OpenTelemetry metrics and timing waterfalls to external APM platforms.
+   - Enriches return objects with contextual metadata.
+3. **`onNavigate(url, targetId)`**:
+   - Triggers automated cookie injection or session setup upon page navigation.
+
+---
+
+## 2. Agent Operational Awareness
+
+When plugins are active, tool return payloads may include an optional `_pluginMetadata` object containing trace IDs, custom metrics, or security audit timestamps. Agents should treat this object as informational telemetry.

package/dist/granular/plugins_plugin-runtime.md

@@ -0,0 +1,60 @@
+---
+id: plugin-runtime
+domain: plugins
+triggers:
+  - "list plugins"
+  - "load plugin"
+  - "install plugin"
+  - "weavetab plugin"
+  - "extend mcp"
+tools:
+  - "list_plugins"
+  - "load_plugin"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Plugin Runtime: Dynamic Extension Loading
+
+Weavetab features an extensible plugin architecture powered by `@weavetab/sdk`. Agents can query loaded extensions and dynamically load community or official plugins into the live MCP runtime without restarting the server.
+
+---
+
+## 1. Inspecting Active Plugins (`list_plugins`)
+
+Discover all installed plugins, their versions, and the tools or hooks they expose:
+
+```json
+{}
+```
+
+### Response Example:
+```json
+{
+  "plugins": [
+    {
+      "name": "@weavetab/plugin-recaptcha-solver",
+      "version": "1.2.0",
+      "status": "active",
+      "toolsProvided": ["captcha_solve_token"],
+      "hooks": ["beforeToolCall"]
+    }
+  ]
+}
+```
+
+---
+
+## 2. Dynamic Runtime Loading (`load_plugin`)
+
+Load a verified plugin package into the active runtime session:
+
+```json
+{
+  "name": "@weavetab/plugin-datadog-tracer"
+}
+```
+
+### Plugin Verification Guarantees:
+- Plugins must implement the `@weavetab/sdk` standard interface.
+- Loaded tools become immediately callable by the agent in subsequent turns.
+- If an agent is in the `viewer` RBAC tier, `load_plugin` is rejected with `PERMISSION_DENIED`.

package/dist/granular/resilience_loop-breaker.md

@@ -0,0 +1,67 @@
+---
+id: loop-breaker
+domain: resilience
+triggers:
+  - "loop detected"
+  - "stuck in loop"
+  - "reset loop counter"
+  - "captcha detected"
+  - "hcaptcha"
+  - "recaptcha"
+tools:
+  - "browser_map"
+  - "browser_console"
+  - "browser_captcha"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Loop Breaker & CAPTCHA Escalation Protocol
+
+Agents can get trapped in repetitive click loops when a button does not advance the state (e.g. failing silent validation, unhandled reCAPTCHA challenges, or modals swallowing events). Weavetab actively monitors repetitive patterns and provides circuit breakers.
+
+---
+
+## 1. Loop Detection & Strike Reset (`browser_map`)
+
+Weavetab tracks the sequence of identical or near-identical tool invocations. If an agent calls `browser_click` or `browser_type` on the same selector or ref repeatedly without URL or major DOM mutations, the server raises a `STUCK_LOOP_WARNING`.
+
+### How to Break the Loop:
+1. **Analyze Why the Action Failed**: Check `browser_console` for JavaScript errors:
+   ```json
+   { "action": "read" }
+   ```
+   Or use `browser_map` to see if a validation banner or unhandled modal appeared.
+2. **Reset the Circuit Breaker**:
+   - Re-map with `force: true` to bypass the map skip guard, refresh the DOM view, and automatically clear loop strikes:
+     ```json
+     { "force": true }
+     ```
+
+---
+
+## 2. CAPTCHA Handling Protocol (`browser_captcha`)
+
+When an automated flow is blocked by Cloudflare Turnstile, Google reCAPTCHA, or hCaptcha, do NOT repeatedly click random coordinates.
+
+Invoke `browser_captcha` to analyze and manage the challenge:
+
+```json
+{
+  "action": "detect"
+}
+```
+
+### Response Example:
+```json
+{
+  "detected": true,
+  "type": "turnstile",
+  "provider": "cloudflare",
+  "interactive": true,
+  "ref": "w:99"
+}
+```
+
+### Action Strategy:
+1. If the challenge is interactive and requires human intervention (e.g. image classification), inform the user cleanly or request human bypass.
+2. If the challenge is a simple checkbox Turnstile widget, pass `"action": "solve"` or click the detected widget ref with `browser_click`.