Guías de ayuda

Tus guías ya explican cómo funciona tu producto. Espejo las lee en su servidor, convierte cada página en Markdown limpio y la guarda. Desde ahí el mismo texto alimenta dos cosas:

• La sección Guides del widget de chat: colecciones, artículos y un buscador, que el widget dibuja con su propio estilo. Sin iframes.
• El agente de soporte: con search_guides busca en tus guías antes de contestar y enlaza la guía que usó.

Hay tres formas de conectarlas, todas en la pestaña Guides del proyecto en la consola (#/projects?focus=guides):

	Sitio de docs	Repo de GitHub	Tu propia API
Para	Un sitio de docs público (Starlight, Docusaurus, Mintlify, GitBook o cualquier HTML)	Archivos Markdown o MDX en un repositorio de GitHub, público o privado	Centros de ayuda privados o a medida
Qué publicas	Nada nuevo. Se recomienda un llms.txt	Nada nuevo. Instalas la GitHub App de Espejo	Dos endpoints GET
Cómo lo lee Espejo	llms.txt, después sitemap.xml, después un crawl	Los archivos .md y .mdx de una carpeta, de nuevo en cada push	Pedidos firmados a tus endpoints

Conectar un sitio de docs

Pega la dirección https:// de tus docs, por ejemplo https://docs.acme.com/es/. Tiene que resolver a una dirección pública y no puede llevar usuario ni contraseña. Solo se leen páginas de ese mismo host, y solo bajo ese path.

Espejo busca esto, en este orden, y usa lo primero que dé páginas:

1. llms.txt. Primero {tu url}/llms.txt, después {origen}/llms.txt (del de la raíz, solo los links bajo tu path). Cada título ## es una colección y cada link debajo es una guía, en ese orden. Un link a un archivo .md o .mdx se lee como Markdown, y la guía abre en la misma dirección sin la extensión (/start/install.md abre /start/install, /start/index.md abre /start/).
2. sitemap.xml. {tu url}/sitemap.xml, después {origen}/sitemap-index.xml y {origen}/sitemap.xml. Se siguen los índices de sitemaps (hasta 10 sitemaps hijos). Solo se leen las URLs bajo tu path.
3. Un crawl. Desde tu URL, los links del mismo host bajo ese path, en anchura.

Un llms.txt es la opción más exacta: decides las colecciones, el orden y los títulos, y una versión Markdown de cada página evita adivinar cuál es el contenido principal. Uno mínimo:

# Acme

> El centro de ayuda de Acme.

## Primeros pasos

- [Instalar Acme](https://docs.acme.com/start/install.md): Acme andando en dos minutos
- [Configurar](https://docs.acme.com/start/configure.md)

## Facturación

- [Facturas](https://docs.acme.com/billing/invoices.md)

Cómo una página se vuelve una guía

• Páginas HTML. Espejo se queda con el contenido principal y descarta la navegación, el pie, los scripts y los estilos. Las notas y avisos dentro del contenido quedan, como citas. El título sale del h1 de la página (o de og:title, o de <title>), y la descripción de <meta name="description">. Si la página publica su Markdown con <link rel="alternate" type="text/markdown" href="..."> en el mismo host, se usa ese Markdown.
• Páginas Markdown. Se lee el frontmatter: title, description, collection (mueve la guía a esa colección) y order (su lugar dentro de la colección; sidebar_position también sirve). Sin title, el título es el primer encabezado #.
• MDX. Las líneas import y export se descartan y los componentes quedan como su texto: <Tabs><TabItem label="npm">Corre npm i</TabItem></Tabs> deja Corre npm i.
• Links e imágenes. Los relativos pasan a absolutos. Su esquema no se cambia; el widget solo activa links e imágenes https.

Un frontmatter recomendado:

---
title: Arreglar un pesaje que no se guarda
description: Los tres campos que espera Guardar
collection: Pesajes
order: 2
---

Colecciones y orden

Sin llms.txt, Espejo reconoce estos generadores por su markup y usa su sidebar para las colecciones y el orden: Starlight, Docusaurus, Mintlify y GitBook. Un grupo del sidebar es una colección; un link suelto en el primer nivel va por su carpeta.

Para cada guía, la colección es, de la primera a la última opción: collection del frontmatter, la sección ## del llms.txt, el grupo del sidebar, la primera carpeta bajo tu path (/docs/billing/invoices está en Billing) y por último General.

Páginas que se saltean

Las páginas privadas nunca se leen: una página que contesta 401 o 403, o que redirige a otro host (normalmente, un login), se saltea. También las que no contestan 200, tardan demasiado, son demasiado grandes o no tienen contenido.

Conectar un repo de GitHub

Espejo lee los archivos .md y .mdx de una carpeta de un repositorio, en una rama, a través de la GitHub App de Espejo. El repositorio puede ser privado. Si la tarjeta GitHub repo dice Not configured on this server, GitHub no está disponible en el servidor de Espejo que usas.

Quién puede conectar: en una cuenta personal de GitHub, solo el dueño de esa cuenta; en una organización, solo un admin activo de la organización. Y como fuente solo se pueden usar los repositorios que esa persona puede leer en GitHub, aunque la app tenga acceso a más. Para usar otro repositorio, conecta GitHub de nuevo desde una cuenta que pueda leerlo.

Precaución

Las guías que sincronizas son públicas para cualquiera que tenga la clave pública del proyecto, la misma que lleva el widget en tu página. Eso incluye el contenido sincronizado desde un repositorio privado. Apunta la fuente a una carpeta que tenga solo lo que quieres que lean tus visitantes.

1. En la pestaña Guides, elige GitHub repo y haz clic en Connect GitHub. GitHub abre la página de instalación de la GitHub App de Espejo. El link sirve una vez y vence a los 15 minutos.
2. En GitHub, elige la cuenta u organización y dale a la app acceso a todos los repositorios o solo al que tiene tus guías.
3. GitHub te pide autorizar la app con tu cuenta de GitHub. Espejo lo usa solo para confirmar que eres el dueño de la cuenta personal o admin de la organización, y para ver qué repositorios puedes leer. No lo guarda.
4. GitHub te devuelve a la pestaña Guides del proyecto desde el que empezaste. La consola termina la conexión con tu sesión: solo funciona para el mismo proyecto y la misma persona que hizo clic en Connect GitHub, dentro de los 10 minutos. Después muestra GitHub connected y Connected to GitHub as con la cuenta. Elige el Repository (la lista tiene buscador, muestra hasta 1.000 repositorios y solo los que puedes leer), la Branch (arranca con la rama default del repositorio, y pasa a la rama default de otro repositorio cuando lo eliges) y, si quieres, la Folder (docs/guides; vacía lee todo el repositorio).
5. Elige cómo abre el widget una guía y haz clic en Connect repository. La primera sincronización arranca en el acto.

Permisos

La app pide tres permisos de solo lectura, y nada más:

Permiso	Para qué
Contents: read	Para leer los archivos de la carpeta que elegiste.
Metadata: read	GitHub lo exige a toda app. Permite a Espejo listar los repositorios que ve la app.
Members: read (organización)	Para confirmar que quien conecta una organización es admin de ella.

Espejo nunca escribe en tu repositorio, y cada sincronización lee solo el repositorio que elegiste.

Si tu organización exige que un owner apruebe las GitHub Apps, GitHub le manda el pedido y la consola te lo avisa. Cuando esté aprobada, haz clic en Connect GitHub de nuevo.

Cuando la consola no puede conectar la app, dice por qué, y en todos los casos el arreglo empieza por hacer clic en Connect GitHub de nuevo:

Mensaje	Qué significa
The GitHub link expired after 15 minutes	El link dura 15 minutos.
That GitHub link is not valid anymore	El link ya se usó, o se modificó.
That installation is not yours to connect	Tu cuenta de GitHub no ve esa instalación de la app de Espejo. Conecta desde la cuenta personal que es su dueña, o como admin de la organización.
That installation is on another personal GitHub account	Solo el dueño de una cuenta personal puede conectarla.
Only an admin of the GitHub organization can connect it	No eres admin activo de la organización. Pídele a un admin que la conecte.
This GitHub connection was started from a project you cannot access	El link se inició desde un proyecto que no está en tu lista, así que no se conectó nada.
That GitHub connection was not found, expired after 10 minutes, or was already used	Termina la conexión en la misma sesión del navegador, dentro de los 10 minutos.

Si cambias a qué repositorios accede la app desde su configuración en GitHub, GitHub puede devolverte a la consola con GitHub access updated. Eso no cambia nada en Espejo: para usar un repositorio nuevo, haz clic en Connect GitHub de nuevo, así Espejo sabe qué repositorios puedes leer.

Qué lee Espejo

• Todo archivo que termina en .md o .mdx dentro de la carpeta, subcarpetas incluidas. Los demás archivos se ignoran, y también los de más de 2 MB.
• Hasta 499 archivos por sincronización, tomados en orden de path: en una carpeta más grande, siempre quedan afuera los mismos.
• El frontmatter funciona como en las páginas Markdown: title, description, collection y order (o sidebar_position). Sin title y sin un encabezado #, el título sale del nombre del archivo (reset-password.md es Reset password). El MDX se reduce a su texto de la misma forma.
• Un index.md o un README.md es una guía como cualquier otra.
• La página de cada guía es el archivo en GitHub (https://github.com/acme/help/blob/main/docs/billing/invoices.md). Para un repositorio privado, elige In the widget: tus visitantes no pueden abrir el archivo en GitHub.
• Los links relativos pasan a absolutos en GitHub: [Facturas](./invoices.md) apunta a ese archivo en GitHub. Usa direcciones https absolutas para las imágenes, porque una imagen relativa apunta a la página del archivo en GitHub, no a la imagen.

Para cada guía, la colección es, de la primera opción a la última: collection en el frontmatter, la primera subcarpeta debajo de tu carpeta (docs/billing/invoices.md con la carpeta docs está en Billing) y por último General. Las colecciones siguen el orden de path de su primer archivo, y dentro de una colección las guías van por order y después por path.

Quitar el acceso

Disconnect GitHub account, en la pestaña Guides, hace que el proyecto olvide la instalación. La app sigue instalada en GitHub, y una fuente de repositorio deja de sincronizarse hasta que vuelvas a conectar GitHub. Para quitar la app de GitHub, desinstálala o cambia su acceso a repositorios en la configuración de tu cuenta u organización, en GitHub Apps. Después de eso la fuente muestra Sync failed con el motivo, y las guías de la última sincronización buena siguen publicadas.

Si instalas la app de nuevo, conecta GitHub, abre Change repository y guarda el repositorio otra vez: eso arranca una sincronización aunque nada más haya cambiado.

Si vuelves a instalar la app, abre Change repository y guarda el repositorio de nuevo.

Conectar tu propia API

Para un centro de ayuda que no es un sitio público, expón dos endpoints y Espejo los lee con pedidos firmados. En la consola, elige Your own API y completa:

• Base URL. https, pública. Los paths se le agregan: https://api.acme.com/help más /v1/help/articles es https://api.acme.com/help/v1/help/articles.
• List path. Por defecto /v1/help/articles.
• Article path. Por defecto /v1/help/articles/{id}. Tiene que incluir {id}, que se reemplaza por el id del artículo, codificado para URL.
• Signing secret. Haz clic en Generate secret, cópialo y guárdalo en tu backend. Se muestra una sola vez: Espejo lo guarda cifrado y después solo muestra sus últimos cuatro caracteres. Generate new secret lo reemplaza.

El listado

GET {base}{list path} contesta 200 con JSON:

{
  "articles": [
    {
      "id": "reset-password",
      "title": "Recuperar tu contraseña",
      "description": "Cuando el correo de recuperación no llega",
      "collection": "account",
      "collection_title": "Tu cuenta",
      "order": 1,
      "url": "https://acme.com/help/reset-password",
      "updated_at": "2026-09-30T12:00:00Z"
    }
  ],
  "next": "/v1/help/articles?page=2"
}

Campo	Obligatorio
id	Sí	String o número, hasta 200 caracteres. Estable: identifica la guía entre sincronizaciones.
title	Sí	Los artículos sin id o sin title se saltean.
description	No	Una línea.
collection	No	La clave de la colección. Sin ella, el artículo va a General.
collection_title	No	El nombre que se muestra. Sin él, uno armado a partir de collection.
order	No	Número. Orden dentro de la colección; sin él, el orden del listado.
url	No	La página pública del artículo. Solo se guarda si es https.
updated_at	No	Se acepta, todavía no se usa.

next es opcional: la página siguiente del listado, como path o como URL del mismo host. Espejo lo sigue hasta 50 páginas. Un next de otro host se ignora.

El artículo

GET {base}{article path} contesta 200 con JSON:

{ "id": "reset-password", "title": "Recuperar tu contraseña", "markdown": "Haz clic en **Olvidé mi contraseña** ..." }

o con el Markdown directo y Content-Type: text/markdown. En JSON, title y description pisan los del listado, y markdown es obligatorio. Un artículo que no contesta 200, o no trae Markdown, se saltea.

La firma

Cada pedido lleva dos headers:

Header	Valor
x-espejo-timestamp	Tiempo unix en segundos.
x-espejo-signature	sha256= y el HMAC-SHA256 en hex, con tu secreto, de GET, el path y el timestamp, uno por línea.

El path es exactamente el pedido, con el path de la base y la query: /help/v1/help/articles?page=2. Verifícalo antes de contestar, rechaza timestamps viejos y contesta 401 si no coincide:

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromEspejo(req, secret) {
  const timestamp = req.get("x-espejo-timestamp") ?? "";
  const signature = req.get("x-espejo-signature") ?? "";
  // Cinco minutos de margen por diferencias de reloj.
  if (!/^\d+$/.test(timestamp) || Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const signed = `${req.method}\n${req.originalUrl}\n${timestamp}`;
  const expected = `sha256=${createHmac("sha256", secret).update(signed).digest("hex")}`;
  const received = Buffer.from(signature);
  const wanted = Buffer.from(expected);
  return received.length === wanted.length && timingSafeEqual(received, wanted);
}

Compara los bytes, no los caracteres: timingSafeEqual tira un error si los dos buffers tienen distinto largo, y un header con caracteres que no son ASCII puede tener la misma cantidad de caracteres y más bytes.

req.originalUrl es el path que recibió tu app. Si un proxy delante de ella le saca un prefijo (Espejo pide /help/v1/help/articles y tu app ve /v1/help/articles), la firma no va a coincidir: arma el path que pidió Espejo, con el prefijo, antes de verificarla.

Si el listado contesta 401 o 403, la sincronización falla con Your API rejected the signed request. Revisa el secreto en tu backend, o genera uno nuevo.

Sincronización

Espejo sincroniza tus guías:

• cuando conectas la fuente o la cambias (y cuando generas un secreto nuevo),
• cuando haces clic en Sync now en la pestaña Guides,
• con un repo de GitHub, en cada push a la rama que cambia un archivo de la carpeta (sin carpeta, un archivo .md o .mdx en cualquier lugar). Los pushes seguidos se agrupan en a lo sumo una sincronización por minuto, y un push que llega durante una sincronización se toma cuando termina. Un push solo cuenta si GitHub entrega su evento: GitHub no manda eventos de más de 25 MB, y una entrega fallida no se reenvía sola. En ese caso el próximo push, Sync now o la sincronización diaria toman el cambio,
• y solo, cada 24 horas.

Mientras corre, la pestaña muestra Syncing y cuántas páginas leyó. Al terminar, muestra la fecha, la cantidad de guías y tus colecciones.

Estado	Significa
Waiting for first sync	Conectada, todavía sin leer.
Syncing	Leyendo ahora. Sync now espera a que termine.
Synced	Las guías de esta sincronización están publicadas.
Sync failed	Se muestra el motivo. Las guías de la última sincronización buena siguen publicadas; nada se reemplaza hasta que una sincronización termine bien.

Una sincronización que no encuentra guías es un fallo (No guides found). Cambiar la dirección, el método, los paths de la API, o el repositorio, la rama o la carpeta borra las guías de la fuente anterior y arranca de cero.

Con un repo de GitHub, estos son los fallos que puedes ver, y qué hacer:

Motivo que se muestra	Qué hacer
No guides found	Revisa la rama y la carpeta, y que las guías sean archivos .md o .mdx.
La rama no existe en el repositorio	Revisa el nombre de la rama con Change repository.
El repositorio está vacío	Primero haz push de tus guías.
El árbol del repositorio es demasiado grande para leerlo en un pedido	GitHub no pudo devolver el árbol de archivos entero de una vez. Pasa las guías a un repositorio propio más chico.
GitHub negó el acceso al repositorio	Instala la GitHub App de Espejo de nuevo y dale acceso al repositorio.
GitHub alcanzó su límite de pedidos (rate limit), prueba más tarde	GitHub está limitando los pedidos por ahora. Las guías de la última sincronización buena siguen publicadas; haz clic en Sync now más tarde, o espera la próxima sincronización.
No se pudo leer (un archivo) desde GitHub, o GitHub contestó (un status) al leer (un archivo)	Un archivo no se pudo leer. Falla la sincronización entera para que no se pierda ninguna guía; haz clic en Sync now más tarde.
No se pudo contactar a GitHub. Prueba más tarde	Haz clic en Sync now más tarde.
GitHub contestó (un status) al pedir acceso al repositorio	Haz clic en Sync now más tarde. Si sigue fallando, conecta GitHub de nuevo.
La GitHub App se desinstaló o se suspendió	Instálala de nuevo, conecta GitHub y elige el repositorio.
La GitHub App está suspendida en esta cuenta	Quita la suspensión de la app en GitHub. Las guías se vuelven a sincronizar solas.
La GitHub App (de Espejo) ya no tiene acceso a este repositorio	Dale acceso de nuevo en GitHub, o elige otro repositorio.
Este repositorio no está entre los permitidos para este proyecto	La cuenta que conectó GitHub no puede leer este repositorio. Conecta GitHub de nuevo desde una cuenta que pueda leerlo y después elige el repositorio.
La GitHub App de Espejo ya no está conectada a este proyecto	Haz clic en Connect GitHub y después guarda el repositorio de nuevo con Change repository.
La fuente de GitHub está incompleta. Elige el repositorio de nuevo	Abre Change repository y guárdalo.
GitHub no está configurado en este servidor	GitHub no está disponible en el servidor de Espejo que usas.

Los motivos se muestran en inglés. Al guardar el repositorio, la consola también puede contestar que el repositorio no es uno que puedas leer en GitHub (conecta GitHub de nuevo desde una cuenta que pueda leerlo, o elige otro), que el repositorio no está disponible para la app (dale acceso en GitHub, o elige otro), que la app ya no está instalada (conéctala de nuevo) o que no se pudo contactar a GitHub (prueba de nuevo en un momento).

Límites de una sincronización: 500 pedidos (cuentan páginas, llms.txt, sitemaps y páginas del listado), 10 minutos, 3 pedidos a la vez, 10 segundos y 2 MB por respuesta (5 MB para un sitemap), 5 redirecciones en el mismo host. Un artículo guarda hasta 200.000 caracteres de Markdown, un título hasta 300 y una descripción hasta 500. Los pedidos llegan con el user agent EspejoGuidesBot/1.0 (+https://docs.espejo.dev/en/guides/help-guides/).

Colecciones

Después de la primera sincronización buena, la pestaña lista tus colecciones, cada una con un switch. Una colección oculta queda fuera del widget y de lo que busca el agente, y sigue oculta después de cada sincronización.

Abrir una guía

Elige cómo abre una guía el widget: In the widget (el Markdown, con el estilo del widget y un link a la página) u Open the page (tu página en una pestaña nueva; el agente igual lee el texto).

En el widget

Prende Guides en el Menu de la pestaña Widget. Solo se puede prender cuando las guías ya sincronizaron. Desde ahí, GET /v1/agent/config lista guides en sections, y el widget lee las guías con la clave pública del proyecto. Cualquiera con esa clave puede leer todas las guías sincronizadas, también las que vienen de un repositorio privado de GitHub. El widget muestra Guides aunque el agente de soporte esté apagado; sin Support ni Guides para mostrar, la config contesta 404 y el widget no aparece.

Si armas tu propia UI, el widget usa estos endpoints. El header x-espejo-key es obligatorio: sin él la respuesta es 403. La clave también puede ir en ?key=, pero sólo junto al header, y entonces las dos tienen que coincidir.

Endpoint	Contesta
GET /v1/guides	{ render, collections: [{ slug, title, articles: [{ id, title, description, url }] }], popular }
GET /v1/guides/search?q=	{ results: [{ id, title, description, url, collection, snippet }] }
GET /v1/guides/{id}	{ id, title, description, url, collection, markdown }

• popular trae hasta 3 ids de artículos para Home: por ahora, los primeros en el orden de tus guías.
• La búsqueda encuentra palabras completas, sin distinguir mayúsculas, y la última palabra también encuentra el comienzo de una palabra (instal encuentra Install). Acepta comillas para una frase, -palabra para excluir y or. q se corta a 200 caracteres; un q vacío es 400. Hasta 20 resultados. snippet es texto plano.
• 404 cuando la sección Guides no se muestra (apagada en el menú, o sin sincronizar) y para un artículo que no existe o está en una colección oculta. 403 sin clave o con una clave inválida, con un origen no permitido o con la cuenta desactivada. 429 pasados 120 pedidos por minuto por IP. Un 200 se puede guardar un minuto (Cache-Control: private, max-age=60, Vary: origin, x-espejo-key); los errores van con no-store.

El agente: search_guides

Con guías sincronizadas, el agente de soporte recibe la tool search_guides. Recibe { "query": "..." } y obtiene hasta 5 fragmentos de tus guías, cada uno con su título, colección, URL y hasta 1.200 caracteres de texto. Espejo la ejecuta en su servidor, como get_page_context: nunca llega al navegador.

Préndela o apágala en el panel Support agent, en What it may do in your systems: Answer from your guides. Viene prendida cuando hay guías sincronizadas, y no se puede prender antes. Las colecciones ocultas no se buscan.

Precaución

El texto de las guías se trata como dato, nunca como instrucciones. Espejo envuelve los fragmentos en <guides_results> y su prompt le dice al modelo que no siga pedidos que aparezcan ahí. La misma regla protege al agente del texto de la página, como explica el texto de la página es dato no confiable.

Con un endpoint personalizado

Un endpoint personalizado recibe search_guides en tools cuando está prendida. Si tu agente la llama, Espejo la ejecuta y manda el resultado en el pedido siguiente, como get_page_context.

Con Cobre

Un agente de Cobre solo llama a las tools registradas en su workspace. Registra search_guides como tool client-owned: el script de registro ya la incluye. Después agrega search_guides a las tools de la revisión del agente. Espejo la contesta con las guías sincronizadas; con Answer from your guides apagado, el agente lee que la tool no está disponible. El prompt de Espejo no viaja a Cobre, así que dile al agente en su prompt de Cobre que el texto dentro de <guides_results> es dato, nunca instrucciones.