build: modernize repo-lens skeleton and cross-platform configuration

Replace CPM with FetchContent and update GoogleTest to v1.18.0.
Add compiler toolchains and Debug, Release, and sanitizer presets.
Require CMake 4.0, use target properties for compiler settings,
and enable compilation database export.

Fix skeleton compilation errors and adopt trailing return types,
nodiscard execute methods, and noexcept signatures. Update CI
and project documentation without implementing any TODOs.

Validated Windows builds and tests in all three configurations.

README.md

@@ -4,7 +4,45 @@ repo-lens is a planned lightweight, agent-agnostic repository navigation and con
 
 Coding agents often spend expensive model context rediscovering where code lives and reading irrelevant source. repo-lens aims to perform cheap, deterministic repository queries locally and return compact, bounded results, leaving the model more room to reason about the requested change.
 
-**Status:** early documentation/bootstrap stage. The repository contains inherited C++ starter scaffolding, but repo-lens functionality is not yet implemented. The initial implementation is intended to be a native C++ command-line tool with the executable name `repo`.
+**Status:** early bootstrap stage. The repository contains a native C++ CLI skeleton and inherited build/test scaffolding, but navigation functionality is not yet implemented. The command-line executable is named `repo`.
+
+The skeleton defines `find`, `map`, and `around` tool types. Argument parsing, usage output, and tool implementations remain TODOs; `around` is not dispatched yet. The existing test is a sample assertion, not a navigation test. C++ functions use trailing return types, and the tool interface requires checked `[[nodiscard]]` results and `noexcept` execution.
+
+## Building the skeleton
+
+Use CMake 4.0 or newer, Ninja, and a C++20 compiler. Presets use separate build directories under `build/<preset>` and provide matching configure, build, and test commands:
+
+```text
+cmake --list-presets
+cmake --preset msvc-debug
+cmake --build --preset msvc-debug
+ctest --preset msvc-debug
+```
+
+After editing code, repeat the build and test steps; reconfigure when changing options or presets. To work in Visual Studio, open the repository folder and select a preset. Ninja does not generate a solution for `cmake --open`. Manual configuration with a Visual Studio generator still supports that command, using a separate build directory.
+
+Configuration generates `compile_commands.json` in the build directory, for example `build/msvc-debug/compile_commands.json`. Export is enabled by default for manual builds too. CMake supports this with Ninja and Makefile generators; Visual Studio solution generators do not produce it. In Visual Studio, use Open Folder with a Ninja preset when you need the compilation database.
+
+Choose a preset for your host and compiler:
+
+| Host | Debug | Release |
+| --- | --- | --- |
+| Linux, GCC | `gcc-debug` | `gcc-release` |
+| Linux, Clang | `clang-debug` | `clang-release` |
+| macOS, AppleClang | `appleclang-debug` | `appleclang-release` |
+| Windows, MSVC | `msvc-debug` | `msvc-release` |
+
+Each compiler also has a `<compiler>-sanitizers` Debug preset, with matching build/test presets. It enables AddressSanitizer on MSVC and AddressSanitizer plus UndefinedBehaviorSanitizer on GCC/Clang, with undefined-behavior findings terminating the process. Configuration checks that the combination compiles and links. The executable and test target are instrumented; MSVC also instruments GoogleTest to keep STL annotations consistent. Run sanitizer tests in the same compiler developer environment used for building, so the runtime is available.
+
+Warnings remain local to project targets. `ENABLE_WARNINGS_AS_ERRORS=OFF` disables their error policy; CMake's `--compile-no-warning-as-error` configure option also overrides it. MSVC sanitizer builds use target properties for debug information and runtime checks, leaving directory-level compiler flags unchanged.
+
+On Windows, run these commands from an x64 Native Tools Command Prompt or Developer PowerShell for Visual Studio, with Ninja on `PATH`. On Linux, install the chosen compiler and Ninja; on macOS, install Xcode Command Line Tools and Ninja. Toolchain files in `cmake/toolchains/` select native compilers; these presets do not cross-compile to another operating system. Local paths and overrides belong in an untracked `CMakeUserPresets.json` or configure arguments.
+
+The default build includes the existing GoogleTest sample test and may download its build dependencies. For an application-only build without downloads, configure with `-DENABLE_TESTS=OFF` and skip the test step. Sanitizers are opt-in with `-DENABLE_SANITIZERS=ON`; static analysis and warnings retain their existing configuration options. Building successfully does not make the stub commands functional. Manual configuration with `cmake -S . -B build/manual` remains supported; set `-DCMAKE_BUILD_TYPE=Debug` for single-configuration generators.
+
+GoogleTest is pinned to v1.18.0 and managed by CMake's built-in FetchContent. To reuse a local checkout without downloading it, configure with `-DFETCHCONTENT_SOURCE_DIR_GOOGLETEST=/absolute/path/to/googletest`.
+
+CI installs CMake 4.x and runs Debug, Release, and sanitizer presets for Linux GCC/Clang, macOS AppleClang, and Windows MSVC. The inherited static-analysis helper configures Visual Studio generators; the Ninja presets do not currently run clang-tidy or Microsoft code analysis.
 
 ## Navigation philosophy
 
@@ -18,6 +56,8 @@ Results should have explicit context limits. A query with hundreds of matches sh
 
 Semantic bookmarks may identify stable architectural locations in source that ordinary symbols cannot express. They should be sparse and avoid duplicating easily searchable symbols; lookup should lead to a bounded source excerpt.
 
+Two `# @ai-bookmark` comments currently mark build invariants: the optional test dependency boundary and MSVC sanitizer annotation alignment. Their paths are listed in [the project map](docs/PROJECTMAP.md). Locate them with ripgrep for now; bookmark commands remain directional.
+
 ## Directional CLI
 
 These examples illustrate possible workflows. They are neither implemented nor a final command set: