diff --git a/doc/DOCKER.md b/doc/DOCKER.md
index 623adb9e..033812f3 100644
--- a/doc/DOCKER.md
+++ b/doc/DOCKER.md
@@ -73,6 +73,7 @@ Use this when you want to mimic a fresh machine that only has Ubuntu + npm and v
 
 - `npx paperclipai onboard --yes` completes
 - the server binds to `0.0.0.0:3100` so host access works
+- onboard/run banners and startup logs are visible in your terminal
 
 Build + run:
 
@@ -80,7 +81,7 @@ Build + run:
 ./scripts/docker-onboard-smoke.sh
 ```
 
-Open: `http://localhost:3100`
+Open: `http://localhost:3131` (default smoke host port)
 
 Useful overrides:
 
@@ -93,5 +94,7 @@ Notes:
 
 - Persistent data is mounted at `./data/docker-onboard-smoke` by default.
 - Container runtime user id defaults to your local `id -u` so the mounted data dir stays writable while avoiding root runtime.
-- Smoke script defaults to `authenticated/private` mode so `HOST=0.0.0.0` can be exposed to the host on port 3100.
+- Smoke script defaults to `authenticated/private` mode so `HOST=0.0.0.0` can be exposed to the host.
+- Smoke script defaults host port to `3131` to avoid conflicts with local Paperclip on `3100`.
+- Run the script in the foreground to watch the onboarding flow; stop with `Ctrl+C` after validation.
 - The image definition is in `Dockerfile.onboard-smoke`.
diff --git a/scripts/docker-onboard-smoke.sh b/scripts/docker-onboard-smoke.sh
index b64b7123..2da125de 100755
--- a/scripts/docker-onboard-smoke.sh
+++ b/scripts/docker-onboard-smoke.sh
@@ -3,12 +3,17 @@ set -euo pipefail
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 IMAGE_NAME="${IMAGE_NAME:-paperclip-onboard-smoke}"
-HOST_PORT="${HOST_PORT:-3100}"
+HOST_PORT="${HOST_PORT:-3131}"
 PAPERCLIPAI_VERSION="${PAPERCLIPAI_VERSION:-latest}"
 DATA_DIR="${DATA_DIR:-$REPO_ROOT/data/docker-onboard-smoke}"
 HOST_UID="${HOST_UID:-$(id -u)}"
 PAPERCLIP_DEPLOYMENT_MODE="${PAPERCLIP_DEPLOYMENT_MODE:-authenticated}"
 PAPERCLIP_DEPLOYMENT_EXPOSURE="${PAPERCLIP_DEPLOYMENT_EXPOSURE:-private}"
+DOCKER_TTY_ARGS=()
+
+if [[ -t 0 && -t 1 ]]; then
+  DOCKER_TTY_ARGS=(-it)
+fi
 
 mkdir -p "$DATA_DIR"
 
@@ -24,7 +29,9 @@ echo "==> Running onboard smoke container"
 echo "    UI should be reachable at: http://localhost:$HOST_PORT"
 echo "    Data dir: $DATA_DIR"
 echo "    Deployment: $PAPERCLIP_DEPLOYMENT_MODE/$PAPERCLIP_DEPLOYMENT_EXPOSURE"
+echo "    Live output: onboard banner and server logs stream in this terminal (Ctrl+C to stop)"
 docker run --rm \
+  "${DOCKER_TTY_ARGS[@]}" \
   --name "${IMAGE_NAME//[^a-zA-Z0-9_.-]/-}" \
   -p "$HOST_PORT:3100" \
   -e HOST=0.0.0.0 \