feat: improve config validation, add AGENTS.md guidelines

- Use nameref arrays for safer error handling in config helpers
- Add AGENTS.md with structure, coding, and security guidelines
- Streamline atl binary install in Dockerfile
- Add TOCTOU note in config loader

Author: lroolle

AGENTS.md

@@ -0,0 +1,42 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Root CLI: `claude.sh` (main wrapper), `claude-yolo` (YOLO alias).
+- Container: `Dockerfile`, `Makefile` for build/test tasks.
+- CI/CD: `.github/workflows/*` (CI, release, Claude bot).
+- Scripts: `scripts/version-check.sh` (version consistency).
+- Docs & examples: `README.md`, `CHANGELOG.md`, `workflows/`, `examples/`.
+- Config: project `.claude-yolo` and `.claude-yolo.local` (gitignored); user config under `~/.config/claude-yolo/`.
+
+## Build, Test, and Development Commands
+- `make build`: Build Docker image (`CLAUDE_CODE_VERSION` overridable).
+- `make rebuild|buildx|buildx-multi`: Rebuild (no cache) or multi‑arch.
+- `make test`: Smoke tests (CLI help/version, toolchain check).
+- `make lint`: Lint `Dockerfile` (hadolint).
+- `make version-check`: Ensure `claude.sh`, tags, and `CHANGELOG.md` align.
+- Run locally: `./claude.sh --yolo` or `./claude-yolo` in your project dir.
+
+## Coding Style & Naming Conventions
+- Language: Bash. Start scripts with `#!/bin/bash` and `set -e` (consider `-u -o pipefail` when safe).
+- Security: validate inputs; avoid backticks/eval; reject path traversal; prefer read‑only mounts.
+- Naming: scripts `*.sh`; CLI helpers kebab‑case; constants `ALL_CAPS`, vars/functions `snake_case`.
+- Output: short, clear; mask secrets (follow `mask_sensitive_value`).
+
+## Testing Guidelines
+- Linting: CI runs ShellCheck. Locally run ShellCheck if installed.
+- CI: GitHub Actions runs help/version checks and version consistency.
+- Local: `make test` before PR; keep tests minimal and behavior‑focused.
+- Versioning: update `VERSION` in `claude.sh` and `CHANGELOG.md`; run `scripts/version-check.sh`.
+
+## Commit & Pull Request Guidelines
+- Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:` (see `git log`).
+- PRs: clear description, linked issues, rationale for security‑sensitive changes, `make test` output.
+- Docs: update README/CHANGELOG when user‑visible behavior or flags change.
+- Releases: use tags (`vX.Y.Z`) and the release workflow; multi‑arch images are pushed from CI.
+
+## Security & Configuration Tips
+- Never run YOLO in `$HOME` or system dirs; always `cd` into a project.
+- Validate `-v` mounts; avoid `..` traversal; keep secrets read‑only.
+- Prefer project config: `.claude-yolo`; sensitive overrides in `.claude-yolo.local`.
+- Auth via env when needed: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `GH_TOKEN`.
+

Dockerfile

@@ -144,8 +144,8 @@ RUN npm config set prefix "$CLAUDE_HOME/.npm-global" && \
     npm cache clean --force
 
 # Install Go tools for Atlassian integration (Confluence/Jira/Bitbucket)
-# Build as claude user; move binary as root later (avoid sudo in build)
-RUN go install github.com/lroolle/atlas-cli/cmd/atl@main
+RUN go install github.com/lroolle/atlas-cli/cmd/atl@main && \
+    sudo mv $HOME/go/bin/atl /usr/local/bin/
 
 RUN git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh "$CLAUDE_HOME/.oh-my-zsh" && \
     git clone --depth=1 https://github.com/zsh-users/zsh-autosuggestions "$CLAUDE_HOME/.oh-my-zsh/custom/plugins/zsh-autosuggestions" && \
@@ -160,9 +160,6 @@ RUN echo 'export ZSH="$HOME/.oh-my-zsh"' > "$CLAUDE_HOME/.zshrc" && \
 
 USER root
 
-# Move atl into PATH as root (after building as claude)
-RUN test -f /home/claude/go/bin/atl && mv /home/claude/go/bin/atl /usr/local/bin/atl || true
-
 COPY docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
 
 RUN chmod +x /usr/local/bin/docker-entrypoint.sh && \

claude.sh

@@ -356,11 +356,12 @@ validate_config_value() {
 process_volume_config() {
     local value="$1"
     local errors_var="$2"
+    declare -n errors_ref="$errors_var"
 
     value="${value//\"/}"
 
     if ! validate_config_value "VOLUME" "$value"; then
-        eval "$errors_var+=(\"Invalid volume: \$value\")"
+        errors_ref+=("Invalid volume: $value")
         return 1
     fi
 
@@ -372,18 +373,19 @@ process_volume_config() {
         EXTRA_VOLUMES+=("-v" "$value")
         DOCKER_ONLY_WARNINGS+=("Config volume mount: $value (ignored in local mode)")
     else
-        eval "$errors_var+=(\"Volume validation failed: \$value\")"
+        errors_ref+=("Volume validation failed: $value")
     fi
 }
 
 process_env_config() {
     local value="$1"
     local errors_var="$2"
+    declare -n errors_ref="$errors_var"
 
     value="${value//\"/}"
 
     if ! validate_config_value "ENV" "$value"; then
-        eval "$errors_var+=(\"Invalid env: \$value\")"
+        errors_ref+=("Invalid env: $value")
         return 1
     fi
 
@@ -394,8 +396,7 @@ process_env_config() {
             EXTRA_ENV_VARS+=("-e" "$name=$val")
             DOCKER_ONLY_WARNINGS+=("Config environment variable: $name=$val (ignored in local mode)")
         else
-            eval "$errors_var+=(\"Invalid env name: \$name\")"
-        fi
+            errors_ref+=("Invalid env name: $name")
     else
         # Shorthand pass-through: ENV=${VAR} or ENV=$VAR
         if [[ "$value" =~ ^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$ ]] || [[ "$value" =~ ^\$([A-Za-z_][A-Za-z0-9_]*)$ ]]; then
@@ -417,16 +418,17 @@ process_var_config() {
     local name="$1"
     local value="$2"
     local errors_var="$3"
+    declare -n errors_ref="$errors_var"
 
     if ! [[ "$name" =~ ^[A-Z][A-Z0-9_]*$ ]]; then
-        eval "$errors_var+=(\"Invalid variable name: \$name\")"
+        errors_ref+=("Invalid variable name: $name")
         return 1
     fi
 
     value="${value//\"/}"
 
     if ! validate_config_value "$name" "$value"; then
-        eval "$errors_var+=(\"Validation failed for \$name=\$value\")"
+        errors_ref+=("Validation failed for $name=$value")
         return 1
     fi
 
@@ -439,14 +441,14 @@ process_var_config() {
         CONFIG_DIR="$value"
         if [ ! -d "$CONFIG_DIR" ]; then
             mkdir -p "$CONFIG_DIR" 2>/dev/null || {
-                eval "$errors_var+=(\"Cannot create CONFIG_DIR: \$CONFIG_DIR\")"
+                errors_ref+=("Cannot create CONFIG_DIR: $CONFIG_DIR")
                 CONFIG_DIR=""
                 return 1
             }
         fi
         if [ -n "$CONFIG_DIR" ] && [ ! -f "$CONFIG_DIR/.claude.json" ]; then
             echo '{}' >"$CONFIG_DIR/.claude.json" 2>/dev/null || {
-                eval "$errors_var+=(\"Cannot create \$CONFIG_DIR/.claude.json\")"
+                errors_ref+=("Cannot create $CONFIG_DIR/.claude.json")
             }
         fi
         ;;
@@ -479,7 +481,7 @@ process_var_config() {
         if [[ "$name" =~ ^(DISABLE_|MAX_|ANTHROPIC_|CLAUDE_|AWS_|GOOGLE_) ]]; then
             export "$name"="$value"
         else
-            eval "$errors_var+=(\"Unknown config variable: \$name\")"
+            errors_ref+=("Unknown config variable: $name")
         fi
         ;;
     esac
@@ -489,6 +491,11 @@ load_config_file() {
     local config_file="$1"
     [ -f "$config_file" ] || return 1
 
+    # Note: There's a potential TOCTOU race condition here where the config file
+    # could be modified between validation and loading. For a fully atomic solution,
+    # we would need to read the file once into memory and process from there.
+    # However, given the nature of config files (user-controlled, local),
+    # the security impact is minimal and the current approach is pragmatic.
     local errors=()
 
     while IFS= read -r line || [ -n "$line" ]; do