docs: add local pipx installation instructions

README.md

@@ -17,28 +17,106 @@ saiki --help
 - Python 3.12+
 - [Anki](https://apps.ankiweb.net/) with [AnkiConnect](https://github.com/amikey/anki-connect)
 - `ffmpeg`
-- spaCy models for word mining:
+- spaCy models for word mining (install after Saiki, as shown below)
 
-```shell
+## Installation
-python -m spacy download es_core_news_sm
-python -m spacy download ja_core_news_lg
-```
 
-Setup example:
+Choose either a virtual environment or a local command-line installation with
+pipx. Run the installation commands from the root of this checkout (the directory
+containing `pyproject.toml`).
+
+### Virtual environment
 
 ```shell
 python3.12 -m venv ~/.venv/saiki
 source ~/.venv/saiki/bin/activate
 pip install -U pip
 pip install -e .
-sudo dnf install ffmpeg
+saiki --help
 ```
 
+Activate it with `source ~/.venv/saiki/bin/activate` in each new terminal before
+running Saiki. Install `ffmpeg` with your OS package manager (examples below).
+
+For word mining, install the models for the languages you need inside the
+activated environment:
+
+```shell
+python -m spacy download es_core_news_sm
+python -m spacy download ja_core_news_lg
+```
+
+### Install locally (no virtual environment activation)
+
+Use [pipx](https://github.com/pypa/pipx) to install Saiki as a command-line app.
+It manages an isolated Python environment and puts the commands on your `PATH`,
+so you can run `saiki` from any directory without sourcing a `.venv`.
+
+Install pipx and ffmpeg with your OS package manager, for example:
+
+```shell
+# Fedora
+sudo dnf install pipx ffmpeg
+
+# Ubuntu / Debian
+sudo apt install pipx ffmpeg
+
+# macOS (Homebrew)
+brew install pipx ffmpeg
+```
+
+Run the block for your OS, then:
+
+```shell
+pipx ensurepath
+```
+
+Open a new terminal so the `PATH` change takes effect. From the root of this
+checkout (the directory containing `pyproject.toml`), install Saiki:
+
+```shell
+pipx install --python python3.12 --include-deps --editable .
+saiki --help
+```
+
+Python 3.12 must be installed; you can replace `python3.12` with another installed
+Python 3.12+ interpreter. Keep this checkout in place: `--editable` makes the
+installed command use its source files directly. Omit `--editable` if you prefer
+an independent installation that does not depend on keeping the checkout.
+
+`--include-deps` also exposes dependency commands such as `edge-tts`, `gtts-cli`,
+and `spacy`. Saiki invokes the TTS commands as subprocesses, so they must be on
+`PATH` too.
+
+For word mining, install the models using the `spacy` command supplied by this
+installation (choose the languages you need):
+
+```shell
+spacy download es_core_news_sm
+spacy download ja_core_news_lg
+```
+
+These install into Saiki's pipx environment. Model downloads are not required for
+`saiki import`. If you previously activated a virtual environment, deactivate it
+or open a fresh terminal before using this installation.
+
 ### Updating
 
-If you installed with `pip install -e .` (editable mode), changes to the source
+For the editable pipx installation, source changes take effect immediately.
-are live immediately — no reinstall needed. Only re-run `pip install -e .` if
+Pull updates from the checkout root; if dependencies or entry points in
-you pull changes that add new dependencies or scripts.
+`pyproject.toml` changed, refresh the installation:
+
+```shell
+git pull
+pipx install --force --include-deps --editable .
+```
+
+For a non-editable pipx installation, reinstall after every update, omitting
+`--editable`. To remove either installation, run `pipx uninstall saiki`.
+
+For a development environment installed with `pip install -e .`, source changes
+are also live immediately. Activate that environment before running the update
+commands; only reinstall if dependencies or scripts changed.
 
 ```shell
 git pull
@@ -48,12 +126,19 @@ pip install -e .   # only needed if pyproject.toml changed
 ### Optional TTS Backends
 
 The default `edge-tts` backend is included. To install the optional Python-backed
-engines (piper, kokoro):
+engines (piper, kokoro), run this from the checkout root:
 
 ```shell
-pip install ".[tts]"
+pipx install --force --include-deps --editable ".[tts]"
+```
 
-# System package for espeak-ng.
+Keep `".[tts]"` in subsequent reinstall commands to retain these extras. Omit
+`--editable` for an independent installation. If using a manually activated
+virtual environment instead, run `pip install ".[tts]"` inside it.
+
+For espeak-ng, install the system package:
+
+```shell
 sudo dnf install espeak-ng
 ```
 
@@ -66,14 +151,14 @@ sudo pacman -S espeak-ng
 
 Backend notes:
 
-- `edge-tts`: installed by `pip install edge-tts`; no API key, but it uses
+- `edge-tts`: included in the base installation; no API key, but it uses
   Microsoft Edge's online TTS service.
-- `gtts`: installed by `requirements.txt`; no API key, but it uses Google's
+- `gtts`: included in the base installation; no API key, but it uses Google's
   online TTS service through `gtts-cli`.
-- `piper`: installed by `pip install piper-tts`; you still need a compatible
+- `piper`: included in the `tts` extra; you still need a compatible
   `.onnx` voice model, usually with its matching `.onnx.json` config file.
 - `espeak-ng`: installed through your OS package manager, not pip.
-- `kokoro`: installed by `pip install kokoro-onnx soundfile`; you still need
+- `kokoro`: included in the `tts` extra; you still need
   `kokoro-v1.0.onnx` and `voices-v1.0.bin`, plus any language-specific G2P
   setup required by your Kokoro release.