Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.panderra.de/llms.txt

Use this file to discover all available pages before exploring further.

​
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: 
---
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

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: 
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.