From c7af02f7c2a474f05c2a05a35cfa1828857b6c8e Mon Sep 17 00:00:00 2001
From: Julian Pawlowski <jpawlowski@users.noreply.github.com>
Date: Sat, 11 Apr 2026 15:17:20 +0000
Subject: [PATCH] feat(devcontainer): add common CLI tools and setup symlinks
 for compatibility

---
 .devcontainer/devcontainer.json | 13 ++++++++++++-
 AGENTS.md                       |  6 ++++++
 scripts/setup/setup             | 18 ++++++++++++++++++
 3 files changed, 36 insertions(+), 1 deletion(-)

diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index a8b0be1..1b1b5ec 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -136,9 +136,20 @@
         },
         "ghcr.io/devcontainers-extra/features/apt-packages:1": {
             "packages": [
+                "bat",
+                "eza",
+                "fd-find",
                 "ffmpeg",
+                "fzf",
+                "git-delta",
+                "hyperfine",
+                "httpie",
+                "ipython3",
+                "jq",
                 "libturbojpeg0",
-                "libpcap-dev"
+                "libpcap-dev",
+                "ripgrep",
+                "yq"
             ]
         }
     }
diff --git a/AGENTS.md b/AGENTS.md
index d69fa7b..a3c301b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -783,6 +783,12 @@ When debugging period calculation issues:
 -   **git-cliff**: Template-based release notes (fast, reliable, installed via cargo in `scripts/setup/setup`)
 -   Manual grep/awk parsing as fallback (always available)
 
+**Agent Productivity CLI Tools (DevContainer):**
+
+-   Expected available tools: `rg`, `fd`, `fzf`, `jq`, `yq`, `bat`, `eza`, `delta`, `hyperfine`, `ipython`, `http`
+-   Debian package notes: `fd-find` provides `fdfind`, `bat` may be `batcat`
+-   Setup creates compatibility symlinks for `fd` and `bat` in `scripts/setup/setup`
+
 **When generating shell commands:**
 
 1. **Prefer development scripts** (they handle .venv automatically)
diff --git a/scripts/setup/setup b/scripts/setup/setup
index a5599e0..b800573 100755
--- a/scripts/setup/setup
+++ b/scripts/setup/setup
@@ -47,6 +47,24 @@ fi
 
 "$SCRIPT_DIR/bootstrap"
 
+# Setup Debian compatibility symlinks for common CLI tool names.
+mkdir -p "$HOME/.local/bin"
+
+# Debian package fd-find provides `fdfind`, but most workflows expect `fd`.
+if command -v fdfind >/dev/null 2>&1; then
+    ln -sf "$(command -v fdfind)" "$HOME/.local/bin/fd"
+fi
+
+# Debian package bat provides `batcat`, but most workflows expect `bat`.
+if command -v batcat >/dev/null 2>&1; then
+    ln -sf "$(command -v batcat)" "$HOME/.local/bin/bat"
+fi
+
+# Ensure user-local bin directory is available in interactive shells.
+if ! grep -q '\$HOME/.local/bin' "$HOME/.zshrc" 2>/dev/null; then
+    printf '\n# Added by scripts/setup/setup\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.zshrc"
+fi
+
 # Install HACS for testing with other custom components
 echo ""
 log_header "Installing HACS in dev environment"