theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/rules/python/fastapi.md

@@ -0,0 +1,58 @@
+---
+paths:
+  - "**/app/**/*.py"
+  - "**/fastapi/**/*.py"
+  - "**/*_api.py"
+---
+# Reglas de FastAPI
+
+Usa estas reglas en proyectos FastAPI junto con las reglas generales de Python.
+
+## Estructura
+
+- Coloca la construcción de la app en `create_app()`.
+- Mantén los routers delgados; mueve la persistencia y la lógica de negocio a servicios o helpers CRUD.
+- Mantén separados los esquemas de request, los esquemas de actualización y los esquemas de respuesta.
+- Mantén las sesiones de base de datos y la autenticación en dependencias.
+
+## Async
+
+- Usa `async def` en los endpoints que realizan I/O.
+- Usa clientes de base de datos y HTTP asíncronos desde endpoints asíncronos.
+- No llames a `requests`, sesiones síncronas de SQLAlchemy ni operaciones bloqueantes de archivo/red desde rutas asíncronas.
+
+## Inyección de dependencias
+
+```python
+@router.get("/users/{user_id}")
+async def get_user(
+    user_id: str,
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    ...
+```
+
+No crees `SessionLocal()` ni clientes de larga vida dentro de los handlers de ruta.
+
+## Esquemas
+
+- Nunca incluyas contraseñas, hashes de contraseñas, access tokens, refresh tokens ni estado interno de autenticación en los modelos de respuesta.
+- Usa `response_model` en los endpoints que devuelven datos de la aplicación.
+- Usa restricciones de campo en lugar de validación escrita a mano cuando Pydantic pueda expresar la regla.
+
+## Seguridad
+
+- Mantén los orígenes CORS específicos por entorno.
+- No combines orígenes comodín con CORS con credenciales.
+- Valida la expiración, el issuer, la audience y el algoritmo del JWT.
+- Aplica rate limiting a los endpoints de autenticación y a los de escritura intensiva.
+- Redacta credenciales, cookies, cabeceras de autorización y tokens en los logs.
+
+## Testing
+
+- Sobrescribe exactamente la dependencia usada por `Depends`.
+- Limpia `app.dependency_overrides` después de los tests.
+- Prefiere clientes de test asíncronos para aplicaciones asíncronas.
+
+Consulta la skill `patrones-fastapi`.

package/vendor/theus-arsenal/rules/python/hooks.md

@@ -0,0 +1,19 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Hooks para Python
+
+> Este archivo extiende [common/hooks.md](../common/hooks.md) con contenido específico de Python.
+
+## Hooks PostToolUse
+
+Configúralos en `~/.theus/settings.json`:
+
+- **black/ruff**: autoformatear archivos `.py` después de editarlos
+- **mypy/pyright**: ejecutar verificación de tipos después de editar archivos `.py`
+
+## Advertencias
+
+- Advertir sobre sentencias `print()` en los archivos editados (usa el módulo `logging` en su lugar)

package/vendor/theus-arsenal/rules/python/patterns.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Patrones de Python
+
+> Este archivo extiende [common/patterns.md](../common/patterns.md) con contenido específico de Python.
+
+## Protocol (duck typing)
+
+```python
+from typing import Protocol
+
+class Repository(Protocol):
+    def find_by_id(self, id: str) -> dict | None: ...
+    def save(self, entity: dict) -> dict: ...
+```
+
+## Dataclasses como DTOs
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class CreateUserRequest:
+    name: str
+    email: str
+    age: int | None = None
+```
+
+## Context managers y generadores
+
+- Usa context managers (sentencia `with`) para la gestión de recursos
+- Usa generadores para evaluación perezosa e iteración eficiente en memoria
+
+## Referencia
+
+Consulta la skill `patrones-python` para patrones en profundidad, incluidos decoradores, concurrencia y organización de paquetes.

package/vendor/theus-arsenal/rules/python/security.md

@@ -0,0 +1,30 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Seguridad en Python
+
+> Este archivo extiende [common/security.md](../common/security.md) con contenido específico de Python.
+
+## Gestión de secretos
+
+```python
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+api_key = os.environ["API_KEY"]  # Lanza KeyError si falta
+```
+
+## Escaneo de seguridad
+
+- Usa **bandit** para análisis estático de seguridad:
+  ```bash
+  bandit -r src/
+  ```
+
+## Referencia
+
+Consulta la skill `revision-seguridad` para pautas generales de revisión de seguridad.

package/vendor/theus-arsenal/rules/python/testing.md

@@ -0,0 +1,38 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+---
+# Testing en Python
+
+> Este archivo extiende [common/testing.md](../common/testing.md) con contenido específico de Python.
+
+## Framework
+
+Usa **pytest** como framework de testing.
+
+## Cobertura
+
+```bash
+pytest --cov=src --cov-report=term-missing
+```
+
+## Organización de los tests
+
+Usa `pytest.mark` para categorizar los tests:
+
+```python
+import pytest
+
+@pytest.mark.unit
+def test_calculate_total():
+    ...
+
+@pytest.mark.integration
+def test_database_connection():
+    ...
+```
+
+## Referencia
+
+Consulta la skill `testing-python` para patrones detallados de pytest y fixtures.

package/vendor/theus-arsenal/rules/react/coding-style.md

@@ -0,0 +1,109 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+---
+# Estilo de código React
+
+> Este archivo extiende [typescript/coding-style.md](../typescript/coding-style.md) y [common/coding-style.md](../common/coding-style.md) con contenido específico de React.
+
+## Extensiones de archivo
+
+- `.tsx` para cualquier archivo que contenga JSX, aunque sea un fragmento de una línea
+- `.ts` para lógica pura, hooks personalizados sin JSX, definiciones de tipos y utilidades
+- `.test.tsx` / `.test.ts` reflejando el archivo fuente
+- Usa `.jsx` solo cuando el proyecto evita TypeScript de forma intencional — señala en la revisión cada archivo React nuevo sin tipos
+
+## Nomenclatura
+
+- Componentes: `PascalCase` tanto para el símbolo como para el archivo (`UserCard.tsx`, export por defecto `UserCard`)
+- Hooks personalizados: `useCamelCase` para el símbolo, kebab-case para el archivo cuando la convención del proyecto es kebab-case (`use-debounce.ts` exporta `useDebounce`)
+- Context: símbolo `<Dominio>Context`, componente proveedor `<Dominio>Provider`, hook consumidor `use<Dominio>`
+- Manejadores de eventos: `handleClick`, `handleSubmit` dentro del componente; la prop que lo recibe es `onClick`, `onSubmit`
+- Props booleanas: `isLoading`, `hasError`, `canSubmit` — nunca `loading` ni `error` a secas para booleanos
+
+## Forma del componente
+
+```tsx
+type Props = {
+  user: User;
+  onSelect: (id: string) => void;
+};
+
+export function UserCard({ user, onSelect }: Props) {
+  return (
+    <button type="button" onClick={() => onSelect(user.id)}>
+      {user.name}
+    </button>
+  );
+}
+```
+
+- Prefiere `type Props = {}` para formas de props cerradas del componente
+- Usa `interface` solo cuando el tipo de props se extiende vía declaration merging o se exporta como punto de extensión de una API pública
+- Desestructura siempre las props en la lista de parámetros — nada de acceder a `props.user` dentro del cuerpo
+- Tipa el retorno de forma implícita a través del JSX (`function Foo(): JSX.Element` solo cuando la función retorna condicionalmente y la unión confunde la inferencia)
+
+## JSX
+
+- Cierra en sí mismas las etiquetas sin hijos: `<img />`, `<UserCard user={u} />`
+- Usa fragmentos `<>...</>` en lugar de un `<div>` envolvente cuando no se necesita un elemento del DOM
+- Renderizado condicional: `{condition && <Foo />}` para booleanos, ternario para uno-u-otro, retorno temprano para cláusulas de guarda
+- Nunca pongas lógica inline en el JSX cuando se lee como multilínea — extráela a una const encima del return o a una función
+
+```tsx
+// Preferir
+const greeting = user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`;
+return <h1>{greeting}</h1>;
+
+// En lugar de
+return <h1>{user.isAdmin ? "Welcome, admin" : `Hello ${user.name}`}</h1>;
+```
+
+## Frontera servidor / cliente (Next.js App Router, RSC)
+
+- Por defecto un archivo nuevo es Server Component — añade `"use client"` solo cuando el archivo usa estado, efectos, refs, APIs del navegador o manejadores de eventos
+- Coloca la directiva `"use client"` en la línea 1, antes de cualquier import
+- Nunca importes un archivo de Client Component desde dentro de un archivo de acción `"use server"`
+- Nunca re-exportes código exclusivo de servidor a través de un módulo cliente — el bundler lo incluirá silenciosamente
+
+## Imports
+
+- Primero los imports de React: `import { useState } from "react"`
+- Luego librerías de terceros, después imports absolutos del proyecto y finalmente los relativos
+- Imports solo de tipos: `import type { ReactNode } from "react"` — nunca mezcles imports de runtime y de tipos en una misma sentencia cuando `consistent-type-imports` de ESLint está configurado
+
+## Disciplina de hooks
+
+Consulta [hooks.md](./hooks.md) para el conjunto completo de reglas. Puntos de estilo destacados:
+
+- Los hooks personalizados deben empezar con `use` — lo exige `eslint-plugin-react-hooks`
+- Agrupa todas las llamadas a hooks al inicio del componente, antes de cualquier lógica condicional
+- Evita crear hooks ad hoc para envoltorios de una línea — inserta la llamada directamente
+
+## Estado
+
+- Local primero (`useState`); elévalo solo cuando se comparte
+- Context para estado transversal leído por muchos componentes (tema, autenticación, i18n) — no para actualizaciones de alta frecuencia
+- Store externo (Zustand, Jotai, Redux Toolkit) cuando el estado debe persistir entre cambios de ruta, sincronizarse entre pestañas o depurarse vía devtools
+- Nunca dupliques estado que pueda derivarse — calcúlalo durante el render
+
+## Componentes de clase
+
+Prohibidos en código nuevo. Convierte los componentes de clase heredados a componentes de función cuando los toques para cambios no triviales.
+
+## Estructura de archivos por componente
+
+```
+components/UserCard/
+  UserCard.tsx
+  UserCard.module.css   # o styled-components, o clases de Tailwind inline
+  UserCard.test.tsx
+  index.ts              # solo re-export
+```
+
+Los componentes de archivo único inline son aceptables para piezas presentacionales triviales.

package/vendor/theus-arsenal/rules/react/hooks.md

@@ -0,0 +1,187 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/hooks/**/*.ts"
+  - "**/hooks/**/*.js"
+  - "**/use-*.ts"
+  - "**/use-*.tsx"
+---
+# Hooks de React
+
+> Este archivo cubre los **hooks de React** (`useState`, `useEffect`, `useMemo`, `useCallback`, hooks personalizados) — NO el sistema de runtime `hooks/` de Theus. El nombre sigue la convención por lenguaje `rules/<lang>/hooks.md` usada en todo este repositorio.
+>
+> Extiende [typescript/patterns.md](../typescript/patterns.md) y [common/patterns.md](../common/patterns.md).
+
+## Reglas de los hooks
+
+Impón `eslint-plugin-react-hooks` con `react-hooks/rules-of-hooks` en nivel error.
+
+1. Hooks solo en el nivel superior de un componente de función o de otro hook
+2. Nunca en bucles, condicionales, funciones anidadas ni después de retornos tempranos
+3. Siempre llamados en el mismo orden en cada render
+4. Solo dentro de componentes de función de React o hooks personalizados (funciones que empiezan con `use`)
+
+```tsx
+// INCORRECTO: hook condicional
+function Foo({ enabled }: { enabled: boolean }) {
+  if (enabled) {
+    const [x, setX] = useState(0); // violación de la regla
+  }
+}
+
+// CORRECTO: hook incondicional, condición dentro
+function Foo({ enabled }: { enabled: boolean }) {
+  const [x, setX] = useState(0);
+  if (!enabled) return null;
+  return <span>{x}</span>;
+}
+```
+
+## `useEffect` — cuándo NO usarlo
+
+`useEffect` sirve para sincronizarse con sistemas externos (suscripciones, APIs del navegador, librerías de terceros). **No** es la herramienta adecuada para:
+
+- Estado derivado — calcúlalo durante el render
+- Transformar datos para renderizar — calcúlalo durante el render
+- Reiniciar estado cuando cambia una prop — usa una `key` en el padre o deriva desde las props
+- Notificar a los padres de cambios de estado — llama al callback en el manejador de eventos
+- Inicializar singletons a nivel de aplicación — llama a la función a nivel de módulo o en `main.tsx`
+
+```tsx
+// INCORRECTO: efecto para estado derivado
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${first} ${last}`);
+}, [first, last]);
+
+// CORRECTO: derivar durante el render
+const fullName = `${first} ${last}`;
+```
+
+## Arrays de dependencias
+
+- Incluye siempre todo valor reactivo referenciado dentro del efecto/callback
+- Habilita la regla de lint `react-hooks/exhaustive-deps` — nunca la silencies sin un comentario que explique por qué
+- Si el array de dependencias se vuelve inmanejable, el efecto hace demasiado — divídelo
+- Identidad estable para funciones pasadas en deps: envuélvelas en `useCallback` solo cuando la función es a su vez dependencia de otro hook o se pasa a un hijo memoizado
+
+## Limpieza
+
+Toda suscripción, intervalo, listener o petición en curso debe limpiarse.
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+  fetch(url, { signal: controller.signal }).then(handleResponse);
+  return () => controller.abort();
+}, [url]);
+```
+
+```tsx
+useEffect(() => {
+  const id = setInterval(tick, 1000);
+  return () => clearInterval(id);
+}, []);
+```
+
+Sin limpieza = condiciones de carrera cuando cambian las deps y fugas de memoria al desmontar.
+
+## `useMemo` y `useCallback` — cuándo valen la pena
+
+Postura por defecto: **no memoices**. Añade `useMemo` / `useCallback` solo cuando:
+
+1. El valor se pasa como prop a un hijo envuelto en `React.memo`, y la identidad importa
+2. El valor es dependencia de otro `useEffect` / `useMemo` / `useCallback`
+3. El cálculo es costoso de forma medible (perfila antes de asumirlo)
+
+La memoización prematura añade ruido, oculta bugs y puede ser más lenta que el recálculo que reemplaza.
+
+## Hooks personalizados
+
+Extrae un hook personalizado cuando:
+
+- La misma secuencia de hooks (estado + efecto + calculado) aparece en 2 o más componentes
+- La lógica tiene un propósito claro y nombrable (`useDebounce`, `useOnClickOutside`, `useLocalStorage`)
+- Quieres probar la lógica de forma independiente de cualquier componente
+
+NO lo extraigas cuando:
+
+- Tendría un único llamador — insértalo inline
+- El "hook" es solo `useState` con otro nombre — añade indirección sin aportar valor
+
+```tsx
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const id = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(id);
+  }, [value, delay]);
+  return debounced;
+}
+```
+
+## Patrones de `useState`
+
+- Estado inicial desde una prop solo al montar: pasa una función `useState(() => computeInitial(prop))` cuando el cálculo es costoso
+- Actualizador funcional cuando el nuevo estado depende del anterior: `setCount(c => c + 1)` — nunca `setCount(count + 1)` dentro de contextos asíncronos o con batching
+- Agrupa estado relacionado en un solo objeto solo cuando siempre cambian juntos; de lo contrario, divide en múltiples llamadas a `useState`
+- Usa `useReducer` en cuanto las transiciones de estado dependen del estado previo o hay 3 o más valores relacionados
+
+## Patrones de `useRef`
+
+- Refs de DOM para APIs imperativas (focus, scroll, librerías de terceros)
+- Contenedor mutable que no provoca re-render (ids de temporizadores, valores previos, banderas de "está montado")
+- Nunca leas ni escribas `ref.current` durante el render — solo dentro de efectos o manejadores de eventos
+- `useImperativeHandle` solo cuando expones la API de un hijo a un ref del padre — vía de escape de último recurso
+
+## `useSyncExternalStore`
+
+Usa este hook para suscribirte a cualquier store externo (API del navegador, librería de estado de terceros, emisor de eventos personalizado). Es la forma soportada de hacer que el estado externo sea seguro con el renderizado concurrente.
+
+```tsx
+const isOnline = useSyncExternalStore(
+  (cb) => {
+    window.addEventListener("online", cb);
+    window.addEventListener("offline", cb);
+    return () => {
+      window.removeEventListener("online", cb);
+      window.removeEventListener("offline", cb);
+    };
+  },
+  () => navigator.onLine,
+  () => true,
+);
+```
+
+## Novedades de React 19
+
+- `use()` — desenvuelve promesas y contextos inline; usable de forma condicional (el único hook con esa propiedad)
+- `useFormStatus()` / `useFormState()` (o `useActionState`) — estado de envío de formularios sin prop drilling
+- `useOptimistic()` — actualizaciones de UI optimistas mientras una acción de servidor está pendiente
+- `useTransition()` — marca actualizaciones de estado no urgentes para que las urgentes sigan siendo responsivas
+
+Cuando el proyecto apunta a React 19+, prefiere estos hooks sobre equivalentes hechos a mano.
+
+## La trampa del closure obsoleto
+
+Los manejadores asíncronos y los intervalos capturan los valores del render en el que fueron creados. Corrígelo así:
+
+1. Usando la forma de actualizador funcional de `setState`
+2. Poniendo el valor cambiante en el array de deps del `useEffect` y reconstruyendo el manejador
+3. Leyendo desde un ref que se mantiene sincronizado
+
+## Configuración de lint
+
+Reglas requeridas:
+
+```json
+{
+  "rules": {
+    "react-hooks/rules-of-hooks": "error",
+    "react-hooks/exhaustive-deps": "warn"
+  }
+}
+```
+
+Trata las advertencias de `exhaustive-deps` como errores en CI para código nuevo.

package/vendor/theus-arsenal/rules/react/patterns.md

@@ -0,0 +1,194 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "**/components/**/*.ts"
+  - "**/components/**/*.js"
+  - "**/app/**/*.tsx"
+  - "**/pages/**/*.tsx"
+---
+# Patrones de React
+
+> Este archivo extiende [typescript/patterns.md](../typescript/patterns.md) y [common/patterns.md](../common/patterns.md) con contenido específico de React. Para reglas específicas de hooks, consulta [hooks.md](./hooks.md).
+
+## Separación contenedor / presentacional
+
+Los componentes contenedores son dueños del fetching de datos, el estado y los efectos secundarios. Los componentes presentacionales reciben props y renderizan — sin llamadas a servicios, sin hooks más allá del estado local de UI.
+
+```tsx
+// Contenedor — dueño de los datos
+export function UserPage({ userId }: { userId: string }) {
+  const { data: user, isLoading } = useUser(userId);
+  if (isLoading) return <Spinner />;
+  if (!user) return <NotFound />;
+  return <UserCard user={user} onSelect={handleSelect} />;
+}
+
+// Presentacional — puro
+export function UserCard({ user, onSelect }: { user: User; onSelect: (id: string) => void }) {
+  return <button onClick={() => onSelect(user.id)}>{user.name}</button>;
+}
+```
+
+## Árbol de decisión para la ubicación del estado
+
+1. Usado por un solo componente → `useState` dentro de él
+2. Usado por el padre + unos pocos hijos → elévalo al ancestro común más cercano y pásalo vía props
+3. Usado en ramas distantes → React Context **solo para lecturas de baja frecuencia** (tema, autenticación, locale)
+4. Actualizaciones de alta frecuencia compartidas por todo el árbol → store externo (Zustand, Jotai, Redux Toolkit)
+5. Datos derivados del servidor → librería de server-state (TanStack Query, SWR, fetch en RSC) — no estado de aplicación
+
+Context mal usado para valores que cambian con frecuencia provoca que cada consumidor se re-renderice en cada actualización.
+
+## Frontera Server / Client Component (RSC, Next.js App Router)
+
+- Los Server Components son el valor por defecto — se ejecutan en el servidor, no viajan al cliente y pueden usar `await` directamente
+- Los Client Components optan explícitamente con `"use client"` al inicio del archivo
+- Los datos fluyen hacia abajo: un Server Component puede renderizar un Client Component y pasarle props serializables
+- Un Client Component no puede importar un Server Component, pero puede recibirlo vía `children` o slots con nombre
+
+```tsx
+// Servidor (por defecto)
+export default async function Page() {
+  const user = await fetchUser();
+  return <UserClient user={user} />;
+}
+
+// Cliente
+"use client";
+export function UserClient({ user }: { user: User }) {
+  const [tab, setTab] = useState("profile");
+  return <Tabs value={tab} onChange={setTab}>{user.name}</Tabs>;
+}
+```
+
+- Nunca importes paquetes `"server-only"` (clientes de BD, secretos) desde un archivo de Client Component — envuélvelos en un Server Component o Server Action
+- Marca los módulos sensibles con `import "server-only"` para que el bundler falle si un archivo cliente los importa
+
+## Suspense + Error Boundaries
+
+Toda frontera de Suspense necesita un Error Boundary por encima. El par cubre ambos estados.
+
+```tsx
+<ErrorBoundary fallback={<ErrorView />}>
+  <Suspense fallback={<Skeleton />}>
+    <UserDetails id={id} />
+  </Suspense>
+</ErrorBoundary>
+```
+
+- Coloca las fronteras de Suspense cerca de donde se necesitan los datos, no en la raíz de la ruta
+- Múltiples fronteras más estrechas revelan el contenido cargado de forma progresiva
+- El Error Boundary debe ser un componente de clase (React 19 aún no tiene equivalente funcional) O usar un wrapper de librería como `react-error-boundary`
+
+## Formularios
+
+### No controlados (React 19 + form actions)
+
+Prefiere inputs no controlados con form actions cuando el formulario tiene un paso de envío claro. El navegador es dueño del valor; React lo lee vía `FormData` al enviar.
+
+```tsx
+async function action(formData: FormData) {
+  "use server";
+  await saveUser({ name: String(formData.get("name")) });
+}
+
+export function UserForm() {
+  return (
+    <form action={action}>
+      <input name="name" required />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+```
+
+### Controlados
+
+Usa inputs controlados cuando el valor gobierna otra parte de la UI, requiere validación en tiempo real o formateo.
+
+```tsx
+const [email, setEmail] = useState("");
+return <input value={email} onChange={(e) => setEmail(e.target.value)} />;
+```
+
+### Librerías de formularios
+
+Para formularios complejos (multi-paso, arrays de campos dinámicos, validación entre campos), usa una librería:
+
+- React Hook Form — mínimos re-renders, enfoque no controlado primero
+- TanStack Form — tipada, agnóstica de framework
+- Final Form — cuando importan los re-renders basados en suscripciones
+
+## Fetching de datos
+
+| Estrategia | Cuándo |
+|---|---|
+| Fetch en RSC (`await` en un Server Component) | Datos por petición en Next.js App Router, sin necesidad de caché en el cliente |
+| TanStack Query | Caché en el cliente, mutaciones, actualizaciones optimistas, polling |
+| SWR | Caché ligera + revalidación, más simple que TanStack Query |
+| `fetch` en `useEffect` | Evítalo — condiciones de carrera, sin caché, sin reintentos. Solo aceptable para casos puntuales de disparar-y-olvidar |
+
+Nunca hagas fetch en un `useEffect` cuando hay una librería de caché real disponible — estas manejan deduplicación, invalidación de caché, reintento de errores e integración con Suspense.
+
+## Listas y keys
+
+- La `key` debe ser estable entre renders — nunca `index` para una lista que puede reordenarse, insertar o eliminar
+- La `key` debe ser única entre hermanos, no globalmente
+- Una lista reordenada con keys por índice hace que el estado de los componentes hijos se pegue a la fila equivocada
+
+## Composición sobre herencia
+
+- Pasa `children` para composición estilo slot
+- Pasa funciones render-prop para renderizado parametrizado
+- Pasa tipos de componente para puntos de extensión: `renderItem={UserRow}`
+- Nunca extiendas una clase de componente para especializar comportamiento
+
+## Componentes compuestos
+
+Para controles relacionados (Tabs, Accordion, Menu), usa componentes compuestos que comparten estado vía Context:
+
+```tsx
+<Tabs defaultValue="profile">
+  <Tabs.List>
+    <Tabs.Trigger value="profile">Profile</Tabs.Trigger>
+    <Tabs.Trigger value="settings">Settings</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Panel value="profile"><ProfileForm /></Tabs.Panel>
+  <Tabs.Panel value="settings"><SettingsForm /></Tabs.Panel>
+</Tabs>
+```
+
+## Portales
+
+Usa `createPortal` para modales, tooltips y contenedores de toasts — cualquier cosa que deba escapar del `overflow: hidden` del padre o del contexto de apilamiento de `z-index`. Renderiza hacia un nodo del DOM estable montado en `index.html`.
+
+## Refs y forwarding (React 19+)
+
+React 19 permite que los componentes de función acepten `ref` como una prop normal — `forwardRef` ya no es necesario.
+
+```tsx
+export function Input({ ref, ...rest }: { ref?: React.Ref<HTMLInputElement> } & InputProps) {
+  return <input ref={ref} {...rest} />;
+}
+```
+
+Las bases de código más antiguas en React 18 siguen necesitando `forwardRef`.
+
+## Fuera de alcance (secciones puntero)
+
+### Next.js (App Router)
+
+- Server Actions, Route Handlers, Middleware, rutas paralelas/interceptadas, Metadata en streaming
+- Se tratan como una preocupación de framework aparte — al añadir patrones profundos específicos de Next, propón una pista dedicada `rules/nextjs/`
+- Por ahora, sigue la documentación oficial de Next.js para los detalles del App Router
+
+### React Native
+
+- Imports específicos de plataforma (`Platform.OS`, `.ios.tsx` / `.android.tsx`), `StyleSheet`, librerías de navegación (React Navigation, Expo Router)
+- Se trata como una pista aparte — `rules/react-native/` aún no existe
+- Los hooks y patrones core de React de este archivo siguen aplicando
+
+## Referencia de skills
+
+Para profundizar en React consulta `skills/patrones-react/SKILL.md`. Para preocupaciones de frontend entre frameworks consulta `skills/patrones-frontend/SKILL.md`. Para accesibilidad consulta `skills/accesibilidad/SKILL.md`.