@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/docs/CONTRACTS.md

@@ -0,0 +1,207 @@
+# 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/canonical-session-resolution.md`](rfcs/canonical-session-resolution.md):
+  proposed contract for resolving URL routes, query parameters, localStorage,
+  sidebar rows, and compression-lineage IDs to one canonical visible session
+  target. Start here for session routing, boot restore, stale parent, or
+  compression-tip selection changes.
+- [`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`, `geist-contrast`) 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`
+- <subsystem-specific documents>
+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.
+
+## Contract changes
+
+Changing contract documents, RFC guidance, or contract tests changes review
+expectations for future contributors. A PR that intentionally changes an
+existing contract should include a `Contract Change` section in its PR body with:
+
+- the previous contract,
+- the new contract,
+- the affected docs and tests,
+- the compatibility or migration reason.
+
+Contract tests and corresponding docs must move together. Tests that encode
+product semantics must not silently redefine the contract by asserting the
+opposite behavior without updating the public docs and naming the change in the
+PR body.
+
+The static tests for this guidance are advisory coverage. They pin contributor
+wording so the rule stays visible. This advisory coverage is not an automated
+policy gate; static coverage is not an automated policy gate and does not enforce
+PR-body content on GitHub. A future release-time or CI check could
+surface contract-affecting diffs whose PR body lacks `Contract Routing`, but this
+document only defines the review expectation.
+
+Release batches should list included contract-affecting PRs explicitly so
+reviewers can distinguish ordinary green-CI fixes from changes that update the
+project's product or runtime guardrails.
+
+## 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.
+- Contract-affecting PRs include `Contract Routing`; intentional contract
+  changes also include `Contract Change`.
+- 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.

package/vendor/agent-frontend-shell/docs/EXTENSIONS.md

@@ -0,0 +1,212 @@
+# WebUI Extensions
+
+Hermes WebUI supports a small, opt-in extension surface for self-hosted installs.
+It lets an administrator serve local static assets and inject same-origin CSS or
+JavaScript into the app shell without editing the WebUI source tree.
+
+> **Trust model — read this first.** Extensions execute with full WebUI session
+> authority. An extension JS file can call any API the logged-in user can call,
+> including reading conversation history, sending messages, modifying settings,
+> and triggering tool actions. **Only enable extensions you wrote yourself or
+> from sources you trust as much as the WebUI source itself.** If your WebUI is
+> shared with users you do not fully trust, do not enable extensions.
+> Do not point `HERMES_WEBUI_EXTENSION_DIR` at a user-writable directory.
+
+This is intentionally not a plugin marketplace or dependency system. It is a
+safe escape hatch for local dashboards, internal tooling, and workflow-specific
+panels that should not live in core Hermes WebUI.
+
+## What extensions can do
+
+Extensions can:
+
+- serve files from one configured local directory at `/extensions/...`
+- inject configured same-origin stylesheets into `<head>`
+- inject configured same-origin scripts before `</body>`
+- call the normal WebUI APIs available to the browser session
+
+Extensions cannot, by themselves:
+
+- bypass WebUI authentication
+- serve files outside the configured extension directory
+- load third-party scripts/styles through the built-in injection config
+- change Hermes Agent permissions, models, memory, or tools unless they call
+  existing authenticated APIs that already allow those changes
+
+## Configuration
+
+Extensions are disabled by default. Configure them with environment variables
+before starting the WebUI server. `HERMES_WEBUI_EXTENSION_DIR` must point to an
+existing directory before any script or stylesheet URLs are injected:
+
+```bash
+export HERMES_WEBUI_EXTENSION_DIR=/path/to/my-extension/static
+export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js
+export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css
+./start.sh
+```
+
+Multiple URLs may be comma-separated:
+
+```bash
+export HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/runtime.js,/extensions/app.js
+export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/base.css,/extensions/theme.css
+```
+
+## URL rules
+
+Injected asset URLs are deliberately restricted:
+
+- must be same-origin paths
+- must start with `/extensions/` or `/static/`
+- must not include a URL scheme, host, fragment, quote, angle bracket, newline,
+  NUL byte, or backslash
+
+Allowed examples:
+
+```text
+/extensions/app.js
+/extensions/app.css
+/extensions/app.js?v=1
+/static/theme.css
+```
+
+Rejected examples:
+
+```text
+https://example.com/app.js
+//example.com/app.js
+javascript:alert(1)
+/api/session
+/extensions/app.js#fragment
+```
+
+These restrictions keep the existing Content Security Policy intact and avoid
+turning the extension hook into a third-party script loader. Invalid configured
+URLs are ignored rather than injected.
+
+## Static file serving
+
+When `HERMES_WEBUI_EXTENSION_DIR` points at an existing directory, files under
+that directory are available below `/extensions/`:
+
+```text
+/path/to/my-extension/static/app.js  ->  /extensions/app.js
+/path/to/my-extension/static/ui.css  ->  /extensions/ui.css
+```
+
+The static handler is sandboxed:
+
+- path traversal is rejected, including encoded traversal
+- dotfiles and dot-directories are not served
+- symlinks that resolve outside the extension directory are rejected
+- missing or invalid extension directories behave as disabled
+- failures return a generic 404 without exposing local filesystem paths
+
+## Security notes
+
+Only enable extensions from directories you control. Extension JavaScript runs in
+the WebUI origin and can call the same authenticated WebUI APIs as the logged-in
+browser session.
+
+For shared or remotely exposed installations:
+
+- keep `HERMES_WEBUI_PASSWORD` enabled
+- bind to loopback unless you intentionally expose the service
+- review extension code before enabling it
+- prefer small, auditable extension files
+- avoid serving generated or user-writable directories as extension roots
+
+## Extension authoring guidance
+
+Extensions share the page with the WebUI app, so they should be additive and
+reversible. Prefer small, well-scoped DOM changes that can be removed or hidden
+without breaking the built-in Chat, Tasks, Settings, or session views.
+
+Recommended patterns:
+
+- create extension-specific containers with unique IDs or class prefixes
+- add UI next to existing views instead of replacing large app containers
+- keep event listeners scoped to extension-owned elements where possible
+- preserve built-in navigation behavior and restore any view state you change
+- use `hidden`, `aria-*`, and extension-scoped CSS for panels or overlays
+- guard initialization so reloading or re-injecting the script does not create
+  duplicate buttons, panels, timers, or event listeners
+
+Avoid destructive mutations such as replacing `document.body.innerHTML`,
+`main.innerHTML`, or other broad WebUI containers. Those patterns can remove or
+mask the app's existing panels and leave normal navigation unable to recover
+after an extension view is opened.
+
+For custom pages, prefer adding a dedicated panel and toggling it alongside the
+built-in views:
+
+```javascript
+(() => {
+  if (document.getElementById('my-extension-panel')) return;
+
+  const panel = document.createElement('section');
+  panel.id = 'my-extension-panel';
+  panel.className = 'main-view my-extension-panel';
+  panel.hidden = true;
+  panel.textContent = 'My extension page';
+
+  document.querySelector('main')?.appendChild(panel);
+
+  function showPanel() {
+    document.querySelectorAll('main > .main-view').forEach((view) => {
+      view.hidden = view !== panel;
+    });
+  }
+
+  // Wire showPanel() to an extension-owned button or menu item.
+})();
+```
+
+If host CSS overrides `[hidden]`, add an extension-scoped rule such as:
+
+```css
+.my-extension-panel[hidden] {
+  display: none !important;
+}
+```
+
+## Minimal example
+
+Create a local extension directory:
+
+```bash
+mkdir -p ~/.hermes/webui-extension
+cat > ~/.hermes/webui-extension/app.css <<'CSS'
+.my-extension-badge {
+  position: fixed;
+  right: 12px;
+  bottom: 12px;
+  padding: 6px 10px;
+  border-radius: 999px;
+  background: #202236;
+  color: #fff;
+  font: 12px system-ui, sans-serif;
+  z-index: 9999;
+}
+CSS
+cat > ~/.hermes/webui-extension/app.js <<'JS'
+(() => {
+  const badge = document.createElement('div');
+  badge.className = 'my-extension-badge';
+  badge.textContent = 'Extension loaded';
+  document.body.appendChild(badge);
+})();
+JS
+```
+
+Start WebUI with the extension enabled:
+
+```bash
+HERMES_WEBUI_EXTENSION_DIR=~/.hermes/webui-extension \
+HERMES_WEBUI_EXTENSION_STYLESHEET_URLS=/extensions/app.css \
+HERMES_WEBUI_EXTENSION_SCRIPT_URLS=/extensions/app.js \
+./start.sh
+```
+
+Open the WebUI and confirm the badge appears.

package/vendor/agent-frontend-shell/docs/ISSUES.md

@@ -0,0 +1,23 @@
+# Upstream Issues — Root Cause Analysis
+
+## #1256: Browser tools fail with "Playwright not installed"
+
+### Root Cause
+The check lives in **hermes-agent** (upstream), not hermes-webui:
+
+```
+hermes-agent/tools/browser_tool.py → check_browser_requirements()
+```
+
+`check_browser_requirements()` does not recognize CDP (Chrome DevTools Protocol) mode — it only looks for a local Playwright/Puppeteer install. When the agent runs in CDP mode (connecting to an existing browser), the check still fails.
+
+### WebUI side
+The WebUI already passes `CLI_TOOLSETS` correctly per-request. The `enabled_toolsets` field in the cron/chat config is dynamic and works as intended.
+
+### Fix required
+The fix must happen in `hermes-agent/tools/browser_tool.py`:
+- `check_browser_requirements()` should skip the Playwright check when CDP mode is configured
+- Or add a `BROWSER_MODE=cdp` env var that bypasses the local browser requirement
+
+### Workaround
+Use `CLOUD_BROWSER=true` or configure `browser.base_url` to point to a remote CDP endpoint. This bypasses the local Playwright requirement.

package/vendor/agent-frontend-shell/docs/UIUX-GUIDE.md

@@ -0,0 +1,196 @@
+# 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.
+
+Visible interim assistant progress is part of the live conversation timeline,
+not raw debug detail. Compact Activity may collapse tool arguments, long tool
+results, and low-level reasoning detail, but it must not make concise
+user-visible progress text available only inside a collapsed disclosure.
+
+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`, `nous`, and `geist-contrast` / Geist Contrast. `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.