diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd32fd3..76761ec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,18 @@
 ---
 
 
+## [v0.49.0] First-run onboarding wizard (PR #285)
+
+- **One-shot bootstrap and first-run setup wizard** (PR #285): New users are greeted with a guided onboarding overlay on first load. The wizard checks system status, configures a provider (OpenRouter, Anthropic, OpenAI, or custom OpenAI-compatible endpoint), sets a workspace and optional password, and marks setup as complete — all without leaving the browser.
+  - `bootstrap.py`: one-shot CLI bootstrap that writes `~/.hermes/config.yaml` and `~/.hermes/.env` from flags; idempotent and safe to re-run
+  - `api/routes.py`: `/api/onboarding/status` (GET) and `/api/onboarding/complete` (POST) endpoints; real provider config persistence to `config.yaml` + `.env`
+  - `static/onboarding.js`: full wizard JS module — step navigation, provider dropdown, model selector, API key input, Back/Continue flow, i18n support
+  - `static/index.html`: onboarding overlay HTML shell + `<script src="/static/onboarding.js">` load
+  - `static/i18n.js`: 40+ onboarding keys added to all 5 locales (en, es, de, zh-Hans, zh-Hant)
+  - `static/boot.js`: on load, fetches `/api/onboarding/status` and opens wizard when `completed=false`
+  - Wizard does NOT show when `onboarding_completed=true` in settings
+  - 14 new tests in `tests/test_onboarding.py`; 693 tests total (up from 679)
+
 ## [v0.48.2] Provider/model mismatch warning (PR #283, fixes #266)
 
 - **Provider mismatch warning** (PR #283): WebUI now warns when you select a model from a provider different from the one Hermes is configured for, instead of silently failing with a 401 error.
diff --git a/ROADMAP.md b/ROADMAP.md
index 761bfd0..21392a8 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -3,8 +3,9 @@
 > Goal: Full 1:1 parity with the Hermes CLI experience via a clean dark web UI.
 > Everything you can do from the CLI terminal, you can do from this UI.
 >
-> Last updated: v0.48.2 (April 12, 2026) — 679 tests, 679 passing
-> Tests: 604 total (604 passing, 0 failures)
+> Last updated: v0.49.0 (April 12, 2026) — 693 tests, 693 passing
+> Onboarding MVP now writes real Hermes provider config from the Web UI for OpenRouter, Anthropic, OpenAI, and custom OpenAI-compatible endpoints.
+> Tests: 693 total (693 passing, 0 failures)
 > Source: <repo>/
 
 ---
@@ -48,6 +49,7 @@
 | v0.48.0 | Gateway session sync | Real-time Telegram/Discord/Slack sessions in sidebar via SSE + DB polling (#274 @bergeouss); +10 tests | 658 |
 | v0.48.1 | Table inline formatting | `inlineMd()` in table cells — **bold**, *italic*, `code`, links render correctly (PR #278); 0 new tests | 658 |
 | v0.48.2 | Provider mismatch warning | Toast warning + auth_mismatch error type for provider/model mismatches (#283, fixes #266); +21 tests | 679 |
+| v0.49.0 | First-run onboarding wizard | One-shot bootstrap + guided setup wizard; provider config persisted to config.yaml + .env; OpenRouter/Anthropic/OpenAI/Custom; wizard hidden after completion (#285); +14 tests | 693 |
 | v0.32 | Auto-compaction handling | Compression detection, /compact command, real context window indicator | 424 |
 | v0.33 | /insights sync | Opt-in state.db sync so `hermes /insights` includes WebUI sessions | 424 |
 | v0.34 | Sprint 26 — Pluggable themes | Dark, Light, Slate, Solarized, Monokai, Nord; settings unsaved-changes guard; /theme command | 433 |
diff --git a/SPRINTS.md b/SPRINTS.md
index e2d115f..7f9b34d 100644
--- a/SPRINTS.md
+++ b/SPRINTS.md
@@ -1163,8 +1163,8 @@ New test cases in `tests/test_sprint26.py`:
 
 ---
 
-*Last updated: April 10, 2026*
-*Current version: v0.45.0 | 604 tests*
+*Last updated: April 12, 2026*
+*Current version: v0.49.0 | 693 tests*
 *Next sprint: Sprint 24 (Web Polish + Bug Fix Pass)*
 *Horizon sprint: Sprint 25 (macOS Desktop Application)*
 *Docs sweep policy: update markdown proactively during PR reviews and after significant releases*
diff --git a/TESTING.md b/TESTING.md
index ce22e7b..f4be53a 100644
--- a/TESTING.md
+++ b/TESTING.md
@@ -8,7 +8,7 @@
 > Prerequisites: SSH tunnel is active on port 8786. Open http://localhost:8786 in browser.
 > Server health check: curl http://127.0.0.1:8786/health should return {"status":"ok"}.
 >
-> Automated tests: 679 total (679 passing, 0 skipped, 0 known failures)
+> Automated tests: 693 total (693 passing, 0 skipped, 0 known failures). Includes onboarding coverage for bootstrap/static wizard presence, real provider config persistence (`config.yaml` + `.env`), and the `/api/onboarding/*` backend.
 > Run: `pytest tests/ -v --timeout=60`
 
 ---
diff --git a/static/index.html b/static/index.html
index 23e61d6..3fec4a5 100644
--- a/static/index.html
+++ b/static/index.html
@@ -14,7 +14,7 @@
 <body>
 <div class="layout">
   <aside class="sidebar">
-    <div class="sidebar-header"><div class="logo">H</div><div><h1 style="margin:0;font-size:15px;font-weight:700;letter-spacing:-.01em">Hermes</h1><div style="font-size:10px;color:var(--muted);opacity:.8;margin-top:1px">v0.48.2</div></div></div>
+    <div class="sidebar-header"><div class="logo">H</div><div><h1 style="margin:0;font-size:15px;font-weight:700;letter-spacing:-.01em">Hermes</h1><div style="font-size:10px;color:var(--muted);opacity:.8;margin-top:1px">v0.49.0</div></div></div>
     <div class="sidebar-nav">
       <button class="nav-tab active" data-panel="chat" data-label="Chat" onclick="switchPanel('chat')" title="Chat" data-i18n-title="tab_chat"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg></button>
       <button class="nav-tab" data-panel="tasks" data-label="Tasks" onclick="switchPanel('tasks')" title="Tasks" data-i18n-title="tab_tasks"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="4" width="18" height="18" rx="2"/><line x1="16" y1="2" x2="16" y2="6"/><line x1="8" y1="2" x2="8" y2="6"/><line x1="3" y1="10" x2="21" y2="10"/></svg></button>