Improve agent documentation

.ci/AGENTS.md

@@ -74,9 +74,7 @@ The oneDAL CI infrastructure supports:
 ### CI Platform Integration
 - **GitHub Actions**: Primary CI/CD platform for public workflows
 - **Azure DevOps**: Extended validation and internal testing
-- **Mergify**: Automated merge management
 - **Renovate**: Dependency update automation
-- **Codefactor**: Code quality analysis
 
 ### Build Matrix Configuration
 The CI system employs comprehensive build matrices covering:
@@ -92,6 +90,10 @@ The CI system employs comprehensive build matrices covering:
 - **Security**: OpenSSF Scorecard integration
 - **Documentation**: Automated doc generation and validation
 
+## Rules for Changes
+- Pipelines call scripts in `.ci/scripts/` and `.ci/env/`. Change the script, not only the pipeline YAML that calls it.
+- Style checks (clang-format, editorconfig-checker) run only in Azure `FormatterChecks`. See "Verification Before You Push" in the root `AGENTS.md`.
+
 ## Usage Guidelines
 
 ### Local Development

.gitattributes

@@ -5,7 +5,7 @@
 # to LF line endings on checkout.
 *.c text
 *.h text
-*.i text
+*.i text linguist-language=C++
 *.hpp text
 *.cpp text
 *.def text

.github/.licenserc.yaml

@@ -64,6 +64,7 @@ header:
     - 'docs/source/substitutions_specific.txt'
     # Some files from .ci/.github
     - '.github/instructions/*.md'
+    - '.github/copilot-instructions.md'
     - '.github/CODEOWNERS'
     - '.github/pull_request_template.md'
     - '.github/renovate.json'

.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# Copilot instructions - oneDAL
+
+`AGENTS.md` is the canonical repository guidance. Before reviewing or editing a file, read the root `AGENTS.md` and every applicable directory-level `AGENTS.md`.
+
+Also follow the matching `.github/instructions/*.instructions.md` files. They provide additive, Copilot-specific guidance selected by `applyTo`; do not duplicate or override `AGENTS.md` policy here.

.github/instructions/AGENTS.md

@@ -0,0 +1,11 @@
+# Agent Instructions for `.github/instructions`
+
+These files provide Copilot guidance for paths selected by their YAML `applyTo` front matter.
+
+## Rules for Changes
+
+- Keep `applyTo` patterns aligned with every file type the instruction governs, including templates and configuration files.
+- Treat overlapping instruction files as additive. Keep broad guidance brief and let scoped files add detail without contradicting it.
+- Keep PR review rules limited to source-confirmed correctness, compatibility, ownership, dispatch, error handling, and test coverage. Do not duplicate checks enforced by formatting, license, or other CI jobs.
+- Link only to existing files, using paths relative to the instruction file.
+- Put durable subsystem context in the nearest `AGENTS.md`; use these files only for Copilot-specific and path-scoped guidance.

.github/instructions/build-systems.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: ["**/makefile", "**/Makefile", "**/BUILD", "**/BUILD.bazel", "**/*.bazel", "**/*.mk", "**/CMakeLists.txt"]
+applyTo: ["**/makefile", "**/Makefile", "**/BUILD", "**/BUILD.bazel", "**/*.tpl.BUILD", "**/*.bazel", "**/*.bzl", ".bazelrc", "**/.bazelrc", "**/*.mk", "**/CMakeLists.txt"]
 ---
 
 # Build Systems Instructions for GitHub Copilot
@@ -15,36 +15,38 @@ applyTo: ["**/makefile", "**/Makefile", "**/BUILD", "**/BUILD.bazel", "**/*.baze
 ### Make (Production)
 ```bash
 # Build everything
-`make`
+make -f makefile daal oneapi PLAT=lnx32e
 
 # Platform-specific builds
-`make PLAT=lnx32e COMPILER=icx`
-`make PLAT=win32e COMPILER=vc`
+make -f makefile daal oneapi_c PLAT=lnx32e COMPILER=gnu
+make -f makefile oneapi_c PLAT=win32e COMPILER=vc
 
 # CPU targets
-`make REQCPU="sse2 avx2 avx512"`
+make -f makefile daal PLAT=lnx32e REQCPU="avx2 avx512"
 
 # Backend selection
-`make BACKEND_CONFIG=mkl`  # Intel MKL (default)
-`make BACKEND_CONFIG=ref`  # Reference/OpenBLAS
+make -f makefile daal PLAT=lnx32e BACKEND_CONFIG=mkl  # Intel MKL (default)
+make -f makefile daal PLAT=lnx32e BACKEND_CONFIG=ref  # Reference/OpenBLAS
 ```
 
 ### Bazel (Development)
 ```bash
 # Build targets
-`bazel build //cpp/oneapi/dal:core`
-`bazel build //examples/daal/cpp:association_rules`
+bazel build //cpp/oneapi/dal:core
+bazel build //examples/daal/cpp:cholesky
 
 # Test targets
-`bazel test //cpp/oneapi/dal:tests`
-`bazel test --config=dpc //cpp/oneapi/dal:tests`  # GPU tests
+bazel test --config=host //cpp/oneapi/dal:tests               # CPU only
+bazel test --config=dpc --device=gpu //cpp/oneapi/dal:tests   # DPC++ on GPU
 ```
 
 ### CMake (Integration)
+There is no root `CMakeLists.txt`. CMake builds the examples against an installed release, found with `find_package(oneDAL)`:
 ```bash
-# Configure and build
-`cmake -B build -S . -DCMAKE_BUILD_TYPE=Release`
-`cmake --build build --parallel`
+source __release_lnx/daal/latest/env/vars.sh   # Make release tree
+cd examples/oneapi/cpp
+cmake -B build -S . -DONEDAL_LINK=dynamic
+cmake --build build --parallel
 ```
 
 ## 🏗️ CPU Architecture Support

.github/instructions/cpp-coding-guidelines.instructions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: ["**/*.cpp", "**/*.hpp", "**/*.h", "**/cpp/**", "**/include/**"]
+applyTo: ["**/*.cpp", "**/*.hpp", "**/*.h", "**/*.i", "**/cpp/**", "**/include/**"]
 ---
 
 # C++ Development and Coding Guidelines for GitHub Copilot
@@ -255,39 +255,14 @@ private:
 };
 ```
 
-## 🔍 **PR Review Checklist**
-
-### Code Quality (VALIDATED CRITERIA)
-- [ ] **Interface consistency** - No mixing DAAL/oneAPI patterns
-  - DAAL: `services::Status`, `SharedPtr`, `.h` headers, traditional guards
-  - oneAPI: exceptions, `std::unique_ptr`/`std::shared_ptr`, `.hpp` headers, `#pragma once`
-- [ ] **Memory management** follows interface patterns
-  - DAAL: `daal::services::SharedPtr<T>`
-  - oneAPI: `std::unique_ptr`, `std::shared_ptr`
-- [ ] **Error handling** appropriate for interface
-  - DAAL: `services::Status` return codes
-  - oneAPI: C++ exceptions
-- [ ] **Naming conventions** followed consistently
-- [ ] **Header guards** correct for interface (`#pragma once` vs traditional)
-
-### Style and Security
-- [ ] **C++17 maximum standard** - no C++20/23 features
-- [ ] **Indentation** uses 4 spaces (no tabs)
-- [ ] **File headers** include copyright and description (validated format)
-- [ ] **Type safety** with proper validation
-- [ ] **Const correctness** applied appropriately
-- [ ] **Bounds checking** implemented where needed
-
-## 🚨 **Critical Reminders for PR Review**
-
-1. **Interface Separation** - NEVER mix DAAL and oneAPI patterns in the same file
-2. **Memory Management** - Use correct smart pointer types for each interface
-3. **Error Handling** - Use status codes for DAAL, exceptions for oneAPI
-4. **Header Extensions** - `.h` for DAAL, `.hpp` for oneAPI
-5. **Include Guards** - Traditional guards for DAAL, `#pragma once` for oneAPI
-6. **C++17 Compliance** - No C++20/23 features for maximum compatibility
-
-## 🔄 **Cross-Reference**
-- **[general.md](/.github/instructions/general.md)** - General repository context
-- **[build-systems.md](/.github/instructions/build-systems.md)** - Build system instructions
-- **[examples.md](/.github/instructions/examples.md)** - Example code patterns
+## PR Review Checklist
+
+- Preserve the interface contract: DAAL uses `services::Status`, `SharedPtr`, `.h` headers, and traditional guards; oneAPI uses exceptions, standard smart pointers, `.hpp` headers, and `#pragma once`.
+- Check ownership, lifetime, error propagation, type safety, and bounds handling when the changed code makes them relevant.
+- Preserve CPU dispatch and avoid introducing C++20/23 features.
+- Flag public API or ABI changes unless the change explicitly accounts for compatibility.
+
+## Cross-Reference
+- [general.instructions.md](general.instructions.md) - Repository context
+- [build-systems.instructions.md](build-systems.instructions.md) - Build system instructions
+- [examples.instructions.md](examples.instructions.md) - Example code patterns

.github/instructions/documentation.instructions.md

@@ -4,95 +4,10 @@ applyTo: ["**/docs/**", "**/*.rst", "**/*.md", "**/Doxyfile"]
 
 # Documentation Instructions for GitHub Copilot
 
-## Documentation Architecture
+Read [../../docs/AGENTS.md](../../docs/AGENTS.md) for the documentation structure and build pipeline.
 
-oneDAL uses a multi-format documentation system:
-- **API Reference**: Doxygen-generated C++ API documentation
-- **Developer Guide**: reStructuredText-based comprehensive guides  
-- **Examples**: Code examples and tutorials
-- **User Guides**: Installation and usage instructions
+## Review Focus
 
-## C++ API Documentation (Doxygen)
-
-### Header File Documentation
-```cpp
-/**
- * @brief K-means clustering algorithm implementation
- * 
- * @tparam Float Floating-point type for computations
- * @tparam Method Algorithm method (lloyd_dense, lloyd_csr)
- * 
- * @par Example
- * @code
- * auto desc = kmeans::descriptor<float>().set_cluster_count(10);
- * auto result = train(desc, data);
- * @endcode
- * 
- * @par Thread Safety
- * This class is not thread-safe.
- */
-template<typename Float, Method Method>
-class kmeans {
-public:
-    /**
-     * @brief Sets the number of clusters
-     * @param[in] count Number of clusters to generate
-     * @return Reference to this descriptor for method chaining
-     */
-    auto& set_cluster_count(std::int64_t count);
-};
-```
-
-### Implementation Documentation
-```cpp
-/**
- * @brief Computes K-means clustering
- * @param[in] desc Algorithm descriptor with parameters
- * @param[in] data Input data table
- * @return Training result containing the trained model
- * 
- * @par Exception Safety
- * Strong exception guarantee - if an exception is thrown, the program state remains unchanged.
- * 
- * @par Thread Safety
- * This function is not thread-safe.
- */
-template<typename Float, Method Method>
-auto train(const kmeans::descriptor<Float, Method>& desc, const table& data);
-```
-
-## reStructuredText Documentation
-
-### Section Structure
-```rst
-K-Means Clustering
-==================
-
-Overview
---------
-K-means clustering groups similar data points into clusters.
-
-Usage Example
-------------
-.. code-block:: cpp
-
-    auto desc = kmeans::descriptor<float>().set_cluster_count(10);
-    auto result = train(desc, data);
-```
-
-## Documentation Standards
-
-### Content Guidelines
-- **Accuracy**: Ensure technical correctness
-- **Completeness**: Cover all public APIs
-- **Clarity**: Use clear, concise language
-- **Examples**: Provide working code examples
-
-### Maintenance Guidelines
-- **Updates**: Keep documentation synchronized with code
-- **Testing**: Validate all code examples compile and run
-- **Links**: Test internal and external links regularly
-
-## Cross-Reference
-- **[AGENTS.md](/docs/AGENTS.md)** - Documentation context
-- **[examples.md](/.github/instructions/examples.md)** - Example patterns
+- Keep public documentation accurate, concise, and synchronized with the implementation.
+- Use the established reStructuredText and Doxygen conventions in the surrounding content.
+- Verify that changed examples, commands, and links remain valid.