Merge development into main

.claude/playwright-mcp-config.json

@@ -0,0 +1,7 @@
+{
+  "browser": {
+    "launchOptions": {
+      "chromiumSandbox": true
+    }
+  }
+}

.claude/skills/gently-session-postmortem/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: gently-session-postmortem
+description: Use when analyzing how a user actually operated the gently UI — replaying a recorded session, walking the semantic action log, correlating UI actions with agent/device behavior at the same timestamps, or rendering what the screen showed at a specific moment.
+---
+
+# Gently session postmortem
+
+Every gently session records its UI interactions (always-on, rrweb-based;
+kill switch `GENTLY_REPLAY=0`). You are the intended reader: work text-first
+through the action log, and render pixels only for the moments that matter.
+
+## Where the artifacts live
+
+Per session, under the storage root (`D:\Gently3` on the Windows production
+machine; on Linux dev runs the default is the *literal* directory `D:/Gently3`
+under the cwd the server launched from, unless `GENTLY_STORAGE_PATH` is set):
+
+```
+sessions/{folder}/ui-replay/
+  actions.jsonl       # semantic action log — READ THIS FIRST
+  rrweb-{tab}.jsonl   # full DOM event stream, one file per browser tab
+  meta.yaml           # tabs seen, first_seen, user agents
+ui-replay/unassigned-{YYYYMMDD}/   # batches that arrived with no active session
+```
+
+Session id → folder mapping: `sessions/_index.yaml`.
+
+## The walk
+
+1. **Read `actions.jsonl`** (one JSON object per line). It is **arrival-ordered,
+   not time-ordered** (batches from multiple tabs interleave) — sort by `t`
+   before reconstructing a timeline. Non-browser traffic (curl probes, harness
+   runs) records too; check the tab's `user_agent` in `meta.yaml` before
+   treating a tab as a human. Kinds you'll see:
+   - `page-load` — with url + viewport; a new `tab` id per browser tab/reload.
+   - `tab:embryos`, `view:board`, `bz:-10`, `button#op-detect`,
+     `click:marking-action-btn:Done` — clicks, named from the UI's semantic
+     `data-*` vocabulary, element ids, or class+text fallback. `target` carries
+     tag/id/dataset/label.
+   - `submit`, `navigate` — forms and SPA route/hash changes.
+   - `bus-summary` — per-flush counts of ClientEventBus traffic
+     (`BOTTOM_CAMERA_FRAME×240` means live frames were streaming; token
+     streaming shows as high `AGENT_*` counts). This is how you know what the
+     *system* was doing between clicks.
+   - `gap` — the recorder dropped events under pressure (params say how many).
+2. **Join with the rest of the file store on timestamps.** Everything else is
+   already on disk: agent logs (`logs/gently_*.log`), perception traces and
+   `predictions.jsonl` per embryo, `timelapse.yaml`, events. See the
+   `gently-debugging` skill for that map.
+   **Clock semantics:** `actions.jsonl` `t` is the *browser's* clock as UTC
+   ISO; rrweb `timestamp` is epoch ms; `meta.yaml` `first_seen` is *naive
+   server-local* time (IST on the production rig — expect it to differ from
+   the same tab's UTC `page-load` by the UTC offset); server logs print
+   server-local time. Convert everything to epoch before joining, and expect
+   modest client/server skew (same machine ⇒ sub-second; remote browser ⇒
+   whatever their clock is).
+   **Names vs labels:** action names use the UI's *internal* vocabulary
+   (`tab:events`), while `target.label` is what the user actually saw
+   ("Logs") — quote labels when narrating for humans.
+3. **Render the moments that matter** (needs the repo venv with Playwright):
+
+   ```bash
+   python tools/session_replay/render_frame.py \
+     --session 81865db3 --t 2026-07-13T07:05:38Z --out /tmp/frame.png \
+     [--tab 04dce1bd] [--url http://localhost:8080] [--storage PATH]
+   ```
+
+   `--t` takes an ms offset, `52s`, `mm:ss`, or an absolute ISO timestamp
+   (paste straight from an action's `t`). `--url` pointing at a *running*
+   gently makes stored images inside the frame resolve; without it you get
+   structure + inlined CSS only. Default tab is the largest stream.
+4. **Human scrubbing**: `http://localhost:8080/replay` lists recordings;
+   `/replay/{session_id}` plays one (tab picker, speed, click an action to
+   seek to it).
+
+## Caveats
+
+- The live camera `<img id="op-cam-img">` is deliberately blocked from
+  capture (base64 frame storms) — replays show a placeholder box there. What
+  the camera saw lives in the file store (volumes/projections); whether it
+  was streaming is in `bus-summary`.
+- Replays disable CSS animations/transitions (`animation: none` injected) so
+  final styles apply — otherwise paused replays freeze entrance animations at
+  their invisible from-state. Consequence: spinners/pulses appear static, and
+  a frame rendered mid-animation shows the settled state, not the tween.
+- A rendered frame shows the DOM *at that instant*: click a nav button and
+  the previous panel is still on screen — the response mutations land in the
+  following ~200 ms. Render a second frame slightly later to see the effect.
+- A session's recording can span multiple `rrweb-{tab}` files (reloads, second
+  windows). `meta.yaml` + `page-load` actions give the timeline of tabs.
+- The final ≤4s batch of a tab can be missing if the browser/app closed
+  uncleanly (see spec: quit-flush race).
+- Recording only exists for sessions run with `settings.ui.replay` on
+  (default on; `GENTLY_REPLAY=0` disables).

.github/workflows/lint.yml

@@ -0,0 +1,69 @@
+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
+        # Pinned so CI never floats to a new ruff release mid-review. Keep in
+        # sync with the ruff-pre-commit rev in .pre-commit-config.yaml and the
+        # pin in pyproject.toml.
+        run: pip install ruff==0.16.0
+
+      - 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).
+  # Required gate: the deps-only errors have been cleared (issue #63), so a
+  # regression here now fails the workflow like the deps-less run above.
+  mypy-strict:
+    runs-on: ubuntu-latest
+    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,17 @@ 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
+
+# UI crawler generated output
+tools/ui_crawler/out*/
+

.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest",
+        "--config",
+        ".claude/playwright-mcp-config.json"
+      ],
+      "env": {}
+    }
+  }
+}

.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0  # keep in sync with the ruff pins in pyproject.toml + lint.yml; bump via `pre-commit autoupdate`
+    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: