# Review: README restructure (commit `14a7653`)

Status: done -- review of shipped work

**What it was reviewing:** opencode's implementation of
`plans/readme-restructure.md` — reshaping `README.md` around a
pitch → features → install → per-command usage structure borrowed from
`supabase-plus`'s README shape. Checked the actual diff (`git show
14a7653`) line by line against the spec's explicit constraints, not just the
new document's surface quality.

## Verdict: the restructuring itself is well done; one section's content was silently dropped, and one TOC link is dead

### What's correct, including the part most likely to go wrong

The spec's two "needs a decision, don't invent" items — a `## License`
section and a `## Repo & Contributions` section — are both correctly
**absent** from the new README. Neither a LICENSE file nor an honest
contributions policy exists yet, and the plan was explicit that opencode
should not fabricate either. Checked directly (`grep -i
"license\|contribut"` against every heading): nothing was invented. This
was the single most important constraint in the spec and it held.

Everything else structural matches: `## Features` uses the five bullets the
plan proposed, pulled from existing claims rather than invented ones;
`## Requirements` is pulled out as its own section; `## Installation` has
exactly the two real sub-methods (`Local (venv)`, `As a systemd service`)
rather than fabricated ones; `## Usage` is restructured into nine
per-command sections matching the plan's mapping table, and spot-checking
"Watch it live" and "Probe routing without spending" confirms the
Monitoring section's content (all five tools: `/metrics`, `/events/decisions`,
`tui.py`, `baseline_report.py`, `router_cli.py`) survived the reflow intact,
just condensed. A Table of Contents now exists where none did before.

### `## Setup`'s "Where Ollama lives" subsection was deleted, not moved

**Confirmed by diff, not inference.** `git show 14a7653 -- README.md`
shows this entire block removed with no corresponding addition anywhere in
the new document:

```
-### Where Ollama lives
-
-```bash
-ollama pull mistral-nemo:12b   # or whatever you set as classifier.model
-```
-
-...To use one across a VPN, point **both** endpoints at it:
-...and apply `deploy/ollama-over-vpn.conf` on the serving host — Ollama binds
-`127.0.0.1` by default and will otherwise refuse. Bind it to the VPN address
-rather than `0.0.0.0`: Ollama has no authentication, so anything reaching the
-port can run inference and enumerate your models.
-
-Both endpoints move together because the verifier speaks Ollama's *native*
-API and cannot follow the classifier to a cloud provider...
```

Grepped the current `README.md` for `ollama-over-vpn`, `ollama pull
mistral-nemo`, and `Both endpoints move together` — zero hits. This isn't a
paraphrase living somewhere else; the content is gone.

**Why this matters more than an ordinary trim.** This section carried a real
security instruction, not just background — Ollama has no authentication of
its own, and the doc's own words were the thing telling a reader to bind it
to a VPN address rather than `0.0.0.0`. The plan's own "What must NOT
change" section was explicit: *"Everything below stays exactly as it is,
moved but not rewritten"* and *"No new measurements, dates, or claims"* —
the inverse, dropping an existing one, was never authorized either. The most
likely mechanical cause: the old "Setup" section's opening sentence moved to
`## Requirements` and its venv steps moved to `## Installation`, and
"Where Ollama lives" — a `###` subsection of the same old `## Setup` — seems
to have been left behind in that split rather than carried to either
destination.

### Dead TOC link: "Scheduled Jobs (systemd)"

The Table of Contents (line 74) still has an entry
`- [Scheduled Jobs (systemd)](#scheduled-jobs-systemd)`. That heading no
longer exists — the content it pointed to was correctly moved into `###
As a systemd service` under Installation, which already has its own
correct TOC entry at line 43. The old line was never removed, so it's a
link to nowhere sitting in a document whose main improvement this pass was
*adding working navigation*. One line to delete.

A handful of other headings with em-dashes, backticks, or `&` (e.g.
`` `models` — one row per served model variant``, `Known Limitations & Open
Items`) produced anchor mismatches against a straightforward slugify check,
but GitHub- and Gitea-flavored anchor generation both have their own
non-obvious rules for those characters that a quick script can't be trusted
to reproduce exactly — these are worth a manual click-through in whatever
renderer this repo actually displays in (Gitea, at `git.adlee.work`), not
something to fix on the strength of this review alone.

## Recommendation

Restore "Where Ollama lives" verbatim — it's sitting in `git show
14a7653^:README.md` (the pre-restructure version) if a clean copy is
needed — into `## Installation`, most naturally as a third subsection
alongside `Local (venv)` and `As a systemd service` (it's setup guidance
that applies to either), or folded into `Local (venv)` if a separate
heading feels like too much for one paragraph plus a warning. Delete the
dead `Scheduled Jobs (systemd)` TOC line. Then do one manual pass clicking
every TOC link in the actual Gitea-rendered view, since that's the renderer
that matters here and not something worth guessing at from a script.