@wenathlan/saddle 1.8.16 → 1.8.18

package/docs/plans/02.research.computer.use.md

@@ -1,58 +0,0 @@
-# 02 — Pesquisa: Computer Use Agents (2026)
-
-## Estado da arte
-
-Em 2026, *computer-use agents* deixaram de ser protótipos e entraram em produção para
-tarefas restritas e supervisionadas. Principais provedores e frameworks:
-
-- **Anthropic Computer Use** (`computer_use_20251124`): ferramentas `computer` (mouse/teclado),
-  `text_editor`, `bash`. Recomenda rodar em **VMs/containers com privilégios mínimos**.
-- **OpenAI Operator / CUA**: 87% de sucesso em sites JS complexos; 58% no WebArena.
-- **Google Project Mariner**: 83.5% WebVoyager, 84% ScreenSpot.
-- **Microsoft UFO²**: funde Windows UI Automation + OmniParser (visão).
-- **browser-use** (open source): 89.1% WebVoyager (abordagem híbrida DOM + visão).
-
-### Benchmarks
-- **OSWorld:** humano 72.36% vs SOTA ~12–20% (desktop ainda imaturo).
-- **WebArena:** tops ~71%, produção na faixa 50–60%.
-- **WebVoyager:** browser-use 89.1% (híbrido).
-
-### Conclusão de arquitetura
-Ganham abordagens **híbridas**:
-1. Raciocínio por **DOM / accessibility tree** para elementos estruturados.
-2. **Visão** (VLM) para layouts não-padrão, canvas, imagens.
-3. **Scripts determinísticos** para validação e replay.
-4. **Verificação** (screenshot antes/depois, diff de elementos).
-
-## Projetos de referência encontrados
-
-| Projeto | Diferencial relevante para UKA |
-|---------|-------------------------------|
-| [agentbrowser](https://github.com/AshtonVaughan/agentbrowser) | Cursor visível humano via CDP, trilha SVG, trajetórias Bézier com jitter/overshoot, **traces JSONL** em `~/.agentbrowser/traces/`, replay determinístico por seed, bypass de Cloudflare/OneTrust |
-| [humanjs](https://github.com/totigm/humanjs) | Playwright humanizado: curvas Bézier, ritmo de digitação, scroll, **personalidades** (careful/fast/distracted/precise), gravador → JSON timeline, MCP server |
-| [human-browser-use](https://github.com/andyless/human-browser-use) | Extensão p/ browser-use: trajetória Bézier, typing lognormal, scroll inercial, stealth fingerprint (`navigator.webdriver`, WebGL, canvas) |
-| [agentic-stealth-browser](https://github.com/shanewas/agentic-stealth-browser) | TLS spoofing (JA3/JA4), fingerprint, recovery chain (detecta captcha → rotaciona proxy), account warming |
-| [mantis](https://github.com/mercurialsolo/mantis) | Agent perception-reasoning-action em Xvfb+Chrome+xdotool (sem fingerprint Playwright), vídeo screencast, deploy em Baseten/Modal/EKS/GKE |
-| [win-pilot-mcp](https://github.com/omidmanoochehri/win-pilot-mcp) | MCP Windows computer-use: screen capture, OCR, mouse humano, logging estruturado, replay de macros |
-| [cloakbrowser-human](https://github.com/evelaa123/cloakbrowser-human) | Wrapper Playwright que adiciona camada **comportamental** (mouse Bézier, typing, scroll) — complementa stealth de fingerprint |
-
-## Padrões de movimento humano (extraídos da pesquisa)
-
-- **Trajetória do mouse:** curva Bézier única, velocidade variável por arc-length:
-  - 0–5%: ramp-up (0.3x → 2.5x)
-  - 5–75%: cruise (2.3–2.5x) com variação senoidal
-  - 75–100%: ease-out cúbico (2.5x → 0.3x)
-  - sub-pixel drift final (σ 0.3–1.5px)
-  - duração via **Lei de Fitts**: `0.05 + 0.07*log2(1 + distance/20)` s
-- **Overshoot:** ~15% de chance, auto-aumenta em movimentos longos.
-- **Typing:** inter-key delay lognormal (μ=4.17, σ=0.3 → ~65ms), bigram speedup, 2% typo.
-- **Scroll:** wheel events com acel/decel, overshoot, settle delay.
-- **Stealth:** `navigator.webdriver → undefined`, spoof de plugins/WebGL/canvas, flags de launch.
-
-## Aplicação no UKA
-
-- Implementar `HumanCursor` (SVG overlay + CDP `Input.dispatchMouseEvent`) inspirado no
-  agentbrowser/humanjs, com trajetórias Bézier + jitter + overshoot determinísticas por seed.
-- Gravar **todos os eventos** como `SessionEvent` tipado → exportar JSON para `docs/logs/`.
-- Usar replay determinístico (seed) para testes reprodutíveis.
-- Tratar GUI como imagem (visão) + DOM/accessibility para alvos estruturados.

package/docs/plans/03.research.captcha.bypass.md

@@ -1,68 +0,0 @@
-# 03 — Pesquisa: hCaptcha / Cloudflare / reCAPTCHA Bypass
-
-## Contexto
-
-O UKA precisa **testar** a capacidade do computer-use de enfrentar captchas fortes. A
-pesquisa abaixo levanta abordagens open-source e comerciais (uso edUKAcional / automação
-supervisionada).
-
-## hCaptcha
-
-### hcaptcha-challenger (QIN2DIM) — referência principal
-- Resolve hCaptcha com **LLM multimodal** (sem Tampermonkey, sem serviço anti-captcha 3º).
-- Modelos plugáveis (ONNX):
-  - `image_label_binary` → ResNet ✅
-  - `image_label_area_select: point` → YOLOv8 ✅
-  - `image_label_area_select: bounding box` → YOLOv8 segmentation
-  - `image_drag_drop` → Spatial Chain-of-Thought ✅
-  - `image_label_multiple_choice` → ViT zero-shot
-- Pipeline: `install()` → `AgentT.from_page()` → `handle_checkbox()` → `execute()` loop.
-- Deps: `playwright`, `httpx`, `opencv-python`, `pillow`, `loguru`, `pydantic-settings`.
-
-### Outros solvers
-- **hCaptcha-Solver (Camoufox + Multibot):** usa Camoufox p/ HSW token + Groq vision +
-  **geração de movimento de mouse realista** (Multibot API). Lida com `image_label_binary`,
-  `area_select`, `drag_drop`. Requer proxy.
-- **maximedrn/hcaptcha-solver-python-selenium:** userscript Tampermonkey + Selenium (edUKAcional).
-- **auto-captcha-solver / auto-captcha (NopeCHA):** detecta hCaptcha, reCAPTCHA v2/v3,
-  Cloudflare Turnstile via **API de token NopeCHA**; injeta token automaticamente. Tem MCP
-  server e CLI. Tipos: hCaptcha ✅, reCAPTCHA v2/v3 ✅, Turnstile ⚠️ (lento).
-
-## Cloudflare (Turnstile / interstitials)
-
-- **agentic-stealth-browser** passa Cloudflare interstitial usando TLS spoofing + fingerprint
-  + comportamento humano + **recovery chain** (detecta captcha → rotaciona proxy/sessão → retry).
-- **auto-captcha** resolve Turnstile via NopeCHA (fila lenta, requer proxy em produção).
-- **captcha-solver (CloakBrowser + 2Captcha/CapSolver):** Turnstile resolvido em ~5s via
-  ClickSolver (free) ou fallback pago.
-
-## reCAPTCHA
-
-- v2/v3/Enterprise: cobertos por hcaptcha-challenger (via proxy), auto-captcha (NopeCHA),
-  2Captcha, CapSolver.
-
-## Capes (tipos suportados por 2Captcha/CapSolver — 30+)
-
-reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile, hCaptcha, FunCaptcha (Arkose), GeeTest,
-KeyCaptcha, Amazon WAF, DataDome, Akamai, Imperva, Friendly, MTCaptcha, Lemin, Cutcaptcha,
-Tencent, Yandex, ALTCHA, Prosopo, entre outros.
-
-## Camadas de defesa que o UKA deve considerar
-
-| Camada | O que ataca | Mitigação no UKA |
-|--------|-------------|------------------|
-| Fingerprint (WebDriver, CDP, headless, GPU) | detecta automação | stealth JS + Brave real/CDP, spoof WebGL/canvas |
-| Comportamental (mouse/keyboard/scroll) | analisa padrões | trajetórias Bézier humanas, typing lognormal |
-| TLS (JA3/JA4) | identifica cliente | TLS regional / proxy residencial sticky |
-| IP reputation | bloqueia faixas | proxies residenciais com sessão sticky |
-| Captcha | desafio final | solver VLM (hcaptcha-challenger) ou token API |
-
-## Aplicação no UKA
-
-- Criar `tests/examples/hcaptcha-test.html` (página de teste local) + usar sites reais fortes
-  (Cloudflare, Google reCAPTCHA demo, hCaptcha demo) no Brave.
-- Pipeline de teste: abrir → detectar captcha → resolver (VLM ou token API) → registrar
-  token/screenshot/log em `tests/output/`.
-- **Não** usar para abuso: foco em automação supervisionada e pesquisa.
-- Dependências relevantes: `playwright`, `puppeteer`, `@xenova/transformers`,
-  `onnxruntime-web`, `tesseract.js`, `cloudinary` (evidências).

package/docs/plans/04.research.sandbox.ai.md

@@ -1,52 +0,0 @@
-# 04 — Pesquisa: Sandbox Virtual e Containers para IA
-
-## Por que sandbox?
-
-Computer-use agents executam código/inputs não confiáveis (saída de LLM, uploads de
-usuário). Rodar em sandbox isola a execução, impede acesso ao sistema de produção e limita
-recursos. A pesquisa mostra que provedores ladearam para **microVMs Firecracker**.
-
-## Vercel Sandbox (opção principal do UKA)
-
-- Compute primitive para rodar código não confiável com segurança (AI agents, code gen).
-- **Firecracker microVM** por sandbox, filesystem e rede próprios, isolamento forte.
-- Runtimes: `node26/24/22`, `python3.13`. Default `node24`.
-- Cada sandbox roda como `vercel-sandbox` (sudo disponível), working dir `/vercel/sandbox`.
-- Startup em **milissegundos**; suporta Docker/FUSE dentro do microVM (privilégio elevado).
-- **Credential brokering:** injeta secrets em requests de saída sem expor dentro do VM
-  (`console.log(process.env)` não vaza a chave).
-- **Network policy:** allowlist de domínios, atualizável em runtime.
-- SDK JS e Python; CLI. Multi-agent isolation (usuário Linux por agente, grupos p/ compartilhar).
-
-### AI SDK Computer Use (vercel-labs) — template de referência
-- Next.js + AI SDK + Claude Sonnet 4.5 + **Vercel Sandbox**.
-- Snapshot pré-construído com: **Xvnc**, **openbox**, **noVNC + websockify**, **Google
-  Chrome**, **xdotool + ImageMagick**.
-- Fluxo: User ↔ Chat UI ↔ AI SDK ↔ Claude → Vercel Sandbox (desktop via noVNC iframe).
-- Ferramentas: `computer` (screenshot/click/type/scroll) + `bash`.
-- Env: `ANTHROPIC_API_KEY`, `SANDBOX_SNAPSHOT_ID`, `VERCEL_OIDC_TOKEN`/`VERCEL_TOKEN`.
-
-### vercel-labs/agent-browser (serverless)
-- CLI Rust nativo; roda agent-browser + Chrome em Vercel Sandbox microVM efêmero.
-- Helper `@agent-browser/sandbox/vercel` + `@vercel/sandbox`.
-
-### vercel-labs/sandcastle (PoC desktop)
-- Desktop Linux web sobre Vercel Sandbox. Stack: Next.js, Tailwind, **Zustand + SWR**,
-  **Neon Postgres + Drizzle ORM**, `@vercel/sandbox`, code-server, Xpra. Auth password/OAuth.
-
-## Outras opções
-
-- **Modal / Baseten / EKS / GKE** (usados pelo mantis) — containers Docker customizados.
-- **Daytona / Cloudflare** — alternativas de sandbox (citadas mas com menos fit p/ TS).
-- **Containers Docker locais** (xdotool + Xvfb + Chromium) para dev sem nuvem.
-
-## Decisão para o UKA
-
-- **Produção:** Vercel Sandbox como camada de execução do computer-use; site de controle
-  deployado em **Vercel** (ou Netlify) (`web/`).
-- **Banco:** criado no deploy (Drizzle/LibSQL ou Prisma em Neon/Turso), conforme `09-esquema-banco-dados.md`.
-- **Armazenamento:** Cloudinary para assets/replays (`10-cloudinary-storage.md`).
-- **Dev local:** Brave real via Playwright/CDP para a plataforma de captura (`05-plataforma-captura-movimentos.md`).
-- **Comunicação:** requests **POST/GET HTTPS** do agente → site deployado → DB + Cloudinary.
-- Dependências: `@vercel/sandbox`, `vercel`, `@netlify/blobs`, `@netlify/functions`,
-  `hono`/`express`, `drizzle-orm`, `@libsql/client`, `socket.io`.

package/docs/plans/05.capture.platform.md

@@ -1,57 +0,0 @@
-# 05 Capture Platform
-
-## Purpose
-
-Build a web platform that captures the user/agent movement inside the browser (focus: brave) and exports everything as json logs to `docs/logs/`. This is the base to train and replay the UKA computer use with human behavior.
-
-## Core concepts
-
-- Virtual mouse / virtual arrow: an svg cursor injected in the page (via cdp init script) that follows the real movement and draws a trail and click ripple.
-- Event capture: click, double click, drag, scroll, coordinates (x,y), rotation (scroll/wheel angle), timing, target (selector/role/text), deterministic seed.
-- Export: compacted json in `docs/logs/<session>.json`.
-
-## Platform architecture (root based, no src)
-
-```
-web/ (capture frontend)
- ├─ index.html              # capture page
- ├─ capture.js              # injects svg cursor + listeners
- ├─ recorder.js             # collects sessionevent to buffer
- └─ exporter.js             # serializes to docs/logs/<session>.json
-
-(root logic files, grouped per skill arch)
- ├─ humancursor.js          # bezier + jitter + overshoot (cdp Input.dispatchMouseEvent)
- ├─ trajectory.js           # path generator (ghost-cursor / humanjs inspired)
- ├─ fingerprint.js          # stealth patches webgl/canvas/audio
- ├─ recorder.js             # json event stream
- ├─ replay.js               # deterministic replay by seed
- └─ runcapture.js           # entrypoint (opens brave via cdp)
-```
-
-## Sessionevent format
-
-```ts
-type SessionEvent =
-  | { t: number; type: "move"; x: number; y: number; tx: number; ty: number }
-  | { t: number; type: "click"; x: number; y: number; button: "left"|"right"; target?: string }
-  | { t: number; type: "drag"; x0: number; y0: number; x1: number; y1: number }
-  | { t: number; type: "scroll"; dx: number; dy: number; angle: number }
-  | { t: number; type: "key"; key: string; target?: string }
-  | { t: number; type: string; [k: string]: unknown };
-```
-
-## How it works (summary)
-
-1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
-2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
-3. Move the cursor humanly (bezier with jitter/overshoot), all via cdp, not locators.
-4. Each action emits a `SessionEvent` with timestamp, coordinates, target, seed.
-5. Compact trajectories (collapse move runs) and export to `docs/logs/`.
-
-## Relation with logs
-
-The final json format of `docs/logs/` files is detailed in `11-movement-logs-json.md`. An example log is at `docs/logs/examplesession.json`.
-
-## Dependencies involved
-
-`playwright`, `puppeteer`, `chromium-bidi`, `bezier-js`, `@napi-rs/canvas`, `d3`, `socket.io-client`, `zod` (event validation).

package/docs/plans/06.dependencies.md

@@ -1,97 +0,0 @@
-# 06 Dependencies
-
-Dependency list of the `@wenathlan/UKA` package, grouped by function. Total: 65 packages (including the dev tooling set). The user asked for "50 to 60, or 60+. Counting 10 more", so this set covers browser automation, ai/vision, sandbox, server, db, storage and validation.
-
-## Browser automation and mouse (8)
-1. `playwright` — real brave/chromium automation via cdp.
-2. `puppeteer` — fallback automation / stealth.
-3. `chromium-bidi` — bidi protocol for input control.
-4. `@playwright/test` — e2e tests for the platform and captcha.
-5. `bezier-js` — human mouse trajectory generation (bezier).
-6. `@napi-rs/canvas` — draw virtual cursor / trail / ripple.
-7. `d3` — movement trajectory visualization.
-8. `sharp` — screenshot/evidence processing.
-
-## Ai / vision / captcha (12)
-9. `ai` — ai sdk core.
-10. `@ai-sdk/anthropic` — claude (computer use).
-11. `@ai-sdk/google` — gemini (vision).
-12. `@ai-sdk/openai` — gpt (vision/reasoning).
-13. `@ai-sdk/react` — agent ui hooks.
-14. `@ai-sdk/vercel` — vercel integration.
-15. `@xenova/transformers` — local vlm models (onnx).
-16. `onnxruntime-web` — onnx inference in browser (yolo/resnet).
-17. `tesseract.js` — ocr for captcha/text.
-18. `openai` — raw sdk for vision/solvers.
-19. `comlink` — workers for inference in a separate thread.
-20. `jsdom` — virtual dom for parsing/tests.
-
-## Sandbox and deploy (3)
-21. `@vercel/sandbox` — firecracker microvm for isolated execution.
-22. `vercel` — cli/deploy to vercel.
-23. `nanoid` — short url-safe ids.
-
-> Note: `@netlify/functions` and `@netlify/blobs` were removed. The architecture skill rejects netlify/vercel functions and platform locked storage. Realtime uses socket. Db uses prisma/drizzle/mysql2.
-
-## Server / api (7)
-24. `hono` — light http api (production).
-25. `express` — alternative api / dev.
-26. `cors` — cors for agent requests.
-27. `helmet` — security headers.
-28. `socket.io` — realtime event streaming (socket).
-29. `socket.io-client` — replay/stream client.
-30. `multer` — file upload (tokens, evidence).
-
-## Database / orm (5)
-31. `drizzle-orm` — primary orm.
-32. `mysql2` — mysql driver (skill arch: data uses mysql2).
-33. `@prisma/client` — prisma client.
-34. `prisma` — cli/migrations.
-35. `yaml` — schema/env config.
-
-## Storage (1)
-36. `cloudinary` — upload replays, screenshots, assets.
-
-## Validation / types (3)
-37. `zod` — event/log schema.
-38. `valibot` — light validation.
-39. `arktype` — runtime types.
-
-## Logging (1)
-40. `pino` — structured (json) agent logs.
-
-## Frontend / build (8)
-41. `react` — platform ui.
-42. `react-dom` — react render.
-43. `next` — production web framework.
-44. `vite` — bundler.
-45. `@vitejs/plugin-react` — react plugin for vite.
-46. `tailwindcss` — styling.
-47. `@tailwindcss/vite` — tailwind+vite integration.
-48. `@testing-library/react` — component tests.
-49. `@testing-library/dom` — dom test utils.
-50. `@testing-library/jest-dom` — test matchers.
-
-## Media / util (4)
-51. `pngjs` — png read/write (click masks).
-52. `ffmpeg-static` — replay video recording.
-53. `@t3-oss/env-core` — typed env validation.
-54. `uuid` — session/agent ids.
-
-## Dev tooling (11 — the "10+")
-55. `typescript` — compiler.
-56. `@biomejs/biome` — lint/format.
-57. `vitest` — test runner.
-58. `@vitest/coverage-v8` — coverage.
-59. `tsx` — run ts without build.
-60. `@types/node` — node types.
-61. `@types/react` — react types.
-62. `@types/react-dom` — react dom types.
-63. `@ai-sdk/anthropic` (dev) — mirrored in devdeps.
-64. `@vercel/sandbox` (dev) — mirrored in devdeps.
-65. `prisma` (dev) — cli in devdeps.
-
-## Conventions
-- Files lowercase. No underscore. No hyphen.
-- English only. Jsdoc comments. Third person voice.
-- No hardcoded host. Use `host`. Ports randomized then locked.

package/docs/plans/07.captcha.test.page.md

@@ -1,41 +0,0 @@
-# 07 Captcha Test Page
-
-## Goal
-
-Have a controlled target to validate the UKA computer use against strong captchas. Open it in brave (via the capture platform) and record the result.
-
-## Target options
-
-### A. Local page (`tests/examples/hcaptchatest.html`) — recommended to start
-- Static html with the hcaptcha widget using the public test sitekey.
-- Buttons to trigger the challenge, show the resolved token and status.
-- Validates detection + solver + log without heavy external network.
-
-### B. Real strong sites — advanced tests
-- hcaptcha demo: `https://accounts.hcaptcha.com/demo`
-- cloudflare turnstile: `https://challenges.cloudflare.com/turnstile`
-- google recaptcha: `https://www.google.com/recaptcha/api2/demo`
-
-## Test pipeline (script in `tests/scripts/`)
-
-1. `launchbrave()` — opens real brave via playwright/cdp.
-2. `navigate(url)` — goes to the test page.
-3. `detectcaptcha(page)` — scans dom/frames for hcaptcha / turnstile / recaptcha.
-4. `solve(page)` — uses vlm solver (hcaptcha challenger) or token api (nopecha/2captcha).
-5. `record(page)` — saves screenshot, token and movement log to `tests/output/`.
-6. `assert(passed)` — verifies the challenge was passed.
-
-## Evidence in `tests/output/`
-- `hcaptcha-<ts>.json` — token + metadata.
-- `hcaptcha-<ts>.png` — screenshot of challenge and post-solve.
-- `hcaptcha-<ts>-trace.json` — movement log (replay).
-- `hcaptcha-<ts>.mp4` — replay video (via `ffmpeg-static`).
-
-## Success criteria
-- Auto detects captcha type.
-- Solves hcaptcha (checkbox) with vlm/llm.
-- Passes cloudflare turnstile in at least 1 of 3 attempts (with sticky proxy).
-- Generates reproducible json log (seed).
-
-## Ethical note
-For research and supervised automation only. Respect tos and rate limits.

package/docs/plans/08.production.infra.md

@@ -1,70 +0,0 @@
-# 08 Production Infra
-
-## Goal
-
-The `web/` folder is the production site. It is deployed to vercel or netlify and works as the sandbox backend: it receives agent data via https requests (post/get), writes to the db and saves assets to cloudinary.
-
-## Why deploy (user decision)
-- The database is created in the deploy (vercel/netlify + turso/mysql), not local.
-- The agent/sandbox talks to the site via https, no own infra needed.
-- Cloudinary holds heavy data (replay videos, screenshots, big logs).
-
-## Structure of `web/` (root based, no src)
-
-```
-web/
-├── index.js               # entrypoint (open node server, not platform functions)
-├── server.js              # api routes (hono or express)
-├── capture.js             # browser movement capture (virtual mouse, arrow)
-├── recorder.js            # json event stream
-├── replay.js              # deterministic replay by seed
-├── humancursor.js         # bezier + jitter + overshoot (cdp)
-├── trajectory.js          # path generator
-├── fingerprint.js         # stealth patches
-├── db.js                  # drizzle + mysql2 + prisma loader
-├── storage.js             # cloudinary upload
-├── auth.js                # api key / oidc (VERCEL_OIDC_TOKEN)
-├── vercel.json            # vercel build/deploy config
-├── netlify.toml           # netlify deploy config (alt)
-├── drizzle.config.js      # drizzle -> mysql2
-├── schema.prisma          # prisma schema (alt/sync)
-├── index.html             # capture ui
-└── hcaptchatest.html      # captcha test page (mirror of tests/examples)
-```
-
-## Backend rules (skill arch)
-- No vercel functions. No netlify functions. Use an open node server (hono/express).
-- Realtime uses socket (`socket.io`), not platform locked pub/sub.
-- Db uses prisma schema, drizzle orm, mysql2 driver.
-- No localhost. Host parametrized (`host`). Ports randomized then locked.
-- Files lowercase. No underscore. No hyphen.
-
-## Agent requests to deployed site
-
-```
-agent (sandbox)                         deployed site (web/)
-─────────────────                        ──────────────────────
-post /sessions            ───────────►  create session in db
-post /sessions/:id/events ───────────►  append json log (drizzle/mysql2)
-post /captcha/result      ───────────►  save evidence + cloudinary
-get  /sessions/:id        ───────────►  read session + replay url
-get  /sessions/:id/replay ───────────►  return video (cloudinary)
-```
-
-## Environment variables (production)
-- `DATABASE_URL` (mysql2 / turso).
-- `CLOUDINARY_URL` / `CLOUDINARY_CLOUD_NAME` / `CLOUDINARY_API_KEY` / `CLOUDINARY_API_SECRET`.
-- `UKA_API_KEY` (agent auth).
-- `VERCEL_OIDC_TOKEN` (auto on vercel) or `VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID`.
-- `HOST` and `PORT` (parametrized, randomized then locked).
-
-## Deploy
-- Vercel: `vercel --prod`.
-- Netlify: `netlify deploy --prod` (static + open server build, not netlify functions).
-- The db is provisioned in the deploy (turso/mysql), not local sqlite.
-
-## Database (decision)
-- Drizzle orm primary + mysql2 driver.
-- Prisma schema present as alt/sync.
-- Schema detailed in `09-database-schema.md`.
-- Cloudinary detailed in `10-cloudinary-storage.md`.

package/docs/plans/09.database.schema.md

@@ -1,121 +0,0 @@
-# 09 Database Schema
-
-## Decision
-- Primary orm: drizzle orm.
-- Driver: `mysql2` (skill arch: data uses mysql2). Turso/libsql is an accepted alternative.
-- Prisma schema included as alt/sync (`schema.prisma`).
-- The db is created in the deploy (mysql/turso), not local.
-
-## Tables (drizzle, root file `web/db.js` or `schema.js`)
-
-```js
-import { sql } from "drizzle-orm";
-import { mysqlTable, text, int, float, boolean, index, timestamp } from "drizzle-orm/mysql-core";
-
-// session of computer use (one agent / one execution)
-export const sessions = mysqlTable("sessions", {
-  id: text("id").primaryKey(),
-  agentName: text("agent_name"),
-  browser: text("browser").default("brave"),
-  originUrl: text("origin_url"),
-  status: text("status").default("running"),
-  seed: text("seed"),
-  createdAt: timestamp("created_at").defaultNow(),
-  finishedAt: timestamp("finished_at"),
-}, (t) => [index("idx_sessions_status").on(t.status)]);
-
-// captured movement events (virtual mouse, click, scroll, etc)
-export const events = mysqlTable("events", {
-  id: int("id").autoincrement().primaryKey(),
-  sessionId: text("session_id").references(() => sessions.id, { onDelete: "cascade" }),
-  t: float("t"),
-  type: text("type"),
-  x: float("x"),
-  y: float("y"),
-  data: text("data"),
-  createdAt: timestamp("created_at").defaultNow(),
-}, (t) => [index("idx_events_session").on(t.sessionId)]);
-
-// captcha results (tests)
-export const captchaResults = mysqlTable("captcha_results", {
-  id: int("id").autoincrement().primaryKey(),
-  sessionId: text("session_id").references(() => sessions.id, { onDelete: "cascade" }),
-  kind: text("kind"),
-  sitekey: text("sitekey"),
-  token: text("token"),
-  passed: boolean("passed").default(false),
-  solver: text("solver"),
-  evidenceUrl: text("evidence_url"),
-  createdAt: timestamp("created_at").defaultNow(),
-});
-
-// heavy assets (replay videos, screenshots) — pointer to cloudinary
-export const assets = mysqlTable("assets", {
-  id: int("id").autoincrement().primaryKey(),
-  sessionId: text("session_id").references(() => sessions.id, { onDelete: "cascade" }),
-  kind: text("kind"),
-  cloudinaryId: text("cloudinary_id"),
-  url: text("url"),
-  bytes: int("bytes"),
-  createdAt: timestamp("created_at").defaultNow(),
-});
-```
-
-## Prisma (`schema.prisma`) — equivalent
-
-```prisma
-model Session {
-  id         String   @id
-  agentName  String?
-  browser    String   @default("brave")
-  originUrl  String?
-  status     String   @default("running")
-  seed       String?
-  createdAt  DateTime @default(now())
-  finishedAt DateTime?
-  events        Event[]
-  captchaResults CaptchaResult[]
-  assets        Asset[]
-}
-
-model Event {
-  id        Int     @id @default(autoincrement())
-  session   Session @relation(fields: [sessionId], references: [id], onDelete: Cascade)
-  sessionId String
-  t         Float
-  type      String
-  x         Float?
-  y         Float?
-  data      String?
-  createdAt DateTime @default(now())
-}
-
-model CaptchaResult {
-  id         Int     @id @default(autoincrement())
-  session    Session @relation(fields: [sessionId], references: [id], onDelete: Cascade)
-  sessionId  String
-  kind       String
-  sitekey    String?
-  token      String?
-  passed     Boolean @default(false)
-  solver     String?
-  evidenceUrl String?
-  createdAt  DateTime @default(now())
-}
-
-model Asset {
-  id           Int     @id @default(autoincrement())
-  session      Session @relation(fields: [sessionId], references: [id], onDelete: Cascade)
-  sessionId    String
-  kind         String
-  cloudinaryId String
-  url          String
-  bytes        Int
-  createdAt    DateTime @default(now())
-}
-```
-
-## Migrations
-- Drizzle: `drizzle-kit generate` + `drizzle-kit migrate` (mysql) in the deploy.
-- Prisma: `prisma migrate deploy` (mysql) as alt.
-- The db is created in the deploy pipeline (vercel/netlify), not local sqlite.

package/docs/plans/10.cloudinary.storage.md

@@ -1,57 +0,0 @@
-# 10 Cloudinary Storage
-
-## Why cloudinary
-The production site (`web/`) receives agent data via https. Heavy data (replay videos, screenshots, big json logs) is sent to cloudinary instead of the db, keeping the db light (only pointers/urls).
-
-## What goes to cloudinary
-- Replay videos (`.mp4`/`.webm`) generated via `ffmpeg-static` from logs.
-- Captcha challenge screenshots (before/after).
-- Big json logs (long trajectories) as a complementary asset.
-- Training assets (click masks, challenge images).
-
-## Flow
-
-```
-agent/sandbox ──post /captcha/result──► backend (web/)
-                                          │
-                                          ├─ write metadata to db (drizzle/mysql2)
-                                          └─ upload file ──► cloudinary
-                                                 │
-                                                 └─ save asset { url, cloudinaryId } in db
-```
-
-## Config (`web/storage.js`)
-
-```js
-import { v2 as cloudinary } from "cloudinary";
-
-cloudinary.config({
-  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
-  api_key: process.env.CLOUDINARY_API_KEY,
-  api_secret: process.env.CLOUDINARY_API_SECRET,
-});
-
-/**
- * Uploads a local file to cloudinary under uka/<folder>.
- * @param {string} filePath local path
- * @param {string} folder sub folder
- * @returns {Promise<object>} upload result with url and public id
- */
-export async function uploadAsset(filePath, folder) {
-  return cloudinary.uploader.upload(filePath, {
-    resource_type: "auto",
-    folder: `uka/${folder}`,
-  });
-}
-```
-
-## Variables
-- `CLOUDINARY_CLOUD_NAME`
-- `CLOUDINARY_API_KEY`
-- `CLOUDINARY_API_SECRET`
-- `CLOUDINARY_URL` (condensed form, optional)
-
-## Good practices
-- Use `folder: "uka/<sessionId>"` for organization.
-- Save only the `url` + `cloudinaryId` in the db (see `09-database-schema.md`, `assets` table).
-- Compress videos before upload to respect plan limits.