Document @Telemetria behavior on multi-clause functions

Add warning admonition to moduledoc explaining that for multi-clause
functions, @Telemetria must be placed on the bodyless head clause
(the one declaring defaults). All clauses then inherit the annotation.
Mixing head-level and per-clause annotations raises a compile-time error.

Add matching sections to the cheatsheet: 'Multi-clause functions' (head
annotation) and 'Per-clause annotations' (individual clause annotation).

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: am-kantox

lib/telemetria.ex

@@ -52,10 +52,28 @@ defmodule Telemetria do
   - **`reshape: (map() -> map())`** — the function to be called on the resulting attributes
     to reshape them before sending to the actual telemetry handler; the default application-wide
     reshaper might be set in `:telemetria, :reshaper` config
-  - **`messenger_channels: %{optional(atom()) => {module, keyword()}`** — more handy messenger
+  - **`messenger_channels: %{optional(atom()) => {module, keyword()}`** -- more handy messenger
     management, several channels config with channels names associated with their
     implementations and properties
 
+  > ### Multi-clause functions {: .warning}
+  >
+  > When a function has multiple clauses, the `@telemetria` attribute **must** be placed
+  > on the bodyless head clause (the one declaring defaults), not on individual clauses.
+  > This single annotation will wrap **all** clauses with telemetry.
+  >
+  > ```elixir
+  > @telemetria level: :info, locals: [:i]
+  > def classify(i \\ nil)       # <-- attribute goes here, on the head
+  > def classify(nil), do: :none
+  > def classify(i) when i > 0, do: :positive
+  > def classify(_i), do: :negative
+  > ```
+  >
+  > Placing `@telemetria` on individual clauses instead will annotate only those
+  > specific clauses. You may **not** mix head-level and clause-level annotations
+  > for the same function -- it will raise a compile-time error.
+
   ### Simple example
 
   The following code would emit the telemetry event for the function `weather`,

stuff/telemetria_cheatsheet.cheatmd

@@ -75,6 +75,30 @@ end
 
 The event is emitted only when the `if` function returns `true` for the result.
 
+### Multi-clause functions
+
+```elixir
+@telemetria level: :info, locals: [:i]
+def classify(i \\ nil)
+def classify(nil), do: :none
+def classify(i) when i > 0, do: :positive
+def classify(_i), do: :negative
+```
+
+For multi-clause functions, place `@telemetria` on the **bodyless head clause** (the one with defaults). All clauses will be wrapped. Do not mix head-level and per-clause annotations.
+
+### Per-clause annotations
+
+```elixir
+@telemetria level: :warning
+def handle(:error), do: alert()
+
+@telemetria level: :debug
+def handle(:ok), do: :ok
+```
+
+Alternatively, annotate individual clauses separately (each gets its own event with its own options). Cannot be combined with head-level annotation on the same function.
+
 ## Attribute Parameters
 {: .col-2}