pytest-selective 0.1.0__tar.gz → 0.2.0__tar.gz

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/.github/dependabot.yml

@@ -2,6 +2,8 @@ version: 2
 updates:
   - package-ecosystem: github-actions
     directory: /
+    commit-message:
+      prefix: ci
     schedule:
       interval: weekly
     groups:
@@ -9,6 +11,8 @@ updates:
         patterns: ["*"]
   - package-ecosystem: uv
     directory: /
+    commit-message:
+      prefix: build
     schedule:
       interval: weekly
     groups:

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/.github/test-lanes.json

@@ -33,6 +33,10 @@
     ".github/test-lanes.json",
     ".github/workflows/ci.yml",
     ".github/workflows/release.yml",
-    ".github/actions/**"
+    ".github/actions/**",
+    "action.yml",
+    "*/action.yml",
+    "examples/**",
+    ".github/workflows/public-actions.yml"
   ]
 }

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/.github/workflows/ci.yml

@@ -3,7 +3,7 @@ on:
   push:
     branches: [main]
   pull_request:
-    types: [opened, synchronize, reopened, labeled, unlabeled]
+    types: [opened, synchronize, reopened]
   workflow_dispatch:
   workflow_call:
 permissions:
@@ -22,23 +22,23 @@ jobs:
         with:
           fetch-depth: 0
       - id: plan
-        uses: ./.github/actions/plan-lanes
+        uses: ./plan-lanes
         with:
           config: .github/test-lanes.json
           base: ${{ github.event.pull_request.base.sha || github.event.before }}
-          full: ${{ github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'test:full') }}
+          full: ${{ github.run_attempt > 1 || github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'test:full') }}
   quality:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@966f25c4fac4c64bf4ff9df0404321f91f882293
+      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
         with:
           python-version: '3.14'
       - run: uv run --locked pre-commit run --all-files
       - name: Check aggregate gate against the execution lanes
         run: >-
           uv run --no-project --python 3.14
-          --with "ci-esta @ https://github.com/gigaverse-app/ci-esta/archive/966f25c4fac4c64bf4ff9df0404321f91f882293.tar.gz"
+          --with "ci-esta>=0.1.0,<0.2.0"
           ci-esta check-workflow --workflow .github/workflows/ci.yml --lanes .github/test-lanes.json
       - name: Validate routing even when the platform matrix is skipped
         run: uv run --locked pytest -q tests/test_repository_ci.py
@@ -57,15 +57,20 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@966f25c4fac4c64bf4ff9df0404321f91f882293
+      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
         with:
           python-version: ${{ matrix.python }}
       - name: Use native Git for Windows
-        uses: gigaverse-app/ci-esta/.github/actions/native-windows-git@966f25c4fac4c64bf4ff9df0404321f91f882293
+        uses: gigaverse-app/ci-esta/.github/actions/native-windows-git@v0.1
       - name: Record coverage runtime
         run: uv run --locked python -m coverage --version
       - run: uv run --locked pytest -q -n 4 --durations=20 --junitxml=test-timings.xml --cov --cov-report=term-missing --cov-report=xml
-      - uses: gigaverse-app/ci-esta/.github/actions/learn-test-timings@966f25c4fac4c64bf4ff9df0404321f91f882293
+        env:
+          # Keep temporary Git repositories beside the checkout on the work disk.
+          TMP: ${{ runner.temp }}
+          TEMP: ${{ runner.temp }}
+          TMPDIR: ${{ runner.temp }}
+      - uses: gigaverse-app/ci-esta/.github/actions/learn-test-timings@v0.1
         with:
           junit-pattern: test-timings.xml
           artifact-name: test-timings-${{ matrix.python }}-${{ matrix.os }}
@@ -84,7 +89,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@966f25c4fac4c64bf4ff9df0404321f91f882293
+      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
         with:
           python-version: '3.11'
       - run: uv pip install 'pytest==8.0.0'
@@ -93,7 +98,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@966f25c4fac4c64bf4ff9df0404321f91f882293
+      - uses: gigaverse-app/ci-esta/.github/actions/setup-cached-uv@v0.1
         with:
           python-version: '3.14'
       - run: uv build
@@ -112,7 +117,7 @@ jobs:
     if: ${{ !cancelled() }}
     runs-on: ubuntu-latest
     steps:
-      - uses: gigaverse-app/ci-esta/.github/actions/validation-gate@966f25c4fac4c64bf4ff9df0404321f91f882293
+      - uses: gigaverse-app/ci-esta/.github/actions/validation-gate@v0.1
         with:
           needs: ${{ toJSON(needs) }}
           lanes: ${{ needs.select-tests.outputs.lanes || '{}' }}

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/.github/workflows/observe-ci.yml

@@ -13,7 +13,7 @@ permissions:
 
 jobs:
   report:
-    uses: gigaverse-app/ci-esta/.github/workflows/report.yml@966f25c4fac4c64bf4ff9df0404321f91f882293
+    uses: gigaverse-app/ci-esta/.github/workflows/report.yml@v0.3.0
     with:
       run-id: ${{ github.event.workflow_run.id }}
       run-attempt: ${{ github.event.workflow_run.run_attempt }}

pytest_selective-0.2.0/.github/workflows/pr-title.yml

@@ -0,0 +1,45 @@
+name: PR title
+
+# Squash merges use this checked title as the Conventional Commit header.
+on:
+  pull_request_target:
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+
+permissions:
+  pull-requests: read
+
+jobs:
+  conventional-commit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # Only reads PR metadata. Never check out or execute PR code in this workflow.
+      - uses: amannn/action-semantic-pull-request@48f256284bd46cdaab1048c3721360e808335d50 # v6.1.1
+        with:
+          types: |
+            feat
+            fix
+            perf
+            revert
+            docs
+            style
+            refactor
+            test
+            build
+            ci
+            chore
+          requireScope: false
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+      - name: Explain how to repair the title
+        if: failure()
+        run: |
+          cat >> "$GITHUB_STEP_SUMMARY" <<'EOF'
+          Rename the PR to `type(optional-scope): description`, for example
+          `fix(parser): handle empty input` or `docs: clarify installation`.
+          Use `!` before the colon for a breaking change, for example
+          `feat(api)!: remove the deprecated argument`.
+          Choose the type that describes the change; do not hide features or fixes under `chore:`.
+          Editing the PR title reruns this check. No commit rewrite or replacement PR is needed.
+          If the title is already valid, inspect the action log for an API or runner failure.
+          EOF

pytest_selective-0.2.0/.github/workflows/public-actions.yml

@@ -0,0 +1,54 @@
+name: Public action smoke
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  public-actions:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+      - name: Use the reviewed repository graph
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          graph = json.loads(Path('.github/test-lanes.json').read_text())['graph']
+          Path('smoke-impact.json').write_text(json.dumps(graph))
+          PY
+      - uses: ./
+        id: impact
+        with:
+          config: smoke-impact.json
+          base: ${{ github.sha }}
+          full: 'true'
+          full-roots: tests
+          max-shards: '2'
+          explanation-artifact: ''
+      - name: Verify forwarded file-plan outputs
+        env:
+          MODE: ${{ steps.impact.outputs.mode }}
+          ROOTS: ${{ steps.impact.outputs.test_roots }}
+        run: |
+          test "$MODE" = full
+          test -n "$ROOTS"
+      - uses: ./plan-lanes
+        id: lanes
+        with:
+          config: .github/test-lanes.json
+          base: ${{ github.sha }}
+          full: 'true'
+          artifact-name: ''
+      - name: Verify forwarded lane outputs
+        env:
+          LANES: ${{ steps.lanes.outputs.lanes }}
+        run: |
+          python - <<'PY'
+          import json, os
+          assert json.loads(os.environ['LANES']) == {'tests': True}
+          PY

pytest_selective-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,54 @@
+name: Release Please
+
+# Release PRs accumulate changes; merging one is the publishing decision.
+on:
+  workflow_run:
+    workflows: [CI]
+    branches: [main]
+    types: [completed]
+
+permissions: {}
+
+concurrency:
+  group: release-please
+  cancel-in-progress: false
+
+jobs:
+  release-please:
+    if: >-
+      github.event.workflow_run.event == 'push'
+      && github.event.workflow_run.conclusion == 'success'
+      && github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    environment: release-automation
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Only process the tested main head
+        id: current
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          script: |
+            const {data: branch} = await github.rest.repos.getBranch({...context.repo, branch: 'main'});
+            core.setOutput('matches', branch.commit.sha === context.payload.workflow_run.head_sha);
+      - name: Require release bot authentication
+        if: steps.current.outputs.matches == 'true'
+        env:
+          HAS_RELEASE_TOKEN: ${{ secrets.GV_CI_CROSS_REPO_TOKEN != '' }}
+        run: |
+          if [[ "$HAS_RELEASE_TOKEN" != "true" ]]; then
+            echo "::error::Share the organization GV_CI_CROSS_REPO_TOKEN secret with this repository."
+            exit 1
+          fi
+      - name: Prepare release PR or publish its GitHub release
+        if: steps.current.outputs.matches == 'true'
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
+        with:
+          # This credential triggers CI on release PRs and Publish on releases.
+          # GITHUB_TOKEN would suppress those follow-up workflow events.
+          token: ${{ secrets.GV_CI_CROSS_REPO_TOKEN }}
+          target-branch: main
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json

pytest_selective-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

pytest_selective-0.2.0/AGENTS.md

@@ -0,0 +1,58 @@
+# Working on pytest-selective
+
+For adopting the tool in another repository, use
+[the portable skill](skills/pytest-selective/SKILL.md). This file describes work
+on pytest-selective itself.
+
+- Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup and validation. Use the locked
+  environment: `uv sync --locked`, `uv run pre-commit run --all-files`,
+  `uv run pytest -q -n 4`. For packaging changes also build, run strict Twine,
+  `scripts/check_metadata.py` and `scripts/smoke_distribution.py`.
+- Reproduce selection bugs using real temporary Git repositories and existing
+  `tests/testing/git_repo.py` helpers. Cover base and head trees, deleted inputs,
+  explicit declarations and the relevant fallback. Do not mock away selection.
+- Planning supports committed revisions and explicit working-tree snapshots. Preserve full execution on
+  operational uncertainty and diagnostics for invalid declarations. An empty
+  selection is not an empty pytest argument list.
+- Keep consumer routing regressions in the always-running quality job. Update
+  `.github/test-lanes.json` when adding execution inputs; preserve full main/manual
+  checkpoints and the `test:full` override.
+- The README's performance numbers are scenario-specific observations. Keep
+  claims linked to [raw evidence](docs/benchmarks/2026-10-22-routing.md); distinguish
+  runner-seconds, elapsed time and billing. Skill/example edits need usable links
+  and verified commands, not tests that merely assert prose wording.
+
+## Commits and pull requests
+
+- Use Conventional Commits for commits you create and PR titles:
+  `type(optional-scope): description`, for example
+  `fix(parser): handle empty input`.
+- Allowed types: `feat`, `fix`, `perf`, `revert`, `docs`, `style`,
+  `refactor`, `test`, `build`, `ci`, and `chore`. Choose the type for the
+  actual change. Mark breaking changes with `!` before the colon and explain
+  the migration in the PR body.
+- Repair an invalid PR title in place. Preserve useful work; do not close or
+  replace the PR, or rewrite existing commits just to satisfy the title check.
+- Squash merges use the checked PR title. Keep any `BREAKING CHANGE:` details
+  in the body. Follow [CONTRIBUTING.md](CONTRIBUTING.md) and
+  [RELEASING.md](RELEASING.md).
+
+## Releases
+
+Release Please derives versions and changelogs from Conventional Commits. Let
+it prepare the release PR; do not hand-edit versions for ordinary changes.
+Merging a release PR authorizes PyPI publication after CI. Follow RELEASING.md.
+
+## Shared agent instructions
+
+Edit this root `AGENTS.md` as the single source for Codex and Claude.
+`CLAUDE.md` is an AgentSync-managed relative symlink to this file, not a
+separate instruction document. The configuration is
+[agentsync.toml](agentsync.toml). To restore and verify the link:
+
+```bash
+npx --yes @dallay/agentsync@1.52.3 apply
+npx --yes @dallay/agentsync@1.52.3 status
+```
+
+Keep the symlink tracked in Git. See CONTRIBUTING.md for platform setup.

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.2.0](https://github.com/gigaverse-app/pytest-selective/compare/v0.1.1...v0.2.0) (2026-10-23)
+
+
+### Features
+
+* add public action entry points and task-focused onboarding ([#41](https://github.com/gigaverse-app/pytest-selective/issues/41)) ([94da1e6](https://github.com/gigaverse-app/pytest-selective/commit/94da1e6d4088d9ded93ce491dc88993ac140e0ea))
+
+
+### Bug fixes
+
+* **selection:** preserve plugin sessions and accelerate graph construction ([#42](https://github.com/gigaverse-app/pytest-selective/issues/42)) ([2994c88](https://github.com/gigaverse-app/pytest-selective/commit/2994c887d916a965b78f5ff8d48476abed705e37))
+
+## 0.1.1 (2026-10-23)
+
+- Register a native pytest plugin: `pytest --selective`, ini defaults, optional existing impact JSON, an exact comparison base, and `--no-selective` for full execution.
+- Reuse the existing working-tree snapshots and dependency planner; share one plan with xdist workers and preserve unknown collectors, doctests, normal pytest filtering and failure statuses.
+- Install pytest as a runtime dependency; retain the audit extra and all CLI/CI interfaces.
+
 ## 0.1.0 (2026-10-23)
 
 First PyPI release.

pytest_selective-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

pytest_selective-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to pytest-selective
+
+Use Python 3.11+, Git 2.24+, and uv. The planner operates on immutable Git trees;
+tests should exercise real temporary repositories through the existing helpers
+in `tests/testing/git_repo.py`.
+
+```bash
+uv sync --locked
+uv run pre-commit install
+uv run pre-commit run --all-files
+uv run pytest -q --cov --cov-report=term-missing
+uv run python scripts/tutorial.py
+uv build
+uv run twine check --strict dist/*
+uv run python scripts/smoke_distribution.py
+```
+
+Ruff lint and formatting use the versions in `uv.lock`, both locally and in CI.
+Hooks fix repairable lint and formatting issues; review and stage their edits.
+The Markdown hook checks local file links. It does not check external URLs or
+heading anchors. Tests run separately so normal commits stay quick.
+
+## Preserve selection safety
+
+For a bug, first add a failing regression using an actual Git change. Assert the
+selected paths and observable outcome. Include base and head behavior, invalid
+inputs, and fallback handling when relevant. Prefer existing helpers over mocks
+of Git or the selector. Do not weaken selection or add broad ignores to hide a
+failure. Keep root conftests small: every importer inherits their dependencies.
+
+Changes to collection policy, runtime auditing, or the composite action need tests
+at that boundary. Update the tutorial when the public command contract changes.
+Keep performance claims tied to reproducible measurements and their limitations.
+
+## CI and dependency maintenance
+
+CI tests Python 3.11 and 3.14 on Linux, Windows, and macOS. A separate job checks
+pytest 8.0.0 on Python 3.11, the plugin's lower bound. It also checks hooks, builds both distribution
+formats, validates PyPI metadata, and installs each distribution in an isolated
+environment on both Python versions. Evidence artifacts carry coverage and tutorial output on every platform and Python version.
+
+Use `uv lock --upgrade-package NAME` for a targeted dependency update and run the
+affected checks. Dependabot proposes weekly uv and GitHub Actions updates.
+Actions are pinned to commits. Review their release notes before updating pins.
+
+## Pull requests
+
+Explain the user-visible problem and the resulting behavior. Include the exact
+validation commands, measured evidence where applicable, and any remaining
+limitations. The pull request template provides a short checklist. See
+[RELEASING.md](RELEASING.md) for package publication.
+
+
+## CI lane selection
+
+This repository uses its own `plan-lanes` action. Documentation-only PRs keep
+quality checks (including Markdown links) and distribution build/install checks,
+while skipping the six-platform pytest matrix and minimum-pytest lane. Source,
+tests, scripts, dependency/pytest policy and workflow changes run the complete
+matrix. Main, manual/called runs and the `test:full` label run it in full; a
+failed planner also runs all tests. Repository routing controls exercise the
+committed config against real Git trees, including full and missing-history
+controls. Add new non-import execution inputs to `.github/test-lanes.json`.
+
+## Conventional Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+for commits you create and PR titles (the squash commit that lands on `main`):
+
+```text
+fix(parser): handle empty input
+feat: add a new output format
+feat(api)!: remove the deprecated argument
+docs: clarify installation
+```
+
+Allowed types are `feat`, `fix`, `perf`, `revert`, `docs`, `style`,
+`refactor`, `test`, `build`, `ci`, and `chore`. Scope is optional.
+Use `!` before the colon for breaking changes and explain the migration in the
+PR body. Choose the type for the actual change, since release tooling uses it.
+
+The `conventional-commit` check uses
+[amannn/action-semantic-pull-request](https://github.com/amannn/action-semantic-pull-request).
+It reads PR metadata, including for forks, without checking out contributor code.
+If it fails on a title, rename the PR; the edited event reruns the check.
+Keep the existing PR and commits. Work-in-progress commits need not be rewritten.
+
+Use **Squash and merge**, with the PR title as the commit title. Check the final
+message before merging, including single-commit PRs, and preserve any
+`BREAKING CHANGE:` explanation in the body. The repository's squash defaults
+support this, but a maintainer can still edit the final message.
+Release Please turns these commits into a release PR containing the version,
+changelog, and lockfile update. Merging that PR authorizes PyPI publication after
+CI. See [RELEASING.md](RELEASING.md) for the version rules and publishing.
+
+## Shared instructions for Codex and Claude
+
+[AGENTS.md](AGENTS.md) is the canonical repository guidance. Codex reads it
+directly; Claude reads the tracked `CLAUDE.md -> AGENTS.md` symlink. Edit
+`AGENTS.md` once, including commit-policy changes, so both tools receive the
+same instructions.
+
+[dallay/agentsync](https://github.com/dallay/agentsync) manages that link through
+[agentsync.toml](agentsync.toml). After cloning, or to repair a
+missing or stale link, run these commands from the repository root with Node.js
+18+ and npm installed:
+
+```bash
+npx --yes @dallay/agentsync@1.52.3 apply
+npx --yes @dallay/agentsync@1.52.3 status
+```
+
+The CLI version is pinned for reproducible setup. Review and update both commands
+when upgrading AgentSync. The configuration disables managed gitignore changes
+because we intentionally commit the relative link, following AgentSync's
+[committed-destination workflow](https://dallay.github.io/agentsync/guides/gitignore-team-workflows/).
+Ordinary instruction edits propagate immediately through the link.
+
+On native Windows, enable Developer Mode and Git symlink support
+(`git config core.symlinks true`), then run `apply` to repair a checkout that
+materialized the link as plain text. Alternatively, use WSL for a checkout in
+the Linux filesystem. See the
+[Windows setup guide](https://dallay.github.io/agentsync/guides/windows-symlink-setup/).
+If AgentSync backs up an existing `CLAUDE.md`, review and preserve any unique
+guidance in `AGENTS.md`; do not commit the backup as another instruction source.

{pytest_selective-0.1.0 → pytest_selective-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 0.1.0
+Version: 0.2.0
 Summary: Explainable Python test impact analysis: select affected pytest files from Git changes
 Project-URL: Homepage, https://github.com/gigaverse-app/pytest-selective
 Project-URL: Documentation, https://github.com/gigaverse-app/pytest-selective/blob/main/docs/README.md
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pytest>=8
 Requires-Dist: pyyaml<7,>=6
 Provides-Extra: audit
 Requires-Dist: pytest>=8; extra == 'audit'
@@ -33,21 +34,17 @@ Description-Content-Type: text/markdown
 **Run affected Python tests. See why they matter.**
 
 [![CI](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/gigaverse-app/pytest-selective/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pytest-selective)](https://pypi.org/project/pytest-selective/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://github.com/gigaverse-app/pytest-selective/blob/main/pyproject.toml)
 [![Typed](https://img.shields.io/badge/typing-py.typed-3776AB)](https://github.com/gigaverse-app/pytest-selective/blob/main/src/pytest_selective/py.typed)
 [![Ruff](https://img.shields.io/badge/code%20style-Ruff-D7FF64?logo=ruff&logoColor=black)](https://github.com/gigaverse-app/pytest-selective/blob/main/.pre-commit-config.yaml)
 [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/gigaverse-app/pytest-selective/blob/main/LICENSE)
 [![Agent skill](https://img.shields.io/badge/Agent_Skill-ready-2563EB)](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/agents.md)
 
-**Our README CI used 92.3% less runner time: 627s → 48s.** Elapsed time fell
-from 211s to 26s, with docs, routing and package checks preserved. One successful
-same-revision pair, not a universal speedup.
-[Inspect the runs and raw evidence](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/benchmarks/2026-10-22-routing.md).
-
 pytest-selective is a **Python test impact analysis** tool for incremental testing
 with pytest. It follows dependencies through both sides of a Git change, selects
-the affected test files, and explains the result. Plan before collecting tests,
-importing your application, or starting databases and workers.
+the affected test files, and explains the result. Use it directly as a pytest
+plugin, or plan before collection and service startup with the CLI and CI actions.
 
 Built from the selector used in Gigaverse's backend, AI, and shared Python
 infrastructure. The API may change before 1.0.
@@ -67,6 +64,29 @@ used **49 instead of 105 runner-seconds (53.3% less)** while keeping quality,
 routing and package checks. Its reports now compute dependency critical paths
 and slack. [See the source runs and method](https://github.com/gigaverse-app/ci-esta/blob/main/docs/benchmarks/2026-10-23-toolkit.md).
 
+## Choose how to use it
+
+| You want to… | Use | What it saves |
+| --- | --- | --- |
+| Test local edits with your existing pytest command | `uv add --dev pytest-selective`, then `uv run pytest --selective` | Unaffected test execution; staged, unstaged and untracked changes are included |
+| Avoid expensive collection and application imports | `pytest-selective run --config .github/test-impact.json -- -q` | Collection/imports for unaffected files as well as execution |
+| Plan affected files in GitHub Actions | `gigaverse-app/pytest-selective@main` | Plans before installing your application |
+| Keep whole-suite coverage or conformance checks | `gigaverse-app/pytest-selective/plan-lanes@main` | Entire unaffected jobs, including their services and setup |
+| Check assumptions about JSON, templates and other runtime inputs | Optional file-read recorder and dependency audit | Exposes observed reads missing from the declared graph |
+| Keep selection narrow as the project grows | Explanations, startup-floor budgets, expansion and isolation guards | Makes broad new fixture/import dependencies visible |
+
+Start with [local pytest](docs/local-development.md), [the complete CI recipe](docs/ci.md),
+or [dependency audits and hygiene](docs/selection-health.md). The native plugin
+collects normally; the pre-collection runner and CI planner can avoid that cost.
+Keep full checkpoints and use complete lanes when partial suites cannot satisfy
+your coverage contract.
+
+**Public-path availability:** root and short action paths are new on `main`;
+existing `v0.1` releases predate them. Evaluate with `@main`, or pin a reviewed
+commit containing the public `action.yml`. Adopt a compatible release tag after
+it includes these paths. Existing `.github/actions/...` paths remain supported.
+[Public action API](docs/actions.md).
+
 ## Have your agent set it up
 
 Paste this into your coding agent in the Python project you want to improve:
@@ -128,7 +148,27 @@ including Due's widget benchmark, which selection skips entirely.
 
 ## Try it in two minutes
 
-Requires **Python 3.11+, Git 2.24+, and uv**. Use a planner Python version at
+Install the plugin in your test environment, then use ordinary pytest:
+
+```bash
+uv add --dev pytest-selective
+uv run pytest --selective
+uv run pytest --selective --selective-base origin/main -n auto
+uv run pytest --no-selective
+```
+
+Selection is opt-in. The default compares HEAD with staged, unstaged and
+nonignored untracked files. `--selective-base` compares against the exact ref
+you supply, including local edits. The plugin reuses the CLI's dependency graph,
+deselects unaffected collected tests, and keeps doctests and unknown collectors.
+Normal test paths, node IDs, `-k` and `-m` still apply. Missing history runs the
+complete requested suite. [Plugin configuration and limits](docs/local-development.md).
+
+For pre-collection selection, use `pytest-selective run`; for CI jobs with
+expensive setup or whole-suite evidence requirements, use lane selection.
+
+Requires **Python 3.11+ and Git 2.24+**. The examples use uv; the native plugin
+also works in your existing pytest environment. Use a planner Python version at
 least as new as your source syntax; the CI action uses Python 3.14. Your test
 runtime can use a different Python version when planning runs separately.
 The optional audit recorder requires Python 3.11+ in the test environment.
@@ -152,13 +192,20 @@ hold. It uses a temporary repository and leaves your checkout untouched.
 
 ## Install in your project
 
-Until the first PyPI release, install from GitHub using Python 3.11+:
+Install from PyPI using Python 3.11+:
+
+```bash
+pip install "pytest-selective>=0.1.0,<0.2.0"
+```
+
+For source development, GitHub installation is also available:
 
 ```bash
 pip install "pytest-selective @ git+https://github.com/gigaverse-app/pytest-selective.git"
 ```
 
-Pin a reviewed commit in CI. Then follow the
+Use compatible package ranges; lockfiles retain exact resolved artifacts.
+For action-path availability and release pins, see [the action API](docs/actions.md). Then follow the
 [configuration walkthrough](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/configuration.md)
 to declare module roots, test roots, collection-policy fingerprints, and non-Python inputs.
 
@@ -168,7 +215,8 @@ pytest-selective affected --config .github/test-impact.json \
   --explanation-output explanation.json
 ```
 
-Planning reads **committed Git trees**. Uncommitted edits are outside the plan.
+`affected` reads **committed Git trees** by default. Use `affected --working-tree`
+or `pytest-selective run` to include uncommitted edits.
 The report distinguishes `scoped`, `full`, and `none`; an empty selection must
 skip pytest, because invoking pytest without paths runs the whole suite.
 
@@ -185,7 +233,7 @@ skip pytest, because invoking pytest without paths runs the whole suite.
 | Undeclared runtime reads | An opt-in pytest recorder and audit command |
 
 The CLI emits JSON for your runner. The
-[composite action](https://github.com/gigaverse-app/pytest-selective/blob/main/.github/actions/test-impact/action.yml)
+[composite action](https://github.com/gigaverse-app/pytest-selective/blob/main/test-impact/action.yml)
 adds caching and falls back to complete test roots on operational planning
 failures. Invalid dependency declarations fail with a diagnostic that must be fixed.
 
@@ -210,9 +258,9 @@ and evidence checks.
 ## Choose the right tool
 
 [pytest-impacted](https://github.com/promptromp/pytest-impacted) offers a pytest-native
-`--impacted` workflow, including working-tree changes. pytest-selective focuses on
-committed revisions, inspectable JSON plans, runtime dependency audits, and
-planning before application startup. Both use static dependency analysis; choose
+`--impacted` workflow, including working-tree changes. pytest-selective supports the same local edit/test loop and also offers
+inspectable JSON plans, runtime dependency audits, and planning before application
+startup. Both use static dependency analysis; choose
 based on your workflow, and validate selection against your own suite.
 See the [lessons from pytest-impacted](https://github.com/gigaverse-app/pytest-selective/blob/main/docs/pytest-impacted.md)
 for portability and Git-resolution improvements adopted from that comparison.
@@ -246,7 +294,7 @@ optional; pytest-selective does not depend on it.</sub>
 
 See the [CI toolkit integration](docs/ci-toolkit.md) for lane selection, validated
 environment caches, required gates and real dependency critical-path reports.
-# Optimize the work that still has to run
+## Optimize the work that still has to run
 
 Selection and execution solve different parts of slow CI. Once selection keeps
 the required tests, use [CI-esta's critical-path report](https://github.com/gigaverse-app/ci-esta/blob/main/docs/critical-path-optimizations.md)