chore: SAVEPOINT

README.md

@@ -26,23 +26,55 @@ This creates a new directory (name derived from the title) containing a `paper.t
 
 ## Setup
 
-The Python library code in `lib/` requires SageMath. To set up the linting environment, run:
+The Python library code in `lib/` requires SageMath. Run setup once per machine:
 
 ```sh
-./run.sh setup
+./run.sh setup <sage_python_path> <sage_site_packages> [system_name]
 ```
 
-This creates a `.venv` using the SageMath Python interpreter and installs `pylint` into it.
+- `sage_python_path` — path to the SageMath Python interpreter (e.g. `/opt/sage/local/bin/python3`)
+- `sage_site_packages` — path to SageMath's site-packages directory
+- `system_name` — optional label for this machine (defaults to `hostname -s`); used to store per-machine env files as `.env.<system_name>`
+
+On subsequent runs the paths default to whatever was saved in `.env`, so `./run.sh setup` alone re-runs setup with the existing configuration.
+
+Setup also compiles the [plantri](https://github.com/mishun/plantri) submodule via `make`.
+
+## Running Sage
+
+To run a Sage script with `plantri` available on `PATH`:
+
+```sh
+./run.sh sage <script.py> [args...]
+```
+
+Or to open an interactive Sage session:
+
+```sh
+./run.sh sage
+```
 
 ## Linting
 
-To lint the `lib/` directory:
-
 ```sh
 ./run.sh lint
 ```
 
-This runs `pyright` (via `npx`) and `pylint` using the SageMath Python interpreter.
+Runs `pyright` and `pylint` on `lib/` using the SageMath Python interpreter.
+
+## Shell Completion
+
+To enable tab-completion for `run.sh` in zsh, add this to your `.zshrc`:
+
+```sh
+eval "$(path/to/run.sh completion)"
+```
+
+Or source it once in the current shell session:
+
+```sh
+eval "$(./run.sh completion)"
+```
 
 ## Building