feat(nodeup): standardize actionable error messages with hints (#293)

## Summary
- standardize all `NodeupError` messages to `<cause>. Hint: <next
action>`
- keep JSON error envelope schema stable (`kind`, `message`,
`exit_code`) while improving message text
- migrate nodeup command/runtime error paths to actionable hints
(toolchain/run/show/which/self/installer/release-index/etc.)
- update integration tests for new message wording and hint presence
- update nodeup docs/contracts/public docs to reflect the new
error-message behavior

## Validation
- cargo fmt --all
- cargo test -p nodeup
- cargo test

## Notes
- clap-generated parser errors are intentionally unchanged

Author: kdy1

apps/public-docs/nodeup.mdx

@@ -69,6 +69,7 @@ nodeup override set lts --path /path/to/project
 - `--output human|json` is available for management commands.
 - Human mode uses pretty `tracing` logs by default.
 - JSON mode writes machine payloads to stdout and keeps logs off by default unless explicitly enabled.
+- Handled failures use an actionable message shape: `<cause>. Hint: <next action>`.
 - `completions` always writes raw completion scripts to stdout, even when `--output json` is set.
 
 ## Shell completions

crates/nodeup/README.md

@@ -50,6 +50,7 @@ If no selector resolves, commands fail with deterministic `not-found` errors.
   - success payloads are written to stdout as JSON
   - handled failures are written to stderr as JSON envelopes
     - fields: `kind`, `message`, `exit_code`
+    - `message` follows `<cause>. Hint: <next action>` for actionable recovery guidance
   - default logging is off unless explicitly enabled via `RUST_LOG`
 - `completions` command:
   - always writes raw completion script text to stdout
@@ -102,6 +103,8 @@ cargo test
   - verify `<path>/bin/node` exists before `toolchain link`
 - JSON parsing issues in automation:
   - use `--output json` and keep `RUST_LOG` unset (or `off`) to avoid log noise
+- Error troubleshooting:
+  - follow the `Hint:` action in the error message first, then rerun with `RUST_LOG=nodeup=debug` when deeper diagnostics are needed
 
 ## Documentation Links
 

crates/nodeup/src/commands/run_cmd.rs

@@ -28,8 +28,9 @@ pub fn execute(
     app: &NodeupApp,
 ) -> Result<i32> {
     if command.is_empty() {
-        return Err(NodeupError::invalid_input(
-            "nodeup run requires delegated command arguments",
+        return Err(NodeupError::invalid_input_with_hint(
+            "Missing delegated command arguments for `nodeup run`",
+            "Use `nodeup run [--install] <runtime> <command> [args...]`.",
         ));
     }
 
@@ -42,11 +43,13 @@ pub fn execute(
             if install {
                 app.installer.ensure_installed(version, &app.releases)?;
             } else {
-                return Err(NodeupError::not_found(format!(
-                    "Runtime {} is not installed. Re-run with --install or run nodeup toolchain \
-                     install {}",
-                    version, runtime
-                )));
+                return Err(NodeupError::not_found_with_hint(
+                    format!("Runtime {version} is not installed"),
+                    format!(
+                        "Install it with `nodeup toolchain install {runtime}` or retry with \
+                         `nodeup run --install {runtime} ...`."
+                    ),
+                ));
             }
         }
     }
@@ -59,11 +62,17 @@ pub fn execute(
 
     let executable = resolved.executable_path(&app.store, delegated_command);
     if !executable.exists() {
-        return Err(NodeupError::not_found(format!(
-            "Command '{}' is not available in runtime {}",
-            delegated_command,
-            resolved.runtime_id()
-        )));
+        return Err(NodeupError::not_found_with_hint(
+            format!(
+                "Command '{delegated_command}' is not available in runtime {}",
+                resolved.runtime_id()
+            ),
+            format!(
+                "Check available commands with `nodeup which --runtime {} {delegated_command}` or \
+                 pick a runtime that provides it.",
+                resolved.runtime_id()
+            ),
+        ));
     }
 
     info!(