claudeos-core 2.4.1 → 2.4.3

package/README.es.md

@@ -7,58 +7,40 @@
 [![license](https://img.shields.io/npm/l/claudeos-core.svg?color=blue)](LICENSE)
 [![downloads](https://img.shields.io/npm/dm/claudeos-core.svg?logo=npm&color=blue&label=downloads)](https://www.npmjs.com/package/claudeos-core)
 
-**Haz que Claude Code siga las convenciones de TU proyecto al primer intento — no los valores predeterminados genéricos.**
-
-Un scanner determinístico de Node.js lee tu código primero; luego una pipeline de Claude de 4 pasadas escribe el conjunto completo — `CLAUDE.md` + `.claude/rules/` auto-cargado + standards + skills + L4 memory. 10 idiomas de salida, 5 validators post-generación, y un allowlist explícito de rutas que impide al LLM inventar archivos o frameworks que no están en tu código.
-
-Funciona en [**12 stacks**](#supported-stacks) (monorepos incluidos) — un solo comando `npx`, sin configuración, resume-safe, idempotente.
+**Una CLI que analiza tu código fuente y genera de forma reproducible `CLAUDE.md` y `.claude/rules/`. Combina un scanner en Node.js, una pipeline de 4 pasos sobre Claude y 5 validators. Soporta 12 stacks y 10 idiomas, y no inventa rutas que no existan en tu repo.**
 
 ```bash
 npx claudeos-core init
 ```
 
+Funciona sobre [**12 stacks**](#supported-stacks), monorepos incluidos. Un solo comando, sin configuración, segura ante interrupciones e idempotente al volver a ejecutarla.
+
 [🇺🇸 English](README.md) · [🇰🇷 한국어](README.ko.md) · [🇨🇳 中文](README.zh-CN.md) · [🇯🇵 日本語](README.ja.md) · [🇻🇳 Tiếng Việt](README.vi.md) · [🇮🇳 हिन्दी](README.hi.md) · [🇷🇺 Русский](README.ru.md) · [🇫🇷 Français](README.fr.md) · [🇩🇪 Deutsch](README.de.md)
 
 ---
 
 ## ¿Qué es esto?
 
-Usas Claude Code. Es potente, pero cada sesión empieza desde cero — no tiene memoria de cómo está estructurado _tu_ proyecto. Así que recurre a valores predeterminados "generalmente buenos" que rara vez coinciden con lo que tu equipo realmente hace:
-
-- Tu equipo usa **MyBatis**, pero Claude genera repositorios JPA.
-- Tu wrapper de respuesta es `ApiResponse.ok()`, pero Claude escribe `ResponseEntity.success()`.
-- Tus paquetes son layer-first (`controller/order/`), pero Claude crea domain-first (`order/controller/`).
-- Tus errores pasan por middleware centralizado, pero Claude esparce `try/catch` por cada endpoint.
+Cada vez que abres una sesión nueva, Claude Code vuelve a los valores genéricos del framework. El equipo usa **MyBatis**, pero Claude escribe JPA. El wrapper de respuesta es `ApiResponse.ok()` y, aun así, Claude acaba escribiendo `ResponseEntity.success()`. Los paquetes se organizan por capa, pero el código generado los reorganiza por dominio. Mantener a mano un `.claude/rules/` por repositorio resuelve el problema; hasta que el código evoluciona y esas reglas dejan de cuadrar con la realidad.
 
-Te gustaría tener un set de `.claude/rules/` por proyecto — Claude Code lo carga automáticamente cada sesión — pero escribir esas reglas a mano para cada repo nuevo lleva horas, y se desactualizan a medida que el código evoluciona.
+**ClaudeOS-Core las regenera de forma reproducible a partir del código real.** Primero entra un scanner en Node.js que reconoce el stack, el ORM, la organización de paquetes y las rutas de archivos. A continuación, la pipeline de 4 pasos sobre Claude escribe el conjunto completo: `CLAUDE.md`, las reglas auto-cargadas en `.claude/rules/`, los estándares y las skills. Todo queda acotado por una lista explícita de rutas permitidas que el modelo no puede saltarse. Y para cerrar, cinco validators revisan el resultado antes de darlo por bueno.
 
-**ClaudeOS-Core las escribe por ti, desde tu código fuente real.** Un scanner determinístico de Node.js lee tu proyecto primero (stack, ORM, layout de paquetes, convenciones, rutas de archivos). Luego una pipeline de Claude de 4 pasadas convierte los hechos extraídos en un conjunto de documentación completo:
+De este modo, la misma entrada produce siempre la misma salida, byte a byte, en cualquiera de los 10 idiomas disponibles, y sin que aparezca jamás una ruta inexistente. Más abajo se entra en detalle en [Qué lo hace diferente](#qué-lo-hace-diferente).
 
-- **`CLAUDE.md`** — el índice del proyecto que Claude lee en cada sesión
-- **`.claude/rules/`** — reglas auto-cargadas por categoría (`00.core` / `10.backend` / `20.frontend` / `30.security-db` / `40.infra` / `60.memory` / `70.domains` / `80.verification`)
-- **`claudeos-core/standard/`** — documentos de referencia (el "por qué" detrás de cada regla)
-- **`claudeos-core/skills/`** — patrones reutilizables (CRUD scaffolding, plantillas de página)
-- **`claudeos-core/memory/`** — decision log + failure patterns que crecen con el proyecto
-
-Como el scanner le entrega a Claude un allowlist explícito de rutas, el LLM **no puede inventar archivos o frameworks que no estén en tu código**. Cinco validators post-generación (`claude-md-validator`, `content-validator`, `pass-json-validator`, `plan-validator`, `sync-checker`) verifican la salida antes de que se envíe — language-invariant, así que las mismas reglas se aplican generes en inglés, español, o cualquiera de los otros 8 idiomas.
-
-```
-Antes:    Tú → Claude Code → código "generalmente bueno" → corrección manual cada vez
-Después:  Tú → Claude Code → código que coincide con TU proyecto → listo para enviar
-```
+Para proyectos de larga duración, además se prepara una [Memory Layer](#memory-layer-opcional-para-proyectos-de-larga-duración) aparte.
 
 ---
 
-## Velo en un proyecto real
+## Míralo en un proyecto real
 
-Ejecutado en [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) — Java 11 · Spring Boot 2.6 · MyBatis · SQLite · 187 archivos fuente. Salida: **75 archivos generados**, tiempo total **53 minutos**, todos los validators ✅.
+Lo ejecutamos sobre [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app): Java 11, Spring Boot 2.6, MyBatis, SQLite y 187 archivos fuente. El resultado: **75 archivos generados**, **53 minutos** en total y todos los validators en verde ✅.
 
 <p align="center">
   <img src="docs/assets/spring-boot-realworld-demo.gif" alt="ClaudeOS-Core init running on spring-boot-realworld-example-app — stack detection, 4-pass pipeline, validators, completion summary" width="769">
 </p>
 
 <details>
-<summary><strong>📺 Salida del terminal (versión texto, para búsqueda y copia)</strong></summary>
+<summary><strong>Salida de terminal (versión texto, para buscar y copiar)</strong></summary>
 
 ```text
 ╔════════════════════════════════════════════════════╗
@@ -93,18 +75,18 @@ Ejecutado en [`spring-boot-realworld-example-app`](https://github.com/gothinkste
     [██████████░░░░░░░░░░] 50% (2/4)
 
 [6] Pass 3 — Generating all files...
-    🚀 Pass 3 split mode (3a → 3b → 3c → 3d-aux)
+    Pass 3 split mode (3a → 3b → 3c → 3d-aux)
     ✅ 3a complete (2m 57s)            — pass3a-facts.md (187-path allowlist)
     ✅ 3b complete (18m 49s)           — CLAUDE.md + 19 standards + 20 rules
     ✅ 3c complete (12m 35s)           — 13 skills + 9 guides
     ✅ 3d-aux complete (3m 18s)        — database/ + mcp-guide/
-    🎉 Pass 3 split complete: 4/4 stages successful
+    Pass 3 split complete: 4/4 stages successful
     [███████████████░░░░░] 75% (3/4)
 
 [7] Pass 4 — Memory scaffolding...
-    📦 Pass 4 staged-rules: 6 rule files moved to .claude/rules/
+    Pass 4 staged-rules: 6 rule files moved to .claude/rules/
     ✅ Pass 4 complete (5m)
-       📋 Gap-fill: all 12 expected files already present
+       Gap-fill: all 12 expected files already present
     [████████████████████] 100% (4/4)
 
 ╔═══════════════════════════════════════╗
@@ -133,7 +115,7 @@ Ejecutado en [`spring-boot-realworld-example-app`](https://github.com/gothinkste
 </details>
 
 <details>
-<summary><strong>📄 Lo que termina en tu <code>CLAUDE.md</code> (extracto real — Section 1 + 2)</strong></summary>
+<summary><strong>Lo que acaba en tu <code>CLAUDE.md</code> (extracto real, secciones 1 y 2)</strong></summary>
 
 ```markdown
 # CLAUDE.md — spring-boot-realworld-example-app
@@ -142,7 +124,7 @@ Ejecutado en [`spring-boot-realworld-example-app`](https://github.com/gothinkste
 > Java 11 + Spring Boot 2.6, exposing both REST and GraphQL endpoints
 > over a hexagonal MyBatis persistence layer.
 
-## 1. Role Definition
+#### 1. Role Definition
 
 As the senior developer for this repository, you are responsible for
 writing, modifying, and reviewing code. Responses must be written in English.
@@ -150,7 +132,7 @@ A Java Spring Boot REST + GraphQL API server organized around a hexagonal
 (ports & adapters) architecture, with a CQRS-lite read/write split inside
 an XML-driven MyBatis persistence layer and JWT-based authentication.
 
-## 2. Project Overview
+#### 2. Project Overview
 
 | Item | Value |
 |---|---|
@@ -166,12 +148,12 @@ an XML-driven MyBatis persistence layer and JWT-based authentication.
 | Test Stack | JUnit Jupiter 5, Mockito, AssertJ, rest-assured, spring-mock-mvc |
 ```
 
-Cada valor de arriba — coordenadas exactas de dependencias, el nombre de archivo `dev.db`, el nombre de la migración `V1__create_tables.sql`, "no JPA" — es extraído por el scanner desde `build.gradle` / `application.properties` / el árbol de fuentes antes de que Claude escriba el archivo. Nada se adivina.
+Cada valor de la tabla anterior, desde las coordenadas exactas de cada dependencia hasta el nombre del archivo `dev.db`, el de la migración `V1__create_tables.sql` o ese «no JPA», sale del scanner. Lo extrae directamente de `build.gradle`, `application.properties` y el árbol de fuentes antes de que Claude empiece a escribir. Nada se adivina.
 
 </details>
 
 <details>
-<summary><strong>🛡️ Una regla auto-cargada real (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
+<summary><strong>Una regla auto-cargada real (<code>.claude/rules/10.backend/01.controller-rules.md</code>)</strong></summary>
 
 ````markdown
 ---
@@ -179,9 +161,9 @@ paths:
   - "**/*"
 ---
 
-# Controller Rules
+#### Controller Rules
 
-## REST (`io.spring.api.*`)
+##### REST (`io.spring.api.*`)
 
 - Controllers are the SOLE response wrapper for HTTP — no aggregator/facade above them.
   Return `ResponseEntity<?>` or a body Spring serializes via `JacksonCustomizations`.
@@ -194,13 +176,13 @@ paths:
 - Let exceptions propagate to `io.spring.api.exception.CustomizeExceptionHandler`
   (`@ControllerAdvice`). Do NOT `try/catch` business exceptions inside the controller.
 
-## GraphQL (`io.spring.graphql.*`)
+##### GraphQL (`io.spring.graphql.*`)
 
 - DGS components (`@DgsComponent`) are the sole GraphQL response wrappers.
   Use `@DgsQuery` / `@DgsData` / `@DgsMutation`.
 - Resolve the current user via `io.spring.graphql.SecurityUtil.getCurrentUser()`.
 
-## Examples
+##### Examples
 
 ✅ Correct:
 ```java
@@ -228,15 +210,15 @@ public ResponseEntity<?> create(@RequestBody NewArticleParam p) {
 ```
 ````
 
-El glob `paths: ["**/*"]` significa que Claude Code carga automáticamente esta regla cada vez que editas cualquier archivo del proyecto. Cada nombre de clase, ruta de paquete, y exception handler en la regla viene directamente del código fuente escaneado — incluyendo el `CustomizeExceptionHandler` y `JacksonCustomizations` reales del proyecto.
+El glob `paths: ["**/*"]` hace que Claude Code cargue esta regla automáticamente cada vez que se edita cualquier archivo del proyecto. Los nombres de clase, las rutas de paquete y el manejador de excepciones que aparecen en la regla salen tal cual del código escaneado; reflejan, por tanto, el `CustomizeExceptionHandler` y el `JacksonCustomizations` reales del proyecto.
 
 </details>
 
 <details>
-<summary><strong>🧠 Un seed auto-generado de <code>decision-log.md</code> (extracto real)</strong></summary>
+<summary><strong>Un seed de <code>decision-log.md</code> auto-generado (extracto real)</strong></summary>
 
 ```markdown
-## 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
+#### 2026-04-26 — Hexagonal ports & adapters with MyBatis-only persistence
 
 - **Context:** `io.spring.core.*` exposes `*Repository` ports (e.g.,
   `io.spring.core.article.ArticleRepository`) implemented by
@@ -255,260 +237,276 @@ El glob `paths: ["**/*"]` significa que Claude Code carga automáticamente esta
   split the persistence model.
 ```
 
-Pass 4 inicializa `decision-log.md` con las decisiones arquitectónicas extraídas de `pass2-merged.json`, así las sesiones futuras recuerdan *por qué* el código se ve como se ve — no solo *cómo* se ve. Cada opción ("JPA/Hibernate", "MyBatis-Plus") y cada consecuencia están fundamentadas en el bloque real de dependencias de `build.gradle`.
+Pass 4 deja sembrado `decision-log.md` con las decisiones de arquitectura que extrae de `pass2-merged.json`. De esta forma, en sesiones futuras no solo se recuerda *cómo* es el código, sino también *por qué*. Cada opción («JPA/Hibernate», «MyBatis-Plus») y cada consecuencia parten del bloque de dependencias real de `build.gradle`.
 
 </details>
 
 ---
 
-## Quick Start
+## Probado en
 
-**Requisitos previos:** Node.js 18+, [Claude Code](https://docs.anthropic.com/en/docs/claude-code) instalado y autenticado.
+ClaudeOS-Core viene con benchmarks de referencia ejecutados sobre proyectos OSS reales. Si lo has usado en un repositorio público, [abre un issue](https://github.com/claudeos-core/claudeos-core/issues) y lo añadimos a la tabla.
+
+| Proyecto | Stack | Escaneado → Generado | Estado |
+|---|---|---|---|
+| [`spring-boot-realworld-example-app`](https://github.com/gothinkster/spring-boot-realworld-example-app) | Java 11 · Spring Boot 2.6 · MyBatis · SQLite | 187 → 75 archivos | ✅ los 5 validators pasan |
+
+---
+
+## Inicio rápido
+
+**Requisitos previos:** Node.js 18+ y [Claude Code](https://docs.anthropic.com/en/docs/claude-code) instalado y autenticado.
 
 ```bash
-# 1. Ve a la raíz de tu proyecto
+# 1. Sitúate en la raíz del proyecto
 cd my-spring-boot-project
 
-# 2. Ejecuta init (esto analiza tu código y le pide a Claude que escriba las reglas)
+# 2. Lanza init (analiza el código y le pide a Claude que escriba las reglas)
 npx claudeos-core init
 
-# 3. Listo. Abre Claude Code y empieza a programar — tus reglas ya están cargadas.
+# 3. Listo. Abre Claude Code y empieza a programar; las reglas ya están cargadas.
 ```
 
-**Lo que obtienes** después de que `init` termina:
+Cuando termina `init` te encuentras con esto:
 
 ```
 your-project/
 ├── .claude/
-│   └── rules/                    ← Auto-cargado por Claude Code
-│       ├── 00.core/              (reglas generales — naming, arquitectura)
-│       ├── 10.backend/           (reglas de stack backend, si las hay)
-│       ├── 20.frontend/          (reglas de stack frontend, si las hay)
-│       ├── 30.security-db/       (convenciones de seguridad y DB)
-│       ├── 40.infra/             (env, logging, CI/CD)
-│       ├── 50.sync/              (recordatorios de doc-sync — solo rules)
-│       ├── 60.memory/            (reglas de memoria — Pass 4, solo rules)
+│   └── rules/                    ← Cargado automáticamente por Claude Code
+│       ├── 00.core/              (reglas generales: nombrado, arquitectura)
+│       ├── 10.backend/           (reglas del stack backend, si lo hay)
+│       ├── 20.frontend/          (reglas del stack frontend, si lo hay)
+│       ├── 30.security-db/       (convenciones de seguridad y BD)
+│       ├── 40.infra/             (env, logs, CI/CD)
+│       ├── 50.sync/              (recordatorios de sincronización docs, solo reglas)
+│       ├── 60.memory/            (reglas de memoria, Pass 4, solo reglas)
 │       ├── 70.domains/{type}/    (reglas por dominio, type = backend|frontend)
-│       └── 80.verification/      (estrategia de pruebas + recordatorios de verificación de build)
+│       └── 80.verification/      (recordatorios de testing y verificación de build)
 ├── claudeos-core/
-│   ├── standard/                 ← Documentos de referencia (espejan la estructura de categorías)
-│   │   ├── 00.core/              (resumen del proyecto, arquitectura, naming)
-│   │   ├── 10.backend/           (referencia backend — si hay stack backend)
-│   │   ├── 20.frontend/          (referencia frontend — si hay stack frontend)
-│   │   ├── 30.security-db/       (referencia de seguridad y DB)
-│   │   ├── 40.infra/             (referencia env / logging / CI-CD)
+│   ├── standard/                 ← Documentación de referencia (misma estructura por categoría)
+│   │   ├── 00.core/              (visión del proyecto, arquitectura, nombrado)
+│   │   ├── 10.backend/           (referencia backend, si hay stack backend)
+│   │   ├── 20.frontend/          (referencia frontend, si hay stack frontend)
+│   │   ├── 30.security-db/       (referencia de seguridad y BD)
+│   │   ├── 40.infra/             (referencia env / logs / CI-CD)
 │   │   ├── 70.domains/{type}/    (referencia por dominio)
-│   │   ├── 80.verification/      (referencia de build / arranque / pruebas — solo standard)
-│   │   └── 90.optional/          (extras específicos del stack — solo standard)
+│   │   ├── 80.verification/      (referencia build / arranque / tests, solo standard)
+│   │   └── 90.optional/          (extras según stack, solo standard)
 │   ├── skills/                   (patrones reutilizables que Claude puede aplicar)
-│   ├── guide/                    (guías how-to para tareas comunes)
-│   ├── database/                 (resumen de esquema, guía de migraciones)
+│   ├── guide/                    (guías how-to para tareas frecuentes)
+│   ├── database/                 (visión del esquema, guía de migraciones)
 │   ├── mcp-guide/                (notas de integración MCP)
 │   └── memory/                   (decision log, failure patterns, compaction)
 └── CLAUDE.md                     (el índice que Claude lee primero)
 ```
 
-Las categorías que comparten el mismo prefijo numérico entre `rules/` y `standard/` representan la misma área conceptual (p. ej., reglas `10.backend` ↔ standards `10.backend`). Categorías solo de rules: `50.sync` (recordatorios de sincronización de docs) y `60.memory` (memoria de Pass 4). Categoría solo de standard: `90.optional` (extras específicos del stack sin enforcement). Todos los demás prefijos (`00`, `10`, `20`, `30`, `40`, `70`, `80`) aparecen en AMBOS `rules/` y `standard/`. Claude Code ahora conoce tu proyecto.
+Las categorías que comparten prefijo numérico entre `rules/` y `standard/` representan la misma área conceptual; por ejemplo, las reglas de `10.backend` se corresponden con los estándares de `10.backend`. Solo viven en `rules/` las categorías `50.sync` (recordatorios de sincronización) y `60.memory` (memoria de Pass 4); en cambio, solo en `standard/` vive `90.optional` (extras por stack, sin enforcement). El resto de prefijos (`00`, `10`, `20`, `30`, `40`, `70`, `80`) aparece en ambos lados. Con eso, Claude Code ya conoce el proyecto.
 
 ---
 
 ## ¿Para quién es esto?
 
-| Eres... | El dolor que esto elimina |
+| Si eres... | El dolor que quita |
 |---|---|
-| **Un dev en solitario** empezando un proyecto nuevo con Claude Code | "Enseñarle a Claude mis convenciones cada sesión" — desaparece. `CLAUDE.md` + `.claude/rules/` de 8 categorías generados en una sola pasada. |
-| **Un team lead** manteniendo estándares compartidos entre repos | El `.claude/rules/` se desincroniza cuando la gente renombra paquetes, cambia de ORM, o modifica wrappers de respuesta. ClaudeOS-Core re-sincroniza determinísticamente — misma entrada, salida byte-idéntica, sin ruido en los diffs. |
-| **Ya usas Claude Code** pero estás cansado de corregir el código generado | Wrapper de respuesta incorrecto, layout de paquetes incorrecto, JPA cuando usas MyBatis, `try/catch` esparcido cuando tu proyecto usa middleware centralizado. El scanner extrae tus convenciones reales; cada pasada de Claude se ejecuta contra un allowlist explícito de rutas. |
-| **Haciendo onboarding a un nuevo repo** (proyecto existente, uniéndote a un equipo) | Ejecuta `init` en el repo, obtén un mapa de arquitectura vivo: tabla de stack en CLAUDE.md, reglas por capa con ejemplos ✅/❌, decision log seedeado con el "por qué" detrás de las decisiones principales (JPA vs MyBatis, REST vs GraphQL, etc.). Leer 5 archivos le gana a leer 5,000 archivos fuente. |
-| **Trabajando en español / coreano / japonés / chino / 6 idiomas más** | La mayoría de los generadores de reglas de Claude Code son solo en inglés. ClaudeOS-Core escribe el conjunto completo en **10 idiomas** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) con **validación estructural byte-idéntica** — el mismo veredicto de `claude-md-validator` independientemente del idioma de salida. |
-| **Trabajando con un monorepo** (Turborepo, pnpm/yarn workspaces, Lerna) | Dominios backend + frontend analizados en una sola ejecución con prompts separados; `apps/*/` y `packages/*/` recorridos automáticamente; reglas por stack emitidas bajo `70.domains/{type}/`. |
-| **Contribuyendo a OSS o experimentando** | La salida es gitignore-friendly — `claudeos-core/` es tu directorio de trabajo local, solo `CLAUDE.md` + `.claude/` necesitan enviarse. Resume-safe si se interrumpe; idempotente al re-ejecutar (tus ediciones manuales en las reglas sobreviven sin `--force`). |
+| **Dev en solitario** que arranca un proyecto con Claude Code | Se acabó lo de explicarle a Claude las convenciones del proyecto en cada sesión. Generas `CLAUDE.md` y las 8 categorías de `.claude/rules/` de una sola pasada. |
+| **Tech lead** manteniendo estándares compartidos entre repos | Cuando alguien renombra paquetes, cambia de ORM o retoca el wrapper de respuesta, `.claude/rules/` deja de cuadrar. ClaudeOS-Core lo resincroniza siempre igual: misma entrada, misma salida byte a byte y sin ruido en el diff. |
+| **Ya usas Claude Code** y estás cansado de corregir lo que genera | Wrapper equivocado, paquetes mal organizados, JPA cuando se usa MyBatis, `try/catch` esparcidos cuando ya hay middleware central. El scanner extrae las convenciones reales y cada paso de Claude se ejecuta contra una lista explícita de rutas permitidas. |
+| **Te incorporas a un repo nuevo** (proyecto existente, llegada al equipo) | Lanzas `init` sobre el repo y obtienes un mapa vivo de la arquitectura: tabla de stack en CLAUDE.md, reglas por capa con ejemplos ✅/❌ y un decision log sembrado con el «por qué» de las decisiones grandes (JPA frente a MyBatis, REST frente a GraphQL, etc.). Leer 5 archivos sale más a cuenta que leer 5.000 fuentes. |
+| **Trabajas en coreano, japonés, chino o 7 idiomas más** | La mayoría de generadores de reglas para Claude Code solo hablan inglés. ClaudeOS-Core escribe el conjunto completo en **10 idiomas** (`en/ko/ja/zh-CN/es/vi/hi/ru/fr/de`) con **validación estructural byte-identical**: el veredicto de `claude-md-validator` no varía según el idioma de salida. |
+| **Trabajas en monorepo** (Turborepo, pnpm/yarn workspaces, Lerna) | En una sola ejecución se analizan los dominios de backend y frontend con prompts distintos. Recorre `apps/*/` y `packages/*/` automáticamente y emite las reglas de cada stack bajo `70.domains/{type}/`. |
+| **Contribuyes a OSS o estás experimentando** | La salida es amigable con `.gitignore`: `claudeos-core/` es el directorio de trabajo local y al repo solo viajan `CLAUDE.md` y `.claude/`. Si interrumpes el proceso, lo retoma; al volver a ejecutarlo es idempotente y, sin `--force`, respeta las ediciones manuales. |
 
-**No es para ti si:** quieres un bundle preset de tipo "talla única" con agentes/skills/rules que funcione el primer día sin paso de escaneo (ver [docs/es/comparison.md](docs/es/comparison.md) para entender qué encaja en cada caso), tu proyecto aún no encaja en uno de los [stacks soportados](#supported-stacks), o solo necesitas un único `CLAUDE.md` (el `claude /init` integrado es suficiente — no hace falta instalar otra herramienta).
+**No es para ti si:** buscas un pack único y universal de agents/skills/rules que funcione el primer día sin paso de escaneo (consulta [docs/es/comparison.md](docs/es/comparison.md) para ver qué encaja en cada caso); el proyecto todavía no entra en los [stacks soportados](#supported-stacks); o solo necesitas un único `CLAUDE.md`, en cuyo caso el `claude /init` integrado ya basta y no hace falta otra herramienta.
 
 ---
 
 ## ¿Cómo funciona?
 
-ClaudeOS-Core invierte el flujo de trabajo habitual de Claude Code:
+ClaudeOS-Core invierte el flujo habitual de Claude Code:
 
 ```
-Habitual:    Tú describes el proyecto → Claude adivina tu stack → Claude escribe docs
-Aquí:        El código lee tu stack → El código pasa hechos confirmados a Claude → Claude escribe docs a partir de hechos
+Habitual: Tú describes el proyecto → Claude adivina tu stack → Claude escribe la documentación
+Esto:     El código lee tu stack    → El código pasa hechos confirmados a Claude → Claude escribe a partir de hechos
 ```
 
-La pipeline corre en **tres etapas**, con código a ambos lados de la llamada al LLM:
+La pipeline avanza en **tres etapas**, con código tanto antes como después de la llamada al LLM:
 
-**1. Step A — Scanner (determinístico, sin LLM).** Un scanner Node.js recorre la raíz de tu proyecto, lee `package.json` / `build.gradle` / `pom.xml` / `pyproject.toml`, parsea archivos `.env*` (con redacción de variables sensibles para `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), clasifica tu patrón de arquitectura (los 5 patrones de Java A/B/C/D/E, Kotlin CQRS / multi-módulo, Next.js App vs. Pages Router, FSD, components-pattern), descubre dominios, y construye un allowlist explícito de cada ruta de archivo fuente que existe. Salida: `project-analysis.json` — la única fuente de verdad para lo que sigue.
+**1. Etapa A — Scanner (reproducible, sin LLM).** Un scanner en Node.js recorre la raíz del proyecto, lee `package.json`, `build.gradle`, `pom.xml` o `pyproject.toml`, parsea los archivos `.env*` (con redacción automática de variables sensibles como `PASSWORD/SECRET/TOKEN/JWT_SECRET/...`), clasifica el patrón de arquitectura (los 5 patrones A/B/C/D/E de Java, CQRS o multi-módulo en Kotlin, App Router o Pages Router en Next.js, FSD, components-pattern), descubre los dominios y compone una lista explícita con todas las rutas de archivos fuente que existen. El resultado se vuelca en `project-analysis.json`, la única fuente de verdad para lo que viene después.
 
-**2. Step B — Pipeline de Claude de 4 pasadas (restringida por los hechos del Step A).**
-- **Pass 1** lee archivos representativos por grupo de dominio y extrae ~50–100 convenciones por dominio — wrappers de respuesta, librerías de logging, manejo de errores, convenciones de naming, patrones de testing. Se ejecuta una vez por grupo de dominio (`máx 4 dominios, 40 archivos por grupo`) para que el contexto nunca se desborde.
-- **Pass 2** fusiona todo el análisis por dominio en una imagen a nivel de proyecto y resuelve los desacuerdos eligiendo la convención dominante.
-- **Pass 3** escribe `CLAUDE.md` + `.claude/rules/` + `claudeos-core/standard/` + skills + guides — dividido en stages (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide) para que el prompt de cada stage quepa en la ventana de contexto del LLM incluso cuando `pass2-merged.json` es grande. Sub-divide 3b/3c en batches de ≤15 dominios para proyectos con ≥16 dominios.
-- **Pass 4** seedea la capa de memoria L4 (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) y agrega reglas universales de scaffold. Pass 4 tiene **prohibido modificar `CLAUDE.md`** — la Section 8 de Pass 3 es autoritativa.
+**2. Etapa B — Pipeline de 4 pasos sobre Claude (limitada por los hechos de la etapa A).**
+- **Pass 1** lee archivos representativos por grupo de dominios y extrae unas 50–100 convenciones por dominio: wrappers de respuesta, librería de logging, manejo de errores, convenciones de nombrado, patrones de tests. Se ejecuta una vez por grupo (`max 4 domains, 40 files per group`) para que el contexto nunca se desborde.
+- **Pass 2** funde los análisis por dominio en una única visión del proyecto y resuelve los conflictos quedándose con la convención dominante.
+- **Pass 3** escribe `CLAUDE.md`, `.claude/rules/`, `claudeos-core/standard/`, las skills y las guides. Va dividido en etapas (`3a` facts → `3b-core/3b-N` rules+standards → `3c-core/3c-N` skills+guides → `3d-aux` database+mcp-guide) para que el prompt de cada etapa quepa en la ventana de contexto incluso cuando `pass2-merged.json` es grande. Si hay 16 dominios o más, 3b/3c se subdividen en lotes de 15 como mucho.
+- **Pass 4** siembra la capa de memoria L4 (`decision-log.md`, `failure-patterns.md`, `compaction.md`, `auto-rule-update.md`) y añade reglas de scaffolding universales. Pass 4 **tiene prohibido tocar `CLAUDE.md`**: la sección 8 que produce Pass 3 manda.
 
-**3. Step C — Verification (determinístico, sin LLM).** Cinco validators verifican la salida:
-- `claude-md-validator` — 25 checks estructurales en `CLAUDE.md` (8 secciones, conteos H3/H4, unicidad de archivos de memoria, invariante T1 de heading canónico). Language-invariant: mismo veredicto independientemente de `--lang`.
-- `content-validator` — 10 checks de contenido incluyendo verificación de path-claim (`STALE_PATH` atrapa referencias `src/...` fabricadas) y detección de drift en MANIFEST.
-- `pass-json-validator` — well-formedness JSON de Pass 1/2/3/4 + conteo de secciones consciente del stack.
-- `plan-validator` — consistencia plan ↔ disco (legacy, mayormente no-op desde v2.1.0).
-- `sync-checker` — consistencia de registro disco ↔ `sync-map.json` a través de 7 directorios rastreados.
+**3. Etapa C — Verificación (reproducible, sin LLM).** Cinco validators revisan la salida:
+- `claude-md-validator`: 25 comprobaciones estructurales sobre `CLAUDE.md` (8 secciones, conteos de H3/H4, unicidad de archivos de memoria, invariante T1 de heading canónico). Es independiente del idioma; el veredicto es el mismo para cualquier `--lang`.
+- `content-validator`: 10 comprobaciones de contenido, entre ellas la verificación de las rutas citadas (`STALE_PATH` caza referencias inventadas a `src/...`) y la detección de drift en MANIFEST.
+- `pass-json-validator`: que los JSON de Pass 1/2/3/4 estén bien formados y tengan el número de secciones esperado según el stack.
+- `plan-validator`: consistencia entre plan y disco (legacy, prácticamente no-op desde la v2.1.0).
+- `sync-checker`: consistencia entre los 7 directorios rastreados en disco y `sync-map.json`.
 
-Tres niveles de severidad (`fail` / `warn` / `advisory`) para que las warnings nunca bloqueen CI por hallucinations del LLM que el usuario puede arreglar manualmente.
+Existen tres niveles de severidad (`fail` / `warn` / `advisory`), de modo que las alucinaciones del LLM que el usuario puede arreglar a mano nunca bloquean la CI con simples warnings.
 
-El invariante que ata todo: **Claude solo puede citar rutas que realmente existen en tu código**, porque el Step A le entrega un allowlist finito. Si el LLM aun así intenta inventar algo (raro pero ocurre con ciertos seeds), el Step C lo atrapa antes de que los docs se envíen.
+La invariante que sostiene todo esto es clara: **Claude solo puede citar rutas que existan de verdad en el código**, porque la etapa A le pasa una lista cerrada. Y si aun así el LLM intenta inventarse algo (raro, pero pasa con ciertos seeds), la etapa C lo intercepta antes de entregar la documentación.
 
-Para detalles por pasada, resume basado en marker, el workaround de staged-rules para el block de path sensible `.claude/` de Claude Code, e internals de detección de stack, ver [docs/es/architecture.md](docs/es/architecture.md).
+Para los detalles de cada paso, el sistema de resume basado en marcadores, el truco de staged-rules que esquiva el bloqueo de rutas sensibles de `.claude/` por parte de Claude Code, y la lógica interna de detección de stacks, consulta [docs/es/architecture.md](docs/es/architecture.md).
 
 ---
 
 ## Supported Stacks
 
-12 stacks, auto-detectados desde los archivos de tu proyecto:
+12 stacks que se autodetectan a partir de los archivos del proyecto:
 
 **Backend:** Java/Spring Boot · Kotlin/Spring Boot · Node/Express · Node/Fastify · Node/NestJS · Python/Django · Python/FastAPI · Python/Flask
 
 **Frontend:** Node/Next.js · Node/Vite · Angular · Vue/Nuxt
 
-Los proyectos multi-stack (p. ej., Spring Boot backend + Next.js frontend) funcionan sin más.
+Los proyectos multi-stack (por ejemplo, backend Spring Boot con frontend Next.js) funcionan tal cual.
 
-Para reglas de detección y lo que cada scanner extrae, ver [docs/es/stacks.md](docs/es/stacks.md).
+Las reglas de detección y lo que extrae cada scanner están en [docs/es/stacks.md](docs/es/stacks.md).
 
 ---
 
 ## Flujo diario
 
-Tres comandos cubren ~95% del uso:
+Con tres comandos cubres aproximadamente el 95% del uso:
 
 ```bash
 # Primera vez en un proyecto
 npx claudeos-core init
 
-# Después de editar manualmente standards o rules
+# Tras editar manualmente standards o reglas
 npx claudeos-core lint
 
-# Health check (ejecuta antes de commits, o en CI)
+# Health check (antes de hacer commit, o en CI)
 npx claudeos-core health
 ```
 
-Dos más para mantenimiento del memory layer:
-
-```bash
-# Compactar el log de failure-patterns (ejecuta periódicamente)
-npx claudeos-core memory compact
-
-# Promover patrones de fallos frecuentes a reglas propuestas
-npx claudeos-core memory propose-rules
-```
-
-Para todas las opciones de cada comando, ver [docs/es/commands.md](docs/es/commands.md).
+Las opciones completas de cada comando están en [docs/es/commands.md](docs/es/commands.md). Los comandos de la capa de memoria (`memory compact`, `memory propose-rules`) se documentan más abajo en la sección [Memory Layer](#memory-layer-opcional-para-proyectos-de-larga-duración).
 
 ---
 
-## Qué hace diferente a esto
+## Qué lo hace diferente
 
-La mayoría de las herramientas de documentación de Claude Code generan a partir de una descripción (tú le dices a la herramienta, la herramienta le dice a Claude). ClaudeOS-Core genera a partir de tu código fuente real (la herramienta lee, la herramienta le dice a Claude lo que está confirmado, Claude escribe solo lo que está confirmado).
+La mayoría de herramientas de documentación para Claude Code parten de una descripción: tú se la cuentas a la herramienta y la herramienta se la cuenta a Claude. ClaudeOS-Core, en cambio, parte del código fuente real. La herramienta lee, le entrega a Claude lo que está confirmado y Claude solo escribe lo que está confirmado.
 
-Tres consecuencias concretas:
+Esto se traduce en tres consecuencias concretas:
 
-1. **Detección determinística del stack.** Mismo proyecto + mismo código = misma salida. Nada de "esta vez Claude tiró el dado distinto".
-2. **Sin rutas inventadas.** El prompt de Pass 3 lista explícitamente cada ruta de origen permitida; Claude no puede citar rutas que no existen.
-3. **Multi-stack consciente.** Los dominios backend y frontend usan distintos prompts de análisis en la misma ejecución.
+1. **Detección reproducible del stack.** Mismo proyecto y mismo código equivalen a la misma salida. Nada de «esta vez Claude lo ha hecho distinto».
+2. **Sin rutas inventadas.** El prompt de Pass 3 lleva listadas todas las rutas fuente permitidas; Claude no puede citar nada que no exista.
+3. **Consciente del multi-stack.** En la misma ejecución, los dominios de backend y de frontend usan prompts de análisis distintos.
 
-Para una comparación lado a lado de scope con otras herramientas, ver [docs/es/comparison.md](docs/es/comparison.md). La comparación trata sobre **qué hace cada herramienta**, no **cuál es mejor** — la mayoría son complementarias.
+Para una comparación lado a lado con otras herramientas, consulta [docs/es/comparison.md](docs/es/comparison.md). La comparación va de **qué hace cada herramienta**, no de **cuál es mejor**; en su mayoría son complementarias.
 
 ---
 
 ## Verificación (post-generación)
 
-Después de que Claude escribe los docs, el código los verifica. Cinco validators separados:
+Cuando Claude termina de escribir, le toca al código revisarlo. Cinco validators independientes:
 
-| Validator | Qué comprueba | Lo ejecuta |
+| Validator | Qué comprueba | Lo lanza |
 |---|---|---|
-| `claude-md-validator` | Invariantes estructurales de CLAUDE.md (8 secciones, language-invariant) | `claudeos-core lint` |
-| `content-validator` | Las rutas declaradas existen realmente; consistencia del manifest | `health` (advisory) |
-| `pass-json-validator` | Las salidas Pass 1 / 2 / 3 / 4 son JSON bien formado | `health` (warn) |
-| `plan-validator` | El plan guardado coincide con lo que hay en disco | `health` (fail-on-error) |
-| `sync-checker` | Los archivos en disco coinciden con los registros de `sync-map.json` (detección de huérfanos/no registrados) | `health` (fail-on-error) |
+| `claude-md-validator` | Invariantes estructurales de CLAUDE.md (8 secciones, independiente del idioma) | `claudeos-core lint` |
+| `content-validator` | Que las rutas citadas existen y que el manifest es consistente | `health` (advisory) |
+| `pass-json-validator` | Que los JSON de Pass 1 / 2 / 3 / 4 están bien formados | `health` (warn) |
+| `plan-validator` | Que el plan guardado coincide con lo que hay en disco | `health` (fail-on-error) |
+| `sync-checker` | Que los archivos en disco cuadran con `sync-map.json` (detecta huérfanos y no registrados) | `health` (fail-on-error) |
 
-Un `health-checker` orquesta los cuatro validators de runtime con severidad de tres niveles (fail / warn / advisory) y termina con el código adecuado para CI. `claude-md-validator` se ejecuta por separado vía el comando `lint` ya que el drift estructural es una señal de re-init, no un soft warning. Ejecuta cuando quieras:
+El `health-checker` orquesta los cuatro validators de runtime con las tres severidades (fail / warn / advisory) y termina con el código de salida adecuado para CI. `claude-md-validator`, por su parte, corre por separado a través del comando `lint`, porque cualquier drift estructural es señal de que toca volver a hacer init, no un simple aviso. Se puede lanzar cuando convenga:
 
 ```bash
 npx claudeos-core health
 ```
 
-Para los checks de cada validator en detalle, ver [docs/es/verification.md](docs/es/verification.md).
+El detalle de las comprobaciones de cada validator está en [docs/es/verification.md](docs/es/verification.md).
 
 ---
 
 ## Memory Layer (opcional, para proyectos de larga duración)
 
-Después de v2.0, ClaudeOS-Core escribe una carpeta `claudeos-core/memory/` con cuatro archivos:
+Más allá de la pipeline de scaffolding, ClaudeOS-Core también prepara la carpeta `claudeos-core/memory/` para proyectos en los que el contexto sobrevive a una sola sesión. Es opcional: si solo interesan `CLAUDE.md` y las reglas, se puede ignorar sin problema.
 
-- `decision-log.md` — append-only "por qué elegimos X sobre Y"
-- `failure-patterns.md` — errores recurrentes con puntuaciones de frequency/importance
-- `compaction.md` — cómo se auto-compacta la memoria con el tiempo
-- `auto-rule-update.md` — patrones que deberían convertirse en nuevas reglas
+Son cuatro archivos y los escribe Pass 4:
 
-Puedes ejecutar `npx claudeos-core memory propose-rules` para pedirle a Claude que mire los patrones de fallos recientes y sugiera nuevas reglas para añadir.
+- `decision-log.md`: bitácora append-only de «por qué elegimos X en lugar de Y», sembrada desde `pass2-merged.json`.
+- `failure-patterns.md`: errores recurrentes con puntuaciones de frecuencia e importancia.
+- `compaction.md`: cómo se compacta la memoria automáticamente con el tiempo.
+- `auto-rule-update.md`: patrones que merecen convertirse en reglas nuevas.
 
-Para el modelo de memoria y el ciclo de vida, ver [docs/es/memory-layer.md](docs/es/memory-layer.md).
+Dos comandos mantienen viva esta capa:
+
+```bash
+# Compactar el log de failure-patterns (ejecuta de vez en cuando)
+npx claudeos-core memory compact
+
+# Promover los failure patterns frecuentes a propuestas de regla
+npx claudeos-core memory propose-rules
+```
+
+El modelo de memoria y su ciclo de vida están en [docs/es/memory-layer.md](docs/es/memory-layer.md).
 
 ---
 
 ## FAQ
 
 **P: ¿Necesito una API key de Claude?**
-R: No. ClaudeOS-Core usa tu instalación existente de Claude Code — canaliza prompts a `claude -p` en tu máquina. No necesitas cuentas extra.
+R: No. ClaudeOS-Core se apoya en la instalación existente de Claude Code y manda los prompts al `claude -p` que ya tienes en la máquina. Sin cuentas extra.
 
-**P: ¿Esto sobrescribirá mi CLAUDE.md o `.claude/rules/` existente?**
-R: Primera ejecución en un proyecto nuevo: los crea. Re-ejecutar sin `--force` preserva tus ediciones — los marcadores de pase de la ejecución anterior se detectan y los pases se omiten. Re-ejecutar con `--force` borra y regenera todo (tus ediciones se pierden — eso es lo que `--force` significa). Ver [docs/es/safety.md](docs/es/safety.md).
+**P: ¿Va a sobrescribir mi CLAUDE.md o mi `.claude/rules/`?**
+R: La primera vez sobre un proyecto nuevo los crea. Si vuelves a ejecutarlo sin `--force`, se respetan las ediciones, porque detecta los marcadores de pass de la ejecución anterior y se salta esos pasos. Con `--force`, en cambio, borra y regenera todo (y sí, también desaparecen las ediciones; eso es lo que significa `--force`). Más detalle en [docs/es/safety.md](docs/es/safety.md).
 
-**P: Mi stack no está soportado. ¿Puedo añadir uno?**
-R: Sí. Los stacks nuevos necesitan ~3 plantillas de prompt + un domain scanner. Ver [CONTRIBUTING.md](CONTRIBUTING.md) para la guía de 8 pasos.
+**P: Mi stack no está soportado, ¿puedo añadirlo?**
+R: Sí. Para un stack nuevo hacen falta unos 3 prompt templates y un domain scanner. La guía en 8 pasos vive en [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**P: ¿Cómo genero docs en español (u otro idioma)?**
-R: `npx claudeos-core init --lang es`. 10 idiomas soportados: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
+**P: ¿Cómo genero la documentación en español (o en otro idioma)?**
+R: Con `npx claudeos-core init --lang es`. Hay 10 idiomas soportados: en, ko, ja, zh-CN, es, vi, hi, ru, fr, de.
 
 **P: ¿Funciona con monorepos?**
-R: Sí — Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) y npm/yarn workspaces (`package.json#workspaces`) son detectados por el stack-detector. Cada app obtiene su propio análisis. Otras estructuras de monorepo (p. ej., NX) no se detectan específicamente, pero los patrones genéricos `apps/*/` y `packages/*/` los siguen detectando los scanners por stack.
+R: Sí. El stack-detector reconoce Turborepo (`turbo.json`), pnpm workspaces (`pnpm-workspace.yaml`), Lerna (`lerna.json`) y los workspaces de npm/yarn (`package.json#workspaces`). Cada app se analiza por separado. Otros layouts (NX, por ejemplo) no se detectan de manera específica, aunque los scanners de cada stack siguen reconociendo los patrones genéricos `apps/*/` y `packages/*/`.
 
-**P: ¿Qué pasa si Claude Code genera reglas con las que no estoy de acuerdo?**
-R: Edítalas directamente. Luego ejecuta `npx claudeos-core lint` para verificar que CLAUDE.md sigue siendo estructuralmente válido. Tus ediciones se preservan en ejecuciones posteriores de `init` (sin `--force`) — el mecanismo de resume omite los pases cuyos marcadores existen.
+**P: ¿Y si Claude Code genera reglas con las que no estoy de acuerdo?**
+R: Se editan directamente. Después, un `npx claudeos-core lint` confirma que CLAUDE.md sigue siendo estructuralmente válido. Esas ediciones sobreviven a los siguientes `init` (sin `--force`), porque el mecanismo de resume se salta los pasos cuyos marcadores ya existen.
 
 **P: ¿Dónde reporto bugs?**
-R: [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Para problemas de seguridad, ver [SECURITY.md](SECURITY.md).
+R: En [GitHub Issues](https://github.com/claudeos-core/claudeos-core/issues). Para temas de seguridad, consulta [SECURITY.md](SECURITY.md).
+
+---
+
+## Si esto te ahorró tiempo
+
+Una ⭐ en GitHub mantiene el proyecto visible y ayuda a que otra gente lo encuentre. Issues, PRs y contribuciones de templates de stack son siempre bienvenidos; los detalles están en [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
 ## Documentación
 
-| Tema | Lee esto |
+| Tema | Lectura recomendada |
 |---|---|
-| Cómo funciona la pipeline de 4 pasadas (más profundo que el diagrama) | [docs/es/architecture.md](docs/es/architecture.md) |
+| Cómo funciona la pipeline de 4 pasos (más a fondo que el diagrama) | [docs/es/architecture.md](docs/es/architecture.md) |
 | Diagramas visuales (Mermaid) de la arquitectura | [docs/es/diagrams.md](docs/es/diagrams.md) |
-| Detección de stack — qué busca cada scanner | [docs/es/stacks.md](docs/es/stacks.md) |
-| Memory layer — decision logs y failure patterns | [docs/es/memory-layer.md](docs/es/memory-layer.md) |
-| Los 5 validators en detalle | [docs/es/verification.md](docs/es/verification.md) |
-| Cada comando CLI y opción | [docs/es/commands.md](docs/es/commands.md) |
+| Detección de stack: qué busca cada scanner | [docs/es/stacks.md](docs/es/stacks.md) |
+| Memory layer: decision logs y failure patterns | [docs/es/memory-layer.md](docs/es/memory-layer.md) |
+| Detalle de los 5 validators | [docs/es/verification.md](docs/es/verification.md) |
+| Todos los comandos y opciones de la CLI | [docs/es/commands.md](docs/es/commands.md) |
 | Instalación manual (sin `npx`) | [docs/es/manual-installation.md](docs/es/manual-installation.md) |
-| Overrides del scanner — `.claudeos-scan.json` | [docs/es/advanced-config.md](docs/es/advanced-config.md) |
-| Seguridad: qué se preserva al re-init | [docs/es/safety.md](docs/es/safety.md) |
-| Comparación con herramientas similares (scope, no calidad) | [docs/es/comparison.md](docs/es/comparison.md) |
+| Overrides del scanner: `.claudeos-scan.json` | [docs/es/advanced-config.md](docs/es/advanced-config.md) |
+| Seguridad: qué se preserva al volver a hacer init | [docs/es/safety.md](docs/es/safety.md) |
+| Comparación con herramientas similares (alcance, no calidad) | [docs/es/comparison.md](docs/es/comparison.md) |
 | Errores y recuperación | [docs/es/troubleshooting.md](docs/es/troubleshooting.md) |
 
 ---
 
 ## Contribuir
 
-Las contribuciones son bienvenidas — añadir soporte de stacks, mejorar prompts, arreglar bugs. Ver [CONTRIBUTING.md](CONTRIBUTING.md).
+Las contribuciones son bienvenidas: añadir soporte de stacks, mejorar prompts, arreglar bugs. Detalles en [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Para el Código de Conducta y la política de seguridad, ver [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) y [SECURITY.md](SECURITY.md).
+Para el código de conducta y la política de seguridad, consulta [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) y [SECURITY.md](SECURITY.md).
 
 ## Licencia
 
-[ISC](LICENSE) — gratis para cualquier uso, incluyendo comercial.
+[ISC License](LICENSE). De libre uso, también comercial. © 2025–2026 ClaudeOS-Core contributors.
 
 ---
 
-<sub>Construido con cuidado por [@claudeos-core](https://github.com/claudeos-core). Si esto te ahorró tiempo, una ⭐ en GitHub ayuda a mantenerlo visible.</sub>
+<sub>Mantenido por el equipo [claudeos-core](https://github.com/claudeos-core). Issues y PRs en <https://github.com/claudeos-core/claudeos-core>.</sub>