Wegwichtel/docs/agents/AGENTS.md

# Agent-Anweisungen für Wegwichtel

Diese Datei vor jeder Änderung am Projekt lesen. Sie gilt für das gesamte
Repository. Da sie unter `docs/agents/` liegt, muss ihr Pfad in Übergaben und
Agent-Aufträgen ausdrücklich genannt werden; eine automatische Suche nach
einer `AGENTS.md` im Projektverzeichnis findet sie dort nicht.

## Ablage der Dokumentation

- Markdown mit Agent-Anweisungen, Entwicklungsvorgaben und offenen
  Entwicklungsaufgaben ausschließlich unter `docs/agents/` ablegen.
- Markdown für Anwender und Betrieb ausschließlich direkt unter `docs/` ablegen.
- Keine eigenen Markdown-Dateien im Projektverzeichnis oder neben Werkzeugen
  und ausgelieferten Bibliotheken anlegen. Links nach Umzügen aktualisieren.
- Bei Übergaben die relevanten Markdown-Dateien im Repository mit ihren
  aktuellen Pfaden ausdrücklich nennen, insbesondere diese Datei sowie
  `docs/agents/I18N.md`, `docs/agents/GPX-Aufzeichnung.md` und
  `docs/agents/TODO-MODERATION.md`.

# Wegwichtel: Sprache der App

GPX-Änderungen berücksichtigen `GPX-Aufzeichnung.md`: Stationen sind `wpt`,
Aufzeichnungen sind `trkpt`, der Server normalisiert zu `rtept`. Fehlende
Koordinaten bleiben gespeichert und bearbeitbar; keine Ersatzkoordinaten erfinden.
Die GPX-Dateien sind die einzige Quelle der Routenpunkte und berechneten
Routenwerte. SQLite speichert davon nur Min-/Max-Grenzen für die Näheresuche.
Schemaänderungen immer auch mit der Startprüfung an einer vorhandenen,
frisch erzeugten Testdatenbank prüfen.

Diese Vorgabe des Nutzers gilt für alle künftigen Änderungen an der Oberfläche.
Die App richtet sich an Grundschulkinder und Menschen ohne technische Vorkenntnisse.

- Schreibe kurze, verständliche Sätze. Sprich die Nutzer mit „du“ an.
- Erkläre, was eine Aktion bewirkt und was als Nächstes zu tun ist.
- Verwende durchgängig „Strecke“, „Station“, „Meine Entwürfe“ und „für unterwegs speichern“.
- Technische Begriffe wie GPX, JSON, Cache, API, OPFS, IndexedDB, Local Storage,
  Server, Token oder interne Feldnamen gehören nicht in Bedienungstexte,
  Hilfe, Statusmeldungen, Dateiauswahl-Beschreibungen oder vorgelesene Beschriftungen.
- Bezeichne einen Wegexport als „Weg als Datei herunterladen“. Erkläre bei Bedarf,
  dass die Datei für eine andere Wander-App gedacht ist und keine Bilder oder Ton enthält.
- Verwende „Bilder und Tonaufnahmen“ statt „Medien“, „Zur Prüfung senden“ statt „Upload“
  und „auf diesem Gerät“ statt „lokal im Browser“.
- Fehlermeldungen nennen das Problem und einen verständlichen nächsten Schritt.
  Zeige keine rohen Fehler aus dem Betriebssystem, Netzwerkantworten oder Dateipfade.
- Vereinfache auch Hilfen zu Daten und Speicher. Behalte wichtige Angaben zu
  Löschung, Erlaubnissen, Grenzen und Speicher-Schätzungen bei. Mache keine
  Zusicherungen, die die App nicht einhalten kann.
- Rechtliche Texte dürfen notwendige Rechtsbegriffe behalten. Erkläre sie einfach;
  ändere dabei nicht die Bedeutung, Verantwortlichen oder Kontaktdaten.
- Fachliche Details für Entwicklung und Betrieb gehören in Projekt-Dokumentation
  und Code-Kommentare. Code-Bezeichner, Dateiformate und Schnittstellen bleiben fachlich präzise.
- Prüfe neue Texte und angepasste Text-Erwartungen in den vorhandenen Tests.

## Kontaktadresse

Die eingerichtete Kontaktadresse für Wegwichtel ist `info@wegwichtel.de`.
Sie gilt für App-Kontakt, technische Fragen, Rechtefragen, Datenschutzanfragen,
Widerruf und Entfernung von Aufnahmen. In Rechtstexten statisch einsetzen.
Schul- und Behördenadressen bleiben die Kontakte der jeweiligen Stellen.

## Texte und Übersetzungen

- Alle eigenen Bedienungstexte liegen zentral in der Klasse `WegwichtelTexts`
  in `public/js/texts-de.js`. Keine neuen sichtbaren Texte direkt in HTML oder
  Funktionscode schreiben.
- Ausnahme: Impressum, Datenschutzerklärung und Nutzungsvereinbarung bleiben ausschließlich statisch
  auf Deutsch in `public/index.html` und tragen `lang="de"`. Ihre Texte und
  Kontaktangaben gehören nicht in Sprachdateien und erhalten keine i18n-Attribute.
  Auch ihre Dialogüberschriften bleiben beim Sprachwechsel auf Deutsch.
- Das HTML enthält daraus erzeugte deutsche Standardtexte, damit Beschriftungen
  vor dem Laden der Skripte vorhanden sind. Nach Änderungen am Textkatalog
  `node scripts/localize-html.js` ausführen und `public/index.html` mit ablegen.
  Diese erzeugten Texte nicht von Hand ändern; die i18n-Attribute bleiben erhalten.
- JavaScript bezieht Texte über `Wegwichtel.I18n.t(textKey, variables)`.
  HTML verwendet `data-i18n` bzw. `data-i18n-aria-label`, `data-i18n-title`,
  `data-i18n-placeholder` und `data-i18n-alt`.
- Zahlen und Namen sind Platzhalter; ganze Sätze übersetzen, keine Sätze aus
  deutschen Wortteilen zusammensetzen. Für Mengen Einzahl und Mehrzahl verwenden.
- Nutzerinhalte wie Streckennamen, Beschreibungen und Aufnahmen nicht automatisch
  übersetzen oder verändern. Interne Fehlerdiagnosen dürfen technisch bleiben;
  die sichtbare Meldung muss verständlich sein.
- Sprachdateien heißen `public/js/texts-<Sprache>.js` und verwenden dieselbe
  generische Klasse `WegwichtelTexts`. Sie registrieren sich in `TextCatalogs`.
  Die App lädt Deutsch und Englisch und wählt anhand von `navigator.languages`
  bzw. `navigator.language`. Fehlende Übersetzungen fallen auf den ersten
  geladenen Katalog zurück (in der App Deutsch).
- Verwende kurze, stabile englische Funktionsschlüssel wie `app.no-route` oder
  `bootstrap-loader.error.start-error`. Schlüssel nicht aus dem deutschen Text
  ableiten. Startmeldungen in `bootstrap-loader.steps` nach Schritt gruppieren.
- Deutsch und Englisch enthalten dieselben Schlüssel, Platzhalter und Pluralformen.
  Texte in beiden Sprachen einfach und sinngemäß schreiben. Sprachwechsel aktualisieren feste Beschriftungen;
  bereits erzeugte dynamische Ansichten bei Bedarf neu rendern.

## Ausrichtung von Bedienelementen

Button-Gruppen in Strecken- und Stationslisten am rechten Kartenrand ausrichten.
Icon-Buttons bekommen einheitliche Breiten, Höhen und Abstände, auch wenn sie
inaktiv sind. Titel dürfen umbrechen und verändern die Button-Spalten nicht.
Die Bedienflächen bleiben mindestens 44 × 44 Pixel groß.

## Lokale Bilder und Tonaufnahmen erst bei Bedarf laden

Beim Öffnen oder Speichern einer Strecke und beim Umordnen von Stationen
nur Metadaten lesen. Keine Dateien aller Stationen hydratisieren.
Dateireferenzen bzw. IndexedDB-Dateien erst beim Bearbeiten oder Aufrufen
der jeweiligen Station lesen. Der Upload liest die benötigten Dateien direkt.
Temporäre Blob-URLs beim Verlassen der Ansicht freigeben; verspätete
Ladeergebnisse dürfen eine andere Station oder geschlossene Ansicht nicht ändern.

## Stationsorte in der Routenberechnung

Beim Hochladen und erneuten Berechnen sowohl aufgezeichnete Wegpositionen als
auch `wpt` mit gültigen Koordinaten berücksichtigen. Stationsanker dürfen nicht
durch die GPS-Clusterbildung wegfallen. Nur gültige Koordinaten einbeziehen;
Stationen ohne Standort bleiben bearbeitbar. Berechnete Stationsanker im GPX
kennzeichnen und bei Verschieben/Löschen ersetzen, statt veraltete Orte zu behalten.
Rätsel-Stationen sind für später in `docs/agents/TODO-RAETSEL-STATIONEN.md` vorgemerkt.