From 28466ff2deed4754007bf0dac6e213ac6142e9ff Mon Sep 17 00:00:00 2001
From: Jon Langevin <codingsloth@pm.me>
Date: Sun, 24 May 2026 21:22:21 -0400
Subject: [PATCH] docs: add observability smoke example

---
 CLAUDE.md                                     |  5 +++
 README.md                                     | 37 +++++++++++++++++++
 docs/plans/2026-05-25-observability-plugin.md |  5 +++
 examples/external-collector/workflow.yaml     | 24 ++++++++++++
 4 files changed, 71 insertions(+)
 create mode 100644 README.md
 create mode 100644 examples/external-collector/workflow.yaml

diff --git a/CLAUDE.md b/CLAUDE.md
index 0d850a5..40b8151 100644
--- a/CLAUDE.md
+++ b/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
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..129ba13
--- /dev/null
+++ b/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.
diff --git a/docs/plans/2026-05-25-observability-plugin.md b/docs/plans/2026-05-25-observability-plugin.md
index c9fe63e..7f1c933 100644
--- a/docs/plans/2026-05-25-observability-plugin.md
+++ b/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.
diff --git a/examples/external-collector/workflow.yaml b/examples/external-collector/workflow.yaml
new file mode 100644
index 0000000..1ff8e7f
--- /dev/null
+++ b/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