Harden template for production: add comments, fix bugs, add lock file

- Add inline comments to docker-compose.yml explaining the 5 key rules
  (expose vs ports, DB host, DB name persistence, no Traefik labels)
- Add comments to Dockerfile explaining multi-stage build, layer caching,
  and why .dockerignore excludes client/dist
- Add comments to .dockerignore explaining each exclusion
- Fix dev script: use nodemon (auto-restart) instead of node for server.js
- Add postinstall script to auto-install client deps (cd client && npm install)
- Fix SPA fallback: bare return → next() to prevent hanging requests
- Add root package-lock.json for deterministic server dependency installs
- Remove committed tsconfig.tsbuildinfo build artifact, add *.tsbuildinfo to .gitignore
- Update README: simpler install (npm install handles everything), reference SAAC_DEPLOYMENT.md,
  use npx instead of pnpm dlx for shadcn components

docker-compose.yml

@@ -1,3 +1,13 @@
+# SAAC Application Stack
+# See SAAC_DEPLOYMENT.md for full deployment rules and common mistakes.
+#
+# Key rules:
+#   1. Use "expose", NEVER "ports" — Traefik handles routing
+#   2. Database host = service name ("postgres"), NEVER "localhost"
+#   3. Do NOT change POSTGRES_DB after first deploy — Docker volume keeps the old name
+#   4. Do NOT add Traefik labels — SAAC uses file provider, labels are ignored
+#   5. Keep it simple — get this working first, then iterate
+
 services:
   app:
     build:
@@ -9,10 +19,16 @@ services:
     environment:
       - NODE_ENV=production
       - PORT=3000
+      # Database host MUST be the service name ("postgres"), not "localhost".
+      # In Docker, localhost = inside this container. "postgres" resolves to
+      # the postgres service below via Docker DNS.
       - POSTGRES_HOST=postgres
       - POSTGRES_PORT=5432
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
+      # WARNING: Do NOT change POSTGRES_DB after first deploy!
+      # The Docker volume persists the original database name.
+      # If you change this, the new database won't exist and your app will crash.
       - POSTGRES_DB=postgres
       - REDIS_HOST=redis
       - REDIS_PORT=6379
@@ -22,6 +38,9 @@ services:
         condition: service_healthy
       redis:
         condition: service_healthy
+    # Use "expose" to make the port available to Traefik on the Docker network.
+    # NEVER use "ports" (e.g. "3000:3000") — it binds to the host and conflicts
+    # with other apps. Traefik handles all external routing automatically.
     expose:
       - "3000"
     healthcheck:
@@ -37,6 +56,7 @@ services:
     environment:
       - POSTGRES_USER=postgres
       - POSTGRES_PASSWORD=postgres
+      # This creates the database on first start. Must match POSTGRES_DB above.
       - POSTGRES_DB=postgres
     volumes:
       - postgres-data:/var/lib/postgresql/data