feat: Astro Starlight Docs-Site für BTC MAIN AI Application Layer

Vollständige Dokumentations-Site mit:
- Einstieg: Einführung, Schnellstart, Kernkonzepte
- Guides: Deployment, CI/CD, Env-Vars, Domains, Logs
- API-Referenz: Überblick, Auth, Applications, Deployments
- Referenz: Tech Stack, FAQ
- Dockerfile + nginx für containerisiertes Deployment

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,6 @@
+dist/
+node_modules/
+.astro/
+.env
+.env.*
+*.local

Dockerfile

@@ -0,0 +1,12 @@
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

astro.config.mjs

@@ -0,0 +1,66 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: 'BTC MAIN · Managed AI Now',
+      description: 'Dokumentation des AI Application Layer — Deployment, Betrieb und API-Referenz',
+      defaultLocale: 'de',
+      logo: {
+        src: './src/assets/logo.svg',
+        replacesTitle: false,
+      },
+      social: [
+        { icon: 'external', label: 'BTC AG', href: 'https://www.btc-ag.com' },
+      ],
+      editLink: {
+        baseUrl: 'https://git.coolai.btc-ag.cloud/thsoring/docs/edit/main/',
+      },
+      sidebar: [
+        {
+          label: 'Einstieg',
+          items: [
+            { label: 'Einführung', slug: 'einstieg/einfuehrung' },
+            { label: 'Schnellstart', slug: 'einstieg/schnellstart' },
+            { label: 'Kernkonzepte', slug: 'einstieg/konzepte' },
+          ],
+        },
+        {
+          label: 'Anleitungen',
+          items: [
+            { label: 'App deployen', slug: 'guides/app-deployen' },
+            { label: 'CI/CD Pipelines', slug: 'guides/cicd-pipelines' },
+            { label: 'Umgebungsvariablen', slug: 'guides/umgebungsvariablen' },
+            { label: 'Custom Domains', slug: 'guides/custom-domains' },
+            { label: 'Logs & Monitoring', slug: 'guides/logs-monitoring' },
+          ],
+        },
+        {
+          label: 'API-Referenz',
+          items: [
+            { label: 'Überblick', slug: 'api/uebersicht' },
+            { label: 'Authentifizierung', slug: 'api/authentifizierung' },
+            { label: 'Applications', slug: 'api/applications' },
+            { label: 'Deployments', slug: 'api/deployments' },
+          ],
+        },
+        {
+          label: 'Referenz',
+          items: [
+            { label: 'Tech Stack', slug: 'referenz/tech-stack' },
+            { label: 'FAQ', slug: 'referenz/faq' },
+          ],
+        },
+      ],
+      customCss: ['./src/styles/custom.css'],
+      head: [
+        {
+          tag: 'meta',
+          attrs: { property: 'og:image', content: '/og-image.png' },
+        },
+      ],
+      components: {},
+    }),
+  ],
+});

nginx.conf

@@ -0,0 +1,32 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ $uri.html $uri/index.html =404;
+    }
+
+    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot|webp|avif)$ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    location ~* \.html$ {
+        add_header Cache-Control "no-cache, must-revalidate";
+    }
+
+    gzip on;
+    gzip_vary on;
+    gzip_types
+        text/plain
+        text/css
+        text/javascript
+        application/javascript
+        application/json
+        image/svg+xml;
+
+    add_header X-Frame-Options "SAMEORIGIN";
+    add_header X-Content-Type-Options "nosniff";
+    add_header Referrer-Policy "strict-origin-when-cross-origin";
+}

package.json

@@ -0,0 +1,17 @@
+{
+  "name": "btc-main-ai-docs",
+  "type": "module",
+  "version": "1.0.0",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.32.0",
+    "astro": "^5.0.0",
+    "sharp": "^0.33.0"
+  }
+}

src/assets/logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 180 36" fill="none">
+  <!-- AI Hexagon Icon -->
+  <polygon points="16,2 28,9 28,23 16,30 4,23 4,9" fill="#1a56db" opacity="0.15" stroke="#1a56db" stroke-width="1.5"/>
+  <text x="10" y="22" font-family="monospace" font-size="11" font-weight="700" fill="#1a56db">AI</text>
+  <!-- Wordmark -->
+  <text x="38" y="25" font-family="-apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="16" font-weight="800" fill="currentColor" letter-spacing="-0.5">BTC MAIN</text>
+</svg>

src/content/config.ts

@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+  docs: defineCollection({ schema: docsSchema() }),
+};

src/content/docs/api/applications.mdx

@@ -0,0 +1,210 @@
+---
+title: Applications API
+description: REST-API-Referenz für Anwendungen — anlegen, lesen, aktualisieren und löschen.
+sidebar:
+  order: 3
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+Über die Applications-API lassen sich Anwendungen auf der Plattform vollständig programmatisch verwalten.
+
+**Base URL:** `https://coolai.btc-ag.cloud/api/v1`
+
+---
+
+## Alle Anwendungen abrufen
+
+```http
+GET /applications
+```
+
+Gibt alle Anwendungen zurück, auf die der Token Zugriff hat.
+
+<Tabs>
+  <TabItem label="Request">
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/applications \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+  </TabItem>
+  <TabItem label="Response">
+
+```json
+[
+  {
+    "id": 1,
+    "uuid": "abc123...",
+    "name": "meine-app",
+    "status": "running",
+    "fqdn": "https://meine-app.btc-ag.cloud",
+    "git_repository": "https://git.coolai.btc-ag.cloud/meinteam/meine-app",
+    "git_branch": "main",
+    "build_pack": "dockerfile"
+  }
+]
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Einzelne Anwendung abrufen
+
+```http
+GET /applications/{uuid}
+```
+
+<Tabs>
+  <TabItem label="Request">
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+  </TabItem>
+  <TabItem label="Response">
+
+```json
+{
+  "uuid": "abc123...",
+  "name": "meine-app",
+  "status": "running",
+  "fqdn": "https://meine-app.btc-ag.cloud",
+  "git_repository": "https://git.coolai.btc-ag.cloud/meinteam/meine-app",
+  "git_branch": "main",
+  "build_pack": "dockerfile",
+  "ports_exposes": "3000",
+  "environment_variables": [
+    { "key": "LOG_LEVEL", "value": "info", "is_secret": false }
+  ]
+}
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Anwendung anlegen (privates Repository)
+
+```http
+POST /applications/private-deploy-key
+```
+
+Für Repositories auf `git.coolai.btc-ag.cloud`.
+
+**Request-Body:**
+
+| Feld | Typ | Pflicht | Beschreibung |
+|---|---|---|---|
+| `project_uuid` | string | ja | UUID des Projekts |
+| `server_uuid` | string | ja | UUID des Ziel-Servers |
+| `environment_name` | string | ja | z. B. `production` |
+| `private_key_uuid` | string | ja | UUID des Deploy-Keys |
+| `git_repository` | string | ja | SSH-URL des Repositories |
+| `git_branch` | string | ja | Branch (z. B. `main`) |
+| `build_pack` | string | ja | `dockerfile` \| `nixpacks` \| `static` |
+| `ports_exposes` | string | ja | Port(s) der Anwendung (z. B. `3000`) |
+| `name` | string | nein | Anzeigename |
+| `fqdn` | string | nein | Domain(s), kommagetrennt |
+
+<Tabs>
+  <TabItem label="Request">
+
+```bash
+curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-key \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_uuid": "<projekt-uuid>",
+    "server_uuid": "<server-uuid>",
+    "environment_name": "production",
+    "private_key_uuid": "<deploy-key-uuid>",
+    "git_repository": "git@git.coolai.btc-ag.cloud:meinteam/meine-app.git",
+    "git_branch": "main",
+    "build_pack": "dockerfile",
+    "ports_exposes": "3000",
+    "name": "meine-app",
+    "fqdn": "https://meine-app.btc-ag.cloud"
+  }'
+```
+
+  </TabItem>
+  <TabItem label="Response">
+
+```json
+{
+  "uuid": "newly-created-uuid",
+  "message": "Application created."
+}
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Anwendung aktualisieren
+
+```http
+PATCH /applications/{uuid}
+```
+
+Aktualisiert einzelne Felder einer Anwendung. Nur übergebene Felder werden geändert.
+
+**Häufige Update-Felder:**
+
+| Feld | Beschreibung |
+|---|---|
+| `name` | Anzeigename |
+| `fqdn` | Domain(s) |
+| `git_branch` | Branch wechseln |
+| `environment_variables` | Variablen als Newline-getrennter String |
+| `dockerfile_location` | Pfad zum Dockerfile |
+
+<Tabs>
+  <TabItem label="Domain ändern">
+
+```bash
+curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"fqdn": "https://neue-domain.btc-ag.cloud"}'
+```
+
+  </TabItem>
+  <TabItem label="Env-Vars setzen">
+
+```bash
+curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "environment_variables": "DATABASE_URL=postgresql://...\nLOG_LEVEL=info"
+  }'
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Anwendung löschen
+
+```http
+DELETE /applications/{uuid}
+```
+
+```bash
+curl -s -X DELETE https://coolai.btc-ag.cloud/api/v1/applications/<uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+:::caution
+Das Löschen einer Anwendung stoppt den Container und entfernt alle zugehörigen Konfigurationen. Deployment-Historien bleiben erhalten.
+:::

src/content/docs/api/authentifizierung.md

@@ -0,0 +1,121 @@
+---
+title: Authentifizierung
+description: API-Token erstellen und in Anfragen verwenden — Bearer-Authentifizierung für den AI Application Layer.
+sidebar:
+  order: 2
+---
+
+Die API des AI Application Layer verwendet **Bearer-Token-Authentifizierung**. Jeder API-Aufruf muss einen gültigen Token im `Authorization`-Header enthalten.
+
+---
+
+## API-Token erstellen
+
+1. In der Plattform-Oberfläche anmelden
+2. Oben rechts: **Profil → API-Tokens**
+3. **"Neuen Token erstellen"**
+4. Einen sprechenden Namen vergeben (z. B. `ci-pipeline-meine-app`)
+5. Token **sofort kopieren** — er wird danach nicht mehr im Klartext angezeigt
+
+:::caution
+Behandelt API-Tokens wie Passwörter. Niemals in Git einchecken, nicht in Logs ausgeben, nicht per E-Mail teilen.
+:::
+
+---
+
+## Token verwenden
+
+Jeder API-Request benötigt den Header:
+
+```
+Authorization: Bearer <euer-token>
+```
+
+### Beispiel mit curl
+
+```bash
+# Token als Umgebungsvariable (sicher)
+export COOLIFY_TOKEN="<euer-token>"
+
+curl -s https://coolai.btc-ag.cloud/api/v1/applications \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+### Beispiel mit Python
+
+```python
+import httpx
+import os
+
+token = os.environ["COOLIFY_TOKEN"]
+base_url = "https://coolai.btc-ag.cloud/api/v1"
+
+headers = {"Authorization": f"Bearer {token}"}
+
+response = httpx.get(f"{base_url}/applications", headers=headers)
+response.raise_for_status()
+print(response.json())
+```
+
+### Beispiel mit JavaScript/TypeScript
+
+```typescript
+const token = process.env.COOLIFY_TOKEN;
+const baseUrl = "https://coolai.btc-ag.cloud/api/v1";
+
+const response = await fetch(`${baseUrl}/applications`, {
+  headers: {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  },
+});
+
+const apps = await response.json();
+```
+
+---
+
+## Token in CI/CD-Systemen
+
+Hinterlegt den Token als **Secret** in eurem CI/CD-System:
+
+**Gitea Actions:**
+```yaml
+# In .gitea/workflows/deploy.yml
+steps:
+  - name: Deploy
+    env:
+      COOLIFY_TOKEN: ${{ secrets.COOLIFY_TOKEN }}
+    run: |
+      curl -s -X GET \
+        "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=${{ secrets.APP_UUID }}" \
+        -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+Repository → **Settings → Secrets → "Neues Secret"** → `COOLIFY_TOKEN`
+
+---
+
+## Token rotieren
+
+Wenn ein Token kompromittiert wurde oder ein Teammitglied das Unternehmen verlässt:
+
+1. Alten Token in der Plattform-Oberfläche **löschen** (Profil → API-Tokens)
+2. Neuen Token erstellen
+3. Neuen Token in allen CI/CD-Systemen und Scripts aktualisieren
+
+---
+
+## Fehler bei der Authentifizierung
+
+| HTTP-Status | Bedeutung |
+|---|---|
+| `401 Unauthorized` | Token fehlt oder ist ungültig |
+| `403 Forbidden` | Token ist gültig, aber ohne Berechtigung für diese Ressource |
+
+```json
+// Beispiel-Response bei 401
+{
+  "message": "Unauthenticated."
+}
+```

src/content/docs/api/deployments.md

@@ -0,0 +1,172 @@
+---
+title: Deployments API
+description: Deployments auslösen, Status abfragen, Historie einsehen und laufende Deployments abbrechen.
+sidebar:
+  order: 4
+---
+
+## Deployment auslösen
+
+```http
+GET /deploy?uuid={app-uuid}&force={true|false}
+POST /deploy
+```
+
+Startet ein neues Deployment für die angegebene Anwendung.
+
+| Parameter | Typ | Beschreibung |
+|---|---|---|
+| `uuid` | string | UUID der Anwendung |
+| `force` | boolean | `true`: Cache ignorieren, vollständigen Rebuild erzwingen |
+
+```bash
+# Standard-Deployment (mit Cache)
+curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=false" \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+
+# Force-Rebuild (kein Cache)
+curl -s "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=true" \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+**Response:**
+
+```json
+{
+  "message": "Deployment queued.",
+  "deployment_uuid": "deploy-abc123"
+}
+```
+
+---
+
+## Deployment-Historie einer Anwendung
+
+```http
+GET /deployments/applications/{app-uuid}
+```
+
+Gibt alle Deployments einer Anwendung zurück, neueste zuerst.
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.[] | {uuid, status, created_at}'
+```
+
+**Response:**
+
+```json
+[
+  {
+    "uuid": "deploy-abc123",
+    "status": "finished",
+    "created_at": "2026-03-05T10:00:00Z",
+    "logs": "..."
+  },
+  {
+    "uuid": "deploy-xyz789",
+    "status": "failed",
+    "created_at": "2026-03-04T15:30:00Z",
+    "logs": "..."
+  }
+]
+```
+
+---
+
+## Einzelnes Deployment abrufen
+
+```http
+GET /deployments/{deployment-uuid}
+```
+
+Gibt Details und den vollständigen Log eines einzelnen Deployments zurück.
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/deployments/<deployment-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+**Response:**
+
+```json
+{
+  "uuid": "deploy-abc123",
+  "status": "finished",
+  "created_at": "2026-03-05T10:00:00Z",
+  "finished_at": "2026-03-05T10:02:34Z",
+  "logs": "[INFO] Cloning repository...\n[INFO] Building image...\n[INFO] Done."
+}
+```
+
+---
+
+## Laufende Deployments abbrechen
+
+```http
+POST /deployments/{deployment-uuid}/cancel
+```
+
+Bricht ein aktuell laufendes Deployment ab. Hat keinen Effekt auf bereits abgeschlossene Deployments.
+
+```bash
+curl -s -X POST \
+  https://coolai.btc-ag.cloud/api/v1/deployments/<deployment-uuid>/cancel \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+:::note
+Nach einem Abbruch läuft die zuletzt erfolgreich deployete Version weiter. Es gibt keinen Service-Ausfall.
+:::
+
+---
+
+## Deployment-Status-Übersicht
+
+| Status | Beschreibung |
+|---|---|
+| `queued` | In der Warteschlange |
+| `in_progress` | Build oder Deploy läuft gerade |
+| `finished` | Erfolgreich abgeschlossen |
+| `failed` | Fehlgeschlagen |
+| `cancelled` | Manuell abgebrochen |
+
+---
+
+## Polling-Pattern
+
+Für automatisierte Workflows, die auf den Abschluss eines Deployments warten müssen:
+
+```bash
+APP_UUID="<app-uuid>"
+COOLIFY_TOKEN="<token>"
+
+# Deployment starten und UUID merken
+DEPLOY_UUID=$(curl -s \
+  "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=$APP_UUID&force=false" \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq -r '.deployment_uuid')
+
+echo "Deployment gestartet: $DEPLOY_UUID"
+
+# Status pollen
+while true; do
+  STATUS=$(curl -s \
+    "https://coolai.btc-ag.cloud/api/v1/deployments/$DEPLOY_UUID" \
+    -H "Authorization: Bearer $COOLIFY_TOKEN" \
+    | jq -r '.status')
+
+  echo "Status: $STATUS"
+
+  if [[ "$STATUS" == "finished" ]]; then
+    echo "Deployment erfolgreich."
+    break
+  elif [[ "$STATUS" == "failed" || "$STATUS" == "cancelled" ]]; then
+    echo "Deployment fehlgeschlagen: $STATUS"
+    exit 1
+  fi
+
+  sleep 10
+done
+```

src/content/docs/api/uebersicht.md

@@ -0,0 +1,102 @@
+---
+title: API-Überblick
+description: Grundlegendes zur REST-API des AI Application Layer — Base URL, Formate, Fehler und Konventionen.
+sidebar:
+  order: 1
+---
+
+Der AI Application Layer stellt eine vollständige REST-API bereit. Damit lassen sich alle Funktionen der Plattform automatisieren: Anwendungen anlegen und deployen, Konfiguration aktualisieren, Logs abrufen und Deployments steuern.
+
+---
+
+## Base URL
+
+```
+https://coolai.btc-ag.cloud/api/v1
+```
+
+Alle Endpunkte sind relativ zu dieser Base URL. Alle Anfragen erfolgen über HTTPS.
+
+---
+
+## Format
+
+- **Request-Body**: `application/json`
+- **Response**: `application/json`
+- **Zeichensatz**: UTF-8
+
+---
+
+## Authentifizierung
+
+Alle API-Aufrufe erfordern einen Bearer-Token im `Authorization`-Header:
+
+```
+Authorization: Bearer <euer-api-token>
+```
+
+Details zur Token-Erstellung: [Authentifizierung](/api/authentifizierung/)
+
+---
+
+## HTTP-Methoden
+
+| Methode | Verwendung |
+|---|---|
+| `GET` | Ressource lesen |
+| `POST` | Ressource anlegen oder Aktion auslösen |
+| `PATCH` | Ressource teilweise aktualisieren |
+| `DELETE` | Ressource löschen |
+
+---
+
+## Status-Codes
+
+| Code | Bedeutung |
+|---|---|
+| `200 OK` | Erfolgreich |
+| `201 Created` | Ressource erfolgreich angelegt |
+| `400 Bad Request` | Ungültige Anfrage (fehlende/falsche Parameter) |
+| `401 Unauthorized` | Kein oder ungültiger Token |
+| `403 Forbidden` | Keine Berechtigung für diese Ressource |
+| `404 Not Found` | Ressource nicht gefunden |
+| `422 Unprocessable Entity` | Validierungsfehler |
+| `500 Internal Server Error` | Interner Fehler |
+
+---
+
+## Fehler-Response
+
+Fehler werden einheitlich im folgenden Format zurückgegeben:
+
+```json
+{
+  "message": "The application was not found.",
+  "errors": {
+    "uuid": ["The UUID does not exist."]
+  }
+}
+```
+
+---
+
+## Paginierung
+
+Endpunkte, die Listen zurückgeben, unterstützen derzeit keine Paginierung — alle Einträge werden auf einmal zurückgegeben.
+
+---
+
+## Beispiel-Aufruf
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/applications \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.[].name'
+```
+
+---
+
+## Vollständige API-Referenz (Swagger)
+
+Die interaktive Swagger-Dokumentation mit allen Endpunkten und Schemas ist über die Plattform-Oberfläche erreichbar.
+Loggt euch ein und navigiert zu: **Einstellungen → API → API-Referenz öffnen**

src/content/docs/einstieg/einfuehrung.md

@@ -0,0 +1,112 @@
+---
+title: Einführung
+description: Was ist BTC MAIN — Managed AI Now und der AI Application Layer? Architektur, Zielgruppen und Einsatzbereiche.
+sidebar:
+  order: 1
+---
+
+## Was ist BTC MAIN — Managed AI Now?
+
+**BTC MAIN — Managed AI Now** ist das Managed-Plattform-Angebot der BTC AG für die Bereitstellung und den Betrieb moderner Anwendungen.
+Ziel ist es, Entwicklungsteams eine leistungsfähige Deployment-Plattform an die Hand zu geben,
+die sich wie Vercel oder Firebase anfühlt — aber vollständig unter Kontrolle der BTC AG betrieben wird:
+souverän, sicher und ohne Abhängigkeit von Public-Cloud-Anbietern.
+
+---
+
+## Der AI Application Layer
+
+Der **AI Application Layer** ist die technische Kernkomponente von BTC MAIN.
+Er stellt die Infrastruktur und die Werkzeuge bereit, mit denen Anwendungen
+
+- aus einem Git-Repository automatisch gebaut und deployt werden,
+- über definierte Domains mit automatischem TLS-Zertifikat erreichbar sind,
+- über CI/CD-Pipelines kontinuierlich aktualisiert werden können,
+- und im laufenden Betrieb überwacht und verwaltet werden können.
+
+Die Plattform basiert auf etablierten Open-Source-Technologien und läuft auf STACKIT IaaS in der Region Frankfurt (EU01).
+
+---
+
+## Für wen ist diese Plattform?
+
+| Zielgruppe | Typische Aufgaben |
+|---|---|
+| **Entwickler** | Apps deployen, Umgebungsvariablen setzen, Logs einsehen, Pipelines konfigurieren |
+| **DevOps / Platform Engineers** | Neue Projekte anlegen, Domains verwalten, Ressourcen skalieren, API-Automatisierung |
+| **Betrieb / IT** | Betriebsstatus überwachen, Deployments nachvollziehen, Zugang verwalten |
+
+---
+
+## Was kann ich auf der Plattform betreiben?
+
+Der AI Application Layer eignet sich für:
+
+- **Web-Anwendungen** (Frontend, Fullstack, APIs) — jede Sprache und jedes Framework, sofern ein Dockerfile vorhanden ist oder ein unterstütztes Runtime-Profil greift
+- **Hintergrunddienste** (Worker, Daemons, Scheduler)
+- **Statische Websites** (Dokumentationen, Landing Pages)
+- **Managed Services** (Datenbanken, Message Broker — perspektivisch)
+
+:::note
+Der Fokus liegt aktuell auf containerisierten Anwendungen. Bringt eure App als Docker-Image mit, oder stellt ein `Dockerfile` im Repository bereit.
+:::
+
+---
+
+## Architektur-Überblick
+
+```
+Entwickler / CI-Pipeline
+         |
+         | Git Push → Webhook
+         v
++------------------------+
+|  Git (Gitea)           |  Versionsverwaltung & Webhooks
+|  git.coolai.btc-ag.cloud |
++----------+-------------+
+           |
+           | Deployment-Trigger
+           v
++------------------------+
+|  AI Application Layer  |  Deployment-Orchestrierung,
+|  (Plattform-Steuerung) |  Build-Pipeline, Routing-Config
++----------+-------------+
+           |
+           | Container deployen
+           v
++------------------------+
+|  App-Runtime           |  Docker-Container
+|  (Application Server)  |  Eurer Anwendung
++----------+-------------+
+           |
+           | HTTPS-Traffic
+           v
++------------------------+
+|  Reverse Proxy (TLS)   |  Automatisches SSL via
+|  + Let's Encrypt       |  Let's Encrypt, Routing
++------------------------+
+           |
+           | Öffentlicher Zugriff
+           v
+     https://eure-app.btc-ag.cloud
+```
+
+---
+
+## Zugang erhalten
+
+Der Zugang zur Plattform wird über die IT der BTC AG bereitgestellt.
+Meldet euren Bedarf über den internen IT-Servicedesk und gebt dabei an:
+
+- Projektname und kurze Beschreibung
+- Gewünschte Domain(s)
+- Beteiligtes Team / Kostenstelleninfo
+
+Nach der Freigabe erhaltet ihr:
+- Zugang zur Plattform-Oberfläche
+- Einen persönlichen API-Token
+- Ein Gitea-Repository (oder Anbindung an ein bestehendes)
+
+:::tip
+Benötigt ihr sofortigen Zugang für ein Pilotprojekt? Meldet euch direkt beim Platform-Team der BTC AG.
+:::

src/content/docs/einstieg/konzepte.md

@@ -0,0 +1,134 @@
+---
+title: Kernkonzepte
+description: Die wichtigsten Begriffe und Konzepte des AI Application Layer — Projekte, Anwendungen, Deployments, Domains und mehr.
+sidebar:
+  order: 3
+---
+
+Dieser Abschnitt erklärt die zentralen Konzepte der Plattform. Ein solides Verständnis dieser Grundbegriffe hilft dabei, die Plattform effektiv zu nutzen und Missverständnisse zu vermeiden.
+
+---
+
+## Projekte
+
+Ein **Projekt** ist die übergeordnete Organisationseinheit. Projekte fassen zusammengehörige Ressourcen (Anwendungen, Datenbanken, Services) zu einer logischen Einheit zusammen.
+
+```
+Projekt: "E-Commerce-Plattform"
+├── Anwendung: "frontend"
+├── Anwendung: "api-server"
+└── Datenbank: "postgres-prod"
+```
+
+Typische Projektzuschnitte:
+- Ein Projekt pro Produkt oder Team
+- Ein Projekt pro Domäne (z. B. `crm`, `reporting`, `ai-services`)
+
+---
+
+## Anwendungen
+
+Eine **Anwendung** repräsentiert einen containerisierten Prozess — also euren Service, eure Web-App oder euren Worker.
+
+Jede Anwendung hat:
+- ein **Repository** (Git-URL + Branch)
+- ein **Build-Profil** (Dockerfile, Nixpacks, Static, ...)
+- eine oder mehrere **Domains**
+- **Umgebungsvariablen** (Build-Zeit und/oder Laufzeit)
+- eine **Deployment-Historie**
+
+---
+
+## Deployments
+
+Ein **Deployment** ist ein einzelner Durchlauf des Build-und-Deploy-Prozesses. Jedes Deployment
+
+1. klont das Repository am konfigurierten Branch/Commit,
+2. baut das Docker-Image,
+3. startet einen neuen Container,
+4. schaltet den Reverse Proxy auf den neuen Container um.
+
+Jedes Deployment bekommt eine eigene ID und einen Status:
+
+| Status | Bedeutung |
+|---|---|
+| `queued` | Wartet auf Ausführung |
+| `in_progress` | Build/Deploy läuft gerade |
+| `finished` | Erfolgreich abgeschlossen |
+| `failed` | Fehlgeschlagen (Logs prüfen) |
+| `cancelled` | Manuell abgebrochen |
+
+Die komplette Deployment-Historie bleibt erhalten und ist über die API abrufbar.
+
+---
+
+## Build-Profile
+
+Das **Build-Profil** legt fest, wie die Plattform aus dem Repository ein lauffähiges Image erstellt.
+
+| Profil | Beschreibung |
+|---|---|
+| **Dockerfile** | Euer eigenes `Dockerfile` im Repository-Root (empfohlen) |
+| **Nixpacks** | Automatische Erkennung der Sprache/des Frameworks, kein Dockerfile nötig |
+| **Static** | Statische Dateien (HTML/CSS/JS), direkt via nginx ausgeliefert |
+
+:::tip
+Für maximale Kontrolle und Reproduzierbarkeit empfehlen wir immer ein eigenes `Dockerfile`.
+:::
+
+---
+
+## Domains & TLS
+
+Jede Anwendung kann unter einer oder mehreren **Domains** erreichbar sein.
+
+- **Automatisches TLS**: Let's Encrypt-Zertifikate werden automatisch ausgestellt und erneuert.
+- **Custom Domains**: Beliebige Subdomains innerhalb von `btc-ag.cloud` oder eigene Domains (nach DNS-Konfiguration).
+- **Routing**: Der Reverse Proxy leitet eingehende Anfragen anhand des Hostnamens an den richtigen Container weiter.
+
+Die Domain-Konfiguration greift unmittelbar nach dem nächsten Deployment.
+
+---
+
+## Umgebungsvariablen & Secrets
+
+**Umgebungsvariablen** ermöglichen die Konfiguration einer Anwendung ohne Code-Änderungen.
+
+Es gibt zwei Typen:
+
+| Typ | Verfügbarkeit | Typischer Einsatz |
+|---|---|---|
+| **Build-Zeit** | Nur während `docker build` | `NEXT_PUBLIC_API_URL`, Build-Flags |
+| **Laufzeit** | Im laufenden Container | `DATABASE_URL`, API-Keys, Feature-Flags |
+
+**Secrets** sind besonders geschützte Werte: Sie werden verschlüsselt gespeichert und nicht im Klartext in der Oberfläche oder in Logs angezeigt.
+
+---
+
+## Services & Datenbanken
+
+Neben Anwendungen können auf der Plattform auch **verwaltete Services** betrieben werden — z. B. PostgreSQL, Redis oder andere Middleware.
+
+:::note
+Der Ausbau des verwalteten Service-Angebots ist in Planung. Welche Services aktuell verfügbar sind, erfragt ihr beim Platform-Team.
+:::
+
+---
+
+## Webhook-basiertes Deployment
+
+Der **Webhook** ist der Auslöser für automatische Deployments. Wird in Gitea ein Push auf den konfigurierten Branch ausgeführt, sendet Gitea einen HTTP-Request an die Plattform — die daraufhin ein neues Deployment startet.
+
+Mehr dazu: [CI/CD Pipelines einrichten](/guides/cicd-pipelines/)
+
+---
+
+## Reverse Proxy & Routing
+
+Alle eingehenden HTTPS-Anfragen laufen durch einen zentralen **Reverse Proxy** (Traefik). Er ist verantwortlich für:
+
+- TLS-Terminierung
+- Routing nach Hostname zur richtigen Anwendung
+- Automatische Zertifikatserneuerung
+
+Ihr müsst den Reverse Proxy nicht konfigurieren — das übernimmt die Plattform anhand eurer Domain-Einstellungen automatisch.

src/content/docs/einstieg/schnellstart.mdx

@@ -0,0 +1,113 @@
+---
+title: Schnellstart
+description: In wenigen Schritten zur ersten deployten Anwendung auf dem AI Application Layer.
+sidebar:
+  order: 2
+---
+
+import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+
+Dieser Guide begleitet euch von der ersten Anmeldung bis zur laufenden Anwendung.
+Ihr benötigt dafür etwa **15–20 Minuten**.
+
+## Voraussetzungen
+
+- Zugang zur Plattform (API-Token und Zugangsdaten vom IT-Servicedesk)
+- Git installiert (lokal)
+- Docker installiert (lokal, zum Testen des Builds)
+- Eine Anwendung mit `Dockerfile` oder einem unterstützten Runtime-Profil
+
+---
+
+## Schritt-für-Schritt
+
+<Steps>
+
+1. **Anmelden**
+
+   Öffnet die Plattform-Oberfläche und meldet euch mit euren Zugangsdaten an.
+
+   Nach dem Login seht ihr das Dashboard mit einer Übersicht aller euch zugänglichen Projekte.
+
+2. **Projekt wählen oder anlegen**
+
+   Wählt ein bestehendes Projekt aus oder legt ein neues an:
+
+   - Klick auf **"Neues Projekt"**
+   - Name und optionale Beschreibung eingeben
+   - Bestätigen
+
+   Projekte sind logische Gruppen für zusammengehörige Anwendungen (z. B. `backend`, `frontend`, `worker`).
+
+3. **Neue Anwendung anlegen**
+
+   Innerhalb des Projekts: **"Neue Ressource" → "Anwendung" → "Öffentliches/Privates Repository"**
+
+   <Aside type="tip">
+     Für Repositories auf `git.coolai.btc-ag.cloud` wählt **"Privates Repository mit Deploy-Key"**.
+   </Aside>
+
+   Füllt die Felder aus:
+
+   | Feld | Beispiel |
+   |---|---|
+   | Repository-URL | `https://git.coolai.btc-ag.cloud/meinteam/meine-app` |
+   | Branch | `main` |
+   | Build-Pack | `Dockerfile` |
+   | Port | `3000` (oder euer App-Port) |
+
+4. **Domain konfigurieren**
+
+   Unter **"Domains"** tragt ihr die gewünschte Adresse ein, z. B.:
+
+   ```
+   meine-app.btc-ag.cloud
+   ```
+
+   Das TLS-Zertifikat wird automatisch ausgestellt — kein manueller Schritt nötig.
+
+5. **Umgebungsvariablen setzen**
+
+   Unter **"Umgebungsvariablen"** könnt ihr alle nötigen Konfigurationswerte hinterlegen.
+
+   ```
+   DATABASE_URL=postgresql://...
+   APP_ENV=production
+   LOG_LEVEL=info
+   ```
+
+   <Aside type="caution">
+     Sensible Werte (Passwörter, Tokens) als **Secret** markieren — sie werden dann nicht im Klartext angezeigt.
+   </Aside>
+
+6. **Erstes Deployment auslösen**
+
+   Klick auf **"Deployen"** — die Plattform:
+
+   - Klont das Repository
+   - Baut das Docker-Image
+   - Startet den Container
+   - Aktiviert das Routing über den Reverse Proxy
+
+   Ihr könnt den Build-Log in Echtzeit verfolgen.
+
+7. **Anwendung prüfen**
+
+   Nach erfolgreichem Deployment ist die App unter der konfigurierten Domain erreichbar.
+
+   Im Dashboard seht ihr:
+   - Deployment-Status (grün = läuft)
+   - Letzten Deployment-Zeitstempel
+   - Link zur laufenden Instanz
+
+</Steps>
+
+---
+
+## Nächste Schritte
+
+Jetzt, wo eure erste App läuft, richtet ihr am besten den automatischen Deployment-Trigger ein:
+
+- [CI/CD Pipelines einrichten](/guides/cicd-pipelines/) — bei jedem Push automatisch deployen
+- [Umgebungsvariablen verwalten](/guides/umgebungsvariablen/) — Build- vs. Laufzeit-Variablen
+- [Custom Domain hinzufügen](/guides/custom-domains/) — eigene Subdomain einbinden

src/content/docs/guides/app-deployen.mdx

@@ -0,0 +1,173 @@
+---
+title: App deployen
+description: Schritt-für-Schritt-Anleitung für das Deployment einer Anwendung auf dem AI Application Layer — via UI und API.
+sidebar:
+  order: 1
+---
+
+import { Steps, Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+
+Dieser Guide zeigt, wie ihr eine neue Anwendung auf der Plattform einrichtet und deployt — sowohl über die Benutzeroberfläche als auch über die API.
+
+---
+
+## Voraussetzungen
+
+- Aktiver Plattform-Zugang (API-Token vorhanden)
+- Anwendungs-Repository in Gitea (`git.coolai.btc-ag.cloud`)
+- `Dockerfile` im Repository-Root (empfohlen) oder Nixpacks-kompatible Projektstruktur
+- Gewünschte Domain (Subdomain unter `btc-ag.cloud` oder eigene Domain)
+
+---
+
+## Dockerfile-Anforderungen
+
+Ein gutes `Dockerfile` für die Plattform folgt diesen Grundsätzen:
+
+```dockerfile
+# Multi-Stage Build — klein und sicher
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+
+# Expliziter Port
+EXPOSE 3000
+
+# Kein Root
+USER node
+
+CMD ["node", "dist/server.js"]
+```
+
+**Wichtige Punkte:**
+- Den **Port explizit** via `EXPOSE` deklarieren — die Plattform liest diesen Wert aus.
+- **Multi-Stage Builds** verwenden, um das finale Image klein zu halten.
+- Den Container **nicht als Root** ausführen.
+- Keine Secrets ins Image einbacken — alles über Umgebungsvariablen.
+
+---
+
+## Deployment via Oberfläche
+
+<Steps>
+
+1. **Repository verbinden**
+
+   Im Dashboard: **Projekt öffnen → "Neue Ressource" → "Anwendung"**
+
+   Repository-Typ wählen:
+   - **Öffentliches Repository**: GitHub, GitLab, beliebige öffentliche URL
+   - **Privates Repository (Deploy-Key)**: Gitea auf `git.coolai.btc-ag.cloud` (empfohlen)
+
+2. **Repository-Details eintragen**
+
+   | Feld | Beschreibung |
+   |---|---|
+   | Repository-URL | `https://git.coolai.btc-ag.cloud/meinteam/meine-app` |
+   | Branch | z. B. `main` oder `production` |
+   | Build-Pack | `Dockerfile` |
+   | Dockerfile-Pfad | Standard: `./Dockerfile` |
+   | Port | Euer App-Port (z. B. `3000`, `8080`) |
+
+3. **Domain konfigurieren**
+
+   Unter dem Tab **"Domains"**:
+   ```
+   meine-app.btc-ag.cloud
+   ```
+   TLS wird automatisch eingerichtet.
+
+4. **Umgebungsvariablen setzen**
+
+   Unter **"Umgebungsvariablen"** alle nötigen Werte hinterlegen.
+   Secrets (Passwörter, Tokens) als **geheimen Wert** markieren.
+
+5. **Deployment starten**
+
+   Klick auf **"Deployen"** — Build-Log erscheint in Echtzeit.
+
+</Steps>
+
+---
+
+## Deployment via API
+
+<Tabs>
+  <TabItem label="App anlegen">
+
+```bash
+curl -s -X POST https://coolai.btc-ag.cloud/api/v1/applications/private-deploy-key \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "project_uuid": "<projekt-uuid>",
+    "server_uuid": "<server-uuid>",
+    "environment_name": "production",
+    "private_key_uuid": "<deploy-key-uuid>",
+    "git_repository": "git@git.coolai.btc-ag.cloud:meinteam/meine-app.git",
+    "git_branch": "main",
+    "build_pack": "dockerfile",
+    "ports_exposes": "3000",
+    "name": "meine-app",
+    "domains": "https://meine-app.btc-ag.cloud"
+  }'
+```
+
+  </TabItem>
+  <TabItem label="Deployment auslösen">
+
+```bash
+# Deployment triggern (UUID aus dem App-Anlegen-Response)
+curl -s -X GET \
+  "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=false" \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+  </TabItem>
+  <TabItem label="Status prüfen">
+
+```bash
+# Deployment-Status abfragen
+curl -s https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.status'
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Deployment-Verlauf
+
+Jedes Deployment wird mit ID, Zeitstempel, Status und vollständigem Log gespeichert.
+
+```bash
+# Alle Deployments einer Anwendung
+curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.[] | {id: .id, status: .status, created_at: .created_at}'
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Mögliche Ursache | Lösung |
+|---|---|---|
+| Build schlägt fehl | Fehler im Dockerfile | Build-Log prüfen |
+| Container startet nicht | Falscher Port / fehlende Env-Var | Logs prüfen, Umgebungsvariablen kontrollieren |
+| Domain nicht erreichbar | DNS noch nicht propagiert / TLS ausstehend | 5–10 Minuten warten, dann erneut prüfen |
+| `Permission denied` beim Build | Root-Rechte im Container fehlen | `USER`-Direktive im Dockerfile prüfen |
+
+<Aside type="tip">
+  Der Build-Log ist immer der erste Anlaufpunkt bei Problemen. Er zeigt exakt, bei welchem Schritt der Build fehlgeschlagen ist.
+</Aside>

src/content/docs/guides/cicd-pipelines.md

@@ -0,0 +1,157 @@
+---
+title: CI/CD Pipelines
+description: Automatische Deployments mit Gitea-Webhooks und Gitea Actions — von Git Push bis Livegang.
+sidebar:
+  order: 2
+---
+
+Der AI Application Layer unterstützt zwei Ansätze für automatische Deployments:
+
+| Ansatz | Geeignet für | Komplexität |
+|---|---|---|
+| **Gitea Webhook → direkt deployen** | Einfache Projekte, schnelles Setup | Niedrig |
+| **Gitea Actions / Pipeline** | Komplexere Workflows (Tests, Builds, Multi-Stage) | Mittel |
+
+---
+
+## Option 1: Direkt-Deployment via Webhook
+
+Der einfachste Weg: Gitea sendet bei jedem Push auf einen Branch automatisch einen Webhook an die Plattform, die daraufhin ein Deployment startet.
+
+### Webhook-URL ermitteln
+
+Jede Anwendung auf der Plattform hat eine dedizierte Webhook-URL. Ihr findet sie in der Anwendungsübersicht unter **"Webhooks"** oder über die API:
+
+```bash
+curl -s https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '{webhook: .manual_webhook_secret_gitea}'
+```
+
+### Webhook in Gitea einrichten
+
+1. Repository in Gitea öffnen: `https://git.coolai.btc-ag.cloud`
+2. **Settings → Webhooks → Webhook hinzufügen → Gitea**
+
+| Feld | Wert |
+|---|---|
+| Ziel-URL | `https://coolai.btc-ag.cloud/api/v1/deploy?uuid=<app-uuid>&force=false` |
+| HTTP-Methode | `POST` |
+| Content Type | `application/json` |
+| Authorization-Header | `Bearer <euer-api-token>` |
+| Trigger | `Push Events` |
+| Branch-Filter | z. B. `main` |
+
+3. **"Webhook testen"** — bei Erfolg erscheint im Anwendungs-Dashboard ein neues Deployment.
+
+### Webhook via Gitea API einrichten
+
+```bash
+GITEA_TOKEN="<euer-gitea-token>"
+GITEA_URL="https://git.coolai.btc-ag.cloud"
+REPO_OWNER="meinteam"
+REPO_NAME="meine-app"
+APP_UUID="<app-uuid>"
+COOLIFY_TOKEN="<euer-coolify-token>"
+
+curl -s -X POST "$GITEA_URL/api/v1/repos/$REPO_OWNER/$REPO_NAME/hooks" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"type\": \"gitea\",
+    \"config\": {
+      \"url\": \"https://coolai.btc-ag.cloud/api/v1/deploy?uuid=$APP_UUID&force=false\",
+      \"content_type\": \"json\",
+      \"authorization_header\": \"Bearer $COOLIFY_TOKEN\"
+    },
+    \"events\": [\"push\"],
+    \"active\": true
+  }"
+```
+
+---
+
+## Option 2: Gitea Actions Pipeline
+
+Für Projekte, die vor dem Deployment Tests, Linting oder komplexere Build-Schritte benötigen, empfiehlt sich eine Gitea Actions Pipeline.
+
+### Beispiel: Node.js App mit Tests
+
+Datei: `.gitea/workflows/deploy.yml`
+
+```yaml
+name: Build, Test & Deploy
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Node.js einrichten
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Abhängigkeiten installieren
+        run: npm ci
+
+      - name: Tests ausführen
+        run: npm test
+
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deployment auslösen
+        run: |
+          curl -s -X POST \
+            "https://coolai.btc-ag.cloud/api/v1/deploy?uuid=${{ secrets.APP_UUID }}&force=false" \
+            -H "Authorization: Bearer ${{ secrets.COOLIFY_TOKEN }}"
+```
+
+### Secrets in Gitea hinterlegen
+
+Repository → **Settings → Secrets → "Neues Secret"**:
+
+| Name | Wert |
+|---|---|
+| `COOLIFY_TOKEN` | Euer API-Token |
+| `APP_UUID` | UUID der Anwendung auf der Plattform |
+
+:::caution
+Tragt Tokens und UUIDs **niemals direkt in die YAML-Datei** ein. Verwendet immer Gitea Secrets.
+:::
+
+---
+
+## Branch-Strategie
+
+Eine bewährte Strategie für den Umgang mit mehreren Umgebungen:
+
+| Branch | Umgebung | Deployment |
+|---|---|---|
+| `main` | Produktion | Automatisch bei Push |
+| `staging` | Staging | Automatisch bei Push |
+| Feature-Branches | – | Kein automatisches Deployment |
+
+Richtet dafür je eine Anwendung (mit eigener Domain und eigenem Webhook) pro Umgebung ein.
+
+---
+
+## Deployment-Status prüfen
+
+Nach einem Trigger könnt ihr den aktuellen Status abfragen:
+
+```bash
+# Letztes Deployment einer Anwendung
+curl -s "https://coolai.btc-ag.cloud/api/v1/deployments/applications/<app-uuid>" \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq 'first | {status: .status, started: .created_at}'
+```

src/content/docs/guides/custom-domains.md

@@ -0,0 +1,87 @@
+---
+title: Custom Domains
+description: Eigene (Sub-)Domains für Anwendungen einrichten — DNS-Konfiguration und automatisches TLS.
+sidebar:
+  order: 4
+---
+
+Jede Anwendung kann unter einer oder mehreren Domains erreichbar sein. TLS-Zertifikate werden automatisch über Let's Encrypt ausgestellt.
+
+---
+
+## Subdomains unter btc-ag.cloud
+
+Für Subdomains unter `*.btc-ag.cloud` ist **kein DNS-Aufwand auf eurer Seite** nötig — das Platform-Team richtet die nötigen DNS-Einträge ein.
+
+Teilt dem Platform-Team mit:
+- Gewünschte Subdomain (z. B. `meine-app.btc-ag.cloud`)
+- Zugehörige Anwendung auf der Plattform
+
+Sobald der DNS-Eintrag gesetzt ist, genügt es, die Domain in der Anwendungskonfiguration einzutragen.
+
+---
+
+## Eigene externe Domain
+
+Wenn ihr eine eigene Domain (z. B. `app.meinunternehmen.de`) verwenden möchtet:
+
+### 1. CNAME-Eintrag anlegen
+
+Legt bei eurem DNS-Provider einen CNAME-Eintrag an, der auf den Plattform-Eintrittspunkt zeigt:
+
+```
+app.meinunternehmen.de.  CNAME  coolai.btc-ag.cloud.
+```
+
+:::note
+Bei Apex-Domains (ohne Subdomain, also z. B. `meinunternehmen.de`) ist ein CNAME nicht möglich.
+Verwendet stattdessen einen A-Record — die IP-Adresse erhaltet ihr vom Platform-Team.
+:::
+
+### 2. Domain in der Plattform eintragen
+
+Anwendung öffnen → **"Domains" → "Domain hinzufügen"**:
+
+```
+https://app.meinunternehmen.de
+```
+
+:::tip
+Immer `https://` voranstellen — die Plattform konfiguriert sonst kein automatisches TLS.
+:::
+
+### 3. TLS-Zertifikat
+
+Das Zertifikat wird automatisch beim nächsten Deployment oder innerhalb weniger Minuten ausgestellt.
+Voraussetzung: Der DNS-Eintrag muss aktiv und propagiert sein.
+
+---
+
+## Via API
+
+```bash
+# Domain zu einer Anwendung hinzufügen
+curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fqdn": "https://app.meinunternehmen.de"
+  }'
+```
+
+Für mehrere Domains kommagetrennt:
+
+```bash
+-d '{"fqdn": "https://app.meinunternehmen.de,https://www.meinunternehmen.de"}'
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Ursache | Lösung |
+|---|---|---|
+| Domain nicht erreichbar | DNS noch nicht propagiert | `dig app.meinunternehmen.de` ausführen, auf Auflösung warten |
+| TLS-Fehler im Browser | Zertifikat noch nicht ausgestellt | 5–10 Minuten warten, dann erneut testen |
+| Zertifikat für falsche Domain | `fqdn`-Feld enthält Tippfehler | Domain in der Anwendung prüfen und korrigieren |
+| HTTP statt HTTPS | `https://`-Prefix fehlt | Domain-Eintrag mit `https://` beginnen |

src/content/docs/guides/logs-monitoring.md

@@ -0,0 +1,134 @@
+---
+title: Logs & Monitoring
+description: Anwendungs- und Deployment-Logs einsehen — via Oberfläche und API.
+sidebar:
+  order: 5
+---
+
+Der AI Application Layer stellt zwei Arten von Logs bereit: **Deployment-Logs** (Build- und Deploy-Prozess) und **Container-Logs** (Laufzeit-Ausgabe der Anwendung).
+
+---
+
+## Deployment-Logs
+
+Deployment-Logs zeigen den kompletten Ablauf eines Build-und-Deploy-Vorgangs:
+
+- Repository klonen
+- Docker-Image bauen
+- Container starten
+- Reverse Proxy konfigurieren
+
+### Via Oberfläche
+
+Anwendung → **"Deployments"** → Deployment auswählen → **"Log anzeigen"**
+
+Der Log wird in Echtzeit aktualisiert, solange das Deployment läuft.
+
+### Via API
+
+```bash
+# Deployment-Historie einer Anwendung
+curl -s https://coolai.btc-ag.cloud/api/v1/deployments/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.[] | {id, status, created_at}'
+
+# Log eines einzelnen Deployments
+curl -s https://coolai.btc-ag.cloud/api/v1/deployments/<deployment-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.logs'
+```
+
+---
+
+## Container-Logs (Laufzeit)
+
+Container-Logs sind die Standardausgaben (stdout/stderr) eurer laufenden Anwendung — also alles, was ihr mit `console.log`, `logger.info` oder äquivalenten Methoden ausgebt.
+
+### Via Oberfläche
+
+Anwendung → **"Logs"** — zeigt die letzten Zeilen in Echtzeit.
+
+### Via API
+
+```bash
+# Aktuelle Logs der laufenden Instanz
+curl -s https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid>/logs \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+---
+
+## Logging-Best-Practices
+
+Damit Logs nützlich sind, sollte eure Anwendung:
+
+**Strukturiert loggen (JSON)**
+
+```javascript
+// Empfohlen: JSON-Format für maschinelle Auswertbarkeit
+console.log(JSON.stringify({
+  level: 'info',
+  message: 'Request verarbeitet',
+  path: '/api/users',
+  duration_ms: 42,
+  timestamp: new Date().toISOString()
+}));
+```
+
+**Log-Level verwenden**
+
+```
+DEBUG   — Detaillierte Diagnoseinformationen (nur Entwicklung)
+INFO    — Normaler Betriebsablauf
+WARN    — Unerwartete, aber handhabbare Situationen
+ERROR   — Fehler, die Aufmerksamkeit erfordern
+```
+
+**Keine Secrets in Logs**
+
+```javascript
+// Schlecht
+console.log(`Verbinde mit DB: ${databaseUrl}`);
+
+// Gut
+console.log('Datenbankverbindung wird aufgebaut');
+```
+
+---
+
+## Statusüberwachung
+
+Der aktuelle Status jeder Anwendung ist im Dashboard sichtbar:
+
+| Status | Bedeutung |
+|---|---|
+| `running` | Anwendung läuft und ist erreichbar |
+| `stopped` | Manuell gestoppt |
+| `restarting` | Neustart läuft |
+| `exited` | Container beendet (Fehler prüfen) |
+
+### Via API
+
+```bash
+# Status aller Ressourcen auf einem Server
+curl -s https://coolai.btc-ag.cloud/api/v1/servers/<server-uuid>/resources \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  | jq '.[] | {name: .name, status: .status}'
+```
+
+---
+
+## Deployment bei Fehler abbrechen
+
+Läuft ein Deployment und ihr merkt, dass etwas schiefläuft:
+
+```bash
+# Laufendes Deployment abbrechen
+curl -s -X POST \
+  https://coolai.btc-ag.cloud/api/v1/deployments/<deployment-uuid>/cancel \
+  -H "Authorization: Bearer $COOLIFY_TOKEN"
+```
+
+:::tip
+Nach einem fehlgeschlagenen Deployment läuft die zuletzt erfolgreiche Version weiter — es gibt keinen Ausfall durch einen gescheiterten Deploy.
+:::

src/content/docs/guides/umgebungsvariablen.md

@@ -0,0 +1,111 @@
+---
+title: Umgebungsvariablen
+description: Konfiguration von Build- und Laufzeit-Variablen sowie sicherer Umgang mit Secrets.
+sidebar:
+  order: 3
+---
+
+Umgebungsvariablen sind der empfohlene Weg, um Anwendungen zu konfigurieren — ohne Werte ins Repository einzuchecken.
+
+---
+
+## Typen
+
+| Typ | Verfügbar | Beispiel |
+|---|---|---|
+| **Build-Zeit** | Während `docker build` | `NEXT_PUBLIC_API_URL`, `VITE_APP_NAME` |
+| **Laufzeit** | Im laufenden Container | `DATABASE_URL`, `JWT_SECRET`, `LOG_LEVEL` |
+
+Die meisten Variablen sind Laufzeit-Variablen. Build-Zeit-Variablen braucht ihr nur, wenn euer Build-Prozess Werte direkt einbettet (z. B. React/Vite mit `VITE_*`-Variablen).
+
+---
+
+## Variablen setzen
+
+### Via Oberfläche
+
+1. Anwendung öffnen → **"Umgebungsvariablen"**
+2. **"Variable hinzufügen"** → Key und Value eintragen
+3. Bei sensiblen Werten: **"Geheimnis"**-Toggle aktivieren
+4. **"Speichern"** — beim nächsten Deployment aktiv
+
+### Via API
+
+```bash
+# Variablen einer Anwendung aktualisieren (PATCH überschreibt den kompletten Satz)
+curl -s -X PATCH https://coolai.btc-ag.cloud/api/v1/applications/<app-uuid> \
+  -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "environment_variables": "DATABASE_URL=postgresql://user:pass@host:5432/db\nLOG_LEVEL=info\nAPP_ENV=production"
+  }'
+```
+
+---
+
+## Secrets — sicherer Umgang
+
+Secrets sind Variablen, deren Werte besonders sensibel sind (Passwörter, API-Keys, Private Keys).
+
+**Empfehlungen:**
+
+- Secrets **niemals** in Git einchecken (`.gitignore` für `.env`-Dateien)
+- Secrets **niemals** in Logs ausgeben
+- Secrets **rotieren**, wenn Zugang eines Teammitglieds erlischt
+- Nur so viele Secrets wie nötig — je Anwendung nur die tatsächlich benötigten Werte
+
+```bash
+# Beispiel: .env-Datei (lokal / für Entwicklung, niemals committen!)
+DATABASE_URL="postgresql://dev:devpass@localhost:5432/myapp"
+JWT_SECRET="lokaler-dev-secret-nicht-produktionsreif"
+```
+
+---
+
+## Best Practices
+
+### 12-Factor-App-Prinzip
+
+Folgt dem [12-Factor-App](https://12factor.net/de/config)-Prinzip: Alle Konfiguration, die sich zwischen Umgebungen unterscheidet, kommt aus Umgebungsvariablen — nicht aus dem Code.
+
+```
+# Gut: Konfiguration aus der Umgebung
+const dbUrl = process.env.DATABASE_URL;
+
+# Schlecht: Konfiguration im Code
+const dbUrl = "postgresql://user:pass@prod-server:5432/db";
+```
+
+### Unterschied Entwicklung / Produktion
+
+| Umgebung | Empfehlung |
+|---|---|
+| Lokale Entwicklung | `.env`-Datei (niemals committen) |
+| Staging / Produktion | Variablen in der Plattform hinterlegen |
+
+### `.env.example` für Dokumentation
+
+Checkt eine `.env.example` ins Repository ein, die alle Variablen mit Erklärungen, aber ohne echte Werte enthält:
+
+```bash
+# .env.example — In Git einchecken!
+# Beschreibung: Verbindungsstring zur Datenbank
+DATABASE_URL=
+
+# API-Schlüssel für externen Service
+EXTERNAL_API_KEY=
+
+# Loglevel: debug | info | warn | error
+LOG_LEVEL=info
+```
+
+---
+
+## Variablen im Build-Log
+
+Variablen, die als **Geheimnis** markiert sind, werden in Build-Logs automatisch maskiert (`***`).
+
+:::note
+Keine Variable wird automatisch versteckt, wenn sie **nicht** als Geheimnis markiert ist.
+Achtet darauf, sensible Werte korrekt zu klassifizieren.
+:::

src/content/docs/index.mdx

@@ -0,0 +1,65 @@
+---
+title: BTC MAIN · Managed AI Now
+description: Der AI Application Layer der BTC AG — Ihre Plattform für Deployment, Betrieb und Skalierung moderner Anwendungen.
+template: splash
+hero:
+  tagline: Anwendungen deployen. Pipelines automatisieren. Infrastruktur vergessen.
+  image:
+    file: ../../assets/logo.svg
+  actions:
+    - text: Schnellstart
+      link: /einstieg/schnellstart/
+      icon: right-arrow
+      variant: primary
+    - text: Einführung lesen
+      link: /einstieg/einfuehrung/
+      icon: open-book
+      variant: secondary
+---
+
+import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+## Was ist der AI Application Layer?
+
+Der **AI Application Layer** ist die zentrale Deployment-Plattform der BTC AG im Rahmen von **BTC MAIN — Managed AI Now**.
+Er ermöglicht es Entwicklungs- und Betriebsteams, Anwendungen schnell, sicher und reproduzierbar bereitzustellen —
+ohne sich um die darunter liegende Infrastruktur kümmern zu müssen.
+
+<CardGrid stagger>
+  <Card title="Apps deployen" icon="rocket">
+    Git-basiertes Deployment in Sekunden. Docker-Container, statische Seiten oder Server-Anwendungen —
+    einfach in das Repository pushen, der Rest passiert automatisch.
+  </Card>
+  <Card title="Pipelines automatisieren" icon="setting">
+    CI/CD-Workflows mit Gitea-Webhooks oder Gitea Actions. Vollständige Pipeline von
+    Commit bis Livegang — konfigurierbar, nachvollziehbar, wiederholbar.
+  </Card>
+  <Card title="Betrieb im Blick" icon="magnifier">
+    Logs, Deployment-Historie und Ressourcenstatus direkt in der Plattform.
+    Kein SSH auf Produktionssysteme mehr nötig.
+  </Card>
+  <Card title="Sicher & souverän" icon="shield">
+    Betrieben auf STACKIT IaaS in der Region Frankfurt (EU) — vollständig unter Kontrolle der BTC AG,
+    DSGVO-konform, keine Public-Cloud-Abhängigkeit.
+  </Card>
+</CardGrid>
+
+---
+
+## Einstieg
+
+<LinkCard
+  title="Einführung"
+  description="Was ist der AI Application Layer? Architektur, Einsatzbereiche und Zielgruppen."
+  href="/einstieg/einfuehrung/"
+/>
+<LinkCard
+  title="Schnellstart"
+  description="In wenigen Schritten zur ersten deployten Anwendung."
+  href="/einstieg/schnellstart/"
+/>
+<LinkCard
+  title="Kernkonzepte"
+  description="Projekte, Anwendungen, Deployments, Domains — die wichtigsten Begriffe erklärt."
+  href="/einstieg/konzepte/"
+/>

src/content/docs/referenz/faq.md

@@ -0,0 +1,99 @@
+---
+title: FAQ
+description: Häufig gestellte Fragen zum AI Application Layer.
+sidebar:
+  order: 2
+---
+
+## Allgemein
+
+### Was kostet die Nutzung des AI Application Layer?
+
+Die Kosten werden intern über die BTC AG verrechnet. Details zur Kostenzuordnung klären mit dem Platform-Team oder über den IT-Servicedesk.
+
+### Wer kann die Plattform nutzen?
+
+Aktuell steht die Plattform internen Teams der BTC AG zur Verfügung. Ein Self-Service-Onboarding ist in Planung.
+
+### Welche Anwendungstypen werden unterstützt?
+
+Alles, was in einem Docker-Container läuft: Web-APIs, Frontends, Background-Worker, Batch-Jobs, statische Sites und mehr.
+
+### Ist die Plattform DSGVO-konform?
+
+Ja. Alle Daten verbleiben in der Region Frankfurt (EU01) auf STACKIT-Infrastruktur, die vollständig von der BTC AG betrieben wird. Es gibt keine Public-Cloud-Abhängigkeit.
+
+---
+
+## Deployment & Build
+
+### Mein Build schlägt fehl — wo finde ich den Fehler?
+
+Im Deployment-Log der Anwendung: Anwendung → **"Deployments"** → Deployment auswählen → **"Log anzeigen"**.
+Der Log zeigt exakt, bei welchem Schritt der Fehler aufgetreten ist.
+
+### Kann ich einen bestimmten Commit deployen, nicht nur den neuesten?
+
+Aktuell wird immer der HEAD des konfigurierten Branch deployt. Das Deployment eines spezifischen Commits ist über die API möglich, wenn der Branch auf diesen Commit zeigt.
+
+### Wie lange dauert ein typisches Deployment?
+
+Das hängt vom Build ab. Einfache Node.js-Apps bauen in 30–60 Sekunden, größere Images mit Compile-Schritten können 2–5 Minuten brauchen. Nach dem Build ist der neue Container innerhalb von Sekunden live.
+
+### Was passiert mit der laufenden App während eines Deployments?
+
+Die laufende Version bleibt aktiv, bis der neue Container bereit ist. Dann wird der Traffic nahtlos umgeschaltet. Es gibt keine Downtime.
+
+### Kann ich einen Deploy rückgängig machen?
+
+Nicht direkt als "Rollback"-Funktion. Aber: Da alle Deployments in der Historie gespeichert sind, könnt ihr den alten Commit taggen und erneut deployen.
+
+---
+
+## Domains & TLS
+
+### Bekomme ich automatisch ein HTTPS-Zertifikat?
+
+Ja. Sobald die Domain korrekt in der Anwendung eingetragen ist und der DNS-Eintrag auf die Plattform zeigt, wird das Zertifikat automatisch über Let's Encrypt ausgestellt.
+
+### Kann ich eine eigene Domain (nicht btc-ag.cloud) verwenden?
+
+Ja. Ihr müsst einen CNAME auf den Plattform-Eintrittspunkt setzen. Details: [Custom Domains](/guides/custom-domains/).
+
+### Mein Zertifikat läuft ab — muss ich etwas tun?
+
+Nein. Let's Encrypt-Zertifikate werden automatisch 30 Tage vor Ablauf erneuert.
+
+---
+
+## API & Automatisierung
+
+### Wo finde ich meine UUIDs (Projekt, Server, App)?
+
+- **Projekt-UUID**: In der Plattform unter Projekteinstellungen
+- **Server-UUID**: Über `GET /api/v1/servers`
+- **App-UUID**: Über `GET /api/v1/applications` oder in der App-Detailansicht
+
+### Kann ich die Plattform vollständig per API steuern (kein UI)?
+
+Ja. Alle Funktionen der Plattform sind über die REST-API verfügbar.
+
+### Gibt es SDKs oder CLI-Tools?
+
+Aktuell keine offiziellen SDKs seitens der Plattform. Die REST-API lässt sich mit beliebigen HTTP-Clients nutzen (`curl`, `httpx`, `axios`, ...).
+
+---
+
+## Betrieb
+
+### Wie bekomme ich Support?
+
+Über den internen IT-Servicedesk der BTC AG oder direkt beim Platform-Team.
+
+### Wo melde ich Bugs oder Feature-Requests?
+
+Im internen Ticketsystem der BTC AG. Für direkte Rückmeldungen: Platform-Team kontaktieren.
+
+### Gibt es Wartungsfenster?
+
+Geplante Wartungen werden im Voraus angekündigt. Notfall-Wartungen können ohne Vorankündigung stattfinden.

src/content/docs/referenz/tech-stack.md

@@ -0,0 +1,80 @@
+---
+title: Tech Stack
+description: Die Technologien hinter dem AI Application Layer — Plattform-Komponenten und unterstützte Runtimes.
+sidebar:
+  order: 1
+---
+
+## Plattform-Komponenten
+
+| Komponente | Technologie | Aufgabe |
+|---|---|---|
+| **Deployment-Orchestrierung** | Coolify | Deployment-Steuerung, UI, API, Build-Pipeline |
+| **Container-Runtime** | Docker | Ausführung aller Anwendungen |
+| **Reverse Proxy** | Traefik | HTTPS-Routing, TLS-Terminierung |
+| **TLS-Zertifikate** | Let's Encrypt | Automatische Ausstellung und Erneuerung |
+| **Versionsverwaltung** | Gitea | Self-hosted Git-Service |
+| **Infrastruktur** | STACKIT IaaS | Virtuelle Maschinen, Region Frankfurt (EU01) |
+| **Infrastructure as Code** | Terraform | Provisionierung der Infrastruktur |
+
+---
+
+## Unterstützte Build-Profile
+
+### Dockerfile (empfohlen)
+
+Jede Anwendung mit einem `Dockerfile` im Repository-Root wird unterstützt.
+Damit ist jede Sprache, jedes Framework und jede Laufzeit möglich.
+
+```
+Sprachen: Python, Node.js, Go, Java, Rust, PHP, Ruby, .NET, ...
+```
+
+### Nixpacks
+
+Nixpacks erkennt die Projektstruktur automatisch und erstellt ein passendes Build-Profil — kein `Dockerfile` nötig.
+
+Gut unterstützte Ökosysteme:
+
+| Sprache / Framework | Erkennungsmerkmal |
+|---|---|
+| Node.js | `package.json` |
+| Python | `requirements.txt`, `Pipfile`, `pyproject.toml` |
+| Go | `go.mod` |
+| Ruby | `Gemfile` |
+| PHP | `composer.json` |
+| Java/Kotlin | `pom.xml`, `build.gradle` |
+| Rust | `Cargo.toml` |
+
+### Static
+
+Für statische Websites (HTML/CSS/JS) ohne Backend.
+Dateien werden direkt via nginx ausgeliefert.
+
+---
+
+## Betriebsumgebung
+
+| Eigenschaft | Wert |
+|---|---|
+| **Cloud-Provider** | STACKIT IaaS |
+| **Region** | eu01 (Frankfurt, Deutschland) |
+| **Betreiber** | BTC AG |
+| **Datenschutz** | DSGVO-konform, kein Datenabfluss in Public Clouds |
+
+---
+
+## Versionspolitik
+
+Die Plattform wird regelmäßig aktualisiert. Breaking Changes werden im Voraus angekündigt.
+Für Versionshinweise und geplante Wartungsfenster wendet euch an das Platform-Team.
+
+---
+
+## Externe Links
+
+- [Coolify Dokumentation](https://coolify.io/docs)
+- [Docker Dokumentation](https://docs.docker.com)
+- [Traefik Dokumentation](https://doc.traefik.io/traefik/)
+- [Gitea Dokumentation](https://docs.gitea.com)
+- [STACKIT IaaS Dokumentation](https://docs.stackit.cloud/stackit/en/virtual-machines-86444220.html)

src/styles/custom.css

@@ -0,0 +1,74 @@
+/* BTC MAIN - Managed AI Now: Brand Colors */
+:root {
+  --sl-color-accent-low: #0c1a3b;
+  --sl-color-accent: #1a56db;
+  --sl-color-accent-high: #93c5fd;
+
+  --sl-font: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --sl-font-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', monospace;
+}
+
+:root[data-theme='dark'] {
+  --sl-color-accent-low: #0c1e4a;
+  --sl-color-accent: #3b82f6;
+  --sl-color-accent-high: #bfdbfe;
+  --sl-color-bg: #0d1117;
+  --sl-color-bg-nav: #161b22;
+  --sl-color-bg-sidebar: #0d1117;
+  --sl-color-hairline-light: #21262d;
+  --sl-color-hairline: #30363d;
+}
+
+/* Hero-Page Tweaks */
+.hero {
+  padding-block: 4rem;
+}
+
+.hero > .hero-html h1 {
+  font-size: clamp(2rem, 5vw, 3.5rem);
+  font-weight: 800;
+  line-height: 1.1;
+}
+
+/* Sidebar Badge Styling */
+.sl-badge {
+  border-radius: 4px;
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+/* Code Blocks */
+pre {
+  border: 1px solid var(--sl-color-hairline);
+  border-radius: 8px;
+}
+
+/* API Endpoint Tables */
+table code {
+  background: var(--sl-color-bg-inline-code);
+  border-radius: 4px;
+  padding: 0.1em 0.4em;
+  font-size: 0.875em;
+}
+
+/* Aside / Callouts */
+.starlight-aside {
+  border-radius: 8px;
+}
+
+/* Custom Header Gradient */
+.site-title {
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+
+/* Footer */
+.social-icons a {
+  opacity: 0.7;
+  transition: opacity 0.2s;
+}
+.social-icons a:hover {
+  opacity: 1;
+}

tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}