@smilintux/skcapstone 0.1.0 → 0.2.3

package/tests/test_usage.py

@@ -0,0 +1,333 @@
+"""Tests for LLM token usage tracking."""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+
+import pytest
+
+from skcapstone.usage import (
+    DailyUsageReport,
+    ModelUsageSummary,
+    UsageTracker,
+    _cost_per_million,
+    _today_str,
+)
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def home(tmp_path: Path) -> Path:
+    """Minimal agent home directory."""
+    return tmp_path
+
+
+@pytest.fixture
+def tracker(home: Path) -> UsageTracker:
+    """UsageTracker backed by a temp directory."""
+    return UsageTracker(home)
+
+
+# ---------------------------------------------------------------------------
+# Cost table
+# ---------------------------------------------------------------------------
+
+
+class TestCostTable:
+    """Unit tests for _cost_per_million()."""
+
+    def test_claude_sonnet_priced(self) -> None:
+        """Claude Sonnet returns non-zero pricing."""
+        inp, out = _cost_per_million("claude-sonnet-4-6")
+        assert inp > 0
+        assert out > inp  # output always more expensive
+
+    def test_ollama_free(self) -> None:
+        """Ollama / local models have zero cost."""
+        inp, out = _cost_per_million("ollama:llama3.1")
+        assert inp == 0.0
+        assert out == 0.0
+
+    def test_passthrough_free(self) -> None:
+        """Passthrough backend is always free."""
+        inp, out = _cost_per_million("passthrough")
+        assert inp == 0.0
+        assert out == 0.0
+
+    def test_unknown_model_has_nonzero_fallback(self) -> None:
+        """Unknown models get a conservative non-zero price."""
+        inp, out = _cost_per_million("some-unknown-model-xyz")
+        assert inp > 0
+        assert out > 0
+
+    def test_gpt4o_priced(self) -> None:
+        """GPT-4o returns positive pricing."""
+        inp, out = _cost_per_million("gpt-4o")
+        assert inp > 0
+        assert out > inp
+
+    def test_claude_opus_more_expensive_than_haiku(self) -> None:
+        """Opus costs more per token than Haiku."""
+        opus_inp, opus_out = _cost_per_million("claude-opus-4-6")
+        haiku_inp, haiku_out = _cost_per_million("claude-haiku-4-5")
+        assert opus_inp > haiku_inp
+        assert opus_out > haiku_out
+
+
+# ---------------------------------------------------------------------------
+# UsageTracker.record_usage
+# ---------------------------------------------------------------------------
+
+
+class TestRecordUsage:
+    """Tests for the write path."""
+
+    def test_creates_usage_file(self, tracker: UsageTracker, home: Path) -> None:
+        """record_usage creates tokens-{date}.json."""
+        date_str = "2026-03-02"
+        tracker.record_usage("ollama:llama3.1", 100, 50, date_str=date_str)
+        path = home / "usage" / f"tokens-{date_str}.json"
+        assert path.exists()
+
+    def test_accumulates_calls(self, tracker: UsageTracker) -> None:
+        """Multiple record_usage calls accumulate counters."""
+        date_str = "2026-03-02"
+        for _ in range(5):
+            tracker.record_usage("ollama:llama3.1", 100, 50, date_str=date_str)
+        report = tracker.get_daily(date_str)
+        summary = report.models["ollama:llama3.1"]
+        assert summary.calls == 5
+        assert summary.input_tokens == 500
+        assert summary.output_tokens == 250
+
+    def test_multiple_models_tracked_separately(self, tracker: UsageTracker) -> None:
+        """Different models accumulate independently."""
+        date_str = "2026-03-02"
+        tracker.record_usage("ollama:llama3.1", 100, 50, date_str=date_str)
+        tracker.record_usage("claude-sonnet-4-6", 200, 80, date_str=date_str)
+        report = tracker.get_daily(date_str)
+        assert "ollama:llama3.1" in report.models
+        assert "claude-sonnet-4-6" in report.models
+        assert report.models["ollama:llama3.1"].calls == 1
+        assert report.models["claude-sonnet-4-6"].calls == 1
+
+    def test_cost_zero_for_local_model(self, tracker: UsageTracker) -> None:
+        """Local ollama models accumulate zero estimated cost."""
+        date_str = "2026-03-02"
+        tracker.record_usage("ollama:llama3.1", 10_000, 5_000, date_str=date_str)
+        report = tracker.get_daily(date_str)
+        assert report.models["ollama:llama3.1"].estimated_cost_usd == 0.0
+
+    def test_cost_nonzero_for_paid_model(self, tracker: UsageTracker) -> None:
+        """Paid models accumulate a positive estimated cost."""
+        date_str = "2026-03-02"
+        tracker.record_usage("claude-sonnet-4-6", 1_000_000, 100_000, date_str=date_str)
+        report = tracker.get_daily(date_str)
+        assert report.models["claude-sonnet-4-6"].estimated_cost_usd > 0
+
+    def test_json_file_readable(self, tracker: UsageTracker, home: Path) -> None:
+        """Persisted file is valid JSON."""
+        date_str = "2026-03-02"
+        tracker.record_usage("ollama:llama3.1", 100, 50, date_str=date_str)
+        path = home / "usage" / f"tokens-{date_str}.json"
+        data = json.loads(path.read_text(encoding="utf-8"))
+        assert "models" in data
+        assert "ollama:llama3.1" in data["models"]
+
+
+# ---------------------------------------------------------------------------
+# UsageTracker.get_daily
+# ---------------------------------------------------------------------------
+
+
+class TestGetDaily:
+    """Tests for the daily read path."""
+
+    def test_empty_day_returns_report(self, tracker: UsageTracker) -> None:
+        """get_daily for a day with no data returns an empty report."""
+        report = tracker.get_daily("2099-01-01")
+        assert isinstance(report, DailyUsageReport)
+        assert report.date == "2099-01-01"
+        assert report.models == {}
+
+    def test_total_tokens_property(self, tracker: UsageTracker) -> None:
+        """total_tokens sums input + output across all models."""
+        date_str = "2026-03-02"
+        tracker.record_usage("ollama:llama3.1", 100, 40, date_str=date_str)
+        tracker.record_usage("claude-sonnet-4-6", 200, 60, date_str=date_str)
+        report = tracker.get_daily(date_str)
+        assert report.total_input_tokens == 300
+        assert report.total_output_tokens == 100
+        assert report.total_tokens == 400
+
+    def test_corrupt_file_returns_empty(self, home: Path) -> None:
+        """A corrupt JSON file returns an empty report instead of crashing."""
+        date_str = "2026-03-02"
+        usage_dir = home / "usage"
+        usage_dir.mkdir(parents=True)
+        (usage_dir / f"tokens-{date_str}.json").write_text("not json {{{", encoding="utf-8")
+        tracker = UsageTracker(home)
+        report = tracker.get_daily(date_str)
+        assert isinstance(report, DailyUsageReport)
+        assert report.models == {}
+
+
+# ---------------------------------------------------------------------------
+# UsageTracker.get_weekly / get_monthly
+# ---------------------------------------------------------------------------
+
+
+class TestRangeQueries:
+    """Tests for weekly and monthly range queries."""
+
+    def test_weekly_returns_7_days(self, tracker: UsageTracker) -> None:
+        """get_weekly returns exactly 7 DailyUsageReport objects."""
+        reports = tracker.get_weekly()
+        assert len(reports) == 7
+
+    def test_monthly_returns_30_days(self, tracker: UsageTracker) -> None:
+        """get_monthly returns exactly 30 DailyUsageReport objects."""
+        reports = tracker.get_monthly()
+        assert len(reports) == 30
+
+    def test_weekly_includes_data(self, tracker: UsageTracker) -> None:
+        """get_weekly includes a day that has data recorded."""
+        from datetime import date, timedelta
+        today = date.today().strftime("%Y-%m-%d")
+        tracker.record_usage("ollama:llama3.1", 100, 50, date_str=today)
+        reports = tracker.get_weekly()
+        total = sum(r.total_calls for r in reports)
+        assert total == 1
+
+    def test_aggregate_sums_correctly(self, tracker: UsageTracker) -> None:
+        """aggregate() totals across multiple days."""
+        tracker.record_usage("ollama:llama3.1", 100, 50, date_str="2026-03-01")
+        tracker.record_usage("ollama:llama3.1", 200, 80, date_str="2026-03-02")
+        reports = [tracker.get_daily("2026-03-01"), tracker.get_daily("2026-03-02")]
+        agg = tracker.aggregate(reports)
+        m = agg.models["ollama:llama3.1"]
+        assert m.calls == 2
+        assert m.input_tokens == 300
+        assert m.output_tokens == 130
+
+    def test_aggregate_empty_list(self, tracker: UsageTracker) -> None:
+        """aggregate([]) returns a safe empty report."""
+        agg = tracker.aggregate([])
+        assert agg.date == "empty"
+        assert agg.models == {}
+
+
+# ---------------------------------------------------------------------------
+# Thread safety
+# ---------------------------------------------------------------------------
+
+
+class TestThreadSafety:
+    """Concurrent record_usage calls must not corrupt data."""
+
+    def test_concurrent_writes_same_model(self, tracker: UsageTracker) -> None:
+        """100 concurrent record_usage calls produce correct totals."""
+        date_str = "2026-03-02"
+        n = 100
+        barrier = threading.Barrier(n)
+
+        def _record():
+            barrier.wait()
+            tracker.record_usage("ollama:llama3.1", 10, 5, date_str=date_str)
+
+        threads = [threading.Thread(target=_record) for _ in range(n)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        report = tracker.get_daily(date_str)
+        m = report.models["ollama:llama3.1"]
+        assert m.calls == n
+        assert m.input_tokens == n * 10
+        assert m.output_tokens == n * 5
+
+    def test_concurrent_writes_different_models(self, tracker: UsageTracker) -> None:
+        """Concurrent writes to different models don't lose data."""
+        date_str = "2026-03-02"
+        n = 50
+        barrier = threading.Barrier(n * 2)
+
+        def _record_a():
+            barrier.wait()
+            tracker.record_usage("model-a", 10, 5, date_str=date_str)
+
+        def _record_b():
+            barrier.wait()
+            tracker.record_usage("model-b", 20, 10, date_str=date_str)
+
+        threads = (
+            [threading.Thread(target=_record_a) for _ in range(n)]
+            + [threading.Thread(target=_record_b) for _ in range(n)]
+        )
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        report = tracker.get_daily(date_str)
+        assert report.models["model-a"].calls == n
+        assert report.models["model-b"].calls == n
+
+
+# ---------------------------------------------------------------------------
+# ModelUsageSummary
+# ---------------------------------------------------------------------------
+
+
+class TestModelUsageSummary:
+    """Unit tests for the ModelUsageSummary model."""
+
+    def test_total_tokens(self) -> None:
+        """total_tokens sums input and output."""
+        m = ModelUsageSummary(
+            model="test", calls=1, input_tokens=100, output_tokens=50
+        )
+        assert m.total_tokens == 150
+
+    def test_defaults(self) -> None:
+        """All counts default to zero."""
+        m = ModelUsageSummary(model="test")
+        assert m.calls == 0
+        assert m.input_tokens == 0
+        assert m.output_tokens == 0
+        assert m.estimated_cost_usd == 0.0
+        assert m.total_tokens == 0
+
+
+# ---------------------------------------------------------------------------
+# DailyUsageReport
+# ---------------------------------------------------------------------------
+
+
+class TestDailyUsageReport:
+    """Unit tests for the DailyUsageReport model."""
+
+    def test_empty_report_totals(self) -> None:
+        """Empty report has all-zero aggregates."""
+        r = DailyUsageReport(date="2026-03-02")
+        assert r.total_calls == 0
+        assert r.total_tokens == 0
+        assert r.total_cost_usd == 0.0
+
+    def test_total_cost_aggregates(self) -> None:
+        """total_cost_usd sums across all models."""
+        r = DailyUsageReport(
+            date="2026-03-02",
+            models={
+                "m1": ModelUsageSummary(model="m1", estimated_cost_usd=0.10),
+                "m2": ModelUsageSummary(model="m2", estimated_cost_usd=0.25),
+            },
+        )
+        assert abs(r.total_cost_usd - 0.35) < 1e-9

package/tests/test_version_cmd.py

@@ -0,0 +1,355 @@
+"""Tests for skcapstone version command and doctor --verbose.
+
+Covers:
+- gather_version_info() returns expected keys
+- _check_optional_dep() returns version or None
+- _probe_ollama() running / not-running paths
+- _get_daemon_pid() running / not-running paths
+- version CLI: normal output and --json-out
+- doctor CLI: --verbose mode shows all checks
+- doctor CLI: --verbose with --json-out includes all checks
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from click.testing import CliRunner
+
+
+# ---------------------------------------------------------------------------
+# Shared fixture
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def agent_home(tmp_path: Path) -> Path:
+    """Fully initialised agent home with minimal required files."""
+    home = tmp_path / ".skcapstone"
+    for d in [
+        "identity", "memory", "trust", "security", "sync", "config",
+        "memory/short-term", "memory/mid-term", "memory/long-term",
+    ]:
+        (home / d).mkdir(parents=True, exist_ok=True)
+
+    (home / "manifest.json").write_text(json.dumps({
+        "name": "TestAgent", "version": "0.1.0",
+    }))
+    (home / "identity" / "identity.json").write_text(json.dumps({
+        "name": "TestAgent",
+        "fingerprint": "DEADBEEF12345678",
+        "capauth_managed": True,
+    }))
+    return home
+
+
+# ---------------------------------------------------------------------------
+# Unit tests for version_cmd helpers
+# ---------------------------------------------------------------------------
+
+
+class TestCheckOptionalDep:
+    """Tests for _check_optional_dep()."""
+
+    def test_installed_package_returns_version(self):
+        """Returns version string when package is importable."""
+        from skcapstone.cli.version_cmd import _check_optional_dep
+
+        # 'sys' is always importable; give it a fake __version__ to confirm
+        with patch("importlib.import_module") as mock_import:
+            mock_mod = MagicMock()
+            mock_mod.__version__ = "9.9.9"
+            mock_import.return_value = mock_mod
+            result = _check_optional_dep("fakepkg")
+
+        assert result == "9.9.9"
+
+    def test_missing_package_returns_none(self):
+        """Returns None when package raises ImportError."""
+        from skcapstone.cli.version_cmd import _check_optional_dep
+
+        with patch("importlib.import_module", side_effect=ImportError("no module")):
+            result = _check_optional_dep("nonexistent_pkg_xyz")
+
+        assert result is None
+
+    def test_package_without_version_attr_returns_installed(self):
+        """Returns 'installed' fallback when __version__ is absent."""
+        from skcapstone.cli.version_cmd import _check_optional_dep
+
+        with patch("importlib.import_module") as mock_import:
+            mock_mod = MagicMock(spec=[])  # no attributes
+            mock_import.return_value = mock_mod
+            result = _check_optional_dep("nover_pkg")
+
+        assert result == "installed"
+
+
+class TestProbeOllama:
+    """Tests for _probe_ollama()."""
+
+    def test_running_returns_models(self):
+        """Running Ollama: running=True, models list populated."""
+        from skcapstone.cli.version_cmd import _probe_ollama
+
+        payload = json.dumps({
+            "models": [{"name": "llama3:latest"}, {"name": "phi3:mini"}]
+        }).encode()
+        mock_resp = MagicMock()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_resp.read.return_value = payload
+
+        with patch("urllib.request.urlopen", return_value=mock_resp):
+            result = _probe_ollama()
+
+        assert result["running"] is True
+        assert "llama3:latest" in result["models"]
+        assert "phi3:mini" in result["models"]
+
+    def test_not_running_on_connection_error(self):
+        """Connection refused: running=False, models=[]."""
+        from skcapstone.cli.version_cmd import _probe_ollama
+
+        with patch("urllib.request.urlopen", side_effect=OSError("connection refused")):
+            result = _probe_ollama()
+
+        assert result["running"] is False
+        assert result["models"] == []
+
+    def test_host_included_in_result(self, monkeypatch):
+        """Custom OLLAMA_HOST appears in the returned dict."""
+        from skcapstone.cli.version_cmd import _probe_ollama
+
+        monkeypatch.setenv("OLLAMA_HOST", "http://my-server:11434")
+        with patch("urllib.request.urlopen", side_effect=OSError):
+            result = _probe_ollama()
+
+        assert result["host"] == "http://my-server:11434"
+
+
+class TestGetDaemonPid:
+    """Tests for _get_daemon_pid()."""
+
+    def test_returns_pid_when_running(self, agent_home: Path):
+        """Returns integer PID when daemon is alive."""
+        from skcapstone.cli.version_cmd import _get_daemon_pid
+
+        with patch("skcapstone.daemon.read_pid", return_value=99999):
+            result = _get_daemon_pid(agent_home)
+
+        assert result == 99999
+
+    def test_returns_none_when_stopped(self, agent_home: Path):
+        """Returns None when no PID file exists."""
+        from skcapstone.cli.version_cmd import _get_daemon_pid
+
+        with patch("skcapstone.daemon.read_pid", return_value=None):
+            result = _get_daemon_pid(agent_home)
+
+        assert result is None
+
+    def test_returns_none_on_exception(self, agent_home: Path):
+        """Swallows import or runtime errors, returns None."""
+        from skcapstone.cli.version_cmd import _get_daemon_pid
+
+        with patch("skcapstone.daemon.read_pid", side_effect=RuntimeError("oops")):
+            result = _get_daemon_pid(agent_home)
+
+        assert result is None
+
+
+class TestGatherVersionInfo:
+    """Tests for gather_version_info()."""
+
+    def test_contains_all_expected_keys(self, agent_home: Path):
+        """Dict has all required top-level keys."""
+        from skcapstone.cli.version_cmd import gather_version_info
+
+        with patch("urllib.request.urlopen", side_effect=OSError), \
+             patch("skcapstone.daemon.read_pid", return_value=None):
+            info = gather_version_info(agent_home)
+
+        assert "package_version" in info
+        assert "python_version" in info
+        assert "platform" in info
+        assert "optional_deps" in info
+        assert "ollama" in info
+        assert "daemon_pid" in info
+
+    def test_optional_deps_has_four_packages(self, agent_home: Path):
+        """optional_deps covers watchdog, skcomm, skchat, skseed."""
+        from skcapstone.cli.version_cmd import gather_version_info
+
+        with patch("urllib.request.urlopen", side_effect=OSError), \
+             patch("skcapstone.daemon.read_pid", return_value=None):
+            info = gather_version_info(agent_home)
+
+        deps = info["optional_deps"]
+        assert set(deps.keys()) == {"watchdog", "skcomm", "skchat", "skseed"}
+
+    def test_package_version_matches_module(self, agent_home: Path):
+        """package_version matches skcapstone.__version__."""
+        from skcapstone import __version__
+        from skcapstone.cli.version_cmd import gather_version_info
+
+        with patch("urllib.request.urlopen", side_effect=OSError), \
+             patch("skcapstone.daemon.read_pid", return_value=None):
+            info = gather_version_info(agent_home)
+
+        assert info["package_version"] == __version__
+
+
+# ---------------------------------------------------------------------------
+# CLI integration tests — version command
+# ---------------------------------------------------------------------------
+
+
+class TestVersionCommand:
+    """Integration tests for `skcapstone version`."""
+
+    def _run(self, args: list[str], agent_home: Path):
+        from skcapstone.cli import main
+
+        runner = CliRunner(mix_stderr=False)
+        with patch("urllib.request.urlopen", side_effect=OSError), \
+             patch("skcapstone.daemon.read_pid", return_value=None):
+            return runner.invoke(
+                main,
+                ["version", "--home", str(agent_home)] + args,
+                catch_exceptions=False,
+            )
+
+    def test_default_output_contains_version(self, agent_home: Path):
+        """Normal output includes the skcapstone package version."""
+        from skcapstone import __version__
+
+        result = self._run([], agent_home)
+        assert result.exit_code == 0, result.output
+        assert __version__ in result.output
+
+    def test_default_output_lists_optional_deps(self, agent_home: Path):
+        """Normal output lists all four optional dep names."""
+        result = self._run([], agent_home)
+        assert result.exit_code == 0
+        for pkg in ("watchdog", "skcomm", "skchat", "skseed"):
+            assert pkg in result.output
+
+    def test_json_output_is_valid_and_complete(self, agent_home: Path):
+        """--json-out emits valid JSON with all required keys."""
+        result = self._run(["--json-out"], agent_home)
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert "package_version" in data
+        assert "python_version" in data
+        assert "optional_deps" in data
+        assert "ollama" in data
+        assert "daemon_pid" in data
+
+    def test_daemon_running_shown_in_output(self, agent_home: Path):
+        """Shows running + PID when daemon is alive."""
+        from skcapstone.cli import main
+
+        runner = CliRunner(mix_stderr=False)
+        with patch("urllib.request.urlopen", side_effect=OSError), \
+             patch("skcapstone.daemon.read_pid", return_value=42001):
+            result = runner.invoke(
+                main,
+                ["version", "--home", str(agent_home)],
+                catch_exceptions=False,
+            )
+        assert result.exit_code == 0
+        assert "42001" in result.output
+
+    def test_ollama_running_shows_model_count(self, agent_home: Path):
+        """When Ollama is up, output includes model count."""
+        from skcapstone.cli import main
+
+        payload = json.dumps({
+            "models": [{"name": "llama3:latest"}, {"name": "mistral:7b"}]
+        }).encode()
+        mock_resp = MagicMock()
+        mock_resp.__enter__ = lambda s: s
+        mock_resp.__exit__ = MagicMock(return_value=False)
+        mock_resp.read.return_value = payload
+
+        runner = CliRunner(mix_stderr=False)
+        with patch("urllib.request.urlopen", return_value=mock_resp), \
+             patch("skcapstone.daemon.read_pid", return_value=None):
+            result = runner.invoke(
+                main,
+                ["version", "--home", str(agent_home)],
+                catch_exceptions=False,
+            )
+        assert result.exit_code == 0
+        assert "2 model" in result.output
+
+
+# ---------------------------------------------------------------------------
+# CLI integration tests — doctor --verbose
+# ---------------------------------------------------------------------------
+
+
+class TestDoctorVerbose:
+    """Integration tests for `skcapstone doctor --verbose`."""
+
+    def _run_doctor(self, args: list[str], agent_home: Path):
+        from skcapstone.cli import main
+
+        runner = CliRunner(mix_stderr=False)
+        return runner.invoke(
+            main,
+            ["doctor", "--home", str(agent_home)] + args,
+            catch_exceptions=False,
+        )
+
+    def test_verbose_shows_passing_checks(self, agent_home: Path):
+        """--verbose prints checks that passed, not just failures."""
+        result = self._run_doctor(["--verbose"], agent_home)
+        assert result.exit_code == 0
+        # At minimum the home:exists check should be present in output
+        assert "Agent home directory" in result.output
+
+    def test_verbose_output_includes_check_names(self, agent_home: Path):
+        """--verbose output contains internal check names in parentheses."""
+        result = self._run_doctor(["--verbose"], agent_home)
+        assert result.exit_code == 0
+        # Internal names like (home:exists) appear in verbose mode
+        assert "home:exists" in result.output
+
+    def test_verbose_shows_summary_line(self, agent_home: Path):
+        """--verbose ends with a 'Summary:' line containing pass/fail counts."""
+        result = self._run_doctor(["--verbose"], agent_home)
+        assert result.exit_code == 0
+        assert "Summary:" in result.output
+        assert "passed" in result.output
+
+    def test_non_verbose_collapses_all_pass_categories(self, agent_home: Path):
+        """Without --verbose, fully-passing categories are on one line."""
+        result = self._run_doctor([], agent_home)
+        assert result.exit_code == 0
+        # Agent Home directory exists, so it should be collapsed
+        assert "passed" in result.output
+
+    def test_verbose_json_includes_all_checks(self, agent_home: Path):
+        """--verbose --json-out still emits the full checks list."""
+        result = self._run_doctor(["--verbose", "--json-out"], agent_home)
+        assert result.exit_code == 0
+        data = json.loads(result.output)
+        assert "checks" in data
+        assert len(data["checks"]) > 0
+        # Every check has a name
+        for c in data["checks"]:
+            assert "name" in c
+
+    def test_verbose_help_text_mentions_verbose(self, agent_home: Path):
+        """--help output documents the --verbose flag."""
+        from skcapstone.cli import main
+
+        runner = CliRunner(mix_stderr=False)
+        result = runner.invoke(main, ["doctor", "--help"])
+        assert result.exit_code == 0
+        assert "--verbose" in result.output