docs: add comprehensive README with testing and deployment instructions

Includes development setup, Docker deployment, API reference, WebSocket events,
troubleshooting guide, and curl-based test script. Updates App plan.md with
implementation completion status.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/test-api.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# API test script for Spelljammer Ship Tracker
+# Run with: bash server/test-api.sh
+# Requires: curl, jq (optional, for pretty output)
+
+BASE=http://localhost:3000/api
+JQ="cat"
+command -v jq > /dev/null 2>&1 && JQ="jq ."
+
+echo "=== Health Check ==="
+curl -s $BASE/health | $JQ
+echo ""
+
+echo "=== Create Ship ==="
+SHIP=$(curl -s -X POST $BASE/ships \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Astral Clipper","hull_max":100,"hull_current":100,"armor_max":50,"armor_current":50,"ac":15,"speed":8,"maneuver_class":"B"}')
+echo "$SHIP" | $JQ
+SHIP_ID=$(echo "$SHIP" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+echo "Ship ID: $SHIP_ID"
+echo ""
+
+echo "=== List Ships ==="
+curl -s $BASE/ships | $JQ
+echo ""
+
+echo "=== Get Ship (with weapons) ==="
+curl -s $BASE/ships/$SHIP_ID | $JQ
+echo ""
+
+echo "=== Update Ship (take 15 hull damage) ==="
+curl -s -X PATCH $BASE/ships/$SHIP_ID \
+  -H 'Content-Type: application/json' \
+  -d '{"hull_current":85}' | $JQ
+echo ""
+
+echo "=== Add Weapon: Ballista ==="
+WEAPON=$(curl -s -X POST $BASE/ships/$SHIP_ID/weapons \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Ballista","attack_mod":6,"damage":"3d10","range":"120/480","ammo_max":10,"ammo_current":10}')
+echo "$WEAPON" | $JQ
+WEAPON_ID=$(echo "$WEAPON" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
+echo "Weapon ID: $WEAPON_ID"
+echo ""
+
+echo "=== Add Weapon: Spellcannon ==="
+curl -s -X POST $BASE/ships/$SHIP_ID/weapons \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Spellcannon","attack_mod":8,"damage":"4d8","range":"60/240","ammo_max":5,"ammo_current":5}' | $JQ
+echo ""
+
+echo "=== Update Weapon (fire, reduce ammo) ==="
+curl -s -X PATCH $BASE/weapons/$WEAPON_ID \
+  -H 'Content-Type: application/json' \
+  -d '{"ammo_current":9}' | $JQ
+echo ""
+
+echo "=== Get Ship (verify weapons attached) ==="
+curl -s $BASE/ships/$SHIP_ID | $JQ
+echo ""
+
+echo "=== Delete Weapon ==="
+curl -s -X DELETE $BASE/weapons/$WEAPON_ID | $JQ
+echo ""
+
+echo "=== Delete Ship (cascades to remaining weapons) ==="
+curl -s -X DELETE $BASE/ships/$SHIP_ID | $JQ
+echo ""
+
+echo "=== List Ships (should be empty or minus the deleted one) ==="
+curl -s $BASE/ships | $JQ
+echo ""
+
+echo "=== All tests completed ==="