@agents-at-scale/ark 0.1.36 → 0.1.38

package/templates/mcp-server/examples/{{ .Values.mcpServerName }}-agent.yaml

@@ -0,0 +1,33 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: sample-{{ .Values.mcpServerName }}-agent
+  labels:
+    app.kubernetes.io/name: {{ .Values.mcpServerName }}
+    app.kubernetes.io/component: agent
+spec:
+  model:
+    name: default
+  system: |
+    You are an AI assistant that can use {{ .Values.mcpServerName }} tools to help users.
+    
+    Available tools from {{ .Values.mcpServerName }}:
+{{- range .Values.tools }}
+    - {{ .name }}: {{ .description }}
+{{- end }}
+    
+    Use these tools when appropriate to help users with their requests.
+  
+  tools:
+    - mcpServers:
+        - name: {{ .Values.mcpServerName }}-server
+{{- if .Values.toolConfigurations }}
+{{- range .Values.toolConfigurations }}
+    - name: {{ .name }}
+      description: {{ .description }}
+{{- if .parameters }}
+      parameters:
+{{- toYaml .parameters | nindent 8 }}
+{{- end }}
+{{- end }}
+{{- end }}

package/templates/mcp-server/examples/{{ .Values.mcpServerName }}-query.yaml

@@ -0,0 +1,24 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Query
+metadata:
+  name: test-{{ .Values.mcpServerName }}-query
+  labels:
+    app.kubernetes.io/name: {{ .Values.mcpServerName }}
+    app.kubernetes.io/component: query
+spec:
+  agents:
+    - name: sample-{{ .Values.mcpServerName }}-agent
+  
+  query: |
+{{- if .Values.sampleQuery }}
+    {{ .Values.sampleQuery }}
+{{- else }}
+    Test the {{ .Values.mcpServerName }} MCP server by using its available tools.
+    {{- range .Values.tools }}
+    Please try using the {{ .name }} tool.
+    {{- end }}
+{{- end }}
+  
+  parameters:
+    timeout: "5m"
+    maxTokens: 1000

package/templates/models/azure.yaml

@@ -0,0 +1,33 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Values.modelName }}-model-token
+type: Opaque
+stringData:
+  # IMPORTANT: Environment variables must be substituted before applying
+  # Use one of these methods:
+  #   1. make models-apply (recommended)
+  #   2. make quickstart (full deployment)
+  #   3. make fix-models (if you have broken queries)
+  # Manual: export AZURE_API_KEY="key" && envsubst < models/{{ .Values.modelName }}.yaml | kubectl apply -f -
+  token: ${AZURE_API_KEY}
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Model
+metadata:
+  name: {{ .Values.modelName }}
+spec:
+  type: azure
+  model:
+    value: gpt-4.1-mini
+  config:
+    azure:
+      baseUrl:
+        value: ${AZURE_BASE_URL}
+      apiKey:
+        valueFrom:
+          secretKeyRef:
+            name: {{ .Values.modelName }}-model-token
+            key: token
+      apiVersion:
+        value: ${AZURE_API_VERSION}

package/templates/models/claude.yaml

@@ -0,0 +1,28 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Values.modelName }}-api-key
+type: Opaque
+stringData:
+  # Make sure to use
+  # export CLAUDE_API_KEY="key"
+  # envsubst < models/{{ .Values.modelName }}.yaml | kubectl apply -f -
+  apiKey: ${CLAUDE_API_KEY}
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Model
+metadata:
+  name: {{ .Values.modelName }}
+spec:
+  type: openai
+  model:
+    value: claude-opus-4-20250514
+  config:
+    openai:
+      baseUrl:
+        value: ${CLAUDE_BASE_URL}
+      apiKey:
+        valueFrom:
+          secretKeyRef:
+            name: {{ .Values.modelName }}-api-key
+            key: apiKey

package/templates/models/gemini.yaml

@@ -0,0 +1,28 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Values.modelName }}-model-token
+type: Opaque
+stringData:
+  # Make sure to use
+  # export GEMINI_API_KEY="key"
+  # envsubst < models/{{ .Values.modelName }}.yaml | kubectl apply -f -
+  token: ${GEMINI_API_KEY}
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Model
+metadata:
+  name: {{ .Values.modelName }}
+spec:
+  type: openai
+  model:
+    value: gemini-2.0-flash
+  config:
+    openai:
+      baseUrl:
+        value: ${GEMINI_BASE_URL}
+      apiKey:
+        valueFrom:
+          secretKeyRef:
+            name: {{ .Values.modelName }}-model-token
+            key: token

package/templates/models/openai.yaml

@@ -0,0 +1,39 @@
+apiVersion: v1
+kind: Secret
+metadata:
+  name: {{ .Values.modelName }}-secret
+type: Opaque
+stringData:
+  # Make sure to use
+  # export OPENAI_API_KEY="key"
+  # envsubst < models/{{ .Values.modelName }}.yaml | kubectl apply -f -
+  token: ${OPENAI_API_KEY}
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Model
+metadata:
+  name: {{ .Values.modelName }}
+spec:
+  type: openai
+  model:
+    value: gpt-4.1-mini
+  config:
+    openai:
+      properties:
+        temperature:
+          value: "0.7"
+        max_tokens:
+          value: "2000"
+        top_p:
+          value: "0.95"
+        logprobs:
+          value: "true"
+        top_logprobs:
+          value: "5"
+      baseUrl:
+        value: ${OPENAI_BASE_URL}
+      apiKey:
+        valueFrom:
+          secretKeyRef:
+            name: {{ .Values.modelName }}-secret
+            key: token

package/templates/project/.editorconfig

@@ -0,0 +1,24 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.{yaml,yml}]
+indent_size = 2
+
+[*.{js,ts,jsx,tsx}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

package/templates/project/.helmignore

@@ -0,0 +1,24 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/
+# Build artifacts
+resources/

package/templates/project/.prettierrc.json

@@ -0,0 +1,16 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "bracketSpacing": false,
+  "overrides": [
+    {
+      "files": ["*.yaml", "*.yml"],
+      "options": {
+        "bracketSpacing": false,
+        "singleQuote": false
+      }
+    }
+  ]
+}

package/templates/project/.yamllint.yml

@@ -0,0 +1,50 @@
+# YAML Lint configuration for agent project
+
+extends: default
+
+rules:
+  # Allow longer lines for readability
+  line-length:
+    max: 120
+    level: warning
+
+  # Allow indentation for readability in YAML
+  indentation:
+    spaces: 2
+    indent-sequences: true
+    check-multi-line-strings: false
+
+  # Be more flexible with comments
+  comments:
+    min-spaces-from-content: 1
+
+  # Allow empty values for optional fields
+  empty-values:
+    forbid-in-block-mappings: false
+    forbid-in-flow-mappings: true
+
+  # Allow truthy values (on/off, yes/no)
+  truthy:
+    allowed-values: ["true", "false", "on", "off", "yes", "no"]
+
+  # Allow document start/end markers
+  document-start:
+    present: false
+
+  # Allow multiple documents in one file
+  document-end:
+    present: false
+
+  # Allow braces for Golang template syntax (Helm templates)
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+    min-spaces-inside-empty: 0
+    max-spaces-inside-empty: 0
+
+  # Don't enforce bracket spacing for template syntax
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+    min-spaces-inside-empty: 0
+    max-spaces-inside-empty: 0

package/templates/project/Chart.yaml

@@ -0,0 +1,19 @@
+apiVersion: v2
+name: {{.Values.projectName}}
+description: A Helm chart for {{ .Values.projectName }} - Agents at Scale project
+type: application
+version: 0.1.0
+appVersion: "1.0.0"
+home: https://github.com/your-org/{{ .Values.projectName }}
+sources:
+  - https://github.com/your-org/{{ .Values.projectName }}
+maintainers:
+  - name: {{.Values.authorName}}
+    email: {{.Values.authorEmail}}
+keywords:
+  - agents
+  - ai
+  - automation
+  - ark
+annotations:
+  category: AI/ML

package/templates/project/Makefile

@@ -0,0 +1,360 @@
+# Makefile for Agent Project Template
+# 
+# This Makefile provides commands for building, testing, and deploying
+# your agent project to the Agents at Scale platform.
+
+# Load environment variables from .env file if it exists
+-include .env
+export
+
+# Configuration
+PROJECT_NAME ?= {{ .Values.projectName }}
+NAMESPACE ?= $(PROJECT_NAME)
+CHART_VERSION ?= 0.1.0
+IMAGE_TAG ?= latest
+REGISTRY ?= localhost:5000
+
+# Helm and kubectl
+HELM := helm
+KUBECTL := kubectl
+
+# Tool directories
+TOOLS_DIR := tools
+CHART_DIR := .
+
+# Build output
+OUT_DIR := out
+DOCKER_BUILD_DIR := $(OUT_DIR)/docker
+
+.PHONY: help
+help: ## Show this help message
+	@echo "🚀 Quick Commands:"
+	@echo "  make quickstart     # 5-minute setup with proper resource dependency handling"
+	@echo "  make resources-apply # Apply all custom resources in correct order"
+	@echo "  make fix-models     # Fix broken models (if you have query errors)"
+	@echo ""
+	@echo "📚 All Commands:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+
+.PHONY: quickstart
+quickstart: ## 5-minute setup and deploy to ARK
+	@echo "🚀 Quick Start - Deploying to Agents at Scale..."
+	@echo "📋 Checking prerequisites..."
+	@if [ -z "$$OPENAI_API_KEY" ] && [ -z "$$AZURE_API_KEY" ] && [ -z "$$AZURE_OPENAI_API_KEY" ]; then echo "❌ Please set OPENAI_API_KEY, AZURE_API_KEY, or AZURE_OPENAI_API_KEY in .env file"; exit 1; fi
+	@$(KUBECTL) version --client > /dev/null || (echo "❌ kubectl not found" && exit 1)
+	@$(HELM) version > /dev/null || (echo "❌ helm not found" && exit 1)
+	@command -v envsubst >/dev/null 2>&1 || (echo "❌ envsubst not found (install gettext package)" && exit 1)
+	@echo "✅ Prerequisites check passed"
+	@echo "🔐 Creating namespace..."
+	@$(KUBECTL) create namespace $(NAMESPACE) --dry-run=client -o yaml | $(KUBECTL) apply -f -
+	@echo "🚀 Deploying infrastructure (without custom resources)..."
+	@$(MAKE) build install-no-resources
+	@echo "🚀 Deploying custom resources in dependency order..."
+	@$(MAKE) resources-apply
+	@echo "✅ Quick start complete! Your agents are running on Kubernetes."
+	@if [ -d queries ] && [ -n "$$(find queries -name "*.yaml" -type f | head -1)" ]; then \
+		FIRST_QUERY=$$(find queries -name "*.yaml" -type f | head -1); \
+		QUERY_NAME=$$(grep -E "^[[:space:]]*name:" $$FIRST_QUERY | head -1 | sed 's/.*name:[[:space:]]*//'); \
+		echo "   Try: fark query $$QUERY_NAME --namespace $(NAMESPACE)"; \
+	fi
+
+.PHONY: all
+all: build test ## Build and test everything
+
+# Setup and initialization
+.PHONY: init
+init: ## Initialize project dependencies
+	@echo "Initializing project..."
+	@mkdir -p $(OUT_DIR) $(DOCKER_BUILD_DIR)
+	@if [ -f scripts/setup.sh ]; then ./scripts/setup.sh; fi
+
+.PHONY: clean
+clean: ## Clean build artifacts
+	@echo "Cleaning build artifacts..."
+	@rm -rf $(OUT_DIR)
+	@docker system prune -f
+
+# Building
+.PHONY: build
+build: tools-build chart-package ## Build all components
+
+.PHONY: tools-build
+tools-build: ## Build all custom tools
+	@echo "Building custom tools..."
+	@for tool in $(shell find $(TOOLS_DIR) -mindepth 1 -maxdepth 1 -type d -not -name examples); do \
+		if [ -f "$$tool/Dockerfile" ]; then \
+			echo "Building tool: $$(basename $$tool)"; \
+			docker build -t $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG) $$tool; \
+		fi; \
+	done
+
+.PHONY: chart-package
+chart-package: ## Package Helm chart
+	@echo "Packaging Helm chart..."
+	@$(HELM) package $(CHART_DIR) -d $(OUT_DIR) --version $(CHART_VERSION)
+
+# Testing
+.PHONY: test
+test: test-lint test-tools test-manifests ## Run all tests
+
+.PHONY: test-lint
+test-lint: ## Run linting on YAML files
+	@echo "Linting YAML files..."
+	@find agents teams queries models -name "*.yaml" -exec yamllint {} \; || true
+
+.PHONY: test-tools
+test-tools: ## Test custom tools
+	@echo "Testing custom tools..."
+	@for tool in $(shell find $(TOOLS_DIR) -mindepth 1 -maxdepth 1 -type d -not -name examples); do \
+		if [ -f "$$tool/test.py" ]; then \
+			echo "Testing tool: $$(basename $$tool)"; \
+			cd $$tool && python test.py; \
+		fi; \
+	done
+
+.PHONY: test-manifests
+test-manifests: ## Validate Kubernetes manifests
+	@echo "Validating Kubernetes manifests..."
+	@find agents teams queries models -name "*.yaml" -exec $(KUBECTL) apply --dry-run=client -f {} \; || true
+
+.PHONY: test-e2e
+test-e2e: ## Run end-to-end tests
+	@echo "Running end-to-end tests..."
+	@if [ -d tests/e2e ]; then \
+		$(KUBECTL) apply -f tests/e2e/; \
+		echo "E2E tests applied. Check results with: kubectl get queries -w"; \
+	fi
+
+# Development
+.PHONY: dev
+dev: dev-tools ## Run in development mode
+	@echo "Running in development mode..."
+	@echo "Use 'make dev-apply' to deploy manifests for testing"
+
+.PHONY: dev-tools
+dev-tools: ## Start tools in development mode
+	@echo "Starting tools in development mode..."
+	@for tool in $(shell find $(TOOLS_DIR) -mindepth 1 -maxdepth 1 -type d -not -name examples); do \
+		if [ -f "$$tool/main.py" ]; then \
+			echo "Starting tool: $$(basename $$tool) on port $$(( 8000 + $$(basename $$tool | wc -c) ))"; \
+			cd $$tool && python main.py --port $$(( 8000 + $$(basename $$tool | wc -c) )) & \
+		fi; \
+	done
+
+.PHONY: dev-apply
+dev-apply: ## Apply manifests for development testing
+	@echo "Applying development manifests..."
+	@find agents teams queries models -name "*.yaml" -exec $(KUBECTL) apply -f {} \;
+
+.PHONY: dev-clean
+dev-clean: ## Clean development resources
+	@echo "Cleaning development resources..."
+	@find agents teams queries models -name "*.yaml" -exec $(KUBECTL) delete -f {} \; || true
+
+# Deployment
+.PHONY: install
+install: check-env build ## Deploy to ARK cluster
+	@echo "Deploying to ARK cluster..."
+	@$(HELM) upgrade --install $(PROJECT_NAME) $(CHART_DIR) \
+		--namespace $(NAMESPACE) \
+		--create-namespace \
+		--set image.tag=$(IMAGE_TAG) \
+		--set project.name=$(PROJECT_NAME) \
+		--wait
+
+.PHONY: install-no-resources
+install-no-resources: check-env build ## Deploy to ARK cluster without custom resources (resources handled separately)
+	@echo "Deploying to ARK cluster (excluding custom resources)..."
+	@$(HELM) upgrade --install $(PROJECT_NAME) $(CHART_DIR) \
+		--namespace $(NAMESPACE) \
+		--create-namespace \
+		--set image.tag=$(IMAGE_TAG) \
+		--set project.name=$(PROJECT_NAME) \
+		--set excludeResources=true \
+		--wait
+
+.PHONY: uninstall
+uninstall: ## Remove from ARK cluster
+	@echo "Removing from ARK cluster..."
+	@$(HELM) uninstall $(PROJECT_NAME) --namespace $(NAMESPACE) || true
+
+.PHONY: upgrade
+upgrade: build ## Upgrade deployment
+	@echo "Upgrading deployment..."
+	@$(HELM) upgrade $(PROJECT_NAME) $(CHART_DIR) \
+		--namespace $(NAMESPACE) \
+		--set image.tag=$(IMAGE_TAG) \
+		--set project.name=$(PROJECT_NAME) \
+		--wait
+
+.PHONY: status
+status: ## Check deployment status
+	@echo "Deployment status:"
+	@$(HELM) status $(PROJECT_NAME) --namespace $(NAMESPACE) || echo "Not deployed"
+	@echo "\nResources:"
+	@$(KUBECTL) get agents,teams,queries,models,mcpservers -n $(NAMESPACE) -l project=$(PROJECT_NAME) || true
+
+# Image management
+.PHONY: images-push
+images-push: tools-build ## Push images to registry
+	@echo "Pushing images to registry..."
+	@for tool in $(shell find $(TOOLS_DIR) -mindepth 1 -maxdepth 1 -type d -not -name examples); do \
+		if [ -f "$$tool/Dockerfile" ]; then \
+			echo "Pushing: $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG)"; \
+			docker push $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG); \
+		fi; \
+	done
+
+.PHONY: images-load
+images-load: tools-build ## Load images into local cluster (kind/minikube)
+	@echo "Loading images into local cluster..."
+	@for tool in $(shell find $(TOOLS_DIR) -mindepth 1 -maxdepth 1 -type d -not -name examples); do \
+		if [ -f "$$tool/Dockerfile" ]; then \
+			echo "Loading: $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG)"; \
+			kind load docker-image $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG) || \
+			minikube image load $(REGISTRY)/$(PROJECT_NAME)-$$(basename $$tool):$(IMAGE_TAG) || \
+			echo "Could not load image (not using kind or minikube?)"; \
+		fi; \
+	done
+
+# Utilities
+.PHONY: check-env
+check-env: ## Check required environment variables
+	@echo "Checking environment..."
+	@if [ -z "$$OPENAI_API_KEY" ] && [ -z "$$AZURE_API_KEY" ] && [ -z "$$AZURE_OPENAI_API_KEY" ] && [ -z "$$ANTHROPIC_API_KEY" ]; then \
+		echo "Warning: No model API keys set. Set at least one of:"; \
+		echo "  AZURE_API_KEY, OPENAI_API_KEY, AZURE_OPENAI_API_KEY, ANTHROPIC_API_KEY"; \
+		echo "  (preferably in .env file)"; \
+	fi
+	@$(KUBECTL) version --client > /dev/null || (echo "Error: kubectl not found" && exit 1)
+	@$(HELM) version > /dev/null || (echo "Error: helm not found" && exit 1)
+	@command -v envsubst >/dev/null 2>&1 || (echo "Warning: envsubst not found (install gettext package for .env substitution)")
+
+.PHONY: models-apply
+models-apply: ## Apply model configurations with environment variable substitution (requires .env file)
+	@echo "Applying models with environment variable substitution..."
+	@echo "ℹ️  This substitutes environment variables like \$$AZURE_BASE_URL, \$$AZURE_API_VERSION from .env file"
+	@for model_file in models/*.yaml; do \
+		if [ -f "$$model_file" ]; then \
+			echo "Applying $$model_file..."; \
+			envsubst < "$$model_file" | $(KUBECTL) apply -f - --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "✅ Models applied successfully. Any existing queries will need to be recreated to use the updated models."
+
+.PHONY: models-delete
+models-delete: ## Delete model configurations
+	@echo "Deleting model configurations..."
+	@for model_file in models/*.yaml; do \
+		if [ -f "$$model_file" ]; then \
+			echo "Deleting resources from $$model_file..."; \
+			envsubst < "$$model_file" | $(KUBECTL) delete -f - --namespace=$(NAMESPACE) || true; \
+		fi; \
+	done
+
+.PHONY: fix-models
+fix-models: ## Fix models with proper environment variable substitution and restart queries
+	@echo "🔧 Fixing model configurations..."
+	@$(MAKE) models-apply
+	@echo "🔄 Restarting any existing queries to use updated models..."
+	@$(KUBECTL) get queries -n $(NAMESPACE) --no-headers -o custom-columns=NAME:.metadata.name 2>/dev/null | xargs -r -I {} $(KUBECTL) delete query {} -n $(NAMESPACE) --ignore-not-found=true || true
+	@echo "✅ Models fixed! You can now recreate your queries and they should work properly."
+
+.PHONY: resources-apply
+resources-apply: ## Apply all custom resources in dependency order (models → mcp-servers → tools → agents → teams → queries)
+	@echo "🚀 Applying custom resources in dependency order..."
+	@echo "📋 Step 1: Applying models with environment substitution..."
+	@for model_file in models/*.yaml; do \
+		if [ -f "$$model_file" ]; then \
+			echo "Applying $$model_file..."; \
+			envsubst < "$$model_file" | $(KUBECTL) apply -f - --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "📋 Step 2: Applying MCP servers with environment substitution..."
+	@for mcp_file in mcp-servers/*.yaml; do \
+		if [ -f "$$mcp_file" ]; then \
+			echo "Applying $$mcp_file..."; \
+			envsubst < "$$mcp_file" | $(KUBECTL) apply -f - --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "📋 Step 3: Applying tools with environment substitution..."
+	@for tool_file in tools/*.yaml; do \
+		if [ -f "$$tool_file" ]; then \
+			echo "Applying $$tool_file..."; \
+			envsubst < "$$tool_file" | $(KUBECTL) apply -f - --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "📋 Step 4: Applying agents..."
+	@for agent_file in agents/*.yaml; do \
+		if [ -f "$$agent_file" ]; then \
+			echo "Applying $$agent_file..."; \
+			$(KUBECTL) apply -f "$$agent_file" --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "📋 Step 5: Applying teams..."
+	@for team_file in teams/*.yaml; do \
+		if [ -f "$$team_file" ]; then \
+			echo "Applying $$team_file..."; \
+			$(KUBECTL) apply -f "$$team_file" --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "📋 Step 6: Applying queries..."
+	@for query_file in queries/*.yaml; do \
+		if [ -f "$$query_file" ]; then \
+			echo "Applying $$query_file..."; \
+			$(KUBECTL) apply -f "$$query_file" --namespace=$(NAMESPACE); \
+		fi; \
+	done
+	@echo "✅ All custom resources applied successfully in dependency order."
+
+.PHONY: logs
+logs: ## Show logs from deployed components
+	@echo "Showing logs..."
+	@$(KUBECTL) logs -l project=$(PROJECT_NAME) -n $(NAMESPACE) --tail=100 -f
+
+.PHONY: shell
+shell: ## Open shell in a tool pod
+	@echo "Opening shell in tool pod..."
+	@$(KUBECTL) exec -it -n $(NAMESPACE) $$($(KUBECTL) get pods -l project=$(PROJECT_NAME) -n $(NAMESPACE) -o jsonpath='{.items[0].metadata.name}') -- /bin/bash
+
+.PHONY: port-forward
+port-forward: ## Forward ports for local development
+	@echo "Setting up port forwarding..."
+	@$(KUBECTL) port-forward -n $(NAMESPACE) svc/$(PROJECT_NAME)-tools 8000:8000 &
+	@echo "Tools available at http://localhost:8000"
+
+# Documentation
+.PHONY: docs
+docs: ## Generate documentation
+	@echo "Generating documentation..."
+	@if [ -f scripts/generate-docs.sh ]; then ./scripts/generate-docs.sh; fi
+
+.PHONY: examples
+examples: ## Deploy example configurations
+	@echo "Deploying examples..."
+	@find agents teams queries models -name "*.yaml" -exec $(KUBECTL) apply -f {} \;
+
+# Monitoring and debugging
+.PHONY: debug
+debug: ## Show debugging information
+	@echo "=== Debugging Information ==="
+	@echo "Project: $(PROJECT_NAME)"
+	@echo "Namespace: $(NAMESPACE)"
+	@echo "Chart Version: $(CHART_VERSION)"
+	@echo "Image Tag: $(IMAGE_TAG)"
+	@echo ""
+	@echo "=== Kubernetes Resources ==="
+	@$(KUBECTL) get agents,teams,queries,models,mcpservers -n $(NAMESPACE) || true
+	@echo ""
+	@echo "=== Recent Events ==="
+	@$(KUBECTL) get events -n $(NAMESPACE) --sort-by='.lastTimestamp' | tail -10 || true
+
+.PHONY: validate
+validate: ## Validate all configurations
+	@echo "Validating configurations..."
+	@$(HELM) lint $(CHART_DIR)
+	@find agents teams queries models -name "*.yaml" -exec $(KUBECTL) apply --dry-run=server -f {} \;
+
+# Include custom makefiles if they exist
+-include Makefile.local
+-include scripts/Makefile.custom