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

{pytest_selective-0.1.1 → 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.1 → 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.1 → 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,11 +22,11 @@ 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:

{pytest_selective-0.1.1 → 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@v0.1
+    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.1 → pytest_selective-0.2.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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.

pytest_selective-0.2.0/CLAUDE.md

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

{pytest_selective-0.1.1 → pytest_selective-0.2.0}/CONTRIBUTING.md

@@ -61,3 +61,65 @@ 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.1 → pytest_selective-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pytest-selective
-Version: 0.1.1
+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
@@ -33,11 +33,6 @@ Description-Content-Type: text/markdown
 
 **Run affected Python tests. See why they matter.**
 
-Our [Windows critical-path experiment](docs/benchmarks/2026-10-23-windows-saleor.md)
-cut the full validation gate from **249s to 185s** against a fresh unchanged
-control, preserving every existing case, the full platform matrix and coverage.
-The report separates test execution from runner variation and includes raw evidence.
-
 [![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)
@@ -46,11 +41,6 @@ The report separates test execution from runner variation and includes raw evide
 [![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. Use it directly as a pytest
@@ -74,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:
@@ -154,7 +167,8 @@ complete requested suite. [Plugin configuration and limits](docs/local-developme
 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+, Git 2.24+, and uv**. Use a planner Python version at
+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.
@@ -190,8 +204,8 @@ For source development, GitHub installation is also available:
 pip install "pytest-selective @ git+https://github.com/gigaverse-app/pytest-selective.git"
 ```
 
-Use compatible package ranges and `@v0.1` Actions tags in CI; lockfiles retain
-exact resolved artifacts. 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.
 
@@ -219,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.
 
@@ -244,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.
@@ -280,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)

{pytest_selective-0.1.1 → pytest_selective-0.2.0}/README.md

@@ -2,11 +2,6 @@
 
 **Run affected Python tests. See why they matter.**
 
-Our [Windows critical-path experiment](docs/benchmarks/2026-10-23-windows-saleor.md)
-cut the full validation gate from **249s to 185s** against a fresh unchanged
-control, preserving every existing case, the full platform matrix and coverage.
-The report separates test execution from runner variation and includes raw evidence.
-
 [![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)
@@ -15,11 +10,6 @@ The report separates test execution from runner variation and includes raw evide
 [![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. Use it directly as a pytest
@@ -43,6 +33,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:
@@ -123,7 +136,8 @@ complete requested suite. [Plugin configuration and limits](docs/local-developme
 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+, Git 2.24+, and uv**. Use a planner Python version at
+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.
@@ -159,8 +173,8 @@ For source development, GitHub installation is also available:
 pip install "pytest-selective @ git+https://github.com/gigaverse-app/pytest-selective.git"
 ```
 
-Use compatible package ranges and `@v0.1` Actions tags in CI; lockfiles retain
-exact resolved artifacts. 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.
 
@@ -188,7 +202,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.
 
@@ -213,9 +227,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.
@@ -249,7 +263,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)