patrickschiller · Oct 22, 2026 · Oct 22, 2026
diff --git a/.env.prod.example b/.env.prod.example
@@ -3,7 +3,7 @@
 
 # Pin deployments to an immutable OpenClockwork release. Do not use `latest`
 # for production upgrades.
-OPENCLOCKWORK_VERSION=2.1.0
+OPENCLOCKWORK_VERSION=2.2.0
 # Keep these names unchanged across upgrades.
 OPENCLOCKWORK_DB_VOLUME=openclockwork-db-data-prod
 OPENCLOCKWORK_ATTACHMENTS_VOLUME=openclockwork-attachments-prod

diff --git a/FEATURES.md b/FEATURES.md
@@ -1,12 +1,14 @@
 # OpenClockwork Features
 
-OpenClockwork 2.1.0 provides **Solo** personal work tracking and **Team** time and
+OpenClockwork 2.2.0 provides **Solo** personal work tracking and **Team** time and
 attendance in one responsive, self-hosted application. Both keep deployment,
 data, and configuration under the operator's control, with German and English UI.
 
-Version 2.1.0 adds direct PIN identification and explicit time booking at Team
-tablets, HR PIN administration, and an authentication audit. It retains the
-personnel-data access restrictions introduced in 2.0.1. RFID is planned separately.
+Version 2.2.0 adds HR working-time PDF exports for one, selected, or all employees,
+including inactive employees with historical bookings. It retains the PIN tablet
+terminals and audit introduced in 2.1.0 and personnel-data access restrictions
+introduced in 2.0.1. RFID is planned separately. See the
+[German legal context and export limitations](docs/WORKING_TIME_EXPORTS.de.md).
 
 This page describes implemented capabilities, not a guarantee that every rule,
 device, or external browser handoff has been certified. See
@@ -87,7 +89,7 @@ contains effective work or time off, the accounting mode starts on the next
 working-timezone calendar date. See [the mode guide](docs/OPERATING_MODES.md).
 
 Solo customer management and personal billable reports are not Team screens in
-2.1.0. Preserving records across a switch does not make every mode-specific
+2.2.0. Preserving records across a switch does not make every mode-specific
 workflow available in both modes.
 
 ## Mobile PWA
@@ -227,7 +229,7 @@ Employee submits
 | Absence administration  | Record and review sickness, training, and flextime entries                                             |
 | Approval operations     | Manager/HR inboxes, bulk actions, correction loops, and workflow history                               |
 | Terminal administration | Configure, activate, pair, monitor, revoke, re-pair, deactivate, or permanently delete tablet kiosks   |
-| Working-time reports    | HR-only start, end, break, gross, net, approval, and CSV reporting, with optional clocking locations   |
+| Working-time reports    | HR-only CSV/PDF reporting for one, selected, or all employees; optional locations in table/CSV only    |
 
 Production starts with an empty database. The interactive
 `prisma/create-admin.ts` bootstrap offers Solo or Team and creates exactly one
@@ -252,9 +254,17 @@ bookings, and customer-facing activity reports in one administrative workflow.
 - Detailed evaluations filtered by period, employee, project, and order
 - Customer-facing activity report and CSV export
 - Project-independent HR working-time report for all closed, non-rejected entries
+- Direct PDF download for individual employees or a bulk selection, with separate
+  employee sections, personnel numbers, explicit timezone, full timestamps,
+  booking-day/period totals, approval state, and warnings for open timers
+- Historical inactive employees remain selectable for working-time exports
 - Opt-in clock-in and clock-out locations in the report table and CSV export,
   combining durable terminal labels with available GPS coordinates and accuracy
 
+PDFs exclude locations, project details, and private notes. Break deductions use
+the stored policy and do not establish when actual rest breaks were taken.
+See [German export requirements and limitations](docs/WORKING_TIME_EXPORTS.de.md).
+
 Exports contain employee names and working-time data and must be handled as
 personal data under the organisation's access and retention policies. Exact
 clocking locations are excluded by default and require an explicit HR action;

diff --git a/NOTICE b/NOTICE
@@ -46,3 +46,8 @@ superseded by this NOTICE. A consolidated list of runtime and build-time
 dependencies is generated from the package manifests of each application
 in the workspace; consult the lockfiles and the upstream projects for the
 authoritative license terms.
+
+Working-time PDF reports embed Noto Sans Regular and Bold, distributed under
+the SIL Open Font License, Version 1.1. Copyright 2022 The Noto Project Authors
+(https://github.com/notofonts/latin-greek-cyrillic). The font files and full
+license are included in apps/api/src/assets/fonts/.
diff --git a/README.md b/README.md
@@ -14,16 +14,18 @@
   <a href="https://github.com/patrickschiller/openclockwork/releases/latest"><img src="https://img.shields.io/github/v/release/patrickschiller/openclockwork" alt="Latest GitHub release"></a>
 </p>
 
-OpenClockwork 2.1.0 provides two operating modes in one open-source application.
+OpenClockwork 2.2.0 provides two operating modes in one open-source application.
 **Solo** helps an independent professional track personal work, organise customer
 projects, and produce timesheets without inventing an HR department. **Team**
 supports employee attendance, work schedules, leave, approvals, and tablet
 terminals. Both use the same self-hosted PostgreSQL, API, and responsive PWA.
 
-**New in 2.1.0:** Team employees can identify themselves directly at a paired
-tablet with their personal number and a separate terminal PIN, then explicitly
-confirm clock-in or clock-out. HR manages PINs, terminal authentication methods,
-and the authentication audit. The access-control fixes from 2.0.1 are retained.
+**New in 2.2.0:** HR can download working-time PDFs alongside CSV for one,
+selected, or all employees, including inactive employees with historical
+bookings. Reports show full timestamps, break deductions, net work, status,
+and totals, with a separate section per person. Read the
+[German legal context and export limitations](docs/WORKING_TIME_EXPORTS.de.md).
+PIN tablet terminals from 2.1.0 and the access-control fixes from 2.0.1 are retained.
 
 The interface is available in German and English on phones, tablets, and
 desktops. Language is independent of working-time rules: targets, breaks,
@@ -33,7 +35,7 @@ country. No proprietary time-clock hardware or hosted subscription is required.
 **Existing installations remain in Team mode after an upgrade.** A mode change
 is a separate, authenticated administrator action with a preview and safety
 checks. Invoice creation, monetary billing, and CAUR coding-agent usage import
-are not included in 2.1.0; see the [roadmap](ROADMAP.md).
+are not included in 2.2.0; see the [roadmap](ROADMAP.md).
 
 ## Choose your mode
 
@@ -89,7 +91,11 @@ Solo customer-management and billable-timesheet UI.
   bulk actions, and workflow history.
 - **Projects and reporting.** Assign employees, structure projects by service
   order, compare PLAN and IST hours, edit booking targets, split entries, and
-  export customer or working-time reports with optional clock-in/out locations.
+  export customer or working-time reports as CSV. HR can download working-time
+  PDFs for one, selected, or all employees, with a separate section per person.
+  Clock-in/out locations are optional in HR tables and CSV and excluded from PDFs.
+  See the [German working-time export guidance](docs/WORKING_TIME_EXPORTS.de.md)
+  for the legal context and the limits of automatic break deductions.
 - **Self-hosted and API-first.** PostgreSQL, NestJS, React, OpenAPI, Socket.IO,
   Docker, and an Azure reference deployment—without SaaS lock-in.
 - **Localised interface.** German and English translations, browser-aware dates,
@@ -190,8 +196,8 @@ and read [UPGRADING.md](UPGRADING.md) before changing an existing installation.
 
 The PWA is online-first. A running timer remains server state while a device is
 offline; new writes require server confirmation and are not queued as offline
-bookings. CSV export starts a browser download, and print/PDF uses the browser's
-print dialog. Verify both handoffs in your chosen browser or installed PWA;
+bookings. CSV and HR working-time PDF exports start browser downloads; Solo
+print/PDF uses the browser's print dialog. Verify these handoffs in your chosen browser or installed PWA;
 embedded browsers may handle downloads and printing differently.
 
 ## Tech stack
@@ -335,7 +341,7 @@ repository and enter its directory:
 ```bash
 git clone https://github.com/patrickschiller/openclockwork.git
 cd openclockwork
-git switch --detach v2.1.0
+git switch --detach v2.2.0
 cp .env.prod.example .env.prod
 ```
 
@@ -366,7 +372,7 @@ openssl rand -hex 32
 
 Open `.env.prod` in an editor and replace every `change-me` value:
 
-- Set `OPENCLOCKWORK_VERSION=2.1.0` for this release. Use the same explicit
+- Set `OPENCLOCKWORK_VERSION=2.2.0` for this release. Use the same explicit
   version for the API and web images; never deploy `latest`.
 - Put the first command's output into `POSTGRES_PASSWORD` and replace
   `change-me-database-password` inside `DATABASE_URL` with that exact same

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
@@ -1,3 +1,83 @@
+# OpenClockwork v2.2.0
+
+## Working-time PDFs for HR
+
+- HR can download a working-time PDF alongside the existing CSV export for one
+  employee, several selected employees, or all employees in the chosen period.
+  Historical records of inactive employees remain selectable. Each employee
+  starts on a new page in a combined document.
+- Reports include the employee's name and personnel number, reporting period,
+  export timestamp, installation timezone, full start/end dates and UTC offsets,
+  gross time, rule-based break deductions, net time, booking status and totals.
+  Elapsed time retains second precision in the report. Stored break-rule
+  snapshots determine deductions; changing a schedule does not rewrite history.
+- Pending completed bookings are labelled provisional. Open bookings are
+  flagged and excluded from totals; rejected and cancelled entries are omitted.
+  Overnight work belongs to its booking's start day, so daily subtotals are
+  booking-day totals rather than calendar-day compliance checks. Full dates and
+  UTC offsets make overnight work and daylight-saving transitions traceable.
+- PDF downloads enforce HR authorization and organization scope. Location data,
+  free-text notes and project details are excluded. Combined PDFs contain
+  personal data for several employees: restrict access and share them only with
+  the intended recipients.
+- Requested in [Discussion #37](https://github.com/patrickschiller/openclockwork/discussions/37).
+  A [two-page example PDF](https://github.com/user-attachments/files/33845433/openclockwork-arbeitszeitnachweis-beispiel.pdf)
+  uses synthetic data only. Read the
+  [German working-time export guide](https://github.com/patrickschiller/openclockwork/blob/v2.2.0/docs/WORKING_TIME_EXPORTS.de.md)
+  for selection, calculations and limitations.
+
+## Legal context in Germany
+
+- Employers must generally record the beginning, end and duration of daily
+  working time. German law does not prescribe a universal PDF layout or a
+  general PDF-export requirement for these records. See the
+  [BMAS working-time recording FAQ](https://www.bmas.de/DE/Arbeit/Arbeitsrecht/Arbeitnehmerrechte/Regelungen-zur-Arbeitszeit/Fragen-und-Antworten/faq-arbeitszeiterfassung.html)
+  and the [BAG decision of 13 September 2022, 1 ABR 22/21](https://www.bundesarbeitsgericht.de/entscheidung/1-abr-22-21/).
+- [Section 16(2) ArbZG](https://www.gesetze-im-internet.de/arbzg/__16.html)
+  requires the records specified there, including work beyond the working-day
+  limit under section 3 sentence 1, to be retained for at least two years.
+  [Section 17(1) MiLoG](https://www.gesetze-im-internet.de/milog/__17.html)
+  separately requires covered employers, notably for specified marginal
+  employment and sectors, to record beginning, end and duration by the end of
+  the seventh following calendar day and retain the records for at least two
+  years. Its scope and exemptions matter: this seven-day deadline is not a
+  general deadline for every employment relationship.
+- Automatic break deductions do not prove that breaks were actually taken.
+  The PDF states this limitation; it does not record actual break intervals.
+  Employers remain responsible for accurate, complete records, actual breaks,
+  lawful processing, access and retention. The export is a documentation aid,
+  not a certification of legal compliance or a complete payroll statement.
+  For minimum-wage documentation,
+  [BMAS confirms that signatures are not required](https://www.bmas.de/DE/Arbeit/Arbeitsrecht/Mindestlohn/Dokumentationspflicht/dokumentationspflicht.html).
+  The cited rules prescribe neither PDF/A nor export certification;
+  sector-specific rules and agreements may apply.
+  Legal sources were reviewed on 22 October 2026.
+
+## Upgrade and compatibility
+
+- Upgrading from 2.1.0 adds no database migrations and requires no seed, reset,
+  new secret or change to the working timezone. Preserve existing data,
+  attachment volumes, configuration and historical migrations. When skipping
+  older releases, follow their intervening requirements, including the 2.1.0
+  PIN migration. See the
+  [upgrade guide](https://github.com/patrickschiller/openclockwork/blob/v2.2.0/UPGRADING.md).
+- Deploy matching API and web images. If deployed separately, update the API
+  first, wait for `/api/health` to report `2.2.0`, then deploy the web image.
+  Reopen existing browser/PWA tabs to load the new export controls. The API
+  contract and generated web client include the PDF endpoint; existing CSV
+  exports, working-time accounts, approvals and break policies remain supported.
+- The PIN/QR functionality introduced in 2.1.0 and personnel-data access controls
+  introduced in 2.0.1 are retained. PIN deployment still requires its independent
+  secrets, restricted runtime role and operator-managed audit retention.
+
+## Docker images
+
+- `ghcr.io/patrickschiller/openclockwork-api:2.2.0`
+- `ghcr.io/patrickschiller/openclockwork-web:2.2.0`
+
+The release workflow also updates each image's `latest` tag. Pin `2.2.0` or a
+verified digest for production and use the same release for both images.
+
 # OpenClockwork v2.1.0
 
 ## PIN tablet terminals

diff --git a/RELEASING.md b/RELEASING.md
@@ -25,15 +25,18 @@ public-contract impact. Use matching metadata in five places:
 5. Run `RELEASE_TAG=vMAJOR.MINOR.PATCH pnpm release:verify-tag` and the full CI
    suite.
 
-For 2.1.0, include the additive PIN migration and matching QR/PIN API contract,
-upgrade instructions, role-setup tools and audit verification tools. Retain the
-2.0.1 personnel-data access fixes. Verify QR defaults and existing records across
-the upgrade, PIN and credential-access tests, concurrent booking/revocation,
-audit integrity and the separate runtime-role Docker path. Record the accepted
-local user check without claiming an unperformed target-device or external
-archive test. Production PIN activation still requires the operator's protected
-archive and retention configuration; publishing the source and images does not
-provision or certify that deployment.
+For 2.2.0, include the individual and bulk HR working-time PDF export, matching
+OpenAPI contract and client, legal context and upgrade instructions. Verify HR
+authorization and organization scope, selected/all employees including inactive
+employees with historical records, pending/open bookings, historical break-rule
+snapshots, second precision, overnight work and daylight-saving transitions.
+Render representative PDFs and inspect pagination, employee boundaries, totals
+and German/English text. Use synthetic data for public examples and attachments.
+There are no new migrations relative to 2.1.0; retain the PIN migration and all
+earlier security fixes. State the scoped German retention and recording rules
+without presenting the PDF as a legal certification. Production PIN activation
+still requires the operator's protected archive and retention configuration;
+publishing the source and images does not provision or certify that deployment.
 
 ## Publish
 
@@ -43,8 +46,8 @@ annotated tag on the exact merge commit and push it:
 ```bash
 git switch main
 git pull --ff-only
-git tag -a v2.1.0 -m "OpenClockwork v2.1.0"
-git push origin v2.1.0
+git tag -a v2.2.0 -m "OpenClockwork v2.2.0"
+git push origin v2.2.0
 ```
 
 The release workflow verifies the tag and notes, runs Nx and API end-to-end
@@ -60,8 +63,8 @@ pulled anonymously by self-hosted installations.
 ## Verify the published release
 
 ```bash
-docker pull ghcr.io/patrickschiller/openclockwork-api:2.1.0
-docker pull ghcr.io/patrickschiller/openclockwork-web:2.1.0
+docker pull ghcr.io/patrickschiller/openclockwork-api:2.2.0
+docker pull ghcr.io/patrickschiller/openclockwork-web:2.2.0
 ```
 
 Confirm that the GitHub Release is marked latest, contains the curated upgrade

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,9 +1,10 @@
 # OpenClockwork Roadmap
 
 OpenClockwork is a public, Apache-2.0 self-hosted application for personal work
-and Team time and attendance. Version **2.1.0** adds PIN tablet terminals to
-Team, building on the Solo/Team workflows from 2.0 and the access-control fixes
-from 2.0.1. Customer invoicing and coding-agent usage accounting remain
+and Team time and attendance. Version **2.2.0** adds HR working-time PDF exports
+for one or several employees, building on PIN tablet terminals from 2.1.0,
+Solo/Team workflows from 2.0 and the access-control fixes from 2.0.1.
+Customer invoicing and coding-agent usage accounting remain
 future work; a billable time flag does not mean those features already exist.
 
 This roadmap expresses priorities and intended scope, not release dates or
@@ -15,7 +16,7 @@ boundaries, and [README.md](README.md) for release installation.
 
 | Stage | Scope                                               | Status / dependency                     |
 | ----- | --------------------------------------------------- | --------------------------------------- |
-| 1     | Country-neutral configuration and defaults          | Included in 1.4.0; retained in 2.1.0    |
+| 1     | Country-neutral configuration and defaults          | Included in 1.4.0; retained in 2.2.0    |
 | 2     | Complete personal Solo workflow alongside Team      | Included in 2.0.0                       |
 | 3     | QR/PIN tablet terminals and HR authentication audit | Included in 2.1.0; Team only            |
 | 4     | Optional RFID terminal extension                    | Planned separately after PIN acceptance |
@@ -178,7 +179,7 @@ customer invoice from tracked work and follow it through payment or correction.
 [CAUR — Coding Agent Usage Record](https://github.com/patrickschiller/caur)
 defines a vendor-neutral usage record for a completed or interrupted coding-agent
 run. It is a separate specification project, not an invoice format or pricing
-catalogue, and is not imported by OpenClockwork 2.1.0. A future integration should
+catalogue, and is not imported by OpenClockwork 2.2.0. A future integration should
 consume explicitly supported schema versions and provide attribution, review,
 and billing around them. Its design should follow the
 [CAUR specification](https://github.com/patrickschiller/caur/blob/main/SPEC.md)