> ## Documentation Index
> Fetch the complete documentation index at: https://docs.panderra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# CLAUDE.md — Big Panda Doku

Diese Datei trainiert Claude Code (und andere AI-Assistenten) auf die
Konventionen dieses Doku-Repos. Im Code-Repo `ai_knowledger` gibt es eine
separate CLAUDE.md mit anderem Scope (Code-Standards) — diese hier ist nur
für die Mintlify-Doku.

## Sprache

* **Inhalte: Deutsch** in Du-Form, freundlich, nicht zu formell
* **Code-Beispiele**: Englisch (Kommentare, Variablen-Namen)
* **Frontmatter**: englische Keys (`title`, `description`), deutsche Werte

## Frontmatter-Pflicht

Jede `*.mdx`-Datei beginnt mit Frontmatter:

```yaml theme={null}
---
title: "Aussagekräftiger Seitentitel"
description: "Kurzbeschreibung für SEO und Sidebar (1–2 Sätze)"
---
```

## Inhalts-Standards

* **Code-Blöcke** bekommen immer Sprach-Tag (`bash`, `python`, `json`, `mdx`, …)
* **Bilder** brauchen Alt-Text
* **Interne Links** sind relativ (`/tutorials/claude-desktop`, nicht volle URL)
* **Procedural Content** (Tutorials) startet mit „Voraussetzungen"-Sektion
* **Code-Beispiele** lokal mit `npx mintlify@latest dev` durchgetestet, bevor sie committed werden

## Tonfall

* Du-Form
* Aktive Verben
* Kurze Sätze
* Beispiele vor Theorie

## Big-Panda-Glossar (Begriffe konsistent halten)

* **Knowledge Base / Wissensdatenbank** — zentrale Datenbasis pro Tenant
* **Visibility Ceiling** — Sichtbarkeits-Obergrenze: `public < internal < restricted < community`
* **Drei-Achsen-Auth** — Auth-Modell: Scope + Rolle + Visibility (siehe ADR-015)
* **Document-Types** — `knowledge`, `skill`, `memory`, `process`, `glossary`, `bootstrap`, `skill_index` (siehe ADR-020)
* **MCP-Tools** — Model Context Protocol Endpoints für KI-Clients
* **Bootstrap** — pro Tenant ein Singleton-Eintrag mit Mental-Modell für KI

## Git

* **Niemals** `--no-verify` beim Commit (Pre-commit-Hooks haben einen Grund)
* Commit-Messages auf Englisch, im Imperativ, kurz
* Eine logische Änderung pro Commit

## Lokale Vorschau

```bash theme={null}
npx mintlify@latest dev
```

Öffnet `localhost:3000` mit Live-Reload. Voraussetzung: Node.js 18+.

## Was nicht ins Doku-Repo gehört

* Architektur-Details, ADRs, Sprint-Logs → leben im Code-Repo `ai_knowledger`
* Quellcode der Plattform

## API Reference — wird generiert, nicht von Hand gepflegt

`api-reference/openapi.json` ist die **Single Source of Truth** für die
API-Reference-Sidebar. Die Datei wird **nicht** manuell editiert — sie
entsteht aus den FastAPI-Routen des knowledge-service.

### Spec aktualisieren

Vom Code-Repo `ai_knowledger/` aus:

```bash theme={null}
cd platform
bash scripts/export-openapi-to-docs.sh
```

Das Skript:

1. Ruft `app.openapi()` im laufenden knowledge-service-Container auf
2. Filtert auf die fünf öffentlichen Tags (Products, Knowledge Entries,
   Categories, Sites, Search) — interne Routen wie `/me/admin/...` oder
   `/me/search-settings` bleiben draußen
3. Schreibt Pfade auf das Gateway-Format um (`/products` →
   `/api/knowledge/products`)
4. Setzt Bearer-Auth-Schema und tenant-templated Server-URL
5. Schreibt das Resultat nach `big_panda_docs/api-reference/openapi.json`

Wenn an den FastAPI-Routen etwas geändert wird (neue Felder, neuer
Endpoint), Skript erneut laufen lassen, dann committen.

### Was Mintlify daraus macht

`docs.json` referenziert die Spec unter `navigation.groups[].openapi:
"api-reference/openapi.json"`. Mintlify generiert beim nächsten Build
automatisch eine Reference-Page pro Endpoint mit Try-It-Out-Console,
Request-Schema, Response-Schema und Sprach-Examples (cURL, Python,
JavaScript). Keine manuellen MDX-Pages dafür schreiben.

### Wenn ein Endpoint absichtlich nicht öffentlich sein soll

Dann gehört der Tag nicht in `PUBLIC_TAGS` von
`platform/services/knowledge-service/scripts/export_openapi.py`. Der
Tag-Filter ist die Schnittstelle zwischen "intern" und "extern". Lieber
einen Tag umbenennen oder einen neuen Tag einführen als die Doku
drum herum zu frickeln.

## Querverweise zum Code-Repo

Wenn Architektur oder Datenmodell-Details für Doku-Leser (Pilot-Kunden,
Dritt-Entwickler) relevant sind: erkläre sie hier in der nötigen Tiefe, ohne
auf interne Sprint-Logs oder Code-Pfade zu verweisen.