docs(playwright): browser-1 by default, seven-browser pool opt-in on one shared server

[WilcoLouwerse]

Why

Companion to ConductionNL/hydra feat/shared-playwright-mcp-server. Claude Code starts every stdio MCP server in .mcp.json at session start; seven per session is how a 16 GB Linux VM ran out of memory on 2026-09-08 with 98 idle Playwright processes and zero browsers open.

What

• docs/claude/playwright-setup.md rewritten around the new layout: one browser-1 in the project .mcp.json, the pool under hydra/.claude/mcp/, one shared @playwright/mcp on localhost:8931 referenced by http URLs (zero processes per session), user-scope registration for VS Code (which cannot take --mcp-config), the headed browser-6 kept as stdio. The old "CLI alternative" with seven ports is superseded by the shared server.
• examples/.mcp.json.example is now browser-1 only; new examples/browser-pool-shared.json.example is the opt-in pool.
• README.md, testing.md, global-claude-settings.md, workstation-setup.md point at the same facts instead of describing .mcp.json as the 7-browser file.
• Review follow-up: three stale references that contradicted the above are corrected too — the discovery-stage tooling table in docs/claude/README.md, the ICT-infrastructure inventory in docs/iso/code.md, and the /ecosystem-investigate description in docs/claude/commands-tender.md.
• docs/hydra/* (container-image .mcp.json) deliberately untouched.

Notes for the merger

Updated 2026-09-11. The earlier version of this section described #716, #718 and #719 as open; all three have since merged. This branch has been updated from main (merge commit in the history), so the one-line edits now sit on top of #719's rewrite rather than beside it. No conflicts.

🤖 Generated with Claude Code

[WilcoLouwerse]

Merge-order check against the other open PRs

File-level overlap with the open docs PRs, and a dry-run merge of each against this branch (git merge-tree --write-tree):

PR	Shared file(s)	Dry-run
#716	docs/claude/global-claude-settings.md	clean
#718	docs/claude/global-claude-settings.md	clean
#719	docs/claude/README.md, docs/claude/testing.md	clean
#720	none	—

Different sections in each case: this PR touches only the MCP/browser-pool lines. Order does not matter.

This branch is rebased on 477f930e (current main).

[WilcoLouwerse]

Inline findings from a Standard review. Verdict follows in a separate review.

[WilcoLouwerse]

Verdict: APPROVE (Standard) — self-review posted as COMMENT (GitHub blocks approving your own PR)

No blockers. Doc-to-code fidelity against ConductionNL/hydra#653 is strong: every path, the port, the env var name, the systemd unit name, the journalctl invocation, all seven subcommands, and both JSON examples were checked against the actual files at a8a5ade and match. browser-6 is correctly the only stdio entry and browser-7 is correctly in the http set — no off-by-one. Trailing newlines present on all seven files; both JSON examples parse; code fences balanced.

One 🟡 inline: a dead anchor this PR creates in global-claude-settings.md:287, where the rewrite renamed the heading the link targets. Two 🟢 notes on version drift and section ordering.

The docs/hydra/* deferral was verified rather than taken on trust: those files describe the container-baked .mcp.json under images/{builder,reviewer,security}/, and run-browser-tests.sh writes its own separate single-browser config — none of it is workstation guidance, so leaving them untouched is right.

Follow-up — three stale references outside this PR's diff

Not posted inline because the lines are not in this diff, but each contradicts what this PR establishes:

• docs/claude/README.md:245 — the discovery-stage table still lists Playwright browsers (browser-1–browser-7) as available tooling, which the same file now contradicts at line 442.
• docs/iso/code.md:468 — states 7 Playwright MCP browser sessions (browser-1 … browser-7) as the standing ICT infrastructure. This one is a compliance-document inventory claim, so it is the most worth correcting.
• docs/claude/commands-tender.md:90 — /ecosystem-investigate says it "Uses the browser pool (browser-1 through browser-5)" with no note that the pool now needs the shared server.

Note for the merger

The merge-order comment on this PR is now stale: #716, #718 and #719 have all merged. This branch is 17 commits behind main but still merges clean — git merge-tree --write-tree exits 0 and GitHub reports MERGEABLE/CLEAN. The overlap enumeration in that comment was accurate (#716/#718 on global-claude-settings.md, #719 on README.md + testing.md); worth an Update branch before merging so the one-line edits land on top of #719's rewrite rather than beside it.

[WilcoLouwerse]

Verdict: APPROVE (Quick) — self-review posted as COMMENT (GitHub blocks approving your own PR)

All three inline findings and all three follow-ups from the previous pass are addressed.

• The dead anchor now points at playwright-setup.md#the-pool-in-vs-code, which matches the heading exactly. A repo-wide sweep of anchored links into every file this PR rewrote found no other dangling anchor.
• The version-freeze sentence is accurate, and — the part worth checking rather than assuming — the remedy it names actually works. It tells the reader to restart, and restart in the companion PR was unit-aware only as of that PR's own fix commit. Before that, stop + start would have left the unit enabled-but-inactive with the server running as a loose foreground process, so the documented remedy would have silently un-managed the service. Doc and code agree now.
• The forward reference sits inside the fenced snippet as a bash comment and cites the section verbatim.

The three stale references outside the original diff are corrected. The compliance-document one in docs/iso/code.md was the one worth getting right, and the replacement neither overstates nor understates: it describes one shared server with up to seven named sessions, only browser-1 configured by default, which is what the code ships.

Verified rather than taken on trust: both examples/*.example files are identical to hydra's real .mcp.json and .claude/mcp/browser-pool-shared.json when parsed; every one of the seven subcommands the script implements is documented and no documented subcommand is missing from the script; the port, env var name, unit name and journalctl invocation all match; browser-6 is the only stdio entry and browser-7 is correctly in the http set; every changed file ends with a newline.

The merge from main since the last review brought in 19 commits and broke nothing in this PR's files. Required checks pass and the merge state is clean, so the stale merger note is resolved as well as corrected.