Update docs

Author: dboreham

README.md

@@ -80,8 +80,14 @@ To get started quickly on a fresh Ubuntu 24.04 instance (e.g, a Digital Ocean dr
 
 **WARNING:** Always review downloaded scripts prior to running them so that you know what going to happen to your machine.
 
-### Lazy Mode
-Stack is written in Python and so needs a recent Python 3 on the machine. It also needs either docker or podman installed, and these utilities: git, jq. The [full installation instructions](./docs/install.md) show how to get these but if you're allready set up, proceed:
+### Install with uv
+If you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed:
+```bash
+uv tool install --from git+https://github.com/bozemanpass/stack stack
+```
+
+### Download a release
+Stack is written in Python and so needs a recent Python 3 on the machine. It also needs either docker or podman installed, and these utilities: git, jq. The [full installation instructions](./docs/install.md) show how to get these but if you're already set up, proceed:
 
 Stack is distributed as a single-file self-extracting script. The latest release can be downloaded like this:
 ```bash

docs/CONTRIBUTING.md

@@ -10,17 +10,7 @@ Suitable for developers either modifying or debugging the orchestrator Python co
 
 In addition to the pre-requisites listed in the [README](/README.md), the following are required:
 
-1. Python venv package
-   This may or may not be already installed depending on the host OS and version. Check by running:
-   ```
-   $ python3 -m venv
-   usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] [--prompt PROMPT] ENV_DIR [ENV_DIR ...]
-   venv: error: the following arguments are required: ENV_DIR
-   ```
-   If the venv package is missing you should see a message indicating how to install it, for example with:
-   ```
-   $ apt install python3.10-venv
-   ```
+1. [uv](https://docs.astral.sh/uv/getting-started/installation/) — used for dependency management and virtual environments.
 
 ### Install
 
@@ -29,19 +19,20 @@ In addition to the pre-requisites listed in the [README](/README.md), the follow
    $ git clone https://github.com/bozemanpass/stack.git
    ```
 
-   2. Enter the project directory:
+2. Enter the project directory:
    ```
    $ cd stack
    ```
 
-   3. Setup the virtualenv:
+3. Install dependencies:
    ```
-   $ source ./scripts/developer-mode-setup.sh
+   $ ./scripts/developer-mode-setup.sh
    ```
+   This runs `uv sync`, which creates a `.venv` virtual environment and installs all dependencies.
 
-   4. Verify installation:
+4. Verify installation:
    ```
-   $ (venv)  stack
+   $ uv run stack
       Usage: stack [OPTIONS] COMMAND [ARGS]...
 
       BPI stack
@@ -68,11 +59,11 @@ In addition to the pre-requisites listed in the [README](/README.md), the follow
 
 ## Build a zipapp (single file distributable script)
 
-Use shiv to build a single file Python executable zip archive of stack:
+Use shiv (via `uvx`) to build a single file Python executable zip archive of stack:
 
 1. Run shiv to create a zipapp file:
    ```
-   $ (venv)  ./scripts/build_shiv_package.sh
+   $ ./scripts/build_shiv_package.sh
    ```
    This creates a file under `./package/` that is executable outside of any venv, and on other machines and OSes and architectures, and requiring only the system Python3:
 

docs/install.md

@@ -23,7 +23,23 @@ curl -SL https://github.com/docker/compose/releases/download/v2.11.2/docker-comp
 chmod +x ~/.docker/cli-plugins/docker-compose
 ```
 
-Next decide on a directory where you would like to put the stack program. Typically, this would be 
+### Install with uv (recommended)
+
+If you have [uv](https://docs.astral.sh/uv/getting-started/installation/) installed, you can install stack directly from the git repository:
+
+```bash
+uv tool install --from git+https://github.com/bozemanpass/stack stack
+```
+
+This installs `stack` into an isolated environment and adds it to your PATH. To update to the latest version:
+
+```bash
+uv tool upgrade stack
+```
+
+### Install from a downloaded release
+
+Decide on a directory where you would like to put the stack program. Typically, this would be
 a "user" binary directory such as `~/bin` or perhaps `/usr/local/bin/stack` or possibly just the current working directory.
 
 Now, having selected that directory, download the latest release from [this page](https://github.com/bozemanpass/stack/releses) into it (we're using `~/bin` below for concreteness but edit to suit if you selected a different directory). Also be sure that the destination directory exists and is writable: