docs: initialize NVM once per shell session

AGENTS.md

@@ -90,7 +90,7 @@ Do not manually edit generated output or installed dependencies:
 
 - Node.js must use the `lts/jod` NVM alias, as declared in `.nvmrc`.
 - Documented commands target Bash on Linux, macOS, or Windows WSL. Use Bash explicitly for agent commands; fish's `nvm.fish` is unavailable in Bash.
-- Before every npm command, explicitly load Bash NVM and select Node in the same shell session: `export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"; . "$NVM_DIR/nvm.sh" && nvm use lts/jod && npm run build`. Do not rely on `.bashrc` loading in noninteractive shells or fall back to system Node.
+- Initialize Bash NVM once at the start of each shell session: `export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"; . "$NVM_DIR/nvm.sh" && nvm use` from the project root. `nvm use` reads `lts/jod` from `.nvmrc`. Reuse that initialized shell for subsequent npm commands. If a tool starts a fresh shell for each execution, initialize each new shell or use a persistent shell; environment changes do not carry between independent shells. Stop if initialization fails. Do not rely on `.bashrc` loading in noninteractive shells or fall back to system Node.
 - If `${NVM_DIR:-$HOME/.nvm}/nvm.sh` is missing, ask the user for permission before installing Bash NVM. Follow `docs/development.md#shell-and-nvm-setup` after approval. Keep existing fish NVM separate.
 - Install exact dependencies: `npm ci`
 - Start the Ionic development server: `npm start`

README.md

@@ -38,49 +38,48 @@ For desktop development, also install:
 These commands target **Bash** (Linux, macOS, or Windows WSL). From fish,
 start `bash` first. Follow the [shell and NVM setup](docs/development.md#shell-and-nvm-setup)
 before continuing. If Bash NVM is missing, agents must ask permission before
-installing it. `.nvmrc` declares `lts/jod`:
+installing it. `.nvmrc` declares `lts/jod`.
+
+Initialize NVM once at the start of each Bash session, from the project root:
 
 ```bash
 export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
-. "$NVM_DIR/nvm.sh"
+. "$NVM_DIR/nvm.sh" && nvm use
-nvm install lts/jod
-nvm use lts/jod && npm ci
 ```
 
-Each npm command block loads Bash NVM explicitly and selects the required Node
+On first setup, run `nvm install` after loading NVM if the required Node version
-version, including in fresh noninteractive shells.
+is not installed. Stop if setup fails; do not use the system Node as a fallback.
+The commands below reuse this session. Repeat the setup when opening a new shell.
+
+Install the project dependencies:
+
+```bash
+npm ci
+```
 
 If Ionic CLI is not already installed:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm install --global @ionic/cli
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm install --global @ionic/cli
 ```
 
 ## Web development
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm start
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm start
 ```
 
 Build the Angular application:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run build
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm run build
 ```
 
 Run linting and tests:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run lint
-. "$NVM_DIR/nvm.sh"
+npm test
-nvm use lts/jod && npm run lint
-nvm use lts/jod && npm test
 ```
 
 `npm test` starts Karma in its configured mode and may remain open in watch mode.
@@ -96,18 +95,14 @@ For VS Code, the recommended extension is `esbenp.prettier-vscode`. Use **Format
 The Tauri CLI is available through:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run tauri -- <command>
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm run tauri -- <command>
 ```
 
 For example:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run tauri -- dev
-. "$NVM_DIR/nvm.sh"
+npm run tauri -- build
-nvm use lts/jod && npm run tauri -- dev
-nvm use lts/jod && npm run tauri -- build
 ```
 
 > Tauri development intentionally uses `http://localhost:8103`. The current `npm start` script does not explicitly select that port, so verify that Ionic is listening on `8103` when using `tauri dev`.

docs/development.md

@@ -27,18 +27,21 @@ NVM. After approval, follow the official
 Use the default `~/.nvm` location, or set `NVM_DIR` to your existing Bash NVM
 installation. Keep an existing fish installation separate.
 
-After NVM is installed, install the required Node release from the project root:
+Initialize NVM once at the start of each Bash session, from the project root:
 
 ```bash
 export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
-. "$NVM_DIR/nvm.sh"
+. "$NVM_DIR/nvm.sh" && nvm use
-nvm install lts/jod
 ```
 
-Every npm command block below explicitly loads NVM and selects `lts/jod`.
+`nvm use` reads the required `lts/jod` version from `.nvmrc`. On first setup,
-This also works in noninteractive Bash sessions that do not load `.bashrc`.
+run `nvm install` after loading NVM if that version is not installed.
-Run each block from the project root. Stop if loading NVM or selecting Node fails;
+Stop if loading NVM or selecting Node fails; do not fall back to system Node.
-do not fall back to the system Node version.
+
+Run the commands below in that initialized shell. Repeat setup for each new
+shell, including noninteractive shells that do not load `.bashrc`. Agents should
+reuse an initialized shell for subsequent npm commands; separate command
+executions do not necessarily share environment changes.
 
 Angular 22 requires TypeScript 6.0 and Node.js 22.22.3 or newer on the
 Node.js 22 line. If your installed `lts/jod` is older, run `nvm install lts/jod`
@@ -47,17 +50,13 @@ after loading Bash NVM.
 Install exact project dependencies with:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm ci
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm ci
 ```
 
 If needed, install Ionic CLI globally:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm install --global @ionic/cli
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm install --global @ionic/cli
 ```
 
 The committed `.nvmrc` uses the named `lts/jod` alias. Do not replace it with another Node release or add `.tool-versions` unless the team intentionally changes version-management tools.
@@ -71,17 +70,13 @@ Install Rust stable and the Tauri 2 prerequisites for your operating system. `sr
 Start the Ionic development server:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm start
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm start
 ```
 
 Build the Angular application:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run build
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm run build
 ```
 
 The production web output is generated under `www/`. Do not edit that directory manually.
@@ -140,10 +135,8 @@ which proposes incompatible downgrades of Angular and the test tooling.
 Run Tauri commands through the npm script:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run tauri dev
-. "$NVM_DIR/nvm.sh"
+npm run tauri build
-nvm use lts/jod && npm run tauri dev
-nvm use lts/jod && npm run tauri build
 ```
 
 Tauri development intentionally expects the frontend at `http://localhost:8103`. `devUrl` tells Tauri where to connect, and `beforeDevCommand` runs `npm run ng -- serve --host=0.0.0.0 --port=8103` to serve the frontend on the matching port without opening a browser. This uses the project's Angular CLI and does not require a global Ionic CLI installation. Keep these settings aligned when changing Tauri or serve configuration.
@@ -158,12 +151,10 @@ load these values from `.env` files. Keep private keys and passwords outside the
 repository.
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
-. "$NVM_DIR/nvm.sh"
 export TAURI_SIGNING_PRIVATE_KEY="$HOME/.tauri/myapp.key"
 # For a key without a password:
 export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""
-nvm use lts/jod && npm run tauri build
+npm run tauri build
 ```
 
 For a password-protected key, replace the empty-password export with a hidden

docs/testing.md

@@ -12,22 +12,19 @@ as the app rather than installing an older nested copy.
 
 These examples target Bash and run from the project root. Complete the
 [shell and NVM setup](development.md#shell-and-nvm-setup) first. Agents must ask
-permission before installing missing Bash NVM. Each npm block loads NVM explicitly.
+permission before installing missing Bash NVM. Initialize NVM once per Bash
+session as described there, then run the commands below in that same shell.
 
 Run the interactive test suite:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm test
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm test
 ```
 
 Run the configured non-watching CI test mode:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm test -- --configuration=ci
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm test -- --configuration=ci
 ```
 
 The test environment requires an available Chrome installation. Test coverage output, when enabled by the test runner, is written under `coverage/app/`.
@@ -35,9 +32,7 @@ The test environment requires an available Chrome installation. Test coverage ou
 Run the suite once in headless Chrome with a coverage report:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm test -- --watch=false --browsers=ChromeHeadless --code-coverage
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm test -- --watch=false --browsers=ChromeHeadless --code-coverage
 ```
 
 If Chrome is not auto-detected, set `CHROME_BIN` to its executable path
@@ -53,17 +48,13 @@ spies and signals to isolate assignments, confirmation, and role swaps.
 Lint TypeScript and Angular templates:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run lint
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm run lint
 ```
 
 Build the production Angular application:
 
 ```bash
-export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+npm run build
-. "$NVM_DIR/nvm.sh"
-nvm use lts/jod && npm run build
 ```
 
 Check Rust changes from the Tauri directory: