WilcoLouwerse · Sep 11, 2026 · Sep 8, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/docs/claude/README.md b/docs/claude/README.md
@@ -114,7 +114,7 @@ How to run Claude Code with a local Qwen model via Ollama for privacy, cost redu
 
 ### [Playwright MCP Browser Setup](./playwright-setup.md)
 
-Detailed setup guide for the 7 independent Playwright browser sessions used for parallel testing, including VS Code extension configuration, CLI alternatives, and usage rules.
+Setup guide for the Playwright MCP browsers: `browser-1` by default, the opt-in seven-browser pool on one shared server for parallel testing, VS Code user-scope registration, verification and usage rules.
 
 ### [Usage Tracker](../../usage-tracker/README.md)
 
@@ -242,7 +242,7 @@ Collect requirements, study existing solutions, and identify what to build. Clau
 | Source                 | How                                                                                                    | Commands / Tools                                                                                       |
 | ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
 | **Tracking issues**    | Sync and analyze open issues from project repos (GitHub; `tea` only for non-Conduction Forgejo repos)  | `/swc-update`, `gh issue list`, `tea issues list`                                                      |
-| **Other applications** | Crawl code or browse running apps to understand patterns                                               | `/opsx-explore`, Playwright browsers (`browser-1`–`browser-7`)                                         |
+| **Other applications** | Crawl code or browse running apps to understand patterns                                               | `/opsx-explore`, Playwright browsers (`browser-1`; `browser-2`–`browser-7` opt-in)                                         |
 | **Documentation**      | Read docs from other platforms, APIs, standards                                                        | `WebFetch`, `WebSearch`, `/opsx-explore`                                                               |
 | **Tenders**            | Scrape TenderNed, classify by category, analyze requirements and ecosystem gaps                        | `/tender-scan`, `/tender-status`, `/tender-gap-report`, `/ecosystem-investigate`, `Read` (PDF support) |
 | **App store scouting** | Spot interesting apps on WordPress plugin directory, GitHub/Codeberg trending, ArtifactHub, Nextcloud app store | `WebSearch`, `WebFetch`, Playwright browsers                                                  |
@@ -440,7 +440,7 @@ cp docs/claude/examples/CLAUDE.local.md.example .claude/CLAUDE.local.md
 
 ## Playwright MCP Browser Setup
 
-The workspace uses 7 independent Playwright browser sessions for parallel testing. Copy the [example .mcp.json](./examples/.mcp.json.example) to your project root as `.mcp.json`, or see the [playwright-setup.md](./playwright-setup.md) guide for the full configuration, verification steps, CLI alternatives, and usage rules.
+Every project ships **one** headless browser (`browser-1`) in its root `.mcp.json` — copy the [example .mcp.json](./examples/.mcp.json.example). The seven-browser pool for parallel agents is opt-in: one shared `@playwright/mcp` server on `localhost:8931`, referenced by URL, so a pool costs zero processes per session ([example](./examples/browser-pool-shared.json.example)). Claude Code starts every stdio server in `.mcp.json` at session start; seven per session is how WSL ran out of memory on 2026-09-08. See [playwright-setup.md](./playwright-setup.md) for the shared server, the user-scope registration for VS Code, verification steps and usage rules.
 
 **Quick summary:**
 
@@ -491,7 +491,8 @@ This repo contains **documentation**, **global settings**, and **project templat
 │       ├── retrofit.md                  # Legacy app retrofit playbook
 │       └── examples/                    # Project-level template files
 │           ├── CLAUDE.local.md.example      # Template for project .claude/CLAUDE.local.md
-│           └── .mcp.json.example            # Template for project root .mcp.json (7 browsers)
+│           ├── .mcp.json.example            # Template for project root .mcp.json (browser-1 only)
+│           └── browser-pool-shared.json.example  # Opt-in 7-browser pool pointing at the shared server
 │
 ├── global-settings/                  # Mandatory user-level settings for ~/.claude/
 │   ├── settings.json                     # → ~/.claude/settings.json (global read-only policy)
@@ -511,7 +512,7 @@ Each Conduction project (Nextcloud apps, WordPress sites, etc.) has its own `.cl
 
 ```
 <project-root>/
-├── .mcp.json                     # Playwright browser MCP servers (see docs/claude/examples/.mcp.json.example)
+├── .mcp.json                     # Playwright browser-1 (see docs/claude/examples/.mcp.json.example); pools live in .claude/mcp/
 │
 └── .claude/
     ├── CLAUDE.md                     # Workflow rules, project context
@@ -647,6 +648,8 @@ npx -y @playwright/mcp@latest --headless --isolated --port 9999
 # Should print: Listening on http://localhost:9999
 ```
 
+If the pool entries (`browser-2`…) fail while `browser-1` works, the shared server is not running: `scripts/playwright-mcp-server.sh status` in the hydra checkout.
+
 ### Claude Code doesn't see commands
 
 Ensure `.claude/` is at the workspace root and Claude Code is started from that directory.

diff --git a/docs/claude/commands-tender.md b/docs/claude/commands-tender.md
@@ -87,7 +87,7 @@ Deep-dive research into a software category — find and analyze open-source com
 **What it does:**
 
 1. Loads category context and related tenders from the intelligence database
-2. Uses the browser pool (browser-1 through browser-5) to scrape 5-10 competitors from multiple source types
+2. Uses the browser pool (browser-1 through browser-5) to scrape 5-10 competitors from multiple source types — the pool beyond `browser-1` is opt-in and needs the shared server, see [playwright-setup.md](playwright-setup.md)
 3. Creates competitor profiles in `concurrentie-analyse/{category}/{competitor-slug}/`
 4. Inserts competitors and feature data into the database with provenance tracking
 5. Presents a comparison table and recommendation for Nextcloud ecosystem fit

diff --git a/docs/claude/examples/.mcp.json.example b/docs/claude/examples/.mcp.json.example
@@ -3,30 +3,6 @@
     "browser-1": {
       "command": "npx",
       "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
-    },
-    "browser-2": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
-    },
-    "browser-3": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
-    },
-    "browser-4": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
-    },
-    "browser-5": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
-    },
-    "browser-6": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
-    },
-    "browser-7": {
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--headless", "--isolated"]
     }
   }
 }
diff --git a/docs/claude/examples/browser-pool-shared.json.example b/docs/claude/examples/browser-pool-shared.json.example
@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "browser-1": { "type": "http", "url": "http://localhost:8931/mcp" },
+    "browser-2": { "type": "http", "url": "http://localhost:8931/mcp" },
+    "browser-3": { "type": "http", "url": "http://localhost:8931/mcp" },
+    "browser-4": { "type": "http", "url": "http://localhost:8931/mcp" },
+    "browser-5": { "type": "http", "url": "http://localhost:8931/mcp" },
+    "browser-6": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--browser", "chromium", "--isolated"]
+    },
+    "browser-7": { "type": "http", "url": "http://localhost:8931/mcp" }
+  }
+}
diff --git a/docs/claude/global-claude-settings.md b/docs/claude/global-claude-settings.md
@@ -296,8 +296,8 @@ Restart Claude Code or run `/hooks`. From then on your hooks fire alongside the
 
 `settings.json` does not read an `mcpServers` key ([Claude Code docs](https://code.claude.com/docs/en/debug-your-config#check-common-causes)), so MCP servers are **not** part of the global settings. Versions up to 2.4.0 shipped a dead `mcpServers` block with 7 Playwright browsers; it never loaded anything and was removed in 2.4.1. Configure MCP servers at one of the two supported scopes instead:
 
-- **Project scope** — `.mcp.json` at the repository root, committed so the whole team gets the same servers. Hydra ships one with the 7-browser pool; a workspace that symlinks Hydra's `.claude/skills` symlinks its `.mcp.json` the same way. See [playwright-setup.md](playwright-setup.md).
-- **User scope** — `claude mcp add --scope user …`, stored in `~/.claude.json` and loaded in every project on your machine. See [playwright-setup.md → User scope](playwright-setup.md#user-scope-all-projects-on-this-machine).
+- **Project scope** — `.mcp.json` at the repository root, committed so the whole team gets the same servers. Hydra ships one with `browser-1` only; the seven-browser pool is opt-in under `.claude/mcp/` (shared server, URL entries). A workspace that symlinks Hydra's `.claude/skills` symlinks `.mcp.json` and `.claude/mcp` the same way. See [playwright-setup.md](playwright-setup.md).
+- **User scope** — `claude mcp add --scope user …`, stored in `~/.claude.json` and loaded in every project on your machine. See [playwright-setup.md → The pool in VS Code](playwright-setup.md#the-pool-in-vs-code).
 
 When both define the same server name, the project-scope entry wins.