opencode-skills-collection 3.1.14 → 3.1.16

package/bundled-skills/aegisops-ai/SKILL.md

@@ -88,7 +88,7 @@ Create a `.env` file in the root directory to securely
 store your credentials:
 
 ```bash
-echo "GEMINI_API_KEY='your_api_key_here'" > .env
+printf 'GEMINI_API_KEY=%s\n' "$GEMINI_API_KEY" > .env
 ```
 ## 🏁 Operational Dashboard
 

package/bundled-skills/agent-self-scheduling/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: agent-self-scheduling
+description: "Schedule AI agent runs with cron, loops, or external clocks while avoiding unsafe tight autonomous timers."
+category: agent-orchestration
+risk: critical
+source: community
+source_repo: davidondrej/skills
+source_type: community
+date_added: "2026-07-07"
+author: davidondrej
+tags: [agents, scheduling, automation, cron]
+tools: [claude, codex]
+license: "MIT"
+license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
+---
+
+# Agent Self-Scheduling
+
+## When to Use
+
+- Use when the user asks for recurring, scheduled, heartbeat, or looped agent work.
+- Use when you need to choose between cron, external schedulers, hooks, or built-in agent scheduling.
+
+First question: does the agent have a built-in scheduler (Hermes → Camp B), or do you own the clock (everything else → Camp A)?
+
+Universal floor: cron is 1 minute minimum (5-field expr, no seconds) — every camp. For sub-minute you MUST use a `while ...; sleep N; done` loop, a TS extension, or an event hook. Never put an LLM on a tight timer.
+
+## Camp A — one-shot agents, you own the clock
+
+These run once and exit (amnesiac unless resumed). Schedule them externally.
+
+```bash
+claude -p "PROMPT" --output-format json --allowedTools "Read,Edit,Bash"  # Claude Code
+codex exec --json "PROMPT"                                                # Codex
+pi run "PROMPT"                                                           # Pi
+```
+
+Wrap in a clock:
+
+```bash
+# 1. cron (>= 1 min floor)
+*/10 * * * * cd /path/to/project && pi run "check X and report" >> ~/agent.log 2>&1
+# 2. systemd timer (Linux, survives reboot, better logging) — OnUnitActiveSec=10min
+# 3. dumb loop (sub-minute, or no cron available)
+while true; do pi run "check X"; sleep 30; done
+```
+
+Gotchas (each breaks unattended runs if ignored):
+- **Permissions hang forever.** Pass `--allowedTools` (Claude) or sandbox/auto-approve flags (Codex), or the run blocks on a prompt.
+- **Use JSON output** (`--output-format json` / `--json`) so the wrapper parses results deterministically.
+- **Runs are amnesiac.** Resume (`codex exec resume --last`) or persist state to a file the next run reads.
+
+Pi has NO built-in scheduler/loop/heartbeat by design — external clock only (or a TS extension for agent-side timers).
+
+### cmux — orchestration only, NO scheduler
+
+cmux has no timer/watch/cron. Three ways to loop it: orchestrator-driven (`send` → `sleep` → `read-screen` on your own clock), a dumb while-sleep wrapper, or — preferred — event-driven via `cmux notify` + OSC terminal hooks, which is cheaper and more responsive than polling. `read-screen` is non-interruptive, safe to poll.
+
+If a loop checks another agent, send the user a one-line status each check: what the agent is doing, on track or not. (Claude Code may prefill a predicted next user message after finishing — that's Claude, not the user.)
+
+## Camp B — Hermes built-in scheduler
+
+Hermes' gateway ticks every 60s and runs due jobs in fresh isolated sessions. State-check first:
+
+```bash
+hermes gateway install            # user-level ( --system to survive reboot)
+hermes cron create "every 1h" "summarize new emails and report" --skill himalaya
+hermes cron create "0 9 * * *" "post daily standup"      # cron expr
+hermes cron create "30m" "one-shot reminder in 30 min"   # one-shot delay
+```
+
+Hermes-unique: **zero-token mode** (run a script, deliver stdout verbatim — use for watchdogs), **chaining** (`context_from` pipes one job's output into the next), **self-terminating loops**, and **loop safety** (scheduled sessions cannot create more cron jobs — don't schedule from inside a scheduled job). Each run is a fresh session: the prompt must carry all context.
+
+## Heartbeat pattern
+
+One fast recurring tick gates many slower per-task checks: the tick reads a task list + per-task `last_run` timestamps and only acts on tasks that are due. In Hermes use a recurring job (zero-token mode when nothing's due); in Camp A use a while-sleep loop. Define active-hours, and stay silent when nothing is due — no empty noise.
+
+## Verify it fires (before reporting success)
+
+1. Camp A: log file grows after one interval, or run the wrapped command once by hand → clean JSON, exit 0.
+2. Camp B: `hermes cron list` shows the job + sane `next_run`; trigger a run-now to confirm delivery.
+3. Confirm permission/sandbox flags are present — the #1 silent failure is a hung permission prompt.
+4. Heartbeats: confirm a nothing-due tick stays silent.
+
+## Limitations
+
+- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
+- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.

package/bundled-skills/alpha-vantage/SKILL.md

@@ -17,7 +17,9 @@ Access 20+ years of global financial data: equities, options, forex, crypto, com
 2. Set as environment variable:
 
 ```bash
-export ALPHAVANTAGE_API_KEY="your_key_here"
+read -rsp "Alpha Vantage API key: " ALPHAVANTAGE_API_KEY
+echo
+export ALPHAVANTAGE_API_KEY
 ```
 
 ## Installation

package/bundled-skills/anti-sleep/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: anti-sleep
+description: "Keep a Mac awake with caffeinate during long builds, downloads, or supervised automation runs."
+category: operations
+risk: critical
+source: community
+source_repo: davidondrej/skills
+source_type: community
+date_added: "2026-07-07"
+author: davidondrej
+tags: [macos, caffeinate, operations]
+tools: [claude, codex]
+license: "MIT"
+license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
+---
+
+# Anti-Sleep (macOS caffeinate)
+
+## When to Use
+
+- Use when the user wants the Mac to stay awake during a long supervised task.
+- Use when a build, download, or automation run should not be interrupted by sleep.
+
+Keep the Mac awake using the built-in `caffeinate` command. No install needed.
+
+## Quick start — the standard command
+
+```bash
+caffeinate -d -i -t 7200    # full power: screen stays on + no idle sleep, for 2 hours
+```
+
+Duration is `-t <seconds>`: 2h = 7200, 7h = 25200, overnight (9h) = 32400.
+
+## Aggressiveness levels
+
+| Flags | Effect |
+|---|---|
+| `-i` | prevents idle **system** sleep only (screen may still dim/lock) |
+| `-d` | prevents **display** sleep (screen stays on) |
+| `-d -i` | **default choice** — screen on + system awake |
+| `-d -i -s` | adds `-s`: prevents sleep even on AC power semantics; `-s` only works when plugged in |
+| `-u -t 1` | simulates user activity — wakes the display right now |
+
+Default to `-d -i -t <seconds>` unless the user says otherwise.
+
+## Tie to a process instead of a timer
+
+```bash
+caffeinate -d -i -w <PID>          # stays awake until that process exits (great for builds)
+caffeinate -i npm run build       # wraps a command; exits when the command finishes
+```
+
+## Run it in a visible terminal (cmux pane)
+
+Prefer running it in the user's own terminal pane so it's visible and easy to Ctrl+C. In cmux (read the `cmux` skill first if interacting with panes):
+
+```bash
+cmux send --surface surface:<N> "caffeinate -d -i -t 25200\n"
+```
+
+Otherwise run it as a background Bash task. Never block your own foreground shell with it.
+
+## Verify and monitor
+
+```bash
+pgrep -fl caffeinate                       # is it running? shows exact flags
+ps -o etime= -p <PID>                      # how long it's been running
+pmset -g assertions | grep -i deny        # confirm sleep assertions are active
+```
+
+**Gotcha:** `caffeinate` prints nothing and holds the prompt — it looks "stuck" or like Enter wasn't pressed. It isn't stuck. Verify with `pgrep`, not by looking at the terminal.
+
+**Expiry:** with `-t` it exits silently when time runs out — no notification. If the user asks "is it still on?" after hours, check `pgrep` first; it may simply have expired.
+
+## Keyboard backlight
+
+`caffeinate` cannot keep the keyboard backlight on — it has its own inactivity timer with no CLI/API on Apple Silicon (researched 2026-07). Fix is manual, one-time: System Settings > Keyboard > "Turn keyboard backlight off after inactivity" > Never.
+
+## Stop early
+
+```bash
+pkill -f "caffeinate -d -i"    # or Ctrl+C in the pane running it
+```
+
+After starting: confirm to the user the PID, the flags, and the wall-clock time it will expire.
+
+## Limitations
+
+- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
+- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.

package/bundled-skills/api-security-best-practices/SKILL.md

@@ -732,7 +732,7 @@ Retry-After: 900
 **Solution:**
 \`\`\`javascript
 // ❌ Bad
-const JWT_SECRET = 'my-secret-key';
+const tokenSigningKey = '[redacted weak value]';
 
 // ✅ Good
 const JWT_SECRET = process.env.JWT_SECRET;

package/bundled-skills/app-store-optimization/SKILL.md

@@ -354,6 +354,13 @@ Generates comprehensive pre-launch and update checklists.
 4. **Test Locally**: Have native speakers review before publishing
 5. **Measure ROI**: Track downloads by locale to assess impact
 
+## Optional External Research Tools
+
+Use external tools only when the workflow needs current market inputs or a second pass on directional estimates. Treat third-party estimates as approximate and cite the retrieval date.
+
+- [AppNiche Revenue Checker](https://getappniche.com/tools/app-revenue-checker) - free iOS App Store revenue benchmark for competitor prioritization and ASO score context.
+- [AppNiche ASO Keyword Opportunity Checker](https://getappniche.com/tools/app-store-keyword-tool) - free iOS keyword opportunity check for keyword research and Apple keyword field planning.
+
 ## Limitations
 
 ### Data Dependencies

package/bundled-skills/audio-transcriber/scripts/transcribe.py

@@ -12,6 +12,19 @@ import shutil
 from datetime import datetime
 from pathlib import Path
 
+
+def safe_user_path(path_value, base_dir="."):
+    """Resolve a CLI path under the current workspace."""
+    if base_dir != ".":
+        raise ValueError("Custom base directories are not supported for CLI paths")
+    base_path = Path.cwd().resolve()
+    resolved_path = Path(path_value).expanduser().resolve()
+    try:
+        resolved_path.relative_to(base_path)
+    except ValueError as exc:
+        raise ValueError(f"Path escapes allowed directory: {path_value}") from exc
+    return resolved_path
+
 # Rich for beautiful terminal output
 try:
     from rich.console import Console
@@ -386,9 +399,9 @@ def save_outputs(transcript_text, ata_text, audio_file, output_dir="."):
     
     # Sempre salva transcript
     transcript_filename = f"transcript-{timestamp}.md"
-    transcript_path = Path(output_dir) / transcript_filename
+    transcript_path = safe_user_path(output_dir) / transcript_filename
     
-    with open(transcript_path, 'w', encoding='utf-8') as f:
+    with transcript_path.open('w', encoding='utf-8') as f:
         f.write(transcript_text)
     
     console.print(f"[green]✅ Transcript salvo:[/green] {transcript_filename}")
@@ -397,9 +410,9 @@ def save_outputs(transcript_text, ata_text, audio_file, output_dir="."):
     ata_path = None
     if ata_text:
         ata_filename = f"ata-{timestamp}.md"
-        ata_path = Path(output_dir) / ata_filename
+        ata_path = safe_user_path(output_dir) / ata_filename
         
-        with open(ata_path, 'w', encoding='utf-8') as f:
+        with ata_path.open('w', encoding='utf-8') as f:
             f.write(ata_text)
         
         console.print(f"[green]✅ Ata salva:[/green] {ata_filename}")

package/bundled-skills/azure-mgmt-botservice-py/SKILL.md

@@ -247,6 +247,7 @@ if hasattr(keys.properties, 'properties'):
 ### Create Connection Setting
 
 ```python
+import os
 from azure.mgmt.botservice.models import (
     ConnectionSetting,
     ConnectionSettingProperties
@@ -260,7 +261,7 @@ connection = client.bot_connection.create(
         location="global",
         properties=ConnectionSettingProperties(
             client_id="<oauth-client-id>",
-            client_secret="<oauth-client-secret>",
+            client_secret=os.environ["BOT_OAUTH_CLIENT_SECRET"],
             scopes="User.Read",
             service_provider_id="<service-provider-id>"
         )

package/bundled-skills/azure-resource-manager-mysql-dotnet/SKILL.md

@@ -60,6 +60,7 @@ Subscription
 ### 1. Create MySQL Flexible Server
 
 ```csharp
+using System;
 using Azure.ResourceManager.MySql.FlexibleServers;
 using Azure.ResourceManager.MySql.FlexibleServers.Models;
 
@@ -74,7 +75,7 @@ MySqlFlexibleServerData data = new MySqlFlexibleServerData(AzureLocation.EastUS)
 {
     Sku = new MySqlFlexibleServerSku("Standard_D2ds_v4", MySqlFlexibleServerSkuTier.GeneralPurpose),
     AdministratorLogin = "mysqladmin",
-    AdministratorLoginPassword = "YourSecurePassword123!",
+    AdministratorLoginPassword = Environment.GetEnvironmentVariable("MYSQL_ADMIN_PASSWORD") ?? throw new InvalidOperationException("MYSQL_ADMIN_PASSWORD is required"),
     Version = MySqlFlexibleServerVersion.Ver8_0_21,
     Storage = new MySqlFlexibleServerStorage
     {

package/bundled-skills/azure-resource-manager-postgresql-dotnet/SKILL.md

@@ -60,6 +60,7 @@ Subscription
 ### 1. Create PostgreSQL Flexible Server
 
 ```csharp
+using System;
 using Azure.ResourceManager.PostgreSql.FlexibleServers;
 using Azure.ResourceManager.PostgreSql.FlexibleServers.Models;
 
@@ -74,7 +75,7 @@ PostgreSqlFlexibleServerData data = new PostgreSqlFlexibleServerData(AzureLocati
 {
     Sku = new PostgreSqlFlexibleServerSku("Standard_D2ds_v4", PostgreSqlFlexibleServerSkuTier.GeneralPurpose),
     AdministratorLogin = "pgadmin",
-    AdministratorLoginPassword = "YourSecurePassword123!",
+    AdministratorLoginPassword = Environment.GetEnvironmentVariable("POSTGRES_ADMIN_PASSWORD") ?? throw new InvalidOperationException("POSTGRES_ADMIN_PASSWORD is required"),
     Version = PostgreSqlFlexibleServerVersion.Ver16,
     Storage = new PostgreSqlFlexibleServerStorage
     {

package/bundled-skills/azure-resource-manager-sql-dotnet/SKILL.md

@@ -72,6 +72,7 @@ ArmClient
 ### 1. Create SQL Server
 
 ```csharp
+using System;
 using Azure.ResourceManager.Sql;
 using Azure.ResourceManager.Sql.Models;
 
@@ -83,7 +84,7 @@ var resourceGroup = await subscription
 var serverData = new SqlServerData(AzureLocation.EastUS)
 {
     AdministratorLogin = "sqladmin",
-    AdministratorLoginPassword = "YourSecurePassword123!",
+    AdministratorLoginPassword = Environment.GetEnvironmentVariable("SQL_ADMIN_PASSWORD") ?? throw new InvalidOperationException("SQL_ADMIN_PASSWORD is required"),
     Version = "12.0",
     MinimalTlsVersion = SqlMinimalTlsVersion.Tls1_2,
     PublicNetworkAccess = ServerNetworkAccessFlag.Enabled

package/bundled-skills/biopython/SKILL.md

@@ -54,11 +54,12 @@ uv pip install biopython
 For NCBI database access, always set your email address (required by NCBI):
 
 ```python
+import os
 from Bio import Entrez
 Entrez.email = "your.email@example.com"
 
 # Optional: API key for higher rate limits (10 req/s instead of 3 req/s)
-Entrez.api_key = "your_api_key_here"
+Entrez.api_key = os.environ.get("NCBI_API_KEY")
 ```
 
 ## Using This Skill

package/bundled-skills/brain-to-docs/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: brain-to-docs
+description: "Interview the user to turn project vision and decisions into README and ADR documentation."
+category: productivity
+risk: critical
+source: community
+source_repo: davidondrej/skills
+source_type: community
+date_added: "2026-07-07"
+author: davidondrej
+tags: [documentation, adr, planning]
+tools: [claude, codex]
+license: "MIT"
+license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
+---
+
+# brain-to-docs
+
+## When to Use
+
+- Use when the user wants to extract project vision, decisions, or preferences into durable docs.
+- Use when README and ADRs should be built through a back-and-forth interview.
+
+The whole purpose: extract as much of the user's taste, judgment, knowledge, vision,
+preferences, and decisions as possible into text — saved as clear, concise
+markdown docs for the project. README holds the vision; `docs/adr/` holds the
+decisions.
+
+## The loop
+
+1. **Check docs first, every time.** Read `docs/adr/` (and `README.md`) before
+   doing anything — other agents and people add/edit ADRs constantly.
+2. **Ask 5 different questions** in plain text (never a questions UI) — default 5
+   unless the user asks for a different number. Make them high-variety: a wide,
+   creative spectrum of unique angles, not all the same type (e.g. not all "tech
+   stack" or all "product" or all "monetization"). Exception: if the user asks for a
+   specific focus area, follow it. The user answers whichever they find most useful.
+3. **Update docs after EVERY answer** — no exceptions. You decide whether it
+   updates `README.md` or becomes a new ADR — whatever makes sense.
+4. Repeat until the user says "we're done" (or similar).
+
+## Rules
+
+- All answers & responses during this "brain to docs" process must be VERY
+  CONCISE, all sentences should be SHORT, and everything should be written in
+  PLAIN ENGLISH.
+- ADRs: short, numbered `NNNN-slug.md`, Status + Context + Decision + Consequences.
+- README: vision only. Decisions go in ADRs.
+- Don't challenge the user's thinking unless they ask, or they're making a severe mistake.
+
+## Limitations
+
+- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
+- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.

package/bundled-skills/browser-harness/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: browser-harness
+description: "Drive an existing browser through CDP for authenticated, visual, or interactive web automation."
+category: browser-automation
+risk: critical
+source: community
+source_repo: davidondrej/skills
+source_type: community
+date_added: "2026-07-07"
+author: davidondrej
+tags: [browser, cdp, automation, scraping]
+tools: [claude, codex]
+license: "MIT"
+license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
+---
+
+# browser-harness
+
+## When to Use
+
+- Use when a task needs a real logged-in browser, visible interaction, or JS-heavy page control.
+- Use when static fetches are insufficient and CDP browser automation is appropriate.
+
+Direct browser control via CDP. For task-specific edits, use `agent-workspace/agent_helpers.py`. For setup, install, or connection problems, read install.md.
+
+**Routing check first:** if the task needs no interaction (no clicks, logins, or forms) and you just want page content, use DeepAPI `POST /v1/scrape/website` instead of driving a browser — see the `deepapi` skill. Use browser-harness when the task needs a real browser: interaction, JS-heavy flows, logged-in sessions, or visual verification.
+
+Domain skills (community-contributed per-site playbooks under `agent-workspace/domain-skills/`) are off by default. Set `BH_DOMAIN_SKILLS=1` to enable them; see the bottom section.
+
+**If `BH_DOMAIN_SKILLS=1` and the task is site-specific, read every file in the matching `agent-workspace/domain-skills/<site>/` directory before inventing an approach.**
+
+## Usage
+
+```bash
+browser-harness -c '
+new_tab("https://docs.browser-use.com")
+wait_for_load()
+print(page_info())
+'
+```
+
+- Invoke as browser-harness — it's on $PATH. No cd, no uv run.
+- First navigation is new_tab(url), not goto_url(url) — goto runs in the user's active tab and clobbers their work.
+
+## Tool call shape
+
+```bash
+browser-harness -c '
+# any python. helpers pre-imported. daemon auto-starts.
+'
+```
+
+run.py calls ensure_daemon() before exec — you never start/stop manually unless you want to.
+
+### Remote browsers
+
+Use remote for parallel sub-agents (each gets its own isolated browser via a distinct BU_NAME) or on a headless server. BROWSER_USE_API_KEY must be set. start_remote_daemon, list_cloud_profiles, list_local_profiles, sync_local_profile are pre-imported.
+
+When supervising those sub-agents, after each check send the user one very short status line: what they are doing and whether they are on track.
+
+Claude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking.
+
+```bash
+browser-harness -c '
+start_remote_daemon("work")                               # default — clean browser, no profile
+# start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
+# start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
+# start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
+# start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
+'
+
+BU_NAME=work browser-harness -c '
+new_tab("https://example.com")
+print(page_info())
+'
+```
+
+start_remote_daemon prints liveUrl and auto-opens it in the local browser (if a GUI is detected) so the user can watch along. Headless servers print only — share the URL with the user. The daemon PATCHes the cloud browser to stop on shutdown, which persists profile state. Running remote daemons bill until timeout.
+
+Profiles (cookies-only login state) live in interaction-skills/profile-sync.md — covers list_cloud_profiles(), the chat-driven "which profile?" pattern, and sync_local_profile() for uploading a local Chrome profile.
+
+## Interaction skills
+
+If you start struggling with a specific mechanic while navigating, look in interaction-skills/ for helpers. They cover reusable UI mechanics like dialogs, tabs, dropdowns, iframes, and uploads. The available interaction skills are:
+- connection.md
+- cookies.md
+- cross-origin-iframes.md
+- dialogs.md
+- downloads.md
+- drag-and-drop.md
+- dropdowns.md
+- iframes.md
+- network-requests.md
+- print-as-pdf.md
+- profile-sync.md
+- screenshots.md
+- scrolling.md
+- shadow-dom.md
+- tabs.md
+- uploads.md
+- viewport.md
+
+## What actually works
+
+- Screenshots first: use capture_screenshot() to understand the current page quickly, find visible targets, and decide whether you need a click, a selector, or more navigation.
+- Clicking: capture_screenshot() → read the pixel off the image → click_at_xy(x, y) → capture_screenshot() to verify. Suppress the Playwright-habit reflex of "locate first, then click" — no getBoundingClientRect, no selector hunt. Drop to DOM only when the target has no visible geometry (hidden input, 0×0 node). Hit-testing happens in Chrome's browser process, so clicks go through iframes / shadow DOM / cross-origin without extra work.
+- Bulk HTTP: http_get(url) + ThreadPoolExecutor. No browser for static pages (249 Netflix pages in 2.8s).
+- After goto: wait_for_load().
+- Wrong/stale tab: ensure_real_tab(). Use it when the current tab is stale or internal; the daemon also auto-recovers from stale sessions on the next call.
+- Verification: print(page_info()) is the simplest "is this alive?" check, but screenshots are the default way to verify whether a visible action actually worked.
+- DOM reads: use js(...) for inspection and extraction when the screenshot shows that coordinates are the wrong tool.
+- Iframe sites (Azure blades, Salesforce): click_at_xy(x, y) passes through; only drop to iframe DOM work when coordinate clicks are the wrong tool.
+- Auth wall: redirected to login → stop and ask the user. Don't type credentials from screenshots.
+- Raw CDP for anything helpers don't cover: cdp("Domain.method", params).
+
+## Design constraints
+
+- Coordinate clicks default. Input.dispatchMouseEvent goes through iframes/shadow/cross-origin at the compositor level.
+- Connect to the user's running Chrome. Don't launch your own browser.
+- cdp-use is only for CDPClient.send_raw. Prefer raw CDP strings over typed wrappers.
+- run.py stays tiny. No argparse, subcommands, or extra control layer.
+- Core helpers stay short. Put task-specific helper additions in `agent-workspace/agent_helpers.py`; daemon/bootstrap and remote session admin live in the core package.
+- Don't add a manager layer. No retries framework, session manager, daemon supervisor, config system, or logging framework.
+
+## Hermes Agent integration
+
+Installed at `~/Developer/browser-harness` as editable `uv tool install -e .`. Binary at `~/.local/bin/browser-harness`. Skill at `~/.hermes/skills/browser-harness/`.
+
+**Frontmatter pitfall:** The upstream SKILL.md ships with `name: browser` in frontmatter, which collides with Hermes's built-in `browser` toolset. When copying into `~/.hermes/skills/`, rename to `name: browser-harness` in the frontmatter or Hermes will shadow/conflict with its own browser tools.
+
+**Brave Browser:** Works identically to Chrome. Enable remote debugging at `brave://inspect/#remote-debugging` (same checkbox). The harness auto-discovers Brave's profile directory.
+
+## Authenticated content extraction (proven pattern)
+
+browser-harness connects to the user's real browser with their active sessions — ideal for extracting content from login-walled sites where `web_extract` or Hermes's built-in `browser_navigate` fail (e.g. X/Twitter articles, LinkedIn, paywalled sites).
+
+**Pattern:**
+```bash
+browser-harness -c '
+new_tab("https://x.com/user/status/123456")
+wait_for_load()
+import time
+time.sleep(5)  # let JS-heavy pages render
+text = js("""
+    const article = document.querySelector("article");
+    if (article) return article.innerText;
+    return document.body.innerText;
+""")
+with open("/tmp/extracted.txt", "w") as f:
+    f.write(text)
+print("Written", len(text), "chars")
+'
+```
+
+- Write to a temp file to avoid shell escaping issues with large text
+- Use `time.sleep()` generously for JS-heavy SPAs (X, LinkedIn need 3-5s)
+- X/Twitter articles render inline — just scroll/extract via DOM, no extra click needed
+- For very long pages, `js(...)` with `innerText` grabs everything including below-fold content
+
+## Hermes Agent integration
+
+Installed at `~/Developer/browser-harness` as editable `uv tool install -e .`. Binary at `~/.local/bin/browser-harness`. Skill at `~/.hermes/skills/browser-harness/`.
+
+**Frontmatter pitfall:** The upstream SKILL.md ships with `name: browser` in frontmatter, which collides with Hermes's built-in `browser` toolset. When copying into `~/.hermes/skills/`, rename to `name: browser-harness` in the frontmatter.
+
+**Brave Browser:** Works identically to Chrome. Enable remote debugging at `brave://inspect/#remote-debugging` (same checkbox). The harness auto-discovers Brave's profile directory.
+
+## Authenticated content extraction (proven pattern)
+
+browser-harness connects to the user's real browser with active sessions — ideal for login-walled sites where `web_extract` or Hermes's built-in `browser_navigate` fail (X/Twitter articles, LinkedIn, paywalled sites).
+
+```bash
+browser-harness -c '
+new_tab("https://x.com/user/status/123456")
+wait_for_load()
+import time
+time.sleep(5)  # let JS-heavy pages render
+text = js("""
+    const article = document.querySelector("article");
+    if (article) return article.innerText;
+    return document.body.innerText;
+""")
+with open("/tmp/extracted.txt", "w") as f:
+    f.write(text)
+print("Written", len(text), "chars")
+'
+```
+
+- Write to a temp file to avoid shell escaping issues with large text
+- Use `time.sleep()` generously for JS-heavy SPAs (X, LinkedIn need 3-5s)
+- X/Twitter articles render inline — just scroll/extract via DOM, no extra click needed
+- `js(...)` with `innerText` grabs everything including below-fold content
+
+## Gotchas (field-tested)
+
+- **Brave Browser** uses `brave://inspect/#remote-debugging` instead of `chrome://inspect/...`. The harness auto-discovers Brave's data dir.
+- Login-walled content extraction (e.g. X/Twitter articles): navigate with `new_tab(url)`, `wait_for_load()`, then extract via `js("document.querySelector('article').innerText")`. Write to a temp file to avoid shell escaping: `with open('/tmp/out.txt', 'w') as f: f.write(text)`. The user's existing browser session handles auth automatically.
+- Omnibox popups are fake page targets. Filter chrome://omnibox-popup... and other internals when you need a real tab.
+- CDP target order != Chrome's visible tab-strip order. Use UI automation when the user means "the first/second tab I can see"; Target.activateTarget only shows a known target.
+- Default daemon sessions can go stale. ensure_real_tab() re-attaches to a real page.
+- Browser Use API is camelCase on the wire. cdpUrl, proxyCountryCode, etc.
+- Remote cdpUrl is HTTPS, not ws. Resolve the websocket URL via /json/version.
+- Stop cloud browsers with PATCH /browsers/{id} + {"action":"stop"}.
+- After every meaningful action, re-screenshot before assuming it worked. Use the image to verify changed state, open menus, navigation, visible errors, and whether the page is in the state you expected.
+- Use screenshots to drive exploration. They are often the fastest way to find the next click target, notice hidden blockers, and decide if a selector is even worth writing.
+- Prefer compositor-level actions over framework hacks. Try screenshots, coordinate clicks, and raw key input before adding DOM-specific workarounds.
+- If you need framework-specific DOM tricks, check interaction-skills/ first. That is where dropdown, dialog, iframe, shadow DOM, and form-specific guidance belongs.
+
+## Domain skills (opt-in)
+
+Only applies when `BH_DOMAIN_SKILLS=1`. Otherwise ignore — `agent-workspace/domain-skills/` is dormant and `goto_url` won't surface skill files.
+
+When enabled, search `agent-workspace/domain-skills/<host>/` before inventing an approach. `goto_url` returns up to 10 skill filenames for the navigated host.
+
+If you learn anything non-obvious — a private API, stable selector, framework quirk, URL pattern, hidden wait, or site-specific trap — open a PR to `agent-workspace/domain-skills/<site>/`. Capture the durable shape of the site (the map, not the diary). Don't write pixel coordinates (break on layout), task narration, or secrets — the directory is public.
+
+## Limitations
+
+- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
+- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.