svelte-kit-vice/docs/README.md

---
title: UIX Documentation — Start Here
type: index
audience: human + agent
authority: navigational — the single entry point to the whole doc corpus
status: current
---

# UIX Documentation — Start Here

This is the front door to the framework's documentation. If you are an agent or a
new session opening this repo, read this first: it tells you what exists, where it
lives, and the order to read it in. It is a **map**, not content — every entry
links the real document.

> **Want to run it and make a change, not just read?** →
> [`docs/getting-started.md`](./getting-started.md) — clone, run, and your first
> change, in order.

## What this framework is (60 seconds)

UIX is a Svelte 5 component system built around a **declarative contract**
(`morfo`) that the other layers consume. A component is declared once in morfo
(parts, `data-*`/ARIA, keyboard, events with a semantic family/intent); `soma`
executes the behavior, `sema` projects the perceptual signal, and `eidos`
materializes the visuals — all by reading the DOM attributes the morfo promises.

> **Morfo declares · Soma transcribes · Sema projects · Eidos paints.**

The full thesis is in [`src/uix/README.md`](../src/uix/README.md); the deep
architecture in [`src/uix/active_architecture.md`](../src/uix/active_architecture.md).

## The strata

The corpus is organized in layers of permanence, not by folder:

| Stratum | What it is | Where |
| --- | --- | --- |
| **E0 — orientation** | this file; the narrative entry; the glossary | `docs/README.md`, `src/uix/README.md`, `docs/glossary.md` |
| **E1 — architecture** | how the layers fit | `active_architecture.md` + per-layer READMEs |
| **E2 — canon** | the fixed vocabulary & contracts | `CANON.md`, `eidos/TSC.md`, `GUIA_IMPLEMENTACION_SEMAUIX.md` |
| **E3 — decisions / RFC** | *why* it is built this way | `decisions.md` + the RFCs & decision logs |
| **E4 — guides** | how to do a thing | `COMPONENT_GUIDE.md`, `THEMING*` |
| **E5 — module reference** | per-artifact docs | `arts/*/README`, `libs/*`, `svrs/*` |
| **process** | ephemeral (hand-offs, snapshots, audits) | `docs/process/` — never a source of truth |

Writing or editing docs? The conventions that keep this corpus drift-free —
link the canon, don't copy it; keep reference docs timeless; one source per
concern — are in [`docs/authoring.md`](./authoring.md).

## Reading order for a fresh start

1. **[`src/uix/README.md`](../src/uix/README.md)** — the thesis: the four layers, what makes it different, what it is not.
2. **[`src/uix/active_architecture.md`](../src/uix/active_architecture.md)** — the deep architecture: the transcription chain, the DOM-primitive ownership table, the hard rules.
3. **[`docs/CANON.md`](./CANON.md)** — the semantic vocabulary (8 families, intents, verbs, channels). **Single source of truth — every other doc links here instead of re-stating it.**
4. Then the **layer reference** for whatever you are touching (table below).

Keep the [**glossary**](./glossary.md) open while you read — it defines the
invented vocabulary (morfo, archetype, hold, TSC, …) one line each.

## The map

### E1 — Architecture

| Doc | Layer |
| --- | --- |
| [`src/uix/active_architecture.md`](../src/uix/active_architecture.md) | The whole system — start here for depth |
| [`morfo/README.md`](../src/uix/morfo/README.md) | The declarative contract (DNA) |
| [`soma/README.md`](../src/uix/soma/README.md) · [`SOMA_ARCHITECTURE.md`](../src/uix/soma/SOMA_ARCHITECTURE.md) | Headless behavior — README onboards, ARCHITECTURE is the deep reference |
| [`sema/README.md`](../src/uix/sema/README.md) | Perceptual engine + channels (sound/haptic) + cascade |
| [`eidos/README.md`](../src/uix/eidos/README.md) | The visual layer |
| [`active-uix/README.md`](../src/uix/active-uix/README.md) | Composition root (boot modes) |
| [`arts/README.md`](../src/arts/README.md) | Runtime artifacts (`Engine*`/`Active*`) |

### E2 — Canon

| Doc | What it fixes |
| --- | --- |
| [`docs/CANON.md`](./CANON.md) | The semantic vocabulary — authoritative |
| [`eidos/TSC.md`](../src/uix/eidos/TSC.md) | Token Scope Contract — where every eidos token may be emitted |
| [`src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md`](../src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md) | The canonical implementation guide (families, color subsets, holds, a11y) — authoritative for any new wrapper |

### E3 — Decisions / RFC

| Doc | What it records |
| --- | --- |
| [`docs/decisions.md`](./decisions.md) | The RFC/design index — entry to all rationale |
| [`src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md`](../src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md) | Where the implementation deviates from / extends the book |
| [`eidos/CHANNELS_SYNTHESIS.md`](../src/uix/eidos/CHANNELS_SYNTHESIS.md) | The eight expression channels, synthesized |
| [`eidos/THEMING_NOTES.md`](../src/uix/eidos/THEMING_NOTES.md) | Theming: comparison vs reference libs + FAQ |

### E4 — Guides

| Doc | How to |
| --- | --- |
| [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/COMPONENT_GUIDE.md) | Build a component (ordered steps + rules A1–A37) |
| [`src/uix/COMPONENT_COMPLETION_CHECKLIST.md`](../src/uix/COMPONENT_COMPLETION_CHECKLIST.md) | Decide when a component is *done* (machine-audited) |
| [`eidos/THEMING.md`](../src/uix/eidos/THEMING.md) · [`THEMING_GUIDE.md`](../src/uix/eidos/THEMING_GUIDE.md) | Theming reference (E1) + the add-component / define-theme how-tos (E4) |
| [`eidos/components/README.md`](../src/uix/eidos/components/README.md) | The eidos component pattern |
| [`web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md`](../web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md) | Author an interactive demo page |

### E5 — Module reference

Per-artifact READMEs live next to the code: `src/arts/{name}/README.md` (indexed
in [`arts/README.md`](../src/arts/README.md)), plus the pure helpers in `src/libs/`
and the server-authoritative engines in `src/svrs/`.

## "I want to…"

| Goal | Go to |
| --- | --- |
| Run it and make a first change | [`docs/getting-started.md`](./getting-started.md) |
| Understand the framework | `src/uix/README.md` → `active_architecture.md` |
| Know why UIX, not Radix / Mantine | [`docs/comparison.md`](./comparison.md) |
| Know what a family / intent / verb means | `docs/CANON.md` |
| Build a new component | `soma/COMPONENT_GUIDE.md` |
| Know if a component is finished | `src/uix/COMPONENT_COMPLETION_CHECKLIST.md` (`npm run component:audit`) |
| Theme it / add a token | `eidos/THEMING.md` + `eidos/TSC.md` |
| Understand why a decision was made | `docs/decisions.md` → the relevant RFC / `LIBRO_VARIACIONES` |
| Use a runtime artifact (auth, cache, http, …) | `arts/README.md` + `src/arts/{name}/README.md` |
| **Write or edit documentation** | [`docs/authoring.md`](./authoring.md) — the authoring rules |
| Test or validate a change | [`docs/testing-and-tooling.md`](./testing-and-tooling.md) — tests, validators, codegen, SSR |

## Authoritative sources & rules

- **Editorial source**: [`docs/Disenando_lo_que_ocurre_v2_3.md`](./Disenando_lo_que_ocurre_v2_3.md) — the book *Diseñando lo que ocurre* (v2.3), the origin of the semantic canon. (Currently untracked; the local editorial reference.)
- **Agent rules**: [`CLAUDE.md`](../CLAUDE.md) and [`AGENTS.md`](../AGENTS.md) — the build/test commands, code style, and the hard rules. Read these before editing.

## Process (ephemeral — not a source of truth)

[`docs/process/`](./process/) holds session hand-offs, architecture snapshots and
audits. They record *what happened*, not *what is true* — the docs above are the
truth. The active corpus-migration state is in
[`docs/process/CONTINUE-docs-corpus.md`](./process/CONTINUE-docs-corpus.md).

> **Note**: `soma/components/words` + `eidos/components/palabras` are an active,
> separate development track and are deliberately outside this corpus.
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								---
 								title: UIX Documentation — Start Here
 								type: index
 								audience: human + agent
 								authority: navigational — the single entry point to the whole doc corpus
 								status: current
 								---
 								# UIX Documentation — Start Here
 								This is the front door to the framework's documentation. If you are an agent or a
 								new session opening this repo, read this first: it tells you what exists, where it
 								lives, and the order to read it in. It is a **map**, not content — every entry
 								links the real document.
-												docs(corpus): add docs/getting-started.md — clone to first change

The narrative onboarding path that complements the map (docs/README.md) and the
build guide (COMPONENT_GUIDE): run it, the mental model, and your first change,
in order. Grounded in the real routes (/uix/components/*, /active, /temas) and
the real scripts (check / test / morfo:check / smoke / component:audit /
perm:check), it points at COMPONENT_GUIDE / THEMING_GUIDE rather than
duplicating them.

The centerpiece is "see the whole architecture in one element": inspect a toggle
and watch morfo's data-toggle, soma's data-state, sema's data-event-* and eidos's
CSS all on one node — the doctrine made visible.

Wired into docs/README.md (top callout + first "I want to…" row).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								> **Want to run it and make a change, not just read?** →
 								> [`docs/getting-started.md`](./getting-started.md) — clone, run, and your first
 								> change, in order.
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								## What this framework is (60 seconds)
 								UIX is a Svelte 5 component system built around a **declarative contract**
 								(`morfo`) that the other layers consume. A component is declared once in morfo
 								(parts, `data-*`/ARIA, keyboard, events with a semantic family/intent); `soma`
 								executes the behavior, `sema` projects the perceptual signal, and `eidos`
 								materializes the visuals — all by reading the DOM attributes the morfo promises.
 								> **Morfo declares · Soma transcribes · Sema projects · Eidos paints.**
 								The full thesis is in [`src/uix/README.md`](../src/uix/README.md); the deep
 								architecture in [`src/uix/active_architecture.md`](../src/uix/active_architecture.md).
 								## The strata
 								The corpus is organized in layers of permanence, not by folder:
 								| Stratum | What it is | Where |
 								| --- | --- | --- |
-												docs(corpus): add docs/glossary.md — the invented vocabulary, one line each

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>

											
										
										
											4 months ago
+								| **E0 — orientation** | this file; the narrative entry; the glossary | `docs/README.md`, `src/uix/README.md`, `docs/glossary.md` |
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								| **E1 — architecture** | how the layers fit | `active_architecture.md` + per-layer READMEs |
 								| **E2 — canon** | the fixed vocabulary & contracts | `CANON.md`, `eidos/TSC.md`, `GUIA_IMPLEMENTACION_SEMAUIX.md` |
 								| **E3 — decisions / RFC** | *why* it is built this way | `decisions.md` + the RFCs & decision logs |
 								| **E4 — guides** | how to do a thing | `COMPONENT_GUIDE.md`, `THEMING*` |
 								| **E5 — module reference** | per-artifact docs | `arts/*/README`, `libs/*`, `svrs/*` |
 								| **process** | ephemeral (hand-offs, snapshots, audits) | `docs/process/` — never a source of truth |
-												docs(corpus): add docs/authoring.md — the rules for writing docs here

So a session or agent that creates or edits documentation does it consistently
with the corpus, not against it. Codifies what the migration learned, each rule
tied to the failure it fixes:

1. Link the canon, never copy it (the anti-drift law — "7 families" survived in
   three docs because they re-transcribed instead of linking).
2. Every doc belongs to one stratum (E0-E5 / process); where each kind lives.
3. Reference docs are timeless — hand-offs, dated status and hardcoded catalogs
   go to process/ or become pointers.
4. One source per concern; two docs on a subject get distinct stated roles.
5. Frontmatter convention.
6. Sections cited by §N are load-bearing — stub-split, never silently renumber;
   verify moved links resolve.
7. English target; code comments always English.
8. Naming (rfc-* / design-*), markdown relative links, pre-commit checklist.

Wired into docs/README.md ("I want to… write a doc" + a note after the strata).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								Writing or editing docs? The conventions that keep this corpus drift-free —
 								link the canon, don't copy it; keep reference docs timeless; one source per
 								concern — are in [`docs/authoring.md`](./authoring.md).
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								## Reading order for a fresh start
 . **[`src/uix/README.md`](../src/uix/README.md)** — the thesis: the four layers, what makes it different, what it is not.
 . **[`src/uix/active_architecture.md`](../src/uix/active_architecture.md)** — the deep architecture: the transcription chain, the DOM-primitive ownership table, the hard rules.
 . **[`docs/CANON.md`](./CANON.md)** — the semantic vocabulary (8 families, intents, verbs, channels). **Single source of truth — every other doc links here instead of re-stating it.**
 . Then the **layer reference** for whatever you are touching (table below).
-												docs(corpus): add docs/glossary.md — the invented vocabulary, one line each

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>

											
										
										
											4 months ago
+								Keep the [**glossary**](./glossary.md) open while you read — it defines the
 								invented vocabulary (morfo, archetype, hold, TSC, …) one line each.
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								## The map
 								### E1 — Architecture
 								| Doc | Layer |
 								| --- | --- |
 								| [`src/uix/active_architecture.md`](../src/uix/active_architecture.md) | The whole system — start here for depth |
 								| [`morfo/README.md`](../src/uix/morfo/README.md) | The declarative contract (DNA) |
 								| [`soma/README.md`](../src/uix/soma/README.md) · [`SOMA_ARCHITECTURE.md`](../src/uix/soma/SOMA_ARCHITECTURE.md) | Headless behavior — README onboards, ARCHITECTURE is the deep reference |
 								| [`sema/README.md`](../src/uix/sema/README.md) | Perceptual engine + channels (sound/haptic) + cascade |
 								| [`eidos/README.md`](../src/uix/eidos/README.md) | The visual layer |
 								| [`active-uix/README.md`](../src/uix/active-uix/README.md) | Composition root (boot modes) |
 								| [`arts/README.md`](../src/arts/README.md) | Runtime artifacts (`Engine*`/`Active*`) |
 								### E2 — Canon
 								| Doc | What it fixes |
 								| --- | --- |
 								| [`docs/CANON.md`](./CANON.md) | The semantic vocabulary — authoritative |
 								| [`eidos/TSC.md`](../src/uix/eidos/TSC.md) | Token Scope Contract — where every eidos token may be emitted |
 								| [`src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md`](../src/docs/GUIA_IMPLEMENTACION_SEMAUIX.md) | The canonical implementation guide (families, color subsets, holds, a11y) — authoritative for any new wrapper |
 								### E3 — Decisions / RFC
 								| Doc | What it records |
 								| --- | --- |
 								| [`docs/decisions.md`](./decisions.md) | The RFC/design index — entry to all rationale |
 								| [`src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md`](../src/docs/LIBRO_VARIACIONES_Y_EXTENSIONES.md) | Where the implementation deviates from / extends the book |
 								| [`eidos/CHANNELS_SYNTHESIS.md`](../src/uix/eidos/CHANNELS_SYNTHESIS.md) | The eight expression channels, synthesized |
 								| [`eidos/THEMING_NOTES.md`](../src/uix/eidos/THEMING_NOTES.md) | Theming: comparison vs reference libs + FAQ |
 								### E4 — Guides
 								| Doc | How to |
 								| --- | --- |
 								| [`soma/COMPONENT_GUIDE.md`](../src/uix/soma/COMPONENT_GUIDE.md) | Build a component (ordered steps + rules A1–A37) |
 								| [`src/uix/COMPONENT_COMPLETION_CHECKLIST.md`](../src/uix/COMPONENT_COMPLETION_CHECKLIST.md) | Decide when a component is *done* (machine-audited) |
 								| [`eidos/THEMING.md`](../src/uix/eidos/THEMING.md) · [`THEMING_GUIDE.md`](../src/uix/eidos/THEMING_GUIDE.md) | Theming reference (E1) + the add-component / define-theme how-tos (E4) |
 								| [`eidos/components/README.md`](../src/uix/eidos/components/README.md) | The eidos component pattern |
 								| [`web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md`](../web/routes/uix/lib/DEMO_AUTHORING_GUIDE.md) | Author an interactive demo page |
 								### E5 — Module reference
 								Per-artifact READMEs live next to the code: `src/arts/{name}/README.md` (indexed
 								in [`arts/README.md`](../src/arts/README.md)), plus the pure helpers in `src/libs/`
 								and the server-authoritative engines in `src/svrs/`.
 								## "I want to…"
 								| Goal | Go to |
 								| --- | --- |
-												docs(corpus): add docs/getting-started.md — clone to first change

The narrative onboarding path that complements the map (docs/README.md) and the
build guide (COMPONENT_GUIDE): run it, the mental model, and your first change,
in order. Grounded in the real routes (/uix/components/*, /active, /temas) and
the real scripts (check / test / morfo:check / smoke / component:audit /
perm:check), it points at COMPONENT_GUIDE / THEMING_GUIDE rather than
duplicating them.

The centerpiece is "see the whole architecture in one element": inspect a toggle
and watch morfo's data-toggle, soma's data-state, sema's data-event-* and eidos's
CSS all on one node — the doctrine made visible.

Wired into docs/README.md (top callout + first "I want to…" row).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								| Run it and make a first change | [`docs/getting-started.md`](./getting-started.md) |
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								| Understand the framework | `src/uix/README.md` → `active_architecture.md` |
-												docs(corpus): add docs/comparison.md — honest framework-level positioning

Where UIX sits relative to the two families (headless behavior: Radix/Ark/bits/
React Aria; styled systems: Mantine/Chakra/Radix Themes/shadcn), grounded in
UIX's own documented design choices rather than claims about competitors'
internals:

- morfo as a single declarative contract (compile-time drift),
- a perception layer (sema) neither family has,
- two-moment motion, theme-as-retint, validated token scope, graceful
  degradation,
- and the honest trade-offs (more to learn, smaller ecosystem, sema only pays
  off if used).

The one competitor-specific claim (Chakra collapses presence onto one axis) is
sourced in eidos-motion.md. Per-component prop-parity comparisons stay in each
component README, by doctrine. Wired into docs/README.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								| Know why UIX, not Radix / Mantine | [`docs/comparison.md`](./comparison.md) |
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
+								| Know what a family / intent / verb means | `docs/CANON.md` |
 								| Build a new component | `soma/COMPONENT_GUIDE.md` |
 								| Know if a component is finished | `src/uix/COMPONENT_COMPLETION_CHECKLIST.md` (`npm run component:audit`) |
 								| Theme it / add a token | `eidos/THEMING.md` + `eidos/TSC.md` |
 								| Understand why a decision was made | `docs/decisions.md` → the relevant RFC / `LIBRO_VARIACIONES` |
 								| Use a runtime artifact (auth, cache, http, …) | `arts/README.md` + `src/arts/{name}/README.md` |
-												docs(corpus): add docs/authoring.md — the rules for writing docs here

So a session or agent that creates or edits documentation does it consistently
with the corpus, not against it. Codifies what the migration learned, each rule
tied to the failure it fixes:

1. Link the canon, never copy it (the anti-drift law — "7 families" survived in
   three docs because they re-transcribed instead of linking).
2. Every doc belongs to one stratum (E0-E5 / process); where each kind lives.
3. Reference docs are timeless — hand-offs, dated status and hardcoded catalogs
   go to process/ or become pointers.
4. One source per concern; two docs on a subject get distinct stated roles.
5. Frontmatter convention.
6. Sections cited by §N are load-bearing — stub-split, never silently renumber;
   verify moved links resolve.
7. English target; code comments always English.
8. Naming (rfc-* / design-*), markdown relative links, pre-commit checklist.

Wired into docs/README.md ("I want to… write a doc" + a note after the strata).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								| **Write or edit documentation** | [`docs/authoring.md`](./authoring.md) — the authoring rules |
-												docs(corpus): add docs/testing-and-tooling.md — testing, validation, codegen, SSR

Consolidates the cross-cutting verification story that was scattered across
package.json, COMPONENT_GUIDE and SOMA_ARCHITECTURE into one reference:

- The two-project vitest suite (browser client / node server) and how to run one.
- Each validator and the class of bug it catches: morfo:check (DOM vs contract),
  morfo:vocabulary (verb drift), component:audit (acceptance), perm:check
  (state transitions), smoke (hydration), translations:check, eidos-lint.
- Codegen vs authored: generate:eidos-css, generate:contracts-docs, and the
  compileMorfo primitive.
- The SSR posture: dom:false -> disabledDom, ActiveDom owner-document resolution,
  ornamental sema, and why smoke (not HTTP 200) is what catches hydration bugs.

All grounded in the real package.json scripts. Wired into docs/README.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											4 months ago
+								| Test or validate a change | [`docs/testing-and-tooling.md`](./testing-and-tooling.md) — tests, validators, codegen, SSR |
-												docs(corpus): add docs/README.md — the corpus entry point (E0), wire it from CLAUDE.md

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>

											
										
										
											4 months ago
 								## Authoritative sources & rules
 								- **Editorial source**: [`docs/Disenando_lo_que_ocurre_v2_3.md`](./Disenando_lo_que_ocurre_v2_3.md) — the book *Diseñando lo que ocurre* (v2.3), the origin of the semantic canon. (Currently untracked; the local editorial reference.)
 								- **Agent rules**: [`CLAUDE.md`](../CLAUDE.md) and [`AGENTS.md`](../AGENTS.md) — the build/test commands, code style, and the hard rules. Read these before editing.
 								## Process (ephemeral — not a source of truth)
 								[`docs/process/`](./process/) holds session hand-offs, architecture snapshots and
 								audits. They record *what happened*, not *what is true* — the docs above are the
 								truth. The active corpus-migration state is in
 								[`docs/process/CONTINUE-docs-corpus.md`](./process/CONTINUE-docs-corpus.md).
 								> **Note**: `soma/components/words` + `eidos/components/palabras` are an active,
 								> separate development track and are deliberately outside this corpus.