---
name: pmwiki
version: 1.0
language: de
description: >
  Arbeitsanweisung für KI-Agenten zum sicheren Bearbeiten, Erweitern,
  Analysieren und Warten einer aktuellen PmWiki-Installation. Enthält
  PmWiki-Markup, Seitenstruktur, local/config.php, CSS, Skins, Cookbook,
  eigenes Markup, Uploads, Sicherheit, Fehlersuche, Performance und
  einen vorsichtigen Agenten-Workflow.
---

# PmWiki – Agent Skill

## 1. Ziel dieses Skills

Dieser Skill soll einem KI-Agenten ermöglichen, eine **aktuelle stabile PmWiki-Installation** selbständig, nachvollziehbar und möglichst sicher zu bearbeiten.

Der Agent soll insbesondere:

- PmWiki-Seiten lesen und bearbeiten können,
- PmWiki-Markup korrekt erzeugen,
- Gruppen, Seiten, Site-Seiten und Anhänge verstehen,
- Inhalt, Konfiguration, CSS, Skin und PHP-Erweiterungen sauber trennen,
- `local/config.php` und lokale Konfigurationsdateien bearbeiten,
- Cookbook-Rezepte finden, beurteilen und einbinden,
- eigenes Markup mit `Markup()` erstellen,
- Skins und Templates anpassen,
- Uploads, Rechte und Sicherheit berücksichtigen,
- Fehler systematisch diagnostizieren,
- Performance-Probleme eingrenzen,
- Änderungen klein, prüfbar und reversibel halten.

Dieser Skill ist **keine bloße Syntaxliste**, sondern eine Arbeitsanweisung für autonome oder halbautonome Agenten.

---

# 2. Grundannahmen

## 2.1 Aktuelle PmWiki-Version

Für diese Umgebung gilt grundsätzlich:

> Es ist die jeweils aktuelle stabile PmWiki-Version installiert.

Der Agent muss deshalb bei normalen Aufgaben **nicht zuerst eine Altversions-Kompatibilitätsprüfung durchführen**.

Ausnahmen:

- ein altes Cookbook-Rezept wird verwendet,
- alter lokaler PHP-Code ist vorhanden,
- alter Skin-Code wird übernommen,
- eine PHP-Warnung oder Deprecated-Meldung tritt auf,
- die Aufgabe betrifft ein Upgrade oder eine konkrete Sicherheitslücke.

Dann sind Versions- und PHP-Kompatibilität ausdrücklich zu prüfen.

## 2.2 Aktuelle PHP-Version bevorzugen

PmWiki soll auf einer noch mit Sicherheitsupdates versorgten PHP-Version laufen.

Bei PHP-Problemen zuerst unterscheiden:

- PmWiki-Core,
- eigenes PHP,
- Skin-PHP,
- Cookbook-Rezept.

Alte Rezepte sind wesentlich häufiger die Ursache für PHP-Kompatibilitätsprobleme als ein aktueller PmWiki-Core.

---

# 3. Wichtigste Regel: Den Core nicht verändern

Normalerweise **nicht direkt bearbeiten**:

```text
pmwiki.php
scripts/
wikilib.d/
```

Lokale Anpassungen gehören stattdessen in:

```text
local/
cookbook/
pub/css/
pub/skins/<eigener-skin>/
```

Grundregel:

> Native PmWiki-Erweiterungspunkte verwenden, nicht den Core patchen.

Direkte Core-Änderungen werden bei Updates überschrieben und erschweren Fehlersuche und Wartung.

---

# 4. Wichtigste Informationsquellen

Bei Unsicherheit sollen Quellen in dieser Reihenfolge verwendet werden.

## 4.1 Offizielle PmWiki-Dokumentation

### Zentrale Einstiegsseiten

- https://www.pmwiki.org/wiki/PmWiki/DocumentationIndex
- https://www.pmwiki.org/wiki/PmWiki/MarkupMasterIndex
- https://www.pmwiki.org/wiki/PmWiki/FAQ
- https://www.pmwiki.org/wiki/PmWiki/Troubleshooting

### Seitensyntax / Markup

- https://www.pmwiki.org/wiki/PmWiki/BasicEditing
- https://www.pmwiki.org/wiki/PmWiki/TextFormattingRules
- https://www.pmwiki.org/wiki/PmWiki/Links
- https://www.pmwiki.org/wiki/PmWiki/Images
- https://www.pmwiki.org/wiki/PmWiki/Tables
- https://www.pmwiki.org/wiki/PmWiki/TableDirectives
- https://www.pmwiki.org/wiki/PmWiki/WikiStyles
- https://www.pmwiki.org/wiki/PmWiki/PageDirectives
- https://www.pmwiki.org/wiki/PmWiki/ConditionalMarkup
- https://www.pmwiki.org/wiki/PmWiki/PageLists
- https://www.pmwiki.org/wiki/PmWiki/PageTextVariables
- https://www.pmwiki.org/wiki/PmWiki/PageVariables
- https://www.pmwiki.org/wiki/PmWiki/IncludeOtherPages

### Administration / Entwicklung

- https://www.pmwiki.org/wiki/PmWiki/LocalCustomizations
- https://www.pmwiki.org/wiki/PmWiki/GroupCustomizations
- https://www.pmwiki.org/wiki/PmWiki/Variables
- https://www.pmwiki.org/wiki/PmWiki/Functions
- https://www.pmwiki.org/wiki/PmWiki/CustomMarkup
- https://www.pmwiki.org/wiki/PmWiki/Skins
- https://www.pmwiki.org/wiki/PmWiki/SkinTemplates
- https://www.pmwiki.org/wiki/PmWiki/Security
- https://www.pmwiki.org/wiki/PmWiki/PasswordsAdmin
- https://www.pmwiki.org/wiki/PmWiki/AuthUser
- https://www.pmwiki.org/wiki/PmWiki/Uploads
- https://www.pmwiki.org/wiki/PmWiki/UploadsAdmin
- https://www.pmwiki.org/wiki/PmWiki/DebugVariables
- https://www.pmwiki.org/wiki/PmWiki/SpecialPages

### Releases / Sicherheit

- https://www.pmwiki.org/wiki/PmWiki/ReleaseNotes
- https://www.pmwiki.org/wiki/PmWiki/ChangeLog
- https://www.pmwiki.org/wiki/PmWiki/Upgrades
- https://www.pmwiki.org/wiki/PmWiki/Download

## 4.2 PmWiki Cookbook

- https://www.pmwiki.org/wiki/Cookbook/Cookbook

Cookbook-Rezepte sind Zusatzsoftware.

Vor dem Einbau eines Rezepts prüfen:

- Zweck,
- Maintainer,
- Aktualität,
- PHP-Kompatibilität,
- PmWiki-Kompatibilität,
- offene PITS-/Talk-Hinweise,
- Sicherheitsauswirkungen,
- ob die Funktion inzwischen im PmWiki-Core vorhanden ist.

Ein Rezept niemals allein aufgrund seines Namens installieren.

## 4.3 Deutsche Dokumentation

Deutschsprachige Dokumentation unter:

```text
PmWikiDe.*
```

ist als Erklärung hilfreich.

Bei technischen Details und neuen Funktionen im Zweifel die aktuelle englische Hauptdokumentation bevorzugen.

## 4.4 Lokale Installation hat Vorrang

Die reale lokale Installation entscheidet über das tatsächliche Verhalten.

Wenn Dokumentation und lokale Installation scheinbar widersprechen, zuerst suchen nach:

- Custom Markup,
- Cookbook-Rezepten,
- Skin-Code,
- `local/config.php`,
- gruppen- oder seitenspezifischer Konfiguration,
- `GroupHeader` / `GroupFooter`,
- angepassten Site-Seiten.

---

# 5. Typische PmWiki-Dateistruktur

```text
pmwiki.php

local/
    config.php
    GroupName.php
    GroupName.PageName.php

cookbook/
    recipe.php

pub/
    css/
        local.css
        GroupName.css
        GroupName.PageName.css
    skins/
        myskin/
            myskin.tmpl
            myskin.php
            myskin.css

scripts/
wikilib.d/
wiki.d/
uploads/
docs/
```

## 5.1 Bedeutung

| Ort | Bedeutung | Agentenregel |
|---|---|---|
| `pmwiki.php` | Core | normalerweise nicht bearbeiten |
| `scripts/` | Core-Skripte | normalerweise nicht bearbeiten |
| `wikilib.d/` | ausgelieferte Wiki-Seiten | nicht blind verändern |
| `wiki.d/` | lokale Seiten + Historie | nicht wie normale Markdown-Dateien behandeln |
| `local/config.php` | zentrale lokale PHP-Konfiguration | primärer Konfigurationsort |
| `local/Group.php` | gruppenspezifische Konfiguration | für gruppenspezifisches Verhalten |
| `local/Group.Page.php` | seitenspezifische Konfiguration | sparsam verwenden |
| `cookbook/` | Erweiterungen / Rezepte | guter Ort für eigene Features |
| `pub/css/local.css` | globale lokale CSS-Regeln | bevorzugter globaler CSS-Ort |
| `pub/css/Group.css` | Gruppen-CSS | für eine Wiki-Gruppe |
| `pub/css/Group.Page.css` | Seiten-CSS | für eine einzelne Seite |
| `pub/skins/` | Layout / HTML-Schale | eigenen Skin bevorzugen |
| `uploads/` | Anhänge | als Inhaltsdaten behandeln |

---

# 6. Ganz wichtig: `wiki.d/` nicht direkt wie Markdown bearbeiten

PmWiki speichert Seiten üblicherweise im PageStore unter:

```text
wiki.d/
```

Diese Dateien enthalten nicht nur sichtbaren Seitentext, sondern auch Metadaten und Revisionsinformationen.

Deshalb:

## Bevorzugt

- Seite über `?action=edit` bearbeiten,
- PmWiki-eigene Schreibfunktionen verwenden,
- vorhandene Import-/Automationsmechanismen nutzen.

## Nur mit besonderer Vorsicht

Direktes Editieren von `wiki.d/*` per FTP, Shell oder Agent.

Das ist eher für:

- Wiederherstellung,
- Migration,
- Spezialadministration,
- kontrollierte Massenkonvertierung.

Vorher immer Backup anlegen.

---

# 7. Seitenmodell

Eine PmWiki-Seite heißt normalerweise:

```text
Group.PageName
```

Beispiele:

```text
Main.HomePage
Ethos.Liebe
Natur.Wachsen
Site.SideBar
```

## Wichtige Begriffe

- **Group** = Wiki-Gruppe
- **Name** = Seitenname innerhalb der Gruppe
- **FullName** = `Group.Name`

Wichtige Seitenvariablen:

```text
{$Group}
{$Name}
{$FullName}
{$Title}
{$PageUrl}
{$Version}
{$VersionNum}
```

Bei komplexer Verwendung immer `PmWiki/PageVariables` prüfen.

---

# 8. PmWiki ist nicht Markdown

Ein Agent darf Markdown nicht ungeprüft in PmWiki kopieren.

Beispiel:

| Bedeutung | Markdown | PmWiki |
|---|---|---|
| Überschrift | `## Titel` | `!! Titel` |
| kursiv | `*Text*` | `''Text''` |
| fett | `**Text**` | `'''Text'''` |
| Link | `[Text](URL)` | `[[URL | Text]]` |
| Liste | `- Punkt` | `* Punkt` |
| Nummerierung | `1. Punkt` | `# Punkt` |
| Codeblock | ``` | `[@ ... @]` |
| Tabelle | Markdown-Pipes | PmWiki `|| ... ||` |

---

# 9. Wichtigste PmWiki-Syntax

## 9.1 Absätze

Leerzeile = neuer Absatz.

```text
Erster Absatz.

Zweiter Absatz.
```

## 9.2 Überschriften

```text
!! Hauptüberschrift
!!! Unterüberschrift
!!!! Weitere Ebene
```

## 9.3 Hervorhebung

```text
''kursiv''
'''fett'''
'''''fett und kursiv'''''
```

## 9.4 Listen

### Aufzählung

```text
* Punkt 1
* Punkt 2
** Unterpunkt
*** weiterer Unterpunkt
```

### Nummeriert

```text
# Erster Punkt
# Zweiter Punkt
## Unterpunkt
```

### Gemischte Verschachtelung

PmWiki kann nummerierte und unnummerierte Ebenen kombinieren.

## 9.5 Definitionsliste

```text
:Begriff:Definition
```

Diese Syntax kann gleichzeitig als PageTextVariable dienen.

## 9.6 Zeilenumbruch

```text
Erste Zeile\\
Zweite Zeile
```

Nur verwenden, wenn ein erzwungener Umbruch wirklich gewollt ist.

## 9.7 Horizontale Linie

```text
----
```

## 9.8 Markup unterdrücken

```text
[=Dieser Text wird nicht als normales PmWiki-Markup interpretiert.=]
```

## 9.9 Präformatierter / Code-Block

```text
[@
$variable = 'test';
[[kein Link]]
@]
```

---

# 10. Links

## 10.1 Interner Link

```text
[[Ethos.Liebe]]
```

## 10.2 Link mit sichtbarer Beschriftung

```text
[[Ethos.Liebe | Liebe im Kolibriethos]]
```

## 10.3 Seite derselben Gruppe

```text
[[AndereSeite]]
```

## 10.4 Externer Link

```text
[[https://www.example.org/ | Beispiel]]
```

## 10.5 Anker

Anker setzen:

```text
[[#abschnitt]]
```

Darauf verlinken:

```text
[[#abschnitt | Zum Abschnitt]]
```

Andere Seite:

```text
[[Ethos.Liebe#abschnitt | Abschnitt auf Liebe]]
```

## 10.6 Kategorien

Typisch:

```text
[[!KategorieName]]
```

Kategorien können in `(:pagelist category=...:)` verwendet werden.

---

# 11. Bilder und Anhänge

## 11.1 Anhang anzeigen

```text
Attach:bild.jpg
```

## 11.2 Bild mit Alternativ-/Titeltext

```text
Attach:bild.jpg"Beschreibung des Bildes"
```

## 11.3 Datei verlinken statt einbetten

```text
[[Attach:dokument.pdf]]
```

## 11.4 Bild aus anderer Gruppe

```text
Attach:AndereGruppe./bild.jpg
```

Die genaue Auflösung hängt von `$UploadPrefixFmt` ab.

## 11.5 Externes Bild

```text
https://example.org/bild.jpg"Beschreibung"
```

## 11.6 Bild als Link

```text
[[https://example.org/ | Attach:bild.jpg"Beschreibung"]]
```

## 11.7 Größen und Styles

Beispiel:

```text
%width=300px% Attach:bild.jpg %%
```

Für häufig wiederkehrende Bilddarstellung besser:

- CSS-Klasse definieren,
- gegebenenfalls eigenes Markup verwenden,
- nicht auf jeder Seite lange Inline-Styles wiederholen.

---

# 12. WikiStyles

## 12.1 Inline

```text
%red% roter Text %%
%bgcolor=#ffffcc% markierter Text %%
%class=hinweis% Text %%
```

## 12.2 Block

```text
>>class=hinweis<<
Ein ganzer Block.

* Auch Listen sind möglich.
>><<
```

## 12.3 `(:div:)`

```text
(:div class="hinweis":)
Inhalt
(:divend:)
```

Nicht verwechseln:

- WikiStyle-Syntax,
- HTML-Klassen in `(:div:)`,
- echte CSS-Regeln.

## 12.4 CSS bevorzugen

```css
.hinweis {
    padding: 1rem;
    margin: 1rem 0;
    border-radius: 0.5rem;
}
```

wird vorzugsweise in der passenden CSS-Datei gepflegt.

---

# 13. Tabellen

## 13.1 Einfache Tabelle

```text
|| border=1
||! Überschrift 1 ||! Überschrift 2 ||
|| Zelle 1 || Zelle 2 ||
|| Zelle 3 || Zelle 4 ||
```

## 13.2 Erweiterte Tabellen

PmWiki kennt Tabellen-Direktiven wie:

```text
(:table:)
(:cell:)
(:cellnr:)
(:tableend:)
```

Für Attribute und komplexere Tabellen:

- `PmWiki/Tables`
- `PmWiki/TableDirectives`

prüfen.

Tabellen nicht unnötig als allgemeines Seitenlayout missbrauchen.

---

# 14. Wichtige Direktiven

PmWiki-Direktiven haben typischerweise die Form:

```text
(:direktive parameter:)
```

## 14.1 Seitentitel

```text
(:title Ein besserer Seitentitel:)
```

## 14.2 Beschreibung

```text
(:description Kurze Beschreibung der Seite:)
```

## 14.3 Andere Seite einfügen

```text
(:include Ethos.Liebe:)
```

Inhalte nicht duplizieren, wenn `(:include:)` strukturell besser passt.

## 14.4 Bedingte Inhalte

```text
(:if condition:)
Inhalt
(:else:)
Alternative
(:ifend:)
```

Mögliche Bedingungen können sich beziehen auf:

- Seite,
- Gruppe,
- Aktion,
- Rechte,
- Variablen,
- Existenz einer Seite,
- weitere definierte Bedingungen.

Komplexe Bedingungen in `PmWiki/ConditionalMarkup` prüfen.

## 14.5 Pagelist

```text
(:pagelist group=Ethos list=normal:)
```

Pagelists können sehr leistungsfähig und bei großen Wikis auch teuer sein.

Deshalb möglichst einschränken:

```text
(:pagelist group=Ethos name=Liebe*,Grund* list=normal:)
```

Unbeschränkte Pagelists auf häufig aufgerufenen Seiten vermeiden.

## 14.6 Suche

```text
(:searchbox:)
(:searchresults:)
```

## 14.7 Redirect

```text
(:redirect Ethos.Homepage:)
```

## 14.8 Skin-Bereiche ausblenden

Je nach Skin unter anderem:

```text
(:noheader:)
(:noleft:)
(:notitle:)
(:nofooter:)
```

Diese funktionieren nur sinnvoll, wenn der Skin die entsprechenden Formatbereiche unterstützt.

---

# 15. PageTextVariables – sehr wichtig für Agenten

PageTextVariables eignen sich hervorragend für strukturierte, agentenlesbare Seiten.

## 15.1 Definitionsform

```text
:Autor:Hans
:Thema:Liebe
:Status:Entwurf
```

Lesen:

```text
{$:Autor}
{$:Thema}
{$:Status}
```

## 15.2 Direktivenform

```text
(:Autor: Hans :)
(:Thema: Liebe :)
(:Status: Entwurf :)
```

## 15.3 Sinnvolle Verwendung

PTVs eignen sich für:

- Metadaten,
- Bildkataloge,
- Statusinformationen,
- Autoren,
- Themen,
- Schlagwörter,
- Quelldaten,
- Datum,
- automatische Listen,
- PageListTemplates,
- agentisch gepflegte Wissensstrukturen.

Beispiel:

```text
(:ImageFile: Begegnung01.jpg :)
(:Theme: Begegnung :)
(:Status: veröffentlicht :)
(:Source: KI-Bild :)

!! Kurzbeschreibung

Menschen begegnen einander zwischen Nähe und Eigenständigkeit.
```

## 15.4 Schema nicht stillschweigend verändern

Wenn eine Website bereits ein PTV-Schema hat, dieses beibehalten.

Beispiel stabile Namen:

```text
:ImageFile:
:Theme:
:Summary:
:Source:
:Status:
:Created:
:Modified:
```

---

# 16. Wichtige Spezialseiten

Der Agent sollte unter anderem diese Mechanismen kennen:

```text
Group.GroupHeader
Group.GroupFooter
Group.GroupAttributes

Site.SideBar
Site.PageActions
Site.EditForm
Site.EditQuickReference
Site.Search
Site.PageNotFound

SiteAdmin.*
```

Vor einer neuen PHP-Lösung prüfen, ob die gewünschte Funktion bereits über:

- `GroupHeader`,
- `GroupFooter`,
- `Site.*`,
- `SiteAdmin.*`,
- PageListTemplates

lösbar ist.

---

# 17. `local/config.php`

## 17.1 Zweck

`local/config.php` ist der wichtigste Ort für globale lokale Konfiguration.

Beispiele:

```php
<?php
$WikiTitle = 'Mein Wiki';
$Skin = 'mein-skin';
$EnableUpload = 1;
```

## 17.2 Core-Variablen nicht erfinden

Vor Verwendung einer PmWiki-Variable prüfen:

- `PmWiki/Variables`
- gegebenenfalls lokale Definitionen im bestehenden Code.

## 17.3 Rezepte laden

Typisch:

```php
include_once("$FarmD/cookbook/meinrezept.php");
```

Vorher die jeweilige Rezeptdokumentation lesen.

Manche Variablen müssen **vor**, andere **nach** dem Include gesetzt werden.

## 17.4 PHP-only Dateien

Bei reinen PHP-Konfigurationsdateien ist ein abschließendes:

```php
?>
```

normalerweise unnötig.

So vermeidet man versehentliche Ausgabe/Whitespace nach dem PHP-Code.

## 17.5 Direkte Funktionsaufrufe

Funktionen wie:

```php
CondAuth()
PageVar()
PageTextVar()
RetrieveAuthPage()
```

sollten erst verwendet werden, wenn PmWiki dafür ausreichend initialisiert ist.

Bei komplexer Konfiguration die offizielle Seite `LocalCustomizations` beachten.

---

# 18. Gruppen- und seitenspezifische Konfiguration

Für eine Gruppe:

```text
local/Ethos.php
```

Für eine einzelne Seite:

```text
local/Ethos.Liebe.php
```

CSS entsprechend:

```text
pub/css/Ethos.css
pub/css/Ethos.Liebe.css
```

Diese Mechanismen sind häufig besser als viele `if ($pagename == ...)`-Blöcke in `config.php`.

## Sicherheitswarnung

Zugriffsrechte/Passwörter nicht unbedacht nur in einer gruppenspezifischen PHP-Datei definieren.

Eine Seite aus einer anderen Gruppe kann Inhalte beispielsweise über `(:include:)` anfordern, ohne dass dieselbe gruppenspezifische Konfigurationsdatei zwingend im erwarteten Kontext geladen wurde.

Sicherheitsrelevante Zugriffsregeln global und nach PmWiki-Dokumentation konfigurieren.

---

# 19. CSS-Kaskade

Typische lokale CSS-Orte:

```text
pub/css/local.css
pub/css/Group.css
pub/css/Group.Page.css
```

Der Agent soll immer prüfen:

1. Welche CSS-Dateien sind tatsächlich geladen?
2. In welcher Reihenfolge?
3. Welche Regel gewinnt durch Spezifität?
4. Gibt es eine spätere Media Query?
5. Wird mobil ein anderer Skin oder eine andere CSS-Datei geladen?
6. Ist der Browsercache relevant?

## 19.1 `<!--HTMLHeader-->`

Bei Skins ist die Position von:

```html
<!--HTMLHeader-->
```

wichtig.

PmWiki und Rezepte fügen dort CSS und Head-Elemente ein.

Die Reihenfolge der Skin-CSS-Dateien relativ zu `<!--HTMLHeader-->` beeinflusst, ob `local.css` Skin-Regeln überschreiben kann.

---

# 20. Skins und Templates

## 20.1 Eigenen Skin bevorzugen

Wenn größere Layoutänderungen nötig sind, einen eigenen Skin verwenden statt einen mitgelieferten Skin dauerhaft zu patchen.

Typische Struktur:

```text
pub/skins/meinskin/
    meinskin.tmpl
    meinskin.php
    meinskin.css
```

Aktivierung:

```php
$Skin = 'meinskin';
```

## 20.2 Wichtige Template-Marker

Typisch und wichtig:

```html
<!--HTMLHeader-->
<!--PageText-->
<!--HTMLFooter-->
```

Je nach Skin außerdem Bereiche für Header, Sidebar, Footer und Actions.

`<!--HTMLFooter-->` nicht unnötig entfernen; Rezepte können darauf angewiesen sein.

## 20.3 Template-Änderungen testen

Nach Änderungen prüfen:

- valides HTML,
- Desktop,
- Smartphone,
- sehr schmale Breite,
- Sidebar,
- PageActions,
- Editieransicht,
- Suchseite,
- Login/Logout,
- Seiten ohne Inhalt,
- Seiten mit sehr vielen Bildern.

---

# 21. Eigenes Markup mit `Markup()`

PmWiki kann über PHP um eigene Syntax erweitert werden.

Grundform:

```php
Markup($name, $when, $pattern, $replace);
```

## 21.1 Einfache Ersetzung

```php
Markup(
    'ke-hello',
    'inline',
    '/%%HELLO%%/',
    'Hallo'
);
```

## 21.2 Callback verwenden

Wenn Logik erforderlich ist, Callback benutzen:

```php
Markup(
    'ke-box',
    'directives',
    '/\\(:kebox\\s*(.*?):\\)/',
    'KEBoxMarkup'
);

function KEBoxMarkup($m) {
    $args = $m[1] ?? '';
    return "<div class='ke-box'>" . htmlspecialchars($args) . "</div>";
}
```

Dies ist nur ein Grundmuster. Für produktiven Code muss geprüft werden, ob der Rückgabewert als HTML oder erneut als Wiki-Markup verarbeitet werden soll.

## 21.3 Kein `Markup_e()`

Nicht neu verwenden:

```php
Markup_e(...)
```

und keine alten Regex-Muster mit `/e` einführen.

Moderne Implementierungen nutzen `Markup()` + Callback.

## 21.4 Reihenfolge ist wichtig

Der zweite Parameter von `Markup()` steuert, wann die Regel relativ zu anderen Regeln verarbeitet wird.

Beispiele können sein:

```text
directives
inline
<links
>links
```

Bei komplexem Markup nicht raten.

Prüfen:

- `PmWiki/CustomMarkup`,
- bestehende lokale Regeln,
- gegebenenfalls `?action=ruleset` bei sicher aktivierter Diagnose.

## 21.5 Eindeutige interne Namen

Bevorzugt Projektpräfix:

```text
ke-hello
ke-imagebox
ke-gallery
```

Öffentliche Wiki-Syntax kann trotzdem kurz bleiben:

```text
(:hallo:)
```

aber PHP-Funktions- und Rule-Namen sollten kollisionsarm sein.

---

# 22. Wann eigenes Markup sinnvoll ist

Eigenes Markup ist sinnvoll bei:

- wiederkehrenden komplexen Layoutblöcken,
- parametrisierbaren Komponenten,
- Datenbankzugriff,
- kontrolliert generiertem HTML,
- speziellen Bildkomponenten,
- dynamischen Inhalten,
- websiteweiten Komponenten.

Nicht sofort PHP schreiben, wenn native PmWiki-Mittel reichen.

Vorher prüfen:

```text
(:include:)
GroupHeader
GroupFooter
WikiStyles
PageTextVariables
PageLists
PageListTemplates
```

---

# 23. Rezept-/Cookbook-Entwicklung

Eigene größere Funktionen besser als separates Rezept schreiben:

```text
cookbook/ke-feature.php
```

und in `config.php` laden.

Vorteile:

- `config.php` bleibt übersichtlich,
- Funktion ist separat testbar,
- kann in Git versioniert werden,
- leichter deaktivierbar,
- leichter dokumentierbar.

Jedes eigene Rezept sollte am Anfang kurz dokumentieren:

```php
<?php
/**
 * ke-feature.php
 * Zweck: ...
 * Öffentliche Syntax: (:kefeature ...:)
 * Abhängigkeiten: ...
 */
```

---

# 24. Sicherheit

## 24.1 PHP ist ausführbarer Code

Vor jeder PHP-Erweiterung prüfen:

- Welche Eingaben kommen vom Benutzer?
- Werden Parameter validiert?
- Wird HTML korrekt escaped?
- Kann ein Dateipfad manipuliert werden?
- Kann SQL manipuliert werden?
- Kann fremder JavaScript-Code eingeschleust werden?
- Werden Geheimnisse ausgegeben?

## 24.2 Keine beliebige HTML-/JS-Ausführung für normale Editoren

Keine Funktion bauen, die beliebigen Benutzereingabetext ungeprüft als:

```html
<script>
...
</script>
```

oder beliebiges HTML in die Seite übernimmt.

## 24.3 Passwörter / Rechte

Nicht einfach Rechte lockern, damit eine Funktion "funktioniert".

Prüfen:

- Seitenattribute,
- Gruppenattribute,
- `$DefaultPasswords`,
- AuthUser,
- `CondAuth()`,
- Custom-Rezepte.

## 24.4 PageVariables und geschützte Seiten

Bei geschützten Inhalten beachten, dass bestimmte PageVariables Informationen über andere Seiten offenlegen können.

Die aktuelle PmWiki-Dokumentation zu `pvCoreAuthCache` und sicherheitsbewussten PageVariable-Definitionen beachten.

## 24.5 Geheimnisse

Nicht in Git einchecken oder in Antworten ausgeben:

- FTP-Passwörter,
- Datenbankpasswörter,
- API-Keys,
- private Schlüssel,
- Sessiondaten.

---

# 25. Uploads

PmWiki-Uploads sind standardmäßig ein eigener Sicherheitsbereich.

Vor Änderungen prüfen:

```php
$EnableUpload
$UploadDir
$UploadUrlFmt
$UploadPrefixFmt
```

Zusätzlich:

- erlaubte Dateitypen,
- maximale Größe,
- Upload-Recht,
- Überschreibschutz,
- direkter Webzugriff auf `uploads/`.

## Wichtiger Grundsatz

Eine lesegeschützte Wiki-Seite bedeutet nicht automatisch, dass eine Datei unter `uploads/` ebenfalls gegen direkten URL-Zugriff geschützt ist.

Bei privaten Anhängen sichere Attachment-Konfiguration einsetzen.

Keine serverseitig ausführbaren Upload-Dateitypen freischalten, wenn keine klar abgesicherte Architektur dafür existiert.

---

# 26. Datenbankintegration

PmWiki ist primär seitenbasiert, kann aber über ein Rezept mit MySQL/MariaDB/SQLite oder anderen Datenquellen verbunden werden.

## 26.1 Regeln

- PDO oder gepflegte Datenbankschnittstelle verwenden,
- Prepared Statements,
- keine SQL-Konkatenation aus Benutzereingaben,
- Zugangsdaten außerhalb öffentlich zugänglicher Dateien halten,
- Ergebnismenge begrenzen,
- Fehlerzustand definieren,
- langsame Abfragen vermeiden,
- nach Möglichkeit cachen.

## 26.2 Mögliche Ausgabeformen

Ein Rezept kann liefern:

- reinen Text,
- kontrolliertes HTML,
- PmWiki-Markup,
- Links,
- Tabellen,
- JSON für eine JS-Komponente.

Der Agent muss klar entscheiden, **welche Ausgabeschicht** verwendet wird.

Untrusted Datenbankinhalt niemals ungeprüft als HTML ausgeben.

---

# 27. JavaScript

JavaScript nicht direkt in viele Wiki-Seiten kopieren.

Bevorzugt:

- zentrale JS-Datei,
- Einbindung über Skin oder `$HTMLFooterFmt` / `$HTMLHeaderFmt`,
- eindeutige Klassen/Data-Attribute,
- progressive Erweiterung.

Bei JS-Fehlern prüfen:

- Browser-Konsole,
- DOM-Struktur,
- doppelte IDs,
- Lade-Reihenfolge,
- `defer` / `async`,
- mobile Templates,
- Consent-Manager,
- Content-Security-Policy.

---

# 28. Diagnostik

## 28.1 `$EnableDiag`

PmWiki besitzt Diagnosefunktionen.

Temporär:

```php
$EnableDiag = 1;
```

Je nach Konfiguration können dann unter anderem Aktionen wie diese verfügbar sein:

```text
?action=diag
?action=ruleset
```

Auf Produktionsseiten Diagnose nicht ungeschützt dauerhaft aktiviert lassen.

## 28.2 Stopwatch

Für Performance-Analyse:

```php
$EnableStopWatch = 1;
```

Im Skin kann z. B. verwendet werden:

```html
<!--function:StopWatchHTML 1-->
```

Nach Diagnose wieder entfernen/deaktivieren, wenn nicht dauerhaft gewünscht.

## 28.3 PHP-Lint

Nach PHP-Änderungen, wenn CLI verfügbar:

```bash
php -l local/config.php
php -l cookbook/ke-feature.php
```

Ein erfolgreicher Syntaxcheck bedeutet noch nicht, dass Laufzeit und PmWiki-Integration korrekt sind.

---

# 29. Performance-Diagnose

Wenn eine Seite langsam ist, systematisch isolieren.

## 29.1 Zuerst unterscheiden

### Server/PHP langsam

Merkmale:

- lange Time To First Byte,
- Stopwatch zeigt Verzögerung,
- Delay vor dem sichtbaren Rendern.

Mögliche Ursachen:

- Rezept,
- Datenbank,
- Authentifizierung,
- Passwort-Hashing,
- große PageLists,
- große Indexsuche,
- langsame Regex-Regel,
- Dateisystem,
- Remote Request im PHP-Code.

### Browser langsam

Merkmale:

- HTML kommt schnell,
- danach lange Darstellung/Laden.

Mögliche Ursachen:

- große Bilder,
- zu viele Bilder,
- JavaScript,
- externe Scripts,
- Consentmanager,
- Fonts,
- CSS,
- großer DOM,
- Layout Shifts.

## 29.2 Vorgehensweise

1. sehr einfache Kontrollseite vergleichen,
2. Stopwatch ansehen,
3. Netzwerk-Waterfall ansehen,
4. verdächtige Rezepte einzeln deaktivieren,
5. große Pagelists eingrenzen,
6. externe Ressourcen kontrollieren,
7. Bildgrößen prüfen,
8. Lazy Loading prüfen,
9. DOM-Größe prüfen,
10. Komponenten einzeln wieder aktivieren.

Nicht fünf Systeme gleichzeitig verändern.

---

# 30. Performance-Regeln für neue Agenten-Funktionen

Vermeiden:

- unbeschränkte Pagelists auf jeder Seite,
- komplettes Verzeichnis-Scanning pro Request,
- Remote-HTTP-Aufrufe beim Seitenrendern,
- große Bibliotheken für kleine Funktionen,
- doppelte CSS-/JS-Dateien,
- sehr große Inline-Skripte,
- hunderte eager geladene Bilder,
- unnötig große Originalbilder,
- Regex mit extremem Backtracking,
- Datenbankabfragen ohne Limit.

Bei bildreichen Seiten:

- Dimensionen angeben, wenn sinnvoll,
- responsive CSS,
- Lazy Loading unterhalb des sichtbaren Bereichs,
- Thumbnails / angepasste Größen,
- Smartphone-Verhalten testen.

---

# 31. Fehlerbilder und typische Ursachen

## 31.1 Markup wird als Text angezeigt

Prüfen:

- Tippfehler,
- Rezept eingebunden?
- `Markup()` registriert?
- falsche Markup-Reihenfolge?
- Regex fehlerhaft?
- Inhalt in `[= ... =]` oder `[@ ... @]` eingeschlossen?
- Bedingung verhindert Ausführung?

## 31.2 CSS wirkt nicht

Prüfen:

- echte Klasse im erzeugten DOM,
- CSS-Datei tatsächlich geladen,
- Media Query,
- Spezifität,
- später geladene Regel,
- Cache,
- anderer Mobile-Skin,
- Position von `<!--HTMLHeader-->`.

## 31.3 Weiße Seite / HTTP 500

Sofort:

1. letzte PHP-Änderung zurücknehmen,
2. `php -l` ausführen,
3. PHP-/Server-Log ansehen,
4. Include-Pfad prüfen,
5. Rezept-Kompatibilität prüfen.

## 31.4 Eigenes Markup zerstört anderen Text

Verdacht auf:

- zu breite Regex,
- falsche Verarbeitungsphase,
- fehlendes Escaping,
- rekursive Ersetzung,
- Namenskollision,
- fehlerhafte Callback-Rückgabe.

## 31.5 Änderung verschwindet nach Upgrade

Sehr wahrscheinlich wurde eine Core-Datei oder ein ausgelieferter Skin direkt verändert.

Änderung nach:

```text
local/
cookbook/
pub/css/
eigener Skin
```

verschieben.

---

# 32. Nützliche Suchbegriffe im Dateisystem

Wenn Shell/FTP/Git-Suche verfügbar ist:

```text
Markup(
include_once(
require_once(
$Skin
$EnableUpload
$DefaultPasswords
AuthUser
CondAuth(
$HTMLHeaderFmt
$HTMLFooterFmt
$HTMLStylesFmt
$ImgTagFmt
GUIButtons
EnableDiag
EnableStopWatch
GroupHeader
GroupFooter
```

Bei einer unbekannten Direktive wie:

```text
(:hallo:)
```

suchen nach:

```text
hallo
Markup(
```

in:

```text
local/
cookbook/
pub/skins/
```

und – sofern durchsuchbar – in Wiki-Seiten.

Nicht aus dem Namen schließen, wo eine Funktion implementiert ist.

---

# 33. Agentenfreundliche Inhaltsarchitektur

PmWiki eignet sich sehr gut als menschen- und agentenlesbarer Wissensspeicher, wenn die Struktur explizit ist.

Bevorzugen:

- klare Gruppenstruktur,
- stabile Seitennamen,
- PageTextVariables,
- `GroupHeader` / `GroupFooter`,
- zentrale PageListTemplates,
- wiederverwendbare Komponenten,
- CSS-Klassen,
- kleine dokumentierte Custom-Markups,
- Trennung von Daten und Darstellung.

## Beispiel Bilddatensatz als Wiki-Seite

```text
(:title Begegnung zwischen Nähe und Freiheit:)

(:ImageFile: BegegnungNaheFreiheit.jpg :)
(:Theme: Begegnung :)
(:Subtheme: Nähe und Distanz :)
(:Status: veröffentlicht :)
(:Source: KI-generiert :)

!! Kurzbeschreibung

Das Bild zeigt Begegnung als Balance zwischen Verbundenheit und Eigenständigkeit.

!! Interpretation

Längerer Kommentar ...

!! Verwandte Seiten

* [[Ethos.Begegnung]]
* [[Ethos.Liebe]]
* [[Ethos.Grenzen]]
```

Damit bleiben Daten für Menschen sichtbar und sind zugleich maschinell gut auswertbar.

---

# 34. Vorgehen bei einem neuen Custom-Markup

Wenn der Benutzer zum Beispiel verlangt:

```text
(:hallo:)
```

soll der Agent:

1. prüfen, ob es bereits existiert,
2. erwartete Ausgabe definieren,
3. Parameter festlegen,
4. entscheiden, ob native PmWiki-Mittel reichen,
5. PHP-Code möglichst in eigenes Cookbook-Rezept legen,
6. interne Namen mit Projektpräfix verwenden,
7. semantisches HTML erzeugen,
8. CSS getrennt halten,
9. Eingaben validieren,
10. fehlerhafte Parameter testen,
11. Syntax dokumentieren.

Beispiel Dokumentation:

```text
(:hallo:)
(:hallo typ=kurz:)
(:hallo typ=besucher:)
```

Die öffentliche Syntax darf kurz sein; interne Rule-/Funktionsnamen sollten eindeutig bleiben.

---

# 35. Git und Backups

Für agentische Wartung ist Versionskontrolle sehr empfehlenswert.

## Gut für Git

```text
local/
cookbook/
pub/css/
pub/skins/eigener-skin/
.htaccess
Dokumentation
Skill-Dateien
```

## Bewusst entscheiden

```text
wiki.d/
uploads/
```

Diese können sehr groß, dynamisch oder inhaltlich sensibel sein.

Ob sie in Git gehören, hängt vom Backup-Konzept ab.

## Nicht in Git

```text
Passwörter
API-Keys
FTP-Zugangsdaten
Datenbankpasswörter
Private Keys
Sessiondateien
```

Vor riskanten Änderungen:

- Git-Commit oder Tag,
- oder Zeitstempel-Backup.

---

# 36. Arbeitsablauf für den Agenten

## Phase A – Verstehen

1. Aufgabe genau bestimmen.
2. Betroffene Ebene identifizieren:
   - Wiki-Inhalt,
   - CSS,
   - Konfiguration,
   - Rezept,
   - Skin,
   - Upload/Auth,
   - Webserver.
3. Bestehende Implementierung suchen.
4. Abhängigkeiten feststellen.

## Phase B – Richtige Ebene wählen

Faustregeln:

| Aufgabe | Ebene |
|---|---|
| Text ändern | Wiki-Seite |
| wiederkehrenden Inhalt einfügen | Include / GroupHeader / Template |
| Darstellung ändern | CSS |
| globale PmWiki-Einstellung | `local/config.php` |
| gruppenspezifische Einstellung | `local/Group.php` |
| neue Wiki-Syntax | Cookbook / `Markup()` |
| globales HTML-Layout | Skin |
| URL-Rewriting | Webserver + PmWiki-Konfiguration |
| Rechte | PmWiki-Auth-Konfiguration |

## Phase C – Sichern

Vor Änderung:

- relevante Datei lesen,
- Backup oder Git-Zustand sichern,
- bestehende Konventionen beachten.

## Phase D – Ändern

- kleinste mögliche Änderung,
- keine unnötigen Refactorings,
- keine fremden Funktionen nebenbei verändern,
- verständliche Namen,
- Kommentare bei nicht offensichtlichem PHP.

## Phase E – Validieren

Mindestens:

- PHP-Lint bei PHP-Änderung,
- betroffene Seite laden,
- Editieren/Speichern testen, falls relevant,
- unangemeldete Ansicht testen, falls Rechte relevant,
- Desktop + Mobil bei Layout,
- Browser-Konsole bei JS,
- Nachbarseite testen.

## Phase F – Ergebnisbericht

Nicht nur schreiben:

```text
Fertig.
```

Sondern:

```text
Geändert:
- local/config.php
- pub/css/local.css

Grund:
- ...

Geprüft:
- PHP-Lint
- Desktop
- Mobil

Offenes Risiko:
- ...

Rollback:
- ...
```

---

# 37. Minimalitätsprinzip

Ein guter Agent verändert nicht mehr als nötig.

Vor einer Änderung immer fragen:

> Kann dieselbe Wirkung mit einer kleineren, nativeren und leichter rückgängig zu machenden PmWiki-Lösung erreicht werden?

Beispiel:

Schlecht:

- neues PHP-Rezept,
- eigenes JavaScript,
- neue Datenbanktabelle,

wenn ein:

```text
(:include Site.BesucherHinweis:)
```

genügt.

---

# 38. Grenzen zwischen PmWiki und Server

Nicht jedes Problem ist ein PmWiki-Problem.

Mögliche andere Ebenen:

- Apache `.htaccess`,
- Nginx,
- PHP-Konfiguration,
- Dateirechte,
- DNS,
- TLS/HTTPS,
- CDN,
- Consentmanager,
- Google-Skripte,
- Browsercache.

Vor Änderung immer feststellen, **wo der Fehler tatsächlich entsteht**.

## `.htaccess`

Vor jeder Änderung sichern.

Ein Syntaxfehler kann die gesamte Website unerreichbar machen.

---

# 39. Besonderheiten bei Security-Aufgaben

Obwohl grundsätzlich die aktuelle PmWiki-Version vorausgesetzt wird, soll der Agent bei Sicherheitsaufgaben immer zusätzlich prüfen:

- aktuelle `ReleaseNotes`,
- aktuelle `Security`-Dokumentation,
- einschlägige PITS-Einträge,
- PHP-Sicherheitsstatus,
- alte Cookbook-Rezepte,
- eigene Custom-Markups.

Denn ein aktueller Core schützt nicht automatisch vor Fehlern in lokalem oder fremdem Erweiterungscode.

---

# 40. Kompakte Syntax-Referenz

```text
SEITE
Group.PageName
{$Group} {$Name} {$FullName} {$Title}

ÜBERSCHRIFTEN
!! Überschrift
!!! Unterüberschrift
!!!! weitere Ebene

TEXT
''kursiv''
'''fett'''
'''''fett + kursiv'''''

LISTEN
* Punkt
** Unterpunkt
# nummeriert
## Unterpunkt
:Begriff:Definition

ZEILENUMBRUCH
Zeile 1\\
Zeile 2

TRENNLINIE
----

LINKS
[[Group.Page]]
[[Group.Page | Beschriftung]]
[[https://example.org/ | Beschriftung]]
[[#anker]]
[[Page#anker | Beschriftung]]
[[!Kategorie]]

ESCAPE / CODE
[= nicht interpretieren =]

[@
Code / präformatierter Text
@]

BILD / DATEI
Attach:bild.jpg
Attach:bild.jpg"Alttext"
[[Attach:dokument.pdf]]
Attach:Group./bild.jpg

STYLE
%class=box% Text %%

>>class=box<<
Block
>><<

DIV
(:div class="box":)
Block
(:divend:)

TABELLE
|| border=1
||! Kopf 1 ||! Kopf 2 ||
|| Zelle 1 || Zelle 2 ||

DIREKTIVEN
(:title Titel:)
(:description Beschreibung:)
(:include Group.Page:)
(:if condition:)
...
(:else:)
...
(:ifend:)
(:pagelist group=Group list=normal:)
(:searchbox:)
(:redirect Group.Page:)

PAGETEXTVARIABLE
:Thema:Liebe
{$:Thema}

KONFIGURATION
local/config.php
local/Group.php
local/Group.Page.php

CSS
pub/css/local.css
pub/css/Group.css
pub/css/Group.Page.css

EIGENES MARKUP
Markup('name', 'phase', '/pattern/', 'callback');

DIAGNOSE
$EnableDiag = 1;
$EnableStopWatch = 1;
?action=diag
?action=ruleset
```

---

# 41. Entscheidungsbaum für Änderungen

```text
Will ich nur Inhalt ändern?
  -> Wiki-Seite bearbeiten.

Ist derselbe Inhalt auf mehreren Seiten nötig?
  -> (:include:), GroupHeader, GroupFooter oder Template prüfen.

Ist es nur Darstellung?
  -> CSS.

Ist es eine PmWiki-Einstellung?
  -> local/config.php oder passende lokale Konfiguration.

Brauche ich neue parametrisierte Wiki-Syntax?
  -> eigenes Markup / Cookbook-Rezept.

Ändert sich die HTML-Grundstruktur?
  -> eigener Skin / Template.

Geht es um Rewrite, Header, PHP-Limits oder Dateizugriff?
  -> Webserver/PHP-Ebene prüfen.
```

---

# 42. Agenten-Doktrin

Bei jeder Arbeit an PmWiki gelten diese Regeln:

1. **Aktuelle stabile PmWiki-Version als Basis annehmen.**
2. **Core-Dateien nicht direkt verändern.**
3. **Native PmWiki-Funktionen vor eigenem PHP verwenden.**
4. **PmWiki-Markup nicht mit Markdown verwechseln.**
5. **Inhalt, CSS, Konfiguration, Rezept und Skin sauber trennen.**
6. **`wiki.d/` nicht wie gewöhnliche Markdown-Dateien bearbeiten.**
7. **Cookbook-Rezepte als externen ausführbaren Code behandeln.**
8. **Für eigenes Markup `Markup()` + Callback verwenden.**
9. **Uploads, Authentifizierung und PageVariables sicherheitsbewusst behandeln.**
10. **Änderungen klein, testbar und reversibel halten.**
11. **Vor Änderungen vorhandene lokale Lösungen suchen.**
12. **Nach Änderungen nicht nur Funktion, sondern auch Nachbarseiten testen.**
13. **Bei Security-Problemen trotz aktuellem Core lokale Erweiterungen mitprüfen.**
14. **Am Ende exakt berichten, was geändert und wie es geprüft wurde.**

---

# 43. Optional: projektspezifische Ergänzungen

Für eine konkrete Website sollte dieser allgemeine Skill durch eine zweite Datei ergänzt werden, zum Beispiel:

```text
PMWIKI_PROJECT.md
```

Darin gehören ausschließlich projektspezifische Informationen, etwa:

```text
Domain
Installationspfad
aktiver Desktop-Skin
aktiver Mobile-Skin
wichtige CSS-Dateien
eigene Markups
Cookbook-Rezepte
Gruppenstruktur
Bildverzeichnisse
Upload-Struktur
Git-Repository
Testsystem
Produktivsystem
Backup-Verfahren
Datenbanktabellen
Namenskonventionen
```

So bleibt dieser `SKILL.md` allgemein wiederverwendbar, während der Agent zugleich die konkrete Website sehr genau kennt.