docs: add first-run onboarding guide

[franksong2702]

Thinking Path

• First-run setup is one of the highest-leverage parts of Hermes WebUI because users hit it before they know the Hermes/WebUI boundary.
• The wizard already handles provider selection, local endpoint probing, workspace setup, password setup, and OAuth/terminal-first fallbacks, but that behavior was scattered across README text, code, and issue comments.
• Docker local-model users especially need explicit Base URL guidance because localhost inside a container is not the host running LM Studio or Ollama.
• A docs-only guide is the lowest-risk way to make onboarding testable, supportable, and easier to validate during a fresh install.

What Changed

• Added docs/onboarding.md with a step-by-step first-run guide covering:
  • install path choices
  • safe isolated re-runs of onboarding
  • what the wizard checks
  • provider groups and keyless local providers
  • Docker/local model server Base URL rules
  • workspace and password setup
  • files written by the wizard
  • issue-reporting diagnostics
• Linked the new guide from the README quick-start/onboarding section and Docs list.
• Added a README pointer to the community native Windows guide tracked in [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952.
• Corrected stale README / .env.example state-dir documentation from ~/.hermes/webui-mvp to the current ~/.hermes/webui default.

Why It Matters

This gives new users a single source to read before or during first-run setup, and gives Discord/support replies a concrete link instead of repeating scattered setup advice. It also makes fresh-install validation easier because users can re-run onboarding safely with isolated HERMES_HOME and HERMES_WEBUI_STATE_DIR instead of deleting their real ~/.hermes state.

Verification

• git diff --cached --check
• Confirmed staged scope is docs/config-template only: .env.example, README.md, docs/onboarding.md
• Confirmed local relative docs referenced by the new guide exist: docs/docker.md, docs/troubleshooting.md, docs/wsl-autostart.md

No runtime tests were run because this PR changes documentation and comments only.

Risks / Follow-ups

• The native Windows links are intentionally framed as community-maintained and unsupported by the official bootstrap.
• More screenshots could be added later, but this PR keeps the first slice text-only and low-risk.

Model Used

Provider: OpenAI
Model: Codex (GPT-5)
Notable tool use: local git/gh workflow, repository search, docs-only static verification.

[nesquena-hermes]

Thanks @franksong2702 — onboarding writeups are exactly the kind of low-risk, high-leverage docs that pay back on every Discord support thread. Reading the diff at 7aa1a5f4 plus the live state-dir code at api/config.py:42 to sanity-check the corrections.

Summary

Docs-only PR. Adds docs/onboarding.md (181 lines covering install paths, safe wizard re-runs with isolated HERMES_HOME / HERMES_WEBUI_STATE_DIR, provider groups, local-server Base URL rules, workspace step, password step, files written, and issue-reporting diagnostics). README gets a pointer into it from the quick-start section and the Docs list. .env.example and README's environment-variable table fix a stale ~/.hermes/webui-mvp reference to the current ~/.hermes/webui. CI green on all three Python versions.

Stale-default correction is correct

api/config.py:42 defines the actual default:

STATE_DIR = (
    Path(os.getenv("HERMES_WEBUI_STATE_DIR", str(HOME / ".hermes" / "webui")))
    .expanduser()
    .resolve()
)

So ~/.hermes/webui (not webui-mvp) is what the running app uses. The README env-var table and .env.example comment were both lying about that, and docs/onboarding.md would have inherited the same lie if it cited the old path. Good catch.

Content notes

A few things I'd consider tweaking before this is the canonical onboarding doc, but none are blockers:

1. HERMES_WEBUI_SKIP_ONBOARDING=1 (line ~62-63 of the new doc): worth confirming that env var exists. grep -rn "HERMES_WEBUI_SKIP_ONBOARDING" api/ on master returns no hits; the wizard skip path is controlled by get_onboarding_status() in api/onboarding.py, not an env-var flag. If the env var isn't honored, this line will frustrate exactly the managed-hosting operators it's aimed at. Either add the env-var support in a follow-up PR or drop that sentence.

2. Docker host.docker.internal table is exactly right and answers the most common Discord question — the LM Studio / Ollama Base URL confusion. The note that localhost inside the container is the container itself, not the host, is the single most useful sentence in the file.

3. HERMES_WEBUI_DEFAULT_WORKSPACE table row says default is ~/workspace. That matches api/config.py but I'd cross-check whether the Docker default differs — docs/docker.md mentions /workspace as the browsable path, which the new guide also calls out correctly.

4. README [Feature] Native Windows support — working setup & guide (no Docker/WSL2) #1952 link is the right framing: community-maintained, tracked-in-issue, not officially supported. Keeps the door open without forcing a Windows-native bootstrap into the supported surface.

Verification scope is appropriate

PR body lists git diff --cached --check, confirms relative docs (docs/docker.md, docs/troubleshooting.md, docs/wsl-autostart.md) exist, and skips runtime tests. That's the right scope — there's no Python or JS surface that could be touched here, so adding pytest runs would only catch staged whitespace problems the lint already catches.

Minor polish suggestions (non-blocking)

• The --brief section uses backtick code fences inside a numbered list; on the GitHub renderer that occasionally looks off in narrow viewports, but it's fine in the standalone file view.
• "Specialized" provider group table mentions "Xiaomi MiMo" — that's recent (commit 128e734d), so it's accurate, just worth knowing the doc will need maintenance as the provider list grows.
• Consider adding a short "If the wizard never appears at all, check HERMES_WEBUI_SKIP_ONBOARDING and the existence of a previous config.yaml" note — that's the other common failure shape.

LGTM as a docs-only first slice. Catches the most common new-user pitfalls (Docker localhost, deleting ~/.hermes, native Windows expectations) in one place. The webui-mvp → webui correction alone justifies the merge.

[franksong2702]

Thanks for flagging the HERMES_WEBUI_SKIP_ONBOARDING=1 line. I re-checked the PR head and current code after the latest release train; the env var is implemented, so I think the onboarding guide can keep that sentence.

Evidence:

• api/onboarding.py reads HERMES_WEBUI_SKIP_ONBOARDING in get_onboarding_status() and treats 1 / true / yes as an unconditional operator skip.
• api/onboarding.py also guards apply_onboarding_setup() with the same env var, so a stale frontend call will not overwrite config files when the operator has requested skip-onboarding.
• bootstrap.py documents the same operator escape hatch, and tests/test_sprint39.py covers the unconditional skip behavior.

So no PR change from me on that point. The rest of the comments look non-blocking to me.

[nesquena-hermes]

Shipped via stage-337 → master in v0.51.44 (commit f00cb74f). Thanks @franksong2702 — onboarding writeups are the highest-leverage docs we can ship.

You were right about HERMES_WEBUI_SKIP_ONBOARDING=1 — I re-verified grep -rn HERMES_WEBUI_SKIP_ONBOARDING /home/hermes/hermes-webui-public/api/ and the env var IS implemented (api/onboarding.py:808 + :898, bootstrap.py:68, covered by tests/test_sprint39.py). Your doc is accurate as-shipped.

The ~/.hermes/webui-mvp → ~/.hermes/webui correction is going to save support questions for months. Docker localhost-vs-container-host clarification is the most useful single sentence in the new file.

Release: https://github.com/nesquena/hermes-webui/releases/tag/v0.51.44