setup: handle managed python pre-commit installs

README.md

@@ -87,6 +87,12 @@ These older docs are still useful but are no longer the best starting point.
 ```
 
 This installs the local development hooks and prepares the shell-based workflow.
+If `pip3` is unavailable or blocked by an externally managed Python environment, install the distro package first:
+
+```bash
+sudo apt-get install -y pre-commit
+./setup.sh
+```
 
 ### Required Dependencies
 

docs/getting-started.md

@@ -52,6 +52,13 @@ Use the local README in:
 ./setup.sh
 ```
 
+If `./setup.sh` cannot install `pre-commit` because `pip3` is missing or the host uses an externally managed Python environment, install the distro package first:
+
+```bash
+sudo apt-get install -y pre-commit
+./setup.sh
+```
+
 ### GitHub Authentication
 
 Most root scripts expect:

setup.sh

@@ -3,12 +3,25 @@
 set -e
 
 if ! command -v pre-commit >/dev/null 2>&1; then
+    if ! command -v pip3 >/dev/null 2>&1; then
+        echo "pre-commit not found and pip3 is unavailable."
+        echo "Install pre-commit with your package manager first."
+        echo "On Ubuntu/Debian: sudo apt-get install -y pre-commit"
+        exit 1
+    fi
+
     echo "pre-commit not found, installing via pip..."
-    pip3 install pre-commit
+    if ! pip3 install pre-commit; then
+        echo "pip3 could not install pre-commit."
+        echo "If this system uses an externally managed Python environment,"
+        echo "install the distro package instead."
+        echo "On Ubuntu/Debian: sudo apt-get install -y pre-commit"
+        exit 1
+    fi
 else
     echo "pre-commit already installed."
 fi
 
 pre-commit install
 
-echo "pre-commit hooks installed!" 
+echo "pre-commit hooks installed!"