chore(docs): proofread README and docs prose for grammar and style

nolte · claude · nolte · commit 5de65f70c8d3 · 2026-06-07T23:41:14.000+02:00
Fix broken grammar and inconsistent capitalisation in the README,
unify the German address form to the dominant impersonal infinitive,
spell out abbreviations on first use, and align em-dash spacing and a
heading to the established project style. README is Vale-clean and all
include-markdown markers are preserved.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ Centralised reusable [GitHub Actions workflows](https://docs.github.com/en/actio
 | ```reusable-ansible-galaxy-push.yaml```      | Publish an Ansible role to [Ansible Galaxy](https://galaxy.ansible.com/) via [robertdebock/galaxy-action](https://github.com/robertdebock/galaxy-action).        |
 | ```reusable-ansible-molecule.yaml```         | Run a [Molecule](https://molecule.readthedocs.io/) test scenario via [gofrolist/molecule-action](https://github.com/gofrolist/molecule-action).                  |
 | ```reusable-automerge.yaml```                | Auto-merge pull requests via [pascalgn/automerge-action](https://github.com/pascalgn/automerge-action).                                                          |
-| ```reusable-chain-bench.yaml```              | Run the supply-chain CIS benchmark via [aquasecurity/chain-bench-action](https://github.com/aquasecurity/chain-bench-action).                                    |
+| ```reusable-chain-bench.yaml```              | Run the supply-chain CIS (Center for Internet Security) benchmark via [aquasecurity/chain-bench-action](https://github.com/aquasecurity/chain-bench-action).     |
 | ```reusable-dependency-review.yaml```        | Gate pull requests against vulnerable or licence-incompatible dependency changes via [actions/dependency-review-action](https://github.com/actions/dependency-review-action). |
 | ```reusable-docker-lint-build.yaml```        | Run [hadolint](https://github.com/hadolint/hadolint-action) on a Dockerfile and a buildx dry-build (no push) for fast PR feedback.                              |
 | ```reusable-docker-publish.yaml```           | Build a multi-arch container image with [docker/build-push-action](https://github.com/docker/build-push-action) and push it to a configurable OCI registry.      |
@@ -28,29 +28,29 @@ Centralised reusable [GitHub Actions workflows](https://docs.github.com/en/actio
 | ```reusable-spelling-vale.yaml```            | Lint Markdown prose via [errata-ai/vale-action](https://github.com/errata-ai/vale-action) with inline reviewdog annotations on pull requests.                    |
 | ```reusable-sphinx.yaml```                   | Build and publish a [Sphinx](https://www.sphinx-doc.org/en/master) documentation site to [GitHub Pages](https://pages.github.com/).                              |
 | ```reusable-stale.yaml```                    | Mark and close stale issues and pull requests via [actions/stale](https://github.com/actions/stale).                                                             |
-| ```reusable-trivy.yaml```                    | Scan the GitRepo by using [aquasecurity/trivy-action](https://github.com/aquasecurity/trivy-action).                                                             |
-| ```reusable-tf-lint.yaml```                  | Use [terraform-linters/setup-tflint](https://github.com/terraform-linters/setup-tflint) for Lint terraform sources.                                              |
+| ```reusable-trivy.yaml```                    | Scan the repository with [aquasecurity/trivy-action](https://github.com/aquasecurity/trivy-action).                                                              |
+| ```reusable-tf-lint.yaml```                  | Lint Terraform sources with [terraform-linters/setup-tflint](https://github.com/terraform-linters/setup-tflint).                                                 |
 
 <!--td-workflows-end-->
 
 
 ## Probot configuration
 
 <!--probot-intro-start-->
-Collection of common Configurations for Project Management and CI/CD.  
-For Using in other GitHub Projects, having a reusable set of Probot Configuration Repository, more information at [probot.github.io](https://probot.github.io/docs/best-practices/#configuration).
+Collection of common configurations for project management and CI/CD.  
+Reuse this shared set of Probot configurations across your GitHub projects. For more information, see the [Probot best-practices documentation](https://probot.github.io/docs/best-practices/#configuration).
 <!--probot-intro-end-->
 
 <!--td-probot-apps-start-->
 | probot                                                            | git                                                                         | description                                                                                                         |
 |-------------------------------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
-| [boring-cyborg](https://probot.github.io/apps/boring-cyborg/)     | [kaxil/boring-cyborg](https://github.com/kaxil/boring-cyborg)               | Different actions like, automatically label Pull Request                                                       |
+| [boring-cyborg](https://probot.github.io/apps/boring-cyborg/)     | [kaxil/boring-cyborg](https://github.com/kaxil/boring-cyborg)               | Automates pull-request labelling and other repository housekeeping tasks.                                            |
 | [release-drafter](https://probot.github.io/apps/release-drafter/) | [release-drafter/release-drafter](https://github.com/release-drafter/release-drafter) | Creates a human-readable release changelog (**deprecated** as a Probot app—prefer the workflow implementation).     |
-| [renovate](https://github.com/apps/renovate)                      |                                                                             | Using [renovate](https://www.whitesourcesoftware.com/free-developer-tools/renovate/) for keep dependencies in sync. |
+| [renovate](https://github.com/apps/renovate)                      |                                                                             | Keeps dependencies in sync with [Renovate](https://www.whitesourcesoftware.com/free-developer-tools/renovate/), an automated dependency-update bot. |
 | [settings](https://probot.github.io/apps/settings/)               | [probot/settings](https://github.com/probot/settings)                       | Configure GitHub Projects by Source.                                                                                |
 <!--td-probot-apps-end-->
 
-For More information take a look to the GH Page, [gh-plumbing](http://nolte.github.io/gh-plumbing).
+For more information, see the [gh-plumbing GitHub Pages site](http://nolte.github.io/gh-plumbing).
 
 ## Development
 
@@ -63,13 +63,13 @@ asdf install
 
 ### Workflows
 
-For local testing you can use [nektos/act](https://github.com/nektos/act), run the GitHub Actions locally.
+For local testing, use [nektos/act](https://github.com/nektos/act) to run the GitHub Actions on your machine.
 
 ```sh
 act push -j static -W .github/workflows/build-static-tests.yaml
 ```
 
-Will be start the [![.github/workflows/build-static-tests.yaml](https://github.com/nolte/gh-plumbing/actions/workflows/build-static-tests.yaml/badge.svg)](https://github.com/nolte/gh-plumbing/actions/workflows/build-static-tests.yaml) at your system.
+This runs the [`build-static-tests`](https://github.com/nolte/gh-plumbing/actions/workflows/build-static-tests.yaml) workflow on your machine.
 
 
 ### Documentation
@@ -83,7 +83,7 @@ pip install -r requirements-dev.txt
 mkdocs serve -a localhost:8001
 ```
 
-Open [localhost:8001](http://localhost:8001/) for take a look to the latest documentation, created with [mkdocs](https://www.mkdocs.org/).
+Open [localhost:8001](http://localhost:8001/) to view the latest documentation, built with [mkdocs](https://www.mkdocs.org/).
 <!--development-intro-end-->
 
 ### Task
diff --git a/docs/de/development/index.md b/docs/de/development/index.md
@@ -59,7 +59,7 @@ act push -j static -W .github/workflows/build-static-tests.yaml
 
 ---
 
-## Prose-Linting
+## Prosa-Linting
 
 [Vale](https://vale.sh/) prüft Markdown-Dateien im CI über `reusable-spelling-vale.yaml`. Die Regeln liegen in `.vale.ini`, die Styles unter `.github/styles/`.
 
diff --git a/docs/de/portfolio-app/setup.md b/docs/de/portfolio-app/setup.md
@@ -24,18 +24,18 @@ Credential, das GitHub als user-initiated wertet.
 
 Die Spec verlangt eine Portfolio-Level-Lösung: eine App, in jedem
 Konsument-Repo installiert, mit demselben Wrapper-Pattern in jedem
-`.github/workflows/`. Kein PAT-Sammeln pro Repo, kein
-personengebundenes Credential.
+`.github/workflows/`. Kein Sammeln von Personal-Access-Tokens (PAT)
+pro Repo, kein personengebundenes Credential.
 
 ---
 
 ## Owner-Modi
 
 Die Portfolio-App kann Konsumenten unter einer GitHub-**Organisation**
-oder unter einem persönlichen **User-Account** bedienen. Wähle den
-Modus, der zum Account passt, der die Konsumenten-Repositories
-besitzt — beide Modi liefern dasselbe nachgelagerte Verhalten
-(App-emittierte Events kaskadieren user-initiated), nur die
+oder unter einem persönlichen **User-Account** bedienen. Den Modus
+wählen, der zum Account passt, der die Konsumenten-Repositories
+besitzt. Beide Modi liefern dasselbe nachgelagerte Verhalten —
+App-emittierte Events kaskadieren user-initiated —, nur die
 Credential-Verkabelung unterscheidet sich.
 
 | Modus | Wann wählen | Credentials liegen als |
@@ -108,12 +108,12 @@ Jedes aktivierte Häkchen würde nur tote Webhook-Versuche erzeugen.
    `https://github.com/settings/apps/new` für einen persönlichen
    Account). Namensvorschlag: `nolte-portfolio-bot`.
 2. **Permissions wie oben vergeben** und jeden Webhook-Event abwählen.
-3. **Private Key (PEM) generieren** — einmal speichern; GitHub zeigt
-   ihn nicht erneut an.
+3. **Private Key im PEM-Format (Privacy-Enhanced Mail) generieren** —
+   einmal speichern; GitHub zeigt ihn nicht erneut an.
 4. **App-ID notieren** (sichtbar auf der App-Settings-Seite).
 5. **App installieren** in jedem Konsument-Repository, das
-   cascade-korrekte Workflows braucht. Beginne mit
-   `nolte/gh-plumbing` selbst.
+   cascade-korrekte Workflows braucht. Mit `nolte/gh-plumbing` selbst
+   beginnen.
 6. **Credentials setzen** im Scope, der zum Owner-Modus passt:
    - **Organisations-Modus:** eine
      [Org-Level-Actions-Variable](https://docs.github.com/en/actions/learn-github-actions/variables)
@@ -149,10 +149,10 @@ Jedes aktivierte Häkchen würde nur tote Webhook-Versuche erzeugen.
 ## Wrapper-Pattern (für nachgelagerte Konsumenten)
 
 Die Cascade-emittierenden Wrapper in `nolte/gh-plumbing` zeigen das
-Pattern. Übernimm dieselbe Form in dein Repository für jeden Wrapper,
-der eine `reusable-*.yaml` aufruft, deren Arbeit nachgelagerte
-Workflows triggern soll oder die du unter derselben Release-Audit-
-Identität halten willst.
+Pattern. Dieselbe Form in das eigene Repository für jeden Wrapper
+übernehmen, der eine `reusable-*.yaml` aufruft, deren Arbeit
+nachgelagerte Workflows triggern soll oder die unter derselben
+Release-Audit-Identität bleiben soll.
 
 ```yaml title=".github/workflows/automerge.yaml"
 on:
@@ -233,7 +233,7 @@ Eine dritte Self-Check-Zeile betrifft den Issue-Lifecycle:
 |---|---|
 | PR squash-mergen, dessen Body `Closes #N` enthält | Issue `#N` flippt automatisch auf `CLOSED`; `gh issue view N --json state` liefert `CLOSED`. Setzt die App-Permission `Issues: Read and write` voraus — ohne sie greift der Merge zwar, der Close feuert aber nicht, obwohl `gh pr view --json closingIssuesReferences` den Autolink korrekt geparst zeigt. |
 
-Wenn ein Cascade immer noch nicht triggert, prüfe:
+Wenn ein Cascade immer noch nicht triggert, prüfen:
 
 1. Die App ist im Konsument-Repo installiert (`Settings → GitHub Apps`).
 2. `vars.PORTFOLIO_APP_ID` ist für den Workflow sichtbar.
@@ -254,7 +254,7 @@ Wenn ein Cascade immer noch nicht triggert, prüfe:
 | Reguläre jährliche Rotation | Neuen Private Key auf der App-Seite generieren, `PORTFOLIO_APP_PRIVATE_KEY` in jedem Konsumenten aktualisieren (oder einmal auf Org-Level, falls org-scoped), den alten Key auf der App-Seite löschen. |
 | Vermuteter Key-Leak | Geleakten Key sofort in den App-Settings widerrufen, neuen Key generieren, am selben Tag verteilen. App-ID bleibt unverändert. |
 | App-ID-Rotation | Niemals nötig — App-IDs sind unveränderlich. |
-| Permission-Scope-Änderung | App-Permissions editieren; bestehende Installation-Tokens mit alten Permissions laufen für ihre TTL (≤ 1 h) weiter, dann werden sie mit neuem Scope erneuert. |
+| Permission-Scope-Änderung | App-Permissions editieren; bestehende Installation-Tokens mit alten Permissions laufen für ihre Gültigkeitsdauer (TTL, ≤ 1 h) weiter, dann werden sie mit neuem Scope erneuert. |
 
 ---
 
diff --git a/docs/de/probot/settings.md b/docs/de/probot/settings.md
@@ -26,7 +26,7 @@ repository:
 ```
 
 !!! tip "Overrides"
-    Schlüssel in deiner lokalen `.github/settings.yml` überschreiben die geerbten Werte. Definiere dort nur, was vom geteilten Default abweicht.
+    Schlüssel in der lokalen `.github/settings.yml` überschreiben die geerbten Werte. Dort nur angeben, was vom geteilten Default abweicht.
 
 ---
 
diff --git a/docs/de/workflows/release.md b/docs/de/workflows/release.md
@@ -66,11 +66,11 @@ jobs:
 !!! note "Tag muss zu einem bestehenden Entwurf passen"
     `tag` muss zum Tag eines bestehenden Release-Drafter-Entwurfs passen. Es
     gibt keine „neuester gewinnt"-Heuristik — existiert kein Entwurf für den
-    angegebenen Tag, scheitert der Workflow sofort. Lass vorher den
-    Draft-Workflow auf `develop` laufen.
+    angegebenen Tag, scheitert der Workflow sofort. Zuvor den
+    Draft-Workflow auf `develop` laufen lassen.
 
 !!! tip "Dry Run"
-    Setze `dry_run: true`, um jeden Validierungs-Gate auszuführen, ohne den
+    `dry_run: true` setzen, um jeden Validierungs-Gate auszuführen, ohne den
     Entwurf zu einem veröffentlichten Release umzuschalten. Nützlich, um den
     Publish-Pfad vor dem eigentlichen Release zu verifizieren.
 
@@ -91,7 +91,7 @@ jobs:
 ```
 
 !!! warning "Direkte Commits auf master"
-    Commit nicht direkt auf `master` — der Workflow überschreibt deine Änderungen beim nächsten Release.
+    Nicht direkt auf `master` committen — der Workflow überschreibt lokale Änderungen beim nächsten Release.
 
 ---
 
diff --git a/docs/en/portfolio-app/setup.md b/docs/en/portfolio-app/setup.md
@@ -58,7 +58,7 @@ permissions**:
 |---|---|---|
 | `Contents` | `Read and write` | Squash-merge to develop, edit releases, fast-forward master |
 | `Pull requests` | `Read and write` | `pascalgn/automerge-action` reads and merges PRs |
-| `Issues` | `Read and write` | Auto-close issues referenced via `Closes #N` / `Fixes #N` / `Resolves #N` in the PR body when the App squash-merges. GitHub only honours these autolinks when the merging actor has `Issues: write`; without this scope the autolinks parse correctly into `closingIssuesReferences` but the close never fires (observed end-to-end on #357 / #358). |
+| `Issues` | `Read and write` | Automatically close issues referenced via `Closes #N` / `Fixes #N` / `Resolves #N` in the PR body when the App squash-merges. GitHub only honours these autolinks when the merging actor has `Issues: write`; without this scope the autolinks parse correctly into `closingIssuesReferences` but the close never fires (observed end-to-end on #357 / #358). |
 | `Actions` | `Read-only` | `release-publish` reads `gh run list` for the post-publish cascade sanity check |
 | `Metadata` | `Read-only` | Mandatory baseline (GitHub sets this automatically and won't let you disable it) |
 
@@ -226,7 +226,7 @@ A third self-check covers the issue lifecycle:
 
 | Action | Expected outcome |
 |---|---|
-| Squash-merge a PR whose body says `Closes #N` | Issue `#N` flips to `CLOSED` automatically; `gh issue view N --json state` returns `CLOSED`. Requires the App's `Issues: Read and write` permission — without it the merge succeeds but the close never fires, even though `gh pr view --json closingIssuesReferences` shows the link was parsed. |
+| Squash-merge a PR whose body says `Closes #N` | Issue `#N` flips to `CLOSED` automatically; `gh issue view N --json state` returns `CLOSED`. Requires the App's `Issues: Read and write` permission—without it the merge succeeds but the close never fires, even though `gh pr view --json closingIssuesReferences` shows that GitHub parsed the link. |
 
 If a cascade still fails to fire, check:
 
