@laitszkin/apollo-toolkit 2.11.1 → 2.11.3

package/AGENTS.md

@@ -13,7 +13,7 @@ This repository enables users to install and run a curated set of reusable agent
 
 - Users can align project documentation with the current codebase.
 - Users can consolidate completed project specs into a standardized README and categorized project documentation set, then archive the consumed planning files.
-- Users can investigate application logs and produce evidence-backed root-cause findings.
+- Users can investigate application logs, slice them to precise time windows, search by keyword or regex, and produce evidence-backed root-cause findings.
 - Users can answer repository-backed questions with additional web research when needed.
 - Users can commit and push local changes without performing version or release work.
 - Users can manage Codex user-preference memory by reviewing the last 24 hours of chats, storing categorized memory documents under `~/.codex/memory`, and syncing a memory index into `~/.codex/AGENTS.md`.
@@ -28,7 +28,7 @@ This repository enables users to install and run a curated set of reusable agent
 - Users can extend existing features in a brownfield codebase with required tests and approvals.
 - Users can propose product features from an existing codebase and publish accepted proposals.
 - Users can discover reproducible edge-case risks and report prioritized hardening gaps.
-- Users can fix remote GitHub issues locally and submit the resulting pull requests.
+- Users can read, filter, and inspect remote GitHub issues before planning follow-up work.
 - Users can run evidence-first application security audits focused on confirmed vulnerabilities.
 - Users can learn new or improved skills from recent Codex conversation history.
 - Users can audit and maintain the skill catalog itself, including dependency classification and shared-skill extraction decisions.

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this repository are documented in this file.
 
 ## [Unreleased]
 
+## [v2.11.3] - 2026-03-24
+
+### Added
+- Add bundled `analyse-app-logs` scripts for filtering logs by bounded time windows and searching by keyword or regex, with focused tests for both helpers.
+- Add `read-github-issue` as a dedicated GitHub issue discovery skill with bundled scripts for finding issue candidates and reading a specific issue with comments.
+
+### Changed
+- Expand `open-github-issue` to support structured `performance`, `security`, `docs`, and `observability` issue categories in addition to `problem` and `feature`.
+- Refocus the former `fix-github-issues` workflow into read-only GitHub issue discovery and inspection guidance instead of a hardcoded fixing workflow.
+- Update repository capability docs and agent prompts to reflect the new GitHub issue-reading and log-search workflows.
+
+## [v2.11.2] - 2026-03-23
+
+### Changed
+- Update `develop-new-features` and `enhance-existing-features` so small localized work such as bug fixes, pure frontend polish, and simple adjustments can skip spec generation, while non-trivial feature work still uses approval-backed specs.
+- Strengthen `generate-spec` so spec creation must verify relevant official documentation for external dependencies before writing requirements or scope.
+- Refine spec templates so `spec.md` uses dedicated `In Scope` and `Out of Scope` sections, checklist completion uses structured completion records, and E2E versus integration decisions support multiple per-flow records without encouraging false checkbox completion.
+
 ## [v2.11.1] - 2026-03-23
 
 ### Changed

package/README.md

@@ -19,7 +19,7 @@ A curated skill catalog for Codex, OpenClaw, and Trae with a managed installer t
 - enhance-existing-features
 - feature-propose
 - financial-research
-- fix-github-issues
+- read-github-issue
 - generate-spec
 - harden-app-security
 - improve-observability
@@ -142,7 +142,7 @@ Compatibility note:
 
 - `generate-spec` is a local skill used by `develop-new-features` and `enhance-existing-features`.
 - `maintain-skill-catalog` can conditionally use `find-skills`, but its install source is not verified in this repository, so it is intentionally omitted from the table.
-- `fix-github-issues` accepts `open-source-pr-workflow` or an environment alias named `open-pr-workflow`. Apollo Toolkit already vendors `open-source-pr-workflow`, so `open-pr-workflow` is not a required external dependency here.
+- `read-github-issue` uses GitHub CLI (`gh`) directly for remote issue discovery and inspection, so it does not add any extra skill dependency.
 
 ## Release publishing
 

package/analyse-app-logs/README.md

@@ -11,6 +11,7 @@ This skill helps agents analyze logs end-to-end, correlate runtime signals with
 - A strict evidence standard (log lines + code correlation + impact + confidence).
 - A checklist to avoid false conclusions.
 - A pattern catalog for common operational failures (timeouts, retry storms, auth errors, resource pressure, schema mismatch, race conditions, and dependency outages).
+- Bundled CLI helpers for filtering logs to a specific time window and searching by keyword or regex.
 - GitHub issue publication via the `open-github-issue` dependency skill.
 - Issue language selection delegated to `open-github-issue` based on the target repository README: Chinese README -> localized issue body, otherwise English issue body.
 
@@ -20,6 +21,9 @@ This skill helps agents analyze logs end-to-end, correlate runtime signals with
 - `agents/openai.yaml`: Agent interface metadata and default prompt.
 - `references/investigation-checklist.md`: Investigation validation checklist.
 - `references/log-signal-patterns.md`: Log signal pattern reference.
+- `scripts/filter_logs_by_time.py`: Time-window log filtering helper.
+- `scripts/search_logs.py`: Keyword / regex search helper with optional context.
+- `scripts/log_cli_utils.py`: Shared timestamp parsing utilities.
 - Dependency skill: `open-github-issue` for deterministic issue publishing.
 
 ## Installation
@@ -65,6 +69,14 @@ Best results come from including:
 
 When the time window is not explicitly provided, the skill should first derive a bounded analysis window from a recent concrete event, such as the last container restart, and inspect only that slice before widening the search.
 
+Useful bundled commands:
+
+```bash
+python3 scripts/filter_logs_by_time.py app.log --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:30:00Z"
+python3 scripts/search_logs.py app.log --keyword timeout --keyword payment --mode all --after-context 3
+python3 scripts/search_logs.py app.log --regex "request_id=ab12.*ERROR" --start "2026-03-24T10:00:00Z" --end "2026-03-24T10:15:00Z"
+```
+
 ## Example
 
 ### Input prompt

package/analyse-app-logs/SKILL.md

@@ -15,7 +15,7 @@ description: Comprehensive application log investigation workflow that reads log
 ## Standards
 
 - Evidence: Use a bounded investigation window and correlate log lines with code, runtime context, and concrete identifiers.
-- Execution: Scope the incident, build a timeline, validate candidate issues, then prioritize and optionally publish them.
+- Execution: Scope the incident, use the bundled scripts to cut logs down by time window or search terms, build a timeline, validate candidate issues, then prioritize and optionally publish them.
 - Quality: Separate confirmed issues from hypotheses and include time-window, log, code, impact, and confidence evidence for each report.
 - Output: Return incident summary, confirmed issues, hypotheses, monitoring improvements, and publication status.
 
@@ -38,9 +38,11 @@ Use this skill to analyze application logs systematically with the codebase and
    - If the user does not provide a trustworthy window, derive one from a concrete runtime boundary first, such as the last container restart, pod recreation, deploy start, worker boot, or first failure after a known healthy state.
    - Prefer analyzing logs only inside that bounded window first (for example, from the last restart until now) to avoid stale logs polluting the diagnosis; widen the window only when the bounded slice cannot explain the symptom.
    - Identify relevant identifiers (trace ID, request ID, user ID, job ID, tx hash).
+   - Use `scripts/filter_logs_by_time.py` first when the raw log set is large and the incident window can be bounded.
 2. Build a timeline from logs
    - Extract key events in chronological order within the chosen window: deploys, config changes, warnings, errors, retries, and recoveries.
    - Group repeated symptoms by signature (error type, message prefix, stack frame, endpoint).
+   - Use `scripts/search_logs.py` to narrow by error signature, IDs, endpoint names, or repeated keywords before summarizing the timeline.
 3. Correlate across context
    - Link related log lines using identifiers and timestamps.
    - Map stack traces and log messages to exact code locations.
@@ -118,4 +120,7 @@ Use this structure in responses:
 
 - `references/investigation-checklist.md`: Step-by-step checklist for evidence-driven log investigations.
 - `references/log-signal-patterns.md`: Common log signatures, likely causes, validation hints, and false-positive guards.
+- `scripts/filter_logs_by_time.py`: Filter raw logs to a bounded incident window from files or stdin.
+- `scripts/search_logs.py`: Search logs by keyword or regex with optional time-window filtering and context lines.
+- `scripts/log_cli_utils.py`: Shared timestamp parsing and stdin/file iteration utilities for the bundled log scripts.
 - Dependency skill: `open-github-issue` for deterministic issue publishing with auth fallback and README language detection.

package/analyse-app-logs/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "Analyse App Logs"
   short_description: "Analyze logs with code context to detect issues"
-  default_prompt: "Use $analyse-app-logs to inspect application logs with code context, first anchor the investigation to a bounded recent time window such as the last container restart or deploy, identify evidence-backed issues, suggest concrete remediation steps, and delegate confirmed GitHub issue publication to $open-github-issue."
+  default_prompt: "Use $analyse-app-logs to inspect application logs with code context, first anchor the investigation to a bounded recent time window such as the last container restart or deploy, use the bundled log-filter and log-search scripts to narrow the evidence set precisely, identify evidence-backed issues, suggest concrete remediation steps, and delegate confirmed GitHub issue publication to $open-github-issue."

package/analyse-app-logs/scripts/filter_logs_by_time.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from log_cli_utils import ensure_timezone, extract_timestamp, in_window, iter_input_lines, parse_cli_timestamp
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Filter log lines by timestamp window from files or stdin."
+    )
+    parser.add_argument("paths", nargs="*", help="Log file paths. Reads stdin when omitted.")
+    parser.add_argument("--start", help="Inclusive start timestamp.")
+    parser.add_argument("--end", help="Inclusive end timestamp.")
+    parser.add_argument(
+        "--assume-timezone",
+        default="UTC",
+        help="Timezone for naive timestamps and --start/--end values. Default: UTC.",
+    )
+    parser.add_argument(
+        "--keep-undated",
+        action="store_true",
+        help="Keep lines without a parseable timestamp.",
+    )
+    parser.add_argument(
+        "--count-only",
+        action="store_true",
+        help="Print only the count of matching lines.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    assume_timezone = ensure_timezone(args.assume_timezone)
+    start = parse_cli_timestamp(args.start, assume_timezone) if args.start else None
+    end = parse_cli_timestamp(args.end, assume_timezone) if args.end else None
+
+    if start and end and start > end:
+        print("Error: --start must be earlier than or equal to --end.", file=sys.stderr)
+        return 1
+
+    matches = 0
+    for line in iter_input_lines(args.paths):
+        timestamp = extract_timestamp(line, assume_timezone)
+        if timestamp is None and not args.keep_undated:
+            continue
+        if timestamp is not None and not in_window(timestamp, start, end):
+            continue
+
+        matches += 1
+        if not args.count_only:
+            print(line)
+
+    if args.count_only:
+        print(matches)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/analyse-app-logs/scripts/log_cli_utils.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import re
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Iterator, Sequence
+
+
+TIMESTAMP_PATTERN = re.compile(
+    r"(?P<timestamp>"
+    r"\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:\d{2})?"
+    r")"
+)
+
+TIMESTAMP_FORMATS = (
+    "%Y-%m-%dT%H:%M:%S.%f%z",
+    "%Y-%m-%dT%H:%M:%S%z",
+    "%Y-%m-%d %H:%M:%S.%f%z",
+    "%Y-%m-%d %H:%M:%S%z",
+    "%Y-%m-%dT%H:%M:%S.%f",
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%d %H:%M:%S.%f",
+    "%Y-%m-%d %H:%M:%S",
+)
+
+
+def normalize_timestamp(raw: str) -> str:
+    value = raw.strip().replace(",", ".")
+    if value.endswith("Z"):
+        return value[:-1] + "+00:00"
+    return value
+
+
+def parse_cli_timestamp(raw: str, assume_timezone: timezone) -> datetime:
+    normalized = normalize_timestamp(raw)
+    for fmt in TIMESTAMP_FORMATS:
+        try:
+            parsed = datetime.strptime(normalized, fmt)
+        except ValueError:
+            continue
+        if parsed.tzinfo is None:
+            return parsed.replace(tzinfo=assume_timezone)
+        return parsed
+    raise argparse.ArgumentTypeError(f"invalid timestamp: {raw}")
+
+
+def extract_timestamp(line: str, assume_timezone: timezone) -> datetime | None:
+    match = TIMESTAMP_PATTERN.search(line)
+    if not match:
+        return None
+    try:
+        return parse_cli_timestamp(match.group("timestamp"), assume_timezone)
+    except argparse.ArgumentTypeError:
+        return None
+
+
+def build_timezone(raw: str) -> timezone:
+    if raw.upper() == "UTC":
+        return timezone.utc
+
+    match = re.fullmatch(r"([+-])(\d{2}):(\d{2})", raw)
+    if not match:
+        raise argparse.ArgumentTypeError("timezone must be UTC or ±HH:MM")
+
+    sign, hours, minutes = match.groups()
+    total_minutes = int(hours) * 60 + int(minutes)
+    if sign == "-":
+        total_minutes *= -1
+    return timezone.utc if total_minutes == 0 else timezone(timedelta(minutes=total_minutes))
+
+
+def iter_input_lines(paths: Sequence[str]) -> Iterator[str]:
+    if not paths:
+        import sys
+
+        for line in sys.stdin:
+            yield line.rstrip("\n")
+        return
+
+    for raw_path in paths:
+        if raw_path == "-":
+            import sys
+
+            for line in sys.stdin:
+                yield line.rstrip("\n")
+            continue
+
+        path = Path(raw_path)
+        with path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                yield line.rstrip("\n")
+
+
+def in_window(
+    timestamp: datetime | None,
+    start: datetime | None,
+    end: datetime | None,
+) -> bool:
+    if timestamp is None:
+        return False
+    if start and timestamp < start:
+        return False
+    if end and timestamp > end:
+        return False
+    return True
+
+
+def ensure_timezone(value: str) -> timezone:
+    return build_timezone(value)

package/analyse-app-logs/scripts/search_logs.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections import deque
+from typing import Callable
+
+from log_cli_utils import ensure_timezone, extract_timestamp, in_window, iter_input_lines, parse_cli_timestamp
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Search log lines by keyword or regex, with optional time filtering."
+    )
+    parser.add_argument("paths", nargs="*", help="Log file paths. Reads stdin when omitted.")
+    parser.add_argument(
+        "--keyword",
+        action="append",
+        default=[],
+        help="Keyword to match. Repeat for multiple values.",
+    )
+    parser.add_argument(
+        "--regex",
+        action="append",
+        default=[],
+        help="Regular expression to match. Repeat for multiple values.",
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["any", "all"],
+        default="any",
+        help="Require any or all patterns to match. Default: any.",
+    )
+    parser.add_argument(
+        "--ignore-case",
+        action="store_true",
+        help="Case-insensitive matching for keywords and regex.",
+    )
+    parser.add_argument("--start", help="Inclusive start timestamp.")
+    parser.add_argument("--end", help="Inclusive end timestamp.")
+    parser.add_argument(
+        "--assume-timezone",
+        default="UTC",
+        help="Timezone for naive timestamps and --start/--end values. Default: UTC.",
+    )
+    parser.add_argument(
+        "--before-context",
+        type=int,
+        default=0,
+        help="Print N lines of context before each match.",
+    )
+    parser.add_argument(
+        "--after-context",
+        type=int,
+        default=0,
+        help="Print N lines of context after each match.",
+    )
+    parser.add_argument(
+        "--count-only",
+        action="store_true",
+        help="Print only the number of matching lines.",
+    )
+    return parser.parse_args()
+
+
+def build_matchers(args: argparse.Namespace) -> list[Callable[[str], bool]]:
+    flags = re.IGNORECASE if args.ignore_case else 0
+    matchers: list[Callable[[str], bool]] = []
+
+    for keyword in args.keyword:
+        needle = keyword.lower() if args.ignore_case else keyword
+
+        def match_keyword(line: str, needle: str = needle) -> bool:
+            haystack = line.lower() if args.ignore_case else line
+            return needle in haystack
+
+        matchers.append(match_keyword)
+
+    for pattern in args.regex:
+        compiled = re.compile(pattern, flags)
+        matchers.append(lambda line, compiled=compiled: bool(compiled.search(line)))
+
+    return matchers
+
+
+def line_matches(line: str, matchers: list[Callable[[str], bool]], mode: str) -> bool:
+    if not matchers:
+        return True
+    results = [matcher(line) for matcher in matchers]
+    return any(results) if mode == "any" else all(results)
+
+
+def main() -> int:
+    args = parse_args()
+    assume_timezone = ensure_timezone(args.assume_timezone)
+    start = parse_cli_timestamp(args.start, assume_timezone) if args.start else None
+    end = parse_cli_timestamp(args.end, assume_timezone) if args.end else None
+    if start and end and start > end:
+        print("Error: --start must be earlier than or equal to --end.", file=sys.stderr)
+        return 1
+
+    matchers = build_matchers(args)
+    matches = 0
+    before_buffer: deque[str] = deque(maxlen=args.before_context)
+    after_remaining = 0
+
+    for line in iter_input_lines(args.paths):
+        timestamp = extract_timestamp(line, assume_timezone)
+        if (start or end) and not in_window(timestamp, start, end):
+            before_buffer.append(line)
+            continue
+
+        is_match = line_matches(line, matchers, args.mode)
+
+        if is_match:
+            matches += 1
+            if not args.count_only:
+                while before_buffer:
+                    print(before_buffer.popleft())
+                print(line)
+            after_remaining = args.after_context
+        elif after_remaining > 0 and not args.count_only:
+            print(line)
+            after_remaining -= 1
+
+        before_buffer.append(line)
+
+    if args.count_only:
+        print(matches)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/analyse-app-logs/tests/test_filter_logs_by_time.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import tempfile
+import unittest
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "filter_logs_by_time.py"
+SCRIPT_DIR = SCRIPT_PATH.parent
+if str(SCRIPT_DIR) not in __import__("sys").path:
+    __import__("sys").path.insert(0, str(SCRIPT_DIR))
+SPEC = importlib.util.spec_from_file_location("filter_logs_by_time", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class FilterLogsByTimeTests(unittest.TestCase):
+    def test_filters_lines_inside_window(self) -> None:
+        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
+            handle.write(
+                "2026-03-24T10:00:00Z INFO boot\n"
+                "2026-03-24T10:05:00Z ERROR failed\n"
+                "2026-03-24T10:10:00Z INFO recovered\n"
+            )
+            path = handle.name
+
+        args = Namespace(
+            paths=[path],
+            start="2026-03-24T10:01:00Z",
+            end="2026-03-24T10:06:00Z",
+            assume_timezone="UTC",
+            keep_undated=False,
+            count_only=False,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "sys.stdout", new_callable=io.StringIO
+        ) as stdout:
+            code = MODULE.main()
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stdout.getvalue().strip(), "2026-03-24T10:05:00Z ERROR failed")
+
+    def test_keep_undated_lines_when_requested(self) -> None:
+        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
+            handle.write(
+                "2026-03-24T10:00:00Z INFO boot\n"
+                "plain undated line\n"
+            )
+            path = handle.name
+
+        args = Namespace(
+            paths=[path],
+            start=None,
+            end=None,
+            assume_timezone="UTC",
+            keep_undated=True,
+            count_only=False,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "sys.stdout", new_callable=io.StringIO
+        ) as stdout:
+            code = MODULE.main()
+
+        self.assertEqual(code, 0)
+        self.assertIn("plain undated line", stdout.getvalue())
+
+    def test_rejects_inverted_window(self) -> None:
+        args = Namespace(
+            paths=[],
+            start="2026-03-24T10:10:00Z",
+            end="2026-03-24T10:00:00Z",
+            assume_timezone="UTC",
+            keep_undated=False,
+            count_only=False,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "sys.stderr", new_callable=io.StringIO
+        ) as stderr:
+            code = MODULE.main()
+
+        self.assertEqual(code, 1)
+        self.assertIn("--start", stderr.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/analyse-app-logs/tests/test_search_logs.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import tempfile
+import unittest
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "search_logs.py"
+SCRIPT_DIR = SCRIPT_PATH.parent
+if str(SCRIPT_DIR) not in __import__("sys").path:
+    __import__("sys").path.insert(0, str(SCRIPT_DIR))
+SPEC = importlib.util.spec_from_file_location("search_logs", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class SearchLogsTests(unittest.TestCase):
+    def test_keyword_search_respects_time_window(self) -> None:
+        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
+            handle.write(
+                "2026-03-24T10:00:00Z INFO boot\n"
+                "2026-03-24T10:05:00Z ERROR payment timeout\n"
+                "2026-03-24T10:10:00Z ERROR payment timeout\n"
+            )
+            path = handle.name
+
+        args = Namespace(
+            paths=[path],
+            keyword=["timeout"],
+            regex=[],
+            mode="any",
+            ignore_case=False,
+            start="2026-03-24T10:01:00Z",
+            end="2026-03-24T10:06:00Z",
+            assume_timezone="UTC",
+            before_context=0,
+            after_context=0,
+            count_only=False,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "sys.stdout", new_callable=io.StringIO
+        ) as stdout:
+            code = MODULE.main()
+
+        self.assertEqual(code, 0)
+        self.assertEqual(
+            stdout.getvalue().strip(),
+            "2026-03-24T10:05:00Z ERROR payment timeout",
+        )
+
+    def test_all_mode_requires_every_matcher(self) -> None:
+        matchers = [
+            lambda line: "timeout" in line,
+            lambda line: "payment" in line,
+        ]
+
+        self.assertTrue(MODULE.line_matches("payment timeout", matchers, "all"))
+        self.assertFalse(MODULE.line_matches("timeout only", matchers, "all"))
+
+    def test_count_only_reports_match_total(self) -> None:
+        with tempfile.NamedTemporaryFile("w+", encoding="utf-8", delete=False) as handle:
+            handle.write(
+                "2026-03-24T10:00:00Z INFO boot\n"
+                "2026-03-24T10:05:00Z ERROR payment timeout\n"
+                "2026-03-24T10:06:00Z WARN retry timeout\n"
+            )
+            path = handle.name
+
+        args = Namespace(
+            paths=[path],
+            keyword=["timeout"],
+            regex=[],
+            mode="any",
+            ignore_case=True,
+            start=None,
+            end=None,
+            assume_timezone="UTC",
+            before_context=0,
+            after_context=0,
+            count_only=True,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch(
+            "sys.stdout", new_callable=io.StringIO
+        ) as stdout:
+            code = MODULE.main()
+
+        self.assertEqual(code, 0)
+        self.assertEqual(stdout.getvalue().strip(), "2")
+
+
+if __name__ == "__main__":
+    unittest.main()