@weavetab/skills 2.5.0 → 2.5.2

package/documents/canvas-and-visual-capture.md

@@ -1,103 +1,117 @@
----
-id: canvas-and-visual-capture
-domain: documents
-triggers:
-  - "take screenshot"
-  - "capture viewport"
-  - "export pdf"
-  - "canvas inspection"
-  - "extract design tokens"
-tools:
-  - "browser_screenshot"
-  - "browser_viewport"
-  - "browser_canvas"
-  - "browser_pdf"
-  - "browser_extract_design"
-  - "browser_map"
-  - "browser_click"
-weavetab: ">=2.5.0"
----
-
-# Visual Capture, Canvas Forensics & Design Extraction
-
-Beyond textual DOM manipulation, modern web applications contain dynamic HTML5 canvas renderings (charts, maps, WebGL games), and agents often need high-fidelity visual artifacts.
-
----
-
-## 1. Targeted Screenshots (`browser_screenshot`)
-
-Capture full page layouts, the visible viewport, or specific element bounding boxes:
-
-```json
-{
-  "fullPage": true,
-  "format": "png"
-}
-```
-
-Or target a specific element ref:
-```json
-{
-  "ref": "w:55",
-  "format": "jpeg",
-  "quality": 80
-}
-```
-
----
-
-## 2. PDF Document Generation (`browser_pdf`)
-
-Render the current page into a print-ready PDF document with print CSS styles applied:
-
-```json
-{
-  "landscape": false,
-  "printBackground": true,
-  "paperWidth": 8.5,
-  "paperHeight": 11
-}
-```
-
----
-
-## 3. HTML5 Canvas Pixel Inspection & Visual Grounding (`browser_canvas` & `browser_map`)
-
-When a chart or graphic is rendered via `<canvas>`, standard DOM reading tools cannot see individual buttons or nodes. You have two strategies:
-
-### A. Set-of-Marks Visual Grounding (Recommended for Canvas UIs & WebGL)
-Run `browser_map({ visual: "auto" })`. It detects canvas elements and high-contrast regions, attaches numbered badges `[1]…[N]`, and returns an annotated image:
-```json
-{
-  "visual": "auto"
-}
-```
-Then interact directly by mark number without guessing pixel coordinates:
-```json
-{
-  "mark": 3
-}
-```
-
-### B. Direct Canvas Pixel Export (`browser_canvas`)
-To extract the raw image data or draw programmatic gesture paths:
-```json
-{
-  "ref": "w:19",
-  "action": "toDataURL"
-}
-```
-
----
-
-## 4. Design System Extraction (`browser_extract_design`)
-
-Reverse-engineer UI stylesheets, active CSS custom properties (variables), typography scales, and color palettes:
-
-```json
-{
-  "selector": ".antigravity-hud-panel"
-}
-```
-
-Returns structured JSON representing colors, font families, shadows, and spacing tokens.
+---
+id: canvas-and-visual-capture
+domain: documents
+triggers:
+  - "take screenshot"
+  - "capture viewport"
+  - "export pdf"
+  - "canvas inspection"
+  - "extract design tokens"
+tools:
+  - "browser_screenshot"
+  - "browser_viewport"
+  - "browser_canvas"
+  - "browser_pdf"
+  - "browser_extract_design"
+  - "browser_map"
+  - "browser_click"
+weavetab: ">=2.5.0"
+---
+
+# Visual Capture, Canvas Forensics & Design Extraction
+
+Beyond textual DOM manipulation, modern web applications contain dynamic HTML5 canvas renderings (charts, maps, WebGL games), and agents often need high-fidelity visual artifacts.
+
+---
+
+## 1. Targeted Screenshots (`browser_screenshot`)
+
+Capture full page layouts, the visible viewport, or specific element bounding boxes:
+
+```json
+{
+  "fullPage": true,
+  "format": "png"
+}
+```
+
+Or crop to a specific element by CSS selector, or to a pixel rectangle with `clip`:
+```json
+{
+  "selector": "#pricing-table",
+  "format": "jpeg",
+  "quality": 80
+}
+```
+
+Options: `format` (`png` default, or `jpeg`), `quality` (JPEG only), `fullPage`, `selector`, and `clip` (`{x, y, width, height}`).
+
+---
+
+## 2. PDF Document Generation (`browser_pdf`)
+
+Render the current page into a print-ready PDF file:
+
+```json
+{
+  "filename": "report.pdf",
+  "landscape": false,
+  "scale": 1.0,
+  "pageRanges": "1-5",
+  "margin": { "top": 0.4, "bottom": 0.4, "left": 0.4, "right": 0.4 }
+}
+```
+
+Options: `filename` (defaults to `capture_<timestamp>.pdf`), `landscape`, `scale` (default 1.0), `pageRanges` (e.g. `"1-5"`, empty for all), and `margin` — either a single number in inches or a `{top,bottom,left,right}` object (default 0.4).
+
+---
+
+## 3. HTML5 Canvas Pixel Inspection & Visual Grounding (`browser_canvas` & `browser_map`)
+
+When a chart or graphic is rendered via `<canvas>`, standard DOM reading tools cannot see individual buttons or nodes. You have two strategies:
+
+### A. Set-of-Marks Visual Grounding (Recommended for Canvas UIs & WebGL)
+Run `browser_map({ visual: "auto" })`. It detects canvas elements and high-contrast regions, attaches numbered badges `[1]…[N]`, and returns an annotated image:
+```json
+{
+  "visual": "auto"
+}
+```
+Then interact directly by mark number without guessing pixel coordinates:
+```json
+{
+  "mark": 3
+}
+```
+
+### B. Direct Canvas Pixel Export (`browser_canvas`)
+To export the raw canvas as an image, or simulate a drag/gesture path across it:
+```json
+{
+  "ref": "w:19",
+  "action": "get_image"
+}
+```
+
+For drawing or selecting a region, pass `"action": "draw"` with a `points` array of `{x, y}` positions (relative to the canvas):
+```json
+{
+  "action": "draw",
+  "selector": "canvas#chart",
+  "points": [ { "x": 40, "y": 10 }, { "x": 200, "y": 120 } ]
+}
+```
+
+---
+
+## 4. Design System Extraction (`browser_extract_design`)
+
+Reverse-engineer UI stylesheets, active CSS custom properties (variables), typography scales, and color palettes:
+
+```json
+{
+  "selector": ".antigravity-hud-panel"
+}
+```
+
+Returns structured JSON representing colors, font families, shadows, and spacing tokens.

package/documents/office-document-ingestion.md

@@ -1,63 +1,91 @@
----
-id: office-document-ingestion
-domain: documents
-triggers:
-  - "read excel"
-  - "read docx"
-  - "parse csv"
-  - "spreadsheet"
-  - "word document"
-  - "parse table"
-tools:
-  - "browser_office"
-weavetab: ">=2.5.0"
----
-
-# Office Document Ingestion: Word, Excel & CSV Parsing
-
-Agents frequently need to parse structured spreadsheets or corporate documents downloaded during automation runs. `browser_office` parses `.docx`, `.xlsx`, `.xls`, and `.csv` files directly into clean JSON structures.
-
----
-
-## 1. Parsing Spreadsheets (`.xlsx`, `.csv`)
-
-Stream structured sheet data, headers, and cell values:
-
-```json
-{
-  "filePath": "C:/Users/fy2ne/Downloads/quarterly_revenue.xlsx",
-  "sheet": "Q3_Summary",
-  "headerRow": 1,
-  "maxRows": 100
-}
-```
-
-### Response Example:
-```json
-{
-  "fileType": "xlsx",
-  "sheets": ["Q1", "Q2", "Q3_Summary"],
-  "rowCount": 45,
-  "data": [
-    { "Department": "Engineering", "Budget": 1250000, "Actual": 1180000 },
-    { "Department": "Marketing", "Budget": 600000, "Actual": 620000 }
-  ]
-}
-```
-
----
-
-## 2. Ingesting Word Documents (`.docx`)
-
-Extract semantic paragraphs, document headings, tables, and lists:
-
-```json
-{
-  "filePath": "C:/Users/fy2ne/Documents/service_agreement.docx",
-  "extractTables": true
-}
-```
-
-### Operational Advantages:
-- Eliminates the need for heavy external Python libraries or microservices.
-- Safely sanitizes binary formats before passing content into LLM context.
+---
+id: office-document-ingestion
+domain: documents
+triggers:
+  - "read excel"
+  - "read docx"
+  - "parse csv"
+  - "spreadsheet"
+  - "word document"
+  - "parse table"
+tools:
+  - "browser_office"
+weavetab: ">=2.5.0"
+---
+
+# Office Document Ingestion: Word, Excel, PDF & CSV Parsing
+
+Agents frequently need to parse structured spreadsheets or corporate documents downloaded during automation runs. `browser_office` reads `.xlsx`, `.xls`, `.docx`, `.pdf`, and `.csv` content directly into JSON.
+
+---
+
+## 1. Two Modes: `url` and `file`
+
+`browser_office({ action: "read" })` accepts exactly one source:
+
+- **`url`** — fetch a document URL in-browser using the active session cookies. Ideal for authenticated downloads, SharePoint links, and Google Drive exports. The format is auto-detected from the URL path or MIME type (and magic bytes as a fallback).
+- **`file`** — parse a file already present in the local downloads directory. Pass a **bare filename** only (e.g. `"report.xlsx"`); path separators are rejected.
+
+`max_rows` (default 500) caps Excel/CSV rows; `max_chars` (default 50000) caps PDF/Word text.
+
+Use `action: "list"` first if you don't know what files are in the downloads directory.
+
+---
+
+## 2. Parsing Spreadsheets (`.xlsx`, `.xls`, `.csv`)
+
+```json
+{
+  "action": "read",
+  "file": "quarterly_revenue.xlsx",
+  "max_rows": 100
+}
+```
+
+Excel returns per-sheet tables (rows as objects keyed by header):
+
+```json
+{
+  "success": true,
+  "source": "quarterly_revenue.xlsx",
+  "type": "excel",
+  "data": {
+    "Q3_Summary": [
+      { "Department": "Engineering", "Budget": 1250000, "Actual": 1180000 },
+      { "Department": "Marketing", "Budget": 600000, "Actual": 620000 }
+    ]
+  },
+  "truncated": false
+}
+```
+
+CSV returns `type: "csv"` with a flat `data` array of row objects.
+
+---
+
+## 3. Ingesting Word & PDF Documents (`.docx`, `.pdf`)
+
+Word and PDF extraction return text in `content` (truncated by `max_chars`). PDF additionally reports page metadata under `data`:
+
+```json
+{
+  "action": "read",
+  "url": "https://intranet.example.com/docs/service_agreement.pdf"
+}
+```
+
+```json
+{
+  "success": true,
+  "source": "https://intranet.example.com/docs/service_agreement.pdf",
+  "type": "pdf",
+  "content": "SERVICE AGREEMENT ...",
+  "truncated": true,
+  "data": { "numpages": 12, "info": { "Title": "Service Agreement" } }
+}
+```
+
+### Operational Notes:
+- PDF/Word parsing relies on local binary dependencies (e.g. poppler); if unavailable the call returns `success: false` with an explanatory `error`.
+- If the URL resolves to an HTML login page rather than a document, `type` is `"html"` and `success` is `false` — the link is likely gated.
+- Never point `browser_scrape` or `browser_map` at binary documents; they cannot read inside Excel, Word, or PDF files.

package/evals/evaluator.js

@@ -1,146 +1,146 @@
-const fs = require('fs');
-const path = require('path');
-
-const packageRoot = path.join(__dirname, '..');
-const scenariosPath = path.join(packageRoot, 'evals', 'scenarios.json');
-const skillsJsonPath = path.join(packageRoot, 'skills.json');
-
-const OFFICIAL_TOOLS = new Set([
-  "browser_map", "browser_navigate", "browser_click", "browser_type",
-  "browser_type_secret", "browser_key", "browser_scroll", "browser_dialog",
-  "browser_burst", "browser_tabs", "browser_wait", "browser_captcha",
-  "browser_thoughts", "browser_pointer", "browser_select", "browser_fill",
-  "browser_highlight", "browser_upload", "browser_find", "browser_storage",
-  "browser_network_intercept", "browser_console", "browser_pdf", "browser_eval",
-  "browser_cookies", "browser_canvas", "browser_scrape", "browser_snapshot",
-  "browser_screenshot", "browser_viewport", "browser_clipboard", "browser_inspect",
-  "browser_extract_design", "browser_automation", "browser_recording",
-  "browser_detect", "browser_performance",
-  "browser_github", "browser_office", "browser_emulate",
-  "browser_checkpoint", "browser_pattern_learn"
-]);
-
-const BANNED_TOOLS = [
-  "browser_evaluate", "browser_ask", "scrape_page", "click_element", "fill_field"
-];
-
-console.log("====================================================");
-console.log("Weavetab Agent Skills Evaluation Harness (evals/)");
-console.log("====================================================");
-
-if (!fs.existsSync(scenariosPath)) {
-  console.error("Missing evals/scenarios.json");
-  process.exit(1);
-}
-
-if (!fs.existsSync(skillsJsonPath)) {
-  console.error("Missing skills.json. Run 'npm run build' first.");
-  process.exit(1);
-}
-
-const scenariosData = JSON.parse(fs.readFileSync(scenariosPath, 'utf8'));
-const skillsData = JSON.parse(fs.readFileSync(skillsJsonPath, 'utf8'));
-
-let passed = 0;
-let failed = 0;
-const errors = [];
-
-console.log(`Running evaluation on ${scenariosData.scenarios.length} scenarios...\n`);
-
-for (const scenario of scenariosData.scenarios) {
-  process.stdout.write(`  [TEST] ${scenario.id.padEnd(35)} `);
-
-  const guidePath = path.join(packageRoot, scenario.expectedDomain, scenario.expectedGuide);
-  if (!fs.existsSync(guidePath)) {
-    console.log("❌ FAIL: Guide file missing");
-    errors.push(`Scenario '${scenario.id}': Expected guide not found at ${guidePath}`);
-    failed++;
-    continue;
-  }
-
-  const guideContent = fs.readFileSync(guidePath, 'utf8');
-
-  // 1. Verify expected tools are documented
-  let toolsMissing = [];
-  for (const tool of scenario.expectedTools) {
-    if (!guideContent.includes(tool)) {
-      toolsMissing.push(tool);
-    }
-  }
-
-  if (toolsMissing.length > 0) {
-    console.log(`❌ FAIL: Missing tools (${toolsMissing.join(', ')})`);
-    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} does not document required tools: ${toolsMissing.join(', ')}`);
-    failed++;
-    continue;
-  }
-
-  // 2. Verify no banned tools in guide
-  let bannedFound = [];
-  for (const banned of scenario.bannedTools || BANNED_TOOLS) {
-    if (guideContent.includes(`\`${banned}\``) || guideContent.includes(`"${banned}"`)) {
-      bannedFound.push(banned);
-    }
-  }
-
-  if (bannedFound.length > 0) {
-    console.log(`❌ FAIL: Contains banned tools (${bannedFound.join(', ')})`);
-    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} references banned tools: ${bannedFound.join(', ')}`);
-    failed++;
-    continue;
-  }
-
-  console.log("✔ PASS");
-  passed++;
-}
-
-// Global Check: Verify all 48 tools appear across the entire skill base
-console.log("\n----------------------------------------------------");
-console.log("Auditing Global Tool Coverage Across All 9 Domains...");
-const coveredTools = new Set();
-for (const skill of skillsData.skills) {
-  for (const t of skill.tools) {
-    coveredTools.add(t);
-  }
-}
-
-// Also scan markdown files for tools covered in text
-for (const domain of skillsData.domains) {
-  const dPath = path.join(packageRoot, domain);
-  if (!fs.existsSync(dPath)) continue;
-  for (const f of fs.readdirSync(dPath).filter(x => x.endsWith('.md'))) {
-    const content = fs.readFileSync(path.join(dPath, f), 'utf8');
-    for (const tool of OFFICIAL_TOOLS) {
-      if (content.includes(tool)) {
-        coveredTools.add(tool);
-      }
-    }
-  }
-}
-
-let uncoveredTools = [];
-for (const tool of OFFICIAL_TOOLS) {
-  if (!coveredTools.has(tool)) {
-    uncoveredTools.push(tool);
-  }
-}
-
-console.log(`Official Tools In MCP: ${OFFICIAL_TOOLS.size}`);
-console.log(`Covered in Skills:     ${coveredTools.size}`);
-
-if (uncoveredTools.length > 0) {
-  console.warn(`⚠️ Warning: Uncovered tools in skills: ${uncoveredTools.join(', ')}`);
-}
-
-console.log("====================================================");
-console.log(`Test Summary: ${passed} Passed, ${failed} Failed`);
-console.log("====================================================");
-
-if (failed > 0) {
-  console.error("\nFailure details:");
-  errors.forEach(err => console.error(`  - ${err}`));
-  process.exit(1);
-} else {
-  console.log("\nAll benchmark evaluation tests passed successfully.");
-  process.exit(0);
-}
+const fs = require('fs');
+const path = require('path');
+
+const packageRoot = path.join(__dirname, '..');
+const scenariosPath = path.join(packageRoot, 'evals', 'scenarios.json');
+const skillsJsonPath = path.join(packageRoot, 'skills.json');
+
+const OFFICIAL_TOOLS = new Set([
+  "browser_map", "browser_navigate", "browser_click", "browser_type",
+  "browser_type_secret", "browser_key", "browser_scroll", "browser_dialog",
+  "browser_burst", "browser_tabs", "browser_wait", "browser_captcha",
+  "browser_thoughts", "browser_pointer", "browser_select", "browser_fill",
+  "browser_highlight", "browser_upload", "browser_find", "browser_storage",
+  "browser_network_intercept", "browser_console", "browser_pdf", "browser_eval",
+  "browser_cookies", "browser_canvas", "browser_scrape", "browser_snapshot",
+  "browser_screenshot", "browser_viewport", "browser_clipboard", "browser_inspect",
+  "browser_extract_design", "browser_automation", "browser_recording",
+  "browser_detect", "browser_performance",
+  "browser_office", "browser_emulate",
+  "browser_checkpoint", "browser_pattern_learn"
+]);
+
+const BANNED_TOOLS = [
+  "browser_evaluate", "browser_ask", "scrape_page", "click_element", "fill_field"
+];
+
+console.log("====================================================");
+console.log("Weavetab Agent Skills Evaluation Harness (evals/)");
+console.log("====================================================");
+
+if (!fs.existsSync(scenariosPath)) {
+  console.error("Missing evals/scenarios.json");
+  process.exit(1);
+}
+
+if (!fs.existsSync(skillsJsonPath)) {
+  console.error("Missing skills.json. Run 'npm run build' first.");
+  process.exit(1);
+}
+
+const scenariosData = JSON.parse(fs.readFileSync(scenariosPath, 'utf8'));
+const skillsData = JSON.parse(fs.readFileSync(skillsJsonPath, 'utf8'));
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+console.log(`Running evaluation on ${scenariosData.scenarios.length} scenarios...\n`);
+
+for (const scenario of scenariosData.scenarios) {
+  process.stdout.write(`  [TEST] ${scenario.id.padEnd(35)} `);
+
+  const guidePath = path.join(packageRoot, scenario.expectedDomain, scenario.expectedGuide);
+  if (!fs.existsSync(guidePath)) {
+    console.log("❌ FAIL: Guide file missing");
+    errors.push(`Scenario '${scenario.id}': Expected guide not found at ${guidePath}`);
+    failed++;
+    continue;
+  }
+
+  const guideContent = fs.readFileSync(guidePath, 'utf8');
+
+  // 1. Verify expected tools are documented
+  let toolsMissing = [];
+  for (const tool of scenario.expectedTools) {
+    if (!guideContent.includes(tool)) {
+      toolsMissing.push(tool);
+    }
+  }
+
+  if (toolsMissing.length > 0) {
+    console.log(`❌ FAIL: Missing tools (${toolsMissing.join(', ')})`);
+    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} does not document required tools: ${toolsMissing.join(', ')}`);
+    failed++;
+    continue;
+  }
+
+  // 2. Verify no banned tools in guide
+  let bannedFound = [];
+  for (const banned of scenario.bannedTools || BANNED_TOOLS) {
+    if (guideContent.includes(`\`${banned}\``) || guideContent.includes(`"${banned}"`)) {
+      bannedFound.push(banned);
+    }
+  }
+
+  if (bannedFound.length > 0) {
+    console.log(`❌ FAIL: Contains banned tools (${bannedFound.join(', ')})`);
+    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} references banned tools: ${bannedFound.join(', ')}`);
+    failed++;
+    continue;
+  }
+
+  console.log("✔ PASS");
+  passed++;
+}
+
+// Global Check: Verify all 41 tools appear across the entire skill base
+console.log("\n----------------------------------------------------");
+console.log("Auditing Global Tool Coverage Across All 9 Domains...");
+const coveredTools = new Set();
+for (const skill of skillsData.skills) {
+  for (const t of skill.tools) {
+    coveredTools.add(t);
+  }
+}
+
+// Also scan markdown files for tools covered in text
+for (const domain of skillsData.domains) {
+  const dPath = path.join(packageRoot, domain);
+  if (!fs.existsSync(dPath)) continue;
+  for (const f of fs.readdirSync(dPath).filter(x => x.endsWith('.md'))) {
+    const content = fs.readFileSync(path.join(dPath, f), 'utf8');
+    for (const tool of OFFICIAL_TOOLS) {
+      if (content.includes(tool)) {
+        coveredTools.add(tool);
+      }
+    }
+  }
+}
+
+let uncoveredTools = [];
+for (const tool of OFFICIAL_TOOLS) {
+  if (!coveredTools.has(tool)) {
+    uncoveredTools.push(tool);
+  }
+}
+
+console.log(`Official Tools In MCP: ${OFFICIAL_TOOLS.size}`);
+console.log(`Covered in Skills:     ${coveredTools.size}`);
+
+if (uncoveredTools.length > 0) {
+  console.warn(`⚠️ Warning: Uncovered tools in skills: ${uncoveredTools.join(', ')}`);
+}
+
+console.log("====================================================");
+console.log(`Test Summary: ${passed} Passed, ${failed} Failed`);
+console.log("====================================================");
+
+if (failed > 0) {
+  console.error("\nFailure details:");
+  errors.forEach(err => console.error(`  - ${err}`));
+  process.exit(1);
+} else {
+  console.log("\nAll benchmark evaluation tests passed successfully.");
+  process.exit(0);
+}