From 629a2e65a370b8ed14e663e0fd3a2e31875947c8 Mon Sep 17 00:00:00 2001
From: stacknil <stacknil@proton.me>
Date: Mon, 23 Mar 2026 16:20:23 +0800
Subject: [PATCH 1/3] build: add local setup README pointer

---
 README.md | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 07a59a2..e41d04c 100644
--- a/README.md
+++ b/README.md
@@ -80,15 +80,17 @@ LogLens does not currently detect:
 - PAM-specific failures beyond the parsed sample patterns
 - Cross-file or cross-host correlation
 
-## Build
-
-```bash
-cmake -S . -B build
-cmake --build build
-ctest --test-dir build --output-on-failure
-```
-
-## Run
+## Build
+
+```bash
+cmake -S . -B build
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+For fresh-machine setup and repeatable local presets, see [`docs/dev-setup.md`](./docs/dev-setup.md).
+
+## Run
 
 ```bash
 ./build/loglens --mode syslog --year 2026 ./assets/sample_auth.log ./out

From 29ea23eb00257ca6a341f049513720c126229637 Mon Sep 17 00:00:00 2001
From: stacknil <stacknil@proton.me>
Date: Mon, 23 Mar 2026 16:20:33 +0800
Subject: [PATCH 2/3] build: add minimal developer setup doc

---
 docs/dev-setup.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/dev-setup.md

diff --git a/docs/dev-setup.md b/docs/dev-setup.md
new file mode 100644
index 0000000..dd39328
--- /dev/null
+++ b/docs/dev-setup.md
@@ -0,0 +1,67 @@
+# Developer Setup
+
+This note is for contributors working in a fresh local environment. It keeps the setup small and mirrors the repository's existing CMake and CTest flow.
+
+## Required Tools
+
+- CMake 3.21 or newer for the shared presets in `CMakePresets.json`
+- CMake 3.20 or newer for the manual fallback flow
+- A C++20 compiler
+  - Windows: Visual Studio 2022 or Build Tools 2022 with the MSVC v143 toolset
+  - Linux: `g++` 10+ or `clang++` 14+ plus `make` or `ninja`
+- Git for normal contribution flow
+
+## Quick Start With Presets
+
+`CMakePresets.json` includes two repeatable local entry points:
+
+- `dev-debug`: default local iteration build with tests enabled
+- `ci-release`: release build intended to mirror the GitHub Actions CI flags
+
+Local debug iteration:
+
+```bash
+cmake --preset dev-debug
+cmake --build --preset dev-debug
+ctest --preset dev-debug
+```
+
+Local CI-style validation:
+
+```bash
+cmake --preset ci-release
+cmake --build --preset ci-release
+ctest --preset ci-release
+```
+
+## Manual Fallback
+
+If you do not want to use presets, or if your local CMake is 3.20 but not 3.21+, the equivalent manual flow is:
+
+```bash
+cmake -S . -B build -D CMAKE_BUILD_TYPE=Debug -D BUILD_TESTING=ON
+cmake --build build
+ctest --test-dir build --output-on-failure
+```
+
+## Windows Notes
+
+- Run from a Developer PowerShell for Visual Studio 2022, an x64 Native Tools prompt, or another shell where the MSVC toolchain is already available.
+- If `cmake` is missing from `PATH`, install either the Visual Studio C++ workload with CMake support or a standalone Kitware CMake package, then reopen the shell.
+- Visual Studio generators are multi-config, so the presets set `Debug` or `Release` again at build and test time for consistency.
+
+## Linux Notes
+
+- A small Ubuntu/Debian-style setup is usually enough:
+
+```bash
+sudo apt install cmake g++ make
+```
+
+- If you prefer Clang, configure manually with `-D CMAKE_CXX_COMPILER=clang++` or create a local user preset.
+
+## Expected Local Outputs
+
+- Build directories under `build/dev-debug` or `build/ci-release`
+- Test runs for `parser`, `detector`, and `cli`
+- `compile_commands.json` in the debug build directory when the selected generator supports it

From 018bcffe9164cfdfcc5ad4d87ce863fe7932a7ed Mon Sep 17 00:00:00 2001
From: stacknil <stacknil@proton.me>
Date: Mon, 23 Mar 2026 16:20:43 +0800
Subject: [PATCH 3/3] build: add shared CMake presets

---
 CMakePresets.json | 61 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 CMakePresets.json

diff --git a/CMakePresets.json b/CMakePresets.json
new file mode 100644
index 0000000..e134a5b
--- /dev/null
+++ b/CMakePresets.json
@@ -0,0 +1,61 @@
+{
+  "version": 3,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 20,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "dev-debug",
+      "displayName": "Local Debug",
+      "description": "Default local debug build with tests enabled.",
+      "binaryDir": "${sourceDir}/build/dev-debug",
+      "cacheVariables": {
+        "BUILD_TESTING": "ON",
+        "CMAKE_BUILD_TYPE": "Debug",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    },
+    {
+      "name": "ci-release",
+      "displayName": "CI-style Release",
+      "description": "Release build that matches the repository CI flags.",
+      "binaryDir": "${sourceDir}/build/ci-release",
+      "cacheVariables": {
+        "BUILD_TESTING": "ON",
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "dev-debug",
+      "configurePreset": "dev-debug",
+      "configuration": "Debug"
+    },
+    {
+      "name": "ci-release",
+      "configurePreset": "ci-release",
+      "configuration": "Release"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "dev-debug",
+      "configurePreset": "dev-debug",
+      "configuration": "Debug",
+      "output": {
+        "outputOnFailure": true
+      }
+    },
+    {
+      "name": "ci-release",
+      "configurePreset": "ci-release",
+      "configuration": "Release",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}