opencodekit 0.16.19 → 0.16.20

package/dist/index.js

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.19",
+  version: "0.16.20",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/opencode.json

@@ -3,7 +3,7 @@
   "agent": {
     "build": {
       "description": "Primary development agent with full codebase access",
-      "model": "github-copilot/claude-opus-4.6"
+      "model": "opencode/kimi-k2.5-free"
     },
     "compaction": {
       "description": "Session summarizer for context continuity across compactions"
@@ -193,9 +193,6 @@
   ],
   "provider": {
     "github-copilot": {
-      "options": {
-        "timeout": 600000
-      },
       "models": {
         "claude-haiku-4.5": {
           "attachment": true,
@@ -260,11 +257,11 @@
           "variants": {
             "adaptive": {
               "options": {
-                "thinking": {
-                  "type": "adaptive"
-                },
                 "output_config": {
                   "effort": "high"
+                },
+                "thinking": {
+                  "type": "adaptive"
                 }
               }
             },
@@ -368,6 +365,9 @@
             }
           }
         }
+      },
+      "options": {
+        "timeout": 600000
       }
     },
     "kimi-for-coding": {
@@ -547,6 +547,32 @@
             }
           }
         },
+        "claude-opus-4-6-thinking": {
+          "limit": {
+            "context": 200000,
+            "output": 64000
+          },
+          "name": "Claude Opus 4 6 Thinking",
+          "options": {
+            "thinking": {
+              "budgetTokens": 8192,
+              "type": "enabled"
+            }
+          },
+          "reasoning": true,
+          "variants": {
+            "low": {
+              "thinkingConfig": {
+                "thinkingBudget": 8192
+              }
+            },
+            "max": {
+              "thinkingConfig": {
+                "thinkingBudget": 32768
+              }
+            }
+          }
+        },
         "claude-sonnet-4-5": {
           "limit": {
             "context": 200000,

package/dist/template/.opencode/skill/pdf-extract/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: pdf-extract
+description: Extract text, images, tables, and metadata from PDF files. Choose the right library based on extraction needs - text only, structured data, or complex layouts.
+---
+
+# PDF Content Extraction
+
+Extract content from PDF files using the best library for your specific use case.
+
+## Quick Decision Guide
+
+| Use Case                    | Recommended Library | Why                                |
+| --------------------------- | ------------------- | ---------------------------------- |
+| Simple text extraction      | `pdf-parse` (v2+)   | Fast, lightweight, pure TypeScript |
+| Complex layouts/coordinates | `pdfjs-dist`        | Full control, precise positioning  |
+| Tables/tabular data         | `pdf-data-parser`   | Built for grid-based content       |
+| Forms (XFA)                 | `pdf-lib` + custom  | Form field extraction              |
+| Browser + Node.js           | `pdf-parse` v2      | Cross-platform, works everywhere   |
+
+---
+
+## Library 1: pdf-parse (Recommended for Text)
+
+**Best for:** Simple text extraction, metadata, fast processing
+
+### Installation
+
+```bash
+npm install pdf-parse
+```
+
+### Basic Text Extraction
+
+```typescript
+import { PDFParse } from "pdf-parse";
+import { readFile } from "fs/promises";
+
+async function extractText(filePath: string): Promise<string> {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+  return result.text;
+}
+
+// Usage
+const text = await extractText("./document.pdf");
+console.log(text);
+```
+
+### Extract with Metadata
+
+```typescript
+import { PDFParse } from "pdf-parse";
+
+async function extractWithMetadata(filePath: string) {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+
+  return {
+    text: result.text,
+    info: result.info, // Document metadata
+    numpages: result.numpages,
+    version: result.version,
+  };
+}
+```
+
+### Extract Specific Pages
+
+```typescript
+import { PDFParse } from "pdf-parse";
+
+async function extractPage(filePath: string, pageNum: number) {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer, {
+    max: pageNum,
+    min: pageNum,
+  });
+
+  return result.text;
+}
+```
+
+### URL-based Extraction (without downloading full file)
+
+```typescript
+import { getHeader } from "pdf-parse/node";
+
+async function checkPDFHeaders(url: string) {
+  // Check file size and headers before downloading
+  const headers = await getHeader(url, true);
+  console.log(`File size: ${headers.size} bytes`);
+
+  if (headers.size > 10 * 1024 * 1024) {
+    console.warn("Large PDF - consider streaming");
+  }
+}
+```
+
+---
+
+## Library 2: pdfjs-dist (Mozilla PDF.js)
+
+**Best for:** Complex layouts, coordinates, images, page-by-page control
+
+### Installation
+
+```bash
+npm install pdfjs-dist
+```
+
+### Basic Text Extraction with Coordinates
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+import { readFile } from "fs/promises";
+import path from "path";
+
+async function extractWithCoordinates(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const dataArray = new Uint8Array(data);
+
+  const pdfDocument = await pdfjsLib.getDocument({
+    data: dataArray,
+    standardFontDataUrl: path.join(process.cwd(), "node_modules/pdfjs-dist/standard_fonts/"),
+  }).promise;
+
+  const numPages = pdfDocument.numPages;
+  const results = [];
+
+  for (let pageNum = 1; pageNum <= numPages; pageNum++) {
+    const page = await pdfDocument.getPage(pageNum);
+    const textContent = await page.getTextContent();
+
+    const pageText = textContent.items.map((item: any) => ({
+      text: item.str,
+      x: item.transform[4],
+      y: item.transform[5],
+      font: item.fontName,
+      width: item.width,
+      height: item.height,
+    }));
+
+    results.push({
+      page: pageNum,
+      items: pageText,
+    });
+  }
+
+  return results;
+}
+```
+
+### Extract Images from PDF
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+
+async function extractImages(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  const images = [];
+
+  for (let pageNum = 1; pageNum <= pdfDocument.numPages; pageNum++) {
+    const page = await pdfDocument.getPage(pageNum);
+    const ops = await page.getOperatorList();
+
+    for (let i = 0; i < ops.fnArray.length; i++) {
+      if (ops.fnArray[i] === pdfjsLib.OPS.paintImageXObject) {
+        const imageName = ops.argsArray[i][0];
+        const image = await page.objs.get(imageName);
+
+        images.push({
+          page: pageNum,
+          name: imageName,
+          width: image.width,
+          height: image.height,
+          data: image.data, // Raw image data
+        });
+      }
+    }
+  }
+
+  return images;
+}
+```
+
+### Render Page to Image
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+import { createCanvas } from "canvas";
+import { writeFile } from "fs/promises";
+
+async function renderPageToImage(pdfPath: string, pageNum: number, outputPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  const page = await pdfDocument.getPage(pageNum);
+  const viewport = page.getViewport({ scale: 2.0 }); // Higher scale = better quality
+
+  const canvas = createCanvas(viewport.width, viewport.height);
+  const context = canvas.getContext("2d");
+
+  await page.render({
+    canvasContext: context,
+    viewport: viewport,
+  }).promise;
+
+  const buffer = canvas.toBuffer("image/png");
+  await writeFile(outputPath, buffer);
+
+  console.log(`Page ${pageNum} saved to ${outputPath}`);
+}
+```
+
+---
+
+## Library 3: pdf-data-parser (Tables)
+
+**Best for:** Tabular data, structured grid content
+
+### Installation
+
+```bash
+npm install pdf-data-parser
+```
+
+### Extract Tables
+
+```typescript
+import { PdfDataParser } from "pdf-data-parser";
+
+async function extractTables(pdfPath: string) {
+  const parser = new PdfDataParser({
+    url: pdfPath,
+    // Options
+    heading: "Table Title", // Filter to specific table
+    cells: 3, // Minimum cells per row
+    headers: ["Name", "Amount"], // Expected headers
+    repeating: false, // Handle repeating headers
+  });
+
+  const rows = await parser.parse();
+  return rows; // Array of arrays
+}
+```
+
+### Stream Large PDFs
+
+```typescript
+import { PdfDataReader } from "pdf-data-parser";
+import { createWriteStream } from "fs";
+
+async function streamToCSV(pdfPath: string, outputPath: string) {
+  const reader = new PdfDataReader({
+    url: pdfPath,
+    cells: 2,
+  });
+
+  const output = createWriteStream(outputPath);
+
+  reader.on("data", (row: string[]) => {
+    output.write(row.join(",") + "\n");
+  });
+
+  reader.on("end", () => {
+    output.end();
+    console.log("CSV created");
+  });
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Error Handling
+
+```typescript
+async function safeExtract(filePath: string) {
+  try {
+    const buffer = await readFile(filePath);
+
+    // Validate PDF header
+    const header = buffer.slice(0, 5).toString();
+    if (header !== "%PDF-") {
+      throw new Error("Invalid PDF file");
+    }
+
+    const result = await parser.parse(buffer);
+    return result;
+  } catch (error) {
+    if (error.message.includes("password")) {
+      throw new Error("PDF is password protected");
+    }
+    if (error.message.includes("damaged")) {
+      throw new Error("PDF is corrupted");
+    }
+    throw error;
+  }
+}
+```
+
+### 2. Memory Management (Large Files)
+
+```typescript
+// For large PDFs, process page by page
+async function extractLargePDF(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  // Don't load all pages at once
+  for (let i = 1; i <= pdfDocument.numPages; i++) {
+    const page = await pdfDocument.getPage(i);
+    const text = await page.getTextContent();
+
+    // Process immediately, don't accumulate
+    await processPageText(text);
+
+    // Clean up
+    page.cleanup();
+  }
+}
+```
+
+### 3. Text Cleaning
+
+```typescript
+function cleanExtractedText(text: string): string {
+  return text
+    .replace(/\s+/g, " ") // Normalize whitespace
+    .replace(/[^\x20-\x7E\n]/g, "") // Remove non-printable chars
+    .trim();
+}
+```
+
+### 4. Performance Tips
+
+```typescript
+// Parallel extraction for multiple files
+async function extractMultiple(files: string[]) {
+  const results = await Promise.all(
+    files.map((file) => extractText(file).catch((err) => ({ file, error: err }))),
+  );
+  return results;
+}
+
+// Use streams for very large files
+import { createReadStream } from "fs";
+import { PdfDataReader } from "pdf-data-parser";
+```
+
+---
+
+## Common Issues & Solutions
+
+| Issue                | Cause                 | Solution                              |
+| -------------------- | --------------------- | ------------------------------------- |
+| Text appears garbled | Encoding issue        | Use pdfjs-dist with explicit encoding |
+| Missing text         | Scanned image PDF     | Use OCR (Tesseract) before extraction |
+| Out of memory        | Large PDF             | Stream processing, page-by-page       |
+| Password error       | Encrypted PDF         | Use `pdf-lib` to decrypt first        |
+| Missing coordinates  | Wrong library         | Use pdfjs-dist for positioning        |
+| Table structure lost | Plain text extraction | Use pdf-data-parser                   |
+| Font warnings        | Missing fonts         | Set `standardFontDataUrl` option      |
+
+---
+
+## Complete Example: Document Processor
+
+```typescript
+import { PDFParse } from "pdf-parse";
+import { readFile } from "fs/promises";
+
+interface DocumentResult {
+  text: string;
+  metadata: {
+    title?: string;
+    author?: string;
+    pages: number;
+    creationDate?: Date;
+  };
+  summary: string;
+}
+
+async function processDocument(filePath: string): Promise<DocumentResult> {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+
+  // Generate summary (first 500 chars)
+  const summary = result.text.replace(/\s+/g, " ").slice(0, 500).trim() + "...";
+
+  return {
+    text: result.text,
+    metadata: {
+      title: result.info?.Title,
+      author: result.info?.Author,
+      pages: result.numpages,
+      creationDate: result.info?.CreationDate ? new Date(result.info.CreationDate) : undefined,
+    },
+    summary,
+  };
+}
+
+// Usage
+const doc = await processDocument("./report.pdf");
+console.log(`Document: ${doc.metadata.title}`);
+console.log(`Pages: ${doc.metadata.pages}`);
+console.log(`Summary: ${doc.summary}`);
+```
+
+---
+
+## References
+
+- [pdf-parse npm](https://www.npmjs.com/package/pdf-parse)
+- [pdfjs-dist docs](https://mozilla.github.io/pdf.js/)
+- [pdf-data-parser GitHub](https://github.com/drewletcher/pdf-data-parser)
+- [pdf-lib GitHub](https://github.com/Hopding/pdf-lib)

package/dist/template/.opencode/skill/playwright/SKILL.md

@@ -1,112 +1,310 @@
 ---
 name: playwright
-description: Browser automation with Playwright MCP. Test pages, fill forms, take screenshots, check responsive design, validate UX, test login flows. Use when user wants to test websites or automate browser interactions.
+description: Browser automation for testing, screenshots, form validation, and UX verification. Uses Playwright CLI for token-efficient automation, with MCP fallback for complex exploratory workflows.
 ---
 
-# Playwright Browser Automation (MCP)
+# Playwright Browser Automation
 
-Browser automation via Playwright MCP server for testing and automation.
+Browser automation via **Playwright CLI** (primary) and **Playwright MCP** (fallback for complex workflows).
 
-## Available Tools
+## Quick Decision
 
-- `browser_navigate` - Navigate to URL
-- `browser_snapshot` - Get page accessibility snapshot with element refs
-- `browser_take_screenshot` - Capture screenshot
-- `browser_click` - Click element by ref
-- `browser_type` - Type text (appends to existing)
-- `browser_fill` - Fill input (clears first, then types)
-- `browser_wait_for` - Wait for text or selector
-- `browser_resize` - Resize viewport or emulate device
+| Scenario                                            | Use     |
+| --------------------------------------------------- | ------- |
+| Quick screenshots, simple forms, token efficiency   | **CLI** |
+| Complex exploratory testing, self-healing workflows | **MCP** |
+
+---
 
-## Workflow
+## CLI Mode (Recommended)
 
-1. **Navigate** to the target URL using `browser_navigate`
-2. **Snapshot** to see page structure and element refs using `browser_snapshot`
-3. **Interact** using element refs from snapshot (`browser_click`, `browser_fill`)
-4. **Screenshot** to capture results using `browser_take_screenshot`
+The CLI approach is **token-efficient** - no large schemas or verbose accessibility trees in context. Best for most automation tasks.
 
-## Quick Start
+### Installation
 
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli install --skills  # Optional: install for Claude/Copilot
 ```
-# Navigate to page
-skill_mcp(skill_name="playwright", tool_name="browser_navigate", arguments='{"url": "https://example.com"}')
 
-# Get page structure with element refs
-skill_mcp(skill_name="playwright", tool_name="browser_snapshot")
+### Core Workflow
 
-# Click element (use ref from snapshot)
-skill_mcp(skill_name="playwright", tool_name="browser_click", arguments='{"element": "Submit button", "ref": "e123"}')
+```
+# 1. Open browser and navigate
+bash({ command: "playwright-cli open https://example.com" })
+
+# 2. Get element refs (snapshot)
+bash({ command: "playwright-cli snapshot" })
 
-# Fill input field
-skill_mcp(skill_name="playwright", tool_name="browser_fill", arguments='{"element": "Email", "ref": "e456", "text": "test@example.com"}')
+# 3. Interact using refs
+bash({ command: "playwright-cli fill e12 'test@example.com'" })
+bash({ command: "playwright-cli click e34" })
 
-# Take screenshot
-skill_mcp(skill_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/result.png"}')
+# 4. Screenshot
+bash({ command: "playwright-cli screenshot --filename=/tmp/result.png" })
 ```
 
-## Examples
+### Commands Reference
+
+#### Navigation
+
+| Command      | Description                              |
+| ------------ | ---------------------------------------- |
+| `open [url]` | Open browser, optionally navigate to URL |
+| `goto <url>` | Navigate to URL                          |
+| `close`      | Close the page/browser                   |
+| `go-back`    | Go back to previous page                 |
+| `go-forward` | Go forward to next page                  |
+| `reload`     | Reload current page                      |
+
+#### Interaction
+
+| Command                    | Description                               |
+| -------------------------- | ----------------------------------------- |
+| `snapshot`                 | Capture page snapshot to get element refs |
+| `type <text>`              | Type text into focused element            |
+| `fill <ref> <text>`        | Fill text into specific element           |
+| `click <ref> [button]`     | Click element (left/right/middle)         |
+| `dblclick <ref>`           | Double-click element                      |
+| `hover <ref>`              | Hover over element                        |
+| `drag <startRef> <endRef>` | Drag and drop                             |
+| `select <ref> <value>`     | Select dropdown option                    |
+| `check <ref>`              | Check checkbox/radio                      |
+| `uncheck <ref>`            | Uncheck checkbox                          |
+| `upload <file>`            | Upload file(s)                            |
+
+#### Keyboard
+
+| Command         | Description                            |
+| --------------- | -------------------------------------- |
+| `press <key>`   | Press key (e.g., `Enter`, `ArrowLeft`) |
+| `keydown <key>` | Hold key down                          |
+| `keyup <key>`   | Release key                            |
 
-### Test Responsive Design
+#### Screenshots & PDF
 
+| Command                              | Description                |
+| ------------------------------------ | -------------------------- |
+| `screenshot [ref]`                   | Screenshot page or element |
+| `screenshot --filename=/tmp/out.png` | Save to specific path      |
+| `pdf`                                | Save page as PDF           |
+| `pdf --filename=page.pdf`            | Save PDF to specific path  |
+
+#### Tabs
+
+| Command              | Description    |
+| -------------------- | -------------- |
+| `tab-list`           | List all tabs  |
+| `tab-new [url]`      | Create new tab |
+| `tab-close [index]`  | Close tab      |
+| `tab-select <index>` | Switch to tab  |
+
+#### Storage
+
+| Command                          | Description                     |
+| -------------------------------- | ------------------------------- |
+| `cookie-list`                    | List cookies                    |
+| `cookie-get <name>`              | Get cookie value                |
+| `cookie-set <name> <value>`      | Set cookie                      |
+| `cookie-delete <name>`           | Delete cookie                   |
+| `cookie-clear`                   | Clear all cookies               |
+| `localstorage-list`              | List localStorage               |
+| `localstorage-get <key>`         | Get localStorage value          |
+| `localstorage-set <key> <value>` | Set localStorage                |
+| `sessionstorage-*`               | Same pattern for sessionStorage |
+
+#### Network
+
+| Command             | Description           |
+| ------------------- | --------------------- |
+| `route <pattern>`   | Mock network requests |
+| `route-list`        | List active routes    |
+| `unroute [pattern]` | Remove route(s)       |
+
+#### DevTools
+
+| Command                 | Description                         |
+| ----------------------- | ----------------------------------- |
+| `console [min-level]`   | List console messages               |
+| `network`               | List network requests               |
+| `eval <func> [ref]`     | Evaluate JavaScript on page/element |
+| `run-code <code>`       | Run Playwright code snippet         |
+| `tracing-start`         | Start trace recording               |
+| `tracing-stop`          | Stop trace recording                |
+| `video-start`           | Start video recording               |
+| `video-stop [filename]` | Stop video recording                |
+
+### CLI Options
+
+```bash
+# Headless mode
+playwright-cli open https://example.com --headless
+
+# Choose browser
+playwright-cli open https://example.com --browser=firefox
+
+# Emulate device
+playwright-cli open https://example.com --device="iPhone 14"
+
+# Named session (isolated browser)
+playwright-cli -s=project1 open https://example.com
+
+# See all options
+playwright-cli --help
 ```
-# Navigate
-skill_mcp(skill_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000"}')
 
-# Desktop
-skill_mcp(skill_name="playwright", tool_name="browser_resize", arguments='{"width": 1920, "height": 1080}')
-skill_mcp(skill_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/desktop.png"}')
+### CLI Examples
+
+#### Test Responsive Design
 
-# Mobile
-skill_mcp(skill_name="playwright", tool_name="browser_resize", arguments='{"device": "iPhone 13"}')
-skill_mcp(skill_name="playwright", tool_name="browser_take_screenshot", arguments='{"filename": "/tmp/mobile.png"}')
+```typescript
+// Desktop
+bash({ command: "playwright-cli open http://localhost:3000" });
+bash({ command: "playwright-cli resize 1920 1080" });
+bash({ command: "playwright-cli screenshot --filename=/tmp/desktop.png" });
+
+// Mobile
+bash({ command: "playwright-cli resize 390 844" }); // iPhone 14
+bash({ command: "playwright-cli screenshot --filename=/tmp/mobile.png" });
 ```
 
-### Fill a Form
+#### Fill a Form
+
+```typescript
+bash({ command: "playwright-cli open http://localhost:3000/contact" });
+
+// Get snapshot to see element refs
+bash({ command: "playwright-cli snapshot" });
+
+// Fill using refs from snapshot output
+bash({ command: "playwright-cli fill e12 'John Doe'" });
+bash({ command: "playwright-cli fill e34 'john@example.com'" });
+bash({ command: "playwright-cli click e56" }); // Submit button
 
+// Wait for confirmation
+bash({ command: "playwright-cli eval 'document.body.innerText.includes(\"Thank you\")'" });
 ```
-# Navigate to form
-skill_mcp(skill_name="playwright", tool_name="browser_navigate", arguments='{"url": "http://localhost:3000/contact"}')
 
-# Get element refs
-skill_mcp(skill_name="playwright", tool_name="browser_snapshot")
+#### Multi-Step Login Flow
 
-# Fill fields (use refs from snapshot)
-skill_mcp(skill_name="playwright", tool_name="browser_fill", arguments='{"element": "Name", "ref": "e12", "text": "John Doe"}')
-skill_mcp(skill_name="playwright", tool_name="browser_fill", arguments='{"element": "Email", "ref": "e34", "text": "john@example.com"}')
+```typescript
+bash({ command: "playwright-cli open https://app.example.com/login" });
+bash({ command: "playwright-cli snapshot" });
 
-# Submit
-skill_mcp(skill_name="playwright", tool_name="browser_click", arguments='{"element": "Submit", "ref": "e56"}')
+bash({ command: "playwright-cli fill e10 'username'" });
+bash({ command: "playwright-cli fill e12 'password'" });
+bash({ command: "playwright-cli click e15" });
 
-# Wait for confirmation
-skill_mcp(skill_name="playwright", tool_name="browser_wait_for", arguments='{"text": "Thank you", "timeout": 5000}')
+// Verify logged in
+bash({ command: "playwright-cli eval 'document.querySelector(\".dashboard\") !== null'" });
+bash({ command: "playwright-cli screenshot --filename=/tmp/logged-in.png" });
 ```
 
-## Tips
+#### Session Management
+
+```typescript
+// List all browser sessions
+bash({ command: "playwright-cli list" });
+
+// Use named session
+bash({ command: "playwright-cli -s=project1 open https://example.com" });
+
+// Close specific session
+bash({ command: "playwright-cli -s=project1 close" });
+
+// Close all browsers
+bash({ command: "playwright-cli close-all" });
+```
+
+---
+
+## MCP Mode (Fallback)
+
+Use MCP for complex exploratory workflows or when you need persistent browser state with rich introspection.
+
+### Tools (8 Essential)
+
+- `browser_navigate` - Navigate to URL
+- `browser_snapshot` - Get accessibility snapshot with element refs
+- `browser_take_screenshot` - Capture screenshot
+- `browser_click` - Click element by ref
+- `browser_type` - Type text (appends)
+- `browser_fill` - Fill input (clears first, then types)
+- `browser_wait_for` - Wait for text or selector
+- `browser_resize` - Resize viewport or emulate device
 
-- **Always snapshot first** to get element refs before interacting
-- **Use descriptive element names** in click/fill for clarity
-- **Save screenshots to /tmp** for easy access
-- **Use device presets** for accurate mobile emulation
-- **Chain wait_for** after navigation for dynamic pages
+### MCP Workflow
 
-## Server Options
+```typescript
+// Navigate
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_navigate"),
+  (arguments = '{"url": "https://example.com"}'),
+);
 
-For advanced usage, modify `mcp.json`:
+// Get element refs
+skill_mcp((skill_name = "playwright"), (tool_name = "browser_snapshot"));
+
+// Interact
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_click"),
+  (arguments = '{"element": "Submit", "ref": "e12"}'),
+);
+
+// Screenshot
+skill_mcp(
+  (skill_name = "playwright"),
+  (tool_name = "browser_take_screenshot"),
+  (arguments = '{"filename": "/tmp/result.png"}'),
+);
+```
+
+### MCP Configuration
 
 ```json
 {
   "playwright": {
     "command": "npx",
-    "args": ["@playwright/mcp@latest", "--headless", "--browser=firefox"],
-    "includeTools": ["browser_navigate", "browser_snapshot", "..."]
+    "args": ["@playwright/mcp@latest"],
+    "includeTools": [
+      "browser_navigate",
+      "browser_snapshot",
+      "browser_take_screenshot",
+      "browser_click",
+      "browser_type",
+      "browser_fill",
+      "browser_wait_for",
+      "browser_resize"
+    ]
   }
 }
 ```
 
-Common options:
+---
+
+## Best Practices
+
+1. **Default to CLI** for token efficiency
+2. **Snapshot before interact** - always get element refs first
+3. **Use named sessions** (`-s=`) for isolated browser contexts
+4. **Save outputs to /tmp** for easy access and cleanup
+5. **Check console/network** for debugging: `playwright-cli console error`
+6. **Use eval for custom checks** when built-in commands aren't enough
+
+## Troubleshooting
+
+| Issue               | Solution                                         |
+| ------------------- | ------------------------------------------------ |
+| Element not found   | Re-run snapshot to get fresh refs                |
+| Page not loading    | Check network with `playwright-cli network`      |
+| Timing issues       | Use `eval` to check conditions before proceeding |
+| Session conflicts   | Use named sessions (`-s=project1`)               |
+| Browser won't close | `playwright-cli kill-all` as last resort         |
 
-- `--headless` - Run without visible browser
-- `--browser=chrome|firefox|webkit` - Choose browser
-- `--device="iPhone 13"` - Emulate device
+## References
 
-> **Note**: This skill loads 8 essential tools. For full 17+ tools (tabs, PDF, evaluate, drag), modify `mcp.json` to add more tools to `includeTools`.
+- [Playwright CLI GitHub](https://github.com/microsoft/playwright-cli)
+- [Playwright MCP GitHub](https://github.com/microsoft/playwright-mcp)
+- [Playwright Docs](https://playwright.dev)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.16.19",
+	"version": "0.16.20",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",