Package-Leitfaden

Sinn, Grenzen und Status jedes ADDXION Shared Package.

Holistischer Überblick über jedes Shared Package. Für Grenztabellen siehe Package-Grenzen. Für den Schritt-für-Schritt-Plan siehe Roadmap.

Leitprinzip: Wiederkehrende Logik und UI nicht in Consumern duplizieren — in das passende Package extrahieren. Siehe Einmal pflegen.

`@addxion/neon`

Sinn: Design-System-Meta-Package. Ein Consumer-Einstieg für Tokens, Komponenten und AI-Manifest. @addxion/core bleibt interne Engine (Token-Generierung, tw:, Manifest-Pipeline) und wird über @addxion/neon re-exportiert.

Enthält:

Semantic Tokens und tw:-Utilities (@addxion/neon/styles)
Self-hosted Inter (@addxion/neon/fonts/inter.css) — siehe Typografie
React-Primitives (@addxion/neon/react — Button, Badge, Input)
AI-Manifest für Agents (@addxion/neon/manifest)
Astro-Referenzkomponenten und React-Chrome (@addxion/components, inkl. MarketingHeader)

Enthält nicht:

Markenwerte (brand.css lebt beim Consumer)
App-Logik, Auth, Chat-UI, Nav-Daten
Shell-, Behavior- oder XI-Logik

Consumer: süper, addxion.ai, addxion-docs, addxion.com (Marketing)

MarketingHeader: Struktur und Mobile-Verhalten über @addxion/components/react. Inhalt (Logo, Nav, CTAs) und Brand-Klassen im Consumer-SiteHeader. Abgrenzung zu App-PageHeader: Websites entwickeln.

Repo-Home: addxion-neon

Status: Live. Meta-Package Phase 1.4 erledigt. Vollständige Neon-Migration aller Consumer-Komponenten noch offen (siehe Roadmap).

Beziehungen: Wird von @addxion/shell für UI-Tokens genutzt. Unabhängig von @addxion/auth, @addxion/ai, @addxion/behavior, @addxion/xi.

Nicht verwenden für: Identity, LLM-Calls, Scroll-Logik, Cross-App-Navigation.

`@addxion/auth`

Sinn: Identity-SSOT für das gesamte Ökosystem. Ein Schema, eine Session, App-übergreifende Grants.

Enthält:

Better-Auth-Schema und Drizzle-Migrationen
Permissions, Rollen, Session-Handling
app_registry und app_grant (Cross-App-Zugriff)
Avatar-Handling

Enthält nicht:

Produkt-Tabellen (Theorie, Fahrstunden, Chat-Verlauf)
LLM-Client, UI-Komponenten

Consumer: süper, addxion.ai, addxion-com/cms

Repo-Home: addxion-ai/packages/auth

Status: Live. app_registry + app_grant erledigt (Phase 6.1).

Beziehungen: @addxion/xi/nav filtert Destinations nach Grants. @addxion/shell nutzt Auth für Gates (ClientAuthGate). @addxion/ai und Produkt-DBs bleiben getrennt.

Nicht verwenden für: App-spezifische Daten, Design Tokens, Nav-Manifeste.

`@addxion/ai`

Sinn: LLM-SSOT. Ein OpenRouter-Client, ein Streaming-Format, ein Message-Typ-System.

Enthält:

OpenRouter-Anbindung
Streaming-Parser und Chunk-Typen
Error-Handling für LLM-Calls

Enthält nicht:

System-Prompts (Consumer-Verantwortung)
Chat-DB (Süper-D1 vs. addxion.ai Neon)
Shell-Rendering, Scroll-Logik
RAG (Consumer oder später xi-runtime)

Consumer: süper (POST /api/ai/chat), addxion.ai

Repo-Home: addxion-ai/packages/ai

Status: Live.

Beziehungen: Liefert Stream-Chunks an @addxion/behavior (Scroll-Intent) und @addxion/shell (Chat-Surface). Unabhängig von @addxion/neon und @addxion/xi.

Nicht verwenden für: UI-Komponenten, Auth, Nav-Daten, Design Tokens.

`@addxion/behavior`

Sinn: Framework-agnostische Interaktions-Hooks. Entscheidet wann gescrollt oder haptisch feedback gegeben wird — nicht wie es aussieht.

Enthält:

useFollowStream (Follow-at-bottom während Streaming)
useScrollIntent (User-Intent: Scroll, Select, Keyboard)
useHaptic (Haptic Feedback, wo unterstützt)

Enthält nicht:

React-Komponenten, DOM-Rendering
LLM-Calls, Auth, Nav-Daten

Consumer: süper (Chat-Scroll), addxion.ai (Chat-Scroll via Shell)

Repo-Home: addxion-ai/packages/behavior

Status: Live (Phase 4 erledigt).

Beziehungen: Konsumiert Stream-Events von @addxion/ai. Wird von @addxion/shell für Chat-Anbindung genutzt. Keine Abhängigkeit zu @addxion/xi oder @addxion/neon.

Nicht verwenden für: Layout-Komponenten, Nav-Filter, LLM-Anbindung direkt.

`@addxion/shell`

Sinn: Nutzer-Schnittstellen-Schicht — nicht eine Bash-Shell. Persistente UI-Hülle um wechselnden Seiteninhalt: PageHeader, Chat, Command Palette, Gates, BottomNav.

Enthält:

PageHeader, ChatSurface, ChatShell, CommandPalette
Gates: ClientAuthGate, OnboardingGate
BottomNav, SiteFooter, PageSkeleton
Framework-Adapter: adapters/next, adapters/tanstack

Enthält nicht:

Nav-Daten (kommt aus @addxion/xi/nav)
LLM-Calls (kommt aus @addxion/ai)
Scroll-Entscheidungen (kommt aus @addxion/behavior)
Design-Tokens (kommt aus @addxion/neon)
Marketing-Header (kommt aus @addxion/components MarketingHeader)

Consumer: süper, addxion.ai. Optional: addxion-docs (Command Palette, Content-only bisher).

Repo-Home: addxion-ai/packages/shell

Status: Live (Phase 3 erledigt). süper und addxion.ai konsumieren @addxion/shell. Framework-Adapter existieren, werden aber nicht überall genutzt.

Beziehungen: Rendert Nav aus @addxion/xi/nav. Bindet @addxion/behavior für Chat-Scroll. Nutzt @addxion/neon für Tokens. Schützt Routen via @addxion/auth-Gates.

Cross-App-Sync: PageHeader ist eine gemeinsame Komponente — strukturelle Änderungen nur hier, Seitentitel pro App in manifest.ts. Siehe PageHeader — Cross-App-Sync.

Nicht verwenden für: Nav-Manifeste definieren, LLM-Streaming, Identity-Schema.

`@addxion/xi`

Sinn: Cross-App-Glue. Verbindet Apps über gemeinsame Typen, Nav-Manifeste und (langfristig) den Evolutions-Port zu EvolutionCore.

Enthält (Subpath-Exports):

@addxion/xi/protocol — Typen, Events, Deep-Link-Konventionen
@addxion/xi/nav — Manifest-Loader, Rollen-/Grant-Filter, Command-Items
@addxion/xi/runtime — Stub; langfristig Port/Client zu EvolutionCore (T-EVOLUTION-CORE, evolutioncore.md)

Enthält nicht:

Design Tokens, React-Shell-Komponenten
Docs-Sidebar (Starlight Content-Nav)
LLM-Client

Consumer: süper (manifest.ts + BottomNav + Command), addxion.ai (manifest.ts + Command Menu). Federation-Runtime in beiden Command Palettes (federated-manifests.ts).

Repo-Home: addxion-ai/packages/xi

Status: Live (Phase 2 + 6.2 erledigt). runtime bleibt Stub bis Phase 6.4.

Beziehungen: Liefert gefilterte Sections an @addxion/shell. Nutzt @addxion/auth Grants für Federation. Unabhängig von @addxion/behavior und @addxion/ai.

Nicht verwenden für: UI-Rendering, Docs-Navigation, Design System, Scroll-Hooks.

Entscheidungsmatrix

Bedarf	Package
Button, Token, Manifest	`@addxion/neon`
Login, Session, Grant	`@addxion/auth`
OpenRouter, Streaming	`@addxion/ai`
Chat-Scroll, Haptics	`@addxion/behavior`
PageHeader, Chat, Gates	`@addxion/shell`
Nav-Manifest, Cross-App-Links	`@addxion/xi`

Truths

ID	Wahrheit
T-PKG-BOUNDARY	Package-Grenzen nicht ohne Vertrag überschreiten
T-PLATFORM-SSOT	Plattform-Wahrheit nur in addxion-docs
T-TRUTHS-SSOT	Truths-Registry — referenzieren, nicht duplizieren

Für Agents

Scope: Sinn, Enthält/Enthält-nicht und Status pro Shared Package.

Holistischer Überblick; Grenztabellen in packages.md
Status-Änderungen synchron mit roadmap.md
Neue Packages oder Exports: diese Seite + packages.md + betroffenes Guidance-Doc