Update docs based on agent experience review

api-reference/client-libraries.mdx

@@ -1,8 +1,7 @@
 ---
 title: Client Libraries
-description: Use Trophy's type-safe SDKs to integrate with the API.
-og:description: Use Trophy's type-safe SDKs to integrate with the API and start
-  building gamified product experiences.
+description: Official Trophy SDKs for Node, Go, Java, .NET, PHP, Python, and Ruby with install commands and GitHub repositories.
+og:description: Official Trophy SDKs for Node, Go, Java, .NET, PHP, Python, and Ruby with install commands and GitHub repositories.
 icon: code-xml
 ---
 

api-reference/errors.mdx

@@ -0,0 +1,30 @@
+---
+title: Error Codes
+description: Common Trophy API HTTP status codes.
+og:description: Common Trophy API HTTP status codes.
+icon: circle-x
+---
+
+This page summarizes the HTTP status codes you will see most often when integrating with the Trophy Application API. For endpoint-specific behaviour and response schemas, see the [API reference](/api-reference/introduction).
+
+## Authentication errors {#authentication-errors}
+
+| Status | When it happens | What to do |
+| --- | --- | --- |
+| `401 Unauthorized` | The `X-API-KEY` header is missing or invalid | Create or rotate an application API key and verify [authentication](/api-reference/authentication) set up|
+
+## Rate limiting {#rate-limiting}
+
+| Status | When it happens | What to do |
+| --- | --- | --- |
+| `429 Too Many Requests` | Your organisation exceeded the endpoint [rate limit](/api-reference/rate-limiting) | Back off and retry; request a higher limit if needed |
+
+## Retry guidance {#retry-guidance}
+
+- Retry `429` and `5xx` with exponential backoff.
+- On retry, send the same idempotency key for the same logical action so Trophy does not double-count.
+- Do not retry `401` until the API key is fixed.
+
+## Get Support {#get-support}
+
+Want to get in touch with the Trophy team? Reach out to us via [email](mailto:support@trophy.so). We're here to help!

api-reference/introduction.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: Learn about the Trophy API and get started building your integration.
+description: Authenticate, handle errors and rate limits, use idempotency, and explore Trophy Application API SDKs.
 subtitle: Learn about the Trophy API and get started building your integration.
 ---
 
@@ -36,6 +36,9 @@ Learn more about how to integrate with the Trophy Application API below.
   <Card title="Idempotency" icon="repeat" href="/api-reference/idempotency">
     Learn how to prevent unintended side effects when retrying requests.
   </Card>
+  <Card title="Errors" icon="circle-exclamation" href="/api-reference/errors">
+    Common HTTP status codes for auth, rate limits, and metric events.
+  </Card>
   <Card title="SDKs" icon="code-xml" href="/api-reference/client-libraries">
     Use Trophy’s type-safe SDKs to integrate with the API.
   </Card>

docs.json

@@ -81,7 +81,8 @@
                 "group": "Getting Started",
                 "pages": [
                   "getting-started/introduction",
-                  "getting-started/quickstart"
+                  "getting-started/quickstart",
+                  "getting-started/production-checklist"
                 ]
               },
               {
@@ -155,6 +156,7 @@
                   "api-reference/authentication",
                   "api-reference/rate-limiting",
                   "api-reference/idempotency",
+                  "api-reference/errors",
                   "api-reference/client-libraries"
                 ]
               },
@@ -488,7 +490,8 @@
                 "group": "Primeros pasos",
                 "pages": [
                   "es/getting-started/introduction",
-                  "es/getting-started/quickstart"
+                  "es/getting-started/quickstart",
+                  "es/getting-started/production-checklist"
                 ]
               },
               {
@@ -562,6 +565,7 @@
                   "es/api-reference/authentication",
                   "es/api-reference/rate-limiting",
                   "es/api-reference/idempotency",
+                  "es/api-reference/errors",
                   "es/api-reference/client-libraries"
                 ]
               },

es/api-reference/client-libraries.mdx

@@ -1,8 +1,7 @@
 ---
 title: Bibliotecas de Cliente
-description: Utiliza los SDK con tipado seguro de Trophy para integrar con la API.
-og:description: Utiliza los SDK con tipado seguro de Trophy para integrar con la
-  API y empezar a crear experiencias de producto gamificadas.
+description: SDKs oficiales de Trophy para Node, Go, Java, .NET, PHP, Python y Ruby con comandos de instalación y repositorios de GitHub.
+og:description: SDKs oficiales de Trophy para Node, Go, Java, .NET, PHP, Python y Ruby con comandos de instalación y repositorios de GitHub.
 icon: code-xml
 ---
 

es/api-reference/errors.mdx

@@ -0,0 +1,30 @@
+---
+title: Códigos de error
+description: Códigos de estado HTTP comunes de la API de Trophy.
+og:description: Códigos de estado HTTP comunes de la API de Trophy.
+icon: circle-x
+---
+
+Esta página resume los códigos de estado HTTP que verá con mayor frecuencia al integrar con la API de la aplicación Trophy. Para el comportamiento específico de cada endpoint y los esquemas de respuesta, consulte la [referencia de la API](/es/api-reference/introduction).
+
+## Errores de autenticación {#authentication-errors}
+
+| Estado | Cuándo ocurre | Qué hacer |
+| --- | --- | --- |
+| `401 Unauthorized` | Falta el encabezado `X-API-KEY` o no es válido | Cree o rote una clave de API de aplicación y verifique la configuración de [autenticación](/es/api-reference/authentication)|
+
+## Límite de solicitudes {#rate-limiting}
+
+| Estado | Cuándo ocurre | Qué hacer |
+| --- | --- | --- |
+| `429 Too Many Requests` | Su organización excedió los [Límites de velocidad](/es/api-reference/rate-limiting) del endpoint | Reduzca la frecuencia y reintente; solicite un límite más alto si es necesario |
+
+## Orientación para reintentos {#retry-guidance}
+
+- Reintente `429` y `5xx` con backoff exponencial.
+- Al reintentar, envíe la misma clave de idempotencia para la misma acción lógica para que Trophy no cuente dos veces.
+- No reintente `401` hasta que se corrija la clave de API.
+
+## Obtener soporte {#get-support}
+
+¿Quiere ponerse en contacto con el equipo de Trophy? Comuníquese con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar!

es/api-reference/introduction.mdx

@@ -1,40 +1,50 @@
 ---
 title: Introducción
-description: Aprende sobre la API de Trophy y comienza a construir tu integración.
-subtitle: Aprende sobre la API de Trophy y comienza a construir tu integración.
+description: Autentíquese, gestione errores y límites de velocidad, utilice
+  idempotencia y explore los SDK de la API de la aplicación Trophy.
+subtitle: Aprenda sobre la API de Trophy y comience a desarrollar su integración.
 ---
-La API de aplicaciones de Trophy es un conjunto de endpoints que proporcionan interfaces simples para crear experiencias de gamificación y cubre toda la gama de acciones que un usuario final de tu aplicación puede realizar.
 
-No incluye funciones administrativas globales ni acciones que solo deberían ser realizadas por tus sistemas internos. Si buscas funcionalidad administrativa, consulta la [API de administración](/es/admin-api/introduction).
+La API de la aplicación Trophy es un conjunto de endpoints que proporcionan interfaces simples para construir experiencias de gamificación y cubre toda la gama de acciones que un usuario final de su aplicación puede realizar.
 
-La API de aplicaciones es accesible a través de [SDKs](/es/api-reference/client-libraries) disponibles en la mayoría de los lenguajes de programación principales o, para quienes deseen gestionar sus propios clientes HTTP, está disponible en la siguiente URL base.
+No incluye funciones administrativas globales ni acciones que solo deben ser realizadas por sus sistemas internos. Si busca funcionalidad administrativa, consulte la [API de administración](/es/admin-api/introduction).
+
+La API de la aplicación es accesible a través de [SDK](/es/api-reference/client-libraries) disponibles en la mayoría de los principales lenguajes de programación o, para aquellos que deseen gestionar sus propios clientes HTTP, está disponible en la siguiente URL base.
 
 ```bash Base URL
 https://api.trophy.so/v1
 ```
 
+<Tip>
 La referencia completa de la API está disponible públicamente en [/openapi](https://api.trophy.so/v1/openapi).
+</Tip>
 
-## Comienza {#get-started}
+## Comience {#get-started}
 
-Aprende más sobre cómo integrar la API de aplicaciones de Trophy a continuación.
+Aprenda más sobre cómo integrar con la API de la aplicación Trophy a continuación.
 
 <CardGroup>
   <Card title="Autenticación" icon="key" href="/es/api-reference/authentication">
-    Integra de forma segura tus aplicaciones con la API de Trophy utilizando claves de API.
+    Autentíquese con claves de API de aplicación con alcance de usuario o claves de API de administración a nivel de cuenta.
   </Card>
   <Card
     title="Límite de solicitudes"
     icon="circle-gauge"
     href="/es/api-reference/rate-limiting"
   >
-    Aprende sobre la API de Trophy y la Límite de solicitudes de solicitudes.
+    Aprenda sobre la API de Trophy y el límite de solicitudes.
+  </Card>
+  <Card title="Idempotencia" icon="repeat" href="/es/api-reference/idempotency">
+    Aprenda cómo prevenir efectos secundarios no deseados al reintentar solicitudes.
+  </Card>
+  <Card title="Errores" icon="circle-exclamation" href="/es/api-reference/errors">
+    Códigos de estado HTTP comunes para autenticación, límites de velocidad y eventos métricos.
   </Card>
-  <Card title="SDKs" icon="code-xml" href="/es/api-reference/client-libraries">
-    Utiliza los SDKs con tipado seguro de Trophy para integrar con la API.
+  <Card title="SDK" icon="code-xml" href="/es/api-reference/client-libraries">
+    Use los SDK de tipo seguro de Trophy para integrar con la API.
   </Card>
 </CardGroup>
 
-## Obtener soporte {#get-support}
+## Obtenga soporte {#get-support}
 
-¿Quieres ponerte en contacto con el equipo de Trophy? Comunícate con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
+¿Desea ponerse en contacto con el equipo de Trophy? Comuníquese con nosotros por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudar!

es/getting-started/introduction.mdx

@@ -1,46 +1,152 @@
 ---
 title: Bienvenido a Trophy
-description: Documentación de Trophy para APIs de gamificación, guías de inicio
-  rápido y tutoriales.
+description: Trophy es la capa de gamificación para aplicaciones de consumo.
+  Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK
+  prediseñadas de Trophy.
+og:description: Trophy es la capa de gamificación para aplicaciones de consumo.
+  Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK
+  prediseñadas de Trophy.
 ---
 
-Trophy es un conjunto de herramientas fácil de usar para desarrolladores que permite crear experiencias de producto gamificadas en cualquier aplicación móvil o web.
+import SdkInstallCommand from "../../snippets/sdk-install-command.mdx";
+import VerifiedFirstEvent from "../../snippets/verified-first-event.mdx";
+import MetricChangeResponseBlock from "../../snippets/metric-change-response-block.mdx";
 
-Facilita la creación de funciones como [Logros](/es/features/achievements), [Rachas](/es/features/streaks), [Puntos](/es/features/points) y [Clasificaciones](/es/features/leaderboards) con solo unas pocas líneas de código, y puede enviar [correos electrónicos](/es/features/emails) y [Notificaciones push](/es/features/push-notifications) gamificados para aumentar tu retención y engagement.
+Trophy es la capa de gamificación para aplicaciones de consumo. Crea puntos, logros, rachas y clasificaciones en minutos con las API y SDK prediseñadas de Trophy.
+
+## Primeros pasos {#getting-started}
+
+Instala un SDK de Trophy para rastrear la actividad de los usuarios y potenciar puntos, logros, rachas y clasificaciones en tu aplicación.
+
+<SdkInstallCommand />
+
+<CardGroup cols={3}>
+  <Card title="Inicio rápido" icon="circle-play" href="/es/getting-started/quickstart">
+    Configura una cuenta de Trophy y crea tu primera funcionalidad en cinco minutos.
+  </Card>
+  <Card title="Usa la API REST" icon="code" href="/es/api-reference/introduction">
+    Aprende a usar la API REST para integrar Trophy en tu aplicación.
+  </Card>
+  <Card
+    title="Ver un ejemplo completo"
+    icon="github"
+    href="https://github.com/trophyso/example-study-platform/tree/demo"
+  >
+    Aplicación de ejemplo completa con un stack de gamificación completo usando Trophy.
+  </Card>
+</CardGroup>
+
+## Uso de agentes de IA {#using-ai-agents}
+
+Conecta los servidores MCP de Trophy para que los agentes puedan leer documentación en tiempo real y configurar tu cuenta durante la integración.
+
+<Tip>
+Se recomienda usar los servidores MCP de Trophy para una experiencia de configuración y desarrollo más rápida.
+</Tip>
+
+<CardGroup cols={3}>
+  <Card title="MCP de documentación" icon="book-open" href="/es/mcp/docs-mcp-server/introduction">
+    Búsqueda de documentación en tiempo real para agentes de IA.
+  </Card>
+  <Card title="MCP de cuenta" icon="cog" href="/es/mcp/account-mcp-server/introduction">
+    Configura tu cuenta de Trophy usando agentes de IA.
+  </Card>
+  <Card title="Mejores prácticas" icon="circle-check" href="/es/mcp/best-practice">
+    Configuración recomendada para usar ambos servidores MCP juntos.
+  </Card>
+</CardGroup>
+
+## Envía tu primer evento {#send-your-first-event}
+
+Todas las funciones de gamificación están impulsadas por [eventos de métricas](/es/features/events). Aquí te mostramos cómo enviar tu primer evento usando un SDK de Trophy:
+
+<VerifiedFirstEvent />
+
+La respuesta incluye los cambios en el estado de gamificación como resultado del evento, incluyendo:
+- El nuevo valor total de la métrica del usuario
+- Cualquier logro desbloqueado recientemente
+- Nuevos totales de Puntos y recompensas
+- Un objeto de Racha actualizado
+- Cualquier nueva posición en las Clasificaciones
+
+Usa esta respuesta para reaccionar a los cambios en el estado de gamificación del usuario e impulsar elementos de UI.
+
+<MetricChangeResponseBlock />
+
+## Construye según el caso de uso {#build-by-use-case}
+
+Para obtener más información sobre cómo construir funciones de gamificación comunes usando Trophy, consulta las siguientes guías:
 
 <CardGroup>
-  <Card title="Conceptos de Trophy" icon="book-open" href="/es/features">
-    Familiarízate con el modelo mental de gamificación en Trophy.
+  <Card title="Logros" icon="trophy" href="/es/guides/how-to-build-an-achievements-feature">
+    Desbloquea logros a partir del progreso o acciones únicas.
+  </Card>
+    <Card title="Rachas" icon="flame" href="/es/guides/how-to-build-a-streaks-feature">
+    Impulsa ciclos de hábitos diarios o semanales con detección de zona horaria integrada.
+  </Card>
+  <Card title="Puntos" icon="sparkle" href="/es/guides/how-to-build-an-xp-feature">
+    Otorga puntos desde acciones dentro de la aplicación y configura niveles e impulsos.
   </Card>
   <Card
-    title="Inicio rápido"
-    icon="circle-play"
-    href="/es/getting-started/quickstart"
+    title="Clasificaciones"
+    icon={
+      <svg
+        width="20"
+        height="18"
+        viewBox="0 0 20 18"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+        className="text-primary dark:text-primary-light"
+      >
+        <path
+          d="M2 16H6V8H2V16ZM8 16H12V2H8V16ZM14 16H18V10H14V16ZM0 16V8C0 7.45 0.195833 6.97917 0.5875 6.5875C0.979167 6.19583 1.45 6 2 6H6V2C6 1.45 6.19583 0.979167 6.5875 0.5875C6.97917 0.195833 7.45 0 8 0H12C12.55 0 13.0208 0.195833 13.4125 0.5875C13.8042 0.979167 14 1.45 14 2V8H18C18.55 8 19.0208 8.19583 19.4125 8.5875C19.8042 8.97917 20 9.45 20 10V16C20 16.55 19.8042 17.0208 19.4125 17.4125C19.0208 17.8042 18.55 18 18 18H2C1.45 18 0.979167 17.8042 0.5875 17.4125C0.195833 17.0208 0 16.55 0 16Z"
+          fill="currentColor"
+        />
+      </svg>
+    }
+    href="/es/guides/how-to-build-a-leaderboards-feature"
   >
-    Integra Trophy en tu backend en menos de 10 minutos.
+    Crea clasificaciones recurrentes o únicas.
   </Card>
-  <Card title="Guías" icon="rocket" href="/es/guides">
-    Usa Trophy para crear soluciones prácticas a casos de uso comunes de gamificación.
+  <Card title="Correos electrónicos" icon="mail" href="/es/features/emails">
+    Correos electrónicos del ciclo de vida impulsados por rachas, logros y actividad.
   </Card>
-  <Card title="Referencia del API" icon="code" href="/es/api-reference">
-    Explora el API de Trophy y descubre lo que es posible.
+  <Card title="Notificaciones push" icon="bell" href="/es/features/push-notifications">
+    Flujos de notificaciones automatizadas usando datos de gamificación.
   </Card>
 </CardGroup>
 
-## Por qué Trophy {#why-trophy}
+## Kit de interfaz de usuario {#ui-kit}
+
+Implementa interfaces de gamificación más rápido con la biblioteca de componentes React de Trophy, construida sobre shadcn/ui y diseñada para trabajar con las estructuras de datos de Trophy.
+
+<Card title="Kit de interfaz de usuario" icon="shapes" href="https://ui.trophy.so">
+  Explora componentes de interfaz preconstruidos para rachas, logros, clasificaciones, puntos y más.
+</Card>
+
+## Lista de verificación de producción {#production-checklist}
 
-<Frame>
-  <img height="200" width="100%" noZoom src="https://trophy.so/opengraph-image" />
-</Frame>
+Antes de implementar tu integración en producción, revisa los pasos recomendados en la lista de verificación de producción:
 
-Si tu objetivo es que tus usuarios creen un hábito regular de usar tu aplicación —para aprender algo, publicar contenido o incluso hacer ejercicio— la gamificación podría ser para ti.
+<Card title="Lista de verificación de producción" icon="list-check" href="/es/getting-started/production-checklist">
+  Pasos recomendados para asegurar que tu integración esté lista para producción.
+</Card>
 
-Ha sido comprobado por Duolingo y otros que la gamificación aumenta predeciblemente la retención e incrementa el engagement en la plataforma.
+## Precios {#pricing}
 
-Pero construir gamificación a escala puede ser complicado. Tienes una base de usuarios global, todos en diferentes zonas horarias, todos con diferentes patrones de uso que necesitan ser medidos y optimizados en tiempo real. Además, quieres ejecutar experimentos para probar diferentes enfoques y ver cómo impactan la retención, pero esto requiere cambios constantes en el código, lo que retrasa el trabajo en tu producto principal.
+Trophy mide el uso por **usuarios activos mensuales (MAU)**. Un MAU es un usuario que envía al menos un [evento de métrica](/es/features/events) en un mes calendario determinado. No se te cobra por usuarios abandonados que dejan de enviar eventos.
 
-Trophy elimina el trabajo pesado involucrado en crear funciones como logros, rachas, sistemas de puntos y clasificaciones, al mismo tiempo que proporciona APIs confiables y escalables para lanzar experiencias de gamificación más rápido que construyéndolas internamente. Además, ofrece una plataforma web para configurar, medir y experimentar fácilmente con la experiencia del producto sin cambios constantes en el código.
+El nivel gratuito incluye **1,000 MAU**. Los planes de pago comienzan en $25/mes con cargos por excedente.
+
+<CardGroup cols={2}>
+  <Card title="Facturación" icon="gauge" href="/es/account/billing">
+    Nivel gratuito, planes de pago, asignaciones y excedentes.
+  </Card>
+  <Card title="Calculadora de precios" icon="calculator" href="https://trophy.so/pricing">
+    Obtén un estimado de costos mensuales según el uso esperado.
+  </Card>
+</CardGroup>
 
-## Obtener soporte {#get-support}
+## Obtén soporte {#get-support}
 
-¿Quieres ponerte en contacto con el equipo de Trophy? Escríbenos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
+¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!