yslow 0.1.0__tar.gz

yslow-0.1.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run:*)",
+      "Bash(./check.sh 2>&1)",
+      "Bash(./check.sh)",
+      "WebSearch"
+    ]
+  }
+}

yslow-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

yslow-0.1.0/CLAUDE.md

@@ -0,0 +1,22 @@
+# Claude context
+
+## Quick reference
+
+- `./check.sh` — run all checks (format, lint, typecheck, tests)
+- `uv run yslow` — run the tool
+- `uv run pytest` — tests only
+- `uv run ty check` — type check only
+- `uv run ruff check --fix` — lint
+- `uv run ruff format` — format
+- `uv run pytest tests/test_snapshots.py --snapshot-update` — regenerate UI snapshots after output changes
+
+## Key files
+
+- `TODO.md` — feature backlog and progress tracking
+- `docs/` — design and reference documentation (metrics, etc.)
+- `logs/` — session logs recording what was changed and why
+
+## Guidelines
+
+- Update or add docs in `docs/` when changing metrics, thresholds, or diagnostic logic
+- At the end of a session, write a log entry in `logs/` (format: `YYYY-MM-DD-short-description.md`) summarizing what changed and any open questions

yslow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wesley Ellis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yslow-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: yslow
+Version: 0.1.0
+Summary: Diagnose why your network connection is slow
+Project-URL: Homepage, https://codeberg.org/tahnok/yslow
+Project-URL: Repository, https://codeberg.org/tahnok/yslow
+Project-URL: Issues, https://codeberg.org/tahnok/yslow/issues
+Author-email: Wesley Ellis <wesley@tahnok.ca>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diagnostics,latency,network,troubleshooting,wifi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: rich>=14.3.3
+Description-Content-Type: text/markdown
+
+# yslow
+
+A command-line tool that diagnoses why your network connection is slow (or feels slow).
+
+Instead of just reporting numbers, yslow isolates *where* the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.
+
+## What it checks
+
+- **Gateway latency** — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
+- **Internet latency** — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
+- **Packet loss** — at both the local and internet level.
+- **Jitter** — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.
+
+By comparing gateway vs internet results, yslow isolates the problem:
+
+| Gateway | Internet | Diagnosis |
+|---------|----------|-----------|
+| Fast | Fast | Connection is healthy |
+| Slow | Slow | Local network is the bottleneck (router/wifi) |
+| Fast | Slow | ISP or internet routing issue |
+| Unreachable | Slow | Unusual setup, but internet works |
+
+## Usage
+
+```
+uv run yslow
+```
+
+Requires Python 3.10+ and Linux. No dependencies beyond the standard library.
+
+## How it works
+
+yslow uses **TCP handshake timing** rather than ICMP ping. A TCP connect to port 443 measures the same network round-trip as ping, but works without root privileges and inside containers where ICMP is often blocked.
+
+For the gateway, it tries common TCP ports (80, 443, 53) and falls back to ICMP ping if needed.
+
+## Development
+
+```
+uv sync                  # install deps
+./check.sh               # run all checks (format, lint, typecheck, tests)
+uv run pytest            # run tests only
+uv run ty check          # type check only
+uv run ruff check --fix  # lint
+uv run ruff format       # format
+```
+
+## Documentation
+
+See [`docs/metrics.md`](docs/metrics.md) for details on what yslow measures (RTT, packet loss, jitter), how each metric is calculated, and the thresholds used for diagnosis.
+
+## Planned
+
+- DNS resolution timing
+- Bandwidth / throughput estimation
+- Bufferbloat detection (latency under load)
+- Route analysis (where along the path is the bottleneck)

yslow-0.1.0/README.md

@@ -0,0 +1,57 @@
+# yslow
+
+A command-line tool that diagnoses why your network connection is slow (or feels slow).
+
+Instead of just reporting numbers, yslow isolates *where* the problem is — your local network (wifi/router), your ISP, or the broader internet — and tells you in plain language.
+
+## What it checks
+
+- **Gateway latency** — how fast your machine can talk to your router. High latency or jitter here points to wifi congestion, a bad cable, or an overloaded router.
+- **Internet latency** — TCP handshake time to multiple well-known servers (Cloudflare, Google, OpenDNS).
+- **Packet loss** — at both the local and internet level.
+- **Jitter** — variance in latency, which causes buffering, choppy calls, and inconsistent page loads.
+
+By comparing gateway vs internet results, yslow isolates the problem:
+
+| Gateway | Internet | Diagnosis |
+|---------|----------|-----------|
+| Fast | Fast | Connection is healthy |
+| Slow | Slow | Local network is the bottleneck (router/wifi) |
+| Fast | Slow | ISP or internet routing issue |
+| Unreachable | Slow | Unusual setup, but internet works |
+
+## Usage
+
+```
+uv run yslow
+```
+
+Requires Python 3.10+ and Linux. No dependencies beyond the standard library.
+
+## How it works
+
+yslow uses **TCP handshake timing** rather than ICMP ping. A TCP connect to port 443 measures the same network round-trip as ping, but works without root privileges and inside containers where ICMP is often blocked.
+
+For the gateway, it tries common TCP ports (80, 443, 53) and falls back to ICMP ping if needed.
+
+## Development
+
+```
+uv sync                  # install deps
+./check.sh               # run all checks (format, lint, typecheck, tests)
+uv run pytest            # run tests only
+uv run ty check          # type check only
+uv run ruff check --fix  # lint
+uv run ruff format       # format
+```
+
+## Documentation
+
+See [`docs/metrics.md`](docs/metrics.md) for details on what yslow measures (RTT, packet loss, jitter), how each metric is calculated, and the thresholds used for diagnosis.
+
+## Planned
+
+- DNS resolution timing
+- Bandwidth / throughput estimation
+- Bufferbloat detection (latency under load)
+- Route analysis (where along the path is the bottleneck)

yslow-0.1.0/TODO.md

@@ -0,0 +1,41 @@
+# TODO
+
+## Testing
+- [x] Add test suite (unit tests for parsing, result building; mock-based tests for probing)
+
+## New diagnostics
+- [ ] DNS resolution timing — measure lookup time for common domains, detect slow/broken resolvers
+- [ ] Bufferbloat detection — measure latency while simultaneously loading the connection
+- [ ] Speed test — download/upload throughput estimation
+- [ ] IPv6 health — check if IPv6 is configured but broken/slower than IPv4 (common cause of "feels slow" when apps try IPv6 first and fall back)
+- [ ] Wifi signal strength — read signal/noise from iw/iwconfig, flag weak signal or high noise
+- [ ] Route analysis — traceroute-style hop-by-hop latency to find where the bottleneck is
+- [ ] MTU / fragmentation issues — detect path MTU problems
+- [ ] DNS-over-HTTPS vs plain DNS comparison — detect if DoH config is hurting perceived speed
+- [ ] TLS handshake timing — separate TCP connect from TLS negotiation to isolate slow TLS
+- [ ] Bandwidth asymmetry — flag upload vs download disparity (kills video calls and syncing)
+- [ ] Probe a user-specified target — "why is github.com slow?" mode
+- [ ] Network interface health — read TX/RX errors, drops, retransmits from /proc/net/dev and /proc/net/snmp
+- [ ] Competing traffic detection — check if something else on the machine is saturating the connection
+- [ ] VPN detection, so we can account for extra latency, problems with the gateway
+- [ ] Specific site probe, we can ask the user if a particular site or service is feeling slow
+
+## Longer-running / monitoring mode
+- [x] Continuous monitoring mode — `--watch` / `-w` flag, configurable interval, live dashboard
+- [x] Session summary on exit (Ctrl+C) — total checks, healthy %, most common issues
+- [x] Terminal bell + OSC 9 desktop notification on problem detection
+- [ ] Stateful check modules — checks that accumulate data, control their own run frequency, produce smarter summaries over time
+- [ ] Summary statistics over a monitoring session (percentiles, worst periods)
+- [ ] Latency-under-load test — run probes while generating traffic to detect congestion/bufferbloat
+- [ ] Historical comparison — save results to a local log, compare "is it worse than usual?"
+- [ ] Time-of-day correlation — in monitoring mode, flag patterns like "always slow at 7pm"
+- [ ] Network condition simulation for testing — Docker/tc/netem, network namespaces, or VMs
+
+## Performance / UX
+- [ ] Parallel probing — probe all targets concurrently instead of sequentially
+- [ ] Colored output (green/yellow/red for OK/warning/problem)
+- [ ] Summary verdict — single top-line sentence like "Your wifi is the bottleneck"
+- [ ] Suggested fixes — actionable next steps based on findings (e.g., "Try switching DNS to 1.1.1.1")
+
+## Platform
+- [ ] macOS support (gateway detection, wifi tools differ)

yslow-0.1.0/check.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -e
+
+run() {
+    local label="$1"
+    shift
+    if ! output=$("$@" 2>&1); then
+        echo "=== $label FAILED ==="
+        echo "$output"
+        exit 1
+    fi
+}
+
+run "ruff format" uv run ruff format --check .
+run "ruff check" uv run ruff check .
+run "ty" uv run ty check
+run "pytest" uv run pytest -q "$@"
+
+echo "All checks passed."

yslow-0.1.0/docs/dataflow.md

@@ -0,0 +1,69 @@
+# Data flow
+
+How a network check becomes a displayed result.
+
+## Models
+
+```
+ProbeResult        Raw ping data for one host (RTTs, loss, jitter)
+Issue              A single diagnosed problem from one check (kind, severity, description)
+CheckResult        Output of one check cycle: timestamp + ProbeResults + Issues
+IssueRecord        Aggregation of Issues across multiple CheckResults, grouped by kind
+```
+
+## Pipeline
+
+```
+ ┌─────────────────────────────────────────────────────────────┐
+ │  Probes (checks/)                                          │
+ │                                                            │
+ │  gateway.run()  ──→  ProbeResult (1 host)                  │
+ │  internet.run() ──→  list[ProbeResult] (multiple hosts)    │
+ └──────────────────────────┬──────────────────────────────────┘
+                            │
+                            ▼
+ ┌─────────────────────────────────────────────────────────────┐
+ │  Diagnosis (diagnosis.py)                                  │
+ │                                                            │
+ │  analyze(gateway, internet) ──→  list[Issue]               │
+ │                                                            │
+ │  Compares probe results against thresholds (see metrics.md)│
+ │  to produce issues like "gateway-loss", "isp-latency", etc.│
+ └──────────────────────────┬──────────────────────────────────┘
+                            │
+                            ▼
+ ┌─────────────────────────────────────────────────────────────┐
+ │  Runner (runner.py)                                        │
+ │                                                            │
+ │  run_once() ──→  CheckResult                               │
+ │                                                            │
+ │  Bundles timestamp + ProbeResults + Issues into one result.│
+ └──────────────────────────┬──────────────────────────────────┘
+                            │
+                            ▼
+ ┌─────────────────────────────────────────────────────────────┐
+ │  Aggregation (models.py)                                   │
+ │                                                            │
+ │  IssueRecord.from_results(list[CheckResult])               │
+ │      ──→  list[IssueRecord]                                │
+ │                                                            │
+ │  Groups Issues by kind across all check results.           │
+ │  Tracks count, last_seen, whether currently active,        │
+ │  and last observed value.                                  │
+ └──────────────────────────┬──────────────────────────────────┘
+                            │
+                            ▼
+ ┌─────────────────────────────────────────────────────────────┐
+ │  UI (ui/)                                                  │
+ │                                                            │
+ │  WatchState holds a rolling buffer of CheckResults.        │
+ │  On each cycle:                                            │
+ │    - Runs a check (run_once)                               │
+ │    - Appends the CheckResult                               │
+ │    - Renders dashboard:                                    │
+ │        Status indicator (stable / unstable / problem)      │
+ │        Issue history (from IssueRecords)                   │
+ │        Probe summary (gateway + internet one-liners)       │
+ │    - Sends desktop notification on healthy→problem change  │
+ └─────────────────────────────────────────────────────────────┘
+```

yslow-0.1.0/docs/metrics.md

@@ -0,0 +1,55 @@
+# Metrics
+
+yslow measures three things about your network connection. Each is collected by sending a series of probes (currently 5) to each target.
+
+## RTT (round-trip time)
+
+The time for a single probe to reach a target and get a response, in milliseconds.
+
+We measure RTT using TCP handshakes (SYN → SYN-ACK) on port 443 for internet targets, and TCP or ICMP ping for the gateway. TCP handshake is preferred because it works without elevated privileges and isn't blocked by most firewalls.
+
+We report the **average RTT** across all successful probes in a run.
+
+### Thresholds
+
+| Target | Elevated | High |
+|--------|----------|------|
+| Gateway (LAN) | > 3 ms | > 10 ms |
+| ISP (internet avg minus gateway avg) | > 50 ms | > 150 ms |
+| Internet (when no gateway data) | > 50 ms | > 150 ms |
+
+"Elevated" is a warning; "high" is an error.
+
+The ISP threshold uses the difference between internet RTT and gateway RTT to isolate how much latency is added beyond your local network.
+
+## Packet loss
+
+The percentage of probes that received no response within the timeout (3 seconds).
+
+Any packet loss is flagged as an error. When both gateway and internet loss are measured, we compare them to determine the source:
+
+- Internet loss > gateway loss → problem is beyond your local network (ISP/routing)
+- Internet loss ≤ gateway loss → problem is likely your local network (wifi/router)
+
+## Jitter
+
+The sample standard deviation of RTTs within a single probe run, in milliseconds. It measures how **consistent** the connection is — a low average RTT with high jitter means some packets are fast and some are slow.
+
+High jitter degrades real-time applications (video calls, gaming, VoIP) even when average latency looks acceptable, because individual packets arrive with unpredictable timing.
+
+### How it's calculated
+
+Given RTTs `[r1, r2, ..., rn]` with mean `m`:
+
+    jitter = sqrt(sum((ri - m)^2) / (n - 1))
+
+This is the standard sample standard deviation (using Bessel's correction with `n-1`).
+
+### Thresholds
+
+| Target | High |
+|--------|------|
+| Gateway (LAN) | > 5 ms |
+| Internet (beyond LAN) | > 20 ms above gateway jitter |
+
+Internet jitter subtracts gateway jitter before comparing to the threshold, so local network jitter isn't double-counted. If your gateway has 15 ms jitter and your internet targets have 18 ms jitter, the ISP is only adding ~3 ms of jitter — the local network is the problem, not the ISP.

yslow-0.1.0/logs/2026-03-21-continuous-monitoring.md

@@ -0,0 +1,100 @@
+# Session: Continuous monitoring mode
+
+Date: 2026-03-21
+
+## What we built
+
+Added `--watch` / `-w` flag for continuous monitoring mode. Runs checks on a configurable interval (default 30s), displays a live dashboard, and notifies on problems via terminal bell + OSC 9 desktop notifications.
+
+Also unified the one-shot and monitoring output paths so both modes share the same rendering logic.
+
+## Key decisions
+
+### No TUI toolkit
+
+Decided against adding a terminal UI library (e.g., rich, textual). The dashboard is a single screen redrawn periodically — `\033[2J\033[H` (clear + home) plus `print()` is sufficient. This preserves the zero-runtime-dependency constraint. If we ever need interactive controls or complex layouts, we can revisit.
+
+### Structured error model: severity + kind, no category enum
+
+Initially considered a `Category` enum (LOCAL, ISP, INTERNET, CONNECTIVITY) alongside `Severity`. Decided against it because:
+- As we add more checks (DNS, wifi signal, bufferbloat, etc.), a fixed category enum would need constant expansion
+- The "where" context is better captured in the description string, which is already descriptive
+- Severity is what drives behavior (notifications, healthy/unhealthy state)
+
+Each issue has a `kind` string (e.g., `"gateway-latency"`, `"isp-loss"`) for grouping, and `description` + `value` for display. The `message` property combines them: `"LAN: high latency to gateway (71 ms) — wifi congestion"`.
+
+### Issue model: description + value, not a single message string
+
+Split the human-readable message into `description` (stable across occurrences) and `value` (the specific measurement). This solved two problems:
+- In monitoring mode, issues need to be grouped by kind — identical descriptions group naturally
+- One-shot mode wants specific values, monitoring history wants the description without values cluttering the grouping
+
+The `message` property reconstructs the full string by inserting the value before the em dash.
+
+### Three monitoring states: stable / unstable / problem
+
+Replaced the original OK/PROBLEM binary with three states:
+- **Stable**: every check has been healthy, nothing to report
+- **Problem**: current check has issues
+- **Unstable**: current check is healthy, but problems were seen recently — the connection is flaky
+
+This better matches the user's mental model. "It's fine now but it was bad 2 minutes ago" is meaningfully different from "it's always been fine."
+
+### Persistent issue history
+
+The dashboard shows every issue kind ever seen (within the rolling buffer), with count, last value, and timing. Active issues show `!!` prefix and "ongoing"; resolved ones show `  ` prefix and "Xm ago". This means transitioning from unstable back to problem doesn't lose the history of past issues.
+
+### Notifications only on transition
+
+Terminal bell + OSC 9 fire only on healthy-to-problem transitions. Repeating the bell every check cycle during a persistent problem would be unusable.
+
+### Consistent output between modes
+
+Both modes now use the same rendering path:
+- Check modules (`gateway`, `internet`) own their `summary()` function for one-line status
+- `_render_probes()` formats the summary lines
+- Issue display uses the same formatting
+- Status line appears in both modes
+- Startup message in both modes ("checking..." / "running initial check...")
+
+This eliminated `diagnose()`, `output.py`, and the `quiet` parameter on check modules. Checks are now pure data — they run probes and return results, with no print side effects.
+
+### Labels: LAN and ISP/internet
+
+Settled on "LAN:" and "ISP/internet:" as consistent labels across summary lines and issue descriptions. Initially had "Local network:" in issues vs "LAN:" in summaries vs "Internet:" in some places. Unified everything.
+
+### Duration formatting
+
+Two formatters: `_format_duration` for countdowns and session summaries (e.g., "2m 05s"), and `_format_ago` for issue history (seconds when under 1 minute, just minutes after — no one cares that an error was "2m 37s ago").
+
+## Architectural direction
+
+### Toward stateful check modules
+
+The current check modules are stateless functions. The user expressed interest in making them stateful for monitoring mode — each check could:
+- Decide its own run frequency (`should_run()`)
+- Accumulate data across cycles
+- Produce smarter summaries based on history
+
+This would let future checks (DNS timing, wifi signal) run on different schedules and build up richer analysis without the monitor needing to understand each check's internals.
+
+### Documentation as we go
+
+Created `docs/metrics.md` covering RTT, packet loss, and jitter — what they are, how we measure them, and thresholds. Added a guideline to CLAUDE.md to update docs when changing metrics or diagnostic logic.
+
+### Network condition simulation (TODO)
+
+Noted the need for simulating network conditions in tests (packet loss, high latency, jitter) — possibly via Docker containers with `tc`/`netem`, network namespaces, or lightweight VMs. Currently all tests use mocking.
+
+## Files changed
+
+- `yslow/models.py` — added `Severity`, `Issue` (with kind/description/value/message), `CheckResult`
+- `yslow/diagnosis.py` — refactored to return `list[Issue]`, removed `diagnose()`
+- `yslow/monitor.py` — new: monitoring loop, state tracking, dashboard rendering, notifications
+- `yslow/checks/gateway.py` — simplified to pure data, added `summary()`
+- `yslow/checks/internet.py` — simplified to pure data, added `summary()`
+- `yslow/__init__.py` — added argparse, unified one-shot and watch mode
+- `yslow/output.py` — removed (dead code after consolidation)
+- `docs/metrics.md` — new: measurement documentation
+- `tests/test_diagnosis.py` — updated for `Issue` return type
+- `tests/test_monitor.py` — new: monitor state, notification, and render tests

yslow-0.1.0/logs/2026-03-21-ui-overhaul.md

@@ -0,0 +1,54 @@
+# UI overhaul session — 2026-03-21
+
+## What we did
+
+### ASCII banner
+- Added a figlet-style "yslow" ASCII art banner displayed at startup in both modes.
+
+### Restructured into `ui/` package
+- Moved one-shot mode out of `__init__.py` into its own file.
+- Created `ui/` package with:
+  - `common.py` — shared console, banner, formatting helpers, probe rendering
+  - `check.py` — one-shot mode (`check()`)
+  - `watch.py` — continuous mode (`watch()`, `WatchState`, issue history)
+- Created `runner.py` — `run_once()` extracted from UI code where it didn't belong.
+- Renamed `MonitorState` → `WatchState`, `monitor()` → `watch()`, `oneshot()` → `check()` to match CLI verbs (`yslow` = check, `yslow -w` = watch).
+
+### Snapshot tests
+- Added `tests/test_snapshots.py` with `--snapshot-update` flag for regeneration.
+- One snapshot file per scenario per mode (6 files in `tests/snapshots/`).
+- Tests call the real `check()` and `render()` functions, capturing stdout — no knowledge of internal rendering structure.
+- Uses `Console(color_system=None)` for plain-text snapshots (also tests the pipe-to-file path).
+- Three scenarios: all good, one issue, everything failed.
+
+### Swapped issue/probe ordering
+- Both modes now show issues/status before probe detail stats.
+
+### Migrated to rich
+- Replaced hand-rolled ANSI escape codes with `rich.Console`.
+- Colors: green checkmark for healthy, red warning for issues, yellow for unstable, dim for secondary info (banner, probes).
+- `console.clear()` replaces raw `\033[2J\033[H`.
+- Auto-strips formatting when piped to a file (rich's TTY detection).
+
+### Spinners
+- Replaced the countdown timer (`Next check in 30s`) with rich `console.status()` spinners.
+- `checking...` spinner while probes run (both modes).
+- `rechecking in {interval}s...` spinner while waiting (watch mode).
+
+### Structured Issue model
+- Split `Issue.description` into `location`, `problem`, `diagnosis` fields.
+- Updated `diagnosis.py` with structured fields for all issue types.
+- `Issue.message` property still produces a readable single-line string from the fields.
+
+### Issue table (rich Table)
+- Built `render_issues()` using `rich.Table` with columns: location, problem, diagnosis, value.
+- Watch mode history table adds count + timing columns.
+
+## Open question / next steps
+
+The issue table and probe stats sections feel redundant — they show overlapping information (e.g., "LAN: high latency to gateway, 45ms" in the issue table vs "LAN: 45.0 ms rtt" in the probe stats). Unifying them into a single view would be cleaner but the right design isn't obvious yet. The table stuff may get reverted while this is figured out.
+
+Possible directions:
+- Single table that shows probes with inline issue annotations
+- Issues as the primary view, probes only shown in a `--verbose` mode
+- Probes as the primary table with issue indicators (color/icons) on problem rows

yslow-0.1.0/logs/2026-03-22-data-model-cleanup.md

@@ -0,0 +1,16 @@
+# Data model cleanup — 2026-03-22
+
+## What we did
+
+### Promoted IssueRecord to a proper model
+- Moved `IssueRecord` from `ui/watch.py` to `models.py` — it's a domain concept (aggregation of issues across check results), not a UI concern.
+- Added `IssueRecord.from_results(list[CheckResult])` static method, moving the aggregation logic out of `WatchState`.
+- `WatchState.issue_history()` now delegates to `IssueRecord.from_results()`.
+
+### Added dataflow documentation
+- Created `docs/dataflow.md` documenting the full pipeline: probes → diagnosis → CheckResult → IssueRecord → UI.
+- Covers all four model types and how they relate.
+
+## Context
+
+Working toward unifying the redundant display sections (issue history, probe summary, session summary). Understanding and cleaning up the data model is the first step — the display redundancy noted in the 2026-03-21 session is still open.

yslow-0.1.0/logs/2026-03-22-remove-summary-cleanup-tests.md

@@ -0,0 +1,20 @@
+# Remove session summary & reorganize tests — 2026-03-22
+
+## What we did
+
+### Removed redundant session summary
+- Deleted `print_summary()` from `ui/watch.py` — it duplicated the dashboard's issue history display.
+- Removed `format_duration()` from `ui/common.py` (sole caller was `print_summary`).
+- Removed `started_at` and `elapsed` from `WatchState` (only used by `print_summary`).
+- Updated `docs/dataflow.md` to remove the "on exit" line.
+
+### Reorganized tests to match module structure
+- Deleted `test_monitor.py` — was a grab bag testing `models`, `ui/common`, and `ui/watch`.
+- Created `test_watch.py` — `WatchState`, `notify`, `_render` tests.
+- Created `test_common.py` — `format_ago` tests.
+- Moved `TestCheckResultHealthy` and `TestIssueHistory` into `test_models.py`.
+- Added shared `make_check` helper and `T0` constant to `conftest.py`.
+
+## Context
+
+Continues the display redundancy cleanup noted in the 2026-03-21 session and the data model work from earlier today. The dashboard is now the single place issues are displayed in watch mode.

yslow-0.1.0/logs/2026-03-22-ui-status-and-diagnosis.md

@@ -0,0 +1,22 @@
+# 2026-03-22 — UI status header rework and diagnosis cleanup
+
+## What changed
+
+### UI status header
+- Replaced the old `problem` / `unstable` / `stable` header with a conversational format:
+  - `Is it slow?` on its own line (dim)
+  - Answer on next line: `● YES!` (red) / `● Sorta?` (yellow) / `● Nope!` (green)
+- Added section headers: `Why?` before issue list, `Details` before probe results
+- Removed gateway address from the LAN details line (was showing `(gateway 192.168.1.1)`)
+
+### Diagnosis: combined gateway-latency and gateway-jitter
+- Old: separate `gateway-latency` and `gateway-jitter` issues with different descriptions
+- New: single `gateway-quality` issue ("LAN: unstable wifi/LAN connection") that includes whichever details are relevant (rtt, jitter, or both) in the value string
+- `gateway-loss` remains separate since packet loss is a distinct symptom
+
+### Snapshot tests
+- Fixed `--snapshot-update` flag: comparison tests now skip when updating instead of failing before the update test runs
+- Added snapshot update command to CLAUDE.md quick reference
+
+## Open questions
+- None

yslow-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "yslow"
+version = "0.1.0"
+description = "Diagnose why your network connection is slow"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Wesley Ellis", email = "wesley@tahnok.ca" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Networking :: Monitoring",
+]
+keywords = ["network", "diagnostics", "latency", "wifi", "troubleshooting"]
+dependencies = [
+    "rich>=14.3.3",
+]
+
+[project.urls]
+Homepage = "https://codeberg.org/tahnok/yslow"
+Repository = "https://codeberg.org/tahnok/yslow"
+Issues = "https://codeberg.org/tahnok/yslow/issues"
+
+[project.scripts]
+yslow = "yslow:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "freezegun>=1.5.5",
+    "pytest>=9.0.2",
+    "ruff>=0.15.7",
+    "ty>=0.0.24",
+]