fix(examples): with-telemetry.yaml -> RFC-0013 successor components (#454)

[trilamsr]

Summary

docs/examples/with-telemetry.yaml failed tracecore validate against the OCB binary because it referenced components and a config shape retired by RFC-0013:

'receivers' unknown type: "clockreceiver"
'exporters' unknown type: "stdoutexporter"
'' has invalid keys: telemetry

Swapped to the canonical post-pivot shape, matching docs/getting-started.md and the in-repo Helm chart default:

• hostmetrics (load scraper @ 1s) replaces clockreceiver. Note: telemetrygeneratorreceiver does not exist in opentelemetry-collector-contrib (RFC-0013 PR-E; upstream contrib issues #41687 and #43657 both closed not_planned). hostmetrics is the actual successor.
• debug (verbosity: detailed) replaces stdoutexporter.
• service.telemetry.metrics.readers.pull.exporter.prometheus.{host,port} replaces the legacy top-level telemetry: block (gone in PR-A2).
• healthcheckextension at :13133/ carries liveness + readiness (the legacy block's healthz/readyz paths) via service.extensions.

Root cause

Two layers:

1. Direct: RFC-0013 PR-A2 + PR-E retired clockreceiver and stdoutexporter and folded the top-level telemetry: block into upstream service.telemetry; the operator example was not migrated.
2. Why it drifted undetected: scripts/validator-recipe.sh only walks docs/integrations/*.md; docs/examples/ has no CI gate, so the file stayed broken on main until PR docs(integrations): add trust-posture callout to 11 recipes (#443) #453 reviewer noticed.

A follow-up to add a docs/examples/*.yaml validate sweep to make validator-recipe (or a sibling validator-examples target) is the right structural fix. I'd file it as a separate issue if reviewer agrees the scope is correct.

A+ sweep finding

Scanned all repo YAMLs for the retired symbols. One additional broken example surfaced: module/receiver/ncclfrreceiver/example_config.yaml still references stdoutexporter, and its README invokes the retired tracecore collect subcommand. Filed as #457 (out of scope for #454).

docs/examples/prometheus-alerts.example.yaml mentions stdoutexporter in a regex-example comment string, but the file is a Prometheus rules file (not a collector config) and structurally validates fine. Noted in #457.

Verification

$ ./_build/tracecore validate --config=docs/examples/with-telemetry.yaml
# (was exit 1 pre-fix; now exit 0)

$ make validator-recipe
validator-recipe: 14 validated, 3 skipped (non-linux host) of 12 recipe(s)
PASS test 1..5; validator-recipe_test: all assertions passed

$ make smoke-quickstart
smoke-quickstart: validated 2 YAML payload(s) and shell-syntax-checked 8 shell block(s) across 2 quickstart doc(s)

Pre-commit gates (DCO, AI-trailer, golangci-lint, go vet, go mod verify, attribute-namespace-check) all passed.

Test plan

• ./_build/tracecore validate --config=docs/examples/with-telemetry.yaml exits 0 (was 1)
• make validator-recipe passes (sibling-example sanity)
• make smoke-quickstart passes (quickstart doc sanity)
• A+ sweep across **/*.{yaml,yml} for clockreceiver|stdoutexporter|telemetrygeneratorreceiver; fix(examples): module/receiver/ncclfrreceiver/example_config.yaml references retired stdoutexporter + tracecore collect subcommand (RFC-0013 cleanup) #457 filed

docs(examples): fix with-telemetry.yaml so it validates against the OCB-assembled tracecore binary. Swap retired clockreceiver / stdoutexporter / top-level telemetry: block for hostmetrics + debug + service.telemetry + healthcheckextension per RFC-0013.

Closes #454.

[trilamsr]

Independent Adversarial Review — PR #458

B/A/A+ Criteria

• RFC-0013 compliance: all sections (§2, §3, §4, PR-A2, PR-E)
• Operator usability: invocation, test URLs, feature toggles documented
• Correctness: YAML syntax, component presence, no orphaned keys
• Scope discipline: tight to fix(examples): with-telemetry.yaml references retired clockreceiver + stdoutexporter (RFC-0013 cleanup) #454, fix(examples): module/receiver/ncclfrreceiver/example_config.yaml references retired stdoutexporter + tracecore collect subcommand (RFC-0013 cleanup) #457 properly deferred

Findings

No issues. All specific probes verified:

1. clockreceiver → hostmetrics: RFC-0013 PR-E successor confirmed. telemetrygeneratorreceiver mythical per upstream #41687/#43657 (both closed not_planned). Matches docs/getting-started.md + Helm chart defaults.

2. stdoutexporter → debug: RFC-0013 PR-A2 successor confirmed. verbosity: detailed is valid OTel level.

3. telemetry: block → service.telemetry.metrics.readers: RFC-0013 §4 upstream adoption. Host/port defaults preserved. otelcol_* metric names per contract §3.

4. healthcheckextension addition: RFC-0013 §2 adoption matrix official. Not scope creep — replaces legacy /healthz and /readyz paths with upstream extension's automatic /livez and /readyz subpaths. Parity, not addition. Already documented in docs/integrations/k8sobjects-events.md. Extension bundled in builder-config.yaml line 66.

5. Comment density: ~24 load-bearing comment lines (up from ~12). No bloat — each comment addresses a real operator question (how to run, test, toggle optional features, migration path). M2 reference correctly removed.

6. Component availability: hostmetrics ✓ (builder-config.yaml:28), debug ✓ (line 60), health_check ✓ (line 66).

7. Service.extensions wiring: Correct reference to defined extension key.

8. Invocation command: ./_build/tracecore --config=… correct per PR-A2; matches docs/getting-started.md.

Simplification Sweep

Comments: All load-bearing. No simplification without losing operator clarity.

Configuration: Minimal. No redundant keys.

Verdict

GRADE: A+

• RFC-0013 compliance: complete ✓
• Correctness: verified ✓
• Operator clarity: improved ✓
• Scope discipline: tight ✓

Ready to merge. No blockers.