# Wiki Frontend Redesign Implementation

Date: 2026-04-19
Scope: CL4R1T4S-driven redesign of the personal wiki frontend at `~/.hermes/wiki-ui`

## Summary

The wiki frontend was upgraded from a generic MVP dashboard into a search-first knowledge workspace. The redesign keeps the Markdown-first architecture intact while improving browse flow, reading order, raw-file context, and keyboard efficiency.

## Implemented Changes

### Information architecture
- Home page now emphasizes workspace identity, search, primary actions, pinned pages, sections, capture flow, and recent activity.
- Added stable section landing pages at `/section/{section}` for both formal wiki sections and raw sections.
- Added core doc views for `index.md`, `SCHEMA.md`, `log.md`, and `README.md` through `/doc/{name}`.

### Page reading flow
- Formal page view now surfaces summary before body.
- Added generated table of contents.
- Sources are clickable and route into raw pages when the source path points into `raw/`.
- Backlinks are shown as a dedicated relationship block.
- Raw frontmatter moved into a lower-priority expandable block.

### Raw file flow
- Raw view now shows section, mime, size, timestamp, and next-step actions.
- Added `Referenced by` block showing which wiki pages cite a raw file.
- PDF handling now follows the approved rule: embed when possible, otherwise the page still exposes download.
- Quick note and upload redirects now show a visible capture confirmation.

### Interaction and visual system
- Added keyboard focus shortcut support for `/` and `Ctrl/Cmd+K` via `static/app.js`.
- Replaced full-page gradient / gradient-button / oversized-card MVP styling with flatter, denser, content-first workspace styling.
- Added reusable Jinja components for result items, section lists, source lists, activity items, and workspace hero shell.

### Testing and verification
- Added smoke tests under `~/.hermes/wiki-ui/tests/test_app_smoke.py`.
- Verified routes and redesign features locally and through nginx/HTTPS.
- Restarted `wiki-ui.service` to load the new code.

## Files Touched
- `~/.hermes/wiki-ui/app.py`
- `~/.hermes/wiki-ui/templates/base.html`
- `~/.hermes/wiki-ui/templates/index.html`
- `~/.hermes/wiki-ui/templates/section.html`
- `~/.hermes/wiki-ui/templates/page.html`
- `~/.hermes/wiki-ui/templates/raw.html`
- `~/.hermes/wiki-ui/templates/components/*.html`
- `~/.hermes/wiki-ui/static/style.css`
- `~/.hermes/wiki-ui/static/app.js`
- `~/.hermes/wiki-ui/tests/test_app_smoke.py`

## Verification Notes
- `python -m py_compile /root/.hermes/wiki-ui/app.py`
- `python -m pytest /root/.hermes/wiki-ui/tests/test_app_smoke.py -q`
- Local checks passed for `/`, `/section/entities`, `/page/entities/hermes-agent`, and `/raw/...`
- Reverse-proxied check passed for `https://wiki.hazim.work`