Release v2.1.x: Penguin-DAL migration, centralized libs, and test suite overhaul

.claude/.claude/README.md

@@ -0,0 +1,60 @@
+# Claude Context Files
+
+This directory contains focused standards files for Claude Code to reference when working on specific parts of the codebase.
+
+## 🚫 DO NOT MODIFY EXISTING FILES
+
+**These are centralized template standards that will be overwritten when updated.**
+
+Files you must **NEVER modify**:
+- `go.md`, `python.md`, `react.md` (language standards)
+- `flask-backend.md`, `go-backend.md`, `webui.md` (service standards)
+- `database.md`, `security.md`, `testing.md`, `containers.md`, `kubernetes.md` (domain standards)
+- `README.md` (this file)
+
+**Instead, CREATE NEW FILES for app-specific context:**
+- `.claude/app.md` - App-specific rules and context
+- `.claude/[feature].md` - Feature-specific context (e.g., `billing.md`, `notifications.md`)
+- `docs/APP_STANDARDS.md` - Human-readable app-specific documentation
+
+---
+
+## ⚠️ CRITICAL RULES
+
+Every file in this directory starts with a "CRITICAL RULES" section. Claude should read and follow these rules strictly.
+
+## File Index
+
+### Language Standards
+| File | When to Read |
+|------|--------------|
+| `go.md` | Working on Go code (*.go files) |
+| `python.md` | Working on Python code (*.py files) |
+| `react.md` | Working on React/frontend code (*.jsx, *.tsx files) |
+
+### Service Standards
+| File | When to Read |
+|------|--------------|
+| `flask-backend.md` | Working on Flask backend service |
+| `go-backend.md` | Working on Go backend service |
+| `webui.md` | Working on WebUI/React service |
+
+### Domain Standards
+| File | When to Read |
+|------|--------------|
+| `database.md` | Any database operations (PyDAL, SQLAlchemy, GORM) |
+| `security.md` | Authentication, authorization, security scanning |
+| `testing.md` | Running tests, beta infrastructure, smoke tests |
+| `containers.md` | Docker images, Dockerfiles, container configuration |
+| `kubernetes.md` | K8s deployments, Helm v3 charts, Kustomize overlays |
+
+## Usage
+
+Claude should:
+1. Read the main `CLAUDE.md` for project overview and critical rules
+2. Read relevant `.claude/*.md` files based on the task at hand
+3. Follow the CRITICAL RULES sections strictly - these are non-negotiable
+
+## File Size Limit
+
+All files in this directory should be under 5000 characters to ensure Claude can process them effectively.

.claude/.claude/app.md

@@ -0,0 +1,27 @@
+# App-Specific Context
+
+> ✅ **This file IS safe to modify.** Add your app-specific rules, context, and requirements here.
+
+## About This App
+
+<!-- Describe what this application does -->
+
+## App-Specific Rules
+
+<!-- Add rules specific to this application that Claude should follow -->
+
+## Key Files & Locations
+
+<!-- List important files Claude should know about -->
+
+## Domain-Specific Terms
+
+<!-- Define any domain terminology Claude should understand -->
+
+## Integration Notes
+
+<!-- Any app-specific integration details -->
+
+---
+
+*This file is for app-specific context. Do not add general standards here - those belong in the template files.*

.claude/.claude/containers.md

@@ -0,0 +1,114 @@
+# Container Image Standards
+
+## ⚠️ CRITICAL RULES
+
+1. **Debian 12 (bookworm) ONLY** - all container images must use Debian-based images
+2. **NEVER use Alpine** - causes glibc/musl compatibility issues, missing packages, debugging difficulties
+3. **Use `-slim` variants** when available for smaller image sizes
+4. **PostgreSQL 16.x** standard for all database containers
+5. **Multi-arch builds required** - support both amd64 and arm64
+
+---
+
+## Base Image Selection
+
+### Priority Order (MUST follow)
+
+1. **Debian 12 (bookworm)** - PRIMARY, always use if available
+2. **Debian 11 (bullseye)** - fallback if bookworm unavailable
+3. **Debian 13 (trixie)** - fallback for newer packages
+4. **Ubuntu LTS** - ONLY if no Debian option exists
+5. ❌ **NEVER Alpine** - forbidden, causes too many issues
+
+---
+
+## Standard Images
+
+| Service | Image | Notes |
+|---------|-------|-------|
+| PostgreSQL | `postgres:16-bookworm` | Primary database |
+| MySQL | `mysql:8.0-debian` | Alternative database |
+| Redis | `redis:7-bookworm` | Cache/session store |
+| Python | `python:3.13-slim-bookworm` | Flask backend |
+| Node.js | `node:18-bookworm-slim` | WebUI build |
+| Nginx | `nginx:stable-bookworm-slim` | Reverse proxy |
+| Go | `golang:1.24-bookworm` | Build stage only |
+| Runtime | `debian:bookworm-slim` | Go runtime stage |
+
+---
+
+## Dockerfile Patterns
+
+### Python Service
+```dockerfile
+FROM python:3.13-slim-bookworm AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+
+FROM python:3.13-slim-bookworm
+WORKDIR /app
+COPY --from=builder /app /app
+CMD ["gunicorn", "-b", "0.0.0.0:8080", "app:app"]
+```
+
+### Go Service
+```dockerfile
+FROM golang:1.24-bookworm AS builder
+WORKDIR /app
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -o /app/server
+
+FROM debian:bookworm-slim
+COPY --from=builder /app/server /server
+CMD ["/server"]
+```
+
+### Node.js/React Service
+```dockerfile
+FROM node:18-bookworm-slim AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:stable-bookworm-slim
+COPY --from=builder /app/dist /usr/share/nginx/html
+```
+
+---
+
+## Why Not Alpine?
+
+❌ **glibc vs musl** - Many Python packages require glibc, Alpine uses musl
+❌ **Missing packages** - Common tools often unavailable or different versions
+❌ **Debugging harder** - No bash by default, limited tooling
+❌ **DNS issues** - Known DNS resolution problems in some scenarios
+❌ **Build failures** - C extensions often fail to compile
+
+✅ **Debian-slim** - Only ~30MB larger than Alpine but zero compatibility issues
+
+---
+
+## Docker Compose Example
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-bookworm
+
+  redis:
+    image: redis:7-bookworm
+
+  api:
+    build:
+      context: ./services/flask-backend
+    # Uses python:3.13-slim-bookworm internally
+
+  web:
+    image: nginx:stable-bookworm-slim
+```