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/palabras, 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/palabras/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).
• Fase 5 (6/n) — comparativa: nuevo docs/comparison.md — posicionamiento honesto a nivel framework, anclado en los diferenciadores que el corpus YA documenta (morfo = contrato declarativo · sema = capa de percepción · motion de dos momentos · theme = retintar lo fijo · TSC · degradación headless/SSR) + los trade-offs reales (más que aprender · ecosistema menor · sema solo paga si la usas). NO inventa claims sobre competidores; la única concreta (Chakra colapsa presence en un eje) está sourced en eidos-motion.md. La comparativa per-componente sigue en los READMEs (doctrina). Enganchado en docs/README.md.
• Fase 5 (5/n) — testing/tooling/codegen: nuevo docs/testing-and-tooling.md — consolida la historia transversal de verificación (estaba dispersa en package.json / COMPONENT_GUIDE / SOMA_ARCHITECTURE): suite vitest de 2 proyectos (client browser / server node), validadores (morfo:check · morfo:vocabulary · component:audit · perm:check · smoke · translations:check · eidos-lint — qué caza cada uno), codegen (generate:eidos-css · generate:contracts-docs + compileMorfo: generado vs autorado), y postura SSR (dom:false→disabledDom, ActiveDom owner-doc/iframe-safe, sema ornamental, hidratación = lo que smoke caza). Anclado en scripts reales de package.json. Enganchado en docs/README.md ("I want to… test").
• Fase 5 (4/n) — getting-started: nuevo docs/getting-started.md — el camino narrativo de cero a primer cambio: run it → modelo mental con la cadena de transcripción → ver las 4 capas en un solo elemento del DOM (toggle: data-toggle/data-state/data-event-* + el CSS de eidos) → loop de verificación con scripts reales → 3 caminos de primer cambio. Anclado en rutas reales (/uix/components/*, /active, /temas) y scripts reales (check/test/morfo:check/smoke/component:audit/perm:check); apunta a COMPONENT_GUIDE/THEMING_GUIDE sin duplicar. Enganchado en docs/README.md (callout arriba + fila "I want to"). Hay además un get-started de la app en /active/get-started/* (incl. ai-agents) — este es el doc-side.
• Fase 5 (3/n) — reglas de autoría de doc: nuevo docs/authoring.md — cómo se crea/edita documentación en el corpus, codificando lo que aprendió la migración: (1) linkear el canon, nunca copiarlo (la ley anti-drift); (2) cada doc tiene un estrato + dónde va; (3) docs de referencia atemporales (hand-offs/fechas/catálogos hardcoded → process o puntero); (4) una fuente por concern (roles distintos si hay 2 docs del mismo tema); (5) frontmatter; (6) ediciones renumber-safe (stub pattern para §N citadas, verificar links); (7) idioma EN; (8) naming rfc-*/design-*; + checklist pre-commit. Cada regla cita el fallo real que arregla. Enganchado en docs/README.md ("I want to… write a doc" + nota tras los estratos).

PENDIENTE

Fase 7 — Corpus-libro en docs/ (ACTIVA, decisión de usuario 2026-07-02)

El usuario fijó la forma objetivo: la referencia de capa SE MUEVE a docs/ con orden de libro, en inglés (sustituye la "estructura híbrida" del kickoff); los 189 READMEs de componente quedan fuera (E5 in-place). Plan completo por tandas + árbol objetivo + patrón de migración (mover→traducir→stub→barrido→ docs:check): PLAN-docs-book.md. F7.1 + F7.2 HECHAS (2026-07-02): docs/architecture/ completo — los 7 capítulos E1 (overview · active-architecture · morfo · soma · soma-architecture · sema · eidos) movidos y traducidos a inglés (~5.4k L), stubs con mapa §N en las rutas viejas, links del corpus barridos, docs:check 0 errores tras cada capítulo. F7.3 HECHA (2026-07-02): docs/canon/ (tsc, recipe-contract) + docs/theming/ completo (reference §1–§38 · guide · notes · channels · motion §1–§19 · motion-guide · changelog verbatim) — los stubs de THEMING.md y eidos-motion.md llevan mapa § completo (los docs más citados por §N desde código/CLAUDE.md). F7.4 HECHA (2026-07-02): docs/rfcs/ — 7 RFCs es→en con rename rfc-* vía stub (citas provenance intactas); decisions.md realineado. F7.5 HECHA (2026-07-02): docs/guides/ — component-guide (banner es→en) · completion-checklist (docs-check I5 + component-audit.ts movidos en la misma tanda) · demo-authoring · component-audit (§5 reconciliado a link-don't-copy: 6-tab v1 → puntero a la guía v2; canary button). F7.6 HECHA (2026-07-02): docs/decisions/ — book-deviations + guia-semantica-historica movidos VERBATIM en castellano (bitácora del autor / semilla histórica; exención I2 defaultSemantic de docs-check sigue al archivo); barrido final global (frontmatter related:, authoring E1, morfo §2.bis, README E2/E3 restos pre-F6) + TOC-libro completo en README (30 capítulos: 8 architecture + 2 canon + 7 theming + 7 rfcs + 4 guides + 2 decisions). F7.7 HECHA (2026-07-02, diff aprobado): CLAUDE.md 981→350 L. EL PLAN F7 ESTÁ COMPLETO — el workstream docs (fases 1–7) queda cerrado. Luego F7.5 guides (tocar ruta checklist en docs-check I5), F7.6 decisions + TOC-libro, F7.7 CLAUDE.md (diff antes de commitear).

Fase 6 — Reconciliación — HECHA (2026-07-02)

Las auditorías fable_audit.md + fable-eidos-audit.md (2026-07-01/02) verificaron ~14 conflictos doc↔doc y doc↔código + referencia mezclada con bitácora + espejos sin guard. Ejecutada completa (6 commits, 925508c7 → cierre): los ~14 conflictos corregidos (translations→texts barrido total, GUIA degradada a histórica con 5 fixes, THEMING §1/§2/§3/§4 reconciliados, deps de soma, checklist con columna Enforcement + IDs A-*, cascada sema renumerada 1·2·3·4·5a·5b, archetypes por puntero); eidos/THEMING_CHANGELOG.md (THEMING 2603→~1500, stubs vigentes+puntero); npm run docs:check con 6 invariantes (links en WARN). La tabla "Known traps" de docs/building-a-component.md quedó vacía (indicador de éxito). Detalle y desviaciones: PLAN-docs-reconciliation.md §"Resultado del cierre". Hallazgos derivados pendientes de decisión de usuario: clsx fantasma (chip), THEMING_AUDIT borrado en worktree (foráneo), PENDIENTES.md borrado (normas N-6/N-7 huérfanas), popper/ vacío.

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) · reglas de autoría (hecho) · arco getting-started (hecho) · decision-log consolidado (semilla: src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md) · walkthrough "construye tu propia capa" · comparativa honesta vs Radix/Ark/Mantine (hecho) · historia transversal SSR/testing/codegen (hecho).

Restan de Fase 5 (los más opinables/arriesgados): decision-log consolidado (riesgo: duplicar LIBRO_VARIACIONES, que YA es el decision-log impl-vs-libro; lo no-consolidado son los ~10 "Session hand-off" de CLAUDE.md → encaja mejor con el ítem Diferido "adelgazar CLAUDE.md") · walkthrough "construye tu propia capa" (especulativo — requiere validar que el patrón de capa se extiende limpio a una 5ª; mejor hacerlo deliberado, no de relleno).

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).
• Fósiles .md pendientes (censo 2026-06-14, respuesta a "los .md que quedan"):
  • DATA_ATTRS.md (RAÍZ del repo) + scripts/generate-contracts-docs.ts — ELIMINADOS (2026-06-14, orden explícita "elimina deprecated/erróneos"). Eran un par acoplado fósil del terra borrado: el script importaba src/uix/terra/utils/contracts.ts (no existe → muerto) y escribía el catálogo deprecated DATA_ATTRS.md. La fuente real del contrato data-* es el morfo + morfo:check. Pendiente menor: package.json aún tiene el entry generate:contracts-docs apuntando al script borrado — NO lo toqué (package.json está foráneo-modificado; barrerlo arrastraría cambios ajenos). Quitar esa línea cuando se resuelvan los cambios foráneos de package.json.
  • src/audit-opus-4-6-26.md (arch audit 2026-06-04) — process/efímero en ubicación de referencia, sin citas externas → mover a docs/process/ limpio.
  • src/uix/eidos/THEMING_AUDIT_2026-06-01.md — process/efímero, pero citado en ~7 sitios (CLAUDE.md ×3, THEMING.md ×3, COLOR_ENGINE_RFC) → mover requiere sweep de citas; encaja con el adelgazado de CLAUDE.md.
  • NO mover (provenance citada, como los RFCs): src/uix/eidos/lib/canvas-text/fix-stext.md (citado en ~8 sitios del código canvas-text + TYPOGRAPHY_RFC). Se queda; opcional indexar en decisions.md.
  • Foráneos/concurrentes (no tocar): eidos/MOTION_SERVICE_RFC.md, eidos/components/chronos/SPEC-CHRONOS-INICIAL.md. Excluidos: words/palabras.
  • Hand-offs de proceso en la RAÍZ: CONTINUE-icon-type-scale.md RETIRADO (2026-06-14) — track icono↔tipografía ya resuelto (opción 1); su mitad inferior era el plan "1:1 total" superado (ruido), sus 2 TODOs vivos → pendiente.md, sus decisiones ya en THEMING §5. OJO — verificación reveló drift: §5 documentaba el caso cards STALE (iconos prominentes inflados a xl/xxl) contra el código real del recipe radio-cards (16/16/18/18/20, sigue el título); se corrigió §5 (8a9a0e9c). Lección: no afirmar "preservado en X" sin abrir X y comparar. pendiente.md (pendientes eidos vivos) se queda en raíz; SYSTEM-AUDIT-2026-06-13.md = untracked/foráneo.
• 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.