From 6b72618cbb3d01ec27c935a6c37f934bea56175b Mon Sep 17 00:00:00 2001
From: Serge Gatezh <2880401+gatezh@users.noreply.github.com>
Date: Sat, 7 Feb 2026 18:58:16 -0700
Subject: [PATCH] fix: use GNU sed for Linux + add AI agent best practices to
 AGENTS.md

---
 .../workflows/update-and-build-ralphex-fe.yml | 11 +++---
 AGENTS.md                                     | 36 +++++++++++++++++++
 2 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/update-and-build-ralphex-fe.yml b/.github/workflows/update-and-build-ralphex-fe.yml
index 55cb6df..aac8a13 100644
--- a/.github/workflows/update-and-build-ralphex-fe.yml
+++ b/.github/workflows/update-and-build-ralphex-fe.yml
@@ -58,14 +58,11 @@ jobs:
           echo "  Bun: $INPUT_BUN_VERSION"
           echo "  Hugo: $INPUT_HUGO_VERSION"
 
-          # Update Bun version
-          sed -i.bak "s/^ARG BUN_VERSION=.*/ARG BUN_VERSION=$INPUT_BUN_VERSION/" "${{ env.DOCKERFILE_PATH }}"
+          # Update Bun version (GNU sed syntax for Linux)
+          sed -i "s/^ARG BUN_VERSION=.*/ARG BUN_VERSION=$INPUT_BUN_VERSION/" "${{ env.DOCKERFILE_PATH }}"
 
-          # Update Hugo version
-          sed -i.bak "s/^ARG HUGO_VERSION=.*/ARG HUGO_VERSION=$INPUT_HUGO_VERSION/" "${{ env.DOCKERFILE_PATH }}"
-
-          # Clean up backup file
-          rm -f "${{ env.DOCKERFILE_PATH }}.bak"
+          # Update Hugo version (GNU sed syntax for Linux)
+          sed -i "s/^ARG HUGO_VERSION=.*/ARG HUGO_VERSION=$INPUT_HUGO_VERSION/" "${{ env.DOCKERFILE_PATH }}"
 
           # Verify changes
           echo ""
diff --git a/AGENTS.md b/AGENTS.md
index 79d47fc..b2dd446 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,6 +6,42 @@ This document defines patterns, conventions, and guidelines for AI agents workin
 
 This repository contains Dockerfiles for custom devcontainer images hosted on GitHub Container Registry (ghcr.io). Each image is designed for VS Code Dev Containers with specific development environments.
 
+## AI Agent Best Practices
+
+### Always Verify with Official Documentation
+
+When implementing features or making changes, **ALWAYS** check the latest official documentation:
+
+- **GitHub Actions**: https://docs.github.com/en/actions
+  - Runs on Ubuntu (GNU/Linux) - use GNU coreutils syntax, NOT macOS/BSD syntax
+  - Example: `sed -i "pattern" file` (GNU) NOT `sed -i.bak "pattern" file` (BSD)
+  - Check platform-specific tool behavior (sed, grep, awk, etc.)
+  - Verify workflow syntax with official examples
+
+- **Docker/Dockerfile**: https://docs.docker.com/reference/dockerfile/
+  - Multi-platform builds use `TARGETARCH` (amd64, arm64)
+  - Verify base image availability and compatibility
+
+- **Tools and Dependencies**:
+  - Bun: https://bun.sh/docs
+  - Hugo: https://gohugo.io/documentation/
+  - GitHub CLI: https://cli.github.com/manual/
+  - Always verify command syntax from official docs, not assumptions
+
+### Platform Awareness
+
+- **GitHub Actions runners**: Ubuntu Linux (use GNU tools)
+- **Docker builds**: Multi-platform (linux/amd64, linux/arm64)
+- **Base images**: Check Alpine vs Debian (apk vs apt, musl vs glibc)
+- **Scripts**: Test for portability (sh vs bash, GNU vs BSD tools)
+
+### Validation Before Committing
+
+- YAML syntax validation for workflows
+- Dockerfile syntax validation
+- Test on target platform (not just local macOS/Windows)
+- Verify assumptions about available tools and their versions
+
 ## Directory Structure
 
 ```