# Quickstart - Browser Tool

Guia corta para dejar la herramienta lista y ejecutar una prueba minima.

Si quieres minimizar pasos manuales, usa directamente:

- `docs/INSTALACION_POR_AGENTE.md`

## 1) Instalar

Desde `opencode-browser-tool/`:

```bash
./install.sh
```

Alternativa neutral por npm/node:

```bash
npm run setup
```

Esto instala dependencias, compila y prepara `Chromium managed by Playwright`.

## 2) Compilar

```bash
npm run build
```

## 2.1) Verificar

```bash
./check.sh
```

## 3) Configurar MCP en el proyecto

Crear `opencode-browser-tool/.opencode/opencode.json` con:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "browser-tool": {
      "type": "local",
      "command": [
        "node",
        "/ABSOLUTE/PATH/opencode-browser-tool/dist/server.js"
      ]
    }
  }
}
```

Nota: ajusta la ruta absoluta de `dist/server.js` a tu equipo.

## 4) Verificar conexion MCP

```bash
opencode mcp list
```

Debe aparecer `browser-tool` como `connected`.

## 5) Primera prueba minima

Pide a OpenCode una secuencia simple:

- abrir navegador
- navegar a una URL
- tomar snapshot
- cerrar navegador

Ejemplo de instruccion:

```text
Usa solo browser-tool: abre navegador visible, navega a https://example.com, toma snapshot con label quickstart y cierra navegador.
```

## 5.1) Auto-descubrimiento recomendado

Antes de pruebas complejas, pide:

- `browser_help`
- `browser_health`
- `browser_diagnostics_clear` (opcional, para empezar limpio)

Con eso el agente detecta capacidades disponibles, defaults y estado operativo actual.

## 6) Dónde quedan las capturas

Se guardan en:

- `opencode-browser-tool/artifacts/`

## 7) Descubrir capacidades automaticamente

Usa las tools `browser_help` y `browser_health` al inicio de una sesion para que el agente reciba capacidades, defaults y estado de ejecucion.

Para incidencias durante pruebas, usa `browser_diagnostics` para extraer consola, errores de pagina y requests fallidas.
Si un flujo no avanza, usa `browser_observe` para capturar estado intermedio y `browser_handle_consent` para resolver banners.

## 8) Grabacion bajo demanda (video/trace)

Para sesiones complejas, abre con grabacion:

- `recordVideo: true`
- `recordTrace: true`
- `recordLabel: "caso-xyz"`

Los artifacts se cierran y quedan disponibles al ejecutar `browser_close`.

## 9) Reporte consolidado de ejecucion

Al finalizar un flujo, puedes pedir:

- `browser_report` con `format: both`

Nota: por defecto la herramienta ya deja `saveToFile=true` al instalar.

Esto deja resumen tecnico en JSON y lectura humana en Markdown dentro de `artifacts/`.

Si quieres cambiar ese default de forma persistente, usa `browser_config` con `action: set`.

## 10) Elegir navegador: testing o system

Por defecto, `browser_open` usa `browserKind: testing` (Playwright managed).

Si necesitas perfil real de usuario, puedes usar navegador del sistema:

```json
{
  "browserKind": "system",
  "persistentProfile": true,
  "userDataDir": "/home/pancho/.chrome-perfil-google-real",
  "startUrl": "https://www.google.com"
}
```

Tambien puedes fijarlo de forma persistente con `browser_config` (`browserDefaultKind`, `browserDefaultPersistentProfile`, `browserDefaultUserDataDir`).

## 11) Verbose y delay humano (default activo)

Por defecto, `browser_open` aplica:

- `verbose: true`
- `verboseOverlay: true` (en modo visible)
- `interactionDelayMinMs: 1000`
- `interactionDelayMaxMs: 3000`

Puedes desactivar verbose por ejecucion:

```json
{
  "verbose": false,
  "verboseOverlay": false
}
```

Y puedes ajustar delays por ejecucion:

```json
{
  "interactionDelayMinMs": 800,
  "interactionDelayMaxMs": 1800
}
```