Add Copilot repository guidance and tuned Scout knowledge

.github/copilot-instructions.md

@@ -0,0 +1,141 @@
+# Repository instructions
+
+## Repository purpose and architecture
+
+`cpp-library` is a CMake infrastructure toolkit consumed by other C++ library
+repositories through `CPMAddPackage`. Its implementation is CMake scripts and
+consumer templates; C++ sources here are integration fixtures.
+
+There are two entry points:
+
+- `setup.cmake` runs in CMake script mode to scaffold a new consumer project,
+  including its `CMakeLists.txt`, header, directory structure, and Git repository.
+- `cpp-library.cmake` exposes the public functions used by consumers. It owns
+  `cpp_library_setup()`, package/alias naming, version propagation, and test/example
+  executable creation. `cmake/cpp-library-setup.cmake` supplies internal helpers
+  for version discovery, library target creation, and template copying.
+
+The consumer lifecycle is order-sensitive:
+
+1. Load CPM and this toolkit, then call
+   `cpp_library_enable_dependency_tracking()` **before `project()`**. It registers
+   the provider through `CMAKE_PROJECT_TOP_LEVEL_INCLUDES`; CMake 3.24+ is required.
+2. After `project()`, declare dependencies through `find_package()` or CPM.
+   Call `include(CTest)` at directory scope before `cpp_library_setup()` when
+   supplying `TESTS` or `EXAMPLES`. Setup requires `DESCRIPTION`, `NAMESPACE`,
+   and `HEADERS`.
+3. Setup creates the library target and optional installation rules. Only
+   top-level projects proceed to template generation, tests, examples, and docs.
+   `BUILD_TESTING` gates both tests and examples; `BUILD_DOCS` gates documentation.
+
+`cmake/cpp-library-dependency-provider.cmake` records dependency versions and
+components in `GLOBAL` properties. `cmake/cpp-library-install.cmake` uses this
+state and target link interfaces to generate installed `find_dependency()` calls.
+The install module is loaded inside public setup, after `project()`.
+Installation defaults to `PROJECT_IS_TOP_LEVEL`, controlled by an explicit
+`INSTALL_OPTION` or the legacy uppercase `<NAMESPACE>_INSTALL` cache option.
+Use distinct `INSTALL_OPTION` names for independently installable packages that
+share a namespace.
+
+Install finalization is deferred until the target's directory has finished
+declaring links. `_cpp_library_finish_install()` first generates the package
+config, then registers dependency validation before export/config installation.
+Preserve this ordering and the target-local install metadata: untracked
+dependencies warn during configuration but fail installation.
+
+`templates/` contains outputs for consumers. Static files are copied only when
+missing unless `CPP_LIBRARY_FORCE_INIT` is enabled; `.in` files are configured.
+`cmake/cpp-library-ci.cmake` generates consumer CI from
+`templates/.github/workflows/ci.yml.in`, which is separate from this repository's
+own `.github/workflows/ci.yml`. Documentation generation uses
+`cmake/cpp-library-docs.cmake`, Doxygen, and doxygen-awesome-css.
+`cmake/cpp-library-testing.cmake` provides the public runtime-DLL copy helper;
+test/example target creation lives in the root module.
+
+## Commands
+
+Run script regressions from the repository root. PowerShell examples:
+
+```powershell
+cmake -P tests\install\CMakeLists.txt
+cmake -P tests\install\test_provider_merge.cmake
+cmake -P tests\install\test_nested_install.cmake
+cmake -P tests\setup\test_target_type.cmake
+cmake -P tests\setup\test_runtime_dlls.cmake
+cmake -P tests\setup\test_setup_version_resolution.cmake
+cmake -P tests\docs\test_docs.cmake
+```
+
+Each standalone script is an independently runnable regression; for example,
+run only target-type coverage with
+`cmake -P tests\setup\test_target_type.cmake`. The install `CMakeLists.txt` is a
+script-mode harness that includes both dependency-mapping and provider tests;
+those included files rely on its mocks and assertion helpers.
+
+Use CMake 3.24+ for the regressions. Compiled integration fixtures require Ninja
+and a configured C++ compiler; on Windows use an x64 Visual Studio developer
+environment. Documentation rendering additionally requires Doxygen.
+The nested-install regression performs build/install/downstream-consumer round
+trips for static and shared libraries, including Windows DLL deployment.
+The repository's CI also demonstrates a generated consumer's complete
+CPM-to-install-to-`find_package()` round trip.
+
+To exercise changes in an existing consumer without publishing a release:
+
+```cmake
+CPMAddPackage(
+    NAME cpp-library
+    SOURCE_DIR "${CMAKE_SOURCE_DIR}/../cpp-library"
+)
+```
+
+In a consumer project, the generated presets provide build, test, and lint
+commands:
+
+```text
+cmake --preset test
+cmake --build --preset test
+ctest --preset test
+ctest --preset test -R "^<test-name>$"
+cmake --preset clang-tidy
+cmake --build --preset clang-tidy
+cmake --preset docs
+cmake --build --preset docs
+```
+
+The `clang-tidy` preset requires clang-tidy and runs analysis during compilation.
+These presets come from `templates/CMakePresets.json` and apply to consumers.
+`cmake --preset init` enables `CPP_LIBRARY_FORCE_INIT` and overwrites generated
+consumer templates.
+
+## Codebase conventions
+
+- Consumer `HEADERS`, `SOURCES`, `TESTS`, and `EXAMPLES` arguments are filenames
+  resolved under `include/<namespace>/`, `src/`, `tests/`, and `examples/`,
+  respectively. Omitting `SOURCES` creates an `INTERFACE` target; compiled
+  targets respect `BUILD_SHARED_LIBS`. Headers use CMake `FILE_SET headers`.
+- `project(component)` with `NAMESPACE org` yields target `component`, alias
+  `org::component`, and package `org-component`; the GitHub repository naming
+  convention is `org/org-component`. If the project already has the namespace
+  prefix, the alias strips it. Matching namespace and clean project name collapse
+  to one package name rather than duplicating it.
+- Consumer versions come from Git tags with a leading `v` removed.
+  `CPP_LIBRARY_VERSION` overrides Git discovery for source archives and package
+  managers; missing tags fall back to `0.0.0` with a warning.
+- Non-namespaced dependency targets need explicit mappings such as
+  `cpp_library_map_dependency(opencv_core "OpenCV 4.8")`. Keep dependency
+  declarations after `project()` in the top-level consumer scope; explicit
+  mappings also cover dependencies the provider cannot capture.
+- Dependency unit tests use `run_test()`, `mock_target_links()`, the function
+  under test, and `verify_output()`. Follow the actual harness in
+  `tests/install/CMakeLists.txt` and cases in `test_dependency_mapping.cmake`.
+  Provider functions load in test mode, and each case resets tracked/mapped
+  `GLOBAL` state rather than creating real CMake targets.
+- When updating pinned dependencies, search for `[DEPENDENCY]` markers across
+  CMake, workflows, and docs. In Markdown, keep the marker inside an HTML comment.
+  Changes to generated consumer behavior belong in the corresponding template
+  and generation code, not just a generated consumer file.
+
+README.md documents the public API and consumer workflows; CLAUDE.md provides
+additional repository context. Check current implementation when their details
+disagree, especially installation controls and deferred processing.

.scout/evaluations/autotune-query-set.toml

@@ -0,0 +1,210 @@
+description = "cpp-library CMake toolkit search quality: public API, internal modules, consumer templates, and regressions"
+
+[[queries]]
+id = "ident-setup"
+query = "cpp_library_setup"
+class = "identifier"
+
+[judgments.ident-setup]
+"cpp-library.cmake" = 3
+"README.md" = 2
+"setup.cmake" = 1
+
+[[queries]]
+id = "ident-provider"
+query = "cpp_library_enable_dependency_tracking"
+class = "identifier"
+
+[judgments.ident-provider]
+"cpp-library.cmake" = 3
+"cmake/cpp-library-dependency-provider.cmake" = 2
+"README.md" = 2
+"setup.cmake" = 1
+
+[[queries]]
+id = "ident-mapping"
+query = "cpp_library_map_dependency"
+class = "identifier"
+
+[judgments.ident-mapping]
+"cmake/cpp-library-install.cmake" = 3
+"README.md" = 2
+"tests/install/test_dependency_mapping.cmake" = 2
+
+[[queries]]
+id = "ident-runtime-dlls"
+query = "cpp_library_copy_runtime_dlls"
+class = "identifier"
+
+[judgments.ident-runtime-dlls]
+"cmake/cpp-library-testing.cmake" = 3
+"cmake/cpp-library-copy-runtime-dlls.cmake" = 2
+"README.md" = 2
+"cpp-library.cmake" = 1
+"setup.cmake" = 0
+
+[[queries]]
+id = "ident-version"
+query = "_cpp_library_get_git_version"
+class = "identifier"
+
+[judgments.ident-version]
+"cmake/cpp-library-setup.cmake" = 3
+"cmake/cpp-library-install.cmake" = 2
+"cpp-library.cmake" = 2
+
+[[queries]]
+id = "ident-docs"
+query = "_cpp_library_setup_docs"
+class = "identifier"
+
+[judgments.ident-docs]
+"cmake/cpp-library-docs.cmake" = 3
+"cpp-library.cmake" = 2
+"cmake/cpp-library-copy-runtime-dlls.cmake" = 0
+
+[[queries]]
+id = "ident-ci"
+query = "_cpp_library_setup_ci"
+class = "identifier"
+
+[judgments.ident-ci]
+"cmake/cpp-library-ci.cmake" = 3
+"cmake/cpp-library-setup.cmake" = 2
+
+[[queries]]
+id = "ident-executables"
+query = "_cpp_library_setup_executables"
+class = "identifier"
+
+[judgments.ident-executables]
+"cpp-library.cmake" = 3
+"cmake/cpp-library-testing.cmake" = 2
+
+[[queries]]
+id = "nl-version"
+query = "determine the consumer library version from git tags or an explicit override"
+class = "natural_language"
+
+[judgments.nl-version]
+"cmake/cpp-library-setup.cmake" = 3
+"cpp-library.cmake" = 2
+"cmake/cpp-library-install.cmake" = 2
+"README.md" = 1
+
+[[queries]]
+id = "nl-install-validation"
+query = "reject installation when linked dependencies were not tracked and generate package dependency declarations"
+class = "natural_language"
+
+[judgments.nl-install-validation]
+"cmake/cpp-library-install.cmake" = 3
+"cmake/cpp-library-dependency-provider.cmake" = 2
+"README.md" = 1
+"setup.cmake" = 0
+
+[[queries]]
+id = "nl-library-kind"
+query = "create a header-only interface library or a compiled static or shared library with exported headers"
+class = "natural_language"
+
+[judgments.nl-library-kind]
+"cmake/cpp-library-setup.cmake" = 3
+"cpp-library.cmake" = 2
+"README.md" = 1
+
+[[queries]]
+id = "nl-runtime-dlls"
+query = "deploy runtime DLL dependencies beside executables on Windows without copying a file onto itself"
+class = "natural_language"
+
+[judgments.nl-runtime-dlls]
+"cmake/cpp-library-copy-runtime-dlls.cmake" = 3
+"cmake/cpp-library-testing.cmake" = 3
+"cpp-library.cmake" = 2
+"tests/install/README.md" = 1
+"setup.cmake" = 0
+
+[[queries]]
+id = "nl-docs-inputs"
+query = "add extra documentation inputs and validate single-line Doxygen assignments before rendering HTML"
+class = "natural_language"
+
+[judgments.nl-docs-inputs]
+"cmake/cpp-library-docs.cmake" = 3
+"cpp-library.cmake" = 2
+"README.md" = 1
+
+[[queries]]
+id = "nl-ci-generation"
+query = "generate the consumer GitHub Actions workflow from a template and substitute pinned action versions"
+class = "natural_language"
+
+[judgments.nl-ci-generation]
+"cmake/cpp-library-ci.cmake" = 3
+"templates/.github/workflows/ci.yml.in" = 2
+"cmake/cpp-library-setup.cmake" = 1
+".github/workflows/ci.yml" = 0
+
+[[queries]]
+id = "nl-scaffolding"
+query = "scaffold a new consumer project with an initial header, tests, examples, and CMakeLists"
+class = "natural_language"
+
+[judgments.nl-scaffolding]
+"setup.cmake" = 3
+"README.md" = 2
+"cpp-library.cmake" = 1
+
+[[queries]]
+id = "nl-consumer-presets"
+query = "consumer presets for Ninja builds, testing, documentation, clang-tidy, and forced template initialization"
+class = "natural_language"
+
+[judgments.nl-consumer-presets]
+"templates/CMakePresets.json" = 3
+"README.md" = 2
+"cmake/cpp-library-setup.cmake" = 1
+
+[[queries]]
+id = "filt-runtime-dlls"
+query = "cpp_library_copy_runtime_dlls"
+class = "filtered"
+extensions = ["cmake"]
+paths = ["cmake"]
+
+[judgments.filt-runtime-dlls]
+"cmake/cpp-library-testing.cmake" = 3
+"cmake/cpp-library-copy-runtime-dlls.cmake" = 2
+
+[[queries]]
+id = "filt-docs-options"
+query = "DOCS_OPTIONS"
+class = "filtered"
+extensions = ["cmake"]
+paths = ["cmake"]
+
+[judgments.filt-docs-options]
+"cmake/cpp-library-docs.cmake" = 3
+"cmake/cpp-library-copy-runtime-dlls.cmake" = 0
+
+[[queries]]
+id = "filt-consumer-presets"
+query = "BUILD_TESTING"
+class = "filtered"
+extensions = ["json"]
+paths = ["templates"]
+
+[judgments.filt-consumer-presets]
+"templates/CMakePresets.json" = 3
+
+[[queries]]
+id = "filt-version"
+query = "_cpp_library_get_git_version"
+class = "filtered"
+extensions = ["cmake"]
+paths = ["cmake"]
+
+[judgments.filt-version]
+"cmake/cpp-library-setup.cmake" = 3
+"cmake/cpp-library-install.cmake" = 2

.scout/memory/index.md

@@ -0,0 +1,15 @@
+# Memory Bank Index
+
+## Knowledge
+
+- [[knowledge/architecture-overview.md|Architecture Overview]] (concept, 0.80) `architecture-overview` `cpp-library-architecture` `cpp-library-overview` `toolkit-architecture` `cmake-infrastructure-overview`
+- [[knowledge/consumer-lifecycle-and-template-overwrite-controls.md|Consumer Lifecycle and Template Overwrite Controls]] (decision, 0.75) `template-initialization` `cpp-library-force-init` `project-is-top-level` `lightweight-consumer-mode` `template-copying`
+- [[knowledge/deferred-install-dependency-validation-and-config-generation.md|Deferred Install Dependency Validation and Config Generation]] (pattern, 0.75) `deferred-install` `install-validation` `untracked-dependencies` `cmake-language-defer` `find-dependency`
+- [[knowledge/dependency-tracking-lifecycle-and-provider-ordering.md|Dependency Tracking Lifecycle and Provider Ordering]] (observation, 0.75) `dependency-tracking` `dependency-provider` `cpp-library-enable-dependency-tracking` `cmake-project-top-level-includes` `set-dependency-provider`
+- [[knowledge/documentation-setup-and-theme-integration-with-build-docs.md|Documentation Setup and Theme Integration with BUILD_DOCS]] (pattern, 0.75) `build-docs` `doxygen` `doxygen-awesome-css` `documentation-generation` `docs-target`
+- [[knowledge/target-naming-and-alias-deduplication-convention.md|Target Naming and Alias Deduplication Convention]] (pattern, 0.75) `target-naming` `alias-deduplication` `package-name` `clean-name` `cmake-alias-convention`
+- [[knowledge/testing-and-example-executable-target-generation-gated-by-build-testing.md|Testing and Example Executable Target Generation Gated by BUILD_TESTING]] (pattern, 0.75) `build-testing` `doctest` `testing-setup` `negative-compilation-tests` `runtime-dll-copy`
+
+## Procedures
+
+- [[procedures/interactive-and-headless-project-scaffolding-with-setup-cmake.md|Interactive and Headless Project Scaffolding with setup.cmake]] (procedure, 0.75) `setup-cmake` `project-scaffolding` `consumer-initialization` `standalone-generator` `cpp-library-setup-script`

.scout/memory/knowledge/architecture-overview.md

@@ -0,0 +1,29 @@
+---
+title: "Architecture Overview"
+entity_type: concept
+source: inferred
+confidence: 0.80
+created: 2026-10-12T21:15:34Z
+last_accessed: 2026-10-12T21:17:06Z
+last_reinforced: 2026-10-12T21:15:34Z
+access_count: 2
+sources:
+  - "cpp-library.cmake:47-81"
+  - "setup.cmake:1-50"
+  - "cmake/cpp-library-setup.cmake:140-195"
+tags: ["architecture-overview", "cpp-library-architecture", "cpp-library-overview", "toolkit-architecture", "cmake-infrastructure-overview"]
+tier: knowledge
+---
+
+# Architecture Overview
+
+cpp-library is a CMake infrastructure toolkit consumed by C++ libraries via CPMAddPackage to standardize build, test, install, docs, and CI workflows. Its implementation is CMake scripts and consumer templates; C++ sources in this repository are integration fixtures. It provides two entry points: setup.cmake for standalone project scaffolding, and cpp-library.cmake for runtime consumption. Consumer projects enable dependency tracking before project(), invoke project(), include(CTest) when using tests or examples, and configure via cpp_library_setup(). Target creation distinguishes between INTERFACE and compiled libraries (respecting BUILD_SHARED_LIBS), while top-level builds configure templates and CI. Installation and its dependency validation are independently controlled by installation options, including for subprojects.
+
+Key boundary paths:
+- cpp-library.cmake: runtime entry point exposing public functions
+- cmake/cpp-library-setup.cmake: target setup, template management, and git version resolution
+- cmake/cpp-library-install.cmake: deferred install config generation and dependency validation
+- cmake/cpp-library-dependency-provider.cmake: CMake 3.24+ dependency provider hook
+- setup.cmake: standalone project generator
+
+Aliases / also known as: Architecture Overview, cpp-library architecture, cpp-library overview, toolkit architecture, CMake infrastructure overview