From ec1d3c4d04e810e6c8bda5cf1b65b9a5deb99d18 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9=20Bezek?=
 <200930841+Andre-Bzk@users.noreply.github.com>
Date: Sun, 19 Jul 2026 12:21:22 +0200
Subject: [PATCH] docs: document PowerShell-host fallback and self-test in
 install steps

Update the README to match the installer's new behavior: it detects the
available PowerShell host (prefers pwsh 7, falls back to Windows PowerShell
5.1) instead of writing a broken pwsh path when PS7 is absent, and runs a
self-test to confirm the statusline renders. Removes the now-inaccurate claim
that PowerShell 7 must be installed first.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01C4QKwZ7bC7oCMVtnuJdDKm
---
 README.md | 63 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 55 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index bdbb0c5..834d5c9 100644
--- a/README.md
+++ b/README.md
@@ -58,15 +58,37 @@ Where to change them:
 ```powershell
 git clone https://github.com/Andre-Bzk/claude-statusline-kit claude-statusline-kit
 cd claude-statusline-kit
-.\install.ps1
+powershell -ExecutionPolicy Bypass -File .\install.ps1
 ```
 
 Then restart Claude Code (or start a new session).
 
+> **Why `powershell` and not `pwsh`?** The installer runs under the built-in
+> **Windows PowerShell 5.1** (`powershell.exe`), which ships with every Windows
+> — so bootstrapping works even before PowerShell 7 is installed. (`pwsh` would
+> fail with *"pwsh is not recognized"* on a fresh PC.) To wire the statusline
+> runtime into `settings.json` the installer detects the available host: it
+> prefers `pwsh` (PowerShell 7, sharper glyphs) and falls back to Windows
+> PowerShell 5.1 when PS7 isn't present — so the statusline works out of the box
+> either way. Installing PowerShell 7 (see **Requirements**) is recommended but
+> optional. A built-in self-test then confirms the statusline actually renders.
+>
+> **Why `-ExecutionPolicy Bypass`?** On a fresh Windows PC the per-user
+> execution policy is `Restricted`, so a bare `.\install.ps1` fails with
+> *"... cannot be loaded because running scripts is disabled on this system."*
+> Passing `-ExecutionPolicy Bypass -File` runs the installer for this one
+> invocation only — it changes **no** persistent machine or user setting.
+> Extra options work the same way, e.g.
+> `powershell -ExecutionPolicy Bypass -File .\install.ps1 -Force`.
+>
+> Prefer to unblock scripts once and for all? Run
+> `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` (no admin needed), then
+> `.\install.ps1` works directly.
+
 The installer is **idempotent** — run it again anytime. It auto-detects the
-`pwsh` path on the target machine and merges the `statusLine` block into an
-existing `settings.json` **without** overwriting your other settings (a
-`.bak` backup is written first).
+PowerShell host on the target machine (pwsh 7, else Windows PowerShell 5.1) and
+merges the `statusLine` block into an existing `settings.json` **without**
+overwriting your other settings (a `.bak` backup is written first).
 
 ### Nerd Font (automatic, no admin)
 
@@ -153,15 +175,40 @@ Wo man sie ändert:
 ```powershell
 git clone https://github.com/Andre-Bzk/claude-statusline-kit claude-statusline-kit
 cd claude-statusline-kit
-.\install.ps1
+powershell -ExecutionPolicy Bypass -File .\install.ps1
 ```
 
 Danach Claude Code neu starten (oder eine neue Session öffnen).
 
+> **Warum `powershell` und nicht `pwsh`?** Der Installer läuft unter dem
+> mitgelieferten **Windows PowerShell 5.1** (`powershell.exe`), das auf jedem
+> Windows vorhanden ist — so klappt das Bootstrapping schon, bevor PowerShell 7
+> installiert ist. (`pwsh` würde auf einem frischen PC mit *„pwsh wurde nicht
+> erkannt"* fehlschlagen.) Um den Statusline-Runtime in die `settings.json`
+> einzutragen, erkennt der Installer den vorhandenen Host: Er bevorzugt `pwsh`
+> (PowerShell 7, schärfere Glyphen) und fällt auf Windows PowerShell 5.1 zurück,
+> falls PS7 fehlt — die Statusline funktioniert also so oder so out of the box.
+> PowerShell 7 zu installieren (siehe **Voraussetzungen**) ist empfohlen, aber
+> optional. Ein integrierter Selbsttest bestätigt anschließend, dass die
+> Statusline tatsächlich gerendert wird.
+>
+> **Warum `-ExecutionPolicy Bypass`?** Auf einem frischen Windows-PC steht die
+> Execution Policy für den Benutzer auf `Restricted`, deshalb bricht ein bloßes
+> `.\install.ps1` mit *„... cannot be loaded because running scripts is disabled
+> on this system."* ab. `-ExecutionPolicy Bypass -File` führt den Installer nur
+> für diesen einen Aufruf aus — es ändert **keine** dauerhafte System- oder
+> Benutzereinstellung. Zusätzliche Optionen funktionieren genauso, z. B.
+> `powershell -ExecutionPolicy Bypass -File .\install.ps1 -Force`.
+>
+> Skripte lieber dauerhaft freischalten? Einmalig
+> `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` ausführen (keine
+> Admin-Rechte nötig), danach klappt `.\install.ps1` direkt.
+
 Der Installer ist **idempotent** — jederzeit erneut ausführbar. Er erkennt den
-`pwsh`-Pfad auf dem Zielrechner automatisch und fügt den `statusLine`-Block in
-eine vorhandene `settings.json` ein, **ohne** deine anderen Einstellungen zu
-überschreiben (vorher wird ein `.bak`-Backup geschrieben).
+PowerShell-Host auf dem Zielrechner automatisch (pwsh 7, sonst Windows
+PowerShell 5.1) und fügt den `statusLine`-Block in eine vorhandene
+`settings.json` ein, **ohne** deine anderen Einstellungen zu überschreiben
+(vorher wird ein `.bak`-Backup geschrieben).
 
 ### Nerd-Font (automatisch, ohne Admin)