docs: align README with uv and Python floor (#19)

.issueflows/03-solved-issues/issue19_original.md

@@ -0,0 +1,16 @@
+# Issue #19: Align README with uv and the actual Python version floor
+
+Source: https://github.com/ife-bat/oeleo/issues/19
+
+## Original issue text
+
+## Summary
+README still mixes `pip` / `python -m build` guidance and says Python 3.8 is no longer required for ≥0.6, while `pyproject.toml` still has `requires-python = \">=3.8,<3.13\"`. Day-to-day toolchain is **uv**.
+
+**Finding ID:** DOC-01  
+**Size:** yolo-fit  
+**Design doc:** `.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md` and `this-project.md`
+
+## Acceptance
+- [ ] README install/dev/test commands match `uv` workflow
+- [ ] Python version story matches `pyproject.toml` (raise floor or fix the README claim)

.issueflows/03-solved-issues/issue19_plan.md

@@ -0,0 +1,41 @@
+# Issue #19 plan
+
+## Goal
+
+Align README install/dev/test/build guidance with the project's **uv** workflow and the current `requires-python` floor (`>=3.11,<3.13`).
+
+## Constraints
+
+- Docs-only; do not change `pyproject.toml` unless the README claim still disagrees (floor already raised in #11).
+- Keep a clear PyPI end-user install path (`pip install oeleo` is fine for consumers).
+- Match day-to-day commands in `.issueflows/04-designs-and-guides/this-project.md`.
+- Update DOC-01 note in `code-review-packaging-and-ops.md` so agents do not re-open closed drift.
+
+### Prior art
+
+- `this-project.md` — canonical `uv sync` / `uv run pytest -m "not ssh"` commands.
+- `code-review-packaging-and-ops.md` DOC-01 — source finding for this issue.
+- Issue #11 — already raised `requires-python` to `>=3.11,<3.13`; README Dev bullets already reflect that.
+
+## Approach
+
+1. Expand **Development** with `uv sync` / `uv sync --all-extras`, version bump via `uv version --bump`, and tests matching CI (`not ssh` default).
+2. Replace `python -m build` / `python -m twine …` with `uv build` / `uv publish`.
+3. Leave consumer `pip install oeleo` under Install; optionally note from-source/dev uses uv.
+4. Confirm Python version wording matches `pyproject.toml` (no floor change needed).
+5. Mark DOC-01 addressed in the packaging design doc.
+
+## Files to touch
+
+| File | Change |
+|------|--------|
+| `README.md` | uv-first dev/test/build/publish; Python floor consistency |
+| `.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md` | DOC-01 resolved note |
+
+## Test strategy
+
+`uv run pytest -m "not ssh"` (docs-only; regression check).
+
+## Open questions
+
+None — yolo auto-confirm.

.issueflows/03-solved-issues/issue19_status.md

@@ -0,0 +1,15 @@
+# Issue #19 status
+
+- [x] Done
+
+## What's done
+
+- README Development: `uv sync`, tests, format, `uv version --bump`, `uv build` / `uv publish`.
+- Consumer install kept as `pip install oeleo`; pointed clone/dev at Development.
+- Confirmed Python floor wording matches `pyproject.toml` (`>=3.11,<3.13`; raised in #11).
+- DOC-01 marked resolved in `code-review-packaging-and-ops.md`; `this-project.md` publish note updated.
+- Unit tests: `uv run pytest -m "not ssh"` green.
+
+## Remaining work
+
+None.

.issueflows/04-designs-and-guides/code-review-packaging-and-ops.md

@@ -15,10 +15,12 @@ See [`code-review-overview.md`](code-review-overview.md) for the index.
 
 ### DOC-01 — Docs/toolchain drift
 
-- README still shows `pip install oeleo` and `python -m build` / twine; day-to-day is **uv**.
-- README: “Python 3.8 support is no longer required” for ≥0.6, but `requires-python = ">=3.8,<3.13"` remains.
+**Resolved in #19** (floor raised earlier in #11): README Development uses `uv sync` / `uv run` / `uv build` / `uv publish`, and states `requires-python = ">=3.11,<3.13"`. Consumer install remains `pip install oeleo` from PyPI.
+
+Still open / related:
+
 - `requirements.txt` at repo root is tiny/legacy relative to `uv.lock`.
-- Agents should follow **`uv`** + `pyproject.toml` over README anecdotes when they conflict; fix docs in a dedicated issue.
+- Prefer **`uv`** + `pyproject.toml` if any remaining doc anecdotes disagree.
 
 ## Windows app / PyInstaller
 

.issueflows/04-designs-and-guides/this-project.md

@@ -48,7 +48,7 @@ Config is via **environment variables** / `.env` (see `.env_example` and README)
 
 - **Static version (uv):** `[project] version` lives in `pyproject.toml` (currently `0.7.0`).
 - Bump with `uv version --bump <level>` before the release commit when closing a release-oriented issue.
-- Publish historically via build + twine (README); keep PyPI tokens out of the repo.
+- Publish with `uv build` / `uv publish` (see README); keep PyPI tokens out of the repo.
 
 ## Entry points
 

README.md

@@ -19,9 +19,14 @@ Python package / app that can be used for transferring files from an instrument-
 
 ### Install
 
+From PyPI (end users):
+
 ```bash
-$ pip install oeleo
+pip install oeleo
 ```
+
+From a clone (development), use **uv** — see [Development](#development).
+
 ### Run
 
 1. Create an `oeleo` worker instance.
@@ -276,44 +281,29 @@ for name in ("paramiko", "fabric", "invoke"):
 
 ## Development
 
-- Developed using `uv` on `python 3.11+`.
-- Requires Python `>=3.11,<3.13` (see `pyproject.toml`).
-
-### Some useful commands
-
-#### Update version
-
-```bash
-# update version in pyproject.toml, e.g. from 0.5.3 to 0.6.0
-```
-## Testing
-
-Unit tests:
+Day-to-day toolchain is **uv** (`uv.lock` is committed). Requires Python `>=3.11,<3.13` (see `pyproject.toml`); develop on **3.11+** (CI uses 3.12).
 
 ```bash
-uv run pytest
-```
+# Sync the project environment (add --all-extras when you need pystray)
+uv sync
+uv sync --all-extras
 
-SSH integration tests (requires a local SSH server):
+# Unit tests (default / CI path)
+uv run pytest -m "not ssh"
 
-```bash
+# SSH integration tests (needs a local SSH server — see tests/README.md)
 uv run pytest -m ssh
-```
 
-See `tests/README.md` for Docker setup, environment variables, and helper scripts.
+# Format (black + isort; not enforced in CI)
+uv run black oeleo tests app
+uv run isort oeleo tests app
 
-#### Build
+# Bump version in pyproject.toml (e.g. 0.7.0 → 0.7.1)
+uv version --bump patch
 
-```bash
-python -m build
-```
-
-#### Publish
-
-If you are using 2-factor authentication, you need to create a token on pypi.org and run:
-
-```bash
-python -m twine upload -u __token__ -p <token> dist/*
+# Build and publish
+uv build
+uv publish   # uses PyPI token from the environment / keyring
 ```
 
 ### Next