svelte-kit-vice/docs/process/CONTINUE-docs-corpus.md

CONTINUE — reorganización del corpus de documentación

Hand-off para retomar en otra sesión. Trabajo iniciado 2026-06-13/14, rama active-uix.

Objetivo

Convertir la documentación del framework (dispersa, ~32k líneas) en un corpus estratificado, claro y completo, en inglés, que sirva de base para (a) un libro sobre cómo construir frameworks / cómo está construido active, y (b) la web de docs. Componentes y web/routes quedan FUERA (fase futura).

Diagnóstico de partida: NO es falta de contenido (204 READMEs + 38 docs ad-hoc, sin stubs). Es estructura — sin entrada única, sin canon único, mezcla de permanente/efímero, drift, dos idiomas.

Reglas de trabajo (no negociables)

• PROHIBIDO lanzar agentes / workflows. Hacer el trabajo a mano. (Memoria: feedback-no-subagents-do-it-yourself.)
• Responder en castellano. Comentarios de código en inglés.
• NUNCA tocar words/palabras (soma/components/words, eidos/components/palabras).
• Verificar staged antes de commit: git reset -q → git add solo los míos → confirmar git diff --cached --name-only sin foráneos (launch/package/animations/palabras/words/settings.local). Commit por bloque, push.
• El libro docs/Disenando_lo_que_ocurre_v2_3.md (untracked, del usuario) es la fuente editorial del canon. NO tocarlo. Leído entero esta sesión.

Decisiones acordadas

• Idioma objetivo: inglés (migración gradual; los docs de capa siguen en español por ahora).
• Estructura híbrida: docs/ raíz para entrada/canon/RFCs/proceso; referencia de capa in-place.
• docs/process/ = artefactos efímeros (hand-offs, snapshots, auditorías). NUNCA fuente de verdad.
• Estratos: E0 orientación · E1 arquitectura por capa · E2 canon · E3 decisiones/RFC · E4 guías · E5 referencia de módulo · process (efímero).
• Canon: destila doctrina (del libro) + enlaza el código para los valores (no copia tablas que driftan). Cada doc que necesite el vocabulario enlaza docs/CANON.md, no lo copia.
• soma: dos docs con roles separados (README=onboarding, SOMA_ARCHITECTURE=referencia profunda), sin retirar ninguno.
• active_architecture: ya hecho (§0→contratos, §10→process snapshot).

HECHO (pusheado en active-uix)

• Fase 1 — saneo: drift de canon corregido contra el código (8 familias con delegate, SEMA_FAMILY_POLICY dos ejes, verbos reales, DATA_ATTRS "Terra"→LEGACY); hand-offs embebidos de 6 READMEs de capa → docs/process/handoffs-2026-05.md; §10 de active_arch. Commits 5c18a892, 19ce90b0, e74a54ba, 41c3b0f9, b7121054. (+ 67cec940 timer auto-key, no-corpus.)
• Fase 2 — canon E2: docs/CANON.md (anclado al libro por capítulo + código por file:símbolo); 5 docs apuntan a él como autoridad + entrada lectura 0. Commits c9032a7f, 462d86c0.
• Fase 3 (2/3): active-uix/README reescrito como referencia atemporal (633820ef); active_architecture §0→"Contratos mínimos" / §10→snapshot en process (ae49f737).
• Fase 1b cierre — arts hand-offs: los "## Handoff 2026-05-14" de arts/README + arts/adom/README + arts/format/README extraídos a docs/process/handoffs-2026-05.md y quitados de los READMEs (mismo patrón que 1b).
• Fase 3 (3/3) — soma de-dup: soma/README 1057→400 L (ahora onboarding/guía: propósito, pertenencia, morfo slim, patrón de componente + composición, checklist, inventory por puntero) y SOMA_ARCHITECTURE 969→1043 L (referencia profunda; absorbió mergeProps · KEYS · focus/roving · boolean-helpers · context() · type-aliases reactivos en el nuevo §8.bis). Renumerado limpio del README, cero solape, cross-refs verificadas. Fase 3 cerrada.
• Fase 4 (1/3) — checklists: el diagnóstico "3 copias" era erróneo. COMPONENT_GUIDE = checklist de autoría (pasos 1–40 + reglas A1–A37); COMPONENT_COMPLETION_CHECKLIST = matriz de aceptación machine-auditada (atada a scripts/component-audit.ts, npm run component:audit). Son complementarios, NO duplicados — fusionarlos a un archivo rompería el binding del script. Consolidación real: una fuente por concern + cross-links bidireccionales con roles nítidos; soma/README §9 (la única copia-resumen real) reducido a puntero a ambos. Pendiente menor (flagged, fuera de scope): drift 7 familias→8 en COMPONENT_COMPLETION_CHECKLIST M-3.3.
• Fase 4 (2/3) — índice de decisiones: nuevo docs/decisions.md — entrada única E3 que cataloga los 7 RFC de eidos (color-model/engine · typography/depth/shape/structure engines · scaling) + 3 design docs de arts (connection/timer/session) + decision-logs (LIBRO_VARIACIONES, GESTURES), cada uno con estado + la decisión que registra. El rename físico de los ficheros se DIFIRIÓ (ver Diferido): los nombres *_RFC/DESIGN_* están citados como provenance en ~30 archivos de código; el índice da el naming consistente sin tocar las citas.
• Fase 4 (3/3) — THEMING split (stubs): THEMING.md 2571→1930 L, partido renumber-safe en 3 docs-estrato: eidos/TSC.md (E2, §7+§18), eidos/THEMING_GUIDE.md (E4, §8+§9), eidos/THEMING_NOTES.md (E3, §15+§17). THEMING conserva stubs-puntero numerados → las 34 secciones y todas las citas §N del corpus/código sobreviven; §16 + ## Referencias + §20-34 quedan in-place. Además §14 motion saneado (contradicción con eidos-motion.md). Fase 4 cerrada.
• Fase 5 (1/n) — entrada E0: nuevo docs/README.md — puerta única del corpus (lo pidió el usuario: "necesario para que los agentes empiecen y para cada sesión nueva"). Contiene: orientación de 60 seg, los 7 estratos, orden de lectura, mapa de docs por estrato (E1-E5 + process) y atajos task-oriented ("I want to…"). Cableado desde CLAUDE.md ("Start here", arriba de Reference Documents) para que toda sesión/agente lo lea primero. Todos los enlaces verificados. Pendiente del E0: solo adelgazar CLAUDE.md (ver Diferido).
• Fase 5 (2/n) — glosario: nuevo docs/glossary.md — el vocabulario inventado (las capas, morfo, soma, sema, eidos) definido en una línea cada término + puntero a la fuente autoritativa; el subset semántico (family/intent/verb/channel) apunta a CANON, no se recopia (sin drift). Enganchado en docs/README.md (estrato E0 + orden de lectura).

PENDIENTE

Fase 4 — COMPLETA (resumen en HECHO; detalle de THEMING ↓ para el registro)

• Partir THEMING.md (2571 L, 34 secciones, multi-estrato): TSC (§7, §18) → canon visual E2; "añadir componente" (§8)/"definir theme" (§9) → E4 guía; comparación (§15)/FAQ (§17) → E3. El resto (§1-6 mental model/capas/roles/sizes/naming, §10-13 runtime/bundle/validación/sema) = E1 referencia de capa.
  • YA hecho (commit de §14): §14 motion saneado — tenía una contradicción con eidos-motion.md (THEMING decía "motion deferred / data-motion-ref no existe / superseded por TSC event:"; eidos-motion.md dice F1-F7 implementado + motor en arts/motion + el event: scope es el obsoleto). Reescrito como puntero a eidos-motion.md (canónico) + conservado el token theming --motion-scale-lift.
  • RIESGO (= el del rename): las secciones están citadas por §N a través del corpus (CLAUDE.md §23/25/26/27/28, RFCs §25, arts/color/README §26, THEMING_AUDIT §23) + las §25/29/30/31 solapan los RFCs de color/depth/shape/structure (ya en docs/decisions.md). Renumerar rompe esas citas.
  • Enfoque elegido (usuario): split con stubs — renumber-safe, sin sweep. Extraer cada bloque a su estrato y dejar un stub-puntero numerado en THEMING manteniendo el número de sección → las citas §N sobreviven.
  • HECHO — TSC: §7 (Token Scope Contract) + §18 (cobertura universal v2.2) → src/uix/eidos/TSC.md (canon visual E2, frontmatter como CANON.md). En THEMING quedan stubs §7/§18 apuntando a TSC.md. 2550→2271 L. Verificado: 34 headers intactos, §8/§19 limpios, anchors del TOC OK, §23/25/26/27/28 sin tocar.
  • HECHO — guías + notas: §8+§9 → src/uix/eidos/THEMING_GUIDE.md (E4: añadir componente + definir theme); §15 (comparación) + §17 (FAQ) → src/uix/eidos/THEMING_NOTES.md (E3). Stubs-puntero en THEMING; §16 anti-patterns y ## Referencias conservados in-place; §20-34 (datados, changelog) in-place (citados). THEMING 2571→1930 L; split completo; 34 secciones + citas §N intactas.
  • NOTA harness: escribir un archivo EXISTENTE con PowerShell Set-Content o con regex (\d+, / sueltos) en el comando lo bloquea un analizador (lo lee como Remove-Item path). Funciona: [System.IO.File]::WriteAllLines(abs, $arr, utf8NoBom) + límites por .StartsWith() (sin regex). Crear archivos NUEVOS con Set-Content sí va. Las tools Edit/Write también.

Fase 5 — huecos de libro (escribir nuevo)

Entrada E0 (hecho) · Glosario (hecho) · arco getting-started · decision-log consolidado (semilla: src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md) · walkthrough "construye tu propia capa" · comparativa honesta vs Radix/Ark/Mantine (hoy dispersa en THEMING_NOTES §15, eidos-motion §16) · historia transversal SSR/testing/codegen.

Diferido (decisión del usuario)

• Rename físico de RFCs/design (*_ENGINE_RFC/*_RFC → rfc-*; DESIGN_CONN/DESIGN/DESIGN_TIMR → design-*): los nombres actuales están citados como provenance en ~30 archivos de código (eidos/lib/*.ts ×~20, arts/timer/*, arts/color/*, arts/session/types.ts, tests) + ~10 docs + CLAUDE.md. docs/decisions.md ya da el naming consistente a nivel índice sin tocar nada. El rename físico solo vale la pena si se barren TODAS las citas en el mismo pass (si no, drift) — decisión del usuario por el coste/beneficio (cosmético vs ~40 archivos + check). De paso: ruta mala soma/layers/GESTURES.md (real: layers/gesture/GESTURES.md) en SOMA_ARCHITECTURE/old-README.
• Poda física de las copias de vocabulario (Fase 2): hoy tienen puntero de autoridad pero conservan la lista; reemplazar por el puntero. Opcional.
• Commitear el libro v2.3 (hoy untracked → el enlace de CANON.md no resuelve en remoto). Decisión del usuario.
• Migración de idioma coordinada (docs de capa es→en).
• DATA_ATTRS.md (fósil Terra, 2158 L, hoy LEGACY): mover a process o regenerar desde los morfos.
• Adelgazar CLAUDE.md: mover sus ~10 "Session hand-off" embebidos a process/ — su propio paso, archivo sensible. (El índice E0 ya existe: docs/README.md, cableado desde CLAUDE.md.)

Referencias

• Mapa de trabajo (scratch): G:\tmp\docs-corpus-map.md.
• Canon: docs/CANON.md. Proceso: docs/process/. Arquitectura: src/uix/active_architecture.md.