From 715017924cef56b8654d0ad9fe8aca4acb848445 Mon Sep 17 00:00:00 2001 From: nesquena-hermes <[email protected]> Date: Mon, 18 May 2026 03:45:42 +0000 Subject: [PATCH] Stage 382: PR #2503 --- AGENTS.md | 26 ++- CHANGELOG.md | 4 + CONTRIBUTING.md | 18 ++- README.md | 11 +- THEMES.md | 11 +- docs/CONTRACTS.md | 173 ++++++++++++++++++++ docs/UIUX-GUIDE.md | 191 +++++++++++++++++++++++ docs/docker.md | 9 +- docs/rfcs/hermes-run-adapter-contract.md | 7 +- docs/troubleshooting.md | 2 +- 10 files changed, 433 insertions(+), 19 deletions(-) create mode 100644 docs/CONTRACTS.md create mode 100644 docs/UIUX-GUIDE.md diff --git a/AGENTS.md b/AGENTS.md index a916be04..6b902daf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,8 @@ Before making changes, read: 1. `README.md` 2. `CONTRIBUTING.md` -3. `CHANGELOG.md` +3. `docs/CONTRACTS.md` +4. `CHANGELOG.md` For architecture, testing, or setup work, also read the matching reference: @@ -19,6 +20,10 @@ For architecture, testing, or setup work, also read the matching reference: - `TESTING.md` for local verification commands and manual test guidance - `docs/onboarding.md` for first-run onboarding behavior - `docs/troubleshooting.md` for diagnostic flows +- `docs/rfcs/README.md` for larger RFCs and state/durability contracts + +For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before +changing layout, interaction flow, themes, chat rendering, or composer chrome. ## Onboarding and reinstall support @@ -39,15 +44,22 @@ Follow that checklist's safety rules: ## Contribution style -- Keep changes focused on one logical problem. -- Prefer the existing Python + vanilla JavaScript structure over new - dependencies or build steps. +- Keep one logical change per PR; split unrelated refactors or cleanup. +- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched + subsystem before editing. +- Prefer the existing Python + vanilla JavaScript structure. Do not add + dependencies, build tools, frameworks, or long-lived processes without clear + justification and a rollback story. - Update docs when changing setup, onboarding, runtime behavior, architecture, - or testing guidance. + testing guidance, or user-facing workflows. - Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or documentation changes that should be release-note ready. -- For UI or UX changes, follow `CONTRIBUTING.md`: include before/after evidence - and test relevant responsive states. +- For UI or UX changes, include before/after evidence and test relevant + desktop, narrow, and mobile states. +- For behavior changes, add or update automated tests where practical and list + the manual verification performed. +- For runtime, streaming, recovery, replay, compression, or sidebar metadata + changes, name the state layer being mutated and prove the relevant invariant. ## Local state and secrets diff --git a/CHANGELOG.md b/CHANGELOG.md index e9e06bb3..e1773aac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ - **PR #2499** by @franksong2702 — Keep server-idle session rows from inheriting stale local streaming fields during sidebar optimistic merging, so PWA/browser caches cannot keep a completed session's spinner alive after `/api/sessions` reports no active stream or pending user message. - **PR #2501** (closes #1855) — Short-circuit the `resolve_model_provider` stage in `POST /api/chat/start` (and sibling chat-handler call sites) when the request already carries an explicit `(model, model_provider)` pair and the model isn't `@provider:model`-qualified. The new fast path in `_resolve_compatible_session_model_state()` returns the inputs verbatim without calling `get_available_models()` — that catalog rebuild can do network I/O (custom OpenAI-compat `/models`, OpenRouter `/models`, LM Studio probes, credential-pool refresh) under an RLock thundering-herd guard and was observed wedging a single request for 115 seconds in a production-grade local deployment. The recurrence captured via the PR #1911 stage diagnostics confirmed the wedge sat entirely in `resolve_model_provider` while every other stage completed in <5 ms. Users behind default-60s reverse proxies (nginx / Apache / Caddy / Cloudflare) were seeing a `502 Proxy Error` while the WebUI eventually completed the run anyway, creating a duplicate-send risk if the user retried in the browser. The slow path is preserved for the inputs that genuinely need it: bare/un-qualified models without a stored `model_provider` (cross-provider repair), `@provider:model`-qualified strings (active-provider validation per #1253), and empty models (default-model lookup). 14 new regression tests in `tests/test_issue1855_resolve_model_provider_fast_path.py` cover both directions — fast-path skips, slow-path still fires — including a static check that the short-circuit precedes the catalog call in source order. +### Documentation + +- **PR #2503** by @franksong2702 (refs #2502) — Add `docs/CONTRACTS.md` as a public contributor-facing routing index that points UI/UX, runtime/state, and onboarding/setup changes to the relevant public docs (DESIGN.md, AGENTS.md, RFCs, troubleshooting) before contributors edit code or open PRs. Also adds `docs/UIUX-GUIDE.md` synthesizing the calm-developer-console UI/UX principles from DESIGN.md / README.md / THEMES.md / `docs/ui-ux/` into one contributor guide, refreshes the README and THEMES.md skin lists to cover all ten built-in skins (`catppuccin` + `nous`), and tightens the AGENTS.md / CONTRIBUTING.md contribution-style notes for state-layer and evidence requirements. Docs-only — no runtime or maintainer-policy changes. + ## [v0.51.88] — 2026-05-18 — Release BL (stage-381 — 3-PR security + UX + lineage batch — session-bound CSRF tokens for unsafe browser requests + quoted-reply selected-text composer append + compression-continuation sidebar collapse) ### Security diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4a37c512..e84e7730 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,22 @@ Thanks for contributing. Hermes WebUI is intentionally simple to work on: Python on the server, vanilla JS in the browser, no build step, no bundler, no frontend framework. The best pull requests preserve that simplicity while solving a real problem cleanly. +## Before You Start + +- Read [`AGENTS.md`](AGENTS.md) if an AI assistant is doing or helping with the + change. +- Read [`docs/CONTRACTS.md`](docs/CONTRACTS.md) and any linked contract/RFC for + the subsystem you will touch. +- For UI or UX work, read [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md) + and [`DESIGN.md`](DESIGN.md). +- For runtime, streaming, recovery, replay, compression, context reconstruction, + or session metadata work, start with [`docs/rfcs/README.md`](docs/rfcs/README.md) + and the relevant RFC listed there. + +Use those documents as review guardrails: keep the change scoped, preserve the +no-build-step architecture, update docs/changelog when behavior changes, include +UI evidence for UI changes, and add tests for behavior changes where practical. + ## Two Paths to a Strong Pull Request ### Path 1: Small, Focused Changes @@ -60,7 +76,7 @@ There is currently no PR template in this repo, so include the important section If the change is user-visible, include screenshots or a short video. -For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images will likely be ignored, or closed in a regular maintainer sweep without review. +For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images may not receive meaningful review until that evidence is added. ### 4. AI Usage Disclosure diff --git a/README.md b/README.md index 783cabd2..9086bd21 100644 --- a/README.md +++ b/README.md @@ -467,10 +467,13 @@ Production data and real cron jobs are never touched. Current snapshot: - CDN resources pinned with SRI integrity hashes ### Themes -- 7 built-in themes: Dark (default), Light, Slate, Solarized Dark, Monokai, Nord, OLED -- Switch via Settings panel dropdown (instant live preview) or `/theme` command +- Appearance is split into two axes: Theme (`system`, `dark`, `light`) and Skin + (`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, `charizard`, + `sienna`, `catppuccin`, `nous`) +- Switch via Settings -> Appearance (instant live preview) or `/theme ` - Persists across reloads (server-side in settings.json + localStorage for flicker-free loading) -- Custom themes: define a `:root[data-theme="name"]` CSS block and it works — see [THEMES.md](THEMES.md) +- Skins use `data-skin` plus CSS variables; dark mode resolves through the + `.dark` class, not a `data-theme` custom-theme axis — see [THEMES.md](THEMES.md) ### Settings and configuration - **Hermes Control Center** (sidebar launcher button) -- Conversation tab (export/import/clear), Preferences tab (model, send key, theme, language, all toggles), System tab (version, password) @@ -556,6 +559,8 @@ State lives outside the repo at `~/.hermes/webui/` by default - `CHANGELOG.md` -- release notes per sprint - `SPRINTS.md` -- forward sprint plan with CLI + Claude parity targets - `THEMES.md` -- theme system documentation, custom theme guide +- `docs/CONTRACTS.md` -- project contract/RFC/design index for contributors and agents +- `docs/UIUX-GUIDE.md` -- UI/UX principles sourced from existing design docs and visual inventories - `docs/docker.md` -- Docker compose setup, common failures, and bind-mount migration - `docs/supervisor.md` -- launchd, systemd, supervisord, runit, and s6 process-supervisor setup - `docs/onboarding.md` -- first-run wizard, provider setup, local model server Base URLs, and safe re-runs diff --git a/THEMES.md b/THEMES.md index 466259b9..017d8a9f 100644 --- a/THEMES.md +++ b/THEMES.md @@ -4,7 +4,7 @@ Hermes Web UI splits **appearance** into two independent pickers: - **Theme** — the mode: `System`, `Dark`, or `Light`. Drives the background, text, surface, and chrome colors. -- **Skin** — the accent palette: eight named skins ship built-in. Drives only +- **Skin** — the accent palette: ten named skins ship built-in. Drives only the `--accent` family (active states, links, focus rings, primary actions). You pick one of each and they combine, so the look adapts to your environment @@ -15,13 +15,14 @@ without losing your favorite accent — pure CSS, no Python changes needed. ## Switching Appearance **Settings panel:** Click the gear icon → **Appearance**. The **Theme** card -toggles Light/Dark/System; the **Skin** grid offers eight accent palettes. +toggles Light/Dark/System; the **Skin** grid offers ten accent palettes. Preview is instant — the UI updates as you click. **Slash command:** Type `/theme ` in the composer. The command accepts both theme names (`system`, `dark`, `light`) and skin names (`default`, `ares`, -`mono`, `slate`, `poseidon`, `sisyphus`, `charizard`, `sienna`). It updates the -matching axis and leaves the other one alone. +`mono`, `slate`, `poseidon`, `sisyphus`, `charizard`, `sienna`, +`catppuccin`, `nous`). It updates the matching axis and leaves the other one +alone. **Persistence:** Both choices are stored in `localStorage` for flicker-free loading, and saved server-side via `POST /api/settings` (under `theme` and @@ -54,6 +55,8 @@ absent for light. System mode tracks the OS preference at runtime. | **Sisyphus** | Vivid purple. Distinctive without being loud. | | **Charizard** | Warm orange. Energetic and easy on the eyes. | | **Sienna** | Warm clay and sand earth palette. Soft and natural. | +| **Catppuccin** | Catppuccin Latte/Mocha palette with Mauve accent. | +| **Nous** | Steel-blue accent with dashed technical surfaces. | Each skin defines paired light + dark variants so it reads cleanly on either theme. The skin is applied as `data-skin=""` on `` (the default diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md new file mode 100644 index 00000000..4911487b --- /dev/null +++ b/docs/CONTRACTS.md @@ -0,0 +1,173 @@ +# Project Contracts + +This document is a contributor-facing index for existing Hermes WebUI contracts, +RFCs, design constraints, and review expectations. It does not replace the +source documents and it does not mark proposals as implemented. Follow each +linked document's status and scope. + +Use this file when starting a change so the relevant public contract is visible +before code is edited. This first version focuses on documentation routing; it +does not change runtime behavior, maintainer policy, bot behavior, or CI gates. + +## Start here + +- [`AGENTS.md`](../AGENTS.md): repository entry point for AI assistants, + public-safety rules, and the short redline checklist. +- [`CONTRIBUTING.md`](../CONTRIBUTING.md): contribution style, verification, + PR description expectations, UI evidence, and project-specific constraints. +- [`README.md`](../README.md): product overview, quick start, architecture map, + feature inventory, and docs index. +- [`CHANGELOG.md`](../CHANGELOG.md): release-note-ready history. Update it when + maintainers should carry the change into release notes. + +## Runtime, durability, and state contracts + +- [`docs/rfcs/webui-run-state-consistency-contract.md`](rfcs/webui-run-state-consistency-contract.md): + proposed consistency rules for current WebUI streaming, recovery, replay, + model-context reconstruction, compression, UI scene/cache, and sidebar metadata + repairs. Start here for narrow fixes that keep the existing WebUI execution + path. +- [`docs/rfcs/hermes-run-adapter-contract.md`](rfcs/hermes-run-adapter-contract.md): + proposed event/control contract, runtime-state ownership matrix, + acceptance-test catalog, and reversible migration gates for moving WebUI + execution behind an adapter boundary. Use this for adapter-seam, control-plane, + runner, sidecar, or execution-ownership work; do not treat it as authorization + to implement those slices. +- [`docs/rfcs/turn-journal.md`](rfcs/turn-journal.md): proposed crash-safe + write-ahead journal for browser-originated chat turns. +- [`docs/rfcs/README.md`](rfcs/README.md): RFC conventions and current RFC index. + +When a change touches streaming, recovery, replay, compression, context +reconstruction, cancellation, approval/clarify, session metadata, or run state, +read the relevant RFC before editing. In the PR description, name the state layer +or event/control surface affected and include a regression test or manual +verification for the relevant invariant. + +Proposed RFCs are review guardrails, not implementation authorization. Do not +implement RFC fragments unless the task or tracking issue explicitly asks for +that slice. + +## UI, UX, and theme contracts + +- [`DESIGN.md`](../DESIGN.md): design tokens and the current calm-console + direction: conversation first, quiet metadata, restrained accents, and + progressive disclosure for debugging detail. +- [`docs/UIUX-GUIDE.md`](UIUX-GUIDE.md): contributor-facing synthesis of the + repository's UI/UX principles, sourced from existing project docs and code + comments. +- [`docs/ui-ux/index.html`](ui-ux/index.html): message-area inventory wired to + the real app stylesheet. +- [`docs/ui-ux/two-stage-proposal.html`](ui-ux/two-stage-proposal.html): + existing two-stage chat UX proposal for issue #536. +- [`THEMES.md`](../THEMES.md): theme and skin guidance; the core palette + variable contract lives in `static/style.css`. + +Current appearance has a theme axis (`light`, `dark`, `system`) and a separate +skin axis (`default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, +`charizard`, `sienna`, `catppuccin`, `nous`) in `static/boot.js` and +`static/style.css`. Do not follow stale `data-theme`-only theme guidance unless +the current code and tests prove that model still applies. + +For UI or UX work, include before/after evidence, verify relevant responsive +states, and prefer stable class/data hooks over one-off visual behavior. + +## Choosing the relevant contract + +Before editing, identify which contract family the task exercises. This is a +routing check, not a request to read every document in the repository. Read the +documents that match the touched subsystem. + +Use this lightweight note in an issue comment, draft PR, task note, or AI-agent +handoff when it helps clarify scope: + +```markdown +## Contract Routing + +Task type: +Touched areas: +Relevant public docs: +- `AGENTS.md` +- `CONTRIBUTING.md` +- `docs/CONTRACTS.md` +- +Scope boundaries: +Evidence needed before claiming done: +``` + +For small, obvious fixes, keep this short. The goal is to avoid routing mistakes, +not to create process overhead. + +## PR preparation checklist + +Before opening or updating a PR, verify `CONTRIBUTING.md` against the actual PR +body. This checklist applies even when code and tests are already done. + +Required checks: + +- The PR solves one logical problem. +- The PR body contains all required sections from `CONTRIBUTING.md`: + `Thinking Path`, `What Changed`, `Why It Matters`, `Verification`, + `Risks / Follow-ups`, and `Model Used`. +- `Model Used` discloses provider/model and notable agent/tool use, or says + `None -- human-authored`. +- UI/UX changes include before/after evidence and responsive-state coverage. +- Runtime/streaming changes name the state layer or invariant being changed and + list the regression or manual invariant check. +- Onboarding/setup validation used isolated `HERMES_HOME` and + `HERMES_WEBUI_STATE_DIR`, unless the human operator explicitly requested real + state. +- Docs and `CHANGELOG.md` updates are either included or explicitly not needed. +- After the GitHub write, read the PR back and verify the headings rendered as + intended. + +Green CI plus a focused diff is not sufficient if the PR description or evidence +does not match the touched subsystem. + +## Setup, onboarding, and operational references + +- [`TESTING.md`](../TESTING.md): automated test command and manual browser test + plan. +- [`ARCHITECTURE.md`](../ARCHITECTURE.md): API, module layout, and design + constraints. +- [`docs/onboarding.md`](onboarding.md): first-run wizard and provider setup. +- [`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md): safety + rules for assistant-led install, reinstall, bootstrap, provider setup, local + model setup, Docker onboarding, and WSL onboarding. +- [`docs/docker.md`](docker.md): Docker compose setup, common failures, and + bind-mount migration. +- [`docs/troubleshooting.md`](troubleshooting.md): diagnostic flows for common + failures. +- [`docs/EXTENSIONS.md`](EXTENSIONS.md): administrator-controlled WebUI + extension injection. + +## Quick redline checklist + +Before opening a change for review, confirm: + +- The change solves one logical problem; unrelated refactors are split out. +- `AGENTS.md`, this index, and any linked contract for the touched subsystem were + read before editing. +- Behavior, setup, architecture, testing, or workflow changes update the relevant + docs; release-note-ready changes update `CHANGELOG.md`. +- UI/UX changes include before/after evidence and cover relevant desktop, + narrow, and mobile states. +- Runtime, streaming, recovery, replay, compression, or sidebar changes state + which layer they mutate and include a regression for the invariant. +- New dependencies, build tools, frameworks, or long-lived processes are avoided + unless the benefit and rollback story are explicit. +- Onboarding/setup validation uses isolated `HERMES_HOME` and + `HERMES_WEBUI_STATE_DIR` unless the human operator explicitly asks to use real + state. +- Secrets, private paths, local-only workflows, and personal notes stay out of + tracked docs and examples. + +## Future evolution + +This index is not intended to make the first contract set final. Future PRs may +add, revise, split, or retire contracts when real issues, implementation changes, +RFC decisions, contributor feedback, or review experience show that guidance is +incomplete or stale. + +Potential follow-up areas include session import/export, cron, extensions, +security boundaries, Docker/runtime isolation, and lightweight checks that keep +key contract links from drifting. diff --git a/docs/UIUX-GUIDE.md b/docs/UIUX-GUIDE.md new file mode 100644 index 00000000..7f9edc4e --- /dev/null +++ b/docs/UIUX-GUIDE.md @@ -0,0 +1,191 @@ +# UI/UX Guide + +This document summarizes UI/UX principles that are already visible in the +repository. It is a contributor guide, not a new design proposal. Source +documents include [`DESIGN.md`](../DESIGN.md), [`README.md`](../README.md), +[`THEMES.md`](../THEMES.md), [`docs/ui-ux/index.html`](ui-ux/index.html), +[`docs/ui-ux/two-stage-proposal.html`](ui-ux/two-stage-proposal.html), and +design comments in `static/style.css`. + +Use this guide when a change touches layout, chat rendering, composer chrome, +navigation, theme/skin behavior, responsive behavior, or visual hierarchy. For +purely backend changes, use the runtime/state contracts instead. + +## Product shape + +Hermes WebUI is a browser workbench for Hermes Agent with near-CLI parity and a +simple implementation shape: Python on the server, vanilla JavaScript in the +browser, no build step, no bundler, and no frontend framework. + +The primary layout is three-panel: + +- left sidebar for sessions and navigation, +- center panel for chat, +- right panel for workspace file browsing and previews. + +Model, profile, workspace, attachments, voice input, context usage, Stop, and +Send controls live in the composer footer. Settings and session-level tools live +in the Hermes Control Center. Preserve this shape unless the change explicitly +justifies a different interaction model. + +## Core feeling: calm developer console + +The main artifact is the conversation. Tool calls, thinking traces, context +compaction records, token usage, runtime status, and other internals are useful, +but they are transcript metadata. They should sit below user and assistant prose +in visual priority. + +Prefer: + +- quiet surfaces, +- clear spacing, +- restrained accent use, +- progressive disclosure for debugging detail, +- legible text over decorative chrome. + +Avoid turning the interface into a demo page of colorful cards. Errors, +approvals, and other action-required states may be prominent because the user +must notice and respond to them. + +## Conversation hierarchy + +A chat turn should read as one coherent story: + +1. User message: right-aligned, compact bubble. +2. Assistant content: left-aligned, prose-first, not a heavy bubble. +3. Tool, thinking, progress, and context traces: quiet disclosure rows inside or + adjacent to the assistant turn. +4. Raw logs and verbose details: hidden until explicitly expanded. + +Do not render every internal event as a first-class chat card. A turn that used +many tools should summarize the work as inspectable activity, not make the user +read a stack of unrelated-looking cards. + +## Tool, thinking, and activity traces + +Tool cards are debug event rows, not chat messages. Show the icon, name, short +target or preview, and status first. Arguments, result snippets, and long logs +belong behind expansion, with result snippets truncated and full output behind a +show-more affordance where needed. + +Thinking and context cards should share the quiet metadata visual family. They +should not overpower assistant prose. Collapsed activity summaries should be +terse, for example `Activity: 4 tools`, and should not duplicate the thinking +area, list every tool name in the summary, or add redundant trailing count +badges. + +The existing two-stage proposal in `docs/ui-ux/two-stage-proposal.html` records a +compatible direction for long turns: live work can be grouped as a worklog, then +settled history can collapse while the final answer reads as the calm +conclusion. Treat that page as an existing proposal, not as shipped behavior +unless the code and tests prove it is implemented. + +## Typography and content + +Use split typography intentionally: + +- assistant prose uses the same system sans stack as the rest of the UI by + default (`--font-ui` in `static/style.css`), +- editorial serif assistant prose is historical/proposal or skin-scoped only; + do not reintroduce a global assistant serif without explicit design approval + plus code and test evidence, +- user bubbles and functional UI also use the system sans stack unless a scoped + skin intentionally overrides typography, +- monospace is for code, file paths, commands, tool names, and compact metadata. + +Keep scale tight. Avoid introducing near-duplicate one-off font sizes, colors, +radius values, or spacing values when an existing token works. + +## Color, depth, and shape + +Use one accent at a time. Semantic colors are for semantic state: success, +warning, error, and info. Do not mix many bright colors decoratively in the same +viewport. + +Use almost no shadows in the transcript. Reserve shadows for popovers, +dropdowns, modals, and floating controls. Chat cards should usually use either a +subtle border or a subtle tint, not aggressive combinations of both. + +Avoid stacks of nested rounded rectangles. Rows and list items should feel +compact; panels and cards may be slightly rounder; true pills are reserved for +chips and badges. + +## Composer and controls + +The composer is the command surface. Keep it legible, stable, and focused: + +- no theatrical hover scaling for routine controls, +- no ambient chrome that crowds the model/workspace/profile controls, +- no new footer buttons on tight layouts without a clear value tradeoff, +- keep Stop/Send and context feedback easy to find while composing. + +When adding a control, consider where users will find it on both wide desktop and +mobile. If a setting or quota/control surface does not fit in the composer, route +it through the appropriate Control Center panel instead of squeezing the footer. + +## Responsive behavior + +Mobile is not an afterthought. The repository documents a responsive layout with +a hamburger sidebar, mobile-accessible top tabs, a right-edge file slide-over, +full-height chat/composer behavior on phones, and touch-friendly controls. + +For UI changes, verify the relevant states: + +- wide desktop, +- ordinary laptop width, +- narrow/mobile width, +- open and closed side panels when relevant, +- long chat content and live streaming when relevant. + +Controls should remain usable at touch sizes, and mobile navigation should not +steal chat height unnecessarily. + +## Themes and skins + +Theme and skin work should use the existing variable system. `THEMES.md` points +to the core palette variables in `static/style.css`; skin comments in the CSS +show the expected pattern for full palette rewrites and accent-only changes. + +Current implementation has two appearance axes, sourced from `static/boot.js`: +`theme` is only `light`, `dark`, or `system` and resolves to the `.dark` class +for dark mode; `skin` is a separate axis applied with `data-skin` and currently +includes `default`, `ares`, `mono`, `slate`, `poseidon`, `sisyphus`, +`charizard`, `sienna`, `catppuccin`, and `nous`. `slate` is both an active skin +and a legacy theme-name migration target; `solarized`, `monokai`, `nord`, and +`oled` are legacy theme names mapped to current theme/skin pairs. Do not follow +stale `data-theme`-only guidance without first proving the current +`static/boot.js`, `static/index.html`, and `static/style.css` contracts still +support it. + +Do not hardcode new colors, radii, shadows, or typography values into isolated +components when a token or existing variable can carry the intent. If a token is +missing, explain why a new one is needed. + +## Evidence expected for UI changes + +For any interface or interaction change: + +- include before/after images or a short video, +- mention the tested viewport sizes and responsive states, +- reference the affected visual inventory or design source when applicable, +- add or update tests for behavior, state persistence, or regression-prone DOM + structure where practical, +- keep stable class or data hooks when they help future visual regression tests. + +## Do / don't summary + +Do: + +- keep the conversation primary, +- collapse noisy internals by default when settled, +- make debugging details accessible without making them visually dominant, +- use existing tokens, variables, and component patterns, +- protect action-required states such as errors and approvals. + +Don't: + +- make every tool call look like a separate chat message, +- add decorative color or motion without a user-facing reason, +- introduce a frontend framework, bundler, or build step for ordinary UI work, +- hide important recovery, error, or approval state, +- treat proposal mockups as shipped behavior without code/test evidence. diff --git a/docs/docker.md b/docs/docker.md index f238773b..da5bb702 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -42,7 +42,14 @@ docker compose up -d open http://localhost:8787 ``` -That's it. Your existing `~/.hermes` directory is mounted, your `~/workspace` is browsable, and the WebUI auto-detects your UID/GID from the mounted volume. +That's it for a real personal Docker install. Your existing `~/.hermes` +directory is mounted, your `~/workspace` is browsable, and the WebUI +auto-detects your UID/GID from the mounted volume. + +For troubleshooting, reinstall, or onboarding reproduction trials, do not mount +your real `~/.hermes` unless you intentionally want to test real state. Use an +isolated Hermes home and follow +[`docs/onboarding-agent-checklist.md`](onboarding-agent-checklist.md) instead. ## What goes wrong (and how to fix it) diff --git a/docs/rfcs/hermes-run-adapter-contract.md b/docs/rfcs/hermes-run-adapter-contract.md index 6c9f3f1e..aba03a65 100644 --- a/docs/rfcs/hermes-run-adapter-contract.md +++ b/docs/rfcs/hermes-run-adapter-contract.md @@ -25,8 +25,11 @@ runtime boundary instead of remaining scattered through the main WebUI request process. This document is intentionally a reviewable spec and migration gate. It should be -accepted before any implementation PR changes the streaming hot path, introduces a -runner process, or moves a new approval / clarify / queue / goal control path. +accepted before any implementation PR for this adapter direction changes the +streaming hot path, introduces a runner process, or moves a new approval / +clarify / queue / goal control path. Narrow current-path bug fixes that do not +introduce a new runtime boundary can still proceed under the WebUI run-state +consistency contract and the relevant issue scope. ## Problem diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 0a9a4c45..3617aeba 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -2,7 +2,7 @@ Concrete diagnostic flows for the most common failure modes when running Hermes WebUI. Each entry has the symptom, the diagnostic commands you should run *before* opening an issue, and the fix that has worked for past reporters. -If your symptom isn't listed and the diagnostics don't narrow it down, file a bug at https://github.com/nesquena/hermes-webui/issues — include the **full output** of every command in the relevant section. +If your symptom isn't listed and the diagnostics don't narrow it down, file a bug at https://github.com/nesquena/hermes-webui/issues — include the relevant command output after redacting secrets, private paths, full `.env` files, full `auth.json` files, cookies, tokens, and password hashes. ---