Skip to main content

Maintaining these docs

Documentation is part of the Definition of Done for AudioSilo: a change that alters behaviour, UI, configuration, or the wire contract isn't finished until the affected pages here say the new truth. This page is the operating manual for the docs themselves.

Where things live​

The docs are their own repo, audiosilo-docs, a sibling of the code repos inside the ~/dev/audiosilo workspace:

audiosilo-docs/
docs-users/ the User Guide (served at /users)
docs-developers/ the Developer Docs (served at /developers)
sidebars-users.ts hand-written sidebar + canonical page list
sidebars-developers.ts
screenshots/ the capture pipeline (manifest.mjs, run.sh, capture-*.mjs)
static/img/screenshots/ the generated images the pages embed
src/ landing page + theme (shared Shelf tokens, follows the system colour scheme)

It's a standard Docusaurus site with two docs instances - one per audience. The User Guide assumes a self-hoster who is not a programmer; the Developer Docs assume a contributor. Keep material in the right instance and cross-link sparingly.

Local workflow​

cd audiosilo-docs
npm install # first time
npm start # live-reloading dev server
npm run build # the docs gate - MUST pass before a change is done

npm run build is deliberately strict: broken internal links, broken anchors, and missing embedded images all fail the build. That is the mechanical check that pages and screenshots stay consistent - treat it exactly like the code repos' gates. A prebuild check (scripts/check-admonitions.mjs) also rejects old-style admonition titles (see Writing style below).

The prebuild also runs the stale-name check (scripts/stale-names.mjs). It fails when a page names a server capability flag, API route, config key or AUDIOSILO_ variable that the server no longer has. It reads only names in backticks: a flag next to the word capability (the cast capability, or capabilities.cast), a route written with its method (GET /me/progress) or under /api/v1/, a dotted key whose first part is a config section (tls.mode), and an AUDIOSILO_ variable. Fenced code blocks are skipped. On the Bridge and metadata pages it checks only capabilities, because those pages name their own services' routes and settings.

What the server has comes from scripts/server-names.json, a snapshot taken at a pinned server commit, so the build needs no network. After a server change lands, run npm run names:sync (it reads ../audiosilo-server at origin/main; -- --server <dir> --ref <rev> for another), then fix the pages it reports. A name a page keeps on purpose, such as a planned route, the metadata service's routes or another repo's variable, goes in scripts/stale-names-allow.json with the reason. An entry no page needs any more fails the check too.

Search (the @easyops-cn/docusaurus-search-local theme) builds its index during npm run build, so the search box returns nothing under npm start. To try a search, or to check how a page ranks, use the built site: npm run build && npm run serve. A postinstall script, scripts/patch-search-link.mjs, makes the theme's "See all results" link point at /search?q= (the theme ignores trailingSlash: false); it fails the install if a theme upgrade changes that line, so check the link still keeps its query and then update or remove the script.

When a code change needs a docs change​

Grep these docs for the symbol, flag, route, or UI label you changed - onBrokenLinks can't catch a stale claim, only a stale link. Write any User Guide change to the readability rules. The common mappings:

You changed…Update
An API route, envelope, or fieldserver/api/reference.md (+ conventions), cross-repo contract - after updating the workspace CROSS-REPO.md itself
Config keys, env vars, CLI flagsserver/configuration.md + the User Guide pages that mention them (/users/getting-started/remote-access, quickstarts)
Admin console UI (admin-ui)/users/admin/* pages + the admin/ screenshots (capture just those with SHOTS_ONLY=admin/ screenshots/run.sh) + server/web-ui.md for build, serving, CSP or new-section changes
Player screens or strings/users/listening/* pages + the web-player/ screenshots
The player's design system (STYLEGUIDE.md, tokens, fonts, src/components/ui/ primitives, high contrast, the large-text, touch-target and screen-reader rules)frontend/styling.md (+ testing.md when the token generator or style guards change; /users/listening/settings#accessibility when users notice it); the frontend's own STYLEGUIDE.md stays authoritative, so these pages summarise it rather than copy it
The player's shell: tabs, route groups, breakpoints, top barfrontend/shell.md + the route map in frontend/routes.md, /users/listening/browsing (getting around), /users/listening/mobile-apps
The full player, mini / docked player, the companion, player sheets, web keyboard shortcutsfrontend/player-ui.md + /users/listening/full-player, /users/listening/playback, /users/listening/companion, /users/listening/keyboard-shortcuts (+ /users/listening/up-next for the Up next sheet, /users/listening/browsing for Previously on)
The book page (src/components/book/, the book tabs)frontend/book-page.md + /users/listening/book-page + the web-player/book-*.png and phone-book-detail.png screenshots
Bookmarks and notes (src/components/annotations/, the editors, labels)frontend/annotations.md + /users/listening/bookmarks-and-notes (+ the annotations rows in state-and-data.md)
The Journal (src/components/journal/, export, src/lib/listening-sessions.ts)frontend/journal.md + /users/listening/journal + the web-player/journal*.png screenshots
The You hub, Your listening, Year in listening (src/components/you/, the /year modal, sharing a card)frontend/you-and-settings.md + /users/listening/you, /users/listening/year-in-listening + the web-player/you-stats.png, phone-you-stats.png and year.png screenshots
Settings or a server's Account page (src/components/settings/, src/components/account/)frontend/you-and-settings.md + /users/listening/settings, /users/listening/account (+ /users/listening/api-keys for API keys) + the web-player/settings.png, settings-appearance.png, phone-settings.png and account.png screenshots; when a setting moves, every page that links its settings.md#… anchor
Connect and onboarding (src/app/connect/, src/components/connect/), home and away addresses (address-route.ts, address-runner.ts, server-address.ts), the sign-in key (sign-in-key.ts)frontend/connect-and-addresses.md + /users/listening/connecting + the web-player/connect*.png screenshots; the server side of the addresses is server/configuration.md and /users/getting-started/remote-access
Recaps, characters, the series rails and the spoiler gate (src/components/library/book-meta.tsx, meta-gating.ts, community-cover.ts)frontend/state-and-data.md + /users/listening/recaps-and-characters
The end of a book, what plays nextfrontend/end-of-book.md + /users/listening/end-of-book, /users/listening/up-next, the Up next and downloads settings in /users/listening/settings
The sleep timerfrontend/sleep-timer.md + /users/listening/sleep-timer, the Sleep settings in /users/listening/settings
Playback engines / native modulefrontend/playback.md (+ /users/listening/playback for lock-screen and headphone behaviour)
One tab plays at a time on the web (src/lib/tab-channel.ts, src/playback/playing-claim.ts, other-tab-notice.ts, claimPlaying / giveWayTo / otherTabsPlace / onGaveWayAnswer in store.ts, the out and maybeReached marks in listening-outbox.ts)frontend/playback.md + frontend/offline.md + /users/listening/playback (Good to know)
The periodic save's pace and off-screen rendering (saveIntervalMs, saveLoop / placeLoop / spanKeeper / openMissingSpan in store.ts, src/lib/app-activity.ts, quietOffScreen in src/lib/visible-store.ts, mirrorSpanEnd in progress-sync.ts; the server's livePlaying window)frontend/playback.md (the three loops, what a kill leaves behind, the spans and the one-tab section's timings) + state-and-data.md (the hooks off screen, the mirror) + data-model.md (the save pace against the playing window) + the reference's two state fields + the cross-repo contract + index.md (Progress sync) + testing.md + /users/listening/playback#your-position-follows-you, /users/listening/in-the-house, /users/admin/activity#live-now (how far behind another device or the console can be)
Watch renditions and the file cache (media/filecache.go, media/remux.go, media/rendition.go, api/handlers_renditions.go, the renditions capability), a watch client (the console's clientKind, the player's knownPlatform / deviceGlyph)server/media.md (and its remux section) + the reference + api/index.md (the flag, the codes, the watch's X-AudioSilo-Client) + configuration.md (--ffmpeg, the cache folder) + cross-repo-contract.md (after the workspace CROSS-REPO.md §5, §8, §20) + you-and-settings.md + /users/admin/server#transcoding, /users/getting-started/first-run, /users/admin/activity, /users/admin/users-and-invites, /users/listening/account
How the web loads a server's covers and audio (CoverImage, src/lib/cors-mode.ts, the <audio> element's crossOrigin; server cors, Cross-Origin-Resource-Policy)frontend/playback.md + styling.md (CoverImage) + api/index.md CORS + auth-and-security.md + cross-repo-contract.md §12 (after the workspace CROSS-REPO.md §12)
Smart speed, Voice boost, time saved (effects.ts, time-saved.ts, effects-settings.tsx, the Android effects/ processors, VoiceBoostTap.swift, VoiceBoostDSP.swift)frontend/audio-effects.md (+ frontend/book-page.md for smartSpeedSaved) + /users/listening/full-player (Smart speed and Voice boost), the Playback settings in /users/listening/settings, the Your listening row in /users/listening/book-page + the web-player/phone-speed-sheet.png, settings.png and phone-settings.png screenshots
The Apple Watch app (targets/watch/, watch-core/, plugins/withWatchScheme.js), the phone's side (modules/audiosilo-watch, src/watch/, WatchCard, WatchSection, Send to watch), the phone-watch messagesfrontend/apple-watch.md (+ testing.md) + /users/listening/apple-watch, /users/listening/account, /users/listening/offline-downloads, /users/listening/mobile-apps. The web can't show the watch: watch/*.png are device shots, taken by hand (screenshots/README.md, "Device shots")
The Wear OS app (wear/, wear-core/, plugins/withWearApp.js, the *-wear EAS profiles, wear.yml), the phone's Android side (modules/audiosilo-watch/android, watchWording), the Data Layer contractfrontend/wear-os.md (+ testing.md, and frontend/apple-watch.md for a message change) + /users/listening/wear-os, /users/listening/account, /users/listening/offline-downloads, /users/listening/mobile-apps. The web can't show the watch: wear/*.png are device shots, taken by hand (screenshots/README.md, "Device shots")
CarPlay, Android Auto (src/car/, the module's car code, plugins/withCarPlay.js), the after-first-unlock token store, the iOS widgets and Live Activity (src/widgets/)frontend/native-integrations.md (+ testing.md for how to run them) + /users/listening/in-the-car, /users/listening/mobile-apps (Availability, In the car, widgets), /users/listening/sleep-timer (the Live Activity). The web can't show these surfaces: device screenshots, when there are any, are added by hand to the manifest
Connection ids, the identity migration (src/lib/connection-id.ts, src/lib/identity-migration.ts, a new document keyed by a connection id)frontend/state-and-data.md (+ ID_DOCUMENTS when a new document is keyed by a connection id)
Profiles, the PIN, the Household page's On this device (src/stores/profiles.ts, src/lib/profile-pin.ts, src/components/profiles/, src/components/household/device-people.tsx)frontend/profiles.md + /users/listening/profiles, /users/listening/household
Household members: the Household page, the add sheet, member cards, addMemberHere (src/components/household/, src/components/connect/add-member-here.ts; server auth/members.go, catalog/members.go, handlers_members.go, the household.* settings; the console's people/household.tsx)frontend/household.md + state-and-data.md + kids-mode.md + you-and-settings.md (a member's account page, the lost-phone tick) + the reference + api/index.md (the codes and the capability) + auth-and-security.md + data-model.md + server/configuration.md + backups-and-notifications.md (the member audit area) + the cross-repo contract + /users/listening/household, /users/listening/kids-mode, /users/listening/account, /users/listening/profiles, /users/admin/users-and-invites#household-members, /users/admin/server (Household, the audit log)
Kids mode (src/components/kids/, the bedtime rule and the kids 1× speed in src/playback/listener-settings.ts, applied by auto-sleep-controller.ts, the kids car snapshot in src/car/)frontend/kids-mode.md (+ frontend/sleep-timer.md for the auto sleep rule) + /users/listening/kids-mode (+ /users/listening/in-the-car for the car)
Listening in the house (src/components/house/, the household hooks; server catalog/household.go)frontend/listening-in-the-house.md + the reference + auth-and-security.md + /users/listening/in-the-house, /users/admin/activity (what the server records)
Chromecast (src/cast/, plugins/withCast.js; server auth/cast.go, handlers_cast.go, the web CSP)frontend/chromecast.md + the reference + auth-and-security.md + server/web-ui.md for the web CSP (castSenderScripts, the policy TestHTMLCSPCastSender pins) + /users/listening/chromecast, /users/listening/playback (other speakers), /users/getting-started/remote-access (the certificate note)
Downloads / PWA, the offline companion (offline-meta.ts), podcast episode downloads (src/downloads/episode-ready.ts, src/playback/episode-fetch-rules.ts, autoDownloadEpisodes)frontend/offline.md (+ frontend/podcasts.md for episodes) + /users/listening/offline-downloads (+ /users/listening/podcasts and /users/listening/settings for episodes) + the web-player/downloads.png screenshot
The online flag and the offline states (src/lib/device-online.ts, offlineState, useUnreadQuery and useUnreadBooks in src/lib/offline-state.ts, OfflineState, the onlineManager wiring and the mutations default in provider.tsx), the kept /server answer (src/api/server-snapshots.ts), the library the Library is on (resolveLibrary, resolveCarLibrary, useSelectedLibrary, LibraryPicker)frontend/state-and-data.md (Offline states, the kept /server answer, Library selection) + frontend/library-and-browse.md + frontend/offline.md (which path listening takes, the companion's seeding, keep-ahead's held reads) + frontend/native-integrations.md (the car's library tab) + frontend/reader.md and frontend/player-ui.md (the Text tab's offline) + frontend/journal.md (unreadSources) + frontend/you-and-settings.md (useYearStory's offline) + /users/listening/offline-downloads (With no connection), /users/listening/browsing, /users/listening/in-the-car, /users/listening/companion, /users/troubleshooting
The web start: async routes, deferred/afterPaint, the root's services (root-services*.tsx), the startup cache (src/api/startup-cache.ts), the startup queries (startup-queries.ts), the start scripts' compile hint and parts (scripts/web-start-chunks.cjs), first-screen covers, the web's language chunks (catalogs.web.ts), sw.js's build precachefrontend/web-build.md + offline.md + state-and-data.md + i18n.md + /users/listening/browsing (the home screen's note), /users/listening/offline-downloads (the PWA), /users/listening/settings (Language)
First-run setup: the /setup page (handlers_setup.go, assets/setup.*), the console's Set up your server flow and Overview card (features/setup/, finish-setup-card.tsx), catalog/setup.go, library/preview.go, library/mounts.go, handlers_admin_setup.go; the first-run admin after its banner (internal/launcher/firstrun.go: reset-admin and the sign-in hint, auth/firstrun.go, the console's login hint)/users/getting-started/first-run (a section and shot per step, and If you lose the password) + /users/troubleshooting (I lost the first-run admin password) + the quickstarts' setup step (/users/getting-started/quickstart-docker, install-unraid, install-synology, install-binary) + /users/admin/console-tour (the card) + web-ui.md (the flow and the /setup page) + the reference (and POST /setup) + api/index.md (the codes) + data-model.md (setup_state, 0053) + configuration.md (--setup, the commands) + backups-and-notifications.md (settings.setup) + the server/setup-wizard*.png and setup/*.png screenshots (capture-setup.mjs: SHOTS_ONLY=setup/,server/setup-wizard screenshots/run.sh)
The ebook reader: the server's ebook field, handlers_ebook.go, library/ebook.go (BookEbook, OpenEbook), catalog/reading_progress.go (ResolvePlace), web.readerCSP; the player's reader/ (the reader document, scripts/build-reader.mjs), src/reader/ (the web and app hosts, the app's EPUB cache and chunked transfer), Read on the book page, the ebook in downloads (manifest.ebookUri)frontend/reader.md + frontend/offline.md + the reference + server/web-ui.md + scanner.md + the cross-repo contract + /users/listening/reading-the-ebook (+ /users/listening/keyboard-shortcuts for its keys, /users/listening/offline-downloads for the ebook in downloads) + the web-player/reader*.png and book-read.png screenshots
Scanner, detection, metadataserver/scanner.md + /users/getting-started/organizing-your-library (+ configuration.md and /users/admin/libraries#rescanning for scan.concurrency)
Community chapters (internal/chapteralign, internal/chaptercheck, catalog/communitychapters.go, the Chapters card's panel)server/community-chapters.md + the Community chapters section of /users/admin/books (and /users/admin/health for the Health rows)
Edited chapters: catalog/chapteredits.go, chapter_edits, PUT/DELETE …/book/chapters, editor tokens (auth.IssueEditorToken), the console's chapter editor (features/book/chapters-editor.tsx, chapters-edit-model.ts), the player's edited captionserver/community-chapters.md + the reference + auth-and-security.md (editor tokens) + data-model.md + web-ui.md (the Chapters card) + frontend/book-page.md (the caption) + /users/admin/books#edit-chapter-times-and-titles, /users/listening/book-page#chapters + the admin/book-chapters-edit.png screenshot
Auth, invites, sharesserver/auth-and-security.md + /users/admin/users-and-invites, /users/admin/sharing
Single sign-on, OpenID Connect (server internal/oidc, auth/identities.go, handlers_oidc.go, auth.oidc.*; the console's sign-in link, Settings > Sign-in, Waiting sign-ins, the "Signed in with" card; the player's button, src/components/connect/oidc-sign-in.ts, oidc-intent.ts)server/auth-and-security.md + server/configuration.md + the API reference, /users/admin/single-sign-on and the /users/admin/sso/* provider pages, the oidc screenshots (screenshots/capture-oidc.mjs, SHOTS_ONLY=admin/ screenshots/run.sh)
Rate limiting (api/ratelimit.go, rateLimit, requireAuth/mediaAuth's per-credential buckets, rate_limit.*)auth-and-security.md + api/index.md + configuration.md + /users/getting-started/remote-access (why it's safe, the reverse proxy), /users/troubleshooting (Too many tries)
The Bridge: the server's side (auth/bridge.go, internal/bridge, handlers_bridge.go, handlers_bridge_estimate.go, the bridge capability, the console's features/bridge/) or audiosilo-bridge (its config, images, compose example, mapping checks, job runner, page, the agent container and its credential hand-off, sidecars.generate, sidecars.describe, sidecars.contribute, meta.correct, the setup checklist, the Accounts tab and its GitHub sign-in)the Bridge developer pages (index, pairing and jobs, mappings, characters and recaps, the .audiosilo folder, the agent container, contributions, configuration, development) + the reference + api/index.md (the capability, the codes, the bridge token) + auth-and-security.md + data-model.md + backups-and-notifications.md (the bridge_job_* events) + web-ui.md (the console's Settings > Bridge and the book page's Bridge parts) + the cross-repo contract (after the workspace CROSS-REPO.md §23) + /users/admin/bridge, /users/admin/generating-characters-and-recaps, /users/getting-started/running-a-bridge (its steps follow the setup checklist's order), /users/getting-started/bridge-accounts and /users/community/contributing-from-your-server + meta/contributing-data.md (what the Bridge files, and how meta routes it) + the admin/settings-bridge*.png, admin/bridge-setup.png, admin/bridge-pair.png, admin/book-generate.png, admin/generate-dialog.png and admin/book-description.png screenshots + the Bridge page's bridge/*.png screenshots (capture-bridge.mjs: BRIDGE=<checkout> SHOTS_ONLY=bridge/ screenshots/run.sh)
Podcasts: library kind, internal/podcast, catalog/handlers, the Bridge's podcastjob, netguard, feed/Fetch files, downloads, on-demand/status/Retry and queue prefetch, listener fetch limits, claim priority/reserved capacity, retention aggregates/policies, generations/ETags, publication journals, CHAP or root markers; directory search and OPML (internal/podcast/{discovery,opml,quota}, follow.go, opmlimport.go, export.go, podcasts.discovery.enabled, the Podcast Index variables)bridge/podcasts.md (with its discovery and OPML section, its player and player discovery and OPML sections) + server/modules.md, configuration.md (and its podcast discovery section), API reference (including admin storage and Bridge retention), API flags, data-model.md, scanner.md, auth-and-security.md, bridge/configuration.md, attachments.md, mappings.md, pairing-and-jobs.md, bridge/index.md, cross-repo-contract.md, backups-and-notifications.md (the podcast notifications) + /users/admin/podcasts, /users/admin/notifications#podcasts, /users/admin/libraries, /users/admin/bridge, /users/admin/server#modules, /users/getting-started/running-a-bridge, /users/faq (what a directory search sends) + admin/libraries.png, admin/library-add.png, admin/library-add-podcasts.png, admin/library-edit.png and admin/settings-modules.png
The player's podcasts: src/components/podcasts/, src/playback/episode-fetch.ts, Home's New episodes (new-episodes-*, use-new-episodes.ts), the shows Library mode, src/lib/library-kind.ts, the podcast client gate (auth.PodcastPlayerMinVersion, app.json expo.version, client-id.ts), the gated whole-list replace (catalog.GatedScopes); finding shows (find-shows-*, directory-search.tsx, discovery-*, follow-by-url.tsx, follow-requests.tsx, opml-*, use-opml-import.ts, shows-actions.tsx, check-episodes-button.tsx, artwork-retry.ts, src/lib/podcast-requests.ts, findShowsHref, the podcast_discovery / podcast_opml client methods and hooks), the server's CORS lists (corsAllowHeaders, corsExposeHeaders)frontend/podcasts.md (and its Finding shows) + bridge/podcasts.md (the wire and the controller's rules; discovery and OPML for 2d-2) + api/index.md CORS and cross-repo-contract.md §12 + auth-and-security.md + the reference (the gate, the replace rules) + api/index.md + the lines in playback.md, state-and-data.md, offline.md, chromecast.md, end-of-book.md and kids-mode.md + /users/listening/podcasts (and the podcast lines in browsing, up-next, end-of-book, offline-downloads, chromecast, kids-mode, mobile-apps, /users/troubleshooting, /users/admin/podcasts, /users/admin/server#modules, /users/faq) + the web-player/library-shows.png, podcast-show.png, home-new-episodes.png, episode-fetching.png, phone-podcast-show.png, find-shows-search.png, find-shows-address.png, find-shows-import.png and phone-find-shows.png screenshots (the podcast seed in run.sh and its directory fixture; Find shows' stand-in routes in capture-web.mjs)
Managed modules: the server's internal/modules (its Runner, the builtin registry), api/modules.go, a modules.<id> setting, the console's Settings > Modules (features/settings/modules-topic.tsx), the player's src/modules/ registry and slotsserver/modules.md (+ the adding-a-module steps) + configuration.md (the key, the variable, the runtime table) + the reference (GET /admin/modules, the settings envelope's modules, the module's flag on GET /server, the module's Bridge jobs) + api/index.md (the flag, module_off, kid_account, demo_account) + bridge/pairing-and-jobs.md (the jobs a module owns, held while it is off) + web-ui.md + frontend/state-and-data.md + the cross-repo contract + /users/admin/server#modules (the console's Learn more link opens it: keep the heading) + /users/admin/bridge#when-the-contributions-module-is-off + the admin/settings-modules.png screenshot
Audible accounts, backups and position sync (Bridge Phases 4a, 4b and 4c): the server's catalog/audible.go, catalog/audible_import.go, catalog/audible_sync.go (and FurthestOnly in catalog/listening_sync.go), internal/audible (the scheduler, imports.go), bridge/audible.go (audible.poll, audible.import, audible.sync), api/handlers_audible.go, api/handlers_audible_sync.go, 0063, 0064, 0065 (planned destinations, contests), 0066 (sync, no_sync, progress.change_seq), the audible module and flag, the console's features/audible/ (the Audible accounts card, Settings > Audible); the Bridge's internal/audible (the client, the build-tagged fake and AUDIOSILO_BRIDGE_AUDIBLE_*), audibleacct, audiblejob (import.go), audiblesync (the job and the push loop), link/audiblesync.go, 0011 (audible_push, refusal_kind), importjob, placement, transfer, fsutil's install, link/audible.go, 0009, 0010 (the device profile), redact.go, audiblejob/plan.go, the Accounts tab's AudibleCard, the audible setup itembridge/audible.md + bridge/configuration.md (and its Secrets) + bridge/development.md (the tagged gate) + pairing-and-jobs.md (and its setup checklist) + the reference (and 4c's position sync routes, the reserved audible: device id on /me/listening/sync and the progress PUT, and the module flag on GET /server, features, GET /admin/modules) + api/index.md (the flag, the codes) + server/modules.md + configuration.md + data-model.md (0063, 0064, 0065, 0066; progress.change_seq) + web-ui.md + the cross-repo contract (after the workspace CROSS-REPO.md §8, §23 and §25) + /users/admin/audible (its sync section), /users/listening/playback (Places from Audible), /users/getting-started/bridge-accounts#audible, /users/admin/bridge (the card, the setup step), /users/admin/server#modules + the admin/audible-accounts-card.png, admin/audible-titles.png, admin/audible-backup-settings.png, admin/audible-backup-all.png, admin/audible-destination.png, bridge/accounts-audible.png and bridge/audible-sign-in.png screenshots (capture-bridge.mjs against a Bridge built with -tags audiblefake and the fake: SHOTS_ONLY=bridge/,admin/audible screenshots/run.sh). Copy about backing up says "a personal backup of books you bought" and "check your local law", never that it is legal everywhere
Add from LibriVox: the server's api/handlers_librivox.go, bridge/librivox.go (librivox.fetch), catalog/librivox.go (FoldLibrivoxFetch, WorkRecordingBooks), meta/librivox.go, the console's features/librivox/ (and the job list's fetchReason, the Community card's LibriVox line, the bell); the Bridge's internal/librivoxjob, metaops/librivox.go, netguard's per-request Allow; the player's src/components/librivox/bridge/librivox.md + the reference (and community_match, the internal kinds of POST /admin/bridge/jobs, the librivox feature) + api/index.md (the feature, in_library and the other codes) + bridge/pairing-and-jobs.md + bridge/attachments.md and server/scanner.md (librivox.json) + data-model.md (the fold) + web-ui.md + frontend/library-and-browse.md and routes.md + backups-and-notifications.md + the cross-repo contract (after the workspace CROSS-REPO.md §23 and §17) + /users/admin/librivox and the admin/librivox.png and web-player/find-librivox.png screenshots
Chapterless books: the Bridge's internal/chapterdetect, chapter_detecting, the windows manifest, chapters.detect; the server's metadata/chapterlist.go, catalog/generatedchapters.go, the console's Detect chapters (health/detect-chapters-dialog.tsx) and the Chapters card's source control; the player's generated captionbridge/chapters.md + bridge/attachments.md + bridge/pairing-and-jobs.md (the kinds table) + server/community-chapters.md + the reference (chapters_source, chapter_choice, generated_chapters_fit, the 409 codes) + api/index.md (the chapters feature, the codes) + data-model.md + backups-and-notifications.md (chapters_source on the event) + web-ui.md (Health, the Chapters card) + frontend/book-page.md (the caption) + /users/admin/chapter-detection, /users/admin/generating-characters-and-recaps#books-without-chapters, /users/admin/health, /users/admin/books#chapters-found-in-the-narration, /users/listening/book-page#chapters + the admin/health-detect-chapters.png, admin/detect-chapters-dialog.png and admin/book-chapters-generated.png screenshots
Read-along: the Bridge's internal/readalong, internal/epubcfi, readalong_aligning, goal readalong, readalongjob.go (the reuse table, the 50% refusal); the server's metadata/readalong.go, library/readalong.go, catalog/readalong.go, handlers_readalong.go, the readalong.align kind, Book.readalong, the readalong capability; the console's Read-along card (features/book/readalong-*)bridge/readalong.md + bridge/attachments.md + bridge/pairing-and-jobs.md (the kinds table) + the reference (/readalong, Book.readalong on /item, the estimate's kind=readalong.align, the job, the Bridge book route's duration and ebook) + api/index.md (the capability, the feature, no_readalong, readalong_stale, readalong_open, no_ebook) + scanner.md (ebook hashing) + data-model.md (0058) + backups-and-notifications.md + web-ui.md (the card) + the cross-repo contract (after the workspace CROSS-REPO.md §23 and §24) + /users/admin/making-read-along, /users/admin/bridge (the job), /users/admin/notifications + the admin/book-readalong.png and admin/readalong-dialog.png screenshots (SHOTS_ONLY=admin/book-readalong,admin/readalong-dialog)
Read-along in the player (Bridge Phase 3c-2): reader/src/readalong.js, the read-along messages in protocol.ts and reader.js, src/reader/ (readalong-map.ts, readalong-gating.ts, use-book-readalong.ts, narration.ts, use-reader-readalong.ts, reader-session.ts, page-edge.tsx, Follow narration in reader-screen.tsx), the companion's Text tab (companion/text-panel.tsx, use-text-tab.ts), Make read-along (src/components/bridge/make-readalong.tsx, use-make-readalong.ts, readalong-model.ts), the map in downloads (src/downloads/readalong-file.ts, readalongGeneratedAt), useReadalong / useReadalongEstimatefrontend/reader.md + player-ui.md + offline.md + state-and-data.md + /users/listening/reading-the-ebook#follow-the-narration, /users/listening/companion#text, /users/listening/full-player, /users/listening/offline-downloads, /users/admin/making-read-along#from-the-player + the web-player/player-text.png, reader-readalong.png, phone-player-text-chip.png and phone-player-text.png screenshots (SHOTS_ONLY=web-player/player-text,web-player/reader-readalong,web-player/phone-player-text; the seed is run.sh 2e, seed-readalong.mjs and fixtures/call-of-the-wild.readalong.json, and the run stops early when Gutenberg's EPUB no longer matches the map)
Upcoming releases (Track U): the server's internal/upcoming (with ics.go, the calendar), catalog/upcoming.go, meta/upcoming.go, handlers_upcoming.go, handlers_upcoming_calendar.go, auth/feed.go (the feed token kind, 0060), the upcoming.* config, the upcoming, upcoming_calendar and upcoming_covers capabilities, release_date on the /meta rails, book_released; the console's dated series gaps (series-model.ts releaseState, series-card.tsx) and Settings > Metadata's upcoming switch and New release windowthe reference (and release_date on /meta, metadata.upcoming and metadata.upcoming_window_days on /admin/settings) + api/index.md (the flags, upcoming_off, metadata_off, kid_account, demo_account, not_found, cover_unavailable, the feed token and the ?token= scope) + auth-and-security.md (feed tokens; also invariants.md's confined token-in-URL and media.md) + configuration.md + data-model.md (0059, 0060 and the tokens kinds, the upcoming server state) + backups-and-notifications.md + the cross-repo contract (after the workspace CROSS-REPO.md §8 and §17) + /users/admin/books#series, /users/admin/server#community-metadata, /users/admin/notifications + the admin/series.png and admin/settings-metadata.png screenshots. The player's side (Track U2: src/components/upcoming/, useUpcomingAll, src/lib/upcoming.ts, release-date.ts, formatReleaseDate, the series page's dated ghosts, the You hub's Upcoming section; Track U3: UpcomingCover, UpcomingCalendarCard, src/lib/upcoming-calendar.ts, the calendar hooks and the device copy of the link): state-and-data.md (and The upcoming calendar) + testing.md + the route map in routes.md + you-and-settings.md + /users/listening/upcoming, /users/listening/browsing (Home, series pages), /users/listening/you + /users/admin/server#community-metadata (the calendar's public-address note) + the web-player/home-upcoming.png, upcoming.png, phone-upcoming.png and upcoming-calendar.png screenshots (the capture's upcoming pass in capture-web.mjs)
Listening sync (Sync v2, Track W1): the server's catalog/listening_sync.go, handlers_listening_sync.go, the listening_sync capability, listening_events (0061) and the progress columns, Stay wins (listening_stay, stay_version / edit_version in 0080, standByPlace), device_name / other_place on progress, the put event of a PUT, sessions and history from spans (recordSpan); the player's src/playback/listening-outbox.ts, listening-sync.ts, the spans in store.ts, ack_version in progress-sync.ts, offerOf and the offer toast, listening-offer.tsx, listening-sync-card.tsx, the unsynced warnings on sign-out, removing a server and removing a personthe reference (and the progress routes' device_name / other_place, and A Stay) + api/index.md (the flag, too_many_events) + data-model.md (listening_events, the progress columns, 0061, sessions) + auth-and-security.md + the cross-repo contract (after the workspace CROSS-REPO.md §20 and §25) + frontend/offline.md + playback.md (the spans, the offer) + state-and-data.md + you-and-settings.md + book-page.md + /users/listening/playback#listening-on-more-than-one-device, /users/listening/account#listening-sync, /users/listening/book-page, /users/listening/browsing (Home's line), /users/listening/offline-downloads, /users/listening/settings and /users/listening/profiles (the remove warnings), /users/admin/activity + the web-player/account.png, account-listening-sync.png and book-place-offer.png screenshots
Generated characters, recaps and descriptions: .audiosilo/ (the server's library/attachments.go, metadata/attachments.go, catalog/attachments.go, meta/generated.go; the Bridge's internal/generate, internal/pipeline/describe_stage.go), the console's Description part (describe-section.tsx) or the player's generate action, mark and About (src/components/bridge/, GeneratedMark, aboutContent)bridge/attachments.md + bridge/generating.md + server/scanner.md + the /meta generated content + frontend/book-page.md (and its About) + /users/admin/generating-characters-and-recaps, /users/listening/recaps-and-characters, /users/listening/book-page (About) + the admin/book-description.png and web-player/book-about-generated.png screenshots
Community matching: internal/matchrun (Classify, ReviewFloor, tidyTitle, workers, maxRequestsPerSecond, maxFailStreak), internal/meta/match.go, internal/meta/pacer.go, a run's waits in internal/meta/client.go, the tag hints (metadata.setHints, 0067), the recorded match (catalog/bookmatches.go, book_matches, 0069, 0070, catalog.matchedExpr, the book aside's Community card and Unlink, the match dialog's match), health/bulk-match.tsx, the Add it link (lib/meta-site.ts, add-to-community.tsx) and the not-matched notice (unmatched-prompt.tsx); works/match's params and expand in audiosilo-metathe reference (outcomes, scopes, what a run asks of the service) and its match endpoint + configuration.md (the waits) + data-model.md (and book_matches under durable per-library config) + scanner.md + web-ui.md + meta/api.md (and its rate limit, which names workers and maxRequestsPerSecond) + the cross-repo contract (after the workspace CROSS-REPO.md §17) + /users/admin/health#matching-every-book-at-once, /users/admin/books#matching-with-community-metadata (and #books-matched-to-a-store-listing, #unlinking-a-community-match), /users/admin/activity (the coverage wording), /users/admin/server#community-metadata, /users/faq (what matching sends), /users/community/meta-site#adding-a-missing-book (Add it) + the site's src/pages/metadata.astro (privacy copy, kept in step with the console's health.bulkMatch.privacy) + the admin/health-bulk-match.png and admin/book-community-match.png screenshots
Other recordings of a work (server#241): the server's catalog.workIDExpr (Book.work_id), catalog/otherrecordings.go (OtherRecordings, InProgress), meta.pickRank and local_others in meta/local.go, 0079, the other_recordings capability, the upcoming job's resolve-only run (Options.Resolve); the player's other-recordings.tsx, recording-row.tsx, recordings-picker.tsx and the one-entry-per-work model in series-model.ts (workEntry, groupByWork, recordingCounts)the reference (work_id on /books, local_others and the pick, /next) + api/index.md + data-model.md (and 0079, the upcoming_owned generation rule in overview.md) + configuration.md + the cross-repo contract (after the workspace CROSS-REPO.md §8 and §17) + frontend/book-page.md and library-and-browse.md + /users/listening/book-page#more-than-one-recording-of-a-book, /users/listening/browsing (series cards and pages), /users/listening/end-of-book, /users/getting-started/organizing-your-library, /users/admin/books#recordings-of-the-same-book, /users/admin/server (the upcoming switch) + the web-player/book-other-recordings.png and series-recordings.png screenshots (the pass in capture-web.mjs, run.sh section 2f)
The unknown-ASIN report (LibraForge C3): the server's internal/coverage, catalog/coverage.go (UnknownASINCandidates), meta/report.go, unknown_asin_reports (0068), the unknown_asin_report server state, metadata.report_unknown and metadata.report_status, Settings > Metadata's Help complete the community database switch; metaserve's intake queueconfiguration.md + the reference (metadata.report_unknown, metadata.report_status) + data-model.md + the cross-repo contract + meta/api.md and meta/sync-bot.md + /users/admin/server#helping-complete-the-community-database, /users/admin/books, /users/admin/health (tag hints), /users/faq (what is sent) + the admin/settings-metadata.png screenshot
Listening imports: internal/importer (the ABS client and its codes, abs_certificate among them; matching, planning, identifiersFor), catalog/imports.go, the match hints (catalog/hints.go, book_hints, 0074, matchrun.QueryFor's order), the console's features/imports/ (ImportFlow, also in the setup flow's abs step)the reference (its identifiers) + data-model.md (and match hints) + web-ui.md (the abs step) + /users/admin/import, /users/getting-started/coming-from-audiobookshelf, /users/getting-started/first-run (step 6), /users/admin/health (Audiobookshelf's ASINs and ISBNs) + the admin/settings-import.png and setup/abs.png screenshots
Metadata mirror mode (metadata.mode, internal/metamirror, internal/meta/mirror.go, the Source card, the mirror panel on Health > System)server/configuration.md + the mirror routes in api/reference.md + /users/admin/server (Keeping a local copy), /users/admin/health (the local copy), /users/faq (privacy)
pkg/query, pkg/query/querytest, pkg/release in audiosilo-meta, or the artifact schemameta/overview.md + meta/data-model.md + the cross-repo contract (mirror-mode servers read the artifact directly)
Page revision dates in audiosilo-meta: internal/revision (what a page's digest covers, fields.go), page_revisions, metabuild's --previous / --revised-at / --previous-tag, release.yml's previous-release fetch and reset_revisions, metaserve's <lastmod>, dateModified and Last-Modified, the image's REVISION stampmeta/overview.md (and the published image) + meta/data-model.md + meta/api.md (and the validators under HTML routes and sitemaps, the -version row of Flags)
Meta schemas, metaserve API, or intake tooling (route.yml, the intake denylist included)meta developer pages (data model, API, contributing) - and the cross-repo contract when the server's /meta envelope is affected, and /users/community/contributing-from-your-server when the limits that hold a Bridge's submission change
meta.audiosilo.app site UI/users/community/meta-site + the meta/ screenshots (+ meta/overview.md when it is a site-architecture change)
The Docker entrypoint (docker-entrypoint.sh: PUID/PGID, the chown and the folder checks) or the folder permission wording (internal/fsaccess, a backup's permission_denied)configuration.md + /users/troubleshooting#permission-denied (it quotes the log lines verbatim) + the install pages (/users/getting-started/quickstart-docker, install-synology, install-unraid)
Build / release / distributionrelease-pipeline.md + releasing.md (+ /users/getting-started/install-unraid when the native archives or the LinuxServer.io image's template, paths or defaults change)
A capability flagserver/api/index.md + the feature's user page
The shared design tokens (audiosilo-server/admin-ui/src/styles/globals.css: colours, font stacks, shadows, motion)Section 2 (shared tokens) of this site's src/css/custom.css, copied across verbatim (the dark block stays inside its @media screen wrapper), then a look at the built site in light and dark
tip

When you flip something from "planned" to "shipped" (WebSocket sync or uploads), search the whole docs tree for the feature name - several pages deliberately mark these as not-yet-shipped.

Screenshots​

Every embedded image is listed in screenshots/manifest.mjs and lives under static/img/screenshots/. The pipeline (screenshots/run.sh) rebuilds the server, seeds a small public-domain LibriVox library, runs a demo-mode server, and captures the web player, admin console, connect page, the first-run setup page and console flow (on a second, --setup server) and, when the audiosilo-bridge checkout is there, the Bridge's own page (a real Bridge paired with the demo server, capture-bridge.mjs) with Playwright. Anything it can't reach gets a labelled placeholder so the build never breaks.

Rules that keep this maintainable:

  1. Pages embed only manifest-listed images. Add the manifest entry first.
  2. Never hand-edit a generated screenshot - fix the capture script or the seeded state, then re-run; otherwise the next regeneration loses your edit.
  3. UI changed? Re-run screenshots/run.sh and commit the refreshed images alongside the docs change.

Adding a page​

  1. Create the .md file under docs-users/ or docs-developers/ with title: and description: frontmatter (body starts at ##; the title: already renders as the page heading, so do not repeat it).
  2. Add its id to the matching sidebars-*.ts - sidebars are hand-written so reading order stays deliberate; the build fails if the ids drift.
  3. Link related pages with relative .md links (validated at build time).
  4. npm run build.

Writing style​

User Guide readability rules​

The User Guide is read by people who just want to get something done. A user called an earlier version "word salad" because answers were buried in long, exhaustive pages. These rules keep it readable. Check every User Guide change against them.

  1. Open with what it does and how to use it, in 2-3 sentences. Say up front if the feature needs an admin, a Bridge or a particular app.
  2. Short sentences, one idea per paragraph. Aim for under 20 words a sentence and split anything over 30. Keep paragraphs to 1-3 sentences.
  3. Steps are numbered lists. One action per step, UI labels in bold.
  4. No internal names. No phase or track names, issue or PR numbers, decision ids, code identifiers, source paths or API routes. Config keys and environment variables appear only where the reader has to type them.
  5. Titles are tasks ("Listen offline", "Back up your server"), not components ("Offline downloads", "The companion"). Keep the file name, so the URL stays stable.
  6. Basics first, edge cases last. The common path comes first. Rare cases go in a short "Good to know" section at the end or in Troubleshooting.
  7. No version history. Describe what the product does now. Name a minimum version only when the reader must update for something to work, in one line.
  8. Describe the normal path, not every state. Don't quote every label, status and error message. Error messages belong in Troubleshooting.
  9. Say it once. Each fact lives on one page; other pages link to it.
  10. Keep pages short. Most pages stay under about 800 words. A page past 1,500 words is cut or split.
  11. One Features page. Features lists every feature in one line with a link. A new user-visible feature adds its line there in the same change.

Cut, don't add. When you update a page, look for something to remove as well. Accuracy still comes first: check behaviour in the source before you write it down.

Keep links working. Other pages, the apps and the console link to User Guide pages and headings. When you rename a heading, keep its old anchor with an explicit id: ## Download a book {/* #downloading-a-book */}. Cross-referenced headings use a colon or rephrase rather than a dash, so their anchors stay clean. Moving or renaming a page file needs a redirect, so prefer changing only its title:.

The Developer Docs follow rules 2, 3, 6, 7 and 9 too, and the "Keep links working" note. They may name code. Under rule 7 they keep a version only where one side must still handle an older peer, and never name a phase, a track or a PR.

Wording​

These apply to the User Guide and the Developer Docs.

  • Say what it does, not how it feels. Name the step, the mechanism or the number. "Downloaded books play with no connection", not "your library is always within reach". If a sentence about AudioSilo could appear unchanged in another project's docs, cut it.
  • Name who does what. "The server scans the folder", not "the folder is scanned". Use the passive only when the actor does not matter.
  • No colon as a mid-sentence connector. A colon introduces a list, an example, a figure, a definition or a labelled item. Anywhere else, write two sentences.
  • Plain and literal. No metaphors, slogans or sentence fragments for effect. Never "simply", "easily" or "just" in a step. Instead of "much faster", give the measured figure. With no figure, say what changes.
  • One name per thing. Use the label the reader sees in the product, or the real symbol in the Developer Docs, and keep it for the whole page. Do not switch between "the console", "the admin page" and "the dashboard".
  • Numbered steps start with the goal and end with the result. "To share a book, open its page and select Share." After the last step, say what the reader should now see. A checklist needs neither.
  • Links say where they go. Link text is the page's title or a short description, never "here" or "this page".
  • A rule never beats a clear sentence. Short does not mean clipped. Keep a longer sentence when it carries one idea with its condition. If a rule makes a sentence worse, rewrite the sentence another way.

Three more for the Developer Docs:

  • Whole sentences. Keep "the" and "a", give every clause a verb, and spell out arrows and slashes in prose. "The parser rejects a bad date and writes nothing", not "bad date -> no write". Arrows and slashes inside code notation are fine. A parenthesis holds one complete aside, and a second one in the same sentence becomes its own sentence. A symbol or path cited in parentheses is not an aside.
  • Grow a page by restructuring it. When a release changes a behaviour, rewrite the sentence that describes it. Do not add a clause, a parenthesis or a version tag to the old one.
  • One kind of page. A page is a how-to (steps to a goal), a reference (facts to look up) or an explanation (why it works this way). When a page starts doing two of these, split it and link.

Formatting​

  • No em dashes, and few spaced hyphens. Do not use the em dash character. It also produces messy heading anchors. A spaced hyphen (-) in the middle of a sentence is the same habit, so prefer a full stop or a comma. A list item written as a label, a hyphen and its text is fine. The one exception: a code block that reproduces literal program output verbatim must match the source, em dashes included (no current output contains one).
  • Admonition titles go in brackets. Write :::note[Title] (also tip, info, warning, danger, caution), then the body, then a closing :::. The old :::note Title form no longer parses on this site (future.v4 turns off markdown.mdx1Compat.admonitions) and shows up as literal :::note Title text, so the build rejects it. A bare :::note without a title is fine.

Deployment​

Pushes to main build and publish the site via GitHub Actions (.github/workflows/deploy.yml) to GitHub Pages. The site serves at its custom domain docs.audiosilo.app: docusaurus.config.ts sets url/baseUrl and a static/CNAME file is committed.