macverdict 0.2.0__tar.gz

macverdict-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

macverdict-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anirudh Jayaraman
+
+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.

macverdict-0.2.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.5
+Name: macverdict
+Version: 0.2.0
+Summary: Stop watching graphs: macverdict tells you why your Mac was slow this week and what to do about it. Slowdown blame, RAM verdict, battery forecast and MacBook Air throttling, from quiet background sampling.
+Project-URL: Homepage, https://github.com/anirudhjayaraman/macverdict
+Project-URL: Source, https://github.com/anirudhjayaraman/macverdict
+Project-URL: Issues, https://github.com/anirudhjayaraman/macverdict/issues
+Author: Anirudh Jayaraman
+License-Expression: MIT
+License-File: LICENSE
+Keywords: battery,diagnostics,launchd,macbook,macos,monitoring,performance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# macverdict
+
+**Stop watching graphs. macverdict tells you why your Mac was slow this week, and what to do about it.**
+
+*Formerly called macpulse. If you installed it under that name, run `macverdict setup` once: it brings your history across and removes the old parts.*
+
+Activity Monitor, Stats and iStat Menus show you numbers *right now*, and leave the diagnosis to you.
+macverdict quietly samples your Mac in the background (about one second every 15 minutes) and turns
+weeks of history into four plain answers:
+
+1. **What's slowing me down?** It blames the app that was actually the biggest memory or CPU user
+   each time your Mac struggled, grouping helper processes so Chrome's 60 processes count as Chrome.
+2. **Do I need more RAM?** A verdict from weeks of memory pressure and swap, not the misleading
+   "memory used" figure, including what to buy next time.
+3. **How long will my battery last?** Your real wear rate vs. Apple's rating, and roughly when you'll
+   hit 80% capacity.
+4. **Is my Air overheating?** How often the fanless MacBook Air slowed itself down to cool off, and
+   which apps were running when it did.
+
+```
+$ macverdict insights          # illustration: three weeks on an 8 GB MacBook Air
+macverdict insights · MacBook Air · 8.0 GB RAM · last 30 days
+
+● What's slowing you down
+  Google Chrome was the biggest memory user in 85% of your 794 slowdown moments.
+    · Google Chrome: the biggest memory user in 85% of slowdowns, typically 5.0 GB.
+    · Final Cut Pro: the biggest CPU user in 15% of slowdowns.
+    · Biggest win: quit or trim Google Chrome when your Mac feels slow.
+
+● Do you need more RAM?
+  8 GB isn't enough for how you work. Your next Mac should have 16 GB.
+    · Memory pressure was elevated in 33% of samples.
+    · Swap: typically under 9.0 GB, peak 13.5 GB.
+
+● How long will your battery last?
+  At your pace, it reaches 80% capacity around May 2027.
+    · It's wearing faster than Apple's rating: 3.8% of capacity per 100 cycles, vs 2% expected.
+
+● Is your Air overheating?
+  Your Mac slowed itself down to cool off in 6% of samples.
+    · Busiest apps when it ran hot: Final Cut Pro.
+```
+
+## See it on a real Mac
+
+A real week on a MacBook Air (Apple M5, 16 GB). `macverdict report` turns the history into a page
+like this. **[Open the full sample report](https://anirudhjayaraman.github.io/macverdict/sample-report.html)**.
+
+![macverdict insights: Chrome behind every slowdown, 16 GB is enough, battery healthy, no throttling](https://raw.githubusercontent.com/anirudhjayaraman/macverdict/main/docs/insights.png)
+
+The trends make the story visible: memory pressure (shaded) on Mon 19 and Tue 20, matching the
+swap spike, then a quiet rest of the week.
+
+![macverdict trends: a week of health score, CPU, memory with pressure shaded, swap, disk, battery](https://raw.githubusercontent.com/anirudhjayaraman/macverdict/main/docs/trends.png)
+
+Free and open source, one dependency (`psutil`), no sudo, no cloud: nothing leaves your Mac.
+Built for Apple-silicon MacBooks, works on any Mac running macOS 12+.
+
+## How it compares
+
+| | Live stats | Keeps history | Tells you *why* & what to do | Price |
+|---|---|---|---|---|
+| Activity Monitor (built in) | ✅ | ❌ | ❌ | Free |
+| [Stats](https://github.com/exelban/stats) | ✅ menu bar | ❌ | ❌ | Free |
+| [iStat Menus](https://bjango.com/mac/istatmenus/) | ✅ very detailed | Some | Rule-based alerts | Paid |
+| [macmon](https://github.com/vladkens/macmon) / [mactop](https://github.com/anemll/mactop) | ✅ power & GPU | ❌ | ❌ | Free |
+| [Glances](https://github.com/nicolargo/glances) | ✅ any OS | Short buffer / export | ❌ | Free |
+| [Mole](https://github.com/tw93/mole) `mo status` | ✅ | ❌ | Live health score | Free |
+| [coconutBattery](https://www.coconut-flavour.com/coconutbattery/) | Battery only | ✅ battery | ❌ | Free / paid |
+| **macverdict** | Snapshot (`macverdict`) | ✅ everything | ✅ **blame, RAM verdict, battery forecast, throttling** | **Free** |
+
+**Use macverdict alongside a live monitor, not instead of one.** If you want to watch GPU power or fan
+speed in real time, Stats and macmon are excellent. macverdict answers the questions those tools can't:
+what happened over the last few weeks, and what you should change.
+
+## Everyday health check
+
+```
+$ macverdict
+macverdict · Apple M5 · macOS 26.5.2 · 16.0 GB RAM · up 1d 17h
+
+Health score: 100 / 100
+
+  OK       cpu      CPU 6%, load 1.9 on 10 cores.
+  OK       memory   Memory pressure normal, 66% used, swap 0 B.
+  OK       disk     698.7 GB free (75%).
+  OK       battery  52% charged, capacity 100%, 71 cycles, 30.6°C.
+  OK       thermal  No thermal throttling.
+```
+
+## What it checks
+
+| Area | Signals | Why it matters |
+|---|---|---|
+| CPU | usage, 5-min load vs. core count, runaway processes | sustained load means work is queuing |
+| Memory | **macOS memory pressure** (the real signal, not "% used"), swap, biggest apps | the #1 cause of slowdowns on 8–16 GB Macs |
+| Disk | free space on the Data volume | macOS needs room for swap and updates |
+| Battery | maximum capacity, cycle count, temperature | <80% capacity = service territory; heat = throttling |
+| Thermal | macOS's own thermal state, plus CPU speed limit | fanless Airs slow themselves down when hot |
+| Uptime | days since restart | long uptimes accumulate swap and leaks |
+
+Each finding comes with plain-English advice, and everything rolls up into a 0–100 health score.
+
+## Install
+
+```bash
+brew install anirudhjayaraman/tap/macverdict
+macverdict setup
+```
+
+That's it. `macverdict setup` starts background recording, builds the small alert app and sends a
+test alert (click **Allow** if macOS asks). Then run `macverdict` any time.
+
+To remove it: `macverdict uninstall`, then `brew uninstall macverdict`.
+
+<details>
+<summary>Not using Homebrew?</summary>
+
+Install with [uv](https://docs.astral.sh/uv/) or pipx instead, then run `macverdict setup`:
+
+```bash
+uv tool install git+https://github.com/anirudhjayaraman/macverdict
+```
+
+</details>
+
+Needs macOS 12 or later. Clickable alerts need Apple's Command Line Tools (`xcode-select --install`);
+without them, everything else still works.
+
+## Use
+
+```bash
+macverdict                      # diagnose right now
+macverdict insights             # blame, RAM verdict, battery forecast, throttling
+macverdict report               # HTML report with insights and trends, opens in your browser
+macverdict history --days 30    # min/avg/max summary in the terminal
+macverdict export history.csv   # take your data to a spreadsheet or notebook
+macverdict check --json         # machine-readable snapshot
+macverdict setup --every 5      # record every 5 minutes instead of 15
+macverdict notify-test          # check that alerts reach you
+macverdict uninstall            # stop background recording and remove the alert app
+```
+
+The background agent shows up as **macverdict** in System Settings → General → Login Items &
+Extensions (or as `python3` if the alert app couldn't be built).
+macOS labels it "unidentified developer" because it's signed on your own Mac rather than with a
+paid Apple Developer ID, which is normal for open-source command-line tools. Switching it off
+there stops recording.
+
+The background agent runs at low priority, survives reboots, and shows a macOS notification only
+when something is critical (e.g. memory pressure critical, battery overheating, disk nearly full).
+
+## Notifications
+
+The background agent only alerts you when something is critical, and clicking an alert opens your
+macverdict report. `macverdict setup` builds the small alert app that makes this work.
+
+It's built from source on your machine (`src/macverdict/notifier/MacverdictNotifier.swift`, about
+100 lines) and signed locally, so there's no downloaded binary and no Apple account involved.
+It has no Dock icon and only runs for a few seconds when posting an alert or handling a click.
+
+Without it, macverdict falls back to macOS's built-in `osascript`. Those alerts show as coming
+from **Script Editor**, and clicking one opens Script Editor. If no banner appears at all, check
+System Settings → Notifications (macverdict or Script Editor) and that no Focus mode is on.
+
+## Use it from Python
+
+```python
+from macverdict import collect, evaluate, health_score, insights, storage
+
+snap = collect()
+findings = evaluate(snap)
+print(health_score(findings), [f.message for f in findings if f.level != "ok"])
+
+rows = storage.load(storage.connect(), days=30, full=True)
+for i in insights.build(rows, snap["system"]["memory_total"], insights.hardware_model()):
+    print(i.title, "→", i.headline)
+```
+
+## Where data lives
+
+`~/Library/Application Support/macverdict/` holds `history.db` (SQLite), `report.html` and the agent
+logs. Samples older than 90 days are pruned automatically. Set `MACVERDICT_HOME` to use another folder.
+
+## How it works
+
+- `psutil` for CPU, memory, swap, disk, network and processes
+- `sysctl kern.memorystatus_vm_pressure_level` for macOS memory pressure
+- `ioreg -rn AppleSmartBattery` for battery capacity, cycles and temperature
+- `NSProcessInfo.thermalState` (read via ctypes, no PyObjC) and `pmset -g therm` for throttling
+- a per-user `launchd` agent for scheduling
+- a tiny Swift app (built locally) for clickable notifications, with `osascript` as a fallback
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT

macverdict-0.2.0/README.md

@@ -0,0 +1,203 @@
+# macverdict
+
+**Stop watching graphs. macverdict tells you why your Mac was slow this week, and what to do about it.**
+
+*Formerly called macpulse. If you installed it under that name, run `macverdict setup` once: it brings your history across and removes the old parts.*
+
+Activity Monitor, Stats and iStat Menus show you numbers *right now*, and leave the diagnosis to you.
+macverdict quietly samples your Mac in the background (about one second every 15 minutes) and turns
+weeks of history into four plain answers:
+
+1. **What's slowing me down?** It blames the app that was actually the biggest memory or CPU user
+   each time your Mac struggled, grouping helper processes so Chrome's 60 processes count as Chrome.
+2. **Do I need more RAM?** A verdict from weeks of memory pressure and swap, not the misleading
+   "memory used" figure, including what to buy next time.
+3. **How long will my battery last?** Your real wear rate vs. Apple's rating, and roughly when you'll
+   hit 80% capacity.
+4. **Is my Air overheating?** How often the fanless MacBook Air slowed itself down to cool off, and
+   which apps were running when it did.
+
+```
+$ macverdict insights          # illustration: three weeks on an 8 GB MacBook Air
+macverdict insights · MacBook Air · 8.0 GB RAM · last 30 days
+
+● What's slowing you down
+  Google Chrome was the biggest memory user in 85% of your 794 slowdown moments.
+    · Google Chrome: the biggest memory user in 85% of slowdowns, typically 5.0 GB.
+    · Final Cut Pro: the biggest CPU user in 15% of slowdowns.
+    · Biggest win: quit or trim Google Chrome when your Mac feels slow.
+
+● Do you need more RAM?
+  8 GB isn't enough for how you work. Your next Mac should have 16 GB.
+    · Memory pressure was elevated in 33% of samples.
+    · Swap: typically under 9.0 GB, peak 13.5 GB.
+
+● How long will your battery last?
+  At your pace, it reaches 80% capacity around May 2027.
+    · It's wearing faster than Apple's rating: 3.8% of capacity per 100 cycles, vs 2% expected.
+
+● Is your Air overheating?
+  Your Mac slowed itself down to cool off in 6% of samples.
+    · Busiest apps when it ran hot: Final Cut Pro.
+```
+
+## See it on a real Mac
+
+A real week on a MacBook Air (Apple M5, 16 GB). `macverdict report` turns the history into a page
+like this. **[Open the full sample report](https://anirudhjayaraman.github.io/macverdict/sample-report.html)**.
+
+![macverdict insights: Chrome behind every slowdown, 16 GB is enough, battery healthy, no throttling](https://raw.githubusercontent.com/anirudhjayaraman/macverdict/main/docs/insights.png)
+
+The trends make the story visible: memory pressure (shaded) on Mon 19 and Tue 20, matching the
+swap spike, then a quiet rest of the week.
+
+![macverdict trends: a week of health score, CPU, memory with pressure shaded, swap, disk, battery](https://raw.githubusercontent.com/anirudhjayaraman/macverdict/main/docs/trends.png)
+
+Free and open source, one dependency (`psutil`), no sudo, no cloud: nothing leaves your Mac.
+Built for Apple-silicon MacBooks, works on any Mac running macOS 12+.
+
+## How it compares
+
+| | Live stats | Keeps history | Tells you *why* & what to do | Price |
+|---|---|---|---|---|
+| Activity Monitor (built in) | ✅ | ❌ | ❌ | Free |
+| [Stats](https://github.com/exelban/stats) | ✅ menu bar | ❌ | ❌ | Free |
+| [iStat Menus](https://bjango.com/mac/istatmenus/) | ✅ very detailed | Some | Rule-based alerts | Paid |
+| [macmon](https://github.com/vladkens/macmon) / [mactop](https://github.com/anemll/mactop) | ✅ power & GPU | ❌ | ❌ | Free |
+| [Glances](https://github.com/nicolargo/glances) | ✅ any OS | Short buffer / export | ❌ | Free |
+| [Mole](https://github.com/tw93/mole) `mo status` | ✅ | ❌ | Live health score | Free |
+| [coconutBattery](https://www.coconut-flavour.com/coconutbattery/) | Battery only | ✅ battery | ❌ | Free / paid |
+| **macverdict** | Snapshot (`macverdict`) | ✅ everything | ✅ **blame, RAM verdict, battery forecast, throttling** | **Free** |
+
+**Use macverdict alongside a live monitor, not instead of one.** If you want to watch GPU power or fan
+speed in real time, Stats and macmon are excellent. macverdict answers the questions those tools can't:
+what happened over the last few weeks, and what you should change.
+
+## Everyday health check
+
+```
+$ macverdict
+macverdict · Apple M5 · macOS 26.5.2 · 16.0 GB RAM · up 1d 17h
+
+Health score: 100 / 100
+
+  OK       cpu      CPU 6%, load 1.9 on 10 cores.
+  OK       memory   Memory pressure normal, 66% used, swap 0 B.
+  OK       disk     698.7 GB free (75%).
+  OK       battery  52% charged, capacity 100%, 71 cycles, 30.6°C.
+  OK       thermal  No thermal throttling.
+```
+
+## What it checks
+
+| Area | Signals | Why it matters |
+|---|---|---|
+| CPU | usage, 5-min load vs. core count, runaway processes | sustained load means work is queuing |
+| Memory | **macOS memory pressure** (the real signal, not "% used"), swap, biggest apps | the #1 cause of slowdowns on 8–16 GB Macs |
+| Disk | free space on the Data volume | macOS needs room for swap and updates |
+| Battery | maximum capacity, cycle count, temperature | <80% capacity = service territory; heat = throttling |
+| Thermal | macOS's own thermal state, plus CPU speed limit | fanless Airs slow themselves down when hot |
+| Uptime | days since restart | long uptimes accumulate swap and leaks |
+
+Each finding comes with plain-English advice, and everything rolls up into a 0–100 health score.
+
+## Install
+
+```bash
+brew install anirudhjayaraman/tap/macverdict
+macverdict setup
+```
+
+That's it. `macverdict setup` starts background recording, builds the small alert app and sends a
+test alert (click **Allow** if macOS asks). Then run `macverdict` any time.
+
+To remove it: `macverdict uninstall`, then `brew uninstall macverdict`.
+
+<details>
+<summary>Not using Homebrew?</summary>
+
+Install with [uv](https://docs.astral.sh/uv/) or pipx instead, then run `macverdict setup`:
+
+```bash
+uv tool install git+https://github.com/anirudhjayaraman/macverdict
+```
+
+</details>
+
+Needs macOS 12 or later. Clickable alerts need Apple's Command Line Tools (`xcode-select --install`);
+without them, everything else still works.
+
+## Use
+
+```bash
+macverdict                      # diagnose right now
+macverdict insights             # blame, RAM verdict, battery forecast, throttling
+macverdict report               # HTML report with insights and trends, opens in your browser
+macverdict history --days 30    # min/avg/max summary in the terminal
+macverdict export history.csv   # take your data to a spreadsheet or notebook
+macverdict check --json         # machine-readable snapshot
+macverdict setup --every 5      # record every 5 minutes instead of 15
+macverdict notify-test          # check that alerts reach you
+macverdict uninstall            # stop background recording and remove the alert app
+```
+
+The background agent shows up as **macverdict** in System Settings → General → Login Items &
+Extensions (or as `python3` if the alert app couldn't be built).
+macOS labels it "unidentified developer" because it's signed on your own Mac rather than with a
+paid Apple Developer ID, which is normal for open-source command-line tools. Switching it off
+there stops recording.
+
+The background agent runs at low priority, survives reboots, and shows a macOS notification only
+when something is critical (e.g. memory pressure critical, battery overheating, disk nearly full).
+
+## Notifications
+
+The background agent only alerts you when something is critical, and clicking an alert opens your
+macverdict report. `macverdict setup` builds the small alert app that makes this work.
+
+It's built from source on your machine (`src/macverdict/notifier/MacverdictNotifier.swift`, about
+100 lines) and signed locally, so there's no downloaded binary and no Apple account involved.
+It has no Dock icon and only runs for a few seconds when posting an alert or handling a click.
+
+Without it, macverdict falls back to macOS's built-in `osascript`. Those alerts show as coming
+from **Script Editor**, and clicking one opens Script Editor. If no banner appears at all, check
+System Settings → Notifications (macverdict or Script Editor) and that no Focus mode is on.
+
+## Use it from Python
+
+```python
+from macverdict import collect, evaluate, health_score, insights, storage
+
+snap = collect()
+findings = evaluate(snap)
+print(health_score(findings), [f.message for f in findings if f.level != "ok"])
+
+rows = storage.load(storage.connect(), days=30, full=True)
+for i in insights.build(rows, snap["system"]["memory_total"], insights.hardware_model()):
+    print(i.title, "→", i.headline)
+```
+
+## Where data lives
+
+`~/Library/Application Support/macverdict/` holds `history.db` (SQLite), `report.html` and the agent
+logs. Samples older than 90 days are pruned automatically. Set `MACVERDICT_HOME` to use another folder.
+
+## How it works
+
+- `psutil` for CPU, memory, swap, disk, network and processes
+- `sysctl kern.memorystatus_vm_pressure_level` for macOS memory pressure
+- `ioreg -rn AppleSmartBattery` for battery capacity, cycles and temperature
+- `NSProcessInfo.thermalState` (read via ctypes, no PyObjC) and `pmset -g therm` for throttling
+- a per-user `launchd` agent for scheduling
+- a tiny Swift app (built locally) for clickable notifications, with `osascript` as a fallback
+
+## Development
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+.venv/bin/pytest
+```
+
+## License
+
+MIT

macverdict-0.2.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "macverdict"
+version = "0.2.0"
+description = "Stop watching graphs: macverdict tells you why your Mac was slow this week and what to do about it. Slowdown blame, RAM verdict, battery forecast and MacBook Air throttling, from quiet background sampling."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Anirudh Jayaraman" }]
+keywords = ["macos", "macbook", "monitoring", "diagnostics", "performance", "battery", "launchd"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Monitoring",
+]
+dependencies = ["psutil>=5.9"]
+
+[project.urls]
+Homepage = "https://github.com/anirudhjayaraman/macverdict"
+Source = "https://github.com/anirudhjayaraman/macverdict"
+Issues = "https://github.com/anirudhjayaraman/macverdict/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[project.scripts]
+macverdict = "macverdict.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/macverdict"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["docs", "legacy"]

macverdict-0.2.0/src/macverdict/__init__.py

@@ -0,0 +1,8 @@
+"""macverdict: tells you why your Mac was slow, and what to do about it. (Formerly macpulse.)"""
+
+__version__ = "0.2.0"
+
+from .checks import Finding, evaluate, health_score
+from .collectors import collect
+
+__all__ = ["collect", "evaluate", "health_score", "Finding", "__version__"]

macverdict-0.2.0/src/macverdict/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

macverdict-0.2.0/src/macverdict/checks.py

@@ -0,0 +1,147 @@
+"""Turn a snapshot into findings with plain-English advice, and a 0-100 score."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from .fmt import human_bytes
+
+GB = 1024 ** 3
+LEVELS = ("ok", "info", "warn", "critical")
+PENALTY = {"ok": 0, "info": 2, "warn": 10, "critical": 25}
+
+
+@dataclass
+class Finding:
+    level: str  # one of LEVELS
+    area: str
+    message: str
+    advice: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _cpu(s: dict) -> list[Finding]:
+    cpu, cores = s["cpu"], s["system"]["cpu_count"] or 1
+    load_ratio = cpu["load_avg"][1] / cores
+    out = []
+    if cpu["percent"] >= 90:
+        out.append(Finding("warn", "cpu", f"CPU is busy at {cpu['percent']:.0f}%.",
+                           "Check the top CPU processes below; quit anything you are not using."))
+    if load_ratio >= 1.5:
+        out.append(Finding("warn", "cpu", f"5-minute load is {cpu['load_avg'][1]:.1f} on {cores} cores.",
+                           "Sustained load above core count means work is queuing up."))
+    if not out:
+        out.append(Finding("ok", "cpu", f"CPU {cpu['percent']:.0f}%, load {cpu['load_avg'][1]:.1f} on {cores} cores."))
+    for p in s.get("top_cpu", [])[:1]:
+        if p["cpu_percent"] >= 80:
+            out.append(Finding("info", "cpu", f"{p['name']} (pid {p['pid']}) is using {p['cpu_percent']:.0f}% CPU.",
+                               "Expected if it is doing real work; otherwise it may be stuck."))
+    return out
+
+
+def _memory(s: dict) -> list[Finding]:
+    m = s["memory"]
+    level = (m.get("pressure") or {}).get("level")
+    swap = m["swap_used"]
+    out = []
+    if level == "critical":
+        out.append(Finding("critical", "memory", "Memory pressure is CRITICAL.",
+                           "macOS is compressing and swapping heavily. Close large apps or browser tabs."))
+    elif level == "warn":
+        out.append(Finding("warn", "memory", "Memory pressure is elevated.",
+                           "Close apps you are not using; this is the main cause of slowdowns on 8-16 GB Macs."))
+    if swap >= 6 * GB:
+        out.append(Finding("critical", "memory", f"Swap in use: {human_bytes(swap)}.",
+                           "Heavy swapping wears the SSD and slows everything. A restart clears it."))
+    elif swap >= 2 * GB:
+        out.append(Finding("warn", "memory", f"Swap in use: {human_bytes(swap)}.",
+                           "Some swapping is normal, but sustained growth means you need more free RAM."))
+    if not out:
+        out.append(Finding("ok", "memory", f"Memory pressure {level or 'n/a'}, {m['percent']:.0f}% used, "
+                                           f"swap {human_bytes(swap)}."))
+    biggest = (s.get("apps") or s.get("top_memory") or [])[:1]
+    for p in biggest:
+        if p["rss"] >= 0.25 * m["total"]:
+            out.append(Finding("info", "memory", f"{p['name']} is using {human_bytes(p['rss'])} of RAM.",
+                               "Restarting a long-running app often returns leaked memory."))
+    return out
+
+
+def _disk(s: dict) -> list[Finding]:
+    d = s["disk"]
+    pct, free = d["free_percent"], d["free"]
+    if pct < 5 or free < 10 * GB:
+        return [Finding("critical", "disk", f"Only {human_bytes(free)} free ({pct:.0f}%).",
+                        "macOS needs free space for swap and updates. Clear Downloads, caches, or old iOS backups.")]
+    if pct < 15:
+        return [Finding("warn", "disk", f"Disk is getting full: {human_bytes(free)} free ({pct:.0f}%).",
+                        "Use System Settings > General > Storage to find large files.")]
+    return [Finding("ok", "disk", f"{human_bytes(free)} free ({pct:.0f}%).")]
+
+
+def _battery(s: dict) -> list[Finding]:
+    b = s.get("battery")
+    if not b:
+        return []
+    out = []
+    health = b.get("max_capacity_percent") or b.get("health_percent")
+    if health is not None and health < 80:
+        out.append(Finding("warn", "battery", f"Battery maximum capacity is {health:.0f}%.",
+                           "Apple considers batteries below 80% consumed; consider a service appointment."))
+    if (b.get("cycle_count") or 0) >= 1000:
+        out.append(Finding("info", "battery", f"Battery has {b['cycle_count']} cycles (rated for 1000).", ""))
+    temp = b.get("temperature_c")
+    if temp is not None and temp >= 45:
+        out.append(Finding("critical", "battery", f"Battery is hot: {temp:.0f}°C.",
+                           "Move the Mac off soft surfaces and out of the sun; stop heavy work until it cools."))
+    elif temp is not None and temp >= 38:
+        out.append(Finding("warn", "battery", f"Battery is warm: {temp:.0f}°C.",
+                           "The MacBook Air is fanless, so sustained heat leads to throttling."))
+    if not out:
+        out.append(Finding("ok", "battery", f"{b['percent']:.0f}% charged, capacity {health}%, "
+                                            f"{b.get('cycle_count')} cycles, {temp}°C."))
+    return out
+
+
+def _thermal(s: dict) -> list[Finding]:
+    t = s["thermal"]
+    state = t.get("state")
+    if state == "critical":
+        return [Finding("critical", "thermal", "macOS reports CRITICAL heat and is slowing the Mac hard.",
+                        "Stop heavy work now and give it airflow: hard surface, out of the sun.")]
+    if t["throttled"]:
+        detail = f"limited to {t['cpu_speed_limit']}% speed" if t["cpu_speed_limit"] < 100 else "thermal state is serious"
+        return [Finding("warn", "thermal", f"Your Mac is slowing itself down to cool off ({detail}).",
+                        "Reduce load or improve airflow. On a fanless MacBook Air this is the main cause of "
+                        "slowdowns during long heavy tasks.")]
+    if state == "fair":
+        return [Finding("info", "thermal", "Your Mac is warm (thermal state: fair).",
+                        "Not slowing down yet, but sustained heavy work may start throttling.")]
+    return [Finding("ok", "thermal", "No thermal throttling.")]
+
+
+def _uptime(s: dict) -> list[Finding]:
+    days = (s["timestamp"] - s["system"]["boot_time"]) / 86400
+    if days >= 14:
+        return [Finding("info", "uptime", f"Up for {days:.0f} days.",
+                        "A restart clears swap, leaked memory and pending updates.")]
+    return []
+
+
+RULES = (_cpu, _memory, _disk, _battery, _thermal, _uptime)
+
+
+def evaluate(snapshot: dict) -> list[Finding]:
+    findings = [f for rule in RULES for f in rule(snapshot)]
+    return sorted(findings, key=lambda f: -LEVELS.index(f.level))
+
+
+def health_score(findings: list[Finding]) -> int:
+    return max(0, 100 - sum(PENALTY[f.level] for f in findings))
+
+
+def worst_level(findings: list[Finding]) -> str:
+    return max((f.level for f in findings), key=LEVELS.index, default="ok")