Companion to the entry point: an agent or new session can look up the framework's
coined terms (morfo, soma, sema, eidos, archetype, runtime part, Presence,
polymorphic close, hold, cascade, TSC, recipe, variant, role, scaling, …) in one
place, each with a pointer to its authoritative doc. The semantic subset
(family / intent / verb / channel) points at CANON.md instead of restating the
values, so it cannot drift.
Wired into docs/README.md (E0 stratum + reading order).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A single front door to the whole documentation set, for new sessions and agents
to orient before doing anything: the 60-second framework summary, the strata
(E0 orientation / E1 architecture / E2 canon / E3 decisions / E4 guides / E5
module reference / process), a reading order, a per-stratum map of every doc,
and task-oriented shortcuts ("I want to build a component / theme it / know why
a decision was made…").
CLAUDE.md gets a "Start here" pointer at the top of Reference Documents so the
entry point is actually reached on session start (this is the small additive
pointer, not the deferred CLAUDE.md slimming). All links verified.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Completes the renumber-safe split of THEMING.md.
- §8 "añadir componente" + §9 "definir theme" -> src/uix/eidos/THEMING_GUIDE.md
(E4 authoring guides).
- §15 "comparación con librerías" + §17 "FAQ — decisiones polémicas" ->
src/uix/eidos/THEMING_NOTES.md (E3 comparison + rationale).
THEMING.md keeps numbered pointer-stubs at §8/§9/§15/§17; §16 anti-patterns,
the ## Referencias section, and the dated §20-34 changelog stay in place. All
34 sections and every "THEMING §N" citation across the corpus + code survive.
THEMING 2571 -> 1930 lines across the three commits; it is now a leaner E1
layer reference with TSC (E2), the guides (E4) and the notes (E3) as siblings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
First piece of the THEMING split, using the renumber-safe stub approach so the
many "THEMING §N" citations across the corpus + code keep resolving.
§7 (Token Scope Contract) and §18 (universal coverage, v2.2) move to a new
src/uix/eidos/TSC.md — the eidos visual canon (E2), with CANON.md-style
frontmatter. THEMING.md keeps numbered pointer-stubs at §7/§18, so section
numbers (and therefore §23/§25/§26/§27/§28 citations) are untouched. 2550 -> 2271
lines; 34 headers intact, TOC anchors still resolve.
Remaining split pieces (own commits): guides §8/§9 -> E4, comparison §15 +
FAQ §17 -> E3.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
THEMING §14 described motion as "deferred / data-motion-ref does not exist /
superseded by the TSC event:* scope". eidos-motion.md says the opposite: the
two-moment model is implemented (F1-F7, 2026-06-04), the engine was relocated to
arts/motion as a service, and it is the event:* scope that is now obsolete. §14
was a stale snapshot contradicting the canonical motion doc.
Rewrite §14 as a lean pointer to eidos-motion.md (canonical, current) with a
status note flagging the obsolete data-motion-ref / event:* framing, and keep
the theming-specific bit (the --motion-scale-lift "pickup" token). Renumber-safe
— §14 stays §14, so the §N citations across the corpus are untouched.
The full stratum-split of THEMING (TSC -> E2, guides -> E4, comparison/FAQ ->
E3) is deferred: it renumbers sections that are cited by number across the
corpus + code, so it needs a dedicated pass with a citation sweep.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A single E3 entry point cataloguing the design rationale: the 7 eidos RFCs
(color model/engine, typography/depth/shape/structure engines, scaling), the
3 arts subsystem design docs (connection/timer/session), and the cross-cutting
decision logs (LIBRO_VARIACIONES, GESTURES). Each entry gives status + the one
decision it records, linking the document for the full argument.
This delivers the "naming único" goal at the index level. The physical file
rename (*_RFC -> rfc-*, DESIGN_* -> design-*) is deferred: those names are cited
as provenance anchors in ~30 source files (eidos/lib/*.ts, arts/timer/*,
arts/color/*, tests), so a rename only pays off if every citation is swept in
the same pass. The index gives consistent naming without that churn.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The "3 duplicate checklists" diagnosis was wrong. There are two legitimate,
complementary artifacts plus one redundant summary:
- COMPONENT_GUIDE.md — the build checklist (ordered authoring steps 1-40 +
rationale rules A1-A37). How to build a component.
- COMPONENT_COMPLETION_CHECKLIST.md — the acceptance matrix (machine-audited
rules with severity/applicability, bound to scripts/component-audit.ts). When
a component counts as done. Merging it into the guide would break the
script binding.
Consolidation = one source per concern, not one file. Both docs now carry a
header that states their role and cross-links the other as the complement.
soma/README §9 (the only real copy) is reduced to a pointer at both; it keeps
no checklist of its own.
Flagged out of scope: COMPONENT_COMPLETION_CHECKLIST M-3.3 still says "7
families" (canon is 8 with delegate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The two docs overlapped ~80% (purpose, layers, runtime parts, Soma class,
data-* contracts, naming, checklist). Give each a single role:
- README (1057→400 L): onboarding + authoring guide — purpose, membership
criterion, morfo contract (slim), component + composition pattern, new-
component checklist, and a "deep reference" map pointing into the
architecture doc. Inventory now points at the live directory tree instead
of a hardcoded (drifting) list.
- SOMA_ARCHITECTURE (969→1043 L): the complete deep reference. Absorbed the
few reference bits that only lived in the README — mergeProps, KEYS /
directional keys, focus / roving / scroll-lock, boolean attr helpers, the
internal context() helper and the reactive type-aliases — into a new
§8.bis. Trimmed its purpose section (now owned by the README).
README sections renumbered contiguously; cross-references verified, no other
doc links soma/README by section number.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Close the Phase 1b debt: the "## Handoff 2026-05-14" blocks embedded at
the top of arts/README, arts/adom/README and arts/format/README move to
docs/process/handoffs-2026-05.md, so the layer references read as
timeless. Same mechanical pattern already applied to the UIX READMEs in
41c3b0f9.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Self-contained hand-off to resume the documentation-corpus reorganization in a
fresh session: objective, work rules (no agents, Castilian, never touch
words/palabras, verify-staged), agreed decisions (EN target, hybrid layout,
docs/process for the ephemeral, the E0–E5 strata, canon links code for values),
what's done (Phases 1–2 + Phase 3 2/3, with commit hashes), and what's pending
(soma de-dup — heavy, do with fresh context; the 3 arts hand-offs from 1b debt;
Phases 4–5; deferred items). Lives in docs/process/ (a hand-off is process, not
a CONTINUE-*.md loose at the repo root — which is what we've been removing).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 3 (E1), per the chosen scope. active_architecture.md should read as a
timeless architecture reference:
- §0 "Handoff 2026-05-14" → "## 0. Contratos mínimos por módulo": dropped the
session framing (estado acordado, open/closed questions, P1/P2/P3 findings,
frontend context); kept the minimum-contracts table as reference. The
ownership/degradation rules it stated are now timeless in active-uix/README.
- §10 "Estado actual (2026-05-17)" → a one-line §10 pointing at docs/process/.
The dated status snapshot moved verbatim to
docs/process/active-architecture-snapshot-2026-05.md (kept for traceability;
several of its "pendientes" are since done). Section numbering stays continuous.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 2 of the doc-corpus cleanup. docs/CANON.md distills the immutable semantic
doctrine — the 8 families, 6 intents, intent policy, canonical verbs, the
evaluable-vs-structural rule, composition rules, and the expression-channel owner
split — anchored to TWO sources: the book "Diseñando lo que ocurre" v2.3 (cited
by chapter) and the code (linked by file:symbol, never copied).
Design choice that fixes the root cause of the drift: the canon states DOCTRINE
and LINKS the code for VALUES. It does not re-transcribe the per-family holds,
channel signatures or full verb lists — those live in verbs.ts / types.ts /
intent.ts / sema-map.ts and are linked. A second copy of a value is a future
drift (that is how "7 families" survived in three docs). From now: any doc that
needs to state a family/intent/verb/rule links CANON.md instead of pasting it.
Semantic canon only; the visual canon (TSC, color roles, EIDOS_VARIANTS) stays in
eidos/THEMING.md and is cross-linked.
Next block (pending review): redirect the docs that still re-transcribe the
vocabulary (sema/README §policy+verbs, active_architecture §6, morfo/README,
GUIA §1) to link CANON.md, and wire it into the reading-order entry.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Phase 1b of the doc-corpus cleanup: reference docs should read as timeless.
Pulled the inline "Handoff 2026-05-1x" blocks out of the six layer READMEs
(README, morfo, sema, soma, eidos, active-uix) into
docs/process/handoffs-2026-05.md, with docs/process/README.md explaining that
process/ holds ephemeral, time-stamped artifacts (hand-offs, audits, plans) —
never the source of truth.
README.md keeps its useful "visión de conjunto" pointer to active_architecture
+ GUIA, minus the hand-off framing.
Deferred on purpose: active_architecture §0 (embeds the "contratos mínimos"
table other docs link to — separated during the architecture pass) and
CLAUDE.md's ~10 session hand-offs (it is the per-session instructions file;
its own step). Docs-only.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dev