Write the voice down, then apply it

[adnaan]

The docs had drifted into a register nobody chose. This writes the target down
and applies it to the 67 pages this repo owns.

Why "again"

The landing copy alone has been rewritten four times — #65, #83, #135, #136 —
and drifted back each time. Nothing in the repo recorded what the register was
supposed to be, so every rewrite re-derived it from scratch and landed on the
same flat default. VOICE.md is that record.

What the audit found

Not what I expected. The lexicon was already clean: one seamless, one
modern, zero powerful / effortless / robust / out of the box, zero
throat-clearing openers, sentence length a healthy 13–19 words.

The problem was that there were two hand-written voices, and only one was
broken. The ten pages under content/recipes/apps/ were ported once from
examples/<slug>/README.md and then cut loose:

	recipes/apps/ (10 files)	other 53
exclamation marks	9	2
emoji	14	5
Title Case headings	36	7

source-of-truth.md still claimed those pages were mirrored from
livetemplate/examples. They have not been since the consolidation, and
source-of-truth.yaml said so. That stale row is why nobody maintained them.

The register was producing false claims

This is the part worth a reviewer's attention.

chat.md said "Zero manual broadcasting code required!" while
examples/chat/main.go has an explicit ctx.Subscribe(ctx.SelfTopic()) and
three explicit ctx.Publish(...) calls. A reader who believed it would wonder
why their own app doesn't sync. Same page, same problem: "broadcasting happens
automatically", "automatic multi-tab syncing". All corrected against the real
file.

Counts

tell	before	after
emoji	19	0
Title Case headings	43	0
claudisms	14	0
product-as-subject openers	3	0
royal we	4	0
meta-commentary	3	0
hype lexicon	1	0
banned phrases	5	0
triadic negation	5	1
exclamation marks	11	3
passive voice	114	34

The three non-zero floors are deliberate and the script says why. The
exclamations are quoted UI copy ("Changes saved!" is what a flash message
says). The triadic negation is the landing's no hx-post, no onClick, no route to register, where each item names a real thing you would otherwise write.

34 passives is honest rather than lazy. Most of what remains is not passive
voice: "the title is required" describes an HTML attribute, "action methods are
exported" is Go, "is untouched" is an adjective. The regex cannot tell those
apart, so the ceiling stays at 34 instead of pretending 0 is reachable.

The checker is a ratchet

scripts/voice-check.sh runs in the validate job. Each ceiling is the count
on the day it was last tightened, so the build fails when a number goes up.
Bring one down, lower the ceiling in the same commit.

It will not catch a page that is merely flat. Most of VOICE.md is not
checkable — that is why it is written down rather than only encoded.

Three carve-outs, all documented:

• Emoji in a comparison table are scan markers doing real work (the "does
  this scale?" matrix in recipes/counter/index.md). Table rows are skipped.
• H1 carries the page name and must equal the front-matter title:. It
  feeds nav and breadcrumbs. Downcasing it is a rename — breadcrumb_test.go
  caught me doing exactly that to App Recipes. There is now an h1-vs-title
  check, and I verified it fires by breaking a title on purpose.
• reach for stays. At 24 files it is house idiom, and it is deliberately
  absent from the checker.

Flagged, not fixed

Two things a reviewer should not read as oversights.

1. chat.md's tutorial documents an API that does not exist. It shows
   func (s *ChatState) Change(ctx *livetemplate.ActionContext) error switching
   on ctx.Action with ctx.Bind(&data), and calls an undefined controller
   in main. The real examples/chat/main.go uses the controller pattern. That
   is a correctness fix, not a register one, and folding it into a prose PR
   would hide it.
2. 15 intra-site anchor links are broken. 13 are in mirrored pages. Checked
   against main: identical on both, so this PR adds none.

Not in scope

32 pages carry an upstream source_repo and cmd/sync overwrites the whole
file on release, so editing them here is work that gets thrown away. They need
PRs against livetemplate, lvt, client and examples — including
examples/CONTRIBUTING.md, whose §4 tells the next author to write the README
that started this.

Verification

• scripts/voice-check.sh green at the committed ceilings
• tinkerdown validate content/ — 98/98, 0 errors
• make test-e2e-local green, uncached, against the prod Docker image on :8084
• make sweep — 194/196; the 2 are the pre-existing 4.9 MB large-table timeouts
• anchor links diffed against main — 15 broken on both, 0 new
• 24 rewrites read back out of a real browser via chromedp
• every modified file checked for an upstream source_repo — no mirrored page touched

Note: this repo has no pre-commit hook installed, so do not read these commits
as hook-approved.

🤖 Generated with Claude Code

https://claude.ai/code/session_0166MK1arBYbVZq6wfm8EsQZ