Release 0.22.0

.github/workflows/lint.yml

@@ -0,0 +1,67 @@
+name: Lint
+
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format check
+        run: ruff format --check .
+
+      # Fast baseline mypy without project deps. With ignore_missing_imports,
+      # third-party imports fall back to Any, so this is the weaker check — kept
+      # as the required gate because it needs no heavy install and stays green.
+      # The stronger, deps-installed run lives in the mypy-strict job below.
+      # Pin to match the pre-commit mirrors-mypy rev and the pyproject dev
+      # group so CI, local commits, and `uv sync` never run different mypys.
+      - name: Install mypy
+        run: pip install mypy==2.1.0
+
+      - name: mypy (deps-less)
+        run: mypy .
+
+  # Deps-installed mypy: with the real third-party packages present (numpy,
+  # anthropic, …) mypy resolves their actual types instead of Any, surfacing
+  # genuine mismatches the deps-less run above cannot see. This is what a
+  # contributor gets from `uv run mypy .` after `uv sync` (see CONTRIBUTING.md).
+  # Non-blocking for now (continue-on-error) while the remaining deps-only
+  # errors are worked through — flip this to a required gate once it is clean.
+  mypy-strict:
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+
+      # gently-perception is not on PyPI; it is installed editable from a sibling
+      # clone (see [tool.uv.sources]), so `uv sync` fails without it.
+      - name: Clone gently-perception sibling
+        run: git clone --depth 1 https://github.com/gently-project/gently-perception.git ../gently-perception
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+          enable-cache: true
+
+      - name: uv sync
+        run: uv sync
+
+      - name: mypy (deps-installed)
+        run: uv run mypy .

.gitignore

@@ -145,3 +145,13 @@ electron/
 /stage_definitions_for_review.txt
 gently/ui/tui/node_modules/
 gently/ui/tui/dist/
+
+# Stray local storage: GENTLY_STORAGE_PATH default (D:\Gently3) resolves
+# literally to ./D:/ under the repo on Linux. Not data we track.
+/D:/
+.superpowers/
+
+# Runtime operator overrides (written by the Settings panel)
+config/config.local.yml
+config/settings.local.yml
+config/dashboard_defaults.json

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17  # run `pre-commit autoupdate` to pin to latest
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    # Keep in sync with the mypy pin in pyproject.toml dev group and
+    # .github/workflows/lint.yml. Run `pre-commit autoupdate` to bump.
+    rev: v2.1.0
+    hooks:
+      - id: mypy
+        pass_filenames: false
+        args: ["."]

.python-version

@@ -0,0 +1 @@
+3.11

CHANGELOG.md

@@ -394,6 +394,52 @@ Net: ~3,500 lines removed across P6–P7.
 
 ---
 
+## v0.22.0
+
+File-based storage, a redesigned web UI, new hardware, and the tooling to
+keep it all honest.
+
+**File-based storage (Gently3)**
+Retired the SQLite databases. All state now lives as human-browsable files
+under `D:\Gently3\` — sessions, embryos, volumes, projections, traces,
+campaigns, learnings, agent memory, all YAML/JSONL/TIFF.
+- `FileStore` replaces `GentlyStore`; `FileContextStore` replaces the
+  `agent_mind.db` `ContextStore`. Drop-in API replacements.
+- A root `gently.yaml` manifest documents the layout for humans and agents.
+- YAML parses are cached in `FileContextStore` — fixes slow Plans/campaign
+  loading.
+
+**Web UI redesign**
+- Agent chat became a docked, sliding side panel (overlay + pin-to-dock)
+  instead of owning the screen.
+- Added a Home landing tab; the chat no longer auto-runs the startup wizard.
+- Login is non-blocking — a "Continue in view-only" escape hatch.
+- Recent images aggregate across previous sessions.
+
+**Hardware**
+- Integrated the ACUITYnano temperature controller (config, web control,
+  SDKs) with a live HiveMQ cloud SIM for hardware-free testing.
+- Added the SPIM-head F-drive device, hard limits, and focus/align plans.
+- Room-light toggle and a device-layer terminal UI.
+
+**Agent + perception**
+- Integrated the agent with perception: pull tool, prompt context, event
+  bridge, wake-router.
+- Live acquisition control with observable, permissioned autonomy and a
+  refreshed prompt.
+- Retired napari from the agent; added web-chat autocomplete and pruned
+  dead tools.
+
+**Tooling and environment**
+- Added ruff lint/format tooling and fixed all violations.
+- Adopted incremental mypy typing — config, CI, pre-commit wiring, and a
+  documented policy in `CONTRIBUTING.md`; pinned mypy to 2.1.0.
+- Switched environment setup to uv with an offline/UI-only launch path;
+  pinned pymmcore to device-interface 70.
+- Relicensed and updated the author list.
+
+---
+
 ## Notes on how we think about this
 
 Things we've learned building this, roughly in order:

CLAUDE.md

@@ -96,6 +96,51 @@ Perception is handled by `gently-perception` (separate repo: `pskeshu/gently-per
 
 The device layer runs as a separate process (`python start_device_layer.py`). It communicates with the agent via HTTP. Bluesky plans require ophyd device name kwargs (e.g. `xy_stage='xy_stage'`, `volume_scanner='volume_scanner'`) — these must match the device names registered in `device_factory.py`.
 
+## Desktop App (Tauri)
+
+Gently can run as a Windows desktop app — a thin Tauri (WebView2) shell in
+`desktop/` that OWNS the Python backend. It spawns `launch_gently.py --no-browser`,
+shows a splash, then renders the live web UI (`http://localhost:8080`) in a native
+window. The Python-served web UI stays the single source of truth — no app logic
+lives in the shell. Full detail: `desktop/README.md`.
+
+### Build / run
+```
+cd desktop
+npm install        # once — restores the Tauri CLI
+npm run dev        # dev: build + launch (spawns the backend for you)
+npm run build      # release: NSIS installer under src-tauri/target/release/bundle/
+```
+Prereqs: Rust (MSVC toolchain), the repo's uv `.venv`, WebView2 runtime (inbox on
+Win 11). The **release** exe (`src-tauri/target/release/gently-desktop.exe`) is what
+the Desktop shortcut points at; rebuild with `npm run build` to refresh it.
+
+### Key pieces
+- `desktop/src-tauri/src/main.rs` — spawns the backend, waits for the server,
+  navigates the window to it, owns teardown.
+- **No orphans:** the spawned Python (and its device-layer grandchild) run in a
+  Windows Job Object with `KILL_ON_JOB_CLOSE`, so quitting/crashing the shell reaps
+  the whole tree.
+- **No console window:** the backend is spawned with `CREATE_NO_WINDOW` in release
+  (the device-layer supervisor does the same); `tauri dev` keeps the console so
+  logs stay visible while developing.
+
+### Editing code — what reflects
+- **Web UI** (`gently/ui/web/templates`, `static/js`, `static/css`): refresh the
+  window (Ctrl+R) — served live by Python, no rebuild.
+- **Python backend**: restart it, or run with `--reload`
+  (`launch_gently.py --reload`, or `GENTLY_LAUNCH_ARGS="--reload …"`) to auto-restart
+  on `gently/*.py` changes, then Ctrl+R. Whole-backend restart — not for live hardware.
+- **Rust shell / `tauri.conf.json`**: `npm run dev` auto-rebuilds and relaunches.
+
+### Shell env config (read by `main.rs`)
+`GENTLY_HOME` (repo dir), `GENTLY_PYTHON` (interpreter), `GENTLY_LAUNCH_ARGS`
+(extra `launch_gently` args), `VIZ_PORT` (default 8080), `GENTLY_DEVICE_LAYER_SCRIPT`.
+
+### Deferred
+Bundling the Python env (torch/anthropic/perception) for a redistributable
+installer — today's build launches the repo's `.venv`, so it's single-machine.
+
 ## Debugging Data Sources
 
 - **Agent logs**: `D:\Gently3\logs\gently_*.log`

CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to Gently
+
+## Code quality toolchain
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting, and
+[mypy](https://mypy-lang.org/) for type checking, enforced automatically before every
+commit via [pre-commit](https://pre-commit.com/).
+
+### First-time setup
+
+Install the dev dependencies (includes ruff, mypy, and pre-commit):
+
+```bash
+uv sync
+```
+
+Then install the pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+From this point on, ruff runs on staged files and mypy runs across the whole
+project whenever you `git commit`.
+
+### Running manually
+
+To check all files at once (useful before opening a PR):
+
+```bash
+pre-commit run --all-files
+```
+
+Or run the tools directly:
+
+```bash
+ruff check .          # lint
+ruff format .         # format in-place
+```
+
+### Keeping hooks up to date
+
+To update hook versions to their latest releases:
+
+```bash
+pre-commit autoupdate
+```
+
+### Type checking
+
+Run mypy the same way pre-commit and CI do:
+
+```bash
+mypy .
+```
+
+The codebase is being typed incrementally (see issue #46). Modules with
+pre-existing errors are listed in the `[[tool.mypy.overrides]]` block in
+`pyproject.toml` with `ignore_errors = true`, so `mypy .` passes today even
+though not every module is fully typed yet.
+
+Policy for working with this list:
+
+- **New modules** must pass `mypy .` cleanly — do not add them to the
+  overrides list.
+- **PRs that substantively touch a module on the overrides list** should fix
+  that module's type errors and remove it from the list as part of the
+  change.
+
+### CI
+
+Every pull request runs the lint job (`.github/workflows/lint.yml`), which checks ruff lint and formatting and runs mypy across the entire project. Fix any failures locally with `pre-commit run --all-files` before pushing.