docs: rephrase

README.md

@@ -20,12 +20,12 @@ Under the hood, Koharu uses [candle](https://github.com/huggingface/candle) and
 
 ## Features
 
-- Automatic text block detection, speech bubble detection, and segmentation masks
-- 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
+- Automatic detection of text regions, speech bubbles, and cleanup masks
+- OCR for manga dialogue, captions, and other page text
+- Inpainting to remove source lettering from the page
+- Translation with local or remote LLM backends
+- Vertical CJK layout and text rendering
+- Layered PSD export 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/).
@@ -40,13 +40,13 @@ If you just want to get started, see [Install Koharu](https://koharu.rs/how-to/i
 
 ### 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.
+Koharu can export the current page either as a rendered image or as a layered Photoshop PSD. PSD export keeps helper layers and writes translated text as editable text layers, which makes manual cleanup much easier when the automatic pass gets you 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.
+Koharu includes a built-in MCP server for agent workflows. By default it listens on a random local port, but you can pin it with `--port`.
 
 ```bash
 # macOS / Linux
@@ -61,7 +61,7 @@ For local setup and the available tools, see [Run GUI, Headless, and MCP Modes](
 
 ### Headless Mode
 
-Koharu can also run without the desktop window.
+Koharu can also run without opening the desktop window.
 
 ```bash
 # macOS / Linux
@@ -70,17 +70,17 @@ koharu --port 4000 --headless
 koharu.exe --port 4000 --headless
 ```
 
-You can then open the web UI at `http://localhost:4000`.
+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.
+Koharu supports CUDA, Metal, and Vulkan. CPU fallback is always available when the accelerated path is unavailable or not worth the setup cost 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.
+On Windows, Koharu ships with CUDA support 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.
 
@@ -95,13 +95,13 @@ If you want to confirm GPU support, see [CUDA GPU Compute Capability](https://de
 
 ### 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.
+Koharu supports Metal on Apple Silicon Macs. No extra runtime setup is required beyond a 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.
+Koharu also supports Vulkan on Windows and Linux. This backend is currently used primarily 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.
+Detection and inpainting still depend on CUDA or Metal, so Vulkan is useful 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
 
@@ -118,11 +118,11 @@ For backend selection, fallback behavior, and model runtime support, see [Accele
 
 ## ML Models
 
-Koharu uses a mix of computer vision and language models rather than trying to solve the whole page with one model.
+Koharu uses a staged stack of vision and language models instead of trying to solve the entire page with a single network.
 
 ### Computer Vision Models
 
-Koharu uses several pre-trained models for different parts of the pipeline:
+Koharu uses multiple pretrained models, each tuned for a specific part of the page pipeline:
 
 - [comic-text-bubble-detector](https://huggingface.co/ogkalu/comic-text-and-bubble-detector) for joint text block and speech bubble detection
 - [comic-text-detector](https://huggingface.co/mayocream/comic-text-detector) for text segmentation masks
@@ -137,19 +137,19 @@ Optional built-in alternatives available in **Settings > Engines** include:
 - [Manga OCR](https://huggingface.co/mayocream/manga-ocr) and [MIT 48px OCR](https://huggingface.co/mayocream/mit48px-ocr) as alternative OCR engines
 - [lama-manga](https://huggingface.co/mayocream/lama-manga) as an alternative inpainter
 
-The models are downloaded automatically when you run Koharu for the first time.
+Koharu downloads the required models automatically on first use.
 
-Some models are consumed directly from upstream Hugging Face repos, while Rust-friendly safetensors conversions are hosted on [Hugging Face](https://huggingface.co/mayocream) when Koharu needs a converted bundle.
+Some models are consumed directly from upstream Hugging Face repos, while Rust-friendly `safetensors` conversions are hosted on [Hugging Face](https://huggingface.co/mayocream) when Koharu needs a converted bundle.
 
 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.
+Koharu supports both local and remote LLM backends. When possible, it also tries to preselect sensible defaults based on your system locale.
 
 #### 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:
+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. Suggested models:
 
 For translating to English:
 
@@ -165,7 +165,7 @@ 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.
+LLMs are downloaded on demand when you pick a model in Settings. If you are constrained by memory, start with a smaller model. If you have the VRAM or RAM budget, the 7B and 8B models generally produce better translations.
 
 #### Remote LLMs
 
@@ -177,9 +177,9 @@ Koharu can also translate through remote or self-hosted API providers instead of
 - 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.
+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 are 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.
+Use a remote provider if you do not want to download local models, if you want to reduce local VRAM or RAM use, 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/).
 
@@ -187,7 +187,7 @@ For LM Studio, OpenRouter, and other OpenAI-style endpoints, see [Use OpenAI-Com
 
 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/).
+We provide prebuilt binaries for Windows, macOS, and Linux. For the standard 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
 
@@ -216,13 +216,13 @@ If you want more direct control over the Tauri build:
 bun tauri build --release --no-bundle
 ```
 
-The built binaries will be located in `target/release`.
+The built binaries are written to `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.
+If Koharu is useful in your workflow, consider sponsoring the project.
 
 - [GitHub Sponsors](https://github.com/sponsors/mayocream)
 - [Patreon](https://www.patreon.com/mayocream)

docs/en-US/explanation/acceleration-and-runtime.md

@@ -4,16 +4,16 @@ title: Acceleration and Runtime
 
 # Acceleration and Runtime
 
-Koharu supports multiple runtime paths so it can run well on a wide range of hardware.
+Koharu supports multiple runtime backends so the same pipeline can run across a wide range of hardware.
 
 ## CUDA on NVIDIA GPUs
 
-CUDA is the main GPU acceleration path on systems with supported NVIDIA hardware.
+CUDA is the primary GPU backend on systems with supported NVIDIA hardware.
 
 - Koharu supports NVIDIA GPUs with compute capability 7.5 or higher
 - Koharu bundles CUDA toolkit 13.1
 
-On first run, the required dynamic libraries are extracted to the application data directory.
+On first run, Koharu extracts the required dynamic libraries into the application data directory.
 
 !!! note
 
@@ -21,13 +21,13 @@ On first run, the required dynamic libraries are extracted to the application da
 
 ## Metal on Apple Silicon
 
-On macOS, Koharu supports Metal acceleration for Apple Silicon devices such as M1 and M2 systems.
+On macOS, Koharu supports Metal acceleration on Apple Silicon systems such as the M1 and M2 families.
 
 ## Vulkan on Windows and Linux
 
-Vulkan is supported on Windows and Linux for OCR and LLM inference as an alternative GPU acceleration path when CUDA or Metal are not available.
+On Windows and Linux, Vulkan is available as an alternative GPU path for OCR and LLM inference when CUDA or Metal are not available.
 
-AMD and Intel GPUs can use Vulkan for acceleration, but detection and inpainting models still rely on CUDA or Metal.
+AMD and Intel GPUs can benefit from Vulkan, but detection and inpainting still depend on CUDA or Metal.
 
 ## CPU fallback
 
@@ -43,10 +43,10 @@ koharu.exe --cpu
 
 ## Why fallback matters
 
-Fallback behavior makes Koharu usable on more machines, but it changes the experience:
+Fallback behavior makes Koharu usable on more machines, but it changes the performance profile:
 
 - GPU inference is much faster when supported
 - CPU mode is more compatible but can be substantially slower
 - Smaller local LLMs are often the best choice on CPU-only systems
 
-For exact model choices, see [Models and Providers](models-and-providers.md).
+For model selection guidance, see [Models and Providers](models-and-providers.md).

docs/en-US/explanation/how-koharu-works.md

@@ -4,7 +4,7 @@ title: How Koharu Works
 
 # How Koharu Works
 
-Koharu is built around a page pipeline for manga translation. The user-facing workflow is simple, but the implementation intentionally separates joint detection, segmentation, OCR, inpainting, translation, and rendering into different stages.
+Koharu is built around a staged page pipeline for manga translation. The editor presents that pipeline as a simple workflow, but the implementation keeps detection, segmentation, OCR, inpainting, translation, and rendering separate because each stage produces different data and fails in different ways.
 
 ## The pipeline at a glance
 
@@ -37,7 +37,7 @@ The important implementation detail is that `Detect` is already a multi-model st
 - `comic-text-detector-seg` produces a per-pixel text probability map that becomes the cleanup mask.
 - `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.
+That split lets Koharu use one model to reason about page structure and another to decide which exact pixels should be removed.
 
 ## What each stage produces
 
@@ -51,20 +51,20 @@ That split is why Koharu can use one model to decide where text belongs on the p
 
 ## Why the stages are separate
 
-Manga pages are harder than plain document OCR:
+Manga pages are much harder than ordinary 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 finds text blocks and bubble regions, then runs OCR on cropped regions, then uses a segmentation mask for cleanup, and only then asks an LLM to translate the text.
+Because of that, a single model is usually not enough. Koharu first finds text blocks and bubble regions, then runs OCR on cropped regions, then uses a segmentation mask for cleanup, and only after that asks an LLM to translate the text.
 
 ## The implementation shape
 
-In source terms, the engine registry and pipeline execution live in `koharu-app/src/engine.rs`, while the default engine selection lives in `koharu-app/src/config.rs`.
+In the source tree, the engine registry and pipeline execution live in `koharu-app/src/engine.rs`, while default engine selection lives in `koharu-app/src/config.rs`.
 
-Some implementation details that matter:
+Some implementation details matter:
 
 - the default detect engine is `comic-text-bubble-detector`, which writes `TextBlock` values and bubble regions in one pass
 - `comic-text-detector-seg` runs after text blocks exist and stores the final cleanup mask as `doc.segment`
@@ -89,10 +89,10 @@ By default, Koharu runs:
 - vision models locally
 - local LLMs locally
 
-If you configure a remote LLM provider, Koharu sends only the text selected for translation to that provider.
+If you configure a remote LLM provider, Koharu sends only the OCR 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, AOT inpainting, and background references to official model cards. See [Text Rendering and Vertical CJK Layout](text-rendering-and-vertical-cjk-layout.md) for the renderer internals, vertical writing-mode behavior, and current layout limits.
+See [Technical Deep Dive](technical-deep-dive.md) for model types, segmentation-mask behavior, AOT inpainting, and upstream model references. See [Text Rendering and Vertical CJK Layout](text-rendering-and-vertical-cjk-layout.md) for renderer internals, vertical writing-mode behavior, and current layout limits.
 
 

docs/en-US/explanation/index.md

@@ -4,7 +4,7 @@ title: Explanation
 
 # Explanation
 
-Explanation pages describe how Koharu is put together and why it behaves the way it does.
+These pages describe how Koharu is built and why the runtime behaves the way it does.
 
 ## Topics
 

docs/en-US/explanation/models-and-providers.md

@@ -6,11 +6,11 @@ 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.
+If you want the architecture-level view 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.
+Koharu downloads required vision models automatically the first time you use them.
 
 The current default stack includes:
 
@@ -20,7 +20,7 @@ The current default stack includes:
 - [aot-inpainting](https://huggingface.co/mayocream/aot-inpainting) for default inpainting
 - [YuzuMarker.FontDetection](https://huggingface.co/fffonion/yuzumarker-font-detection) for font and color detection
 
-Some models are used directly from upstream Hugging Face repos, while converted safetensors weights are hosted on [Hugging Face](https://huggingface.co/mayocream) when Koharu needs a Rust-friendly bundle.
+Some models are used directly from upstream Hugging Face repos, while converted `safetensors` weights are hosted on [Hugging Face](https://huggingface.co/mayocream) when Koharu needs a Rust-friendly bundle.
 
 ### What each vision model is
 
@@ -32,7 +32,7 @@ Some models are used directly from upstream Hugging Face repos, while converted
 | `aot-inpainting` | inpainting network | reconstructs masked image regions 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. Detection, segmentation, OCR, and inpainting all need different output shapes:
+The important design choice is that Koharu does not use one model for every page task. Detection, segmentation, OCR, and inpainting all need different output shapes:
 
 - joint detection wants text blocks and bubble regions
 - segmentation wants per-pixel masks
@@ -52,7 +52,7 @@ You can swap individual stages in **Settings > Engines**. Built-in alternatives
 
 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.
+In practice, the local models are usually quantized decoder-only transformers. GGUF is the model format; `llama.cpp` is the inference runtime.
 
 ### Suggested local models for English output
 
@@ -70,7 +70,7 @@ In practice, the local models are usually quantized decoder-only transformers. G
 
 ## Remote providers
 
-Koharu can translate through remote or self-hosted APIs instead of downloading a local model.
+Koharu can also translate through remote or self-hosted APIs instead of downloading a local model.
 
 Supported providers include:
 
@@ -104,7 +104,7 @@ Use remote providers when you want:
 
 ## Background reading
 
-For theory and diagrams behind the model categories on this page, see:
+For background theory 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)

docs/en-US/explanation/technical-deep-dive.md

@@ -4,7 +4,7 @@ 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 text and bubble detection, segmentation masks, OCR, inpainting, and translation are handled separately.
+This page covers the technical structure of Koharu's manga pipeline: what each model does, how the stages fit together, and why text and bubble detection, segmentation masks, OCR, inpainting, and translation are handled separately.
 
 ## The page pipeline in implementation terms
 
@@ -26,13 +26,13 @@ flowchart TD
     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:
+At the code level, the public pipeline is `Detect -> OCR -> Inpaint -> LLM Generate -> Render`, but the detect stage is already doing three distinct jobs:
 
 - text and bubble detection
 - text foreground segmentation
 - font and color estimation
 
-That design is deliberate. A manga translation tool needs both page structure and pixel precision.
+That design is deliberate. A manga translation tool needs both page structure and pixel-level precision.
 
 ## Model types at a glance
 
@@ -45,7 +45,7 @@ That design is deliberate. A manga translation tool needs both page structure an
 | 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 |
 
-Optional built-in alternatives remain available. The main ones are [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors) as an alternative detector and layout-analysis engine, [speech-bubble-segmentation](https://huggingface.co/mayocream/speech-bubble-segmentation) as a dedicated bubble detector, and [lama-manga](https://huggingface.co/mayocream/lama-manga) as an alternative inpainter.
+Optional built-in alternatives are still available. The main ones are [PP-DocLayoutV3](https://huggingface.co/PaddlePaddle/PP-DocLayoutV3_safetensors) as an alternative detector and layout-analysis engine, [speech-bubble-segmentation](https://huggingface.co/mayocream/speech-bubble-segmentation) as a dedicated bubble detector, and [lama-manga](https://huggingface.co/mayocream/lama-manga) as an alternative inpainter.
 
 ## Why text and bubble detection matters on manga pages
 
@@ -57,14 +57,14 @@ Detection is not just "find boxes around text". On manga pages it has to answer
 - which boxes should be deduplicated before OCR
 - which regions should become editable `TextBlock` records
 
-This matters because manga is visually dense:
+This matters because manga pages are 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 the detector output to create `TextBlock` records first, then uses those blocks to drive OCR and later rendering. Bubble regions are kept as separate geometry so the UI and later tooling can still reason about the speech-balloon area.
+Koharu first converts detector output into `TextBlock` records, then uses those blocks to drive OCR and later rendering. Bubble regions are kept as separate geometry so the UI and downstream tooling can still reason about the speech-balloon area.
 
 In the current implementation, the default detect stage:
 
@@ -73,11 +73,11 @@ In the current implementation, the default detect stage:
 - converts bubble detections into `BubbleRegion` values
 - sorts text blocks into manga reading order before OCR
 
-If you prefer a document-layout-style detector, `PP-DocLayoutV3` is still available as an alternative engine. It is just no longer the default.
+If you prefer a document-layout-style detector, `PP-DocLayoutV3` is still available as an alternative engine. It is simply no longer the default.
 
 ## 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".
+A segmentation mask is an image-sized map in which each pixel indicates whether it belongs to a target class. In Koharu's case, that class is effectively "text foreground that should later be removed during cleanup".
 
 This is different from a bounding box:
 
@@ -102,22 +102,22 @@ In Koharu, the segmentation path is intentionally separate from layout:
 - the resulting binary mask becomes `doc.segment`
 - `aot-inpainting` then uses `doc.segment` as the erase and fill mask for inpainting
 
-The cleanup step still matters because raw segmentation probabilities are usually soft and noisy. Koharu thresholds the prediction and dilates the final binary mask so the cleanup covers text edges and outlines instead of leaving halos behind.
+The cleanup step still matters because raw segmentation probabilities are usually soft and noisy. Koharu thresholds the prediction and dilates the final binary mask so cleanup covers text edges and outlines instead of leaving halos behind.
 
 ## How the vision models work in theory
 
 ### Joint detection: text blocks and bubble regions in one pass
 
-[ogkalu/comic-text-and-bubble-detector](https://huggingface.co/ogkalu/comic-text-and-bubble-detector) is the default detector because it directly predicts the two region types the rest of the pipeline cares about most:
+[ogkalu/comic-text-and-bubble-detector](https://huggingface.co/ogkalu/comic-text-and-bubble-detector) is the default detector because it predicts the two region types the rest of the pipeline cares about most:
 
 - text-like regions that should become `TextBlock`s
 - speech-bubble regions that should stay available to the editor and downstream tooling
 
-Koharu's Candle port maps those detections into document data structures and then sorts the text blocks into manga reading order before OCR. Conceptually, this is closer to page object detection than to OCR itself.
+Koharu's Candle port maps those detections into document data structures and then sorts the text blocks into manga reading order before OCR. Conceptually, this is closer to page-level object detection 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:
+Koharu's `comic-text-detector` path is segmentation-first. The Rust port loads:
 
 - a YOLOv5-style backbone
 - a U-Net decoder for mask prediction
@@ -128,16 +128,16 @@ The default page pipeline uses the segmentation-only path because Koharu already
 - one model that is good at page-level region detection
 - one model that is good at pixel-level text foreground
 
-This is a better fit for cleanup than relying on boxes alone.
+That is a much 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:
+[PaddleOCR-VL](https://huggingface.co/docs/transformers/en/model_doc/paddleocr_vl) is a compact vision-language model. The published architecture 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:
+In Koharu, OCR is treated as a multimodal sequence-generation problem:
 
 1. the image crop is encoded into visual tokens
 2. a text prompt such as `OCR:` conditions the task
@@ -150,13 +150,13 @@ Koharu's implementation follows that pattern closely:
 - 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.
+So OCR in Koharu is not a classic CTC-only recognizer. It is a compact document-oriented VLM used for a tightly scoped OCR task.
 
 ### Inpainting: why the default is now AOT
 
 The default inpainter is the AOT model from [manga-image-translator](https://github.com/zyddnys/manga-image-translator), exposed in Koharu as `aot-inpainting`. It is a masked-image inpainting network built around gated convolutions and repeated context-mixing blocks with multiple dilation rates.
 
-The important intuition is:
+The practical intuition is:
 
 - text removal needs more than a rectangular crop fill
 - the model needs both local edge detail and wider context from the bubble or background
@@ -181,7 +181,7 @@ The theory is standard modern LLM inference:
 - 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:
+The practical trade-off is also familiar:
 
 - larger models usually translate better
 - smaller quantized models use less VRAM and RAM
@@ -191,7 +191,7 @@ Koharu keeps the image understanding steps local even when you choose a remote t
 
 ## Koharu-specific implementation notes
 
-Some details that are easy to miss if you only read the high-level docs:
+Some details are easy to miss if you only read the high-level docs:
 
 - the default detect stage is `comic-text-bubble-detector`, not `PP-DocLayoutV3`
 - `comic-text-detector-seg` still loads the segmentation-only `comic-text-detector` path for `doc.segment`
@@ -218,7 +218,7 @@ Some details that are easy to miss if you only read the high-level docs:
 
 ### Background theory and Wikipedia diagrams
 
-These pages are useful when you want the general theory and the overview diagrams before diving into model cards:
+These pages are useful if you want the general theory and 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)
@@ -227,4 +227,4 @@ These pages are useful when you want the general theory and the overview diagram
 - [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.
+Those Wikipedia links are background references. For Koharu-specific behavior and actual model choices, prefer the official model cards and the source tree.

docs/en-US/explanation/text-rendering-and-vertical-cjk-layout.md

@@ -5,11 +5,11 @@ description: How Koharu's text renderer works, why text rendering is difficult,
 
 # Text Rendering and Vertical CJK Layout
 
-Text rendering is one of the hardest parts of a manga translator. Detection, OCR, and inpainting decide what should happen to the page, but the renderer decides whether the result still looks like a manga page instead of a debug overlay.
+Text rendering is one of the hardest parts of a manga translator. Detection, OCR, and inpainting decide what should happen to the page, but the renderer decides whether the result still reads like a finished manga page instead of a debug overlay.
 
-A good outside reference here is Aria Desires's [Text Rendering Hates You](https://faultlore.com/blah/text-hates-you/). Its main point applies directly to Koharu: text rendering is not a clean linear problem, and there is no universally perfect answer. Layout, shaping, font fallback, rasterization, and composition all push on each other.
+A useful outside reference is Aria Desires's [Text Rendering Hates You](https://faultlore.com/blah/text-hates-you/). The core point applies directly to Koharu: text rendering is not a clean linear problem, and there is no universally correct answer. Layout, shaping, font fallback, rasterization, and composition all affect one another.
 
-Koharu does not try to be a full desktop publishing engine. It tries to be very good at the specific kinds of text layout manga pages need most, especially vertical CJK bubble text.
+Koharu does not try to be a full desktop publishing engine. It aims to be very good at the text layout patterns manga pages need most, especially vertical CJK bubble text.
 
 ## Why this problem is hard
 
@@ -23,7 +23,7 @@ flowchart LR
     D --> E[Composition]
 ```
 
-That picture is useful, but in practice the stages do not stay independent:
+That breakdown is useful, but in practice the stages do not stay independent:
 
 - you cannot know the final line breaks until you know shaped advances
 - you cannot shape reliably without knowing the writing direction and OpenType features
@@ -31,7 +31,7 @@ That picture is useful, but in practice the stages do not stay independent:
 - you cannot just draw code points one by one because real text is shaped into glyph runs
 - you cannot assume that a bubble's box is the same thing as the renderer's true ink bounds
 
-Vertical manga text makes this harder again:
+Vertical manga text makes the problem harder again:
 
 - columns flow top-to-bottom, but the columns themselves flow right-to-left
 - punctuation often needs vertical alternates or recentering
@@ -40,7 +40,7 @@ Vertical manga text makes this harder again:
 
 ## What Koharu actually does
 
-At the implementation level, the renderer lives in the `koharu-renderer` crate and the main orchestration happens in `koharu-app/src/renderer.rs`, `src/layout.rs`, `src/shape.rs`, `src/segment.rs`, and `src/renderer.rs`.
+At the implementation level, the renderer lives in the `koharu-renderer` crate, and the main orchestration happens in `koharu-app/src/renderer.rs`, `src/layout.rs`, `src/shape.rs`, `src/segment.rs`, and `src/renderer.rs`.
 
 The pipeline for one translated `TextBlock` is roughly:
 
@@ -72,14 +72,14 @@ Koharu does not blindly force all CJK text into vertical mode. The current heuri
 - if the translation contains CJK text and the block is taller than it is wide, use `VerticalRl`
 - otherwise, keep the block horizontal
 
-That means vertical layout is tied to both:
+That means vertical layout depends on both:
 
 - script detection
 - the geometry of the detected or user-adjusted text box
 
 This is simple on purpose. It matches a large share of manga bubble text, and it avoids turning every mixed-script caption into vertical text just because it contains one Japanese character.
 
-It is also a heuristic, not a universal writing-mode engine. That matters for edge cases and is one of the current limits of the renderer.
+It is still a heuristic, not a general writing-mode engine. That matters for edge cases and is one of the current limits of the renderer.
 
 ## How vertical CJK is implemented
 
@@ -96,7 +96,7 @@ When Koharu shapes vertical text, it enables the OpenType features:
 - `vert`
 - `vrt2`
 
-These are the standard vertical alternates used by fonts that actually support vertical writing. This is one of the biggest reasons the renderer can produce convincing vertical CJK layout instead of looking like rotated horizontal text.
+These are the standard vertical alternates exposed by fonts that actually support vertical writing. This is one of the main reasons the renderer can produce convincing vertical CJK layout instead of looking like rotated horizontal text.
 
 If the font has proper vertical glyph substitutions, Koharu can use them. If the font does not, the result degrades to whatever the font provides.
 
@@ -127,7 +127,7 @@ This covers cases such as:
 - brackets and corner marks
 - middle dots and similar marks
 
-This is not a cosmetic extra. It is one of the reasons the current vertical path looks much more deliberate than a generic text renderer.
+This is not cosmetic. It is one of the reasons the current vertical path looks more intentional than a generic text renderer.
 
 ### 5. Emphasis punctuation is normalized
 
@@ -145,7 +145,7 @@ This is important because:
 - vertical punctuation and alternate glyph forms can have surprising extents
 - outline and bitmap glyphs need to land in the same final surface reliably
 
-In practice, this bounds pass is one of the pieces that makes the renderer feel stable instead of constantly shaving off the top, bottom, or right edge of the text.
+In practice, this bounds pass is one of the reasons the renderer feels stable instead of constantly clipping the top, bottom, or right edge of the text.
 
 ## Why the output is good on manga bubbles
 
@@ -163,7 +163,7 @@ That combination is why the renderer can produce vertical CJK text that looks in
 
 ## How perfect is it?
 
-It is strong for the common manga cases. It is not a perfect Japanese typesetting engine.
+It is strong for common manga cases. It is not a full Japanese typesetting engine.
 
 That distinction matters.
 
@@ -176,7 +176,7 @@ Koharu is best understood as:
 
 ## Current limits
 
-The codebase is fairly honest about where the renderer is still incomplete.
+The codebase is fairly clear about where the renderer is still incomplete.
 
 ### Writing mode is heuristic
 
@@ -222,12 +222,12 @@ Koharu instead pushes vertical handling back into the shaping and layout stages.
 
 ## External reference worth reading
 
-[Text Rendering Hates You](https://faultlore.com/blah/text-hates-you/) is useful because it explains the renderer problem in a language-agnostic way. The specific stack in Koharu is different from a browser engine, but the same core lessons show up here:
+[Text Rendering Hates You](https://faultlore.com/blah/text-hates-you/) is useful because it explains the renderer problem in a language-agnostic way. Koharu's stack is different from a browser engine, but the same core lessons show up here:
 
 - shaping is not optional
 - fallback fonts are unavoidable
 - layout and shaping depend on each other
 - "perfect" text rendering is mostly a story people tell before they implement it
 
-If you want the short version: Koharu's renderer is careful precisely because text rendering really does hate you.
+If you want the short version: Koharu's renderer is careful because text rendering is a coupled systems problem, not a final paint step.
 

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

@@ -4,7 +4,7 @@ title: Build From Source
 
 # Build From Source
 
-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.
+If you want to compile Koharu locally instead of using a prebuilt release, start with the repository's Bun wrapper. It matches the project's build flow and handles platform-specific setup that a direct Tauri invocation does not.
 
 ## What the build includes
 
@@ -46,7 +46,7 @@ bun install
 bun run build
 ```
 
-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.
+This is the standard source-build path for most users. It runs the repository's Bun helper and then launches Tauri with the build flow the project expects.
 
 On Windows, that wrapper also tries to discover `nvcc` and `cl.exe` automatically before starting the build.
 
@@ -57,7 +57,7 @@ The main binaries are written to `target/release`:
 
 ## Development build
 
-If you are actively working on the app instead of producing a release-style binary, use:
+If you are actively working on the app rather than producing a release-style binary, use:
 
 ```bash
 bun run dev
@@ -79,7 +79,7 @@ Unlike `bun run build`, this path does not go through the repository's Windows h
 
 ## 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.
+If you only want to build the Rust crate directly and intentionally bypass the Bun and Tauri wrapper, use `bun cargo` rather than invoking `cargo` yourself.
 
 Examples:
 
@@ -91,7 +91,7 @@ bun cargo build --release -p koharu --features=cuda
 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.
+This is useful for lower-level Rust work, but `bun run build` remains the better choice for a normal desktop build because it preserves the full Tauri packaging flow.
 
 ## What happens at runtime after the build
 

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

@@ -4,7 +4,7 @@ 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.
+Koharu exposes a built-in MCP server over local Streamable HTTP. This page shows how to connect MCP clients to it, with concrete setup for Antigravity, Claude Desktop, and Claude Code.
 
 ## What Koharu exposes over MCP
 
@@ -16,7 +16,7 @@ Koharu's MCP server is the same local runtime used by the desktop app and headle
 - 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.
+That means an MCP client can drive the same manga workflow as Koharu's GUI.
 
 ## 1. Start Koharu on a stable port
 
@@ -108,7 +108,7 @@ If that works, move on to page actions such as:
 
 ## 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`.
+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 approach 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.
 
@@ -188,7 +188,7 @@ Then move to actual page work:
 
 ## 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.
+If by "Claude" you mean Claude Code, the safest setup for Koharu's local `http://127.0.0.1` MCP endpoint is to use the same stdio bridge pattern.
 
 ### Add it to your user config
 

docs/en-US/how-to/contributing.md

@@ -4,9 +4,9 @@ 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.
+Koharu accepts contributions across 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.
+This guide focuses on the repository workflow that matches CI and keeps changes easy to review.
 
 ## Before you start
 
@@ -40,7 +40,7 @@ If you are not sure where a change belongs:
 
 ## Set up the repository
 
-Install JS dependencies first:
+Install JavaScript dependencies first:
 
 ```bash
 bun install
@@ -58,7 +58,7 @@ For active development, use:
 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.
+The dev command runs the Tauri app in development mode and keeps the local server on a fixed port for UI work and e2e tests.
 
 ## Use the repo's preferred local commands
 
@@ -113,7 +113,7 @@ If you changed docs:
 - `zensical build -f docs/zensical.ja-JP.toml`
 - `zensical build -f docs/zensical.zh-CN.toml`
 
-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.
+You do not need to run every command in this list for every PR, but you should cover the code paths you touched.
 
 ## E2E tests
 

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

@@ -4,7 +4,7 @@ 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.
+Koharu's workflow is page-based. You import one or more page images, run the pipeline, review text blocks, and then export either flattened output or a layered handoff file for manual finishing.
 
 ## Supported page inputs
 
@@ -50,7 +50,7 @@ When exported, Koharu uses an `_inpainted` filename suffix.
 
 Koharu can also export a layered Photoshop PSD.
 
-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.
+PSD export is the handoff format for users who want to keep working in Photoshop or a PSD-compatible editor after the ML pipeline has done its first pass.
 
 In the current implementation, PSD export uses editable text layers by default and can include:
 
@@ -99,7 +99,7 @@ This is the main way to manage a chapter or batch job inside the app today.
 
 ## Recommended workflow
 
-If you care about polish, a good pattern is:
+If you care about polish, a practical pattern is:
 
 1. run detection, OCR, translation, and render in Koharu
 2. export a rendered image for quick review

docs/en-US/how-to/index.md

@@ -4,7 +4,7 @@ title: How-To Guides
 
 # How-To Guides
 
-How-to guides focus on specific jobs you may want to complete with Koharu.
+How-to guides focus on concrete tasks you may want to complete with Koharu.
 
 ## Common tasks
 
@@ -14,5 +14,5 @@ How-to guides focus on specific jobs you may want to complete with Koharu.
 - [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
+- [Build From Source](build-from-source.md): local build flow with Bun, Tauri, and platform features
 - [Troubleshooting](troubleshooting.md): common startup, download, GPU, pipeline, and connectivity failures

docs/en-US/how-to/install-koharu.md

@@ -18,7 +18,7 @@ If your platform is not covered by a release build, use [Build From Source](buil
 
 ## 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:
+Koharu is a local-first application. In practice, the desktop binary is only part of the install 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
@@ -34,7 +34,7 @@ On first run, Koharu may:
 - 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.
+This is normal and can take a while 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.
 
@@ -53,7 +53,7 @@ Some practical details matter:
 - 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.
+On CUDA-capable systems, Koharu bundles and initializes the runtime pieces it needs instead of requiring you to configure every library path manually.
 
 !!! note
 

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

@@ -28,7 +28,7 @@ That is why desktop editing, headless automation, and MCP tooling stay aligned.
 
 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.
+Even in desktop mode, Koharu still starts a local HTTP server internally. The embedded window talks to that local server instead of calling the pipeline directly.
 
 This is the default mode and is the best choice for most users.
 
@@ -72,13 +72,13 @@ When Koharu is running on a fixed port, the main endpoints are:
 
 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.
+Because Koharu binds to loopback, these endpoints are local by default. If you want 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 using the same loaded documents, models, and page pipeline as the rest of the app.
+Koharu includes a built-in MCP server that uses the same loaded documents, models, and page pipeline as the rest of the app.
 
 Point your MCP client or agent at:
 
@@ -144,7 +144,7 @@ On Windows, debug and headless runs also influence how Koharu attaches to or cre
 
 ## Running without keyring
 
-By default Koharu stores API keys in the system keyring. In container or CI environments where there is no persistent keyring, you can pass `--no-keyring` to skip it and supply API keys through environment variables instead.
+By default, Koharu stores API keys in the system keyring. In container or CI environments where there is no persistent keyring, you can pass `--no-keyring` to skip it and supply API keys through environment variables instead.
 
 The variable name for each provider follows the pattern `KOHARU_<PROVIDER>_API_KEY`:
 

docs/en-US/how-to/troubleshooting.md

@@ -4,7 +4,7 @@ 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.
+This page covers the most common Koharu problems in the current implementation: first-run downloads, runtime initialization, GPU fallback, headless and MCP access, pipeline-stage ordering, and source-build setup.
 
 ## Before you start
 
@@ -47,7 +47,7 @@ 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.
+If `--cpu` works and the normal launch does not, the problem is usually in the GPU path rather than general app startup.
 
 ## Model or runtime downloads fail
 
@@ -70,7 +70,7 @@ What to check:
 - 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.
+If downloads keep failing, test on a different network first. That is the fastest way to separate a machine-local problem from an upstream reachability issue.
 
 ## Koharu falls back to CPU even though you have an NVIDIA GPU
 
@@ -93,7 +93,7 @@ If the driver is old or the CUDA check fails, Koharu deliberately prefers CPU ov
 
 ## OCR, inpainting, or export says something is missing
 
-Some errors are just pipeline ordering problems.
+Some errors are simply pipeline ordering problems.
 
 Common examples from the current API and MCP layer:
 
@@ -131,7 +131,7 @@ Try this:
 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.
+If the structure is wrong, translation quality usually gets worse downstream because OCR and rendering both depend on block geometry.
 
 ## Headless mode starts, but you cannot open the Web UI
 

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

@@ -6,7 +6,7 @@ title: 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.
+This page covers Koharu's current OpenAI-compatible integration. It is separate from Koharu's built-in OpenAI, Gemini, Claude, and DeepSeek provider presets.
 
 ## What Koharu expects from a compatible endpoint
 
@@ -25,7 +25,7 @@ Some implementation details matter:
 - 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."
+So "OpenAI-compatible" here means OpenAI API-compatible, not just "works with OpenAI-adjacent tooling."
 
 ## Where to configure it in Koharu
 
@@ -113,7 +113,7 @@ If the server only implements `Responses` or some custom schema, Koharu's curren
 
 ## 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.
+Koharu does not treat these endpoints as one generic remote bucket. Each configured preset becomes its own LLM entry source.
 
 For example:
 

docs/en-US/index.md

@@ -469,19 +469,19 @@ hide:
     <div class="kh-shell">
       <div class="kh-announce-wrap">
         <div class="kh-announce">
-          <span>Introducing:</span>
-          <span class="kh-announce__token">llama.cpp-based model inference</span>
+          <span>Now available:</span>
+          <span class="kh-announce__token">llama.cpp local inference</span>
           <span class="kh-announce__copy">
-            Runs GGUF models locally with CUDA, Vulkan, or Metal acceleration.
+            Run GGUF models locally with CUDA, Vulkan, or Metal acceleration.
           </span>
         </div>
       </div>
 
       <div class="kh-hero__copy">
-        <h1>Translate manga locally, privately, seamlessly.</h1>
+        <h1>Translate manga locally, privately, and with a real production pipeline.</h1>
         <p class="kh-hero__lede">
-          Koharu is a SOTA manga translation desktop app in Rust for OCR, cleanup,
-          translation, review, and export on Windows, macOS, and Linux.
+          Koharu is a Rust desktop application for manga translation. It handles OCR,
+          cleanup, translation, review, and export on Windows, macOS, and Linux.
         </p>
         <div class="kh-hero__model-row">
           <div class="kh-hero__model-label">Local models include</div>
@@ -497,7 +497,7 @@ hide:
             Download for Windows&nbsp;&nbsp;<span class="kh-download-button__version">0.42.1</span>
           </a>
           <div class="kh-download-hero__subtext">
-            Koharu is free and open source.
+            Free and open source.
           </div>
         </div>
       </div>
@@ -516,12 +516,11 @@ hide:
     <div class="kh-shell">
       <div class="kh-section__header">
         <div class="kh-kicker">No-GUI Deployment</div>
-        <h2>Run Koharu without the desktop window when you want a local Web UI or scripted page pipelines.</h2>
+        <h2>Run Koharu without the desktop window when you need a local Web UI or a scriptable translation runtime.</h2>
         <p>
-          The desktop app is the main experience, but the same runtime can also run
-          headless. Use it for browser-based access on another machine, repeatable batch
-          translation, or local automation that still depends on Koharu's page-aware
-          pipeline.
+          The desktop app is the primary interface, but the same runtime can also run
+          headless. Use it for browser-based access, repeatable batch work, or local
+          automation that still depends on Koharu's page-aware pipeline.
         </p>
       </div>
 
@@ -529,8 +528,8 @@ hide:
         <div class="kh-command-card">
           <div class="kh-command-card__title">Headless mode</div>
           <div class="kh-command-card__copy">
-            Start Koharu without the desktop window and keep the same translation runtime
-            available through a browser session on a fixed local port.
+            Start Koharu without the desktop window and keep the same translation
+            runtime available through a browser session on a fixed local port.
           </div>
           <pre><code># macOS / Linux
 koharu --port 4000 --headless
@@ -541,8 +540,8 @@ koharu.exe --port 4000 --headless</code></pre>
         <div class="kh-command-card">
           <div class="kh-command-card__title">What headless is for</div>
           <div class="kh-command-card__copy">
-            Use it when you need the existing desktop workflow in a form that is easier
-            to script, schedule, or expose to other local tools.
+            Use it when you need the desktop workflow in a form that is easier to
+            script, schedule, or expose to other local tools.
           </div>
           <div class="kh-chip-list">
             <span class="kh-chip">Local Web UI</span>
@@ -559,11 +558,11 @@ koharu.exe --port 4000 --headless</code></pre>
     <div class="kh-shell">
       <div class="kh-section__header">
         <div class="kh-kicker">MCP Integration</div>
-        <h2>Let agents drive Koharu while the models and page data stay local.</h2>
+        <h2>Let agents drive Koharu while models and page data stay on the local machine.</h2>
         <p>
-          Koharu includes MCP support so desktop editing, headless mode, and agent
-          workflows can all talk to the same local translation runtime instead of
-          splitting work across different stacks.
+          Koharu includes MCP support so the desktop UI, headless mode, and agent
+          workflows all talk to the same local translation runtime instead of drifting
+          into separate stacks.
         </p>
       </div>
 
@@ -571,9 +570,8 @@ koharu.exe --port 4000 --headless</code></pre>
         <div class="kh-mcp-card">
           <h3>One runtime, multiple entry points</h3>
           <p>
-            The same page pipeline can power the desktop UI, the headless Web UI, and
-            MCP tools, so automation does not drift away from the way Koharu behaves in
-            normal editing sessions.
+            The same page pipeline powers the desktop UI, the headless Web UI, and MCP
+            tools, so automation stays aligned with normal editing sessions.
           </p>
         </div>
         <div class="kh-mcp-card">
@@ -592,11 +590,11 @@ koharu.exe --port 4000 --headless</code></pre>
       <div class="kh-dev__lead">
         <img src="assets/Koharu_Halo.png" alt="Koharu" />
         <div class="kh-kicker">Developer Friendly</div>
-        <h2>Build locally and integrate the same desktop runtime into your own tooling.</h2>
+        <h2>Build from source and reuse the same runtime in your own tooling.</h2>
         <p>
-          Koharu is practical to work on and practical to embed: build from source with
-          Bun and Rust, use stable runtime flags, and reuse headless mode or MCP when you
-          need local automation around the app.
+          Koharu is designed to be practical to build and practical to integrate. Use
+          Bun and Rust for local builds, stable runtime flags for deployment, and
+          headless mode or MCP when you need automation around the app.
         </p>
       </div>
 
@@ -605,8 +603,8 @@ koharu.exe --port 4000 --headless</code></pre>
           <div class="kh-resource-card">
             <div class="kh-resource-card__eyebrow">Build</div>
             <div class="kh-resource-card__copy">
-              Build the desktop app from source with the same Bun and Rust toolchain used
-              by the project.
+              Build the desktop app from source with the same Bun and Rust toolchain
+              used by the project.
             </div>
             <pre><code>bun install
 bun run build</code></pre>
@@ -614,8 +612,8 @@ bun run build</code></pre>
           <div class="kh-resource-card">
             <div class="kh-resource-card__eyebrow">Runtime flags</div>
             <div class="kh-resource-card__copy">
-              The desktop binary exposes a small set of useful flags for local deployment
-              and automation without introducing a separate backend service.
+              The desktop binary exposes a small set of runtime flags for local
+              deployment and automation without introducing a separate backend service.
             </div>
             <div class="kh-chip-list">
               <span class="kh-chip">--headless</span>

docs/en-US/reference/cli.md

@@ -4,7 +4,7 @@ title: CLI Reference
 
 # CLI Reference
 
-This page covers the command-line options exposed by Koharu's desktop binary.
+This page documents the command-line options exposed by Koharu's desktop binary.
 
 Koharu uses the same binary for:
 
@@ -36,7 +36,7 @@ koharu.exe [OPTIONS]
 
 ## Behavior notes
 
-Some flags change more than just startup appearance:
+Some flags affect more than 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
@@ -88,8 +88,8 @@ Start with explicit debug logging:
 koharu --debug
 ```
 
-Use without keyring
+Use without keyring:
 
 ```bash
 KOHARU_OPENAI_API_KEY=[key] koharu --no-keyring
-```
+```

docs/en-US/reference/http-api.md

@@ -10,11 +10,11 @@ Koharu exposes a local HTTP API under:
 http://127.0.0.1:<PORT>/api/v1
 ```
 
-This is the same API used by the desktop UI and headless Web UI.
+This is the same API used by the desktop UI and the headless Web UI.
 
 ## Runtime model
 
-Important behavior from the current implementation:
+Important current behavior:
 
 - the API is served by the same process as the GUI or headless runtime
 - the server binds to `127.0.0.1` by default
@@ -23,7 +23,7 @@ Important behavior from the current implementation:
 
 ## Common response shapes
 
-Frequently used types include:
+Frequently used response types include:
 
 - `MetaInfo`: app version and ML device
 - `DocumentSummary`: document id, name, size, revision, layer availability, and text-block count

docs/en-US/reference/index.md

@@ -4,7 +4,7 @@ title: Reference
 
 # Reference
 
-Reference pages collect factual details you may want to look up quickly.
+Reference pages collect factual details you may want to look up quickly while working with Koharu.
 
 ## Available references
 

docs/en-US/reference/keyboard-shortcuts.md

@@ -4,7 +4,7 @@ title: Keyboard Shortcuts
 
 # Keyboard Shortcuts
 
-These are the default controls documented for the editor.
+These are the default editor controls currently documented in the app.
 
 | Shortcut | Action |
 | --- | --- |

docs/en-US/reference/mcp-tools.md

@@ -73,7 +73,7 @@ Valid `view_text_block` layers:
 | `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 `document_id`, `llm_target`, `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.
+`process` is the coarse-grained convenience tool. If you need finer control or easier debugging, use the stage tools separately.
 
 ## LLM tools
 

docs/en-US/reference/settings.md

@@ -14,7 +14,7 @@ Theme options:
 - `Dark`
 - `System`
 
-The app uses the selected theme immediately through the frontend theme provider.
+The app applies the selected theme immediately through the frontend theme provider.
 
 ## Language
 

docs/en-US/tutorials/index.md

@@ -4,7 +4,7 @@ title: Tutorials
 
 # Tutorials
 
-Tutorials walk through complete tasks from start to finish.
+Tutorials walk through complete tasks from start to finish, using the same workflow you would follow in the app.
 
 ## Available tutorials
 

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

@@ -4,7 +4,7 @@ title: Translate Your First Page
 
 # Translate Your First Page
 
-This tutorial walks through the normal Koharu workflow for a single manga page: import, detect, recognize, translate, review, and export.
+This tutorial walks through the standard Koharu workflow for a single manga page: import, detect, recognize, translate, review, and export.
 
 ## Before you begin
 
@@ -107,7 +107,7 @@ The usual fixes are:
 - switch to a stronger translation model
 - export PSD and finish the page with manual lettering cleanup
 
-Koharu works best when you treat the pipeline as a fast first pass, then use manual review where the page needs it.
+Koharu works best when you treat the pipeline as a fast first pass and then apply manual review where the page needs it.
 
 ## Next steps