From b11162d5f1c97d386e90a662cceb822b7bc8dc5a Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Wed, 9 Sep 2026 02:04:24 +0200
Subject: [PATCH] fix(ui): align contextual documentation with headings

Verified with the coordinated workspace changes by devkit full run
2026-09-08T225814-186389-0000-3e3ed7cd (all seven phases passed).
This shared UI pass does not mark the individual module reviews complete.
---
 src/govoplan_tickets/backend/manifest.py   |  7 ++++++-
 webui/src/features/tickets/TicketsPage.tsx |  6 ++++--
 webui/src/i18n/generatedTranslations.ts    | 12 ++++++++++++
 webui/src/module.ts                        |  2 ++
 webui/src/styles/tickets.css               |  2 +-
 5 files changed, 25 insertions(+), 4 deletions(-)
 create mode 100755 webui/src/i18n/generatedTranslations.ts

diff --git a/src/govoplan_tickets/backend/manifest.py b/src/govoplan_tickets/backend/manifest.py
index 61d10b2..186ff6a 100644
--- a/src/govoplan_tickets/backend/manifest.py
+++ b/src/govoplan_tickets/backend/manifest.py
@@ -207,6 +207,8 @@ DOCUMENTATION = (
         title="Tickets module boundary",
         summary="Operational requests, incidents, problems, reports, queue work, service targets, and auditable resolution.",
         body=(
+            "Documentation books sit immediately beside the visible heading or contextual label for "
+            "Tickets, not among operational action buttons. Field help remains beside its label. "
             "Tickets owns the operational service record and its lifecycle. Cases remains authoritative for formal procedures; "
             "Helpdesk may contribute routing and service-target policy without creating a second ticket store. Attachments and "
             "related work are typed references. Soft deletion removes a ticket from ordinary work and Search while retaining its immutable history."
@@ -218,7 +220,10 @@ DOCUMENTATION = (
             "de": {
                 "title": "Modulgrenze von Tickets",
                 "summary": "Operative Anfragen, Störungen, Probleme, Meldungen, Warteschlangenarbeit, Serviceziele und nachvollziehbare Lösungen.",
-                "body": "Tickets verantwortet den operativen Servicevorgang und seinen Lebenszyklus. Cases bleibt für förmliche Verfahren maßgeblich; Helpdesk kann Weiterleitung und Serviceziele beisteuern, ohne einen zweiten Ticketspeicher anzulegen. Anhänge und verbundene Arbeit sind typisierte Verweise. Eine weiche Löschung entfernt ein Ticket aus der normalen Arbeit und Suche, erhält aber die unveränderliche Historie.",
+                "body": "Dokumentationsbücher stehen unmittelbar neben der sichtbaren Überschrift oder "
+                "Kontextbezeichnung für Tickets, nicht zwischen ausführbaren Aktionsschaltflächen. Feldhilfe "
+                "bleibt neben der Feldbezeichnung. "
+                "Tickets verantwortet den operativen Servicevorgang und seinen Lebenszyklus. Cases bleibt für förmliche Verfahren maßgeblich; Helpdesk kann Weiterleitung und Serviceziele beisteuern, ohne einen zweiten Ticketspeicher anzulegen. Anhänge und verbundene Arbeit sind typisierte Verweise. Eine weiche Löschung entfernt ein Ticket aus der normalen Arbeit und Suche, erhält aber die unveränderliche Historie.",
             }
         },
         related_modules=OPTIONAL_DEPENDENCIES,
diff --git a/webui/src/features/tickets/TicketsPage.tsx b/webui/src/features/tickets/TicketsPage.tsx
index cbdb11e..b36f5de 100644
--- a/webui/src/features/tickets/TicketsPage.tsx
+++ b/webui/src/features/tickets/TicketsPage.tsx
@@ -338,7 +338,9 @@ export default function TicketsPage({ settings, auth }: PlatformRouteContext) {
             </label>
             <span className="tickets-count">{total} tickets</span>
           </>}
-          helpAction={<DocumentationHelpLink reference={{ topicId: "tickets.operational-workflow", documentationType: "user" }} label="Open Tickets documentation" />}
+          title="Tickets"
+          titleLevel={1}
+          titleHelp={<DocumentationHelpLink reference={{ topicId: "tickets.operational-workflow", documentationType: "user" }} label="Open Tickets documentation" />}
           createAction={canReport ?
             <Button type="button" variant="primary" onClick={() => {
               setEditing(null);
@@ -450,7 +452,7 @@ function TicketDetail({ record, availability, history, canTriage, canAssign, can
       <header className="ticket-detail-header">
         <div>
           <span className="ticket-eyebrow">{record.ticket_number} · {humanize(record.ticket_type)}</span>
-          <h1>{record.title}</h1>
+          <h2>{record.title}</h2>
         </div>
         <div className="ticket-detail-badges">
           <StatusBadge status={priorityTone(record.priority)} label={humanize(record.priority)} />
diff --git a/webui/src/i18n/generatedTranslations.ts b/webui/src/i18n/generatedTranslations.ts
new file mode 100755
index 0000000..2b51094
--- /dev/null
+++ b/webui/src/i18n/generatedTranslations.ts
@@ -0,0 +1,12 @@
+import type { PlatformTranslations } from "@govoplan/core-webui";
+
+/** Module-owned translations for contextual headings. */
+export const generatedTranslations: PlatformTranslations = {
+  en: {
+    "Tickets": "Tickets",
+  },
+  de: {
+    "Tickets": "Tickets",
+  },
+};
+
diff --git a/webui/src/module.ts b/webui/src/module.ts
index e40cef1..3055044 100644
--- a/webui/src/module.ts
+++ b/webui/src/module.ts
@@ -1,11 +1,13 @@
 import { createElement, lazy } from "react";
 import type { PlatformWebModule } from "@govoplan/core-webui";
+import { generatedTranslations } from "./i18n/generatedTranslations";
 import "./styles/tickets.css";
 
 
 const TicketsPage = lazy(() => import("./features/tickets/TicketsPage"));
 
 export const ticketsModule: PlatformWebModule = {
+  translations: generatedTranslations,
   id: "tickets",
   label: "Tickets",
   version: "0.1.20",
diff --git a/webui/src/styles/tickets.css b/webui/src/styles/tickets.css
index 335de68..32cabdf 100644
--- a/webui/src/styles/tickets.css
+++ b/webui/src/styles/tickets.css
@@ -74,7 +74,7 @@
   border-bottom: 1px solid var(--border);
 }
 
-.ticket-detail-header h1 {
+.ticket-detail-header h2 {
   margin: 4px 0 0;
   font-size: 1.4rem;
   letter-spacing: 0;