@weavetab/skills 2.5.0 → 2.5.1

package/resilience/session-time-travel.md

@@ -1,131 +1,146 @@
----
-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"
----
-
-# 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"
-}
-```
-
+---
+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"
+---
+
+# 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",
+  "url": "https://example.com"
+}
+```
+
+Or inject an authentication cookie (one cookie per call):
+
+```json
+{
+  "action": "set",
+  "name": "session_token",
+  "value": "xyz123",
+  "domain": "example.com",
+  "path": "/",
+  "httpOnly": true,
+  "secure": true,
+  "sameSite": "Lax"
+}
+```
+
+Delete a cookie by name (and optionally domain/path):
+
+```json
+{
+  "action": "delete",
+  "name": "session_token",
+  "domain": "example.com"
+}
+```
+
+Accepted fields: `name`, `value`, `domain`, `path`, `expires` (Unix seconds), `httpOnly`, `secure`, `sameSite` (`Strict`/`Lax`/`None`), and `url` (for `get`).
+
+---
+
+## 5. Web Storage Inspection & Injection (`browser_storage`)
+
+Query or clear `localStorage` and `sessionStorage` keys. Choose the store with `scope`:
+
+```json
+{
+  "scope": "local",
+  "action": "get",
+  "key": "authToken"
+}
+```
+
+- **`scope`**: `"local"` or `"session"`.
+- **`action`**: `get`, `set`, `remove`, `list` (all keys + values), or `clear` (the whole scope).
+- **`key`** is required for `get`, `set`, and `remove`; **`value`** is required for `set`.
+

package/resilience/stale-ref-recovery.md

@@ -1,53 +1,61 @@
----
-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"
----
-
-# 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`.
+---
+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"
+---
+
+# 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 can invalidate a volatile `w:NN` handle between reads and actions.
+
+---
+
+## 1. The Multi-Tier Auto-Recovery Heuristic
+
+When a tool receives a detached or invalidated `ref`, Weavetab attempts to re-resolve it instead of failing immediately. The recovery runs a sub-5ms heuristic over these strategies (in order) and re-stamps `data-wt-id="NN"` onto the live node:
+
+```
+  [Action on w:14 fails / handle detached]
+                 │
+                 ▼
+  [1. Connected node + fingerprint check]
+                 │ (if not found)
+                 ▼
+  [2. Stored CSS selector]  (data-testid, id, class)
+                 │ (if not found)
+                 ▼
+  [3. Exact label / aria-label match]
+                 │ (if not found)
+                 ▼
+  [4. Placeholder / name attribute match]
+                 │ (if not found)
+                 ▼
+  [5. Fuzzy substring match]  (when label length >= 3)
+```
+
+The successful strategy is reported back to the agent (`stored_selector`, `exact_label`, `placeholder_or_name`, `fuzzy_label`). If every strategy misses, the tool returns a hard failure.
+
+---
+
+## 2. Agent Reactive Behavior
+
+If an action fails because all recovery strategies were exhausted, the tool returns one of:
+
+- `error_code: "ELEMENT_NOT_FOUND"` — the ref was in the cached map but no longer exists in the DOM.
+- `error_code: "FINGERPRINT_MISMATCH"` — an element exists but its tag/role fingerprint no longer matches; the DOM was likely rebuilt.
+
+Either way:
+
+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, or refresh handles with `browser_map`.
+3. **Execute the Action on the New Handle**: use the updated ref returned by `browser_find`/`browser_map`.

package/security/rbac-and-policies.md

@@ -1,47 +1,50 @@
----
-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"
----
-
-# 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`).
+---
+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"
+---
+
+# 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.
+
+Roles are configured per agent (in `config.json`). The server checks the role **before** launching a browser or resolving the target.
+
+---
+
+## 1. The 5 Security Roles
+
+| Role | Tool Access | Intended Use |
+| :--- | :--- | :--- |
+| `admin` | Full access (`*`). | Primary operator / lead agent. |
+| `operator` | Full access (`*`). | Standard automation agent. |
+| `automation` | Every tool except `browser_thoughts` — automation agents must be non-interactive. | Background cron / worker. |
+| `viewer` | Read-only set only: `browser_map`, `browser_find`, `browser_scrape`, `browser_console`, `browser_eval`, `browser_inspect`, `browser_extract_design`, `browser_snapshot`, `browser_screenshot`, `browser_pdf`, `browser_cookies`, `browser_tabs`, `browser_wait`, `browser_pattern_learn`. | Research subagents / scrapers. |
+| `system` | `browser_thoughts`, `browser_detect`, `browser_performance`, `browser_checkpoint`, `browser_pattern_learn`. | Internal/system operations. |
+
+Any other role value is treated as fully allowed.
+
+---
+
+## 2. Handling Permission Denials
+
+There is no JSON `error_code` for RBAC. A denied call fails with `isError: true` and a plain-text message prefixed with `[!]`:
+
+```
+[!] Role 'viewer' does not have permission to use 'browser_click'. Viewer role only permits read-only tools (map/find/scrape/console/eval/inspect/snapshot/pdf/cookies).
+```
+
+### Protocol:
+1. Do not retry the denied tool — the role will not change mid-session.
+2. Delegate the interactive action to the parent agent or a higher-privilege operator.
+3. Limit your output to findings gathered via read-only tools (`browser_scrape`, `browser_map`, `browser_inspect`).

package/security/secret-containment-protocol.md

@@ -1,59 +1,62 @@
----
-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"
----
-
-# 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.
+---
+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"
+---
+
+# 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`.
+
+`browser_type_secret` never accepts a plaintext secret. It reads the value from an **environment variable** on the host running the MCP server, so the secret never reaches the agent transcript. Set the variable first (e.g. `export PORTAL_PASSWORD="…"`), then reference it by key:
+
+```json
+{
+  "ref": "w:12",
+  "envKey": "PORTAL_PASSWORD"
+}
+```
+
+Accepted targeting parameters: `id` (alias `ref`) or `target` (CSS selector). `envKey` is **required**.
+
+---
+
+## 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.