### One-Click Startup Guide

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide-zh.md

Provides a step-by-step guide to launch the Aevatar.Aspire platform, including starting infrastructure components, initializing the database, configuring Orleans networking (for macOS), and finally running all services. This is the recommended way to get the system up and running.

```bash
# 1. Start infrastructure
cd src/Aevatar.Aspire
docker-compose up -d

# 2. Initialize database (first run)
cd ../Aevatar.DBMigrator
dotnet run

# 3. Configure Orleans network (macOS users)
sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3

# 4. Start all services
cd ../Aevatar.Aspire
dotnet run
```

--------------------------------

### Development Environment Setup

Source: https://github.com/aevatarai/aevatar-station/blob/dev/framework/TECHNICAL_DOCUMENTATION.md

Commands to set up the development environment, including installing the .NET SDK, MongoDB, and cloning the repository.

```bash
# Install .NET 8 SDK
# Install MongoDB Community Edition
# Install Visual Studio 2022 or VS Code

git clone <repository-url>
cd aevatar-framework
dotnet restore
dotnet build

dotnet test --collect:"XPlat Code Coverage"
```

--------------------------------

### Getting Started - Running the Application

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.HttpApi.Host/README.md

Instructions for running the Aevatar.HttpApi.Host application. This involves ensuring prerequisites like MongoDB and Redis are running, configuring connection strings, and executing the application.

```APIDOC
Getting Started:
1. Prerequisites:
   - MongoDB running
   - Redis running
2. Configuration:
   - Update connection strings in `appsettings.json`.
3. Execution:
   - Run the application using the command: `dotnet run`
4. Access:
   - Swagger UI available at: `/swagger`
```

--------------------------------

### Getting Started with Aevatar Station

Source: https://github.com/aevatarai/aevatar-station/blob/dev/docs/product_summary.md

This snippet provides the bash commands to clone the Aevatar Station monorepo, run database migrations, start the Orleans silo, and launch the HTTP API host. It also explains how to connect a WebSocket client to the `/api/agent/aevatarHub` endpoint.

```bash
# Clone the monorepo
git clone https://github.com/aevatarAI/aevatar-station.git
cd aevatar-station/station/src

# Run database migrations
cd Aevatar.DbMigrator && dotnet run && cd ..

# Start the Orleans silo
cd Aevatar.Silo && dotnet run

# Start the HTTP API
cd ../Aevatar.HttpApi.Host && dotnet run

# Connect a WebSocket client to /api/agent/aevatarHub to publish events in real time.
```

--------------------------------

### Aevatar.AuthServer Application Startup

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.AuthServer/README.md

Details the standard ASP.NET Core startup process for the Aevatar.AuthServer, including Serilog configuration, host creation, ABP initialization, middleware setup, and application start.

```APIDOC
Application Startup:
1. Configures Serilog for logging.
2. Creates and configures the web host.
3. Initializes the ABP application.
4. Configures middleware for request processing.
5. Starts the application.
```

--------------------------------

### Development Guides Generation

Source: https://github.com/aevatarai/aevatar-station/blob/dev/technical-documentation-practices.md

Details the content for development guides, covering environment setup, workflows, testing, and debugging.

```markdown
4. **Generate Development Guides**
   - Setup and development environment configuration
   - Common development workflows and patterns
   - Testing strategies and approaches
   - Debugging and troubleshooting guides
```

--------------------------------

### Aevatar Station Official Documentation

Source: https://github.com/aevatarai/aevatar-station/blob/dev/competitors/n8n/templates-community.md

Offers comprehensive user guides, technical development guides, and complete API references. It also includes installation guides, system configuration guides, troubleshooting common issues, recommended practices, and version upgrade guides.

```APIDOC
User Guides:
  - Comprehensive user documentation.

Developer Docs:
  - Technical development guides.

API Reference:
  - Complete API documentation.

Installation Guides:
  - Setup and installation instructions.

Configuration:
  - System configuration guides.

Troubleshooting:
  - Common issue resolution.

Best Practices:
  - Recommended practices.

Migration Guides:
  - Version upgrade guides.
```

--------------------------------

### Configuration Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.DbMigrator/README.md

Example JSON structure for the application's configuration file (appsettings.json), including database connection strings, Redis settings, and OpenIddict application details.

```json
{
  "ConnectionStrings": {
    "Default": "mongodb://localhost:27017/Aevatar"
  },
  "Redis": {
    "Configuration": "127.0.0.1"
  },
  "OpenIddict": {
    "Applications": {
      "Aevatar_Web": {
        "ClientId": "web-client",
        "ClientSecret": "client-secret",
        "RootUrl": "https://localhost:44302"
      }
    }
  }
}
```

--------------------------------

### One-Click Launch for Aevatar.Aspire

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Provides a step-by-step guide to launch the Aevatar.Aspire microservices ecosystem. It includes starting infrastructure via Docker Compose, initializing the database, configuring the Orleans network (for macOS), and finally running all services.

```bash
# 1. Start infrastructure
cd src/Aevatar.Aspire
docker-compose up -d

# 2. Initialize database (first run)
cd ../Aevatar.DBMigrator
dotnet run

# 3. Configure Orleans network (macOS users)
sudo ifconfig lo0 alias 127.0.0.2
sudo ifconfig lo0 alias 127.0.0.3

# 4. Start all services
cd ../Aevatar.Aspire
dotnet run
```

--------------------------------

### BroadcastLatencyBenchmark Example Commands

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/benchmark/BroadcastLatencyBenchmark/README.md

Provides example commands for running the BroadcastLatencyBenchmark with specific scenarios, such as high-scale testing, debugging communication flow, performance testing, and quick tests with custom event numbers.

```bash
# High-scale broadcast test
dotnet run -- --subscriber-count 1000 --publisher-count 5 --duration 120 --events-per-second 2

# Debug communication flow
dotnet run -- --debug --verbose --subscriber-count 3

# Performance test with stored IDs (default behavior)
dotnet run -- --subscriber-count 500 --duration 300 --events-per-second 5

# Quick test with custom event number
dotnet run -- --subscriber-count 20 --duration 10 --event-number 250
```

--------------------------------

### Basic Usage

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/benchmark/LayeredLatencyBenchmark/README.md

Runs the LayeredLatencyBenchmark with default settings. This is the simplest way to start the benchmark.

```bash
dotnet run
```

--------------------------------

### Install .NET 8 SDK

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/TECHNICAL_DOCUMENTATION.md

Installs the .NET 8 SDK using the official installation script. This is a prerequisite for building and running .NET applications.

```bash
# Install .NET 8 SDK
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --version 8.0.101
```

--------------------------------

### Webhook Configuration Example (JSON)

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.WebHook.Deploy/README.md

An example JSON configuration file for deploying a webhook, specifying details such as name, environment, API version, resource limits, replicas, and monitoring settings.

```json
{
  "Webhook": {
    "Name": "OrderProcessingWebhook",
    "Environment": "Production",
    "ApiVersion": "v1",
    "Resources": {
      "MemoryLimit": "256Mi",
      "CpuLimit": "200m"
    },
    "Replicas": 2,
    "Monitoring": {
      "Enabled": true,
      "AlertThresholds": {
        "ErrorRate": 0.01,
        "ResponseTime": 500
      }
    }
  }
}
```

--------------------------------

### C# Plugin Implementation Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/framework/TECHNICAL_DOCUMENTATION.md

Provides a C# example of implementing the `IAgentPlugin` interface, including methods for initialization, method execution, event handling, and state management. Demonstrates a basic WeatherPlugin.

```csharp
// Plugin implementation
public class WeatherPlugin : IAgentPlugin
{
    public AgentPluginMetadata Metadata => new(
        "WeatherPlugin",
        "1.0.0",
        "Weather Service Plugin");

    private IAgentContext? _context;

    public Task InitializeAsync(IAgentContext context, CancellationToken cancellationToken = default)
    {
        _context = context;
        return Task.CompletedTask;
    }

    public async Task<object?> ExecuteMethodAsync(string methodName, object?[] parameters, CancellationToken cancellationToken = default)
    {
        return methodName switch
        {
            "GetWeather" => await GetWeatherAsync((string)parameters[0]!),
            _ => throw new NotSupportedException($"Method {methodName} not supported")
        };
    }

    public async Task HandleEventAsync(IAgentEvent agentEvent, CancellationToken cancellationToken = default)
    {
        if (agentEvent.EventType == "WeatherRequest")
        {
            var weatherData = await GetWeatherAsync(agentEvent.Data?.ToString() ?? "");
            await _context!.PublishEventAsync(new WeatherResponseEvent
            {
                EventType = "WeatherResponse",
                Data = weatherData,
                Timestamp = DateTime.UtcNow
            });
        }
    }

    public Task<object?> GetStateAsync(CancellationToken cancellationToken = default) => Task.FromResult<object?>(null);
    public Task SetStateAsync(object? state, CancellationToken cancellationToken = default) => Task.CompletedTask;
    public Task DisposeAsync() => Task.CompletedTask;

    private async Task<string> GetWeatherAsync(string location)
    {
        // Plugin-specific weather logic
        return $"Sunny, 25°C in {location}";
    }
}
```

--------------------------------

### TDD Cycle Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/CLAUDE.md

Illustrates the Test-Driven Development (TDD) cycle, starting with writing a failing test, followed by minimal implementation to pass, and potential refactoring. This example uses C# and the xUnit testing framework.

```csharp
// STEP 1: Write failing test FIRST
[Fact]
public async Task Should_CalculateDiscount_When_CustomerIsVIP()
{
    // This test MUST be written BEFORE the CalculateDiscount method exists
    var service = new PricingService();
    var result = await service.CalculateDiscount(customerId: "VIP123", amount: 100);
    
    result.ShouldBe(10); // 10% discount for VIP
}

// STEP 2: Run test - it MUST fail (method doesn't exist yet)
// STEP 3: Write MINIMAL implementation to pass
// STEP 4: Refactor if needed
// STEP 5: Write next failing test for next requirement
```

--------------------------------

### Startup Speed Optimization

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Tips for optimizing startup speed, including pre-pulling Docker images, enabling BuildKit, and using SSD storage.

```bash
# 1. Pre-pull Docker images
docker-compose pull

# 2. Enable Docker BuildKit
export DOCKER_BUILDKIT=1

# 3. Use SSD storage for Docker data
# Configure in Docker Desktop settings
```

--------------------------------

### Automatic Project Creation & User Onboarding

Source: https://github.com/aevatarai/aevatar-station/blob/dev/docs/epics/1-node-visualizer-specifications.md

Details the process of automatically creating a default project for new organizations and guiding users to the workflow dashboard. This ensures a seamless onboarding experience, allowing users to immediately start building workflows without manual setup. It covers project naming, permissions, user navigation, and error handling.

```APIDOC
Automatic Project Creation & User Onboarding:
  Version: v0.6
  Objective: Streamline onboarding by automatically creating a default project and directing users to the workflow dashboard.
  Key Requirements:
    Automatic Project Creation:
      - New organizations trigger default project generation.
      - Default project naming convention: "Default Project" or "[Organization Name] - Main Project".
      - Includes appropriate permissions and configurations.
      - Transparent creation process, no user intervention required.
      - System creates necessary project infrastructure (database entries, permissions, etc.).
    User Navigation & Onboarding:
      - Automatic redirection to the workflow dashboard within the default project.
      - Dashboard displays welcome messaging and guidance.
      - Clear visual indicators for the default project context.
      - Project selector pre-selected to the default project.
    Project Configuration:
      - Standard settings for common use cases.
      - Basic permissions for organization creator/admin.
      - Support for all standard workflow features (agents, templates, plugins).
      - Organization owner has full administrative access.
    Error Handling & Fallbacks:
      - Graceful handling of project creation failures with user notification.
      - Fallback mechanisms for navigation failures.
      - Clear error messages for setup issues.
      - Retry mechanism for project creation.
  Acceptance Criteria:
    - New organizations automatically receive a default project.
    - Users directed to the workflow dashboard in their default project.
    - Default project is fully functional upon user arrival.
    - Project creation is transparent and requires no user intervention.
    - Users receive clear visual confirmation of project context.
    - Error scenarios handled gracefully with user feedback.
    - Dashboard provides helpful onboarding guidance.
    - All standard workflow features available immediately.
```

--------------------------------

### Advanced Startup Options

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide-zh.md

Provides commands for different startup modes: full startup, quick development mode (skipping infrastructure), and displaying help information.

```bash
# 启动所有组件，包括基础设施
dotnet run

# 跳过基础设施启动，适合开发阶段
dotnet run --skip-infrastructure

# 显示帮助信息
dotnet run --help
```

--------------------------------

### Launch Options

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Demonstrates different ways to launch the application, including full mode, quick development mode, and showing help.

```bash
# Start all components, including infrastructure
dotnet run
```

```bash
# Skip infrastructure startup, suitable for development phase
dotnet run --skip-infrastructure
```

```bash
dotnet run --help
```

--------------------------------

### Troubleshooting First Startup Failure

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Steps to troubleshoot initial startup failures, including checking prerequisites like .NET SDK and Docker, and verifying service status.

```bash
# Check prerequisites
dotnet --version  # Confirm .NET 9 SDK
docker --version  # Confirm Docker is running

# Step-by-step startup troubleshooting
docker-compose up -d  # Start infrastructure first
docker-compose ps     # Confirm all services are Running
```

--------------------------------

### Get Agent Relationships API

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/api-interface-design-en.md

Retrieves the relationship graph of a specified agent, including parent and child agents. Requires agent GUID for identification.

```APIDOC
GET /{guid}/relationship

Description: Retrieve the relationship graph of the specified agent, including hierarchical relationship information such as parent agents and child agents.

Request Parameters:
- guid (Guid, Required): Agent unique identifier

Authorization: Required

Request Example: GET /api/agent/123e4567-e89b-12d3-a456-426614174000/relationship

Response Example:
{
  "agentId": "123e4567-e89b-12d3-a456-426614174000",
  "parentAgents": [
    {
      "id": "parent-agent-id",
      "name": "Parent Agent",
      "agentType": "ManagerAgent"
    }
  ],
  "subAgents": [
    {
      "id": "sub-agent-id-1",
      "name": "Sub Agent 1",
      "agentType": "WorkerAgent"
    }
  ]
}
```

--------------------------------

### _id Format Pattern Examples

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Silo/AgentWarmup/DESIGN.md

Illustrates the _id format pattern with various agent types and identifier formats (Guid, string, long) using C#.

```csharp
// TestDbGAgent with Guid identifier
_id: "testdbgagent/99f2e278ae5e4a759075b15d64b4e749"

// UserGAgent with Guid identifier  
_id: "usergagent/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

// OrderGAgent with string identifier
_id: "ordergagent/order-12345"

// ProductGAgent with long identifier
_id: "productgagent/9876543210"
```

--------------------------------

### Troubleshooting: First Startup Failure

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide-zh.md

Provides steps to diagnose and resolve issues during the initial project startup, including checking prerequisites like .NET SDK and Docker versions, and performing a step-by-step startup.

```bash
# 检查前置条件
dotnet --version  # 确认.NET 9 SDK
docker --version  # 确认Docker运行

# 分步启动排查
docker-compose up -d  # 先启动基础设施
docker-compose ps     # 确认所有服务Running
```

--------------------------------

### Test Case Documentation Structure

Source: https://github.com/aevatarai/aevatar-station/blob/dev/CLAUDE.md

An example of hierarchical test case documentation in Markdown, suitable for XMind compatibility. It outlines test cases for a PricingService, focusing on discount calculations for VIP customers.

```markdown
# PricingService Test Cases
## Discount Calculation
### VIP Customer Discounts
#### Standard VIP Discount Rules
##### VIP customer receives 10% discount on orders over $100
###### Expected Result
- Discount amount equals 10% of order total
- Final amount is reduced by discount
- Discount is recorded in order history
```

--------------------------------

### Test Implementation Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/CLAUDE.md

A C# code snippet demonstrating a unit test for an agent's event handling logic. It follows the Arrange-Act-Assert pattern and includes a placeholder for an agent's state.

```csharp
[Fact] 
public async Task Should_UpdateState_When_EventReceived()
{
    // Arrange
    var agent = await GetGrainAsync<IMyAgent>(Guid.NewGuid());
    var testEvent = new MyEvent { Data = "test" };
    
    // Act
    await agent.HandleEventAsync(testEvent);
    
    // Assert
    var state = await agent.GetStateAsync();
    state.Property.ShouldBe("test");
}
```

--------------------------------

### Aspire Authentication Flow

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/ai/aspire_references.md

Details the steps required to authenticate with Aspire services. It covers starting the Aspire Dashboard, logging in, retrieving an authentication token from the AuthServer API, and using the token for subsequent API requests.

```APIDOC
Authentication Flow:

1. Start Aspire Dashboard:
   Command: dotnet run
   Description: Execute in the Aspire project directory.

2. Dashboard Login:
   Action: Open the provided URL when the console displays the login prompt.
   URL Example: https://localhost:18888/login?t=<token>

3. Retrieve Auth Token:
   API Endpoint: http://localhost:7001/connect/token
   Description: Obtain the authentication key from the AuthServer API.

4. Use Auth Token:
   Method: Bearer authentication
   Description: Include the retrieved token in the Authorization header for all authenticated API requests.
```

--------------------------------

### Startup Speed Optimization

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide-zh.md

Lists commands and configurations to improve application startup speed, including pre-pulling Docker images, enabling Docker BuildKit, and using SSD storage for Docker data.

```bash
# 1. 预拉取Docker镜像
docker-compose pull

# 2. 启用Docker BuildKit
export DOCKER_BUILDKIT=1

# 3. 使用SSD存储Docker数据
# 在Docker Desktop设置中配置
```

--------------------------------

### Program.cs - Application Entry Point

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Developer.Host/README.md

The Program.cs file is the entry point for the Aevatar.Developer.Host application. It configures essential services such as logging, the Orleans client, and the web host, setting up the application's core infrastructure.

```C#
public class Program
{
    public static async Task<int> Main(string[] args)
    {
        // Configure logging
        Log.Logger = new LoggerConfiguration()
            .MinimumLevel.Information()
            .WriteTo.Console()
            .CreateLogger();

        try
        {
            var builder = WebApplication.CreateBuilder(args);

            // Configure Orleans client
            builder.Host.UseOrleansClient(clientBuilder =>
            {
                clientBuilder.UseLocalhostClustering();
            });

            // Configure web host and ABP module
            builder.Services.AddApplication<AevatarDeveloperHostModule>();

            var app = builder.Build();

            // Configure middleware (e.g., exception handling, Swagger, CORS)
            app.UseAbpFramework(
                options => {
                    // Configure options
                }
            );
            app.UseSwaggerUI();
            app.UseCors();
            app.UseRouting();
            app.UseAuthentication();
            app.UseAuthorization();
            app.MapControllers();

            await app.InitializeApplicationAsync();
            await app.RunAsync();
            return 0;
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Application terminated unexpectedly");
            return 1;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}
```

--------------------------------

### Module Registration Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.AuthServer.Grants/README.md

This C# code demonstrates how to register the `AevatarAuthServerGrantsModule` within an ABP (Abp.io) application module. It uses the `DependsOn` attribute to ensure the grants module is included in the application's dependency injection setup.

```csharp
[DependsOn(typeof(AevatarAuthServerGrantsModule))]
public class YourAppModule : AbpModule
{
    // Module will automatically register all grant handlers
}
```

--------------------------------

### Functional Test Case Structure Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/test-case-generation-guidelines.md

Illustrates the hierarchical markdown structure for organizing functional test cases, including document title, feature modules, test focuses, verification points, and test scenarios.

```markdown
# XX Functional Test Cases
## Feature Module Name
### Test Focus 1 (e.g., Avatar Settings)
#### Verification Point 1.1 (e.g., Upload Rule Validation)
##### Test Scenario 1.1.1
###### Expected Result
Expected result details 1
##### Test Scenario 1.1.2
###### Expected Result
Expected result details 2
#### Verification Point 1.2 (e.g., Default Logic Check)
##### Test Scenario 1.2.1
###### Expected Result
- Expected result details 1
### Test Focus 2 (e.g., Nickname Rules)
#### Verification Point 2.1 (e.g., Format Rule Check)
##### Test Scenario 2.1.1
###### Expected Result
Expected result details 1
```

--------------------------------

### ABP Module Configuration Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Application.Contracts/README.md

Illustrates the entry point for the Aevatar.Application.Contracts module, showing its configuration of dependencies and extension points, including its reliance on domain shared modules and ABP framework contract modules.

```cs
// AevatarApplicationContractsModule.cs: The entry point for the module
[DependsOn(typeof(AbpDaprModule), typeof(AbpAspNetCoreMvcDaprEventBusModule))]
public class AevatarApplicationContractsModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        // Configuration logic here
    }
}
```

--------------------------------

### Development Commands

Source: https://github.com/aevatarai/aevatar-station/blob/dev/CLAUDE.md

Common bash commands for building, testing, formatting, and starting the Aevatar Station services. Includes commands for running database migrations, the authentication server, the Silo host, and the HTTP API host.

```bash
# Build & Test
dotnet build
dotnet test
dotnet format && dotnet build --no-incremental  # Pre-commit

# Start Services (in order)
cd station/src/Aevatar.DbMigrator && dotnet run
cd ../Aevatar.AuthServer && dotnet run
cd ../Aevatar.Silo && dotnet run
cd ../Aevatar.HttpApi.Host && dotnet run

# Specific Tests
dotnet test framework/test/Aevatar.Core.Tests --filter "FullyQualifiedName~[TestClass]" --verbosity normal
```

--------------------------------

### Quick Reference Index

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/core-metrics-design.md

Links to key configuration files and external documentation relevant to the Aevatar Agent Platform's metrics and monitoring setup.

```markdown
- [Core Metrics Requirements Document](Core_Metrics_Requirements_Document.md)
- [docker-compose.yml](../src/Aevatar.Aspire/docker-compose.yml)
- [otel-collector-config.yaml](../src/Aevatar.Aspire/otel-collector-config.yaml)
- [prometheus.yml](../src/Aevatar.Aspire/prometheus.yml)
- [Orleans Monitoring Docs](https://learn.microsoft.com/en-us/dotnet/orleans/host/monitoring/?pivots=orleans-7-0)
- [OpenTelemetry .NET](https://opentelemetry.io/docs/instrumentation/net/)
- [Prometheus Docs](https://prometheus.io/docs/introduction/overview/)
- [Grafana Docs](https://grafana.com/docs/)
- [AevatarStation Source](../../aevatar-station/)
- [AevatarFramework Source](../../aevatar-framework/)
- [Orleans Fork Source](../../non-fork/orleans/)
```

--------------------------------

### Display Help Information

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Aspire/README.md

Displays the command-line help information for the `dotnet run` command, showing available options and usage.

```bash
dotnet run --help
```

--------------------------------

### Example Analysis Approach

Source: https://github.com/aevatarai/aevatar-station/blob/dev/technical-documentation-practices.md

Describes a systematic approach to analyzing the codebase for documentation generation, focusing on entry points, data flow, abstractions, and dependencies.

```markdown
## Example Analysis Approach

When analyzing the codebase:

1. **Start with entry points** (main methods, startup classes, controllers)
2. **Follow the data flow** through the system
3. **Identify key abstractions** and their implementations
4. **Map dependencies** between components
5. **Extract configuration patterns** and requirements
6. **Document extension mechanisms** and customization points
7. **Identify operational concerns** (logging, monitoring, error handling)

Generate documentation that would enable a new developer to understand the system architecture, set up a development environment, and contribute effectively to the codebase within their first week.
```

--------------------------------

### Metric Naming Convention Best Practices

Source: https://github.com/aevatarai/aevatar-station/blob/dev/docs/custom-otel-metrics-tutorial.md

Provides examples of good and bad metric naming conventions. Good examples follow a framework pattern with clear, descriptive names, while bad examples are inconsistent and abbreviated.

```csharp
// ✅ Good - follows framework pattern
public const string UserRegistrationDuration = "myapp_user_registration_duration";
public const string ActiveConnections = "myapp_active_connections";

// ❌ Bad - inconsistent naming
public const string RegTime = "registration_time";
public const string Connections = "conn_count";
```

--------------------------------

### Build and Run Benchmark

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/benchmark/BroadcastLatencyBenchmark/README.md

Commands to build and run the Aevatar Station benchmark project using .NET CLI. Supports custom parameters for configuration.

```bash
# Navigate to project directory
cd station/benchmark/BroadcastLatencyBenchmark

# Build the project
dotnet build

# Run with default settings
dotnet run

# Run with custom parameters
dotnet run -- --subscriber-count 50 --duration 30 --verbose
```

--------------------------------

### Install .NET Aspire Workload

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Aspire/README.md

Installs the necessary .NET Aspire workload for developing and running Aspire applications. This is a prerequisite for setting up the project.

```bash
dotnet workload install aspire
```

--------------------------------

### Daily Development Workflow

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Steps for daily development, including checking infrastructure, starting the environment, and testing.

```bash
# 📅 Daily development process
1. Check infrastructure status
   docker-compose ps

2. Quick start development environment  
   cd src/Aevatar.Aspire
   dotnet run --skip-infrastructure

3. Develop code → Save → Auto hot reload ✨

4. Test and verify
   - Access Swagger UI to test APIs
   - View Orleans Dashboard to monitor status
   - Use Jaeger to trace request chains

5. Verify before committing code
   dotnet test  # Run all tests
```

--------------------------------

### Aevatar Platform v0.6 User Onboarding and Project Creation

Source: https://github.com/aevatarai/aevatar-station/blob/dev/docs/versions/aevatar-v0.6.md

Details the user onboarding process in Aevatar Platform v0.6, including first-time default project creation, unique slug and name generation, owner role initialization, and seeding starter workflows. It also covers login landing behavior, UI states, observability, concurrency, and edge cases for invite/org flows.

```APIDOC
User Onboarding & Project Creation (v0.6):

- First-Time Default Project Creation: Automatically creates a default project for new users.
- Unique Slug and Name Generation: Ensures unique identifiers for projects and related entities.
- Owner Role and Permissions Initialization: Sets up initial roles and permissions for project owners.
- Seed Starter Workflow: Provides a default workflow to begin with.
- Login Landing Behavior and Precedence: Defines how users are directed after login.
- Onboarding UI States and Messaging: Manages the user interface during the onboarding process.
- Observability and Auditability: Implements logging and tracking for onboarding activities.
- Concurrency and Idempotency Guarantees: Ensures reliable execution under concurrent operations.
- Invite/Org Flow and Deleted-Only-Project Edge Cases: Handles scenarios related to invitations, organizations, and deleted projects.

Additional Onboarding at Organization Creation:
- Automatic Default Project Creation: Creates a default project when an organization is set up.
- User Navigation to Workflow Dashboard: Directs users to the workflow dashboard post-creation.
- Default Project Permissions and Configuration: Configures initial settings for the default project.
- Error Recovery and Fallback Mechanisms: Implements strategies for handling errors during onboarding.
```

--------------------------------

### Install Aevatar SignalR Package

Source: https://github.com/aevatarai/aevatar-station/blob/dev/signalR/README.md

Installs the Aevatar.SignalR NuGet package using the .NET CLI. This is the first step to integrate Aevatar SignalR into your project.

```bash
dotnet add package Aevatar.SignalR
```

--------------------------------

### Grafana Alert Rule Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

An example JSON configuration for a Grafana alert rule to monitor high API error rates.

```json
{
  "alert": {
    "name": "High Error Rate",
    "message": "API error rate exceeds 5%",
    "frequency": "10s",
    "conditions": [
      {
        "evaluator": {
          "params": [0.05],
          "type": "gt"
        }
      }
    ]
  }
}
```

--------------------------------

### Prompt Templates and Examples

Source: https://github.com/aevatarai/aevatar-station/blob/dev/docs/stories/1-8-prompt-based-workflow-creation-stories.md

Describes the availability of pre-built prompt templates and interactive examples to assist users in creating effective workflow prompts.

```APIDOC
PromptTemplatesAndExamples:
  - Templates: Pre-built templates for common workflow patterns (data processing, content generation, approval workflows).
  - Examples: Interactive examples that users can modify and learn from.
  - Suggestions: Contextual suggestions based on user's previous workflows.
```

--------------------------------

### Deployment Documentation Creation

Source: https://github.com/aevatarai/aevatar-station/blob/dev/technical-documentation-practices.md

Outlines the requirements for deployment documentation, including infrastructure, configuration, monitoring, and tuning.

```markdown
5. **Create Deployment Documentation**
   - Infrastructure requirements and recommendations
   - Configuration management
   - Monitoring and observability setup
   - Performance tuning guidelines
```

--------------------------------

### Monitoring Alert Configuration Example

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide-zh.md

Provides an example JSON structure for a Grafana alert rule, defining conditions for high error rates.

```json
{
  "alert": {
    "name": "High Error Rate",
    "message": "API错误率超过5%",
    "frequency": "10s",
    "conditions": [
      {
        "evaluator": {
          "params": [0.05],
          "type": "gt"
        }
      }
    ]
  }
}
```

--------------------------------

### Webhook Deployment Example (C#)

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.WebHook.Deploy/README.md

Demonstrates the process of deploying a webhook using the Aevatar.WebHook.Deploy library. It includes validation, artifact generation, deployment, and verification steps.

```csharp
public class WebhookDeployer
{
    private readonly IWebhookDeployService _deployService;
    
    public WebhookDeployer(IWebhookDeployService deployService)
    {
        _deployService = deployService;
    }
    
    public async Task DeployWebhookAsync(WebhookDeploymentOptions options)
    {
        // Validate the deployment configuration
        await _deployService.ValidateDeploymentAsync(options);
        
        // Generate deployment artifacts
        var artifacts = await _deployService.GenerateDeploymentArtifactsAsync(options);
        
        // Deploy the webhook
        var deploymentResult = await _deployService.DeployAsync(artifacts, options);
        
        // Verify the deployment
        await _deployService.VerifyDeploymentAsync(deploymentResult);
    }
}
```

--------------------------------

### Start Docker Infrastructure

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Aspire/dashboard/GRAFANA_DASHBOARD_README.md

Starts the Docker Compose services required for the Aevatar platform. This is a prerequisite for accessing the Grafana dashboard and collecting metrics.

```bash
cd src/Aevatar.Aspire
docker compose up -d
```

--------------------------------

### Aevatar.WebHook.Host Initialization and Configuration

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.WebHook.Host/README.md

Details the initial steps in Program.cs, including loading configuration from appsettings.json, setting up logging with Serilog, and initializing the Orleans cluster. This forms the foundational resonance for the application.

```csharp
public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            })
            .UseSerilog(); // Assuming Serilog is configured elsewhere
}
```

```json
{
  "WebhookId": "your-webhook-id",
  "Version": "1.0.0",
  "ApiHostUrl": "http://api.example.com",
  "Orleans": {
    "ClusterId": "aevatar-cluster",
    "ServiceId": "aevatar-service"
  }
}
```

--------------------------------

### Build the Solution

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/src/Aevatar.Aspire/README.md

Builds the entire .NET solution, compiling all projects within the repository. This ensures all code is up-to-date before running.

```bash
dotnet build
```

--------------------------------

### Install .NET Aspire Workload

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/docs/aspire-usage-guide.md

Installs the necessary .NET Aspire workload for developing and running Aspire applications. This is a prerequisite for using the Aevatar.Aspire platform.

```bash
dotnet workload install aspire
```

--------------------------------

### Program.cs - Main Entry Point

Source: https://github.com/aevatarai/aevatar-station/blob/dev/station/benchmark/LayeredLatencyBenchmark/README.md

The main entry point for the LayeredLatencyBenchmark application. It handles command-line argument parsing and orchestrates the benchmark execution.

```csharp
// Placeholder for Program.cs content
// Contains CLI argument parsing and benchmark orchestration.
```