sudacode/SubMiner
1
0
Fork 0
mirror of https://github.com/ksyasuda/SubMiner.git synced 2026-02-27 18:22:41 -08:00
Code Issues Packages Projects Releases Wiki Activity

docs: refresh architecture and development docs

Browse Source 
Update docs content to match current launcher/plugin/runtime structure and fix stale home demo media assets with cache-busted URLs plus poster refresh. Add supporting backlog/subagent tracking records and docs asset regression coverage.
This commit is contained in:
Kyle Yasuda
2026-02-22 20:25:55 -08:00
parent 36e9346595
commit 1d3f099e44
14 changed files with 428 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md Normal file
View File

@@ -0,0 +1,50 @@
---
id: TASK-112
title: Fix docs demo video thumbnail cache staleness
status: Done
assignee:
- codex
created_date: '2026-02-23 03:41'
updated_date: '2026-02-23 03:43'
labels:
- bug
- docs
- media
dependencies: []
priority: medium
ordinal: 112000
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
Docs home page demo continues to show an old thumbnail after replacing the demo video file in place. The page currently reuses static media URLs (`/assets/minecard.webm`, `/assets/minecard.mp4`, `/assets/demo-poster.jpg`), so browser/CDN cache can keep stale poster/video preview data.
<!-- SECTION:DESCRIPTION:END -->
## Action Steps
<!-- SECTION:PLAN:BEGIN -->
1. Add a failing regression check that asserts cache-busted URL usage for docs home demo media references.
2. Update docs home demo media URLs to include a shared asset version token for poster/source/fallback paths.
3. Run the regression check and docs build validation.
4. Record fix notes and move task status to Done.
<!-- SECTION:PLAN:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Docs home video references include a deterministic cache-busting token so direct asset replacement does not serve stale preview data.
- [x] #2 Poster/source/fallback links in the demo block use the same token to avoid mixed old/new media.
- [x] #3 Validation commands for the new regression check and docs build pass.
<!-- AC:END -->
## Implementation Notes
<!-- SECTION:NOTES:BEGIN -->
- Generated a fresh thumbnail from `docs/public/assets/minecard.webm` into `docs/public/assets/minecard-poster.jpg`.
- Updated `docs/index.md` demo block to use a shared `demoAssetVersion` token across poster, webm/mp4 sources, and gif fallback links.
- Follow-up: regenerated `minecard-poster.jpg` at exact `00:00:12` from the webm and bumped token to `demoAssetVersion = '20260223-2'`.
- Added regression check `docs/index.assets.test.ts` to ensure demo media references keep shared cache-busting URL patterns.
- Validation:
- `bun test docs/index.assets.test.ts`
- `bun run docs:build`
<!-- SECTION:NOTES:END -->

33
backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md Normal file
View File

@@ -0,0 +1,33 @@
---
id: TASK-113
title: Refresh architecture doc content to match current codebase
status: Done
assignee:
- codex-architecture-doc-refresh
created_date: '2026-02-22 19:39'
updated_date: '2026-02-22 19:44'
labels:
- docs
- architecture
dependencies: []
priority: low
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
User requested a thorough review of the current codebase and `docs/architecture.md`, then updating document content to reflect current implementation details. Mermaid/flow diagrams are explicitly out of scope for this pass.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Architecture content sections align with current source tree/module ownership.
- [x] #2 Service/composer/runtime descriptions are updated for current behavior and module names.
- [x] #3 Mermaid/flow chart sections remain unchanged in this pass.
<!-- AC:END -->
## Notes
- Reviewed current module ownership across `src/main.ts`, `src/main/runtime/*`, `src/core/services/*`, `src/config/*`, `src/renderer/*`, `launcher/*`, and `plugin/subminer.lua`.
- Updated `docs/architecture.md` content sections only; Mermaid blocks intentionally left untouched.
- Verification: `bun run docs:build` passed.

35
backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md Normal file
View File

@@ -0,0 +1,35 @@
---
id: TASK-114
title: Refresh development doc content to match current codebase
status: Done
assignee:
- codex-development-docs-review
created_date: '2026-02-23 03:46'
updated_date: '2026-02-23 03:49'
labels:
- docs
- developer-experience
dependencies: []
priority: medium
---
## Description
<!-- SECTION:DESCRIPTION:BEGIN -->
User requested a thorough review of the current codebase and `docs/development.md`, then updates so the page reflects current scripts, architecture, and contributor workflow.
<!-- SECTION:DESCRIPTION:END -->
## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 `docs/development.md` commands/tooling sections match current `package.json`, `Makefile`, and active CI lanes.
- [x] #2 Runtime/composition guidance reflects current module ownership and does not reference removed guardrail steps.
- [x] #3 Updated doc builds cleanly via `bun run docs:build`.
<!-- AC:END -->
## Notes
- Reviewed `docs/development.md` against current `package.json` scripts, `Makefile` targets, launcher/runtime env overrides, and `.github/workflows/ci.yml` gate order.
- Updated setup instructions to use Bun for `vendor/texthooker-ui` and include submodule initialization.
- Added CI-equivalent local test/build/docs command sequence and clarified that subtitle dist tests are currently placeholders.
- Expanded environment-variable coverage (`SUBMINER_ROFI_THEME`, Jimaku/Jellyfin overrides, `SUBMINER_LOG_LEVEL`, `SUBMINER_MPV_LOG`, macOS helper skip flag).
- Verification: `bun run docs:build` passed.

123
docs/architecture.md
View File

@@ -1,6 +1,12 @@
# Architecture # Architecture
SubMiner uses a service-oriented Electron architecture with a composition-oriented main process and a modular renderer process. SubMiner is split into three cooperating runtimes:
- Electron desktop app (`src/`) for overlay/UI/runtime orchestration.
- Launcher CLI (`launcher/`) for mpv/app command workflows.
- mpv Lua plugin (`plugin/subminer.lua`) for player-side controls and IPC handoff.
Within the desktop app, `src/main.ts` is a composition root that wires small runtime/domain modules plus core services.
## Goals ## Goals
@@ -15,31 +21,52 @@ SubMiner uses a service-oriented Electron architecture with a composition-orient
## Project Structure ## Project Structure
```text ```text
launcher/ # Standalone CLI launcher wrapper and mpv helpers
commands/ # Command modules (doctor/config/mpv/jellyfin/playback/app passthrough)
config/ # Launcher config parsers + CLI parser builder
main.ts # Launcher entrypoint and command dispatch
plugin/
subminer.lua # mpv plugin (auto-start, IPC, AniSkip + hover controls)
src/ src/
main-entry.ts # Background-mode bootstrap wrapper before loading main.js
main.ts # Entry point — delegates to runtime composers/domain modules main.ts # Entry point — delegates to runtime composers/domain modules
preload.ts # Electron preload bridge preload.ts # Electron preload bridge
types.ts # Shared type definitions types.ts # Shared type definitions
main/ # Composition root modules (extracted from main.ts) main/ # Main-process composition/runtime adapters
app-lifecycle.ts # Electron lifecycle event registration app-lifecycle.ts # App lifecycle + app-ready runtime runner factories
cli-runtime.ts # CLI command handling and dispatch cli-runtime.ts # CLI command runtime service adapters
dependencies.ts # Shared dependency builders for IPC/runtime config-validation.ts # Startup/hot-reload config error formatting and fail-fast helpers
ipc-mpv-command.ts # MPV command composition helpers dependencies.ts # Shared dependency builders for IPC/runtime services
ipc-runtime.ts # IPC channel registration and handlers ipc-runtime.ts # IPC runtime registration wrappers
overlay-runtime.ts # Overlay window/modal selection and state overlay-runtime.ts # Overlay modal routing + active-window selection
overlay-shortcuts-runtime.ts # Overlay keyboard shortcut handling overlay-shortcuts-runtime.ts # Overlay keyboard shortcut handling
startup.ts # Startup bootstrap flow (argv/env processing) overlay-visibility-runtime.ts # Overlay visibility + tracker-driven bounds service
startup-lifecycle.ts # App-ready initialization sequence frequency-dictionary-runtime.ts # Frequency dictionary runtime adapter
state.ts # Application runtime state container jlpt-runtime.ts # JLPT dictionary runtime adapter
subsync-runtime.ts # Subsync command orchestration media-runtime.ts # Media path/title/subtitle-position runtime service
startup.ts # Startup bootstrap dependency builder
startup-lifecycle.ts # Lifecycle runtime runner adapter
state.ts # Application runtime state container + reducer transitions
subsync-runtime.ts # Subsync command runtime adapter
runtime/ runtime/
composers/ # Composition assembly clusters consumed by main.ts composers/ # High-level composition clusters used by main.ts
domains/ # Domain barrel exports for runtime services domains/ # Domain barrel exports (startup/overlay/mpv/jellyfin/...)
registry.ts # Domain registry consumed by main.ts
core/ core/
services/ # ~60 focused service modules (see below) services/ # Focused runtime services (Electron adapters + pure logic)
anilist/ # AniList token store/update queue/update helpers
immersion-tracker/ # Immersion persistence/session/metadata modules
tokenizer/ # Tokenizer stage modules (selection/enrichment/annotation)
utils/ # Pure helpers and coercion/config utilities utils/ # Pure helpers and coercion/config utilities
cli/ # CLI parsing and help output cli/ # CLI parsing and help output
config/ # Config schema, defaults, validation, template generation config/ # Config defaults/definitions, loading, parse, resolution pipeline
definitions/ # Domain-specific defaults + option registries
resolve/ # Domain-specific config resolution pipeline stages
shared/ipc/ # Cross-process IPC channel constants + payload validators
renderer/ # Overlay renderer (modularized UI/runtime) renderer/ # Overlay renderer (modularized UI/runtime)
handlers/ # Keyboard/mouse interaction modules
modals/ # Jimaku/Kiku/subsync/runtime-options/session-help modals
positioning/ # Invisible-layer layout + offset controllers
window-trackers/ # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS) window-trackers/ # Backend-specific tracker implementations (Hyprland, Sway, X11, macOS)
jimaku/ # Jimaku API integration helpers jimaku/ # Jimaku API integration helpers
subsync/ # Subtitle sync (alass/ffsubsync) helpers subsync/ # Subtitle sync (alass/ffsubsync) helpers
@@ -51,27 +78,32 @@ src/
### Service Layer (`src/core/services/`) ### Service Layer (`src/core/services/`)
- **Startup** — `startup-service`, `app-lifecycle-service`, `app-ready-service` - **Overlay/window runtime:** `overlay-manager.ts`, `overlay-window.ts`, `overlay-window-geometry.ts`, `overlay-visibility.ts`, `overlay-bridge.ts`, `overlay-runtime-init.ts`, `overlay-content-measurement.ts`, `overlay-drop.ts`
- **Overlay** — `overlay-manager-service`, `overlay-window-service`, `overlay-visibility-service`, `overlay-bridge-service`, `overlay-runtime-init-service`, `overlay-content-measurement-service` - **Shortcuts/input:** `shortcut.ts`, `overlay-shortcut.ts`, `overlay-shortcut-handler.ts`, `shortcut-fallback.ts`, `numeric-shortcut.ts`
- **Shortcuts** — `shortcut-service`, `overlay-shortcut-service`, `overlay-shortcut-handler`, `shortcut-fallback-service`, `numeric-shortcut-service`, `numeric-shortcut-session-service` - **MPV runtime:** `mpv.ts`, `mpv-transport.ts`, `mpv-protocol.ts`, `mpv-properties.ts`, `mpv-render-metrics.ts`
- **MPV** — `mpv-service`, `mpv-control-service`, `mpv-render-metrics-service`, `mpv-transport`, `mpv-protocol`, `mpv-state`, `mpv-properties` - **Mining + Anki/Jimaku runtime:** `mining.ts`, `field-grouping.ts`, `field-grouping-overlay.ts`, `anki-jimaku.ts`, `anki-jimaku-ipc.ts`
- **IPC** — `ipc-service`, `ipc-command-service`, `runtime-options-ipc-service` - **Subtitle/token pipeline:** `subtitle-processing-controller.ts`, `subtitle-position.ts`, `subtitle-ws.ts`, `tokenizer.ts` + `tokenizer/*` stage modules
- **Mining** — `mining-service`, `field-grouping-service`, `field-grouping-overlay-service`, `anki-jimaku-service`, `anki-jimaku-ipc-service` - **Integrations:** `jimaku.ts`, `subsync.ts`, `subsync-runner.ts`, `texthooker.ts`, `jellyfin.ts`, `jellyfin-remote.ts`, `discord-presence.ts`, `yomitan-extension-loader.ts`, `yomitan-settings.ts`
- **Subtitles** — `subtitle-ws-service`, `subtitle-position-service`, `secondary-subtitle-service`, `tokenizer-service` - **Config/runtime controls:** `config-hot-reload.ts`, `runtime-options-ipc.ts`, `cli-command.ts`, `startup.ts`
- **Integrations** — `jimaku-service`, `subsync-service`, `subsync-runner-service`, `texthooker-service`, `yomitan-extension-loader-service`, `yomitan-settings-service` - **Domain submodules:** `anilist/*` (token/update queue/updater), `immersion-tracker/*` (storage/session/metadata/query/reducer)
- **Config** — `runtime-config-service`, `cli-command-service`
### Renderer Layer (`src/renderer/`) ### Renderer Layer (`src/renderer/`)
The overlay renderer is split by concern so `renderer.ts` stays focused on bootstrapping, IPC wiring, and module composition. The renderer keeps `renderer.ts` focused on orchestration. UI behavior is delegated to per-concern modules.
```text ```text
src/renderer/ src/renderer/
renderer.ts # Entrypoint/orchestration only renderer.ts # Entrypoint/orchestration only
context.ts # Shared runtime context contract context.ts # Shared runtime context contract
state.ts # Centralized renderer mutable state state.ts # Centralized renderer mutable state
error-recovery.ts # Global renderer error boundary + recovery actions
overlay-content-measurement.ts # Reports rendered bounds to main process
subtitle-render.ts # Primary/secondary subtitle rendering + style application subtitle-render.ts # Primary/secondary subtitle rendering + style application
positioning.ts # Visible/invisible positioning + mpv metrics layout positioning.ts # Facade export for positioning controller
positioning/
controller.ts # Position controller orchestration
invisible-layout*.ts # Invisible layer layout computations
position-state.ts # Position state helpers
handlers/ handlers/
keyboard.ts # Keybindings, chord handling, modal key routing keyboard.ts # Keybindings, chord handling, modal key routing
mouse.ts # Hover/drag behavior, selection + observer wiring mouse.ts # Hover/drag behavior, selection + observer wiring
@@ -79,12 +111,18 @@ src/renderer/
jimaku.ts # Jimaku modal flow jimaku.ts # Jimaku modal flow
kiku.ts # Kiku field-grouping modal flow kiku.ts # Kiku field-grouping modal flow
runtime-options.ts # Runtime options modal flow runtime-options.ts # Runtime options modal flow
session-help.ts # Keyboard shortcuts/help modal flow
subsync.ts # Manual subsync modal flow subsync.ts # Manual subsync modal flow
utils/ utils/
dom.ts # Required DOM lookups + typed handles dom.ts # Required DOM lookups + typed handles
platform.ts # Layer/platform capability detection platform.ts # Layer/platform capability detection
``` ```
### Launcher + Plugin Runtimes
- `launcher/main.ts` dispatches commands through `launcher/commands/*` and shared config readers in `launcher/config/*`. It handles mpv startup, app passthrough, Jellyfin helper commands, and playback handoff.
- `plugin/subminer.lua` runs inside mpv and handles IPC startup checks, overlay toggles, hover-token messages, and AniSkip intro-skip UX.
## Flow Diagram ## Flow Diagram
The main process has three layers: `main.ts` delegates to composition modules that wire together domain services. The renderer runs in a separate Electron process, connected through `preload.ts`. The main process has three layers: `main.ts` delegates to composition modules that wire together domain services. The renderer runs in a separate Electron process, connected through `preload.ts`.
@@ -179,6 +217,12 @@ Composer modules share contract conventions via `src/main/runtime/composers/cont
This keeps side effects explicit and makes behavior easy to unit-test with fakes. This keeps side effects explicit and makes behavior easy to unit-test with fakes.
Additional conventions in the current code:
- `main.ts` uses `createMainRuntimeRegistry()` (`src/main/runtime/registry.ts`) to access domain handlers (`startup`, `overlay`, `mpv`, `ipc`, `shortcuts`, `anilist`, `jellyfin`, `mining`) without importing every runtime module directly.
- Domain barrels in `src/main/runtime/domains/*` re-export runtime handlers + main-deps builders, while composers in `src/main/runtime/composers/*` assemble larger runtime clusters.
- Many runtime handlers accept `*MainDeps` objects generated by `createBuild*MainDepsHandler` builders to isolate side effects and keep units testable.
### IPC Contract + Validation Boundary ### IPC Contract + Validation Boundary
- Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring. - Central channel constants live in `src/shared/ipc/contracts.ts` and are consumed by both main (`ipcMain`) and renderer preload (`ipcRenderer`) wiring.
@@ -199,9 +243,10 @@ For domains migrated to reducer-style transitions (for example AniList token/que
## Program Lifecycle ## Program Lifecycle
- **Startup:** `startup.ts` parses CLI args and detects the compositor backend. If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks. - **Startup:** `startup.ts` parses CLI args and detects the compositor backend. If `--generate-config` is passed, it writes the template and exits. Otherwise `app-lifecycle.ts` acquires the single-instance lock and registers Electron lifecycle hooks.
- **Initialization:** Once `app.whenReady()` fires, `startup-lifecycle.ts` runs a short critical path first (config reload, keybindings, mpv client, overlay setup, IPC bridge), then schedules non-critical warmups in the background (MeCab availability check, Yomitan extension load, dictionary prewarm, optional Jellyfin remote startup). - **Initialization:** Once `app.whenReady()` fires, `composeAppReadyRuntime()` runs the critical path first (strict config reload, runtime options + keybindings, mpv client creation, overlay/IPC setup). Non-critical warmups are launched asynchronously (`mecab`, `yomitan-extension`, dictionary prewarm, optional Jellyfin remote session).
- **Runtime:** Event-driven. mpv property changes, IPC messages, CLI commands, and keyboard shortcuts all route through the composition layer to domain services, which update state and broadcast to the renderer. - **Runtime:** Event-driven. mpv events, IPC messages, CLI commands, overlay shortcuts, hot-reload notifications, and integration callbacks route through runtime handlers/composers, update `AppState`, and broadcast to overlay windows.
- **Shutdown:** Electron's `will-quit` triggers service teardown — closes the mpv socket, unregisters shortcuts, stops WebSocket and texthooker servers, destroys the window tracker, and cleans up Anki state. - **Overlay window model:** runtime manages three overlay windows: `visible`, `invisible`, and `secondary`. `splitOverlayGeometryForSecondaryBar()` reserves the top 20% for the secondary subtitle bar and routes the remaining area to the active primary overlay layer.
- **Shutdown:** `onWillQuitCleanup` tears down tray + watchers + integrations, stops subtitle/texthooker servers, flushes buffered MPV OSD log writes, closes token/session windows, and stops Jellyfin/Discord runtime services.
```mermaid ```mermaid
flowchart TD flowchart TD
@@ -252,15 +297,15 @@ flowchart TD
- **Better testability:** most behavior can be tested without Electron windows/mpv. - **Better testability:** most behavior can be tested without Electron windows/mpv.
- **Better reviewability:** PRs can be scoped to one subsystem. - **Better reviewability:** PRs can be scoped to one subsystem.
- **Backward compatibility:** CLI flags and IPC channels can remain stable while internals evolve. - **Backward compatibility:** CLI flags and IPC channels can remain stable while internals evolve.
- **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` for startup, lifecycle, IPC, CLI, and domain runtime wiring. - **Runtime registry + domain barrels:** `src/main/runtime/registry.ts` and `src/main/runtime/domains/*` reduce direct fan-in inside `main.ts` while keeping domain ownership explicit.
- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), state (`mpv-state.ts`), and properties (`mpv-properties.ts`) for maintainability. - **Extracted composition root:** `main.ts` delegates to focused modules under `src/main/` and `src/main/runtime/composers/` for lifecycle, IPC, overlay, mpv, shortcut, and integration wiring.
- **Split MPV service layers:** MPV internals are separated into transport (`mpv-transport.ts`), protocol (`mpv-protocol.ts`), and properties/render metrics modules for maintainability.
- **Config by domain:** defaults, option registries, and resolution are split by domain under `src/config/definitions/*` and `src/config/resolve/*`, keeping config evolution localized.
## Extension Rules ## Extension Rules
- Add behavior to an existing service in `src/core/services/*` or create a focused composition module in `src/main/` / `src/main/runtime/composers/` — not as ad-hoc logic in `main.ts`. - Add behavior to an existing service in `src/core/services/*` or create a focused runtime module under `src/main/runtime/*`; avoid ad-hoc logic in `main.ts`.
- Keep service APIs explicit and narrowly scoped. - Add new cross-process channels in `src/shared/ipc/contracts.ts` first, validate payloads in `src/shared/ipc/validators.ts`, then wire handlers in IPC runtime modules.
- Prefer additive changes that preserve existing CLI flags and IPC channel behavior. - If change spans startup/overlay/mpv/integration wiring, prefer composing through `src/main/runtime/domains/*` + `src/main/runtime/composers/*` rather than direct wiring in `main.ts`.
- Add/update unit tests for each service extraction or behavior change. - Keep service APIs explicit and narrowly scoped, and preserve existing CLI flag / IPC channel behavior unless the change is intentionally breaking.
- For cross-cutting changes, extract-first then refactor internals after parity is verified. - Add or update focused tests (including malformed-payload IPC tests) when runtime boundaries or contracts change.
- When adding new IPC channels or CLI commands, register them in the appropriate `src/main/` module (`ipc-runtime.ts` for IPC, `cli-runtime.ts` for CLI).
- When adding/changing IPC channels, update `src/shared/ipc/contracts.ts`, validate payloads in `src/shared/ipc/validators.ts`, and add malformed-payload tests.

41
docs/development.md
View File

@@ -8,12 +8,15 @@
## Setup ## Setup
```bash ```bash
git clone https://github.com/ksyasuda/SubMiner.git git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
cd SubMiner cd SubMiner
# if you cloned without --recurse-submodules:
git submodule update --init --recursive
make deps make deps
# or manually: # or manually:
bun install bun install
cd vendor/texthooker-ui && pnpm install --frozen-lockfile (cd vendor/texthooker-ui && bun install --frozen-lockfile)
``` ```
## Building ## Building
@@ -47,6 +50,7 @@ Verify the workflow:
```bash ```bash
make build-launcher make build-launcher
dist/launcher/subminer --help >/dev/null
bash scripts/verify-generated-launcher.sh bash scripts/verify-generated-launcher.sh
``` ```
@@ -56,16 +60,29 @@ bash scripts/verify-generated-launcher.sh
bun run dev # builds + launches with --start --dev bun run dev # builds + launches with --start --dev
electron . --start --dev --log-level debug # equivalent Electron launch with verbose logging electron . --start --dev --log-level debug # equivalent Electron launch with verbose logging
electron . --background # tray/background mode, minimal default logging electron . --background # tray/background mode, minimal default logging
make dev-start # build + launch via Makefile
``` ```
## Testing ## Testing
CI-equivalent local gate:
```bash
bun run tsc --noEmit
bun run test:fast
bun run test:launcher:smoke:src
bun run build
bun run test:smoke:dist
bun run docs:build
```
Common focused commands:
```bash ```bash
bun run test:config # Source-level config schema/validation tests bun run test:config # Source-level config schema/validation tests
bun run test:launcher # Launcher regression tests (config discovery + command routing) bun run test:launcher # Launcher regression tests (config discovery + command routing)
bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring bun run test:launcher:smoke:src # Launcher e2e smoke: launcher -> mpv IPC -> overlay start/stop wiring
bun run test:core # Source-level core regression tests (default lane) bun run test:core # Source-level core regression tests (default lane)
bun run test:subtitle # Subtitle pipeline tests (build + run)
bun run test:fast # Source-level config + core lane (no build prerequisite) bun run test:fast # Source-level config + core lane (no build prerequisite)
``` ```
@@ -80,9 +97,10 @@ bun run build # compile dist artifacts
bun run test:smoke:dist # explicit smoke scope for compiled runtime bun run test:smoke:dist # explicit smoke scope for compiled runtime
bun run test:config:dist # optional full dist config suite bun run test:config:dist # optional full dist config suite
bun run test:core:dist # optional full dist core suite bun run test:core:dist # optional full dist core suite
bun run test:subtitle:dist # optional smoke lane for subtitle dist regressions
``` ```
`bun run test:subtitle` and `bun run test:subtitle:dist` are currently placeholders and do not run an active suite.
## Config Generation ## Config Generation
```bash ```bash
@@ -111,6 +129,7 @@ Run `make help` for a full list of targets. Key ones:
| Target | Description | | Target | Description |
| ---------------------- | ---------------------------------------------------------------- | | ---------------------- | ---------------------------------------------------------------- |
| `make build` | Build platform package for detected OS | | `make build` | Build platform package for detected OS |
| `make build-launcher` | Generate Bun launcher wrapper at `dist/launcher/subminer` |
| `make install` | Install platform artifacts (wrapper, theme, AppImage/app bundle) | | `make install` | Install platform artifacts (wrapper, theme, AppImage/app bundle) |
| `make install-plugin` | Install mpv Lua plugin and config | | `make install-plugin` | Install mpv Lua plugin and config |
| `make deps` | Install JS dependencies (root + texthooker-ui) | | `make deps` | Install JS dependencies (root + texthooker-ui) |
@@ -128,17 +147,25 @@ Run `make help` for a full list of targets. Key ones:
- Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`. - Linux packaged desktop launches pass `--background` using electron-builder `build.linux.executableArgs` in `package.json`.
- Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring. - Prefer direct inline deps objects in `src/main/` modules for simple pass-through wiring.
- Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping). - Add a helper/adapter service only when it performs meaningful adaptation, validation, or reuse (not identity mapping).
- See [Architecture](/architecture) for the composition model and extension rules.
## Environment Variables ## Environment Variables
| Variable | Description | | Variable | Description |
| --------------------------------- | ---------------------------------------------------------- | | ---------------------------------- | ------------------------------------------------------------------------------- |
| `SUBMINER_APPIMAGE_PATH` | Override AppImage location for subminer script | | `SUBMINER_APPIMAGE_PATH` | Override SubMiner app binary path for launcher playback commands |
| `SUBMINER_BINARY_PATH` | Alias for `SUBMINER_APPIMAGE_PATH` | | `SUBMINER_BINARY_PATH` | Alias for `SUBMINER_APPIMAGE_PATH` |
| `SUBMINER_ROFI_THEME` | Override rofi theme path for launcher picker |
| `SUBMINER_LOG_LEVEL` | Override app logger level (`debug`, `info`, `warn`, `error`) |
| `SUBMINER_MPV_LOG` | Override mpv/app shared log file path |
| `SUBMINER_YT_SUBGEN_MODE` | Override `youtubeSubgen.mode` for launcher | | `SUBMINER_YT_SUBGEN_MODE` | Override `youtubeSubgen.mode` for launcher |
| `SUBMINER_WHISPER_BIN` | Override `youtubeSubgen.whisperBin` for launcher | | `SUBMINER_WHISPER_BIN` | Override `youtubeSubgen.whisperBin` for launcher |
| `SUBMINER_WHISPER_MODEL` | Override `youtubeSubgen.whisperModel` for launcher | | `SUBMINER_WHISPER_MODEL` | Override `youtubeSubgen.whisperModel` for launcher |
| `SUBMINER_YT_SUBGEN_OUT_DIR` | Override generated subtitle output directory | | `SUBMINER_YT_SUBGEN_OUT_DIR` | Override generated subtitle output directory |
| `SUBMINER_YT_SUBGEN_AUDIO_FORMAT` | Override extraction format used for whisper fallback | | `SUBMINER_YT_SUBGEN_AUDIO_FORMAT` | Override extraction format used for whisper fallback |
| `SUBMINER_YT_SUBGEN_KEEP_TEMP` | Set to `1` to keep temporary subtitle-generation workspace | | `SUBMINER_YT_SUBGEN_KEEP_TEMP` | Set to `1` to keep temporary subtitle-generation workspace |
| `SUBMINER_JIMAKU_API_KEY` | Override Jimaku API key for launcher subtitle downloads |
| `SUBMINER_JIMAKU_API_KEY_COMMAND` | Command used to resolve Jimaku API key at runtime |
| `SUBMINER_JIMAKU_API_BASE_URL` | Override Jimaku API base URL |
| `SUBMINER_JELLYFIN_ACCESS_TOKEN` | Override Jellyfin access token (used before stored encrypted session fallback) |
| `SUBMINER_JELLYFIN_USER_ID` | Optional Jellyfin user ID override |
| `SUBMINER_SKIP_MACOS_HELPER_BUILD` | Set to `1` to skip building the macOS helper binary during `bun run build` |

14
docs/index.assets.test.ts Normal file
View File

@@ -0,0 +1,14 @@
import { expect, test } from 'bun:test';
import { readFileSync } from 'node:fs';
const docsIndexPath = new URL('./index.md', import.meta.url);
const docsIndexContents = readFileSync(docsIndexPath, 'utf8');
test('docs demo media uses shared cache-busting asset version token', () => {
expect(docsIndexContents).toMatch(/const demoAssetVersion = ['"][^'"]+['"]/);
expect(docsIndexContents).toContain(':poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`"');
expect(docsIndexContents).toContain('<source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />');
expect(docsIndexContents).toContain('<source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />');
expect(docsIndexContents).toContain('<a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">');
expect(docsIndexContents).toContain('<img :src="`/assets/minecard.gif?v=${demoAssetVersion}`" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" />');
});

14
docs/index.md
View File

@@ -67,6 +67,10 @@ features:
details: Stream subtitles in real time to browser tools via local WebSocket and keep your stack integrated. details: Stream subtitles in real time to browser tools via local WebSocket and keep your stack integrated.
--- ---
<script setup>
const demoAssetVersion = '20260223-2';
</script>
<div class="landing-shell"> <div class="landing-shell">
<section class="workflow-section"> <section class="workflow-section">
<h2>How it fits together</h2> <h2>How it fits together</h2>
@@ -102,11 +106,11 @@ features:
<section class="demo-section"> <section class="demo-section">
<h2>See it in action</h2> <h2>See it in action</h2>
<p>Subtitles, lookup flow, and card enrichment from a real playback session.</p> <p>Subtitles, lookup flow, and card enrichment from a real playback session.</p>
<video controls playsinline preload="metadata" poster="/assets/demo-poster.jpg"> <video controls playsinline preload="metadata" :poster="`/assets/minecard-poster.jpg?v=${demoAssetVersion}`">
<source :src="'/assets/minecard.webm'" type="video/webm" /> <source :src="`/assets/minecard.webm?v=${demoAssetVersion}`" type="video/webm" />
<source :src="'/assets/minecard.mp4'" type="video/mp4" /> <source :src="`/assets/minecard.mp4?v=${demoAssetVersion}`" type="video/mp4" />
<a :href="'/assets/minecard.webm'" target="_blank" rel="noreferrer"> <a :href="`/assets/minecard.webm?v=${demoAssetVersion}`" target="_blank" rel="noreferrer">
<img :src="'/assets/minecard.gif'" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" /> <img :src="`/assets/minecard.gif?v=${demoAssetVersion}`" alt="SubMiner demo GIF fallback" style="width: 100%; height: auto;" />
</a> </a>
</video> </video>
</section> </section>

BIN
docs/public/assets/minecard-poster.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 122 KiB

4
docs/subagents/INDEX.md
View File

@@ -90,3 +90,7 @@ Read first. Keep concise.
| `codex-overlay-three-window-layout-20260223T021606Z-9z2t` | `codex-overlay-three-window-layout` | `Implement top-anchored secondary subtitle overlay window (20%) plus swappable primary overlay region (80%).` | `handoff` | `docs/subagents/agents/codex-overlay-three-window-layout-20260223T021606Z-9z2t.md` | `2026-02-23T02:44:37Z` | | `codex-overlay-three-window-layout-20260223T021606Z-9z2t` | `codex-overlay-three-window-layout` | `Implement top-anchored secondary subtitle overlay window (20%) plus swappable primary overlay region (80%).` | `handoff` | `docs/subagents/agents/codex-overlay-three-window-layout-20260223T021606Z-9z2t.md` | `2026-02-23T02:44:37Z` |
| `opencode-task110-backlog-sync-20260223T025059Z-k3m7` | `opencode-task110-backlog-sync` | `Verify TASK-110 completion state and synchronize backlog metadata with plan-first workflow.` | `handoff` | `docs/subagents/agents/opencode-task110-backlog-sync-20260223T025059Z-k3m7.md` | `2026-02-23T02:53:30Z` | | `opencode-task110-backlog-sync-20260223T025059Z-k3m7` | `opencode-task110-backlog-sync` | `Verify TASK-110 completion state and synchronize backlog metadata with plan-first workflow.` | `handoff` | `docs/subagents/agents/opencode-task110-backlog-sync-20260223T025059Z-k3m7.md` | `2026-02-23T02:53:30Z` |
| `codex-docs-page-polish-20260223T025932Z-b7k2` | `codex-docs-page-polish` | `Polish docs landing page and sync public workflow docs with current overlay stack.` | `handoff` | `docs/subagents/agents/codex-docs-page-polish-20260223T025932Z-b7k2.md` | `2026-02-23T03:19:20Z` | | `codex-docs-page-polish-20260223T025932Z-b7k2` | `codex-docs-page-polish` | `Polish docs landing page and sync public workflow docs with current overlay stack.` | `handoff` | `docs/subagents/agents/codex-docs-page-polish-20260223T025932Z-b7k2.md` | `2026-02-23T03:19:20Z` |
| `opencode-remove-maint-guardrails-20260223T033715Z-2a53` | `opencode-remove-maint-guardrails` | `Remove Maintainability Guardrails docs section and associated guardrail code/commands.` | `handoff` | `docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md` | `2026-02-23T03:40:20Z` |
| `codex-architecture-doc-refresh-20260223T033941Z-d6se` | `codex-architecture-doc-refresh` | `Review repository architecture surfaces and refresh docs/architecture.md content to match current code state.` | `handoff` | `docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md` | `2026-02-23T03:44:17Z` |
| `codex-docs-video-thumb-cache-20260223T033929Z-k8p2` | `codex-docs-video-thumb-cache` | `Fix docs landing page demo video thumbnail staleness after direct asset replacement.` | `handoff` | `docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md` | `2026-02-23T03:44:04Z` |
| `codex-development-docs-review-20260223T034520Z-2ebb` | `codex-development-docs-review` | `Review codebase and refresh docs/development.md to match current project state.` | `done` | `docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md` | `2026-02-23T03:49:16Z` |

32
docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md Normal file
View File

@@ -0,0 +1,32 @@
# Agent: `codex-architecture-doc-refresh-20260223T033941Z-d6se`
- alias: `codex-architecture-doc-refresh`
- mission: `Review current runtime/module architecture and update docs/architecture.md content to match real code paths.`
- status: `handoff`
- branch: `main`
- started_at: `2026-02-23T03:39:41Z`
- heartbeat_minutes: `5`
## Current Work (newest first)
- [2026-02-23T03:44:17Z] handoff: architecture docs refreshed to match current codebase structure/runtime ownership; docs build passed; ready for user review.
- [2026-02-23T03:44:17Z] test: `bun run docs:build` passed.
- [2026-02-23T03:44:17Z] progress: updated `docs/architecture.md` sections for project structure, service layer, renderer layering, lifecycle, composition conventions, and extension rules; mermaid blocks left unchanged.
- [2026-02-23T03:39:41Z] intent: refresh `docs/architecture.md` using direct repo evidence; keep diagrams untouched per user request.
- [2026-02-23T03:39:41Z] progress: loaded `docs/subagents/INDEX.md`, `docs/subagents/collaboration.md`, current `docs/architecture.md`, and source tree inventory.
## Files Touched
- `docs/subagents/INDEX.md`
- `docs/subagents/collaboration.md`
- `docs/subagents/agents/codex-architecture-doc-refresh-20260223T033941Z-d6se.md`
- `backlog/tasks/task-113 - Refresh-architecture-doc-content-to-match-current-codebase.md`
- `docs/architecture.md`
## Assumptions
- User wants content accuracy only; mermaid/flow diagrams intentionally left as-is.
- Existing uncommitted guardrail-removal changes are separate work; avoid touching those files.
## Open Questions / Blockers
- None.
## Next Step
- Await user follow-up; if requested, apply same drift pass to other docs pages (`docs/development.md`, `docs/mining-workflow.md`).

31
docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md Normal file
View File

@@ -0,0 +1,31 @@
# Agent: `codex-development-docs-review-20260223T034520Z-2ebb`
- alias: `codex-development-docs-review`
- mission: `Review codebase and refresh docs/development.md to match current project state.`
- status: `done`
- branch: `main`
- started_at: `2026-02-23T03:46:06Z`
- heartbeat_minutes: `5`
## Current Work (newest first)
- [2026-02-23T03:49:16Z] handoff: refreshed `docs/development.md` for current setup/build/test/env workflow; validated with `bun run docs:build`; updated backlog ticket + subagent bookkeeping.
- [2026-02-23T03:48:30Z] test: `bun run docs:build` passed after docs edits (VitePress chunk-size warning only).
- [2026-02-23T03:47:40Z] progress: fixed setup drift (`pnpm` -> `bun`, added submodule init), aligned testing section with CI lanes, corrected subtitle test placeholder wording, expanded env vars to active launcher/runtime overrides.
- [2026-02-23T03:46:06Z] intent: initialize subagent+backlog bookkeeping, then audit `docs/development.md` against actual scripts/tests/runtime layout before editing docs.
## Files Touched
- `docs/subagents/agents/codex-development-docs-review-20260223T034520Z-2ebb.md`
- `docs/subagents/INDEX.md`
- `docs/subagents/collaboration.md`
- `backlog/tasks/task-114 - Refresh-development-doc-content-to-match-current-codebase.md`
- `docs/development.md`
## Assumptions
- `Backlog.md` is managed via `backlog/` markdown files in this repo; create a new task ticket for this request.
- Existing dirty worktree entries are from prior sessions; avoid touching unrelated lines/files.
## Open Questions / Blockers
- None.
## Next Step
- Await user review/follow-up scope.

39
docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md Normal file
View File

@@ -0,0 +1,39 @@
# Agent: `codex-docs-video-thumb-cache-20260223T033929Z-k8p2`
- alias: `codex-docs-video-thumb-cache`
- mission: `Fix docs landing page demo video thumbnail staleness after direct asset replacement`
- status: `handoff`
- branch: `main`
- started_at: `2026-02-23T03:40:48Z`
- heartbeat_minutes: `5`
## Current Work
- [2026-02-23T03:40:48Z] intent: confirm root cause for stale docs video thumbnail and apply minimal cache-busting/docs fix.
- [2026-02-23T03:40:48Z] plan: touch `docs/index.md`; add regression coverage if lightweight; validate with docs build/targeted test.
- [2026-02-23T03:40:48Z] assumption: stale thumbnail caused by static poster/source URLs reusing identical path after direct file replacement.
- [2026-02-23T03:42:25Z] progress: added failing regression test `docs/index.assets.test.ts` asserting shared cache-busting token across demo media URLs.
- [2026-02-23T03:42:58Z] progress: generated fresh poster from `docs/public/assets/minecard.webm` (`minecard-poster.jpg`) and wired docs video block to shared `demoAssetVersion` tokenized URLs.
- [2026-02-23T03:43:20Z] test: `bun test docs/index.assets.test.ts` passes (1/1).
- [2026-02-23T03:43:35Z] test: `bun run docs:build` passes.
- [2026-02-23T03:43:55Z] handoff: TASK-112 marked Done with implementation notes and validation commands.
- [2026-02-23T03:44:04Z] progress: regenerated `minecard-poster.jpg` from `minecard.webm` at exactly `00:00:12` and bumped `demoAssetVersion` to `20260223-2` to force refresh.
- [2026-02-23T03:44:04Z] test: reran `bun test docs/index.assets.test.ts` (pass).
## Files Touched
- `docs/subagents/agents/codex-docs-video-thumb-cache-20260223T033929Z-k8p2.md`
- `docs/subagents/INDEX.md`
- `docs/subagents/collaboration.md`
- `backlog/tasks/task-112 - Fix-docs-demo-video-thumbnail-cache-staleness.md`
- `docs/index.assets.test.ts`
- `docs/index.md`
- `docs/public/assets/minecard-poster.jpg`
## Assumptions
- Browser/CDN cache can keep prior media when URL path remains unchanged.
- Docs home video section in `docs/index.md` is the only requested scope.
## Open Questions / Blockers
- None.
## Next Step
- Share fix summary and ask user to hard-refresh docs page once (`Cmd+Shift+R`) to bypass local cache.

46
docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md Normal file
View File

@@ -0,0 +1,46 @@
# Agent: `opencode-remove-maint-guardrails-20260223T033715Z-2a53`
- alias: `opencode-remove-maint-guardrails`
- mission: `Remove Maintainability Guardrails docs section and associated guardrail code/commands.`
- status: `handoff`
- branch: `main`
- started_at: `2026-02-23T03:37:39Z`
- heartbeat_minutes: `5`
## Current Work (newest first)
- [2026-02-23T03:40:20Z] handoff: completed TASK-111; removed docs section, package scripts, CI guardrail step, and runtime-cycle/fan-in script code + fixtures; validation (`bun run tsc --noEmit`, `bun run docs:build`) passed.
- [2026-02-23T03:40:03Z] progress: removed `## Maintainability Guardrails` from `docs/development.md`, deleted `check:main-fanin*` and `check:runtime-cycles*` scripts from `package.json`, removed CI fail-fast guardrails step, and deleted associated scripts/fixtures under `scripts/`.
- [2026-02-23T03:37:39Z] intent: initialized session, linked backlog task TASK-111, and preparing scoped removal pass for maintainability guardrails docs and related code.
- [2026-02-23T03:37:39Z] assumptions: removal target is explicit "Maintainability Guardrails" section and direct command/code references tied to it.
## Files Touched
- `docs/subagents/INDEX.md`
- `docs/subagents/collaboration.md`
- `docs/subagents/agents/opencode-remove-maint-guardrails-20260223T033715Z-2a53.md`
- `backlog/tasks/task-111 - Remove-Maintainability-Guardrails-docs-section-and-related-guardrail-code.md` (via Backlog MCP)
- `docs/development.md`
- `package.json`
- `.github/workflows/ci.yml`
- `scripts/check-main-runtime-fanin.ts` (deleted)
- `scripts/check-runtime-cycles.ts` (deleted)
- `scripts/check-runtime-cycles.test.ts` (deleted)
- `scripts/fixtures/runtime-cycles/acyclic/entry.ts` (deleted)
- `scripts/fixtures/runtime-cycles/acyclic/feature.ts` (deleted)
- `scripts/fixtures/runtime-cycles/acyclic/utils/index.ts` (deleted)
- `scripts/fixtures/runtime-cycles/cyclic/module-a.ts` (deleted)
- `scripts/fixtures/runtime-cycles/cyclic/module-b.ts` (deleted)
- `scripts/fixtures/runtime-cycles/cyclic/nested/index.ts` (deleted)
## Assumptions
- Request targets current docs page section shown in screenshot and associated command/code paths, not unrelated guardrails.
## Open Questions / Blockers
- None.
## Next Step
- Await user follow-up (optional commit/changelog pass if requested).

9
docs/subagents/collaboration.md
View File

@@ -157,3 +157,12 @@ Shared notes. Append-only.
- [2026-02-23T02:44:37Z] [codex-overlay-three-window-layout-20260223T021606Z-9z2t|codex-overlay-three-window-layout] backlog sync requested post-commit; updated TASK-110 `updated_date`, added commit reference (`b8f7d5e`), and added final summary block. - [2026-02-23T02:44:37Z] [codex-overlay-three-window-layout-20260223T021606Z-9z2t|codex-overlay-three-window-layout] backlog sync requested post-commit; updated TASK-110 `updated_date`, added commit reference (`b8f7d5e`), and added final summary block.
- [2026-02-23T02:50:59Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] starting TASK-110 closure verification pass via Backlog MCP + writing-plans/executing-plans workflow; scope backlog metadata validation/sync only unless missing evidence is found. - [2026-02-23T02:50:59Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] starting TASK-110 closure verification pass via Backlog MCP + writing-plans/executing-plans workflow; scope backlog metadata validation/sync only unless missing evidence is found.
- [2026-02-23T02:53:30Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] completed verification/sync: recorded closure plan, revalidated commit/code evidence (parallel subagent audits), appended TASK-110 verification note, and confirmed task remains Done with all AC checked. - [2026-02-23T02:53:30Z] [opencode-task110-backlog-sync-20260223T025059Z-k3m7|opencode-task110-backlog-sync] completed verification/sync: recorded closure plan, revalidated commit/code evidence (parallel subagent audits), appended TASK-110 verification note, and confirmed task remains Done with all AC checked.
- [2026-02-23T03:37:39Z] [opencode-remove-maint-guardrails-20260223T033715Z-2a53|opencode-remove-maint-guardrails] starting TASK-111 removal pass: delete docs section "Maintainability Guardrails" and remove associated guardrail command/code references; scope docs/scripts/config only.
- [2026-02-23T03:40:20Z] [opencode-remove-maint-guardrails-20260223T033715Z-2a53|opencode-remove-maint-guardrails] completed TASK-111: removed maintainability guardrails docs section, deleted fan-in/runtime-cycle scripts + fixtures, removed related package scripts and CI step, validated via `bun run tsc --noEmit` and `bun run docs:build`.
- [2026-02-23T03:39:41Z] [codex-architecture-doc-refresh-20260223T033941Z-d6se|codex-architecture-doc-refresh] starting docs drift audit for `docs/architecture.md`; scope is content-only refresh vs current `src/**` architecture (no mermaid/chart edits), avoiding active guardrail-removal files.
- [2026-02-23T03:40:48Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] starting docs bugfix for stale home demo thumbnail after direct video replacement; scope `docs/index.md` plus lightweight regression coverage/backlog linkage only.
- [2026-02-23T03:43:55Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] completed TASK-112: generated `minecard-poster.jpg` from latest webm, switched docs demo media URLs to shared cache-busting token, added `docs/index.assets.test.ts`, and validated with `bun test docs/index.assets.test.ts` + `bun run docs:build`.
- [2026-02-23T03:44:04Z] [codex-docs-video-thumb-cache-20260223T033929Z-k8p2|codex-docs-video-thumb-cache] user follow-up applied: regenerated poster at exact `00:00:12` from `minecard.webm` and bumped docs asset token to `20260223-2` to force static thumbnail refresh.
- [2026-02-23T03:44:17Z] [codex-architecture-doc-refresh-20260223T033941Z-d6se|codex-architecture-doc-refresh] completed architecture drift pass: refreshed `docs/architecture.md` structure/service/composition/lifecycle content against current code (`src`, `launcher`, `plugin`), left mermaid sections untouched, and verified `bun run docs:build`; moved backlog linkage to `TASK-113` to avoid active `TASK-112` collision.
- [2026-02-23T03:46:06Z] [codex-development-docs-review-20260223T034520Z-2ebb|codex-development-docs-review] starting user-requested thorough codebase + `docs/development.md` drift audit; scope docs refresh + verification only, no runtime behavior changes expected.
- [2026-02-23T03:49:16Z] [codex-development-docs-review-20260223T034520Z-2ebb|codex-development-docs-review] completed `docs/development.md` refresh: setup/deps/submodule instructions corrected, CI-parity testing lane documented, placeholder subtitle test status clarified, Makefile reference adjusted, env variable table expanded to active launcher/runtime overrides; `bun run docs:build` passed.