docs: add hierarchical AGENTS and long-lived Copilot instructions

.github/.licenserc.yaml

@@ -51,6 +51,10 @@ header:
   - docker/x86_64/manylinux2014/oneAPI.repo
   - docs/cpp/index/loader-compatibility.csv
   - docs/requirements.txt
+  - AGENTS.md
+  - '**/AGENTS.md'
+  - .github/copilot-instructions.md
+  - .github/instructions/*.instructions.md
 
   comment: never
 

.github/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — .github/
+
+CI/CD workflows, automation, templates, and Copilot instructions.
+
+- Keep required checks and matrix in workflow files only.
+- Keep instruction docs long-lived (no mutable values).
+- Treat workflow/job renames as breaking for tooling; change only intentionally.
+- When CI behavior changes, align contributor-facing docs.

.github/copilot-instructions.md

@@ -0,0 +1,23 @@
+# GitHub Copilot Instructions — ScalableVectorSearch
+
+This file is the canonical instruction set for Copilot behavior in this repository
+(required flow, precedence, and fallback rules).
+
+`AGENTS.md` is reserved for AGENTS-aware tooling context and should not duplicate
+Copilot policy text.
+
+## Mandatory
+1. Read root `AGENTS.md` first.
+2. Read the nearest directory `AGENTS.md` for edited files.
+3. If multiple apply, use the most specific.
+
+## Authoring rules
+- Keep suggestions minimal and scoped.
+- Use source-of-truth files for mutable details.
+- Do not invent or hardcode versions/flags/matrices.
+
+## Source-of-truth files
+- `CMakeLists.txt`, `cmake/*.cmake`
+- `.github/workflows/`
+- `.clang-format`, `.pre-commit-config.yaml`
+- `include/svs/`, `bindings/python/`

.github/instructions/build-system.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: "{CMakeLists.txt,cmake/**}"
+---
+
+# Build System Instructions for GitHub Copilot
+
+- Use existing option/target patterns; avoid introducing parallel build paths.
+- Keep configuration values referenced from existing CMake modules.
+- Do not hardcode versions/toolchain assumptions in instructions or comments.
+- For behavior changes, suggest updating/validating CI workflows in `.github/workflows/`.

.github/instructions/testing.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: "tests/**"
+---
+
+# Testing Instructions for GitHub Copilot
+
+- Add regression tests for bug fixes.
+- Keep tests deterministic and scoped to changed behavior.
+- Prefer smallest test surface that proves correctness.
+- Refer to repository test/build configuration as source of truth rather than duplicating values.

AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md
+
+This file is for AGENTS-aware tools.
+
+Scope:
+- Tool-specific guidance for AGENTS-aware agents.
+- Repository context that is not Copilot-specific.
+
+For Copilot policy (required flow, source-of-truth, fallback rules), see:
+- `.github/copilot-instructions.md` (canonical for Copilot behavior)
+
+Do not duplicate Copilot policy here.

benchmark/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — benchmark/
+
+Benchmark harness and performance-eval code.
+
+- Keep runs reproducible (inputs/config in repo).
+- Separate harness changes from algorithm changes when possible.
+- If shared with tests, validate impacted test targets.

bindings/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — bindings/
+
+Interop layer between core C++ and exposed APIs.
+
+- Read: `bindings/cpp/AGENTS.md`, `bindings/python/AGENTS.md`.
+- Keep contracts aligned with `include/svs/`.
+- Make ownership/lifetime explicit across boundaries.
+- Pair behavior/signature changes with tests (and examples when user-facing).

bindings/cpp/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — bindings/cpp/
+
+C++ binding/demo integration code.
+
+- `include/svs/` is API authority.
+- Avoid parallel abstractions that drift from core API.
+- Call out ABI-facing changes in PR notes.

bindings/python/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — bindings/python/
+
+Python package, extension bindings, and Python-facing behavior.
+
+- Source of truth: files under `bindings/python/` (+ cross-check with `CMakeLists.txt`).
+- Keep API compatibility by default.
+- Preserve clear dtype/shape validation and error messages.
+- Add tests for every user-visible behavior change.

cmake/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — cmake/
+
+Build modules, dependency wiring, and feature toggles.
+
+- `CMakeLists.txt` + `cmake/*.cmake` are authoritative.
+- Keep option names/defaults stable unless task requires change.
+- Prefer additive options over rewrites.
+- Validate option/target changes against CI workflows.

examples/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — examples/
+
+User-facing C++/Python examples.
+
+- Keep examples runnable and minimal.
+- Prefer clarity over micro-optimization.
+- Update examples when public APIs change.
+- Do not embed mutable version/environment details.

include/svs/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — include/svs/
+
+Public C++ headers and API contracts.
+
+- Backward compatibility is default.
+- Prefer additive API evolution.
+- Keep headers self-contained and aligned with CMake C++ standard.
+- Pair public API changes with tests and docs.

tests/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — tests/
+
+Unit/integration/benchmark-adjacent tests.
+
+- Add regressions for bug fixes.
+- Keep tests deterministic and scoped.
+- Match test scope to changed surface area.
+- Gate assertions for arch/feature-specific behavior.

tools/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — tools/
+
+Developer and maintenance tools/scripts.
+
+- Keep tools deterministic and automation-friendly.
+- Avoid local-machine assumptions.
+- If outputs feed tests/benchmarks, preserve output contract.

utils/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — utils/
+
+Utility binaries/helpers for benchmarking and characterization.
+
+- Keep behavior explicit (comments/CLI help).
+- Keep utility code separate from core library logic.
+- Preserve output format when consumed by scripts.