diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 27c7f010..551fcb17 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -8,6 +8,7 @@ Use this page when you know what you want to run and need the command shape. For
 |---|---|---|
 | Check the install | `nanobot --version` | If this fails, try `python -m nanobot --version` |
 | Create or refresh config | `nanobot onboard` | Creates `~/.nanobot/config.json` and `~/.nanobot/workspace/` |
+| Refresh config non-interactively | `nanobot onboard --refresh` | Preserves existing values and adds missing default fields without prompting |
 | Use guided setup | `nanobot onboard --wizard` | Best when you prefer prompts over hand-editing JSON |
 | Open the browser workbench | `nanobot webui` | Prepares local WebUI settings, starts the gateway, and opens the browser |
 | Check config without calling a model | `nanobot status` | Summarizes the selected config, workspace, active model, and providers |
@@ -58,6 +59,7 @@ with `--background`, use `nanobot gateway stop`.
 | Command | Description |
 |---|---|
 | `nanobot onboard` | Initialize or refresh the default config and workspace |
+| `nanobot onboard --refresh` | Refresh an existing config without prompting, preserving existing values |
 | `nanobot onboard --wizard` | Use the interactive setup wizard |
 | `nanobot onboard --config <path> --workspace <path>` | Initialize or refresh a specific instance |
 
diff --git a/docs/quick-start.md b/docs/quick-start.md
index 74a55f0d..f1752048 100644
--- a/docs/quick-start.md
+++ b/docs/quick-start.md
@@ -115,7 +115,7 @@ Initialization creates:
 | `~/.nanobot/config.json` | Main settings file for providers, models, channels, tools, gateway, and API |
 | `~/.nanobot/workspace/` | Agent workspace for memory, sessions, heartbeat tasks, skills, and artifacts |
 
-If you already have a config, `nanobot onboard` can refresh missing default fields without overwriting your existing values.
+If you already have a config, `nanobot onboard` can refresh missing default fields without overwriting your existing values. Use `nanobot onboard --refresh` to do the same refresh without an interactive prompt.
 
 ## 3. Configure a Provider
 
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 5b0504e3..70b940e8 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -111,10 +111,10 @@ Common config mistakes:
 To refresh missing defaults without overwriting existing settings, run:
 
 ```bash
-nanobot onboard
+nanobot onboard --refresh
 ```
 
-When prompted about overwriting the config, choose the option that keeps current values and merges missing defaults.
+For an interactive choice between resetting and refreshing, run `nanobot onboard` and choose the option that keeps current values and merges missing defaults.
 
 ## Provider and Model Problems