diff --git a/.gitignore b/.gitignore
index 32a16f6..5f67318 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,3 +7,4 @@ config.yaml
 *.tsbuildinfo
 pnpm-debug.log*
 .claude/settings.local.json
+.playwright-mcp/
diff --git a/.mcp.json b/.mcp.json
new file mode 100644
index 0000000..8163be5
--- /dev/null
+++ b/.mcp.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest", "--isolated"]
+    }
+  }
+}
diff --git a/AGENTS.md b/AGENTS.md
index f825b61..b3b95a3 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,10 +1,26 @@
 # Agent notes
 
-## Dev logs
+Monorepo: `packages/server` (Hono API, port 7100) + `packages/web` (Vite/React, port 7200, proxies `/api` to server).
 
-When `pnpm dev` is running, server and web stdout/stderr are tee'd to:
+## Validating your own work
 
-- `.logs/server.log` — `tsx watch src/index.ts`
-- `.logs/web.log` — `vite`
+Close the loop before declaring done. Available tools:
 
-Tail or read these files to inspect dev output. Logs reset on each `pnpm dev` start; accumulate across hot reloads within a session.
+- `pnpm typecheck` — TS across both packages
+- `pnpm test` — vitest in both packages
+- `pnpm lint` — oxlint
+- `pnpm fmt:check` — oxfmt
+- `pnpm dev` — runs server + web concurrently (long-running; start in background). Stdout/stderr is tee'd to `.logs/server.log` and `.logs/web.log` — tail or read these to inspect output. Logs reset on each start; accumulate across hot reloads within a session.
+
+For UI/UX changes, type-checks aren't enough — drive the app via the **Playwright MCP** (`.mcp.json`):
+
+- `browser_navigate` to `http://localhost:7200`
+- `browser_snapshot` for the accessibility tree (preferred over screenshots for assertions)
+- `browser_click`, `browser_type`, `browser_press_key` to exercise keyboard shortcuts
+- `browser_console_messages` to catch runtime errors
+- `browser_network_requests` to verify `/api/*` calls
+- `browser_take_screenshot` only when visual confirmation is needed
+
+Typical loop: edit → dev server hot-reloads → snapshot/interact → check console + `.logs/*` → iterate.
+
+A `config.yaml` with valid tokens already exists locally; don't overwrite it.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file