@weavetab/skills 1.0.1 → 2.5.0-beta.4

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.4"
+---
+
+# 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`.

package/security/rbac-and-policies.md

@@ -0,0 +1,47 @@
+---
+id: rbac-and-policies
+domain: security
+triggers:
+  - "rbac"
+  - "security policy"
+  - "role boundaries"
+  - "viewer agent"
+  - "permission denied"
+tools:
+  - "browser_inspect"
+  - "browser_scrape"
+  - "browser_map"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Role-Based Access Control (RBAC) & Agent Guardrails
+
+Weavetab allows developers to run untrusted or lower-privilege subagents within strict security boundaries to prevent accidental destructive operations or data leaks.
+
+---
+
+## 1. The 4 Security Tiers
+
+| Tier | Name | Allowed Tools & Capabilities | Intended Role |
+| :--- | :--- | :--- | :--- |
+| **0** | `admin` | Full tool access (all 48 tools), plugin loading, arbitrary script eval, cookies/storage write. | Primary Operator / Lead Agent. |
+| **1** | `operator` | Interactive tools (`browser_click`, `browser_fill`, `browser_upload`), but blocked from loading untrusted plugins. | Standard Automation Agent. |
+| **2** | `automation` | Pre-approved deterministic macros (`browser_automation`), scoped form filling, no arbitrary script execution. | Background Cron / Worker. |
+| **3** | `viewer` | Read-only inspection tools (`browser_map`, `browser_find`, `browser_scrape`, `browser_inspect`). All click, type, and storage tools are rejected with `PERMISSION_DENIED`. | Research Subagents / Scrapers. |
+
+---
+
+## 2. Handling `PERMISSION_DENIED` Errors
+
+If an agent attempts an action outside its allocated role tier:
+```json
+{
+  "error_code": "PERMISSION_DENIED",
+  "message": "Tool 'browser_click' is disabled under role 'viewer'. Only read operations are permitted."
+}
+```
+
+### Protocol:
+1. Do not retry the denied tool.
+2. Delegate the interactive action to the parent agent or primary operator.
+3. Limit your output to findings gathered via read-only tools (`browser_scrape`, `browser_map`, `browser_inspect`).

package/security/secret-containment-protocol.md

@@ -0,0 +1,59 @@
+---
+id: secret-containment-protocol
+domain: security
+triggers:
+  - "enter password"
+  - "input credentials"
+  - "api key entry"
+  - "sensitive token"
+  - "secret containment"
+tools:
+  - "browser_type_secret"
+weavetab: ">=2.5.0-beta.4"
+---
+
+# Secret Containment Protocol & Zero-Bleed Execution
+
+AI agent transcripts, LLM providers, and tool logs represent massive attack surfaces for credential leaks. Weavetab enforces a hardware-grade **Zero-Bleed Security Guarantee** for sensitive inputs.
+
+---
+
+## 1. Entering Credentials with `browser_type_secret`
+
+Whenever an agent inputs passwords, two-factor backup codes, credit card numbers, or proprietary API keys, you MUST use `browser_type_secret`:
+
+```json
+{
+  "ref": "w:12",
+  "secret": "MySuperSecretPassword!2026",
+  "clear": true
+}
+```
+
+---
+
+## 2. The Zero-Bleed Guarantee Architecture
+
+When `browser_type_secret` is invoked:
+1. **CDP Interception**: The secret is typed via masked CDP synthetic key events.
+2. **HUD Redaction**: The browser Heads-Up Display (HUD) and visual overlay strictly renders bullets (`••••••••`).
+3. **Log Sanitization**: Console logs, MCP server logs, and JSON return values strip the secret string and return:
+   ```json
+   {
+     "success": true,
+     "message": "Secret typed successfully into ref 'w:12' (length: 26). Value redacted."
+   }
+   ```
+4. **No Re-Emission**: Never print or echo raw credentials into subsequent model thoughts or conversation messages.
+
+---
+
+## 3. Strict Operating Prohibition
+
+> [!CAUTION]
+> Under NO circumstances should an agent pass passwords or credentials to:
+> - `browser_type`
+> - `browser_fill`
+> - `browser_eval`
+> 
+> Doing so causes plaintext secrets to enter unmasked transcripts and tool logs.