lesavka/README.md

# Lesavka

<p align="center">
  <img src="client/assets/icons/hicolor/1024x1024/apps/lesavka.png" alt="Lesavka icon" width="260" />
</p>

Lesavka is a control surface for lab equipment that needs to feel close at hand even when the actual machine is all the way down a flight of stairs. It pulls the important pieces into one place: the two eye feeds, input ownership, staged camera/audio devices, capture power, diagnostics, and the session log.

The point is simple: sit down at the desk, confirm the equipment side is awake, pick the devices you want, and work without guessing what the lab machine is doing.

## What It Does

- Shows the left and right eye feeds in the launcher, with breakout windows.
- Stage input and output choices before a session starts.
- Moves input between client and server with a single button.
- Keeps capture power and GPIO state visible.
- Keeps diagnostics and logs upfront for debugging.
- Installs through idempotent client and server scripts.

## Install / Update

### Operator Station

```bash
cd /home/brad/Development/lesavka
git pull --ff-only
sudo LESAVKA_REF=master ./scripts/install/client.sh
```

### Equipment Side

```bash
ssh <equipment-host> 'cd /var/src/lesavka && git pull --ff-only && sudo LESAVKA_REF=master ./scripts/install/server.sh'
```

The install scripts are the trusted path. They make the expected directories, install the binaries, refresh the desktop launcher or service, and keep the config in predictable places.

## Daily Shape

1. Launch `Lesavka` from the desktop menu or run `lesavka`.
2. Refresh devices if hardware changed.
3. Pick the camera, camera quality, speaker, microphone, keyboard, and mouse you want for the next run.
4. Confirm the server chip is blue before trusting the session.
5. Connect the relay, watch both eyes come online, then move inputs.
6. Use diagnostics and the session console when the bench feels wrong. The log should say what happened.

## Media Notes

- Eye capture has server-side controls for resolution, frame rate, and bitrate.
- Camera uplink quality is selected from modes the webcam actually reports and Lesavka knows how to send.
- Live queues are bounded. Stale frames should drop instead of piling up latency.
- The HDMI/UVC path is treated as real hardware, not an abstract video toy: it needs to keep moving and stay low-latency.

## Quality Gate

Lesavka has to prove the parts that work keep working.

The gate order is:

```text
style/docs -> LOC/naming -> coverage -> tests -> media reliability -> gate glue -> SonarQube -> supply chain/artifact security
```

So formatting and hygiene first, source files under the line limit, every tracked source file at 95%+ coverage, normal tests green, media tests proving frames keep moving, then the reporting/security checks.

Useful entry points:

```bash
./scripts/ci/platform_quality_gate.sh
./scripts/ci/quality_gate.sh
./scripts/ci/test_gate.sh
./scripts/ci/media_reliability_gate.sh
```

## Operational Notes

- Runtime and test environment variables are indexed in `docs/operational-env.md`.
- Gate criteria and evidence paths are documented in `docs/quality-gate.md`.
- Manual hardware checks belong in clearly marked manual scripts, not hidden in CI-only assumptions.
- If the launcher says a device path, format, or stream is wrong, fix the setup or the code until the evidence is boring.

## Versioning

Lesavka uses semver: `<major>.<minor>.<patch>`.

- Patch: bug fixes, UI polish, installer hardening, logging clarity, stability work.
- Minor: new controls, diagnostics, protocol additions, or operator-visible behavior that stays compatible when both sides are updated together.
- Major: deliberate breaking changes to protocol, install behavior, or workflow.