chore: Improve CLAUDE.md (#547)

Author: patricklafrance

.agents/skills/agent-browser/SKILL.md

@@ -64,7 +64,10 @@ agent-browser type @e2 "text"         # Type without clearing
 agent-browser select @e1 "option"     # Select dropdown option
 agent-browser check @e1               # Check checkbox
 agent-browser press Enter             # Press key
+agent-browser keyboard type "text"    # Type at current focus (no selector)
+agent-browser keyboard inserttext "text"  # Insert without key events
 agent-browser scroll down 500         # Scroll page
+agent-browser scroll down 500 --selector "div.content"  # Scroll within a specific container
 
 # Get information
 agent-browser get text @e1            # Get element text
@@ -77,6 +80,11 @@ agent-browser wait --load networkidle # Wait for network idle
 agent-browser wait --url "**/page"    # Wait for URL pattern
 agent-browser wait 2000               # Wait milliseconds
 
+# Downloads
+agent-browser download @e1 ./file.pdf          # Click element to trigger download
+agent-browser wait --download ./output.zip     # Wait for any download to complete
+agent-browser --download-path ./downloads open <url>  # Set default download directory
+
 # Capture
 agent-browser screenshot              # Screenshot to temp dir
 agent-browser screenshot --full       # Full page screenshot
@@ -107,6 +115,22 @@ agent-browser click @e5
 agent-browser wait --load networkidle
 ```
 
+### Authentication with Auth Vault (Recommended)
+
+```bash
+# Save credentials once (encrypted with AGENT_BROWSER_ENCRYPTION_KEY)
+# Recommended: pipe password via stdin to avoid shell history exposure
+echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
+
+# Login using saved profile (LLM never sees password)
+agent-browser auth login github
+
+# List/show/delete profiles
+agent-browser auth list
+agent-browser auth show github
+agent-browser auth delete github
+```
+
 ### Authentication with State Persistence
 
 ```bash
@@ -182,6 +206,19 @@ agent-browser --auto-connect snapshot
 agent-browser --cdp 9222 snapshot
 ```
 
+### Color Scheme (Dark Mode)
+
+```bash
+# Persistent dark mode via flag (applies to all pages and new tabs)
+agent-browser --color-scheme dark open https://example.com
+
+# Or via environment variable
+AGENT_BROWSER_COLOR_SCHEME=dark agent-browser open https://example.com
+
+# Or set during session (persists for subsequent commands)
+agent-browser set media dark
+```
+
 ### Visual Browser (Debugging)
 
 ```bash
@@ -227,6 +264,56 @@ agent-browser -p ios close
 
 **Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
 
+## Security
+
+All security features are opt-in. By default, agent-browser imposes no restrictions on navigation, actions, or output.
+
+### Content Boundaries (Recommended for AI Agents)
+
+Enable `--content-boundaries` to wrap page-sourced output in markers that help LLMs distinguish tool output from untrusted page content:
+
+```bash
+export AGENT_BROWSER_CONTENT_BOUNDARIES=1
+agent-browser snapshot
+# Output:
+# --- AGENT_BROWSER_PAGE_CONTENT nonce=<hex> origin=https://example.com ---
+# [accessibility tree]
+# --- END_AGENT_BROWSER_PAGE_CONTENT nonce=<hex> ---
+```
+
+### Domain Allowlist
+
+Restrict navigation to trusted domains. Wildcards like `*.example.com` also match the bare domain `example.com`. Sub-resource requests, WebSocket, and EventSource connections to non-allowed domains are also blocked. Include CDN domains your target pages depend on:
+
+```bash
+export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"
+agent-browser open https://example.com        # OK
+agent-browser open https://malicious.com       # Blocked
+```
+
+### Action Policy
+
+Use a policy file to gate destructive actions:
+
+```bash
+export AGENT_BROWSER_ACTION_POLICY=./policy.json
+```
+
+Example `policy.json`:
+```json
+{"default": "deny", "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]}
+```
+
+Auth vault operations (`auth login`, etc.) bypass action policy but domain allowlist still applies.
+
+### Output Limits
+
+Prevent context flooding from large pages:
+
+```bash
+export AGENT_BROWSER_MAX_OUTPUT=50000
+```
+
 ## Diffing (Verifying Changes)
 
 Use `diff snapshot` after performing an action to verify it had the intended effect. This compares the current accessibility tree against the last snapshot taken in the session.
@@ -254,7 +341,7 @@ agent-browser diff url https://staging.example.com https://prod.example.com --sc
 
 ## Timeouts and Slow Pages
 
-The default Playwright timeout is 60 seconds for local browsers. For slow websites or large pages, use explicit waits instead of relying on the default timeout:
+The default Playwright timeout is 25 seconds for local browsers. This can be overridden with the `AGENT_BROWSER_DEFAULT_TIMEOUT` environment variable (value in milliseconds). For slow websites or large pages, use explicit waits instead of relying on the default timeout:
 
 ```bash
 # Wait for network activity to settle (best for slow pages)

.agents/skills/agent-browser/templates/authenticated-session.sh

@@ -3,6 +3,11 @@
 # Purpose: Login once, save state, reuse for subsequent runs
 # Usage: ./authenticated-session.sh <login-url> [state-file]
 #
+# RECOMMENDED: Use the auth vault instead of this template:
+#   echo "<pass>" | agent-browser auth save myapp --url <login-url> --username <user> --password-stdin
+#   agent-browser auth login myapp
+# The auth vault stores credentials securely and the LLM never sees passwords.
+#
 # Environment variables:
 #   APP_USERNAME - Login username/email
 #   APP_PASSWORD - Login password

.agents/skills/turborepo/SKILL.md

@@ -9,7 +9,7 @@ description: |
   monorepo, shares code between apps, runs changed/affected packages, debugs cache,
   or has apps/packages directories.
 metadata:
-  version: 2.8.11-canary.17
+  version: 2.8.13-canary.8
 ---
 
 # Turborepo Skill
@@ -722,7 +722,7 @@ import { Button } from "@repo/ui/button";
 
 ```json
 {
-  "$schema": "https://turborepo.dev/schema.v2.json",
+  "$schema": "https://v2-8-13-canary-8.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],

.agents/skills/turborepo/references/best-practices/RULE.md

@@ -192,10 +192,10 @@ export * from './modal';
 
 ```typescript
 // BAD: Reaching into another package
-import { Button } from '../../packages/ui/src/button';
+import { Button } from "../../packages/ui/src/button";
 
 // GOOD: Install and import properly
-import { Button } from '@repo/ui/button';
+import { Button } from "@repo/ui/button";
 ```
 
 ### Shared Code in Apps

.agents/skills/turborepo/references/best-practices/dependencies.md

@@ -161,7 +161,7 @@ catalog:
 // Any package.json
 {
   "dependencies": {
-    "react": "catalog:"  // Uses version from catalog
+    "react": "catalog:" // Uses version from catalog
   }
 }
 ```
@@ -200,7 +200,7 @@ For library packages that expect the consumer to provide dependencies:
     "react-dom": "^18.0.0"
   },
   "devDependencies": {
-    "react": "^18.0.0",      // For development/testing
+    "react": "^18.0.0", // For development/testing
     "react-dom": "^18.0.0"
   }
 }

.agents/skills/turborepo/references/best-practices/packages.md

@@ -93,9 +93,9 @@ Package handles its own compilation.
 ```json
 {
   "exports": {
-    ".": "./src/index.ts",           // @repo/ui
-    "./button": "./src/button.tsx",  // @repo/ui/button
-    "./card": "./src/card.tsx",      // @repo/ui/card
+    ".": "./src/index.ts", // @repo/ui
+    "./button": "./src/button.tsx", // @repo/ui/button
+    "./card": "./src/card.tsx", // @repo/ui/card
     "./hooks": "./src/hooks/index.ts" // @repo/ui/hooks
   }
 }
@@ -124,7 +124,7 @@ Package handles its own compilation.
 // apps/web/package.json
 {
   "dependencies": {
-    "@repo/ui": "workspace:*"  // pnpm/bun
+    "@repo/ui": "workspace:*" // pnpm/bun
     // "@repo/ui": "*"         // npm/yarn
   }
 }
@@ -287,7 +287,7 @@ TypeScript `compilerOptions.paths` breaks with JIT packages. Use Node.js subpath
 
 ```typescript
 // packages/ui/button.tsx
-import { MY_STRING } from "#utils.ts";  // Uses .ts extension
+import { MY_STRING } from "#utils.ts"; // Uses .ts extension
 ```
 
 **Compiled Package:**
@@ -303,7 +303,7 @@ import { MY_STRING } from "#utils.ts";  // Uses .ts extension
 
 ```typescript
 // packages/ui/button.tsx
-import { MY_STRING } from "#utils.js";  // Uses .js extension
+import { MY_STRING } from "#utils.js"; // Uses .js extension
 ```
 
 ### Use `tsc` for Internal Packages

.agents/skills/turborepo/references/best-practices/structure.md

@@ -95,7 +95,7 @@ Package tasks enable Turborepo to:
 
 ```json
 {
-  "$schema": "https://turborepo.dev/schema.v2.json",
+  "$schema": "https://v2-8-13-canary-8.turborepo.dev/schema.json",
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
@@ -124,8 +124,8 @@ You can group packages by adding more workspace paths:
 packages:
   - "apps/*"
   - "packages/*"
-  - "packages/config/*"    # Grouped configs
-  - "packages/features/*"  # Feature packages
+  - "packages/config/*" # Grouped configs
+  - "packages/features/*" # Feature packages
 ```
 
 This allows:
@@ -148,7 +148,7 @@ packages/
 ```yaml
 # BAD: Nested wildcards cause ambiguous behavior
 packages:
-  - "packages/**"  # Don't do this!
+  - "packages/**" # Don't do this!
 ```
 
 ## Package Anatomy
@@ -167,10 +167,11 @@ packages/ui/
 
 ```json
 {
-  "name": "@repo/ui",           // Unique, namespaced name
-  "version": "0.0.0",           // Version (can be 0.0.0 for internal)
-  "private": true,              // Prevents accidental publishing
-  "exports": {                  // Entry points
+  "name": "@repo/ui", // Unique, namespaced name
+  "version": "0.0.0", // Version (can be 0.0.0 for internal)
+  "private": true, // Prevents accidental publishing
+  "exports": {
+    // Entry points
     "./button": "./src/button.tsx"
   }
 }
@@ -254,7 +255,7 @@ packages/
 ```js
 // apps/web/.eslintrc.js
 module.exports = {
-  extends: ["@repo/eslint-config/next"],
+  extends: ["@repo/eslint-config/next"]
 };
 ```
 

.agents/skills/turborepo/references/caching/gotchas.md

@@ -109,7 +109,7 @@ Task uses an env var not listed in `env`:
 
 ```javascript
 // build.js
-const apiUrl = process.env.API_URL;  // not tracked!
+const apiUrl = process.env.API_URL; // not tracked!
 ```
 
 Fix: add to task config:
@@ -134,7 +134,7 @@ Task reads a file outside default inputs:
     "build": {
       "inputs": [
         "$TURBO_DEFAULT$",
-        "../../shared-config.json"  // file outside package
+        "../../shared-config.json" // file outside package
       ]
     }
   }

.agents/skills/turborepo/references/ci/RULE.md

@@ -49,7 +49,7 @@ This requires Git history to compute what changed.
 # GitHub Actions
 - uses: actions/checkout@v4
   with:
-    fetch-depth: 2  # Minimum for --affected
+    fetch-depth: 2 # Minimum for --affected
     # Use 0 for full history if merge base is far
 ```
 
@@ -60,7 +60,7 @@ Turborepo compares the current HEAD to the merge base with `main`. If that commi
 For PRs with many commits, consider:
 
 ```yaml
-fetch-depth: 0  # Full history
+fetch-depth: 0 # Full history
 ```
 
 ## Environment Variables Reference

.agents/skills/turborepo/references/ci/github-actions.md

@@ -44,7 +44,7 @@ jobs:
 - uses: actions/setup-node@v4
   with:
     node-version: 20
-    cache: 'pnpm'
+    cache: "pnpm"
 
 - run: pnpm install --frozen-lockfile
 ```
@@ -55,7 +55,7 @@ jobs:
 - uses: actions/setup-node@v4
   with:
     node-version: 20
-    cache: 'yarn'
+    cache: "yarn"
 
 - run: yarn install --frozen-lockfile
 ```
@@ -146,7 +146,7 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-          cache: 'pnpm'
+          cache: "pnpm"
 
       - name: Install dependencies
         run: pnpm install --frozen-lockfile