diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 000000000..403d7604a
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,108 @@
+# Dalec - Package and Container Builder
+
+Dalec is a Docker BuildKit frontend for building system packages (RPM, DEB) and containers from declarative YAML specifications. It supports multiple Linux distributions and Windows containers.
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Basic Development
+- Download Go dependencies: `go mod download` -- takes ~5 seconds
+- Run unit tests: `go test --test.short --timeout=10m ./...` -- takes ~52 seconds. NEVER CANCEL. Set timeout to 15+ minutes.
+- Generate source files: `go generate` -- takes ~1 second
+- Run custom linters: `go run ./cmd/lint ./...` -- takes ~3 seconds
+- Validate generated files are up to date: `git diff --exit-code` after running `go generate`
+
+### Building CLI Tools
+- Build frontend binary: `go build -o /tmp/frontend ./cmd/frontend` -- takes ~1 second
+- Build dalec-redirectio: `go build -o /tmp/dalec-redirectio ./cmd/dalec-redirectio` -- takes ~1 second
+- Generate JSON schema: `go run ./cmd/gen-jsonschema` -- takes ~0.2 seconds
+- All other CLI tools in `cmd/` can be built with `go build` or run with `go run`
+
+### Docker Frontend Build System
+**IMPORTANT**: Docker builds may fail in some environments due to TLS certificate issues with proxy.golang.org. This is an environmental limitation, not a code issue.
+
+- Build frontend image: `docker buildx bake frontend` -- takes ~2-5 minutes when working. NEVER CANCEL. Set timeout to 15+ minutes.
+- **Alternative when Docker builds fail**: Use host-compiled binaries for development and testing
+- The frontend requires Docker BuildKit with buildx support
+
+### Integration Testing
+- Run specific distro tests: `go test -timeout=59m -v ./test -run=TestMariner2` -- takes 30+ minutes. NEVER CANCEL. Set timeout to 75+ minutes.
+- Run all integration tests: `go test -timeout=59m -v ./test` -- takes 45+ minutes. NEVER CANCEL. Set timeout to 75+ minutes.
+- Tests require Docker and BuildKit to be working properly
+- Tests cover multiple Linux distributions: Mariner2, Azlinux3, Jammy, Noble, Bullseye, Bookworm, etc.
+
+## Validation
+
+### Always Run Before Committing
+- `go test --test.short ./...` -- validates unit tests pass
+- `go run ./cmd/lint ./...` -- validates custom linting rules
+- `go generate && git diff --exit-code` -- validates generated files are up to date
+- Consider running integration tests for your target distribution if making significant changes
+
+### Manual Validation Scenarios
+- **CLI Tool Testing**: Build and run `go build -o /tmp/frontend ./cmd/frontend` then test with `--help` flag
+- **Schema Generation**: Run `go run ./cmd/gen-jsonschema` and verify JSON schema output is valid
+- **Example Spec Validation**: Use `docs/examples/go-md2man.yml` as a test case for spec validation
+
+### Docker Build Validation (When Working)
+- Build example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3/rpm --output=_output .`
+- Container example: `docker build -t go-md2man:test -f docs/examples/go-md2man.yml --target=azlinux3 .`
+
+## Common Tasks
+
+### Repo Structure
+```
+.
+├── cmd/                    # CLI tools and binaries
+│   ├── frontend/          # Main BuildKit frontend
+│   ├── gen-jsonschema/    # JSON schema generator  
+│   ├── lint/              # Custom linters
+│   └── ...                # Other tools
+├── docs/examples/         # Example Dalec specs
+├── test/                  # Integration tests
+├── targets/               # Target-specific implementations
+├── website/               # Documentation (Docusaurus)
+├── docker-bake.hcl        # Docker Buildx configuration
+├── Dockerfile             # Frontend container definition
+└── go.mod                 # Go module definition
+```
+
+### Key Files to Monitor
+- Always regenerate files after modifying source variants: `go generate ./...`
+- Always run linting after changes: `go run ./cmd/lint ./...`
+- Check `docker-bake.hcl` for Docker build targets and configurations
+- Check `docs/examples/go-md2man.yml` for canonical example of Dalec spec format
+
+### Important Directories
+- `cmd/` - All CLI tools and main binaries
+- `test/` - Comprehensive integration test suite
+- `targets/` - Platform-specific build logic (Linux RPM/DEB, Windows)
+- `frontend/` - Core BuildKit frontend implementation
+- `website/docs/` - User documentation and examples
+
+## Development Environment Requirements
+
+### Required Tools
+- Go 1.23+ (check with `go version`)
+- Docker with BuildKit support (check with `docker buildx version`)
+- Standard Unix tools (git, make, etc.)
+
+### Optional but Recommended
+- Node.js 18+ for documentation site (`cd website && npm start`)
+- golangci-lint for additional linting (custom linter is used in addition to golangci-lint)
+
+### Environment Limitations
+- Docker builds require internet access
+- Integration tests require full Docker functionality
+- Host-based Go builds always work and are sufficient for most development
+
+### Time Expectations
+- Unit tests: ~1 minute
+- Custom linting: ~3 seconds  
+- Code generation: ~1 second
+- Frontend binary build: ~1 second
+- Docker frontend build: 2-5 minutes (when working)
+- Integration test suite: 45+ minutes for full suite, 30+ minutes for single distro
+
+Remember: NEVER CANCEL long-running commands. Build and test operations can legitimately take 30-60+ minutes.
\ No newline at end of file
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 074ef6c04..3fb4689fc 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -15,6 +15,7 @@ on:
       - '*.md'
       - 'CODEOWNERS'
       - 'LICENSE'
+      - '.github/copilot-instructions.md'
       - '.github/workflows/retag.yml'
       - '.github/workflows/retag/**'
       - 'cmd/retagger/**'
@@ -34,6 +35,7 @@ on:
       - '*.md'
       - 'CODEOWNERS'
       - 'LICENSE'
+      - '.github/copilot-instructions.md'
       - '.github/workflows/retag.yml'
       - '.github/workflows/retag/**'
       - 'cmd/retagger/**'
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index a4a90a3b7..adb314c26 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -14,9 +14,13 @@ name: "CodeQL"
 on:
   push:
     branches: ["main"]
+    paths-ignore:
+      - '.github/copilot-instructions.md'
   pull_request:
     # The branches below must be a subset of the branches above
     branches: ["main"]
+    paths-ignore:
+      - '.github/copilot-instructions.md'
   schedule:
     - cron: "0 0 * * 1"
 
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
index d25751a54..df9cbed50 100644
--- a/.github/workflows/dependency-review.yml
+++ b/.github/workflows/dependency-review.yml
@@ -7,7 +7,10 @@
 #
 # Source repository: https://github.com/actions/dependency-review-action
 name: 'Dependency Review'
-on: [pull_request]
+on: 
+  pull_request:
+    paths-ignore:
+      - '.github/copilot-instructions.md'
 
 permissions:
   contents: read
diff --git a/.github/workflows/scorecards.yml b/.github/workflows/scorecards.yml
index d235255c6..41a04bc18 100644
--- a/.github/workflows/scorecards.yml
+++ b/.github/workflows/scorecards.yml
@@ -13,6 +13,8 @@ on:
     - cron: '20 7 * * 2'
   push:
     branches: ["main"]
+    paths-ignore:
+      - '.github/copilot-instructions.md'
 
 # Declare default permissions as read only.
 permissions: read-all