feat: business-first README and correct installs on Python 3.13+

.github/workflows/main.yml

@@ -77,3 +77,104 @@ jobs:
           ! grep -E '/(\.env|\.cache/|[^/]+\.db$|output\.png$|\.claude/|\.worktrees/)' /tmp/openadapt-sdist-files.txt
           unzip -l dist/*.whl > /tmp/openadapt-wheel-files.txt
           ! grep -E '(\.env|\.cache/|[^/]+\.db$|output\.png$|\.claude/|\.worktrees/)' /tmp/openadapt-wheel-files.txt
+
+  # pip on Python 3.13 and 3.14 used to skip every current launcher (all
+  # capped below 3.13) and silently install openadapt 1.3.0, an unrelated
+  # pre-compiler CLI. The launcher now installs on any Python >=3.10 and keeps
+  # the engine behind a version marker. This job proves, on the first
+  # unsupported interpreters, that the built wheel installs without the engine
+  # and that each engine command prints the Python 3.12 install fix.
+  unsupported-python-guard:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+    strategy:
+      matrix:
+        python-version: ['3.13', '3.14']
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Build the launcher wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+
+      # Installing dist/*.whl directly would hide the original bug, which was
+      # pip choosing an older release by name. Resolve by name with PyPI in
+      # view: if this launcher didn't install here, an old release that allows
+      # this Python (1.3.0 did) would win and the version check would fail.
+      - name: Resolve openadapt by name and confirm pip picks this launcher
+        run: |
+          for spec in openadapt 'openadapt[browser]' 'openadapt[capture]'; do
+            python -m pip install --dry-run --quiet --find-links dist \
+              --report resolution.json "$spec"
+            python - "$spec" <<'PY'
+          import json
+          import pathlib
+          import sys
+          import tomllib
+
+          spec = sys.argv[1]
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())
+          expected = project["project"]["version"]
+          report = json.loads(pathlib.Path("resolution.json").read_text())
+          chosen = {
+              item["metadata"]["name"]: item["metadata"]["version"]
+              for item in report["install"]
+          }
+          assert chosen.get("openadapt") == expected, (spec, chosen.get("openadapt"))
+          for name in ("openadapt-flow", "openadapt-agent"):
+              assert name not in chosen, (spec, name, chosen[name])
+          print(f"{spec}: pip chose openadapt {expected} with no engine")
+          PY
+          done
+
+      - name: Install the wheel and confirm it brings no engine
+        run: |
+          python -m pip install dist/*.whl
+          python - <<'PY'
+          import pathlib
+          import tomllib
+          from importlib.metadata import PackageNotFoundError, version
+
+          project = tomllib.loads(pathlib.Path("pyproject.toml").read_text())
+          expected = project["project"]["version"]
+          assert version("openadapt") == expected, version("openadapt")
+          for name in ("openadapt-flow", "openadapt-agent"):
+              try:
+                  found = version(name)
+              except PackageNotFoundError:
+                  continue
+              raise SystemExit(f"{name} {found} must not install on this Python")
+          print(f"openadapt {expected} installed alone, as intended")
+          PY
+
+      - name: Engine commands print the install fix
+        run: |
+          for command in "quickstart --break-it" "flow tutorial" "doctor"; do
+            read -ra args <<<"$command"
+            set +e
+            output=$(openadapt "${args[@]}" 2>&1)
+            status=$?
+            set -e
+            echo "$output"
+            test "$status" -eq 1
+            grep -q "uv tool install --python 3.12 openadapt" <<<"$output"
+          done
+          help_text=$(openadapt --help)
+          grep -q "OpenAdapt needs Python 3.10" <<<"$help_text"
+
+      - name: Run the Python support tests
+        run: |
+          python -m pip install pytest packaging
+          pytest tests/test_python_support.py -v