# PmWiki-Seitenupdates – täglicher Leitfaden für KI-Agenten

## Zweck

Dieser Leitfaden enthält nur das Wissen, das für die tägliche Erstellung und
Änderung von PmWiki-Seiten auf KI-Ethos benötigt wird. Installation,
Serverhärtung, Skin-Entwicklung und PmWiki-Updates stehen in
`PmWiki_Neuinstallation.md` und im technischen Pflichtenheft.

## 1. Wichtigster Grundsatz: live zuerst

Bei einer bereits vorhandenen Seite ist der aktuelle Live-Quelltext die
Arbeitsgrundlage. Lokale Dateien können älter sein als manuelle Ergänzungen und
Freigaben von Hans.

Vor jeder Änderung:

1. Live-Quelltext über PmWikis Bearbeitungsweg abrufen.
2. Live-Fassung sichern oder in das Seitenmanifest aufnehmen.
3. Lokale und Live-Fassung vergleichen.
4. Gewünschte Änderung in die Live-Fassung einarbeiten.
5. Hans-Kommentare, unbekannte Ergänzungen und Review-Metadaten erhalten.
6. Direkt vor dem Speichern den Live-Hash erneut prüfen.
7. Nach dem Speichern Quelltext, Status und Darstellung kontrollieren.

Nicht still löschen:

```text
(:ReviewedBy:...:)
(:ReviewedDate:...:)
(:ReviewRequestedBy:...:)
(:ReviewRequestedDate:...:)
HH(Editor): ...
(:editorcomment:)
...
(:editorcommentend:)
```

Wenn eine lokale Fassung solche Live-Inhalte nicht enthält, darf sie nicht als
vollständiger Ersatz veröffentlicht werden.

## 2. Seitenstatus

```text
draft     neuer, noch nicht eingereichter Entwurf
review    wartet auf Hans' Prüfung
approved  von Hans freigegeben
revision  freigegebene Seite wurde inhaltlich erneut geändert
```

- Nur Hans setzt `approved`.
- Neue Seiten beginnen mit `draft` und werden bewusst zur Prüfung eingereicht.
- Bei einer inhaltlichen Änderung an `approved` gilt `approved → revision`.
- Eine bereits freigegebene Seite darf durch eine Überarbeitung nicht auf
  `draft` zurückfallen.
- `Werkstatt.Tasks` zeigt `review`, `revision` und `draft` dynamisch an.

## 3. Metadatenblock

Eine neue normale Inhaltsseite beginnt beispielsweise so:

```text
(:PageType:article:)
(:Status:draft:)
(:Responsible:Hans Hufnagel:)
(:CreatedBy:KI-Agent:)
(:CreatedDate:2026-09-29:)
(:ModifiedBy:KI-Agent:)
(:ModifiedDate:2026-09-29:)
(:title Verständlicher Seitentitel:)
(:keywords Begriff eins, Begriff zwei:)
(:description Kurze seitenspezifische Beschreibung.:)
(:linebreaks:)
```

Zusätzliche Variablen richten sich nach Seitentyp und vorhandenem Schema. Ein
Schema wird nicht stillschweigend erweitert oder umbenannt.

`(:linebreaks:)` steht nach dem vollständigen Metadatenblock. In Bereichen, in
denen Quelltextzeilen keine sichtbaren Umbrüche erzeugen sollen, kann lokal mit
`(:nolinebreaks:)` gearbeitet und danach wieder `(:linebreaks:)` aktiviert
werden.

## 4. PmWiki ist nicht Markdown

### Überschriften

```text
! Überschrift erster Ebene
!! Überschrift zweiter Ebene
!!! Überschrift dritter Ebene
```

Normale Inhaltsseiten verwenden keine eigene `!`-Überschrift als Seitentitel.
Die Skin erzeugt die einzige H1 aus `(:title ...:)`. Im Inhalt beginnt die
Gliederung normalerweise mit `!!`.

### Hervorhebung

```text
''kursiv''
'''fett'''
'''''fett und kursiv'''''
@@Monospace@@
```

### Absätze und Zeilenumbrüche

Eine Leerzeile beginnt einen neuen Absatz. Bei aktivem `(:linebreaks:)` werden
Quelltextzeilen sichtbar umgebrochen.

```text
(:nolinebreaks:)
Ein längerer Fließtext, dessen Quelltextumbrüche nicht sichtbar sein sollen.
(:linebreaks:)
```

### Listen

```text
* Aufzählung
** Unterpunkt
*** weiterer Unterpunkt

# Nummer eins
## Unterpunkt
# Nummer zwei
```

### Interne Links

```text
[[Projekt.Homepage]]
[[Projekt.Homepage|Projektübersicht]]
[[Homepage|Seite derselben Gruppe]]
```

Für stabile Projektlinks wird die Schreibweise `Gruppe.Seite` bevorzugt.

### Externe Links

```text
[[https://www.pmwiki.org/|PmWiki]]
```

Wichtige Fachbegriffe erhalten bei der ersten passenden Nennung einen
Wikipedia-Link, sofern ein geeigneter Artikel existiert:

```text
[[https://de.wikipedia.org/wiki/V%C3%B6lkerrecht|Völkerrecht]]
```

Wikipedia ersetzt bei belastbaren Aussagen keine Primär- oder Fachquelle.

### Bilder und Anhänge

```text
Attach:IMG-000492.jpg
Attach:IMG-000492.jpg"Aussagekräftiger Alternativtext"
[[Attach:datei.md|Begleitdatei öffnen oder herunterladen]]
```

Projektübliche zentrierte Bildtafel:

```text
%center%Attach:IMG-000492.jpg"Aussagekräftiger Alternativtext"%%

%center%''Kurze Bildunterschrift. [[Projekt.BilderUebersetzen|Hinweis zum Übersetzen von Bildtexten]].''%%
```

### Horizontale Linie

```text
----
```

### Präformatierter Block

```text
[@
Text oder Code, der nicht als PmWiki-Markup ausgewertet wird.
@]
```

### Einfache Tabelle

```text
|| border=1 width=100%
||! Spalte 1 ||! Spalte 2 ||
|| Inhalt A || Inhalt B ||
```

### Definitionsliste

```text
:Begriff:Erklärung
```

### Direktiven

```text
(:title Seitentitel:)
(:description Beschreibung:)
(:include AndereGruppe.AndereSeite:)
(:redirect Zielgruppe.Zielseite:)
(:if auth edit:)
Nur für Bearbeitungsberechtigte sichtbar.
(:ifend:)
```

Direktiven und PageTextVariables sehen ähnlich aus. Vor dem Erfinden neuer
Variablen zuerst das vorhandene Schema prüfen.

### WikiStyles

```text
%center%zentrierter Inhalt%%
%small%kleiner Text%%
%note%Hinweistext%%
```

Komplexe Gestaltung gehört in die zentrale CSS-Datei, nicht als umfangreiche
Inline-Formatierung auf jede Seite.

## 5. Seitenstruktur und Navigation

Eine neue Inhaltsseite benötigt:

- Link von mindestens einer Übersicht,
- Eintrag im passenden WikiTrail,
- Pfad am Seitenanfang,
- Vor-/Zurück-Navigation am Seitenende,
- Rückweg zur Bereichsübersicht.

Typisches Muster:

```text
^|[[Bilderbuch.Navigation]]|^

... Seiteninhalt ...

[[Bilderbuch.Homepage|Zur Bilderbuch-Übersicht]]

<<|[[Bilderbuch.Navigation]]|>>
```

Sidebars bleiben kurze Wegweiser. Vollständige Bestände gehören auf dynamische
Übersichtsseiten.

## 6. Quellen und zugängliche Inhalte

- Tatsachenbehauptungen möglichst unmittelbar belegen.
- Bei aktuellen, rechtlichen, medizinischen oder wissenschaftlichen Aussagen
  Primär- und Fachquellen bevorzugen.
- Unsicherheit, Gegenpositionen und Grenzen benennen.
- Textreiche Bildtafeln erhalten eine zugängliche Textfassung oder einen
  nachvollziehbaren Begleittext.
- Alt-Texte beschreiben Inhalt und Funktion des Bildes, nicht nur „Bild“ oder
  den Dateinamen.

## 7. Veröffentlichung mit Manifest

Standardwerkzeug:

```powershell
./scripts/publish-pages.ps1 -Manifest manifests/pages/BEISPIEL.json -Inspect
./scripts/publish-pages.ps1 -Manifest manifests/pages/BEISPIEL.json -Apply
```

Ein Manifest enthält mindestens:

```json
{
  "baseUrl": "https://www.ki-ethos.de",
  "authId": "ki-agent",
  "backupRoot": "Projekt/backup/ZEITPUNKT-vor-aenderung",
  "pages": [
    {
      "name": "Gruppe.Seite",
      "source": "Projekt/content/gruppe/Gruppe.Seite.pmwiki",
      "expectedLiveSha256": "AKTUELLER_LIVE_HASH",
      "summary": "Kurze nachvollziehbare Änderungszusammenfassung",
      "submitReview": false
    }
  ]
}
```

Der erwartete Hash wird unmittelbar vor der Veröffentlichung aus dem aktuellen
Live-Quelltext ermittelt. Er ist kein Ersatz für den Inhaltsvergleich.

Bei einer bestehenden Seite muss die lokale Quelldatei die zusammengeführte
Live-Fassung enthalten. `submitReview` wird nur gesetzt, wenn eine neue
`draft`-Seite tatsächlich zur Prüfung eingereicht werden soll.

## 8. Nachprüfung

Nach einer normalen Änderung mindestens prüfen:

- HTTP 200,
- genau eine H1,
- korrekter Seitentitel und Canonical,
- zum Status passende Robots-Angabe,
- kein sichtbares PmWiki-Markup,
- neue und geänderte Links,
- Bilder vollständig geladen,
- Status auf der Seite und Einordnung in `Werkstatt.Tasks`,
- visuelle Stichprobe.

Bei Änderungen an Layout, Bilddarstellung, Interaktion oder Skin zusätzlich
Desktop und Mobilansicht prüfen.

## 9. Kurzcheckliste

```text
[ ] Live-Quelltext abgerufen
[ ] Hans-Ergänzungen und Review-Metadaten erkannt
[ ] richtige Statusfolge gewählt
[ ] Änderung auf Live-Fassung aufgebaut
[ ] Navigation und Übersicht angepasst
[ ] Fachbegriffe und Quellen geprüft
[ ] Manifest mit aktuellem Hash geprüft
[ ] Backup erstellt
[ ] veröffentlicht und erneut gelesen
[ ] Darstellung, Links, Bilder und Robots geprüft
[ ] STATUS nur bei systemweiter Relevanz aktualisiert
[ ] abgeschlossene größere Änderung knapp in StatusHistory dokumentiert
```

## Offizielle Referenzen

- https://www.pmwiki.org/wiki/PmWiki/BasicEditing
- 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/PageTextVariables
- https://www.pmwiki.org/wiki/PmWiki/WikiTrails
- https://www.pmwiki.org/wiki/PmWiki/PageHistory