docs: refresh README — accuracy pass + HarborForge platform context

Verified against current code; fixed stale/inaccurate sections and
documented previously-undocumented features/flags/endpoints. Added a
"Part of the HarborForge platform" reference and role/port.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.gitmodules

@@ -1,6 +1,6 @@
 [submodule "HarborForge.Backend.Test"]
 	path = HarborForge.Backend.Test
-	url = https://zhi:rT5Wjw24mV4all38fIoNQfl2@git.hangman-lab.top/zhi/HarborForge.Backend.Test.git
+	url = https://git.hangman-lab.top/zhi/HarborForge.Backend.Test.git
 [submodule "HarborForge.Frontend.Test"]
 	path = HarborForge.Frontend.Test
-	url = https://zhi:rT5Wjw24mV4all38fIoNQfl2@git.hangman-lab.top/zhi/HarborForge.Frontend.Test.git
+	url = https://git.hangman-lab.top/zhi/HarborForge.Frontend.Test.git

README.md

@@ -1 +1,136 @@
 # HarborForge.Test
+
+Integration / end-to-end test harness for the HarborForge platform. It
+spins up the full stack (MySQL, AbstractWizard, HarborForge.Backend,
+HarborForge.Frontend) in Docker and runs the backend and frontend test
+suites against it.
+
+Part of the [HarborForge](../README.md) platform.
+
+## Layout
+
+```
+HarborForge.Test/
+├── run-test.sh                       # Quick frontend E2E run (no rebuild)
+├── run-test-frontend.sh              # Full frontend E2E run (rebuild + optional port expose)
+├── cleanup.sh                        # Tear down containers / wizard config volume
+├── docker-compose-frontend.yml       # Internal-only test stack
+├── docker-compose-frontend-expose.yml# Same stack with ports bound to 127.0.0.1
+├── .env.TEST                         # Default service ports
+├── HarborForge.Backend.Test/         # git submodule — backend pytest suite
+└── HarborForge.Frontend.Test/        # git submodule — frontend Playwright suite
+```
+
+The two test suites are git submodules (see `.gitmodules`). After cloning,
+initialize them:
+
+```bash
+git submodule update --init --recursive
+```
+
+## What It Tests
+
+### Backend — `HarborForge.Backend.Test` (pytest)
+
+A standalone pytest suite that imports the backend code from
+`../HarborForge.Backend/` via `tests/conftest.py` and runs against an
+in-memory SQLite database for fast, isolated unit/integration tests.
+Configured by `pyproject.toml` (`testpaths = ["tests"]`, verbose,
+short tracebacks).
+
+Coverage spans auth/JWT, users, projects, milestones, tasks, comments,
+roles/permissions, the milestone and task state machines
+(`test_milestone_actions.py`, `test_task_transitions.py`), proposals
+(`test_propose.py`), the monitor endpoint, and miscellaneous endpoints
+(notifications, activity log, API keys, dashboard).
+
+Run it standalone:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r HarborForge.Backend.Test/requirements.txt
+cd HarborForge.Backend.Test && pytest          # or: pytest -v, pytest tests/test_auth.py
+```
+
+See `HarborForge.Backend.Test/README.md` for the full test breakdown.
+
+### Frontend — `HarborForge.Frontend.Test` (Playwright)
+
+A Playwright (`@playwright/test`) end-to-end suite that drives the running
+frontend through a browser. Specs in `tests/` cover the setup wizard,
+projects editor, milestones, tasks, role editor and proposals
+(`wizard.spec.ts`, `project-editor.spec.ts`, `milestone.spec.ts`,
+`task.spec.ts`, `role-editor.spec.ts`, `propose.spec.ts`,
+`proposal-essential.spec.ts`). Its Docker image runs a helper proxy
+(`server/proxy.mjs`) alongside `npx playwright test`.
+
+> Note: the frontend's own Vitest unit tests live in the
+> `HarborForge.Frontend` repo; this harness exercises the frontend through
+> Playwright against the full Docker stack.
+
+## Docker Test Stack
+
+`docker-compose-frontend.yml` defines five services on a private
+`test-network` bridge — `mysql` (MySQL 8, tmpfs storage), `wizard`
+(AbstractWizard), `backend` (HarborForge.Backend), `frontend`
+(HarborForge.Frontend), and `test` (the Playwright runner image built from
+`HarborForge.Frontend.Test/`). Service ports default from `.env.TEST`
+(`WIZARD_PORT=8080`, `MYSQL_PORT=3306`, `BACKEND_PORT=8000`,
+`FRONTEND_PORT=3000`).
+
+- `docker-compose-frontend.yml` — services are reachable only on the
+  internal network (wizard alone is bound to `127.0.0.1`).
+- `docker-compose-frontend-expose.yml` — same stack, but mysql, wizard,
+  backend and frontend ports are also bound to `127.0.0.1` for debugging.
+
+## Running the Tests
+
+### Quick run (no rebuild)
+
+```bash
+./run-test.sh
+```
+
+Brings the stack up from `docker-compose-frontend.yml`, waits (up to ~60s)
+for the frontend to answer HTTP 200, runs the `test` service once, then
+tears everything down with `down -v`.
+
+### Full run (rebuild, optional port exposure)
+
+```bash
+./run-test-frontend.sh                      # rebuild all images, run, auto-cleanup
+./run-test-frontend.sh --expose-port on     # use the *-expose.yml file, keep services up
+./run-test-frontend.sh --expose-port off    # default: cleanup after the run
+```
+
+It loads `.env.TEST`, rebuilds the frontend (with build arg
+`VITE_API_BASE=http://backend:8000`), backend and test-runner images with
+`--no-cache`, starts the stack, waits for the frontend, then runs the
+`test` service with `WORKERS=1`. With `--expose-port on` it uses
+`docker-compose-frontend-expose.yml` and leaves the stack running for
+inspection.
+
+### Cleanup
+
+```bash
+./cleanup.sh
+```
+
+Stops and removes containers/networks (keeps images) and drops the
+`harborforgetest_wizard_config` volume. The run scripts also call
+`docker compose ... down -v` themselves on completion (except when port
+exposure is on).
+
+## CI Notes
+
+- Both run scripts use `set -e` and propagate the test container's exit
+  code, so they are CI-friendly: a non-zero `TEST_EXIT_CODE` fails the job.
+- `run-test-frontend.sh` suppresses build/startup output unless a step
+  fails, in which case it prints the tail of that step's log.
+- Builds use `--no-cache` and remove prior `harborforge-test-*:dev` images
+  to guarantee a clean stack each run; MySQL uses `tmpfs` so no state
+  persists between runs.
+- Ensure submodules are initialized
+  (`git submodule update --init --recursive`) before invoking the scripts
+  in CI.

docker-compose-frontend-expose.yml

@@ -74,6 +74,9 @@ services:
     restart: "no"
     environment:
       VITE_API_BASE_URL: http://backend:${BACKEND_PORT:-8000}
+      VITE_WIZARD_PORT: ${WIZARD_PORT:-8080}
+      FRONTEND_DEV_MODE: ${FRONTEND_DEV_MODE:-1}
+      NODE_ENV: development
     ports:
       - "127.0.0.1:${FRONTEND_PORT:-3000}:${FRONTEND_PORT:-3000}"
     depends_on:
@@ -91,13 +94,16 @@ services:
     restart: "no"
     environment:
       # Use internal service name for test to reach frontend
-      BASE_URL: http://frontend:${FRONTEND_PORT:-3000}
+      BASE_URL: http://127.0.0.1:${FRONTEND_PORT:-3000}
-      FRONTEND_URL: http://frontend:${FRONTEND_PORT:-3000}
+      FRONTEND_URL: http://127.0.0.1:${FRONTEND_PORT:-3000}
-      WEB_SERVER_URL: http://frontend:${FRONTEND_PORT:-3000}
+      WEB_SERVER_URL: http://127.0.0.1:${FRONTEND_PORT:-3000}
-      WIZARD_URL: http://wizard:${WIZARD_PORT:-8080}/wizard
+      WIZARD_URL: http://127.0.0.1:${WIZARD_PORT:-8080}/wizard
-      WIZARD_API_URL: http://wizard:${WIZARD_PORT:-8080}
+      WIZARD_API_URL: http://127.0.0.1:${WIZARD_PORT:-8080}
       WIZARD_HOST: wizard
       WIZARD_PORT: ${WIZARD_PORT:-8080}
+      BACKEND_URL: http://127.0.0.1:${BACKEND_PORT:-8000}
+      BACKEND_HOST: backend
+      FRONTEND_HOST: frontend
       CHROME_DEBUGGING_PORT: 9222
     networks:
       - test-network

docker-compose-frontend.yml

@@ -54,6 +54,9 @@ services:
       SECRET_KEY: ${SECRET_KEY:-change_me_in_production}
       LOG_LEVEL: ${LOG_LEVEL:-INFO}
       DATABASE_URL: mysql+pymysql://harborforge:harborforge_pass@mysql:${MYSQL_PORT:-3306}/harborforge
+    depends_on:
+      mysql:
+        condition: service_healthy
     networks:
       - test-network
 
@@ -69,6 +72,9 @@ services:
     environment:
       # Use internal service name
       VITE_API_BASE_URL: http://backend:${BACKEND_PORT:-8000}
+      VITE_WIZARD_PORT: ${WIZARD_PORT:-8080}
+      FRONTEND_DEV_MODE: ${FRONTEND_DEV_MODE:-1}
+      NODE_ENV: development
     networks:
       - test-network
 

run-test-frontend.sh

@@ -1,10 +1,8 @@
 #!/bin/bash
 # Run frontend test with optional port exposure
 # Usage: ./run-test-frontend.sh [--expose-port {on|off}]
-# Default: off
+# Default:
-# 
+#   --expose-port off: Auto cleanup after test
-# --expose-port on:  Keep services running after test (manual cleanup required)
-# --expose-port off: Auto cleanup after test (default)
 
 set -e
 
@@ -54,13 +52,44 @@ fi
 
 echo "📦 Using compose file: $COMPOSE_FILE"
 
+run_quiet() {
+    local label="$1"
+    shift
+    local log_file
+    log_file=$(mktemp)
+    if "$@" >"$log_file" 2>&1; then
+        rm -f "$log_file"
+        return 0
+    fi
+    echo "❌ ${label} failed"
+    echo "--- ${label} log ---"
+    tail -n 200 "$log_file"
+    rm -f "$log_file"
+    return 1
+}
+
 # Clean any previous containers first
 echo "🧹 Cleaning up previous containers..."
-docker compose -f "$COMPOSE_FILE" down -v 2>/dev/null || true
+docker compose -f "$COMPOSE_FILE" down -v >/dev/null 2>&1 || true
+
+# Build frontend with correct API base URL (force no cache, remove image first)
+echo "🔨 Building frontend..."
+docker rmi harborforge-test-frontend:dev >/dev/null 2>&1 || true
+run_quiet "frontend build" docker compose -f "$COMPOSE_FILE" build --no-cache --build-arg VITE_API_BASE=http://backend:8000 frontend
+
+# Build backend (force no cache, remove image first)
+echo "🔨 Building backend..."
+docker rmi harborforge-test-backend:dev >/dev/null 2>&1 || true
+run_quiet "backend build" docker compose -f "$COMPOSE_FILE" build --no-cache backend
+
+# Build test runner (force no cache, remove image first)
+echo "🔨 Building test runner..."
+docker rmi harborforge-test-runner:dev >/dev/null 2>&1 || true
+run_quiet "test runner build" docker compose -f "$COMPOSE_FILE" build --no-cache test
 
 # Start services
 echo "📦 Starting services..."
-docker compose -f "$COMPOSE_FILE" up -d
+run_quiet "service startup" docker compose -f "$COMPOSE_FILE" up -d
 
 # Wait for frontend to be ready
 echo "⏳ Waiting for services..."
@@ -81,9 +110,9 @@ fi
 
 echo "✅ Services ready!"
 
-# Run test
+# Run test using the image default CMD so proxy startup stays inside Frontend.Test Dockerfile
 echo "🧪 Running test..."
-docker compose -f "$COMPOSE_FILE" run --rm test
+docker compose -f "$COMPOSE_FILE" run --rm -e WORKERS=1 test
 TEST_EXIT_CODE=$?
 
 # Cleanup decision based on expose-port