docs: AGENTS.md como instrucciones comunes a cualquier agente

Sigue la convención que usa el propio angular/angular, que tiene su AGENTS.md
en la raíz con frontmatter `trigger: always_on` —lo que esperan Windsurf y
Antigravity— y mantiene el archivo corto enlazando a la documentación en vez
de duplicarla.

CLAUDE.md y GEMINI.md son punteros de tres líneas para las herramientas que
buscan un nombre propio. No duplican nada: cualquier cambio va en AGENTS.md,
y un test comprueba que sigan siendo punteros y no copias.

El contenido es lo que un agente necesita saber y no puede deducir del
código: que adev-es es una capa de traducción sobre un overlay, que el
respaldo .en.* es lo único que protege una traducción de la próxima
sincronización, y las cuatro reglas que rompen cosas si se ignoran —entre
ellas los prefijos de alerta, que son claves del tokenizer y no prosa.

Con tests, porque un agente no duda del documento: si AGENTS.md nombra un
comando que ya no existe o un ancla que se movió, actúa sobre información
falsa sin que nada avise. Se verifica que los `npm run` existan, que los
enlaces y anclas resuelvan, y que los prefijos de alerta sigan estando en el
enum de adev — si upstream añade o quita uno, salta aquí.

Author: oidacra

AGENTS.md

@@ -0,0 +1,76 @@
+---
+trigger: always_on
+---
+
+Este repositorio es la traducción al español de la documentación de Angular
+(angular.dev → angular.lat). Esta guía es para agentes de IA que trabajen aquí.
+
+**Escribe siempre en español**: commits, PRs, issues, comentarios de código y
+respuestas. El proyecto entero está en español.
+
+## Cómo está montado
+
+No es una copia del sitio, es una **capa de traducción**:
+
+- `origin/` — submódulo con el `angular/angular` en inglés, fijado a un SHA.
+- `adev-es/` — solo lo traducido. El build copia `origin` entero y superpone
+  `adev-es` encima, así que lo que no esté traducido sale en inglés y no rompe.
+- `xxx.md` es la traducción; `xxx.en.md` es el inglés del que se partió.
+
+Ese respaldo `.en.*` **no es opcional**: es lo único que le dice a
+`update-origin` que el archivo ya está traducido. Sin él, la siguiente
+sincronización le escribe el inglés encima sin aviso. Vale para cualquier
+extensión, no solo `.md` — la navegación y el pie de página son `.ts` y `.html`.
+
+## Comandos
+
+```shell
+npm run check-translations    # qué falta traducir y qué se desactualizó
+npm run lint-glossary         # terminología contra glosario.yml
+npm run plan-translation      # qué bloques tocar en una traducción desactualizada
+npm run verify-translation    # comprueba que solo se tocó lo previsto
+npm test                      # tests de las herramientas
+npm run build                 # compila el sitio
+```
+
+## Documentación
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — flujo completo. Anclas útiles:
+  [`#respaldo`](CONTRIBUTING.md#respaldo),
+  [`#actualizar`](CONTRIBUTING.md#actualizar),
+  [`#antes-del-pr`](CONTRIBUTING.md#antes-del-pr).
+- [UPDATE-ORIGIN.md](UPDATE-ORIGIN.md) — sincronizar con una versión nueva.
+- [glosario.yml](glosario.yml) — reglas de terminología, cada una con su motivo.
+
+## Reglas que rompen cosas si se ignoran
+
+- **`.md` y `.en.md` van en el mismo commit.** Separarlos deja el archivo
+  marcado como desactualizado de forma permanente: la detección busca el commit
+  que tocó ambos.
+- **No repitas `cp archivo.md archivo.en.md`** si el `.en.md` ya existe.
+  Escribirías español sobre el respaldo y se perdería el registro del original.
+- **Los prefijos de alerta se quedan en inglés**: `NOTE:`, `TIP:`, `IMPORTANT:`,
+  `HELPFUL:`, `CRITICAL:`, `SUMMARY:`, `QUESTION:`. Son claves del tokenizer de
+  adev, no prosa; traducirlas hace que el aviso se renderice como párrafo plano.
+  Traduce solo el texto que sigue.
+- **No traduzcas código, rutas, URLs ni nombres de API.** Sí los comentarios
+  dentro del código y los atributos con prosa visible (`title=`, `header=`).
+- **Mantén el número de líneas** entre el original y la traducción cuando se
+  pueda: es lo que hace legibles los diffs futuros.
+
+## Al actualizar una traducción desactualizada
+
+No se retraduce: se aplica solo el cambio que ocurrió en inglés. Lee el
+documento completo en ambos idiomas —la traducción existente es la mejor
+referencia de terminología y registro— pero edita únicamente los bloques que
+indique `plan-translation`.
+
+## Issues y PRs
+
+- Usa la CLI `gh`.
+- Los issues de traducción se agrupan **por sección**, no uno por archivo, y
+  siguen la convención del repo: `Traducir - Guías de X`, `Actualizar - X`,
+  con prefijo de versión cuando aplica: `[Angular 22.1] Traducir …`.
+- Etiqueta siempre con `docs-translation`.
+- Antes de crear issues, comprueba con `gh issue list` qué existe ya: el repo
+  los mantiene a mano y duplicarlos es peor que no crearlos.

CLAUDE.md

@@ -0,0 +1,5 @@
+Las instrucciones de este repositorio están en [AGENTS.md](AGENTS.md), que es la
+convención común a todas las herramientas de agente.
+
+Este archivo existe solo para que las que buscan un nombre propio lo encuentren.
+No dupliques contenido aquí: cualquier cambio va en `AGENTS.md`.

GEMINI.md

@@ -0,0 +1,5 @@
+Las instrucciones de este repositorio están en [AGENTS.md](AGENTS.md), que es la
+convención común a todas las herramientas de agente.
+
+Este archivo existe solo para que las que buscan un nombre propio lo encuentren.
+No dupliques contenido aquí: cualquier cambio va en `AGENTS.md`.

tools/agents-md.test.mjs

@@ -0,0 +1,69 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * AGENTS.md le dice a un agente qué comandos existen y dónde está la
+ * documentación. Si esas referencias se quedan atrás, el agente actúa sobre
+ * información falsa sin que nada avise — y a diferencia de una persona, no va a
+ * dudar del documento.
+ */
+
+const ROOT = resolve(import.meta.dirname, '..');
+const doc = readFileSync(resolve(ROOT, 'AGENTS.md'), 'utf8');
+const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf8'));
+
+test('existe y declara el trigger que esperan las herramientas', () => {
+  assert.match(doc, /^---\ntrigger: always_on\n---/, 'falta el frontmatter');
+});
+
+test('todos los `npm run` que menciona existen', () => {
+  const usados = [...doc.matchAll(/npm run ([a-z-]+)/g)].map((m) => m[1]);
+  assert.ok(usados.length >= 5, 'apenas menciona comandos');
+  for (const c of new Set(usados)) {
+    assert.ok(pkg.scripts[c], `AGENTS.md menciona "npm run ${c}" y no existe`);
+  }
+});
+
+test('los archivos que enlaza existen', () => {
+  const enlaces = [...doc.matchAll(/\]\(([^)#]+\.(?:md|yml))(?:#[\w-]+)?\)/g)].map((m) => m[1]);
+  assert.ok(enlaces.length, 'no enlaza nada');
+  for (const f of new Set(enlaces)) {
+    assert.ok(existsSync(resolve(ROOT, f)), `enlaza ${f}, que no existe`);
+  }
+});
+
+test('las anclas de CONTRIBUTING que cita existen', () => {
+  const contributing = readFileSync(resolve(ROOT, 'CONTRIBUTING.md'), 'utf8');
+  const anclas = [...doc.matchAll(/CONTRIBUTING\.md#([\w-]+)/g)].map((m) => m[1]);
+  assert.ok(anclas.length, 'no cita ninguna ancla');
+  for (const a of new Set(anclas)) {
+    assert.ok(contributing.includes(`{#${a}}`), `cita #${a} y CONTRIBUTING no la define`);
+  }
+});
+
+// Traducir un prefijo que no está en el enum rompe el renderizado del aviso.
+// Si upstream añade o quita uno, este test lo detecta antes que un lector.
+test('los prefijos de alerta que nombra existen en el tokenizer de adev', () => {
+  const src = resolve(ROOT, 'origin/adev/shared-docs/pipeline/shared/marked/extensions/docs-alert.mts');
+  if (!existsSync(src)) return; // submódulo sin inicializar
+
+  const claves = [...readFileSync(src, 'utf8').matchAll(/^\s+([A-Z]+)\s*=/gm)].map((m) => m[1]);
+  const nombrados = [...doc.matchAll(/`([A-Z]+):`/g)].map((m) => m[1]);
+
+  assert.ok(nombrados.length >= 5, 'apenas nombra prefijos');
+  for (const p of new Set(nombrados)) {
+    assert.ok(claves.includes(p), `nombra "${p}:" y no está en AlertSeverityLevel`);
+  }
+});
+
+test('los punteros por herramienta apuntan a AGENTS.md y no duplican', () => {
+  for (const f of ['CLAUDE.md', 'GEMINI.md']) {
+    const p = resolve(ROOT, f);
+    assert.ok(existsSync(p), `falta ${f}`);
+    const c = readFileSync(p, 'utf8');
+    assert.match(c, /AGENTS\.md/, `${f} no apunta a AGENTS.md`);
+    assert.ok(c.length < 600, `${f} parece duplicar contenido en vez de apuntar`);
+  }
+});