---
name: vault-html
description: "Convert vault markdown documents to styled HTML files and deliver them inline in chat via MEDIA: prefix. Covers md-to-html conversion, HTML template/style conventions, vault index maintenance, and the hard rule against serving vault files via nginx."
---

# Vault HTML Generation

## Trigger
- User asks to view/open a vault document as HTML
- User asks for a "clickable" version of a vault file
- Any time a markdown doc is saved to the vault and an HTML rendering would help the user read it

## The workflow
1. Read the markdown file
2. Convert to HTML using `templates/md-to-html.py`
3. Write the `.html` file alongside the `.md` file
4. Add an entry to `/root/.hermes/vault/index.html` pointing to the `.html` file
5. Deliver the file with `MEDIA:/path/to/file.html`

## HTML style conventions
- Navy header (`#0B1120`) with amber accents (`#E8893A`)
- Back link to `../index.html`
- Tables rendered as real `<table>` elements
- Bold, code, and lists formatted
- Mobile-responsive single-column layout

## Delivery
Always deliver the final HTML file with the `MEDIA:` prefix so it opens inline in the Hermes chat browser. On Connie (Windows), `MEDIA:` attached HTML files download instead of opening — in that case, provide a copyable HTTP URL from the Python server on port 9124 instead.

## Important: do NOT serve vault files via nginx
The vault lives at `/root/.hermes/vault/`. On this VPS, `/root` is mounted `ro` and owned by `root:root` with mode `drwx------`. Even though `/root/.hermes` is a separate `rw` mount, nginx (running as `www-data`) **cannot traverse `/root`** regardless of inner permissions or bind mounts. We verified this empirically:
- `alias /root/.hermes/vault/;` → 403 Permission denied
- `mount --bind /root/.hermes/vault /var/www/vault` → bind mounts as `/dev/sda1` (not a true bind in nginx's mount namespace), nginx still 404s
- AppArmor is not the blocker (no nginx profile in enforce mode)

**MEDIA: is the only reliable delivery path.** Do not attempt nginx serving.