Refactor documentation for consistency and clarity

Author: stephenway

docs/.vitepress/build-meta.json

@@ -1,5 +1,5 @@
 {
   "contractVersion": "1.0.2",
   "schemaHash": "sha256-07239d0e1a46c781c78b3ae70db52acceeb8dc17e431cd64858e23ad0e61020d",
-  "buildTime": "2026-02-24T21:38:31.100Z"
+  "buildTime": "2026-02-24T22:35:08.063Z"
 }

docs/.vitepress/config.mts

@@ -7,15 +7,15 @@ if (base !== '/' && !base.endsWith('/')) base += '/';
 
 export default defineConfig({
   title: 'Majestic Core',
-  description: 'Technical documentation — architecture, API contracts, invariants',
+  description: 'Technical documentation: architecture, API contracts, invariants',
   base,
   lang: 'en-US',
 
   head: [
     ['link', { rel: 'icon', href: `${base === '/' ? '/' : base}logo.svg`, type: 'image/svg+xml' }],
   ],
 
-  appearance: 'force-dark', // Match Svelte app — dark only, no toggle
+  appearance: 'force-dark', // Match Svelte app (dark only, no toggle)
 
   themeConfig: {
     logo: '/logo.svg',

docs/.vitepress/theme/index.ts

@@ -2,7 +2,7 @@ import DefaultTheme from 'vitepress/theme';
 import { h } from 'vue';
 import './majestic.css';
 
-// Build meta written by prepare.mjs — import path relative to theme
+// Build meta written by prepare.mjs (import path relative to theme)
 // @ts-expect-error JSON import
 import buildMeta from '../build-meta.json';
 
@@ -20,7 +20,7 @@ export default {
           },
           innerHTML: `
             <p style="font-size: 0.75rem; color: var(--vp-c-text-3); margin: 0;">
-              Contract: ${(buildMeta as { contractVersion?: string }).contractVersion || '—'} · Hash: ${(buildMeta as { schemaHash?: string }).schemaHash || '—'} · Built: ${(buildMeta as { buildTime?: string }).buildTime || '—'}
+              Contract: ${(buildMeta as { contractVersion?: string }).contractVersion || '-'} · Hash: ${(buildMeta as { schemaHash?: string }).schemaHash || '-'} · Built: ${(buildMeta as { buildTime?: string }).buildTime || '-'}
             </p>
           `,
         }),

docs/.vitepress/theme/majestic.css

@@ -1,32 +1,32 @@
 /**
- * Majestic brand palette — matches Svelte app (majestic-server app.css, tailwind)
+ * Majestic brand palette: matches Svelte app (majestic-server app.css, tailwind)
  * Dark theme only. Spec site, not marketing.
  */
 :root,
 .dark {
-  /* Backgrounds — brand-void, charcoal, ash */
+  /* Backgrounds: brand-void, charcoal, ash */
   --vp-c-bg: #0f0d0b;
   --vp-c-bg-alt: #1a1814;
   --vp-c-bg-elv: #252219;
   --vp-c-bg-soft: #252219;
 
-  /* Text — brand-bone, muted, subtle */
+  /* Text: brand-bone, muted, subtle */
   --vp-c-text-1: #e8e2d8;
   --vp-c-text-2: #b8b0a4;
   --vp-c-text-3: #8a8378;
 
-  /* Brand accent — espresso gold */
+  /* Brand accent: espresso gold */
   --vp-c-brand-1: #a67b4a;
   --vp-c-brand-2: #c9a065;
   --vp-c-brand-3: #8e6b3a;
   --vp-c-brand-soft: rgba(166, 123, 74, 0.15);
 
-  /* Borders — subtle bone tint */
+  /* Borders: subtle bone tint */
   --vp-c-border: rgba(232, 226, 216, 0.12);
   --vp-c-divider: rgba(232, 226, 216, 0.08);
   --vp-c-gutter: rgba(0, 0, 0, 0.4);
 
-  /* Default/gray — warm neutrals */
+  /* Default/gray: warm neutrals */
   --vp-c-default-1: #8a8378;
   --vp-c-default-2: #6a6358;
   --vp-c-default-3: #4a4338;

docs/architecture/capability-modeling.md

@@ -1,12 +1,12 @@
-# Capability Modeling — Design Blueprint
+# Capability Modeling - Design Blueprint
 
 **Principle:** Store facts. Compute opinions.
 
 ---
 
-## Layer 1 — Media Capability Profile (Database)
+## Layer 1 - Media Capability Profile (Database)
 
-Store normalized fields only. Do NOT store `direct_play_compatible` or `compatibility_reason` — those are computed.
+Store normalized fields only. Do NOT store `direct_play_compatible` or `compatibility_reason` - those are computed.
 
 ### Video
 - `video_codec` (h264, hevc, vp9, av1)
@@ -30,11 +30,11 @@ Store normalized fields only. Do NOT store `direct_play_compatible` or `compatib
 - `probe_state` (`ok` | `failed` | `unknown`)
 - `probe_error` (short string when failed)
 - `probe_version` (optional, for invalidation)
-- `probe_last_run_at` (when probe last ran — observability for "why is this unknown?")
+- `probe_last_run_at` (when probe last ran - observability for "why is this unknown?")
 
 ---
 
-## Step 1 — Probe Module
+## Step 1 - Probe Module
 
 **Location:** `src/lib/server/probe/ffprobe.ts`
 
@@ -69,7 +69,7 @@ Store normalized fields only. Do NOT store `direct_play_compatible` or `compatib
 
 ---
 
-## Step 2 — When to Probe
+## Step 2 - When to Probe
 
 On scan:
 - **New file** → probe
@@ -84,7 +84,7 @@ If probe fails:
 
 ---
 
-## Step 3 — Device Profile (Apple TV)
+## Step 3 - Device Profile (Apple TV)
 
 Static object, versioned:
 
@@ -114,7 +114,7 @@ type DeviceProfile = {
 
 ---
 
-## Step 4 — Evaluate Function
+## Step 4 - Evaluate Function
 
 Pure function:
 ```ts

docs/architecture/curated-api.md

@@ -1,12 +1,12 @@
-# Majestic Curated API — Cloudflare Shared Data Layer
+# Majestic Curated API - Cloudflare Shared Data Layer
 
 > **DEPRECATED.** The metadata/enrichment layer described here is superseded by [majestic-canon](../strategy/authoritative-data-distribution-dissection.md#15-canon-architecture--three-layers). Canon uses authoritative data distribution (signed patch packs) instead of live API. This document is retained for historical context and optional live-assist fallback design. **See majestic-canon for the canonical dataset source.**
 
 ---
 
 **Purpose (historical):** Centralize movie, edition, person, and studio data for all paid Majestic server installs. Prior matched movies and editions become available to every paid instance, reducing TMDB/OMDb lookups and improving edition matching accuracy.
 
-**Context:** TMDB models Movie as atomic. Multi-version (theatrical vs director's cut, etc.) has been in their backlog since 2019—it requires a parent/child ontology they don't have. Majestic designed Movie → Edition from day one. The Curated API was the interim design. **majestic-canon** is the target: patch-based distribution, not live API.
+**Context:** TMDB models Movie as atomic. Multi-version (theatrical vs director's cut, etc.) has been in their backlog since 2019 - it requires a parent/child ontology they don't have. Majestic designed Movie → Edition from day one. The Curated API was the interim design. **majestic-canon** is the target: patch-based distribution, not live API.
 
 **Status:** Deprecated. Superseded by majestic-canon. Optional live-assist fallback only (under 5% of lookups).
 
@@ -312,12 +312,12 @@ Not required at launch. Build when telemetry schema exists and installs are live
 ## 11. Implementation Order
 
 1. **Design doc** (this document) ✓
-2. **Roadmap phase** — Add Phase 1.5 to ROADMAP
-3. **curatedApiClient** — Minimal client: `lookupByTitleYear`, `lookupByUpc`. No-op when unconfigured.
-4. **Scanner integration** — Call client before local DB when parsing filename/folder. Fallback unchanged.
-5. **Cloudflare Workers** — Deploy read-only API. D1 or R2 backend. Auth middleware.
-6. **Edition Validation 100** — Seed dataset. Verify matching correctness.
-7. **Barcode integration** — Call `GET /editions/upc/:upc` in barcodeService before UPCMDB.
+2. **Roadmap phase** - Add Phase 1.5 to ROADMAP
+3. **curatedApiClient** - Minimal client: `lookupByTitleYear`, `lookupByUpc`. No-op when unconfigured.
+4. **Scanner integration** - Call client before local DB when parsing filename/folder. Fallback unchanged.
+5. **Cloudflare Workers** - Deploy read-only API. D1 or R2 backend. Auth middleware.
+6. **Edition Validation 100** - Seed dataset. Verify matching correctness.
+7. **Barcode integration** - Call `GET /editions/upc/:upc` in barcodeService before UPCMDB.
 
 ---
 
@@ -343,4 +343,4 @@ Curated API does not compromise foundational principles. Keep it boring. Keep it
 | **Dataset corrections retroactively alter identity** | Never silently mutate identity_hash or UPC normalization. Dataset improvements must be additive, not destructive. Version-signal any logic change. |
 | **Latency creep** | 500ms is hard. Not advisory. If lookup drifts to 900ms, 1.2s, 2s, scanner UX degrades. Enforce at client. |
 | **Curated API becomes "better TMDB"** | Stay narrow. Store identity-critical edition data, canonical film linkage, deterministic match keys. Do not become a general-purpose metadata mirror, popularity engine, or review aggregation system. Let TMDB chase popularity. Majestic chases correctness. |
-| **Identity vs engagement data mixing** | Alternate overviews, cut-specific runtime, cast differences—fine if identity-critical. Do not store user taste signals, popularity adjustments, ranking hints, or behavioral metadata. The moment you mix identity with engagement, you blur the contract. Curated layer = edition correctness. Nothing else. |
+| **Identity vs engagement data mixing** | Alternate overviews, cut-specific runtime, cast differences - fine if identity-critical. Do not store user taste signals, popularity adjustments, ranking hints, or behavioral metadata. The moment you mix identity with engagement, you blur the contract. Curated layer = edition correctness. Nothing else. |

docs/architecture/edition-grouping.md

@@ -1,4 +1,4 @@
-# Edition Grouping — Design
+# Edition Grouping - Design
 
 **Principle:** Server owns truth. Client renders it.
 
@@ -8,7 +8,7 @@ Edition grouping is the first feature that makes someone say: "Wait… this actu
 
 ## What It Must Do
 
-1. **Group by `movie_id`** — Multiple media files for the same movie become one row with multiple editions.
+1. **Group by `movie_id`** - Multiple media files for the same movie become one row with multiple editions.
 
 2. **Editions listed with:**
    - Edition label (override > computed > canonical)
@@ -81,14 +81,14 @@ Priority: override > computed > canonical (when variants exist) > format.
 
 Reuse `resolveEditionLabelForPoster` logic where applicable.
 
-**Critical:** Edition labels must be **deterministic, cached, and not re-derived on every scan** from heuristics. If filename/folder parsing is used, it must produce a **normalized, stored label** — not a live guess. You're building a library, not a regex experiment.
+**Critical:** Edition labels must be **deterministic, cached, and not re-derived on every scan** from heuristics. If filename/folder parsing is used, it must produce a **normalized, stored label** - not a live guess. You're building a library, not a regex experiment.
 
 **Label survival:** Labels must survive file deletion and re-add. If a file is removed and later re-imported with the same fingerprint → same edition → same label. Label storage must be anchored to **media_file identity** (fingerprint or media_file_id), not to path. If labels depend on current folder path and get regenerated on re-import, you introduce drift.
 
 For media files without disc_edition linkage:
 
 - Store derived label (e.g. in media_file or a join table) at scan/match time
-- Anchor to fingerprint or media_file_id — not path
+- Anchor to fingerprint or media_file_id - not path
 - Fallback: "Edition 1", "Edition 2" (deterministic by media_file_id)
 
 ---
@@ -103,7 +103,7 @@ Criteria (in order):
 2. Resolution descending (4K before 1080p)
 3. media_file_id ascending (tie-breaker)
 
-**What we avoid:** Bitrate comparisons, "best HDR wins," audio heuristics, device-dependent reordering. If ordering depends on device, the UI feels unstable — the same movie reorders when device changes. Canonical first. Always.
+**What we avoid:** Bitrate comparisons, "best HDR wins," audio heuristics, device-dependent reordering. If ordering depends on device, the UI feels unstable - the same movie reorders when device changes. Canonical first. Always.
 
 ---
 
@@ -138,9 +138,9 @@ You do not want a movie to show "Playable" while one edition is flagged as corru
 
 ```
 Editions
-• Theatrical — 4K HDR10 · Direct Play Ready
-• Director's Cut — 1080p SDR · Direct Play Ready
-• Steelbook — DV P7 · Not Supported on Apple TV
+• Theatrical - 4K HDR10 · Direct Play Ready
+• Director's Cut - 1080p SDR · Direct Play Ready
+• Steelbook - DV P7 · Not Supported on Apple TV
 ```
 
 Each selectable. Each with capability summary + compatibility status.
@@ -154,10 +154,10 @@ Default selection = first (canonical). User can change. Play uses selected editi
 ## What Not to Do
 
 - **No silent auto-picking** when multiple editions exist
-- **No client-side grouping** — server aggregates
-- **No grid performance degradation** — aggregation is a server concern
-- **No guessing** — explicit selection required
-- **No "best available" collapse** — never auto-play or auto-select "best edition on this device." That is how you become Plex again. Majestic does not optimize away choice. It exposes it.
+- **No client-side grouping** - server aggregates
+- **No grid performance degradation** - aggregation is a server concern
+- **No guessing** - explicit selection required
+- **No "best available" collapse** - never auto-play or auto-select "best edition on this device." That is how you become Plex again. Majestic does not optimize away choice. It exposes it.
 
 ---
 
@@ -169,11 +169,11 @@ Default selection = first (canonical). User can change. Play uses selected editi
 
 ## Implementation Order
 
-1. **Schema (if needed):** Edition label storage — ensure derived labels are cached, not recomputed per request
+1. **Schema (if needed):** Edition label storage - ensure derived labels are cached, not recomputed per request
 2. **API:** New `/library` response shape with `editions` array, `default_edition_index`
-3. **API:** Aggregation logic — group media_files by movie_id, build editions array
+3. **API:** Aggregation logic - group media_files by movie_id, build editions array
 4. **API:** Edition label resolution (from stored/cached source), canonical ordering
-5. **API:** Badge priority — worst status across editions
+5. **API:** Badge priority - worst status across editions
 6. **Apple TV:** Update model for new response shape
 7. **Apple TV:** Grid uses movie-level items (one poster per movie)
 8. **Apple TV:** Detail page shows Editions section when count > 1

docs/architecture/identity-layer.md

@@ -1,6 +1,6 @@
 # Identity Layer
 
-The identity layer defines how Majestic models ownership and edition truth. Edition identity is derived from content-derived inputs—never from paths, filenames, or mutable metadata.
+The identity layer defines how Majestic models ownership and edition truth. Edition identity is derived from content-derived inputs - never from paths, filenames, or mutable metadata.
 
 ## Principles
 

docs/architecture/identity-matching.md

@@ -4,15 +4,15 @@ Majestic matches media files to movies using a deterministic priority order. The
 
 ## Resolution Order
 
-1. **Per-file `.majestic.json`** — `{filename}.majestic.json` in the same directory (e.g. `A New Standard.mkv.majestic.json`). Overrides directory-level for this file only. Use when a shared extras folder contains files from different movies.
+1. **Per-file `.majestic.json`** - `{filename}.majestic.json` in the same directory (e.g. `A New Standard.mkv.majestic.json`). Overrides directory-level for this file only. Use when a shared extras folder contains files from different movies.
 
-2. **Directory-level `.majestic.json`** — `.majestic.json` in the file's directory. Applies to all files in that folder. Written automatically when you resolve or re-match in the UI.
+2. **Directory-level `.majestic.json`** - `.majestic.json` in the file's directory. Applies to all files in that folder. Written automatically when you resolve or re-match in the UI.
 
-3. **Filename parsing** — `Title (Year).mkv`, `Title (Year) [Steelbook].mkv`, etc.
+3. **Filename parsing** - `Title (Year).mkv`, `Title (Year) [Steelbook].mkv`, etc.
 
-4. **Folder name parsing** — Parent directory name.
+4. **Folder name parsing** - Parent directory name.
 
-5. **User confirmation** — Unresolved or ambiguous matches appear in Settings → Unresolved.
+5. **User confirmation** - Unresolved or ambiguous matches appear in Settings → Unresolved.
 
 ## What `.majestic.json` Contains
 
@@ -47,10 +47,10 @@ The matcher still **reads** `.majestic.json` if present; it just **skips writing
 
 ## Why This Design
 
-- **DB is source of truth** — Survives rescans, renames, restarts. Scanner respects existing `media_file.movie_id`.
-- **Per-file override** — Shared extras folders (e.g. `Extras/` with files from multiple movies) can use per-file `.majestic.json` to avoid directory-level overreach.
-- **No file mutation** — We never modify the media file itself. Only metadata.
-- **Transparent** — A visible JSON file in the folder. Users who organize by folder can inspect or edit it.
+- **DB is source of truth** - Survives rescans, renames, restarts. Scanner respects existing `media_file.movie_id`.
+- **Per-file override** - Shared extras folders (e.g. `Extras/` with files from multiple movies) can use per-file `.majestic.json` to avoid directory-level overreach.
+- **No file mutation** - We never modify the media file itself. Only metadata.
+- **Transparent** - A visible JSON file in the folder. Users who organize by folder can inspect or edit it.
 
 ## Target Audience