用途：在修改或视觉调试 Nango 前端 UI 时使用，涉及 packages/webapp、packages/connect-ui、浏览器交互、截图等场景。
核心规则：常规 Web UI 检查应使用受控浏览器或无头环境，未经明确要求不要打开用户现有浏览器标签；截图、trace 和临时 Playwright 脚本存放到 .context/ 下且不提交；仅当任务需要真实 macOS 桌面、原生窗口、可见浏览器会话或 Accessibility 树检查时才用 Peekaboo；本地启动细节以 running-and-testing-locally 为准。
Nango 目标：Dashboard webapp 位于 http://localhost:3000，常用命令 npm run dev:watch:web；API server 位于 http://localhost:3003，常用 npm run server:dev:watch；Connect UI 位于 http://localhost:3009，常用 npm run dev:watch:web 或 npm run connect-ui:dev:watch。多数前端工作运行 npm run dev:docker、npm run dev:watch、npm run dev:watch:web。后两个为长驻命令，需分开会话并等待首次 TypeScript 构建完成后再做浏览器测试。
标准截图流程：启动或复用本地服务；用受控浏览器工具抓取桌面基线，如有 Playwright MCP 或浏览器工具则使用，否则用无头 Playwright 而不修改仓库依赖，例如 npx playwright screenshot --browser=chromium --viewport-size=1512,862 http://localhost:3000 .context/nango-webapp-desktop.png；Connect UI 同理替换端口为 3009。若提示 Chromium 缺失，执行 npx playwright install chromium。用 view_image 查看截图后编辑最小相关文件，改完运行 npm run ts-build 验证；仅 webapp 视觉工作可 cd packages/webapp && npm run build，Connect UI 运行 npm run connect-ui:build。完成前重新截图并对比。
无头交互：点击、填表、认证或多步检查时，在 .context/ 下创建临时 Playwright 脚本运行并保存截图；使用稳定选择器与可见文本，避免依赖用户浏览器状态。常见流程包括 Dashboard 在 3000 端口登录/注册，认证后的 Integrations、Connections、Logs、Metrics 及环境设置页面，以及 3009 端口的 Connect UI；需要认证时遵循 running-and-testing-locally 中的本地凭据与验证日志流程。
启动排障：若服务启动出现 Knex 迁移目录损坏或文件缺失错误，说明本地数据库含其他分支迁移，不要未经确认重置用户数据库；仅做视觉验证时可使用临时数据库，相关命令包括用 docker exec nango-db psql 创建和删除 nango_ui_skill_validation，并用 NANGO_DB_NAME=nango_ui_skill_validation npm run dev:watch:web 启动。
Peekaboo 工作流：先检查权限 peekaboo permissions status，Screen Recording 与 Accessibility 均需 Granted；优先按窗口 id 定向捕获，避免按应用名捕获卡住，例如 peekaboo list windows、peekaboo image 与 peekaboo see 命令。常规检查避免用 peekaboo open 在用户现有浏览器创建标签。
复查清单：布局风险明显时编辑前抓取基线截图；编辑后抓取桌面截图；截图、trace 和临时脚本留在 .context/；浏览器自动化不依赖用户现有浏览器状态；前端改动后运行 npm run ts-build 或相关包构建。