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.

.github/workflows/ci.yml

@@ -6,70 +6,55 @@ on:
   pull_request:
     branches: [ "main" ]
 
-env:
-  CLANG_TIDY_VERSION: "13.0.0"
-
 jobs:
   build:
-    runs-on: ${{matrix.os}}
+    runs-on: ${{ matrix.platform.os }}
     strategy: 
       fail-fast: false
       matrix:
-        os: [windows-latest, ubuntu-latest, macos-latest]
+        build_configuration: [debug, release, sanitizers]
-        build_configuration: [Debug, Release]
+        platform:
-        compiler: [llvm, gcc]
+          - { os: ubuntu-latest, compiler: gcc }
-
+          - { os: ubuntu-latest, compiler: clang }
-        exclude:
+          - { os: macos-latest, compiler: appleclang }
-          - os: windows-latest
+          - { os: windows-latest, compiler: msvc }
-
-        include:
-          - os: 'windows-latest'
-            compiler: llvm
-            build_configuration: Debug
-
-          - os: 'windows-latest'
-            compiler: llvm
-            build_configuration: Release
-
-          - os: 'windows-latest'
-            compiler: gcc
-            build_configuration: Debug
-
-          - os: 'windows-latest'
-            compiler: gcc
-            build_configuration: Release
-
-          - os: 'windows-latest'
-            compiler: msvc
-            build_configuration: Debug
-
-          - os: 'windows-latest'
-            compiler: msvc
-            build_configuration: Release
-
-          - os: 'ubuntu-latest'
-            triplet: x64-linux
-
-          - os: 'macos-latest'
-            triplet: x64-osx
 
     steps:
     - name: checkout
       uses: actions/checkout@v3
 
+    - name: Set up Python for CMake installation
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install CMake 4.x
+      run: python -m pip install "cmake>=4.0,<5"
+
+    - name: Set up MSVC developer environment
+      if: runner.os == 'Windows'
+      uses: ilammy/msvc-dev-cmd@v1
+
+    - name: Install Ninja on Linux
+      if: runner.os == 'Linux'
+      run: sudo apt-get update && sudo apt-get install -y ninja-build
+
+    - name: Install Ninja on macOS
+      if: runner.os == 'macOS'
+      run: brew list ninja >/dev/null 2>&1 || brew install ninja
+
     - name: cache
       uses: actions/cache@v3
       with:
-        path: "**/CPM_modules"
+        path: build/${{ matrix.platform.compiler }}-${{ matrix.build_configuration }}/_deps
-        key: ${{ github.workflow }}-cpm-modules-${{ hashFiles('**/CMakeLists.txt', '**/*.cmake') }}
+        key: ${{ runner.os }}-${{ matrix.platform.compiler }}-${{ matrix.build_configuration }}-${{ github.workflow }}-fetchcontent-${{ hashFiles('CMakePresets.json', '**/CMakeLists.txt', '**/*.cmake') }}
 
     - name: Configure CMake
-      run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{matrix.build_configuration}}
+      run: cmake --preset ${{ matrix.platform.compiler }}-${{ matrix.build_configuration }}
 
     - name: Build
-      run: cmake --build ${{github.workspace}}/build --config ${{matrix.build_configuration}}
+      run: cmake --build --preset ${{ matrix.platform.compiler }}-${{ matrix.build_configuration }} --parallel 2
 
     - name: Test
-      working-directory: ${{github.workspace}}/build
+      run: ctest --preset ${{ matrix.platform.compiler }}-${{ matrix.build_configuration }}
-      run: ctest -C ${{matrix.build_configuration}}
 

.gitignore

@@ -35,6 +35,8 @@
 *.pdb
 *.exp
 
+.build
 build/
+CMakeUserPresets.json
 .vs/
 Testing/

AGENTS.md

@@ -0,0 +1,14 @@
+# Working on repo-lens
+
+- Keep engineering simple: prefer deterministic local queries, bounded output, composable commands, and explicit context limits. Orchestrate proven tools before reimplementing them; semantic tooling must remain optional.
+- Avoid speculative infrastructure, dependencies, and abstractions. Introduce complexity only for a demonstrated need; source and Git are canonical.
+- Write clear, maintainable native C++. Follow surrounding code and existing formatting/tool configuration. Do not invent detailed conventions; document project conventions as they actually emerge.
+- Use trailing return types where applicable. Declare `execute` overrides `[[nodiscard]]` and `noexcept`, matching the interface. Keep `noexcept` contracts honest: recoverable execution failures must be returned as exit codes rather than escaping exceptions.
+- Start with `docs/PROJECTMAP.md`. Prefer available symbol lookup for known symbols, textual search for known text, and sparse semantic bookmarks for architectural concepts without suitable symbols. Search, narrow, inspect a bounded range or containing symbol, then expand only as needed. Justify whole-file reads.
+- Keep context small: summarize large result sets, report limits and omitted results, and inspect callers, references, tests, or related code only when relevant. Never claim semantic classifications that the underlying evidence cannot establish reliably.
+- Inspect the working tree before editing; preserve existing human changes. Keep changes focused and avoid unrelated cleanup.
+- Create feature branches when requested. Never commit, merge, push, submit, or otherwise publish changes unless explicitly instructed. The human developer decides when work is complete and integrates it.
+- Validate proportionately: use relevant builds/tests for implementation changes and check documentation for accuracy and scope. Report what was checked and any limitations; do not claim unrun checks passed.
+- Use the matching configure/build/test preset for your host compiler; use its sanitizer preset when runtime validation is relevant. The sample test does not validate navigation behavior. Generated build trees and compilation databases are outputs, not source to edit.
+- Keep `@ai-bookmark` markers sparse and unique, for stable architectural boundaries or invariants without a useful symbol. Record their routes in the project map and return bounded excerpts when using them; do not label every function or TODO.
+- Keep documentation concise and useful. Update the project map when routing materially changes. Record decisions only when they preserve rationale or invariants not cheaply inferable from source and Git; do not maintain AI changelogs or persistent agent history.

CMakeLists.txt

@@ -1,25 +1,27 @@
-cmake_minimum_required(VERSION 3.23)
+cmake_minimum_required(VERSION 4.0)
 
-project(blank-slate VERSION 1.0.0)
+project(repo-lens VERSION 1.0.0 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED true)
-set(CMAKE_CONFIGURATION_TYPES "Debug;Release" CACHE STRING "" FORCE)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON CACHE BOOL "Generate compile_commands.json with supported generators")
 
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 OPTION(ENABLE_TESTS "Enable Unit Tests" ON)
 OPTION(ENABLE_ALL_REASONABLE_WARNINGS "Enable all possible reasonable warnings" ON )
 OPTION(ENABLE_WARNINGS_AS_ERRORS "Warnings are treated as Errors" ON)
 OPTION(ENABLE_STATIC_ANALYSIS "Enable Static Analysis Tools" ON)
-OPTION(ENABLE_SANITIZERS "Enable Sanitizer Tools" ON)
+OPTION(ENABLE_SANITIZERS "Enable Sanitizer Tools" OFF)
 
 list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake)
 
 include(compilerwarnings)
 include(sanitizers)
 include(staticanalysis)
-include(cpm)
 
+# @ai-bookmark OPTIONAL_TEST_DEPENDENCY_BOUNDARY
+# Keep dependency downloads inside the optional test path; the application builds offline.
 if (ENABLE_TESTS)
     message("-- Unit Testing Enabled")
     enable_testing()

CMakePresets.json

@@ -0,0 +1,84 @@
+{
+  "version": 4,
+  "cmakeMinimumRequired": { "major": 4, "minor": 0, "patch": 0 },
+  "configurePresets": [
+    {
+      "name": "base",
+      "hidden": true,
+      "generator": "Ninja",
+      "binaryDir": "${sourceDir}/.build/${presetName}",
+      "cacheVariables": {
+        "CMAKE_EXPORT_COMPILE_COMMANDS": true,
+        "ENABLE_TESTS": true,
+        "ENABLE_SANITIZERS": false
+      }
+    },
+    { "name": "debug", "hidden": true, "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" } },
+    { "name": "release", "hidden": true, "cacheVariables": { "CMAKE_BUILD_TYPE": "Release" } },
+    {
+      "name": "gcc", "hidden": true,
+      "toolchainFile": "${sourceDir}/cmake/toolchains/gcc.cmake",
+      "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Linux" }
+    },
+    {
+      "name": "clang", "hidden": true,
+      "toolchainFile": "${sourceDir}/cmake/toolchains/clang.cmake",
+      "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Linux" }
+    },
+    {
+      "name": "appleclang", "hidden": true,
+      "toolchainFile": "${sourceDir}/cmake/toolchains/appleclang.cmake",
+      "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Darwin" }
+    },
+    {
+      "name": "msvc", "hidden": true,
+      "toolchainFile": "${sourceDir}/cmake/toolchains/msvc.cmake",
+      "condition": { "type": "equals", "lhs": "${hostSystemName}", "rhs": "Windows" }
+    },
+    { "name": "gcc-debug", "inherits": ["base", "debug", "gcc"] },
+    { "name": "gcc-release", "inherits": ["base", "release", "gcc"] },
+    { "name": "clang-debug", "inherits": ["base", "debug", "clang"] },
+    { "name": "clang-release", "inherits": ["base", "release", "clang"] },
+    { "name": "appleclang-debug", "inherits": ["base", "debug", "appleclang"] },
+    { "name": "appleclang-release", "inherits": ["base", "release", "appleclang"] },
+    { "name": "msvc-debug", "inherits": ["base", "debug", "msvc"] },
+    { "name": "msvc-release", "inherits": ["base", "release", "msvc"] },
+    { "name": "gcc-sanitizers", "inherits": "gcc-debug", "cacheVariables": { "ENABLE_SANITIZERS": true } },
+    { "name": "clang-sanitizers", "inherits": "clang-debug", "cacheVariables": { "ENABLE_SANITIZERS": true } },
+    { "name": "appleclang-sanitizers", "inherits": "appleclang-debug", "cacheVariables": { "ENABLE_SANITIZERS": true } },
+    { "name": "msvc-sanitizers", "inherits": "msvc-debug", "cacheVariables": { "ENABLE_SANITIZERS": true } }
+  ],
+  "buildPresets": [
+    { "name": "gcc-debug", "configurePreset": "gcc-debug" },
+    { "name": "gcc-release", "configurePreset": "gcc-release" },
+    { "name": "clang-debug", "configurePreset": "clang-debug" },
+    { "name": "clang-release", "configurePreset": "clang-release" },
+    { "name": "appleclang-debug", "configurePreset": "appleclang-debug" },
+    { "name": "appleclang-release", "configurePreset": "appleclang-release" },
+    { "name": "msvc-debug", "configurePreset": "msvc-debug" },
+    { "name": "msvc-release", "configurePreset": "msvc-release" },
+    { "name": "gcc-sanitizers", "configurePreset": "gcc-sanitizers" },
+    { "name": "clang-sanitizers", "configurePreset": "clang-sanitizers" },
+    { "name": "appleclang-sanitizers", "configurePreset": "appleclang-sanitizers" },
+    { "name": "msvc-sanitizers", "configurePreset": "msvc-sanitizers" }
+  ],
+  "testPresets": [
+    {
+      "name": "base", "hidden": true,
+      "output": { "outputOnFailure": true },
+      "execution": { "noTestsAction": "error", "stopOnFailure": true }
+    },
+    { "name": "gcc-debug", "inherits": "base", "configurePreset": "gcc-debug" },
+    { "name": "gcc-release", "inherits": "base", "configurePreset": "gcc-release" },
+    { "name": "clang-debug", "inherits": "base", "configurePreset": "clang-debug" },
+    { "name": "clang-release", "inherits": "base", "configurePreset": "clang-release" },
+    { "name": "appleclang-debug", "inherits": "base", "configurePreset": "appleclang-debug" },
+    { "name": "appleclang-release", "inherits": "base", "configurePreset": "appleclang-release" },
+    { "name": "msvc-debug", "inherits": "base", "configurePreset": "msvc-debug" },
+    { "name": "msvc-release", "inherits": "base", "configurePreset": "msvc-release" },
+    { "name": "gcc-sanitizers", "inherits": "base", "configurePreset": "gcc-sanitizers" },
+    { "name": "clang-sanitizers", "inherits": "base", "configurePreset": "clang-sanitizers" },
+    { "name": "appleclang-sanitizers", "inherits": "base", "configurePreset": "appleclang-sanitizers" },
+    { "name": "msvc-sanitizers", "inherits": "base", "configurePreset": "msvc-sanitizers" }
+  ]
+}

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:

cmake/compilerwarnings.cmake

@@ -4,7 +4,7 @@ function( target_enable_warnings _target )
     if(MSVC)
         target_compile_options(
             ${_target} 
-            PUBLIC
+            PRIVATE
             /W4 # Baseline reasonable warnings
             /w14242 # 'identifier': conversion from 'type1' to 'type1', possible loss of data
             /w14254 # 'operator': conversion from 'type1:field_bits' to 'type2:field_bits', possible loss of data
@@ -12,7 +12,7 @@ function( target_enable_warnings _target )
             /w14265 # 'classname': class has virtual functions, but destructor is not virtual instances of this class may not
                     # be destructed correctly
             /w14287 # 'operator': unsigned/negative constant mismatch
-            /we4289 # nonstandard extension used: 'variable': loop control variable declared in the for-loop is used outside
+            /w14289 # nonstandard extension used: 'variable': loop control variable declared in the for-loop is used outside
                     # the for-loop scope
             /w14296 # 'operator': expression is always 'boolean_value'
             /w14311 # 'variable': pointer truncation from 'type1' to 'type2'
@@ -29,10 +29,8 @@ function( target_enable_warnings _target )
             /w14928 # illegal copy-initialization; more than one user-defined conversion has been implicitly applied
             /permissive- # standards conformance mode for MSVC compiler.
         )
-    elseif(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
+    elseif(CMAKE_CXX_COMPILER_ID MATCHES "^(GNU|Clang|AppleClang)$")
-        target_compile_options(
+        set(_warnings
-            ${_target} 
-            INTERFACE
             -Wall
             -Wextra # reasonable and standard
             -Wextra-semi # Warn about semicolon after in-class function definition.
@@ -52,55 +50,21 @@ function( target_enable_warnings _target )
             -Wformat=2 # warn on security issues around functions that format output (ie printf)
             -Wimplicit-fallthrough # warn on statements that fallthrough without an explicit annotation
         )
-    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+        if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-        target_compile_options(
+            list(APPEND _warnings
-            ${_target} 
+                -Wmisleading-indentation # warn if indentation implies blocks where blocks do not exist
-            INTERFACE
+                -Wduplicated-cond # warn if if / else chain has duplicated conditions
-            -Wall
+                -Wduplicated-branches # warn if if / else branches have duplicated code
-            -Wextra # reasonable and standard
+                -Wlogical-op # warn about logical operations being used where bitwise were probably wanted
-            -Wextra-semi # Warn about semicolon after in-class function definition.
+                -Wuseless-cast # warn if you perform a cast to the same type
-            -Wshadow # warn the user if a variable declaration shadows one from a parent context
+            )
-            -Wnon-virtual-dtor # warn the user if a class with virtual functions has a non-virtual destructor. This helps
+        endif()
-
+        target_compile_options(${_target} PRIVATE ${_warnings})
-            # catch hard to track down memory errors
+    else()
-            -Wold-style-cast # warn for c-style casts
+        message(AUTHOR_WARNING "No warning profile for ${CMAKE_CXX_COMPILER_ID}")
-            -Wcast-align # warn for potential performance problem casts
-            -Wunused # warn on anything being unused
-            -Woverloaded-virtual # warn if you overload (not override) a virtual function
-            -Wpedantic # warn if non-standard C++ is used
-            -Wconversion # warn on type conversions that may lose data
-            -Wsign-conversion # warn on sign conversions
-            -Wnull-dereference # warn if a null dereference is detected
-            -Wdouble-promotion # warn if float is implicit promoted to double
-            -Wformat=2 # warn on security issues around functions that format output (ie printf)
-            -Wimplicit-fallthrough # warn on statements that fallthrough without an explicit annotation
-            -Wmisleading-indentation # warn if indentation implies blocks where blocks do not exist
-            -Wduplicated-cond # warn if if / else chain has duplicated conditions
-            -Wduplicated-branches # warn if if / else branches have duplicated code
-            -Wlogical-op # warn about logical operations being used where bitwise were probably wanted
-            -Wuseless-cast # warn if you perform a cast to the same type
-        )
     endif()
 endfunction()
 
 function(target_warnings_as_errors _target)
-    if(MSVC)
+    set_property(TARGET ${_target} PROPERTY COMPILE_WARNING_AS_ERROR ON)
-        target_compile_options(
+endfunction()
-            ${_target}
-            PUBLIC
-            /WX
-        )
-    elseif(CMAKE_CXX_COMPILER_ID MATCHES ".*Clang")
-        target_compile_options(
-            ${_target}
-            PUBLIC
-            -Werror
-        )
-    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-        target_compile_options(
-            ${_target}
-            PUBLIC
-            -Werror
-        )
-    endif()
-endfunction()

cmake/cpm.cmake

@@ -1,33 +0,0 @@
-set(CPM_DOWNLOAD_VERSION 0.38.1)
-
-if(CPM_SOURCE_CACHE)
-  set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
-elseif(DEFINED ENV{CPM_SOURCE_CACHE})
-  set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
-else()
-  set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake")
-endif()
-
-# Expand relative path. This is important if the provided path contains a tilde (~)
-get_filename_component(CPM_DOWNLOAD_LOCATION ${CPM_DOWNLOAD_LOCATION} ABSOLUTE)
-
-function(download_cpm)
-  message(STATUS "Downloading CPM.cmake to ${CPM_DOWNLOAD_LOCATION}")
-  file(DOWNLOAD
-       https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake
-       ${CPM_DOWNLOAD_LOCATION}
-  )
-endfunction()
-
-if(NOT (EXISTS ${CPM_DOWNLOAD_LOCATION}))
-  download_cpm()
-else()
-  # resume download if it previously failed
-  file(READ ${CPM_DOWNLOAD_LOCATION} check)
-  if("${check}" STREQUAL "")
-    download_cpm()
-  endif()
-  unset(check)
-endif()
-
-include(${CPM_DOWNLOAD_LOCATION})

cmake/gtest.cmake

@@ -1,17 +1,20 @@
 include_guard()
 
-CPMAddPackage(
+include(FetchContent)
-	NAME googletest
+
-	GITHUB_REPOSITORY google/googletest
+set(INSTALL_GTEST OFF CACHE BOOL "Install GoogleTest" FORCE)
-	GIT_TAG v1.13.0
+set(gtest_force_shared_crt ON CACHE BOOL "Use the shared MSVC runtime for GoogleTest" FORCE)
-	VERSION 1.13.0
+
-	OPTIONS
+FetchContent_Declare(
-	"INSTALL_GTEST OFF"
+	googletest
-	"gtest_force_shared_crt ON"
+	GIT_REPOSITORY https://github.com/google/googletest.git
+	GIT_TAG v1.18.0
+	GIT_SHALLOW TRUE
 )
+FetchContent_MakeAvailable(googletest)
 set_property(TARGET 
 	gtest 
 	gtest_main 
 	gmock
 	gmock_main
-	PROPERTY FOLDER third_party/GoogleTest)
+	PROPERTY FOLDER third_party/GoogleTest)

cmake/sanitizers.cmake

@@ -1,20 +1,34 @@
 include_guard()
 
-function( target_enable_sanitizers _target )
+include(CheckCXXSourceCompiles)
-    if( MSVC )
+include(CMakePushCheckState)
-        string(FIND "$ENV{PATH}" "$ENV{VSINSTALLDIR}" index_of_vs_install_dir)
 
-        if("${index_of_vs_install_dir}" STREQUAL "-1")
+function(target_enable_sanitizers _target)
-            message(
+    if(MSVC)
-                SEND_ERROR
+        set(_compile_options /fsanitize=address)
-                "Using MSVC sanitizers requires setting the MSVC environment before building the project. Please manually open the MSVC command prompt and rebuild the project."
+        set(_link_options /INCREMENTAL:NO)
-            )
+        # Use the same settings for this target and the capability check.
-        endif()
+        set_property(TARGET ${_target} PROPERTY MSVC_RUNTIME_CHECKS "")
-
+        set_property(TARGET ${_target} PROPERTY MSVC_DEBUG_INFORMATION_FORMAT ProgramDatabase)
-        target_compile_options(${_target} PUBLIC /fsanitize=address /Zi /INCREMENTAL:NO)
+        set(CMAKE_MSVC_RUNTIME_CHECKS "")
-        target_link_options(${_target} PUBLIC /INCREMENTAL:NO)
+        set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT ProgramDatabase)
+    elseif(CMAKE_CXX_COMPILER_ID MATCHES "^(GNU|Clang|AppleClang)$")
+        set(_compile_options -fsanitize=address,undefined -fno-sanitize-recover=undefined -fno-omit-frame-pointer)
+        set(_link_options -fsanitize=address,undefined)
     else()
-        target_compile_options(${_target} INTERFACE -fsanitize=address,leak,undefined)
+        message(FATAL_ERROR "Sanitizers are not configured for ${CMAKE_CXX_COMPILER_ID}")
-        target_link_options(${_target} INTERFACE -fsanitize=address,leak,undefined)
     endif()
-endfunction()
+
+    cmake_push_check_state(RESET)
+    string(JOIN " " CMAKE_REQUIRED_FLAGS ${_compile_options})
+    set(CMAKE_REQUIRED_LINK_OPTIONS ${_link_options})
+    set(CMAKE_TRY_COMPILE_TARGET_TYPE EXECUTABLE)
+    check_cxx_source_compiles("int main() { return 0; }" REPO_LENS_SANITIZERS_SUPPORTED)
+    cmake_pop_check_state()
+    if(NOT REPO_LENS_SANITIZERS_SUPPORTED)
+        message(FATAL_ERROR "The requested sanitizer configuration cannot compile and link. Check compiler/runtime installation or configure with ENABLE_SANITIZERS=OFF.")
+    endif()
+
+    target_compile_options(${_target} PRIVATE ${_compile_options})
+    target_link_options(${_target} PRIVATE ${_link_options})
+endfunction()

cmake/toolchains/appleclang.cmake

@@ -0,0 +1,4 @@
+# Apple's compiler wrappers use the active Xcode/Command Line Tools installation.
+include_guard(GLOBAL)
+set(CMAKE_C_COMPILER /usr/bin/clang CACHE FILEPATH "C compiler")
+set(CMAKE_CXX_COMPILER /usr/bin/clang++ CACHE FILEPATH "C++ compiler")

cmake/toolchains/clang.cmake

@@ -0,0 +1,4 @@
+# Native LLVM Clang builds; compiler executables must be on PATH.
+include_guard(GLOBAL)
+set(CMAKE_C_COMPILER clang CACHE FILEPATH "C compiler")
+set(CMAKE_CXX_COMPILER clang++ CACHE FILEPATH "C++ compiler")

cmake/toolchains/gcc.cmake

@@ -0,0 +1,4 @@
+# Native GCC builds; compiler executables must be on PATH.
+include_guard(GLOBAL)
+set(CMAKE_C_COMPILER gcc CACHE FILEPATH "C compiler")
+set(CMAKE_CXX_COMPILER g++ CACHE FILEPATH "C++ compiler")

cmake/toolchains/msvc.cmake

@@ -0,0 +1,4 @@
+# Run Ninja builds in a Visual Studio developer environment.
+include_guard(GLOBAL)
+set(CMAKE_C_COMPILER cl CACHE FILEPATH "C compiler")
+set(CMAKE_CXX_COMPILER cl CACHE FILEPATH "C++ compiler")

docs/PROJECTMAP.md

@@ -0,0 +1,69 @@
+# Project map
+
+This is a routing table: **where should an agent look?** It is not an architecture manual. Start here, then inspect only the source or documentation relevant to the task.
+
+The repository contains a C++ CLI skeleton, native compiler presets, and a sample test. Navigation implementations remain TODOs. The bookmarks below route to existing build invariants, not implemented navigation features.
+
+## Current routes
+
+### Purpose and direction
+Path: `README.md`
+Entry: project purpose, scope, illustrative CLI, and measurement goals.
+Related: `AGENTS.md` for agent operating instructions.
+
+### CLI parsing and dispatch skeleton
+Path: `src/main.cpp`
+Entry: `main`
+Important symbols: `print_usage`, `extract_tool_name`, `extract_tool_arguments`
+Flow: placeholder parsing -> `find`/`map` dispatch -> tool `execute`; parsing and usage remain TODOs.
+Related: `src/CMakeLists.txt` lists all executable sources. `around` has a stub but is not dispatched yet.
+
+### Tool interface and implementations
+Path: `include/repo_tool_*.hpp`, `src/repo_tool_*.cpp`
+Entry: `include/repo_tool_interface.hpp`
+Important symbols: `rl::IRepoLensTool`, `rl::exit_code`, `rl::RepoLensToolFind`, `rl::RepoLensToolMap`, `rl::RepoLensToolAround`
+Related: `AGENTS.md` for trailing return types and the `[[nodiscard]]`/`noexcept` execution contract. Tool bodies remain TODOs.
+Tests: no navigation behavior tests yet.
+
+### Native build and compiler settings
+Path: `CMakeLists.txt`, `CMakePresets.json`, `cmake/`, `src/CMakeLists.txt`
+Entry: `CMakePresets.json` for matching configure/build/test presets; `cmake/toolchains/` for GCC, Clang, AppleClang, and MSVC selection.
+Important symbols: `target_enable_warnings`, `target_warnings_as_errors`, `target_enable_sanitizers`
+Related: `cmake/compilerwarnings.cmake` for diagnostics; `cmake/sanitizers.cmake` for capability checks and target settings; `cmake/staticanalysis.cmake` is an inherited Visual Studio generator helper.
+Bookmarks: `OPTIONAL_TEST_DEPENDENCY_BOUNDARY` in root `CMakeLists.txt` separates the offline application build from test dependencies.
+Ignore normally: generated `build/` and `.build/` trees; build helpers unless the task concerns tooling. Use the selected build's `compile_commands.json` when compilation context is needed.
+
+### Test dependencies and validation
+Path: `test/`, `cmake/gtest.cmake`
+Entry: `test/CMakeLists.txt`; `test/test_main.cpp` is only a sample assertion.
+Flow: `ENABLE_TESTS` -> FetchContent GoogleTest -> `repo-lens-test` -> CTest discovery.
+Bookmarks: `MSVC_SANITIZER_ANNOTATION_ALIGNMENT` in `test/CMakeLists.txt` keeps STL annotations consistent across the instrumented test and its dependencies.
+Related: `<compiler>-sanitizers` presets; `README.md` for local dependency overrides and build instructions.
+
+### CI and formatting
+Path: `.github/workflows/`, `.clang-format`, `.clang-tidy`
+Entry: `.github/workflows/ci.yml` configures/builds/tests Debug, Release, and sanitizer presets on native hosts.
+Related: `.github/workflows/auto-clang-format.yml` is inherited formatting automation; `.clang-tidy` is configuration, not evidence that analysis runs with Ninja.
+Ignore normally: workflows unless the task concerns validation or automation.
+
+## Maintaining the map
+
+Update routes when actual source structure or useful entry points materially change. Add only existing areas; do not predeclare hypothetical subsystems. Keep entries short and omit fields that add no routing value.
+
+Suggested entry shape (fields are optional):
+
+```text
+Subsystem
+Path:
+Entry:
+Important symbols:
+Flow:
+Tests:
+Bookmarks:
+Related:
+Ignore normally:
+```
+
+Use `Flow` for a short sequence of entry points, not an implementation explanation. List bookmarks only for stable semantic or architectural locations where ordinary searchable symbols are insufficient.
+
+Locate bookmark declarations cheaply with `rg -n '@ai-bookmark' CMakeLists.txt test cmake src include`, then inspect a bounded range around the relevant marker. repo-lens bookmark commands are not implemented yet. Prefer symbols for ordinary functions and classes.

include/repo_tool_around.hpp

@@ -0,0 +1,17 @@
+#ifndef REPO_LENSE_TOOL_AROUND_HPP_INCLUDED
+#define REPO_LENSE_TOOL_AROUND_HPP_INCLUDED
+
+#pragma once
+
+#include "repo_tool_interface.hpp"
+
+namespace rl
+{
+class RepoLensToolAround final : public IRepoLensTool
+{
+public:
+    [[nodiscard]] auto execute(std::string_view args) noexcept -> exit_code override;
+};
+}
+
+#endif //REPO_LENSE_TOOL_AROUND_HPP_INCLUDED

include/repo_tool_find.hpp

@@ -0,0 +1,17 @@
+#ifndef REPO_LENSE_TOOL_FIND_HPP_INCLUDED
+#define REPO_LENSE_TOOL_FIND_HPP_INCLUDED
+
+#pragma once
+
+#include "repo_tool_interface.hpp"
+
+namespace rl
+{
+class RepoLensToolFind final : public IRepoLensTool
+{
+public:
+    [[nodiscard]] auto execute(std::string_view args) noexcept -> exit_code override;
+};
+}
+
+#endif //REPO_LENSE_TOOL_FIND_HPP_INCLUDED

include/repo_tool_interface.hpp

@@ -0,0 +1,29 @@
+#ifndef REPO_LENSE_TOOL_INTERFACE_HPP_INCLUDED
+#define REPO_LENSE_TOOL_INTERFACE_HPP_INCLUDED
+
+#include <cstdint>
+#include <string_view>
+
+#pragma once
+
+namespace rl
+{
+
+using exit_code = std::int32_t;
+
+class IRepoLensTool
+{
+public: 
+    IRepoLensTool() noexcept = default;
+    virtual ~IRepoLensTool() noexcept = default;
+    IRepoLensTool(const IRepoLensTool&) noexcept = delete;
+    IRepoLensTool(IRepoLensTool&&) noexcept = delete;
+    auto operator=(const IRepoLensTool&) noexcept -> IRepoLensTool& = delete;
+    auto operator=(IRepoLensTool&&) noexcept -> IRepoLensTool& = delete;
+
+    [[nodiscard]] virtual auto execute(std::string_view arguments) noexcept -> exit_code = 0;
+};
+
+}
+
+#endif //REPO_LENSE_TOOL_INTERFACE_HPP_INCLUDED

include/repo_tool_map.hpp

@@ -0,0 +1,17 @@
+#ifndef REPO_LENSE_TOOL_MAP_HPP_INCLUDED
+#define REPO_LENSE_TOOL_MAP_HPP_INCLUDED
+
+#pragma once
+
+#include "repo_tool_interface.hpp"
+
+namespace rl
+{
+class RepoLensToolMap final : public IRepoLensTool
+{
+public:
+    [[nodiscard]] auto execute(std::string_view args) noexcept -> exit_code override;
+};
+}
+
+#endif //REPO_LENSE_TOOL_MAP_HPP_INCLUDED

src/CMakeLists.txt

@@ -1,13 +1,14 @@
-set(current_target blank_slate)
+set(current_target repo)
 
 add_executable(
     ${current_target} 
     main.cpp
+    repo_tool_around.cpp
+    repo_tool_find.cpp
+    repo_tool_map.cpp
 )
 
-CPMAddPackage("gh:fmtlib/fmt#10.0.0")
+target_include_directories(${current_target} PRIVATE "${PROJECT_SOURCE_DIR}/include")
-target_link_libraries(${current_target} PRIVATE fmt::fmt)
-set_property(TARGET fmt PROPERTY FOLDER third_party/fmt)
 
 if( ENABLE_ALL_REASONABLE_WARNINGS )
     MESSAGE("-- Additional Warnings Enabled")

src/main.cpp

@@ -1,7 +1,50 @@
-#include <fmt/core.h>
+#include <cinttypes>
-
+#include <string_view>
-auto main() -> int
+#include <vector>
+
+#include "repo_tool_find.hpp"
+#include "repo_tool_map.hpp"
+
+namespace
 {
-    fmt::print("Hello, World!");
+	auto print_usage() noexcept -> int32_t
-}
+	{
+		//@AGENT TODO: print to stdout the usage parameters
+		return -1;
+	}
 
+	auto extract_tool_name([[maybe_unused]] std::string_view cmdline) noexcept -> std::string_view
+	{
+		//@AGENT TODO: cmdline should be the entire contents of argv, extract the tool name and return it.
+		return {};
+	}
+
+	auto extract_tool_arguments([[maybe_unused]] std::string_view cmdline) noexcept -> std::vector<std::string_view>
+	{
+		//@AGENT TODO: cmdline should be the entire contents of argv, extract the tool arguments and return them
+		return {};
+	}
+}
+
+auto main(int argc, char* argv[]) noexcept -> int
+{
+    if (argc < 2)
+    {
+        return print_usage();
+    }
+
+    const std::string_view tool_name = extract_tool_name(argv[1]);
+    const std::string_view tool_args = extract_tool_name(argv[1]);
+
+    if( tool_name == "find" )
+    {
+        rl::RepoLensToolFind tool;
+        return tool.execute(tool_args);
+    }
+
+    else if (tool_name == "map")
+    {
+		rl::RepoLensToolMap tool;
+		return tool.execute(tool_args);
+    }
+}

src/repo_tool_around.cpp

@@ -0,0 +1,10 @@
+#include "repo_tool_around.hpp"
+
+namespace rl
+{
+    auto RepoLensToolAround::execute([[maybe_unused]] std::string_view args) noexcept -> exit_code
+    {
+        //@AGENT_TODO: Around tool implementation goes here
+        return 0;
+    }
+}

src/repo_tool_find.cpp

@@ -0,0 +1,13 @@
+#include "repo_tool_find.hpp"
+
+#include <iostream>
+
+namespace rl
+{
+    auto RepoLensToolFind::execute([[maybe_unused]] std::string_view args) noexcept -> exit_code
+    {
+        //@AGENT_TODO: find tool implementation goes here
+        std::cout << "Repo Lense Find Tool Executed\n";
+        return 0;
+    }
+}

src/repo_tool_map.cpp

@@ -0,0 +1,10 @@
+#include "repo_tool_map.hpp"
+
+namespace rl
+{
+    auto RepoLensToolMap::execute([[maybe_unused]] std::string_view args) noexcept -> exit_code
+    {
+        //@AGENT_TODO: Map tool implementation goes here
+        return 0;
+    }
+}

test/CMakeLists.txt

@@ -1,14 +1,31 @@
 include(gtest)
 
 add_executable(
-  blank-slate-test
+  repo-lens-test
   test_main.cpp
 )
 
 target_link_libraries(
-  blank-slate-test
+  repo-lens-test
   gtest_main
 )
 
+if(ENABLE_ALL_REASONABLE_WARNINGS)
+  target_enable_warnings(repo-lens-test)
+endif()
+if(ENABLE_WARNINGS_AS_ERRORS)
+  target_warnings_as_errors(repo-lens-test)
+endif()
+if(ENABLE_SANITIZERS)
+  target_enable_sanitizers(repo-lens-test)
+  if(MSVC)
+    # @ai-bookmark MSVC_SANITIZER_ANNOTATION_ALIGNMENT
+    # MSVC STL sanitizer annotations must agree across linked translation units.
+    foreach(_test_dependency IN ITEMS gtest gtest_main gmock gmock_main)
+      target_enable_sanitizers(${_test_dependency})
+    endforeach()
+  endif()
+endif()
+
 include(GoogleTest)
-gtest_discover_tests(blank-slate-test)
+gtest_discover_tests(repo-lens-test)