docs(dev-mode): document branch preview setup

Author: werserk

docs/dev-mode-branch-preview.md

@@ -0,0 +1,89 @@
+# Branch Preview Dev Mode
+
+Branch Preview is a local maintainer tool for checking another git branch from the Hermes Web UI. It is intentionally hidden from ordinary users and should be treated as a developer/reviewer feature, not a normal application setting.
+
+## Who should use it
+
+Use Branch Preview only on trusted local instances where a super administrator is reviewing code changes.
+
+Ordinary users should not see this feature. Super administrators can find it under:
+
+```text
+Settings → Advanced → Developer tools → Branch preview
+```
+
+## Security model
+
+Branch Preview builds code from the selected branch inside a local worktree. Building untrusted branches can execute untrusted build scripts or dependencies.
+
+Keep it disabled unless all of these are true:
+
+- you trust the repository checkout;
+- you trust the branch or understand the risk;
+- the instance is local/private;
+- the current user is a super administrator.
+
+Client-side hiding is only UX. Server-side super-admin guards and persisted Dev Mode checks remain authoritative.
+
+## Requirements
+
+- Hermes Web UI is running from a local git checkout.
+- The server process can run `git` in that checkout.
+- The server process can create/remove worktrees under the active Hermes profile directory.
+- The user is `super_admin`.
+- `dev.enabled` is enabled before build/reset actions are allowed.
+
+Read-only branch listing/status can be available before `dev.enabled` is enabled so a maintainer can select a branch without a catch-22. Mutating actions still require persisted Dev Mode to be enabled.
+
+## Generic maintainer setup
+
+Use the normal branch names for your checkout. By default, Branch Preview falls back to `main`.
+
+Example profile config:
+
+```yaml
+dev:
+  enabled: true
+  review_base: main
+  preview_branch: main
+```
+
+Then open the Web UI as a super administrator and use:
+
+```text
+Settings → Advanced → Developer tools → Branch preview
+```
+
+## Unavailable states
+
+The UI may show a compact unavailable message instead of controls:
+
+- `not_git_repo` — the Web UI server is not running from a git checkout.
+- `repo_path_missing` — a future explicit repo path setting points to a missing checkout.
+- `disabled` — branch preview is disabled for this instance/user.
+
+When unavailable, the UI should not render branch/build/reset controls.
+
+## Troubleshooting
+
+1. Confirm the server working directory is a git checkout:
+
+   ```bash
+   git rev-parse --is-inside-work-tree
+   ```
+
+2. Confirm branches are visible:
+
+   ```bash
+   git for-each-ref --format='%(refname:short)' refs/heads refs/remotes
+   ```
+
+3. Confirm the profile has the intended base branch:
+
+   ```yaml
+   dev:
+     enabled: true
+     review_base: main
+   ```
+
+4. If build/reset buttons are disabled, save Dev Mode settings first. The UI switch edits draft state; build/reset use the persisted server config.

packages/client/src/i18n/locales/en.ts

@@ -219,6 +219,7 @@ export default {
       status: 'Show session status and queue',
       abort: 'Stop the active bridge run',
       queue: 'Queue a message behind the active run',
+      plan: 'Write a markdown implementation plan',
       clear: 'Clear the current display',
       clearHistory: 'Delete this session’s stored message history',
       title: 'Rename this session',
@@ -1327,46 +1328,6 @@ export default {
 
   // Changelog
   changelog: {
-    new_0_5_22_1: 'Fix Hermes session list API reading the Web UI local session store instead of the Hermes profile database',
-    new_0_5_23_1: 'Add bridge-only chat slash commands with localized command suggestions',
-    new_0_5_23_2: 'Persist command history for session replay without polluting model context, usage, or compression',
-    new_0_5_23_3: 'Isolate gateway profile environment variables to prevent credentials leaking across profiles',
-    new_0_5_23_4: 'Reserve the Web UI port during gateway allocation to avoid startup conflicts',
-    new_0_5_23_5: 'Fix self-update restart handling so successful helper exits are not reported as failures',
-    new_0_5_24_1: 'Align Bridge chat with API Server handling for multimodal input, system prompt, and workspace context',
-    new_0_5_25_1: 'Add group chat room reset and clone actions',
-    new_0_5_25_2: 'Make the Web UI state directory configurable for custom deployment layouts',
-    new_0_5_25_3: 'Add MiMo as a TTS provider in voice settings',
-    new_0_5_25_4: 'Fetch custom provider model lists through the backend to avoid browser CORS failures',
-    new_0_5_25_5: 'Fix tool approval flow for bridge sessions',
-    new_0_5_25_6: 'Remove the forced CLI platform hint from bridge prompts so custom media/file instructions are preserved',
-    new_0_5_25_7: 'Show base64 image content correctly in user message history',
-    new_0_5_25_8: 'Add Playwright browser tests, chat streaming contract coverage, provider model coverage, and coverage baseline',
-    new_0_5_26_1: 'Support Windows and local Markdown media paths in chat history and rendered messages',
-    new_0_5_26_2: 'Filter empty assistant history and clear stale compression status when a new run starts',
-    new_0_5_26_3: 'Add locked file writes for config and profile updates to reduce concurrent write corruption',
-    new_0_5_26_4: 'Add QQBot and DingTalk channel settings',
-    new_0_5_26_5: 'Make CLI port detection portable and improve mobile terminal drawer sizing',
-    new_0_5_26_6: 'Isolate Bridge profile environments and fix Hermes plugin discovery across Python environments',
-    new_0_5_26_7: 'Explain stopped gateway states with Web UI diagnostics and keep log loading state stable',
-    new_0_5_26_8: 'Fix session reset mode options, custom provider base URL handling, and dynamic deliver targets',
-    new_0_5_26_9: 'Add a local tool-call trace visibility toggle in the chat input bar',
-    new_0_5_26_10: 'Support Hermes Agent package installs when no source checkout is available',
-    new_0_5_26_11: 'Add xAI Grok OAuth login for SuperGrok subscription users and update Grok model presets',
-    new_0_5_26_12: 'Expand browser, chat streaming, provider, gateway, config, plugin, and Bridge test coverage',
-    new_0_5_27_1: 'Add session-level model settings for Bridge chats, with independent provider and model saved per session',
-    new_0_5_27_2: 'Right-click a Bridge session and choose Set Model to switch the model for that session',
-    new_0_5_27_3: 'Runs now validate the session model and fall back to the current default model when the saved model is unavailable',
-    new_0_5_27_4: 'Context compression now follows the current Profile default selected model by default',
-    new_0_5_30_1: 'Bridge chat now preserves structured history, fixing intermittent no-response and skipped tool execution caused by text-flattened tool history',
-    new_0_5_30_2: 'Group chat mention routing is more reliable for multiple agents, removes each agent’s own ＠ mention before delivery, and keeps user display names bound after refresh',
-    new_0_5_30_3: 'Model pages, chat model dropdowns, and session model selection now scope providers and models to the active Profile with accurate default markers',
-    new_0_5_30_4: 'Gateway management is simplified: the standalone Gateway page is removed, each Profile is checked for platform configuration before starting the needed gateway, and a lightweight gateway runner handles starts and restarts',
-    new_0_5_30_5: 'Improve Gateway startup across Docker, Termux, and Windows with runtime-lock handling, port-conflict cleanup, background execution, and restart support',
-    new_0_5_30_6: 'Harden Windows compatibility for path detection, file downloads, and job/update subprocesses so they no longer flash terminal windows',
-    new_0_5_30_7: 'Fix config writes and provider presets: validate .env keys, route FUN-Codex through the Responses API, and refresh Z.AI/GLM model lists',
-    new_0_5_30_8: 'Polish frontend details including collapsed sidebar layout, short group labels, sidebar divider, and conversation outline styling',
-    new_0_5_30_9: 'Context compression now follows Profile compression settings and hardens stale snapshots by reusing previous summaries with a safe tail instead of recompressing full history',
     new_0_5_31_1: "Harden Bridge broker restarts, fix final group-chat stream rendering, and add {'@'}all routing for group chat",
     new_0_5_31_2: 'File manager can copy absolute paths, and the mobile session drawer overlay no longer falls behind chat content',
     new_0_5_31_3: 'Profile selector now shows avatars, custom avatar uploads, runtime status modal, and gateway/profile restart actions',
@@ -1404,6 +1365,16 @@ export default {
     new_0_6_0_6: 'Update docs and website copy for account management, default credentials, account/Profile management, uploads/downloads, and bundled media skills',
     new_0_6_0_7: 'Add CLI maintenance commands for clearing login IP locks and resetting the default admin / 123456 login',
     new_0_6_0_8: 'Version 0.6.0 is the boundary between single-user and multi-user Web UI. If multi-user mode causes issues, please file an issue and roll back to the 0.5.35 single-user release if needed',
+    new_0_6_1_1: 'Session lists now show every Profile available to the account unless a Profile filter is explicitly selected, and CLI start/stop/status no longer print the node:sqlite experimental warning',
+    new_0_6_1_2: 'Clarify and confirmation replies now travel through the authenticated chat socket to the Hermes bridge, with response-path tests',
+    new_0_6_1_3: 'Navigation entries and chat session rows now use native links for open-in-new-tab, copy-link, and persistent collapsed sidebar behavior',
+    new_0_6_1_4: 'Session links no longer leak route Profile filters into the normal session list, and Open in new tab labels are localized',
+    new_0_6_1_5: 'Skills now read skills.external_dirs from the active Profile config, mark external skills, preserve local precedence, and resolve external files',
+    new_0_6_1_6: 'Login IP lockout now allows 10 failed attempts and the locked login screen shows clear-lock and reset-default-login recovery commands',
+    new_0_6_1_7: 'Mobile and background chat disconnects are treated as transient, then reconnect resumes the run state from the server',
+    new_0_6_1_8: 'Bridge tool marker flushing now persists partial tool-call marker prefixes at tool and run boundaries',
+    new_0_6_1_9: 'Profile-aware history actions now delete sessions with profile-qualified targets and refresh History when the global Profile changes',
+    new_0_6_1_10: 'The legacy AUTH_DISABLED bypass was removed for multi-user permissions, while AUTH_TOKEN remains supported',
 
   },
 }