diff --git a/docs/developer/development.md b/docs/developer/development.md
index e6c6be62..65818990 100644
--- a/docs/developer/development.md
+++ b/docs/developer/development.md
@@ -1,95 +1,90 @@
 # Developer Documentation
 
-Welcome to the Bookhoard developer documentation. This section contains API references, protocol specifications, and technical documentation for integrating with Bookhoard.
+The developer tier of Bookhoard's docs: **how it works** — wire formats,
+data access, pipelines, and the rules the codebase enforces on you.
+(User docs tell you what things do; admin docs what the controls do;
+this section is the machinery itself.) Everything here is written
+against the source and kept honest by gates — if a doc and the code
+disagree, one of them fails `make test`.
 
-## 📚 API Documentation
+## Start here: architecture, setup, testing
 
-### Complete API Reference
+**[Development Guide](../contributing/development.md)** — the working
+developer's page: directory structure, backend components, database
+schema, tech stack, local setup, code generation (sqlc / templ /
+vite), build targets, and the full testing doctrine with its rules.
 
-- **[API Reference](api/api-reference.md)** - Complete REST API reference
-  - Authentication
-  - User management
-  - Libraries
-  - Media items
-  - Reading progress
-  - Notes & highlights
-  - Analytics
-  - Book matching
-  - OPDS
-  - Sync protocols (KOReader, Kobo)
-  - WebSocket
+## API Reference
 
-### Split Endpoint Documentation
+Two hundred endpoint documents, one per route, generated-adjacent and
+gate-checked against the router (a route without a doc fails the build,
+and so does a doc whose request examples drift from the Bruno
+collection):
 
-Browse individual endpoint documentation:
+- **[API Reference overview](api/api-reference.md)** — every area, auth
+  model, and conventions
+- Entry points: [Authentication](api/authentication/login.md),
+  [Users](api/users/get_profile.md),
+  [Libraries](api/libraries/list_libraries.md),
+  [Media Items](api/media-items/get_media_item.md),
+  [Progress](api/progress/get_media_progress.md),
+  [Notes](api/notes/get_notes.md) ·
+  [Highlights](api/highlights/get_highlights.md) ·
+  [Ratings](api/ratings/get_ratings.md),
+  [Devices](api/devices/get_devices.md),
+  [Collections](api/collections/list_collections.md),
+  [Analytics](api/analytics/get_analytics.md),
+  [Book Matching](api/book-matching/search_books.md),
+  [OPDS](api/opds/feeds.md),
+  [Scanner](api/scanner/overview.md),
+  [Admin](api/admin/list_users.md)
+- The machine-readable mirror lives at `docs/developer/openapi.yaml`
+  (regenerated by the parity test, never hand-edited).
 
-- **[API Documentation](api/api-reference.md)** - Split endpoint docs
-  - [Authentication](api/authentication/login.md) - Register, login, tokens
-  - [Users](api/users/get_profile.md) - Profile management
-  - [Libraries](api/libraries/list_libraries.md) - Library operations
-  - [Media Items](api/media-items/get_media_item.md) - Book/ebook management
-  - [Progress](api/progress/get_media_progress.md) - Reading progress tracking
-  - [Notes](api/notes/get_notes.md) - User notes
-  - [Highlights](api/highlights/get_highlights.md) - Book highlights
-  - [Ratings](api/ratings/get_ratings.md) - Book ratings
-  - [Devices](api/devices/get_devices.md) - Device management
-  - [Analytics](api/analytics/get_analytics.md) - Usage statistics
-  - [Book Matching](api/book-matching/search_books.md) - Search and link books
-  - [Collections](api/collections/list_collections.md) - Collection management
-  - [OPDS](api/opds/feeds.md) - Open Publication Distribution
-  - [Sync Protocols](api/sync/koreader-protocol.md) - KOReader and Kobo sync
-  - [WebSocket](api/websocket/protocol.md) - Real-time events
+## Protocols
 
-### Collections API
+- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** — progress,
+  metadata, conflicts; the plugin's server side
+- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** — native Kobo
+  sync (server-complete; device rollout pending — use
+  [KOReader](api/sync/koreader-protocol.md) on Kobo hardware today)
+- **[WebSocket wire format](websocket-api.md)** — real-time events:
+  message catalog, keepalive, fan-out and backpressure contracts
+- **[WebSocket endpoint](api/websocket/protocol.md)** — connection
+  parameters and endpoint-level reference
 
-- **[Collections API](api/collections/list_collections.md)** - Complete collections API reference
-  - Create and manage collections
-  - Auto-assign rules
-  - Test rules
-  - Bulk operations
-  - Device shelf mappings
+## Under the hood
 
-## 🔌 Protocol Specifications
+- **[Library Visibility](library-visibility.md)** — how per-user data
+  isolation actually works: Postgres RLS, the `app.user_id` GUC,
+  ScopedDB, and the rules new code must follow (the database enforces;
+  the app declares identity)
+- **[Scanner audio metadata](scanner/audio-metadata.md)** — the sidecar
+  and tag extraction priority for audiobooks
+- **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** —
+  how Calibre sidecar metadata becomes catalog rows
+- **[Frontend Integration Notes](../FRONTEND_INTEGRATION.md)** — the
+  tag & contributor normalization contract (display fields vs. search
+  fields, and why both exist)
+- **[Android App — Design & Roadmap](android-app.md)** — the native
+  client's design goals and platform posture
 
-### Sync Protocols
+## Standards this docs tree enforces
 
-- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** - Kobo device sync protocol
-  - Kobo markup sync
-  - Library fetch
-  - Authentication
+- **[Writing UI documentation without screenshots](writing-ui-docs.md)** —
+  the standard for every UI page in this repo
+- **[UI control glossary](ui-controls.md)** — the canonical spelling of
+  every control the docs cite (the label gate checks it against the
+  templates)
+- **[Contract Pins](../contract_pins.md)** — the API contract changelog;
+  loosening a pinned assertion requires an entry there
 
-- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** - KOReader sync protocol
-  - Progress sync
-  - Metadata fetch
-  - Conflict handling
-
-### WebSocket Protocol
-
-- **[WebSocket API](websocket-api.md)** - Real-time sync and events
-  - Connection flow
-  - Message format
-  - Event types
-  - Authentication
-
-## 🛠 Implementation Guides
-
-### Library Visibility
-
-- **[Library Visibility](library-visibility.md)** - Per-user library
-  visibility: the family-lens rule. New media endpoints MUST thread the
-  visible-library set (helpers, SQL pattern, series per-library).
-
-### Calibre Integration
-
-- **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** - Technical implementation details
-  - Architecture and design
-  - Data structures and functions
-  - Database schema mapping
-  - Testing strategy
-  - Error handling
-  - Performance considerations
+The gates behind all of it: routes ↔ docs coverage, docs ↔ Bruno
+parity, relative-link resolution, UI-label existence, and the RLS
+invariant test. Adding a route without a doc — or renaming a button the
+docs quote — fails the suite, by design.
 
 ---
 
-**Looking for user documentation?** See the [User Portal](../user/user-guide.md)
-**Need to deploy?** See the [Operations Portal](../operations/operations.md)
+**Looking for user documentation?** See the [User Portal](../user/user-guide.md).
+**Need to deploy or operate?** See the [Operations Portal](../operations/operations.md).
diff --git a/docs/developer/writing-ui-docs.md b/docs/developer/writing-ui-docs.md
index b9c773c7..98e28675 100644
--- a/docs/developer/writing-ui-docs.md
+++ b/docs/developer/writing-ui-docs.md
@@ -86,9 +86,12 @@ make the page followable even if that label is renamed next week.
   No API-client detail: request and response schemas live in the developer
   docs. The calibration in one line: **user = what you see, admin = what
   it does, developer = how it works.**
-- **Developer section — tone is a separate discussion, not yet decided.**
-  Write it plainly and hand-off-rich as well; do not import opinions about
-  its voice until that pass happens.
+- **Developer section — source-pinned and wire-accurate.** The
+  developer tier is *how it works*: wire formats, data access, pipeline
+  mechanics, and enforced rules, every claim grounded in source the way
+  admin docs ground behavior. External software (device installs,
+  third-party tooling) is linked to its project's documentation, not
+  paraphrased. (Decided 2026-11-02, closing the earlier open question.)
 
 ## Generate what has a registry