chore(config): consolidate config maintenance to schema_overlay.yaml

.claude/skills/config-management/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: config-management
+description: >
+  How to manage Datadog Agent configuration inventory in this repo. A single hand-written YAML
+  overlay is the source of truth; Rust code and Markdown documentation are generated from it at
+  build time. Trigger: adding/removing/reclassifying a config key, changing support level or
+  pipeline attribution, editing the vendored schema, fixing errors in generated files, or
+  build.rs panics with an overlay validation message.
+disable-model-invocation: false
+---
+
+# /config-management
+
+## Mental model
+
+There is one place where config metadata is hand-edited, and everything else flows from it via
+`build.rs` code:
+
+```
+                         ┌──────────────────────────┐
+  vendored, untouched →  │ schema/core_schema.yaml  │
+                         └────────────┬─────────────┘
+                                      │
+                         ┌────────────┴──────────────┐
+  hand-edited (SoT)  →   │ schema/schema_overlay.yaml│
+                         └────────────┬──────────────┘
+                                      │
+                     ┌────────────────┼─────────────────┐
+     config/build.rs │                │                 │ config-testsupport/build.rs
+                     ▼                │                 ▼
+                   PROD               │             TEST/DOC
+              generated Rust:         │          generated Rust:    generated Markdown:
+              classifier data,        │          config_registry    configuration docs
+              slim entry table        │          annotations        (via .md.tmpl)
+                                      │
+                         config-overlay-model crate:
+                         overlay types, schema_gen, saluki_keys
+                         (shared build-dep for both build.rs files)
+```
+
+Doc generation lives in `config-testsupport/build.rs`, not `config/build.rs`, because it is a
+dev/CI concern — not a prod build artifact. The generated `dogstatsd.md` is written in-tree by
+the testsupport build and checked for staleness in CI.
+
+The overlay partitions every key in `core_schema.yaml` into exactly one section: `supported`,
+`unsupported`, `investigate`, or `ignored`. The model for those sections lives in the
+`config-overlay-model` crate; read its `lib.rs` when you need the exact field shape — the doc
+comments on the structs are authoritative.
+
+## The cardinal rule
+
+Generated files are output, not source. They have a header like
+`// @generated by build.rs from ... — DO NOT EDIT`.
+
+If you see a clippy warning, rustfmt diff, doc-lint error, missing key, or wrong field value in a
+generated file, find the upstream source and fix it there.
+
+The four upstream sources, in rough order of how often you'll touch them:
+
+1. `schema_overlay.yaml` — per-key support level, pipelines, descriptions, prose documentation,
+   env-var overrides, aliases, smoke-test JSON, etc.
+2. The Markdown template (`*.md.tmpl` next to or above the generated `.md`) — prose layout, section
+   headers, table columns, top-of-file matter.
+3. The generators — code that turns overlay+schema into Rust and Markdown. Edit these when the
+   shape of generated output needs to change, not the data.
+    - `config-overlay-model/src/schema_gen.rs`, `saluki_keys.rs` — shared build utilities
+    - `config/build/classifier_gen.rs` — prod classifier generation
+    - `config-testsupport/build/registry_gen.rs`, `doc_gen.rs` — test annotations + doc generation
+4. `core_schema.yaml` — only when vendoring an updated schema from upstream Datadog. The overlay
+   validator rejects keys not in the schema, so new keys must be added here first.
+
+`saluki_keys.rs` lists ADP-only keys that don't exist in the vendored schema. Treat it as an
+extension of the overlay for those keys — same review rules apply.
+
+## Common task: add or change a key
+
+1. Find the key in `schema_overlay.yaml`. Section order is enforced (`supported`, `unsupported`,
+   optional `investigate`, `ignored`) and keys within a section are alphabetical. The build will
+   tell you if you violate this.
+2. Make the edit. Required fields differ per section; the overlay-model `lib.rs` is the
+   authoritative reference. Common gotchas:
+    - `supported` requires non-empty `used_by` and `pipelines`; `description` ≤ 50 chars.
+    - `unsupported` with `planned: true` requires an `issue`.
+    - Multi-line `documentation` strings render as prose blocks below tables; single-line ones
+      render
+      inside tables.
+3. Build: `cargo build -p datadog-agent-config-testsupport` exercises both `build.rs` files and
+   performs all overlay validation up front. Read the panic message — it names the rule and the
+   offending key.
+4. Inspect the regenerated outputs (under `config-testsupport/.../config_registry/` and
+   `docs/agent-data-plane/configuration/`). Spot-check the diff; commit it alongside the overlay
+   change.
+
+## Common task: clippy / fmt / doc-lint failure in a generated file
+
+1. Confirm it's generated: look for the `@generated by build.rs` header.
+2. Decide whether the fix belongs in the data (overlay) or the shape (generator/template):
+    - Wrong description, wrong pipelines, missing entry, wrong support level → overlay.
+    - Whitespace, table formatting, section ordering, comment headers, import lines, codegen
+      macros →
+      generator code in `config/build/` or `config-testsupport/build/`.
+    - Prose surrounding generated tables in a `.md` → the corresponding `.md.tmpl`.
+
+## Common task: bumping the vendored schema
+
+Replace `core_schema.yaml`. The build will fail listing schema keys out of alignment with the
+overlay. Add each new key to the appropriate overlay section (`investigate` is the correct holding
+pen when uncertain — never silently classify a key as `ignored` or `supported` without human
+review).
+
+## Finding things
+
+Prefer search over hard-coded paths because pieces of this system rename more than usual:
+
+- Overlay file: `find lib -name schema_overlay.yaml`
+- Prod generator: `ls lib/datadog-agent/config/build/` (classifier only)
+- Test/doc generators: `ls lib/datadog-agent/config-testsupport/build/`
+- Doc template: `find docs -name '*.md.tmpl'`
+- Overlay model + shared build utilities: the `config-overlay-model` crate
+  (`schema_gen.rs`, `saluki_keys.rs` live here as public modules)
+- Saluki-only keys: `config-overlay-model/src/saluki_keys.rs`
+
+## Self-healing
+
+If you hit any of the following, propose an edit to this `SKILL.md` before continuing:
+
+- A path here doesn't exist or has moved.
+- You needed multiple `find`/`grep` calls to locate something this skill should point to directly.
+- A recipe led you wrong.
+- A new generator, template, or artifact exists but isn't mentioned.
+- The cardinal rule has a new exception.
+
+Keep edits conceptual — exact paths churn, the data-flow shape is stable.

.claude/skills/confkey/README.md

@@ -1,86 +1,48 @@
-# Config Skill
+# confkey Skill
 
-Tracks configuration key parity between the Datadog Agent and ADP's DogStatsD implementation.
-Maintains two ledger files and a documentation page:
-
-- `docs/agent-data-plane/configuration/dogstatsd.md` — the doc
-- `docs/agent-data-plane/configuration/dogstatsd/known-configs.json` — classified keys
-- `docs/agent-data-plane/configuration/dogstatsd/known-configs-not-applicable.json` — dismissed keys
+Workflows for analyzing individual configuration keys (ConfKeys) for parity between the Datadog
+Agent and ADP's DogStatsD implementation. Classification state lives in `schema_overlay.yaml` — see
+the `/config-management` skill for the full data model.
 
 Glossary:
 - **ConfKey** — a config key used by the Agent, ADP, or both.
 - **FeatureState** — implementation reality: `PARITY`, `MISSING`, `DIVERGENT`, `ADP_ONLY`,
   `NOT_APPLICABLE`, `UNKNOWN`.
-- **Action** — what to do: `NONE`, `IMPLEMENT`, `DOCUMENT`, `DOCUMENTED`, `INVESTIGATE`.
 
 * * *
 
 ## Modes
 
-### `audit-all`
-
-Full sweep. Discovers all ConfKeys in both codebases, classifies any unreviewed ones, re-analyzes
-parity for non-final keys, and updates the doc.
-
-```
-/confkey audit-all
-```
-
-Runs a multi-step workflow with user gates at each phase. Expect sub-agents and several
-AskUserQuestion prompts. Use when starting fresh or when the ledger may have drifted.
-
-* * *
+### `audit <key> [key ...]`
 
-### `audit-one <key>`
-
-Analyzes a single ConfKey via a clean-room sub-agent, shows you the result, and proposes ledger and
-doc updates.
+Analyzes one or more ConfKeys via a clean-room sub-agent — static code analysis of how each key is
+registered and used in both codebases. Shows you the result and proposes overlay updates (e.g.
+moving a key from `ignored` to `investigate`, opening an issue).
 
 ```
-/confkey audit-one dogstatsd_port
-/confkey audit-one dogstatsd_buffer_size -- check if ADP default matches the agent
+/confkey audit dogstatsd_port
+/confkey audit dogstatsd_buffer_size -- check if ADP default matches the agent
 ```
 
-If the key is already in the ledger, shows a side-by-side comparison so you can confirm or correct
+If the key is already in the overlay, shows a side-by-side comparison so you can confirm or correct
 the existing classification.
 
 * * *
 
 ### `create-issue [key ...]`
 
-Drafts and files GitHub issues for keys that need attention. With no arguments, scans the ledger for
-keys where `action` is `IMPLEMENT`, `INVESTIGATE`, or `DOCUMENT` and no issue is linked yet.
+Drafts and files GitHub issues for keys that need attention. With no arguments, scans the overlay
+for keys in `unsupported` with `planned: true` and no issue yet, or keys in `investigate` with no
+linked issue.
 
 ```
 /confkey create-issue
 /confkey create-issue dogstatsd_buffer_size dogstatsd_packet_buffer_size
 ```
 
 Checks for duplicates, proposes groupings for related keys, iterates on drafts with you, offers to
-file with `gh`, and updates the `issue` field in the ledger.
-
-* * *
-
-### `complete-issue <number>`
-
-For when you've implemented a fix and are ready to close out the ledger. Reads the issue and diffs
-the branch against main to determine what actually changed, then proposes ledger and doc updates.
-
-```
-/confkey complete-issue 1234
-```
-
-Optionally runs a fresh parity analysis to confirm the implementation matches expectations before
-writing anything.
+file with `gh`, and updates the `issue` field in the overlay.
 
 * * *
 
-### `freeform <request>`
-
-Loads all mode and resource context, then executes whatever you ask. Use when you want to do
-something that doesn't fit the other modes — ad-hoc queries, bulk edits, cross-mode workflows.
 
-```
-/confkey freeform how many keys are still MISSING with no linked issue?
-/confkey freeform reclassify dogstatsd_origin_detection as DIVERGENT and update the doc
-```