# 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`](../docs/SVRNTY-PLUGIN-PROTOCOL.md) — read this before contributing.

**Adding features?** Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the 5 recipes + decision flowchart.

## Install

```bash
# 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 7 methods:

```python
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
api.register_audio_attachment_processor(fn)       # hook STT/voice attachment pipeline
```

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` | ✓ live (lone fork commit, 7-method API) |
| Plugin scaffold | ✓ live (routes/static/tests/scripts/.github) |
| Migrated features (vault_status, transcribe, brand skin, voice-message mic) | ✓ live |
| Automation (drift CI, AST connection map, sync command, eval suite) | ✓ live (Gitea runner registered) |
| Upstream PR to nesquena/hermes-webui | deferred — gated on 2+ release smoke (PRD Phase 4) |
| Forced internal dependencies | **0** (plugin uses only public API) |
| Test suite | 26/26 PASS (unit + evals) |