From 62357c2f8820bdf153feb67cb6d6654d7e23db39 Mon Sep 17 00:00:00 2001
From: Devin Container Agent <devin-agent@container.local>
Date: Tue, 19 May 2026 08:24:10 +0000
Subject: [PATCH 1/4] test: add failing tests for OTel setup playbooks (Red)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Capture regression fixture from unmodified codebase and write test
suites (bash + PowerShell) covering setup/ playbook deployment,
agent-scoped wrappers, idempotency, and validate-config execution.

All new test cases fail (Red) as expected — setup/ content does not
exist yet.

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 tests/fixtures/assess-observability-skill.md |   7 +
 tests/test-deploy.ps1                        | 217 ++++++++++++++
 tests/test-deploy.sh                         | 283 +++++++++++++++++++
 3 files changed, 507 insertions(+)
 create mode 100644 tests/fixtures/assess-observability-skill.md
 create mode 100644 tests/test-deploy.ps1
 create mode 100644 tests/test-deploy.sh

diff --git a/tests/fixtures/assess-observability-skill.md b/tests/fixtures/assess-observability-skill.md
new file mode 100644
index 0000000..40f4aab
--- /dev/null
+++ b/tests/fixtures/assess-observability-skill.md
@@ -0,0 +1,7 @@
+---
+name: assess-observability
+description: "Run observability maturity assessment covering distributed tracing, structured logging, metrics, health checks, and OpenTelemetry compliance"
+allowed-tools: "Read, Grep, Glob, Bash(git *), Write, Edit, Agent"
+---
+
+Read and follow `.context/playbooks/assess/observability.md` in full.
diff --git a/tests/test-deploy.ps1 b/tests/test-deploy.ps1
new file mode 100644
index 0000000..42cc6fe
--- /dev/null
+++ b/tests/test-deploy.ps1
@@ -0,0 +1,217 @@
+#!/usr/bin/env pwsh
+# Test suite for deploy.ps1 — verifies setup/ playbook deployment and regressions.
+#
+# Usage:
+#   pwsh ./tests/test-deploy.ps1
+#
+# Exit codes:
+#   0  All tests passed
+#   1  One or more tests failed
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $PSCommandPath
+$RepoDir = Split-Path -Parent $ScriptDir
+
+$script:Passed = 0
+$script:Failed = 0
+
+function Pass {
+    param([string]$Label)
+    Write-Host "  PASS: $Label"
+    $script:Passed++
+}
+
+function Fail {
+    param([string]$Label)
+    Write-Host "  FAIL: $Label"
+    $script:Failed++
+}
+
+function Assert-FileExists {
+    param([string]$Label, [string]$Path)
+    if (Test-Path $Path -PathType Leaf) {
+        Pass "$Label exists"
+    } else {
+        Fail "$Label does not exist: $Path"
+    }
+}
+
+function Assert-FileNotExists {
+    param([string]$Label, [string]$Path)
+    if (-not (Test-Path $Path -PathType Leaf)) {
+        Pass "$Label does not exist (expected)"
+    } else {
+        Fail "$Label unexpectedly exists: $Path"
+    }
+}
+
+function Assert-DirNotExists {
+    param([string]$Label, [string]$Path)
+    if (-not (Test-Path $Path -PathType Container)) {
+        Pass "$Label directory does not exist (expected)"
+    } else {
+        Fail "$Label directory unexpectedly exists: $Path"
+    }
+}
+
+function Assert-Executable {
+    param([string]$Label, [string]$Path)
+    if ($IsLinux -or $IsMacOS) {
+        if (Test-Path $Path) {
+            $mode = (Get-Item $Path).UnixMode
+            if ($mode -match 'x') {
+                Pass "$Label is executable"
+            } else {
+                Fail "$Label is not executable: $Path"
+            }
+        } else {
+            Fail "$Label does not exist: $Path"
+        }
+    } else {
+        # On Windows, skip execute bit check
+        Pass "$Label executable check skipped (Windows)"
+    }
+}
+
+function Assert-Contains {
+    param([string]$Label, [string]$Path, [string]$Expected)
+    if (Test-Path $Path) {
+        $content = Get-Content $Path -Raw
+        if ($content -match [regex]::Escape($Expected)) {
+            Pass "$Label contains '$Expected'"
+        } else {
+            Fail "$Label does not contain '$Expected'"
+        }
+    } else {
+        Fail "$Label file not found: $Path"
+    }
+}
+
+function Assert-NotContains {
+    param([string]$Label, [string]$Path, [string]$Unexpected)
+    if (Test-Path $Path) {
+        $content = Get-Content $Path -Raw
+        if ($content -notmatch [regex]::Escape($Unexpected)) {
+            Pass "$Label does not contain '$Unexpected'"
+        } else {
+            Fail "$Label unexpectedly contains '$Unexpected'"
+        }
+    } else {
+        Fail "$Label file not found: $Path"
+    }
+}
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC1: Fresh deploy — all agents
+# ═══════════════════════════════════════════════════════════════════════
+Write-Host ""
+Write-Host "=== TC1: Fresh deploy — all agents ==="
+$tc1Dir = Join-Path ([System.IO.Path]::GetTempPath()) "tc1-$([guid]::NewGuid().ToString('N').Substring(0,8))"
+New-Item -ItemType Directory -Path $tc1Dir -Force | Out-Null
+& "$RepoDir/deploy.ps1" -Agents all -Overwrite -Target $tc1Dir *>$null
+
+Write-Host "  --- Playbook files ---"
+Assert-FileExists "create-local-otel-stack.md" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack.md"
+Assert-FileExists "discover-local-otel-stack.md" "$tc1Dir/.context/playbooks/setup/discover-local-otel-stack.md"
+Assert-FileExists "use-local-otel-stack.md" "$tc1Dir/.context/playbooks/setup/use-local-otel-stack.md"
+Assert-FileExists "instrument-dotnet-otel.md" "$tc1Dir/.context/playbooks/setup/instrument-dotnet-otel.md"
+
+Write-Host "  --- Companion scripts ---"
+Assert-FileExists "start-local-otel-stack.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh"
+Assert-Executable "start-local-otel-stack.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh"
+Assert-FileExists "test-local-otel-stack.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh"
+Assert-Executable "test-local-otel-stack.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh"
+Assert-FileExists "validate-config.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/validate-config.sh"
+Assert-Executable "validate-config.sh" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/validate-config.sh"
+
+Write-Host "  --- Non-executable files ---"
+Assert-FileExists "Start-LocalOtelStack.ps1" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1"
+Assert-FileExists "versions.env" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack/versions.env"
+
+Write-Host "  --- Claude thin wrappers ---"
+Assert-FileExists "claude/setup-create-local-otel-stack" "$tc1Dir/.claude/skills/setup-create-local-otel-stack/SKILL.md"
+Assert-FileExists "claude/setup-discover-local-otel-stack" "$tc1Dir/.claude/skills/setup-discover-local-otel-stack/SKILL.md"
+Assert-FileExists "claude/setup-use-local-otel-stack" "$tc1Dir/.claude/skills/setup-use-local-otel-stack/SKILL.md"
+Assert-FileExists "claude/setup-instrument-dotnet-otel" "$tc1Dir/.claude/skills/setup-instrument-dotnet-otel/SKILL.md"
+
+Write-Host "  --- Copilot thin wrappers ---"
+Assert-FileExists "copilot/setup-create-local-otel-stack" "$tc1Dir/.github/skills/setup-create-local-otel-stack/SKILL.md"
+Assert-FileExists "copilot/setup-discover-local-otel-stack" "$tc1Dir/.github/skills/setup-discover-local-otel-stack/SKILL.md"
+Assert-FileExists "copilot/setup-use-local-otel-stack" "$tc1Dir/.github/skills/setup-use-local-otel-stack/SKILL.md"
+Assert-FileExists "copilot/setup-instrument-dotnet-otel" "$tc1Dir/.github/skills/setup-instrument-dotnet-otel/SKILL.md"
+
+Write-Host "  --- allowed-tools check ---"
+Assert-Contains "claude wrapper allowed-tools" "$tc1Dir/.claude/skills/setup-create-local-otel-stack/SKILL.md" "allowed-tools:"
+Assert-NotContains "claude wrapper no git-only bash" "$tc1Dir/.claude/skills/setup-create-local-otel-stack/SKILL.md" "Bash(git *)"
+
+Write-Host "  --- Safety and provenance ---"
+Assert-Contains "local-dev-only warning" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack.md" "Local development and testing only"
+Assert-Contains "provenance comment" "$tc1Dir/.context/playbooks/setup/create-local-otel-stack.md" "Ported from devopsin"
+
+Write-Host "  --- Index routing ---"
+Assert-Contains "index has setup playbooks" "$tc1Dir/.context/index.md" "playbooks/setup/"
+
+Write-Host "  --- Negative ---"
+Assert-FileNotExists "local-otel-stack.md" "$tc1Dir/.context/playbooks/setup/local-otel-stack.md"
+
+Remove-Item -Recurse -Force $tc1Dir
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC2: Agent-scoped deploy — Claude only
+# ═══════════════════════════════════════════════════════════════════════
+Write-Host ""
+Write-Host "=== TC2: Agent-scoped deploy — Claude only ==="
+$tc2Dir = Join-Path ([System.IO.Path]::GetTempPath()) "tc2-$([guid]::NewGuid().ToString('N').Substring(0,8))"
+New-Item -ItemType Directory -Path $tc2Dir -Force | Out-Null
+& "$RepoDir/deploy.ps1" -Agents claude -Overwrite -Target $tc2Dir *>$null
+
+Assert-FileExists "claude wrapper present" "$tc2Dir/.claude/skills/setup-create-local-otel-stack/SKILL.md"
+Assert-DirNotExists "copilot dir absent" "$tc2Dir/.github/skills/setup-create-local-otel-stack"
+
+Remove-Item -Recurse -Force $tc2Dir
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC3: Agent-scoped deploy — Copilot only
+# ═══════════════════════════════════════════════════════════════════════
+Write-Host ""
+Write-Host "=== TC3: Agent-scoped deploy — Copilot only ==="
+$tc3Dir = Join-Path ([System.IO.Path]::GetTempPath()) "tc3-$([guid]::NewGuid().ToString('N').Substring(0,8))"
+New-Item -ItemType Directory -Path $tc3Dir -Force | Out-Null
+& "$RepoDir/deploy.ps1" -Agents copilot -Overwrite -Target $tc3Dir *>$null
+
+Assert-FileExists "copilot wrapper present" "$tc3Dir/.github/skills/setup-create-local-otel-stack/SKILL.md"
+Assert-DirNotExists "claude dir absent" "$tc3Dir/.claude/skills/setup-create-local-otel-stack"
+
+Remove-Item -Recurse -Force $tc3Dir
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC4: No regressions — existing thin wrappers
+# ═══════════════════════════════════════════════════════════════════════
+Write-Host ""
+Write-Host "=== TC4: No regressions — existing thin wrappers ==="
+$tc4Dir = Join-Path ([System.IO.Path]::GetTempPath()) "tc4-$([guid]::NewGuid().ToString('N').Substring(0,8))"
+New-Item -ItemType Directory -Path $tc4Dir -Force | Out-Null
+& "$RepoDir/deploy.ps1" -Agents claude -Overwrite -Target $tc4Dir *>$null
+
+Assert-FileExists "assess-observability" "$tc4Dir/.claude/skills/assess-observability/SKILL.md"
+
+Remove-Item -Recurse -Force $tc4Dir
+
+# ═══════════════════════════════════════════════════════════════════════
+# Summary
+# ═══════════════════════════════════════════════════════════════════════
+Write-Host ""
+Write-Host "=== Results ==="
+Write-Host "  Passed: $($script:Passed)"
+Write-Host "  Failed: $($script:Failed)"
+
+if ($script:Failed -gt 0) {
+    Write-Host ""
+    Write-Host "TEST SUITE FAILED"
+    exit 1
+} else {
+    Write-Host ""
+    Write-Host "TEST SUITE PASSED"
+    exit 0
+}
diff --git a/tests/test-deploy.sh b/tests/test-deploy.sh
new file mode 100644
index 0000000..2bfea53
--- /dev/null
+++ b/tests/test-deploy.sh
@@ -0,0 +1,283 @@
+#!/usr/bin/env bash
+# Test suite for deploy.sh — verifies setup/ playbook deployment and regressions.
+#
+# Usage:
+#   ./tests/test-deploy.sh
+#
+# Exit codes:
+#   0  All tests passed
+#   1  One or more tests failed
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PASSED=0
+FAILED=0
+
+pass() {
+  echo "  PASS: $1"
+  PASSED=$((PASSED + 1))
+}
+
+fail() {
+  echo "  FAIL: $1"
+  FAILED=$((FAILED + 1))
+}
+
+assert_file_exists() {
+  local label="$1"
+  local path="$2"
+  if [ -f "$path" ]; then
+    pass "$label exists"
+  else
+    fail "$label does not exist: $path"
+  fi
+}
+
+assert_file_not_exists() {
+  local label="$1"
+  local path="$2"
+  if [ ! -f "$path" ]; then
+    pass "$label does not exist (expected)"
+  else
+    fail "$label unexpectedly exists: $path"
+  fi
+}
+
+assert_dir_not_exists() {
+  local label="$1"
+  local path="$2"
+  if [ ! -d "$path" ]; then
+    pass "$label directory does not exist (expected)"
+  else
+    fail "$label directory unexpectedly exists: $path"
+  fi
+}
+
+assert_executable() {
+  local label="$1"
+  local path="$2"
+  if [ -x "$path" ]; then
+    pass "$label is executable"
+  else
+    fail "$label is not executable: $path"
+  fi
+}
+
+assert_not_executable() {
+  local label="$1"
+  local path="$2"
+  if [ ! -x "$path" ]; then
+    pass "$label is not executable (expected)"
+  else
+    fail "$label is unexpectedly executable: $path"
+  fi
+}
+
+assert_contains() {
+  local label="$1"
+  local path="$2"
+  local expected="$3"
+  if grep -qF "$expected" "$path" 2>/dev/null; then
+    pass "$label contains '$expected'"
+  else
+    fail "$label does not contain '$expected'"
+  fi
+}
+
+assert_not_contains() {
+  local label="$1"
+  local path="$2"
+  local unexpected="$3"
+  if ! grep -qF "$unexpected" "$path" 2>/dev/null; then
+    pass "$label does not contain '$unexpected'"
+  else
+    fail "$label unexpectedly contains '$unexpected'"
+  fi
+}
+
+assert_files_identical() {
+  local label="$1"
+  local file_a="$2"
+  local file_b="$3"
+  if diff -q "$file_a" "$file_b" >/dev/null 2>&1; then
+    pass "$label files are identical"
+  else
+    fail "$label files differ"
+    diff "$file_a" "$file_b" || true
+  fi
+}
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC1: Fresh deploy — all agents
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC1: Fresh deploy — all agents ==="
+TC1_DIR=$(mktemp -d)
+"$REPO_DIR/deploy.sh" --agents all --overwrite "$TC1_DIR" >/dev/null 2>&1
+
+echo "  --- Playbook files ---"
+assert_file_exists "create-local-otel-stack.md" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack.md"
+assert_file_exists "discover-local-otel-stack.md" "$TC1_DIR/.context/playbooks/setup/discover-local-otel-stack.md"
+assert_file_exists "use-local-otel-stack.md" "$TC1_DIR/.context/playbooks/setup/use-local-otel-stack.md"
+assert_file_exists "instrument-dotnet-otel.md" "$TC1_DIR/.context/playbooks/setup/instrument-dotnet-otel.md"
+
+echo "  --- Companion scripts (executable) ---"
+assert_file_exists "start-local-otel-stack.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh"
+assert_executable "start-local-otel-stack.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh"
+assert_file_exists "test-local-otel-stack.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh"
+assert_executable "test-local-otel-stack.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh"
+assert_file_exists "validate-config.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/validate-config.sh"
+assert_executable "validate-config.sh" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/validate-config.sh"
+
+echo "  --- Non-executable files ---"
+assert_file_exists "Start-LocalOtelStack.ps1" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1"
+assert_file_exists "versions.env" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/versions.env"
+assert_not_executable "versions.env" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack/versions.env"
+
+echo "  --- Claude thin wrappers ---"
+assert_file_exists "claude/setup-create-local-otel-stack" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md"
+assert_file_exists "claude/setup-discover-local-otel-stack" "$TC1_DIR/.claude/skills/setup-discover-local-otel-stack/SKILL.md"
+assert_file_exists "claude/setup-use-local-otel-stack" "$TC1_DIR/.claude/skills/setup-use-local-otel-stack/SKILL.md"
+assert_file_exists "claude/setup-instrument-dotnet-otel" "$TC1_DIR/.claude/skills/setup-instrument-dotnet-otel/SKILL.md"
+
+echo "  --- Copilot thin wrappers ---"
+assert_file_exists "copilot/setup-create-local-otel-stack" "$TC1_DIR/.github/skills/setup-create-local-otel-stack/SKILL.md"
+assert_file_exists "copilot/setup-discover-local-otel-stack" "$TC1_DIR/.github/skills/setup-discover-local-otel-stack/SKILL.md"
+assert_file_exists "copilot/setup-use-local-otel-stack" "$TC1_DIR/.github/skills/setup-use-local-otel-stack/SKILL.md"
+assert_file_exists "copilot/setup-instrument-dotnet-otel" "$TC1_DIR/.github/skills/setup-instrument-dotnet-otel/SKILL.md"
+
+echo "  --- allowed-tools check ---"
+assert_contains "claude wrapper allowed-tools" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" "allowed-tools:"
+assert_not_contains "claude wrapper no git-only bash" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" "Bash(git *)"
+
+echo "  --- Safety and provenance ---"
+assert_contains "local-dev-only warning" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack.md" "Local development and testing only"
+assert_contains "provenance comment" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack.md" "Ported from devopsin"
+
+echo "  --- Index routing ---"
+assert_contains "index has setup playbooks" "$TC1_DIR/.context/index.md" "playbooks/setup/"
+
+echo "  --- Negative: monolithic skill not ported ---"
+assert_file_not_exists "local-otel-stack.md" "$TC1_DIR/.context/playbooks/setup/local-otel-stack.md"
+
+rm -rf "$TC1_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC2: Agent-scoped deploy — Claude only
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC2: Agent-scoped deploy — Claude only ==="
+TC2_DIR=$(mktemp -d)
+"$REPO_DIR/deploy.sh" --agents claude --overwrite "$TC2_DIR" >/dev/null 2>&1
+
+assert_file_exists "claude wrapper present" "$TC2_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md"
+assert_dir_not_exists "copilot dir absent" "$TC2_DIR/.github/skills/setup-create-local-otel-stack"
+
+rm -rf "$TC2_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC3: Agent-scoped deploy — Copilot only
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC3: Agent-scoped deploy — Copilot only ==="
+TC3_DIR=$(mktemp -d)
+"$REPO_DIR/deploy.sh" --agents copilot --overwrite "$TC3_DIR" >/dev/null 2>&1
+
+assert_file_exists "copilot wrapper present" "$TC3_DIR/.github/skills/setup-create-local-otel-stack/SKILL.md"
+assert_dir_not_exists "claude dir absent" "$TC3_DIR/.claude/skills/setup-create-local-otel-stack"
+
+rm -rf "$TC3_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC4: No regressions — existing thin-wrapper generation
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC4: No regressions — existing thin wrappers ==="
+TC4_DIR=$(mktemp -d)
+"$REPO_DIR/deploy.sh" --agents claude --overwrite "$TC4_DIR" >/dev/null 2>&1
+
+assert_file_exists "assess-observability" "$TC4_DIR/.claude/skills/assess-observability/SKILL.md"
+assert_file_exists "review-security" "$TC4_DIR/.claude/skills/review-security/SKILL.md"
+assert_file_exists "plan-adr" "$TC4_DIR/.claude/skills/plan-adr/SKILL.md"
+assert_file_exists "refactor-safe-refactor" "$TC4_DIR/.claude/skills/safe-refactor/SKILL.md"
+
+echo "  --- Regression content check ---"
+assert_files_identical "assess-observability fixture" \
+  "$TC4_DIR/.claude/skills/assess-observability/SKILL.md" \
+  "$SCRIPT_DIR/fixtures/assess-observability-skill.md"
+
+rm -rf "$TC4_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC5: Idempotency
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC5: Idempotency ==="
+TC5_DIR=$(mktemp -d)
+
+"$REPO_DIR/deploy.sh" --agents all --overwrite "$TC5_DIR" >/dev/null 2>&1
+find "$TC5_DIR" -type f | sort | xargs sha256sum > /tmp/tc5_run1.txt
+find "$TC5_DIR" -type f -perm /111 | sort > /tmp/tc5_perms1.txt
+
+"$REPO_DIR/deploy.sh" --agents all --overwrite "$TC5_DIR" >/dev/null 2>&1
+find "$TC5_DIR" -type f | sort | xargs sha256sum > /tmp/tc5_run2.txt
+find "$TC5_DIR" -type f -perm /111 | sort > /tmp/tc5_perms2.txt
+
+if diff -q /tmp/tc5_run1.txt /tmp/tc5_run2.txt >/dev/null 2>&1; then
+  pass "File checksums identical across both runs"
+else
+  fail "File checksums differ between runs"
+  diff /tmp/tc5_run1.txt /tmp/tc5_run2.txt || true
+fi
+
+if diff -q /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt >/dev/null 2>&1; then
+  pass "Executable permissions identical across both runs"
+else
+  fail "Executable permissions differ between runs"
+  diff /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt || true
+fi
+
+rm -rf "$TC5_DIR" /tmp/tc5_run1.txt /tmp/tc5_run2.txt /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt
+
+# ═══════════════════════════════════════════════════════════════════════
+# TC6: validate-config passes — deployed copy
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== TC6: validate-config passes ==="
+TC6_DIR=$(mktemp -d)
+"$REPO_DIR/deploy.sh" --agents all --overwrite "$TC6_DIR" >/dev/null 2>&1
+
+if "$TC6_DIR/.context/playbooks/setup/create-local-otel-stack/validate-config.sh" >/dev/null 2>&1; then
+  pass "Deployed validate-config.sh exits 0"
+else
+  fail "Deployed validate-config.sh exited non-zero"
+fi
+
+if "$REPO_DIR/playbooks/setup/create-local-otel-stack/validate-config.sh" >/dev/null 2>&1; then
+  pass "Source validate-config.sh exits 0"
+else
+  fail "Source validate-config.sh exited non-zero"
+fi
+
+rm -rf "$TC6_DIR"
+
+# ═══════════════════════════════════════════════════════════════════════
+# Summary
+# ═══════════════════════════════════════════════════════════════════════
+echo ""
+echo "=== Results ==="
+echo "  Passed: $PASSED"
+echo "  Failed: $FAILED"
+
+if [ "$FAILED" -gt 0 ]; then
+  echo ""
+  echo "TEST SUITE FAILED"
+  exit 1
+else
+  echo ""
+  echo "TEST SUITE PASSED"
+  exit 0
+fi

From a0d91bef59021e0f5f7f1618c962c98fdd829e44 Mon Sep 17 00:00:00 2001
From: Devin Container Agent <devin-agent@container.local>
Date: Tue, 19 May 2026 08:37:37 +0000
Subject: [PATCH 2/4] feat: add OTel setup playbooks from devopsin

Port four OpenTelemetry operational skills from devopsin@9fa20ff0
(feature/split-telemetry-skills) into playbooks/setup/:

- create-local-otel-stack.md + companion scripts/configs
- discover-local-otel-stack.md
- use-local-otel-stack.md
- instrument-dotnet-otel.md

Key changes:
- New playbooks/setup/ category with keywords frontmatter
- deploy.sh: setup/ loop with unrestricted Bash allowed-tools
- deploy.ps1: setup entry in $playbookCategories
- core/.context/index.md: setup playbook routing entries
- README.md: setup/ in repository structure
- docker-compose.yaml: all ports bound to 127.0.0.1
- validate-config.sh: per-port localhost binding assertions
- Related Skills links updated to sibling-file format
- Provenance comments and local-dev-only warnings added

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 README.md                                     |  11 +
 core/.context/index.md                        |  11 +
 deploy.ps1                                    |   1 +
 deploy.sh                                     |   6 +
 playbooks/setup/create-local-otel-stack.md    | 322 ++++++++++++++++++
 .../Start-LocalOtelStack.ps1                  | 179 ++++++++++
 .../docker-compose.yaml                       |  82 +++++
 .../otel-collector-config-compose.yaml        |  62 ++++
 .../otel-collector-config.yaml                |  61 ++++
 .../otel-collector-sidecar-config.yaml        |  49 +++
 .../start-local-otel-stack.sh                 | 169 +++++++++
 .../test-local-otel-stack.sh                  | 225 ++++++++++++
 .../validate-config.sh                        | 191 +++++++++++
 .../create-local-otel-stack/versions.env      |   9 +
 playbooks/setup/discover-local-otel-stack.md  |  95 ++++++
 playbooks/setup/instrument-dotnet-otel.md     | 226 ++++++++++++
 playbooks/setup/use-local-otel-stack.md       | 151 ++++++++
 tests/test-deploy.sh                          |  13 +
 18 files changed, 1863 insertions(+)
 create mode 100644 playbooks/setup/create-local-otel-stack.md
 create mode 100644 playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
 create mode 100644 playbooks/setup/create-local-otel-stack/docker-compose.yaml
 create mode 100644 playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
 create mode 100644 playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
 create mode 100644 playbooks/setup/create-local-otel-stack/otel-collector-sidecar-config.yaml
 create mode 100755 playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
 create mode 100755 playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh
 create mode 100755 playbooks/setup/create-local-otel-stack/validate-config.sh
 create mode 100644 playbooks/setup/create-local-otel-stack/versions.env
 create mode 100644 playbooks/setup/discover-local-otel-stack.md
 create mode 100644 playbooks/setup/instrument-dotnet-otel.md
 create mode 100644 playbooks/setup/use-local-otel-stack.md

diff --git a/README.md b/README.md
index 55fba6d..17f1562 100644
--- a/README.md
+++ b/README.md
@@ -130,8 +130,19 @@ playbooks/                              Tier 2 — on demand (→ target .contex
     safe-refactor.md, extract-module.md, dependency-upgrade.md
   docs/                                 Developer-facing documentation generation (1)
     gitbook.md
+  setup/                                Setup and tooling playbooks (4)
+    create-local-otel-stack.md
+    create-local-otel-stack/            (companion scripts and configs — deployed alongside the playbook)
+    discover-local-otel-stack.md
+    use-local-otel-stack.md
+    instrument-dotnet-otel.md
 ```
 
+> Scripts in `playbooks/setup/create-local-otel-stack/` are deployed to
+> `.context/playbooks/setup/create-local-otel-stack/` alongside the playbook.
+> Playbook content references scripts at this path so agents can run them from
+> the repository root.
+
 ## Playbook Format
 
 Playbooks use a universal markdown format with YAML frontmatter:
diff --git a/core/.context/index.md b/core/.context/index.md
index 0d788bc..89aea49 100644
--- a/core/.context/index.md
+++ b/core/.context/index.md
@@ -108,6 +108,17 @@ Combine multiple matches when a task spans domains.
 
 ---
 
+## Playbooks — Setup (operational setup procedures)
+
+| Keywords | File | Summary |
+|----------|------|---------|
+| create otel stack, local otel, set up opentelemetry, local telemetry, opentelemetry local | `.context/playbooks/setup/create-local-otel-stack.md` | Deploy a local OTel collector stack for development and testing |
+| discover otel stack, find otel stack, otel stack running | `.context/playbooks/setup/discover-local-otel-stack.md` | Discover and validate a running local OTel stack |
+| use otel stack, connect otel, send telemetry, otlp endpoint | `.context/playbooks/setup/use-local-otel-stack.md` | Configure services to emit to a local OTel stack |
+| instrument dotnet, dotnet otel, opentelemetry dotnet, dotnet sdk otel | `.context/playbooks/setup/instrument-dotnet-otel.md` | Instrument a .NET service with OpenTelemetry SDK |
+
+---
+
 ## Conventions (style and workflow guidance)
 
 | Keywords | File | Summary |
diff --git a/deploy.ps1 b/deploy.ps1
index c2e94d4..609614b 100644
--- a/deploy.ps1
+++ b/deploy.ps1
@@ -594,6 +594,7 @@ if ((Test-AgentEnabled 'claude') -or (Test-AgentEnabled 'copilot')) {
         @{ Dir = 'plan';     Tools = $null }
         @{ Dir = 'refactor'; Tools = $null }
         @{ Dir = 'docs';     Tools = $null }
+        @{ Dir = 'setup';    Tools = 'Read, Grep, Glob, Bash, Write, Edit, Agent' }
     )
 
     foreach ($category in $playbookCategories) {
diff --git a/deploy.sh b/deploy.sh
index edd982d..c8605af 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -610,6 +610,12 @@ if agent_enabled claude || agent_enabled copilot; then
     filename=$(basename "$playbook")
     generate_skills_for_selected_agents "$playbook" "docs/$filename"
   done
+
+  for playbook in "$SCRIPT_DIR"/playbooks/setup/*.md; do
+    filename=$(basename "$playbook")
+    generate_skills_for_selected_agents "$playbook" "setup/$filename" \
+      "Read, Grep, Glob, Bash, Write, Edit, Agent"
+  done
 else
   echo "  Skipping skill wrapper generation (no selected agent uses skills)."
 fi
diff --git a/playbooks/setup/create-local-otel-stack.md b/playbooks/setup/create-local-otel-stack.md
new file mode 100644
index 0000000..606ce7b
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack.md
@@ -0,0 +1,322 @@
+<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
+---
+name: setup-create-local-otel-stack
+description: >
+  Use to create and start a local OpenTelemetry observability stack
+  (OTel Collector, VictoriaMetrics, VictoriaLogs, VictoriaTraces).
+  Only use this after running discover-local-otel-stack and confirming that no stack is currently running.
+  To send telemetry to a running stack, use use-local-otel-stack instead.
+keywords: [create otel stack, local otel, set up opentelemetry, local telemetry, opentelemetry local]
+---
+
+# Create Local OTel Stack
+
+> **Local development and testing only.** Do not use these configs in shared, staging, or production environments.
+
+Create and start a local OpenTelemetry observability stack for development and testing. This skill provides container runtime-agnostic instructions for deploying metrics, logs, and traces backends.
+
+> **Prerequisites:** Run `discover-local-otel-stack` first to confirm no stack is already running.
+> Once the stack is up, use `use-local-otel-stack` to send telemetry to it.
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                       Local OTel Stack                             │
+│                                                                    │
+│  ┌─────────────────┐    ┌──────────────────────────────────────┐  │
+│  │  OTel Collector │    │  Victoria* Backends                  │  │
+│  │  :4317 (gRPC)   │───►│  VictoriaMetrics  :8428 (PromQL)    │  │
+│  │  :4318 (HTTP)   │    │  VictoriaLogs     :9428 (LogsQL)    │  │
+│  └─────────────────┘    │  VictoriaTraces   :10428 (Jaeger)   │  │
+│                          └──────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+| Component | Image | Port | Purpose |
+|-----------|-------|------|---------|
+| OTel Collector | `ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.133.0` | 4317 (gRPC), 4318 (HTTP) | Receives OTLP, routes to backends |
+| VictoriaMetrics | `victoriametrics/victoria-metrics:v1.130.0` | 8428 | Metrics, queryable via PromQL |
+| VictoriaLogs | `victoriametrics/victoria-logs:v1.47.0` | 9428 | Logs, queryable via LogsQL |
+| VictoriaTraces | `victoriametrics/victoria-traces:v0.7.1` | 10428 | Traces, queryable via Jaeger API |
+
+## Deployment Scenarios
+
+### Scenario 1: Stack on host, agents in containers
+
+In this scenario:
+- The stack runs directly on the host (Podman pod or Docker network)
+- AI agents run in containers on the same host
+- Each agent container runs a lightweight OTel Collector **sidecar** that forwards telemetry to the host via `host.containers.internal:4318`
+
+Agent instrumentation:
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+(pointing at the in-container sidecar, which forwards to `host.containers.internal:4318`)
+
+Sidecar config (`otel-collector-sidecar-config.yaml`):
+- Receives on `0.0.0.0:4317` and `0.0.0.0:4318`
+- Exports via `otlphttp` to `http://host.containers.internal:4318`
+
+### Scenario 2: Stack and agents on the same host
+
+No sidecar required. Agents connect directly:
+```bash
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```
+
+## Container Runtime Examples
+
+### Podman (pod-based, no compose)
+
+```bash
+# Start the stack
+.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
+
+# Stop the stack
+.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh --stop
+
+# Force recreate if already running
+.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh --force
+```
+
+Uses shared network namespace: containers communicate via `localhost`.
+
+### Docker (user-defined bridge network)
+
+```bash
+# Create network
+docker network create otel-stack
+
+# Start VictoriaMetrics
+docker run -d --network otel-stack --name victoriametrics \
+  -p 8428:8428 \
+  victoriametrics/victoria-metrics:v1.130.0 \
+  --storageDataPath=/storage
+
+# Start VictoriaLogs
+docker run -d --network otel-stack --name victorialogs \
+  -p 9428:9428 \
+  victoriametrics/victoria-logs:v1.47.0 \
+  --storageDataPath=/vlogs
+
+# Start VictoriaTraces
+docker run -d --network otel-stack --name victoriatraces \
+  -p 10428:10428 \
+  victoriametrics/victoria-traces:v0.7.1 \
+  --storageDataPath=/vtraces --servicegraph.enableTask=true
+
+# Start OTel Collector (using compose config)
+docker run -d --network otel-stack --name otel-collector \
+  -p 4317:4317 -p 4318:4318 \
+  -v ./otel-collector-config-compose.yaml:/etc/otel-collector-config.yml:ro \
+  ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.133.0 \
+  --config=/etc/otel-collector-config.yml
+```
+
+Uses service names for inter-container communication (e.g., `victoriametrics:8428`).
+
+### Docker Compose / Podman Compose
+
+Image versions are read from `versions.env` via variable substitution. Pass `--env-file` so Docker Compose can resolve the `${IMAGE_*}` variables:
+
+```bash
+# Start all services (versions read from versions.env)
+docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env up -d
+
+# Stop all services
+docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env down
+
+# View logs
+docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env logs -f
+
+# Restart specific service
+docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env restart otel-collector
+```
+
+Automatically creates network; uses service names for communication.
+
+### Rancher Desktop (nerdctl)
+
+Same syntax as Docker, but use `nerdctl` instead of `docker`:
+```bash
+nerdctl network create otel-stack
+nerdctl run -d --network otel-stack --name victoriametrics ...
+```
+
+## Configuration Files
+
+### versions.env
+
+Single source of truth for container image versions. Update versions here to propagate to all scripts automatically.
+
+### otel-collector-config.yaml
+
+Host-side collector configuration:
+- Receives OTLP on `:4317` (gRPC) and `:4318` (HTTP)
+- Includes `hostmetrics` scraper (CPU, memory, disk, network)
+- Routes metrics → VictoriaMetrics, logs → VictoriaLogs, traces → VictoriaTraces
+- Uses `localhost` throughout since all containers share the pod/network namespace
+
+### otel-collector-sidecar-config.yaml
+
+In-container forwarder configuration:
+- Receives OTLP on `:4317` and `:4318` (in-container)
+- Exports via `otlphttp` to `http://host.containers.internal:4318`
+- Includes health check extension on `:13133`
+- No `hostmetrics` (that's the host-side collector's responsibility)
+
+### otel-collector-config-compose.yaml
+
+Docker Compose-specific collector configuration:
+- Same as host-side config but uses service names (`victoriametrics`, `victorialogs`, `victoriatraces`) instead of `localhost`
+- Required because Docker Compose creates a bridge network where services communicate via service names
+
+## Testing
+
+### Lightweight validation (no container runtime required)
+
+`validate-config.sh` checks that all required files are present, scripts are executable, YAML is valid, and `docker-compose.yaml` references the correct `${IMAGE_*}` placeholders. It does not require Podman or Docker and is suitable for CI:
+
+```bash
+.context/playbooks/setup/create-local-otel-stack/validate-config.sh
+```
+
+### Full smoke test (requires Podman)
+
+Run the smoke test to verify the stack works end-to-end:
+
+```bash
+# Run from the skill directory on Linux (requires podman):
+.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh
+```
+
+The script will:
+1. Force-clean any leftover containers from a previous run (idempotent pre-flight)
+2. Start the stack
+3. Wait for all services (including the OTel Collector health endpoint) to be ready before sending telemetry
+4. Send sample telemetry via `telemetrygen`
+5. Poll each backend for ingested data (up to 30s each, 2s intervals)
+6. Assert non-empty results
+7. Check that vmui endpoints are reachable
+8. Tear down and exit 0 (success) or 1 (failure)
+
+**CI usage:** Wrap with `timeout 120 .context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh` to ensure SIGTERM (not SIGKILL) fires on timeout, which allows the trap-based cleanup to run. If the runner may be killed with SIGKILL, add a post-job step: `.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh --force-cleanup`.
+
+## Platform-Specific Notes
+
+### Windows (PowerShell)
+
+Use the PowerShell script for Windows environments:
+```powershell
+# Start the stack
+.\.context\playbooks\setup\create-local-otel-stack\Start-LocalOtelStack.ps1
+
+# Stop the stack
+.\.context\playbooks\setup\create-local-otel-stack\Start-LocalOtelStack.ps1 -Stop
+
+# Force recreate
+.\.context\playbooks\setup\create-local-otel-stack\Start-LocalOtelStack.ps1 -Force
+```
+
+### macOS
+
+Same commands as Linux, but you may need to use `docker` instead of `podman` if Podman is not installed.
+
+### Networking Differences
+
+**Podman pods**: Share a network namespace, so containers refer to each other via `localhost`.
+
+**Docker networks**: Use a named network, so containers use service names (e.g., `victoriametrics:8428`).
+
+The OTel Collector configurations differ accordingly between the two approaches.
+
+## Troubleshooting
+
+### Orphaned containers / port conflicts after a failed run
+
+If the start script or smoke test exited uncleanly (e.g. killed with SIGKILL in CI), containers may remain running and ports 4317, 4318, 8428, 9428, 10428 may still be bound. Use `--force-cleanup` to unconditionally remove all named containers and the pod:
+
+```bash
+# Podman
+.context/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh --force-cleanup
+
+# PowerShell
+.\.context\playbooks\setup\create-local-otel-stack\Start-LocalOtelStack.ps1 -ForceCleanup
+```
+
+If the scripts themselves are broken, clean up manually:
+
+```bash
+# Podman
+podman pod rm -f local-otel-stack
+podman rm -f otel-collector victoriametrics victorialogs victoriatraces
+
+# Docker
+docker rm -f otel-collector victoriametrics victorialogs victoriatraces
+docker network rm otel-stack
+```
+
+### Port conflicts (other services)
+
+If ports are already in use by a different service, the start script will fail. You can either:
+- Stop the conflicting services
+- Modify the port mappings in the scripts
+- Use `--force` to recreate the stack (if the previous stack is still running)
+
+### Containers not starting
+
+Check container logs:
+```bash
+# Podman
+podman logs victoriametrics
+podman logs otel-collector
+
+# Docker
+docker logs victoriametrics
+docker logs otel-collector
+```
+
+### Health check failures
+
+If backends don't become healthy within 30 seconds:
+- Check system resources (memory, disk space)
+- Verify no firewall blocks are preventing communication
+- Review container logs for error messages
+
+### Telemetry not appearing
+
+1. Verify your application is configured with the correct OTLP endpoint
+2. Check the OTel Collector logs for ingestion errors
+3. Query the backends directly to verify they're receiving data
+4. Run the smoke test to validate the full pipeline
+
+## Version Updates
+
+`versions.env` is the single source of truth for image versions. The Bash and PowerShell start scripts source it directly. `docker-compose.yaml` references the same variables via `${IMAGE_*}` substitution (pass `--env-file versions.env` when running `docker-compose`).
+
+To update component versions:
+
+1. Edit `versions.env` with new image tags
+2. Run `.context/playbooks/setup/create-local-otel-stack/validate-config.sh` to confirm `docker-compose.yaml` still references the variables correctly
+3. Test with `.context/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh`
+4. Update the architecture table in the `## Architecture` section of this file if version numbers are shown there
+
+**Note:** The architecture table in this document contains version strings for reference. Update them alongside `versions.env` when upgrading. The SKILL.md Docker examples in `## Container Runtime Examples` also contain full image references — update those too.
+
+Always test after version updates as APIs may change between major versions.
+
+## Related Skills
+
+- [discover-local-otel-stack](discover-local-otel-stack.md) — Check whether a local OTel stack is running.
+- [use-local-otel-stack](use-local-otel-stack.md) — Configure OTLP endpoint and query the local stack.
+- [instrument-dotnet-otel](instrument-dotnet-otel.md) — Instrument a .NET app with the OTel SDK.
+
+## External References
+
+- Observability standard — see `.context/standards/observability.md` for production OTel setup
+- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
+- [VictoriaMetrics Documentation](https://docs.victoriametrics.com/)
+- [VictoriaLogs Documentation](https://docs.victoriametrics.com/VictoriaLogs/)
+- [VictoriaTraces Documentation](https://docs.victoriametrics.com/VictoriaTraces/)
diff --git a/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1 b/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
new file mode 100644
index 0000000..8698767
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
@@ -0,0 +1,179 @@
+#!/usr/bin/env pwsh
+# Start or stop the local OpenTelemetry observability stack.
+#
+# Usage:
+#   ./Start-LocalOtelStack.ps1                 # start the stack
+#   ./Start-LocalOtelStack.ps1 -Stop           # tear down the stack
+#   ./Start-LocalOtelStack.ps1 -Force          # recreate if already running
+#   ./Start-LocalOtelStack.ps1 -ForceCleanup   # remove containers/pod by name unconditionally
+#
+# Manual cleanup (if scripts fail completely):
+#   podman pod rm -f local-otel-stack
+#   docker rm -f otel-collector victoriametrics victorialogs victoriatraces
+
+param(
+    [switch]$Stop,
+    [switch]$Force,
+    [switch]$ForceCleanup
+)
+
+$ErrorActionPreference = "Stop"
+
+$ScriptDir = Split-Path -Parent $PSCommandPath
+$VersionsFile = Join-Path $ScriptDir "versions.env"
+
+# Image versions — single source of truth
+$Versions = @{}
+Get-Content $VersionsFile | ForEach-Object {
+    if ($_ -match '^IMAGE_(\w+)=(.+)$') {
+        $Versions[$Matches[1]] = $Matches[2]
+    }
+}
+
+$PodName = "local-otel-stack"
+
+function Invoke-ForceCleanup {
+    Write-Host "Force-cleaning up local OTel stack (removing by name, ignoring errors)..."
+    podman pod rm -f $PodName 2>$null; $LASTEXITCODE = 0
+    foreach ($cname in @('otel-collector', 'victoriametrics', 'victorialogs', 'victoriatraces')) {
+        podman rm -f $cname 2>$null; $LASTEXITCODE = 0
+    }
+    Write-Host "Force-cleanup complete."
+}
+
+function Stop-Stack {
+    Write-Host "Stopping local OTel stack..."
+    $pod = podman pod exists $PodName 2>$null
+    if ($LASTEXITCODE -eq 0) {
+        podman pod rm -f $PodName *>$null
+        Write-Host "Pod '$PodName' removed."
+    } else {
+        Write-Host "Pod '$PodName' does not exist."
+    }
+}
+
+function Wait-ForHealth {
+    param(
+        [string]$Url,
+        [string]$Name,
+        [int]$Timeout = 30
+    )
+    
+    $deadline = (Get-Date).AddSeconds($Timeout)
+    while ((Get-Date) -lt $deadline) {
+        try {
+            $response = Invoke-WebRequest -Uri $Url -TimeoutSec 2 -UseBasicParsing *>$null
+            if ($response.StatusCode -eq 200) {
+                Write-Host "  $Name is healthy"
+                return $true
+            }
+        } catch {
+            # Continue trying
+        }
+        Start-Sleep 1
+    }
+    Write-Host "  WARNING: $Name did not become healthy within ${Timeout}s"
+    return $false
+}
+
+function Start-Stack {
+    $pod = podman pod exists $PodName 2>$null
+    if ($LASTEXITCODE -eq 0) {
+        if ($Force) {
+            Write-Host "Pod '$PodName' already exists. Recreating (-Force)..."
+            Stop-Stack
+        } else {
+            Write-Error "ERROR: Pod '$PodName' already exists. Use -Force to recreate, or -Stop to tear down."
+        }
+    }
+
+    $ConfigPath = Join-Path $ScriptDir "otel-collector-config.yaml"
+    if (-not (Test-Path $ConfigPath)) {
+        Write-Error "ERROR: OTel Collector config not found at: $ConfigPath"
+    }
+
+    Write-Host "Creating pod '$PodName'..."
+    podman pod create --name $PodName `
+        -p 4317:4317 `
+        -p 4318:4318 `
+        -p 8428:8428 `
+        -p 9428:9428 `
+        -p 10428:10428
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to create pod"
+    }
+
+    Write-Host "Starting VictoriaMetrics..."
+    podman run -d --pod $PodName --name victoriametrics `
+        $Versions["VM"] `
+        --storageDataPath=/storage
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to start VictoriaMetrics"
+    }
+
+    Write-Host "Starting VictoriaLogs..."
+    podman run -d --pod $PodName --name victorialogs `
+        $Versions["VL"] `
+        --storageDataPath=/vlogs
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to start VictoriaLogs"
+    }
+
+    Write-Host "Starting VictoriaTraces..."
+    podman run -d --pod $PodName --name victoriatraces `
+        $Versions["VT"] `
+        --storageDataPath=/vtraces `
+        --servicegraph.enableTask=true
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to start VictoriaTraces"
+    }
+
+    Write-Host "Starting OTel Collector..."
+    podman run -d --pod $PodName --name otel-collector `
+        -v "${ConfigPath}:/etc/otel-collector-config.yml:ro" `
+        $Versions["OTEL"] `
+        --config=/etc/otel-collector-config.yml
+
+    if ($LASTEXITCODE -ne 0) {
+        Write-Error "Failed to start OTel Collector"
+    }
+
+    Write-Host ""
+    Write-Host "Waiting for backends to become healthy..."
+    $vmOk = Wait-ForHealth "http://localhost:8428/health" "VictoriaMetrics"
+    $vlOk = Wait-ForHealth "http://localhost:9428/health" "VictoriaLogs"
+    # VictoriaTraces has no /health endpoint; use Jaeger services API as readiness probe
+    $vtOk = Wait-ForHealth "http://localhost:10428/select/jaeger/api/services" "VictoriaTraces"
+
+    if (-not ($vmOk -and $vlOk -and $vtOk)) {
+        Write-Host "WARNING: Some backends did not become healthy. Check 'podman pod ps' and container logs."
+    }
+
+    Write-Host ""
+    Write-Host "--- Local OTel Stack Ready ---"
+    Write-Host "Metrics UI (vmui):  http://localhost:8428/vmui"
+    Write-Host "Logs UI (vmui):     http://localhost:9428/select/vmui/"
+    Write-Host "Traces UI (vmui):   http://localhost:10428/select/vmui"
+    Write-Host "OTLP HTTP:          http://localhost:4318"
+    Write-Host "OTLP gRPC:          localhost:4317"
+    Write-Host "Metrics (PromQL):   http://localhost:8428/api/v1/query"
+    Write-Host "Logs (LogsQL):      http://localhost:9428/select/logsql/query"
+    Write-Host "Traces (Jaeger):    http://localhost:10428/select/jaeger/api/traces"
+    Write-Host ""
+    Write-Host "Example queries:"
+    Write-Host "  curl 'http://localhost:8428/api/v1/query?query=up'"
+    Write-Host "  curl 'http://localhost:9428/select/logsql/query?query=*'"
+    Write-Host "  curl 'http://localhost:10428/select/jaeger/api/services'"
+}
+
+if ($ForceCleanup) {
+    Invoke-ForceCleanup
+} elseif ($Stop) {
+    Stop-Stack
+} else {
+    Start-Stack
+}
diff --git a/playbooks/setup/create-local-otel-stack/docker-compose.yaml b/playbooks/setup/create-local-otel-stack/docker-compose.yaml
new file mode 100644
index 0000000..25bd7dd
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/docker-compose.yaml
@@ -0,0 +1,82 @@
+version: '3.8'
+# Image versions are read from versions.env (the single source of truth).
+# Run with:  docker-compose --env-file versions.env up -d
+# Or set the IMAGE_* variables in your environment before running.
+# The ${IMAGE_VM} syntax is native Docker Compose variable substitution.
+
+services:
+  victoriametrics:
+    image: ${IMAGE_VM}
+    container_name: victoriametrics
+    ports:
+      - "127.0.0.1:8428:8428"
+    command:
+      - --storageDataPath=/storage
+    volumes:
+      - vm_data:/storage
+    networks:
+      - otel-stack
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8428/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  victorialogs:
+    image: ${IMAGE_VL}
+    container_name: victorialogs
+    ports:
+      - "127.0.0.1:9428:9428"
+    command:
+      - --storageDataPath=/vlogs
+    volumes:
+      - vl_data:/vlogs
+    networks:
+      - otel-stack
+    healthcheck:
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:9428/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  victoriatraces:
+    image: ${IMAGE_VT}
+    container_name: victoriatraces
+    ports:
+      - "127.0.0.1:10428:10428"
+    command:
+      - --storageDataPath=/vtraces
+      - --servicegraph.enableTask=true
+    volumes:
+      - vt_data:/vtraces
+    networks:
+      - otel-stack
+
+  otel-collector:
+    image: ${IMAGE_OTEL}
+    container_name: otel-collector
+    ports:
+      - "127.0.0.1:4317:4317"  # OTLP gRPC receiver
+      - "127.0.0.1:4318:4318"  # OTLP HTTP receiver
+    volumes:
+      - ./otel-collector-config-compose.yaml:/etc/otel-collector-config.yml:ro
+    command:
+      - --config=/etc/otel-collector-config.yml
+    networks:
+      - otel-stack
+    depends_on:
+      victoriametrics:
+        condition: service_healthy
+      victorialogs:
+        condition: service_healthy
+      victoriatraces:
+        condition: service_started
+
+volumes:
+  vm_data:
+  vl_data:
+  vt_data:
+
+networks:
+  otel-stack:
+    driver: bridge
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
new file mode 100644
index 0000000..40253f0
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
@@ -0,0 +1,62 @@
+# Docker Compose OTel Collector — backend router
+# Runs in Docker Compose, using service names for inter-container communication.
+# Receives OTLP telemetry on :4318 (HTTP) / :4317 (gRPC) and routes it
+# to the Victoria* backends (VictoriaMetrics, VictoriaLogs, VictoriaTraces).
+#
+# This config uses service names (e.g., victoriametrics:8428) instead of localhost
+# because Docker Compose creates a bridge network where services communicate via
+# service names, not shared namespaces.
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: "0.0.0.0:4318"
+        cors:
+          allowed_origins: ["http://*", "https://*"]
+      grpc:
+        endpoint: "0.0.0.0:4317"
+  hostmetrics:
+    collection_interval: 15s
+    scrapers:
+      cpu:
+      memory:
+      disk:
+      network:
+
+exporters:
+  otlphttp/victoriametrics:
+    metrics_endpoint: "http://victoriametrics:8428/opentelemetry/v1/metrics"
+    tls:
+      insecure: true
+  otlphttp/victorialogs:
+    logs_endpoint: "http://victorialogs:9428/insert/opentelemetry/v1/logs"
+    tls:
+      insecure: true
+  otlphttp/victoriatraces:
+    traces_endpoint: "http://victoriatraces:10428/insert/opentelemetry/v1/traces"
+    tls:
+      insecure: true
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+    spike_limit_mib: 64
+  batch:
+    timeout: 5s
+    send_batch_size: 1024
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victoriatraces]
+    metrics:
+      receivers: [otlp, hostmetrics]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victoriametrics]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victorialogs]
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
new file mode 100644
index 0000000..f2fcf26
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
@@ -0,0 +1,61 @@
+# Host Local OTel Stack Collector — backend router
+# Runs on the developer's host as part of the local observability stack.
+# Receives OTLP telemetry on :4318 (HTTP) / :4317 (gRPC) and routes it
+# to the Victoria* backends (VictoriaMetrics, VictoriaLogs, VictoriaTraces).
+#
+# See also: otel-collector-sidecar-config.yaml (the in-container forwarder
+# that sends telemetry from agent containers to this collector).
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: "0.0.0.0:4318"
+        cors:
+          allowed_origins: ["http://*", "https://*"]
+      grpc:
+        endpoint: "0.0.0.0:4317"
+  hostmetrics:
+    collection_interval: 15s
+    scrapers:
+      cpu:
+      memory:
+      disk:
+      network:
+
+exporters:
+  otlphttp/victoriametrics:
+    metrics_endpoint: "http://localhost:8428/opentelemetry/v1/metrics"
+    tls:
+      insecure: true
+  otlphttp/victorialogs:
+    logs_endpoint: "http://localhost:9428/insert/opentelemetry/v1/logs"
+    tls:
+      insecure: true
+  otlphttp/victoriatraces:
+    traces_endpoint: "http://localhost:10428/insert/opentelemetry/v1/traces"
+    tls:
+      insecure: true
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+    spike_limit_mib: 64
+  batch:
+    timeout: 5s
+    send_batch_size: 1024
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victoriatraces]
+    metrics:
+      receivers: [otlp, hostmetrics]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victoriametrics]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp/victorialogs]
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-sidecar-config.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-sidecar-config.yaml
new file mode 100644
index 0000000..d26d089
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-sidecar-config.yaml
@@ -0,0 +1,49 @@
+# Container OTel Collector — lightweight forwarder
+# Runs inside agent containers as a sidecar, forwarding OTLP telemetry
+# from in-container processes to the host local-otel-stack collector via
+# host.containers.internal:4318.
+#
+# See also: otel-collector-config.yaml (the host-side collector
+# that receives forwarded telemetry and routes it to Victoria* backends).
+receivers:
+  otlp:
+    protocols:
+      http:
+        endpoint: "0.0.0.0:4318"
+      grpc:
+        endpoint: "0.0.0.0:4317"
+
+exporters:
+  otlphttp:
+    endpoint: "http://host.containers.internal:4318"
+    tls:
+      insecure: true
+
+processors:
+  memory_limiter:
+    check_interval: 1s
+    limit_mib: 256
+    spike_limit_mib: 64
+  batch:
+    timeout: 5s
+    send_batch_size: 1024
+
+extensions:
+  health_check:
+    endpoint: "0.0.0.0:13133"
+
+service:
+  extensions: [health_check]
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp]
+    metrics:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp]
+    logs:
+      receivers: [otlp]
+      processors: [memory_limiter, batch]
+      exporters: [otlphttp]
diff --git a/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh b/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
new file mode 100755
index 0000000..581ac53
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# Start or stop the local OpenTelemetry observability stack.
+#
+# Usage:
+#   ./start-local-otel-stack.sh                 # start the stack
+#   ./start-local-otel-stack.sh --stop          # tear down the stack
+#   ./start-local-otel-stack.sh --force         # recreate if already running
+#   ./start-local-otel-stack.sh --force-cleanup # remove containers/pod by name unconditionally
+#
+# Manual cleanup (if scripts fail completely):
+#   podman pod rm -f local-otel-stack
+#   docker rm -f otel-collector victoriametrics victorialogs victoriatraces
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Image versions — single source of truth
+# shellcheck source=versions.env
+source "$SCRIPT_DIR/versions.env"
+
+POD_NAME="local-otel-stack"
+
+STOP=false
+FORCE=false
+FORCE_CLEANUP=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --stop)          STOP=true ;;
+        --force)         FORCE=true ;;
+        --force-cleanup) FORCE_CLEANUP=true ;;
+        *)               echo "Unknown argument: $arg"; exit 1 ;;
+    esac
+done
+
+# force_cleanup removes the pod and all named containers unconditionally,
+# regardless of whether they are running or even exist. Safe to call multiple
+# times (idempotent). Use this when --stop may have failed or was never reached.
+force_cleanup() {
+    echo "Force-cleaning up local OTel stack (removing by name, ignoring errors)..."
+    podman pod rm -f "$POD_NAME" 2>/dev/null || true
+    # Also remove any stray named containers that may have outlived the pod
+    for cname in otel-collector victoriametrics victorialogs victoriatraces; do
+        podman rm -f "$cname" 2>/dev/null || true
+    done
+    echo "Force-cleanup complete."
+}
+
+stop_stack() {
+    echo "Stopping local OTel stack..."
+    if podman pod exists "$POD_NAME" 2>/dev/null; then
+        podman pod rm -f "$POD_NAME" >/dev/null 2>&1
+        echo "Pod '$POD_NAME' removed."
+    else
+        echo "Pod '$POD_NAME' does not exist."
+    fi
+}
+
+wait_for_health() {
+    local url="$1"
+    local name="$2"
+    local timeout="${3:-30}"
+    local deadline=$((SECONDS + timeout))
+
+    while [ $SECONDS -lt $deadline ]; do
+        if curl -sf --max-time 2 "$url" >/dev/null 2>&1; then
+            echo "  $name is healthy"
+            return 0
+        fi
+        sleep 1
+    done
+    echo "  WARNING: $name did not become healthy within ${timeout}s"
+    return 1
+}
+
+start_stack() {
+    if podman pod exists "$POD_NAME" 2>/dev/null; then
+        if [ "$FORCE" = true ]; then
+            echo "Pod '$POD_NAME' already exists. Recreating (--force)..."
+            stop_stack
+        else
+            echo "ERROR: Pod '$POD_NAME' already exists. Use --force to recreate, or --stop to tear down." >&2
+            exit 1
+        fi
+    fi
+
+    CONFIG_PATH="$SCRIPT_DIR/otel-collector-config.yaml"
+
+    if [ ! -f "$CONFIG_PATH" ]; then
+        echo "ERROR: OTel Collector config not found at: $CONFIG_PATH" >&2
+        exit 1
+    fi
+
+    # On Git Bash (MINGW), MSYS_NO_PATHCONV prevents automatic POSIX-to-Windows
+    # path translation on volume mounts, which would mangle the container-side path.
+    export MSYS_NO_PATHCONV=1
+
+    echo "Creating pod '$POD_NAME'..."
+    podman pod create --name "$POD_NAME" \
+        -p 4317:4317 \
+        -p 4318:4318 \
+        -p 8428:8428 \
+        -p 9428:9428 \
+        -p 10428:10428
+
+    echo "Starting VictoriaMetrics..."
+    # --opentelemetry.usePrometheusNaming was removed: VictoriaMetrics 1.100+
+    # defaults to Prometheus-compatible naming for OTel metrics, making the
+    # explicit flag unnecessary.
+    podman run -d --pod "$POD_NAME" --name victoriametrics \
+        "$IMAGE_VM" \
+        --storageDataPath=/storage
+
+    echo "Starting VictoriaLogs..."
+    podman run -d --pod "$POD_NAME" --name victorialogs \
+        "$IMAGE_VL" \
+        --storageDataPath=/vlogs
+
+    echo "Starting VictoriaTraces..."
+    podman run -d --pod "$POD_NAME" --name victoriatraces \
+        "$IMAGE_VT" \
+        --storageDataPath=/vtraces \
+        --servicegraph.enableTask=true
+
+    echo "Starting OTel Collector..."
+    podman run -d --pod "$POD_NAME" --name otel-collector \
+        -v "$CONFIG_PATH:/etc/otel-collector-config.yml:ro" \
+        "$IMAGE_OTEL" \
+        --config=/etc/otel-collector-config.yml
+
+    echo ""
+    echo "Waiting for backends to become healthy..."
+    vm_ok=true
+    vl_ok=true
+    vt_ok=true
+    wait_for_health "http://localhost:8428/health" "VictoriaMetrics" || vm_ok=false
+    wait_for_health "http://localhost:9428/health" "VictoriaLogs" || vl_ok=false
+    # VictoriaTraces has no /health endpoint; use Jaeger services API as readiness probe
+    wait_for_health "http://localhost:10428/select/jaeger/api/services" "VictoriaTraces" || vt_ok=false
+
+    if [ "$vm_ok" = false ] || [ "$vl_ok" = false ] || [ "$vt_ok" = false ]; then
+        echo "WARNING: Some backends did not become healthy. Check 'podman pod ps' and container logs."
+    fi
+
+    echo ""
+    echo "--- Local OTel Stack Ready ---"
+    echo "Metrics UI (vmui):  http://localhost:8428/vmui"
+    echo "Logs UI (vmui):     http://localhost:9428/select/vmui/"
+    echo "Traces UI (vmui):   http://localhost:10428/select/vmui"
+    echo "OTLP HTTP:          http://localhost:4318"
+    echo "OTLP gRPC:          localhost:4317"
+    echo "Metrics (PromQL):   http://localhost:8428/api/v1/query"
+    echo "Logs (LogsQL):      http://localhost:9428/select/logsql/query"
+    echo "Traces (Jaeger):    http://localhost:10428/select/jaeger/api/traces"
+    echo ""
+    echo "Example queries:"
+    echo "  curl 'http://localhost:8428/api/v1/query?query=up'"
+    echo "  curl 'http://localhost:9428/select/logsql/query?query=*'"
+    echo "  curl 'http://localhost:10428/select/jaeger/api/services'"
+}
+
+if [ "$FORCE_CLEANUP" = true ]; then
+    force_cleanup
+elif [ "$STOP" = true ]; then
+    stop_stack
+else
+    start_stack
+fi
diff --git a/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh b/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh
new file mode 100755
index 0000000..52494d9
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/test-local-otel-stack.sh
@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# Smoke test for the local OpenTelemetry observability stack.
+#
+# Starts the stack, sends sample telemetry via telemetrygen, queries each
+# backend API, asserts non-empty results, and tears down.
+#
+# Usage:
+#   ./test-local-otel-stack.sh
+#
+# CI note: register trap before any fallible commands so cleanup fires even
+# on early failures. If the CI runner may be killed with SIGKILL (not
+# SIGTERM), add a post-job step:  ./start-local-otel-stack.sh --force-cleanup
+# or run with: timeout 120 ./test-local-otel-stack.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+START_SCRIPT="$SCRIPT_DIR/start-local-otel-stack.sh"
+
+# Image versions — single source of truth
+# shellcheck source=versions.env
+source "$SCRIPT_DIR/versions.env"
+
+POD_NAME="local-otel-stack"
+
+PASSED=0
+FAILED=0
+
+assert_non_empty() {
+    local test_name="$1"
+    local content="$2"
+    local trimmed
+    trimmed="$(echo "$content" | tr -d '[:space:]')"
+
+    if [ -z "$trimmed" ] || [ "$trimmed" = "{}" ] || [ "$trimmed" = "[]" ] || [ "$trimmed" = '{"status":"success","data":[]}' ]; then
+        echo "  FAIL: $test_name - empty response"
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+    echo "  PASS: $test_name"
+    PASSED=$((PASSED + 1))
+    return 0
+}
+
+assert_contains() {
+    local test_name="$1"
+    local content="$2"
+    local expected="$3"
+
+    if echo "$content" | grep -qi "$expected"; then
+        echo "  PASS: $test_name (contains '$expected')"
+        PASSED=$((PASSED + 1))
+        return 0
+    fi
+    echo "  FAIL: $test_name - response does not contain '$expected'"
+    FAILED=$((FAILED + 1))
+    return 1
+}
+
+# poll_url <url> <label> [timeout_secs]
+# Polls url up to timeout_secs (default 60), every 2s, until it returns HTTP 2xx.
+# Returns 0 on success, 1 on timeout.
+poll_url() {
+    local url="$1"
+    local label="$2"
+    local timeout="${3:-60}"
+    local elapsed=0
+
+    while [ "$elapsed" -lt "$timeout" ]; do
+        if curl -sf --max-time 3 "$url" >/dev/null 2>&1; then
+            echo "  OK: $label is ready"
+            return 0
+        fi
+        sleep 2
+        elapsed=$((elapsed + 2))
+    done
+    echo "  TIMEOUT: $label did not become ready within ${timeout}s"
+    return 1
+}
+
+# poll_non_empty <url> <label> [timeout_secs]
+# Polls url up to timeout_secs, returning 0 when the response is non-empty/non-trivial.
+poll_non_empty() {
+    local url="$1"
+    local label="$2"
+    local timeout="${3:-30}"
+    local elapsed=0
+    local result
+
+    while [ "$elapsed" -lt "$timeout" ]; do
+        result=$(curl -sf --max-time 3 "$url" 2>/dev/null || echo "")
+        local trimmed
+        trimmed="$(echo "$result" | tr -d '[:space:]')"
+        if [ -n "$trimmed" ] \
+            && [ "$trimmed" != "{}" ] \
+            && [ "$trimmed" != "[]" ] \
+            && [ "$trimmed" != '{"status":"success","data":[]}' ]; then
+            echo "$result"
+            return 0
+        fi
+        sleep 2
+        elapsed=$((elapsed + 2))
+    done
+    echo ""
+    return 1
+}
+
+# Register trap as the very first fallible point so cleanup fires even on
+# early arg-parse failures or set -e exits.
+cleanup() {
+    echo ""
+    echo "=== Tearing down ==="
+    bash "$START_SCRIPT" --stop || true
+}
+trap cleanup EXIT
+
+# On Git Bash, prevent POSIX path translation
+export MSYS_NO_PATHCONV=1
+
+# Step 0: Force-cleanup any leftover state from a previous run so this test
+# is fully idempotent even after a SIGKILL or a failed prior run.
+echo ""
+echo "=== Pre-flight: removing any leftover containers ==="
+bash "$START_SCRIPT" --force-cleanup
+
+# Step 1: Start the stack
+echo ""
+echo "=== Starting local OTel stack ==="
+bash "$START_SCRIPT" --force
+
+# Step 2: Wait for all services to be healthy before sending any telemetry.
+# The start script already waits for backends, but we additionally poll the
+# OTel Collector health endpoint here to ensure it is ready to receive OTLP.
+echo ""
+echo "=== Waiting for OTel Collector to be ready ==="
+if ! poll_url "http://localhost:13133" "OTel Collector health" 60; then
+    echo "ERROR: OTel Collector did not become ready. Aborting." >&2
+    exit 1
+fi
+
+# Step 3: Send sample telemetry
+echo ""
+echo "=== Sending sample telemetry ==="
+
+echo "  Sending traces..."
+podman run --rm --pod "$POD_NAME" "$IMAGE_TELEMETRYGEN" \
+    traces --otlp-http --otlp-insecure --otlp-endpoint localhost:4318 --duration 5s || echo "  WARNING: telemetrygen traces failed"
+
+echo "  Sending metrics..."
+podman run --rm --pod "$POD_NAME" "$IMAGE_TELEMETRYGEN" \
+    metrics --otlp-http --otlp-insecure --otlp-endpoint localhost:4318 --duration 5s || echo "  WARNING: telemetrygen metrics failed"
+
+echo "  Sending logs..."
+podman run --rm --pod "$POD_NAME" "$IMAGE_TELEMETRYGEN" \
+    logs --otlp-http --otlp-insecure --otlp-endpoint localhost:4318 --duration 5s || echo "  WARNING: telemetrygen logs failed"
+
+# Step 4: Poll each backend until data appears (up to 30s each) rather than
+# waiting a fixed amount of time. This is faster on capable hardware and more
+# reliable on slow or resource-constrained runners.
+echo ""
+echo "=== Querying backends (with retry, up to 30s each) ==="
+
+echo "  Querying VictoriaMetrics..."
+metrics_result=$(poll_non_empty 'http://localhost:8428/api/v1/label/__name__/values' "VictoriaMetrics data" 30 || echo "")
+assert_non_empty "VictoriaMetrics - metrics query" "$metrics_result" || true
+# telemetrygen emits gen_metric_* metrics — verify telemetrygen-specific data was ingested
+assert_contains "VictoriaMetrics - telemetrygen data" "$metrics_result" "gen" || true
+
+echo "  Querying VictoriaLogs..."
+logs_result=$(poll_non_empty 'http://localhost:9428/select/logsql/query?query=*' "VictoriaLogs data" 30 || echo "")
+assert_non_empty "VictoriaLogs - logs query" "$logs_result" || true
+# telemetrygen logs include the telemetrygen service name
+assert_contains "VictoriaLogs - telemetrygen data" "$logs_result" "telemetrygen" || true
+
+echo "  Querying VictoriaTraces..."
+traces_result=$(poll_non_empty 'http://localhost:10428/select/jaeger/api/services' "VictoriaTraces data" 30 || echo "")
+assert_non_empty "VictoriaTraces - services query" "$traces_result" || true
+# telemetrygen registers as a service — verify it appears in the Jaeger services list
+assert_contains "VictoriaTraces - telemetrygen service" "$traces_result" "telemetrygen" || true
+
+# Step 4b: Verify vmui endpoints are reachable
+echo ""
+echo "=== Verifying vmui endpoints ==="
+vmui_vm=$(curl -sf -o /dev/null -w "%{http_code}" http://localhost:8428/vmui/ 2>/dev/null || echo "000")
+if [ "$vmui_vm" = "200" ]; then
+    echo "  PASS: VictoriaMetrics vmui reachable"
+    PASSED=$((PASSED + 1))
+else
+    echo "  FAIL: VictoriaMetrics vmui not reachable (HTTP $vmui_vm)"
+    FAILED=$((FAILED + 1))
+fi
+
+vmui_vl=$(curl -sf -o /dev/null -w "%{http_code}" http://localhost:9428/select/vmui/ 2>/dev/null || echo "000")
+if [ "$vmui_vl" = "200" ]; then
+    echo "  PASS: VictoriaLogs vmui reachable"
+    PASSED=$((PASSED + 1))
+else
+    echo "  FAIL: VictoriaLogs vmui not reachable (HTTP $vmui_vl)"
+    FAILED=$((FAILED + 1))
+fi
+
+vmui_vt=$(curl -sf -o /dev/null -w "%{http_code}" http://localhost:10428/select/vmui 2>/dev/null || echo "000")
+if [ "$vmui_vt" = "200" ]; then
+    echo "  PASS: VictoriaTraces vmui reachable"
+    PASSED=$((PASSED + 1))
+else
+    echo "  FAIL: VictoriaTraces vmui not reachable (HTTP $vmui_vt)"
+    FAILED=$((FAILED + 1))
+fi
+
+# Step 5: Report results
+echo ""
+echo "=== Results ==="
+echo "  Passed: $PASSED"
+echo "  Failed: $FAILED"
+
+if [ "$FAILED" -gt 0 ]; then
+    echo ""
+    echo "SMOKE TEST FAILED"
+    exit 1
+else
+    echo ""
+    echo "SMOKE TEST PASSED"
+    exit 0
+fi
diff --git a/playbooks/setup/create-local-otel-stack/validate-config.sh b/playbooks/setup/create-local-otel-stack/validate-config.sh
new file mode 100755
index 0000000..4b9ee28
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/validate-config.sh
@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Validate configuration files for the local OpenTelemetry observability stack.
+#
+# This script validates the configuration without requiring a container runtime,
+# making it suitable for CI/CD environments where containers may not be available.
+#
+# Usage:
+#   ./validate-config.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# Image versions — single source of truth
+# shellcheck source=versions.env
+source "$SCRIPT_DIR/versions.env"
+
+PASSED=0
+FAILED=0
+
+assert_file_exists() {
+    local test_name="$1"
+    local file_path="$2"
+    
+    if [ -f "$file_path" ]; then
+        echo "  PASS: $test_name - file exists"
+        PASSED=$((PASSED + 1))
+        return 0
+    else
+        echo "  FAIL: $test_name - file not found: $file_path"
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+}
+
+assert_file_executable() {
+    local test_name="$1"
+    local file_path="$2"
+    
+    if [ -x "$file_path" ]; then
+        echo "  PASS: $test_name - file is executable"
+        PASSED=$((PASSED + 1))
+        return 0
+    else
+        echo "  FAIL: $test_name - file is not executable: $file_path"
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+}
+
+assert_yaml_valid() {
+    local test_name="$1"
+    local file_path="$2"
+    
+    # Check if yq is available for YAML validation
+    if command -v yq >/dev/null 2>&1; then
+        if yq eval '.' "$file_path" >/dev/null 2>&1; then
+            echo "  PASS: $test_name - valid YAML"
+            PASSED=$((PASSED + 1))
+            return 0
+        else
+            echo "  FAIL: $test_name - invalid YAML"
+            FAILED=$((FAILED + 1))
+            return 1
+        fi
+    else
+        echo "  SKIP: $test_name - yq not available for YAML validation"
+        return 0
+    fi
+}
+
+assert_env_format() {
+    local test_name="$1"
+    local file_path="$2"
+    
+    # Check if the file follows KEY=VALUE format
+    while IFS= read -r line; do
+        # Skip comments and empty lines
+        if [[ "$line" =~ ^[[:space:]]*# ]] || [[ -z "${line// }" ]]; then
+            continue
+        fi
+        
+        if [[ ! "$line" =~ ^[A-Z_][A-Z0-9_]*= ]]; then
+            echo "  FAIL: $test_name - invalid format: $line"
+            FAILED=$((FAILED + 1))
+            return 1
+        fi
+    done < "$file_path"
+    
+    echo "  PASS: $test_name - valid env format"
+    PASSED=$((PASSED + 1))
+    return 0
+}
+
+assert_contains() {
+    local test_name="$1"
+    local file_path="$2"
+    local expected="$3"
+    
+    if grep -q "$expected" "$file_path"; then
+        echo "  PASS: $test_name - contains '$expected'"
+        PASSED=$((PASSED + 1))
+        return 0
+    else
+        echo "  FAIL: $test_name - missing '$expected'"
+        FAILED=$((FAILED + 1))
+        return 1
+    fi
+}
+
+echo "=== Validating Local OTel Stack Configuration ==="
+
+# Check required files exist
+echo ""
+echo "=== Checking required files ==="
+assert_file_exists "versions.env" "$SCRIPT_DIR/versions.env"
+assert_file_exists "otel-collector-config.yaml" "$SCRIPT_DIR/otel-collector-config.yaml"
+assert_file_exists "otel-collector-sidecar-config.yaml" "$SCRIPT_DIR/otel-collector-sidecar-config.yaml"
+assert_file_exists "otel-collector-config-compose.yaml" "$SCRIPT_DIR/otel-collector-config-compose.yaml"
+assert_file_exists "docker-compose.yaml" "$SCRIPT_DIR/docker-compose.yaml"
+
+# Check scripts are executable
+echo ""
+echo "=== Checking script permissions ==="
+assert_file_executable "start-local-otel-stack.sh" "$SCRIPT_DIR/start-local-otel-stack.sh"
+assert_file_executable "test-local-otel-stack.sh" "$SCRIPT_DIR/test-local-otel-stack.sh"
+assert_file_executable "validate-config.sh" "$SCRIPT_DIR/validate-config.sh"
+
+# Validate configuration file formats
+echo ""
+echo "=== Validating configuration formats ==="
+assert_env_format "versions.env format" "$SCRIPT_DIR/versions.env"
+assert_yaml_valid "otel-collector-config.yaml" "$SCRIPT_DIR/otel-collector-config.yaml"
+assert_yaml_valid "otel-collector-sidecar-config.yaml" "$SCRIPT_DIR/otel-collector-sidecar-config.yaml"
+assert_yaml_valid "otel-collector-config-compose.yaml" "$SCRIPT_DIR/otel-collector-config-compose.yaml"
+assert_yaml_valid "docker-compose.yaml" "$SCRIPT_DIR/docker-compose.yaml"
+
+# Check critical configuration content
+echo ""
+echo "=== Checking configuration content ==="
+assert_contains "OTel receiver config" "$SCRIPT_DIR/otel-collector-config.yaml" "receivers:"
+assert_contains "OTel exporter config" "$SCRIPT_DIR/otel-collector-config.yaml" "exporters:"
+assert_contains "OTel service config" "$SCRIPT_DIR/otel-collector-config.yaml" "service:"
+assert_contains "Sidecar host.containers.internal" "$SCRIPT_DIR/otel-collector-sidecar-config.yaml" "host.containers.internal"
+assert_contains "Compose service names" "$SCRIPT_DIR/otel-collector-config-compose.yaml" "victoriametrics:"
+assert_contains "Docker compose services" "$SCRIPT_DIR/docker-compose.yaml" "services:"
+assert_contains "Image versions defined" "$SCRIPT_DIR/versions.env" "IMAGE_OTEL="
+
+# Check docker-compose.yaml uses variable substitution (not hardcoded versions).
+# docker-compose.yaml reads image versions from versions.env via ${IMAGE_*}
+# placeholders — this check verifies the placeholders are present so the file
+# stays in sync with versions.env automatically.
+echo ""
+echo "=== Checking docker-compose.yaml version variable substitution ==="
+for var in IMAGE_OTEL IMAGE_VM IMAGE_VL IMAGE_VT; do
+    if grep -q "\${${var}}" "$SCRIPT_DIR/docker-compose.yaml"; then
+        echo "  PASS: docker-compose.yaml references \${${var}}"
+        PASSED=$((PASSED + 1))
+    else
+        echo "  FAIL: docker-compose.yaml does not reference \${${var}} — version may be hardcoded"
+        FAILED=$((FAILED + 1))
+    fi
+done
+
+# Check docker-compose.yaml binds all ports to localhost only (127.0.0.1).
+# Each port is checked individually to prevent partial misconfigurations.
+echo ""
+echo "=== Checking port bindings (127.0.0.1 only) ==="
+for port in 4317 4318 8428 9428 10428; do
+    assert_contains "Port $port bound to localhost" \
+        "$SCRIPT_DIR/docker-compose.yaml" "127.0.0.1:${port}:${port}"
+done
+
+# Report results
+echo ""
+echo "=== Validation Results ==="
+echo "  Passed: $PASSED"
+echo "  Failed: $FAILED"
+
+if [ "$FAILED" -gt 0 ]; then
+    echo ""
+    echo "CONFIGURATION VALIDATION FAILED"
+    exit 1
+else
+    echo ""
+    echo "CONFIGURATION VALIDATION PASSED"
+    echo ""
+    echo "Note: Full smoke test requires a container runtime (podman/docker)."
+    echo "Run './test-local-otel-stack.sh' when a runtime is available."
+    exit 0
+fi
diff --git a/playbooks/setup/create-local-otel-stack/versions.env b/playbooks/setup/create-local-otel-stack/versions.env
new file mode 100644
index 0000000..61cf31d
--- /dev/null
+++ b/playbooks/setup/create-local-otel-stack/versions.env
@@ -0,0 +1,9 @@
+# Canonical source of truth for container image versions.
+# Sourced by start and test scripts (PowerShell and Bash).
+# Update versions here — they propagate to all scripts automatically.
+
+IMAGE_OTEL=ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.133.0
+IMAGE_VM=victoriametrics/victoria-metrics:v1.130.0
+IMAGE_VL=victoriametrics/victoria-logs:v1.47.0
+IMAGE_VT=victoriametrics/victoria-traces:v0.7.1
+IMAGE_TELEMETRYGEN=ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.133.0
diff --git a/playbooks/setup/discover-local-otel-stack.md b/playbooks/setup/discover-local-otel-stack.md
new file mode 100644
index 0000000..def21bb
--- /dev/null
+++ b/playbooks/setup/discover-local-otel-stack.md
@@ -0,0 +1,95 @@
+<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
+---
+name: setup-discover-local-otel-stack
+description: >
+  Use to determine whether a local OpenTelemetry stack is already running on this machine.
+  Always run this before using create-local-otel-stack or use-local-otel-stack.
+  Returns whether each component (OTel Collector, VictoriaMetrics, VictoriaLogs, VictoriaTraces)
+  is healthy and what endpoints are available.
+keywords: [discover otel stack, find otel stack, otel stack running]
+---
+
+# Discover Local OTel Stack
+
+Use this skill to determine whether a local OpenTelemetry observability stack is currently running.
+Run it before creating a new stack or configuring an app to send telemetry.
+
+## Quick check: all components
+
+Run all four health checks in one line:
+
+    curl -sf http://localhost:8428/health \
+      && curl -sf http://localhost:9428/health \
+      && curl -s --max-time 2 -o /dev/null http://localhost:4318/ \
+      && curl -sf http://localhost:10428/select/jaeger/api/services \
+      && echo "STACK RUNNING" || echo "STACK NOT RUNNING (or partially unavailable)"
+
+> Note: The OTel Collector check uses `/` (not `/v1/metrics`) because OTLP endpoints return 405/415 on GET requests
+> (they expect POST with protobuf bodies). We check TCP reachability to the collector port instead of HTTP status,
+> using `--max-time 2` to avoid hanging if the port is not listening.
+
+## Individual component checks
+
+| Component | Health endpoint | Expected response |
+|-----------|----------------|-------------------|
+| VictoriaMetrics | `http://localhost:8428/health` | `200 OK` |
+| VictoriaLogs | `http://localhost:9428/health` | `200 OK` |
+| VictoriaTraces | `http://localhost:10428/select/jaeger/api/services` | JSON array |
+| OTel Collector (HTTP) | `http://localhost:4318/` | TCP connect succeeds (any HTTP response) |
+| OTel Collector (gRPC) | Port 4317 | TCP connect succeeds |
+
+### Detailed checks
+
+    # VictoriaMetrics
+    curl http://localhost:8428/health
+
+    # VictoriaLogs
+    curl http://localhost:9428/health
+
+    # VictoriaTraces (list registered services)
+    curl http://localhost:10428/select/jaeger/api/services
+
+    # OTel Collector HTTP receiver (TCP reachability check)
+    curl -s --max-time 2 -o /dev/null http://localhost:4318/
+
+    # OTel Collector gRPC port (TCP reachability)
+    curl --max-time 2 http://localhost:4317 || echo "gRPC port check (non-200 is normal)"
+
+## Checking from inside a container
+
+From within a container, replace `localhost` with `host.containers.internal`:
+
+    curl http://host.containers.internal:8428/health
+    curl http://host.containers.internal:9428/health
+
+See the `host.containers.internal` compatibility table in `use-local-otel-stack` for
+runtime-specific availability.
+
+## Interpreting results
+
+| Result | Next step |
+|--------|-----------|
+| All components respond | Stack is running — proceed to `use-local-otel-stack` |
+| No components respond | Stack is not running — use `create-local-otel-stack` |
+| Some components respond | Partial failure — check container logs; may need `--force` restart |
+
+## Verifying data is flowing (optional)
+
+If the stack is running, confirm telemetry data is being received:
+
+    # Any metrics present?
+    curl 'http://localhost:8428/api/v1/label/__name__/values'
+
+    # Any logs present?
+    curl 'http://localhost:9428/select/logsql/query?query=*&limit=1'
+
+    # Any traces present?
+    curl 'http://localhost:10428/select/jaeger/api/services'
+
+Empty arrays indicate the stack is up but no telemetry has been sent yet.
+
+## Related Skills
+
+- [create-local-otel-stack](create-local-otel-stack.md) — Start a new local OTel stack.
+- [use-local-otel-stack](use-local-otel-stack.md) — Configure OTLP endpoint and query the local stack.
+- [instrument-dotnet-otel](instrument-dotnet-otel.md) — Instrument a .NET app with the OTel SDK.
diff --git a/playbooks/setup/instrument-dotnet-otel.md b/playbooks/setup/instrument-dotnet-otel.md
new file mode 100644
index 0000000..ec67d8d
--- /dev/null
+++ b/playbooks/setup/instrument-dotnet-otel.md
@@ -0,0 +1,226 @@
+<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
+---
+name: setup-instrument-dotnet-otel
+description: >
+  Use when instrumenting a .NET application with the OpenTelemetry SDK for traces, metrics, and logs.
+  Covers SDK setup, OTLP export configuration, and three known pitfalls with the .NET OTLP exporter:
+  explicit endpoint breaking signal path appending, gRPC unreachable via host.containers.internal,
+  and ActivityListener test isolation failures. Use use-local-otel-stack to send telemetry to a local
+  stack for testing.
+keywords: [instrument dotnet, dotnet otel, opentelemetry dotnet, dotnet sdk otel]
+---
+
+# Instrument .NET Apps with OpenTelemetry
+
+Use this skill when adding OpenTelemetry SDK instrumentation to a .NET application.
+
+> **Testing telemetry locally?** Use `use-local-otel-stack` to send telemetry to a local stack.
+> Use `discover-local-otel-stack` first to confirm it is running.
+
+## NuGet packages
+
+    dotnet add package OpenTelemetry.Extensions.Hosting
+    dotnet add package OpenTelemetry.Instrumentation.AspNetCore
+    dotnet add package OpenTelemetry.Instrumentation.Http
+    dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
+
+For integration tests:
+
+    dotnet add package OpenTelemetry.Exporter.InMemory
+
+## Startup.cs — canonical pattern
+
+```csharp
+services.AddOpenTelemetry()
+    .ConfigureResource(resource => resource
+        .AddService(serviceName: config.ServiceName, serviceVersion: config.ServiceVersion)
+        .AddAttributes(new Dictionary<string, object>
+        {
+            ["environment"] = env.EnvironmentName,
+        }))
+    .WithTracing(builder => builder
+        .AddAspNetCoreInstrumentation()
+        .AddHttpClientInstrumentation()
+        .AddSource("MyApp")
+        .AddOtlpExporter())     // no lambda — reads OTEL_EXPORTER_OTLP_* env vars
+    .WithMetrics(builder => builder
+        .AddMeter("Microsoft.AspNetCore.Hosting")
+        .AddMeter("System.Net.Http")
+        .AddMeter("MyApp")
+        .AddOtlpExporter())     // no lambda
+    .WithLogging(
+        builder => builder.AddOtlpExporter(),   // no lambda
+        options =>
+        {
+            options.IncludeFormattedMessage = true;  // export the rendered log string, not just the template
+            options.IncludeScopes = true;            // include ILogger.BeginScope() data as log attributes
+        });
+```
+
+**Key point:** Use `AddOtlpExporter()` with no lambda. Let the SDK read `OTEL_EXPORTER_OTLP_*`
+environment variables at runtime. Setting `options.Endpoint` in code triggers a known pitfall
+(see below).
+
+## Environment variables
+
+```
+# Local development: no env vars needed — SDK defaults to localhost:4317 (gRPC)
+
+# Local stack via host.containers.internal (use HTTP, not gRPC — see pitfall 2):
+OTEL_EXPORTER_OTLP_ENDPOINT=http://host.containers.internal:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+# Production / remote collector:
+OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+# Optional: override the service name set in code
+OTEL_SERVICE_NAME=my-service
+```
+
+---
+
+## Known pitfalls
+
+### Pitfall 1: Explicit `options.Endpoint` breaks HTTP/protobuf signal path appending
+
+**Affects:** `OpenTelemetry.Exporter.OpenTelemetryProtocol` 1.15+ with HTTP/protobuf protocol.
+
+**Symptom:** The exporter sends `POST /` and receives 404, even though the collector is alive
+on port 4318 and `/v1/traces` returns 415 (correct — expects a protobuf body).
+
+App logs:
+```
+Sending HTTP request "POST" "http://host.containers.internal:4318/"
+Received HTTP response headers after 4.7ms - 404
+```
+
+**Root cause:** When `options.Endpoint` is set explicitly, `new Uri("http://host:4318")` normalises
+to `http://host:4318/` (trailing slash). The SDK sees a path component (`/`) and treats it as a
+user-specified custom path, so it does **not** append `/v1/traces`, `/v1/metrics`, etc.
+When the endpoint comes from `OTEL_EXPORTER_OTLP_ENDPOINT`, the SDK's internal parsing handles
+this correctly.
+
+**Broken pattern:**
+```csharp
+.AddOtlpExporter(options =>
+{
+    options.Endpoint = new Uri(otelConfig.OtlpEndpoint);  // DO NOT do this
+    options.Protocol = OtlpExportProtocol.HttpProtobuf;
+})
+```
+
+**Fix:** Remove the lambda entirely:
+```csharp
+.AddOtlpExporter()
+```
+
+Set the endpoint via environment variable instead:
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://host.containers.internal:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+```
+
+**If you must set the endpoint in code**, append the signal path yourself:
+```csharp
+.WithTracing(builder => builder
+    .AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri(otelConfig.OtlpEndpoint + "/v1/traces");
+        options.Protocol = OtlpExportProtocol.HttpProtobuf;
+    }))
+.WithMetrics(builder => builder
+    .AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri(otelConfig.OtlpEndpoint + "/v1/metrics");
+        options.Protocol = OtlpExportProtocol.HttpProtobuf;
+    }))
+.WithLogging(builder => builder
+    .AddOtlpExporter(options =>
+    {
+        options.Endpoint = new Uri(otelConfig.OtlpEndpoint + "/v1/logs");
+        options.Protocol = OtlpExportProtocol.HttpProtobuf;
+    }))
+```
+This is fragile. Prefer env vars.
+
+---
+
+### Pitfall 2: gRPC (port 4317) unreachable via `host.containers.internal`
+
+**Symptom:** The exporter logs `POST http://host.containers.internal:4317/` but never logs a
+response. Export hangs until timeout.
+
+**Root cause:** The gRPC port (4317) is not reachable via `host.containers.internal` from inside
+WSL2/container environments, even when the HTTP port (4318) on the same collector is reachable.
+
+**Tested endpoint matrix:**
+
+| Endpoint | Protocol | Status |
+|----------|----------|--------|
+| `localhost:4317` | gRPC | Works |
+| `localhost:4318` | HTTP/protobuf | Works |
+| `host.containers.internal:4317` | gRPC | Hangs (no response) |
+| `host.containers.internal:4318` | HTTP/protobuf | Works |
+
+**Fix:** Use HTTP/protobuf on port 4318 when using `host.containers.internal`:
+
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://host.containers.internal:4318
+OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+```
+
+For localhost (direct container or local dev), gRPC on port 4317 works fine and is the SDK default.
+
+---
+
+### Pitfall 3: `ActivityListener` flaky in integration test suites
+
+**Symptom:** An integration test using `ActivityListener` to capture OTel spans passes when run
+alone but fails intermittently in the full test suite:
+```
+Expected: not <empty>
+But was:  < <System.Diagnostics.Activity> >
+```
+
+**Root cause:** `ActivityListener` and `ActivitySource` are global statics. When other tests create
+`TestServer` instances that initialise `TracerProvider`, the global activity state is polluted.
+Test execution order affects which listener captures which activities.
+
+**Fix:** Use `InMemoryExporter` from `OpenTelemetry.Exporter.InMemory` instead:
+
+```csharp
+var exportedActivities = new List<Activity>();
+
+using var server = CreateTestServer(services =>
+{
+    services.ConfigureOpenTelemetryTracerProvider(builder =>
+        builder.AddInMemoryExporter(exportedActivities));
+});
+
+using var client = server.CreateClient();
+await client.GetAsync("/health");
+
+var tracerProvider = server.Services.GetService<TracerProvider>();
+tracerProvider.ForceFlush();
+
+Assert.That(exportedActivities, Is.Not.Empty);
+```
+
+Key points:
+- `ConfigureOpenTelemetryTracerProvider` adds the in-memory exporter alongside Startup.cs config.
+- `ForceFlush()` ensures all spans are exported before asserting.
+- No global state pollution — each test gets its own `TestServer` and exporter collection.
+
+Test project package reference:
+```xml
+<PackageReference Include="OpenTelemetry.Exporter.InMemory" Version="1.*" />
+```
+
+---
+
+## Related Skills
+
+- [discover-local-otel-stack](discover-local-otel-stack.md) — Check whether a local OTel stack is running.
+- [use-local-otel-stack](use-local-otel-stack.md) — Configure OTLP endpoint and query the local stack.
+- [create-local-otel-stack](create-local-otel-stack.md) — Start a new local OTel stack.
diff --git a/playbooks/setup/use-local-otel-stack.md b/playbooks/setup/use-local-otel-stack.md
new file mode 100644
index 0000000..77914d2
--- /dev/null
+++ b/playbooks/setup/use-local-otel-stack.md
@@ -0,0 +1,151 @@
+<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
+---
+name: setup-use-local-otel-stack
+description: >
+  Use when you need to send OpenTelemetry telemetry to a local stack, or query it
+  for metrics, logs, or traces during development or testing.
+  Run discover-local-otel-stack first to confirm the stack is available.
+  Do not use this skill when you need to access real production telemetry.
+keywords: [use otel stack, connect otel, send telemetry, otlp endpoint]
+---
+
+# Use Local OTel Stack
+
+Use this skill to configure applications or agents to send OTLP telemetry to a running local stack,
+or to query the stack for metrics, logs, and traces.
+
+> **Prerequisite:** Run `discover-local-otel-stack` first to confirm the stack is available.
+> If it is not running, use `create-local-otel-stack` to start it.
+
+## Sending telemetry: endpoint configuration
+
+The recommended approach is to configure the OTLP endpoint via environment variables.
+The OTel SDK reads these natively across all supported languages.
+
+### From the host machine
+
+    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+> Use HTTP/protobuf (port 4318), not gRPC (port 4317), for the local stack.
+> The default gRPC port works on localhost but is unreliable via `host.containers.internal`.
+> See [Known pitfalls](#known-pitfalls) below.
+
+### From inside a container
+
+The host machine's stack is accessible via `host.containers.internal`:
+
+    export OTEL_EXPORTER_OTLP_ENDPOINT=http://host.containers.internal:4318
+    export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+**`host.containers.internal` availability by runtime:**
+
+| Runtime | Platform | Available? | Notes |
+|---------|----------|-----------|-------|
+| Podman | Linux, macOS, Windows | Yes | Injected automatically |
+| Docker Desktop | macOS, Windows | Yes | Injected automatically |
+| Docker Engine (plain) | Linux | No | Use `--add-host=host.docker.internal:host-gateway` |
+| Rancher Desktop (nerdctl) | macOS, Windows | Usually | Add `--add-host` if not working |
+
+For plain Docker Engine on Linux, substitute `host.docker.internal` for `host.containers.internal`
+and pass `--add-host=host.docker.internal:host-gateway` when running the container.
+
+### Sidecar pattern (agent containers, Scenario 1)
+
+If the container already runs a local OTel Collector sidecar (forwarding to `host.containers.internal:4318`):
+
+    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+The sidecar config (`otel-collector-sidecar-config.yaml` in `create-local-otel-stack`) forwards to the host stack.
+
+## Querying the stack
+
+### Endpoints
+
+| Signal | Protocol | URL (from host) | URL (from container) |
+|--------|----------|-----------------|----------------------|
+| Metrics | PromQL | `http://localhost:8428/api/v1/query` | `http://host.containers.internal:8428/api/v1/query` |
+| Logs | LogsQL | `http://localhost:9428/select/logsql/query` | `http://host.containers.internal:9428/select/logsql/query` |
+| Traces | Jaeger API | `http://localhost:10428/select/jaeger/api/traces` | `http://host.containers.internal:10428/select/jaeger/api/traces` |
+
+### UI access
+
+| What | URL |
+|------|-----|
+| VictoriaMetrics UI | `http://localhost:8428/vmui` |
+| VictoriaLogs UI | `http://localhost:9428/select/vmui/` |
+| VictoriaTraces UI | `http://localhost:10428/select/vmui` |
+
+### Example queries
+
+    # Metrics: list all metric names
+    curl 'http://localhost:8428/api/v1/label/__name__/values'
+
+    # Metrics: query a specific metric
+    curl 'http://localhost:8428/api/v1/query?query=up'
+
+    # Logs: all recent logs
+    curl 'http://localhost:9428/select/logsql/query?query=*'
+
+    # Logs: filter by service name
+    curl 'http://localhost:9428/select/logsql/query?query=_service_name="myservice"'
+
+    # Traces: list services
+    curl 'http://localhost:10428/select/jaeger/api/services'
+
+    # Traces: get traces for a service
+    curl 'http://localhost:10428/select/jaeger/api/traces?service=myservice'
+
+## Integration with agent workflows
+
+### AI agents running in containers
+
+1. Include `otel-collector-sidecar-config.yaml` in the agent container.
+2. Start the sidecar collector alongside the main process.
+3. Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`.
+4. The sidecar forwards telemetry to the host stack via `host.containers.internal:4318`.
+
+### Local development and testing
+
+1. Confirm the stack is running (`discover-local-otel-stack`).
+2. Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`.
+3. Optionally set `OTEL_SERVICE_NAME=my-service` to identify the service in the backend.
+
+## Known pitfalls
+
+### gRPC (port 4317) unreachable via `host.containers.internal`
+
+**Symptom:** The exporter logs `POST http://host.containers.internal:4317/` but never logs a response.
+Export hangs until timeout.
+
+**Root cause:** The gRPC endpoint (port 4317) does not work via `host.containers.internal` even
+when the HTTP endpoint (port 4318) on the same collector does. This is specific to the
+`host.containers.internal` network path in WSL2/container environments.
+
+**Tested endpoint matrix:**
+
+| Endpoint | Protocol | Status |
+|----------|----------|--------|
+| `localhost:4317` | gRPC | Works |
+| `localhost:4318` | HTTP/protobuf | Works |
+| `host.containers.internal:4317` | gRPC | Hangs (no response) |
+| `host.containers.internal:4318` | HTTP/protobuf | Works |
+
+**Fix:** Always use HTTP/protobuf on port 4318 for `host.containers.internal`:
+
+    OTEL_EXPORTER_OTLP_ENDPOINT=http://host.containers.internal:4318
+    OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+
+### .NET: explicit `options.Endpoint` breaks signal path appending
+
+For .NET applications using the `OpenTelemetry.Exporter.OpenTelemetryProtocol` package,
+setting `options.Endpoint` explicitly in code can cause the SDK to send to `/` instead of
+`/v1/traces` or `/v1/metrics`.
+
+See [instrument-dotnet-otel](instrument-dotnet-otel.md) for the full explanation and fix.
+
+## Related Skills
+
+- [discover-local-otel-stack](discover-local-otel-stack.md) — Check whether a local OTel stack is running.
+- [create-local-otel-stack](create-local-otel-stack.md) — Start a new local OTel stack.
+- [instrument-dotnet-otel](instrument-dotnet-otel.md) — Instrument a .NET app with the OTel SDK.
diff --git a/tests/test-deploy.sh b/tests/test-deploy.sh
index 2bfea53..d0cb7cc 100644
--- a/tests/test-deploy.sh
+++ b/tests/test-deploy.sh
@@ -13,6 +13,15 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
+# Detect whether the source filesystem supports permission differentiation.
+# On WSL2-mounted Windows filesystems, all files are rwxrwxrwx regardless
+# of git index permissions. In that case, skip non-executable assertions
+# because cp preserves the (always-executable) source permissions.
+PERMS_SUPPORTED=true
+if [ -x "$REPO_DIR/README.md" ]; then
+  PERMS_SUPPORTED=false
+fi
+
 PASSED=0
 FAILED=0
 
@@ -69,6 +78,10 @@ assert_executable() {
 assert_not_executable() {
   local label="$1"
   local path="$2"
+  if [ "$PERMS_SUPPORTED" = false ]; then
+    echo "  SKIP: $label non-executable check (filesystem does not differentiate permissions)"
+    return 0
+  fi
   if [ ! -x "$path" ]; then
     pass "$label is not executable (expected)"
   else

From bb37926d520227b6c62a9c4d881a2e2e31a01514 Mon Sep 17 00:00:00 2001
From: Devin Container Agent <devin-agent@container.local>
Date: Tue, 19 May 2026 08:49:22 +0000
Subject: [PATCH 3/4] =?UTF-8?q?fix:=20address=20review=20findings=20?=
 =?UTF-8?q?=E2=80=94=20security,=20docs,=20and=20test=20coverage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Security:
- Bind Docker inline examples to 127.0.0.1 (not 0.0.0.0) in playbook docs
- Bind Podman/PowerShell start scripts to 127.0.0.1 on all ports including 13133
- Add health_check extension to host and compose collector configs

Documentation:
- Add docker-compose -f flag pointing to docker-compose.yaml in all examples
- Move provenance comments inside YAML frontmatter block (fix HTML-before-frontmatter)
- Convert multi-line description: > to single-line description: "..." in all playbooks

Tests:
- Assert Claude wrappers contain unrestricted Bash and correct description/path
- Assert Copilot wrappers omit allowed-tools: field

PowerShell:
- Fix Wait-ForHealth to use -ErrorAction Stop instead of *>$null

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 playbooks/setup/create-local-otel-stack.md    | 28 +++++++++----------
 .../Start-LocalOtelStack.ps1                  | 13 +++++----
 .../otel-collector-config-compose.yaml        |  5 ++++
 .../otel-collector-config.yaml                |  5 ++++
 .../start-local-otel-stack.sh                 | 11 ++++----
 playbooks/setup/discover-local-otel-stack.md  |  8 ++----
 playbooks/setup/instrument-dotnet-otel.md     |  9 ++----
 playbooks/setup/use-local-otel-stack.md       |  8 ++----
 tests/test-deploy.sh                          | 10 ++++++-
 9 files changed, 51 insertions(+), 46 deletions(-)

diff --git a/playbooks/setup/create-local-otel-stack.md b/playbooks/setup/create-local-otel-stack.md
index 606ce7b..d68fbd5 100644
--- a/playbooks/setup/create-local-otel-stack.md
+++ b/playbooks/setup/create-local-otel-stack.md
@@ -1,11 +1,7 @@
-<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
 ---
 name: setup-create-local-otel-stack
-description: >
-  Use to create and start a local OpenTelemetry observability stack
-  (OTel Collector, VictoriaMetrics, VictoriaLogs, VictoriaTraces).
-  Only use this after running discover-local-otel-stack and confirming that no stack is currently running.
-  To send telemetry to a running stack, use use-local-otel-stack instead.
+# Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced.
+description: "Create and start a local OpenTelemetry observability stack (OTel Collector, VictoriaMetrics, VictoriaLogs, VictoriaTraces) for development and testing"
 keywords: [create otel stack, local otel, set up opentelemetry, local telemetry, opentelemetry local]
 ---
 
@@ -91,25 +87,25 @@ docker network create otel-stack
 
 # Start VictoriaMetrics
 docker run -d --network otel-stack --name victoriametrics \
-  -p 8428:8428 \
+  -p 127.0.0.1:8428:8428 \
   victoriametrics/victoria-metrics:v1.130.0 \
   --storageDataPath=/storage
 
 # Start VictoriaLogs
 docker run -d --network otel-stack --name victorialogs \
-  -p 9428:9428 \
+  -p 127.0.0.1:9428:9428 \
   victoriametrics/victoria-logs:v1.47.0 \
   --storageDataPath=/vlogs
 
 # Start VictoriaTraces
 docker run -d --network otel-stack --name victoriatraces \
-  -p 10428:10428 \
+  -p 127.0.0.1:10428:10428 \
   victoriametrics/victoria-traces:v0.7.1 \
   --storageDataPath=/vtraces --servicegraph.enableTask=true
 
 # Start OTel Collector (using compose config)
 docker run -d --network otel-stack --name otel-collector \
-  -p 4317:4317 -p 4318:4318 \
+  -p 127.0.0.1:4317:4317 -p 127.0.0.1:4318:4318 \
   -v ./otel-collector-config-compose.yaml:/etc/otel-collector-config.yml:ro \
   ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:0.133.0 \
   --config=/etc/otel-collector-config.yml
@@ -122,17 +118,19 @@ Uses service names for inter-container communication (e.g., `victoriametrics:842
 Image versions are read from `versions.env` via variable substitution. Pass `--env-file` so Docker Compose can resolve the `${IMAGE_*}` variables:
 
 ```bash
+COMPOSE=".context/playbooks/setup/create-local-otel-stack"
+
 # Start all services (versions read from versions.env)
-docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env up -d
+docker-compose -f "$COMPOSE/docker-compose.yaml" --env-file "$COMPOSE/versions.env" up -d
 
 # Stop all services
-docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env down
+docker-compose -f "$COMPOSE/docker-compose.yaml" --env-file "$COMPOSE/versions.env" down
 
 # View logs
-docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env logs -f
+docker-compose -f "$COMPOSE/docker-compose.yaml" --env-file "$COMPOSE/versions.env" logs -f
 
 # Restart specific service
-docker-compose --env-file .context/playbooks/setup/create-local-otel-stack/versions.env restart otel-collector
+docker-compose -f "$COMPOSE/docker-compose.yaml" --env-file "$COMPOSE/versions.env" restart otel-collector
 ```
 
 Automatically creates network; uses service names for communication.
@@ -294,7 +292,7 @@ If backends don't become healthy within 30 seconds:
 
 ## Version Updates
 
-`versions.env` is the single source of truth for image versions. The Bash and PowerShell start scripts source it directly. `docker-compose.yaml` references the same variables via `${IMAGE_*}` substitution (pass `--env-file versions.env` when running `docker-compose`).
+`versions.env` is the single source of truth for image versions. The Bash and PowerShell start scripts source it directly. `docker-compose.yaml` references the same variables via `${IMAGE_*}` substitution (pass `-f docker-compose.yaml --env-file versions.env` when running `docker-compose`).
 
 To update component versions:
 
diff --git a/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1 b/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
index 8698767..7f95a45 100644
--- a/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
+++ b/playbooks/setup/create-local-otel-stack/Start-LocalOtelStack.ps1
@@ -62,7 +62,7 @@ function Wait-ForHealth {
     $deadline = (Get-Date).AddSeconds($Timeout)
     while ((Get-Date) -lt $deadline) {
         try {
-            $response = Invoke-WebRequest -Uri $Url -TimeoutSec 2 -UseBasicParsing *>$null
+            $response = Invoke-WebRequest -Uri $Url -TimeoutSec 2 -UseBasicParsing -ErrorAction Stop
             if ($response.StatusCode -eq 200) {
                 Write-Host "  $Name is healthy"
                 return $true
@@ -94,11 +94,12 @@ function Start-Stack {
 
     Write-Host "Creating pod '$PodName'..."
     podman pod create --name $PodName `
-        -p 4317:4317 `
-        -p 4318:4318 `
-        -p 8428:8428 `
-        -p 9428:9428 `
-        -p 10428:10428
+        -p 127.0.0.1:4317:4317 `
+        -p 127.0.0.1:4318:4318 `
+        -p 127.0.0.1:8428:8428 `
+        -p 127.0.0.1:9428:9428 `
+        -p 127.0.0.1:10428:10428 `
+        -p 127.0.0.1:13133:13133
 
     if ($LASTEXITCODE -ne 0) {
         Write-Error "Failed to create pod"
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
index 40253f0..5cac820 100644
--- a/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
@@ -46,7 +46,12 @@ processors:
     timeout: 5s
     send_batch_size: 1024
 
+extensions:
+  health_check:
+    endpoint: "0.0.0.0:13133"
+
 service:
+  extensions: [health_check]
   pipelines:
     traces:
       receivers: [otlp]
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
index f2fcf26..b2fb4d7 100644
--- a/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
@@ -45,7 +45,12 @@ processors:
     timeout: 5s
     send_batch_size: 1024
 
+extensions:
+  health_check:
+    endpoint: "0.0.0.0:13133"
+
 service:
+  extensions: [health_check]
   pipelines:
     traces:
       receivers: [otlp]
diff --git a/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh b/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
index 581ac53..5818906 100755
--- a/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
+++ b/playbooks/setup/create-local-otel-stack/start-local-otel-stack.sh
@@ -98,11 +98,12 @@ start_stack() {
 
     echo "Creating pod '$POD_NAME'..."
     podman pod create --name "$POD_NAME" \
-        -p 4317:4317 \
-        -p 4318:4318 \
-        -p 8428:8428 \
-        -p 9428:9428 \
-        -p 10428:10428
+        -p 127.0.0.1:4317:4317 \
+        -p 127.0.0.1:4318:4318 \
+        -p 127.0.0.1:8428:8428 \
+        -p 127.0.0.1:9428:9428 \
+        -p 127.0.0.1:10428:10428 \
+        -p 127.0.0.1:13133:13133
 
     echo "Starting VictoriaMetrics..."
     # --opentelemetry.usePrometheusNaming was removed: VictoriaMetrics 1.100+
diff --git a/playbooks/setup/discover-local-otel-stack.md b/playbooks/setup/discover-local-otel-stack.md
index def21bb..fff31c5 100644
--- a/playbooks/setup/discover-local-otel-stack.md
+++ b/playbooks/setup/discover-local-otel-stack.md
@@ -1,11 +1,7 @@
-<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
 ---
 name: setup-discover-local-otel-stack
-description: >
-  Use to determine whether a local OpenTelemetry stack is already running on this machine.
-  Always run this before using create-local-otel-stack or use-local-otel-stack.
-  Returns whether each component (OTel Collector, VictoriaMetrics, VictoriaLogs, VictoriaTraces)
-  is healthy and what endpoints are available.
+# Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced.
+description: "Determine whether a local OpenTelemetry stack is already running and report component health and endpoints"
 keywords: [discover otel stack, find otel stack, otel stack running]
 ---
 
diff --git a/playbooks/setup/instrument-dotnet-otel.md b/playbooks/setup/instrument-dotnet-otel.md
index ec67d8d..cc17483 100644
--- a/playbooks/setup/instrument-dotnet-otel.md
+++ b/playbooks/setup/instrument-dotnet-otel.md
@@ -1,12 +1,7 @@
-<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
 ---
 name: setup-instrument-dotnet-otel
-description: >
-  Use when instrumenting a .NET application with the OpenTelemetry SDK for traces, metrics, and logs.
-  Covers SDK setup, OTLP export configuration, and three known pitfalls with the .NET OTLP exporter:
-  explicit endpoint breaking signal path appending, gRPC unreachable via host.containers.internal,
-  and ActivityListener test isolation failures. Use use-local-otel-stack to send telemetry to a local
-  stack for testing.
+# Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced.
+description: "Instrument a .NET application with the OpenTelemetry SDK for traces, metrics, and logs, including OTLP export configuration and known pitfalls"
 keywords: [instrument dotnet, dotnet otel, opentelemetry dotnet, dotnet sdk otel]
 ---
 
diff --git a/playbooks/setup/use-local-otel-stack.md b/playbooks/setup/use-local-otel-stack.md
index 77914d2..9984f7e 100644
--- a/playbooks/setup/use-local-otel-stack.md
+++ b/playbooks/setup/use-local-otel-stack.md
@@ -1,11 +1,7 @@
-<!-- Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced. -->
 ---
 name: setup-use-local-otel-stack
-description: >
-  Use when you need to send OpenTelemetry telemetry to a local stack, or query it
-  for metrics, logs, or traces during development or testing.
-  Run discover-local-otel-stack first to confirm the stack is available.
-  Do not use this skill when you need to access real production telemetry.
+# Ported from devopsin@9fa20ff0 (feature/split-telemetry-skills) — not automatically synced.
+description: "Send OpenTelemetry telemetry to a local stack or query it for metrics, logs, and traces during development or testing"
 keywords: [use otel stack, connect otel, send telemetry, otlp endpoint]
 ---
 
diff --git a/tests/test-deploy.sh b/tests/test-deploy.sh
index d0cb7cc..8c0552f 100644
--- a/tests/test-deploy.sh
+++ b/tests/test-deploy.sh
@@ -162,9 +162,17 @@ assert_file_exists "copilot/setup-discover-local-otel-stack" "$TC1_DIR/.github/s
 assert_file_exists "copilot/setup-use-local-otel-stack" "$TC1_DIR/.github/skills/setup-use-local-otel-stack/SKILL.md"
 assert_file_exists "copilot/setup-instrument-dotnet-otel" "$TC1_DIR/.github/skills/setup-instrument-dotnet-otel/SKILL.md"
 
-echo "  --- allowed-tools check ---"
+echo "  --- Wrapper content checks ---"
 assert_contains "claude wrapper allowed-tools" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" "allowed-tools:"
 assert_not_contains "claude wrapper no git-only bash" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" "Bash(git *)"
+assert_contains "claude wrapper unrestricted bash" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" "Bash,"
+assert_contains "claude wrapper has description" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" 'description: "Create and start a local OpenTelemetry'
+assert_contains "claude wrapper has playbook path" "$TC1_DIR/.claude/skills/setup-create-local-otel-stack/SKILL.md" ".context/playbooks/setup/create-local-otel-stack.md"
+
+echo "  --- Copilot wrappers omit allowed-tools ---"
+assert_not_contains "copilot wrapper no allowed-tools" "$TC1_DIR/.github/skills/setup-create-local-otel-stack/SKILL.md" "allowed-tools:"
+assert_contains "copilot wrapper has description" "$TC1_DIR/.github/skills/setup-create-local-otel-stack/SKILL.md" 'description: "Create and start a local OpenTelemetry'
+assert_contains "copilot wrapper has playbook path" "$TC1_DIR/.github/skills/setup-create-local-otel-stack/SKILL.md" ".context/playbooks/setup/create-local-otel-stack.md"
 
 echo "  --- Safety and provenance ---"
 assert_contains "local-dev-only warning" "$TC1_DIR/.context/playbooks/setup/create-local-otel-stack.md" "Local development and testing only"

From 8391e3f619e22e54034cfa4402637bc6f4d15a01 Mon Sep 17 00:00:00 2001
From: Daniel Nicholls <daniel.nicholls@theaccessgroup.com>
Date: Wed, 8 Jul 2026 12:36:48 +0100
Subject: [PATCH 4/4] fix: address Copilot review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- validate-config.sh: remove source of versions.env (arbitrary code
  execution risk in CI); the variables were unused — validation only
  reads the file as text
- validate-config.sh: use grep -F -- for fixed-string matching in
  assert_contains to avoid false positives from regex metacharacters
  (e.g. 127.0.0.1 dot-matching any char)
- deploy.sh: wrap docs/ and setup/ skill-generation loops in
  directory-existence guards, matching the PowerShell Test-Path
  behaviour and preventing set -e failures on empty/missing dirs
- tests/test-deploy.sh TC5: replace fixed /tmp/tc5_*.txt paths with
  mktemp files to avoid concurrent-run collisions; use find -exec
  sha256sum {} + to handle filenames with whitespace
- otel-collector-config.yaml, otel-collector-config-compose.yaml:
  restrict CORS allowed_origins to localhost only
  (http://localhost:* and http://127.0.0.1:*) to prevent arbitrary
  websites from posting telemetry to the local collector

Generated with [Devin](https://cli.devin.ai/docs)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
---
 deploy.sh                                     | 24 ++++++++++++-------
 .../otel-collector-config-compose.yaml        |  2 +-
 .../otel-collector-config.yaml                |  2 +-
 .../validate-config.sh                        |  8 ++-----
 tests/test-deploy.sh                          | 22 ++++++++++-------
 5 files changed, 32 insertions(+), 26 deletions(-)

diff --git a/deploy.sh b/deploy.sh
index c8605af..7e12f3b 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -606,16 +606,22 @@ if agent_enabled claude || agent_enabled copilot; then
     generate_skills_for_selected_agents "$playbook" "refactor/$filename"
   done
 
-  for playbook in "$SCRIPT_DIR"/playbooks/docs/*.md; do
-    filename=$(basename "$playbook")
-    generate_skills_for_selected_agents "$playbook" "docs/$filename"
-  done
+  if [[ -d "$SCRIPT_DIR/playbooks/docs" ]]; then
+    for playbook in "$SCRIPT_DIR"/playbooks/docs/*.md; do
+      [[ -f "$playbook" ]] || continue
+      filename=$(basename "$playbook")
+      generate_skills_for_selected_agents "$playbook" "docs/$filename"
+    done
+  fi
 
-  for playbook in "$SCRIPT_DIR"/playbooks/setup/*.md; do
-    filename=$(basename "$playbook")
-    generate_skills_for_selected_agents "$playbook" "setup/$filename" \
-      "Read, Grep, Glob, Bash, Write, Edit, Agent"
-  done
+  if [[ -d "$SCRIPT_DIR/playbooks/setup" ]]; then
+    for playbook in "$SCRIPT_DIR"/playbooks/setup/*.md; do
+      [[ -f "$playbook" ]] || continue
+      filename=$(basename "$playbook")
+      generate_skills_for_selected_agents "$playbook" "setup/$filename" \
+        "Read, Grep, Glob, Bash, Write, Edit, Agent"
+    done
+  fi
 else
   echo "  Skipping skill wrapper generation (no selected agent uses skills)."
 fi
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
index 5cac820..808db83 100644
--- a/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config-compose.yaml
@@ -12,7 +12,7 @@ receivers:
       http:
         endpoint: "0.0.0.0:4318"
         cors:
-          allowed_origins: ["http://*", "https://*"]
+          allowed_origins: ["http://localhost:*", "http://127.0.0.1:*"]
       grpc:
         endpoint: "0.0.0.0:4317"
   hostmetrics:
diff --git a/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
index b2fb4d7..17b0c07 100644
--- a/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
+++ b/playbooks/setup/create-local-otel-stack/otel-collector-config.yaml
@@ -11,7 +11,7 @@ receivers:
       http:
         endpoint: "0.0.0.0:4318"
         cors:
-          allowed_origins: ["http://*", "https://*"]
+          allowed_origins: ["http://localhost:*", "http://127.0.0.1:*"]
       grpc:
         endpoint: "0.0.0.0:4317"
   hostmetrics:
diff --git a/playbooks/setup/create-local-otel-stack/validate-config.sh b/playbooks/setup/create-local-otel-stack/validate-config.sh
index 4b9ee28..fd98646 100755
--- a/playbooks/setup/create-local-otel-stack/validate-config.sh
+++ b/playbooks/setup/create-local-otel-stack/validate-config.sh
@@ -11,10 +11,6 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 
-# Image versions — single source of truth
-# shellcheck source=versions.env
-source "$SCRIPT_DIR/versions.env"
-
 PASSED=0
 FAILED=0
 
@@ -97,7 +93,7 @@ assert_contains() {
     local file_path="$2"
     local expected="$3"
     
-    if grep -q "$expected" "$file_path"; then
+    if grep -qF -- "$expected" "$file_path"; then
         echo "  PASS: $test_name - contains '$expected'"
         PASSED=$((PASSED + 1))
         return 0
@@ -153,7 +149,7 @@ assert_contains "Image versions defined" "$SCRIPT_DIR/versions.env" "IMAGE_OTEL=
 echo ""
 echo "=== Checking docker-compose.yaml version variable substitution ==="
 for var in IMAGE_OTEL IMAGE_VM IMAGE_VL IMAGE_VT; do
-    if grep -q "\${${var}}" "$SCRIPT_DIR/docker-compose.yaml"; then
+    if grep -qF -- "\${${var}}" "$SCRIPT_DIR/docker-compose.yaml"; then
         echo "  PASS: docker-compose.yaml references \${${var}}"
         PASSED=$((PASSED + 1))
     else
diff --git a/tests/test-deploy.sh b/tests/test-deploy.sh
index 8c0552f..67a4579 100644
--- a/tests/test-deploy.sh
+++ b/tests/test-deploy.sh
@@ -238,30 +238,34 @@ rm -rf "$TC4_DIR"
 echo ""
 echo "=== TC5: Idempotency ==="
 TC5_DIR=$(mktemp -d)
+TC5_CHECKSUMS1=$(mktemp)
+TC5_CHECKSUMS2=$(mktemp)
+TC5_PERMS1=$(mktemp)
+TC5_PERMS2=$(mktemp)
 
 "$REPO_DIR/deploy.sh" --agents all --overwrite "$TC5_DIR" >/dev/null 2>&1
-find "$TC5_DIR" -type f | sort | xargs sha256sum > /tmp/tc5_run1.txt
-find "$TC5_DIR" -type f -perm /111 | sort > /tmp/tc5_perms1.txt
+find "$TC5_DIR" -type f -exec sha256sum {} + | sort > "$TC5_CHECKSUMS1"
+find "$TC5_DIR" -type f -perm /111 | sort > "$TC5_PERMS1"
 
 "$REPO_DIR/deploy.sh" --agents all --overwrite "$TC5_DIR" >/dev/null 2>&1
-find "$TC5_DIR" -type f | sort | xargs sha256sum > /tmp/tc5_run2.txt
-find "$TC5_DIR" -type f -perm /111 | sort > /tmp/tc5_perms2.txt
+find "$TC5_DIR" -type f -exec sha256sum {} + | sort > "$TC5_CHECKSUMS2"
+find "$TC5_DIR" -type f -perm /111 | sort > "$TC5_PERMS2"
 
-if diff -q /tmp/tc5_run1.txt /tmp/tc5_run2.txt >/dev/null 2>&1; then
+if diff -q "$TC5_CHECKSUMS1" "$TC5_CHECKSUMS2" >/dev/null 2>&1; then
   pass "File checksums identical across both runs"
 else
   fail "File checksums differ between runs"
-  diff /tmp/tc5_run1.txt /tmp/tc5_run2.txt || true
+  diff "$TC5_CHECKSUMS1" "$TC5_CHECKSUMS2" || true
 fi
 
-if diff -q /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt >/dev/null 2>&1; then
+if diff -q "$TC5_PERMS1" "$TC5_PERMS2" >/dev/null 2>&1; then
   pass "Executable permissions identical across both runs"
 else
   fail "Executable permissions differ between runs"
-  diff /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt || true
+  diff "$TC5_PERMS1" "$TC5_PERMS2" || true
 fi
 
-rm -rf "$TC5_DIR" /tmp/tc5_run1.txt /tmp/tc5_run2.txt /tmp/tc5_perms1.txt /tmp/tc5_perms2.txt
+rm -rf "$TC5_DIR" "$TC5_CHECKSUMS1" "$TC5_CHECKSUMS2" "$TC5_PERMS1" "$TC5_PERMS2"
 
 # ═══════════════════════════════════════════════════════════════════════
 # TC6: validate-config passes — deployed copy