docs: agregar plan de documentación y internacionalización (Fase D/I)

Co-authored-by: aider (openrouter/openai/gpt-5) <aider@aider.chat>

docs/2025-11-01-plan-refactor-tecnico.md

@@ -425,6 +425,8 @@ Cada lote incluye objetivo, cambios, métricas y comprobaciones. Mantener tests
 6) Dividir TaskItem y revisar AppShell (Lote 5): **Completado**.
 7) DI ligera para DB (Lote 6).
 8) Aumentar cobertura en módulos flojos (Lote 7).
+9) Documentación exhaustiva (Fase D): plan y PRs D0–D6.
+10) Internacionalización (Fase I): plan y PRs I0–I7.
 
 ## Información adicional a recopilar (para Lote 0)
 
@@ -433,3 +435,77 @@ Cada lote incluye objetivo, cambios, métricas y comprobaciones. Mantener tests
 - apps/web/vite.config.ts
 
 Con estos 3 archivos podremos definir cambios mínimos para tener un typecheck limpio por paquetes sin introducir dependencias externas.
+
+## Fase D — Documentación (nueva)
+
+- Principios:
+  - Markdown en /docs como fuente de verdad; sin dependencias nuevas; build opcional más adelante.
+  - Verificación simple en CI para comprobar “completitud” (p. ej., grep de variables de entorno usadas vs documentadas).
+- PR D0: Estructura y guía de estilo
+  - docs/README (mapa de contenidos), guía de estilo y convenciones.
+  - Índice propuesto: Quickstart, Instalación, Configuración (ENV), Uso web, Uso por chat/comandos, Operaciones, Arquitectura, Seguridad, Contribución, Troubleshooting/FAQ.
+  - Aceptación: esqueleto aprobado y navegación clara.
+- PR D1: Referencia de variables de entorno
+  - Tabla completa: nombre, descripción, tipo, por defecto, requerido/optativo, ámbito (core/web), sensibilidad, recarga dinámica.
+  - Generar .env.example coherente con la tabla.
+  - Aceptación: 100% de variables de entorno documentadas.
+- PR D2: Quickstart e instalación
+  - Pasos desde cero a “todo funcionando” (core + web).
+  - Matriz de comandos: typecheck core/web, dev, build, test, coverage.
+  - Aceptación: reproducible en máquina limpia.
+- PR D3: Uso (web + comandos)
+  - Catálogo de comandos (nueva, tomar, soltar, ver, web…): expectativas y ejemplos.
+  - Guía de la interfaz web (navegación, calendarios ICS, preferencias).
+  - Aceptación: ejemplos probados manualmente.
+- PR D4: Operaciones y despliegue
+  - Endpoints /health y /metrics, migraciones, copias de seguridad, rotación de claves, runbooks de incidencias.
+  - Aceptación: runbooks accionables.
+- PR D5: Arquitectura y DB
+  - Visión por capas (core, servicios, web), flujos (webhook → colas → tareas), esquema SQLite principal.
+  - Aceptación: suficiente para nuevos contribuidores.
+- PR D6: Contribución y ADRs
+  - Cómo proponer cambios, estándares TS/UTC/ICS, política de versiones.
+  - ADRs para decisiones clave (UTC, DB locator, ICS all-day).
+  - Aceptación: plantilla de PR y guía de contribución listas.
+
+## Fase I — Internacionalización (nueva)
+
+- Principios:
+  - Sin dependencias externas: diccionarios JSON + helper t() con plantillas {var}.
+  - en-US como base del código; es-ES como primera localización.
+  - Locale configurable por ENV y, en web, preferencia por usuario (con fallback).
+- PR I0: Inventario y glosario
+  - Auditoría de textos visibles (servicios, UI, errores “para usuario”, títulos ICS).
+  - Glosario EN/ES y convenciones de keys (scope.key).
+  - Aceptación: listado consolidado.
+- PR I1: Normalización de identificadores a inglés
+  - Renombrar funciones/variables/módulos que sigan en español (sin tocar textos visibles).
+  - Aceptación: grep de identificadores no ingleses → 0 o lista de excepciones (nombres propios).
+- PR I2: Infra i18n mínima (core)
+  - Helper t(locale, key, params) y carga de diccionarios.
+  - ENV APP_LOCALE y orden de resolución (env → usuario → default).
+  - Aceptación: conmutación en 1–2 mensajes de ejemplo entre en-US/es-ES.
+- PR I3: Externalización de mensajes en servicios
+  - WhatsApp/CLI/respuestas de comandos → keys + params.
+  - Mantener es-ES como referencia y crear en-US equivalentes.
+  - Aceptación: tests de comandos verdes en ambos locales; 0 strings hardcoded en servicios.
+- PR I4: UI web (SvelteKit)
+  - Carga de diccionarios por ruta/layout, helper en frontend, marcadores para traducciones faltantes.
+  - Preferencia de idioma por usuario y fallback Accept-Language.
+  - Aceptación: cambiar idioma desde preferencias refleja cadenas principales.
+- PR I5: Formatos y convenciones por locale
+  - Fechas/números con Intl; labels de días; ymd→dmy solo en vistas.
+  - ICS: título/PRODID localizables; contenido sigue en UTC.
+  - Aceptación: pruebas de formateo y snapshots actualizados.
+- PR I6: Logs y métricas
+  - Política: logs en inglés estable; mensajes de usuario traducibles; métricas/labels estáticos.
+  - Aceptación: política documentada y aplicada.
+- PR I7: QA i18n en CI
+  - Comprobador: claves sin traducción, claves huérfanas, placeholders inválidos.
+  - Smoke tests en en-US y es-ES (web y comandos básicos).
+  - Aceptación: CI bloquea claves faltantes.
+
+- Orden recomendado:
+  1) Completar Lote 7 (cobertura) para congelar comportamiento.
+  2) PRs D0–D6 (documentación) en paralelo donde sea posible.
+  3) PRs I0–I7 (i18n) en tandas pequeñas, con tests en ambos locales.