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>

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.

run-test-frontend.sh

@@ -1,16 +1,13 @@
 #!/bin/bash
 # Run frontend test with optional port exposure
-# Usage: ./run-test-frontend.sh [--expose-port {on|off}] [--test-real-plugin]
+# Usage: ./run-test-frontend.sh [--expose-port {on|off}]
-# Default: 
+# Default:
 #   --expose-port off: Auto cleanup after test
-#   --test-real-plugin: Run only real-plugin.spec.ts (requires vps.t1 plugin)
 
 set -e
 
 EXPOSE_PORT="off"
-TEST_REAL_PLUGIN="off"
 COMPOSE_FILE="docker-compose-frontend.yml"
-TEST_PATTERN=""
 
 # Load environment variables from .env.TEST if exists
 if [ -f ".env.TEST" ]; then
@@ -31,13 +28,9 @@ while [[ $# -gt 0 ]]; do
             EXPOSE_PORT="${1#*=}"
             shift
             ;;
-        --test-real-plugin)
-            TEST_REAL_PLUGIN="on"
-            shift
-            ;;
         *)
             echo "Unknown option: $1"
-            echo "Usage: $0 [--expose-port {on|off}] [--test-real-plugin]"
+            echo "Usage: $0 [--expose-port {on|off}]"
             exit 1
             ;;
     esac
@@ -49,14 +42,6 @@ if [[ "$EXPOSE_PORT" != "on" && "$EXPOSE_PORT" != "off" ]]; then
     exit 1
 fi
 
-# Set test pattern for real plugin test
-if [[ "$TEST_REAL_PLUGIN" == "on" ]]; then
-    TEST_PATTERN="real-plugin.spec.ts"
-    echo "🔌 Real Plugin Test Mode: ON"
-    echo "   Will run: tests/real-plugin.spec.ts"
-    echo "   Requires vps.t1 to have OpenClaw plugin installed"
-fi
-
 # Select compose file based on expose-port
 if [[ "$EXPOSE_PORT" == "on" ]]; then
     COMPOSE_FILE="docker-compose-frontend-expose.yml"
@@ -125,15 +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..."
-if [[ -n "$TEST_PATTERN" ]]; then
+docker compose -f "$COMPOSE_FILE" run --rm -e WORKERS=1 test
-    # Run specific test for real plugin
-    docker compose -f "$COMPOSE_FILE" run --rm -e WORKERS=1 test npx playwright test tests/real-plugin.spec.ts --reporter=list
-else
-    # Run all tests
-    docker compose -f "$COMPOSE_FILE" run --rm -e WORKERS=1 test
-fi
 TEST_EXIT_CODE=$?
 
 # Cleanup decision based on expose-port
@@ -143,7 +122,7 @@ if [[ "$EXPOSE_PORT" == "on" ]]; then
     echo "   Use './run-test-frontend.sh --expose-port on' to cleanup"
     echo "   Or manually: docker compose -f $COMPOSE_FILE down -v"
     echo ""
-    
+
     if [ $TEST_EXIT_CODE -eq 0 ]; then
         echo "✅ Test passed!"
     else
@@ -153,7 +132,7 @@ else
     echo ""
     echo "🧹 Cleaning up containers and volumes..."
     docker compose -f "$COMPOSE_FILE" down -v
-    
+
     if [ $TEST_EXIT_CODE -eq 0 ]; then
         echo "✅ Test passed!"
     else