ipscout 1.0.0__tar.gz

ipscout-1.0.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "ipscout",
+  "owner": {
+    "name": "bitranox"
+  },
+  "metadata": {
+    "description": "ipscout delivered as a single Claude Code plugin: a skill for probing network reachability and inspecting the local network from Python or the shell, in-process and without administrator rights."
+  },
+  "plugins": [
+    {
+      "name": "ipscout",
+      "source": ".",
+      "description": "Ping, sweep, traceroute and interface enumeration from Python or the CLI, unprivileged and without a subprocess. Covers the library API, the JSON output for machine consumers, and the platform limits measured on Linux, macOS and Windows."
+    }
+  ]
+}

ipscout-1.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "ipscout",
+  "description": "Ping hosts, sweep a subnet, measure round-trip time and packet loss, run a traceroute, scan ports, look up MAC addresses and the neighbour cache, query routes and the default gateway, list interfaces and subnets, send wake-on-LAN and find the path MTU - from Python or the shell, as an ordinary user with no root or Administrator rights and without shelling out. Ships the python-network-probe skill: the library API, the CLI with its JSON envelope, the raise-on-setup-problems error contract, and the measured platform limits.",
+  "version": "1.1.0",
+  "author": {
+    "name": "bitranox"
+  },
+  "homepage": "https://github.com/bitranox/ipscout",
+  "repository": "https://github.com/bitranox/ipscout",
+  "license": "MIT"
+}

ipscout-1.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,22 @@
+{
+  "image": "mcr.microsoft.com/devcontainers/python:3.13",
+
+  "postCreateCommand": "bash -lc '\nPY=/usr/local/bin/python;\n$PY -m pip install -U pip && \\\n$PY -m pip install ipykernel && \\\n$PY -m pip install -e . && \\\n# register kernel using this exact interpreter\n$PY -m ipykernel install --name=python3 --display-name=\"Python 3 (3.13)\" --user && \\\n# patch the notebook to point to the python3 kernelspec (VS Code will bind to /usr/local/bin/python)\n$PY - <<\"PY\"\nimport json, pathlib\np = pathlib.Path(\"notebooks/Quickstart.ipynb\")\nif p.exists():\n    nb = json.loads(p.read_text(encoding=\"utf-8\"))\n    md = nb.setdefault(\"metadata\", {})\n    md[\"kernelspec\"] = {\n        \"name\": \"python3\",\n        \"display_name\": \"Python 3 (3.13)\",\n        \"language\": \"python\"\n    }\n    md[\"language_info\"] = {\"name\": \"python\"}\n    p.write_text(json.dumps(nb, ensure_ascii=False, indent=1), encoding=\"utf-8\")\n    print(\"Pinned kernelspec to python3 in\", p)\nelse:\n    print(\"Notebook not found:\", p)\nPY'\n",
+
+  "customizations": {
+    "vscode": {
+      "extensions": ["ms-toolsai.jupyter", "ms-python.python"],
+      "settings": {
+        "workbench.startupEditor": "none",
+        "jupyter.alwaysTrustNotebooks": true,
+        "jupyter.kernelPickerType": "OnlyRecommended",
+        "python.defaultInterpreterPath": "/usr/local/bin/python"
+      }
+    },
+    "codespaces": {
+      "openFiles": ["README.md"]
+    }
+  },
+
+  "postAttachCommand": "bash -lc 'if [ -f notebooks/Quickstart.ipynb ]; then code -r notebooks/Quickstart.ipynb; fi'"
+}

ipscout-1.0.0/.devcontainer/settings.json

@@ -0,0 +1,6 @@
+{
+  "python.defaultInterpreterPath": "/usr/local/bin/python3.13",
+  "jupyter.alwaysTrustNotebooks": true,
+  "jupyter.kernelPickerType": "OnlyRecommended",
+  "jupyter.askForKernelRestart": false
+}

ipscout-1.0.0/.env.example

@@ -0,0 +1,11 @@
+# Copy to .env and fill values as needed.
+
+# Codecov upload token (required for private repos; optional for public repos)
+CODECOV_TOKEN=
+
+# PyPI API token for release workflow (.github/workflows/release.yml)
+# Format: pypi-AgENdGVzdC5weXBpLm9yZwIk...
+PYPI_API_TOKEN=
+
+# Optional: GitHub token for API-limited tasks
+GITHUB_TOKEN=

ipscout-1.0.0/.github/actions/extract-metadata/action.yml

@@ -0,0 +1,108 @@
+name: Extract project metadata
+description: >-
+  Parse pyproject.toml and expose project metadata as step outputs.
+  Requires Python to be available in the runner environment.
+  Auto-installs rtoml if not already present.
+
+outputs:
+  PACKAGE_MODULE:
+    description: Python-importable module name (underscored)
+    value: ${{ steps.meta.outputs.PACKAGE_MODULE }}
+  PROJECT_NAME:
+    description: Project name from pyproject.toml
+    value: ${{ steps.meta.outputs.PROJECT_NAME }}
+  CLI_BIN:
+    description: CLI entry-point binary name
+    value: ${{ steps.meta.outputs.CLI_BIN }}
+  SRC_PATH:
+    description: Source directory path (e.g. "src")
+    value: ${{ steps.meta.outputs.SRC_PATH }}
+  COV_FAIL_UNDER:
+    description: Minimum coverage percentage from tool.coverage.report.fail_under
+    value: ${{ steps.meta.outputs.COV_FAIL_UNDER }}
+  COV_REPORT_FILE:
+    description: Coverage report filename (e.g. "coverage.xml")
+    value: ${{ steps.meta.outputs.COV_REPORT_FILE }}
+  PYTEST_VERBOSITY:
+    description: Pytest verbosity flag (e.g. "-vv")
+    value: ${{ steps.meta.outputs.PYTEST_VERBOSITY }}
+  BANDIT_SKIP_FLAG:
+    description: Bandit skip flag string (e.g. "-s B101,B601") or empty
+    value: ${{ steps.meta.outputs.BANDIT_SKIP_FLAG }}
+  PYTEST_MARKER_EXPR:
+    description: >-
+      Marker expression for the CI test run (e.g. "not local_only and not integration"),
+      built from tool.ci.pytest-exclude-markers
+    value: ${{ steps.meta.outputs.PYTEST_MARKER_EXPR }}
+
+runs:
+  using: composite
+  steps:
+    - name: Extract project metadata from pyproject.toml
+      id: meta
+      shell: python
+      run: |
+        import os, subprocess, sys
+        try:
+            import rtoml
+        except ModuleNotFoundError:
+            subprocess.check_call([sys.executable, "-m", "pip", "install", "rtoml", "-q"])
+            import rtoml
+
+        from pathlib import Path
+        data = rtoml.load(Path('pyproject.toml'))
+
+        # --- [project] section ---
+        project = data['project']['name']
+        module = project.replace('-', '_')
+        dash = project.replace('_', '-')
+        scripts = list(data['project'].get('scripts', {}).keys())
+        cli_bin = scripts[0] if scripts else dash
+
+        # --- [tool.scripts.test] section ---
+        scripts_test = data.get('tool', {}).get('scripts', {}).get('test', {})
+        src_path = scripts_test.get('src-path', 'src')
+        pytest_verbosity = scripts_test.get('pytest-verbosity', '-vv')
+        cov_report_file = scripts_test.get('coverage-report-file', 'coverage.xml')
+
+        # --- [tool.coverage.report] section ---
+        cov_fail_under = (
+            data.get('tool', {}).get('coverage', {}).get('report', {}).get('fail_under', 90)
+        )
+
+        # --- [tool.bandit] section ---
+        bandit_skips = data.get('tool', {}).get('bandit', {}).get('skips', [])
+        bandit_skip_flag = f"-s {','.join(bandit_skips)}" if bandit_skips else ""
+
+        # --- [tool.ci] section ---
+        # CI always skips local_only (those tests need a dev box). A project whose
+        # suite also carries markers CI cannot satisfy - integration tests needing a
+        # container that a separate workflow starts - names them here, rather than
+        # every such repo forking this workflow to edit one -m expression.
+        ci_config = data.get('tool', {}).get('ci', {})
+        exclude_markers = ['local_only', *ci_config.get('pytest-exclude-markers', [])]
+        pytest_marker_expr = ' and '.join(f'not {m}' for m in exclude_markers)
+
+        # Write to GITHUB_OUTPUT for composite action outputs
+        with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as out:
+            out.write(f"PROJECT_NAME={project}\n")
+            out.write(f"PACKAGE_MODULE={module}\n")
+            out.write(f"CLI_BIN={cli_bin}\n")
+            out.write(f"SRC_PATH={src_path}\n")
+            out.write(f"PYTEST_VERBOSITY={pytest_verbosity}\n")
+            out.write(f"COV_REPORT_FILE={cov_report_file}\n")
+            out.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
+            out.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")
+            out.write(f"PYTEST_MARKER_EXPR={pytest_marker_expr}\n")
+
+        # Also write to GITHUB_ENV so subsequent steps can use ${{ env.VAR }}
+        with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as env:
+            env.write(f"PROJECT_NAME={project}\n")
+            env.write(f"PACKAGE_MODULE={module}\n")
+            env.write(f"CLI_BIN={cli_bin}\n")
+            env.write(f"SRC_PATH={src_path}\n")
+            env.write(f"PYTEST_VERBOSITY={pytest_verbosity}\n")
+            env.write(f"COV_REPORT_FILE={cov_report_file}\n")
+            env.write(f"COV_FAIL_UNDER={cov_fail_under}\n")
+            env.write(f"BANDIT_SKIP_FLAG={bandit_skip_flag}\n")
+            env.write(f"PYTEST_MARKER_EXPR={pytest_marker_expr}\n")

ipscout-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    allow:
+      - dependency-type: "direct"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+      include: "scope"

ipscout-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,39 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    - cron: '0 8 * * 1'
+
+jobs:
+  analyze:
+    name: CodeQL Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v4
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: "/language:${{ matrix.language }}"

ipscout-1.0.0/.github/workflows/default_cicd_public.yml

@@ -0,0 +1,436 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Run daily at 3:17 AM UTC (off-peak hours, odd minute to avoid congestion)
+    - cron: '17 3 * * *'
+
+jobs:
+  setup:
+    name: Extract Python versions and OS matrix from pyproject.toml
+    runs-on: ubuntu-latest
+    outputs:
+      python-versions: ${{ steps.metadata.outputs.python-versions }}
+      python-latest: ${{ steps.metadata.outputs.python-latest }}
+      os-matrix: ${{ steps.metadata.outputs.os-matrix }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.x"
+      - name: Parse pyproject.toml for Python versions and OS matrix
+        id: metadata
+        shell: python
+        run: |
+          import json, os, tomllib
+
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+
+          # Python versions from classifiers
+          classifiers = data.get("project", {}).get("classifiers", [])
+          prefix = "Programming Language :: Python :: "
+          versions = [
+              c[len(prefix):]
+              for c in classifiers
+              if c.startswith(prefix) and "." in c[len(prefix):]
+          ]
+          if not versions:
+              raise SystemExit("No Python X.Y versions found in classifiers")
+
+          # OS matrix from [tool.ci]
+          ci_config = data.get("tool", {}).get("ci", {})
+          os_list = ci_config.get("os", ["ubuntu-latest"])
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as fh:
+              fh.write(f"python-versions={json.dumps(versions)}\n")
+              fh.write(f"python-latest={versions[-1]}\n")
+              fh.write(f"os-matrix={json.dumps(os_list)}\n")
+
+  test:
+    name: Tests (Python ${{ matrix.python }}, ${{ matrix.os }})
+    needs: setup
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJSON(needs.setup.outputs.os-matrix) }}
+        python: ${{ fromJSON(needs.setup.outputs.python-versions) }}
+    env:
+      PYO3_USE_ABI3_FORWARD_COMPATIBILITY: "1"
+      PYTHONIOENCODING: "utf-8"
+      UV_LINK_MODE: "copy"
+      UV_BREAK_SYSTEM_PACKAGES: "1"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install bash 4+ on macOS
+        if: runner.os == 'macOS'
+        run: |
+          brew install bash
+          echo "$(brew --prefix)/bin" >> "$GITHUB_PATH"
+
+      - name: Extract project metadata
+        id: metadata
+        uses: ./.github/actions/extract-metadata
+
+      - name: Install CI system dependencies (Ubuntu)
+        if: runner.os == 'Linux'
+        shell: python
+        run: |
+          import subprocess
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import pip._vendor.tomli as tomllib
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          deps = data.get("tool", {}).get("ci", {}).get("system-dependencies-ubuntu", [])
+          if deps:
+              print(f"Installing system packages: {' '.join(deps)}")
+              subprocess.check_call(["sudo", "apt-get", "update"])
+              subprocess.check_call(["sudo", "apt-get", "install", "-y", *deps])
+          else:
+              print("No CI system dependencies configured for Ubuntu.")
+
+      - name: Install CI system dependencies (macOS)
+        if: runner.os == 'macOS'
+        shell: python
+        run: |
+          import subprocess
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import pip._vendor.tomli as tomllib
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          deps = data.get("tool", {}).get("ci", {}).get("system-dependencies-macos", [])
+          if deps:
+              print(f"Installing system packages: {' '.join(deps)}")
+              subprocess.check_call(["brew", "install", *deps])
+          else:
+              print("No CI system dependencies configured for macOS.")
+
+      - name: Install dev deps
+        shell: bash
+        run: |
+          uv pip install -e .[dev] --system
+
+      - name: Install CI system dependencies (Windows/choco)
+        if: runner.os == 'Windows'
+        shell: python
+        run: |
+          import subprocess
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import pip._vendor.tomli as tomllib
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          deps = data.get("tool", {}).get("ci", {}).get("system-dependencies-windows-choco", [])
+          if deps:
+              print(f"Installing choco packages: {' '.join(deps)}")
+              subprocess.check_call(["choco", "install", "-y", *deps])
+          else:
+              print("No CI choco dependencies configured for Windows.")
+
+      - name: Install CI pip dependencies (Windows)
+        if: runner.os == 'Windows'
+        shell: python
+        run: |
+          import subprocess
+          try:
+              import tomllib
+          except ModuleNotFoundError:
+              import pip._vendor.tomli as tomllib
+          with open("pyproject.toml", "rb") as f:
+              data = tomllib.load(f)
+          deps = data.get("tool", {}).get("ci", {}).get("system-dependencies-windows-pip", [])
+          if deps:
+              print(f"Installing pip packages: {' '.join(deps)}")
+              subprocess.check_call(["uv", "pip", "install", *deps, "--system"])
+          else:
+              print("No CI pip dependencies configured for Windows.")
+
+      # Self-hosted runners persist ruff cache via RUFF_CACHE_DIR volume mount,
+      # so actions/cache is only needed on GitHub-hosted runners.
+      - name: Restore ruff cache
+        if: runner.environment == 'github-hosted'
+        id: ruff-cache
+        uses: actions/cache/restore@v6
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+          restore-keys: |
+            ruff-${{ runner.os }}-py${{ matrix.python }}-
+            ruff-${{ runner.os }}-
+
+      - name: Run ruff (lint + format)
+        id: ruff
+        continue-on-error: true
+        shell: bash
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run pyright (type check)
+        id: pyright
+        continue-on-error: true
+        shell: bash
+        run: pyright
+
+      - name: Run pytest (tests + coverage)
+        id: pytest
+        continue-on-error: true
+        shell: bash
+        env:
+          TEST_VERBOSE: "1"
+          # Write coverage SQLite database to local disk — network mounts
+          # and stale journal files cause "database is locked" errors.
+          COVERAGE_FILE: "${{ runner.temp }}/.coverage"
+        run: >-
+          pytest -m "${{ env.PYTEST_MARKER_EXPR }}"
+          --cov=${{ env.SRC_PATH }}/${{ env.PACKAGE_MODULE }}
+          --cov-report=term-missing
+          --cov-report=xml:${{ env.COV_REPORT_FILE }}
+          --cov-fail-under=${{ env.COV_FAIL_UNDER }}
+          ${{ env.PYTEST_VERBOSITY }}
+
+      - name: Upload coverage to Codecov
+        if: >-
+          always()
+          && steps.pytest.outcome == 'success'
+          && matrix.os == 'ubuntu-latest'
+          && matrix.python == needs.setup.outputs.python-latest
+        uses: codecov/codecov-action@v7
+        with:
+          files: ${{ env.COV_REPORT_FILE }}
+          fail_ci_if_error: false
+
+      - name: Run import-linter (architecture)
+        id: importlinter
+        continue-on-error: true
+        shell: bash
+        run: lint-imports
+
+      - name: Run bandit (security scan)
+        id: bandit
+        continue-on-error: true
+        shell: bash
+        run: bandit -q -c pyproject.toml -r ${{ env.SRC_PATH }}/${{ env.PACKAGE_MODULE }} ${{ env.BANDIT_SKIP_FLAG }}
+
+      - name: Run pip-audit (vulnerability scan)
+        id: pipaudit
+        continue-on-error: true
+        shell: python
+        run: |
+          import subprocess, sys, tempfile
+          import rtoml
+          from pathlib import Path
+
+          # Audit the project's OWN resolved dependency tree, not the ambient
+          # environment. "Install dev deps" uses --system, so the interpreter
+          # being audited is the runner image's, and that image ships packages
+          # this project neither declares nor distributes (setuptools, pip,
+          # wheel). Auditing those reported CVEs no consumer of this project is
+          # exposed to, and a scan that is permanently yellow is a scan everyone
+          # learns to ignore. Resolving pyproject.toml here keeps the result
+          # identical on every OS/python and dependent only on what we declare.
+          data = rtoml.load(Path("pyproject.toml"))
+
+          # Not every project declares dev dependencies, and those that do may use
+          # either an extra or a PEP 735 group. Asking uv for one that does not
+          # exist is a hard error ("Requested extra not found"), which would leave
+          # the audit permanently broken here rather than merely noisy, so select
+          # the flag from what this project actually declares.
+          selector = []
+          if "dev" in data.get("project", {}).get("optional-dependencies", {}):
+              selector = ["--extra", "dev"]
+          elif "dev" in data.get("dependency-groups", {}):
+              selector = ["--group", "dev"]
+
+          tmp = Path(tempfile.mkdtemp())
+          req = tmp / "compiled-requirements.txt"
+          subprocess.check_call(
+              ["uv", "pip", "compile", *selector, "pyproject.toml", "-o", str(req), "--quiet"]
+          )
+
+          # Drop direct URL references ("pkg @ git+https://...") before auditing.
+          # pip-audit cannot audit those (they are not on PyPI) but, given a
+          # requirements file, first tries to `git clone` each one to resolve a
+          # version - a slow, credential-dependent fetch. No public project here
+          # uses one today, yet "allow-direct-references" is enabled, so this
+          # guards the day one appears and keeps this step identical to the
+          # default_cicd_private template's.
+          audit_req = tmp / "audit-requirements.txt"
+          kept, dropped = [], []
+          for line in req.read_text(encoding="utf-8").splitlines():
+              if " @ " in line and not line.lstrip().startswith("#"):
+                  dropped.append(line.split(" @ ", 1)[0].strip())
+              else:
+                  kept.append(line)
+          audit_req.write_text("\n".join(kept) + "\n", encoding="utf-8")
+          if dropped:
+              # Never drop coverage silently: name what is not being audited here.
+              print(f"::notice::pip-audit: not auditing {len(dropped)} direct-URL dependency/ies "
+                    f"(audited in their own repo): {', '.join(sorted(dropped))}")
+
+          req = audit_req
+          vulns = data.get("tool", {}).get("pip-audit", {}).get("ignore-vulns", [])
+          # --no-deps: the compiled file is already a complete pinned resolution,
+          # so pip-audit must audit it verbatim rather than re-resolving it.
+          cmd = ["pip-audit", "--no-deps", "-r", str(req)]
+          for v in vulns:
+              cmd.extend(["--ignore-vuln", v])
+          sys.exit(subprocess.call(cmd))
+
+      - name: Check all steps passed
+        shell: bash
+        run: |
+          if [[ "${{ steps.ruff.outcome }}" != "success" ]]; then
+            echo "::error::Ruff check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pyright.outcome }}" != "success" ]]; then
+            echo "::error::Pyright check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pytest.outcome }}" != "success" ]]; then
+            echo "::error::Pytest failed"
+            exit 1
+          fi
+          if [[ "${{ steps.importlinter.outcome }}" != "success" ]]; then
+            echo "::error::Import-linter check failed"
+            exit 1
+          fi
+          if [[ "${{ steps.bandit.outcome }}" != "success" ]]; then
+            echo "::error::Bandit security scan failed"
+            exit 1
+          fi
+          if [[ "${{ steps.pipaudit.outcome }}" != "success" ]]; then
+            echo "::warning::pip-audit vulnerability scan failed"
+          fi
+          echo "All checks passed!"
+
+      - name: Build wheel/sdist
+        shell: bash
+        run: uv build
+
+      - name: Verify wheel install in clean env
+        shell: bash
+        run: |
+          uv venv .venv_wheel
+          . .venv_wheel/bin/activate 2>/dev/null || . .venv_wheel/Scripts/activate 2>/dev/null
+          uv pip install dist/*.whl
+          "$CLI_BIN" --version 2>/dev/null || python -m "$PACKAGE_MODULE" --version
+
+      - name: Prune uv cache
+        continue-on-error: true
+        shell: bash
+        run: uv cache prune --ci
+
+      - name: Save ruff cache
+        if: always() && runner.environment == 'github-hosted' && steps.ruff-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v6
+        with:
+          path: .ruff_cache
+          key: ruff-${{ runner.os }}-py${{ matrix.python }}-${{ github.sha }}
+
+  pipx-uv:
+    name: pipx/uv verification (ubuntu)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Extract project metadata
+        id: metadata
+        uses: ./.github/actions/extract-metadata
+
+      - name: Build wheel
+        run: uv build
+      - name: pipx install from wheel
+        run: |
+          uv pip install --system pipx
+          pipx ensurepath
+          export PATH="$HOME/.local/bin:$PATH"
+          pipx install dist/*.whl
+          "$CLI_BIN" --version
+
+      - name: uv tool install
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"
+          uv tool install --force .
+          "$CLI_BIN" --version
+
+      - name: Prune uv cache
+        continue-on-error: true
+        run: uv cache prune --ci
+
+  notebooks:
+    name: Execute notebooks (ubuntu, Python 3.14)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          prune-cache: false
+
+      - name: Install notebook runner deps
+        run: |
+          uv pip install --system nbclient nbformat ipykernel jupyter_client
+          python -m ipykernel install --user --name python3 --display-name "Python 3"
+      - name: Execute Quickstart notebook
+        env:
+          PIP_DISABLE_PIP_VERSION_CHECK: "1"
+          PIP_NO_INPUT: "1"
+        run: |
+          python - << 'PY'
+          from pathlib import Path
+
+          import nbformat
+          from nbclient import NotebookClient
+
+          nb_path = Path('notebooks/Quickstart.ipynb')
+          if not nb_path.exists():
+              raise SystemExit(f"Notebook not found: {nb_path}")
+
+          notebook = nbformat.read(nb_path, as_version=4)
+          client = NotebookClient(
+              notebook,
+              timeout=900,
+              kernel_name='python3',
+              allow_errors=False,
+          )
+          client.execute()
+
+          out_path = Path('notebooks/Quickstart-executed.ipynb')
+          nbformat.write(notebook, out_path)
+          print(f"Executed notebook written to: {out_path}")
+          PY