docs: consistency audit across README, docs site, and zenoh-bridge demo

.github/workflows/deploy-docs.yaml

@@ -10,6 +10,7 @@ on:
       - "**/*.svg"
       - "**/*.png"
       - "**/*.jpg"
+      - "docs/assets/**"
   workflow_dispatch:
 
 permissions:
@@ -41,12 +42,10 @@ jobs:
           pip install mkdocs-awesome-pages-plugin
           pip install mkdocs-exclude
           pip install mkdocs-macros-plugin
-          pip install mkdocs-same-dir
           pip install pymdown-extensions
           pip install python-markdown-math
           pip install mdx-truly-sane-lists
           pip install plantuml-markdown
-          pip install mkdocs-mermaid2-plugin
 
       - name: Build with MkDocs
         run: mkdocs build --clean --verbose
@@ -83,4 +82,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-

Makefile

@@ -1,23 +1,24 @@
-# Makefile for Openadkit Document
+# Makefile for Open AD Kit documentation
 # Installs required MkDocs packages and serves documentation
 
-.PHONY: help prepare serve build clean
+.PHONY: help prepare prepare-if-missing serve build clean
 
 # Default target
 help:
-	@echo "Openadkit Documentation - Available commands:"
+	@echo "Open AD Kit Documentation - Available commands:"
 	@echo "  make prepare      Prepare Mkdocs development container"
+	@echo "  make prepare-if-missing  Reuse local image if present, otherwise build it"
 	@echo "  make serve        Start development server on the built container"
 	@echo "  make build        Build static documentation"
 	@echo "  make clean        Clean build artifacts"
 
 # Serve documentation locally
 serve:
-	docker run -it --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev
+	docker run --rm -p 8000:8000 -v $$(pwd):/app mkdocs-dev
 
 # Build static documentation
 build:
-	docker run -it --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build
+	docker run --rm -v $$(pwd):/app --user $$(id -u):$$(id -g) mkdocs-dev mkdocs build
 
 # Clean build artifacts
 clean:
@@ -26,3 +27,11 @@ clean:
 # Install mkdocs dependencies
 prepare:
 	docker build -f doc_env/Dockerfile -t mkdocs-dev .
+
+# Reuse an existing image when offline or when rebuilding is unnecessary
+prepare-if-missing:
+	@if docker image inspect mkdocs-dev >/dev/null 2>&1; then \
+		echo "Using existing mkdocs-dev image"; \
+	else \
+		docker build -f doc_env/Dockerfile -t mkdocs-dev .; \
+	fi

README.md

@@ -31,9 +31,9 @@ The Autoware Foundation is a voting member of the [SOAFEE (Scalable Open Archite
 
 Open AD Kit is a micro-service based project, which means that it is designed to be deployed on a variety of platforms with microservices architecture. Each component is designed to be independent and can be deployed on a variety of platforms.
 
-- **Independent components** for sensing, perception, mapping, localization, planning, control, and visualization
-- **Multi-platform deployment** supporting both amd64 and arm64 architectures  
-- **Service mesh integration** with configurable environment variables
+- **Independent images** for sensing, perception, mapping, localization, planning, control, APIs, simulation, and visualization
+- **Multi-platform deployment** supporting both amd64 and arm64 architectures
+- **Configurable ROS 2 container deployments** with environment-driven composition
 
 ![Granular Components](docs/assets/images/granular-components.png)
 
@@ -53,7 +53,7 @@ Open AD Kit leverages modern cloud native technologies to deliver scalable, port
 
 - **Seamless scaling** from development laptops to production edge devices
 - **Hybrid cloud support** bridging development and production environments
-- **Container orchestration** ready for Kubernetes and similar platforms
+- **Containerized runtimes** using Docker Compose, Docker Bake, and platform-specific integrations such as AutoSD
 
 ![Cloud Native](docs/assets/images/cloud-native.png)
 

deployments/README.md

@@ -6,4 +6,4 @@ This directory contains deployment configurations for **Open AD Kit**. Each fold
   - [Planning Simulation](./samples/planning-simulation): Simple Open AD Kit deployment that demonstrates the autoware **planning features** with planning simulation.
   - [Logging Simulation](./samples/logging-simulation): Simple Open AD Kit deployment that demonstrates the autoware **end-to-end functionality** with sensor simulation using rosbag.
 - **Demo deployment** configurations with specific use case scenarios.
-  - [Zenoh Bridge](./demos/zenoh-bridge): A demo of remote visualization with Zenoh bridge. See [Zenoh Bridge Document](openadkit-dev/docs/deployments/zenoh-bridge/index.md) for more details.
+  - [Zenoh Bridge](./demos/zenoh-bridge): A demo of remote visualization with Zenoh bridge. See the [Zenoh Bridge documentation](../docs/deployments/demos/zenoh-bridge/index.md) for more details.

deployments/demos/zenoh-bridge/README.md

@@ -27,10 +27,9 @@ The project provides different deployment strategies to suit various testing nee
 
 ## Quick Start
 
-We recommend using the Split Topology mode in the `local` directory:
+We recommend using the Split Topology mode from this directory:
 
 ```bash
-cd local
 ./edge.sh up -d
 ./cloud.sh up -d
 ```

deployments/demos/zenoh-bridge/docker-compose.yaml

@@ -44,7 +44,7 @@ services:
     environment:
       - RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
       - ROS_DOMAIN_ID=1
-      - REMOTE_PASSWORD=o
+      - REMOTE_PASSWORD=openadkit
       - USE_SIM_TIME=true
     ports:
       - "0.0.0.0:6081:6080"

deployments/samples/logging-simulation/README.md

@@ -4,17 +4,25 @@ This sample deployment shows how to run Autoware Open AD Kit **logging simulatio
 
 ## Requirements
 
-In order to run the logging simulation, you need to have the logging simulation **sample map** and **rosbag**. You can download them by running the following commands:
+In order to run the logging simulation, you need the logging simulation **sample map**, **rosbag**, and the Autoware artifacts downloaded by `setup.sh --download-artifacts`.
+
+If `gdown` or `unzip` are not installed yet, install them first:
+
+```bash
+sudo apt-get install -y python3-pip unzip
+python3 -m pip install --user gdown
+```
 
 ### Sample Logging Map
 
 Download and unpack a logging simulation sample map that is used in this sample.
 
-- You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually.
+- You can also download [the map](https://drive.google.com/file/d/1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI/view?usp=sharing) manually.
 
 ```bash
-gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI'
-unzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip
+mkdir -p ~/autoware_map
+gdown -O ~/autoware_map/sample-map-rosbag.zip 'https://docs.google.com/uc?export=download&id=1A-8BvYRX3DhSzkAnOcGWFw5T30xTlwZI'
+unzip -o -d ~/autoware_map ~/autoware_map/sample-map-rosbag.zip
 ```
 
 > **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/).
@@ -23,15 +31,23 @@ unzip -d ~/autoware_map/ ~/autoware_map/sample-map-rosbag.zip
 
 Download and unpack a sample rosbag that is used for **sensor simulation** in this sample.
 
-- You can also download [the rosbag](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually.
+- You can also download [the rosbag](https://drive.google.com/file/d/1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP/view?usp=sharing) manually.
 
 ```bash
-gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP'
-unzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip
+gdown -O ~/autoware_map/sample-rosbag.zip 'https://docs.google.com/uc?export=download&id=1sU5wbxlXAfHIksuHjP3PyI2UVED8lZkP'
+unzip -o -d ~/autoware_map ~/autoware_map/sample-rosbag.zip
 ```
 
 > **Note**: Due to privacy concerns, the rosbag(Copyright 2020 TIER IV, Inc.) does not contain image data, which will cause: Traffic light recognition functionality cannot be tested with this sample rosbag. Object detection accuracy is decreased.
 
+### Autoware Artifacts
+
+This deployment mounts `${HOME}/autoware_data` into the sensing and perception containers. Download the artifacts ahead of time by following the [Getting Started](../../../docs/getting-started/index.md) guide:
+
+```bash
+sudo ./setup.sh --download-artifacts
+```
+
 ## Run the Deployment
 
 1. Start the deployment by running the following command:
@@ -46,7 +62,7 @@ unzip -d ~/autoware_map/ ~/autoware_map/sample-rosbag.zip
     http://localhost:6080/vnc.html
     ```
 
-    Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.**
+    Use the default password `openadkit` to access the visualizer. **It can take a few seconds for the visualizer to start.**
 
     > If your machine is on a remote server, you can access the visualizer by using its accessible IP address:
     >

deployments/samples/planning-simulation/README.md

@@ -4,7 +4,14 @@ This sample deployment shows how to run Autoware Open AD Kit **planning simulati
 
 ## Requirements
 
-In order to run the planning simulation, you need to have the planning simulation **sample map**. You can download it by running the following commands:
+In order to run the planning simulation, you need the planning simulation **sample map**.
+
+If `gdown` or `unzip` are not installed yet, install them first:
+
+```bash
+sudo apt-get install -y python3-pip unzip
+python3 -m pip install --user gdown
+```
 
 ### Sample Planning Map
 
@@ -13,8 +20,9 @@ Download and unpack a planning simulation sample map that is used in this sample
 - You can also download [the map](https://drive.google.com/file/d/1499_nsbUbIeturZaDj7jhUownh5fvXHd/view?usp=sharing) manually.
 
 ```bash
-gdown -O ~/autoware_map/ 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd'
-unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip
+mkdir -p ~/autoware_map
+gdown -O ~/autoware_map/sample-map-planning.zip 'https://docs.google.com/uc?export=download&id=1499_nsbUbIeturZaDj7jhUownh5fvXHd'
+unzip -o -d ~/autoware_map ~/autoware_map/sample-map-planning.zip
 ```
 
 > **Note**: This sample map(Copyright 2020 TIER IV, Inc.) is only for demonstration purposes. You can use your own map by following the [How-to Guide](https://autowarefoundation.github.io/autoware-documentation/main/how-to-guides/integrating-autoware/creating-maps/).
@@ -33,7 +41,7 @@ unzip -d ~/autoware_map ~/autoware_map/sample-map-planning.zip
     http://localhost:6080/vnc.html
     ```
 
-    Use the default password `openadkit` to access the visualizer. **It can take a few seconds to visualizer to start.**
+    Use the default password `openadkit` to access the visualizer. **It can take a few seconds for the visualizer to start.**
 
     > If your machine is on a remote server, you can access the visualizer by using its accessible IP address:
     >

doc_env/Dockerfile

@@ -7,12 +7,10 @@ RUN pip install --no-cache-dir \
     mkdocs-awesome-pages-plugin \
     mkdocs-exclude \
     mkdocs-macros-plugin \
-    mkdocs-same-dir \
     pymdown-extensions \
     python-markdown-math \
     mdx-truly-sane-lists \
-    plantuml-markdown \
-    mkdocs-mermaid2-plugin
+    plantuml-markdown
 
 EXPOSE 8000
 

doc_env/README.md

@@ -1,17 +1,17 @@
-# Openadkit: Containerized MkDocs Development
+# Open AD Kit: Containerized MkDocs Development
 
-This document explains how to set up a containerized development environment for MkDocs in the Openadkit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments.
+This document explains how to set up a containerized development environment for MkDocs in the Open AD Kit project using Docker and Makefile. The `doc_env/Dockerfile` and `Makefile` are designed to replicate the dependencies and configuration used in the project's GitHub Actions workflow, ensuring consistency between local development and CI/CD environments.
 
 ## TL;DR
 
-In the Openadkit project **root directory**:
+In the Open AD Kit project **root directory**:
 
 ```bash
 make prepare
 make serve
 ```
 
-Access the MkDocs development server at `http://localhost:8000`. To build the static site:
+Access the MkDocs development server at `http://localhost:8000/openadkit/`. To build the static site:
 
 ```bash
 make build
@@ -26,8 +26,9 @@ make build
 
 The `Makefile` simplifies common tasks for managing the MkDocs environment. Available commands:
 
-- `make prepare`: Builds the Docker image with required MkDocs dependencies.
-- `make serve`: Starts the MkDocs development server at `http://localhost:8000`.
+- `make prepare`: Rebuilds the Docker image with required MkDocs dependencies.
+- `make prepare-if-missing`: Reuses an existing `mkdocs-dev` image if present, otherwise builds it.
+- `make serve`: Starts the MkDocs development server at `http://localhost:8000/openadkit/`.
 - `make build`: Generates the static site in the `site/` directory with correct permissions.
 - `make clean`: Removes the `site/` directory to clean up build artifacts.
 - `make help`: Displays available commands.
@@ -36,19 +37,21 @@ Run `make help` to see all options.
 
 ## Setup and Usage
 
-1. **Build the Docker Image**
+1. **Prepare the Docker Image**
 
    Run the following command to build the Docker image:
 
    ```bash
    make prepare
    ```
 
-   This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes:
-   - Base image: `python:3.11-slim`
-   - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `mkdocs-same-dir`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown`, `mkdocs-mermaid2-plugin`
-   - Working directory: `/app`
-   - Exposed port: `8000`
+    This builds the `mkdocs-dev` image using the `doc_env/Dockerfile`, which includes:
+    - Base image: `python:3.11-slim`
+    - Installed MkDocs plugins: `mkdocs-material`, `mkdocs-awesome-pages-plugin`, `mkdocs-exclude`, `mkdocs-macros-plugin`, `pymdown-extensions`, `python-markdown-math`, `mdx-truly-sane-lists`, `plantuml-markdown`
+    - Working directory: `/app`
+    - Exposed port: `8000`
+
+    Use `make prepare-if-missing` only when you intentionally want to reuse an existing local image, such as during offline verification.
 
 2. **Run the Development Server**
 
@@ -58,7 +61,7 @@ Run `make help` to see all options.
    make serve
    ```
 
-   - Opens `http://localhost:8000` in your browser to view the live site.
+   - Opens `http://localhost:8000/openadkit/` in your browser to view the live site.
    - Changes to `docs/` or `mkdocs.yaml` trigger automatic reloading.
    - The current directory is mounted to `/app` in the container for live updates.
 
@@ -86,18 +89,13 @@ Run `make help` to see all options.
 
 - **File Permissions**: The `make build` command uses `--user $(id -u):$(id -g)` to ensure the `site/` directory has the same ownership as your host user, avoiding permission issues on Linux systems.
 - **Customizing Plugins**: Update both `doc_env/Dockerfile` and `mkdocs.yaml` if additional MkDocs plugins are needed.
-- **Optimizing Builds**: Use a `.dockerignore` file to exclude unnecessary files (e.g., `site/`, `.github/`) to reduce build time. Example `.dockerignore`:
-  ```
-  .github/
-  deployments/
-  site/
-  ```
 - **Cleaning Up Docker**: Use `docker system prune` to remove unused images and containers.
-- **Documentation**: Refer to `docs/dev/index.md` for additional development environment details.
+- **Documentation Source**: The published documentation lives under `docs/` and is configured by `mkdocs.yaml`.
 
 ## Troubleshooting
 
 - **Permission Issues**: If the `site/` directory has incorrect permissions, ensure `make build` is used instead of directly running `docker run ... mkdocs build`.
 - **Port Conflicts**: If port `8000` is in use, stop other services or change the port mapping (e.g., `-p 8001:8000` in the `make serve` command by editing the `Makefile`).
+- **Prepare Fails During Package Download**: If Docker cannot reach PyPI while building `mkdocs-dev`, rerun `make prepare` once network access is available. If you already have a suitable local image and only need to test docs content, use `make prepare-if-missing`.
 
-For further assistance, consult the main `README.md` or open an issue in the Openadkit repository.
+For further assistance, consult the main `README.md` or open an issue in the Open AD Kit repository.

docs/components/index.md

@@ -1,6 +1,6 @@
 # Components
 
-Open AD Kit is a component based project, which means that it is designed to be deployed on a variety of platforms with microservices architecture. Each **Autoware component** is designed to be independent and can be configured to work together to achieve a particular task, such as a simulation or a full autonomous driving stack.
+Open AD Kit is a component-based project designed to run on a variety of platforms with containerized services. Each **Autoware function** remains independently deployable, while the published images group closely related functions together where that keeps the runtime layout simpler.
 
 ![Granular Components](../assets/images/granular-components.png)
 
@@ -30,14 +30,10 @@ The planning component is responsible for planning the vehicle's path. Planning
 
 The control component is responsible for controlling the vehicle's actuators. Control component can be configured to use a variety of control algorithms, including **PID and MPC**. For more details, see the [Autoware control design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/control/).
 
-### Vehicle
+### Vehicle and System
 
-The vehicle component is responsible for managing the vehicle's state. Vehicle component can be configured to use a variety of vehicle algorithms, including **vehicle state estimation and vehicle control**. For more details, see the [Autoware vehicle design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/vehicle/).
+The `vehicle-system` image packages both the vehicle interface and system-level services used by the Open AD Kit deployments. On the functional side, the vehicle component manages vehicle-specific interfaces and state, while the system component provides health monitoring and related system services. For more details, see the [Autoware vehicle design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/components/vehicle/).
 
 ### API
 
-The API component is responsible for providing [AD API](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/) interface for the vehicle's state. API component can be configured to enable/disable various interfaces. For more details, see the [Autoware Interface design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/interfaces/).
-
-### System
-
-The system component is responsible for managing the vehicle's system. System component can be configured to use a variety of system algorithms, including **system health monitoring and system error handling**.
+The API component is responsible for providing [AD API](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-interfaces/ad-api/) interface for the vehicle's state. API component can be configured to enable or disable various interfaces. For more details, see the [Autoware Interface design document](https://autowarefoundation.github.io/autoware-documentation/main/design/autoware-architecture-v1/interfaces/).