feat: pipx as recommended install method

- README.md: lead install section with pipx; show pipx inject for each
  provider extra and GUI; pip as secondary option; update instructions
  (pipx upgrade vs specsmith self-update)
- updater.py: add is_pipx_install() detection (checks sys.executable
  path + PIPX_HOME / PIPX_LOCAL_VENVS env vars); run_self_update() now
  uses 'pipx upgrade specsmith' when running inside a pipx environment
  instead of 'pip install --upgrade'
- agents.md.j2: add install/update block to Quick Command Reference
  showing pipx install + inject pattern alongside pip fallback

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

README.md

@@ -76,10 +76,30 @@ Every governed project follows: **propose → check → execute → verify → r
 
 ## Install
 
+**Recommended — global install via [pipx](https://pipx.pypa.io) (isolated, no dependency conflicts):**
+
+```bash
+pipx install specsmith                    # core CLI + epistemic library
+pipx inject specsmith anthropic           # + Claude support
+pipx inject specsmith openai             # + GPT / O-series support
+pipx inject specsmith google-generativeai # + Gemini support
+pipx inject specsmith PySide6            # + GUI (specsmith gui)
+```
+
+**Or with pip (into your active environment):**
+
+```bash
+pip install specsmith                # core
+pip install "specsmith[anthropic]"  # + Claude
+pip install "specsmith[openai]"     # + GPT/O-series
+pip install "specsmith[gui]"        # + GUI
+```
+
+**Update:**
+
 ```bash
-pip install specsmith             # core + epistemic library
-pip install specsmith[anthropic]  # + Claude support (specsmith run)
-pip install specsmith[openai]     # + GPT/O-series support
+pipx upgrade specsmith     # pipx install
+specsmith self-update      # pip install
 ```
 
 ## Quick Start

src/specsmith/templates/agents.md.j2

@@ -215,3 +215,16 @@ Stop condition (H13): P1 requirement with confidence below MEDIUM = work stops.
 | `pr`           | `specsmith pr` (create PR with governance)     |
 | `update`       | `specsmith update` (check + install + migrate) |
 | `session-end`  | `specsmith session-end` (end checklist)        |
+
+**specsmith install / update:**
+
+```bash
+# Recommended — global isolated install
+pipx install specsmith
+pipx inject specsmith anthropic openai  # add LLM providers
+pipx upgrade specsmith                  # update
+
+# Or with pip
+pip install specsmith
+specsmith self-update
+```

src/specsmith/updater.py

@@ -60,24 +60,50 @@ def is_outdated() -> bool:
     return current != latest
 
 
+def is_pipx_install() -> bool:
+    """Return True if specsmith was installed via pipx.
+
+    Checks sys.executable path and PIPX_HOME / PIPX_LOCAL_VENVS env vars.
+    """
+    import os
+    import sys
+
+    exe = sys.executable.replace("\\", "/").lower()
+    return (
+        "pipx" in exe
+        or bool(os.environ.get("PIPX_HOME"))
+        or bool(os.environ.get("PIPX_LOCAL_VENVS"))
+    )
+
+
 def run_self_update(
     *,
     channel: str = "",
     target_version: str = "",
 ) -> tuple[bool, str]:
-    """Update specsmith via pip.
+    """Update specsmith.
+
+    Detects whether running under pipx and uses the appropriate command:
+      - pipx: ``pipx upgrade specsmith`` (or ``pipx install specsmith==X.Y.Z``)
+      - pip: ``pip install --upgrade specsmith``
 
     If target_version is set, installs that exact version.
     Otherwise uses --pre flag for dev channel, plain upgrade for stable.
     """
-    if target_version:
-        cmd = ["pip", "install", f"specsmith=={target_version}"]
+    if is_pipx_install():
+        if target_version:
+            cmd = ["pipx", "install", f"specsmith=={target_version}", "--force"]
+        else:
+            cmd = ["pipx", "upgrade", "specsmith"]
     else:
-        if not channel:
-            channel = get_update_channel()
-        cmd = ["pip", "install", "--upgrade", "specsmith"]
-        if channel == "dev":
-            cmd.insert(2, "--pre")
+        if target_version:
+            cmd = ["pip", "install", f"specsmith=={target_version}"]
+        else:
+            if not channel:
+                channel = get_update_channel()
+            cmd = ["pip", "install", "--upgrade", "specsmith"]
+            if channel == "dev":
+                cmd.insert(2, "--pre")
 
     try:
         result = subprocess.run(