From 32227d244fb4a917e8057d3faa114912d945800b Mon Sep 17 00:00:00 2001
From: mgradwohl <mattgr@msn.com>
Date: Wed, 19 Aug 2026 16:14:40 -0700
Subject: [PATCH 1/2] docs: refresh project documentation

Align the Markdown documentation with the current C++ template, consolidate duplicated guidance, and clarify the policy for future public API documentation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .github/copilot-instructions.md  | 302 +++----------------
 .github/pull_request_template.md |   2 +-
 CONTRIBUTING.md                  | 129 ++++----
 README.md                        | 502 +++++++------------------------
 SECURITY.md                      |  46 +--
 TODO.md                          | 122 ++------
 6 files changed, 250 insertions(+), 853 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 425ac27..1bbbd7d 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,279 +1,65 @@
-# MyProject - Copilot Instructions
+# Copilot Instructions
 
-This file provides guidance for GitHub Copilot coding agents working on this project.
+## Project Context
 
-## Project Overview
+MyProject is a cross-platform C++23 application template. Clang 22, lld, CMake Presets, and Ninja are the primary toolchain. Linux and Windows are supported; Google Test and spdlog are fetched by CMake.
 
-MyProject is a cross-platform C++23 application built with modern tooling. The project emphasizes:
-- Modern C++23 with clang as the primary toolchain
-- Clean architecture with proper separation of concerns
-- Cross-platform support (Linux, Windows)
+Read [README.md](../README.md) for the current feature and command reference and [CONTRIBUTING.md](../CONTRIBUTING.md) for coding conventions. Do not duplicate those documents here.
 
-## Development Environment
+## Working Practices
 
-### Required Tools
-- **Compiler:** Clang 22+ with lld linker
-- **Build System:** CMake 3.28+ with Ninja and CMake Presets
-- **Compiler Cache:** ccache 4.9.1+ (required for faster rebuilds)
-- **Static Analysis:** clang-tidy (included with LLVM)
-- **Code Formatting:** clang-format (included with LLVM)
-- **Coverage:** llvm-profdata, llvm-cov (included with LLVM)
-- **Testing:** Google Test (via CMake FetchContent)
-- **Logging:** spdlog (via CMake FetchContent)
+- Make focused changes that preserve Linux and Windows behavior.
+- Use CMake Presets as the supported build interface.
+- Add application files to `MYPROJECT_SOURCES` or `MYPROJECT_HEADERS` in `CMakeLists.txt`.
+- Add test files to the `MyProject_tests` target in `tests/CMakeLists.txt`.
+- Declare source dependencies with CMake `FetchContent` and `SYSTEM`, pin a version tag, and link them explicitly.
+- Keep warnings scoped to project targets through `myproject_apply_default_warnings()`.
+- Update README documentation when changing presets, CMake options, scripts, dependencies, CI, generated paths, or project structure.
+- Keep `TODO.md` limited to unimplemented work.
+- Update Linux and PowerShell tooling together when their behavior is intended to match.
 
-### Build Commands
+## Validation
+
+Use the smallest relevant checks, normally:
 
-Configure and build (Linux):
 ```bash
 cmake --preset debug
 cmake --build --preset debug
+ctest --preset debug
+./tools/check-format.sh
+./tools/clang-tidy.sh debug
 ```
 
-Configure and build (Windows):
-```powershell
-cmake --preset win-debug
-cmake --build --preset win-debug
-```
-
-Run tests:
-```bash
-ctest --preset debug        # Linux
-ctest --preset win-debug    # Windows
-```
-
-List available presets:
-```bash
-cmake --list-presets
-```
-
-### VS Code Tasks
-The project includes predefined tasks in `.vscode/tasks.json` that auto-detect platform:
-- **CMake: Build Debug** - Build with debug symbols (default, Ctrl+Shift+B)
-- **CMake: Build RelWithDebInfo** - Build with optimizations + debug info
-- **CMake: Build Release** - Build optimized release version
-- **CMake: Build Optimized** - Build with LTO, march=x86-64-v3, stripped
-- **CMake: Build ASan+UBSan (Linux)** - Build with AddressSanitizer + UBSan
-- **CMake: Build TSan (Linux)** - Build with ThreadSanitizer
-- **CMake: Test Debug** - Execute test suite
-- **Clang-Tidy** - Run static analysis
-- **Clang-Format** - Format all source files
-- **Check Format** - Check formatting compliance
-- **CPack: Create Package** - Create distributable ZIP package
-- **Coverage: Generate Report** - Generate HTML code coverage report
-- **Check Prerequisites** - Verify all required tools are installed with correct versions
-
-## Coding Standards
-
-### Language and Style
-- **C++ Standard:** C++23 (required)
-- **Compiler:** Primarily validated with clang
-- **Formatting:** Use `.clang-format` (LLVM base, Allman braces)
-  - Run `./tools/clang-format.sh` before commits
-- **Static Analysis:** Use `.clang-tidy` configuration
-  - Run `./tools/clang-tidy.sh` regularly
-  - Note: PCH flags are automatically stripped from compile_commands.json for clang-tidy compatibility
-
-### Compiler Warnings
-The project applies comprehensive warnings tuned for Clang on Windows and Linux:
-
-- **Baseline (all platforms):** `-Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wshadow -Wnon-virtual-dtor -Woverloaded-virtual -Wformat=2 -Wimplicit-fallthrough -Wnull-dereference -Wdouble-promotion -Wcast-align -Wundef -Werror=return-type`
-- **Linux/macOS:** Adds `-Wmisleading-indentation`
-- **Windows:** Adds `-Wno-unknown-pragmas -Wno-nonportable-system-include-path` (suppresses MSVC STL/SDK noise)
-- **Warnings-as-errors:** Controlled by `MYPROJECT_WARNINGS_AS_ERRORS` (default ON)
-
-Warnings are applied per-target via `myproject_apply_default_warnings()` — they do NOT affect third-party dependencies.
-
-### IDE Configuration (clangd)
-The `.clangd` file configures clangd for IDE integration:
-- Adds project-specific flags and system header prefixes
-- **Removes PCH flags** (`-Xclang`, `-include-pch`, `-emit-pch`, etc.) that clangd cannot handle
-- This does NOT disable PCH in builds - only tells clangd to ignore those flags
-
-### Include Order
-
-1. Matching header (`.cpp` files only)
-2. Project headers (`src/`, `include/`, `tests/`), alphabetical
-3. Third-party libraries (spdlog, gtest, boost), alphabetical
-4. C++ standard library headers, alphabetical
-5. Other (fallback)
-
-Separate each group with a blank line. Use `#pragma once` in all headers.
-
-**Example:**
-```cpp
-#include "MyClass.h"
-
-#include "src/utils/Helper.h"
-
-#include <spdlog/spdlog.h>
-
-#include <memory>
-#include <string>
-```
-
-### Naming Conventions
-- **Classes/Types:** PascalCase (e.g., `DataProcessor`, `FileHandler`)
-- **Functions/Methods:** camelCase (e.g., `processData`, `handleFile`)
-- **Member Variables:** camelCase with `m_` prefix for private members (e.g., `m_data`)
-- **Constants:** UPPER_SNAKE_CASE (e.g., `MAX_BUFFER_SIZE`)
-
-### Preprocessor Directives
-- Use `#ifdef X` instead of `#if defined(X)` for simple checks
-- Use `#ifndef X` instead of `#if !defined(X)`
-- Compound conditions like `#if defined(X) && !defined(Y)` stay as-is
-
-## Project Structure
-
-```
-Devshell-Updated.ps1  # Windows dev environment setup (in project root)
-
-src/
-├── main.cpp          # Application entry point
-└── version.h.in      # Version header template (CMake generates version.h)
-
-tests/
-├── CMakeLists.txt    # Test configuration
-└── test_main.cpp     # Test cases
-
-tools/
-├── build.sh/ps1        # Build helper scripts
-├── configure.sh/ps1    # Configure helper scripts
-├── check-prereqs.sh/ps1  # Check prerequisite tools and versions
-├── clang-tidy.sh/ps1   # Static analysis
-├── clang-format.sh/ps1 # Code formatting
-├── check-format.sh/ps1 # Format checking
-└── coverage.sh/ps1     # Code coverage reports
-
-.github/
-├── workflows/ci.yml    # CI/CD pipeline
-├── ISSUE_TEMPLATE/     # Bug report and feature request templates
-├── pull_request_template.md  # PR checklist
-└── dependabot.yml      # Automated dependency updates
-
-dist/                   # CPack output (gitignored)
-coverage/               # Coverage reports (gitignored)
-```
-## Engineering Workflow
-- When making changes to the project structure, scripts (.sh or .ps1), clang files (.clang-format, .clang-tidy, .clangd), or CMake files, update README.md accordingly and copilot-instructions.md if needed and ensure setup scripts and workflow.yml files reflect changes.
-- if new folders are created under the project root, make sure to make a smart choice to .gitignore them if needed and exclude them from clangd, clang-format and clang-tidy configurations.
-- When adding a new component or depency ensure to use CMake FetchContent where possible and document the addition in README.md, and update setup scripts, project scripts, readmes, workflow.yml files as needed, and copilot-instructions.md if needed. Also update clangd, clang-format and clang-tidy configurations to exclude the new dependency if needed. 
-- If FetchContent downloads need to be reused across presets, enable the shared cache via `MYPROJECT_ENABLE_FETCHCONTENT_CACHE=ON` (optional). The default cache location is `.cache/fetchcontent` beside the source root (gitignored). Respect a user-specified `MYPROJECT_FETCHCONTENT_CACHE_DIR` or the standard `FETCHCONTENT_BASE_DIR` environment variable when provided.
-
-## Testing
-
-### Test Framework
-- Use **Google Test (gtest)** for all tests
-- Tests live in `tests/` directory
-- Run via `ctest --preset debug`
-
-### Code Coverage
-- Run `./tools/coverage.sh` to generate HTML coverage report
-- Report generated at `coverage/index.html`
-- Uses llvm-cov with Clang instrumentation
-
-### Example Test Structure
-```cpp
-#include <gtest/gtest.h>
-
-#include "src/MyClass.h"
-
-TEST(MyClassTest, BasicFunctionality)
-{
-    MyClass obj;
-    EXPECT_EQ(obj.getValue(), 42);
-}
-```
-
-## Common Tasks
-
-### Adding a New Feature
-1. Create/modify source files in `src/`
-2. Update `MYPROJECT_SOURCES` in CMakeLists.txt if adding files
-3. Add tests in `tests/`
-4. Run clang-format
-5. Run clang-tidy
-6. Build and test
-
-### Adding Dependencies
-- Use CMake `FetchContent` for header-only libraries (see spdlog example in CMakeLists.txt)
-- **Always use `SYSTEM` keyword** in `FetchContent_Declare` to suppress warnings from third-party code
-- Update CMakeLists.txt and document in README.md
-
-**Example:**
-```cmake
-FetchContent_Declare(
-    mylib
-    GIT_REPOSITORY https://github.com/example/mylib.git
-    GIT_TAG v1.0.0
-    SYSTEM  # Treat as system headers to suppress warnings
-)
-FetchContent_MakeAvailable(mylib)
-```
-
-## Best Practices
-
-### Code Quality
-- **Minimal changes:** Make the smallest possible changes to achieve the goal
-- **DRY principle:** Don't repeat yourself; extract common code
-- **RAII:** Use smart pointers and RAII for resource management
-- **Const correctness:** Mark methods and variables `const` when appropriate
-- **Error handling:** Check return values, use exceptions sparingly
-
-### Performance
-- Avoid unnecessary copies (use const references, move semantics)
-- Profile before optimizing
-
-### Documentation
-- Use clear, descriptive names that minimize need for comments
-- Add comments only when code intent is not obvious
-- Keep README.md up to date
-
-### Git Workflow
-- Write clear commit messages
-- Keep commits focused and atomic
-- Ensure code builds and tests pass before committing
-- Post commit monitor the CI results for issues and address any problems promptly
+Use sanitizer or coverage presets when the changed behavior warrants them. PowerShell equivalents exist for repository scripts.
 
-## Common Pitfalls to Avoid
+## C++ Style
 
-- Don't use `using namespace std` in headers
-- Don't ignore clang-tidy warnings
-- Don't skip running tests before committing
-- Don't add unnecessary dependencies
-- Don't commit without running clang-format
+- Target C++23 and use the checked-in clang-format and clang-tidy configurations.
+- Follow the naming and include-order rules in `CONTRIBUTING.md`.
+- Prefer RAII, const-correctness, standard-library facilities, and explicit error handling.
+- Use `#pragma once` in headers.
+- Use `#ifdef X` or `#ifndef X` for simple preprocessor checks.
+- Do not weaken project warnings or add suppressions for third-party code when a `SYSTEM` boundary is appropriate.
 
-## Design Decisions
+## Documentation Style
 
-This section documents intentional design choices and rejected alternatives.
+This repository currently builds an application and has no exported library API. Prioritize accurate Markdown over generated API documentation. Do not add JSDoc, docstrings, or routine inline comments. If public C++ headers are added later, use concise Doxygen-compatible comments for public contracts that cannot be expressed clearly through names and types.
 
-### What We Use
-- **CMake Presets** as the single source of truth for build configurations (not toolchain files)
-- **FetchContent** for dependencies (not CPM.cmake - adds complexity without benefit for this template)
-- **Platform default C++ standard libraries** (libstdc++ on Linux, MSVC STL on Windows - not libc++)
-- **Individual CMake options** for features (not an umbrella "Developer Mode" switch)
-- **clangd** for IDE integration (cpptools disabled to avoid conflicts)
+Keep Markdown responsibilities distinct:
 
-### Disabled Clang-Tidy Checks
-These checks are disabled in `.clang-tidy` due to false positives or excessive noise:
-- `bugprone-exception-escape` - traces through spdlog/STL exception paths, creates wall of noise
-- `misc-include-cleaner` - doesn't work correctly with Windows headers (`<windows.h>`, `<cstdio>`)
-- `bugprone-easily-swappable-parameters` - too opinionated for general use
-- `modernize-use-trailing-return-type` - style preference, not a bug
-- `readability-identifier-naming` - conflicts with different naming conventions
-- `readability-identifier-length` - too restrictive
-- `readability-magic-numbers` - too noisy for a template
-- `readability-implicit-bool-conversion` - common C++ idiom
-- `portability-avoid-pragma-once` - `#pragma once` is the project standard
+- `README.md`: users, features, setup, and command reference
+- `CONTRIBUTING.md`: contributor process and coding conventions
+- `TODO.md`: active and deferred backlog
+- `SECURITY.md`: vulnerability reporting and supported versions
+- This file: instructions specific to coding agents
 
-### Why Not Implemented
-- **Toolchain files:** CMake Presets already provide complete build configurations
-- **install/export config:** This is an app template, not a library - no downstream consumers
-- **libc++:** Adds complexity; platform defaults work well and are more portable
-- **CPM.cmake:** FetchContent is sufficient; CPM adds another dependency to manage
+## Intentional Design
 
-## When in Doubt
+- Presets are the single build-configuration interface; toolchain files are not used.
+- FetchContent is sufficient for the template; no additional package-manager wrapper is required.
+- Platform-default standard libraries are used.
+- clangd is the language server, and its configuration removes PCH-related flags that it cannot consume.
+- PCH remains enabled for normal builds but is disabled or stripped where coverage, sanitizers, or clang-tidy require it.
+- The application template does not provide install/export configuration for downstream library consumers.
 
-1. Check existing code for patterns and conventions
-2. Run static analysis tools
-3. Follow the principle of least surprise
-4. Refer to C++ Core Guidelines for best practices
+The disabled clang-tidy checks and their exact configuration are authoritative in `.clang-tidy`; do not duplicate that list in documentation.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index aca2b25..44570eb 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -16,7 +16,7 @@
 
 <!-- Mark completed items with an [x] -->
 
-- [ ] I have read the [CONTRIBUTING](CONTRIBUTING.md) guidelines
+- [ ] I have read the [contribution guidelines](../CONTRIBUTING.md)
 - [ ] My code follows the project's coding standards
 - [ ] I have run `clang-format` on my changes
 - [ ] I have run `clang-tidy` and addressed any warnings
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8386e5c..37819eb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,114 +1,87 @@
 # Contributing to MyProject
 
-Thank you for your interest in contributing!
+This guide covers the contributor workflow and coding conventions. Project capabilities and command reference live in [README.md](README.md).
 
-## Development Setup
+## Set Up the Toolchain
 
-### Prerequisites
+Install the tools listed in the README, then validate them:
 
-**Linux:**
 ```bash
-# Ubuntu/Debian
-sudo apt install clang-22 lld-22 cmake ninja-build
-
-# Or use a recent clang version available on your system
+./tools/check-prereqs.sh
 ```
 
-**Windows:**
-1. Install LLVM from https://releases.llvm.org/
-2. Set `LLVM_ROOT` environment variable to the LLVM installation path
-3. Install CMake and Ninja
-4. (Optional) Install vcpkg for package management
-
-### Building
-
-```bash
-# Linux
-./tools/configure.sh debug
-./tools/build.sh debug
+On Windows, set `LLVM_ROOT` and run `.\tools\check-prereqs.ps1`. The repository is primarily validated with Clang 22, CMake 3.28 or newer, Ninja, lld, and ccache 4.9.1 or newer.
 
-# Windows (PowerShell)
-.\tools\configure.ps1 debug
-.\tools\build.ps1 debug
-```
+## Build and Test
 
-### Running Tests
+Use CMake Presets rather than the deprecated configure and build wrappers:
 
 ```bash
-ctest --test-dir build/debug --output-on-failure
+cmake --preset debug
+cmake --build --preset debug
+ctest --preset debug
 ```
 
-## Code Style
-
-### Formatting
+Use `win-debug` for the corresponding Windows commands. Run `cmake --list-presets` for other build and test configurations.
 
-This project uses clang-format with the configuration in `.clang-format`. Run before committing:
+Before opening a pull request, run the checks relevant to the change:
 
 ```bash
-./tools/clang-format.sh    # Linux
-.\tools\clang-format.ps1   # Windows
+./tools/check-format.sh
+./tools/clang-tidy.sh debug
+ctest --preset debug
 ```
 
-To check without modifying:
-```bash
-./tools/check-format.sh    # Linux
-.\tools\check-format.ps1   # Windows
-```
-
-### Static Analysis
+Apply formatting with `./tools/clang-format.sh`. PowerShell equivalents are available in `tools/`.
 
-Run clang-tidy regularly:
+## C++ Conventions
 
-```bash
-./tools/clang-tidy.sh debug    # Linux
-.\tools\clang-tidy.ps1 debug   # Windows
-```
+- Use C++23 and follow the repository `.clang-format` and `.clang-tidy` configurations.
+- Name types in `PascalCase`, functions in `camelCase`, constants in `UPPER_SNAKE_CASE`, and private members with an `m_` prefix.
+- Prefer RAII, const-correctness, explicit error handling, and standard-library facilities.
+- Use `#pragma once` in headers.
+- Use `#ifdef X` and `#ifndef X` for simple preprocessor checks.
+- Avoid `using namespace std` in headers.
 
-### Include Guidelines
+Order includes in groups separated by blank lines:
 
-**Include order:**
-1. Matching header (for `.cpp` files)
-2. Project headers (alphabetical)
-3. Third-party headers (alphabetical)
-4. Standard library headers (alphabetical)
+1. The matching header in a `.cpp` file
+2. Project headers, alphabetically
+3. Third-party headers, alphabetically
+4. Standard library headers, alphabetically
+5. Other platform or system headers when needed
 
-Separate each group with a blank line.
+Warnings are configured per project target. Do not weaken them globally to accommodate a dependency; declare fetched dependencies as `SYSTEM`.
 
-**Example:**
-```cpp
-#include "MyClass.h"
+## Tests
 
-#include "src/utils/Helper.h"
+Use Google Test and place tests under `tests/`. Add new test source files to `tests/CMakeLists.txt`, and add application source or header files to the corresponding lists in the root `CMakeLists.txt`.
 
-#include <spdlog/spdlog.h>
+Prefer behavior-focused test names and assertions. Tests should cover changed behavior rather than implementation details.
 
-#include <memory>
-#include <string>
-#include <vector>
-```
+## Documentation
 
-## Pull Request Process
+Keep each document focused:
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Run formatting: `./tools/clang-format.sh`
-5. Run static analysis: `./tools/clang-tidy.sh`
-6. Run tests: `ctest --test-dir build/debug`
-7. Commit your changes (`git commit -m 'Add amazing feature'`)
-8. Push to the branch (`git push origin feature/amazing-feature`)
-9. Open a Pull Request
+- `README.md` describes the template, supported workflows, and command reference.
+- `CONTRIBUTING.md` defines contributor expectations and code conventions.
+- `TODO.md` contains only current backlog and deferred ideas.
+- `SECURITY.md` defines vulnerability reporting and support expectations.
+- `.github/copilot-instructions.md` contains repository-specific agent guidance.
 
-The **PR template** will guide you through the checklist. Please complete all applicable items before requesting review.
+Update documentation when changing CMake options, presets, scripts, CI, dependencies, generated paths, or project structure.
 
-## Reporting Issues
+This project currently has no public library API. Do not add JSDoc, docstrings, or comments to self-explanatory implementation code. If reusable public headers are introduced, use Doxygen-compatible comments for public contracts where names and types are insufficient; keep internal implementation commentary minimal.
 
-Please use the appropriate **issue template**:
-- **Bug Report** - For bugs and unexpected behavior
-- **Feature Request** - For new features and improvements
+## Pull Requests
 
-The templates will guide you to include all necessary information.
+1. Create a focused branch.
+2. Make the smallest complete change.
+3. Add or update tests when behavior changes.
+4. Run formatting, static analysis, and relevant test presets.
+5. Update documentation when the user or developer workflow changes.
+6. Open a pull request and complete the repository template.
 
-### Security Issues
+Do not include unrelated cleanup in the same pull request.
 
-For security vulnerabilities, please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines. **Do not** open public issues for security vulnerabilities.
+Use the issue templates for public bug reports and feature requests. Report security vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
diff --git a/README.md b/README.md
index 8e2aa47..785b175 100644
--- a/README.md
+++ b/README.md
@@ -1,459 +1,189 @@
 # MyProject
 
-A modern C++23 project template with clang toolchain, CMake Presets, Google Test, and VS Code integration.
+A cross-platform C++23 application template built around Clang, CMake Presets, Ninja, Google Test, and VS Code.
 
-## Features
+## What Is Included
 
-- **Modern C++23** with clang as the primary compiler (LLVM 22)
-- **CMake 3.28+** build system with CMake Presets and Ninja
-- **Auto-generated version header** with version, build type, compiler, and timestamp
-- **Precompiled headers** for faster compilation
-- **Compiler caching** via ccache/sccache for faster rebuilds
-- **Code coverage** with llvm-cov and HTML reports
-- **CPack packaging** for distributable archives and installers
-- **GNUInstallDirs** for portable installation paths
-- **Google Test** for unit testing
-- **spdlog** for logging (via FetchContent)
-- **clang-tidy** and **clang-format** integration
-- **VS Code** tasks, launch configs, and clangd support
-- **Cross-platform** support for Linux and Windows
+- Linux and Windows presets for debug, release, optimized, coverage, and sanitizer builds
+- Clang with lld as the primary toolchain
+- Strict per-target warnings, with warnings treated as errors by default
+- Precompiled headers and ccache/sccache support
+- Google Test and spdlog through CMake `FetchContent`
+- clang-format, clang-tidy, llvm-cov, and CPack integration
+- GitHub Actions jobs for builds, tests, formatting, static analysis, coverage, and sanitizers
+- VS Code tasks, launch configurations, and clangd settings
+- A generated version header containing project, build, and compiler information
 
-## Getting Started
+The checked-in application is intentionally small: `src/main.cpp` logs version information and prints a greeting, while `tests/test_main.cpp` contains example Google Test cases.
 
-### Step 1: Create a New Repository from This Template
+## Create a Project from the Template
 
-1. Click the green **"Use this template"** button at the top of this page
-2. Select **"Create a new repository"**
-3. Name your repository (e.g., `AwesomeApp`)
-4. Click **"Create repository"**
-
-### Step 2: Clone Your New Repository
-
-```bash
-git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
-cd YOUR_REPO_NAME
-```
-
-### Step 3: Run the Setup Script
-
-The setup script renames all placeholder names (`MyProject`, `MYPROJECT`, `myproject`) throughout the codebase to your project name:
+1. Select **Use this template** on GitHub and create a repository.
+2. Clone the new repository.
+3. Run the one-time rename script:
 
 ```bash
 # Linux/macOS
-./setup.sh --name "YourProjectName"
-
-# Windows (PowerShell)
-.\setup.ps1 -Name "YourProjectName"
-
-# Optional: include author name
 ./setup.sh --name "YourProjectName" --author "Your Name"
 ```
 
-> **Note:** The setup script deletes itself after running - it's only needed once.
-
-### Step 4: Commit the Changes
-
-```bash
-git add -A
-git commit -m "Initial project setup"
-git push
-```
-
-### Step 5: Build and Run
-
-Using CMake Presets (recommended):
-
-```bash
-# Linux
-cmake --preset debug
-cmake --build --preset debug
-./build/debug/YourProjectName
-
-# Windows (PowerShell)
-cmake --preset win-debug
-cmake --build --preset win-debug
-.\build\win-debug\YourProjectName.exe
+```powershell
+# Windows
+.\setup.ps1 -Name "YourProjectName" -Author "Your Name"
 ```
 
-List all available presets:
-```bash
-cmake --list-presets
-```
+The author argument is optional. The setup scripts replace the `MyProject`, `MYPROJECT`, and `myproject` placeholders, then remove both setup scripts.
 
-### Step 6: Run Tests
+Commit the generated changes before beginning application development.
 
-```bash
-# Linux
-ctest --preset debug
+## Requirements
 
-# Windows
-ctest --preset win-debug
-```
+| Tool | Requirement |
+| --- | --- |
+| Clang/LLVM | 22 or newer, including lld |
+| CMake | 3.28 or newer |
+| Ninja | Required by all presets |
+| ccache | 4.9.1 or newer |
+| clang-format and clang-tidy | Required for quality checks |
+| llvm-profdata and llvm-cov | Required only for coverage |
 
-## Requirements
+On Windows, set `LLVM_ROOT` to the LLVM installation directory. `Devshell-Updated.ps1` can load a Visual Studio Developer Shell and configure the expected paths; update its installation paths if necessary.
 
-### Linux
-- Clang 22+ recommended
-- CMake 3.28+ (4.2.1+ recommended)
-- Ninja
-- lld (LLVM linker)
-- clang-tidy (static analysis)
-- clang-format (code formatting)
-- ccache 4.9.1+ (required for faster rebuilds)
-- llvm-profdata, llvm-cov (for coverage reports)
+Check a Linux development environment with:
 
 ```bash
-# Ubuntu/Debian (with LLVM APT repository for clang-22)
-sudo apt install clang-22 clang-tidy-22 clang-format-22 lld-22 llvm-22 cmake ninja-build ccache
+./tools/check-prereqs.sh
 ```
 
-### Windows
-- LLVM/Clang 22+ (includes clang-tidy, clang-format, lld, llvm-cov)
-- Set `LLVM_ROOT` environment variable
-- CMake 3.28+
-- Ninja
-- ccache 4.9.1+ (install via `choco install ccache` or `scoop install ccache`)
-
-#### Windows Development Environment
-
-For Windows builds, you need the `LLVM_ROOT` environment variable set and Visual Studio Developer Shell loaded. Use the provided DevShell script to set up your environment:
+The equivalent Windows command is:
 
 ```powershell
-# Load development environment (sets LLVM_ROOT, loads VS DevShell)
-. .\Devshell-Updated.ps1
+.\tools\check-prereqs.ps1
 ```
 
-The script:
-- Loads Visual Studio Developer Shell
-- Sets `LLVM_ROOT` environment variable
-- Adds LLVM and CMake to PATH
-
-> **Note:** You may need to update the paths in `Devshell-Updated.ps1` to match your Visual Studio installation.
-
-## Project Structure
-
-```
-.
-├── CMakeLists.txt          # Main build configuration
-├── CMakePresets.json       # CMake presets for all platforms/configs
-├── Devshell-Updated.ps1    # Windows dev environment setup
-├── setup.sh / setup.ps1    # Project renaming scripts (deleted after use)
-├── src/
-│   ├── main.cpp            # Application entry point
-│   └── version.h.in        # Version header template (generates version.h)
-├── tests/
-│   ├── CMakeLists.txt      # Test configuration
-│   └── test_main.cpp       # Example tests
-├── tools/
-│   ├── build.sh/ps1        # Build helper scripts
-│   ├── configure.sh/ps1    # Configure helper scripts
-│   ├── check-prereqs.sh/ps1 # Check prerequisite tools and versions
-│   ├── clang-tidy.sh/ps1   # Static analysis
-│   ├── clang-format.sh/ps1 # Code formatting
-│   ├── check-format.sh/ps1 # Format checking
-│   └── coverage.sh/ps1     # Code coverage reports
-├── dist/                   # CPack output (generated, gitignored)
-│   └── *.zip, *.tar.gz     # Distribution packages
-├── coverage/               # Coverage reports (generated, gitignored)
-│   └── index.html          # HTML coverage report
-├── .clang-format           # Formatting rules
-├── .clang-tidy             # Static analysis rules
-├── .clangd                 # clangd LSP configuration
-├── .github/
-│   ├── workflows/ci.yml    # CI/CD pipeline
-│   ├── ISSUE_TEMPLATE/     # Bug report and feature request templates
-│   ├── pull_request_template.md  # PR checklist
-│   └── dependabot.yml      # Automated dependency updates
-├── SECURITY.md             # Security policy and vulnerability reporting
-└── .vscode/
-    ├── tasks.json          # Build tasks (platform-aware)
-    ├── launch.json         # Debug configurations (platform-aware)
-    └── settings.json       # Editor settings
-```
-
-## VS Code Integration
-
-Install recommended extensions (VS Code will prompt you):
-- **clangd** (LLVM) - IntelliSense and code completion
-- **CodeLLDB** - Debugging support
-- **CMake Tools** - CMake integration
+## Build, Run, and Test
 
-### Build Tasks
+CMake Presets are the supported interface. The older `tools/configure.*` and `tools/build.*` wrappers remain only for backward compatibility.
 
-Tasks automatically use the correct preset for your platform (Linux or Windows):
-
-- `Ctrl+Shift+B` - Build debug (default)
-- Use Command Palette (`Ctrl+Shift+P`) → "Tasks: Run Task" for other configurations
-
-Available tasks:
-- CMake: Configure/Build Debug, RelWithDebInfo, Release, Optimized
-- CMake: Build ASan+UBSan (Linux), Build TSan (Linux)
-- CMake: Test Debug
-- Clang-Tidy, Clang-Format, Check Format
-- Check Prerequisites
-
-### Debugging
-
-Launch configurations automatically use the correct paths for your platform:
-
-- `F5` - Debug with current launch configuration
-- Configurations: Debug (Debug), Debug (RelWithDebInfo), Run (Release), Run (Optimized)
-
-## Build Types
-
-Available as CMake presets (use `cmake --list-presets` to see all):
-
-| Preset (Linux) | Preset (Windows) | Description |
-|----------------|------------------|-------------|
-| `debug` | `win-debug` | Debug symbols, no optimization, security hardening |
-| `relwithdebinfo` | `win-relwithdebinfo` | Debug symbols + optimization |
-| `release` | `win-release` | Optimized, no debug symbols |
-| `optimized` | `win-optimized` | LTO, march=x86-64-v3, stripped |
-| `coverage` | `win-coverage` | Debug + code coverage instrumentation |
-| `asan-ubsan` | — | AddressSanitizer + UBSan (Linux only) |
-| `tsan` | — | ThreadSanitizer (Linux only) |
-
-## Code Quality Tools
-
-### Formatting
 ```bash
-./tools/clang-format.sh        # Apply formatting (modifies files)
-./tools/check-format.sh        # Check compliance (no changes)
-```
-
-### Static Analysis
-```bash
-./tools/clang-tidy.sh debug    # Run clang-tidy
+# Linux
+cmake --preset debug
+cmake --build --preset debug
+ctest --preset debug
+./build/debug/MyProject
 ```
 
-> **Note:** The build uses precompiled headers (PCH) for faster compilation. Since PCH files are compiler-version-specific, the clang-tidy target automatically strips PCH flags from the compile commands. This allows clang-tidy to work even if its version differs from the compiler version.
-
-### Code Coverage
-
-Generate code coverage reports using llvm-cov. Reports are output to the `coverage/` folder (gitignored).
-
-```bash
-# Linux - generates HTML report
-./tools/coverage.sh
-
-# Linux - generate and open in browser
-./tools/coverage.sh --open
-
+```powershell
 # Windows
-.\tools\coverage.ps1
-.\tools\coverage.ps1 -OpenReport
+cmake --preset win-debug
+cmake --build --preset win-debug
+ctest --preset win-debug
+.\build\win-debug\MyProject.exe
 ```
 
-The coverage report shows:
-- Line-by-line coverage highlighting (green = covered, red = not covered)
-- Coverage percentages per file and overall
-- Branch coverage for conditional statements
+Run `cmake --list-presets` to list the presets available on the current platform.
 
-View the report at `coverage/index.html` after generation.
+### Presets
 
-### Sanitizers (Linux only)
+| Linux | Windows | Purpose |
+| --- | --- | --- |
+| `debug` | `win-debug` | Debug symbols and uninitialized-variable pattern filling |
+| `relwithdebinfo` | `win-relwithdebinfo` | Optimized build with debug information |
+| `release` | `win-release` | Standard optimized release |
+| `optimized` | `win-optimized` | `-O3`, IPO/LTO, x86-64-v3, and stripped output |
+| `coverage` | `win-coverage` | LLVM coverage instrumentation with PCH disabled |
+| `asan-ubsan` | - | AddressSanitizer and UndefinedBehaviorSanitizer |
+| `tsan` | - | ThreadSanitizer |
 
-Sanitizers catch bugs that unit tests and static analysis miss. Two presets are available:
+Each configure preset has a matching build and test preset.
 
-**AddressSanitizer + UndefinedBehaviorSanitizer** — catches memory errors and undefined behavior:
-```bash
-cmake --preset asan-ubsan
-cmake --build --preset asan-ubsan
-ctest --preset asan-ubsan
-# Or run directly:
-ASAN_OPTIONS=detect_leaks=1 ./build/asan-ubsan/MyProject
-```
+## Development Commands
 
-**ThreadSanitizer** — catches data races in multithreaded code (cannot combine with ASan):
 ```bash
-cmake --preset tsan
-cmake --build --preset tsan
-ctest --preset tsan
+./tools/clang-format.sh
+./tools/check-format.sh
+./tools/clang-tidy.sh debug
+./tools/coverage.sh
 ```
 
-Common issues detected:
-| Sanitizer | Detects |
-|-----------|---------|
-| ASan | Buffer overflows, use-after-free, double-free, memory leaks |
-| UBSan | Signed overflow, null pointer dereference, misaligned access |
-| TSan | Data races, deadlocks, thread leaks |
-
-> **Note:** Sanitizers add runtime overhead (~2-5x slower). Use them during development and CI, not in production builds.
-
-### Compiler Warnings
+PowerShell equivalents are available for each script. Use `./tools/coverage.sh --open` or `.\tools\coverage.ps1 -OpenReport` to open the generated report at `coverage/index.html`.
 
-The project applies a comprehensive set of compiler warnings tuned for Clang on both Windows and Linux. Warnings are applied per-target (not globally) to avoid affecting third-party dependencies.
-
-**Baseline warnings (all platforms):**
-```
--Wall -Wextra -Wpedantic -Wconversion -Wsign-conversion -Wshadow
--Wnon-virtual-dtor -Woverloaded-virtual -Wformat=2 -Wimplicit-fallthrough
--Wnull-dereference -Wdouble-promotion -Wcast-align -Wundef -Werror=return-type
-```
+The coverage and sanitizer presets disable PCH where instrumentation or analysis requires it. clang-tidy uses a generated PCH-free compile database so the regular build can retain PCH.
 
-**Linux/macOS additions:**
-```
--Wmisleading-indentation
-```
+## CMake Options
 
-**Windows suppressions** (reduces noise from MSVC STL/SDK headers):
-```
--Wno-unknown-pragmas -Wno-nonportable-system-include-path
-```
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `MYPROJECT_BUILD_TESTS` | `ON` | Build the Google Test target |
+| `MYPROJECT_ENABLE_CCACHE` | `ON` | Use sccache or ccache when available |
+| `MYPROJECT_ENABLE_COVERAGE` | `OFF` | Enable LLVM coverage instrumentation |
+| `MYPROJECT_ENABLE_FETCHCONTENT_CACHE` | `OFF` | Share dependency downloads across build trees |
+| `MYPROJECT_FETCHCONTENT_CACHE_DIR` | empty | Override the shared dependency cache path |
+| `MYPROJECT_ENABLE_IPO` | `ON` | Enable interprocedural optimization when supported |
+| `MYPROJECT_ENABLE_PCH` | `ON` | Enable application precompiled headers |
+| `MYPROJECT_ENABLE_WARNINGS` | `ON` | Enable the project warning set |
+| `MYPROJECT_WARNINGS_AS_ERRORS` | `ON` | Promote project warnings to errors |
 
-**CMake options:**
-| Option | Default | Description |
-|--------|---------|-------------|
-| `MYPROJECT_ENABLE_WARNINGS` | `ON` | Enable all warnings |
-| `MYPROJECT_WARNINGS_AS_ERRORS` | `ON` | Treat warnings as errors (`-Werror`) |
+The checked-in presets enable the shared `FetchContent` cache. Its default location is `.cache/fetchcontent`; `MYPROJECT_FETCHCONTENT_CACHE_DIR` and the `FETCHCONTENT_BASE_DIR` environment variable can override it.
 
-To disable warnings-as-errors for local development:
-```bash
-cmake --preset debug -DMYPROJECT_WARNINGS_AS_ERRORS=OFF
-```
+Options apply to project targets without imposing project warnings on third-party dependencies.
 
-## Packaging with CPack
+## Packaging
 
-Create distributable packages using CPack. Packages are output to the `dist/` folder (gitignored).
+Configure and build a release before invoking CPack:
 
 ```bash
-# First, build the release configuration
-cmake --preset release          # Linux
+cmake --preset release
 cmake --build --preset release
-
-# Create a ZIP package
-cpack --config build/release/CPackConfig.cmake -G ZIP
-
-# Windows
-cmake --preset win-release
-cmake --build --preset win-release
-cpack --config build/win-release/CPackConfig.cmake -G ZIP
-```
-
-Supported generators:
-| Generator | Platform | Output |
-|-----------|----------|--------|
-| `ZIP` | All | .zip archive |
-| `TGZ` | All | .tar.gz archive |
-| `DEB` | Linux | Debian .deb package |
-| `RPM` | Linux | Red Hat .rpm package |
-| `NSIS` | Windows | .exe installer |
-
-Packages are created in `dist/` with the naming format: `ProjectName-Version-Platform.ext`
-
-## Version Header
-
-The project auto-generates a `version.h` header at configure time with:
-- Project version (from CMakeLists.txt)
-- Build type (Debug, Release, etc.)
-- Compiler ID and version
-- Build timestamp (`__DATE__` and `__TIME__`)
-
-Usage:
-```cpp
-#include "version.h"
-
-spdlog::info("{} v{}", myproject::Version::PROJECT_NAME, myproject::Version::STRING);
-spdlog::debug("Built: {} {}", myproject::Version::BUILD_DATE, myproject::Version::BUILD_TIME);
-```
-
-The header is generated to `build/<preset>/generated/version.h` and provides both C macros (`MYPROJECT_VERSION`) and a C++ namespace (`myproject::Version`).
-
-## Adding Dependencies
-
-Use CMake's `FetchContent` for header-only or source-based dependencies. Always use `SYSTEM` to suppress compiler warnings from third-party code:
-
-```cmake
-FetchContent_Declare(
-    mylib
-    GIT_REPOSITORY https://github.com/example/mylib.git
-    GIT_TAG v1.0.0
-    SYSTEM  # Treat as system headers to suppress warnings
-)
-FetchContent_MakeAvailable(mylib)
+cpack --config build/release/CPackConfig.cmake
 ```
 
-Then link to your target:
+CPack always configures ZIP and TGZ archives. It also enables NSIS on Windows, DragNDrop on macOS, and DEB or RPM on Unix when the corresponding packaging tools are installed. Outputs are written to `dist/`.
 
-```cmake
-target_link_libraries(YourProjectName PRIVATE mylib)
-```
-
-### Optional: Shared FetchContent cache
-
-By default, dependencies fetched via FetchContent live under each build dir’s `_deps`. To speed up repeated config/builds across presets while keeping the source tree clean, enable the shared cache (it defaults to `.cache/fetchcontent` beside the source root and is gitignored/excluded from tooling):
-
-```bash
-cmake --preset debug -DMYPROJECT_ENABLE_FETCHCONTENT_CACHE=ON
-
-cmake --preset win-debug -DMYPROJECT_ENABLE_FETCHCONTENT_CACHE=ON
-```
+## Project Layout
 
-To pick a custom cache directory (also reused by CPM if you add it), set either `MYPROJECT_FETCHCONTENT_CACHE_DIR` or the standard `FETCHCONTENT_BASE_DIR`:
-
-```bash
-cmake --preset debug -DMYPROJECT_ENABLE_FETCHCONTENT_CACHE=ON -DMYPROJECT_FETCHCONTENT_CACHE_DIR=/path/to/cache
+```text
+.
+|-- CMakeLists.txt              Main build and packaging configuration
+|-- CMakePresets.json           Configure, build, and test presets
+|-- src/                        Application source and version template
+|-- tests/                      Google Test target and examples
+|-- tools/                      Quality, coverage, and compatibility scripts
+|-- .github/
+|   |-- actions/setup-llvm/     Reusable CI toolchain setup
+|   |-- workflows/ci.yml        Build and quality workflow
+|   `-- copilot-instructions.md Repository guidance for coding agents
+|-- .vscode/                    Tasks, launch configurations, and editor settings
+|-- CONTRIBUTING.md             Contributor workflow and coding conventions
+|-- SECURITY.md                 Vulnerability reporting policy
+`-- TODO.md                     Current project backlog
 ```
 
-## CI/CD
-
-This template includes a GitHub Actions workflow (`.github/workflows/ci.yml`) that automatically:
-- Builds on Linux (Ubuntu 24.04) and Windows
-- Runs all tests
-- Runs sanitizers (ASan+UBSan, TSan) on Linux
-- Checks code formatting (clang-format)
-- Runs static analysis (clang-tidy)
-- Generates code coverage reports
-
-**Dependabot** is configured to automatically create PRs for GitHub Actions updates (weekly).
-
-## Design Decisions
-
-This section documents intentional design choices to help template users understand why certain approaches were taken.
+Generated `build/`, `coverage/`, `dist/`, `.cache/`, and `compile_commands.json` paths are ignored by Git.
 
-### What This Template Uses
+## Dependencies
 
-| Choice | Rationale |
-|--------|----------|
-| **CMake Presets** | Single source of truth for all build configurations. No separate toolchain files needed. |
-| **FetchContent** | Simple dependency management built into CMake. No external package manager required. |
-| **Platform default C++ libraries** | libstdc++ on Linux, MSVC STL on Windows. More portable than forcing libc++ everywhere. |
-| **clangd for IDE** | Superior C++ language server. cpptools disabled to avoid conflicts. |
-| **Individual CMake options** | Granular control (e.g., `MYPROJECT_ENABLE_PCH`) rather than umbrella "Developer Mode". |
+Runtime and test dependencies are pinned by Git tag:
 
-### Disabled Clang-Tidy Checks
+| Dependency | Version | Scope |
+| --- | --- | --- |
+| spdlog | 1.13.0 | Application logging |
+| Google Test | 1.15.2 | Tests only |
 
-Some checks are disabled in `.clang-tidy` due to false positives or excessive noise:
+Add source dependencies with `FetchContent_Declare(... SYSTEM)` so third-party headers remain outside project warning enforcement.
 
-| Check | Reason |
-|-------|--------|
-| `bugprone-exception-escape` | Traces through spdlog/STL exception paths, creates wall of noise |
-| `misc-include-cleaner` | False positives with Windows headers (`<windows.h>`, `<cstdio>`) |
-| `bugprone-easily-swappable-parameters` | Too opinionated for general use |
-| `modernize-use-trailing-return-type` | Style preference, not a correctness issue |
-| `readability-identifier-naming` | Conflicts with different naming conventions |
-| `readability-identifier-length` | Too restrictive for template code |
-| `readability-magic-numbers` | Too noisy for a template project |
-| `readability-implicit-bool-conversion` | Common C++ idiom |
-| `portability-avoid-pragma-once` | `#pragma once` is the project standard |
+## CI
 
-### Why Certain Features Are Not Included
+`.github/workflows/ci.yml` runs on pushes and pull requests targeting `main`. It validates prerequisites, builds and tests Linux and Windows debug presets, checks formatting, runs clang-tidy, generates a coverage artifact, and exercises ASan+UBSan and TSan.
 
-| Feature | Reason Not Included |
-|---------|---------------------|
-| **CMake toolchain files** | Presets provide complete build configurations already |
-| **install/export config** | This is an app template, not a library with downstream consumers |
-| **libc++** | Adds complexity; platform defaults work well and are more portable |
-| **CPM.cmake** | FetchContent is sufficient; CPM adds another dependency to manage |
+Dependabot checks GitHub Actions dependencies weekly.
 
-## Contributing
+## Documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+This repository currently produces an application, not a reusable library, so it has no exported API that needs generated reference documentation. Keep user and contributor guidance in Markdown. If public headers are added later, document their public types and functions with Doxygen-compatible C++ comments; do not use JSDoc or language-style docstrings.
 
-- Use the **issue templates** for bug reports and feature requests
-- PRs will be checked against the **PR template** checklist
-- Security issues should be reported per [SECURITY.md](SECURITY.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for coding conventions and the pull request workflow. Report vulnerabilities according to [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) file.
+Licensed under the [MIT License](LICENSE).
diff --git a/SECURITY.md b/SECURITY.md
index a8264ef..58cb337 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,45 +2,23 @@
 
 ## Supported Versions
 
-| Version | Supported          |
-| ------- | ------------------ |
-| Latest  | :white_check_mark: |
+This template does not maintain multiple release lines. Security fixes apply to the latest revision of the default branch.
 
-## Reporting a Vulnerability
+## Report a Vulnerability
 
-If you discover a security vulnerability in this project, please report it responsibly:
+Do not open a public issue for a suspected vulnerability. Use GitHub private vulnerability reporting when it is enabled for the repository, or contact the repository maintainer privately.
 
-1. **Do not** open a public GitHub issue for security vulnerabilities
-2. Instead, please email the maintainer directly or use GitHub's private vulnerability reporting feature
+Include:
 
-### What to Include
+- A description of the issue and its potential impact
+- Reproduction steps or a minimal proof of concept
+- Affected versions, platforms, and configurations
+- A suggested mitigation, if known
 
-- Description of the vulnerability
-- Steps to reproduce
-- Potential impact
-- Suggested fix (if any)
+Please allow up to 48 hours for acknowledgment and one week for an initial assessment. Resolution time depends on severity and complexity.
 
-### Response Timeline
+## Security-Relevant Tooling
 
-- **Acknowledgment:** Within 48 hours
-- **Initial assessment:** Within 1 week
-- **Resolution:** Depends on severity and complexity
+The repository exercises ASan, UBSan, and TSan in CI, runs clang-tidy, treats project warnings as errors by default, and pins FetchContent dependencies to Git tags. Debug and sanitizer presets also initialize trivial automatic variables with a pattern to expose uninitialized use.
 
-## Security Best Practices
-
-This project follows security best practices:
-
-- **Sanitizers:** ASan, UBSan, and TSan presets for catching memory and threading bugs
-- **Static Analysis:** clang-tidy integration for catching potential issues at compile time
-- **Hardening:** Debug builds use `-ftrivial-auto-var-init=pattern` to catch uninitialized variable bugs
-- **Dependencies:** Managed via CMake FetchContent with pinned versions
-- **CI/CD:** Automated testing on every push and pull request
-
-## Dependencies
-
-Third-party dependencies are fetched at build time:
-
-- **spdlog** - Logging library (MIT License)
-- **Google Test** - Testing framework (BSD-3-Clause License)
-
-We recommend regularly updating dependencies and running security scans on production builds.
+These checks reduce risk but do not replace application-specific threat modeling or dependency review. Third-party source dependencies are spdlog 1.13.0 and Google Test 1.15.2; GitHub Actions dependencies are monitored by Dependabot.
diff --git a/TODO.md b/TODO.md
index a313bb9..26fb6d3 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,104 +1,34 @@
-# MyProject - TODO & Improvement Ideas
+# Project Backlog
 
-## Recommended Next Steps
+This file tracks work that is not implemented. Completed features belong in release history or commit history rather than the active backlog.
 
-Priority order for maximum impact with minimal effort:
+## Near-Term
 
-1. **EditorConfig** (5 min) - Immediate value, prevents CRLF/LF diffs
-2. **Security hardening flags** (15 min) - Add to release/optimized presets
-3. **Pre-commit hooks** (30 min) - Catch formatting issues before CI
-4. **GitHub Release workflow** (1 hr) - Auto-create releases with binaries on tag push
-5. **Dev container** (2-3 hrs) - Biggest friction reducer for new users
-6. **`std::expected` example** (1 hr) - Showcase modern C++23 idioms
+| Idea | Area | Notes |
+| --- | --- | --- |
+| EditorConfig | Developer experience | Standardize line endings and basic editor behavior outside VS Code. |
+| Release workflow | Distribution | Build packages and create a GitHub release from version tags. |
+| Dependency scanning | Security | Scan pinned C++ dependencies; Dependabot currently covers only GitHub Actions. |
+| Pre-commit checks | Developer experience | Run formatting and whitespace checks locally without duplicating CI configuration. |
+| Dev container | Onboarding | Provide a reproducible LLVM, CMake, Ninja, and ccache environment. |
 
----
+## Future Enhancements
 
-## Active Backlog
+| Idea | Area | Notes |
+| --- | --- | --- |
+| Benchmark target | Performance | Add Google Benchmark when the application has code worth measuring. |
+| Fuzz targets | Testing | Add libFuzzer targets for parsers or other untrusted-input boundaries. |
+| Performance profiling | Performance | Document perf/Instruments and evaluate profile-guided optimization. |
+| SBOM and license scanning | Supply chain | Produce package metadata when release automation exists. |
+| ARM64 or WebAssembly presets | Portability | Add only with a supported toolchain and CI coverage. |
+| C++23 examples | Education | Add `std::expected`, ranges, or mdspan examples only when they support real template structure rather than demo-only code. |
 
-- [ ] **Performance profiling** - Add perf/Instruments support, profile-guided optimization (PGO) builds
+## Deferred
 
----
+| Idea | Reason |
+| --- | --- |
+| Mutation testing with Mull | Current Mull releases do not support the project LLVM version. |
+| Standard library modules | Compiler, standard library, CMake, and clangd support is not yet mature enough for this cross-platform template. |
+| `std::generator` example | Standard library support remains inconsistent across supported platforms. |
 
-## Improvement Ideas
-
-### High Impact / Quick Wins
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **EditorConfig** | Developer Experience | 5 min | An `.editorconfig` file ensures consistent editor settings (indentation, line endings, charset) across all editors and IDEs—not just VS Code. This is especially valuable for cross-platform projects where Windows developers might accidentally introduce CRLF line endings. It's a simple file that prevents annoying whitespace-only diffs. | Ready to implement. No blockers. |
-| **Hardening flags** | Build & Tooling | 15 min | Security hardening compiler flags like `-fstack-protector-strong`, `-D_FORTIFY_SOURCE=2`, `-fPIE`, and Control Flow Integrity (CFI) protect against common vulnerability classes including buffer overflows and ROP attacks. These flags have minimal performance impact in release builds and represent security best practices that should be standard in any production-quality C++ project. | Ready to implement. Add to release/optimized presets. |
-| **Pre-commit hooks** | Developer Experience | 30 min | Pre-commit hooks via `.pre-commit-config.yaml` automatically run clang-format and other checks before each commit. This catches formatting issues, trailing whitespace, and other problems at the earliest possible moment—before code even reaches CI. Developers get instant feedback and never accidentally push unformatted code. | Ready to implement. Requires Python for pre-commit tool. |
-| **GitHub Release workflow** | Documentation & Release | 1 hr | A GitHub Actions workflow that automatically creates releases with pre-built binaries when you push a version tag streamlines the release process. Users get downloadable artifacts without manual intervention, and the release notes can be auto-generated from commit history. | Ready to implement. No blockers. |
-| **Dev container** | Developer Experience | 2-3 hrs | A `.devcontainer/` configuration enables instant, reproducible development environments in VS Code and GitHub Codespaces. New contributors can start coding within minutes without manually installing clang, cmake, ninja, or any other dependencies. This dramatically lowers the barrier to entry for contributors and ensures everyone has identical tooling, eliminating "works on my machine" issues. | Ready to implement. No blockers. |
-
-### Code Quality & Safety
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **Fuzzing** | Testing & Quality | 2 hrs | libFuzzer integration provides automated, coverage-guided fuzzing that generates random inputs to find edge cases and crashes. Unlike unit tests that check expected behavior, fuzzing discovers unexpected failures. A single fuzzing target can find more bugs in an hour than months of manual testing, especially for parsing, serialization, or any code handling untrusted input. | Ready to implement. libFuzzer built into Clang. Needs fuzz targets. |
-| **Property-based testing** | Testing & Quality | Medium | Property-based testing with rapidcheck generates hundreds of random test cases from declarative properties. Instead of writing `EXPECT_EQ(reverse(reverse(list)), list)` for a few examples, you declare the property and the framework generates diverse inputs. This finds edge cases you wouldn't think to test manually. | Ready to implement. rapidcheck available via FetchContent. |
-| **Mutation testing** | Testing & Quality | High | Mutation testing tools like mull systematically introduce bugs into your code and verify that your tests catch them. This measures the actual quality of your test suite—not just coverage, but whether your assertions would detect real bugs. It answers the question: "If this code was wrong, would my tests fail?" | **Blocked.** Mull requires LLVM 14-17. Clang 22 likely needs newer mull support. Defer until mull catches up. |
-
-### Performance Optimization
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **Benchmark framework** | Testing & Quality | 1-2 hrs | Google Benchmark integration provides a standard way to measure and track performance. Microbenchmarks catch performance regressions early, and the framework handles warmup, statistical analysis, and output formatting. Combined with CI, you can detect performance regressions before they reach production. | Ready to implement. Available via FetchContent. |
-| **Compile-time metrics** | Build & Tooling | Low | Use `-ftime-trace` to generate Chrome tracing files showing where build time goes. Helps identify slow headers and optimize compilation. | Ready to implement. Built into Clang. |
-| **Unity builds** | Build & Tooling | Low | `CMAKE_UNITY_BUILD` combines multiple source files into single translation units, dramatically reducing compile times for full rebuilds by eliminating redundant header parsing and enabling better optimization across file boundaries. While incremental builds don't benefit, clean builds can be 2-5x faster. | Ready to implement. Single CMake variable. Low value for small projects. |
-
-### Modern C++ Adoption
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **`std::expected` examples** | Modern C++23 | 1 hr | `std::expected<T, E>` provides a modern, type-safe alternative to exceptions or error codes for recoverable errors. Including example patterns in the template demonstrates idiomatic C++23 error handling and helps developers adopt this powerful feature correctly. | Ready to implement. Fully supported in Clang 22. |
-| **`std::mdspan` examples** | Modern C++23 | Low | Multi-dimensional array views for scientific computing and graphics. Shows modern approach to multi-dimensional data access. | Ready to implement. Fully supported in Clang 22. |
-| **`std::ranges` pipelines** | Modern C++23 | Low | Modern iteration patterns with range adaptors and views. Cleaner, more composable code than raw loops. | Ready to implement. Fully supported in Clang 22. |
-| **`std::print` adoption** | Modern C++23 | Low | `std::print` and `std::println` provide type-safe, format-string-based output that's cleaner than iostream and safer than printf. For simple console output, this can replace spdlog dependencies entirely, reducing compilation time and external dependencies. | ✅ Already implemented in template. |
-| **`std::generator` examples** | Modern C++23 | Low | `std::generator` enables lazy, coroutine-based sequences that can represent infinite or expensive-to-compute collections. Example code demonstrating generator patterns helps developers leverage this C++23 feature for cleaner, more memory-efficient iteration. | **Partial support.** libc++ `std::generator` is experimental. May need `-fexperimental-library`. |
-| **C++20/23 module support** | Build & Tooling | Medium | C++ modules (`import std;`) replace header files with compiled module interfaces, offering faster compilation, better encapsulation, and elimination of include-order bugs. CMake 3.28+ has experimental module support. While tooling is still maturing, early adoption positions the project for the future of C++. | **Blocked.** `import std;` requires custom-built libc++ with modules. clangd support incomplete. Revisit late 2026 (LLVM 24+). |
-
-### Tooling Gaps
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **Dependency scanning** | Security | Medium | `osv-scanner` or similar for scanning C++ dependencies for known vulnerabilities. Dependabot only covers GitHub Actions, not C++ deps. | Ready to implement. osv-scanner is standalone binary. |
-| **Include-what-you-use** | Code Quality | Medium | IWYU is more reliable than clang-tidy's `misc-include-cleaner`. Ensures headers include exactly what they need. | Ready to implement. Separate tool from LLVM. |
-
-### Platform & Distribution
-
-| Idea | Type | Effort | Description | Notes |
-|------|------|--------|-------------|-------|
-| **Changelog generation** | Documentation & Release | 1 hr | Conventional commit messages combined with automated changelog generation (via tools like git-cliff or release-please) create professional, consistent release notes. This documents what changed between versions without manual effort, helping users understand upgrade impacts. | Ready to implement. git-cliff is standalone binary. |
-| **SBOM generation** | Documentation & Release | Medium | Software Bill of Materials (SBOM) generation documents all dependencies in standard formats like SPDX or CycloneDX. This is increasingly required for supply chain security compliance and helps users understand exactly what's in your software. Some industries and government contracts now mandate SBOMs. | Ready to implement. Tools: syft, cyclonedx-cli. May need CMake integration. |
-| **License scanning** | Documentation & Release | Low | REUSE compliance ensures every file has clear license information via SPDX headers. This removes legal ambiguity for users and contributors, making it clear how the code can be used. Automated scanning in CI prevents accidentally adding incompatibly-licensed code. | Ready to implement. REUSE tool via pip. |
-| **Cross-compilation presets** | Build & Tooling | Medium | CMake presets for ARM64 and WebAssembly (via Emscripten) targets enable building for additional platforms without leaving the familiar preset workflow. ARM64 support is increasingly important as Apple Silicon and ARM servers become mainstream; WASM enables running C++ in browsers. | ARM64: Ready (needs cross-compiler). WASM: Requires Emscripten SDK install. |
-
----
-
-## Completed
-
-- [x] CMake Presets Implementation
-- [x] Deprecate legacy scripts
-- [x] Update VS Code integration
-- [x] Clean up tasks.json
-- [x] Update utility scripts
-- [x] Update README
-- [x] Update setup scripts
-- [x] Add Precompiled Headers (PCH)
-- [x] Add compiler caching (ccache/sccache)
-- [x] Fix clang-tidy warnings
-- [x] Add GitHub Actions CI (Linux/Windows builds, format-check, static-analysis, coverage jobs)
-- [x] Add code coverage (llvm-cov)
-- [x] Add GNUInstallDirs
-- [x] Add CPack support
-- [x] Version header generation (version.h from CMake)
-- [x] Sanitizer support (ASan+UBSan, TSan presets for Linux)
-- [x] Comprehensive compiler warnings (platform-tuned for Clang on Windows/Linux)
-- [x] Document design decisions (copilot-instructions.md, README.md)
-
-### Completed Improvement Ideas
-
-| Idea | Type | Effort | Description |
-|------|------|--------|-------------|
-| **Version header generation** | Build & Tooling | Low | Auto-generating a `version.h` header from CMake embeds version information directly in the binary. This enables runtime version queries, proper `--version` output, and ensures the compiled binary always knows its own version. It's a small feature that makes releases and debugging significantly easier. |
+When implementing an item, update the README only if the supported workflow or feature set changes, then remove the item from this file.

From 957b2af23a14a928ce0f24fea2a0b37a11d782b4 Mon Sep 17 00:00:00 2001
From: Matt Gradwohl <mattgr@msn.com>
Date: Wed, 19 Aug 2026 16:24:51 -0700
Subject: [PATCH 2/2] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 785b175..2efea49 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ The checked-in application is intentionally small: `src/main.cpp` logs version i
 3. Run the one-time rename script:
 
 ```bash
-# Linux/macOS
+# Linux
 ./setup.sh --name "YourProjectName" --author "Your Name"
 ```