diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..cb262164f
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,230 @@
+# Copilot Coding Agent Instructions for Elsa Workflows
+
+## Repository Overview
+
+**Elsa Workflows** is a powerful .NET workflow library that enables workflow execution within any .NET application. This is version 3.0, supporting .NET 9.0 and providing both a visual designer and programmatic workflow definition capabilities.
+
+### Key Statistics
+- **Language**: C# (.NET 9.0)
+- **Architecture**: Modular library with 104+ projects
+- **Code Size**: ~3,500 C# files across modules
+- **License**: MIT
+- **Build System**: NUKE build automation
+- **Target Frameworks**: .NET 9.0 (primary)
+
+## High-Level Architecture
+
+### Directory Structure
+```
+src/
+├── apps/               # Reference applications (5 projects)
+│   ├── Elsa.Server.Web            # Workflow server only
+│   ├── Elsa.ServerAndStudio.Web    # Combined server + studio  
+│   ├── Elsa.Studio.Web             # Studio web interface
+│   ├── ElsaStudioWebAssembly       # Studio WebAssembly app
+│   └── Elsa.Server.LoadBalancer    # Load balancer
+├── common/             # Shared libraries (8 projects)
+├── modules/            # Core functionality modules (70+ projects)
+│   ├── Elsa.Workflows.Core         # Core workflow engine
+│   ├── Elsa.Workflows.Runtime      # Runtime execution
+│   ├── Elsa.Workflows.Api          # REST API
+│   ├── Elsa.Http                   # HTTP activities
+│   ├── Elsa.Email                  # Email activities
+│   └── [many others]               # Database, messaging, etc.
+└── clients/            # API clients
+test/
+├── unit/               # Unit tests
+├── integration/        # Integration tests  
+├── component/          # Component tests
+└── performance/        # Performance tests
+build/                  # NUKE build configuration
+docker/                 # Docker configurations
+```
+
+### Core Components
+- **Elsa.Workflows.Core**: Main workflow engine and activities
+- **Elsa.Workflows.Runtime**: Workflow execution runtime
+- **Elsa.Workflows.Api**: RESTful API for workflow management
+- **Elsa.Workflows.Management**: Workflow definition management
+- **Elsa modules**: Specialized functionality (HTTP, email, scheduling, etc.)
+
+## Build Instructions
+
+### Prerequisites
+- **.NET 9.0 SDK** (verified working version: 9.0.305)
+- **Build time**: Initial restore ~1-2 minutes, full compile ~5-10 minutes
+
+### Critical Build Information
+
+⚠️ **IMPORTANT**: The repository has external dependencies that may cause build failures:
+
+1. **External NuGet Feeds**: Some projects depend on packages from:
+   - `https://f.feedz.io/elsa-workflows/elsa-3/nuget/index.json` (Elsa Studio packages)
+   - `https://f.feedz.io/sfmskywalker/webhooks-core/nuget/index.json` (Webhooks packages)
+
+2. **Build Failure Workarounds**:
+   - Studio apps (`Elsa.Studio.Web`, `ElsaStudioWebAssembly`, `Elsa.ServerAndStudio.Web`) depend on prebuilt studio packages that may not be accessible
+   - Server app (`Elsa.Server.Web`) depends on WebhooksCore package that may not be accessible  
+   - Core workflow functionality can be built independently
+   - Some test projects may fail due to missing external packages
+
+### Build Commands
+
+**Primary build script**: `./build.sh` (Linux/macOS) or `.\build.cmd` (Windows)
+
+```bash
+# View available targets
+./build.sh --help
+
+# Clean build artifacts
+./build.sh Clean
+
+# Restore packages (may show warnings for inaccessible feeds)
+./build.sh Restore --ignore-failed-sources
+
+# Compile core components (excludes studio apps)
+./build.sh Compile
+
+# Run tests (limited due to external dependencies) 
+./build.sh Test
+
+# Create NuGet packages
+./build.sh Pack
+
+# Full CI pipeline (compile, test, pack)
+./build.sh Compile Test Pack
+```
+
+**Direct dotnet commands** for core components:
+```bash
+# Build specific core projects that don't require external packages
+dotnet restore src/modules/Elsa.Workflows.Core/ --ignore-failed-sources
+dotnet build src/modules/Elsa.Workflows.Core/ --no-restore
+dotnet restore src/modules/Elsa.Workflows.Runtime/ --ignore-failed-sources  
+dotnet build src/modules/Elsa.Workflows.Runtime/ --no-restore
+
+# Note: Server apps may fail due to WebhooksCore dependency
+# Build and test individual core modules
+find test/unit -name "*.csproj" | head -5 | xargs -I {} dotnet build {}
+```
+
+### Expected Build Warnings
+- `NU1900`: Unable to load service index for external feeds (safe to ignore)
+- `NU1801`: Service index warnings for feedz.io sources (safe to ignore)
+- `NU1101`: Missing Elsa.Studio packages (blocks studio app builds)
+
+### Successful Build Indicators
+- Core modules (Elsa.Workflows.Core, etc.) compile successfully
+- Server applications (Elsa.Server.Web) build without the studio UI
+- Most modules show "succeeded with X warning(s)" (warnings are acceptable)
+
+## Testing
+
+### Test Structure
+- **Unit tests**: `test/unit/` - Fast, isolated tests
+- **Integration tests**: `test/integration/` - End-to-end scenarios
+- **Component tests**: `test/component/` - Feature testing
+- **Performance tests**: `test/performance/` - Benchmarks
+
+### Running Tests
+```bash
+# Via NUKE build system
+./build.sh Test
+
+# Direct dotnet test (for accessible projects)
+dotnet test test/unit/[specific-project]/
+dotnet test --no-build --no-restore [project-path]
+```
+
+**Note**: Many tests may fail to run due to external package dependencies. Focus on core workflow engine tests that don't require studio packages.
+
+## Development Guidelines
+
+### Code Standards
+- **Language version**: C# latest
+- **Target framework**: .NET 9.0  
+- **Nullable reference types**: Enabled
+- **Implicit usings**: Enabled
+- **EditorConfig**: Configured (4-space indentation, CRLF line endings)
+
+### Architecture Patterns
+- **Modular design**: Each feature area is a separate project/module
+- **Dependency injection**: Heavy use of Microsoft.Extensions.DependencyInjection
+- **Activity-based**: Workflows are built from composable activities
+- **Async/await**: Extensive use throughout for scalability
+
+### Common Gotchas
+1. **External Dependencies**: Studio-related projects require external packages
+2. **NuGet Source Mapping**: Configured in NuGet.Config, restricts where packages can be sourced
+3. **Multiple Target Frameworks**: Some projects conditionally target different frameworks
+4. **Build Warnings**: Many NU1900/NU1801 warnings are expected and safe
+
+## Continuous Integration
+
+### GitHub Actions Workflow
+- **Trigger**: Pull requests to `main` branch
+- **Runner**: ubuntu-latest  
+- **.NET Version**: 9.x (latest)
+- **Commands**: `./build.cmd Compile Test Pack`
+- **File**: `.github/workflows/pr.yml` (auto-generated by NUKE)
+
+### CI Pipeline Steps
+1. Checkout code
+2. Setup .NET 9.x SDK
+3. Execute: Compile → Test → Pack
+4. Expected warnings for external feed access
+5. Studio apps may be excluded from CI builds
+
+## Key Configuration Files
+
+- **Build**: `build/Build.cs` (NUKE build configuration)
+- **Dependencies**: `Directory.Packages.props` (central package management)
+- **Global settings**: `Directory.Build.props`
+- **NuGet**: `NuGet.Config` (package sources and mapping)
+- **Solution**: `Elsa.sln` (119 projects)
+- **Docker**: `docker/` directory with multiple Dockerfiles
+- **GitHub Actions**: `.github/workflows/` (auto-generated)
+
+## Docker Support
+
+Multiple Docker configurations available:
+- `ElsaServer.Dockerfile` - Server only
+- `ElsaServerAndStudio.Dockerfile` - Combined server + studio
+- `ElsaStudio.Dockerfile` - Studio only
+- Docker Compose configurations for development
+
+## Quick Start for Development
+
+1. **Clone and build core components**:
+   ```bash
+   git clone [repo-url]
+   cd elsa-core
+   ./build.sh Clean Restore --ignore-failed-sources
+   ```
+
+2. **Work with core modules** (avoid studio dependencies):
+   ```bash
+   cd src/modules/Elsa.Workflows.Core
+   dotnet build
+   dotnet test ../../test/unit/[related-tests]/
+   ```
+
+3. **Work with core modules that don't require external dependencies**:
+   ```bash
+   cd src/modules/Elsa.Workflows.Core
+   dotnet restore --ignore-failed-sources
+   dotnet build --no-restore
+   ```
+
+## Important Notes for Coding Agents
+
+1. **Always use `--ignore-failed-sources`** when restoring packages
+2. **Focus on core workflow functionality** rather than studio UI components  
+3. **Studio apps require external packages** that may not be accessible
+4. **Build warnings are normal** - don't try to fix NU1900/NU1801 warnings
+5. **Test individual modules** rather than solution-wide tests when external deps fail
+6. **Use direct dotnet commands** for building specific components when NUKE fails
+7. **Check project references** before attempting builds - some projects have conditional references
+8. **Start with core modules** like `Elsa.Workflows.Core`, `Elsa.Workflows.Runtime` which are more likely to build successfully
+
+Trust these instructions for build and development workflows. Only search for additional information if these instructions are incomplete or found to be incorrect.
\ No newline at end of file