docs: refresh architecture and development docs

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.
2026-02-28 06:22:45 -08:00 · 2026-02-22 20:25:55 -08:00
parent 36e9346595
commit 1d3f099e44
14 changed files with 428 additions and 59 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -8,12 +8,15 @@
 ## Setup

 ```bash
-git clone https://github.com/ksyasuda/SubMiner.git
+git clone --recurse-submodules https://github.com/ksyasuda/SubMiner.git
 cd SubMiner
+# if you cloned without --recurse-submodules:
+git submodule update --init --recursive
+
 make deps
 # or manually:
 bun install
-cd vendor/texthooker-ui && pnpm install --frozen-lockfile
+(cd vendor/texthooker-ui && bun install --frozen-lockfile)
 ```

 ## Building
@@ -47,6 +50,7 @@ Verify the workflow:

 ```bash
 make build-launcher
+dist/launcher/subminer --help >/dev/null
 bash scripts/verify-generated-launcher.sh
 ```

@@ -56,16 +60,29 @@ bash scripts/verify-generated-launcher.sh
 bun run dev    # builds + launches with --start --dev
 electron . --start --dev --log-level debug   # equivalent Electron launch with verbose logging
 electron . --background                       # tray/background mode, minimal default logging
+make dev-start                                # build + launch via Makefile
 ```

 ## 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
 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: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:subtitle     # Subtitle pipeline tests (build + run)
 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:config:dist      # optional full dist config 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

 ```bash
@@ -111,6 +129,7 @@ Run `make help` for a full list of targets. Key ones:
 | Target                 | Description                                                      |
 | ---------------------- | ---------------------------------------------------------------- |
 | `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-plugin`  | Install mpv Lua plugin and config                                |
 | `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`.
 - 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).
- See [Architecture](/architecture) for the composition model and extension rules.

 ## Environment Variables

-| Variable                          | Description                                                |
-| --------------------------------- | ---------------------------------------------------------- |
-| `SUBMINER_APPIMAGE_PATH`          | Override AppImage location for subminer script             |
-| `SUBMINER_BINARY_PATH`            | Alias for `SUBMINER_APPIMAGE_PATH`                         |
-| `SUBMINER_YT_SUBGEN_MODE`         | Override `youtubeSubgen.mode` for launcher                 |
-| `SUBMINER_WHISPER_BIN`            | Override `youtubeSubgen.whisperBin` for launcher           |
-| `SUBMINER_WHISPER_MODEL`          | Override `youtubeSubgen.whisperModel` for launcher         |
-| `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_KEEP_TEMP`    | Set to `1` to keep temporary subtitle-generation workspace |
+| Variable                           | Description                                                                     |
+| ---------------------------------- | ------------------------------------------------------------------------------- |
+| `SUBMINER_APPIMAGE_PATH`           | Override SubMiner app binary path for launcher playback commands                |
+| `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_WHISPER_BIN`             | Override `youtubeSubgen.whisperBin` for launcher                                |
+| `SUBMINER_WHISPER_MODEL`           | Override `youtubeSubgen.whisperModel` for launcher                              |
+| `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_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`     |