feat: lint undocumented telemetry

.github/skills/azd-preflight/SKILL.md

@@ -24,7 +24,7 @@ Runs the full azd preflight suite and auto-fixes failures.
 
 ## Overview
 
-The azd preflight suite (`mage preflight`) validates code quality across 9 checks before
+The azd preflight suite (`mage preflight`) validates code quality across 10 checks before
 changes are submitted. This skill runs the suite, parses failures, applies automated fixes,
 and re-runs until all checks pass — or escalates to the user when a fix requires human judgment.
 
@@ -36,7 +36,7 @@ and re-runs until all checks pass — or escalates to the user when a fix requir
 
 ## Exit Criteria
 
-- All 9 preflight checks pass (or user explicitly chose to skip specific checks)
+- All 10 preflight checks pass (or user explicitly chose to skip specific checks)
 - Every changed `CHANGELOG.md` passes its targeted spell check
 - All auto-applied fixes are saved to disk (not staged or committed — the user decides when to commit)
 - A clear summary of what passed, what was fixed, and what was skipped is displayed

.github/skills/azd-preflight/references/fix-strategies.md

@@ -1,7 +1,7 @@
 # Fix Strategies
 
 Detailed fix procedures for each preflight check failure. Process checks in
-their original order (1-9) because earlier fixes can resolve later failures.
+their original order (1-10) because earlier fixes can resolve later failures.
 
 ## Formatting (`gofmt`) — Auto-fix
 
@@ -45,6 +45,18 @@ For each finding:
 
 If a lint finding is ambiguous or the fix would change behavior, ask the user via `ask_user`.
 
+## Telemetry Documentation (`telemetrylint`) — Analyze and Fix
+
+Run the checker to get the source location and missing document:
+
+```bash
+cd cli/azd && go run ./tools/telemetrylint 2>&1
+```
+
+Add each missing core event or field to both telemetry reference documents.
+Add each missing extension event or field to Markdown in that extension's
+directory. Re-run the checker after updating the documentation.
+
 ## Go Spell Check (`cspell`) — Analyze and Fix
 
 Re-run the Go source spell check to get the specific unknown words:

.github/skills/azd-preflight/references/output-and-errors.md

@@ -5,12 +5,13 @@
 ### Success
 
 ```
-Preflight passed — all 9 checks clean.
+Preflight passed — all 10 checks clean.
 
   ✓ gofmt
   ✓ go fix
   ✓ copyright
   ✓ lint
+  ✓ telemetry docs
   ✓ cspell
   ✓ cspell-misc
   ✓ build
@@ -29,6 +30,7 @@ Preflight passed after fixes.
   ✓ go fix (fixed: 2 modernizations applied)
   ✓ copyright (no issues)
   ✓ lint (fixed: 5 findings resolved)
+  ✓ telemetry docs (fixed: missing entries added)
   ✓ cspell (fixed: 1 word added to dictionary)
   ✓ cspell-misc (no issues)
   ✓ build (no issues)
@@ -42,12 +44,13 @@ Files modified: {list of changed files}
 ### Partial Success
 
 ```
-Preflight partially passed — {N} of 9 checks clean, {M} skipped.
+Preflight partially passed — {N} of 10 checks clean, {M} skipped.
 
   ✓ gofmt
   ✓ go fix
   ✓ copyright
   ✓ lint
+  ✓ telemetry docs
   ✓ cspell
   ✓ cspell-misc
   ✓ build

.github/skills/azd-preflight/references/preflight-checks.md

@@ -1,6 +1,6 @@
 # Preflight Checks Reference
 
-The `mage preflight` command runs these 9 checks in order. Each check, its
+The `mage preflight` command runs these 10 checks in order. Each check, its
 purpose, and the automated fix strategy are listed below.
 
 ## 1. Formatting (`gofmt`)
@@ -33,23 +33,33 @@ issues include:
 - `unused` — remove dead code
 - `staticcheck` — fix static analysis warnings
 
-## 5. Go Spell Check (`cspell`)
+## 5. Telemetry Documentation (`telemetrylint`)
+
+**Command**: `go run ./tools/telemetrylint` (from `cli/azd/`)
+
+**Passes when**: Every core event and field appears in both telemetry
+reference documents, and static extension usage items appear in extension
+Markdown documentation.
+
+**Auto-fix**: Add the missing event or field to the relevant documentation.
+
+## 6. Go Spell Check (`cspell`)
 
 **Command**: `cspell lint "**/*.go" --relative --config ./.vscode/cspell.yaml --no-progress` (from `cli/azd/`)
 **Passes when**: No unknown words found.
 **Auto-fix**: For legitimate technical terms, add them to `cli/azd/.vscode/cspell.yaml`
 using file-scoped `overrides` entries (not the global `words` list). For actual
 typos, fix the spelling in source code.
 
-## 6. Misc/Docs Spell Check (`cspell-misc`)
+## 7. Misc/Docs Spell Check (`cspell-misc`)
 
 **Command**: `cspell lint "**/*" --relative --config ./.vscode/cspell.misc.yaml --no-progress`
 (from the repository root)
 **Passes when**: No unknown words are found in miscellaneous and documentation files.
 **Auto-fix**: Fix typos. Add legitimate terms to file-scoped `overrides` entries in
 `.vscode/cspell.misc.yaml`.
 
-## 7. Build (`go build`)
+## 8. Build (`go build`)
 
 **Command**: `go build ./...` (from `cli/azd/`)
 **Passes when**: Compilation succeeds with zero errors.
@@ -59,14 +69,14 @@ typos, fix the spelling in source code.
 - Undefined symbols
 - Syntax errors
 
-## 8. Unit Tests (`go test -short`)
+## 9. Unit Tests (`go test -short`)
 
 **Command**: `go test ./... -short -cover -count=1` (from `cli/azd/`)
 **Passes when**: All tests pass.
 **Auto-fix**: Analyze test failures and fix the root cause in source code or
 tests. Do NOT skip or delete failing tests — fix them.
 
-## 9. Playback Tests (Functional)
+## 10. Playback Tests (Functional)
 
 **Command**: Discovers test recordings in `test/functional/testdata/recordings/`
 and runs matching functional tests with `AZURE_RECORD_MODE=playback`.

.github/skills/azd-preflight/references/workflow.md

@@ -42,7 +42,7 @@ Run this targeted check from the repository root:
 cspell lint "<changelog-path>" --relative --config "<cspell-config>" --no-progress
 ```
 
-Capture these results separately from the nine `mage preflight` checks. This conditional check is
+Capture these results separately from the ten `mage preflight` checks. This conditional check is
 required because the repository-wide misc config excludes directories that have their own cspell
 configuration, including `cli/`.
 
@@ -70,10 +70,10 @@ Also parse the targeted changelog spell-check results when changed changelogs we
 ### Step 4 — Fix Failures (Iterative)
 
 For each failing check, apply the fix strategy from the references. Process checks in
-their original order (1-9) because earlier fixes can resolve later failures (e.g., `gofmt`
+their original order (1-10) because earlier fixes can resolve later failures (e.g., `gofmt`
 fixes may resolve `lint` issues, `build` fixes resolve `test` failures).
 
-After the nine standard checks, fix any targeted changelog spelling failures.
+After the ten standard checks, fix any targeted changelog spelling failures.
 
 {{ references/fix-strategies.md }}
 
@@ -91,7 +91,7 @@ Re-run the targeted spell check for every changed changelog.
 
 **If failures remain**: Return to Step 4 for the remaining failures. This is an iterative
 loop — continue until either:
-- All 9 checks and every changed changelog pass, OR
+- All 10 checks and every changed changelog pass, OR
 - 3 full cycles have been attempted without progress on a specific check
 
 ### Step 6 — Escalate if Stuck

.github/workflows/telemetry-docs.yml

@@ -0,0 +1,25 @@
+name: telemetry-docs
+
+on:
+  pull_request:
+    paths:
+      - "cli/azd/**"
+      - "docs/reference/telemetry-data.md"
+      - "docs/specs/metrics-audit/telemetry-schema.md"
+      - ".github/workflows/telemetry-docs.yml"
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: cli/azd/go.mod
+      - name: Check telemetry documentation
+        working-directory: cli/azd
+        run: go run ./tools/telemetrylint

.vscode/cspell.misc.yaml

@@ -47,6 +47,7 @@ overrides:
           - exegraph
           - pseudonymizing
           - pulumi
+          - telemetrylint
     - filename: ./README.md
       words:
           - VSIX

cli/azd/.vscode/cspell.yaml

@@ -376,6 +376,13 @@ overrides:
       - Logf
       - Getenv
       - httptest
+  - filename: magefile.go
+    words:
+      - telemetrylint
+  - filename: tools/telemetrylint/**
+    words:
+      - Elts
+      - telemetrylint
   - filename: docs/extensions/extension-framework.md
     words:
       - invopop

cli/azd/docs/tracing-in-azd.md

@@ -71,6 +71,26 @@ tracing.SetUsageAttributes(fields.EnvName.StringHashed(envName))
 
 This example sets a usage attribute to be included in the root command event.
 
+### 4. Update the telemetry documentation
+
+Add every new event and attribute key to both the
+[public telemetry reference](../../../docs/reference/telemetry-data.md) and
+the [metrics audit schema](../../../docs/specs/metrics-audit/telemetry-schema.md).
+For extension usage events, document the event and each fixed attribute in
+the extension's README or another Markdown file in the extension directory.
+
+Run the completeness checker from `cli/azd`:
+
+```bash
+go run ./tools/telemetrylint
+```
+
+The checker reads the event and field declarations, scans static
+`tracing.Start` and `attribute.*` literals, and checks static extension
+`ReportUsageRequest` values. It understands the documented `cmd.`, `mcp.`,
+and `vsrpc.` prefixes, but dynamic extension keys cannot be enumerated and
+must be documented by the extension author.
+
 ---
 
 ## Existing Event Taxonomy

cli/azd/extensions/microsoft.azd.demo/README.md

@@ -138,6 +138,11 @@ The `telemetry` command demonstrates the telemetry service, which lets an extens
 
 The command reports a single `demo.telemetry.reported` event with two fixed, low-cardinality attributes and prints whether the host recorded it.
 
+The attributes are:
+
+- `demo.mode`: the fixed demo mode, currently `safe`
+- `demo.outcome`: whether the demo telemetry call was `accepted` or `dropped`
+
 This example shows two things:
 
 - **Every value is a fixed enum.** Resource names, paths, prompts, and anything a user typed are customer content and must never be sent.

cli/azd/magefile.go

@@ -159,6 +159,7 @@ func Preflight() error {
 		checkGoFix
 		checkCopyright
 		checkLint
+		checkTelemetryDocs
 		checkCspell
 		checkCspellMisc
 		checkBuild
@@ -167,7 +168,7 @@ func Preflight() error {
 		numChecks
 	)
 	checkNames := [numChecks]string{
-		"gofmt", "go fix", "copyright", "lint",
+		"gofmt", "go fix", "copyright", "lint", "telemetry docs",
 		"cspell", "cspell-misc", "build", "test", "playback tests",
 	}
 
@@ -269,7 +270,22 @@ func Preflight() error {
 		printResult(checkLint)
 	})
 
-	// 5a. cspell (Go source)
+	// 5. Telemetry documentation
+	wg.Go(func() {
+		out, err := runCaptureAll(
+			azdDir, nil, "go", "run", "./tools/telemetrylint",
+		)
+		if err != nil {
+			results[checkTelemetryDocs] = checkResult{
+				"fail", err.Error(), out,
+			}
+		} else {
+			results[checkTelemetryDocs] = checkResult{"pass", "", out}
+		}
+		printResult(checkTelemetryDocs)
+	})
+
+	// 6a. cspell (Go source)
 	wg.Go(func() {
 		out, err := runCaptureAll(azdDir, nil,
 			"cspell", "lint", "**/*.go",
@@ -282,7 +298,7 @@ func Preflight() error {
 		printResult(checkCspell)
 	})
 
-	// 5b. cspell (misc/docs)
+	// 6b. cspell (misc/docs)
 	wg.Go(func() {
 		out, err := runCaptureAll(repoRoot, nil,
 			"cspell", "lint", "**/*",
@@ -295,7 +311,7 @@ func Preflight() error {
 		printResult(checkCspellMisc)
 	})
 
-	// 6. go build — compile all packages AND pre-build the azd + azd-record
+	// 7. go build — compile all packages AND pre-build the azd + azd-record
 	// binaries so that Wave 2 tests can skip auto-building. This lets unit
 	// tests and playback tests run in parallel safely.
 	wg.Go(func() {
@@ -351,7 +367,7 @@ func Preflight() error {
 		skipBuildEnv := []string{"CLI_TEST_SKIP_BUILD=true"}
 		var wg2 sync.WaitGroup
 
-		// 7. Unit tests
+		// 8. Unit tests
 		wg2.Go(func() {
 			if err := runStreamingWithEnv(
 				azdDir, skipBuildEnv,
@@ -364,7 +380,7 @@ func Preflight() error {
 			printResult(checkTest)
 		})
 
-		// 8. Playback tests
+		// 9. Playback tests
 		wg2.Go(func() {
 			if err := runFunctionalTests(azdDir, testRunOpts{
 				mode: "playback",