docs(observability): document the dashboards, alerts and local stack

.ai/base.md

@@ -27,6 +27,7 @@ Understand the intended design first:
 - `docs/cli.md` — the `ocf` scaffolding CLI, its flags, and what the generated code contains
 - `docs/guidelines.md` — best practices for structuring operators (desired state, one component per condition, etc.)
 - `docs/compatibility.md` — supported version combinations and compatibility policy
+- `docs/observability.md` — Grafana dashboards, Prometheus alert rules, the render pipeline and the local stack
 
 ### Source to read
 
@@ -47,6 +48,7 @@ Verify the real API before using or documenting it. Key packages:
 - `pkg/metrics/` — Prometheus implementation of `component.MetricsRecorder`: condition metrics plus the per-resource
   apply counters
 - `pkg/testing/` — testing utilities (`golden/` for snapshot tests, `integration/` for integration helpers)
+- `observability/` — dashboard and alert templates, the dev stack and simulator, and the template lint test
 
 When changing a public API, also check `examples/` for real usage patterns and to identify what else needs updating.
 
@@ -96,17 +98,18 @@ semantics. GoDoc is part of the public API surface.
 
 Update documentation in the **same response** as the code change — never leave them out of sync.
 
-| Code area changed                                 | Documentation to update                    |
-| ------------------------------------------------- | ------------------------------------------ |
-| Component builder, reconciliation, status model   | `docs/component.md`                        |
-| Primitives, field application, editors, selectors | `docs/primitives.md`                       |
-| Primitive implementations                         | `docs/primitives/*.md`                     |
-| Generic building blocks, custom resource wrappers | `docs/custom-resource.md`                  |
-| Wrapper templates, CLI flags                      | `docs/cli.md`                              |
-| Operator structuring patterns, best practices     | `docs/guidelines.md`                       |
-| Any `pkg/` export visible in the quick start      | `README.md`                                |
-| Examples                                          | `examples/*/README.md`                     |
-| Any file under `docs/` synced into the plugin     | Run `make sync-plugin` (CI fails on drift) |
+| Code area changed                                   | Documentation to update                    |
+| --------------------------------------------------- | ------------------------------------------ |
+| Component builder, reconciliation, status model     | `docs/component.md`                        |
+| Primitives, field application, editors, selectors   | `docs/primitives.md`                       |
+| Primitive implementations                           | `docs/primitives/*.md`                     |
+| Generic building blocks, custom resource wrappers   | `docs/custom-resource.md`                  |
+| Wrapper templates, CLI flags                        | `docs/cli.md`                              |
+| Operator structuring patterns, best practices       | `docs/guidelines.md`                       |
+| Dashboards, alert rules, render pipeline, dev stack | `docs/observability.md`                    |
+| Any `pkg/` export visible in the quick start        | `README.md`                                |
+| Examples                                            | `examples/*/README.md`                     |
+| Any file under `docs/` synced into the plugin       | Run `make sync-plugin` (CI fails on drift) |
 
 When updating documentation in markdown files, make sure to run `make fmt-md` for consistent formatting.
 

Makefile

@@ -105,6 +105,7 @@ sync-plugin: ## Sync framework docs into the Claude plugin skill references.
 		$(PLUGIN_SKILLS)/structuring-operators/references \
 		$(PLUGIN_SKILLS)/testing-operators/references
 	cp docs/component.md $(PLUGIN_SKILLS)/building-components/references/component.md
+	cp docs/observability.md $(PLUGIN_SKILLS)/building-components/references/observability.md
 	cp docs/primitives.md $(PLUGIN_SKILLS)/using-primitives/references/primitives.md
 	cp docs/primitives/*.md $(PLUGIN_SKILLS)/using-primitives/references/primitives/
 	cp docs/custom-resource.md $(PLUGIN_SKILLS)/custom-resource-wrappers/references/custom-resource.md

README.md

@@ -115,6 +115,7 @@ Full documentation, including a step-by-step tutorial, is at
 | [CLI](https://sourcehawk.github.io/operator-component-framework/cli/)                          | Scaffold wrapper packages with `ocf scaffold wrapper`        |
 | [Guidelines](https://sourcehawk.github.io/operator-component-framework/guidelines/)            | Patterns for structuring operators well                      |
 | [Testing](https://sourcehawk.github.io/operator-component-framework/testing/)                  | Golden snapshots and version-matrix coverage                 |
+| [Observability](https://sourcehawk.github.io/operator-component-framework/observability/)      | Grafana dashboards and Prometheus alerts for your operator   |
 | [Compatibility](https://sourcehawk.github.io/operator-component-framework/compatibility/)      | Supported Kubernetes and controller-runtime versions         |
 
 The full Go API reference is on [pkg.go.dev](https://pkg.go.dev/github.com/sourcehawk/operator-component-framework).

docs/component.md

@@ -842,12 +842,15 @@ func init() {
 
 recCtx := component.ReconcileContext{
     // ...
-    Metrics: metrics.NewRecorder("webapp-controller", conditions, collectors),
+    Metrics: metrics.NewRecorder("webapp", conditions, collectors),
 }
 ```
 
-The controller name becomes the `controller` label on every series the recorder emits. Passing `nil` for either
-collector disables that family; passing `nil` for `Metrics` itself disables both.
+The controller name becomes the `controller` label on every series the recorder emits. It must match the
+controller-runtime controller name (the lower-cased kind passed to `For`, unless `Named` overrides it) so that the
+shipped [dashboards and alerts](observability.md) correlate the framework's series with controller-runtime's reconcile
+and workqueue series. Passing `nil` for either collector disables that family; passing `nil` for `Metrics` itself
+disables both.
 
 ### Resource metrics
 

docs/index.md

@@ -33,6 +33,10 @@ New to the framework? Start with **Getting Started**. Already building and looki
 
     Golden snapshots and version-matrix golden generation.
 
+- :material-chart-line: **[Observability](observability.md)**
+
+    Grafana dashboards and Prometheus alerts for your operator.
+
 </div>
 
 ## Why this exists