@weavetab/skills 1.0.3 → 2.5.0-beta.5

package/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.5"
+---
+
+# 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/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.5"
+---
+
+# 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.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/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.5"
+---
+
+# 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/package.json

@@ -1,15 +1,28 @@
 {
   "name": "@weavetab/skills",
-  "version": "1.0.3",
-  "description": "Supercharge your AI Agents with Weavetab MCP Skills. Native drop-in skills for Antigravity, Cursor, Cline, and more.",
-  "author": "fy2ne",
+  "version": "2.5.0-beta.5",
+  "description": "Supercharge your AI Agents with Weavetab MCP Skills. Domain-driven agent intelligence for Antigravity, Cursor, Cline, Windsurf, and more.",
+  "author": {
+    "name": "fy2ne",
+    "email": "hello@fy2ne.me",
+    "url": "https://fy2ne.me"
+  },
   "license": "MIT",
   "files": [
     "bin",
-    "general",
-    "automation",
-    "advanced",
     "src",
+    "dist",
+    "ROUTER.md",
+    "browser",
+    "desktop",
+    "memory",
+    "resilience",
+    "security",
+    "plugins",
+    "network-and-perf",
+    "documents",
+    "developer",
+    "evals",
     "skills.json"
   ],
   "repository": {
@@ -23,6 +36,8 @@
   "keywords": [
     "weavetab",
     "weavetab-mcp",
+    "weavetab-skills",
+    "weavetab-plugins",
     "mcp",
     "ai-agent",
     "cursor",
@@ -30,10 +45,16 @@
     "antigravity",
     "browser-automation",
     "agent-skills",
-    "openclaw"
+    "openclaw",
+    "plugins",
+    "skills",
+    "agentic"
   ],
+  "peerDependencies": {
+    "@weavetab/mcp": "2.5.0-beta.5"
+  },
   "peerDependenciesMeta": {
-    "weavetab": {
+    "@weavetab/mcp": {
       "optional": true
     }
   },
@@ -42,7 +63,8 @@
     "skills": "bin/cli.js"
   },
   "scripts": {
-    "build": "node scripts/build.js"
+    "build": "node scripts/build.js",
+    "test": "node evals/evaluator.js"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.3.1",

package/plugins/hooks-and-overrides.md

@@ -0,0 +1,35 @@
+---
+id: hooks-and-overrides
+domain: plugins
+triggers:
+  - "plugin hooks"
+  - "before tool call"
+  - "after tool call"
+  - "telemetry interception"
+  - "sdk hooks"
+tools: []
+weavetab: ">=2.5.0-beta.5"
+---
+
+# 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/plugins/plugin-runtime.md

@@ -0,0 +1,63 @@
+---
+id: plugin-runtime
+domain: plugins
+triggers:
+  - "what plugins are installed"
+  - "weavetab plugin"
+  - "extend mcp"
+  - "plugin tools"
+  - "plugin permissions"
+tools: []
+weavetab: ">=2.5.0-beta.5"
+---
+
+# Plugin Runtime: Weavetab Plugin Architecture
+
+Weavetab features an extensible plugin architecture powered by `@weavetab/sdk`. All installed plugins are loaded automatically at server startup — their tools appear directly in the MCP tool list alongside built-in tools. Agents never need to discover or activate plugins manually.
+
+---
+
+## 1. How Plugin Tools Appear
+
+Plugin tools are first-class MCP tools. If `@weavetab/plugin-recaptcha-solver` is installed, `captcha_solve_token` appears in the tool list immediately on startup — no discovery step needed.
+
+There are **no** `list_plugins` or `load_plugin` tools. Managing plugins is a CLI operation:
+
+```bash
+# Install a plugin (restart required)
+weavetab plugin add @weavetab/plugin-youtube
+
+# Remove a plugin
+weavetab plugin rm @weavetab/plugin-youtube
+
+# List installed plugins
+weavetab plugin list
+```
+
+---
+
+## 2. Plugin Permission Model
+
+Every plugin declares what it can do in `weavetab.json`. The runtime enforces this at load time:
+
+| Permission | What it gates |
+|---|---|
+| `tools.add: true` | Plugin can register new MCP tools |
+| `tools.override: ["browser_navigate"]` | Plugin can wrap/replace that built-in tool |
+| `tools.remove: ["browser_pdf"]` | Plugin can disable that built-in tool |
+| `hooks.onBeforeAction: true` | Plugin can intercept all tool calls before execution |
+| `hooks.onAfterAction: true` | Plugin can inspect/transform all tool results |
+
+Plugins that attempt to exceed their declared permissions are blocked with a stderr warning — they do not crash.
+
+---
+
+## 3. Trust Tiers
+
+| Tier | Badge | Condition |
+|---|---|---|
+| Official | `✚ [Official]` | `@weavetab/plugin-*` packages |
+| Verified | `✔ [Verified]` | Listed in the Weavetab verified registry |
+| Unverified | `⚠ [Unverified]` | Unknown community package |
+
+Unverified plugins are loaded but their permissions are logged visibly at startup for user review.

package/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.5"
+---
+
+# 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`.

package/resilience/session-time-travel.md

@@ -0,0 +1,131 @@
+---
+id: session-time-travel
+domain: resilience
+triggers:
+  - "time travel"
+  - "browser checkpoint"
+  - "rollback session"
+  - "save state"
+  - "restore cookies"
+tools:
+  - "browser_checkpoint"
+  - "browser_cookies"
+  - "browser_storage"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# Session Time-Travel & Instant State Rollback
+
+In complex multi-step workflows (e.g. checkout funnels, multi-page configuration wizards, onboarding questionnaires), an error at Step 7 traditionally forces an agent to reload the root URL, re-authenticate, and waste 10+ turns repeating steps.
+
+`browser_checkpoint` enables instantaneous time-travel by snapshotting and restoring complete browser session state.
+
+---
+
+## 1. What a Checkpoint Captures
+
+A single named checkpoint atomically preserves:
+- **Cookies**: Full domain cookies including `HttpOnly`, `Secure`, and `SameSite` flags.
+- **Web Storage**: Entire `localStorage` and `sessionStorage` key-value maps.
+- **Navigation State**: Exact page URL, scroll positions (`x`, `y`), and page title.
+
+---
+
+## 2. Checkpoint Operations
+
+### A. Saving a Checkpoint (`save`)
+Create a checkpoint right before undertaking risky, branching, or destructive actions:
+
+```json
+{
+  "action": "save",
+  "name": "pre_checkout_authenticated"
+}
+```
+
+### B. Restoring a Checkpoint (`restore`)
+If a downstream step errors out, times out, or hits an invalid state, roll back immediately:
+
+```json
+{
+  "action": "restore",
+  "name": "pre_checkout_authenticated"
+}
+```
+*Latency: ~15ms*. The page navigates back to the checkpoint URL with cookies and storage atomically injected.
+
+### C. Listing Checkpoints (`list`)
+Inspect all active checkpoints for the current page target:
+
+```json
+{
+  "action": "list"
+}
+```
+
+### D. Cleaning Up (`delete`)
+Free memory once a workflow has concluded:
+
+```json
+{
+  "action": "delete",
+  "name": "pre_checkout_authenticated"
+}
+```
+
+---
+
+## 3. High-Leverage Agent Pattern
+
+```
+1. Authenticate to Target Portal
+2. browser_checkpoint({ action: "save", name: "auth_ready" })
+3. Attempt automated action sequence (e.g. form filling or testing)
+4. IF error occurs:
+     browser_checkpoint({ action: "restore", name: "auth_ready" })
+     -> Agent is immediately back at authenticated state without re-login!
+```
+
+---
+
+## 4. Fine-Grained Cookie Management (`browser_cookies`)
+
+Inspect, set, or delete individual browser session cookies without restoring an entire checkpoint:
+
+```json
+{
+  "action": "get",
+  "urls": ["https://example.com"]
+}
+```
+
+Or inject an authentication cookie:
+```json
+{
+  "action": "set",
+  "cookies": [
+    {
+      "name": "session_token",
+      "value": "xyz123",
+      "domain": "example.com",
+      "httpOnly": true,
+      "secure": true
+    }
+  ]
+}
+```
+
+---
+
+## 5. Web Storage Inspection & Injection (`browser_storage`)
+
+Query or clear `localStorage` and `sessionStorage` keys:
+
+```json
+{
+  "storageType": "localStorage",
+  "action": "get",
+  "key": "authToken"
+}
+```
+

package/resilience/stale-ref-recovery.md

@@ -0,0 +1,53 @@
+---
+id: stale-ref-recovery
+domain: resilience
+triggers:
+  - "stale element reference"
+  - "detached from dom"
+  - "spa re-render"
+  - "react hydration"
+  - "element not found"
+tools:
+  - "browser_find"
+  - "browser_map"
+  - "browser_click"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# Stale Ref Recovery & SPA Hydration Resilience
+
+In modern Single Page Applications (built with React, Next.js, Vue, Nuxt, Svelte), DOM nodes are frequently destroyed and recreated during client-side hydration or reactive state updates. This often causes `STALE_ELEMENT_REFERENCE` or `NODE_DETACHED` errors when an agent attempts an action.
+
+---
+
+## 1. The 4-Tier Auto-Recovery Chain
+
+When a tool receives a stale or missing `ref`, Weavetab does not immediately fail. It activates an internal 4-tier recovery chain:
+
+```
+  [Action on w:14 Fails / Stale]
+                │
+                ▼
+  [Tier 1: Stored Selector] ──▶ Re-queries cached stable selector (data-testid, id)
+                │ (if not found)
+                ▼
+  [Tier 2: Exact Label Match] ──▶ Queries element with identical visible text & tag
+                │ (if not found)
+                ▼
+  [Tier 3: Semantic Role Match] ──▶ Queries nearest sibling with matching ARIA role
+                │ (if not found)
+                ▼
+  [Tier 4: Fuzzy Match] ──▶ Re-anchors to highest-confidence visual candidate
+```
+
+If the recovery chain succeeds, the action executes seamlessly and the return payload notifies the agent that the handle was refreshed.
+
+---
+
+## 2. Agent Reactive Behavior
+
+If an action returns `ERROR: STALE_ELEMENT_REFERENCE` because all 4 recovery tiers were exhausted:
+
+1. **Do NOT Repeat the Identical Call**: Retrying the exact same stale `ref` (`w:14`) will fail again.
+2. **Execute a Fast Targeted Lookup**: Run `browser_find` with the text of the button or input field.
+3. **Execute the Action on the New Handle**: Use the updated handle returned by `browser_find`.