Truths — Plattform-Wahrheiten

Diese Seite ist die zentrale Truth-Registry. Truths sind festgehaltene Wahrheiten, die über Repos, Docs und Implementierung hinweg gelten. Andere Seiten referenzieren Truth-IDs — sie formulieren dieselbe Wahrheit nicht erneut aus.

Das Truth-Prinzip

Truths sind SSOT — und das ist selbst eine Truth. T-TRUTHS-SSOT

Das Prinzip gilt überall, wo in ADDXION dokumentiert oder gebaut wird:

Ort	Pflicht
addxion-docs (jede Seite)	## Truths mit relevanten IDs am Ende
addxion-docs (diese Seite)	Volltext jeder Truth — einzige Heimat
Consumer-Repos (süper, addxion-ai, …)	AGENTS.md → Verweis auf /docs/ecosystem/truths/ + relevante IDs
Produkt-MASTERPLANs	Verlinken, nicht paraphrasieren
Guidance-Seiten (z. B. Einmal pflegen)	Ausarbeitung und Beispiele — kanonische Formulierung bleibt hier

Neue Erkenntnis / festes Prinzip?
  ├─ Gilt ökosystem- oder architekturweit?
  │     ├─ Ja → Truth-ID in truths.md anlegen
  │     │       → betroffene Doc-## Truths + Consumer-AGENTS.md aktualisieren
  │     └─ Nein → nur Produkt-MASTERPLAN oder lokale Doc
  └─ Bereits als Truth vorhanden?
        └─ Nur referenzieren (T-…), nicht erneut als „Prinzip“ formulieren

Truths vs. Für Agents: Truths = was gilt (Wahrheit). ## Für Agents = was zu tun ist (Handlung). Beides am Ende jeder Doc-Seite. Spezifikation: Documentation as Code.

Neue oder geänderte Truths: nur hier pflegen, dann betroffene Doc-Seiten, scripts/ensure-doc-sections.mjs und Consumer-AGENTS.md verlinken.

Meta

T-TRUTHS-SSOT

Truths haben eine einzige Heimat: addxion-docs → diese Seite. Docs, MASTERPLANs und AGENTS.md in Consumer-Repos verweisen per ID (T-…), duplizieren keine Truth-Tabellen.

Meta: Dieses SSOT-Prinzip ist selbst eine Truth — es gilt auch für die Art, wie Truths dokumentiert werden. Keine parallele „Prinzipien“- oder „Wahrheiten“-Sammlung in anderen Repos.

T-DOC-SECTIONS

Jede Doc-Seite in src/content/docs/ trägt zwei Pflicht-Sektionen am Ende: ## Truths (geltende Wahrheiten) und ## Für Agents (Handlungsregeln). Spezifikation: Documentation as Code.

T-AGENTS-REPO

Jedes Repo, in dem gebaut oder dokumentiert wird, hat ein AGENTS.md mit Verweis auf relevante Truths und Plattform-Docs — nicht als zweite Truth-Quelle.

---

Ökosystem

T-NORTH-STAR

Durchgängiges Nutzererlebnis über süper, addxion.ai und addxion.com. Gleiche Design-Sprache, gemeinsame Auth, getrennte App-Daten pro Produkt.

T-MAINTAIN

Einmal pflegen: So gut wie möglich keine doppelte Pflege in mehreren Projekten. Shared Packages und systematische Vereinfachung vor parallelen Kopien. Ausarbeitung: Einmal pflegen.

T-PLATFORM-SSOT

Plattform-Wahrheit (Package-Grenzen, Architektur, Roadmap-Status) lebt nur in addxion-docs. Produkt-MASTERPLANs verlinken dorthin.

T-REPO-BOUNDARY

Jedes Repo hat eine klare Verantwortung. SSOT pro Inhaltstyp: Repo Boundaries.

T-DOCS-SYNC

Docs werden im gleichen PR-Zyklus wie ökosystem-relevante Code-Änderungen aktualisiert. Prozess: Docs-Sync.

---

Packages

T-PKG-NEON

Öffentlicher Design-Package-Name: @addxion/neon. @addxion/core ist interne Engine, kein Consumer-Einstieg.

T-PKG-SHELL

@addxion/shell = Nutzer-Schnittstellen-Schicht (Layout, Chat, Command, Gates). Nicht bash/zsh. Chat ist Shell-Komponente, keine Feature-Seite.

T-PKG-XI

@addxion/xi = ein Package, Subpath-Exports (protocol, nav, runtime). Cross-App-Glue only — kein UI, keine Docs-Sidebar.

T-EVOLUTION-CORE

EvolutionCore ist der portable Evolutionskern (eigenes Elixir-Repo): mutieren → trialen → scoren → committen, mit Versionierung und Rollback. Apps und andere Systeme sind Umgebungen (World) hinter Ports (observe / act / evaluate / constrain). @addxion/xi/runtime ist der TypeScript-Port/Client — nicht die Evolutionslogik und kein Chat-Ersatz (@addxion/ai). Ausarbeitung: EvolutionCore → xi-runtime.

T-PKG-AUTH

@addxion/auth = Identity-SSOT. Kein paralleles Auth-Schema in Consumern.

T-PKG-AI

@addxion/ai = LLM-SSOT (Streaming, Message-Typen). Keine Shell-, Scroll- oder Produkt-Prompts im Package.

T-PKG-BEHAVIOR

@addxion/behavior = Scroll- und Interaktions-Entscheidungen, framework-agnostic. Kein React-DOM, kein Rendering.

T-PKG-BOUNDARY

Package-Grenzen ohne expliziten Vertrag nicht überschreiten. Tabellen: Package-Grenzen.

---

Navigation

T-NAV-MANIFEST

App-Navigation: manifest.ts pro App + @addxion/xi/nav. Keine Nav-Listen in Shell-Komponenten hardcoden.

T-NAV-THREE

Drei getrennte Nav-Schichten: xi-nav (Apps), Starlight (Docs-Content), Shell (Rendering). Nicht vermischen.

T-NAV-DOCS

Starlight-Sidebar in addxion-docs = Content-Nav. Kein xi-nav für Docs-Kapitel.

T-SHELL-PAGEHEADER

PageHeader-Struktur in @addxion/shell. Titel pro App aus manifest.ts via resolveSection. Keine lokalen Forks. Details: PageHeader — Cross-App-Sync.

T-SHELL-ICONS

App-UI-Icons (Nav, Command Palette, Shell-Chrome): lucide-react. Mapping in Consumer-Shell (app-nav-destinations.ts), nicht in manifest.ts. Details: Iconography.

T-UI-BORDERED

Bereiche trennen über eine geteilte 1px-Linie (Background Gap Trick oder shared edge) — nicht über Schatten, doppelte Borders oder floating Cards. Strukturelle Layout-Container eckig; interaktive Elemente dürfen gerundet bleiben. Ausarbeitung: Bordered Grid.

---

Daten

T-DATA-AUTH-SHARED

Identity (User, Session, Org, Grants) ist ökosystem-weit geteilt (addxion-auth).

T-DATA-APP-ISOLATED

Produkt-Daten (Chat, Fortschritt, Domänen-Tabellen) sind pro App isoliert. Kein Cross-Product-Leak.

---

Branding

T-BRAND-STRATEGY

Markenstrategie (Positionierung, Portfolio, Zielgruppe, Story, Archetype) lebt nur in addxion-docs unter /docs/branding/. Marketing-Seiten-Copy in addxion-com folgt dieser SSOT — sie formuliert die Strategie nicht parallel neu. Visuelle Markenwerte bleiben T-NEON-BRAND.

---

Neon

T-NEON-BRAND

Markenwerte (ink, cream, Fonts) leben in Consumer-brand.css — nicht in addxion-neon.

T-NEON-FONTS

Keine Google Fonts. Self-hosted Inter aus @addxion/neon/fonts/inter.css. System-Schrift hat Vorrang.

T-NEON-SECTIONS

Versionierte Sections (hero-v1, features-v1) nicht in-place überschreiben — neue Version anlegen.

---

Verwendung in Docs und Repos

In Doc-Seiten (## Truths)

## Truths

| ID | Wahrheit |
|----|----------|
| [T-MAINTAIN](/docs/ecosystem/truths/#t-maintain) | Einmal pflegen — keine Doppelpflege |
| [T-SHELL-PAGEHEADER](/docs/ecosystem/truths/#t-shell-pageheader) | PageHeader-Struktur nur in Shell |

Nur Truths auflisten, die auf dieser Seite relevant sind. Vollständige Registry: diese Seite.

In Consumer-AGENTS.md (Pflicht in jedem Build-Repo)

Jedes Repo, in dem Code oder Docs gepflegt werden, führt einen Abschnitt ## Truths:

## Truths

Plattform-Wahrheiten (SSOT): https://addxion.com/docs/ecosystem/truths/

| ID | Relevanz für dieses Repo |
|----|--------------------------|
| T-MAINTAIN | Shared Packages statt Duplikate |
| T-NAV-MANIFEST | Nav nur über manifest.ts + xi/nav |
| T-PKG-SHELL | Shell-UI aus @addxion/shell konsumieren |

Nur IDs auflisten, die in diesem Repo beim Bauen und Dokumentieren gelten. Volltext: Truth-Registry (Link oben).

Repos ohne ## Truths in AGENTS.md gelten als nicht am Truth-Prinzip ausgerichtet.

Vorlage zum Kopieren: templates/consumer-agents-truths.md im addxion-docs-Repo.

Neue Truth anlegen

1. ID vergeben (T-BEREICH-KURZNAME, stabil, kebab-case-Anker)
2. Formulierung hier eintragen
3. Betroffene Doc-## Truths-Sektionen und ggf. ensure-doc-sections.mjs aktualisieren
4. bun run build in addxion-docs

Truths

ID	Wahrheit
T-TRUTHS-SSOT	Diese Seite ist die einzige Truth-Registry
T-DOC-SECTIONS	Jede Doc-Seite: ## Truths + ## Für Agents
T-PLATFORM-SSOT	Plattform-Wahrheit nur in addxion-docs

Für Agents

Scope: Zentrale Truth-Registry — SSOT für Plattform-Wahrheiten.

• Neue Wahrheit nur hier, nicht auf Einzelseiten als Volltext duplizieren
• Truth-ID stabil halten; Umbenennung nur mit Anker-Update in allen Referenzen
• Meta-Truth T-TRUTHS-SSOT gilt für diese Seite selbst