diff --git a/.cursor/rules/localization-workflow.mdc b/.cursor/rules/localization-workflow.mdc
index 6cba1e6..08be1c0 100644
--- a/.cursor/rules/localization-workflow.mdc
+++ b/.cursor/rules/localization-workflow.mdc
@@ -9,8 +9,8 @@ alwaysApply: true
 - Keep all locale navigation in `docs.json` under `navigation.languages`; do not reintroduce `navigation.global` or top-level `navbar`.
 - Keep SEO metatags in English unless explicitly requested otherwise.
 - Do not translate code snippets, inline code, URLs, route slugs, or API identifiers.
-- Shared media lives under repo-root `assets/`. Default-language pages are at repo-root section paths (for example `<section>/<page>.mdx`) and targets are under locale directories (for example `es/<section>/<page>.mdx`), so relative `src` paths must account for each file depth. `scripts/localize-internal-links.mjs` rewrites markdown `](/...)` and JSX `href="/..."` only: for target locales, bare paths get that locale prefix and paths prefixed with another locale are re-prefixed to the active locale; for source/default processing, locale prefixes are stripped back to root paths. It does not change media `src` or snippet imports.
-- `scripts/localize-component-imports.mjs` rewrites MDX import paths that reference `<locale>/components/*.jsx` so each locale page imports its own locale components (for whichever locale is being processed).
+- Shared media lives under repo-root `assets/`. Default-language pages are at repo-root section paths (for example `<section>/<page>.mdx`) and targets are under locale directories (for example `es/<section>/<page>.mdx`), so relative `src` paths need one more `../` under each locale segment than in English. `scripts/localize-internal-links.mjs` rewrites markdown `](/...)` and JSX `href="/..."` only (absolute navigation paths). Relative repo-root `assets/` `src` and MDX `import` paths are normalized by `scripts/localize-mdx-paths.mjs` after Lingo.
+- `scripts/localize-mdx-paths.mjs` rewrites: `<locale>/components/*.jsx` for the active locale; `from ".../snippets/..."`; and JSX `src=".../assets/..."` so `../` depth matches the file’s path. Run after Lingo in `translate:generate` and translate-on-main; CI checks via `translate:localize-mdx-paths:check`.
 - Shared MDX snippets live under repo-root `snippets/` (not per-locale). Import with relative paths from each page; do not add shared MDX snippets to Lingo `i18n.json` buckets unless you intend to translate them.
 - Locale-aware React components that can contain text live under `components/*.jsx` for default language and `<locale>/components/*.jsx` for targets, and are manually maintained per locale (do not add them to Lingo `i18n.json` buckets; do not keep these in shared `snippets/`).
 - Keep a **single** OpenAPI document at repo-root `openapi.yml` (not under `en/` or `es/`). Endpoint and webhook MDX must use Mintlify’s form `openapi: openapi.yml <method> <path>` or `openapi: openapi.yml webhook <eventKey>`. Do not translate the `openapi:` line.
diff --git a/.github/workflows/translate-on-main.yml b/.github/workflows/translate-on-main.yml
index 956e849..f2e1b03 100644
--- a/.github/workflows/translate-on-main.yml
+++ b/.github/workflows/translate-on-main.yml
@@ -70,8 +70,8 @@ jobs:
             node scripts/translate-docs-json.mjs --target "$locale"
             echo "Localizing internal links for $locale"
             node scripts/localize-internal-links.mjs --target "$locale"
-            echo "Localizing component imports for $locale"
-            node scripts/localize-component-imports.mjs --target "$locale"
+            echo "Localizing MDX paths (components, snippets, assets) for $locale"
+            node scripts/localize-mdx-paths.mjs --target "$locale"
           done
 
       - name: Sync Mintlify heading anchors
diff --git a/.github/workflows/validate-translations.yml b/.github/workflows/validate-translations.yml
index d78c7bd..cb9ce9c 100644
--- a/.github/workflows/validate-translations.yml
+++ b/.github/workflows/validate-translations.yml
@@ -54,8 +54,8 @@ jobs:
       - name: Ensure internal links are locale-localized
         run: npm run translate:localize-links:check
 
-      - name: Ensure component imports are locale-localized
-        run: npm run translate:localize-component-imports:check
+      - name: Ensure localized MDX paths are correct
+        run: npm run translate:localize-mdx-paths:check
 
       - name: Ensure fragile link fragments are not used
         run: npm run translate:validate-links
diff --git a/README.md b/README.md
index 7e4e8d0..e00077b 100644
--- a/README.md
+++ b/README.md
@@ -59,11 +59,11 @@ Notes:
 - `lingo/glossary.csv`: Terms that must stay fixed or use specific translations.
 - `lingo/brand-voice.md`: Single brand voice used for all locales.
 - `scripts/translate-docs-json.mjs`: Translates language-specific `docs.json` navigation labels directly in the source-of-truth `docs.json`. Prefer `npm run translate:docs-json -- --target <locale>`.
-- `scripts/localize-internal-links.mjs`: Rewrites internal absolute **navigation** links in each locale’s MDX for whatever locale is being processed (`--target`, `--all`, or default targets): bare paths get that locale’s prefix (e.g. `/platform/points` → `/es/platform/points` when processing `es/`), and any path already prefixed with **another** locale from `i18n.json` (`en`, `es`, future `fr`, etc.) is re-prefixed to the active locale (so `/en/...` or stale `/es/...` on a `fr/` page become `/fr/...`). Longer codes are matched first (e.g. `en-US` before `en`). It does **not** change relative image or video `src` paths, MDX/JSX **import** paths, or shared **MDX snippets**; those must be correct in source so all locales stay aligned. Prefer `npm run translate:localize-links --` with `--target`, `--all`, or `--all --check`.
-- `scripts/localize-component-imports.mjs`: Rewrites MDX `import ... from ".../<locale>/components/...jsx"` paths so they match the active locale being processed (`--target`, `--all`, or default targets). This keeps locale pages importing locale-local components after PIT/CI translation.
+- `scripts/localize-internal-links.mjs`: Rewrites internal absolute **navigation** links in each locale’s MDX for whatever locale is being processed (`--target`, `--all`, or default targets): bare paths get that locale’s prefix (e.g. `/platform/points` → `/es/platform/points` when processing `es/`), and any path already prefixed with **another** locale from `i18n.json` (`en`, `es`, future `fr`, etc.) is re-prefixed to the active locale (so `/en/...` or stale `/es/...` on a `fr/` page become `/fr/...`). Longer codes are matched first (e.g. `en-US` before `en`). It does **not** change relative image or video `src` paths or MDX `import` paths (those are normalized by `scripts/localize-mdx-paths.mjs` after translation: components, `snippets/`, and repo-root `assets/`). Prefer `npm run translate:localize-links --` with `--target`, `--all`, or `--all --check`.
+- `scripts/localize-mdx-paths.mjs`: Rewrites MDX paths for locale docs: (1) `.../<locale>/components/...jsx` for the active locale, (2) `import ... ".../snippets/..."` depth to repo-root `snippets/`, and (3) JSX `src=".../assets/..."` depth to repo-root `assets/` (Lingo copies English relative paths). Use `--target`, `--all`, or default targets; `translate:generate` and translate-on-main run it after Lingo.
 - **Shared MDX snippets (`snippets/*.mdx`)**: Reusable MDX blocks stay in repo-root `snippets/` (not per-locale). Import them with relative paths from each page (for example `../../snippets/foo.mdx` from `locale/<section>/<page>.mdx`, or more `../` segments for deeper pages). They are excluded from Lingo buckets in `i18n.json` so they stay English and identical everywhere.
 - **Localized React components (`components/*.jsx` for default language, `<locale>/components/*.jsx` for targets)**: UI components that can contain locale text are stored per locale (for example `components/rate-limit-badge.jsx`, `es/components/rate-limit-badge.jsx`) and manually maintained per locale (not translated by PIT/CI automation).
-- **Media paths**: Default-language pages live at repo root paths like `<section>/<page>.mdx` and target locales live under `<locale>/<section>/<page>.mdx`; shared files sit in repo-root `assets/`. Keep relative media paths correct for each file depth.
+- **Media paths**: Default-language pages live at repo root paths like `<section>/<page>.mdx` and target locales live under `<locale>/<section>/<page>.mdx`; shared files sit in repo-root `assets/`. Prefer relative `src="../assets/..."` (or more `../`) from English source; `scripts/localize-mdx-paths.mjs` rewrites `assets/` `src` depth for each target locale file.
 - **`openapi.yml`**: One OpenAPI 3.1 spec at the **repository root** (alongside `docs.json`). API and webhook pages reference it explicitly in frontmatter, for example `openapi: openapi.yml get /users/{id}` or `openapi: openapi.yml webhook points.changed`. Do not duplicate the YAML under locale folders; Lingo must not alter `openapi:` lines.
 - **`scripts/sync-openapi-titles.mjs`**: Copies each operation/webhook **`summary`** from `openapi.yml` into the English page’s **`title:`** frontmatter (Mintlify’s default when `title` is omitted). Target locales get an English `title` only if missing (bootstrap); run **`npm run translate:generate`** so Lingo translates those titles. Runs automatically at the start of `translate:generate` and in translate-on-main before Lingo.
 - `scripts/sync-heading-anchors.mjs`: Writes Mintlify [custom heading IDs](https://www.mintlify.com/docs/create/text#custom-heading-ids) as **`## Title {#slug}`** markdown. Slugs match Mintlify’s auto rules from the **English** title so hashes like `#pro-plan` stay stable across locales. Run `npm run translate:sync-anchors` after bulk heading edits; translation pipelines run it automatically (see **Heading anchors and Lingo** below). The script can also migrate one-line **`<h2 id="slug">…</h2>`** left from older tooling back to `{#slug}` syntax.
@@ -82,13 +82,13 @@ Use `npm run <script> -- <args>` when a script needs CLI flags (the `--` forward
 
 | Script | Purpose |
 | --- | --- |
-| `translate:generate` | Run Lingo for target locale(s), then `docs.json` labels, internal link localization, and heading-anchor sync. Requires `.env` with `LINGO_*` vars. |
+| `translate:generate` | Run Lingo for target locale(s), then `docs.json` labels, internal links, `translate:localize-mdx-paths`, and heading-anchor sync. Requires `.env` with `LINGO_*` vars. |
 | `translate:docs-json` | Translate `docs.json` nav for one `--target` locale. Requires `.env`. |
 | `translate:localize-links` | Localize internal `href` paths; pass `--target`, `--all`, and/or `--check`. |
 | `translate:localize-links:all` | Same as `translate:localize-links -- --all`. |
 | `translate:localize-links:check` | CI-style check: all locales, no writes (`--all --check`). |
-| `translate:localize-component-imports` | Localize MDX imports that reference `<locale>/components/*.jsx` to the active locale. |
-| `translate:localize-component-imports:check` | CI-style check: fail if any MDX imports point at another locale’s components. |
+| `translate:localize-mdx-paths` | Fix localized MDX paths: locale `components/` imports, `snippets/` import depth, relative `assets/` `src` depth. |
+| `translate:localize-mdx-paths:check` | CI-style check: fail if any of the above is wrong for its locale/path. |
 | `translate:sync-anchors` | Apply English-derived `{#slug}` on default-language root MDX and target locales (see `i18n.json` `locale.targets`). |
 | `translate:sync-anchors:check` | Fail if any MDX needs re-sync (CI). |
 | `translate:sync-openapi-titles` | Set default-language API & webhook `title:` from `openapi.yml` summaries; bootstrap missing target `title` from English. |
diff --git a/es/getting-started/quickstart.mdx b/es/getting-started/quickstart.mdx
index 3bafc6e..df58058 100644
--- a/es/getting-started/quickstart.mdx
+++ b/es/getting-started/quickstart.mdx
@@ -7,122 +7,343 @@ og:description: Sigue esta guía de inicio rápido para integrar Trophy en tu
 
 import SdkInstallCommand from "../../snippets/sdk-install-command.mdx";
 import AddEnvVarBlock from "../../snippets/add-env-var-block.mdx";
+import TrophyClientInitBlock from "../../snippets/trophy-client-init-block.mdx";
 import MetricChangeRequestBlock from "../../snippets/metric-change-request-block.mdx";
 import MetricChangeResponseBlock from "../../snippets/metric-change-response-block.mdx";
 
 Aquí integrarás tu aplicación web backend con Trophy y comenzarás a construir tu primera función gamificada.
 
-<Steps>
-  <Step title="Crea tu cuenta de Trophy">
-    Primero, [crea una nueva cuenta](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) si aún no tienes una y dirígete al [panel de Trophy](https://app.trophy.so).
+<Tabs>
+  <Tab title="Lo haré yo mismo" icon="user">
+    Estas instrucciones son para quienes desean implementar Trophy manualmente. Si prefieres usar agentes de codificación, cambia de pestaña arriba.
+    
+    <Steps>
+      <Step title="Crea tu cuenta de Trophy">
+        Primero, [crea una cuenta nueva](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) si aún no tienes una y accede al [panel de Trophy](https://app.trophy.so).
 
-    Añade la información de tu app para configurar tu cuenta
+        Completa la incorporación para configurar tu cuenta.
 
-  </Step>
-  <Step title="Añade el SDK de Trophy a tu backend">
-    Tenemos bibliotecas SDK disponibles en la mayoría de los principales lenguajes de programación, pero si no ves el tuyo en la lista, ¡háznoslo saber y crearemos uno!
+      </Step>
+      <Step title="Añade el SDK de Trophy a tu backend">
+        Tenemos bibliotecas SDK disponibles en la mayoría de los principales lenguajes de programación, pero si no ves el tuyo en la lista, ¡háznoslo saber y crearemos uno!
 
-    <SdkInstallCommand />
+        <SdkInstallCommand />
 
-    Alternativamente, puedes llamar directamente a la API usando cualquier biblioteca HTTP del lado del servidor.
+        Alternativamente, puedes llamar directamente a la API usando cualquier cliente HTTP del lado del servidor.
 
-  </Step>
-  <Step title="Configura el entorno">
-    Añade tu clave API que creaste durante la incorporación (o [crea una nueva](https://app.trophy.so/integration)) como una variable de entorno en tu aplicación backend:
+      </Step>
+      <Step title="Configura el entorno">
+        Ve a la [página de integración](https://app.trophy.so/integration) del panel de Trophy y crea una nueva clave de API.
+        
+        Añade tu clave de API como variable de entorno en tu aplicación backend:
 
-    <AddEnvVarBlock />
+        <AddEnvVarBlock />
 
-    Asegúrate de pasar esta clave API al SDK de Trophy o a tu cliente API para autenticarte.
+        Luego inicializa el cliente de la API de Trophy en tu backend usando esa clave de API:
 
-  </Step>
-  <Step title="Crea tu primera métrica">
-    Todas las funciones de gamificación se basan en las interacciones del usuario. En Trophy, usas [Métricas](/es/platform/metrics) para definir y modelar esas interacciones y [Eventos](/es/platform/events) para rastrearlas.
-    
-    Aquí crearás tu primera métrica para comenzar. En el panel de Trophy, dirígete a la [página de métricas](https://app.trophy.so/metrics) y haz clic en el botón _Nueva Métrica_:
-
-    <Frame>
-      <video
-        autoPlay
-        muted
-        loop
-        playsInline
-        className="w-full aspect-video"
-        src="../../assets/platform/metrics/create_new_metric.mp4"
-      ></video>
-    </Frame>
-
-    Asigna un nombre a la métrica y pulsa _Guardar_.
-
-  </Step>
-  <Step title="Integra la métrica en tu backend">
-    Una vez creada la métrica, dirígete a la pestaña de configuración y copia su clave de referencia API única.
-
-    <Frame>
-      <video
-        autoPlay
-        muted
-        loop
-        playsInline
-        className="w-full aspect-video"
-        src="../../assets/quick-start/copy_metric_key.mp4"
-      ></video>
-    </Frame>
-
-    Para registrar un evento contra esta métrica cuando un usuario interactúa con tu producto, llama a la [API de evento de cambio de métrica](/es/api-reference/endpoints/metrics/send-a-metric-change-event), pasando los detalles del usuario que realizó la interacción. En este ejemplo, la clave de métrica sería `flashcards-flipped`:
-
-    <MetricChangeRequestBlock />
-
-    Al realizar esta llamada, le indicas a Trophy que un usuario específico realizó una interacción con tu producto. Como resultado, Trophy procesará automáticamente cualquier función de gamificación como logros o rachas que hayas configurado para la métrica.
-
-  </Step>
-  <Step title="Continúa construyendo tu experiencia de gamificación">
-    Con una métrica integrada en tu backend, estás listo para empezar a añadir funciones de gamificación a tu producto.
-    
-    Sigue los enlaces a continuación para obtener más información sobre cada función que puedes construir con Trophy:
-
-    <CardGroup>
-      <Card title="Logros" icon="trophy" href="/es/platform/achievements">
-        Recompensa a los usuarios por su progreso continuo o por realizar acciones específicas.
-      </Card>
-      <Card title="Rachas" icon="flame" href="/es/platform/streaks">
-        Motiva a los usuarios a desarrollar hábitos de uso regulares.
-      </Card>
-      <Card title="Puntos" icon="sparkle" href="/es/platform/points">
-        Construye sistemas de puntos sofisticados para recompensar y retener usuarios.
-      </Card>
-      <Card
-        title="Tablas de clasificación"
-        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/platform/leaderboards">
-        Crea competencias amistosas para aumentar la participación de los usuarios.
-      </Card>
-      <Card title="Correos electrónicos" icon="mail" href="/es/platform/emails">
-        Envía correos electrónicos personalizados del ciclo de vida a los usuarios en el momento perfecto.
-      </Card>
-      <Card title="Notificaciones push" icon="bell" href="/es/platform/push-notifications">
-        Impulsa flujos de notificaciones automatizadas utilizando datos de gamificación personalizados.
-      </Card>
-    </CardGroup>
-
-    O explora nuestra [referencia de API](/es/api-reference/introduction) para familiarizarte con lo que Trophy puede hacer.
-
-  </Step>
-</Steps>
-
-## Obtener Soporte {#get-support}
+        <TrophyClientInitBlock />
+
+        Asegúrate de que todas las llamadas al SDK de Trophy usen este cliente para la autenticación.
+      </Step>
+      <Step title="Crea tu primera métrica">
+        Todas las funciones de gamificación se basan en interacciones del usuario. En Trophy, usas [Métricas](/es/platform/metrics) para definir y modelar esas interacciones y [Eventos](/es/platform/events) para rastrearlas.
+        
+        Aquí crearás tu primera métrica para comenzar. En el panel de Trophy, dirígete a la [página de métricas](https://app.trophy.so/metrics) y pulsa el botón _Nueva métrica_:
+
+        <Frame>
+          <video
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="w-full aspect-video"
+            src="../../assets/platform/metrics/create_new_metric.mp4"
+          ></video>
+        </Frame>
+
+        Asigna un nombre a la métrica y haz clic en _Guardar_.
+
+      </Step>
+      <Step title="Integra la métrica en tu backend">
+        Una vez creada la métrica, ve a la pestaña de configuración y copia su clave de referencia única del API.
+
+        <Frame>
+          <video
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="w-full aspect-video"
+            src="../../assets/quick-start/copy_metric_key.mp4"
+          ></video>
+        </Frame>
+
+        Para rastrear un evento contra esta métrica cuando un usuario interactúa con tu producto, llama al [API de evento de cambio de métrica](/es/api-reference/endpoints/metrics/send-a-metric-change-event), pasando los detalles del usuario que realizó la interacción. En este ejemplo, la clave de la métrica sería `flashcards-flipped`:
+
+        <MetricChangeRequestBlock />
+
+        Al realizar esta llamada, le indicas a Trophy que un usuario específico interactuó con tu producto. Como resultado, Trophy procesará automáticamente cualquier función de gamificación como Logros o Rachas que hayas configurado contra la métrica.
+
+      </Step>
+      <Step title="Continúa construyendo tu experiencia de gamificación">
+        Con una métrica integrada en tu backend, estás listo para comenzar a agregar funciones de gamificación a tu producto.
+        
+        Sigue los enlaces a continuación para conocer más sobre cada función que puedes construir con Trophy:
+
+        <CardGroup>
+          <Card title="Logros" icon="trophy" href="/es/platform/achievements">
+            Recompensa a los usuarios por su progreso continuo o por realizar acciones específicas.
+          </Card>
+          <Card title="Rachas" icon="flame" href="/es/platform/streaks">
+            Motiva a los usuarios a desarrollar hábitos de uso regular.
+          </Card>
+          <Card title="Puntos" icon="sparkle" href="/es/platform/points">
+            Construye sistemas de puntos sofisticados para recompensar y retener usuarios.
+          </Card>
+          <Card
+            title="Tablas de clasificación"
+            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/platform/leaderboards">
+            Crea competencias amistosas para aumentar la participación de los usuarios.
+          </Card>
+          <Card title="Correos electrónicos" icon="mail" href="/es/platform/emails">
+            Envía correos electrónicos de ciclo de vida personalizados a los usuarios en el momento perfecto.
+          </Card>
+          <Card title="Notificaciones push" icon="bell" href="/es/platform/push-notifications">
+            Impulsa flujos de notificación automatizados usando datos de gamificación personalizados.
+          </Card>
+        </CardGroup>
+
+        O explora nuestra [referencia de API](/es/api-reference/introduction) para familiarizarte con lo que Trophy puede hacer.
+
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="Estoy usando IA" icon="bot">
+    Estas instrucciones son para quienes prefieren desarrollar usando agentes de codificación como Cursor y Claude Code.
+
+    <Steps>
+      <Step title="Crea tu cuenta de Trophy">
+        Primero, [crea una nueva cuenta](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) si aún no tienes una y dirígete al [panel de Trophy](https://app.trophy.so).
+
+        Completa la incorporación para configurar tu cuenta.
+      </Step>
+
+      <Step title="Configura Trophy MCP o Agent Skill">
+        Para la mejor experiencia de configuración con IA, conecta Trophy a través de MCP, Agent Skill, o ambos:
+
+        - URL del servidor MCP: `https://docs.trophy.so/mcp`
+        - URL de Agent Skill: `https://docs.trophy.so/skill.md`
+
+        <Tip>
+          MCP le da a tu agente acceso en vivo a la documentación de Trophy. Agent Skill le proporciona instrucciones estructuradas sobre las capacidades de Trophy. Usar ambos generalmente ofrece los mejores resultados.
+        </Tip>
+
+        <Tabs>
+          <Tab title="Claude">
+            1. Abre [Conectores de Claude](https://claude.ai/settings/connectors).
+            2. Selecciona **Agregar conector personalizado**.
+            3. Agrega:
+               - Nombre: `Trophy`
+               - URL: `https://docs.trophy.so/mcp`
+            4. En el chat, usa el botón de más para habilitar el conector de Trophy.
+            5. Opcional pero recomendado: agrega Trophy Agent Skill en la [configuración de Habilidades de Claude](https://claude.ai/customize/skills) usando `https://docs.trophy.so/skill.md` para que Claude use consistentemente el resumen de capacidades de Trophy.
+          </Tab>
+          <Tab title="Claude Code">
+            Agrega Trophy MCP:
+
+            ```bash
+            claude mcp add --transport http Trophy https://docs.trophy.so/mcp
+            ```
+
+            Verifica:
+
+            ```bash
+            claude mcp list
+            ```
+
+            Opcional: agrega Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+          <Tab title="Cursor">
+            Abre la configuración de MCP y agrega esto a tu `mcp.json`:
+
+            ```json
+            {
+              "mcpServers": {
+                "Trophy": {
+                  "url": "https://docs.trophy.so/mcp"
+                }
+              }
+            }
+            ```
+
+            Opcional: agrega Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+          <Tab title="VS Code">
+            Crea `.vscode/mcp.json`:
+
+            ```json
+            {
+              "servers": {
+                "Trophy": {
+                  "type": "http",
+                  "url": "https://docs.trophy.so/mcp"
+                }
+              }
+            }
+            ```
+
+            Opcional: agrega Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+        </Tabs>
+      </Step>
+      <Step title="Indica a tu agente que realice la configuración inicial">
+        Aquí hay un prompt que puedes usar con tu agente de codificación para realizar la configuración inicial de Trophy:
+
+        <Prompt
+          description="Realizar la configuración inicial de Trophy"
+          icon="paperclip"
+          iconType="solid"
+          actions={["copy", "cursor"]}
+        >
+          Estoy añadiendo gamificación a mi aplicación usando Trophy.
+
+          Antes de realizar cambios, verifica que el servidor MCP `Trophy` conectado o la Agent Skill estén disponibles y úsalos como la fuente principal de información para los detalles de integración de Trophy.
+
+          Por favor, realiza la configuración inicial completa de principio a fin:
+          1. Detecta el lenguaje/framework del backend en este repositorio e instala el SDK oficial de Trophy correspondiente (o usa llamadas HTTP si no hay SDK disponible).
+          2. Añade `TROPHY_API_KEY` a la configuración de entorno de forma segura (sin secretos comprometidos en git), e intégralo en la inicialización del cliente de Trophy.
+          3. Añade código para rastrear un evento de cambio de métrica para la métrica `<metric>` usando el cliente de API de Trophy, conectando todos los atributos de usuario requeridos como ID, y usando placeholders para todos los atributos opcionales como nombre, email y zona horaria.
+          4. Añade manejo básico de errores y logging alrededor de las llamadas a la API de Trophy.
+          5. Añade o actualiza una sección breve en el README explicando cómo funciona la integración y cómo extenderla.
+
+          Restricciones:
+          - Usa los resultados de la herramienta MCP de Trophy para todas las decisiones de implementación específicas de Trophy.
+          - Si el contexto de Agent Skill de Trophy está disponible en este entorno, síguelo.
+          - No dependas de memoria previa para el comportamiento de la API de Trophy cuando MCP o Agent proporcionen una respuesta.
+          - Mantén los secretos fuera del control de versiones.
+          - Usa los patrones y convenciones de nomenclatura existentes del proyecto.
+          - Muéstrame un resumen conciso de los archivos modificados y cómo probar la configuración.
+          - Sugiere los siguientes pasos basándote en las características de gamificación que Trophy soporta.
+        </Prompt>
+
+        <Note>
+          Asegúrate de reemplazar `<metric>` con la métrica que configuraste durante la incorporación.
+        </Note>
+
+        Esto hará lo siguiente:
+
+        1. Agregar el [SDK de Trophy](/es/api-reference/client-libraries) correspondiente a tu aplicación según tu stack tecnológico
+        2. Agregar una nueva variable `TROPHY_API_KEY` a la configuración de tu entorno
+        3. Agregar código para enviar eventos a Trophy basándose en la métrica que configuraste durante la incorporación.
+      </Step>
+      <Step title="Obtén tu clave API">
+        Una vez completada la configuración, [crea una clave API](https://app.trophy.so/integration) desde la página de integración del panel de Trophy y agrégala a tu entorno.
+      </Step>
+      <Step title="Construye tu primera función de gamificación">
+        Una vez completada la configuración inicial, utiliza este prompt de seguimiento para preparar tu agente para el siguiente paso y que te pregunte qué construir a continuación:
+
+        <Prompt
+          description="Construye tu primera función de gamificación"
+          icon="paperclip"
+          iconType="solid"
+          actions={["copy", "cursor"]}
+        >
+          Prepárate para continuar mi integración de Trophy desde la configuración existente.
+
+          Primero, verifica que el servidor MCP `Trophy` conectado o la habilidad del agente estén disponibles y utilízalos como fuente de referencia para los detalles de integración específicos de cada función.
+
+          Antes de implementar nada, pregúntame qué función de gamificación quiero construir, proporcionando opciones basadas en lo que el MCP de Trophy o la habilidad del agente indiquen que Trophy soporta.
+
+          Después de que elija una opción:
+          1. Implementa únicamente esa función seleccionada utilizando las APIs relevantes de Trophy y los patrones existentes del proyecto.
+          2. Agrega las llamadas/endpoints/acciones del lado del servidor necesarias que utilicen las APIs de Trophy y una interfaz de usuario mínima o superficie de respuesta de API.
+          3. Documenta cualquier nueva variable de entorno, ruta y pasos de uso.
+
+          Si solicito una función que Trophy no soporta, no implementes una solución alternativa.
+          En su lugar, infórmame que no está soportada actualmente y pídeme que contacte al soporte de Trophy en support@trophy.so para enviar una solicitud de función.
+
+          Mantén los cambios orientados a producción:
+          - Sigue la arquitectura existente y las convenciones de nomenclatura.
+          - Maneja los fallos de API de forma adecuada.
+          - Devuelve una lista clara de archivos modificados y pasos de verificación manual.
+        </Prompt>
+
+        Para ideas sobre qué construir a continuación, explora:
+
+        <CardGroup>
+          <Card title="Logros" icon="trophy" href="/es/platform/achievements">
+            Recompensa a los usuarios por su progreso continuo o por realizar acciones específicas.
+          </Card>
+          <Card title="Rachas" icon="flame" href="/es/platform/streaks">
+            Motiva a los usuarios a desarrollar hábitos de uso regulares.
+          </Card>
+          <Card title="Puntos" icon="sparkle" href="/es/platform/points">
+            Construye sistemas de puntos sofisticados para recompensar y retener usuarios.
+          </Card>
+          <Card
+            title="Tablas de clasificación"
+            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/platform/leaderboards">
+            Crea competencias amistosas para aumentar la participación de los usuarios.
+          </Card>
+          <Card title="Correos electrónicos" icon="mail" href="/es/platform/emails">
+            Envía correos electrónicos personalizados del ciclo de vida a los usuarios en el momento perfecto.
+          </Card>
+          <Card title="Notificaciones push" icon="bell" href="/es/platform/push-notifications">
+            Impulsa flujos de notificaciones automatizadas utilizando datos de gamificación personalizados.
+          </Card>
+        </CardGroup>
+
+        O explora nuestra [referencia de API](/es/api-reference/introduction) para familiarizarte con lo que Trophy puede hacer.
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+## Obtén soporte {#get-support}
 
 ¿Quieres ponerte en contacto con el equipo de Trophy? Contáctanos por [correo electrónico](mailto:support@trophy.so). ¡Estamos aquí para ayudarte!
diff --git a/getting-started/introduction.mdx b/getting-started/introduction.mdx
index 2d7ec2c..fdd0c98 100644
--- a/getting-started/introduction.mdx
+++ b/getting-started/introduction.mdx
@@ -8,6 +8,9 @@ Trophy is a developer-friendly toolkit for building gamified product experiences
 It makes building features like [Achievements](/platform/achievements), [Streaks](/platform/streaks), [Points](/platform/points) and [Leaderboards](/platform/leaderboards) simple with just a few lines of code, and can send gamified [Emails](/platform/emails) and [Push Notifications](/platform/push-notifications) to increase your retention and engagement.
 
 <CardGroup>
+  <Card title="Platform Concepts" icon="book-open" href="/platform">
+    Get familiar with the mental model of gamification in Trophy.
+  </Card>
   <Card
     title="Quick Start"
     icon="circle-play"
@@ -16,10 +19,7 @@ It makes building features like [Achievements](/platform/achievements), [Streaks
     Integrate Trophy into your backend in under 10 minutes.
   </Card>
   <Card title="Guides" icon="rocket" href="/guides">
-    Use Trophy to build practical solutions to common gamification use cases.
-  </Card>
-  <Card title="Platform" icon="box" href="/platform">
-    Learn the key concepts behind building gamification experiences with Trophy.
+    Use Trophy to build solutions to common gamification use cases.
   </Card>
   <Card title="API Reference" icon="code" href="/api-reference">
     Explore the Trophy API and see what's possible.
diff --git a/getting-started/quickstart.mdx b/getting-started/quickstart.mdx
index 94cd3c1..ebd791d 100644
--- a/getting-started/quickstart.mdx
+++ b/getting-started/quickstart.mdx
@@ -7,121 +7,342 @@ og:description: Follow this quick start guide to integrate Trophy into your
 
 import SdkInstallCommand from "../snippets/sdk-install-command.mdx";
 import AddEnvVarBlock from "../snippets/add-env-var-block.mdx";
+import TrophyClientInitBlock from "../snippets/trophy-client-init-block.mdx";
 import MetricChangeRequestBlock from "../snippets/metric-change-request-block.mdx";
 import MetricChangeResponseBlock from "../snippets/metric-change-response-block.mdx";
 
 Here you'll integrate your backend web application with Trophy and start building your first gamified feature.
 
-<Steps>
-  <Step title="Create your Trophy account">
-    First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) if you don't already have one and head into the [Trophy dashboard](https://app.trophy.so).
+<Tabs>
+  <Tab title="I'm doing this myself" icon="user">
+    These instructions are for those who want to implement Trophy by hand. If instead you prefer to use coding agents, switch tabs above.
+    
+    <Steps>
+      <Step title="Create your Trophy account">
+        First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) if you don't already have one and head into the [Trophy dashboard](https://app.trophy.so).
 
-    Head through onboarding to get your account set up.
+        Head through onboarding to get your account set up.
 
-  </Step>
-  <Step title="Add the Trophy SDK to your backend">
-    We have SDK libraries available in most major programming languages but if you don't see yours listed, let us know and we'll make one!
+      </Step>
+      <Step title="Add the Trophy SDK to your backend">
+        We have SDK libraries available in most major programming languages but if you don't see yours listed, let us know and we'll make one!
 
-    <SdkInstallCommand />
+        <SdkInstallCommand />
 
-    Alternatively, you can directly call the API using any server-side HTTP library.
+        Alternatively, you can directly call the API using any server-side HTTP client.
 
-  </Step>
-  <Step title="Set up environment">
-    Add your API key that you created during onboarding (or [create a new one](https://app.trophy.so/integration)) as an environment variable in your backend application:
+      </Step>
+      <Step title="Set up environment">
+        Head to the [integration page](https://app.trophy.so/integration) of the Trophy dashboard and create a new API key.
+        
+        Add your API key as an environment variable in your backend application:
 
-    <AddEnvVarBlock />
+        <AddEnvVarBlock />
 
-    Make sure to pass this API key to the Trophy SDK or to your API client to authenticate.
+        Then initialize the Trophy API client in your backend using that API key:
 
-  </Step>
-  <Step title="Create your first metric">
-    All gamification features are driven by user interactions. In Trophy, you use [Metrics](/platform/metrics) to define and model those interactions and [Events](/platform/events) to track them.
-    
-    Here you'll create your first metric to get started. In the Trophy dashboard, head into the [metrics page](https://app.trophy.so/metrics) and hit the _New Metric_ button:
-
-    <Frame>
-      <video
-        autoPlay
-        muted
-        loop
-        playsInline
-        className="w-full aspect-video"
-        src="../assets/platform/metrics/create_new_metric.mp4"
-      ></video>
-    </Frame>
-
-    Give the metric a name and hit _Save_.
-
-  </Step>
-  <Step title="Integrate the metric into your backend">
-    Once you've created your metric, head to the configure tab and copy it's unique API reference key.
-
-    <Frame>
-      <video
-        autoPlay
-        muted
-        loop
-        playsInline
-        className="w-full aspect-video"
-        src="../assets/quick-start/copy_metric_key.mp4"
-      ></video>
-    </Frame>
-
-    To track an event against this metric when a user interacts with your product, call the [metric change event API](/api-reference/endpoints/metrics/send-a-metric-change-event), passing along details of the user that made the interaction. In this example the metric key would be `flashcards-flipped`:
-
-    <MetricChangeRequestBlock />
-
-    By making this call, you're telling Trophy that a specific user made an interaction with your product. As a result, Trophy will process any gamification features like achievements or streaks that you've configured against the metric automatically.
-
-  </Step>
-  <Step title="Continue building your gamification experience">
-    With a metric integrated into your backend, you're ready to start adding gamification features to your product.
-    
-    Follow the links below to learn more about each feature you can build with Trophy:
-
-    <CardGroup>
-      <Card title="Achievements" icon="trophy" href="/platform/achievements">
-        Reward users for continued progress or taking specific actions.
-      </Card>
-      <Card title="Streaks" icon="flame" href="/platform/streaks">
-        Motivate users to build regular usage habits.
-      </Card>
-      <Card title="Points" icon="sparkle" href="/platform/points">
-        Build sophisticated points systems to reward and retain users.
-      </Card>
-      <Card
-        title="Leaderboards"
-        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="/platform/leaderboards">
-        Create friendly competitions to increase user engagement.
-      </Card>
-      <Card title="Emails" icon="mail" href="/platform/emails">
-        Deliver personalized lifecycle emails to users at the perfect moment.
-      </Card>
-      <Card title="Push Notifications" icon="bell" href="/platform/push-notifications">
-        Drive automated notification flows using personalized gamification data.
-      </Card>
-    </CardGroup>
-
-    Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
-
-  </Step>
-</Steps>
+        <TrophyClientInitBlock />
+
+        Make sure all Trophy SDK calls use this client for authentication.
+      </Step>
+      <Step title="Create your first metric">
+        All gamification features are driven by user interactions. In Trophy, you use [Metrics](/platform/metrics) to define and model those interactions and [Events](/platform/events) to track them.
+        
+        Here you'll create your first metric to get started. In the Trophy dashboard, head into the [metrics page](https://app.trophy.so/metrics) and hit the _New Metric_ button:
+
+        <Frame>
+          <video
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="w-full aspect-video"
+            src="../assets/platform/metrics/create_new_metric.mp4"
+          ></video>
+        </Frame>
+
+        Give the metric a name and hit _Save_.
+
+      </Step>
+      <Step title="Integrate the metric into your backend">
+        Once you've created your metric, head to the configure tab and copy it's unique API reference key.
+
+        <Frame>
+          <video
+            autoPlay
+            muted
+            loop
+            playsInline
+            className="w-full aspect-video"
+            src="../assets/quick-start/copy_metric_key.mp4"
+          ></video>
+        </Frame>
+
+        To track an event against this metric when a user interacts with your product, call the [metric change event API](/api-reference/endpoints/metrics/send-a-metric-change-event), passing along details of the user that made the interaction. In this example the metric key would be `flashcards-flipped`:
+
+        <MetricChangeRequestBlock />
+
+        By making this call, you're telling Trophy that a specific user made an interaction with your product. As a result, Trophy will process any gamification features like achievements or streaks that you've configured against the metric automatically.
+
+      </Step>
+      <Step title="Continue building your gamification experience">
+        With a metric integrated into your backend, you're ready to start adding gamification features to your product.
+        
+        Follow the links below to learn more about each feature you can build with Trophy:
+
+        <CardGroup>
+          <Card title="Achievements" icon="trophy" href="/platform/achievements">
+            Reward users for continued progress or taking specific actions.
+          </Card>
+          <Card title="Streaks" icon="flame" href="/platform/streaks">
+            Motivate users to build regular usage habits.
+          </Card>
+          <Card title="Points" icon="sparkle" href="/platform/points">
+            Build sophisticated points systems to reward and retain users.
+          </Card>
+          <Card
+            title="Leaderboards"
+            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="/platform/leaderboards">
+            Create friendly competitions to increase user engagement.
+          </Card>
+          <Card title="Emails" icon="mail" href="/platform/emails">
+            Deliver personalized lifecycle emails to users at the perfect moment.
+          </Card>
+          <Card title="Push Notifications" icon="bell" href="/platform/push-notifications">
+            Drive automated notification flows using personalized gamification data.
+          </Card>
+        </CardGroup>
+
+        Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
+
+      </Step>
+    </Steps>
+  </Tab>
+  <Tab title="I'm using AI" icon="bot">
+    These instructions are for those who prefer to develop using coding agents like Cursor and Claude Code.
+
+    <Steps>
+      <Step title="Create your Trophy account">
+        First, [create a new account](https://app.trophy.so/sign-up?utm_source=docs&utm_medium=quickstart) if you don't already have one and head into the [Trophy dashboard](https://app.trophy.so).
+
+        Head through onboarding to get your account set up.
+      </Step>
+
+      <Step title="Configure Trophy MCP or Agent Skill">
+        For the best AI setup experience, connect Trophy through MCP, Agent Skill, or both:
+
+        - MCP server URL: `https://docs.trophy.so/mcp`
+        - Agent skill URL: `https://docs.trophy.so/skill.md`
+
+        <Tip>
+          MCP gives your agent live access to Trophy docs. Agent Skill gives it structured instructions about Trophy capabilities. Using both usually gives the best results.
+        </Tip>
+
+        <Tabs>
+          <Tab title="Claude">
+            1. Open [Claude Connectors](https://claude.ai/settings/connectors).
+            2. Select **Add custom connector**.
+            3. Add:
+               - Name: `Trophy`
+               - URL: `https://docs.trophy.so/mcp`
+            4. In chat, use the plus button to enable the Trophy connector.
+            5. Optional but recommended: add Trophy Agent Skill in [Claude Skills settings](https://claude.ai/customize/skills) using `https://docs.trophy.so/skill.md` so Claude consistently uses Trophy's capability summary.
+          </Tab>
+          <Tab title="Claude Code">
+            Add Trophy MCP:
+
+            ```bash
+            claude mcp add --transport http Trophy https://docs.trophy.so/mcp
+            ```
+
+            Verify:
+
+            ```bash
+            claude mcp list
+            ```
+
+            Optional: add Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+          <Tab title="Cursor">
+            Open MCP settings and add this to your `mcp.json`:
+
+            ```json
+            {
+              "mcpServers": {
+                "Trophy": {
+                  "url": "https://docs.trophy.so/mcp"
+                }
+              }
+            }
+            ```
+
+            Optional: add Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+          <Tab title="VS Code">
+            Create `.vscode/mcp.json`:
+
+            ```json
+            {
+              "servers": {
+                "Trophy": {
+                  "type": "http",
+                  "url": "https://docs.trophy.so/mcp"
+                }
+              }
+            }
+            ```
+
+            Optional: add Trophy Agent Skill:
+
+            ```bash
+            npx skills add https://docs.trophy.so
+            ```
+
+          </Tab>
+        </Tabs>
+      </Step>
+      <Step title="Tell your agent to perform initial setup">
+        Here's a prompt you can use with your coding agent to perform initial Trophy setup:
+
+        <Prompt
+          description="Perform initial Trophy setup"
+          icon="paperclip"
+          iconType="solid"
+          actions={["copy", "cursor"]}
+        >
+          I'm adding gamification to my app using Trophy.
+
+          Before making changes, verify the connected `Trophy` MCP server or Agent Skill is available and use it as the primary source of truth for Trophy integration details.
+
+          Please do the full initial setup end-to-end:
+          1. Detect the backend language/framework in this repo and install the relevant official Trophy SDK (or use HTTP calls if no SDK is available).
+          2. Add `TROPHY_API_KEY` to environment config in a secure way (no secrets committed to git), and wire it into the Trophy client initialization.
+          3. Add code to track a metric change event for the metric `<metric>` using the Trophy API client, wiring all required user attributes like ID, and using placeholders for all optional attributes like name, email and tz.
+          4. Add basic error handling and logging around Trophy API calls.
+          5. Add or update a short README section explaining how the integration works and how to extend it.
+
+          Constraints:
+          - Use Trophy MCP tool results for all Trophy-specific implementation decisions.
+          - If Trophy Agent Skill context is available in this environment, follow it.
+          - Do not rely on prior memory for Trophy API behavior when MCP or Agent provides an answer.
+          - Keep secrets out of source control.
+          - Use existing project patterns and naming conventions.
+          - Show me a concise summary of changed files and how to test the setup.
+          - Suggest next steps based on the gamification features Trophy supports.
+        </Prompt>
+
+        <Note>
+          Make sure to replace `<metric>` with the metric you set up during onboarding.
+        </Note>
+
+        This will:
+
+        1. Add the relevant [Trophy SDK](/api-reference/client-libraries) to your app based on your tech stack
+        2. Add a new `TROPHY_API_KEY` variable to your environment settings
+        3. Add code to send events to Trophy based on the metric you set up during onboarding.
+      </Step>
+      <Step title="Grab your API key">
+        Once the set up is complete, [create an API key](https://app.trophy.so/integration) from the integration page of the Trophy dashboard and add it to your environment.
+      </Step>
+      <Step title="Build your first gamification feature">
+        Once initial setup is complete, use this follow-up prompt to prepare your agent for the next step and have it ask you what to build next:
+
+        <Prompt
+          description="Build your first gamification feature"
+          icon="paperclip"
+          iconType="solid"
+          actions={["copy", "cursor"]}
+        >
+          Prepare to continue my Trophy integration from the existing setup.
+
+          First, verify the connected `Trophy` MCP server or Agent skill is available and use it as the source of truth for feature-specific integration details.
+
+          Before implementing anything, ask me which gamification feature I want to build, providing options based on what the Trophy MCP or Agent Skill says Trophy supports.
+
+          After I choose one option:
+          1. Implement only that selected feature using the relevant Trophy APIs and existing project patterns.
+          2. Add the required server-side calls/endpoints/actions that use Trophy APIs and a minimal UI or API response surface.
+          3. Document any new env vars, routes, and usage steps.
+
+          If I ask for a feature Trophy does not support, do not implement a workaround.
+          Instead, tell me it's not currently supported and ask me to contact Trophy support at support@trophy.so to submit a feature request.
+
+          Keep changes production-minded:
+          - Follow existing architecture and naming conventions.
+          - Handle API failures gracefully.
+          - Return a clear list of changed files and manual verification steps.
+        </Prompt>
+
+        For ideas on what to build next, explore:
+
+        <CardGroup>
+          <Card title="Achievements" icon="trophy" href="/platform/achievements">
+            Reward users for continued progress or taking specific actions.
+          </Card>
+          <Card title="Streaks" icon="flame" href="/platform/streaks">
+            Motivate users to build regular usage habits.
+          </Card>
+          <Card title="Points" icon="sparkle" href="/platform/points">
+            Build sophisticated points systems to reward and retain users.
+          </Card>
+          <Card
+            title="Leaderboards"
+            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="/platform/leaderboards">
+            Create friendly competitions to increase user engagement.
+          </Card>
+          <Card title="Emails" icon="mail" href="/platform/emails">
+            Deliver personalized lifecycle emails to users at the perfect moment.
+          </Card>
+          <Card title="Push Notifications" icon="bell" href="/platform/push-notifications">
+            Drive automated notification flows using personalized gamification data.
+          </Card>
+        </CardGroup>
+
+        Or, explore our [API reference](/api-reference/introduction) to get familiar with what Trophy can do.
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
 
 ## Get Support {#get-support}
 
diff --git a/i18n.lock b/i18n.lock
index 9740af2..5eeebe0 100644
--- a/i18n.lock
+++ b/i18n.lock
@@ -451,7 +451,7 @@ checksums:
     meta/description: 2e8b0385f2d1f523725686f68c6c1bd7
     content/0: 1afd0e053c8f9915148f7daa14eb2294
     content/1: cd9868df10aeab9a65622e4e07447f88
-    content/2: d311b7b7c2ccd335cc891f7023366275
+    content/2: 36f323be8397fab5c215a536cc36436a
     content/3: eadf663b83d7e238fbbaee0881e970e9
     content/4: 07d724e6a11c44e010a8095607c5ac60
     content/5: 8c067d15221f598260d781f6690ad75d
@@ -464,30 +464,67 @@ checksums:
     meta/title: 1f7444492b1434872386d0d93df30e6b
     meta/description: 2e4b53d1f513ed4b0baf43b3e03c50d0
     meta/og%3Adescription: 0c31ff8357910c4566c5444ba7ec2d9a
-    content/0: 119883e2bc73082539bbbcbd42b0b12a
+    content/0: 6e422a40926769a70977ec8760d8678a
     content/1: babb88ff68c2b9d3eef53fa4ade50088
-    content/2: b823c366ca4dd6beb7ee201f1f20c626
-    content/3: 488f7fd6cbf19b00c6fc12e5214219d4
-    content/4: 4477840972dd546895d1c3d8839d3a65
-    content/5: 6e2dce668c1cd5ca8c14a74a2101c8b7
-    content/6: c425baae7e79684a3a38c841872633f5
-    content/7: ffd994400c700ed59b367641588fb7ee
-    content/8: fa756c95954bfeb2f043aba89c102987
-    content/9: abbb6f769802480f124f8eff8a3bb10e
-    content/10: 6e0d334422275401ad52ed1871a3c6fd
-    content/11: 97c4454a66d0bdc736cb46007c371405
-    content/12: 6dd440e524d7b4c038ebc1a560b4f520
-    content/13: 9005fc157da4863f62f4755dfab372e9
-    content/14: 0b27c53a66c57d83ba16aa3be110bc0d
-    content/15: 40416cc82bc0686f1bef88d0dc437599
-    content/16: f12605b9c6dfa332cc9996e75520fc69
-    content/17: 097402a37c60beed5442958452e93306
-    content/18: 0cbbc8c6cdcb59047e6896b3998ea24e
-    content/19: d23efdd386d0c32d3343ba473670f98d
-    content/20: b70ca617ef398fee9b557ae44f782e54
-    content/21: b5d2e2fe5c4a70591235066277fb9219
-    content/22: 10e8e9a59847ddd720c6d06b12c7b120
-    content/23: 9799b973234bf2d10d5c971b267f55a5
+    content/2: ec83b8be6d912b1234ffbc9f09f4ff05
+    content/3: cdd33bc655b03bcba0b69e783340ec53
+    content/4: 3d6c6c4f9855a8cf2f9d5f591b6c52df
+    content/5: f74b0afb330a295bb50103c7b2063e69
+    content/6: 0048a761c5e2e672081222f23b20c716
+    content/7: 3c5ab0cfa0a2b998885ff412132eb7ab
+    content/8: cd1c91d062a27881a798e92f1e239199
+    content/9: 62bee6c8ee296a5be9c50b624827e7e7
+    content/10: d06b3bc7b41c515df4deddc588e68420
+    content/11: 72336c0411fd631876e3b6b63f71314a
+    content/12: 1c8720cd1c62ca0f00da9f08a2283ebe
+    content/13: 00b82b76758da5447270141518cdd41c
+    content/14: dffb591a41a53b1baaa93e10c333afef
+    content/15: 9a227656a512c5a79fc25ce848ebf163
+    content/16: 73f64f20b5e760dc0940d7e4cc23793d
+    content/17: a69085aaa46c9b99c79ca3266d228e00
+    content/18: f3931e5548f073249acc2b79e7972bf8
+    content/19: 2e43465d0cd62f76e82df405620d29b6
+    content/20: e04161d7430bdcfea2e24d6bd7f011eb
+    content/21: c7293817039526172227474b477af24f
+    content/22: c4f2237a5b7f6bdc10bcbb71409980ae
+    content/23: 531d7a02d64d00b7421254744a2480b1
+    content/24: cd99ee12ffd6f6bcf8a702a4909f1972
+    content/25: fc2f7dbd7f5af136c2b9b706db387410
+    content/26: 9f7d704655d6054f2ebd52da64a1c760
+    content/27: a664e8ae8a77b49981495c752e680f7d
+    content/28: ab951ba5533e9c68e789c42bb48a2c36
+    content/29: da5a5b2fdae4c8cca772d6dd77a1d99f
+    content/30: 296ec9090882ae655fd6fb11d18d6824
+    content/31: 21742d74f28887a4c9001f4f6f587a81
+    content/32: fdc368df04e3007ce730f38f1490a9b9
+    content/33: 589f66723b9cc5fe6fd2af359597296d
+    content/34: 5579e48d381bbe05eb460f2611b99ae7
+    content/35: 143e689ab4d5ffff7bc5e4a33af55685
+    content/36: fdc368df04e3007ce730f38f1490a9b9
+    content/37: 589f66723b9cc5fe6fd2af359597296d
+    content/38: 632d4ebc0b716e4361dfaa976a4bfd67
+    content/39: 152ee5e36b0e32c36b0bc07572b1bea4
+    content/40: fdc368df04e3007ce730f38f1490a9b9
+    content/41: 589f66723b9cc5fe6fd2af359597296d
+    content/42: afd6ab10651a820d051920d617dd010b
+    content/43: cf4f06c5f179e0518445186762238fb0
+    content/44: a9750e31c995086a047544aac4f69b8b
+    content/45: f43461ee3f1e455c83c3463488f5ea8c
+    content/46: f6f75d2cf6ea2fa8587e9c050a17a0f7
+    content/47: ba903d08fe21291f7de673c8efdeb8a5
+    content/48: 39869860e06375a53507816702e25894
+    content/49: 673b1581199af42481abd365bc499274
+    content/50: 7786c528b0fe8ddff35b7e1ea9132458
+    content/51: 7b18b460193604289c3a692342a44fb2
+    content/52: 58e6eca0de1e31ef7585b4f9b0d0b951
+    content/53: 30d8c07c0158ac1190f28b9068684c5b
+    content/54: 27718fbe349c9723c83a1bc0268f625d
+    content/55: 8cd8795d20c8b4ecb4adf2f1986cfe28
+    content/56: 6c56ce6270996a6da36a63551094929f
+    content/57: e04161d7430bdcfea2e24d6bd7f011eb
+    content/58: 876449849f4776edd4b50d5bb1bc11cc
+    content/59: 10e8e9a59847ddd720c6d06b12c7b120
+    content/60: 9799b973234bf2d10d5c971b267f55a5
   953868115d4c9e608173a3be973757d5:
     meta/title: f48ab602c5c8031afd2de550b2778bf0
     meta/description: e25074e52204f7c87fd6279e356af78d
diff --git a/package.json b/package.json
index 8d950f8..babf5fa 100644
--- a/package.json
+++ b/package.json
@@ -11,8 +11,8 @@
     "translate:localize-links": "node scripts/localize-internal-links.mjs",
     "translate:localize-links:all": "node scripts/localize-internal-links.mjs --all",
     "translate:localize-links:check": "node scripts/localize-internal-links.mjs --all --check",
-    "translate:localize-component-imports": "node scripts/localize-component-imports.mjs",
-    "translate:localize-component-imports:check": "node scripts/localize-component-imports.mjs --all --check",
+    "translate:localize-mdx-paths": "node scripts/localize-mdx-paths.mjs",
+    "translate:localize-mdx-paths:check": "node scripts/localize-mdx-paths.mjs --all --check",
     "translate:sync-anchors": "node scripts/sync-heading-anchors.mjs",
     "translate:sync-anchors:check": "node scripts/sync-heading-anchors.mjs --check",
     "translate:sync-openapi-titles": "node scripts/sync-openapi-titles.mjs",
diff --git a/scripts/generate-translations.mjs b/scripts/generate-translations.mjs
index d46d840..36e78b6 100644
--- a/scripts/generate-translations.mjs
+++ b/scripts/generate-translations.mjs
@@ -98,7 +98,7 @@ try {
     execSync(`npx lingo.dev@latest run --target-locale ${target}${runForce}`, { stdio: "inherit" });
     execSync(`node scripts/translate-docs-json.mjs --target ${target}`, { stdio: "inherit" });
     execSync(`node scripts/localize-internal-links.mjs --target ${target}`, { stdio: "inherit" });
-    execSync(`node scripts/localize-component-imports.mjs --target ${target}`, { stdio: "inherit" });
+    execSync(`node scripts/localize-mdx-paths.mjs --target ${target}`, { stdio: "inherit" });
     console.log(`Translation generation completed for target locale: ${target}`);
   }
   execSync("node scripts/sync-heading-anchors.mjs", { stdio: "inherit" });
diff --git a/scripts/localize-component-imports.mjs b/scripts/localize-mdx-paths.mjs
similarity index 54%
rename from scripts/localize-component-imports.mjs
rename to scripts/localize-mdx-paths.mjs
index ec8ed0a..8bfb097 100644
--- a/scripts/localize-component-imports.mjs
+++ b/scripts/localize-mdx-paths.mjs
@@ -1,5 +1,12 @@
 #!/usr/bin/env node
 
+/**
+ * localize-mdx-paths.mjs — After Lingo, normalize MDX paths per file location and locale:
+ * 1) `import ... from ".../<locale>/components/*.jsx|tsx"` → active target locale.
+ * 2) `import ... from ".../snippets/..."` relative depth → repo-root `snippets/`.
+ * 3) JSX `src=".../assets/..."` relative depth → repo-root `assets/`.
+ */
+
 import fs from "node:fs";
 import path from "node:path";
 
@@ -40,13 +47,48 @@ const knownLocalesPattern = knownLocales
   .join("|");
 
 // import ... from ".../en/components/foo.jsx|tsx"
-const IMPORT_RE = new RegExp(
+const COMPONENT_IMPORT_RE = new RegExp(
   `(from\\s+["'])([^"']*?/)(?:${knownLocalesPattern})(/components/[^"']+\\.(?:jsx|tsx))(["'])`,
   "g"
 );
 
-function rewriteContent(content, locale) {
-  return content.replace(IMPORT_RE, (_full, p1, p2, p3, p4) => `${p1}${p2}${locale}${p3}${p4}`);
+// import ... from "../snippets/foo.mdx" (one or more ../)
+const SNIPPET_IMPORT_RE = /(from\s+["'])(?:\.\.\/)+(snippets\/[^"']+)(["'])/g;
+
+// src="../assets/foo.png" or src='...' (closing quote must match opener)
+const ASSET_SRC_RE = /(src=)(["'])(?:\.\.\/)+(assets\/[^"']+)\2/g;
+
+function rewriteComponentImports(content, locale) {
+  return content.replace(COMPONENT_IMPORT_RE, (_full, p1, p2, p3, p4) => `${p1}${p2}${locale}${p3}${p4}`);
+}
+
+function dirDepthFromRepoRoot(fileAbs) {
+  const rel = path.relative(process.cwd(), fileAbs).replace(/\\/g, "/");
+  const dir = path.dirname(rel);
+  if (dir === ".") return 0;
+  return dir.split("/").filter(Boolean).length;
+}
+
+function snippetImportPrefix(depth) {
+  if (depth <= 0) return "./";
+  return "../".repeat(depth);
+}
+
+function rewriteSnippetImports(content, fileAbs) {
+  const prefix = snippetImportPrefix(dirDepthFromRepoRoot(fileAbs));
+  return content.replace(SNIPPET_IMPORT_RE, (_full, p1, p2, p3) => `${p1}${prefix}${p2}${p3}`);
+}
+
+function rewriteAssetSrc(content, fileAbs) {
+  const prefix = snippetImportPrefix(dirDepthFromRepoRoot(fileAbs));
+  return content.replace(ASSET_SRC_RE, (_full, p1, q, p3) => `${p1}${q}${prefix}${p3}${q}`);
+}
+
+function rewriteFile(content, locale, fileAbs) {
+  let next = rewriteComponentImports(content, locale);
+  next = rewriteSnippetImports(next, fileAbs);
+  next = rewriteAssetSrc(next, fileAbs);
+  return next;
 }
 
 function walkMdx(dir) {
@@ -84,15 +126,29 @@ function walkRootMdx(root, excludedTopDirs) {
   return out;
 }
 
+const excludedTop = new Set([
+  sourceLocale,
+  ...targetLocales,
+  "node_modules",
+  ".git",
+  ".github",
+  "scripts",
+  "lingo",
+  "styles",
+  ".cursor",
+  "snippets",
+  "assets",
+]);
+
 let changedFiles = 0;
 
 for (const locale of locales) {
   const files = locale === sourceLocale
-    ? walkRootMdx(".", new Set([sourceLocale, ...targetLocales, "node_modules", ".git", ".github", "scripts", "lingo", "styles", ".cursor"]))
+    ? walkRootMdx(".", excludedTop)
     : walkMdx(locale);
   for (const file of files) {
     const raw = fs.readFileSync(file, "utf8");
-    const next = rewriteContent(raw, locale);
+    const next = rewriteFile(raw, locale, file);
     if (next !== raw) {
       changedFiles += 1;
       if (!checkOnly) fs.writeFileSync(file, next);
@@ -102,10 +158,10 @@ for (const locale of locales) {
 
 if (checkOnly) {
   if (changedFiles > 0) {
-    console.error(`Found ${changedFiles} file(s) with non-localized component imports.`);
+    console.error(`Found ${changedFiles} file(s) with incorrect localized MDX paths.`);
     process.exit(1);
   }
-  console.log("Component imports are locale-localized.");
+  console.log("Localized MDX paths are correct.");
 } else {
-  console.log(`Localized component imports in ${changedFiles} file(s).`);
+  console.log(`Updated localized MDX paths in ${changedFiles} file(s).`);
 }
diff --git a/snippets/trophy-client-init-block.mdx b/snippets/trophy-client-init-block.mdx
new file mode 100644
index 0000000..ea40089
--- /dev/null
+++ b/snippets/trophy-client-init-block.mdx
@@ -0,0 +1,57 @@
+{/* vale off */}
+
+<CodeGroup>
+```typescript Node
+import { TrophyApiClient } from "@trophyso/node";
+
+const trophy = new TrophyApiClient({
+  apiKey: process.env.TROPHY_API_KEY as string,
+});
+```
+
+```ruby Ruby
+client = TrophyApiClient::Client.new(
+  :api_key => ENV["TROPHY_API_KEY"]
+)
+```
+
+```python Python
+from trophy import Trophy
+
+client = Trophy(
+    api_key=os.environ.get("TROPHY_API_KEY"),
+)
+```
+
+```php PHP
+use Trophy\TrophyClient;
+
+$trophy = new TrophyClient([
+    'apiKey' => getenv('TROPHY_API_KEY')
+]);
+```
+
+```java Java (Gradle)
+TrophyApiClient client = TrophyApiClient.builder()
+    .apiKey(System.getenv("TROPHY_API_KEY"))
+    .build();
+```
+
+```java Java (Maven)
+TrophyApiClient client = TrophyApiClient.builder()
+    .apiKey(System.getenv("TROPHY_API_KEY"))
+    .build();
+```
+
+```go Go
+client, err := trophy.NewClient(
+    option.WithAPIKey(os.Getenv("TROPHY_API_KEY")),
+)
+```
+
+```csharp .NET (C#)
+var trophy = new TrophyClient(
+    Environment.GetEnvironmentVariable("TROPHY_API_KEY")
+);
+```
+</CodeGroup>