feat: flatten platform on agent type definition schema (NR-568041) (#2572)

Author: gsanchezgavier

CHANGELOG.md

@@ -14,6 +14,11 @@ Remember that the keywords that you can use are the following:
 
 ## Unreleased
 
+### enhancement
+- Agent type definitions now use a flat per-platform schema (one YAML file per `(platform, operating_system)` pair). 
+  Agent type FQNs and configuration values are unchanged, so this is **not a breaking change** for end users.
+  Internal authors of custom agent type definitions need to migrate their YAMLs — see [docs/INTEGRATING_AGENTS.md](docs/INTEGRATING_AGENTS.md).
+
 ## v1.16.1 - 2026-06-04
 
 ### 🐞 Bug fixes

agent-control/agent-type-registry/README.md

@@ -3,21 +3,36 @@
 Any `*.yaml` file defined in this folder or any subfolder will be embedded into the agent control binary
 at compilation time. These files define the agent-type registry.
 
+Each YAML file describes a single agent type definition. The metadata declares a `platform`
+(`host` or `kubernetes`) and, when `platform: host`, also an `operating_system` (`linux` or
+`windows`). An agent that targets multiple host operating systems and/or kubernetes is split
+into one file per `(platform, operating_system)` pair, all sharing the same `namespace`,
+`name` and `version`. At startup, Agent Control loads only the definitions whose `platform`
+(and `operating_system`, when `platform: host`) match the binary it's running in: the on-host
+binary loads `host` definitions matching its OS, and the Kubernetes binary loads `kubernetes`
+definitions.
+
 ## Files organization recommendations
 
-The following structure is recommended:
+The following naming convention is recommended:
 
 ```
 agent-type-registry/
 ├─ namespace/
-│  ├─ agent_type_name-version.yaml
+│  ├─ <platform>[-<operating_system>]-<agent_type_name>-<version>.yaml
 ```
 
+For `platform: host`, the operating system (`linux` or `windows`) is included; for
+`platform: kubernetes` it is omitted.
+
 Example:
 
 ```
 agent-type-registry/
 ├─ newrelic/
-│  ├─ com.newrelic.infrastructure-0.1.0.yaml
-│  ├─ io-opentelemetry.collector-0.1.0.yaml
+│  ├─ kubernetes-com.newrelic.infrastructure-0.1.0.yaml
+│  ├─ host-linux-com.newrelic.infrastructure-0.1.0.yaml
+│  ├─ host-windows-com.newrelic.infrastructure-0.1.0.yaml
+│  ├─ kubernetes-io.opentelemetry.collector-0.1.0.yaml
+│  ├─ host-linux-io.opentelemetry.collector-0.1.0.yaml
 ```