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).

## 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)
Glosario del vocabulario inventado · 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 §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`.