[Doc] Clarify README install and quick start guidance (#1453)

- separate npm installation from repo checkout quick start
- make ROS 2 environment sourcing explicit in prerequisites and examples
- add direct GitHub install instructions
- clarify that GitHub installs usually build from source
- limit prebuilt binary claims to the published npm package
- improve docs and message-generation wording
- align npmjs README with the updated package-consumer guidance

Fix: #1452

Author: minggangw

README.md

@@ -20,39 +20,66 @@ rclnodejs.init().then(() => {
 });
 ```
 
+This example assumes your ROS 2 environment is already sourced.
+
 ## Documentation
 
 - Get started:
   [Installation](#installation), [Quick Start](#quick-start), [Tutorials](./tutorials/)
 - Reference:
-  [API Documentation](#api-documentation), [Using TypeScript](#using-rclnodejs-with-typescript), [ROS2 Interface Message Generation](#ros2-interface-message-generation)
+  [API Documentation](#api-documentation), [Using TypeScript](#using-rclnodejs-with-typescript), [ROS 2 Interface Message Generation](#ros-2-interface-message-generation)
 - Features and examples:
   [rclnodejs-cli](#rclnodejs-cli), [Electron-based Visualization](#electron-based-visualization), [Observable Subscriptions](#observable-subscriptions), [Performance Benchmarks](#performance-benchmarks)
 - Project docs:
   [Efficient Usage Tips](./docs/EFFICIENCY.md), [FAQ and Known Issues](./docs/FAQ.md), [Building from Scratch](./docs/BUILDING.md), [Contributing](./docs/CONTRIBUTING.md)
 
 ## Installation
 
+Choose the path that matches how you plan to use rclnodejs:
+
+- Install from npm: add rclnodejs to your own application.
+- Quick Start: run the examples from this repository checkout.
+
 ### Prerequisites
 
 - [Node.js](https://nodejs.org/en/) version >= 16.13.0
-- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
+- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html)
 
-### Install rclnodejs
+Before installing, building, or running rclnodejs, source your ROS 2 environment:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+```
+
+### Install from npm
+
+Use this path if you want to depend on rclnodejs from your own ROS 2 Node.js application.
 
 ```bash
 npm i rclnodejs
 ```
 
-> **Note:** To install rclnodejs from GitHub: add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
+After installation, use the example at the top of this README as a minimal publisher, or continue with [Quick Start](#quick-start) to run the examples in this repository.
+
+### Install from GitHub
+
+Use this path only if you need a branch or commit that is not yet published to npm.
+
+GitHub installs normally build from source. The published npm package includes prebuilt binaries for supported Linux targets, but this repository does not track those prebuilt artifacts.
+
+```bash
+npm install RobotWebTools/rclnodejs#<branch>
+```
+
+Or add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependency section.
 
 > **Docker:** For containerized development, see the included [Dockerfile](./Dockerfile) for building and testing with different ROS distributions and Node.js versions.
 
 See the [features](./docs/FEATURES.md) and try the [examples](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) to get started.
 
 ### Prebuilt Binaries
 
-rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This significantly speeds up installation and reduces dependencies.
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing the published npm package.
 
 **Supported Platforms:**
 
@@ -74,25 +101,27 @@ npm install rclnodejs
 
 ## Quick Start
 
-1. Source your ROS 2 environment.
+Use these steps if you are working from this repository checkout and want to run one of the included examples.
 
-```bash
-source /opt/ros/<distro>/setup.bash
-```
+These steps assume the [installation prerequisites](#prerequisites) are already satisfied and your ROS 2 environment has been sourced.
 
-2. Install the repository dependencies.
+1. Install the repository dependencies from the project root.
 
 ```bash
 npm install
 ```
 
-3. Run a publisher example from this checkout.
+2. Run a publisher example from this checkout.
 
 ```bash
 node example/topics/publisher/publisher-example.js
 ```
 
-You should see messages being published once per second. Explore more runnable examples in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) and step-by-step guides in [tutorials/](./tutorials/).
+You should see messages being published once per second.
+
+If you want to build an application instead of running the repository examples, install rclnodejs into your own project with [Install from npm](#install-from-npm) and start from the sample code near the top of this README.
+
+Explore more runnable examples in [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example) and step-by-step guides in [tutorials/](./tutorials/).
 
 ## rclnodejs-cli
 
@@ -102,7 +131,7 @@ See the rclnodejs-cli repository for installation instructions and the current c
 
 ## API Documentation
 
-API documentation is available [online](https://robotwebtools.github.io/rclnodejs/docs/index.html) or generate locally with `npm run docs`.
+API documentation is available [online](https://robotwebtools.github.io/rclnodejs/docs/index.html). To generate it locally from this repository checkout, run `npm run docs`.
 
 ## Electron-based Visualization
 
@@ -164,7 +193,7 @@ obsSub.observable
 
 See the [Observable Subscriptions Tutorial](./tutorials/observable-subscriptions.md) for more details.
 
-## ROS2 Interface Message Generation
+## ROS 2 Interface Message Generation
 
 ROS client libraries convert IDL message descriptions into target language source code. rclnodejs provides the `generate-ros-messages` script to generate JavaScript message interface files and TypeScript declarations.
 
@@ -178,7 +207,7 @@ stringMsgObject.data = 'hello world';
 
 ### Running Message Generation
 
-Run the message generation script when new ROS packages are installed:
+Run the message generation script in your project when new ROS packages are installed:
 
 ```bash
 npx generate-ros-messages

scripts/npmjs-readme.md

@@ -14,24 +14,38 @@ rclnodejs.init().then(() => {
 });
 ```
 
+This example assumes your ROS 2 environment is already sourced.
+
 ## Installation
 
 ### Prerequisites
 
 - [Node.js](https://nodejs.org/en/) version >= 16.13.0
-- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html) - **Don't forget to [source the setup file](https://docs.ros.org/en/jazzy/Tutorials/Beginner-CLI-Tools/Configuring-ROS2-Environment.html#source-the-setup-files)**
+- [ROS 2 SDK](https://docs.ros.org/en/jazzy/Installation.html)
+
+Before installing or running rclnodejs, source your ROS 2 environment:
+
+```bash
+source /opt/ros/<distro>/setup.bash
+```
 
 ### Install rclnodejs
 
 ```bash
 npm i rclnodejs
 ```
 
-- **Note:** To install rclnodejs from GitHub, add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependencies.
+To install from GitHub instead of npm, run:
+
+```bash
+npm install RobotWebTools/rclnodejs#<branch>
+```
+
+Or add `"rclnodejs":"RobotWebTools/rclnodejs#<branch>"` to your `package.json` dependencies.
 
 ### Prebuilt Binaries
 
-rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation.
+rclnodejs ships with prebuilt native binaries for common Linux configurations since `v1.5.2`, eliminating the need for compilation during installation. This applies to supported Linux environments when installing the published npm package.
 
 **Supported Platforms:**
 
@@ -52,21 +66,24 @@ npm install rclnodejs
 ## Documentation and Examples
 
 - API documentation: [robotwebtools.github.io/rclnodejs/docs](https://robotwebtools.github.io/rclnodejs/docs/index.html)
+- Tutorials: [tutorials/](https://github.com/RobotWebTools/rclnodejs/tree/develop/tutorials)
 - JavaScript examples: [example/](https://github.com/RobotWebTools/rclnodejs/tree/develop/example)
 - TypeScript demos: [ts_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/ts_demo)
 - Electron demos: [electron_demo/](https://github.com/RobotWebTools/rclnodejs/tree/develop/electron_demo)
 - Companion CLI: [rclnodejs-cli](https://github.com/RobotWebTools/rclnodejs-cli/)
 
 ## Message Generation
 
-rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun:
+rclnodejs generates JavaScript message interfaces and TypeScript declarations during installation for `rclnodejs > 1.5.0`. If you install additional ROS packages later, rerun the generator in your project:
 
 ```bash
 npx generate-ros-messages
 ```
 
 Generated files are written to `<your-project>/node_modules/rclnodejs/generated/`.
 
+This step is only needed after adding ROS packages that were not present when rclnodejs was installed.
+
 ## Using rclnodejs with TypeScript
 
 TypeScript declaration files are included in the package. In most projects, configuring your `tsconfig.json` is sufficient: