Merge branch 'feature/process-compose-frontend'

ai/frontend-context.md

@@ -36,14 +36,19 @@ Install dependencies in a fresh checkout or worktree:
 direnv exec "$(git rev-parse --show-toplevel)" npm install
 ```
 
-Start the development server on the port assigned by the shell hook:
+To start only the development server on the port assigned by the shell hook:
 
 ```sh
 direnv exec "$(git rev-parse --show-toplevel)" \
-  npm run dev -- --port "$VITE_PORT"
+  npm run dev -- \
+  --host 127.0.0.1 \
+  --port "$VITE_PORT" \
+  --strictPort
 ```
 
-`process-compose` does not start or proxy the frontend.
+`process-compose` starts the frontend as part of the full development stack.
+The frontend remains directly accessible on `VITE_PORT`; Caddy does not proxy
+it.
 
 The available validation commands are:
 

ai/shared.md

@@ -74,12 +74,15 @@ those changes with the most relevant parser, formatter, dry run, or check.
 - Run backend commands from `backend/`, or explicitly change into it in the
   command. The direnv target remains the worktree root.
 - Run frontend commands from `frontend/website/`.
-- `process-compose` does not start the frontend. Start it separately with
+- `process-compose` starts the frontend on the worktree's assigned port. To
-  the worktree's assigned port when needed:
+  start only the frontend:
 
   ```sh
   direnv exec "$(git rev-parse --show-toplevel)" \
-    npm run dev -- --port "$VITE_PORT"
+    npm run dev -- \
+    --host 127.0.0.1 \
+    --port "$VITE_PORT" \
+    --strictPort
   ```
 
 - When a normally valid check fails because a required service is down,

nix/shell-hook.sh

@@ -124,4 +124,5 @@ if [ ! -e "$REPO_ROOT/backend/public/storage" ]; then
   (cd "$REPO_ROOT/backend" && php artisan storage:link)
 fi
 
-echo "[dev] run 'process-compose up' to start postgres + mailpit + backend + caddy"
+echo "[dev] run 'process-compose up' to start:" \
+  "postgres + mailpit + backend + caddy + frontend"

process-compose.yaml

@@ -44,6 +44,21 @@ processes:
       initial_delay_seconds: 2
       period_seconds: 10
 
+  frontend:
+    command: >-
+      npm run dev --
+      --host 127.0.0.1
+      --port ${VITE_PORT:-5173}
+      --strictPort
+    working_dir: ./frontend/website
+    readiness_probe:
+      http_get:
+        host: 127.0.0.1
+        port: ${VITE_PORT:-5173}
+        path: /
+      initial_delay_seconds: 1
+      period_seconds: 2
+
   caddy:
     command: caddy run --config Caddyfile --adapter caddyfile
     depends_on: