# AnnexCode – Handbuch

## 1. Überblick

AnnexCode ist der Web- und Code-Editor der Suite AnnexCREATE. Die App richtet sich an Freelancer, Selbständige und kleine Agenturen, die Websites und kleine Webprojekte bauen und auf ihrem eigenen Webspace veröffentlichen.

Kernnutzen auf einen Blick:

- **Ein Fenster für alles**: Syntax-Editor, WYSIWYG-HTML-Vorschau, Bootstrap-Komponenten, lokale Entwicklungsserver, integriertes Terminal und FTP-Workflow im bekannten Drei-Spalten-Layout der Suite.
- **Vorschau, die mitarbeitet**: Die HTML-Vorschau rendert das Projekt mit allen CSS-Dateien, lässt sich in drei Viewports prüfen und schreibt Textänderungen direkt in den Quelltext zurück.
- **Veröffentlichen ohne Zusatztools**: Server-Verbindungen verwalten, Dateien per FTP hochladen und lokale mit Remote-Dateien in der FTP-Perspektive vergleichen.
- **KI-Unterstützung nach Wahl**: lokal über Ollama oder LM Studio, oder per Cloud-Provider (Claude, Kimi, Codex) mit API-Key im macOS-Schlüsselbund.

AnnexCode ist Teil des „Creative OS" AnnexCREATE: Design-System, Asset-Bibliothek, Brandkits, Zwischenablage, Lizenzierung und Diagnostik werden mit allen anderen Apps der Suite geteilt.

## 2. Installation & Aktivierung

AnnexCode wird über **AnnexHub** installiert und verwaltet:

1. AnnexHub öffnen und im Bereich **Apps** (⌘1 in AnnexHub) AnnexCode auswählen.
2. Installieren bzw. aktualisieren – Updates werden in AnnexHub angezeigt, inklusive Changelog.
3. Die Lizenz aktivierst du in AnnexHub im Bereich **Lizenzen**: online per Lizenzschlüssel oder offline über eine signierte Aktivierungs-Datei.

**Offline-first**: AnnexCode läuft ohne Serververbindung. Editor, Vorschau, lokale Server, Terminal und die Arbeit an Projektdateien funktionieren vollständig offline. Server-Zugriff brauchst du nur für Lizenz-Updates in AnnexHub, den Upload auf deinen Webspace und Cloud-KI-Provider.

## 3. Grundworkflow

Der typische Ablauf vom Start bis zur veröffentlichten Seite:

1. **Datei anlegen oder öffnen**: Neue HTML-Datei über `Ablage ▸ Neu` (⌘N) oder ein bestehendes `.axcode`-Projekt über `Ablage ▸ Öffnen…` (⌘O) laden.
2. **Im Editor arbeiten**: Code mit Syntax-Highlighting schreiben; bei Bedarf über die Suchleiste im Editor suchen und ersetzen.
3. **Komponenten einfügen**: Fertige Bootstrap-Komponenten (z. B. Navbar, Hero, Card) per Drag & Drop aus der Sidebar in die Vorschau oder den Quelltext ziehen und im Inspector anpassen.
4. **Vorschau prüfen**: Die WYSIWYG-Vorschau in den Viewports Desktop, Tablet und Mobile kontrollieren; Textänderungen lassen sich direkt in der Vorschau vornehmen.
5. **Lokalen Server starten**: Für PHP-, Node.js- oder Python-Projekte den passenden Entwicklungsserver starten und die Vorschau über die Server-URL anzeigen.
6. **Speichern**: Projekt über `Ablage ▸ Speichern…` (⌘S) als `.axcode`-Container sichern.
7. **Verbindung einrichten**: Im Verbindungs-Manager eine Server-Verbindung anlegen (FTP, SFTP oder WebDAV; das Passwort landet im macOS-Schlüsselbund).
8. **Hochladen**: Die aktive Datei per Toolbar-Button auf den Server laden – oder vorher in der FTP-Perspektive den Sync-Stand aller Dateien vergleichen.

## 4. Kernfunktionen

### Editor, Syntax-Highlighting und Suchen & Ersetzen

Der Editor (`SyntaxTextEditor`) öffnet Dateien in Tabs und hebt Syntax für HTML, CSS, JavaScript, PHP, Python, JSON, XML, Swift und Rust hervor. Über eine einblendbare Suchleiste suchst du in der aktiven Datei und ersetzt einzelne Treffer oder alle auf einmal. Der Editor ist bewusst schlank gehalten: keine Autovervollständigung, kein Linting, kein Debugger, keine Git-Integration.

### Datei-Import

Textdateien (html, htm, css, js, php, py, json, xml, swift, rs, md, txt, csv, yaml, yml) werden beim Import direkt als Editor-Datei geöffnet. Bilder, Vektoren und PDFs laufen über die zentrale Import-Engine der Suite und landen als verknüpfte Assets mit Beschreibungsdatei im Projekt.

### WYSIWYG-HTML-Vorschau

Die Vorschau (WKWebView) rendert die aktive HTML-Datei mit allen CSS-Dateien des Projekts kombiniert. Du kannst zwischen den Viewports Desktop (1200), Tablet (768) und Mobile (375) wechseln und im Edit-Mode Text direkt in der Vorschau ändern – die Änderung wird in den HTML-Quelltext zurückgeschrieben. Umgekehrt funktioniert es auch: Ein Klick auf ein Element in der Vorschau springt zur zugehörigen Stelle im Code und markiert sie mit dem nativen Find-Indikator, ohne den Fokus aus der Vorschau zu stehlen (in der localhost-Ansicht steht der Sprung nicht zur Verfügung, weil dort kein Element-Mapping existiert). Läuft ein lokaler Server, zeigt die Vorschau optional dessen URL statt des statischen Renderings.

### Komponenten-Panel und Inspector

Das Komponenten-Panel enthält zehn fertige Bootstrap-Komponenten: Navbar, Hero, Card, Button, Formular, Footer, Grid-Row, Alert, Section und Image. Du ziehst sie per Drag & Drop in die Vorschau oder den Quelltext; der Inspector editiert ihre Eigenschaften (Text, Bild, Farbe, URL, Boolean) und schreibt die Änderungen direkt ins HTML.

### Lokale Entwicklungsserver und Package-Manager

Pro Projekt lassen sich der PHP-Built-in-Server, ein Node.js-Server (mit `npm start`-Erkennung) oder Pythons `http.server` starten, stoppen und neu starten. Ports werden automatisch aus dem Bereich 8100–8199 vergeben; das kombinierte Stdout/Stderr-Log liegt pro Projekt vor. Laufende Server werden beim Beenden der App automatisch gestoppt. Abhängig vom Tech-Stack installierst du Pakete aus der App heraus: `npm install` (Node.js-Projekte) oder `composer install` (PHP-Projekte); Ausgabe und Fehlercodes erscheinen in einem eigenen Sheet.

### Integriertes Terminal

Ein Terminal-Panel lässt sich am unteren Fensterrand einblenden: über die Toolbar oder `Darstellung ▸ Terminal ein-/ausblenden` (⌃⌘T). Es startet eine Shell-Session im Projektverzeichnis mit zeilenweiser Eingabe (bewusst kein interaktives Pseudo-Terminal). Die Ausgabe wird append-only angezeigt, bei sehr großer Menge mit Verlaufs-Limit und entsprechendem Marker. Laufende Befehle brichst du mit dem Ctrl-C-Äquivalent ab; beim Schließen des Panels werden Prozesse sauber beendet.

### Server-Verbindungen und Deployment

Im Verbindungs-Manager legst du Server-Verbindungen an und bearbeitest sie; Passwörter werden im macOS-Schlüsselbund abgelegt und nicht ins Projekt geschrieben. Den Upload der aktiven Datei startest du per Toolbar-Button mit Fortschrittsanzeige; im Picker stehen FTP, SFTP und WebDAV zur Auswahl (Listing, Upload und Download über alle drei Protokolle). Die **FTP-Perspektive** vergleicht die lokalen Projektdateien mit dem Remote-Listing und zeigt pro Datei den Sync-Status (synchron, lokal neuer, remote neuer, Konflikt, lokal fehlend, remote fehlend). Einzelne Dateien lädst du direkt aus dem Vergleich hoch oder herunter. Es ist ein manueller Vergleich – kein Auto-Sync.

### Google-Codes

Der Snippet-Generator erzeugt Codes für Google Analytics 4, Google Ads, Search Console und Tag Manager und fügt sie an der korrekten Stelle (head/body) in der `index.html` ein. Existiert für denselben Dienst und Account bereits ein Eintrag, wird er ersetzt. Die Codes werden als Projektmetadaten gespeichert.

### KI-Chat-Panel

Das KI-Panel unterstützt fünf Provider-Slots: Ollama und LM Studio lokal (ohne API-Key) sowie Claude, Kimi und Codex in der Cloud (API-Key im macOS-Schlüsselbund). Endpunkt und Modell sind frei konfigurierbar. Die aktive Editor-Datei lässt sich als Kontext an Anfragen anhängen; aus dem Editor heraus stehen Kontext-Aktionen bereit: Code erklären, refactoren und Unit-Tests generieren.

### Assets, Brandkits und Zwischenablage

Die Suite-weite Asset-Bibliothek sitzt in der Sidebar; ziehst du eine Textdatei daraus auf den Editor, wird sie als Datei geöffnet. Brandkits verknüpfst du im Inspector mit dem Projekt – deren Assets erscheinen als eigene Sidebar-Sektion mit Schnellzugriff (Asset-Pfad kopieren). Über die Annex-Zwischenablage kopierst du Dateiinhalte mit Text-Fallback für fremde Apps und registrierst Verknüpfungen zwischen Dateien und Assets.

### Menüleiste und Tastaturkürzel

AnnexCode nutzt echte macOS-Menüs:

- `Ablage ▸ Neu` – neue leere HTML-Datei (⌘N)
- `Ablage ▸ Öffnen…` – `.axcode`-Container öffnen (⌘O)
- `Ablage ▸ Speichern…` – zeigt immer das Save-Panel (⌘S)
- `AnnexCode ▸ Einstellungen…` (⌘,)
- `Darstellung ▸ Terminal ein-/ausblenden` (⌃⌘T)

Den Upload startest du über den Toolbar-Button oder mit ⌘U (öffnet den Upload-Dialog für die aktive Datei).

### Einstellungen und Mehrsprachigkeit

Die Einstellungen bündeln die Suite-Optionen (Theme/Farbschema, Diagnostik, Datenschutz) plus einen Abschnitt für die KI-Provider. Die Oberfläche ist auf Deutsch, Englisch, Spanisch, Französisch und Italienisch lokalisiert (Standard: Deutsch).

## 5. Formate & Interoperabilität

**Eigenes Format `.axcode`** in zwei Ausprägungen:

- **Annex-Container**: speichert einen Snapshot des Projekts (Dateien, Verbindungen ohne Passwörter, Projekt-URL, Brandkit-Verknüpfungen). Speichern und Laden sind in der App verdrahtet (`Ablage ▸ Speichern…` / `Ablage ▸ Öffnen…`).
- **Projekt-Paket**: Verzeichnis mit `project.json`, das Tech-Stack (Plain HTML, Bootstrap 5, Tailwind CDN, Node.js Static, PHP + Composer), Projektmetadaten, Google-Codes und Projektdateien enthält. Das Laden von Projekt-Paketen ist aktuell über die Modell-API bzw. den MCP-Host erreichbar.

**Import**: Textformate (siehe Abschnitt 4) sowie Bilder, Vektoren und PDFs als verknüpfte Assets über die Suite-Import-Engine. Einen eigenen Datei-Export (z. B. als ZIP oder statisches HTML) gibt es nicht – Dateien verlassen die App über Container-Speichern, Upload oder Zwischenablage.

**Zusammenspiel mit der Suite**:

- Annex-Zwischenablage mit Text-Fallback gegen andere Annex-Apps und fremde Apps.
- Gemeinsame Asset-Bibliothek und Brandkit-Verknüpfungen, inklusive Asset-Verlinkung über die LinkedObject-Registry.
- Verbindungen können Kunden- und Projekt-IDs tragen – als Anknüpfung an die Suite-Verwaltung.
- Beim Speichern wird das Dokument in den geteilten Versions-Index geschrieben und taucht dadurch in der zentralen Suche von AnnexHub auf.

iCloud- bzw. Cloud-Sync ist nicht verdrahtet.

## 6. MCP-Bedienung

AnnexCode ist über den MCP-Host steuerbar, der in **AnnexHub** läuft (JSON-RPC 2.0 via STDIO) und von dort gestartet wird. Damit lassen sich Aktionen der App durch KI-Agenten automatisieren.

Suite-Tools (für alle Apps):

- `list_apps` – listet alle verfügbaren Annex-Apps mit Installationsstatus und Version.
- `open_app` – öffnet eine Annex-App anhand ihrer ID.
- `open_document` – öffnet eine Datei in der angegebenen Annex-App.
- `get_active_document` – gibt Informationen zum aktiven Dokument einer App zurück.
- `get_license_status` – gibt den Lizenzstatus eines Annex-Produkts zurück.
- `search_assets` – durchsucht die zentrale Asset-Bibliothek nach Name oder Tags.

App-spezifisches Tool:

- `code.open_file` – öffnet eine Datei in AnnexCode.

Skills (suite-weit): `suite.discover`, `brandkit.apply`.

## 7. Diagnostik & Privatsphäre

AnnexCode protokolliert Fehler und Aktionen lokal über `AnnexLog` in rotierende JSON-Log-Dateien unter `~/Library/Logs/AnnexCREATE/AnnexCode/`, gespiegelt nach `os_log` (Subsystem `com.annexcreative.annexcode`). Die Protokolle werden mit einem PII-Filter geschrieben – keine Pfade, Dateinamen oder E-Mail-Adressen. Die Diagnostik ist in der Entwicklungsphase standardmäßig aktiv und in den Einstellungen (Datenschutz) abschaltbar; es findet keine Übertragung statt.

Telemetrie läuft ausschließlich per Opt-in (Standard: aus) und kann zur Laufzeit in den Einstellungen umgeschaltet werden. Passwörter für Server-Verbindungen und API-Keys der KI-Provider liegen im macOS-Schlüsselbund.

## 8. FAQ

**Brauche ich eine Internetverbindung zum Arbeiten?**
Nein. Editor, Vorschau, lokale Server, Terminal und Projektarbeit laufen offline. Netz brauchst du nur für Upload, Cloud-KI und Lizenz-/Update-Funktionen in AnnexHub.

**Kann ich per SFTP oder WebDAV hochladen?**
Ja. FTP, SFTP und WebDAV stehen im Verbindungs-Picker zur Auswahl; Listing, Upload und Download funktionieren über alle drei Protokolle – auch in der FTP-Perspektive.

**Wo werden meine FTP-Passwörter gespeichert?**
Im macOS-Schlüsselbund. Sie werden nicht ins Projekt oder den `.axcode`-Container geschrieben.

**Gibt es Git-Integration, Linting oder Autovervollständigung?**
Nein – der Editor ist bewusst schlank gehalten. Für Versionskontrolle und Checks nutzt du externe Werkzeuge, z. B. über das integrierte Terminal.

**Funktioniert die KI auch ohne Cloud-Anbieter?**
Ja. Mit Ollama oder LM Studio läuft das KI-Panel lokal und ohne API-Key.

**Wie exportiere ich mein Projekt als ZIP oder fertige Website?**
Einen eigenen Datei-Export gibt es nicht. Deine Dateien liegen im Projektverzeichnis und verlassen die App über Container-Speichern, Upload auf deinen Server oder die Zwischenablage.

**Was ist der Unterschied zwischen `.axcode`-Container und Projekt-Paket?**
Der Container ist ein einzelnes Dokument mit einem Snapshot des Projektstands; das Projekt-Paket ist ein Verzeichnis mit `project.json` und allen Projektdateien. Öffnen per Dialog unterstützt aktuell den Container.

**Synchronisiert die FTP-Perspektive automatisch?**
Nein. Sie ist ein manueller Vergleich: Du siehst den Sync-Status pro Datei und lädst einzelne Dateien gezielt hoch oder herunter.