IOES-Lab · yeseorizi · Oct 1, 2026 · Oct 1, 2026
diff --git a/README.md b/README.md
@@ -19,15 +19,17 @@ POSIM 1.0 has not been released.
 Existing ROS package names and launch commands remain available. For example,
 the demonstration package is still called `dave_demos`. The initial import
 contains the CUDA sonar implementation; the WGPU work in
-[DAVE PR #44](https://github.com/IOES-Lab/dave/pull/44) is not included in `main`.
+[POSIM PR #6](https://github.com/IOES-Lab/POSIM/pull/6) (moved from DAVE #44) is not included in `main`.
 Without a CUDA toolkit, the CUDA-specific sonar targets are skipped during
 configuration. A successful build on ARM64 therefore does not establish sonar
 availability.
 
 ## Get started
 
-1. Follow the [Ubuntu installation guide](docs/installation.md), or build a
-   [Docker image from this checkout](docs/docker.md).
+1. Start with the [documentation index](docs/README.md). Follow the
+   [Ubuntu source guide](docs/installation.md), or use a
+   [published validation image](docs/docker.md). The PR #5 images are not a
+   POSIM release and include fixes not yet merged into `main`.
 2. Open a terminal with the installed ROS and workspace environments loaded.
 3. Start a world:
 
@@ -56,7 +58,8 @@ More examples are in [the demo guide](examples/dave_demos/README.md).
 
 The [legacy DAVE Wiki](https://dave-ros2.notion.site) remains available for
 background material. Follow this repository's installation instructions for
-POSIM; the legacy Wiki is not a POSIM release manual.
+POSIM; the legacy Wiki is not a POSIM release manual. See the
+[migration notice](docs/migration.md) and [CUDA/WGPU support limits](docs/support.md).
 
 ## Contributing
 

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,29 @@
+# POSIM documentation
+
+POSIM means **Platform for Ocean Simulation** and continues the DAVE codebase.
+The development target is Ubuntu 26.04, ROS 2 Lyrical and Gazebo Jetty.
+Existing `dave_*` package names are retained for compatibility.
+
+## Choose your starting point
+
+- **Try the published candidate:** [Docker Quickstart](docker.md). Select the
+  image for your architecture and run from its installed workspace.
+- **Develop from source on Ubuntu:** [installation](installation.md), then
+  [Quickstart](quickstart.md).
+- **Check sonar availability first:** [CUDA, WGPU and host limitations](support.md).
+- **Move from DAVE:** [migration notice](migration.md) and
+  [compatibility](compatibility.md).
+- **Maintain builds or prepare a release:** [maintainer setup](maintainer-setup.md).
+
+## Status, checked 2026-10-01
+
+POSIM 1.0 has not been released. Two architecture-specific **validation tags**
+were published on 2026-09-30 from the candidate in
+[PR #5](https://github.com/IOES-Lab/POSIM/pull/5). The candidate includes runtime
+fixes not yet merged into `main`. Do not apply its runtime results to a fresh
+`main` build or assume that `latest`, `main-*` or release tags exist.
+
+WGPU sonar is under review in [PR #6](https://github.com/IOES-Lab/POSIM/pull/6).
+Ocean waves/WAM-V work is under review in
+[PR #7](https://github.com/IOES-Lab/POSIM/pull/7). Neither is included in the
+published PR #5 validation images.
diff --git a/docs/docker.md b/docs/docker.md
@@ -1,52 +1,159 @@
-# POSIM Docker development images
+# Run POSIM with Docker
 
-Build images from the repository root so that Docker uses the exact checkout.
-These are local development tags; they do not imply a published POSIM release.
+## 1. Understand which image you are using
 
-## AMD64
+**Status checked 2026-10-01:** the images below are public **validation
+candidates**, not a POSIM 1.0 release. They come from
+[PR #5](https://github.com/IOES-Lab/POSIM/pull/5), which is still unmerged.
+They include candidate runtime fixes absent from `main` and do not include
+WGPU from PR #6 or WAM-V from PR #7.
+
+| Target | Published validation tag | Installed workspace |
+| --- | --- | --- |
+| Linux ARM64 / Apple Silicon Docker | `ioeslab/posim:validation-pr5-abad9d70-arm64-rdp` | `/home/docker/dave_ws` |
+| Linux AMD64 / x86-64 | `ioeslab/posim:validation-pr5-abad9d70-amd64` | `/opt/dave_ws` |
+
+These are separate architecture-specific tags, not a single cross-architecture
+tag. `latest`, `main-amd64`, `main-arm64-rdp` and versioned release tags were
+not published in this validation. Do not substitute one of those names.
+
+Install Docker using the official instructions for
+[Ubuntu](https://docs.docker.com/engine/install/ubuntu/) or
+[macOS](https://docs.docker.com/desktop/setup/install/mac-install/).
+Check `docker version` and `docker info` before continuing. Use Bash or zsh on
+the host; on Windows, use a WSL shell with Docker Linux-container support.
+The Windows host path was not part of the 2026-09-30 native-architecture checks.
+Docker Desktop on Apple Silicon runs Linux in a VM; it is not native macOS
+execution and does not expose the Mac's Metal backend to this Linux image.
+
+## 2. Select one architecture and pull the pinned image
+
+The tag names above are convenient labels. The commands below use immutable
+registry digests so that you obtain the exact published candidate.
+
+**Apple Silicon / Linux ARM64:**
 
 ```bash
-docker build --platform linux/amd64 \
-  -f .docker/lyrical.amd64.dockerfile -t posim:dev-amd64 .
-docker run --rm -it posim:dev-amd64 bash
+export POSIM_PLATFORM=linux/arm64
+export POSIM_IMAGE=ioeslab/posim@sha256:72179187c96a801184a15ab9cdaf3ca9714d3717ce04e97cd2ec60f34d83edb8
+docker pull --platform "$POSIM_PLATFORM" "$POSIM_IMAGE"
 ```
 
-The workspace remains at `/opt/dave_ws`. In an interactive Bash shell its setup
-is loaded through `.bashrc`. For a non-interactive command, source
-`/opt/ros/lyrical/setup.bash` and `/opt/dave_ws/install/setup.bash` explicitly.
-GUI forwarding and GPU passthrough must be configured for the host before using
-graphical or GPU-dependent scenarios.
+**Linux AMD64 / x86-64:**
 
-## ARM64 / Apple Silicon
+```bash
+export POSIM_PLATFORM=linux/amd64
+export POSIM_IMAGE=ioeslab/posim@sha256:9783525a2a18ecc2e275e9af43e82ccab6202bb99b63790ffd165d8885fa9784
+docker pull --platform "$POSIM_PLATFORM" "$POSIM_IMAGE"
+```
+
+Use the native host architecture where possible. AMD64 execution on an ARM64
+host requires emulation and is not equivalent to native AMD64 performance.
+The images are large: check available Docker disk space before pulling.
+
+## 3. Open an isolated shell
 
 ```bash
-docker build --platform linux/arm64 \
-  -f .docker/lyrical.arm64v8.dockerfile -t posim:dev-arm64-rdp .
-docker run --rm -it --name posim-arm64 \
-  -p 127.0.0.1:13389:3389 --shm-size=2g posim:dev-arm64-rdp
+docker run --rm -it --init --name posim-quickstart \
+  --platform "$POSIM_PLATFORM" --shm-size=1g \
+  --entrypoint bash \
+  -e LIBGL_ALWAYS_SOFTWARE=1 -e QT_QPA_PLATFORM=offscreen \
+  -e GZ_IP=127.0.0.1 "$POSIM_IMAGE"
 ```
 
-Connect an RDP client to `localhost:13389`. The inherited development image uses
-the username and password `docker`; the command above exposes RDP only on the
-local machine. The workspace remains at `/home/docker/dave_ws`.
+If a container named `posim-quickstart` already exists, choose another name;
+do not delete an unrelated container. No host directory is mounted, no Docker
+socket is exposed, and no RDP port is opened by this command. Exiting the shell
+removes this disposable container, so copy out any files you want to keep first.
 
-For a shell without the RDP services:
+**Inside the container**, load the installed environments explicitly:
 
 ```bash
-docker run --rm -it --user docker --entrypoint bash posim:dev-arm64-rdp
+source /opt/ros/lyrical/setup.bash
+export POSIM_WS="${DAVE_WS:-${DAVE_UNDERLAY:-}}"
+test -n "$POSIM_WS" && test -r "$POSIM_WS/install/setup.bash"
+source "$POSIM_WS/install/setup.bash"
+cd /tmp
+printf 'ROS_DISTRO=%s\n' "$ROS_DISTRO"
+gz sim --versions
+ros2 pkg prefix dave_demos
 ```
 
-Docker Desktop on Apple Silicon runs this Linux ARM64 image. It does not make
-the Mac's Metal backend available to the CUDA sonar implementation. The initial
-POSIM source does not include the WGPU work from DAVE PR #44.
+Expect `lyrical`, a Gazebo Sim 10.x (Jetty) version, and an installed
+`dave_demos` prefix under the workspace listed above. `DAVE_WS`, `DAVE_UNDERLAY`
+and the `dave_*` package names are compatibility names, not stale commands.
 
-## Publication
+## 4. Start a headless world
 
-`ioeslab/posim` is the configured Docker Hub destination, pending maintainer
-setup and successful publication. The workflows use architecture-specific tags:
-`main-amd64` and `main-arm64-rdp` for branch builds, and version tags such as
-`1.0.0-amd64` and `1.0.0-arm64-rdp` after a future `v1.0.0` tag.
+```bash
+ros2 launch dave_demos dave_world.launch.py \
+  world_name:=dave_ocean_waves headless:=true
+```
+
+No GUI window is expected. In a second **host** terminal, inspect the clock:
+
+```bash
+docker exec -it posim-quickstart bash -c \
+  'source /opt/ros/lyrical/setup.bash; gz topic -e -t /world/oceans_waves/clock'
+```
+
+The world name in the clock topic is `oceans_waves`, not the world filename.
+Clock messages should advance. Stop the clock viewer with Ctrl+C, then stop
+the launch with Ctrl+C in the first terminal and wait for the child processes
+to exit. Check the complete log for segmentation faults, aborts or forced kills.
+A running container alone is not a successful Quickstart.
+
+Try the [REXROV, DVL and camera commands](quickstart.md) next, one at a time.
+Those commands run inside the same sourced shell. The candidate includes a
+Fuel asset cache for the checked cases. Other worlds/assets may still require
+network access on first use; offline-camera success is not an all-world
+offline guarantee. Server-only camera/DVL execution still needs rendering,
+provided by software rendering in the recorded headless tests.
+
+## 5. What was verified
+
+On 2026-09-30, each published architecture was anonymously pulled by digest
+and tested in fresh containers: **14/14 distinct headless Quickstarts**,
+**1/1 additional camera trial with `--network none`**, installed inventory and
+**5/5 installed transport churn probes** passed. Pulls could reuse cached
+layers; this was not an all-layer cold-download test.
+
+- [ARM64 successful publication and re-pull](https://github.com/IOES-Lab/POSIM/actions/runs/36693050122)
+- [AMD64 successful publication job](https://github.com/IOES-Lab/POSIM/actions/runs/36679060248/job/109770314602)
+
+The AMD64 job succeeded even though its enclosing run includes an unsuccessful
+ARM64 publication attempt. The later ARM64 run linked above is the successful
+record. Earlier prepublication evidence comprised 77 connected trials and
+5 offline camera trials per architecture; those are a different test phase,
+not the count of new re-pull tests.
+
+GUI/RDP, joystick input, CUDA/WGPU sonar, physical sensor accuracy and execution
+of every retained world are **outside this validation**. The `-rdp` suffix
+describes the ARM64 image packaging, not a newly verified desktop session.
+
+For audit, the tested application candidate is `abad9d70de843474478de5ef55371c049e40deef`.
+The image revision label `32eedbacf781a0fd1e517481571e76bfaab73c51` identifies
+GitHub's synthetic PR-test checkout, **not** a merge of PR #5 into `main`.
+Publication-tooling commit `584953b5` did not rebuild the images.
+
+## 6. Build a development image yourself (different source state)
+
+From a checkout made using the [source guide](installation.md):
+
+```bash
+cd ~/posim_ws/src/dave
+git rev-parse HEAD
+# Choose ONE build for your target architecture:
+docker build --platform linux/amd64 \
+  -f .docker/lyrical.amd64.dockerfile -t posim:dev-amd64 .
+# Or on ARM64:
+docker build --platform linux/arm64 \
+  -f .docker/lyrical.arm64v8.dockerfile -t posim:dev-arm64-rdp .
+```
 
-Do not assume these tags exist until the corresponding publication has
-completed. This initial configuration does not create a combined multi-platform
-manifest. See [maintainer setup](maintainer-setup.md).
+These `posim:dev-*` tags are local, unpublished builds of **your checkout**.
+They are not the validated registry images above. Building `main` does not
+silently include PR #5's fixes. Record and test that source state independently.
+For GPU/GUI requirements and the experimental WGPU path, see
+[backend support](support.md). Publication settings are documented for
+[maintainers](maintainer-setup.md); this Quickstart does not enable publication.
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,9 +1,14 @@
 # Install POSIM from source
 
 These instructions target **Ubuntu 26.04, ROS 2 Lyrical, and Gazebo Jetty**.
-For macOS, use the [ARM64 Docker image build](docker.md); this page does not
+For macOS, use the [ARM64 Docker candidate](docker.md); this page does not
 describe a native macOS installation.
 
+This procedure builds the current **development `main`**, not the published
+PR #5 candidate. Native source installation was reviewed against the scripts,
+but was not rerun from a clean Ubuntu host during this documentation update.
+For the previously verified image and its limits, see [Docker](docker.md).
+
 ## 1. Check out the source
 
 ```bash
@@ -22,13 +27,16 @@ Review `src/dave/extras/ros-lyrical-gz-jetty-install.sh`, then run it on the tar
 Ubuntu machine:
 
 ```bash
-DAVE_EXTRAS_DIR="$PWD/src/dave/extras" \
+ROS_DISTRO=lyrical DAVE_EXTRAS_DIR="$PWD/src/dave/extras" \
   bash src/dave/extras/ros-lyrical-gz-jetty-install.sh
 ```
 
 This helper performs an apt system upgrade, installs ROS/Gazebo and the
 ArduSub/MAVROS dependencies, and adds environment setup to the user's shell
-configuration. The explicit `DAVE_EXTRAS_DIR` selects the helper files from the
+configuration. Read it before running, and use a fresh Bash shell rather than
+one already sourced for another ROS distribution. Do not run this Ubuntu apt
+installer on macOS or execute a remote script directly through `sudo`.
+The explicit `DAVE_EXTRAS_DIR` selects the helper files from the
 same checkout. It is a retained compatibility variable.
 
 ## 3. Import companion repositories and build
@@ -38,6 +46,7 @@ In a Bash terminal:
 ```bash
 cd ~/posim_ws
 source /opt/ros/lyrical/setup.bash
+source "$HOME/.ros_ardusub_env/env"
 vcs import src --shallow --skip-existing \
   --input src/dave/extras/repos/posim.lyrical.repos
 rosdep update --rosdistro lyrical
@@ -75,9 +84,22 @@ For a server-only REXROV run with interactive controls disabled:
 ```bash
 ros2 launch dave_demos dave_robot.launch.py \
   namespace:=rexrov world_name:=dave_ocean_waves z:=-5 paused:=false \
-  gui:=false use_teleop:=false use_web_joystick:=false
+  gui:=false headless:=true use_teleop:=false use_web_joystick:=false
 ```
 
 Some sensors still require a rendering context during server-only execution.
 First use may also need network access to Gazebo Fuel. See the
 [demo guide](../examples/dave_demos/README.md) for other launch entries.
+
+Open each new Bash terminal with both the ROS/ArduSub environment and the
+workspace sourced before launching:
+
+```bash
+source /opt/ros/lyrical/setup.bash
+source "$HOME/.ros_ardusub_env/env"
+source ~/posim_ws/install/setup.bash
+```
+
+See [Quickstart](quickstart.md) for received-data and shutdown checks and
+[support](support.md) before attempting CUDA or WGPU sonar. A native `main`
+build does not inherit the validation status of the candidate Docker image.
diff --git a/docs/maintainer-setup.md b/docs/maintainer-setup.md
@@ -17,7 +17,17 @@ Until that variable is enabled, Docker jobs remain skipped. Lint runs on `main`
 and pull requests. Docker jobs reject fork pull requests on self-hosted runners.
 The image build uses the checked-out source as its Docker context.
 
-## Enable publication
+## Current publication boundary (2026-10-01)
+
+`POSIM_ENABLE_DOCKER_CI` is enabled. `POSIM_PUBLISH_IMAGES` remains `false`.
+Two [validation-only candidate tags](docker.md) were published through PR #5's
+explicit manual workflow; this did not enable normal main/release publication
+or merge PR #5. The runtime fixes and candidate-publishing tools are still on
+that PR branch, not on `main`. Do not enable general publication until the
+runtime validation changes have been reviewed/merged and `main` has passed
+its own build, runtime and registry re-pull checks.
+
+## Enable future main/release publication
 
 After builds work, create or authorize the `ioeslab/posim` Docker Hub repository
 and configure these **repository secrets**:
@@ -27,7 +37,8 @@ and configure these **repository secrets**:
 
 Set repository variable `POSIM_PUBLISH_IMAGES` to `true` to enable login and
 publication for non-PR builds. With that variable unset, the workflows build
-without logging in or publishing. PR builds never publish images.
+without logging in or publishing. The ordinary PR build workflows never publish images. The explicitly guarded
+PR #5 candidate publisher is a separate validation-only path.
 
 The inherited DAVE PR-image publisher is omitted from the initial POSIM setup:
 the imported Docker build workflows do not produce the image archives that it

diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,49 @@
+# Moving from DAVE to POSIM
+
+POSIM means **Platform for Ocean Simulation**. Development continues at
+[IOES-Lab/POSIM](https://github.com/IOES-Lab/POSIM), on `main`.
+Use the [documentation index](README.md), [Ubuntu installation](installation.md)
+or [Docker candidate Quickstart](docker.md) for new installations.
+
+The [original DAVE Wiki](https://dave-ros2.notion.site) documents an older
+DAVE state. Its historical `ros2` branch commands, Docker image names and
+release claims should not be read as current POSIM instructions. The
+[working POSIM guide](https://caring-dibble-be5.notion.site/3ecc941998988150ad59f75d5bd105cf) records the transition and current limitations.
+Keep the original DAVE references and attribution for the inherited work.
+
+## Compatibility names that should not be renamed by hand
+
+- ROS packages such as `dave_demos`, `dave_worlds` and `dave_sensor_models`.
+- Launch filenames such as `dave_world.launch.py` and `dave_robot.launch.py`.
+- The source checkout key `src/dave` used by repository import.
+- Image workspace paths `/opt/dave_ws` and `/home/docker/dave_ws`.
+- Environment variables `DAVE_EXTRAS_DIR`, `DAVE_WS` and `DAVE_UNDERLAY`.
+
+See [compatibility](compatibility.md). Do not globally replace `dave` with
+`posim` in executable commands or installed resource references.
+
+## Open work and release status
+
+- [PR #5](https://github.com/IOES-Lab/POSIM/pull/5): Docker/runtime fixes and
+  published validation images, still unmerged.
+- [PR #6](https://github.com/IOES-Lab/POSIM/pull/6): WGPU sonar transferred
+  from DAVE #44, still under review.
+- [PR #7](https://github.com/IOES-Lab/POSIM/pull/7): ocean waves/WAM-V
+  transferred from DAVE #27, still under review.
+
+The old PR discussions remain linked from the new PRs. New issues and review
+belong in POSIM. These development checkpoints do not announce POSIM 1.0.
+
+## Original Wiki transition notice
+
+The original public Wiki and the working personal Wiki are different sites.
+On 2026-10-01, the [original Wiki home](https://dave-ros2.notion.site/?v=d54cc8422868455888cc629d8e6117a9)
+was updated with an **OUTDATED — Development has moved to POSIM** notice,
+a link to this repository and the
+[working installation/Quickstart/backend guide](https://caring-dibble-be5.notion.site/3ecc941998988150ad59f75d5bd105cf).
+The notice also distinguishes validation images from an official POSIM 1.0
+release and identifies WGPU as unmerged development work.
+
+The original site's remaining pages are historical DAVE material. Adding the
+home-page notice does not mean that all legacy tutorials have been rewritten
+or executed against POSIM.