Qué instalar, cómo está organizado el repositorio, los comandos del día a día y las reglas de cambio.
Implementado. Esta página describe el flujo de trabajo del repositorio. Las reglas de cada zona viven en los
CLAUDE.mdanidados y en.claude/rules/; esta página es el mapa de entrada.
La toolchain (Bun exacto de .bun-version, Zig 0.17.0 de native/zig/build.zig.zon, Docker
con Compose v2, el submódulo docs/references/quic-zig) la prepara y la comprueba
scripts/dev/bootstrap.sh: ver Puesta en marcha de un nodo. El recorrido entero,
de desarrollar a publicar, está en Ciclo de vida.
| Directorio | Qué hay |
|---|---|
apps/ | Servicios Elysia @styx/*-svc, la web, y el contenido de la documentación (apps/docs) |
packages/ | Núcleo compartido @styx/*, plugins propios y componentes de interfaz |
native/ | Data plane en Zig (media-core, media-daemon, transmux, libav-bridge) |
protocols/ | Protocolos binarios entre Bun y Zig |
spikes/ | Experimentos desechables: los hallazgos pasan a ADR, fixtures o contratos y el código se elimina |
integrations/ | Adaptadores de sistemas externos |
tools/ | Herramientas permanentes promovidas de experimentos (harness de gates, soak) |
scripts/ | Guardas y generadores |
docs/ | Gobernanza interna: ADR, tickets, planes, evidencia, revisiones. Su primer nivel está cerrado |
deploy/, docker/ | Compose y Dockerfiles por servicio (los Dockerfiles no están en deploy/) |
apps/docs/ (el sitio de documentación) y docs/ (la gobernanza) son cosas distintas: el sitio
se genera de la gobernanza y del código, nunca al revés.
| Comando | Qué hace |
|---|---|
bun install --frozen-lockfile | Dependencias del workspace, sin tocar bun.lock |
bun run typecheck | Comprueba tipos de cada proyecto de references por separado (un tsgo sin más no recorre las referencias) |
bun run lint | oxlint |
bun run test | Vitest de la raíz. No recoge apps/cli (bun run --cwd apps/cli test, con el runner de Bun) ni la integración de apps/identity-svc |
bun run format:check | Prettier |
bun run build | El build de cada workspace: Rolldown + .d.ts en paquetes, bundle AOT en servicios, Vite en web y docs, binario compilado en apps/cli |
bun run check:roadmap | Las guardas de gobernanza (ver guardas) |
bun run check:context | La jerarquía de contexto coincide con el árbol real |
zig build y zig build test | Desde native/zig/: el daemon y sus tests. El build de la raíz no cubre Zig |
bun run test:zig:tsan | Carril de TSAN del data plane |
bun run docs:gen / docs:check | Genera o comprueba la referencia generada de la documentación |
bun run release:plan | Qué versión saldría para cada componente y por qué (ver Ciclo de vida) |
bun run dev / dev:ts / dev:zig | dev lanza el script dev de todos los workspaces; dev:ts y dev:zig abren una sesión de mks-dev-session, que no es dependencia del repo y hay que tenerlo instalado aparte |
Un servicio no arranca suelto con su bun run dev sin su configuración: la base de datos
(DATABASE_URL), la identidad del bus (SPIRE_SEED, SPIRE_KEYRING, SPIRE_NATS_NKEY_SEED),
el proveedor OIDC en identity-svc o el socket del daemon, según el servicio. La lista está en la
cabecera de su src/bootstrap.ts. Cómo levantar la pila entera en local está en
Puesta en marcha de un nodo.
[#track/docs]), sin coautoría ni atribución de herramientas, uno por paso verde. La
preparación (staging) es explícita por ruta.CLAUDE.md: ni el estado de un gate, ni la cola de tickets, ni hashes
de commits. Eso se lee de sus fuentes (styx.model.yml, los tickets, el registro de progreso).bun.lock sólo lo regenera el Bun de .bun-version (lockfile v2); CI y las imágenes
instalan con --frozen-lockfile.Antes de tocar una zona, lee su CLAUDE.md (apps/, apps/web/, packages/,
packages/plugins/, native/, native/zig/, protocols/, docs/) y las reglas de
.claude/rules/ que cargan por ruta.