docs: Replace examples in reference docs with links to task docs

.cursor/rules/component-reference-examples.mdc

@@ -0,0 +1,54 @@
+---
+description: >-
+  Component reference docs — prefer examples in task guides (monitor, tutorials,
+  collect); when reference Examples may include inline Alloy and when to link only.
+globs: docs/sources/reference/components/**/*.md
+alwaysApply: false
+---
+
+# Component reference: Examples sections
+
+**Prefer** end-to-end examples in **task-based** docs under `docs/sources/monitor/`, `docs/sources/tutorials/`, and `docs/sources/collect/`. Keep large **Examples** content in **reference** component pages **only when necessary**.
+
+## Default: Examples = links to task docs
+
+When the happy path is documented in a task guide, the reference page’s **Examples** section should usually be a **bullet list** of links to those guides:
+
+- Use the heading **`## Examples`** (plural) at **component** scope (near the end of the page, before **Compatible components** when present).
+- Each bullet is a **markdown link** whose **link text is the target page title** (that doc’s `title` in front matter or its primary heading).
+- Link **only** to pages under **`monitor/`**, **`tutorials/`**, or **`collect/`** — not to other reference components.
+- Use **relative** paths from the component file (for example `../../../monitor/...`, `../../../tutorials/...`, `../../../collect/...`).
+
+Do **not** list other **reference** components (for example `prometheus.scrape`, `loki.write`) in Examples; those belong in **Compatible components** or the task guide.
+
+## Task-doc bullets plus optional `#####` walkthrough
+
+When you need **both** pointers to task guides **and** a **concrete** multi-component or step-by-step example in the same **Examples** block:
+
+1. Put the **bullet list** of task-based doc links first (under **`## Examples`** or **`#### Examples`**).
+2. Add a **`#####`** subheading for each **standalone** walkthrough (name it after the scenario).
+3. Put Alloy blocks and explanatory text under that **`#####`**.
+
+Use this pattern wherever task-doc links should stay short but readers still need a detailed example in the reference. This can happen if the example currently presented in the reference doc would look out of place in the task based doc, or make it too cluttered.
+
+## Per-feature Examples (large multi-feature reference pages)
+
+Some component pages document **many** sub-features (for example individual **`stage.*`** blocks on `loki.process`, or **detector** blocks on `otelcol.processor.resourcedetection`). A single **`## Examples`** section at the **end** can be long and far from the feature text, so it is harder to read and maintain. This is very rare and should be avoided.
+
+For those pages, use the **same** Examples pattern (heading name **`Examples`**, **bullet list** of task-doc links), but place it **next to the feature**:
+
+- Add **`#### Examples`** immediately under the relevant **`###`** feature heading (match heading depth to your outline: one level deeper than that feature section).
+- Reuse the same link rules as in **Default** for the bullets (task-based paths only, link text = target doc title).
+
+**`docs/sources/reference/components/loki/loki.process.md`** typically uses **per-feature** **`#### Examples`** under each relevant **`### stage.*`** section. **`docs/sources/reference/components/otelcol/otelcol.processor.resourcedetection.md`** documents many detectors; it may keep a single **`## Examples`** block at the end **or** adopt the same per-feature pattern next to each detector when that reads better than one long Examples section.
+
+## When inline examples in the reference doc are OK
+
+- **Deprecated behavior** must not be promoted in task-based docs, but you may show **examples only in the reference** doc so users who still rely on the feature have a correct snippet.
+- **Single-component examples**: if the snippet uses **only** the component this page documents (no other `component.type` blocks), an inline example in the reference is fine. If the flow needs **more than one component**, put the pipeline in a **task-based** doc and link to it from Examples.
+- **Richer than the task doc**: if the reference example is **more complex** or **more informative** than the task guide, **do not remove** that detail from the reference until the task doc matches. **Prefer** copying the extra context into the task doc, then replacing the reference **Examples** with links. If the task doc still has **less** information, **ask the user** whether they want you to **try moving or expanding** the task doc so it is at least as complete as the reference (rather than silently leaving duplication or deleting content).
+
+## How to choose task-doc links
+
+- Search `monitor/`, `tutorials/`, and `collect/` for the component name or scenario. Only link to pages that **actually use** or **walk through** that component.
+- If there is no suitable task doc yet, add one when you can; until then, inline reference examples are acceptable per the rules above (especially single-component or deprecated-only cases).

docs/sources/monitor/monitor-windows.md

@@ -228,7 +228,7 @@ loki.process "endpoint" {
       }
   }
 
-  stage.eventlogmessage {
+  stage.windowsevent {
       source = "message"
       overwrite_existing = true
   }

docs/sources/reference/components/loki/loki.process.md

@@ -2005,7 +2005,13 @@ The line is appended to the previous value, separated by a comma.
 
 Lines in a section without a preceding valid entry (key-value pair) are ignored and discarded.
 
-#### Example with `loki.source.windowsevent`
+#### Examples
+
+- [Monitor Microsoft Windows servers and desktops with Grafana Alloy](../../../monitor/monitor-windows/)
+
+##### Security log pipeline with `loki.source.windowsevent`
+
+The following example reads the **Security** log, applies a `json` stage, then `stage.windowsevent`, and promotes selected fields to labels before forwarding to a `loki.write` component.
 
 ```alloy
 loki.source.windowsevent "security"  {
@@ -2027,7 +2033,7 @@ loki.process "default" {
   stage.labels {
     values = {
       Description = "",
-      Subject_SecurityID  = "",        
+      Subject_SecurityID  = "",
       ReadOP = "Subject_ReadOperation",
     }
   }
@@ -2039,7 +2045,7 @@ The `loki.source.windowsevent` component forwards Windows security events to the
 Given the following event:
 
 ```text
-{"event_id": 1, "Overwritten": "old", "message": ""Special privileges assigned to new logon.\r\n\r\nSubject:\r\n\tSecurity ID:\t\tS-1-1-1\r\n\tAccount Name:\t\tSYSTEM\r\n\tAccount Domain:\t\tNT AUTHORITY\r\n\tLogon ID:\t\t0xAAA\r\n\r\nPrivileges:\t\tSeAssignPrimaryTokenPrivilege\r\n\t\t\tSeTcbPrivilege\r\n\t\t\tSeSecurityPrivilege\r\n\t\t\tSeTakeOwnershipPrivilege\r\n\t\t\tSeLoadDriverPrivilege\r\n\t\t\tSeBackupPrivilege\r\n\t\t\tSeRestorePrivilege\r\n\t\t\tSeDebugPrivilege\r\n\t\t\tSeAuditPrivilege\r\n\t\t\tSeSystemEnvironmentPrivilege\r\n\t\t\tSeImpersonatePrivilege\r\n\t\t\tSeDelegateSessionUserImpersonatePrivilege""}
+{"event_id": 1, "Overwritten": "old", "message": "Special privileges assigned to new logon.\r\n\r\nSubject:\r\n\tSecurity ID:\t\tS-1-1-1\r\n\tAccount Name:\t\tSYSTEM\r\n\tAccount Domain:\t\tNT AUTHORITY\r\n\tLogon ID:\t\t0xAAA\r\n\r\nPrivileges:\t\tSeAssignPrimaryTokenPrivilege\r\n\t\t\tSeTcbPrivilege\r\n\t\t\tSeSecurityPrivilege\r\n\t\t\tSeTakeOwnershipPrivilege\r\n\t\t\tSeLoadDriverPrivilege\r\n\t\t\tSeBackupPrivilege\r\n\t\t\tSeRestorePrivilege\r\n\t\t\tSeDebugPrivilege\r\n\t\t\tSeAuditPrivilege\r\n\t\t\tSeSystemEnvironmentPrivilege\r\n\t\t\tSeImpersonatePrivilege\r\n\t\t\tSeDelegateSessionUserImpersonatePrivilege"}
 ```
 
 The `json` stage would create the following key-value pairs in the set of extracted data:

docs/sources/reference/components/loki/loki.source.windowsevent.md

@@ -64,22 +64,10 @@ The `loki.source.windowsevent` component doesn't support any blocks. You can con
 
 `loki.source.windowsevent` is only reported as unhealthy if given an invalid configuration.
 
-## Example
+## Examples
 
-This example collects log entries from the Event Log specified in `eventlog_name` and forwards them to a `loki.write` component.
+- [Monitor Microsoft Windows servers and desktops with Grafana Alloy](../../../monitor/monitor-windows/)
 
-```alloy
-loki.source.windowsevent "application"  {
-    eventlog_name = "Application"
-    forward_to = [loki.write.endpoint.receiver]
-}
-
-loki.write "endpoint" {
-    endpoint {
-        url ="loki:3100/api/v1/push"
-    }
-}
-```
 <!-- START GENERATED COMPATIBLE COMPONENTS -->
 
 ## Compatible components

docs/sources/reference/components/prometheus/prometheus.exporter.windows.md

@@ -610,72 +610,9 @@ The `cs` and `logon` collectors are deprecated and removed from the exporter.
 You can still configure these collectors, but they have no effect.
 {{< /admonition >}}
 
-## Example
+## Examples
 
-The following example uses a [`prometheus.scrape`][scrape] component to collect metrics from `prometheus.exporter.windows`:
-
-```alloy
-prometheus.exporter.windows "default" { }
-
-// Configure a prometheus.scrape component to collect windows metrics.
-prometheus.scrape "example" {
-  targets    = prometheus.exporter.windows.default.targets
-  forward_to = [prometheus.remote_write.demo.receiver]
-}
-
-prometheus.remote_write "demo" {
-  endpoint {
-    url = "<PROMETHEUS_REMOTE_WRITE_URL>"
-
-    basic_auth {
-      username = "<USERNAME>"
-      password = "<PASSWORD>"
-    }
-  }
-}
-```
-
-The following example shows you how to enable additional collectors and configure them:
-
-```alloy
-prometheus.exporter.windows "advanced" {
-  // Enable additional collectors beyond the default set
-  enabled_collectors = [
-    "cpu", "logical_disk", "net", "os", "service", "system",  // defaults
-    "dns", "iis", "process", "scheduled_task"                 // additional
-  ]
-
-  // Configure DNS collector settings
-  dns {
-    enabled_list = ["metrics", "wmi_stats"]
-  }
-
-  // Configure IIS collector settings
-  iis {
-    site_include = "^(Default Web Site|Production)$"
-    app_exclude  = "^$"
-  }
-
-  // Configure process collector settings
-  process {
-    include = "^(chrome|firefox|notepad).*"
-    exclude = "^$"
-  }
-}
-
-prometheus.scrape "advanced_example" {
-  targets    = prometheus.exporter.windows.advanced.targets
-  forward_to = [prometheus.remote_write.demo.receiver]
-}
-```
-
-Replace the following:
-
-- _`<PROMETHEUS_REMOTE_WRITE_URL>`_: The URL of the Prometheus `remote_write` compatible server to send metrics to.
-- _`<USERNAME>`_: The username to use for authentication to the `remote_write` API.
-- _`<PASSWORD>`_: The password to use for authentication to the `remote_write` API.
-
-[scrape]: ../prometheus.scrape/
+- [Monitor Microsoft Windows servers and desktops with Grafana Alloy](../../../monitor/monitor-windows/)
 
 <!-- START GENERATED COMPATIBLE COMPONENTS -->