From 7bea4c16e6f5d36b7cf2dd44e695c60fe1181619 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 14:53:28 +0200
Subject: [PATCH 01/40] fix typos in docs

---
 README.md                             |  2 +-
 docs/alert_aggregator.md              |  2 +-
 docs/auxiliar/input_buffer.md         |  2 +-
 docs/contribution.md                  | 14 ++---
 docs/detectors.md                     |  4 +-
 docs/examples/others/basic_usage.py   | 75 ---------------------------
 docs/examples/others/federation.py    |  4 +-
 docs/parsers.md                       |  2 +-
 docs/parsers/template_tree_matcher.md |  2 +-
 docs/schemas.md                       |  2 +-
 docs/user_guide/basic_knowledge.md    |  4 +-
 11 files changed, 19 insertions(+), 94 deletions(-)
 delete mode 100644 docs/examples/others/basic_usage.py

diff --git a/README.md b/README.md
index 1f6050a2..72a284da 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ The library contains the next components:
 * **Parsers**: parse the logs received from the reader.
 * **Detectors**: return alerts if anomalies are detected.
 * **Alert Aggregation**: aggregate the alerts produced by the detectors.
-* **Schemas**: standard data classes use in DetectMate.
+* **Schemas**: standard data classes used in DetectMate.
 ```
  +--------+     +-----------+    +-------------------+
  | Parser | --> |  Detector | -> | Alert Aggregation |
diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index 300d2a89..c70294db 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -7,7 +7,7 @@ Alert aggregation aggregates alerts from detectors.
 | **Input**  | [DetectorSchema](schemas.md)    | Alerts from detectors  |
 | **Output** | [AggregateSchema](schemas.md) | Aggregated alerts    |
 
-This document explains expected APIs, how to implement a parser, testing tips and common pitfalls.
+This document explains expected APIs, how to implement an alert aggregator, testing tips and common pitfalls.
 
 ## Overview
 
diff --git a/docs/auxiliar/input_buffer.md b/docs/auxiliar/input_buffer.md
index dcd7f17f..afb2295d 100644
--- a/docs/auxiliar/input_buffer.md
+++ b/docs/auxiliar/input_buffer.md
@@ -1,6 +1,6 @@
 #  Data Buffer
 
-The data buffer is an auxiliar methods that can be use in all the components. It takes the stream data and formated to the specifications given.
+The data buffer is an auxiliary method that can be used in all the components. It takes the stream data and formats it to the given specifications.
 
 It has different configuration states to configure its behaviour.
 
diff --git a/docs/contribution.md b/docs/contribution.md
index d517c2c8..64b81925 100644
--- a/docs/contribution.md
+++ b/docs/contribution.md
@@ -12,7 +12,7 @@ at least the following information in a bug report:
 
 1. Description of the bug. Describe the problem clearly.
 2. Steps to reproduce. With the following configuration, go to.., click.., see error
-3. Expected behavoir. What should happen?
+3. Expected behavior. What should happen?
 4. Environment. What was the environment for the test(version, browser, etc..)
 
 *Please don't include any private/sensitive information in your issue! For reporting security-related issues, see [SECURITY.md](https://github.com/ait-detectmate/DetectMateLibrary/blob/main/SECURITY.md)*
@@ -39,7 +39,7 @@ git clone -b development git@github.com:YOURUSERNAME/DetectMateLibrary.git
 
 ### 3. Create a feature branch
 
-Every single workpackage should be developed in it's own feature-branch. Use a name that describes the feature:
+Every single workpackage should be developed in its own feature-branch. Use a name that describes the feature:
 
 ```bash
 cd DetectMateLibrary
@@ -48,7 +48,7 @@ git checkout -b feature-some_important_work
 
 ### 4. Develop your feature and improvements in the feature-branch
 
-Please make sure that you commit only improvements that are related to the workpage you created the feature-branch for.
+Please make sure that you commit only improvements that are related to the workpackage you created the feature-branch for.
 
 ### 5. Fetch and merge from the upstream
 
@@ -103,13 +103,13 @@ git rebase -i HEAD~2
 
 Delete your local feature-branch after the pull-request was merged into the development branch.
 
-### 8. Update your local main branch
+### 8. Update your local development branch
 
 Update your local development branch:
 
 ```bash
 git fetch upstream development
-git checkout -b development
+git checkout development
 git rebase upstream/development
 ```
 
@@ -117,9 +117,9 @@ Additional infos:
 
 - [https://www.atlassian.com/git/tutorials/merging-vs-rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
 
-### 9. Update your main branch in your github-repository
+### 9. Update the development branch in your GitHub repository
 
-Please make sure that you updated your local development branch as described in section 8. above. After that push the changes to your github-repository to keep it up2date:
+Please make sure that you updated your local development branch as described in section 8. above. After that push the changes to your github-repository to keep it up to date:
 
 ```bash
 git push
diff --git a/docs/detectors.md b/docs/detectors.md
index cfabb06f..2460fbca 100644
--- a/docs/detectors.md
+++ b/docs/detectors.md
@@ -127,7 +127,7 @@ The detectors are numbered from simplest to most complex, and the sidebar lists
 Every detector page shows a minimal, working configuration file next to its example. The
 reference below explains the blocks those files use.
 
-When `auto_config` is set to `False`, the detector expects an explicit `events` or `global` block that specifies exactly which variables to monitor. `events`refers to event-specific variables while `global` refers to variables, that are not bound to events (`header_variables`can but don't have to be event bound):
+When `auto_config` is set to `False`, the detector expects an explicit `events` or `global` block that specifies exactly which variables to monitor. `events` refers to event-specific variables while `global` refers to variables, that are not bound to events (`header_variables` can but don't have to be event bound):
 
 ```yaml
 detectors:
@@ -154,7 +154,7 @@ detectors:
 
 ### Common parameters (all detectors)
 
-There are some parameters, that **every** detector inhertis from `CoreDetectorConfig`/`CoreConfig`/`BasicConfig`, regardless of what it does. The other parameters, that are **specific** for the respective detector, are explained right at the detectors documentation page, later on.
+There are some parameters, that **every** detector inherits from `CoreDetectorConfig`/`CoreConfig`/`BasicConfig`, regardless of what it does. The other parameters, that are **specific** for the respective detector, are explained right at the detectors documentation page, later on.
 
 <!-- Start common_arguments -->
 ???+ note "Top level"
diff --git a/docs/examples/others/basic_usage.py b/docs/examples/others/basic_usage.py
deleted file mode 100644
index dbf95c17..00000000
--- a/docs/examples/others/basic_usage.py
+++ /dev/null
@@ -1,75 +0,0 @@
-# flake8: noqa
-log_path = "tests/test_data/logs.log"
-templates_path = "tests/test_data/audit_templates.txt"
-parsed_path = "parsed_logs.json"
-log_json = "logs.json"
-alert_path = "alerts.json"
-
-
-# --8<-- [start:example_1]
-from detectmatelibrary.parsers.template_matcher import MatcherParser
-from detectmatelibrary.helper.from_to import From, To
-
-
-config_dict = {
-    "parsers": {
-        "MatcherParser": {
-            "auto_config": True,
-            "method_type": "matcher_parser",
-            "path_templates": templates_path,
-            "log_format": r'type=<Type> msg=audit\(<Time>:<Serial>\): <Content>'
-        }
-    }
-}
-parser = MatcherParser(name="MatcherParser", config=config_dict)
-
-
-for i, log in enumerate(From.log(parser, log_path, do_process=False)):
-    To.json(log, log_json)
-
-    parsed_log = parser.process(log)
-    To.json(parsed_log, parsed_path)
-
-# --8<-- [end:example_1]
-
-# --8<-- [start:example_2]
-from detectmatelibrary.detectors.random_detector import RandomDetector
-from detectmatelibrary.helper.from_to import From, To, FromTo
-
-config_dict = {
-    "detectors": {
-        "RandomDetector": {
-            "auto_config": False,
-            "method_type": "random_detector",
-            "params": {},
-            "events": {
-                1: {
-                    "test": {
-                        "params": {},
-                        "variables": [{
-                            "pos": 0,
-                            "name": "process",
-                            "params": {
-                                "threshold": 0.
-                            }
-                        }]
-                    }
-                }
-            }
-        }
-    }
-}
-detector =  RandomDetector(name="RandomDetector", config=config_dict)
-
-for alert in FromTo.json2json(detector, parsed_path, alert_path):
-    if alert is not None:
-        print("Anomaly detected!")
-
-# --8<-- [end:example_2]
-
-import os
-
-os.remove(parsed_path)
-os.remove(log_json)
-if os.path.exists(alert_path):
-    os.remove(alert_path)
diff --git a/docs/examples/others/federation.py b/docs/examples/others/federation.py
index 8e21ffa2..1d6d9c53 100644
--- a/docs/examples/others/federation.py
+++ b/docs/examples/others/federation.py
@@ -37,7 +37,7 @@ def from_binary(self, binary):
 
 detector2.aggregate()  # Detector 2 is used as centralize node
 
-print("Dectector 3", detector3.elems)  # All detectors have been updated
+print("Detector 3", detector3.elems)  # All detectors have been updated
 
 # --8<-- [end:example_2]
 
@@ -50,7 +50,7 @@ def from_binary(self, binary):
 
 detector2.aggregate()  # Detector 2 is used as centralize node
 
-print("Dectector 3", detector3.elems)  # All detectors have been updated
+print("Detector 3", detector3.elems)  # All detectors have been updated
 # --8<-- [end:example_3]
 
 # --8<-- [start:example_4]
diff --git a/docs/parsers.md b/docs/parsers.md
index 01247e1a..233312b4 100644
--- a/docs/parsers.md
+++ b/docs/parsers.md
@@ -118,7 +118,7 @@ def test_my_parser_parse():
 
 ### Common parameters (all parsers)
 
-There are some parameters, that **every** parser inhertis from `CoreParserrConfig`/`CoreConfig`/`BasicConfig`, regardless of what it does. The other parameters, that are **specific** for the respective parser, are explained right at the parsers documentation page, later on.
+There are some parameters, that **every** parser inherits from `CoreParserConfig`/`CoreConfig`/`BasicConfig`, regardless of what it does. The other parameters, that are **specific** for the respective parser, are explained right at the parsers documentation page, later on.
 
 <!-- Start common_arguments -->
 ???+ note "Top level"
diff --git a/docs/parsers/template_tree_matcher.md b/docs/parsers/template_tree_matcher.md
index 8d74432c..328da50d 100644
--- a/docs/parsers/template_tree_matcher.md
+++ b/docs/parsers/template_tree_matcher.md
@@ -2,7 +2,7 @@
 
 The Template Tree Matcher is a parser that matches incoming logs against a set of templates using a tree-based depth-first search. It provides faster matching for batch workloads compared with the streaming Template Matcher.
 
-This parser wraps functionality from the DetectMatePerformance project: https://github.com/ait-detectmate/DetectMatePerformance. Prefer  use the performance implementation when parsing many log lines in non-stream (batch) mode.
+This parser wraps functionality from the DetectMatePerformance project: https://github.com/ait-detectmate/DetectMatePerformance. Prefer the performance implementation when parsing many log lines in non-stream (batch) mode.
 
 ## In/out
 
diff --git a/docs/schemas.md b/docs/schemas.md
index 9e1fd588..eafcca36 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -57,7 +57,7 @@ class BaseSchema:
         """Check equality between two schema instances."""
 ```
 
-## Schema Clases
+## Schema Classes
 
 Below are the primary schema classes and their main fields. All fields are optional at the Protobuf level; components should document which fields they require.
 
diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index ab096de2..ff7fd6f4 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -61,7 +61,7 @@ INFO [18-05-2005] hello I am a log about DetectMate getting started
 This line has three parts:
 
 - **`INFO` -- the category of the message (the "log level").** Some other
-messages from the programm could be for example `DEBUG` (fine-grained detail for developers) or `WARNING` (something looks off, but it´s not a failure yet). So this part just gives you a hint how important this logging statement is.
+messages from the program could be for example `DEBUG` (fine-grained detail for developers) or `WARNING` (something looks off, but it's not a failure yet). So this part just gives you a hint how important this logging statement is.
 
 - **`[18-05-2005]` -- the timestamp:** when the message was written.
 
@@ -80,7 +80,7 @@ The pattern that tells the parser how to split a line is called the
 so the parser knows which chunk is the log level, which is the timestamp, and
 which is the actual message content.
 
-The term `log_format`is regularly used in the literature. Such as in the
+The term `log_format` is regularly used in the literature. Such as in the
 **Drain-Parser**, **LogParser**, and many more use it frequently.
 
 Based on the example above:

From ccf28016928fa638ac6843f7cde0ba95c2d30dd3 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 14:57:43 +0200
Subject: [PATCH 02/40] improve wording

---
 docs/detectors/combo.md           | 2 +-
 docs/parsers/json_parser.md       | 2 +-
 docs/parsers/logbatcher_parser.md | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/detectors/combo.md b/docs/detectors/combo.md
index b88171a1..00b22642 100644
--- a/docs/detectors/combo.md
+++ b/docs/detectors/combo.md
@@ -1,6 +1,6 @@
 # New Value Combo Detector
 
-The New Value Combo Detector raises alerts when previously unseen combinations of values appear in configured fields (for example new user names, IP addresses, or process names). It is useful to detect novelty, configuration drift, or the appearance of new actors in the environment.
+The New Value Combo Detector raises alerts when previously unseen combinations of values appear in configured fields (for example a known user logging in from a known IP address they have never used before). It is useful to detect unusual pairings of otherwise familiar values, which the [New Value Detector](new_value.md) would miss.
 
 ## In/out
 
diff --git a/docs/parsers/json_parser.md b/docs/parsers/json_parser.md
index a393c7c2..8b6ece4c 100644
--- a/docs/parsers/json_parser.md
+++ b/docs/parsers/json_parser.md
@@ -25,7 +25,7 @@ With the configuration file below, the `message` field is also matched against t
 
 ## Configuration file
 
-The configuration used by the example above. It sets only what this use case needs; every other parameter keeps its default (see [Configuration arguments](#configuration-arguments)).
+The configuration used by the second example above (the first one runs with all defaults). It sets only what this use case needs; every other parameter keeps its default (see [Configuration arguments](#configuration-arguments)).
 
 ```yaml
 --8<-- "docs/examples/parsers/json_parser.yaml"
diff --git a/docs/parsers/logbatcher_parser.md b/docs/parsers/logbatcher_parser.md
index cf5aeb8d..f339f1b5 100644
--- a/docs/parsers/logbatcher_parser.md
+++ b/docs/parsers/logbatcher_parser.md
@@ -46,7 +46,7 @@ Using a local Ollama instance:
 
 ## Configuration file
 
-The configuration used by the example above. It sets only what this use case needs; every other parameter keeps its default (see [Configuration arguments](#configuration-arguments)).
+The configuration used by the first example above (the Ollama example builds its configuration in Python instead). It sets only what this use case needs; every other parameter keeps its default (see [Configuration arguments](#configuration-arguments)).
 
 ```yaml
 --8<-- "docs/examples/parsers/logbatcher_parser.yaml"

From e67bcec124bbdc55c94d65ab1b85c66bdd402fe6 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:04:26 +0200
Subject: [PATCH 03/40] correct hw to test docs examples

---
 docs/development.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/docs/development.md b/docs/development.md
index ea498c8b..c4fc5644 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -109,7 +109,7 @@ files under `docs/examples/`, mirrored by category (`docs/examples/parsers/`,
 `docs/examples/detectors/`), and are pulled into the Markdown pages via
 [`pymdownx.snippets`](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/).
 This way every snippet in the docs is an actual `.py` file that gets executed by
-the test suite, so a broken example fails CI instead of silently shipping.
+the test suite in CI, so a broken example fails CI instead of silently shipping.
 
 **1. Add the snippet file.** Put your example under `docs/examples/<category>/`.
 By convention the filename matches its documentation page (`charset.md` →
@@ -142,11 +142,12 @@ globs every `.py` under `docs/examples/` and runs each one as a script via
 `runpy.run_path(..., run_name="__main__")`. There is no plugin and no assert
 requirement: a snippet passes as long as it runs standalone without raising. If
 your example needs something unavailable in CI (e.g. an API key), comment out
-those calls rather than letting them fail. Run the snippet tests together with
-the rest of the suite:
+those calls rather than letting them fail. The test is marked `ignored`, so a
+plain `pytest` run skips it; pass `--run-ignored` (as CI does) to include it:
 
 ```bash
-uv run --dev pytest
+uv run --dev pytest --run-ignored                    # whole suite, snippets included
+uv run --dev pytest tests/test_docs --run-ignored    # snippets only
 ```
 
 **4. Component pages: a YAML file, and generated argument tables.** Each parser and
@@ -177,7 +178,7 @@ For a live local preview while editing:
 uv run --dev mkdocs serve
 ```
 
-`mkdocs` comes in transitively via `mike` in the `dev` group, so `--dev` is
-required. There is no `--strict` mode configured; the hard check on the docs is
+`mkdocs` comes in via `mkdocs-material` (a direct dependency of the `dev` group),
+so `--dev` is required. There is no `--strict` mode configured; the hard check on the docs is
 `check_paths: true` from `pymdownx.snippets`, which fails the build on a missing
 snippet or marker.

From 9917096909acfe5607968329e98ea243472b390e Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:04:36 +0200
Subject: [PATCH 04/40] typo

---
 docs/federation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/federation.md b/docs/federation.md
index fa9ccdce..e824d16d 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -51,7 +51,7 @@ Example 2:
 --8<-- "docs/examples/others/federation.py:example_3"
 ```
 
-## Stack
+## Stack later
 
 The diagram below shows the workflow:
 

From 9475bb62f7b39582fd2673ed86ed4f37deb8a067 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:05:37 +0200
Subject: [PATCH 05/40] parser schema and imports in example

---
 docs/parsers.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/parsers.md b/docs/parsers.md
index 233312b4..d1276fe0 100644
--- a/docs/parsers.md
+++ b/docs/parsers.md
@@ -32,7 +32,7 @@ class CoreParser:
         - Return True if parsing succeeded and output_ contains a result.
         """
 
-    def train(self, input_: Iterable[schemas.LogSchema]) -> None:
+    def train(self, input_: schemas.LogSchema) -> None:
         """Optional: train internal models. Can be a no-op for stateless parsers."""
 ```
 
@@ -57,9 +57,11 @@ Example:
 
 ```python
 # filepath: src/detectmatelibrary/parsers/my_parser.py
+import time
+from typing import Any
+
 from detectmatelibrary.common.parser import CoreParser, CoreParserConfig
 from detectmatelibrary import schemas
-from typing import Any
 
 
 class MyParserConfig(CoreParserConfig):

From 4d2b350a322495fba2a2d6ea9d5ef803b7e8ee39 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:06:22 +0200
Subject: [PATCH 06/40] value range description

---
 docs/detectors/value_range.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/detectors/value_range.md b/docs/detectors/value_range.md
index 44f24a6d..21220d98 100644
--- a/docs/detectors/value_range.md
+++ b/docs/detectors/value_range.md
@@ -1,6 +1,6 @@
 # Value Range Detector
 
-The Value Range Detector raises alerts when numerical values outside of known ranges appear in configured fields. It is useful to detect unexpected changes, configuration drift, or the appearance of new actors in the environment.
+The Value Range Detector raises alerts when numerical values outside of known ranges appear in configured fields. It is useful to detect unexpected changes in quantities such as sizes, counts, or durations.
 
 ## In/out
 
@@ -19,7 +19,7 @@ Input and output schemas in the pipeline
 
 ## Description
 
-This detector maintains a lightweight set of observed values per monitored field and emits an alert when a value outside the learned range is seen (subject to configuration).
+This detector keeps only the minimum and maximum value seen during training for each monitored field, so its memory use stays constant however many values it sees. It emits an alert when a value falls outside that range (subject to configuration).
 
 ## Example
 

From 97107636c1ac96827d09bebc11eb91b6d4fded44 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:06:44 +0200
Subject: [PATCH 07/40] remove duplication

---
 docs/user_guide/what_is_detectmate.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/what_is_detectmate.md b/docs/user_guide/what_is_detectmate.md
index 3c9f3d88..0feb3443 100644
--- a/docs/user_guide/what_is_detectmate.md
+++ b/docs/user_guide/what_is_detectmate.md
@@ -1,6 +1,6 @@
 # What is DetectMate?
 
-Welcome to the documentation for the DetectMate Library. DetectMate is a library for anomaly detection in log data.
+DetectMate is a library for anomaly detection in log data.
 It is built from ready-made building blocks (parsers, detectors and aggregators) that you combine into a detection pipeline.
 
 ## Why use DetectMate?

From 7893aafd3d6148f72205581a1fcc6b8bf5703e5a Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:52:26 +0200
Subject: [PATCH 08/40] wording

---
 docs/user_guide/basic_knowledge.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index ff7fd6f4..b3dd028d 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -1,6 +1,6 @@
 # Basic knowledge
 
-Before you continue we have to give some insights on the rudimental topics of log anomaly detection.
+This page introduces the basic concepts you need before using DetectMate for log anomaly detection.
 
 ## What is a log?
 

From a2f5b111b599830f28e006ff2ad26b716b34df54 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:57:06 +0200
Subject: [PATCH 09/40] correct example

---
 docs/user_guide/basic_knowledge.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index b3dd028d..ad31d94a 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -55,7 +55,7 @@ know, but not the letter inside.
 For example:
 
 ```text
-INFO [18-05-2005] hello I am a log about DetectMate getting started
+INFO [18-05-2005] hello I am a log about DetectMate getting started and about what is a log
 ```
 
 This line has three parts:

From 71653423b6ce51256c571ffcd9a0482f3dfd0083 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 15:58:03 +0200
Subject: [PATCH 10/40] correct table

---
 docs/user_guide/basic_knowledge.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index ad31d94a..a4adbf87 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -90,11 +90,11 @@ Based on the example above:
 
 A parsed log would contain fields like:
 
-| Field              | Value                                                  |
-|--------------------|--------------------------------------------------------|
-| Template           | `hello I am a log about <*> and about <*>`              |
-| Variables          | `["DetectMate getting started", "what is a log"]`      |
-| LogFormatVariables | `{"Level": "INFO", "Time": "18-05-2005"}`              |
+| Field                | Value                                                  |
+|----------------------|--------------------------------------------------------|
+| `template`           | `hello I am a log about <*> and about <*>`              |
+| `variables`          | `["DetectMate getting started", "what is a log"]`      |
+| `logFormatVariables` | `{"Level": "INFO", "Time": "18-05-2005", "Content": "hello I am a log about DetectMate getting started and about what is a log"}` |
 
 Parsed logs expose structured data that downstream detection components use for
 anomaly detection.

From dff268011340681dd961abad666d0b3b7eac3b54 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 16:13:07 +0200
Subject: [PATCH 11/40] typo

---
 docs/user_guide/tutorial.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index e16f8ddf..1c88097e 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -233,7 +233,7 @@ Two details are easy to miss here, and both matter for production configs:
 ## Common pitfalls
 
 * Manually escaping regex characters (like `(` and `)`) inside a
-  `log_format` string breaks matching
+  `log_format` string breaks matching:
   `generate_logformat_regex()` already escapes literal text for you.
 * A detector's `detect()` only checks `EventID`s it has already seen through
   `train()` at least once. If you configure a detector for an `EventID` that

From b87a70dbd781c845e1cfffc5d9483650371c5b45 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 16:15:07 +0200
Subject: [PATCH 12/40] wording

---
 docs/user_guide/tutorial.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 1c88097e..d8c57568 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -11,7 +11,7 @@ deeper:
   what each one finds
 - you combine their alerts with an alert aggregator
 
-By the end you should have seen most of what the library can do and, more
+By the end you should have seen the core workflow and, more
 importantly, understand *why* each piece behaves the way it does.
 
 ## 1. Read a different dataset from scratch

From 20d583d06470d8e835deec82b2e7afb18fd63970 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 16:19:30 +0200
Subject: [PATCH 13/40] add count vs row explanation

---
 docs/user_guide/tutorial.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index d8c57568..35c17b58 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -224,7 +224,8 @@ Two details are easy to miss here, and both matter for production configs:
   refer to  --  that's why most rows above pair up alerts from *different*
   underlying logs. The two rows where both `logIDs` are identical
   (`['4', '4']` and `['7', '7']`) are the exception, and not a coincidence:
-  those are exactly the log `#5` and `#8` cases from step 3, where
+  those are exactly the log `#5` and `#8` cases from step 3 (`logIDs` count
+  from 0 while the table above counts from 1, so logID `4` is row `#5`), where
   `NewValueDetector` and `EventSequenceDetector` both alerted on the same
   event back to back, so the window happened to contain only that pair. A
   real deployment that wants alerts grouped *by log* rather than by arrival

From 04ed69b6e2396a319ab55fc11e463e85844acf2c Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 16:25:48 +0200
Subject: [PATCH 14/40] replace arrows

---
 docs/user_guide/installation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md
index 830a20bc..db1bab5a 100644
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -19,7 +19,7 @@ uv pip install --no-cache-dir <directory_detectmatelibrary>
 ## Optional dependencies
 
 Not every feature needs the same dependencies, so DetectMate uses optional
-extras --> you install only what you need.
+extras: you install only what you need.
 
 | Extra | Installs | When you need it |
 |---|---|---|

From 72c9ee9f5038d7c6b6c3fcc9d69da83ec085e5cc Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 16:26:02 +0200
Subject: [PATCH 15/40] correct file location

---
 docs/user_guide/quickstart.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/user_guide/quickstart.md b/docs/user_guide/quickstart.md
index db57e1f8..607c88b7 100644
--- a/docs/user_guide/quickstart.md
+++ b/docs/user_guide/quickstart.md
@@ -18,7 +18,7 @@ detector to check whether the dataset contains anomalies. We use the
 ```
 ## Common pitfalls
 
-* When re-running the parser code, delete `audit_raw.json` and `audit_parsed.json`
-  first if you want to execute it again --> otherwise output is appended to stale files.
+* Before re-running the parser code, delete `local/audit_raw.json` and
+  `local/audit_parsed.json`; otherwise the new output is appended to the old files.
 
 Go back [Index](../index.md)

From 7769a0a08079745b758e657a9743958f0d759476 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Thu, 8 Oct 2026 17:04:38 +0200
Subject: [PATCH 16/40] remove stray line

---
 docs/schemas.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/schemas.md b/docs/schemas.md
index eafcca36..f992fc3d 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -36,7 +36,6 @@ class BaseSchema:
 
     def init_schema(self, kwargs: dict[str, Any] | None) -> None:
         """Initialize the schema instance and set attributes."""
-        self.var_names = set(var_names)
 
     def is_field_list(self, field_name: str) -> bool:
         """Check if a field is a list."""

From 1a3cd5c509f8d01e7f53b5e8ba4dfbbe3682d58b Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 10:45:37 +0200
Subject: [PATCH 17/40] fix typos in federation example

---
 docs/examples/others/federation.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/examples/others/federation.py b/docs/examples/others/federation.py
index 1d6d9c53..a45bd9ed 100644
--- a/docs/examples/others/federation.py
+++ b/docs/examples/others/federation.py
@@ -4,7 +4,7 @@
 import struct
 
 
-class NewComponent(CoreComponent):  # Inherent from CoreComponent
+class NewComponent(CoreComponent):  # Inherit from CoreComponent
     def __init__(self, elems):
         self.elems = elems
         super().__init__(name="FedExample")
@@ -35,7 +35,7 @@ def from_binary(self, binary):
 
 detector1 + detector2 + detector3
 
-detector2.aggregate()  # Detector 2 is used as centralize node
+detector2.aggregate()  # Detector 2 is used as central node
 
 print("Detector 3", detector3.elems)  # All detectors have been updated
 
@@ -48,7 +48,7 @@ def from_binary(self, binary):
 
 detector1 + detector2 + detector3
 
-detector2.aggregate()  # Detector 2 is used as centralize node
+detector2.aggregate()  # Detector 2 is used as central node
 
 print("Detector 3", detector3.elems)  # All detectors have been updated
 # --8<-- [end:example_3]
@@ -61,7 +61,7 @@ def from_binary(self, binary):
 detector1.stack([detector2, detector3])
 
 detector2.aggregate()
-print("Detector 3", detector3.elems)  # It is not longer combine but stack, so it will not work
+print("Detector 3", detector3.elems)  # It is no longer combined but stacked, so it will not work
 
 detector1.aggregate()
 print("Detector 3", detector3.elems)  # Now it will work
@@ -79,10 +79,10 @@ def from_binary(self, binary):
 output = detector1.aggregate(unstack=True)  # unstack = True will free memory
 
 print("Detector 1", detector1.elems)  # Detector 1 has been updated
-print("Output binary", output)  # Output that we send to other componets
+print("Output binary", output)  # Output that we send to other components
 
 # We update detector 3 now
-print("Detector 3", detector3.elems)  # Now detector 3 is not in the share memory so it will not work
+print("Detector 3", detector3.elems)  # Now detector 3 is not in the shared memory, so it will not work
 detector3 = detector3.from_binary(output)
 print("Detector 3", detector3.elems)  # Now it will work
 # --8<-- [end:example_5]

From d04a6c0dd1ad3d59ba407e39182c950d7bfd9b15 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 10:49:36 +0200
Subject: [PATCH 18/40] correct claim about BigramFrequencyDetector

---
 docs/federation.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/federation.md b/docs/federation.md
index e824d16d..be99af5c 100644
--- a/docs/federation.md
+++ b/docs/federation.md
@@ -16,7 +16,9 @@ def finalize_federation(self) -> None:
     """(Federation only) Liberate memory from federation"""
 ```
 
-The tracker detectors (subclasses of `base_detectors.TrackerDetector`: New Event, New Value, New Value Combo, Value Range, Charset, Event Sequence, Bigram Frequency, SCVS and ECVC) implement all four in `TrackerDetector`, which is the reference implementation. Set `allow_fed: true` in their `params` to enable it.
+The tracker detectors (subclasses of `base_detectors.TrackerDetector`: New Event, New Value, New Value Combo, Value Range, Charset, Event Sequence, SCVS and ECVC) implement all four in `TrackerDetector`, which is the reference implementation. Set `allow_fed: true` in their `params` to enable it.
+
+The Bigram Frequency detector is also a tracker detector, but it disables the binary transfer: its `to_binary()` returns empty bytes. It therefore supports **Combine first** only, not **Stack later**.
 
 `from_binary` rebuilds the detector as `type(self)(name=..., config=...)`, so a `TrackerDetector` subclass must be constructible from its name and config alone; give any other constructor argument a default.
 

From e4e87e75b2604bb147819e06d01e49343537eaa2 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 10:50:44 +0200
Subject: [PATCH 19/40] correct wording

---
 docs/schemas.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/schemas.md b/docs/schemas.md
index f992fc3d..0d76fc45 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -125,9 +125,9 @@ Fields:
 | description | string | Human-readable description of the alert aggregation. |
 | alertsObtain | map<string,string> | Additional alert metadata from the alert aggregation. |
 
-## Tutorial
+## Examples
 
-Small tutorials of the different schemas.
+Short examples of working with the schemas.
 
 ### Initialize a schema
 

From 8eb48d6d317d21795abae06cc63b222081343076 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 10:53:26 +0200
Subject: [PATCH 20/40] make table match schemas.proto

---
 docs/schemas.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/schemas.md b/docs/schemas.md
index 0d76fc45..c18c8b98 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -88,8 +88,8 @@ Fields:
 | logID | string | Original raw log ID (link to LogSchema). |
 | log | string | Raw log text. |
 | logFormatVariables | map<string,string> | Key/value pairs from format extraction. |
-| receivedTimestamp | int32 | Timestamp when log was received. |
-| parsedTimestamp | int32 | Timestamp when parsing completed. |
+| receivedTimestamp | int64 | Timestamp when log was received. |
+| parsedTimestamp | int64 | Timestamp when parsing completed. |
 
 ### DetectorSchema
 Output from Detectors (alerts / findings).
@@ -101,12 +101,12 @@ Fields:
 | detectorID | string | Detector instance identifier. |
 | detectorType | string | Type/name of detector. |
 | alertID | string | Unique alert identifier. |
-| detectionTimestamp | int32 | When the alert was produced. |
+| detectionTimestamp | int64 | When the alert was produced. |
 | logIDs | repeated string | IDs of logs related to the alert. |
 | score | float | Confidence/score (if applicable). |
-| extractedTimestamps | repeated int32 | Timestamps extracted from logs. |
+| extractedTimestamps | repeated int64 | Timestamps extracted from logs. |
 | description | string | Human-readable description of the alert. |
-| receivedTimestamp | int32 | When inputs were received by detector. |
+| receivedTimestamp | int64 | When inputs were received by detector. |
 | alertsObtain | map<string,string> | Additional alert metadata. |
 
 ### AggregateSchema
@@ -117,11 +117,11 @@ Fields:
 | Field | Type | Notes |
 |---|---|---|
 | detectorIDs | repeated string | List of detector instance identifier. |
-| detectorTypes | string | List of type/name of detectors. |
-| alertIDs | string | repeated list of unique alert identifier. |
-| outputTimestamp | int32 | When the aggregation was produced. |
+| detectorTypes | repeated string | List of type/name of detectors. |
+| alertIDs | repeated string | List of unique alert identifiers. |
+| outputTimestamp | int64 | When the aggregation was produced. |
 | logIDs | repeated string | IDs of logs related to the alerts. |
-| extractedTimestamps | repeated int32 | Timestamps extracted from logs. |
+| extractedTimestamps | repeated int64 | Timestamps extracted from logs. |
 | description | string | Human-readable description of the alert aggregation. |
 | alertsObtain | map<string,string> | Additional alert metadata from the alert aggregation. |
 

From f79803ffbb429f64b911fe86c218d60fb69cd5f2 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 10:58:02 +0200
Subject: [PATCH 21/40] correct logging example

---
 docs/user_guide/basic_knowledge.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index a4adbf87..df6cc643 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -10,6 +10,8 @@ states during execution. For example:
 ```python
 import logging
 
+logging.basicConfig(level=logging.INFO, format="%(message)s")  # show INFO messages, without a prefix
+
 var1 = "DetectMate getting started"
 var2 = "what is a log"
 logging.info(f"hello I am a log about {var1} and about {var2}")

From 2d024bafc2bbcadd352f0899a41586e5fd16f342 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:01:51 +0200
Subject: [PATCH 22/40] add info about event id

---
 docs/user_guide/basic_knowledge.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index df6cc643..ce405f03 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -94,6 +94,7 @@ A parsed log would contain fields like:
 
 | Field                | Value                                                  |
 |----------------------|--------------------------------------------------------|
+| `EventID`            | `0`                                                    |
 | `template`           | `hello I am a log about <*> and about <*>`              |
 | `variables`          | `["DetectMate getting started", "what is a log"]`      |
 | `logFormatVariables` | `{"Level": "INFO", "Time": "18-05-2005", "Content": "hello I am a log about DetectMate getting started and about what is a log"}` |
@@ -101,4 +102,29 @@ A parsed log would contain fields like:
 Parsed logs expose structured data that downstream detection components use for
 anomaly detection.
 
+### What is an EventID?
+
+Every distinct template is a different *kind* of event, and the parser gives
+each one a number: the **`EventID`**. All lines that match the same template get
+the same `EventID`, so `User alice logged in from 192.168.0.5` and
+`User bob logged in from 10.0.0.2` share one `EventID`, while a
+`User bob logged out` line would get another.
+
+How the number is chosen depends on the parser. With the
+[Template Matcher](../parsers/template_matcher.md), it is the position of the
+matching template in your template file, counting from `0`: the first template is
+`EventID 0`, the second `EventID 1`, and so on. In the table above the template
+file contains just one template, so the line gets `EventID 0`. A line that
+matches no template gets `EventID -1` and the template `<Not Found>`.
+
+The `EventID` is what detectors build on:
+
+- Detectors that watch variable values are configured per `EventID`: their
+  `events` block says which variables to monitor for which kind of event (see
+  [Detectors](../detectors.md#configuration)).
+- Some detectors look at nothing but the `EventID`, for example the
+  [New Event Detector](../detectors/new_event.md) (an `EventID` never seen
+  before) and the [Event Sequence Detector](../detectors/event_sequence.md) (an
+  unusual order of `EventID`s).
+
 Go back [Index](../index.md)

From 9231f6684fe6b66f21940ba55f0b1784a43bead6 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:07:11 +0200
Subject: [PATCH 23/40] let tutorial use data independent from test fixtures

---
 docs/examples/data/tutorial_audit.log                    | 9 +++++++++
 .../examples/data/tutorial_templates.txt                 | 0
 docs/examples/others/tutorial.py                         | 4 ++--
 docs/user_guide/tutorial.md                              | 9 ++++++---
 4 files changed, 17 insertions(+), 5 deletions(-)
 create mode 100644 docs/examples/data/tutorial_audit.log
 rename tests/test_data/logs_templates.txt => docs/examples/data/tutorial_templates.txt (100%)

diff --git a/docs/examples/data/tutorial_audit.log b/docs/examples/data/tutorial_audit.log
new file mode 100644
index 00000000..8d5b9f7a
--- /dev/null
+++ b/docs/examples/data/tutorial_audit.log
@@ -0,0 +1,9 @@
+type=DAEMON_START msg=audit(1757673850.240:4506): op=start ver=3.0.9 format=enriched kernel=6.6.62+rpt-rpi-2712 auid=4294967295 pid=691 uid=0 ses=4294967295 res=successAUID="unset" UID="root"
+type=CONFIG_CHANGE msg=audit(1757673850.283:3): op=set audit_backlog_limit=8192 old=64 auid=4294967295 ses=4294967295 res=1AUID="unset"
+type=SYSCALL msg=audit(1757673850.283:3): arch=c00000b7 syscall=206 success=yes exit=60 a0=3 a1=7fffc27ad8f0 a2=3c a3=0 items=0 ppid=696 pid=710 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=(none) ses=4294967295 comm="auditctl" exe="/usr/sbin/auditctl" key=(null)ARCH=aarch64 SYSCALL=sendto AUID="unset" UID="root" GID="root" EUID="root" SUID="root" FSUID="root" EGID="root" SGID="root" FSGID="root"
+type=PROCTITLE msg=audit(1757673850.283:3): proctitle=2F7362696E2F617564697463746C002D52002F6574632F61756469742F61756469742E72756C6573
+type=CONFIG_CHANGE msg=audit(1757673850.283:4): op=set audit_failure=1 old=1 auid=4294967295 ses=4294967295 res=1AUID="unset"
+type=SYSCALL msg=audit(1757673850.283:4): arch=c00000b7 syscall=206 success=yes exit=60 a0=3 a1=7fffc27ad8f0 a2=3c a3=0 items=0 ppid=696 pid=710 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=(none) ses=4294967295 comm="auditctl" exe="/usr/sbin/auditctl" key=(null)ARCH=aarch64 SYSCALL=sendto AUID="unset" UID="root" GID="root" EUID="root" SUID="root" FSUID="root" EGID="root" SGID="root" FSGID="root"
+type=PROCTITLE msg=audit(1757673850.283:4): proctitle=2F7362696E2F617564697463746C002D52002F6574632F61756469742F61756469742E72756C6573
+type=CONFIG_CHANGE msg=audit(1757673850.283:5): op=set audit_backlog_wait_time=60000 old=15000 auid=4294967295 ses=4294967295 res=1AUID="unset"
+type=SYSCALL msg=audit(1757673850.283:5): arch=c00000b7 syscall=206 success=yes exit=60 a0=3 a1=7fffc27ad8f0 a2=3c a3=0 items=0 ppid=696 pid=710 auid=4294967295 uid=0 gid=0 euid=0 suid=0 fsuid=0 egid=0 sgid=0 fsgid=0 tty=(none) ses=4294967295 comm="auditctl" exe="/usr/sbin/auditctl" key=(null)ARCH=aarch64 SYSCALL=sendto AUID="unset" UID="root" GID="root" EUID="root" SUID="root" FSUID="root" EGID="root" SGID="root" FSGID="root"
diff --git a/tests/test_data/logs_templates.txt b/docs/examples/data/tutorial_templates.txt
similarity index 100%
rename from tests/test_data/logs_templates.txt
rename to docs/examples/data/tutorial_templates.txt
diff --git a/docs/examples/others/tutorial.py b/docs/examples/others/tutorial.py
index 07be93a3..aadb78f2 100644
--- a/docs/examples/others/tutorial.py
+++ b/docs/examples/others/tutorial.py
@@ -7,7 +7,7 @@
 except NameError:  # running inside a Jupyter notebook
     ROOT = Path.cwd().resolve().parents[1]
 
-log_path = str(ROOT / "tests" / "test_data" / "logs.log")
+log_path = str(ROOT / "docs" / "examples" / "data" / "tutorial_audit.log")
 
 # do_process=False turns From.log into a pure reader: it yields raw
 # LogSchema objects without running them through a parser yet, so the
@@ -22,7 +22,7 @@
 # --8<-- [start:own_parser]
 from detectmatelibrary.parsers.template_matcher import MatcherParser  # noqa: E402
 
-templates_path = str(ROOT / "tests" / "test_data" / "logs_templates.txt")
+templates_path = str(ROOT / "docs" / "examples" / "data" / "tutorial_templates.txt")
 
 config_dict = {
     "parsers": {
diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 35c17b58..f4653560 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -19,7 +19,7 @@ importantly, understand *why* each piece behaves the way it does.
 The Quickstart uses the `audit.log` dataset, which already ships with a
 matching `audit_templates.txt`. To actually practice building
 something, this tutorial uses a different file instead:
-`tests/test_data/logs.log`. It is still Linux `auditd` output  --  same overall
+`docs/examples/data/tutorial_audit.log`. It is still Linux `auditd` output  --  same overall
 shape as the Quickstart's dataset  --  but recorded on a different machine, and
 it comes with **no template file**. That is the point: before you can parse
 it, you have to look at it.
@@ -75,8 +75,11 @@ type=<Type> msg=audit(<Time>:<Serial>): <Content>
 
 **Writing the templates.** **MatcherParser** needs a template file as an input. For each of the four content shapes above, we
 replace the parts that change between log lines with `<*>`, following the
-[template format](../parsers/template_matcher.md#template-format) rules  --  save the results in
-`tests/test_data/logs_templates.txt`:
+[template format](../parsers/template_matcher.md#template-format) rules, and save the results
+in a file of your own (for example `local/tutorial_templates.txt`, then point
+`templates_path` in the code below at it). The finished version ships as
+`docs/examples/data/tutorial_templates.txt`, which the example code uses, so you
+can compare your result against it:
 
 ```text
 op=start ver=<*> format=<*> kernel=<*> auid=<*> pid=<*> uid=<*> ses=<*> res=<*>

From 2fccc7b3eca5a628c66390276d9d4fda0cd5732e Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:10:00 +0200
Subject: [PATCH 24/40] grammar

---
 docs/user_guide/basic_knowledge.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index ce405f03..c8126187 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -82,8 +82,8 @@ The pattern that tells the parser how to split a line is called the
 so the parser knows which chunk is the log level, which is the timestamp, and
 which is the actual message content.
 
-The term `log_format` is regularly used in the literature. Such as in the
-**Drain-Parser**, **LogParser**, and many more use it frequently.
+The term `log_format` is common in the log-parsing literature and is used by
+tools such as the **Drain parser** and **LogParser**, among many others.
 
 Based on the example above:
 

From e1a326117f4c6b3733436f5feaa96283c5536a66 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:30:07 +0200
Subject: [PATCH 25/40] remove pitfall from quickstart

---
 docs/examples/others/quickstart.py | 4 ++++
 docs/user_guide/quickstart.md      | 4 ----
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/examples/others/quickstart.py b/docs/examples/others/quickstart.py
index 32ea96f5..7702a039 100644
--- a/docs/examples/others/quickstart.py
+++ b/docs/examples/others/quickstart.py
@@ -25,6 +25,10 @@
 raw_logs = list(From.log(parser, log_path, do_process=False))
 parsed_logs = [parser.process(log) for log in raw_logs]
 
+# To.json appends to existing files, so start from empty ones on every run
+for path in (log_json, parsed_path):
+    Path(path).unlink(missing_ok=True)
+
 To.json(raw_logs, log_json)
 To.json(parsed_logs, parsed_path)
 # --8<-- [end:parse]
diff --git a/docs/user_guide/quickstart.md b/docs/user_guide/quickstart.md
index 607c88b7..f735f4fe 100644
--- a/docs/user_guide/quickstart.md
+++ b/docs/user_guide/quickstart.md
@@ -16,9 +16,5 @@ detector to check whether the dataset contains anomalies. We use the
 ```python
 --8<-- "docs/examples/detectors/random_detector.py"
 ```
-## Common pitfalls
-
-* Before re-running the parser code, delete `local/audit_raw.json` and
-  `local/audit_parsed.json`; otherwise the new output is appended to the old files.
 
 Go back [Index](../index.md)

From c36afcd3aefcf3a0bb049c1add4de4069bc4cd4a Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:40:45 +0200
Subject: [PATCH 26/40] fix quickstart path problem

---
 docs/examples/others/quickstart.py |  2 +-
 docs/user_guide/quickstart.md      | 20 ++++++++++++++++++++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/docs/examples/others/quickstart.py b/docs/examples/others/quickstart.py
index 7702a039..0c8ccfb6 100644
--- a/docs/examples/others/quickstart.py
+++ b/docs/examples/others/quickstart.py
@@ -3,7 +3,7 @@
 from detectmatelibrary.parsers.template_matcher import MatcherParser
 from detectmatelibrary.helper.from_to import From, To
 
-ROOT = Path(__file__).resolve().parents[3]  # repository root; adjust if needed
+ROOT = Path.cwd()  # run this from the repository root (see "Before you start")
 templates_path = str(ROOT / "tests" / "test_data" / "audit_templates.txt")
 log_path = str(ROOT / "tests" / "test_data" / "audit.log")
 log_json = str(ROOT / "local" / "audit_raw.json")
diff --git a/docs/user_guide/quickstart.md b/docs/user_guide/quickstart.md
index f735f4fe..178ec10a 100644
--- a/docs/user_guide/quickstart.md
+++ b/docs/user_guide/quickstart.md
@@ -5,6 +5,26 @@ This quickstart shows how to parse a log dataset (we use data from the
 detector to check whether the dataset contains anomalies. We use the
 `MatcherParser` and the `RandomDetector`.
 
+## Before you start
+
+The example data ships with the source repository, not with the installed
+package: the logs are in `tests/test_data/audit.log` and the matching templates in
+`tests/test_data/audit_templates.txt`. The steps below therefore assume that you:
+
+1. have cloned the repository and installed it (see [Installation](installation.md)):
+
+    ```bash
+    git clone https://github.com/ait-detectmate/DetectMateLibrary.git
+    cd DetectMateLibrary
+    uv sync
+    ```
+
+2. run the code from the repository root, the folder that contains
+   `pyproject.toml`, for example with `uv run python quickstart.py`. Step 2 opens
+   its configuration file with a path relative to that folder.
+
+Step 1 writes its output files to `local/` in the repository root.
+
 ## 1. Parse the logs
 
 ```python

From fabe873045ae6d89dfef96b450091805db9d4cdd Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:45:59 +0200
Subject: [PATCH 27/40] add navigation footer

---
 docs/advanced/overall_architecture.md | 2 --
 docs/alert_aggregator.md              | 2 --
 docs/auxiliar/input_buffer.md         | 2 --
 docs/helper/from_to.md                | 1 -
 docs/other/log_formats.md             | 4 ----
 docs/schemas.md                       | 3 ---
 docs/user_guide/basic_knowledge.md    | 2 --
 docs/user_guide/installation.md       | 2 --
 docs/user_guide/quickstart.md         | 2 --
 docs/user_guide/tutorial.md           | 2 --
 docs/user_guide/what_is_detectmate.md | 3 ---
 mkdocs.yml                            | 2 ++
 12 files changed, 2 insertions(+), 25 deletions(-)

diff --git a/docs/advanced/overall_architecture.md b/docs/advanced/overall_architecture.md
index 44320fff..c9821e2a 100644
--- a/docs/advanced/overall_architecture.md
+++ b/docs/advanced/overall_architecture.md
@@ -38,5 +38,3 @@ Each Core* base class exposes a small, stable API that implementations must impl
 ```python
 --8<-- "docs/examples/others/components_methods.py:read"
 ```
-
-Go back [Index](../index.md)
diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index c70294db..a1a81b17 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -38,5 +38,3 @@ class CoreAlertAggregation:
 ## Available alert aggregation
 
 - [Basic Concat](alert_aggregators/basic_concatenation.md)
-
-Go back to [Index](index.md)
diff --git a/docs/auxiliar/input_buffer.md b/docs/auxiliar/input_buffer.md
index afb2295d..09a53397 100644
--- a/docs/auxiliar/input_buffer.md
+++ b/docs/auxiliar/input_buffer.md
@@ -31,5 +31,3 @@ Code examples to show the behaviour of the **DataBuffer** class.
 ```python
 --8<-- "docs/examples/others/data_buffer.py:example_3"
 ```
-
-Go back [Index](../index.md)
diff --git a/docs/helper/from_to.md b/docs/helper/from_to.md
index 81de7c6e..92f8a6e2 100644
--- a/docs/helper/from_to.md
+++ b/docs/helper/from_to.md
@@ -290,4 +290,3 @@ Example output data after parsing:
     }
 }
 ```
-Go back to [Index](../index.md)
diff --git a/docs/other/log_formats.md b/docs/other/log_formats.md
index a4d8c4c7..025e1f35 100644
--- a/docs/other/log_formats.md
+++ b/docs/other/log_formats.md
@@ -308,7 +308,3 @@ Mobile health application log. Pipe-delimited format from a step-counter app.
 ```
 
 **`log_format`:** `<Time>|<Component>|<Pid>|<Content>`
-
----
-
-Go back to [Index](../index.md)
diff --git a/docs/schemas.md b/docs/schemas.md
index c18c8b98..ddfbea39 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -147,6 +147,3 @@ Short examples of working with the schemas.
 ```python
 --8<-- "docs/examples/others/schemas.py:example_3"
 ```
-
-
-Go back [Index](index.md)
diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index c8126187..91dd0462 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -126,5 +126,3 @@ The `EventID` is what detectors build on:
   [New Event Detector](../detectors/new_event.md) (an `EventID` never seen
   before) and the [Event Sequence Detector](../detectors/event_sequence.md) (an
   unusual order of `EventID`s).
-
-Go back [Index](../index.md)
diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md
index db1bab5a..5d40ba1b 100644
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -125,5 +125,3 @@ uv run --dev pytest --cov=. --cov-report=term-missing
 * If `uv` is unavailable, use a Python virtualenv and the `pip`/`pytest` commands directly.
 * If `protoc` is missing, install the system package or download a prebuilt binary for your OS.
 * Always run commands from the project root so file paths (`pyproject.toml`, `src/`) resolve correctly.
-
-Go back [Index](../index.md)
diff --git a/docs/user_guide/quickstart.md b/docs/user_guide/quickstart.md
index 178ec10a..12539f81 100644
--- a/docs/user_guide/quickstart.md
+++ b/docs/user_guide/quickstart.md
@@ -36,5 +36,3 @@ Step 1 writes its output files to `local/` in the repository root.
 ```python
 --8<-- "docs/examples/detectors/random_detector.py"
 ```
-
-Go back [Index](../index.md)
diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index f4653560..7143c2e6 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -246,5 +246,3 @@ Two details are easy to miss here, and both matter for production configs:
 * Calling `.process()` on a detector or aggregator returns `None` when
   nothing fires, and the actual output schema (truthy) when it does  --  check
   with `if result:` rather than assuming a boolean.
-
-Go back [Index](../index.md)
diff --git a/docs/user_guide/what_is_detectmate.md b/docs/user_guide/what_is_detectmate.md
index 0feb3443..7e1beb2c 100644
--- a/docs/user_guide/what_is_detectmate.md
+++ b/docs/user_guide/what_is_detectmate.md
@@ -10,6 +10,3 @@ It is built from ready-made building blocks (parsers, detectors and aggregators)
 * **A broad catalogue out of the box:** 6 parsers and 13 detectors
   ship ready to use, from simple rule-based checks to deep-learning sequence models.
 * **Need something specific to your data?** Inherit from the respective core class to build a parser or detector for your own use case. The core classes provide all the essentials, so creating a fully custom component for your use case takes very little code.
-
-
-Go back [Index](../index.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index e1cb1f41..b5b8fa43 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -3,6 +3,8 @@ site_url: https://ait-detectmate.github.io/DetectMateLibrary/
 
 theme:
   name: material # windmill is auch cool
+  features:
+    - navigation.footer   # previous / next page links at the bottom of every page
   palette:
     # Light mode configuration
     - media: "(prefers-color-scheme: light)"

From 5d030bfe2b6fd572d83e1102a62149ba6454958e Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:47:51 +0200
Subject: [PATCH 28/40] add requirements to installation

---
 docs/user_guide/installation.md | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/user_guide/installation.md b/docs/user_guide/installation.md
index 5d40ba1b..ee70898c 100644
--- a/docs/user_guide/installation.md
+++ b/docs/user_guide/installation.md
@@ -1,9 +1,20 @@
 # Installation
 
-It is recommended to use [uv](https://docs.astral.sh/uv/) for installation. From
-the project root:
+## Requirements
+
+- **Python 3.12 or newer.** If you don't have it, uv can install it for you:
+  `uv python install 3.12`.
+- **[uv](https://docs.astral.sh/uv/)** (recommended) or pip.
+- **git**, to get the source code.
+
+## Install from source
+
+It is recommended to use [uv](https://docs.astral.sh/uv/) for installation. Clone
+the repository and install it from the project root:
 
 ```bash
+git clone https://github.com/ait-detectmate/DetectMateLibrary.git
+cd DetectMateLibrary
 uv sync
 ```
 

From 3941820665205c044c4e938b72927318ebf2dd37 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:52:05 +0200
Subject: [PATCH 29/40] change template file wording

---
 docs/user_guide/tutorial.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 7143c2e6..21a7c950 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -5,8 +5,7 @@ A complete walkthrough of using DetectMate  --  more detailed than the
 ready-made template file and runs one detector. This tutorial goes one level
 deeper:
 
-- you parse a dataset that has no template file yet, so you write the templates
-  yourself
+- you parse a new dataset and write its templates yourself
 - you run two detectors that look for different kinds of anomalies and compare
   what each one finds
 - you combine their alerts with an alert aggregator
@@ -21,8 +20,9 @@ matching `audit_templates.txt`. To actually practice building
 something, this tutorial uses a different file instead:
 `docs/examples/data/tutorial_audit.log`. It is still Linux `auditd` output  --  same overall
 shape as the Quickstart's dataset  --  but recorded on a different machine, and
-it comes with **no template file**. That is the point: before you can parse
-it, you have to look at it.
+this time **you write the templates yourself**. A finished template file is
+included in the repository, but only so you can check your result in step 2.
+That is the point: before you can parse a dataset, you have to look at it.
 
 > Note: you likely have to edit your Path to your project root. In this code snippet we assume, that your
 > notebook lives two folders below the project root. If it sits somewhere else, adjust `parents[...]` (for a

From ab72e23929b338befb37b1085339a785f0bf44d4 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:54:11 +0200
Subject: [PATCH 30/40] fix path confusion in tutorial

---
 docs/examples/others/tutorial.py | 5 +----
 docs/user_guide/tutorial.md      | 9 ++++++---
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/examples/others/tutorial.py b/docs/examples/others/tutorial.py
index aadb78f2..5a763838 100644
--- a/docs/examples/others/tutorial.py
+++ b/docs/examples/others/tutorial.py
@@ -2,10 +2,7 @@
 from pathlib import Path
 from detectmatelibrary.helper.from_to import From
 
-try:
-    ROOT = Path(__file__).resolve().parents[3]
-except NameError:  # running inside a Jupyter notebook
-    ROOT = Path.cwd().resolve().parents[1]
+ROOT = Path.cwd()  # the repository root; see the note above this code
 
 log_path = str(ROOT / "docs" / "examples" / "data" / "tutorial_audit.log")
 
diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 21a7c950..09edb59b 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -24,9 +24,12 @@ this time **you write the templates yourself**. A finished template file is
 included in the repository, but only so you can check your result in step 2.
 That is the point: before you can parse a dataset, you have to look at it.
 
-> Note: you likely have to edit your Path to your project root. In this code snippet we assume, that your
-> notebook lives two folders below the project root. If it sits somewhere else, adjust `parents[...]` (for a
-> script) or the `Path.cwd()` line (for a notebook) accordingly.
+> **Note:** like the Quickstart, this tutorial assumes a cloned repository and
+> runs from the repository root, the folder that contains `pyproject.toml` (see
+> [Before you start](quickstart.md#before-you-start)). The code finds its files
+> relative to that folder through `ROOT = Path.cwd()`. If you work in a notebook
+> stored somewhere else, set `ROOT` to the path of your clone instead, for example
+> `ROOT = Path("/home/me/DetectMateLibrary")`.
 
 ```python
 --8<-- "docs/examples/others/tutorial.py:read"

From c02689a67d0ecca301d710b4e3fa02c6888d442d Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 11:56:13 +0200
Subject: [PATCH 31/40] change pitfall wording

---
 docs/user_guide/tutorial.md | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 09edb59b..0f8a331a 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -242,10 +242,15 @@ Two details are easy to miss here, and both matter for production configs:
 * Manually escaping regex characters (like `(` and `)`) inside a
   `log_format` string breaks matching:
   `generate_logformat_regex()` already escapes literal text for you.
-* A detector's `detect()` only checks `EventID`s it has already seen through
-  `train()` at least once. If you configure a detector for an `EventID` that
-  never appears in the training window (`data_use_training`), it will stay
-  silent for that event type  --  not alert on everything, and not error either.
+* Detectors configured with an `events` block (such as `NewValueDetector`) only
+  check `EventID`s they have seen in training. If you configure an `EventID` that
+  never appears in the training window (`data_use_training`), the detector stays
+  silent for that event type: it does not alert on everything, and it does not
+  raise an error. It does log a warning when training ends, for example
+  `[NewValueDetector] EventID 5 is configured but was never observed in training data`,
+  so check the log after training. This does not apply to every detector: the
+  [New Event Detector](../detectors/new_event.md) exists to alert on exactly
+  those never-seen `EventID`s.
 * Calling `.process()` on a detector or aggregator returns `None` when
   nothing fires, and the actual output schema (truthy) when it does  --  check
   with `if result:` rather than assuming a boolean.

From cf7c419a1b8c16e5d74a4d4b7a1ca7f04f456035 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 12:06:04 +0200
Subject: [PATCH 32/40] schemas raise instead of returning exception class

---
 docs/schemas.md                           | 20 +++++++++++---
 src/detectmatelibrary/schemas/__init__.py |  5 +++-
 src/detectmatelibrary/schemas/_classes.py | 19 +++++++++-----
 src/detectmatelibrary/schemas/_op.py      | 32 +++++++++++++++++------
 4 files changed, 57 insertions(+), 19 deletions(-)

diff --git a/docs/schemas.md b/docs/schemas.md
index ddfbea39..ad0d5e90 100644
--- a/docs/schemas.md
+++ b/docs/schemas.md
@@ -46,16 +46,28 @@ class BaseSchema:
     def serialize(self) -> bytes:
         """Serialize the schema instance to bytes."""
 
-    def deserialize(self, message: bytes) -> None | op.IncorrectSchema:
-        """Deserialize bytes to populate the schema instance."""
+    def deserialize(self, message: bytes) -> None:
+        """Deserialize bytes to populate the schema instance.
 
-    def check_is_same(self, other: Self) -> None | op.IncorrectSchema:
-        """Check if another schema instance is of the same schema type."""
+        Raises NotSupportedSchema if the bytes cannot be parsed.
+        """
+
+    def check_is_same(self, other: Self) -> None:
+        """Check if another schema instance is of the same schema type.
+
+        Raises IncorrectSchema if it is not.
+        """
 
     def __eq__(self, other: object) -> bool:
         """Check equality between two schema instances."""
 ```
 
+The exceptions these methods raise can be imported from `detectmatelibrary.schemas`:
+
+```python
+from detectmatelibrary.schemas import IncorrectSchema, NotSupportedSchema
+```
+
 ## Schema Classes
 
 Below are the primary schema classes and their main fields. All fields are optional at the Protobuf level; components should document which fields they require.
diff --git a/src/detectmatelibrary/schemas/__init__.py b/src/detectmatelibrary/schemas/__init__.py
index 479b0911..f48ccd7b 100644
--- a/src/detectmatelibrary/schemas/__init__.py
+++ b/src/detectmatelibrary/schemas/__init__.py
@@ -11,6 +11,7 @@
     AggregateSchema,
     FieldNotFound,
 )
+from ._op import IncorrectSchema, NotSupportedSchema
 
 
 __all__ = [
@@ -19,5 +20,7 @@
     "ParserSchema",
     "DetectorSchema",
     "AggregateSchema",
-    "FieldNotFound"
+    "FieldNotFound",
+    "IncorrectSchema",
+    "NotSupportedSchema",
 ]
diff --git a/src/detectmatelibrary/schemas/_classes.py b/src/detectmatelibrary/schemas/_classes.py
index ca390052..e0b1d046 100644
--- a/src/detectmatelibrary/schemas/_classes.py
+++ b/src/detectmatelibrary/schemas/_classes.py
@@ -88,15 +88,22 @@ def serialize(self) -> bytes:
         """Serialize the schema instance to bytes."""
         return op.serialize(schema=self.get_schema())
 
-    def deserialize(self, message: bytes) -> None | op.IncorrectSchema:
-        """Deserialize bytes to populate the schema instance."""
+    def deserialize(self, message: bytes) -> None:
+        """Deserialize bytes to populate the schema instance.
+
+        Raises:
+            NotSupportedSchema: If the bytes cannot be parsed.
+        """
         schema = op.deserialize(schema_class=self.schema_class, message=message)
         self.set_schema(schema=schema)
-        return None
 
-    def check_is_same(self, other: Self) -> None | op.IncorrectSchema:
-        """Check if another schema instance is of the same schema type."""
-        return op.check_is_same_schema(
+    def check_is_same(self, other: Self) -> None:
+        """Check if another schema instance is of the same schema type.
+
+        Raises:
+            IncorrectSchema: If the other instance is of another schema type.
+        """
+        op.check_is_same_schema(
             id_schema_1=self.schema_class,
             id_schema_2=other.schema_class
         )
diff --git a/src/detectmatelibrary/schemas/_op.py b/src/detectmatelibrary/schemas/_op.py
index 975e6080..d2c92015 100644
--- a/src/detectmatelibrary/schemas/_op.py
+++ b/src/detectmatelibrary/schemas/_op.py
@@ -51,15 +51,23 @@ def is_repeated(schema: SchemaT, field_name: str) -> bool:
 
 def check_is_same_schema(
     id_schema_1: SchemaID, id_schema_2: SchemaID
-) -> None | IncorrectSchema:
-    """Raise exception if two schemas do not match."""
+) -> None:
+    """Check that two schemas are of the same type.
+
+    Raises:
+        IncorrectSchema: If the two schemas do not match.
+    """
     if id_schema_1 != id_schema_2:
         raise IncorrectSchema()
     return None
 
 
-def check_if_schema_is_complete(schema: SchemaT) -> None | NotCompleteSchema:
-    """Check if the schema is complete."""
+def check_if_schema_is_complete(schema: SchemaT) -> None:
+    """Check if the schema is complete.
+
+    Raises:
+        NotCompleteSchema: If a non-repeated field is not set.
+    """
     missing_fields = []
     for field in schema.DESCRIPTOR.fields:
         if not __is_repeated(field) and not schema.HasField(field.name):
@@ -86,8 +94,12 @@ def initialize(schema: SchemaT, **kwargs: Any) -> SchemaT:
 
 def copy(
     schema_class: SchemaT, schema: SchemaT
-) -> SchemaT | IncorrectSchema:
-    """Make a copy of the schema."""
+) -> SchemaT:
+    """Make a copy of the schema.
+
+    Raises:
+        IncorrectSchema: If the schema cannot be copied into schema_class.
+    """
     new_schema = initialize(schema_class, **{})
     try:
         new_schema.CopyFrom(schema)
@@ -100,8 +112,12 @@ def serialize(schema: SchemaT) -> bytes:
     return schema.SerializeToString()  # type: ignore
 
 
-def deserialize(schema_class: SchemaT, message: bytes) -> SchemaT | NotSupportedSchema:
-    """Return the schema and id from a serialize message."""
+def deserialize(schema_class: SchemaT, message: bytes) -> SchemaT:
+    """Parse a serialized message into a new schema_class instance.
+
+    Raises:
+        NotSupportedSchema: If the message cannot be parsed.
+    """
     schema = schema_class()
     try:
         schema.ParseFromString(message)

From 16874b31796ac1bbb410c67e476ed6e415d8ed55 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 12:07:33 +0200
Subject: [PATCH 33/40] corec class names

---
 docs/advanced/overall_architecture.md | 2 +-
 docs/alert_aggregator.md              | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/advanced/overall_architecture.md b/docs/advanced/overall_architecture.md
index c9821e2a..71e09028 100644
--- a/docs/advanced/overall_architecture.md
+++ b/docs/advanced/overall_architecture.md
@@ -25,7 +25,7 @@ Each arrow represents a stream of Schema objects. Components are designed to run
 
 ## Components architecture
 
-All components inherit from a `CoreComponent` class. This class provides all the essential functionality required for DetectMate to operate (see UML diagram below). Every `Detector` must inherit from `CoreDetector`, every `AlertAggregator` must inherit from `CoreAlertAggregation` and every `Parser` must inherit from `CoreParser` to ensure compatibility with DetectMate.
+All components inherit from a `CoreComponent` class. This class provides all the essential functionality required for DetectMate to operate (see UML diagram below). Every `Detector` must inherit from `CoreDetector`, every `AlertAggregator` must inherit from `CoreAlertAggregator` and every `Parser` must inherit from `CoreParser` to ensure compatibility with DetectMate.
 
 Each component's arguments must be stored in its corresponding configuration class. These config classes follow the same design pattern as their components and must inherit from `CoreConfig`.
 
diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index a1a81b17..c5b75c78 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -11,16 +11,16 @@ This document explains expected APIs, how to implement an alert aggregator, test
 
 ## Overview
 
-- Alert aggregation must inherit from `CoreAlertAggregation` and provide a `aggregate_alerts()` implementation.
+- Alert aggregation must inherit from `CoreAlertAggregator` and provide a `aggregate_alerts()` implementation.
 - `CoreParser.run()` handles lifecycle and calls `aggregate_alerts()` for each input; implement pure alert aggregation logic inside `aggregate_alerts()` where possible.
-- Use a typed `Config` class (subclass of `CoreAlertAggregationConfig`) to hold runtime parameters.
+- Use a typed `Config` class (subclass of `CoreAlertAggregatorConfig`) to hold runtime parameters.
 
 ## CoreParser  --  minimal API
 
 Recommended signatures and behavior:
 
 ```python
-class CoreAlertAggregation:
+class CoreAlertAggregator:
  def aggregate_alerts(
         self,
         input_: list[DetectorSchema] | DetectorSchema,

From 839d04e4b30ae4276483bd0510b0ca4cc8790764 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 12:21:56 +0200
Subject: [PATCH 34/40] correct description of parse and run

---
 docs/parsers.md | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/docs/parsers.md b/docs/parsers.md
index d1276fe0..af2a5073 100644
--- a/docs/parsers.md
+++ b/docs/parsers.md
@@ -38,13 +38,23 @@ class CoreParser:
 
 ## ParserSchema  --  what to populate
 
-Minimum fields commonly expected by downstream components:
+`parse()` only has to fill the fields that describe the match:
 
 - `EventID` (int)  --  identifier for the matched template/event
 - `template` (string)  --  event template text
 - `variables` (repeated string)  --  extracted parameters (extend the list)
-- `parsedLogID` / `logID`  --  identifiers linking raw and parsed records
-- `parsedTimestamp` / `receivedTimestamp`  --  timestamps
+
+`CoreParser.run()`, which calls `parse()`, fills in everything else for you:
+
+- `parserID`, `parserType`  --  the parser's name and `method_type`
+- `parsedLogID`  --  a new unique ID for the parsed record
+- `logID`, `log`  --  copied from the input `LogSchema`
+- `logFormatVariables`  --  the header fields extracted with `log_format`
+- `receivedTimestamp`, `parsedTimestamp`  --  set just before and just after
+  `parse()` runs
+
+Don't set these in `parse()`: `run()` writes `parsedTimestamp` after `parse()`
+returns, so a value set there is overwritten.
 
 ## Creating a new parser  --  step by step
 
@@ -57,7 +67,6 @@ Example:
 
 ```python
 # filepath: src/detectmatelibrary/parsers/my_parser.py
-import time
 from typing import Any
 
 from detectmatelibrary.common.parser import CoreParser, CoreParserConfig
@@ -87,7 +96,6 @@ class MyParser(CoreParser):
         output_["EventID"] = 1
         output_["template"] = " ".join(["<*>"] * len(tokens))
         output_["variables"].extend(tokens)
-        output_["parsedTimestamp"] = int(time.time())
         return True
 ```
 

From b1d6a8b7f564d1fece2f38416a4f8d5d6d0c3a2e Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 12:29:43 +0200
Subject: [PATCH 35/40] parser return value

---
 docs/parsers.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/parsers.md b/docs/parsers.md
index af2a5073..abbb2edc 100644
--- a/docs/parsers.md
+++ b/docs/parsers.md
@@ -26,10 +26,11 @@ class CoreParser:
         Return True when a parsed output was produced, False otherwise.
         """
 
-    def parse(self, input_: schemas.LogSchema, output_: schemas.ParserSchema) -> bool:
+    def parse(self, input_: schemas.LogSchema, output_: schemas.ParserSchema) -> bool | None:
         """Implement parsing here.
-        - Fill required output_ fields (see ParserSchema table below).
-        - Return True if parsing succeeded and output_ contains a result.
+        - Fill the required output_ fields (see "ParserSchema - what to populate" below).
+        - Return True, or None, to emit output_ as the parsed log.
+        - Return False to drop the log: process() then returns None for it.
         """
 
     def train(self, input_: schemas.LogSchema) -> None:

From 000b0cbc44caec3e3d85a9c237d57619aafb4fa2 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 13:17:57 +0200
Subject: [PATCH 36/40] correct detector snippet!

---
 docs/detectors.md | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/docs/detectors.md b/docs/detectors.md
index 2460fbca..2cd613aa 100644
--- a/docs/detectors.md
+++ b/docs/detectors.md
@@ -18,12 +18,23 @@ This document describes the minimal API, implementation guidance, a short exampl
 class CoreDetectorConfig(CoreConfig):
     component_type: str = "detectors"
     method_type: str = "core_detector"
-    parser: str = "<PLACEHOLDER>"
+    parser: str = "PARSER"
 
     auto_config: bool = True
+    events: EventsConfig | dict[str, Any] = {}
+    global_instances: dict[str, Any] = {}  # written as `global` in YAML
 
 
 class CoreDetector(CoreComponent):
+    def __init__(
+        self,
+        name: str = "CoreDetector",
+        buffer_mode: BufferMode = BufferMode.NO_BUF,
+        buffer_size: int | None = None,
+        config: CoreDetectorConfig | dict[str, Any] | None = CoreDetectorConfig(),
+    ) -> None:
+        """buffer_mode and buffer_size set how many logs detect() receives per call."""
+
     def run(
         self, input_: List[ParserSchema] | ParserSchema, output_: DetectorSchema
     ) -> bool:
@@ -144,7 +155,7 @@ detectors:
             - pos: 0  # location of an unnamed variable from the log message
               name: var1  # name of variable (arbitrary)
           header_variables:
-            - pos: level  # location of a named variable (defined in log_format of parser)
+            - pos: Level  # name of a field in the parser's log_format (case-sensitive: <Level> -> Level)
     global:  # define global instance for new_value_detector similar to "events"
       global_instance1:  # define instance name
         header_variables:  # same logic as header_variables in "events"
@@ -247,7 +258,8 @@ The two neural detectors ([DeepLog](detectors/deeplog.md), [LogBERT](detectors/l
 pid=<*> uid=<*> auid=<*> ses=<*> msg='op=<*> acct=<*> exe=<*> hostname=<*> addr=<*> terminal=<*> res=<*>'
 ```
 
-`pos: 0` captures `pid=`, `pos: 6` captures `exe=`, etc.
+`pos: 0` captures the value after `pid=` (for example `10125`), `pos: 6` the value after
+`exe=` (for example `"/usr/sbin/cron"`), and so on.
 
 **`header_variables[].pos`**  --  A named field from the log format string (e.g., `Type`, `Time`, `Content`) rather than a wildcard position.
 

From 4e39a713e5bc37cc67f7ff9d82aae2ddcee05cd9 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 13:22:06 +0200
Subject: [PATCH 37/40] add axplanation for nemed eventid and autoconfig

---
 docs/detectors.md                       | 34 +++++++++++++++++++-
 docs/examples/data/named_templates.csv  |  3 ++
 docs/examples/detectors/named_events.py | 42 +++++++++++++++++++++++++
 3 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/data/named_templates.csv
 create mode 100644 docs/examples/detectors/named_events.py

diff --git a/docs/detectors.md b/docs/detectors.md
index 2cd613aa..4621cb72 100644
--- a/docs/detectors.md
+++ b/docs/detectors.md
@@ -138,6 +138,13 @@ The detectors are numbered from simplest to most complex, and the sidebar lists
 Every detector page shows a minimal, working configuration file next to its example. The
 reference below explains the blocks those files use.
 
+`auto_config` defaults to `True` for detectors, but the configure phase only runs when
+`data_use_configure` is set. A detector with an `events` block and no
+`data_use_configure` therefore uses that block even if `auto_config` is left out. The
+example configurations set `auto_config: false` anyway, to make this explicit. If
+`auto_config` is `True` *and* `data_use_configure` is set, the configure phase replaces the
+`events` block with its own selection.
+
 When `auto_config` is set to `False`, the detector expects an explicit `events` or `global` block that specifies exactly which variables to monitor. `events` refers to event-specific variables while `global` refers to variables, that are not bound to events (`header_variables` can but don't have to be event bound):
 
 ```yaml
@@ -248,7 +255,7 @@ The two neural detectors ([DeepLog](detectors/deeplog.md), [LogBERT](detectors/l
 
 ### Configuration semantics (preliminary)
 
-**`events` key**  --  The integer key is the `EventID` (or `event_id`) to monitor (see the [Template Matcher](parsers/template_matcher.md) docs for how the EventID is assigned.
+**`events` key**  --  The key is the `EventID` (or `event_id`) to monitor: an integer as the parser emits it (see the [Template Matcher](parsers/template_matcher.md) docs for how the EventID is assigned), or a name (see [Named EventIDs and variables](#named-eventids-and-variables) below).
 
 **`global` key** - This one has a similar functionality as the `events` key but refers to variables, that are not bound to events (thus can only contain `header_variables`).
 
@@ -263,6 +270,31 @@ pid=<*> uid=<*> auid=<*> ses=<*> msg='op=<*> acct=<*> exe=<*> hostname=<*> addr=
 
 **`header_variables[].pos`**  --  A named field from the log format string (e.g., `Type`, `Time`, `Content`) rather than a wildcard position.
 
+### Named EventIDs and variables
+
+Instead of numbers, the `events` block can use names: a name for the `EventID`, and
+the name of a wildcard for `variables[].pos`. The names come from the
+[Template Matcher](parsers/template_matcher.md)'s template file:
+
+- **Named variables:** write `<user>` instead of `<*>` in a template. A template uses
+  either named wildcards or `<*>`, not both. This works in `.txt` and `.csv` template files.
+- **Named EventIDs:** use a `.csv` template file with an `EventId` column next to the
+  `EventTemplate` column:
+
+    ```text
+    --8<-- "docs/examples/data/named_templates.csv"
+    ```
+
+The parser still emits numbers (`EventID` 1 and position 0 for `<user>` in the second
+template), so the names must be translated before the detector runs. Do this once,
+after creating both components, with `compile_detector_config()`. **Without this step
+the detector monitors nothing**; it only logs a warning that the named `EventID` was
+never observed in training.
+
+```python
+--8<-- "docs/examples/detectors/named_events.py:example"
+```
+
 
 ### Auto-configuration (optional)
 
diff --git a/docs/examples/data/named_templates.csv b/docs/examples/data/named_templates.csv
new file mode 100644
index 00000000..a0606052
--- /dev/null
+++ b/docs/examples/data/named_templates.csv
@@ -0,0 +1,3 @@
+EventId,EventTemplate
+login_ok,Accepted password for <user> from <ip> port <port>
+login_failure,Failed password for <user> from <ip> port <port>
diff --git a/docs/examples/detectors/named_events.py b/docs/examples/detectors/named_events.py
new file mode 100644
index 00000000..1b8cbece
--- /dev/null
+++ b/docs/examples/detectors/named_events.py
@@ -0,0 +1,42 @@
+# --8<-- [start:example]
+from detectmatelibrary import schemas
+from detectmatelibrary.parsers.template_matcher import MatcherParser
+from detectmatelibrary.detectors.new_value_detector import NewValueDetector
+
+# Templates from a CSV file: the EventId column names each template, and
+# named wildcards (<user>, <ip>, <port>) name its variables.
+parser = MatcherParser(name="MatcherParser", config={"parsers": {"MatcherParser": {
+    "method_type": "matcher_parser",
+    "path_templates": "docs/examples/data/named_templates.csv",
+}}})
+
+# The detector configuration uses those names instead of numbers.
+detector = NewValueDetector(name="NewUserDetector", config={"detectors": {"NewUserDetector": {
+    "method_type": "new_value_detector",
+    "auto_config": False,
+    "params": {"data_use_training": 2},
+    "events": {
+        "login_failure": {                                  # EventId from the CSV
+            "failed_login": {
+                "variables": [{"pos": "user", "name": "user"}],  # named wildcard <user>
+            },
+        },
+    },
+}}})
+
+# Resolve the names to the numbers the parser emits (login_failure -> 1, user -> 0).
+# Without this step the detector monitors nothing.
+detector.config.events = parser.template_matcher.compile_detector_config(detector.config.events)
+
+lines = [
+    "Failed password for alice from 10.0.0.1 port 22",    # training
+    "Failed password for alice from 10.0.0.2 port 22",    # training
+    "Failed password for mallory from 10.0.0.3 port 22",  # new user
+]
+for line in lines:
+    alert = detector.process(parser.process(schemas.LogSchema({"log": line})))
+    print(dict(alert["alertsObtain"]) if alert else None)
+# None
+# None
+# {'EventID 1 - user': "Unknown value: 'mallory'"}
+# --8<-- [end:example]

From 2dfef0bdf40cf2066941522115c581426539785b Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 13:27:41 +0200
Subject: [PATCH 38/40] remove double dashes

---
 docs/alert_aggregator.md           |  2 +-
 docs/auxiliar/persistency.md       | 20 +++++------
 docs/detectors.md                  | 54 +++++++++++++++---------------
 docs/detectors/ecvc_detector.md    |  2 +-
 docs/detectors/event_sequence.md   |  4 +--
 docs/detectors/scvs_detector.md    |  2 +-
 docs/development.md                |  8 ++---
 docs/other/log_formats.md          |  6 ++--
 docs/parsers.md                    | 24 ++++++-------
 docs/parsers/logbatcher_parser.md  |  4 +--
 docs/user_guide/basic_knowledge.md |  6 ++--
 docs/user_guide/tutorial.md        | 38 ++++++++++-----------
 12 files changed, 85 insertions(+), 85 deletions(-)

diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index c5b75c78..bc5a6e8b 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -15,7 +15,7 @@ This document explains expected APIs, how to implement an alert aggregator, test
 - `CoreParser.run()` handles lifecycle and calls `aggregate_alerts()` for each input; implement pure alert aggregation logic inside `aggregate_alerts()` where possible.
 - Use a typed `Config` class (subclass of `CoreAlertAggregatorConfig`) to hold runtime parameters.
 
-## CoreParser  --  minimal API
+## CoreAlertAggregator: minimal API
 
 Recommended signatures and behavior:
 
diff --git a/docs/auxiliar/persistency.md b/docs/auxiliar/persistency.md
index 097236e6..808af5c0 100644
--- a/docs/auxiliar/persistency.md
+++ b/docs/auxiliar/persistency.md
@@ -31,12 +31,12 @@ Two families ship today:
   raw rows. Very storage heavy and *not recommended* for production-ready detectors.
 - **Tracker backends** (`EventStabilityTracker`) keep only derived features
   (e.g. "this variable has been constant for the last 10k events") that are relevant for the detector. Use these
-  when you only need a summary or a subset of the log's information, not the raw history  --  they cost a fraction of
+  when you only need a summary or a subset of the log's information, not the raw history: they cost a fraction of
   the memory.
 
 All backends implement the same four-method contract: `add_data`, `get_data`,
 `dump`, `load`. That contract is what `EventPersistency` and
-`PersistencySaver` rely on  --  anything you add later only has to follow it.
+`PersistencySaver` rely on, so anything you add later only has to follow it.
 
 ### 3. Saver lifecycle (`PersistencySaver`)
 
@@ -44,7 +44,7 @@ All backends implement the same four-method contract: `add_data`, `get_data`,
 state has to be written somewhere. `PersistencySaver` wraps an
 `EventPersistency` and:
 
-- writes to disk (or any `fsspec` URI) on two triggers  --  a wall-clock interval
+- writes to disk (or any `fsspec` URI) on two triggers: a wall-clock interval
   and an event-count threshold;
 - optionally `auto_load`s previously saved state during construction;
 - exposes `start()` / `stop()` so the background timer can be torn down
@@ -106,7 +106,7 @@ ep[event_id]                       # alias for get_event_data
 |---|---|
 | `persistency.EventStabilityTracker` | You only care about how variables behave over time (`STATIC` / `STABLE` / `UNSTABLE` / `RANDOM`). Cheapest memory footprint. |
 
-All three are re-exported from the top of the package  --  `persistency.X` is the
+All three are re-exported from the top of the package: `persistency.X` is the
 canonical import; the deeply nested submodules are an implementation detail.
 
 ### Persisting to disk
@@ -129,7 +129,7 @@ saver.stop()    # final flush, stops the background timer
 
 `PersistencySaver.save()` is thread-safe, and `stop()` is idempotent. The two
 save triggers (`save_interval_seconds` and `events_until_save`) are
-independent  --  whichever fires first wins.
+independent: whichever fires first wins.
 
 If writing to storage fails (unwritable path, full disk, lost credentials),
 `save()` and `stop()` raise `persistency.PersistencySaveError`, and
@@ -149,13 +149,13 @@ saver = persistency.PersistencySaver(
 ```
 
 If `auto_load=True` and no saved state exists, the constructor raises
-`persistency.PersistencyLoadError` immediately  --  fail-fast rather than
+`persistency.PersistencyLoadError` immediately: it fails fast rather than
 silently starting empty.
 
 #### Exporting and importing state on demand
 
-For one-shot transfers  --  e.g. moving trained state to a new environment, or
-taking a manual snapshot  --  use the standalone functions directly:
+For one-shot transfers (e.g. moving trained state to a new environment, or
+taking a manual snapshot), use the standalone functions directly:
 
 ```python
 from detectmatelibrary.utils import persistency
@@ -163,7 +163,7 @@ from detectmatelibrary.utils import persistency
 # Export to a file URI
 persistency.save(ep, "./snapshots/trained-state")
 
-# Export to bytes (no disk I/O  --  useful when sending state over a network API)
+# Export to bytes (no disk I/O; useful when sending state over a network API)
 data: bytes = persistency.save(ep)
 
 # Import from a file URI
@@ -187,7 +187,7 @@ when a saver is active.
 #### Detector-level export and import
 
 When working through a detector (the typical path for DetectMateService), use
-the methods on the detector object directly  --  no need to access
+the methods on the detector object directly, with no need to access
 `EventPersistency` internals:
 
 ```python
diff --git a/docs/detectors.md b/docs/detectors.md
index 4621cb72..f3d9e5fe 100644
--- a/docs/detectors.md
+++ b/docs/detectors.md
@@ -10,7 +10,7 @@ Detectors process structured logs from Parsers and emit alerts when anomalies ar
 
 This document describes the minimal API, implementation guidance, a short example detector and a unit test pattern.
 
-## CoreDetector  --  minimal API
+## CoreDetector: minimal API
 
 
 
@@ -51,7 +51,7 @@ class CoreDetector(CoreComponent):
         """Empty, can be define in the detector. It trains the detector"""
 ```
 
-## Implementing a detector  --  example
+## Implementing a detector: example
 
 Simple detector that raises an alert when a numeric variable exceeds a threshold.
 
@@ -255,11 +255,11 @@ The two neural detectors ([DeepLog](detectors/deeplog.md), [LogBERT](detectors/l
 
 ### Configuration semantics (preliminary)
 
-**`events` key**  --  The key is the `EventID` (or `event_id`) to monitor: an integer as the parser emits it (see the [Template Matcher](parsers/template_matcher.md) docs for how the EventID is assigned), or a name (see [Named EventIDs and variables](#named-eventids-and-variables) below).
+**`events` key**: the key is the `EventID` (or `event_id`) to monitor: an integer as the parser emits it (see the [Template Matcher](parsers/template_matcher.md) docs for how the EventID is assigned), or a name (see [Named EventIDs and variables](#named-eventids-and-variables) below).
 
 **`global` key** - This one has a similar functionality as the `events` key but refers to variables, that are not bound to events (thus can only contain `header_variables`).
 
-**`variables[].pos`**  --  The 0-indexed position of the `<*>` wildcard in the matched template, counting from left to right starting at 0. For example, given:
+**`variables[].pos`**: the 0-indexed position of the `<*>` wildcard in the matched template, counting from left to right starting at 0. For example, given:
 
 ```text
 pid=<*> uid=<*> auid=<*> ses=<*> msg='op=<*> acct=<*> exe=<*> hostname=<*> addr=<*> terminal=<*> res=<*>'
@@ -268,7 +268,7 @@ pid=<*> uid=<*> auid=<*> ses=<*> msg='op=<*> acct=<*> exe=<*> hostname=<*> addr=
 `pos: 0` captures the value after `pid=` (for example `10125`), `pos: 6` the value after
 `exe=` (for example `"/usr/sbin/cron"`), and so on.
 
-**`header_variables[].pos`**  --  A named field from the log format string (e.g., `Type`, `Time`, `Content`) rather than a wildcard position.
+**`header_variables[].pos`**: a named field from the log format string (e.g., `Type`, `Time`, `Content`) rather than a wildcard position.
 
 ### Named EventIDs and variables
 
@@ -298,7 +298,7 @@ never observed in training.
 
 ### Auto-configuration (optional)
 
-Detectors can optionally support **auto-configuration**  --  a process where the detector automatically discovers which variables are worth monitoring, instead of requiring the user to specify them manually.
+Detectors can optionally support **auto-configuration**: a process where the detector automatically discovers which variables are worth monitoring, instead of requiring the user to specify them manually.
 
 Auto-configuration is controlled by the `auto_config` flag in the pipeline config (e.g. `config/pipeline_config_default.yaml`):
 
@@ -310,7 +310,7 @@ detectors:
     params:
       data_use_configure: 1000  # logs used to pick the variables
       data_use_training: 1000   # logs used to train on them afterwards
-    # no "events" block needed  --  it will be generated automatically
+    # no "events" block needed: it is generated automatically
 ```
 
 
@@ -318,9 +318,9 @@ detectors:
 
 When auto-configuration is enabled, the detector goes through two extra phases before training:
 
-**Phase 1  --  `configure(input_)`**: The detector ingests events into an `EventPersistency` instance that uses a tracker backend to analyze variable behavior  --  for example, whether each variable is stable, random, or still has insufficient data. This instance is typically separate from the one used for training, because the configuration phase needs to observe *all* variables to decide which ones are worth monitoring, while training only tracks the variables that were selected as a result.
+**Phase 1, `configure(input_)`**: The detector ingests events into an `EventPersistency` instance that uses a tracker backend to analyze variable behavior, for example whether each variable is stable, random, or still has insufficient data. This instance is typically separate from the one used for training, because the configuration phase needs to observe *all* variables to decide which ones are worth monitoring, while training only tracks the variables that were selected as a result.
 
-**Phase 2  --  `set_configuration()`**: After enough data has been ingested, the detector queries the tracker to select variables that meet its criteria (e.g. only stable variables). It then generates a full `events` configuration from those results and updates its own config. At this point `auto_config` is set to `False` in the generated config, since the configuration is now explicit.
+**Phase 2, `set_configuration()`**: After enough data has been ingested, the detector queries the tracker to select variables that meet its criteria (e.g. only stable variables). It then generates a full `events` configuration from those results and updates its own config. At this point `auto_config` is set to `False` in the generated config, since the configuration is now explicit.
 
 After these two phases, the detector proceeds with the normal `train()` and `detect()` lifecycle using the generated configuration.
 
@@ -344,9 +344,9 @@ the hyperparameter searches of `DrainParser` and the deep-learning detectors.
 That distinction is visible in the config. A detector's settings live in two
 blocks:
 
-* **`auto_config_params`**  --  inputs *to* the configure phase. They pick which
+* **`auto_config_params`**: inputs *to* the configure phase. They pick which
   variables the phase selects and are read only while `auto_config` is `True`.
-* **`params`**  --  operational settings, read during training and detection on
+* **`params`**: operational settings, read during training and detection on
   every run.
 
 The configure phase writes its results into the top-level `events` block (and,
@@ -369,11 +369,11 @@ axes:
 | `slope_time` | change centroid vs. `slope_threshold` | normalized timestamps |
 
 Any subset of the four may be enabled, and any single one may stand alone. The
-default  --  `index` alone  --  is the historical behaviour: each segment's mean rate
-of change is compared against its entry in `segment_thresholds`  --  four segments
-by default, one threshold per segment  --  and the segments are **equal-count**:
+default (`index` alone) is the historical behaviour: each segment's mean rate
+of change is compared against its entry in `segment_thresholds` (four segments
+by default, one threshold per segment), and the segments are **equal-count**:
 each holds the same number of observations, regardless of how much time they
-cover. For bursty log sources that is misleading  --  a variable that changed
+cover. For bursty log sources that is misleading: a variable that changed
 constantly during a quiet night and then went silent under a flood of daytime
 traffic looks stable, because the flood supplies enough samples to dominate the
 later segments. Enabling `time` cuts the same segments at **equal
@@ -381,12 +381,12 @@ durations** instead, so each segment covers the same amount of wall-clock time;
 the detector then needs an event time per record, which it reads from the log's
 named variables (`logFormatVariables`, i.e. the fields declared in the parser's
 `log_format`) under the name given by `timestamp_variable`. `slope_index` and
-`slope_time` ask a different question  --  whether the change centroid sits early
-or late in the series  --  on the index axis and the time axis respectively.
+`slope_time` ask a different question (whether the change centroid sits early
+or late in the series), on the index axis and the time axis respectively.
 
 These parameters live on every `VariableDetector` subclass (`NewValueDetector`,
 `NewValueComboDetector`, `ValueRangeDetector`, `CharsetDetector`, `BigramDetector`, …)
-and go in the detector's `auto_config_params` block  --  they are inputs to the
+and go in the detector's `auto_config_params` block: they are inputs to the
 auto-configuration phase, read only while `auto_config` is `True`, and never
 consulted at detection time.
 
@@ -432,7 +432,7 @@ requires strictly more than half of them to.
 
 Ties resolve to UNSTABLE. That keeps `majority` from ever being more lenient
 than a coin-flip, and makes it collapse onto `consensus` at one and two enabled
-methods  --  turning a third method on is the only place the rule starts to matter.
+methods. Turning a third method on is the only place the rule starts to matter.
 
 **All four methods false is a config error**, rejected by a pydantic validator.
 It is not a harmless no-op: classification decides `INSUFFICIENT_DATA`,
@@ -448,7 +448,7 @@ All of these live in the detector's `auto_config_params` block.
 | `use_stable_vars` | `bool` | `true` | Include variables classified `STABLE` in the generated configuration. |
 | `use_static_vars` | `bool` | `true` | Include variables classified `STATIC`. Defaults to `false` on `NewValueComboDetector`. |
 | `classification` | `ClassificationMethods` | see below | Which classification methods run and how their verdicts combine. |
-| `timestamp_variable` | `str \| null` | `null` | Name of the field in `logFormatVariables` holding the record's event time. Required for `time` and `slope_time` to have any effect. Only named log-format fields are consulted  --  never the positional `variables` list. |
+| `timestamp_variable` | `str \| null` | `null` | Name of the field in `logFormatVariables` holding the record's event time. Required for `time` and `slope_time` to have any effect. Only named log-format fields are consulted, never the positional `variables` list. |
 | `timestamp_format` | `str \| null` | `null` | Explicit [`strftime`](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes) pattern for parsing that field. When unset, `TimeFormatHandler` auto-detects the format (ISO 8601, Apache, syslog, numeric epoch seconds/milliseconds, and other common layouts). |
 
 Set `timestamp_format` when the source uses a layout the auto-detection does not
@@ -485,13 +485,13 @@ Time-aware classification is best-effort and never fails a run:
   falls back to the index axis.
 * If timestamps stop lining up with the recorded observations, or the observed time
   span is zero, or they arrive out of order, `time` silently reuses the equal-index
-  cuts, and `slope_time` computes its centroid on the index axis instead  --  it
+  cuts, and `slope_time` computes its centroid on the index axis instead, so it
   degrades to `slope_index`.
 * Under `majority`, a method that fell back still casts its own vote. If both methods
   of a pair (`slope_index`/`slope_time` or `index`/`time`) are enabled and timestamps
   are unusable, they compute the same verdict, which then counts twice.
 
-In every fallback case classification still runs and produces a result  --  only the
+In every fallback case classification still runs and produces a result; only the
 axis behind it changes back to index.
 
 A segment with no observations in it is *not* a fallback: it scores a mean of 0.0,
@@ -499,7 +499,7 @@ because nothing observed means nothing changed. Once the segment floor above is
 met, equal-index cuts never leave a segment empty; equal-duration cuts of a bursty
 variable still do, routinely, so `time` on its own is lenient towards a burst of
 churn followed by silence. Enable `index` and `time` together when that leniency
-matters  --  the index pass keeps every segment populated.
+matters: the index pass keeps every segment populated.
 
 
 ### Saving state (persist)
@@ -522,7 +522,7 @@ detectors:
       ...
 ```
 
-All fields are optional  --  `persist: {}` uses all defaults. Omitting `persist:` entirely
+All fields are optional: `persist: {}` uses all defaults. Omitting `persist:` entirely
 disables saving (backward compatible). The other detectors (Random, Rule, DeepLog,
 LogBERT) have no state to save: a `persist:` block on them fails at config load with
 `persist: Extra inputs are not permitted`.
@@ -534,7 +534,7 @@ named `NewValueDetector` writes to `./state/NewValueDetector/`.
 
 The default `path` is CWD-relative. systemd services usually run with CWD `/`,
 so `./state` would resolve to `/state` (wrong location, needs root). To avoid
-this, set `StateDirectory=` in your unit file  --  systemd creates `/var/lib/<dir>`
+this, set `StateDirectory=` in your unit file: systemd creates `/var/lib/<dir>`
 with the right ownership and exports `$STATE_DIRECTORY`, which the default `path`
 reads automatically. No explicit `path:` needed:
 
@@ -558,7 +558,7 @@ Setting `path:` explicitly (e.g. an `s3://` URL) always overrides `$STATE_DIRECT
 
 #### Storage options examples
 
-**Local filesystem**  --  no `storage_options` needed:
+**Local filesystem** (no `storage_options` needed):
 
 ```yaml
 persist:
@@ -608,5 +608,5 @@ persist:
 ```
 
 In practice, credentials are usually supplied via environment variables
-(`AWS_ACCESS_KEY_ID`, etc.) or instance roles  --  in which case `storage_options`
+(`AWS_ACCESS_KEY_ID`, etc.) or instance roles, in which case `storage_options`
 stays empty or is omitted.
diff --git a/docs/detectors/ecvc_detector.md b/docs/detectors/ecvc_detector.md
index 17e53b61..af292b69 100644
--- a/docs/detectors/ecvc_detector.md
+++ b/docs/detectors/ecvc_detector.md
@@ -21,7 +21,7 @@ Input and output schemas in the pipeline
 
 A count vector is formed by counting the number of appearances of each event ID in a sequence of a specific window size.
 
-Count vectors learned during training are stored via [persistency](../auxiliar/persistency.md), so a trained model can be saved and restored with a `persist:` block. A count vector is only comparable within the window it was counted over, so restoring state at a different `window_size` logs a warning  --  the restored vectors cannot match and every window would alert.
+Count vectors learned during training are stored via [persistency](../auxiliar/persistency.md), so a trained model can be saved and restored with a `persist:` block. A count vector is only comparable within the window it was counted over, so restoring state at a different `window_size` logs a warning, because the restored vectors cannot match and every window would alert.
 
 ## Example
 
diff --git a/docs/detectors/event_sequence.md b/docs/detectors/event_sequence.md
index 1fade4b2..a8751bf4 100644
--- a/docs/detectors/event_sequence.md
+++ b/docs/detectors/event_sequence.md
@@ -21,7 +21,7 @@ Input and output schemas in the pipeline
 
 The detector slides a window of `fixed_window_size` event IDs over the log stream. During training every full window is stored as a known sequence; during detection a window whose exact sequence is not in that set is reported as an anomaly.
 
-Because a novel event stays inside the window for `fixed_window_size` steps, a single unexpected event produces up to `fixed_window_size` consecutive alerts  --  one per window it invalidates. This is intentional: each of those windows is a distinct sequence that was never trained.
+Because a novel event stays inside the window for `fixed_window_size` steps, a single unexpected event produces up to `fixed_window_size` consecutive alerts, one per window it invalidates. This is intentional: each of those windows is a distinct sequence that was never trained.
 
 Sequences are stored as fixed-length n-grams, so a persisted model is only meaningful at the length it was trained with. When state is restored via [persistency](../auxiliar/persistency.md) at a different `fixed_window_size`, the detector logs a warning, adopts the persisted length, and skips auto-configuration.
 
@@ -31,7 +31,7 @@ With `auto_config: True` the detector spends the configure phase feeding one win
 
 Candidates whose window never filled during the configure phase are skipped, so a short configure phase simply narrows the choice.
 
-If no candidate is stable, no window length is meaningful for this log stream. Rather than fall back to an arbitrary length and alert on nearly every window, the detector generates an empty configuration: **no instance of the detector is created**, `fixed_window_size` stays `None`, and it neither trains nor alerts for the rest of the run. A warning names the range that was searched. The same applies to `auto_config: False` without a `fixed_window_size`  --  the detector stays inert.
+If no candidate is stable, no window length is meaningful for this log stream. Rather than fall back to an arbitrary length and alert on nearly every window, the detector generates an empty configuration: **no instance of the detector is created**, `fixed_window_size` stays `None`, and it neither trains nor alerts for the rest of the run. A warning names the range that was searched. The same applies to `auto_config: False` without a `fixed_window_size`: the detector stays inert.
 
 Longer windows are more specific and therefore alert more readily; if the auto-configured length is too sensitive, narrow the range or set `fixed_window_size` explicitly.
 
diff --git a/docs/detectors/scvs_detector.md b/docs/detectors/scvs_detector.md
index f3ee9609..ce75278a 100644
--- a/docs/detectors/scvs_detector.md
+++ b/docs/detectors/scvs_detector.md
@@ -21,7 +21,7 @@ Input and output schemas in the pipeline
 
 A count vector is formed by counting the number of appearances of each event ID in a sequence of a specific window size.
 
-Count vectors learned during training are stored via [persistency](../auxiliar/persistency.md), so a trained model can be saved and restored with a `persist:` block. A count vector is only comparable within the window it was counted over, so restoring state at a different `window_size` logs a warning  --  the restored vectors cannot match and every window would alert.
+Count vectors learned during training are stored via [persistency](../auxiliar/persistency.md), so a trained model can be saved and restored with a `persist:` block. A count vector is only comparable within the window it was counted over, so restoring state at a different `window_size` logs a warning, because the restored vectors cannot match and every window would alert.
 
 ## Example
 
diff --git a/docs/development.md b/docs/development.md
index c4fc5644..97ba47ce 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -74,7 +74,7 @@ def configure(self, input_):
 ```
 
 The `set_configuration()` method queries the tracker results and writes the
-final `events` block. It touches nothing else on the config  --  everything the
+final `events` block. It touches nothing else on the config: everything the
 operator set under `params` or `auto_config_params` must survive untouched, so
 `set_configuration` never rebuilds the config from scratch:
 
@@ -92,8 +92,8 @@ def set_configuration(self):
 ### Why `auto_config_params` lives on `BasicConfig`
 
 Both `auto_config` and `Component.configure()` are declared on the shared base,
-so `auto_config_params` is declared there too  --  on `BasicConfig`, beside
-`auto_config`  --  rather than on the detector config alone. Detectors are the only
+so `auto_config_params` is declared there too (on `BasicConfig`, beside
+`auto_config`) rather than on the detector config alone. Detectors are the only
 component type with a real configure phase today, so they are the only ones that
 narrow the block with fields; parsers and alert aggregators inherit it empty, and
 an empty block is omitted from the serialized config, so their YAML is unaffected.
@@ -135,7 +135,7 @@ from detectmatelibrary.parsers.logbatcher import LogBatcherParser, LogBatcherPar
 You can also include the whole file by dropping the `:section` suffix
 (`--8<-- "docs/examples/parsers/template_tree_matcher.py"`), but section markers
 are the norm. Because `check_paths: true` is set, the build aborts if the file or
-marker doesn't exist  --  a missing snippet is caught at build time.
+marker doesn't exist, so a missing snippet is caught at build time.
 
 **3. Make sure it's testable.** The test (`tests/test_docs/test_doc_examples.py`)
 globs every `.py` under `docs/examples/` and runs each one as a script via
diff --git a/docs/other/log_formats.md b/docs/other/log_formats.md
index 025e1f35..8cf611a8 100644
--- a/docs/other/log_formats.md
+++ b/docs/other/log_formats.md
@@ -2,7 +2,7 @@
 
 This catalog covers 18 common log formats and provides ready-to-use `log_format` patterns for the DetectMate parsers, such as the [MatcherParser](../parsers/template_matcher.md).
 
-**Key concept:** `log_format` splits a raw log line into structured header fields that become entries in `ParserSchema.logFormatVariables`. The special `<Content>` token captures the variable message body, which is then matched against your template file to produce `EventID` and `variables`. Formats without `<Content>` are fully structured  --  no template file is needed.
+**Key concept:** `log_format` splits a raw log line into structured header fields that become entries in `ParserSchema.logFormatVariables`. The special `<Content>` token captures the variable message body, which is then matched against your template file to produce `EventID` and `variables`. Formats without `<Content>` are fully structured, so no template file is needed.
 
 **Generic configuration:**
 
@@ -77,7 +77,7 @@ Dec 10 07:07:38 LabSZ sshd[24206]: Failed password for invalid user test9 from 1
 
 ### ApacheAccess
 
-Apache httpd access log (Combined Log Format). Each line is fully structured  --  no template file is required.
+Apache httpd access log (Combined Log Format). Each line is fully structured, so no template file is required.
 
 ```text
 64.242.88.10 - - [07/Mar/2004:16:10:02 -0800] "GET /twiki/bin/edit/Main/Double_bounce_sender?topicparent=Main.ConfigurationVariables HTTP/1.1" 401 12846 "-" "Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.2) Gecko/20021202"
@@ -237,7 +237,7 @@ Thunderbird supercomputer log. Similar to BGL but from a different cluster; incl
 
 ### Linux
 
-Linux syslog format (RFC 3164). Produced by `syslog`, `rsyslog`, and `syslog-ng`  --  covers auth, cron, kernel messages, and more.
+Linux syslog format (RFC 3164). Produced by `syslog`, `rsyslog`, and `syslog-ng`; covers auth, cron, kernel messages, and more.
 
 ```text
 Jun 14 15:16:02 combo sshd(pam_unix)[19939]: authentication failure; logname= uid=0 euid=0 tty=NODEVssh ruser= rhost=218.188.2.4
diff --git a/docs/parsers.md b/docs/parsers.md
index abbb2edc..f7661259 100644
--- a/docs/parsers.md
+++ b/docs/parsers.md
@@ -15,7 +15,7 @@ This document explains expected APIs, how to implement a parser, testing tips an
 - `CoreParser.run()` handles lifecycle and calls `parse()` for each input; implement pure parsing logic inside `parse()` where possible.
 - Use a typed `Config` class (subclass of `CoreParserConfig`) to hold runtime parameters.
 
-## CoreParser  --  minimal API
+## CoreParser: minimal API
 
 Recommended signatures and behavior:
 
@@ -28,7 +28,7 @@ class CoreParser:
 
     def parse(self, input_: schemas.LogSchema, output_: schemas.ParserSchema) -> bool | None:
         """Implement parsing here.
-        - Fill the required output_ fields (see "ParserSchema - what to populate" below).
+        - Fill the required output_ fields (see "ParserSchema: what to populate" below).
         - Return True, or None, to emit output_ as the parsed log.
         - Return False to drop the log: process() then returns None for it.
         """
@@ -37,27 +37,27 @@ class CoreParser:
         """Optional: train internal models. Can be a no-op for stateless parsers."""
 ```
 
-## ParserSchema  --  what to populate
+## ParserSchema: what to populate
 
 `parse()` only has to fill the fields that describe the match:
 
-- `EventID` (int)  --  identifier for the matched template/event
-- `template` (string)  --  event template text
-- `variables` (repeated string)  --  extracted parameters (extend the list)
+- `EventID` (int): identifier for the matched template/event
+- `template` (string): event template text
+- `variables` (repeated string): extracted parameters (extend the list)
 
 `CoreParser.run()`, which calls `parse()`, fills in everything else for you:
 
-- `parserID`, `parserType`  --  the parser's name and `method_type`
-- `parsedLogID`  --  a new unique ID for the parsed record
-- `logID`, `log`  --  copied from the input `LogSchema`
-- `logFormatVariables`  --  the header fields extracted with `log_format`
-- `receivedTimestamp`, `parsedTimestamp`  --  set just before and just after
+- `parserID`, `parserType`: the parser's name and `method_type`
+- `parsedLogID`: a new unique ID for the parsed record
+- `logID`, `log`: copied from the input `LogSchema`
+- `logFormatVariables`: the header fields extracted with `log_format`
+- `receivedTimestamp`, `parsedTimestamp`: set just before and just after
   `parse()` runs
 
 Don't set these in `parse()`: `run()` writes `parsedTimestamp` after `parse()`
 returns, so a value set there is overwritten.
 
-## Creating a new parser  --  step by step
+## Creating a new parser: step by step
 
 1. Create a Config class inheriting `CoreParserConfig`.
 2. Create parser class inheriting `CoreParser`.
diff --git a/docs/parsers/logbatcher_parser.md b/docs/parsers/logbatcher_parser.md
index f339f1b5..af199892 100644
--- a/docs/parsers/logbatcher_parser.md
+++ b/docs/parsers/logbatcher_parser.md
@@ -25,8 +25,8 @@ uv sync --extra llm
 
 `LogBatcherParser` wraps the [LogBatcher](https://github.com/LogIntelligence/LogBatcher) engine (MIT, LogIntelligence 2024) as a `CoreParser`. Parsing proceeds in two phases:
 
-1. **Cache lookup**  --  the incoming log is matched against previously seen templates using a hash-based exact match followed by a tree-based similarity check. If a match is found, no LLM call is made.
-2. **LLM query**  --  on a cache miss, the log is submitted to the configured model. The returned template is stored in the cache for future reuse.
+1. **Cache lookup**: the incoming log is matched against previously seen templates using a hash-based exact match followed by a tree-based similarity check. If a match is found, no LLM call is made.
+2. **LLM query**: on a cache miss, the log is submitted to the configured model. The returned template is stored in the cache for future reuse.
 
 Variable slots in templates use the `<*>` wildcard notation (e.g. `User <*> logged in from <*>`). Extracted variables are written to `output_["variables"]` in order of appearance.
 
diff --git a/docs/user_guide/basic_knowledge.md b/docs/user_guide/basic_knowledge.md
index 91dd0462..f1630aa0 100644
--- a/docs/user_guide/basic_knowledge.md
+++ b/docs/user_guide/basic_knowledge.md
@@ -62,12 +62,12 @@ INFO [18-05-2005] hello I am a log about DetectMate getting started and about wh
 
 This line has three parts:
 
-- **`INFO` -- the category of the message (the "log level").** Some other
+- **`INFO`: the category of the message (the "log level").** Some other
 messages from the program could be for example `DEBUG` (fine-grained detail for developers) or `WARNING` (something looks off, but it's not a failure yet). So this part just gives you a hint how important this logging statement is.
 
-- **`[18-05-2005]` -- the timestamp:** when the message was written.
+- **`[18-05-2005]`: the timestamp,** i.e. when the message was written.
 
-- **`hello I am a log...` -- the actual text:** what the program wants to tell you.
+- **`hello I am a log...`: the actual text,** i.e. what the program wants to tell you.
 
 The log level sits at the very front because it acts as a filter: in real systems thousands of lines pile up every second, so you can say e.g. "only show me `WARNING` and worse." That way both humans and machines can instantly decide whether a line is relevant.
 
diff --git a/docs/user_guide/tutorial.md b/docs/user_guide/tutorial.md
index 0f8a331a..9fdc0113 100644
--- a/docs/user_guide/tutorial.md
+++ b/docs/user_guide/tutorial.md
@@ -1,6 +1,6 @@
 # Tutorial (end-to-end)
 
-A complete walkthrough of using DetectMate  --  more detailed than the
+A complete walkthrough of using DetectMate, more detailed than the
 [Quickstart](quickstart.md). The Quickstart parses a ready-made dataset with a
 ready-made template file and runs one detector. This tutorial goes one level
 deeper:
@@ -18,8 +18,8 @@ importantly, understand *why* each piece behaves the way it does.
 The Quickstart uses the `audit.log` dataset, which already ships with a
 matching `audit_templates.txt`. To actually practice building
 something, this tutorial uses a different file instead:
-`docs/examples/data/tutorial_audit.log`. It is still Linux `auditd` output  --  same overall
-shape as the Quickstart's dataset  --  but recorded on a different machine, and
+`docs/examples/data/tutorial_audit.log`. It is still Linux `auditd` output (same overall
+shape as the Quickstart's dataset), but recorded on a different machine, and
 this time **you write the templates yourself**. A finished template file is
 included in the repository, but only so you can check your result in step 2.
 That is the point: before you can parse a dataset, you have to look at it.
@@ -38,7 +38,7 @@ That is the point: before you can parse a dataset, you have to look at it.
 `From.log` is the same helper used in the Quickstart (see the
 [From helper](../helper/from_to.md) docs). Passing `do_process=False`
 turns it into a plain file reader that hands back [`LogSchema`](../schemas.md)
-objects instead of running them through a parser  --  exactly what you want
+objects instead of running them through a parser, which is exactly what you want
 before you've decided how to parse the data.
 
 The file only has 9 lines, small enough to read in full:
@@ -56,8 +56,8 @@ type=SYSCALL msg=audit(1757673850.283:5): arch=c00000b7 syscall=206 success=yes
 ```
 
 Every line starts with the same prefix shape, `type=<Type> msg=audit(<Time>:<Serial>):
-<Content>`, and there are only four distinct *event types*  --  `DAEMON_START`,
-`CONFIG_CHANGE`, `SYSCALL`, and `PROCTITLE`  --  each with its own static
+<Content>`, and there are only four distinct *event types* (`DAEMON_START`,
+`CONFIG_CHANGE`, `SYSCALL`, and `PROCTITLE`), each with its own static
 template hiding behind the variable parts.
 
 ## 2. Build and configure your own parser
@@ -93,13 +93,13 @@ proctitle=<*>
 
 A few things worth noticing while writing templates like these:
 
-- The line number is the `EventID`  --  line 1 (0-indexed: `0`) matches
+- The line number is the `EventID`: line 1 (0-indexed: `0`) matches
   `DAEMON_START`, line 2 (`1`) matches `CONFIG_CHANGE`, and so on, exactly as
   described in [EventID assignment](../parsers/template_matcher.md#eventid-assignment-preliminary).
 - The second template's `op=set <*> old=<*> ...` has only one wildcard where
   the raw text has an `audit_backlog_limit=8192`, `audit_failure=1`, or
   `audit_backlog_wait_time=60000` key/value pair. A single `<*>` is not
-  limited to one word  --  it happily captures the whole `key=value` chunk, so
+  limited to one word: it happily captures the whole `key=value` chunk, so
   there's no need for a wildcard per key name even though the key itself
   varies between log lines.
 - None of the templates need to account for the trailing `AUID="unset"
@@ -115,17 +115,17 @@ A few things worth noticing while writing templates like these:
 
 > **Common pitfall: don't escape `log_format` yourself.** The Quickstart's
 > `log_format` string escapes the parentheses by hand:
-> `r"...audit\(<Time>:<Serial>\):..."`. Don't copy that  --  it's wrong.
+> `r"...audit\(<Time>:<Serial>\):..."`. Don't copy that; it's wrong.
 > `generate_logformat_regex()` (used internally by every parser that accepts
 > `log_format`) already escapes every literal character outside the
 > `<Placeholder>` tokens, parentheses included. Escaping them yourself asks it
 > to match a **literal backslash** followed by `(`, which never occurs in
-> real log data  --  the regex then silently fails to match anything, and every
+> real log data. The regex then silently fails to match anything, and every
 > log falls back to `<Not Found>`. Write `log_format` as plain text; only the
 > `<Placeholder>` tokens are special.
 
 Running this prints, for each of the 9 logs, the `EventID` and the matched
-template  --  all four templates get used, and every line matches (nothing
+template. All four templates get used, and every line matches (nothing
 comes back as `<Not Found>`).
 
 ## 3. Run several detectors and compare their alerts
@@ -147,7 +147,7 @@ stream:
 
 Both detectors are configured with `data_use_training: 3`: the first 3 logs
 (`DAEMON_START`, `CONFIG_CHANGE`, `SYSCALL`) are used to train, and detection
-runs on the remaining 6  --  see [Configuration](../detectors.md#configuration)
+runs on the remaining 6; see [Configuration](../detectors.md#configuration)
 for how `data_use_training` and `events` interact. `NewValueDetector` is
 pointed at the two fields we identified while writing the templates in step
 2: the `key=value` pair inside `CONFIG_CHANGE` (`EventID: 1`, `pos: 0`) and
@@ -174,24 +174,24 @@ In the table above, **`True` means that detector raised an alert** for that log
 Reading the table alongside the raw data explains why each detector fires
 when it does:
 
-- **`NewValueDetector`** only fires on logs `#5` and `#8`  --  the second and
+- **`NewValueDetector`** only fires on logs `#5` and `#8`: the second and
   third `CONFIG_CHANGE` events, whose `audit_failure=1` and
   `audit_backlog_wait_time=60000` values were never seen during training
   (only `audit_backlog_limit=8192`, from log `#2`, was). It stays silent on
   every `SYSCALL` after log `#3`, because `comm="auditctl"` is identical
-  every time  --  there is nothing *new* about it once it's been trained once.
+  every time, so there is nothing *new* about it once it's been trained once.
 - **`EventSequenceDetector`** fires starting at log `#4`, and on every log
   after that except the `SYSCALL`s. With `fixed_window_size: 2`, training on
   the first 3 logs only teaches it the transitions `(DAEMON_START →
   CONFIG_CHANGE)` and `(CONFIG_CHANGE → SYSCALL)`. The transition `(SYSCALL →
-  PROCTITLE)` at log `#4` was never trained, so it alerts  --  and keeps
+  PROCTITLE)` at log `#4` was never trained, so it alerts, and keeps
   alerting every time that same transition recurs (`#7`), because alerts
   don't teach the detector anything; only `train()` does. `(PROCTITLE →
   CONFIG_CHANGE)` at log `#5` is equally untrained and alerts too, while
   `(CONFIG_CHANGE → SYSCALL)` at logs `#6` and `#9` was trained at log `#3`
   and stays quiet.
 
-Note that both detectors agree on logs `#5` and `#8`  --  the same underlying
+Note that both detectors agree on logs `#5` and `#8`: the same underlying
 event looks anomalous from two independent angles: an unfamiliar value *and*
 an unfamiliar position in the sequence. That overlap is what an alert
 aggregator is for.
@@ -201,7 +201,7 @@ aggregator is for.
 [Alert aggregation](../alert_aggregator.md) takes the stream of alerts coming
 out of one or more detectors and combines them into
 [`AggregateSchema`](../schemas.md) records. Here we feed every alert produced
-in step 3  --  from either detector, in the order they were emitted  --  into
+in step 3 (from either detector, in the order they were emitted) into
 [`BasicConcatAggregation`](../alert_aggregators/basic_concatenation.md), the
 simplest aggregation strategy available:
 
@@ -227,7 +227,7 @@ Two details are easy to miss here, and both matter for production configs:
   produce five overlapping aggregate outputs, not three separate batches.
 - **`BasicConcatAggregation` does not correlate by log line.** It concatenates
   whatever alerts happen to be in the window, regardless of which log they
-  refer to  --  that's why most rows above pair up alerts from *different*
+  refer to. That's why most rows above pair up alerts from *different*
   underlying logs. The two rows where both `logIDs` are identical
   (`['4', '4']` and `['7', '7']`) are the exception, and not a coincidence:
   those are exactly the log `#5` and `#8` cases from step 3 (`logIDs` count
@@ -252,5 +252,5 @@ Two details are easy to miss here, and both matter for production configs:
   [New Event Detector](../detectors/new_event.md) exists to alert on exactly
   those never-seen `EventID`s.
 * Calling `.process()` on a detector or aggregator returns `None` when
-  nothing fires, and the actual output schema (truthy) when it does  --  check
+  nothing fires, and the actual output schema (truthy) when it does, so check
   with `if result:` rather than assuming a boolean.

From 55f95fbc4bd4f6641b08ae64cc36ca1a02fc9f77 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Fri, 9 Oct 2026 13:42:09 +0200
Subject: [PATCH 39/40] corrections, add window behaviour

---
 docs/alert_aggregator.md | 61 +++++++++++++++++++++++++++++-----------
 1 file changed, 45 insertions(+), 16 deletions(-)

diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index bc5a6e8b..97fa7636 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -1,40 +1,69 @@
-# Components: Alert Aggregation
+# Alert Aggregation
 
-Alert aggregation aggregates alerts from detectors.
+Alert aggregators combine the alerts produced by detectors into aggregated records.
 
 |            | Schema                     | Description        |
 |------------|----------------------------|--------------------|
 | **Input**  | [DetectorSchema](schemas.md)    | Alerts from detectors  |
 | **Output** | [AggregateSchema](schemas.md) | Aggregated alerts    |
 
-This document explains expected APIs, how to implement an alert aggregator, testing tips and common pitfalls.
+This document explains the expected API and how to implement an alert aggregator.
 
 ## Overview
 
-- Alert aggregation must inherit from `CoreAlertAggregator` and provide a `aggregate_alerts()` implementation.
-- `CoreParser.run()` handles lifecycle and calls `aggregate_alerts()` for each input; implement pure alert aggregation logic inside `aggregate_alerts()` where possible.
+- Alert aggregators must inherit from `CoreAlertAggregator` and provide an `aggregate_alerts()` implementation.
+- `CoreAlertAggregator.run()` handles the lifecycle and calls `aggregate_alerts()`. Aggregators use a
+  sliding window (a `WINDOW` [data buffer](auxiliar/input_buffer.md)) of `buffer_size` alerts, so
+  `aggregate_alerts()` always receives a **list**: the most recent `buffer_size` alerts. It is first
+  called once the window is full, and then once for every new alert, so consecutive windows overlap.
+  With the default `buffer_size` of 1, it is called for every alert with a list of one.
 - Use a typed `Config` class (subclass of `CoreAlertAggregatorConfig`) to hold runtime parameters.
 
 ## CoreAlertAggregator: minimal API
 
-Recommended signatures and behavior:
-
 ```python
-class CoreAlertAggregator:
- def aggregate_alerts(
+class CoreAlertAggregator(CoreComponent):
+    def __init__(
+        self,
+        name: str = "CoreAlertAggregator",
+        buffer_mode: BufferMode = BufferMode.WINDOW,
+        buffer_size: int | None = 1,
+        config: CoreAlertAggregatorConfig | dict[str, Any] | None = CoreAlertAggregatorConfig(),
+    ) -> None:
+        """buffer_mode and buffer_size set which alerts aggregate_alerts() receives per call."""
+
+    def aggregate_alerts(
         self,
         input_: list[DetectorSchema] | DetectorSchema,
         output_: AggregateSchema,
     ) -> bool:
-        return True
+        """Implement the aggregation here.
+        - Return True to emit output_ as the aggregated record.
+        - Return False to emit nothing: process() then returns None.
+        """
 
-    @override
-    def train(
-        self, input_: DetectorSchema | list[DetectorSchema]
-    ) -> None:
-        pass
+    def train(self, input_: DetectorSchema | list[DetectorSchema]) -> None:
+        """Optional: learn from alerts. Can be a no-op."""
 ```
 
-## Available alert aggregation
+## What `run()` fills in for you
+
+Before calling `aggregate_alerts()`, `CoreAlertAggregator.run()` collects these fields from the
+alerts in the window:
+
+- `detectorIDs`, `detectorTypes`, `alertIDs`: one entry per alert
+- `logIDs`, `extractedTimestamps`: the entries of all alerts, combined into one list
+
+After `aggregate_alerts()` returns `True`, `run()` also sets `outputTimestamp`. So
+`aggregate_alerts()` only has to set `description` and `alertsObtain`.
+
+!!! warning "The alerts' details are not carried over"
+    `run()` copies only IDs and timestamps. The `description` and `alertsObtain` of the incoming
+    alerts, which hold the actual alert messages, are **not** copied into the aggregate, and
+    `AggregateSchema` has no `score` field at all. If your aggregator needs this information, read it
+    from `input_` in `aggregate_alerts()` and write it into `output_["description"]` or
+    `output_["alertsObtain"]` yourself.
+
+## Available alert aggregators
 
 - [Basic Concat](alert_aggregators/basic_concatenation.md)

From df827a64a9cdae33fbb599eedfda971bcb4459e0 Mon Sep 17 00:00:00 2001
From: thorinaboenke <thorina-boenke@web.de>
Date: Mon, 12 Oct 2026 10:27:54 +0200
Subject: [PATCH 40/40] improve alert aggregation wording!

---
 docs/alert_aggregator.md | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/docs/alert_aggregator.md b/docs/alert_aggregator.md
index 97fa7636..deac6763 100644
--- a/docs/alert_aggregator.md
+++ b/docs/alert_aggregator.md
@@ -54,15 +54,13 @@ alerts in the window:
 - `detectorIDs`, `detectorTypes`, `alertIDs`: one entry per alert
 - `logIDs`, `extractedTimestamps`: the entries of all alerts, combined into one list
 
-After `aggregate_alerts()` returns `True`, `run()` also sets `outputTimestamp`. So
-`aggregate_alerts()` only has to set `description` and `alertsObtain`.
+After `aggregate_alerts()` returns `True`, `run()` also sets `outputTimestamp`. So the only
+fields left for `aggregate_alerts()` to fill are `description` and `alertsObtain`.
 
 !!! warning "The alerts' details are not carried over"
-    `run()` copies only IDs and timestamps. The `description` and `alertsObtain` of the incoming
-    alerts, which hold the actual alert messages, are **not** copied into the aggregate, and
-    `AggregateSchema` has no `score` field at all. If your aggregator needs this information, read it
-    from `input_` in `aggregate_alerts()` and write it into `output_["description"]` or
-    `output_["alertsObtain"]` yourself.
+    `run()` copies only the fields listed above. Everything else in the incoming alerts is dropped
+    unless your `aggregate_alerts()` keeps it, including their `detectionTimestamp` and
+    `receivedTimestamp`.
 
 ## Available alert aggregators