chore: commit remaining docs and project updates

docs/.vitepress/config.ts

@@ -0,0 +1,47 @@
+const repositoryName = process.env.GITHUB_REPOSITORY?.split('/')[1];
+const base = process.env.GITHUB_ACTIONS && repositoryName ? `/${repositoryName}/` : '/';
+
+export default {
+  title: 'SubMiner',
+  description: 'Documentation for SubMiner',
+  base,
+  appearance: 'dark',
+  cleanUrls: true,
+  lastUpdated: true,
+  markdown: {
+    theme: {
+      light: 'catppuccin-latte',
+      dark: 'catppuccin-macchiato',
+    },
+  },
+  themeConfig: {
+    logo: '/assets/SubMiner.png',
+    nav: [
+      { text: 'Docs', link: '/' },
+      { text: 'Installation', link: '/installation' },
+      { text: 'Usage', link: '/usage' },
+      { text: 'Configuration', link: '/configuration' },
+      { text: 'Development', link: '/development' },
+      { text: 'Architecture', link: '/architecture' },
+    ],
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Overview', link: '/' },
+          { text: 'Installation', link: '/installation' },
+          { text: 'Usage', link: '/usage' },
+        ],
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'Development', link: '/development' },
+          { text: 'Architecture', link: '/architecture' },
+        ],
+      },
+    ],
+    socialLinks: [{ icon: 'github', link: 'https://github.com/ksyasuda/SubMiner' }],
+  },
+};

docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme';
+import '@catppuccin/vitepress/theme/macchiato/mauve.css';
+
+export default DefaultTheme;

docs/README.md

@@ -2,17 +2,36 @@
 
 Use this directory for detailed SubMiner documentation.
 
-- [Installation](installation.md)
+## Local Docs Site
+
+Run the VitePress docs site locally:
+
+```bash
+pnpm run docs:dev
+```
+
+Build static docs output:
+
+```bash
+pnpm run docs:build
+```
+
+- [Installation](/installation)
   - Platform requirements
   - AppImage / macOS / source installs
   - mpv plugin setup
-- [Usage](usage.md)
+- [Usage](/usage)
   - Script vs plugin workflow
   - Running SubMiner with mpv
   - Keybindings and runtime behavior
-- [Configuration](configuration.md)
+- [Configuration](/configuration)
   - Full config file reference and option details
-- [Development](development.md)
+- [Development](/development)
   - Contributor notes
+  - Architecture migration overview
   - Environment variables
   - License and acknowledgments
+- [Architecture](/architecture)
+  - Composability migration status
+  - Core runtime structure
+  - Extension design rules

docs/architecture.md

@@ -0,0 +1,51 @@
+# Architecture
+
+SubMiner is migrating from a single, monolithic `src/main.ts` runtime toward a composable architecture with clear extension points.
+
+## Current Structure
+
+- `src/main.ts`: bootstrap/composition root plus remaining legacy orchestration.
+- `src/core/`: shared runtime primitives:
+  - `app-orchestrator.ts`: lifecycle wiring for ready/activate/quit hooks.
+  - `action-bus.ts`: typed action dispatch path.
+  - `actions.ts`: canonical app action types.
+  - `module.ts` / `module-registry.ts`: module lifecycle contract.
+  - `services/`: extracted runtime services (IPC, shortcuts, subtitle, overlay, MPV command routing).
+- `src/ipc/`: shared IPC contract + wrappers used by main, preload, and renderer.
+- `src/subtitle/`: staged subtitle pipeline (`normalize` -> `tokenize` -> `merge`).
+- `src/modules/`: feature modules:
+  - `runtime-options`
+  - `jimaku`
+  - `subsync`
+  - `anki`
+  - `texthooker`
+- provider registries:
+  - `src/window-trackers/index.ts`
+  - `src/tokenizers/index.ts`
+  - `src/token-mergers/index.ts`
+  - `src/translators/index.ts`
+  - `src/subsync/engines.ts`
+
+## Migration Status
+
+- Completed:
+  - Action bus wired for CLI, shortcuts, and IPC-triggered commands.
+  - Command/action mapping covered by focused core tests.
+  - Shared IPC channel contract adopted across main/preload/renderer.
+  - Runtime options extracted into module lifecycle.
+  - Provider registries replace hardcoded backend selection.
+  - Subtitle tokenization/merge/enrich flow moved to staged pipeline.
+  - Stage-level subtitle pipeline tests added for deterministic behavior.
+  - Jimaku, Subsync, Anki, and texthooker/websocket flows moduleized.
+- In progress:
+  - Further shrink `src/main.ts` by moving orchestration into dedicated services/orchestrator files.
+  - Continue moduleizing remaining integrations with complex lifecycle coupling.
+
+## Design Rules
+
+- New feature behavior should be added as:
+  - a module (`src/modules/*`) and/or
+  - a provider registration (`src/*/index.ts` registries),
+  instead of editing unrelated branches in `src/main.ts`.
+- New command triggers should dispatch `AppAction` and reuse existing action handlers.
+- New IPC channels should be added only via `src/ipc/contract.ts`.

docs/development.md

@@ -2,6 +2,10 @@
 
 To add or change a config option, update `src/config/definitions.ts` first. Defaults, runtime-option metadata, and generated `config.example.jsonc` are derived from this centralized source.
 
+## Architecture
+
+The composability migration state and extension-point guidelines are documented in [`architecture.md`](/architecture).
+
 ## Environment Variables
 
 | Variable                 | Description                                    |

docs/index.md

@@ -0,0 +1,43 @@
+---
+layout: home
+
+title: SubMiner
+tagline: All-in-one sentence mining overlay for MPV with AnkiConnect and dictionary integration
+
+hero:
+  name: SubMiner
+  text: Documentation
+  tagline: Install, configure, and use SubMiner for subtitle-driven mining workflows.
+  image:
+    src: /assets/SubMiner.png
+    alt: SubMiner logo
+  actions:
+    - theme: brand
+      text: Installation
+      link: /installation
+    - theme: alt
+      text: Configuration
+      link: /configuration
+    - theme: alt
+      text: Development
+      link: /development
+    - theme: alt
+      text: Architecture
+      link: /architecture
+
+features:
+  - title: End-to-end workflow
+    details: Connect mpv subtitle capture, Yomitan lookup, and Anki card generation in one overlay.
+  - title: Practical configuration
+    details: Use the complete option reference to tune behavior for mining, media generation, and keybindings.
+  - title: Contributor docs
+    details: Build, test, and package SubMiner with the development notes in this docs set.
+---
+
+## Documentation Sections
+
+- [Installation](/installation)
+- [Usage](/usage)
+- [Configuration](/configuration)
+- [Development](/development)
+- [Architecture](/architecture)