# Modo guía

> Fuente: https://astrallab.dev/es/docs/guides

Disponible desde la 0.2.4

Recorre un flujo de cualquier aplicación web con un agente y Astral escribe la guía de usuario por ti.

## Qué obtienes

Una guía escrita a partir de una ejecución grabada, en la carpeta de la ejecución junto a `report.html`:

- `guide.md` y `guide.html` (una página autocontenida): un título, una introducción, una sección numerada por paso y una instrucción numerada por cada acción.
- Una captura por acción, tomada antes de un clic, con el objetivo marcado.
- Una sección final de **Resultado** con una captura de cierre.
- Un enlace a la grabación: un MP4 en macOS, un PNG animado en el resto.
- Solo nombres de archivo relativos, así que la carpeta se puede mover o comprimir tal cual.

## Pídeselo a tu agente

Cualquier agente MCP conectado a Astral puede hacerlo. Pídeselo, por ejemplo: _«escribe una guía de usuario para crear un cliente, en español»_. Detrás está el prompt MCP `write-guide`, que tu agente lista junto con los demás (consulta [la referencia de herramientas](https://astrallab.dev/es/docs/tools.md)). Sus argumentos:

- `task` (obligatorio): lo que enseña la guía, por ejemplo «cómo crear una cuenta».
- `lang`: el idioma de la guía como código, `es` o `en` (por defecto `en`).
- `url`: dónde empieza el recorrido (opcional: si no, la pestaña actual).

El agente explora el flujo, lo ejecuta una vez como [ejecución de prueba](https://astrallab.dev/es/docs/test-runs.md) con la opción `guide`, comprueba el resultado e informa de los archivos.

## La opción guide

El prompt usa una opción de `astral.test`, que también puedes definir tú mismo en un script:

```js
await astral.test('Create a customer', async () => {
  await astral.step('Open the customers page', () =>
    astral.navigate({url: 'http://127.0.0.1:4555/'}));
  // ...the rest of the flow
}, {
  record: 'video',
  guide: {lang: 'es', title: 'Crear un cliente', intro: 'Cómo dar de alta un cliente nuevo.'}
});
```

`guide` acepta `lang`, `title` e `intro`. Activa por sí misma las capturas por acción; añade `record: 'video'` para obtener también una grabación. El resultado de la ejecución incluye `guide: {md, html, lang}`.

## Idiomas

Los rótulos dibujados en la página y las etiquetas de la guía (Resultado, Ver la grabación, Captura de pantalla) están traducidos para inglés y español. Cualquier otro código de idioma recurre a los rótulos en inglés, mientras que los nombres de los pasos, el título y la introducción quedan en el idioma en que los escribió el agente. Nombra cada paso como lo haría el usuario, por ejemplo «Crea tu cuenta», no como lo haría una prueba.

## Contraseñas

Una contraseña escrita nunca llega a la guía. La instrucción dice “Escribe tu contraseña en «Password»” (o “Type your password in «Password»” en inglés) y el valor no se escribe en ningún archivo.

## Recorridos fallidos

Si un paso falla, la guía se escribe igualmente, pero empieza con una advertencia, “This walkthrough did not complete: step N failed. Do not publish this guide as it is.” (en el idioma de la guía), y el paso fallido queda marcado. Corrige el flujo y vuelve a ejecutarlo.

## Cómo se ve

El `guide.md` de una ejecución real contra la app de demostración DevLab (solo se sustituye la dirección):

```markdown
# Cómo crear una cuenta

Esta guía te lleva por el registro paso a paso.

## 1. Abre la página de registro

1. Ve a https://your-app.example/register

   ![Captura de pantalla](01-step1-navigate.png)

## 2. Rellena tus datos

1. Escribe «Ana Guía» en «Name»

   ![Captura de pantalla](03-step2-type.png)

2. Escribe «ana@devlab.test» en «Email»

   ![Captura de pantalla](04-step2-type.png)

3. Escribe tu contraseña en «Password»

   ![Captura de pantalla](05-step2-type.png)

4. Escribe tu contraseña en «Confirm password»

   ![Captura de pantalla](06-step2-type.png)

## 3. Crea la cuenta

1. Haz clic en «Create account»

   ![Captura de pantalla](08-step3-click-before.png)

## Resultado

![Resultado final](10-step3-final.png)

[Ver la grabación](recording.mp4)
```

Los nombres de los campos vienen de las propias etiquetas de la app, así que una app en inglés da «Email» dentro de frases en español.

## Plataformas

Verificado solo en macOS. La grabación MP4 se codifica en macOS; en otros sistemas la grabación es un PNG animado. Windows y Linux no están verificados para el modo guía.