hermes-webui/docs/CONTRACTS.md

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: repository entry point for AI assistants, public-safety rules, and the short redline checklist.
• CONTRIBUTING.md: contribution style, verification, PR description expectations, UI evidence, and project-specific constraints.
• README.md: product overview, quick start, architecture map, feature inventory, and docs index.
• 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: 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: 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: proposed crash-safe write-ahead journal for browser-originated chat turns.
• docs/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 tokens and the current calm-console direction: conversation first, quiet metadata, restrained accents, and progressive disclosure for debugging detail.
• docs/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: message-area inventory wired to the real app stylesheet.
• docs/ui-ux/two-stage-proposal.html: existing two-stage chat UX proposal for issue #536.
• 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:

## 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.

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: automated test command and manual browser test plan.
• ARCHITECTURE.md: API, module layout, and design constraints.
• docs/onboarding.md: first-run wizard and provider setup.
• docs/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 compose setup, common failures, and bind-mount migration.
• docs/troubleshooting.md: diagnostic flows for common failures.
• docs/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.