Add search and filter telemetry sub-section to CLI overview

src/frontend/config/sidebar/reference.topics.ts

@@ -213,6 +213,10 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
           },
           slug: 'reference/cli/install-script',
         },
+        {
+          label: 'Search and filter',
+          slug: 'reference/cli/search-filter',
+        },
         {
           label: 'Configuration',
           translations: {

src/frontend/src/content/docs/dashboard/ai-coding-agents.mdx

@@ -1,5 +1,5 @@
 ---
-title: Dashboard and AI coding agents
+title: AI coding agents and the Aspire Dashboard
 seoTitle: Aspire dashboard and AI coding agents for distributed apps
 description: Learn how AI coding agents use the Aspire CLI and MCP server to read logs and telemetry from the Aspire dashboard, diagnose failures, and propose code changes.
 ---

src/frontend/src/content/docs/fundamentals/telemetry.mdx

@@ -73,6 +73,34 @@ When you start an Aspire project with debugging (pressing <kbd>F5</kbd>), the fo
 
 All of these steps happen internally, so in most cases you simply need to run the app to see this process in action.
 
+### Use telemetry with AI coding agents
+
+AI coding agents can access Aspire telemetry to diagnose issues, inspect app behavior, and monitor resources without requiring you to manually copy data from the dashboard. The Aspire CLI is built for agent-driven workflows—commands support non-interactive execution and `--format Json` for structured output that agents can parse.
+
+When running an Aspire AppHost, agents use CLI commands like `aspire otel logs`, `aspire otel traces`, and `aspire describe` to fetch structured logs, distributed traces, and resource status directly from the dashboard. A typical agent workflow starts the app with `aspire start`, waits for resources with `aspire wait`, then queries telemetry to diagnose issues and verify fixes.
+
+When using a standalone dashboard, agents pass `--dashboard-url` to point CLI commands at the dashboard instance and query telemetry from any application sending OTLP data.
+
+<LearnMore>
+
+- [AI coding agents and Aspire](/get-started/ai-coding-agents/) — using AI agents with an Aspire AppHost
+- [AI coding agents and the Aspire Dashboard](/dashboard/ai-coding-agents/#standalone-mode) — using AI agents with a standalone dashboard
+
+</LearnMore>
+
+## APIs and data access
+
+The Aspire dashboard exposes APIs for both receiving and querying telemetry data. Applications write data to the dashboard using OTLP endpoints, and developers and tools read data back through multiple interfaces:
+
+- **Aspire CLI** — The `aspire otel logs`, `aspire otel traces`, and `aspire otel spans` commands query telemetry directly from the terminal. Use `--format Json` for structured output suitable for scripting and automation.
+- **Export** — The `aspire export` command packages telemetry and resource data into a zip file for offline analysis or sharing.
+- **MCP server** — The Aspire MCP server exposes dashboard data to AI coding agents through Model Context Protocol tools.
+- **HTTP telemetry API** — The dashboard exposes HTTP endpoints under `/api/telemetry/` that return data in OTLP JSON format, supporting real-time streaming and resource filtering.
+
+<LearnMore>
+For more information, see [Dashboard APIs and data access](/dashboard/apis/).
+</LearnMore>
+
 ## Deployment
 
 Aspire deployment environments should configure OpenTelemetry environment variables that make sense for their environment. For example, `OTEL_EXPORTER_OTLP_ENDPOINT` should be configured to the environment's local OTLP collector or monitoring service.

src/frontend/src/content/docs/reference/cli/commands/aspire-logs.mdx

@@ -58,7 +58,7 @@ The following options are available:
 
 - **`-s, --search <search>`**
 
-  Full-text search to filter log content. Only log lines whose message or resource name contains the specified text are shown. Multiple words are treated as separate fragments that must all match. Use quoted phrases to match exact multi-word text (for example, `--search '"connection timeout"'`).
+  Full-text search to filter log content. Only log lines whose message or resource name contains the specified text are shown. Multiple words are treated as separate fragments that must all match. Use quoted phrases to match exact multi-word text (for example, `--search '"connection timeout"'`). For more information, see [Search and filter](/reference/cli/search-filter/).
 
 - **`-t, --timestamps`**
 

src/frontend/src/content/docs/reference/cli/commands/aspire-otel-logs.mdx

@@ -75,7 +75,7 @@ The following options are available:
 
 - **`--search <search>`**
 
-  Full-text search across log text fields, such as log messages, attribute values, scope, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers.
+  Full-text search across log text fields, such as log messages, attribute values, scope, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/).
 
   | Syntax | Meaning |
   |--------|---------|

src/frontend/src/content/docs/reference/cli/commands/aspire-otel-spans.mdx

@@ -75,7 +75,7 @@ The following options are available:
 
 - **`--search <search>`**
 
-  Full-text search across span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers.
+  Full-text search across span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/).
 
   | Syntax | Meaning |
   |--------|---------|

src/frontend/src/content/docs/reference/cli/commands/aspire-otel-traces.mdx

@@ -73,7 +73,7 @@ The following options are available:
 
 - **`--search <search>`**
 
-  Full-text search across trace and span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers.
+  Full-text search across trace and span text fields, such as names, attribute values, source, and IDs. Supports plain free-text fragments and structured `field:value` qualifiers. For more information, see [Search and filter](/reference/cli/search-filter/).
 
   | Syntax | Meaning |
   |--------|---------|

src/frontend/src/content/docs/reference/cli/overview.mdx

@@ -214,6 +214,12 @@ Use `aspire describe`, `aspire logs`, and `aspire export` to inspect resources,
   [Command reference: `aspire describe`](../commands/aspire-describe/), [Command reference: `aspire logs`](../commands/aspire-logs/), [Command reference: `aspire export`](../commands/aspire-export/), and [Command reference: `aspire otel`](../commands/aspire-otel/)
 </LearnMore>
 
+Use the `--search` option with `aspire logs` and `aspire otel` commands to filter output by matching text against log content and trace/span fields. Search supports free-text fragments, structured `field:value` qualifiers, negation, and comparison operators.
+
+<LearnMore>
+  [Search and filter](../search-filter/)
+</LearnMore>
+
 ## Diagnose and prepare the environment
 
 Use `aspire doctor` to verify that your environment is ready for Aspire development, and `aspire certs` to manage the HTTPS development certificates used by local resources and dashboards.

src/frontend/src/content/docs/reference/cli/search-filter.mdx

@@ -0,0 +1,85 @@
+---
+title: Search and filter
+description: Learn how to use the --search option to filter logs, traces, and spans in the Aspire CLI.
+---
+
+The `--search` option filters output by matching against text and attributes on returned data. Search is supported by these commands:
+
+- [`aspire logs`](../commands/aspire-logs/)
+- [`aspire otel logs`](../commands/aspire-otel-logs/)
+- [`aspire otel spans`](../commands/aspire-otel-spans/)
+- [`aspire otel traces`](../commands/aspire-otel-traces/)
+
+For example, to filter console logs for a specific resource by text:
+
+```bash title="Aspire CLI"
+aspire logs redis --search "timeout"
+```
+
+## Search syntax
+
+Search queries support free-text fragments, field qualifiers, attribute qualifiers, negation, and comparison operators.
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `word` | Free-text fragment — must appear in at least one searchable field | `timeout` |
+| `"quoted phrase"` | Single fragment containing spaces | `"connection refused"` |
+| `field:value` | Field qualifier — value must match the named field | `severity:error` |
+| `field:"value with spaces"` | Quoted field qualifier value | `message:"connection failed"` |
+| `@attr:value` | Attribute qualifier — matches custom span/log attributes | `@http.method:GET` |
+| `-field:value` / `-@attr:value` | Negated qualifier — excludes matches | `-severity:debug` |
+| `field:>N` / `field:>=N` / `field:<N` / `field:<=N` | Numeric comparison | `duration:>100` |
+
+All terms are AND'd: every fragment and qualifier must independently match.
+
+## Console logs
+
+Matches against log line text content and resource name. Only free-text is supported (no structured qualifiers).
+
+```bash title="Aspire CLI"
+aspire logs redis --search "timeout"
+aspire logs --follow --search "\"connection error\""
+```
+
+## Structured logs
+
+Supports free-text and structured qualifiers. Free-text matches against message, resource name, scope, trace/span IDs, severity, and all attribute keys/values.
+
+Available field qualifiers: `severity`, `resource`, `scope`, `message`, `trace-id`, `span-id`, `event`.
+
+```bash title="Aspire CLI"
+aspire otel logs --search "severity:error \"connection failed\""
+aspire otel logs --search "resource:api -severity:debug"
+aspire otel logs --search "scope:Microsoft.EntityFrameworkCore"
+```
+
+## Traces
+
+Supports free-text and structured qualifiers. Free-text matches against trace name, resource name, and all span fields within the trace.
+
+Available field qualifiers: `name`, `resource`, `trace-id`, `status`, `duration`.
+
+```bash title="Aspire CLI"
+aspire otel traces --search "checkout"
+aspire otel traces --search "status:error duration:>500"
+aspire otel traces --search "@http.status_code:500"
+```
+
+## Spans
+
+Supports free-text and structured qualifiers. Free-text matches against span name, resource name, scope, trace/span IDs, status, kind, and all attribute keys/values.
+
+Available field qualifiers: `name`, `resource`, `scope`, `status`, `kind`, `trace-id`, `span-id`, `duration`.
+
+```bash title="Aspire CLI"
+aspire otel spans --search "@http.method:GET duration:>100 status:error"
+aspire otel spans --search "@db.system:postgresql"
+aspire otel spans --search "-kind:internal"
+```
+
+## See also
+
+- [Command reference: `aspire logs`](../commands/aspire-logs/)
+- [Command reference: `aspire otel logs`](../commands/aspire-otel-logs/)
+- [Command reference: `aspire otel spans`](../commands/aspire-otel-spans/)
+- [Command reference: `aspire otel traces`](../commands/aspire-otel-traces/)