python-mcp-bootstrap 0.1.3__tar.gz

python_mcp_bootstrap-0.1.3/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+.venv/
+.venv.previous*/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.pip-cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Bootstrap-local artifacts
+.uv-cache/
+.uv-python/
+UV-CACHE/
+UV-PYTHON/
+
+# Example app first-run artifacts
+/examples/.python-version
+/examples/_vendor/
+
+# Secrets and local env
+.env
+.env.*
+!.env.example
+*.pem
+
+# Editor and OS
+.DS_Store
+.idea/
+.vscode/
+*.swp

python_mcp_bootstrap-0.1.3/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+## 0.1.3 — 2026-11-04
+
+- Restore the single handoff that 0.1.2 removed. 0.1.2 stopped exec'ing on the
+  good-running path entirely, so a wrapper that branched on `spec.env_var` and
+  skipped `bootstrap()` after the handoff failed with `missing_continuation`
+  (exit `7`) on any machine whose first run was already on a supported
+  interpreter. It worked on machines that had to provision, which made the
+  failure depend on the host.
+- The good-running path execs once when no handoff has been recorded, setting
+  `spec.env_var`; a later pass with that variable set and no continuation still
+  reports `missing_continuation` (exit `7`). The loop stays dead, and the
+  documented handoff signal works again.
+- Correct the migration advice in the v0.1.2 release notes, which claimed
+  env-var branches were unaffected.
+- Remove `CODE_OF_CONDUCT.md`: single maintainer, no community to govern yet;
+  `CONTRIBUTING.md` covers the checks a change must pass. Fix the issue template
+  front matter to use strings rather than empty YAML sequences.
+- Drop the hand-maintained version line from the README; the tag is the source
+  of truth.
+
+## 0.1.2 — 2026-11-04
+
+- Fix an infinite re-exec: when the running interpreter already met the floor
+  and neither `main_fn` nor `spec.package_main` was configured, `bootstrap()`
+  exec'd the same entry point on the same interpreter with the same arguments,
+  forever. That branch now returns a `missing_continuation` report (exit `7`,
+  new) and execs nothing. Reports carry `env_var` and `handed_off` so a
+  consumer can tell a first pass from a re-entry.
+- `docs/contract.md` documents exit `7` and states the no-self-exec property;
+  `README.md` and `docs/integration.md` now say a continuation is required for
+  an entry point that always calls `bootstrap()`. Consumers that check
+  `spec.env_var` themselves keep working unchanged.
+- Consent card: "private Python" became "project-local Python", which is what
+  it always meant.
+- `SECURITY.md` points at GitHub private vulnerability reporting instead of
+  "the repository owner".
+- Package metadata names a maintainer, and the README states that distribution
+  is GitHub Releases only (the project is not on PyPI).
+
+## 0.1.1 — 2026-11-04
+
+- Fix the tag-run CI failure on every matrix cell and on the wheel/release
+  gate: `actions/checkout@v4` fetches the annotated release tag, then
+  re-fetches the commit as `refs/tags/<tag>`, replacing the tag object with a
+  lightweight ref to the same commit. `release_check.py` correctly reported
+  `tag '<tag>' is not annotated`. The jobs that run the suite or the release
+  gate now restore the annotated ref after checkout and assert its object
+  type. The annotated-tag requirement itself is unchanged.
+- The local matching-tag test skips with a clear reason when the tag is absent
+  or not an annotated object, so a checkout artifact cannot mask the real
+  gate.
+- Library behaviour is unchanged from 0.1.0.
+
+## 0.1.0 — 2026-11-04
+
+- Initial release of the shared pre-install Python bootstrap for MCP
+  applications.
+- `BootstrapSpec`, version parsing, platform-aware venv paths, and uv
+  discovery in a single stdlib-only `core.py` that stays importable on
+  Python 3.12.
+- Selection order (`--python`, the running interpreter, an existing `.venv`,
+  then the consent card), explicit `--install-python` consent before any
+  download, project-local provisioning, install verification, atomic pin
+  writes, and exec handoff.
+- Windows-aware handoff and uv discovery, managed-only interpreter selection,
+  project-path validation, `--` argument handling, and credential-redacted
+  diagnostics.
+- `install_args` reject path-like entries (absolute, Windows-rooted, and `..`,
+  including attached short forms) and venv-redirecting flags (`--target`,
+  `--prefix`, `--root`, `--python`); non-path flags such as `--index-url`
+  pass through.
+- `pin` is a plain `X[.Y[.Z]]` final version at or above `required`, so
+  `.post` and `+local` strings and pre-releases fail before any download.
+- A broken or mismatched `.venv` is moved aside, never deleted, and
+  `verify_import` runs isolated (`-I -P`).
+- Vendor tooling (`scripts/vendor.py`) with `VENDOR.json` manifests and a
+  `--check` drift test, plus the vendored example first run in CI.
+- `scripts/release_check.py` validates metadata, the changelog, release notes,
+  the Python pin, tracked-file hygiene, annotated tags, and published release
+  assets.
+- CI on Python 3.14.10 and 3.15.2 on Ubuntu, macOS, and Windows, plus a 3.12
+  compatibility job, a wheel/release gate, and the vendored example first run.
+- Development pin 3.15.2 and MIT license.
+- Honest limits: path checks are lexical (symlinks are not resolved), and
+  concurrent first runs against one project are unsupported.

python_mcp_bootstrap-0.1.3/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing
+
+## Setup
+
+The development pin is Python 3.15.2. The package floor is 3.14.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+```
+
+## Checks
+
+Run all four before proposing a change:
+
+```bash
+python -m pytest --cov=python_mcp_bootstrap --cov-fail-under=90
+python -m ruff format --check
+python -m ruff check
+python -m mypy
+```
+
+Build the distribution as a final packaging check:
+
+```bash
+python -m build
+```
+
+Exercise the vendored consumer path as CI does:
+
+```bash
+python scripts/vendor.py --target examples --dest _vendor/python_mcp_bootstrap.py
+python scripts/vendor.py --target examples --dest _vendor/python_mcp_bootstrap.py --check
+```
+
+## CI status
+
+CI is advisory for now: there is no branch protection and there are no
+required status checks. Check the matrix before merging; a pending cell is not
+green. A green tag run is the strongest evidence for a release.
+
+## Rules
+
+- `src/python_mcp_bootstrap/core.py` stays stdlib-only.
+- `core.py` must remain importable and runnable on Python 3.12; CI runs the
+  suite on 3.12 as well as on the 3.14 and 3.15 matrix.
+- Never import `mcp` from the bootstrap path.
+- Never add an install, download, or provisioning subprocess before explicit
+  consent. Version probes and the isolated import check may run before consent.
+- Never use `shell=True`.
+- Keep machine-specific paths, credentials, and private labels out of tracked
+  files.
+
+## Release
+
+Before tagging, from the commit that will be tagged:
+
+```bash
+python scripts/release_check.py
+python -m pytest --cov=python_mcp_bootstrap --cov-fail-under=90
+python -m build
+```
+
+Rebuild `dist/` from that tip (`dist/` is gitignored), regenerate
+`dist/SHA256SUMS` for the wheel and sdist, and verify the wheel in a clean
+environment before attaching them:
+
+```bash
+python -m venv /tmp/wheel-check
+/tmp/wheel-check/bin/python -m pip install dist/*.whl
+/tmp/wheel-check/bin/python -m python_mcp_bootstrap --check
+```
+
+Tag with an annotated tag, push it, and attach the wheel and sdist to the
+GitHub release:
+
+```bash
+git tag -a v<version> -m "python-mcp-bootstrap v<version>"
+git push origin v<version>
+python scripts/release_check.py --tag v<version>
+```
+
+Use annotated tags for releases. CI’s package job fails a tag/version mismatch
+and a lightweight tag when the tag is present; the `release-gate` workflow
+verifies the published release’s wheel, sdist, and `SHA256SUMS` assets. The
+release notes live in `docs/releases/`. Tags are unsigned for now; do not
+present a tag as a signature.
+
+## Scope
+
+The core owns interpreter selection, consent, provisioning, verification, and
+handoff. MCP server behavior and consumer-specific install steps belong in the
+consumer repositories.

python_mcp_bootstrap-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 python-mcp-bootstrap contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_mcp_bootstrap-0.1.3/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.5
+Name: python-mcp-bootstrap
+Version: 0.1.3
+Summary: Pre-install Python runtime bootstrap for MCP applications.
+Project-URL: Repository, https://github.com/4zhmv6zvj2-afk/python-mcp-bootstrap
+Author-email: Ron <4zhmv6zvj2-afk@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bootstrap,mcp,python,runtime,uv
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# python-mcp-bootstrap
+
+A small setup helper for Python apps that use MCP.
+
+MCP (Model Context Protocol) is a way for AI assistants to use tools and data.
+Before one of those apps starts, this helper makes sure it runs on a supported
+version of Python. If your computer does not have one, it explains what is
+missing and asks before downloading anything. It never changes the Python that
+is already installed.
+
+This is a bootstrap *for* MCP applications, not an MCP implementation. It has
+no runtime dependency on the MCP SDK and never imports one.
+
+**Most people do not need to run this directly.** The app's setup script uses
+it. If you are a developer adding it to an app, jump to
+[For developers](#for-developers).
+
+
+## Do I need this?
+
+- If an app's setup tells you to run `python first_run.py`, that script uses
+  this helper. Follow the app's instructions.
+- If you are building or packaging an MCP app and need a first-run Python
+  check, use this library.
+- If you just want to run an app that is already set up, no.
+
+## What it does
+
+1. Looks for Python 3.14 or newer.
+2. Looks for a working `.venv` in the project.
+3. If the Python or the app environment is missing or incomplete, prints a
+   JSON report with a `card` and a `next` command. Nothing is downloaded.
+4. If you agree, the wrapper re-runs with `--install-python`, which installs
+   what is missing inside the project.
+5. Continues setup with that Python.
+
+It can also check a Python you name:
+
+```bash
+python first_run.py --python /path/to/python
+```
+
+## What it will not do
+
+- It will not download Python without `--install-python`.
+- It will not change your system Python or system packages.
+- It will not delete an existing `.venv`; a wrong one is moved aside.
+- It will not run `curl | sh`. If `uv` is missing, it prints a tip with the
+  official uv installation page and stops. It never runs that tip.
+- It will not run commands through a shell.
+- It masks credential-shaped values in its reports and captured output.
+
+## For developers
+
+This repository is a library, not the app. The command-line tool is a
+diagnostic:
+
+```bash
+python -m python_mcp_bootstrap --check
+python -m python_mcp_bootstrap --version
+```
+
+Distribution is GitHub Releases only: install the wheel or sdist from the
+[releases page](https://github.com/4zhmv6zvj2-afk/python-mcp-bootstrap/releases).
+This project is **not published on PyPI**, so `pip install python-mcp-bootstrap`
+does not resolve.
+
+Use `BootstrapSpec` and `bootstrap()` from an app's first-run wrapper:
+
+```python
+import sys
+from pathlib import Path
+
+from python_mcp_bootstrap import BootstrapSpec, bootstrap
+
+
+def continue_setup(args: list[str]) -> int:
+    # The rest of setup goes here.
+    del args
+    return 0
+
+
+root = Path(__file__).resolve().parent
+spec = BootstrapSpec(
+    app="example-mcp",
+    entrypoint="first_run.py",
+    env_var="EXAMPLE_MCP_INTERPRETER",
+    install_args=("-e", "."),
+    verify_import="example_mcp",
+    package_main=continue_setup,
+)
+raise SystemExit(bootstrap(sys.argv[1:], root, spec))
+```
+
+`package_main` is the function `bootstrap()` calls when the current Python is
+already suitable. Pass it: an entry point that calls `bootstrap()`
+unconditionally needs somewhere to continue.
+
+The first pass may hand off once, and it records the chosen interpreter in
+`spec.env_var`. A later pass that reaches `bootstrap()` with that variable
+already set and no continuation gets a `missing_continuation` report (exit
+`7`) instead of another exec, so the re-exec loop is gone. A wrapper that
+branches on `spec.env_var` and skips `bootstrap()` after the handoff keeps
+working, which is what the variable is for.
+
+`bootstrap()` checks `--python`, the current interpreter, and an existing
+`.venv`, in that order. It only offers to install the pinned Python after
+`--install-python`. An existing `.venv` is also checked with `verify_import`;
+the check runs isolated (`-I -P`), so only that venv's installed packages
+count. If the app or MCP module is missing, the repair card asks for
+`--install-python` before running the installer.
+
+`install_args` are consumer-controlled. Path-like entries are rejected when
+the spec is built if they are absolute, Windows-rooted, or contain `..`,
+including attached short-option values (`-t/tmp/x`). Venv-redirecting flags
+(`--target`, `--prefix`, `--root`, `--python` and their short forms) are
+rejected. Non-path flags such as `--index-url` pass through; credentials in
+reports are masked.
+
+The core is one stdlib-only file, `core.py`. It must stay importable on Python
+3.12 because it runs before the app's dependencies are installed; CI runs the
+suite on 3.12 as well as on the supported 3.14 and 3.15 interpreters.
+
+### Vendoring
+
+Consumers copy `core.py` and a `VENDOR.json` manifest instead of taking a
+runtime dependency:
+
+```bash
+python scripts/vendor.py \
+  --target /path/to/consumer \
+  --dest src/example/_vendor/python_mcp_bootstrap.py
+```
+
+Use `--check` to verify a pinned copy. The example app vendors `core.py` into
+`examples/_vendor/` and CI runs the same `vendor.py --check` sequence.
+
+- Contract: [docs/contract.md](docs/contract.md)
+- Integration details: [docs/integration.md](docs/integration.md)
+- Example first run: [examples/first_run.py](examples/first_run.py)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Contributing and release checks: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Development
+
+Requires Python 3.14+. The development pin is 3.15.2.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest --cov=python_mcp_bootstrap --cov-fail-under=90
+python -m ruff format --check
+python -m ruff check
+python -m mypy
+python -m build
+```
+
+CI targets Python 3.14.10 and 3.15.2 on Ubuntu, macOS, and Windows, plus a 3.12
+compatibility job, a wheel/release gate, and the vendored example first run.
+CI is advisory for now (no required status checks); check the current matrix
+before merging, and treat a pending cell as not green.
+
+## Who maintains this
+
+Maintained by Ron as a small single-maintainer project. It exists because
+first-run setup for MCP apps kept re-solving the same problem: make sure a
+supported interpreter is present before the app's dependencies are, without
+touching the system Python.
+
+Issues and pull requests are welcome. There is no support SLA. `SECURITY.md`
+lists what the bootstrap does and does not guarantee.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

python_mcp_bootstrap-0.1.3/README.md

@@ -0,0 +1,176 @@
+# python-mcp-bootstrap
+
+A small setup helper for Python apps that use MCP.
+
+MCP (Model Context Protocol) is a way for AI assistants to use tools and data.
+Before one of those apps starts, this helper makes sure it runs on a supported
+version of Python. If your computer does not have one, it explains what is
+missing and asks before downloading anything. It never changes the Python that
+is already installed.
+
+This is a bootstrap *for* MCP applications, not an MCP implementation. It has
+no runtime dependency on the MCP SDK and never imports one.
+
+**Most people do not need to run this directly.** The app's setup script uses
+it. If you are a developer adding it to an app, jump to
+[For developers](#for-developers).
+
+
+## Do I need this?
+
+- If an app's setup tells you to run `python first_run.py`, that script uses
+  this helper. Follow the app's instructions.
+- If you are building or packaging an MCP app and need a first-run Python
+  check, use this library.
+- If you just want to run an app that is already set up, no.
+
+## What it does
+
+1. Looks for Python 3.14 or newer.
+2. Looks for a working `.venv` in the project.
+3. If the Python or the app environment is missing or incomplete, prints a
+   JSON report with a `card` and a `next` command. Nothing is downloaded.
+4. If you agree, the wrapper re-runs with `--install-python`, which installs
+   what is missing inside the project.
+5. Continues setup with that Python.
+
+It can also check a Python you name:
+
+```bash
+python first_run.py --python /path/to/python
+```
+
+## What it will not do
+
+- It will not download Python without `--install-python`.
+- It will not change your system Python or system packages.
+- It will not delete an existing `.venv`; a wrong one is moved aside.
+- It will not run `curl | sh`. If `uv` is missing, it prints a tip with the
+  official uv installation page and stops. It never runs that tip.
+- It will not run commands through a shell.
+- It masks credential-shaped values in its reports and captured output.
+
+## For developers
+
+This repository is a library, not the app. The command-line tool is a
+diagnostic:
+
+```bash
+python -m python_mcp_bootstrap --check
+python -m python_mcp_bootstrap --version
+```
+
+Distribution is GitHub Releases only: install the wheel or sdist from the
+[releases page](https://github.com/4zhmv6zvj2-afk/python-mcp-bootstrap/releases).
+This project is **not published on PyPI**, so `pip install python-mcp-bootstrap`
+does not resolve.
+
+Use `BootstrapSpec` and `bootstrap()` from an app's first-run wrapper:
+
+```python
+import sys
+from pathlib import Path
+
+from python_mcp_bootstrap import BootstrapSpec, bootstrap
+
+
+def continue_setup(args: list[str]) -> int:
+    # The rest of setup goes here.
+    del args
+    return 0
+
+
+root = Path(__file__).resolve().parent
+spec = BootstrapSpec(
+    app="example-mcp",
+    entrypoint="first_run.py",
+    env_var="EXAMPLE_MCP_INTERPRETER",
+    install_args=("-e", "."),
+    verify_import="example_mcp",
+    package_main=continue_setup,
+)
+raise SystemExit(bootstrap(sys.argv[1:], root, spec))
+```
+
+`package_main` is the function `bootstrap()` calls when the current Python is
+already suitable. Pass it: an entry point that calls `bootstrap()`
+unconditionally needs somewhere to continue.
+
+The first pass may hand off once, and it records the chosen interpreter in
+`spec.env_var`. A later pass that reaches `bootstrap()` with that variable
+already set and no continuation gets a `missing_continuation` report (exit
+`7`) instead of another exec, so the re-exec loop is gone. A wrapper that
+branches on `spec.env_var` and skips `bootstrap()` after the handoff keeps
+working, which is what the variable is for.
+
+`bootstrap()` checks `--python`, the current interpreter, and an existing
+`.venv`, in that order. It only offers to install the pinned Python after
+`--install-python`. An existing `.venv` is also checked with `verify_import`;
+the check runs isolated (`-I -P`), so only that venv's installed packages
+count. If the app or MCP module is missing, the repair card asks for
+`--install-python` before running the installer.
+
+`install_args` are consumer-controlled. Path-like entries are rejected when
+the spec is built if they are absolute, Windows-rooted, or contain `..`,
+including attached short-option values (`-t/tmp/x`). Venv-redirecting flags
+(`--target`, `--prefix`, `--root`, `--python` and their short forms) are
+rejected. Non-path flags such as `--index-url` pass through; credentials in
+reports are masked.
+
+The core is one stdlib-only file, `core.py`. It must stay importable on Python
+3.12 because it runs before the app's dependencies are installed; CI runs the
+suite on 3.12 as well as on the supported 3.14 and 3.15 interpreters.
+
+### Vendoring
+
+Consumers copy `core.py` and a `VENDOR.json` manifest instead of taking a
+runtime dependency:
+
+```bash
+python scripts/vendor.py \
+  --target /path/to/consumer \
+  --dest src/example/_vendor/python_mcp_bootstrap.py
+```
+
+Use `--check` to verify a pinned copy. The example app vendors `core.py` into
+`examples/_vendor/` and CI runs the same `vendor.py --check` sequence.
+
+- Contract: [docs/contract.md](docs/contract.md)
+- Integration details: [docs/integration.md](docs/integration.md)
+- Example first run: [examples/first_run.py](examples/first_run.py)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Contributing and release checks: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## Development
+
+Requires Python 3.14+. The development pin is 3.15.2.
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e '.[dev]'
+python -m pytest --cov=python_mcp_bootstrap --cov-fail-under=90
+python -m ruff format --check
+python -m ruff check
+python -m mypy
+python -m build
+```
+
+CI targets Python 3.14.10 and 3.15.2 on Ubuntu, macOS, and Windows, plus a 3.12
+compatibility job, a wheel/release gate, and the vendored example first run.
+CI is advisory for now (no required status checks); check the current matrix
+before merging, and treat a pending cell as not green.
+
+## Who maintains this
+
+Maintained by Ron as a small single-maintainer project. It exists because
+first-run setup for MCP apps kept re-solving the same problem: make sure a
+supported interpreter is present before the app's dependencies are, without
+touching the system Python.
+
+Issues and pull requests are welcome. There is no support SLA. `SECURITY.md`
+lists what the bootstrap does and does not guarantee.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

python_mcp_bootstrap-0.1.3/SECURITY.md

@@ -0,0 +1,47 @@
+# Security policy
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| 0.1.x | yes |
+
+## Reporting
+
+Use GitHub's private vulnerability reporting: open the repository's
+**Security** tab and choose **Report a vulnerability**. That goes to the
+maintainers privately and keeps the report out of the public timeline.
+
+If that channel is unavailable, open a minimal public issue saying only that
+you have a security report and how to reach you. Do not put credentials,
+tokens, or exploit details in a public issue.
+
+## Bootstrap-specific guarantees
+
+- The bootstrap does not download Python unless the caller passes the explicit
+  `--install-python` consent flag.
+- The bootstrap never runs `curl | sh`; if uv is missing it returns a human
+  `tip` with the official uv installation docs link and stops. That tip is
+  never executed.
+- The bootstrap never modifies the system Python or its site-packages.
+- The bootstrap does not use `shell=True` and has no shell executor.
+- A project `.venv` from another interpreter is moved aside, not deleted.
+- Credential-shaped values (URL userinfo on any scheme, key/value fields, and
+  Bearer headers) in command arguments and captured output are redacted before
+  they enter a report.
+- Project-local paths and path-like `install_args` may not escape the project
+  root (absolute, Windows-rooted, and `..` values are rejected before any
+  subprocess starts, including attached short flag forms). Venv-redirecting
+  flags (`--target`, `--prefix`, `--root`, `--python`) are rejected.
+- Path checks are lexical: they do not resolve symlinks. A symlink inside the
+  project can still point outside; the consumer owns that boundary.
+- Concurrent first runs are not supported; there is no lock around the
+  `.venv` move or the provisioning steps.
+- `root` is the consumer's project directory and the working directory for
+  every step; the bootstrap never works outside it on its own.
+- The `verify_import` check runs in isolated mode (`-I -P`), so the project
+  cwd, script directory, and `PYTHONPATH` cannot satisfy it.
+- Release tags are annotated. Tags are unsigned for now. An unsigned tag is not
+  a signature; verify release artifacts by digest when that matters.
+
+A change that weakens any of these properties requires review before merge.