devskill 2.0.7 → 2.0.8

package/skills/aspire/references/dashboard.md

@@ -0,0 +1,226 @@
+# Dashboard — Complete Reference
+
+The Aspire Dashboard provides real-time observability for all resources in your distributed application. It launches automatically with `aspire run` and can also run standalone.
+
+---
+
+## Features
+
+### Resources view
+
+Displays all resources (projects, containers, executables) with:
+
+- **Name** and **type** (Project, Container, Executable)
+- **State** (Starting, Running, Stopped, FailedToStart, etc.)
+- **Start time** and **uptime**
+- **Endpoints** — clickable URLs for each exposed endpoint
+- **Source** — project path, container image, or executable path
+- **Actions** — Stop, Start, Restart buttons
+
+### Console logs
+
+Aggregated raw stdout/stderr from all resources:
+
+- Filter by resource name
+- Search within logs
+- Auto-scroll with pause
+- Color-coded by resource
+
+### Structured logs
+
+Application-level structured logs (via ILogger, OpenTelemetry):
+
+- **Filterable** by resource, log level, category, message content
+- **Expandable** — click to see full log entry with all properties
+- **Correlated** with traces — click to jump to the related trace
+- Supports .NET ILogger structured logging properties
+- Supports OpenTelemetry log signals from any language
+
+### Distributed traces
+
+End-to-end request traces across all services:
+
+- **Waterfall view** — shows the full call chain with timing
+- **Span details** — HTTP method, URL, status code, duration
+- **Database spans** — SQL queries, connection details
+- **Messaging spans** — queue operations, topic publishes
+- **Error highlighting** — failed spans shown in red
+- **Cross-service correlation** — trace context propagated automatically for .NET; manual for other languages
+
+### Metrics
+
+Real-time and historical metrics:
+
+- **Runtime metrics** — CPU, memory, GC, thread pool
+- **HTTP metrics** — request rate, error rate, latency percentiles
+- **Custom metrics** — any metrics your services emit via OpenTelemetry
+- **Chartable** — time-series graphs for each metric
+
+### GenAI Visualizer
+
+For applications using AI/LLM integrations:
+
+- **Token usage** — prompt tokens, completion tokens, total tokens per request
+- **Prompt/completion pairs** — see the exact prompt sent and response received
+- **Model metadata** — which model, temperature, max tokens
+- **Latency** — time per AI call
+- Requires services to emit [GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) via OpenTelemetry
+
+---
+
+## Dashboard URL
+
+By default, the dashboard runs on an auto-assigned port. Find it:
+
+- In the terminal output when `aspire run` starts
+- Via MCP: `list_resources` tool
+- Override with `--dashboard-port`:
+
+```bash
+aspire run --dashboard-port 18888
+```
+
+---
+
+## Standalone Dashboard
+
+Run the dashboard without an AppHost — useful for existing applications that already emit OpenTelemetry:
+
+```bash
+docker run --rm -d \
+  -p 18888:18888 \
+  -p 4317:18889 \
+  mcr.microsoft.com/dotnet/aspire-dashboard:latest
+```
+
+| Port             | Purpose                                                      |
+| ---------------- | ------------------------------------------------------------ |
+| `18888`          | Dashboard web UI                                             |
+| `4317` → `18889` | OTLP gRPC receiver (standard OTel port → dashboard internal) |
+
+### Configure your services
+
+Point your OpenTelemetry exporters at the dashboard:
+
+```bash
+# Environment variables for any language's OpenTelemetry SDK
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+OTEL_SERVICE_NAME=my-service
+```
+
+### Docker Compose example
+
+```yaml
+services:
+  dashboard:
+    image: mcr.microsoft.com/dotnet/aspire-dashboard:latest
+    ports:
+      - "18888:18888"
+      - "4317:18889"
+
+  api:
+    build: ./api
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
+      - OTEL_SERVICE_NAME=api
+
+  worker:
+    build: ./worker
+    environment:
+      - OTEL_EXPORTER_OTLP_ENDPOINT=http://dashboard:18889
+      - OTEL_SERVICE_NAME=worker
+```
+
+---
+
+## Dashboard configuration
+
+### Authentication
+
+The standalone dashboard supports authentication via browser tokens:
+
+```bash
+docker run --rm -d \
+  -p 18888:18888 \
+  -p 4317:18889 \
+  -e DASHBOARD__FRONTEND__AUTHMODE=BrowserToken \
+  -e DASHBOARD__FRONTEND__BROWSERTOKEN__TOKEN=my-secret-token \
+  mcr.microsoft.com/dotnet/aspire-dashboard:latest
+```
+
+### OTLP configuration
+
+```bash
+# Accept OTLP over gRPC (default)
+-e DASHBOARD__OTLP__GRPC__ENDPOINT=http://0.0.0.0:18889
+
+# Accept OTLP over HTTP
+-e DASHBOARD__OTLP__HTTP__ENDPOINT=http://0.0.0.0:18890
+
+# Require API key for OTLP
+-e DASHBOARD__OTLP__AUTHMODE=ApiKey
+-e DASHBOARD__OTLP__PRIMARYAPIKEY=my-api-key
+```
+
+### Resource limits
+
+```bash
+# Limit log entries retained
+-e DASHBOARD__TELEMETRYLIMITS__MAXLOGCOUNT=10000
+
+# Limit trace entries retained
+-e DASHBOARD__TELEMETRYLIMITS__MAXTRACECOUNT=10000
+
+# Limit metric data points
+-e DASHBOARD__TELEMETRYLIMITS__MAXMETRICCOUNT=50000
+```
+
+---
+
+## Copilot integration
+
+The dashboard integrates with GitHub Copilot in VS Code:
+
+- Ask questions about resource status
+- Query logs and traces in natural language
+- The MCP server (see [MCP Server](mcp-server.md)) provides the bridge
+
+---
+
+## Non-.NET service telemetry
+
+For non-.NET services to appear in the dashboard, they must emit OpenTelemetry signals. Aspire auto-injects the OTLP endpoint env var when using `.WithReference()`:
+
+### Python (OpenTelemetry SDK)
+
+```python
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+import os
+
+# Aspire injects OTEL_EXPORTER_OTLP_ENDPOINT automatically
+endpoint = os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "http://localhost:4317")
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint=endpoint)))
+trace.set_tracer_provider(provider)
+```
+
+### JavaScript (OpenTelemetry SDK)
+
+```javascript
+const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
+const { OTLPTraceExporter } = require("@opentelemetry/exporter-trace-otlp-grpc");
+
+const provider = new NodeTracerProvider();
+provider.addSpanProcessor(
+  new BatchSpanProcessor(
+    new OTLPTraceExporter({
+      url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || "http://localhost:4317",
+    })
+  )
+);
+provider.register();
+```

package/skills/aspire/references/deployment.md

@@ -0,0 +1,237 @@
+# Deployment — Complete Reference
+
+Aspire separates **orchestration** (what to run) from **deployment** (where to run it). The `aspire publish` command translates your AppHost resource model into deployment manifests for your target platform.
+
+---
+
+## Publish vs Deploy
+
+| Concept | What it does |
+|---|---|
+| **`aspire publish`** | Generates deployment artifacts (Dockerfiles, Helm charts, Bicep, etc.) |
+| **Deploy** | You run the generated artifacts through your CI/CD pipeline |
+
+Aspire does NOT deploy directly. It generates the manifests — you deploy them.
+
+---
+
+## Supported Targets
+
+### Docker
+
+**Package:** `Aspire.Hosting.Docker`
+
+```bash
+aspire publish -p docker -o ./docker-output
+```
+
+Generates:
+- `docker-compose.yml` — service definitions matching your AppHost
+- `Dockerfile` for each .NET project
+- Environment variable configuration
+- Volume mounts
+- Network configuration
+
+```csharp
+// AppHost configuration for Docker publishing
+var api = builder.AddProject<Projects.Api>("api")
+    .PublishAsDockerFile();  // override default publish behavior
+```
+
+### Kubernetes
+
+**Package:** `Aspire.Hosting.Kubernetes`
+
+```bash
+aspire publish -p kubernetes -o ./k8s-output
+```
+
+Generates:
+- Kubernetes YAML manifests (Deployments, Services, ConfigMaps, Secrets)
+- Helm chart (optional)
+- Ingress configuration
+- Resource limits based on AppHost configuration
+
+```csharp
+// AppHost: customize K8s publishing
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReplicas(3)                    // maps to K8s replicas
+    .WithExternalHttpEndpoints();       // maps to Ingress/LoadBalancer
+```
+
+### Azure Container Apps
+
+**Package:** `Aspire.Hosting.Azure.AppContainers`
+
+```bash
+aspire publish -p azure -o ./azure-output
+```
+
+Generates:
+- Bicep templates for Azure Container Apps Environment
+- Container App definitions for each service
+- Azure Container Registry configuration
+- Managed identity configuration
+- Dapr components (if using Dapr integration)
+- VNET configuration
+
+```csharp
+// AppHost: Azure-specific configuration
+var api = builder.AddProject<Projects.Api>("api")
+    .WithExternalHttpEndpoints()        // maps to external ingress
+    .WithReplicas(3);                   // maps to min replicas
+
+// Azure resources are auto-provisioned
+var storage = builder.AddAzureStorage("storage");   // creates Storage Account
+var cosmos = builder.AddAzureCosmosDB("cosmos");    // creates Cosmos DB account
+var sb = builder.AddAzureServiceBus("messaging");   // creates Service Bus namespace
+```
+
+### Azure App Service
+
+**Package:** `Aspire.Hosting.Azure.AppService`
+
+```bash
+aspire publish -p appservice -o ./appservice-output
+```
+
+Generates:
+- Bicep templates for App Service Plans and Web Apps
+- Connection string configuration
+- Application settings
+
+---
+
+## Resource model to deployment mapping
+
+| AppHost concept | Docker Compose | Kubernetes | Azure Container Apps |
+|---|---|---|---|
+| `AddProject<T>()` | `service` with Dockerfile | `Deployment` + `Service` | `Container App` |
+| `AddContainer()` | `service` with `image:` | `Deployment` + `Service` | `Container App` |
+| `AddRedis()` | `service: redis` | `StatefulSet` | Managed Redis |
+| `AddPostgres()` | `service: postgres` | `StatefulSet` | Azure PostgreSQL |
+| `.WithReference()` | `environment:` vars | `ConfigMap` / `Secret` | App settings |
+| `.WithReplicas(n)` | `deploy: replicas: n` | `replicas: n` | `minReplicas: n` |
+| `.WithVolume()` | `volumes:` | `PersistentVolumeClaim` | Azure Files |
+| `.WithHttpEndpoint()` | `ports:` | `Service` port | Ingress |
+| `.WithExternalHttpEndpoints()` | `ports:` (host) | `Ingress` / `LoadBalancer` | External ingress |
+| `AddParameter(secret: true)` | `.env` file | `Secret` | Key Vault reference |
+
+---
+
+## CI/CD integration
+
+### GitHub Actions example
+
+```yaml
+name: Deploy
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Install Aspire CLI
+        run: curl -sSL https://aspire.dev/install.sh | bash
+
+      - name: Generate manifests
+        run: aspire publish -p azure -o ./deploy
+
+      - name: Deploy to Azure
+        uses: azure/arm-deploy@v2
+        with:
+          template: ./deploy/main.bicep
+          parameters: ./deploy/main.parameters.json
+```
+
+### Azure DevOps example
+
+```yaml
+trigger:
+  branches:
+    include: [main]
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: UseDotNet@2
+    inputs:
+      version: '10.0.x'
+
+  - script: curl -sSL https://aspire.dev/install.sh | bash
+    displayName: 'Install Aspire CLI'
+
+  - script: aspire publish -p azure -o $(Build.ArtifactStagingDirectory)/deploy
+    displayName: 'Generate deployment manifests'
+
+  - task: AzureResourceManagerTemplateDeployment@3
+    inputs:
+      deploymentScope: 'Resource Group'
+      templateLocation: '$(Build.ArtifactStagingDirectory)/deploy/main.bicep'
+```
+
+---
+
+## Environment-specific configuration
+
+### Using parameters for secrets
+
+```csharp
+// AppHost
+var dbPassword = builder.AddParameter("db-password", secret: true);
+var postgres = builder.AddPostgres("db", password: dbPassword);
+```
+
+In deployment:
+- **Docker:** Loaded from `.env` file
+- **Kubernetes:** Loaded from `Secret` resource
+- **Azure:** Loaded from Key Vault via managed identity
+
+### Conditional resources
+
+```csharp
+// Use Azure services in production, emulators locally
+if (builder.ExecutionContext.IsPublishMode)
+{
+    var cosmos = builder.AddAzureCosmosDB("cosmos");    // real Azure resource
+}
+else
+{
+    var cosmos = builder.AddAzureCosmosDB("cosmos")
+        .RunAsEmulator();                                // local emulator
+}
+```
+
+---
+
+## Dev Containers & GitHub Codespaces
+
+Aspire templates include `.devcontainer/` configuration:
+
+```json
+{
+  "name": "Aspire App",
+  "image": "mcr.microsoft.com/devcontainers/dotnet:10.0",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/node:1": {}
+  },
+  "postCreateCommand": "curl -sSL https://aspire.dev/install.sh | bash",
+  "forwardPorts": [18888],
+  "portsAttributes": {
+    "18888": { "label": "Aspire Dashboard" }
+  }
+}
+```
+
+Port forwarding works automatically in Codespaces — the dashboard and all service endpoints are accessible via forwarded URLs.

package/skills/aspire/references/integrations-catalog.md

@@ -0,0 +1,68 @@
+# Integrations Catalog
+
+Aspire has **144+ integrations** across 13 categories. Rather than maintaining a static list, use the MCP tools to get live, up-to-date integration data.
+
+---
+
+## Discovering integrations (MCP tools)
+
+The Aspire MCP server provides two tools for integration discovery — these work on **all CLI versions** (13.1+) and do **not** require a running AppHost.
+
+| Tool                   | What it does                                                                                             | When to use                                                                                 |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `list_integrations`    | Returns all available Aspire hosting integrations with their NuGet package IDs                           | "What integrations are available for databases?" / "Show me all Redis-related integrations" |
+| `get_integration_docs` | Retrieves detailed documentation for a specific integration package (setup, configuration, code samples) | "How do I configure PostgreSQL?" / "Show me the docs for `Aspire.Hosting.Redis`"            |
+
+### Workflow
+
+1. **Browse** — Call `list_integrations` to see what's available. Filter results by category or keyword.
+2. **Deep dive** — Call `get_integration_docs` with the package ID (e.g., `Aspire.Hosting.Redis`) and version (e.g., `9.0.0`) to get full setup instructions.
+3. **Add** — Run `aspire add <integration>` to install the hosting package into your AppHost.
+
+> **Tip:** These tools return the same data as the [official integrations gallery](https://aspire.dev/integrations/gallery/). Prefer them over static docs — integrations are added frequently.
+
+---
+
+## Integration pattern
+
+Every integration follows a two-package pattern:
+
+- **Hosting package** (`Aspire.Hosting.*`) — adds the resource to the AppHost
+- **Client package** (`Aspire.*`) — configures the client SDK in your service with health checks, telemetry, and retries
+- **Community Toolkit** (`CommunityToolkit.Aspire.*`) — community-maintained integrations from [Aspire Community Toolkit](https://github.com/CommunityToolkit/Aspire)
+
+```csharp
+// === AppHost (hosting side) ===
+var redis = builder.AddRedis("cache");  // Aspire.Hosting.Redis
+var api = builder.AddProject<Projects.Api>("api")
+    .WithReference(redis);
+
+// === Service (client side) — in API's Program.cs ===
+builder.AddRedisClient("cache");        // Aspire.StackExchange.Redis
+// Automatically configures: connection string, health checks, OpenTelemetry, retries
+```
+
+---
+
+## Categories at a glance
+
+Use `list_integrations` for the full live list. This summary covers the major categories:
+
+| Category            | Key integrations                                                                      | Example hosting package                  |
+| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------- |
+| **AI**              | Azure OpenAI, OpenAI, GitHub Models, Ollama                                           | `Aspire.Hosting.Azure.CognitiveServices` |
+| **Caching**         | Redis, Garnet, Valkey, Azure Cache for Redis                                          | `Aspire.Hosting.Redis`                   |
+| **Cloud / Azure**   | Storage, Cosmos DB, Service Bus, Key Vault, Event Hubs, Functions, SQL, SignalR (25+) | `Aspire.Hosting.Azure.Storage`           |
+| **Cloud / AWS**     | AWS SDK integration                                                                   | `Aspire.Hosting.AWS`                     |
+| **Databases**       | PostgreSQL, SQL Server, MongoDB, MySQL, Oracle, Elasticsearch, Milvus, Qdrant, SQLite | `Aspire.Hosting.PostgreSQL`              |
+| **DevTools**        | Data API Builder, Dev Tunnels, Mailpit, k6, Flagd, Ngrok, Stripe                      | `Aspire.Hosting.DevTunnels`              |
+| **Messaging**       | RabbitMQ, Kafka, NATS, ActiveMQ, LavinMQ                                              | `Aspire.Hosting.RabbitMQ`                |
+| **Observability**   | OpenTelemetry (built-in), Seq, OTel Collector                                         | `Aspire.Hosting.Seq`                     |
+| **Compute**         | Docker Compose, Kubernetes                                                            | `Aspire.Hosting.Docker`                  |
+| **Reverse Proxies** | YARP                                                                                  | `Aspire.Hosting.Yarp`                    |
+| **Security**        | Keycloak                                                                              | `Aspire.Hosting.Keycloak`                |
+| **Frameworks**      | JavaScript, Python, Go, Java, Rust, Bun, Deno, Orleans, MAUI, Dapr, PowerShell        | `Aspire.Hosting.Python`                  |
+
+For polyglot framework method signatures, see [Polyglot APIs](polyglot-apis.md).
+
+---