feat: add standalone Playwright recorder tool with Docker-based codegen

- introduce repo-local, ephemeral Playwright codegen workflow
- add executable codegen script using official Playwright Docker image
- persist generated recordings under recordings/ (git-ignored, .gitkeep)
- add minimal Makefile with install and codegen targets
- switch project license to MIT
- improve README with clear usage, requirements, and design rationale
- add MIRRORS file for multi-remote setup
- clean up gitignore for generated artifacts and node tooling

README.md

@@ -1,6 +1,138 @@
-# playwright-recorder
+# 🎭 playwright-recorder
 
-Homepage: https://github.com/kevinveenbirkenbach/playwright-recorder
+> A small, reproducible Playwright **recording / codegen tool**  
+> built around **Docker**, **X11/XWayland**, and **ephemeral workspaces**
 
-## Author
-Kevin Veen-Birkenbach <kevin@veen.world>
+🔗 Homepage: https://github.com/kevinveenbirkenbach/playwright-recorder
+
+---
+
+## ✨ What is this?
+
+`playwright-recorder` is a **developer tool** for recording Playwright tests via
+the official Playwright **codegen** feature — without polluting your project:
+
+- 🎥 **GUI-based recording** (Playwright Inspector)
+- 🧼 **Always fresh** (no reused state, no lockfile pain)
+- 🐳 **Runs fully in Docker**
+- 🗂️ **Repo-local, git-ignored workspace**
+- 📄 **Only generated tests are persisted**
+- 🚫 **No `/tmp` usage**
+
+Perfect for:
+- recording login flows
+- capturing UI regressions
+- generating first test drafts
+- infra-heavy projects where Playwright does *not* belong in the main repo
+
+---
+
+* `recordings/` is **ignored by git**
+* `.gitkeep` ensures the folder exists
+* ephemeral workspace lives in `recordings/.work/` and is auto-cleaned
+
+---
+
+## 🚀 Usage
+
+### 1️⃣ Requirements
+
+* Docker
+* X11 or XWayland (Wayland-only will NOT work)
+* `xhost`
+
+On Arch Linux:
+
+## ⚙️ Installation (one-time)
+
+Prepare the recorder script:
+
+```bash
+make install
+```
+
+This makes `scripts/codegen.sh` executable.
+
+---
+
+## 🎥 Start recording
+
+```bash
+make codegen
+```
+
+Or with a start URL:
+
+```bash
+./scripts/codegen.sh https://example.com/login
+```
+
+---
+
+## 📤 Output
+
+* 📄 Generated test:
+
+  ```text
+  recordings/codegen.spec.ts
+  ```
+
+* 🧼 Ephemeral workspace (auto-deleted):
+
+  ```text
+  recordings/.work/
+  ```
+
+Nothing else touches your repo.
+
+---
+
+## ⚙️ Configuration (optional)
+
+Environment variables:
+
+| Variable             | Default           | Description         |
+| -------------------- | ----------------- | ------------------- |
+| `PLAYWRIGHT_VERSION` | `1.58.1`          | Playwright version  |
+| `PLAYWRIGHT_IMAGE`   | auto              | Docker image tag    |
+| `RECORDINGS_DIR`     | `recordings`      | Output directory    |
+| `OUTPUT_FILE`        | `codegen.spec.ts` | Generated file name |
+| `TARGET`             | `playwright-test` | Codegen target      |
+| `DISPLAY`            | `:0`              | X11 display         |
+
+Example:
+
+```bash
+OUTPUT_FILE=login.spec.ts make codegen
+```
+
+---
+
+## 🧠 Design philosophy
+
+* ❌ Not a test runner
+* ❌ Not CI tooling
+* ❌ Not framework glue
+* ✅ A **focused recording utility**
+* ✅ One job, done well
+
+---
+
+## 🔐 Security note
+
+`xhost +local:docker` is used **temporarily** to allow GUI access.
+Access is **revoked automatically** when the script exits.
+
+---
+
+## 🧑‍💻 Author
+
+Kevin Veen-Birkenbach
+📧 [kevin@veen.world](mailto:kevin@veen.world)
+🏡 [www.veen.world](https://www.veen.world)
+
+---
+
+## 📜 License
+
+MIT License – see [LICENSE](LICENSE)