docs: add CLAUDE.md project instructions

Co-Authored-By: Virgil <virgil@lethean.io>

CLAUDE.md

@@ -1,33 +1,63 @@
 # CLAUDE.md
 
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 Module: `forge.lthn.ai/core/go-webview` — Chrome DevTools Protocol client for browser automation.
 
 ## Commands
 
 ```bash
 go test ./...                          # Run all tests (must pass before commit)
-go test -v -run Name   # Run a single test
+go test -v -run TestActionSequence_Good ./...  # Run a single test
 gofmt -w .                             # Format code
+go vet ./...                           # Static analysis
 ```
 
+## Prerequisites
+
+Tests and usage require a running Chrome/Chromium with `--remote-debugging-port=9222`. The package does not launch Chrome itself. Verify with `curl http://localhost:9222/json`.
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
+
+# Headless (CI)
+google-chrome --headless=new --remote-debugging-port=9222 --no-sandbox --disable-gpu
+```
+
+## Architecture
+
+```
+Application Code → Webview (high-level API) → CDPClient (WebSocket transport) → Chrome
+```
+
+Single flat package (`package webview`). No sub-packages.
+
+| File | Layer | Purpose |
+|------|-------|---------|
+| `cdp.go` | Transport | WebSocket connection, CDP message framing, event dispatch. No browser-level logic. |
+| `webview.go` | High-level API | Navigate, Click, Type, Screenshot, DOM queries, console capture. Application-facing. |
+| `actions.go` | Action system | `Action` interface + concrete types (ClickAction, TypeAction, etc.) + fluent `ActionSequence` builder. |
+| `console.go` | Diagnostics | `ConsoleWatcher` (filtered console capture) and `ExceptionWatcher` (JS exception tracking). |
+| `angular.go` | SPA helpers | Angular-specific: Zone.js stability, router navigation, component introspection, ngModel access. |
+
+Key patterns:
+- `CDPClient.Call(ctx, method, params)` sends a CDP command and blocks for the response via a pending-channel map.
+- Events flow from Chrome → `readLoop` goroutine → registered handlers (each dispatched in its own goroutine).
+- `Webview` enables `Runtime`, `Page`, and `DOM` CDP domains on construction; console capture starts immediately.
+- New action types: add struct + `Execute` method in `actions.go`, builder method on `ActionSequence`, `_Good` test.
+- New SPA framework helpers: create `<framework>.go` following the `angular.go` pattern.
+
 ## Coding Standards
 
-- UK English in all comments, docs, and commit messages
+- UK English in all comments, docs, and commit messages (behaviour, colour, initialise)
 - EUPL-1.2 licence header (`// SPDX-License-Identifier: EUPL-1.2`) in every Go file
-- Conventional commits: `type(scope): description`
+- Conventional commits: `type(scope): description` (scopes: cdp, angular, console, actions)
 - Co-author trailer on every commit: `Co-Authored-By: Virgil <virgil@lethean.io>`
 - Test naming: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (panics/edge cases)
-
-## Key API
-
-```go
-wv, err := webview.New(webview.WithDebugURL("http://localhost:9222"))
-defer wv.Close()
-wv.Navigate("https://example.com")
-wv.Click("#submit")
-wv.Type("#input", "text")
-screenshot, _ := wv.Screenshot()
-```
+- Standard `testing.T` only — no test frameworks
+- Wrap errors with `fmt.Errorf("context: %w", err)`
+- Protect shared state with `sync.RWMutex`; copy handler slices before calling outside lock
 
 ## Docs