svrnty-hermes-webui-plugin

THE single repo holding every Svrnty modification to nesquena/hermes-webui. Loaded at runtime via the plugin loader hook patched into the fork.

Protocol contract: hermes/docs/SVRNTY-PLUGIN-PROTOCOL.md — read this before contributing.

Adding features? Read CONTRIBUTING.md for the 5 recipes + decision flowchart.

Install

# 1. Install the plugin in the same venv as hermes-webui
pip install -e ~/workspaces/hermes/svrnty-hermes-webui-plugin

# 2. Tell hermes-webui to load it
export HERMES_WEBUI_PYTHON_PLUGIN=svrnty_hermes_webui_plugin
# or set in docker-compose.override.yml under environment:

# 3. Restart hermes-webui — endpoints under /api/* + assets under /plugins/svrnty/* land

Without HERMES_WEBUI_PYTHON_PLUGIN, hermes-webui runs vanilla (no Svrnty mods).

What's in here

Dir	What
plugin.py	Entry point — register(api) wires routes + static
routes/	One file per Svrnty /api/* endpoint (transcribe, vault_status, …)
static/	Brand skin: app.js, app.css, Montserrat fonts
CONNECTION-MAP.md	AST-generated map of every upstream symbol this plugin touches
scripts/	Tooling — AST walker, upstream sync, boot smoke
tests/	Unit · integration · evals (each upstream-sync runs evals)
.github/workflows/	Plugin-tests · connection-map-check · upstream-drift CI

Public extension API

The plugin loader (one fork commit in hermes-webui) exposes exactly 6 methods:

api.register_route(path, method, handler)   # add /api/<path>
api.register_static(prefix, directory)      # serve files under /plugins/<prefix>/...
api.inject_script(url)                      # add <script> to index.html
api.inject_stylesheet(url)                  # add <link> to index.html
api.config_get(key, default)                # safe upstream config read
api.logger(name)                            # namespaced logger

Touching anything else in hermes-webui = a Rule 2 violation per the protocol. Document the escape hatch in CONNECTION-MAP.md under "forced internal dependencies".

Hygiene

• make sync-upstream — one-command rebase against latest upstream + report
• python scripts/ast-connection-map.py — regenerate the map
• python scripts/boot-smoke.py — start + curl every plugin endpoint
• pytest tests/ — full suite (unit + integration + evals)

Status

Component	State
Loader hook in hermes-webui	TBD (Phase 1)
Plugin scaffold	Phase 1 in progress
Migrated features (transcribe, vault_status, brand skin)	TBD (Phase 2)
Automation (drift CI, sync command, eval suite)	TBD (Phase 3)
Upstream PR	TBD (Phase 4)