development.md was a bare link list whose 'implementation guides'
blurb still taught the pre-RLS visibility pattern. Now it's the
developer-tier portal: contributing/development.md as the start-here
(architecture/setup/testing — fresh and maintained), the gated API
reference with its per-area entry points and the openapi.yaml mirror,
the four protocol docs, the under-the-hood guides (RLS visibility,
scanner sidecars, calibre OPF, tag-normalization contract, Android
design), the standards (writing-ui-docs, glossary, contract pins),
and the gates enumerated — routes<->docs, Bruno parity, links, labels,
RLS invariant. writing-ui-docs.md's Developer-tier line closes the
open tone question: how-it-works, source-pinned, external software
linked not paraphrased.
Two additions to the screenshot-free writing standard, both owner-
ruled during the admin-docs planning session:
- Tone by audience gains the Administration tier, ending the 'not yet
decided' limbo for admin docs: plain language like the user docs, plus
what every control actually does (semantics, cost, consequences)
before the reader clicks, and per-setting what/does/means/range
coverage. Calibration in one line: user = what you see, admin = what
it does, developer = how it works. The Developer section keeps its
separate tone discussion for the deferred dev-docs pass.
- New 'Promises need approval' section: no coming-soon / under-
consideration / future-release language anywhere without the owner's
explicit approval of that exact promise; speculative text found in the
docs is reported, never quietly kept or quietly deleted. Provenance
recorded (the 2026-11-02 device-promise removals; the Operations
placeholders knowingly kept).
The planned Playwright screenshot docs (SCREENSHOT_AUTOMATION.md) are
replaced by a text standard: screenshots rot silently and cannot be
gate-checked, while this UI's labels are server-rendered templ literals
that can. Layers: pattern-first prose (concepts survive redesigns) >
capability inventory > label->outcome flows > quoted labels > generated
references where a registry exists (filters/fields.md precedent). The
filter docs stay hands-off exemplars; user-doc tone is plain language by
contract, dev/admin tone explicitly deferred.
writing-ui-docs.md is the standard (page template, findability notes,
tone-by-audience, process rule: a UI change is not done until the docs
audit runs). ui-controls.md is the canonical control-label glossary the
docs quote from; TestUIControlLabels greps every entry against
templates/*.templ (source: ts override; also:-fragments for
Alpine-composed labels like the Match/Group header) so renames fail
make test in the same commit as the rename. Gate proven both ways: a
planted bogus label failed; restored set passes.
John O'Keefe