docs(user): reader audio section + kobo guide refresh to platform reality

reader-guide.md gains the audiobook/episode player section (seek,
prev/next episode, Bookmarks panel, Chapters list, Player settings with
autoplay/speed/resume-rewind overrides, Shortcuts dialog) — the player
existed with zero user docs.

kobo-setup.md drops the stale 'not available yet, actively being
developed' framing: the server side of native Kobo sync is implemented
and documented (sync/initialization endpoints, bookmark + markup sync,
shelf mappings, KEPUB sidecar config), so the guide now states exactly
that, keeps stock-firmware rollout as the honest remaining piece, and
keeps KOReader as the supported today-path.

ui-controls.md: Player settings / Shortcuts & interactions / Chapters /
Bookmarks entries (templ-entity fragments for ampersand labels).

docs/developer/ui-controls.md

@@ -68,6 +68,27 @@ note: templ source stores the ampersand entity; the rendered label reads "Add &
 label: Download all episodes now
 where: Add Podcast Feed panel
 does: Grabs the feed's back catalog immediately on subscribe.
+
+label: Player settings
+where: audio player → settings control
+does: Opens the per-player preferences — Autoplay on open, Default playback speed, Resume rewind.
+also: title="Settings"
+
+label: Shortcuts & interactions
+where: audio player → the ? control
+does: Lists every keyboard shortcut the player supports.
+also: Shortcuts & interactions
+note: templ source stores the ampersand entity
+
+label: Chapters
+where: audio player → chapter-list control
+does: Opens the chapter list and shows the current chapter position.
+note: title attribute on the control
+
+label: Bookmarks
+where: audio player → bookmarks control
+does: Opens your markers for this title; tap one to jump back.
+note: title attribute on the control
 ```
 
 ## Collections

docs/user/devices/kobo-setup.md

@@ -1,34 +1,41 @@
 # Kobo Device Setup Guide
 
-> ## 🚧 Coming Soon
+There are two ways to use a Kobo with Bookhoard, and they can be chosen
->
+independently per device:
-> Native Kobo sync is not available yet. It is actively being developed and this guide will be filled in as the feature lands.
 
-## Using a Kobo With Bookhoard Today
+| Way | Status | What you get |
+| --- | --- | --- |
+| **KOReader on the Kobo** | Works today, fully | Reading position, bookmarks, highlights, notes, OPDS wireless book delivery |
+| **Stock Kobo firmware (native sync)** | Server support is complete; device-side enablement is the remaining piece | Reading position and stats, bookmarks/highlights/notes, shelf mappings (your collections as Kobo shelves), automatic EPUB → KEPUB conversion, and the Kobo's own sync experience |
 
-You don't have to wait: **KOReader runs on Kobo hardware** and syncs fully with Bookhoard today — reading position, bookmarks, highlights, and notes, plus OPDS wireless book delivery.
+## Using a Kobo today
 
-See the **[KOReader Setup Guide](koreader-setup.md)** for complete instructions.
+**KOReader runs on Kobo hardware** and syncs fully with Bookhoard right
+now — the [KOReader Setup Guide](koreader-setup.md) walks the whole path
+(plugin install, server approval, OPDS delivery, troubleshooting).
 
-## What's Planned for Native Kobo Sync
+## About native Kobo sync
 
-When released, native Kobo sync will let stock Kobo firmware talk directly to Bookhoard:
+The server side of the native protocol is implemented and documented: the
+Kobo sync and initialization endpoints, bookmark and markup (highlight and
+note) sync, shelf mappings that expose your collections as Kobo shelves,
+and the KEPUB sidecar configuration used for conversion. What remains is
+the device-side rollout, so stock-firmware sync is not yet something to
+rely on for daily use — this guide will gain a full setup walkthrough when
+that lands.
 
-- **Reading position sync** — percentages, pages, and reading statistics
+Nothing about native sync takes anything away from KOReader: the two can
-- **Bookmarks, highlights, and notes** — synced with the web and other devices
+coexist, and a KOReader setup keeps working either way.
-- **OPDS wireless delivery** — browse and download books directly on the Kobo
-- **Automatic EPUB → KEPUB conversion** — for better Kobo rendering
-- **Shelf mappings** — Bookhoard collections appearing as Kobo shelves
-
-The server-side protocol endpoints are already implemented and under test; the feature will be announced when it's ready for real devices.
 
 ## FAQ
 
 **Q: Should I buy a Kobo to use with Bookhoard today?**
-A: Kobo devices work great with Bookhoard via KOReader. Native (stock firmware) sync is coming soon.
+A: Yes, via KOReader — it is the supported path today and covers sync plus
+wireless book delivery.
 
-**Q: What happens to my KOReader setup when native sync arrives?**
+**Q: Will I have to redo anything when native sync lands?**
-A: Nothing — KOReader will keep working. Native sync simply adds another option for people who prefer stock Kobo firmware.
+A: No — KOReader keeps working; native sync just adds the stock-firmware
+option.
 
 ## Additional Resources
 

docs/user/reader-guide.md

@@ -2,7 +2,8 @@
 
 Bookhoard's built-in web reader works in any modern browser — desktop or
 mobile — and keeps your position, highlights, bookmarks, and notes in sync
-with the Android app and KOReader.
+with the Android app and KOReader. Audiobooks get their own player, covered
+at the end of this guide.
 
 ## Opening a Book
 
@@ -79,3 +80,25 @@ to jump to it.
 Position, highlights, bookmarks, and notes sync automatically through the
 server (see the [Sync Guide](sync-guide.md)). Close the tab whenever you
 like — the reader resumes exactly where you left off on any device.
+
+## Listening to audiobooks and podcast episodes
+
+Books with audio files, and podcast episodes, open in the audio player
+instead of the page reader. It is one player for both:
+
+- The **seek bar** is your position; drag it, or use the **previous /
+  next episode** controls when you are playing a sequence
+- **Bookmarks** opens a panel of your markers for this title — tap one to
+  jump back
+- **Chapters** opens the chapter list (shows "currently chapter N of M");
+  audiobooks with embedded chapters and podcast shows with chapter marks
+  both land here
+- **Player settings** holds the per-player preferences: **Autoplay on
+  open**, **Default playback speed**, and **Resume rewind** (a few seconds
+  back when you resume — the defaults come from your
+  [profile](profile-guide.md) and this panel overrides them per player)
+- The **Shortcuts & interactions** panel (the **?** control) lists every
+  keyboard shortcut
+
+Progress, bookmarks, and your speed carry across devices through the same
+sync as everything else.