svelte-kit-vice/docs/process/PLAN-docs-book.md

PLAN — Corpus-libro en docs/ (fase 7 del workstream docs)

Kickoff para sesión nueva: "Lee docs/process/PLAN-docs-book.md y continúa la tanda que toque." Decisión de usuario (2026-07-02): el corpus deja de ser un mapa sobre docs dispersos — la referencia de capa SE MUEVE a docs/ con orden de libro, en inglés. Los 189 READMEs de componente quedan FUERA (E5 in-place, enlazados). Sustituye la decisión "estructura híbrida" del kickoff original (CONTINUE-docs-corpus §Decisiones acordadas).

Objetivo

Un corpus único, estructurado y sin ambigüedad bajo docs/: base directa del libro y de la futura web de docs. Junto al código quedan stubs finos (puntero + mini-resumen) para que ninguna cita por ruta se rompa y el que navega el código encuentre la puerta.

Reglas de trabajo (heredadas + nuevas)

• PROHIBIDO lanzar agentes/workflows. Responder en castellano; docs nuevos en inglés.
• NUNCA tocar words/, palabras/, chronos/, el libro (docs/Disenando_lo_que_ocurre_v2_3.md), ni eidos/MOTION_SERVICE_RFC.md + chronos/SPEC-* (foráneos/concurrentes — NO se mueven).
• Editar con Edit/Write (PowerShell solo WriteAllLines para reescrituras).
• Git: git reset -q → add solo lo propio → commit por tanda.
• npm run docs:check verde (0 errores) al cierre de CADA tanda.
• Patrón de migración por doc (validado por el piloto F7.1):
  1. Traducir a inglés adaptando (reglas de docs/authoring.md: frontmatter, timeless, link-don't-copy) — misma sustancia, no reescritura creativa.
  2. Write en la ruta nueva del árbol objetivo.
  3. La ruta vieja queda como stub (status: moved, puntero + 2-4 líneas de orientación; si el doc era citado por §N desde código, el stub lleva el mapa §N→sección nueva).
  4. Barrer los links del corpus que apuntaban a la ruta vieja → ruta nueva (el stub garantiza que los no barridos sigan resolviendo).
  5. docs:check + commit.

Árbol objetivo

docs/
  README.md                    ← entrada: pasa de mapa a TOC del libro (se
                                 actualiza en cada tanda)
  getting-started.md · glossary.md · authoring.md · comparison.md
  testing-and-tooling.md · building-a-component.md · CANON.md · decisions.md
                               ← ya viven aquí; se quedan
  architecture/
    overview.md                ← src/uix/README.md (la tesis)
    active-architecture.md     ← src/uix/active_architecture.md
    morfo.md                   ← src/uix/morfo/README.md
    soma.md                    ← src/uix/soma/README.md
    soma-architecture.md       ← src/uix/soma/SOMA_ARCHITECTURE.md
    sema.md                    ← src/uix/sema/README.md
    eidos.md                   ← src/uix/eidos/README.md
    active-uix.md              ← src/uix/active-uix/README.md   (piloto F7.1)
  canon/
    tsc.md                     ← src/uix/eidos/TSC.md
    recipe-contract.md         ← src/uix/eidos/RECIPE_CONTRACT.md
  theming/
    reference.md               ← src/uix/eidos/THEMING.md
    guide.md                   ← THEMING_GUIDE.md · notes.md ← THEMING_NOTES.md
    changelog.md               ← THEMING_CHANGELOG.md
    motion.md                  ← eidos-motion.md · motion-guide.md ← MOTION_GUIDE.md
    channels.md                ← CHANNELS_SYNTHESIS.md
  rfcs/
    rfc-color-model.md         ← COLOR_MODEL_RFC.md      (el rename legacy→
    rfc-color-engine.md        ← COLOR_ENGINE_RFC.md      rfc-* por fin es
    rfc-depth.md · rfc-shape.md · rfc-structure.md        seguro: el stub en
    rfc-scaling.md · rfc-typography.md                    la ruta vieja conserva
                                                          las ~30 citas provenance)
  guides/
    component-guide.md         ← src/uix/soma/COMPONENT_GUIDE.md
    completion-checklist.md    ← src/uix/COMPONENT_COMPLETION_CHECKLIST.md
                                 (actualizar la ruta en scripts/docs-check.ts I5)
    demo-authoring.md          ← web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md
    component-audit.md         ← web/routes/uix/lib/COMPONENT_AUDIT_GUIDE.md
  decisions/
    book-deviations.md         ← src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md
    guia-semantica-historica.md← src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md
                                 (histórica; se mueve tal cual, en castellano —
                                 es semilla, no referencia)
  process/                     ← queda (efímero)

Fuera del libro (E5 in-place, enlazados desde el TOC): READMEs de componente (189), src/arts/*/README.md (29), docs de libs/svrs, eidos/components/README.md (patrón — candidato a guides/ en F7.5, decidir), audits/fósiles ya gestionados.

Tandas

Tanda	Contenido	Volumen	Estado
F7.1	Plan + esqueleto + piloto active-uix.md (valida el patrón)	~100 L	HECHA 2026-07-02
F7.2	architecture/ completo — overview · active-architecture · morfo · soma · soma-architecture · sema · eidos (7 capítulos, ~5.4k L movidas/traducidas; stubs con mapa §N en las rutas viejas)	—	HECHA 2026-07-02
F7.3	theming/ + canon/ completos — canon/tsc + canon/recipe-contract; theming/reference (§1–§38, stub con mapa completo) + guide + notes + channels + motion (§1–§19, stub con mapa) + motion-guide + changelog (verbatim) — 9 docs, ~5.2k L	—	HECHA 2026-07-02
F7.4	rfcs/ completo — 7 RFCs traducidos + rename rfc-* (stubs conservan las citas provenance; decisions.md realineado; MOTION_SERVICE_RFC NO — foráneo) — 1.5k L	—	HECHA 2026-07-02
F7.5	guides/ completo — component-guide (banner es→en, resto verbatim) · completion-checklist (docs-check I5 + component-audit.ts movidos en la misma tanda) · demo-authoring · component-audit (§5 reconciliado a link-don't-copy)	—	HECHA 2026-07-02
F7.6	decisions/ completo — book-deviations + guia-semantica-historica (verbatim castellano: bitácora del autor; exención I2 de docs-check movida con el doc); barrido final global + TOC-libro completo en README	—	HECHA 2026-07-02
F7.7	CLAUDE.md fino — 981→350 L: hand-offs → process/handoffs-claude-md.md, referencias → libro, CANON.md como autoridad, doctrina compactada a reglas+puntero (diff aprobado por el usuario)	—	HECHA 2026-07-02

Notas por tanda:

• La traducción es→en va incluida en cada movimiento (F7.2 es la cara: THEMING ya quedó saneada en la fase 6; SOMA_ARCHITECTURE/sema/eidos READMEs son el grueso).
• Tras cada tanda, actualizar docs/README.md (el TOC) — es el índice del libro.
• docs:check ya vigila links y campos fantasma; considerar añadir invariante "stub no crece" si aparece drift stub↔destino.

Riesgos conocidos

• Citas §N desde código (THEMING §5/§25/§35, TSC, DESIGN_*): el stub lleva mapa §N cuando el doc migre. Las citas por ruta sobreviven por el stub.
• scripts/docs-check.ts (I5) y cualquier tooling que lea rutas de docs se actualizan EN LA MISMA tanda que mueve su doc.
• Traducir ≠ reescribir: sustancia idéntica; lo que huela a stale se marca con <!-- TODO(reconcile): ... --> y se anota en el CONTINUE, no se "arregla" silenciosamente en la traducción.