Improve notification silence docs

.gitignore

@@ -12,4 +12,4 @@ node_modules
 .cursor
 .bin/
 
-claude.md
+claude.md

mission-control/docs/guide/notifications/concepts/silences.mdx

@@ -4,53 +4,75 @@ sidebar_custom_props:
   icon: mage:notification-bell-muted
 ---
 
+import Silence from "@site/docs/reference/notifications/_silence.mdx"
+
 A silence is a way to temporarily suppress notifications. Each silence has:
 
-- A set duration - like an expiration timer
-- A scope - it can be applied to either:
-  - Individual resources (a specific catalog, health check, or component)
-  - Multiple matching resources using filters
+- A description - explaining why the silence was created
+- A duration - specified by `from` and `until` timestamps in RFC3339 format
+- A scope - defined through selectors and filters to target specific resources
+- A recursive flag - to apply silence to child resources
 
 :::note
 Notifications that aren't sent due to silence are still visible in the notification history for auditing purposes.
 :::
 
+
+```yaml title="" file=<rootDir>/modules/mission-control/fixtures/silences/silence-test-env.yaml
+``` 
+
 ## Use cases
 
-- Planned maintenance or deployments. Eg: You can silence a namespace or a helm release and automatically silence notifications from all their children.
-- Non-critical resources: Notifications from resources that routinely trigger alerts but are expected and harmless can be silenced.
-- Known issues: If there's a known issue that can't be immediately resolved (e.g., due to dependencies or resource constraints), you might silence related alerts until a fix can be implemented.
+- Planned maintenance or deployments - Silence notifications from a namespace or helm release and optionally all their children
+- Non-critical resources - Suppress notifications from resources that routinely trigger expected and harmless alerts
+- Known issues - Temporarily silence alerts for known issues that can't be immediately resolved due to dependencies or resource constraints
 
-## Add Silence
+## Creating Silences
 
-Silences can be added from the notification page. Alternatively, if you're using the default slack notification templates, you get a silence button
-on each notification.
+Silences can be created in multiple ways:
+1. Through the notification page UI
+2. Using the silence button on Slack notifications (when using default templates)
+3. By applying a NotificationSilence custom resource
 
-![Silence Notification form](./silence-notification-form.png)
+<Silence />
+
+### Resource Selection
+
+Silences can target resources in two ways:
 
-### Filters
+1. **Selectors**: Direct resource matching using kind and name
+2. **Filters**: Complex matching using CEL expressions
 
-A silence can optionally contain a filter. A filter is a cel-expression that results in a boolean value.
-If a filter return true, the notification is silenced.
+#### Selectors
 
-#### Examples
+Selectors provide a straightforward way to target specific resources by their kind and name. Multiple selectors can be specified to target different resources.
 
-| Filter | description |
+#### Filters
+
+A filter is a CEL expression that evaluates to a boolean value. The notification is silenced when the filter returns true. Filters provide powerful, flexible matching capabilities.
+
+##### Filter Examples
+
+| Filter | Description |
 |--------|-------------|
-| `check.type == 'http'`                                                    | silences only HTTP check related notifications. |
-| `regexp.Match("^check-[0-9]+", check.name)`                               | matches any check with the prefix `check-` |
-| `config.name == "postgresql" && config.type == "Kubernetes::StatefulSet"` | silences notifications from a stateful set named "postgresql" |
-| `config.type == "Kubernetes::Pod" && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming").size > 0 && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming")[0].tags.?env.orValue("") == "prod"` | matches kubernetes pod in a prod namespace |
+| `check.type == 'http'` | Silences HTTP check notifications |
+| `regexp.Match("^check-[0-9]+", check.name)` | Matches checks with prefix `check-` |
+| `config.name == "postgresql" && config.type == "Kubernetes::StatefulSet"` | Silences notifications from a specific StatefulSet |
+| `config.type == "Kubernetes::Pod" && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming").size > 0 && catalog.traverse(config.id, "Kubernetes::Namespace", "incoming")[0].tags.?env.orValue("") == "prod"` | Matches pods in production namespaces |
 
-#### Template variables
+##### Available Template Variables
 
+Filters can reference these variables:
 - [CheckEvents](/reference/notifications/template_vars/checks)
 - [ConfigEvents](/reference/notifications/template_vars/config)
 - [ComponentEvents](/reference/notifications/template_vars/components)
 
-### Recursive mode
+### Recursive Mode
 
-When a silence is recursively applied, it applies to its all children.
-So silencing a namespace would silence all deployments, statefulsets, pods, etc in that namespace.
+When `recursive: true` is set, the silence applies to all child resources of the matched resources. For example:
+- Silencing a namespace affects all deployments, statefulsets, pods, etc. within it
+- Silencing a statefulset affects all its pods
+
+![Silence Notification form](./silence-notification-form.png)
 
 

mission-control/docs/reference/notifications/_silence.mdx

@@ -0,0 +1,52 @@
+<Fields withTemplates="true" rows={[
+  {
+    field: "description",
+    description: "A description explaining the purpose of the silence",
+    scheme: "string"
+  },
+  {
+    field: "from",
+    description: "Start time of the silence period in RFC3339 format or datetime",
+    scheme: "string"
+  },
+  {
+    field: "until",
+    description: "End time of the silence period in RFC3339 format or datetime",
+    scheme: "string"
+  },
+  {
+    field: "recursive",
+    description: "When true, the silence applies to all child resources of the matched resources. For example, silencing a namespace would silence all deployments, statefulsets, pods, etc. within it.",
+    scheme: "boolean"
+  },
+  {
+    field: "filter",
+    description: "A CEL expression that determines whether to apply the silence. The silence is only applied if the filter evaluates to true.",
+    scheme: "CEL",
+    templateEnv: [
+      {"name": "CheckEvents", "url": "/reference/notifications/template_vars/checks"},
+      {"name": "ConfigEvents", "url": "/reference/notifications/template_vars/config"},
+      {"name": "ComponentEvents", "url": "/reference/notifications/template_vars/components"},
+    ],
+  },
+  {
+    field: "selectors",
+    description: "List of resource selectors to target specific resources by their kind and name",
+    scheme: "[[]ResourceSelector](#resource-selector)"
+  }
+]}/>
+
+### Resource Selector
+
+<Fields rows={[
+  {
+    field: "kind",
+    description: "The kind of resource to select (e.g., 'Kubernetes::StatefulSet', 'Kubernetes::Pod')",
+    scheme: "string"
+  },
+  {
+    field: "name",
+    description: "The name of the resource to select",
+    scheme: "string"
+  }
+]}/>