docs: explain functionality performance security and UX testing

content/docs/meta.es.json

@@ -30,6 +30,7 @@
     "max",
     "---Detalles técnicos---",
     "architecture",
-    "search-architecture"
+    "search-architecture",
+    "testing"
   ]
 }

content/docs/meta.json

@@ -30,6 +30,7 @@
     "max",
     "---Technical details---",
     "architecture",
-    "search-architecture"
+    "search-architecture",
+    "testing"
   ]
 }

content/docs/meta.ru.json

@@ -30,6 +30,7 @@
     "max",
     "---Технические подробности---",
     "architecture",
-    "search-architecture"
+    "search-architecture",
+    "testing"
   ]
 }

content/docs/search-architecture.es.mdx

@@ -227,3 +227,5 @@ Código del motor en [`cli-messaging`](https://github.com/WireCatLabs/cli-messag
 La gramática exacta, los campos, los presets y los límites están en la referencia del lenguaje de consulta de [Telegram](./tg/query-language.md) o [MAX](./max/query-language.md). La preparación y las opciones están en las guías del archivo de [Telegram](./tg/archive.md) y [MAX](./max/archive.md).
 
 ¿Quieres probarlo? Sigue los ejemplos de búsqueda para **[Telegram](./tg/search.md)** o **[MAX](./max/search.md)**.
+
+Consulta [pruebas](./testing.mdx) para las comprobaciones funcionales, métricas de clasificación, mediciones de rendimiento y sus límites.

content/docs/search-architecture.mdx

@@ -209,6 +209,8 @@ The [interactive playground](./search-playground.mdx) runs the shared query pars
 
 The browser opens no account and runs no conversation build, embedding or live AI. Its short summaries are prepared examples shown only when their evidence is retrieved. The interface is translated; the sample messages stay in English. Use it to learn how to inspect a source, then use the messenger guides for a real archive.
 
+See [testing](./testing.mdx) for functional checks, ranking metrics, performance measurements and their limits.
+
 ## Source map
 
 Engine source in [`cli-messaging`](https://github.com/WireCatLabs/cli-messaging/tree/v0.211.0), the shared library behind both tg and max. These references describe an inspected implementation snapshot, not the installed version or a performance promise.

content/docs/search-architecture.ru.mdx

@@ -227,3 +227,5 @@ max conversations related "Project team" 4521 --json
 Точная грамматика, поля, preset и пределы — в справке по языку запросов [Telegram](./tg/query-language.md) или [MAX](./max/query-language.md). Подготовка и опции — на страницах архива [Telegram](./tg/archive.md) и [MAX](./max/archive.md).
 
 Готовы попробовать? Перейдите к примерам поиска в **[Telegram](./tg/search.md)** или **[MAX](./max/search.md)**.
+
+В разделе [тестирование](./testing.mdx) описаны функциональные проверки, метрики ранжирования, замеры производительности и их ограничения.

content/docs/testing.es.mdx

@@ -0,0 +1,99 @@
+---
+title: Pruebas
+description: "Comprobaciones funcionales, evaluaciones de búsqueda, seguridad y recorridos del lector: qué demuestran y cómo repetirlas."
+---
+
+Al evaluar o modificar `tg` y `max`, usa comprobaciones distintas para corrección, velocidad, seguridad y facilidad de uso. Esta guía explica qué evidencia aporta cada una y dónde reproducirla. Las comprobaciones automáticas cubren casos definidos; superarlas no demuestra que toda búsqueda encuentre una respuesta ni que todas las cuentas y dispositivos se comporten igual.
+
+## Qué comprobamos
+
+| Área | Qué verifica una comprobación | Cómo lo comprobamos |
+| --- | --- | --- |
+| Funcionalidad | Salidas, errores y códigos de terminación esperados; filtros de cuenta, chat, autor y fecha | Pruebas unitarias, integración con almacenes aislados y contratos CLI/MCP |
+| Compatibilidad | Los cambios compartidos funcionan en ambas herramientas y entornos compatibles | Pruebas de adopción, Node.js/Bun, plataformas e instalación de paquetes |
+| Calidad de búsqueda | Se recuperan fuentes relevantes y se ordenan de forma útil | Preguntas sintéticas con mensajes relevantes etiquetados, consultas negativas y métricas de clasificación |
+| Rendimiento | Latencia y consumo de recursos con una carga definida | Consultas cronometradas, escalado del archivo y mediciones separadas de descarga, incorporación y consulta |
+| Seguridad | Se respetan límites concretos de permisos, privacidad y entradas; los analizadores detectan candidatos para revisión | Pruebas negativas, análisis de secretos, dependencias y código, e investigación manual |
+| Experiencia de usuario (UX) | El lector completa una tarea y entiende el resultado | Recorridos en navegador, teclado y móvil, accesibilidad y revisión editorial |
+
+La cobertura indica cuánto código ejecutan las pruebas. No mide la relevancia de búsqueda, la utilidad de una guía ni la ausencia de vulnerabilidades.
+
+## Funcionalidad y paquetes publicados
+
+Las pruebas de implementación permanecen junto al código. `cli-messaging` comprueba el análisis compartido de consultas, almacenamiento, migraciones, búsqueda y permisos. `tg-cli` y `max-cli` comprueban sus adaptadores y la adopción del comportamiento compartido. Las cuentas sintéticas y los almacenes temporales permiten reproducir regresiones sin mensajes personales.
+
+Las pruebas de búsqueda separan las coincidencias estrictas de `--discover`, comprueban los filtros obligatorios tanto en el mensaje coincidente como en la respuesta recuperada, la sintaxis explícita y los límites de trabajo. La [arquitectura de búsqueda](./search-architecture.mdx) explica estos contratos. Una respuesta solo es útil si sigue cumpliendo el alcance solicitado.
+
+[cli-testing](https://github.com/WireCatLabs/cli-testing) contiene comprobaciones reutilizables que acceden desde fuera a ejecutables compilados, servidores MCP o paquetes publicados, además de investigación entre herramientas. Sus pruebas unitarias comprueban el ejecutor; son distintas de ejecutar una batería contra una herramienta. Su [arquitectura](https://github.com/WireCatLabs/cli-testing/blob/main/docs/dev/ARCHITECTURE.md) y [plan](https://github.com/WireCatLabs/cli-testing/blob/main/docs/dev/BACKLOG.md) indican los grupos y su estado de implementación.
+
+La [comprobación de búsqueda publicada](https://github.com/WireCatLabs/cli-testing/blob/main/performance/search/released/README.md) instala paquetes elegidos explícitamente, crea un archivo sintético y ejecuta los binarios con acceso a red bloqueado. Comprueba recuperación de respuestas, aislamiento del autor y búsqueda estricta sin cambios; es una comprobación pequeña del contrato, separada de la evaluación de relevancia.
+
+En una copia de desarrollo de `tg-cli` o `max-cli`, ejecuta:
+
+```sh
+pnpm lint
+pnpm typecheck
+pnpm test:coverage
+pnpm release:check
+```
+
+`release:check` compila y comprueba el contrato de publicación; no prueba una cuenta en vivo. La verificación de paquetes anterior es una ejecución separada bajo demanda.
+
+## Calidad de búsqueda y clasificación
+
+Un **candidato** es un mensaje recuperado para su posible inclusión antes del orden definitivo. La recuperación de candidatos y la clasificación necesitan mediciones distintas: un clasificador no puede promover una respuesta que nunca se recuperó.
+
+| Métrica | Qué pregunta responde |
+| --- | --- |
+| Success@k, también Hit@k | ¿Hay al menos un resultado relevante etiquetado entre las primeras *k* posiciones? |
+| Recall@k | ¿Qué proporción de todos los resultados relevantes etiquetados aparece en esas posiciones? |
+| Precision@k | ¿Qué proporción de esas posiciones contiene resultados relevantes? |
+| Mean reciprocal rank (MRR) | ¿En qué posición aparece el primer resultado relevante, promediada entre consultas? |
+| nDCG@k | ¿Qué calidad tiene el orden con grados de relevancia y mayor peso en las primeras posiciones? |
+| Recuperación de candidatos | ¿Incluye el conjunto de candidatos los resultados relevantes etiquetados antes de ordenarlos? |
+
+Cada informe debe indicar qué métricas calcula realmente. La tabla define medidas disponibles; no implica que cada ejecutor informe de todas ellas.
+
+MRR promedia `1 / rank` del primer resultado relevante y usa cero cuando no se encuentra en la salida evaluada. Declara cualquier límite de profundidad. nDCG compara el orden con relevancia graduada con un orden ideal al mismo límite.
+
+Por ejemplo, **43,8% Success@10** significa que el 43,8% de las consultas evaluadas tiene al menos un resultado relevante etiquetado entre los diez primeros. No dice si se recuperaron todos los resultados relevantes o si la respuesta aparece primero. La décima y la primera posición cuentan por igual como éxito; MRR y nDCG muestran la diferencia.
+
+Las etiquetas deben distinguir una respuesta real de un mensaje que solo menciona el tema. Incluye preguntas sin respuesta, calificadores desconocidos, formulaciones engañosas y respuestas sin las palabras clave de la pregunta. Las coincidencias parciales son posibles fuentes, no prueba de que exista una respuesta.
+
+Usa ejemplos de desarrollo para encontrar fallos y un conjunto separado para evaluar cambios. Cuando un ejemplo ha influido en la implementación, pasa a ser evidencia de desarrollo. Registra consultas, etiquetas, límite de candidatos, compilación y reglas de agregación para comparar porcentajes. La [guía de evaluación](https://github.com/WireCatLabs/cli-testing/blob/main/performance/search/combined-search-evaluation.md) y el [índice de experimentos](https://github.com/WireCatLabs/cli-testing/blob/main/performance/search/README.md) contienen la investigación reproducible.
+
+## Rendimiento y recursos
+
+Mide la consulta completa y sus etapas: recuperación, puntuación, ampliación con respuestas y salida. La **puntuación** asigna un valor de relevancia; la **reclasificación** cambia el orden de candidatos ya recuperados. Una puntuación rápida no garantiza por sí sola una orden rápida.
+
+Informa de la latencia mediana (**p50**) y aquella por debajo de la cual termina el 95% de las ejecuciones medidas (**p95**), junto con tamaño del archivo, número de consultas y candidatos, equipo, entorno, compilación y estado frío o caliente. Registra el máximo de memoria del proceso, no solo el tamaño de los pesos de un modelo. Mide la incorporación de datos por separado. Si se usa un modelo, separa bytes y tiempo de descarga, estado de caché, tiempo de carga y memoria.
+
+Los [experimentos de búsqueda](https://github.com/WireCatLabs/cli-testing/tree/main/performance/search) comparan enfoques de clasificación y tamaños de archivos. Se ejecutan bajo demanda, fuera del paquete publicado del ejecutor. Las mediciones sintéticas describen esa carga y ese equipo; compara configuraciones en las mismas condiciones antes de elegir un modo predeterminado.
+
+## Seguridad y privacidad
+
+Las comprobaciones de seguridad prueban acciones denegadas, entradas incorrectas, aislamiento de cuentas y límites de recursos. El análisis de secretos, dependencias y código produce hallazgos para revisión; un análisis limpio no demuestra ausencia de vulnerabilidades. El [método de seguridad](https://github.com/WireCatLabs/cli-testing/blob/main/docs/security/METHOD.md) define la auditoría y el tratamiento de la evidencia.
+
+Los ejemplos sin conexión usan datos sintéticos, configuración y almacenamiento aislados. El acceso a red o credenciales debe fallar en una comprobación que promete ejecución sin conexión. Las baterías en vivo y con agentes requieren una configuración privada de pruebas seleccionada explícitamente y autorización; no se ejecutan automáticamente sobre la cuenta del propietario. Los resultados de auditorías operativas y de cuentas privadas permanecen privados. La investigación pública usa datos sintéticos.
+
+Consulta los controles del usuario y sus límites en [seguridad](./security.mdx) y [permisos](./permissions.mdx). Los permisos de la CLI no restringen acciones de un agente mediante otras herramientas.
+
+## Experiencia de usuario y documentación
+
+Las pruebas de navegador siguen recorridos del lector: abrir una guía, navegar, probar la búsqueda, copiar órdenes de instalación y leer Markdown. Las comprobaciones específicas cubren teclado, diseño móvil, idiomas y accesibilidad. El análisis automático de accesibilidad detecta problemas concretos; la lectura y revisión manual evalúan claridad, utilidad y comprensión de resultados incompletos.
+
+Las comprobaciones de documentación validan enlaces, ejemplos, estructura por idioma, huellas de fuentes y contratos de órdenes revisados. La revisión editorial lee todo el texto modificado en cada idioma. Que las traducciones tengan la misma estructura no demuestra que su significado sea correcto.
+
+En `cli-docs`, ejecuta estas comprobaciones locales:
+
+```sh
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm docs:check
+pnpm test:browser
+```
+
+La orden local de navegador ejecuta los recorridos esenciales; CI ejecuta la exportación completa, enlaces, SEO y pruebas de navegador más amplias. Para cambios fuera de esos recorridos, ejecuta directamente la prueba afectada. Otros repositorios publican sus órdenes en la [guía de pruebas de cli-testing](https://github.com/WireCatLabs/cli-testing/blob/main/docs/dev/TESTING.md) y en su documentación para colaboradores.
+
+Al comparar resultados, separa fallos funcionales, cambios de relevancia, regresiones de rendimiento y hallazgos pendientes. Elige la siguiente comprobación según el comportamiento modificado y conserva sus entradas y evidencia para que otro colaborador pueda repetirla.