pretty

backlog/archive/milestones/m-0 - codebase-clarity-&-composability.md

@@ -1,6 +1,6 @@
 ---
 id: m-0
-title: "Codebase Clarity & Composability"
+title: 'Codebase Clarity & Composability'
 ---
 
 ## Description

backlog/archive/tasks/task-19 - Enable-overlay-keybinds-whenever-app-runtime-is-active.md

@@ -13,12 +13,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Restored task after accidental cleanup. Ensure keybindings are available whenever the Electron runtime is active, while respecting focused overlay/input contexts that require local key handling.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Started implementation: tracing overlay shortcut registration lifecycle and runtime activation gating.
 
 Root cause: overlay shortcut sync executes during overlay runtime initialization before overlayRuntimeInitialized is set true, so registration could be skipped until a later visibility toggle.
@@ -32,12 +35,15 @@ Updated CLI runtime gating so --start initializes overlay runtime, which activat
 User clarified MPV-only workflow requirement. Added MPV plugin keybindings and script messages for mining/runtime actions (copy/mine/multi/mode/field-grouping/subsync/audio-card/runtime-options) so these actions are available from mpv chord bindings without relying on overlay global shortcuts.
 
 Per user direction, reverted all shortcut/runtime/plugin changes from this implementation cycle. Desired behavior is to keep keybindings working only when overlay is active.
+
 <!-- SECTION:NOTES:END -->
 
 ## Final Summary
 
 <!-- SECTION:FINAL_SUMMARY:BEGIN -->
+
 Ensured overlay shortcuts are available as soon as overlay runtime becomes active by resyncing after activation flag is set. This prevents startup states where shortcuts remained inactive until a later overlay visibility change.
 
 Follow-up fix: included --start in overlay-runtime-required commands so keybinds are active right after startup, even before toggling visible/invisible overlays.
+
 <!-- SECTION:FINAL_SUMMARY:END -->

backlog/archive/tasks/task-20 - Implement-content-bounded-overlay-windows-and-decoupled-secondary-top-bar.md

@@ -13,11 +13,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement the overlay sizing redesign documented in `overlay_window.md`: move visible/invisible overlays from fullscreen bounds to content-bounded sizing, and decouple secondary subtitle rendering into an independent top bar window/lifecycle.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Per-layer bounds ownership is implemented for overlay windows (no shared full-bounds setter for all layers).
 - [ ] #2 Renderer-to-main IPC contract exists for measured overlay content bounds with layer identity and safe validation.
 - [ ] #3 Visible and invisible overlays use content-bounded sizing with padding/clamp/jitter protections and full-bounds fallback when measurements are unavailable.

backlog/archive/tasks/task-20.3 - Implement-content-bounded-sizing-algorithm-for-visible-and-invisible-overlay-windows.md

@@ -16,11 +16,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement content-bounded sizing for visible/invisible windows using measured rects plus tracker origin, with robust clamping and jitter resistance.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Bounds algorithm applies configurable padding, minimum size, display-workarea clamp, and integer snap.
 - [ ] #2 Main-process bounds updates are thresholded/debounced to reduce jitter and unnecessary `setBounds` churn.
 - [ ] #3 When no valid measurement exists, layer falls back to safe tracker/display bounds without breaking interaction.

backlog/archive/tasks/task-20.4 - Implement-dedicated-secondary-top-bar-overlay-window.md

@@ -13,11 +13,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Create and integrate a dedicated secondary subtitle overlay window with independent lifecycle, z-order, bounds, and pointer policy, decoupled from primary visible/invisible overlay windows.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 A third overlay window dedicated to secondary subtitles is created and managed alongside existing visible/invisible windows.
 - [ ] #2 Secondary window visibility follows secondary mode semantics (`hidden`/`visible`/`hover`) independent of primary overlay visibility.
 - [ ] #3 Secondary subtitle text/mode/style updates are routed directly to the secondary window renderer path.

backlog/archive/tasks/task-20.5 - Add-rollout-guards-tests-and-validation-matrix-for-content-bounded-overlays.md

@@ -13,11 +13,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add safety controls and verification coverage for the new content-bounded overlay architecture and secondary top-bar window.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Feature flag or equivalent rollout guard exists for switching to new sizing/window behavior.
 - [ ] #2 Service-level/unit tests cover bounds clamping, jitter thresholding, invalid measurement fallback, and per-layer updates.
 - [ ] #3 Manual validation checklist documents and verifies wrap/no-wrap, style changes, monitor moves, tracker churn, modal interactions, and simultaneous overlay states.

backlog/archive/tasks/task-22 - Make-secondary-subtitles-hover-revealed-but-non-lookupable-in-Yomitan-sessions.md

@@ -12,11 +12,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Investigate and implement a UX where secondary subtitles (e.g., English text in our current sessions) become visible when hovered, while explicitly preventing user interactions that allow text lookup (including Yomitan integration) on those subtitles. This should allow readability-on-hover without exposing the secondary overlay text to selection/lookup workflows.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Secondary subtitles become visible only while hovered (or via equivalent hover-triggered mechanism), and return to default hidden/low-visibility state when not hovered.
 - [ ] #2 When hovered, secondary subtitles do not trigger Yomitan lookup behavior in sessions where Yomitan is enabled.
 - [ ] #3 Secondary subtitles remain non-interactive for lookup paths (for example, text selection or lookup event propagation) while hover-visibility still works as intended.
@@ -25,6 +29,8 @@ Investigate and implement a UX where secondary subtitles (e.g., English text in
 <!-- AC:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Acceptance criteria are reviewed and covered by explicit manual/automated test coverage for hover reveal and lookup suppression behavior.
 <!-- DOD:END -->

backlog/archive/tasks/task-30 - Enable-anime-streaming-via-extension-repos-with-configurable-mpv-playback-flow.md

@@ -13,13 +13,17 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add a feature to query configured extension repositories for anime titles/episodes from SubMiner, let users select a streamable source, and play it through mpv with minimal friction. The result should be interactive from Electron (and triggered from mpv via existing command bridge), and fully configurable in app config.
 
 The implementation should provide a modular backend resolver and a clear UI flow that mirrors existing modal interaction patterns, while keeping mpv playback unchanged (use loadfile with resolved URL and optional headers/referrer metadata).
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Create a stable config schema for one or more extension source backends (repos/endpoints/flags) and persist in user config + default template.
 - [ ] #2 Resolve an anime search term to candidate series from configured sources.
 - [ ] #3 Resolve an episode selection to at least one playable stream URL candidate with playback metadata when available.
@@ -32,13 +36,17 @@ The implementation should provide a modular backend resolver and a clear UI flow
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Execution sequence for implementation: 1) TASK-30.1 (config/model), 2) TASK-30.2 (resolver), 3) TASK-30.3 (IPC), 4) TASK-30.4 (UI modal), 5) TASK-30.5 (mpv trigger), 6) TASK-30.6 (validation/rollout checklist).
 
 Rollout recommendation: complete TASK-30.6 only after TASK-30.1-30.5 are done and can be verified in combination.
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Config schema validated in app startup (bad config surfaces clear error).
 - [ ] #2 No hardcoded source/resolver URLs in UI layer; resolver details are backend-driven.
 - [ ] #3 Play command path uses existing mpv IPC/runtime helpers.

backlog/archive/tasks/task-30.1 - Design-extension-source-config-model-and-defaults.md

@@ -14,11 +14,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Define a backend-agnostic configuration contract for extension repository streaming, including resolver endpoints/process mode, query/auth headers, timeouts, enable flags, and source preference. Wire schema through Config/ResolvedConfig and generated template/defaults so users can manage repos entirely through config.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Add new config sections for extension source providers in Config and ResolvedConfig types.
 - [ ] #2 Add validation defaults and env-compatible parsing for provider list, auth, header overrides, and feature flags.
 - [ ] #3 Update config template and docs text so defaults are discoverable and editable.
@@ -29,11 +33,15 @@ Define a backend-agnostic configuration contract for extension repository stream
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 1 — Foundation: config contract + validation + defaults
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Config examples in template/docs include at least one provider entry shape.
 - [ ] #2 Defaults remain backward-compatible when key is absent.
 - [ ] #3 Feature can be disabled without touching unrelated settings.

backlog/archive/tasks/task-30.2 - Implement-extension-resolver-service-search-episode-stream-resolution.md

@@ -15,11 +15,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Build a dedicated service in main process that queries configured extension repos and normalizes results into a unified internal model, including optional playback metadata. Keep transport abstracted so future backends (local process, remote API, Manatán-compatible source) can be swapped without changing renderer contracts.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Create a typed internal model for source, series, episode, and playable candidate with fields for quality/audio/headers/referrer/userAgent.
 - [ ] #2 Implement provider abstraction with pluggable fetch/execution strategy from config.
 - [ ] #3 Add services for searchAnime, listEpisodes, resolveStream (or equivalent) with cancellation/error boundaries.
@@ -30,11 +34,15 @@ Build a dedicated service in main process that queries configured extension repo
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 2 — Core service: provider integration and stream resolution
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Resolver never leaks raw provider payload to renderer.
 - [ ] #2 Streaming URL output includes reason for failure when unavailable.
 - [ ] #3 Service boundaries allow unit-level validation of request/response mapping logic.

backlog/archive/tasks/task-30.3 - Expose-resolver-operations-via-Electron-IPC-to-renderer.md

@@ -15,11 +15,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add a typed preload and main-IPC contract for streaming queries and playback resolution so the renderer can initiate search/list/resolve without embedding network/provider logic in UI code.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Define IPC handlers in main with input/output schema validation and timeouts.
 - [ ] #2 Expose corresponding functions in preload `window.electronAPI` and ElectronAPI types.
 - [ ] #3 Reuse existing mpv command channel for playback and add a dedicated request/response flow for resolver actions.
@@ -31,11 +35,15 @@ Add a typed preload and main-IPC contract for streaming queries and playback res
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 3 — API surface: IPC/preload contract for resolver operations
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Renderer code can query providers without importing Node-only modules.
 - [ ] #2 IPC paths have clear names and consistent response shapes across all calls.
 - [ ] #3 Error paths return explicit machine-readable codes mapped to user-visible messages.

backlog/archive/tasks/task-30.4 - Add-interactive-streaming-modal-search-episode-list-source-selection-play.md

@@ -15,11 +15,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement a renderer flow to query configured providers, display results, let user choose series and episode, and trigger playback for a selected stream. The UI should support keyboard interactions and surface backend errors clearly.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Create modal UI/state model for query, results list, selected item, episode list, candidate qualities, and loading/error status.
 - [ ] #2 Wire renderer actions to new IPC methods for search/episode/resolve.
 - [ ] #3 Render one-click or enter-to-play action that calls existing mpv playback pathway.
@@ -31,11 +35,15 @@ Implement a renderer flow to query configured providers, display results, let us
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 4 — UX: interactive modal flow and playback callout
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Modal state is isolated and unsubscribes listeners on close.
 - [ ] #2 No direct network logic in renderer beyond IPC calls.
 - [ ] #3 Visual style and behavior are consistent with existing modal patterns.

backlog/archive/tasks/task-30.5 - Wire-mpv-script-message-shortcut-trigger-into-streaming-modal-and-playback-path.md

@@ -18,11 +18,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Allow users to open streaming selection from within mpv via keybind/menu and route that intent into renderer modal and playback flow without requiring separate window focus changes.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Add/extend mpv Lua plugin or existing command registry to emit a custom action for opening the streaming picker.
 - [ ] #2 Handle this action in main IPC/mpv-command pipeline and forward to renderer modal state.
 - [ ] #3 Add at least one default keybinding/menu entry documented in config/plugin notes.
@@ -33,11 +37,15 @@ Allow users to open streaming selection from within mpv via keybind/menu and rou
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 5 — In-player entry: mpv trigger/menu integration
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 No duplicate mpv command parsing between picker and legacy commands.
 - [ ] #2 Feature can be used in overlay and mpv-only mode where applicable.
 - [ ] #3 No dependency on modal open state when launched by mpv trigger.

backlog/archive/tasks/task-30.6 - Add-integration-validation-plan-and-rollout-checklist-for-anime-streaming-feature.md

@@ -16,11 +16,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Create a concrete validation task that defines end-to-end acceptance checks for config loading, resolver behavior, IPC contract correctness, UI flow, and mpv-triggered launch. The checklist should be actionable and align with existing project conventions so completion can be verified without guesswork.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Define test scenarios for config success/failure cases, including invalid provider config and feature disabled mode.
 - [ ] #2 Define search/list/resolve API contract tests and error-code assertions (empty, timeout, auth error, no playable URL).
 - [ ] #3 Define renderer UX checks for modal state transitions, loading indicators, empty results, selection, and play invocation.
@@ -33,11 +37,15 @@ Create a concrete validation task that defines end-to-end acceptance checks for
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Phase 6 — Validation: rollout, smoke tests, and release readiness checklist
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 Checklist covers happy-path and failure-path for each task dependency.
 - [ ] #2 Verification steps are executable without external tooling assumptions.
 - [ ] #3 No task can be marked done without explicit evidence fields filled in.

backlog/archive/tasks/task-30.7 - Add-English-source-preference-hard-sub-stripping-workflow-in-Aniyomi-streaming-path.md

@@ -17,11 +17,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Improve the Aniyomi/anime extension streaming flow to prefer English-capable sources with soft subtitles, and automatically recover when only hard-subbed streams are available by stripping embedded subtitles with ffmpeg and attaching external Jimaku subtitle files into mpv.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 During source scoring/selection, prefer providers/sources that declare or expose soft subtitles for English audio or subtitle tracks over hard-subbed alternatives.
 - [ ] #2 Add a config option for preferred language targets (default English) and fallback policy (favor soft subtitles, then hard-sub fallback).
 - [ ] #3 Detect when a resolved stream is hard-sub-only and a soft-sub source is unavailable for the same episode.

backlog/archive/tasks/task-30.8 - Add-observability-and-tuning-metrics-for-Aniyomi-subtitle-source-fallback-decisions.md

@@ -16,11 +16,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add lightweight telemetry/analytics hooks (local logs + optional structured counters) to measure how Aniyomi/anime streaming source selection behaves, including soft-sub preference, hard-sub fallback usage, and ffmpeg+Jimaku post-processing outcomes, to support source ranking tuning.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Track per-playback decision metadata including chosen source, language match score, subtitle mode (soft/hard), and reason for source preference ordering.
 - [ ] #2 Emit success/failure counters for hard-sub stripping attempts (started/succeeded/failed/unsupported codec) with reason codes.
 - [ ] #3 Log whether Jimaku subtitle attachment was available and successfully loaded for ffmpeg-assisted flows.

backlog/archive/tasks/task-30.9 - Expose-subtitle-preference-and-ffmpeg-fallback-tuning-controls-in-settings-UI.md

@@ -15,11 +15,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add user-configurable controls for Aniyomi streaming subtitle behavior, including preferred language profile, soft-vs-hard source preference, ffmpeg-assisted hard-sub removal behavior, and policy toggles so quality and fallback behavior can be tuned without code changes.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Add settings UI fields to define preferred subtitle/audiotrack language order (e.g., en, ja) and enable/disable hard-sub fallback mode.
 - [ ] #2 Add explicit toggle for enabling hard-sub stripping via ffmpeg and configurable timeout/quality limits to avoid long waits.
 - [ ] #3 Expose source ranking preferences for soft-sub vs hard-sub sources and optional fallback to native/transcoded source when preferred modes are unavailable.

backlog/archive/tasks/task-43 - Add-community-subtitle-timing-database-for-shared-sync-corrections.md

@@ -16,12 +16,15 @@ priority: low
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Allow users to share their subtitle timing corrections to a community database, so other users watching the same video file get pre-synced subtitles automatically.
 
 ## Motivation
+
 Subtitle synchronization (alass/ffsubsync) is one of the most friction-heavy steps in the mining workflow. Users spend time syncing subtitles that someone else has already synced for the exact same video. A shared database of timing corrections keyed by video file hash would eliminate redundant work.
 
 ## Design
+
 1. **Video identification**: Use a partial file hash (first + last N bytes, or a media fingerprint) to identify video files without uploading content
 2. **Timing data**: Store the timing offset/warp parameters produced by alass/ffsubsync, not the full subtitle file
 3. **Upload flow**: After a successful sync, offer to share the timing correction (opt-in)
@@ -29,6 +32,7 @@ Subtitle synchronization (alass/ffsubsync) is one of the most friction-heavy ste
 5. **Trust model**: Simple upvote/downvote on corrections; show number of users who confirmed a correction works
 
 ## Technical considerations
+
 - Backend could be a simple REST API with a lightweight database (or even a GitHub-hosted JSON/SQLite file for v1)
 - Privacy: only file hashes and timing parameters are shared, never video content or personal data
 - Subtitle source (jimaku entry ID) can serve as an additional matching key
@@ -36,12 +40,15 @@ Subtitle synchronization (alass/ffsubsync) is one of the most friction-heavy ste
 - Could integrate with existing jimaku modal flow
 
 ## Phasing
+
 - v1: Local export/import of timing corrections (share as files)
 - v2: Optional cloud sync with community database
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Video files are identified by content hash without uploading video data.
 - [ ] #2 Timing corrections (offset/warp parameters) can be exported and shared.
 - [ ] #3 Before syncing, the app checks for existing community corrections for the current video.

backlog/archive/tasks/task-48 - Add-streaming-mode-integration-in-subminer-using-ani-cli-stream-source.md

@@ -16,11 +16,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement a new streaming mode so SubMiner can resolve and play episodes via ani-cli stream sources instead of existing file/download flow. The mode is enabled with a CLI flag (`-s` / `--stream`) and, when active, should prefer streamed playback and subtitle handling that keeps Japanese (or configured primary) subtitles as the main track. If a stream lacks Japanese subtitle tracks, fetch and inject subtitles from Jimaku and set them as primary subtitles according to SubMiner config.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Add a command-line option `-s`/`--stream` that enables streaming mode and is documented in help/config UX.
 - [ ] #2 When streaming mode is enabled, resolve episode/video URLs using existing ani-cli stream selection logic (ported into SubMiner) and route playback to the resolved stream source.
 - [ ] #3 If stream metadata contains a Japanese subtitle track, preserve that track as the primary subtitle stream path per current primary-subtitle selection behavior.
@@ -32,11 +36,15 @@ Implement a new streaming mode so SubMiner can resolve and play episodes via ani
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. Streaming via ani-cli in subminer was removed due Cloudflare 403/unreliable source metadata; re-evaluate later if reintroduced behind a feature flag and redesigned resolver/metadata pipeline.
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 CLI accepts both `-s` and `--stream` and enables streaming-specific behavior.
 - [ ] #2 Streaming mode resolves streams through migrated ani-cli logic.
 - [ ] #3 Japanese subs are preferred from stream metadata when available; Jimaku fallback is used only when absent.

backlog/archive/tasks/task-48.1 - Add-streaming-CLI-flag-plumbing-and-option-wiring.md

@@ -16,11 +16,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Add the `-s`/`--stream` option end-to-end in SubMiner CLI and configuration handling, including defaults, help text, parsing/validation, and explicit routing so streaming mode is only enabled when requested.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Introduce `-s` short option and `--stream` long option in CLI parsing without breaking existing flags.
 - [ ] #2 When set, the resulting config state reflects streaming mode enabled and is propagated to playback/session startup.
 - [ ] #3 When unset, behavior remains identical to current non-streaming flows.
@@ -29,5 +33,7 @@ Add the `-s`/`--stream` option end-to-end in SubMiner CLI and configuration hand
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. CLI stream mode work deferred until streaming architecture is revisited.
+
 <!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.2 - Port-ani-cli-stream-resolution-logic-into-SubMiner.md

@@ -16,11 +16,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement stream URL resolution by porting ani-cli logic for selecting providers/episodes and obtaining playable stream URLs so SubMiner can consume stream sources directly.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Encapsulate stream search/provider selection logic in a dedicated module in SubMiner.
 - [ ] #2 Resolve episode query input into a canonical playable stream URL in streaming mode.
 - [ ] #3 Preserve existing behavior for non-streaming flow and expose errors when stream resolution fails.
@@ -29,5 +33,7 @@ Implement stream URL resolution by porting ani-cli logic for selecting providers
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. Stream URL resolution via ani-cli postponed; previous attempt exposed anti-bot/403 fragility and poor title-source reliability.
+
 <!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.3 - Implement-stream-subtitle-selection-and-primary-language-precedence.md

@@ -16,11 +16,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Handle subtitle track selection for stream playback so Japanese (or configured primary language) subtitle behavior is correctly applied when stream metadata includes or omits JP tracks.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Use stream metadata to choose and mark the configured primary language subtitle as active when available.
 - [ ] #2 If no matching primary language track exists in stream metadata, keep previous fallback behavior only for non-streaming mode.
 - [ ] #3 When no Japanese track exists and config primary is different, explicitly set configured primary as primary track for streaming flow.
@@ -29,5 +33,7 @@ Handle subtitle track selection for stream playback so Japanese (or configured p
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. Stream subtitle language precedence in streaming mode deferred with full design revisit.
+
 <!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.4 - Add-Jimaku-subtitle-fallback-for-stream-mode.md

@@ -17,11 +17,15 @@ priority: medium
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 When a resolved stream lacks JP/primary-language tracks, fetch subtitles from Jimaku and inject them for playback, overriding non-primary subtitle defaults in streaming mode according to config.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Detect missing primary subtitle from stream metadata and trigger Jimaku lookup for matching episode.
 - [ ] #2 Load fetched Jimaku subtitles into playback pipeline and mark them as the primary subtitle track.
 - [ ] #3 Fallback is only used in streaming mode and should not alter subtitle behavior outside streaming.
@@ -30,5 +34,7 @@ When a resolved stream lacks JP/primary-language tracks, fetch subtitles from Ji
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. Jimaku fallback for streams deferred along with entire streaming flow.
+
 <!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.5 - Add-verification-plan-tests-for-streaming-mode-behavior.md

@@ -16,11 +16,15 @@ priority: low
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Create a validation plan or tests for CLI flag behavior, stream resolution, and subtitle precedence/fallback rules so streaming mode changes are measurable and regressions are caught.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 Document/manual checklist covers `-s` and `--stream` invocation and streaming-only behavior.
 - [ ] #2 Include cases for (a) stream with JP subtitles, (b) no JP subtitles with Jimaku fallback, (c) primary-language not Japanese.
 - [ ] #3 Run or provide reproducible checks to confirm non-streaming behavior unchanged.
@@ -29,5 +33,7 @@ Create a validation plan or tests for CLI flag behavior, stream resolution, and
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. Verification plan moved to deferred reimplementation context.
+
 <!-- SECTION:NOTES:END -->

backlog/archive/tasks/task-48.6 - Wire-s-stream-mode-to-Ani-cli-and-Jimaku-subtitle-fallback.md

@@ -22,11 +22,15 @@ priority: high
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Implement SubMiner streaming mode end-to-end behind a `-s`/`--stream` flag. In stream mode, use the vendored ani-cli resolution flow to get playable stream URLs instead of local file/YouTube URL handling. If resolved streams do not expose Japanese subtitles, fetch matching subtitles from Jimaku and load them into mpv as the active primary subtitle track, overwriting the current non-primary/non-Japanese default according to subminer primary-subtitle configuration.
+
 <!-- SECTION:DESCRIPTION:END -->
 
 ## Acceptance Criteria
+
 <!-- AC:BEGIN -->
+
 - [ ] #1 When `subminer -s` is used, resolution should pass a search/query through ani-cli stream logic and play the resolved stream source.
 - [ ] #2 If the stream includes a Japanese subtitle track, preserve and select the configured primary subtitle language behavior without Jimaku injection.
 - [ ] #3 If no Japanese (or configured primary language) subtitle exists in stream metadata, fetch and inject Jimaku subtitles before playback starts.
@@ -37,11 +41,15 @@ Implement SubMiner streaming mode end-to-end behind a `-s`/`--stream` flag. In s
 ## Implementation Notes
 
 <!-- SECTION:NOTES:BEGIN -->
+
 Superseded by TASK-51. End-to-end stream wiring to ani-cli is deferred.
+
 <!-- SECTION:NOTES:END -->
 
 ## Definition of Done
+
 <!-- DOD:BEGIN -->
+
 - [ ] #1 CLI exposes both `-s` and `--stream` in help/config and validation.
 - [ ] #2 Implementation includes a clear fallback path when stream subtitles are absent and Jimaku search/download fails gracefully.
 - [ ] #3 Subtitles loading path avoids temp-file leaks; temporary media/subtitle artifacts are cleaned up on exit.

backlog/archive/tasks/task-51 - Revisit-Ani-cli-stream-mode-integration-later.md

@@ -15,9 +15,11 @@ dependencies: []
 ## Description
 
 <!-- SECTION:DESCRIPTION:BEGIN -->
+
 Current codebase has removed ani-cli integration and stream-mode from subminer temporarily. Keep a deferred design task to reintroduce streaming mode in a future cycle.
 
 Findings from prior attempts:
+
 - `subminer -s <query>` path relied on `ani-cli` resolving stream URLs, but returned stream URLs that are Cloudflare-protected (`tools.fast4speed.rsvp`) and often returned 403 from mpv/ytdl-hook (generic anti-bot/Forbidden).
 - Even after passing `ytdl` extractor args, stream playback via subminer still failed because URL/anti-bot handling differed from direct ani-cli execution context.
 - We also observed stream title resolution issues: selected titles from ani-cli menu were unreliable/random and broke downstream Jimaku matching behavior.
@@ -25,6 +27,7 @@ Findings from prior attempts:
 - Based on these findings and instability, stream mode should be explicitly deferred rather than partially reintroduced.
 
 Proposal:
+
 - Reintroduce behind a feature flag / future milestone only.
 - Re-design around a dedicated stream source resolver with robust URL acquisition and source metadata preservation (query/episode/title) before subtitle sync flows.
 <!-- SECTION:DESCRIPTION:END -->