@wenathlan/saddle 1.8.17 → 1.8.18

package/docs/todo-1.8.16.md

@@ -677,4 +677,59 @@
 - [x] Update every active 1.8.16 version metadata location to 1.8.17 after the implementation scope is validated.
 - [x] Update release notes, changelog, registry and artifact documentation with an accurate platform matrix and no unverified image claims.
 - [x] Validate YAML formatting, package and engine gates, workflow logic, package dry-run, high-severity audit, flat-native validation, and whitespace before creating the 1.8.17 tag.
-- [ ] Publish and inspect the 1.8.17 release, all registry workflows, container manifest platforms, post-push label checks, and smoke-test results.
+- [x] Publish and inspect the 1.8.17 release, all registry workflows, container manifest platforms, post-push label checks, and smoke-test results. The public release contains 38 assets; GHCR run `31847952976` verified `linux/amd64`, `linux/arm64`, and `linux/ppc64le` and completed the amd64 label and CLI smoke checks.
+
+## 11. Version 1.8.17 README consolidation and archival request
+
+- [x] Inventory every historical `README.md` revision with Git before selecting durable content for the current README. The root history contains 41 revisions and separate platform README paths.
+- [x] Consolidate still-relevant capabilities, installation paths, modes, packaging surfaces, and limits into an external consolidation record while preserving the README scope reference.
+- [x] Update active release references to `1.8.17` while preserving historical release records as history rather than overwriting them.
+- [ ] Remove direct links or filename references to documents inside `docs/` from the README; retain only appropriate root-document references.
+- [x] Inventory the exact user-requested documentation range before any archive operation and exclude the archive itself from recursive inputs.
+- [x] Receive a user-supplied passphrase before creating an encrypted archive; do not generate an unrecoverable undocumented credential.
+- [x] Create and verify the requested encrypted archive only after the passphrase and archive scope are explicit. The verified list contains 199 files and 13 directory entries with unrelated assets excluded.
+- [x] Preserve the current README as a non-deterministic scope reference; record the historical consolidation and active 1.8.17 reference matrix outside that file.
+- [x] Build the encrypted package from `docs/logs`, `docs/plans`, `docs/sources`, and `docs/talks1` through `docs/talks9`, excluding unrelated `docs/assets` content and the generated archive itself.
+
+## 12. Encrypted documentation relocation
+
+- [x] Move the verified encrypted package from the repository root into `docs/` without changing its bytes.
+- [x] Remove only `docs/logs`, `docs/plans`, `docs/sources`, and `docs/talks1` through `docs/talks9` after the package is present at its destination.
+- [x] Verify that `docs/assets` and all remaining top-level documentation files survive the removal before committing.
+
+## 13. README version-reference audit
+
+- [x] Enumerate every version reference in the current README and every historical root README revision with Git. The root history contains 41 revisions and the current README retains 1.8.14 scope statements.
+- [x] Distinguish active metadata from immutable historical release evidence and identify stale version statements.
+- [x] Preserve the current README as a scope reference while recording the complete capability consolidation outside it.
+- [x] Ensure the external consolidation uses the active 1.8.17 matrix and does not contain direct links to materials inside `docs/`.
+- [x] Validate and commit the version-reference audit without rewriting the README scope document.
+
+## 14. Whole-repository active-version audit
+
+- [x] Enumerate every tracked current-file reference to a pre-1.8.17 version and classify it as active metadata, test fixture, changelog, release evidence, research, or scope text.
+- [x] Inspect every historical root README revision for durable behavior not yet represented in the external consolidation.
+- [x] Update any discovered active metadata to 1.8.17 while preserving tests, historical records, and scope references. No old Saddle product metadata remained; the Android build-variable match is an AndroidX dependency.
+- [x] Expand the external consolidation with the complete classification and durable historical behavior, without direct links to internal materials.
+- [x] Validate and commit the whole-repository version audit without reworking the README scope document. The only excluded non-product token is an AndroidX dependency version.
+
+## 15. Direct README re-evaluation request
+
+- [ ] Inventory the README's release badge, current-scope statements, historical sections, and direct internal references.
+- [ ] Compare every affected section with all historical root README revisions before deciding whether it can represent 1.8.17 truthfully.
+- [ ] Identify the exact set of active release references that could be updated without rewriting the preserved scope document or corrupting historical evidence.
+- [ ] Validate and record the direct README re-evaluation outcome.
+
+## 16. npm distribution and 1.8.18 planning base
+
+- [x] Inspect the package dry-run contents to confirm which README the npm package distributes and whether a separate distribution document exists. The package contains the root README and the extension README; no separate distribution README exists.
+- [x] Map each durable capability from the 41 historical README revisions into the consolidated planning base for 1.8.18.
+- [x] Record any permitted active metadata alignment separately from the immutable README scope reference.
+- [x] Validate and commit the 1.8.18 planning base without replacing the README scope document.
+
+## 17. README publication consolidation request
+
+- [x] Build a section-by-section matrix across the 41 root README revisions and the current README.
+- [x] Identify all release references that describe the active package rather than historical evidence or fixture state.
+- [x] Consolidate the README into foundation, engine, productization, API, extension, security, package, development, CLI, repository, history and current-scope sections while preserving historical evidence accurately.
+- [x] Validate the README-facing update through `npm pack --dry-run`; the resulting `@wenathlan/saddle@1.8.17` package contains the root README.

package/docs/todo-1.8.18.md

@@ -0,0 +1,152 @@
+# Saddle 1.8.18 — isolated execution and binary-processing plan
+
+> This plan contains **920 individual actions**. It uses 92 unchecked work packages, each with ten ordered actions: **inspect, extract, classify, design, implement, test, boundary-test, review, document, and record**. The ten actions apply to the exact subject named by each work package; a package may be marked complete only after all ten actions have evidence.
+
+## Completion guardrails
+
+| Rule | Requirement |
+| --- | --- |
+| Truthfulness | A contract may describe, plan, validate, or invoke isolation. It must not claim to provide a VPS, micro-VM, browser isolation, persistent database, GPU, signing, or a remote service unless the caller supplies and verifies the corresponding adapter. |
+| Isolation | Untrusted bytes are never executed by the transport-neutral root. Execution requires a caller-owned isolated-runner adapter and an explicit policy. |
+| Storage | Remote storage is durable state, not literal RAM or VRAM. Materialization remains bounded, measurable, and caller-owned. |
+| Effects | Network, browser, container, filesystem, database, credentials, dispatch, retention, and deletion remain explicit privileged effects. |
+| Compatibility | New contracts are additive, TypeScript-first, dependency-free, serializable, root-first, and use deterministic tests. |
+| Publishing | Release work begins only after all gates pass and every version-bearing manifest agrees on `1.8.18`. |
+
+## 1. Scope source audit — actions 001–100
+
+- [ ] **001–010.** Read README source lines 001–200; extract architecture, mode, and naming requirements.
+- [ ] **011–020.** Read README source lines 201–400; extract execution, binary, and isolation requirements.
+- [ ] **021–030.** Read README source lines 401–600; extract storage, memory, and provider assertions.
+- [ ] **031–040.** Read README source lines 601–800; extract runner, workflow, and deployment assertions.
+- [ ] **041–050.** Read README source lines 801–1000; extract agent, browser, scrape, and bot assertions.
+- [ ] **051–060.** Read README source lines 1001–1200; extract protocol, database, and API assertions.
+- [ ] **061–070.** Read README source lines 1201–1400; extract package, native, and extension assertions.
+- [ ] **071–080.** Read README source lines 1401–1600; extract web, playground, and UI assertions.
+- [ ] **081–090.** Read README source lines 1601–1848; extract release, quality, and governance assertions.
+- [ ] **091–100.** Compare the extracted source claims with current 1.8.17 code, tests, manifests, and shipped artifacts.
+
+## 2. Feasibility, terminology, and capability evidence — actions 101–200
+
+- [ ] **101–110.** Classify every source claim as shipped, adapter-ready, research-only, deferred, infeasible, or policy-rejected.
+- [ ] **111–120.** Define precise vocabulary for process plan, isolated execution, sandbox adapter, container adapter, micro-VM adapter, and remote runner.
+- [ ] **121–130.** Define precise vocabulary for durable storage, working set, cache, mmap, tmpfs, memory pressure, and materialization.
+- [ ] **131–140.** Define precise vocabulary for binary inspection, binary transform, binary execution, binary artifact, and binary provenance.
+- [ ] **141–150.** Define precise vocabulary for browser transport, browser session, browser isolation, browser action, and browser evidence.
+- [ ] **151–160.** Define precise vocabulary for edge processing, third-party runner, provider chain, job lease, and artifact boundary.
+- [ ] **161–170.** Define a claim-evidence schema that distinguishes declared capability from verified capability and observed result.
+- [ ] **171–180.** Define a capability receipt schema for platform, architecture, isolation mechanism, limits, and adapter identity.
+- [ ] **181–190.** Define a policy vocabulary for allowed, denied, approval-required, unknown, expired, and unsupported execution requests.
+- [ ] **191–200.** Document the non-goals: no false VPS, no hidden credentials, no arbitrary code execution in the root, and no quota evasion.
+
+## 3. Execution-policy contracts — actions 201–300
+
+- [ ] **201–210.** Design the serializable execution-request contract with input reference, target, policy, and artifact destination.
+- [ ] **211–220.** Design the serializable execution-policy contract with network, filesystem, process, time, memory, and output limits.
+- [ ] **221–230.** Design the serializable execution-plan contract that separates planning from privileged execution.
+- [ ] **231–240.** Design the serializable execution-receipt contract for adapter identity, limits, timings, exit classification, and artifacts.
+- [ ] **241–250.** Design the serializable execution-evidence contract for hashes, logs, retention intent, and verification state.
+- [ ] **251–260.** Design the isolated-runner adapter interface without importing Docker, Firecracker, Playwright, or provider SDKs in the root.
+- [ ] **261–270.** Design the cancellation and unknown-remote-state contract with no false rollback claims.
+- [ ] **271–280.** Design the admission-control contract for queue budget, concurrency budget, working-set budget, and execution quota.
+- [ ] **281–290.** Design the explicit approval token and consent correlation contract for privileged execution requests.
+- [ ] **291–300.** Design deterministic fixture shapes for accepted, denied, expired, unsupported, cancelled, and unknown execution states.
+
+## 4. Binary inspection and transformation contracts — actions 301–400
+
+- [ ] **301–310.** Define a binary-source contract for inline bytes, durable artifact references, and caller-owned streams.
+- [ ] **311–320.** Define bounded binary metadata inspection based on magic bytes, size, digest, and declared media type.
+- [ ] **321–330.** Define binary classification results for archive, executable, document, image, model, unknown, and malformed input.
+- [ ] **331–340.** Define the binary-transform plan contract with deterministic input, options, cache identity, and output expectations.
+- [ ] **341–350.** Define the transform adapter interface for caller-owned WASM, native, container, or remote execution paths.
+- [ ] **351–360.** Define archive-inspection contracts that list entries and limits without extracting untrusted content.
+- [ ] **361–370.** Define archive-extraction plans that require a caller-owned extraction adapter and explicit path controls.
+- [ ] **371–380.** Define binary-output verification for digest, byte count, media type, expected structure, and provenance.
+- [ ] **381–390.** Define binary-processing failure taxonomy for malformed, oversized, unsupported, denied, timeout, and verification failure.
+- [ ] **391–400.** Define deterministic binary fixtures and fuzz boundaries without storing unsafe executable payloads in the repository.
+
+## 5. Working-set, storage, and materialization contracts — actions 401–500
+
+- [ ] **401–410.** Define working-set admission estimates for byte size, range support, locality, and required transforms.
+- [ ] **411–420.** Define bounded range materialization plans for local, remote, chunked, and content-addressed storage adapters.
+- [ ] **421–430.** Define cache identity, cache freshness, cache evidence, and caller-owned eviction plans.
+- [ ] **431–440.** Define temporary materialization lifecycle states from planned through verified cleanup intent.
+- [ ] **441–450.** Define storage capability receipts for range reads, writes, integrity checks, regions, and retention constraints.
+- [ ] **451–460.** Define integrity verification for chunks, manifests, content addresses, and reconstructed binary artifacts.
+- [ ] **461–470.** Define storage-pool policy for primary, mirror, fan-out, quorum, repair planning, and no-background-retry limits.
+- [ ] **471–480.** Define memory-pressure decisions that remain declarative and never claim local or remote RAM ownership.
+- [ ] **481–490.** Define storage-to-execution handoff records with bytes, hash, policy identity, and recipient adapter identity.
+- [ ] **491–500.** Define deterministic tests for working-set budgets, range support, corrupt members, and cleanup-plan generation.
+
+## 6. Runner, provider-chain, and remote-isolation adapters — actions 501–600
+
+- [ ] **501–510.** Define runner capability declarations for process, container, micro-VM, browser, network, and hardware attributes.
+- [ ] **511–520.** Define runner eligibility evaluation with explicit requirements and no provider-specific implicit fallback.
+- [ ] **521–530.** Define deterministic provider-chain selection from declared capabilities, policy, preference, and evidence.
+- [ ] **531–540.** Define runner dispatch plans that remain effect-free until a caller-provided adapter executes them.
+- [ ] **541–550.** Define GitHub Actions runner adapter requirements without treating an ephemeral workflow as a permanent VPS.
+- [ ] **551–560.** Define Forgejo, Gitea, GitLab, Codeberg, and Woodpecker adapter requirements without embedding tokens or endpoints.
+- [ ] **561–570.** Define container-runner adapter requirements for image identity, read-only input, bounded mounts, resource limits, and receipt evidence.
+- [ ] **571–580.** Define micro-VM adapter requirements for kernel/image provenance, CPU/memory limits, network policy, and lifecycle receipt.
+- [ ] **581–590.** Define remote cancellation, observation, and handoff semantics when provider state is delayed, unknown, or unavailable.
+- [ ] **591–600.** Define deterministic fake-runner tests proving planning, policy denial, adapter selection, and receipt validation without remote execution.
+
+## 7. Agent browser, scrape, and MCP capability contracts — actions 601–700
+
+- [ ] **601–610.** Define browser-session capability receipts for transport, isolation claim, headless state, and permitted actions.
+- [ ] **611–620.** Define browser-action request and evidence contracts for navigation, click, type, capture, and download planning.
+- [ ] **621–630.** Define browser isolation requirements that require a caller-owned transport and cannot be inferred from a UI label.
+- [ ] **631–640.** Define snapshot, frame, tab, and context-budget handoffs between browser adapters and agent logic.
+- [ ] **641–650.** Define scrape-request consent, robots, freshness, cache, provenance, and bounded-output policy contracts.
+- [ ] **651–660.** Define crawler frontier, domain budget, retry, queue, and cancellation contracts with explicit persistence ownership.
+- [ ] **661–670.** Define proxy and captcha boundaries as caller-owned evidence or adapters, never bundled bypass behavior.
+- [ ] **671–680.** Define MCP tool declarations for execution planning, binary inspection, capability evaluation, and artifact evidence.
+- [ ] **681–690.** Define SaddleBot task boundaries for explicit operator commands, message provenance, and no autonomous credential handling.
+- [ ] **691–700.** Define deterministic tests for browser evidence, scraper freshness, crawl budgets, MCP serialization, and bot policy rejection.
+
+## 8. Persistence, database, protocol, and observability contracts — actions 701–800
+
+- [ ] **701–710.** Define persistence interfaces for execution plans, receipts, evidence, artifacts, approvals, and resumable tasks.
+- [ ] **711–720.** Evaluate Drizzle ORM only as an optional caller-owned persistence adapter, not as a root dependency or required database.
+- [ ] **721–730.** Define relational schema projections for jobs, artifacts, leases, receipts, evidence, approvals, and retention decisions.
+- [ ] **731–740.** Define migration ownership, database credentials, tenancy, and backup policy as application-layer responsibilities.
+- [ ] **741–750.** Define JSON, NDJSON, SSE, block, and MCP representations for execution states and binary-processing progress.
+- [ ] **751–760.** Define event correlation identifiers across job, runner, artifact, approval, browser, and delivery boundaries.
+- [ ] **761–770.** Define redaction controls for logs, metadata, URLs, headers, secrets, and binary-derived strings.
+- [ ] **771–780.** Define health, heartbeat, queue depth, working-set pressure, and adapter freshness observations without false availability claims.
+- [ ] **781–790.** Define audit trail integrity for plan-to-receipt transitions, evidence references, and operator-visible denial reasons.
+- [ ] **791–800.** Define deterministic persistence-adapter tests using in-memory fakes and no mandatory database server.
+
+## 9. Unified `web/` playground — actions 801–900
+
+- [ ] **801–810.** Audit the existing root-first `web/` site, routes, assets, build script, and deployment-neutral base-path behavior.
+- [ ] **811–820.** Define the playground information architecture for capability planning, binary inspection, execution policy, receipt viewing, and integration guidance.
+- [ ] **821–830.** Define a browser-only demonstration model that uses local fixtures and does not execute uploaded or remote binaries.
+- [ ] **831–840.** Define a playground execution-plan form with explicit policy fields, bounded input options, and denial explanations.
+- [ ] **841–850.** Define a playground binary-inspection form limited to metadata and caller-selected safe sample fixtures.
+- [ ] **851–860.** Define a playground storage-to-working-set visualization that explains stages and limits without claiming RAM conversion.
+- [ ] **861–870.** Define a playground runner-selection view that compares declared capabilities and leaves dispatch disabled without an adapter.
+- [ ] **871–880.** Define a playground browser and scrape view that displays evidence boundaries, consent needs, and caller-owned transport requirements.
+- [ ] **881–890.** Define a playground integration view for library import, adapters, database option, container option, and hosted-operation prerequisites.
+- [ ] **891–900.** Define responsive, accessible, deterministic UI tests and static build verification for every new playground state.
+
+## 10. Security, quality, packaging, and 1.8.18 release — actions 901–920
+
+- [ ] **901–910.** Perform the 1.8.18 threat-model review for untrusted bytes, remote dispatch, archive handling, secrets, browser actions, SSRF, and provider boundaries.
+- [ ] **911–920.** Run final source, test, package, native, documentation, version, artifact, release-note, and registry-readiness gates before creating any 1.8.18 tag.
+
+## 11. Unified internal API architecture — actions 921–970
+
+- [x] **921–930.** Define internal API boundaries for gateway, planner, materializer, executor, persistence, and receipt projection within the single `web/` surface.
+- [x] **931–940.** Define a hard default policy that rejects user-hardware access, local execution, remote dispatch, paid providers, and free-tier providers until the caller explicitly supplies an adapter and approval.
+- [x] **941–950.** Define in-memory demonstration adapters for the six internal API boundaries that are deterministic, do not call the network, and do not execute supplied bytes.
+- [x] **951–960.** Define browser-facing internal API request and response envelopes for plan creation, policy evaluation, binary metadata inspection, and receipt projection.
+- [x] **961–970.** Define test cases proving that a missing adapter, unapproved provider, remote URL, local hardware target, or binary execution request yields a structured denial without side effects.
+
+## 12. Final version alignment and commit — actions 971–980
+
+- [x] **971–980.** Align active npm, lockfile, Maven, NuGet, RubyGems, extension, desktop, Capacitor, crawler and iOS metadata to `1.8.18`; create the candidate release note, run the release gates, inspect the npm package, configure `iakadion` authorship, commit, and push the verified source revision.
+
+## Evidence ledger
+
+Every completed ten-action work package must link its evidence to the final release record: source revision or research URL, design note, code path, deterministic test name, boundary test, documentation update, validation command, result, reviewer state, and disposition. The 970 actions deliberately start with factual classification; implementation may proceed only for capabilities that are both technically feasible and expressible without false infrastructure claims.

package/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Saddle browser bridge",
-  "version": "1.8.17",
+  "version": "1.8.18",
   "description": "User initiated page snapshots through the Saddle browser contract.",
   "minimum_chrome_version": "110",
   "permissions": ["activeTab", "scripting", "storage"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenathlan/saddle",
-  "version": "1.8.17",
+  "version": "1.8.18",
   "description": "binary computing engine that turns distributed storage into a publishable working set",
   "type": "module",
   "private": false,
@@ -83,7 +83,8 @@
     "./surface-requirements": "./dist/surfaces/requirements.js",
     "./worker": "./dist/runtime/worker.js",
     "./binary-archive": "./dist/binary/archive.js",
-    "./binary-transform": "./dist/binary/transform.js"
+    "./binary-transform": "./dist/binary/transform.js",
+    "./isolation": "./dist/isolation/contracts.js"
   },
   "files": [
     "dist",

package/docs/plans/00.index.md

@@ -1,50 +0,0 @@
-# Index
-
-Project: **UKA** — computer use agent, sandbox for AI and captcha bypass. Super bot with computational memory. Package `@wenathlan/saddle`. Domain acquired.
-
-Theme: computer use, bypasses, captcha, sandbox for AI, container for AI, multi-platform bot, storage-to-compute memory transformation.
-
-## Planning Documents (`docs/plans`)
-
-| # | File | Subject |
-|---|------|---------|
-| 01 | [architecture.md](./01.architecture.md) | General system architecture |
-| 02 | [research.computer.use.md](./02.research.computer.use.md) | Research: computer use agents 2026 |
-| 03 | [research.captcha.bypass.md](./03.research.captcha.bypass.md) | Research: hcaptcha cloudflare recaptcha bypass |
-| 04 | [research.sandbox.ai.md](./04.research.sandbox.ai.md) | Research: virtual sandbox and containers for AI |
-| 05 | [capture.platform.md](./05.capture.platform.md) | Browser movement capture platform |
-| 06 | [dependencies.md](./06.dependencies.md) | 60+ project dependencies |
-| 07 | [captcha.test.page.md](./07.captcha.test.page.md) | Test page with hcaptcha cloudflare |
-| 08 | [production.infra.md](./08.production.infra.md) | Production infra (vercel/netlify) and sandbox backend |
-| 09 | [database.schema.md](./09.database.schema.md) | Database schema (drizzle/prisma/mysql2) |
-| 10 | [cloudinary.storage.md](./10.cloudinary.storage.md) | Data storage on cloudinary |
-| 11 | [movement.logs.json.md](./11.movement.logs.json.md) | JSON movement log format (brave) |
-| 12 | [research.atlas.agent.browser.md](./12.research.atlas.agent.browser.md) | Atlas: agent browser repos with same classification |
-| 28 | [action.plan.md](./28.action.plan.md) | Action plan and next steps |
-
-## Super Bot Documentation (`docs/plans`)
-
-| # | File | Subject |
-|---|------|---------|
-| 45 | [robotarchitecture.md](./45.robotarchitecture.md) | Super bot architecture overview |
-| 37 | [deploystrategy.md](./37.deploystrategy.md) | Deploy strategies (Netlify, Vercel, CI/CD, Docker, VM) |
-| 36 | [computational.memory.md](./36.computational.memory.md) | Storage-to-compute memory transformation system |
-| 39 | [multi.platform.bot.md](./39.multi.platform.bot.md) | Multi-platform bot (GitHub, GitLab, Forgejo, Gitea, Discord) |
-| 40 | [npm.publish.md](./40.npm.publish.md) | NPM package publishing (`@wenathlan/saddle`) |
-| 46 | [scdnintegration.md](./46.scdnintegration.md) | SCDN integration for assets and deployment |
-| 44 | [reference.md](./44.reference.md) | Reference index for all saddle documentation |
-| 33 | [bots.codigo.revisao.md](./33.bots.codigo.revisao.md) | Best AI code review bots (research) |
-| 32 | [bots.automacao.computacional.md](./32.bots.automacao.computacional.md) | Best computational automation bots (research) |
-| 34 | [bots.seguranca.cicd.md](./34.bots.seguranca.cicd.md) | Bot research (security + CI/CD) |
-
-## Folders
-
-- `docs/plans/` — planning and research (this index)
-- `docs/talks/` — decision transcripts
-- `docs/logs/` — JSON movement logs from Brave (`examplesession.json`)
-- `tests/` — unit tests (`examples/`, `output/`, `scripts/`)
-- `web/` — production site, deployed to Vercel or Netlify (files at root, no `src/`)
-
-## Phase Decision
-
-We are in **planning + research**. Platform implementation starts **only after user approval** (see `28.action.plan.md`).

package/docs/plans/01.architecture.md

@@ -1,86 +0,0 @@
-# 01 Architecture
-
-## Goal
-
-Build **UKA**, a computer use agent for ai that:
-
-1. Captures human movement in the browser (virtual mouse, virtual arrow, click, rotation, coordinates) in a real environment (brave / chromium).
-2. Exports movement as json logs to `docs/logs/`.
-3. Runs in a virtual sandbox to isolate ai agent execution.
-4. Faces strong captchas (hcaptcha, cloudflare turnstile, recaptcha) in controlled tests, opening test pages in brave.
-5. Persists data in production via a deployed site (vercel/netlify) plus db (drizzle/prisma/mysql2) plus cloudinary.
-
-## Architecture rules (skill arch)
-
-- No `src/` folder. Logic lives at the root of `web/`.
-- No vercel functions. No netlify functions. Use prisma, drizzle, mysql2, socket.
-- No localhost. Host is parametrized (`host`). Ports randomized then locked.
-- Files lowercase. No underscore. No hyphen. English docs. Jsdoc comments.
-- Logic grouped. Up to 20 related logics per file.
-- Runs as a library across modes (computer, browser, cli, binary, headless, etc).
-
-## Atlas (the browser)
-
-Atlas is the real browser component of UKA. It works across the 30 modes from the
-architecture skill (computer, browser, cli, binary, headless, etc) and its primary
-job is to bypass hcaptcha so the agent can act. It serves both the agent and the
-sandbox, and talks to our own database on vercel/netlify. See
-[12 research atlas agent browser](./12-research-atlas-agent-browser.md) for the
-prior-art survey and the p1 stealth / p2 vlm / p3 token fallback layering.
-
-## Components
-
-```
-atlas (web/atlas.js + deps)
-  - real browser across 30 modes
-  - stealth layer + hcaptcha bypass (vlm or token api fallback)
-  - feeds agent and sandbox
-
-capture ui (web/*.html + web/capture.js)
-  - virtual arrow / virtual mouse injected via cdp
-  - captures click, drag, scroll, coordinates, rotation
-  - exports json to docs/logs/
-
-sandbox (web/ + @vercel/sandbox)
-  - isolated firecracker microvm per session/agent
-  - chrome/brave ready, novnc streaming
-  - api https (post/get) to the deployed site
-
-production backend (web/, deployed to vercel/netlify)
-  - open node server (hono/express), not platform functions
-  - db (drizzle + mysql2 + prisma schema)
-  - cloudinary for assets and replays
-```
-
-## Main flows
-
-### A. Capture (local/dev)
-1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
-2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
-3. Record each event with timestamp, type, coordinates, target, rng seed.
-4. Compact trajectories and export to `docs/logs/<session>.json`.
-
-### B. Captcha test
-1. Open test page (`tests/examples/hcaptchatest.html` or a real site).
-2. Run solver (hcaptcha challenger / vision) or record manual bypass.
-3. Save evidence (screenshot, token, log) to `tests/output/`.
-
-### C. Production
-1. Agent calls the deployed site api (`web/`).
-2. Backend writes session to db (drizzle/mysql2) and assets to cloudinary.
-3. Logs and replays available via get https.
-
-## Key technologies (details in `06-dependencies.md`)
-
-- Browser automation: `playwright`, `puppeteer`, `chromium-bidi`, `@playwright/test`
-- Human mouse: `bezier-js`, `@napi-rs/canvas`, `d3`
-- Ai / vision: `ai`, `@ai-sdk/*`, `@xenova/transformers`, `onnxruntime-web`, `tesseract.js`
-- Sandbox: `@vercel/sandbox`, `vercel`
-- Server: `hono`, `express`, `cors`, `helmet`, `socket.io` (socket realtime)
-- Db: `drizzle-orm`, `mysql2`, `@prisma/client`, `prisma`
-- Storage: `cloudinary`
-- Validation: `zod`, `valibot`, `arktype`
-
-## Next steps
-
-See `action-plan.md`. Implementation starts after user approval.

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).