Merge error handling improvements and development setup from claude/add-error-handling branch

.devcontainer/Dockerfile

@@ -0,0 +1,45 @@
+# OrcPub Development Container
+# Requires: Java 8, Leiningen, Node.js (for ClojureScript tooling)
+
+FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04
+
+# Avoid prompts during package installation
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install OpenJDK 8 and other dependencies
+RUN apt-get update && apt-get install -y \
+    openjdk-8-jdk \
+    openjdk-8-jdk-headless \
+    curl \
+    wget \
+    unzip \
+    git \
+    rlwrap \
+    nodejs \
+    npm \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set Java 8 as default
+ENV JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
+ENV PATH="${JAVA_HOME}/bin:${PATH}"
+
+# Verify Java version
+RUN java -version
+
+# Install Leiningen
+RUN mkdir -p /usr/local/bin \
+    && curl -fsSL https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein -o /usr/local/bin/lein \
+    && chmod +x /usr/local/bin/lein
+
+# Pre-fetch leiningen dependencies as root (will be cached)
+RUN lein --version
+
+# Create workspace directory
+WORKDIR /workspaces/orcpub
+
+# Switch to vscode user for development
+USER vscode
+
+# Ensure lein works for vscode user (will download to user home)
+RUN lein --version

.devcontainer/devcontainer.json

@@ -0,0 +1,62 @@
+{
+  "name": "OrcPub Development",
+  "build": {
+    "dockerfile": "Dockerfile",
+    "context": ".."
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "installZsh": true,
+      "configureZshAsDefaultShell": true,
+      "installOhMyZsh": true,
+      "upgradePackages": true
+    },
+    "ghcr.io/devcontainers/features/git:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "betterthantomorrow.calva",
+        "betterthantomorrow.calva-spritz",
+        "vscjava.vscode-java-pack",
+        "redhat.java"
+      ],
+      "settings": {
+        "java.configuration.runtimes": [
+          {
+            "name": "JavaSE-1.8",
+            "path": "/usr/lib/jvm/java-8-openjdk-amd64",
+            "default": true
+          }
+        ],
+        "calva.replConnectSequences": [
+          {
+            "name": "OrcPub Server",
+            "projectType": "Leiningen",
+            "cljsType": "Figwheel Main",
+            "menuSelections": {
+              "leinProfiles": ["dev"]
+            }
+          }
+        ]
+      }
+    }
+  },
+  "forwardPorts": [4334, 3000, 8080],
+  "portsAttributes": {
+    "4334": {
+      "label": "Datomic Transactor",
+      "onAutoForward": "silent"
+    },
+    "3000": {
+      "label": "ClojureScript Dev Server",
+      "onAutoForward": "notify"
+    },
+    "8080": {
+      "label": "OrcPub Server",
+      "onAutoForward": "openBrowser"
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "remoteUser": "vscode"
+}

.devcontainer/post-create.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "=== OrcPub Development Container Setup ==="
+
+# Verify Java 8
+echo "Checking Java version..."
+java -version 2>&1 | head -2
+JAVA_VER=$(java -version 2>&1 | awk -F '"' '/version/ {print $2}')
+if [[ "${JAVA_VER}" != 1.8* ]]; then
+  echo "WARNING: Expected Java 8, found $JAVA_VER"
+else
+  echo "✓ Java 8 verified"
+fi
+
+# Verify Leiningen
+echo "Checking Leiningen..."
+lein --version
+echo "✓ Leiningen verified"
+
+# Extract Datomic if not already extracted
+DATOMIC_DIR="lib/datomic-free-0.9.5703"
+DATOMIC_ARCHIVE="lib/datomic-free-0.9.5703.tar.gz"
+
+if [ -f "$DATOMIC_ARCHIVE" ] && [ ! -d "$DATOMIC_DIR/bin" ]; then
+  echo "Extracting Datomic..."
+  tar -xzf "$DATOMIC_ARCHIVE" -C lib/
+  echo "✓ Datomic extracted"
+elif [ -d "$DATOMIC_DIR/bin" ]; then
+  echo "✓ Datomic already extracted"
+else
+  echo "WARNING: Datomic archive not found at $DATOMIC_ARCHIVE"
+fi
+
+# Fetch project dependencies
+echo "Fetching project dependencies (this may take a while on first run)..."
+lein deps || echo "WARNING: Could not fetch all dependencies"
+
+echo ""
+echo "=== Setup Complete ==="
+echo ""
+echo "To start the development environment, run:"
+echo "  ./start.sh"
+echo ""
+echo "Or manually:"
+echo "  1. Start Datomic:  $DATOMIC_DIR/bin/transactor $DATOMIC_DIR/config/samples/free-transactor-template.properties"
+echo "  2. Start server:   lein run"
+echo "  3. Start REPL:     lein repl"
+echo ""

.vscode/tasks.json

@@ -0,0 +1,26 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Datomic Transactor",
+      "type": "shell",
+      "command": "./lib/datomic-free-0.9.5703/bin/transactor ./lib/datomic-free-0.9.5703/config/working-transactor.properties",
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Clojure Server",
+      "type": "shell",
+      "command": "lein run",
+      "isBackground": true,
+      "problemMatcher": []
+    },
+    {
+      "label": "Lein REPL",
+      "type": "shell",
+      "command": "lein repl",
+      "isBackground": true,
+      "problemMatcher": []
+    }
+  ]
+}

AGENTS.md

@@ -0,0 +1,137 @@
+# Agent Guidelines
+
+> **This is a living document.** Update it as conventions evolve or new patterns emerge. When you establish a new pattern or discover a better approach, document it here.
+
+---
+
+## First Steps
+
+**Before doing anything else, read [`docs/CODEBASE.md`](./docs/CODEBASE.md).**
+
+That document contains:
+- Tech stack and architecture overview
+- Directory structure and key files
+- Core concepts (entity/template/modifier system)
+- Patterns and conventions
+- Known quirks and gotchas
+- Accumulated learnings from previous work
+
+**Update `docs/CODEBASE.md`** when you:
+- Discover something non-obvious about the codebase
+- Find a quirk or gotcha that would trip up future agents
+- Learn how a subsystem works that isn't documented
+- Complete significant work that changes how things work
+
+---
+
+## Development Setup
+
+### Quick Start (Local)
+
+1. **Java 8** required (not newer)
+2. **Leiningen** for build/REPL
+3. **Datomic transactor** running:
+   ```bash
+   # Windows (use bundled version due to path length bug)
+   bin\transactor config/samples/free-transactor-template.properties
+
+   # Mac/Linux
+   bin/transactor config/samples/free-transactor-template.properties
+   ```
+4. **Backend REPL**: `lein with-profile +start-server repl`
+   ```clojure
+   (init-database)  ; only once per fresh DB
+   (start-server)
+   ```
+5. **Frontend**: `lein figwheel` (hot reloads)
+
+### Using Dev Container
+
+The `.devcontainer/` setup handles all dependencies automatically.
+
+### Using start.sh
+
+The `start.sh` script automates the above steps with dependency checking.
+
+---
+
+## Code Conventions
+
+### Error Handling
+
+Use the DRY macros from `src/cljc/orcpub/errors.cljc`:
+
+```clojure
+(require '[orcpub.errors :as errors])
+
+;; Database operations
+(errors/with-db-error-handling :operation-failed {:user-id id} "Failed to save"
+  (d/transact conn tx-data))
+
+;; Email operations
+(errors/with-email-error-handling :email-failed {:to email} "Failed to send"
+  (postal/send-message msg))
+
+;; Parsing/validation
+(errors/with-validation :invalid-input {:field "id"} "Invalid ID format"
+  (Long/parseLong id-string))
+```
+
+See `docs/ERROR_HANDLING.md` for full documentation.
+
+### File Organization
+
+- **Backend only**: `src/clj/orcpub/`
+- **Frontend only**: `src/cljs/orcpub/`
+- **Shared code**: `src/cljc/orcpub/` (runs on both JVM and browser)
+
+### Testing
+
+- Mirror source structure in `test/clj/` and `test/cljs/`
+- Run backend tests: `lein test`
+- Run frontend tests: `lein doo`
+
+---
+
+## Working on This Repo
+
+### Before Making Changes
+
+1. Read `docs/CODEBASE.md` for context
+2. Understand the entity/template/modifier system if touching character logic
+3. Check existing patterns in similar files
+
+### After Making Changes
+
+1. Run relevant tests
+2. Update `docs/CODEBASE.md` if you learned something new
+3. Update this file if you established new conventions
+
+### Commit Style
+
+Follow conventional commits:
+- `feat:` new features
+- `fix:` bug fixes
+- `docs:` documentation changes
+- `refactor:` code restructuring
+- `test:` adding/updating tests
+
+---
+
+## Key Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [`docs/CODEBASE.md`](./docs/CODEBASE.md) | **Start here.** Architecture, patterns, learnings |
+| [`docs/ERROR_HANDLING.md`](./docs/ERROR_HANDLING.md) | Error handling utilities and patterns |
+| [`docs/ORCBREW_FILE_VALIDATION.md`](./docs/ORCBREW_FILE_VALIDATION.md) | File import/export validation |
+| [`README.md`](./README.md) | Setup, deployment, contributing |
+
+---
+
+## Notes for Future Agents
+
+- The modifier system uses `?symbol` syntax - this is intentional DSL, not a typo
+- Datomic Free on Windows requires the bundled version (path length bug)
+- Frontend changes hot-reload; backend changes need REPL reload
+- `clojure.edn/read-string` is safe; `clojure.core/read-string` is not - we use the safe one