docs: add cloakbrowser migration plan

docs/plans/2026-03-11-web-automation-cloakbrowser-design.md

@@ -0,0 +1,33 @@
+# Web Automation CloakBrowser Migration Design
+
+## Goal
+Replace all Camoufox and direct Playwright Chromium usage in `web-automation` with CloakBrowser, while preserving the existing feature set: one-shot extraction, persistent browsing sessions, authenticated flows, multi-step automation, and markdown scraping. After local validation, keep the repo copy and docs as the canonical published version, then commit and push.
+
+## Architecture
+`web-automation` will become CloakBrowser-only. A single browser-launch layer in `skills/web-automation/scripts/browse.ts` will provide the canonical runtime for the other scripts. Stateful flows will use CloakBrowser persistent contexts; one-shot extraction will also use CloakBrowser instead of raw `playwright.chromium`.
+
+## Scope
+- Replace `camoufox-js` in `browse.ts` and any helper/test scripts
+- Replace direct `playwright.chromium` launch in `extract.js`
+- Update shared types/imports to match the CloakBrowser Playwright-compatible API
+- Remove Camoufox/Chromium-specific setup instructions from skill docs
+- Update package metadata and lockfile to depend on `cloakbrowser`
+- Keep the user-facing command surface stable where possible
+
+## Compatibility Strategy
+To minimize user breakage:
+- keep the script filenames and CLI interfaces stable
+- support old `CAMOUFOX_*` env vars as temporary aliases where practical
+- introduce neutral naming in docs and code for the new canonical path
+
+## Testing Strategy
+- Verify launcher setup directly through `browse.ts`
+- Verify `extract.js` still handles: missing URL, invalid scheme, smoke extraction from `https://example.com`
+- Verify one persistent-context path and one higher-level consumer (`scrape.ts` or `flow.ts`) still works
+- Update docs only after the runtime is validated
+
+## Rollout
+1. Implement and verify locally in the repo worktree
+2. Update repo docs/indexes to describe CloakBrowser-based `web-automation`
+3. Commit and push the repo changes
+4. If needed, sync the installed OpenClaw workspace copy from the validated repo version