docs: more content

.github/CONTRIBUTING.md

@@ -1,13 +1,34 @@
 # Contributing
 
-We welcome contributions! Please ensure your code is:
+Thanks for contributing to Koharu.
 
-- Well-structured and follows existing conventions
-- Tested and passing all checks
+For the full contributor guide, including local setup, validation commands, and docs workflow, see:
+
+- [`docs/how-to/contributing.md`](../docs/how-to/contributing.md)
+
+In short, contributors should:
+
+- follow existing code and UI patterns
+- run the checks that match the area they changed
+- explain what changed and how they verified it in the PR
+
+Useful local commands:
+
+```bash
+bun install
+bun run build
+bun cargo fmt -- --check
+bun cargo check
+bun cargo clippy -- -D warnings
+bun cargo test --workspace --tests
+bun run format
+bun run test:e2e
+zensical build -c
+```
 
 ## AI-Generated PRs
 
 AI-generated contributions are welcome, provided:
 
-1. A human has reviewed the code before opening the PR
-2. The submitter understands the changes being made
+1. A human has reviewed the code before opening the PR.
+2. The submitter understands the changes being made.

README.md

@@ -1,209 +1,231 @@
-# Koharu
-
-[Documentation](https://koharu.rs)
-
-ML-powered manga translator, written in **Rust**.
-
-Koharu introduces a new workflow for manga translation, utilizing the power of ML to automate the process. It combines the capabilities of object detection, OCR, inpainting, and LLMs to create a seamless translation experience.
-
-Under the hood, Koharu uses [candle](https://github.com/huggingface/candle) and [llama.cpp](https://github.com/ggml-org/llama.cpp) for high-performance inference, and uses [Tauri](https://github.com/tauri-apps/tauri) for the GUI. All components are written in Rust, ensuring safety and speed.
-
-> [!NOTE]
-> Koharu runs its vision models and local LLMs **locally** on your machine by default. If you choose a remote LLM provider, Koharu sends translation text only to the provider you configured. Koharu itself does not collect user data.
-
----
-
-![screenshot](docs/assets/koharu-screenshot-en.png)
-
-> [!NOTE]
-> For help and support, please join our [Discord server](https://discord.gg/mHvHkxGnUY).
-
-## Features
-
-- Automatic speech bubble detection and segmentation
-- OCR for manga text recognition
-- Inpainting to remove original text from images
-- LLM-powered translation
-- Vertical text layout for CJK languages
-- Export to layered PSD with editable text
-- MCP server for AI agents
-
-## Usage
-
-### Hot keys
-
-- <kbd>Ctrl</kbd> + Mouse Wheel: Zoom in/out
-- <kbd>Ctrl</kbd> + Drag: Pan the canvas
-- <kbd>Del</kbd>: Delete selected text block
-
-### Export
-
-Koharu can export the current page as a rendered image or as a layered Photoshop PSD. PSD export preserves helper layers and writes translated text as editable text layers for further cleanup in Photoshop.
-
-### MCP Server
-
-Koharu has a built-in MCP server that can be used to integrate with AI agents. By default, the MCP server will listen on a random port, but you can specify the port using the `--port` flag.
-
-```bash
-# macOS / Linux
-koharu --port 9999
-# Windows
-koharu.exe --port 9999
-```
-
-You can input `http://localhost:9999/mcp` into the MCP server URL field in your AI agent.
-
-### Headless Mode
-
-Koharu can be run in headless mode via command line.
-
-```bash
-# macOS / Linux
-koharu --port 4000 --headless
-# Windows
-koharu.exe --port 4000 --headless
-```
-
-You can now access Koharu Web UI at `http://localhost:4000`.
-
-## GPU acceleration
-
-CUDA, Metal and Vulkan are supported for GPU acceleration, significantly improving performance on supported hardware.
-
-### CUDA (NVIDIA GPUs on Windows)
-
-Koharu is built with CUDA support on Windows, allowing it to leverage the power of NVIDIA GPUs for faster processing.
-
-Koharu bundles CUDA toolkit 13.1, dylibs will be automatically extracted to the application data directory on first run.
-
-> [!NOTE]
-> Please ensure that your system has the latest NVIDIA drivers installed. You can download the latest drivers via [NVIDIA App](https://www.nvidia.com/en-us/software/nvidia-app/).
-
-#### Supported NVIDIA GPUs
-
-Koharu supports NVIDIA GPUs with compute capability 7.5 or higher.
-
-Please make sure your GPU is supported by checking the [CUDA GPU Compute Capability](https://developer.nvidia.com/cuda-gpus) and the [cuDNN Support Matrix](https://docs.nvidia.com/deeplearning/cudnn/backend/latest/reference/support-matrix.html).
-
-### Metal (Apple Silicon on macOS)
-
-Koharu supports Metal for GPU acceleration on macOS with Apple Silicon (M1, M2, etc.). This allows Koharu to run efficiently on a wide range of Apple devices.
-
-### Vulkan (Windows and Linux)
-
-Koharu also supports Vulkan for GPU acceleration on Windows and Linux. Vulkan is a cross-platform graphics and compute API that provides high performance and low overhead.
-
-Note that Vulkan support only applies to the OCR and LLM inference, while the detection and inpainting models still rely on CUDA or Metal. AMD and Intel GPUs can use Vulkan for acceleration, but for the best experience with all features enabled, a CUDA-compatible NVIDIA GPU or Apple Silicon device is recommended.
-
-### CPU fallback
-
-You can always force Koharu to use CPU for inference:
-
-```bash
-# macOS / Linux
-koharu --cpu
-# Windows
-koharu.exe --cpu
-```
-
-## ML Models
-
-Koharu relies on a mixin of computer vision and natural language processing models to perform its tasks.
-
-### Computer Vision Models
-
-Koharu uses several pre-trained models for different tasks:
-
-- [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors) for text detection and layout analysis
-- [comic-text-detector](https://huggingface.co/mayocream/comic-text-detector) for text segmentation
-- [PaddleOCR-VL-1.5](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5) for OCR text recognition
-- [lama-manga](https://huggingface.co/mayocream/lama-manga) for inpainting
-- [YuzuMarker.FontDetection](https://huggingface.co/fffonion/yuzumarker-font-detection) for font and color detection
-
-The models will be automatically downloaded when you run Koharu for the first time.
-
-We convert the original models to safetensors format for better performance and compatibility with Rust. The converted models are hosted on [Hugging Face](https://huggingface.co/mayocream).
-
-### Large Language Models
-
-Koharu supports both local and remote LLM backends, and preselects a model based on your system locale when possible.
-
-#### Local LLMs
-
-Koharu supports various quantized LLMs in GGUF format via [llama.cpp](https://github.com/ggml-org/llama.cpp). These models run on your machine and are downloaded on demand when you select them in Settings. Supported models and suggested usage:
-
-For translating to English:
-
-- [vntl-llama3-8b-v2](https://huggingface.co/lmg-anon/vntl-llama3-8b-v2-gguf): ~8.5 GB Q8_0 weight size and suggests >=10 GB VRAM or plenty of system RAM for CPU inference, best when accuracy matters most.
-- [lfm2-350m-enjp-mt](https://huggingface.co/LiquidAI/LFM2-350M-ENJP-MT-GGUF): ultra-light (≈350M, Q8_0); runs comfortably on CPUs and low-memory GPUs, ideal for quick previews or low-spec machines at the cost of quality.
-
-For translating to Chinese:
-
-- [sakura-galtransl-7b-v3.7](https://huggingface.co/SakuraLLM/Sakura-GalTransl-7B-v3.7): ~6.3 GB and fits on 8 GB VRAM, good balance of quality and speed.
-- [sakura-1.5b-qwen2.5-v1.0](https://huggingface.co/shing3232/Sakura-1.5B-Qwen2.5-v1.0-GGUF-IMX): lightweight (≈1.5B, Q5KS); fits on mid-range GPUs (4–6 GB VRAM) or CPU-only setups with moderate RAM, faster than 7B/8B while keeping Qwen-style tokenizer behavior.
-
-For other languages, you may use:
-
-- [hunyuan-7b-mt-v1.0](https://huggingface.co/Mungert/Hunyuan-MT-7B-GGUF): ~6.3GB and fits on 8 GB VRAM, decent multi-language translation quality.
-
-LLMs will be automatically downloaded on demand when you select a model in the settings. Choose the smallest model that meets your quality needs if you are memory-bound; prefer the 7B/8B variants when you have sufficient VRAM/RAM for better translations.
-
-#### Remote LLMs
-
-Koharu can also translate through remote or self-hosted API providers instead of a downloaded local model. Supported remote providers:
-
-- OpenAI
-- Gemini
-- Claude
-- DeepSeek
-- OpenAI Compatible, including tools and services such as LM Studio, OpenRouter, or any endpoint that exposes the OpenAI-style `/v1/models` and `/v1/chat/completions` APIs
-
-Remote providers are configured in **Settings > API Keys**. For OpenAI Compatible, you also set a custom base URL. API keys are optional for local servers like LM Studio, but typically required for hosted services like OpenRouter.
-
-Use remote providers when you want to avoid local model downloads, reduce local VRAM/RAM usage, or connect Koharu to a hosted model. Keep in mind that OCR text selected for translation is sent to the configured provider.
-
-## Installation
-
-You can download the latest release of Koharu from the [releases page](https://github.com/mayocream/koharu/releases/latest).
-
-We provide pre-built binaries for Windows, macOS, and Linux. For other platforms, you may need to build from source, see the [Development](#development) section below.
-
-## Development
-
-To build Koharu from source, follow the steps below.
-
-### Prerequisites
-
-- [Rust](https://www.rust-lang.org/tools/install) (1.92 or later)
-- [Bun](https://bun.sh/) (1.0 or later)
-
-### Install dependencies
-
-```bash
-bun install
-```
-
-### Build
-
-```bash
-bun run build
-```
-
-The built binaries will be located in the `target/release` directory.
-
-## Sponsorship
-
-If you find Koharu useful, consider sponsoring the project to support its development!
-
-- [GitHub Sponsors](https://github.com/sponsors/mayocream)
-- [Patreon](https://www.patreon.com/mayocream)
-
-## Contributors
-
-<a href="https://github.com/mayocream/koharu/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=mayocream/koharu" />
-</a>
-
-## License
-
-Koharu is licensed under the [GNU General Public License v3.0](LICENSE).
+# Koharu
+
+[Documentation](https://koharu.rs)
+
+ML-powered manga translator, written in **Rust**.
+
+Koharu introduces a new workflow for manga translation, utilizing the power of ML to automate the process. It combines the capabilities of object detection, OCR, inpainting, and LLMs to create a seamless translation experience.
+
+Under the hood, Koharu uses [candle](https://github.com/huggingface/candle) and [llama.cpp](https://github.com/ggml-org/llama.cpp) for high-performance inference, and uses [Tauri](https://github.com/tauri-apps/tauri) for the GUI. All components are written in Rust, ensuring safety and speed.
+
+> [!NOTE]
+> Koharu runs its vision models and local LLMs **locally** on your machine by default. If you choose a remote LLM provider, Koharu sends translation text only to the provider you configured. Koharu itself does not collect user data.
+
+---
+
+![screenshot](docs/assets/koharu-screenshot-en.png)
+
+> [!NOTE]
+> For help and support, join the [Discord server](https://discord.gg/mHvHkxGnUY).
+
+## Features
+
+- Automatic speech bubble detection and segmentation
+- OCR for manga text recognition
+- Inpainting to remove original text from images
+- LLM-powered translation
+- Vertical text layout for CJK languages
+- Export to layered PSD with editable text
+- Local HTTP API and MCP server for automation
+
+If you just want to get started, see [Install Koharu](https://koharu.rs/how-to/install-koharu/) and [Translate Your First Page](https://koharu.rs/tutorials/translate-your-first-page/).
+
+## Usage
+
+### Hot keys
+
+- <kbd>Ctrl</kbd> + Mouse Wheel: Zoom in/out
+- <kbd>Ctrl</kbd> + Drag: Pan the canvas
+- <kbd>Del</kbd>: Delete selected text block
+
+### Export
+
+Koharu can export the current page as a rendered image or as a layered Photoshop PSD. PSD export preserves helper layers and writes translated text as editable text layers, which makes manual cleanup much easier when the automatic pass gets most of the way there.
+
+For export behavior, PSD contents, and file naming, see [Export Pages and Manage Projects](https://koharu.rs/how-to/export-and-manage-projects/).
+
+### MCP Server
+
+Koharu has a built-in MCP server for AI agents. By default it listens on a random port, but you can pin it with the `--port` flag.
+
+```bash
+# macOS / Linux
+koharu --port 9999
+# Windows
+koharu.exe --port 9999
+```
+
+Then point your client at `http://localhost:9999/mcp`.
+
+For local setup and the available tools, see [Run GUI, Headless, and MCP Modes](https://koharu.rs/how-to/run-gui-headless-and-mcp/), [Configure MCP Clients](https://koharu.rs/how-to/configure-mcp-clients/), and [MCP Tools Reference](https://koharu.rs/reference/mcp-tools/).
+
+### Headless Mode
+
+Koharu can also run without the desktop window.
+
+```bash
+# macOS / Linux
+koharu --port 4000 --headless
+# Windows
+koharu.exe --port 4000 --headless
+```
+
+You can then open the web UI at `http://localhost:4000`.
+
+For runtime modes, ports, and local endpoints, see [Run GUI, Headless, and MCP Modes](https://koharu.rs/how-to/run-gui-headless-and-mcp/).
+
+## GPU acceleration
+
+Koharu supports CUDA, Metal, and Vulkan for acceleration. CPU fallback is always available if the accelerated path is unavailable or not worth the trouble on your system.
+
+### CUDA (NVIDIA GPUs on Windows)
+
+Koharu is built with CUDA support on Windows so it can use NVIDIA GPUs for the full local pipeline.
+
+Koharu bundles CUDA Toolkit 13.1. The required DLLs are extracted to the application data directory on first run.
+
+> [!NOTE]
+> Make sure you have current NVIDIA drivers installed. You can update them through [NVIDIA App](https://www.nvidia.com/en-us/software/nvidia-app/).
+
+#### Supported NVIDIA GPUs
+
+Koharu supports NVIDIA GPUs with compute capability 7.5 or higher.
+
+If you want to confirm GPU support, see [CUDA GPU Compute Capability](https://developer.nvidia.com/cuda-gpus) and the [cuDNN Support Matrix](https://docs.nvidia.com/deeplearning/cudnn/backend/latest/reference/support-matrix.html).
+
+### Metal (Apple Silicon on macOS)
+
+Koharu supports Metal on Apple Silicon Macs. That gives you local acceleration without any extra setup beyond the normal app install.
+
+### Vulkan (Windows and Linux)
+
+Koharu also supports Vulkan on Windows and Linux. This path is mainly used for OCR and local LLM inference.
+
+Detection and inpainting still depend on CUDA or Metal, so Vulkan is helpful but not a full replacement for the main accelerated path. AMD and Intel GPUs can still benefit from it, but the best all-around experience is still NVIDIA on Windows or Apple Silicon on macOS.
+
+### CPU fallback
+
+You can always force Koharu to use CPU for inference:
+
+```bash
+# macOS / Linux
+koharu --cpu
+# Windows
+koharu.exe --cpu
+```
+
+For backend selection, fallback behavior, and model runtime support, see [Acceleration and Runtime](https://koharu.rs/explanation/acceleration-and-runtime/).
+
+## ML Models
+
+Koharu uses a mix of computer vision and language models rather than trying to solve the whole page with one model.
+
+### Computer Vision Models
+
+Koharu uses several pre-trained models for different parts of the pipeline:
+
+- [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors) for text detection and layout analysis
+- [comic-text-detector](https://huggingface.co/mayocream/comic-text-detector) for text segmentation
+- [PaddleOCR-VL-1.5](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5) for OCR text recognition
+- [lama-manga](https://huggingface.co/mayocream/lama-manga) for inpainting
+- [YuzuMarker.FontDetection](https://huggingface.co/fffonion/yuzumarker-font-detection) for font and color detection
+
+The models are downloaded automatically when you run Koharu for the first time.
+
+We convert the upstream weights to safetensors format for better compatibility and runtime behavior in Rust. The converted weights are hosted on [Hugging Face](https://huggingface.co/mayocream).
+
+For a closer look at the pipeline, see [Models and Providers](https://koharu.rs/explanation/models-and-providers/) and the [Technical Deep Dive](https://koharu.rs/explanation/technical-deep-dive/).
+
+### Large Language Models
+
+Koharu supports both local and remote LLM backends, and it tries to preselect a sensible model based on your system locale when possible.
+
+#### Local LLMs
+
+Koharu supports quantized GGUF models through [llama.cpp](https://github.com/ggml-org/llama.cpp). These models run on your machine and are downloaded on demand when you select them in Settings. Supported models and suggested usage:
+
+For translating to English:
+
+- [vntl-llama3-8b-v2](https://huggingface.co/lmg-anon/vntl-llama3-8b-v2-gguf): around 8.5 GB in Q8_0, best when translation quality matters more than speed or memory use
+- [lfm2-350m-enjp-mt](https://huggingface.co/LiquidAI/LFM2-350M-ENJP-MT-GGUF): very small and easy to run on CPUs or low-memory GPUs, good for quick previews and low-spec machines
+
+For translating to Chinese:
+
+- [sakura-galtransl-7b-v3.7](https://huggingface.co/SakuraLLM/Sakura-GalTransl-7B-v3.7): around 6.3 GB, a good balance of quality and speed on 8 GB GPUs
+- [sakura-1.5b-qwen2.5-v1.0](https://huggingface.co/shing3232/Sakura-1.5B-Qwen2.5-v1.0-GGUF-IMX): lighter and faster, useful on mid-range GPUs or CPU-only setups
+
+For other languages, you can use:
+
+- [hunyuan-7b-mt-v1.0](https://huggingface.co/Mungert/Hunyuan-MT-7B-GGUF): around 6.3 GB, with decent multilingual translation quality
+
+LLMs are downloaded on demand when you pick a model in Settings. If you are memory-bound, start small. If you have enough VRAM or RAM, the 7B and 8B models usually produce better translations.
+
+#### Remote LLMs
+
+Koharu can also translate through remote or self-hosted API providers instead of a downloaded local model. Supported remote providers:
+
+- OpenAI
+- Gemini
+- Claude
+- DeepSeek
+- OpenAI Compatible, including LM Studio, OpenRouter, or any endpoint that exposes the OpenAI-style `/v1/models` and `/v1/chat/completions` APIs
+
+Remote providers are configured in **Settings > API Keys**. OpenAI-compatible providers also need a custom base URL. API keys are optional for local servers such as LM Studio, but usually required for hosted services such as OpenRouter.
+
+Use a remote provider if you do not want to download local models, if you want to keep VRAM and RAM usage down, or if you already have a hosted model endpoint. Keep in mind that the OCR text selected for translation is sent to the provider you configured.
+
+For LM Studio, OpenRouter, and other OpenAI-style endpoints, see [Use OpenAI-Compatible APIs](https://koharu.rs/how-to/use-openai-compatible-api/). For provider configuration, see [Settings Reference](https://koharu.rs/reference/settings/).
+
+## Installation
+
+You can download the latest release of Koharu from the [releases page](https://github.com/mayocream/koharu/releases/latest).
+
+We provide pre-built binaries for Windows, macOS, and Linux. For the normal install flow, see [Install Koharu](https://koharu.rs/how-to/install-koharu/). If something goes wrong, see [Troubleshooting](https://koharu.rs/how-to/troubleshooting/).
+
+## Development
+
+To build Koharu from source, follow the steps below.
+
+### Prerequisites
+
+- [Rust](https://www.rust-lang.org/tools/install) 1.92 or later
+- [Bun](https://bun.sh/) 1.0 or later
+
+### Install dependencies
+
+```bash
+bun install
+```
+
+### Build
+
+```bash
+bun run build
+```
+
+If you want more direct control over the Tauri build:
+
+```bash
+bun tauri build --release --no-bundle
+```
+
+The built binaries will be located in `target/release`.
+
+For platform-specific build notes, see [Build From Source](https://koharu.rs/how-to/build-from-source/). For the local development workflow, see [Contributing](https://koharu.rs/how-to/contributing/).
+
+## Sponsorship
+
+If you find Koharu useful, consider sponsoring the project to support its development.
+
+- [GitHub Sponsors](https://github.com/sponsors/mayocream)
+- [Patreon](https://www.patreon.com/mayocream)
+
+## Contributors
+
+<a href="https://github.com/mayocream/koharu/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=mayocream/koharu" />
+</a>
+
+## License
+
+Koharu is licensed under the [GNU General Public License v3.0](LICENSE).

docs/explanation/how-koharu-works.md

@@ -4,20 +4,73 @@ title: How Koharu Works
 
 # How Koharu Works
 
-Koharu is built around a translation pipeline for manga pages.
+Koharu is built around a page pipeline for manga translation. The user-facing workflow is simple, but the implementation intentionally separates layout, segmentation, OCR, inpainting, translation, and rendering into different stages.
 
-## The core workflow
+## The pipeline at a glance
 
-For a typical page, Koharu combines several stages:
+```mermaid
+flowchart LR
+    A[Input manga page] --> B[Detect stage]
+    B --> B1[Layout analysis]
+    B --> B2[Segmentation mask]
+    B --> B3[Font hints]
+    B1 --> C[OCR stage]
+    B2 --> D[Inpaint stage]
+    C --> E[LLM translation stage]
+    D --> F[Render stage]
+    E --> F
+    F --> G[Localized page or PSD export]
+```
 
-1. Text detection and layout analysis
-2. Text region segmentation
-3. OCR text recognition
-4. Inpainting to remove original text
-5. LLM-based translation
-6. Text rendering and export
+At the public pipeline level, Koharu runs:
 
-This lets one application handle both the language work and much of the visual cleanup.
+1. `Detect`
+2. `OCR`
+3. `Inpaint`
+4. `LLM Generate`
+5. `Render`
+
+The important implementation detail is that `Detect` is already a multi-model stage:
+
+- `PP-DocLayoutV3` finds text-like layout regions and reading order.
+- `comic-text-detector` produces a per-pixel text probability map.
+- `YuzuMarker.FontDetection` estimates font and color hints for later rendering.
+
+That split is why Koharu can use one model to decide where text belongs on the page and another to decide which exact pixels should be removed.
+
+## What each stage produces
+
+| Stage | Main models | Main output |
+| --- | --- | --- |
+| Detect | `PP-DocLayoutV3`, `comic-text-detector`, `YuzuMarker.FontDetection` | text blocks, segmentation mask, font hints |
+| OCR | `PaddleOCR-VL-1.5` | recognized source text for each block |
+| Inpaint | `lama-manga` | page with original text removed |
+| LLM Generate | local GGUF LLM or remote provider | translated text |
+| Render | Koharu renderer | final localized page or export |
+
+## Why the stages are separate
+
+Manga pages are harder than plain document OCR:
+
+- speech bubbles are irregular and often curved
+- Japanese text may be vertical while captions or SFX may be horizontal
+- text can overlap artwork, screentones, speed lines, and panel borders
+- reading order is part of the page structure, not just the raw pixels
+
+Because of that, one model is usually not enough. Koharu first estimates layout, then runs OCR on cropped regions, then uses a segmentation mask for cleanup, and only then asks an LLM to translate the text.
+
+## The implementation shape
+
+In source terms, the pipeline entrypoint runs in `koharu-pipeline/src/pipeline.rs`, while the vision stack is coordinated in `koharu-ml/src/facade.rs`.
+
+Some implementation details that matter:
+
+- the detect stage uses `PP-DocLayoutV3` first and converts text-like layout labels into `TextBlock` objects
+- overlapping boxes are deduplicated before OCR
+- text direction is inferred from region aspect ratio so vertical manga text can be handled earlier
+- OCR runs on cropped text regions, not on the full page
+- inpainting consumes the current segmentation mask, not just a rectangular box
+- when you choose a remote LLM provider, Koharu sends OCR text for translation, not the full page image
 
 ## Why the stack matters
 
@@ -36,3 +89,7 @@ By default, Koharu runs:
 - local LLMs locally
 
 If you configure a remote LLM provider, Koharu sends only the text selected for translation to that provider.
+
+## Want the deep technical version?
+
+See [Technical Deep Dive](technical-deep-dive.md) for model types, segmentation mask theory, FFT-based inpainting, and background references to Wikipedia diagrams plus official model cards.

docs/explanation/index.md

@@ -9,5 +9,6 @@ Explanation pages describe how Koharu is put together and why it behaves the way
 ## Topics
 
 - [How Koharu Works](how-koharu-works.md)
+- [Technical Deep Dive](technical-deep-dive.md)
 - [Acceleration and Runtime](acceleration-and-runtime.md)
 - [Models and Providers](models-and-providers.md)

docs/explanation/models-and-providers.md

@@ -6,6 +6,8 @@ title: Models and Providers
 
 Koharu uses both vision models and language models. The vision stack prepares the page; the language stack handles translation.
 
+If you want the architecture-level explanation of how these pieces fit together, read [Technical Deep Dive](technical-deep-dive.md) after this page.
+
 ## Vision models
 
 Koharu automatically downloads the required vision models when you use them for the first time.
@@ -20,10 +22,29 @@ The default stack includes:
 
 Converted model weights are hosted on [Hugging Face](https://huggingface.co/mayocream) in safetensors format for Rust compatibility and performance.
 
+### What each vision model is
+
+| Model | Model type | Why Koharu uses it |
+| --- | --- | --- |
+| `PP-DocLayoutV3` | layout detector | finds text-like regions and reading order |
+| `comic-text-detector` | segmentation network | produces a text mask for cleanup |
+| `PaddleOCR-VL-1.5` | vision-language model | reads cropped text into text tokens |
+| `lama-manga` | inpainting network | reconstructs the image after text removal |
+| `YuzuMarker.FontDetection` | classifier / regressor | estimates font and style hints for rendering |
+
+The important design choice is that Koharu does not use a single model for every page task. Layout, segmentation, OCR, and inpainting all need different output shapes:
+
+- layout wants regions and order
+- segmentation wants per-pixel masks
+- OCR wants text
+- inpainting wants restored pixels
+
 ## Local LLMs
 
 Koharu supports local GGUF models through [llama.cpp](https://github.com/ggml-org/llama.cpp). These models run on your machine and are downloaded on demand when you select them in the LLM picker.
 
+In practice, the local models are usually quantized decoder-only transformers. GGUF is the file format; `llama.cpp` is the inference runtime.
+
 ### Suggested local models for English output
 
 - [vntl-llama3-8b-v2](https://huggingface.co/lmg-anon/vntl-llama3-8b-v2-gguf): around 8.5 GB in Q8_0 form, best when translation quality matters most
@@ -52,6 +73,8 @@ Supported providers include:
 
 Remote providers are configured in **Settings > API Keys**.
 
+For a step-by-step setup guide for LM Studio, OpenRouter, and similar endpoints, see [Use OpenAI-Compatible APIs](../how-to/use-openai-compatible-api.md).
+
 ## Choosing between local and remote
 
 Use local models when you want:
@@ -69,3 +92,13 @@ Use remote providers when you want:
 !!! note
 
     When you use a remote provider, Koharu sends OCR text selected for translation to the provider you configured.
+
+## Background reading
+
+For theory and diagrams behind the model categories on this page, see:
+
+- [Technical Deep Dive](technical-deep-dive.md)
+- [Fourier transform on Wikipedia](https://en.wikipedia.org/wiki/Fourier_transform)
+- [Image segmentation on Wikipedia](https://en.wikipedia.org/wiki/Image_segmentation)
+- [OCR on Wikipedia](https://en.wikipedia.org/wiki/Optical_character_recognition)
+- [Transformer architecture on Wikipedia](https://en.wikipedia.org/wiki/Transformer_(deep_learning_architecture))

docs/explanation/technical-deep-dive.md

@@ -0,0 +1,235 @@
+---
+title: Technical Deep Dive
+---
+
+# Technical Deep Dive
+
+This page explains the technical side of Koharu's manga pipeline: what each model does, how the stages fit together, and why layout analysis, segmentation masks, OCR, inpainting, and translation are handled separately.
+
+## The page pipeline in implementation terms
+
+```mermaid
+flowchart TD
+    A[Input page] --> B[PP-DocLayoutV3]
+    A --> C[comic-text-detector]
+    B --> D[Text blocks]
+    C --> E[Segmentation mask]
+    A --> F[YuzuMarker font detector]
+    D --> G[PaddleOCR-VL crop OCR]
+    E --> H[LaMa inpainting]
+    G --> I[Local or remote LLM]
+    F --> J[Renderer style hints]
+    H --> K[Renderer]
+    I --> K
+    J --> K
+    K --> L[Rendered page / PSD]
+```
+
+At the code level, the public pipeline steps are `Detect -> OCR -> Inpaint -> LLM Generate -> Render`, but the detect stage is already doing three distinct jobs:
+
+- page layout analysis
+- text foreground segmentation
+- font and color estimation
+
+That design is deliberate. A manga translation tool needs both page structure and pixel precision.
+
+## Model types at a glance
+
+| Component | Default model | Model type | Main job in Koharu |
+| --- | --- | --- | --- |
+| Layout analysis | [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors) | document layout detector | find text-like regions, labels, confidence, and reading order |
+| Segmentation | [comic-text-detector](https://github.com/dmMaze/comic-text-detector) | text segmentation network | produce a dense text mask for cleanup |
+| OCR | [PaddleOCR-VL-1.5](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5) | vision-language model | read cropped text regions into Unicode text |
+| Inpainting | [lama-manga](https://huggingface.co/mayocream/lama-manga) / [LaMa](https://github.com/advimman/lama) | image inpainting network | fill masked regions after text removal |
+| Font hints | [YuzuMarker.FontDetection](https://huggingface.co/fffonion/yuzumarker-font-detection) | image classifier / regressor | estimate font family, colors, and stroke hints |
+| Translation | local GGUF model via [llama.cpp](https://github.com/ggml-org/llama.cpp) or remote API | decoder-only LLM in most local setups | translate OCR text into the target language |
+
+## Why layout analysis matters on manga pages
+
+Layout analysis is not just "find boxes around text". On manga pages it has to answer several structural questions:
+
+- which regions are text-like at all
+- where the reading order probably is
+- whether a block is tall enough to behave like vertical text
+- which boxes should be deduplicated before OCR
+- which parts of the page are captions, bubble text, titles, or other layout categories
+
+This matters because manga is visually dense:
+
+- speech bubbles are often curved or skewed
+- text may sit on top of screentones and action lines
+- vertical Japanese and horizontal Latin text can coexist on the same page
+- the region that should be read is not always the same shape as the pixels that should be erased
+
+Koharu uses layout output to create `TextBlock` records first, then uses those blocks to drive OCR and later rendering.
+
+In the current implementation, the layout stage:
+
+- runs `PP-DocLayoutV3::inference_one_fast(...)`
+- keeps regions whose labels look text-like
+- converts them into `TextBlock` values
+- deduplicates heavily overlapping regions
+- infers vertical vs horizontal source direction from aspect ratio
+
+So layout analysis is the structural backbone of the rest of the pipeline.
+
+## What a segmentation mask is
+
+A segmentation mask is an image-sized map where each pixel says whether it belongs to a target class. In Koharu's case, the target class is effectively "text foreground that should later be removed during cleanup".
+
+This is different from a bounding box:
+
+| Representation | What it means | Best used for |
+| --- | --- | --- |
+| Bounding box | coarse rectangular region | OCR crop selection, ordering, UI editing |
+| Polygon | tighter geometric outline | line-level geometry |
+| Segmentation mask | per-pixel foreground map | inpainting and precise cleanup |
+
+```mermaid
+flowchart LR
+    A[Speech bubble] --> B[Layout box]
+    A --> C[Segmentation mask]
+    B --> D[Crop for OCR]
+    C --> E[Erase exact text pixels]
+```
+
+In Koharu, the segmentation path is intentionally separate from layout:
+
+- `comic-text-detector` produces a grayscale probability map
+- Koharu refines that map with post-processing
+- the refined result becomes `doc.segment`
+- LaMa then uses `doc.segment` as the erase and fill mask for inpainting
+
+The refinement step matters because raw segmentation probabilities are usually soft and noisy. Koharu thresholds the prediction, tries block-aware refinement, and dilates the final binary mask so the cleanup covers text edges and outlines instead of leaving halos behind.
+
+## How the vision models work in theory
+
+### Layout analysis: detector plus reading-order reasoning
+
+[PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3) is a layout model built for document parsing under skew, warping, and other non-planar distortions. Its model card highlights two properties that are especially relevant to manga-style pages:
+
+- it predicts multi-point geometry instead of only axis-aligned two-point boxes
+- it predicts logical reading order in the same forward pass
+
+Koharu's Rust port mirrors that shape: the `pp_doclayout_v3` module contains an `HGNetV2` backbone plus attention-based encoder and decoder blocks, and the inference result exposes `label`, `score`, `bbox`, `polygon_points`, and `order`.
+
+Conceptually, this is closer to object detection plus layout parsing than to OCR itself.
+
+### Segmentation: dense per-pixel text prediction
+
+Koharu's `comic-text-detector` path is a segmentation-first design. The Rust port loads:
+
+- a YOLOv5-style backbone
+- a U-Net decoder for mask prediction
+- an optional DBNet head for full detection mode
+
+The default page pipeline uses the segmentation-only path because Koharu already gets layout boxes from `PP-DocLayoutV3`. That means Koharu combines:
+
+- one model that is good at page structure
+- one model that is good at pixel-level text foreground
+
+This is a better fit for cleanup than relying on boxes alone.
+
+### OCR: multimodal decoding from image crops to text tokens
+
+[PaddleOCR-VL](https://huggingface.co/docs/transformers/en/model_doc/paddleocr_vl) is a compact vision-language model. The official architecture description says it combines:
+
+- a NaViT-style dynamic-resolution visual encoder
+- the ERNIE-4.5-0.3B language model
+
+In theory, OCR here works like a multimodal sequence generation problem:
+
+1. the image crop is encoded into visual tokens
+2. a text prompt such as `OCR:` conditions the task
+3. the decoder autoregressively emits the recognized text tokens
+
+Koharu's implementation follows that pattern closely:
+
+- it loads `PaddleOCR-VL-1.5.gguf` and a separate multimodal projector
+- it injects the image through the llama.cpp multimodal path
+- it prompts with `OCR:`
+- it greedily decodes text for each crop
+
+So OCR in Koharu is not a classic CTC-only recognizer. It is a small document-oriented VLM being used in a tightly scoped OCR task.
+
+### Inpainting: why LaMa uses Fourier convolutions
+
+[LaMa](https://github.com/advimman/lama) is an inpainting model designed for large masked regions. Its paper title is explicit about the key idea: *Resolution-robust Large Mask Inpainting with Fourier Convolutions*.
+
+The important intuition is:
+
+- ordinary convolutions are local
+- text removal often needs long-range context from the rest of the bubble or background
+- frequency-domain operations can capture wider context efficiently
+
+This is where FFT comes in.
+
+#### What FFT means here
+
+FFT stands for **Fast Fourier Transform**. It is a fast algorithm for moving between:
+
+- the spatial domain, where pixels live
+- the frequency domain, where repeating patterns and large-scale structure are easier to manipulate
+
+In Koharu's LaMa port, the `FourierUnit` does exactly that:
+
+1. apply `rfft2` to feature maps
+2. process the real and imaginary channels with learned `1x1` convolutions
+3. apply `irfft2` to return to image space
+
+Koharu even implements custom `rfft2` and `irfft2` ops for CPU, CUDA, and Metal backends so the same spectral block can run across hardware targets.
+
+For manga cleanup, this matters because the missing region is often not just a tiny scratch. It may be an entire speech bubble interior with gradients, screentones, and inked edges. Fourier-style global mixing helps the model preserve larger structures while filling the hole.
+
+## Local LLMs and model type
+
+Koharu's local translation path uses GGUF models through `llama.cpp`. In practice, these are usually quantized decoder-only transformers.
+
+The theory is standard modern LLM inference:
+
+- tokenize the OCR text
+- run masked self-attention over the growing token sequence
+- predict the next token repeatedly until the output is complete
+
+The practical trade-off is also standard:
+
+- larger models usually translate better
+- smaller quantized models use less VRAM and RAM
+- remote providers trade local privacy for easier access to larger hosted models
+
+Koharu keeps the image understanding steps local even when you choose a remote text-generation provider. The remote side only needs the OCR text.
+
+## Koharu-specific implementation notes
+
+Some details that are easy to miss if you only read the high-level docs:
+
+- the detect stage currently loads `ComicTextDetector::load_segmentation_only(...)`, not the full DBNet-backed detection mode
+- the segmentation mask is refined against the current detected text blocks before inpainting
+- OCR runs on cropped text-block images, not the original whole page
+- the OCR wrapper uses the multimodal llama.cpp path and the task prompt `OCR:`
+- inpainting consumes `doc.segment`, so bad masks lead directly to bad cleanup
+- font prediction is normalized before rendering so near-black and near-white colors snap to cleaner values
+
+## Recommended reading
+
+### Official model and project references
+
+- [PP-DocLayoutV3 model card](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3)
+- [PaddleOCR-VL-1.5 model card](https://huggingface.co/PaddlePaddle/PaddleOCR-VL-1.5)
+- [PaddleOCR-VL architecture docs in Hugging Face Transformers](https://huggingface.co/docs/transformers/en/model_doc/paddleocr_vl)
+- [comic-text-detector repository](https://github.com/dmMaze/comic-text-detector)
+- [LaMa repository](https://github.com/advimman/lama)
+- [llama.cpp](https://github.com/ggml-org/llama.cpp)
+
+### Background theory and Wikipedia diagrams
+
+These pages are useful when you want the general theory and the overview diagrams before diving into model cards:
+
+- [Fourier transform](https://en.wikipedia.org/wiki/Fourier_transform)
+- [Image segmentation](https://en.wikipedia.org/wiki/Image_segmentation)
+- [Optical character recognition](https://en.wikipedia.org/wiki/Optical_character_recognition)
+- [Transformer (deep learning architecture)](https://en.wikipedia.org/wiki/Transformer_(deep_learning_architecture))
+- [Object detection](https://en.wikipedia.org/wiki/Object_detection)
+- [Inpainting](https://en.wikipedia.org/wiki/Inpainting)
+
+Those Wikipedia links are background references. For Koharu-specific behavior and the actual model architecture choices, prefer the official model cards and the source tree.

docs/how-to/build-from-source.md

@@ -4,23 +4,101 @@ title: Build From Source
 
 # Build From Source
 
-If you do not want to use a release build, you can compile Koharu locally.
+If you want to compile Koharu locally instead of using a prebuilt release, start with the repository's Bun wrapper. It matches the normal developer workflow and handles platform-specific setup that a direct Tauri call does not.
+
+## What the build includes
+
+A full desktop build includes:
+
+- the Rust application in `koharu/`
+- the embedded UI from `ui/`
+- the local HTTP, RPC, and MCP server used by both GUI and headless modes
+
+The default desktop build is platform-aware:
+
+| Platform | Desktop feature path |
+| --- | --- |
+| Windows | `cuda` |
+| Linux | `cuda` |
+| macOS on Apple Silicon | `metal` |
 
 ## Prerequisites
 
 - [Rust](https://www.rust-lang.org/tools/install) 1.92 or later
 - [Bun](https://bun.sh/) 1.0 or later
 
+For Windows source builds, install:
+
+- Visual Studio C++ build tools
+- the CUDA Toolkit if you want the default CUDA-enabled desktop build
+
+The repository's `scripts/dev.ts` helper tries to discover `nvcc` and `cl.exe` automatically on Windows before launching Tauri.
+
 ## Install dependencies
 
 ```bash
 bun install
 ```
 
-## Build the project
+## Recommended desktop build
 
 ```bash
 bun run build
 ```
 
-The built binaries will be placed in `target/release`.
+This is the normal source-build path for most users. It runs the repository's Bun helper, which then launches Tauri with the project's expected build flow.
+
+On Windows, that wrapper also tries to discover `nvcc` and `cl.exe` automatically before starting the build.
+
+The main binaries are written to `target/release`:
+
+- `target/release/koharu`
+- `target/release/koharu.exe` on Windows
+
+## Development build
+
+If you are actively working on the app instead of producing a release-style binary, use:
+
+```bash
+bun run dev
+```
+
+The dev script launches `tauri dev` and starts the local server on a fixed port so the desktop shell and UI can talk to the same runtime during development.
+
+## Detailed Tauri control
+
+If you want to control the Tauri invocation directly instead of going through the wrapper, use:
+
+```bash
+bun tauri build --release --no-bundle
+```
+
+This is closer to the underlying Tauri command and is useful when you want more explicit control over the build invocation.
+
+Unlike `bun run build`, this path does not go through the repository's Windows helper that tries to configure CUDA and Visual Studio tooling for you first.
+
+## Direct Rust builds
+
+If you only want to build the Rust crate directly and intentionally bypass the Bun and Tauri wrapper, use `bun cargo` rather than calling `cargo` yourself.
+
+Examples:
+
+```bash
+# Windows / Linux
+bun cargo build --release -p koharu --features=cuda
+
+# macOS Apple Silicon
+bun cargo build --release -p koharu --features=metal
+```
+
+This is useful for lower-level Rust work, but `bun run build` remains the better choice for a normal desktop app build because it preserves the full Tauri packaging flow.
+
+## What happens at runtime after the build
+
+Building the app does not bundle every model weight. On first launch, Koharu still needs to:
+
+- initialize runtime libraries under the local app data directory
+- download the default vision and OCR models
+- download optional local translation LLMs later when you choose them in Settings
+
+If you want to prefetch those dependencies without starting the app, see [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md).

docs/how-to/configure-mcp-clients.md

@@ -0,0 +1,255 @@
+---
+title: Configure MCP Clients
+---
+
+# Configure MCP Clients
+
+Koharu exposes a built-in MCP server over local Streamable HTTP. This page shows how to connect MCP clients to it, with detailed setup for Antigravity, Claude Desktop, and Claude Code.
+
+## What Koharu exposes over MCP
+
+Koharu's MCP server is the same local runtime used by the desktop app and headless Web UI. In practice, the MCP tools cover:
+
+- document loading and inspection
+- image previews for original, segment, inpainted, and rendered layers
+- detect, OCR, inpaint, render, and full pipeline processing
+- LLM model listing, loading, unloading, and translation
+- text-block editing and export
+
+That means an MCP client can drive the same manga workflow that Koharu's GUI uses.
+
+## 1. Start Koharu on a stable port
+
+Use a fixed port so your MCP client always has the same URL.
+
+```bash
+# macOS / Linux
+koharu --port 9999 --headless
+
+# Windows
+koharu.exe --port 9999 --headless
+```
+
+You can also keep the desktop window and still expose MCP:
+
+```bash
+# macOS / Linux
+koharu --port 9999
+
+# Windows
+koharu.exe --port 9999
+```
+
+Koharu's MCP endpoint will then be:
+
+```text
+http://127.0.0.1:9999/mcp
+```
+
+Important details:
+
+- keep Koharu running while the MCP client is connected
+- Koharu binds to `127.0.0.1` by default, so these examples assume the MCP client is on the same machine
+- no authentication headers are required for the default local setup
+
+## 2. Quick endpoint check
+
+Before editing any client config, make sure Koharu is actually running on the expected port.
+
+Open:
+
+```text
+http://127.0.0.1:9999/
+```
+
+If the Web UI loads, the local server is up and the MCP endpoint should also exist at `/mcp`.
+
+## Antigravity
+
+Antigravity can point directly at Koharu's local MCP URL through its raw MCP config.
+
+### Steps
+
+1. Start Koharu with `--port 9999`.
+2. Open Antigravity.
+3. Open the `...` menu at the top of the editor's agent panel.
+4. Click **Manage MCP Servers**.
+5. Click **View raw config**.
+6. Add a `koharu` entry under `mcpServers`.
+7. Save the config.
+8. Restart Antigravity if it does not reload the MCP server automatically.
+
+### Example config
+
+```json
+{
+  "mcpServers": {
+    "koharu": {
+      "serverUrl": "http://127.0.0.1:9999/mcp"
+    }
+  }
+}
+```
+
+If you already have other MCP servers configured, add `koharu` alongside them instead of replacing the whole `mcpServers` object.
+
+### After setup
+
+Ask Antigravity something simple first:
+
+- `What tools are available from Koharu?`
+- `How many documents are currently loaded in Koharu?`
+
+If that works, move on to page actions such as:
+
+- `Open C:\\manga\\page-01.png in Koharu and run detect and OCR.`
+- `Show me the segment mask for document 0.`
+- `Run the full pipeline on document 0 and export the rendered page.`
+
+## Claude Desktop
+
+Claude Desktop's current local MCP config is command-based. Because Koharu exposes a local HTTP MCP endpoint rather than a packaged desktop extension, the practical config-file path is to use a small bridge process that connects Claude Desktop to `http://127.0.0.1:9999/mcp`.
+
+This guide uses `mcp-remote` for that bridge.
+
+### Before you start
+
+Make sure one of these is true:
+
+- `npx` is already available on your machine
+- Node.js is installed so `npx` can run
+
+### Steps
+
+1. Start Koharu with `--port 9999`.
+2. Open Claude Desktop.
+3. Open **Settings**.
+4. Open the **Developer** section.
+5. Open the MCP config file from Claude Desktop's built-in editor entry.
+6. Add a `koharu` server entry.
+7. Save the file.
+8. Fully restart Claude Desktop.
+
+### Windows config
+
+```json
+{
+  "mcpServers": {
+    "koharu": {
+      "command": "C:\\Progra~1\\nodejs\\npx.cmd",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http://127.0.0.1:9999/mcp"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+### macOS / Linux config
+
+```json
+{
+  "mcpServers": {
+    "koharu": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "http://127.0.0.1:9999/mcp"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+Notes:
+
+- if you already have other entries in `mcpServers`, add `koharu` without deleting them
+- `mcp-remote@latest` is fetched on first use, so the first startup may need internet access
+- if your Windows Node install is not under `C:\\Program Files\\nodejs`, update the `command` path accordingly
+- Anthropic's current remote-MCP connector flow for Claude Desktop is managed through **Settings > Connectors** for actual remote servers; this page intentionally covers the config-file bridge pattern for Koharu's local `127.0.0.1` endpoint
+
+### After setup
+
+Open a new Claude Desktop chat and ask:
+
+- `What Koharu MCP tools do you have available?`
+- `Check whether Koharu has any loaded documents.`
+
+Then move to actual page work:
+
+- `Open D:\\manga\\page-01.png in Koharu.`
+- `Run detect, OCR, inpaint, translate, and render for document 0.`
+- `Show me the rendered output for document 0.`
+
+## Claude Code
+
+If by "Claude" you mean Claude Code, the safest setup for Koharu's local `http://127.0.0.1` MCP endpoint is also to use the same stdio bridge pattern.
+
+### Add it to your user config
+
+macOS / Linux:
+
+```bash
+claude mcp add-json koharu "{\"type\":\"stdio\",\"command\":\"npx\",\"args\":[\"-y\",\"mcp-remote@latest\",\"http://127.0.0.1:9999/mcp\"],\"env\":{}}" --scope user
+```
+
+This writes the server into Claude Code's MCP configuration for your user account.
+
+Windows:
+
+```bash
+claude mcp add-json koharu "{\"type\":\"stdio\",\"command\":\"cmd\",\"args\":[\"/c\",\"npx\",\"-y\",\"mcp-remote@latest\",\"http://127.0.0.1:9999/mcp\"],\"env\":{}}" --scope user
+```
+
+On native Windows, Claude Code's docs explicitly recommend the `cmd /c npx` wrapper for local stdio MCP servers that use `npx`.
+
+### Verify it
+
+```bash
+claude mcp get koharu
+claude mcp list
+```
+
+If you already configured Koharu in Claude Desktop, Claude Code can also import compatible entries from Claude Desktop on supported platforms:
+
+```bash
+claude mcp add-from-claude-desktop --scope user
+```
+
+## First tasks to try
+
+Once the client is connected, these are good first tasks:
+
+- ask Koharu for the loaded document count
+- open one page image from disk
+- run detect and OCR only first
+- inspect the segment or rendered layer before running a full export
+
+This makes failures easier to diagnose than jumping straight into a full batch pipeline.
+
+## Common mistakes
+
+- starting Koharu without `--port`, then trying to connect a client to the wrong port
+- using `http://127.0.0.1:9999/` instead of `http://127.0.0.1:9999/mcp`
+- closing Koharu after adding the client config
+- replacing your entire client config instead of merging a new `koharu` entry
+- expecting Claude Desktop to connect directly to Koharu's HTTP URL through a plain command-less config entry
+- forgetting that Koharu's default local server is only reachable from the same machine
+
+## Related pages
+
+- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md)
+- [MCP Tools Reference](../reference/mcp-tools.md)
+- [CLI Reference](../reference/cli.md)
+- [Troubleshooting](troubleshooting.md)
+
+## External references
+
+- [Claude Code MCP docs](https://code.claude.com/docs/en/mcp)
+- [Claude Help: Building custom connectors via remote MCP servers](https://support.claude.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers)
+- [Wolfram support article with current Antigravity and Claude Desktop MCP config examples](https://support.wolfram.com/73463/)

docs/how-to/contributing.md

@@ -0,0 +1,174 @@
+---
+title: Contributing
+---
+
+# Contributing
+
+Koharu accepts contributions to the Rust workspace, the Tauri app shell, the Next.js UI, the ML pipeline, MCP integrations, tests, and documentation.
+
+This guide focuses on the current repository workflow so you can make changes that match CI and are easy to review.
+
+## Before you start
+
+You should have:
+
+- [Rust](https://www.rust-lang.org/tools/install) 1.92 or later
+- [Bun](https://bun.sh/) 1.0 or later
+
+On Windows, source builds also expect:
+
+- Visual Studio C++ build tools
+- the CUDA Toolkit for the normal CUDA-enabled local build path
+
+If you have not built Koharu locally before, read [Build From Source](build-from-source.md) first.
+
+## Repository layout
+
+The main top-level areas are:
+
+- `koharu/`: the Tauri desktop application shell
+- `koharu-*`: Rust workspace crates for runtime, ML, pipeline, RPC, rendering, PSD export, and types
+- `ui/`: the web UI used inside the desktop shell and headless mode
+- `e2e/`: Playwright end-to-end tests and fixtures
+- `docs/`: the documentation site content
+
+If you are not sure where a change belongs:
+
+- UI interaction and panels usually live in `ui/`
+- backend APIs, MCP tools, and orchestration usually live in `koharu-rpc/` or `koharu-pipeline/`
+- rendering, OCR, model runtime, and ML-specific logic live in the Rust workspace crates
+
+## Set up the repository
+
+Install JS dependencies first:
+
+```bash
+bun install
+```
+
+For a normal local desktop build, use:
+
+```bash
+bun run build
+```
+
+For active development, use:
+
+```bash
+bun run dev
+```
+
+The dev command runs the Tauri app in dev mode and keeps the local server on a fixed port for UI development and e2e tests.
+
+## Use the repo's preferred local commands
+
+For local Rust commands, prefer `bun cargo` instead of calling `cargo` directly.
+
+Examples:
+
+```bash
+bun cargo fmt -- --check
+bun cargo check
+bun cargo clippy -- -D warnings
+bun cargo test --workspace --tests
+```
+
+For UI formatting, use:
+
+```bash
+bun run format
+```
+
+For docs validation, use:
+
+```bash
+zensical build -c
+```
+
+## What to run before opening a PR
+
+Run the checks that match the area you changed.
+
+If you changed Rust code:
+
+- `bun cargo fmt -- --check`
+- `bun cargo check`
+- `bun cargo clippy -- -D warnings`
+- `bun cargo test --workspace --tests`
+
+If you changed the desktop app or full integration flow:
+
+- `bun run build`
+
+If you changed the UI or interaction flow:
+
+- `bun run format`
+- `bun run test:e2e`
+
+If you changed docs:
+
+- `zensical build -c`
+
+You do not always need to run every command in this list for every PR, but you should run enough to cover the code paths you touched.
+
+## E2E tests
+
+Koharu includes Playwright tests under `e2e/`.
+
+Run them with:
+
+```bash
+bun run test:e2e
+```
+
+The current Playwright setup starts Koharu through:
+
+```bash
+bun run dev -- --headless
+```
+
+and waits for the local API to come up before running the browser tests.
+
+## Docs changes
+
+Docs live in `docs/` and are built by Zensical.
+
+When updating docs:
+
+- keep instructions aligned with the current implementation
+- prefer concrete commands and real paths over generic advice
+- update navigation in `zensical.toml` if you add a new page
+- build the docs locally with `zensical build -c`
+
+## Pull request expectations
+
+A good contribution usually has:
+
+- one clear goal
+- code that follows existing patterns instead of introducing a new style unnecessarily
+- tests or validation steps that match the change
+- a PR description that explains what changed and how you verified it
+
+Small, focused PRs are easier to review than large mixed changes.
+
+If your change affects user-visible behavior, mention:
+
+- what the old behavior was
+- what the new behavior is
+- how you tested it
+
+## AI-generated PRs
+
+AI-generated contributions are welcome, provided:
+
+1. A human has reviewed the code before opening the PR.
+2. The submitter understands the changes being made.
+
+That rule already exists in the repository's GitHub contribution guidance and remains in effect here as well.
+
+## Related pages
+
+- [Build From Source](build-from-source.md)
+- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md)
+- [Configure MCP Clients](configure-mcp-clients.md)
+- [Troubleshooting](troubleshooting.md)

docs/how-to/export-and-manage-projects.md

@@ -4,26 +4,103 @@ title: Export Pages and Manage Projects
 
 # Export Pages and Manage Projects
 
+Koharu's workflow is page-based. You import image pages, run the pipeline, review text blocks, and then export either flattened output or a layered handoff file for manual finishing.
+
+## Supported page inputs
+
+The current import flow is image-based. Koharu accepts:
+
+- `.png`
+- `.jpg`
+- `.jpeg`
+- `.webp`
+
+Folder import recursively scans for supported image files and ignores everything else.
+
 ## Export rendered output
 
 Koharu can export the current page as a rendered image.
 
 Use this when you want a final flattened result for reading, sharing, or publishing.
 
+Implementation details:
+
+- rendered export uses the page's original image extension when possible
+- Koharu names the exported file with a `_koharu` suffix
+- rendered export requires the page to already have a rendered layer
+
+Example output names:
+
+- `page-001_koharu.png`
+- `chapter-03_koharu.jpg`
+
+## Export inpainted output
+
+Koharu also keeps an inpainted layer in the pipeline, which is useful when you want a cleaned page without translated lettering.
+
+This is most useful for:
+
+- external lettering workflows
+- cleanup review
+- batch export of text-removed pages
+
+When exported, Koharu uses an `_inpainted` filename suffix.
+
 ## Export layered PSD files
 
 Koharu can also export a layered Photoshop PSD.
 
-PSD export preserves helper layers and writes translated text as editable text layers, which makes final cleanup in Photoshop much easier.
+PSD export is the handoff format for users who want to keep working in Photoshop or a PSD-compatible editor after the ML pipeline is done.
 
-## Work with `.khr` project files
+In the current implementation, PSD export uses editable text layers by default and can include:
 
-Koharu stores project data in `.khr` files.
+- the original image
+- the inpainted image
+- the segmentation mask
+- the brush layer
+- translated text layers
+- a merged composite image
 
-On Windows, Koharu automatically associates `.khr` files so they can be opened by double-clicking. These files can also be viewed in ways that expose the thumbnails of their contained images.
+That makes the PSD much more useful than a flat image when you still need to:
+
+- tweak wording
+- adjust bubble fit
+- repaint artifacts
+- hide or inspect helper layers
+
+Koharu names PSD exports with a `_koharu.psd` suffix.
+
+## PSD export limitations
+
+Koharu currently writes classic PSD files, not PSB files. That means very large pages can fail to export.
+
+The implementation rejects dimensions above `30000 x 30000`.
+
+## Manage loaded page sets
+
+Koharu lets you work with multiple loaded pages in one session.
+
+The practical choices are:
+
+- open images and replace the current set
+- append more images to the current set
+- open a folder and load its supported image files
+- append a folder to the current set
+
+This is the main way to manage a chapter or batch job inside the app today.
 
 ## When to use each format
 
-- Rendered image: best for final delivery
-- PSD: best for manual cleanup and touch-up work
-- `.khr`: best for saving in-progress Koharu projects
+| Output | Best for |
+| --- | --- |
+| Rendered image | final delivery, reading copies, simple sharing |
+| Inpainted image | external lettering, cleanup review, text-removal workflows |
+| PSD | manual cleanup, touch-up, editable translated text |
+
+## Recommended workflow
+
+If you care about polish, a good pattern is:
+
+1. run detection, OCR, translation, and render in Koharu
+2. export a rendered image for quick review
+3. export a PSD when you want editable text and helper layers for final cleanup

docs/how-to/index.md

@@ -8,7 +8,11 @@ How-to guides focus on specific jobs you may want to complete with Koharu.
 
 ## Common tasks
 
-- [Install Koharu](install-koharu.md)
-- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md)
-- [Export Pages and Manage Projects](export-and-manage-projects.md)
-- [Build From Source](build-from-source.md)
+- [Install Koharu](install-koharu.md): release setup, first-run downloads, and acceleration expectations
+- [Contributing](contributing.md): repository layout, local commands, validation steps, and PR expectations
+- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md): local deployment patterns and runtime flags
+- [Configure MCP Clients](configure-mcp-clients.md): connect Antigravity, Claude Desktop, or Claude Code to Koharu's local MCP endpoint
+- [Use OpenAI-Compatible APIs](use-openai-compatible-api.md): connect LM Studio, OpenRouter, and other OpenAI-style chat-completions endpoints
+- [Export Pages and Manage Projects](export-and-manage-projects.md): rendered images, PSD handoff, and page-set management
+- [Build From Source](build-from-source.md): local developer build flow with Bun, Tauri, and platform features
+- [Troubleshooting](troubleshooting.md): common startup, download, GPU, pipeline, and connectivity failures

docs/how-to/install-koharu.md

@@ -16,16 +16,28 @@ Koharu provides prebuilt binaries for:
 
 If your platform is not covered by a release build, use [Build From Source](build-from-source.md).
 
+## What gets installed locally
+
+Koharu is a local-first app. In practice, the desktop binary is only part of the installation footprint. The first real run also creates a per-user local data directory for:
+
+- runtime libraries used by llama.cpp and GPU backends
+- downloaded vision and OCR models
+- optional local translation models you select later
+
+Koharu keeps its own files under a `Koharu` app-data root and stores model weights separately from the application binary.
+
 ## First launch expectations
 
 On first run, Koharu may:
 
-- extract bundled runtime libraries
-- download required vision models
-- download local LLMs later when you select them in Settings
+- extract or download runtime libraries required by the local inference stack
+- download the default vision and OCR models used by detection, segmentation, OCR, inpainting, and font estimation
+- wait to download local translation LLMs until you actually select them in Settings
 
 This is normal and can take time depending on your connection and hardware.
 
+If you want to prefetch those runtime dependencies ahead of time, run Koharu once with `--download`. That path initializes the runtime packages and default vision stack, then exits without opening the GUI.
+
 ## GPU acceleration notes
 
 Koharu supports:
@@ -35,12 +47,33 @@ Koharu supports:
 - Vulkan on Windows and Linux for OCR and LLM inference
 - CPU fallback on all platforms
 
-For CUDA, Koharu bundles CUDA toolkit 13.1, then extracts the required dynamic libraries into the app data directory on first run.
+Some practical details matter:
+
+- detection and inpainting benefit most from CUDA or Metal
+- Vulkan is mainly the fallback GPU path for OCR and local LLM inference
+- if Koharu cannot verify that your NVIDIA driver supports CUDA 13.1, it falls back to CPU
+
+For CUDA-capable systems, Koharu bundles and initializes the runtime pieces it needs instead of requiring you to wire every library path by hand.
 
 !!! note
 
     Keep your NVIDIA driver up to date. Koharu checks for CUDA 13.1 support and falls back to CPU if the driver is too old.
 
+## After installation
+
+Once Koharu launches successfully, the next decisions are usually:
+
+- desktop GUI vs headless mode
+- local translation model vs remote provider
+- rendered export vs layered PSD export
+
+See:
+
+- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md)
+- [Models and Providers](../explanation/models-and-providers.md)
+- [Export Pages and Manage Projects](export-and-manage-projects.md)
+- [Troubleshooting](troubleshooting.md)
+
 ## Need help?
 
 For support, join the [Discord server](https://discord.gg/mHvHkxGnUY).

docs/how-to/run-gui-headless-and-mcp.md

@@ -4,17 +4,37 @@ title: Run GUI, Headless, and MCP Modes
 
 # Run GUI, Headless, and MCP Modes
 
-Koharu can run as a normal desktop app, a headless local server with a Web UI, or an MCP server for AI agents.
+Koharu can run as a normal desktop app, a headless local server with a Web UI, or an MCP server for AI agents. These are not separate backends. They all sit on top of the same local runtime and HTTP server.
+
+## What stays the same across modes
+
+No matter how you launch Koharu, the runtime model is the same:
+
+- the server binds to `127.0.0.1`
+- the UI and API are served by the same local process
+- the page pipeline, model loading, and exports use the same internal code paths
+
+That is why desktop editing, headless automation, and MCP tooling stay aligned.
+
+## Mode summary
+
+| Mode | Desktop window | Local server | Typical use |
+| --- | --- | --- | --- |
+| Desktop | yes | yes | normal interactive editing |
+| Headless | no | yes | local Web UI, scripting, automation |
+| MCP | optional | yes | agent tooling through `/mcp` |
 
 ## Run the desktop app
 
 Launch Koharu normally from your installed application.
 
+Even in desktop mode, Koharu still starts a local HTTP server internally. The embedded window talks to that local server rather than calling the pipeline directly.
+
 This is the default mode and is the best choice for most users.
 
 ## Run headless mode
 
-Headless mode starts the local HTTP server without opening the desktop GUI.
+Headless mode starts the local server without opening the desktop GUI.
 
 ```bash
 # macOS / Linux
@@ -26,9 +46,11 @@ koharu.exe --port 4000 --headless
 
 After startup, open the Web UI at `http://localhost:4000`.
 
+Headless mode stays in the foreground until you stop it, typically with `Ctrl+C`.
+
 ## Run with a fixed port
 
-By default, Koharu uses a random local port. Use `--port` when you need a stable address.
+By default, Koharu uses a random local port. Use `--port` when you need a stable address for bookmarks, scripts, reverse proxies, or MCP clients.
 
 ```bash
 # macOS / Linux
@@ -38,13 +60,40 @@ koharu --port 9999
 koharu.exe --port 9999
 ```
 
+If you do not specify `--port`, Koharu still starts the server, but the chosen port is dynamic.
+
+## Connect to the local API
+
+When Koharu is running on a fixed port, the main endpoints are:
+
+- Web UI: `http://localhost:9999/`
+- RPC / HTTP API: `http://localhost:9999/api/v1`
+- MCP server: `http://localhost:9999/mcp`
+
+Replace `9999` with the port you chose.
+
+Because Koharu binds to loopback, these endpoints are local by default. If you want remote access from another machine, you need to expose that port yourself through your own network setup.
+
+For endpoint-level details, see [HTTP API Reference](../reference/http-api.md).
+
 ## Connect to the MCP server
 
-Koharu includes a built-in MCP server. When you run Koharu on a fixed port, point your AI agent at:
+Koharu includes a built-in MCP server using the same loaded documents, models, and page pipeline as the rest of the app.
+
+Point your MCP client or agent at:
 
 `http://localhost:9999/mcp`
 
-Replace `9999` with the port you chose.
+This is useful when you want an agent to:
+
+- inspect text blocks
+- run OCR or translation
+- export rendered pages
+- automate review or batch workflows
+
+For client-specific setup examples, see [Configure MCP Clients](configure-mcp-clients.md).
+
+For the built-in tool list itself, see [MCP Tools Reference](../reference/mcp-tools.md).
 
 ## Force CPU mode
 
@@ -58,9 +107,11 @@ koharu --cpu
 koharu.exe --cpu
 ```
 
+This is useful for compatibility testing, driver issues, or low-risk debugging when GPU setup is uncertain.
+
 ## Download runtime dependencies only
 
-Use `--download` if you want Koharu to fetch runtime packages and exit without starting the app.
+Use `--download` if you want Koharu to prefetch runtime dependencies and exit without starting the app.
 
 ```bash
 # macOS / Linux
@@ -69,3 +120,24 @@ koharu --download
 # Windows
 koharu.exe --download
 ```
+
+In the current implementation, this path initializes:
+
+- runtime libraries used by the local inference stack
+- the default vision and OCR models
+
+It does not predownload every optional local translation LLM. Those are still fetched when you select them in Settings.
+
+## Enable debug output
+
+Use `--debug` when you want console-oriented startup with log output.
+
+```bash
+# macOS / Linux
+koharu --debug
+
+# Windows
+koharu.exe --debug
+```
+
+On Windows, debug and headless runs also influence how Koharu attaches to or creates a console window.

docs/how-to/troubleshooting.md

@@ -0,0 +1,276 @@
+---
+title: Troubleshooting
+---
+
+# Troubleshooting
+
+This page covers the most common Koharu problems that follow from the current implementation: first-run downloads, runtime initialization, GPU fallback, headless and MCP access, pipeline-stage ordering, and source-build setup.
+
+## Before you start
+
+When troubleshooting, first identify which layer is failing:
+
+- application startup
+- runtime or model downloads
+- GPU acceleration
+- page pipeline stages such as detect, OCR, inpaint, or render
+- headless or MCP connectivity
+- source build and local development
+
+That usually narrows the problem quickly.
+
+## Koharu does not start cleanly on first launch
+
+Possible causes:
+
+- runtime libraries have not finished downloading or extracting yet
+- the first-run model downloads are still in progress
+- the machine is missing local permissions for its app-data directory
+- GPU initialization failed and the app is trying to fall back
+
+Try this:
+
+1. wait longer on the very first launch, especially on slower disks or networks
+2. start Koharu once with `--download` to prefetch runtime dependencies without opening the GUI
+3. start once with `--cpu` to check whether the problem is GPU-related
+4. start once with `--debug` to get console-oriented logs
+
+```bash
+# macOS / Linux
+koharu --download
+koharu --cpu
+koharu --debug
+
+# Windows
+koharu.exe --download
+koharu.exe --cpu
+koharu.exe --debug
+```
+
+If `--cpu` works and the normal launch does not, the problem is usually in the GPU path rather than the general app startup path.
+
+## Model or runtime downloads fail
+
+Koharu needs network access on first use for:
+
+- llama.cpp runtime packages
+- GPU runtime support files where applicable
+- the default vision and OCR model stack
+- optional local translation models when selected later
+
+Likely causes:
+
+- intermittent network failures
+- blocked access to GitHub release assets or model hosting
+- local filesystem permission issues in the app-data directory
+
+What to check:
+
+- whether GitHub and Hugging Face downloads are reachable from the machine
+- whether retrying `--download` succeeds
+- whether another process or security tool is locking files in the local runtime directory
+
+If downloads keep failing, test on a different network first. That quickly distinguishes a machine-local problem from an upstream reachability issue.
+
+## Koharu falls back to CPU even though you have an NVIDIA GPU
+
+This is expected when Koharu cannot confirm support for CUDA 13.1.
+
+The current runtime behavior is:
+
+- detect an NVIDIA driver
+- query driver compatibility
+- continue on CUDA only when the driver reports CUDA 13.1 support
+- otherwise fall back to CPU
+
+Try this:
+
+1. update the NVIDIA driver
+2. restart Koharu after the update
+3. verify behavior with `--debug`
+
+If the driver is old or the CUDA check fails, Koharu deliberately prefers CPU over a partially working CUDA configuration.
+
+## OCR, inpainting, or export says something is missing
+
+Some errors are just pipeline ordering problems.
+
+Common examples from the current API and MCP layer:
+
+- `No segment mask available. Run detect first.`
+- `No rendered image found`
+- `No inpainted image found`
+
+These usually mean a required earlier stage has not produced its output yet.
+
+Use this order:
+
+1. Detect
+2. OCR
+3. Inpaint
+4. LLM Generate
+5. Render
+6. Export
+
+If export fails because there is no rendered or inpainted layer, rerun the missing stage instead of retrying export repeatedly.
+
+## Detection or OCR quality is poor on a page
+
+Common causes:
+
+- low-resolution source images
+- unusual page crops
+- heavy screentones or noisy scans
+- vertical text mixed with difficult artwork
+- badly placed or duplicated text blocks after detection
+
+Try this:
+
+1. start from a cleaner page image if possible
+2. inspect the detected text blocks before translating
+3. fix obvious bad blocks before running the rest of the pipeline
+4. rerun later stages after the structural fixes
+
+If the structure is wrong, translation quality usually gets worse downstream because OCR and rendering both depend on the block geometry.
+
+## Headless mode starts, but you cannot open the Web UI
+
+Check the basics first:
+
+- did you pass `--headless`
+- did you choose a fixed port
+- is the process still running
+
+Example:
+
+```bash
+koharu --port 4000 --headless
+```
+
+Then open:
+
+```text
+http://localhost:4000
+```
+
+Important implementation detail:
+
+- Koharu binds to `127.0.0.1`
+
+That means the local Web UI is only available on the same machine unless you expose it yourself through your own networking setup.
+
+Also verify that another process is not already using the selected port.
+
+## The MCP client cannot connect
+
+Use a fixed port and point the client to:
+
+```text
+http://localhost:9999/mcp
+```
+
+Common mistakes:
+
+- using the root URL instead of `/mcp`
+- forgetting `--port`
+- trying to connect after the Koharu process has already exited
+- trying to reach the service from another machine without explicitly exposing the port
+
+If normal headless Web UI access works but MCP does not, check the exact URL first. Wrong path selection is more common than server failure.
+
+If the client is Antigravity, Claude Desktop, or Claude Code, follow the client-specific setup in [Configure MCP Clients](configure-mcp-clients.md).
+
+## Import appears to do nothing
+
+The current documented import flow is image-based. Koharu accepts:
+
+- `.png`
+- `.jpg`
+- `.jpeg`
+- `.webp`
+
+Folder import recursively filters files to those extensions only.
+
+If a folder import seems empty, check whether the folder actually contains supported image files instead of archives, PSDs, or other formats.
+
+## Export fails or gives you the wrong kind of output
+
+Use the output type that matches the current pipeline state:
+
+- rendered export requires a rendered layer
+- inpainted export requires an inpainted layer
+- PSD export is the best choice when you still want editable text and helper layers
+
+Also remember:
+
+- rendered exports use a `_koharu` suffix
+- inpainted exports use an `_inpainted` suffix
+- PSD export uses `_koharu.psd`
+- classic PSD export rejects images above `30000 x 30000`
+
+If the page is extremely large, resize or split it before expecting PSD export to succeed.
+
+## Source build fails on Windows
+
+The Windows build helper expects:
+
+- `nvcc` for the default CUDA build path
+- `cl.exe` from Visual Studio C++ tools
+
+The Bun wrapper script tries to discover both automatically, but if either one is missing the build can fail before Tauri finishes launching.
+
+Use the project wrapper commands:
+
+```bash
+bun install
+bun run build
+```
+
+If you want direct control over the Tauri command, try:
+
+```bash
+bun tauri build --release --no-bundle
+```
+
+If you want lower-level Rust builds, prefer:
+
+```bash
+bun cargo build --release -p koharu --features=cuda
+```
+
+If you only need to confirm that the app works at all, try a CPU-only runtime launch first instead of debugging the full CUDA toolchain immediately.
+
+## Source build fails because of the chosen feature path
+
+The desktop build is platform-aware:
+
+- Windows and Linux use `cuda`
+- macOS on Apple Silicon uses `metal`
+
+If you manually invoke lower-level cargo commands with the wrong feature set for your platform, the build can fail or produce a mismatched binary. Follow the platform examples in [Build From Source](build-from-source.md).
+
+## When to stop debugging locally
+
+You have probably isolated the issue enough to report it when:
+
+- `--cpu` works but GPU mode does not
+- `--download` consistently fails on a healthy network
+- the same page repeatedly triggers a reproducible pipeline failure
+- headless mode starts but a correct `localhost` URL still fails
+
+At that point, collect:
+
+- your OS and hardware
+- the exact command you ran
+- whether `--cpu` changes the result
+- the exact error message
+- whether the issue happens on one page or every page
+
+## Related pages
+
+- [Install Koharu](install-koharu.md)
+- [Run GUI, Headless, and MCP Modes](run-gui-headless-and-mcp.md)
+- [Configure MCP Clients](configure-mcp-clients.md)
+- [Build From Source](build-from-source.md)
+- [CLI Reference](../reference/cli.md)
+- [Technical Deep Dive](../explanation/technical-deep-dive.md)

docs/how-to/use-openai-compatible-api.md

@@ -0,0 +1,139 @@
+---
+title: Use OpenAI-Compatible APIs
+---
+
+# Use OpenAI-Compatible APIs
+
+Koharu can translate through APIs that follow the OpenAI Chat Completions shape. That includes local servers such as LM Studio and hosted routers such as OpenRouter.
+
+This page is specifically about the current OpenAI-compatible path in Koharu. It is different from Koharu's built-in OpenAI, Gemini, Claude, and DeepSeek provider presets.
+
+## What Koharu expects from a compatible endpoint
+
+In the current implementation, Koharu expects:
+
+- a base URL that points at the API root, usually ending in `/v1`
+- `GET /models` for connection testing
+- `POST /chat/completions` for translation
+- a response that includes `choices[0].message.content`
+- bearer-token authentication when an API key is provided
+
+Some implementation details matter:
+
+- Koharu trims whitespace and a trailing slash from the base URL before appending `/models` or `/chat/completions`
+- an empty API key is omitted entirely instead of sending an empty `Authorization` header
+- a compatible model only appears in Koharu's LLM picker after both `Base URL` and `Model name` are filled in
+- each configured preset shows up as its own selectable source in the LLM picker
+
+That means OpenAI-compatible here really means OpenAI API-compatible, not just "can be used with OpenAI tools in general."
+
+## Where to configure it in Koharu
+
+Open **Settings** and scroll to **Local LLM & OpenAI Compatible Providers**.
+
+The current UI exposes:
+
+- a preset selector: `Ollama`, `LM Studio`, `Preset 1`, `Preset 2`
+- `Base URL`
+- `API Key (optional)`
+- `Model name`
+- `Test Connection`
+- advanced fields for `Temperature`, `Max tokens`, and a custom system prompt
+
+`Test Connection` currently calls `/models` with a 5-second timeout and reports whether Koharu connected successfully, how many model IDs the endpoint returned, and the measured latency.
+
+## LM Studio
+
+Use the built-in `LM Studio` preset when you want a local model server on the same machine.
+
+1. Start LM Studio's local server.
+2. In Koharu, open **Settings**.
+3. Choose the `LM Studio` preset.
+4. Set `Base URL` to `http://127.0.0.1:1234/v1`.
+5. Leave `API Key` empty unless you configured authentication in front of LM Studio.
+6. Enter the exact LM Studio model identifier in `Model name`.
+7. Click `Test Connection`.
+8. Open Koharu's LLM picker and select the LM Studio-backed model entry.
+
+Notes:
+
+- Koharu's default LM Studio preset already uses `http://127.0.0.1:1234/v1`
+- LM Studio's official docs use the same OpenAI-compatible base path on port `1234`
+- Koharu's connection test only shows the model count, not the full model names, so you still need to know the exact model ID you want to use
+
+If you are unsure about the model identifier, query LM Studio directly:
+
+```bash
+curl http://127.0.0.1:1234/v1/models
+```
+
+Then copy the `id` field for the model you want.
+
+Official references:
+
+- [LM Studio OpenAI compatibility docs](https://lmstudio.ai/docs/developer/openai-compat)
+- [LM Studio list models endpoint](https://lmstudio.ai/docs/developer/openai-compat/models)
+
+## OpenRouter
+
+Use `Preset 1` or `Preset 2` for hosted OpenAI-compatible services such as OpenRouter. That avoids overwriting the local LM Studio preset.
+
+1. Create an API key in OpenRouter.
+2. In Koharu, open **Settings**.
+3. Choose `Preset 1` or `Preset 2`.
+4. Set `Base URL` to `https://openrouter.ai/api/v1`.
+5. Paste your OpenRouter API key into `API Key`.
+6. Enter the exact OpenRouter model ID in `Model name`.
+7. Click `Test Connection`.
+8. Select that preset-backed model from Koharu's LLM picker.
+
+Important details:
+
+- OpenRouter model IDs should include the organization prefix, not just a display name
+- Koharu currently sends standard bearer auth and a normal OpenAI-style chat-completions request body
+- OpenRouter supports extra headers such as `HTTP-Referer` and `X-OpenRouter-Title`, but Koharu does not currently expose fields for those optional headers
+
+Official references:
+
+- [OpenRouter API overview](https://openrouter.ai/docs/api/reference/overview)
+- [OpenRouter authentication](https://openrouter.ai/docs/api/reference/authentication)
+- [OpenRouter models](https://openrouter.ai/models)
+
+## Other compatible endpoints
+
+For other self-hosted or routed APIs, use the same checklist:
+
+- use the API root as `Base URL`, not the full `/chat/completions` URL
+- make sure the endpoint supports `GET /models`
+- make sure it supports `POST /chat/completions`
+- use the exact model `id`, not just a marketing name
+- provide an API key if the server requires bearer authentication
+
+If the server only implements `Responses` or some custom schema, Koharu's current OpenAI-compatible integration will not work without an adapter or proxy because Koharu currently talks to `chat/completions`.
+
+## How model selection works in practice
+
+Koharu does not treat these endpoints as one generic remote bucket. Instead, each configured preset becomes its own LLM entry source.
+
+For example:
+
+- `LM Studio` can point at a local server
+- `Preset 1` can point at OpenRouter
+- `Preset 2` can point at another self-hosted OpenAI-compatible API
+
+That lets you keep multiple compatible backends configured and switch between them from the normal LLM picker.
+
+## Common mistakes
+
+- using a base URL without `/v1`
+- pasting the full `/chat/completions` URL into `Base URL`
+- leaving `Model name` empty and expecting the model to appear anyway
+- using a display label instead of the exact API model ID
+- assuming `Test Connection` loads or selects a model for you
+- trying to use an endpoint that only supports the newer `Responses` API
+
+## Related pages
+
+- [Models and Providers](../explanation/models-and-providers.md)
+- [Translate Your First Page](../tutorials/translate-your-first-page.md)
+- [Troubleshooting](troubleshooting.md)

docs/reference/cli.md

@@ -6,6 +6,13 @@ title: CLI Reference
 
 This page covers the command-line options exposed by Koharu's desktop binary.
 
+Koharu uses the same binary for:
+
+- desktop startup
+- headless local Web UI
+- the local HTTP API
+- the built-in MCP server
+
 ## Common usage
 
 ```bash
@@ -20,11 +27,26 @@ koharu.exe [OPTIONS]
 
 | Option | Meaning |
 | --- | --- |
-| `-d`, `--download` | Download runtime libraries and exit |
+| `-d`, `--download` | Prefetch runtime libraries and the default vision and OCR stack, then exit |
 | `--cpu` | Force CPU mode even when a GPU is available |
-| `-p`, `--port <PORT>` | Bind the local HTTP server to a specific port |
+| `-p`, `--port <PORT>` | Bind the local HTTP server to a specific `127.0.0.1` port instead of a random one |
 | `--headless` | Run without starting the desktop GUI |
-| `--debug` | Enable debug mode with console output |
+| `--debug` | Enable debug-oriented console output |
+
+## Behavior notes
+
+Some flags change more than just startup appearance:
+
+- without `--port`, Koharu chooses a random local port
+- with `--headless`, Koharu skips the Tauri window but still serves the Web UI and API
+- with `--download`, Koharu exits after dependency prefetch and does not stay running
+- with `--cpu`, both the vision stack and local LLM path avoid GPU acceleration
+
+When a fixed port is set, the main local endpoints are:
+
+- `http://localhost:<PORT>/`
+- `http://localhost:<PORT>/api/v1`
+- `http://localhost:<PORT>/mcp`
 
 ## Common patterns
 
@@ -45,3 +67,21 @@ Download runtime packages ahead of time:
 ```bash
 koharu --download
 ```
+
+Run a local MCP endpoint on a stable port:
+
+```bash
+koharu --port 9999
+```
+
+Then connect your MCP client to:
+
+```text
+http://localhost:9999/mcp
+```
+
+Start with explicit debug logging:
+
+```bash
+koharu --debug
+```

docs/reference/http-api.md

@@ -0,0 +1,196 @@
+---
+title: HTTP API Reference
+---
+
+# HTTP API Reference
+
+Koharu exposes a local HTTP API under:
+
+```text
+http://127.0.0.1:<PORT>/api/v1
+```
+
+This is the same API used by the desktop UI and headless Web UI.
+
+## Runtime model
+
+Important behavior from the current implementation:
+
+- the API is served by the same process as the GUI or headless runtime
+- the server binds to `127.0.0.1` by default
+- the API and MCP server share the same loaded documents, models, and pipeline state
+- when no `--port` is provided, Koharu chooses a random local port
+
+## Common response shapes
+
+Frequently used types include:
+
+- `MetaInfo`: app version and ML device
+- `DocumentSummary`: document id, name, size, revision, layer availability, and text-block count
+- `DocumentDetail`: full document metadata plus text blocks
+- `JobState`: current pipeline job progress
+- `LlmState`: current LLM load state
+- `ImportResult`: imported document count and summaries
+- `ExportResult`: count of exported files
+
+## Endpoints
+
+### Meta and fonts
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/meta` | get app version and active ML backend |
+| `GET` | `/fonts` | list font families available for rendering |
+
+### Documents
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/documents` | list loaded documents |
+| `POST` | `/documents/import?mode=replace` | replace the current document set with uploaded images |
+| `POST` | `/documents/import?mode=append` | append uploaded images to the current document set |
+| `GET` | `/documents/{documentId}` | get one document and all text-block metadata |
+| `GET` | `/documents/{documentId}/thumbnail` | get a thumbnail image |
+| `GET` | `/documents/{documentId}/layers/{layer}` | fetch one image layer |
+
+The import endpoint uses multipart form data with repeated `files` fields.
+
+Document layers currently exposed by the implementation include:
+
+- `original`
+- `segment`
+- `inpainted`
+- `brush`
+- `rendered`
+
+### Page pipeline
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/documents/{documentId}/detect` | detect text blocks and layout |
+| `POST` | `/documents/{documentId}/ocr` | run OCR on detected text blocks |
+| `POST` | `/documents/{documentId}/inpaint` | remove original text using the current mask |
+| `POST` | `/documents/{documentId}/render` | render translated text |
+| `POST` | `/documents/{documentId}/translate` | generate translations for one block or the full page |
+| `PUT` | `/documents/{documentId}/mask-region` | replace or update part of the segmentation mask |
+| `PUT` | `/documents/{documentId}/brush-region` | write a patch into the brush layer |
+| `POST` | `/documents/{documentId}/inpaint-region` | re-inpaint a rectangular region only |
+
+Useful request details:
+
+- `/render` accepts `textBlockId`, `shaderEffect`, `shaderStroke`, and `fontFamily`
+- `/translate` accepts `textBlockId` and `language`
+- `/mask-region` accepts `data` plus an optional `region`
+- `/brush-region` accepts `data` plus a required `region`
+- `/inpaint-region` accepts a rectangular `region`
+
+## Text blocks
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/documents/{documentId}/text-blocks` | create a new text block from `x`, `y`, `width`, `height` |
+| `PATCH` | `/documents/{documentId}/text-blocks/{textBlockId}` | patch text, translation, box geometry, or style |
+| `DELETE` | `/documents/{documentId}/text-blocks/{textBlockId}` | remove a text block |
+
+The text-block patch shape currently includes:
+
+- `text`
+- `translation`
+- `x`
+- `y`
+- `width`
+- `height`
+- `style`
+
+`style` can include font families, font size, RGBA color, text alignment, italic and bold flags, and stroke configuration.
+
+## Export
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/documents/{documentId}/export?layer=rendered` | export one rendered image |
+| `GET` | `/documents/{documentId}/export?layer=inpainted` | export one inpainted image |
+| `GET` | `/documents/{documentId}/export/psd` | export one layered PSD |
+| `POST` | `/exports?layer=rendered` | export all rendered pages |
+| `POST` | `/exports?layer=inpainted` | export all inpainted pages |
+
+Single-document export endpoints return binary file content. Bulk export returns JSON with the number of files written.
+
+## LLM control
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/llm/models` | list local and API-backed translation models |
+| `GET` | `/llm/state` | get the current LLM status |
+| `POST` | `/llm/load` | load a local or API-backed model |
+| `POST` | `/llm/offload` | unload the current model |
+| `POST` | `/llm/ping` | test an OpenAI-compatible base URL |
+
+Useful request details:
+
+- `/llm/models` accepts optional `language` and `openaiCompatibleBaseUrl` query parameters
+- `/llm/load` accepts `id`, `apiKey`, `baseUrl`, `temperature`, `maxTokens`, and `customSystemPrompt`
+- `/llm/ping` accepts `baseUrl` and optional `apiKey`
+
+## Provider API keys
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/providers/{provider}/api-key` | read a saved API key for a provider |
+| `PUT` | `/providers/{provider}/api-key` | store or overwrite a provider API key |
+
+Current built-in provider ids include:
+
+- `openai`
+- `gemini`
+- `claude`
+- `deepseek`
+- `openai-compatible`
+
+## Pipeline jobs
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/jobs/pipeline` | start a full processing job |
+| `DELETE` | `/jobs/{jobId}` | cancel a running pipeline job |
+
+The pipeline job request can include:
+
+- `documentId` to target one page, or omit it to process all loaded pages
+- LLM settings such as `llmModelId`, `llmApiKey`, `llmBaseUrl`, `llmTemperature`, `llmMaxTokens`, and `llmCustomSystemPrompt`
+- render settings such as `shaderEffect`, `shaderStroke`, and `fontFamily`
+- `language`
+
+## Events stream
+
+Koharu also exposes server-sent events at:
+
+```text
+GET /events
+```
+
+Current event names are:
+
+- `snapshot`
+- `documents.changed`
+- `document.changed`
+- `job.changed`
+- `download.changed`
+- `llm.changed`
+
+The stream sends an initial `snapshot` event and uses a 15-second keepalive.
+
+## Typical workflow
+
+The normal API order for one page is:
+
+1. `POST /documents/import?mode=replace`
+2. `POST /documents/{documentId}/detect`
+3. `POST /documents/{documentId}/ocr`
+4. `POST /llm/load`
+5. `POST /documents/{documentId}/translate`
+6. `POST /documents/{documentId}/inpaint`
+7. `POST /documents/{documentId}/render`
+8. `GET /documents/{documentId}/export?layer=rendered`
+
+If you want agent-oriented access instead of HTTP endpoint orchestration, see [MCP Tools Reference](mcp-tools.md).

docs/reference/index.md

@@ -8,5 +8,8 @@ Reference pages collect factual details you may want to look up quickly.
 
 ## Available references
 
-- [CLI Reference](cli.md)
-- [Keyboard Shortcuts](keyboard-shortcuts.md)
+- [CLI Reference](cli.md): startup flags, local server behavior, and common runtime patterns
+- [HTTP API Reference](http-api.md): local REST endpoints, event stream names, payloads, and workflow order
+- [MCP Tools Reference](mcp-tools.md): built-in MCP tool names, parameters, and suggested usage flow
+- [Settings Reference](settings.md): appearance, language, provider keys, local-LLM presets, and About page behavior
+- [Keyboard Shortcuts](keyboard-shortcuts.md): the default editor shortcuts currently documented in the UI

docs/reference/mcp-tools.md

@@ -0,0 +1,140 @@
+---
+title: MCP Tools Reference
+---
+
+# MCP Tools Reference
+
+Koharu exposes MCP tools at:
+
+```text
+http://127.0.0.1:<PORT>/mcp
+```
+
+These tools operate on the same runtime state as the GUI and HTTP API.
+
+## General behavior
+
+Important implementation details:
+
+- image-based tools can return text plus inline image content
+- `open_documents` replaces the current document set rather than appending
+- `process` starts the full pipeline but does not itself stream progress
+- `llm_load` and `process` currently accept local-model-style parameters and do not expose every HTTP API field
+
+## Inspection tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `app_version` | get the application version | none |
+| `device` | get ML device and GPU-related info | none |
+| `get_documents` | get the number of loaded documents | none |
+| `get_document` | get one document's metadata and text blocks | `index` |
+| `list_font_families` | list available render fonts | none |
+| `llm_list` | list translation models | none |
+| `llm_ready` | check whether an LLM is currently loaded | none |
+
+## Image and block preview tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `view_image` | preview a whole document layer | `index`, `layer`, optional `max_size` |
+| `view_text_block` | preview one cropped text block | `index`, `text_block_index`, optional `layer` |
+
+Valid `view_image` layers:
+
+- `original`
+- `segment`
+- `inpainted`
+- `rendered`
+
+Valid `view_text_block` layers:
+
+- `original`
+- `rendered`
+
+## Document and export tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `open_documents` | load image files from disk and replace the current set | `paths` |
+| `export_document` | write the rendered document to disk | `index`, `output_path` |
+
+`open_documents` expects filesystem paths, not uploaded file blobs.
+
+`export_document` currently exports the rendered image path only. PSD export is available through the HTTP API but does not currently have a dedicated MCP tool.
+
+## Pipeline tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `detect` | run text detection and font prediction | `index` |
+| `ocr` | run OCR on detected blocks | `index` |
+| `inpaint` | remove text using the current mask | `index` |
+| `render` | draw translated text back onto the page | `index`, optional `text_block_index`, `shader_effect`, `font_family` |
+| `process` | start detect -> OCR -> inpaint -> translate -> render | optional `index`, `llm_model_id`, `language`, `shader_effect`, `font_family` |
+
+`process` is the coarse-grained convenience tool. If you need more control or easier debugging, use the stage tools separately.
+
+## LLM tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `llm_load` | load a translation model | `id`, optional `temperature`, `max_tokens`, `custom_system_prompt` |
+| `llm_offload` | unload the current model | none |
+| `llm_generate` | translate one block or all blocks | `index`, optional `text_block_index`, `language` |
+
+`llm_generate` expects an LLM to already be loaded.
+
+## Text-block editing tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `update_text_block` | patch text, translation, box geometry, or style | `index`, `text_block_index`, optional text and style fields |
+| `add_text_block` | add a new empty text block | `index`, `x`, `y`, `width`, `height` |
+| `remove_text_block` | remove one text block | `index`, `text_block_index` |
+
+The current update tool can change:
+
+- `translation`
+- `x`
+- `y`
+- `width`
+- `height`
+- `font_families`
+- `font_size`
+- `color`
+- `shader_effect`
+
+## Mask and cleanup tools
+
+| Tool | What it does | Key parameters |
+| --- | --- | --- |
+| `dilate_mask` | expand the current text mask | `index`, `radius` |
+| `erode_mask` | shrink the current text mask | `index`, `radius` |
+| `inpaint_region` | re-inpaint a specific rectangle only | `index`, `x`, `y`, `width`, `height` |
+
+These are useful when the automatic segmentation mask is close but still needs manual cleanup.
+
+## Suggested prompt flow
+
+For reliable agent behavior, this sequence works well:
+
+1. `open_documents`
+2. `get_documents`
+3. `detect`
+4. `ocr`
+5. `get_document`
+6. `llm_load`
+7. `llm_generate`
+8. `inpaint`
+9. `render`
+10. `view_image`
+11. `export_document`
+
+If you need to inspect a problem block, use `view_text_block` before asking the agent to patch layout or translation.
+
+## Related pages
+
+- [Configure MCP Clients](../how-to/configure-mcp-clients.md)
+- [Run GUI, Headless, and MCP Modes](../how-to/run-gui-headless-and-mcp.md)
+- [HTTP API Reference](http-api.md)

docs/reference/settings.md

@@ -0,0 +1,151 @@
+---
+title: Settings Reference
+---
+
+# Settings Reference
+
+Koharu's Settings screen exposes appearance, language, device, provider, and local-LLM configuration. This page documents the current settings surface as implemented in the app.
+
+## Appearance
+
+Theme options:
+
+- `Light`
+- `Dark`
+- `System`
+
+The app uses the selected theme immediately through the frontend theme provider.
+
+## Language
+
+The current UI locale list comes from the bundled translation resources.
+
+Currently shipped locales are:
+
+- `en-US`
+- `es-ES`
+- `ja-JP`
+- `ru-RU`
+- `zh-CN`
+- `zh-TW`
+
+Changing the UI language updates the frontend locale and also influences language-aware LLM model listing in the current implementation.
+
+## Device
+
+The Settings screen shows the current ML compute backend as `ML Compute`.
+
+This value comes from the app metadata endpoint and reflects the runtime backend Koharu is currently using, such as CPU or a GPU-backed path.
+
+## API Keys
+
+The current built-in provider key section covers:
+
+- `OpenAI`
+- `Gemini`
+- `Claude`
+- `DeepSeek`
+
+Important behavior:
+
+- API keys are stored through the local keyring integration rather than plain frontend storage
+- Gemini is marked as a free-tier provider in the current UI
+- the password-style input is only a visibility toggle in the UI, not a different storage mode
+
+## Local LLM and OpenAI-compatible providers
+
+This section is used for local servers such as Ollama and LM Studio, and for custom OpenAI-compatible endpoints.
+
+### Presets
+
+Current presets:
+
+- `Ollama`
+- `LM Studio`
+- `Preset 1`
+- `Preset 2`
+
+Default base URLs:
+
+- Ollama: `http://localhost:11434/v1`
+- LM Studio: `http://127.0.0.1:1234/v1`
+- Preset 1: empty until configured
+- Preset 2: empty until configured
+
+Each preset stores its own:
+
+- `Base URL`
+- `API Key`
+- `Model name`
+- `Temperature`
+- `Max tokens`
+- `Custom system prompt`
+
+That lets you keep several compatible backends configured and switch between them from the same settings screen.
+
+### Required fields for the model picker
+
+In the current implementation, a preset-backed OpenAI-compatible model only becomes selectable when both of these are filled in:
+
+- `Base URL`
+- `Model name`
+
+An empty preset does not appear as a usable model entry.
+
+### Advanced fields
+
+The expandable advanced section currently exposes:
+
+- `Temperature`
+- `Max tokens`
+- `Custom system prompt`
+
+Behavior notes:
+
+- leaving `Temperature` or `Max tokens` empty sends no override
+- leaving `Custom system prompt` empty uses Koharu's default manga translation system prompt
+- the reset button clears only the custom prompt override for the current preset
+
+### Test Connection
+
+`Test Connection` is a connectivity check for the current preset.
+
+The current implementation:
+
+- sends a request to Koharu's `/llm/ping` path
+- checks the preset `Base URL`
+- optionally includes the preset API key
+- reports success or failure inline
+- shows model count and latency on success
+- uses a 5-second timeout for the underlying compatible-model listing
+
+This is a connectivity test, not a model load.
+
+## About page
+
+Settings links to a separate About page.
+
+The About screen currently shows:
+
+- the current app version
+- whether a newer GitHub release exists
+- the author link
+- the repository link
+
+In packaged app mode, the version check compares the local app version against the latest GitHub release for `mayocream/koharu`.
+
+## Persistence model
+
+The current settings behavior is split across storage layers:
+
+- provider API keys are stored through the system keyring
+- local LLM preset config is persisted in Koharu's frontend preferences store
+- theme and other UI preferences also persist locally
+
+That means clearing frontend preferences is not the same as clearing saved provider API keys.
+
+## Related pages
+
+- [Use OpenAI-Compatible APIs](../how-to/use-openai-compatible-api.md)
+- [Models and Providers](../explanation/models-and-providers.md)
+- [HTTP API Reference](http-api.md)

docs/tutorials/translate-your-first-page.md

@@ -4,13 +4,13 @@ title: Translate Your First Page
 
 # Translate Your First Page
 
-This tutorial covers the normal Koharu workflow for a single manga page: import, detect, recognize, translate, review, and export.
+This tutorial walks through the normal Koharu workflow for a single manga page: import, detect, recognize, translate, review, and export.
 
 ## Before you begin
 
 - Install Koharu from the latest GitHub release
-- Start with a clear manga page image
-- Make sure you have enough local VRAM/RAM for your preferred model, or plan to use a remote provider
+- Start with a clear page image in `.png`, `.jpg`, `.jpeg`, or `.webp`
+- Make sure you have enough local VRAM or RAM for your preferred model, or plan to use a remote provider
 
 If you have not installed Koharu yet, start with [Install Koharu](../how-to/install-koharu.md).
 
@@ -18,23 +18,40 @@ If you have not installed Koharu yet, start with [Install Koharu](../how-to/inst
 
 Open the desktop application normally.
 
-On the first run, Koharu may download required runtime packages and ML models. This is expected.
+On the first run, Koharu may spend time initializing local runtime packages and downloading the default vision stack. This is expected and usually only happens once per machine or runtime update.
 
 ## 2. Import a page
 
-Load your manga page into the app.
+Load your page image into the app.
 
-Koharu keeps your work inside a project, and on Windows it can associate `.khr` project files so you can reopen them by double-clicking.
+At the moment, the documented import flow is image-based rather than project-file based. If you import a folder instead of a single file, Koharu recursively filters it down to supported image files.
+
+For a first pass, use one clean page so it is easy to judge:
+
+- text detection quality
+- OCR quality
+- translation quality
+- final bubble fit
 
 ## 3. Detect text and run OCR
 
 Use Koharu's built-in vision pipeline to:
 
-- detect speech bubbles and text regions
-- segment text areas
-- recognize the original text with OCR
+- detect text-like layout regions
+- build a segmentation mask for cleanup
+- estimate font and color hints
+- recognize the source text with OCR
+
+Under the hood, Koharu does not just run OCR on the full page. It first creates text blocks, crops those regions, and then runs OCR on the cropped areas.
+
+After detection and OCR, review the page before you translate. Look for:
 
-At this point, review the detected blocks and clean up anything obvious before translation.
+- missed bubbles or captions
+- duplicate or badly placed text blocks
+- obvious OCR errors
+- vertical text that should stay vertical
+
+Fixing structural issues before translation usually saves time later.
 
 ## 4. Choose a translation backend
 
@@ -45,28 +62,56 @@ Pick either:
 
 Koharu can use OpenAI, Gemini, Claude, DeepSeek, and OpenAI-compatible endpoints such as LM Studio or OpenRouter.
 
+If you want to wire up LM Studio, OpenRouter, or another OpenAI-style endpoint, follow [Use OpenAI-Compatible APIs](../how-to/use-openai-compatible-api.md).
+
+In practice:
+
+- local models are better when privacy and offline use matter most
+- remote models are easier when your machine is memory-constrained
+- when you use a remote provider, Koharu sends OCR text for translation rather than the whole page image
+
 ## 5. Translate and review
 
 Run translation on the page, then inspect the result carefully.
 
-Koharu helps with text layout and vertical CJK rendering, but you should still review:
+Koharu helps with text layout and vertical CJK rendering, but the final page still benefits from manual review. Focus on:
 
 - names and terminology
-- line breaks
-- font choices
-- bubble fit
+- tone and character voice
+- line breaks and bubble fit
+- font choice and stroke readability
+- blocks whose source OCR looked uncertain
+
+If a translation reads correctly but still looks cramped, adjust the text block or styling before exporting.
 
 ## 6. Export the result
 
-When the page looks right, export it as either:
+When the page looks right, export it in the format that matches your next step:
+
+- rendered image for a flattened final page
+- PSD for editable text and helper layers
+
+Rendered exports are best when the page is finished. PSD export is better when you still want to:
+
+- make small wording edits
+- repaint artifacts
+- hide or inspect helper layers
+- finish the page in Photoshop
+
+## 7. If the first result is not good enough
+
+The usual fixes are:
 
-- a rendered image
-- a layered Photoshop PSD with editable text layers
+- rerun detection after adjusting page selection or replacing bad blocks
+- correct OCR or translation text manually
+- switch to a stronger translation model
+- export PSD and finish the page with manual lettering cleanup
 
-PSD export is useful when you want to do final cleanup in Photoshop without rebuilding the page structure by hand.
+Koharu works best when you treat the pipeline as a fast first pass, then use manual review where the page needs it.
 
 ## Next steps
 
 - Learn export options: [Export Pages and Manage Projects](../how-to/export-and-manage-projects.md)
 - Compare runtime choices: [Acceleration and Runtime](../explanation/acceleration-and-runtime.md)
-- Choose a model: [Models and Providers](../explanation/models-and-providers.md)
+- Understand the model stack: [Technical Deep Dive](../explanation/technical-deep-dive.md)
+- Choose a translation backend: [Models and Providers](../explanation/models-and-providers.md)

zensical.toml

@@ -13,24 +13,32 @@ nav = [
     "tutorials/index.md",
     "tutorials/translate-your-first-page.md",
   ]},
-  {"How-To Guides" = [
-    "how-to/index.md",
-    "how-to/install-koharu.md",
-    "how-to/run-gui-headless-and-mcp.md",
-    "how-to/export-and-manage-projects.md",
-    "how-to/build-from-source.md",
-  ]},
-  {"Explanation" = [
-    "explanation/index.md",
-    "explanation/how-koharu-works.md",
-    "explanation/acceleration-and-runtime.md",
-    "explanation/models-and-providers.md",
-  ]},
-  {"Reference" = [
-    "reference/index.md",
-    "reference/cli.md",
-    "reference/keyboard-shortcuts.md",
-  ]},
+  {"How-To Guides" = [
+    "how-to/index.md",
+    "how-to/install-koharu.md",
+    "how-to/contributing.md",
+    "how-to/run-gui-headless-and-mcp.md",
+    "how-to/configure-mcp-clients.md",
+    "how-to/use-openai-compatible-api.md",
+    "how-to/export-and-manage-projects.md",
+    "how-to/build-from-source.md",
+    "how-to/troubleshooting.md",
+  ]},
+  {"Explanation" = [
+    "explanation/index.md",
+    "explanation/how-koharu-works.md",
+    "explanation/technical-deep-dive.md",
+    "explanation/acceleration-and-runtime.md",
+    "explanation/models-and-providers.md",
+  ]},
+  {"Reference" = [
+    "reference/index.md",
+    "reference/cli.md",
+    "reference/http-api.md",
+    "reference/mcp-tools.md",
+    "reference/settings.md",
+    "reference/keyboard-shortcuts.md",
+  ]},
 ]
 
 [project.extra]