docs: big update

Author: Zuhaitz-dev

README.md

@@ -26,6 +26,27 @@ Deep dives into the compiler's internals and tooling protocols.
 - **[LSP Protocol](LSP.md)**: Documentation for the Zen C Language Server integration.
 - **[Plugin System](PLUGINS.md)**: How to extend the compiler with custom plugins.
 
+## Reference (16 chapters)
+
+| # | Chapter | Description |
+|:---|:---|:---|
+| 1 | [Variables & Constants](reference/01-variables-constants.md) | let, types, mutability |
+| 2 | [Primitive Types](reference/02-primitive-types.md) | int, float, bool, char, etc. |
+| 3 | [Aggregate Types](reference/03-aggregate-types.md) | Arrays, slices, tuples |
+| 4 | [Functions & Lambdas](reference/04-functions-lambdas.md) | Functions, closures |
+| 5 | [Control Flow](reference/05-control-flow.md) | if, while, for, match |
+| 6 | [Operators](reference/06-operators.md) | Arithmetic, comparison, sugar operators |
+| 7 | [Printing & F-strings](reference/07-printing-interpolation.md) | Output, string interpolation |
+| 8 | [Memory & Lifetimes](reference/08-memory-management.md) | Ownership, borrowing |
+| 9 | [OOP](reference/09-oop.md) | Traits, impl blocks, methods |
+| 10 | [Generics](reference/10-generics.md) | Type-safe templates |
+| 11 | [Concurrency](reference/11-concurrency.md) | Stackless async/await |
+| 12 | [Advanced](reference/12-advanced.md) | Inline assembly, raw blocks |
+| 13 | [Interop](reference/13-interop.md) | C, C++, CUDA, Objective-C interop |
+| 14 | [Unit Testing](reference/14-unit-testing-framework.md) | test, assert, expect |
+| 15 | [Diagnostics](reference/15-diagnostics.md) | Compiler warnings, categories |
+| 16 | [MISRA Rules](reference/16-misra-rules.md) | Safety rules, Zen-specific checks |
+
 ## Related Resources
 
 - **[zenc](https://github.com/zenc-lang/zenc)**: The core compiler source code.

raw/README.md _raw_archived/README.mdraw/README.md renamed to _raw_archived/README.md

@@ -14,41 +14,90 @@ let ints: int[SIZE] = [1, 2, 3, 4, 5];
 let zeros: [int; SIZE]; // Nullinitialisiert
 ```
 
-#### Tupel
-Mehrere Werte gruppieren, Elemente über den Index aufrufen.
+
+
+
+#### Tuples
+
+Mehrere Werte zu einem einzigen zusammengesetzten Wert gruppieren. Tupel unterstützen beliebige Stelligkeiten (2, 3, 4, … bis 10+), Verschachtelung, Mutation einzelner Felder und Destrukturierung.
+
+**Grundlegende Verwendung**
+
+```zc
+let pair = (1, "hello");
+let triple = (1, "hello", 3.14);
+let five = (1, 2, 3, 4, 5);
+let typed: (int, string, f64) = (1, "two", 3.0);
+```
+
+**Feldzugriff**
+
+Elemente werden positionell mit `.0`, `.1`, `.2` usw. oder über die rohen Strukturfeldnamen `.v0`, `.v1` zugegriffen:
+
 ```zc
-let pair = (1, "Hallo");
-let x = pair.0;  // 1
-let s = pair.1;  // "Hallo"
+let t = (1, "hello", 3.14);
+assert(t.0 == 1);
+assert(t.v1 == "hello");
 ```
 
 **Mehrere Rückgabewerte**
 
 Funktionen können Tupel zurückgeben, um mehrere Ergebnisse zu liefern:
+
 ```zc
-fn addiere_und_subtrahiere(a: int, b: int) -> (int, int) {
-    return (a + b, a - b);
+fn stats(data: int) -> (int, int) {
+    return (data * 2, data + 1);
 }
-
-let ergebnis = addiere_und_subtrahiere(3, 2);
-let summe = ergebnis.0;        // 5
-let differenz = ergebnis.1;    // 1
+let r = stats(5);
+assert(r.0 == 10);
+assert(r.1 == 6);
 ```
 
 **Destrukturierung**
 
-Tupel können direkt in Variablen zerlegt werden:
 ```zc
-let (summe, differenz) = addiere_und_subtrahiere(3, 2);
-// summe = 5, differenz = 1
+let (sum, diff) = add_and_subtract(3, 2);
+let (a: string, b: u8) = ("hello", 42);
+let (x, y: i32) = (1, 2);
 ```
 
-Typisierte Tupel-Destrukturierung ermöglicht explizite Typannotationen:
+**Verschachtelte Tupel**
+
 ```zc
-let (a: string, b: u8) = ("Hallo", 42);
-let (x, y: i32) = (1, 2);  // Gemischt: x abgeleitet, y explizit
+let nested = ((1, 2), (3, 4));
+let inner = nested.v0;
+assert(inner.v0 == 1);
 ```
 
+**Mutation**
+
+Einzelne Felder können neu zugewiesen werden:
+
+```zc
+let t = (1, 2);
+t.v0 = 99;
+```
+
+**Zeichenkettenvergleich**
+
+Tupel mit `string`-Feldern müssen für den Vergleich `strcmp()` verwenden, nicht `==` (das einen Zeigervergleich auf `char*` durchführt):
+
+```zc
+let t = (1, "hello");
+assert(strcmp(t.1, "hello") == 0);
+```
+
+**Aufzählungstupel**
+
+Aufzählungsvarianten können Tupeldaten tragen:
+
+```zc
+enum Shape {
+    Point, Line(int, int), Labeled(int, string, f64),
+}
+```
+
+
 #### Structs
 Datenstrukturen mit optionalen Bitfeldern.
 ```zc