Prep v0.1.0 public open-source launch

Developer experience + launch polish:

- pytest runs on a bare checkout (pyproject `pythonpath = ["."]`) — no editable
  install needed; `pip install numpy pytest` is enough.
- Makefile (test / lint / format / docs / build) and a pre-commit config
  (ruff lint+format + basic hygiene hooks).
- README / docs install now show the working from-source command (a PyPI
  `retina-sdk` release is landing shortly); fixes the previously broken
  `pip install retina-sdk` first command.
- Version 0.0.4 -> 0.1.0 across pyproject / __init__ / CITATION / README / docs.
- CHANGELOG [0.1.0] section (grace window + anchor) dated for the launch.
- Social-preview banner (media/social-preview.png); ignore uv.lock.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: raullenchai

.github/ISSUE_TEMPLATE/bug_report.md

@@ -28,7 +28,7 @@ What actually happened (include the full traceback if there is one).
 
 ## Environment
 
-- Trio Retina version: <!-- e.g. 0.0.4 -->
+- Trio Retina version: <!-- e.g. 0.1.0 -->
 - Python version: <!-- e.g. 3.11 -->
 - OS: <!-- e.g. macOS 14, Ubuntu 22.04 -->
 - Optional extras installed: <!-- e.g. [yolo], [video], none -->

.gitignore

@@ -9,3 +9,4 @@ build/
 site/
 *.pt
 events.jsonl
+uv.lock

.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+# Install once with:  pip install pre-commit && pre-commit install
+# Runs the same ruff checks CI does, on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff          # lint
+        args: [--fix]
+      - id: ruff-format   # format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

CHANGELOG.md

@@ -6,6 +6,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.0] — 2026-06-17
+
+First public open-source release.
+
 ### Added
 
 - `ZoneRule(exit_grace_s=...)`: a track stays logically inside until it has been
@@ -85,7 +89,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   (`JsonlSink`, `WebhookSink`).
 - `event_f1` / `match_events`: a generic metric to compare two event streams.
 
-[Unreleased]: https://github.com/machinefi/trio-retina/compare/main...HEAD
+[Unreleased]: https://github.com/machinefi/trio-retina/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/machinefi/trio-retina/releases/tag/v0.1.0
 [0.0.4]: https://github.com/machinefi/trio-retina
 [0.0.3]: https://github.com/machinefi/trio-retina
 [0.0.2]: https://github.com/machinefi/trio-retina

CITATION.cff

@@ -11,4 +11,4 @@ abstract: >-
   world models.
 repository-code: https://github.com/machinefi/trio-retina
 license: Apache-2.0
-version: 0.0.4
+version: 0.1.0

CONTRIBUTING.md

@@ -10,19 +10,25 @@ Retina has a numpy-only core, so a basic environment is light:
 ```bash
 python -m venv .venv
 source .venv/bin/activate        # Windows: .venv\Scripts\activate
-pip install -e '.[dev]'
+pip install -e '.[dev]'          # or just: pip install numpy pytest ruff
 ```
 
+The core is `numpy`-only and `pytest` reads `retina` straight from the source
+tree (`pythonpath = ["."]`), so `pytest -q` runs on a bare checkout — the
+editable install above is a convenience, not a requirement.
+
 ## Tests & lint
 
 ```bash
-pytest -q             # run the test suite
-ruff check .          # lint
-ruff format .         # auto-format (line-length = 100)
+make test     # pytest -q
+make lint     # ruff check .
+make format   # ruff format .   (line-length = 100)
+make help     # all tasks
 ```
 
-Both `ruff check .` and `pytest -q` must be green before you open a PR — CI runs
-exactly these across Python 3.10–3.13.
+Optional: `pip install pre-commit && pre-commit install` runs the same ruff
+checks on every commit. Both `ruff check .` and `pytest -q` must be green before
+you open a PR — CI runs exactly these across Python 3.10–3.13.
 
 ## Design principles
 

Makefile

@@ -0,0 +1,30 @@
+# Trio Retina — common dev tasks. Run `make` to see them all.
+.DEFAULT_GOAL := help
+
+.PHONY: help install test lint format docs build clean
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'
+
+install:  ## Install the package with dev extras (editable)
+	pip install -e '.[dev]'
+
+test:  ## Run the test suite
+	pytest -q
+
+lint:  ## Lint with ruff
+	ruff check .
+
+format:  ## Auto-format with ruff
+	ruff format .
+
+docs:  ## Build the docs site locally (needs the [docs] extra)
+	mkdocs serve
+
+build:  ## Build sdist + wheel into dist/
+	python -m build
+
+clean:  ## Remove build/test caches and artifacts
+	rm -rf dist build site *.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +

README.md

@@ -21,11 +21,13 @@ Think **OpenTelemetry for perception** — it doesn't build the sensors, it norm
 
 ## 💻 install
 
+From source — a PyPI `retina-sdk` release is landing shortly:
+
 ```bash
-pip install retina-sdk            # core: numpy only
-pip install 'retina-sdk[yolo]'    # + Ultralytics YOLO adapter
-pip install 'retina-sdk[video]'   # + OpenCV frame source (files / RTSP / webcam)
-pip install 'retina-sdk[all]'     # everything
+pip install "retina-sdk @ git+https://github.com/machinefi/trio-retina"          # core: numpy only
+pip install "retina-sdk[yolo]  @ git+https://github.com/machinefi/trio-retina"   # + Ultralytics YOLO adapter
+pip install "retina-sdk[video] @ git+https://github.com/machinefi/trio-retina"   # + OpenCV frame source (files / RTSP / webcam)
+pip install "retina-sdk[all]   @ git+https://github.com/machinefi/trio-retina"   # everything
 ```
 
 ## 🔥 quickstart
@@ -189,7 +191,7 @@ Full rationale, references, and the world-model stack: [`DESIGN.md`](DESIGN.md).
 
 ## 🗺️ roadmap
 
-Early but real (`v0.0.4`). Stable: the event layer + JSON Schema/validator, the composable pipeline (`|` / list / JSON), YOLO + open-vocab + VLM detectors, IoU + Norfair trackers.
+Early but real (`v0.1.0`). Stable: the event layer + JSON Schema/validator, the composable pipeline (`|` / list / JSON), YOLO + open-vocab + VLM detectors, IoU + Norfair trackers.
 
 Next: ByteTrack / OC-SORT · `proximity` / `anomaly` events · VLM-as-event-source · Kafka / MQTT sinks · the **latent channel** (surface V-JEPA scene + per-object embeddings). See [`CHANGELOG.md`](CHANGELOG.md).
 

docs/index.md

@@ -8,11 +8,13 @@ Think **OpenTelemetry for perception** — it doesn't build the sensors, it norm
 
 ## Install
 
+From source — a PyPI `retina-sdk` release is landing shortly:
+
 ```bash
-pip install retina-sdk            # core: numpy only
-pip install 'retina-sdk[yolo]'    # + Ultralytics YOLO adapter
-pip install 'retina-sdk[video]'   # + OpenCV frame source (files / RTSP / webcam)
-pip install 'retina-sdk[all]'     # everything
+pip install "retina-sdk @ git+https://github.com/machinefi/trio-retina"          # core: numpy only
+pip install "retina-sdk[yolo]  @ git+https://github.com/machinefi/trio-retina"   # + Ultralytics YOLO adapter
+pip install "retina-sdk[video] @ git+https://github.com/machinefi/trio-retina"   # + OpenCV frame source (files / RTSP / webcam)
+pip install "retina-sdk[all]   @ git+https://github.com/machinefi/trio-retina"   # everything
 ```
 
 ## Quickstart