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`](./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`](./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`.