docs: add observability smoke example

CLAUDE.md

@@ -32,6 +32,11 @@ GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build -ldflags="-s -w" -o workflow-plug
 3. Add to `plugin.json` capabilities.moduleTypes
 4. Add tests in `internal/module_example_test.go`
 
+Telemetry metric names are owned by the implementing application or domain
+module. Keep this generic plugin free of application-specific prefixes and
+assertions; tests here should verify routing, filtering, and rendering behavior
+without baking in app metric names.
+
 ## Adding a Step Type
 
 1. Create `internal/step_example.go` implementing the step

README.md

@@ -0,0 +1,37 @@
+# workflow-plugin-observability
+
+External Workflow plugin for OTel-first telemetry collection.
+
+## Modules
+
+- `observability.telemetry` receives neutral metrics, logs, and span events from Workflow's host-side telemetry bridge.
+- `observability.collector` validates collector intent, renders OTel Collector config, and returns app environment wiring.
+
+## Minimal External Collector
+
+```yaml
+modules:
+  - name: telemetry
+    type: observability.telemetry
+    config:
+      serviceName: checkout-api
+      environment: production
+
+  - name: collector
+    type: observability.collector
+    config:
+      distribution: external
+      topology: external
+      signals: [traces, metrics, logs]
+      endpoint: https://otel-collector.example.com:4318
+```
+
+OTel/OTLP is the preferred path for traces, metrics, and logs. Direct Grafana, Prometheus, Loki, and Datadog integrations are planned for backend-specific resources and runtime choices where OTel is not the best fit, such as dashboards, monitors, Loki push, Prometheus scrape/remote-write helpers, and Datadog Agent/DDOT deployment.
+
+## Custom Telemetry
+
+Applications and plugins emit telemetry by satisfying Workflow SDK interfaces, not by importing this plugin. Metric names belong to the implementing application or domain module; this plugin records and routes the names it receives without imposing prefixes.
+
+## Rollback
+
+Remove `observability.telemetry` and `observability.collector` from Workflow YAML and redeploy. Generated collector resources are labeled with `workflow.gocodealone.io/managed-by: workflow-plugin-observability` so provider adapters can roll back only resources owned by this plugin.

docs/plans/2026-05-25-observability-plugin.md

@@ -823,3 +823,8 @@ Expected:
 - All listed tests pass.
 - `workflow-plugin-cms` has no `/metrics` route or `monitoring` package.
 - New templates create `observability.telemetry`, not `metrics.collector`.
+
+Task 8 update: generic observability plugin docs and examples use
+application-neutral telemetry names. Concrete metric names are owned by the
+implementing application or plugin that satisfies the Workflow telemetry
+interfaces.

examples/external-collector/workflow.yaml

@@ -0,0 +1,24 @@
+modules:
+  - name: telemetry
+    type: observability.telemetry
+    config:
+      serviceName: checkout-api
+      environment: production
+      resource:
+        team: platform
+        app: checkout
+
+  - name: collector
+    type: observability.collector
+    config:
+      distribution: external
+      topology: external
+      signals: [traces, metrics, logs]
+      endpoint: https://otel-collector.example.com:4318
+
+# Expected application environment produced by the collector plan:
+# OTEL_SERVICE_NAME=collector
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
+# OTEL_TRACES_EXPORTER=otlp
+# OTEL_METRICS_EXPORTER=otlp
+# OTEL_LOGS_EXPORTER=otlp