HTML + Human Review — the document loop

Purpose

One skill, two halves of the same loop:

1. Publish (read): convert a Markdown file into a readable HTML artifact without changing its meaning.
2. Review (edit): open the Markdown source in a visual editor so the user edits text directly and leaves anchored comments; apply the batch to the .md; regenerate the HTML.

The Markdown file is ALWAYS the source of truth. The HTML is a generated, read-only artifact.

Done: done when the .md carries every edit from the batch and its HTML has been regenerated from it.

1. Write/generate the .md                      [as always]
2. md2html → HTML to READ                      [0 tokens]
3. review the .md → visual editor              [review]
4. Apply the batch to the .md source           [tokens only here]
5. Regenerate the HTML                         [0 tokens]

Half 1 — Markdown → HTML artifact

Always generate the HTML by running the deterministic script — never hand-write the HTML when the script is available:

python3 tools/md2html.py path/to/document.md

Output: <source-dir>/artifacts/<basename>.html (clean styles, footer with source + date). Same base filename; never create -v2/-final duplicates unless explicitly asked.

If the script is unavailable and HTML must be hand-written: preserve every element (headings, lists, tables, code, links, footnotes), invent nothing, change no numbers/dates/units, and produce a complete standalone document (inline CSS, works over file://, no external dependencies, responsive).

Light/dark theme

Every generated page (reading HTML and cloud review page) carries a ☾/☀ button. Untouched, the theme is automatic: dark between sunset and sunrise (computed in the browser for the SUN_LAT/SUN_LON set at the top of both scripts; change them to your city) or whenever the OS is in dark mode; a small dot on the button marks automatic. One click pins the other theme until the next sunrise/sunset, then it goes back to automatic. The choice lives in localStorage (key pos-theme), shared by every page on the same origin. Printing and PDF export always come out light. The server-mode editor has its own toggle, but it only darkens its frame, not the document.

Half 2 — Human review loop (over the .md source)

Two modes, same batch format and same applying rules. In a cloud session the cloud mode is the default (a local server can't run there); locally the server mode is the default.

Cloud mode — self-contained review page

python3 tools/md2review.py path/to/document.md

Output: <source-dir>/artifacts/<basename>.review.html — a self-contained page (inline CSS/JS, zero external requests, works over file://) where the user:

1. Edits text directly on the blocks (contenteditable; bold/italic get re-mapped to **/* — the page serializes after in Markdown).
2. Selects text → anchored comment via the macro buttons or free text (side panel, deletable before export).
3. Writes an optional overall_note.
4. Hits "Export batch" → JSON {source_file, generated_at, edits[{label,before,after}], comments[{quote,feedback}], overall_note} copied to clipboard (+ downloadable .json fallback) → pastes it in the chat.
5. The agent applies it to the .md (rules below) → regenerates the reading HTML (mandatory hook).

State is memory-only: closing without exporting loses the review (the page warns). The .review.html is a disposable input-capturer — regenerable from the .md, never a source, never edited by hand.

Server mode — local

npx -y human-review path/to/document.md        # open the editor on the .md source
npx -y human-review poll path/to/document.md --timeout 600   # wait for the batch

Re-run on timeout (unsent work persists in the browser). After applying a batch, confirm with --ack. Server by Peter Yang's human-review (see credits).

Applying the batch

• edits are changes the user already made: carry after across verbatim into the .md, re-mapping formatting to Markdown syntax. Never revert them.
• comments are instructions that need judgment: find each by its quote, apply per the macros below or the comment's text.
• Process every page in the batch, not just the first.

Regeneration hook (mandatory)

After applying a batch to a .md that has an HTML artifact → immediately regenerate the HTML (0 tokens). Never leave the md/HTML pair out of sync.

Anti-rule (hard)

Never edit the generated HTML — it gets overwritten on the next regeneration. The editor always opens on the .md. If the user edits a generated HTML by mistake: diff their changes, port them to the .md source first, then regenerate.

Review vocabulary — comment macros (fixed meaning)

(Rename the macros to your own language/shorthand — the point is a fixed, shared vocabulary.)

Attachments in a review

The editor is text-only. Workaround: the user drops the file anywhere on disk and writes its path in a comment or the overall note, plus what to do with it. When a batch arrives, scan comments and overall_note for file paths and read every referenced file before applying. Treat the referenced file as part of the feedback.

Correction → memory loop

If the same kind of correction appears in 2+ review sessions, propose promoting it to a permanent rule — in the author's voice file or the OS memory — and say what was promoted and why. Each review should train the system so the next draft ships better by default.

Core principle

Markdown stores the canonical content. HTML provides the reading experience. Review happens on the Markdown, through the editor. Always regenerate the HTML from the Markdown rather than maintaining two versions.

Credits

• Server-mode editor: petergyang/human-review.
• The cloud mode was built to run the same loop where a local server can't (cloud agent sessions); as a bonus, its batch carries bold/italic through serialization.